@bendyline/squisq 2.1.0 → 2.2.0

package/src/transform/types.ts

@@ -1,158 +0,0 @@
-/**
- * Transform Types
- *
- * Defines the type system for doc block transforms — algorithms that take
- * an existing Doc and produce a new Doc with blocks optimized for visual
- * presentation. Transforms are read-only on the input and deterministic.
- */
-
-import type { Doc } from '../schemas/Doc.js';
-import type { ExtractionType } from '../generate/contentExtractor.js';
-import type { ColorScheme } from '../schemas/BlockTemplates.js';
-
-// ── Style identification ─────────────────────────────────────────
-
-/** Identifier for a built-in or caller-registered transform style. */
-export type TransformStyleId = string;
-
-/** Summary info for UI dropdowns (mirrors getThemeSummaries pattern). */
-export interface TransformStyleSummary {
-  id: TransformStyleId;
-  name: string;
-  description: string;
-}
-
-// ── Style configuration ──────────────────────────────────────────
-
-/** Declarative configuration controlling how a style transforms content. */
-export interface TransformStyleConfig {
-  /** Unique style identifier. */
-  id: TransformStyleId;
-  /** Human-readable name for UI display. */
-  name: string;
-  /** Short description for UI tooltips. */
-  description: string;
-
-  /**
-   * Minimum confidence for extracted elements to become template blocks (0–1).
-   * Higher values = fewer but higher-quality transformations.
-   */
-  minConfidence: number;
-
-  /**
-   * Maximum fraction of blocks that get transformed (0–1).
-   * 0.2 = light touch, 0.8 = aggressive restructuring.
-   */
-  transformRatio: number;
-
-  /** Which extraction types this style prefers, in priority order. */
-  preferredTypes: ExtractionType[];
-
-  /** Color schemes to rotate through on template blocks. */
-  colorSchemes: ColorScheme[];
-
-  /** Whether to insert sectionHeader blocks between groups. */
-  insertSectionHeaders: boolean;
-
-  /** Whether to interleave imageWithCaption blocks when images are available. */
-  interleaveImages: boolean;
-
-  /** Maximum template blocks promoted per source section. */
-  blocksPerSection: { max: number };
-
-  /** Transition style preference for transformed blocks. */
-  transitionStyle: 'cut' | 'fade' | 'dissolve' | 'mixed';
-
-  /**
-   * Per-style extraction→template remapping. Falls back to the fixed
-   * default map in `generate/templateMapper.ts` for unmapped types.
-   * Only text-compatible targets are honored (see
-   * `translateTemplateBlock`) — an unknown pairing keeps the default.
-   */
-  templateMap?: Partial<Record<ExtractionType, string>>;
-
-  /**
-   * Theme this style pairs best with. Consumers (CLI, editor preview)
-   * apply it only when the doc doesn't already declare a `themeId`.
-   */
-  suggestedThemeId?: string;
-
-  /** Optional opening/closing beats added around the transformed doc. */
-  pacing?: {
-    /** Prepend a `title` block built from the doc's title. */
-    intro?: boolean;
-    /** Append a closing beat (best unused quote/impact line, else a sectionHeader). */
-    outro?: boolean;
-  };
-
-  /**
-   * Duration-based slide budget (folded in from the since-removed
-   * `generateSlideshow`): caps promoted template blocks at roughly
-   * `slidesPerMinute` of doc duration (default: uncapped — only
-   * `transformRatio` applies).
-   */
-  budget?: {
-    /** Target promoted blocks per minute of content (e.g. 5). */
-    slidesPerMinute?: number;
-  };
-
-  /**
-   * Page (linear) mode hints for docs produced by this style. Consumers
-   * pass this as `MaterializePageSectionsOptions.transformPage` so the
-   * summarization strategy shapes the page rendition (spacing, emphasis).
-   */
-  page?: import('../doc/page/materializePageSection.js').PageTransformHints;
-}
-
-/** 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. */
-export interface TransformImage {
-  /** Image source path or URL. */
-  src: string;
-  /** Alt text for accessibility. */
-  alt?: string;
-  /** Photo credit. */
-  credit?: string;
-  /** License identifier. */
-  license?: string;
-}
-
-/** Options passed to `applyTransform()`. */
-export interface TransformOptions {
-  /** Deterministic seed. Default: hash of doc.articleId. */
-  seed?: number;
-  /** Available images for image interleaving / accent images. */
-  images?: TransformImage[];
-  /** Theme ID to embed in the output Doc. */
-  themeId?: string;
-  /** Override specific style config values. */
-  overrides?: Partial<TransformStyleConfig>;
-  /** Caller-owned registry used when `style` is an id. */
-  registry?: TransformStyleRegistry;
-}
-
-// ── Transform result ─────────────────────────────────────────────
-
-/** Result of applying a transform. */
-export interface TransformResult {
-  /** The transformed Doc. Input doc is NOT mutated. */
-  doc: Doc;
-  /** Statistics about what changed. */
-  stats: {
-    totalInputBlocks: number;
-    transformedBlocks: number;
-    insertedBlocks: number;
-  };
-}

