@bendyline/squisq 1.5.2 → 2.0.0

package/src/transform/timingAllocator.ts

@@ -33,6 +33,24 @@ export function allocateTiming(
 ): Block[] {
   if (blocks.length === 0) return [];
 
+  // Template blocks carrying a numeric `sourceStartTime` are ANCHORED to
+  // the doc timeline — when the source doc is narration-timed
+  // (`applyNarrationTiming`), those anchors are where the words are
+  // actually spoken, and rescaling would tear the slides away from the
+  // voice. Anchored blocks keep their positions; floating blocks
+  // (intro/outro bookends, section headers, interleaved images) fill the
+  // gaps between anchors. With no anchors at all, behavior is the
+  // historical rescale-to-fit.
+  const hasAnchors = blocks.some(
+    (b) => isTemplateBlock(b) && typeof b.sourceStartTime === 'number',
+  );
+  return hasAnchors
+    ? allocateAnchored(blocks, totalDuration)
+    : allocateRescaled(blocks, totalDuration);
+}
+
+/** Historical behavior: scale every duration to fill the total, clamp 3–20 s. */
+function allocateRescaled(blocks: Array<Block | TemplateBlock>, totalDuration: number): Block[] {
   const effectiveDuration = totalDuration > 0 ? totalDuration : estimateDefaultDuration(blocks);
 
   // First pass: assign raw durations
@@ -59,37 +77,150 @@ export function allocateTiming(
   // Second pass: assign startTimes and build output Blocks
   let currentTime = 0;
   const result: Block[] = [];
-
   for (let i = 0; i < blocks.length; i++) {
-    const block = blocks[i];
-    const duration = durations[i];
+    result.push(toOutputBlock(blocks[i], currentTime, durations[i]));
+    currentTime += durations[i];
+  }
+  return result;
+}
+
+/** Minimum duration for a floating block squeezed between anchors. */
+const MIN_FLOATING_DURATION = 1;
 
+/**
+ * Anchor-aware allocation: anchored entries (template blocks with a
+ * numeric `sourceStartTime`, and untransformed source Blocks with their
+ * own real timing) are PLACED at their timeline positions; runs of
+ * floating blocks (bookends, headers, images) distribute across the gap
+ * before the next anchor. Durations then derive from consecutive starts
+ * so the timeline stays CONTIGUOUS — a slide summarizing unpromoted
+ * source content simply holds until the next slide begins, which is
+ * what keeps every narration second covered by some block.
+ */
+function allocateAnchored(blocks: Array<Block | TemplateBlock>, totalDuration: number): Block[] {
+  interface Entry {
+    block: Block | TemplateBlock;
+    anchorStart: number | null;
+    rawDuration: number;
+  }
+  const entries: Entry[] = blocks.map((block) => {
     if (isTemplateBlock(block)) {
-      // Convert TemplateBlock to Block shell, preserving all template-specific
-      // fields (stat, quote, description, etc.) so they survive through to
-      // the player's template expansion step.
-      const outputBlock = {
-        ...block,
-        startTime: currentTime,
-        duration,
-        title: getTemplateTitle(block),
-      } as unknown as Block;
-      result.push(outputBlock);
-    } else {
-      // Existing block — update timing
-      result.push({
-        ...block,
-        startTime: currentTime,
-        duration,
-      });
+      return {
+        block,
+        anchorStart: typeof block.sourceStartTime === 'number' ? block.sourceStartTime : null,
+        rawDuration: block.duration > 0 ? block.duration : DEFAULT_BLOCK_DURATION,
+      };
+    }
+    // Untransformed source blocks carry real (possibly narration) timing.
+    return {
+      block,
+      anchorStart: block.startTime,
+      rawDuration: block.duration > 0 ? block.duration : DEFAULT_BLOCK_DURATION,
+    };
+  });
+
+  // Pass 1: starts. Anchors pin their positions (the cursor then jumps
+  // past the anchor's authored span, so following floats land AFTER it).
+  // Float runs place differently by position: LEADING floats (before any
+  // anchor — intro bookends) fill the opening gap from t=0; MID floats
+  // (section headers, images) end-align just before the next anchor —
+  // a header belongs to the section it introduces; TRAILING floats
+  // (outro) run sequentially after the last anchor's span.
+  const starts = new Array<number>(entries.length);
+  let cursor = 0;
+  let seenAnchor = false;
+  let i = 0;
+  while (i < entries.length) {
+    const entry = entries[i];
+    if (entry.anchorStart !== null) {
+      const start = Math.max(cursor, entry.anchorStart);
+      starts[i] = start;
+      const hint = isTemplateBlock(entry.block)
+        ? (entry.block.sourceDuration ?? entry.rawDuration)
+        : entry.rawDuration;
+      cursor = start + Math.max(MIN_FLOATING_DURATION, hint);
+      seenAnchor = true;
+      i++;
+      continue;
     }
+    const runStart = i;
+    while (i < entries.length && entries[i].anchorStart === null) i++;
+    const run = entries.slice(runStart, i);
+    const rawSum = run.reduce((sum, e) => sum + e.rawDuration, 0);
+    const nextAnchorStart =
+      i < entries.length ? Math.max(entries[i].anchorStart ?? cursor, cursor) : null;
 
-    currentTime += duration;
+    if (nextAnchorStart === null) {
+      // Trailing floats: natural sizes after the last anchor's span.
+      let acc = cursor;
+      for (let k = 0; k < run.length; k++) {
+        starts[runStart + k] = acc;
+        acc += run[k].rawDuration;
+      }
+      cursor = acc;
+    } else if (!seenAnchor) {
+      // Leading floats: fill [cursor, nextAnchorStart) proportionally.
+      const gap = nextAnchorStart - cursor;
+      let acc = cursor;
+      for (let k = 0; k < run.length; k++) {
+        starts[runStart + k] = acc;
+        acc += rawSum > 0 ? (run[k].rawDuration / rawSum) * gap : gap / run.length;
+      }
+      cursor = nextAnchorStart;
+    } else {
+      // Mid floats: end-aligned at natural size, capped by the gap.
+      const gap = Math.max(0, nextAnchorStart - cursor);
+      const scale = rawSum > 0 ? Math.min(1, gap / rawSum) : 0;
+      let acc = Math.max(cursor, nextAnchorStart - rawSum * scale);
+      for (let k = 0; k < run.length; k++) {
+        starts[runStart + k] = acc;
+        acc += run[k].rawDuration * scale;
+      }
+      cursor = nextAnchorStart;
+    }
   }
 
+  // Pass 2: strictly increasing starts, then contiguous durations.
+  for (let k = 0; k < starts.length; k++) {
+    const floor = k > 0 ? starts[k - 1] + MIN_FLOATING_DURATION : 0;
+    if (starts[k] < floor) starts[k] = floor;
+  }
+  const result: Block[] = [];
+  for (let k = 0; k < entries.length; k++) {
+    const entry = entries[k];
+    let duration: number;
+    if (k + 1 < entries.length) {
+      duration = Math.max(MIN_FLOATING_DURATION, starts[k + 1] - starts[k]);
+    } else {
+      const authored = isTemplateBlock(entry.block)
+        ? (entry.block.sourceDuration ?? entry.rawDuration)
+        : entry.rawDuration;
+      // The final block covers through the end of the doc/narration when
+      // the caller knows it runs longer.
+      duration = Math.max(MIN_FLOATING_DURATION, authored, totalDuration - starts[k]);
+    }
+    result.push(toOutputBlock(entry.block, starts[k], duration));
+  }
   return result;
 }
 
+/**
+ * Convert an entry to an output Block shell. Template blocks preserve all
+ * template-specific fields (stat, quote, description, …) so they survive
+ * through to the player's template expansion step.
+ */
+function toOutputBlock(block: Block | TemplateBlock, startTime: number, duration: number): Block {
+  if (isTemplateBlock(block)) {
+    return {
+      ...block,
+      startTime,
+      duration,
+      title: getTemplateTitle(block),
+    } as unknown as Block;
+  }
+  return { ...block, startTime, duration };
+}
+
 /** Clamp a duration to the min/max range. */
 function clampDuration(d: number): number {
   return Math.max(MIN_BLOCK_DURATION, Math.min(MAX_BLOCK_DURATION, d));

package/src/transform/types.ts

@@ -12,7 +12,7 @@ import type { ColorScheme } from '../schemas/BlockTemplates.js';
 
 // ── Style identification ─────────────────────────────────────────
 
-/** Identifier for a registered transform style. */
+/** Identifier for a built-in or caller-registered transform style. */
 export type TransformStyleId = string;
 
 /** Summary info for UI dropdowns (mirrors getThemeSummaries pattern). */
@@ -97,6 +97,17 @@ export interface TransformStyleConfig {
   };
 }
 
+/** Built-in id or a call-scoped declarative style definition. */
+export type TransformStyleInput = TransformStyleId | TransformStyleConfig;
+
+/** Explicit caller-owned registry for custom transform styles. */
+export interface TransformStyleRegistry {
+  register(style: TransformStyleConfig): void;
+  unregister(id: string): boolean;
+  get(id: string): TransformStyleConfig | undefined;
+  list(): TransformStyleConfig[];
+}
+
 // ── Transform options ────────────────────────────────────────────
 
 /** Image metadata for image interleaving. */
@@ -121,6 +132,8 @@ export interface TransformOptions {
   themeId?: string;
   /** Override specific style config values. */
   overrides?: Partial<TransformStyleConfig>;
+  /** Caller-owned registry used when `style` is an id. */
+  registry?: TransformStyleRegistry;
 }
 
 // ── Transform result ─────────────────────────────────────────────

package/src/versions/gitignore.ts

@@ -0,0 +1,34 @@
+/**
+ * Keep version snapshots out of Git when a ContentContainer is persisted
+ * as a real folder (typically a `<basename>_files/` sidecar).
+ */
+
+import type { ContentContainer } from '../storage/ContentContainer.js';
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+const GITIGNORE_PATH = '.gitignore';
+const VERSIONS_IGNORE_RULE = '.versions/';
+const EQUIVALENT_VERSIONS_RULE = /^(!?)\/?\.versions\/?$/;
+
+/**
+ * Ensure the container-root `.gitignore` ignores its `.versions/` folder.
+ * Existing rules and newline style are preserved.
+ */
+export async function ensureVersionsGitIgnored(container: ContentContainer): Promise<void> {
+  const data = await container.readFile(GITIGNORE_PATH);
+  const existing = data ? decoder.decode(data) : '';
+
+  let alreadyIgnored = false;
+  for (const line of existing.split(/\r?\n/)) {
+    const match = EQUIVALENT_VERSIONS_RULE.exec(line.trim());
+    if (match) alreadyIgnored = match[1] !== '!';
+  }
+  if (alreadyIgnored) return;
+
+  const newline = existing.includes('\r\n') ? '\r\n' : '\n';
+  const separator = existing.length > 0 && !existing.endsWith('\n') ? newline : '';
+  const next = `${existing}${separator}${VERSIONS_IGNORE_RULE}${newline}`;
+  await container.writeFile(GITIGNORE_PATH, encoder.encode(next), 'text/plain');
+}

package/src/versions/index.ts

@@ -3,6 +3,8 @@
  *
  * Snapshots of the primary markdown document live inside the same
  * {@link ContentContainer} at `.versions/<basename>.<timestamp>.md`.
+ * When a snapshot is retained, the container root also gets a `.gitignore`
+ * rule for `.versions/`, preserving any existing ignore rules.
  * Hosts call {@link DocumentVersionManager.saveVersion} (or the
  * underlying {@link saveVersion}) when they want to stamp a new version;
  * the editor's auto-save effect calls it on idle. Either way, snapshots

package/src/versions/operations.ts

@@ -6,7 +6,14 @@
  */
 
 import type { ContentContainer } from '../storage/ContentContainer.js';
-import { buildVersionPath, getDocBasename, parseVersionPath, VERSIONS_PREFIX } from './paths.js';
+import { DOCUMENT_VERSION_PATHS, getDocBasename } from './paths.js';
+import {
+  coalesceSnapshots,
+  listSnapshots,
+  pruneSnapshots,
+  readTextSnapshot,
+  saveTextSnapshot,
+} from './snapshotStore.js';
 import type {
   CoalesceOptions,
   PrunePolicy,
@@ -16,9 +23,6 @@ import type {
   Version,
 } from './types.js';
 
-const decoder = new TextDecoder();
-const encoder = new TextEncoder();
-
 async function resolveBasename(
   container: ContentContainer,
   override: string | undefined,
@@ -46,30 +50,7 @@ export async function listVersions(
   container: ContentContainer,
   basename?: string,
 ): Promise<Version[]> {
-  const entries = await container.listFiles(VERSIONS_PREFIX);
-  const versions: Version[] = [];
-  for (const entry of entries) {
-    const parsed = parseVersionPath(entry.path);
-    if (!parsed) continue;
-    if (basename !== undefined && parsed.basename !== basename) continue;
-    versions.push({
-      path: entry.path,
-      basename: parsed.basename,
-      timestamp: parsed.timestamp,
-      size: entry.size,
-      collision: parsed.collision,
-    });
-  }
-  // Newest first. Tie-break on collision (higher = newer). Compare the
-  // numeric collision rather than the path string: lexicographically a path
-  // with no suffix sorts *after* one with `-N`, because `.` (0x2E) is
-  // greater than `-` (0x2D), which would invert the order.
-  versions.sort((a, b) => {
-    const dt = b.timestamp.getTime() - a.timestamp.getTime();
-    if (dt !== 0) return dt;
-    return b.collision - a.collision;
-  });
-  return versions;
+  return listSnapshots(container, DOCUMENT_VERSION_PATHS, basename);
 }
 
 /**
@@ -80,10 +61,7 @@ export async function readVersion(
   container: ContentContainer,
   version: Version | string,
 ): Promise<string | null> {
-  const path = typeof version === 'string' ? version : version.path;
-  const data = await container.readFile(path);
-  if (!data) return null;
-  return decoder.decode(data);
+  return readTextSnapshot(container, version);
 }
 
 /**
@@ -107,34 +85,13 @@ export async function saveVersion(
     return { saved: false, version: null, reason: 'no-document' };
   }
 
-  const versions = await listVersions(container, basename);
-  if (!options.force && versions.length > 0) {
-    const latest = versions[0]!;
-    const existing = await readVersion(container, latest);
-    if (existing === content) {
-      return { saved: false, version: null, reason: 'unchanged' };
-    }
-  }
-
-  const now = options.now ?? new Date();
-  let collision = 0;
-  let path = buildVersionPath(basename, now, collision);
-  while (await container.exists(path)) {
-    collision += 1;
-    path = buildVersionPath(basename, now, collision);
-  }
-
-  const data = encoder.encode(content);
-  await container.writeFile(path, data, 'text/markdown');
-
-  const version: Version = {
-    path,
+  return saveTextSnapshot(container, DOCUMENT_VERSION_PATHS, {
+    content,
     basename,
-    timestamp: now,
-    size: data.byteLength,
-    collision,
-  };
-  return { saved: true, version, reason: 'saved' };
+    mimeType: 'text/markdown',
+    now: options.now,
+    force: options.force,
+  });
 }
 
 /**
@@ -171,27 +128,7 @@ export async function pruneVersions(
   policy: PrunePolicy,
   basename?: string,
 ): Promise<Version[]> {
-  const versions = await listVersions(container, basename);
-  const toDelete: Version[] = [];
-
-  if (policy.type === 'keep-last-n') {
-    const n = Math.max(0, Math.floor(policy.n));
-    toDelete.push(...versions.slice(n));
-  } else if (policy.type === 'older-than') {
-    const cutoff = policy.date.getTime();
-    for (const v of versions) {
-      if (v.timestamp.getTime() < cutoff) toDelete.push(v);
-    }
-  } else {
-    for (const v of versions) {
-      if (!policy.keep(v, versions)) toDelete.push(v);
-    }
-  }
-
-  for (const v of toDelete) {
-    await container.removeFile(v.path);
-  }
-  return toDelete;
+  return pruneSnapshots(container, DOCUMENT_VERSION_PATHS, policy, basename);
 }
 
 /**
@@ -203,28 +140,5 @@ export async function coalesceVersions(
   options: CoalesceOptions = {},
   basename?: string,
 ): Promise<Version[]> {
-  const windowMs = options.windowMs ?? 60_000;
-  const versions = await listVersions(container, basename);
-  const toDelete: Version[] = [];
-  // Walk newest -> oldest, anchored to the last *kept* snapshot. Any
-  // candidate within `windowMs` of the anchor is dropped; the first one
-  // outside the window becomes the new anchor. Comparing each pair against
-  // its previous neighbor instead would chain through deleted snapshots
-  // and over-prune any tightly-clustered run (e.g. 30s apart with a 60s
-  // window collapses to a single survivor).
-  if (versions.length > 0) {
-    let anchor = versions[0]!;
-    for (let i = 1; i < versions.length; i++) {
-      const candidate = versions[i]!;
-      if (anchor.timestamp.getTime() - candidate.timestamp.getTime() <= windowMs) {
-        toDelete.push(candidate);
-      } else {
-        anchor = candidate;
-      }
-    }
-  }
-  for (const v of toDelete) {
-    await container.removeFile(v.path);
-  }
-  return toDelete;
+  return coalesceSnapshots(container, DOCUMENT_VERSION_PATHS, options, basename);
 }

package/src/versions/paths.ts

@@ -6,11 +6,21 @@
  * snapshots collide on the same UTC second.
  */
 
-import { formatVersionTimestamp, parseVersionTimestamp } from './timestamp.js';
+import {
+  buildSnapshotPath,
+  parseSnapshotPath,
+  type SnapshotPathStrategy,
+} from './snapshotStore.js';
 
 /** Subfolder (inside the ContentContainer) that holds version snapshots. */
 export const VERSIONS_PREFIX = '.versions/';
 
+/** Internal strategy shared with the generic snapshot store. */
+export const DOCUMENT_VERSION_PATHS: SnapshotPathStrategy = Object.freeze({
+  prefix: VERSIONS_PREFIX,
+  extension: 'md',
+});
+
 /**
  * Strip the directory and extension from a document path to produce the
  * basename used in version filenames. `subdir/index.md` -> `index`.
@@ -27,9 +37,7 @@ export function getDocBasename(documentPath: string): string {
  * (e.g. `2`, `3`) when two saves land on the same UTC second.
  */
 export function buildVersionPath(basename: string, date: Date, collision = 0): string {
-  const stamp = formatVersionTimestamp(date);
-  const suffix = collision > 0 ? `-${collision + 1}` : '';
-  return `${VERSIONS_PREFIX}${basename}.${stamp}${suffix}.md`;
+  return buildSnapshotPath(DOCUMENT_VERSION_PATHS, basename, date, collision);
 }
 
 /**
@@ -39,28 +47,5 @@ export function buildVersionPath(basename: string, date: Date, collision = 0): s
 export function parseVersionPath(
   path: string,
 ): { basename: string; timestamp: Date; collision: number } | null {
-  if (!path.startsWith(VERSIONS_PREFIX)) return null;
-  const rest = path.slice(VERSIONS_PREFIX.length);
-  if (!rest.endsWith('.md')) return null;
-  const stem = rest.slice(0, -'.md'.length);
-  // basename can contain dots; the timestamp is always the *last* dot-segment
-  // (optionally followed by a `-N` collision suffix).
-  const lastDot = stem.lastIndexOf('.');
-  if (lastDot <= 0) return null;
-  const basename = stem.slice(0, lastDot);
-  const tail = stem.slice(lastDot + 1);
-  const dash = tail.indexOf('-');
-  let stamp: string;
-  let collision = 0;
-  if (dash >= 0) {
-    stamp = tail.slice(0, dash);
-    const n = Number(tail.slice(dash + 1));
-    if (!Number.isInteger(n) || n < 2) return null;
-    collision = n - 1;
-  } else {
-    stamp = tail;
-  }
-  const timestamp = parseVersionTimestamp(stamp);
-  if (!timestamp) return null;
-  return { basename, timestamp, collision };
+  return parseSnapshotPath(DOCUMENT_VERSION_PATHS, path);
 }