@moldable-ai/ui 0.2.19 → 0.2.21

package/docs/adaptive-materials.md

@@ -0,0 +1,79 @@
+# Adaptive materials
+
+Moldable uses restrained translucent material to separate controls and
+navigation from the content they operate on. Material frames content; it does
+not replace content surfaces.
+
+## Roles
+
+Use `regular` material for normal toolbar and window chrome, grouped controls,
+menus, and temporary control overlays. It provides enough frosting for text
+and icons to remain stable as content moves behind it.
+
+Use `clear` material only for compact controls floating over photos, maps,
+video, or another richly colored canvas. Check the control against the
+lightest, darkest, and busiest content it can cover. If contrast is not stable,
+use `regular`.
+
+Documents, calendars, tables, forms, cards, sheets, inspectors, and primary
+working canvases remain opaque. Do not stack translucent content cards to
+create hierarchy.
+
+## Components
+
+`Material` applies one adaptive surface:
+
+```tsx
+<Material asChild variant="clear" shape="circle" interactive>
+  <IconButton label="Center map" variant="ghost">
+    <Locate />
+  </IconButton>
+</Material>
+```
+
+`MaterialGroup` applies one sampled layer to a related cluster:
+
+```tsx
+<MaterialGroup variant="regular" shape="capsule" spacing="compact">
+  <IconButton label="Previous" variant="ghost">
+    <ChevronLeft />
+  </IconButton>
+  <IconButton label="Next" variant="ghost">
+    <ChevronRight />
+  </IconButton>
+</MaterialGroup>
+```
+
+Children of a `MaterialGroup` should be ordinary transparent or ghost
+controls. Do not apply another `Material` to every child. A single grouped
+sampler produces clearer hierarchy and avoids accumulated blur.
+
+`Toolbar`, `AppFrameTitlebar`, and `AppFrameStatusbar` expose a `material`
+property. Their normal chrome uses `regular`; pass `material="none"` for an
+opaque or transparent composition that supplies its own surface.
+
+## Fallback behavior
+
+Every material starts from an opaque fallback. Translucent sampling is enabled
+only when the renderer supports backdrop filtering.
+
+- Reduced transparency uses opaque fills and removes blur and saturation.
+- Increased contrast makes fills more opaque and strengthens borders.
+- Forced colors use system surfaces and borders without blur or shadows.
+- Reduced motion removes material press transforms.
+
+The manual `data-transparency="reduced"`, `data-contrast="increased"`, and
+`data-motion="reduced"` attributes mirror system preferences for deterministic
+catalog and app testing.
+
+Do not animate blur, saturation, or backdrop filters. They are expensive,
+visually noisy, and difficult to make accessible. Limit the number of visible
+sampled layers and avoid nesting them.
+
+## Host boundary
+
+CSS material samples content inside the app renderer. It cannot sample the
+desktop behind a native window. Native behind-window material, window
+transparency, active-window appearance, and energy policy remain host-owned
+capabilities. Apps should use the same semantic variants regardless of which
+adapter renders them.

package/docs/app-anatomy.md

@@ -0,0 +1,74 @@
+# App anatomy
+
+## Recommended window shell
+
+Apps should be able to own a dedicated window without changing their internal
+layout. `AppFrame` consumes host-owned safe-area variables and keeps the app
+canvas independent of the desktop shell.
+
+```tsx
+<AppFrame>
+  <AppFrameTitlebar>
+    <AppFrameToolbar>
+      {/* title, view controls, primary actions */}
+    </AppFrameToolbar>
+  </AppFrameTitlebar>
+  <AppFrameContent scrollable={false}>
+    {/* app-owned canvas and panes */}
+  </AppFrameContent>
+</AppFrame>
+```
+
+The host renders native window controls and drag regions. Do not draw those
+inside app UI.
+
+## Recommended pane shell
+
+```tsx
+<PanelGroup>
+  <Panel surface="sidebar" className="w-64">
+    <Toolbar>{/* navigation and search */}</Toolbar>
+    <PanelContent>{/* selectable list */}</PanelContent>
+  </Panel>
+  <Panel>
+    <Toolbar>{/* title and primary actions */}</Toolbar>
+    <PanelContent>{/* primary work */}</PanelContent>
+  </Panel>
+</PanelGroup>
+```
+
+Use `SplitView` when the user benefits from resizing panes. Use `PanelGroup`
+for fixed or responsive layouts. Do not nest both merely for styling.
+
+## Pane responsibilities
+
+- Sidebar: sources, navigation, saved views, and compact search.
+- Main pane: the user's primary object and dominant workflow.
+- Inspector: properties and secondary controls for the current selection.
+- Toolbar: current context and actions, never a second page header.
+
+Every pane must use `min-h-0 min-w-0`. The element containing long content owns
+`overflow-auto`; headers and footers remain fixed.
+
+## Chat clearance
+
+`installMoldableFrameLifecycle()` applies the embedded host's chat state to the
+shared token. `AppFrameContent` consumes it by default. In layouts that own
+their own scroll region, set `chatSafe={false}` on `AppFrameContent` and add
+`pb-[var(--chat-safe-padding)]` or an equivalent `calc()` only to that region.
+Do not pad every ancestor.
+
+The token is `0px` in a standalone app window. Chat belongs to the central
+orchestrator rather than being recreated inside every app.
+
+## Narrow widths
+
+Collapse optional inspectors before truncating the primary task. At narrow
+widths, preserve action reachability, focus order, and readable labels.
+
+## Multiwindow ownership
+
+Each app window owns its local navigation, selection, loading, empty, error,
+and save feedback. Workspace identity, app process lifecycle, native
+permissions, and orchestration remain host-owned. Never assume another visible
+window can supply a missing app state.

