cursedbelt-core 1.0.0

package/dist/core/download.js

@@ -0,0 +1,37 @@
+/**
+ * Trigger a browser file download from in-memory data — the canonical client-side
+ * "save this blob" primitive (there was no shared one; call sites hand-rolled
+ * `createObjectURL` + `<a download>` + revoke). DOM-only: it no-ops off the browser
+ * so importing modules stay server-safe.
+ *
+ * ```ts
+ * downloadBlob(csvText, 'notes.csv', 'text/csv');
+ * downloadBlob(sqliteBytes, 'snapshot.sqlite', 'application/x-sqlite3');
+ * ```
+ */
+export function downloadBlob(data, filename, mime) {
+    if (typeof document === 'undefined' || typeof URL.createObjectURL !== 'function')
+        return;
+    const url = URL.createObjectURL(new Blob([data], { type: mime }));
+    try {
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = filename;
+        a.rel = 'noopener';
+        document.body.appendChild(a);
+        a.click();
+        a.remove();
+    }
+    finally {
+        // Revoke on the next tick so the click's navigation has grabbed the URL first.
+        setTimeout(() => URL.revokeObjectURL(url), 0);
+    }
+}
+/** Decode a base64 payload (e.g. an exported `.sqlite` snapshot) to bytes for {@link downloadBlob}. */
+export function base64ToBytes(base64) {
+    const bin = atob(base64);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        bytes[i] = bin.charCodeAt(i);
+    return bytes;
+}

package/dist/core/events/ccEventBus.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The global event bus (03 §6.4) — lifecycle notifications only, never data
+ * payloads (those ride the port hub).
+ *
+ * The depth guard is the reason this is a primitive rather than an EventEmitter:
+ * handlers emit, and a handler chain that loops — `NOTE_SAVED` → indexer →
+ * dashboard → audit interceptor → `NOTE_SAVED` — freezes the main thread with no
+ * error and no stack that names the cycle. Each emission inherits
+ * `depth = parent.depth + 1` via `causationId`; past `MAX_EVENT_DEPTH` the bus
+ * terminates the chain and raises an `EventLoopDiagnostic` that names the whole
+ * chain, so the loop is a report instead of a hang.
+ *
+ * Handlers are async-scheduled, never re-entrant: emitting from inside a handler
+ * queues, so a synchronous handler cannot re-enter the dispatcher mid-iteration.
+ */
+export interface CCEvent {
+    type: string;
+    tenantId: string;
+    causationId: string;
+    depth: number;
+    payload: Record<string, unknown>;
+}
+export interface EventLoopDiagnostic {
+    chain: string[];
+    terminatedAt: string;
+    causationId: string;
+}
+export type Unsubscribe = () => void;
+/** Past this depth a chain is a loop, not a workflow (03 §6.4). */
+export declare const MAX_EVENT_DEPTH = 5;
+export interface CCEventBusOptions {
+    onLoopDiagnostic?: (diagnostic: EventLoopDiagnostic) => void;
+    maxDepth?: number;
+}
+export interface CCEventBus {
+    emit(event: Partial<CCEvent> & {
+        type: string;
+    }): void;
+    on(type: string, handler: (event: CCEvent) => void): Unsubscribe;
+    /** Resolves once the queue drains — the probe's "is the main thread still responsive?" hook. */
+    settled(): Promise<void>;
+    diagnostics(): readonly EventLoopDiagnostic[];
+}
+export declare function createCcEventBus(options?: CCEventBusOptions): CCEventBus;

package/dist/core/events/ccEventBus.js

