@bendyline/squisq 1.3.0 → 1.4.1

package/src/icons/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Icons barrel — subpath `@bendyline/squisq/icons`.
+ *
+ * Exposes the FontAwesome Free catalog (`ICONS`, `IconEntry`,
+ * `IconFamily`) and the lookup helpers (`resolveIcon`,
+ * `canonicalIconToken`, `looksLikeIconToken`).
+ */
+
+export { ICONS } from './iconData.js';
+export type { IconEntry, IconFamily } from './iconData.js';
+export {
+  resolveIcon,
+  canonicalIconToken,
+  looksLikeIconToken,
+  suggestIcons,
+  iconGlyph,
+} from './resolve.js';
+export type { IconSuggestion } from './resolve.js';

package/src/icons/resolve.ts

@@ -0,0 +1,139 @@
+/**
+ * Icon Resolver
+ *
+ * Looks up a user-supplied token against the FontAwesome Free catalog.
+ *
+ * Tokens come in two forms:
+ * - **Bare** (`github`) — resolves only when the name is unique across
+ *   families. The picker prefers this form for friendliness.
+ * - **Qualified** (`fa-brands:github`, `fa-solid:user`) — required when
+ *   the name collides across families (e.g. `user` ships in both solid
+ *   and regular).
+ *
+ * Returning `null` from `resolveIcon` is a deliberate signal: callers
+ * should render the source token verbatim so authors can write
+ * `{[notathing]}` in prose without it being silently swallowed.
+ */
+
+import { ICONS } from './iconData.js';
+import type { IconEntry, IconFamily } from './iconData.js';
+
+// Index built once per module: name → IconEntry[]. Multi-entry buckets
+// indicate cross-family collisions that require a qualified token.
+const BY_NAME = new Map<string, IconEntry[]>();
+for (const entry of ICONS) {
+  const bucket = BY_NAME.get(entry.name);
+  if (bucket) bucket.push(entry);
+  else BY_NAME.set(entry.name, [entry]);
+}
+
+const FAMILY_PREFIXES: Record<string, IconFamily> = {
+  'fa-brands': 'brands',
+  'fa-solid': 'solid',
+  'fa-regular': 'regular',
+  brands: 'brands',
+  solid: 'solid',
+  regular: 'regular',
+};
+
+/**
+ * True when a token looks like an icon reference. Used by the markdown
+ * parser to decide whether a `{[…]}` body in a heading is worth probing
+ * (the heading-template path already extracted the trailing annotation
+ * by the time inline detection runs).
+ */
+export function looksLikeIconToken(token: string): boolean {
+  return /^[a-zA-Z0-9_:-]+$/.test(token);
+}
+
+/**
+ * Resolve a token to an icon. Returns `null` when the token is unknown
+ * OR when the bare form collides — callers should render `null` results
+ * as literal markdown text so authors can opt out by qualifying.
+ */
+export function resolveIcon(token: string): IconEntry | null {
+  if (!looksLikeIconToken(token)) return null;
+  // Qualified form: `<family-prefix>:<name>`.
+  const colon = token.indexOf(':');
+  if (colon > 0) {
+    const prefix = token.slice(0, colon);
+    const name = token.slice(colon + 1);
+    const family = FAMILY_PREFIXES[prefix];
+    if (!family) return null;
+    const bucket = BY_NAME.get(name);
+    return bucket?.find((e) => e.family === family) ?? null;
+  }
+  // Bare form: must be unique across families.
+  const bucket = BY_NAME.get(token);
+  if (!bucket || bucket.length !== 1) return null;
+  return bucket[0];
+}
+
+/**
+ * The canonical "shortest unambiguous" token for an icon — bare if the
+ * name is unique, otherwise the qualified form. Used when serializing
+ * a resolved icon back to markdown so we don't gratuitously qualify
+ * names that don't need it.
+ */
+export function canonicalIconToken(entry: IconEntry): string {
+  const bucket = BY_NAME.get(entry.name);
+  if (bucket && bucket.length === 1) return entry.name;
+  return `fa-${entry.family}:${entry.name}`;
+}
+
+/**
+ * Render the icon's Unicode codepoint as a single-character string.
+ * Returns `''` for entries without a codepoint (defensive — FA always
+ * has one). Used by editors and previews that want to display the
+ * actual glyph using the FontAwesome font; pair with the right
+ * font-family/font-weight for the icon's family.
+ */
+export function iconGlyph(entry: IconEntry): string {
+  if (!entry.unicode) return '';
+  const code = parseInt(entry.unicode, 16);
+  if (!Number.isFinite(code)) return '';
+  return String.fromCodePoint(code);
+}
+
+/** Single autocomplete suggestion. `score` ranks lower-is-better:
+ *  0 = name starts-with query, 1 = name contains query,
+ *  2 = keyword contains query. */
+export interface IconSuggestion {
+  entry: IconEntry;
+  token: string;
+  score: number;
+}
+
+/**
+ * Rank icons against a partial token typed by the user. Used by the
+ * Monaco completion provider in editor-react and re-exported so any
+ * host can build its own typeahead.
+ */
+export function suggestIcons(query: string, limit = 50): IconSuggestion[] {
+  const q = query.trim().toLowerCase();
+  const matches: IconSuggestion[] = [];
+  for (const icon of ICONS) {
+    let score = -1;
+    if (!q) {
+      // Empty query — surface a few common icons. We just walk in
+      // order; the limit cuts it off.
+      score = 3;
+    } else if (icon.name.startsWith(q)) {
+      score = 0;
+    } else if (icon.name.includes(q)) {
+      score = 1;
+    } else if (icon.keywords.includes(q)) {
+      score = 2;
+    }
+    if (score < 0) continue;
+    matches.push({ entry: icon, token: canonicalIconToken(icon), score });
+    if (matches.length > 400) break; // hard cap before sort
+  }
+  matches.sort(
+    (a, b) =>
+      a.score - b.score || a.token.length - b.token.length || a.token.localeCompare(b.token),
+  );
+  return matches.slice(0, limit);
+}
+
+export type { IconEntry, IconFamily };