package/docs/component-catalog.md

@@ -0,0 +1,82 @@
+# Component catalog
+
+The catalog turns component review into a deterministic matrix rather than a
+set of hand-picked screenshots. Import the catalog utilities from the separate
+subpath so production app bundles do not pull in review infrastructure.
+
+```tsx
+import {
+  ComponentCatalog,
+  createCatalogManifest,
+} from '@moldable-ai/ui/catalog'
+
+const manifest = createCatalogManifest({
+  title: 'App UI',
+  sections: [
+    {
+      id: 'controls',
+      title: 'Controls',
+      stories: [
+        {
+          id: 'primary-action',
+          title: 'Primary action',
+          components: ['button'],
+          interactions: ['rest', 'focus-visible', 'disabled', 'loading'],
+          render: ({ interaction }) => (
+            <Button
+              autoFocus={interaction === 'focus-visible'}
+              disabled={interaction === 'disabled'}
+            >
+              Continue
+            </Button>
+          ),
+        },
+      ],
+    },
+  ],
+})
+
+<ComponentCatalog manifest={manifest} />
+```
+
+## Required review matrix
+
+Every public interactive component should cover:
+
+- light and dark themes;
+- regular and compact density;
+- wide and narrow viewports;
+- standard accessibility behavior plus reduced transparency, increased
+  contrast, and reduced motion where material or motion is part of the recipe;
+- rest, focus-visible, disabled, invalid, selected, loading, and empty states
+  where those states apply;
+- keyboard behavior in unit tests.
+
+`buildCatalogCases()` generates stable case IDs and supports filtering, which
+lets a visual-regression runner capture one addressable case at a time. Keep
+catalog stories deterministic: fixed content, fixed dates, no network calls,
+and no animation unless motion itself is under review.
+
+Accessibility environments are opt-in per story through
+`accessibilityModes`. Standard cases preserve the existing case ID; a
+nonstandard mode is appended as the final segment. The catalog maps those
+modes to deterministic `data-transparency`, `data-contrast`, and `data-motion`
+attributes.
+
+## Public component accountability
+
+Every story declares the public visual component modules it exercises through
+`components`. The core catalog test reads the barrel exports from
+`components/ui/index.ts` and requires every module to be either:
+
+- named by at least one deterministic story; or
+- listed in `coreCatalogExclusions` with a concise reason.
+
+Exclusions are visible debt, not permanent exemptions. Remove an exclusion in
+the same change that adds representative stories. Unknown component ids, stale
+exclusions, duplicate exclusions, and empty reasons fail the catalog test.
+
+The core catalog covers window materials, semantic controls, collections,
+navigation, representative popover material, and feedback recipes. Complex
+portals and geometry-dependent components remain explicitly deferred until an
+isolated browser fixture can make their states deterministic.

package/docs/component-guide-template.md

@@ -0,0 +1,37 @@
+# Component guide template
+
+Use this structure for each public component family.
+
+```markdown
+# Component
+
+One-sentence intent.
+
+## When to use
+
+## When not to use
+
+## Anatomy
+
+## Usage
+
+## Variants and sizes
+
+## API
+
+## States and interaction
+
+## Keyboard and accessibility
+
+## Platform behavior
+
+## Do
+
+## Don't
+
+## Testing
+```
+
+Document the real exported API. Include neighboring-component decisions and
+the states callers must implement. Keep examples compact and use semantic
+theme tokens.

