@neta-art/cohub 3.0.0 → 3.2.0

package/dist/board/core/draw-geometry.js

@@ -0,0 +1,183 @@
+//#region src/board/core/draw-geometry.ts
+/** Radius of a sample in world units given the stroke size and pressure. */
+function sampleRadius(size, pressure) {
+	const clamped = Math.min(1, Math.max(0, pressure));
+	return Math.max(.5, size / 2 * (.5 + clamped));
+}
+/** Axis-aligned bounds of a stroke in its local space, padded by stroke width. */
+function computeDrawBounds(points, size) {
+	if (points.length === 0) return {
+		x: 0,
+		y: 0,
+		width: 1,
+		height: 1
+	};
+	let minX = Number.POSITIVE_INFINITY;
+	let minY = Number.POSITIVE_INFINITY;
+	let maxX = Number.NEGATIVE_INFINITY;
+	let maxY = Number.NEGATIVE_INFINITY;
+	for (const point of points) {
+		const r = sampleRadius(size, point.p);
+		minX = Math.min(minX, point.x - r);
+		minY = Math.min(minY, point.y - r);
+		maxX = Math.max(maxX, point.x + r);
+		maxY = Math.max(maxY, point.y + r);
+	}
+	return {
+		x: minX,
+		y: minY,
+		width: Math.max(1, maxX - minX),
+		height: Math.max(1, maxY - minY)
+	};
+}
+/**
+* Ramer–Douglas–Peucker simplification. Reduces point count for low-zoom
+* rendering without touching the persisted raw samples. Returns indices into
+* the input so callers can keep pressure alongside the simplified path.
+*/
+function simplifyDrawIndices(points, tolerance) {
+	const n = points.length;
+	if (n <= 2 || tolerance <= 0) return points.map((_, i) => i);
+	const keep = new Array(n).fill(false);
+	keep[0] = true;
+	keep[n - 1] = true;
+	const stack = [[0, n - 1]];
+	while (stack.length > 0) {
+		const segment = stack.pop();
+		if (!segment) break;
+		const [start, end] = segment;
+		let maxDist = -1;
+		let index = -1;
+		const a = points[start];
+		const b = points[end];
+		if (!a || !b) continue;
+		for (let i = start + 1; i < end; i += 1) {
+			const point = points[i];
+			if (!point) continue;
+			const d = perpendicularDistance(point, a, b);
+			if (d > maxDist) {
+				maxDist = d;
+				index = i;
+			}
+		}
+		if (maxDist > tolerance && index !== -1) {
+			keep[index] = true;
+			stack.push([start, index], [index, end]);
+		}
+	}
+	const out = [];
+	for (let i = 0; i < n; i += 1) if (keep[i]) out.push(i);
+	return out;
+}
+function perpendicularDistance(point, a, b) {
+	const dx = b.x - a.x;
+	const dy = b.y - a.y;
+	const lengthSq = dx * dx + dy * dy;
+	if (lengthSq === 0) return Math.hypot(point.x - a.x, point.y - a.y);
+	const t = ((point.x - a.x) * dx + (point.y - a.y) * dy) / lengthSq;
+	const projX = a.x + t * dx;
+	const projY = a.y + t * dy;
+	return Math.hypot(point.x - projX, point.y - projY);
+}
+/**
+* Build a closed outline polygon for a variable-width stroke. The left side is
+* offset outward along each segment normal by the sample radius, the right side
+* mirrored, producing a smooth ribbon that widens with pressure. Suitable for a
+* filled Pixi polygon. Returns an empty array for degenerate input.
+*/
+function buildStrokeOutline(points, size) {
+	const n = points.length;
+	if (n === 0) return [];
+	const first = points[0];
+	if (!first) return [];
+	if (n === 1) {
+		const r = sampleRadius(size, first.p);
+		const p = first;
+		const k = r * Math.SQRT1_2;
+		return [
+			{
+				x: p.x,
+				y: p.y - r
+			},
+			{
+				x: p.x + k,
+				y: p.y - k
+			},
+			{
+				x: p.x + r,
+				y: p.y
+			},
+			{
+				x: p.x + k,
+				y: p.y + k
+			},
+			{
+				x: p.x,
+				y: p.y + r
+			},
+			{
+				x: p.x - k,
+				y: p.y + k
+			},
+			{
+				x: p.x - r,
+				y: p.y
+			},
+			{
+				x: p.x - k,
+				y: p.y - k
+			}
+		];
+	}
+	const left = [];
+	const right = [];
+	for (let i = 0; i < n; i += 1) {
+		const current = points[i];
+		const prev = points[Math.max(0, i - 1)] ?? current;
+		const next = points[Math.min(n - 1, i + 1)] ?? current;
+		if (!current || !prev || !next) continue;
+		let dx = next.x - prev.x;
+		let dy = next.y - prev.y;
+		const len = Math.hypot(dx, dy) || 1;
+		dx /= len;
+		dy /= len;
+		const nx = -dy;
+		const ny = dx;
+		const r = sampleRadius(size, current.p);
+		left.push({
+			x: current.x + nx * r,
+			y: current.y + ny * r
+		});
+		right.push({
+			x: current.x - nx * r,
+			y: current.y - ny * r
+		});
+	}
+	return [...left, ...right.reverse()];
+}
+/**
+* Distance from a world point to the stroke's polyline, in the shape's local
+* space. Used for hit testing: a hit registers within half the stroke width plus
+* a small tolerance. `local` is the point expressed in the draw item's frame.
+*/
+function distanceToStroke(points, local) {
+	if (points.length === 0) return Number.POSITIVE_INFINITY;
+	const first = points[0];
+	if (!first) return Number.POSITIVE_INFINITY;
+	if (points.length === 1) return Math.hypot(local.x - first.x, local.y - first.y);
+	let min = Number.POSITIVE_INFINITY;
+	for (let i = 0; i < points.length - 1; i += 1) {
+		const from = points[i];
+		const to = points[i + 1];
+		if (!from || !to) continue;
+		const d = perpendicularDistance({
+			x: local.x,
+			y: local.y,
+			p: 0
+		}, from, to);
+		if (d < min) min = d;
+	}
+	return min;
+}
+//#endregion
+export { buildStrokeOutline, computeDrawBounds, distanceToStroke, sampleRadius, simplifyDrawIndices };

