feat(editor): browse and install npm packages from the Dependencies panel

.env.example

@@ -23,6 +23,11 @@ PORT=3001
 #
 # DATABASE_URL=sqlite:./.tmp/dev.db
 
+# ─── npm registry ────────────────────────────────────────────────────────────
+# Registry the Dependencies panel, the dependency resolver and runtime installs
+# use. Leave unset for the public registry.
+# NPM_REGISTRY_URL=https://registry.npmjs.org
+
 # ─── Filesystem paths ────────────────────────────────────────────────────────
 UPLOADS_DIR=./uploads
 STATIC_DIR=./dist

CLAUDE.md

@@ -273,6 +273,8 @@ Deep imports into these engine modules are enforced by `src/__tests__/architectu
 - `@core/framework` — the framework engine (color, typography, spacing CSS generation)
 - `@core/framework-schema` — pure leaf: TypeBox schemas + derived types for persisted framework token settings; no dependency on the engine or page-tree
 - `@core/fonts`
+- `@core/collab`
+- `@core/registry` — TypeBox shapes for the npm registry proxy plus the ESM-entry preflight shared by the importmap builder and the Dependencies panel
 
 Note: `@core/framework-schema` is a dependency of both `@core/page-tree` (for `FrameworkSettingsSchema` and `GeneratedClassMetadataSchema`) and `@core/framework` (for the persisted data shapes). This arrangement keeps the module graph one-directional — the engine depends on the schema leaf, not on the page tree. Any other module barrel is still a convention without a gate; treat deep imports in those as drift and migrate them to the barrel as part of whatever change you're making.
 

docs/README.md

@@ -27,6 +27,7 @@ docs/
 │   ├── content-workspace.md        ← Content workspace: collections, entries, body editor
 │   ├── auth-and-access.md          ← sessions, MFA, capabilities, roles
 │   ├── site-shell.md               ← site config (breakpoints, classes, files, deps)
+│   ├── dependencies.md             ← Dependencies panel: registry proxy, install/remove, lock
 │   ├── modules.md                  ← module engine + first-party blocks
 │   ├── data-workspace.md           ← Data workspace: table schema + field management UI
 │   ├── dashboard.md                ← Dashboard workspace + widget registry
@@ -145,6 +146,7 @@ Three categories, three voices:
 | [features/auth-and-access.md](features/auth-and-access.md)       | Sessions, MFA, step-up, lockout, CSRF, capabilities                  |
 | [features/site-shell.md](features/site-shell.md)                 | The persisted site config (breakpoints, classes, files, deps)        |
 | [features/branches.md](features/branches.md)                     | Site branches: fork, edit in isolation, preview links, three-way merge, version restore |
+| [features/dependencies.md](features/dependencies.md)             | Dependencies panel: npm registry proxy, browse, install, remove, lock |
 | [features/modules.md](features/modules.md)                       | Module engine, defining first-party blocks                          |
 | [features/dashboard.md](features/dashboard.md)                   | Dashboard workspace, widgets, grid, customize mode                  |
 | [features/spotlight.md](features/spotlight.md)                   | Cmd+K command palette                                                |

docs/deployment/README.md

@@ -32,6 +32,7 @@ STATIC_DIR    built admin SPA directory; /app/dist in the Docker image
 INSTATIC_SECRET_KEY  base64 32-byte key for encrypted server secrets
 PUBLIC_ORIGIN        comma-separated public origin(s) the CSRF check trusts; auto-detected from RENDER_EXTERNAL_URL / RAILWAY_PUBLIC_DOMAIN on those platforms
 TRUSTED_PROXY_CIDRS  optional; trusts proxy socket peers for forwarded client-IP attribution only (audit logs, rate-limit keys) — NOT used for CSRF
+NPM_REGISTRY_URL     optional; registry for the Dependencies panel, the dependency resolver and runtime installs (default https://registry.npmjs.org); set it for a private registry or corporate mirror
 ```
 
 Generate `INSTATIC_SECRET_KEY` with `bun run scripts/generate-secret-key.ts` before adding Anthropic, OpenAI, or OpenRouter credentials or enabling TOTP MFA in production. Without it, the admin can load but saving reversible secrets fails because there is no stable encryption key.

docs/deployment/docker-image.md

@@ -144,6 +144,7 @@ Render auto-injects `RENDER_EXTERNAL_URL`, which Instatic uses as the CSRF publi
 | `INSTATIC_SECRET_KEY` | Yes for reversible server secrets | Output of `bun run scripts/generate-secret-key.ts` |
 | `PUBLIC_ORIGIN` | Behind managed HTTPS proxies | Comma-separated public origins for the CSRF check, e.g. `https://www.example.com`. Auto-detected from `RENDER_EXTERNAL_URL` / `RAILWAY_PUBLIC_DOMAIN` on those platforms |
 | `TRUSTED_PROXY_CIDRS` | Optional | Comma-separated trusted proxy CIDRs for client-IP attribution only (audit logs, rate-limit keys) — **not** used for CSRF. Trust only your real proxy CIDRs; never `0.0.0.0/0` for a public service |
+| `NPM_REGISTRY_URL` | Optional | Registry used by the Dependencies panel, the dependency resolver and runtime `bun install`; defaults to `https://registry.npmjs.org`. Set for a private registry or mirror; downloads/advisories are skipped for non-public registries |
 
 Managed platforms usually inject `PORT`. Do not hard-code a different listen port unless the platform asks for a fixed target port.
 

docs/e2e/README.md