package/docs/design-tokens.md

@@ -0,0 +1,185 @@
+# Design tokens
+
+The token system makes an interface feel consistent before it makes it
+distinctive. Use semantic roles from `@moldable-ai/ui/styles`; do not choose
+raw palette values, one-off control dimensions, or custom easing curves in app
+chrome.
+
+Tokens are CSS custom properties so they work in React, plain CSS, canvas
+overlays, and host-provided webviews. Tailwind aliases are provided for the
+roles that are useful in markup.
+
+## Token layers
+
+1. **Theme primitives** such as `--background`, `--foreground`, and
+   `--primary` preserve the shadcn-compatible theme contract.
+2. **Semantic roles** such as `--surface-recessed`, `--text-secondary`, and
+   `--control-pressed` describe intent.
+3. **Component recipes** combine roles into a complete control or layout.
+
+Apps should primarily use layer two through shared components or the Tailwind
+aliases below. Override theme primitives to brand a complete app. Override a
+semantic role only when the meaning of that role changes for the entire
+subtree.
+
+## Typography
+
+The default UI font is the platform sans-serif stack. Monospaced text uses the
+platform monospace stack. Prefer `Text` for normal interface copy; the token
+utilities are useful for display-scale titles and highly composed canvases.
+
+| Role    | CSS token          | Tailwind utility  | Use                                |
+| ------- | ------------------ | ----------------- | ---------------------------------- |
+| Display | `--type-display-*` | `text-ui-display` | One dominant app or document title |
+| Heading | `--type-heading-*` | `text-ui-heading` | Primary view heading               |
+| Title   | `--type-title-*`   | `text-ui-title`   | Major section title                |
+| Body    | `--type-body-*`    | `text-ui-body`    | Dense working content              |
+| Label   | `--type-label-*`   | `text-ui-label`   | Controls and metadata              |
+| Caption | `--type-caption-*` | `text-ui-caption` | Timestamps and compact annotations |
+
+Use display type sparingly. A large title can establish a focused canvas, but
+it should not force every utility screen into a marketing-page hierarchy.
+Prefer `font-sans` and `font-mono` over naming a platform font directly.
+
+## Density
+
+Density is contextual, not a global scale transform. Place `data-density` on
+the smallest pane that needs a different rhythm:
+
+```tsx
+<section data-density="compact">
+  <Toolbar>{/* compact desktop actions */}</Toolbar>
+  <div className="min-h-row">{/* selectable row */}</div>
+</section>
+```
+
+Supported values are:
+
+- `compact`: inspectors, source lists, and toolbars.
+- default (attribute omitted): general app UI.
+- `comfortable`: touch-forward or presentation-oriented surfaces.
+
+The scope sets control heights, row and toolbar heights, gaps, inline padding,
+pane padding, and section spacing. Utilities include `h-control-xs`,
+`h-control-sm`, `h-control-md`, `h-control-lg`, `min-h-row`, `min-h-toolbar`,
+`gap-control-gap`, `px-control-inline`, `p-pane`, and `gap-section`.
+
+Component size or density props remain authoritative when supplied. Do not use
+density to shrink labels below readable sizes or to make a pointer-only target
+difficult to acquire.
+
+## Text and surfaces
+
+Use the narrowest semantic role that describes the region:
+
+| Role                 | Tailwind alias        | Purpose                           |
+| -------------------- | --------------------- | --------------------------------- |
+| `--text-primary`     | `text-text-primary`   | Primary content                   |
+| `--text-secondary`   | `text-text-secondary` | Supporting content                |
+| `--text-tertiary`    | `text-text-tertiary`  | De-emphasized metadata            |
+| `--text-disabled`    | `text-text-disabled`  | Unavailable content               |
+| `--surface-canvas`   | `bg-surface-canvas`   | Primary work surface              |
+| `--surface-raised`   | `bg-surface-raised`   | Bounded content above the canvas  |
+| `--surface-recessed` | `bg-surface-recessed` | Wells and subordinate regions     |
+| `--surface-sidebar`  | `bg-surface-sidebar`  | Source navigation                 |
+| `--surface-toolbar`  | `bg-surface-toolbar`  | Translucent window or pane chrome |
+| `--surface-overlay`  | `bg-surface-overlay`  | Menus, popovers, and toasts       |
+| `--surface-selected` | `bg-surface-selected` | Selected collection items         |
+
+Use `border-separator` for ordinary pane boundaries and
+`border-separator-strong` when the boundary must remain clear over imagery or
+a busy canvas. Avoid stacking raised surfaces inside cards merely to create
+visual hierarchy; whitespace and a separator are usually quieter.
+
+## Control states
+
+Control state roles are shared across buttons, rows, grid items, segmented
+controls, and fields:
+
+- `--control-hover`
+- `--control-pressed`
+- `--control-selected`
+- `--control-selected-foreground`
+- `--control-disabled`
+- `--control-focus`
+- `--control-invalid`
+
+A complete recipe covers rest, hover, pressed, focus-visible, selected,
+disabled, and invalid states. Disabled wins over pointer states. Focus remains
+visible when combined with selected or invalid. Selection is durable state;
+hover is not a substitute for it.
+
+Do not use state-layer colors as arbitrary fills. Prefer the shared component
+when one exists.
+
+## Shape and materials
+
+Use `rounded-control`, `rounded-container`, and `rounded-overlay` to keep
+related objects visually consistent. `rounded-window` is host-informed and
+normally only useful in previews; the native host owns the actual window
+shape.
+
+Adaptive material has two semantic variants. Each includes fill, fallback,
+border, highlight, blur, and saturation tokens:
+
+- `--material-regular-*` supports normal toolbar and control chrome.
+- `--material-clear-*` supports compact controls over media or a richly
+  colored canvas.
+- `shadow-panel`, `shadow-overlay`, and `shadow-window` provide elevation
+  independently from translucency.
+
+Use `Material` and `MaterialGroup` instead of assembling those tokens in app
+markup. `MaterialGroup` owns one sampled layer for a related control cluster;
+its children must not add nested material.
+
+Translucency must have an opaque fallback. The token system removes blur and
+uses opaque toolbar and overlay surfaces when the operating system requests
+reduced transparency or an ancestor has `data-transparency="reduced"`.
+Unsupported renderers stay on the same opaque fallback. Increased contrast
+makes fills more opaque and strengthens their borders.
+
+Material is a control and navigation affordance. Primary canvases, documents,
+tables, calendars, forms, cards, sheets, and inspectors remain opaque. See
+[Adaptive materials](./adaptive-materials.md) for composition rules.
+
+## Motion
+
+Use motion to explain entry, exit, reordering, or a state transition:
+
+| Purpose                         | Duration                    | Easing                   |
+| ------------------------------- | --------------------------- | ------------------------ |
+| Immediate feedback              | `--motion-duration-instant` | `--motion-ease-standard` |
+| Hover and press                 | `--motion-duration-fast`    | `--motion-ease-standard` |
+| Popover or selection transition | `--motion-duration-normal`  | `--motion-ease-enter`    |
+| Large surface transition        | `--motion-duration-slow`    | `--motion-ease-enter`    |
+
+`ease-standard`, `ease-enter`, `ease-exit`, and `ease-spring` are available as
+Tailwind utilities. Use the duration variables directly or with an arbitrary
+value such as `duration-[var(--motion-duration-fast)]`.
+
+Reduced-motion preferences collapse token durations to 1ms and remove
+decorative package animations. Components must still render their final state
+without depending on an animation callback.
+
+## Contrast and themes
+
+Light and dark themes share semantic names. Never branch app behavior on a
+specific color value. Increased-contrast preferences strengthen separators,
+state layers, and tertiary text. Forced-color mode maps semantic roles to
+system colors and removes material shadows.
+
+Test at minimum:
+
+- Light and dark.
+- Default and increased contrast.
+- Reduced motion and reduced transparency.
+- Compact and comfortable density.
+- Focus-visible, selected, disabled, and invalid states in combination.
+
+## Adding a token
+
+Add a token only when the decision repeats across component families. Name it
+for its role, provide light and dark behavior when necessary, define
+accessibility fallbacks, expose a Tailwind alias only if it improves normal
+composition, and document the intended use. A component-specific visual tweak
+belongs in that component recipe instead.

