chalkbridge 1.0.0 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# chalkbridge
+
+## 1.0.3
+
+**An upgrade now actually arrives, a bridge can be stopped, and it ends when you are
+done with it.**
+
+(1.0.2 was built and verified but never published — everything below shipped as 1.0.3.)
+
+The bridge is spawned detached and outlives the session that started it — deliberately,
+because writes have to succeed with no browser connected. But `ensureBridge` reused
+whatever was already listening without ever checking its version, so `npx -y chalkbridge
+mcp` would fetch a new package, find the **old** bridge still answering, and reuse it.
+Every fix would ship and none would arrive, silently. If 1.0.1 seemed not to change
+anything for you, that is why.
+
+- **A bridge from another build is replaced.** It is asked to stop first, so its pending
+  `.excalidraw` write still reaches the disk.
+- **`chalkbridge stop`** ends the bridge for the current repo, flushing anything unsaved.
+  Until now the only options were a reboot or hunting the pid.
+- **`POST /api/shutdown`** is what both use — a request rather than a signal, because on
+  Windows a signal from another process terminates outright and the flush never happens.
+- **A pid fallback for bridges built before this release.** 1.0.0 and 1.0.1 have no
+  shutdown endpoint, so the polite path is unavailable for exactly the bridges an upgrade
+  has to replace. Without it, upgrading from either would leave the new build unable to
+  start at all. Found by running the published 1.0.1 against a local build.
+
+**And it ends when you are done with it.** Until now a bridge ran until the machine
+restarted — one per repo, forever — which is not what anybody expects after closing a chat
+and a tab. It now exits when nothing is watching *and* nothing is asking, for 90 seconds:
+
+| | |
+|---|---|
+| chat closed, tab closed | exits |
+| tab refreshed | reconnects in about a second, so it stays |
+| chat closed, tab still open | stays — somebody is looking at the canvas |
+| Claude drawing with no tab open | every tool call counts, so it stays |
+| two chats on one repo | activity keeps it alive |
+
+One rule, no session counting. `CHALK_IDLE_TIMEOUT` tunes it and `0` restores the old
+behaviour.
+
+**A tool call now survives its own bridge.** That is what makes the above invisible: if a
+bridge has given up, the next call re-runs the bootstrap — spawning one and reopening the
+canvas — instead of failing. Previously a bridge lost mid-session meant every call failed
+until Claude Code was restarted.
+
+After this release, updating really is just restarting Claude Code.
+
+## 1.0.1
+
+**Arrows are drawn where they belong, the first time.**
+
+Six bugs of the same family, all found by drawing one real diagram — 29 boxes, 34 arrows —
+which cost roughly forty tool calls of workaround. Every one of them answered `applied`
+and then did less than that, which is the most expensive shape a bug can have: the caller
+spends its next calls re-reading to find out why.
+
+- **`chalk_connect` now places the arrow.** The expander returns a stub at the origin with
+  `points: [[0.5, 0], [99.5, 0]]` — the bindings were correct and the geometry was a
+  placeholder — so every new arrow landed in the same corner and looked like a scribble.
+- **`chalk_update_elements` redraws the arrows of a box it moved**, and brings the box's
+  caption with it. Only `chalk_arrange` used to do either, so the only way to repair a
+  diagram was to displace every element and align it back, one row at a time.
+- **`chalk_frame` works more than once.** Upstream rebuilds a frame from its `children`,
+  which a frame that already exists does not have, so it threw — and *every second frame
+  failed*, whatever was in it.
+- **`patch.role` restyles** instead of writing a junk `role` field onto the element.
+  Explicit properties still win over what the role implies.
+- **`patch.label` renames the caption** instead of writing a junk `label` field, and says
+  so plainly when there is no caption to rename rather than silently doing nothing.
+- **Deleting a container tombstones its caption**, instead of leaving a word floating on
+  the canvas that nothing owns.
+
+`applied` and `deleted` now list only the ids you asked about. A caption that followed its
+box is a consequence, not a result you should have to reason about.
+
+No schema changes — every tool takes and returns exactly what it did in 1.0.0.
+
+## 1.0.0
+
+First release.
+
+A self-hosted Excalidraw canvas that Claude Code can read and draw on. The canvas opens in
+your browser, you select on it and ask in the terminal, and the diagram is a plain
+`.excalidraw` file in your repository.
+
+- **Read** — `chalk_describe_scene` renders the canvas as a compact text form, 3.7× smaller
+  than the same structure as JSON. `chalk_get_selection` answers "what are these?"
+  including the edges that cross the selection boundary.
+- **Draw** — boxes by `role` rather than by colour, arrows bound to their boxes, layered
+  graph layout, frames, groups, annotations. Writes succeed with no browser connected.
+- **Illustrate** — a machine-wide icon catalog with FTS5 search; a hand-drawn set is
+  bundled and `chalk_install_pack("devicon")` adds technology logos in one call. Vendor
+  sets return instructions and are never downloaded for you.
+- **Export** — PNG and SVG rendered by your own browser, and `.excalidraw` written where
+  you asked.
+- **Undo** — labelled snapshots.
+
+Node 22 or newer. No native modules, no container, nothing leaves the machine.

package/README.md

@@ -53,10 +53,26 @@ reach loopback. Do not work around it by binding a wider address.
 ```bash
 chalkbridge health              # what is running for this repository
 chalkbridge serve               # start the bridge by hand
+chalkbridge stop                # end it, flushing anything unsaved
 chalkbridge icons list          # what is in the machine-wide icon catalog
 chalkbridge icons install devicon
 ```
 
