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

package/types/src/client/preact-all.d.ts

@@ -0,0 +1,4 @@
+export * from 'preact/compat';
+export { default } from 'preact/compat';
+export { createRoot, hydrateRoot } from 'preact/compat/client';
+export { jsx, jsxs } from 'preact/jsx-runtime';

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

@@ -0,0 +1,62 @@
+import type { AnnotationContextValue as BaseAnnotationContextValue } from '@fabrika/annotations/runtime';
+export type { Annotation, AnnotationAttachment, AnnotationAuthor, AnnotationContext } from '@fabrika/annotations/runtime';
+export interface PlanResponse {
+    id: string;
+    type: 'select' | 'radio' | 'checkbox' | 'text' | 'range';
+    label: string;
+    value: unknown;
+    options?: string[];
+    required?: boolean;
+    note?: string;
+}
+export interface FeedbackEntry {
+    id: string;
+    markdown: string;
+    label?: string;
+    required?: boolean;
+}
+export interface AnnotationContextValue extends BaseAnnotationContextValue {
+    /** Every answer held for this draft, including ones carried in from an
+     *  earlier revision. Controls read and write this one. */
+    responses: Map<string, PlanResponse>;
+    setResponse: (id: string, response: PlanResponse) => void;
+    /** `responses` narrowed to the questions this revision actually asks.
+     *  Everything that reports feedback — markdown, validation, "has content" —
+     *  reads this instead, so a carried-over answer to a since-removed question
+     *  is not submitted. Identical to `responses` until the host supplies the
+     *  canvas file list and every one of them has rendered. */
+    submittableResponses: Map<string, PlanResponse>;
+    registerResponse: (id: string) => void;
+    registerCanvasRendered: (filename: string) => void;
+    feedbackEntries: Map<string, FeedbackEntry>;
+    setFeedbackEntry: (id: string, entry: FeedbackEntry) => void;
+    removeFeedbackEntry: (id: string) => void;
+    /** Canvas is rendered read-only (reviewing history). */
+    isReadOnly: boolean;
+}
+export declare const AnnotationCtx: import("react").Context<AnnotationContextValue>;
+export declare function useAnnotations(): AnnotationContextValue;
+/** Record that this revision asks the question, so submission can tell it from
+ *  an answer carried in for a question that is gone. Deliberately has no
+ *  cleanup: unmounting means the reader navigated away, not that the question
+ *  disappeared. */
+export declare function useResponseRegistration(id: string): void;
+export declare function useFeedback(id: string, markdown: string, options?: {
+    label?: string;
+    required?: boolean;
+}): void;
+export { SessionContext } from '@fabrika/annotations/runtime';
+export declare const CanvasFileCtx: import("react").Context<string>;
+export declare function useCanvasFile(): string;
+export type ActiveView = {
+    type: 'overview';
+} | {
+    type: 'canvas';
+    filename: string;
+} | {
+    type: 'file';
+    path: string;
+};
+export declare const ActiveViewCtx: import("react").Context<{
+    setActiveView: (v: ActiveView) => void;
+}>;

package/types/src/engine/compiler.d.ts

@@ -0,0 +1,44 @@
+import { type AssertReadable } from './file-admission';
+export type CompileResult = {
+    ok: true;
+    js: string;
+} | {
+    ok: false;
+    error: string;
+};
+type RequiredPropKind = 'array' | 'string';
+/**
+ * One name the compiler makes available to authored JSX without an import.
+ *
+ * `requiredProps` is enforced during the render validation pass below, so a
+ * canvas that forgets a prop fails at push time with a precise message instead
+ * of rendering blank in the browser.
+ */
+export interface CanvasComponentSpec {
+    requiredProps?: Record<string, RequiredPropKind>;
+}
+export type CanvasComponents = Record<string, CanvasComponentSpec>;
+/**
+ * The components every canvas host provides. Order is the order they appear in
+ * the injected destructure, so keep it stable for readable generated code.
+ */
+export declare const KERNEL_COMPONENTS: CanvasComponents;
+export interface CompileOptions {
+    /** Admission for static file reads, including resolved imports. Not a JavaScript sandbox. */
+    assertReadable?: AssertReadable;
+    /** Resolves `<FilePreview>` / `<Markdown file>` references at compile time. */
+    projectRoot?: string;
+    /** Scratch dir for the temp `.jsx` handed to Bun.build. Created on demand. */
+    tempDir?: string;
+    /**
+     * Host components to add on top of KERNEL_COMPONENTS, keyed by name. Each one
+     * must also be exported from the host's `#canvas/components` barrel — that is
+     * what the injected import actually reads at runtime. Re-declaring a kernel
+     * name overrides its spec.
+     */
+    components?: CanvasComponents;
+}
+export declare function compileJsx(jsx: string, options?: CompileOptions): Promise<CompileResult>;
+/** @deprecated Use `compileJsx(jsx, { projectRoot, tempDir })`. */
+export declare function compilePlan(jsx: string, projectRoot?: string): Promise<CompileResult>;
+export {};