package/dist/board/core/export-assets.d.ts

@@ -0,0 +1,14 @@
+import { BoardItem } from "../../protocol/dist/board-document.js";
+//#region src/board/core/export-assets.d.ts
+/** Bound source textures independently from the final output bitmap budget. */
+declare const BOARD_EXPORT_MAX_TEXTURES = 64;
+type BoardExportAssetSelection = {
+  /** One representative item for each selected preview key. */
+  items: BoardItem[];
+  keys: string[];
+  omittedKeys: string[];
+};
+/** Select a stable, document-ordered set of unique preview assets to load. */
+declare function selectBoardExportAssets(items: BoardItem[], assetKey: (item: BoardItem) => string | null, maxTextures?: number): BoardExportAssetSelection;
+//#endregion
+export { BOARD_EXPORT_MAX_TEXTURES, BoardExportAssetSelection, selectBoardExportAssets };

package/dist/board/core/export-assets.js

@@ -0,0 +1,22 @@
+//#region src/board/core/export-assets.ts
+/** Bound source textures independently from the final output bitmap budget. */
+const BOARD_EXPORT_MAX_TEXTURES = 64;
+/** Select a stable, document-ordered set of unique preview assets to load. */
+function selectBoardExportAssets(items, assetKey, maxTextures = 64) {
+	const limit = Number.isSafeInteger(maxTextures) ? Math.max(0, maxTextures) : 64;
+	const selected = /* @__PURE__ */ new Map();
+	const omitted = /* @__PURE__ */ new Set();
+	for (const item of items) {
+		const key = assetKey(item);
+		if (!key || selected.has(key) || omitted.has(key)) continue;
+		if (selected.size < limit) selected.set(key, item);
+		else omitted.add(key);
+	}
+	return {
+		items: [...selected.values()],
+		keys: [...selected.keys()],
+		omittedKeys: [...omitted]
+	};
+}
+//#endregion
+export { BOARD_EXPORT_MAX_TEXTURES, selectBoardExportAssets };

package/dist/board/core/export-plan.d.ts

