feat(hub-ui-onboard): short-circuit when installed, dim the pill, add hide for now

When every named package is already in node_modules, onInstalled runs on
the first request and the button never shows. The pill is smaller and sits
at 25% opacity until hovered or open. The panel offers "Hide for now" for
the browser tab next to "Disable entirely".

Author: antfubot

docs/content/1.guide/18.hub-initiate.md

@@ -85,7 +85,7 @@ if (!onboarding.disabled)
   injectScript(onboarding.scriptSrc)
 ```
 
-Install runs the project's package manager (detected from the lockfile) with the configured `packages` only; the request body controls nothing, and a cross-origin `POST` is refused. The button polls `status` once a second and, when `onInstalled` returned a handler, loads the real `embedded.js` and removes itself. Without a handler it asks the user to restart. Disable writes `<stateDir>/hub-ui-onboard.json` (default `node_modules/.devframe`); the host reads `onboarding.disabled` on the next start and injects nothing. Mount the onboarding only when the user did not set the host's own devtools option, so an explicit `devtools: true` or `false` in the host configuration always wins. [`examples/hub-onboard-vite`](https://github.com/devframes/devframe/tree/main/examples/hub-onboard-vite) shows the whole flow on Vite.
+Install runs the project's package manager (detected from the lockfile) with the configured `packages` only; the request body controls nothing, and a cross-origin `POST` is refused. The button polls `status` once a second and, when `onInstalled` returned a handler, loads the real `embedded.js` and removes itself. Without a handler it asks the user to restart. When every named package is already in `node_modules`, `onboarding.installed` is `true`, `onInstalled` runs on the first request, and the button never shows. The panel has two ways out: "Hide for now" hides the button for the browser tab (`sessionStorage`), and "Disable entirely" writes `<stateDir>/hub-ui-onboard.json` (default `node_modules/.devframe`) so the host reads `onboarding.disabled` on the next start and injects nothing. Mount the onboarding only when the user did not set the host's own devtools option, so an explicit `devtools: true` or `false` in the host configuration always wins. [`examples/hub-onboard-vite`](https://github.com/devframes/devframe/tree/main/examples/hub-onboard-vite) shows the whole flow on Vite.
 
 ## Renderer modules
 

docs/content/6.errors/DF9003.md

@@ -1,15 +1,15 @@
 ---
 title: 'DF9003: onInstalled Threw'
-description: '`onInstalled` threw after the packages were installed.'
+description: '`onInstalled` threw after the packages were installed: {reason}'
 ---
 
 ## Message
 
-> `onInstalled` threw after the packages were installed.
+> `onInstalled` threw after the packages were installed: `{reason}`
 
 ## Cause
 
-The packages are installed. The host's `onInstalled` callback, which usually imports the new packages and starts the hub, threw. The original error is attached as `cause`.
+The packages are installed. The host's `onInstalled` callback, which usually imports the new packages and starts the hub, threw. `{reason}` is its message; the original error is attached as `cause`.
 
 ## Fix
 

examples/hub-onboard-vite/README.md

@@ -9,15 +9,18 @@ pnpm --filter hub-onboard-vite dev
 Open the printed URL. The button at the bottom left opens a panel with two actions:
 
 - Install runs `pnpm add -D @devframes/hub @devframes/hub-ui @devframes/plugin-git` in this directory. When it finishes, the host starts the real hub on `/__devframes/` in the same process and the button swaps itself for the floating dock.
-- Disable writes `node_modules/.devframe/hub-ui-onboard.json`. The host reads `onboarding.disabled` on the next start and injects no script.
+- Hide for now hides the button for this browser tab.
+- Disable entirely writes `node_modules/.devframe/hub-ui-onboard.json`. The host reads `onboarding.disabled` on the next start and injects no script.
+
+When the three packages are already installed, the button never shows: the host's `onInstalled` runs on the first request and the real dock appears directly.
 
 Install changes this example's `package.json` and the lockfile. Run `git checkout -- examples/hub-onboard-vite pnpm-lock.yaml` and delete the state file to reset the demo.
 
 ## How it works
 
 [`vite.config.ts`](./vite.config.ts) holds the whole integration:
 
-- `createOnboarding({ packages, branding, onInstalled })` returns `nodeMiddleware`, `scriptSrc` and `disabled`.
+- `createOnboarding({ packages, branding, onInstalled })` returns `nodeMiddleware`, `scriptSrc`, `disabled` and `installed`.
 - `server.middlewares.use(onboarding.nodeMiddleware)` serves `/__devframes/embedded.js` and the `/__devframes/__onboard/*` routes.
 - `transformIndexHtml` injects `<script type="module" src="/__devframes/embedded.js">` unless the user disabled it earlier.
 - `onInstalled` resolves the new packages from the project root, calls `initHub` with Vite's HTTP server, and returns `hub.handler`. From then on every request under the base goes to the hub.

examples/hub-onboard-vite/index.html

@@ -12,7 +12,8 @@ <h1>Hub onboarding (Vite)</h1>
       <li>is <code>/__devframes/embedded.js</code>, a 20 kB stand-in for the hub UI</li>
       <li>installs <code>@devframes/hub</code>, <code>@devframes/hub-ui</code> and <code>@devframes/plugin-git</code> when you click Install</li>
       <li>then hands <code>/__devframes/</code> to the real hub in this same process, no restart</li>
-      <li>writes <code>node_modules/.devframe/hub-ui-onboard.json</code> when you click Disable</li>
+      <li>hides for this tab when you click Hide for now</li>
+      <li>writes <code>node_modules/.devframe/hub-ui-onboard.json</code> when you click Disable entirely</li>
     </ul>
   </body>
 </html>

packages/hub-ui-onboard/src/client/index.ts

@@ -13,6 +13,7 @@ import { DEVFRAME_LOGO } from './logo'
 const moduleUrl = import.meta.url
 const base = new URL('./', moduleUrl)
 const POLL_MS = 1000
+const HIDDEN_KEY = 'devframes-onboard-hidden'
 
 const api = (path: string, init?: RequestInit) => fetch(new URL(`__onboard/${path}`, base), init)
 
@@ -86,9 +87,10 @@ function mount(initial: OnboardingStatus): void {
   pill.className = 'devframes-onboard-pill'
   pill.title = messages.title
   pill.setAttribute('aria-haspopup', 'dialog')
+  pill.setAttribute('aria-expanded', 'false')
   const glow = document.createElement('span')
   glow.className = 'devframes-onboard-glow'
-  pill.append(glow, mark(branding, 'w-5 h-5'))
+  pill.append(glow, mark(branding, 'w-4 h-4'))
 
   const panel = document.createElement('div')
   panel.className = 'devframes-onboard-panel'
@@ -113,11 +115,18 @@ function mount(initial: OnboardingStatus): void {
   note.className = 'm-0 text-xs'
   note.hidden = true
 
-  const install = button('btn-primary', messages.install, () => void startInstall())
-  const disable = button('btn-action', messages.disable, () => void disableDevtools())
+  const install = button('btn-primary text-sm justify-center', messages.install, () => void startInstall())
+  const hide = button('btn-text text-sm color-muted', messages.hide, () => {
+    sessionStorage.setItem(HIDDEN_KEY, '1')
+    host.remove()
+  })
+  const disable = button('btn-text text-sm color-muted', messages.disable, () => void disableDevtools())
+  const secondary = document.createElement('div')
+  secondary.className = 'flex items-center gap-1 -ml-2'
+  secondary.append(hide, disable)
   const actions = document.createElement('div')
-  actions.className = 'flex items-center justify-end gap-2'
-  actions.append(disable, install)
+  actions.className = 'flex flex-col gap-1'
+  actions.append(install, secondary)
 
   panel.append(heading, description, command, note, actions)
   scheme.append(pill, panel)
@@ -188,8 +197,11 @@ async function main(): Promise<void> {
   // Never stack a second button inside an iframe of the same origin.
   if (window.parent !== window)
     return
+  if (sessionStorage.getItem(HIDDEN_KEY))
+    return
   const status = await fetchStatus()
-  if (status.state === 'disabled')
+  // Nothing to offer: disabled by the user, or already installed with no hub to hand off to.
+  if (status.state === 'disabled' || status.state === 'installed')
     return
   if (status.state === 'ready') {
     await handOff()

packages/hub-ui-onboard/src/client/style.css

@@ -4,9 +4,15 @@
  * clearly next to the utilities.
  */
 .devframes-onboard-pill {
-  --uno: fixed bottom-4 left-4 z-floating-anchor w-10 h-10 rounded-full border border-base bg-dock-glass shadow;
+  --uno: fixed bottom-4 left-4 z-floating-anchor w-8 h-8 rounded-full border border-base bg-dock-glass shadow;
   --uno: flex items-center justify-center cursor-pointer select-none p-0 outline-none;
-  --uno: transition-transform duration-200 hover:scale-105 focus-visible:ring-2 ring-primary-400;
+  --uno: op25 hover:op100 focus-visible:op100 focus-visible:ring-2 ring-primary-400;
+  --uno: transition-all duration-200 hover:scale-105;
+}
+
+/* Full opacity while the panel is open, so the pill reads as its anchor. */
+.devframes-onboard-pill[aria-expanded='true'] {
+  --uno: op100;
 }
 
 .devframes-onboard-glow {

packages/hub-ui-onboard/src/diagnostics.ts

@@ -22,7 +22,7 @@ export const diagnostics = defineDiagnostics({
       fix: 'Make sure that `cwd` points at the project that should receive the dependency (in a workspace, the package that runs the dev server).',
     },
     DF9003: {
-      why: '`onInstalled` threw after the packages were installed.',
+      why: (p: { reason: string }) => `\`onInstalled\` threw after the packages were installed: ${p.reason}`,
       fix: 'The packages are installed. Fix the error in your `onInstalled` callback, or restart the dev server to load them.',
     },
     DF9004: {

packages/hub-ui-onboard/src/index.ts

@@ -11,7 +11,7 @@ import { pipeline } from 'node:stream/promises'
 import { fileURLToPath } from 'node:url'
 import { Diagnostic } from 'nostics'
 import { diagnostics } from './diagnostics'
-import { formatCommand, resolveInstallCommand, runInstall } from './install'
+import { formatCommand, packagesInstalled, resolveInstallCommand, runInstall } from './install'
 
 export type * from './types'
 
@@ -38,7 +38,8 @@ function defaultMessages(productName: string): OnboardingMessages {
     title: productName,
     description: `${productName} is not installed in this project yet. Install it to open the panel.`,
     install: `Install ${productName}`,
-    disable: 'Disable',
+    hide: 'Hide for now',
+    disable: 'Disable entirely',
     installing: 'Installing...',
     restart: `Installed. Restart your dev server to open ${productName}.`,
     retry: 'Retry',
@@ -120,7 +121,8 @@ export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
   const messages = { ...defaultMessages(branding.productName?.trim() || 'Devframes'), ...options.messages }
 
   const disabled = readDisabled(stateFile)
-  let state: OnboardingState = disabled ? 'disabled' : 'idle'
+  const installed = !disabled && packagesInstalled(plan)
+  let state: OnboardingState = disabled ? 'disabled' : installed ? 'installed' : 'idle'
   let error: OnboardingStatus['error']
   let delegate: OnboardingHandler | undefined
   let command: Promise<ResolvedCommand> | undefined
@@ -132,6 +134,18 @@ export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
     state = 'error'
   }
 
+  /** Hand the base to the host's hub, if it offers one. */
+  async function activate(): Promise<void> {
+    try {
+      const next = await options.onInstalled?.()
+      delegate = typeof next === 'function' ? next : undefined
+      state = delegate ? 'ready' : 'installed'
+    }
+    catch (cause) {
+      fail(cause, () => diagnostics.DF9003({ reason: cause instanceof Error ? cause.message : String(cause), cause }))
+    }
+  }
+
   async function install(): Promise<void> {
     state = 'installing'
     error = undefined
@@ -145,16 +159,13 @@ export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
       fail(cause, () => diagnostics.DF9001({ command, exitCode: undefined, stderr: String(cause) }))
       return
     }
-    try {
-      const next = await options.onInstalled?.()
-      delegate = typeof next === 'function' ? next : undefined
-      state = delegate ? 'ready' : 'installed'
-    }
-    catch (cause) {
-      fail(cause, () => diagnostics.DF9003({ cause }))
-    }
+    await activate()
   }
 
+  // Already installed: the hub takes over on the first request. Not earlier,
+  // because the host's `onInstalled` may need a server that exists only later.
+  let activated: Promise<void> | undefined
+
   function disable(): Response {
     try {
       mkdirSync(join(stateFile, '..'), { recursive: true })
@@ -173,6 +184,8 @@ export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
   }
 
   const handler: OnboardingHandler = async (request) => {
+    if (installed)
+      await (activated ??= activate())
     if (delegate)
       return delegate(request)
     const { pathname } = new URL(request.url)
@@ -212,6 +225,7 @@ export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
         .catch(cause => next ? next(cause) : res.destroy(cause))
     },
     disabled,
+    installed,
     scriptSrc: `${base}embedded.js`,
   }
 }

packages/hub-ui-onboard/src/install.ts

@@ -1,5 +1,5 @@
 import type { ResolvedCommand } from 'package-manager-detector'
-import { access } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import process from 'node:process'
 import { detect, resolveCommand } from 'package-manager-detector'
@@ -41,16 +41,30 @@ export async function runInstall(plan: InstallPlan, command: ResolvedCommand): P
       stderr: result.stderr.trim().slice(-2048),
     })
   }
