@bendyline/squisq 1.5.1 → 2.0.0

package/src/doc/treeview/render.ts

@@ -0,0 +1,41 @@
+/**
+ * ASCII tree renderer: nested nodes → clean tree art.
+ *
+ * A deterministic depth-first walk emitting rail/branch prefixes. The
+ * fixpoint is structural: `parseTree(renderTree(t))` preserves the node
+ * hierarchy + labels + comments, and `renderTree(parseTree(renderTree(t)))`
+ * is byte-identical (idempotent after one normalization cycle). Unlike the
+ * diagram renderer there is no spatial layout, so jitter is impossible.
+ */
+
+import { ASCII_TREE_VOCAB, UNICODE_TREE_VOCAB } from './chars.js';
+import type { Tree, TreeNode } from './types.js';
+
+export interface RenderTreeOptions {
+  /** Character vocabulary; defaults to the tree's own detected style. */
+  style?: 'unicode' | 'ascii';
+}
+
+export function renderTree(tree: Tree, options: RenderTreeOptions = {}): string {
+  const vocab = (options.style ?? tree.style) === 'ascii' ? ASCII_TREE_VOCAB : UNICODE_TREE_VOCAB;
+  const lines: string[] = [];
+
+  const label = (node: TreeNode): string =>
+    node.comment ? `${node.label}  # ${node.comment}` : node.label;
+
+  const walk = (nodes: readonly TreeNode[], prefix: string): void => {
+    nodes.forEach((node, i) => {
+      const last = i === nodes.length - 1;
+      lines.push(prefix + (last ? vocab.elbow : vocab.tee) + label(node));
+      walk(node.children, prefix + (last ? vocab.gap : vocab.rail));
+    });
+  };
+
+  // Roots sit at column 0 with no connector; their children get branches.
+  for (const root of tree.roots) {
+    lines.push(label(root));
+    walk(root.children, '');
+  }
+
+  return lines.join('\n');
+}

package/src/doc/treeview/types.ts

@@ -0,0 +1,43 @@
+/**
+ * Public types for the ASCII treeview codec.
+ *
+ * A tree is a hierarchy of labelled nodes (file trees, dependency trees,
+ * category outlines). Unlike the diagram codec's spatial grid model, the
+ * tree model is a plain nested structure — rendering is a deterministic
+ * tree-walk, so the parse↔render fixpoint is structural and trivially
+ * byte-stable.
+ */
+
+export interface TreeNode {
+  /**
+   * Stable id: slug of the label, deduplicated with `-2`/`-3` suffixes in
+   * document (depth-first) order. Identical art re-parses to identical ids
+   * (the outline widget's selection resolves by id).
+   */
+  id: string;
+  /** Display label, verbatim (may keep a trailing `/`). */
+  label: string;
+  /** Child nodes (empty for leaves). */
+  children: TreeNode[];
+  /** True when this node reads as a container (trailing `/` or has children). */
+  isDir?: boolean;
+  /** Trailing `# …` / `<-- …` comment, preserved across round-trips. */
+  comment?: string;
+}
+
+export interface Tree {
+  /** Top-level nodes (a forest — usually one root for a file tree). */
+  roots: TreeNode[];
+  /** Character vocabulary detected in the source; render emits the same. */
+  style: 'unicode' | 'ascii';
+  /** Non-fatal parse notes (ragged dedents, dropped lines, …). */
+  warnings: string[];
+}
+
+export interface TreeDetection {
+  isTree: boolean;
+  /** Present when `isTree` — avoids a second parse in callers. */
+  tree?: Tree;
+  /** Machine-greppable accept/reject reasons. */
+  reasons: string[];
+}

package/src/doc/utils/applyRenderStyle.ts

@@ -50,16 +50,9 @@ function isFullBleedCoverMedia(layer: Layer): boolean {
   return fit === undefined || fit === 'cover';
 }
 