package/docs/foundations.md

@@ -0,0 +1,58 @@
+# Foundations
+
+## Character
+
+Moldable apps are local working instruments, not websites or SaaS dashboards.
+The interface should be calm, compact, direct, and organized around the user's
+objects. Decoration must clarify hierarchy or state.
+
+## Hierarchy
+
+Use `Text` roles instead of rebuilding typography from arbitrary utilities.
+Most desktop chrome should use `regular`, `strong`, `small`, or
+`small-strong`. Reserve `heading1` for a view's primary title and `heading2`
+for a major section.
+
+Use one obvious accent action in a region. Secondary actions should be quiet.
+Status color communicates status only; it is not decoration.
+
+## Density
+
+- Compact controls are the default in toolbars and inspectors.
+- Preserve usable pointer targets even when the visible control is small.
+- Prefer separators, background shifts, and whitespace over nested cards.
+- Working panes own scrolling. The window shell should not accidentally scroll.
+- Set `data-density="compact"`, `"default"`, or `"comfortable"` at a
+  composition boundary. Components should consume density tokens rather than
+  inventing per-screen heights.
+
+## Surfaces
+
+- `background`: primary work surface.
+- `muted`: subordinate region, well, or quiet selection context.
+- `sidebar`: navigation/list source surface.
+- `popover`: temporary floating surface.
+- `card`: bounded content group, not a universal page wrapper.
+
+Use semantic tokens only. Do not introduce raw gray, zinc, white, or black
+classes in app UI.
+
+Use adaptive material only for navigation and control layers. Regular material
+supports toolbars and grouped controls; clear material is reserved for compact
+controls over media. Content canvases and content-bearing surfaces stay
+opaque. Group related controls under one sampler and never nest material
+effects.
+
+## Motion
+
+Motion explains state or continuity. Keep it brief and honor
+`prefers-reduced-motion`. Pulse only for live activity; a static notification
+does not pulse.
+
+Use the shared duration and easing tokens. Do not make routine controls feel
+springy, and do not animate layout merely to make a screen feel active.
+
+## Focus
+
+Keyboard focus must remain visible against every surface. Do not remove a
+focus ring unless the replacement is at least as clear.

