@bendyline/squisq 2.1.0 → 2.2.0

package/src/schemas/ImageEditDoc.ts

@@ -1,102 +0,0 @@
-/**
- * ImageEditDoc — JSON document describing a layered, editable image.
- *
- * This is the persistent state of the `<ImageEditor>` component. It lives
- * inside a `<imagebasename>_files/` sidecar folder (exposed as a
- * {@link ContentContainer}) at `state.json`, alongside referenced asset
- * bytes in `assets/` and version snapshots in `.versions/`.
- *
- * Layers compose the existing core {@link Layer} types (image / text /
- * shape / path) so renderers can share infrastructure with the doc system.
- * Editor-specific metadata (name, visibility, lock, opacity, blendMode)
- * lives in {@link EditorLayerMeta} and is merged onto each layer. The
- * {@link Layer.animation} field is permitted but ignored by the image
- * editor — animations are a slideshow concept.
- *
- * All asset paths in layers (e.g. `ImageLayer.content.src`) are
- * relative to the sidecar root, keeping the document portable.
- */
-
-import type { ImageLayer, PathLayer, ShapeLayer, TextLayer } from './Doc.js';
-
-// ============================================
-// Layer type
-// ============================================
-
-/**
- * Per-layer editor metadata. Merged into each layer so the persisted
- * shape is a single object. All fields optional; sensible defaults
- * apply when absent (visible: true, locked: false, opacity: 1).
- */
-export interface EditorLayerMeta {
-  /** Human-readable name shown in the layers panel. */
-  name?: string;
-  /** When false, the layer is hidden from rendering. Default true. */
-  visible?: boolean;
-  /** When true, the layer cannot be selected/edited. Default false. */
-  locked?: boolean;
-  /** 0..1 multiplier on the layer's alpha. Default 1. */
-  opacity?: number;
-  /**
-   * Canvas blend mode (matches the CSS / Canvas2D vocabulary).
-   * Default 'source-over' (normal compositing).
-   */
-  blendMode?: GlobalCompositeOperation;
-}
-
-/**
- * A layer in an {@link ImageEditDoc}.
- *
- * `path` layers carry the full drawing-shape vocabulary: when
- * `content.shapeKind` is set (e.g. `'diamond'`, `'star'`, `'arrow-right'`),
- * the renderer re-derives the SVG `d` from the layer's `position` box via
- * `shapePath`, so the shape moves/resizes like the native rect/circle/line.
- */
-export type ImageEditLayer = (ImageLayer | TextLayer | ShapeLayer | PathLayer) & EditorLayerMeta;
-
-/** The layer kinds the image editor supports. */
-export type ImageEditLayerKind = ImageEditLayer['type'];
-
-// ============================================
-// Document
-// ============================================
-
-/** Canvas dimensions and background. */
-export interface ImageEditCanvas {
-  /** Canvas width in pixels. */
-  width: number;
-  /** Canvas height in pixels. */
-  height: number;
-  /**
-   * Background fill (CSS color, or `'transparent'` for an alpha canvas).
-   * Default: `'transparent'`.
-   */
-  background?: string;
-}
-
-/** Optional document metadata. */
-export interface ImageEditMeta {
-  /** Path to the original source image (sidecar-relative). Set when the doc is seeded from an existing image. */
-  sourcePath?: string;
-  /** ISO timestamp set on first save. */
-  createdAt?: string;
-  /** ISO timestamp updated on every save. */
-  updatedAt?: string;
-}
-
-/**
- * The persisted image-editor document.
- *
- * Layers are composited back-to-front: `layers[0]` is the bottom of the stack
- * (typically the base raster), `layers[layers.length - 1]` is the top.
- */
-export interface ImageEditDoc {
-  /** Schema version. Bumped on breaking changes. */
-  version: 1;
-  /** Canvas configuration. */
-  canvas: ImageEditCanvas;
-  /** Layers, back-to-front. */
-  layers: ImageEditLayer[];
-  /** Optional metadata. */
-  meta?: ImageEditMeta;
-}

