@fabrika/canvas-kernel 0.1.44

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contember Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @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.
+
+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.
+
+## License
+
+MIT

package/annotate.ts

@@ -0,0 +1,94 @@
+// @fabrika/canvas-kernel/annotate — the annotation surface.
+//
+// Ring 2: collecting a reader's notes on something, and getting them back out
+// as markdown an agent can act on. What a note points at is a locator strategy
+// (text, block, image region), so a host annotates its own kind of thing by
+// writing one target; the list, the editor, the draft and the markdown do not
+// change. Grouping, headings and navigation stay with the host — this ring has
+// no taxonomy of its own.
+//
+// Not yet a severed dependency: `AnnotationProvider` still imports the canvas
+// response-pruning from `generateMarkdown`, so a bundle built off this entry
+// carries that along. The export list is the API statement; the import graph
+// has one edge left to cut.
+
+// --- Annotation state ------------------------------------------------------
+export { AnnotationProvider } from "./src/client/AnnotationProvider";
+export type { PersistedState } from "./src/client/AnnotationProvider";
+export { useAnnotations, AnnotationCtx, SessionContext } from "./src/client/runtime";
+export type {
+  Annotation,
+  AnnotationAttachment,
+  AnnotationAuthor,
+  AnnotationContext,
+  AnnotationContextValue,
+} from "./src/client/runtime";
+export {
+  annotationDraftKey,
+  carryUnsubmittedDraft,
+  clearPersistedDraft,
+} from "./src/client/annotationDraft";
+export type { AnnotationDraftPhase } from "./src/client/annotationDraft";
+
+// --- Surface ---------------------------------------------------------------
+export { AnnotationList } from "./src/client/AnnotationList";
+export type { AnnotationListProps } from "./src/client/AnnotationList";
+export { AnnotationDraftFooter } from "./src/client/AnnotationDraftFooter";
+export type { AnnotationDraftFooterProps } from "./src/client/AnnotationDraftFooter";
+export { AnnotationEditor, imageToUrl } from "./src/client/AnnotationEditor";
+export { Popover, AnnotationPopover, AnnotationCreatePopover, AnnotationEditPopover } from "./src/client/Popover";
+
+// --- Drawing ---------------------------------------------------------------
+export { useTextAnnotation } from "./src/client/useTextAnnotation";
+export { useRegionAnnotation } from "./src/client/useRegionAnnotation";
+
+// --- Locator strategies ----------------------------------------------------
+export { sealTarget } from "./src/client/annotationTarget";
+export type { AnnotationTarget, SealedAnnotationTarget, TargetAnnotation } from "./src/client/annotationTarget";
+export { blockTarget } from "./src/client/blockTarget";
+export type { BlockLocator } from "./src/client/blockTarget";
+export { textTarget } from "./src/client/textTarget";
+export type { TextLocator } from "./src/client/textTarget";
+export {
+  createRegionOverlay,
+  describeRegion,
+  findRegionHost,
+  isDrawableRegion,
+  regionBetween,
+  regionPointIn,
+  regionStyle,
+  regionTarget,
+  REGION_HOST_ATTR,
+  REGION_UNITS,
+} from "./src/client/regionTarget";
+export type { RegionBox, RegionLocator, RegionPoint, RegionShape } from "./src/client/regionTarget";
+export {
+  ANNOTATION_TARGETS,
+  ANNOTATABLE_SELECTOR,
+  BLOCK_SELECTOR,
+  describeSnippet,
+  findAnnotationElement,
+  findSnippetElement,
+  getBlockSnippet,
+  restoreAnnotationTargets,
+} from "./src/client/annotationDom";
+
+// --- Marks -----------------------------------------------------------------
+export {
+  restoreMarks,
+  renameMarkId,
+  setMarkActive,
+  unwrapMarks,
+  updateAllMarkStates,
+  wrapRangeWithMark,
+} from "./src/client/highlightRange";
+
+// --- Feedback out ----------------------------------------------------------
+export { renderAnnotation } from "./src/client/annotationMarkdown";
+export type { RenderableAnnotation } from "./src/client/annotationMarkdown";
+export { extractContext, formatSnippetInContext } from "./src/client/annotationContext";
+
+// --- Host-provided context -------------------------------------------------
+export { CanvasHostContext, localCanvasHost, useCanvasHost } from "./src/client/hostContext";
+export type { CanvasHost } from "./src/client/hostContext";
+export { autoResizeTextarea, fileAnnotationPath, generateAnnotationId, hostAcceptsUploads } from "./src/client/utils";