package/docs/native-integration.md

@@ -0,0 +1,33 @@
+# Native integration
+
+Renderer components should feel compatible with macOS without pretending to be
+native controls. Use a host-native control only when Moldable exposes a shared,
+transport-neutral capability for it.
+
+## Selection policy
+
+1. Prefer a real Moldable host contract when the operation is inherently
+   platform-owned, such as sharing, file selection, or a system permission.
+2. Use the shared renderer component when its semantics are app-owned.
+3. Provide an accessible renderer fallback only when the product contract
+   defines what happens on desktop, iOS, and remote clients.
+
+Do not create UI-only no-op stubs for native menus, share sheets, or date
+pickers. First define ownership, cancellation, errors, replay/reconnect
+behavior, and platform fallbacks.
+
+`DateField` is the portable renderer baseline. A future system date picker,
+share sheet, or native menu must only be selected after the host advertises the
+service through a versioned context. Requests must remain bound to the
+originating app window and user activation.
+
+Standalone windows should remain host-owned surfaces around an app frame. Do
+not load arbitrary app URLs directly into a privileged native webview merely to
+gain window chrome.
+
+## Platform details
+
+Use toolbars, panes, compact controls, keyboard commands, restrained material,
+and clear selection state to achieve platform affinity. Do not copy private
+framework code, undocumented IPC, proprietary fonts, or host-specific symbol
+plumbing.

package/docs/standalone-app-windows.md

