@fabrika/canvas-kernel 0.1.45 → 0.3.1

package/src/client/index.ts

@@ -1,128 +1,47 @@
-// @fabrika/canvas-kernel/client — the reusable annotation surface.
-//
-// Everything a host needs to render a compiled canvas and collect feedback on
-// it, minus the app shell (navigation, file browser, revision chrome), which
-// each host builds itself.
-
-// --- Annotation state ------------------------------------------------------
-// Everything that lives in runtime.ts is re-exported through `#canvas/runtime`,
-// never through a relative path. The runtime holds the React contexts and ships
-// as its own bundle shared with the compiled canvas; importing it relatively
-// would bundle a second copy, and the provider and its consumers would then be
-// writing to and reading from different contexts.
-export { AnnotationProvider } from "./AnnotationProvider";
-export type { PersistedState } from "./AnnotationProvider";
+export { AnnotationProvider } from './AnnotationProvider'
+export type { PersistedState } from './AnnotationProvider'
+export { feedbackEntrySchema, parsePersistedState, persistedStateSchema, planResponseSchema } from './persistenceSchemas'
+// Canvas documents and the shell must read the same external context instance.
 export {
-  useAnnotations,
-  useFeedback,
-  useCanvasFile,
-  useResponseRegistration,
-  AnnotationCtx,
-  SessionContext,
-  ActiveViewCtx,
-  CanvasFileCtx,
-} from "#canvas/runtime";
+	ActiveViewCtx,
+	AnnotationCtx,
+	CanvasFileCtx,
+	SessionContext,
+	useAnnotations,
+	useCanvasFile,
+	useFeedback,
+	useResponseRegistration,
+} from '#canvas/runtime'
 export type {
-  Annotation,
-  AnnotationAttachment,
-  AnnotationAuthor,
-  AnnotationContext,
-  AnnotationContextValue,
-  ActiveView,
-  FeedbackEntry,
-  PlanResponse,
-} from "#canvas/runtime";
-
-// --- Surface ---------------------------------------------------------------
-export { AnnotationSidebar } from "./AnnotationSidebar";
-// The sidebar's reusable halves. Grouping stayed with the sidebar — what an
-// annotation belongs to is the host's taxonomy, so the host slices the list.
-export { AnnotationList } from "./AnnotationList";
-export type { AnnotationListProps } from "./AnnotationList";
-export { AnnotationDraftFooter } from "./AnnotationDraftFooter";
-export type { AnnotationDraftFooterProps } from "./AnnotationDraftFooter";
-export { AnnotationEditor, imageToUrl } from "./AnnotationEditor";
-export { PlanRenderer } from "./PlanRenderer";
-export { Popover, AnnotationPopover, AnnotationCreatePopover, AnnotationEditPopover } from "./Popover";
-export { ResponsePreview, MarkdownPreview } from "./ResponsePreview";
-export { FileIcon } from "./FileIcon";
-
-/** The kernel component set, as a namespace for hosts that inject it wholesale. */
-export * as components from "./components";
-export { useTextAnnotation } from "./useTextAnnotation";
-export { useRegionAnnotation } from "./useRegionAnnotation";
-
-// --- Host-provided context -------------------------------------------------
-export { CanvasHostContext, localCanvasHost, useCanvasHost } from "./hostContext";
-export type { CanvasHost } from "./hostContext";
-export { ActiveViewContext, RevisionContext } from "./appContext";
-export type { CanvasFileInfo, RevisionInfo } from "./appContext";
-export { RenderErrorContext } from "./RenderErrorContext";
-export type { CanvasRenderError } from "./RenderErrorContext";
-
-// --- Annotation plumbing ---------------------------------------------------
-export { extractContext, formatSnippetInContext } from "./annotationContext";
+	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 {
-  ANNOTATION_TARGETS,
-  ANNOTATABLE_SELECTOR,
-  BLOCK_SELECTOR,
-  describeSnippet,
-  findAnnotationElement,
-  findSnippetElement,
-  getBlockSnippet,
-  restoreAnnotationTargets,
-  scrollToAnnotation,
-} from "./annotationDom";
-
-// --- Locator strategies ----------------------------------------------------
-// What a snippet points at is the one thing in an annotation that is domain
-// specific. A host that needs to annotate something the kernel has no target
-// for writes one of these; nothing else has to change.
-export { sealTarget } from "./annotationTarget";
-export type { AnnotationTarget, SealedAnnotationTarget, TargetAnnotation } from "./annotationTarget";
-export { blockTarget } from "./blockTarget";
-export type { BlockLocator } from "./blockTarget";
-export { textTarget } from "./textTarget";
-export type { TextLocator } from "./textTarget";
-export {
-  createRegionOverlay,
-  describeRegion,
-  findRegionHost,
-  isDrawableRegion,
-  regionBetween,
-  regionPointIn,
-  regionStyle,
-  regionTarget,
-  REGION_HOST_ATTR,
-  REGION_UNITS,
-} from "./regionTarget";
-export type { RegionBox, RegionLocator, RegionPoint, RegionShape } from "./regionTarget";
-export {
-  annotationDraftKey,
-  carryUnsubmittedDraft,
-  clearPersistedDraft,
-} from "./annotationDraft";
-export type { AnnotationDraftPhase } from "./annotationDraft";
-export {
-  restoreMarks,
-  renameMarkId,
-  setMarkActive,
-  unwrapMarks,
-  updateAllMarkStates,
-  wrapRangeWithMark,
-} from "./highlightRange";
-// One annotation as markdown — the half of feedback that belongs to no
-// particular document format. `generateMarkdown` below is the canvas format
-// built on it; a host with its own headings calls this directly.
-export { renderAnnotation } from "./annotationMarkdown";
-export type { RenderableAnnotation } from "./annotationMarkdown";
-export {
-  canPruneResponses,
-  generateMarkdown,
-  getMissingRequired,
-  getMissingRequiredFeedback,
-  getMissingRequiredLabels,
-  hasValue,
-  pruneStaleResponses,
-} from "./generateMarkdown";
-export { autoResizeTextarea, fileAnnotationPath, generateAnnotationId, hostAcceptsUploads, RESPONSE_ANNOTATION_PATH } from "./utils";
+	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/src/client/pageGlobals.ts

