eventmodeler 0.6.11 → 0.6.13

package/dist/index.js

@@ -92,11 +92,11 @@ var require_re = __commonJS((exports, module) => {
     }
     return value;
   };
-  var createToken = (name, value, isGlobal) => {
+  var createToken = (name2, value, isGlobal) => {
     const safe = makeSafeRegex(value);
     const index = R++;
-    debug(name, index, value);
-    t[name] = index;
+    debug(name2, index, value);
+    t[name2] = index;
     src[index] = value;
     safeSrc[index] = safe;
     re[index] = new RegExp(value, isGlobal ? "g" : undefined);
@@ -1815,8 +1815,8 @@ var require_semver2 = __commonJS((exports, module) => {
 });
 
 // src/index.ts
-import * as fs5 from "node:fs";
-import * as path5 from "node:path";
+import * as fs6 from "node:fs";
+import * as path6 from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 
@@ -2281,7 +2281,8 @@ function loadProjectConfig(startDir) {
     const content = fs2.readFileSync(configPath, "utf-8");
     const config = JSON.parse(content);
     if (config.type === "cloud" && config.modelId && config.modelName) {
-      return { type: "cloud", modelId: config.modelId, modelName: config.modelName };
+      const mode = config.mode === "sheets" || config.mode === "freeform" ? config.mode : undefined;
+      return { type: "cloud", modelId: config.modelId, modelName: config.modelName, mode };
     }
     return null;
   } catch {
@@ -2291,10 +2292,19 @@ function loadProjectConfig(startDir) {
 function saveProjectConfig(config, targetDir = process.cwd()) {
   const configPath = path2.join(targetDir, PROJECT_CONFIG_FILENAME);
   const content = { type: "cloud", modelId: config.modelId, modelName: config.modelName };
+  if (config.mode)
+    content.mode = config.mode;
   fs2.writeFileSync(configPath, JSON.stringify(content, null, 2) + `
 `);
   return configPath;
 }
+function removeProjectConfig(startDir) {
+  const configPath = findProjectConfigPath(startDir);
+  if (!configPath)
+    return null;
+  fs2.rmSync(configPath);
+  return configPath;
+}
 function getProjectRoot(startDir = process.cwd()) {
   const configPath = findProjectConfigPath(startDir);
   if (configPath) {
@@ -2480,7 +2490,7 @@ async function init() {
     } else {
       console.log("Your models:");
       models.forEach((m, i) => {
-        console.log(`  ${i + 1}. ${m.name}  (${m.role}, ${m.visibility})`);
+        console.log(`  ${i + 1}. ${m.name}  (${m.role}, ${m.visibility}, ${m.mode ?? "freeform"})`);
       });
       console.log(`  n. Create a new model`);
       const answer = (await ask(`
@@ -2494,16 +2504,17 @@ Pick a model [1]: `)).trim() || "1";
           process.exit(2);
         }
         const m = models[idx - 1];
-        picked = { id: m.id, name: m.name };
+        picked = { id: m.id, name: m.name, mode: m.mode ?? "freeform" };
       }
     }
     const configPath = saveProjectConfig({
       type: "cloud",
       modelId: picked.id,
-      modelName: picked.name
+      modelName: picked.name,
+      mode: picked.mode ?? "freeform"
     });
     console.log(`
-Linked to model "${picked.name}" (${picked.id}).`);
+Linked to model "${picked.name}" (${picked.id}, ${picked.mode ?? "freeform"}).`);
     console.log(`Wrote ${configPath}.`);
   } finally {
     rl.close();
@@ -2525,13 +2536,41 @@ async function createModel(ask) {
       method: "POST",
       json: { name, visibility: visAnswer }
     });
-    return { id: created.id, name: created.name };
+    return { id: created.id, name: created.name, mode: "freeform" };
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`Failed to create model: ${msg}`);
     process.exit(1);
   }
 }
+
+// src/commands/status.ts
+function registerStatusCommands(program, conn) {
+  program.command("status").description("Show the current connection: which model, which mode, which command surface").option("--model <id>", "Report the state for this model instead of .eventmodeler.json").action(() => {
+    if (conn.state === "disconnected") {
+      console.log("Not connected. Run `eventmodeler init` to link a model, or pass --model <id>.");
+      return;
+    }
+    const name = conn.modelName ? `"${conn.modelName}" ` : "";
+    const id = conn.modelId ?? "(unknown id)";
+    if (conn.state === "unknown") {
+      console.log(`Connected to ${name}${id} — mode could not be resolved; all commands are available.`);
+      return;
+    }
+    const surface = conn.state === "sheets" ? "sheets surface (`sheet …`)" : "freeform surface (create/update/remove/show/…)";
+    console.log(`Connected to ${name}${id}`);
+    console.log(`  mode: ${conn.state} — ${surface}`);
+    if (conn.overridden)
+      console.log("  (via --model override)");
+  });
+  program.command("disconnect").description("Unlink the current directory from its model (removes .eventmodeler.json)").action(() => {
+    const removed = removeProjectConfig();
+    if (removed)
+      console.log(`Disconnected — removed ${removed}.`);
+    else
+      console.log("Not connected (no .eventmodeler.json found).");
+  });
+}
 // ../packages/canvas-model/src/build.ts
 import * as Y2 from "yjs";
 function buildYArray(items) {
@@ -2577,6 +2616,10 @@ function getEntry(doc, scope, id) {
   return entry instanceof Y4.AbstractType ? entry.toJSON() : entry;
 }
 // ../packages/canvas-model/src/dimensions.ts
+var GRID_SIZE = 20;
+function snap(value) {
+  return Math.round(value / GRID_SIZE) * GRID_SIZE;
+}
 var ELEMENT_DIMENSIONS = {
   commandSticky: { width: 160, height: 100 },
   eventSticky: { width: 160, height: 100 },
@@ -2605,6 +2648,35 @@ function canonicalSizeForScope(scope) {
 }
 // ../packages/canvas-model/src/actions.ts
 import * as Y5 from "yjs";
+
+// ../packages/canvas-model/src/cascade.ts
+var FLOWS_SCOPE = "flows";
+var SCENARIOS_SCOPE = "scenarios";
+var SCENARIO_SECTIONS = ["givenEntries", "whenEntries", "thenEntries"];
+function cascadeStickyRemoval(doc, removedIds) {
+  if (removedIds.size === 0)
+    return;
+  const flows = getScopeMap(doc, FLOWS_SCOPE);
+  for (const [fid, f] of flows.entries()) {
+    const src = f.get("sourceId");
+    const tgt = f.get("targetId");
+    if (removedIds.has(src) || removedIds.has(tgt))
+      flows.delete(fid);
+  }
+  const scenarios = getScopeMap(doc, SCENARIOS_SCOPE);
+  for (const scenario of scenarios.values()) {
+    for (const key of SCENARIO_SECTIONS) {
+      const arr = scenario.get(key);
+      if (!arr)
+        continue;
+      for (let i = arr.length - 1;i >= 0; i--) {
+        const stickyId = arr.get(i).get("stickyId");
+        if (stickyId && removedIds.has(stickyId))
+          arr.delete(i, 1);
+      }
+    }
+  }
+}
 // ../packages/canvas-model/src/containment.ts
 function centerOf(bbox) {
   return { x: bbox.x + bbox.width / 2, y: bbox.y + bbox.height / 2 };
@@ -2630,7 +2702,7 @@ function innermostContainer(containers, point) {
   return best;
 }
 // ../packages/canvas-model/src/completeness.ts
-var FLOWS_SCOPE = "flows";
+var FLOWS_SCOPE2 = "flows";
 var SLICES_SCOPE = "slices";
 var AGGREGATES_SCOPE = "aggregates";
 var FIELD_BEARING_SCOPES = [
@@ -2678,7 +2750,7 @@ function targetIdSet(target) {
 }
 function inboundFlows(doc, target) {
   const ids = targetIdSet(target);
-  return getEntries(doc, FLOWS_SCOPE).filter((f) => ids.has(f.targetId));
+  return getEntries(doc, FLOWS_SCOPE2).filter((f) => ids.has(f.targetId));
 }
 function untracedFields(doc, target) {
   const fields = target.fields ?? [];
@@ -2756,13 +2828,19 @@ var baseContainer = (idKey) => NamedBox.extend({
 });
 var SliceStatusSchema = z.enum(["draft", "created", "planned", "in-progress", "blocked", "done"]);
 var SliceSchema = baseContainer("sliceId").extend({
-  status: SliceStatusSchema.optional()
+  status: SliceStatusSchema.optional(),
+  note: z.string().optional()
 });
 var AggregateSchema = baseContainer("aggregateId");
 var ActorSchema = baseContainer("actorId");
 var ChapterSchema = baseContainer("chapterId");
 var ContextSchema = baseContainer("contextId");
-var SwimLaneSchema = baseContainer("swimLaneId");
+var LaneKindSchema = z.enum(["actor", "interaction", "swimlane", "specification"]);
+var SwimLaneSchema = baseContainer("swimLaneId").extend({
+  laneKind: LaneKindSchema.optional(),
+  note: z.string().optional(),
+  color: z.string().optional()
+});
 var NoteSchema = Box.extend({
   noteId: z.string().uuid().optional(),
   modelId: z.string().uuid().optional(),
@@ -2828,7 +2906,8 @@ var FlowTypeSchema = z.enum([
   "ScreenToCommand",
   "ProcessorToCommand",
   "CommandToExternalEvent",
-  "ExternalEventToProcessor"
+  "ExternalEventToProcessor",
+  "ExternalEventToScreen"
 ]);
 var FlowHandleSchema = z.enum([
   "top-source",
@@ -2855,6 +2934,32 @@ var FlowSchema = z.object({
   targetHandle: FlowHandleSchema.optional(),
   mappings: z.array(FlowMappingSchema).optional()
 });
+var SheetFlowSchema = z.object({
+  sheetFlowId: z.string().uuid().optional(),
+  modelId: z.string().uuid().optional(),
+  sourceChapterId: z.string().uuid(),
+  sourceHandle: z.string().min(1),
+  targetChapterId: z.string().uuid(),
+  targetHandle: z.string().min(1)
+});
+var CellRefSchema = z.object({
+  stickyId: z.string().uuid(),
+  scope: z.enum([
+    "commands",
+    "events",
+    "readModels",
+    "screens",
+    "processors",
+    "externalEvents",
+    "scenarios"
+  ])
+});
+var SheetStructureSchema = z.object({
+  columns: z.array(z.string().uuid()),
+  rows: z.array(z.string().uuid()),
+  cells: z.record(z.string(), z.array(CellRefSchema)),
+  cellNotes: z.record(z.string(), z.string()).optional()
+});
 var SCOPE_SCHEMAS = {
   commands: CommandSchema,
   events: EventSchema,
@@ -2869,7 +2974,8 @@ var SCOPE_SCHEMAS = {
   contexts: ContextSchema,
   swimLanes: SwimLaneSchema,
   notes: NoteSchema,
-  flows: FlowSchema
+  flows: FlowSchema,
+  sheetFlows: SheetFlowSchema
 };
 function isValidatedScope(scope) {
   return scope in SCOPE_SCHEMAS;
@@ -2893,6 +2999,519 @@ function pickSchema(scope, data) {
   }
   return SCOPE_SCHEMAS[scope];
 }
+// ../packages/canvas-model/src/grid.ts
+import * as Y6 from "yjs";
+var GRID_SCOPE = "grid";
+function getGridMap(doc) {
+  return doc.getMap(GRID_SCOPE);
+}
+function cellKey(sliceId, swimLaneId) {
+  return `${sliceId}:${swimLaneId}`;
+}
+function resolveSheet(doc, chapterId) {
+  const grid = getGridMap(doc);
+  let sheet = grid.get(chapterId);
+  if (!sheet) {
+    sheet = new Y6.Map;
+    sheet.set("columns", new Y6.Array);
+    sheet.set("rows", new Y6.Array);
+    sheet.set("cells", new Y6.Map);
+    grid.set(chapterId, sheet);
+  }
+  return {
+    sheet,
+    columns: sheet.get("columns"),
+    rows: sheet.get("rows"),
+    cells: sheet.get("cells")
+  };
+}
+function ensureSheet(doc, chapterId) {
+  doc.transact(() => {
+    resolveSheet(doc, chapterId);
+  });
+}
+function readSheet(doc, chapterId) {
+  const sheet = getGridMap(doc).get(chapterId);
+  if (!sheet)
+    return;
+  return sheet.toJSON();
+}
+function clampIndex(at, length) {
+  if (at === undefined || at > length)
+    return length;
+  return at < 0 ? 0 : at;
+}
+function insertUnique(arr, value, at) {
+  if (arr.toArray().includes(value))
+    return;
+  arr.insert(clampIndex(at, arr.length), [value]);
+}
+function addColumn(doc, chapterId, sliceId, at) {
+  doc.transact(() => {
+    const { columns } = resolveSheet(doc, chapterId);
+    insertUnique(columns, sliceId, at);
+  });
+}
+function moveColumn(doc, chapterId, sliceId, toIndex) {
+  doc.transact(() => {
+    const { columns } = resolveSheet(doc, chapterId);
+    const from = columns.toArray().indexOf(sliceId);
+    if (from === -1)
+      return;
+    columns.delete(from, 1);
+    columns.insert(clampIndex(toIndex, columns.length), [sliceId]);
+  });
+}
+function removeColumn(doc, chapterId, sliceId) {
+  doc.transact(() => {
+    const sheet = getGridMap(doc).get(chapterId);
+    if (!sheet)
+      return;
+    const columns = sheet.get("columns");
+    const cells = sheet.get("cells");
+    const cellNotes = sheet.get("cellNotes");
+    const idx = columns.toArray().indexOf(sliceId);
+    if (idx !== -1)
+      columns.delete(idx, 1);
+    for (const key of [...cells.keys()]) {
+      if (key.startsWith(`${sliceId}:`))
+        cells.delete(key);
+    }
+    for (const key of [...cellNotes?.keys() ?? []]) {
+      if (key.startsWith(`${sliceId}:`))
+        cellNotes.delete(key);
+    }
+  });
+}
+function addRow(doc, chapterId, swimLaneId, at) {
+  doc.transact(() => {
+    const { rows } = resolveSheet(doc, chapterId);
+    insertUnique(rows, swimLaneId, at);
+  });
+}
+function moveRow(doc, chapterId, swimLaneId, toIndex) {
+  doc.transact(() => {
+    const { rows } = resolveSheet(doc, chapterId);
+    const from = rows.toArray().indexOf(swimLaneId);
+    if (from === -1)
+      return;
+    rows.delete(from, 1);
+    rows.insert(clampIndex(toIndex, rows.length), [swimLaneId]);
+  });
+}
+function removeRow(doc, chapterId, swimLaneId) {
+  doc.transact(() => {
+    const sheet = getGridMap(doc).get(chapterId);
+    if (!sheet)
+      return;
+    const rows = sheet.get("rows");
+    const cells = sheet.get("cells");
+    const cellNotes = sheet.get("cellNotes");
+    const idx = rows.toArray().indexOf(swimLaneId);
+    if (idx !== -1)
+      rows.delete(idx, 1);
+    for (const key of [...cells.keys()]) {
+      if (key.endsWith(`:${swimLaneId}`))
+        cells.delete(key);
+    }
+    for (const key of [...cellNotes?.keys() ?? []]) {
+      if (key.endsWith(`:${swimLaneId}`))
+        cellNotes.delete(key);
+    }
+  });
+}
+function getCellArray(cells, key, create) {
+  let arr = cells.get(key);
+  if (!arr && create) {
+    arr = new Y6.Array;
+    cells.set(key, arr);
+  }
+  return arr;
+}
+function findStickyCell(cells, stickyId) {
+  for (const key of cells.keys()) {
+    const arr = cells.get(key);
+    const index = arr.toArray().findIndex((m) => m.get("stickyId") === stickyId);
+    if (index !== -1)
+      return { key, index };
+  }
+  return;
+}
+function placeInCell(doc, chapterId, sliceId, swimLaneId, ref, at) {
+  doc.transact(() => {
+    const { cells } = resolveSheet(doc, chapterId);
+    const existing = findStickyCell(cells, ref.stickyId);
+    if (existing)
+      cells.get(existing.key).delete(existing.index, 1);
+    const arr = getCellArray(cells, cellKey(sliceId, swimLaneId), true);
+    arr.insert(clampIndex(at, arr.length), [
+      (() => {
+        const m = new Y6.Map;
+        m.set("stickyId", ref.stickyId);
+        m.set("scope", ref.scope);
+        return m;
+      })()
+    ]);
+  });
+}
+function removeSticky(doc, chapterId, stickyId) {
+  doc.transact(() => {
+    const sheet = getGridMap(doc).get(chapterId);
+    if (!sheet)
+      return;
+    const cells = sheet.get("cells");
+    const loc = findStickyCell(cells, stickyId);
+    if (!loc)
+      return;
+    cells.get(loc.key).delete(loc.index, 1);
+  });
+}
+function removeSheet(doc, chapterId) {
+  doc.transact(() => {
+    getGridMap(doc).delete(chapterId);
+  });
+}
+function getCellNotesMap(doc, chapterId, create) {
+  const sheet = getGridMap(doc).get(chapterId);
+  if (!sheet)
+    return;
+  let notes = sheet.get("cellNotes");
+  if (!notes && create) {
+    notes = new Y6.Map;
+    sheet.set("cellNotes", notes);
+  }
+  return notes;
+}
+function readCellNotes(doc, chapterId) {
+  const notes = getGridMap(doc).get(chapterId)?.get("cellNotes");
+  return notes ? notes.toJSON() : {};
+}
+function setCellNote(doc, chapterId, sliceId, swimLaneId, text) {
+  doc.transact(() => {
+    const key = cellKey(sliceId, swimLaneId);
+    const trimmed = text.trim();
+    if (!trimmed) {
+      getCellNotesMap(doc, chapterId, false)?.delete(key);
+      return;
+    }
+    getCellNotesMap(doc, chapterId, true).set(key, trimmed);
+  });
+}
+// ../packages/canvas-model/src/sheet-delete.ts
+var CHAPTERS_SCOPE = "chapters";
+var SLICES_SCOPE2 = "slices";
+var SWIM_LANES_SCOPE = "swimLanes";
+var SCENARIOS_SCOPE2 = "scenarios";
+var SHEET_FLOWS_SCOPE = "sheetFlows";
+function deleteSheet(doc, chapterId) {
+  doc.transact(() => {
+    const sheet = getGridMap(doc).get(chapterId);
+    const removedStickies = new Set;
+    const sliceIds = new Set;
+    const laneIds = new Set;
+    if (sheet) {
+      for (const id of sheet.get("columns").toArray())
+        sliceIds.add(id);
+      for (const id of sheet.get("rows").toArray())
+        laneIds.add(id);
+      const cells = sheet.get("cells");
+      for (const key of cells.keys()) {
+        for (const ref of cells.get(key).toArray()) {
+          const stickyId = ref.get("stickyId");
+          getScopeMap(doc, ref.get("scope")).delete(stickyId);
+          removedStickies.add(stickyId);
+        }
+      }
+    }
+    for (const id of sliceIds)
+      getScopeMap(doc, SLICES_SCOPE2).delete(id);
+    for (const id of laneIds)
+      getScopeMap(doc, SWIM_LANES_SCOPE).delete(id);
+    const scenarios = getScopeMap(doc, SCENARIOS_SCOPE2);
+    for (const [id, sc] of scenarios.entries()) {
+      if (sliceIds.has(sc.get("sliceId"))) {
+        scenarios.delete(id);
+        removedStickies.add(id);
+      }
+    }
+    cascadeStickyRemoval(doc, removedStickies);
+    const sheetFlows = getScopeMap(doc, SHEET_FLOWS_SCOPE);
+    for (const [id, f] of sheetFlows.entries()) {
+      if (f.get("sourceChapterId") === chapterId || f.get("targetChapterId") === chapterId) {
+        sheetFlows.delete(id);
+      }
+    }
+    removeSheet(doc, chapterId);
+    getScopeMap(doc, CHAPTERS_SCOPE).delete(chapterId);
+  });
+}
+// ../packages/canvas-model/src/sheet-layout.ts
+function applyLayoutOverride(cells, ov) {
+  const out = {};
+  for (const [k, arr] of Object.entries(cells))
+    out[k] = arr.filter((r) => r.stickyId !== ov.stickyId);
+  if (ov.toSliceId && ov.toSwimLaneId && ov.scope) {
+    const key = cellKey(ov.toSliceId, ov.toSwimLaneId);
+    const arr = out[key] ? [...out[key]] : [];
+    const at = ov.index === undefined ? arr.length : Math.max(0, Math.min(arr.length, ov.index));
+    arr.splice(at, 0, { stickyId: ov.stickyId, scope: ov.scope });
+    out[key] = arr;
+  }
+  return out;
+}
+var SHEET_LAYOUT = {
+  headerTop: 80,
+  headerLeft: 200,
+  cellPadX: 60,
+  cellPadY: 60,
+  stickyGap: 20,
+  minColWidth: 340,
+  minRowHeight: 240
+};
+var SCENARIO_CARD = { width: 300, height: 80 };
+function stickySize(scope) {
+  if (scope === "scenarios")
+    return SCENARIO_CARD;
+  return FIXED_SIZE_SCOPE_DIMENSIONS[scope] ?? { width: 160, height: 100 };
+}
+function isVerticalCell(refs) {
+  return refs.length > 0 && refs[0].scope === "scenarios";
+}
+function cellContentSize(refs) {
+  if (refs.length === 0)
+    return { width: 0, height: 0 };
+  const vertical = isVerticalCell(refs);
+  let width = 0;
+  let height = 0;
+  refs.forEach((ref, i) => {
+    const s = stickySize(ref.scope);
+    if (vertical) {
+      height += s.height + (i > 0 ? SHEET_LAYOUT.stickyGap : 0);
+      width = Math.max(width, s.width);
+    } else {
+      width += s.width + (i > 0 ? SHEET_LAYOUT.stickyGap : 0);
+      height = Math.max(height, s.height);
+    }
+  });
+  return { width, height };
+}
+function pruneOrphanCellRefs(doc, chapterId) {
+  const sheet = getGridMap(doc).get(chapterId);
+  if (!sheet)
+    return 0;
+  const cells = sheet.get("cells");
+  let pruned = 0;
+  for (const key of [...cells.keys()]) {
+    const arr = cells.get(key);
+    for (let i = arr.length - 1;i >= 0; i -= 1) {
+      const ref = arr.get(i);
+      const scope = ref.get("scope");
+      const stickyId = ref.get("stickyId");
+      if (!getScopeMap(doc, scope).has(stickyId)) {
+        arr.delete(i, 1);
+        pruned += 1;
+      }
+    }
+  }
+  return pruned;
+}
+function computeSheetLayout(doc, chapterId, override) {
+  const structure = readSheet(doc, chapterId);
+  if (!structure)
+    return;
+  const chapter = getEntry(doc, "chapters", chapterId);
+  const originX = snap(chapter?.x ?? 0);
+  const originY = snap(chapter?.y ?? 0);
+  const { columns, rows } = structure;
+  const cells = override ? applyLayoutOverride(structure.cells, override) : structure.cells;
+  const colWidths = columns.map((sliceId) => {
+    let w = 0;
+    for (const swimLaneId of rows) {
+      const refs = cells[cellKey(sliceId, swimLaneId)] ?? [];
+      const c = cellContentSize(refs);
+      if (c.width > 0)
+        w = Math.max(w, c.width + SHEET_LAYOUT.cellPadX * 2);
+    }
+    return snap(Math.max(w, SHEET_LAYOUT.minColWidth));
+  });
+  const rowHeights = rows.map((swimLaneId) => {
+    let h = 0;
+    for (const sliceId of columns) {
+      const refs = cells[cellKey(sliceId, swimLaneId)] ?? [];
+      const c = cellContentSize(refs);
+      if (c.height > 0)
+        h = Math.max(h, c.height + SHEET_LAYOUT.cellPadY * 2);
+    }
+    return snap(Math.max(h, SHEET_LAYOUT.minRowHeight));
+  });
+  const colX = [];
+  let xCursor = originX + SHEET_LAYOUT.headerLeft;
+  colWidths.forEach((w, i) => {
+    colX[i] = xCursor;
+    xCursor += w;
+  });
+  const rowY = [];
+  let yCursor = originY + SHEET_LAYOUT.headerTop;
+  rowHeights.forEach((h, i) => {
+    rowY[i] = yCursor;
+    yCursor += h;
+  });
+  const gridWidth = SHEET_LAYOUT.headerLeft + colWidths.reduce((a, b) => a + b, 0);
+  const gridHeight = SHEET_LAYOUT.headerTop + rowHeights.reduce((a, b) => a + b, 0);
+  const columnLayouts = columns.map((sliceId, i) => ({
+    sliceId,
+    index: i,
+    x: colX[i],
+    y: originY,
+    width: colWidths[i],
+    height: gridHeight
+  }));
+  const rowLayouts = rows.map((swimLaneId, i) => ({
+    swimLaneId,
+    index: i,
+    x: originX,
+    y: rowY[i],
+    width: gridWidth,
+    height: rowHeights[i]
+  }));
+  const stickies = [];
+  columns.forEach((sliceId, ci) => {
+    rows.forEach((swimLaneId, ri) => {
+      const refs = cells[cellKey(sliceId, swimLaneId)] ?? [];
+      if (refs.length === 0)
+        return;
+      const content = cellContentSize(refs);
+      const cellLeft = colX[ci];
+      const cellTop = rowY[ri];
+      const midX = cellLeft + colWidths[ci] / 2;
+      const midY = cellTop + rowHeights[ri] / 2;
+      if (isVerticalCell(refs)) {
+        let cursorY = cellTop + SHEET_LAYOUT.cellPadY;
+        for (const ref of refs) {
+          const size = stickySize(ref.scope);
+          stickies.push({
+            stickyId: ref.stickyId,
+            scope: ref.scope,
+            sliceId,
+            swimLaneId,
+            x: Math.round(midX - size.width / 2),
+            y: Math.round(cursorY),
+            width: size.width,
+            height: size.height
+          });
+          cursorY += size.height + SHEET_LAYOUT.stickyGap;
+        }
+      } else {
+        let cursorX = midX - content.width / 2;
+        for (const ref of refs) {
+          const size = stickySize(ref.scope);
+          stickies.push({
+            stickyId: ref.stickyId,
+            scope: ref.scope,
+            sliceId,
+            swimLaneId,
+            x: Math.round(cursorX),
+            y: Math.round(midY - size.height / 2),
+            width: size.width,
+            height: size.height
+          });
+          cursorX += size.width + SHEET_LAYOUT.stickyGap;
+        }
+      }
+    });
+  });
+  return {
+    chapterId,
+    chapter: { x: originX, y: originY, width: gridWidth, height: gridHeight },
+    columns: columnLayouts,
+    rows: rowLayouts,
+    stickies
+  };
+}
+// ../packages/canvas-model/src/reflow.ts
+var REFLOW_ORIGIN = Symbol("sheet-reflow");
+var CHAPTERS_SCOPE2 = "chapters";
+var SLICES_SCOPE3 = "slices";
+var SWIM_LANES_SCOPE2 = "swimLanes";
+var STICKY_SCOPES = [
+  "commands",
+  "events",
+  "readModels",
+  "screens",
+  "processors",
+  "externalEvents",
+  "scenarios"
+];
+function setIfChanged(m, key, val) {
+  if (m.get(key) !== val)
+    m.set(key, val);
+}
+function applyBox(m, box, size = true) {
+  if (!m)
+    return;
+  setIfChanged(m, "x", box.x);
+  setIfChanged(m, "y", box.y);
+  if (size) {
+    setIfChanged(m, "width", box.width);
+    setIfChanged(m, "height", box.height);
+  }
+}
+function reflowAllSheets(doc, origin = REFLOW_ORIGIN) {
+  const chapters = getScopeMap(doc, CHAPTERS_SCOPE2);
+  if (chapters.size === 0)
+    return;
+  doc.transact(() => {
+    for (const chapterId of chapters.keys())
+      ensureSheet(doc, chapterId);
+    const slices = getScopeMap(doc, SLICES_SCOPE3);
+    const lanes = getScopeMap(doc, SWIM_LANES_SCOPE2);
+    const stickyMaps = STICKY_SCOPES.map((s) => getScopeMap(doc, s));
+    for (const chapterId of getGridMap(doc).keys()) {
+      pruneOrphanCellRefs(doc, chapterId);
+      const layout = computeSheetLayout(doc, chapterId);
+      if (!layout)
+        continue;
+      const ch = chapters.get(chapterId);
+      if (ch) {
+        setIfChanged(ch, "width", layout.chapter.width);
+        setIfChanged(ch, "height", layout.chapter.height);
+      }
+      for (const col of layout.columns)
+        applyBox(slices.get(col.sliceId), col);
+      for (const row of layout.rows)
+        applyBox(lanes.get(row.swimLaneId), row);
+      const scenarioOrder = new Map;
+      for (const s of layout.stickies) {
+        const map = stickyMaps[STICKY_SCOPES.indexOf(s.scope)];
+        const entry = map?.get(s.stickyId);
+        applyBox(entry, s, false);
+        if (s.scope === "scenarios" && entry) {
+          if (entry.get("sliceId") !== s.sliceId)
+            entry.set("sliceId", s.sliceId);
+          const idx = scenarioOrder.get(s.sliceId) ?? 0;
+          setIfChanged(entry, "order", idx);
+          scenarioOrder.set(s.sliceId, idx + 1);
+        }
+      }
+    }
+  }, origin);
+}
+// ../packages/canvas-model/src/lanes.ts
+var LANE_KINDS = ["actor", "interaction", "swimlane", "specification"];
+var LANE_ELEMENT_SCOPES = {
+  actor: ["screens", "processors"],
+  interaction: ["commands", "readModels"],
+  swimlane: ["events", "externalEvents"],
+  specification: ["scenarios"]
+};
+function isLaneKind(v) {
+  return typeof v === "string" && LANE_KINDS.includes(v);
+}
+function laneAllows(kind, scope) {
+  if (!isLaneKind(kind))
+    return false;
+  return LANE_ELEMENT_SCOPES[kind].includes(scope);
+}
 // src/lib/resolve-model.ts
 function resolveModelId(flagValue) {
   if (flagValue)
@@ -4239,6 +4858,1158 @@ function registerSnapshotCommands(program) {
   });
 }
 
+// src/commands/sheet.ts
+import * as fs5 from "node:fs";
+import * as path5 from "node:path";
+
+// src/lib/sheet-render.ts
+var SCOPE_TAG = {
+  commands: "cmd",
+  events: "evt",
+  readModels: "rm",
+  screens: "scr",
+  processors: "prc",
+  externalEvents: "ext",
+  scenarios: "scn"
+};
+var LEGEND = "tags: cmd command · evt event · rm read-model · scr screen · prc processor · ext external-event · scn scenario  ( * = linked copy · † = has note )";
+var ORIGINAL_ID_KEY2 = {
+  events: "originalEventStickyId",
+  readModels: "originalReadModelStickyId",
+  screens: "originalScreenId",
+  externalEvents: "originalExternalEventId"
+};
+var EMPTY = "—";
+var DEFAULTS = { maxColWidth: 40, widthBudget: 120 };
+function colLabel(i) {
+  let n = i;
+  let s = "";
+  do {
+    s = String.fromCharCode(65 + n % 26) + s;
+    n = Math.floor(n / 26) - 1;
+  } while (n >= 0);
+  return s;
+}
+function wrap(text, width) {
+  if (text.length <= width)
+    return [text];
+  const lines = [];
+  let cur = "";
+  for (const word of text.split(" ")) {
+    if (word.length > width) {
+      if (cur) {
+        lines.push(cur);
+        cur = "";
+      }
+      let rest = word;
+      while (rest.length > width) {
+        lines.push(rest.slice(0, width));
+        rest = rest.slice(width);
+      }
+      cur = rest;
+    } else if (!cur) {
+      cur = word;
+    } else if (cur.length + 1 + word.length <= width) {
+      cur += " " + word;
+    } else {
+      lines.push(cur);
+      cur = word;
+    }
+  }
+  if (cur)
+    lines.push(cur);
+  return lines;
+}
+function entityName(doc, scope2, id) {
+  const e = getEntry(doc, scope2, id);
+  return e?.name?.trim() || "(unnamed)";
+}
+function elementText(doc, ref) {
+  const tag = SCOPE_TAG[ref.scope] ?? ref.scope;
+  const e = getEntry(doc, ref.scope, ref.stickyId);
+  const originalKey = ORIGINAL_ID_KEY2[ref.scope];
+  if (e?.isLinkedCopy && originalKey && typeof e[originalKey] === "string") {
+    return `${tag} ${entityName(doc, ref.scope, e[originalKey])} *`;
+  }
+  return `${tag} ${entityName(doc, ref.scope, ref.stickyId)}`;
+}
+function pad(s, width) {
+  return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+var NOTE = "†";
+function resolve4(doc, chapterId) {
+  const structure = readSheet(doc, chapterId);
+  if (!structure)
+    return;
+  const { columns, rows, cells } = structure;
+  const notes = readCellNotes(doc, chapterId);
+  const cols = columns.map((sliceId, i) => ({
+    label: colLabel(i),
+    name: entityName(doc, "slices", sliceId),
+    note: Boolean(getEntry(doc, "slices", sliceId)?.note)
+  }));
+  const lanes2 = rows.map((swimLaneId, i) => {
+    const e = getEntry(doc, "swimLanes", swimLaneId);
+    return { label: String(i + 1), name: e?.name?.trim() || "(unnamed)", kind: e?.laneKind ?? "?", note: Boolean(e?.note) };
+  });
+  const elems = columns.map((sliceId) => rows.map((swimLaneId) => (cells[cellKey(sliceId, swimLaneId)] ?? []).map((r) => elementText(doc, r))));
+  const cellNote = columns.map((sliceId) => rows.map((swimLaneId) => Boolean(notes[cellKey(sliceId, swimLaneId)])));
+  return {
+    title: entityName(doc, "chapters", chapterId),
+    columns: cols,
+    rows: lanes2,
+    elems,
+    cellNote,
+    empty: columns.length === 0 && rows.length === 0
+  };
+}
+function rowLabel(r) {
+  const base = r.name.toLowerCase() === r.kind.toLowerCase() ? `${r.label} ${r.name}` : `${r.label} ${r.name} (${r.kind})`;
+  return r.note ? `${base} ${NOTE}` : base;
+}
+function header(r) {
+  return `Sheet "${r.title}"  (${r.columns.length} slices × ${r.rows.length} lanes)`;
+}
+function cellLines(elems, width, hasNote) {
+  const lines = elems.length === 0 ? [EMPTY] : (() => {
+    const joined = elems.join(" · ");
+    return joined.length <= width ? [joined] : elems.flatMap((e) => wrap(e, width));
+  })();
+  if (hasNote)
+    lines[lines.length - 1] = `${lines[lines.length - 1]} ${NOTE}`;
+  return lines;
+}
+function colHead(c) {
+  return c.note ? `${c.label} ${c.name} ${NOTE}` : `${c.label} ${c.name}`;
+}
+function renderTable(r, opts) {
+  const gutter = Math.max(...r.rows.map(rowLabel).map((s) => s.length), 0);
+  const colWidths = r.columns.map((c, ci) => {
+    const widest = Math.max(colHead(c).length, ...r.elems[ci].map((cell, ri) => Math.max(0, ...cell.map((e) => e.length)) + (r.cellNote[ci][ri] ? 2 : 0)), EMPTY.length);
+    return Math.min(widest, opts.maxColWidth + 2);
+  });
+  const totalWidth = gutter + colWidths.reduce((a, w) => a + w + 2, 0);
+  const lines = [header(r), LEGEND, ""];
+  const headCells = r.columns.map((c, ci) => wrap(colHead(c), colWidths[ci]));
+  const headHeight = Math.max(...headCells.map((h) => h.length));
+  for (let i = 0;i < headHeight; i += 1) {
+    lines.push(pad("", gutter) + "  " + r.columns.map((_, ci) => pad(headCells[ci][i] ?? "", colWidths[ci])).join("  "));
+  }
+  lines.push("─".repeat(totalWidth));
+  r.rows.forEach((row, ri) => {
+    const cellsLines = r.columns.map((_, ci) => cellLines(r.elems[ci][ri], colWidths[ci], r.cellNote[ci][ri]));
+    const rowHeight = Math.max(...cellsLines.map((cl) => cl.length));
+    for (let i = 0;i < rowHeight; i += 1) {
+      const label = i === 0 ? rowLabel(row) : "";
+      const body = r.columns.map((_, ci) => pad(cellsLines[ci][i] ?? "", colWidths[ci])).join("  ");
+      lines.push(pad(label, gutter) + "  " + body);
+    }
+    if (ri < r.rows.length - 1)
+      lines.push("┈".repeat(totalWidth));
+  });
+  return { text: lines.join(`
+`), width: totalWidth };
+}
+function renderListing(r) {
+  const lines = [header(r), LEGEND, ""];
+  r.columns.forEach((c, ci) => {
+    lines.push(`${c.label} "${c.name}"${c.note ? ` ${NOTE}` : ""}`);
+    let any = false;
+    r.rows.forEach((row, ri) => {
+      const elems = r.elems[ci][ri];
+      const noted = r.cellNote[ci][ri];
+      if (elems.length === 0 && !noted)
+        return;
+      any = true;
+      const addr = `${c.label}${row.label}`;
+      const mark = noted ? ` ${NOTE}` : "";
+      if (elems.length <= 1) {
+        lines.push(`  ${addr}  ${elems[0] ?? EMPTY}  [${row.kind}]${mark}`);
+      } else {
+        lines.push(`  ${addr}  [${row.kind}]${mark}`);
+        elems.forEach((e, i) => lines.push(`    ${addr}.${i + 1}  ${e}`));
+      }
+    });
+    if (!any)
+      lines.push("  (empty)");
+    lines.push("");
+  });
+  return lines.join(`
+`).trimEnd();
+}
+function renderSheetOverview(doc, chapterId, options = {}) {
+  const opts = { ...DEFAULTS, ...options };
+  const r = resolve4(doc, chapterId);
+  if (!r)
+    return;
+  if (r.empty)
+    return `${header(r)}
+
+  (empty sheet)`;
+  const table = renderTable(r, opts);
+  return table.width <= opts.widthBudget ? table.text : renderListing(r);
+}
+
+// src/lib/sheet-address.ts
+class SheetAddressError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SheetAddressError";
+  }
+}
+function name(doc, scope2, id) {
+  return getEntry(doc, scope2, id)?.name?.trim() || "(unnamed)";
+}
+function colIndexFromLabel(label) {
+  if (!/^[A-Za-z]+$/.test(label))
+    return -1;
+  let n = 0;
+  for (const ch of label.toUpperCase())
+    n = n * 26 + (ch.charCodeAt(0) - 64);
+  return n - 1;
+}
+function resolveSheet2(doc, ref) {
+  const grid2 = getGridMap(doc);
+  const ids = [...grid2.keys()];
+  if (ids.length === 0)
+    throw new SheetAddressError("This model has no sheets.");
+  const done = (chapterId) => ({ chapterId, structure: readSheet(doc, chapterId) });
+  if (ref && grid2.has(ref))
+    return done(ref);
+  if (!ref) {
+    if (ids.length === 1)
+      return done(ids[0]);
+    const list = ids.map((id) => `"${name(doc, "chapters", id)}"`).join(", ");
+    throw new SheetAddressError(`Multiple sheets — name one. Available: ${list}`);
+  }
+  const lower = ref.toLowerCase();
+  const matches = ids.filter((id) => name(doc, "chapters", id).toLowerCase() === lower);
+  if (matches.length === 0) {
+    const list = ids.map((id) => `"${name(doc, "chapters", id)}"`).join(", ") || "(none)";
+    throw new SheetAddressError(`No sheet named "${ref}". Available: ${list}`);
+  }
+  if (matches.length > 1)
+    throw new SheetAddressError(`Ambiguous sheet name "${ref}" — pass the chapterId instead.`);
+  return done(matches[0]);
+}
+function resolveColumn(doc, s, ref) {
+  const { columns } = s.structure;
+  const make = (index) => ({ sliceId: columns[index], index, label: labelOf(index) });
+  if (columns.includes(ref))
+    return make(columns.indexOf(ref));
+  const byLabel = colIndexFromLabel(ref);
+  if (byLabel >= 0 && byLabel < columns.length)
+    return make(byLabel);
+  const lower = ref.toLowerCase();
+  const hits = columns.filter((id) => name(doc, "slices", id).toLowerCase() === lower);
+  if (hits.length === 1)
+    return make(columns.indexOf(hits[0]));
+  if (hits.length > 1)
+    throw new SheetAddressError(`Ambiguous column name "${ref}" — use its letter instead.`);
+  throw new SheetAddressError(byLabel >= 0 ? `No column "${ref}" — not a slice name, and column ${ref.toUpperCase()} is out of range (sheet has ${columns.length} columns).` : `No column named "${ref}".`);
+}
+function resolveRow(doc, s, ref) {
+  const { rows } = s.structure;
+  const make = (index) => ({ swimLaneId: rows[index], index, label: String(index + 1) });
+  if (rows.includes(ref))
+    return make(rows.indexOf(ref));
+  const numeric = /^\d+$/.test(ref);
+  if (numeric) {
+    const index = parseInt(ref, 10) - 1;
+    if (index >= 0 && index < rows.length)
+      return make(index);
+  }
+  const lower = ref.toLowerCase();
+  const hits = rows.filter((id) => name(doc, "swimLanes", id).toLowerCase() === lower);
+  if (hits.length === 1)
+    return make(rows.indexOf(hits[0]));
+  if (hits.length > 1)
+    throw new SheetAddressError(`Ambiguous row name "${ref}" — use its number instead.`);
+  throw new SheetAddressError(numeric ? `No row "${ref}" — not a lane name, and row ${ref} is out of range (sheet has ${rows.length} rows).` : `No row named "${ref}".`);
+}
+function labelOf(index) {
+  let n = index;
+  let str = "";
+  do {
+    str = String.fromCharCode(65 + n % 26) + str;
+    n = Math.floor(n / 26) - 1;
+  } while (n >= 0);
+  return str;
+}
+function parseCellAddress(addr) {
+  const m = /^([A-Za-z]+)(\d+)(?:\.(\d+))?$/.exec(addr.trim());
+  if (!m)
+    throw new SheetAddressError(`"${addr}" is not a cell address (expected e.g. B2 or B2.1).`);
+  return { colLabel: m[1], rowNum: parseInt(m[2], 10), ordinal: m[3] ? parseInt(m[3], 10) : undefined };
+}
+function resolveCell(doc, s, addr) {
+  const { colLabel: colLabel2, rowNum } = parseCellAddress(addr);
+  const col = resolveColumn(doc, s, colLabel2);
+  const row = resolveRow(doc, s, String(rowNum));
+  const refs = (s.structure.cells[cellKey(col.sliceId, row.swimLaneId)] ?? []).map((r) => ({
+    stickyId: r.stickyId,
+    scope: r.scope
+  }));
+  return {
+    sliceId: col.sliceId,
+    swimLaneId: row.swimLaneId,
+    colIndex: col.index,
+    rowIndex: row.index,
+    address: `${col.label}${row.label}`,
+    refs
+  };
+}
+function resolveElement(doc, s, addr) {
+  const { ordinal } = parseCellAddress(addr);
+  const cell = resolveCell(doc, s, addr);
+  if (cell.refs.length === 0)
+    throw new SheetAddressError(`Cell ${cell.address} is empty.`);
+  let index;
+  if (ordinal === undefined) {
+    if (cell.refs.length > 1) {
+      throw new SheetAddressError(`Cell ${cell.address} holds ${cell.refs.length} elements — address one as ${cell.address}.1 … ${cell.address}.${cell.refs.length}.`);
+    }
+    index = 0;
+  } else {
+    index = ordinal - 1;
+    if (index < 0 || index >= cell.refs.length) {
+      throw new SheetAddressError(`Cell ${cell.address} has no element #${ordinal} (it holds ${cell.refs.length}).`);
+    }
+  }
+  const ref = cell.refs[index];
+  return {
+    stickyId: ref.stickyId,
+    scope: ref.scope,
+    sliceId: cell.sliceId,
+    swimLaneId: cell.swimLaneId,
+    ordinal: index + 1,
+    address: `${cell.address}.${index + 1}`
+  };
+}
+
+// src/commands/sheet.ts
+var TYPE_LABEL = {
+  commands: "command",
+  events: "event",
+  readModels: "readmodel",
+  screens: "screen",
+  processors: "processor",
+  externalEvents: "external-event",
+  scenarios: "scenario"
+};
+var ELEMENT_TYPES = ["command", "event", "readmodel", "screen", "processor", "external-event", "scenario"];
+var FLOW_TYPE = {
+  commands: { events: "CommandToEvent", externalEvents: "CommandToExternalEvent" },
+  events: { readModels: "EventToReadModel" },
+  readModels: { screens: "ReadModelToScreen", processors: "ReadModelToProcessor" },
+  screens: { commands: "ScreenToCommand" },
+  processors: { commands: "ProcessorToCommand" },
+  externalEvents: { processors: "ExternalEventToProcessor", screens: "ExternalEventToScreen" }
+};
+var SRC_HANDLE = {
+  commands: "bottom-source",
+  events: "top-source",
+  readModels: "top-source",
+  screens: "bottom-source",
+  processors: "bottom-source",
+  externalEvents: "top-source"
+};
+var TGT_HANDLE = {
+  commands: "top-target",
+  events: "top-target",
+  readModels: "bottom-target",
+  screens: "bottom-target",
+  processors: "bottom-target",
+  externalEvents: "top-target"
+};
+var LINKED_COPY = {
+  events: { idKey: "eventStickyId", originalIdKey: "originalEventStickyId" },
+  readModels: { idKey: "readModelStickyId", originalIdKey: "originalReadModelStickyId" },
+  screens: { idKey: "screenId", originalIdKey: "originalScreenId" },
+  externalEvents: { idKey: "externalEventId", originalIdKey: "originalExternalEventId" }
+};
+function nameOf(doc, scope2, id) {
+  return getEntry(doc, scope2, id)?.name?.trim() || "(unnamed)";
+}
+function colLabel2(i) {
+  let n = i;
+  let s = "";
+  do {
+    s = String.fromCharCode(65 + n % 26) + s;
+    n = Math.floor(n / 26) - 1;
+  } while (n >= 0);
+  return s;
+}
+async function runWrite(opts, fn) {
+  const modelId = resolveModelId(opts.model);
+  try {
+    const out = await withDoc(modelId, (doc) => {
+      const s = resolveSheet2(doc, opts.sheet);
+      const result = fn(doc, s, modelId);
+      reflowAllSheets(doc);
+      return result;
+    });
+    console.log(out);
+  } catch (err) {
+    if (err instanceof SheetAddressError) {
+      console.error(err.message);
+      process.exit(2);
+    }
+    throw err;
+  }
+}
+function atIndex(at) {
+  if (at === undefined)
+    return;
+  const n = parseInt(at, 10);
+  if (!Number.isFinite(n) || n < 1)
+    return;
+  return n - 1;
+}
+function parsePayload(nameOrJson) {
+  const trimmed = nameOrJson.trim();
+  if (trimmed.startsWith("{")) {
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (err) {
+      throw new SheetAddressError(`Invalid JSON payload: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object")
+      throw new SheetAddressError("Payload must be a JSON object or a bare name.");
+    return parsed;
+  }
+  return { name: trimmed };
+}
+function rejectLane(doc, swimLaneId, rowIndex, kind, type) {
+  const allowed = (LANE_ELEMENT_SCOPES[kind] ?? []).map((sc) => TYPE_LABEL[sc] ?? sc).join(", ");
+  throw new SheetAddressError(`Lane "${nameOf(doc, "swimLanes", swimLaneId)}" (row ${rowIndex + 1}, kind=${kind}) accepts ${allowed || "(nothing)"}, not ${type}.`);
+}
+function insertColumn(doc, s, modelId, name2, at) {
+  const id = crypto.randomUUID();
+  const d = ELEMENT_DIMENSIONS.slice;
+  const v = validateEntry("slices", { name: name2, x: 0, y: 0, width: d.width, height: d.height });
+  if (!v.ok)
+    throw new SheetAddressError(`Invalid slice: ${v.issues.join("; ")}`);
+  doc.transact(() => {
+    getScopeMap(doc, "slices").set(id, deepToY({ ...v.data, sliceId: id, modelId }));
+    addColumn(doc, s.chapterId, id, at);
+  });
+  const idx = readSheet(doc, s.chapterId).columns.indexOf(id);
+  return `${colLabel2(idx)}  "${name2}"  ${id}`;
+}
+function insertLane(doc, s, modelId, kind, name2, at) {
+  const id = crypto.randomUUID();
+  const d = ELEMENT_DIMENSIONS.swimLane;
+  const v = validateEntry("swimLanes", { name: name2, laneKind: kind, x: 0, y: 0, width: d.width, height: d.height });
+  if (!v.ok)
+    throw new SheetAddressError(`Invalid lane: ${v.issues.join("; ")}`);
+  doc.transact(() => {
+    getScopeMap(doc, "swimLanes").set(id, deepToY({ ...v.data, swimLaneId: id, modelId }));
+    addRow(doc, s.chapterId, id, at);
+  });
+  const idx = readSheet(doc, s.chapterId).rows.indexOf(id);
+  return `${idx + 1}  "${name2}" (${kind})  ${id}`;
+}
+function insertElement(doc, s, modelId, type, cellArg, nameOrJson) {
+  const cell = resolveCell(doc, s, cellArg);
+  const kind = getEntry(doc, "swimLanes", cell.swimLaneId)?.laneKind ?? "?";
+  const payload = parsePayload(nameOrJson);
+  const id = crypto.randomUUID();
+  if (type === "scenario") {
+    if (!laneAllows(kind, "scenarios"))
+      rejectLane(doc, cell.swimLaneId, cell.rowIndex, kind, "scenario");
+    if (!payload.name)
+      throw new SheetAddressError("A scenario needs a name.");
+    const entry2 = {
+      scenarioId: id,
+      modelId,
+      sliceId: cell.sliceId,
+      name: payload.name,
+      order: 0,
+      givenEntries: [],
+      whenEntries: [],
+      thenEntries: [],
+      x: 0,
+      y: 0,
+      width: SCENARIO_CARD.width,
+      height: SCENARIO_CARD.height
+    };
+    doc.transact(() => {
+      getScopeMap(doc, "scenarios").set(id, deepToY(entry2));
+      placeInCell(doc, s.chapterId, cell.sliceId, cell.swimLaneId, { stickyId: id, scope: "scenarios" });
+    });
+    return addressOf(doc, s, cell.sliceId, cell.swimLaneId, id, cell.address);
+  }
+  const meta = resolveType(type);
+  if (!laneAllows(kind, meta.scope))
+    rejectLane(doc, cell.swimLaneId, cell.rowIndex, kind, type);
+  const entry = { ...payload, x: 0, y: 0 };
+  enforceCanonicalSize(meta, entry);
+  const v = validateEntry(meta.scope, entry);
+  if (!v.ok)
+    throw new SheetAddressError(`Invalid ${type}: ${v.issues.join("; ")}`);
+  const final = { ...v.data, [meta.idKey]: id, modelId };
+  doc.transact(() => {
+    getScopeMap(doc, meta.scope).set(id, deepToY(final));
+    placeInCell(doc, s.chapterId, cell.sliceId, cell.swimLaneId, { stickyId: id, scope: meta.scope });
+  });
+  return addressOf(doc, s, cell.sliceId, cell.swimLaneId, id, cell.address);
+}
+function addressOf(doc, s, sliceId, swimLaneId, id, cellAddr) {
+  const refs = readSheet(doc, s.chapterId).cells[cellKey(sliceId, swimLaneId)] ?? [];
+  const ord = refs.findIndex((r) => r.stickyId === id) + 1;
+  return `${cellAddr}.${ord}  ${id}`;
+}
+function moveElement(doc, s, elAddr, toCell) {
+  const el = resolveElement(doc, s, elAddr);
+  const dest = resolveCell(doc, s, toCell);
+  const kind = getEntry(doc, "swimLanes", dest.swimLaneId)?.laneKind ?? "?";
+  if (!laneAllows(kind, el.scope))
+    rejectLane(doc, dest.swimLaneId, dest.rowIndex, kind, TYPE_LABEL[el.scope] ?? el.scope);
+  doc.transact(() => {
+    placeInCell(doc, s.chapterId, dest.sliceId, dest.swimLaneId, { stickyId: el.stickyId, scope: el.scope });
+  });
+  return addressOf(doc, s, dest.sliceId, dest.swimLaneId, el.stickyId, dest.address);
+}
+function reorderAxis(doc, s, ref, to) {
+  const toIndex = to - 1;
+  if (/^\d+$/.test(ref)) {
+    const row = resolveRow(doc, s, ref);
+    doc.transact(() => moveRow(doc, s.chapterId, row.swimLaneId, toIndex));
+    const idx = readSheet(doc, s.chapterId).rows.indexOf(row.swimLaneId);
+    return `row → ${idx + 1}`;
+  }
+  if (colIndexFromLabel(ref) >= 0 || s.structure.columns.length > 0) {
+    const col = resolveColumn(doc, s, ref);
+    doc.transact(() => moveColumn(doc, s.chapterId, col.sliceId, toIndex));
+    const idx = readSheet(doc, s.chapterId).columns.indexOf(col.sliceId);
+    return `column → ${colLabel2(idx)}`;
+  }
+  throw new SheetAddressError(`reorder takes a column letter (A) or row number (1), got "${ref}".`);
+}
+function removeTarget(doc, s, target) {
+  if (/^[A-Za-z]+\d+(\.\d+)?$/.test(target)) {
+    const el = resolveElement(doc, s, target);
+    doc.transact(() => {
+      removeSticky(doc, s.chapterId, el.stickyId);
+      getScopeMap(doc, el.scope).delete(el.stickyId);
+      cascadeStickyRemoval(doc, new Set([el.stickyId]));
+    });
+    return `removed ${el.address} (${TYPE_LABEL[el.scope] ?? el.scope})`;
+  }
+  if (/^\d+$/.test(target)) {
+    const row = resolveRow(doc, s, target);
+    const laneName = nameOf(doc, "swimLanes", row.swimLaneId);
+    const refs2 = s.structure.columns.flatMap((sliceId) => s.structure.cells[cellKey(sliceId, row.swimLaneId)] ?? []);
+    doc.transact(() => {
+      removeRow(doc, s.chapterId, row.swimLaneId);
+      getScopeMap(doc, "swimLanes").delete(row.swimLaneId);
+      for (const r of refs2)
+        getScopeMap(doc, r.scope).delete(r.stickyId);
+      cascadeStickyRemoval(doc, new Set(refs2.map((r) => r.stickyId)));
+    });
+    return `removed row ${row.label} "${laneName}" and its ${refs2.length} element(s)`;
+  }
+  const col = resolveColumn(doc, s, target);
+  const sliceName = nameOf(doc, "slices", col.sliceId);
+  const refs = s.structure.rows.flatMap((swimLaneId) => s.structure.cells[cellKey(col.sliceId, swimLaneId)] ?? []);
+  doc.transact(() => {
+    removeColumn(doc, s.chapterId, col.sliceId);
+    getScopeMap(doc, "slices").delete(col.sliceId);
+    for (const r of refs)
+      getScopeMap(doc, r.scope).delete(r.stickyId);
+    cascadeStickyRemoval(doc, new Set(refs.map((r) => r.stickyId)));
+  });
+  return `removed column ${col.label} "${sliceName}" and its ${refs.length} element(s)`;
+}
+function updateElement(doc, s, modelId, address, json) {
+  const el = resolveElement(doc, s, address);
+  let parsed;
+  try {
+    const p = JSON.parse(json);
+    if (!p || typeof p !== "object")
+      throw new Error("payload must be a JSON object");
+    parsed = p;
+  } catch (err) {
+    throw new SheetAddressError(`Invalid JSON: ${err.message}`);
+  }
+  const map = getScopeMap(doc, el.scope);
+  const existing = getEntry(doc, el.scope, el.stickyId) ?? {};
+  if (!isValidatedScope(el.scope)) {
+    const merged = { ...existing, ...parsed, scenarioId: el.stickyId, modelId, sliceId: existing.sliceId };
+    doc.transact(() => {
+      map.delete(el.stickyId);
+      map.set(el.stickyId, deepToY(merged));
+    });
+    return `updated ${el.address}`;
+  }
+  const meta = resolveScope(el.scope);
+  const entry = { x: 0, y: 0, ...parsed };
+  enforceCanonicalSize(meta, entry);
+  const v = validateEntry(el.scope, entry);
+  if (!v.ok)
+    throw new SheetAddressError(`Invalid ${TYPE_LABEL[el.scope] ?? el.scope}: ${v.issues.join("; ")}`);
+  const final = { ...v.data, [meta.idKey]: el.stickyId, modelId };
+  doc.transact(() => {
+    map.delete(el.stickyId);
+    map.set(el.stickyId, deepToY(final));
+  });
+  return `updated ${el.address}`;
+}
+function flowBetween(doc, s, modelId, fromAddr, toAddr, typeOverride) {
+  const from = resolveElement(doc, s, fromAddr);
+  const to = resolveElement(doc, s, toAddr);
+  const inferred = FLOW_TYPE[from.scope]?.[to.scope];
+  if (!inferred) {
+    throw new SheetAddressError(`No valid flow from ${TYPE_LABEL[from.scope] ?? from.scope} to ${TYPE_LABEL[to.scope] ?? to.scope}.`);
+  }
+  if (typeOverride && typeOverride !== inferred) {
+    throw new SheetAddressError(`Flow ${from.address}→${to.address} is ${inferred}, not ${typeOverride}.`);
+  }
+  const id = crypto.randomUUID();
+  const entry = {
+    flowId: id,
+    modelId,
+    flowType: inferred,
+    sourceId: from.stickyId,
+    targetId: to.stickyId,
+    sourceHandle: SRC_HANDLE[from.scope],
+    targetHandle: TGT_HANDLE[to.scope]
+  };
+  const v = validateEntry("flows", entry);
+  if (!v.ok)
+    throw new SheetAddressError(`Invalid flow: ${v.issues.join("; ")}`);
+  doc.transact(() => {
+    getScopeMap(doc, "flows").set(id, deepToY({ ...v.data, flowId: id }));
+  });
+  return `${from.address} → ${to.address}  (${inferred})  ${id}`;
+}
+function sliceFlowHandle(side, dir, sliceId) {
+  return `sf:slice:${side}:${dir}:${sliceId}`;
+}
+function sheetEdgeHandle(side, dir) {
+  return `sf:sheet:${side}:${dir}`;
+}
+function resolveAnchor(doc, sheet, dir, col, side) {
+  const flag = dir === "source" ? "from" : "to";
+  const sheetName = nameOf(doc, "chapters", sheet.chapterId);
+  if (col !== undefined) {
+    const c = resolveColumn(doc, sheet, col);
+    const s2 = side ?? (dir === "source" ? "bottom" : "top");
+    if (s2 !== "top" && s2 !== "bottom") {
+      throw new SheetAddressError(`--${flag}-side must be top|bottom for a slice anchor, got "${s2}".`);
+    }
+    return { handle: sliceFlowHandle(s2, dir, c.sliceId), label: `"${sheetName}" ${c.label} (${s2})` };
+  }
+  const s = side ?? (dir === "source" ? "right" : "left");
+  if (s !== "left" && s !== "right") {
+    throw new SheetAddressError(`--${flag}-side must be left|right for a sheet-edge anchor, got "${s}".`);
+  }
+  return { handle: sheetEdgeHandle(s, dir), label: `"${sheetName}" (${s} edge)` };
+}
+function connectSheets(doc, modelId, fromRef, toRef, opts) {
+  const src = resolveSheet2(doc, fromRef);
+  const dst = resolveSheet2(doc, toRef);
+  if (src.chapterId === dst.chapterId) {
+    throw new SheetAddressError("Connect joins two different sheets — source and target are the same sheet.");
+  }
+  const from = resolveAnchor(doc, src, "source", opts.from, opts.fromSide);
+  const to = resolveAnchor(doc, dst, "target", opts.to, opts.toSide);
+  const id = crypto.randomUUID();
+  const entry = {
+    sheetFlowId: id,
+    sourceChapterId: src.chapterId,
+    sourceHandle: from.handle,
+    targetChapterId: dst.chapterId,
+    targetHandle: to.handle
+  };
+  const v = validateEntry("sheetFlows", entry);
+  if (!v.ok)
+    throw new SheetAddressError(`Invalid sheet flow: ${v.issues.join("; ")}`);
+  doc.transact(() => {
+    getScopeMap(doc, "sheetFlows").set(id, deepToY({ ...v.data, sheetFlowId: id, modelId }));
+  });
+  return `${from.label} → ${to.label}  ${id}`;
+}
+function canonicalId(doc, scope2, id) {
+  const e = getEntry(doc, scope2, id);
+  const key = LINKED_COPY[scope2]?.originalIdKey;
+  if (e?.isLinkedCopy && key && typeof e[key] === "string")
+    return e[key];
+  return id;
+}
+function copyElement(doc, s, modelId, srcAddr, toCell) {
+  const src = resolveElement(doc, s, srcAddr);
+  const meta = LINKED_COPY[src.scope];
+  if (!meta) {
+    throw new SheetAddressError(`${TYPE_LABEL[src.scope] ?? src.scope} elements can't have linked copies (only events, read-models, screens, external-events).`);
+  }
+  const dest = resolveCell(doc, s, toCell);
+  const kind = getEntry(doc, "swimLanes", dest.swimLaneId)?.laneKind ?? "?";
+  if (!laneAllows(kind, src.scope))
+    rejectLane(doc, dest.swimLaneId, dest.rowIndex, kind, TYPE_LABEL[src.scope] ?? src.scope);
+  const originalId = canonicalId(doc, src.scope, src.stickyId);
+  const id = crypto.randomUUID();
+  const dim = FIXED_SIZE_DIM(src.scope);
+  doc.transact(() => {
+    getScopeMap(doc, src.scope).set(id, deepToY({ [meta.idKey]: id, modelId, name: "", x: 0, y: 0, width: dim.width, height: dim.height, isLinkedCopy: true, [meta.originalIdKey]: originalId }));
+    placeInCell(doc, s.chapterId, dest.sliceId, dest.swimLaneId, { stickyId: id, scope: src.scope });
+  });
+  return addressOf(doc, s, dest.sliceId, dest.swimLaneId, id, dest.address);
+}
+function FIXED_SIZE_DIM(scope2) {
+  const meta = resolveScope(scope2);
+  const entry = {};
+  if (meta)
+    enforceCanonicalSize(meta, entry);
+  return { width: entry.width ?? 160, height: entry.height ?? 100 };
+}
+function patchEntityNote(doc, scope2, id, text) {
+  doc.transact(() => {
+    const e = getScopeMap(doc, scope2).get(id);
+    if (!e)
+      return;
+    if (text)
+      e.set("note", text);
+    else
+      e.delete("note");
+  });
+}
+function noteTarget(doc, s, target, text) {
+  const t = text.trim();
+  const verb = t ? "noted" : "cleared note on";
+  if (/^[A-Za-z]+\d+\.\d+$/.test(target)) {
+    throw new SheetAddressError(`Notes attach to a cell (B2), column (A), or lane (2) — not an element (${target}).`);
+  }
+  if (/^[A-Za-z]+\d+$/.test(target)) {
+    const cell = resolveCell(doc, s, target);
+    setCellNote(doc, s.chapterId, cell.sliceId, cell.swimLaneId, t);
+    return `${verb} cell ${cell.address}`;
+  }
+  if (/^\d+$/.test(target)) {
+    const row = resolveRow(doc, s, target);
+    patchEntityNote(doc, "swimLanes", row.swimLaneId, t);
+    return `${verb} lane ${row.label} "${nameOf(doc, "swimLanes", row.swimLaneId)}"`;
+  }
+  const col = resolveColumn(doc, s, target);
+  patchEntityNote(doc, "slices", col.sliceId, t);
+  return `${verb} column ${col.label} "${nameOf(doc, "slices", col.sliceId)}"`;
+}
+function buildFromSpec(doc, modelId, nameArg, spec) {
+  if (!spec || typeof spec !== "object")
+    throw new SheetAddressError("Spec must be a JSON object.");
+  const s = spec;
+  const sheetName = String(nameArg ?? s.name ?? s.sheet ?? "Sheet");
+  const cols = (Array.isArray(s.columns) ? s.columns : []).map((c) => typeof c === "string" ? { name: c } : c);
+  const rows = (Array.isArray(s.rows) ? s.rows : []).map((r) => {
+    const o = r;
+    return { name: o.name, kind: o.kind ?? o.laneKind ?? "", note: o.note };
+  });
+  if (cols.length === 0)
+    throw new SheetAddressError('Spec needs a non-empty "columns" array.');
+  if (rows.length === 0)
+    throw new SheetAddressError('Spec needs a non-empty "rows" array.');
+  for (const r of rows) {
+    if (!isLaneKind(r.kind))
+      throw new SheetAddressError(`Row "${r.name}" has invalid kind "${r.kind}".`);
+  }
+  const cells = s.cells && typeof s.cells === "object" ? s.cells : {};
+  const ops = [];
+  const count = {};
+  const scopeAt = {};
+  const cellOf = (addr) => {
+    const { colLabel: cl, rowNum } = parseCellAddress(addr);
+    const ci = colIndexFromLabel(cl);
+    const ri = rowNum - 1;
+    if (ci < 0 || ci >= cols.length)
+      throw new SheetAddressError(`Cell ${addr}: column out of range.`);
+    if (ri < 0 || ri >= rows.length)
+      throw new SheetAddressError(`Cell ${addr}: row out of range.`);
+    return { ci, ri, kind: rows[ri].kind, cl, rowNum };
+  };
+  for (const [addr, elems] of Object.entries(cells)) {
+    const { ci, ri, kind, cl, rowNum } = cellOf(addr);
+    for (const el of elems) {
+      const address = `${cl}${rowNum}.${count[`${cl}${rowNum}`] = (count[`${cl}${rowNum}`] ?? 0) + 1}`;
+      if (el.type === "scenario") {
+        if (!laneAllows(kind, "scenarios"))
+          throw new SheetAddressError(`Cell ${addr}: ${kind} lane can't hold a scenario.`);
+        if (!el.name)
+          throw new SheetAddressError(`Cell ${addr}: scenario needs a name.`);
+        ops.push({ kind: "scenario", ci, ri, name: String(el.name), address });
+        scopeAt[address] = "scenarios";
+        continue;
+      }
+      const meta = resolveType(el.type);
+      if (!meta)
+        throw new SheetAddressError(`Cell ${addr}: unknown element type "${el.type}".`);
+      if (!laneAllows(kind, meta.scope))
+        throw new SheetAddressError(`Cell ${addr}: ${kind} lane can't hold a ${el.type}.`);
+      const { type: _t, ...rest } = el;
+      const entry = { x: 0, y: 0, ...rest };
+      enforceCanonicalSize(meta, entry);
+      const v = validateEntry(meta.scope, entry);
+      if (!v.ok)
+        throw new SheetAddressError(`Cell ${addr} (${el.type}): ${v.issues.join("; ")}`);
+      ops.push({ kind: "sticky", ci, ri, scope: meta.scope, idKey: meta.idKey, data: v.data, address });
+      scopeAt[address] = meta.scope;
+    }
+  }
+  const specCopies = Array.isArray(s.copies) ? s.copies : [];
+  for (const c of specCopies) {
+    const { ci, ri, kind, cl, rowNum } = cellOf(c.at);
+    const meta = resolveType(c.type);
+    if (!meta || !(meta.scope in LINKED_COPY))
+      throw new SheetAddressError(`Copy at ${c.at}: "${c.type}" can't be a linked copy.`);
+    if (!laneAllows(kind, meta.scope))
+      throw new SheetAddressError(`Copy at ${c.at}: ${kind} lane can't hold a ${c.type}.`);
+    if (scopeAt[c.copyOf] !== meta.scope)
+      throw new SheetAddressError(`Copy at ${c.at}: copyOf ${c.copyOf} is not a ${c.type}.`);
+    const address = `${cl}${rowNum}.${count[`${cl}${rowNum}`] = (count[`${cl}${rowNum}`] ?? 0) + 1}`;
+    ops.push({ kind: "copy", ci, ri, scope: meta.scope, copyOf: c.copyOf, address });
+    scopeAt[address] = meta.scope;
+  }
+  const specFlows = Array.isArray(s.flows) ? s.flows : [];
+  for (const f of specFlows) {
+    const ss = scopeAt[f.from];
+    const ts = scopeAt[f.to];
+    if (!ss)
+      throw new SheetAddressError(`Flow: unknown source ${f.from}.`);
+    if (!ts)
+      throw new SheetAddressError(`Flow: unknown target ${f.to}.`);
+    const inferred = FLOW_TYPE[ss]?.[ts];
+    if (!inferred)
+      throw new SheetAddressError(`Flow ${f.from}→${f.to}: no valid flow from ${TYPE_LABEL[ss] ?? ss} to ${TYPE_LABEL[ts] ?? ts}.`);
+    if (f.type && f.type !== inferred)
+      throw new SheetAddressError(`Flow ${f.from}→${f.to} is ${inferred}, not ${f.type}.`);
+  }
+  const chapterId = crypto.randomUUID();
+  const idByAddress = {};
+  doc.transact(() => {
+    const cd = ELEMENT_DIMENSIONS.chapter;
+    getScopeMap(doc, "chapters").set(chapterId, deepToY({ chapterId, modelId, name: sheetName, x: 0, y: 0, width: cd.width, height: cd.height }));
+    ensureSheet(doc, chapterId);
+    const sd = ELEMENT_DIMENSIONS.slice;
+    const sliceIds = cols.map((c) => {
+      const id = crypto.randomUUID();
+      const entry = { sliceId: id, modelId, name: c.name, x: 0, y: 0, width: sd.width, height: sd.height };
+      if (c.status)
+        entry.status = c.status;
+      if (c.note)
+        entry.note = c.note;
+      getScopeMap(doc, "slices").set(id, deepToY(entry));
+      addColumn(doc, chapterId, id);
+      return id;
+    });
+    const ld = ELEMENT_DIMENSIONS.swimLane;
+    const laneIds = rows.map((r) => {
+      const id = crypto.randomUUID();
+      const entry = { swimLaneId: id, modelId, name: r.name, laneKind: r.kind, x: 0, y: 0, width: ld.width, height: ld.height };
+      if (r.note)
+        entry.note = r.note;
+      getScopeMap(doc, "swimLanes").set(id, deepToY(entry));
+      addRow(doc, chapterId, id);
+      return id;
+    });
+    for (const op of ops) {
+      if (op.kind === "copy")
+        continue;
+      const id = crypto.randomUUID();
+      if (op.kind === "scenario") {
+        getScopeMap(doc, "scenarios").set(id, deepToY({
+          scenarioId: id,
+          modelId,
+          sliceId: sliceIds[op.ci],
+          name: op.name,
+          order: 0,
+          givenEntries: [],
+          whenEntries: [],
+          thenEntries: [],
+          x: 0,
+          y: 0,
+          width: SCENARIO_CARD.width,
+          height: SCENARIO_CARD.height
+        }));
+        placeInCell(doc, chapterId, sliceIds[op.ci], laneIds[op.ri], { stickyId: id, scope: "scenarios" });
+      } else {
+        getScopeMap(doc, op.scope).set(id, deepToY({ ...op.data, [op.idKey]: id, modelId }));
+        placeInCell(doc, chapterId, sliceIds[op.ci], laneIds[op.ri], { stickyId: id, scope: op.scope });
+      }
+      idByAddress[op.address] = id;
+    }
+    for (const op of ops) {
+      if (op.kind !== "copy")
+        continue;
+      const meta = LINKED_COPY[op.scope];
+      const id = crypto.randomUUID();
+      const dim = FIXED_SIZE_DIM(op.scope);
+      getScopeMap(doc, op.scope).set(id, deepToY({ [meta.idKey]: id, modelId, name: "", x: 0, y: 0, width: dim.width, height: dim.height, isLinkedCopy: true, [meta.originalIdKey]: idByAddress[op.copyOf] }));
+      placeInCell(doc, chapterId, sliceIds[op.ci], laneIds[op.ri], { stickyId: id, scope: op.scope });
+      idByAddress[op.address] = id;
+    }
+    for (const f of specFlows) {
+      const fid = crypto.randomUUID();
+      const ss = scopeAt[f.from];
+      const ts = scopeAt[f.to];
+      getScopeMap(doc, "flows").set(fid, deepToY({ flowId: fid, modelId, flowType: FLOW_TYPE[ss][ts], sourceId: idByAddress[f.from], targetId: idByAddress[f.to], sourceHandle: SRC_HANDLE[ss], targetHandle: TGT_HANDLE[ts] }));
+    }
+    const specCellNotes = s.cellNotes && typeof s.cellNotes === "object" ? s.cellNotes : {};
+    for (const [addr, text] of Object.entries(specCellNotes)) {
+      const { colLabel: cl, rowNum } = parseCellAddress(addr);
+      const ci = colIndexFromLabel(cl);
+      const ri = rowNum - 1;
+      if (ci >= 0 && ci < cols.length && ri >= 0 && ri < rows.length && text) {
+        setCellNote(doc, chapterId, sliceIds[ci], laneIds[ri], text);
+      }
+    }
+  });
+  reflowAllSheets(doc);
+  const nElems = ops.length;
+  return `built sheet "${sheetName}" — ${cols.length} slices, ${rows.length} lanes, ${nElems} elements, ${specFlows.length} flows  ${chapterId}`;
+}
+function buildSheetJson(doc, s) {
+  const { columns, rows, cells } = s.structure;
+  const columnViews = columns.map((sliceId, i) => {
+    const e = getEntry(doc, "slices", sliceId);
+    return { label: colLabel2(i), name: e?.name ?? "(unnamed)", sliceId, status: e?.status ?? null, note: e?.note ?? null };
+  });
+  const rowViews = rows.map((swimLaneId, i) => {
+    const e = getEntry(doc, "swimLanes", swimLaneId);
+    return { label: String(i + 1), name: e?.name ?? "(unnamed)", laneKind: e?.laneKind ?? null, swimLaneId, note: e?.note ?? null };
+  });
+  const cellNotes = readCellNotes(doc, s.chapterId);
+  const cellNotesByAddr = {};
+  for (const [k, text] of Object.entries(cellNotes)) {
+    const [sliceId, swimLaneId] = k.split(":");
+    const ci = columns.indexOf(sliceId);
+    const ri = rows.indexOf(swimLaneId);
+    if (ci >= 0 && ri >= 0)
+      cellNotesByAddr[`${colLabel2(ci)}${ri + 1}`] = text;
+  }
+  const cellViews = {};
+  columns.forEach((sliceId, ci) => {
+    rows.forEach((swimLaneId, ri) => {
+      const refs = cells[cellKey(sliceId, swimLaneId)] ?? [];
+      if (refs.length === 0)
+        return;
+      cellViews[`${colLabel2(ci)}${ri + 1}`] = refs.map((r, k) => ({
+        address: `${colLabel2(ci)}${ri + 1}.${k + 1}`,
+        type: TYPE_LABEL[r.scope] ?? r.scope,
+        stickyId: r.stickyId,
+        name: nameOf(doc, r.scope, r.stickyId)
+      }));
+    });
+  });
+  return { sheet: nameOf(doc, "chapters", s.chapterId), chapterId: s.chapterId, columns: columnViews, rows: rowViews, cells: cellViews, cellNotes: cellNotesByAddr };
+}
+function buildCellView(doc, s, cellArg) {
+  const { ordinal } = parseCellAddress(cellArg);
+  const cell = resolveCell(doc, s, cellArg);
+  const slice = getEntry(doc, "slices", cell.sliceId);
+  const lane = getEntry(doc, "swimLanes", cell.swimLaneId);
+  let refs = cell.refs.map((r, i) => ({ ...r, ord: i + 1 }));
+  if (ordinal !== undefined) {
+    const one = refs[ordinal - 1];
+    if (!one)
+      throw new SheetAddressError(`Cell ${cell.address} has no element #${ordinal} (it holds ${refs.length}).`);
+    refs = [one];
+  }
+  const flows = getEntries(doc, "flows");
+  return {
+    cell: cell.address,
+    note: readCellNotes(doc, s.chapterId)[cellKey(cell.sliceId, cell.swimLaneId)] ?? null,
+    slice: { label: colLabel2(cell.colIndex), name: slice?.name ?? "(unnamed)", sliceId: cell.sliceId, note: slice?.note ?? null },
+    lane: { label: String(cell.rowIndex + 1), name: lane?.name ?? "(unnamed)", laneKind: lane?.laneKind ?? null, swimLaneId: cell.swimLaneId, note: lane?.note ?? null },
+    elements: refs.map((r) => ({
+      address: `${cell.address}.${r.ord}`,
+      type: TYPE_LABEL[r.scope] ?? r.scope,
+      ...getEntry(doc, r.scope, r.stickyId) ?? {},
+      outboundFlows: flows.filter((f) => f.sourceId === r.stickyId).map((f) => ({ flowType: f.flowType, to: endpointName(doc, f.targetId) })),
+      inboundFlows: flows.filter((f) => f.targetId === r.stickyId).map((f) => ({ flowType: f.flowType, from: endpointName(doc, f.sourceId) }))
+    }))
+  };
+}
+function endpointName(doc, id) {
+  if (!id)
+    return "(none)";
+  for (const scope2 of ["commands", "events", "readModels", "screens", "processors", "externalEvents"]) {
+    const e = getEntry(doc, scope2, id);
+    if (e) {
+      const key = ORIGINAL_ID_KEY_LOCAL[scope2];
+      const nm = e.isLinkedCopy && key && typeof e[key] === "string" ? nameOf(doc, scope2, e[key]) : nameOf(doc, scope2, id);
+      return `${TYPE_LABEL[scope2] ?? scope2} ${nm}`;
+    }
+  }
+  return id;
+}
+var ORIGINAL_ID_KEY_LOCAL = {
+  events: "originalEventStickyId",
+  readModels: "originalReadModelStickyId",
+  screens: "originalScreenId",
+  externalEvents: "originalExternalEventId"
+};
+function registerSheetCommands(program) {
+  const sheet = program.command("sheet").description("Work with sheets-mode models (grid of slices × lanes)");
+  sheet.command("show [sheet] [cell]").description("Render a sheet as a 2D grid; pass a cell (e.g. B2 or B2.1) to drill into it").option("--json", "Emit the lossless machine-readable structure instead of the 2D table").option("--model <id>", "Target model id (overrides .eventmodeler.json)").action(async (sheetRef, cellArg, opts) => {
+    const modelId = resolveModelId(opts.model);
+    if (cellArg === undefined && sheetRef !== undefined && /^[A-Za-z]+\d+(\.\d+)?$/.test(sheetRef)) {
+      cellArg = sheetRef;
+      sheetRef = undefined;
+    }
+    try {
+      const output = await withDoc(modelId, (doc) => {
+        const s = resolveSheet2(doc, sheetRef);
+        if (cellArg)
+          return JSON.stringify(buildCellView(doc, s, cellArg), null, 2);
+        if (opts.json)
+          return JSON.stringify(buildSheetJson(doc, s), null, 2);
+        return renderSheetOverview(doc, s.chapterId) ?? "(empty sheet)";
+      });
+      console.log(output);
+    } catch (err) {
+      if (err instanceof SheetAddressError) {
+        console.error(err.message);
+        process.exit(2);
+      }
+      throw err;
+    }
+  });
+  sheet.command("new [name]").description("Create a new sheet — empty, or scaffolded whole from --from <file>").option("--from <file>", "Build the whole sheet from a JSON spec (mirrors `show --json`)").option("--model <id>", "Target model id").action(async (name2, opts) => {
+    const modelId = resolveModelId(opts.model);
+    try {
+      if (opts.from) {
+        const filePath = path5.resolve(process.cwd(), opts.from);
+        if (!fs5.existsSync(filePath))
+          throw new SheetAddressError(`Spec file not found: ${opts.from}`);
+        let spec;
+        try {
+          spec = JSON.parse(fs5.readFileSync(filePath, "utf8"));
+        } catch (err) {
+          throw new SheetAddressError(`Invalid JSON in ${opts.from}: ${err.message}`);
+        }
+        const out2 = await withDoc(modelId, (doc) => buildFromSpec(doc, modelId, name2, spec));
+        console.log(out2);
+        return;
+      }
+      if (!name2)
+        throw new SheetAddressError("Pass a <name> (or --from <file>).");
+      const id = crypto.randomUUID();
+      const d = ELEMENT_DIMENSIONS.chapter;
+      const v = validateEntry("chapters", { name: name2, x: 0, y: 0, width: d.width, height: d.height });
+      if (!v.ok)
+        throw new SheetAddressError(`Invalid sheet: ${v.issues.join("; ")}`);
+      const out = await withDoc(modelId, (doc) => {
+        doc.transact(() => {
+          getScopeMap(doc, "chapters").set(id, deepToY({ ...v.data, chapterId: id, modelId }));
+          ensureSheet(doc, id);
+        });
+        reflowAllSheets(doc);
+        return `sheet "${name2}"  ${id}`;
+      });
+      console.log(out);
+    } catch (err) {
+      if (err instanceof SheetAddressError) {
+        console.error(err.message);
+        process.exit(2);
+      }
+      throw err;
+    }
+  });
+  sheet.command("delete [sheet]").description("Delete a whole sheet and everything in it — slices, lanes, elements, scenarios, flows. Destructive; pass --yes to confirm.").option("--yes", "Confirm the deletion (required — this cannot be undone)").option("--model <id>", "Target model id").action(async (sheetRef, opts) => {
+    const modelId = resolveModelId(opts.model);
+    try {
+      const out = await withDoc(modelId, (doc) => {
+        const s = resolveSheet2(doc, sheetRef);
+        const name2 = getEntry(doc, "chapters", s.chapterId)?.name ?? s.chapterId;
+        const elements = Object.values(s.structure.cells).reduce((n, refs) => n + refs.length, 0);
+        const summary = `sheet "${name2}" — ${s.structure.columns.length} slice(s), ${s.structure.rows.length} lane(s), ${elements} element(s)`;
+        if (!opts.yes) {
+          return `Would delete ${summary}.
+This cannot be undone. Re-run with --yes to confirm.`;
+        }
+        deleteSheet(doc, s.chapterId);
+        reflowAllSheets(doc);
+        return `Deleted ${summary}.`;
+      });
+      console.log(out);
+    } catch (err) {
+      if (err instanceof SheetAddressError) {
+        console.error(err.message);
+        process.exit(2);
+      }
+      throw err;
+    }
+  });
+  const insert = sheet.command("insert").description("Insert a slice (column), a lane (row), or an element into a cell");
+  insert.command("slice <name>").description("Insert a new slice (column)").option("--at <n>", "Position (1-based); appends if omitted").option("--sheet <ref>", "Which sheet (name or chapterId) when the model has several").option("--model <id>", "Target model id").action((name2, opts) => runWrite(opts, (doc, s, modelId) => insertColumn(doc, s, modelId, name2, atIndex(opts.at))));
+  for (const kind of LANE_KINDS) {
+    insert.command(`${kind} <name>`).description(`Insert a ${kind} lane (row)`).option("--at <n>", "Position (1-based); appends if omitted").option("--sheet <ref>", "Which sheet (name or chapterId) when the model has several").option("--model <id>", "Target model id").action((name2, opts) => runWrite(opts, (doc, s, modelId) => insertLane(doc, s, modelId, kind, name2, atIndex(opts.at))));
+  }
+  for (const type of ELEMENT_TYPES) {
+    insert.command(`${type} <cell> <element>`).description(`Insert a ${type} into a cell (e.g. B2). <element> is a name or a JSON object.`).option("--sheet <ref>", "Which sheet (name or chapterId) when the model has several").option("--model <id>", "Target model id").action((cell, element, opts) => runWrite(opts, (doc, s, modelId) => insertElement(doc, s, modelId, type, cell, element)));
+  }
+  sheet.command("move <element>").description("Move an element to another cell, e.g. `move B2.1 --to C2` (keeps its id + flows)").requiredOption("--to <cell>", "Destination cell (e.g. C2)").option("--sheet <ref>", "Which sheet when the model has several").option("--model <id>", "Target model id").action((element, opts) => runWrite(opts, (doc, s) => moveElement(doc, s, element, opts.to)));
+  sheet.command("reorder <ref>").description("Reorder a slice (column letter) or lane (row number), e.g. `reorder A --to 3`").requiredOption("--to <n>", "New 1-based position").option("--sheet <ref>", "Which sheet when the model has several").option("--model <id>", "Target model id").action((ref, opts) => runWrite(opts, (doc, s) => reorderAxis(doc, s, ref, parseInt(opts.to, 10))));
+  sheet.command("rm <target>").description("Remove an element (B2.1), a column (A), or a lane (2) — cascades to flows/scenarios").option("--sheet <ref>", "Which sheet when the model has several").option("--model <id>", "Target model id").action((target, opts) => runWrite(opts, (doc, s) => removeTarget(doc, s, target)));
+  sheet.command("update <address> <json>").description(`Replace an element's shape in place (e.g. \`update A2.1 '{"name":"PlaceOrderV2","fields":[…]}'\`)`).option("--sheet <ref>", "Which sheet when the model has several").option("--model <id>", "Target model id").action((address, json, opts) => runWrite(opts, (doc, s, modelId) => updateElement(doc, s, modelId, address, json)));
+  sheet.command("flow <from> <to>").description("Connect two elements, e.g. `flow A2.1 A3.1` (flow type inferred from the element kinds)").option("--type <flowType>", "Force a flow type (otherwise inferred)").option("--sheet <ref>", "Which sheet when the model has several").option("--model <id>", "Target model id").action((from, to, opts) => runWrite(opts, (doc, s, modelId) => flowBetween(doc, s, modelId, from, to, opts.type)));
+  sheet.command("connect <fromSheet> <toSheet>").description("Draw a branching flow between two sheets, e.g. `connect Checkout Fulfillment` (sheet edges), or anchor on slices with `--from D --to A`").option("--from <col>", "Anchor the source on a slice (column letter/name); omit for the source sheet's right edge").option("--to <col>", "Anchor the target on a slice (column letter/name); omit for the target sheet's left edge").option("--from-side <side>", "Source anchor side — top|bottom for a slice (default bottom), left|right for a sheet edge (default right)").option("--to-side <side>", "Target anchor side — top|bottom for a slice (default top), left|right for a sheet edge (default left)").option("--model <id>", "Target model id").action(async (fromSheet, toSheet, opts) => {
+    const modelId = resolveModelId(opts.model);
+    try {
+      const out = await withDoc(modelId, (doc) => connectSheets(doc, modelId, fromSheet, toSheet, opts));
+      console.log(out);
+    } catch (err) {
+      if (err instanceof SheetAddressError) {
+        console.error(err.message);
+        process.exit(2);
+      }
+      throw err;
+    }
+  });
+  sheet.command("copy <element>").description("Place a linked copy of an element into another cell, e.g. `copy A3.1 --to D3` (events/read-models/screens/external-events)").requiredOption("--to <cell>", "Destination cell").option("--sheet <ref>", "Which sheet when the model has several").option("--model <id>", "Target model id").action((element, opts) => runWrite(opts, (doc, s, modelId) => copyElement(doc, s, modelId, element, opts.to)));
+  sheet.command("note <target> [text]").description('Annotate a cell (B2), column (A), or lane (2). Omit text (or pass "") to clear.').option("--sheet <ref>", "Which sheet when the model has several").option("--model <id>", "Target model id").action((target, text, opts) => runWrite(opts, (doc, s) => noteTarget(doc, s, target, text ?? "")));
+}
+
+// src/lib/connection-state.ts
+function argvModel(argv) {
+  for (let i = 0;i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--model")
+      return argv[i + 1];
+    if (a.startsWith("--model="))
+      return a.slice("--model=".length);
+  }
+  return;
+}
+async function fetchMode(modelId) {
+  try {
+    const res = await api(`/api/models/${modelId}/visibility`);
+    return res.mode === "sheets" || res.mode === "freeform" ? res.mode : undefined;
+  } catch {
+    return;
+  }
+}
+async function resolveConnectionState(argv) {
+  const cfg = loadProjectConfig();
+  const override = argvModel(argv);
+  const modelId = override ?? cfg?.modelId;
+  if (!modelId)
+    return { state: "disconnected" };
+  const usingConfig = !override || override === cfg?.modelId;
+  if (usingConfig && cfg?.mode) {
+    return { state: cfg.mode, modelId, modelName: cfg.modelName, mode: cfg.mode };
+  }
+  const mode = await fetchMode(modelId);
+  return {
+    state: mode ?? "unknown",
+    modelId,
+    modelName: usingConfig ? cfg?.modelName : undefined,
+    mode,
+    overridden: Boolean(override && override !== cfg?.modelId)
+  };
+}
+
 // src/lib/update-check.ts
 var import_semver = __toESM(require_semver2(), 1);
 import { spawn } from "node:child_process";
@@ -4299,28 +6070,28 @@ async function fetchLatestVersion() {
   }
 }
 function promptYesNo(question) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve6) => {
     const rl = readline2.createInterface({
       input: process.stdin,
       output: process.stdout
     });
     const timeout = setTimeout(() => {
       rl.close();
-      resolve4(false);
+      resolve6(false);
     }, PROMPT_TIMEOUT_MS);
     rl.question(question, (answer) => {
       clearTimeout(timeout);
       rl.close();
-      resolve4(["y", "yes"].includes(answer.trim().toLowerCase()));
+      resolve6(["y", "yes"].includes(answer.trim().toLowerCase()));
     });
   });
 }
 function runUpdate() {
   const [command, args] = updateCommand(detectPackageManager());
-  return new Promise((resolve4) => {
+  return new Promise((resolve6) => {
     const child = spawn(command, args, { stdio: "inherit" });
-    child.on("close", (code) => resolve4(code ?? 1));
-    child.on("error", () => resolve4(1));
+    child.on("close", (code) => resolve6(code ?? 1));
+    child.on("error", () => resolve6(1));
   });
 }
 async function maybeUpdateCli(packageName, currentVersion, argv) {
@@ -4361,21 +6132,50 @@ async function maybeUpdateCli(packageName, currentVersion, argv) {
 
 // src/index.ts
 var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = path5.dirname(__filename2);
-var packageJson = JSON.parse(fs5.readFileSync(path5.join(__dirname2, "..", "package.json"), "utf-8"));
+var __dirname2 = path6.dirname(__filename2);
+var packageJson = JSON.parse(fs6.readFileSync(path6.join(__dirname2, "..", "package.json"), "utf-8"));
 var program = new Command().name("eventmodeler").version(packageJson.version).description("CLI tool for interacting with Event Model files").option("--id <uuid>", "Skip name resolution, use UUID directly").option("--no-update-check", "Skip checking npm for a newer CLI version");
 setProgram(program);
+var FREEFORM_COMMANDS = new Set(["create", "update", "remove", "show"]);
+var conn = await resolveConnectionState(process.argv);
 registerAuthCommands(program);
 registerInitCommands(program);
+registerStatusCommands(program, conn);
 registerListCommands(program);
-registerShowCommands(program);
-registerSummaryCommands(program);
-registerCreateCommands(program);
-registerUpdateCommands(program);
-registerRemoveCommands(program);
-registerSnapshotCommands(program);
+var connected = conn.state !== "disconnected";
+var freeform = conn.state === "freeform" || conn.state === "unknown";
+var sheets = conn.state === "sheets" || conn.state === "unknown";
+if (connected) {
+  registerSummaryCommands(program);
+  registerSnapshotCommands(program);
+}
+if (freeform) {
+  registerShowCommands(program);
+  registerCreateCommands(program);
+  registerUpdateCommands(program);
+  registerRemoveCommands(program);
+}
+if (sheets) {
+  registerSheetCommands(program);
+}
+program.on("command:*", (operands) => {
+  redirectUnknown(operands[0] ?? "", conn);
+});
 await maybeUpdateCli(packageJson.name, packageJson.version, process.argv);
 program.parseAsync(process.argv).catch((err) => {
   console.error("Error:", err.message);
   process.exit(1);
 });
+function redirectUnknown(cmd, c) {
+  if (c.state === "disconnected") {
+    console.error(`Not connected — run \`eventmodeler init\` to link a model, or pass --model <id>. (command: ${cmd || "(none)"})`);
+  } else if (c.state === "sheets" && FREEFORM_COMMANDS.has(cmd)) {
+    console.error(`\`${cmd}\` isn't available on a sheets model — use the \`sheet\` family: \`sheet insert\`, \`sheet show\`, \`sheet move\`, \`sheet update\`, \`sheet rm\`.`);
+  } else if (c.state === "freeform" && cmd === "sheet") {
+    const who = c.modelName ? `"${c.modelName}"` : c.modelId ?? "this model";
+    console.error(`\`sheet\` commands are for sheets-mode models; ${who} is freeform. Use create/update/remove/show.`);
+  } else {
+    console.error(`Unknown command: ${cmd}`);
+  }
+  process.exit(2);
+}