package/src/imageEdit/ImageEditVersionManager.ts

@@ -0,0 +1,73 @@
+/**
+ * Convenience wrapper around the image-edit version operations that
+ * captures a {@link ContentContainer} reference and an optional basename
+ * override. Mirrors `DocumentVersionManager` in shape.
+ */
+
+import type { ContentContainer } from '../storage/ContentContainer.js';
+import type { CoalesceOptions, PrunePolicy, Version } from '../versions/types.js';
+import {
+  coalesceImageEditVersions,
+  listImageEditVersions,
+  pruneImageEditVersions,
+  readImageEditVersion,
+  revertToImageEditVersion,
+  saveImageEditVersion,
+  type RevertImageEditOptions,
+  type SaveImageEditVersionOptions,
+  type SaveImageEditVersionResult,
+} from './versions.js';
+import type { ImageEditDoc } from '../schemas/ImageEditDoc.js';
+
+export interface ImageEditVersionManagerOptions {
+  /** Override the basename used in version filenames. Defaults to `'state'`. */
+  basename?: string;
+  /** Override the source filename inside the sidecar. Defaults to `state.json`. */
+  stateFilename?: string;
+}
+
+export class ImageEditVersionManager {
+  private readonly container: ContentContainer;
+  private readonly basename: string | undefined;
+  private readonly stateFilename: string | undefined;
+
+  constructor(container: ContentContainer, options: ImageEditVersionManagerOptions = {}) {
+    this.container = container;
+    this.basename = options.basename;
+    this.stateFilename = options.stateFilename;
+  }
+
+  saveVersion(options: SaveImageEditVersionOptions = {}): Promise<SaveImageEditVersionResult> {
+    return saveImageEditVersion(this.container, {
+      basename: this.basename,
+      stateFilename: this.stateFilename,
+      ...options,
+    });
+  }
+
+  listVersions(): Promise<Version[]> {
+    return listImageEditVersions(this.container, this.basename);
+  }
+
+  readVersion(version: Version | string): Promise<ImageEditDoc | null> {
+    return readImageEditVersion(this.container, version);
+  }
+
+  revertToVersion(
+    version: Version | string,
+    options: RevertImageEditOptions = {},
+  ): Promise<{ reverted: boolean; snapshotted: Version | null }> {
+    return revertToImageEditVersion(this.container, version, {
+      stateFilename: this.stateFilename,
+      ...options,
+    });
+  }
+
+  pruneVersions(policy: PrunePolicy): Promise<Version[]> {
+    return pruneImageEditVersions(this.container, policy, this.basename);
+  }
+
+  coalesceVersions(options: CoalesceOptions = {}): Promise<Version[]> {
+    return coalesceImageEditVersions(this.container, options, this.basename);
+  }
+}

