cursedbelt-core 1.0.0

package/dist/core/file-tree/fileTreeModel.js

@@ -0,0 +1,312 @@
+/**
+ * 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.
+ */
+const childrenOf = (node) => node.kind === 'folder' ? (node.children ?? []) : [];
+/** Every node in the tree, depth-first — the order the rows would be in fully expanded. */
+export function walkFileTree(nodes) {
+    const out = [];
+    const visit = (list) => {
+        for (const node of list) {
+            out.push(node);
+            visit(childrenOf(node));
+        }
+    };
+    visit(nodes);
+    return out;
+}
+export function findFileTreeNode(nodes, id) {
+    for (const node of walkFileTree(nodes))
+        if (node.id === id)
+            return node;
+    return 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 function flattenFileTree(nodes, collapsed) {
+    const shut = new Set(collapsed);
+    const out = [];
+    const visit = (list, depth, parentId) => {
+        list.forEach((node, index) => {
+            const kids = childrenOf(node);
+            /*
+             * 🔴 EVERY folder is expandable unless it says otherwise (2026-09-11).
+             *
+             * Owner: *"Make them use an arrow icon next to a dir even when the dir is empty."*
+             * This was `kids.length > 0` and it was wrong in both directions. For a LAZY tree it
+             * is a trap door — a consumer that loads a row's contents only while it is open gives
+             * a collapsed row no children, the row loses its twisty, and it can never be opened
+             * again (measured in `apps/collections`, whose sidebar fetches one folder's files at a
+             * time). For an EAGER tree it draws an empty folder as a leaf, so the one mark that
+             * distinguishes a place from a file disappears exactly while the folder is new and
+             * being filled.
+             *
+             * "A row that claims to open onto nothing is its own small lie" was the old reasoning
+             * and it is answered by what VS Code does: the chevron says *folder*, not *occupied*,
+             * and opening an empty one onto nothing is the honest answer, not a broken promise.
+             * `node.expandable === false` is still honoured for a row that can never hold anything.
+             */
+            const expandable = node.kind === 'folder' && (node.expandable ?? true);
+            const expanded = expandable && !shut.has(node.id);
+            out.push({ node, depth, parentId, index, expandable, expanded });
+            if (expanded)
+                visit(kids, depth + 1, node.id);
+        });
+    };
+    visit(nodes, 0, null);
+    return out;
+}
+/** `id` and everything under it — the set a drag may not land inside. */
+export function descendantIdsOf(nodes, id) {
+    const node = findFileTreeNode(nodes, id);
+    const out = new Set();
+    if (!node)
+        return out;
+    const visit = (n) => {
+        out.add(n.id);
+        for (const child of childrenOf(n))
+            visit(child);
+    };
+    visit(node);
+    return out;
+}
+/**
+ * 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 function parentIdOf(nodes, id) {
+    const visit = (list, parent) => {
+        for (const node of list) {
+            if (node.id === id)
+                return { at: parent };
+            const found = visit(childrenOf(node), node.id);
+            if (found)
+                return found;
+        }
+        return null;
+    };
+    return visit(nodes, null)?.at ?? null;
+}
+/** The share of a folder row's height that means "into" rather than "between". */
+export const INTO_ZONE = 0.5;
+/**
+ * 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 function resolveDrop({ nodes, row, offsetRatio, dragId, allowReorder = false, lockedReason = 'That folder is locked', canDrop, }) {
+    // Blank space under the last row: out of every folder. The one gesture that needs no
+    // target, and the only way to say "top level" when the top level has no row of its own.
+    if (!row)
+        return canDrop?.(dragId, { kind: 'root' })
+            ? { target: null, refused: true, reason: canDrop(dragId, { kind: 'root' }) }
+            : { target: { kind: 'root' }, refused: false, reason: null };
+    const forbidden = dragId ? descendantIdsOf(nodes, dragId) : new Set();
+    const target = row.node;
+    /** The consumer's last word on an otherwise-legal target. */
+    const vetted = (offer) => {
+        if (!offer.target || !canDrop)
+            return offer;
+        const reason = canDrop(dragId, offer.target);
+        return reason ? { target: null, refused: true, reason } : offer;
+    };
+    const intoFolder = () => {
+        if (target.kind !== 'folder')
+            return { target: null, refused: false, reason: null };
+        if (forbidden.has(target.id))
+            return {
+                target: null,
+                refused: true,
+                reason: target.id === dragId
+                    ? 'A folder cannot go inside itself'
+                    : 'A folder cannot go inside one of its own folders',
+            };
+        if (target.acceptsDrop === false)
+            return { target: null, refused: true, reason: lockedReason };
+        return vetted({ target: { kind: 'into', parentId: target.id }, refused: false, reason: null });
+    };
+    // A FILE row means "the folder that row is in" — what every file explorer does, and what
+    // keeps a long list of files from being a wall of rows nothing can be dropped on.
+    if (target.kind === 'file' && !allowReorder) {
+        if (row.parentId === null)
+            return vetted({ target: { kind: 'root' }, refused: false, reason: null });
+        const parent = findFileTreeNode(nodes, row.parentId);
+        if (parent && parent.acceptsDrop === false)
+            return { target: null, refused: true, reason: lockedReason };
+        if (parent && forbidden.has(parent.id))
+            return { target: null, refused: true, reason: 'A folder cannot go inside itself' };
+        return vetted({ target: { kind: 'into', parentId: row.parentId }, refused: false, reason: null });
+    }
+    if (!allowReorder)
+        return intoFolder();
+    // With an order to change, the middle half of a folder row is "into" and the edges are
+    // "between". A file row is all edges — there is no inside of a file.
+    const edge = target.kind === 'folder' ? (1 - INTO_ZONE) / 2 : 0.5;
+    if (target.kind === 'folder' && offsetRatio > edge && offsetRatio < 1 - edge)
+        return intoFolder();
+    const side = offsetRatio < 0.5 ? 'before' : 'after';
+    if (forbidden.has(target.id))
+        return { target: null, refused: true, reason: 'A folder cannot go inside itself' };
+    return vetted({
+        target: { kind: side, siblingId: target.id, parentId: row.parentId },
+        refused: false,
+        reason: 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 function resolveKeyboardMove({ nodes, rows, row, direction, lockedReason = 'That folder is locked', canDrop, }) {
+    const vetted = (target) => {
+        const reason = canDrop?.(row.node.id, target);
+        return reason
+            ? { target: null, refused: true, reason }
+            : { target, refused: false, reason: null };
+    };
+    if (direction === 'out') {
+        if (row.parentId === null)
+            return { target: null, refused: true, reason: 'It is already at the top level' };
+        const grandparentId = parentIdOf(nodes, row.parentId);
+        if (grandparentId === null)
+            return vetted({ kind: 'root' });
+        const grandparent = findFileTreeNode(nodes, grandparentId);
+        if (grandparent?.acceptsDrop === false)
+            return { target: null, refused: true, reason: lockedReason };
+        return vetted({ kind: 'into', parentId: grandparentId });
+    }
+    // A row's siblings are all on screen whenever the row itself is — a shut folder hides its
+    // CHILDREN, never its peers — so the visible rows are the whole level.
+    const level = rows.filter((entry) => entry.parentId === row.parentId);
+    const above = level
+        .filter((entry) => entry.index < row.index && entry.node.kind === 'folder')
+        .at(-1);
+    if (!above)
+        return { target: null, refused: true, reason: 'There is no folder above it to move into' };
+    if (above.node.acceptsDrop === false)
+        return { target: null, refused: true, reason: lockedReason };
+    // Belt and braces: a folder cannot go inside itself, and `above` is a sibling rather than
+    // a descendant — but the rule is the tree's, not this function's, and stating it once here
+    // is cheaper than discovering the day someone changes what `above` means.
+    if (descendantIdsOf(nodes, row.node.id).has(above.node.id))
+        return { target: null, refused: true, reason: 'A folder cannot go inside itself' };
+    return vetted({ kind: 'into', parentId: above.node.id });
+}
+/**
+ * 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 function describeDrop(nodes, drop) {
+    if (!drop)
+        return '';
+    if (drop.kind === 'root')
+        return 'To the top level';
+    if (drop.kind === 'into') {
+        const folder = findFileTreeNode(nodes, drop.parentId);
+        return folder ? `Into ${folder.name}` : 'Into this folder';
+    }
+    const sibling = findFileTreeNode(nodes, drop.siblingId);
+    const where = drop.kind === 'before' ? 'Above' : 'Below';
+    return sibling ? `${where} ${sibling.name}` : `${where} this row`;
+}
+/**
+ * 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 function matchTypeahead(rows, query, fromIndex) {
+    if (!query)
+        return -1;
+    const needle = query.toLowerCase();
+    for (let step = 1; step <= rows.length; step += 1) {
+        const index = (fromIndex + step + rows.length) % rows.length;
+        const row = rows[index];
+        if (row?.node.name.toLowerCase().startsWith(needle))
+            return index;
+    }
+    return -1;
+}
+/**
+ * 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 function filterFileTree(nodes, query) {
+    const needle = query.trim().toLowerCase();
+    if (!needle)
+        return nodes;
+    const keep = (node) => {
+        const hit = node.name.toLowerCase().includes(needle);
+        if (hit)
+            return node;
+        const kids = childrenOf(node)
+            .map(keep)
+            .filter((n) => n !== null);
+        if (kids.length === 0)
+            return null;
+        return { ...node, children: kids };
+    };
+    return nodes.map(keep).filter((n) => n !== null);
+}

package/dist/core/folder-tree/actions.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The FOLDER OPERATIONS every app with folders offers — one model, so "move it into
+ * that one" means the same thing in music as it does in collections.
+ *
+ * ── The owner's ask, verbatim (draft, 2026-08-25) ───────────────────────────────────────
+ * *"in cb make or ensure we have a standardized folder list view. I want it applied to
+ * music app and collections app and other apps with folders like that which should get the
+ * same features if any. The features should include a 3 dot menu for choosing to move all
+ * contents to a different folder or move a folder into another folder. For instance I could
+ * move rock songs from a folder 'extra-rock-songs' to a 'rock' folder with it. Also allow
+ * deleting a folder which deletes all the folder contents or allows deleting the folder and
+ * having the contents not grouped in a folder anymore. Allow renaming folders."*
+ *
+ * ── 🔴 Four verbs, and three of them already existed ────────────────────────────────────
+ * `planFolderRename`, `planFolderMove` and `planFolderDelete` in `tree.ts` are exactly
+ * rename, "move a folder into another folder", and "delete the folder and leave the
+ * contents ungrouped" — built for the vault and notes, and reachable from no menu anywhere.
+ * The gap the owner is describing is not model, it is SURFACE: every app grew its own
+ * subset of folder tools, so the operations that were never wired are the ones nobody has.
+ * This module adds the ONE missing verb and the shared descriptions; the menu that renders
+ * them is `react/folder-tree/FolderActionsMenu`.
+ *
+ * ── 🔴 Why "delete the contents too" is not a plan ──────────────────────────────────────
+ * The other three verbs are pure path rewrites — a {@link FolderRemap} list the consumer
+ * applies, with nothing destroyed. Deleting the CONTENTS destroys items, and this module
+ * has never seen an item; it only ever sees the paths they carry. So `purge` is a mode the
+ * menu offers and the CONSUMER implements against its own store, which is also the only
+ * place that can count what is about to be lost or refuse the operation. Modelling it here
+ * would mean inventing an item, and an item this model cannot see is one it cannot protect.
+ */
+import type { FolderNode, FolderRemap } from "./tree";
+/**
+ * Move everything at or under `source` INTO `destination`, and stop `source` existing.
+ *
+ * The owner's own example: *"I could move rock songs from a folder 'extra-rock-songs' to a
+ * 'rock' folder with it."* Items directly in `extra-rock-songs` land directly in `rock`;
+ * `extra-rock-songs/live` becomes `rock/live`.
+ *
+ * 🔴 This is NOT `planFolderMove`, and the difference is the whole reason it exists.
+ * `planFolderMove(source, newParent)` makes `source` a CHILD — `rock/extra-rock-songs` —
+ * which keeps the folder the owner is trying to get rid of. Both are real operations a
+ * person wants ("put this inside that" vs "empty this into that"), they read almost
+ * identically in a menu, and getting them confused is silent: the files are all present and
+ * the folder you meant to dissolve is still there one level down.
+ *
+ * @param destination an empty array means the ROOT — "take these out of any folder".
+ */
+export declare function planFolderMergeInto(serializedPaths: Iterable<string>, source: readonly string[], destination: readonly string[]): FolderRemap[];
+/** One place a folder may be moved or merged to. `path` empty = the root. */
+export interface FolderTarget {
+    path: string[];
+    serialized: string;
+    /** `Home › Phones`, for a menu label. The root's label is the caller's word for it. */
+    label: string;
+    key: string;
+}
+/**
+ * Every folder `source` may legally be moved into, deepest-first within each branch.
+ *
+ * 🔴 A folder can never be moved into itself or into one of its own descendants — that
+ * orphans the subtree, and `planFolderMove` throws on it. Filtering the DESTINATIONS rather
+ * than catching the throw is what makes the menu honest: the offer a person is shown is the
+ * set of offers that work, so there is no way to pick one and be told no.
+ *
+ * The current parent is filtered out too. "Move it to where it already is" is not a
+ * no-op a person meant to ask for; it is a menu entry that does nothing, which reads as a
+ * broken control.
+ */
+export declare function folderMoveTargets(nodes: readonly FolderNode[], source: readonly string[], options?: {
+    rootLabel?: string;
+    separator?: string;
+}): FolderTarget[];
+/**
+ * What "delete this folder" is allowed to mean.
+ *
+ * Two modes rather than one, because the owner asked for both in one sentence and they are
+ * opposites: one is a filing change and the other destroys files. They are never the same
+ * button — see {@link FolderActionsMenuProps} for how the menu keeps them apart.
+ */
+export type FolderDeleteMode = 
+/** Splice the folder out; every item keeps existing, one path segment shorter. */
+"ungroup"
+/** Delete the folder AND everything in it. The consumer's store does this, not us. */
+ | "purge";

package/dist/core/folder-tree/actions.js

@@ -0,0 +1,119 @@
+/**
+ * The FOLDER OPERATIONS every app with folders offers — one model, so "move it into
+ * that one" means the same thing in music as it does in collections.
+ *
+ * ── The owner's ask, verbatim (draft, 2026-08-25) ───────────────────────────────────────
+ * *"in cb make or ensure we have a standardized folder list view. I want it applied to
+ * music app and collections app and other apps with folders like that which should get the
+ * same features if any. The features should include a 3 dot menu for choosing to move all
+ * contents to a different folder or move a folder into another folder. For instance I could
+ * move rock songs from a folder 'extra-rock-songs' to a 'rock' folder with it. Also allow
+ * deleting a folder which deletes all the folder contents or allows deleting the folder and
+ * having the contents not grouped in a folder anymore. Allow renaming folders."*
+ *
+ * ── 🔴 Four verbs, and three of them already existed ────────────────────────────────────
+ * `planFolderRename`, `planFolderMove` and `planFolderDelete` in `tree.ts` are exactly
+ * rename, "move a folder into another folder", and "delete the folder and leave the
+ * contents ungrouped" — built for the vault and notes, and reachable from no menu anywhere.
+ * The gap the owner is describing is not model, it is SURFACE: every app grew its own
+ * subset of folder tools, so the operations that were never wired are the ones nobody has.
+ * This module adds the ONE missing verb and the shared descriptions; the menu that renders
+ * them is `react/folder-tree/FolderActionsMenu`.
+ *
+ * ── 🔴 Why "delete the contents too" is not a plan ──────────────────────────────────────
+ * The other three verbs are pure path rewrites — a {@link FolderRemap} list the consumer
+ * applies, with nothing destroyed. Deleting the CONTENTS destroys items, and this module
+ * has never seen an item; it only ever sees the paths they carry. So `purge` is a mode the
+ * menu offers and the CONSUMER implements against its own store, which is also the only
+ * place that can count what is about to be lost or refuse the operation. Modelling it here
+ * would mean inventing an item, and an item this model cannot see is one it cannot protect.
+ */
+import { folderPathKey, isFolderPathUnder, parseFolderPath, serializeFolderPath, } from "./path";
+/**
+ * Move everything at or under `source` INTO `destination`, and stop `source` existing.
+ *
+ * The owner's own example: *"I could move rock songs from a folder 'extra-rock-songs' to a
+ * 'rock' folder with it."* Items directly in `extra-rock-songs` land directly in `rock`;
+ * `extra-rock-songs/live` becomes `rock/live`.
+ *
+ * 🔴 This is NOT `planFolderMove`, and the difference is the whole reason it exists.
+ * `planFolderMove(source, newParent)` makes `source` a CHILD — `rock/extra-rock-songs` —
+ * which keeps the folder the owner is trying to get rid of. Both are real operations a
+ * person wants ("put this inside that" vs "empty this into that"), they read almost
+ * identically in a menu, and getting them confused is silent: the files are all present and
+ * the folder you meant to dissolve is still there one level down.
+ *
+ * @param destination an empty array means the ROOT — "take these out of any folder".
+ */
+export function planFolderMergeInto(serializedPaths, source, destination) {
+    if (source.length === 0)
+        throw new Error("cannot move the root's contents");
+    if (isFolderPathUnder(destination, source)) {
+        throw new Error("cannot move a folder's contents into itself or one of its descendants");
+    }
+    const out = [];
+    const seen = new Set();
+    for (const raw of serializedPaths) {
+        const path = parseFolderPath(raw);
+        if (path.length === 0 || !isFolderPathUnder(path, source))
+            continue;
+        const key = folderPathKey(path);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        // Drop the whole SOURCE prefix and re-root what is left under `destination`.
+        const moved = [...destination, ...path.slice(source.length)];
+        const from = serializeFolderPath(path);
+        const to = serializeFolderPath(moved);
+        if (from !== to)
+            out.push({ from, to });
+    }
+    return out;
+}
+/**
+ * Every folder `source` may legally be moved into, deepest-first within each branch.
+ *
+ * 🔴 A folder can never be moved into itself or into one of its own descendants — that
+ * orphans the subtree, and `planFolderMove` throws on it. Filtering the DESTINATIONS rather
+ * than catching the throw is what makes the menu honest: the offer a person is shown is the
+ * set of offers that work, so there is no way to pick one and be told no.
+ *
+ * The current parent is filtered out too. "Move it to where it already is" is not a
+ * no-op a person meant to ask for; it is a menu entry that does nothing, which reads as a
+ * broken control.
+ */
+export function folderMoveTargets(nodes, source, options = {}) {
+    const separator = options.separator ?? " › ";
+    const currentParent = folderPathKey(source.slice(0, -1));
+    const targets = [];
+    // The root, unless the folder is already at the top level.
+    if (source.length > 1) {
+        targets.push({
+            path: [],
+            serialized: "",
+            label: options.rootLabel ?? "Top level",
+            key: folderPathKey([]),
+        });
+    }
+    const walk = (list) => {
+        for (const node of list) {
+            const key = folderPathKey(node.path);
+            const isSelfOrDescendant = isFolderPathUnder(node.path, source);
+            if (!isSelfOrDescendant && key !== currentParent) {
+                targets.push({
+                    path: [...node.path],
+                    serialized: node.serialized,
+                    label: node.path.join(separator),
+                    key,
+                });
+            }
+            // 🔴 Descend even into a branch that was itself refused: only the SUBTREE of
+            // `source` is unreachable. The current parent is skipped as a target and its
+            // children are perfectly good ones.
+            if (!isSelfOrDescendant)
+                walk(node.children);
+        }
+    };
+    walk(nodes);
+    return targets;
+}

package/dist/core/folder-tree/index.d.ts

@@ -0,0 +1,3 @@
+export { FOLDER_PATH_DELIMITER, FOLDER_PATH_ESCAPE, folderDescendantPrefix, folderPathKey, formatFolderPath, isFolderPathUnder, isValidFolderName, normalizeFolderName, parseFolderPath, serializeFolderPath, } from "./path";
+export { buildFolderIndex, buildFolderTree, flattenFolderTree, type FolderIndex, type FolderNode, type FolderRemap, planFolderDelete, planFolderMove, planFolderRename, } from "./tree";
+export { type FolderDeleteMode, type FolderTarget, folderMoveTargets, planFolderMergeInto, } from "./actions";

package/dist/core/folder-tree/index.js

@@ -0,0 +1,20 @@
+// cursedbelt-core/folder-tree — the PURE nested-folder model: path encoding, the derived
+// tree, per-folder counts, and the structural-edit plans (rename/move/delete). No
+// React, no DOM, node-builtin-free — so a SERVER can hold the same folder semantics
+// its UI does.
+//
+//   import { buildFolderTree, planFolderRename, serializeFolderPath } from 'cursedbelt-core/folder-tree';
+//
+// The three UI pieces (rail, picker, breadcrumb) live at `cursedbelt/react/folder-tree`,
+// which re-exports everything here — so a browser-only consumer keeps one import.
+//
+// ── Why the model is its own export ─────────────────────────────────────────────
+// The vault (the first consumer) is zero-knowledge: folders are derived entirely in
+// the browser from encrypted meta, so a React subpath was the whole world. `apps/notes`
+// is the second, and its folders are SERVER state — filed items are searched, filtered
+// and bulk-moved by SQL. Importing the React barrel into a Bun server to reach
+// `isFolderPathUnder` would drag `Button`/`Input` and the whole component graph into a
+// process that renders nothing. Same law as `cursedbelt-core/sharing` vs `cursedbelt/react/sharing`.
+export { FOLDER_PATH_DELIMITER, FOLDER_PATH_ESCAPE, folderDescendantPrefix, folderPathKey, formatFolderPath, isFolderPathUnder, isValidFolderName, normalizeFolderName, parseFolderPath, serializeFolderPath, } from "./path";
+export { buildFolderIndex, buildFolderTree, flattenFolderTree, planFolderDelete, planFolderMove, planFolderRename, } from "./tree";
+export { folderMoveTargets, planFolderMergeInto, } from "./actions";

package/dist/core/folder-tree/path.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Folder PATH encoding — the storage contract every consumer of the folder tree
+ * shares. A folder path is an ordered array of segment names (`["Home","Phones",
+ * "Noah"]`); on disk it is a single delimiter-joined STRING so it can ride in one
+ * field (an entry's `meta.folder`, a note's group tag) without a separate registry.
+ *
+ * ── Why a delimited string and not id references ─────────────────────────────
+ * The first consumer (the vault) is a zero-knowledge, op-log-synced store: a folder
+ * lives inside an entry's ENCRYPTED meta, and there is no server-side place to keep
+ * an id→name map that every device would have to converge on. Deriving the whole
+ * tree from the set of path strings on the items keeps folders a pure function of
+ * the items — nothing extra to sync, nothing to version-skew. The cost is that a
+ * folder exists only while it (or a descendant) holds an item; that is the same
+ * "derived, not declared" model the vault already used for flat folders, extended
+ * to nesting.
+ *
+ * ── The delimiter, and why it is ESCAPED rather than forbidden ───────────────
+ * `/` joins segments. A `/` is common enough inside a real folder name ("TV/Film",
+ * "and/or") that forbidding it would be a footgun, and — critically — a MIGRATION
+ * hazard: a legacy flat folder literally named "TV/Movies" must stay ONE folder,
+ * not silently split into two. So the delimiter is escaped, not banned: a literal
+ * `/` in a name becomes `\/` and a literal `\` becomes `\\`. Serialize→parse is a
+ * lossless round trip for any name that is non-empty and free of control chars.
+ */
+/** The character that joins path segments in the stored string. */
+export declare const FOLDER_PATH_DELIMITER = "/";
+/** The escape character. A literal delimiter or escape inside a name is prefixed. */
+export declare const FOLDER_PATH_ESCAPE = "\\";
+/** Trim a raw name for use as a segment. Internal whitespace is preserved; only the
+ *  ends are trimmed, so "  My Bank " and "My Bank" are the same folder. */
+export declare function normalizeFolderName(name: string): string;
+/** A folder name is valid iff it is non-empty after trimming and carries no control
+ *  characters (which would corrupt the stored string and never render). The
+ *  delimiter and escape are ALLOWED — they are escaped on serialize. */
+export declare function isValidFolderName(name: string): boolean;
+/**
+ * Serialize a path (array of segment names) into the stored string. Empty and
+ * whitespace-only segments are dropped, and each surviving segment is trimmed, so
+ * the output is canonical: `serialize(parse(s))` normalizes any spelling of `s`.
+ */
+export declare function serializeFolderPath(segments: readonly string[]): string;
+/**
+ * Parse a stored string back into its segment array. Splits on UNESCAPED delimiters
+ * only, then unescapes each segment. Empty segments (a leading/trailing/double
+ * delimiter) are dropped rather than becoming blank folders.
+ */
+export declare function parseFolderPath(serialized: string): string[];
+/**
+ * A case-insensitive identity key for a path — the thing two paths compare equal by.
+ * Folder names dedupe case-insensitively (like the flat rail always did), so "Work"
+ * and "work" are one folder, but the key is still per-SEGMENT so "Home/Phones" and
+ * "Homework/hones" never collide (which a naive lowercased-string prefix would).
+ */
+export declare function folderPathKey(segments: readonly string[]): string;
+/** True when `child` is `parent` or sits anywhere beneath it (segment-aligned, so
+ *  `Home` contains `Home/Phones` but NOT `Homework`). An empty `parent` (the root)
+ *  contains everything. */
+export declare function isFolderPathUnder(child: readonly string[], parent: readonly string[]): boolean;
+/**
+ * The stored-string prefix EVERY descendant of `segments` starts with, and nothing
+ * else does — `serialize(segments) + "/"`. It exists so a store that keeps the
+ * serialized path in one column (a SQL `LIKE 'Home/%'`, a `startsWith` on a key/value
+ * store) can select a whole subtree without parsing every row.
+ *
+ * It is exact BECAUSE the delimiter is escaped: a folder literally named `TV/Film`
+ * serializes as `TV\/Film`, whose fifth character is the escape, so it can never be
+ * mistaken for `TV` + a child. `Homework` does not start with `Home/` either. The one
+ * thing the prefix does NOT cover is the folder itself — a caller wants
+ * `path = serialized OR path LIKE prefix || '%'`, which is what `isFolderPathUnder`
+ * says in memory. The root (an empty path) has no prefix that means "everything", so
+ * it returns `""` and the caller should skip the filter entirely.
+ */
+export declare function folderDescendantPrefix(segments: readonly string[]): string;
+/** Render a path as a human breadcrumb: `Home › Phones › Noah`. The separator is a
+ *  display choice; the default is the one the picker and rail use. */
+export declare function formatFolderPath(segments: readonly string[], separator?: string): string;