@bendyline/squisq-editor-react 1.6.2 → 2.0.0

package/src/__tests__/imageEditModalContract.test.tsx

@@ -0,0 +1,119 @@
+/** @vitest-environment jsdom */
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ContentContainer } from '@bendyline/squisq/storage';
+import { MemoryContentContainer } from '@bendyline/squisq/storage';
+import type { MediaProvider } from '@bendyline/squisq/schemas';
+import { useEditorContext } from '../EditorContext';
+
+const imageEditorProps: Array<{
+  filesContainer: ContentContainer;
+  saveFormat: 'png' | 'jpeg' | 'webp';
+  onExport: (blob: Blob, format: 'png' | 'jpeg' | 'webp') => void;
+}> = [];
+
+vi.mock('../ImageEditor', () => ({
+  ImageEditor: (props: (typeof imageEditorProps)[number]) => {
+    imageEditorProps.push(props);
+    return <div data-testid="image-editor-contract-stub" />;
+  },
+}));
+vi.mock('../RawEditor', () => ({ RawEditor: () => <div /> }));
+vi.mock('../WysiwygEditor', () => ({ WysiwygEditor: () => <div /> }));
+vi.mock('../PreviewPanel', () => ({ PreviewPanel: () => <div /> }));
+
+import { EditorShell } from '../EditorShell';
+
+function Trigger({ path }: { path: string }) {
+  const { openImageEdit } = useEditorContext();
+  return <button onClick={() => openImageEdit(path)}>edit</button>;
+}
+
+function provider(): MediaProvider {
+  return {
+    addMedia: vi.fn(async (name: string) => name),
+    resolveUrl: vi.fn(async (name: string) => `blob:${name}`),
+    listMedia: vi.fn(async () => []),
+    removeMedia: vi.fn(async () => {}),
+    dispose: vi.fn(),
+  };
+}
+
+beforeEach(() => {
+  imageEditorProps.length = 0;
+  if (typeof window.matchMedia !== 'function') {
+    Object.defineProperty(window, 'matchMedia', {
+      configurable: true,
+      value: () => ({ matches: false, addEventListener() {}, removeEventListener() {} }),
+    });
+  }
+});
+
+describe('ImageEditModal storage contract', () => {
+  it('writes JPEG bytes/MIME back to a .jpg path', async () => {
+    const mediaProvider = provider();
+    render(
+      <EditorShell
+        initialMarkdown="# image"
+        mediaProvider={mediaProvider}
+        toolbarSlotRight={<Trigger path="photo.jpg" />}
+      />,
+    );
+    fireEvent.click(screen.getByText('edit'));
+    await waitFor(() => expect(screen.getByTestId('image-editor-contract-stub')).toBeTruthy());
+    const props = imageEditorProps[imageEditorProps.length - 1]!;
+    expect(props.saveFormat).toBe('jpeg');
+    await act(async () => props.onExport(new Blob(['jpeg']), 'jpeg'));
+    expect(mediaProvider.addMedia).toHaveBeenCalledWith(
+      'photo.jpg',
+      expect.any(Blob),
+      'image/jpeg',
+    );
+  });
+
+  it('hashes sidecar paths so sanitized-name collisions remain separate', async () => {
+    const parent = new MemoryContentContainer();
+    const mediaProvider = provider();
+    const first = render(
+      <EditorShell
+        initialMarkdown="# image"
+        workspaceContainer={parent}
+        mediaProvider={mediaProvider}
+        toolbarSlotRight={<Trigger path="a/b.png" />}
+      />,
+    );
+    fireEvent.click(screen.getByText('edit'));
+    await waitFor(() => expect(imageEditorProps).toHaveLength(1));
+    const firstContainer = imageEditorProps[0].filesContainer;
+    first.unmount();
+
+    render(
+      <EditorShell
+        initialMarkdown="# image"
+        workspaceContainer={parent}
+        mediaProvider={mediaProvider}
+        toolbarSlotRight={<Trigger path="a_b.png" />}
+      />,
+    );
+    fireEvent.click(screen.getByText('edit'));
+    await waitFor(() => expect(imageEditorProps).toHaveLength(2));
+    const secondContainer = imageEditorProps[1].filesContainer;
+    await firstContainer.writeFile('sentinel', new Uint8Array([1]).buffer);
+    await secondContainer.writeFile('sentinel', new Uint8Array([2]).buffer);
+    const paths = (await parent.listFiles('.imageEdits')).map((entry) => entry.path);
+    expect(paths.filter((path) => path.endsWith('/sentinel'))).toHaveLength(2);
+  });
+
+  it('refuses unsupported source formats instead of writing mismatched bytes', async () => {
+    render(
+      <EditorShell
+        initialMarkdown="# image"
+        mediaProvider={provider()}
+        toolbarSlotRight={<Trigger path="animated.gif" />}
+      />,
+    );
+    fireEvent.click(screen.getByText('edit'));
+    await waitFor(() => expect(screen.getByText(/supports PNG, JPEG, and WebP/i)).toBeTruthy());
+    expect(screen.queryByTestId('image-editor-contract-stub')).toBeNull();
+  });
+});

