feat(hub-ui): support transparent standalone viewers

Author: dvcolomban

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

@@ -59,6 +59,7 @@ interface DevframeHubUi {
 
 `@devframes/hub-ui`'s `createUi()` is the reference (viewer + floating dock); its `setup(ctx)` publishes config to `ctx.staticConfig.ui` (`ConnectionMeta.configs.ui`):
 
+- **`viewer`** — set to `false` to disable the standalone viewer, or `{ background: 'transparent' }` when its document should visually inherit an embedding page's surface.
 - **`branding`** — rebrand the UI (logo, name, primary color).
 - **`dockPreferences`** — dock-bar: `categoryOrder`, floating-dock `maxVisibleItems`, first-run `defaultMode` (`'float'`/`'edge'`) and `defaultPosition`.
 - **`embeddedVisibility`** — the floating dock's reveal policy:

packages/hub-ui/src/client/standalone/index.html

@@ -5,6 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Devframes</title>
     <meta name="description" content="Devframes hub" />
+    <link rel="stylesheet" href="./__hub-ui.css" />
     <style>
       html,
       body {

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

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { createUi } from './index'
+
+describe('createUi viewer background', () => {
+  it('loads the runtime viewer stylesheet from the production HTML', () => {
+    expect.assertions(1)
+
+    const html = readFileSync(join(import.meta.dirname, '..', 'dist', 'client', 'standalone', 'index.html'), 'utf8')
+
+    expect(html).toContain('<link rel="stylesheet" href="./__hub-ui.css" />')
+  })
+
+  it('preserves the default viewer background', () => {
+    expect.assertions(1)
+
+    const ui = createUi()
+
+    expect(ui.assets?.['__hub-ui.css']()).toBe('')
+  })
+
+  it('provides a transparent viewer background when requested', () => {
+    expect.assertions(1)
+
+    const ui = createUi({ viewer: { background: 'transparent' } })
+
+    expect(ui.assets?.['__hub-ui.css']()).toBe('html,body{background:transparent!important}')
+  })
+
+  it('does not publish viewer assets when the viewer is disabled', () => {
+    expect.assertions(2)
+
+    const ui = createUi({ viewer: false })
+
+    expect(ui.viewer).toBeUndefined()
+    expect(ui.assets).toBeUndefined()
+  })
+})

packages/hub-ui/src/index.ts

@@ -33,8 +33,14 @@ function clientDir(): string {
 }
 
 export interface CreateUiOptions {
-  /** Serve the standalone viewer SPA at the hub base. Default: `true`. */
-  viewer?: boolean
+  /**
+   * Serve the standalone viewer SPA at the hub base. Pass an object to
+   * customize the viewer surface. Default: `true`.
+   */
+  viewer?: boolean | {
+    /** Page background used around transparent renderer content. Default: `'default'`. */
+    background?: 'default' | 'transparent'
+  }
   /** Serve the floating-dock bootstrap at `<base>embedded.js`. Default: `true`. */
   embedded?: boolean
   /**
@@ -87,13 +93,23 @@ export interface CreateUiOptions {
  */
 export function createUi(options: CreateUiOptions = {}): DevframeHubUi {
   const client = clientDir()
+  const viewerBackground = typeof options.viewer === 'object' ? options.viewer.background : undefined
   return {
     ...(options.viewer !== false
       ? { viewer: { distDir: join(client, 'standalone') } }
       : {}),
     ...(options.embedded !== false
       ? { embedded: { entry: join(client, 'embedded.js') } }
       : {}),
+    ...(options.viewer !== false
+      ? {
+          assets: {
+            '__hub-ui.css': () => viewerBackground === 'transparent'
+              ? 'html,body{background:transparent!important}'
+              : '',
+          },
+        }
+      : {}),
     // Publish the reference UI's config through the generic `ctx.staticConfig`
     // — it rides the connection handshake to every mounted frame and the
     // standalone viewer as `ConnectionMeta.configs.ui`.

tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts

@@ -3,7 +3,9 @@
  */
 // #region Interfaces
 export interface CreateUiOptions {
-  viewer?: boolean;
+  viewer?: boolean | {
+    background?: 'default' | 'transparent';
+  };
   embedded?: boolean;
   branding?: DevframeBranding;
   embeddedVisibility?: EmbeddedVisibility;