@@ -0,0 +1,25 @@
+// highlight.js and mermaid reach the page as <script> tags from the host, not through the bundle.
+
+interface HighlightJs {
+	highlightElement(element: HTMLElement): void
+}
+
+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 function pageHighlighter(): HighlightJs | undefined {
+	return window.hljs
+}
+
+export function pageMermaid(): MermaidApi | undefined {
+	return window.mermaid
+}

package/src/client/persistenceSchemas.ts

@@ -0,0 +1,41 @@
+import { annotationStateSchema } from '@fabrika/annotations/schemas'
+import { z } from 'zod'
+
+export const planResponseSchema = z.object({
+	id: z.string(),
+	type: z.enum(['select', 'radio', 'checkbox', 'text', 'range']),
+	label: z.string(),
+	value: z.unknown(),
+	options: z.array(z.string()).optional(),
+	required: z.boolean().optional(),
+	note: z.string().optional(),
+}).passthrough().transform(response => ({ ...response, value: response.value }))
+
+export const feedbackEntrySchema = z.object({
+	id: z.string(),
+	markdown: z.string(),
+	label: z.string().optional(),
+	required: z.boolean().optional(),
+}).passthrough()
+
+export const persistedStateSchema = annotationStateSchema.extend({
+	responses: z.array(
+		z.tuple([z.string(), planResponseSchema]).optional().catch(undefined),
+	)
+		.transform(entries => entries.filter(entry => entry !== undefined)).catch([]),
+	feedbackEntries: z.array(
+		z.tuple([z.string(), feedbackEntrySchema]).optional().catch(undefined),
+	)
+		.transform(entries => entries.filter(entry => entry !== undefined)).optional().catch([]),
+})
+
+export function parsePersistedState(value: unknown) {
+	const result = persistedStateSchema.safeParse(value)
+	return result.success ? result.data : null
+}
+
+export const feedbackResponseSchema = z.object({ feedback: z.string().nullish() })
+export const filePreviewResponseSchema = z.union([
+	z.object({ error: z.string().min(1) }),
+	z.object({ content: z.string(), language: z.string().nullish() }),
+])

package/src/client/preact-all.ts

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

