cursedbelt-core 1.0.0

package/src/core/folder-tree/actions.ts

@@ -0,0 +1,153 @@
+/**
+ * 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";
+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 function planFolderMergeInto(
+	serializedPaths: Iterable<string>,
+	source: readonly string[],
+	destination: readonly string[],
+): FolderRemap[] {
+	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: FolderRemap[] = [];
+	const seen = new Set<string>();
+	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;
+}
+
+/** 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 function folderMoveTargets(
+	nodes: readonly FolderNode[],
+	source: readonly string[],
+	options: { rootLabel?: string; separator?: string } = {},
+): FolderTarget[] {
+	const separator = options.separator ?? " › ";
+	const currentParent = folderPathKey(source.slice(0, -1));
+	const targets: FolderTarget[] = [];
+	// 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: readonly FolderNode[]): void => {
+		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;
+}
+
+/**
+ * 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/src/core/folder-tree/index.ts

@@ -0,0 +1,46 @@
+// 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,
+	type FolderIndex,
+	type FolderNode,
+	type FolderRemap,
+	planFolderDelete,
+	planFolderMove,
+	planFolderRename,
+} from "./tree";
+export {
+	type FolderDeleteMode,
+	type FolderTarget,
+	folderMoveTargets,
+	planFolderMergeInto,
+} from "./actions";

package/src/core/folder-tree/path.spec.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from "bun:test";
+import {
+	folderDescendantPrefix,
+	folderPathKey,
+	formatFolderPath,
+	isFolderPathUnder,
+	isValidFolderName,
+	parseFolderPath,
+	serializeFolderPath,
+} from "./path";
+
+describe("folder path serialization", () => {
+	test("round-trips a simple nested path", () => {
+		const path = ["Home", "Phones", "Noah"];
+		const s = serializeFolderPath(path);
+		expect(s).toBe("Home/Phones/Noah");
+		expect(parseFolderPath(s)).toEqual(path);
+	});
+
+	test("escapes a literal delimiter inside a name so it stays ONE segment", () => {
+		const path = ["TV/Movies"];
+		const s = serializeFolderPath(path);
+		expect(s).toBe("TV\\/Movies");
+		expect(parseFolderPath(s)).toEqual(["TV/Movies"]);
+	});
+
+	test("escapes a literal backslash", () => {
+		const path = ["a\\b", "c"];
+		const s = serializeFolderPath(path);
+		expect(s).toBe("a\\\\b/c");
+		expect(parseFolderPath(s)).toEqual(["a\\b", "c"]);
+	});
+
+	test("a name containing an escaped-delimiter sequence round-trips", () => {
+		const path = ["a\\/b"]; // literally: a, backslash, slash, b
+		expect(parseFolderPath(serializeFolderPath(path))).toEqual(path);
+	});
+
+	test("trims segments and drops empty ones", () => {
+		expect(serializeFolderPath(["  Home  ", "", "  ", "Phones"])).toBe("Home/Phones");
+		expect(parseFolderPath("/Home//Phones/")).toEqual(["Home", "Phones"]);
+	});
+
+	test("empty path is the empty string and back", () => {
+		expect(serializeFolderPath([])).toBe("");
+		expect(parseFolderPath("")).toEqual([]);
+	});
+});
+
+describe("folder name validity", () => {
+	test("accepts ordinary names, including ones with a slash", () => {
+		expect(isValidFolderName("Work")).toBe(true);
+		expect(isValidFolderName("TV/Movies")).toBe(true);
+		expect(isValidFolderName("  padded  ")).toBe(true);
+	});
+
+	test("rejects blank and whitespace-only names", () => {
+		expect(isValidFolderName("")).toBe(false);
+		expect(isValidFolderName("   ")).toBe(false);
+	});
+
+	test("rejects control characters", () => {
+		expect(isValidFolderName("a\tb")).toBe(false);
+		expect(isValidFolderName("a\nb")).toBe(false);
+	});
+});
+
+describe("path identity + containment", () => {
+	test("keys dedupe case-insensitively per segment", () => {
+		expect(folderPathKey(["Work"])).toBe(folderPathKey(["work"]));
+		expect(folderPathKey(["Home", "Phones"])).toBe(folderPathKey(["home", "PHONES"]));
+	});
+
+	test("distinct nested paths never collide on the key (no naive string prefix)", () => {
+		expect(folderPathKey(["Home", "Phones"])).not.toBe(folderPathKey(["Homework", "hones"]));
+	});
+
+	test("containment is segment-aligned", () => {
+		expect(isFolderPathUnder(["Home", "Phones"], ["Home"])).toBe(true);
+		expect(isFolderPathUnder(["Home"], ["Home"])).toBe(true);
+		expect(isFolderPathUnder(["Homework"], ["Home"])).toBe(false);
+		expect(isFolderPathUnder(["Home"], [])).toBe(true); // root contains all
+	});
+
+	test("formats a breadcrumb", () => {
+		expect(formatFolderPath(["Home", "Phones", "Noah"])).toBe("Home › Phones › Noah");
+	});
+});
+
+describe("folderDescendantPrefix", () => {
+	test("is the prefix every descendant's stored path starts with", () => {
+		expect(folderDescendantPrefix(["Home"])).toBe("Home/");
+		expect(folderDescendantPrefix(["Home", "Phones"])).toBe("Home/Phones/");
+	});
+
+	test("a sibling whose NAME starts the same is not matched by it", () => {
+		const prefix = folderDescendantPrefix(["Home"]);
+		expect(serializeFolderPath(["Home", "Phones"]).startsWith(prefix)).toBe(true);
+		expect(serializeFolderPath(["Homework"]).startsWith(prefix)).toBe(false);
+	});
+
+	test("an escaped delimiter inside a name cannot be read as a child", () => {
+		// "TV/Film" is ONE folder; its stored form is `TV\/Film`, so a prefix search for
+		// the folder "TV" must not claim it. This is the migration hazard path.ts calls out.
+		const prefix = folderDescendantPrefix(["TV"]);
+		expect(serializeFolderPath(["TV/Film"]).startsWith(prefix)).toBe(false);
+		expect(serializeFolderPath(["TV", "Film"]).startsWith(prefix)).toBe(true);
+	});
+
+	test("the root has no prefix — the caller skips the filter instead", () => {
+		expect(folderDescendantPrefix([])).toBe("");
+	});
+});

package/src/core/folder-tree/path.ts

@@ -0,0 +1,148 @@
+/**
+ * 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 const FOLDER_PATH_DELIMITER = "/";
+/** The escape character. A literal delimiter or escape inside a name is prefixed. */
+export 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 function normalizeFolderName(name: string): string {
+	return name.trim();
+}
+
+/** 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 function isValidFolderName(name: string): boolean {
+	const n = normalizeFolderName(name);
+	if (n.length === 0) return false;
+	// Reject C0 control chars (0x00–0x1F) and DEL (0x7F): they never render and would
+	// corrupt the stored string. Checked by code point so no literal control byte
+	// (or the no-control-characters-in-regex lint) ever appears in this source.
+	for (const ch of n) {
+		const code = ch.codePointAt(0) ?? 0;
+		if (code < 0x20 || code === 0x7f) return false;
+	}
+	return true;
+}
+
+/** Escape one segment: `\` → `\\`, then `/` → `\/`. Order matters — escape the
+ *  escape first so a name containing `\/` is not double-decoded. */
+function escapeSegment(seg: string): string {
+	return seg
+		.replaceAll(FOLDER_PATH_ESCAPE, FOLDER_PATH_ESCAPE + FOLDER_PATH_ESCAPE)
+		.replaceAll(FOLDER_PATH_DELIMITER, FOLDER_PATH_ESCAPE + FOLDER_PATH_DELIMITER);
+}
+
+/**
+ * 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 function serializeFolderPath(segments: readonly string[]): string {
+	return segments
+		.map(normalizeFolderName)
+		.filter((s) => s.length > 0)
+		.map(escapeSegment)
+		.join(FOLDER_PATH_DELIMITER);
+}
+
+/**
+ * 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 function parseFolderPath(serialized: string): string[] {
+	const out: string[] = [];
+	let seg = "";
+	let escaped = false;
+	for (const ch of serialized) {
+		if (escaped) {
+			seg += ch;
+			escaped = false;
+		} else if (ch === FOLDER_PATH_ESCAPE) {
+			escaped = true;
+		} else if (ch === FOLDER_PATH_DELIMITER) {
+			out.push(seg);
+			seg = "";
+		} else {
+			seg += ch;
+		}
+	}
+	out.push(seg);
+	// A trailing lone escape (malformed input) is dropped with the empty tail.
+	return out.map(normalizeFolderName).filter((s) => s.length > 0);
+}
+
+/**
+ * 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 function folderPathKey(segments: readonly string[]): string {
+	return serializeFolderPath(segments.map((s) => normalizeFolderName(s).toLowerCase()));
+}
+
+/** 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 function isFolderPathUnder(child: readonly string[], parent: readonly string[]): boolean {
+	if (parent.length === 0) return true;
+	if (child.length < parent.length) return false;
+	for (let i = 0; i < parent.length; i++) {
+		const c = normalizeFolderName(child[i] ?? "").toLowerCase();
+		const p = normalizeFolderName(parent[i] ?? "").toLowerCase();
+		if (c !== p) return false;
+	}
+	return true;
+}
+
+/**
+ * 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 function folderDescendantPrefix(segments: readonly string[]): string {
+	const serialized = serializeFolderPath(segments);
+	return serialized === "" ? "" : serialized + FOLDER_PATH_DELIMITER;
+}
+
+/** 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 function formatFolderPath(segments: readonly string[], separator = " › "): string {
+	return segments.map(normalizeFolderName).join(separator);
+}

package/src/core/folder-tree/tree.spec.ts

@@ -0,0 +1,157 @@
+import { describe, expect, test } from "bun:test";
+import {
+	buildFolderIndex,
+	buildFolderTree,
+	flattenFolderTree,
+	type FolderNode,
+	planFolderDelete,
+	planFolderMove,
+	planFolderRename,
+} from "./tree";
+
+/** A compact "name(child,child)" view of a subtree, for readable assertions. */
+function shape(nodes: readonly FolderNode[]): string {
+	return nodes
+		.map((n) => (n.children.length ? `${n.name}(${shape(n.children)})` : n.name))
+		.join(",");
+}
+
+describe("buildFolderTree", () => {
+	test("derives intermediate ancestors from a deep leaf path", () => {
+		const tree = buildFolderTree(["Home/Phones/Noah"]);
+		expect(shape(tree)).toBe("Home(Phones(Noah))");
+		expect(tree[0]?.serialized).toBe("Home");
+		expect(tree[0]?.children[0]?.serialized).toBe("Home/Phones");
+		expect(tree[0]?.children[0]?.children[0]?.serialized).toBe("Home/Phones/Noah");
+	});
+
+	test("merges siblings and dedupes case-insensitively (first spelling wins)", () => {
+		const tree = buildFolderTree(["Home/Phones", "home/Tablets", "Work"]);
+		expect(shape(tree)).toBe("Home(Phones,Tablets),Work");
+	});
+
+	test("distinct people under distinct parents do NOT merge", () => {
+		const tree = buildFolderTree(["Home/Phones/Noah", "Work/Phones/Alex"]);
+		expect(shape(tree)).toBe("Home(Phones(Noah)),Work(Phones(Alex))");
+	});
+
+	test("flatten is depth-first, parent before child", () => {
+		const tree = buildFolderTree(["Home/Phones", "Work"]);
+		expect(flattenFolderTree(tree).map((n) => n.serialized)).toEqual([
+			"Home",
+			"Home/Phones",
+			"Work",
+		]);
+	});
+});
+
+describe("planFolderRename", () => {
+	const paths = ["Home", "Home/Phones", "Home/Phones/Noah", "Work"];
+
+	test("renames the folder and moves every descendant with it", () => {
+		const plan = planFolderRename(paths, ["Home", "Phones"], "Mobiles");
+		expect(plan).toEqual([
+			{ from: "Home/Phones", to: "Home/Mobiles" },
+			{ from: "Home/Phones/Noah", to: "Home/Mobiles/Noah" },
+		]);
+	});
+
+	test("renaming a root moves its whole subtree", () => {
+		const plan = planFolderRename(paths, ["Home"], "House");
+		expect(plan).toEqual([
+			{ from: "Home", to: "House" },
+			{ from: "Home/Phones", to: "House/Phones" },
+			{ from: "Home/Phones/Noah", to: "House/Phones/Noah" },
+		]);
+	});
+
+	test("does not touch unrelated folders", () => {
+		const plan = planFolderRename(paths, ["Home", "Phones"], "Mobiles");
+		expect(plan.some((r) => r.from === "Work")).toBe(false);
+	});
+
+	test("rejects a blank new name", () => {
+		expect(() => planFolderRename(paths, ["Home"], "  ")).toThrow();
+	});
+});
+
+describe("planFolderMove", () => {
+	const paths = ["Home", "Home/Phones", "Home/Phones/Noah", "Work"];
+
+	test("moves a subtree under a new parent", () => {
+		const plan = planFolderMove(paths, ["Home", "Phones"], ["Work"]);
+		expect(plan).toEqual([
+			{ from: "Home/Phones", to: "Work/Phones" },
+			{ from: "Home/Phones/Noah", to: "Work/Phones/Noah" },
+		]);
+	});
+
+	test("moving to the root drops the parent segment", () => {
+		const plan = planFolderMove(paths, ["Home", "Phones"], []);
+		expect(plan).toEqual([
+			{ from: "Home/Phones", to: "Phones" },
+			{ from: "Home/Phones/Noah", to: "Phones/Noah" },
+		]);
+	});
+
+	test("refuses to move a folder into its own descendant", () => {
+		expect(() => planFolderMove(paths, ["Home"], ["Home", "Phones"])).toThrow();
+	});
+
+	test("a no-op move (already there) yields no rewrites", () => {
+		expect(planFolderMove(paths, ["Home", "Phones"], ["Home"])).toEqual([]);
+	});
+});
+
+describe("planFolderDelete", () => {
+	const paths = ["Home", "Home/Phones", "Home/Phones/Noah", "Work"];
+
+	test("splices out the folder, re-homing descendants to the parent", () => {
+		const plan = planFolderDelete(paths, ["Home", "Phones"]);
+		expect(plan).toEqual([
+			{ from: "Home/Phones", to: "Home" },
+			{ from: "Home/Phones/Noah", to: "Home/Noah" },
+		]);
+	});
+
+	test("deleting a root re-homes its direct items to no-folder", () => {
+		const plan = planFolderDelete(paths, ["Home"]);
+		expect(plan).toContainEqual({ from: "Home", to: "" });
+		expect(plan).toContainEqual({ from: "Home/Phones", to: "Phones" });
+		expect(plan).toContainEqual({ from: "Home/Phones/Noah", to: "Phones/Noah" });
+	});
+});
+
+describe("duplicate names under different parents", () => {
+	test("rename touches only the targeted branch (only STORED paths are remapped)", () => {
+		// Only leaf paths are stored on items here — "Home/Phones" exists as an ancestor
+		// node but no item sits directly in it, so it needs no rewrite.
+		const paths = ["Home/Phones/Noah", "Work/Phones/Alex"];
+		const plan = planFolderRename(paths, ["Home", "Phones"], "Mobiles");
+		expect(plan).toEqual([{ from: "Home/Phones/Noah", to: "Home/Mobiles/Noah" }]);
+		expect(plan.some((r) => r.from.startsWith("Work"))).toBe(false);
+	});
+});
+
+describe("buildFolderIndex", () => {
+	const paths = ["Home/Phones/Noah", "Home/Phones/Noah", "Home/Taxes", "Work", ""];
+
+	test("counts are CUMULATIVE, so a collapsed parent still totals its subtree", () => {
+		const index = buildFolderIndex(paths);
+		expect(index.count("Home")).toBe(3);
+		expect(index.count("Home/Phones")).toBe(2);
+		expect(index.count("Home/Phones/Noah")).toBe(2);
+		expect(index.count("Work")).toBe(1);
+	});
+
+	test("the tree is the same one buildFolderTree derives, and empty paths are ignored", () => {
+		const index = buildFolderIndex(paths);
+		expect(index.tree.map((n) => n.name)).toEqual(["Home", "Work"]);
+		expect(index.count("Nowhere")).toBe(0);
+	});
+
+	test("counts are case-insensitive on the path, like every other folder identity", () => {
+		const index = buildFolderIndex(["Home/Taxes"]);
+		expect(index.count("home/taxes")).toBe(1);
+	});
+});