@@ -0,0 +1,70 @@
+/** Past this depth a chain is a loop, not a workflow (03 §6.4). */
+export const MAX_EVENT_DEPTH = 5;
+export function createCcEventBus(options = {}) {
+    const maxDepth = options.maxDepth ?? MAX_EVENT_DEPTH;
+    const handlers = new Map();
+    const diagnostics = [];
+    const chains = new Map();
+    const queue = [];
+    let draining = false;
+    let drained = Promise.resolve();
+    let resolveDrained = null;
+    const drain = async () => {
+        draining = true;
+        while (queue.length > 0) {
+            const event = queue.shift();
+            for (const handler of handlers.get(event.type) ?? []) {
+                try {
+                    handler(event);
+                }
+                catch {
+                    // A throwing subscriber must not stop the rest of the chain.
+                }
+            }
+            await Promise.resolve(); // yield: handlers are scheduled, never re-entrant
+        }
+        draining = false;
+        resolveDrained?.();
+        resolveDrained = null;
+    };
+    return {
+        emit(partial) {
+            const causationId = partial.causationId ?? `cause_${chains.size + 1}_${partial.type}`;
+            const depth = partial.depth ?? 0;
+            const chain = [...(chains.get(causationId) ?? []), partial.type];
+            chains.set(causationId, chain);
+            if (depth > maxDepth) {
+                const diagnostic = { chain, terminatedAt: partial.type, causationId };
+                diagnostics.push(diagnostic);
+                options.onLoopDiagnostic?.(diagnostic);
+                return; // chain terminated — the guard, not a crash
+            }
+            queue.push({
+                type: partial.type,
+                tenantId: partial.tenantId ?? 'tenant-a',
+                causationId,
+                depth,
+                payload: partial.payload ?? {},
+            });
+            if (!draining) {
+                drained = new Promise((resolve) => {
+                    resolveDrained = resolve;
+                });
+                void drain();
+            }
+        },
+        on(type, handler) {
+            const list = handlers.get(type) ?? [];
+            list.push(handler);
+            handlers.set(type, list);
+            return () => {
+                const current = handlers.get(type) ?? [];
+                const index = current.indexOf(handler);
+                if (index >= 0)
+                    current.splice(index, 1);
+            };
+        },
+        settled: () => (draining ? drained : Promise.resolve()),
+        diagnostics: () => diagnostics,
+    };
+}

package/dist/core/file-tree/fileTreeModel.d.ts