+**The bridge is spawned detached and outlives your session** — deliberately, because
+writes have to succeed with no browser connected. It ends when nothing is watching *and*
+nothing is asking:
+
+| | |
+|---|---|
+| chat closed, tab closed | exits after 90 seconds |
+| tab refreshed | reconnects in about a second, so it stays |
+| chat closed, tab still open | stays — you are still looking at the canvas |
+| Claude drawing with no tab | every tool call counts, so it stays |
+
+If it has already given up, the next tool call brings it back and reopens the canvas, so
+you never have to think about it. `chalkbridge stop` ends one now; `CHALK_IDLE_TIMEOUT`
+tunes the ninety seconds, and `0` keeps it up forever.
+
 `CHALK_NO_AUTOSTART=1` and `CHALK_NO_OPEN=1` turn off the two automatic behaviours;
 `CHALK_PORT` pins the port; `CHALK_DATA_DIR` moves the icon catalog.
 

package/dist/{chunk-HFKCLTVU.js → chunk-VTFAXWQJ.js}

@@ -1248,6 +1248,14 @@ var bridgeUnreachable = (port) => port === null ? err("BRIDGE_UNREACHABLE", "no
   hint: "the bridge may have exited \u2014 `chalkbridge health` reports what is running",
   detail: { port }
 });
