@fabrika/canvas-kernel 0.1.45 → 0.3.1

package/src/engine/sessionSchemas.ts

@@ -0,0 +1,71 @@
+import { annotationAuthorSchema, annotationSchema } from '@fabrika/annotations/schemas'
+import { z } from 'zod'
+
+const diffStatsSchema = z.object({ added: z.number(), removed: z.number() }).passthrough()
+const revisionFields = {
+	revision: z.number().int(),
+	label: z.string().optional(),
+	createdAt: z.string(),
+	hasFeedback: z.boolean(),
+	feedbackConsumed: z.boolean(),
+	response: z.string().optional(),
+}
+const revisionSchema = z.object({
+	...revisionFields,
+	canvasFiles: z.array(z.object({ filename: z.string(), diffStats: diffStatsSchema.optional() }).passthrough()),
+	canvasScope: z.discriminatedUnion('kind', [
+		z.object({ kind: z.literal('view'), filename: z.string() }).passthrough(),
+		z.object({ kind: z.literal('directory') }).passthrough(),
+	]).optional(),
+}).passthrough()
+const legacyRevisionSchema = z.object({
+	...revisionFields,
+	canvasFiles: z.never().optional(),
+	sourceFile: z.string().optional(),
+	diffStats: diffStatsSchema.optional(),
+}).passthrough()
+const shareSchema = z.object({
+	shareId: z.string(),
+	url: z.string(),
+	revision: z.number().int(),
+	createdAt: z.string(),
+	ownerToken: z.string().optional(),
+	expiresAt: z.string().optional(),
+	lastFeedbackAt: z.string().optional(),
+	encryptionKey: z.string().optional(),
+}).passthrough()
+const metadataFields = {
+	projectRoot: z.string(),
+	createdAt: z.string(),
+	updatedAt: z.string(),
+}
+export const savedSessionMetadataSchema = z.object({
+	...metadataFields,
+	currentRevision: z.number().int(),
+	revisions: z.array(z.union([revisionSchema, legacyRevisionSchema])),
+	shares: z.array(shareSchema).optional(),
+}).passthrough().transform(meta => ({
+	migrated: meta.revisions.some(revision => revision.canvasFiles === undefined),
+	meta: {
+		...meta,
+		revisions: meta.revisions.map(revision => {
+			if (revision.canvasFiles !== undefined) return revision
+			const { sourceFile, diffStats, canvasFiles: _canvasFiles, ...fields } = revision
+			return { ...fields, canvasFiles: [{ filename: sourceFile || 'plan.jsx', diffStats }] }
+		}),
+	},
+}))
+
+export const remoteFeedbackEntrySchema = z.object({
+	id: z.string(),
+	shareId: z.string(),
+	revision: z.number().int(),
+	submittedAt: z.string(),
+	author: annotationAuthorSchema,
+	annotations: z.array(annotationSchema.omit({ images: true, source: true, author: true }).optional().catch(undefined))
+		.transform(annotations => annotations.filter(annotation => annotation !== undefined)),
+	generalNote: z.string().optional(),
+}).passthrough()
+
+export const remoteFeedbackSchema = z.array(remoteFeedbackEntrySchema.optional().catch(undefined))
+	.transform(entries => entries.filter(entry => entry !== undefined)).catch([])

package/src/engine/watcher.ts

@@ -1,84 +1,94 @@
-import { watch, existsSync, readFileSync, readdirSync } from "fs";
-import { join } from "path";
-import { compileJsx, type CanvasComponents } from "./compiler";
-import type { SessionManager } from "./session";
+import { existsSync, watch } from 'fs'
+import { type CanvasComponents, compileJsx } from './compiler'
+import { assertCanvasFileReadable, type AssertReadable, readCanvasFile } from './file-admission'
+import type { SessionManager } from './session'
 
