源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)
Publish Claude Code Binaries / Stage and publish binaries (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-arm64 (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build linux-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build windows-amd64 (push) Canceled after 0s
Sync Tutti Agent Skills / sync (push) Canceled after 0s
Windows Agent Adapters / Test Windows agent adapters (push) Canceled after 0s
Windows Daemon Adapters / Test Windows daemon adapters (push) Canceled after 0s
Publish Tutti App Runtime / Publish runtime catalog (push) Canceled after 0s
Publish Claude Code Binaries / Stage and publish binaries (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-arm64 (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build linux-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build windows-amd64 (push) Canceled after 0s
Sync Tutti Agent Skills / sync (push) Canceled after 0s
Windows Agent Adapters / Test Windows agent adapters (push) Canceled after 0s
Windows Daemon Adapters / Test Windows daemon adapters (push) Canceled after 0s
Publish Tutti App Runtime / Publish runtime catalog (push) Canceled after 0s
This commit is contained in:
commit
2ed3415fb7
8018 files changed
+1936476
No files matched your search
@@ -0,0 +1,206 @@
|
||||
# @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.
|
||||
Reference in new issue
Block a user