@thatopen/services 0.0.3 → 0.0.5

package/src/built-in/CDEManager/example.ts

@@ -0,0 +1,214 @@
+/* MD
+  ## CDEManager
+  ---
+  CDEManager is the central state machine for a Common Data Environment. It holds
+  files, folders, metadata schemas, viewer groups, and user permissions, and exposes a
+  typed state machine that all file operations — selecting, editing, uploading,
+  viewing — route through. It has no DOM or Three.js dependencies and can run in Node,
+  a browser, or a server-side worker wherever `@thatopen/components` is available.
+
+  This example shows how to initialize CDEManager, populate it with mock and live data,
+  subscribe to its events, navigate the state machine, and build file names from a
+  naming schema.
+
+  ### 🖖 Importing our libraries
+  First, install all necessary dependencies:
+*/
+
+// In production platform apps, CDEManager is loaded through the platform client:
+//   const cde = await client.initBuiltInComponent(CDEManager.uuid, components);
+// Here we import directly from source for local testing.
+import * as OBC from "@thatopen/components";
+import { CDEManager } from "./index";
+import type { CDEFile } from "./src/types";
+
+/* MD
+  ### 🚀 Initializing CDEManager
+  CDEManager is an `OBC.Component`, so you get it from the shared `components`
+  registry with `components.get(CDEManager)`. The constructor registers it
+  automatically — calling `get` a second time returns the same instance.
+*/
+
+const components = new OBC.Components();
+const cde = components.get(CDEManager);
+
+const output = document.getElementById("output") as HTMLPreElement;
+const log = (msg: string) => {
+  console.log(msg);
+  output.textContent += msg + "\n";
+};
+
+/* MD
+  ### 📋 Subscribing to events
+  All CDEManager events are `OBC.Event<T>` instances. Subscribe before setting data
+  so you capture the first trigger.
+*/
+
+cde.onFilesChanged.add((files) => {
+  log(`[event] onFilesChanged: ${files.length} file(s)`);
+});
+
+cde.onFoldersChanged.add((folders) => {
+  log(`[event] onFoldersChanged: ${folders.length} folder(s)`);
+});
+
+cde.onMachineStateChanged.add((state) => {
+  log(`[event] machineState → ${state.kind}`);
+});
+
+cde.onSelectedGroupChanged.add((group) => {
+  log(`[event] selectedGroup → ${group ?? "(none)"}`);
+});
+
+/* MD
+  ### 📂 Populating with mock data
+  Setting `cde.files` and `cde.folders` directly triggers `onFilesChanged` and
+  `onFoldersChanged`. This lets you build and test views without a live backend.
+*/
+
+const mockFolder = { _id: "folder-str", name: "Structural", parentId: null };
+cde.folders = [mockFolder];
+
+const now = new Date();
+const mockFiles: CDEFile[] = [
+  {
+    _id: "file-col", name: "column.ifc",
+    folderId: "folder-str", createdBy: "alice@example.com",
+    createdAt: now, metadata: { discipline: "STR", phase: "DD" },
+    itemType: "FILE",
+  } as CDEFile,
+  {
+    _id: "file-fnd", name: "foundations.ifc",
+    folderId: "folder-str", createdBy: "bob@example.com",
+    createdAt: now, metadata: { discipline: "STR", phase: "CD" },
+    itemType: "FILE",
+  } as CDEFile,
+  {
+    _id: "file-pdf", name: "report.pdf",
+    folderId: null, createdBy: "alice@example.com",
+    createdAt: now, metadata: {},
+    itemType: "FILE",
+  } as CDEFile,
+];
+cde.files = mockFiles;
+
+/* MD
+  ### 🔍 Filtering files: visibleFiles vs getSelectedFiles
+  `visibleFiles` excludes files whose folder was marked as a system folder by
+  `loadFolders` (folders whose names start with `__`). With mock data set directly,
+  no system folders are marked, so all files are always visible.
+
+  `getSelectedFiles` is the folder-scoped view used by the UI table. When
+  `selectedGroup` is `null` it returns root files only (no folderId); when set to a
+  folder id it returns files in that folder.
+*/
+
+log(`\nvisibleFiles (all, no system folders excluded): ${cde.visibleFiles.length}`);
+
+// getSelectedFiles respects selectedGroup, not visibleFiles.
+cde.selectedGroup = null;
+log(`getSelectedFiles (selectedGroup=null → root only): ${cde.getSelectedFiles().length}`);
+
+cde.selectedGroup = "folder-str";
+log(`getSelectedFiles (selectedGroup=folder-str): ${cde.getSelectedFiles().length}`);
+
+/* MD
+  ### 🎛️ State machine navigation
+  Every UI-level action goes through `sendMachineEvent`. The current state is readable
+  via `cde.machineState`. Events that aren't valid for the current state are silently
+  ignored — checking `machineState.kind` before sending prevents unexpected no-ops.
+
+  The `"selected"` state stores the selected files in `machineState.files`. This is
+  separate from `getSelectedFiles()`, which always returns the current folder view
+  regardless of machine state.
+*/
+
+log(`\nmachineState before SELECT: ${cde.machineState.kind}`);
+
+cde.sendMachineEvent({ type: "SELECT", files: [mockFiles[0], mockFiles[1]] });
+// machineState.files holds the selection — getSelectedFiles() returns the folder view.
+const sel = cde.machineState as { kind: string; files?: CDEFile[] };
+log(`machineState.files: ${sel.files?.length ?? 0} file(s) selected`);
+
+cde.sendMachineEvent({ type: "DESELECT" });
+log(`machineState after DESELECT: ${cde.machineState.kind}`);
+
+/* MD
+  ### 🏷️ Viewer groups and canView
+  `viewerGroups` declares which file extensions can be loaded side by side.
+  `multiple: true` allows multi-file loads; omitting it means only one file at a time.
+  `canView` checks whether a set of files belongs to one group and respects the flag.
+*/
+
+cde.viewerGroups = [
+  { extensions: ["ifc", "frag"], multiple: true },
+  { extensions: ["pdf"] },
+];
+
+const ifcFiles = mockFiles.filter(f => f.name.endsWith(".ifc"));
+log(`\ncanView([column.ifc, foundations.ifc]): ${cde.canView(ifcFiles)}`);
+log(`canView([report.pdf]): ${cde.canView([mockFiles[2]])}`);
+// Mixed types never share a viewer group, regardless of multiple.
+log(`canView([column.ifc, report.pdf]): ${cde.canView([mockFiles[0], mockFiles[2]])}`);
+
+/* MD
+  ### 📝 Naming schema
+  A naming schema assembles a computed file name from metadata fields. Segments define
+  the order and an optional transform; `separator` joins them. If a metadata key is
+  absent, `missingMetadataPlaceholder` is used so missing values stay visible.
+*/
+
+cde.missingMetadataPlaceholder = "XX";
+cde.setNamingSchema({
+  segments: [
+    { key: "discipline" },
+    { key: "phase" },
+  ],
+  separator: "-",
+});
+
+// column.ifc has both fields → "STR-DD"
+log(`\nbuildFileName(column.ifc): "${cde.buildFileName(mockFiles[0])}"`);
+// report.pdf has no metadata → "XX-XX"
+log(`buildFileName(report.pdf): "${cde.buildFileName(mockFiles[2])}"`);
+
+/* MD
+  ### 🌐 Live data (requires credentials)
+  The live section below connects to a real backend. Pass credentials as query
+  parameters when opening example.html:
+
+    example.html?accessToken=<token>&apiUrl=https://...&projectId=<id>
+
+  Without them, this section is skipped.
+
+  `loadFolders()` does more than just fetch folders — it also loads user permissions
+  and project members in the same call, then excludes any `__`-prefixed system
+  folders from `cde.folders`.
+*/
+
+const params = new URLSearchParams(location.search);
+const accessToken = params.get("accessToken");
+const apiUrl = params.get("apiUrl");
+const projectId = params.get("projectId");
+
+if (accessToken && apiUrl && projectId) {
+  const { EngineServicesClient } = await import("thatopen-services");
+  const client = new EngineServicesClient(accessToken, apiUrl);
+  cde.ctx = { client, projectId };
+
+  await cde.loadFolders();
+  log(`\nloadFolders: ${cde.folders.length} visible folder(s), project: "${cde.projectName}"`);
+  log(`userPermissions: ${JSON.stringify(cde.userPermissions)}`);
+
+  await cde.loadMetadataSchema();
+  log(`loadMetadataSchema: ${Object.keys(cde.metadataSchema).length} field(s) defined`);
+} else {
+  log("\nLive data skipped — pass ?accessToken=&apiUrl=&projectId= to run the full cycle.");
+}
+
+/* MD
+  ### 🎉 Wrap up
+  CDEManager handles state, events, filtering, and naming entirely in memory. The
+  backend connection through `cde.ctx` is optional — everything above `loadFolders`
+  works offline with mock data. See platform_cde for the full production wiring.
+*/

