@bendyline/squisq 1.5.2 → 2.0.1

package/src/__tests__/scopedContentContainer.test.ts

@@ -73,6 +73,26 @@ describe('ScopedContentContainer', () => {
     expect(() => scopeContainer(parent, '/')).toThrow();
     expect(() => scopeContainer(parent, 'a/../b')).toThrow();
     expect(() => scopeContainer(parent, './a')).toThrow();
+    expect(() => scopeContainer(parent, 'a\\b')).toThrow(/forward slashes/);
+  });
+
+  it('rejects traversal, dot segments, and backslashes on every file operation', async () => {
+    const scoped = scopeContainer(parent, 'sidecar');
+    for (const badPath of ['../escape.txt', 'a/../../escape.txt', './same.txt', 'a\\b.txt']) {
+      expect(() => scoped.readFile(badPath)).toThrow();
+      expect(() => scoped.writeFile(badPath, enc('x'))).toThrow();
+      expect(() => scoped.removeFile(badPath)).toThrow();
+      expect(() => scoped.exists(badPath)).toThrow();
+      await expect(scoped.listFiles(badPath)).rejects.toThrow();
+    }
+    expect(await parent.listFiles()).toEqual([]);
+  });
+
+  it('normalizes repeated and leading slashes without changing scope', async () => {
+    const scoped = scopeContainer(parent, '//sidecar//nested//');
+    expect(scoped.prefix).toBe('sidecar/nested');
+    await scoped.writeFile('//assets//x.txt', enc('x'));
+    expect(dec(await parent.readFile('sidecar/nested/assets/x.txt'))).toBe('x');
   });
 
   it('getDocumentPath / readDocument always return null', async () => {

package/src/__tests__/shapeGeometry.test.ts

@@ -69,9 +69,21 @@ describe('connectorPath', () => {
     expect(connectorPath('orthogonal', a, b)).toBe('M 0 0 L 50 0 L 50 50 L 100 50');
   });
 
+  it('orthogonal routing approaches top/bottom ports vertically', () => {
+    expect(
+      connectorPath('orthogonal', { port: 'bottom', x: 80, y: 60 }, { port: 'top', x: 20, y: 140 }),
+    ).toBe('M 80 60 L 80 100 L 20 100 L 20 140');
+  });
+
   it('curved is a cubic bezier', () => {
     expect(connectorPath('curved', a, b).startsWith('M 0 0 C')).toBe(true);
   });
+
+  it('curved routing follows the endpoint port directions', () => {
+    expect(
+      connectorPath('curved', { port: 'bottom', x: 80, y: 60 }, { port: 'top', x: 20, y: 140 }),
+    ).toBe('M 80 60 C 80 110, 20 90, 20 140');
+  });
 });
 
 describe('clipEndpoints', () => {

package/src/__tests__/templateAnnotationParse.test.ts

@@ -11,6 +11,16 @@ function getHeading(md: string) {
 }
 
 describe('Template annotation in Heading parse path', () => {
+  it('extracts and round-trips an empty annotation without leaving literal heading text', () => {
+    const source = '## Getting Started {[]}';
+    const heading = getHeading(source);
+
+    expect(heading.templateAnnotation).toEqual({});
+    expect(heading.children).toHaveLength(1);
+    expect(heading.children[0]).toMatchObject({ type: 'text', value: 'Getting Started' });
+    expect(stringifyMarkdown(parseMarkdown(source)).trim()).toBe(source);
+  });
+
   it('parseMarkdown extracts {[template]} from a heading', () => {
     const md = '## Getting Started {[comparisonBar]}';
     const doc = parseMarkdown(md);

package/src/__tests__/templateInputs.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { parseMarkdown } from '../markdown/parse.js';
+import { deriveTemplateInputs } from '../doc/templateInputs.js';
+
+function statInputs(heading: string, body: string): Record<string, unknown> | null {
+  return deriveTemplateInputs('statHighlight', heading, parseMarkdown(body).children);
+}
+
+describe('statHighlight template input derivation', () => {
+  it('uses a leading bold metric as the hero stat', () => {
+    expect(
+      statInputs('The Big Number', '**42%** of teams prefer visual blocks over raw slides.'),
+    ).toEqual({
+      stat: '42%',
+      description: 'of teams prefer visual blocks over raw slides.',
+    });
+  });
+
+  it('accepts an explicitly bold small integer', () => {
+    expect(statInputs('Answer Count', '**42** answers were submitted')).toEqual({
+      stat: '42',
+      description: 'answers were submitted',
+    });
+  });
+
+  it('promotes only the metric when the bold run contains a longer phrase', () => {
+    expect(statInputs('Revenue', '**Revenue grew 42%** year over year')).toEqual({
+      stat: '42%',
+      description: 'Revenue grew year over year',
+    });
+  });
+
+  it('drops an inline separator between the metric and description', () => {
+    expect(
+      statInputs('The Big Number', '**42%** — The percentage of developers who prefer it.'),
+    ).toEqual({
+      stat: '42%',
+      description: 'The percentage of developers who prefer it.',
+    });
+  });
+
+  it('preserves a stat-looking heading for existing documents', () => {
+    expect(statInputs('89%', 'of customers recommend it')).toEqual({
+      stat: '89%',
+      description: 'of customers recommend it',
+    });
+  });
+
+  it('extracts an unformatted body metric for automatic templates', () => {
+    expect(statInputs('Funding', '$2.3M raised')).toEqual({
+      stat: '$2.3M',
+      description: 'raised',
+    });
+  });
+
+  it('does not let a year in a structural heading eclipse the body metric', () => {
+    expect(statInputs('2024 Results', '42% of teams reached their goal')).toEqual({
+      stat: '42%',
+      description: 'of teams reached their goal',
+    });
+  });
+
+  it('retains the historical fallback when no metric can be found', () => {
+    expect(statInputs('A Result', 'Supporting context')).toEqual({
+      stat: 'A Result',
+      description: 'Supporting context',
+    });
+  });
+});

package/src/__tests__/templateMetadata.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { templateRegistry, TEMPLATE_METADATA, TEMPLATE_ALIASES } from '../doc/templates/index';
+import { templateRegistry, TEMPLATE_METADATA } from '../doc/templates/index';
+import { TEMPLATE_ALIASES } from '../doc/templates/templateNames';
 
 describe('TEMPLATE_METADATA', () => {
   it('stays exactly 1:1 with templateRegistry (same ids)', () => {

package/src/__tests__/templates.test.ts

@@ -1,6 +1,5 @@
 import { describe, it, expect } from 'vitest';
 import {
-  expandTemplateBlock,
   expandDocBlocks,
   getAvailableTemplates,
   hasTemplate,
@@ -10,11 +9,41 @@ import {
   VIEWPORT_PRESETS,
 } from '../doc/templates/index';
 import type { TemplateBlock } from '../schemas/BlockTemplates';
-import type { TextLayer } from '../schemas/Doc';
-import { getLayers } from '../doc/getLayers';
+import type { Block, Layer, TextLayer } from '../schemas/Doc';
+import type { RuntimeTemplateRegistry } from '../doc/templates/index';
+import { materializeBlockLayersWithRuntime } from '../doc/materializeBlockLayers';
+import { materializeLayers } from './materializeTestUtils';
 import { markdownToDoc } from '../doc/markdownToDoc';
 import { parseMarkdown } from '../markdown/parse';
 
+function materializeTemplateForTest(
+  block: TemplateBlock,
+  context: ReturnType<typeof createTemplateContext>,
+  registry: RuntimeTemplateRegistry = templateRegistry as unknown as RuntimeTemplateRegistry,
+): Block {
+  const { layers } = materializeBlockLayersWithRuntime(
+    block,
+    {
+      theme: context.theme,
+      viewport: context.viewport,
+      persistentLayers: false,
+      blockIndex: context.blockIndex,
+      totalBlocks: context.totalBlocks,
+      failureMode: 'empty',
+    },
+    { registry, templateContext: context, applyRenderStyle: false },
+  );
+  return {
+    id: block.id,
+    startTime: 0,
+    duration: block.duration,
+    audioSegment: block.audioSegment,
+    ...(layers.length > 0 ? { layers } : {}),
+    transition: block.transition,
+    template: block.template,
+  };
+}
+
 describe('templateRegistry', () => {
   it('contains all expected templates', () => {
     const expected = [
@@ -66,7 +95,7 @@ describe('hasTemplate', () => {
   });
 });
 
-describe('expandTemplateBlock', () => {
+describe('canonical template materialization', () => {
   it('expands titleSlide template into layers', () => {
     const block: TemplateBlock = {
       template: 'title',
@@ -77,7 +106,7 @@ describe('expandTemplateBlock', () => {
       subtitle: 'Test Subtitle',
     };
     const context = createTemplateContext(DEFAULT_THEME, 0, 5, VIEWPORT_PRESETS.landscape);
-    const result = expandTemplateBlock(block, context);
+    const result = materializeTemplateForTest(block, context);
 
     expect(result.id).toBe('title-1');
     expect(result.duration).toBe(10);
@@ -97,7 +126,7 @@ describe('expandTemplateBlock', () => {
       body: 'I love building software platforms.',
     };
     const context = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
-    const result = expandTemplateBlock(block, context);
+    const result = materializeTemplateForTest(block, context);
     const layers = result.layers ?? [];
     const imageLayer = layers.find((l) => l.type === 'image');
     expect(imageLayer).toBeDefined();
@@ -130,7 +159,7 @@ describe('expandTemplateBlock', () => {
       title: 'Sized',
     };
     const context = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
-    const result = expandTemplateBlock(block, context);
+    const result = materializeTemplateForTest(block, context);
     const imageLayer = (result.layers ?? []).find((l) => l.type === 'image');
     expect(imageLayer).toBeDefined();
     expect((imageLayer!.content as { fit?: string }).fit).toBe('contain');
@@ -153,7 +182,7 @@ describe('expandTemplateBlock', () => {
       body: 'A list of things.',
     };
     const context = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
-    const result = expandTemplateBlock(block, context);
+    const result = materializeTemplateForTest(block, context);
     const layers = result.layers ?? [];
     const imageLayer = layers.find((l) => l.type === 'image');
     expect(imageLayer).toBeDefined();
@@ -179,7 +208,7 @@ describe('expandTemplateBlock', () => {
       description: 'drop in salmon',
     };
     const context = createTemplateContext(DEFAULT_THEME, 0, 5, VIEWPORT_PRESETS.landscape);
-    const result = expandTemplateBlock(block, context);
+    const result = materializeTemplateForTest(block, context);
 
     expect((result.layers ?? []).length).toBeGreaterThan(0);
     // Should have at least a shape background + text layers
@@ -195,7 +224,7 @@ describe('expandTemplateBlock', () => {
       audioSegment: 0,
     } as unknown as TemplateBlock;
     const context = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
-    const result = expandTemplateBlock(block, context);
+    const result = materializeTemplateForTest(block, context);
     expect(result.layers ?? []).toEqual([]);
   });
 
@@ -241,7 +270,7 @@ describe('expandTemplateBlock', () => {
         leftValue: 50,
         rightValue: 50,
       } as unknown as TemplateBlock;
-      const result = expandTemplateBlock(block, context);
+      const result = materializeTemplateForTest(block, context);
       expect(result.id).toBe(`test-${name}`);
       expect(result.layers ?? []).toBeInstanceOf(Array);
       // Each template should produce at least 1 layer
@@ -265,7 +294,7 @@ describe('expandTemplateBlock', () => {
     };
 
     const context = createTemplateContext(DEFAULT_THEME, 0, 10, VIEWPORT_PRESETS.landscape);
-    const result = expandTemplateBlock(block, context);
+    const result = materializeTemplateForTest(block, context);
     const layers = result.layers ?? [];
     const captionLayer = layers.find(
       (layer): layer is TextLayer => layer.type === 'text' && layer.id === 'caption',
@@ -301,10 +330,10 @@ describe('expandTemplateBlock', () => {
     };
 
     const context = createTemplateContext(DEFAULT_THEME, 0, 10, VIEWPORT_PRESETS.landscape);
-    const imageCaption = (expandTemplateBlock(imageBlock, context).layers ?? []).find(
+    const imageCaption = (materializeTemplateForTest(imageBlock, context).layers ?? []).find(
       (layer): layer is TextLayer => layer.type === 'text' && layer.id === 'caption',
     );
-    const videoCaption = (expandTemplateBlock(videoBlock, context).layers ?? []).find(
+    const videoCaption = (materializeTemplateForTest(videoBlock, context).layers ?? []).find(
       (layer): layer is TextLayer => layer.type === 'text' && layer.id === 'caption',
     );
 
@@ -370,6 +399,85 @@ describe('expandDocBlocks', () => {
     expect(result[0].startTime).toBe(0);
   });
 
+  it('never mutates or aliases raw blocks and persistent layers', () => {
+    const rawLayer: Layer = {
+      type: 'shape',
+      id: 'raw-shape',
+      content: { shape: 'rect', fill: '#112233' },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    };
+    const rawBlock: Block = {
+      id: 'raw',
+      startTime: 99,
+      duration: 6,
+      audioSegment: 0,
+      layers: [rawLayer],
+    };
+    const persistentLayer: Layer = {
+      type: 'shape',
+      id: 'persistent',
+      content: { shape: 'rect', fill: '#445566' },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    };
+    const beforeBlock = JSON.stringify(rawBlock);
+    const beforePersistent = JSON.stringify(persistentLayer);
+
+    const [expanded] = expandDocBlocks([rawBlock], {
+      persistentLayers: { bottomLayers: [persistentLayer] },
+      audioSegments: [{ startTime: 10, duration: 6 }],
+    });
+
+    expect(JSON.stringify(rawBlock)).toBe(beforeBlock);
+    expect(JSON.stringify(persistentLayer)).toBe(beforePersistent);
+    expect(expanded).not.toBe(rawBlock);
+    expect(expanded.layers?.[0]).not.toBe(persistentLayer);
+    expect(expanded.layers?.[1]).not.toBe(rawLayer);
+
+    (expanded.layers?.[0] as Layer & { content: { fill: string } }).content.fill = '#ffffff';
+    expect(JSON.stringify(persistentLayer)).toBe(beforePersistent);
+    expect(expandDocBlocks([rawBlock])[0].layers).toHaveLength(1);
+  });
+
+  it('protects template inputs from mutating registry implementations', () => {
+    const source: TemplateBlock = {
+      template: 'title',
+      id: 'title-safe',
+      duration: 5,
+      audioSegment: 0,
+      title: 'Original',
+    };
+    const sharedLayer: Layer = {
+      type: 'shape',
+      id: 'shared-layer',
+      content: { shape: 'rect', fill: '#112233' },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    };
+    const registry: RuntimeTemplateRegistry = {
+      title: (input) => {
+        (input as { title: string }).title = 'Mutated';
+        return [sharedLayer];
+      },
+    };
+    const first = materializeTemplateForTest(
+      source,
+      createTemplateContext(DEFAULT_THEME, 0, 1),
+      registry,
+    );
+    const second = materializeTemplateForTest(
+      source,
+      createTemplateContext(DEFAULT_THEME, 0, 1),
+      registry,
+    );
+    expect(source.title).toBe('Original');
+    expect(first.layers?.[0]).not.toBe(sharedLayer);
+    expect(first.layers?.[0]).not.toBe(second.layers?.[0]);
+    (first.layers?.[0] as Layer & { content: { fill: string } }).content.fill = '#ffffff';
+    expect((sharedLayer as Layer & { content: { fill: string } }).content.fill).toBe('#112233');
+    expect((second.layers?.[0] as Layer & { content: { fill: string } }).content.fill).toBe(
+      '#112233',
+    );
+  });
+
   it('supports landscape and portrait viewports', () => {
     const blocks: TemplateBlock[] = [
       { template: 'title', id: 'title-1', duration: 5, audioSegment: 0, title: 'Test' },
@@ -533,7 +641,7 @@ describe('DEFAULT_THEME', () => {
   });
 });
 
-describe('inline-param coercion → getLayers', () => {
+describe('inline-param coercion → materializeBlockLayers', () => {
   function firstBlock(md: string) {
     return markdownToDoc(parseMarkdown(md), { generateCoverBlock: false }).blocks[0];
   }
@@ -547,7 +655,7 @@ describe('inline-param coercion → getLayers', () => {
       mapStyle: 'road',
     });
 
-    const layers = getLayers(block, {});
+    const layers = materializeLayers(block, {});
     const mapLayer = layers.find((l) => l.type === 'map');
     expect(mapLayer).toBeDefined();
     // Coerced center/zoom flow into the map layer's content — not empty strings.
@@ -558,7 +666,7 @@ describe('inline-param coercion → getLayers', () => {
 
   it('renders a twoColumn from pure-inline labeled-pair annotation', () => {
     const block = firstBlock('# Coffee {[twoColumn left="Espresso|Bold" right="Filter|Smooth"]}\n');
-    const layers = getLayers(block, {});
+    const layers = materializeLayers(block, {});
     // Guard requires both labels — a non-empty layer set proves coercion worked.
     expect(layers.length).toBeGreaterThan(0);
     const texts = layers
@@ -572,6 +680,24 @@ describe('inline-param coercion → getLayers', () => {
   });
 });
 
+describe('shared template materialization', () => {
+  it('keeps on-demand and timed expansion layer output in lockstep', () => {
+    const block: TemplateBlock = {
+      template: 'title',
+      id: 'shared-title',
+      duration: 7,
+      audioSegment: 0,
+      title: 'One materializer',
+      subtitle: 'Two orchestration modes',
+    };
+
+    const onDemand = materializeLayers(block, { theme: DEFAULT_THEME });
+    const [expanded] = expandDocBlocks([block], { theme: DEFAULT_THEME });
+
+    expect(expanded.layers).toEqual(onDemand);
+  });
+});
+
 describe('VIEWPORT_PRESETS', () => {
   it('has landscape and portrait presets', () => {
     expect(VIEWPORT_PRESETS).toHaveProperty('landscape');

package/src/__tests__/themeCompile.test.ts

@@ -6,7 +6,8 @@ import {
   STARTER_THEME,
   deriveColorPalette,
 } from '../schemas/themeCompile.js';
-import { registerTheme, unregisterTheme, getRegisteredThemes } from '../schemas/Theme.js';
+import { createThemeRegistry } from '../schemas/Theme.js';
+import type { Theme } from '../schemas/Theme.js';
 import { resolveTheme, DEFAULT_THEME, THEMES } from '../schemas/themeLibrary.js';
 import { resolveFontFamily } from '../schemas/fontStacks.js';
 
@@ -132,46 +133,72 @@ describe('parseTheme / serializeTheme round-trip', () => {
   });
 });
 
-describe('registerTheme / resolveTheme', () => {
-  it('registered theme takes precedence over built-in with same id', () => {
+describe('caller-owned theme registries', () => {
+  it('an explicit registry can override a built-in without process-global leakage', () => {
     const overlay = compileTheme({
       id: 'standard',
       name: 'Standard Override',
       seedColors: { primary: '#ff0000' },
     });
-    registerTheme(overlay);
-    try {
-      const resolved = resolveTheme('standard');
-      expect(resolved.name).toBe('Standard Override');
-      expect(resolved.colors.primary).toBe('#ff0000');
-    } finally {
-      unregisterTheme('standard');
-    }
-    // After cleanup, built-in is restored
+    const registry = createThemeRegistry([overlay]);
+    const resolved = resolveTheme('standard', registry);
+    expect(resolved.name).toBe('Standard Override');
+    expect(resolved.colors.primary).toBe('#ff0000');
     expect(resolveTheme('standard').name).toBe('Standard Light');
   });
 
-  it('registered custom-id theme is resolvable via Doc.themeId', () => {
+  it('resolves a custom id only through the registry that owns it', () => {
     const custom = compileTheme({
       id: 'custom-test-1',
       name: 'Custom Test One',
       seedColors: { primary: '#00aabb' },
     });
-    registerTheme(custom);
-    try {
-      const resolved = resolveTheme('custom-test-1');
-      expect(resolved.id).toBe('custom-test-1');
-      expect(resolved.name).toBe('Custom Test One');
-      expect(getRegisteredThemes().some((t) => t.id === 'custom-test-1')).toBe(true);
-    } finally {
-      unregisterTheme('custom-test-1');
-    }
+    const registry = createThemeRegistry([custom]);
+    expect(resolveTheme('custom-test-1', registry).name).toBe('Custom Test One');
+    expect(resolveTheme('custom-test-1')).toBe(DEFAULT_THEME);
+    expect(registry.list().map((theme) => theme.id)).toContain('custom-test-1');
   });
 
   it('resolveTheme falls back to default for unknown ids', () => {
     expect(resolveTheme('nonexistent-theme')).toBe(DEFAULT_THEME);
     expect(resolveTheme(undefined)).toBe(DEFAULT_THEME);
   });
+
+  it('validates and stores an immutable snapshot', () => {
+    const registry = createThemeRegistry();
+    const source = compileTheme({
+      id: 'isolated-theme',
+      name: 'Isolated',
+      seedColors: { primary: '#336699' },
+    });
+    registry.register(source);
+    source.name = 'Changed later';
+    source.colors.primary = '#ffffff';
+
+    const stored = registry.get('isolated-theme')!;
+    expect(stored.name).toBe('Isolated');
+    expect(stored.colors.primary).toBe('#336699');
+    expect(Object.isFrozen(stored)).toBe(true);
+    expect(Object.isFrozen(stored.colors)).toBe(true);
+    expect(() => registry.register({ id: 'invalid' } as Theme)).toThrow(/invalid theme/i);
+  });
+
+  it('supports caller-owned registries with isolated state', () => {
+    const source = compileTheme({
+      id: 'tenant-theme',
+      name: 'Tenant',
+      seedColors: { primary: '#123456' },
+    });
+    const tenantA = createThemeRegistry([source]);
+    const tenantB = createThemeRegistry();
+    expect(tenantA.get('tenant-theme')?.name).toBe('Tenant');
+    expect(tenantB.get('tenant-theme')).toBeUndefined();
+  });
+
+  it('freezes built-ins so lookup ergonomics do not expose mutable global state', () => {
+    expect(Object.isFrozen(THEMES)).toBe(true);
+    expect(Object.isFrozen(resolveTheme('cinematic'))).toBe(true);
+  });
 });
 
 describe('FontFamily resolution', () => {