cursedbelt-core 1.0.0

package/dist/core/palette/ShortcutRegistry.d.ts

@@ -0,0 +1,33 @@
+/** A registered keyboard shortcut — its binding plus how it reads in the palette. */
+export interface ShortcutEntry {
+    /** Short name of the thing it acts on (e.g. `'Board'`). */
+    label: string;
+    /** Binding in tinykeys format (`'$mod+k'`, `'alt+b'`) — also the registry key. */
+    keys: string;
+    /** What the shortcut does, shown as the palette row's description (e.g. `'Open the board'`). */
+    action: string;
+}
+type Listener = () => void;
+/**
+ * Keyed by `keys`, so registering the same binding twice replaces it (last write wins
+ * — no duplicate rows) and a feature can re-register on every mount idempotently.
+ */
+export declare class ShortcutRegistry {
+    private entries;
+    private listeners;
+    private snapshot;
+    /** Add or replace the shortcut for `entry.keys`. */
+    register(entry: ShortcutEntry): void;
+    /** Remove the shortcut bound to `keys` (no-op if absent). */
+    unregister(keys: string): void;
+    /** Every registered shortcut, in insertion order. Stable until the next mutation. */
+    getAll(): ShortcutEntry[];
+    /** Subscribe to registry changes (returns an unsubscribe). Powers the live palette list. */
+    subscribe(listener: Listener): () => void;
+    /** Drop every shortcut (mainly for tests / teardown). */
+    clear(): void;
+    private commit;
+}
+/** The app-wide shortcut registry singleton. */
+export declare const shortcutRegistry: ShortcutRegistry;
+export {};

package/dist/core/palette/ShortcutRegistry.js