-/**
- * Whether the theme asks for ambient Ken Burns on otherwise-static imagery.
- * `defaultImageAnimation: 'slowZoom'` is treated as an alias for the boolean
- * (that's what themes authoring it were reaching for).
- */
+/** Whether the theme asks for ambient Ken Burns on otherwise-static imagery. */
 export function themeWantsAmbientMotion(theme: Theme): boolean {
-  return (
-    theme.renderStyle.ambientMotion === true ||
-    theme.renderStyle.defaultImageAnimation === 'slowZoom'
-  );
+  return theme.renderStyle.ambientMotion === true;
 }
 
 /**

package/src/doc/utils/diagramText.ts

@@ -0,0 +1,78 @@
+/** Text fitting shared by the live diagram canvas and template renderer. */
+
+export const DIAGRAM_LABEL_LINE_HEIGHT = 1.25;
+export const DIAGRAM_LABEL_HORIZONTAL_PADDING = 24;
+export const DIAGRAM_LABEL_VERTICAL_PADDING = 16;
+export const DIAGRAM_LABEL_MIN_FONT_SIZE = 10;
+
+export interface DiagramLabelFit {
+  fontSize: number;
+  lineCount: number;
+  /** Upward shift that centers the full line group around the node midpoint. */
+  firstLineOffset: number;
+  textWidth: number;
+}
+
+/**
+ * Fit a plain diagram label inside a node card using the same character-width
+ * estimate and word wrapping as React's `TextLayer`.
+ */
+export function fitDiagramLabel(
+  text: string,
+  boxWidth: number,
+  boxHeight: number,
+  preferredFontSize: number,
+): DiagramLabelFit {
+  const textWidth = Math.max(1, boxWidth - DIAGRAM_LABEL_HORIZONTAL_PADDING);
+  const textHeight = Math.max(1, boxHeight - DIAGRAM_LABEL_VERTICAL_PADDING);
+  const preferred = Math.max(DIAGRAM_LABEL_MIN_FONT_SIZE, Math.floor(preferredFontSize));
+
+  let fontSize = preferred;
+  let lineCount = countWrappedLines(text, fontSize, textWidth);
+  while (
+    fontSize > DIAGRAM_LABEL_MIN_FONT_SIZE &&
+    lineCount * fontSize * DIAGRAM_LABEL_LINE_HEIGHT > textHeight
+  ) {
+    fontSize--;
+    lineCount = countWrappedLines(text, fontSize, textWidth);
+  }
+
+  return {
+    fontSize,
+    lineCount,
+    firstLineOffset:
+      lineCount === 1 ? 0 : -((lineCount - 1) * fontSize * DIAGRAM_LABEL_LINE_HEIGHT) / 2,
+    textWidth,
+  };
+}
+
+function countWrappedLines(text: string, fontSize: number, maxWidth: number): number {
+  return text
+    .split('\n')
+    .reduce((count, line) => count + wrappedLineCount(line, fontSize, maxWidth), 0);
+}
+
+function wrappedLineCount(text: string, fontSize: number, maxWidth: number): number {
+  if (!text.trim()) return 1;
+  const charsPerLine = Math.floor(maxWidth / (fontSize * 0.5));
+  if (charsPerLine <= 0) return 1;
+
+  let lines = 0;
+  let currentLength = 0;
+  for (const word of text.split(/\s+/)) {
+    const testLength = currentLength > 0 ? currentLength + 1 + word.length : word.length;
+    if (testLength <= charsPerLine) {
+      currentLength = testLength;
+      continue;
+    }
+    if (currentLength > 0) lines++;
+    if (word.length > charsPerLine) {
+      lines += Math.floor((word.length - 1) / charsPerLine);
+      currentLength = word.length % charsPerLine || charsPerLine;
+    } else {
+      currentLength = word.length;
+    }
+  }
+  if (currentLength > 0) lines++;
+  return Math.max(1, lines);
+}

package/src/doc/utils/shapeGeometry.ts

