@ifc-lite/viewer 1.17.6 → 1.19.0

package/src/store/slices/addElementSlice.ts

@@ -0,0 +1,275 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Add-element tool state — drives the right-side AddElementPanel and
+ * the viewport's click-to-place state machine. The actual STEP work
+ * runs through `mutationSlice` actions (`addWall` / `addSlab` /
+ * `addBeam` / `addColumn`); this slice holds:
+ *
+ *   - the panel form state (selected type, per-type dimensions,
+ *     target storey, target federated model)
+ *   - the in-progress click-placement state (pendingPoints,
+ *     hoverPoint, slabMode for rectangle vs polygon)
+ *
+ * Defaults match the IfcCreator builders' construction-standard
+ * conventions: wall thickness 0.2m, floor height 3m, slab 5×5×0.3m,
+ * column 0.4×0.4×3m, beam 0.3×0.5×3m.
+ */
+
+import { type StateCreator } from 'zustand';
+
+export type AddElementType =
+  | 'wall'
+  | 'slab'
+  | 'beam'
+  | 'column'
+  | 'door'
+  | 'window'
+  | 'space'
+  | 'roof'
+  | 'plate'
+  | 'member';
+export type AddElementSlabMode = 'rectangle' | 'polygon';
+
+/**
+ * A single accumulated 3D click point in **renderer-frame** Y-up world
+ * coordinates (the same space the camera projects from). The IFC
+ * conversion happens at builder dispatch time so the live preview can
+ * project each pending point to screen without needing to know the
+ * target storey's elevation.
+ */
+export interface AddElementVec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface AddElementWallParams {
+  Thickness: number;
+  Height: number;
+}
+
+export interface AddElementSlabParams {
+  Width: number;
+  Depth: number;
+  Thickness: number;
+}
+
+export interface AddElementBeamParams {
+  Width: number;
+  Height: number;
+}
+
+export interface AddElementColumnParams {
+  Width: number;
+  Depth: number;
+  Height: number;
+}
+
+export interface AddElementDoorParams {
+  Width: number;
+  Height: number;
+  FrameThickness: number;
+}
+
+export interface AddElementWindowParams {
+  Width: number;
+  Height: number;
+  FrameThickness: number;
+}
+
+export interface AddElementSpaceParams {
+  Width: number;
+  Depth: number;
+  Height: number;
+}
+
+export interface AddElementRoofParams {
+  Width: number;
+  Depth: number;
+  Thickness: number;
+}
+
+export interface AddElementPlateParams {
+  Width: number;
+  Depth: number;
+  Thickness: number;
+}
+
+export interface AddElementMemberParams {
+  Width: number;
+  Height: number;
+}
+
+/**
+ * Auto-space generation settings — ties into `generateSpacesFromWalls`.
+ * Lives here so the panel form survives type-switches.
+ */
+export interface AddElementAutoSpaceParams {
+  /** Wall-end snap tolerance in metres (collapses tiny gaps). */
+  SnapTolerance: number;
+  /** Drop detected regions below this area (m²). */
+  MinArea: number;
+  /** IfcSpace extrusion height (m). */
+  Height: number;
+  /** Naming pattern; `{n}` = 1-based index. */
+  NamePattern: string;
+  /** IfcSpaceTypeEnum value (without dots). */
+  PredefinedType: string;
+}
+
+/** Live preview from the most recent dry-run detection (cleared on commit). */
+export interface AddElementAutoSpacePreview {
+  storeyExpressId: number;
+  /** CCW outlines in IFC storey-local 2D (X/Y, m). */
+  outlines: Array<Array<[number, number]>>;
+  /** Per-region metadata for the panel summary. */
+  regions: Array<{ area: number }>;
+  wallsConsidered: number;
+  wallsContributing: number;
+  /**
+   * Diagnostic counts from the planar-graph pipeline. Surfaced
+   * verbatim in the Auto Spaces panel so users can spot pipeline
+   * failures (e.g. zero edges after intersect-split → walls don't
+   * connect).
+   */
+  diagnostics?: {
+    vertices: number;
+    edgesAfterSplit: number;
+    facesTotal: number;
+    outerFacesDropped: number;
+    belowMinAreaDropped: number;
+    largestArea: number;
+    skipReasons: Record<string, number>;
+  };
+}
+
+export interface AddElementSlice {
+  addElementType: AddElementType;
+  /** Target storey expressId; `null` ⇒ auto-pick first storey on click. */
+  addElementStoreyId: number | null;
+  /** Target model id; `null` ⇒ auto-pick the active model on click. */
+  addElementModelId: string | null;
+  addElementWallParams: AddElementWallParams;
+  addElementSlabParams: AddElementSlabParams;
+  addElementBeamParams: AddElementBeamParams;
+  addElementColumnParams: AddElementColumnParams;
+  addElementDoorParams: AddElementDoorParams;
+  addElementWindowParams: AddElementWindowParams;
+  addElementSpaceParams: AddElementSpaceParams;
+  addElementRoofParams: AddElementRoofParams;
+  addElementPlateParams: AddElementPlateParams;
+  addElementMemberParams: AddElementMemberParams;
+  addElementAutoSpaceParams: AddElementAutoSpaceParams;
+  addElementAutoSpacePreview: AddElementAutoSpacePreview | null;
+
+  /** Rectangle (2 clicks) or polygon (N clicks + Enter to close). */
+  addElementSlabMode: AddElementSlabMode;
+  /** In-progress click points. Cleared on tool exit, type change, or Esc. */
+  addElementPendingPoints: AddElementVec3[];
+  /** Live preview point under the cursor (snap-aware). */
+  addElementHoverPoint: AddElementVec3 | null;
+
+  setAddElementType: (t: AddElementType) => void;
+  setAddElementStoreyId: (id: number | null) => void;
+  setAddElementModelId: (id: string | null) => void;
+  setAddElementWallParams: (p: Partial<AddElementWallParams>) => void;
+  setAddElementSlabParams: (p: Partial<AddElementSlabParams>) => void;
+  setAddElementBeamParams: (p: Partial<AddElementBeamParams>) => void;
+  setAddElementColumnParams: (p: Partial<AddElementColumnParams>) => void;
+  setAddElementDoorParams: (p: Partial<AddElementDoorParams>) => void;
+  setAddElementWindowParams: (p: Partial<AddElementWindowParams>) => void;
+  setAddElementSpaceParams: (p: Partial<AddElementSpaceParams>) => void;
+  setAddElementRoofParams: (p: Partial<AddElementRoofParams>) => void;
+  setAddElementPlateParams: (p: Partial<AddElementPlateParams>) => void;
+  setAddElementMemberParams: (p: Partial<AddElementMemberParams>) => void;
+  setAddElementAutoSpaceParams: (p: Partial<AddElementAutoSpaceParams>) => void;
+  setAddElementAutoSpacePreview: (preview: AddElementAutoSpacePreview | null) => void;
+  setAddElementSlabMode: (m: AddElementSlabMode) => void;
+  appendAddElementPendingPoint: (p: AddElementVec3) => void;
+  setAddElementHoverPoint: (p: AddElementVec3 | null) => void;
+  clearAddElementPending: () => void;
+}
+
+const ADD_ELEMENT_DEFAULTS = {
+  type: 'wall' as AddElementType,
+  wall: { Thickness: 0.2, Height: 3 } as AddElementWallParams,
+  slab: { Width: 5, Depth: 5, Thickness: 0.3 } as AddElementSlabParams,
+  beam: { Width: 0.3, Height: 0.5 } as AddElementBeamParams,
+  column: { Width: 0.4, Depth: 0.4, Height: 3 } as AddElementColumnParams,
+  door: { Width: 0.9, Height: 2.1, FrameThickness: 0.05 } as AddElementDoorParams,
+  window: { Width: 1.2, Height: 1.5, FrameThickness: 0.05 } as AddElementWindowParams,
+  space: { Width: 4, Depth: 4, Height: 3 } as AddElementSpaceParams,
+  roof: { Width: 8, Depth: 8, Thickness: 0.3 } as AddElementRoofParams,
+  plate: { Width: 1, Depth: 1, Thickness: 0.02 } as AddElementPlateParams,
+  member: { Width: 0.1, Height: 0.1 } as AddElementMemberParams,
+  autoSpace: {
+    SnapTolerance: 0.1,
+    MinArea: 0.5,
+    Height: 3,
+    NamePattern: 'Space {n}',
+    PredefinedType: 'INTERNAL',
+  } as AddElementAutoSpaceParams,
+};
+
+export const createAddElementSlice: StateCreator<AddElementSlice, [], [], AddElementSlice> = (set) => ({
+  addElementType: ADD_ELEMENT_DEFAULTS.type,
+  addElementStoreyId: null,
+  addElementModelId: null,
+  addElementWallParams: { ...ADD_ELEMENT_DEFAULTS.wall },
+  addElementSlabParams: { ...ADD_ELEMENT_DEFAULTS.slab },
+  addElementBeamParams: { ...ADD_ELEMENT_DEFAULTS.beam },
+  addElementColumnParams: { ...ADD_ELEMENT_DEFAULTS.column },
+  addElementDoorParams: { ...ADD_ELEMENT_DEFAULTS.door },
+  addElementWindowParams: { ...ADD_ELEMENT_DEFAULTS.window },
+  addElementSpaceParams: { ...ADD_ELEMENT_DEFAULTS.space },
+  addElementRoofParams: { ...ADD_ELEMENT_DEFAULTS.roof },
+  addElementPlateParams: { ...ADD_ELEMENT_DEFAULTS.plate },
+  addElementMemberParams: { ...ADD_ELEMENT_DEFAULTS.member },
+  addElementAutoSpaceParams: { ...ADD_ELEMENT_DEFAULTS.autoSpace },
+  addElementAutoSpacePreview: null,
+  addElementSlabMode: 'rectangle',
+  addElementPendingPoints: [],
+  addElementHoverPoint: null,
+
+  setAddElementType: (addElementType) =>
+    // Switching types resets the pending-click queue — a wall's start
+    // doesn't make sense as a slab's first corner. Hover is cleared
+    // alongside so a stale preview doesn't flash with the new shape.
+    set({ addElementType, addElementPendingPoints: [], addElementHoverPoint: null }),
+  setAddElementStoreyId: (addElementStoreyId) => set({ addElementStoreyId }),
+  setAddElementModelId: (addElementModelId) => set({ addElementModelId }),
+  setAddElementWallParams: (p) =>
+    set((s) => ({ addElementWallParams: { ...s.addElementWallParams, ...p } })),
+  setAddElementSlabParams: (p) =>
+    set((s) => ({ addElementSlabParams: { ...s.addElementSlabParams, ...p } })),
+  setAddElementBeamParams: (p) =>
+    set((s) => ({ addElementBeamParams: { ...s.addElementBeamParams, ...p } })),
+  setAddElementColumnParams: (p) =>
+    set((s) => ({ addElementColumnParams: { ...s.addElementColumnParams, ...p } })),
+  setAddElementDoorParams: (p) =>
+    set((s) => ({ addElementDoorParams: { ...s.addElementDoorParams, ...p } })),
+  setAddElementWindowParams: (p) =>
+    set((s) => ({ addElementWindowParams: { ...s.addElementWindowParams, ...p } })),
+  setAddElementSpaceParams: (p) =>
+    set((s) => ({ addElementSpaceParams: { ...s.addElementSpaceParams, ...p } })),
+  setAddElementRoofParams: (p) =>
+    set((s) => ({ addElementRoofParams: { ...s.addElementRoofParams, ...p } })),
+  setAddElementPlateParams: (p) =>
+    set((s) => ({ addElementPlateParams: { ...s.addElementPlateParams, ...p } })),
+  setAddElementMemberParams: (p) =>
+    set((s) => ({ addElementMemberParams: { ...s.addElementMemberParams, ...p } })),
+  setAddElementAutoSpaceParams: (p) =>
+    set((s) => ({ addElementAutoSpaceParams: { ...s.addElementAutoSpaceParams, ...p } })),
+  setAddElementAutoSpacePreview: (preview) =>
+    set({ addElementAutoSpacePreview: preview }),
+  setAddElementSlabMode: (addElementSlabMode) =>
+    set({ addElementSlabMode, addElementPendingPoints: [], addElementHoverPoint: null }),
+  appendAddElementPendingPoint: (p) =>
+    set((s) => ({ addElementPendingPoints: [...s.addElementPendingPoints, p] })),
+  setAddElementHoverPoint: (addElementHoverPoint) => set({ addElementHoverPoint }),
+  clearAddElementPending: () =>
+    set({ addElementPendingPoints: [], addElementHoverPoint: null }),
+});

