@bendyline/squisq 1.2.2 → 1.4.0

package/dist/versions/paths.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Path conventions for version snapshots.
+ *
+ * Snapshots live at `<VERSIONS_PREFIX><basename>.<timestamp>[<-suffix>].md`.
+ * The optional numeric suffix (`-2`, `-3`, ...) is appended only when two
+ * snapshots collide on the same UTC second.
+ */
+/** Subfolder (inside the ContentContainer) that holds version snapshots. */
+export declare const VERSIONS_PREFIX = ".versions/";
+/**
+ * Strip the directory and extension from a document path to produce the
+ * basename used in version filenames. `subdir/index.md` -> `index`.
+ */
+export declare function getDocBasename(documentPath: string): string;
+/**
+ * Build a version snapshot path. Optionally append a collision suffix
+ * (e.g. `2`, `3`) when two saves land on the same UTC second.
+ */
+export declare function buildVersionPath(basename: string, date: Date, collision?: number): string;
+/**
+ * Parse a version snapshot path. Returns null if it doesn't match the
+ * convention (so unrelated files stored under `.versions/` are ignored).
+ */
+export declare function parseVersionPath(path: string): {
+    basename: string;
+    timestamp: Date;
+    collision: number;
+} | null;
+//# sourceMappingURL=paths.d.ts.map

package/dist/versions/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/versions/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,4EAA4E;AAC5E,eAAO,MAAM,eAAe,eAAe,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAK3D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,SAAI,GAAG,MAAM,CAIpF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,GACX;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAyBjE"}

package/dist/versions/paths.js

@@ -0,0 +1,66 @@
+/**
+ * Path conventions for version snapshots.
+ *
+ * Snapshots live at `<VERSIONS_PREFIX><basename>.<timestamp>[<-suffix>].md`.
+ * The optional numeric suffix (`-2`, `-3`, ...) is appended only when two
+ * snapshots collide on the same UTC second.
+ */
+import { formatVersionTimestamp, parseVersionTimestamp } from './timestamp.js';
+/** Subfolder (inside the ContentContainer) that holds version snapshots. */
+export const VERSIONS_PREFIX = '.versions/';
+/**
+ * Strip the directory and extension from a document path to produce the
+ * basename used in version filenames. `subdir/index.md` -> `index`.
+ */
+export function getDocBasename(documentPath) {
+    const slash = documentPath.lastIndexOf('/');
+    const file = slash >= 0 ? documentPath.slice(slash + 1) : documentPath;
+    const dot = file.lastIndexOf('.');
+    return dot > 0 ? file.slice(0, dot) : file;
+}
+/**
+ * Build a version snapshot path. Optionally append a collision suffix
+ * (e.g. `2`, `3`) when two saves land on the same UTC second.
+ */
+export function buildVersionPath(basename, date, collision = 0) {
+    const stamp = formatVersionTimestamp(date);
+    const suffix = collision > 0 ? `-${collision + 1}` : '';
+    return `${VERSIONS_PREFIX}${basename}.${stamp}${suffix}.md`;
+}
+/**
+ * Parse a version snapshot path. Returns null if it doesn't match the
+ * convention (so unrelated files stored under `.versions/` are ignored).
+ */
+export function parseVersionPath(path) {
+    if (!path.startsWith(VERSIONS_PREFIX))
+        return null;
+    const rest = path.slice(VERSIONS_PREFIX.length);
+    if (!rest.endsWith('.md'))
+        return null;
+    const stem = rest.slice(0, -'.md'.length);
+    // basename can contain dots; the timestamp is always the *last* dot-segment
+    // (optionally followed by a `-N` collision suffix).
+    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;
+    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 };
+}
+//# sourceMappingURL=paths.js.map

package/dist/versions/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/versions/paths.ts"],"names":[],"mappings":"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"}

package/dist/versions/timestamp.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Sortable, human-readable timestamps for version filenames.
+ *
+ * Format: ISO 8601 basic, UTC, second precision, `Z` suffix —
+ * e.g. `20260430T152030Z`. Lexicographic order matches chronological order,
+ * so `listFiles` returns versions in time order without parsing.
+ */
+/**
+ * Format a Date as a sortable, filename-safe UTC timestamp string.
+ */
+export declare function formatVersionTimestamp(date: Date): string;
+/**
+ * Parse a version timestamp string back to a Date. Returns null if the input
+ * doesn't match the expected format.
+ */
+export declare function parseVersionTimestamp(stamp: string): Date | null;
+/**
+ * The pattern a valid version timestamp matches. Exported so other modules
+ * can validate filenames without re-deriving the regex.
+ */
+export declare const VERSION_TIMESTAMP_PATTERN: RegExp;
+//# sourceMappingURL=timestamp.d.ts.map