@@ -9,9 +9,11 @@
  *  - `markerPath(style, dir)` → the `<marker>` path for a line end-style, in the
  *    standard 0–10 marker viewBox (shared by the SSR `PathLayer` renderer and the
  *    editor's edge renderer).
- *  - `connectorPath(routing, start, end)` + `clipEndpoints(a, b)` → the line/edge
+ *  - `connectorPath(routing, start, end)` + `snapEndpoints(a, b)` → the line/edge
  *    geometry between two shapes (straight / orthogonal / curved), lifted from the
- *    diagram template so drawings and diagrams draw identical connectors.
+ *    diagram template so drawings and diagrams draw identical connectors. The older
+ *    `clipEndpoints(a, b)` helper remains for free-angle clipping, but rendered
+ *    connectors use snapped ports so authored lines land on stable attachment points.
  */
 
 import type { MarkerStyle } from '../../schemas/Doc.js';
@@ -411,6 +413,27 @@ export interface ClipBox {
   ry: number;
 }
 
+export type ConnectorPort =
+  | 'top'
+  | 'right'
+  | 'bottom'
+  | 'left'
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-right'
+  | 'bottom-left';
+
+export interface ConnectorSnapPoint {
+  port: ConnectorPort;
+  x: number;
+  y: number;
+}
+
+export interface ConnectorAnchor {
+  side: 'top' | 'right' | 'bottom' | 'left';
+  offset: number;
+}
+
 /** Intersection of the center-to-center line with `from`'s bounding box. */
 export function clipPoint(from: ClipBox, to: ClipBox): { x: number; y: number } {
   const dx = to.cx - from.cx;
@@ -430,23 +453,150 @@ export function clipEndpoints(
   return { start: clipPoint(a, b), end: clipPoint(b, a) };
 }
 
+/** The stable connector ports exposed around a shape/card box. */
+export function snapPoints(box: ClipBox): ConnectorSnapPoint[] {
+  const left = box.cx - box.rx;
+  const right = box.cx + box.rx;
+  const top = box.cy - box.ry;
+  const bottom = box.cy + box.ry;
+  return [
+    { port: 'top', x: box.cx, y: top },
+    { port: 'right', x: right, y: box.cy },
+    { port: 'bottom', x: box.cx, y: bottom },
+    { port: 'left', x: left, y: box.cy },
+    { port: 'top-left', x: left, y: top },
+    { port: 'top-right', x: right, y: top },
+    { port: 'bottom-right', x: right, y: bottom },
+    { port: 'bottom-left', x: left, y: bottom },
+  ];
+}
+
+/** Resolve a normalized authored anchor to a concrete point on a box. */
+export function anchorPoint(box: ClipBox, anchor: ConnectorAnchor): ConnectorSnapPoint {
+  const offset = Math.max(0, Math.min(1, anchor.offset));
+  const left = box.cx - box.rx;
+  const right = box.cx + box.rx;
+  const top = box.cy - box.ry;
+  const bottom = box.cy + box.ry;
+  switch (anchor.side) {
+    case 'top':
+      return { port: 'top', x: left + (right - left) * offset, y: top };
+    case 'right':
+      return { port: 'right', x: right, y: top + (bottom - top) * offset };
+    case 'bottom':
+      return { port: 'bottom', x: left + (right - left) * offset, y: bottom };
+    case 'left':
+      return { port: 'left', x: left, y: top + (bottom - top) * offset };
+  }
+}
+
+/** Nearest stable connector port on `box` to an arbitrary point. */
+export function nearestSnapPoint(
+  box: ClipBox,
+  point: { x: number; y: number },
+): ConnectorSnapPoint {
+  let best = snapPoints(box)[0];
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const candidate of snapPoints(box)) {
+    const score = distanceSq(candidate, point) + portTieBreak(candidate.port);
+    if (score < bestScore) {
+      best = candidate;
+      bestScore = score;
+    }
+  }
+  return best;
+}
+
+/**
+ * Pick the pair of connector ports, one on each box, with the shortest
+ * distance between them. This gives stable attachments to side/corner handles
+ * instead of arbitrary center-ray intersections.
+ */
+export function snapEndpoints(
+  a: ClipBox,
+  b: ClipBox,
+): { start: ConnectorSnapPoint; end: ConnectorSnapPoint } {
+  let bestStart = snapPoints(a)[0];
+  let bestEnd = snapPoints(b)[0];
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const start of snapPoints(a)) {
+    for (const end of snapPoints(b)) {
+      const score = distanceSq(start, end) + portTieBreak(start.port) + portTieBreak(end.port);
+      if (score < bestScore) {
+        bestStart = start;
+        bestEnd = end;
+        bestScore = score;
+      }
+    }
+  }
+  return { start: bestStart, end: bestEnd };
+}
+
+function distanceSq(a: { x: number; y: number }, b: { x: number; y: number }): number {
+  const dx = a.x - b.x;
+  const dy = a.y - b.y;
+  return dx * dx + dy * dy;
+}
+
+function portTieBreak(port: ConnectorPort): number {
+  return port.includes('-') ? 0.02 : 0;
+}
+
 /** Build the SVG `d` for a connector between two clipped endpoints. */
 export function connectorPath(
   routing: ConnectorRouting,
-  start: { x: number; y: number },
-  end: { x: number; y: number },
+  start: { x: number; y: number; port?: ConnectorPort },
+  end: { x: number; y: number; port?: ConnectorPort },
 ): string {
   if (routing === 'straight') {
     return `M ${r(start.x)} ${r(start.y)} L ${r(end.x)} ${r(end.y)}`;
   }
   if (routing === 'orthogonal') {
+    const startAxis = portAxis(start.port);
+    const endAxis = portAxis(end.port);
+    if (startAxis === 'vertical' && endAxis === 'vertical') {
+      const midY = (start.y + end.y) / 2;
+      return `M ${r(start.x)} ${r(start.y)} L ${r(start.x)} ${r(midY)} L ${r(end.x)} ${r(midY)} L ${r(end.x)} ${r(end.y)}`;
+    }
+    if (startAxis === 'vertical' && endAxis === 'horizontal') {
+      return `M ${r(start.x)} ${r(start.y)} L ${r(start.x)} ${r(end.y)} L ${r(end.x)} ${r(end.y)}`;
+    }
+    if (startAxis === 'horizontal' && endAxis === 'vertical') {
+      return `M ${r(start.x)} ${r(start.y)} L ${r(end.x)} ${r(start.y)} L ${r(end.x)} ${r(end.y)}`;
+    }
     const midX = (start.x + end.x) / 2;
     return `M ${r(start.x)} ${r(start.y)} L ${r(midX)} ${r(start.y)} L ${r(midX)} ${r(end.y)} L ${r(end.x)} ${r(end.y)}`;
   }
   // curved
-  const dx = Math.abs(end.x - start.x);
-  const cp = Math.max(40, dx / 2);
-  return `M ${r(start.x)} ${r(start.y)} C ${r(start.x + cp)} ${r(start.y)}, ${r(end.x - cp)} ${r(end.y)}, ${r(end.x)} ${r(end.y)}`;
+  const distance = Math.hypot(end.x - start.x, end.y - start.y);
+  const cp = Math.max(40, distance / 2);
+  const startVector = portVector(start.port, { x: 1, y: 0 });
+  const endVector = portVector(end.port, { x: -1, y: 0 });
+  return `M ${r(start.x)} ${r(start.y)} C ${r(start.x + startVector.x * cp)} ${r(start.y + startVector.y * cp)}, ${r(end.x + endVector.x * cp)} ${r(end.y + endVector.y * cp)}, ${r(end.x)} ${r(end.y)}`;
+}
+
+function portAxis(port: ConnectorPort | undefined): 'horizontal' | 'vertical' | null {
+  if (port === 'top' || port === 'bottom') return 'vertical';
+  if (port === 'left' || port === 'right') return 'horizontal';
+  return null;
+}
+
+function portVector(
+  port: ConnectorPort | undefined,
+  fallback: { x: number; y: number },
+): { x: number; y: number } {
+  switch (port) {
+    case 'top':
+      return { x: 0, y: -1 };
+    case 'right':
+      return { x: 1, y: 0 };
+    case 'bottom':
+      return { x: 0, y: 1 };
+    case 'left':
+      return { x: -1, y: 0 };
+    default:
+      return fallback;
+  }
 }
 
 /** Map a `lineStyle` (solid|dashed|dotted) to an SVG `stroke-dasharray`. */