package/src/store/slices/annotationsSlice.test.ts

@@ -0,0 +1,133 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { createAnnotationsSlice, type AnnotationsSlice } from './annotationsSlice.js';
+
+// Stub localStorage so the slice can read/write without browser env.
+function installStubStorage(): { wipe: () => void } {
+  const data = new Map<string, string>();
+  (globalThis as unknown as { localStorage: Storage }).localStorage = {
+    getItem: (k: string) => data.get(k) ?? null,
+    setItem: (k: string, v: string) => { data.set(k, v); },
+    removeItem: (k: string) => { data.delete(k); },
+    clear: () => data.clear(),
+    key: (i: number) => Array.from(data.keys())[i] ?? null,
+    get length() { return data.size; },
+  } as Storage;
+  return { wipe: () => data.clear() };
+}
+
+describe('AnnotationsSlice', () => {
+  let state: AnnotationsSlice;
+  let setState: (partial: Partial<AnnotationsSlice> | ((s: AnnotationsSlice) => Partial<AnnotationsSlice>)) => void;
+  let storage: { wipe: () => void };
+
+  beforeEach(() => {
+    storage = installStubStorage();
+    storage.wipe();
+
+    setState = (partial) => {
+      const next = typeof partial === 'function' ? partial(state) : partial;
+      state = { ...state, ...next };
+    };
+    state = createAnnotationsSlice(setState as never, () => state, {} as never);
+  });
+
+  describe('initial state', () => {
+    it('starts with no annotations and no draft', () => {
+      assert.strictEqual(state.annotations.size, 0);
+      assert.strictEqual(state.draft, null);
+      assert.strictEqual(state.selectedAnnotationId, null);
+    });
+  });
+
+  describe('beginDraft + commitDraft', () => {
+    it('opens a draft at the given world position', () => {
+      state.beginDraft({ x: 1, y: 2, z: 3 }, 42, 'arch');
+      assert.ok(state.draft);
+      assert.deepStrictEqual(state.draft!.position, { x: 1, y: 2, z: 3 });
+      assert.strictEqual(state.draft!.entityExpressId, 42);
+      assert.strictEqual(state.draft!.modelId, 'arch');
+    });
+
+    it('commits the draft into a new annotation', () => {
+      state.beginDraft({ x: 1, y: 2, z: 3 }, 42, 'arch');
+      const id = state.commitDraft('Defect: chip in the corner');
+      assert.ok(id);
+      assert.strictEqual(state.annotations.size, 1);
+      const ann = state.annotations.get(id!);
+      assert.strictEqual(ann?.note, 'Defect: chip in the corner');
+      assert.strictEqual(ann?.entityExpressId, 42);
+      assert.strictEqual(state.draft, null);
+    });
+
+    it('drops the draft silently when committed with an empty note', () => {
+      state.beginDraft({ x: 0, y: 0, z: 0 }, null, null);
+      const id = state.commitDraft('   ');
+      assert.strictEqual(id, null);
+      assert.strictEqual(state.annotations.size, 0);
+      assert.strictEqual(state.draft, null);
+    });
+
+    it('clears the selected pin when a draft begins', () => {
+      state.beginDraft({ x: 0, y: 0, z: 0 }, null, null);
+      const id = state.commitDraft('first');
+      state.selectAnnotation(id!);
+      assert.strictEqual(state.selectedAnnotationId, id);
+      state.beginDraft({ x: 1, y: 1, z: 1 }, null, null);
+      assert.strictEqual(state.selectedAnnotationId, null);
+    });
+  });
+
+  describe('updateAnnotation', () => {
+    it('updates the note and bumps updatedAt', () => {
+      state.beginDraft({ x: 0, y: 0, z: 0 }, null, null);
+      const id = state.commitDraft('original')!;
+      const original = state.annotations.get(id)!;
+      // Force a measurable time delta even when the test runner is fast.
+      const before = original.updatedAt;
+      state.updateAnnotation(id, 'revised');
+      const after = state.annotations.get(id)!;
+      assert.strictEqual(after.note, 'revised');
+      assert.ok(after.updatedAt >= before);
+    });
+
+    it('keeps the annotation when the note is wiped (does not auto-delete)', () => {
+      state.beginDraft({ x: 0, y: 0, z: 0 }, null, null);
+      const id = state.commitDraft('something')!;
+      state.updateAnnotation(id, '');
+      const ann = state.annotations.get(id);
+      assert.ok(ann);
+      assert.strictEqual(ann!.note, '');
+    });
+  });
+
+  describe('removeAnnotation', () => {
+    it('removes the entry and clears the selection if it was selected', () => {
+      state.beginDraft({ x: 0, y: 0, z: 0 }, null, null);
+      const id = state.commitDraft('to-delete')!;
+      state.selectAnnotation(id);
+      state.removeAnnotation(id);
+      assert.strictEqual(state.annotations.size, 0);
+      assert.strictEqual(state.selectedAnnotationId, null);
+    });
+  });
+
+  describe('persistence', () => {
+    it('survives a fresh slice instantiation by round-tripping localStorage', () => {
+      state.beginDraft({ x: 7, y: 8, z: 9 }, 1, 'm1');
+      const id = state.commitDraft('persistent')!;
+
+      // Spin up a brand-new slice — it should pick up the saved entry
+      // without us threading state through ourselves.
+      let s2: AnnotationsSlice;
+      const setState2: (p: never) => void = () => {};
+      s2 = createAnnotationsSlice(setState2 as never, () => s2, {} as never);
+      assert.strictEqual(s2.annotations.size, 1);
+      assert.strictEqual(s2.annotations.get(id)?.note, 'persistent');
+    });
+  });
+});

