Merge remote-tracking branch 'origin/main' into feat/extract-vite-bridge-package

# Conflicts:
#	examples/hub-next-minimal/src/client/hub.ts
#	examples/hub-vite-minimal/vite.config.ts

Author: antfubot

design/uno.config.ts

@@ -123,3 +123,57 @@ export const shadowSurfaceSafelist: string[] = [
   'color-active',
   'border-base',
 ]
+
+/**
+ * The primary-ramp stops a shadow-root surface's `primary-ramp.css` exposes
+ * as overridable `--colors-primary-<stop>` custom properties (derived from
+ * `--devframe-primary`). Must match that file's declarations exactly.
+ */
+const OVERRIDABLE_PRIMARY_STOPS = ['DEFAULT', '600', '500', '400', '300'] as const
+
+function hexToRgbTriplet(hex: string): string | undefined {
+  const match = /^#([0-9a-f]{6})$/i.exec(hex)
+  if (!match)
+    return undefined
+  const int = Number.parseInt(match[1], 16)
+  return `${(int >> 16) & 255} ${(int >> 8) & 255} ${int & 255}`
+}
+
+/**
+ * Rewire a Wind3-compiled shadow-root stylesheet's baked-in `primary` theme
+ * colors into CSS relative-color syntax reading the live `--colors-primary-*`
+ * variables `primary-ramp.css` derives from `--devframe-primary`.
+ *
+ * Wind3 (unlike Wind4) resolves each theme color to a literal `rgb(r g b /
+ * <alpha>)` at compile time — the `<alpha>` slot is already dynamic (a slash
+ * literal, or the utility's own `--un-*-opacity` variable), but the base `r g
+ * b` triplet is baked in, so every `primary`-based utility (`text-primary`,
+ * `bg-primary`, `btn-primary`, `ring-primary-500`, …) ignores
+ * `--devframe-primary` entirely — only hand-written rules that already
+ * reference `--colors-primary-*` directly (the dock's glow gradient,
+ * `primary-ramp.css` itself) retint. Swapping the baked triplet for `from
+ * var(--colors-primary-<stop>, <hex>) r g b` keeps that exact alpha
+ * mechanism intact while sourcing the base color from the variable — a
+ * rebrand's `--devframe-primary` now reaches every baked utility too.
+ *
+ * Call once per generated pass, after `generator.generate(...)`, passing the
+ * resolved `generator.config.theme.colors.primary` ramp.
+ *
+ * @param css - The compiled Wind3 CSS (pre-`--un-*` namespacing).
+ * @param primaryRamp - The generator's resolved `theme.colors.primary` ramp.
+ */
+export function rewireBakedPrimaryColors(css: string, primaryRamp: Record<string, string>): string {
+  let out = css
+  for (const stop of OVERRIDABLE_PRIMARY_STOPS) {
+    const hex = primaryRamp[stop]
+    const rgb = hex && hexToRgbTriplet(hex)
+    if (!rgb)
+      continue
+    const varName = stop === 'DEFAULT' ? '--colors-primary-DEFAULT' : `--colors-primary-${stop}`
+    out = out.replace(
+      new RegExp(String.raw`rgb\(${rgb}(?!\d)`, 'g'),
+      `rgb(from var(${varName}, ${hex}) r g b`,
+    )
+  }
+  return out
+}

examples/hub-hono-minimal/README.md

@@ -11,7 +11,7 @@ Open <http://localhost:5179> — the host page carries the floating dock via one
 
 ## How it works
 