package/src/doc/validate.ts

@@ -36,12 +36,12 @@ import { deriveTemplateInputs } from './templateInputs.js';
 import { lintTemplateParams } from './templates/inputDescriptors.js';
 import {
   templateRegistry,
-  TEMPLATE_ALIASES,
   resolveTemplateName,
   isShapeName,
   normalizeShapeKind,
   SHAPE_NAMES,
 } from './templates/index.js';
+import { TEMPLATE_ALIASES } from './templates/templateNames.js';
 import { nearestName } from './utils/nearest.js';
 
 // ============================================

package/src/generate/templateMapper.ts

@@ -38,8 +38,13 @@ export interface MapOptions {
   audioSegment: number;
   colorScheme?: ColorScheme;
   accentImage?: AccentImage;
+  /** Doc-timeline SECONDS when the extracted content is spoken. */
   sourceStartTime?: number;
   sourceDuration?: number;
+  /** Provenance: the source block the element was extracted from. */
+  sourceBlockId?: string;
+  /** Provenance: char offset of the extraction in the source plain text. */
+  sourceCharOffset?: number;
 }
 
 /**
@@ -52,6 +57,8 @@ export function mapElementToBlock(element: ExtractedElement, options: MapOptions
     audioSegment: options.audioSegment,
     sourceStartTime: options.sourceStartTime,
     sourceDuration: options.sourceDuration,
+    sourceBlockId: options.sourceBlockId,
+    sourceCharOffset: options.sourceCharOffset,
   };
 
   switch (element.data.type) {

package/src/imageEdit/export.ts

@@ -203,9 +203,10 @@ function renderPathToSvg(
   const fill = c.fill ?? 'none';
   const dash = c.dasharray ? ` stroke-dasharray="${escapeAttr(c.dasharray)}"` : '';
 
-  // Markers: explicit start/end win; otherwise derive from the legacy `arrow` flag.
-  const startStyle = effectiveExportMarker(c.startMarker, c.arrow, 'start');
-  const endStyle = effectiveExportMarker(c.endMarker, c.arrow, 'end');
+  // Keep old serialized documents readable without retaining `arrow` in the public type.
+  const legacyArrow = (c as typeof c & { arrow?: 'none' | 'end' | 'start' | 'both' }).arrow;
+  const startStyle = effectiveExportMarker(c.startMarker, legacyArrow, 'start');
+  const endStyle = effectiveExportMarker(c.endMarker, legacyArrow, 'end');
   const start = markerPath(startStyle, 'start');
   const end = markerPath(endStyle, 'end');
   const startId = `marker-start-${layer.id}`;
@@ -228,11 +229,11 @@ function renderPathToSvg(
 
 function effectiveExportMarker(
   explicit: MarkerStyle | undefined,
-  arrow: (ImageEditLayer & { type: 'path' })['content']['arrow'],
+  legacyArrow: 'none' | 'end' | 'start' | 'both' | undefined,
   end: 'start' | 'end',
 ): MarkerStyle {
   if (explicit) return explicit;
-  return arrow === 'both' || arrow === end ? 'arrow' : 'none';
+  return legacyArrow === 'both' || legacyArrow === end ? 'arrow' : 'none';
 }
 
 function markerDefSvg(

package/src/imageEdit/versionPaths.ts

@@ -10,7 +10,11 @@
  * `.md` so the two histories live side-by-side without colliding.
  */
 