package/types/src/engine/file-admission.d.ts

@@ -0,0 +1,6 @@
+export type AssertReadable = (path: string) => void;
+export declare class CanvasFileAdmissionError extends Error {
+    constructor();
+}
+export declare function assertCanvasFileReadable(path: string, assertReadable?: AssertReadable): void;
+export declare function readCanvasFile(path: string, assertReadable?: AssertReadable): string;

package/types/src/engine/paths.d.ts

@@ -0,0 +1,36 @@
+/**
+ * On-disk layout for one canvas host (agent-canvas, fabrika, …).
+ *
+ * Built explicitly by the host at startup rather than resolved from module-level
+ * constants, so importing the kernel has no side effects and two hosts can
+ * coexist in one process (tests rely on this).
+ */
+export interface CanvasPaths {
+    /** Persistent root — survives reboots. */
+    dataDir: string;
+    /** Session + revision store. */
+    sessionsDir: string;
+    /** Ephemeral root — may be lost on reboot. */
+    tempDir: string;
+    /** Daemon PID file. */
+    pidFile: string;
+    /** Scratch space for JSX compilation. */
+    compileTempDir: string;
+    /** Uploaded annotation images. */
+    uploadsDir: string;
+}
+export interface CanvasPathsConfig {
+    /** Namespace for on-disk locations, e.g. `"agent-canvas"` or `"fabrika"`. */
+    appName: string;
+    /**
+     * Persistent root. Defaults to `~/.claude/<appName>`. Hosts that keep data
+     * elsewhere — or that migrate from a legacy location — resolve it themselves
+     * and pass the result; the kernel holds no migration policy.
+     */
+    dataDir?: string;
+    /** Ephemeral root. Defaults to `<tmpdir>/<appName>`. */
+    tempDir?: string;
+    /** Create the directories. Pass `false` when only the strings are needed. */
+    ensure?: boolean;
+}
+export declare function createCanvasPaths(config: CanvasPathsConfig): CanvasPaths;

package/types/src/engine/session.d.ts

