From 8a34e606c858d036879394ac84960dddc2e3a15e Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 14 Aug 2026 06:45:05 +0000
Subject: [PATCH 1/4] feat(hub-ui): add a dev-served playground with HMR

Mounts a bare, headless hub instance and hub-ui's own DockStandalone/
DockEmbedded straight from source, so the client Vue components hot-reload
during development instead of requiring a build.

Run with `pnpm --filter @devframes/hub-ui dev`.
---
 packages/hub-ui/package.json              |  1 +
 packages/hub-ui/playground/hub-plugin.ts  | 70 ++++++++++++++++++++++
 packages/hub-ui/playground/index.html     | 55 +++++++++++++++++
 packages/hub-ui/playground/main.ts        | 58 ++++++++++++++++++
 packages/hub-ui/playground/seed.ts        | 72 +++++++++++++++++++++++
 packages/hub-ui/playground/vite.config.ts | 27 +++++++++
 packages/hub-ui/tsconfig.json             |  2 +-
 7 files changed, 284 insertions(+), 1 deletion(-)
 create mode 100644 packages/hub-ui/playground/hub-plugin.ts
 create mode 100644 packages/hub-ui/playground/index.html
 create mode 100644 packages/hub-ui/playground/main.ts
 create mode 100644 packages/hub-ui/playground/seed.ts
 create mode 100644 packages/hub-ui/playground/vite.config.ts

diff --git a/packages/hub-ui/package.json b/packages/hub-ui/package.json
index 97c7d15d..1ee1ac3f 100644
--- a/packages/hub-ui/package.json
+++ b/packages/hub-ui/package.json
@@ -34,6 +34,7 @@
     "build:node": "tsdown",
     "build:embedded": "vite build --config vite.embedded.config.ts",
     "build:standalone": "vite build --config src/client/standalone/vite.config.ts",
+    "dev": "pnpm -C ../.. exec turbo run build --filter=@devframes/hub... && vite --config playground/vite.config.ts",
     "typecheck": "tsc --noEmit",
     "prepack": "pnpm build",
     "storybook": "storybook dev -p 6014",
