devframe 0.9.0-beta.4 → 0.9.0-beta.5

package/dist/utils/serve-static.mjs

@@ -1,9 +1,9 @@
 import { createReadStream } from "node:fs";
-import { extname, join, normalize, resolve, sep } from "pathe";
 import { stat } from "node:fs/promises";
-import { H3, defineHandler } from "h3";
 import { Readable } from "node:stream";
 import { lookup } from "mrmime";
+import { extname, join, normalize, resolve, sep } from "pathe";
+import { H3, defineHandler } from "h3";
 //#region src/utils/serve-static.ts
 const HTML_EXTENSIONS = [".html", ".htm"];
 async function statFile(abs) {
@@ -74,7 +74,43 @@ function normalizeOptions(options) {
 	};
 }
 /**
-* h3 event handler that serves files from `dir` with SPA fallback.
+* Drive one request through a {@link RemoteAssetsStore}: the store's
+* `Response` on a hit, a 404 on a miss, or a 502 (styled error page for HTML
+* navigations) on provider failure — shared between the h3 and connect flavors.
+*/
+async function remoteResponse(store, urlPath, accept) {
+	try {
+		return await store.serve(urlPath) ?? new Response(null, { status: 404 });
+	} catch (error) {
+		if (typeof accept === "string" && accept.includes("text/html")) return new Response(remoteErrorPage(store.assets.package, store.assets.version, error instanceof Error ? error.message : String(error)), {
+			status: 502,
+			headers: { "Content-Type": "text/html; charset=utf-8" }
+		});
+		return new Response(null, { status: 502 });
+	}
+}
+function serveRemoteAssetsHandler(store) {
+	return defineHandler(async (event) => {
+		const method = event.req.method;
+		if (method !== "GET" && method !== "HEAD") {
+			event.res.status = 405;
+			event.res.headers.set("Allow", "GET, HEAD");
+			return "";
+		}
+		const res = await remoteResponse(store, event.url.pathname, event.req.headers.get("accept"));
+		event.res.status = res.status;
+		res.headers.forEach((v, k) => event.res.headers.set(k, v));
+		if (method === "HEAD") {
+			await res.body?.cancel().catch(() => {});
+			return "";
+		}
+		return res.body ?? "";
+	});
+}
+/**
+* h3 event handler that serves files from `source` with SPA fallback — a
+* local directory, or a {@link RemoteAssetsStore} whose files stream through
+* the CDN back-proxy into the local cache.
 *
 * Drop-in replacement for `fromNodeMiddleware(sirv(dir, { dev: true, single: true }))`
 * when the surrounding server is an h3 app — no `Cache-Control` beyond
@@ -82,8 +118,9 @@ function normalizeOptions(options) {
 * file extension falls back to `<dir>/index.html` so client-side routing
 * works.
 */