-- [`src/app.ts`](./src/app.ts) — runtime-agnostic: `initHub({ devframes, ui: createUi() })` plus `app.all('/__devframes/*', c => hub.handler(c.req.raw))`. Everything — frame SPAs, `__connection.json`, `__index.json`, `embedded.js`, `__client-imports.js` — flows through that one route. The instance is memoized on `globalThis` so a dev-time reload reuses the live hub. It configures no WebSocket transport, so each entry below wires the socket its runtime's way; both end up serving `/__devframes/__ws` on the app's own origin, which is what the hub advertises either way.
+- [`src/app.ts`](./src/app.ts) — runtime-agnostic: `initHub({ devframes, ui: createUi({ branding }) })` (rebranded to Hono's own orange, `#e36002`) plus `app.all('/__devframes/*', c => hub.handler(c.req.raw))`. Everything — frame SPAs, `__connection.json`, `__index.json`, `embedded.js`, `__client-imports.js` — flows through that one route. The instance is memoized on `globalThis` so a dev-time reload reuses the live hub. It configures no WebSocket transport, so each entry below wires the socket its runtime's way; both end up serving `/__devframes/__ws` on the app's own origin, which is what the hub advertises either way.
 - [`src/server.ts`](./src/server.ts) — Node: `@hono/node-server`'s `serve()` returns the `node:http` server, and `hub.attach(server)` routes its upgrade events to the shared RPC socket.
 - [`src/bun.ts`](./src/bun.ts) — Bun: upgrades arrive as fetch requests, so this entry binds Bun's own transport to the hub context with `createContextRpcServer` + `attachBunWsTransport` and answers the upgrade route inside `Bun.serve({ fetch, websocket })`.
 

examples/hub-hono-minimal/src/app.ts

@@ -38,7 +38,11 @@ export const hub: HubInstance = globalRef.__hubHonoMinimal ??= initHub({
     createOgDevframe(),
     createAssetsDevframe({ watch: false }),
   ],
-  ui: createUi(),
+  // Rebrand the reference UI to Hono's own orange — one field, no CSS:
+  // `createUi`'s `branding` option publishes `branding.json`, which the dock
+  // fetches at boot and feeds into `--devframe-primary` (see
+  // `@devframes/hub-ui`'s `primary-ramp.css`).
+  ui: createUi({ branding: { primaryColor: '#e36002', productName: 'Devframes on Hono' } }),
   // Single-user localhost demo: reachable only on loopback, so it opts out
   // of the gate for a no-friction dev experience. A hub reachable beyond
   // localhost should gate (see docs/guide/security.md).

examples/hub-next-minimal/src/client/hub.ts

@@ -1,3 +1,4 @@
+import type { createUi as CreateUi } from '@devframes/hub-ui'
 import type { HubInstance } from '@devframes/hub/initiate'
 import type { DevframeJsonRenderSpec } from '@devframes/json-render'
 import type { jsonRenderUiRenderer as JsonRenderUiRenderer } from '@devframes/json-render-ui/hub'
@@ -51,7 +52,8 @@ const BUILTIN_PLUGIN_PACKAGES = [
 ] as const
 
 async function loadHub(): Promise<HubInstance> {
-  const [jsonRenderUi, dataInspector, assets, ...builtins] = await Promise.all([
+  const [hubUi, jsonRenderUi, dataInspector, assets, ...builtins] = await Promise.all([
+    import(/* webpackIgnore: true */ /* turbopackIgnore: true */ '@devframes/hub-ui'),
     import(/* webpackIgnore: true */ /* turbopackIgnore: true */ '@devframes/json-render-ui/hub'),
     import(/* webpackIgnore: true */ /* turbopackIgnore: true */ '@devframes/plugin-data-inspector'),
     import(/* webpackIgnore: true */ /* turbopackIgnore: true */ '@devframes/plugin-assets'),
@@ -69,11 +71,14 @@ async function loadHub(): Promise<HubInstance> {
     (assets.createAssetsDevframe as (options: { watch: boolean }) => DevframeDefinition)({ watch: false }),
   ]
   // `@devframes/next/hub` runs the socket on a side-car (Next routes can't
