@bendyline/squisq 1.5.2 → 2.0.1

package/src/__tests__/docToMarkdownMedia.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown, stringifyMarkdown } from '../markdown/index';
+import { markdownToDoc } from '../doc/markdownToDoc';
+import { docToMarkdown } from '../doc/docToMarkdown';
+
+/** One full normalization cycle: md → doc → md. */
+function normalize(markdown: string): string {
+  return stringifyMarkdown(docToMarkdown(markdownToDoc(parseMarkdown(markdown))));
+}
+
+/** Byte-stability convention: stable after one normalization cycle. */
+function expectStable(markdown: string): string {
+  const once = normalize(markdown);
+  const twice = normalize(once);
+  expect(twice).toBe(once);
+  return once;
+}
+
+describe('docToMarkdown media round-trip', () => {
+  it('preserves a preamble document-anchored narration annotation', () => {
+    const md = `{[audio src=audio/narration-001.webm anchor=document]}\n\n# Hello\n\nBody text.\n`;
+    const once = expectStable(md);
+    expect(once).toContain('{[audio src=audio/narration-001.webm anchor=document]}');
+    // It must come back at the TOP (before the first heading) so reparsing
+    // yields documentMedia again.
+    expect(once.indexOf('{[audio')).toBeLessThan(once.indexOf('# Hello'));
+    const reparsed = markdownToDoc(parseMarkdown(once));
+    expect(reparsed.documentMedia?.length).toBe(1);
+    expect(reparsed.documentMedia![0].anchor).toBe('document');
+  });
+
+  it('preserves a block-level clip mid-contents with params', () => {
+    const md = `# Scene\n\nLead-in paragraph.\n\n{[video src=video/b.mp4 startAt=2 clipStart=1 clipEnd=9 spillover=true]}\n\nTrailing paragraph.\n`;
+    const once = expectStable(md);
+    expect(once).toContain(
+      '{[video src=video/b.mp4 startAt=2 clipStart=1 clipEnd=9 spillover=true]}',
+    );
+    // Original position: after the lead-in, before the trailing paragraph.
+    expect(once.indexOf('Lead-in')).toBeLessThan(once.indexOf('{[video'));
+    expect(once.indexOf('{[video')).toBeLessThan(once.indexOf('Trailing'));
+    const reparsed = markdownToDoc(parseMarkdown(once));
+    const withMedia = reparsed.blocks.find((b) => b.media && b.media.length > 0);
+    expect(withMedia?.media?.[0].clipStart).toBe(1);
+    expect(withMedia?.media?.[0].spillover).toBe(true);
+  });
+
+  it('preserves a document-anchored annotation authored inside a section body', () => {
+    const md = `# Section\n\nSome text.\n\n{[audio src=audio/full.mp3 anchor=document startAt=0:30]}\n\nMore text.\n`;
+    const once = expectStable(md);
+    // Raw text passthrough keeps the mm:ss time form byte-identical.
+    expect(once).toContain('{[audio src=audio/full.mp3 anchor=document startAt=0:30]}');
+    const reparsed = markdownToDoc(parseMarkdown(once));
+    expect(reparsed.documentMedia?.[0].startAt).toBe(30);
+  });
+
+  it('preserves quoted srcs with spaces', () => {
+    const md = `{[audio src="audio/my take.webm" anchor=document]}\n\n# Doc\n\nText.\n`;
+    const once = expectStable(md);
+    expect(once).toContain('src="audio/my take.webm"');
+    const reparsed = markdownToDoc(parseMarkdown(once));
+    expect(reparsed.documentMedia?.[0].src).toBe('audio/my take.webm');
+  });
+
+  it('emits programmatic doc clips (no origin) at the document top canonically', () => {
+    const doc = markdownToDoc(parseMarkdown('# Title\n\nBody.\n'));
+    doc.documentMedia = [
+      { id: 'clip-1', src: 'audio/take.webm', kind: 'audio', startAt: 0, anchor: 'document' },
+    ];
+    const md = stringifyMarkdown(docToMarkdown(doc));
+    expect(md).toContain('{[audio src=audio/take.webm anchor=document]}');
+    expect(md.indexOf('{[audio')).toBeLessThan(md.indexOf('# Title'));
+    // And the emission itself round-trips.
+    const reparsed = markdownToDoc(parseMarkdown(md));
+    expect(reparsed.documentMedia?.length).toBe(1);
+    expect(stringifyMarkdown(docToMarkdown(reparsed))).toBe(md);
+  });
+
+  it('leaves docs without media untouched', () => {
+    const md = `# Plain\n\nNothing to see.\n`;
+    const once = expectStable(md);
+    expect(once).not.toContain('{[audio');
+  });
+});