@@ -0,0 +1,84 @@
+import { BoardDocument, BoardItem } from "../../protocol/dist/board-document.js";
+import { Rect } from "../geometry.js";
+import { FrameLookup } from "./bindings.js";
+//#region src/board/core/export-plan.d.ts
+/** What part of the board to capture. */
+type BoardExportRegion =
+/** Everything in the document. */
+{
+  kind: "all";
+} |
+/** Exactly these items, whatever else overlaps them. */
+{
+  kind: "items";
+  ids: string[];
+} |
+/** A frame item's rect, treated as a page: its chrome is excluded. */
+{
+  kind: "frame";
+  id: string;
+} |
+/** An explicit world-space rect. */
+{
+  kind: "rect";
+  rect: Rect;
+};
+type BoardExportPlanInput = {
+  document: BoardDocument;
+  region: BoardExportRegion;
+  /** Output pixels per world unit. Defaults to 2 (retina-grade). */
+  scale?: number;
+  /** World-space breathing room around the content. Frames use 0. */
+  padding?: number;
+  maxEdge?: number;
+  maxPixels?: number;
+};
+type BoardExportPlan = {
+  /** World-space rect captured, padding included. */
+  world: Rect;
+  /** Scale actually used, after clamping. */
+  scale: number;
+  /** Scale asked for, before clamping. */
+  requestedScale: number;
+  /** Output size in pixels. */
+  width: number;
+  height: number;
+  /** Items to draw, in document order. */
+  items: BoardItem[];
+  /** True when `scale` had to be reduced to fit the size budget. */
+  clamped: boolean;
+};
+/**
+ * Normalise a document before it reaches the renderers.
+ *
+ * Renderers read shape fields directly and assume schema defaults have been
+ * applied — a hand-built or partially-migrated document would otherwise reach
+ * them with missing fields. Parsing here means every entry point (CLI, web,
+ * tests) gets the same guarantee, and an invalid document fails with a schema
+ * error instead of a render-time crash.
+ */
+declare function normalizeBoardDocument(document: BoardDocument): BoardDocument;
+/**
+ * Hard ceilings.
+ *
+ * `MAX_EDGE` stays under the 8192 texture limit that essentially every WebGL2
+ * and Canvas2D backend guarantees. `MAX_PIXELS` bounds peak memory instead of
+ * edge length — a 8192×8192 RGBA buffer alone is 256MB, which is enough to kill
+ * a browser tab, so the total is capped well below the square of the edge.
+ */
+declare const BOARD_EXPORT_MAX_EDGE = 8192;
+declare const BOARD_EXPORT_MAX_PIXELS = 32000000;
+declare const BOARD_EXPORT_DEFAULT_SCALE = 2;
+declare const BOARD_EXPORT_DEFAULT_PADDING = 32;
+/** Above this, an export is still produced but the caller is warned. */
+declare const BOARD_EXPORT_ITEM_WARN_THRESHOLD = 2000;
+declare function boardFrameLookup(document: BoardDocument): FrameLookup;
+/** Bounds of a single item, resolving arrow endpoints through their bindings. */
+declare function exportItemBounds(item: BoardItem, getFrame: FrameLookup): Rect;
+/**
+ * Resolve a region into a concrete capture plan, or null when there is nothing
+ * to draw. Callers treat null as "empty selection", not as an error.
+ */
+declare function planBoardExport(input: BoardExportPlanInput): BoardExportPlan | null;
+//#endregion
+export { BOARD_EXPORT_DEFAULT_PADDING, BOARD_EXPORT_DEFAULT_SCALE, BOARD_EXPORT_ITEM_WARN_THRESHOLD, BOARD_EXPORT_MAX_EDGE, BOARD_EXPORT_MAX_PIXELS, BoardExportPlan, BoardExportPlanInput, BoardExportRegion, boardFrameLookup, exportItemBounds, normalizeBoardDocument, planBoardExport };

package/dist/board/core/export-plan.js

