@neta-art/cohub 8.10.1 → 8.11.0

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

@@ -1,42 +1,6 @@
+import { BoardFileSnapshotFacts, BuildSnapshotInput, FILE_EXCERPT_MAX_BYTES, FILE_EXCERPT_MAX_CHARS, FileCategory, ResolvedCover, buildCodeExcerpt, buildFileExcerpt, buildFileSnapshot, fileBaseName, fileCategory, fileStem, readCoverFromFrontmatter, readFrontmatterScalars, readTitleFromFrontmatter, resolveCoverRef, resolveFileTitle, resolveSpacePath, shouldFetchFileExcerpt, splitFrontmatter } from "./file-snapshot.js";
 //#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
@@ -47,132 +11,47 @@ declare function filePreviewKind(snapshot: BoardFileSnapshotFacts | undefined):
 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 document title declared by top-level frontmatter. */
-declare function readTitleFromFrontmatter(frontmatter: string | null): string | null;
-/**
- * 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;
+/** `MD · 12 KB` — empty when neither fact is available. */
+declare function fileMetaLine(path: string, size: number | undefined): string;
+/** Map a file category onto an existing palette token. */
+declare function fileCategoryAccent(category: FileCategory, palette: {
+  text: number;
+  rare: number;
+  epic: number;
+  legendary: number;
+  muted: number;
+}): number;
 /** 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 rationale 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.
+ * — offline, 5xx, timeout, 401/403 — is `unavailable`.
  */
 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.
+ * spaces are the norm ("README.md"), so every preview cache is keyed by both.
  */
 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.
+ * 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".
+ * `complete` decides whether the incoming facts supersede the cached ones or
+ * are merged over them. A complete read's omissions are authoritative.
  */
 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, readTitleFromFrontmatter, resolveCoverRef, resolveSpacePath, shouldFetchFileExcerpt, splitFrontmatter };
+export { type BoardFileSnapshotFacts, type BuildSnapshotInput, FILE_EXCERPT_MAX_BYTES, FILE_EXCERPT_MAX_CHARS, FileAvailability, type FileCategory, FilePreviewKind, type ResolvedCover, availabilityFromError, buildCodeExcerpt, buildFileExcerpt, buildFileSnapshot, fileBaseName, fileCategory, fileCategoryAccent, fileMetaLine, filePreviewKind, filePreviewMemoKey, filePreviewScope, fileStem, fileTypeLabel, formatFileSize, isFileSnapshotFresh, mergeFileSnapshot, readCoverFromFrontmatter, readFrontmatterScalars, readTitleFromFrontmatter, resolveCoverRef, resolveFileTitle, resolveSpacePath, shouldFetchFileExcerpt, splitFrontmatter };

package/dist/board/core/file-preview.js

@@ -1,37 +1,6 @@
+import { FILE_EXCERPT_MAX_BYTES, FILE_EXCERPT_MAX_CHARS, buildCodeExcerpt, buildFileExcerpt, buildFileSnapshot, fileBaseName, fileCategory, fileStem, readCoverFromFrontmatter, readFrontmatterScalars, readTitleFromFrontmatter, resolveCoverRef, resolveFileTitle, resolveSpacePath, shouldFetchFileExcerpt, splitFrontmatter } from "./file-snapshot.js";
 //#region src/board/core/file-preview.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. */
