feat(plugins): serve every builtin plugin's SPA from a lockstep assets package

Extends the deferred-assets pattern (piloted on plugin-inspect) to all
remaining builtin plugins: og, data-inspector, code-server, assets,
messages, terminals, a11y, and git. Each plugin's iframe SPA now ships in
a lockstep `@devframes/plugin-<name>--assets` package instead of the node
tarball — the Vite build (or git's Next export) emits into assets-pkg/dist,
and cli.distDir points at a RemoteAssets declaration. Panel clientScript
bundles (messages/terminals dist/client) and a11y's dist/inject agent stay
in their node packages.

Each plugin declares its `--assets` package as an optional peer dependency
(so it resolves when a consumer installs it) alongside the dev-only
workspace link (so resolveFrom finds the local build in the monorepo);
this optional-peer declaration is also added to the inspect pilot.

Wires per-plugin turbo outputs (assets-pkg/dist), knip overrides, and
updates each plugin's test harness to resolve the SPA via
resolveStaticAssetsSource.

Author: antfubot

knip.jsonc

@@ -183,6 +183,42 @@
       "entry": [],
       "project": []
     },
+    // Each plugin's lockstep `--assets` package is referenced only as a
+    // runtime string (`${pkg.name}--assets` in `cli.distDir`), never imported,
+    // so knip can't see the dev-only workspace link. A workspace config
+    // replaces (not merges) the `plugins/*` glob's `entry`, so repeat it.
+    "plugins/og": {
+      "entry": ["src/{index,cli,vite,constants,types}.ts", "src/{client,node,rpc,inject,engine,registry}/index.ts"],
+      "ignoreDependencies": ["@devframes/plugin-og--assets"]
+    },
+    "plugins/og/assets-pkg": { "entry": [], "project": [] },
+    "plugins/data-inspector": {
+      "entry": ["src/{index,cli,vite,constants,types}.ts", "src/{client,node,rpc,inject,engine,registry}/index.ts"],
+      "ignoreDependencies": ["@devframes/plugin-data-inspector--assets"]
+    },
+    "plugins/data-inspector/assets-pkg": { "entry": [], "project": [] },
+    "plugins/code-server": {
+      "entry": ["src/{index,cli,vite,constants,types}.ts", "src/{client,node,rpc,inject,engine,registry}/index.ts"],
+      "ignoreDependencies": ["@devframes/plugin-code-server--assets"]
+    },
+    "plugins/code-server/assets-pkg": { "entry": [], "project": [] },
+    "plugins/assets": {
+      "entry": ["src/{index,cli,vite,constants,types}.ts", "src/{client,node,rpc,inject,engine,registry}/index.ts"],
+      "ignoreDependencies": ["@devframes/plugin-assets--assets"]
+    },
+    "plugins/assets/assets-pkg": { "entry": [], "project": [] },
+    "plugins/messages": {
+      "entry": ["src/{index,cli,vite,constants,types}.ts", "src/{client,node,rpc,inject,engine,registry}/index.ts"],
+      "ignoreDependencies": ["@devframes/plugin-messages--assets"]
+    },
+    "plugins/messages/assets-pkg": { "entry": [], "project": [] },
+    "plugins/terminals": {
+      "entry": ["src/{index,cli,vite,constants,types}.ts", "src/{client,node,rpc,inject,engine,registry}/index.ts"],
+      "ignoreDependencies": ["@devframes/plugin-terminals--assets"]
+    },
+    "plugins/terminals/assets-pkg": { "entry": [], "project": [] },
+    "plugins/a11y/assets-pkg": { "entry": [], "project": [] },
+    "plugins/git/assets-pkg": { "entry": [], "project": [] },
     "plugins/a11y": {
       // `storybook-solidjs-vite` (not an official `@storybook/*` framework
       // package) doesn't match knip's Storybook plugin trigger, so it never
@@ -199,15 +235,17 @@
         "src/{index,cli,vite,constants,types}.ts",
         "src/{client,node,rpc,inject,engine,registry}/index.ts",
         "src/**/*.stories.tsx"
-      ]
+      ],
+      "ignoreDependencies": ["@devframes/plugin-a11y--assets"]
     },
     "plugins/git": {
       // The React client build's root sits at `src/client` (`next dev
       // src/client`), not the workspace root, so knip's default PostCSS
       // config glob (workspace-root `postcss.config.*`) misses it.
       "postcss": {
         "config": ["src/client/postcss.config.mjs"]
-      }
+      },
+      "ignoreDependencies": ["@devframes/plugin-git--assets"]
     }
   }
 }

plugins/a11y/README.md

