@fabrika/canvas-kernel 0.9.0-dev.1 → 0.9.0-dev.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/canvas-kernel",
-	"version": "0.9.0-dev.1",
+	"version": "0.9.0-dev.3",
 	"type": "module",
 	"description": "Canvas JSX compiler, session/revision store, renderer and interactive component library.",
 	"license": "MIT",
@@ -16,40 +16,47 @@
 		"index.ts",
 		"src",
 		"!src/**/*.test.ts",
-		"!src/**/*.test.tsx"
+		"!src/**/*.test.tsx",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./index.ts",
-			"types": "./index.ts",
+			"types": "./types/index.d.ts",
 			"default": "./index.ts"
 		},
 		"./server": {
 			"bun": "./index.ts",
-			"types": "./index.ts",
+			"types": "./types/index.d.ts",
 			"default": "./index.ts"
 		},
 		"./client": {
 			"bun": "./src/client/index.ts",
-			"types": "./src/client/index.ts",
+			"types": "./types/src/client/index.d.ts",
 			"default": "./src/client/index.ts"
 		},
 		"./components": {
 			"bun": "./src/client/components/index.ts",
-			"types": "./src/client/components/index.ts",
+			"types": "./types/src/client/components/index.d.ts",
 			"default": "./src/client/components/index.ts"
 		},
 		"./runtime": {
 			"bun": "./src/client/runtime.ts",
-			"types": "./src/client/runtime.ts",
+			"types": "./types/src/client/runtime.d.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"
+		"#canvas/components": {
+			"types": "./types/src/client/components/index.d.ts",
+			"default": "./src/client/components/index.ts"
+		},
+		"#canvas/runtime": {
+			"types": "./types/src/client/runtime.d.ts",
+			"default": "./src/client/runtime.ts"
+		}
 	},
 	"scripts": {
 		"typecheck": "tsc --noEmit",
@@ -57,8 +64,8 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/annotations": "0.9.0-dev.1",
-		"@fabrika/daemon-kit": "0.9.0-dev.1",
+		"@fabrika/annotations": "0.9.0-dev.3",
+		"@fabrika/daemon-kit": "0.9.0-dev.3",
 		"marked": "^17.0.4",
 		"mermaid-parser-bundle": "^0.1.2",
 		"preact": "^10.25.0",

package/types/index.d.ts

@@ -0,0 +1,11 @@
+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 { 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/types/src/client/AnnotationProvider.d.ts

@@ -0,0 +1,31 @@
+import type { Annotation, AnnotationContext, AnnotationContextValue, FeedbackEntry, PlanResponse } from '#canvas/runtime';
+import React from 'react';
+import { type AnnotationDraftPhase } from './annotationDraft';
+export type { Annotation, AnnotationContext, AnnotationContextValue, FeedbackEntry, PlanResponse };
+export { useAnnotations } from '#canvas/runtime';
+export interface PersistedState {
+    annotations: Annotation[];
+    generalNote: string;
+    responses: [string, PlanResponse][];
+    feedbackEntries?: [string, FeedbackEntry][];
+}
+interface AnnotationProviderProps {
+    sessionId: string;
+    revision: number;
+    isReadOnly: boolean;
+    draftPhase: AnnotationDraftPhase;
+    /** Remote annotations fetched from shared views. Merged read-only into
+     *  the annotation list so they render alongside the author's own. */
+    remoteAnnotations?: Annotation[];
+    /** Canvas files this revision is made of. Supplying it enables pruning of
+     *  answers to questions the revision no longer asks; omit it and every
+     *  answer is submitted, which is what a host without canvas tabs wants. */
+    canvasFiles?: readonly string[];
+    /** Server-authoritative persistence. When supplied, the draft is loaded and
+     *  saved through these instead of localStorage, so it survives reloads and
+     *  follows the author across browsers. Omit for the localStorage default. */
+    loadState?: (sessionId: string, revision: number, phase: AnnotationDraftPhase) => Promise<PersistedState | null>;
+    saveState?: (sessionId: string, revision: number, state: PersistedState, phase: AnnotationDraftPhase) => void;
+    children: React.ReactNode;
+}
+export declare function AnnotationProvider({ sessionId, revision, isReadOnly, draftPhase, remoteAnnotations, canvasFiles, loadState, saveState, children }: AnnotationProviderProps): React.JSX.Element;

package/types/src/client/AnnotationSidebar.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+/**
+ * The canvas host's sidebar: the reusable annotation list and draft footer,
+ * wrapped in the chrome only a canvas has — revisions, per-revision feedback,
+ * canvas files, agent responses, and the wait for the agent to come back.
+ */
+interface AnnotationSidebarProps {
+    onSubmit: (feedback: string) => void;
+    collapseButton?: React.ReactNode;
+}
+export declare function AnnotationSidebar({ onSubmit, collapseButton }: AnnotationSidebarProps): React.JSX.Element;
+export {};

package/types/src/client/FileIcon.d.ts

@@ -0,0 +1,8 @@
+interface FileIconProps {
+    name: string;
+    type: 'file' | 'dir';
+    expanded?: boolean;
+    className?: string;
+}
+export declare function FileIcon({ name, type, expanded, className }: FileIconProps): import("react").JSX.Element;
+export {};

package/types/src/client/PlanRenderer.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface PlanRendererProps {
+    revision: number;
+    filename: string;
+}
+export declare function PlanRenderer({ revision, filename }: PlanRendererProps): React.JSX.Element;
+export {};

package/types/src/client/RenderErrorContext.d.ts

@@ -0,0 +1,8 @@
+export interface CanvasRenderError {
+    revision: number;
+    filename: string;
+    message: string;
+    stack?: string;
+    componentStack?: string;
+}
+export declare const RenderErrorContext: import("react").Context<(error: CanvasRenderError) => void>;

package/types/src/client/ResponsePreview.d.ts

@@ -0,0 +1,12 @@
+interface ResponsePreviewProps {
+    open: boolean;
+    onClose: () => void;
+    onSubmit: (feedback: string) => void;
+    includedRemoteIds: Set<string>;
+    onToggleRemoteId: (id: string) => void;
+}
+export declare function ResponsePreview({ open, onClose, onSubmit, includedRemoteIds, onToggleRemoteId }: ResponsePreviewProps): import("react").JSX.Element | null;
+export declare function MarkdownPreview({ text }: {
+    text: string;
+}): import("react").JSX.Element;
+export {};

package/types/src/client/annotationDom.d.ts

@@ -0,0 +1,12 @@
+import type { Annotation } from './AnnotationProvider';
+import type { ActiveView } from './appContext';
+/**
+ * Find the DOM element for an annotation — the decoration this kernel drew for
+ * it, or failing that whatever its snippet names.
+ */
+export declare function findAnnotationElement(ann: Annotation): HTMLElement | null;
+/**
+ * Scroll the canvas/file view to an annotation element and flash it.
+ * Handles file annotations by switching view first.
+ */
+export declare function scrollToAnnotation(ann: Annotation, setActiveView: (view: ActiveView) => void): void;

package/types/src/client/annotationDraft.d.ts

@@ -0,0 +1,18 @@
+interface RevisionState {
+    revision: number;
+    hasFeedback: boolean;
+}
+interface AnnotationStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface RemovableAnnotationStorage {
+    removeItem(key: string): void;
+}
+export type AnnotationDraftPhase = 'current' | 'next';
+export declare function annotationDraftKey(sessionId: string, revision: number, phase?: AnnotationDraftPhase): string;
+export declare function clearPersistedDraft(storage: RemovableAnnotationStorage, sessionId: string, revision: number): void;
+/** Carry an unsent draft forward without crossing submitted revisions. */
+export declare function carryUnsubmittedDraft(storage: AnnotationStorage, sessionId: string, targetRevision: number, revisions: RevisionState[]): number | null;
+export {};

package/types/src/client/appContext.d.ts

@@ -0,0 +1,48 @@
+import type { ActiveView } from '#canvas/runtime';
+/**
+ * Shell state the annotation surface reads but does not own.
+ *
+ * The kernel ships no app shell — each host builds its own chrome — but the
+ * reusable annotation surface still needs to know which revision is on screen
+ * and how to navigate. The host provides both contexts around the surface.
+ */
+export type { ActiveView };
+export interface CanvasFileInfo {
+    filename: string;
+    diffStats?: {
+        added: number;
+        removed: number;
+    };
+}
+export interface RevisionInfo {
+    revision: number;
+    label?: string;
+    canvasFiles: CanvasFileInfo[];
+    createdAt: string;
+    hasFeedback: boolean;
+    feedbackConsumed: boolean;
+    response?: string;
+}
+export declare const ActiveViewContext: import("react").Context<{
+    activeView: ActiveView;
+    setActiveView: (v: ActiveView) => void;
+    openFiles: string[];
+    closeFile: (path: string) => void;
+    canvasFiles: string[];
+}>;
+export declare const RevisionContext: import("react").Context<{
+    currentRevision: number;
+    selectedRevision: number;
+    revisions: RevisionInfo[];
+    setSelectedRevision: (rev: number) => void;
+    isReadOnly: boolean;
+    compareRevision: {
+        left: number;
+        right: number;
+    } | null;
+    setCompareRevision: (rev: {
+        left: number;
+        right: number;
+    } | null) => void;
+    agentWatching: boolean;
+}>;

package/types/src/client/components/Callout.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface CalloutProps {
+    type?: 'info' | 'warning' | 'danger' | 'tip';
+    children?: React.ReactNode;
+}
+export declare function Callout({ type, children }: CalloutProps): React.JSX.Element;
+export {};

package/types/src/client/components/Checklist.d.ts

@@ -0,0 +1,9 @@
+interface ChecklistItem {
+    label: string;
+    checked: boolean;
+}
+interface ChecklistProps {
+    items: ChecklistItem[];
+}
+export declare function Checklist({ items }: ChecklistProps): import("react").JSX.Element;
+export {};

package/types/src/client/components/Choice.d.ts

@@ -0,0 +1,21 @@
+export type ChoiceOption = string | {
+    value: string;
+    label?: string;
+};
+/** Radio — pick one option */
+interface ChoiceProps {
+    id: string;
+    label: string;
+    options: ChoiceOption[];
+    required?: boolean;
+}
+export declare function Choice({ id, label, options, required }: ChoiceProps): import("react").JSX.Element;
+/** Checkbox — pick multiple options */
+interface MultiChoiceProps {
+    id: string;
+    label: string;
+    options: ChoiceOption[];
+    required?: boolean;
+}
+export declare function MultiChoice({ id, label, options, required }: MultiChoiceProps): import("react").JSX.Element;
+export {};

package/types/src/client/components/CodeBlock.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface CodeBlockProps {
+    language?: string;
+    children?: React.ReactNode;
+}
+export declare function CodeBlock({ language, children }: CodeBlockProps): React.JSX.Element;
+export {};

package/types/src/client/components/Diff.d.ts

@@ -0,0 +1,7 @@
+interface DiffProps {
+    before: string;
+    after: string;
+    language?: string;
+}
+export declare function Diff({ before, after, language }: DiffProps): import("react").JSX.Element;
+export {};

package/types/src/client/components/FilePreview.d.ts

@@ -0,0 +1,8 @@
+interface FilePreviewProps {
+    path: string;
+    lines?: [number, number];
+    /** Injected by compiler at build time — skip runtime fetch when present */
+    __content?: string;
+}
+export declare function FilePreview({ path, lines, __content }: FilePreviewProps): import("react").JSX.Element;
+export {};

package/types/src/client/components/Image.d.ts

@@ -0,0 +1,9 @@
+interface ImageProps {
+    src: string;
+    alt?: string;
+    caption?: string;
+    width?: number | string;
+    height?: number | string;
+}
+export declare function ImageView({ src, alt, caption, width, height }: ImageProps): import("react").JSX.Element;
+export {};

package/types/src/client/components/Markdown.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+interface MarkdownProps {
+    /** Inline markdown source (via children) */
+    children?: React.ReactNode;
+    /** File path (resolved at compile time) */
+    file?: string;
+    /** Injected by compiler when file prop is used */
+    __content?: string;
+}
+export declare function Markdown({ children, file, __content }: MarkdownProps): React.JSX.Element;
+export {};

package/types/src/client/components/Mermaid.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+interface MermaidProps {
+    children?: React.ReactNode;
+}
+export declare function Mermaid({ children }: MermaidProps): React.JSX.Element;
+export {};

package/types/src/client/components/Note.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+interface NoteProps {
+    children?: React.ReactNode;
+}
+export declare function Note({ children }: NoteProps): React.JSX.Element;
+export {};

package/types/src/client/components/Priority.d.ts

@@ -0,0 +1,5 @@
+interface PriorityProps {
+    level: 'high' | 'medium' | 'low';
+}
+export declare function Priority({ level }: PriorityProps): import("react").JSX.Element;
+export {};

package/types/src/client/components/ResponseNote.d.ts

@@ -0,0 +1,7 @@
+/** Seamless note input for response components */
+export declare function ResponseNote({ note, onChange }: {
+    show?: boolean;
+    note: string;
+    onToggle?: () => void;
+    onChange: (n: string) => void;
+}): import("react").JSX.Element;

package/types/src/client/components/Section.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+interface SectionProps {
+    title: string;
+    children?: React.ReactNode;
+}
+export declare function Section({ title, children }: SectionProps): React.JSX.Element;
+export {};

package/types/src/client/components/Table.d.ts

@@ -0,0 +1,6 @@
+interface TableProps {
+    headers: string[];
+    rows: string[][];
+}
+export declare function Table({ headers, rows }: TableProps): import("react").JSX.Element;
+export {};

package/types/src/client/components/Task.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+type Status = 'todo' | 'done' | 'blocked' | 'in-progress';
+type BadgeVariant = 'info' | 'success' | 'warning' | 'danger' | 'neutral';
+interface ItemProps {
+    id: string;
+    label: string;
+    status?: Status;
+    badge?: string;
+    badgeVariant?: BadgeVariant;
+    children?: React.ReactNode;
+}
+export declare function Item({ id, label, status, badge, badgeVariant, children }: ItemProps): React.JSX.Element;
+/** @deprecated Use <Item> instead */
+export declare function Task(props: ItemProps): React.JSX.Element;
+export {};

package/types/src/client/components/UserInput.d.ts

@@ -0,0 +1,22 @@
+/** Free text input from user */
+interface UserInputProps {
+    id: string;
+    label: string;
+    placeholder?: string;
+    multiline?: boolean;
+    required?: boolean;
+}
+export declare function UserInput({ id, label, placeholder, multiline, required }: UserInputProps): import("react").JSX.Element;
+/** Numeric range / slider */
+interface RangeInputProps {
+    id: string;
+    label: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    required?: boolean;
+    minLabel?: string;
+    maxLabel?: string;
+}
+export declare function RangeInput({ id, label, min, max, step, required, minLabel, maxLabel }: RangeInputProps): import("react").JSX.Element;
+export {};

package/types/src/client/components/index.d.ts

@@ -0,0 +1,16 @@
+export { useFeedback } from '#canvas/runtime';
+export { Callout } from './Callout';
+export { Checklist } from './Checklist';
+export { Choice, MultiChoice } from './Choice';
+export { CodeBlock } from './CodeBlock';
+export { Diff } from './Diff';
+export { FilePreview } from './FilePreview';
+export { ImageView } from './Image';
+export { Markdown } from './Markdown';
+export { Mermaid } from './Mermaid';
+export { Note } from './Note';
+export { Priority } from './Priority';
+export { Section } from './Section';
+export { Table } from './Table';
+export { Item, Task } from './Task';
+export { RangeInput, UserInput } from './UserInput';

package/types/src/client/components/renderMarkdownChildren.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+/**
+ * Auto-render markdown for string children, passing JSX children through.
+ * Block-level JSX (Callout, Diff, etc.) breaks the prose into separate markdown blocks,
+ * while inline JSX (code, strong, links) stays within the surrounding paragraph so text
+ * keeps flowing instead of stacking one fragment per line.
+ */
+export declare function renderMarkdownChildren(children: React.ReactNode): React.ReactNode;

package/types/src/client/diffLines.d.ts

@@ -0,0 +1,7 @@
+export interface DiffLine {
+    type: 'same' | 'removed' | 'added';
+    line: string;
+}
+/** Line-level diff of two texts, longest-common-subsequence based. */
+export declare function buildDiffLines(before: string, after: string): DiffLine[];
+export declare function computeLCS(a: string[], b: string[]): string[];

package/types/src/client/generateMarkdown.d.ts

@@ -0,0 +1,29 @@
+import type { Annotation, FeedbackEntry, PlanResponse } from './AnnotationProvider';
+/**
+ * Drop answers whose question is not in this revision's canvas. A draft carried
+ * forward by carryUnsubmittedDraft() can hold an answer to a question the new
+ * revision removed; submitting that would report an answer the author was never
+ * asked for.
+ *
+ * `seenResponseIds` must be the sticky set of controls that have mounted at any
+ * point in this draft, never the currently-mounted ones — see canPruneResponses.
+ */
+export declare function pruneStaleResponses(responses: Map<string, PlanResponse>, seenResponseIds: ReadonlySet<string>): Map<string, PlanResponse>;
+/**
+ * Whether the set of seen response ids is complete enough to prune against.
+ *
+ * An id is only evidence of absence once every canvas that could host it has
+ * rendered. Until then "not seen" means "not looked at yet" — the host opens
+ * multi-canvas sessions on the overview, where no canvas is mounted at all, so
+ * pruning early would throw away every answer the author gave.
+ */
+export declare function canPruneResponses(canvasFiles: readonly string[] | undefined, renderedCanvases: ReadonlySet<string>): boolean;
+/**
+ * Generate human-readable markdown feedback from annotations and responses.
+ */
+export declare function generateMarkdown(annotations: Annotation[], generalNote: string, responses?: Map<string, PlanResponse>, feedbackEntries?: Map<string, FeedbackEntry>, includedRemoteIds?: Set<string>): string;
+export declare function hasValue(r: PlanResponse): boolean;
+export declare function getMissingRequired(responses: Map<string, PlanResponse>): PlanResponse[];
+export declare function getMissingRequiredFeedback(entries: Map<string, FeedbackEntry>): FeedbackEntry[];
+/** Returns list of missing required field labels, or empty if all valid */
+export declare function getMissingRequiredLabels(responses: Map<string, PlanResponse>, feedbackEntries: Map<string, FeedbackEntry>): string[];

package/types/src/client/hostContext.d.ts

@@ -0,0 +1,30 @@
+import { type ComponentType } from 'react';
+/**
+ * What the annotation surface needs from the host serving it.
+ *
+ * The kernel ships a local-daemon implementation, so a host that serves
+ * canvases straight off its own daemon needs no provider. Hosts with extra
+ * delivery modes (agent-canvas also serves read-only encrypted share links)
+ * provide their own.
+ */
+export interface CanvasHost {
+    /** Session the canvas belongs to. */
+    sessionId: string;
+    /** Read-only share view — local-only affordances stay hidden. */
+    isShared: boolean;
+    /** Host can read project files (feedback bodies, file browser). */
+    fsAvailable: boolean;
+    /** Endpoint accepting annotation image uploads, or `null` for a host that
+     *  has none — the attach affordances then stay hidden rather than posting
+     *  into the void. Required, not optional, so no host can be silent about it. */
+    uploadUrl: (() => string) | null;
+    /** Fetch and `import()` a compiled canvas module. */
+    loadCanvasModule: (filename: string, revision?: number) => Promise<CanvasModule>;
+}
+/** What the canvas compiler emits: one module whose default export renders the canvas. */
+export interface CanvasModule {
+    default: ComponentType;
+}
+export declare const localCanvasHost: CanvasHost;
+export declare const CanvasHostContext: import("react").Context<CanvasHost>;
+export declare function useCanvasHost(): CanvasHost;

package/types/src/client/index.d.ts

@@ -0,0 +1,20 @@
+export { AnnotationProvider } from './AnnotationProvider';
+export type { PersistedState } from './AnnotationProvider';
+export { feedbackEntrySchema, filePreviewResponseSchema, parsePersistedState, persistedStateSchema, planResponseSchema } from './persistenceSchemas';
+export { ActiveViewCtx, AnnotationCtx, CanvasFileCtx, SessionContext, useAnnotations, useCanvasFile, useFeedback, useResponseRegistration, } from '#canvas/runtime';
+export type { ActiveView, Annotation, AnnotationAttachment, AnnotationAuthor, AnnotationContext, AnnotationContextValue, FeedbackEntry, PlanResponse, } from '#canvas/runtime';
+export { findAnnotationElement, scrollToAnnotation } from './annotationDom';
+export { annotationDraftKey, carryUnsubmittedDraft, clearPersistedDraft } from './annotationDraft';
+export type { AnnotationDraftPhase } from './annotationDraft';
+export { AnnotationSidebar } from './AnnotationSidebar';
+export { ActiveViewContext, RevisionContext } from './appContext';
+export type { CanvasFileInfo, RevisionInfo } from './appContext';
+export * as components from './components';
+export { FileIcon } from './FileIcon';
+export { canPruneResponses, generateMarkdown, getMissingRequired, getMissingRequiredFeedback, getMissingRequiredLabels, hasValue, pruneStaleResponses, } from './generateMarkdown';
+export { CanvasHostContext, localCanvasHost, useCanvasHost } from './hostContext';
+export type { CanvasHost } from './hostContext';
+export { PlanRenderer } from './PlanRenderer';
+export { RenderErrorContext } from './RenderErrorContext';
+export type { CanvasRenderError } from './RenderErrorContext';
+export { MarkdownPreview, ResponsePreview } from './ResponsePreview';

package/types/src/client/pageGlobals.d.ts

@@ -0,0 +1,29 @@
+interface HighlightJs {
+    highlightElement(element: HTMLElement): void;
+    highlight(code: string, options: {
+        language: string;
+    }): {
+        value: string;
+    };
+    highlightAuto(code: string): {
+        value: string;
+    };
+}
+interface MermaidApi {
+    initialize(config: {
+        startOnLoad: boolean;
+        theme: string;
+    }): void;
+    render(id: string, source: string): Promise<{
+        svg: string;
+    }>;
+}
+declare global {
+    interface Window {
+        hljs?: HighlightJs;
+        mermaid?: MermaidApi;
+    }
+}
+export declare function pageHighlighter(): HighlightJs | undefined;
+export declare function pageMermaid(): MermaidApi | undefined;
+export {};