@bendyline/squisq-editor-react 2.1.0 → 2.2.0

package/src/timeline/timelineOps.ts

@@ -1,381 +0,0 @@
-/**
- * Pure edits over the authored ASCII timeline model.
- *
- * The code fence remains the source of truth. Canvas coordinates are
- * normalized to the same global, shared scale used by
- * `asciiTimelineToTemplateData`; commands render the edited model back into
- * canonical fence text after applying one of these operations.
- */
-
-import type {
-  AsciiTimeline,
-  AsciiTimelineEvent,
-  AsciiTimelineMarker,
-  AsciiTimelineSide,
-  AsciiTimelineTrack,
-} from '@bendyline/squisq/doc';
-
-const STRUCTURAL_MARKERS = /[●○◉◆◇•]+/gu;
-const LEADING_RAILS = /^[─━═╌╍┄┅┈┉-]+/u;
-const COORDINATE_PRECISION = 1_000;
-const COLUMN_EPSILON = 1 / COORDINATE_PRECISION / 2;
-
-export interface TimelineEventPatch {
-  label?: string;
-  /** `null` clears the optional description. */
-  description?: string | null;
-  side?: AsciiTimelineSide;
-  /** `null` restores the label side/default placement. */
-  descriptionSide?: AsciiTimelineSide | null;
-  callout?: boolean;
-  marker?: AsciiTimelineMarker;
-  /** Normalized position on the global timeline scale. */
-  position?: number;
-}
-
-export interface AddTimelineEventOptions {
-  id?: string;
-  label?: string;
-  description?: string;
-  side?: AsciiTimelineSide;
-  descriptionSide?: AsciiTimelineSide;
-  callout?: boolean;
-  marker?: AsciiTimelineMarker;
-}
-
-export interface AddTimelineEventResult {
-  timeline: AsciiTimeline;
-  eventId: string;
-}
-
-export interface AddTimelineTrackOptions {
-  id?: string;
-  label?: string;
-  eventId?: string;
-  eventLabel?: string;
-}
-
-export interface AddTimelineTrackResult {
-  timeline: AsciiTimeline;
-  trackId: string;
-  eventId: string;
-}
-
-/**
- * Normalize editable one-line prose exactly as the canonical core renderer
- * does. This prevents the verified command path from accepting a value that
- * is silently reinterpreted as timeline syntax on its first render.
- */
-export function sanitizeTimelineText(value: string): string {
-  const normalized = value
-    .normalize('NFC')
-    .replace(/[\r\n\t]+/g, ' ')
-    .replace(STRUCTURAL_MARKERS, '·')
-    .replace(/\*/g, '∗')
-    .replace(/::/g, '∶')
-    .replace(/\s+/g, ' ')
-    .trim();
-
-  return normalized.replace(LEADING_RAILS, (run) =>
-    Array.from(run, (character) => (character === '-' ? '−' : '–')).join(''),
-  );
-}
-
-/** Return a globally unique, renderer-safe event id. */
-export function nextTimelineEventId(timeline: AsciiTimeline, base = 'event'): string {
-  const used = new Set(timeline.tracks.flatMap((track) => track.events.map((event) => event.id)));
-  const safeBase = safeId(base, 'event');
-  if (!used.has(safeBase)) return safeBase;
-  let suffix = 2;
-  while (used.has(`${safeBase}-${suffix}`)) suffix++;
-  return `${safeBase}-${suffix}`;
-}
-
-/** Return a renderer-safe id that is unique among timeline tracks. */
-export function nextTimelineTrackId(timeline: AsciiTimeline, base = 'track'): string {
-  const used = new Set(timeline.tracks.map((track) => track.id));
-  const safeBase = safeId(base, 'track');
-  if (!used.has(safeBase)) return safeBase;
-  let suffix = 2;
-  while (used.has(`${safeBase}-${suffix}`)) suffix++;
-  return `${safeBase}-${suffix}`;
-}
-
-/**
- * Add a representable track with one starter point. Empty tracks are not part
- * of the authored ASCII grammar, so line creation and its first point are one
- * atomic operation/undo step.
- */
-export function addTimelineTrackOp(
-  timeline: AsciiTimeline,
-  options: AddTimelineTrackOptions = {},
-): AddTimelineTrackResult {
-  const label = sanitizeTimelineText(options.label ?? '') || 'New line';
-  const eventLabel = sanitizeTimelineText(options.eventLabel ?? '') || 'New event';
-  const trackId = nextTimelineTrackId(timeline, options.id ?? label);
-  const eventId = nextTimelineEventId(timeline, options.eventId ?? eventLabel);
-  const { start, span } = globalBounds(timeline);
-  const column = Math.round((start + span / 2) * COORDINATE_PRECISION) / COORDINATE_PRECISION;
-  const row = timeline.tracks.reduce((maximum, track) => Math.max(maximum, track.row), -1) + 1;
-  const track: AsciiTimelineTrack = {
-    id: trackId,
-    label,
-    row,
-    startColumn: start,
-    endColumn: start + span,
-    events: [
-      {
-        id: eventId,
-        label: eventLabel,
-        column,
-        side: 'above',
-        marker: 'filled',
-      },
-    ],
-  };
-
-  return {
-    timeline: {
-      ...timeline,
-      tracks: [...timeline.tracks, track],
-      width: Math.max(timeline.width, Math.ceil(track.endColumn) + 1),
-      height: Math.max(timeline.height, row + 1),
-    },
-    trackId,
-    eventId,
-  };
-}
-
-/** Rename a track without changing its stable id, points, or branches. */
-export function updateTimelineTrackOp(
-  timeline: AsciiTimeline,
-  trackId: string,
-  label: string,
-): AsciiTimeline {
-  const track = timeline.tracks.find((candidate) => candidate.id === trackId);
-  const nextLabel = sanitizeTimelineText(label);
-  if (!track || !nextLabel || track.label === nextLabel) return timeline;
-  return {
-    ...timeline,
-    tracks: timeline.tracks.map((candidate) =>
-      candidate.id === trackId ? { ...candidate, label: nextLabel } : candidate,
-    ),
-  };
-}
-
-/**
- * Remove a whole track, including branches incident to any of its points.
- * Keep the last track so the source fence remains representable and mounted.
- */
-export function removeTimelineTrackOp(timeline: AsciiTimeline, trackId: string): AsciiTimeline {
-  if (timeline.tracks.length <= 1) return timeline;
-  const track = timeline.tracks.find((candidate) => candidate.id === trackId);
-  if (!track) return timeline;
-  const removedEventIds = new Set(track.events.map((event) => event.id));
-  return {
-    ...timeline,
-    tracks: timeline.tracks.filter((candidate) => candidate.id !== trackId),
-    links: timeline.links.filter(
-      (link) => !removedEventIds.has(link.source) && !removedEventIds.has(link.target),
-    ),
-  };
-}
-
-/**
- * Add a visible point to `trackId` at a normalized global rail position.
- * Returns the stable id so the canvas can select/focus the new point after
- * the fence rewrite.
- */
-export function addTimelineEventOp(
-  timeline: AsciiTimeline,
-  trackId: string,
-  position: number,
-  options: AddTimelineEventOptions = {},
-): AddTimelineEventResult | null {
-  if (!Number.isFinite(position)) return null;
-  const track = timeline.tracks.find((candidate) => candidate.id === trackId);
-  if (!track) return null;
-
-  const column = columnAtPosition(timeline, position);
-  // Two coincident markers cannot be independently hit on the canvas. A
-  // marker click should select the existing point rather than adding atop it.
-  if (track.events.some((event) => Math.abs(event.column - column) <= COLUMN_EPSILON)) return null;
-
-  const label = sanitizeTimelineText(options.label ?? '') || 'New event';
-  const description = sanitizeTimelineText(options.description ?? '');
-  const eventId = nextTimelineEventId(timeline, options.id ?? label);
-  const insertionIndex = track.events.filter((event) => event.column < column).length;
-  const side = options.side ?? (insertionIndex % 2 === 0 ? 'above' : 'below');
-  const event: AsciiTimelineEvent = {
-    id: eventId,
-    label,
-    ...(description ? { description } : {}),
-    column,
-    side,
-    ...(description && options.descriptionSide ? { descriptionSide: options.descriptionSide } : {}),
-    ...(options.callout === false ? { callout: false } : {}),
-    marker: options.marker ?? 'filled',
-  };
-
-  const events = [...track.events, event].sort(
-    (left, right) => left.column - right.column || left.id.localeCompare(right.id),
-  );
-  const tracks = timeline.tracks.map((candidate) =>
-    candidate.id === trackId ? { ...candidate, events } : candidate,
-  );
-  // ASCII art has no distinct diamond glyph. Promote the authored vocabulary
-  // when the inspector explicitly requests one rather than silently folding
-  // the user's choice back to a filled point in the renderer.
-  const style = options.marker === 'diamond' ? 'unicode' : timeline.style;
-  return { timeline: { ...timeline, tracks, style }, eventId };
-}
-
-/** Update one point without changing its stable id or branch endpoints. */
-export function updateTimelineEventOp(
-  timeline: AsciiTimeline,
-  eventId: string,
-  patch: TimelineEventPatch,
-): AsciiTimeline {
-  const location = findEvent(timeline, eventId);
-  if (!location || Object.keys(patch).length === 0) return timeline;
-
-  const hasLabel = Object.prototype.hasOwnProperty.call(patch, 'label');
-  const hasDescription = Object.prototype.hasOwnProperty.call(patch, 'description');
-  const hasDescriptionSide = Object.prototype.hasOwnProperty.call(patch, 'descriptionSide');
-  const hasPosition = Object.prototype.hasOwnProperty.call(patch, 'position');
-  const label = hasLabel ? sanitizeTimelineText(patch.label ?? '') : location.event.label;
-  if (!label) return timeline;
-
-  let description = hasDescription
-    ? sanitizeTimelineText(patch.description ?? '')
-    : location.event.description;
-  if (!description) description = undefined;
-
-  let column = location.event.column;
-  if (hasPosition) {
-    if (!Number.isFinite(patch.position)) return timeline;
-    column = columnAtPosition(timeline, patch.position as number);
-    const collision = location.track.events.some(
-      (event) => event.id !== eventId && Math.abs(event.column - column) <= COLUMN_EPSILON,
-    );
-    if (collision) return timeline;
-  }
-
-  const editedText = hasLabel || hasDescription;
-  const callout =
-    patch.callout !== undefined
-      ? patch.callout
-      : editedText && location.event.callout === false
-        ? true
-        : location.event.callout;
-  const descriptionSide = !description
-    ? undefined
-    : hasDescriptionSide
-      ? (patch.descriptionSide ?? undefined)
-      : location.event.descriptionSide;
-
-  const nextEvent: AsciiTimelineEvent = {
-    ...location.event,
-    label,
-    column,
-    ...(description ? { description } : {}),
-    ...(patch.side ? { side: patch.side } : {}),
-    ...(descriptionSide ? { descriptionSide } : {}),
-    ...(callout !== undefined ? { callout } : {}),
-    ...(patch.marker ? { marker: patch.marker } : {}),
-  };
-  if (!description) delete nextEvent.description;
-  if (!descriptionSide) delete nextEvent.descriptionSide;
-
-  if (eventsEqual(location.event, nextEvent)) return timeline;
-  const events = location.track.events
-    .map((event) => (event.id === eventId ? nextEvent : event))
-    .sort((left, right) => left.column - right.column || left.id.localeCompare(right.id));
-  // A point authored exactly on a track boundary anchors that edge. Let the
-  // old scale remain stable throughout a drag preview, then move/reassign the
-  // boundary in the single drop transaction. Crossing the next point hands
-  // the edge to that point; moving any point outside a shorter track expands
-  // the track so every marker remains inside its authored bounds.
-  const movedPosition = hasPosition && nextEvent.column !== location.event.column;
-  const anchoredStart =
-    movedPosition && Math.abs(location.event.column - location.track.startColumn) <= COLUMN_EPSILON;
-  const anchoredEnd =
-    movedPosition && Math.abs(location.event.column - location.track.endColumn) <= COLUMN_EPSILON;
-  const eventStart = Math.min(...events.map((event) => event.column));
-  const eventEnd = Math.max(...events.map((event) => event.column));
-  const startColumn = anchoredStart ? eventStart : Math.min(location.track.startColumn, eventStart);
-  const endColumn = anchoredEnd ? eventEnd : Math.max(location.track.endColumn, eventEnd);
-  const tracks = timeline.tracks.map((track) =>
-    track.id === location.track.id ? { ...track, startColumn, endColumn, events } : track,
-  );
-  const style = patch.marker === 'diamond' ? 'unicode' : timeline.style;
-  return { ...timeline, tracks, style };
-}
-
-/**
- * Remove a point and every incident branch. Empty tracks are removed because
- * the canonical renderer cannot represent them. The last point in the whole
- * timeline is retained so an edit cannot erase its own source fence/widget.
- */
-export function removeTimelineEventOp(timeline: AsciiTimeline, eventId: string): AsciiTimeline {
-  const location = findEvent(timeline, eventId);
-  if (!location) return timeline;
-  const eventCount = timeline.tracks.reduce((sum, track) => sum + track.events.length, 0);
-  if (eventCount <= 1) return timeline;
-
-  const tracks = timeline.tracks
-    .map((track) =>
-      track.id === location.track.id
-        ? { ...track, events: track.events.filter((event) => event.id !== eventId) }
-        : track,
-    )
-    .filter((track) => track.events.length > 0);
-  const links = timeline.links.filter((link) => link.source !== eventId && link.target !== eventId);
-  return { ...timeline, tracks, links };
-}
-
-function globalBounds(timeline: AsciiTimeline): { start: number; span: number } {
-  if (timeline.tracks.length === 0) return { start: 0, span: 1 };
-  const start = Math.min(...timeline.tracks.map((track) => track.startColumn));
-  const end = Math.max(...timeline.tracks.map((track) => track.endColumn));
-  return { start, span: Math.max(1, end - start) };
-}
-
-function columnAtPosition(timeline: AsciiTimeline, position: number): number {
-  const { start, span } = globalBounds(timeline);
-  const clamped = Math.max(0, Math.min(1, position));
-  return Math.round((start + clamped * span) * COORDINATE_PRECISION) / COORDINATE_PRECISION;
-}
-
-function safeId(value: string, fallback: string): string {
-  return (
-    sanitizeTimelineText(value)
-      .toLowerCase()
-      .replace(/[^a-z0-9_.~-]+/g, '-')
-      .replace(/^-+|-+$/g, '') || fallback
-  );
-}
-
-function findEvent(
-  timeline: AsciiTimeline,
-  eventId: string,
-): { track: AsciiTimeline['tracks'][number]; event: AsciiTimelineEvent } | null {
-  for (const track of timeline.tracks) {
-    const event = track.events.find((candidate) => candidate.id === eventId);
-    if (event) return { track, event };
-  }
-  return null;
-}
-
-function eventsEqual(left: AsciiTimelineEvent, right: AsciiTimelineEvent): boolean {
-  return (
-    left.id === right.id &&
-    left.label === right.label &&
-    left.description === right.description &&
-    left.column === right.column &&
-    left.side === right.side &&
-    left.descriptionSide === right.descriptionSide &&
-    left.callout === right.callout &&
-    left.marker === right.marker
-  );
-}