diff --git a/packages/hub-ui/playground/hub-plugin.ts b/packages/hub-ui/playground/hub-plugin.ts
new file mode 100644
index 00000000..bf4ae102
--- /dev/null
+++ b/packages/hub-ui/playground/hub-plugin.ts
@@ -0,0 +1,70 @@
+import type { HubInstance } from '@devframes/hub/initiate'
+import type { Plugin, ViteDevServer } from 'vite'
+import { Server as NodeHttpServer } from 'node:http'
+import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'
+import { seedPlayground } from './seed'
+
+/**
+ * Mounts a bare, headless hub instance as Vite dev-server middleware — just
+ * enough backend for `main.ts`'s `DockStandalone`/`DockEmbedded` to connect
+ * to (RPC, WebSocket, `__connection.json`). No `devframes`, no `ui` slot, no
+ * renderer manifest: this playground is developing hub-ui itself, not
+ * exercising the wider hub protocol (`examples/hub-vite` already does that).
+ *
+ * A hand-rolled slice of `@devframes/vite/hub` rather than that package
+ * itself — pulling it in here would make `@devframes/hub-ui` and
+ * `@devframes/vite` depend on each other (`@devframes/vite` already carries
+ * an optional peer dependency on `@devframes/hub-ui` for its own default UI
+ * slot), a cyclic workspace dependency for no real benefit.
+ */
+export function hubUiPlaygroundHub(): Plugin {
+  let instance: HubInstance | undefined
+
+  const teardown = async (): Promise<void> => {
+    const previous = instance
+    instance = undefined
+    await previous?.close().catch(() => {})
+  }
+
+  return {
+    name: 'hub-ui-playground:hub',
+    apply: 'serve',
+
+    async configureServer(server: ViteDevServer) {
+      // Vite re-invokes `configureServer` on each restart.
+      await teardown()
+
+      const httpServer = server.httpServer instanceof NodeHttpServer ? server.httpServer : undefined
+      const hub = initHub({
+        base: DEVFRAMES_HUB_BASE,
+        // Storage (if anything writes to it) lands under this package's own
+        // `node_modules`, not the playground folder.
+        cwd: new URL('..', import.meta.url).pathname,
+        origin: () => {
+          const resolved = server.resolvedUrls?.local?.[0]
+          return resolved ? new URL(resolved).origin : ''
+        },
+        // Frictionless local loop — no interactive OTP gate.
+        auth: false,
+        // Share Vite's own HTTP server for the WS upgrade, like
+        // `@devframes/vite/hub` does.
+        server: httpServer,
+        ...(httpServer ? {} : { ws: { sidecar: true } }),
+        configure: seedPlayground,
+      })
+      instance = hub
+
+      server.middlewares.use(hub.nodeMiddleware)
+
+      server.httpServer?.once('close', () => {
+        if (instance !== hub)
+          return
+        void teardown()
+      })
+    },
+
+    async closeBundle() {
+      await teardown()
+    },
+  }
+}
diff --git a/packages/hub-ui/playground/index.html b/packages/hub-ui/playground/index.html
new file mode 100644
index 00000000..b584c783
--- /dev/null
+++ b/packages/hub-ui/playground/index.html
@@ -0,0 +1,55 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>hub-ui playground</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+        background: #fff;
+        font-family: system-ui, sans-serif;
+      }
+      html.dark,
+      html.dark body {
+        background: #111;
+        color: #eee;
+      }
+      /* `main.ts` marks the mode on `<body>` before mounting — `#app` only
+         needs to fill the viewport in standalone mode (where `DockStandalone`
+         mounts into it); in embedded mode it stays empty and out of the way,
+         leaving `#host-content` visible under the floating dock. */
+      body.standalone #app {
+        height: 100%;
+      }
+      #host-content {
+        max-width: 40rem;
+        margin: 4rem auto;
+        padding: 0 1.5rem;
+        line-height: 1.6;
+      }
+    </style>
+  </head>
+  <body>
+    <!--
+      Standalone mode (default) mounts `DockStandalone` into `#app`, filling
+      the page — this content sits underneath it, unused.
+
+      `?embedded` instead leaves this content visible and floats
+      `DockEmbedded` over it, standing in for a host app the dock is
+      inspecting.
+    -->
+    <div id="app"></div>
+    <div id="host-content">
+      <h1>hub-ui playground</h1>
+      <p>
+        A sample host page. Load with <code>?embedded</code> to see the
+        floating dock (<code>DockEmbedded</code>) over this content instead
+        of the full-page standalone viewer (<code>DockStandalone</code>).
+      </p>
+    </div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>
diff --git a/packages/hub-ui/playground/main.ts b/packages/hub-ui/playground/main.ts
new file mode 100644
index 00000000..24db58dc
--- /dev/null
+++ b/packages/hub-ui/playground/main.ts
@@ -0,0 +1,58 @@
+import type { DockPanelStorage } from '@devframes/hub/client'
+import { getDevframeRpcClient, setDevframeClientContext } from '@devframes/hub/client'
+import { useLocalStorage } from '@vueuse/core'
+import { watchEffect } from 'vue'
+import { isDark } from '../src/client/state/color-mode'
+import { DEFAULT_DOCK_PANEL_STORE } from '../src/client/state/docks'
+
+/**
+ * The base `hub-plugin.ts` mounts the playground's hub instance at. Kept as
+ * an explicit constant (rather than inferred from the page's own URL, like
+ * the production `standalone`/`embedded` entries do) because this playground
+ * page is served from Vite's own root (`/`), not colocated with the hub the
+ * way a built `createUi()` viewer is.
+ */
+const HUB_BASE = '/__devframes/'
+
+/**
+ * `?embedded` mounts the floating `DockEmbedded` bootstrap over the sample
+ * host content in `index.html` — the same surface a host page gets from
+ * `<script src="<base>embedded.js">`. The default mounts `DockStandalone`
+ * full-page — the primary surface most hub-ui changes touch.
+ */
+const mode = new URLSearchParams(location.search).has('embedded') ? 'embedded' : 'standalone'
+document.body.classList.add(mode)
+
+// This page runs in the light DOM, so mirror the color mode onto the
+// document element like the standalone viewer does.
+watchEffect(() => {
+  const el = document.documentElement
+  el.classList.toggle('dark', isDark.value)
+  el.classList.toggle('light', !isDark.value)
+  el.style.colorScheme = isDark.value ? 'dark' : 'light'
+})
+
+async function main(): Promise<void> {
+  const rpc = await getDevframeRpcClient({ baseURL: HUB_BASE, simpleAuth: false })
+  const { createDocksContext } = await import('../src/client/state/context')
+
+  if (mode === 'embedded') {
+    const state = useLocalStorage<DockPanelStorage>(
+      'devframes-hub-ui-playground-dock-state',
+      DEFAULT_DOCK_PANEL_STORE(),
+      { mergeDefaults: true },
+    )
+    const context = await createDocksContext('embedded', rpc, state)
+    setDevframeClientContext(context)
+    const { DockEmbedded } = await import('../src/client/components/DockEmbedded')
+    document.body.appendChild(new DockEmbedded({ context }) as unknown as HTMLElement)
+    return
+  }
+
+  const context = await createDocksContext('standalone', rpc)
+  setDevframeClientContext(context)
+  const { DockStandalone } = await import('../src/client/components/DockStandalone')
+  document.getElementById('app')!.appendChild(new DockStandalone({ context }) as unknown as HTMLElement)
+}
+
+void main()
diff --git a/packages/hub-ui/playground/seed.ts b/packages/hub-ui/playground/seed.ts
new file mode 100644
index 00000000..d4088341
--- /dev/null
+++ b/packages/hub-ui/playground/seed.ts
@@ -0,0 +1,72 @@
+import type { DevframeHubContext } from '@devframes/hub/node'
+import type { DevframeDockEntryBase } from '@devframes/hub/types'
+
+/**
+ * A dock type no renderer covers — registering it exercises the viewer's
+ * fallback view (`No renderer for "playground-unrendered" in the current
+ * environment`) instead of leaving the dock bar empty. Mirrors
+ * `examples/hub-vite/src/unrendered-dock.ts`.
+ */
+interface PlaygroundUnrenderedDockEntry extends DevframeDockEntryBase {
+  type: 'playground-unrendered'
+}
+
+declare module '@devframes/hub/types' {
+  interface DevframeDockEntryRegistry {
+    'playground-unrendered': PlaygroundUnrenderedDockEntry
+  }
+}
+
+const unrenderedDockEntry: PlaygroundUnrenderedDockEntry = {
+  type: 'playground-unrendered',
+  id: 'playground:unrendered',
+  title: 'No Renderer',
+  icon: 'ph:puzzle-piece-duotone',
+  category: 'app',
+}
+
+/**
+ * Seeds the playground's hub context with just enough content to exercise
+ * hub-ui's own surfaces — the dock bar, message center, and command palette —
+ * without needing a real mounted devframe SPA. Called from `hub-plugin.ts`'s
+ * `configure` hook once the context exists.
+ */
+export async function seedPlayground(ctx: DevframeHubContext): Promise<void> {
+  ctx.docks.register(unrenderedDockEntry)
+
+  ctx.commands.register({
+    id: 'playground:say-hello',
+    title: 'Playground · Say Hello',
+    icon: 'ph:hand-waving-duotone',
+    category: 'playground',
+    handler: () => 'Hello from the hub-ui playground!',
+  })
+  ctx.commands.register({
+    id: 'playground:throw',
+    title: 'Playground · Throw an Error',
+    icon: 'ph:bomb-duotone',
+    category: 'playground',
+    handler: () => {
+      throw new Error('Deliberate playground error — exercises the command palette\'s failure toast.')
+    },
+  })
+
+  await ctx.messages.add({
+    level: 'info',
+    message: 'Hub UI playground started',
+    description: 'Editing anything under packages/hub-ui/src/client hot-reloads this page.',
+  })
+  await ctx.messages.add({
+    level: 'success',
+    message: 'Sample success message',
+  })
+  await ctx.messages.add({
+    level: 'warn',
+    message: 'Sample warning message',
+    description: 'Messages support an optional description line like this one.',
+  })
+  await ctx.messages.add({
+    level: 'error',
+    message: 'Sample error message',
+  })
+}
diff --git a/packages/hub-ui/playground/vite.config.ts b/packages/hub-ui/playground/vite.config.ts
new file mode 100644
index 00000000..3d73f592
--- /dev/null
+++ b/packages/hub-ui/playground/vite.config.ts
@@ -0,0 +1,27 @@
+import { fileURLToPath } from 'node:url'
+import Vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vite'
+import { alias } from '../../../alias'
+import { hubUiPlaygroundHub } from './hub-plugin'
+
+/**
+ * Dev-serves this package's own client source (the floating `DockEmbedded`
+ * bootstrap and the standalone `DockStandalone` viewer) against a real,
+ * local hub instance — full HMR on every `.vue`/`.ts` file under
+ * `src/client`, no build step. Run with `pnpm --filter @devframes/hub-ui dev`.
+ *
+ * `main.ts` mounts `DockStandalone`/`DockEmbedded` straight from source, the
+ * same way a built `createUi()` viewer would, just unbundled — see
+ * `hub-plugin.ts` for why this doesn't reuse `@devframes/vite/hub`.
+ */
+export default defineConfig({
+  root: fileURLToPath(new URL('.', import.meta.url)),
+  resolve: { alias },
+  // Reached from arbitrary hostnames (LAN IPs, tunnels, tailnets) like the
+  // other reference hub hosts in this repo.
+  server: { allowedHosts: true, strictPort: false },
+  plugins: [
+    Vue(),
+    hubUiPlaygroundHub(),
+  ],
+})
diff --git a/packages/hub-ui/tsconfig.json b/packages/hub-ui/tsconfig.json
index aaf1e9d9..8d95328a 100644
--- a/packages/hub-ui/tsconfig.json
+++ b/packages/hub-ui/tsconfig.json
@@ -6,6 +6,6 @@
     "lib": ["esnext", "dom", "dom.iterable"],
     "types": ["vite/client"]
   },
