@nextop-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:

import "@nextop-os/workbench-surface/styles.css";

Hosts that already import @nextop-os/ui-system/styles.css elsewhere may keep doing so, then import @nextop-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.

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.

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.

External business state is not written to the Workbench snapshot. The snapshot stores shell state such as nodes, frames, stack order, and host node metadata. Snapshots are sanitized before save so business payloads such as paths, URLs, cwd, runtime status, or activation payloads 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.

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

Hosts own the safe-area values they provide for their shell chrome. 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.