@@ -0,0 +1,52 @@
+// A tiny global registry of the app's keyboard shortcuts — the single source of truth
+// that BOTH the keybinding layer (`useHotkeys`) and the command palette read from. An
+// app registers a shortcut once; the palette can then list "Board → ⌥B" in its
+// cold-state reference without the binding and its documentation drifting apart.
+//
+// Register in a mount effect (never at module load) so the palette's list reflects the
+// shortcuts actually wired up for the current screen; the registry notifies subscribers
+// on every change so a mounted palette stays live as shortcuts come and go.
+/**
+ * Keyed by `keys`, so registering the same binding twice replaces it (last write wins
+ * — no duplicate rows) and a feature can re-register on every mount idempotently.
+ */
+export class ShortcutRegistry {
+    entries = new Map();
+    listeners = new Set();
+    // A frozen snapshot, rebuilt only on mutation, so `getAll()` is referentially stable
+    // between changes — required for `useSyncExternalStore` to not loop.
+    snapshot = [];
+    /** Add or replace the shortcut for `entry.keys`. */
+    register(entry) {
+        this.entries.set(entry.keys, entry);
+        this.commit();
+    }
+    /** Remove the shortcut bound to `keys` (no-op if absent). */
+    unregister(keys) {
+        if (this.entries.delete(keys))
+            this.commit();
+    }
+    /** Every registered shortcut, in insertion order. Stable until the next mutation. */
+    getAll() {
+        return this.snapshot;
+    }
+    /** Subscribe to registry changes (returns an unsubscribe). Powers the live palette list. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Drop every shortcut (mainly for tests / teardown). */
+    clear() {
+        if (this.entries.size === 0)
+            return;
+        this.entries.clear();
+        this.commit();
+    }
+    commit() {
+        this.snapshot = [...this.entries.values()];
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+/** The app-wide shortcut registry singleton. */
+export const shortcutRegistry = new ShortcutRegistry();

package/dist/core/palette/fuzzyRank.d.ts

@@ -0,0 +1,18 @@
+import type { NavItem } from '../navigation';
+/**
+ * The initials of a multi-word label (`'Query Builder'` → `'qb'`). Single-word labels
+ * return `''` (their prefix already matches via the label itself). Powers initialism
+ * matching ("sh" → "System Health") under the strict contiguous matcher.
+ */
+export declare function searchInitials(label: string): string;
+/**
+ * Rank `items` against `query`, best match first; non-matches dropped. Generic over the
+ * item type (so callers can pass plain {@link NavItem}s *or* richer catalogue entries
+ * that carry domain/group tags for grouping — the extra fields ride straight through).
+ * An empty/blank query returns `[]` (the palette shows its cold state instead).
+ *
+ * Returns *all* matches in rank order; callers cap the count for display (the palette
+ * shows 30). uFuzzy's contiguous scorer means "frac" ranks "Fractal" above "Format
+ * Lab", and the initials augmentation means "qb" surfaces "Query Builder".
+ */
+export declare function fuzzyRankItems<T extends NavItem>(query: string, items: T[]): T[];

package/dist/core/palette/fuzzyRank.js

@@ -0,0 +1,73 @@
+// The command-palette ranking layer — uFuzzy over the nav catalogue. This is the
+// *upgrade* HeaderSearch's `rankCatalogue` (a substring scorer) cannot match: uFuzzy
+// scores by contiguous-match proximity, so abbreviated/typeahead input ranks the
+// right page first. Pure + synchronous + React-free (uFuzzy is regex-based, no DOM),
+// so it runs in the client, a server test, or the kitchen-sink demo identically.
+//
+// Why `intraMode: 1` (SingleError, contiguous) over `0` (MultiInsert, scattered):
+// scattered mode treats every needle char as "appears somewhere later", which is far
+// too permissive for short nav labels (every query matches half the menu). Contiguous
+// mode keeps results tight — the documented tradeoff is lower typo tolerance, which is
+// the right call for a fixed, known set of navigation labels.
+//
+// The catch: contiguous mode means a bare initialism ("qb") would NOT reach "Query
+// Builder" (the chars aren't adjacent). So each haystack string is augmented with the
+// label's **initials** as an explicit token ("Query Builder" → "query builder qb") —
+// now "qb" matches that token contiguously, giving free initialism support without
+// loosening the matcher. Keywords (synonyms / old names / abbreviations) are appended
+// too, so "mandelbrot" still finds "Fractal".
+import uFuzzy from '@leeoniya/ufuzzy';
+// One singleton instance — uFuzzy compiles regexes from its options on construction,
+// so re-creating it per query would be wasteful. `intraMode: 1` = contiguous match.
+const uf = new uFuzzy({ intraMode: 1 });
+/** Split a label into words on whitespace and the separators nav labels actually use. */
+const WORD_SPLIT = /[\s/&·,_-]+/;
+/**
+ * The initials of a multi-word label (`'Query Builder'` → `'qb'`). Single-word labels
+ * return `''` (their prefix already matches via the label itself). Powers initialism
+ * matching ("sh" → "System Health") under the strict contiguous matcher.
+ */
+export function searchInitials(label) {
+    const words = label.split(WORD_SPLIT).filter(Boolean);
+    if (words.length < 2)
+        return '';
+    // Lower-cased for a predictable token; uFuzzy matches case-insensitively anyway.
+    return words.map((w) => (w[0] ?? '').toLowerCase()).join('');
+}
+/** Build the per-item haystack string: label + its initials + any keywords, space-joined. */
+function haystackFor(item) {
+    return [item.label, searchInitials(item.label), ...(item.keywords ?? [])]
+        .filter(Boolean)
+        .join(' ');
+}
+/**
+ * Rank `items` against `query`, best match first; non-matches dropped. Generic over the
+ * item type (so callers can pass plain {@link NavItem}s *or* richer catalogue entries
+ * that carry domain/group tags for grouping — the extra fields ride straight through).
+ * An empty/blank query returns `[]` (the palette shows its cold state instead).
+ *
+ * Returns *all* matches in rank order; callers cap the count for display (the palette
+ * shows 30). uFuzzy's contiguous scorer means "frac" ranks "Fractal" above "Format
+ * Lab", and the initials augmentation means "qb" surfaces "Query Builder".
+ */
+export function fuzzyRankItems(query, items) {
+    const q = query.trim();
+    if (!q || items.length === 0)
+        return [];
+    const haystack = items.map(haystackFor);
+    const [idxs, , order] = uf.search(haystack, q);
+    // `idxs` is null when nothing matched and an empty array when filtered to zero; both
+    // mean "no results". `order` (the ranked iteration order into `idxs`) is present
+    // whenever there are matches under uFuzzy's info threshold (1e3 — far above any nav
+    // set); fall back to raw `idxs` order if it's ever absent.
+    if (!idxs || idxs.length === 0)
+        return [];
+    const ranked = order ? order.map((o) => idxs[o]) : idxs;
+    const out = [];
+    for (const haystackIdx of ranked) {
+        const item = items[haystackIdx];
+        if (item)
+            out.push(item);
+    }
+    return out;
+}

package/dist/core/palette/hotkeys.d.ts

@@ -0,0 +1,28 @@
+/** The four modifier flags a binding can require. */
+interface HotkeyMods {
+    meta: boolean;
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+}
+/** A parsed binding: the required modifier set + the final (lower-cased) key. */
+export interface ParsedHotkey extends HotkeyMods {
+    key: string;
+}
+/**
+ * Is this an Apple platform (macOS / iOS)? Decides whether `$mod` means ⌘ (Meta) or
+ * Ctrl, and which glyphs the badge draws. Guarded for non-DOM (SSR / unit) hosts —
+ * returns `false` when there's no `navigator`.
+ */
+export declare function isApplePlatform(): boolean;
+/** Split a `'+'`-separated binding into its required modifiers + final key. */
+export declare function parseHotkey(binding: string, isApple?: boolean): ParsedHotkey;
+/** Does a keyboard event satisfy `binding` — exact modifier set + the key? */
+export declare function matchHotkey(e: KeyboardEvent, binding: string, isApple?: boolean): boolean;
+/**
+ * Render a binding as a human badge for the platform: macOS draws glyphs with no
+ * separator (`⌘K`, `⌥B`, `⌃⇧P`); elsewhere words joined with a thin space (`Ctrl K`,
+ * `Alt B`). The palette input badge + the per-row shortcut labels both use this.
+ */
+export declare function formatHotkey(binding: string, isApple?: boolean): string;
+export {};

package/dist/core/palette/hotkeys.js

@@ -0,0 +1,118 @@
+// Platform-portable keyboard-shortcut parsing, matching, and display formatting.
+// React-free (pure functions + DOM event/`navigator` reads, no React) so the
+// ShortcutRegistry, the `useHotkeys` hook, and the palette badge all share one
+// source of truth for "what does `$mod+k` mean and how is it drawn?".
+//
+// Binding syntax is the tinykeys format — `'+'`-separated modifiers then a key:
+//   `$mod+k`   → ⌘K on macOS, Ctrl K elsewhere   (the portable command modifier)
+//   `alt+b`    → ⌥B on macOS, Alt B elsewhere
+//   `shift+?`  → ⇧?
+// `$mod` is the whole point: one binding, correct on every platform.
+/**
+ * Is this an Apple platform (macOS / iOS)? Decides whether `$mod` means ⌘ (Meta) or
+ * Ctrl, and which glyphs the badge draws. Guarded for non-DOM (SSR / unit) hosts —
+ * returns `false` when there's no `navigator`.
+ */
+export function isApplePlatform() {
+    if (typeof navigator === 'undefined')
+        return false;
+    // `navigator.platform` is the most reliable signal but is being deprecated, so fall
+    // back to the UA string. Covers Mac, iPhone, iPad, iPod (incl. iPadOS desktop-UA).
+    const probe = `${navigator.platform ?? ''} ${navigator.userAgent ?? ''}`;
+    return /mac|iphone|ipad|ipod/i.test(probe);
+}
+/** Split a `'+'`-separated binding into its required modifiers + final key. */
+export function parseHotkey(binding, isApple = isApplePlatform()) {
+    const parts = binding
+        .toLowerCase()
+        .split('+')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    const key = parts.pop() ?? '';
+    const tokens = new Set(parts);
+    const mod = tokens.has('$mod');
+    return {
+        key,
+        meta: tokens.has('meta') || tokens.has('cmd') || tokens.has('command') || (mod && isApple),
+        ctrl: tokens.has('ctrl') || tokens.has('control') || (mod && !isApple),
+        alt: tokens.has('alt') || tokens.has('option') || tokens.has('opt'),
+        shift: tokens.has('shift'),
+    };
+}
+/** Does a keyboard event satisfy `binding` — exact modifier set + the key? */
+export function matchHotkey(e, binding, isApple = isApplePlatform()) {
+    const want = parseHotkey(binding, isApple);
+    // Exact modifier match (not "at least") so `$mod+k` never fires on ⌘⇧K.
+    if (e.metaKey !== want.meta)
+        return false;
+    if (e.ctrlKey !== want.ctrl)
+        return false;
+    if (e.altKey !== want.alt)
+        return false;
+    if (e.shiftKey !== want.shift)
+        return false;
+    return eventMatchesKey(e, want.key);
+}
+/**
+ * Match the produced `key`, falling back to the physical `code` — because on macOS a
+ * held Option mutates `event.key` (⌥B yields "∫"), so an `alt+b` binding must match on
+ * `KeyB` too. Letters + digits are covered (the practical shortcut surface).
+ */
+function eventMatchesKey(e, key) {
+    if (!key)
+        return false;
+    if (e.key.toLowerCase() === key)
+        return true;
+    if (key.length === 1 && key >= 'a' && key <= 'z' && e.code === `Key${key.toUpperCase()}`) {
+        return true;
+    }
+    if (key.length === 1 && key >= '0' && key <= '9' && e.code === `Digit${key}`)
+        return true;
+    return false;
+}
+const MAC_GLYPH = {
+    meta: '⌘',
+    ctrl: '⌃',
+    alt: '⌥',
+    shift: '⇧',
+};
+const PC_WORD = {
+    meta: 'Win',
+    ctrl: 'Ctrl',
+    alt: 'Alt',
+    shift: 'Shift',
+};
+/** Pretty-print a key token for display: a letter/digit upper-cases, named keys title-case. */
+function displayKey(key) {
+    if (key.length === 1)
+        return key.toUpperCase();
+    const named = {
+        arrowup: '↑',
+        arrowdown: '↓',
+        arrowleft: '←',
+        arrowright: '→',
+        enter: '↵',
+        escape: 'Esc',
+        backspace: '⌫',
+        delete: 'Del',
+        ' ': 'Space',
+        space: 'Space',
+    };
+    return named[key] ?? key.charAt(0).toUpperCase() + key.slice(1);
+}
+/**
+ * Render a binding as a human badge for the platform: macOS draws glyphs with no
+ * separator (`⌘K`, `⌥B`, `⌃⇧P`); elsewhere words joined with a thin space (`Ctrl K`,
+ * `Alt B`). The palette input badge + the per-row shortcut labels both use this.
+ */
+export function formatHotkey(binding, isApple = isApplePlatform()) {
+    const p = parseHotkey(binding, isApple);
+    const order = isApple
+        ? ['ctrl', 'alt', 'shift', 'meta'] // Apple convention: ⌃⌥⇧⌘ then key
+        : ['ctrl', 'meta', 'alt', 'shift'];
+    const mods = order.filter((m) => p[m]).map((m) => (isApple ? MAC_GLYPH[m] : PC_WORD[m]));
+    const key = displayKey(p.key);
+    if (isApple)
+        return [...mods, key].join('');
+    return [...mods, key].join(' ');
+}

package/dist/core/palette/index.d.ts

@@ -0,0 +1,3 @@
+export { fuzzyRankItems, searchInitials, } from './fuzzyRank';
+export { formatHotkey, isApplePlatform, matchHotkey, type ParsedHotkey, parseHotkey, } from './hotkeys';
+export { type ShortcutEntry, ShortcutRegistry, shortcutRegistry, } from './ShortcutRegistry';

package/dist/core/palette/index.js

@@ -0,0 +1,8 @@
+// `cursedbelt-core/palette` — the React-free command-palette core: the uFuzzy ranking
+// layer, the shortcut registry, and the portable hotkey utilities. No React, no
+// browser dependency beyond optional `navigator`/event reads — usable in a startup
+// module, a server test, or the React layer alike. The `CommandPalette` component +
+// its hooks live in `cursedbelt/react` and build on exactly this.
+export { fuzzyRankItems, searchInitials, } from './fuzzyRank';
+export { formatHotkey, isApplePlatform, matchHotkey, parseHotkey, } from './hotkeys';
+export { ShortcutRegistry, shortcutRegistry, } from './ShortcutRegistry';

package/dist/core/schema/projection.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Dynamic Schema Projection — the Virtual Schema Adapter (02 §7.2).
+ *
+ * User-defined structure (imported CSVs, external tables, custom columns)
+ * projects through `l_columns` typed metadata (01 §2.1). Components read a
+ * unified layout object and **no user action ever generates DDL**.
+ *
+ * That last rule is the whole design. The obvious implementation — `ALTER TABLE`
+ * per user column — makes every import a schema migration: it needs a write lock
+ * on a live DB, it cannot be rolled back cleanly mid-import, and a tenant with
+ * 300 custom columns produces a 300-column table that no index helps. Projecting
+ * instead means the physical schema is fixed (`l_values` with one typed column
+ * per storage class) and the *logical* schema is data.
+ *
+ * Typed value columns also fix a real SQLite failure: a single `value TEXT`
+ * column holding mixed storage classes sorts `10` before `9`, and a date next to
+ * a number compares by its type tag first. Landing each value in the column
+ * matching its declared type keeps `ORDER BY` single-storage-class correct.
+ */
+/** The column types `l_columns.col_type` admits (01 §2.1). */
+export declare const PROJECTED_COLUMN_TYPES: readonly ["text", "number", "bool", "date", "select", "json"];
+export type ProjectedColumnType = (typeof PROJECTED_COLUMN_TYPES)[number];
+/** One user-defined column's metadata — a row of `l_columns`. */
+export interface ProjectedColumn {
+    id: string;
+    name: string;
+    colType: ProjectedColumnType;
+    position: number;
+    /** Type-specific options — `select` choices, number precision, date format. */
+    options?: Record<string, unknown>;
+}
+/** The physical `l_values` slots. Exactly one is non-null per (row, column). */
+export interface ProjectedValueRow {
+    v_text: string | null;
+    v_num: number | null;
+    v_bool: number | null;
+    v_date: string | null;
+    v_json: string | null;
+}
+/** Which physical column a logical type lands in. */
+export declare const STORAGE_COLUMN: Readonly<Record<ProjectedColumnType, keyof ProjectedValueRow>>;
+/** What a component sees — never the physical row. */
+export interface ProjectedField {
+    columnId: string;
+    name: string;
+    type: ProjectedColumnType;
+    value: string | number | boolean | null;
+    /** Parsed `json` payload; undefined for every other type. */
+    json?: unknown;
+}
+export interface ProjectionDiagnostic {
+    code: 'projection-lossy-cast';
+    columnId: string;
+    message: string;
+}
+/**
+ * Project a stored row into the unified layout object components read.
+ *
+ * Reads only the slot the column's declared type owns. Deliberately: a row whose
+ * `v_text` still holds a value from before a column's type was changed must not
+ * resurface — the declared type is the truth, and a stale slot is stale data.
+ */
+export declare function projectColumn(column: ProjectedColumn, row: ProjectedValueRow | null): ProjectedField;
+export interface CastResult {
+    row: ProjectedValueRow;
+    diagnostics: readonly ProjectionDiagnostic[];
+}
+/**
+ * Cast an incoming value into the slot its column's type owns.
+ *
+ * A value that cannot be cast is preserved as `json` with a WARNING
+ * `projection-lossy-cast` rather than being dropped. Dropping is the behavior
+ * that loses a user's imported data silently; keeping it means the cell is
+ * visibly wrong and recoverable.
+ */
+export declare function castValue(column: ProjectedColumn, value: unknown): CastResult;
+/**
+ * Map an external field type (CSV sniff, sheet cell type, API schema) onto a
+ * projected column type. Anything unrecognized becomes `json` — the lossless
+ * default, per 02 §7.2.
+ */
+export declare function mapExternalType(externalType: string): ProjectedColumnType;
+/** Project a whole row: every declared column, in `position` order. */
+export declare function projectRow(columns: readonly ProjectedColumn[], values: ReadonlyMap<string, ProjectedValueRow>): readonly ProjectedField[];

package/dist/core/schema/projection.js

@@ -0,0 +1,184 @@
+/**
+ * Dynamic Schema Projection — the Virtual Schema Adapter (02 §7.2).
+ *
+ * User-defined structure (imported CSVs, external tables, custom columns)
+ * projects through `l_columns` typed metadata (01 §2.1). Components read a
+ * unified layout object and **no user action ever generates DDL**.
+ *
+ * That last rule is the whole design. The obvious implementation — `ALTER TABLE`
+ * per user column — makes every import a schema migration: it needs a write lock
+ * on a live DB, it cannot be rolled back cleanly mid-import, and a tenant with
+ * 300 custom columns produces a 300-column table that no index helps. Projecting
+ * instead means the physical schema is fixed (`l_values` with one typed column
+ * per storage class) and the *logical* schema is data.
+ *
+ * Typed value columns also fix a real SQLite failure: a single `value TEXT`
+ * column holding mixed storage classes sorts `10` before `9`, and a date next to
+ * a number compares by its type tag first. Landing each value in the column
+ * matching its declared type keeps `ORDER BY` single-storage-class correct.
+ */
+/** The column types `l_columns.col_type` admits (01 §2.1). */
+export const PROJECTED_COLUMN_TYPES = ['text', 'number', 'bool', 'date', 'select', 'json'];
+/** Which physical column a logical type lands in. */
+export const STORAGE_COLUMN = {
+    text: 'v_text',
+    number: 'v_num',
+    bool: 'v_bool',
+    date: 'v_date',
+    // A `select` is a constrained string, so it sorts and indexes as text.
+    select: 'v_text',
+    json: 'v_json',
+};
+/**
+ * Project a stored row into the unified layout object components read.
+ *
+ * Reads only the slot the column's declared type owns. Deliberately: a row whose
+ * `v_text` still holds a value from before a column's type was changed must not
+ * resurface — the declared type is the truth, and a stale slot is stale data.
+ */
+export function projectColumn(column, row) {
+    const base = { columnId: column.id, name: column.name, type: column.colType };
+    if (row === null)
+        return { ...base, value: null };
+    switch (column.colType) {
+        case 'number':
+            return { ...base, value: row.v_num };
+        case 'bool':
+            // SQLite has no boolean storage class; 0/1 becomes a real boolean here so
+            // components never write `=== 1`.
+            return { ...base, value: row.v_bool === null ? null : row.v_bool !== 0 };
+        case 'date':
+            return { ...base, value: row.v_date };
+        case 'json': {
+            if (row.v_json === null)
+                return { ...base, value: null };
+            try {
+                return { ...base, value: row.v_json, json: JSON.parse(row.v_json) };
+            }
+            catch {
+                // Malformed JSON surfaces as raw text rather than throwing — one bad
+                // cell must not blank an entire table render.
+                return { ...base, value: row.v_json };
+            }
+        }
+        default:
+            return { ...base, value: row.v_text };
+    }
+}
+const EMPTY_ROW = { v_text: null, v_num: null, v_bool: null, v_date: null, v_json: null };
+/**
+ * Cast an incoming value into the slot its column's type owns.
+ *
+ * A value that cannot be cast is preserved as `json` with a WARNING
+ * `projection-lossy-cast` rather than being dropped. Dropping is the behavior
+ * that loses a user's imported data silently; keeping it means the cell is
+ * visibly wrong and recoverable.
+ */
+export function castValue(column, value) {
+    const row = { ...EMPTY_ROW };
+    const diagnostics = [];
+    if (value === null || value === undefined || value === '')
+        return { row, diagnostics };
+    const lossy = (message) => {
+        diagnostics.push({ code: 'projection-lossy-cast', columnId: column.id, message });
+        row.v_json = JSON.stringify(value);
+    };
+    switch (column.colType) {
+        case 'number': {
+            const numeric = typeof value === 'number' ? value : Number(String(value).replace(/[,\s]/g, ''));
+            if (Number.isFinite(numeric))
+                row.v_num = numeric;
+            else
+                lossy(`'${String(value)}' is not a number; stored as json.`);
+            break;
+        }
+        case 'bool': {
+            const text = String(value).trim().toLowerCase();
+            if (typeof value === 'boolean')
+                row.v_bool = value ? 1 : 0;
+            else if (['true', 'yes', 'y', '1'].includes(text))
+                row.v_bool = 1;
+            else if (['false', 'no', 'n', '0'].includes(text))
+                row.v_bool = 0;
+            else
+                lossy(`'${String(value)}' is not a boolean; stored as json.`);
+            break;
+        }
+        case 'date': {
+            const iso = toIsoDate(value);
+            if (iso !== null)
+                row.v_date = iso;
+            else
+                lossy(`'${String(value)}' is not a recognizable date; stored as json.`);
+            break;
+        }
+        case 'select': {
+            const choices = Array.isArray(column.options?.choices) ? column.options.choices : null;
+            const text = String(value);
+            if (choices === null || choices.map(String).includes(text))
+                row.v_text = text;
+            else
+                lossy(`'${text}' is not one of the declared choices; stored as json.`);
+            break;
+        }
+        case 'json':
+            row.v_json = typeof value === 'string' ? value : JSON.stringify(value);
+            break;
+        default:
+            row.v_text = typeof value === 'string' ? value : String(value);
+    }
+    return { row, diagnostics };
+}
+/**
+ * ISO-8601 date, or null. Anchored to UTC so the same CSV imported in two
+ * timezones produces the same stored day — the off-by-one-day class of import
+ * bug.
+ */
+function toIsoDate(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value.toISOString();
+    const text = String(value).trim();
+    if (/^\d{4}-\d{2}-\d{2}$/.test(text))
+        return `${text}T00:00:00.000Z`;
+    const parsed = Date.parse(text);
+    return Number.isNaN(parsed) ? null : new Date(parsed).toISOString();
+}
+/**
+ * Map an external field type (CSV sniff, sheet cell type, API schema) onto a
+ * projected column type. Anything unrecognized becomes `json` — the lossless
+ * default, per 02 §7.2.
+ */
+export function mapExternalType(externalType) {
+    switch (externalType.toLowerCase()) {
+        case 'string':
+        case 'text':
+        case 'varchar':
+            return 'text';
+        case 'number':
+        case 'numeric':
+        case 'int':
+        case 'integer':
+        case 'float':
+        case 'double':
+        case 'decimal':
+            return 'number';
+        case 'bool':
+        case 'boolean':
+            return 'bool';
+        case 'date':
+        case 'datetime':
+        case 'timestamp':
+            return 'date';
+        case 'enum':
+        case 'select':
+            return 'select';
+        default:
+            return 'json';
+    }
+}
+/** Project a whole row: every declared column, in `position` order. */
+export function projectRow(columns, values) {
+    return [...columns]
+        .sort((a, b) => a.position - b.position)
+        .map((column) => projectColumn(column, values.get(column.id) ?? null));
+}