@bendyline/squisq 1.3.0 → 1.4.1

package/src/__tests__/versions.test.ts

@@ -0,0 +1,415 @@
+import { describe, expect, it, beforeEach } from 'vitest';
+import { MemoryContentContainer } from '../storage/ContentContainer';
+import {
+  DocumentVersionManager,
+  VERSIONS_PREFIX,
+  buildVersionPath,
+  coalesceVersions,
+  formatVersionTimestamp,
+  getDocBasename,
+  listVersions,
+  parseVersionPath,
+  parseVersionTimestamp,
+  pruneVersions,
+  readVersion,
+  revertToVersion,
+  saveVersion,
+} from '../versions';
+
+const decoder = new TextDecoder();
+
+async function readUtf8(c: MemoryContentContainer, path: string): Promise<string | null> {
+  const data = await c.readFile(path);
+  return data ? decoder.decode(data) : null;
+}
+
+describe('formatVersionTimestamp / parseVersionTimestamp', () => {
+  it('round-trips to second precision', () => {
+    const d = new Date(Date.UTC(2026, 3, 30, 15, 20, 30));
+    const stamp = formatVersionTimestamp(d);
+    expect(stamp).toBe('20260430T152030Z');
+    const parsed = parseVersionTimestamp(stamp);
+    expect(parsed?.getTime()).toBe(d.getTime());
+  });
+
+  it('returns null for invalid input', () => {
+    expect(parseVersionTimestamp('not-a-stamp')).toBeNull();
+    expect(parseVersionTimestamp('20260430T152030')).toBeNull(); // missing Z
+    expect(parseVersionTimestamp('2026-04-30T15:20:30Z')).toBeNull(); // wrong format
+  });
+
+  it('orders chronologically when sorted lexicographically', () => {
+    const a = formatVersionTimestamp(new Date(Date.UTC(2026, 0, 1, 0, 0, 0)));
+    const b = formatVersionTimestamp(new Date(Date.UTC(2026, 0, 1, 0, 0, 1)));
+    const c = formatVersionTimestamp(new Date(Date.UTC(2026, 5, 15, 12, 0, 0)));
+    expect([c, a, b].sort()).toEqual([a, b, c]);
+  });
+});
+
+describe('paths', () => {
+  it('getDocBasename strips folder + extension', () => {
+    expect(getDocBasename('index.md')).toBe('index');
+    expect(getDocBasename('subdir/foo.md')).toBe('foo');
+    expect(getDocBasename('a/b/c/longname.md')).toBe('longname');
+    expect(getDocBasename('noext')).toBe('noext');
+  });
+
+  it('buildVersionPath round-trips through parseVersionPath', () => {
+    const d = new Date(Date.UTC(2026, 3, 30, 15, 20, 30));
+    const p = buildVersionPath('index', d);
+    expect(p).toBe(`${VERSIONS_PREFIX}index.20260430T152030Z.md`);
+    const parsed = parseVersionPath(p);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.basename).toBe('index');
+    expect(parsed!.timestamp.getTime()).toBe(d.getTime());
+    expect(parsed!.collision).toBe(0);
+  });
+
+  it('buildVersionPath / parseVersionPath handle collision suffix', () => {
+    const d = new Date(Date.UTC(2026, 3, 30, 15, 20, 30));
+    const p1 = buildVersionPath('index', d, 1);
+    expect(p1).toBe(`${VERSIONS_PREFIX}index.20260430T152030Z-2.md`);
+    const parsed = parseVersionPath(p1);
+    expect(parsed?.collision).toBe(1);
+  });
+
+  it('parseVersionPath returns null for non-version files', () => {
+    expect(parseVersionPath('index.md')).toBeNull();
+    expect(parseVersionPath('.versions/notes.txt')).toBeNull();
+    expect(parseVersionPath('.versions/index.invalidstamp.md')).toBeNull();
+    expect(parseVersionPath('.versions/index.20260430T152030Z-1.md')).toBeNull(); // suffix must be >= 2
+  });
+});
+
+describe('saveVersion', () => {
+  let container: MemoryContentContainer;
+
+  beforeEach(() => {
+    container = new MemoryContentContainer();
+  });
+
+  it('returns no-document when container has no markdown', async () => {
+    const result = await saveVersion(container);
+    expect(result.saved).toBe(false);
+    expect(result.reason).toBe('no-document');
+  });
+
+  it('returns empty when document content is empty', async () => {
+    await container.writeDocument('', 'index.md');
+    const result = await saveVersion(container);
+    expect(result.saved).toBe(false);
+    expect(result.reason).toBe('empty');
+  });
+
+  it('writes a snapshot to .versions/ on first save', async () => {
+    await container.writeDocument('# hello', 'index.md');
+    const now = new Date(Date.UTC(2026, 3, 30, 15, 20, 30));
+    const result = await saveVersion(container, { now });
+
+    expect(result.saved).toBe(true);
+    expect(result.reason).toBe('saved');
+    expect(result.version?.path).toBe(`${VERSIONS_PREFIX}index.20260430T152030Z.md`);
+    expect(result.version?.basename).toBe('index');
+    expect(await readUtf8(container, result.version!.path)).toBe('# hello');
+  });
+
+  it('returns unchanged on identical second save', async () => {
+    await container.writeDocument('# hello', 'index.md');
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 30)) });
+    const result = await saveVersion(container, {
+      now: new Date(Date.UTC(2026, 3, 30, 15, 20, 31)),
+    });
+    expect(result.saved).toBe(false);
+    expect(result.reason).toBe('unchanged');
+    const all = await listVersions(container);
+    expect(all).toHaveLength(1);
+  });
+
+  it('writes again when content changes', async () => {
+    await container.writeDocument('# hello', 'index.md');
+    const r1 = await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 30)) });
+    await container.writeDocument('# hello world', 'index.md');
+    const r2 = await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 31)) });
+
+    expect(r1.saved).toBe(true);
+    expect(r2.saved).toBe(true);
+    expect(r1.version?.path).not.toBe(r2.version?.path);
+    expect(await listVersions(container)).toHaveLength(2);
+  });
+
+  it('force: true writes despite equality', async () => {
+    await container.writeDocument('# hello', 'index.md');
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 30)) });
+    const r = await saveVersion(container, {
+      force: true,
+      now: new Date(Date.UTC(2026, 3, 30, 15, 20, 31)),
+    });
+    expect(r.saved).toBe(true);
+    expect(await listVersions(container)).toHaveLength(2);
+  });
+
+  it('appends a collision suffix when two saves land on the same UTC second', async () => {
+    await container.writeDocument('# hello', 'index.md');
+    const now = new Date(Date.UTC(2026, 3, 30, 15, 20, 30));
+    const r1 = await saveVersion(container, { now });
+    // Mutate doc and force-save in the same second.
+    await container.writeDocument('# hello v2', 'index.md');
+    const r2 = await saveVersion(container, { now });
+
+    expect(r1.version?.path).toBe(`${VERSIONS_PREFIX}index.20260430T152030Z.md`);
+    expect(r2.version?.path).toBe(`${VERSIONS_PREFIX}index.20260430T152030Z-2.md`);
+  });
+
+  it('content option overrides container.readDocument()', async () => {
+    await container.writeDocument('# stored', 'index.md');
+    const r = await saveVersion(container, {
+      content: '# override',
+      now: new Date(Date.UTC(2026, 3, 30, 15, 20, 30)),
+    });
+    expect(r.saved).toBe(true);
+    expect(await readUtf8(container, r.version!.path)).toBe('# override');
+  });
+
+  it('basename option overrides the derived basename', async () => {
+    await container.writeDocument('# hi', 'index.md');
+    const r = await saveVersion(container, {
+      basename: 'custom',
+      now: new Date(Date.UTC(2026, 3, 30, 15, 20, 30)),
+    });
+    expect(r.version?.path).toBe(`${VERSIONS_PREFIX}custom.20260430T152030Z.md`);
+  });
+});
+
+describe('listVersions', () => {
+  let container: MemoryContentContainer;
+  beforeEach(() => {
+    container = new MemoryContentContainer();
+  });
+
+  it('ignores non-matching filenames inside .versions/', async () => {
+    await container.writeFile(`${VERSIONS_PREFIX}README.txt`, new TextEncoder().encode('skip me'));
+    await container.writeFile(
+      `${VERSIONS_PREFIX}index.invalidstamp.md`,
+      new TextEncoder().encode('also skip'),
+    );
+    expect(await listVersions(container)).toEqual([]);
+  });
+
+  it('returns newest-first', async () => {
+    await container.writeDocument('a', 'index.md');
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 10, 0, 0)) });
+    await container.writeDocument('b', 'index.md');
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 11, 0, 0)) });
+    await container.writeDocument('c', 'index.md');
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 12, 0, 0)) });
+
+    const versions = await listVersions(container);
+    expect(versions.map((v) => v.timestamp.getUTCHours())).toEqual([12, 11, 10]);
+  });
+
+  it('basename filter excludes other docs', async () => {
+    await container.writeFile(
+      `${VERSIONS_PREFIX}foo.20260430T100000Z.md`,
+      new TextEncoder().encode('foo'),
+    );
+    await container.writeFile(
+      `${VERSIONS_PREFIX}bar.20260430T100000Z.md`,
+      new TextEncoder().encode('bar'),
+    );
+    expect((await listVersions(container, 'foo')).map((v) => v.basename)).toEqual(['foo']);
+  });
+
+  it('orders collision-suffix snapshots newest-first within the same UTC second', async () => {
+    // Three saves at the same UTC second produce paths with collisions 0, 1, 2.
+    // The lex order of the suffix bytes (`-` < `.`) does not match the write
+    // order, so the comparator must use the parsed collision number.
+    await container.writeDocument('a', 'index.md');
+    const now = new Date(Date.UTC(2026, 3, 30, 15, 20, 30));
+    await saveVersion(container, { now });
+    await container.writeDocument('b', 'index.md');
+    await saveVersion(container, { now });
+    await container.writeDocument('c', 'index.md');
+    await saveVersion(container, { now });
+
+    const versions = await listVersions(container);
+    expect(versions.map((v) => v.collision)).toEqual([2, 1, 0]);
+    expect(versions[0]!.path).toBe(`${VERSIONS_PREFIX}index.20260430T152030Z-3.md`);
+    expect(versions[2]!.path).toBe(`${VERSIONS_PREFIX}index.20260430T152030Z.md`);
+  });
+
+  it('saveVersion dedup compares against the actual newest snapshot after a collision', async () => {
+    // Regression: when a collision suffix exists, dedup must read the
+    // collision file (the real "latest"), not the earlier no-suffix file.
+    await container.writeDocument('first', 'index.md');
+    const now = new Date(Date.UTC(2026, 3, 30, 15, 20, 30));
+    await saveVersion(container, { now });
+    await container.writeDocument('second', 'index.md');
+    await saveVersion(container, { now });
+
+    // Latest content on disk is "second"; saving it again should be a no-op.
+    const r = await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 31)) });
+    expect(r.saved).toBe(false);
+    expect(r.reason).toBe('unchanged');
+  });
+});
+
+describe('readVersion', () => {
+  it('accepts both Version object and string path', async () => {
+    const container = new MemoryContentContainer();
+    await container.writeDocument('# content', 'index.md');
+    const r = await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 15, 20, 30)) });
+    expect(await readVersion(container, r.version!)).toBe('# content');
+    expect(await readVersion(container, r.version!.path)).toBe('# content');
+  });
+
+  it('returns null for missing snapshot', async () => {
+    const container = new MemoryContentContainer();
+    expect(await readVersion(container, '.versions/missing.20260430T100000Z.md')).toBeNull();
+  });
+});
+
+describe('revertToVersion', () => {
+  let container: MemoryContentContainer;
+  beforeEach(() => {
+    container = new MemoryContentContainer();
+  });
+
+  it('writes a snapshot of the current doc before reverting (default)', async () => {
+    await container.writeDocument('# v1', 'index.md');
+    const r1 = await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 10, 0, 0)) });
+    await container.writeDocument('# v2 in flight', 'index.md');
+
+    const result = await revertToVersion(container, r1.version!);
+    expect(result.reverted).toBe(true);
+    expect(result.snapshotted).not.toBeNull();
+    expect(await container.readDocument()).toBe('# v1');
+    // We should now have two snapshots: the original + the just-snapshotted v2.
+    expect(await listVersions(container)).toHaveLength(2);
+  });
+
+  it('snapshotCurrent: false skips the safety snapshot', async () => {
+    await container.writeDocument('# v1', 'index.md');
+    const r1 = await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 10, 0, 0)) });
+    await container.writeDocument('# v2 in flight', 'index.md');
+
+    const result = await revertToVersion(container, r1.version!, { snapshotCurrent: false });
+    expect(result.snapshotted).toBeNull();
+    expect(await container.readDocument()).toBe('# v1');
+    expect(await listVersions(container)).toHaveLength(1);
+  });
+
+  it('returns reverted: false for missing snapshot', async () => {
+    const result = await revertToVersion(container, '.versions/missing.20260430T100000Z.md');
+    expect(result.reverted).toBe(false);
+  });
+});
+
+describe('pruneVersions', () => {
+  let container: MemoryContentContainer;
+
+  async function seed(times: number): Promise<void> {
+    for (let i = 0; i < times; i++) {
+      await container.writeDocument(`# v${i}`, 'index.md');
+      await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 10 + i, 0, 0)) });
+    }
+  }
+
+  beforeEach(() => {
+    container = new MemoryContentContainer();
+  });
+
+  it('keep-last-n keeps the n newest', async () => {
+    await seed(5);
+    const deleted = await pruneVersions(container, { type: 'keep-last-n', n: 3 });
+    expect(deleted).toHaveLength(2);
+    const remaining = await listVersions(container);
+    expect(remaining).toHaveLength(3);
+    expect(remaining.map((v) => v.timestamp.getUTCHours())).toEqual([14, 13, 12]);
+  });
+
+  it('keep-last-n with n: 0 deletes everything', async () => {
+    await seed(3);
+    await pruneVersions(container, { type: 'keep-last-n', n: 0 });
+    expect(await listVersions(container)).toHaveLength(0);
+  });
+
+  it('older-than deletes only items older than the cutoff', async () => {
+    await seed(5);
+    const cutoff = new Date(Date.UTC(2026, 3, 30, 12, 0, 0));
+    const deleted = await pruneVersions(container, { type: 'older-than', date: cutoff });
+    // hours 10 and 11 are older than 12 → deleted.
+    expect(deleted).toHaveLength(2);
+    const remaining = await listVersions(container);
+    expect(remaining.map((v) => v.timestamp.getUTCHours())).toEqual([14, 13, 12]);
+  });
+
+  it('predicate keeps items the predicate accepts', async () => {
+    await seed(4);
+    const deleted = await pruneVersions(container, {
+      type: 'predicate',
+      keep: (v) => v.timestamp.getUTCHours() % 2 === 0,
+    });
+    // 10 and 12 are even (kept); 11 and 13 are odd (deleted).
+    expect(deleted).toHaveLength(2);
+    expect((await listVersions(container)).map((v) => v.timestamp.getUTCHours())).toEqual([12, 10]);
+  });
+});
+
+describe('coalesceVersions', () => {
+  it('collapses snapshots within the window', async () => {
+    const container = new MemoryContentContainer();
+    // Three saves: t=0, t=30s (within window), t=2min (outside window).
+    await container.writeDocument('a', 'index.md');
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 10, 0, 0)) });
+    await container.writeDocument('b', 'index.md');
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 10, 0, 30)) });
+    await container.writeDocument('c', 'index.md');
+    await saveVersion(container, { now: new Date(Date.UTC(2026, 3, 30, 10, 2, 0)) });
+
+    const deleted = await coalesceVersions(container, { windowMs: 60_000 });
+    // Walking newest-first: the (10:00:30, 10:00:00) pair is 30s apart
+    // (within the window), so 10:00:00 — the older of the two — is dropped.
+    // The (10:02:00, 10:00:30) pair is 90s apart, so 10:00:30 survives.
+    expect(deleted).toHaveLength(1);
+    expect(deleted[0]!.timestamp.getTime()).toBe(Date.UTC(2026, 3, 30, 10, 0, 0));
+  });
+
+  it('anchors to the last kept snapshot instead of chaining adjacent pairs', async () => {
+    // Regression: four snapshots 30s apart with windowMs: 60_000 should keep
+    // the newest plus anything beyond 60s of the anchor (here, t=0). Chaining
+    // through deleted entries would erase everything but the newest.
+    const container = new MemoryContentContainer();
+    const base = Date.UTC(2026, 3, 30, 10, 0, 0);
+    await container.writeDocument('a', 'index.md');
+    await saveVersion(container, { now: new Date(base) });
+    await container.writeDocument('b', 'index.md');
+    await saveVersion(container, { now: new Date(base + 30_000) });
+    await container.writeDocument('c', 'index.md');
+    await saveVersion(container, { now: new Date(base + 60_000) });
+    await container.writeDocument('d', 'index.md');
+    await saveVersion(container, { now: new Date(base + 90_000) });
+
+    const deleted = await coalesceVersions(container, { windowMs: 60_000 });
+    // Anchor=t+90 keeps t+30 dropped (60s ≤ window), keeps t=0 (90s > window
+    // from anchor → new anchor). t+60 is also within 60s of t+90 → dropped.
+    expect(deleted).toHaveLength(2);
+    const remaining = await listVersions(container);
+    expect(remaining.map((v) => v.timestamp.getTime() - base)).toEqual([90_000, 0]);
+  });
+});
+
+describe('DocumentVersionManager', () => {
+  it('forwards calls and applies the basename override', async () => {
+    const container = new MemoryContentContainer();
+    await container.writeDocument('# hi', 'index.md');
+    const manager = new DocumentVersionManager(container, { basename: 'custom' });
+    const r = await manager.saveVersion({ now: new Date(Date.UTC(2026, 3, 30, 15, 20, 30)) });
+    expect(r.version?.path).toBe(`${VERSIONS_PREFIX}custom.20260430T152030Z.md`);
+
+    const list = await manager.listVersions();
+    expect(list).toHaveLength(1);
+
+    const content = await manager.readVersion(list[0]!);
+    expect(content).toBe('# hi');
+  });
+});

