viteboard 0.1.0

package/src/app/AppController.ts

@@ -0,0 +1,955 @@
+import { BoardState } from "./BoardState";
+import { CommandManager } from "./CommandManager";
+import { ElementActions } from "./ElementActions";
+import { ImageInsertService } from "./ImageInsertService";
+import { ClipboardService } from "./ClipboardService";
+import { bindKeyboardShortcuts } from "./KeyboardShortcuts";
+import { exportViewportPng, exportFullBoardPng, downloadBlob } from "./ExportPng";
+import { EmbedRegionSelector, type ScreenRect } from "./EmbedRegionSelector";
+
+import { CanvasSurface } from "../canvas/CanvasSurface";
+import { CanvasRenderer } from "../canvas/CanvasRenderer";
+import { RenderScheduler } from "../canvas/RenderScheduler";
+import { HitTester } from "../canvas/HitTester";
+import { ImageCache } from "../canvas/ImageCache";
+import { PerformanceMonitor } from "../canvas/PerformanceMonitor";
+import { zoomAt, clampZoom, DEFAULT_ZOOM, screenToWorld } from "../canvas/Viewport";
+import type { BoardDocument } from "../elements/types";
+
+import { ToolController } from "../tools/ToolController";
+import type { ToolContext, ToolName } from "../tools/ToolContext";
+import { SelectTool } from "../tools/SelectTool";
+import { PanTool } from "../tools/PanTool";
+import { StickyTool, STICKY_COLORS, setLastStickyColor } from "../tools/StickyTool";
+import { TaskTool } from "../tools/TaskTool";
+import { ShapeTool } from "../tools/ShapeTool";
+import { TextTool } from "../tools/TextTool";
+import { ArrowTool } from "../tools/ArrowTool";
+import { ImageTool } from "../tools/ImageTool";
+
+import { boardStore } from "../storage/LocalBoardStore";
+import { assetStore } from "../storage/AssetStore";
+import { serializeBoard } from "../storage/BoardSerializer";
+import { importExportService } from "../storage/ImportExportService";
+
+import { Toolbar } from "../ui/Toolbar";
+import { TopControls } from "../ui/TopControls";
+import { TextEditorOverlay } from "../ui/TextEditorOverlay";
+import { openTemplatePicker } from "../ui/TemplatePicker";
+import { openStorageManager } from "../ui/StorageManager";
+import { PerformanceOverlay } from "../ui/PerformanceOverlay";
+import { openModal, showToast } from "../ui/Modal";
+
+import { StressTestGenerator } from "../testing/StressTestGenerator";
+import { StressTestPanel } from "../testing/StressTestPanel";
+import { invalidateTextCache } from "../elements/renderElement";
+
+const BOARD_SAVE_DEBOUNCE = 300;
+const VIEWPORT_SAVE_DEBOUNCE = 1000;
+const TEXT_SIZE_PRESETS = [
+  { label: "Small", shortLabel: "S", fontSize: 13, fontWeight: "400" },
+  { label: "Body", shortLabel: "Body", fontSize: 16, fontWeight: "400" },
+  { label: "H3", shortLabel: "H3", fontSize: 18, fontWeight: "650" },
+  { label: "H2", shortLabel: "H2", fontSize: 24, fontWeight: "700" },
+  { label: "H1", shortLabel: "H1", fontSize: 32, fontWeight: "750" },
+];
+const TEXT_CAPABLE_TYPES = new Set(["text"]);
+const SHAPE_TYPES = new Set(["rectangle", "ellipse", "frame"]);
+const SHAPE_FILL_COLORS = ["#0078d4", "#4dabf7", "#6e6e6e", "#ffffff", "#0f0f0f", "#fef08a", "#93c5fd", "#fca5a5"];
+const SHAPE_TEXT_COLORS = [
+  { label: "Black text", value: "#1f2933" },
+  { label: "White text", value: "#ffffff" },
+];
+
+/**
+ * Optional configuration. With no options the controller still supports the
+ * legacy standalone IndexedDB-backed board mode. When file-backed options are
+ * passed (by the Docs shell) it loads/saves a board through repo files and
+ * uploads pasted images into the active docs root instead of IndexedDB.
+ */
+export type AppOptions = {
+  boardId?: string;
+  loadBoard?: (id: string) => Promise<BoardDocument | undefined>;
+  saveBoard?: (doc: BoardDocument) => Promise<void>;
+  deleteBoard?: (id: string) => Promise<void>;
+  /** Persist an image blob to disk; returns the relative `src` path to store. */
+  uploadImage?: (blob: Blob, name?: string) => Promise<string>;
+  /** Resolve a board image src path inside the active docs root. */
+  resolveAssetUrl?: (src: string) => string;
+  /** Optional world-space region to fit when opening a board from an embed. */
+  initialRegion?: [number, number, number, number];
+  onExit?: () => void;
+  onDeleted?: () => void;
+};
+
+export class AppController {
+  state = new BoardState();
+  commands = new CommandManager();
+  surface: CanvasSurface;
+  renderer: CanvasRenderer;
+  scheduler: RenderScheduler;
+  hitTester: HitTester;
+  imageCache: ImageCache;
+  monitor = new PerformanceMonitor();
+
+  actions: ElementActions;
+  imageInsert: ImageInsertService;
+  toolController!: ToolController;
+  textEditor: TextEditorOverlay;
+
+  toolbar!: Toolbar;
+  topControls!: TopControls;
+  perfOverlay!: PerformanceOverlay;
+  stressPanel!: StressTestPanel;
+
+  private boardSaveTimer: number | null = null;
+  private viewportSaveTimer: number | null = null;
+  private options: AppOptions;
+  private listenerAbort = new AbortController();
+  private root: HTMLElement;
+  private bottomToolCluster: HTMLElement | null = null;
+  private stickyColorPopover: HTMLElement | null = null;
+  private textSizePopover: HTMLElement | null = null;
+  private shapeStylePopover: HTMLElement | null = null;
+  private layerMenu: HTMLElement | null = null;
+
+  constructor(root: HTMLElement, options: AppOptions = {}) {
+    this.root = root;
+    this.options = options;
+    if (options.boardId) this.state.boardId = options.boardId;
+    const signal = this.listenerAbort.signal;
+    this.surface = new CanvasSurface(root, 3, signal);
+    this.imageCache = new ImageCache(
+      assetStore,
+      () => this.state.requestRender(),
+      options.resolveAssetUrl
+    );
+    this.renderer = new CanvasRenderer(this.surface, this.state, this.imageCache);
+    this.scheduler = new RenderScheduler(() => this.renderer.render());
+    this.hitTester = new HitTester(this.state);
+    this.actions = new ElementActions(this.state, this.commands);
+    this.textEditor = new TextEditorOverlay(this.state, this.commands);
+    this.imageInsert = new ImageInsertService(
+      this.state,
+      this.commands,
+      this.imageCache,
+      showToast,
+      options.uploadImage
+    );
+
+    this.state.onRenderNeeded(() => {
+      this.scheduler.requestRender();
+      this.topControls?.setZoom(this.state.viewport.scale);
+      this.scheduleViewportSave();
+      this.updateContextualToolPanels();
+    });
+    this.state.onChange(() => this.scheduleBoardSave());
+    this.surface.onResize(() => this.state.requestRender());
+
+    this.setupTools(root, signal);
+    this.setupUi(root);
+    this.setupSelectionOverlays(root, signal);
+    this.setupDragDrop(root);
+    new ClipboardService(this.state, this.actions, this.imageInsert, signal);
+
+    bindKeyboardShortcuts(
+      {
+        state: this.state,
+        commands: this.commands,
+        actions: this.actions,
+        toolController: this.toolController,
+        resetView: () => this.resetView(),
+      },
+      signal
+    );
+
+    void this.loadInitialState();
+  }
+
+  /**
+   * Tear down all window-level listeners and free image bitmaps. The host is
+   * expected to remove the editor's root container afterwards (which disposes
+   * the canvas/DOM listeners attached to it).
+   */
+  destroy(): void {
+    if (this.boardSaveTimer !== null) clearTimeout(this.boardSaveTimer);
+    if (this.viewportSaveTimer !== null) clearTimeout(this.viewportSaveTimer);
+    this.listenerAbort.abort();
+    this.imageCache.clear();
+  }
+
+  // ---------- setup ----------
+
+  private setupTools(root: HTMLElement, signal?: AbortSignal): void {
+    const ctx: ToolContext = {
+      state: this.state,
+      renderer: this.renderer,
+      surface: this.surface,
+      hitTester: this.hitTester,
+      commands: this.commands,
+      setTool: (tool) => this.toolController.setTool(tool),
+      setCursor: (cursor) => {
+        this.surface.container.style.cursor = cursor;
+      },
+      openTextEditor: (el) => this.textEditor.open(el),
+    };
+
+    this.toolController = new ToolController(
+      this.surface.container,
+      ctx,
+      [
+        new SelectTool(),
+        new PanTool(),
+        new StickyTool(),
+        new TaskTool(),
+        new ShapeTool("rectangle"),
+        new ShapeTool("ellipse"),
+        new ShapeTool("diamond"),
+        new ShapeTool("triangle"),
+        new ShapeTool("pill"),
+        new ShapeTool("chevron"),
+        new TextTool(),
+        new ArrowTool(),
+        new ImageTool((files, x, y) => void this.imageInsert.insertFiles(files, x, y)),
+      ],
+      signal
+    );
+
+    this.toolController.onToolChange((tool: ToolName) => {
+      this.toolbar?.setActiveTool(tool);
+    });
+  }
+
+  private setupUi(root: HTMLElement): void {
+    this.toolbar = new Toolbar(root, {
+      setTool: (tool) => this.toolController.setTool(tool),
+      openTemplates: () => openTemplatePicker(this.state, this.commands),
+      toggleTheme: () => this.toggleTheme(),
+      openExportMenu: () => this.openExportMenu(),
+      toggleStressPanel: () => this.stressPanel.toggle(),
+      // Embed tool only makes sense for file-backed boards (the doc shell).
+      copyEmbed: this.options.onExit ? () => this.startEmbedSelection() : undefined,
+    });
+    this.toolbar.setActiveTool("select");
+
+    this.topControls = new TopControls(
+      root,
+      {
+        onExit: this.options.onExit ? () => this.exitToDocs() : undefined,
+        resetView: () => this.resetView(),
+        zoomIn: () => {
+          zoomAt(this.state.viewport, window.innerWidth / 2, window.innerHeight / 2, this.state.viewport.scale * 1.2);
+          this.state.requestRender();
+        },
+        zoomOut: () => {
+          zoomAt(this.state.viewport, window.innerWidth / 2, window.innerHeight / 2, this.state.viewport.scale / 1.2);
+          this.state.requestRender();
+        },
+        openStorageManager: () =>
+          openStorageManager(
+            this.state,
+            () => this.clearBoard(),
+            () => void this.resetAllLocalData()
+          ),
+        togglePerfOverlay: () => this.perfOverlay.toggle(),
+        deleteBoard: this.options.deleteBoard ? () => this.confirmDeleteBoard() : undefined,
+        onTitleChange: (title) => {
+          this.state.title = title;
+          this.state.emitChange();
+        },
+      },
+      this.state.title
+    );
+
+    this.perfOverlay = new PerformanceOverlay(
+      root,
+      this.state,
+      this.renderer,
+      this.hitTester,
+      this.monitor,
+      this.imageCache
+    );
+
+    const generator = new StressTestGenerator(this.state);
+    this.stressPanel = new StressTestPanel(root, generator, this.renderer);
+  }
+
+  private setupSelectionOverlays(root: HTMLElement, signal: AbortSignal): void {
+    this.bottomToolCluster = document.createElement("div");
+    this.bottomToolCluster.className = "bottom-tool-cluster";
+    root.appendChild(this.bottomToolCluster);
+    this.bottomToolCluster.appendChild(this.toolbar.element);
+
+    this.stickyColorPopover = document.createElement("div");
+    this.stickyColorPopover.className = "context-tool-popover sticky-color-popover";
+    this.stickyColorPopover.setAttribute("aria-hidden", "true");
+    for (const color of STICKY_COLORS) {
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.className = "sticky-color-btn";
+      btn.title = "Set sticky color";
+      btn.setAttribute("aria-label", `Set sticky color ${color}`);
+      btn.style.setProperty("--swatch", color);
+      btn.addEventListener("click", () => this.setSelectedStickyColor(color));
+      this.stickyColorPopover.appendChild(btn);
+    }
+    this.bottomToolCluster.appendChild(this.stickyColorPopover);
+
+    this.textSizePopover = document.createElement("div");
+    this.textSizePopover.className = "context-tool-popover text-size-popover";
+    this.textSizePopover.setAttribute("aria-hidden", "true");
+    for (const preset of TEXT_SIZE_PRESETS) {
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.className = "text-size-btn";
+      btn.textContent = preset.shortLabel;
+      btn.setAttribute("aria-label", `Set text size ${preset.label}`);
+      btn.addEventListener("click", () => this.setSelectedTextSize(preset));
+      this.textSizePopover.appendChild(btn);
+    }
+    this.bottomToolCluster.appendChild(this.textSizePopover);
+
+    this.shapeStylePopover = document.createElement("div");
+    this.shapeStylePopover.className = "context-tool-popover shape-style-popover";
+    this.shapeStylePopover.setAttribute("aria-hidden", "true");
+    for (const color of SHAPE_FILL_COLORS) {
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.className = "shape-fill-btn";
+      btn.title = "Set shape color";
+      btn.setAttribute("aria-label", `Set shape color ${color}`);
+      btn.style.setProperty("--swatch", color);
+      btn.addEventListener("click", () => this.setSelectedShapeFill(color));
+      this.shapeStylePopover.appendChild(btn);
+    }
+    const divider = document.createElement("div");
+    divider.className = "context-tool-divider";
+    this.shapeStylePopover.appendChild(divider);
+    for (const color of SHAPE_TEXT_COLORS) {
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.className = "shape-text-color-btn";
+      btn.textContent = color.value === "#ffffff" ? "W" : "B";
+      btn.setAttribute("aria-label", color.label);
+      btn.addEventListener("click", () => this.setSelectedShapeTextColor(color.value));
+      this.shapeStylePopover.appendChild(btn);
+    }
+    this.bottomToolCluster.appendChild(this.shapeStylePopover);
+
+    this.surface.interactionLayer.addEventListener(
+      "contextmenu",
+      (e) => this.openLayerMenu(e),
+      { signal, capture: true }
+    );
+
+    document.addEventListener(
+      "pointerdown",
+      (e) => {
+        if (this.layerMenu && !this.layerMenu.contains(e.target as Node)) this.closeLayerMenu();
+      },
+      { signal }
+    );
+    document.addEventListener(
+      "keydown",
+      (e) => {
+        if (e.key === "Escape") this.closeLayerMenu();
+      },
+      { signal }
+    );
+  }
+
+  private updateContextualToolPanels(): void {
+    this.updateStickyColorPopover();
+    this.updateTextSizePopover();
+    this.updateShapeStylePopover();
+  }
+
+  private setContextPanelVisible(panel: HTMLElement | null, isVisible: boolean): void {
+    if (!panel) return;
+    panel.classList.toggle("is-visible", isVisible);
+    panel.setAttribute("aria-hidden", String(!isVisible));
+  }
+
+  private updateStickyColorPopover(): void {
+    const popover = this.stickyColorPopover;
+    if (!popover) return;
+    const selectedStickies = this.state.getSelected().filter((el) => el.type === "sticky");
+    const shouldShow = selectedStickies.length > 0 && !this.textEditor.isEditing;
+    this.setContextPanelVisible(popover, shouldShow);
+    if (!shouldShow) return;
+
+    const activeFill = selectedStickies[0]?.style.fill;
+    for (const child of popover.children) {
+      const btn = child as HTMLButtonElement;
+      const isActive = btn.style.getPropertyValue("--swatch") === activeFill;
+      btn.classList.toggle("active", isActive);
+      btn.setAttribute("aria-pressed", String(isActive));
+    }
+  }
+
+  private setSelectedStickyColor(color: string): void {
+    setLastStickyColor(color);
+    const targets = this.state.getSelected().filter((el) => el.type === "sticky" && !el.locked);
+    if (targets.length === 0) return;
+    const state = this.state;
+    const before = targets.map((el) => ({
+      id: el.id,
+      fill: el.style.fill,
+      textColor: el.style.textColor,
+      updatedAt: el.updatedAt,
+    }));
+    const after = targets.map((el) => ({
+      id: el.id,
+      fill: color,
+      textColor: "#1f2933",
+      updatedAt: Date.now(),
+    }));
+    const apply = (snaps: typeof before): void => {
+      for (const snap of snaps) {
+        const el = state.elementsById.get(snap.id);
+        if (!el) continue;
+        el.style.fill = snap.fill;
+        el.style.textColor = snap.textColor;
+        el.updatedAt = snap.updatedAt;
+      }
+      state.emitChange();
+    };
+    this.commands.execute("sticky-color", () => apply(after), () => apply(before));
+  }
+
+  private updateTextSizePopover(): void {
+    const popover = this.textSizePopover;
+    if (!popover) return;
+    const targets = this.selectedTextTargets();
+    const shouldShow = targets.length > 0 && !this.textEditor.isEditing;
+    this.setContextPanelVisible(popover, shouldShow);
+    if (!shouldShow) return;
+
+    const activeSize = targets[0]?.style.fontSize ?? (targets[0]?.type === "sticky" ? 15 : 16);
+    for (const child of popover.children) {
+      const btn = child as HTMLButtonElement;
+      const preset = TEXT_SIZE_PRESETS.find((item) => item.shortLabel === btn.textContent);
+      const isActive = preset?.fontSize === activeSize;
+      btn.classList.toggle("active", isActive);
+      btn.setAttribute("aria-pressed", String(isActive));
+    }
+  }
+
+  private selectedTextTargets(): ReturnType<BoardState["getSelected"]> {
+    return this.state
+      .getSelected()
+      .filter((el) => TEXT_CAPABLE_TYPES.has(el.type) && !el.locked);
+  }
+
+  private setSelectedTextSize(preset: (typeof TEXT_SIZE_PRESETS)[number]): void {
+    const targets = this.selectedTextTargets();
+    if (targets.length === 0) return;
+    const state = this.state;
+    const before = targets.map((el) => ({
+      id: el.id,
+      fontSize: el.style.fontSize,
+      fontWeight: el.style.fontWeight,
+      height: el.height,
+      updatedAt: el.updatedAt,
+    }));
+    const after = targets.map((el) => ({
+      id: el.id,
+      fontSize: preset.fontSize,
+      fontWeight: preset.fontWeight,
+      height: el.type === "text" ? Math.max(el.height, Math.ceil(preset.fontSize * 1.45)) : el.height,
+      updatedAt: Date.now(),
+    }));
+    const apply = (snaps: typeof before): void => {
+      for (const snap of snaps) {
+        const el = state.elementsById.get(snap.id);
+        if (!el) continue;
+        el.style.fontSize = snap.fontSize;
+        el.style.fontWeight = snap.fontWeight;
+        el.height = snap.height;
+        el.updatedAt = snap.updatedAt;
+        invalidateTextCache(el.id);
+      }
+      state.emitChange();
+    };
+    this.commands.execute("text-size", () => apply(after), () => apply(before));
+  }
+
+  private updateShapeStylePopover(): void {
+    const popover = this.shapeStylePopover;
+    if (!popover) return;
+    const targets = this.selectedShapeTargets();
+    const shouldShow = targets.length > 0 && !this.textEditor.isEditing;
+    this.setContextPanelVisible(popover, shouldShow);
+    if (!shouldShow) return;
+
+    const activeFill = targets[0]?.style.fill;
+    const activeTextColor = targets[0]?.style.textColor ?? "#1f2933";
+    for (const child of popover.children) {
+      const el = child as HTMLElement;
+      if (el.classList.contains("shape-fill-btn")) {
+        const isActive = el.style.getPropertyValue("--swatch") === activeFill;
+        el.classList.toggle("active", isActive);
+        el.setAttribute("aria-pressed", String(isActive));
+      }
+      if (el.classList.contains("shape-text-color-btn")) {
+        const isWhite = el.textContent === "W";
+        const isActive = isWhite ? activeTextColor === "#ffffff" : activeTextColor !== "#ffffff";
+        el.classList.toggle("active", isActive);
+        el.setAttribute("aria-pressed", String(isActive));
+      }
+    }
+  }
+
+  private selectedShapeTargets(): ReturnType<BoardState["getSelected"]> {
+    return this.state
+      .getSelected()
+      .filter((el) => SHAPE_TYPES.has(el.type) && !el.locked);
+  }
+
+  private setSelectedShapeFill(color: string): void {
+    const targets = this.selectedShapeTargets();
+    if (targets.length === 0) return;
+    const state = this.state;
+    const before = targets.map((el) => ({ id: el.id, fill: el.style.fill, updatedAt: el.updatedAt }));
+    const after = targets.map((el) => ({ id: el.id, fill: color, updatedAt: Date.now() }));
+    const apply = (snaps: typeof before): void => {
+      for (const snap of snaps) {
+        const el = state.elementsById.get(snap.id);
+        if (!el) continue;
+        el.style.fill = snap.fill;
+        el.updatedAt = snap.updatedAt;
+      }
+      state.emitChange();
+    };
+    this.commands.execute("shape-fill", () => apply(after), () => apply(before));
+  }
+
+  private setSelectedShapeTextColor(color: string): void {
+    const targets = this.selectedShapeTargets();
+    if (targets.length === 0) return;
+    const state = this.state;
+    const before = targets.map((el) => ({ id: el.id, textColor: el.style.textColor, updatedAt: el.updatedAt }));
+    const after = targets.map((el) => ({ id: el.id, textColor: color, updatedAt: Date.now() }));
+    const apply = (snaps: typeof before): void => {
+      for (const snap of snaps) {
+        const el = state.elementsById.get(snap.id);
+        if (!el) continue;
+        el.style.textColor = snap.textColor;
+        el.updatedAt = snap.updatedAt;
+        invalidateTextCache(el.id);
+      }
+      state.emitChange();
+    };
+    this.commands.execute("shape-text-color", () => apply(after), () => apply(before));
+  }
+
+  private openLayerMenu(e: MouseEvent): void {
+    e.preventDefault();
+    e.stopPropagation();
+    if (this.textEditor.isEditing) return;
+
+    const world = screenToWorld(e.clientX, e.clientY, this.state.viewport);
+    const hit = this.hitTester.hitTest(world.x, world.y, this.state.viewport.scale);
+    if (hit && !this.state.selectedIds.has(hit.id)) {
+      this.state.clearSelection();
+      this.state.selectedIds.add(hit.id);
+      this.state.requestRender();
+    }
+
+    const selected = this.state.getSelected();
+    if (selected.length === 0) {
+      this.closeLayerMenu();
+      return;
+    }
+
+    this.closeLayerMenu();
+    const menu = document.createElement("div");
+    menu.className = "layer-menu";
+    menu.setAttribute("role", "menu");
+    const label = document.createElement("div");
+    label.className = "layer-menu-label";
+    label.textContent = selected.length === 1 ? "Layer" : `${selected.length} layers`;
+    menu.appendChild(label);
+
+    const addAction = (text: string, action: () => void) => {
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.setAttribute("role", "menuitem");
+      btn.textContent = text;
+      btn.addEventListener("click", () => {
+        action();
+        this.closeLayerMenu();
+      });
+      menu.appendChild(btn);
+    };
+    const addDivider = () => {
+      const div = document.createElement("div");
+      div.className = "layer-menu-divider";
+      menu.appendChild(div);
+    };
+
+    addAction("Bring forward", () => this.actions.bringForward());
+    addAction("Send backward", () => this.actions.sendBackward());
+    addDivider();
+    addAction("Bring to front", () => this.actions.bringToFront());
+    addAction("Send to back", () => this.actions.sendToBack());
+
+    this.root.appendChild(menu);
+    this.layerMenu = menu;
+    this.positionLayerMenu(menu, e.clientX, e.clientY);
+  }
+
+  private positionLayerMenu(menu: HTMLElement, x: number, y: number): void {
+    const margin = 12;
+    menu.style.left = "0px";
+    menu.style.top = "0px";
+    requestAnimationFrame(() => {
+      const rect = menu.getBoundingClientRect();
+      const left = Math.min(Math.max(margin, x), window.innerWidth - rect.width - margin);
+      const top = Math.min(Math.max(margin, y), window.innerHeight - rect.height - margin);
+      menu.style.left = `${left}px`;
+      menu.style.top = `${top}px`;
+    });
+  }
+
+  private closeLayerMenu(): void {
+    this.layerMenu?.remove();
+    this.layerMenu = null;
+  }
+
+  /** Save, then hand control back to the docs shell. */
+  private exitToDocs(): void {
+    if (this.boardSaveTimer !== null) {
+      clearTimeout(this.boardSaveTimer);
+      this.boardSaveTimer = null;
+    }
+    void this.saveBoard().finally(() => this.options.onExit?.());
+  }
+
+  /**
+   * Launch the drag-to-select overlay. The user draws a rectangle over the
+   * board; that screen rectangle is converted to a world-space region and a
+   * `board` embed snippet is copied to the clipboard automatically.
+   */
+  private startEmbedSelection(): void {
+    EmbedRegionSelector.begin(this.root, (rect) => {
+      if (rect) void this.copyEmbedSnippet(rect);
+    });
+  }
+
+  /** Build a `board` markdown directive for the given screen rectangle. */
+  private async copyEmbedSnippet(rect: ScreenRect): Promise<void> {
+    const vp = this.state.viewport;
+    const topLeft = screenToWorld(rect.x, rect.y, vp);
+    const bottomRight = screenToWorld(rect.x + rect.w, rect.y + rect.h, vp);
+    const x = Math.round(topLeft.x);
+    const y = Math.round(topLeft.y);
+    const w = Math.round(bottomRight.x - topLeft.x);
+    const h = Math.round(bottomRight.y - topLeft.y);
+    const snippet =
+      "```board\n" +
+      `src: /${this.state.boardId}\n` +
+      `region: ${x}, ${y}, ${w}, ${h}\n` +
+      "height: 360\n" +
+      `title: ${this.state.title}\n` +
+      "```";
+    try {
+      await navigator.clipboard.writeText(snippet);
+      showToast("Embed snippet copied — paste it into any doc");
+    } catch {
+      showToast("Could not access clipboard");
+    }
+  }
+
+  private setupDragDrop(root: HTMLElement): void {
+    root.addEventListener("dragover", (e) => {
+      e.preventDefault();
+      if (e.dataTransfer) e.dataTransfer.dropEffect = "copy";
+    });
+    root.addEventListener("drop", (e) => {
+      e.preventDefault();
+      if (e.dataTransfer?.files && e.dataTransfer.files.length > 0) {
+        void this.imageInsert.insertFiles(e.dataTransfer.files, e.clientX, e.clientY);
+      }
+    });
+  }
+
+  // ---------- persistence ----------
+
+  private async loadInitialState(): Promise<void> {
+    // theme first (instant)
+    const savedTheme = boardStore.getPref("theme");
+    if (savedTheme === "dark" || savedTheme === "light") {
+      this.applyTheme(savedTheme);
+    } else if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
+      this.applyTheme("dark");
+    }
+
+    // File-backed mode: load the specific board through the injected loader.
+    if (this.options.loadBoard) {
+      try {
+        const doc = await this.options.loadBoard(this.options.boardId ?? this.state.boardId);
+        if (doc) {
+          this.applyDocument(doc);
+          this.fitInitialRegion();
+        }
+      } catch (err) {
+        console.error("Board file load failed", err);
+        showToast("Could not load board file");
+      }
+      this.state.requestRender();
+      return;
+    }
+
+    const lastBoardId = boardStore.getPref("lastBoardId") ?? "default-board";
+    try {
+      const doc = await boardStore.loadBoard(lastBoardId);
+      if (doc) this.applyDocument(doc);
+    } catch (err) {
+      console.error("Board recovery failed", err);
+      const recovery = boardStore.getPref("recovery");
+      if (recovery) {
+        showToast("Could not load saved board — starting fresh");
+      }
+    }
+    this.state.requestRender();
+  }
+
+  private applyDocument(doc: BoardDocument): void {
+    this.state.boardId = doc.id;
+    this.state.title = doc.title;
+    this.state.createdAt = doc.createdAt;
+    this.state.viewport = { ...doc.viewport };
+    this.state.elements = [];
+    this.state.elementsById.clear();
+    for (const el of doc.elements) this.state.addElement(el);
+    this.applyTheme(doc.theme);
+    this.topControls.setTitle(doc.title);
+    this.topControls.setZoom(doc.viewport.scale);
+    this.state.invalidateSort();
+  }
+
+  private fitInitialRegion(): void {
+    const region = this.options.initialRegion;
+    if (!region) return;
+    const [x, y, w, h] = region;
+    if (w <= 0 || h <= 0) return;
+
+    const marginX = Math.min(120, Math.max(48, this.surface.width * 0.08));
+    const topMargin = 88;
+    const bottomMargin = 124;
+    const availableW = Math.max(240, this.surface.width - marginX * 2);
+    const availableH = Math.max(180, this.surface.height - topMargin - bottomMargin);
+    const fitScale = Math.min(availableW / w, availableH / h);
+    const maxComfortScale = Math.max(0.7, Math.min(1.1, this.state.viewport.scale * 1.15));
+    const scale = clampZoom(Math.min(fitScale * 0.58, maxComfortScale));
+
+    this.state.viewport = {
+      scale,
+      offsetX: marginX + (availableW - w * scale) / 2 - x * scale,
+      offsetY: topMargin + (availableH - h * scale) / 2 - y * scale,
+    };
+    this.topControls.setZoom(scale);
+  }
+
+  private scheduleBoardSave(): void {
+    if (this.boardSaveTimer !== null) clearTimeout(this.boardSaveTimer);
+    this.boardSaveTimer = window.setTimeout(() => {
+      this.boardSaveTimer = null;
+      void this.saveBoard();
+    }, BOARD_SAVE_DEBOUNCE);
+  }
+
+  private scheduleViewportSave(): void {
+    if (this.viewportSaveTimer !== null) return;
+    this.viewportSaveTimer = window.setTimeout(() => {
+      this.viewportSaveTimer = null;
+      void this.saveBoard();
+    }, VIEWPORT_SAVE_DEBOUNCE);
+  }
+
+  private async saveBoard(): Promise<void> {
+    try {
+      if (this.options.saveBoard) {
+        await this.options.saveBoard(serializeBoard(this.state));
+      } else {
+        await boardStore.saveBoard(serializeBoard(this.state));
+      }
+    } catch {
+      showToast(this.options.saveBoard ? "Save to file failed" : "Save failed — browser storage may be full");
+    }
+  }
+
+  // ---------- theme ----------
+
+  applyTheme(theme: "light" | "dark"): void {
+    this.state.theme = theme;
+    document.documentElement.setAttribute("data-theme", theme);
+    boardStore.setPref("theme", theme);
+    this.toolbar?.setTheme(theme);
+    this.state.requestRender();
+  }
+
+  toggleTheme(): void {
+    this.applyTheme(this.state.theme === "dark" ? "light" : "dark");
+    this.scheduleBoardSave();
+  }
+
+  // ---------- view ----------
+
+  resetView(): void {
+    this.state.viewport.offsetX = 0;
+    this.state.viewport.offsetY = 0;
+    this.state.viewport.scale = DEFAULT_ZOOM;
+    this.state.requestRender();
+  }
+
+  // ---------- board management ----------
+
+  clearBoard(): void {
+    const state = this.state;
+    const removed = [...state.elements];
+    this.commands.execute(
+      "clear-board",
+      () => {
+        for (const el of removed) state.removeElement(el.id);
+        state.emitChange();
+      },
+      () => {
+        for (const el of removed) {
+          if (!state.elementsById.has(el.id)) state.addElement(el);
+        }
+        state.emitChange();
+      }
+    );
+    showToast("Board cleared");
+  }
+
+  async resetAllLocalData(): Promise<void> {
+    await boardStore.clearAllBoards();
+    await assetStore.clearAll();
+    boardStore.clearPrefs();
+    this.imageCache.clear();
+    this.commands.clear();
+    this.state.elements = [];
+    this.state.elementsById.clear();
+    this.state.clearSelection();
+    this.state.invalidateSort();
+    this.resetView();
+    showToast("All local data cleared");
+  }
+
+  private confirmDeleteBoard(): void {
+    openModal("Delete board?", (body, close) => {
+      const p = document.createElement("p");
+      p.className = "modal-copy";
+      p.textContent = `This will permanently delete "${this.state.title}" from the active docs root. This cannot be undone.`;
+      const actions = document.createElement("div");
+      actions.className = "modal-actions";
+      const cancel = document.createElement("button");
+      cancel.className = "btn";
+      cancel.textContent = "Cancel";
+      cancel.addEventListener("click", close);
+      const del = document.createElement("button");
+      del.className = "btn danger";
+      del.textContent = "Delete board";
+      del.addEventListener("click", async () => {
+        del.disabled = true;
+        if (this.boardSaveTimer !== null) {
+          clearTimeout(this.boardSaveTimer);
+          this.boardSaveTimer = null;
+        }
+        if (this.viewportSaveTimer !== null) {
+          clearTimeout(this.viewportSaveTimer);
+          this.viewportSaveTimer = null;
+        }
+        try {
+          await this.options.deleteBoard?.(this.state.boardId);
+          close();
+          showToast("Board deleted");
+          (this.options.onDeleted ?? this.options.onExit)?.();
+        } catch {
+          del.disabled = false;
+          showToast("Could not delete board");
+        }
+      });
+      actions.append(cancel, del);
+      body.append(p, actions);
+    });
+  }
+
+  // ---------- export / import ----------
+
+  private openExportMenu(): void {
+    openModal("Export & import", (body, close) => {
+      const actions = document.createElement("div");
+      actions.className = "modal-actions";
+      actions.style.flexDirection = "column";
+      actions.style.alignItems = "stretch";
+
+      const addAction = (label: string, fn: () => void | Promise<void>, primary = false) => {
+        const btn = document.createElement("button");
+        btn.className = "btn" + (primary ? " primary" : "");
+        btn.textContent = label;
+        btn.addEventListener("click", () => {
+          void fn();
+          close();
+        });
+        actions.appendChild(btn);
+      };
+
+      addAction("Export current view as PNG", async () => {
+        const blob = await exportViewportPng(this.state, this.imageCache, this.surface.width, this.surface.height);
+        downloadBlob(blob, this.state.title + "-view.png");
+      }, true);
+
+      addAction("Export full board as PNG", async () => {
+        const blob = await exportFullBoardPng(this.state, this.imageCache);
+        if (blob) downloadBlob(blob, this.state.title + "-board.png");
+        else showToast("Board is empty");
+      });
+
+      addAction("Export board JSON (no images)", () => {
+        importExportService.exportBoardJson(serializeBoard(this.state));
+      });
+
+      addAction("Export full bundle (JSON + images)", async () => {
+        await importExportService.exportFullBundle(serializeBoard(this.state));
+      });
+
+      addAction("Import board from file…", () => this.pickImportFile());
+
+      body.appendChild(actions);
+    });
+  }
+
+  private pickImportFile(): void {
+    const input = document.createElement("input");
+    input.type = "file";
+    input.accept = "application/json,.json";
+    input.onchange = async () => {
+      const file = input.files?.[0];
+      if (!file) return;
+      const doc = await importExportService.importFromFile(file);
+      if (!doc) {
+        showToast("Import failed — invalid board file");
+        return;
+      }
+      // replace current board only after successful validation
+      this.state.boardId = doc.id;
+      this.state.title = doc.title;
+      this.state.createdAt = doc.createdAt;
+      this.state.viewport = { ...doc.viewport };
+      this.state.elements = [];
+      this.state.elementsById.clear();
+      this.state.clearSelection();
+      for (const el of doc.elements) this.state.addElement(el);
+      this.applyTheme(doc.theme);
+      this.topControls.setTitle(doc.title);
+      this.commands.clear();
+      this.state.emitChange();
+      showToast("Board imported");
+    };
+    input.click();
+  }
+}