package/src/built-in/CDEManager/examples/FileEditing/example.ts

@@ -0,0 +1,226 @@
+/* MD
+  ## Bulk file editing — stage, preview, revert, and commit
+  ---
+  A project manager preparing a deliverable handoff needs to update discipline tags
+  across fifteen IFC files after a scope change, rename each to match the new naming
+  convention, and archive three superseded models — all before anything is sent to the
+  backend. Doing the changes one file at a time risks leaving the file list in a
+  half-updated state if the session is interrupted, and there is no way to review
+  exactly what will change before committing.
+
+  CDEManager provides a staging mode where metadata edits, renames, and archive marks
+  can be accumulated across any number of files before anything is written. The full
+  diff is visible in the machine state at any point, so the UI can show a per-row
+  preview of what is about to happen and let the user change their mind before
+  confirming.
+
+  This tutorial covers entering bulk edit mode from both the idle state and an active
+  selection; staging metadata edits and renames for multiple files; observing how
+  staging the original value back automatically clears a staged edit; reverting all
+  staged changes for one file in a single step; staging and unstaging a file for
+  archive; committing all staged changes and reading the result; and confirming that
+  the state returns to the correct previous position after the commit.
+
+  By the end, you'll have a working demonstration of the full bulk edit cycle — stage,
+  preview, revert, commit, and cancel — with all transitions driven through the state
+  machine.
+*/
+
+import * as OBC from "@thatopen/components";
+// In production platform apps, CDEManager is loaded through the platform client:
+//   const cde = await client.initBuiltInComponent(CDEManager.uuid, components);
+// Here we import directly from source for local testing.
+import { CDEManager } from "../../index";
+import type { CDEFile } from "../../src/types";
+
+/* MD
+  ### 🛠️ Setting up
+  All flows in this example run against mock data without a backend connection. Entering
+  bulk edit mode is permission-gated, so we simulate the platform startup step that
+  loads user permissions before running any demos.
+*/
+
+const components = new OBC.Components();
+const cde = components.get(CDEManager);
+
+const output = document.getElementById("output") as HTMLPreElement;
+const log = (msg: string) => { console.log(msg); output.textContent += msg + "\n"; };
+
+// Simulate the platform startup step that loads permissions.
+cde.ctx = {
+  client: {
+    checkPermissionBatch: async () => Array(5).fill({ hasPermission: true }),
+    getProjectData: async () => ({ project: { title: "" }, users: [] }),
+    listFolders: async () => [],
+  } as any,
+  projectId: "mock",
+};
+await cde.loadFolders();
+// Clear the context — mock flows don't make API calls.
+cde.ctx = undefined;
+
+const now = new Date();
+const mockFiles: CDEFile[] = [
+  {
+    _id: "f1", name: "column.ifc", folderId: null,
+    createdBy: "alice", createdAt: now,
+    metadata: { discipline: "STR", phase: "DD" },
+  } as CDEFile,
+  {
+    _id: "f2", name: "foundations.ifc", folderId: null,
+    createdBy: "bob", createdAt: now,
+    metadata: { discipline: "STR", phase: "CD" },
+  } as CDEFile,
+  {
+    _id: "f3", name: "report.pdf", folderId: null,
+    createdBy: "alice", createdAt: now,
+    metadata: {},
+  } as CDEFile,
+];
+cde.files = mockFiles;
+
+cde.onMachineStateChanged.add((s) => log(`  → ${s.kind}`));
+cde.onFilesChanged.add((files) => log(`  [onFilesChanged] ${files.length} file(s)`));
+
+/* MD
+  ### 📋 Staging edits across multiple files
+  In bulk edit mode, every change accumulates in the machine state rather than being
+  applied right away. The state carries a per-file record of staged metadata edits and
+  renames, so the UI can display a diff table without any extra bookkeeping — it just
+  reads the machine state.
+
+  Cancelling discards all staged changes and returns to wherever the session started,
+  leaving every file exactly as it was.
+*/
+
+log("\n--- stage edits and cancel ---");
+cde.sendMachineEvent({ type: "START_EDIT_FILES" });
+
+cde.sendMachineEvent({ type: "UPDATE_FILE_METADATA", fileId: "f1", key: "discipline", value: "MEP" });
+cde.sendMachineEvent({ type: "UPDATE_FILE_METADATA", fileId: "f2", key: "phase", value: "SD" });
+cde.sendMachineEvent({ type: "RENAME_FILE", fileId: "f1", name: "column-revised.ifc" });
+
+if (cde.machineState.kind === "editingFiles") {
+  const { pendingEdits, pendingRenames } = cde.machineState;
+  log(`  staged edits:   ${Object.keys(pendingEdits).length} file(s)`);
+  log(`  staged renames: ${Object.keys(pendingRenames).length} file(s)`);
+}
+
+cde.sendMachineEvent({ type: "CANCEL_EDIT_FILES" });
+log(`  state after cancel: ${cde.machineState.kind}`);
+// Files are untouched — nothing was committed.
+log(`  f1 discipline: ${cde.files.find(f => f._id === "f1")!.metadata.discipline}`);
+
+/* MD
+  ### 🔍 Smart diff: staging the original value clears the edit
+  The staging system tracks whether a value actually differs from the file's current
+  state. If a user edits a field and then edits it back to its original value, the
+  edit disappears from the staged list on its own — the state machine does the diffing
+  so the UI doesn't need to.
+*/
+
+log("\n--- smart diff ---");
+cde.sendMachineEvent({ type: "START_EDIT_FILES" });
+
+cde.sendMachineEvent({ type: "UPDATE_FILE_METADATA", fileId: "f1", key: "discipline", value: "MEP" });
+if (cde.machineState.kind === "editingFiles") {
+  log(`  f1 staged: ${Object.keys(cde.machineState.pendingEdits).includes("f1")}`);
+}
+
+// Staging the original value back auto-removes f1 from pendingEdits.
+cde.sendMachineEvent({ type: "UPDATE_FILE_METADATA", fileId: "f1", key: "discipline", value: "STR" });
+if (cde.machineState.kind === "editingFiles") {
+  log(`  f1 staged after revert: ${Object.keys(cde.machineState.pendingEdits).includes("f1")}`);
+}
+
+cde.sendMachineEvent({ type: "CANCEL_EDIT_FILES" });
+
+/* MD
+  ### ↩️ Reverting all staged changes for one file
+  When a user wants to undo everything they staged for a particular file — not just
+  one field — a single revert event wipes all of its staged edits, renames, and archive
+  marks at once. Files with no staged changes are unaffected.
+*/
+
+log("\n--- revert one file ---");
+cde.sendMachineEvent({ type: "START_EDIT_FILES" });
+
+cde.sendMachineEvent({ type: "UPDATE_FILE_METADATA", fileId: "f1", key: "discipline", value: "MEP" });
+cde.sendMachineEvent({ type: "RENAME_FILE", fileId: "f1", name: "column-revised.ifc" });
+cde.sendMachineEvent({ type: "ARCHIVE_FILE_EDIT", fileId: "f1" });
+
+if (cde.machineState.kind === "editingFiles") {
+  const { pendingEdits, pendingRenames, pendingArchives } = cde.machineState;
+  log(`  before revert — edits: ${Object.keys(pendingEdits).length}, renames: ${Object.keys(pendingRenames).length}, archives: ${pendingArchives.length}`);
+}
+
+// REVERT_FILE_METADATA clears edits, renames, and archive mark for f1 in one event.
+cde.sendMachineEvent({ type: "REVERT_FILE_METADATA", fileId: "f1" });
+
+if (cde.machineState.kind === "editingFiles") {
+  const { pendingEdits, pendingRenames, pendingArchives } = cde.machineState;
+  log(`  after revert  — edits: ${Object.keys(pendingEdits).length}, renames: ${Object.keys(pendingRenames).length}, archives: ${pendingArchives.length}`);
+}
+
+cde.sendMachineEvent({ type: "CANCEL_EDIT_FILES" });
+
+/* MD
+  ### 🗑️ Staging archives and committing
+  Marking a file for archive in bulk edit mode stages the deletion — the file stays
+  visible in the table, just flagged, so the user can see it in the preview and change
+  their mind before committing. Unstaging removes the mark and the file is back to
+  normal. Files staged for archive are excluded from metadata and rename operations
+  when the commit runs, so staging both a rename and an archive on the same file never
+  creates a conflict.
+*/
+
+log("\n--- archive staging + commit ---");
+cde.sendMachineEvent({ type: "START_EDIT_FILES" });
+
+cde.sendMachineEvent({ type: "ARCHIVE_FILE_EDIT", fileId: "f3" });
+if (cde.machineState.kind === "editingFiles") {
+  log(`  pending archives: ${cde.machineState.pendingArchives.length}`);
+}
+
+// Unstaging gives the user a chance to reconsider before the commit.
+cde.sendMachineEvent({ type: "UNARCHIVE_FILE_EDIT", fileId: "f3" });
+if (cde.machineState.kind === "editingFiles") {
+  log(`  after unarchive: ${cde.machineState.pendingArchives.length}`);
+}
+
+// Stage f3 for archive again, and also rename f1.
+cde.sendMachineEvent({ type: "ARCHIVE_FILE_EDIT", fileId: "f3" });
+cde.sendMachineEvent({ type: "RENAME_FILE", fileId: "f1", name: "column-renamed.ifc" });
+
+log(`  files before commit: ${cde.files.length}`);
+cde.sendMachineEvent({ type: "SAVE_FILE_EDITS" });
+
+// Without a live client, changes are applied locally and synchronously.
+log(`  files after commit: ${cde.files.length}`);
+log(`  f1 name: ${cde.files.find(f => f._id === "f1")?.name ?? "not found"}`);
+log(`  f3 still in list: ${cde.files.some(f => f._id === "f3")}`);
+
+/* MD
+  ### 🔁 Returning to the previous selection
+  The state machine records where it came from when bulk edit mode is entered. Entering
+  from an active selection returns there after committing — the same files are still
+  highlighted in the table. Entering from idle returns to idle. Either way, the
+  selection is never lost.
+*/
+
+log("\n--- previousState: commit from selection ---");
+// Start fresh with the original two IFC files.
+const f1 = cde.files.find(f => f._id === "f1")!;
+const f2 = cde.files.find(f => f._id === "f2")!;
+
+cde.sendMachineEvent({ type: "SELECT", files: [f1, f2] });
+// Entering from "selected" records it as the return point.
+cde.sendMachineEvent({ type: "START_EDIT_FILES" });
+
+cde.sendMachineEvent({ type: "UPDATE_FILE_METADATA", fileId: "f1", key: "phase", value: "SD" });
+cde.sendMachineEvent({ type: "SAVE_FILE_EDITS" });
+
+log(`  state after commit: ${cde.machineState.kind}`);
+if (cde.machineState.kind === "selected") {
+  log(`  selection preserved: ${cde.machineState.files.length} file(s)`);
+}