+var bridgeVersionMismatch = (running, ours, port) => err(
+  "BRIDGE_VERSION_MISMATCH",
+  `a Chalkbridge ${running} bridge is running on 127.0.0.1:${port} and this is ${ours}`,
+  {
+    hint: "it did not stop when asked \u2014 run `chalkbridge stop` in this repo, or end that process, and try again",
+    detail: { running, ours, port }
+  }
+);
 var portUnavailable = (from, tried) => err("PORT_UNAVAILABLE", `no free port between ${from} and ${from + tried - 1}`, {
   hint: "something is occupying the whole range \u2014 set CHALK_PORT to pick a different one",
   detail: { from, tried }
@@ -1266,6 +1274,11 @@ var unknownElement = (id) => err("UNKNOWN_ELEMENT", `no element ${id} in this sc
   tool: "chalk_describe_scene",
   detail: { id }
 });
+var noBoundLabel = (id) => err("NO_BOUND_LABEL", `element ${id} has no caption to rename`, {
+  hint: "draw it with a label in the first place, or put the text beside it with chalk_annotate",
+  tool: "chalk_annotate",
+  detail: { id }
+});
 var emptySelection = (tool) => err("EMPTY_SELECTION", "no elements named \u2014 there is nothing to act on", {
   hint: "pass the ids you mean, or call chalk_get_selection to find out what the user is pointing at",
   tool: "chalk_get_selection",
@@ -1453,7 +1466,8 @@ function createNodeSkeletonExpander() {
       if (!loaded.ok) return loaded;
       let raw;
       try {
-        raw = loaded.value([...context ?? [], ...skeletons], { regenerateIds: false });
+        const convertible = (context ?? []).filter((element) => element.type !== "frame");
+        raw = loaded.value([...convertible, ...skeletons], { regenerateIds: false });
       } catch (thrown) {
         return fail(expansionFailed(describeThrown(thrown)));
       }
@@ -1489,6 +1503,6 @@ var stable = (element) => {
   return rest;
 };
 
-export { AnnotateInput, AnnotateOutput, ApiError, ArrangeOutput, ArrangeToolInput, BINDING_FIELDS, ClientMessage, ConnectOutput, ConnectToolInput, CreateElementsInput, CreateElementsOutput, DebugElementRequest, DeleteElementsInput, DeleteElementsOutput, DescribeSceneInput, DescribeSceneOutput, DetailLevel, EXCALIDRAW_FILE_TYPE, EXCALIDRAW_FILE_VERSION, ElementId, EmbedInput, EmbedOutput, ExcalidrawFile, ExportImageInput, ExportImageOutput, ExportSceneInput, ExportSceneOutput, FLAG_GLYPH, FileId, FocusInput, FocusOutput, FrameId, FrameInput, FrameOutput, GUIDE_TOPICS, GetElementsInput, GetElementsOutput, GetSelectionInput, GetSelectionOutput, GroupId, GroupInput, GroupOutput, GuideTopic, HOUSE, HealthResponse, IconId, IconItem, ImportSceneInput, ImportSceneOutput, Index, InstallPackInput, InstallPackOutput, KIND_ABBREVIATION, ListPacksInput, ListPacksOutput, ListScenesInput, ListScenesOutput, PROTOCOL_VERSION, PackKind, PackName, PackRecipe, PlaceIconInput, PlaceIconOutput, ROUNDNESS, RawElementsInput, RawElementsOutput, ReadMeInput, ReadMeOutput, RemovePackInput, RemovePackOutput, RestoreSnapshotInput, RestoreSnapshotOutput, SERVER_MANAGED_FIELDS, STALE_SELECTION_MS, Scene, SceneElement, SceneId, SceneSettingsInput, SceneSettingsOutput, ScreenshotInput, ScreenshotOutput, ScreenshotResponse, SearchIconsInput, SearchIconsOutput, SnapshotId, SnapshotInput, SnapshotOutput, UngroupInput, UngroupOutput, UpdateElementsInput, UpdateElementsOutput, assertNever, bridgeSpawnFailed, bridgeUnreachable, catalogUnavailable, createNodeSkeletonExpander, deepEqual, describeThrown, diskConflict, emptySelection, expansionFailed, exportFailed, exportTimedOut, fail, frameIdOf, iconIdOf, idCollision, isFail, isOk, noBrowser, noScenes, notAPack, notARepo, ok, packInstallFailed, partition, pathOutsideRepo, point, portUnavailable, refusedFieldMessage, sceneFileMissing, staleVersion, storeUnavailable, unknownElement, unknownIcon, unknownScene, unknownSnapshot, unreadableSceneFile };
-//# sourceMappingURL=chunk-HFKCLTVU.js.map
-//# sourceMappingURL=chunk-HFKCLTVU.js.map
+export { AnnotateInput, AnnotateOutput, ApiError, ArrangeOutput, ArrangeToolInput, BINDING_FIELDS, ClientMessage, ConnectOutput, ConnectToolInput, CreateElementsInput, CreateElementsOutput, DebugElementRequest, DeleteElementsInput, DeleteElementsOutput, DescribeSceneInput, DescribeSceneOutput, DetailLevel, EXCALIDRAW_FILE_TYPE, EXCALIDRAW_FILE_VERSION, ElementId, EmbedInput, EmbedOutput, ExcalidrawFile, ExportImageInput, ExportImageOutput, ExportSceneInput, ExportSceneOutput, FLAG_GLYPH, FileId, FocusInput, FocusOutput, FrameId, FrameInput, FrameOutput, GUIDE_TOPICS, GetElementsInput, GetElementsOutput, GetSelectionInput, GetSelectionOutput, GroupId, GroupInput, GroupOutput, GuideTopic, HOUSE, HealthResponse, IconId, IconItem, ImportSceneInput, ImportSceneOutput, Index, InstallPackInput, InstallPackOutput, KIND_ABBREVIATION, ListPacksInput, ListPacksOutput, ListScenesInput, ListScenesOutput, PROTOCOL_VERSION, PackKind, PackName, PackRecipe, PlaceIconInput, PlaceIconOutput, ROUNDNESS, RawElementsInput, RawElementsOutput, ReadMeInput, ReadMeOutput, RemovePackInput, RemovePackOutput, RestoreSnapshotInput, RestoreSnapshotOutput, SERVER_MANAGED_FIELDS, STALE_SELECTION_MS, Scene, SceneElement, SceneId, SceneSettingsInput, SceneSettingsOutput, ScreenshotInput, ScreenshotOutput, ScreenshotResponse, SearchIconsInput, SearchIconsOutput, SnapshotId, SnapshotInput, SnapshotOutput, UngroupInput, UngroupOutput, UpdateElementsInput, UpdateElementsOutput, assertNever, bridgeSpawnFailed, bridgeUnreachable, bridgeVersionMismatch, catalogUnavailable, createNodeSkeletonExpander, deepEqual, describeThrown, diskConflict, emptySelection, expansionFailed, exportFailed, exportTimedOut, fail, frameIdOf, iconIdOf, idCollision, isFail, isOk, noBoundLabel, noBrowser, noScenes, notAPack, notARepo, ok, packInstallFailed, partition, pathOutsideRepo, point, portUnavailable, refusedFieldMessage, sceneFileMissing, staleVersion, storeUnavailable, unknownElement, unknownIcon, unknownScene, unknownSnapshot, unreadableSceneFile };
+//# sourceMappingURL=chunk-VTFAXWQJ.js.map
+//# sourceMappingURL=chunk-VTFAXWQJ.js.map

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { SceneElement, PackName, PackKind, IconId, SceneId, Scene, SnapshotId, SERVER_MANAGED_FIELDS, BINDING_FIELDS, GUIDE_TOPICS, DetailLevel, createNodeSkeletonExpander, ok, fail, bridgeSpawnFailed, bridgeUnreachable, GuideTopic, storeUnavailable, describeThrown, unreadableSceneFile, pathOutsideRepo, packInstallFailed, sceneFileMissing, notAPack, PackRecipe, portUnavailable, DescribeSceneOutput, DescribeSceneInput, GetSelectionOutput, GetSelectionInput, GetElementsOutput, GetElementsInput, ListScenesOutput, ListScenesInput, SceneSettingsOutput, SceneSettingsInput, SearchIconsOutput, SearchIconsInput, ScreenshotOutput, ScreenshotInput, ReadMeOutput, ReadMeInput, PlaceIconOutput, PlaceIconInput, SnapshotOutput, SnapshotInput, RestoreSnapshotOutput, RestoreSnapshotInput, ExportSceneOutput, ExportSceneInput, ImportSceneOutput, ImportSceneInput, ExportImageOutput, ExportImageInput, InstallPackOutput, InstallPackInput, notARepo, ScreenshotResponse, RemovePackOutput, ListPacksOutput, RawElementsOutput, FocusOutput, EmbedOutput, AnnotateOutput, FrameOutput, UngroupOutput, GroupOutput, ArrangeOutput, DeleteElementsOutput, UpdateElementsOutput, ConnectOutput, CreateElementsOutput, HealthResponse, iconIdOf, unknownScene, unknownSnapshot, exportFailed, unknownIcon, HOUSE, FileId, ElementId, diskConflict, refusedFieldMessage, idCollision, expansionFailed, emptySelection, unknownElement, frameIdOf, GroupId, staleVersion, deepEqual, exportTimedOut, noBrowser, DebugElementRequest, CreateElementsInput, ConnectToolInput, UpdateElementsInput, DeleteElementsInput, ArrangeToolInput, GroupInput, UngroupInput, FrameInput, AnnotateInput, EmbedInput, FocusInput, RawElementsInput, ListPacksInput, RemovePackInput, Index, ROUNDNESS, STALE_SELECTION_MS, noScenes, ClientMessage, assertNever, PROTOCOL_VERSION, ApiError, EXCALIDRAW_FILE_VERSION, EXCALIDRAW_FILE_TYPE, FLAG_GLYPH, point, KIND_ABBREVIATION, catalogUnavailable, FrameId, IconItem, ExcalidrawFile } from './chunk-HFKCLTVU.js';
+import { SceneElement, PackName, PackKind, IconId, SceneId, Scene, SnapshotId, SERVER_MANAGED_FIELDS, BINDING_FIELDS, GUIDE_TOPICS, DetailLevel, createNodeSkeletonExpander, ok, fail, bridgeSpawnFailed, bridgeVersionMismatch, bridgeUnreachable, GuideTopic, storeUnavailable, describeThrown, unreadableSceneFile, pathOutsideRepo, packInstallFailed, sceneFileMissing, notAPack, PackRecipe, portUnavailable, DescribeSceneOutput, DescribeSceneInput, GetSelectionOutput, GetSelectionInput, GetElementsOutput, GetElementsInput, ListScenesOutput, ListScenesInput, SceneSettingsOutput, SceneSettingsInput, SearchIconsOutput, SearchIconsInput, ScreenshotOutput, ScreenshotInput, ReadMeOutput, ReadMeInput, PlaceIconOutput, PlaceIconInput, SnapshotOutput, SnapshotInput, RestoreSnapshotOutput, RestoreSnapshotInput, ExportSceneOutput, ExportSceneInput, ImportSceneOutput, ImportSceneInput, ExportImageOutput, ExportImageInput, InstallPackOutput, InstallPackInput, notARepo, ScreenshotResponse, RemovePackOutput, ListPacksOutput, RawElementsOutput, FocusOutput, EmbedOutput, AnnotateOutput, FrameOutput, UngroupOutput, GroupOutput, ArrangeOutput, DeleteElementsOutput, UpdateElementsOutput, ConnectOutput, CreateElementsOutput, HealthResponse, iconIdOf, unknownScene, unknownSnapshot, exportFailed, unknownIcon, HOUSE, FileId, ElementId, diskConflict, refusedFieldMessage, idCollision, expansionFailed, emptySelection, unknownElement, frameIdOf, GroupId, staleVersion, noBoundLabel, deepEqual, exportTimedOut, noBrowser, DebugElementRequest, CreateElementsInput, ConnectToolInput, UpdateElementsInput, DeleteElementsInput, ArrangeToolInput, GroupInput, UngroupInput, FrameInput, AnnotateInput, EmbedInput, FocusInput, RawElementsInput, ListPacksInput, RemovePackInput, Index, ROUNDNESS, STALE_SELECTION_MS, noScenes, ClientMessage, assertNever, PROTOCOL_VERSION, ApiError, EXCALIDRAW_FILE_VERSION, EXCALIDRAW_FILE_TYPE, point, FLAG_GLYPH, KIND_ABBREVIATION, catalogUnavailable, FrameId, IconItem, ExcalidrawFile } from './chunk-VTFAXWQJ.js';
 import './chunk-7D4SUZUM.js';
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -1046,9 +1046,11 @@ var KNOWN_CODES = /* @__PURE__ */ new Set([
   "BRIDGE_SPAWN_FAILED",
   "BRIDGE_UNREACHABLE",
   "PORT_UNAVAILABLE",
+  "BRIDGE_VERSION_MISMATCH",
   "STALE_VERSION",
   "ID_COLLISION",
   "UNKNOWN_ELEMENT",
+  "NO_BOUND_LABEL",
   "EMPTY_SELECTION",
   "DISK_CONFLICT",
   "UNREADABLE_SCENE_FILE",
@@ -1098,23 +1100,48 @@ function createBridgeClient() {
         return null;
       }
     },
-    connect(port) {
-      const base = `http://127.0.0.1:${port}`;
-      async function call(path, schema, init, timeoutMs = DEFAULT_API_TIMEOUT_MS) {
-        let response;
+    async shutdown(port, timeoutMs = DEFAULT_HEALTH_TIMEOUT_MS) {
+      try {
+        await fetch(`http://127.0.0.1:${port}/api/shutdown`, {
+          method: "POST",
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+      } catch {
+      }
+      const deadline = Date.now() + timeoutMs * 4;
+      while (Date.now() < deadline) {
+        if (await this.health(port, timeoutMs) === null) return true;
+        await new Promise((resolve6) => setTimeout(resolve6, 100));
+      }
+      return false;
+    },
+    connect(port, reconnect) {
+      let current = port;
+      async function attempt(path, init, timeoutMs) {
         try {
-          response = await fetch(`${base}${path}`, {
+          return await fetch(`http://127.0.0.1:${current}${path}`, {
             ...init,
             signal: AbortSignal.timeout(timeoutMs)
           });
         } catch {
-          return fail(bridgeUnreachable(port));
+          return null;
+        }
+      }
+      async function call(path, schema, init, timeoutMs = DEFAULT_API_TIMEOUT_MS) {
+        let response = await attempt(path, init, timeoutMs);
+        if (response === null && reconnect !== void 0) {
+          const revived = await reconnect();
+          if (revived !== null) {
+            current = revived;
+            response = await attempt(path, init, timeoutMs);
+          }
         }
+        if (response === null) return fail(bridgeUnreachable(current));
         const body = await response.json().catch(() => null);
-        if (!response.ok) return fail(toChalkError(body, port));
+        if (!response.ok) return fail(toChalkError(body, current));
         const parsed = schema.safeParse(body);
         if (!parsed.success) {
-          return fail(bridgeUnreachable(port));
+          return fail(bridgeUnreachable(current));
         }
         return ok(parsed.data);
       }
@@ -1725,6 +1752,24 @@ function createBridgeLauncher(options, deps) {
         await sleep(pollIntervalMs);
       }
       return fail(bridgeSpawnFailed(`it did not start listening within ${readyTimeoutMs}ms`));
+    },
+    async stop(pid) {
+      try {
+        process.kill(pid, "SIGTERM");
+      } catch {
+        return false;
+      }
+      const deadline = Date.now() + 5e3;
+      while (Date.now() < deadline) {
+        try {
+          process.kill(pid, 0);
+        } catch {
+          return true;
+        }
+        await sleep(pollIntervalMs);
+      }
+      deps.logger.warn("a bridge did not exit after being signalled", { pid });
+      return false;
     }
   };
 }
@@ -1733,6 +1778,48 @@ function createBridgeLauncher(options, deps) {
 function createClock() {
   return { now: () => Date.now() };
 }
+
+// src/adapters/system/idle-watch.ts
+var intervalFor = (timeoutMs) => Math.max(1e3, Math.min(1e4, Math.floor(timeoutMs / 3)));
+function createIdleWatch(options, deps) {
+  let lastActivity = deps.clock.now();
+  let timer = null;
+  let fired = false;
+  return {
+    touch() {
+      lastActivity = deps.clock.now();
+    },
+    start({ isWatched, onIdle }) {
+      const timeoutMs = options.timeoutMs;
+      if (timeoutMs === null) {
+        deps.logger.debug("idle shutdown is disabled", { reason: "CHALK_IDLE_TIMEOUT=0" });
+        return;
+      }
+      if (timer !== null) return;
+      const every = options.checkIntervalMs ?? intervalFor(timeoutMs);
+      timer = setInterval(() => {
+        if (fired) return;
+        if (isWatched()) {
+          lastActivity = deps.clock.now();
+          return;
+        }
+        if (deps.clock.now() - lastActivity < timeoutMs) return;
+        fired = true;
+        deps.logger.info("idle \u2014 nothing watching and nothing asking", {
+          idleMs: deps.clock.now() - lastActivity
+        });
+        onIdle();
+      }, every);
+      timer.unref?.();
+      deps.logger.debug("watching for idle", { timeoutMs, every });
+    },
+    stop() {
+      if (timer === null) return;
+      clearInterval(timer);
+      timer = null;
+    }
+  };
+}
 var ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
 var shortId = (length) => {
   let out = "";
@@ -2426,7 +2513,20 @@ function ensureBridge(deps) {
     const repoRoot = await deps.projectDir.findRepoRoot(options.cwd);
     if (!repoRoot.ok) return repoRoot;
     const existingPort = await deps.projectDir.readPort(repoRoot.value);
-    const existing = existingPort === null ? null : await deps.client.health(existingPort);
+    let existing = existingPort === null ? null : await deps.client.health(existingPort);
+    if (existing !== null && existingPort !== null && existing.version !== deps.version) {
+      deps.logger.info("replacing a bridge from another build", {
+        running: existing.version,
+        ours: deps.version,
+        port: existingPort
+      });
+      const stopped = await deps.client.shutdown(existingPort) || await deps.launcher.stop(existing.pid);
+      if (!stopped) {
+        return fail(bridgeVersionMismatch(existing.version, deps.version, existingPort));
+      }
+      await deps.projectDir.clearPort(repoRoot.value);
+      existing = null;
+    }
     let port = existing === null ? null : existingPort;
     let health = existing;
     let spawned = false;
@@ -3237,8 +3337,42 @@ function edgePoint(from, to, gap) {
   const t = scale + push;
   return [cx + dx * t, cy + dy * t];
 }
-function rebindArrows(scene, moved) {
+function redrawOne(current, labels, arrow) {
+  if (arrow.type !== "arrow") return [];
+  const fromId = startOf(arrow);
+  const toId = endOf(arrow);
+  if (fromId === null || toId === null) return [];
+  const from = current.get(fromId);
+  const to = current.get(toId);
+  if (from === void 0 || to === void 0) return [];
+  const startGap = arrow.startBinding?.gap ?? 4;
+  const endGap = arrow.endBinding?.gap ?? 4;
+  const [sx, sy] = edgePoint(boxOf(from), boxOf(to), startGap);
+  const [ex, ey] = edgePoint(boxOf(to), boxOf(from), endGap);
+  const points = [point(0, 0), point(ex - sx, ey - sy)];
+  const redrawn = {
+    ...arrow,
+    x: sx,
+    y: sy,
+    width: Math.abs(ex - sx),
+    height: Math.abs(ey - sy),
+    points,
+    lastCommittedPoint: null
+  };
+  const label = labels.get(arrow.id);
+  if (label === void 0) return [redrawn];
+  return [
+    redrawn,
+    {
+      ...label,
+      x: (sx + ex) / 2 - label.width / 2,
+      y: (sy + ey) / 2 - label.height / 2
+    }
+  ];
+}
+function redrawArrowsTouching(scene, moved) {
   const current = new Map(scene.map((element) => [element.id, moved.get(element.id) ?? element]));
+  const labels = labelsByContainer([...current.values()]);
   const redrawn = [];
   for (const element of current.values()) {
     if (element.type !== "arrow") continue;
@@ -3246,26 +3380,16 @@ function rebindArrows(scene, moved) {
     const toId = endOf(element);
     if (fromId === null || toId === null) continue;
     if (!moved.has(fromId) && !moved.has(toId)) continue;
-    const from = current.get(fromId);
-    const to = current.get(toId);
-    if (from === void 0 || to === void 0) continue;
-    const startGap = element.startBinding?.gap ?? 4;
-    const endGap = element.endBinding?.gap ?? 4;
-    const [sx, sy] = edgePoint(boxOf(from), boxOf(to), startGap);
-    const [ex, ey] = edgePoint(boxOf(to), boxOf(from), endGap);
-    const points = [point(0, 0), point(ex - sx, ey - sy)];
-    redrawn.push({
-      ...element,
-      x: sx,
-      y: sy,
-      width: Math.abs(ex - sx),
-      height: Math.abs(ey - sy),
-      points,
-      lastCommittedPoint: null
-    });
+    redrawn.push(...redrawOne(current, labels, element));
   }
   return redrawn;
 }
+function redrawArrows(scene, ids) {
+  const current = new Map(scene.map((element) => [element.id, element]));
+  const labels = labelsByContainer(scene);
+  const wanted = new Set(ids);
+  return [...current.values()].filter((element) => wanted.has(element.id)).flatMap((element) => redrawOne(current, labels, element));
+}
 function translate(scene, deltas) {
   const labels = labelsByContainer(scene);
   const moved = /* @__PURE__ */ new Map();
@@ -3280,7 +3404,7 @@ function translate(scene, deltas) {
       moved.set(label.id, { ...label, x: label.x + dx, y: label.y + dy });
     }
   }
-  return [...moved.values(), ...rebindArrows(scene, moved)];
+  return [...moved.values(), ...redrawArrowsTouching(scene, moved)];
 }
 var alignments = {
   "align-left": (box, bounds) => [bounds.x - box.x, 0],
@@ -3576,7 +3700,15 @@ function connectElements(deps) {
     };
     const created = await deps.write.create(scene.value, [skeleton], true);
     if (!created.ok) return created;
-    const committed = deps.write.append(scene.value, created.value);
+    const placed = redrawArrows(
+      [...scene.value.elements, ...created.value.created, ...created.value.changed],
+      [skeleton.id]
+    );
+    const geometry = new Map(placed.map((element) => [element.id, element]));
+    const committed = deps.write.append(scene.value, {
+      created: created.value.created.map((element) => geometry.get(element.id) ?? element),
+      changed: created.value.changed
+    });
     if (!committed.ok) return committed;
     return ok({ ...committed.value, arrowId: skeleton.id });
   };
@@ -4195,6 +4327,13 @@ function rawElements(deps) {
 
 // src/app/usecases/write/update-elements.ts
 var missing = (id) => toRejection(id, unknownElement(id));
+var onlyRequested = (landed, requested) => {
+  const asked = new Set(requested);
+  return landed.filter((id) => asked.has(id));
+};
+var captionOf = (scene, container) => scene.find(
+  (element) => element.type === "text" && element.containerId === container && !element.isDeleted
+);
 function updateElements(deps) {
   return (input) => {
     const scene = deps.write.resolve(input.sceneId);
@@ -4203,25 +4342,73 @@ function updateElements(deps) {
     const changed = [];
     const rejected = [];
     const expectations = [];
+    const moved = /* @__PURE__ */ new Map();
+    const knockOn = [];
     for (const update of input.updates) {
       const existing = byId.get(update.id);
       if (existing === void 0 || existing.isDeleted) {
         rejected.push(missing(update.id));
         continue;
       }
+      const { role, label, ...rest } = update.patch;
       const patch = Object.fromEntries(
-        Object.entries(update.patch).filter(([, value]) => value !== void 0)
+        Object.entries(rest).filter(([, value]) => value !== void 0)
       );
-      changed.push({ ...existing, ...patch });
+      if (label !== void 0) {
+        const caption = captionOf(scene.value.elements, update.id);
+        if (caption === void 0) {
+          rejected.push(toRejection(update.id, noBoundLabel(update.id)));
+          continue;
+        }
+        knockOn.push({ ...caption, text: label, originalText: label });
+      }
+      const next = {
+        ...existing,
+        ...role === void 0 ? {} : styleForRole(role),
+        ...patch
+      };
+      changed.push(next);
       expectations.push({ id: update.id, expectedVersion: update.expectedVersion });
+      const dx = next.x - existing.x;
+      const dy = next.y - existing.y;
+      if (dx !== 0 || dy !== 0) moved.set(update.id, next);
+      else if (next.width !== existing.width || next.height !== existing.height) {
+        moved.set(update.id, next);
+      }
     }
-    const applied = deps.write.apply(scene.value, changed, { expectations });
+    if (moved.size > 0) {
+      for (const [id, next] of moved) {
+        const before = byId.get(id);
+        const caption = captionOf(scene.value.elements, id);
+        if (before === void 0 || caption === void 0) continue;
+        knockOn.push({
+          ...caption,
+          x: caption.x + (next.x - before.x),
+          y: caption.y + (next.y - before.y)
+        });
+      }
+      knockOn.push(...redrawArrowsTouching(scene.value.elements, moved));
+    }
+    for (const element of knockOn) {
+      const before = byId.get(element.id);
+      if (before !== void 0) {
+        expectations.push({ id: element.id, expectedVersion: before.version });
+      }
+    }
+    const applied = deps.write.apply(scene.value, [...changed, ...knockOn], { expectations });
     if (!applied.ok) return applied;
     return ok({
       sceneId: applied.value.sceneId,
       sceneVersion: applied.value.sceneVersion,
       broadcastTo: applied.value.broadcastTo,
-      applied: applied.value.applied,
+      // What the caller asked for, not everything that moved. A caption that followed its
+      // box and an arrow that was redrawn are consequences; listing them would turn this
+      // into "every element that changed" and leave the caller working out which of them
+      // it had actually requested.
+      applied: onlyRequested(
+        applied.value.applied,
+        input.updates.map((update) => update.id)
+      ),
       rejected: [...rejected, ...applied.value.rejected]
     });
   };
@@ -4255,6 +4442,11 @@ function deleteElements(deps) {
         id: deletion.id,
         expectedVersion: deletion.expectedVersion ?? existing.version
       });
+      const caption = captionOf(scene.value.elements, deletion.id);
+      if (caption !== void 0) {
+        changed.push({ ...caption, isDeleted: true });
+        expectations.push({ id: caption.id, expectedVersion: caption.version });
+      }
     }
     const applied = deps.write.apply(scene.value, changed, { expectations });
     if (!applied.ok) return applied;
@@ -4262,7 +4454,10 @@ function deleteElements(deps) {
       sceneId: applied.value.sceneId,
       sceneVersion: applied.value.sceneVersion,
       broadcastTo: applied.value.broadcastTo,
-      deleted: applied.value.applied,
+      deleted: onlyRequested(
+        applied.value.applied,
+        input.deletions.map((deletion) => deletion.id)
+      ),
       rejected: [...rejected, ...applied.value.rejected]
     });
   };
@@ -4275,6 +4470,7 @@ function printLine(line) {
 }
 var DEFAULT_PORT = 7180;
 var PORT_SCAN_RANGE = 32;
+var DEFAULT_IDLE_SECONDS = 90;
 var truthy = (value) => value !== void 0 && value !== "" && value !== "0" && value.toLowerCase() !== "false";
 var EnvSchema = z.object({
   CHALK_PORT: z.coerce.number().int().min(1).max(65535).optional(),
@@ -4287,12 +4483,18 @@ var EnvSchema = z.object({
    * icon pack into the developer real data directory would be a test that changed the
    * machine it ran on.
    */
-  CHALK_DATA_DIR: z.string().min(1).optional()
+  CHALK_DATA_DIR: z.string().min(1).optional(),
+  /**
+   * Seconds a bridge may sit with no browser client and no tool call before it exits.
+   * `0` keeps it up forever, which is what every version before v1.0.2 did.
+   */
+  CHALK_IDLE_TIMEOUT: z.coerce.number().int().min(0).max(86400).optional()
 });
 function readEnv(source) {
   const parsed = EnvSchema.safeParse(source);
   const env = parsed.success ? parsed.data : {};
   const explicit2 = env.CHALK_PORT ?? null;
+  const idleSeconds = env.CHALK_IDLE_TIMEOUT ?? DEFAULT_IDLE_SECONDS;
   return {
     listenFrom: explicit2 ?? DEFAULT_PORT,
     listenTries: explicit2 === null ? PORT_SCAN_RANGE : 1,
@@ -4300,12 +4502,13 @@ function readEnv(source) {
     autoStart: !truthy(env.CHALK_NO_AUTOSTART),
     autoOpen: !truthy(env.CHALK_NO_OPEN),
     dataDir: env.CHALK_DATA_DIR ?? null,
+    idleTimeoutMs: idleSeconds === 0 ? null : idleSeconds * 1e3,
     logLevel: env.CHALK_LOG_LEVEL ?? "info"
   };
 }
 
 // src/composition/container.ts
-var PACKAGE_VERSION = "1.0.0";
+var PACKAGE_VERSION = "1.0.3";
 function readRuntime() {
   return {
     env: process.env,
@@ -4369,6 +4572,7 @@ function buildCommandContext(runtime = readRuntime()) {
       if (!opened.ok) return opened;
       const store = opened.value;
       const broadcaster = createBroadcaster(idGen, logger);
+      const idleWatch = createIdleWatch({ timeoutMs: config.idleTimeoutMs }, { clock, logger });
       const presenceTracker = createPresenceTracker();
       const expander = createNodeSkeletonExpander();
       const repoWriter = createRepoWriter({ repoRoot }, { store, logger });
@@ -4376,6 +4580,7 @@ function buildCommandContext(runtime = readRuntime()) {
       const diskWatcher = createDiskWatcher({ logger });
       const commit = commitScene({ store, repoWriter });
       const repoFiles = createRepoFiles({ repoRoot });
+      let onShutdown = null;
       const exportBroker = createExportBroker({}, { broadcaster, idGen, logger });
       const globalPaths = globalPathsOf(runtime, config);
       let catalog = null;
@@ -4539,6 +4744,10 @@ function buildCommandContext(runtime = readRuntime()) {
         // logic in `app/`, and a lifecycle command has no more business holding a store
         // than a route does.
         sceneFilePaths: () => store.list().map((scene) => scene.repoPath).filter((path) => path !== null).map((path) => resolve(repoRoot, path)),
+        idleWatch,
+        onShutdownRequest: (handler) => {
+          onShutdown = handler;
+        },
         close: () => {
           repoWriter.cancel();
           exportBroker.abandon();
@@ -4579,6 +4788,7 @@ function buildCommandContext(runtime = readRuntime()) {
           importScene: usecases.importScene,
           broadcaster,
           identity,
+          requestShutdown: () => onShutdown?.(),
           logger
         },
         ws: {
@@ -4602,24 +4812,42 @@ function buildCommandContext(runtime = readRuntime()) {
         { cliEntry: runtime.entryPath, execPath: runtime.execPath, env: runtime.env },
         { projectDir, client, logger }
       );
+      const bootstrap = ensureBridge({
+        // Compared against whatever is already listening: an upgrade that reused an
+        // older detached bridge would ship every fix and deliver none of them.
+        version: runtime.version,
+        projectDir,
+        client,
+        launcher,
+        opener: createBrowserOpener(logger),
+        logger
+      });
       return {
         logger,
         projectDir,
         client,
+        launcher,
         // A7 — the tool handlers never see a port, a URL, or a `fetch`. They see the
         // bridge's read surface and a shelf of markdown, and nothing else exists to
         // tempt them into caching a scene (invariant 1).
+        //
+        // The `reconnect` argument is what makes a session survive its own bridge. One
+        // now exits when nothing is watching and nothing is asking, so "the port this
+        // session started with" stops being true the moment the user closes the tab and
+        // walks away. Re-running the bootstrap puts a bridge *and a tab* back, which is
+        // what the session's first call did, so a tool call after a break just works.
         createToolDeps: (port) => ({
-          bridge: client.connect(port),
+          bridge: client.connect(port, async () => {
+            const revived = await bootstrap({
+              cwd: runtime.cwd,
+              autoStart: config.autoStart,
+              autoOpen: config.autoOpen
+            });
+            return revived.ok ? revived.value.port : null;
+          }),
           guides: createGuideLibrary({ dir: resolveGuidesDir() }, { logger })
         }),
-        ensureBridge: ensureBridge({
-          projectDir,
-          client,
-          launcher,
-          opener: createBrowserOpener(logger),
-          logger
-        })
+        ensureBridge: bootstrap
       };
     }
   };
@@ -5606,6 +5834,8 @@ var STATUS = {
   BRIDGE_SPAWN_FAILED: 500,
   BRIDGE_UNREACHABLE: 503,
   PORT_UNAVAILABLE: 500,
+  // 409: something is there, it is simply not the build this process belongs to.
+  BRIDGE_VERSION_MISMATCH: 409,
   // 409 for both: a stale version and a file that changed underneath us are the same
   // shape of problem — the caller's view of the world is out of date, and re-reading is
   // the way forward.
@@ -5613,6 +5843,8 @@ var STATUS = {
   ID_COLLISION: 409,
   // 404, not 409: the id is not there to conflict with.
   UNKNOWN_ELEMENT: 404,
+  // 422: the id is fine and the request is well-formed, there is simply nothing to rename.
+  NO_BOUND_LABEL: 422,
   EMPTY_SELECTION: 400,
   DISK_CONFLICT: 409,
   UNREADABLE_SCENE_FILE: 422,
@@ -5862,6 +6094,20 @@ var sessionRoutes = [
   })
 ];
 
+// src/interfaces/http/routes/shutdown.ts
+var shutdownRoute = {
+  name: "shutdown",
+  register(app, deps) {
+    app.post("/api/shutdown", async (_request, reply) => {
+      const identity = deps.identity();
+      deps.logger.info("shutdown requested over the API", { pid: identity.pid });
+      await reply.send({ stopping: true, pid: identity.pid, version: identity.version });
+      setTimeout(() => deps.requestShutdown(), 0);
+      return reply;
+    });
+  }
+};
+
 // src/interfaces/http/routes/write.ts
 var writeRoutes = [
   postRoute({
@@ -5947,6 +6193,7 @@ var ROUTES = [
   elementsRoute,
   settingsRoute,
   debugElementRoute,
+  shutdownRoute,
   ...writeRoutes,
   ...sessionRoutes
 ];
@@ -5960,6 +6207,9 @@ async function createHttpServer(deps) {
     bodyLimit: 32 * 1024 * 1024
   });
   await app.register(websocket);
+  app.addHook("onRequest", async () => {
+    deps.touch();
+  });
   for (const route of ROUTES) {
     route.register(app, deps.routes);
     deps.logger.debug("registered route", { route: route.name });
@@ -5969,6 +6219,7 @@ async function createHttpServer(deps) {
     const send = (message) => {
       socket.send(JSON.stringify(message));
     };
+    deps.touch();
     const handle = deps.broadcaster.register(send);
     const session = { handle, send };
     socket.on("message", (data) => {
@@ -6049,7 +6300,8 @@ ${built.error.hint ?? ""}
       ws: services.ws,
       broadcaster: services.broadcaster,
       logger: services.logger,
-      uiDistPath: services.uiDistPath
+      uiDistPath: services.uiDistPath,
+      touch: () => services.idleWatch.touch()
     });
     const listening = await listenOnFirstFreePort(app, {
       host: "127.0.0.1",
@@ -6076,6 +6328,7 @@ ${built.error.hint ?? ""}
     await new Promise((resolve6) => {
       const shutdown = async (signal) => {
         services.logger.info("shutting down", { signal });
+        services.idleWatch.stop();
         await services.diskWatcher.stop();
         const flushed = await services.repoWriter.flushAll();
         if (flushed.length > 0) {
@@ -6086,18 +6339,75 @@ ${built.error.hint ?? ""}
         services.close();
         resolve6();
       };
+      services.idleWatch.start({
+        isWatched: () => services.broadcaster.clientCount() > 0,
+        onIdle: () => void shutdown("idle")
+      });
       process.once("SIGINT", () => void shutdown("SIGINT"));
       process.once("SIGTERM", () => void shutdown("SIGTERM"));
+      services.onShutdownRequest(() => void shutdown("api"));
     });
     return 0;
   }
 };
 
+// src/interfaces/cli/commands/stop.ts
+var stopCommand = {
+  name: "stop",
+  summary: "stop the bridge running for this repo, flushing anything unsaved",
+  detail: [
+    "Ends the bridge for the repository containing the working directory.",
+    "",
+    "The bridge flushes every pending .excalidraw write, stops watching the repo, and",
+    "clears its port file on the way out \u2014 so nothing drawn in the last two seconds is",
+    "lost. Nothing is started; the next Claude Code session starts a fresh one."
+  ].join("\n"),
+  async run(context) {
+    const services = context.createClientServices({ prefix: "[stop]" });
+    const repoRoot = await services.projectDir.findRepoRoot(context.runtime.cwd);
+    if (!repoRoot.ok) {
+      context.print(repoRoot.error.message);
+      if (repoRoot.error.hint !== void 0) context.print(`  ${repoRoot.error.hint}`);
+      return 1;
+    }
+    const port = await services.projectDir.readPort(repoRoot.value);
+    if (port === null) {
+      context.print(`no bridge is running for ${repoRoot.value}`);
+      return 0;
+    }
+    const health = await services.client.health(port);
+    if (health === null) {
+      await services.projectDir.clearPort(repoRoot.value);
+      context.print(`nothing was listening on 127.0.0.1:${port} \u2014 cleared the stale port file`);
+      return 0;
+    }
+    context.print(
+      `stopping chalkbridge ${health.version} on 127.0.0.1:${port} (pid ${health.pid})`
+    );
+    if (await services.client.shutdown(port)) {
+      context.print("  stopped \u2014 pending scene writes were flushed");
+      return 0;
+    }
+    context.print("  it has no shutdown endpoint (built before v1.0.2) \u2014 ending it by pid");
+    if (await services.launcher.stop(health.pid)) {
+      await services.projectDir.clearPort(repoRoot.value);
+      context.print(`  stopped pid ${health.pid}`);
+      return 0;
+    }
+    context.print("  it would not stop \u2014 end it yourself:");
+    context.print(
+      context.runtime.platform === "win32" ? `    taskkill /PID ${health.pid} /F` : `    kill ${health.pid}`
+    );
+    return 1;
+  }
+};
+
 // src/interfaces/cli/registry.ts
 var COMMANDS = [
   serveCommand,
   mcpCommand,
   healthCommand,
+  stopCommand,
   iconsCommand
 ];
 

package/dist/index.js

@@ -1,4 +1,4 @@
-export { createNodeSkeletonExpander, fail, isFail, isOk, ok, partition } from './chunk-HFKCLTVU.js';
+export { createNodeSkeletonExpander, fail, isFail, isOk, ok, partition } from './chunk-VTFAXWQJ.js';
 import './chunk-7D4SUZUM.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chalkbridge",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "type": "module",
   "description": "Self-hosted Excalidraw canvas for Claude Code to draw and reason on architecture diagrams.",
   "license": "MIT",
@@ -22,6 +22,7 @@
     "ui-dist",
     "guides",
     "packs",
+    "CHANGELOG.md",
     "THIRD-PARTY-NOTICES.md"
   ],
   "bin": {