# @tutti-os/workbench-surface Shared React workbench surface primitives for rendering neutral workbench nodes. Consumers can import the workbench surface stylesheet once from the application shell. It pulls in the shared UI-system defaults first, then layers the workbench structural styles on top: ```ts import "@tutti-os/workbench-surface/styles.css"; ``` Hosts that already import `@tutti-os/ui-system/styles.css` elsewhere may keep doing so, then import `@tutti-os/workbench-surface/styles.css` for the structural layer. The package owns workbench surface behavior, frame-level rendering contracts, and shell snapshot persistence mechanics. Applications still own product state, node bodies, business persistence, and persistence adapters, while window-chrome i18n now flows through the shared app-level i18n runtime instead of injected label objects. ## Host State And Lifecycle Boundaries `WorkbenchHost` owns shell mechanics: - projected node reconciliation - launch request dispatch - opening, restoring, and focusing windows - dock rendering and default window actions - snapshot persistence for shell state The consuming host owns product behavior: - business instance creation and reuse policy - external node and workspace business state - business-state commits and reducers - close policy for host-owned instances - external store subscriptions When a node body or header needs host-owned business state, pass an `externalStateSource`. The source is read into render context as `externalNodeState` and `externalWorkspaceState`. If the source exposes `subscribe(...)`, the host re-renders when that subscription notifies. Node body and header contexts expose `isDragging` and `isResizing`. The Workbench shell continues applying live frame geometry during direct manipulation. Window position is shell-owned: changing only `frame.x` or `frame.y` does not render a body during drag or resize. Width and height changes remain live, as do changes to node data, external state, focus, visibility, or interaction state. The body always renders after the interaction settles so the final committed frame reaches responsive layout. Body actions that need execution-time window position should read the current node from `context.host.getSnapshot()` instead of closing over a rendered position. Translated window boundaries keep using their window rect for menu clamping, but viewport-positioned menus portal to `document.body` so fixed coordinates are not offset a second time by the window translation. Headers keep live frame renders by default. A definition may provide `getHeaderFrameRenderKey(context)` when several intermediate frames produce the same visible header layout. During drag or resize, equal primitive keys skip `renderHeader`; changes to node data, external state, focus, or interaction state still render. Call `context.windowActions.getFrame()` inside actions that need execution-time geometry instead of closing over a frame omitted from the key. Host-owned business instances are represented with `projectedNodes`. A projected node tells the workbench that a shell should currently exist for a host-owned instance; the workbench reconciles that presence with snapshot layout and live shell state. Dock entries are configured at the host level through `dockEntries`, separate from node definitions. Dock entry identity drives slot ordering, grouping, anchor lookup, popup aggregation, badge state, and launch payload dispatch. Entries may also provide host-owned popup metadata through `resolvePopupItem(...)` and `capturePopupItemPreview(...)`, plus custom badge content when the default count or status shapes are not enough. Component-based dock previews should render their host-owned body through `WorkbenchDockComponentPreviewFrame`. The frame owns source-to-viewport scaling, clipping, centering, and the non-interactive preview boundary. Preview children are decorative and never participate in pointer hit testing; the Dock button remains the only interaction owner even if frozen preview markup is replaced between pointer events. Popup preview providers receive the canonical target size through `item.previewViewport`; use that value instead of duplicating Dock card dimensions in a consuming host. Presentation-only changes to merged Dock entries belong in `dockEntryPresentationOverrides`. `WorkbenchHost` applies these overrides by entry id after contributions and explicit entries are merged, preserving Dock order without changing contribution nodes or rebuilding the host session. Use this seam for host-owned visibility and retention presentation; keep product preference persistence in the consuming host. Dock, shortcut, and command opens flow through `launchNode(...)` and the optional `onLaunchRequest(...)` callback. The host may create a business instance asynchronously, then return the shell identity, title, default frame, required `framePolicy` (`"cascade"` to offset from the active node or `"absolute"` to keep host coordinates), stable `dockEntryId`, and optional one-shot activation payload. Activations and launch payloads are transient render signals and are not persisted. Runtime external business state is not written to the Workbench snapshot. Hosts that need durable node-specific state should expose it through `getSnapshotNodeState(...)`; Workbench stores that value as `snapshotNodeState`. Node bodies that need live-only coordination can write `runtimeNodeState` through `setNodeRuntimeState(...)`; refresh-safe state uses `setSnapshotNodeState(...)`. The snapshot also stores shell state such as nodes, frames, stack order, and host node metadata. Snapshots are sanitized before save so transient render data such as activation payloads, runtime status, or live subscriptions do not become layout truth. Hosts that need to address shells from outside a render context can use `createWorkbenchHostProjectedNodeId(...)` for projected presence and `createWorkbenchHostLaunchedNodeId(...)` for launch-created shells. These helpers only derive stable shell ids; layout restore and stack reconciliation remain owned by `WorkbenchHost`. ## Contributions Hosts may keep using the explicit `WorkbenchHost` props directly. For larger hosts, `WorkbenchHost` also accepts optional `contributions` that can provide node definitions, dock entries, external state, launch handlers, and node-close handlers. Contributions may also provide `prepareHostClose(...)` when a module needs to finish or cancel host-wide close before the consuming app closes its workbench shell. Contributions are additive. Explicit top-level props remain supported and keep override authority for compatibility: - explicit `nodes` override contribution nodes with the same `typeId` - explicit `dockEntries` override contribution dock entries with the same `id` - explicit `externalStateSource` fully replaces contribution external-state sources - explicit launch and node-close handlers run before contribution handlers Top-level shell inputs such as `snapshotRepository`, `workspaceId`, `missionControl`, layout constraints, wallpaper, and chrome renderers remain owned by the consuming host rather than contributions. The consuming host also decides when to invoke host-close preparation; `workbench-surface` only owns the contribution contract and deterministic composition helper. For hosts that already use contributions, new workbench modules should prefer adding a contribution instead of adding more feature-specific node, dock, external-state, or launch wiring to a centralized host assembly service. ## Layout Semantics `packages/workbench/surface` owns frame geometry for floating, snapped, and fullscreen nodes. Layout rules: - floating nodes respect the full configured safe area - top-snapped nodes use the normal safe layout and preserve bottom safe area - fullscreen nodes respect top, left, and right safe area, but ignore bottom safe area so immersive content can reach the bottom edge of the workbench surface - persisted snapshots record the surface and layout constraints that produced their frames; initial restore maps node frames, fullscreen restore frames, space frames, and reusable closed-window frames into the current safe layout - legacy snapshots without a layout basis remain readable; fullscreen geometry is recomputed and hidden restore frames are clamped before they become floating windows The package ships a baseline host layout default so new integrations do not start with windows tucked under shared chrome. Today that default uses: - `minWidth: 280` - `minHeight: 160` - `safeArea.top: 52` - `safeArea.bottom: 88` Hosts should override `layoutConstraints` when their shell chrome differs. They should not duplicate fullscreen bottom-safe-area correction outside this package. ## Host Reuse Pattern When another host wants to reuse this package: 1. Keep workbench controller state, shared window mechanics, and default workbench host plus chrome i18n resources in this package. 2. Keep host-owned node bodies, business state, reducers, commits, persistence, routing, and product-specific workbench wording in the consuming host. 3. Create one host-level i18n runtime that merges: - host-owned workbench i18n resources - `workbenchHostI18nResources` - `workbenchWindowChromeI18nResources` - any other shared package i18n resources used by the same shell 4. Let the host surface and window chrome scope that runtime into the workbench namespaces with `createWorkbenchHostI18nRuntime(...)` and `createWorkbenchWindowChromeI18nRuntime(...)`. 5. Use `externalStateSource` for read-only render context injection and `projectedNodes` for host-owned presence such as terminal sessions, agent sessions, or browser records. 6. Provide explicit `dockEntries` for host chrome navigation instead of relying on node type order or node-definition dock metadata. 7. Use `onLaunchRequest` for dock, shortcut, and command opens that require host-owned instance creation before a shell appears. 8. Use `onNodeCloseRequest` when a close button needs host policy instead of a direct shell removal. This keeps generic workbench mechanics reusable while leaving product behavior and host integration in the owning app or service.