@@ -0,0 +1,176 @@
+export interface DiffStats {
+    added: number;
+    removed: number;
+}
+export interface CanvasFileInfo {
+    filename: string;
+    diffStats?: DiffStats;
+}
+/** How the caller selected the canvases in a revision. New revisions always
+ * carry this explicitly; its absence identifies legacy metadata. */
+export type CanvasScope = {
+    kind: 'view';
+    filename: string;
+} | {
+    kind: 'directory';
+};
+export interface RevisionInfo {
+    revision: number;
+    label?: string;
+    canvasFiles: CanvasFileInfo[];
+    createdAt: string;
+    hasFeedback: boolean;
+    feedbackConsumed: boolean;
+    response?: string;
+    canvasScope?: CanvasScope;
+}
+/**
+ * A single piece of feedback received from a remote (shared) reviewer.
+ * Structured so it can be merged into the local annotation system alongside
+ * the author's own annotations. `annotations` is the structured list of
+ * highlighted-text comments; `generalNote` is the free-form markdown.
+ */
+export interface RemoteFeedbackEntry {
+    /** Stable unique id assigned by the worker; used to dedupe on re-poll */
+    id: string;
+    shareId: string;
+    revision: number;
+    /** ISO timestamp when the reviewer submitted */
+    submittedAt: string;
+    author: {
+        id: string;
+        name: string;
+    };
+    annotations: RemoteAnnotation[];
+    generalNote?: string;
+}
+/**
+ * Mirror of the client-side Annotation shape, minus fields that only make
+ * sense locally. Kept intentionally narrow so the wire format is stable.
+ */
+export interface RemoteAnnotation {
+    id: string;
+    snippet: string;
+    note: string;
+    createdAt: string;
+    filePath?: string;
+    canvasFile?: string;
+    context?: {
+        before: string;
+        after: string;
+        hierarchy: string[];
+        lineStart?: number;
+        lineEnd?: number;
+    };
+    attachments?: {
+        url: string;
+        mime?: string;
+    }[];
+}
+/**
+ * A share is a snapshot of a specific revision that has been pushed to a
+ * remote endpoint (CF Worker) for external review. The `shareId` is the
+ * opaque capability token returned by the worker; the `url` is the full
+ * public URL the user shared with reviewers.
+ */
+export interface ShareEntry {
+    shareId: string;
+    url: string;
+    revision: number;
+    createdAt: string;
+    /** Bearer token returned by the worker — proves ownership for revoke. */
+    ownerToken?: string;
+    /** ISO timestamp when the share will expire on the worker side. */
+    expiresAt?: string;
+    /** ISO timestamp of the most recent remote feedback we've seen */
+    lastFeedbackAt?: string;
+    /** Base64url-encoded AES-GCM key for end-to-end encrypted shares. The
+     *  same key is also embedded in `url` as a `#k=...` fragment so reviewers
+     *  can decrypt; the daemon keeps a copy here so it can decrypt feedback
+     *  it polls back from the worker. Absent on legacy unencrypted shares. */
+    encryptionKey?: string;
+}
+export interface SessionData {
+    id: string;
+    projectRoot: string;
+    canvasFiles: string[];
+    currentRevision: number;
+    revisions: RevisionInfo[];
+    createdAt: string;
+    updatedAt: string;
+    shares?: ShareEntry[];
+}
+export type SecretResolution = {
+    ok: true;
+    values: Map<string, string>;
+} | {
+    ok: false;
+    missing: string[];
+};
+export declare class SessionManager {
+    private sessions;
+    private sessionSecrets;
+    private readonly sessionsDir;
+    /**
+     * @param sessionsDir On-disk sessions root, from `createCanvasPaths()`.
+     *   Tests pass an isolated temp directory so they don't interfere with
+     *   the user's real sessions.
+     */
+    constructor(sessionsDir: string);
+    private sessionDir;
+    private revisionDir;
+    /** Compute file order from revision history: first-appearance order, alpha for ties */
+    private deriveFileOrder;
+    /** List *.jsx filenames in a revision directory */
+    getRevisionCanvasFiles(id: string, rev: number): string[];
+    private loadFromDisk;
+    readRevisionJsx(id: string, rev: number, filename: string): string | null;
+    /**
+     * Create or update a session with a set of canvas files.
+     * @param canvasFiles Map of filename -> JSX content
+     */
+    upsert(id: string, canvasFiles: Map<string, string>, projectRoot: string, label?: string, response?: string, canvasScope?: CanvasScope): SessionData;
+    private persistMeta;
+    /** Record a new share for a session revision. */
+    addShare(id: string, entry: ShareEntry): void;
+    getShares(id: string): ShareEntry[];
+    removeShare(id: string, shareId: string): void;
+    updateShareLastFeedback(id: string, shareId: string, at: string): void;
+    /** List all sessions that have at least one share. Used by the remote feedback poller. */
+    listSessionsWithShares(): SessionData[];
+    private persistToDisk;
+    get(id: string): SessionData | undefined;
+    list(): SessionData[];
+    remove(id: string): void;
+    setSecret(id: string, fieldId: string, value: string): boolean;
+    hasSecret(id: string, fieldId: string): boolean;
+    clearSecret(id: string, fieldId: string): boolean;
+    resolveSecrets(id: string, fieldIds: string[]): SecretResolution | null;
+    saveCompiled(id: string, filename: string, js: string, rev?: number): void;
+    getCompiled(id: string, filename: string, rev?: number): string | null;
+    saveFeedback(id: string, rev: number, markdown: string): void;
+    getFeedback(id: string, rev: number): string | null;
+    consumeFeedback(id: string, rev: number): void;
+    getLatestUnconsumedFeedback(id: string): {
+        revision: number;
+        feedback: string;
+    } | null;
+    getRevisionJsxPath(id: string, rev: number, filename: string): string;
+    /**
+     * Remote feedback from shared views. Stored as one JSON file per revision
+     * at `revisions/{rev}/remote_feedback.json`, containing an array of
+     * RemoteFeedbackEntry. Appended to (not replaced) as new feedback arrives.
+     */
+    appendRemoteFeedback(id: string, rev: number, entries: RemoteFeedbackEntry[]): void;
+    getRemoteFeedback(id: string, rev: number): RemoteFeedbackEntry[];
+    /**
+     * Server-side backing store for an in-progress draft. Hosts that wire the
+     * AnnotationProvider's loadState/saveState to these endpoints get drafts that
+     * survive a reload and follow the author across browsers, instead of living
+     * in one browser's localStorage. Opaque payload — the shape is the client's.
+     */
+    saveResponses(id: string, rev: number, payload: unknown): void;
+    getResponses(id: string, rev: number): unknown | null;
+    /** Drop sessions untouched for longer than `maxAge` (default 24h). */
+    cleanupStale(maxAge?: number): void;
+}