@bendyline/squisq 1.3.0 → 1.4.0

package/dist/story/index.js

@@ -1,5 +1,6 @@
 import {
   DEFAULT_LAYOUT,
+  TEMPLATE_ALIASES,
   adjustY,
   comparisonBar,
   countBlocks,
@@ -31,6 +32,7 @@ import {
   getTransitionClass,
   hasTemplate,
   imageWithCaption,
+  leftFeature,
   listBlock,
   mapBlock,
   markdownToDoc,
@@ -39,6 +41,8 @@ import {
   quoteBlock,
   resolveAudioMapping,
   resolveColorScheme,
+  resolveTemplateName,
+  rightFeature,
   scaleAnimationDuration,
   scoreTextSimilarity,
   sectionHeader,
@@ -50,13 +54,13 @@ import {
   twoColumn,
   videoPullQuote,
   videoWithCaption
-} from "../chunk-6BAVXFYC.js";
+} from "../chunk-KSWJR66U.js";
 import {
   DEFAULT_THEME,
   getAvailableThemes,
   getThemeSummaries,
   resolveTheme
-} from "../chunk-FIQR4AJG.js";
+} from "../chunk-B4EEON3N.js";
 import {
   VIEWPORT_PRESETS,
   createTemplateContext,
@@ -66,13 +70,14 @@ import {
   getViewportOrientation,
   isTemplateBlock,
   scaledFontSize2 as scaledFontSize
-} from "../chunk-QM5PKNPW.js";
-import "../chunk-7GF6RDED.js";
+} from "../chunk-5WFRKURX.js";
+import "../chunk-H3AXU4MJ.js";
 import "../chunk-4X3JQXNM.js";
 import "../chunk-3E5F2XMR.js";
 export {
   DEFAULT_LAYOUT,
   DEFAULT_THEME,
+  TEMPLATE_ALIASES,
   VIEWPORT_PRESETS,
   adjustY,
   comparisonBar,
@@ -113,6 +118,7 @@ export {
   hasTemplate,
   imageWithCaption,
   isTemplateBlock,
+  leftFeature,
   listBlock,
   mapBlock,
   markdownToDoc,
@@ -121,7 +127,9 @@ export {
   quoteBlock,
   resolveAudioMapping,
   resolveColorScheme,
+  resolveTemplateName,
   resolveTheme,
+  rightFeature,
   scaleAnimationDuration,
   scaledFontSize,
   scoreTextSimilarity,

package/dist/themeLibrary-BHjJ0Qx6.d.ts

@@ -0,0 +1,40 @@
+import { af as Theme } from './Doc-BeSeH2iX.js';
+
+/**
+ * Built-in Theme Library
+ *
+ * Public entry point for theme lookup. Built-in themes live as JSON
+ * sidecars in [./themes/](./themes/) — they share the exact same shape
+ * as customizer-authored themes (no two-tier distinction).
+ *
+ * Usage:
+ * ```ts
+ * import { THEMES, resolveTheme } from '@bendyline/squisq/schemas';
+ *
+ * const theme = resolveTheme('minimalist'); // by id, with registry override
+ * const theme = THEMES.documentary;         // direct access to a built-in
+ * ```
+ */
+
+/** All built-in themes, keyed by id. */
+declare const THEMES: Record<string, Theme>;
+/** The default theme id. */
+declare const DEFAULT_THEME_ID = "standard";
+/** The default theme (standard — safe system fonts, no external dependencies). */
+declare const DEFAULT_THEME: Theme;
+/**
+ * Resolve a theme by id. Custom themes registered via `registerTheme()`
+ * take precedence over built-ins; otherwise built-ins are searched and
+ * the default theme is returned for unknown ids.
+ */
+declare function resolveTheme(id: string | undefined): Theme;
+/** Get all built-in theme ids. */
+declare function getAvailableThemes(): string[];
+/** Get a summary of all built-in themes (id + name + description) for theme pickers. */
+declare function getThemeSummaries(): Array<{
+    id: string;
+    name: string;
+    description?: string;
+}>;
+
+export { DEFAULT_THEME as D, THEMES as T, DEFAULT_THEME_ID as a, getThemeSummaries as b, getAvailableThemes as g, resolveTheme as r };

package/dist/{types-CkNttVSF.d.ts → types-BdZkdJ3z.d.ts}

@@ -394,6 +394,21 @@ interface MarkdownInlineMath extends MarkdownNodeBase {
     /** Math content (without $ delimiters) */
     value: string;
 }
+/**
+ * Inline FontAwesome icon. Authored as `{[name]}` (bare) or
+ * `{[fa-<family>:name]}` (qualified) in markdown source. The parser
+ * resolves the token against the FA Free catalog and emits this node;
+ * unknown / ambiguous tokens stay as literal text.
+ */
+interface MarkdownInlineIcon extends MarkdownNodeBase {
+    type: 'inlineIcon';
+    /** Token exactly as authored — e.g. `github` or `fa-solid:user`. */
+    token: string;
+    /** Resolved icon family. */
+    family: 'brands' | 'solid' | 'regular';
+    /** Resolved icon name (without the `fa-` prefix). */
+    name: string;
+}
 /**
  * A footnote reference [^id]. GFM extension.
  */
@@ -455,7 +470,7 @@ interface MarkdownTextDirective extends MarkdownNodeBase {
  */
 interface MarkdownMention extends MarkdownNodeBase {
     type: 'mention';
-    /** Namespace for the mentioned entity (e.g. `"gezel"`, `"user"`). */
+    /** Namespace for the mentioned entity (e.g. `"user"`). */
     targetKind: string;
     /** Stable identifier within the namespace. */
     targetId: string;
@@ -465,7 +480,7 @@ interface MarkdownMention extends MarkdownNodeBase {
 /** Block-level content that can appear as direct children of the document root, blockquotes, list items, etc. */
 type MarkdownBlockNode = MarkdownHeading | MarkdownParagraph | MarkdownBlockquote | MarkdownList | MarkdownCodeBlock | MarkdownThematicBreak | MarkdownTable | MarkdownHtmlBlock | MarkdownMathBlock | MarkdownLinkDefinition | MarkdownFootnoteDefinition | MarkdownContainerDirective | MarkdownLeafDirective | MarkdownDefinitionList;
 /** Inline/phrasing content that appears inside paragraphs, headings, links, etc. */
-type MarkdownInlineNode = MarkdownText | MarkdownEmphasis | MarkdownStrong | MarkdownStrikethrough | MarkdownInlineCode | MarkdownLink | MarkdownImage | MarkdownBreak | MarkdownInlineHtml | MarkdownInlineMath | MarkdownFootnoteReference | MarkdownLinkReference | MarkdownImageReference | MarkdownTextDirective | MarkdownMention;
+type MarkdownInlineNode = MarkdownText | MarkdownEmphasis | MarkdownStrong | MarkdownStrikethrough | MarkdownInlineCode | MarkdownLink | MarkdownImage | MarkdownBreak | MarkdownInlineHtml | MarkdownInlineMath | MarkdownFootnoteReference | MarkdownLinkReference | MarkdownImageReference | MarkdownTextDirective | MarkdownMention | MarkdownInlineIcon;
 /**
  * Any node in the markdown tree. Includes structural nodes (listItem,
  * tableRow, tableCell, etc.) that only appear as children of specific parents.

package/dist/types-D98li1gV.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Public types for the document version-history feature.
+ *
+ * Versions are snapshots of the primary markdown document stored alongside
+ * the document inside the same {@link ContentContainer}. They live under
+ * `.versions/<docBasename>.<sortableTimestamp>.md`. The container is the
+ * unit of persistence — when the host serializes the container to a ZIP,
+ * a real folder, or anywhere else, the version snapshots ride along.
+ */
+/**
+ * A single version snapshot record.
+ */
+interface Version {
+    /** Container-relative path, e.g. `.versions/index.20260430T152030Z.md`. */
+    path: string;
+    /** Document basename without extension, e.g. `index`. */
+    basename: string;
+    /** Parsed timestamp from the filename, in UTC. */
+    timestamp: Date;
+    /** Snapshot size in bytes. */
+    size: number;
+    /**
+     * Collision suffix index. `0` for a path with no `-N` suffix, `1` for `-2`,
+     * `2` for `-3`, and so on. Used as the tie-break for ordering snapshots
+     * that share the same UTC second.
+     */
+    collision: number;
+}
+/**
+ * Result of a {@link saveVersion} call.
+ */
+interface SaveVersionResult {
+    /** True when a new snapshot file was actually written. */
+    saved: boolean;
+    /** The newly stamped version (only when `saved` is true). */
+    version: Version | null;
+    /**
+     * Why the save behaved the way it did:
+     * - `'saved'`        — a new snapshot was written.
+     * - `'unchanged'`    — current content matches the latest snapshot byte-for-byte.
+     * - `'no-document'`  — the container has no primary markdown document.
+     * - `'empty'`        — the resolved content was empty.
+     */
+    reason: 'saved' | 'unchanged' | 'no-document' | 'empty';
+}
+/**
+ * Options for {@link saveVersion}.
+ */
+interface SaveVersionOptions {
+    /** Override the document content; otherwise the container's primary doc is read. */
+    content?: string;
+    /** Override the timestamp; defaults to `new Date()`. Useful for tests. */
+    now?: Date;
+    /** Skip the diff-vs-latest check and force a write. */
+    force?: boolean;
+    /** Override the document basename used to build the version filename. */
+    basename?: string;
+}
+/**
+ * Pruning policy passed to {@link pruneVersions}.
+ */
+type PrunePolicy = {
+    type: 'keep-last-n';
+    n: number;
+} | {
+    type: 'older-than';
+    date: Date;
+} | {
+    type: 'predicate';
+    keep: (v: Version, all: Version[]) => boolean;
+};
+/**
+ * Options for {@link revertToVersion}.
+ */
+interface RevertOptions {
+    /**
+     * Whether to snapshot the current document content before replacing it.
+     * Defaults to `true` so a revert is always recoverable.
+     */
+    snapshotCurrent?: boolean;
+}
+/**
+ * Options for {@link coalesceVersions}.
+ */
+interface CoalesceOptions {
+    /**
+     * Two adjacent snapshots whose timestamps are within `windowMs` collapse
+     * to the newer one. Defaults to 60_000 (one minute).
+     */
+    windowMs?: number;
+}
+
+export type { CoalesceOptions as C, PrunePolicy as P, RevertOptions as R, SaveVersionOptions as S, Version as V, SaveVersionResult as a };

package/dist/versions/DocumentVersionManager.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 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 declare class DocumentVersionManager {
+    private readonly container;
+    private readonly basename;
+    constructor(container: ContentContainer, options?: DocumentVersionManagerOptions);
+    saveVersion(options?: SaveVersionOptions): Promise<SaveVersionResult>;
+    listVersions(): Promise<Version[]>;
+    readVersion(version: Version | string): Promise<string | null>;
+    revertToVersion(version: Version | string, options?: RevertOptions): Promise<{
+        reverted: boolean;
+        snapshotted: Version | null;
+    }>;
+    pruneVersions(policy: PrunePolicy): Promise<Version[]>;
+    coalesceVersions(options?: CoalesceOptions): Promise<Version[]>;
+}
+//# sourceMappingURL=DocumentVersionManager.d.ts.map

package/dist/versions/DocumentVersionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentVersionManager.d.ts","sourceRoot":"","sources":["../../src/versions/DocumentVersionManager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AASvE,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,OAAO,EACR,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;gBAElC,SAAS,EAAE,gBAAgB,EAAE,OAAO,GAAE,6BAAkC;IAKpF,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIzE,YAAY,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAIlC,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAI9D,eAAe,CACb,OAAO,EAAE,OAAO,GAAG,MAAM,EACzB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC;IAI9D,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAItD,gBAAgB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAGhE"}

package/dist/versions/DocumentVersionManager.js

@@ -0,0 +1,33 @@
+/**
+ * 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 { coalesceVersions, listVersions, pruneVersions, readVersion, revertToVersion, saveVersion, } from './operations.js';
+export class DocumentVersionManager {
+    constructor(container, options = {}) {
+        this.container = container;
+        this.basename = options.basename;
+    }
+    saveVersion(options = {}) {
+        return saveVersion(this.container, { basename: this.basename, ...options });
+    }
+    listVersions() {
+        return listVersions(this.container, this.basename);
+    }
+    readVersion(version) {
+        return readVersion(this.container, version);
+    }
+    revertToVersion(version, options) {
+        return revertToVersion(this.container, version, options);
+    }
+    pruneVersions(policy) {
+        return pruneVersions(this.container, policy, this.basename);
+    }
+    coalesceVersions(options) {
+        return coalesceVersions(this.container, options, this.basename);
+    }
+}
+//# sourceMappingURL=DocumentVersionManager.js.map

package/dist/versions/DocumentVersionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentVersionManager.js","sourceRoot":"","sources":["../../src/versions/DocumentVersionManager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,eAAe,EACf,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAkBzB,MAAM,OAAO,sBAAsB;IAIjC,YAAY,SAA2B,EAAE,UAAyC,EAAE;QAClF,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IACnC,CAAC;IAED,WAAW,CAAC,UAA8B,EAAE;QAC1C,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,YAAY;QACV,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED,WAAW,CAAC,OAAyB;QACnC,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,eAAe,CACb,OAAyB,EACzB,OAAuB;QAEvB,OAAO,eAAe,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED,aAAa,CAAC,MAAmB;QAC/B,OAAO,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9D,CAAC;IAED,gBAAgB,CAAC,OAAyB;QACxC,OAAO,gBAAgB,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClE,CAAC;CACF"}

package/dist/versions/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Document version history for Squisq.
+ *
+ * Snapshots of the primary markdown document live inside the same
+ * {@link ContentContainer} at `.versions/<basename>.<timestamp>.md`.
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/versions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/versions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,YAAY,EACV,OAAO,EACP,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,eAAe,EACf,aAAa,EACb,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/versions/index.js

@@ -0,0 +1,28 @@
+/**
+ * Document version history for Squisq.
+ *
+ * Snapshots of the primary markdown document live inside the same
+ * {@link ContentContainer} at `.versions/<basename>.<timestamp>.md`.
+ * 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 { saveVersion, listVersions, readVersion, revertToVersion, pruneVersions, coalesceVersions, } from './operations.js';
+export { DocumentVersionManager, } from './DocumentVersionManager.js';
+export { formatVersionTimestamp, parseVersionTimestamp, VERSION_TIMESTAMP_PATTERN, } from './timestamp.js';
+export { VERSIONS_PREFIX, getDocBasename, buildVersionPath, parseVersionPath } from './paths.js';
+//# sourceMappingURL=index.js.map

package/dist/versions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/versions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH,OAAO,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,eAAe,EACf,aAAa,EACb,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,sBAAsB,GAEvB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/versions/operations.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 type { CoalesceOptions, PrunePolicy, RevertOptions, SaveVersionOptions, SaveVersionResult, Version } from './types.js';
+/**
+ * List all snapshots in the container, newest-first.
+ *
+ * @param basename Optional filter: when set, only versions whose basename
+ *   matches are returned.
+ */
+export declare function listVersions(container: ContentContainer, basename?: string): Promise<Version[]>;
+/**
+ * Read the markdown content of a snapshot. Returns null if the snapshot
+ * doesn't exist.
+ */
+export declare function readVersion(container: ContentContainer, version: Version | string): Promise<string | null>;
+/**
+ * Save a new snapshot of the document if its content differs from the
+ * latest existing snapshot.
+ */
+export declare function saveVersion(container: ContentContainer, options?: SaveVersionOptions): Promise<SaveVersionResult>;
+/**
+ * Revert the document to a prior snapshot. By default, the *current*
+ * document is snapshotted first so the revert is itself recoverable.
+ */
+export declare function revertToVersion(container: ContentContainer, version: Version | string, options?: RevertOptions): Promise<{
+    reverted: boolean;
+    snapshotted: Version | null;
+}>;
+/**
+ * Delete snapshots that don't satisfy the policy. Returns the deleted
+ * versions in their original (newest-first) order.
+ */
+export declare function pruneVersions(container: ContentContainer, policy: PrunePolicy, basename?: string): Promise<Version[]>;
+/**
+ * Collapse adjacent snapshots that occurred close together — keeping the
+ * newer one — to keep history readable across rapid edits.
+ */
+export declare function coalesceVersions(container: ContentContainer, options?: CoalesceOptions, basename?: string): Promise<Version[]>;
+//# sourceMappingURL=operations.d.ts.map

package/dist/versions/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/versions/operations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAEvE,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,OAAO,EACR,MAAM,YAAY,CAAC;AAsBpB;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,gBAAgB,EAC3B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,EAAE,CAAC,CAyBpB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,OAAO,GAAG,MAAM,GACxB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKxB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,gBAAgB,EAC3B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CA0C5B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,OAAO,GAAG,MAAM,EACzB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,CAAC,CAe7D;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,gBAAgB,EAC3B,MAAM,EAAE,WAAW,EACnB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,EAAE,CAAC,CAsBpB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,gBAAgB,EAC3B,OAAO,GAAE,eAAoB,EAC7B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,EAAE,CAAC,CAyBpB"}

package/dist/versions/operations.js

@@ -0,0 +1,190 @@
+/**
+ * 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 { buildVersionPath, getDocBasename, parseVersionPath, VERSIONS_PREFIX } from './paths.js';
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+async function resolveBasename(container, override) {
+    if (override)
+        return override;
+    const docPath = await container.getDocumentPath();
+    if (!docPath)
+        return null;
+    return getDocBasename(docPath);
+}
+async function resolveDocPath(container) {
+    // 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, basename) {
+    const entries = await container.listFiles(VERSIONS_PREFIX);
+    const versions = [];
+    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;
+}
+/**
+ * Read the markdown content of a snapshot. Returns null if the snapshot
+ * doesn't exist.
+ */
+export async function readVersion(container, version) {
+    const path = typeof version === 'string' ? version : version.path;
+    const data = await container.readFile(path);
+    if (!data)
+        return null;
+    return decoder.decode(data);
+}
+/**
+ * Save a new snapshot of the document if its content differs from the
+ * latest existing snapshot.
+ */
+export async function saveVersion(container, options = {}) {
+    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' };
+    }
+    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 = {
+        path,
+        basename,
+        timestamp: now,
+        size: data.byteLength,
+        collision,
+    };
+    return { saved: true, version, reason: 'saved' };
+}
+/**
+ * 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, version, options = {}) {
+    const content = await readVersion(container, version);
+    if (content === null) {
+        return { reverted: false, snapshotted: null };
+    }
+    let snapshotted = 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, policy, basename) {
+    const versions = await listVersions(container, basename);
+    const toDelete = [];
+    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;
+}
+/**
+ * Collapse adjacent snapshots that occurred close together — keeping the
+ * newer one — to keep history readable across rapid edits.
+ */
+export async function coalesceVersions(container, options = {}, basename) {
+    const windowMs = options.windowMs ?? 60000;
+    const versions = await listVersions(container, basename);
+    const toDelete = [];
+    // 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;
+}
+//# sourceMappingURL=operations.js.map

package/dist/versions/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/versions/operations.ts"],"names":[],"mappings":"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"}