package/src/doc/audioMapping.ts

@@ -112,16 +112,55 @@ function flattenForAudio(blocks: Block[]): Block[] {
   return result;
 }
 
-/** Info about an MP3 file found in the container. */
+/**
+ * Info about a narration audio file found in the container.
+ *
+ * Originally limited to MP3, this now also covers WebM/MP4/Ogg/M4A
+ * audio files that the browser recorder writes into `audio/`. The type
+ * name is retained for backwards compatibility with the surrounding
+ * matching logic; the data shape is identical regardless of codec.
+ */
 interface Mp3Info {
-  /** Path in the container (e.g., "images/c23n-issaquah-highlands-intro.mp3") */
+  /** Path in the container (e.g., "audio/narration-2026.webm"). */
   path: string;
-  /** Filename without path (e.g., "c23n-issaquah-highlands-intro.mp3") */
+  /** Filename without path (e.g., "narration-2026.webm"). */
   filename: string;
-  /** Parsed timing data (if .timing.json exists) */
+  /** Parsed timing data (if .timing.json exists). */
   timing: AudioTimingData | null;
 }
 
+/**
+ * File extensions that unambiguously denote audio anywhere in the
+ * container. These predate the recorder feature.
+ */
+const AUDIO_ONLY_EXTENSIONS = ['.mp3', '.wav', '.ogg', '.m4a'];
+
+/**
+ * Extensions that could be audio or video — `.webm` and `.mp4` are the
+ * containers `MediaRecorder` produces for browser-side narration, but
+ * they're also used for video clips. Only treat them as narration when
+ * they live under the `audio/` directory the recorder writes to.
+ */
+const AMBIGUOUS_EXTENSIONS = ['.webm', '.mp4'];
+
+function isNarrationAudioPath(path: string): boolean {
+  const lower = path.toLowerCase();
+  if (AUDIO_ONLY_EXTENSIONS.some((ext) => lower.endsWith(ext))) return true;
+  if (AMBIGUOUS_EXTENSIONS.some((ext) => lower.endsWith(ext))) {
+    return lower.startsWith('audio/');
+  }
+  return false;
+}
+
+/** Strip a known narration audio extension from a filename. */
+function stripAudioExtension(filename: string): string {
+  const lower = filename.toLowerCase();
+  for (const ext of [...AUDIO_ONLY_EXTENSIONS, ...AMBIGUOUS_EXTENSIONS]) {
+    if (lower.endsWith(ext)) return filename.slice(0, -ext.length);
+  }
+  return filename;
+}
+
 // ── Core Functions ───────────────────────────────────────────────────
 
 /**
@@ -142,12 +181,17 @@ function parseConsolidatedTiming(data: ArrayBuffer): Record<string, AudioTimingD
 }
 
 /**
- * Discover all MP3 files in a container and load their timing data.
- * Checks for a consolidated timing.json first, then falls back to per-file .timing.json.
+ * Discover all narration audio files in a container and load their
+ * timing data. Covers historical `.mp3`/`.wav`/`.ogg`/`.m4a` files
+ * anywhere in the container plus `.webm`/`.mp4` files under `audio/`
+ * (the destination the browser recorder writes to).
+ *
+ * Checks for a consolidated timing.json first, then falls back to
+ * per-file `.timing.json` sidecars.
  */
 async function discoverMp3s(container: ContentContainer): Promise<Mp3Info[]> {
   const files = await container.listFiles();
-  const mp3Files = files.filter((f) => f.path.endsWith('.mp3'));
+  const audioFiles = files.filter((f) => isNarrationAudioPath(f.path));
   const results: Mp3Info[] = [];
 
   // Try to load consolidated timing.json
@@ -157,15 +201,15 @@ async function discoverMp3s(container: ContentContainer): Promise<Mp3Info[]> {
     consolidatedSections = parseConsolidatedTiming(consolidatedData);
   }
 
-  for (const file of mp3Files) {
+  for (const file of audioFiles) {
     const filename = file.path.split('/').pop() ?? file.path;
     let timing: AudioTimingData | null = null;
 
     // Try consolidated timing first: match section name from filename
     if (consolidatedSections) {
-      const mp3Base = filename.replace(/\.mp3$/, '');
+      const audioBase = stripAudioExtension(filename);
       for (const [sectionName, sectionTiming] of Object.entries(consolidatedSections)) {
-        if (mp3Base.endsWith(`-${sectionName}`)) {
+        if (audioBase.endsWith(`-${sectionName}`)) {
           timing = sectionTiming;
           break;
         }
@@ -259,7 +303,7 @@ function autoMatchBlocks(
       // Fallback: filename-based matching
       if (score < MIN_CONTENT_SIMILARITY && block.title) {
         const titleSlug = slugify(block.title);
-        const fileSlug = slugify(mp3.filename.replace(/\.mp3$/, ''));
+        const fileSlug = slugify(stripAudioExtension(mp3.filename));
         // Check if the title slug appears in the filename slug
         if (fileSlug.includes(titleSlug) && titleSlug.length >= 3) {
           score = Math.max(score, MIN_FILENAME_SIMILARITY + 0.1);

package/src/doc/getLayers.ts

@@ -34,7 +34,7 @@ import type { ViewportConfig } from '../schemas/Viewport.js';
 import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
 import { createTemplateContext, isTemplateBlock } from '../schemas/BlockTemplates.js';
 import { DEFAULT_THEME } from '../schemas/themeLibrary.js';
-import { templateRegistry } from './templates/index.js';
+import { templateRegistry, resolveTemplateName } from './templates/index.js';
 import { expandPersistentLayers } from './templates/persistentLayers.js';
 
 // ============================================
@@ -98,29 +98,40 @@ export function getLayers(block: DocBlock, context: RenderContext = {}): Layer[]
     return injectPersistentLayers(existingLayers, block, context);
   }
 
-  // 2. Template path: look up and call the template function
-  if (isTemplateBlock(block) && block.template in templateRegistry) {
-    const templateName = block.template as keyof typeof templateRegistry;
-    const templateCtx = createTemplateContext(theme, blockIndex, totalBlocks, viewport);
-    let layers: Layer[];
-    try {
-      // Each registry entry accepts its specific TemplateBlock variant; the
-      // discriminated union guarantees the shapes match at runtime.
-      const templateFn = templateRegistry[templateName] as (
-        input: TemplateBlock,
-        ctx: TemplateContext,
-      ) => Layer[];
-      layers = templateFn(block, templateCtx);
-      if (!Array.isArray(layers)) {
-        console.error(`Template ${templateName} did not return an array, got:`, typeof layers);
+  // 2. Template path: look up and call the template function.
+  //
+  // Resolve through TEMPLATE_ALIASES so legacy ids (`titleBlock`,
+  // `quoteBlock`, `mapBlock`, `listBlock`) hit the registry by their
+  // canonical short names. Without this the block-section path renders
+  // an empty SVG card: `hasTemplate()` accepts the alias (so
+  // `isAnnotatedBlock` returns true and the card wrapper renders), but
+  // a raw `block.template in templateRegistry` check below misses it
+  // and the layer list comes back empty.
+  if (isTemplateBlock(block)) {
+    const resolved = resolveTemplateName(block.template);
+    if (resolved in templateRegistry) {
+      const templateName = resolved as keyof typeof templateRegistry;
+      const templateCtx = createTemplateContext(theme, blockIndex, totalBlocks, viewport);
+      let layers: Layer[];
+      try {
+        // Each registry entry accepts its specific TemplateBlock variant; the
+        // discriminated union guarantees the shapes match at runtime.
+        const templateFn = templateRegistry[templateName] as (
+          input: TemplateBlock,
+          ctx: TemplateContext,
+        ) => Layer[];
+        layers = templateFn(block, templateCtx);
+        if (!Array.isArray(layers)) {
+          console.error(`Template ${templateName} did not return an array, got:`, typeof layers);
+          layers = [];
+        }
+      } catch (err: unknown) {
+        console.error(`Error expanding template ${templateName}:`, err);
         layers = [];
       }
-    } catch (err: unknown) {
-      console.error(`Error expanding template ${templateName}:`, err);
-      layers = [];
-    }
 
-    return injectPersistentLayers(layers, block, context);
+      return injectPersistentLayers(layers, block, context);
+    }
   }
 
   // 3. Fallback: no layers and no known template

package/src/doc/markdownToDoc.ts

@@ -28,10 +28,11 @@ import type {
   MarkdownBlockNode,
   MarkdownHeading,
   MarkdownNode,
-  MarkdownImage,
+  HtmlNode,
 } from '../markdown/types.js';
 import { extractPlainText } from '../markdown/utils.js';
 import { estimateReadingTime } from '../timing/readingTime.js';
+import { resolveTemplateName } from './templates/index.js';
 
 // ============================================
 // Options
@@ -152,9 +153,13 @@ export function markdownToDoc(markdownDoc: MarkdownDocument, options?: MarkdownT
   function makeBlock(heading: MarkdownHeading | null): Block {
     const id = heading ? generateId(heading, headingIndex++) : 'preamble';
 
-    // Use template from annotation if present, otherwise fall back to default
+    // Use template from annotation if present, otherwise fall back to default.
+    // Legacy template ids (e.g. `titleBlock`) are normalized to their canonical
+    // short form (`title`) so downstream comparisons can rely on the new names
+    // without sprinkling alias resolution everywhere.
     const annotation = heading?.templateAnnotation;
-    const template = annotation?.template ?? (heading ? defaultTemplate : undefined);
+    const rawTemplate = annotation?.template ?? (heading ? defaultTemplate : undefined);
+    const template = rawTemplate != null ? resolveTemplateName(rawTemplate) : undefined;
 
     // Extract heading text so templates (e.g. sectionHeader) that expect a
     // `title` property receive it without having to reach into sourceHeading.
@@ -434,12 +439,45 @@ function splitIntoSentences(text: string): string[] {
   return merged;
 }
 
+interface ImageRef {
+  url: string;
+  alt?: string;
+}
+
 /**
- * Walk a MarkdownNode tree depth-first to find the first image node.
- * Returns the MarkdownImage or undefined if none found.
+ * Walk a parsed HTML sub-tree depth-first for an `<img>` with a `src`.
+ * Used to surface images that the WYSIWYG editor serialized as raw HTML
+ * (e.g. when an image was resized — markdown's `![alt](url)` shorthand
+ * has no width syntax, so resized images round-trip as `<img src width>`).
  */
-function findFirstImage(node: MarkdownNode): MarkdownImage | undefined {
-  if (node.type === 'image') return node as MarkdownImage;
+function findFirstHtmlImage(nodes: HtmlNode[]): ImageRef | undefined {
+  for (const node of nodes) {
+    if (node.type !== 'htmlElement') continue;
+    if (node.tagName === 'img' && node.attributes.src) {
+      return { url: node.attributes.src, alt: node.attributes.alt };
+    }
+    const nested = findFirstHtmlImage(node.children);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+/**
+ * Walk a MarkdownNode tree depth-first to find the first image reference,
+ * whether expressed as a markdown image node or a raw HTML `<img>` tag.
+ */
+function findFirstImage(node: MarkdownNode): ImageRef | undefined {
+  if (node.type === 'image') {
+    const img = node as { url: string; alt?: string };
+    return { url: img.url, alt: img.alt };
+  }
+  if (node.type === 'htmlBlock' || node.type === 'htmlInline') {
+    const html = node as { htmlChildren?: HtmlNode[] };
+    if (html.htmlChildren) {
+      const found = findFirstHtmlImage(html.htmlChildren);
+      if (found) return found;
+    }
+  }
   if ('children' in node && Array.isArray((node as { children?: unknown[] }).children)) {
     for (const child of (node as { children: MarkdownNode[] }).children) {
       const found = findFirstImage(child);