-const FILE_EXCERPT_MAX_CHARS = 480;
-/** Files above this size are shown as `blank`; we never pull them for a preview. */
-const FILE_EXCERPT_MAX_BYTES = 262144;
-/** Frontmatter keys checked for a cover image, in precedence order. */
-const COVER_KEYS = [
-	"cover",
-	"coverImage",
-	"cover_image",
-	"image",
-	"banner",
-	"thumbnail",
-	"ogImage",
-	"og:image"
-];
-/**
 * 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.
@@ -67,156 +36,22 @@ function formatFileSize(bytes) {
 	}
 	return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
 }
-/** Normalise a space-relative path: resolve `.`/`..` against the file's dir. */
-function resolveSpacePath(fromFilePath, ref) {
-	const base = ref.startsWith("/") ? [] : fromFilePath.split("/").slice(0, -1).filter(Boolean);
-	const segments = ref.replace(/^\//, "").split("/");
-	const out = [...base];
-	for (const segment of segments) {
-		if (!segment || segment === ".") continue;
-		if (segment === "..") {
-			out.pop();
-			continue;
-		}
-		out.push(segment);
+/** `MD · 12 KB` — empty when neither fact is available. */
+function fileMetaLine(path, size) {
+	const type = fileTypeLabel(path);
+	const formatted = formatFileSize(size);
+	if (type && formatted) return `${type} · ${formatted}`;
+	return formatted || type;
+}
+/** Map a file category onto an existing palette token. */
+function fileCategoryAccent(category, palette) {
+	switch (category) {
+		case "doc": return palette.text;
+		case "code": return palette.rare;
+		case "data": return palette.epic;
+		case "media": return palette.legendary;
+		default: return palette.muted;
 	}
-	return out.join("/");
-}
-/**
-* 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.
-*/
-function resolveCoverRef(fromFilePath, raw) {
-	const value = (raw ?? "").trim();
-	if (!value) return null;
-	if (value.startsWith("//")) return {
-		kind: "url",
-		url: `https:${value}`
-	};
-	const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1]?.toLowerCase();
-	if (scheme) {
-		if (scheme === "https") return {
-			kind: "url",
-			url: value
-		};
-		return null;
-	}
-	const path = resolveSpacePath(fromFilePath, value);
-	return path ? {
-		kind: "path",
-		path
-	} : null;
-}
-/**
-* 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.
-*/
-function splitFrontmatter(source) {
-	if (!/^---[ \t]*\r?\n/.test(source)) return {
-		frontmatter: null,
-		body: source
-	};
-	const lines = source.split(/\r?\n/);
-	for (let index = 1; index < lines.length; index += 1) {
-		const line = lines[index] ?? "";
-		if (line === "---" || line === "...") return {
-			frontmatter: lines.slice(1, index).join("\n"),
-			body: lines.slice(index + 1).join("\n")
-		};
-	}
-	return {
-		frontmatter: null,
-		body: source
-	};
-}
-function unquote(value) {
-	const trimmed = value.trim();
-	if (trimmed.length < 2) return trimmed;
-	const first = trimmed[0];
-	const last = trimmed[trimmed.length - 1];
-	if (first === "\"" && last === "\"" || first === "'" && last === "'") return trimmed.slice(1, -1);
-	return trimmed;
-}
-/** Read non-empty top-level scalar values from a frontmatter block. */
-function readFrontmatterScalars(frontmatter) {
-	const found = /* @__PURE__ */ new Map();
-	if (!frontmatter) return found;
-	for (const line of frontmatter.split(/\r?\n/)) {
-		if (!line.trim() || /^\s/.test(line) || line.trimStart().startsWith("#")) continue;
-		const match = /^([A-Za-z0-9_:.-]+):(.*)$/.exec(line);
-		if (!match) continue;
-		const key = match[1];
-		const value = unquote(match[2] ?? "");
-		if (key && value && !found.has(key)) found.set(key, value);
-	}
-	return found;
-}
-/** Read the document title declared by top-level frontmatter. */
-function readTitleFromFrontmatter(frontmatter) {
-	return readFrontmatterScalars(frontmatter).get("title") ?? null;
-}
-/**
-* 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.
-*/
-function readCoverFromFrontmatter(frontmatter) {
-	const found = readFrontmatterScalars(frontmatter);
-	for (const key of COVER_KEYS) {
-		const value = found.get(key);
-		if (value) return value;
-	}
-	return 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.
-*/
-function buildFileExcerpt(source, limit = 480) {
-	if (!source) return "";
-	const cleaned = source.replace(/```[\s\S]*?(?:```|$)/g, " ").replace(/<!--[\s\S]*?-->/g, " ").replace(/<\/?[a-z][^>]*>/gi, " ").replace(/!\[[^\]]*\]\([^)]*\)/g, " ").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/^[ \t]*#{1,6}[ \t]+/gm, "").replace(/^[ \t]*>[ \t]?/gm, "").replace(/^[ \t]*[-*+][ \t]+/gm, "").replace(/^[ \t]*\d+\.[ \t]+/gm, "").replace(/^[ \t]*([-*_])(?:[ \t]*\1){2,}[ \t]*$/gm, " ").replace(/\|/g, " ").replace(/[*_`~]/g, "").replace(/\r\n?/g, "\n").replace(/[ \t]+/g, " ").replace(/\n{2,}/g, "\n").replace(/[ \t]*\n[ \t]*/g, "\n").trim();
-	if (cleaned.length <= limit) return cleaned;
-	const slice = cleaned.slice(0, limit);
-	const lastSpace = slice.lastIndexOf(" ");
-	return `${(lastSpace > limit * .6 ? slice.slice(0, lastSpace) : slice).trimEnd()}…`;
-}
-/** Basename of a path, used as the default card title. */
-function fileBaseName(path) {
-	return path.split("/").filter(Boolean).pop() ?? path;
-}
-/**
-* 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.
-*/
-function buildFileSnapshot(input) {
-	const snapshot = { title: input.title?.trim() || fileBaseName(input.path) };
-	if (input.mimeType) snapshot.mimeType = input.mimeType;
-	if (typeof input.size === "number" && Number.isFinite(input.size)) snapshot.size = input.size;
-	if (typeof input.mtimeMs === "number" && Number.isFinite(input.mtimeMs)) snapshot.mtimeMs = input.mtimeMs;
-	const content = input.content;
-	if (typeof content !== "string" || content.length === 0) return snapshot;
-	const { frontmatter, body } = splitFrontmatter(content);
-	const frontmatterTitle = readTitleFromFrontmatter(frontmatter);
-	if (frontmatterTitle) snapshot.title = frontmatterTitle;
-	const cover = resolveCoverRef(input.path, readCoverFromFrontmatter(frontmatter));
-	if (cover?.kind === "url") snapshot.coverUrl = cover.url;
-	else if (cover?.kind === "path") snapshot.coverPath = cover.path;
-	const excerpt = buildFileExcerpt(body);
-	if (excerpt) snapshot.excerpt = excerpt;
-	return snapshot;
 }
 /** Whether a snapshot's cached facts still describe the file on disk. */
 function isFileSnapshotFresh(snapshot, file) {
@@ -226,17 +61,11 @@ function isFileSnapshotFresh(snapshot, file) {
 	if (snapshot.size !== void 0 && file.size !== void 0 && snapshot.size !== file.size) return false;
 	return true;
 }
-/** Whether a file is small enough that fetching a text preview is worthwhile. */
-function shouldFetchFileExcerpt(input) {
-	if (input.size !== void 0 && input.size > 262144) return false;
-	return true;
-}
 /**
 * 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.
+* — offline, 5xx, timeout, 401/403 — is `unavailable`.
 */
 function availabilityFromError(error) {
 	const status = typeof error === "object" && error !== null ? error.status : void 0;
@@ -248,16 +77,14 @@ function availabilityFromError(error) {
 * 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.
+* spaces are the norm ("README.md"), so every preview cache is keyed by both.
 */
 function filePreviewScope(spaceId, path) {
 	return `${spaceId}\u0000${path}`;
 }
 /**
-* 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.
+* 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.
 */
 function filePreviewMemoKey(spaceId, path, mtimeMs) {
 	return `${filePreviewScope(spaceId, path)}@${mtimeMs ?? 0}`;
@@ -265,12 +92,8 @@ function filePreviewMemoKey(spaceId, path, mtimeMs) {
 /**
 * 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".
+* `complete` decides whether the incoming facts supersede the cached ones or
+* are merged over them. A complete read's omissions are authoritative.
 */
 function mergeFileSnapshot(cached, incoming, complete) {
 	return complete ? incoming : {
@@ -279,4 +102,4 @@ function mergeFileSnapshot(cached, incoming, complete) {
 	};
 }
 //#endregion
-export { FILE_EXCERPT_MAX_BYTES, FILE_EXCERPT_MAX_CHARS, availabilityFromError, buildFileExcerpt, buildFileSnapshot, fileBaseName, filePreviewKind, filePreviewMemoKey, filePreviewScope, fileTypeLabel, formatFileSize, isFileSnapshotFresh, mergeFileSnapshot, readCoverFromFrontmatter, readTitleFromFrontmatter, resolveCoverRef, resolveSpacePath, shouldFetchFileExcerpt, splitFrontmatter };
+export { FILE_EXCERPT_MAX_BYTES, FILE_EXCERPT_MAX_CHARS, availabilityFromError, buildCodeExcerpt, buildFileExcerpt, buildFileSnapshot, fileBaseName, fileCategory, fileCategoryAccent, fileMetaLine, filePreviewKind, filePreviewMemoKey, filePreviewScope, fileStem, fileTypeLabel, formatFileSize, isFileSnapshotFresh, mergeFileSnapshot, readCoverFromFrontmatter, readFrontmatterScalars, readTitleFromFrontmatter, resolveCoverRef, resolveFileTitle, resolveSpacePath, shouldFetchFileExcerpt, splitFrontmatter };

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

@@ -0,0 +1,106 @@
+//#region src/board/core/file-snapshot.d.ts
+/**
+ * File-card snapshot derivation — pure, renderer-agnostic, dependency-free.
+ *
+ * Whoever holds the file content calls `buildFileSnapshot`; today that is the
+ * web client, for cards near its viewport. Nothing here ever writes back to the
+ * workspace file. The file on disk stays the single source of truth, and the
+ * snapshot is a cache keyed by mtime so a stale card is detectable.
+ */
+/** Hard cap on a stored excerpt. Board cards show a few lines at most. */
+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 FileCategory = "doc" | "code" | "data" | "media" | "other";
+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;
+};
+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;
+};
+/** Classify a file so excerpt, title and colour can vary without a second source of truth. */
+declare function fileCategory(path: string, mimeType?: string | null): FileCategory;
+/** Basename of a path, used as a last-resort card title. */
+declare function fileBaseName(path: string): string;
+/** Basename with a trailing extension stripped. Dotfiles keep their full name. */
+declare function fileStem(path: string): string;
+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.
+ * `http:` / `data:` / `blob:` are rejected so a board never downgrades the page
+ * or embeds opaque bytes.
+ */
+declare function resolveCoverRef(fromFilePath: string, raw: string | undefined | null): ResolvedCover;
+type SplitSource = {
+  frontmatter: string | null;
+  body: string;
+};
+/**
+ * Split leading YAML (`---`) or TOML (`+++`) frontmatter from a source.
+ *
+ * BOM and leading blank lines are ignored. The closing fence may carry trailing
+ * whitespace; YAML also accepts `...`. An unterminated block is treated as body.
+ */
+declare function splitFrontmatter(source: string): SplitSource;
+/** Read non-empty top-level scalar values from a frontmatter / YAML / TOML block. */
+declare function readFrontmatterScalars(frontmatter: string | null): Map<string, string>;
+declare function readTitleFromFrontmatter(frontmatter: string | null): string | null;
+declare function readCoverFromFrontmatter(frontmatter: string | null): string | null;
+declare function resolveFileTitle(input: {
+  path: string;
+  frontmatter: string | null;
+  body: string;
+  fallback?: string;
+}): {
+  title: string;
+  body: string;
+};
+/**
+ * Reduce markdown to a short, readable excerpt.
+ *
+ * Decoration is flattened rather than rendered: fenced code is dropped, headings
+ * and list markers go, links keep their text. Emphasis markers are only removed
+ * when they wrap a span, so a stray `*` does not punch holes in the prose.
+ */
+declare function buildFileExcerpt(source: string, limit?: number): string;
+declare function buildCodeExcerpt(source: string, limit?: number): string;
+/**
+ * Build the cached display facts for a file node.
+ *
+ * Content is optional: 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 file is small enough that fetching a text preview is worthwhile. */
+declare function shouldFetchFileExcerpt(input: {
+  mimeType?: string | null;
+  size?: number;
+}): boolean;
+//#endregion
+export { BoardFileSnapshotFacts, BuildSnapshotInput, FILE_EXCERPT_MAX_BYTES, FILE_EXCERPT_MAX_CHARS, FileCategory, ResolvedCover, buildCodeExcerpt, buildFileExcerpt, buildFileSnapshot, fileBaseName, fileCategory, fileStem, readCoverFromFrontmatter, readFrontmatterScalars, readTitleFromFrontmatter, resolveCoverRef, resolveFileTitle, resolveSpacePath, shouldFetchFileExcerpt, splitFrontmatter };