package/src/timeline/timelinePaste.ts

@@ -1,8 +0,0 @@
-/** Paste gate for bare, high-confidence Unicode timeline art. */
-
-import { detectAsciiTimeline } from '@bendyline/squisq/doc';
-
-export function shouldPasteAsTimelineFence(text: string): boolean {
-  if (!text.trim() || /^\s*```/m.test(text)) return false;
-  return detectAsciiTimeline(text).isTimeline;
-}

package/src/timelineSource.ts

@@ -1,244 +0,0 @@
-/**
- * timelineSource
- *
- * Line-level markdown rewrites for the timeline editor: set a block's
- * `duration` on its heading's Pandoc attribute block, and patch a media
- * clip's `startAt` / `clipStart` / `clipEnd` / `spillover` on its `{[audio …]}`
- * / `{[video …]}` annotation line. Both preserve everything else on the line
- * (template annotations, ids, classes, other params) by reusing the shared
- * tokenizers rather than regex-replacing values.
- */
-
-import {
-  matchTrailingPandocAttr,
-  matchTrailingTemplateAnnotation,
-  parsePandocAttrTokens,
-  serializePandocAttributes,
-  tokenizeAttrTokens,
-  splitKeyValueToken,
-  quoteAttrValue,
-} from '@bendyline/squisq/markdown';
-
-/** Format a seconds value compactly: integers bare, else up to 2 decimals. */
-export function formatSeconds(seconds: number): string {
-  const clamped = Math.max(0, seconds);
-  if (Number.isInteger(clamped)) return String(clamped);
-  return String(Math.round(clamped * 100) / 100);
-}
-
-/**
- * Set/insert a `duration` on the heading at 1-based `line`, written in the
- * squisq-native squiggly form — `{[duration=<seconds>]}` on its own, or
- * folded into an existing `{[template …]}` annotation. Preserves any `{#id}`,
- * classes, and other Pandoc params, and migrates a legacy Pandoc
- * `{duration=…}` to the squiggly form (dropping the stale Pandoc key so the
- * two can't disagree). Returns the new full source, or null when the line
- * isn't an ATX heading.
- */
-export function setBlockDurationInSource(
-  source: string,
-  line: number,
-  seconds: number,
-): string | null {
-  const lines = source.split('\n');
-  const idx = line - 1;
-  if (idx < 0 || idx >= lines.length) return null;
-  const original = lines[idx];
-  if (!/^#{1,6}\s/.test(original)) return null;
-
-  const value = formatSeconds(seconds);
-
-  // Peel the trailing `{[…]}` annotation (if any) off the line; we'll fold
-  // `duration` into it. Canonical heading order is `{#pandoc} {[squiggly]}`,
-  // so the squiggly annotation is the last `{…}` on the line.
-  let rest = original;
-  let annotationInner: string | null = null;
-  const tpl = matchTrailingTemplateAnnotation(rest);
-  if (tpl) {
-    annotationInner = tpl.inner.trim();
-    rest = rest.slice(0, tpl.index).replace(/\s+$/, '');
-  }
-
-  // Then peel a trailing Pandoc `{…}` block; drop its `duration` so a legacy
-  // value can't shadow the squiggly one we're writing. Keep the rest (id,
-  // classes, other params).
-  let pandocSerialized: string | null = null;
-  const pa = matchTrailingPandocAttr(rest);
-  if (pa) {
-    const attrs = parsePandocAttrTokens(pa.inner.trim());
-    if (attrs.params) {
-      delete attrs.params.duration;
-      if (Object.keys(attrs.params).length === 0) delete attrs.params;
-    }
-    pandocSerialized = serializePandocAttributes(attrs);
-    rest = rest.slice(0, pa.index).replace(/\s+$/, '');
-  }
-
-  const annotation = setTemplateParam(annotationInner, 'duration', value);
-  const parts = [rest];
-  if (pandocSerialized) parts.push(pandocSerialized);
-  parts.push(annotation);
-  lines[idx] = parts.join(' ');
-  return lines.join('\n');
-}
-
-/**
- * Build a `{[…]}` annotation from an existing inner string (or null for a
- * fresh one), setting `key=value` and preserving the template name plus any
- * other params in their original order.
- */
-function setTemplateParam(inner: string | null, key: string, value: string): string {
-  const tokens = inner ? tokenizeAttrTokens(inner) : [];
-  const firstIsParam = tokens.length > 0 && tokens[0].indexOf('=') > 0;
-  const template = firstIsParam || tokens.length === 0 ? undefined : tokens[0];
-
-  const params: Record<string, string> = {};
-  const order: string[] = [];
-  for (let i = template ? 1 : 0; i < tokens.length; i++) {
-    const kv = splitKeyValueToken(tokens[i]);
-    if (kv) {
-      if (!(kv.key in params)) order.push(kv.key);
-      params[kv.key] = kv.value;
-    }
-  }
-  if (!(key in params)) order.push(key);
-  params[key] = value;
-
-  const parts = template ? [template] : [];
-  for (const k of order) parts.push(`${k}=${quoteAttrValue(params[k])}`);
-  return `{[${parts.join(' ')}]}`;
-}
-
-/** A patch to a media clip; numeric values are seconds, `null` removes the key. */
-export interface MediaClipPatch {
-  startAt?: number | null;
-  clipStart?: number | null;
-  clipEnd?: number | null;
-  spillover?: boolean | null;
-}
-
-/**
- * Patch the `{[audio …]}` / `{[video …]}` annotation at 1-based `line`.
- * Preserves the template name and any params not in the patch. Returns the
- * new full source, or null when the line isn't a media annotation.
- */
-export function setMediaClipInSource(
-  source: string,
-  line: number,
-  patch: MediaClipPatch,
-): string | null {
-  const lines = source.split('\n');
-  const idx = line - 1;
-  if (idx < 0 || idx >= lines.length) return null;
-  const original = lines[idx];
-  const m = matchTrailingTemplateAnnotation(original);
-  if (!m) return null;
-
-  const tokens = tokenizeAttrTokens(m.inner.trim());
-  const firstIsParam = tokens.length > 0 && tokens[0].indexOf('=') > 0;
-  const template = firstIsParam || tokens.length === 0 ? undefined : tokens[0];
-  if (!template || !['audio', 'video', 'media'].includes(template)) return null;
-
-  const params: Record<string, string> = {};
-  const order: string[] = [];
-  for (let i = 1; i < tokens.length; i++) {
-    const kv = splitKeyValueToken(tokens[i]);
-    if (kv) {
-      if (!(kv.key in params)) order.push(kv.key);
-      params[kv.key] = kv.value;
-    }
-  }
-
-  const apply = (key: string, value: string | null) => {
-    if (value === null) {
-      delete params[key];
-      const i = order.indexOf(key);
-      if (i >= 0) order.splice(i, 1);
-    } else {
-      if (!(key in params)) order.push(key);
-      params[key] = value;
-    }
-  };
-  if (patch.startAt !== undefined)
-    apply('startAt', patch.startAt == null ? null : formatSeconds(patch.startAt));
-  if (patch.clipStart !== undefined)
-    apply('clipStart', patch.clipStart == null ? null : formatSeconds(patch.clipStart));
-  if (patch.clipEnd !== undefined)
-    apply('clipEnd', patch.clipEnd == null ? null : formatSeconds(patch.clipEnd));
-  if (patch.spillover !== undefined) apply('spillover', patch.spillover ? 'true' : null);
-
-  const parts = [template, ...order.map((k) => `${k}=${quoteAttrValue(params[k])}`)];
-  const annotation = `{[${parts.join(' ')}]}`;
-  const prefix = original.slice(0, m.index).replace(/\s+$/, '');
-  lines[idx] = prefix ? `${prefix} ${annotation}` : annotation;
-  return lines.join('\n');
-}
-
-/** A timed media clip's identity for (re)writing its annotation. */
-export interface ClipSpec {
-  kind: 'audio' | 'video';
-  src: string;
-  clipStart?: number;
-  clipEnd?: number;
-  spillover?: boolean;
-}
-
-/** Build a `{[audio|video src=… startAt=… clipEnd=…]}` annotation string. */
-export function buildClipAnnotation(spec: ClipSpec, startAt: number): string {
-  const parts: string[] = [spec.kind, `src=${quoteAttrValue(spec.src)}`];
-  if (startAt > 0) parts.push(`startAt=${formatSeconds(startAt)}`);
-  if (spec.clipStart != null && spec.clipStart > 0) {
-    parts.push(`clipStart=${formatSeconds(spec.clipStart)}`);
-  }
-  if (spec.clipEnd != null) parts.push(`clipEnd=${formatSeconds(spec.clipEnd)}`);
-  if (spec.spillover) parts.push('spillover=true');
-  return `{[${parts.join(' ')}]}`;
-}
-
-/** Index of the heading line at/above `idx` (−1 for the preamble). */
-function headingIndexAbove(lines: string[], idx: number): number {
-  for (let i = Math.min(idx, lines.length - 1); i >= 0; i--) {
-    if (/^#{1,6}\s/.test(lines[i])) return i;
-  }
-  return -1;
-}
-
-/**
- * Place a timed clip into the block whose heading is at 1-based
- * `targetHeadingLine`, written as a `{[…]}` annotation. The clip's current
- * authoring line at 1-based `fromLine` (a media embed or an existing
- * annotation) is removed; when the target is the same block the line is
- * rewritten in place. Returns the new source, or null on bad input.
- *
- * This is what lets a clip be dragged from one block into another on the
- * timeline: its representation relocates to the target block's body.
- */
-export function placeClipInBlock(
-  source: string,
-  fromLine: number,
-  targetHeadingLine: number,
-  spec: ClipSpec,
-  startAt: number,
-): string | null {
-  const lines = source.split('\n');
-  const fromIdx = fromLine - 1;
-  if (fromIdx < 0 || fromIdx >= lines.length) return null;
-  const targetIdx0 = targetHeadingLine - 1;
-  if (targetIdx0 < 0 || targetIdx0 >= lines.length) return null;
-
-  const annotation = buildClipAnnotation(spec, Math.max(0, startAt));
-
-  // Same block → rewrite the line in place (preserves position).
-  if (headingIndexAbove(lines, fromIdx) === targetIdx0) {
-    lines[fromIdx] = annotation;
-    return lines.join('\n');
-  }
-
-  // Cross-block → remove the source line and insert into the target block,
-  // right after its heading on its own paragraph.
-  lines.splice(fromIdx, 1);
-  let targetIdx = targetIdx0;
-  if (fromIdx < targetIdx) targetIdx -= 1;
-  lines.splice(targetIdx + 1, 0, '', annotation);
-  return lines.join('\n');
-}