@@ -220,7 +220,7 @@ durable assertion brittle:
   normalization, module dependency/importmap filtering, site runtime build,
   dependency resolver/cache, package importmap/server, malformed runtime-cache
   paths, and runtime asset publish injection are covered by focused Bun tests in
-  `src/__tests__/panels/depsSectionRuntime.test.tsx`,
+  `src/__tests__/panels/dependenciesPanel.test.tsx`,
   `src/__tests__/editor-hooks/useAutoResolveDependencies.test.tsx`,
   `src/__tests__/persistence/cmsRuntimeClient.test.ts`,
   `src/__tests__/server/cmsRuntimeHandlers.test.ts`,

docs/e2e/feature-matrix.md

@@ -191,12 +191,12 @@ SITE-019 note: `visual-builder.e2e.ts` saves a styled Container subtree as a lay
 | ID | Priority | Auto | Area | User Goal | Setup | Path | Expected Outcome | Watch For |
 |---|---:|:---:|---|---|---|---|---|---|
 | SITE-013 | P1 | partial | Code Editor | Author TypeScript site scripts with immediate type feedback | Site editor open | Code panel → New script → Code editor | `.ts`/`.tsx` scripts get DOM-aware completions, hover signatures, strict semantic diagnostics in a bounded collapsible Problems list, relative-file types, autosave, canvas execution, and publish compilation | worker startup, stale diagnostics, package types, completion keyboard reachability, classic-script confusion |
-| SITE-014 | P1 | partial | Dependencies | Declare runtime packages for site scripts and plugin modules | Site script or module with package import | Dependencies panel and runtime resolve endpoint | Missing imports are visible, safe dependencies resolve into a lock/importmap, and cached package files serve under `/_instatic/runtime/cache` | unsafe package names, stale lock/importmap, install failures, traversal-shaped cache paths |
+| SITE-014 | P1 | partial | Dependencies | Browse the npm registry and declare runtime packages for site scripts and plugin modules | Site script or module with package import | Dependencies panel (search, package page, install/remove), registry proxy, runtime resolve endpoint | Registry search and package pages load through the server proxy, missing imports are visible, safe dependencies resolve into a lock/importmap, and cached package files serve under `/_instatic/runtime/cache` | unsafe package names, registry outages surfacing as 502/504, stale lock/importmap, install failures, traversal-shaped cache paths |
 | SITE-016 | P1 | ✅ | Preview/Live | Compare the current draft with the live public route | Page has a published version and a later saved draft | Publish actions → Preview page; toolbar → Open live page | Preview iframe shows the current draft while the live route opens the last published output without admin chrome | draft/public leakage, stale live path, popup target, mobile overlay reachability |
 
 SITE-013 note: focused Bun coverage verifies the worker protocol/client, strict DOM-aware TypeScript diagnostics, DOM completion and hover results, relative cross-file typing, bare-package handoff to runtime analysis, `.tsx` path creation, CodeMirror compiler-diagnostic merging, lazy compiler isolation, and worker bundle budget. The 2026-08-11 agent-browser run covers live type-error rendering, `window` completion UI, hover information, autosave/reload, publish, and anonymous runtime execution; package declaration acquisition remains future work.
 
-SITE-014 note: focused Bun coverage spans the dependency panel, auto-resolve hook, client envelope validation, runtime handler normalization, module dependency/importmap filtering, script import analysis, runtime config, site runtime build, dependency resolver/cache, package importmap/server, and runtime asset publish injection. `tests/e2e/runtime-dependencies.e2e.ts` covers browser authoring of a site script import, Dependencies-panel missing package Add, live `canvas-confetti` registry/cache resolution, save/publish, public importmap emission, browser loading of the emitted `/_instatic/runtime/cache/...` package URL, and a 390px mobile path that authors a missing import, opens Dependencies, verifies no horizontal overflow, and confirms the Add action is reachable. Live registry/install failure UX permutations remain operator-run.
+SITE-014 note: focused Bun coverage spans the dependency panel, auto-resolve hook, client envelope validation, runtime handler normalization, module dependency/importmap filtering, script import analysis, runtime config, site runtime build, dependency resolver/cache, package importmap/server, and runtime asset publish injection. `tests/e2e/runtime-dependencies.e2e.ts` covers browser authoring of a site script import, Dependencies-panel missing package Add, live `canvas-confetti` registry/cache resolution, save/publish, public importmap emission, browser loading of the emitted `/_instatic/runtime/cache/...` package URL, a 390px mobile path that authors a missing import, opens Dependencies, verifies no horizontal overflow, and confirms the Add action is reachable, and a registry-browsing path that searches `pad-left`, opens its package page through the proxy, installs from the sticky install bar, waits for the lock, and removes it again (no dialog: nothing imports it and the confirm-before-delete preference is off by default). Registry proxy handler/client coverage (auth floor, query validation, scoped names, 502/504/404 mapping, TTL + single-flight cache) is Bun-level. Live registry/install failure UX permutations remain operator-run.
 
 SITE-016 note: `tests/e2e/preview-live.e2e.ts` creates a disposable page, publishes version A, saves draft version B without publishing, verifies the Preview page overlay iframe renders draft B, verifies the toolbar Open live page popup still serves published version A without editor chrome, and repeats preview opening at 390px to confirm the overlay remains reachable without document overflow. Issue #234 additionally gates Preview page through the server runtime-preview path so loop and media prefetch matches public rendering. Template-target and Content-entry live-path permutations remain lower-level or future browser coverage.