@@ -122,6 +122,6 @@ pnpm -C plugins/a11y dev         # from source: same, at /__devframes_plugin_a11
 | `src/rpc/` | — | `get-config` static RPC + the type-safe client registry |
 | `src/shared/protocol.ts` | — | the agent ↔ panel `BroadcastChannel` contract |
 | `src/inject/` | — | the host-page agent (axe scan, highlight overlay, hub messages mirror) → `dist/inject/inject.js` |
-| `src/spa/` | — | the Solid panel SPA → `dist/spa` |
+| `src/spa/` | — | the Solid panel SPA → `assets-pkg/dist` (ships in `@devframes/plugin-a11y--assets`) |
 | `demo/` | — | same-origin host page + server (dev + static modes) |
 | `tests/` | — | dev-server RPC + static-build dump |

plugins/a11y/assets-pkg/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@devframes/plugin-a11y--assets",
+  "type": "module",
+  "version": "0.9.0-beta.8",
+  "description": "Prebuilt browser assets (SPA) for @devframes/plugin-a11y, served on demand through devframe's remote-assets back-proxy.",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/devframes/devframe#readme",
+  "repository": {
+    "directory": "plugins/a11y/assets-pkg",
+    "type": "git",
+    "url": "git+https://github.com/devframes/devframe.git"
+  },
+  "bugs": "https://github.com/devframes/devframe/issues",
+  "keywords": [
+    "devframe",
+    "devframe-plugin",
+    "devtools",
+    "client-assets"
+  ],
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "turbo run build --filter=@devframes/plugin-a11y"
+  }
+}

plugins/a11y/demo/server.mjs

@@ -11,7 +11,7 @@
  *
  * Two modes prove the plugin works either way:
  *
- *   node demo/server.mjs          dev    — live WebSocket RPC (`dist/spa`)
+ *   node demo/server.mjs          dev    — live WebSocket RPC (`assets-pkg/dist`)
  *   node demo/server.mjs build    static — baked RPC dump,    (`dist/static`)
  *
  * The scan/highlight loop is identical in both: it rides the BroadcastChannel,
@@ -36,7 +36,7 @@ const devframe = createA11yDevframe()
 const mode = process.argv[2] === 'build' ? 'build' : 'dev'
 const basePath = devframe.basePath
 const injectDir = resolve(ROOT, 'dist/inject')