package/dist/versions/timestamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.d.ts","sourceRoot":"","sources":["../../src/versions/timestamp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAWzD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAOhE;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,QAAe,CAAC"}

package/dist/versions/timestamp.js

@@ -0,0 +1,44 @@
+/**
+ * Sortable, human-readable timestamps for version filenames.
+ *
+ * Format: ISO 8601 basic, UTC, second precision, `Z` suffix —
+ * e.g. `20260430T152030Z`. Lexicographic order matches chronological order,
+ * so `listFiles` returns versions in time order without parsing.
+ */
+const TIMESTAMP_RE = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/;
+function pad2(n) {
+    return n < 10 ? `0${n}` : String(n);
+}
+/**
+ * Format a Date as a sortable, filename-safe UTC timestamp string.
+ */
+export function formatVersionTimestamp(date) {
+    return (String(date.getUTCFullYear()).padStart(4, '0') +
+        pad2(date.getUTCMonth() + 1) +
+        pad2(date.getUTCDate()) +
+        'T' +
+        pad2(date.getUTCHours()) +
+        pad2(date.getUTCMinutes()) +
+        pad2(date.getUTCSeconds()) +
+        'Z');
+}
+/**
+ * Parse a version timestamp string back to a Date. Returns null if the input
+ * doesn't match the expected format.
+ */
+export function parseVersionTimestamp(stamp) {
+    const m = TIMESTAMP_RE.exec(stamp);
+    if (!m)
+        return null;
+    const [, y, mo, d, h, mi, s] = m;
+    const ms = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s));
+    if (Number.isNaN(ms))
+        return null;
+    return new Date(ms);
+}
+/**
+ * The pattern a valid version timestamp matches. Exported so other modules
+ * can validate filenames without re-deriving the regex.
+ */
+export const VERSION_TIMESTAMP_PATTERN = TIMESTAMP_RE;
+//# sourceMappingURL=timestamp.js.map

package/dist/versions/timestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.js","sourceRoot":"","sources":["../../src/versions/timestamp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,YAAY,GAAG,gDAAgD,CAAC;AAEtE,SAAS,IAAI,CAAC,CAAS;IACrB,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAU;IAC/C,OAAO,CACL,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;QACvB,GAAG;QACH,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACxB,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;QAC1B,GAAG,CACJ,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5F,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,YAAY,CAAC"}