package/src/__tests__/imageEditorShell.test.tsx

@@ -6,7 +6,7 @@
  * renders the toolbar / canvas / panels.
  */
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { render, screen, waitFor } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { MemoryContentContainer, scopeContainer } from '@bendyline/squisq/storage';
 import { writeImageEditDoc, createEmptyImageEditDoc } from '@bendyline/squisq/imageEdit';
 import { DARK_SURFACE } from '@bendyline/squisq/schemas';
@@ -56,6 +56,20 @@ describe('<ImageEditor>', () => {
     expect(screen.getByText(/loading image editor/i)).toBeTruthy();
   });
 
+  it('adds a centered shape layer from the Layers panel menu', async () => {
+    const parent = new MemoryContentContainer();
+    const sidecar = scopeContainer(parent, 'pic_files');
+    await writeImageEditDoc(sidecar, createEmptyImageEditDoc(640, 480));
+
+    render(<ImageEditor filesContainer={sidecar} />);
+    await waitFor(() => expect(screen.getByTestId('image-editor')).toBeTruthy());
+
+    fireEvent.click(screen.getByRole('button', { name: 'Add layer' }));
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Shape layer' }));
+
+    await waitFor(() => expect(screen.getByTitle('Rectangle')).toBeTruthy());
+  });
+
   it('applies an explicit dark surface to the editor chrome', async () => {
     const parent = new MemoryContentContainer();
     const sidecar = scopeContainer(parent, 'pic_files');

package/src/__tests__/jsonEditor.test.tsx

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import { useState } from 'react';
-import { fireEvent, render, screen } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import type { SquisqAnnotatedSchema } from '@bendyline/squisq/jsonForm';
 import { JsonEditor } from '../jsonEditor';
 
@@ -165,4 +165,59 @@ describe('JsonEditor', () => {
     fireEvent.change(input, { target: { value: 'changed' } });
     expect(onChange).not.toHaveBeenCalled();
   });
+
+  it('escapes object property names as RFC 6901 pointer segments', () => {
+    const schema: SquisqAnnotatedSchema = {
+      type: 'object',
+      properties: { 'a/b~c': { type: 'string', title: 'Odd key' } },
+    };
+    const onChange = vi.fn();
+    render(<Controlled schema={schema} initial={{ 'a/b~c': 'before' }} onValueChange={onChange} />);
+    fireEvent.change(screen.getByLabelText('Odd key'), { target: { value: 'after' } });
+    expect(onChange).toHaveBeenLastCalledWith({ 'a/b~c': 'after' });
+  });
+
+  it('associates labels/help/errors and reports validation after render', async () => {
+    const schema: SquisqAnnotatedSchema = {
+      type: 'object',
+      properties: {
+        title: { type: 'string', title: 'Title', description: 'A useful title' },
+      },
+    };
+    const onValidate = vi.fn();
+    render(
+      <JsonEditor
+        schema={schema}
+        value={{ title: '' }}
+        onChange={() => {}}
+        validate={() => [{ path: '/title', message: 'Required' }]}
+        onValidate={onValidate}
+      />,
+    );
+    const input = screen.getByLabelText('Title');
+    expect(input.getAttribute('aria-invalid')).toBe('true');
+    const described = input.getAttribute('aria-describedby') ?? '';
+    expect(described).toContain('-help');
+    expect(described).toContain('-error');
+    expect(screen.getByRole('alert').textContent).toBe('Required');
+    await waitFor(() =>
+      expect(onValidate).toHaveBeenCalledWith([{ path: '/title', message: 'Required' }]),
+    );
+  });
+
+  it('adds ARIA state and keyboard navigation to segmented/tabs controls', () => {
+    const schema: SquisqAnnotatedSchema = {
+      oneOf: [
+        { type: 'string', title: 'Text option' },
+        { type: 'number', title: 'Number option' },
+      ],
+      squisq: { control: 'tabs', label: 'Value type' },
+    };
+    render(<JsonEditor schema={schema} value="hello" onChange={() => {}} />);
+    const tabs = screen.getAllByRole('tab');
+    expect(tabs[0].getAttribute('aria-selected')).toBe('true');
+    fireEvent.keyDown(tabs[0], { key: 'ArrowRight' });
+    expect(tabs[1].getAttribute('aria-selected')).toBe('true');
+    expect(screen.getByRole('tabpanel')).toBeTruthy();
+  });
 });

