@fabrika/canvas-kernel 0.1.45 → 0.3.1

package/README.md

@@ -1,73 +1,39 @@
 # @fabrika/canvas-kernel
 
-The reusable half of [Agent Canvas](https://github.com/contember/agent-canvas): a
-host-agnostic SDK for building annotatable, agent-driven canvases.
-
+The canvas SDK from [Agent Canvas](https://github.com/contember/agent-canvas).
 Ships as **TypeScript sources**, not a build artifact. It is written for Bun and
-consumed by bundlers, so a host typechecks the kernel under its own flags and can
-read every line it depends on.
-
-## Rings
-
-A host takes only the rings it needs. Each has its own entry point, and the
-entries are ordered by how much they assume:
-
-| Entry | What it holds | Assumes |
-|---|---|---|
-| `@fabrika/canvas-kernel/daemon` | WebSocket channel, CLI waiter, process lifecycle, router, paths | Nothing about canvases |
-| `@fabrika/canvas-kernel/annotate` | Annotation state and drafts, list + draft footer, editor and popovers, locator strategies (text, block, region), `renderAnnotation` | A DOM |
-| `@fabrika/canvas-kernel/server` | JSX compiler, session/revision store, watcher, the canvas WS vocabulary | A canvas |
-| `@fabrika/canvas-kernel/client` | The annotation ring plus `PlanRenderer`, `AnnotationSidebar`, `generateMarkdown`, revision contexts, component library | A canvas |
-
-Taking `/daemon` alone costs nothing at runtime — no canvas code is reachable
-from it.
-
-## Example: a daemon that is not a canvas
-
-```ts
-import { createNotificationChannel, browserFrame } from '@fabrika/canvas-kernel/daemon'
-
-const channel = createNotificationChannel({
-  roleOf: (ws) => ws.data.role,      // 'browser' | 'wait'
-  topicOf: (ws) => ws.data.sessionId,
-  waiterPolicy: 'keep-open',
-  frames: [
-    browserFrame(isSubmit, async (frame, topic) => {
-      topic.relayToWaiters(frame)
-    }),
-  ],
-})
-
-Bun.serve({ fetch: handler, websocket: channel.handlers })
-```
-
-The channel knows about two socket roles keyed by an opaque topic string. The
-frame vocabulary is the host's — the kernel never learns what a "submission" is.
-
-## Annotation locators
-
-An annotation points at something via an `AnnotationTarget<L>`, a strategy that
-owns one locator shape end to end:
-
-```ts
-export interface AnnotationTarget<L extends object> {
-  readonly kind: string
-  parse(snippet: string): L | null
-  format(locator: L): string
-  find(locator: L, root: ParentNode): HTMLElement | null
-  restore?(locator: L, root: HTMLElement, ann: TargetAnnotation): void
-  describe?(locator: L): string
-}
-```
-
-Three ship: text ranges, document blocks, and rectangular regions of an image.
-Creation and lookup read the same selector, so an annotation minted where the
-lookup does not scan is not expressible.
-
-## Versioning
-
-Released in lockstep with the `agent-canvas` package — same repository, same
-commit, same version number. Pin exactly.
+consumed by bundlers, so a host typechecks it under its own flags.
+
+Canvas-specific functionality over `@fabrika/daemon-kit` and
+`@fabrika/annotations`:
+
+| Entry                       | Responsibility                                                                         |
+| --------------------------- | -------------------------------------------------------------------------------------- |
+| `/server` (also `.`)        | JSX compilation, sessions/revisions, watcher, canvas WS protocol and paths             |
+| `/client`                   | Renderer, canvas draft persistence, responses, revision contexts, sidebar and feedback |
+| `/components`               | Interactive canvas component library                                                   |
+| `/runtime`                  | Canvas contexts shared by compiled documents and the host                              |
+| `/styles.css`, `/theme.css` | Canvas styling and theme                                                               |
+
+## Migration from 0.1.x
+
+- Replace `/daemon` imports with `@fabrika/daemon-kit`.
+- Import daemon helpers previously reexported from `/server` directly from
+  `@fabrika/daemon-kit`. `createCanvasPaths` remains canvas-specific.
+- Replace `/annotate` imports with `@fabrika/annotations`.
+- Import annotation UI, locator strategies, marks and utilities previously
+  reexported from `/client` directly from `@fabrika/annotations`.
+- The canvas `/client` `AnnotationProvider` and `PersistedState` still own
+  revisions, responses and feedback entries. The standalone annotations provider
+  instead takes `scope`, `loadState(scope)` and `saveState(scope, state)` and uses
+  `AnnotationState` with only annotations and a general note.
+- Standalone annotation hosts use `AnnotationHostContext` and `AnnotationHost`,
+  without `loadCanvasModule`. Canvas hosts keep `CanvasHostContext`.
+- Multi-bundle hosts must build and externalize `@fabrika/annotations/runtime`
+  in addition to `#canvas/runtime`, with one import-map entry for each.
+
+The removed entries are not compatibility reexports. All packages release in
+lockstep with exact internal dependency pins.
 
 ## License
 

package/index.ts

@@ -1,84 +1,21 @@
-// @fabrika/canvas-kernel — server entry.
-//
-// The host-agnostic canvas engine: compile pipeline, session/revision store,
-// JSX watcher, WebSocket notification channel, daemon lifecycle, CLI waiter,
-// router, and the on-disk layout.
-// Imports nothing from preact/DOM, so a Bun.serve daemon can pull it in without
-// dragging the browser bundle along.
-//
-// The browser-facing surface (components + annotation runtime) is exposed
-// separately through the package `imports`/`exports` maps as `#canvas/components`
-// and `#canvas/runtime`.
-
-// --- Compile pipeline (JSX -> Bun.build) -----------------------------------
-export { compileJsx, compilePlan, KERNEL_COMPONENTS } from "./src/engine/compiler";
+export { compileJsx, compilePlan, KERNEL_COMPONENTS } from './src/engine/compiler'
+export type { CanvasComponents, CanvasComponentSpec, CompileOptions, CompileResult } from './src/engine/compiler'
+export type { AssertReadable } from './src/engine/file-admission'
+export { createCanvasPaths } from './src/engine/paths'
+export type { CanvasPaths, CanvasPathsConfig } from './src/engine/paths'
+export { SessionManager } from './src/engine/session'
 export type {
-  CompileResult,
-  CompileOptions,
-  CanvasComponents,
-  CanvasComponentSpec,
-} from "./src/engine/compiler";
-
-// --- Session / revision / feedback store -----------------------------------
-export { SessionManager } from "./src/engine/session";
-export type {
-  SessionData,
-  RevisionInfo,
-  CanvasFileInfo,
-  CanvasScope,
-  DiffStats,
-  SecretResolution,
-  RemoteFeedbackEntry,
-  RemoteAnnotation,
-  ShareEntry,
-} from "./src/engine/session";
-
-// --- WebSocket notification channel (host-agnostic) ------------------------
-export { createNotificationChannel, browserFrame } from "./src/engine/channel";
-export type {
-  ChannelRole,
-  ChannelSocket,
-  TopicChannel,
-  RelayOptions,
-  BrowserFrameHandler,
-  NotificationChannel,
-  NotificationChannelOptions,
-} from "./src/engine/channel";
-
-// --- WebSocket feedback protocol (canvas vocabulary) -----------------------
-export { createWebSocketManager } from "./src/engine/websocket";
-export type { WSData, CanvasSocket, WebSocketManagerOptions } from "./src/engine/websocket";
-
-// --- CLI waiter ------------------------------------------------------------
-export { waitForEvent, WaitError } from "./src/engine/waiter";
-export type { WaiterSocket, WaitVerdict, WaitOptions, WaitMessages, WaitFailure } from "./src/engine/waiter";
-
-// --- Daemon process lifecycle ----------------------------------------------
-export { createDaemonLifecycle, DaemonStartError } from "./src/engine/lifecycle";
-export type {
-  DaemonLifecycle,
-  DaemonLifecycleConfig,
-  DaemonHealth,
-  DaemonHealthUp,
-  DaemonHealthDown,
-  DaemonPid,
-  DaemonStopResult,
-  DaemonStopReason,
-  DaemonEvent,
-  DaemonTimeouts,
-} from "./src/engine/lifecycle";
-
-// --- JSX watcher -----------------------------------------------------------
-export { watchSession, unwatchSession, unwatchAll } from "./src/engine/watcher";
-export type { WatchOptions } from "./src/engine/watcher";
-
-// --- Router ----------------------------------------------------------------
-export { dispatch } from "./src/engine/router";
-export type { Route, RouteHandler } from "./src/engine/router";
-
-// --- HTTP helpers ----------------------------------------------------------
-export { jsonResponse, corsHeaders } from "./src/engine/http-utils";
-
-// --- On-disk layout --------------------------------------------------------
-export { createCanvasPaths } from "./src/engine/paths";
-export type { CanvasPaths, CanvasPathsConfig } from "./src/engine/paths";
+	CanvasFileInfo,
+	CanvasScope,
+	DiffStats,
+	RemoteAnnotation,
+	RemoteFeedbackEntry,
+	RevisionInfo,
+	SecretResolution,
+	SessionData,
+	ShareEntry,
+} from './src/engine/session'
+export { unwatchAll, unwatchSession, watchSession } from './src/engine/watcher'
+export type { WatchOptions } from './src/engine/watcher'
+export { createWebSocketManager } from './src/engine/websocket'
+export type { CanvasSocket, WebSocketManagerOptions, WSData } from './src/engine/websocket'

package/package.json

@@ -1,74 +1,71 @@
 {
-  "name": "@fabrika/canvas-kernel",
-  "version": "0.1.45",
-  "type": "module",
-  "description": "Host-agnostic canvas SDK: a daemon runtime (WebSocket channel, CLI waiter, process lifecycle), a locator-agnostic annotation surface, and the canvas engine (JSX→Bun.build compiler, session/revision store, watcher).",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/contember/agent-canvas",
-    "directory": "packages/canvas-kernel"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "index.ts",
-    "daemon.ts",
-    "annotate.ts",
-    "src",
-    "!src/**/*.test.ts"
-  ],
-  "main": "./index.ts",
-  "types": "./index.ts",
-  "exports": {
-    ".": {
-      "types": "./index.ts",
-      "default": "./index.ts"
-    },
-    "./server": {
-      "types": "./index.ts",
-      "default": "./index.ts"
-    },
-    "./daemon": {
-      "types": "./daemon.ts",
-      "default": "./daemon.ts"
-    },
-    "./client": {
-      "types": "./src/client/index.ts",
-      "default": "./src/client/index.ts"
-    },
-    "./annotate": {
-      "types": "./annotate.ts",
-      "default": "./annotate.ts"
-    },
-    "./components": {
-      "types": "./src/client/components/index.ts",
-      "default": "./src/client/components/index.ts"
-    },
-    "./runtime": {
-      "types": "./src/client/runtime.ts",
-      "default": "./src/client/runtime.ts"
-    },
-    "./client/*": "./src/client/*",
-    "./engine/*": "./src/engine/*",
-    "./styles.css": "./src/client/styles.css",
-    "./theme.css": "./src/client/theme.css"
-  },
-  "imports": {
-    "#canvas/components": "./src/client/components/index.ts",
-    "#canvas/runtime": "./src/client/runtime.ts"
-  },
-  "dependencies": {
-    "marked": "^17.0.4",
-    "mermaid-parser-bundle": "^0.1.2",
-    "preact": "^10.25.0",
-    "preact-render-to-string": "^6.6.6"
-  },
-  "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.2",
-    "@types/react": "^18.3.12",
-    "@types/react-dom": "^18.3.1",
-    "happy-dom": "^20.11.2"
-  }
+	"name": "@fabrika/canvas-kernel",
+	"version": "0.3.1",
+	"type": "module",
+	"description": "Canvas JSX compiler, session/revision store, renderer and interactive component library.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/canvas-kernel"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"index.ts",
+		"src",
+		"!src/**/*.test.ts",
+		"!src/**/*.test.tsx"
+	],
+	"exports": {
+		".": {
+			"bun": "./index.ts",
+			"types": "./index.ts",
+			"default": "./index.ts"
+		},
+		"./server": {
+			"bun": "./index.ts",
+			"types": "./index.ts",
+			"default": "./index.ts"
+		},
+		"./client": {
+			"bun": "./src/client/index.ts",
+			"types": "./src/client/index.ts",
+			"default": "./src/client/index.ts"
+		},
+		"./components": {
+			"bun": "./src/client/components/index.ts",
+			"types": "./src/client/components/index.ts",
+			"default": "./src/client/components/index.ts"
+		},
+		"./runtime": {
+			"bun": "./src/client/runtime.ts",
+			"types": "./src/client/runtime.ts",
+			"default": "./src/client/runtime.ts"
+		},
+		"./styles.css": "./src/client/styles.css",
+		"./theme.css": "./src/client/theme.css"
+	},
+	"imports": {
+		"#canvas/components": "./src/client/components/index.ts",
+		"#canvas/runtime": "./src/client/runtime.ts"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"zod": "^3.25.76",
+		"@fabrika/annotations": "^0.3.1",
+		"@fabrika/daemon-kit": "^0.3.1",
+		"marked": "^17.0.4",
+		"mermaid-parser-bundle": "^0.1.2",
+		"preact": "^10.25.0",
+		"preact-render-to-string": "^6.6.6"
+	},
+	"peerDependencies": {
+		"react": ">=18",
+		"react-dom": ">=18"
+	}
 }