@awarebydefault/display-case 1.0.0

package/src/ui/shell-core.test.ts

@@ -0,0 +1,340 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import type { Manifest, ManifestComponent } from '../core/manifest'
+import {
+  buildAddressUrl,
+  buildRenderSrc,
+  buildUrl,
+  gridPad,
+  groupByLevel,
+  groupPrimerSections,
+  initialSelectionFor,
+  MAX_PAD,
+  MIN_PAD,
+  type PrimerSection,
+  parseRoute,
+  primerForLocation,
+  resolveMode,
+  type Selection,
+  selSignature,
+} from './shell-core'
+
+// `primerForLocation` reads `window.location.pathname`; stub a minimal window
+// for the duration of each case and restore it afterwards.
+const realWindow = (globalThis as { window?: unknown }).window
+afterEach(() => {
+  ;(globalThis as { window?: unknown }).window = realWindow
+})
+function atPath(pathname: string): void {
+  ;(globalThis as { window?: unknown }).window = { location: { pathname } }
+}
+
+function manifest(over: Partial<Manifest>): Manifest {
+  return {
+    title: 'T',
+    components: [],
+    primer: true,
+    landing: 'primer',
+    ...over,
+  }
+}
+
+describe('primerForLocation', () => {
+  test('the /primer route is the Primer whenever one is configured', () => {
+    atPath('/primer')
+    // Even when the landing default was overridden to the library, an explicit
+    // /primer link still resolves to the Primer.
+    expect(primerForLocation(manifest({ landing: 'library' }))).toBe(true)
+  })
+
+  test('the /primer route is the library when no Primer is configured', () => {
+    atPath('/primer')
+    expect(
+      primerForLocation(manifest({ primer: false, landing: 'library' })),
+    ).toBe(false)
+  })
+
+  test('the bare / landing honors the resolved landing', () => {
+    atPath('/')
+    expect(primerForLocation(manifest({ landing: 'primer' }))).toBe(true)
+    expect(primerForLocation(manifest({ landing: 'library' }))).toBe(false)
+  })
+
+  test('a /c/... deep link is always a library address', () => {
+    atPath('/c/button/default')
+    expect(primerForLocation(manifest({ landing: 'primer' }))).toBe(false)
+  })
+})
+
+function comp(over: Partial<ManifestComponent>): ManifestComponent {
+  return {
+    id: 'button',
+    name: 'Button',
+    level: 'atom',
+    isFlow: false,
+    caseFile: 'src/Button.case.tsx',
+    placardDoc: null,
+    cases: [],
+    ...over,
+  }
+}
+
+describe('parseRoute', () => {
+  test('extracts the component and case ids from a /c/ path', () => {
+    const r = parseRoute('/c/button/default', '')
+    expect(r.componentId).toBe('button')
+    expect(r.caseId).toBe('default')
+    expect(r.path).toBe('/c/button/default')
+  })
+
+  test('collects only t.* query params into tweaks, stripping the prefix', () => {
+    const r = parseRoute('/c/button/default', '?t.size=lg&t.disabled=1&other=x')
+    expect(r.tweaks).toEqual({ size: 'lg', disabled: '1' })
+  })
+
+  test('reads docs=1 as the open docs flag', () => {
+    expect(parseRoute('/c/x/y', '?docs=1').docs).toBe(true)
+    expect(parseRoute('/c/x/y', '').docs).toBe(false)
+  })
+
+  test('yields empty ids for a path with no component segment', () => {
+    const r = parseRoute('/', '')
+    expect(r.componentId).toBe('')
+    expect(r.caseId).toBe('')
+  })
+})
+
+describe('resolveMode', () => {
+  const route = (path: string) => parseRoute(path, '')
+
+  test('/primer resolves to the primer only when one is configured', () => {
+    expect(resolveMode(route('/primer'), manifest({ primer: true }))).toBe(
+      'primer',
+    )
+    expect(resolveMode(route('/primer'), manifest({ primer: false }))).toBe(
+      'library',
+    )
+  })
+
+  test('the bare / landing honors the resolved landing', () => {
+    expect(resolveMode(route('/'), manifest({ landing: 'primer' }))).toBe(
+      'primer',
+    )
+    expect(resolveMode(route('/'), manifest({ landing: 'library' }))).toBe(
+      'library',
+    )
+  })
+
+  test('any deep link is a library address', () => {
+    expect(
+      resolveMode(route('/c/button/default'), manifest({ landing: 'primer' })),
+    ).toBe('library')
+  })
+})
+
+describe('initialSelectionFor', () => {
+  test('uses the route selection when it names a component', () => {
+    const route = parseRoute('/c/button/primary', '?t.size=lg')
+    expect(initialSelectionFor(manifest({}), route)).toEqual({
+      componentId: 'button',
+      caseId: 'primary',
+      tweaks: { size: 'lg' },
+    })
+  })
+
+  test('falls back to the first component and its first case', () => {
+    const route = parseRoute('/', '')
+    const m = manifest({
+      components: [
+        comp({
+          id: 'card',
+          cases: [
+            {
+              id: 'a',
+              name: 'A',
+              browseUrl: '',
+              renderUrl: '',
+              tweaks: null,
+              transitions: [],
+            },
+            {
+              id: 'b',
+              name: 'B',
+              browseUrl: '',
+              renderUrl: '',
+              tweaks: null,
+              transitions: [],
+            },
+          ],
+        }),
+      ],
+    })
+    expect(initialSelectionFor(m, route)).toEqual({
+      componentId: 'card',
+      caseId: 'a',
+      tweaks: {},
+    })
+  })
+
+  test('returns an empty selection when the manifest has no components', () => {
+    expect(
+      initialSelectionFor(manifest({ components: [] }), parseRoute('/', '')),
+    ).toEqual({ componentId: '', caseId: '', tweaks: {} })
+  })
+})
+
+describe('selSignature', () => {
+  const sel = (over: Partial<Selection>): Selection => ({
+    componentId: 'button',
+    caseId: 'default',
+    tweaks: {},
+    ...over,
+  })
+
+  test('is stable for equal selections', () => {
+    expect(selSignature(sel({}))).toBe(selSignature(sel({})))
+  })
+
+  test('changes when the case or a tweak changes', () => {
+    const base = selSignature(sel({}))
+    expect(selSignature(sel({ caseId: 'primary' }))).not.toBe(base)
+    expect(selSignature(sel({ tweaks: { size: 'lg' } }))).not.toBe(base)
+  })
+})
+
+describe('buildUrl', () => {
+  test('builds a bare /c/ path when there are no tweaks or docs', () => {
+    expect(buildUrl('button', 'default', {}, false)).toBe('/c/button/default')
+  })
+
+  test('encodes tweaks under the t. prefix and the docs flag', () => {
+    expect(buildUrl('button', 'default', { size: 'lg' }, true)).toBe(
+      '/c/button/default?t.size=lg&docs=1',
+    )
+  })
+
+  test('round-trips through parseRoute', () => {
+    const url = buildUrl('button', 'primary', { size: 'lg', on: '1' }, true)
+    const [path, search] = url.split('?')
+    const r = parseRoute(path, `?${search}`)
+    expect(r.componentId).toBe('button')
+    expect(r.caseId).toBe('primary')
+    expect(r.tweaks).toEqual({ size: 'lg', on: '1' })
+    expect(r.docs).toBe(true)
+  })
+})
+
+describe('buildRenderSrc', () => {
+  test('always sets the theme and appends tweaks', () => {
+    const src = buildRenderSrc(
+      '/render/button/default',
+      'dark',
+      { size: 'lg' },
+      false,
+      false,
+    )
+    expect(src.startsWith('/render/button/default?')).toBe(true)
+    expect(src).toContain('theme=dark')
+    expect(src).toContain('t.size=lg')
+    expect(src).not.toContain('fit=1')
+    expect(src).not.toContain('transparent=1')
+  })
+
+  test('adds the fit and transparent stage hints when requested', () => {
+    const src = buildRenderSrc('/render/x/y', 'light', {}, true, true)
+    expect(src).toContain('fit=1')
+    expect(src).toContain('transparent=1')
+  })
+})
+
+describe('buildAddressUrl', () => {
+  test('prefixes the origin and carries theme + tweaks but no stage hints', () => {
+    const url = buildAddressUrl(
+      '/render/button/default',
+      'dark',
+      { size: 'lg' },
+      'https://x.dev',
+    )
+    expect(url.startsWith('https://x.dev/render/button/default?')).toBe(true)
+    expect(url).toContain('theme=dark')
+    expect(url).toContain('t.size=lg')
+    expect(url).not.toContain('fit=1')
+    expect(url).not.toContain('transparent=1')
+  })
+
+  test('stays relative with an empty origin (server / first render)', () => {
+    expect(
+      buildAddressUrl('/render/x/y', 'light', {}, '').startsWith(
+        '/render/x/y?',
+      ),
+    ).toBe(true)
+  })
+})
+
+describe('gridPad', () => {
+  test('clamps to at least one grid cell when there is no slack', () => {
+    expect(gridPad(100, 100)).toBe(MIN_PAD)
+  })
+
+  test('clamps to at most three grid cells when there is ample slack', () => {
+    expect(gridPad(2000, 100)).toBe(MAX_PAD)
+  })
+
+  test('snaps the centered margin to a whole number of grid cells', () => {
+    const pad = gridPad(400, 200)
+    expect(pad % 16).toBe(0)
+    expect(pad).toBeGreaterThanOrEqual(MIN_PAD)
+    expect(pad).toBeLessThanOrEqual(MAX_PAD)
+  })
+})
+
+describe('groupByLevel', () => {
+  test('orders groups atoms-first and drops empty levels', () => {
+    const groups = groupByLevel([
+      comp({ id: 'page', level: 'page' }),
+      comp({ id: 'atom', level: 'atom' }),
+      comp({ id: 'mystery', level: null }),
+    ])
+    expect(groups.map((g) => g.key)).toEqual(['atom', 'page', 'unclassified'])
+  })
+
+  test('files a null level under the unclassified group', () => {
+    const groups = groupByLevel([comp({ id: 'x', level: null })])
+    expect(groups).toHaveLength(1)
+    expect(groups[0].key).toBe('unclassified')
+    expect(groups[0].components).toHaveLength(1)
+  })
+})
+
+describe('groupPrimerSections', () => {
+  const section = (over: Partial<PrimerSection>): PrimerSection => ({
+    id: 's',
+    title: 'S',
+    kind: 'display',
+    ...over,
+  })
+
+  test('folds displays under the heading that precedes them', () => {
+    const groups = groupPrimerSections([
+      section({ id: 'colors', kind: 'heading', title: 'Colors' }),
+      section({ id: 'ramp' }),
+      section({ id: 'swatches' }),
+      section({ id: 'type', kind: 'heading', title: 'Type' }),
+      section({ id: 'scale' }),
+    ])
+    expect(groups).toHaveLength(2)
+    expect(groups[0].heading?.id).toBe('colors')
+    expect(groups[0].items.map((i) => i.id)).toEqual(['ramp', 'swatches'])
+    expect(groups[1].heading?.id).toBe('type')
+    expect(groups[1].items.map((i) => i.id)).toEqual(['scale'])
+  })
+
+  test('puts displays before the first heading into a leading headless group', () => {
+    const groups = groupPrimerSections([
+      section({ id: 'wordmark' }),
+      section({ id: 'intro', kind: 'heading', title: 'Intro' }),
+    ])
+    expect(groups[0].heading).toBeNull()
+    expect(groups[0].items.map((i) => i.id)).toEqual(['wordmark'])
+    expect(groups[1].heading?.id).toBe('intro')
+  })
+})