-  "include": ["src", "scripts", "*.config.ts"],
+  "include": ["src", "scripts", "playground", "*.config.ts"],
   "exclude": ["dist", "node_modules"]
 }

From e30c5c738b2bb0771675bfadc1f03b357f1ed9cd Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 14 Aug 2026 06:45:28 +0000
Subject: [PATCH 2/4] fix(hub-ui): apply the Tailwind preflight reset in
 storybook

Storybook's preview never imported '@unocss/reset/tailwind.css', the same
reset scripts/build-css.ts prepends to the shipped shadow-root stylesheet -
unlike real dock content, stories inherited raw browser defaults (e.g. a
text-variant ActionButton rendering as a native gray button). Import it
first, matching the production build's [reset, ...] order.
---
 packages/hub-ui/.storybook/preview.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/packages/hub-ui/.storybook/preview.ts b/packages/hub-ui/.storybook/preview.ts
index 3bcac0a0..b91bddd3 100644
--- a/packages/hub-ui/.storybook/preview.ts
+++ b/packages/hub-ui/.storybook/preview.ts
@@ -1,4 +1,11 @@
 import type { Decorator, Preview } from '@storybook/vue3-vite'
+// The same Tailwind preflight `scripts/build-css.ts` prepends to the shipped
+// shadow-root stylesheet — first, so `virtual:uno.css`'s utilities (and the
+// hand-written `style.css`) win over its resets, matching the production
+// build's `[reset, userStyle, unoCss, ...]` order. Without it, stories miss
+// the reset (unstyled default `<button>`/`<ul>`/heading margins, …) real
+// dock content never shows once mounted in its actual shadow root.
+import '@unocss/reset/tailwind.css'
 import 'virtual:uno.css'
 import '@antfu/design/styles.css'
 import '../src/client/style.css'