-  // accept WS upgrades) and defaults the UI to `@devframes/hub-ui` (loaded
-  // through its own bundler-ignored dynamic import) — the minimal host needs
-  // no client code, just the injected `embedded.js`.
+  // accept WS upgrades). This host overrides the default UI slot to rebrand
+  // the reference viewer to Next.js/Vercel's monochrome black — one field, no
+  // CSS: `createUi`'s `branding` option publishes `branding.json`, which the
+  // dock fetches at boot and feeds into `--devframe-primary` (see
+  // `@devframes/hub-ui`'s `primary-ramp.css`).
   return createNextDevframeHub({
     devframes,
+    ui: (hubUi.createUi as typeof CreateUi)({ branding: { primaryColor: '#000000', productName: 'Devframes on Next.js' } }),
     // Serve the reference json-render frontend as a prebuilt renderer module
     // — the one-liner that makes `'json-render'` docks render in the prebuilt
     // viewer. Swap it for any community implementation of the same contract.

examples/hub-nitro-minimal/README.md

@@ -10,7 +10,7 @@ Open <http://localhost:3000> - the host page carries the floating dock via one s
 
 ## How it works
 
-- [`hub.ts`](./hub.ts) - `initHub({ devframes, ui: createUi(), key })`: mounts the Inspect and Messages plugins against one shared hub context, fills the hub's `ui` slot with `@devframes/hub-ui`'s prebuilt viewer + floating-dock bootstrap, and memoizes the instance across Nitro's dev-time module reloads.
+- [`hub.ts`](./hub.ts) - `initHub({ devframes, ui: createUi({ branding }) })`: mounts the Inspect and Messages plugins against one shared hub context, fills the hub's `ui` slot with `@devframes/hub-ui`'s prebuilt viewer + floating-dock bootstrap (rebranded to Nitro's own pink/red, `#ff2056`), and memoizes the instance across Nitro's dev-time module reloads.
 - [`routes/__devframes/[...path].ts`](./routes/__devframes/%5B...path%5D.ts) (and its `index.ts` sibling for the namespace root) - the delegation: every request under `/__devframes/` becomes `hub.handler(event.req)`, web-standard Request in, Response out. Everything - frame SPAs, `__connection.json`, `__index.json`, `embedded.js`, `__client-imports.js` - flows through it.
 - [`nitro.config.ts`](./nitro.config.ts) - keeps the devframe packages external so their prebuilt client assets resolve from the packages themselves rather than Nitro's build output.
 - The RPC WebSocket runs on a side-car port - Nitro handlers hand over `Request`s, so `ws: { sidecar: true }` asks for one - advertised through `__connection.json`; the browser client discovers it automatically.

examples/hub-nitro-minimal/hub.ts

@@ -41,7 +41,11 @@ export const hub: HubInstance = globalRef.__hubNitroMinimal ??= initHub({
     createOgDevframe(),
     createAssetsDevframe({ watch: false }),
   ],
-  ui: createUi(),
+  // Rebrand the reference UI to Nitro's own pink/red — one field, no CSS:
+  // `createUi`'s `branding` option publishes `branding.json`, which the dock
+  // fetches at boot and feeds into `--devframe-primary` (see
+  // `@devframes/hub-ui`'s `primary-ramp.css`).
+  ui: createUi({ branding: { primaryColor: '#ff2056', productName: 'Devframes on Nitro' } }),
   // Single-user localhost demo: reachable only on loopback, so it opts out
   // of the gate for a no-friction dev experience. A hub reachable beyond
   // localhost should gate (see docs/guide/security.md).

examples/hub-rsbuild-minimal/README.md

@@ -12,7 +12,7 @@ Open the printed URL - the host page carries the floating dock via one injected
 
 [`rsbuild.config.ts`](./rsbuild.config.ts) is the entire host:
 
-- `initHub({ devframes: [inspect, messages], ui: createUi() })` runs in Rsbuild's Node config process (never bundled into the browser), so `createUi()`'s prebuilt viewer/dock and the plugins' node code work unchanged.
+- `initHub({ devframes: [inspect, messages], ui: createUi({ branding }) })` runs in Rsbuild's Node config process (never bundled into the browser), so `createUi()`'s prebuilt viewer/dock and the plugins' node code work unchanged. `branding.primaryColor` is Rsbuild's own orange (`#ff5e00`) — a rebrand reaches every `primary`-based color in the dock, no CSS required.
 - `dev.setupMiddlewares` unshifts `hub.nodeMiddleware`, which owns the whole `/__devframes/` namespace and hands everything else back to Rsbuild.
 - The RPC WebSocket runs on a side-car port (`ws: { sidecar: true }`, since Rsbuild's middleware stack never hands over upgrades), advertised through `__connection.json`; the browser client discovers it automatically.
 - `html.tags` injects `<script type="module" src="/__devframes/embedded.js">`, so the floating dock mounts itself.

examples/hub-rsbuild-minimal/rsbuild.config.ts

@@ -76,7 +76,11 @@ export default defineConfig({
       hub ??= initHub({
         base,
         devframes: builtinDevframes,
-        ui: createUi(),
+        // Rebrand the reference UI to Rsbuild's own orange — one field, no
+        // CSS: `createUi`'s `branding` option publishes `branding.json`,
+        // which the dock fetches at boot and feeds into `--devframe-primary`
+        // (see `@devframes/hub-ui`'s `primary-ramp.css`).
+        ui: createUi({ branding: { primaryColor: '#ff5e00', productName: 'Devframes on Rsbuild' } }),
         // Serve the reference json-render frontend as a prebuilt renderer
         // module — the one-liner that makes `'json-render'` docks render in
         // the prebuilt viewer. Swap it for any community implementation of

examples/hub-vite-minimal/README.md

@@ -12,7 +12,7 @@ Open the printed URL - the host page carries the floating dock via one injected
 
 [`vite.config.ts`](./vite.config.ts) is the entire host:
 
-- `initHub({ devframes: [inspect, messages], ui: createUi() })` runs in Vite's Node config process (never bundled into the browser), so `createUi()`'s prebuilt viewer/dock and the plugins' node code work unchanged.
+- `initHub({ devframes: [inspect, messages], ui: createUi({ branding }) })` runs in Vite's Node config process (never bundled into the browser), so `createUi()`'s prebuilt viewer/dock and the plugins' node code work unchanged. `branding.primaryColor` is Vite's own purple (`#646cff`) — a rebrand reaches every `primary`-based color in the dock, no CSS required.
 - `server.middlewares.use(hub.nodeMiddleware)` mounts the whole `/__devframes/` namespace; the middleware self-filters by base and hands everything else back to Vite.
 - The RPC WebSocket shares Vite's own dev server at `/__devframes/__ws` - zero extra ports.
 - `transformIndexHtml` injects `<script type="module" src="/__devframes/embedded.js">` into the host page, so the floating dock mounts itself.

examples/hub-vite-minimal/vite.config.ts

@@ -1,5 +1,6 @@
 import type { DevframeJsonRenderSpec } from '@devframes/json-render'
 import type { DevframeJsonRenderDockEntry } from '@devframes/json-render/hub'
+import { createUi } from '@devframes/hub-ui'
 import { jsonRenderUiRenderer } from '@devframes/json-render-ui/hub'
 import { createA11yDevframe } from '@devframes/plugin-a11y'
 import { createAssetsDevframe } from '@devframes/plugin-assets'
@@ -54,10 +55,9 @@ const jsonRenderDock: DevframeJsonRenderDockEntry = {
 // The minimal Vite host: one `viteDevframeHub()` plugin from
 // `@devframes/vite/hub`. It wraps `initHub` (mounted as connect middleware on
 // Vite's dev server, sharing its HTTP server for the WS upgrade at
-// `/__devframes/__ws`), defaults the dock UI to `@devframes/hub-ui`, and
-// injects its `embedded.js` bootstrap into the host page — the whole embedded
-// integration in one call. `quiet` silences the Vite-DevTools recommendation
-// for this reference example.
+// `/__devframes/__ws`) and injects the UI's `embedded.js` bootstrap into the
+// host page — the whole embedded integration in one call. `quiet` silences the
+// Vite-DevTools recommendation for this reference example.
 export default defineConfig({
   // Dev tooling reached from arbitrary hostnames (LAN IPs, tunnels): accept
   // any Host header and fall back to the next free port when busy.
@@ -66,6 +66,12 @@ export default defineConfig({
     viteDevframeHub({
       quiet: true,
       devframes: builtinDevframes,
+      // Rebrand the reference UI to Vite's own purple — one field, no CSS:
+      // `createUi`'s `branding` option publishes `branding.json`, which the
+      // dock fetches at boot and feeds into `--devframe-primary` (see
+      // `@devframes/hub-ui`'s `primary-ramp.css`). Passing `ui` overrides the
+      // default `createUi()` the plugin would otherwise use.
+      ui: createUi({ branding: { primaryColor: '#646cff', productName: 'Devframes on Vite' } }),
       // Serve the reference json-render frontend as a prebuilt renderer
       // module — the one-liner that makes `'json-render'` docks render in
       // the prebuilt viewer. Swap it for any community implementation of