@bendyline/squisq 1.2.2 → 1.4.0

package/src/__tests__/jsonForm.pointer.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect } from 'vitest';
+import {
+  toPointer,
+  pointerSegments,
+  getByPointer,
+  setByPointer,
+  resolveRef,
+} from '../jsonForm/index.js';
+
+describe('toPointer', () => {
+  it('keeps pointer-form paths intact', () => {
+    expect(toPointer('/a/b')).toBe('/a/b');
+    expect(toPointer('/0/1')).toBe('/0/1');
+  });
+  it('converts dotted-form to pointer-form', () => {
+    expect(toPointer('user.role')).toBe('/user/role');
+    expect(toPointer('a')).toBe('/a');
+  });
+  it('returns empty for root', () => {
+    expect(toPointer('')).toBe('');
+    expect(toPointer('/')).toBe('');
+  });
+  it('escapes ~ and / per RFC 6901', () => {
+    // dotted form does not allow / inside a segment; we test pointer-form decoding instead.
+    expect(pointerSegments('/a~1b')).toEqual(['a/b']);
+    expect(pointerSegments('/a~0b')).toEqual(['a~b']);
+  });
+});
+
+describe('getByPointer', () => {
+  const data = { user: { role: 'admin', tags: ['a', 'b'] } };
+  it('resolves nested object paths', () => {
+    expect(getByPointer(data, '/user/role')).toBe('admin');
+    expect(getByPointer(data, 'user.role')).toBe('admin');
+  });
+  it('resolves array indices', () => {
+    expect(getByPointer(data, '/user/tags/1')).toBe('b');
+  });
+  it('returns undefined for missing paths', () => {
+    expect(getByPointer(data, '/user/missing')).toBeUndefined();
+    expect(getByPointer(data, '/user/tags/9')).toBeUndefined();
+  });
+  it('returns the data itself for empty pointer', () => {
+    expect(getByPointer(data, '')).toBe(data);
+  });
+});
+
+describe('setByPointer', () => {
+  it('writes a leaf value immutably', () => {
+    const before = { a: 1, b: 2 };
+    const after = setByPointer(before, '/a', 99);
+    expect(after).toEqual({ a: 99, b: 2 });
+    expect(before).toEqual({ a: 1, b: 2 });
+  });
+  it('clones intermediate objects, shares siblings', () => {
+    const before = { x: { y: 1 }, z: { w: 2 } };
+    const after = setByPointer(before, '/x/y', 7);
+    expect(after).toEqual({ x: { y: 7 }, z: { w: 2 } });
+    expect(after.z).toBe(before.z);
+    expect(after.x).not.toBe(before.x);
+  });
+  it('writes into array indices', () => {
+    const before = { items: ['a', 'b', 'c'] };
+    const after = setByPointer(before, '/items/1', 'B');
+    expect(after.items).toEqual(['a', 'B', 'c']);
+    expect(after.items).not.toBe(before.items);
+  });
+  it('creates intermediate containers when missing', () => {
+    const after = setByPointer({}, '/a/b/0/c', 'leaf');
+    expect(after).toEqual({ a: { b: [{ c: 'leaf' }] } });
+  });
+  it('round-trips with getByPointer', () => {
+    const before = { a: { b: [{ c: 1 }, { c: 2 }] } };
+    const after = setByPointer(before, '/a/b/1/c', 42);
+    expect(getByPointer(after, '/a/b/1/c')).toBe(42);
+    expect(getByPointer(after, '/a/b/0/c')).toBe(1);
+  });
+});
+
+describe('resolveRef', () => {
+  const root = {
+    type: 'object',
+    properties: {
+      pet: { $ref: '#/$defs/Pet' },
+    },
+    $defs: {
+      Pet: { type: 'object', properties: { name: { type: 'string' } } },
+    },
+  };
+  it('returns referenced subschema for a local $ref', () => {
+    const ref = { $ref: '#/$defs/Pet' };
+    const resolved = resolveRef(ref, root);
+    expect(resolved?.type).toBe('object');
+    expect(resolved?.properties?.name?.type).toBe('string');
+  });
+  it('returns the schema unchanged when no $ref present', () => {
+    const node = { type: 'string' };
+    expect(resolveRef(node, root)).toBe(node);
+  });
+  it('returns undefined for unknown refs', () => {
+    expect(resolveRef({ $ref: '#/$defs/Nope' }, root)).toBeUndefined();
+  });
+});