@@ -0,0 +1,276 @@
+/**
+ * The arithmetic behind `react/file-tree` — what is in the tree, what is on screen, and
+ * which drops are legal. No DOM, so all of it is unit-tested; the pointer handling, the
+ * markers and the keyboard live in the component and are not.
+ *
+ * ── Where this came from, and why it is here rather than in an app ──────────────────────
+ * Owner, 2026-09-08: *"the spreadsheet app has a much better file tree sidebar than
+ * collections has. Add the file tree viewer from it into cb so apps like collections can
+ * use it."* `cursed-embeddable-spreadsheet`'s `FileTree` is the tree he means — it has been
+ * carrying that app's whole navigation for weeks. What made it good is mostly in this file:
+ * a drop that cannot happen is never OFFERED, so there is no marker, no highlight and no
+ * error toast after the fact — the cursor simply says no while the row is still in the air.
+ *
+ * ── 🔴 Why this is not `core/folder-tree` ──────────────────────────────────────────────
+ * `folder-tree` derives a hierarchy from delimited PATH STRINGS that items carry, and its
+ * nodes are the result of that derivation. This models a tree that already exists, whatever
+ * produced it: a node has an id, a kind and children, and an app may hand over folders
+ * derived from paths (collections), rows from a table, or a mix of both under one root. The
+ * two are complementary — collections feeds `buildFolderTree`'s output straight into this —
+ * and collapsing them would force every consumer of one to adopt the other's storage shape.
+ */
+/** What a row IS. `folder` may hold children and accept drops; `file` is a leaf. */
+export type FileTreeNodeKind = 'folder' | 'file';
+/**
+ * How visible a node is, generalised from collections' private/locked folders.
+ *
+ * 🔴 It is a LABEL, never an enforcement. The server decides what a session may see, and a
+ * tree that hides a row the server sent (or shows one it did not) is a second, weaker
+ * opinion about access that will disagree with the first. collections' server already omits
+ * what a locked session may not see — see `albums.ts:folderTree` — so a `private` row here
+ * means "you are unlocked and this is one of the protected ones", which is a thing to MARK.
+ */
+export type FileTreeAccess = 'normal' | 'private' | 'locked';
+export interface FileTreeNode {
+    /** Stable across re-derivation — it is the React key, the selection value and the drag id. */
+    id: string;
+    name: string;
+    kind: FileTreeNodeKind;
+    /** Folders only. A folder with `[]` is empty; a file's is ignored. */
+    children?: readonly FileTreeNode[];
+    /**
+     * Whether this folder draws a twisty. **Default `true` for every folder**, empty ones
+     * included — pass `false` only for a row that is a folder in name and can never hold
+     * anything.
+     *
+     * 🔴 2026-09-11, the owner: *"Make them use an arrow icon next to a dir even when the dir
+     * is empty."* It used to default to `children.length > 0`, and that was wrong twice over.
+     * For a LAZY tree it is a trap door — a consumer that fetches a row's contents only while
+     * it is open produces a collapsed row with no children, which loses its caret and can
+     * never be reopened (`apps/collections` hit exactly that, and had to pass this flag to get
+     * out of it). And for an EAGER tree it makes an empty folder look like a file: the arrow
+     * is the only thing on the row that says "this is a place", so a folder you have not put
+     * anything in yet is drawn as a leaf until the moment it stops being empty.
+     *
+     * VS Code draws the chevron on every folder and opens an empty one onto nothing, which is
+     * what this now matches.
+     */
+    expandable?: boolean;
+    /**
+     * A picture of THIS row's contents, drawn in the glyph box in place of its type icon.
+     *
+     * 🔴 2026-09-11, the owner: *"For media files show a thumbnail instead of the file type
+     * icon to the left of the name."* A folder of photographs is a list of rows whose type
+     * icons are all identical, so the glyph column says nothing at all — the thumbnail is the
+     * only thing in the row that distinguishes one picture from the next before you open it.
+     *
+     * It takes the SAME 16px box the type icon uses rather than growing the row: the row's
+     * height is pinned to the glyph by `fleet/standards/file-tree-geometry.json`, and a tree
+     * whose rows change height per file is one you cannot scan. A thumbnail that 404s falls
+     * back to the type icon exactly once — see `FileTree`'s `RowGlyph`. Omit it for anything
+     * that has no picture, and never point it at the full-size object: this is a 16px box, and
+     * a tree of 200 rows pointed at originals is 200 full downloads.
+     */
+    thumbnailUrl?: string;
+    /** Badge on the row — usually "everything at or under here". Omit for none. */
+    count?: number;
+    access?: FileTreeAccess;
+    /**
+     * Refuse drops INTO this node even though it is a folder.
+     *
+     * The consumer's veto, for a rule the tree cannot know: collections uses it so a folder
+     * cannot be dragged across album boundaries, which the server has no route for. Defaults
+     * to true for folders and is meaningless for files.
+     */
+    acceptsDrop?: boolean;
+    /**
+     * Whether this row can be picked up. Default true once `onMove` is wired.
+     *
+     * Not every row in a tree is a thing you can move: collections puts its ALBUMS at the top
+     * level, and albums have no order and no parent to be moved into. A row that cannot go
+     * anywhere must not start a drag — otherwise the gesture begins, follows the cursor, and
+     * refuses everywhere, which reads as a broken tree rather than a fixed one.
+     */
+    draggable?: boolean;
+    /** Whatever the consumer needs back in a callback. Never read here. */
+    meta?: unknown;
+}
+/** Where a drag would put the thing it is carrying. */
+export type FileTreeDrop = {
+    kind: 'into';
+    parentId: string;
+}
+/**
+ * Out of every folder, at the top of the tree.
+ *
+ * The blank space under the last row is what expresses "get this out of here" — the
+ * gesture every file explorer has and the only one that does not need a target row.
+ */
+ | {
+    kind: 'root';
+}
+/** Between two rows, when the consumer stores an order. See {@link ResolveDropOptions}. */
+ | {
+    kind: 'before';
+    siblingId: string;
+    parentId: string | null;
+} | {
+    kind: 'after';
+    siblingId: string;
+    parentId: string | null;
+};
+/** A pointer position resolved against the tree: a target, or a refusal with words. */
+export interface DropOffer {
+    target: FileTreeDrop | null;
+    refused: boolean;
+    /**
+     * Why, in words, when it is refused.
+     *
+     * `DESIGN.md`'s law: a control that cannot do a thing says so. A drop that is silently
+     * ignored reads as a broken app rather than a refused one.
+     */
+    reason: string | null;
+}
+/** One row as drawn, top to bottom. */
+export interface FileTreeRow {
+    node: FileTreeNode;
+    /** How far in it is drawn — 0 at the top level. */
+    depth: number;
+    parentId: string | null;
+    /** Its position among its own siblings, which is what a keyboard move needs. */
+    index: number;
+    /** True when it is a folder with children (so it gets a twisty). */
+    expandable: boolean;
+    expanded: boolean;
+}
+/** Every node in the tree, depth-first — the order the rows would be in fully expanded. */
+export declare function walkFileTree(nodes: readonly FileTreeNode[]): FileTreeNode[];
+export declare function findFileTreeNode(nodes: readonly FileTreeNode[], id: string): FileTreeNode | null;
+/**
+ * The rows actually on screen, given which folders are shut.
+ *
+ * 🔴 `collapsed` is the exception list, not `expanded`. A tree derived fresh from the server
+ * on every refresh gets new nodes constantly, and an expanded-set model shows each of them
+ * shut — so a newly created folder would appear closed and empty at the moment its contents
+ * are the thing you are looking for. The exception list defaults everything open, which is
+ * also what reads best for the small trees these sidebars hold.
+ */
+export declare function flattenFileTree(nodes: readonly FileTreeNode[], collapsed: Iterable<string>): FileTreeRow[];
+/** `id` and everything under it — the set a drag may not land inside. */
+export declare function descendantIdsOf(nodes: readonly FileTreeNode[], id: string): Set<string>;
+/**
+ * The id of the folder a node sits in — `null` at the top level, and `null` for a node this
+ * tree does not contain.
+ *
+ * 🔴 The two nulls are deliberately one answer. Every caller is asking "where would a move
+ * put this", and for a row the tree no longer holds the honest answer is the top level
+ * rather than a throw: a tree re-derived from the server between the press and the release
+ * can genuinely lose the row under the pointer.
+ */
+export declare function parentIdOf(nodes: readonly FileTreeNode[], id: string): string | null;
+/** The share of a folder row's height that means "into" rather than "between". */
+export declare const INTO_ZONE = 0.5;
+export interface ResolveDropOptions {
+    nodes: readonly FileTreeNode[];
+    /** The row under the pointer, or null over blank space below the tree. */
+    row: FileTreeRow | null;
+    /** How far down that row the pointer is, 0 at its top edge and 1 at its bottom. */
+    offsetRatio: number;
+    /** What is being dragged — a node id from this tree, or null for an external payload. */
+    dragId: string | null;
+    /**
+     * Whether the consumer stores a sibling ORDER.
+     *
+     * 🔴 Off by default, and collections is why. Its folders are DERIVED from the paths its
+     * files carry and are always sorted by name, so there is no order to change — offering a
+     * between-rows marker would draw a promise the app cannot keep. Off, a row is only ever
+     * dropped INTO something, which is the whole of what that app can do.
+     */
+    allowReorder?: boolean;
+    /** Words for refusing a drop into a folder whose `acceptsDrop` is false. */
+    lockedReason?: string;
+    /**
+     * The consumer's veto, for a refusal that depends on WHAT is being dragged.
+     *
+     * `acceptsDrop` is a property of the target alone and cannot express "this folder takes
+     * files but not folders from another album" — which is collections' actual rule, because
+     * its server has a route for re-pathing a folder inside one album and none for moving one
+     * across albums. Return the words; return null to allow.
+     *
+     * 🔴 Consulted BEFORE the target is offered, never after the drop. The whole design of
+     * this tree is that an impossible drop is never drawn as possible.
+     */
+    canDrop?: (dragId: string | null, target: FileTreeDrop) => string | null;
+}
+/**
+ * Where the pointer currently is, as a decision.
+ *
+ * The rule the whole gesture is built around: **a drop that cannot happen is never
+ * offered.** Every refusal below returns a reason rather than a null target, so the cursor
+ * and the chip can say no while the row is still in the air.
+ */
+export declare function resolveDrop({ nodes, row, offsetRatio, dragId, allowReorder, lockedReason, canDrop, }: ResolveDropOptions): DropOffer;
+export interface KeyboardMoveOptions {
+    nodes: readonly FileTreeNode[];
+    /** The rows on screen — siblings are read off these, which is every sibling by construction. */
+    rows: readonly FileTreeRow[];
+    /** The row the keyboard is on. */
+    row: FileTreeRow;
+    /** `in` demotes into the nearest folder above it; `out` promotes to its grandparent. */
+    direction: 'in' | 'out';
+    lockedReason?: string;
+    canDrop?: (dragId: string | null, target: FileTreeDrop) => string | null;
+}
+/**
+ * Where ⌥→ / ⌥← would put the focused row — the keyboard's half of the drag.
+ *
+ * 🔴 It exists because a gesture with no keyboard route is a gesture half the people using
+ * it cannot perform, and because TOUCH has no drag here at all: a sidebar row is a small
+ * target on a surface whose one constant gesture is the flick, so the pointer drag gives
+ * that up and this is what is left. `cursedesk`'s tree has carried it since it was written;
+ * this one shipped with the drag alone.
+ *
+ * The two directions are the only two a keyboard can mean unambiguously. **→ demotes into
+ * the nearest folder ABOVE it among its own siblings** — the one place a demotion can go
+ * without asking which of several folders was meant — and **← promotes out to the folder its
+ * own folder is in**, which is `root` at depth 1.
+ *
+ * 🔴 Every refusal the DRAG honours is honoured here, from the same fields: `acceptsDrop`,
+ * the consumer's `canDrop`, and the descendant rule. A keyboard route that can reach a
+ * destination the pointer refuses is a second, weaker opinion about what is legal — and it
+ * is the one nobody looks at, because the pointer is what gets tested by hand.
+ *
+ * There is deliberately no ⌥↑/⌥↓ here. Those would move a row among its siblings, which is
+ * only meaningful when the consumer stores an order — and when it does, the sibling before
+ * and after are already reachable as `before`/`after` drops. Offering them unconditionally
+ * would write a position nothing reads and then draw the row back where it started.
+ */
+export declare function resolveKeyboardMove({ nodes, rows, row, direction, lockedReason, canDrop, }: KeyboardMoveOptions): DropOffer;
+/**
+ * Where a drop would put the thing being carried, in words — for the chip under the cursor
+ * and for the screen reader that cannot see it.
+ *
+ * 🔴 A drag that says only WHAT is held answers half the question. Owner, of the tree this
+ * one was ported from: *"dragging an item from one place to another does not have any
+ * indication that it is working until you drop it somewhere new and see it move."* The chip
+ * following the cursor answers "it is working"; this answers "and it is going there", which
+ * is what stops a wrong drop before the pointer is lifted rather than after.
+ *
+ * Empty for no target — a refusal has its own words and this must never carry a second "no".
+ */
+export declare function describeDrop(nodes: readonly FileTreeNode[], drop: FileTreeDrop | null): string;
+/**
+ * The next row whose name starts with `query`, searching from `fromIndex` and wrapping.
+ *
+ * Typeahead is what makes a long tree usable without a search box — `bud` jumps to
+ * `budget-2026` — and wrapping is what stops it dying at the bottom of the list.
+ */
+export declare function matchTypeahead(rows: readonly FileTreeRow[], query: string, fromIndex: number): number;
+/**
+ * The tree narrowed to what matches, with the folders on the way to a match kept.
+ *
+ * A folder that matches keeps ALL of its contents — searching for a folder means you want
+ * to see what is in it, not a folder that looks empty because its children spell something
+ * else.
+ */
+export declare function filterFileTree(nodes: readonly FileTreeNode[], query: string): readonly FileTreeNode[];