@milaboratories/pl-middle-layer 1.71.16 → 1.72.0

package/dist/middle_layer/middle_layer.js

@@ -2,9 +2,11 @@ import { V2RegistryProvider } from "../block_registry/registry-v2-provider.js";
 import "../block_registry/index.js";
 import { ProjectMetaKey } from "../model/project_model.js";
 import { ProjectsField, ProjectsResourceType, createProjectList, ensureProjectListRid } from "./project_list.js";
-import { TemplateLabelKey, TemplatesField, TemplatesResourceType, createTemplateList, decodeStoredTemplateData } from "./template_list.js";
-import { createTemplate, deleteTemplate, renameTemplate } from "../mutator/template.js";
-import { SharingOutboxField, SharingOutboxResourceType, SharingStateField, SharingStateResourceType, acceptanceFieldLogin, canGrantToEveryone, canImpersonate, decodeEnvelopeData, envelopeProjectMap, isAcceptanceField } from "../model/sharing_model.js";
+import { TemplateDescriptionKey, TemplateLabelKey, TemplatesField, TemplatesResourceType, createTemplateList, decodeStoredTemplateData } from "./template_list.js";
+import { listedById, notListedError } from "../mutator/list.js";
+import { createTemplate, deleteTemplate, renameTemplate, setTemplateDescription } from "../mutator/template.js";
+import { FoldersField, FoldersResourceType, createFolder, createFolderList, deleteFolder, foldersLocalSubtree, moveFolderItems, openFoldersTx, previewFolderDeletion, previewFoldersMove, renameFolder, resetFolders, setFolderDescription } from "./folders.js";
+import { SharingOutboxField, SharingOutboxResourceType, SharingStateField, SharingStateResourceType, canGrantToEveryone, canImpersonate, decodeEnvelopeData, envelopeFolderRoot, newEnvelopeFolderId } from "../model/sharing_model.js";
 import { resolveTemplateEntries } from "../model/template_resolve.js";
 import { TemplateEntryRejected, kindMismatch } from "../model/template_apply.js";
 import { BlockPackPreparer } from "../mutator/block-pack/block_pack.js";
@@ -13,8 +15,8 @@ import { createProject, duplicateProject, withProject, withProjectAuthored } fro
 import { applyTemplateEntries } from "../mutator/template_construct.js";
 import { cacheBlockPackTemplate } from "../mutator/template/template_cache.js";
 import { Project, throwIfMissingServerCapabilities } from "./project.js";
-import { buildShareEnvelope, buildTemplateShareEnvelope, copyEnvelopeProjectsIntoList, envelopeProjectFieldUuid, isEnvelopeProjectField, resourceIdsToStrings, writeEnvelopeAcceptance, writeSharingDecision } from "../mutator/sharing.js";
-import { createLiveEnvelopesComputable, createOutgoingShares, createPendingSharesComputable, createPendingSharesTree, createSharingStateTree } from "./sharing_list.js";
+import { buildFolderShareEnvelope, buildShareEnvelope, buildTemplateShareEnvelope, clearShareHidden, copyEnvelopeProjectsIntoList, writeShareHidden } from "../mutator/sharing.js";
+import { createAvailableSharesComputable, createAvailableSharesTree, createLiveEnvelopesComputable, createOutgoingShares, createSharingStateTree } from "./sharing_list.js";
 import { DefaultMiddleLayerOpsPaths, DefaultMiddleLayerOpsSettings } from "./ops.js";
 import { BlockUpdateWatcher } from "../block_registry/watcher.js";
 import { initDriverKit } from "./driver_kit.js";
@@ -22,10 +24,11 @@ import { createModelServiceRegistry } from "../service_factories.js";
 import { ProjectHelper } from "../model/project_helper.js";
 import { TreeSnapshotStore } from "./tree_snapshot_store.js";
 import { RuntimeCapabilities, ensureError, extractConfig } from "@platforma-sdk/model";
+import { foldersNameTaken, foldersUniqueName, inheritedFolder, normalizeDescription } from "@milaboratories/pl-model-middle-layer";
 import { RetryAgent } from "undici";
-import { BlockEventDispatcher, HmacSha256Signer, cachedDeserialize } from "@milaboratories/ts-helpers";
-import { REQUIRES_PFRAMES_VERSION, registerServiceCapabilities } from "@milaboratories/pl-model-common";
-import { GrantType, field, isEveryoneUserLogin, isNotNullSignedResourceId, isNullSignedResourceId, resourceIdToString } from "@milaboratories/pl-client";
+import { BlockEventDispatcher, HmacSha256Signer } from "@milaboratories/ts-helpers";
+import { REQUIRES_PFRAMES_VERSION, asProjectId, asTemplateId, registerServiceCapabilities } from "@milaboratories/pl-model-common";
+import { GrantType, field, isNullSignedResourceId, resourceIdToString } from "@milaboratories/pl-client";
 import { LRUCache } from "lru-cache";
 import { WatchableValue } from "@milaboratories/computable";
 import { randomUUID } from "node:crypto";