package/src/__tests__/layersPanel.test.tsx

@@ -7,6 +7,8 @@ import type { ImageEditDoc } from '@bendyline/squisq/schemas';
 import { LayersPanel } from '../imageEditor/LayersPanel.js';
 import type { ImageEditorAction } from '../imageEditor/state.js';
 
+const ignoreAddLayer = () => {};
+
 function buildDoc(): ImageEditDoc {
   return {
     version: 1,
@@ -41,7 +43,14 @@ function buildDoc(): ImageEditDoc {
 describe('LayersPanel', () => {
   it('renders layers with the top of the SVG stack first', () => {
     const dispatch = vi.fn<(a: ImageEditorAction) => void>();
-    render(<LayersPanel doc={buildDoc()} selectedLayerId={null} dispatch={dispatch} />);
+    render(
+      <LayersPanel
+        doc={buildDoc()}
+        selectedLayerId={null}
+        dispatch={dispatch}
+        onAddLayer={ignoreAddLayer}
+      />,
+    );
     const items = screen.getAllByText(/Bottom|Middle|Top/);
     expect(items[0]?.textContent).toContain('Top');
     expect(items[items.length - 1]?.textContent).toContain('Bottom');
@@ -49,14 +58,60 @@ describe('LayersPanel', () => {
 
   it('clicking the layer name dispatches a select action', () => {
     const dispatch = vi.fn<(a: ImageEditorAction) => void>();
-    render(<LayersPanel doc={buildDoc()} selectedLayerId={null} dispatch={dispatch} />);
+    render(
+      <LayersPanel
+        doc={buildDoc()}
+        selectedLayerId={null}
+        dispatch={dispatch}
+        onAddLayer={ignoreAddLayer}
+      />,
+    );
     fireEvent.click(screen.getByText('Middle'));
     expect(dispatch).toHaveBeenCalledWith({ type: 'select', layerId: 'b' });
   });
 
+  it('exposes the full layer name as a tooltip when the row is truncated', () => {
+    const dispatch = vi.fn<(a: ImageEditorAction) => void>();
+    render(
+      <LayersPanel
+        doc={buildDoc()}
+        selectedLayerId={null}
+        dispatch={dispatch}
+        onAddLayer={ignoreAddLayer}
+      />,
+    );
+    expect(screen.getByTitle('Middle').textContent).toContain('Middle');
+  });
+
+  it('opens the add-layer menu and reports the selected layer kind', () => {
+    const dispatch = vi.fn<(a: ImageEditorAction) => void>();
+    const onAddLayer = vi.fn();
+    render(
+      <LayersPanel
+        doc={buildDoc()}
+        selectedLayerId={null}
+        dispatch={dispatch}
+        onAddLayer={onAddLayer}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: 'Add layer' }));
+    expect(screen.getByRole('menu')).toBeTruthy();
+    fireEvent.click(screen.getByRole('menuitem', { name: 'Text layer' }));
+    expect(onAddLayer).toHaveBeenCalledWith('text');
+    expect(screen.queryByRole('menu')).toBeNull();
+  });
+
   it('toggling visibility dispatches an update-layer action', () => {
     const dispatch = vi.fn<(a: ImageEditorAction) => void>();
-    render(<LayersPanel doc={buildDoc()} selectedLayerId={null} dispatch={dispatch} />);
+    render(
+      <LayersPanel
+        doc={buildDoc()}
+        selectedLayerId={null}
+        dispatch={dispatch}
+        onAddLayer={ignoreAddLayer}
+      />,
+    );
     // The "Hide layer" buttons exist for visible layers.
     const hideButtons = screen.getAllByRole('button', { name: 'Hide layer' });
     fireEvent.click(hideButtons[0]!); // top-most visible layer is 'b'
@@ -69,7 +124,14 @@ describe('LayersPanel', () => {
 
   it('move-up button is disabled at the top of the stack', () => {
     const dispatch = vi.fn<(a: ImageEditorAction) => void>();
-    render(<LayersPanel doc={buildDoc()} selectedLayerId={null} dispatch={dispatch} />);
+    render(
+      <LayersPanel
+        doc={buildDoc()}
+        selectedLayerId={null}
+        dispatch={dispatch}
+        onAddLayer={ignoreAddLayer}
+      />,
+    );
     const upButtons = screen.getAllByRole('button', { name: 'Move layer up' });
     // Visual order is c, b, a; layer 'c' is at the top of the stack and cannot move up.
     expect((upButtons[0] as HTMLButtonElement).disabled).toBe(true);
@@ -77,7 +139,14 @@ describe('LayersPanel', () => {
 
   it('delete button dispatches a remove-layer action', () => {
     const dispatch = vi.fn<(a: ImageEditorAction) => void>();
-    render(<LayersPanel doc={buildDoc()} selectedLayerId={null} dispatch={dispatch} />);
+    render(
+      <LayersPanel
+        doc={buildDoc()}
+        selectedLayerId={null}
+        dispatch={dispatch}
+        onAddLayer={ignoreAddLayer}
+      />,
+    );
     const delButtons = screen.getAllByRole('button', { name: 'Delete layer' });
     fireEvent.click(delButtons[0]!); // top of stack ('c')
     expect(dispatch).toHaveBeenCalledWith({ type: 'remove-layer', layerId: 'c' });
@@ -90,6 +159,7 @@ describe('LayersPanel', () => {
         doc={{ version: 1, canvas: { width: 1, height: 1 }, layers: [] }}
         selectedLayerId={null}
         dispatch={dispatch}
+        onAddLayer={ignoreAddLayer}
       />,
     );
     expect(screen.getByText(/no layers yet/i)).toBeTruthy();

package/src/__tests__/majorApiTypes.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import type { DiagramEdge, DiagramNode, EditorShellProps } from '../index';
+
+// @ts-expect-error React Flow-prefixed types were removed in the major API cleanup.
+import type { DiagramRFNode } from '../index';
+
+describe('major-version editor API types', () => {
+  it('uses implementation-neutral diagram names', () => {
+    const node: DiagramNode = { id: 'a', position: { x: 0, y: 0 }, data: { label: 'A' } };
+    const edge: DiagramEdge = { id: 'a-b', source: 'a', target: 'b' };
+    expect([node.id, edge.id]).toEqual(['a', 'a-b']);
+  });
+
+  it('does not accept the removed EditorShell container prop', () => {
+    const props: EditorShellProps = {
+      // @ts-expect-error Use workspaceContainer; container was removed.
+      container: null,
+    };
+    expect(props).toHaveProperty('container');
+  });
+
+  it('keeps the old type import absent', () => {
+    const legacy: DiagramRFNode | null = null;
+    expect(legacy).toBeNull();
+  });
+});

package/src/__tests__/mediaBinDrop.test.tsx

@@ -0,0 +1,90 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import type { MediaEntry, MediaProvider } from '@bendyline/squisq/schemas';
+import { MediaBin } from '../MediaBin.js';
+
+function createProvider(): { provider: MediaProvider; added: string[] } {
+  const entries: MediaEntry[] = [];
+  const added: string[] = [];
+  return {
+    added,
+    provider: {
+      async addMedia(name, data, mimeType) {
+        const relativePath = `attachments/${name}`;
+        added.push(relativePath);
+        entries.push({
+          name: relativePath,
+          mimeType,
+          size: data instanceof Blob ? data.size : data.byteLength,
+        });
+        return relativePath;
+      },
+      async resolveUrl(path) {
+        return `blob:${path}`;
+      },
+      async listMedia() {
+        return [...entries];
+      },
+      async removeMedia() {},
+      dispose() {},
+    },
+  };
+}
+
+function dataTransfer(files: File[], itemTypes: string[]) {
+  return {
+    files,
+    items: itemTypes.map((type) => ({ kind: 'file', type })),
+    types: ['Files'],
+    dropEffect: 'none',
+  };
+}
+
+describe('MediaBin image drop target', () => {
+  it('shows a drop affordance and uploads a dropped image through the normal callback', async () => {
+    const { provider, added } = createProvider();
+    const onMediaUploaded = vi.fn();
+    const image = new File([new Uint8Array([1, 2, 3])], 'photo.png', { type: 'image/png' });
+    Object.defineProperty(image, 'arrayBuffer', {
+      configurable: true,
+      value: async () => new Uint8Array([1, 2, 3]).buffer,
+    });
+
+    const { container } = render(
+      <MediaBin mediaProvider={provider} isDark onMediaUploaded={onMediaUploaded} />,
+    );
+    const bin = container.querySelector('.squisq-media-bin') as HTMLElement;
+    const transfer = dataTransfer([image], ['image/png']);
+    await screen.findByText('No files yet.');
+
+    fireEvent.dragEnter(bin, { dataTransfer: transfer });
+    expect(bin.classList.contains('squisq-media-bin--drop-active')).toBe(true);
+    expect(screen.getByText('Drop images here')).toBeTruthy();
+
+    fireEvent.drop(bin, { dataTransfer: transfer });
+
+    await waitFor(() => expect(added).toEqual(['attachments/photo.png']));
+    expect(onMediaUploaded).toHaveBeenCalledWith('attachments/photo.png', 'photo.png', 'image/png');
+    expect(await screen.findByText('photo.png')).toBeTruthy();
+    expect(screen.queryByText('Drop images here')).toBeNull();
+  });
+
+  it('does not activate or upload for a non-image file', async () => {
+    const { provider, added } = createProvider();
+    const text = new File(['notes'], 'notes.txt', { type: 'text/plain' });
+    const { container } = render(<MediaBin mediaProvider={provider} isDark={false} />);
+    const bin = container.querySelector('.squisq-media-bin') as HTMLElement;
+    const transfer = dataTransfer([text], ['text/plain']);
+    await screen.findByText('No files yet.');
+
+    fireEvent.dragEnter(bin, { dataTransfer: transfer });
+    fireEvent.drop(bin, { dataTransfer: transfer });
+
+    expect(bin.classList.contains('squisq-media-bin--drop-active')).toBe(false);
+    expect(screen.queryByText('Drop images here')).toBeNull();
+    await waitFor(() => expect(added).toEqual([]));
+  });
+});

package/src/__tests__/narrationSave.test.ts

@@ -0,0 +1,148 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { describe, expect, it } from 'vitest';
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import { markdownToDoc } from '@bendyline/squisq/doc';
+import {
+  buildNarrationScript,
+  parseNarrationTimingJson,
+  type NarrationAlignment,
+} from '@bendyline/squisq/narration';
+import {
+  insertNarrationPreamble,
+  narrationAnnotationLine,
+} from '../teleprompter/recording/insertPreamble';
+import { buildNarrationSavePlan } from '../teleprompter/recording/narrationSave';
+
+describe('insertNarrationPreamble', () => {
+  it('inserts at the top of a plain document', () => {
+    const next = insertNarrationPreamble('# Title\n\nBody.\n', 'audio/narration-1.webm', null);
+    expect(next.startsWith('{[audio src=audio/narration-1.webm anchor=document]}\n\n# Title')).toBe(
+      true,
+    );
+  });
+
+  it('inserts after the frontmatter fence', () => {
+    const source = '---\ntitle: Doc\n---\n\n# Title\n\nBody.\n';
+    const next = insertNarrationPreamble(source, 'audio/narration-1.webm', null);
+    const lines = next.split('\n');
+    expect(lines[2]).toBe('---');
+    expect(next).toContain(
+      '---\n\n{[audio src=audio/narration-1.webm anchor=document]}\n\n# Title',
+    );
+  });
+
+  it('replaces a previous take (and its camera line) on retake', () => {
+    const withTake = insertNarrationPreamble(
+      '# Title\n\nBody.\n',
+      'audio/narration-old.webm',
+      'video/narration-cam-old.webm',
+    );
+    expect(withTake).toContain('narration-old');
+    expect(withTake).toContain('<video src="video/narration-cam-old.webm"');
+
+    const retaken = insertNarrationPreamble(withTake, 'audio/narration-new.webm', null);
+    expect(retaken).not.toContain('narration-old');
+    expect(retaken).not.toContain('narration-cam-old');
+    expect(retaken).toContain('{[audio src=audio/narration-new.webm anchor=document]}');
+    // No duplicate annotations.
+    expect(retaken.match(/\{\[audio /g)?.length).toBe(1);
+  });
+
+  it('adds the camera companion as an inline video line', () => {
+    const next = insertNarrationPreamble(
+      '# Title\n\nBody.\n',
+      'audio/narration-1.webm',
+      'video/narration-cam-1.webm',
+    );
+    expect(next).toContain('{[audio src=audio/narration-1.webm anchor=document]}');
+    expect(next).toContain('<video src="video/narration-cam-1.webm" controls width="240"></video>');
+  });
+
+  it('quotes srcs with spaces', () => {
+    expect(narrationAnnotationLine('audio/my take.webm')).toBe(
+      '{[audio src="audio/my take.webm" anchor=document]}',
+    );
+  });
+
+  it('round-trips through markdownToDoc as documentMedia', () => {
+    const next = insertNarrationPreamble(
+      '---\ntitle: Doc\n---\n\n# Title\n\nBody.\n',
+      'audio/narration-1.webm',
+      null,
+    );
+    const doc = markdownToDoc(parseMarkdown(next));
+    expect(doc.documentMedia?.length).toBe(1);
+    expect(doc.documentMedia![0].src).toBe('audio/narration-1.webm');
+    expect(doc.documentMedia![0].anchor).toBe('document');
+  });
+});
+
+describe('buildNarrationSavePlan', () => {
+  const script = buildNarrationScript(
+    markdownToDoc(parseMarkdown('# One\n\nAlpha beta.\n\n# Two\n\nGamma delta.\n')),
+  );
+  const alignment: NarrationAlignment = {
+    words: script.tokens.map((_, i) => ({ tokenIndex: i, tSec: i * 0.4, interpolated: false })),
+    blocks: script.blocks.map((range, i) => ({
+      blockId: range.blockId,
+      blockIndex: i,
+      charStart: range.charStart,
+      charEnd: range.charEnd,
+      startSec: i * 5,
+      endSec: (i + 1) * 5,
+    })),
+    detectedSyllables: script.totalSyllables,
+    cost: 0,
+  };
+
+  it('produces recorder-convention paths and a v3 sidecar the parser accepts', () => {
+    const plan = buildNarrationSavePlan({
+      script,
+      alignment,
+      durationSec: 10,
+      audioExt: '.webm',
+      cameraExt: '.webm',
+      baseWpm: 150,
+      cameraOffsetSec: 0.02,
+    });
+    expect(plan.audioRelativeName).toMatch(/^audio\/narration-.*\.webm$/);
+    expect(plan.cameraRelativeName).toMatch(/^video\/narration-cam.*\.webm$/);
+    expect(plan.sidecarPathFor('audio/renamed.webm')).toBe('audio/renamed.webm.timing.json');
+
+    const parsed = parseNarrationTimingJson(JSON.stringify(plan.sidecarPayload));
+    expect(parsed).not.toBeNull();
+    expect(parsed!.blocks.length).toBe(script.blocks.length);
+    expect(parsed!.bookmarks.length).toBe(script.tokens.length);
+    expect(parsed!.cameraOffsetSec).toBeCloseTo(0.02, 6);
+  });
+
+  it('degrades to an empty-timing sidecar when alignment failed', () => {
+    const plan = buildNarrationSavePlan({
+      script,
+      alignment: null,
+      durationSec: 10,
+      audioExt: '.webm',
+      cameraExt: null,
+      baseWpm: 150,
+    });
+    expect(plan.cameraRelativeName).toBeNull();
+    expect(plan.sidecarPayload.blocks).toEqual([]);
+    expect(plan.sidecarPayload.bookmarks).toEqual([]);
+    expect(plan.sidecarPayload.sourceText).toBe(script.sourceText);
+  });
+
+  it('nextMarkdown composes the preamble from one snapshot', () => {
+    const plan = buildNarrationSavePlan({
+      script,
+      alignment,
+      durationSec: 10,
+      audioExt: '.webm',
+      cameraExt: null,
+      baseWpm: 150,
+    });
+    const next = plan.nextMarkdown('# One\n\nAlpha beta.\n', 'audio/narration-x.webm', null);
+    expect(next).toContain('{[audio src=audio/narration-x.webm anchor=document]}');
+  });
+});