package/src/schemas/LayoutStrategy.ts

@@ -1,178 +0,0 @@
-/**
- * Layout Strategy
- *
- * Provides orientation-specific layout hints for slide templates.
- * Templates use these hints to position content appropriately for
- * different aspect ratios (landscape, portrait, square).
- *
- * Key adaptations by orientation:
- * - Portrait: Larger relative text, stacked layouts instead of side-by-side
- * - Square: Balanced layout with moderate adjustments
- * - Landscape: Default/reference layout
- */
-
-import type { ViewportOrientation, ViewportConfig } from './Viewport.js';
-import { calculateFontScale } from './Viewport.js';
-
-/**
- * Layout hints for template positioning based on orientation.
- */
-export interface LayoutHints {
-  /** Primary content Y position (percentage string, e.g., "35%") */
-  primaryY: string;
-  /** Secondary content Y position (percentage string) */
-  secondaryY: string;
-  /** Tertiary/detail Y position (percentage string) */
-  tertiaryY: string;
-  /** Title font size multiplier (relative to base) */
-  titleScale: number;
-  /** Body text font size multiplier (relative to base) */
-  bodyScale: number;
-  /** Two-column: left X position (percentage string) */
-  columnLeftX: string;
-  /** Two-column: right X position (percentage string) */
-  columnRightX: string;
-  /** Two-column in portrait: top Y position for stacked layout */
-  columnTopY: string;
-  /** Two-column in portrait: bottom Y position for stacked layout */
-  columnBottomY: string;
-  /** Whether two-column should stack vertically */
-  stackColumns: boolean;
-  /** Max text width (percentage string) for wrapping */
-  maxTextWidth: string;
-  /** Horizontal padding from edges (percentage string) */
-  horizontalPadding: string;
-  /** Caption position Y for imageWithCaption (percentage string) */
-  captionY: string;
-  /** Caption font size multiplier */
-  captionScale: number;
-}
-
-/**
- * Layout configurations by orientation.
- */
-const LAYOUT_CONFIGS: Record<ViewportOrientation, LayoutHints> = {
-  landscape: {
-    primaryY: '35%',
-    secondaryY: '55%',
-    tertiaryY: '75%',
-    titleScale: 1.0,
-    bodyScale: 1.0,
-    columnLeftX: '25%',
-    columnRightX: '75%',
-    columnTopY: '35%',
-    columnBottomY: '65%',
-    stackColumns: false,
-    maxTextWidth: '80%',
-    horizontalPadding: '10%',
-    captionY: '85%',
-    captionScale: 1.0,
-  },
-  portrait: {
-    // Content positioned higher for thumb-reach zone on mobile
-    primaryY: '25%',
-    secondaryY: '42%',
-    tertiaryY: '58%',
-    // Titles scale down for narrower width; body text scales up to fill vertical space
-    titleScale: 0.7,
-    bodyScale: 1.5,
-    // Stacked columns instead of side-by-side
-    columnLeftX: '50%',
-    columnRightX: '50%',
-    columnTopY: '30%',
-    columnBottomY: '55%',
-    stackColumns: true,
-    // Wider relative to viewport to use available space
-    maxTextWidth: '90%',
-    horizontalPadding: '5%',
-    captionY: '75%',
-    captionScale: 0.85,
-  },
-  square: {
-    primaryY: '30%',
-    secondaryY: '50%',
-    tertiaryY: '70%',
-    titleScale: 0.85,
-    bodyScale: 0.9,
-    columnLeftX: '25%',
-    columnRightX: '75%',
-    columnTopY: '35%',
-    columnBottomY: '65%',
-    stackColumns: false,
-    maxTextWidth: '85%',
-    horizontalPadding: '7.5%',
-    captionY: '82%',
-    captionScale: 0.9,
-  },
-};
-
-/**
- * Get layout hints for a given orientation.
- */
-export function getLayoutHints(orientation: ViewportOrientation): LayoutHints {
-  return LAYOUT_CONFIGS[orientation];
-}
-
-/**
- * Calculate a scaled font size based on viewport and layout hints.
- *
- * @param basePx - Base font size in pixels (designed for 1920x1080)
- * @param viewport - Target viewport configuration
- * @param orientation - Viewport orientation
- * @param isTitle - Whether this is title text (uses titleScale) or body (uses bodyScale)
- */
-export function scaledFontSize(
-  basePx: number,
-  viewport: ViewportConfig,
-  orientation: ViewportOrientation,
-  isTitle: boolean = false,
-): number {
-  const fontScale = calculateFontScale(viewport);
-  const layout = getLayoutHints(orientation);
-  const typeScale = isTitle ? layout.titleScale : layout.bodyScale;
-  return Math.round(basePx * fontScale * typeScale);
-}
-
-/**
- * Get position for two-column layout based on orientation.
- * Returns { left: {x, y}, right: {x, y} } positions.
- */
-export function getTwoColumnPositions(orientation: ViewportOrientation): {
-  left: { x: string; y: string };
-  right: { x: string; y: string };
-} {
-  const layout = getLayoutHints(orientation);
-
-  if (layout.stackColumns) {
-    // Portrait: stack vertically
-    return {
-      left: { x: '50%', y: layout.columnTopY },
-      right: { x: '50%', y: layout.columnBottomY },
-    };
-  }
-
-  // Landscape/square: side by side
-  return {
-    left: { x: layout.columnLeftX, y: '50%' },
-    right: { x: layout.columnRightX, y: '50%' },
-  };
-}
-
-/**
- * Get safe text bounds for a given orientation.
- * Returns margins to keep text away from edges.
- */
-export function getSafeTextBounds(orientation: ViewportOrientation): {
-  left: string;
-  right: string;
-  top: string;
-  bottom: string;
-} {
-  const layout = getLayoutHints(orientation);
-  return {
-    left: layout.horizontalPadding,
-    right: layout.horizontalPadding,
-    top: '10%',
-    bottom: '10%',
-  };
-}