package/dist/versions/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Public types for the document version-history feature.
+ *
+ * Versions are snapshots of the primary markdown document stored alongside
+ * the document inside the same {@link ContentContainer}. They live under
+ * `.versions/<docBasename>.<sortableTimestamp>.md`. The container is the
+ * unit of persistence — when the host serializes the container to a ZIP,
+ * a real folder, or anywhere else, the version snapshots ride along.
+ */
+/**
+ * A single version snapshot record.
+ */
+export interface Version {
+    /** Container-relative path, e.g. `.versions/index.20260430T152030Z.md`. */
+    path: string;
+    /** Document basename without extension, e.g. `index`. */
+    basename: string;
+    /** Parsed timestamp from the filename, in UTC. */
+    timestamp: Date;
+    /** Snapshot size in bytes. */
+    size: number;
+    /**
+     * Collision suffix index. `0` for a path with no `-N` suffix, `1` for `-2`,
+     * `2` for `-3`, and so on. Used as the tie-break for ordering snapshots
+     * that share the same UTC second.
+     */
+    collision: number;
+}
+/**
+ * Result of a {@link saveVersion} call.
+ */
+export interface SaveVersionResult {
+    /** True when a new snapshot file was actually written. */
+    saved: boolean;
+    /** The newly stamped version (only when `saved` is true). */
+    version: Version | null;
+    /**
+     * Why the save behaved the way it did:
+     * - `'saved'`        — a new snapshot was written.
+     * - `'unchanged'`    — current content matches the latest snapshot byte-for-byte.
+     * - `'no-document'`  — the container has no primary markdown document.
+     * - `'empty'`        — the resolved content was empty.
+     */
+    reason: 'saved' | 'unchanged' | 'no-document' | 'empty';
+}
+/**
+ * Options for {@link saveVersion}.
+ */
+export interface SaveVersionOptions {
+    /** Override the document content; otherwise the container's primary doc is read. */
+    content?: string;
+    /** Override the timestamp; defaults to `new Date()`. Useful for tests. */
+    now?: Date;
+    /** Skip the diff-vs-latest check and force a write. */
+    force?: boolean;
+    /** Override the document basename used to build the version filename. */
+    basename?: string;
+}
+/**
+ * Pruning policy passed to {@link pruneVersions}.
+ */
+export type PrunePolicy = {
+    type: 'keep-last-n';
+    n: number;
+} | {
+    type: 'older-than';
+    date: Date;
+} | {
+    type: 'predicate';
+    keep: (v: Version, all: Version[]) => boolean;
+};
+/**
+ * Options for {@link revertToVersion}.
+ */
+export interface RevertOptions {
+    /**
+     * Whether to snapshot the current document content before replacing it.
+     * Defaults to `true` so a revert is always recoverable.
+     */
+    snapshotCurrent?: boolean;
+}
+/**
+ * Options for {@link coalesceVersions}.
+ */
+export interface CoalesceOptions {
+    /**
+     * Two adjacent snapshots whose timestamps are within `windowMs` collapse
+     * to the newer one. Defaults to 60_000 (one minute).
+     */
+    windowMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/versions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/versions/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,SAAS,EAAE,IAAI,CAAC;IAChB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB;;;;;;OAMG;IACH,MAAM,EAAE,OAAO,GAAG,WAAW,GAAG,aAAa,GAAG,OAAO,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,uDAAuD;IACvD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;CAAE,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/versions/types.js

@@ -0,0 +1,11 @@
+/**
+ * Public types for the document version-history feature.
+ *
+ * Versions are snapshots of the primary markdown document stored alongside
+ * the document inside the same {@link ContentContainer}. They live under
+ * `.versions/<docBasename>.<sortableTimestamp>.md`. The container is the
+ * unit of persistence — when the host serializes the container to a ZIP,
+ * a real folder, or anywhere else, the version snapshots ride along.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/versions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/versions/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "description": "Headless utilities for doc/block rendering, spatial math, Markdown, and storage",
   "license": "MIT",
   "author": "Bendyline",
@@ -85,13 +85,40 @@
       "types": "./dist/transform/index.d.ts",
       "import": "./dist/transform/index.js",
       "default": "./dist/transform/index.js"
+    },
+    "./versions": {
+      "types": "./dist/versions/index.d.ts",
+      "import": "./dist/versions/index.js",
+      "default": "./dist/versions/index.js"
+    },
+    "./jsonForm": {
+      "types": "./dist/jsonForm/index.d.ts",
+      "import": "./dist/jsonForm/index.js",
+      "default": "./dist/jsonForm/index.js"
+    },
+    "./imageEdit": {
+      "types": "./dist/imageEdit/index.d.ts",
+      "import": "./dist/imageEdit/index.js",
+      "default": "./dist/imageEdit/index.js"
+    },
+    "./icons": {
+      "types": "./dist/icons/index.d.ts",
+      "import": "./dist/icons/index.js",
+      "default": "./dist/icons/index.js"
+    },
+    "./recommend": {
+      "types": "./dist/recommend/index.d.ts",
+      "import": "./dist/recommend/index.js",
+      "default": "./dist/recommend/index.js"
     }
   },
   "scripts": {
     "build": "tsup",
+    "dev": "concurrently -n js,dts -c blue,gray -r \"tsup --watch --no-dts --no-clean\" \"tsup --watch --dts-only --no-clean\"",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "genson-js": "0.0.8",
     "hast-util-from-html": "2.0.3",
     "localforage": "1.10.0",
     "ngeohash": "0.6.3",

package/src/__tests__/colorUtils.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isHex,
+  oklchLighten,
+  oklchDarken,
+  oklchSetChroma,
+  contrastRatio,
+  pickContrastingText,
+  deriveScale,
+  relativeLuminance,
+} from '../schemas/colorUtils.js';
+
+describe('isHex', () => {
+  it('accepts #rgb and #rrggbb', () => {
+    expect(isHex('#fff')).toBe(true);
+    expect(isHex('#123abc')).toBe(true);
+    expect(isHex('#FF0080')).toBe(true);
+  });
+  it('rejects malformed strings', () => {
+    expect(isHex('fff')).toBe(false);
+    expect(isHex('#1234')).toBe(false);
+    expect(isHex('#xyz')).toBe(false);
+    expect(isHex('rgb(0,0,0)')).toBe(false);
+  });
+});
+
+describe('oklchLighten / oklchDarken', () => {
+  it('lighten produces a lighter color (higher luminance)', () => {
+    const dark = '#101010';
+    const lighter = oklchLighten(dark, 0.2);
+    expect(relativeLuminance(lighter)).toBeGreaterThan(relativeLuminance(dark));
+  });
+
+  it('darken produces a darker color (lower luminance)', () => {
+    const light = '#e0e0e0';
+    const darker = oklchDarken(light, 0.2);
+    expect(relativeLuminance(darker)).toBeLessThan(relativeLuminance(light));
+  });
+
+  it('round-trips approximately stable for moderate adjustments', () => {
+    const seed = '#3182ce';
+    const round = oklchDarken(oklchLighten(seed, 0.1), 0.1);
+    // sRGB gamut clamping prevents perfect round-trip; expect within a small epsilon.
+    expect(round).toMatch(/^#[0-9a-f]{6}$/);
+    const lumDiff = Math.abs(relativeLuminance(seed) - relativeLuminance(round));
+    expect(lumDiff).toBeLessThan(0.05);
+  });
+
+  it('returns a hex string', () => {
+    expect(oklchLighten('#3182ce', 0.1)).toMatch(/^#[0-9a-f]{6}$/);
+    expect(oklchDarken('#3182ce', 0.1)).toMatch(/^#[0-9a-f]{6}$/);
+  });
+
+  it('falls back to input on parse failure', () => {
+    expect(oklchLighten('not-a-color', 0.1)).toBe('not-a-color');
+  });
+});
+
+describe('oklchSetChroma', () => {
+  it('reducing chroma toward 0 desaturates a color', () => {
+    const vivid = '#ff3366';
+    const muted = oklchSetChroma(vivid, 0.1);
+    // Muted version's R/G/B channels should be much closer to each other than vivid.
+    const parse = (h: string) => [
+      parseInt(h.slice(1, 3), 16),
+      parseInt(h.slice(3, 5), 16),
+      parseInt(h.slice(5, 7), 16),
+    ];
+    const [vr, vg, vb] = parse(vivid);
+    const [mr, mg, mb] = parse(muted);
+    const vSpread = Math.max(vr, vg, vb) - Math.min(vr, vg, vb);
+    const mSpread = Math.max(mr, mg, mb) - Math.min(mr, mg, mb);
+    expect(mSpread).toBeLessThan(vSpread);
+  });
+});
+
+describe('contrastRatio', () => {
+  it('white-on-black is the maximum (≈21)', () => {
+    expect(contrastRatio('#ffffff', '#000000')).toBeCloseTo(21, 0);
+  });
+  it('same-color is 1', () => {
+    expect(contrastRatio('#aabbcc', '#aabbcc')).toBeCloseTo(1, 5);
+  });
+  it('is symmetric', () => {
+    expect(contrastRatio('#222', '#ddd')).toBeCloseTo(contrastRatio('#ddd', '#222'), 5);
+  });
+});
+
+describe('pickContrastingText', () => {
+  it('returns dark text for light backgrounds', () => {
+    expect(pickContrastingText('#ffffff')).toBe('#1a202c');
+    expect(pickContrastingText('#f7fafc')).toBe('#1a202c');
+  });
+  it('returns light text for dark backgrounds', () => {
+    expect(pickContrastingText('#000000')).toBe('#f7fafc');
+    expect(pickContrastingText('#1a202c')).toBe('#f7fafc');
+  });
+  it('respects custom light/dark options', () => {
+    expect(pickContrastingText('#000000', '#fefefe', '#020202')).toBe('#fefefe');
+  });
+});
+
+describe('deriveScale', () => {
+  it('produces 5 stops with base in the middle', () => {
+    const scale = deriveScale('#3182ce', 0.15);
+    expect(scale.base).toBe('#3182ce');
+    expect(relativeLuminance(scale.lighter2)).toBeGreaterThan(relativeLuminance(scale.lighter1));
+    expect(relativeLuminance(scale.lighter1)).toBeGreaterThan(relativeLuminance(scale.base));
+    expect(relativeLuminance(scale.base)).toBeGreaterThan(relativeLuminance(scale.darker1));
+    expect(relativeLuminance(scale.darker1)).toBeGreaterThan(relativeLuminance(scale.darker2));
+  });
+});

package/src/__tests__/getLayers.test.ts

@@ -11,7 +11,7 @@ import type { Block, Layer, TextLayer, ShapeLayer } from '../schemas/Doc.js';
 
 function makeTemplateBlock(overrides: Partial<TemplateBlock> = {}): TemplateBlock {
   return {
-    template: 'titleBlock',
+    template: 'title',
     id: 'test-title-1',
     duration: 5,
     audioSegment: 0,
@@ -43,7 +43,7 @@ const defaultContext: RenderContext = {
 
 describe('getLayers', () => {
   it('generates layers for a known template block', () => {
-    const block = makeTemplateBlock({ template: 'titleBlock', title: 'Test Title' });
+    const block = makeTemplateBlock({ template: 'title', title: 'Test Title' });
     const layers = getLayers(block, defaultContext);
 
     expect(Array.isArray(layers)).toBe(true);
@@ -83,6 +83,31 @@ describe('getLayers', () => {
     expect(layers).toEqual(existingLayers);
   });
 
+  it('resolves legacy template aliases through TEMPLATE_ALIASES', () => {
+    // Regression: `getLayers` previously did `block.template in templateRegistry`
+    // without alias resolution, so docs authored with the legacy long ids
+    // (`titleBlock`, `quoteBlock`, `mapBlock`, `listBlock`) rendered as
+    // empty SVG cards in the linear/document view — `hasTemplate()` accepts
+    // the alias, so `isAnnotatedBlock` returns true and the card wrapper
+    // renders, but the registry lookup below would miss the alias and the
+    // layer array came back empty.
+    const aliasedToCanonical: Array<[string, string]> = [
+      ['titleBlock', 'title'],
+      ['quoteBlock', 'quote'],
+      ['listBlock', 'list'],
+    ];
+    for (const [alias] of aliasedToCanonical) {
+      const block = makeTemplateBlock({
+        template: alias as TemplateBlock['template'],
+        title: 'Aliased',
+        items: ['a', 'b', 'c'],
+        quote: 'q',
+      } as Partial<TemplateBlock>);
+      const layers = getLayers(block, defaultContext);
+      expect(layers.length).toBeGreaterThan(0);
+    }
+  });
+
   it('returns empty array for unknown template', () => {
     const block = {
       template: 'totally_nonexistent',
@@ -103,7 +128,7 @@ describe('getLayers', () => {
   });
 
   it('uses default context values when context is omitted', () => {
-    const block = makeTemplateBlock({ template: 'titleBlock', title: 'Defaults' });
+    const block = makeTemplateBlock({ template: 'title', title: 'Defaults' });
     const layers = getLayers(block);
 
     expect(Array.isArray(layers)).toBe(true);
@@ -147,7 +172,7 @@ describe('getLayers', () => {
     };
 
     it('injects persistent bottom and top layers around block layers', () => {
-      const block = makeTemplateBlock({ template: 'titleBlock', title: 'With Persistent' });
+      const block = makeTemplateBlock({ template: 'title', title: 'With Persistent' });
       const layers = getLayers(block, { ...defaultContext, persistentLayers: persistentConfig });
 
       // First layer should be the bottom persistent layer
@@ -160,7 +185,7 @@ describe('getLayers', () => {
 
     it('respects useBottomLayer: false opt-out', () => {
       const block = makeTemplateBlock({
-        template: 'titleBlock',
+        template: 'title',
         title: 'No Bottom',
         useBottomLayer: false,
       });
@@ -174,7 +199,7 @@ describe('getLayers', () => {
 
     it('respects useTopLayer: false opt-out', () => {
       const block = makeTemplateBlock({
-        template: 'titleBlock',
+        template: 'title',
         title: 'No Top',
         useTopLayer: false,
       });
@@ -187,7 +212,7 @@ describe('getLayers', () => {
     });
 
     it('skips injection when no persistent layers are configured', () => {
-      const block = makeTemplateBlock({ template: 'titleBlock', title: 'No Persistent' });
+      const block = makeTemplateBlock({ template: 'title', title: 'No Persistent' });
       const withoutPersistent = getLayers(block, defaultContext);
       const withEmptyPersistent = getLayers(block, {
         ...defaultContext,