-type BroadcastFn = (sessionId: string) => void;
+type BroadcastFn = (sessionId: string) => void
 
 export interface WatchOptions {
-  /** Scratch dir for recompiles, from `createCanvasPaths()`. */
-  tempDir?: string;
-  /** Host components, same value the push path compiles with — a recompile
-   *  that dropped them would fail on canvases the original push accepted. */
-  components?: CanvasComponents;
+	assertReadable?: AssertReadable
+	/** Scratch dir for recompiles, from `createCanvasPaths()`. */
+	tempDir?: string
+	/** Host components, same value the push path compiles with — a recompile
+	 *  that dropped them would fail on canvases the original push accepted. */
+	components?: CanvasComponents
 }
 
-const watchers = new Map<string, ReturnType<typeof watch>[]>();
+const watchers = new Map<string, ReturnType<typeof watch>[]>()
 
 export function watchSession(
-  sessionId: string,
-  sessionManager: SessionManager,
-  broadcast: BroadcastFn,
-  options: WatchOptions = {},
+	sessionId: string,
+	sessionManager: SessionManager,
+	broadcast: BroadcastFn,
+	options: WatchOptions = {},
 ) {
-  // Close existing watchers for this session
-  unwatchSession(sessionId);
+	// Close existing watchers for this session
+	unwatchSession(sessionId)
 
-  const session = sessionManager.get(sessionId);
-  if (!session) return;
+	const session = sessionManager.get(sessionId)
+	if (!session) return
 
-  const rev = session.currentRevision;
-  const canvasFiles = sessionManager.getRevisionCanvasFiles(sessionId, rev);
-  if (canvasFiles.length === 0) return;
+	const rev = session.currentRevision
+	const canvasFiles = sessionManager.getRevisionCanvasFiles(sessionId, rev)
+	if (canvasFiles.length === 0) return
 
-  const fileWatchers: ReturnType<typeof watch>[] = [];
-  const debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+	const fileWatchers: ReturnType<typeof watch>[] = []
+	const debounceTimers = new Map<string, ReturnType<typeof setTimeout>>()
+	const sources: { filename: string; filePath: string }[] = []
 
-  for (const filename of canvasFiles) {
-    const filePath = sessionManager.getRevisionJsxPath(sessionId, rev, filename);
-    if (!existsSync(filePath)) continue;
+	for (const filename of canvasFiles) {
+		const filePath = sessionManager.getRevisionJsxPath(sessionId, rev, filename)
+		if (!existsSync(filePath)) continue
+		assertCanvasFileReadable(filePath, options.assertReadable)
+		sources.push({ filename, filePath })
+	}
 
-    const watcher = watch(filePath, async (event) => {
-      if (event !== "change") return;
+	for (const { filename, filePath } of sources) {
+		const watcher = watch(filePath, async (event) => {
+			if (event !== 'change') return
 
-      // Debounce per-file
-      const existing = debounceTimers.get(filename);
-      if (existing) clearTimeout(existing);
+			// Debounce per-file
+			const existing = debounceTimers.get(filename)
+			if (existing) clearTimeout(existing)
 
-      debounceTimers.set(filename, setTimeout(async () => {
-        debounceTimers.delete(filename);
-        try {
-          const jsx = readFileSync(filePath, "utf-8");
-          const result = await compileJsx(jsx, {
-            projectRoot: session.projectRoot,
-            tempDir: options.tempDir,
-            ...(options.components ? { components: options.components } : {}),
-          });
-          if (result.ok) {
-            sessionManager.saveCompiled(sessionId, filename, result.js, rev);
-            broadcast(sessionId);
-          }
-        } catch {}
-      }, 200));
-    });
+			debounceTimers.set(
+				filename,
+				setTimeout(async () => {
+					debounceTimers.delete(filename)
+					try {
+						const jsx = readCanvasFile(filePath, options.assertReadable)
+						const result = await compileJsx(jsx, {
+							projectRoot: session.projectRoot,
+							tempDir: options.tempDir,
+							assertReadable: options.assertReadable,
+							...(options.components ? { components: options.components } : {}),
+						})
+						if (result.ok) {
+							sessionManager.saveCompiled(sessionId, filename, result.js, rev)
+							broadcast(sessionId)
+						}
+					} catch {}
+				}, 200),
+			)
+		})
 
-    fileWatchers.push(watcher);
-  }
+		fileWatchers.push(watcher)
+	}
 
-  watchers.set(sessionId, fileWatchers);
+	watchers.set(sessionId, fileWatchers)
 }
 
 export function unwatchSession(sessionId: string) {
-  const sessionWatchers = watchers.get(sessionId);
-  if (sessionWatchers) {
-    for (const w of sessionWatchers) w.close();
-    watchers.delete(sessionId);
-  }
+	const sessionWatchers = watchers.get(sessionId)
+	if (sessionWatchers) {
+		for (const w of sessionWatchers) w.close()
+		watchers.delete(sessionId)
+	}
 }
 
 export function unwatchAll() {
-  for (const [, sessionWatchers] of watchers) {
-    for (const w of sessionWatchers) w.close();
-  }
-  watchers.clear();
+	for (const [, sessionWatchers] of watchers) {
+		for (const w of sessionWatchers) w.close()
+	}
+	watchers.clear()
 }

