feat(hub-ui): support transparent standalone viewers

[dvcolomban]

What changed

• let createUi({ branding: { background } }) accept any valid CSS background shorthand
• accept either one value for both color schemes or { light, dark } variants
• validate the active value with CSS.supports('background', value) and retain the default when it is invalid
• apply valid values through the static --devframes-viewer-background token
• use a custom-background selector with color-scheme: normal so transparent and translucent backgrounds composite with the host page
• keep the existing default light and dark backgrounds when background is omitted

Why

Applications embedding the standalone viewer may need its document background to match or composite with the surrounding host page. A CSS background value supports solid colors, gradients, images, alpha colors, and transparent without adding a special mode for each case.

The host page cannot reliably style a cross-origin iframe document, so the value travels through the existing branding configuration and is applied by the standalone viewer.

Usage

createUi({
  branding: {
    background: {
      light: 'linear-gradient(rgb(255 255 255 / 80%), transparent)',
      dark: 'linear-gradient(rgb(17 17 17 / 80%), transparent)',
    },
  },
})

A string applies to both color schemes:

createUi({ branding: { background: 'transparent' } })

Implementation

The packaged viewer stylesheet remains static. Its HTML defines --devframes-viewer-background as #fff in light mode and #111 in dark mode. The browser entry resolves the configured string or active light/dark variant, checks it with CSS.supports, and sets the token only when valid.

Valid custom backgrounds enable a static selector that sets the document's color-scheme to normal. This preserves iframe compositing for transparent, alpha colors, and translucent gradients, while the component tree retains its light or dark color-scheme for native controls. Invalid values leave the default token untouched.

The Hub publishes no request-specific stylesheet or extra asset route.

Visual comparison

Default viewer background	Transparent viewer background

Compatibility

Existing createUi() calls retain the current opaque light and dark standalone viewer backgrounds. Disabling the standalone viewer with viewer: false also keeps its existing behavior. Background URLs are accepted as trusted application configuration.

Validation

• pnpm lint
• pnpm knip
• pnpm typecheck
• pnpm test: 120 files passed, 1,323 tests passed, 9 skipped
• focused Hub UI behavior and API snapshot tests: 7 passed, 249 skipped
• real Chromium iframe checks:
  • transparent revealed the host page
  • a translucent gradient composited over the host page
  • light/dark variants switched with the active color scheme
  • an invalid value retained the default background
  • omitted configuration retained the opaque default

[vercel]

@dvcolomban is attempting to deploy a commit to the NuxtLabs Team on Vercel.

A member of the Team first needs to authorize it.

[antfu]

I wonder if this would be in the branding object? I would kind prefer to note have dynamic assets which could be hard to control in some cases

[Copilot]

Pull request overview

Adds an opt-in createUi({ viewer: { background: 'transparent' } }) configuration to let the Hub UI standalone viewer render with a transparent document background, so apps embedding the viewer can visually “shine through” behind the iframe.

Changes:

• Extends CreateUiOptions.viewer to accept an object with background: 'default' | 'transparent'.
• Publishes a small runtime CSS asset (__hub-ui.css) and ensures the standalone viewer HTML loads it before paint.
• Adds tests + API snapshot updates and documents the new option.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/snapshots/tsnapi/@devframes/hub-ui/index.snapshot.d.ts	Updates public API snapshot to reflect the expanded viewer option type.
packages/hub-ui/src/index.ts	Implements the new viewer background option and serves the runtime CSS asset.
packages/hub-ui/src/index.test.ts	Adds coverage for the HTML link and the asset behavior in default/transparent/disabled modes.
packages/hub-ui/src/client/standalone/index.html	Loads the runtime CSS asset early via a <link rel="stylesheet">.
docs/content/1.guide/18.hub-initiate.md	Documents the new viewer option usage.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[dvcolomban]

@antfu Thanks for the review !

Indeed this was extracted from a local patch downstream and it included some downstream constraints (we inject pre-build federated design system sheets, hence the dynamic link), I've folded it in the base styling instead, much cleaner !

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (1)

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

• import.meta.dirname is not a standard Node/Vite/Vitest field and will likely be undefined at runtime, causing this test to fail when resolving the built HTML. Prefer resolving the file via import.meta.url (or fileURLToPath) instead, and drop the now-unused join import.

import { join } from 'node:path'

[antfu]

Would this better accept any CSS value? So background?: string | { light: string, dark: string }, and allow undefined for the default. This would allow not only transparent, but for custom devtools that want to add a bit shading to the background for example?

[dvcolomban]

Adopted in e0c898d. branding.background now accepts a CSS background string for both schemes or required light/dark values. The active value is validated with CSS.supports and applied through the existing static token; invalid values keep the default. I also browser-tested transparent, a translucent gradient, scheme switching, invalid fallback, and the opaque default.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.