package/src/imageEdit/export.ts

@@ -0,0 +1,326 @@
+/**
+ * Rasterize an {@link ImageEditDoc} to a PNG / JPEG / WebP {@link Blob}.
+ *
+ * The pipeline:
+ *   1. Build an SVG string mirroring the canvas + layers, with image
+ *      hrefs inlined as `data:` URLs (so the canvas isn't tainted).
+ *   2. Wrap the SVG in a `Blob` and load it through an `Image`.
+ *   3. Draw it onto a canvas (`OffscreenCanvas` when available,
+ *      otherwise a detached `HTMLCanvasElement`).
+ *   4. Convert the canvas to the requested format.
+ *
+ * Browser-only — calls `Image`, `URL.createObjectURL`, and canvas APIs.
+ * Returns a Promise that rejects on SVG parse / load failures.
+ */
+
+import type { ContentContainer } from '../storage/ContentContainer.js';
+import type { ImageEditCanvas, ImageEditDoc, ImageEditLayer } from '../schemas/ImageEditDoc.js';
+import type { Position } from '../schemas/Doc.js';
+
+/** Supported export formats. */
+export type ImageEditExportFormat = 'png' | 'jpeg' | 'webp';
+
+/** Options for {@link exportImageEditDoc}. */
+export interface ImageEditExportOptions {
+  /** Output format. Defaults to `'png'`. */
+  format?: ImageEditExportFormat;
+  /** JPEG/WebP quality 0..1. Defaults to `0.92`. Ignored for PNG. */
+  quality?: number;
+  /** Resolution scale factor. Defaults to `1` (canvas pixels = output pixels). */
+  scale?: number;
+}
+
+const FORMAT_MIME: Record<ImageEditExportFormat, string> = {
+  png: 'image/png',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+};
+
+/**
+ * Export the doc to a raster {@link Blob}. Asset bytes referenced by image
+ * layers are read from `container` and inlined as data URLs.
+ */
+export async function exportImageEditDoc(
+  doc: ImageEditDoc,
+  container: ContentContainer,
+  options: ImageEditExportOptions = {},
+): Promise<Blob> {
+  const format: ImageEditExportFormat = options.format ?? 'png';
+  const quality = options.quality ?? 0.92;
+  const scale = options.scale ?? 1;
+  const mime = FORMAT_MIME[format];
+
+  const svg = await buildSvgString(doc, container);
+  const outW = Math.max(1, Math.round(doc.canvas.width * scale));
+  const outH = Math.max(1, Math.round(doc.canvas.height * scale));
+
+  const img = await loadSvgImage(svg);
+  const canvas = createRasterCanvas(outW, outH);
+  const ctx = canvas.getContext('2d');
+  if (!ctx) throw new Error('exportImageEditDoc: 2D canvas context unavailable');
+
+  // For JPEG (no alpha), pre-fill with the canvas background or white so
+  // transparent regions aren't rendered as black.
+  if (format === 'jpeg') {
+    const bg =
+      doc.canvas.background && doc.canvas.background !== 'transparent'
+        ? doc.canvas.background
+        : '#ffffff';
+    ctx.fillStyle = bg;
+    ctx.fillRect(0, 0, outW, outH);
+  }
+
+  ctx.drawImage(img as CanvasImageSource, 0, 0, outW, outH);
+  return canvasToBlob(canvas, mime, quality);
+}
+
+// ============================================
+// SVG construction
+// ============================================
+
+async function buildSvgString(doc: ImageEditDoc, container: ContentContainer): Promise<string> {
+  const { width, height, background } = doc.canvas;
+  const bgRect =
+    background && background !== 'transparent'
+      ? `<rect width="${width}" height="${height}" fill="${escapeAttr(background)}"/>`
+      : '';
+
+  const layerXml: string[] = [];
+  for (const layer of doc.layers) {
+    if (layer.visible === false) continue;
+    layerXml.push(await renderLayerToSvg(layer, doc.canvas, container));
+  }
+
+  return (
+    `<?xml version="1.0" encoding="UTF-8"?>` +
+    `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"` +
+    ` width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">` +
+    bgRect +
+    layerXml.join('') +
+    `</svg>`
+  );
+}
+
+async function renderLayerToSvg(
+  layer: ImageEditLayer,
+  canvas: ImageEditCanvas,
+  container: ContentContainer,
+): Promise<string> {
+  const opacity = layer.opacity ?? 1;
+  const opacityAttr = opacity < 1 ? ` opacity="${opacity}"` : '';
+  const inner = await renderLayerInner(layer, canvas, container);
+  return `<g data-layer-id="${escapeAttr(layer.id)}"${opacityAttr}>${inner}</g>`;
+}
+
+async function renderLayerInner(
+  layer: ImageEditLayer,
+  canvas: ImageEditCanvas,
+  container: ContentContainer,
+): Promise<string> {
+  const { x, y, w, h } = resolveBox(layer.position, canvas);
+
+  if (layer.type === 'image') {
+    const dataUrl = await loadAssetAsDataUrl(container, layer.content.src);
+    return (
+      `<image x="${x}" y="${y}" width="${w}" height="${h}"` +
+      ` preserveAspectRatio="${preserveAspectRatioFor(layer.content.fit)}"` +
+      ` xlink:href="${escapeAttr(dataUrl)}"/>`
+    );
+  }
+
+  if (layer.type === 'shape') {
+    const c = layer.content;
+    const fill = c.fill ?? 'none';
+    const stroke = c.stroke ? ` stroke="${escapeAttr(c.stroke)}"` : '';
+    const strokeWidth = c.strokeWidth ? ` stroke-width="${c.strokeWidth}"` : '';
+    if (c.shape === 'rect') {
+      const rx = c.borderRadius ? ` rx="${c.borderRadius}" ry="${c.borderRadius}"` : '';
+      return `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="${escapeAttr(fill)}"${stroke}${strokeWidth}${rx}/>`;
+    }
+    if (c.shape === 'circle') {
+      const r = Math.min(w, h) / 2;
+      return `<circle cx="${x + w / 2}" cy="${y + h / 2}" r="${r}" fill="${escapeAttr(fill)}"${stroke}${strokeWidth}/>`;
+    }
+    // line
+    return `<line x1="${x}" y1="${y}" x2="${x + w}" y2="${y + h}"${stroke}${strokeWidth}/>`;
+  }
+
+  // text
+  const c = layer.content;
+  const style = c.style;
+  const lineHeight = style.lineHeight ?? 1.4;
+  const lineHeightPx = style.fontSize * lineHeight;
+  const lines = (c.text ?? '').split('\n');
+  const tspans = lines
+    .map(
+      (line, i) => `<tspan x="${x}" dy="${i === 0 ? 0 : lineHeightPx}">${escapeText(line)}</tspan>`,
+    )
+    .join('');
+  const fontFamily = style.fontFamily ?? 'sans-serif';
+  const fontWeight = style.fontWeight ?? 'normal';
+  const textAnchor =
+    style.textAlign === 'center' ? 'middle' : style.textAlign === 'right' ? 'end' : 'start';
+  return (
+    `<text x="${x}" y="${y + style.fontSize}" font-family="${escapeAttr(fontFamily)}"` +
+    ` font-size="${style.fontSize}" font-weight="${fontWeight}"` +
+    ` fill="${escapeAttr(style.color)}" text-anchor="${textAnchor}">` +
+    tspans +
+    `</text>`
+  );
+}
+
+function preserveAspectRatioFor(fit?: 'cover' | 'contain' | 'fill'): string {
+  if (fit === 'cover') return 'xMidYMid slice';
+  if (fit === 'fill') return 'none';
+  return 'xMidYMid meet'; // contain (default)
+}
+
+function resolveBox(
+  position: Position,
+  canvas: ImageEditCanvas,
+): { x: number; y: number; w: number; h: number } {
+  const x = resolveValue(position.x, canvas.width);
+  const y = resolveValue(position.y, canvas.height);
+  const w =
+    position.width !== undefined ? resolveValue(position.width, canvas.width) : canvas.width;
+  const h =
+    position.height !== undefined ? resolveValue(position.height, canvas.height) : canvas.height;
+  const offset = anchorOffset(position.anchor, w, h);
+  return { x: x + offset.x, y: y + offset.y, w, h };
+}
+
+function resolveValue(v: number | string, base: number): number {
+  if (typeof v === 'number') return v;
+  if (v.endsWith('%')) return (parseFloat(v) / 100) * base;
+  return parseFloat(v) || 0;
+}
+
+function anchorOffset(
+  anchor: Position['anchor'] | undefined,
+  w: number,
+  h: number,
+): { x: number; y: number } {
+  switch (anchor) {
+    case 'center':
+      return { x: -w / 2, y: -h / 2 };
+    case 'top-right':
+      return { x: -w, y: 0 };
+    case 'bottom-left':
+      return { x: 0, y: -h };
+    case 'bottom-right':
+      return { x: -w, y: -h };
+    case 'top-left':
+    default:
+      return { x: 0, y: 0 };
+  }
+}
+
+// ============================================
+// Asset inlining
+// ============================================
+
+async function loadAssetAsDataUrl(container: ContentContainer, src: string): Promise<string> {
+  // Already a data: or absolute URL — pass through.
+  if (/^(data:|https?:|blob:)/.test(src)) return src;
+  const data = await container.readFile(src);
+  if (!data) throw new Error(`exportImageEditDoc: missing asset "${src}"`);
+  const list = await container.listFiles(src);
+  const mime = list.find((e) => e.path === src)?.mimeType ?? guessMime(src);
+  return arrayBufferToDataUrl(data, mime);
+}
+
+function arrayBufferToDataUrl(data: ArrayBuffer, mime: string): string {
+  const bytes = new Uint8Array(data);
+  let binary = '';
+  // chunk to avoid call-stack limits with large images
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode.apply(null, Array.from(bytes.subarray(i, i + CHUNK)));
+  }
+  // btoa exists in browsers and modern Node (>= 16); fall back to Buffer for older runtimes.
+  const b64 = typeof btoa === 'function' ? btoa(binary) : Buffer.from(bytes).toString('base64');
+  return `data:${mime};base64,${b64}`;
+}
+
+function guessMime(path: string): string {
+  const dot = path.lastIndexOf('.');
+  const ext = dot >= 0 ? path.slice(dot).toLowerCase() : '';
+  switch (ext) {
+    case '.png':
+      return 'image/png';
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.webp':
+      return 'image/webp';
+    case '.gif':
+      return 'image/gif';
+    case '.svg':
+      return 'image/svg+xml';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+// ============================================
+// SVG → Image → Canvas → Blob
+// ============================================
+
+async function loadSvgImage(svg: string): Promise<HTMLImageElement> {
+  const blob = new Blob([svg], { type: 'image/svg+xml;charset=utf-8' });
+  const url = URL.createObjectURL(blob);
+  try {
+    return await new Promise<HTMLImageElement>((resolve, reject) => {
+      const img = new Image();
+      img.onload = () => resolve(img);
+      img.onerror = () => reject(new Error('exportImageEditDoc: SVG image failed to load'));
+      img.src = url;
+    });
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+type RasterCanvas = HTMLCanvasElement | OffscreenCanvas;
+
+function createRasterCanvas(width: number, height: number): RasterCanvas {
+  if (typeof OffscreenCanvas !== 'undefined') {
+    return new OffscreenCanvas(width, height);
+  }
+  const c = document.createElement('canvas');
+  c.width = width;
+  c.height = height;
+  return c;
+}
+
+async function canvasToBlob(canvas: RasterCanvas, mime: string, quality: number): Promise<Blob> {
+  if ('convertToBlob' in canvas) {
+    return canvas.convertToBlob({ type: mime, quality });
+  }
+  return new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => {
+        if (blob) resolve(blob);
+        else reject(new Error('exportImageEditDoc: canvas.toBlob returned null'));
+      },
+      mime,
+      quality,
+    );
+  });
+}
+
+// ============================================
+// XML escaping
+// ============================================
+
+function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function escapeText(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}

package/src/imageEdit/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Image-editor primitives: schema re-exports, state helpers, persistence,
+ * version history, and SVG → raster export.
+ *
+ * See `@bendyline/squisq/imageEdit` for the public subpath entry.
+ */
+
+// Schema (re-exported from schemas for ergonomic single-import)
+export type {
+  ImageEditDoc,
+  ImageEditLayer,
+  ImageEditLayerKind,
+  ImageEditCanvas,
+  ImageEditMeta,
+  EditorLayerMeta,
+} from '../schemas/ImageEditDoc.js';
+
+// State helpers
+export {
+  IMAGE_EDIT_STATE_FILENAME,
+  IMAGE_EDIT_ASSETS_PREFIX,
+  createEmptyImageEditDoc,
+  addLayer,
+  removeLayer,
+  reorderLayer,
+  updateLayer,
+  setCanvas,
+  touch,
+} from './state.js';
+
+// Persistence
+export { readImageEditDoc, writeImageEditDoc } from './persistence.js';
+
+// Version paths
+export {
+  IMAGE_EDIT_VERSIONS_PREFIX,
+  IMAGE_EDIT_DEFAULT_BASENAME,
+  buildImageEditVersionPath,
+  parseImageEditVersionPath,
+} from './versionPaths.js';
+
+// Version operations
+export {
+  saveImageEditVersion,
+  listImageEditVersions,
+  readImageEditVersion,
+  readImageEditVersionText,
+  revertToImageEditVersion,
+  pruneImageEditVersions,
+  coalesceImageEditVersions,
+  type SaveImageEditVersionOptions,
+  type SaveImageEditVersionResult,
+  type RevertImageEditOptions,
+} from './versions.js';
+
+// Manager
+export {
+  ImageEditVersionManager,
+  type ImageEditVersionManagerOptions,
+} from './ImageEditVersionManager.js';
+
+// Note: shared version types (`Version`, `PrunePolicy`, `CoalesceOptions`)
+// are re-exported from `@bendyline/squisq/versions` and the package root.
+// Import them from there to avoid duplicating the export surface.
+
+// Export
+export {
+  exportImageEditDoc,
+  type ImageEditExportFormat,
+  type ImageEditExportOptions,
+} from './export.js';

package/src/imageEdit/persistence.ts

@@ -0,0 +1,62 @@
+/**
+ * Load and save {@link ImageEditDoc} JSON to a sidecar
+ * {@link ContentContainer} (typically a {@link ScopedContentContainer}
+ * rooted at `<basename>_files/`).
+ */
+
+import type { ContentContainer } from '../storage/ContentContainer.js';
+import type { ImageEditDoc } from '../schemas/ImageEditDoc.js';
+import { IMAGE_EDIT_STATE_FILENAME } from './state.js';
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+/**
+ * Read `state.json` from the sidecar and parse it. Returns `null` when
+ * the file does not exist; throws on parse / shape errors.
+ */
+export async function readImageEditDoc(
+  container: ContentContainer,
+  filename: string = IMAGE_EDIT_STATE_FILENAME,
+): Promise<ImageEditDoc | null> {
+  const data = await container.readFile(filename);
+  if (!data) return null;
+  const text = decoder.decode(data);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`readImageEditDoc: ${filename} is not valid JSON: ${msg}`);
+  }
+  assertImageEditDoc(parsed, filename);
+  return parsed;
+}
+
+/** Serialize `doc` to JSON and write it to the sidecar. */
+export async function writeImageEditDoc(
+  container: ContentContainer,
+  doc: ImageEditDoc,
+  filename: string = IMAGE_EDIT_STATE_FILENAME,
+): Promise<void> {
+  const text = JSON.stringify(doc, null, 2);
+  await container.writeFile(filename, encoder.encode(text), 'application/json');
+}
+
+function assertImageEditDoc(value: unknown, filename: string): asserts value is ImageEditDoc {
+  if (!value || typeof value !== 'object') {
+    throw new Error(`readImageEditDoc: ${filename} root must be an object`);
+  }
+  const v = value as Partial<ImageEditDoc>;
+  if (v.version !== 1) {
+    throw new Error(
+      `readImageEditDoc: ${filename} has unsupported schema version ${String(v.version)} (expected 1)`,
+    );
+  }
+  if (!v.canvas || typeof v.canvas.width !== 'number' || typeof v.canvas.height !== 'number') {
+    throw new Error(`readImageEditDoc: ${filename} canvas.width/height must be numbers`);
+  }
+  if (!Array.isArray(v.layers)) {
+    throw new Error(`readImageEditDoc: ${filename} layers must be an array`);
+  }
+}