package/src/engine/websocket.ts

@@ -4,156 +4,158 @@
  * so a delivery closes it.
  */
 
-import { browserFrame, createNotificationChannel, type ChannelSocket, type TopicChannel } from "./channel";
-import type { SessionManager, RemoteFeedbackEntry } from "./session";
+import { type ChannelSocket, createNotificationChannel, type TopicChannel } from '@fabrika/daemon-kit'
+import { z } from 'zod'
+import type { RemoteFeedbackEntry, SessionManager } from './session'
 
-export type WSData = { type: "browser" | "wait"; sessionId: string };
+export type WSData = { type: 'browser' | 'wait'; sessionId: string }
 
 export interface CanvasSocket extends ChannelSocket {
-  data: WSData;
+	data: WSData
 }
 
 interface CanvasRenderError {
-  revision: number;
-  filename: string;
-  message: string;
-  stack?: string;
-  componentStack?: string;
+	revision: number
+	filename: string
+	message: string
+	stack?: string
+	componentStack?: string
 }
 
 interface SubmitFrame {
-  type: "submit";
-  feedback: string;
+	type: 'submit'
+	feedback: string
 }
 
 interface RenderErrorFrame {
-  type: "render-error";
-  error: CanvasRenderError;
+	type: 'render-error'
+	error: CanvasRenderError
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isCanvasRenderError(value: unknown): value is CanvasRenderError {
-  return typeof value === "object" && value !== null
-    && "revision" in value && Number.isInteger(value.revision)
-    && "filename" in value && typeof value.filename === "string"
-    && "message" in value && typeof value.message === "string"
-    && (!("stack" in value) || value.stack === undefined || typeof value.stack === "string")
-    && (!("componentStack" in value) || value.componentStack === undefined || typeof value.componentStack === "string");
-}
-
-function isSubmitFrame(value: unknown): value is SubmitFrame {
-  return isRecord(value) && value.type === "submit" && typeof value.feedback === "string";
-}
-
-function isRenderErrorFrame(value: unknown): value is RenderErrorFrame {
-  return isRecord(value) && value.type === "render-error" && isCanvasRenderError(value.error);
-}
+const browserFrameSchema = z.discriminatedUnion('type', [
+	z.object({ type: z.literal('submit'), feedback: z.string() }).passthrough(),
+	z.object({
+		type: z.literal('render-error'),
+		error: z.object({
+			revision: z.number().int(),
+			filename: z.string(),
+			message: z.string(),
+			stack: z.string().optional(),
+			componentStack: z.string().optional(),
+		}).passthrough(),
+	}).passthrough(),
+])
 
 export interface WebSocketManagerOptions {
-  /**
-   * Who marks feedback consumed once a waiting client has been handed it.
-   *
-   * `"on-delivery"` (default) clears it in the same step, so the same feedback
-   * can never be delivered twice — right when the waiting client *is* the
-   * consumer. `"external"` leaves it pending for a separate gate to claim
-   * through the consume endpoint, for hosts where delivery and consumption are
-   * different steps.
-   */
-  feedbackConsumption?: "on-delivery" | "external";
+	/**
+	 * Who marks feedback consumed once a waiting client has been handed it.
+	 *
+	 * `"on-delivery"` (default) clears it in the same step, so the same feedback
+	 * can never be delivered twice — right when the waiting client *is* the
+	 * consumer. `"external"` leaves it pending for a separate gate to claim
+	 * through the consume endpoint, for hosts where delivery and consumption are
+	 * different steps.
+	 */
+	feedbackConsumption?: 'on-delivery' | 'external'
 }
 
 export function createWebSocketManager(
-  sessionManager: SessionManager,
-  options: WebSocketManagerOptions = {},
+	sessionManager: SessionManager,
+	options: WebSocketManagerOptions = {},
 ) {
-  const consumeOnDelivery = (options.feedbackConsumption ?? "on-delivery") === "on-delivery";
-  const pendingRenderErrors = new Map<string, CanvasRenderError>();
-
-  /** Hands a held error to the waiters, if any showed up; the caller announces the departure. */
-  function deliverPendingRenderError(sessionId: string): boolean {
-    const error = pendingRenderErrors.get(sessionId);
-    if (!error) return false;
-    if (!channel.relayToWaiters(sessionId, { type: "render-error", error })) return false;
-    pendingRenderErrors.delete(sessionId);
-    return true;
-  }
-
-  function submit(frame: SubmitFrame, topic: TopicChannel) {
-    const sessionId = topic.topic;
-    const session = sessionManager.get(sessionId);
-    if (!session) return;
-
-    sessionManager.saveFeedback(sessionId, session.currentRevision, frame.feedback);
-    broadcastRevisionUpdate(sessionId);
-    if (!topic.hasWaiter()) return;
-
-    if (consumeOnDelivery) {
-      sessionManager.consumeFeedback(sessionId, session.currentRevision);
-      broadcastRevisionUpdate(sessionId);
-    }
-    topic.relayToWaiters({ type: "submit", feedback: frame.feedback });
-  }
-
-  function renderError(frame: RenderErrorFrame, topic: TopicChannel) {
-    const sessionId = topic.topic;
-    const session = sessionManager.get(sessionId);
-    if (!session) return;
-    if (frame.error.revision !== session.currentRevision) return;
-    if (!session.canvasFiles.includes(frame.error.filename)) return;
-
-    pendingRenderErrors.set(sessionId, frame.error);
-    if (deliverPendingRenderError(sessionId)) topic.broadcastPresence();
-  }
-
-  const channel = createNotificationChannel<CanvasSocket>({
-    roleOf: (socket) => socket.data.type,
-    topicOf: (socket) => socket.data.sessionId,
-    waiterPolicy: "close-on-delivery",
-    presenceFrame: (watching) => ({ type: "watcher-status", watching }),
-    // A render error raised before the CLI watcher connected is held for it.
-    onWaiterOpen: (topic) => { deliverPendingRenderError(topic.topic); },
-    frames: [
-      browserFrame(isSubmitFrame, submit),
-      browserFrame(isRenderErrorFrame, renderError),
-    ],
-  });
-
-  function broadcastPlanUpdate(sessionId: string) {
-    pendingRenderErrors.delete(sessionId);
-    const session = sessionManager.get(sessionId);
-    if (!session) return;
-    channel.broadcast(sessionId, {
-      type: "plan-updated",
-      currentRevision: session.currentRevision,
-      revisions: session.revisions,
-    });
-  }
-
-  function broadcastRevisionUpdate(sessionId: string) {
-    const session = sessionManager.get(sessionId);
-    if (!session) return;
-    channel.broadcast(sessionId, {
-      type: "revision-updated",
-      revisions: session.revisions,
-    });
-  }
-
-  function broadcastRemoteFeedback(sessionId: string, revision: number, entries: RemoteFeedbackEntry[]) {
-    channel.broadcast(sessionId, { type: "remote-feedback", revision, entries });
-  }
-
-  function broadcastWatcherStatus(sessionId: string) {
-    channel.broadcastPresence(sessionId);
-  }
-
-  return {
-    handlers: channel.handlers,
-    broadcastPlanUpdate,
-    broadcastRevisionUpdate,
-    broadcastWatcherStatus,
-    broadcastRemoteFeedback,
-  };
+	const consumeOnDelivery = (options.feedbackConsumption ?? 'on-delivery') === 'on-delivery'
+	const pendingRenderErrors = new Map<string, CanvasRenderError>()
+
+	/** Hands a held error to the waiters, if any showed up; the caller announces the departure. */
+	function deliverPendingRenderError(sessionId: string): boolean {
+		const error = pendingRenderErrors.get(sessionId)
+		if (!error) return false
+		if (!channel.relayToWaiters(sessionId, { type: 'render-error', error })) return false
+		pendingRenderErrors.delete(sessionId)
+		return true
+	}
+
+	function submit(frame: SubmitFrame, topic: TopicChannel) {
+		const sessionId = topic.topic
+		const session = sessionManager.get(sessionId)
+		if (!session) return
+
+		sessionManager.saveFeedback(sessionId, session.currentRevision, frame.feedback)
+		broadcastRevisionUpdate(sessionId)
+		if (!topic.hasWaiter()) return
+
+		if (consumeOnDelivery) {
+			sessionManager.consumeFeedback(sessionId, session.currentRevision)
+			broadcastRevisionUpdate(sessionId)
+		}
+		topic.relayToWaiters({ type: 'submit', feedback: frame.feedback })
+	}
+
+	function renderError(frame: RenderErrorFrame, topic: TopicChannel) {
+		const sessionId = topic.topic
+		const session = sessionManager.get(sessionId)
+		if (!session) return
+		if (frame.error.revision !== session.currentRevision) return
+		if (!session.canvasFiles.includes(frame.error.filename)) return
+
+		pendingRenderErrors.set(sessionId, frame.error)
+		if (deliverPendingRenderError(sessionId)) topic.broadcastPresence()
+	}
+
+	const channel = createNotificationChannel<CanvasSocket>({
+		roleOf: (socket) => socket.data.type,
+		topicOf: (socket) => socket.data.sessionId,
+		waiterPolicy: 'close-on-delivery',
+		presenceFrame: (watching) => ({ type: 'watcher-status', watching }),
+		// A render error raised before the CLI watcher connected is held for it.
+		onWaiterOpen: (topic) => {
+			deliverPendingRenderError(topic.topic)
+		},
+		frames: [
+			{
+				bind(frame, topic) {
+					const parsed = browserFrameSchema.safeParse(frame)
+					if (!parsed.success) return undefined
+					const data = parsed.data
+					return () => data.type === 'submit' ? submit(data, topic) : renderError(data, topic)
+				},
+			},
+		],
+	})
+
+	function broadcastPlanUpdate(sessionId: string) {
+		pendingRenderErrors.delete(sessionId)
+		const session = sessionManager.get(sessionId)
+		if (!session) return
+		channel.broadcast(sessionId, {
+			type: 'plan-updated',
+			currentRevision: session.currentRevision,
+			revisions: session.revisions,
+		})
+	}
+
+	function broadcastRevisionUpdate(sessionId: string) {
+		const session = sessionManager.get(sessionId)
+		if (!session) return
+		channel.broadcast(sessionId, {
+			type: 'revision-updated',
+			revisions: session.revisions,
+		})
+	}
+
+	function broadcastRemoteFeedback(sessionId: string, revision: number, entries: RemoteFeedbackEntry[]) {
+		channel.broadcast(sessionId, { type: 'remote-feedback', revision, entries })
+	}
+
+	function broadcastWatcherStatus(sessionId: string) {
+		channel.broadcastPresence(sessionId)
+	}
+
+	return {
+		handlers: channel.handlers,
+		broadcastPlanUpdate,
+		broadcastRevisionUpdate,
+		broadcastWatcherStatus,
+		broadcastRemoteFeedback,
+	}
 }

package/annotate.ts

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