package/src/versions/DocumentVersionManager.ts

@@ -1,70 +0,0 @@
-/**
- * Convenience wrapper around the version operations that captures a
- * {@link ContentContainer} reference and an optional basename override.
- *
- * Hosts that prefer a stable handle (e.g. to pass into a UI component)
- * use this; everything it does is also reachable as a free function.
- */
-
-import type { ContentContainer } from '../storage/ContentContainer.js';
-import {
-  coalesceVersions,
-  listVersions,
-  pruneVersions,
-  readVersion,
-  revertToVersion,
-  saveVersion,
-} from './operations.js';
-import type {
-  CoalesceOptions,
-  PrunePolicy,
-  RevertOptions,
-  SaveVersionOptions,
-  SaveVersionResult,
-  Version,
-} from './types.js';
-
-export interface DocumentVersionManagerOptions {
-  /**
-   * Override the document basename used in version filenames. Defaults to
-   * the basename of `container.getDocumentPath()` resolved at call time.
-   */
-  basename?: string;
-}
-
-export class DocumentVersionManager {
-  private readonly container: ContentContainer;
-  private readonly basename: string | undefined;
-
-  constructor(container: ContentContainer, options: DocumentVersionManagerOptions = {}) {
-    this.container = container;
-    this.basename = options.basename;
-  }
-
-  saveVersion(options: SaveVersionOptions = {}): Promise<SaveVersionResult> {
-    return saveVersion(this.container, { basename: this.basename, ...options });
-  }
-
-  listVersions(): Promise<Version[]> {
-    return listVersions(this.container, this.basename);
-  }
-
-  readVersion(version: Version | string): Promise<string | null> {
-    return readVersion(this.container, version);
-  }
-
-  revertToVersion(
-    version: Version | string,
-    options?: RevertOptions,
-  ): Promise<{ reverted: boolean; snapshotted: Version | null }> {
-    return revertToVersion(this.container, version, options);
-  }
-
-  pruneVersions(policy: PrunePolicy): Promise<Version[]> {
-    return pruneVersions(this.container, policy, this.basename);
-  }
-
-  coalesceVersions(options?: CoalesceOptions): Promise<Version[]> {
-    return coalesceVersions(this.container, options, this.basename);
-  }
-}

package/src/versions/gitignore.ts

@@ -1,34 +0,0 @@
-/**
- * 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

@@ -1,56 +0,0 @@
-/**
- * Document version history for Squisq.
- *
- * 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
- * are written only when the document differs from the latest one.
- *
- * @example
- * ```ts
- * import { DocumentVersionManager } from '@bendyline/squisq/versions';
- *
- * const versioning = new DocumentVersionManager(container);
- * const result = await versioning.saveVersion();
- * if (result.saved) console.log('Stamped', result.version);
- *
- * const history = await versioning.listVersions();
- * await versioning.revertToVersion(history[0]);
- * await versioning.pruneVersions({ type: 'keep-last-n', n: 50 });
- * ```
- */
-
-export type {
-  Version,
-  SaveVersionOptions,
-  SaveVersionResult,
-  PrunePolicy,
-  RevertOptions,
-  CoalesceOptions,
-} from './types.js';
-
-export {
-  saveVersion,
-  listVersions,
-  readVersion,
-  revertToVersion,
-  pruneVersions,
-  coalesceVersions,
-} from './operations.js';
-
-export {
-  DocumentVersionManager,
-  type DocumentVersionManagerOptions,
-} from './DocumentVersionManager.js';
-
-export {
-  formatVersionTimestamp,
-  parseVersionTimestamp,
-  VERSION_TIMESTAMP_PATTERN,
-} from './timestamp.js';
-
-export { VERSIONS_PREFIX, getDocBasename, buildVersionPath, parseVersionPath } from './paths.js';

package/src/versions/operations.ts