@@ -0,0 +1,136 @@
+# Standalone app windows
+
+Moldable apps should work as focused windows as well as embedded views. The
+same app surface must survive either presentation without imitating operating
+system chrome or assuming that a global desktop shell is present.
+
+## Ownership boundary
+
+| Layer             | Owns                                                                                                                              |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Native host       | Window creation, close/minimize/zoom controls, dragging, resize regions, focus state, system menus, share sheets, and safe insets |
+| Shared UI package | Semantic window tokens, app-level layout recipes, accessible controls, density, and embedded fallbacks                            |
+| App               | Title, document context, primary canvas, toolbars, navigation, selection, and app-specific state                                  |
+| Orchestrator      | Cross-app commands, conversation, launching, and switching; it is not permanent app chrome                                        |
+
+Do not draw traffic-light controls or recreate a title bar in React. When a
+platform cannot provide a native capability, expose it through a host contract
+or use a clearly web-native fallback.
+
+## Window inset contract
+
+The stylesheet defines a renderer boundary with zero-value browser-safe
+defaults:
+
+- `--window-safe-area-top`
+- `--window-safe-area-inline-start`
+- `--window-safe-area-inline-end`
+- `--window-safe-area-bottom`
+- `--window-titlebar-height`
+- `--window-drag-region-height`
+- `--window-control-inset-inline-start`
+- `--window-control-inset-inline-end`
+- `--window-content-inset-top`
+- `--window-content-inset-inline-start`
+- `--window-content-inset-inline-end`
+- `--window-content-inset-bottom`
+- `--window-corner-radius`
+
+The host may set the primitive safe-area, titlebar, and control inset values on
+the document root. Composite content insets then resolve automatically. The
+transport used to deliver those values belongs to the host integration layer,
+not individual apps.
+
+Dedicated windows use the host titlebar by default. An app with a unified
+toolbar can declare `{ "window": { "titlebar": "app" } }` in `moldable.json`.
+In that mode the host removes its strip and advertises the titlebar height and
+leading window-control inset. `AppFrameTitlebar` consumes those values, sends
+`startWindowDrag` on a non-interactive pointerdown, and sends
+`titlebarDoubleClick` on a non-interactive double-click. The latter toggles
+maximize as a cross-platform approximation of the macOS titlebar zoom action.
+
+Window appearance roles are `--window-chrome-background`,
+`--window-chrome-foreground`, `--window-chrome-muted-foreground`,
+`--window-border`, and `--material-shadow-window`. The host may update the
+foreground roles when a window becomes inactive. Apps must not infer focus
+from pointer events.
+
+## A portable root
+
+Keep the root bounded and make one descendant own each scroll region:
+
+```tsx
+<main
+  className="bg-surface-canvas text-text-primary flex h-dvh min-h-0 min-w-0 flex-col overflow-hidden"
+  style={{
+    paddingTop: 'var(--window-content-inset-top)',
+    paddingInlineStart: 'var(--window-content-inset-inline-start)',
+    paddingInlineEnd: 'var(--window-content-inset-inline-end)',
+    paddingBottom: 'var(--window-content-inset-bottom)',
+  }}
+>
+  <Toolbar>{/* app title and primary actions */}</Toolbar>
+  <PanelContent>{/* the primary canvas or collection */}</PanelContent>
+</main>
+```
+
+This conservative layout places app chrome below any overlay titlebar. A
+future shared window-shell recipe may integrate a toolbar into a host-declared
+drag region, but only the platform adapter should mark draggable and
+non-draggable areas.
+
+In embedded presentation all window insets resolve to zero. If chat overlays
+the app, the owning bottom scroll region uses `--chat-safe-padding`. A
+standalone window must not reserve that space unless the orchestrator is
+actually overlaid in that window.
+
+## Window-shaped information architecture
+
+A standalone app should identify itself without relying on a global sidebar:
+
+- Put the current app or document identity in its own top region.
+- Keep the primary object visually dominant.
+- Place frequent tools near the edge of the canvas they affect.
+- Use a sidebar or inspector only when the task needs one.
+- Keep primary actions reachable at narrow widths.
+- Make empty and onboarding states feel like the app, not a generic dialog.
+
+Large, single-purpose canvases can use display typography and generous space.
+Dense utilities should retain compact controls and stronger information
+hierarchy. Native feeling comes from predictable focus, keyboard behavior,
+selection, materials, and restraint—not from decorative window chrome.
+
+## Multi-window state
+
+Treat each window as an independent client of shared product APIs:
+
+- Give each window its own React root, focus, selection, and transient UI
+  state.
+- Keep durable workspace data behind the same authoritative API used by
+  embedded and remote clients.
+- Make document and route identity explicit so a window can reconnect or
+  restore without a process-global singleton.
+- Define ordering, replay, and conflict behavior for live shared state.
+- Keep binary assets addressable; do not place large payloads in window or
+  conversation events.
+
+Closing one window must not imply closing an app service or discarding another
+window's state. System menu, share, file, and date behavior should remain
+behind platform-neutral capability contracts with native adapters.
+
+## Verification matrix
+
+Every app shell or shared window recipe should cover:
+
+- Embedded and standalone presentation.
+- Active and inactive native windows.
+- Light and dark appearance.
+- Narrow, default, and wide sizes.
+- Keyboard-only use and visible focus.
+- Increased contrast, reduced motion, and reduced transparency.
+- Empty, loading, error, ready, and offline or disconnected states.
+- Reopen or reconnect with durable state intact.
+
+Visual regression fixtures should capture the same canonical states at stable
+viewport sizes. Interaction tests should verify focus movement, selection,
+resize behavior, and that window controls remain host-owned.