From f2754a212357859f743df80e0cb09784a231ebeb Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 27 Aug 2026 00:15:23 +0200
Subject: [PATCH 1/7] feat(hub-ui): support transparent standalone viewers

---
 docs/content/1.guide/18.hub-initiate.md       |  1 +
 .../hub-ui/src/client/standalone/index.html   |  1 +
 packages/hub-ui/src/index.test.ts             | 39 +++++++++++++++++++
 packages/hub-ui/src/index.ts                  | 20 +++++++++-
 .../@devframes/hub-ui/index.snapshot.d.ts     |  4 +-
 5 files changed, 62 insertions(+), 3 deletions(-)
 create mode 100644 packages/hub-ui/src/index.test.ts

diff --git a/docs/content/1.guide/18.hub-initiate.md b/docs/content/1.guide/18.hub-initiate.md
index c8685810..0e132121 100644
--- a/docs/content/1.guide/18.hub-initiate.md
+++ b/docs/content/1.guide/18.hub-initiate.md
@@ -61,6 +61,7 @@ interface DevframeHubUi {
 
 `@devframes/hub-ui`'s `createUi()` is the reference (standalone `viewer` SPA + 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-rail: `categoryOrder`, floating-dock `maxVisibleItems`, first-run `defaultMode` (`'float'`/`'edge'`) and `defaultPosition`.
 - **`embeddedVisibility`** — the floating dock's reveal policy:
diff --git a/packages/hub-ui/src/client/standalone/index.html b/packages/hub-ui/src/client/standalone/index.html
index fbf2a89b..1e43d8c5 100644
--- a/packages/hub-ui/src/client/standalone/index.html
+++ b/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 {
diff --git a/packages/hub-ui/src/index.test.ts b/packages/hub-ui/src/index.test.ts
new file mode 100644
index 00000000..baa3c1b2
--- /dev/null
+++ b/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()
+  })
+})
diff --git a/packages/hub-ui/src/index.ts b/packages/hub-ui/src/index.ts
index 9fa8b26a..2e9d25bb 100644
--- a/packages/hub-ui/src/index.ts
+++ b/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,6 +93,7 @@ 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') } }
@@ -94,6 +101,15 @@ export function createUi(options: CreateUiOptions = {}): DevframeHubUi {
     ...(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`.
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts
index 38bfd4a1..d016216a 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts
+++ b/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;

From bd535b54ffd4bee319111a248fa4a4c19e9f9426 Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 27 Aug 2026 11:47:39 +0200
Subject: [PATCH 2/7] refactor(hub-ui): configure viewer background through
 branding

---
 docs/content/1.guide/18.hub-initiate.md       |  4 +-
 .../hub-ui/src/client/standalone/index.html   |  5 ++-
 packages/hub-ui/src/client/standalone/main.ts |  1 +
 packages/hub-ui/src/client/state/branding.ts  |  2 +
 packages/hub-ui/src/index.test.ts             | 39 ++++++++++++-------
 packages/hub-ui/src/index.ts                  | 20 +---------
 packages/hub-ui/src/types.ts                  |  2 +
 .../@devframes/hub-ui/index.snapshot.d.ts     |  5 +--
 8 files changed, 41 insertions(+), 37 deletions(-)

diff --git a/docs/content/1.guide/18.hub-initiate.md b/docs/content/1.guide/18.hub-initiate.md
index 0e132121..3f6cc914 100644
--- a/docs/content/1.guide/18.hub-initiate.md
+++ b/docs/content/1.guide/18.hub-initiate.md
@@ -61,8 +61,8 @@ interface DevframeHubUi {
 
 `@devframes/hub-ui`'s `createUi()` is the reference (standalone `viewer` SPA + 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).
+- **`viewer`** — set to `false` to disable the standalone viewer.
+- **`branding`** — rebrand the UI (logo, name, primary color), or set `background: 'transparent'` when the standalone viewer should reveal the host page behind its iframe.
 - **`dockPreferences`** — dock-rail: `categoryOrder`, floating-dock `maxVisibleItems`, first-run `defaultMode` (`'float'`/`'edge'`) and `defaultPosition`.
 - **`embeddedVisibility`** — the floating dock's reveal policy:
   - `'normal'` (default) — shows immediately.
diff --git a/packages/hub-ui/src/client/standalone/index.html b/packages/hub-ui/src/client/standalone/index.html
index 1e43d8c5..384cb566 100644
--- a/packages/hub-ui/src/client/standalone/index.html
+++ b/packages/hub-ui/src/client/standalone/index.html
@@ -5,7 +5,6 @@
     <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 {
@@ -17,6 +16,10 @@
       html.dark body {
         background: #111;
       }
+      html.viewer-background-transparent,
+      html.viewer-background-transparent body {
+        background: transparent;
+      }
       #app {
         height: 100%;
       }
diff --git a/packages/hub-ui/src/client/standalone/main.ts b/packages/hub-ui/src/client/standalone/main.ts
index 9f357457..f0465d5e 100644
--- a/packages/hub-ui/src/client/standalone/main.ts
+++ b/packages/hub-ui/src/client/standalone/main.ts
@@ -39,6 +39,7 @@ async function main(): Promise<void> {
   // established above.
   const branding = setBranding(rpc.connectionMeta.configs?.ui?.branding || {})
   applyDocumentHead(document, branding)
+  document.documentElement.classList.toggle('viewer-background-transparent', branding.background === 'transparent')
 
   // Per-tab session UI state (which dock is open + its route). `sessionStorage`
   // so a reload restores the selection after the auth handshake, per-tab.
diff --git a/packages/hub-ui/src/client/state/branding.ts b/packages/hub-ui/src/client/state/branding.ts
index 0467eb0c..11072272 100644
--- a/packages/hub-ui/src/client/state/branding.ts
+++ b/packages/hub-ui/src/client/state/branding.ts
@@ -9,6 +9,7 @@ export interface ResolvedBranding {
   logo?: BrandingLogo
   wordmark?: BrandingLogo
   primaryColor?: string
+  background: 'default' | 'transparent'
   tagline?: string
   favicon?: string
   windowTitle: string
@@ -23,6 +24,7 @@ function resolveDefaults(branding: DevframeBranding): ResolvedBranding {
     logo: branding.logo,
     wordmark: branding.wordmark,
     primaryColor: branding.primaryColor,
+    background: branding.background || 'default',
     tagline: branding.tagline,
     favicon: branding.favicon,
     windowTitle: branding.windowTitle?.trim() || productName,
diff --git a/packages/hub-ui/src/index.test.ts b/packages/hub-ui/src/index.test.ts
index baa3c1b2..c5691d74 100644
--- a/packages/hub-ui/src/index.test.ts
+++ b/packages/hub-ui/src/index.test.ts
@@ -1,39 +1,52 @@
+import type { DevframeHubContext } from '@devframes/hub/node'
 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)
+function createContext(): DevframeHubContext {
+  return { staticConfig: {} } as unknown as DevframeHubContext
+}
+
+describe('createUi branding background', () => {
+  it('keeps the viewer stylesheet static', () => {
+    expect.assertions(2)
 
     const html = readFileSync(join(import.meta.dirname, '..', 'dist', 'client', 'standalone', 'index.html'), 'utf8')
 
-    expect(html).toContain('<link rel="stylesheet" href="./__hub-ui.css" />')
+    expect(html).not.toContain('__hub-ui.css')
+    expect(html).toContain('html.viewer-background-transparent')
   })
 
   it('preserves the default viewer background', () => {
-    expect.assertions(1)
+    expect.assertions(2)
 
+    const context = createContext()
     const ui = createUi()
+    ui.setup?.(context)
 
-    expect(ui.assets?.['__hub-ui.css']()).toBe('')
+    expect(context.staticConfig.ui).toEqual({ branding: {} })
+    expect(ui.assets).toBeUndefined()
   })
 
-  it('provides a transparent viewer background when requested', () => {
-    expect.assertions(1)
+  it('publishes a transparent viewer background with the branding', () => {
+    expect.assertions(2)
 
-    const ui = createUi({ viewer: { background: 'transparent' } })
+    const context = createContext()
+    const ui = createUi({ branding: { background: 'transparent' } })
+    ui.setup?.(context)
 
-    expect(ui.assets?.['__hub-ui.css']()).toBe('html,body{background:transparent!important}')
+    expect(context.staticConfig.ui).toEqual({
+      branding: { background: 'transparent' },
+    })
+    expect(ui.assets).toBeUndefined()
   })
 
-  it('does not publish viewer assets when the viewer is disabled', () => {
-    expect.assertions(2)
+  it('disables the standalone viewer', () => {
+    expect.assertions(1)
 
     const ui = createUi({ viewer: false })
 
     expect(ui.viewer).toBeUndefined()
-    expect(ui.assets).toBeUndefined()
   })
 })
diff --git a/packages/hub-ui/src/index.ts b/packages/hub-ui/src/index.ts
index 2e9d25bb..9fa8b26a 100644
--- a/packages/hub-ui/src/index.ts
+++ b/packages/hub-ui/src/index.ts
@@ -33,14 +33,8 @@ function clientDir(): string {
 }
 
 export interface CreateUiOptions {
-  /**
-   * 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 standalone viewer SPA at the hub base. Default: `true`. */
+  viewer?: boolean
   /** Serve the floating-dock bootstrap at `<base>embedded.js`. Default: `true`. */
   embedded?: boolean
   /**
@@ -93,7 +87,6 @@ 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') } }
@@ -101,15 +94,6 @@ export function createUi(options: CreateUiOptions = {}): DevframeHubUi {
     ...(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`.
diff --git a/packages/hub-ui/src/types.ts b/packages/hub-ui/src/types.ts
index aaf7259f..4ff557e1 100644
--- a/packages/hub-ui/src/types.ts
+++ b/packages/hub-ui/src/types.ts
@@ -31,6 +31,8 @@ export interface DevframeBranding {
   wordmark?: BrandingLogo
   /** Brand color; feeds `--devframe-primary` and the whole primary ramp. */
   primaryColor?: string
+  /** Standalone viewer background. Default: `'default'`. */
+  background?: 'default' | 'transparent'
   /** Short line for the auth screen and the standalone meta description. */
   tagline?: string
   /** Favicon URL — applied on the standalone viewer and the popped-out window only. */
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts
index d016216a..06bf200c 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts
@@ -3,9 +3,7 @@
  */
 // #region Interfaces
 export interface CreateUiOptions {
-  viewer?: boolean | {
-    background?: 'default' | 'transparent';
-  };
+  viewer?: boolean;
   embedded?: boolean;
   branding?: DevframeBranding;
   embeddedVisibility?: EmbeddedVisibility;
@@ -16,6 +14,7 @@ export interface DevframeBranding {
   logo?: BrandingLogo;
   wordmark?: BrandingLogo;
   primaryColor?: string;
+  background?: 'default' | 'transparent';
   tagline?: string;
   favicon?: string;
   windowTitle?: string;

From 7892b851a1b7145e9a1344c442b8885e723ff62f Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 27 Aug 2026 12:13:59 +0200
Subject: [PATCH 3/7] fix(hub-ui): preserve transparent iframe canvas

---
 .../hub-ui/src/client/standalone/index.html   | 22 +++++++++++--------
 packages/hub-ui/src/client/standalone/main.ts |  8 +++----
 packages/hub-ui/src/index.test.ts             |  7 ++++--
 3 files changed, 22 insertions(+), 15 deletions(-)

diff --git a/packages/hub-ui/src/client/standalone/index.html b/packages/hub-ui/src/client/standalone/index.html
index 384cb566..dc71e4f1 100644
--- a/packages/hub-ui/src/client/standalone/index.html
+++ b/packages/hub-ui/src/client/standalone/index.html
@@ -6,19 +6,23 @@
     <title>Devframes</title>
     <meta name="description" content="Devframes hub" />
     <style>
+      :root {
+        color-scheme: light;
+        --devframes-viewer-background: #fff;
+      }
+      html.dark {
+        color-scheme: dark;
+        --devframes-viewer-background: #111;
+      }
+      html.viewer-background-transparent {
+        color-scheme: normal;
+        --devframes-viewer-background: transparent;
+      }
       html,
       body {
         margin: 0;
         height: 100%;
-        background: #fff;
-      }
-      html.dark,
-      html.dark body {
-        background: #111;
-      }
-      html.viewer-background-transparent,
-      html.viewer-background-transparent body {
-        background: transparent;
+        background: var(--devframes-viewer-background);
       }
       #app {
         height: 100%;
diff --git a/packages/hub-ui/src/client/standalone/main.ts b/packages/hub-ui/src/client/standalone/main.ts
index f0465d5e..d7744e01 100644
--- a/packages/hub-ui/src/client/standalone/main.ts
+++ b/packages/hub-ui/src/client/standalone/main.ts
@@ -12,14 +12,14 @@ import { DEFAULT_DOCK_SESSION_STORE } from '../state/docks'
 // shell stays frameworkless on purpose; everything visual lives inside the
 // custom element's shadow root.
 
-// The standalone page runs in the light DOM, so mirror the color mode onto the
-// document element — its background and native controls follow the
-// Auto/Light/Dark choice.
+// The standalone viewer runs in the light DOM, so mirror the color mode onto the
+// document element — its background follows the Auto/Light/Dark choice. The
+// component tree carries `color-scheme` for its native controls; keeping that
+// off the document lets the transparent viewer reveal the host page.
 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> {
diff --git a/packages/hub-ui/src/index.test.ts b/packages/hub-ui/src/index.test.ts
index c5691d74..040b3073 100644
--- a/packages/hub-ui/src/index.test.ts
+++ b/packages/hub-ui/src/index.test.ts
@@ -9,13 +9,16 @@ function createContext(): DevframeHubContext {
 }
 
 describe('createUi branding background', () => {
-  it('keeps the viewer stylesheet static', () => {
-    expect.assertions(2)
+  it('defines the viewer background through a static token', () => {
+    expect.assertions(5)
 
     const html = readFileSync(join(import.meta.dirname, '..', 'dist', 'client', 'standalone', 'index.html'), 'utf8')
 
     expect(html).not.toContain('__hub-ui.css')
     expect(html).toContain('html.viewer-background-transparent')
+    expect(html).toContain('--devframes-viewer-background: transparent')
+    expect(html).toContain('background: var(--devframes-viewer-background)')
+    expect(html).toMatch(/html\.viewer-background-transparent\s*\{[^}]*color-scheme:\s*normal/)
   })
 
   it('preserves the default viewer background', () => {

From e0c898d74735c1c2ea534052ba74b859487f1fff Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 27 Aug 2026 14:35:51 +0200
Subject: [PATCH 4/7] feat(hub-ui): accept custom viewer backgrounds

---
 docs/content/1.guide/18.hub-initiate.md       |  2 +-
 .../hub-ui/src/client/standalone/index.html   |  3 +-
 packages/hub-ui/src/client/standalone/main.ts | 15 ++++++++--
 packages/hub-ui/src/client/state/branding.ts  | 21 +++++++++-----
 packages/hub-ui/src/index.test.ts             | 29 ++++++++++++++-----
 packages/hub-ui/src/types.ts                  |  4 +--
 .../@devframes/hub-ui/index.snapshot.d.ts     |  5 +++-
 7 files changed, 55 insertions(+), 24 deletions(-)

diff --git a/docs/content/1.guide/18.hub-initiate.md b/docs/content/1.guide/18.hub-initiate.md
index 3f6cc914..7559d963 100644
--- a/docs/content/1.guide/18.hub-initiate.md
+++ b/docs/content/1.guide/18.hub-initiate.md
@@ -62,7 +62,7 @@ interface DevframeHubUi {
 `@devframes/hub-ui`'s `createUi()` is the reference (standalone `viewer` SPA + floating dock); its `setup(ctx)` publishes config to `ctx.staticConfig.ui` (`ConnectionMeta.configs.ui`):
 
 - **`viewer`** — set to `false` to disable the standalone viewer.
-- **`branding`** — rebrand the UI (logo, name, primary color), or set `background: 'transparent'` when the standalone viewer should reveal the host page behind its iframe.
+- **`branding`** — rebrand the UI (logo, name, primary color). `background` accepts any CSS `background` value (color, gradient, image, or `transparent`) or `{ light, dark }` variants; omit it to keep the design default.
 - **`dockPreferences`** — dock-rail: `categoryOrder`, floating-dock `maxVisibleItems`, first-run `defaultMode` (`'float'`/`'edge'`) and `defaultPosition`.
 - **`embeddedVisibility`** — the floating dock's reveal policy:
   - `'normal'` (default) — shows immediately.
diff --git a/packages/hub-ui/src/client/standalone/index.html b/packages/hub-ui/src/client/standalone/index.html
index dc71e4f1..97510332 100644
--- a/packages/hub-ui/src/client/standalone/index.html
+++ b/packages/hub-ui/src/client/standalone/index.html
@@ -14,9 +14,8 @@
         color-scheme: dark;
         --devframes-viewer-background: #111;
       }
-      html.viewer-background-transparent {
+      html.viewer-background-custom {
         color-scheme: normal;
-        --devframes-viewer-background: transparent;
       }
       html,
       body {
diff --git a/packages/hub-ui/src/client/standalone/main.ts b/packages/hub-ui/src/client/standalone/main.ts
index d7744e01..3e2edafa 100644
--- a/packages/hub-ui/src/client/standalone/main.ts
+++ b/packages/hub-ui/src/client/standalone/main.ts
@@ -2,7 +2,7 @@ import type { DockSessionStorage } from '@devframes/hub/client'
 import { getDevframeRpcClient, setDevframeClientContext } from '@devframes/hub/client'
 import { useSessionStorage } from '@vueuse/core'
 import { watchEffect } from 'vue'
-import { applyDocumentHead, applyPrimaryColor, setBranding } from '../state/branding'
+import { applyDocumentHead, applyPrimaryColor, setBranding, useBrandingBackground } from '../state/branding'
 import { isDark } from '../state/color-mode'
 import { DEFAULT_DOCK_SESSION_STORE } from '../state/docks'
 
@@ -15,11 +15,21 @@ import { DEFAULT_DOCK_SESSION_STORE } from '../state/docks'
 // The standalone viewer runs in the light DOM, so mirror the color mode onto the
 // document element — its background follows the Auto/Light/Dark choice. The
 // component tree carries `color-scheme` for its native controls; keeping that
-// off the document lets the transparent viewer reveal the host page.
+// off the document lets custom backgrounds composite with the host page.
+const brandingBackground = useBrandingBackground()
+
 watchEffect(() => {
   const el = document.documentElement
   el.classList.toggle('dark', isDark.value)
   el.classList.toggle('light', !isDark.value)
+
+  const background = brandingBackground.value
+  const hasValidBackground = background !== undefined && CSS.supports('background', background)
+  el.classList.toggle('viewer-background-custom', hasValidBackground)
+  if (hasValidBackground)
+    el.style.setProperty('--devframes-viewer-background', background)
+  else
+    el.style.removeProperty('--devframes-viewer-background')
 })
 
 async function main(): Promise<void> {
@@ -39,7 +49,6 @@ async function main(): Promise<void> {
   // established above.
   const branding = setBranding(rpc.connectionMeta.configs?.ui?.branding || {})
   applyDocumentHead(document, branding)
-  document.documentElement.classList.toggle('viewer-background-transparent', branding.background === 'transparent')
 
   // Per-tab session UI state (which dock is open + its route). `sessionStorage`
   // so a reload restores the selection after the auth handshake, per-tab.
diff --git a/packages/hub-ui/src/client/state/branding.ts b/packages/hub-ui/src/client/state/branding.ts
index 11072272..40e415fb 100644
--- a/packages/hub-ui/src/client/state/branding.ts
+++ b/packages/hub-ui/src/client/state/branding.ts
@@ -9,7 +9,7 @@ export interface ResolvedBranding {
   logo?: BrandingLogo
   wordmark?: BrandingLogo
   primaryColor?: string
-  background: 'default' | 'transparent'
+  background?: DevframeBranding['background']
   tagline?: string
   favicon?: string
   windowTitle: string
@@ -24,7 +24,7 @@ function resolveDefaults(branding: DevframeBranding): ResolvedBranding {
     logo: branding.logo,
     wordmark: branding.wordmark,
     primaryColor: branding.primaryColor,
-    background: branding.background || 'default',
+    background: branding.background,
     tagline: branding.tagline,
     favicon: branding.favicon,
     windowTitle: branding.windowTitle?.trim() || productName,
@@ -46,15 +46,20 @@ export function setBranding(branding: DevframeBranding): ResolvedBranding {
 
 /** The logo/wordmark URL for the current color scheme, reactive to it. */
 export function useBrandingLogo(pick: (b: ResolvedBranding) => BrandingLogo | undefined = b => b.logo): Ref<string | undefined> {
-  return computed(() => resolveLogo(pick(currentBranding.value), isDark.value))
+  return computed(() => resolveColorSchemeValue(pick(currentBranding.value), isDark.value))
 }
 
-function resolveLogo(logo: BrandingLogo | undefined, dark: boolean): string | undefined {
-  if (!logo)
+/** The standalone viewer background for the current color scheme. */
+export function useBrandingBackground(): Ref<string | undefined> {
+  return computed(() => resolveColorSchemeValue(currentBranding.value.background, isDark.value))
+}
+
+function resolveColorSchemeValue(value: BrandingLogo | undefined, dark: boolean): string | undefined {
+  if (!value)
     return undefined
-  if (typeof logo === 'string')
-    return logo
-  return dark ? (logo.dark || logo.light) : logo.light
+  if (typeof value === 'string')
+    return value
+  return dark ? (value.dark || value.light) : value.light
 }
 
 // --- Applying to the DOM --------------------------------------------------
diff --git a/packages/hub-ui/src/index.test.ts b/packages/hub-ui/src/index.test.ts
index 040b3073..74367122 100644
--- a/packages/hub-ui/src/index.test.ts
+++ b/packages/hub-ui/src/index.test.ts
@@ -1,6 +1,6 @@
 import type { DevframeHubContext } from '@devframes/hub/node'
 import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { createUi } from './index'
 
@@ -10,15 +10,16 @@ function createContext(): DevframeHubContext {
 
 describe('createUi branding background', () => {
   it('defines the viewer background through a static token', () => {
-    expect.assertions(5)
+    expect.assertions(6)
 
-    const html = readFileSync(join(import.meta.dirname, '..', 'dist', 'client', 'standalone', 'index.html'), 'utf8')
+    const html = readFileSync(fileURLToPath(new URL('../dist/client/standalone/index.html', import.meta.url)), 'utf8')
 
     expect(html).not.toContain('__hub-ui.css')
-    expect(html).toContain('html.viewer-background-transparent')
-    expect(html).toContain('--devframes-viewer-background: transparent')
+    expect(html).toContain('html.viewer-background-custom')
+    expect(html).toContain('--devframes-viewer-background: #fff')
+    expect(html).toContain('--devframes-viewer-background: #111')
     expect(html).toContain('background: var(--devframes-viewer-background)')
-    expect(html).toMatch(/html\.viewer-background-transparent\s*\{[^}]*color-scheme:\s*normal/)
+    expect(html).toMatch(/html\.viewer-background-custom\s*\{[^}]*color-scheme:\s*normal/)
   })
 
   it('preserves the default viewer background', () => {
@@ -32,7 +33,7 @@ describe('createUi branding background', () => {
     expect(ui.assets).toBeUndefined()
   })
 
-  it('publishes a transparent viewer background with the branding', () => {
+  it('publishes a CSS viewer background with the branding', () => {
     expect.assertions(2)
 
     const context = createContext()
@@ -45,6 +46,20 @@ describe('createUi branding background', () => {
     expect(ui.assets).toBeUndefined()
   })
 
+  it('publishes color-scheme viewer backgrounds with the branding', () => {
+    expect.assertions(1)
+
+    const context = createContext()
+    const background = {
+      light: 'linear-gradient(white, transparent)',
+      dark: 'linear-gradient(#111, transparent)',
+    }
+    const ui = createUi({ branding: { background } })
+    ui.setup?.(context)
+
+    expect(context.staticConfig.ui).toEqual({ branding: { background } })
+  })
+
   it('disables the standalone viewer', () => {
     expect.assertions(1)
 
diff --git a/packages/hub-ui/src/types.ts b/packages/hub-ui/src/types.ts
index 4ff557e1..d31f8afa 100644
--- a/packages/hub-ui/src/types.ts
+++ b/packages/hub-ui/src/types.ts
@@ -31,8 +31,8 @@ export interface DevframeBranding {
   wordmark?: BrandingLogo
   /** Brand color; feeds `--devframe-primary` and the whole primary ramp. */
   primaryColor?: string
-  /** Standalone viewer background. Default: `'default'`. */
-  background?: 'default' | 'transparent'
+  /** Standalone viewer CSS `background`; a string applies to both color schemes. */
+  background?: string | { light: string, dark: string }
   /** Short line for the auth screen and the standalone meta description. */
   tagline?: string
   /** Favicon URL — applied on the standalone viewer and the popped-out window only. */
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts
index 06bf200c..a30eabb0 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts
@@ -14,7 +14,10 @@ export interface DevframeBranding {
   logo?: BrandingLogo;
   wordmark?: BrandingLogo;
   primaryColor?: string;
-  background?: 'default' | 'transparent';
+  background?: string | {
+    light: string;
+    dark: string;
+  };
   tagline?: string;
   favicon?: string;
   windowTitle?: string;

From a51a4451df3c170287d5ac7bf7d055c505e91cf9 Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 27 Aug 2026 14:48:54 +0200
Subject: [PATCH 5/7] refactor(hub-ui): clarify viewer background application

---
 packages/hub-ui/src/client/standalone/main.ts | 20 +++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/packages/hub-ui/src/client/standalone/main.ts b/packages/hub-ui/src/client/standalone/main.ts
index 3e2edafa..5fde3835 100644
--- a/packages/hub-ui/src/client/standalone/main.ts
+++ b/packages/hub-ui/src/client/standalone/main.ts
@@ -18,18 +18,22 @@ import { DEFAULT_DOCK_SESSION_STORE } from '../state/docks'
 // off the document lets custom backgrounds composite with the host page.
 const brandingBackground = useBrandingBackground()
 
+function applyViewerBackground(documentElement: HTMLElement, background: string | undefined): void {
+  if (background === undefined || !CSS.supports('background', background)) {
+    documentElement.classList.remove('viewer-background-custom')
+    documentElement.style.removeProperty('--devframes-viewer-background')
+    return
+  }
+
+  documentElement.classList.add('viewer-background-custom')
+  documentElement.style.setProperty('--devframes-viewer-background', background)
+}
+
 watchEffect(() => {
   const el = document.documentElement
   el.classList.toggle('dark', isDark.value)
   el.classList.toggle('light', !isDark.value)
-
-  const background = brandingBackground.value
-  const hasValidBackground = background !== undefined && CSS.supports('background', background)
-  el.classList.toggle('viewer-background-custom', hasValidBackground)
-  if (hasValidBackground)
-    el.style.setProperty('--devframes-viewer-background', background)
-  else
-    el.style.removeProperty('--devframes-viewer-background')
+  applyViewerBackground(el, brandingBackground.value)
 })
 
 async function main(): Promise<void> {

From 7478e2f7cd0c22190d8ddc1acd60105ea97c5fdb Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 27 Aug 2026 14:52:57 +0200
Subject: [PATCH 6/7] refactor(hub-ui): decouple scheme value resolver

---
 packages/hub-ui/src/client/state/branding.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/hub-ui/src/client/state/branding.ts b/packages/hub-ui/src/client/state/branding.ts
index 40e415fb..3973969d 100644
--- a/packages/hub-ui/src/client/state/branding.ts
+++ b/packages/hub-ui/src/client/state/branding.ts
@@ -3,6 +3,8 @@ import type { BrandingLogo, DevframeBranding } from '../../types'
 import { computed, ref } from 'vue'
 import { isDark } from './color-mode'
 
+type ColorSchemeValue = string | { light: string, dark: string }
+
 /** Branding with defaults resolved — what the UI actually renders. */
 export interface ResolvedBranding {
   productName: string
@@ -54,7 +56,7 @@ export function useBrandingBackground(): Ref<string | undefined> {
   return computed(() => resolveColorSchemeValue(currentBranding.value.background, isDark.value))
 }
 
-function resolveColorSchemeValue(value: BrandingLogo | undefined, dark: boolean): string | undefined {
+function resolveColorSchemeValue(value: ColorSchemeValue | undefined, dark: boolean): string | undefined {
   if (!value)
     return undefined
   if (typeof value === 'string')

From 4ff4639ebdf04d4eef394f2add04dcee85afcaa7 Mon Sep 17 00:00:00 2001
From: dvcolomban <dinh-van.colomban@contentsquare.com>
Date: Thu, 27 Aug 2026 15:01:51 +0200
Subject: [PATCH 7/7] fix(hub-ui): preserve empty scheme values

---
 .../hub-ui/src/client/state/branding.test.ts  | 19 +++++++++++++++++++
 packages/hub-ui/src/client/state/branding.ts  |  2 +-
 2 files changed, 20 insertions(+), 1 deletion(-)
 create mode 100644 packages/hub-ui/src/client/state/branding.test.ts

diff --git a/packages/hub-ui/src/client/state/branding.test.ts b/packages/hub-ui/src/client/state/branding.test.ts
new file mode 100644
index 00000000..a3ac3631
--- /dev/null
+++ b/packages/hub-ui/src/client/state/branding.test.ts
@@ -0,0 +1,19 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { setBranding, useBrandingBackground } from './branding'
+import { setColorSchemePreference } from './color-mode'
+
+afterEach(() => {
+  setBranding({})
+  setColorSchemePreference('auto')
+})
+
+describe('useBrandingBackground', () => {
+  it('preserves an empty dark value for CSS validation', () => {
+    expect.assertions(1)
+
+    setColorSchemePreference('dark')
+    setBranding({ background: { light: 'white', dark: '' } })
+
+    expect(useBrandingBackground().value).toBe('')
+  })
+})
diff --git a/packages/hub-ui/src/client/state/branding.ts b/packages/hub-ui/src/client/state/branding.ts
index 3973969d..b38d006c 100644
--- a/packages/hub-ui/src/client/state/branding.ts
+++ b/packages/hub-ui/src/client/state/branding.ts
@@ -61,7 +61,7 @@ function resolveColorSchemeValue(value: ColorSchemeValue | undefined, dark: bool
     return undefined
   if (typeof value === 'string')
     return value
-  return dark ? (value.dark || value.light) : value.light
+  return dark ? (value.dark ?? value.light) : value.light
 }
 
 // --- Applying to the DOM --------------------------------------------------