@@ -1,144 +0,0 @@
-/**
- * Pure-ish version operations against a {@link ContentContainer}.
- *
- * These functions are the canonical implementation. {@link DocumentVersionManager}
- * is a thin wrapper that captures a container reference for ergonomics.
- */
-
-import type { ContentContainer } from '../storage/ContentContainer.js';
-import { DOCUMENT_VERSION_PATHS, getDocBasename } from './paths.js';
-import {
-  coalesceSnapshots,
-  listSnapshots,
-  pruneSnapshots,
-  readTextSnapshot,
-  saveTextSnapshot,
-} from './snapshotStore.js';
-import type {
-  CoalesceOptions,
-  PrunePolicy,
-  RevertOptions,
-  SaveVersionOptions,
-  SaveVersionResult,
-  Version,
-} from './types.js';
-
-async function resolveBasename(
-  container: ContentContainer,
-  override: string | undefined,
-): Promise<string | null> {
-  if (override) return override;
-  const docPath = await container.getDocumentPath();
-  if (!docPath) return null;
-  return getDocBasename(docPath);
-}
-
-async function resolveDocPath(container: ContentContainer): Promise<string> {
-  // Default to `index.md` when the container has no document yet — matches
-  // `MemoryContentContainer.writeDocument`'s default.
-  const docPath = await container.getDocumentPath();
-  return docPath ?? 'index.md';
-}
-
-/**
- * List all snapshots in the container, newest-first.
- *
- * @param basename Optional filter: when set, only versions whose basename
- *   matches are returned.
- */
-export async function listVersions(
-  container: ContentContainer,
-  basename?: string,
-): Promise<Version[]> {
-  return listSnapshots(container, DOCUMENT_VERSION_PATHS, basename);
-}
-
-/**
- * Read the markdown content of a snapshot. Returns null if the snapshot
- * doesn't exist.
- */
-export async function readVersion(
-  container: ContentContainer,
-  version: Version | string,
-): Promise<string | null> {
-  return readTextSnapshot(container, version);
-}
-
-/**
- * Save a new snapshot of the document if its content differs from the
- * latest existing snapshot.
- */
-export async function saveVersion(
-  container: ContentContainer,
-  options: SaveVersionOptions = {},
-): Promise<SaveVersionResult> {
-  const content = options.content ?? (await container.readDocument());
-  if (content === null || content === undefined) {
-    return { saved: false, version: null, reason: 'no-document' };
-  }
-  if (content.length === 0) {
-    return { saved: false, version: null, reason: 'empty' };
-  }
-
-  const basename = await resolveBasename(container, options.basename);
-  if (!basename) {
-    return { saved: false, version: null, reason: 'no-document' };
-  }
-
-  return saveTextSnapshot(container, DOCUMENT_VERSION_PATHS, {
-    content,
-    basename,
-    mimeType: 'text/markdown',
-    now: options.now,
-    force: options.force,
-  });
-}
-
-/**
- * Revert the document to a prior snapshot. By default, the *current*
- * document is snapshotted first so the revert is itself recoverable.
- */
-export async function revertToVersion(
-  container: ContentContainer,
-  version: Version | string,
-  options: RevertOptions = {},
-): Promise<{ reverted: boolean; snapshotted: Version | null }> {
-  const content = await readVersion(container, version);
-  if (content === null) {
-    return { reverted: false, snapshotted: null };
-  }
-
-  let snapshotted: Version | null = null;
-  if (options.snapshotCurrent !== false) {
-    const result = await saveVersion(container);
-    snapshotted = result.version;
-  }
-
-  const docPath = await resolveDocPath(container);
-  await container.writeDocument(content, docPath);
-  return { reverted: true, snapshotted };
-}
-
-/**
- * Delete snapshots that don't satisfy the policy. Returns the deleted
- * versions in their original (newest-first) order.
- */
-export async function pruneVersions(
-  container: ContentContainer,
-  policy: PrunePolicy,
-  basename?: string,
-): Promise<Version[]> {
-  return pruneSnapshots(container, DOCUMENT_VERSION_PATHS, policy, basename);
-}
-
-/**
- * Collapse adjacent snapshots that occurred close together — keeping the
- * newer one — to keep history readable across rapid edits.
- */
-export async function coalesceVersions(
-  container: ContentContainer,
-  options: CoalesceOptions = {},
-  basename?: string,
-): Promise<Version[]> {
-  return coalesceSnapshots(container, DOCUMENT_VERSION_PATHS, options, basename);
-}

package/src/versions/paths.ts

@@ -1,51 +0,0 @@
-/**
- * Path conventions for version snapshots.
- *
- * Snapshots live at `<VERSIONS_PREFIX><basename>.<timestamp>[<-suffix>].md`.
- * The optional numeric suffix (`-2`, `-3`, ...) is appended only when two
- * snapshots collide on the same UTC second.
- */
-
-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`.
- */
-export function getDocBasename(documentPath: string): string {
-  const slash = documentPath.lastIndexOf('/');
-  const file = slash >= 0 ? documentPath.slice(slash + 1) : documentPath;
-  const dot = file.lastIndexOf('.');
-  return dot > 0 ? file.slice(0, dot) : file;
-}
-
-/**
- * Build a version snapshot path. Optionally append a collision suffix
- * (e.g. `2`, `3`) when two saves land on the same UTC second.
- */
-export function buildVersionPath(basename: string, date: Date, collision = 0): string {
-  return buildSnapshotPath(DOCUMENT_VERSION_PATHS, basename, date, collision);
-}
-
-/**
- * Parse a version snapshot path. Returns null if it doesn't match the
- * convention (so unrelated files stored under `.versions/` are ignored).
- */
-export function parseVersionPath(
-  path: string,
-): { basename: string; timestamp: Date; collision: number } | null {
-  return parseSnapshotPath(DOCUMENT_VERSION_PATHS, path);
-}