From dabe215fa567c758e220c8a40d54ef98143144e4 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 14 Aug 2026 07:07:45 +0000
Subject: [PATCH 3/4] feat(hub-ui): mount devframes, an action dock, and a
 group in the playground

Mounts two tiny static devframes (Alpha/Beta, devframes.ts) via initHub's
devframes option, so the playground's dock bar has real mounted content
to switch between rather than only client-only entries. Both collapse
under a new "Playground Tools" group dock, alongside a "Ping" action dock
whose client script runs on click - exercising the grouped-dock popover
and the action-dock mechanism the playground didn't previously touch.

Declares playground/client-scripts/*.ts as a knip entry - action dock
scripts are loaded by their runtime URL string, not a static import.
---
 knip.jsonc                                    |  7 ++++
 .../playground/client-scripts/ping-action.ts  | 23 +++++++++++
 packages/hub-ui/playground/constants.ts       |  7 ++++
 packages/hub-ui/playground/devframes.ts       | 40 +++++++++++++++++++
 .../playground/devframes/alpha/index.html     | 30 ++++++++++++++
 .../playground/devframes/beta/index.html      | 30 ++++++++++++++
 packages/hub-ui/playground/hub-plugin.ts      | 17 ++++++--
 packages/hub-ui/playground/seed.ts            | 35 ++++++++++++++++
 8 files changed, 186 insertions(+), 3 deletions(-)
 create mode 100644 packages/hub-ui/playground/client-scripts/ping-action.ts
 create mode 100644 packages/hub-ui/playground/constants.ts
 create mode 100644 packages/hub-ui/playground/devframes.ts
 create mode 100644 packages/hub-ui/playground/devframes/alpha/index.html
 create mode 100644 packages/hub-ui/playground/devframes/beta/index.html

diff --git a/knip.jsonc b/knip.jsonc
index 8c8e7573..4c66d4e7 100644
--- a/knip.jsonc
+++ b/knip.jsonc
@@ -107,6 +107,13 @@
     "packages/hub": {
       "entry": ["src/{index,constants}.ts", "src/{client,node,types}/index.ts", "src/node/{index,initiate}.ts"]
     },
+    "packages/hub-ui": {
+      // `playground/client-scripts/*.ts` are dock `action` entries the
+      // playground's `seed.ts` points at by their runtime URL string
+      // (`action.importFrom`), not a static import knip's graph can see —
+      // the same shape as a devframe's `clientScript`/`clientScripts` entry.
+      "entry": ["playground/client-scripts/*.ts"]
+    },
     "packages/json-render": {
       // `src/node/index.ts` is already picked up via `tsdown.config.ts`
       // (its literal `entry` object parses cleanly); only `core.ts`/`hub.ts`
diff --git a/packages/hub-ui/playground/client-scripts/ping-action.ts b/packages/hub-ui/playground/client-scripts/ping-action.ts
new file mode 100644
index 00000000..f68e08e1
--- /dev/null
+++ b/packages/hub-ui/playground/client-scripts/ping-action.ts
@@ -0,0 +1,23 @@
+import type { DockClientScriptContext } from '@devframes/hub/client'
+
+/**
+ * The "Ping" action dock's client script — `seed.ts` points its `action`
+ * entry at this file's dev URL (served straight from the playground's own
+ * Vite root, no build). Actions re-run their script on every click (see
+ * `executeSetupScript`), so each click posts a fresh message.
+ *
+ * `messages.add` writes over the hub's built-in `hub:messages:add` RPC (it
+ * always exists), so this succeeds — but nothing renders it: the message
+ * feed / toasts read back through `devframes:plugin:messages:list`, which
+ * only `@devframes/plugin-messages` registers, and this playground doesn't
+ * mount it (its SPA needs a build, which would need this very package's own
+ * dist — see `hub-plugin.ts`'s doc comment). Confirm a click ran by watching
+ * the network tab for `client-scripts/ping-action.ts`, or breakpoint here.
+ */
+export default async function ping(context: DockClientScriptContext): Promise<void> {
+  await context.messages.add({
+    level: 'success',
+    message: 'Pong!',
+    description: 'The "Ping" action dock ran its client script just now.',
+  })
+}
diff --git a/packages/hub-ui/playground/constants.ts b/packages/hub-ui/playground/constants.ts
new file mode 100644
index 00000000..37059630
--- /dev/null
+++ b/packages/hub-ui/playground/constants.ts
@@ -0,0 +1,7 @@
+/**
+ * Shared between `devframes.ts` (the group's iframe members) and `seed.ts`
+ * (the group entry itself and its action member) — a group entry and its
+ * members are separate `docks.register()` calls that only line up through
+ * this matching `groupId`.
+ */
+export const PLAYGROUND_GROUP_ID = 'playground-tools'
diff --git a/packages/hub-ui/playground/devframes.ts b/packages/hub-ui/playground/devframes.ts
new file mode 100644
index 00000000..0c2edad2
--- /dev/null
+++ b/packages/hub-ui/playground/devframes.ts
@@ -0,0 +1,40 @@
+import type { DevframeHubContext } from '@devframes/hub/node'
+import { fileURLToPath } from 'node:url'
+import { defineDevframe } from 'devframe'
+import pkg from '../package.json' with { type: 'json' }
+
+/**
+ * Two tiny static devframes — proving the playground's hub instance mounts
+ * real devframes (`ctx.install` under the hood, via `initHub({ devframes })`),
+ * not just the client-only dock entries `seed.ts` registers directly. Each is
+ * a single static `index.html` (`devframes/<dir>/`), no build step.
+ *
+ * `hub-plugin.ts` mounts both with `dock: { groupId: PLAYGROUND_GROUP_ID }`,
+ * collapsing them under the "Playground Tools" group `seed.ts` registers.
+ */
+function createPlaygroundDevframe(id: string, name: string, dir: string) {
+  return defineDevframe({
+    id,
+    name,
+    version: pkg.version,
+    packageName: pkg.name,
+    homepage: pkg.homepage,
+    description: `A tiny static devframe ("${name}") mounted by the hub-ui playground.`,
+    icon: 'ph:flask-duotone',
+    basePath: `/__${id}/`,
+    cli: {
+      distDir: fileURLToPath(new URL(`./devframes/${dir}/`, import.meta.url)),
+    },
+    async setup(rawCtx) {
+      const ctx = rawCtx as unknown as DevframeHubContext
+      await ctx.messages.add({
+        level: 'info',
+        message: `${name} devframe mounted`,
+        description: 'Registered via the hub `devframes` list, like a real integration would be.',
+      })
+    },
+  })
+}
+
+export const playgroundAlphaDevframe = createPlaygroundDevframe('playground-alpha', 'Alpha', 'alpha')
+export const playgroundBetaDevframe = createPlaygroundDevframe('playground-beta', 'Beta', 'beta')
diff --git a/packages/hub-ui/playground/devframes/alpha/index.html b/packages/hub-ui/playground/devframes/alpha/index.html
new file mode 100644
index 00000000..a7af2b7d
--- /dev/null
+++ b/packages/hub-ui/playground/devframes/alpha/index.html
@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Playground · Alpha</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+        background: #10140f;
+        color: #d7e3cd;
+        font-family: system-ui, sans-serif;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        text-align: center;
+      }
+      h1 {
+        color: #8fbc74;
+      }
+    </style>
+  </head>
+  <body>
+    <div>
+      <h1>Alpha</h1>
+      <p>A real devframe, mounted by <code>hub-plugin.ts</code> and grouped under "Playground Tools".</p>
+    </div>
+  </body>
+</html>
diff --git a/packages/hub-ui/playground/devframes/beta/index.html b/packages/hub-ui/playground/devframes/beta/index.html
new file mode 100644
index 00000000..f4bdc63a
--- /dev/null
+++ b/packages/hub-ui/playground/devframes/beta/index.html
@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Playground · Beta</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+        background: #12111a;
+        color: #d9d5ec;
+        font-family: system-ui, sans-serif;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        text-align: center;
+      }
+      h1 {
+        color: #9c8fe0;
+      }
+    </style>
+  </head>
+  <body>
+    <div>
+      <h1>Beta</h1>
+      <p>A second devframe sharing the "Playground Tools" group with Alpha.</p>
+    </div>
+  </body>
+</html>
diff --git a/packages/hub-ui/playground/hub-plugin.ts b/packages/hub-ui/playground/hub-plugin.ts
index bf4ae102..e1581630 100644
--- a/packages/hub-ui/playground/hub-plugin.ts
+++ b/packages/hub-ui/playground/hub-plugin.ts
@@ -2,14 +2,19 @@ import type { HubInstance } from '@devframes/hub/initiate'
 import type { Plugin, ViteDevServer } from 'vite'
 import { Server as NodeHttpServer } from 'node:http'
 import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'