-function serveStaticHandler(dir, options) {
-	const absDir = resolve(dir);
+function serveStaticHandler(source, options) {
+	if (typeof source !== "string") return serveRemoteAssetsHandler(source);
+	const absDir = resolve(source);
 	const opts = normalizeOptions(options);
 	return defineHandler(async (event) => {
 		const method = event.req.method;
@@ -109,9 +146,9 @@ function serveStaticHandler(dir, options) {
 * from `event.url.pathname`, so the file resolver sees paths relative to
 * `dir`.
 */
-function mountStaticHandler(app, base, dir, options) {
+function mountStaticHandler(app, base, source, options) {
 	const staticApp = new H3();
-	staticApp.use(serveStaticHandler(dir, options));
+	staticApp.use(serveStaticHandler(source, options));
 	app.mount(base.replace(/\/$/, ""), staticApp);
 }
 /**
@@ -121,8 +158,8 @@ function mountStaticHandler(app, base, dir, options) {
 * Connect stack — avoids forcing the host package to depend on h3 just to
 * adapt an event handler back into Node middleware.
 */
-function serveStaticNodeMiddleware(dir, options) {
-	const absDir = resolve(dir);
+function serveStaticNodeMiddleware(source, options) {
+	const absDir = typeof source === "string" ? resolve(source) : void 0;
 	const opts = normalizeOptions(options);
 	return (req, res, next) => {
 		(async () => {
@@ -138,6 +175,22 @@ function serveStaticNodeMiddleware(dir, options) {
 				return;
 			}
 			const url = req.url ?? "/";
+			if (absDir === void 0) {
+				const response = await remoteResponse(source, url, req.headers.accept);
+				if (response.status === 404 && next) {
+					next();
+					return;
+				}
+				res.statusCode = response.status;
+				response.headers.forEach((v, k) => res.setHeader(k, v));
+				if (method === "HEAD" || !response.body) {
+					await response.body?.cancel().catch(() => {});
+					res.end();
+					return;
+				}
+				Readable.fromWeb(response.body).pipe(res);
+				return;
+			}
 			const file = await resolveTarget(absDir, url, opts.indexNames, opts.single);
 			if (!file) {
 				if (next) {
@@ -164,5 +217,46 @@ function serveStaticNodeMiddleware(dir, options) {
 		});
 	};
 }
+/**
+* Minimal, dependency-free HTML shown when a remote-assets request cannot
+* be satisfied (no installed package, no cache, provider unreachable).
+*/
+function remoteErrorPage(pkg, version, reason) {
+	const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+	const name = esc(pkg);
+	const ver = esc(version);
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Client assets unavailable</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; min-height: 100vh; display: grid; place-items: center; font: 14px/1.6 ui-sans-serif, system-ui, sans-serif; background: #fafafa; color: #27272a; }
+  main { max-width: 32rem; padding: 2rem; }
+  h1 { font-size: 1rem; font-weight: 600; margin: 0 0 .5rem; }
+  p { margin: .5rem 0; opacity: .8; }
+  pre { font: 12px/1.6 ui-monospace, monospace; background: rgb(125 125 125 / .12); border-radius: 6px; padding: .75rem 1rem; overflow-x: auto; }
+  button { font: inherit; padding: .35rem 1rem; border-radius: 6px; border: 1px solid rgb(125 125 125 / .3); background: transparent; color: inherit; cursor: pointer; }
+  button:hover { background: rgb(125 125 125 / .08); }
+  .muted { opacity: .55; font-size: 12px; }
+  @media (prefers-color-scheme: dark) { body { background: #111; color: #d4d4d8; } }
+</style>
+</head>
+<body>
+<main>
+  <h1>Client assets unavailable</h1>
+  <p>The UI for this tool is served from <code>${name}@${ver}</code>, which could not be reached.</p>
+  <pre>${esc(reason)}</pre>
+  <p>To use it without network access, install the assets package locally:</p>
+  <pre>npm install ${name}@${ver}</pre>
+  <button onclick="location.reload()">Retry</button>
+  <p class="muted">devframe remote assets</p>
+</main>
+</body>
+</html>
+`;
+}
 //#endregion
 export { mountStaticHandler, serveStaticHandler, serveStaticNodeMiddleware };

package/dist/utils/shared-state.d.mts

@@ -1,2 +1,2 @@
-import { _t as SharedState, bt as SharedStatePatch, ft as Immutable, gt as ImmutableSet, ht as ImmutableObject, mt as ImmutableMap, pt as ImmutableArray, vt as SharedStateEvents, xt as createSharedState, yt as SharedStateOptions } from "../devframe-5oblos7I.mjs";
+import { at as Immutable, ct as ImmutableObject, dt as SharedStateEvents, ft as SharedStateOptions, lt as ImmutableSet, mt as createSharedState, ot as ImmutableArray, pt as SharedStatePatch, st as ImmutableMap, ut as SharedState } from "../devframe-Cfx6doi4.mjs";
 export { Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableSet, SharedState, SharedStateEvents, SharedStateOptions, SharedStatePatch, createSharedState };

package/dist/utils/streaming-channel.d.mts

@@ -1,2 +1,2 @@
-import { at as CreateStreamSinkOptions, ct as StreamSink, dt as createStreamSink, it as CreateStreamReaderOptions, lt as StreamSinkEvents, ot as StreamErrorPayload, rt as BufferedChunk, st as StreamReader, ut as createStreamReader } from "../devframe-5oblos7I.mjs";
+import { $ as StreamErrorPayload, Q as CreateStreamSinkOptions, X as BufferedChunk, Z as CreateStreamReaderOptions, et as StreamReader, it as createStreamSink, nt as StreamSinkEvents, rt as createStreamReader, tt as StreamSink } from "../devframe-Cfx6doi4.mjs";
 export { BufferedChunk, CreateStreamReaderOptions, CreateStreamSinkOptions, StreamErrorPayload, StreamReader, StreamSink, StreamSinkEvents, createStreamReader, createStreamSink };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.9.0-beta.4",
+  "version": "0.9.0-beta.5",
   "description": "Framework for building one portable devtool integration that runs in any viewer.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -52,6 +52,7 @@
     "./utils/launch-editor": "./dist/utils/launch-editor.mjs",
     "./utils/nanoid": "./dist/utils/nanoid.mjs",
     "./utils/open": "./dist/utils/open.mjs",
+    "./utils/remote-assets": "./dist/utils/remote-assets.mjs",
     "./utils/simple-schema": "./dist/utils/simple-schema.mjs",
     "./utils/serve-static": "./dist/utils/serve-static.mjs",
     "./utils/shared-state": "./dist/utils/shared-state.mjs",
@@ -89,7 +90,6 @@
     "@standard-schema/spec": "^1.1.0",
     "birpc": "^4.1.0",
     "crossws": "^0.4.10",
-    "destr": "^2.0.5",
     "h3": "^2.0.1-rc.26",
     "mrmime": "^2.0.1",
     "nostics": "^1.2.0",
@@ -106,7 +106,6 @@
     "mlly": "^1.8.2",
     "obug": "^2.1.4",
     "ohash": "^2.0.11",
-    "open": "^11.0.0",
     "p-limit": "^7.3.1",
     "perfect-debounce": "^2.1.0",
     "structured-clone-es": "^2.0.1",

package/skills/devframe/SKILL.md

@@ -5,7 +5,7 @@ description: >
   framework- and build-tool-agnostic foundation for defining a
   devtool once and serving it in many places. Covers
   DevframeDefinition, picking the right deployment adapter
-  (cli / build / spa / vite / embedded / mcp), designing RPC
+  (cli / build / vite / embedded / mcp), designing RPC
   contracts, exposing an agent-native surface over MCP, and
   wiring the author's SPA client. For host-level features (docks,
   terminals, palette, etc.), the devframe can be mounted into a
@@ -85,7 +85,7 @@ export default defineDevframe({
 
 `setup(ctx)` registers RPC functions, shared state, diagnostics, and any other devframe-level wiring. Host adapters can augment `ctx` with extra surfaces - for example, mounting into Vite DevTools via `createPluginFromDevframe(d)` exposes `docks`, `terminals`, `messages`, and `commands` on the augmented context, and the kit auto-derives an iframe dock entry from `id` / `name` / `icon` / `basePath`. For richer host-side behaviour (custom-render, terminals, palette commands) pass `options.setup` to `createPluginFromDevframe`.
 
-See `templates/counter-devframe.ts` for a runnable counter example, `templates/spa-devframe.ts` for an SPA-ready shape, and `templates/vite-client.ts` for the author's client entry.
+See `templates/counter-devframe.ts` for a runnable counter example and `templates/vite-client.ts` for the author's client entry.
 
 ## Scoped context (preferred)
 
@@ -504,7 +504,7 @@ const data = await my.rpc.call('get-stats', { limit: 10 })
 `connectDevframe` auto-detects the backend via `/.devframe/.connection.json`:
 
 - **websocket** (dev mode) - full read/write, requires auth handshake. Listen for token updates on the `devframe-auth` BroadcastChannel.
-- **static** (build / spa output) - read-only, resolves calls from the baked RPC dump.
+- **static** (build output) - read-only, resolves calls from the baked RPC dump.
 
 Use `my.rpc.sharedState(key)` for observable state, `my.rpc.register(defineRpcFunction(...))` to receive server broadcasts, `my.rpc.callOptional(...)` when a missing handler should resolve to `undefined` instead of throwing, and `my.settings.{project,global}` for persisted per-workspace / per-user settings synced from the server.
 
@@ -530,13 +530,12 @@ At runtime, static clients look up the argument hash in the dump; misses resolve
 
 ## CLI adapter subcommands
 
-`createCac(devframe).parse()` gives the tool four subcommands out of the box:
+`createCac(devframe).parse()` gives the tool three subcommands out of the box:
 
 | Subcommand | Action |
 |------------|--------|
 | *(default)* | Dev server on port 9999 (or `--port`) - WebSocket RPC, `cli.distDir` served at `/.devframe/` |
 | `build` | Static snapshot → `./dist-static/` (configurable via `--out-dir`) |
-| `spa` | Deployable SPA → `./dist-spa/` |
 | `mcp` | stdio MCP server |
 
 **Bring your own CLI framework?** `createCac` (`devframe/adapters/cac`) is just a cac wrapper around three peer factories - `createDevServer` (`devframe/adapters/dev`), `createBuild` (`devframe/adapters/build`), and `createMcpServer` (`devframe/adapters/mcp`). Use them directly with commander/yargs/oclif when `createCac`'s baked-in command structure doesn't fit. `cac` is an optional peer dependency pulled in only through `devframe/adapters/cac`, so bring-your-own-CLI tools run without installing it. `createDevServer` returns a `StartedServer` handle (`origin`, `port`, `app`, `wss`, `close()`) so you can wire SIGINT / hot-reload teardown into the surrounding program. `parseCliFlags(schema, raw)` and `defineCliFlags(...)` (both from `devframe/adapters/cac`) validate an arbitrary flag bag against a `CliFlagsSchema` - the helpers are framework-agnostic.