tutti/docs/conventions/workbench.md

Workbench

This document defines durable Workbench ownership rules across shared packages, the desktop renderer host, and tuttid snapshot persistence.

Purpose

Workbench is a reusable shell for workspace tools. It owns window-like interaction mechanics, layout, dock identity, node shell lifecycle, and snapshot sanitation.

It must not become a product workflow core.

Ownership

Current ownership:

• packages/workbench/snapshot owns the canonical TypeScript snapshot contract, migrations, normalization, validation, and JSON Schema.
• packages/workbench/service owns shared Go snapshot validation, canonicalization, and the storage-facing service contract.
• packages/workbench/electron owns product-neutral Electron main-process Dock preview capture and bounded filesystem cache mechanics.
• packages/workbench/surface owns reusable Workbench mechanics: controller commands, host/session reconciliation, placement, stacking, dock rendering, window chrome, render context plumbing, and shell snapshot sanitation.
• apps/desktop/src/renderer/src/features/workspace-workbench owns the Tutti desktop host adapter: product contributions, tuttid clients, preload adapters, workspace context, close policy, launch policy, and desktop-owned Workbench copy.
• services/tuttid/service/workspace owns daemon-side Workbench snapshot load, save, and host-specific snapshot reconciliation before a snapshot is returned to desktop.

Shared Package Rules