package/src/__tests__/drawingBlock.test.ts

@@ -90,9 +90,9 @@ describe('drawingBlock template', () => {
   });
 });
 
-describe('drawingBlock integration with getLayers', () => {
+describe('drawingBlock integration with materializeBlockLayers', () => {
   it('renders a drawing block through the template registry', async () => {
-    const { getLayers } = await import('../doc/getLayers.js');
+    const { materializeBlockLayers } = await import('../doc/materializeBlockLayers.js');
     const parent: Block = {
       id: 'sketch',
       startTime: 0,
@@ -116,7 +116,7 @@ describe('drawingBlock integration with getLayers', () => {
         shape('l', 'arrow', { from: 'ceo', to: 'dev' }, { title: 'manages' }),
       ],
     };
-    const layers = getLayers(parent, {});
+    const layers = materializeBlockLayers(parent, { persistentLayers: false }).layers;
     const types = new Set(layers.map((l: Layer) => l.type));
     expect(types.has('shape')).toBe(true);
     expect(types.has('path')).toBe(true);

package/src/__tests__/fixtures/asciiDiagramBattle.ts

@@ -0,0 +1,512 @@
+/**
+ * Battle-test corpus: a broad, category-organized set of AI-style ASCII
+ * diagrams, each with its intended semantics. Every fixture here is
+ * verified to (a) detect as a diagram, (b) parse to exactly these
+ * nodes/edges/containers, and (c) survive the render↔parse fixpoint
+ * byte-stably. See asciiDiagramBattle.test.ts.
+ *
+ * GENERATED by scratchpad/gen-battle-fixtures.mjs — edit there and re-run.
+ */
+
+export interface BattleDiagram {
+  name: string;
+  category: string;
+  art: string;
+  /** Expected node ids (order-independent). */
+  nodes: string[];
+  /** Expected edges: [source, target, label?, directed?]. directed defaults true. */
+  edges: Array<[string, string, (string | undefined)?, boolean?]>;
+  /** Expected containment: childId → containerId. */
+  containers?: Record<string, string>;
+}
+
+export const BATTLE_DIAGRAMS: BattleDiagram[] = [
+  {
+    name: 'linearEtl',
+    category: 'linear',
+    art: `┌─────────┐     ┌───────────┐     ┌──────────┐
+│ Extract │ ──> │ Transform │ ──> │   Load   │
+└─────────┘     └───────────┘     └──────────┘`,
+    nodes: ['extract', 'transform', 'load'],
+    edges: [
+      ['extract', 'transform'],
+      ['transform', 'load'],
+    ],
+  },
+  {
+    name: 'requestLifecycle',
+    category: 'linear',
+    art: `┌────────┐    ┌───────────────┐    ┌─────────┐    ┌──────────┐
+│ Client │───>│ Load Balancer │───>│   API   │───>│ Database │
+└────────┘    └───────────────┘    └─────────┘    └──────────┘`,
+    nodes: ['client', 'load-balancer', 'api', 'database'],
+    edges: [
+      ['client', 'load-balancer'],
+      ['load-balancer', 'api'],
+      ['api', 'database'],
+    ],
+  },
+  {
+    name: 'deployPipelineAscii',
+    category: 'linear',
+    art: `+-------+     +------+     +-------+     +--------+
+| Build | --> | Test | --> | Stage | --> | Deploy |
++-------+     +------+     +-------+     +--------+`,
+    nodes: ['build', 'test', 'stage', 'deploy'],
+    edges: [
+      ['build', 'test'],
+      ['test', 'stage'],
+      ['stage', 'deploy'],
+    ],
+  },
+  {
+    name: 'mlPipeline',
+    category: 'linear',
+    art: `┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
+│   Data   │──►│ Features │──►│  Train   │──►│  Model   │
+└──────────┘   └──────────┘   └────┬─────┘   └──────────┘
+                                   │ metrics
+                                   ▼
+                              ┌──────────┐
+                              │ Evaluate │
+                              └──────────┘`,
+    nodes: ['data', 'features', 'train', 'model', 'evaluate'],
+    edges: [
+      ['data', 'features'],
+      ['features', 'train'],
+      ['train', 'model'],
+      ['train', 'evaluate', 'metrics'],
+    ],
+  },
+  {
+    name: 'approvalFlow',
+    category: 'linear',
+    art: `┌─────────┐   ┌──────────┐   ┌──────────┐   ┌───────────┐
+│  Draft  │──►│  Review  │──►│ Approved │──►│ Published │
+└─────────┘   └──────────┘   └──────────┘   └───────────┘`,
+    nodes: ['draft', 'review', 'approved', 'published'],
+    edges: [
+      ['draft', 'review'],
+      ['review', 'approved'],
+      ['approved', 'published'],
+    ],
+  },
+  {
+    name: 'loadBalancerFanout',
+    category: 'fan-out',
+    art: `           ┌───────────────┐
+           │ Load Balancer │
+           └──┬──┬──┬──┬───┘
+       ┌──────┘  │  │  └──────┐
+       ▼         ▼  ▼         ▼
+    ┌──────┐┌──────┐┌──────┐┌──────┐
+    │ Web1 ││ Web2 ││ Web3 ││ Web4 │
+    └──────┘└──────┘└──────┘└──────┘`,
+    nodes: ['load-balancer', 'web1', 'web2', 'web3', 'web4'],
+    edges: [
+      ['load-balancer', 'web1'],
+      ['load-balancer', 'web2'],
+      ['load-balancer', 'web3'],
+      ['load-balancer', 'web4'],
+    ],
+  },
+  {
+    name: 'pubsubBroker',
+    category: 'fan-out',
+    art: `  ┌──────────┐      ┌──────────┐
+  │ Producer │─────►│  Broker  │
+  └──────────┘      └─┬──┬──┬──┘
+            ┌─────────┘  │  └─────────┐
+            ▼            ▼            ▼
+      ┌──────────┐┌──────────┐┌──────────┐
+      │   Sub1   ││   Sub2   ││   Sub3   │
+      └──────────┘└──────────┘└──────────┘`,
+    nodes: ['producer', 'broker', 'sub1', 'sub2', 'sub3'],
+    edges: [
+      ['producer', 'broker'],
+      ['broker', 'sub1'],
+      ['broker', 'sub2'],
+      ['broker', 'sub3'],
+    ],
+  },
+  {
+    name: 'collectorFanin',
+    category: 'fan-in',
+    art: `┌────┐  ┌────┐  ┌────┐
+│ S1 │  │ S2 │  │ S3 │
+└─┬──┘  └─┬──┘  └─┬──┘
+  │       │       │
+  ▼       ▼       ▼
+┌─────────────────────┐
+│      Collector      │
+└─────────────────────┘`,
+    nodes: ['s1', 's2', 's3', 'collector'],
+    edges: [
+      ['s1', 'collector'],
+      ['s2', 'collector'],
+      ['s3', 'collector'],
+    ],
+  },
+  {
+    name: 'sharedCache',
+    category: 'fan-in',
+    art: `┌──────────┐   ┌──────────┐   ┌──────────┐
+│ Service1 │   │ Service2 │   │ Service3 │
+└────┬─────┘   └────┬─────┘   └────┬─────┘
+     │              │              │
+     ▼              ▼              ▼
+┌────────────────────────────────────────┐
+│              Shared Cache              │
+└────────────────────────────────────────┘`,
+    nodes: ['service1', 'service2', 'service3', 'shared-cache'],
+    edges: [
+      ['service1', 'shared-cache'],
+      ['service2', 'shared-cache'],
+      ['service3', 'shared-cache'],
+    ],
+  },
+  {
+    name: 'diamond',
+    category: 'dag',
+    art: `       ┌───┐
+       │ A │
+       └┬─┬┘
+    ┌───┘ └───┐
+    ▼         ▼
+  ┌───┐     ┌───┐
+  │ B │     │ C │
+  └─┬─┘     └─┬─┘
+    └───┐ ┌───┘
+        ▼ ▼
+       ┌───┐
+       │ D │
+       └───┘`,
+    nodes: ['a', 'b', 'c', 'd'],
+    edges: [
+      ['a', 'b'],
+      ['a', 'c'],
+      ['b', 'd'],
+      ['c', 'd'],
+    ],
+  },
+  {
+    name: 'orgTree',
+    category: 'dag',
+    art: `              ┌───────┐
+              │  CEO  │
+              └───┬───┘
+        ┌─────────┴─────────┐
+        ▼                   ▼
+    ┌───────┐           ┌───────┐
+    │ VP-Eng│           │ VP-Ops│
+    └───┬───┘           └───────┘
+    ┌───┴───┐
+    ▼       ▼
+┌───────┐┌───────┐
+│  Dev  ││  QA   │
+└───────┘└───────┘`,
+    nodes: ['ceo', 'vp-eng', 'vp-ops', 'dev', 'qa'],
+    edges: [
+      ['ceo', 'vp-eng'],
+      ['ceo', 'vp-ops'],
+      ['vp-eng', 'dev'],
+      ['vp-eng', 'qa'],
+    ],
+  },
+  {
+    name: 'decisionTree',
+    category: 'dag',
+    art: `        ┌───────────┐
+        │  Check?   │
+        └──┬─────┬──┘
+           │     │
+           ▼     ▼
+    ┌────────┐ ┌────────┐
+    │ Accept │ │ Reject │
+    └────────┘ └────────┘`,
+    nodes: ['check', 'accept', 'reject'],
+    edges: [
+      ['check', 'accept'],
+      ['check', 'reject'],
+    ],
+  },
+  {
+    name: 'microservices',
+    category: 'dag',
+    art: `              ┌──────────────┐
+              │   Gateway    │
+              └──┬────┬────┬─┘
+      ┌──────────┘    │    └──────────┐
+      ▼               ▼               ▼
+┌──────────┐    ┌──────────┐    ┌──────────┐
+│  Users   │    │  Orders  │    │ Payments │
+└────┬─────┘    └────┬─────┘    └────┬─────┘
+     ▼               ▼               ▼
+┌──────────┐    ┌──────────┐    ┌──────────┐
+│ UsersDB  │    │ OrdersDB │    │  PayDB   │
+└──────────┘    └──────────┘    └──────────┘`,
+    nodes: ['gateway', 'users', 'orders', 'payments', 'usersdb', 'ordersdb', 'paydb'],
+    edges: [
+      ['gateway', 'users'],
+      ['gateway', 'orders'],
+      ['gateway', 'payments'],
+      ['users', 'usersdb'],
+      ['orders', 'ordersdb'],
+      ['payments', 'paydb'],
+    ],
+  },
+  {
+    name: 'layered',
+    category: 'dag',
+    art: `┌─────────────────────────────┐
+│      Presentation Layer     │
+└──────────────┬──────────────┘
+               ▼
+┌─────────────────────────────┐
+│       Business Layer        │
+└──────────────┬──────────────┘
+               ▼
+┌─────────────────────────────┐
+│         Data Layer          │
+└─────────────────────────────┘`,
+    nodes: ['presentation-layer', 'business-layer', 'data-layer'],
+    edges: [
+      ['presentation-layer', 'business-layer'],
+      ['business-layer', 'data-layer'],
+    ],
+  },
+  {
+    name: 'threeTier',
+    category: 'dag',
+    art: `┌──────────┐     ┌──────────┐     ┌──────────┐
+│ Browser  │────►│   App    │────►│    DB    │
+└──────────┘     └────┬─────┘     └──────────┘
+                      │
+                      ▼
+                 ┌──────────┐
+                 │  Cache   │
+                 └──────────┘`,
+    nodes: ['browser', 'app', 'db', 'cache'],
+    edges: [
+      ['browser', 'app'],
+      ['app', 'db'],
+      ['app', 'cache'],
+    ],
+  },
+  {
+    name: 'retryLoop',
+    category: 'cycle',
+    art: `┌─────────┐         ┌──────────┐
+│ Request │ ──────> │  Worker  │
+└─────────┘         └────┬─────┘
+     ▲                   │
+     └───────────────────┘`,
+    nodes: ['request', 'worker'],
+    edges: [
+      ['request', 'worker'],
+      ['worker', 'request'],
+    ],
+  },
+  {
+    name: 'stateMachine',
+    category: 'cycle',
+    art: `┌─────────┐          ┌─────────┐         ┌──────────┐
+│  Idle   │ ───────> │ Running │ ──────> │ Complete │
+└─────────┘          └────┬────┘         └──────────┘
+     ▲                    │
+     └────────────────────┘`,
+    nodes: ['idle', 'running', 'complete'],
+    edges: [
+      ['idle', 'running'],
+      ['running', 'complete'],
+      ['running', 'idle'],
+    ],
+  },
+  {
+    name: 'circuitBreaker',
+    category: 'cycle',
+    art: `              ┌──────────┐
+              │  Closed  │
+              └──┬─────┬─┘
+                 │     ▲
+     ┌───────────┘     │
+     ▼                 │
+┌──────────┐     ┌─────┴─────┐
+│   Open   │────►│ Half-Open │
+└──────────┘     └───────────┘`,
+    nodes: ['closed', 'open', 'half-open'],
+    edges: [
+      ['closed', 'open'],
+      ['open', 'half-open'],
+      ['half-open', 'closed'],
+    ],
+  },
+  {
+    name: 'fullMesh3',
+    category: 'many-to-many',
+    art: `              ┌───────┐
+              │ Alpha │
+              └──┬─┬──┘
+                 ▲ ▲
+     ┌───────────┘ │
+     │             └────────────┐
+     ▼                          ▼
+  ┌──────┐                  ┌───────┐
+  │ Beta ├◄────────────────►┤ Gamma │
+  └──────┘                  └───────┘`,
+    nodes: ['alpha', 'beta', 'gamma'],
+    edges: [
+      ['alpha', 'beta'],
+      ['beta', 'alpha'],
+      ['alpha', 'gamma'],
+      ['gamma', 'alpha'],
+      ['beta', 'gamma'],
+      ['gamma', 'beta'],
+    ],
+  },
+  {
+    name: 'bidirReplication',
+    category: 'edges',
+    art: `┌──────────┐               ┌──────────┐
+│ Primary  │ <───────────> │ Replica  │
+└──────────┘               └──────────┘`,
+    nodes: ['primary', 'replica'],
+    edges: [
+      ['primary', 'replica'],
+      ['replica', 'primary'],
+    ],
+  },
+  {
+    name: 'undirectedPair',
+    category: 'edges',
+    art: `┌────────┐          ┌────────┐
+│ NodeA  │──────────│ NodeB  │
+└────────┘          └────────┘`,
+    nodes: ['nodea', 'nodeb'],
+    edges: [['nodea', 'nodeb', undefined, false]],
+  },
+  {
+    name: 'labeledTyped',
+    category: 'labels',
+    art: `┌──────────┐              ┌──────────┐
+│   API    │ ─── reads ──►│ Database │
+└────┬─────┘              └──────────┘
+     │ writes
+     ▼
+┌──────────┐
+│  Cache   │
+└──────────┘`,
+    nodes: ['api', 'database', 'cache'],
+    edges: [
+      ['api', 'database', 'reads'],
+      ['api', 'cache', 'writes'],
+    ],
+  },
+  {
+    name: 'queueDlq',
+    category: 'labels',
+    art: `┌──────────┐     ┌──────────┐     ┌──────────┐
+│ Producer │────►│  Queue   │────►│ Consumer │
+└──────────┘     └────┬─────┘     └──────────┘
+                      │ on-fail
+                      ▼
+                 ┌──────────┐
+                 │   DLQ    │
+                 └──────────┘`,
+    nodes: ['producer', 'queue', 'consumer', 'dlq'],
+    edges: [
+      ['producer', 'queue'],
+      ['queue', 'consumer'],
+      ['queue', 'dlq', 'on-fail'],
+    ],
+  },
+  {
+    name: 'cqrs',
+    category: 'labels',
+    art: `┌──────────┐                    ┌──────────────┐
+│  Client  │─── command ───────►│ Write Model  │
+└────┬─────┘                    └──────┬───────┘
+     │ query                          │ events
+     ▼                                ▼
+┌──────────────┐                 ┌──────────────┐
+│  Read Model  │◄────────────────│ Event Store  │
+└──────────────┘                 └──────────────┘`,
+    nodes: ['client', 'write-model', 'read-model', 'event-store'],
+    edges: [
+      ['client', 'write-model', 'command'],
+      ['client', 'read-model', 'query'],
+      ['write-model', 'event-store', 'events'],
+      ['event-store', 'read-model'],
+    ],
+  },
+  {
+    name: 'multilineLabels',
+    category: 'labels',
+    art: `┌──────────────┐        ┌──────────────┐
+│ molen-kernel │        │ molen-client │
+│ headless sim │───────►│ three.js     │
+│ no DOM       │        │ WebGL        │
+└──────────────┘        └──────────────┘`,
+    nodes: ['molen-kernel', 'molen-client'],
+    edges: [['molen-kernel', 'molen-client']],
+  },
+  {
+    name: 'k8sCluster',
+    category: 'container',
+    art: `┌───────────── Kubernetes Cluster ─────────────┐
+│                                              │
+│  ┌─────────┐    ┌─────────┐    ┌─────────┐   │
+│  │  Pod A  │    │  Pod B  │    │  Pod C  │   │
+│  └─────────┘    └─────────┘    └─────────┘   │
+│                                              │
+└──────────────────────────────────────────────┘`,
+    nodes: ['kubernetes-cluster', 'pod-a', 'pod-b', 'pod-c'],
+    edges: [],
+    containers: {
+      'pod-a': 'kubernetes-cluster',
+      'pod-b': 'kubernetes-cluster',
+      'pod-c': 'kubernetes-cluster',
+    },
+  },
+  {
+    name: 'twoRegions',
+    category: 'container',
+    art: `┌──── Region US ─────┐   ┌──── Region EU ─────┐
+│                    │   │                    │
+│  ┌──────────────┐  │   │  ┌──────────────┐  │
+│  │  us-worker   │  │   │  │  eu-worker   │  │
+│  └──────────────┘  │   │  └──────────────┘  │
+│                    │   │                    │
+└────────────────────┘   └────────────────────┘`,
+    nodes: ['region-us', 'us-worker', 'region-eu', 'eu-worker'],
+    edges: [],
+    containers: { 'us-worker': 'region-us', 'eu-worker': 'region-eu' },
+  },
+  {
+    name: 'nestedTwoLevels',
+    category: 'container',
+    art: `┌─────────── Region ────────────┐
+│                               │
+│  ┌─────── Zone A ────────┐    │
+│  │                       │    │
+│  │  ┌──────────────┐     │    │
+│  │  │  Instance 1  │     │    │
+│  │  └──────────────┘     │    │
+│  │                       │    │
+│  └───────────────────────┘    │
+│                               │
+└───────────────────────────────┘`,
+    nodes: ['region', 'zone-a', 'instance-1'],
+    edges: [],
+    containers: { 'zone-a': 'region', 'instance-1': 'zone-a' },
+  },
+  {
+    name: 'roundedCorners',
+    category: 'style',
+    art: `╭─────────╮      ╭─────────╮
+│  Start  │ ───► │   End   │
+╰─────────╯      ╰─────────╯`,
+    nodes: ['start', 'end'],
+    edges: [['start', 'end']],
+  },
+];