@konitif/workbench-runtime 0.284.1 → 0.284.2

package/README.md

@@ -1,60 +1,63 @@
 # @konitif/workbench-runtime
 
-Public runtime orchestration for a KONITIF Workbench. It connects Workbench contracts to reactive application state without owning product semantics.
+Reactive Svelte host adapter for assembling public KONITIF Workbench contracts
+with explicit runtime ports.
 
-Products compose this runtime and provide their own tools, widgets, persistence adapters and policies.
+## Installation
 
-## Autonomous distribution
+```sh
+npm install @konitif/workbench-runtime
+```
+
+## What it provides
+
+- Reactive Workbench stores and shell actions.
+- Workspace history and synchronization controllers.
+- Explicit ports for persistence, host events and detached windows.
+- A runtime assembly entry that selects no browser providers by default.
 
-Run `npm run build`, `npm test` and `npm run verify:package` from this
-repository. The build emits ESM and declarations into `dist`; the verifier
-packs that compiled allowlist, checks its exact contents and consumes both
-public entries outside the source tree. No lifecycle script performs an
-installation or publication.
+## Authority boundary
 
-The package depends on the published Workbench authority rather than a workspace
-locator. Only the archive retained by the release verifier may be published.
+This package adapts Workbench authorities; it does not redefine workspace
+semantics or own product tools, widgets, Viewers or policies. Supplied providers
+remain owned by their hosts. Runtime disposal removes subscriptions but does not
+implicitly flush persistence or close shared native resources.
 
-## Explicit runtime entry
+## Quick start
 
 ```ts
-import {
-  createWorkbenchStoreRuntime,
-  type CreateWorkbenchStoreRuntimeOptions,
-} from '@konitif/workbench-runtime/runtime';
-```
+import { createWorkbenchStore } from '@konitif/workbench-runtime';
 
-This entry requires all six host ports: `workspacePersistence`,
-`shellPersistence`, `focusPersistence`, `workspaceSync`, `hostEvents` and
-`detachedWindows`. Only the last two accept `null`, explicitly disabling those
-capabilities. Missing ports are rejected before providers are read.
+const emptyCatalog = { getDefinition: () => undefined };
+const runtime = createWorkbenchStore({
+  initialToolId: 'home',
+  persistenceKey: 'example-workbench',
+  toolCatalog: emptyCatalog,
+  shellWidgetCatalog: emptyCatalog,
+});
 