packages/workbench/* should stay product-neutral.

Rules:

• keep product-specific node bodies, daemon clients, preload calls, host path selection, unrestricted filesystem access, and workflow policy out of shared Workbench packages
• let @tutti-os/workbench-electron accept a host-selected cache directory and Electron webContents; IPC authorization, BrowserWindow ownership, product logging, and app.getPath("userData") stay in the consuming desktop app
• keep product-specific CSS selectors and host globals out of @tutti-os/workbench-surface
• restore a minimized node from its in-memory Genie texture before launching the mounted node when the cached texture and Dock anchor are usable; allow that first texture frame to paint before host launch work begins
• attempt the host-provided native Dock preview capture before cloning live DOM; clone DOM only after native capture fails or exceeds the bounded wait, and persist a late result's Dock image immediately but defer its full-size decode until the active Genie animation settles and the browser is idle
• for Electron hosts, derive the full-size Genie image and bounded Dock image from one region capture; never upscale the Dock image into a Genie texture
• bound retained Genie Canvas textures by both entry count and estimated RGBA bytes; retain restored-node textures for later minimizes, and remove them when their nodes no longer exist
• publish Genie-hidden state through per-node subscriptions so changing one window does not invalidate every mounted Workbench window
• use per-node operation tokens for Genie hiding; global animation generation may control the shared Canvas but must not block another node from becoming visible
• project normal-window visibility through the mounted body context; it is false while minimized, Genie-hidden, or in Mission Control, so heavy child presentation can wait without importing Workbench animation state
• project Mission Control preview visibility separately from normal-window visibility. A preview that Workbench paints must keep its body rendering even when normal-window visibility is false; a preview filtered out of the presentation must remain paused
• separate a node's own exposure from whether it may occlude lower nodes. Scale restore, shell frame transitions, and onboarding entry keep their own body visible but do not cover lower bodies until the matching DOM animation or transition settles; overlapping transitions release independently
• order geometric occlusion by rendered surface layer before normal window stack order. A dialog-popover node remains above default-layer nodes even when the normal focus stack changes
• keep window chrome hit zones unambiguous; floating-window resize handles should render outside the clipped window surface so corner handles remain reachable and take precedence over header drag regions; interactive controls inside or near draggable chrome must opt out with the product no-drag classes and -webkit-app-region: no-drag, but noninteractive wrappers should not shrink the draggable hot zone
• inject debug diagnostics, product callbacks, and host-specific behavior through explicit props or adapters
• keep WorkbenchHostHandle narrow; product consumers should call public host commands instead of reaching into the raw controller
• expose raw controller access only through an internal runtime handle used by Workbench surface internals
• keep package root exports intentionally small; exporting a symbol makes it a stable interface, not just a convenient file shortcut

Shared packages may own narrow default copy for generic Workbench mechanics, such as chrome and dock labels. Product-owned copy stays in the consuming host i18n layer.

Snapshot State Rules

Workbench snapshots persist shell-owned presentation state plus explicit host-owned node state.

Rules:

• snapshotNodeState is the only persisted node extension field for host-owned node state
• externalNodeState is runtime render input, not a persisted compatibility field
• node state sources should expose snapshot state through getSnapshotNodeState(...)
• snapshot sanitizers and session serialization must strip transient runtime render data before persistence
• snapshot serialization must persist layoutBasis from the same Workbench state as the frames. On initial restore, map frame, restoreFrame, space frames, and reusable closed-window frames from that basis into the current safe layout before exposing a restored floating frame
• keep layoutBasis additive within schema version 1. Snapshots that predate it remain valid and use conservative bounds normalization; do not invent a historical surface size because that would turn unknown geometry into a misleading proportional migration
• persist lockedLayout with the same snapshot as its node frames. On restore, retain it only when at least two locked nodes are restored, so Mission Control keeps its proportional grid and any user-adjusted divider geometry after a Workspace reopen
• canonicalize locked frame coordinates to three decimal places, then clamp width and height to the normalized right and bottom edges. The daemon may accept only bounded float32 transport noise before storing this canonical form
• adapter-specific durable state should remain behind generic contract fields unless the adapter detail is part of the shared snapshot contract
• desktop-owned workspace Dock retention is product metadata in the workspace Workbench snapshot. Preserve explicit false values as user choices and merge them through the repository's product-owner path so ordinary host saves cannot overwrite them
• treat retention as a Dock presentation override. Product hosts must pass it through dockEntryPresentationOverrides; they must not rewrite contribution Dock entries or let presentation state flow into contribution nodes/runtime configuration. WorkbenchHost applies overrides in place after Dock entries are merged so presentation changes preserve entry order and host sessions

Breaking migration rule:

• when the snapshot contract intentionally removes a compatibility field, do not keep silent fallback code in the renderer or daemon; make the break explicit and update tests around the new durable contract

Desktop Host Rules

The desktop workspace Workbench is a host adapter, not a React page that owns Workbench workflows.

Rules:

• keep product contribution factories and host adapter assembly in workspace-workbench/services/internal/**
• expose public service/controller seams from workspace-workbench/services/* when UI needs model data or commands
• keep workspace-workbench/ui/** shallow: render snapshots, subscribe through hooks, and forward DOM events to services or controllers
• do not import workspace-workbench/services/internal/** from workspace-workbench/ui/**
• keep daemon reads, writes, save requests, object URL lifecycle, and similar side effects in feature services or controllers, not node body React files
• keep launchpad option projection, provider catalog shaping, and stable Workbench node id helpers behind public desktop service seams

The mechanical guard for the Workbench UI-to-internal rule is:

pnpm check:renderer-boundaries

Daemon Reconciliation Rules

services/tuttid/service/workspace may reconcile Workbench snapshots with daemon-owned runtime state before returning them to desktop.

Rules:

• keep the core WorkbenchService focused on load, save, validation, canonicalization, and calling the configured reconciler
• put node-kind-specific cleanup behind a WorkbenchSnapshotReconciler implementation
• wire host-specific reconcilers explicitly in services/tuttid/wiring.go
• do not hide a fallback to a concrete node-kind service inside WorkbenchService

This keeps the service interface small while preserving locality for daemon runtime cleanup such as terminal session reconciliation.

Review Questions

When reviewing Workbench changes, ask:

1. Is this generic Workbench mechanics, or product workflow policy?
2. Is durable state going through snapshotNodeState, or is runtime externalNodeState leaking into persistence?
3. Does UI depend on a public service/controller seam instead of services/internal/**?
4. Does a product consumer need a narrow host command, or is it trying to grab the raw controller?
5. Is daemon reconciliation behind an explicit reconciler, or is node-specific logic being added to the core Workbench service?