-  for (const spec of plan.packages) {
-    const name = packageName(spec)
-    if (!name)
-      continue
-    const installed = await access(join(plan.cwd, 'node_modules', name)).then(() => true, () => false)
-    if (!installed)
+  for (const name of namedPackages(plan)) {
+    if (!isInstalled(plan.cwd, name))
       throw diagnostics.DF9002({ name, cwd: plan.cwd })
   }
 }
 
+/**
+ * `true` when every named package is already in `<cwd>/node_modules`, so the
+ * onboarding has nothing to install. Path, URL and alias specs cannot be
+ * checked by name, so a plan made only of those is never "already installed".
+ */
+export function packagesInstalled(plan: InstallPlan): boolean {
+  const names = namedPackages(plan)
+  return names.length > 0 && names.every(name => isInstalled(plan.cwd, name))
+}
+
+function isInstalled(cwd: string, name: string): boolean {
+  return existsSync(join(cwd, 'node_modules', name))
+}
+
+function namedPackages(plan: InstallPlan): string[] {
+  return plan.packages.map(packageName).filter((name): name is string => name !== undefined)
+}
+
 /**
  * The package name of a bare spec (`foo`, `@scope/foo@^1`), or `undefined`
  * for a path, URL or alias spec whose installed name is not in the spec.

packages/hub-ui-onboard/src/types.ts

@@ -17,6 +17,9 @@ export interface OnboardingMessages {
   /** Short sentence under the heading. */
   description: string
   install: string
+  /** Hides the button for this browser tab (`sessionStorage`). */
+  hide: string
+  /** Writes the state file; the host stops injecting the button. */
   disable: string
   installing: string
   /** Shown when the install finished and no hot swap happened. */
@@ -68,6 +71,12 @@ export interface Onboarding {
   nodeMiddleware: (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse, next?: (err?: unknown) => void) => void
   /** `true` when the user disabled DevTools in an earlier session; skip injecting `scriptSrc`. */
   disabled: boolean
+  /**
+   * `true` when every named package was already in `node_modules` at
+   * creation. `onInstalled` then runs on the first request, which already
+   * reaches its handler; the button never shows.
+   */
+  installed: boolean
   /** `<base>embedded.js`: the `<script type="module">` URL to inject. */
   scriptSrc: string
 }