docs: introduce Remote Assets guide

Document remote assets as a feature: pointing cli.distDir at a published
npm package (via a RemoteAssets declaration) so a devframe's SPA is
fetched on demand and cached locally instead of bundled into the node
package. Covers a basic example, the resolution order, options, offline
use, custom providers, and publishing the assets package.

Author: antfubot

docs/.vitepress/config.ts

@@ -23,6 +23,7 @@ function guideGroups(prefix: string) {
       items: [
         { text: 'Introduction', link: `${prefix}/guide/` },
         { text: 'Devframe Definition', link: `${prefix}/guide/devframe-definition` },
+        { text: 'Remote Assets', link: `${prefix}/guide/remote-assets` },
         { text: 'Scoped Context', link: `${prefix}/guide/scoped-context` },
         { text: 'Cross-Plugin Services', link: `${prefix}/guide/services` },
         { text: 'RPC', link: `${prefix}/guide/rpc` },

docs/guide/remote-assets.md

@@ -0,0 +1,101 @@
+---
+outline: deep
+---
+
+# Remote Assets
+
+Anywhere a devframe serves a built SPA — `cli.distDir` — you can point at a **published npm package** instead of a local directory. The assets are then fetched on demand and cached locally, so the node package doesn't have to bundle its UI.
+
+This keeps the installed footprint small: a plugin's prebuilt SPA is usually the bulk of its tarball, and with remote assets it's served on first use rather than shipped to every consumer up front.
+
+## Basic example
+
+Give `cli.distDir` a `RemoteAssets` object naming the package and exact version that holds the built UI:
+
+```ts
+import type { RemoteAssets } from 'devframe'
+import { defineDevframe } from 'devframe'
+import pkg from '../package.json' with { type: 'json' }
+
+const distDir: RemoteAssets = {
+  package: '@acme/my-tool-assets',
+  version: pkg.version,
+  resolveFrom: import.meta.url,
+}
+
+export default defineDevframe({
+  id: 'my-tool',
+  version: pkg.version,
+  packageName: pkg.name,
+  cli: { distDir },
+  setup(ctx) {
+    // …
+  },
+})
+```
+
+That's it — the UI mounts as usual. The first request for each file is streamed from a CDN and written to a local cache; subsequent requests are served from disk.
+
+## How assets resolve
+
+For each request the source resolves in order:
+
+1. **Locally installed package** — resolved from `resolveFrom` (`import.meta.url`). If `@acme/my-tool-assets` is installed next to your tool, it's served directly with no network. This is the offline path.
+2. **On-disk cache** — files already fetched, under the project's storage directory.
+3. **CDN back-proxy** — [jsDelivr](https://www.jsdelivr.com/) by default, mirroring npm. Each file streams to the browser and is cached on the way past.
+
+Exact-version URLs are immutable, so a cached file never goes stale.
+
+## Options
+
+| Field | Purpose |
+|-------|---------|
+| `package` | npm package holding the built assets. |
+| `version` | Exact version to serve — usually your tool's own `pkg.version`. |
+| `resolveFrom` | `import.meta.url` of the declaring module; enables the zero-network path from a locally installed copy. Omit to skip straight to cache + CDN. |
+| `path` | Subpath inside the package the assets live under. Defaults to `dist`. |
+| `provider` | `'jsdelivr'` (default), `'unpkg'`, or a custom provider for an internal mirror. |
+| `offline` | `true` serves only from a local install or the cache — never the network. |
+
+`package` and `version` are interpolated into the CDN URL and cache path, so they're validated: an invalid npm name or non-exact version throws [`DF0065`](../errors/DF0065).
+
+## Offline and air-gapped use
+
+Remote assets are a convenience, not a hard network dependency. To run with no network, install the assets package explicitly — resolution step 1 then serves it locally:
+
+```sh
+npm install @acme/my-tool-assets
+```
+
+Set `offline: true` to guarantee the CDN is never contacted, or point `provider` at an internal npm mirror.
+
+## Custom provider
+
+A custom provider supplies the file URL, and optionally a file listing (used for correct 404s, SPA fallback, and static builds):
+
+```ts
+const distDir: RemoteAssets = {
+  package: '@acme/my-tool-assets',
+  version: pkg.version,
+  resolveFrom: import.meta.url,
+  provider: {
+    fileUrl: (name, version, file) =>
+      `https://npm.internal.acme.com/${name}@${version}/${file}`,
+  },
+}
+```
+
+## Publishing the assets
+
+The assets package is an ordinary npm package that ships the built UI under `path` (default `dist`) and exposes its `package.json` so `resolveFrom` can locate it:
+
+```json
+{
+  "name": "@acme/my-tool-assets",
+  "version": "1.0.0",
+  "exports": { "./package.json": "./package.json" },
+  "files": ["dist"]
+}
+```
+
+Keep its version in lockstep with the tool that declares it, so `version: pkg.version` always points at matching UI.