+import { PLAYGROUND_GROUP_ID } from './constants'
+import { playgroundAlphaDevframe, playgroundBetaDevframe } from './devframes'
 import { seedPlayground } from './seed'
 
 /**
  * Mounts a bare, headless hub instance as Vite dev-server middleware — just
  * enough backend for `main.ts`'s `DockStandalone`/`DockEmbedded` to connect
- * to (RPC, WebSocket, `__connection.json`). No `devframes`, no `ui` slot, no
- * renderer manifest: this playground is developing hub-ui itself, not
- * exercising the wider hub protocol (`examples/hub-vite` already does that).
+ * to (RPC, WebSocket, `__connection.json`), plus two tiny static devframes
+ * (`devframes.ts`) so the dock bar has real mounted content to switch
+ * between, not just the client-only entries `seed.ts` registers. No `ui`
+ * slot, no renderer manifest: this playground is developing hub-ui itself,
+ * not exercising the wider hub protocol (`examples/hub-vite` already does
+ * that).
  *
  * A hand-rolled slice of `@devframes/vite/hub` rather than that package
  * itself — pulling it in here would make `@devframes/hub-ui` and
@@ -50,6 +55,12 @@ export function hubUiPlaygroundHub(): Plugin {
         // `@devframes/vite/hub` does.
         server: httpServer,
         ...(httpServer ? {} : { ws: { sidecar: true } }),
+        // Collapsed under the "Playground Tools" group `seed.ts`'s
+        // `configure` registers below, alongside the "Ping" action.
+        devframes: [
+          { devframe: playgroundAlphaDevframe, dock: { groupId: PLAYGROUND_GROUP_ID } },
+          { devframe: playgroundBetaDevframe, dock: { groupId: PLAYGROUND_GROUP_ID } },
+        ],
         configure: seedPlayground,
       })
       instance = hub
diff --git a/packages/hub-ui/playground/seed.ts b/packages/hub-ui/playground/seed.ts
index d4088341..2cc4ca06 100644
--- a/packages/hub-ui/playground/seed.ts
+++ b/packages/hub-ui/playground/seed.ts
@@ -1,5 +1,7 @@
+import type { DevframeViewAction, DevframeViewGroup } from '@devframes/hub'
 import type { DevframeHubContext } from '@devframes/hub/node'
 import type { DevframeDockEntryBase } from '@devframes/hub/types'
+import { PLAYGROUND_GROUP_ID } from './constants'
 
 /**
  * A dock type no renderer covers — registering it exercises the viewer's
@@ -25,6 +27,37 @@ const unrenderedDockEntry: PlaygroundUnrenderedDockEntry = {
   category: 'app',
 }
 
+/**
+ * The dock-bar button collapsing the Alpha/Beta devframes (grouped by
+ * `hub-plugin.ts`'s `devframes` entries) and the "Ping" action below —
+ * exercises the grouped-dock UI (`DockGroupButton`/`DockGroupPopover`) the
+ * playground otherwise never touches.
+ */
+const playgroundGroup: DevframeViewGroup = {
+  type: 'group',
+  id: PLAYGROUND_GROUP_ID,
+  title: 'Playground Tools',
+  icon: 'ph:flask-duotone',
+  category: 'app',
+  // No `defaultChildId` — clicking reveals the member popover instead of
+  // jumping straight to one, exercising that UI too (`DockGroupPopover`).
+}
+
+/**
+ * A one-shot action dock — no panel of its own, just a client script
+ * (`client-scripts/ping-action.ts`) the viewer imports and runs on click.
+ * Grouped alongside the Alpha/Beta devframes above.
+ */
+const pingAction: DevframeViewAction = {
+  type: 'action',
+  id: 'playground:ping',
+  title: 'Ping',
+  icon: 'ph:hand-waving-duotone',
+  category: 'app',
+  groupId: PLAYGROUND_GROUP_ID,
+  action: { importFrom: '/client-scripts/ping-action.ts' },
+}
+
 /**
  * Seeds the playground's hub context with just enough content to exercise
  * hub-ui's own surfaces — the dock bar, message center, and command palette —
@@ -33,6 +66,8 @@ const unrenderedDockEntry: PlaygroundUnrenderedDockEntry = {
  */
 export async function seedPlayground(ctx: DevframeHubContext): Promise<void> {
   ctx.docks.register(unrenderedDockEntry)
+  ctx.docks.register(playgroundGroup)
+  ctx.docks.register(pingAction)
 
   ctx.commands.register({
     id: 'playground:say-hello',

From 47b3ab8851d38b85f2b95e7feb5492bc07622efc Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 14 Aug 2026 07:21:48 +0000
Subject: [PATCH 4/4] feat(hub-ui): mount the real Git devframe in the
 playground

Replaces the two hand-rolled static "Alpha"/"Beta" devframes with the real
`@devframes/plugin-git` dashboard - the playground now shows this very
checkout's actual commit history, branches, and status instead of placeholder
pages.

`@devframes/plugin-git` is the one built-in plugin that doesn't itself depend
on `@devframes/vite` - every other plugin does, and mounting one of those here
would reintroduce the cyclic workspace dependency `hub-plugin.ts` already
avoids by hand-rolling its hub middleware, just one hop further out.
---
 packages/hub-ui/package.json                  |  3 +-
 packages/hub-ui/playground/devframes.ts       | 40 -------------------
 .../playground/devframes/alpha/index.html     | 30 --------------
 .../playground/devframes/beta/index.html      | 30 --------------
 packages/hub-ui/playground/hub-plugin.ts      | 28 ++++++++-----
 packages/hub-ui/playground/seed.ts            |  6 +--
 pnpm-lock.yaml                                |  3 ++
 7 files changed, 26 insertions(+), 114 deletions(-)
 delete mode 100644 packages/hub-ui/playground/devframes.ts
 delete mode 100644 packages/hub-ui/playground/devframes/alpha/index.html
 delete mode 100644 packages/hub-ui/playground/devframes/beta/index.html

diff --git a/packages/hub-ui/package.json b/packages/hub-ui/package.json
index 1ee1ac3f..c5a385d7 100644
--- a/packages/hub-ui/package.json
+++ b/packages/hub-ui/package.json
@@ -34,7 +34,7 @@
     "build:node": "tsdown",
     "build:embedded": "vite build --config vite.embedded.config.ts",
     "build:standalone": "vite build --config src/client/standalone/vite.config.ts",
-    "dev": "pnpm -C ../.. exec turbo run build --filter=@devframes/hub... && vite --config playground/vite.config.ts",
+    "dev": "pnpm -C ../.. exec turbo run build --filter=@devframes/hub... --filter=@devframes/plugin-git... && vite --config playground/vite.config.ts",
     "typecheck": "tsc --noEmit",
     "prepack": "pnpm build",
     "storybook": "storybook dev -p 6014",
@@ -49,6 +49,7 @@
     "@antfu/design": "catalog:frontend",
     "@devframes/hub": "workspace:*",
     "@devframes/json-render": "workspace:*",
+    "@devframes/plugin-git": "workspace:*",
     "@iconify-json/ph": "catalog:frontend",
     "@storybook/addon-docs": "catalog:storybook",
     "@storybook/vue3-vite": "catalog:storybook",
diff --git a/packages/hub-ui/playground/devframes.ts b/packages/hub-ui/playground/devframes.ts
deleted file mode 100644
index 0c2edad2..00000000
--- a/packages/hub-ui/playground/devframes.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import type { DevframeHubContext } from '@devframes/hub/node'
-import { fileURLToPath } from 'node:url'
-import { defineDevframe } from 'devframe'
-import pkg from '../package.json' with { type: 'json' }
-
-/**
- * Two tiny static devframes — proving the playground's hub instance mounts
- * real devframes (`ctx.install` under the hood, via `initHub({ devframes })`),
- * not just the client-only dock entries `seed.ts` registers directly. Each is
- * a single static `index.html` (`devframes/<dir>/`), no build step.
- *
- * `hub-plugin.ts` mounts both with `dock: { groupId: PLAYGROUND_GROUP_ID }`,
- * collapsing them under the "Playground Tools" group `seed.ts` registers.
- */
-function createPlaygroundDevframe(id: string, name: string, dir: string) {
-  return defineDevframe({
-    id,
-    name,
-    version: pkg.version,
-    packageName: pkg.name,
-    homepage: pkg.homepage,
-    description: `A tiny static devframe ("${name}") mounted by the hub-ui playground.`,
-    icon: 'ph:flask-duotone',
-    basePath: `/__${id}/`,
-    cli: {
-      distDir: fileURLToPath(new URL(`./devframes/${dir}/`, import.meta.url)),
-    },
-    async setup(rawCtx) {
-      const ctx = rawCtx as unknown as DevframeHubContext
-      await ctx.messages.add({
-        level: 'info',
-        message: `${name} devframe mounted`,
-        description: 'Registered via the hub `devframes` list, like a real integration would be.',
-      })
-    },
-  })
-}
-
-export const playgroundAlphaDevframe = createPlaygroundDevframe('playground-alpha', 'Alpha', 'alpha')
-export const playgroundBetaDevframe = createPlaygroundDevframe('playground-beta', 'Beta', 'beta')
diff --git a/packages/hub-ui/playground/devframes/alpha/index.html b/packages/hub-ui/playground/devframes/alpha/index.html
deleted file mode 100644
index a7af2b7d..00000000
--- a/packages/hub-ui/playground/devframes/alpha/index.html
+++ /dev/null
@@ -1,30 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>Playground · Alpha</title>
-    <style>
-      html,
-      body {
-        margin: 0;
-        height: 100%;
-        background: #10140f;
-        color: #d7e3cd;
-        font-family: system-ui, sans-serif;
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        text-align: center;
-      }
-      h1 {
-        color: #8fbc74;
-      }
-    </style>
-  </head>
-  <body>
-    <div>
-      <h1>Alpha</h1>
-      <p>A real devframe, mounted by <code>hub-plugin.ts</code> and grouped under "Playground Tools".</p>
-    </div>
-  </body>
-</html>
diff --git a/packages/hub-ui/playground/devframes/beta/index.html b/packages/hub-ui/playground/devframes/beta/index.html
deleted file mode 100644
index f4bdc63a..00000000
--- a/packages/hub-ui/playground/devframes/beta/index.html
+++ /dev/null
@@ -1,30 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>Playground · Beta</title>
-    <style>
-      html,
-      body {
-        margin: 0;
-        height: 100%;
-        background: #12111a;
-        color: #d9d5ec;
-        font-family: system-ui, sans-serif;
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        text-align: center;
-      }
-      h1 {
-        color: #9c8fe0;
-      }
-    </style>
-  </head>
-  <body>
-    <div>
-      <h1>Beta</h1>
-      <p>A second devframe sharing the "Playground Tools" group with Alpha.</p>
-    </div>
-  </body>
-</html>
diff --git a/packages/hub-ui/playground/hub-plugin.ts b/packages/hub-ui/playground/hub-plugin.ts
index e1581630..297018e1 100644
--- a/packages/hub-ui/playground/hub-plugin.ts
+++ b/packages/hub-ui/playground/hub-plugin.ts
@@ -2,25 +2,31 @@ import type { HubInstance } from '@devframes/hub/initiate'
 import type { Plugin, ViteDevServer } from 'vite'
 import { Server as NodeHttpServer } from 'node:http'
 import { DEVFRAMES_HUB_BASE, initHub } from '@devframes/hub/initiate'
+import gitDevframe from '@devframes/plugin-git'
 import { PLAYGROUND_GROUP_ID } from './constants'
-import { playgroundAlphaDevframe, playgroundBetaDevframe } from './devframes'
 import { seedPlayground } from './seed'
 
 /**
  * Mounts a bare, headless hub instance as Vite dev-server middleware — just
  * enough backend for `main.ts`'s `DockStandalone`/`DockEmbedded` to connect
- * to (RPC, WebSocket, `__connection.json`), plus two tiny static devframes
- * (`devframes.ts`) so the dock bar has real mounted content to switch
- * between, not just the client-only entries `seed.ts` registers. No `ui`
- * slot, no renderer manifest: this playground is developing hub-ui itself,
- * not exercising the wider hub protocol (`examples/hub-vite` already does
- * that).
+ * to (RPC, WebSocket, `__connection.json`), plus a real mounted devframe (the
+ * Git dashboard, below) so the dock bar has real content to switch between,
+ * not just the client-only entries `seed.ts` registers. No `ui` slot, no
+ * renderer manifest: this playground is developing hub-ui itself, not
+ * exercising the wider hub protocol (`examples/hub-vite` already does that).
  *
  * A hand-rolled slice of `@devframes/vite/hub` rather than that package
  * itself — pulling it in here would make `@devframes/hub-ui` and
  * `@devframes/vite` depend on each other (`@devframes/vite` already carries
  * an optional peer dependency on `@devframes/hub-ui` for its own default UI
  * slot), a cyclic workspace dependency for no real benefit.
+ *
+ * `@devframes/plugin-git` is the one built-in plugin that doesn't itself
+ * depend on `@devframes/vite` (every other plugin does, for its own
+ * dev-spa/build tooling) — mounting any of those here would reintroduce the
+ * same cyclic dependency `@devframes/vite/hub` avoids, just one hop further
+ * out (hub-ui → that plugin → `@devframes/vite` → hub-ui again, via its peer
+ * dependency).
  */
 export function hubUiPlaygroundHub(): Plugin {
   let instance: HubInstance | undefined
@@ -56,10 +62,12 @@ export function hubUiPlaygroundHub(): Plugin {
         server: httpServer,
         ...(httpServer ? {} : { ws: { sidecar: true } }),
         // Collapsed under the "Playground Tools" group `seed.ts`'s
-        // `configure` registers below, alongside the "Ping" action.
+        // `configure` registers below, alongside the "Ping" action. Read-only
+        // (`write` stays unset) — this is a throwaway dev loop, not somewhere
+        // to stage/commit from. Inspects this very checkout: `cwd` above is
+        // this package's own directory.
         devframes: [
-          { devframe: playgroundAlphaDevframe, dock: { groupId: PLAYGROUND_GROUP_ID } },
-          { devframe: playgroundBetaDevframe, dock: { groupId: PLAYGROUND_GROUP_ID } },
+          { devframe: gitDevframe, dock: { groupId: PLAYGROUND_GROUP_ID } },
         ],
         configure: seedPlayground,
       })
diff --git a/packages/hub-ui/playground/seed.ts b/packages/hub-ui/playground/seed.ts
index 2cc4ca06..4c63e8c1 100644
--- a/packages/hub-ui/playground/seed.ts
+++ b/packages/hub-ui/playground/seed.ts
@@ -28,8 +28,8 @@ const unrenderedDockEntry: PlaygroundUnrenderedDockEntry = {
 }
 
 /**
- * The dock-bar button collapsing the Alpha/Beta devframes (grouped by
- * `hub-plugin.ts`'s `devframes` entries) and the "Ping" action below —
+ * The dock-bar button collapsing the Git devframe (grouped by
+ * `hub-plugin.ts`'s `devframes` entry) and the "Ping" action below —
  * exercises the grouped-dock UI (`DockGroupButton`/`DockGroupPopover`) the
  * playground otherwise never touches.
  */
@@ -46,7 +46,7 @@ const playgroundGroup: DevframeViewGroup = {
 /**
  * A one-shot action dock — no panel of its own, just a client script
  * (`client-scripts/ping-action.ts`) the viewer imports and runs on click.
- * Grouped alongside the Alpha/Beta devframes above.
+ * Grouped alongside the Git devframe above.
  */
 const pingAction: DevframeViewAction = {
   type: 'action',
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d7fe27a2..4a247aea 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1260,6 +1260,9 @@ importers:
       '@devframes/json-render':
         specifier: workspace:*
         version: link:../json-render
+      '@devframes/plugin-git':
+        specifier: workspace:*
+        version: link:../../plugins/git
       '@iconify-json/ph':
         specifier: catalog:frontend
         version: 1.2.2