package/src/built-in/CDEManager/examples/FileMoves/example.ts

@@ -0,0 +1,186 @@
+/* MD
+  ## Drag-and-drop file and folder moves
+  ---
+  A coordinator restructures the project after a scope change: structural files move
+  from the root into a dedicated discipline folder, a MEP sub-folder needs to be
+  promoted to the top level, and a few documents need to come back to root to appear
+  in the general view. Drag-and-drop is the natural gesture for all of this, but
+  each drag session has intermediate stages — the file is "in the air", hovering over
+  a candidate target — and every panel watching the file table should see the right
+  state without coordinating directly with the drag component.
+
+  CDEManager models drag-and-drop as a sequence of typed state transitions. Picking
+  up files moves the machine to a dragging state that carries the files being dragged
+  and where they came from. Dropping onto a target kicks off the API call and advances
+  to a moving state. Releasing outside any drop zone cancels the drag and returns the
+  machine to exactly the state it was in before the drag started — idle or a selection.
+  Folder drags work the same way, with their own separate completion event.
+
+  This tutorial covers starting a file drag from idle and from an active selection;
+  cancelling the drag and confirming which state the machine returns to; committing
+  a drop onto a folder and reading the moved files from the completion event; moving
+  files back to the project root by passing a null target folder; and starting,
+  cancelling, and committing a folder drag.
+
+  By the end, you'll have a working demonstration of the full drag-and-drop cycle for
+  both files and folders — start, cancel, and commit — with all state transitions and
+  completion events verified against mock data.
+*/
+
+import * as OBC from "@thatopen/components";
+// In production platform apps, CDEManager is loaded through the platform client:
+//   const cde = await client.initBuiltInComponent(CDEManager.uuid, components);
+// Here we import directly from source for local testing.
+import { CDEManager } from "../../index";
+import type { CDEFile } from "../../src/types";
+
+/* MD
+  ### 🛠️ Setting up
+  File and folder moves are permission-gated, so we simulate the platform startup step
+  that loads user permissions. The mock client also provides `updateItem` for file
+  moves and `resolveAccessToken` for folder moves, which use different backend paths.
+*/
+
+const components = new OBC.Components();
+const cde = components.get(CDEManager);
+
+const output = document.getElementById("output") as HTMLPreElement;
+const log = (msg: string) => { console.log(msg); output.textContent += msg + "\n"; };
+
+const mockClient = {
+  checkPermissionBatch: async () => Array(5).fill({ hasPermission: true }),
+  getProjectData: async () => ({ project: { title: "" }, users: [] }),
+  listFolders: async () => [],
+  updateItem: async (_id: string, _updates: any) => ({}),
+  resolveAccessToken: async () => "mock-token",
+  context: { apiUrl: "https://mock.api" },
+};
+
+cde.ctx = { client: mockClient as any, projectId: "mock" };
+await cde.loadFolders();
+
+const folders = [
+  { _id: "folder-str", name: "Structural", parentId: null },
+  { _id: "folder-arch", name: "Architecture", parentId: null },
+  { _id: "folder-mep", name: "MEP", parentId: "folder-arch" },
+];
+cde.folders = folders as any;
+
+const now = new Date();
+const mockFiles: CDEFile[] = [
+  { _id: "f1", name: "column.ifc", folderId: null, createdBy: "alice", createdAt: now, metadata: {} } as CDEFile,
+  { _id: "f2", name: "foundations.ifc", folderId: null, createdBy: "alice", createdAt: now, metadata: {} } as CDEFile,
+  { _id: "f3", name: "duct.ifc", folderId: "folder-arch", createdBy: "bob", createdAt: now, metadata: {} } as CDEFile,
+];
+cde.files = mockFiles;
+
+cde.onMachineStateChanged.add((s) => log(`  → ${s.kind}`));
+cde.onFilesMovedCompleted.add(({ files, targetFolderName }) =>
+  log(`  [onFilesMovedCompleted] ${files.length} file(s) → "${targetFolderName ?? "root"}"`)
+);
+cde.onFolderMovedCompleted.add(({ folderName, targetFolderName }) =>
+  log(`  [onFolderMovedCompleted] "${folderName}" → "${targetFolderName ?? "root"}"`)
+);
+
+/* MD
+  ### 🖱️ File drag — cancel
+  Starting a drag records the dragged files and the folder they came from. Cancelling
+  — for example when the user releases the mouse outside any drop target — returns the
+  machine to the state it was in when the drag started. If the drag started from idle,
+  it returns to idle. If it started from a selection, the same selection is restored.
+*/
+
+log("\n--- file drag: cancel from idle ---");
+cde.sendMachineEvent({ type: "START_DRAG", files: [mockFiles[0]], sourceFolderId: null });
+
+if (cde.machineState.kind === "dragging") {
+  log(`  dragging: ${cde.machineState.files.length} file(s) from "${cde.machineState.sourceFolderId ?? "root"}"`);
+}
+
+cde.sendMachineEvent({ type: "END_DRAG" });
+log(`  state after cancel: ${cde.machineState.kind}`);
+
+log("\n--- file drag: cancel from selection ---");
+cde.sendMachineEvent({ type: "SELECT", files: [mockFiles[0], mockFiles[1]] });
+// Drag starts from "selected" — previousState carries the selection.
+cde.sendMachineEvent({ type: "START_DRAG", files: [mockFiles[0]], sourceFolderId: null });
+cde.sendMachineEvent({ type: "END_DRAG" });
+log(`  state after cancel: ${cde.machineState.kind}`);
+if (cde.machineState.kind === "selected") {
+  log(`  selection preserved: ${cde.machineState.files.length} file(s)`);
+}
+
+/* MD
+  ### 📁 File drag — drop onto a folder
+  When the user drops files onto a valid folder target, the machine moves to a moving
+  state and the API call runs. On completion, the moved files reflect their new folder
+  and the machine returns to idle. The completion event carries both the updated files
+  and the target folder name, so the UI can show a confirmation without reading the
+  whole file list.
+*/
+
+log("\n--- file drag: drop onto folder ---");
+cde.sendMachineEvent({ type: "DESELECT" });
+cde.sendMachineEvent({ type: "START_DRAG", files: [mockFiles[0], mockFiles[1]], sourceFolderId: null });
+
+await new Promise<void>(resolve => {
+  cde.onFilesMovedCompleted.add(() => resolve());
+  cde.sendMachineEvent({ type: "DROP_FILES", targetFolderId: "folder-str" });
+});
+
+log(`  state after move: ${cde.machineState.kind}`);
+const f1Updated = cde.files.find(f => f._id === "f1")!;
+log(`  f1 folderId: ${(f1Updated as any).folderId}`);
+
+/* MD
+  ### 🏠 File drag — drop at root
+  Dropping files without specifying a target folder moves them to the project root.
+  The completion event's `targetFolderName` is null for root drops, which the UI can
+  use to display "Moved to root" instead of a folder name.
+*/
+
+log("\n--- file drag: drop at root ---");
+cde.sendMachineEvent({ type: "START_DRAG", files: [mockFiles[2]], sourceFolderId: "folder-arch" });
+
+await new Promise<void>(resolve => {
+  cde.onFilesMovedCompleted.add(() => resolve());
+  cde.sendMachineEvent({ type: "DROP_FILES", targetFolderId: null });
+});
+
+log(`  state after move: ${cde.machineState.kind}`);
+const f3Updated = cde.files.find(f => f._id === "f3")!;
+log(`  f3 folderId: ${(f3Updated as any).folderId ?? "root"}`);
+
+/* MD
+  ### 📂 Folder drag — cancel and commit
+  Folder drags follow the same state sequence as file drags. Cancelling a folder drag
+  returns to the previous state unchanged. Committing calls a dedicated backend
+  endpoint and fires a separate completion event with the folder names involved, which
+  the UI uses for confirmation messages.
+*/
+
+log("\n--- folder drag: cancel ---");
+cde.sendMachineEvent({ type: "START_FOLDER_DRAG", folderId: "folder-mep", parentFolderId: "folder-arch" });
+
+if (cde.machineState.kind === "draggingFolder") {
+  log(`  draggingFolder: "${cde.machineState.folderId}"`);
+}
+
+cde.sendMachineEvent({ type: "END_FOLDER_DRAG" });
+log(`  state after cancel: ${cde.machineState.kind}`);
+
+log("\n--- folder drag: commit ---");
+// _moveFolder calls fetch directly; intercept it for the mock.
+const realFetch = globalThis.fetch;
+globalThis.fetch = async () => new Response("{}", { status: 200 });
+
+cde.sendMachineEvent({ type: "START_FOLDER_DRAG", folderId: "folder-mep", parentFolderId: "folder-arch" });
+
+await new Promise<void>(resolve => {
+  cde.onFolderMovedCompleted.add(() => resolve());
+  // Move MEP out of Architecture and into Structural.
+  cde.sendMachineEvent({ type: "DROP_FOLDER", targetFolderId: "folder-str" });
+});
+
+globalThis.fetch = realFetch;
+log(`  state after commit: ${cde.machineState.kind}`);