-const panelDir = mode === 'build' ? resolve(ROOT, 'dist/static') : resolve(ROOT, 'dist/spa')
+const panelDir = mode === 'build' ? resolve(ROOT, 'dist/static') : resolve(ROOT, 'assets-pkg/dist')
 
 function requireBuilt(file, hint) {
   if (!existsSync(file)) {

plugins/a11y/package.json

@@ -52,10 +52,14 @@
     "test": "vitest run"
   },
   "peerDependencies": {
+    "@devframes/plugin-a11y--assets": "workspace:*",
     "devframe": "workspace:*",
     "vite": "^8.0.0"
   },
   "peerDependenciesMeta": {
+    "@devframes/plugin-a11y--assets": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }
@@ -65,6 +69,7 @@
   },
   "devDependencies": {
     "@antfu/design": "catalog:frontend",
+    "@devframes/plugin-a11y--assets": "workspace:*",
     "axe-core": "catalog:frontend",
     "colorjs.io": "catalog:frontend",
     "devframe": "workspace:*",

plugins/a11y/src/index.ts

@@ -1,4 +1,4 @@
-import type { DevframeDefinition } from 'devframe'
+import type { DevframeDefinition, RemoteAssets } from 'devframe'
 import { fileURLToPath } from 'node:url'
 import { defineDevframe } from 'devframe'
 import pkg from '../package.json' with { type: 'json' }
@@ -8,10 +8,15 @@ import { setupA11y } from './node/index.ts'
 const DEFAULT_ID = 'devframes_plugin_a11y'
 const BASE_PATH = '/__devframes_plugin_a11y/'
 
-// The Solid panel SPA is built (by Vite) into `dist/spa`. From both the
-// source entry (`src/index.ts`, via the workspace alias) and the published
-// entry (`dist/index.mjs`), `../dist/spa` resolves to `<pkg>/dist/spa`.
-const distDir = fileURLToPath(new URL('../dist/spa', import.meta.url))
+// The Solid panel SPA ships in the lockstep `@devframes/plugin-a11y--assets`
+// package, served on demand through devframe's remote-assets back-proxy;
+// `resolveFrom` serves a locally installed copy (a workspace link here) with
+// zero network. The host-page agent bundle (`dist/inject`, below) stays here.
+const distDir: RemoteAssets = {
+  package: `${pkg.name}--assets`,
+  version: pkg.version,
+  resolveFrom: import.meta.url,
+}
 
 /**
  * Absolute path to the built in-page **agent** module (`dist/inject/inject.js`)

plugins/a11y/src/spa/vite.config.ts

@@ -14,7 +14,7 @@ export default defineConfig({
   resolve: { alias },
   plugins: [solid(), UnoCSS()],
   build: {
-    outDir: fileURLToPath(new URL('../../dist/spa', import.meta.url)),
+    outDir: fileURLToPath(new URL('../../assets-pkg/dist', import.meta.url)),
     emptyOutDir: true,
   },
 })

plugins/a11y/tests/_utils.ts

@@ -1,27 +1,34 @@
 import type { StartedServer } from 'devframe/internal'
 import { existsSync } from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import process from 'node:process'
-import { fileURLToPath } from 'node:url'
 import { DEVFRAME_CONNECTION_META_FILENAME } from 'devframe/constants'
 import { createH3DevframeHost } from 'devframe/internal'
 import { createHostContext } from 'devframe/node'
+import { resolveStaticAssetsSource } from 'devframe/utils/remote-assets'
 import { mountStaticHandler } from 'devframe/utils/serve-static'
 import { getPort } from 'get-port-please'
 import { H3 } from 'h3'
 import { resolve } from 'pathe'
 import { serveTestContext } from '../../../tests/helpers/serve-test-context'
 import createA11yDevframe from '../src/index'
 
-const HERE = fileURLToPath(new URL('.', import.meta.url))
-const SPA_DIST = resolve(HERE, '../dist/spa')
 const devframe = createA11yDevframe()
 
-/** Loud failure if the Solid panel hasn't been built — tests serve `dist/spa`. */
+/** Resolve the Solid panel SPA to a local dir — the workspace-linked `--assets` package in dev. */
+function localSpaDir(): string {
+  const resolved = resolveStaticAssetsSource(devframe.cli!.distDir!, resolve(os.tmpdir(), 'devframes_plugin_a11y-test'))
+  if (typeof resolved !== 'string')
+    throw new TypeError('[devframes_plugin_a11y] client SPA missing — run `pnpm -C plugins/a11y run build` first.')
+  return resolved
+}
+
+/** Loud failure if the Solid panel hasn't been built — tests serve the client SPA. */
 export function assertClientBuilt(): void {
-  if (!existsSync(path.join(SPA_DIST, 'index.html'))) {
+  if (!existsSync(path.join(localSpaDir(), 'index.html'))) {
     throw new Error(
-      '[devframes_plugin_a11y] dist/spa missing — run `pnpm -C plugins/a11y run build` first.',
+      '[devframes_plugin_a11y] client SPA missing — run `pnpm -C plugins/a11y run build` first.',
     )
   }
 }
@@ -37,9 +44,7 @@ export interface InspectorServer extends StartedServer {
  * ws transport tests.
  */
 export async function startInspectorServer(): Promise<InspectorServer> {
-  const distDir = devframe.cli!.distDir!
-  if (typeof distDir !== 'string')
-    throw new TypeError('these tests serve the local dist directory — build the SPA first')
+  const distDir = localSpaDir()
   const basePath = devframe.basePath!
   const host = '127.0.0.1'
   const port = await getPort({ host, random: true })

plugins/assets/assets-pkg/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@devframes/plugin-assets--assets",
+  "type": "module",
+  "version": "0.9.0-beta.8",
+  "description": "Prebuilt browser assets (SPA) for @devframes/plugin-assets, served on demand through devframe's remote-assets back-proxy.",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/devframes/devframe#readme",
+  "repository": {
+    "directory": "plugins/assets/assets-pkg",
+    "type": "git",
+    "url": "git+https://github.com/devframes/devframe.git"
+  },
+  "bugs": "https://github.com/devframes/devframe/issues",
+  "keywords": [
+    "devframe",
+    "devframe-plugin",
+    "devtools",
+    "client-assets"
+  ],
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "turbo run build --filter=@devframes/plugin-assets"
+  }
+}

plugins/assets/package.json

@@ -47,10 +47,14 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
+    "@devframes/plugin-assets--assets": "workspace:*",
     "devframe": "workspace:*",
     "vite": "^7.0.0 || ^8.0.0"
   },
   "peerDependenciesMeta": {
+    "@devframes/plugin-assets--assets": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }
@@ -66,6 +70,7 @@
   },
   "devDependencies": {
     "@antfu/design": "catalog:frontend",
+    "@devframes/plugin-assets--assets": "workspace:*",
     "@devframes/vite": "workspace:*",
     "@iconify-json/ph": "catalog:frontend",
     "@storybook/addon-a11y": "catalog:storybook",