package/src/__tests__/markdown.test.ts

@@ -33,6 +33,7 @@ import type {
   MarkdownLinkReference,
   MarkdownImageReference,
   MarkdownText,
+  MarkdownMention,
 } from '../markdown/index';
 
 // ============================================
@@ -151,6 +152,49 @@ describe('parseMarkdown / stringifyMarkdown', () => {
       expect(link.children[0]).toEqual({ type: 'text', value: 'Click here' });
     });
 
+    it('parses mentions from @[Name](scheme:id)', () => {
+      const doc = parse('Hey @[Leo](gezel:leo), take a look.');
+      const p = doc.children[0] as MarkdownParagraph;
+      const text0 = p.children[0] as MarkdownText;
+      expect(text0).toEqual({ type: 'text', value: 'Hey ' });
+      const mention = p.children[1] as MarkdownMention;
+      expect(mention).toEqual({
+        type: 'mention',
+        targetKind: 'gezel',
+        targetId: 'leo',
+        displayName: 'Leo',
+      });
+      const text2 = p.children[2] as MarkdownText;
+      expect(text2.value).toBe(', take a look.');
+    });
+
+    it('round-trips a mention back to markdown', () => {
+      // remark-stringify escapes `:` in link URLs that follow an `@` (to
+      // disambiguate from autolink syntax). The escape is idempotent —
+      // re-parsing `\:` produces the unescaped url, so the round-trip
+      // preserves the mention semantically even if the raw text changes
+      // on the first pass.
+      const input = 'Hey @[Leo](gezel:leo), ping @[Tess](gezel:tess) too.\n';
+      const once = stringifyMarkdown(parseMarkdown(input));
+      const twice = stringifyMarkdown(parseMarkdown(once));
+      expect(twice).toBe(once);
+      // Semantics are preserved: re-parsing yields mentions.
+      const doc = parseMarkdown(once) as MarkdownDocument;
+      const p = doc.children[0] as MarkdownParagraph;
+      const m1 = p.children.find((c) => c.type === 'mention') as MarkdownMention;
+      expect(m1.targetKind).toBe('gezel');
+      expect(m1.targetId).toBe('leo');
+      expect(m1.displayName).toBe('Leo');
+    });
+
+    it('does not collapse @ + link when the url has no scheme', () => {
+      const doc = parse('Cost @[100]($100)');
+      const p = doc.children[0] as MarkdownParagraph;
+      // "$100" doesn't match scheme:id because $ isn't a scheme character
+      // → stays as text("Cost @") + link
+      expect((p.children[1] as MarkdownLink).type).toBe('link');
+    });
+
     it('parses images', () => {
       const doc = parse('![Alt text](image.png "Image title")');
       const p = doc.children[0] as MarkdownParagraph;

package/src/__tests__/markdownIcons.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown, stringifyMarkdown } from '../markdown/index.js';
+
+describe('inline icon parsing', () => {
+  it('detects a unique bare {[name]} as an inlineIcon node', () => {
+    const doc = parseMarkdown('Hello {[github]} world');
+    const para = doc.children[0] as unknown as { children: Array<Record<string, unknown>> };
+    expect(para.children.length).toBe(3);
+    expect(para.children[0]).toMatchObject({ type: 'text', value: 'Hello ' });
+    expect(para.children[1]).toMatchObject({
+      type: 'inlineIcon',
+      token: 'github',
+      family: 'brands',
+      name: 'github',
+    });
+    expect(para.children[2]).toMatchObject({ type: 'text', value: ' world' });
+  });
+
+  it('resolves qualified tokens', () => {
+    const doc = parseMarkdown('Q: {[fa-solid:user]}');
+    const para = doc.children[0] as unknown as { children: Array<Record<string, unknown>> };
+    const icon = para.children.find((c) => c.type === 'inlineIcon');
+    expect(icon).toMatchObject({
+      type: 'inlineIcon',
+      token: 'fa-solid:user',
+      family: 'solid',
+      name: 'user',
+    });
+  });
+
+  it('leaves unknown / ambiguous tokens as literal text', () => {
+    // `user` is ambiguous (multiple families), `notathing` is unknown —
+    // both should round-trip as plain text so authors can write them.
+    const doc = parseMarkdown('a {[user]} b {[notathing]} c');
+    const para = doc.children[0] as unknown as { children: Array<Record<string, unknown>> };
+    expect(para.children).toHaveLength(1);
+    expect(para.children[0]).toMatchObject({
+      type: 'text',
+      value: 'a {[user]} b {[notathing]} c',
+    });
+  });
+
+  it('round-trips bare icons byte-stable through stringify', () => {
+    // Bare names contain no colon, so the serializer can re-emit them
+    // verbatim. (Qualified tokens like `fa-solid:user` get the colon
+    // escaped as `\:` for safety against remark-directive — that form
+    // re-parses to the same token, just isn't byte-stable.)
+    const src = 'Built with {[github]} and {[face-smile]}.';
+    expect(stringifyMarkdown(parseMarkdown(src)).trim()).toBe(src);
+  });
+
+  it('round-trips qualified icons semantically through stringify', () => {
+    // `{[fa-solid:user]}` may serialize as `{[fa-solid\:user]}` — both
+    // forms parse back to the same inlineIcon node, so we verify
+    // semantic equivalence rather than byte equality.
+    const src = 'Q: {[fa-solid:user]} end';
+    const round1 = stringifyMarkdown(parseMarkdown(src));
+    const reparsed = parseMarkdown(round1);
+    const para = reparsed.children[0] as unknown as { children: Array<Record<string, unknown>> };
+    const icon = para.children.find((c) => c.type === 'inlineIcon');
+    expect(icon).toMatchObject({
+      type: 'inlineIcon',
+      token: 'fa-solid:user',
+      family: 'solid',
+      name: 'user',
+    });
+  });
+});
+
+describe('inline icons inside headings', () => {
+  it('parses the trailing template annotation as the template, body icon as inlineIcon', () => {
+    const doc = parseMarkdown('# Repo {[github]} status {[sectionHeader]}\n');
+    const heading = doc.children[0] as unknown as {
+      type: string;
+      templateAnnotation?: { template?: string };
+      children: Array<Record<string, unknown>>;
+    };
+    expect(heading.type).toBe('heading');
+    expect(heading.templateAnnotation?.template).toBe('sectionHeader');
+    // Children should be: text('Repo '), inlineIcon(github), text(' status')
+    const icon = heading.children.find((c) => c.type === 'inlineIcon');
+    expect(icon).toMatchObject({ type: 'inlineIcon', name: 'github' });
+  });
+
+  it('round-trips heading template + inline icon', () => {
+    const src = '# Repo {[github]} status {[sectionHeader]}\n';
+    expect(stringifyMarkdown(parseMarkdown(src))).toBe(src);
+  });
+
+  it('round-trips a heading where the whole trailing annotation is an icon (not a template)', () => {
+    // `# Foo {[github]}` — `github` is a valid icon (not a known template),
+    // so the bare token should NOT be treated as a template annotation
+    // unless it also happens to be in the template registry. The parser
+    // is liberal here — `extractTemplateAnnotation` runs first and would
+    // capture `{[github]}` as a template annotation; we accept that as
+    // the documented precedence.
+    const src = '# Foo {[github]}\n';
+    const out = stringifyMarkdown(parseMarkdown(src));
+    // The annotation extraction happens first, so the round-trip is
+    // either `# Foo {[github]}` (when serialized back via template
+    // suffix) — verify the output still matches the source.
+    expect(out).toBe(src);
+  });
+});

package/src/__tests__/markdownToDoc.test.ts

@@ -142,12 +142,12 @@ describe('markdownToDoc', () => {
     const md = parseMarkdown('# Test');
     const doc = markdownToDoc(md, {
       articleId: 'custom-article',
-      defaultTemplate: 'titleBlock',
+      defaultTemplate: 'title',
       defaultDuration: 10,
     });
 
     expect(doc.articleId).toBe('custom-article');
-    expect(doc.blocks[0].template).toBe('titleBlock');
+    expect(doc.blocks[0].template).toBe('title');
     expect(doc.blocks[0].duration).toBe(10);
   });
 
@@ -363,11 +363,11 @@ describe('template annotation in markdownToDoc', () => {
   });
 
   it('nested headings preserve their own annotations', () => {
-    const input = '# Chapter {[titleBlock]}\n\nIntro\n\n## Section {[chart]}\n\nData';
+    const input = '# Chapter {[title]}\n\nIntro\n\n## Section {[chart]}\n\nData';
     const md = parseMarkdown(input);
     const doc = markdownToDoc(md);
 
-    expect(doc.blocks[0].template).toBe('titleBlock');
+    expect(doc.blocks[0].template).toBe('title');
     expect(doc.blocks[0].children).toHaveLength(1);
     expect(doc.blocks[0].children![0].template).toBe('chart');
   });
@@ -509,6 +509,21 @@ describe('auto cover block generation', () => {
     expect(doc.startBlock!.heroSrc).toBe('deep.png');
   });
 
+  it('picks raw HTML <img> as heroSrc (WYSIWYG resize case)', () => {
+    // The WYSIWYG editor serializes resized images as raw `<img src width>`
+    // because markdown shorthand has no width syntax. The cover scanner
+    // must see through that, or every resized image silently drops out
+    // of exports.
+    const md = parseMarkdown(
+      '# Title\n\n<img alt="resized" src="resized.jpg" width="194">\n\nText.',
+    );
+    const doc = markdownToDoc(md);
+
+    expect(doc.startBlock).toBeDefined();
+    expect(doc.startBlock!.heroSrc).toBe('resized.jpg');
+    expect(doc.startBlock!.heroAlt).toBe('resized');
+  });
+
   it('works without images (no heroSrc)', () => {
     const md = parseMarkdown('# Title\n\nPlain text, no images.');
     const doc = markdownToDoc(md);

package/src/__tests__/recommendTemplates.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest';
+import { parseMarkdown } from '../markdown/parse.js';
+import { profileBlockContents, recommendTemplatesForBlock } from '../recommend/templates.js';
+
+const ALL_TEMPLATES = [
+  'title',
+  'sectionHeader',
+  'statHighlight',
+  'quote',
+  'factCard',
+  'twoColumn',
+  'dateEvent',
+  'imageWithCaption',
+  'leftFeature',
+  'rightFeature',
+  'map',
+  'fullBleedQuote',
+  'list',
+  'photoGrid',
+  'definitionCard',
+  'comparisonBar',
+  'pullQuote',
+  'videoWithCaption',
+  'videoPullQuote',
+  'dataTable',
+];
+
+function profileOf(source: string) {
+  const doc = parseMarkdown(source);
+  return profileBlockContents(doc.children);
+}
+
+describe('profileBlockContents', () => {
+  it('returns an empty profile for no nodes', () => {
+    const p = profileBlockContents([]);
+    expect(p.wordCount).toBe(0);
+    expect(p.hasImage).toBe(false);
+    expect(p.hasVideo).toBe(false);
+  });
+
+  it('detects a single markdown image', () => {
+    const p = profileOf('![alt](https://example.com/a.png)');
+    expect(p.imageCount).toBe(1);
+    expect(p.hasImage).toBe(true);
+  });
+
+  it('detects an HTML <img> tag', () => {
+    const p = profileOf('<img src="a.png" alt="x" />');
+    expect(p.imageCount).toBe(1);
+    expect(p.hasImage).toBe(true);
+  });
+
+  it('detects a blockquote', () => {
+    const p = profileOf('> The mountain was calling me.');
+    expect(p.hasBlockquote).toBe(true);
+  });
+
+  it('detects a bullet list', () => {
+    const p = profileOf('- one\n- two\n- three');
+    expect(p.hasList).toBe(true);
+  });
+
+  it('detects a GFM table', () => {
+    const p = profileOf('| a | b |\n| --- | --- |\n| 1 | 2 |');
+    expect(p.hasTable).toBe(true);
+  });
+
+  it('detects a date string in body text', () => {
+    const p = profileOf('Construction began in July 1899.');
+    expect(p.hasDate).toBe(true);
+  });
+
+  it('detects an ISO date', () => {
+    const p = profileOf('Launched on 2024-03-15.');
+    expect(p.hasDate).toBe(true);
+  });
+
+  it('detects a prominent number paragraph', () => {
+    const p = profileOf('$2.3M raised');
+    expect(p.hasNumberHighlight).toBe(true);
+  });
+
+  it('detects a YouTube embed via link', () => {
+    const p = profileOf('[Watch](https://www.youtube.com/watch?v=abc)');
+    expect(p.hasVideo).toBe(true);
+  });
+
+  it('detects a <video> tag', () => {
+    const p = profileOf('<video src="x.mp4"></video>');
+    expect(p.hasVideo).toBe(true);
+  });
+
+  it('counts multiple images', () => {
+    const p = profileOf('![a](a.png)\n\n![b](b.png)\n\n![c](c.png)');
+    expect(p.imageCount).toBe(3);
+  });
+});
+
+describe('recommendTemplatesForBlock', () => {
+  it('falls back to universal defaults when nothing is detected', () => {
+    const profile = profileBlockContents([]);
+    const { recommended } = recommendTemplatesForBlock(profile, ALL_TEMPLATES);
+    expect(recommended).toEqual(['title', 'sectionHeader', 'factCard', 'twoColumn']);
+  });
+
+  it('keeps recommended ordering aligned with the input list', () => {
+    const profile = profileOf('![a](a.png)');
+    const { recommended } = recommendTemplatesForBlock(profile, ALL_TEMPLATES);
+    // imageWithCaption comes before leftFeature/rightFeature in ALL_TEMPLATES
+    expect(recommended.indexOf('imageWithCaption')).toBeLessThan(
+      recommended.indexOf('leftFeature'),
+    );
+  });
+
+  it('recommends image templates for blocks with one image (no photoGrid)', () => {
+    const profile = profileOf('![a](a.png)');
+    const { recommended } = recommendTemplatesForBlock(profile, ALL_TEMPLATES);
+    expect(recommended).toContain('imageWithCaption');
+    expect(recommended).toContain('leftFeature');
+    expect(recommended).toContain('rightFeature');
+    expect(recommended).not.toContain('photoGrid');
+  });
+
+  it('adds photoGrid when 2+ images present', () => {
+    const profile = profileOf('![a](a.png)\n\n![b](b.png)');
+    const { recommended } = recommendTemplatesForBlock(profile, ALL_TEMPLATES);
+    expect(recommended).toContain('photoGrid');
+  });
+
+  it('recommends quote templates for blocks with blockquotes', () => {
+    const profile = profileOf('> something memorable');
+    const { recommended } = recommendTemplatesForBlock(profile, ALL_TEMPLATES);
+    expect(recommended).toContain('quote');
+    expect(recommended).toContain('pullQuote');
+    expect(recommended).toContain('fullBleedQuote');
+  });
+
+  it('recommends dateEvent for blocks with date strings', () => {
+    const profile = profileOf('On March 5, 2024, the ribbon was cut.');
+    const { recommended } = recommendTemplatesForBlock(profile, ALL_TEMPLATES);
+    expect(recommended).toContain('dateEvent');
+  });
+
+  it('recommends statHighlight for blocks with prominent numbers', () => {
+    const profile = profileOf('$2.3M raised');
+    const { recommended } = recommendTemplatesForBlock(profile, ALL_TEMPLATES);
+    expect(recommended).toContain('statHighlight');
+  });
+
+  it('recommends dataTable + comparisonBar for blocks with tables', () => {
+    const profile = profileOf('| a | b |\n| --- | --- |\n| 1 | 2 |');
+    const { recommended } = recommendTemplatesForBlock(profile, ALL_TEMPLATES);
+    expect(recommended).toContain('dataTable');
+    expect(recommended).toContain('comparisonBar');
+  });
+
+  it('omits universal generics (factCard, twoColumn) when specific signal fires', () => {
+    const profile = profileOf('> something memorable');
+    const { recommended } = recommendTemplatesForBlock(profile, ALL_TEMPLATES);
+    // title + sectionHeader still come along, but factCard/twoColumn do not
+    expect(recommended).toContain('title');
+    expect(recommended).toContain('sectionHeader');
+    expect(recommended).not.toContain('factCard');
+    expect(recommended).not.toContain('twoColumn');
+  });
+
+  it('combines multiple signals additively', () => {
+    const profile = profileOf('![a](a.png)\n\n> a great line\n\n- alpha\n- beta');
+    const { recommended } = recommendTemplatesForBlock(profile, ALL_TEMPLATES);
+    expect(recommended).toContain('imageWithCaption');
+    expect(recommended).toContain('quote');
+    expect(recommended).toContain('list');
+  });
+
+  it('places unrecommended templates in the rest bucket', () => {
+    const profile = profileOf('![a](a.png)');
+    const { recommended, rest } = recommendTemplatesForBlock(profile, ALL_TEMPLATES);
+    expect(rest).toContain('map');
+    expect(rest).toContain('definitionCard');
+    // No template appears in both buckets
+    for (const name of recommended) expect(rest).not.toContain(name);
+  });
+});

package/src/__tests__/scopedContentContainer.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryContentContainer } from '../storage/ContentContainer';
+import { ScopedContentContainer, scopeContainer } from '../storage/ScopedContentContainer';
+
+const enc = (s: string) => new TextEncoder().encode(s);
+const dec = (b: ArrayBuffer | null) => (b ? new TextDecoder().decode(b) : null);
+
+describe('ScopedContentContainer', () => {
+  let parent: MemoryContentContainer;
+
+  beforeEach(() => {
+    parent = new MemoryContentContainer();
+  });
+
+  it('writeFile + readFile route through the prefix', async () => {
+    const scoped = scopeContainer(parent, 'image_files');
+    await scoped.writeFile('state.json', enc('{}'), 'application/json');
+
+    expect(dec(await parent.readFile('image_files/state.json'))).toBe('{}');
+    expect(dec(await scoped.readFile('state.json'))).toBe('{}');
+  });
+
+  it('exists + removeFile honor the prefix', async () => {
+    const scoped = scopeContainer(parent, 'image_files');
+    await scoped.writeFile('a.txt', enc('a'));
+    expect(await scoped.exists('a.txt')).toBe(true);
+    expect(await parent.exists('image_files/a.txt')).toBe(true);
+
+    await scoped.removeFile('a.txt');
+    expect(await scoped.exists('a.txt')).toBe(false);
+    expect(await parent.exists('image_files/a.txt')).toBe(false);
+  });
+
+  it('listFiles returns prefix-stripped paths and ignores siblings', async () => {
+    const scoped = scopeContainer(parent, 'image_files');
+    await parent.writeFile('outside.txt', enc('x'));
+    await parent.writeFile('image_files_sibling/peek.txt', enc('y')); // not in scope
+    await scoped.writeFile('a.txt', enc('1'));
+    await scoped.writeFile('sub/b.txt', enc('2'));
+
+    const list = await scoped.listFiles();
+    const paths = list.map((e) => e.path).sort();
+    expect(paths).toEqual(['a.txt', 'sub/b.txt']);
+  });
+
+  it('listFiles with prefix joins the scope prefix', async () => {
+    const scoped = scopeContainer(parent, 'sidecar');
+    await scoped.writeFile('assets/a.png', enc('a'));
+    await scoped.writeFile('assets/b.png', enc('b'));
+    await scoped.writeFile('state.json', enc('{}'));
+
+    const list = await scoped.listFiles('assets/');
+    expect(list.map((e) => e.path).sort()).toEqual(['assets/a.png', 'assets/b.png']);
+  });
+
+  it('nested scopes compose', async () => {
+    const a = scopeContainer(parent, 'a');
+    const ab = scopeContainer(a, 'b');
+    await ab.writeFile('c.txt', enc('hi'));
+    expect(dec(await parent.readFile('a/b/c.txt'))).toBe('hi');
+    expect(dec(await ab.readFile('c.txt'))).toBe('hi');
+  });
+
+  it('normalizes leading/trailing slashes in prefix and paths', async () => {
+    const scoped = scopeContainer(parent, '/sidecar/');
+    expect(scoped.prefix).toBe('sidecar');
+    await scoped.writeFile('/x.txt', enc('x'));
+    expect(dec(await parent.readFile('sidecar/x.txt'))).toBe('x');
+  });
+
+  it('rejects empty / dotted prefixes', () => {
+    expect(() => scopeContainer(parent, '')).toThrow();
+    expect(() => scopeContainer(parent, '/')).toThrow();
+    expect(() => scopeContainer(parent, 'a/../b')).toThrow();
+    expect(() => scopeContainer(parent, './a')).toThrow();
+  });
+
+  it('getDocumentPath / readDocument always return null', async () => {
+    const scoped = scopeContainer(parent, 'sidecar');
+    await scoped.writeFile('index.md', enc('# hi'));
+    expect(await scoped.getDocumentPath()).toBeNull();
+    expect(await scoped.readDocument()).toBeNull();
+  });
+
+  it('writeDocument throws', async () => {
+    const scoped = new ScopedContentContainer(parent, 'sidecar');
+    await expect(scoped.writeDocument()).rejects.toThrow();
+  });
+});

package/src/__tests__/slideshowGenerator.test.ts

@@ -34,7 +34,7 @@ describe('generateSlideshow', () => {
     expect(doc.articleId).toBe('Mount Rainier');
     const first = doc.blocks[0];
     if (isTemplateBlock(first)) {
-      expect(first.template).toBe('titleBlock');
+      expect(first.template).toBe('title');
     }
   });
 

package/src/__tests__/surface.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import {
+  applySurface,
+  DARK_SURFACE,
+  DEFAULT_THEME,
+  LIGHT_SURFACE,
+  type SurfaceScheme,
+} from '../schemas/index.js';
+
+describe('SurfaceScheme', () => {
+  it('LIGHT_SURFACE and DARK_SURFACE expose the full field set', () => {
+    for (const s of [LIGHT_SURFACE, DARK_SURFACE]) {
+      expect(typeof s.id).toBe('string');
+      expect(typeof s.background).toBe('string');
+      expect(typeof s.backgroundLight).toBe('string');
+      expect(typeof s.text).toBe('string');
+      expect(typeof s.textMuted).toBe('string');
+    }
+  });
+});
+
+describe('applySurface', () => {
+  it('overlays surface fields onto a theme', () => {
+    const out = applySurface(DEFAULT_THEME, LIGHT_SURFACE);
+    expect(out.colors.background).toBe(LIGHT_SURFACE.background);
+    expect(out.colors.backgroundLight).toBe(LIGHT_SURFACE.backgroundLight);
+    expect(out.colors.text).toBe(LIGHT_SURFACE.text);
+    expect(out.colors.textMuted).toBe(LIGHT_SURFACE.textMuted);
+  });
+
+  it('leaves editorial colors (primary, highlight, warning) untouched', () => {
+    const out = applySurface(DEFAULT_THEME, DARK_SURFACE);
+    expect(out.colors.primary).toBe(DEFAULT_THEME.colors.primary);
+    expect(out.colors.secondary).toBe(DEFAULT_THEME.colors.secondary);
+    expect(out.colors.highlight).toBe(DEFAULT_THEME.colors.highlight);
+    expect(out.colors.warning).toBe(DEFAULT_THEME.colors.warning);
+  });
+
+  it('leaves typography, style, renderStyle, colorSchemes untouched', () => {
+    const out = applySurface(DEFAULT_THEME, LIGHT_SURFACE);
+    expect(out.typography).toBe(DEFAULT_THEME.typography);
+    expect(out.style).toBe(DEFAULT_THEME.style);
+    expect(out.renderStyle).toBe(DEFAULT_THEME.renderStyle);
+    expect(out.colorSchemes).toBe(DEFAULT_THEME.colorSchemes);
+  });
+
+  it('returns a new theme (does not mutate the base)', () => {
+    const frozenTheme = DEFAULT_THEME;
+    const originalBg = frozenTheme.colors.background;
+    const out = applySurface(frozenTheme, DARK_SURFACE);
+    expect(out).not.toBe(frozenTheme);
+    expect(out.colors).not.toBe(frozenTheme.colors);
+    expect(frozenTheme.colors.background).toBe(originalBg);
+  });
+
+  it('accepts custom SurfaceScheme objects', () => {
+    const custom: SurfaceScheme = {
+      id: 'parchment',
+      background: '#f4ecd8',
+      backgroundLight: '#e8dfc4',
+      text: '#2b2b2b',
+      textMuted: '#6b6b6b',
+    };
+    const out = applySurface(DEFAULT_THEME, custom);
+    expect(out.colors.background).toBe('#f4ecd8');
+    expect(out.colors.textMuted).toBe('#6b6b6b');
+  });
+});