feat(hub-ui): add seamless iframe presentation

Author: dvcolomban

docs/content/1.guide/16.hub.md

@@ -214,6 +214,21 @@ ctx.docks.register({
 
 Group and members stay independent top-level entries in `devframe:docks`; `defaultChildId` opens on activation. Grouping affects the dock bar, not iframes — to share **one** soft-navigated iframe, give docks a shared `frameId` and mark the anchor with `subTabs` ([Shared-iframe soft navigation](/guide/client-context#shared-iframe-soft-navigation)).
 
+An iframe that should visually share its host's surface can opt into seamless presentation:
+
+```ts
+ctx.docks.register({
+  type: 'iframe',
+  id: 'embedded-dashboard',
+  title: 'Dashboard',
+  icon: 'ph:gauge-duotone',
+  url: 'http://localhost:4000/',
+  presentation: 'seamless',
+})
+```
+
+The reference Hub UI removes its address bar, opaque loading surface, border, background, shadow, and corner radius for that entry. Other viewers may provide an equivalent treatment or retain their default presentation. The embedded document must also use a transparent background if the host surface should remain visible.
+
 ### The dual role of `category`
 
 `category` (ordered by `DEFAULT_CATEGORIES_ORDER`, default `'default'`) sets an **ungrouped** entry's outer dock-bar bucket. A **grouped** entry takes its outer bucket from the **group's** `category`, and its own `category` becomes an **in-group sub-category**; a member whose `groupId` never resolves renders top-level under its own `category`.

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/components/dock/DockEdge.vue

@@ -34,6 +34,7 @@ const isVertical = computed(() => store.position === 'left' || store.position ==
 
 const groupedEntries = computed(() => context.docks.groupedEntries)
 const selectedEntry = computed(() => context.docks.selected)
+const isSeamlessIframe = computed(() => selectedEntry.value?.type === 'iframe' && selectedEntry.value.presentation === 'seamless')
 const activeGroup = computed(() => getEntryGroup(context.docks.entries, selectedEntry.value))
 const hasPanelContent = computed(() => {
   const entry = selectedEntry.value
@@ -407,8 +408,12 @@ const dragPreviewStyle = computed<CSSProperties | undefined>(() => {
 <template>
   <div
     id="devframes-edge-panel"
-    class="bg-dock-glass border border-base color-base shadow overflow-clip z-floating-anchor font-sans text-[15px] box-border"
-    :class="[panelLayoutClass, { 'devframes-edge-collapsed': isCollapsed }]"
+    class="color-base overflow-clip z-floating-anchor font-sans text-[15px] box-border"
+    :class="[
+      panelLayoutClass,
+      isSeamlessIframe ? 'bg-transparent border-0 shadow-none' : 'bg-dock-glass border border-base shadow',
+      { 'devframes-edge-collapsed': isCollapsed },
+    ]"
     :style="panelStyle"
     @mousemove="bringUp"
   >

packages/hub-ui/src/client/components/dock/DockPanel.vue

@@ -29,6 +29,7 @@ const layout = computed(() => props.layout ?? DEFAULT_DOCK_LAYOUT)
 
 // When the open entry belongs to a group, surface its siblings in a sidebar.
 const activeGroup = computed(() => getEntryGroup(context.docks.entries, selected.value))
+const isSeamlessIframe = computed(() => selected.value?.type === 'iframe' && selected.value.presentation === 'seamless')
 
 const windowSize = reactive(useWindowSize())
 const isHovering = ref(false)
@@ -175,7 +176,8 @@ onMounted(() => {
   <div
     v-show="context.docks.selected && context.docks.selected.type !== 'action'"
     ref="dockPanel"
-    class="bg-dock-glass rounded-lg border border-base color-base shadow overflow-hidden"
+    class="color-base overflow-hidden"
+    :class="isSeamlessIframe ? 'bg-transparent border-0 rounded-0 shadow-none' : 'bg-dock-glass rounded-lg border border-base shadow'"
     :style="panelStyle"
     @contextmenu="openContextMenu"
   >

packages/hub-ui/src/client/components/views/ViewIframe.vue

@@ -20,7 +20,8 @@ const props = defineProps<{
 
 const settings = sharedStateToRef(props.context.docks.settings)
 const isEdgeMode = computed(() => props.context.panel.store.mode === 'edge')
-const showAddressBar = computed(() => settings.value.showIframeAddressBar ?? true)
+const isSeamless = computed(() => props.entry.presentation === 'seamless')
+const showAddressBar = computed(() => !isSeamless.value && (settings.value.showIframeAddressBar ?? true))
 
 const ADDRESS_BAR_HEIGHT = 40
 
@@ -262,6 +263,11 @@ onMounted(() => {
   // cosmetic borders differ between edge/float and address-bar states.
   watchEffect(() => {
     Object.assign(iframe.style, props.iframeStyle)
+    if (isSeamless.value) {
+      iframe.style.border = 'none'
+      iframe.style.borderRadius = '0px'
+      return
+    }
     if (showAddressBar.value && !isEdgeMode.value) {
       iframe.style.borderTopLeftRadius = '0px'
       iframe.style.borderTopRightRadius = '0px'
@@ -381,7 +387,7 @@ onUnmounted(() => {
       ref="viewFrame"
       class="devframes-view-iframe relative w-full h-full flex-1 items-center justify-center"
     >
-      <ViewIframeLoading v-if="showLoadingPlaceholder" />
+      <ViewIframeLoading v-if="showLoadingPlaceholder" :transparent="isSeamless" />
       <ViewAssetsError
         v-if="assetsError"
         :error="assetsError"

packages/hub-ui/src/client/components/views/ViewIframeLoading.stories.ts

@@ -29,3 +29,9 @@ export const Loading: Story = {
     setup: () => () => stage(h(ViewIframeLoading)),
   }),
 }
+
+export const Transparent: Story = {
+  render: () => ({
+    setup: () => () => stage(h(ViewIframeLoading, { transparent: true })),
+  }),
+}

packages/hub-ui/src/client/components/views/ViewIframeLoading.vue

@@ -1,12 +1,19 @@
 <script setup lang="ts">
+defineProps<{
+  transparent?: boolean
+}>()
+
 // Placeholder shown while an iframe view loads its content. A blank iframe
 // paints white during load, so this is only visible once the pane steps aside
 // (`pane.hide()` in `ViewIframe`) — the same layering trick `ViewAssetsError`
 // relies on. It covers the initial load and any hard navigation/refresh.
 </script>
 
 <template>
-  <div class="devframes-view-iframe-loading absolute inset-0 flex flex-col items-center justify-center gap-2 bg-base">
+  <div
+    class="devframes-view-iframe-loading absolute inset-0 flex flex-col items-center justify-center gap-2"
+    :class="transparent ? 'bg-transparent' : 'bg-base'"
+  >
     <div class="i-ph:circle-notch-duotone animate-spin text-3xl color-faint" />
     <div class="text-sm color-muted">
       Loading…

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,29 @@
+import { describe, expect, it } from 'vitest'
+import { createUi } from './index'
+
+describe('createUi viewer background', () => {
+  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`.