package/src/client/runtime.ts

@@ -2,105 +2,52 @@
 // The React.createContext call MUST live here (not in AnnotationProvider)
 // so that both bundles reference the same context object.
 
-import { createContext, useContext, useEffect } from "react";
+import { createContext, useContext, useEffect } from 'react'
 
-export interface AnnotationContext {
-  before: string;
-  after: string;
-  hierarchy: string[];
-  lineStart?: number;
-  lineEnd?: number;
-}
-
-/** Identifies the person who created an annotation. For local annotations
- *  this is the daemon owner (unset). For remote annotations it carries the
- *  reviewer's self-reported name + stable anonymous id assigned by the worker. */
-export interface AnnotationAuthor {
-  id: string;
-  name: string;
-}
-
-/** An image or other file attached to an annotation. The richer sibling of
- *  `images: string[]`, carrying a mime type alongside a URL that can point at
- *  either a local upload (daemon) or a remote blob (CF Worker R2). */
-export interface AnnotationAttachment {
-  url: string;
-  mime?: string;
-}
-
-export interface Annotation {
-  id: string;
-  snippet: string;
-  note: string;
-  createdAt: string;
-  filePath?: string;
-  canvasFile?: string;
-  context?: AnnotationContext;
-  /** Attachments written by the local editor, as bare upload paths/URLs. Still
-   *  the only field it writes, and what persisted drafts hold. */
-  images?: string[];
-  /** Attachments that arrived over the wire, from a reviewer on a shared
-   *  canvas. Both fields render — see `renderAnnotation`. */
-  attachments?: AnnotationAttachment[];
-  /** "remote" annotations come from a shared view and are read-only locally. */
-  source?: "local" | "remote";
-  /** Only set for source === "remote". */
-  author?: AnnotationAuthor;
-}
+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: any;
-  options?: string[];
-  required?: boolean;
-  note?: string;
+	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;
+	id: string
+	markdown: string
+	label?: string
+	required?: boolean
 }
 
-export interface AnnotationContextValue {
-  annotations: Annotation[];
-  addAnnotation: (snippet: string, note: string, filePath?: string) => void;
-  addAnnotationWithId: (id: string, snippet: string, note: string, filePath?: string, context?: AnnotationContext, images?: string[], canvasFile?: string) => void;
-  updateAnnotation: (id: string, note: string) => void;
-  removeAnnotation: (id: string) => void;
-  addAnnotationImage: (id: string, imagePath: string) => void;
-  removeAnnotationImage: (id: string, imagePath: string) => void;
-  generalNote: string;
-  setGeneralNote: (text: string) => void;
-  clearAll: () => void;
-  activeAnnotationId: string | null;
-  setActiveAnnotationId: (id: string | null) => void;
-  /** 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 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 const AnnotationCtx = createContext<AnnotationContextValue>(null!);
+export const AnnotationCtx = createContext<AnnotationContextValue>(null!)
 
 export function useAnnotations(): AnnotationContextValue {
-  return useContext(AnnotationCtx);
+	return useContext(AnnotationCtx)
 }
 
 /** Record that this revision asks the question, so submission can tell it from
@@ -108,42 +55,42 @@ export function useAnnotations(): AnnotationContextValue {
  *  cleanup: unmounting means the reader navigated away, not that the question
  *  disappeared. */
 export function useResponseRegistration(id: string): void {
-  const { registerResponse } = useAnnotations();
-  useEffect(() => {
-    registerResponse(id);
-  }, [id, registerResponse]);
+	const { registerResponse } = useAnnotations()
+	useEffect(() => {
+		registerResponse(id)
+	}, [id, registerResponse])
 }
 
 export function useFeedback(
-  id: string,
-  markdown: string,
-  options?: { label?: string; required?: boolean },
+	id: string,
+	markdown: string,
+	options?: { label?: string; required?: boolean },
 ): void {
-  const { setFeedbackEntry, removeFeedbackEntry } = useAnnotations();
-  useEffect(() => {
-    setFeedbackEntry(id, {
-      id,
-      markdown,
-      label: options?.label,
-      required: options?.required,
-    });
-    return () => removeFeedbackEntry(id);
-  }, [id, markdown, options?.label, options?.required]);
+	const { setFeedbackEntry, removeFeedbackEntry } = useAnnotations()
+	useEffect(() => {
+		setFeedbackEntry(id, {
+			id,
+			markdown,
+			label: options?.label,
+			required: options?.required,
+		})
+		return () => removeFeedbackEntry(id)
+	}, [id, markdown, options?.label, options?.required])
 }
 
-export { SessionContext } from "./SessionContext";
+export { SessionContext } from '@fabrika/annotations/runtime'
 
 // CanvasFile context — tells components which canvas file they belong to
-export const CanvasFileCtx = createContext<string>("");
+export const CanvasFileCtx = createContext<string>('')
 export function useCanvasFile(): string {
-  return useContext(CanvasFileCtx);
+	return useContext(CanvasFileCtx)
 }
 
 // ActiveView navigation — allows components (e.g. FilePreview) to open files
-export type ActiveView = { type: "overview" } | { type: "canvas"; filename: string } | { type: "file"; path: string };
+export type ActiveView = { type: 'overview' } | { type: 'canvas'; filename: string } | { type: 'file'; path: string }
 
 export const ActiveViewCtx = createContext<{
-  setActiveView: (v: ActiveView) => void;
+	setActiveView: (v: ActiveView) => void
 }>({
-  setActiveView: () => {},
-});
+	setActiveView: () => {},
+})

