refactor(assets): defer raw byte serving to the host, don't self-serve

The managed public/ directory is already served by whatever host the
plugin is mounted into (Vite, Nuxt, any framework serves public/ at /),
so the plugin no longer stands up its own /__…-raw/ route. Each asset's
publicPath is now baseURL + its path (baseURL default '/'), pointing at
the host's own URLs.

- Add baseURL option (where the host serves the dir) and serveStatic
  (self-serve, off by default). setupAssets only calls ctx.views.
  hostStatic() when serveStatic is set.
- The standalone CLI is its own host, so createAssetsCli() enables
  serveStatic (under a dedicated base so it doesn't collide with the SPA).
- Plugin dev server: point Vite's own publicDir at the managed dir so
  Vite serves the fixtures at /, and drop the ad-hoc raw-serving
  middleware. Gated to 'serve' so fixtures never bake into dist.
- Docs + README + API snapshots updated.

Co-authored-by: opencode <noreply@opencode.ai>

Author: antfubot

docs/plugins/assets.md

@@ -44,6 +44,7 @@ import { createAssetsDevframe } from '@devframes/plugin-assets'
 
 export default createAssetsDevframe({
   dir: 'static', // defaults to `<cwd>/public`
+  baseURL: '/', // the URL the host serves `dir` at
   write: true,
   uploadExtensions: ['png', 'jpg', 'svg', 'webp'], // defaults to Nuxt DevTools' own allow-list, or '*' for any
 })
@@ -52,10 +53,16 @@ export default createAssetsDevframe({
 | Option | Default | Description |
 |--------|---------|-------------|
 | `dir` | `<cwd>/public` | Directory this devframe manages. |
+| `baseURL` | `/` | URL base the host serves `dir` at — each asset's `publicPath` is `baseURL` + its path. Match a non-root deployment base (e.g. Nuxt's `app.baseURL`). |
 | `write` | `true` | Enable upload, rename, delete, and folder creation from the UI. |
 | `uploadExtensions` | Nuxt DevTools' allow-list | Extensions `upload` accepts, or `'*'` for any. |
+| `serveStatic` | `false` | Serve the directory's bytes from this devframe itself. Left off when mounted into a host that already serves `public/`; the standalone CLI turns it on. |
 | `build` | `false` | Register the `build` CLI subcommand. See [why it's off by default](#static-export) below. |
 
+## How previews are served
+
+Asset previews (`<img>`, `<video>`, download links) load the files by their **public URL**, and the host the plugin is mounted into serves those files — Vite, Nuxt, and most frameworks already serve their `public/` folder at `/`. The plugin never stands up its own byte-serving route; it just resolves each asset's `publicPath` as `baseURL` + the file's path. Point `baseURL` at wherever the host serves `dir` (the default `/` matches the usual `public/` convention). The standalone CLI (`pnpx @devframes/plugin-assets`) is its own host, so it flips `serveStatic` on and serves the directory under a dedicated base.
+
 ## RPC surface
 
 All functions are namespaced `devframes:plugin:assets:*`:
@@ -77,7 +84,7 @@ All functions are namespaced `devframes:plugin:assets:*`:
 
 ## Static export
 
-Every devframe's `build` CLI subcommand is disabled here by default (`capabilities: { build: false }`). Real byte serving for previews goes through `ctx.views.hostStatic()`, which only mounts real files under a live adapter (`cli` / `vite` / `embedded`) — a static export can never copy those bytes, and every write action is inherently excluded from a static dump. Rather than ship a broken, preview-less, write-less shell of the tool, the `build` command is simply not registered. Pass `{ build: true }` to `createAssetsDevframe()` (and `{ force: true }` if calling `createBuild()` directly) if that degraded export is still useful to you — the file listing itself still bakes into the static RPC dump.
+Every devframe's `build` CLI subcommand is disabled here by default (`capabilities: { build: false }`). A static export has no live host serving the files, and every write action is inherently excluded from a static dump. Rather than ship a broken, preview-less, write-less shell of the tool, the `build` command is simply not registered. Pass `{ build: true }` to `createAssetsDevframe()` (and `{ force: true }` if calling `createBuild()` directly) if that degraded export is still useful to you — the file listing itself still bakes into the static RPC dump.
 
 ## Source
 

plugins/assets/README.md

@@ -6,6 +6,8 @@ Browse, preview, upload, rename, and delete the files in a directory — a frame
 pnpx @devframes/plugin-assets
 ```
 
-Manages `<cwd>/public` by default. The package exports `createAssetsDevframe()` for custom definitions and `assetsVitePlugin()` from `@devframes/plugin-assets/vite` for Vite hosts. Pass `{ dir }` to manage a different directory, or `{ write: false }` (`--read-only` on the standalone CLI) for a browse-only deployment.
+Manages `<cwd>/public` by default. The package exports `createAssetsDevframe()` for custom definitions and `assetsVitePlugin()` from `@devframes/plugin-assets/vite` for Vite hosts. Pass `{ dir }` to manage a different directory, `{ baseURL }` to match where the host serves it, or `{ write: false }` (`--read-only` on the standalone CLI) for a browse-only deployment.
+
+Asset previews load files by their public URL, served by the host the plugin is mounted into (Vite/Nuxt/etc. already serve `public/` at `/`) — the plugin doesn't serve the bytes itself. The standalone CLI is its own host, so it serves the directory for you.
 
 The standalone server requires devframe's trust handshake by default because it can read, write, and delete real files. The `build` CLI subcommand is disabled by default — see the docs page for why.

plugins/assets/src/cli.ts

@@ -1,7 +1,10 @@
 import type { CacHandle } from 'devframe/adapters/cac'
 import { createCac } from 'devframe/adapters/cac'
-import assetsDevframe from './index'
+import { createAssetsDevframe } from './index'
 
 export function createAssetsCli(): CacHandle {
-  return createCac(assetsDevframe)
+  // The standalone CLI is its own host, so it serves the managed directory
+  // itself (under a dedicated base) — unlike the mounted plugin, which
+  // defers to the Vite/framework dev server it's attached to.
+  return createCac(createAssetsDevframe({ serveStatic: true }))
 }

plugins/assets/src/index.ts

@@ -28,6 +28,22 @@ export interface AssetsDevframeOptions {
    * own `cwd`.
    */
   dir?: string
+  /**
+   * URL base the **host** serves the managed directory at, used to build
+   * each asset's `publicPath`. Defaults to `/` — Vite, Nuxt, and most
+   * frameworks serve their `public/` folder at the site root. Set this to
+   * match a non-root deployment base (e.g. Nuxt's `app.baseURL`).
+   */
+  baseURL?: string
+  /**
+   * Serve the managed directory's bytes from this devframe itself.
+   * Defaults to `false`: when mounted into a host (Vite/Nuxt/…) that host
+   * already serves `public/` at {@link baseURL}, so the plugin references
+   * those URLs instead of standing up its own route. The standalone CLI
+   * sets this to `true` (it is its own host), serving the directory under
+   * a dedicated base so it doesn't collide with the SPA at `/`.
+   */
+  serveStatic?: boolean
   basePath?: string
   distDir?: string
   /** Preferred standalone CLI port (default 9015). */
@@ -50,11 +66,11 @@ export interface AssetsDevframeOptions {
   auth?: boolean
   /**
    * Register the `build` CLI subcommand. Disabled by default: a static
-   * export can only ever list file metadata from a baked snapshot — real
-   * previews need `ctx.views.hostStatic()`'s live byte serving, and every
-   * write action is inherently excluded from a static dump — so the
-   * command would produce a broken, write-less shell of the tool. Opt
-   * back in if that degraded export is still useful to you.
+   * export can only ever list file metadata from a baked snapshot — there
+   * is no live host serving the files, and every write action is inherently
+   * excluded from a static dump — so the command would produce a broken,
+   * write-less shell of the tool. Opt back in if that degraded export is
+   * still useful to you.
    */
   build?: boolean
 }
@@ -71,7 +87,11 @@ export function createAssetsDevframe(options: AssetsDevframeOptions = {}): Devfr
   const id = options.id ?? DEFAULT_ID
   const distDir = options.distDir ?? resolve(PKG_ROOT, 'dist/spa')
   const write = options.write ?? true
-  const rawBase = `/__${id}-raw/`
+  const serveStatic = options.serveStatic ?? false
+  // When self-serving (standalone CLI), mount under a dedicated base so the
+  // asset bytes don't collide with the SPA served at `/`. Otherwise trust the
+  // host to serve `public/` at `baseURL` (default `/`).
+  const baseURL = options.baseURL ?? (serveStatic ? `/__${id}-raw/` : '/')
 
   return defineDevframe({
     id,
@@ -101,7 +121,8 @@ export function createAssetsDevframe(options: AssetsDevframeOptions = {}): Devfr
         dir,
         write: readOnlyFlag ? false : write,
         uploadExtensions: options.uploadExtensions ?? DEFAULT_ALLOWED_UPLOAD_EXTENSIONS,
-        rawBase,
+        baseURL,
+        serveStatic,
       })
     },
   })

plugins/assets/src/node/context.ts

@@ -8,8 +8,12 @@ export interface AssetsConfig {
   write: boolean
   /** Extensions `upload` accepts, or `'*'` to accept any. */
   uploadExtensions: readonly string[] | '*'
-  /** URL prefix the raw bytes are mounted at (live adapters only). */
-  rawBase: string
+  /**
+   * URL base the managed directory is served at. Normally the host
+   * (Vite / Nuxt / …) serves `public/` at `/`, so asset `publicPath`s are
+   * `joinURL(baseURL, path)` and the plugin serves nothing itself.
+   */
+  baseURL: string
   /** The upload streaming channel, created once in `setupAssets` when `write` is enabled. */
   uploadChannel?: RpcStreamingChannel<Uint8Array>
 }
@@ -47,7 +51,7 @@ export function getAssetsContext(ctx: DevframeNodeContext): AssetsContext {
     dir,
     write: config?.write ?? true,
     uploadExtensions: config?.uploadExtensions ?? '*',
-    rawBase: config?.rawBase ?? '/__devframes_plugin_assets_raw/',
+    baseURL: config?.baseURL ?? '/',
     uploadChannel: config?.uploadChannel,
     resolvePath: (relativePath: string) => resolveAssetPath(dir, relativePath),
   }

plugins/assets/src/node/index.ts

@@ -13,17 +13,32 @@ export interface SetupAssetsOptions {
   write: boolean
   /** Extensions `upload` accepts, or `'*'` to accept any. */
   uploadExtensions: readonly string[] | '*'
-  /** URL prefix the raw bytes are mounted at (live adapters only). */
-  rawBase: string
+  /**
+   * URL base the managed directory is served at — the base every asset's
+   * `publicPath` is resolved against.
+   */
+  baseURL: string
+  /**
+   * Whether this devframe should serve the managed directory's bytes
+   * itself. Left `false` when mounted into a host (Vite / Nuxt / …) that
+   * already serves `public/` at {@link baseURL}; set `true` only for the
+   * standalone CLI, which is its own host.
+   */
+  serveStatic: boolean
 }
 
 const watchers = new WeakMap<DevframeNodeContext, () => Promise<void>>()
 
 /**
  * Register the assets RPC surface on a devframe node context: ensures the
- * managed directory exists, hosts it for raw byte access, registers the
- * read RPCs (always) and write RPCs (when enabled), and starts a live
- * file watcher in dev mode.
+ * managed directory exists, registers the read RPCs (always) and write
+ * RPCs (when enabled), and starts a live file watcher in dev mode.
+ *
+ * Raw asset bytes (for `<img>`/`<video>`/download previews) are served by
+ * the **host** the plugin is attached to — Vite, Nuxt, or any framework
+ * already serves its `public/` dir at {@link SetupAssetsOptions.baseURL}.
+ * The plugin only serves them itself when `serveStatic` is set (the
+ * standalone CLI, which is its own host).
  *
  * Called from the definition's `setup(ctx)` and reusable by host adapters
  * that wire their own context.
@@ -38,11 +53,12 @@ export async function setupAssets(ctx: DevframeNodeContext, options: SetupAssets
 
   configureAssets(ctx, { ...options, uploadChannel })
 
-  // Real byte serving for `<img>`/`<video>`/`<a download>` etc. Only
-  // meaningful under a live adapter (cli / vite / embedded) — a no-op
-  // under `mode: 'build'`, which this plugin opts out of by default via
-  // `capabilities.build: false` anyway.
-  ctx.views.hostStatic(options.rawBase, options.dir)
+  // Only self-serve when this devframe is its own host (the standalone
+  // CLI). When attached to a Vite/Nuxt/etc. dev server, that host already
+  // serves the managed directory at `baseURL`, so we reference its URLs
+  // rather than mounting our own route.
+  if (options.serveStatic)
+    ctx.views.hostStatic(options.baseURL, options.dir)
 
   for (const fn of readFunctions)
     ctx.rpc.register(fn)

plugins/assets/src/node/scanner.ts

@@ -26,31 +26,31 @@ export function guessAssetType(path: string): AssetType {
   return 'other'
 }
 
-function toPublicPath(rawBase: string, posixPath: string): string {
+function toPublicPath(baseURL: string, posixPath: string): string {
   const encoded = posixPath.split('/').map(encodeURIComponent).join('/')
-  return joinURL(rawBase, encoded)
+  return joinURL(baseURL, encoded)
 }
 
 /** Builds an {@link AssetInfo} from an already-resolved `fs.Stats`. */
-export function statToAssetInfo(dir: string, rawBase: string, relPath: string, stat: Stats): AssetInfo {
+export function statToAssetInfo(dir: string, baseURL: string, relPath: string, stat: Stats): AssetInfo {
   const posixPath = relPath.replace(/\\/g, '/')
   return {
     path: posixPath,
     type: guessAssetType(posixPath),
-    publicPath: toPublicPath(rawBase, posixPath),
+    publicPath: toPublicPath(baseURL, posixPath),
     size: stat.size,
     mtime: stat.mtimeMs,
   }
 }
 
 /** Recursively lists every file under `dir`, sorted alphabetically by path. */
-export async function scanAssets(dir: string, rawBase: string): Promise<AssetInfo[]> {
+export async function scanAssets(dir: string, baseURL: string): Promise<AssetInfo[]> {
   const files = await glob(['**/*'], { cwd: dir, onlyFiles: true, dot: false })
 
   const infos = await Promise.all(files.map(async (relPath): Promise<AssetInfo | undefined> => {
     try {
       const stat = await fsp.lstat(join(dir, relPath))
-      return statToAssetInfo(dir, rawBase, relPath, stat)
+      return statToAssetInfo(dir, baseURL, relPath, stat)
     }
     catch {
       // Removed between the glob scan and the stat call — drop it silently,

plugins/assets/src/rpc/functions/list.ts

@@ -34,7 +34,7 @@ export const list = defineAssetsRpc({
       // The RPC runtime awaits handlers before validating `returns`; its
       // public setup type currently models schema-backed returns as
       // synchronous.
-      handler: (async (): Promise<AssetInfo[]> => scanAssets(assets.dir, assets.rawBase)) as any,
+      handler: (async (): Promise<AssetInfo[]> => scanAssets(assets.dir, assets.baseURL)) as any,
     }
   },
 })

plugins/assets/src/rpc/functions/rename.ts

@@ -52,7 +52,7 @@ export const rename = defineAssetsRpc({
 
         if (from === to) {
           const stat = await fsp.lstat(from)
-          return statToAssetInfo(assets.dir, assets.rawBase, path, stat)
+          return statToAssetInfo(assets.dir, assets.baseURL, path, stat)
         }
 
         const targetExists = await fsp.access(to).then(() => true).catch(() => false)
@@ -70,7 +70,7 @@ export const rename = defineAssetsRpc({
         }
 
         const stat = await fsp.lstat(to)
-        return statToAssetInfo(assets.dir, assets.rawBase, nextRelPath, stat)
+        return statToAssetInfo(assets.dir, assets.baseURL, nextRelPath, stat)
       }) as any,
     }
   },

plugins/assets/src/rpc/functions/write-text.ts

@@ -34,7 +34,7 @@ export const writeText = defineAssetsRpc({
       handler: (async ({ path, content }: { path: string, content: string }): Promise<AssetInfo> => {
         const absolute = assets.resolvePath(path)
         await fsp.writeFile(absolute, content, 'utf-8')
-        return statToAssetInfo(assets.dir, assets.rawBase, path, await fsp.lstat(absolute))
+        return statToAssetInfo(assets.dir, assets.baseURL, path, await fsp.lstat(absolute))
       }) as any,
     }
   },