package/src/ui/shell-core.ts

@@ -0,0 +1,295 @@
+import type { Manifest, ManifestComponent } from '../core/manifest'
+import type { HierarchyLevel } from '../index'
+import { HIERARCHY_LEVELS } from '../index'
+
+export type Theme = 'light' | 'dark'
+export type Mode = 'primer' | 'library'
+
+// Two ways to size the preview, à la Chrome DevTools' device toolbar:
+//  - Responsive: a width (or "full"); height fills the panel; manual zoom applies.
+//  - Fixed: an exact W×H (a device preset or custom); the iframe renders at that
+//    size and is auto-scaled to fit the panel (manual zoom is overridden).
+export interface ResponsivePreset {
+  id: string
+  label: string
+  width: 'full' | number
+}
+export const RESPONSIVE: ResponsivePreset[] = [
+  { id: 'full', label: 'Full', width: 'full' },
+  { id: 'desktop', label: 'Desktop', width: 1280 },
+  { id: 'tablet', label: 'Tablet', width: 768 },
+  { id: 'mobile', label: 'Mobile', width: 375 },
+]
+
+export interface DevicePreset {
+  id: string
+  label: string
+  w: number
+  h: number
+}
+export const DEVICES: DevicePreset[] = [
+  { id: 'tv-1080p', label: '1080p', w: 1920, h: 1080 },
+  { id: 'tv-4k', label: '4K', w: 3840, h: 2160 },
+  { id: 'laptop', label: 'Laptop', w: 1366, h: 768 },
+  { id: 'laptop-hidpi', label: 'Laptop HiDPI', w: 1440, h: 900 },
+  { id: 'ipad-pro-11', label: 'iPad Pro', w: 834, h: 1194 },
+  { id: 'ipad', label: 'iPad', w: 820, h: 1180 },
+  { id: 'iphone-14', label: 'iPhone 15', w: 390, h: 844 },
+  { id: 'iphone-promax', label: 'iPhone Pro Max', w: 430, h: 932 },
+  { id: 'iphone-se', label: 'iPhone SE', w: 375, h: 667 },
+  { id: 'pixel-7', label: 'Pixel 7', w: 412, h: 915 },
+  { id: 'galaxy-s20', label: 'Galaxy S20', w: 360, h: 800 },
+]
+
+export const LEVEL_LABEL: Record<HierarchyLevel | 'unclassified', string> = {
+  atom: 'Atoms',
+  molecule: 'Molecules',
+  organism: 'Organisms',
+  template: 'Templates',
+  page: 'Pages',
+  flow: 'Flows',
+  unclassified: 'Unclassified',
+}
+
+export const GROUP_ORDER: (HierarchyLevel | 'unclassified')[] = [
+  ...HIERARCHY_LEVELS,
+  'unclassified',
+]
+
+// At or below this chrome width the nav starts collapsed (tablet and down).
+export const NAV_COLLAPSE_MAX = 1024
+
+export const ZOOM_MIN = 0.5
+export const ZOOM_MAX = 2
+export const ZOOM_STEP = 0.1
+
+// Documentation panel width (px), adjustable by dragging its left edge.
+export const DOC_MIN_W = 256
+export const DOC_MAX_W = 640
+export const DOC_DEFAULT_W = 352 // 22rem
+
+// Stage crossfade duration (ms): the exhibit fades out when the selection
+// changes, swaps while hidden, then fades back in once measured. Mirrors the
+// CSS opacity transition on the stage.
+export const STAGE_FADE_MS = 150
+
+// Primer ↔ Cases crossfade duration (ms): on a mode switch the nav, the screen
+// content, and the mode-specific header controls all fade out together, the view
+// swaps while hidden, then everything fades back in. The mode-switch highlight
+// box lerps across this same span (see `.dc-modeswitch-thumb`). Mirrors the CSS
+// opacity transitions applied to those regions.
+export const MODE_FADE_MS = 200
+
+// The stage's dotted-grid margin around a decorated component, in px. It scales
+// with the spare room — from 1 grid cell when the component is near max width up
+// to 3 cells when there's plenty — and is snapped to the grid so the component's
+// edges land on dot columns/rows. `GRID` is the dot spacing (matches the 16px
+// `background-size` of `.dc-stage-frame`'s grid in chrome.css).
+export const GRID = 16
+export const MIN_PAD = GRID // at least 1 dot
+export const MAX_PAD = GRID * 3 // at most 3 dots
+
+// Center-fit, grid-snapped padding for one axis: half the spare space (after the
+// 1px borders), floored to a whole number of dots, clamped to [MIN_PAD, MAX_PAD].
+export function gridPad(available: number, box: number): number {
+  const slack = Math.floor((available - box - 2) / 2 / GRID) * GRID
+  return Math.max(MIN_PAD, Math.min(MAX_PAD, slack))
+}
+
+export interface Selection {
+  componentId: string
+  caseId: string
+  tweaks: Record<string, string>
+}
+
+export interface ParsedRoute {
+  componentId: string
+  caseId: string
+  tweaks: Record<string, string>
+  docs: boolean
+  /** The pathname this route was parsed from, for mode resolution. */
+  path: string
+}
+
+/**
+ * Pure route parse from an explicit path + query string. Usable on the server —
+ * which has only the request, not `window` — and on the client, so the shell's
+ * server render and its client hydration derive the same initial route and agree.
+ */
+export function parseRoute(pathname: string, search: string): ParsedRoute {
+  const parts = pathname.split('/').filter(Boolean)
+  const tweaks: Record<string, string> = {}
+  const params = new URLSearchParams(search)
+  for (const [k, v] of params) {
+    if (k.startsWith('t.')) tweaks[k.slice(2)] = v
+  }
+  return {
+    componentId: parts[1] ?? '',
+    caseId: parts[2] ?? '',
+    tweaks,
+    docs: params.get('docs') === '1',
+    path: pathname,
+  }
+}
+
+/** Client convenience: parse the live address. Reads `window`, so client-only. */
+export function parseLocation(): ParsedRoute {
+  return parseRoute(window.location.pathname, window.location.search)
+}
+
+/**
+ * Whether a route resolves to the Primer rather than the library. The canonical
+ * `/primer` route does (when a Primer exists); the bare `/` landing does unless
+ * the consumer opted out with `landing: 'cases'` (resolved server-side into
+ * `manifest.landing`). Every `/c/...` deep link — and any other path — is a
+ * library address. Pure (takes the route), so it runs on the server too.
+ */
+export function resolveMode(route: ParsedRoute, m: Manifest): Mode {
+  if (route.path === '/primer') return m.primer ? 'primer' : 'library'
+  if (route.path === '/') return m.landing === 'primer' ? 'primer' : 'library'
+  return 'library'
+}
+
+/** Client convenience over {@link resolveMode}. Reads `window`; client-only. */
+export function primerForLocation(m: Manifest): boolean {
+  return resolveMode(parseLocation(), m) === 'primer'
+}
+
+/** Pure initial selection from a parsed route + manifest (server + client). */
+export function initialSelectionFor(
+  m: Manifest,
+  route: ParsedRoute,
+): Selection {
+  if (route.componentId)
+    return {
+      componentId: route.componentId,
+      caseId: route.caseId,
+      tweaks: route.tweaks,
+    }
+  const first = m.components[0]
+  if (first) {
+    return {
+      componentId: first.id,
+      caseId: first.cases[0]?.id ?? '',
+      tweaks: {},
+    }
+  }
+  return { componentId: '', caseId: '', tweaks: {} }
+}
+
+/** Client convenience over {@link initialSelectionFor}. Reads `window`. */
+export function initialSelection(m: Manifest): Selection {
+  return initialSelectionFor(m, parseLocation())
+}
+
+// Identity of a selection: component + case + tweak overrides. Drives the
+// reveal gate (a size report only counts once it matches the shown selection,
+// tweaks included) and detects when a selection change is a no-op. Note: a
+// tweak-only change alters this signature but is NOT a crossfade trigger — the
+// crossfade controller compares component+case, so the frame retweaks in place.
+export function selSignature(s: Selection): string {
+  return `${s.componentId}\0${s.caseId}\0${JSON.stringify(s.tweaks ?? {})}`
+}
+
+// Encode the shareable app address: which case is on the stage, its tweak
+// overrides (`t.*`), and whether the docs panel is open (`docs=1`). Parsed back
+// on load by `parseLocation` so any of these survive a copied/shared link.
+export function buildUrl(
+  componentId: string,
+  caseId: string,
+  tweaks: Record<string, string>,
+  docsOpen: boolean,
+): string {
+  const params = new URLSearchParams()
+  for (const [k, v] of Object.entries(tweaks)) params.set(`t.${k}`, v)
+  if (docsOpen) params.set('docs', '1')
+  const qs = params.toString()
+  return `/c/${componentId}/${caseId}${qs ? `?${qs}` : ''}`
+}
+
+export function buildRenderSrc(
+  renderUrl: string,
+  theme: Theme,
+  tweaks: Record<string, string>,
+  fit: boolean,
+  transparent: boolean,
+): string {
+  const params = new URLSearchParams()
+  params.set('theme', theme)
+  // The preview's pixel size is controlled by the iframe element, not an inner
+  // max-width, so the frame always renders "full".
+  for (const [k, v] of Object.entries(tweaks)) params.set(`t.${k}`, v)
+  // `fit` asks the render frame to shrink-wrap the case to its natural width so
+  // a small component (e.g. a square button) doesn't stretch to fill the frame.
+  if (fit) params.set('fit', '1')
+  // `transparent` drops the render doc's background so the component sits on the
+  // stage's dotted grid (decorated components only — not pages/flows, and not
+  // the standalone /render endpoint, which keeps its opaque snapshot bg).
+  if (transparent) params.set('transparent', '1')
+  return `${renderUrl}?${params.toString()}`
+}
+
+// The shareable standalone-snapshot address shown above the stage: the render
+// URL with the visible theme and any tweak overrides — none of the
+// stage-internal `fit`/`transparent` hints `buildRenderSrc` adds, since those
+// describe how the vitrine embeds the frame, not the case a reader would open.
+// Absolute (origin-prefixed) so the address a reader copies pastes straight into
+// a browser; `renderUrl` is a server-relative path like `/render/...`. `origin`
+// is passed in (not read from `window`) so this stays pure: the server and the
+// client's first render both use an empty origin (a relative URL), and the
+// client fills the real origin in after hydration — no hydration mismatch.
+export function buildAddressUrl(
+  renderUrl: string,
+  theme: Theme,
+  tweaks: Record<string, string>,
+  origin: string,
+): string {
+  const params = new URLSearchParams()
+  params.set('theme', theme)
+  for (const [k, v] of Object.entries(tweaks)) params.set(`t.${k}`, v)
+  return `${origin}${renderUrl}?${params.toString()}`
+}
+
+export function groupByLevel(components: ManifestComponent[]) {
+  return GROUP_ORDER.map((key) => ({
+    key,
+    components: components.filter((c) => (c.level ?? 'unclassified') === key),
+  })).filter((g) => g.components.length > 0)
+}
+
+// A `##`-heading group in the primer table of contents: the heading plus the
+// Displays that follow it (a leading headless group holds Displays before the
+// first heading).
+export interface PrimerSection {
+  id: string
+  title: string
+  kind: 'heading' | 'display'
+}
+export interface PrimerGroup {
+  heading: PrimerSection | null
+  items: PrimerSection[]
+}
+
+// Fold the primer's flat, document-ordered section list into `##`-heading
+// groups: each heading owns the Displays that follow it. Displays before the
+// first heading (e.g. the wordmark under the H1) sit in a leading headless
+// group so they still appear in the table of contents.
+export function groupPrimerSections(
+  primerSections: PrimerSection[],
+): PrimerGroup[] {
+  const out: PrimerGroup[] = []
+  let current: PrimerGroup | null = null
+  for (const s of primerSections) {
+    if (s.kind === 'heading') {
+      current = { heading: s, items: [] }
+      out.push(current)
+    } else {
+      if (!current) {
+        current = { heading: null, items: [] }
+        out.push(current)
+      }
+      current.items.push(s)
+    }
+  }
+  return out
+}

