@bendyline/squisq 2.1.0 → 2.3.0

package/src/imageEdit/export.ts

@@ -1,410 +0,0 @@
-/**
- * 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 { MarkerStyle, Position } from '../schemas/Doc.js';
-import { markerPath, shapePath } from '../doc/utils/shapeGeometry.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
-// ============================================
-
-/**
- * Build the standalone SVG string that mirrors the canvas + layers. Exposed
- * for tests (the raster step needs a browser); shape/text/path layers don't
- * touch `container`, only image layers do (to inline asset bytes).
- */
-export 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}/>`;
-  }
-
-  if (layer.type === 'path') {
-    return renderPathToSvg(layer, x, y, w, h);
-  }
-
-  // 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>`
-  );
-}
-
-/**
- * Serialize a `path` layer to SVG. Mirrors the runtime
- * `react/src/layers/PathLayer.tsx`: when `shapeKind` is set, `d` is
- * re-derived from the position box via `shapePath` (so named shapes scale);
- * otherwise the stored absolute `d` is used. Start/end markers are emitted
- * as `<marker>` defs scoped to the layer id, matching `markerPath` geometry.
- */
-function renderPathToSvg(
-  layer: ImageEditLayer & { type: 'path' },
-  x: number,
-  y: number,
-  w: number,
-  h: number,
-): string {
-  const c = layer.content;
-  const d = c.shapeKind ? (shapePath(c.shapeKind, x, y, w, h) ?? c.d) : c.d;
-  const stroke = c.stroke ?? '#1e293b';
-  const strokeWidth = c.strokeWidth ?? 2;
-  const fill = c.fill ?? 'none';
-  const dash = c.dasharray ? ` stroke-dasharray="${escapeAttr(c.dasharray)}"` : '';
-
-  // 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}`;
-  const endId = `marker-end-${layer.id}`;
-  const defs =
-    start || end
-      ? `<defs>${start ? markerDefSvg(startId, 'start', start, stroke) : ''}${
-          end ? markerDefSvg(endId, 'end', end, stroke) : ''
-        }</defs>`
-      : '';
-  const markerStart = start ? ` marker-start="url(#${startId})"` : '';
-  const markerEnd = end ? ` marker-end="url(#${endId})"` : '';
-
-  return (
-    defs +
-    `<path d="${escapeAttr(d)}" fill="${escapeAttr(fill)}"` +
-    ` stroke="${escapeAttr(stroke)}" stroke-width="${strokeWidth}"${dash}${markerStart}${markerEnd}/>`
-  );
-}
-
-function effectiveExportMarker(
-  explicit: MarkerStyle | undefined,
-  legacyArrow: 'none' | 'end' | 'start' | 'both' | undefined,
-  end: 'start' | 'end',
-): MarkerStyle {
-  if (explicit) return explicit;
-  return legacyArrow === 'both' || legacyArrow === end ? 'arrow' : 'none';
-}
-
-function markerDefSvg(
-  id: string,
-  dir: 'start' | 'end',
-  marker: { d: string; filled: boolean },
-  stroke: string,
-): string {
-  const refX = dir === 'end' ? 9 : 1;
-  const paint = marker.filled
-    ? `fill="${escapeAttr(stroke)}"`
-    : `fill="none" stroke="${escapeAttr(stroke)}" stroke-width="1.5"`;
-  return (
-    `<marker id="${escapeAttr(id)}" viewBox="0 0 10 10" refX="${refX}" refY="5"` +
-    ` markerWidth="4" markerHeight="4" orient="auto-start-reverse" markerUnits="strokeWidth">` +
-    `<path d="${escapeAttr(marker.d)}" ${paint}/></marker>`
-  );
-}
-
-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

@@ -1,72 +0,0 @@
-/**
- * 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,
-  buildSvgString,
-  type ImageEditExportFormat,
-  type ImageEditExportOptions,
-} from './export.js';

package/src/imageEdit/persistence.ts

@@ -1,113 +0,0 @@
-/**
- * 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`);
-  }
-  v.layers.forEach((layer, i) => assertLayer(layer, i, filename));
-}
-
-const VALID_LAYER_TYPES = new Set(['image', 'text', 'shape', 'path']);
-
-function assertLayer(value: unknown, index: number, filename: string): void {
-  const ctx = `${filename} layers[${index}]`;
-  if (!value || typeof value !== 'object') {
-    throw new Error(`readImageEditDoc: ${ctx} must be an object`);
-  }
-  const layer = value as Record<string, unknown>;
-
-  if (typeof layer['id'] !== 'string') {
-    throw new Error(`readImageEditDoc: ${ctx} must have a string id`);
-  }
-  if (typeof layer['type'] !== 'string' || !VALID_LAYER_TYPES.has(layer['type'])) {
-    throw new Error(
-      `readImageEditDoc: ${ctx} type must be one of image|text|shape, got ${String(layer['type'])}`,
-    );
-  }
-
-  const pos = layer['position'];
-  if (
-    !pos ||
-    typeof pos !== 'object' ||
-    (typeof (pos as Record<string, unknown>)['x'] !== 'number' &&
-      typeof (pos as Record<string, unknown>)['x'] !== 'string') ||
-    (typeof (pos as Record<string, unknown>)['y'] !== 'number' &&
-      typeof (pos as Record<string, unknown>)['y'] !== 'string')
-  ) {
-    throw new Error(`readImageEditDoc: ${ctx} position must have numeric or string x and y`);
-  }
-
-  const content = layer['content'];
-  if (!content || typeof content !== 'object') {
-    throw new Error(`readImageEditDoc: ${ctx} content must be an object`);
-  }
-  const c = content as Record<string, unknown>;
-
-  if (layer['type'] === 'image' && typeof c['src'] !== 'string') {
-    throw new Error(`readImageEditDoc: ${ctx} (image) content.src must be a string`);
-  }
-  if (layer['type'] === 'text' && typeof c['text'] !== 'string') {
-    throw new Error(`readImageEditDoc: ${ctx} (text) content.text must be a string`);
-  }
-  if (layer['type'] === 'shape' && typeof c['shape'] !== 'string') {
-    throw new Error(`readImageEditDoc: ${ctx} (shape) content.shape must be a string`);
-  }
-  if (layer['type'] === 'path' && typeof c['d'] !== 'string') {
-    throw new Error(`readImageEditDoc: ${ctx} (path) content.d must be a string`);
-  }
-}