package/src/schemas/Media.ts

@@ -1,179 +0,0 @@
-/**
- * Media-clip timing model.
- *
- * An additive layer on top of the simple sequential `Doc.audio.segments[]`
- * narration track, which remains first-class. A {@link MediaClip} is a piece
- * of audio or video whose
- * timing is expressed *relative to its parent block* (or the whole document),
- * with an optional `startAt` offset and an optional `spillover` past the
- * block's end. {@link resolveMediaSchedule} flattens these into absolute,
- * doc-timeline `ScheduledClip`s that playback and export consume.
- *
- * Authoring: a body-level `{[audio …]}` / `{[video …]}` annotation inside a
- * block becomes a `block.media` clip; the same annotation in the preamble
- * (before the first heading) with `anchor=document` becomes a
- * `doc.documentMedia` clip that spans the whole timeline.
- */
-
-import type { Block, Doc } from './Doc.js';
-
-/**
- * A timed piece of media attached to a block (or the document).
- */
-export interface MediaClip {
-  /** Stable id (for React keys and timeline selection). */
-  id: string;
-  /** Source path (mp3/mp4/…), relative to the article media dir. */
-  src: string;
-  kind: 'audio' | 'video';
-  /**
-   * Seconds from the parent block's start when this clip begins. For an
-   * `anchor='document'` clip, seconds from the document start. Default 0.
-   */
-  startAt: number;
-  /** Source in-point within the file (seconds). Default 0. */
-  clipStart?: number;
-  /** Source out-point within the file (seconds). Default: file/block end. */
-  clipEnd?: number;
-  /**
-   * When false (default) the clip stops at its block's end. When true it
-   * keeps playing past the block boundary until the clip itself finishes.
-   * Ignored for `anchor='document'` clips (they already span the timeline).
-   */
-  spillover?: boolean;
-  /**
-   * `'block'` (default) — timed relative to the parent block. `'document'` —
-   * timed relative to the document start and able to span every block.
-   */
-  anchor: 'block' | 'document';
-  /**
-   * 1-based source line of the authoring annotation, when derived from
-   * markdown. Enables round-tripping edits (e.g. the timeline editor rewriting
-   * `startAt`) back to the exact line. Absent for programmatically built clips.
-   */
-  sourceLine?: number;
-  /**
-   * Round-trip home of the authoring annotation: the block whose contents
-   * held the paragraph, its position in that block's ORIGINAL contents
-   * array (before extraction), and the paragraph's exact source text.
-   * `docToMarkdown` re-inserts the annotation from this — `raw` verbatim
-   * when present, a re-serialized annotation otherwise. Absent for
-   * programmatically built clips (those emit at the document top).
-   */
-  origin?: { blockId: string; index: number; raw?: string };
-}
-
-/**
- * A {@link MediaClip} resolved to absolute document-timeline coordinates.
- * Produced by {@link resolveMediaSchedule}; consumed by the playback
- * scheduler and the MP4 export.
- */
-export interface ScheduledClip {
-  id: string;
-  src: string;
-  kind: 'audio' | 'video';
-  /** Absolute doc-timeline second the clip starts. */
-  absoluteStart: number;
-  /** Absolute doc-timeline second the clip ends (exclusive). */
-  absoluteEnd: number;
-  /** Source in-point to seek to at `absoluteStart`. */
-  sourceIn: number;
-  anchor: 'block' | 'document';
-  /** Owning block id for block-anchored clips (for video re-homing/export). */
-  blockId?: string;
-  /** 1-based source line of the authoring annotation, when known. */
-  sourceLine?: number;
-}
-
-/** Depth-first flatten of the block tree (local copy to avoid a doc-layer dep). */
-function flatten(blocks: Block[], out: Block[] = []): Block[] {
-  for (const b of blocks) {
-    out.push(b);
-    if (b.children && b.children.length > 0) flatten(b.children, out);
-  }
-  return out;
-}
-
-/** Played length of a clip when known from its in/out points, else null. */
-function clipLength(clip: MediaClip): number | null {
-  if (clip.clipEnd == null) return null;
-  return Math.max(0, clip.clipEnd - (clip.clipStart ?? 0));
-}
-
-/**
- * Base playback span ignoring media — the larger of the audio-segment sum
- * and the last block's end. Document clips that don't pin a length run to
- * this point.
- */
-function baseTimelineEnd(doc: Doc): number {
-  const blockEnd = flatten(doc.blocks).reduce(
-    (max, b) => Math.max(max, b.startTime + b.duration),
-    0,
-  );
-  return Math.max(doc.duration ?? 0, blockEnd);
-}
-
-/**
- * Flatten every block clip and document clip into absolute-timed
- * `ScheduledClip`s. Pure — depends only on `doc`.
- */
-export function resolveMediaSchedule(doc: Doc): ScheduledClip[] {
-  const out: ScheduledClip[] = [];
-  const docEnd = baseTimelineEnd(doc);
-
-  for (const block of flatten(doc.blocks)) {
-    const blockEnd = block.startTime + block.duration;
-    for (const clip of block.media ?? []) {
-      const start = block.startTime + clip.startAt;
-      const len = clipLength(clip);
-      let end: number;
-      if (clip.spillover) {
-        // Continue past the block; fall back to the block end when the
-        // played length is unknown (no clipEnd authored).
-        end = len != null ? start + len : blockEnd;
-      } else {
-        end = len != null ? Math.min(start + len, blockEnd) : blockEnd;
-      }
-      out.push({
-        id: clip.id,
-        src: clip.src,
-        kind: clip.kind,
-        absoluteStart: start,
-        absoluteEnd: Math.max(start, end),
-        sourceIn: clip.clipStart ?? 0,
-        anchor: 'block',
-        blockId: block.id,
-        ...(clip.sourceLine != null ? { sourceLine: clip.sourceLine } : {}),
-      });
-    }
-  }
-
-  for (const clip of doc.documentMedia ?? []) {
-    const start = clip.startAt;
-    const len = clipLength(clip);
-    const end = len != null ? start + len : docEnd;
-    out.push({
-      id: clip.id,
-      src: clip.src,
-      kind: clip.kind,
-      absoluteStart: start,
-      absoluteEnd: Math.max(start, end),
-      sourceIn: clip.clipStart ?? 0,
-      anchor: 'document',
-      ...(clip.sourceLine != null ? { sourceLine: clip.sourceLine } : {}),
-    });
-  }
-
-  return out;
-}
-
-/**
- * Total playback duration including any media that spills past the last
- * block (or audio segment). Export uses this for the frame count and the
- * player for its effective timeline length.
- */
-export function getDocPlaybackDuration(doc: Doc): number {
-  const base = baseTimelineEnd(doc);
-  const mediaEnd = resolveMediaSchedule(doc).reduce((max, c) => Math.max(max, c.absoluteEnd), 0);
-  return Math.max(base, mediaEnd);
-}