-import { formatVersionTimestamp, parseVersionTimestamp } from '../versions/timestamp.js';
+import {
+  buildSnapshotPath,
+  parseSnapshotPath,
+  type SnapshotPathStrategy,
+} from '../versions/snapshotStore.js';
 
 /** Subfolder (inside the sidecar) that holds image-editor snapshots. */
 export const IMAGE_EDIT_VERSIONS_PREFIX = '.versions/';
@@ -18,11 +22,15 @@ export const IMAGE_EDIT_VERSIONS_PREFIX = '.versions/';
 /** Default basename when none is supplied. Matches `IMAGE_EDIT_STATE_FILENAME` stem. */
 export const IMAGE_EDIT_DEFAULT_BASENAME = 'state';
 
+/** Internal strategy shared with the generic snapshot store. */
+export const IMAGE_EDIT_VERSION_PATHS: SnapshotPathStrategy = Object.freeze({
+  prefix: IMAGE_EDIT_VERSIONS_PREFIX,
+  extension: 'json',
+});
+
 /** Build a snapshot path. Optionally append a collision suffix. */
 export function buildImageEditVersionPath(basename: string, date: Date, collision = 0): string {
-  const stamp = formatVersionTimestamp(date);
-  const suffix = collision > 0 ? `-${collision + 1}` : '';
-  return `${IMAGE_EDIT_VERSIONS_PREFIX}${basename}.${stamp}${suffix}.json`;
+  return buildSnapshotPath(IMAGE_EDIT_VERSION_PATHS, basename, date, collision);
 }
 
 /**
@@ -32,26 +40,5 @@ export function buildImageEditVersionPath(basename: string, date: Date, collisio
 export function parseImageEditVersionPath(
   path: string,
 ): { basename: string; timestamp: Date; collision: number } | null {
-  if (!path.startsWith(IMAGE_EDIT_VERSIONS_PREFIX)) return null;
-  const rest = path.slice(IMAGE_EDIT_VERSIONS_PREFIX.length);
-  if (!rest.endsWith('.json')) return null;
-  const stem = rest.slice(0, -'.json'.length);
-  const lastDot = stem.lastIndexOf('.');
-  if (lastDot <= 0) return null;
-  const basename = stem.slice(0, lastDot);
-  const tail = stem.slice(lastDot + 1);
-  const dash = tail.indexOf('-');
-  let stamp: string;
-  let collision = 0;
-  if (dash >= 0) {
-    stamp = tail.slice(0, dash);
-    const n = Number(tail.slice(dash + 1));
-    if (!Number.isInteger(n) || n < 2) return null;
-    collision = n - 1;
-  } else {
-    stamp = tail;
-  }
-  const timestamp = parseVersionTimestamp(stamp);
-  if (!timestamp) return null;
-  return { basename, timestamp, collision };
+  return parseSnapshotPath(IMAGE_EDIT_VERSION_PATHS, path);
 }

package/src/imageEdit/versions.ts

@@ -5,23 +5,24 @@
  * Mirrors `core/src/versions/operations.ts` but operates on
  * {@link ImageEditDoc} JSON state at `.versions/<basename>.<timestamp>.json`
  * instead of the markdown document. Reuses {@link PrunePolicy} so hosts
- * can share their pruning configuration between the two histories.
+ * can share their pruning configuration between the two histories. The
+ * sidecar root gets a `.gitignore` rule for `.versions/` when snapshots
+ * are retained.
  */
 
 import type { ContentContainer } from '../storage/ContentContainer.js';
 import type { ImageEditDoc } from '../schemas/ImageEditDoc.js';
 import type { CoalesceOptions, PrunePolicy, Version } from '../versions/types.js';