@@ -0,0 +1,128 @@
+import { BoardDocumentSchema } from "../../protocol/dist/board-document.js";
+import { itemBounds, rectsIntersect, unionRects } from "../geometry.js";
+import { arrowBounds } from "./bindings.js";
+//#region src/board/core/export-plan.ts
+/**
+* Export planning — pure geometry, no renderer.
+*
+* Every platform (browser, CLI) resolves *what* to capture and *how large* the
+* result may be through this module, so a `--scale 4` on a huge board behaves
+* identically everywhere and no caller can accidentally ask the GPU for a
+* texture it cannot allocate.
+*/
+/**
+* Normalise a document before it reaches the renderers.
+*
+* Renderers read shape fields directly and assume schema defaults have been
+* applied — a hand-built or partially-migrated document would otherwise reach
+* them with missing fields. Parsing here means every entry point (CLI, web,
+* tests) gets the same guarantee, and an invalid document fails with a schema
+* error instead of a render-time crash.
+*/
+function normalizeBoardDocument(document) {
+	return BoardDocumentSchema.parse(document);
+}
+/**
+* Hard ceilings.
+*
+* `MAX_EDGE` stays under the 8192 texture limit that essentially every WebGL2
+* and Canvas2D backend guarantees. `MAX_PIXELS` bounds peak memory instead of
+* edge length — a 8192×8192 RGBA buffer alone is 256MB, which is enough to kill
+* a browser tab, so the total is capped well below the square of the edge.
+*/
+const BOARD_EXPORT_MAX_EDGE = 8192;
+const BOARD_EXPORT_MAX_PIXELS = 32e6;
+const BOARD_EXPORT_DEFAULT_SCALE = 2;
+const BOARD_EXPORT_DEFAULT_PADDING = 32;
+/** Above this, an export is still produced but the caller is warned. */
+const BOARD_EXPORT_ITEM_WARN_THRESHOLD = 2e3;
+function boardFrameLookup(document) {
+	const frames = new Map(document.items.map((item) => [item.id, item.frame]));
+	return (id) => frames.get(id);
+}
+/** Bounds of a single item, resolving arrow endpoints through their bindings. */
+function exportItemBounds(item, getFrame) {
+	if (item.type === "arrow") return arrowBounds(item, getFrame) ?? itemBounds(item.frame);
+	return itemBounds(item.frame);
+}
+function resolveRegion(document, region, getFrame) {
+	switch (region.kind) {
+		case "all": return {
+			items: document.items,
+			rect: unionRects(document.items.map((item) => exportItemBounds(item, getFrame))),
+			padding: null
+		};
+		case "items": {
+			const wanted = new Set(region.ids);
+			const items = document.items.filter((item) => wanted.has(item.id));
+			return {
+				items,
+				rect: unionRects(items.map((item) => exportItemBounds(item, getFrame))),
+				padding: null
+			};
+		}
+		case "frame": {
+			const frame = document.items.find((item) => item.id === region.id);
+			if (!frame) return {
+				items: [],
+				rect: null,
+				padding: null
+			};
+			const rect = itemBounds(frame.frame);
+			return {
+				items: document.items.filter((item) => item.id !== region.id && rectsIntersect(exportItemBounds(item, getFrame), rect)),
+				rect,
+				padding: 0
+			};
+		}
+		case "rect": {
+			const rect = region.rect;
+			return {
+				items: document.items.filter((item) => rectsIntersect(exportItemBounds(item, getFrame), rect)),
+				rect,
+				padding: 0
+			};
+		}
+	}
+}
+/**
+* Largest scale that keeps the output inside both the edge and pixel budgets.
+*
+* There is deliberately no lower bound: a floor here would silently let a very
+* large world exceed the budgets it exists to enforce (a 1e6×1e6 region at a
+* 0.01 floor is 1e8 pixels). Callers see the reduction via `plan.clamped`.
+*/
+function clampScale(requested, world, maxEdge, maxPixels) {
+	const byEdge = Math.min(maxEdge / world.width, maxEdge / world.height);
+	const byArea = Math.sqrt(maxPixels / (world.width * world.height));
+	return Math.min(requested, byEdge, byArea);
+}
+/**
+* Resolve a region into a concrete capture plan, or null when there is nothing
+* to draw. Callers treat null as "empty selection", not as an error.
+*/
+function planBoardExport(input) {
+	const { document, region, scale: requestedScale = 2, maxEdge = BOARD_EXPORT_MAX_EDGE, maxPixels = BOARD_EXPORT_MAX_PIXELS } = input;
+	const resolved = resolveRegion(document, region, boardFrameLookup(document));
+	if (!resolved.rect) return null;
+	const padding = input.padding ?? resolved.padding ?? 32;
+	const world = {
+		x: resolved.rect.x - padding,
+		y: resolved.rect.y - padding,
+		width: Math.max(1, resolved.rect.width + padding * 2),
+		height: Math.max(1, resolved.rect.height + padding * 2)
+	};
+	const safeRequest = Number.isFinite(requestedScale) && requestedScale > 0 ? requestedScale : 2;
+	const scale = clampScale(safeRequest, world, maxEdge, maxPixels);
+	return {
+		world,
+		scale,
+		requestedScale,
+		width: Math.max(1, Math.floor(world.width * scale)),
+		height: Math.max(1, Math.floor(world.height * scale)),
+		items: resolved.items,
+		clamped: scale < safeRequest - 1e-6
+	};
+}
+//#endregion
+export { BOARD_EXPORT_DEFAULT_PADDING, BOARD_EXPORT_DEFAULT_SCALE, BOARD_EXPORT_ITEM_WARN_THRESHOLD, BOARD_EXPORT_MAX_EDGE, BOARD_EXPORT_MAX_PIXELS, boardFrameLookup, exportItemBounds, normalizeBoardDocument, planBoardExport };