package/src/store/slices/annotationsSlice.ts

@@ -0,0 +1,251 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Annotation slice — pins anchored to world points on the 3D scene.
+ *
+ * Each pin holds a short note and persists across reloads via
+ * localStorage (scoped per browser, no server). Pins are NOT IFC
+ * entities — they live alongside the model as an authoring overlay.
+ * Future PRs will add BCF round-trip and IfcAnnotation export.
+ *
+ * Coordinate frame: world positions are stored in the renderer's
+ * local Y-up coordinate space (the same one the camera projects
+ * from). Pins are placed by raycasting the scene under the cursor;
+ * the raycast intersection is already in this frame so no conversion
+ * is needed at write time.
+ */
+
+import { type StateCreator } from 'zustand';
+
+const STORAGE_KEY = 'ifc-lite:annotations:v1';
+const MAX_NOTE_LEN = 2000;
+
+export interface AnnotationPosition {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface Annotation {
+  id: string;
+  /** World-space position in the renderer's local Y-up frame. */
+  position: AnnotationPosition;
+  /** Plain-text body (Markdown rendering deliberately punted to v2). */
+  note: string;
+  /** Express id of the entity the user clicked, when one was hit. */
+  entityExpressId: number | null;
+  /** Federated model id when the click landed on a model mesh; null for empty-space clicks. */
+  modelId: string | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface AnnotationDraft {
+  /** Floating ID used by the inline input UI before the annotation is committed. */
+  draftId: string;
+  position: AnnotationPosition;
+  entityExpressId: number | null;
+  modelId: string | null;
+}
+
+export interface AnnotationsSlice {
+  // State
+  annotations: Map<string, Annotation>;
+  /** Pending pin awaiting a note — drives the inline drop input. */
+  draft: AnnotationDraft | null;
+  /** Currently expanded pin (popover open). */
+  selectedAnnotationId: string | null;
+
+  // Actions
+  /** Open the inline drop input at a world position. */
+  beginDraft: (position: AnnotationPosition, entityExpressId: number | null, modelId: string | null) => void;
+  /** Commit the draft into a new annotation. Empty notes drop the draft silently. */
+  commitDraft: (note: string) => string | null;
+  /** Cancel the draft. */
+  cancelDraft: () => void;
+  /** Update an existing annotation's note. */
+  updateAnnotation: (id: string, note: string) => void;
+  /** Delete an annotation. */
+  removeAnnotation: (id: string) => void;
+  /** Open the popover for an existing pin. */
+  selectAnnotation: (id: string | null) => void;
+  /** Wipe all annotations across all models. Used by tests / "reset". */
+  clearAllAnnotations: () => void;
+}
+
+function generateId(prefix: 'ann' | 'draft'): string {
+  const rnd = Math.random().toString(36).slice(2, 9);
+  return `${prefix}_${Date.now().toString(36)}_${rnd}`;
+}
+
+function clampNote(note: string): string {
+  const trimmed = note.trim();
+  return trimmed.length > MAX_NOTE_LEN ? trimmed.slice(0, MAX_NOTE_LEN) : trimmed;
+}
+
+// ── Persistence ──────────────────────────────────────────────────────
+
+function isFiniteNumber(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v);
+}
+
+function isValidPosition(v: unknown): v is AnnotationPosition {
+  if (!v || typeof v !== 'object') return false;
+  const p = v as Record<string, unknown>;
+  return isFiniteNumber(p.x) && isFiniteNumber(p.y) && isFiniteNumber(p.z);
+}
+
+function isValidAnnotation(v: unknown): v is Annotation {
+  if (!v || typeof v !== 'object') return false;
+  const a = v as Record<string, unknown>;
+  if (typeof a.id !== 'string' || a.id.length === 0) return false;
+  if (typeof a.note !== 'string') return false;
+  if (!isValidPosition(a.position)) return false;
+  if (a.entityExpressId !== null && !isFiniteNumber(a.entityExpressId)) return false;
+  if (a.modelId !== null && typeof a.modelId !== 'string') return false;
+  if (!isFiniteNumber(a.createdAt) || !isFiniteNumber(a.updatedAt)) return false;
+  return true;
+}
+
+function loadFromStorage(): Map<string, Annotation> {
+  try {
+    if (typeof localStorage === 'undefined') return new Map();
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return new Map();
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return new Map();
+    const map = new Map<string, Annotation>();
+    for (const item of parsed) {
+      if (!isValidAnnotation(item)) {
+        // eslint-disable-next-line no-console
+        console.warn(`[annotations] skipping malformed entry from ${STORAGE_KEY}`, item);
+        continue;
+      }
+      map.set(item.id, item);
+    }
+    return map;
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(`[annotations] failed to load from ${STORAGE_KEY}`, err);
+    return new Map();
+  }
+}
+
+function saveToStorage(annotations: Map<string, Annotation>): void {
+  try {
+    if (typeof localStorage === 'undefined') return;
+    const arr = Array.from(annotations.values());
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(arr));
+  } catch (err) {
+    // Quota exceeded / private mode — annotations stay in memory but
+    // the warning makes the failure debuggable.
+    // eslint-disable-next-line no-console
+    console.warn(`[annotations] failed to persist to ${STORAGE_KEY}`, err);
+  }
+}
+
+// ── Slice ────────────────────────────────────────────────────────────
+
+export const createAnnotationsSlice: StateCreator<AnnotationsSlice, [], [], AnnotationsSlice> = (
+  set,
+  get,
+) => ({
+  annotations: loadFromStorage(),
+  draft: null,
+  selectedAnnotationId: null,
+
+  beginDraft: (position, entityExpressId, modelId) => {
+    set({
+      draft: {
+        draftId: generateId('draft'),
+        position,
+        entityExpressId,
+        modelId,
+      },
+      // Drafting opens its own input — close any open popover first
+      // so the two pieces of UI don't fight for focus.
+      selectedAnnotationId: null,
+    });
+  },
+
+  commitDraft: (note) => {
+    const draft = get().draft;
+    if (!draft) return null;
+    const clamped = clampNote(note);
+    if (clamped.length === 0) {
+      set({ draft: null });
+      return null;
+    }
+    const id = generateId('ann');
+    const now = Date.now();
+    const annotation: Annotation = {
+      id,
+      position: draft.position,
+      note: clamped,
+      entityExpressId: draft.entityExpressId,
+      modelId: draft.modelId,
+      createdAt: now,
+      updatedAt: now,
+    };
+    set((state) => {
+      const next = new Map(state.annotations);
+      next.set(id, annotation);
+      saveToStorage(next);
+      return {
+        annotations: next,
+        draft: null,
+        selectedAnnotationId: null,
+      };
+    });
+    return id;
+  },
+
+  cancelDraft: () => {
+    set({ draft: null });
+  },
+
+  updateAnnotation: (id, note) => {
+    set((state) => {
+      const existing = state.annotations.get(id);
+      if (!existing) return {};
+      const clamped = clampNote(note);
+      if (clamped.length === 0) {
+        // Deleting via empty note feels surprising — keep the
+        // annotation but with an empty body so the user can choose
+        // to delete via the trash icon explicitly.
+        const next = new Map(state.annotations);
+        next.set(id, { ...existing, note: '', updatedAt: Date.now() });
+        saveToStorage(next);
+        return { annotations: next };
+      }
+      const next = new Map(state.annotations);
+      next.set(id, { ...existing, note: clamped, updatedAt: Date.now() });
+      saveToStorage(next);
+      return { annotations: next };
+    });
+  },
+
+  removeAnnotation: (id) => {
+    set((state) => {
+      if (!state.annotations.has(id)) return {};
+      const next = new Map(state.annotations);
+      next.delete(id);
+      saveToStorage(next);
+      return {
+        annotations: next,
+        selectedAnnotationId: state.selectedAnnotationId === id ? null : state.selectedAnnotationId,
+      };
+    });
+  },
+
+  selectAnnotation: (id) => {
+    set({ selectedAnnotationId: id });
+  },
+
+  clearAllAnnotations: () => {
+    saveToStorage(new Map());
+    set({ annotations: new Map(), draft: null, selectedAnnotationId: null });
+  },
+});