@@ -55,20 +58,23 @@ var MiddleLayer = class MiddleLayer {
 	templateListResourceId;
 	sharingOutboxResourceId;
 	sharingStateResourceId;
+	foldersResourceId;
 	openedProjectsList;
 	projectListTree;
 	templateListTree;
+	foldersTree;
 	sharingOutboxTree;
 	sharingStateTree;
-	pendingSharesTree;
+	availableSharesTree;
 	blockRegistryProvider;
 	projectList;
 	templateList;
+	folders;
 	outgoingShares;
-	pendingShares;
+	availableShares;
 	liveEnvelopes;
 	pl;
-	constructor(env, driverKit, signer, projectListResourceId, templateListResourceId, sharingOutboxResourceId, sharingStateResourceId, openedProjectsList, projectListTree, templateListTree, sharingOutboxTree, sharingStateTree, pendingSharesTree, blockRegistryProvider, projectList, templateList, outgoingShares, pendingShares, liveEnvelopes) {
+	constructor(env, driverKit, signer, projectListResourceId, templateListResourceId, sharingOutboxResourceId, sharingStateResourceId, foldersResourceId, openedProjectsList, projectListTree, templateListTree, foldersTree, sharingOutboxTree, sharingStateTree, availableSharesTree, blockRegistryProvider, projectList, templateList, folders, outgoingShares, availableShares, liveEnvelopes) {
 		this.env = env;
 		this.driverKit = driverKit;
 		this.signer = signer;
@@ -76,17 +82,20 @@ var MiddleLayer = class MiddleLayer {
 		this.templateListResourceId = templateListResourceId;
 		this.sharingOutboxResourceId = sharingOutboxResourceId;
 		this.sharingStateResourceId = sharingStateResourceId;
+		this.foldersResourceId = foldersResourceId;
 		this.openedProjectsList = openedProjectsList;
 		this.projectListTree = projectListTree;
 		this.templateListTree = templateListTree;
+		this.foldersTree = foldersTree;
 		this.sharingOutboxTree = sharingOutboxTree;
 		this.sharingStateTree = sharingStateTree;
-		this.pendingSharesTree = pendingSharesTree;
+		this.availableSharesTree = availableSharesTree;
 		this.blockRegistryProvider = blockRegistryProvider;
 		this.projectList = projectList;
 		this.templateList = templateList;
+		this.folders = folders;
 		this.outgoingShares = outgoingShares;
-		this.pendingShares = pendingShares;
+		this.availableShares = availableShares;
 		this.liveEnvelopes = liveEnvelopes;
 		this.pl = this.env.pl;
 		this.startEnvelopeCleanup();
@@ -117,7 +126,7 @@ var MiddleLayer = class MiddleLayer {
 	/**
 	* Whether the connected backend supports project sharing. Synthetic — computed
 	* in the middle layer from the backend capabilities the share flow needs (the
-	* cross-color field-reference relaxation the accept flow rests on). It can absorb
+	* cross-color field-reference relaxation a copy out of a share rests on). It can absorb
 	* additional required capabilities later without a UI change.
 	*/
 	get sharingSupported() {
@@ -176,38 +185,258 @@ var MiddleLayer = class MiddleLayer {
 		const cached = this.projectIdCache.get(projectId);
 		if (cached !== void 0) return cached;
 		const rid = await this.pl.withReadTx("ResolveProjectId", async (tx) => {
-			const data = await tx.getResourceData(this.projectListResourceId, true);
-			for (const f of data.fields) {
-				if (isNullSignedResourceId(f.value)) continue;
-				if (resourceIdToString(f.value) === projectId) return f.value;
-			}
-			throw new Error(`Project ${projectId} not found in project list.`);
+			const entry = (await listedById(tx, this.projectListResourceId)).get(projectId);
+			if (entry === void 0) throw notListedError("Project", projectId);
+			return entry.rid;
 		});
 		this.projectIdCache.set(projectId, rid);
 		return rid;
 	}
-	/** Creates a project with initial state and adds it to project list. */
-	async createProject(meta) {
-		let prj;
-		await this.pl.withWriteTx("MLCreateProject", async (tx) => {
-			prj = await createProject(tx, meta);
+	/**
+	* Creates a project with initial state and adds it to project list.
+	*
+	* `folder` is where it lands, placed in the transaction that creates it so the project never
+	* shows up at the top level first. Left out, or naming a folder that is gone, it lands at the
+	* top level.
+	*/
+	async createProject(meta, folder) {
+		const signedRid = await this.pl.withWriteTx("MLCreateProject", async (tx) => {
+			const tree = folder === void 0 ? void 0 : await openFoldersTx(tx, this.foldersRids);
+			const prj = await createProject(tx, meta);
 			tx.createField(field(this.projectListResourceId, randomUUID()), "Dynamic", prj);
+			const rid = await prj.globalId;
+			if (tree !== void 0 && tree.view.folders.some((candidate) => candidate.id === folder)) tree.place([{
+				kind: "project",
+				id: asProjectId(resourceIdToString(rid))
+			}], folder);
 			await tx.commit();
+			return rid;
 		});
-		await this.projectListTree.refreshState();
-		const signedRid = await prj.globalId;
-		const projectId = resourceIdToString(signedRid);
+		await Promise.all([this.projectListTree.refreshState(), ...folder === void 0 ? [] : [this.foldersTree.refreshState()]]);
+		const projectId = asProjectId(resourceIdToString(signedRid));
 		this.projectIdCache.set(projectId, signedRid);
 		return projectId;
 	}
-	/** Updates project metadata */
+	/**
+	* Updates the project metadata fields the caller names, leaving the others as they are.
+	*
+	* A patch rather than a replacement because the label and the description are edited from two
+	* different places: a rename that carried a stale description alongside the new name would
+	* undo a description edit that happened in between, and the reverse.
+	*
+	* The label is stored trimmed, and it goes into the namespace folders share, so a label
+	* already carried by something else inside the same folder is refused rather than written — a
+	* human typed it, and a name that silently becomes a different name is worse than one that is
+	* turned down. The check and the write share one transaction, so two renames racing for the
+	* same name cannot both win. Duplicates an account already holds are tolerated and never
+	* rewritten; see the name check of {@link openFoldersTx}.
+	*/
 	async setProjectMeta(id, meta, author) {
 		const rid = await this.resolveProjectId(id);
-		await withProjectAuthored(this.env.projectHelper, this.pl, rid, author, (prj) => {
-			prj.setMeta(meta);
-		}, { name: "setProjectMeta" });
+		const label = meta.label?.trim();
+		const patch = label === void 0 ? meta : {
+			...meta,
+			label
+		};
+		await this.pl.withWriteTx("ProjectAction: setProjectMeta", async (tx) => {
+			if (label !== void 0) (await openFoldersTx(tx, this.foldersRids)).assertNameFree({
+				kind: "project",
+				id
+			}, label);
+			await withProjectAuthored(this.env.projectHelper, tx, rid, author, (prj) => {
+				prj.updateMeta(patch);
+			});
+			await tx.commit();
+		});
 		await this.projectListTree.refreshState();
 	}
+	get foldersRids() {
+		return {
+			folders: this.foldersResourceId,
+			projects: this.projectListResourceId,
+			templates: this.templateListResourceId
+		};
+	}
+	/** Creates a folder inside `parent`, or at the top level, and returns its id. A name already
+	*  used there is rejected. */
+	async createFolder(name, parent) {
+		const id = await createFolder(this.pl, this.foldersRids, name, parent);
+		await this.foldersTree.refreshState();
+		return id;
+	}
+	/** Renames a folder. A name already used beside it is rejected. */
+	async renameFolder(folder, name) {
+		await renameFolder(this.pl, this.foldersRids, folder, name);
+		await this.foldersTree.refreshState();
+	}
+	/** Sets what a folder says about itself; blank clears it. Descriptions are in no namespace, so
+	*  nothing is refused here. */
+	async setFolderDescription(folder, description) {
+		await setFolderDescription(this.pl, this.foldersRids, folder, description);
+		await this.foldersTree.refreshState();
+	}
+	/** The plan a move would produce — every item and the name it ends up with. Shown for
+	*  confirmation, then handed back to {@link moveFolderItems} unchanged. */
+	async previewFoldersMove(items, destination) {
+		return await previewFoldersMove(this.pl, this.foldersRids, items, destination);
+	}
+	/**
+	* Moves folders, projects and templates into one destination.
+	*
+	* The plan is recomputed inside the write transaction and the move commits only when it is
+	* identical to `confirmedPlan`; otherwise nothing is written and the fresh plan comes back to
+	* be confirmed again.
+	*/
+	async moveFolderItems(items, destination, confirmedPlan) {
+		const outcome = await moveFolderItems(this.pl, this.foldersRids, items, destination, confirmedPlan);
+		if (outcome.ok) await Promise.all([
+			this.foldersTree.refreshState(),
+			this.projectListTree.refreshState(),
+			this.templateListTree.refreshState()
+		]);
+		return outcome;
+	}
+	/** What deleting a folder would destroy: the subtree of folders, and everything in it. */
+	async previewFolderDeletion(folder) {
+		return await previewFolderDeletion(this.pl, this.foldersRids, folder);
+	}
+	/** Deletes a folder, every folder inside it, and every project and template held anywhere in
+	*  that subtree.
+	*  Refused as `needs-confirmation` until the removal it returns is passed back as
+	*  `confirmedRemoval`, and as `plan-changed` if the subtree has changed since. */
+	async deleteFolder(folder, confirmedRemoval) {
+		const outcome = await deleteFolder(this.pl, this.foldersRids, folder, confirmedRemoval);
+		if (outcome.ok) {
+			for (const id of outcome.removal.projects) this.projectIdCache.delete(id);
+			for (const id of outcome.removal.templates) this.templateIdCache.delete(id);
+			await Promise.all([
+				this.foldersTree.refreshState(),
+				this.projectListTree.refreshState(),
+				this.templateListTree.refreshState()
+			]);
+		}
+		return outcome;
+	}
+	/**
+	* Replaces a folder document this build cannot read — one written by a newer version, or one
+	* nothing here can parse — with an empty one. Every folder is gone afterwards; every project and
+	* template stays and shows at the top level. Refused while the document can be read.
+	*/
+	async resetFolders() {
+		await resetFolders(this.pl, this.foldersRids);
+		await this.foldersTree.refreshState();
+	}
+	/**
+	* Duplicates a folder and everything under it: the folders inside, a duplicate of every project
+	* in them, and a copy of every template.
+	*
+	* The copy lands beside the source, so only its root needs a name of its own — `X (Copy)`.
+	* Nothing inside is renamed: names are compared among siblings, and a copied folder's children
+	* are only ever compared with each other, where they came in distinct already.
+	*
+	* The subtree is read first and rebuilt in one write transaction, so the folders and everything
+	* they hold appear together or not at all.
+	*/
+	async duplicateFolder(folder) {
+		const subtree = await this.loadFolderSubtree(folder, () => randomUUID());
+		const created = await this.pl.withWriteTx("MLDuplicateFolder", async (tx) => {
+			const tree = await openFoldersTx(tx, this.foldersRids);
+			const items = [];
+			const projects = [];
+			const templates = [];
+			for (const project of subtree.projects) {
+				const meta = await tx.getKValueJson(project.rid, ProjectMetaKey);
+				const copy = await duplicateProject(tx, project.rid, meta, this.env.projectHelper);
+				tx.createField(field(this.projectListResourceId, randomUUID()), "Dynamic", copy);
+				const rid = await copy.globalId;
+				projects.push(rid);
+				items.push({
+					kind: "project",
+					id: asProjectId(resourceIdToString(rid)),
+					folder: project.folder
+				});
+			}
+			for (const template of subtree.templates) {
+				const rid = await createTemplate(tx, this.templateListResourceId, {
+					label: template.label,
+					description: template.description
+				}, template.data).globalId;
+				const id = asTemplateId(resourceIdToString(rid));
+				templates.push({
+					id,
+					rid
+				});
+				items.push({
+					kind: "template",
+					id,
+					folder: template.folder
+				});
+			}
+			tree.graft({
+				root: subtree.root,
+				folders: subtree.folders,
+				items
+			}, subtree.parent);
+			await tx.commit();
+			return {
+				projects,
+				templates
+			};
+		});
+		for (const rid of created.projects) this.projectIdCache.set(asProjectId(resourceIdToString(rid)), rid);
+		for (const { id, rid } of created.templates) this.templateIdCache.set(id, rid);
+		await Promise.all([
+			this.foldersTree.refreshState(),
+			this.projectListTree.refreshState(),
+			this.templateListTree.refreshState()
+		]);
+	}
+	/**
+	* A folder subtree as a copy needs it: the folders under ids local to this read, the key the
+	* subtree's root goes by, the resource of every project in them, every template read whole, and
+	* the folder the source sits in — which is where a duplicate lands.
+	*
+	* Read in a transaction of its own, before the write that copies it: every template is a read,
+	* and none of it has to be atomic with the copying, because a project or a template that
+	* disappears meanwhile fails that write on its own.
+	*/
+	async loadFolderSubtree(folder, mint) {
+		return await this.pl.withReadTx("MLReadFolderSubtree", async (tx) => {
+			const tree = await openFoldersTx(tx, this.foldersRids);
+			const source = tree.view.folders.find((candidate) => candidate.id === folder);
+			if (source === void 0) throw new Error(`Folder ${folder} does not exist.`);
+			const { inSubtree, localId, folders } = foldersLocalSubtree(tree.view, folder, mint);
+			const projects = [];
+			for (const project of tree.view.projects) {
+				if (project.folder === void 0 || !inSubtree.has(project.folder)) continue;
+				const rid = tree.projectRids.get(project.id);
+				if (rid === void 0) throw notListedError("Project", project.id);
+				projects.push({
+					projectId: project.id,
+					rid,
+					folder: localId(project.folder)
+				});
+			}
+			const templates = [];
+			for (const template of tree.view.templates) {
+				if (template.folder === void 0 || !inSubtree.has(template.folder)) continue;
+				const rid = tree.templateRids.get(template.id);
+				if (rid === void 0) throw notListedError("Template", template.id);
+				const local = localId(template.folder);
+				templates.push(readStoredTemplate(tx, template.id, rid).then((stored) => ({
+					...stored,
+					folder: local
+				})));
+			}
+			return {
+				...source.parent === void 0 ? {} : { parent: source.parent },
+				root: localId(folder),
+				folders,
+				projects,
+				templates: await Promise.all(templates)
+			};
+		});
+	}
 	/**
 	* Renders a project as a `template-v1` YAML document, or reports every reason it
 	* cannot be — the backing call for an "Export Project as Template…" command.
@@ -380,41 +609,81 @@ var MiddleLayer = class MiddleLayer {
 	* A block that cannot be expressed as a template entry stores nothing at all, and every
 	* such block is reported — fixing an unexportable project takes one pass, not one per block.
 	*
+	* The template lands beside its project, and is named by the rule everything there is named
+	* by: a label the caller chose is stored trimmed and refused if it is already used there, and
+	* without one the project's own label is taken — suffixed, since the project itself already
+	* answers to it.
+	*
+	* The template's description is the one the caller gives, stored trimmed; blank means none.
+	* Without one the template is stored undescribed, whatever the project's own description says.
+	*
 	* @param projectId project to snapshot
-	* @param label label for the template; defaults to the project's own label
+	* @param label label for the template; defaults to the project's own label, made free
+	* @param description what the template is for; blank or absent stores none
 	*/
-	async saveProjectAsTemplate(projectId, label) {
+	async saveProjectAsTemplate(projectId, label, description) {
 		const outcome = await this.exportProjectAsTemplate(projectId);
 		if (!outcome.ok) return {
 			ok: false,
 			problems: outcome.problems
 		};
 		const rid = await this.resolveProjectId(projectId);
-		let tpl;
-		await this.pl.withWriteTx("MLSaveProjectAsTemplate", async (tx) => {
+		const wanted = label?.trim();
+		const signedRid = await this.pl.withWriteTx("MLSaveProjectAsTemplate", async (tx) => {
 			const meta = await tx.getKValueJson(rid, ProjectMetaKey);
-			tpl = createTemplate(tx, this.templateListResourceId, label ?? meta.label, {
+			const tree = await openFoldersTx(tx, this.foldersRids);
+			const taken = tree.namesTakenBeside(projectId);
+			if (wanted !== void 0 && foldersNameTaken(wanted, taken)) throw new Error(`"${wanted}" is already used here.`);
+			const name = wanted ?? foldersUniqueName(meta.label, [meta.label, ...taken]);
+			const created = await createTemplate(tx, this.templateListResourceId, {
+				label: name,
+				description
+			}, {
 				schemaVersion: 1,
 				document: outcome.document,
 				sourceProjectLabel: meta.label
-			});
+			}).globalId;
+			tree.place([{
+				kind: "template",
+				id: asTemplateId(resourceIdToString(created))
+			}], tree.folderOf(projectId));
 			await tx.commit();
+			return created;
 		});
-		await this.templateListTree.refreshState();
-		const signedRid = await tpl.globalId;
-		const templateId = resourceIdToString(signedRid);
+		await Promise.all([this.templateListTree.refreshState(), this.foldersTree.refreshState()]);
+		const templateId = asTemplateId(resourceIdToString(signedRid));
 		this.templateIdCache.set(templateId, signedRid);
 		return {
 			ok: true,
 			templateId
 		};
 	}
-	/** Changes a template's label. The stored document is immutable and stays untouched —
-	*  improving a template means saving a new one. */
+	/**
+	* Changes a template's label. The stored document is immutable and stays untouched —
+	* improving a template means saving a new one.
+	*
+	* The label is stored trimmed. It is in the namespace folders, projects and templates share,
+	* so one already used beside the template is refused, in the transaction that writes it.
+	*/
 	async renameTemplate(id, label) {
 		const rid = await this.resolveTemplateId(id);
+		const wanted = label.trim();
 		await this.pl.withWriteTx("MLRenameTemplate", async (tx) => {
-			renameTemplate(tx, rid, label);
+			(await openFoldersTx(tx, this.foldersRids)).assertNameFree({
+				kind: "template",
+				id
+			}, wanted);
+			renameTemplate(tx, rid, wanted);
+			await tx.commit();
+		});
+		await this.templateListTree.refreshState();
+	}
+	/** Sets what a stored template says about itself; blank clears it. The stored document is not
+	*  touched, so it stays byte-identical. */
+	async setTemplateDescription(id, description) {
+		const rid = await this.resolveTemplateId(id);
+		await this.pl.withWriteTx("MLSetTemplateDescription", async (tx) => {
+			setTemplateDescription(tx, rid, description);
 			await tx.commit();
 		});
 		await this.templateListTree.refreshState();
@@ -455,7 +724,8 @@ var MiddleLayer = class MiddleLayer {
 	* @param id template to apply
 	* @param label label for the new project
 	* @param provider where each entry's block comes from
-	* @param options `allowUnstable` widens resolution to pre-release implementations
+	* @param options `allowUnstable` widens resolution to pre-release implementations; `folder` is
+	*   where the new project lands
 	*/
 	async createProjectFromTemplate(id, label, provider, options = {}) {
 		const stored = await this.getTemplateData(id);
@@ -464,7 +734,7 @@ var MiddleLayer = class MiddleLayer {
 			ok: false,
 			problems: preparation.problems
 		};
-		const projectId = await this.createProject({ label });
+		const projectId = await this.createProject({ label }, options.folder);
 		const report = await this.applyPreparedEntries(projectId, stored.document, preparation.prepared, options.author);
 		if (report.problems.length > 0) {
 			await this.deleteProject(projectId);
@@ -485,12 +755,9 @@ var MiddleLayer = class MiddleLayer {
 		const cached = this.templateIdCache.get(templateId);
 		if (cached !== void 0) return cached;
 		const rid = await this.pl.withReadTx("ResolveTemplateId", async (tx) => {
-			const data = await tx.getResourceData(this.templateListResourceId, true);
-			for (const f of data.fields) {
-				if (isNullSignedResourceId(f.value)) continue;
-				if (resourceIdToString(f.value) === templateId) return f.value;
-			}
-			throw new Error(`Template ${templateId} not found in template list.`);
+			const entry = (await listedById(tx, this.templateListResourceId)).get(templateId);
+			if (entry === void 0) throw notListedError("Template", templateId);
+			return entry.rid;
 		});
 		this.templateIdCache.set(templateId, rid);
 		return rid;
@@ -499,43 +766,50 @@ var MiddleLayer = class MiddleLayer {
 	* destruction of all attached objects, like files, analysis results etc. */
 	async deleteProject(id) {
 		await this.pl.withWriteTx("MLRemoveProject", async (tx) => {
-			const data = await tx.getResourceData(this.projectListResourceId, true);
-			let fieldName;
-			for (const f of data.fields) {
-				if (isNullSignedResourceId(f.value)) continue;
-				if (resourceIdToString(f.value) === id) {
-					fieldName = f.name;
-					break;
-				}
-			}
-			if (fieldName === void 0) throw new Error(`Project ${id} not found in project list.`);
-			tx.removeField(field(this.projectListResourceId, fieldName));
+			const entry = (await listedById(tx, this.projectListResourceId)).get(id);
+			if (entry === void 0) throw notListedError("Project", id);
+			tx.removeField(field(this.projectListResourceId, entry.fieldName));
 			await tx.commit();
 		});
 		this.projectIdCache.delete(id);
 		await this.projectListTree.refreshState();
 	}
 	/**
-	* Duplicates an existing project and adds the copy to this user's project list.
+	* Duplicates an existing project and adds the copy to this user's project list, beside the
+	* project it was copied from.
+	*
+	* Without `rename` the copy is named by the rule everything beside the source is named by: the
+	* source's own label, suffixed to be free there — `X (Copy)`. The name is chosen inside the
+	* transaction that creates the copy, against the tree that transaction reads.
 	*
 	* @param srcProjectId - project id of the project to duplicate
 	* @param rename - optional function that receives the source label and all existing
-	*   project labels (read within the same transaction), and returns the label for the copy
+	*   project labels (read within the same transaction), and returns the label for the copy.
+	*   A label chosen this way is the caller's and is never suffixed: when it is already taken
+	*   beside the source, the copy lands at the top level instead.
 	*/
 	async duplicateProject(srcProjectId, rename) {
 		const sourceRid = await this.resolveProjectId(srcProjectId);
 		const newPrj = await this.pl.withWriteTx("MLDuplicateProject", async (tx) => {
 			const sourceMeta = await tx.getKValueJson(sourceRid, ProjectMetaKey);
-			const projectRids = (await tx.getResourceData(this.projectListResourceId, true)).fields.map((f) => f.value).filter(isNotNullSignedResourceId);
-			const existingLabels = (await Promise.all(projectRids.map((rid) => tx.getKValueJson(rid, ProjectMetaKey)))).map((m) => m.label);
-			const newPrj = await duplicateProject(tx, sourceRid, { label: rename ? rename(sourceMeta.label, existingLabels) : sourceMeta.label }, this.env.projectHelper);
+			const tree = await openFoldersTx(tx, this.foldersRids);
+			const label = rename === void 0 ? foldersUniqueName(sourceMeta.label, [sourceMeta.label, ...tree.namesTakenBeside(srcProjectId)]) : rename(sourceMeta.label, await existingProjectLabels(tx, this.projectListResourceId));
+			const newPrj = await duplicateProject(tx, sourceRid, {
+				...sourceMeta,
+				label
+			}, this.env.projectHelper);
 			tx.createField(field(this.projectListResourceId, randomUUID()), "Dynamic", newPrj);
+			const created = {
+				kind: "project",
+				id: asProjectId(resourceIdToString(await newPrj.globalId))
+			};
+			tree.place([created], rename === void 0 ? tree.folderOf(srcProjectId) : inheritedFolder(tree.view, srcProjectId, created, label));
 			await tx.commit();
 			return newPrj;
 		});
-		await this.projectListTree.refreshState();
+		await Promise.all([this.projectListTree.refreshState(), this.foldersTree.refreshState()]);
 		const signedRid = await newPrj.globalId;
-		const newProjectId = resourceIdToString(signedRid);
+		const newProjectId = asProjectId(resourceIdToString(signedRid));
 		this.projectIdCache.set(newProjectId, signedRid);
 		return newProjectId;
 	}
@@ -543,7 +817,7 @@ var MiddleLayer = class MiddleLayer {
 	* Duplicates a project into another user's root, minted in the TARGET user's color so the target
 	* owns it. Sibling of {@link duplicateProject}, but writes into a different root. The source
 	* project (on the current client root) is referenced cross-color for its block data, kept alive
-	* by refcounting, exactly like accepting a shared project. Works both ways: pull (while
+	* by refcounting, exactly like a project copied out of a share. Works both ways: pull (while
 	* impersonating a user, copy their project to yourself) and push (from your own root, copy a
 	* project to a user). Admin cross-root op; requires the crossTreeRefs:v1 backend capability.
 	*/
@@ -557,100 +831,36 @@ var MiddleLayer = class MiddleLayer {
 		await this.pl.withWriteTxOnRoot(targetRoot, "MLDuplicateProjectToUser", async (tx) => {
 			const targetProjectListRid = await ensureProjectListRid(tx);
 			const sourceMeta = await tx.getKValueJson(sourceRid, ProjectMetaKey);
-			const targetListData = await tx.getResourceData(targetProjectListRid, true);
-			const existingLabels = (await Promise.all(targetListData.fields.map((f) => f.value).filter(isNotNullSignedResourceId).map((rid) => tx.getKValueJson(rid, ProjectMetaKey)))).map((m) => m.label);
-			const newPrj = await duplicateProject(tx, sourceRid, { label: rename ? rename(sourceMeta.label, existingLabels) : sourceMeta.label }, this.env.projectHelper);
+			const existingLabels = await existingProjectLabels(tx, targetProjectListRid);
+			const newLabel = rename ? rename(sourceMeta.label, existingLabels) : sourceMeta.label;
+			const newPrj = await duplicateProject(tx, sourceRid, {
+				...sourceMeta,
+				label: newLabel
+			}, this.env.projectHelper);
 			tx.createField(field(targetProjectListRid, randomUUID()), "Dynamic", newPrj);
 			await tx.commit();
 		});
 	}
 	/**
-	* Shares the given projects (Copy & Share). Snapshots the projects, creates one envelope, and
-	* grants it — all in one atomic write transaction, so a failed grant rolls the whole thing back
-	* and the outbox is left as it was.
-	*
-	* Two variants (see {@link ShareProjectsOptions}):
-	* - `{ recipients }` — one writable grant per named recipient; the envelope expires after the
-	*   default TTL (`sharedAt + envelopeTtlMs`).
-	* - `{ everyone: true }` — one make-public grant (backend rewrites the target to the
-	*   everyone-user); the envelope's `expiresAt` is `null`, so it never expires.
+	* Shares the given projects (Copy & Share): snapshots them into one envelope, in the transaction
+	* {@link shareEnvelope} describes.
 	*
 	* v1 always passes `mode: "copy"`.
 	*/
 	async shareProjects(projectIds, options) {
 		if (projectIds.length === 0) throw new Error("shareProjects: no projects given");
-		if ("everyone" in options && options.replace) {
-			const priorEveryone = (await this.findSupersedableEnvelopes(projectIds)).find((p) => p.everyone);
-			if (priorEveryone !== void 0) {
-				await this.changeShare(priorEveryone.shareId, { title: options.title });
-				return;
-			}
-		}
-		await this.createNewShare(projectIds, options);
-	}
-	/**
-	* Mints a fresh share: snapshots the projects into one new envelope (a fresh shareId),
-	* supersedes prior shares of the same project, and grants it — all in one atomic write
-	* transaction, so a failed grant rolls the whole thing back and the outbox is left as it was.
-	* The everyone-refresh path is the {@link changeShare} branch of {@link shareProjects}; this is
-	* the mint-a-new-envelope branch.
-	*/
-	async createNewShare(projectIds, options) {
-		const everyone = "everyone" in options;
 		const sources = await Promise.all(projectIds.map(async (id) => ({
-			kind: "fresh",
 			projectId: id,
 			sourceRid: await this.resolveProjectId(id)
 		})));
-		const sender = this.currentUserLogin ?? "";
-		const expiresAt = everyone ? null : Date.now() + this.env.ops.envelopeTtlMs;
-		const priors = await this.findSupersedableEnvelopes(projectIds);
-		await this.pl.withWriteTx("MLShareProjects", async (tx) => {
-			if (everyone) {
-				for (const prior of priors) if (prior.everyone) tx.removeField(field(this.sharingOutboxResourceId, prior.fieldName));
-			} else {
-				const newRecipients = new Set(options.recipients);
-				for (const prior of priors) {
-					if (prior.everyone) continue;
-					const toRemove = prior.recipients.filter((u) => newRecipients.has(u));
-					if (toRemove.length === 0) continue;
-					if (prior.recipients.filter((u) => !newRecipients.has(u)).length === 0) tx.removeField(field(this.sharingOutboxResourceId, prior.fieldName));
-					else for (const u of toRemove) tx.revokeAccess(prior.rid, u);
-				}
-			}
-			const { envelope } = await buildShareEnvelope(tx, this.sharingOutboxResourceId, sources, {
-				mode: options.mode,
-				sender,
-				title: options.title,
-				expiresAt
-			});
-			await this.grantShareEnvelope(tx, envelope, everyone, everyone ? [] : options.recipients, { writable: true });
-			await tx.commit();
-		});
-		await this.sharingOutboxTree.refreshState();
-	}
-	/**
-	* Grants one freshly built envelope inside the transaction that created it: a single make-public
-	* grant for an everyone-share (empty/ignored target, ANY_AUTHORISED — the backend rewrites the
-	* target to the everyone-user, gated by role + permission ceiling), or one grant per named
-	* recipient.
-	*
-	* `writable` is not a preference. A project pack needs a writable grant because accepting copies
-	* the snapshots out of the envelope, and the cross-color attach rule permits that only to a
-	* writable grant holder. A template share copies nothing — the document sits in the envelope's
-	* own immutable data — so it is granted read-only, and must be: a writable everyone-grant would
-	* hand every user on the server write access to the envelope.
-	*/
-	async grantShareEnvelope(tx, envelope, everyone, recipients, permissions) {
-		const gid = await envelope.globalId;
-		if (everyone) tx.grantAccess(gid, "", permissions, GrantType.ANY_AUTHORISED);
-		else for (const r of recipients) tx.grantAccess(gid, r, permissions);
+		return await this.shareEnvelope("MLShareProjects", options, { writable: true }, (tx, meta) => buildShareEnvelope(tx, this.sharingOutboxResourceId, sources, {
+			mode: options.mode,
+			...meta
+		}));
 	}
 	/**
 	* Shares one stored template. The envelope carries the document itself, so there is no project
 	* snapshot and no resource for the recipient to copy out — which is why the grant is read-only.
-	* The cost of that is the donor's receipt: nobody can write an acceptance onto a read-only
-	* envelope, so a template share never reports who accepted it.
 	*
 	* Nothing about the document is checked: a stored template is shareable by virtue of existing.
 	* An entry the recipient cannot resolve — a block installed from a folder on the sender's
@@ -661,187 +871,110 @@ var MiddleLayer = class MiddleLayer {
 	* @param options recipients XOR everyone, plus the title recipients see
 	*/
 	async shareTemplate(id, options) {
-		const template = await this.loadTemplateForShare(id);
-		const everyone = "everyone" in options;
-		const sender = this.currentUserLogin ?? "";
-		const expiresAt = everyone ? null : Date.now() + this.env.ops.envelopeTtlMs;
-		let shareId;
-		await this.pl.withWriteTx("MLShareTemplate", async (tx) => {
-			const { envelope, data } = buildTemplateShareEnvelope(tx, this.sharingOutboxResourceId, template, {
-				sender,
-				title: options.title,
-				expiresAt
-			});
-			shareId = data.shareId;
-			await this.grantShareEnvelope(tx, envelope, everyone, everyone ? [] : options.recipients, { writable: false });
-			await tx.commit();
-		});
-		await this.sharingOutboxTree.refreshState();
-		return { shareId };
-	}
-	/** The document and the label of a template about to be shared. The label is what the
-	*  recipient's own list will show, so it travels with the document. */
-	async loadTemplateForShare(id) {
 		const rid = await this.resolveTemplateId(id);
-		return await this.pl.withReadTx("MLReadTemplateForShare", async (tx) => {
-			const rd = await tx.getResourceData(rid, false);
-			if (rd.data === void 0) throw new Error(`Template ${id} carries no document.`);
-			return {
-				document: decodeStoredTemplateData(rd.data).document,
-				label: await tx.getKValueJson(rid, TemplateLabelKey)
-			};
-		});
+		const stored = await this.pl.withReadTx("MLReadStoredTemplate", (tx) => readStoredTemplate(tx, id, rid));
+		return await this.shareEnvelope("MLShareTemplate", options, { writable: false }, (tx, meta) => buildTemplateShareEnvelope(tx, this.sharingOutboxResourceId, {
+			document: stored.data.document,
+			label: stored.label,
+			...stored.description === void 0 ? {} : { description: stored.description },
+			source: id
+		}, meta));
 	}
 	/**
-	* Changes a share in place (same {@link ShareId}), in one write transaction: re-snapshots live
-	* source projects and carries deleted ones' snapshots forward; applies edited recipients/title;
-	* transfers already-decided recipients' accept/reject records (they keep their copy and aren't
-	* re-prompted); re-grants; drops the old envelope.
+	* Shares one folder and everything under it: the subtree's folders, every project in them
+	* snapshotted, and every template carried whole.
 	*
-	* `opts.recipients` is the full targeted set (decided users are always kept). `opts.title`
-	* replaces the title — omit keeps the current one. `opts.everyone` upgrades targeted ->
-	* everyone; the reverse is impossible and ignored.
+	* The grant is writable, because a folder holding projects is copied out of the envelope the
+	* way a project pack is. An everyone-share of a folder therefore hands every user on the server
+	* write access to the envelope — the same trade a project share already makes.
 	*
-	* `opts.projectActions` is a per-source-project decision, keyed by projectId: `update`
-	* re-snapshots the live source (falls back to carry if the source is gone), `keep` carries the
-	* existing snapshot (and its timestamp), `remove` drops the project from the pack. A project not
-	* in the map defaults to `keep`. Omit the whole map for the legacy auto behavior (live sources
-	* updated, gone ones kept) — the everyone-refresh path relies on that.
+	* Folder ids do not travel. What the recipient gets is the shape of the subtree, rebuilt under
+	* a folder of their own choosing with ids their own document mints.
 	*
-	* `opts.templateId` is required for, and only used by, a share that carries a template: a stored
-	* template is immutable, so an improved one is a different template and the share cannot re-read
-	* the one it started from — the caller names the new target. Every other option means the same
-	* thing for both kinds of share.
+	* @param folder folder to share; everything beneath it goes with it
+	* @param options recipients XOR everyone, plus the title recipients see
 	*/
-	async changeShare(shareId, opts = {}) {
-		const target = opts.templateId === void 0 ? void 0 : await this.loadTemplateForShare(opts.templateId);
-		await this.pl.withWriteTx("MLChangeShare", async (tx) => {
-			const old = await this.resolveOutboxEnvelope(tx, shareId);
-			if (old === void 0) throw new Error(`changeShare: no live share with id ${shareId} in the outbox.`);
-			const self = this.currentUserLogin ?? "";
-			const grants = await tx.listGrants(old.rid);
-			const everyone = grants.some((g) => isEveryoneUserLogin(g.user)) || opts.everyone === true;
-			const priorRecipients = grants.filter((g) => !isEveryoneUserLogin(g.user) && g.user !== self).map((g) => g.user);
-			if (old.data.payload.kind === "template") {
-				if (target === void 0) throw new Error(`changeShare: share ${shareId} carries a template, so it needs an explicit target template — a stored template never changes, so an improved one is a different template.`);
-				const recipients = everyone ? [] : opts.recipients ?? priorRecipients;
-				tx.removeField(field(this.sharingOutboxResourceId, old.fieldName));
-				const { envelope } = buildTemplateShareEnvelope(tx, this.sharingOutboxResourceId, target, {
-					sender: self,
-					title: opts.title === void 0 ? old.data.title : opts.title.trim(),
-					expiresAt: everyone ? null : Date.now() + this.env.ops.envelopeTtlMs,
-					shareId
-				});
-				await this.grantShareEnvelope(tx, envelope, everyone, recipients, { writable: false });
-				await tx.commit();
-				return;
-			}
-			const oldRd = await tx.getResourceData(old.rid, true);
-			const snapshotByUuid = /* @__PURE__ */ new Map();
-			const acceptances = [];
-			for (const f of oldRd.fields) {
-				if (isNullSignedResourceId(f.value)) continue;
-				if (isEnvelopeProjectField(f.name)) snapshotByUuid.set(envelopeProjectFieldUuid(f.name), f.value);
-				else if (isAcceptanceField(f.name)) {
-					const raw = (await tx.getResourceData(f.value, false)).data;
-					if (raw === void 0) continue;
-					acceptances.push({
-						login: acceptanceFieldLogin(f.name),
-						acc: cachedDeserialize(raw)
-					});
-				}
-			}
-			const decidedLogins = acceptances.map((a) => a.login);
-			const recipients = everyone ? [] : Array.from(/* @__PURE__ */ new Set([...opts.recipients ?? priorRecipients, ...decidedLogins]));
-			const liveProjects = /* @__PURE__ */ new Map();
-			const projList = await tx.getResourceData(this.projectListResourceId, true);
-			for (const f of projList.fields) {
-				if (isNullSignedResourceId(f.value)) continue;
-				liveProjects.set(resourceIdToString(f.value), f.value);
-			}
-			const actions = opts.projectActions;
-			const sources = [];
-			const oldProjects = envelopeProjectMap(old.data);
-			for (const uuid of Object.keys(oldProjects)) {
-				const { label, source, updatedAt } = oldProjects[uuid];
-				const liveRid = liveProjects.get(source);
-				const action = actions ? actions[source] ?? "keep" : liveRid !== void 0 ? "update" : "keep";
-				if (action === "remove") continue;
-				if (action === "update" && liveRid !== void 0) sources.push({
-					kind: "fresh",
-					projectId: source,
-					sourceRid: liveRid
-				});
-				else {
-					const snapshotRid = snapshotByUuid.get(uuid);
-					if (snapshotRid !== void 0) sources.push({
-						kind: "carry",
-						projectId: source,
-						label,
-						snapshotRid,
-						updatedAt
-					});
-				}
-			}
-			const title = opts.title === void 0 ? old.data.title : opts.title.trim();
-			const expiresAt = everyone ? null : Date.now() + this.env.ops.envelopeTtlMs;
-			tx.removeField(field(this.sharingOutboxResourceId, old.fieldName));
-			const { envelope } = await buildShareEnvelope(tx, this.sharingOutboxResourceId, sources, {
-				mode: old.data.mode,
-				sender: self,
-				title,
-				expiresAt,
-				shareId
-			});
-			for (const { login, acc } of acceptances) {
-				if (!everyone && !recipients.includes(login)) continue;
-				writeEnvelopeAcceptance(tx, envelope, login, acc.action, acc.timestamp);
-			}
-			await this.grantShareEnvelope(tx, envelope, everyone, recipients, { writable: true });
+	async shareFolder(folder, options) {
+		const loaded = await this.loadFolderSubtree(folder, newEnvelopeFolderId);
+		const subtree = {
+			source: folder,
+			folders: loaded.folders,
+			projects: loaded.projects.map((project) => ({
+				projectId: project.projectId,
+				sourceRid: project.rid,
+				folder: project.folder
+			})),
+			templates: loaded.templates.map((template) => ({
+				document: template.data.document,
+				label: template.label,
+				...template.description === void 0 ? {} : { description: template.description },
+				folder: template.folder
+			}))
+		};
+		return await this.shareEnvelope("MLShareFolder", options, { writable: true }, (tx, meta) => buildFolderShareEnvelope(tx, this.sharingOutboxResourceId, subtree, meta));
+	}
+	/**
+	* The one transaction every share is made in: the shares named by `options.replace` are
+	* dropped, the envelope `build` makes is created, and it is granted — all at once, so a failed
+	* grant rolls the whole thing back and the outbox is left as it was.
+	*
+	* A share with named recipients grants each of them and expires after the default TTL
+	* (`sharedAt + envelopeTtlMs`). A share with everyone is one make-public grant, and its
+	* `expiresAt` is `null`, so it never expires.
+	*/
+	async shareEnvelope(txName, options, permissions, build) {
+		const everyone = "everyone" in options;
+		const meta = {
+			sender: this.currentUserLogin ?? "",
+			title: options.title,
+			expiresAt: everyone ? null : Date.now() + this.env.ops.envelopeTtlMs
+		};
+		const outcome = await this.pl.withWriteTx(txName, async (tx) => {
+			await this.dropShares(tx, options.replace);
+			const { envelope, data } = await build(tx, meta);
+			await this.grantShareEnvelope(tx, envelope, everyone, everyone ? [] : options.recipients, permissions);
 			await tx.commit();
+			return { shareId: data.shareId };
 		});
 		await this.sharingOutboxTree.refreshState();
+		return outcome;
 	}
 	/**
-	* Finds the donor's own outgoing envelopes built from any of the given source projects —
-	* the supersede candidates for a fresh share of the same project(s). Reads each envelope's
-	* recipient set via `ListGrants` so the caller can pull individual recipients or detect an
-	* everyone-share.
+	* Detaches the named shares from the donor's outbox inside the caller's transaction, so a
+	* replacement and the shares it supersedes land together or not at all.
+	*
+	* A share that no longer resolves is skipped rather than reported: the caller names shares the
+	* author saw a moment ago, and one revoked meanwhile is already in the wanted state.
 	*/
-	async findSupersedableEnvelopes(projectIds) {
-		const wanted = new Set(projectIds);
-		const matched = await this.pl.withReadTx("MLFindSupersede", async (tx) => {
-			const outbox = await tx.getResourceData(this.sharingOutboxResourceId, true);
-			const out = [];
-			for (const f of outbox.fields) {
-				if (isNullSignedResourceId(f.value)) continue;
-				const rd = await tx.getResourceData(f.value, false);
-				if (rd.data === void 0) continue;
-				const data = decodeEnvelopeData(rd.data);
-				if (data === void 0) continue;
-				if (Object.values(envelopeProjectMap(data)).some((p) => wanted.has(p.source))) out.push({
-					fieldName: f.name,
-					rid: f.value,
-					shareId: data.shareId
-				});
-			}
-			return out;
-		});
-		return await Promise.all(matched.map(async ({ fieldName, rid, shareId }) => {
-			const grants = await this.pl.userResources.listGrants(rid);
-			return {
-				fieldName,
-				rid,
-				shareId,
-				everyone: grants.some((g) => isEveryoneUserLogin(g.user)),
-				recipients: grants.filter((g) => !isEveryoneUserLogin(g.user)).map((g) => g.user)
-			};
-		}));
+	async dropShares(tx, shareIds) {
+		for (const shareId of shareIds ?? []) {
+			const target = await this.resolveOutboxEnvelope(tx, shareId);
+			if (target === void 0) continue;
+			tx.removeField(field(this.sharingOutboxResourceId, target.fieldName));
+		}
+	}
+	/**
+	* Grants one freshly built envelope inside the transaction that created it: a single make-public
+	* grant for an everyone-share (empty/ignored target, ANY_AUTHORISED — the backend rewrites the
+	* target to the everyone-user, gated by role + permission ceiling), or one grant per named
+	* recipient.
+	*
+	* `writable` is not a preference. A project pack needs a writable grant because a copy out of
+	* it takes the snapshots out of the envelope, and the cross-color attach rule permits that only
+	* to a writable grant holder. A template share copies nothing — the document sits in the
+	* envelope's own immutable data — so it is granted read-only, and must be: a writable
+	* everyone-grant would hand every user on the server write access to the envelope.
+	*/
+	async grantShareEnvelope(tx, envelope, everyone, recipients, permissions) {
+		const gid = await envelope.globalId;
+		if (everyone) tx.grantAccess(gid, "", permissions, GrantType.ANY_AUTHORISED);
+		else for (const r of recipients) tx.grantAccess(gid, r, permissions);
 	}
 	/**
 	* Revokes and deletes an outgoing share for all recipients: detaches and deletes the envelope, and
-	* its grants are revoked along with it. Already-accepted copies are unaffected (ref-counting keeps
-	* the adopted resources alive). Idempotent — revoking a share that is already gone is a no-op.
+	* its grants are revoked along with it. Copies recipients already took out of it are unaffected
+	* (ref-counting keeps the resources they point at alive). Idempotent — revoking a share that is
+	* already gone is a no-op.
 	*/
 	async revokeShare(shareId) {
 		await this.pl.withWriteTx("MLRevokeShare", async (tx) => {
@@ -878,36 +1011,37 @@ var MiddleLayer = class MiddleLayer {
 	* the envelope's logical `shareId`.
 	*
 	* Reads the {@link liveEnvelopes} Computable — the same shared-resource discovery tree that
-	* feeds {@link pendingShares}. This is the single discovery mechanism: there is no separate
-	* `ListUserResources` re-stream on every accept/reject. `refreshState()` is awaited first so a
+	* feeds {@link availableShares}. This is the single discovery mechanism: there is no separate
+	* `ListUserResources` re-stream on every copy. `refreshState()` is awaited first so a
 	* just-granted envelope is observed (the tree's discovery poll may otherwise lag a freshly
 	* landed grant). The tree is gRPC-only, so this is empty on a REST-connected client.
 	*/
 	async resolveLiveEnvelopes() {
-		await this.pendingSharesTree.refreshState();
+		await this.availableSharesTree.refreshState();
 		const live = await this.liveEnvelopes.getValue() ?? [];
 		const map = /* @__PURE__ */ new Map();
 		for (const e of live) map.set(e.data.shareId, e);
 		return map;
 	}
 	/**
-	* Accepts one or more pending shares. What accepting does depends on what the share carries: a
-	* pack of projects is duplicated into this user's project list, while a template is added to this
-	* user's own template list and builds nothing — the recipient decides later whether to apply it.
-	* Either way the decision is recorded per share, and a read-write share also gets the
-	* donor-visible acceptance written onto its envelope. Per-share failures (e.g. an expiry race)
-	* are collected, not short-circuited — the rest still get accepted. Accept-all = pass every
-	* current pending shareId.
+	* Copies what one or more shares carry into this user's own tree, optionally into a folder.
 	*
-	* `rename` resolves label collisions (same callback contract as {@link duplicateProject}), but
-	* the source lives in the envelope tree, so accept calls the low-level mutator directly. It does
-	* not apply to a template share, whose label is not required to be unique.
+	* A share is a shelf, not an invitation: copying takes nothing off it and records no decision,
+	* so the same share can be copied from again, by this user or anyone else it was granted to.
+	* What a copy produces depends on the payload — a pack of projects lands in the project list,
+	* a template among their templates, building nothing until the recipient applies it, and a
+	* folder is rebuilt whole with everything it held.
+	*
+	* Names are chosen against the destination folder, since that is where the uniqueness rule
+	* applies, and a project and a template follow the same rule. A destination deleted meanwhile
+	* fails the copy rather than spilling it at the top level.
+	* Per-share failures (a revoked envelope, say) are collected rather than short-circuited, so
+	* one dead share does not cost the others.
 	*/
-	async acceptShare(shareIds, rename) {
+	async copyShare(shareIds, destination) {
 		const live = await this.resolveLiveEnvelopes();
-		const login = this.currentUserLogin;
-		const accepted = [];
-		const acceptedTemplates = [];
+		const projects = [];
+		const templates = [];
 		const failed = [];
 		for (const shareId of shareIds) {
 			const envelope = live.get(shareId);
@@ -919,45 +1053,100 @@ var MiddleLayer = class MiddleLayer {
 				continue;
 			}
 			try {
-				const now = Date.now();
 				const payload = envelope.data.payload;
 				if (payload.kind === "template") {
-					const rid = await this.pl.withWriteTx("MLAcceptTemplateShare", async (tx) => {
-						const tpl = createTemplate(tx, this.templateListResourceId, payload.label, {
+					const rid = await this.pl.withWriteTx("MLCopyTemplateShare", async (tx) => {
+						const tree = await openFoldersTx(tx, this.foldersRids);
+						const created = await createTemplate(tx, this.templateListResourceId, {
+							label: foldersUniqueName(payload.label, tree.namesTakenIn(destination)),
+							description: payload.description
+						}, {
 							schemaVersion: 1,
 							document: payload.document,
 							sender: payload.from
-						});
-						writeSharingDecision(tx, this.sharingStateResourceId, shareId, {
-							decision: "accepted",
-							timestamp: now,
-							envelopeSharedAt: envelope.data.sharedAt,
-							acceptedProjects: []
-						});
+						}).globalId;
+						tree.place([{
+							kind: "template",
+							id: asTemplateId(resourceIdToString(created))
+						}], destination);
 						await tx.commit();
-						return await tpl.globalId;
+						return created;
 					});
-					const templateId = resourceIdToString(rid);
+					const templateId = asTemplateId(resourceIdToString(rid));
 					this.templateIdCache.set(templateId, rid);
-					acceptedTemplates.push(templateId);
+					templates.push(templateId);
 					continue;
 				}
-				const createdRids = await this.pl.withWriteTx("MLAcceptShare", async (tx) => {
-					const created = await copyEnvelopeProjectsIntoList(tx, envelope.rid, this.projectListResourceId, rename);
-					writeSharingDecision(tx, this.sharingStateResourceId, shareId, {
-						decision: "accepted",
-						timestamp: now,
-						envelopeSharedAt: envelope.data.sharedAt,
-						acceptedProjects: resourceIdsToStrings(created)
+				if (payload.kind === "folder") {
+					const root = envelopeFolderRoot(payload.folders);
+					if (root === void 0) throw new Error("This share does not describe one folder, so nothing can be rebuilt.");
+					const copied = await this.pl.withWriteTx("MLCopyFolderShare", async (tx) => {
+						const tree = await openFoldersTx(tx, this.foldersRids);
+						const created = await copyEnvelopeProjectsIntoList(tx, envelope.rid, this.projectListResourceId);
+						const createdTemplates = [];
+						const items = [];
+						for (const { uuid, rid } of created) {
+							const inFolder = payload.projects[uuid];
+							items.push({
+								kind: "project",
+								id: asProjectId(resourceIdToString(rid)),
+								folder: inFolder?.folder ?? root
+							});
+						}
+						for (const carried of payload.templates) {
+							const id = asTemplateId(resourceIdToString(await createTemplate(tx, this.templateListResourceId, {
+								label: carried.label,
+								description: carried.description
+							}, {
+								schemaVersion: 1,
+								document: carried.document,
+								sender: payload.from
+							}).globalId));
+							createdTemplates.push(id);
+							items.push({
+								kind: "template",
+								id,
+								folder: carried.folder
+							});
+						}
+						tree.graft({
+							root,
+							folders: payload.folders,
+							items
+						}, destination);
+						await tx.commit();
+						return {
+							projects: created,
+							templates: createdTemplates
+						};
 					});
-					if (login !== null && envelope.data.mode !== "read-only") writeEnvelopeAcceptance(tx, envelope.rid, login, "accepted", now);
+					for (const { rid } of copied.projects) {
+						const projectId = asProjectId(resourceIdToString(rid));
+						this.projectIdCache.set(projectId, rid);
+						projects.push(projectId);
+					}
+					templates.push(...copied.templates);
+					continue;
+				}
+				const createdRids = await this.pl.withWriteTx("MLCopyShare", async (tx) => {
+					const tree = await openFoldersTx(tx, this.foldersRids);
+					const taken = [...tree.namesTakenIn(destination)];
+					const created = await copyEnvelopeProjectsIntoList(tx, envelope.rid, this.projectListResourceId, (sourceLabel) => {
+						const name = foldersUniqueName(sourceLabel, taken);
+						taken.push(name);
+						return name;
+					});
+					tree.place(created.map(({ rid }) => ({
+						kind: "project",
+						id: asProjectId(resourceIdToString(rid))
+					})), destination);
 					await tx.commit();
 					return created;
 				});
-				for (const rid of createdRids) {
-					const projectId = resourceIdToString(rid);
+				for (const { rid } of createdRids) {
+					const projectId = asProjectId(resourceIdToString(rid));
 					this.projectIdCache.set(projectId, rid);
-					accepted.push(projectId);
+					projects.push(projectId);
 				}
 			} catch (e) {
 				failed.push({
@@ -969,27 +1158,31 @@ var MiddleLayer = class MiddleLayer {
 		await Promise.all([
 			this.projectListTree.refreshState(),
 			this.templateListTree.refreshState(),
-			this.sharingStateTree.refreshState()
+			this.foldersTree.refreshState()
 		]);
 		return {
-			accepted,
-			acceptedTemplates,
+			projects,
+			templates,
 			failed
 		};
 	}
-	/** Records rejection of a pending share; it never surfaces again. */
-	async rejectShare(shareId) {
-		const envelope = (await this.resolveLiveEnvelopes()).get(shareId);
-		const login = this.currentUserLogin;
+	/**
+	* Puts a share out of this user's sight. Private to them and reversible with
+	* {@link unhideShare}: nothing is deleted, the donor is not told, and what was already copied
+	* out of it is unaffected.
+	*/
+	async hideShare(shareId) {
 		const now = Date.now();
-		await this.pl.withWriteTx("MLRejectShare", async (tx) => {
-			writeSharingDecision(tx, this.sharingStateResourceId, shareId, {
-				decision: "rejected",
-				timestamp: now,
-				envelopeSharedAt: envelope?.data.sharedAt ?? now,
-				acceptedProjects: []
-			});
-			if (envelope !== void 0 && login !== null && envelope.data.mode !== "read-only") writeEnvelopeAcceptance(tx, envelope.rid, login, "rejected", now);
+		await this.pl.withWriteTx("MLHideShare", async (tx) => {
+			writeShareHidden(tx, this.sharingStateResourceId, shareId, now);
+			await tx.commit();
+		});
+		await this.sharingStateTree.refreshState();
+	}
+	/** Brings a hidden share back into this user's list. */
+	async unhideShare(shareId) {
+		await this.pl.withWriteTx("MLUnhideShare", async (tx) => {
+			clearShareHidden(tx, this.sharingStateResourceId, shareId);
 			await tx.commit();
 		});
 		await this.sharingStateTree.refreshState();
@@ -1103,9 +1296,10 @@ var MiddleLayer = class MiddleLayer {
 		await Promise.all([
 			this.projectListTree.terminate(),
 			this.templateListTree.terminate(),
+			this.foldersTree.terminate(),
 			this.sharingOutboxTree.terminate(),
 			this.sharingStateTree.terminate(),
-			this.pendingSharesTree.terminate()
+			this.availableSharesTree.terminate()
 		]);
 		await this.drainSnapshotWrites(SNAPSHOT_DRAIN_TIMEOUT_MS);
 		await this.env.dispose();
@@ -1134,7 +1328,7 @@ var MiddleLayer = class MiddleLayer {
 		ops.defaultTreeOptions.logStat = getDebugFlags().logTreeStats;
 		ops.debugOps.dumpInitialTreeState = getDebugFlags().dumpInitialTreeState;
 		if (ops.defaultTreeOptions.traversalMode === void 0 && getDebugFlags().treeTraversalMode !== void 0) ops.defaultTreeOptions.traversalMode = getDebugFlags().treeTraversalMode;
-		const { projects, templates, sharingOutbox, sharingState } = await pl.withWriteTx("MLInitialization", async (tx) => {
+		const { projects, templates, sharingOutbox, sharingState, folders } = await pl.withWriteTx("MLInitialization", async (tx) => {
 			const lazyInit = async (fieldName, type) => {
 				const f = field(tx.clientRoot, fieldName);
 				tx.createField(f, "Dynamic");
@@ -1151,12 +1345,15 @@ var MiddleLayer = class MiddleLayer {
 			const templatesR = await lazyInit(TemplatesField, TemplatesResourceType);
 			const outboxR = await lazyInit(SharingOutboxField, SharingOutboxResourceType);
 			const stateR = await lazyInit(SharingStateField, SharingStateResourceType);
+			const foldersR = await lazyInit(FoldersField, FoldersResourceType);
 			await tx.commit();
+			const idOf = async (r) => "existing" in r ? r.existing : await r.ref.globalId;
 			return {
-				projects: projectsR.existing ?? await projectsR.ref.globalId,
-				templates: templatesR.existing ?? await templatesR.ref.globalId,
-				sharingState: stateR.existing ?? await stateR.ref.globalId,
-				sharingOutbox: outboxR.existing ?? await outboxR.ref.globalId
+				projects: await idOf(projectsR),
+				templates: await idOf(templatesR),
+				sharingState: await idOf(stateR),
+				sharingOutbox: await idOf(outboxR),
+				folders: await idOf(foldersR)
 			};
 		});
 		const logger = ops.logger;
@@ -1210,14 +1407,32 @@ var MiddleLayer = class MiddleLayer {
 		const openedProjects = new WatchableValue([]);
 		const projectListTC = await createProjectList(pl, projects, openedProjects, env);
 		const templateListTC = await createTemplateList(pl, templates, env);
+		const foldersTC = await createFolderList(pl, folders, projectListTC.tree, templateListTC.tree, openedProjects, env);
 		const outgoingTC = await createOutgoingShares(pl, sharingOutbox, env);
 		const sharingStateTree = await createSharingStateTree(pl, sharingState, env);
-		const pendingSharesTree = await createPendingSharesTree(pl, env);
-		const pendingShares = createPendingSharesComputable(pendingSharesTree, sharingStateTree, pl.userResources.authUser);
-		const liveEnvelopes = createLiveEnvelopesComputable(pendingSharesTree);
-		return new MiddleLayer(env, driverKit, driverKit.signer, projects, templates, sharingOutbox, sharingState, openedProjects, projectListTC.tree, templateListTC.tree, outgoingTC.tree, sharingStateTree, pendingSharesTree, v2RegistryProvider, projectListTC.computable, templateListTC.computable, outgoingTC.computable, pendingShares, liveEnvelopes);
+		const availableSharesTree = await createAvailableSharesTree(pl, env);
+		const availableShares = createAvailableSharesComputable(availableSharesTree, sharingStateTree, pl.userResources.authUser);
+		const liveEnvelopes = createLiveEnvelopesComputable(availableSharesTree);
+		return new MiddleLayer(env, driverKit, driverKit.signer, projects, templates, sharingOutbox, sharingState, folders, openedProjects, projectListTC.tree, templateListTC.tree, foldersTC.tree, outgoingTC.tree, sharingStateTree, availableSharesTree, v2RegistryProvider, projectListTC.computable, templateListTC.computable, foldersTC.computable, outgoingTC.computable, availableShares, liveEnvelopes);
 	}
 };
+/** Reads one stored template within the caller's transaction. A share carries its document on;
+*  a duplicate carries the blob whole, so the copy says of itself what the original did. */
+async function readStoredTemplate(tx, id, rid) {
+	const rd = await tx.getResourceData(rid, false);
+	if (rd.data === void 0) throw new Error(`Template ${id} carries no document.`);
+	const [label, description] = await Promise.all([tx.getKValueJson(rid, TemplateLabelKey), tx.getKValueJsonIfExists(rid, TemplateDescriptionKey).then(normalizeDescription)]);
+	return {
+		data: decodeStoredTemplateData(rd.data),
+		label,
+		...description === void 0 ? {} : { description }
+	};
+}
+/** The label of every project in a project list, read within the caller's transaction. */
+async function existingProjectLabels(tx, listRid) {
+	const listed = await listedById(tx, listRid);
+	return (await Promise.all([...listed.values()].map(({ rid }) => tx.getKValueJson(rid, ProjectMetaKey)))).map((meta) => meta.label);
+}
 //#endregion
 export { MiddleLayer };