package/dist/board/core/file-preview.d.ts

@@ -0,0 +1,176 @@
+//#region src/board/core/file-preview.d.ts
+/**
+ * File-card preview derivation — pure, renderer-agnostic, dependency-free.
+ *
+ * A board file card is a *thumbnail entry point* to a workspace file, never a
+ * second copy of it. So everything here derives display facts from file content
+ * that the caller already has, and the resulting snapshot is treated strictly as
+ * a cache keyed by the file's mtime: the file on disk stays the single source of
+ * truth, and nothing in this module ever writes back to it.
+ *
+ * Three presentation tiers fall out of which facts are available, so an
+ * unrecognised file degrades instead of being rejected:
+ *
+ * - `cover` — a cover image was declared in markdown frontmatter;
+ * - `text`  — text-like content yielded a readable excerpt;
+ * - `blank` — anything else (binary, empty, oversized): icon, name and type.
+ */
+/** Hard cap on a stored excerpt. Board cards show a few lines at most, and the
+ * snapshot rides along in every board transaction — so this stays small. */
+declare const FILE_EXCERPT_MAX_CHARS = 480;
+/** Files above this size are shown as `blank`; we never pull them for a preview. */
+declare const FILE_EXCERPT_MAX_BYTES: number;
+type FilePreviewKind = "cover" | "text" | "blank";
+/**
+ * Cached display facts for a file node. Every field is derived from the file and
+ * carries `mtimeMs` so a stale snapshot is detectable rather than silently wrong.
+ */
+type BoardFileSnapshotFacts = {
+  title?: string;
+  mimeType?: string;
+  size?: number;
+  mtimeMs?: number;
+  /** Cleaned leading prose, capped at FILE_EXCERPT_MAX_CHARS. */
+  excerpt?: string;
+  /** Cover declared as a path inside the space, resolved against the file's dir. */
+  coverPath?: string;
+  /** Cover declared as an absolute `https:` URL. */
+  coverUrl?: string;
+};
+/**
+ * Which tier a card renders at. Derived rather than stored: presentation follows
+ * from the facts present, so there is no second piece of state to fall out of
+ * sync with them.
+ */
+declare function filePreviewKind(snapshot: BoardFileSnapshotFacts | undefined): FilePreviewKind;
+/** Short uppercase type label for the card's meta line (`MD`, `JSON`, `FILE`). */
+declare function fileTypeLabel(path: string): string;
+/** Human-readable byte size for the meta line. */
+declare function formatFileSize(bytes: number | undefined): string;
+/**
+ * A cover reference, classified by how it must be loaded.
+ *
+ * `http:` is rejected in favour of `https:` (a board should not downgrade the
+ * page to mixed content), and `data:`/`blob:` are rejected because they would
+ * embed opaque, unbounded bytes into board data that no other client can verify.
+ * Everything else is treated as a path inside the space.
+ */
+type ResolvedCover = {
+  kind: "url";
+  url: string;
+} | {
+  kind: "path";
+  path: string;
+} | null;
+/** Normalise a space-relative path: resolve `.`/`..` against the file's dir. */
+declare function resolveSpacePath(fromFilePath: string, ref: string): string;
+/**
+ * Classify a raw cover reference from frontmatter.
+ *
+ * Remote covers are allowed on purpose — a lot of real markdown points at a CDN.
+ * The trade-off is that opening such a board issues a request to that third
+ * party; the renderer degrades silently if it fails, and nothing is retried in a
+ * loop.
+ */
+declare function resolveCoverRef(fromFilePath: string, raw: string | undefined | null): ResolvedCover;
+/** A frontmatter block's raw body plus the content that followed it. */
+type SplitSource = {
+  frontmatter: string | null;
+  body: string;
+};
+/**
+ * Split leading YAML frontmatter from a markdown source. Deliberately minimal:
+ * this only needs the raw block so a handful of scalar keys can be read, not a
+ * YAML parser.
+ */
+declare function splitFrontmatter(source: string): SplitSource;
+/**
+ * Read the first cover-ish scalar from a frontmatter block.
+ *
+ * Only top-level keys are considered (a leading-space line is nested and skipped)
+ * so `cover:` under some other mapping cannot be mistaken for the file's own.
+ */
+declare function readCoverFromFrontmatter(frontmatter: string | null): string | null;
+/**
+ * Reduce source text to a short, readable excerpt.
+ *
+ * The goal is a card-sized hint of what the file is about, so markdown
+ * decoration is flattened rather than rendered: fenced code is dropped whole
+ * (it reads as noise at thumbnail size), headings and emphasis lose their
+ * markers, links keep their text, and blank runs collapse.
+ */
+declare function buildFileExcerpt(source: string, limit?: number): string;
+type BuildSnapshotInput = {
+  path: string;
+  /** File text, when it could be read as text. Omit for binary/oversized. */
+  content?: string | null;
+  title?: string;
+  mimeType?: string | null;
+  size?: number;
+  mtimeMs?: number;
+};
+/** Basename of a path, used as the default card title. */
+declare function fileBaseName(path: string): string;
+/**
+ * Build the cached display facts for a file node.
+ *
+ * Content is optional by design: a snapshot built without it still produces a
+ * usable `blank` card, so a node can be created the instant a file is dropped
+ * and enriched later without blocking on a read.
+ */
+declare function buildFileSnapshot(input: BuildSnapshotInput): BoardFileSnapshotFacts;
+/** Whether a snapshot's cached facts still describe the file on disk. */
+declare function isFileSnapshotFresh(snapshot: BoardFileSnapshotFacts | undefined, file: {
+  mtimeMs?: number;
+  size?: number;
+}): boolean;
+/** Whether a file is small enough that fetching a text preview is worthwhile. */
+declare function shouldFetchFileExcerpt(input: {
+  mimeType?: string | null;
+  size?: number;
+}): boolean;
+/**
+ * Whether a referenced file could be read, and if not, whether that is known to
+ * be permanent.
+ *
+ * This distinction is the whole point: a board is a long-lived document, and a
+ * card should not claim a file is gone because the network blipped. It is also
+ * why availability is client-local transient state and never written to the
+ * node — see the note in board-file-preview-source.
+ */
+type FileAvailability = "ok" | "missing" | "unavailable";
+/**
+ * Classify a failed read.
+ *
+ * Only a 404 (or 410 Gone) is treated as the file being absent. Everything else
+ * — offline, 5xx, timeout, 401/403 — is `unavailable`: the file may well exist and
+ * simply not be reachable by this client right now.
+ */
+declare function availabilityFromError(error: unknown): FileAvailability;
+/**
+ * Cache key for a file within a space.
+ *
+ * A path only means anything relative to its space, and identical paths across
+ * spaces are the norm ("README.md"), so every preview cache is keyed by both. The
+ * separator is NUL because it cannot appear in a space id or a path, so no path can
+ * be crafted to collide with another space's entry.
+ */
+declare function filePreviewScope(spaceId: string, path: string): string;
+/**
+ * Cache key for one *version* of a file. The mtime is part of the key so a changed
+ * file misses the cache instead of serving a stale excerpt or cover.
+ */
+declare function filePreviewMemoKey(spaceId: string, path: string, mtimeMs?: number): string;
+/**
+ * Fold a freshly read snapshot into the cached one.
+ *
+ * `complete` decides whether the incoming facts supersede the cached ones or are
+ * merged over them, and the difference is not cosmetic. A snapshot omits fields the
+ * file does not have, so merging a complete read would resurrect a cover or an
+ * excerpt the file no longer contains — permanently, since the stale value is then
+ * committed back. Merging is right only for an incomplete read, where an absent
+ * field means "could not establish", not "not there".
+ */
+declare function mergeFileSnapshot(cached: BoardFileSnapshotFacts | undefined, incoming: BoardFileSnapshotFacts, complete: boolean): BoardFileSnapshotFacts;
+//#endregion
+export { BoardFileSnapshotFacts, BuildSnapshotInput, FILE_EXCERPT_MAX_BYTES, FILE_EXCERPT_MAX_CHARS, FileAvailability, FilePreviewKind, ResolvedCover, availabilityFromError, buildFileExcerpt, buildFileSnapshot, fileBaseName, filePreviewKind, filePreviewMemoKey, filePreviewScope, fileTypeLabel, formatFileSize, isFileSnapshotFresh, mergeFileSnapshot, readCoverFromFrontmatter, resolveCoverRef, resolveSpacePath, shouldFetchFileExcerpt, splitFrontmatter };