package/src/client/styles.css

@@ -2,6 +2,7 @@
 
 @import "tailwindcss";
 @import "./theme.css";
+@import "@fabrika/annotations/styles.css";
 @source "./**/*.{tsx,ts,jsx,js}";
 
 /* ── Non-theme CSS variables (not used by Tailwind utilities, just custom CSS) ── */
@@ -96,80 +97,6 @@ code, pre, .font-mono {
   font-family: 'JetBrains Mono', 'Fira Code', Consolas, monospace;
 }
 
-/* Annotation inline marks */
-mark[data-annotation-id] {
-  background: var(--color-highlight-annotation);
-  border-bottom: 1.5px solid var(--color-highlight-bg);
-  border-radius: 2px;
-  cursor: pointer;
-  transition: background 150ms ease, box-shadow 150ms ease;
-  color: inherit;
-  padding: 1px 0;
-}
-
-mark[data-annotation-id].mark-active {
-  background: var(--color-highlight-active);
-  border-bottom: 2px solid var(--color-highlight-border);
-  box-shadow: 0 0 0 1px var(--color-highlight-border);
-}
-
-@keyframes ann-flash {
-  0%, 100% { background: var(--color-highlight-annotation); }
-  25%, 75% { background: var(--color-highlight-active); }
-}
-
-.ann-flash {
-  animation: ann-flash 0.6s ease 2;
-}
-
-/* Region annotations — a normalized box drawn over an image block. The host
-   positions the boxes, so every host that marks one gets them placed right. */
-[data-annotation-image] {
-  position: relative;
-  cursor: crosshair;
-  touch-action: none;
-}
-
-.ann-region {
-  position: absolute;
-  background: var(--color-highlight-annotation);
-  border: 2px solid var(--color-highlight-bg);
-  border-radius: 2px;
-  cursor: pointer;
-  transition: background 150ms ease, box-shadow 150ms ease;
-}
-
-.ann-region[data-annotation-region="ellipse"] {
-  border-radius: 50%;
-}
-
-.ann-region.mark-active {
-  background: var(--color-highlight-active);
-  border-color: var(--color-highlight-border);
-  box-shadow: 0 0 0 1px var(--color-highlight-border);
-}
-
-/* The box being dragged out: not yet an annotation, and never a hit target. */
-.ann-region-draft {
-  pointer-events: none;
-  border-style: dashed;
-  border-color: var(--color-highlight-border);
-}
-
-/* Annotation highlight (legacy) */
-.annotation-highlight {
-  background: var(--color-highlight-bg);
-  border-bottom: 2px solid var(--color-highlight-border);
-  border-radius: 2px;
-  cursor: pointer;
-  transition: background 150ms ease;
-}
-
-.annotation-highlight:hover,
-.annotation-highlight.active {
-  background: var(--color-highlight-active);
-}
-
 /* Selection color */
 ::selection {
   background-color: var(--color-highlight-active);