+import {
+  coalesceSnapshots,
+  listSnapshots,
+  pruneSnapshots,
+  readTextSnapshot,
+  saveTextSnapshot,
+} from '../versions/snapshotStore.js';
 import { readImageEditDoc, writeImageEditDoc } from './persistence.js';
 import { IMAGE_EDIT_STATE_FILENAME } from './state.js';
-import {
-  IMAGE_EDIT_VERSIONS_PREFIX,
-  IMAGE_EDIT_DEFAULT_BASENAME,
-  buildImageEditVersionPath,
-  parseImageEditVersionPath,
-} from './versionPaths.js';
-
-const decoder = new TextDecoder();
-const encoder = new TextEncoder();
+import { IMAGE_EDIT_DEFAULT_BASENAME, IMAGE_EDIT_VERSION_PATHS } from './versionPaths.js';
 
 /** Options for {@link saveImageEditVersion}. */
 export interface SaveImageEditVersionOptions {
@@ -60,26 +61,7 @@ export async function listImageEditVersions(
   container: ContentContainer,
   basename?: string,
 ): Promise<Version[]> {
-  const entries = await container.listFiles(IMAGE_EDIT_VERSIONS_PREFIX);
-  const versions: Version[] = [];
-  for (const entry of entries) {
-    const parsed = parseImageEditVersionPath(entry.path);
-    if (!parsed) continue;
-    if (basename !== undefined && parsed.basename !== basename) continue;
-    versions.push({
-      path: entry.path,
-      basename: parsed.basename,
-      timestamp: parsed.timestamp,
-      size: entry.size,
-      collision: parsed.collision,
-    });
-  }
-  versions.sort((a, b) => {
-    const dt = b.timestamp.getTime() - a.timestamp.getTime();
-    if (dt !== 0) return dt;
-    return b.collision - a.collision;
-  });
-  return versions;
+  return listSnapshots(container, IMAGE_EDIT_VERSION_PATHS, basename);
 }
 
 /** Read a snapshot's JSON text. Returns `null` if the snapshot is missing. */
@@ -87,10 +69,7 @@ export async function readImageEditVersionText(
   container: ContentContainer,
   version: Version | string,
 ): Promise<string | null> {
-  const path = typeof version === 'string' ? version : version.path;
-  const data = await container.readFile(path);
-  if (!data) return null;
-  return decoder.decode(data);
+  return readTextSnapshot(container, version);
 }
 
 /** Read and parse a snapshot. Returns `null` if missing. */
@@ -124,34 +103,13 @@ export async function saveImageEditVersion(
   const basename = options.basename ?? IMAGE_EDIT_DEFAULT_BASENAME;
   const serialized = JSON.stringify(doc, null, 2);
 
-  const versions = await listImageEditVersions(container, basename);
-  if (!options.force && versions.length > 0) {
-    const latest = versions[0]!;
-    const existing = await readImageEditVersionText(container, latest);
-    if (existing === serialized) {
-      return { saved: false, version: null, reason: 'unchanged' };
-    }
-  }
-
-  const now = options.now ?? new Date();
-  let collision = 0;
-  let path = buildImageEditVersionPath(basename, now, collision);
-  while (await container.exists(path)) {
-    collision += 1;
-    path = buildImageEditVersionPath(basename, now, collision);
-  }
-
-  const data = encoder.encode(serialized);
-  await container.writeFile(path, data, 'application/json');
-
-  const version: Version = {
-    path,
+  return saveTextSnapshot(container, IMAGE_EDIT_VERSION_PATHS, {
+    content: serialized,
     basename,
-    timestamp: now,
-    size: data.byteLength,
-    collision,
-  };
-  return { saved: true, version, reason: 'saved' };
+    mimeType: 'application/json',
+    now: options.now,
+    force: options.force,
+  });
 }
 
 /** Revert `state.json` to a prior snapshot. Snapshots the current state first by default. */
@@ -181,27 +139,7 @@ export async function pruneImageEditVersions(
   policy: PrunePolicy,
   basename?: string,
 ): Promise<Version[]> {
-  const versions = await listImageEditVersions(container, basename);
-  const toDelete: Version[] = [];
-
-  if (policy.type === 'keep-last-n') {
-    const n = Math.max(0, Math.floor(policy.n));
-    toDelete.push(...versions.slice(n));
-  } else if (policy.type === 'older-than') {
-    const cutoff = policy.date.getTime();
-    for (const v of versions) {
-      if (v.timestamp.getTime() < cutoff) toDelete.push(v);
-    }
-  } else {
-    for (const v of versions) {
-      if (!policy.keep(v, versions)) toDelete.push(v);
-    }
-  }
-
-  for (const v of toDelete) {
-    await container.removeFile(v.path);
-  }
-  return toDelete;
+  return pruneSnapshots(container, IMAGE_EDIT_VERSION_PATHS, policy, basename);
 }
 
 /** Collapse adjacent snapshots within `windowMs`, keeping the newer of each pair. */
@@ -210,22 +148,5 @@ export async function coalesceImageEditVersions(
   options: CoalesceOptions = {},
   basename?: string,
 ): Promise<Version[]> {
-  const windowMs = options.windowMs ?? 60_000;
-  const versions = await listImageEditVersions(container, basename);
-  const toDelete: Version[] = [];
-  if (versions.length > 0) {
-    let anchor = versions[0]!;
-    for (let i = 1; i < versions.length; i++) {
-      const candidate = versions[i]!;
-      if (anchor.timestamp.getTime() - candidate.timestamp.getTime() <= windowMs) {
-        toDelete.push(candidate);
-      } else {
-        anchor = candidate;
-      }
-    }
-  }
-  for (const v of toDelete) {
-    await container.removeFile(v.path);
-  }
-  return toDelete;
+  return coalesceSnapshots(container, IMAGE_EDIT_VERSION_PATHS, options, basename);
 }

package/src/index.ts

@@ -12,3 +12,4 @@ export * from './jsonForm/index.js';
 export * from './imageEdit/index.js';
 export * from './icons/index.js';
 export * from './recommend/index.js';
+export * from './narration/index.js';