package/src/ui/shell.tsx

@@ -0,0 +1,60 @@
+import { ShellView } from './design-system/components/shell/ShellView'
+import { DcTestIds } from './test-ids'
+import { type ShellSeed, useShell } from './use-shell'
+
+/**
+ * The browse chrome's container. It runs the {@link useShell} state machine and
+ * hands the resulting view model to the pure {@link ShellView}, supplying the
+ * one thing a view model can't carry across the app/exhibit boundary: the live
+ * `<iframe>` elements (the render stage and the Primer reading page). In a
+ * page/flow exhibit those slots are static stand-ins instead — same view, no
+ * server. Until the manifest loads (and when it's empty) the container shows the
+ * loading/empty screens rather than the chrome.
+ */
+export function Shell({ seed }: { seed: ShellSeed }) {
+  const vm = useShell(seed)
+  if (!vm.manifest) return <div className="dc-loading">Loading…</div>
+  if (vm.manifest.components.length === 0) {
+    return (
+      <div className="dc-empty">
+        <p>No cases found.</p>
+        <p className="dc-empty-hint">
+          Add a <code>*.case.tsx</code> file to get started.
+        </p>
+      </div>
+    )
+  }
+
+  // The live render stage: one iframe, loaded once at a fixed src; the hook
+  // pushes every later change in via postMessage so it never reloads/flickers.
+  const renderFrame = (
+    <iframe
+      ref={vm.frameRef}
+      title="preview"
+      data-testid={DcTestIds.stageFrame}
+      className="dc-frame"
+      style={{
+        width: `${vm.targetW}px`,
+        height: `${vm.renderH}px`,
+        transform: vm.scale === 1 ? undefined : `scale(${vm.scale})`,
+        transformOrigin: 'top left',
+      }}
+      src={vm.frameSrc ?? undefined}
+    />
+  )
+
+  // The Primer reading page: its own isolated iframe, created lazily the first
+  // time the Primer view is opened (so `primerSrc` is null until then).
+  const primerFrame = vm.primerSrc ? (
+    <iframe
+      ref={vm.primerRef}
+      title="Primer"
+      className="dc-primer-frame"
+      src={vm.primerSrc}
+    />
+  ) : null
+
+  return (
+    <ShellView {...vm} renderFrame={renderFrame} primerFrame={primerFrame} />
+  )
+}