package/daemon.ts

@@ -0,0 +1,46 @@
+// @fabrika/canvas-kernel/daemon — the host-agnostic daemon runtime.
+//
+// Ring 1: everything a local daemon needs that knows nothing about canvases —
+// the WebSocket notification channel, the CLI waiter, process lifecycle, route
+// dispatch, and the on-disk layout. A host whose domain is not canvases (Figma
+// screens, say) takes this entry and none of the canvas engine behind `/server`.
+
+// --- WebSocket notification channel ----------------------------------------
+export { createNotificationChannel, browserFrame } from "./src/engine/channel";
+export type {
+  ChannelRole,
+  ChannelSocket,
+  TopicChannel,
+  RelayOptions,
+  BrowserFrameHandler,
+  NotificationChannel,
+  NotificationChannelOptions,
+} from "./src/engine/channel";
+
+// --- 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";
+
+// --- Router / HTTP ---------------------------------------------------------
+export { dispatch } from "./src/engine/router";
+export type { Route, RouteHandler } from "./src/engine/router";
+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";

package/index.ts

@@ -0,0 +1,84 @@
+// @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 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";

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@fabrika/canvas-kernel",
+  "version": "0.1.44",
+  "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"
+  }
+}

package/src/client/AnnotationDraftFooter.tsx

@@ -0,0 +1,76 @@
+import type React from "react";
+import { useAnnotations } from "./AnnotationProvider";
+import { autoResizeTextarea } from "./utils";
+
+/**
+ * The foot of a draft: the note that belongs to no one annotation, and the
+ * action that sends the draft off.
+ *
+ * What counts as content, and what the payload looks like, is the host's —
+ * hence `hasContent` and a bare `onSubmit`. The two slots are where a host
+ * hangs whatever else its submit step needs (a preview button, a validation
+ * notice) without this component learning about it.
+ */
+export interface AnnotationDraftFooterProps {
+  /** Whether the draft says anything. Hosts count more than annotations and
+   *  the general note, so they decide. */
+  hasContent: boolean;
+  onSubmit: () => void;
+  /** Submitting an empty draft — an explicit "nothing to say", not a no-op. */
+  onSubmitEmpty: () => void;
+  /** Sits between the note and the actions: validation, status, a warning. */
+  notice?: React.ReactNode;
+  /** Sits left of the submit button, sharing the row. */
+  secondaryAction?: React.ReactNode;
+  placeholder?: string;
+  submitLabel?: string;
+  emptyLabel?: string;
+}
+
+export function AnnotationDraftFooter({
+  hasContent, onSubmit, onSubmitEmpty, notice, secondaryAction,
+  placeholder = "General notes...",
+  submitLabel = "Submit",
+  emptyLabel = "Submit without feedback",
+}: AnnotationDraftFooterProps) {
+  const { generalNote, setGeneralNote } = useAnnotations();
+
+  return (
+    <>
+      {/* General note — seamless */}
+      <div className="border-t border-border-subtle px-4 py-3 flex-shrink-0">
+        <textarea
+          value={generalNote}
+          onChange={(e) => setGeneralNote(e.currentTarget.value)}
+          className="w-full bg-transparent text-[13px] font-body text-text-primary resize-none leading-relaxed p-0 border-none ring-0 shadow-none outline-none focus:outline-none focus:ring-0 focus:border-none placeholder:text-text-disabled min-h-[40px]"
+          placeholder={placeholder}
+          onInput={(e) => autoResizeTextarea(e.currentTarget, 40)}
+          ref={(el) => { if (el) autoResizeTextarea(el, 40); }}
+        />
+      </div>
+
+      {notice}
+
+      <div className="px-4 py-3 border-t border-border-subtle flex-shrink-0">
+        {hasContent ? (
+          <div className="flex gap-2">
+            {secondaryAction}
+            <button
+              onClick={onSubmit}
+              className="flex-1 py-2 rounded-lg font-body text-[13px] font-medium transition-all bg-btn-primary text-btn-primary-text hover:opacity-90 hover:-translate-y-px shadow-sm"
+            >
+              {submitLabel}
+            </button>
+          </div>
+        ) : (
+          <button
+            onClick={onSubmitEmpty}
+            className="w-full py-2 rounded-lg font-body text-[13px] font-medium border border-border-medium text-text-secondary hover:text-text-primary hover:border-border-hover hover:bg-bg-input transition-all"
+          >
+            {emptyLabel}
+          </button>
+        )}
+      </div>
+    </>
+  );
+}