-Port types are exported from the same entry. Workspace contracts remain owned
-by `@konitif/workbench/workspace-contracts`. The runtime owns its subscriptions,
-not the supplied shared providers; call `flushPersistence()` before `dispose()`
-if pending state must be saved. Disposal does not close native windows.
+runtime.dispose();
+```
 
-The root entry retains `createWorkbenchStore` and its browser defaults for
-compatibility. The explicit entry selects no browser defaults, but still uses
-Svelte stores, global debounce timers and the existing identity generator.
+The root entry supplies browser-oriented defaults. Import
+`@konitif/workbench-runtime/runtime` when persistence, synchronization, host
+events and detached-window providers must all be supplied explicitly. Call
+`flushPersistence()` before `dispose()` when pending state must be saved.
 
-The npm distribution exposes compiled Node-compatible ESM and NodeNext
-declarations. Repository sources remain TypeScript and are not included in the
-archive.
+## Public entry points
 
-## Host notifications
+| Entry | Purpose |
+| --- | --- |
+| `@konitif/workbench-runtime` | Existing store API and compatibility defaults. |
+| `@konitif/workbench-runtime/runtime` | Explicit six-port runtime assembly. |
 
-`createWorkbenchStore` accepts an optional `hostEvents` provider:
+## Reference
 
-- Omitted: browser `pagehide`, `beforeunload`, hidden visibility and `storage` notifications.
-- `null`: no subscriptions to those host events, even in a browser.
-- `WorkbenchHostEvents`: explicit provider returning an unsubscribe function for each subscription.
+See [`reference/`](reference/) for the machine-readable capability catalog and
+authority diagrams. The catalogs document the adapter and are not persisted
+workspace state.
 
-The provider calls `onPersistenceBoundary()` or `onStorageChange({ key, newValue })`.
-It does not own workspace state or perform persistence. The coordinator filters
-storage notifications, reloads through its persistence ports and validates the
-workspace. Disposal unsubscribes without destroying a shared provider; it does
-not implicitly flush pending saves. Call `flushPersistence()` first when needed.
+## License
 
-This option does not disable `workspaceSync`, detached-window controls or default
-storage adapters. Supply those ports separately for a non-browser host.
+Source-available under [PolyForm Noncommercial 1.0.0](LICENSE.md), not OSI open
+source. Commercial use requires separate written authorization.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@konitif/workbench-runtime",
   "license": "PolyForm-Noncommercial-1.0.0",
-  "version": "0.284.1",
+  "version": "0.284.2",
   "description": "Reactive Svelte host adapter for KONITIF Workbench contracts with explicit runtime ports.",
   "repository": {
     "type": "git",
@@ -32,7 +32,8 @@
     "dist",
     "LICENSE.md",
     "README.md",
-    "package.json"
+    "package.json",
+    "reference"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",

package/reference/README.md

@@ -0,0 +1,10 @@
+# Workbench Runtime reference
+
+This directory contains authored, machine-readable documentation for
+`@konitif/workbench-runtime`.
+
+- [`catalog.json`](catalog.json) groups store coordination and explicit host ports.
+- [`diagrams.json`](diagrams.json) describes runtime assembly and observation flow.
+
+These files support documentation tooling. They are not persisted workspace
+state, host configuration or proof that an external effect occurred.

package/reference/catalog.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": "1.0.0",
+  "package": "@konitif/workbench-runtime",
+  "intent": "Assemble the Workbench runtime and coordinate its controllers without owning the hosted domains.",
+  "clusters": [
+    {
+      "id": "store-and-modes",
+      "title": "Store and modes",
+      "summary": "Composite Workbench state and workspace manipulation modes.",
+      "authority": "Local application coordination.",
+      "owns": [
+        "store",
+        "current mode"
+      ],
+      "doesNotOwn": [
+        "tool domains"
+      ],
+      "workflow": [
+        "Create",
+        "Configure",
+        "Reduce"
+      ],
+      "sources": [
+        "createWorkbenchStore.ts",
+        "createWorkspaceModeController.ts"
+      ]
+    },
+    {
+      "id": "shell-runtime-actions",
+      "title": "Shell and tool actions",
+      "summary": "Application commands connecting the shell, panels, and tools.",
+      "authority": "Orchestration of admitted intents.",
+      "owns": [
+        "shell actions",
+        "tool runtime actions"
+      ],
+      "doesNotOwn": [
+        "business meaning"
+      ],
+      "workflow": [
+        "Receive",
+        "Route",
+        "Apply"
+      ],
+      "sources": [
+        "workbenchShellActions.ts",
+        "workbenchToolRuntimeActions.ts"
+      ]
+    },
+    {
+      "id": "persistence-and-sync",
+      "title": "Persistence and synchronization",
+      "summary": "Restoration of layout, focus, and history.",
+      "authority": "Persistent workspace state.",
+      "owns": [
+        "persisted shell",
+        "focus",
+        "history",
+        "synchronization"
+      ],
+      "doesNotOwn": [
+        "domain artifacts"
+      ],
+      "workflow": [
+        "Capture",
+        "Persist",
+        "Rehydrate"
+      ],
+      "sources": [
+        "workbenchShellPersistence.ts",
+        "workbenchFocusPersistence.ts",
+        "workspaceHistoryController.ts",
+        "workspaceSyncController.ts"
+      ]
+    }
+  ]
+}

package/reference/diagrams.json

@@ -0,0 +1,69 @@
+{
+  "schemaVersion": "1.0.0",
+  "package": "@konitif/workbench-runtime",
+  "diagrams": [
+    {
+      "id": "runtime-session-lifecycle",
+      "title": "Workbench session lifecycle",
+      "kind": "lifecycle",
+      "summary": "The runtime initializes the store, coordinates actions, and preserves idempotent recovery.",
+      "nodes": [
+        {
+          "id": "boot",
+          "label": "Boot",
+          "description": "Configuration, registries, and dependencies are prepared."
+        },
+        {
+          "id": "store",
+          "label": "Workbench store",
+          "description": "The composite session state is created."
+        },
+        {
+          "id": "action",
+          "label": "Admitted action",
+          "description": "The shell, a mode, or a tool receives an intent."
+        },
+        {
+          "id": "runtime",
+          "label": "Coordination",
+          "description": "Controllers apply the transition.",
+          "tone": "runtime"
+        },
+        {
+          "id": "persist",
+          "label": "Persistence and synchronization",
+          "description": "Layout, focus, and history are captured."
+        },
+        {
+          "id": "resume",
+          "label": "Recovery",
+          "description": "The session is rehydrated without duplication.",
+          "tone": "observation"
+        }
+      ],
+      "edges": [
+        {
+          "from": "boot",
+          "to": "store"
+        },
+        {
+          "from": "store",
+          "to": "action"
+        },
+        {
+          "from": "action",
+          "to": "runtime"
+        },
+        {
+          "from": "runtime",
+          "to": "persist"
+        },
+        {
+          "from": "persist",
+          "to": "resume"
+        }
+      ],
+      "caption": "The Workbench runtime coordinates hosted domains without inventing their product meaning."
+    }
+  ]
+}