package/src/schemas/MediaProvider.ts

@@ -1,70 +0,0 @@
-/**
- * MediaProvider — abstract interface for resolving and managing media assets.
- *
- * Components (ImageLayer, VideoLayer, editor preview) use a MediaProvider to
- * resolve relative media paths to displayable URLs and to manage media storage.
- *
- * This decouples the rendering layer from the storage backend:
- * - In the dev site, a SlotStorage-backed provider serves blob URLs from IndexedDB
- * - In production, a simple basePath provider constructs CDN URLs
- * - In tests, a memory-backed provider returns data URIs
- */
-
-/**
- * Metadata about a stored media asset.
- */
-export interface MediaEntry {
-  /** Filename (e.g., 'hero.jpg') */
-  name: string;
-  /** MIME type (e.g., 'image/jpeg') */
-  mimeType: string;
-  /** File size in bytes */
-  size: number;
-}
-
-/**
- * Interface for resolving and managing media assets.
- *
- * All methods are async to support IndexedDB and other async storage backends.
- * The `resolveUrl` method is the primary integration point for rendering
- * components — it converts a relative media path into a displayable URL.
- */
-export interface MediaProvider {
-  /**
-   * Resolve a relative media path to a displayable URL.
-   *
-   * Returns a URL that can be used in <img src>, <video src>, etc.
-   * This may be a blob: URL, data: URL, or absolute HTTP URL depending
-   * on the provider implementation.
-   *
-   * @param relativePath - Relative path as stored in the document (e.g., 'hero.jpg')
-   * @returns Displayable URL, or the original path if resolution fails
-   */
-  resolveUrl(relativePath: string): Promise<string>;
-
-  /**
-   * List all media assets available in this provider's scope.
-   */
-  listMedia(): Promise<MediaEntry[]>;
-
-  /**
-   * Add a media asset. Returns the relative path to reference in documents.
-   *
-   * @param name - Filename for the asset (e.g., 'photo.jpg')
-   * @param data - Binary content (ArrayBuffer, Blob, or Uint8Array)
-   * @param mimeType - MIME type of the data
-   * @returns The relative path to use in document references
-   */
-  addMedia(name: string, data: ArrayBuffer | Blob | Uint8Array, mimeType: string): Promise<string>;
-
-  /**
-   * Remove a media asset by its relative path.
-   */
-  removeMedia(relativePath: string): Promise<void>;
-
-  /**
-   * Dispose of any held resources (e.g., revoke blob URLs).
-   * Call this when the provider is no longer needed.
-   */
-  dispose(): void;
-}