@bendyline/squisq-editor-react 1.5.2 → 1.6.0

package/src/__tests__/tiptapBridge.test.ts

@@ -121,6 +121,20 @@ describe('markdownToTiptap', () => {
     expect(html).toContain('First');
   });
 
+  it('converts task lists to taskList/taskItem markup', () => {
+    const md = '- [ ] buy milk\n- [x] walk dog';
+    const html = markdownToTiptap(md);
+    expect(html).toContain('data-type="taskList"');
+    // Unchecked item carries no data-checked; checked item is marked true.
+    expect(html).toContain('<li data-type="taskItem"><p>buy milk</p></li>');
+    expect(html).toContain('<li data-type="taskItem" data-checked="true"><p>walk dog</p></li>');
+  });
+
+  it('treats [X] (uppercase) as checked', () => {
+    const html = markdownToTiptap('- [X] done');
+    expect(html).toContain('data-checked="true"');
+  });
+
   it('converts blockquotes', () => {
     const md = '> This is a quote';
     const html = markdownToTiptap(md);
@@ -260,6 +274,30 @@ describe('tiptapToMarkdown', () => {
     expect(md).toContain('2. Second');
   });
 
+  it('converts task lists, preserving checked state and text', () => {
+    // Mirrors the structure Tiptap's getHTML() emits for TaskItem:
+    // a <label> holding the checkbox chrome, then a content <div>.
+    const html =
+      '<ul data-type="taskList">' +
+      '<li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>buy milk</p></div></li>' +
+      '<li data-type="taskItem" data-checked="true"><label><input type="checkbox" checked="checked"><span></span></label><div><p>walk dog</p></div></li>' +
+      '</ul>';
+    const md = tiptapToMarkdown(html);
+    expect(md).toContain('- [ ] buy milk');
+    expect(md).toContain('- [x] walk dog');
+    // The unchecked item must NOT be promoted to checked.
+    expect(md).not.toContain('- [x] buy milk');
+  });
+
+  it('preserves a still-empty task item', () => {
+    const html =
+      '<ul data-type="taskList">' +
+      '<li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p></p></div></li>' +
+      '</ul>';
+    const md = tiptapToMarkdown(html);
+    expect(md).toContain('- [ ]');
+  });
+
   it('converts tables', () => {
     const html =
       '<table><thead><tr><th>Name</th><th>Age</th></tr></thead>' +
@@ -303,6 +341,30 @@ describe('tiptapToMarkdown', () => {
     expect(md).toContain('- First line  ');
     expect(md).toContain('  Second line');
   });
+
+  it('keeps a <video> nested in a list item (no silent drop)', () => {
+    const md = tiptapToMarkdown(
+      '<ol><li><p>Step</p><video src="video/clip.webm" width="480" controls=""></video></li></ol>',
+    );
+    expect(md).toContain('1. Step');
+    // The media survives, indented as a continuation of the list item.
+    expect(md).toContain('   <video src="video/clip.webm" controls width="480"></video>');
+  });
+
+  it('keeps an <audio> nested in a list item', () => {
+    const md = tiptapToMarkdown(
+      '<ul><li><p>Note</p><audio src="audio/take.webm" controls=""></audio></li></ul>',
+    );
+    expect(md).toContain('- Note');
+    expect(md).toContain('  <audio src="audio/take.webm" controls></audio>');
+  });
+
+  it('keeps a media-only list item (first tag takes the bullet)', () => {
+    const md = tiptapToMarkdown(
+      '<ul><li><video src="video/only.webm" controls=""></video></li></ul>',
+    );
+    expect(md).toContain('- <video src="video/only.webm" controls></video>');
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -360,4 +422,34 @@ describe('round-trip: markdownToTiptap → tiptapToMarkdown', () => {
     expect(result).toContain('1. First');
     expect(result).toContain('2. Second');
   });
+
+  it('preserves task lists with mixed checked state', () => {
+    const result = roundTrip('- [ ] buy milk\n- [x] walk dog');
+    expect(result).toContain('- [ ] buy milk');
+    expect(result).toContain('- [x] walk dog');
+    expect(result).not.toContain('- [x] buy milk');
+  });
+
+  it('preserves quoted template params with spaces', () => {
+    const result = roundTrip(
+      '## Gallery {[imageWithCaption src=photo.jpg caption="Beach at sunset"]}',
+    );
+    expect(result).toContain('{[imageWithCaption src=photo.jpg caption="Beach at sunset"]}');
+  });
+
+  it('preserves single-quoted template params', () => {
+    const result = roundTrip("## X {[quote text='A long caption']}");
+    expect(result).toContain("text='A long caption'");
+  });
+
+  it('preserves quoted Pandoc attribute values with spaces', () => {
+    const result = roundTrip('## X {#intro caption="hello world"}');
+    expect(result).toContain('{#intro caption="hello world"}');
+  });
+
+  it('preserves both annotation forms with quoted values on one heading', () => {
+    const result = roundTrip('## X {#a label="big plan"} {[quote text="She left"]}');
+    expect(result).toContain('{#a label="big plan"}');
+    expect(result).toContain('{[quote text="She left"]}');
+  });
 });

package/src/__tests__/tiptapBridgeConformance.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import { markdownToTiptap, tiptapToMarkdown } from '../tiptapBridge';
+
+/**
+ * tiptapBridge maintains a SECOND, regex-based markdown parser/serializer that
+ * must agree with core's `parseMarkdown` (see the "must stay in sync" note in
+ * tiptapBridge.ts). Comment-enforced parallel parsers drift silently; this test
+ * makes the agreement mechanical.
+ *
+ * The comparable artifact across the two representations (ProseMirror HTML vs.
+ * mdast) is the block-type sequence core's parser sees. If a bridge round-trip
+ * drops or mangles a construct core understands, the sequence changes and this
+ * test fails — surfacing drift in CI instead of in the editor.
+ */
+
+const blockSeq = (md: string): string[] => parseMarkdown(md).children.map((n) => n.type);
+const bridgeRoundTrip = (md: string): string => tiptapToMarkdown(markdownToTiptap(md));
+
+const CORPUS: Record<string, string> = {
+  heading: '# Title\n\n## Subtitle',
+  paragraph: 'Just a paragraph of text.',
+  bulletList: '- one\n- two\n- three',
+  orderedList: '1. first\n2. second\n3. third',
+  blockquote: '> a quote',
+  codeBlock: '```js\nconst x = 1;\n```',
+  table: '| a | b |\n| --- | --- |\n| 1 | 2 |',
+  inlineEmphasis: 'Some **bold** and *italic* and `code` text.',
+  link: 'A [link](https://example.com) inline.',
+  thematicBreak: 'before\n\n---\n\nafter',
+  mixed: '# Heading\n\nA paragraph.\n\n- a\n- b\n\n> quote\n\n```\ncode\n```',
+};
+
+describe('tiptapBridge ↔ core markdown parser conformance', () => {
+  for (const [name, md] of Object.entries(CORPUS)) {
+    it(`preserves the block-type sequence for: ${name}`, () => {
+      expect(blockSeq(bridgeRoundTrip(md))).toEqual(blockSeq(md));
+    });
+  }
+
+  it('round-trip is idempotent (a second pass changes nothing)', () => {
+    for (const md of Object.values(CORPUS)) {
+      const once = bridgeRoundTrip(md);
+      expect(bridgeRoundTrip(once)).toBe(once);
+    }
+  });
+});

package/src/__tests__/tooltip.test.tsx

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { TooltipLayer } from '../Tooltip';
+import { clampTooltipLeft } from '../tooltipPlacement';
+
+function rect(left: number, top: number, width: number, height: number): DOMRect {
+  return DOMRect.fromRect({ x: left, y: top, width, height });
+}
+
+const originalInnerWidth = Object.getOwnPropertyDescriptor(window, 'innerWidth');
+
+function setViewportWidth(width: number) {
+  Object.defineProperty(window, 'innerWidth', {
+    configurable: true,
+    value: width,
+  });
+}
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+  if (originalInnerWidth) {
+    Object.defineProperty(window, 'innerWidth', originalInnerWidth);
+  }
+});
+
+describe('TooltipLayer', () => {
+  it('clamps centered tooltip placement inside the viewport', () => {
+    expect(clampTooltipLeft(380, 120, 400)).toBe(272);
+    expect(clampTooltipLeft(20, 120, 400)).toBe(8);
+    expect(clampTooltipLeft(200, 120, 400)).toBe(140);
+  });
+
+  it('keeps a tooltip from spilling off the right edge', () => {
+    vi.useFakeTimers();
+    setViewportWidth(400);
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (
+      this: HTMLElement,
+    ) {
+      if (this.classList.contains('squisq-tooltip')) {
+        return rect(0, 0, 120, 28);
+      }
+      return rect(0, 0, 0, 0);
+    });
+
+    render(
+      <div>
+        <button type="button" data-tooltip="View options">
+          View
+        </button>
+        <TooltipLayer />
+      </div>,
+    );
+
+    const button = screen.getByRole('button', { name: 'View' });
+    Object.defineProperty(button, 'getBoundingClientRect', {
+      configurable: true,
+      value: () => rect(360, 10, 40, 32),
+    });
+
+    act(() => {
+      fireEvent.mouseOver(button);
+      vi.advanceTimersByTime(180);
+    });
+
+    const tooltip = screen.getByRole('tooltip');
+    expect(tooltip.textContent).toBe('View options');
+    expect(tooltip.style.left).toBe('272px');
+    expect(tooltip.style.visibility).toBe('visible');
+  });
+});

package/src/__tests__/transitionCatalog.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { isTransitionType } from '@bendyline/squisq/schemas';
+import {
+  TRANSITION_GROUPS,
+  TRANSITION_ENTRIES,
+  DIRECTION_OPTIONS,
+  findTransitionEntry,
+  transitionLabel,
+} from '../transitionCatalog';
+
+describe('transition catalog', () => {
+  it('every curated value is a real core transition type', () => {
+    for (const entry of TRANSITION_ENTRIES) {
+      expect(isTransitionType(entry.value), entry.value).toBe(true);
+    }
+  });
+
+  it('has no duplicate values across groups', () => {
+    const values = TRANSITION_ENTRIES.map((e) => e.value);
+    expect(new Set(values).size).toBe(values.length);
+  });
+
+  it('gives every entry a non-empty label', () => {
+    for (const entry of TRANSITION_ENTRIES) {
+      expect(entry.label.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('only uses known direction models', () => {
+    for (const entry of TRANSITION_ENTRIES) {
+      if (entry.direction) {
+        expect(DIRECTION_OPTIONS[entry.direction]).toBeDefined();
+      }
+    }
+  });
+
+  it('flat list matches the groups', () => {
+    expect(TRANSITION_ENTRIES).toEqual(TRANSITION_GROUPS.flatMap((g) => g.entries));
+  });
+});
+
+describe('transitionLabel', () => {
+  it('maps the empty value to None', () => {
+    expect(transitionLabel('')).toBe('None');
+  });
+
+  it('uses the curated label for a known value', () => {
+    expect(transitionLabel('pageCurl')).toBe('Page Curl');
+  });
+
+  it('humanizes an uncurated (but valid) alias', () => {
+    expect(transitionLabel('ferris')).toBe('Ferris');
+  });
+});
+
+describe('findTransitionEntry', () => {
+  it('finds a curated entry', () => {
+    expect(findTransitionEntry('push')?.direction).toBe('lrud');
+  });
+
+  it('returns undefined for an uncurated value', () => {
+    expect(findTransitionEntry('ferris')).toBeUndefined();
+  });
+});

package/src/__tests__/useBlockNavigator.test.tsx

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useState } from 'react';
+import { useBlockNavigator } from '../useBlockNavigator';
+
+/** Drive the hook against a piece of React-managed source state. */
+function useHarness(initial: string, enabled: boolean) {
+  const [source, setSource] = useState(initial);
+  const nav = useBlockNavigator(source, setSource, { enabled });
+  return { source, nav };
+}
+
+const DOC = '# One\n\nalpha\n\n# Two\n\nbeta\n';
+
+describe('useBlockNavigator', () => {
+  it('passes through to the full source when disabled', () => {
+    const { result } = renderHook(() => useHarness(DOC, false));
+    expect(result.current.nav.editorSource).toBe(DOC);
+    act(() => result.current.nav.setEditorSource('changed\n'));
+    expect(result.current.source).toBe('changed\n');
+  });
+
+  it('scopes editorSource to the active block when enabled', () => {
+    const { result } = renderHook(() => useHarness(DOC, true));
+    expect(result.current.nav.blockCount).toBe(2);
+    expect(result.current.nav.activeBlockKey).toBe(0);
+    expect(result.current.nav.editorSource).toBe('# One\n\nalpha\n\n');
+
+    act(() => result.current.nav.nextBlock());
+    expect(result.current.nav.activeBlockKey).toBe(1);
+    expect(result.current.nav.editorSource).toBe('# Two\n\nbeta\n');
+  });
+
+  it('splices an edit to the active block back into the full source', () => {
+    const { result } = renderHook(() => useHarness(DOC, true));
+    act(() => result.current.nav.setEditorSource('# One\n\nalpha edited'));
+    // A blank line is guaranteed before the following heading.
+    expect(result.current.source).toBe('# One\n\nalpha edited\n\n# Two\n\nbeta\n');
+  });
+
+  it('clamps navigation at the document ends', () => {
+    const { result } = renderHook(() => useHarness(DOC, true));
+    act(() => result.current.nav.prevBlock());
+    expect(result.current.nav.activeBlockKey).toBe(0);
+    act(() => result.current.nav.nextBlock());
+    act(() => result.current.nav.nextBlock());
+    expect(result.current.nav.activeBlockKey).toBe(1);
+  });
+
+  it('adds a new block after the active one and moves to it', () => {
+    const { result } = renderHook(() => useHarness(DOC, true));
+    act(() => result.current.nav.addBlock());
+    expect(result.current.nav.blockCount).toBe(3);
+    expect(result.current.nav.activeBlockKey).toBe(1);
+    expect(result.current.nav.editorSource).toContain('## New section');
+    // The original second block is preserved and now sits last.
+    expect(result.current.source).toContain('# Two\n\nbeta\n');
+  });
+
+  it('selects a block by source line for the outline', () => {
+    const { result } = renderHook(() => useHarness(DOC, true));
+    // Line 5 is the "# Two" heading.
+    act(() => result.current.nav.goToBlockByLine(5));
+    expect(result.current.nav.activeBlockKey).toBe(1);
+    expect(result.current.nav.activeBlockStartLine).toBe(5);
+  });
+});

package/src/__tests__/useMediaRecorder.test.ts

@@ -165,6 +165,30 @@ describe('useMediaRecorder lifecycle', () => {
     expect(result.current.stream).not.toBeNull();
   });
 
+  it('camera includes the mic by default', async () => {
+    const { result } = renderHook(() => useMediaRecorder({ source: 'camera' }));
+    await act(async () => {
+      await result.current.request();
+    });
+    const getUserMedia = navigator.mediaDevices.getUserMedia as ReturnType<typeof vi.fn>;
+    expect(getUserMedia).toHaveBeenCalledWith(
+      expect.objectContaining({ video: true, audio: true }),
+    );
+  });
+
+  it('camera omits the mic when includeMicrophone is false', async () => {
+    const { result } = renderHook(() =>
+      useMediaRecorder({ source: 'camera', includeMicrophone: false }),
+    );
+    await act(async () => {
+      await result.current.request();
+    });
+    const getUserMedia = navigator.mediaDevices.getUserMedia as ReturnType<typeof vi.fn>;
+    expect(getUserMedia).toHaveBeenCalledWith(
+      expect.objectContaining({ video: true, audio: false }),
+    );
+  });
+
   it('cancel() tears down state and stops the stream tracks', async () => {
     const { result } = renderHook(() => useMediaRecorder({ source: 'mic' }));
 

package/src/__tests__/useTimelineClock.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { advanceTime } from '../useTimelineClock';
+
+describe('advanceTime', () => {
+  it('advances by dt within range', () => {
+    expect(advanceTime(2, 1.5, 30)).toBe(3.5);
+  });
+
+  it('clamps to total at the end', () => {
+    expect(advanceTime(29.5, 1, 30)).toBe(30);
+    expect(advanceTime(30, 5, 30)).toBe(30);
+  });
+
+  it('never goes below 0', () => {
+    expect(advanceTime(0.2, -1, 30)).toBe(0);
+  });
+
+  it('returns 0 for an empty timeline', () => {
+    expect(advanceTime(5, 1, 0)).toBe(0);
+  });
+});

package/src/blockProperties.ts

@@ -0,0 +1,88 @@
+/**
+ * blockProperties
+ *
+ * Generic read/write of a single block-meta key on a heading's Pandoc `{…}`
+ * attribute block (stored as the `dataBlockAttrs` inner string in the WYSIWYG
+ * heading node — no braces, matching `tiptapBridge`).
+ *
+ * The transition family (which spans three coupled keys) has its own helpers
+ * in `headingTransition.ts`; this module covers the standalone scalar keys the
+ * block-properties palette edits — `duration`, `startTime`, `x`, `y`, … — all
+ * of which are plain `key=value` params. Parse/serialize is delegated to the
+ * shared core helpers so quoting and ordering match the parser exactly.
+ */
+
+import {
+  parsePandocAttrTokens,
+  serializePandocAttributes,
+  parseTimeSeconds,
+  type HeadingAttributes,
+} from '@bendyline/squisq/markdown';
+import { normalizeTransitionType } from '@bendyline/squisq/schemas';
+import { readBlockAttrsTransition } from './headingTransition';
+import { transitionLabel } from './transitionCatalog';
+
+/** Parse a `dataBlockAttrs` inner string into its flat `key → value` map. */
+export function readBlockAttrsParams(inner: string | null | undefined): Record<string, string> {
+  return inner ? (parsePandocAttrTokens(inner).params ?? {}) : {};
+}
+
+/** Read a single block-meta param, or '' when unset. */
+export function readBlockAttrsValue(inner: string | null | undefined, key: string): string {
+  return readBlockAttrsParams(inner)[key] ?? '';
+}
+
+/**
+ * Set (or, when `value` is empty, remove) a single param in a `dataBlockAttrs`
+ * inner string. Returns the new inner (no braces), or null when the block is
+ * left with no attributes at all — matching how `tiptapBridge` stores an
+ * absent attribute (null, not `{}`).
+ */
+export function setBlockAttrsValue(
+  inner: string | null | undefined,
+  key: string,
+  value: string,
+): string | null {
+  const attrs: HeadingAttributes = inner ? parsePandocAttrTokens(inner) : {};
+  const params: Record<string, string> = { ...(attrs.params ?? {}) };
+  const trimmed = value.trim();
+  if (trimmed === '') delete params[key];
+  else params[key] = trimmed;
+  attrs.params = params;
+  const raw = serializePandocAttributes(attrs);
+  return raw == null || raw === '{}' ? null : raw.slice(1, -1);
+}
+
+/**
+ * A concise, human-readable summary of a block's authored properties for the
+ * on-canvas badge — e.g. `Doors · 1:30 start · 3:20 long`. Returns '' when no
+ * properties are set (the badge then shows just its icon). Reads transition
+ * from both the Pandoc block and the `{[…]}` params; timing from the block.
+ */
+export function summarizeBlockProps(
+  blockAttrs: string | null | undefined,
+  templateParams: string | null | undefined,
+): string {
+  const parts: string[] = [];
+
+  const transition = readBlockAttrsTransition(blockAttrs, templateParams);
+  if (transition.type) {
+    parts.push(transitionLabel(normalizeTransitionType(transition.type) ?? transition.type));
+  }
+
+  const params = readBlockAttrsParams(blockAttrs);
+  if (params.startTime) parts.push(`${formatClock(params.startTime)} start`);
+  if (params.duration) parts.push(`${formatClock(params.duration)} long`);
+
+  return parts.join(' · ');
+}
+
+/** Format a raw time value (`90`, `1:30`, `1500ms`) as `m:ss`, or pass through. */
+function formatClock(raw: string): string {
+  const seconds = parseTimeSeconds(raw);
+  if (seconds == null) return raw;
+  const total = Math.round(seconds);
+  const minutes = Math.floor(total / 60);
+  const secs = total % 60;
+  return `${minutes}:${String(secs).padStart(2, '0')}`;
+}

package/src/blockRange.ts

@@ -0,0 +1,132 @@
+/**
+ * blockRange
+ *
+ * Source-text-range slicing for the block-at-a-time editing view. Splits a
+ * full markdown document into ordered, contiguous slices — one per
+ * heading-defined block plus an optional leading preamble — so a single
+ * block can be shown in isolation and edits spliced back into the parent.
+ *
+ * A block runs from its heading line through the character just before the
+ * next heading at ANY depth (or EOF). Sub-headings therefore start their own
+ * slices — they are NOT folded into their parent — which matches the
+ * "don't see child blocks" requirement and the `slicePastHeading` boundary
+ * in `blockSlice.ts`. Ranges are half-open `[startOffset, endOffset)` and
+ * line-aligned, so trailing blank lines stay with the current block and
+ * `spliceBlock(src, range, getBlockSlices(src)[i].text) === src` for every i.
+ *
+ * These are pure functions over a markdown string — no React, no editor
+ * coupling — so any host can reuse them.
+ */
+
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import type { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { frontmatterEndOffset } from './frontmatter';
+
+/** Half-open character range into the full source: `[startOffset, endOffset)`. */
+export interface BlockRange {
+  startOffset: number;
+  endOffset: number;
+}
+
+/** One block's source text plus the range it occupies in the full document. */
+export interface BlockSlice {
+  text: string;
+  range: BlockRange;
+}
+
+/** Map every line start to its character offset (`lineStarts[line - 1]`). */
+function computeLineStarts(source: string): number[] {
+  const starts = [0];
+  for (let i = 0; i < source.length; i++) {
+    if (source[i] === '\n') starts.push(i + 1);
+  }
+  return starts;
+}
+
+function makeSlice(source: string, startOffset: number, endOffset: number): BlockSlice {
+  return { text: source.slice(startOffset, endOffset), range: { startOffset, endOffset } };
+}
+
+/**
+ * Split `fullSource` into ordered block slices.
+ *
+ * - With no headings, the entire post-frontmatter body is a single slice
+ *   (so an empty or heading-less document still shows one editable card).
+ * - With headings, a leading preamble slice is included only when the text
+ *   before the first heading has non-whitespace content. Each heading then
+ *   yields one slice spanning up to the next heading (any depth) or EOF.
+ *
+ * Frontmatter is never part of any slice — slices start at the body offset.
+ */
+export function getBlockSlices(fullSource: string): BlockSlice[] {
+  const bodyStart = frontmatterEndOffset(fullSource);
+
+  let doc: MarkdownDocument;
+  try {
+    doc = parseMarkdown(fullSource);
+  } catch {
+    // Unparseable mid-edit — treat the whole body as one slice rather than
+    // dropping the user into an empty card.
+    return [makeSlice(fullSource, bodyStart, fullSource.length)];
+  }
+
+  const lineStarts = computeLineStarts(fullSource);
+  const headingOffsets: number[] = [];
+  for (const node of doc.children) {
+    if (node.type !== 'heading') continue;
+    const line = node.position?.start.line;
+    if (typeof line !== 'number') continue;
+    const off = lineStarts[line - 1];
+    if (typeof off === 'number') headingOffsets.push(off);
+  }
+
+  if (headingOffsets.length === 0) {
+    return [makeSlice(fullSource, bodyStart, fullSource.length)];
+  }
+
+  const slices: BlockSlice[] = [];
+  const firstHeading = headingOffsets[0];
+  if (fullSource.slice(bodyStart, firstHeading).trim().length > 0) {
+    slices.push(makeSlice(fullSource, bodyStart, firstHeading));
+  }
+  for (let i = 0; i < headingOffsets.length; i++) {
+    const start = headingOffsets[i];
+    const end = i + 1 < headingOffsets.length ? headingOffsets[i + 1] : fullSource.length;
+    slices.push(makeSlice(fullSource, start, end));
+  }
+  return slices;
+}
+
+/** Replace the text in `range` with `newText`, returning the new full source. */
+export function spliceBlock(fullSource: string, range: BlockRange, newText: string): string {
+  return fullSource.slice(0, range.startOffset) + newText + fullSource.slice(range.endOffset);
+}
+
+/** Character offset of the start of 1-based `line` (clamps past EOF). */
+export function lineToOffset(source: string, line: number): number {
+  const starts = computeLineStarts(source);
+  return starts[Math.max(0, line - 1)] ?? source.length;
+}
+
+/** 1-based line number containing `offset`. */
+export function offsetToLine(source: string, offset: number): number {
+  const starts = computeLineStarts(source);
+  let lo = 0;
+  let hi = starts.length - 1;
+  let ans = 0;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (starts[mid] <= offset) {
+      ans = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return ans + 1;
+}
+
+/** Index of the slice whose range contains `offset`, or -1. */
+export function sliceIndexAtOffset(slices: BlockSlice[], offset: number): number {
+  return slices.findIndex((s) => offset >= s.range.startOffset && offset < s.range.endOffset);
+}