chalkbridge 1.0.4 → 1.1.1

package/dist/{chunk-U2ZMSGNS.js → chunk-XFH76JS6.js}

@@ -299,7 +299,26 @@ var TextSkeleton = z.strictObject({
   fontSize: z.number().optional(),
   fontFamily: FontFamily.optional(),
   textAlign: TextAlign.optional(),
-  verticalAlign: VerticalAlign.optional()
+  verticalAlign: VerticalAlign.optional(),
+  /**
+   * The column a note wraps into.
+   *
+   * Meaningless without `autoResize: false`, which is why the two travel together and why
+   * `domain/scene/skeleton.ts` sets both or neither.
+   */
+  width: z.number().optional(),
+  /**
+   * Upstream: "If `true` the width will fit the text. If `false`, the text will wrap to
+   * fit the width." It defaults to `true`, and that default is why a free-standing note
+   * came out as one line thousands of pixels long — the measurement was right (the
+   * expander measures through `adapters/excalidraw/text-metrics.ts`), there was simply
+   * nothing telling it to break.
+   *
+   * An Excalidraw-shaped flag in a skeleton, exactly as `elbowed` is on the linear one:
+   * there is no friendlier field that carries it, and inventing one would mean a second
+   * name for the same boolean.
+   */
+  autoResize: z.boolean().optional()
 });
 var FrameSkeleton = z.strictObject({
   type: z.literal("frame"),
@@ -387,6 +406,13 @@ var DescribedElement = z.object({
   to: ElementId.nullish(),
   style: DescribedStyle.nullish()
 });
+var Overlap = z.object({
+  a: ElementId,
+  b: ElementId,
+  /** Size of the intersecting region, in px. */
+  width: z.number(),
+  height: z.number()
+});
 var SceneDescription = z.object({
   sceneId: SceneId,
   name: z.string(),
@@ -395,6 +421,19 @@ var SceneDescription = z.object({
   updatedAgoMs: z.number().int(),
   frames: z.array(DescribedFrame),
   elements: z.array(DescribedElement),
+  /** Worst first, and capped — see `MAX_REPORTED_OVERLAPS`. */
+  overlaps: z.array(Overlap),
+  /** Every collision found, including the ones `overlaps` was truncated past. */
+  overlapCount: z.number().int().nonnegative(),
+  /**
+   * Which layout the shape of this graph wants, and what in it decided.
+   *
+   * Three layouts exist and each destroys the structure the others show. Claude cannot
+   * see the canvas, so without a sentence here it picks by habit — which is how a hub
+   * with eight neighbours ends up ranked into one box against an edge and a tall stack
+   * beside it. Null when the scene is too small to have a shape.
+   */
+  layoutAdvice: z.string().nullable(),
   detail: DetailLevel
 });
 var DescribedEdge = z.object({
@@ -732,8 +771,38 @@ var HOUSE = {
     external: { strokeColor: "#1e1e1e", backgroundColor: "transparent" },
     hotspot: { strokeColor: "#e03131", backgroundColor: "#ffc9c9" }
   },
-  sizes: { service: [180, 80], icon: 64, framePad: 40 },
-  spacing: { h: 60, v: 100 }
+  sizes: {
+    /** The floor a labelled shape starts from, and the size an unlabelled one keeps. */
+    service: [180, 80],
+    icon: 64,
+    framePad: 40,
+    /** Breathing room around a bound label. Wider than upstream's 5 px, which lets text
+     *  touch the stroke. */
+    labelPadX: 16,
+    labelPadY: 12,
+    /** Past this a label wraps instead of widening. A 400 px box holding one line reads
+     *  as a banner, not a node. */
+    maxBox: 280,
+    /**
+     * Past this a **free-standing note** wraps. Wider than `maxBox` because the two are
+     * not the same object: a caption names a thing and stays short, a note is prose and
+     * runs to several sentences. Left unwrapped a note is one enormous line — 261
+     * characters measured 2,651 px against a canvas whose whole diagram was 1,760 — and
+     * a paragraph set to `maxBox` is a column of two-word lines instead.
+     */
+    note: 420
+  },
+  spacing: { h: 60, v: 100 },
+  /**
+   * Every computed size rounds up to this.
+   *
+   * `guides/layout.md` already tells the reader to keep coordinates on a 20 px grid so a
+   * nudge stays aligned; sizes derived from measured text have to land on it too. It is
+   * also what answers `adr/0004`'s objection to measuring at all — that per-box widths
+   * differing by a few pixels make a rank of five look ragged. Quantised, they do not
+   * differ by a few pixels: they are equal or they are 20 apart on purpose.
+   */
+  grid: 20
 };
 var CreatableType = z.enum(["rectangle", "diamond", "ellipse", "text", "line"], {
   error: (issue) => issue.input === "arrow" ? "arrow rejected \u2014 use chalk_connect(fromId, toId), it handles the bindings" : `unknown element type ${JSON.stringify(issue.input)} \u2014 valid: rectangle, diamond, ellipse, text, line, and chalk_connect for arrows`
@@ -817,7 +886,32 @@ var ARRANGE_OPS = [
    * crossings, spacing from `HOUSE.spacing`. It reads the arrows among the named
    * elements out of the scene, so the caller names boxes, not edges.
    */
-  "layout-layered"
+  "layout-layered",
+  /**
+   * The radial layout — a hub at the centre and everything else on rings around it,
+   * ordered so a node sits near whatever it hangs off.
+   *
+   * `layout-layered` answers "what flows into what". This answers the other question a
+   * diagram gets drawn to ask: **what is this one thing connected to?** A hub-and-spoke
+   * graph laid out in ranks becomes a wide, shallow fan with the hub jammed against the
+   * left edge — the shape is in the data and the layout throws it away. Ranking is also
+   * the wrong instrument for a graph with no direction to speak of: a mesh of mutual
+   * dependencies has no sources, so every rank is a tie broken on the id.
+   *
+   * Like `layout-layered` it reads the arrows among the named elements out of the scene,
+   * so the caller names boxes, not edges. Unlike it, direction is ignored: what matters
+   * radially is who touches whom.
+   */
+  "layout-radial",
+  /**
+   * The tree layout — a root on the left and everything else fanning right by depth.
+   *
+   * The same graph `layout-radial` draws as a circle, drawn as a root and its
+   * descendants. A ring must be long enough to seat its members, so eight boxes carrying
+   * real labels force a wide radius and every edge then crosses the middle of the circle.
+   * Fanned out instead, no edge crosses another and the eye reads left to right.
+   */
+  "layout-tree"
 ];
 var ArrangeOp = z.enum(ARRANGE_OPS);
 var ArrangeInput = z.object({
@@ -904,7 +998,17 @@ var ReadMeOutput = z.object({
 var writeResult = {
   sceneId: SceneId,
   sceneVersion: z.number().int(),
-  broadcastTo: z.number().int().nonnegative()
+  broadcastTo: z.number().int().nonnegative(),
+  /**
+   * Something is buried on the canvas after this write — or `null`, which is the normal
+   * case and says so by being absent rather than by saying "none".
+   *
+   * On **every** write rather than on a read, because the alternative is that the agent
+   * has to decide to go and look, and the only tool that used to answer "did that land
+   * badly?" was `chalk_screenshot` — a rendered image, the most expensive call here. A
+   * layout mistake now costs one sentence at the moment it is made.
+   */
+  overlapWarning: z.string().nullable()
 };
 var ToolRejection = z.object({
   id: ElementId,
@@ -1056,10 +1160,27 @@ var SearchIconsOutput = z.object({
    */
   note: z.string().nullable()
 });
+var IconPlacement = z.enum(["above", "below", "left", "right", "badge", "inside"]);
 var PlaceIconInput = z.object({
   iconId: IconId,
-  x: z.number(),
-  y: z.number(),
+  /**
+   * Absolute position. Optional **only** when `attachTo` is given — one or the other has
+   * to say where the icon goes, and the error names the missing half.
+   */
+  x: z.number().optional(),
+  y: z.number().optional(),
+  /**
+   * Attach the icon to an existing element instead of positioning it by hand.
+   *
+   * This is the difference between an icon that is *part of* a node and one that merely
+   * happens to be near it today. An attached icon is recorded in
+   * `customData.chalk.anchorIds` and travels with its element through every arrange
+   * operation, `layout-layered` included — which is what stops a set of vendor marks being
+   * left stranded across the canvas the first time the boxes are laid out.
+   */
+  attachTo: ElementId.optional(),
+  /** Where it sits relative to `attachTo`. Ignored without it. Defaults to `above`. */
+  placement: IconPlacement.optional(),
   /** Longest side in px. Defaults to `HOUSE.sizes.icon`; the aspect comes from the icon. */
   size: z.number().positive().optional(),
   /** A caption centred beneath it. An unlabelled icon says "a thing was here". */
@@ -1317,6 +1438,11 @@ var unknownIcon = (id, packs) => err("UNKNOWN_ICON", `no icon "${id}" in the cat
   tool: "chalk_search_icons",
   detail: { id }
 });
+var iconNeedsAPlace = (id) => err("ICON_NEEDS_A_PLACE", `nowhere to put "${id}" \u2014 pass attachTo, or both x and y`, {
+  hint: "attachTo: the element it belongs to (it then travels with that element through every layout). x/y only for an icon that belongs to the canvas rather than to a node",
+  tool: "chalk_place_icon",
+  detail: { id }
+});
 var packInstallFailed = (pack, reason) => err("PACK_INSTALL_FAILED", `could not install the icon pack "${pack}": ${reason}`, {
   hint: "check the machine can reach the npm registry, or install the package yourself and point chalk_install_pack at it with `from`",
   tool: "chalk_install_pack",
@@ -1436,6 +1562,174 @@ function installDomShim() {
   };
 }
 
+// src/domain/style/text-metrics.ts
+var EXCALIFONT_EM = {
+  " ": 0.4,
+  "!": 0.314,
+  '"': 0.371,
+  "#": 0.783,
+  $: 0.721,
+  "%": 0.928,
+  "&": 0.718,
+  "'": 0.218,
+  "(": 0.441,
+  ")": 0.402,
+  "*": 0.525,
+  "+": 0.55,
+  ",": 0.257,
+  "-": 0.411,
+  ".": 0.274,
+  "/": 0.561,
+  "0": 0.664,
+  "1": 0.427,
+  "2": 0.7,
+  "3": 0.608,
+  "4": 0.585,
+  "5": 0.618,
+  "6": 0.64,
+  "7": 0.558,
+  "8": 0.636,
+  "9": 0.629,
+  ":": 0.264,
+  ";": 0.298,
+  "<": 0.55,
+  "=": 0.55,
+  ">": 0.55,
+  "?": 0.466,
+  "@": 0.829,
+  A: 0.676,
+  B: 0.761,
+  C: 0.629,
+  D: 0.78,
+  E: 0.707,
+  F: 0.661,
+  G: 0.78,
+  H: 0.573,
+  I: 0.545,
+  J: 0.569,
+  K: 0.613,
+  L: 0.543,
+  M: 0.766,
+  N: 0.632,
+  O: 0.767,
+  P: 0.698,
+  Q: 0.768,
+  R: 0.736,
+  S: 0.622,
+  T: 0.857,
+  U: 0.73,
+  V: 0.592,
+  W: 0.786,
+  X: 0.628,
+  Y: 0.564,
+  Z: 0.832,
+  "[": 0.472,
+  "\\": 0.589,
+  "]": 0.497,
+  "^": 0.51,
+  _: 0.67,
+  "`": 0.6,
+  a: 0.576,
+  b: 0.555,
+  c: 0.504,
+  d: 0.605,
+  e: 0.537,
+  f: 0.497,
+  g: 0.555,
+  h: 0.567,
+  i: 0.244,
+  j: 0.328,
+  k: 0.533,
+  l: 0.225,
+  m: 0.663,
+  n: 0.526,
+  o: 0.6,
+  p: 0.537,
+  q: 0.539,
+  r: 0.412,
+  s: 0.543,
+  t: 0.553,
+  u: 0.548,
+  v: 0.525,
+  w: 0.693,
+  x: 0.591,
+  y: 0.53,
+  z: 0.572,
+  "{": 0.504,
+  "|": 0.299,
+  "}": 0.544,
+  "~": 0.669,
+  // Beyond ASCII, only what actually turns up in a diagram. `·` earns its place: it is
+  // the separator this project's own labels use ("Dev machine · manage.sh dist"), and the
+  // block fallback below would over-estimate it nearly threefold.
+  "\xB7": 0.2,
+  "\u2013": 0.702,
+  "\u2014": 0.935,
+  "\u2026": 0.709,
+  "\u2022": 0.522,
+  "\u2019": 0.304,
+  "\u201C": 0.412,
+  "\u201D": 0.428,
+  "\xD7": 0.55,
+  "\xB0": 0.412,
+  "\xA3": 0.71,
+  "\u20AC": 0.713,
+  \u00E9: 0.551,
+  \u00FC: 0.508,
+  \u00F1: 0.526,
+  "\u2713": 0.749
+};
+var fallbackEm = (codePoint) => {
+  if (codePoint < 32) return 0;
+  if (codePoint <= 591) return 0.56;
+  if (codePoint >= 8192 && codePoint <= 8303) return 0.95;
+  if (codePoint >= 126976) return 1.4;
+  return 1;
+};
+var emWidth = (character) => {
+  const known = EXCALIFONT_EM[character];
+  if (known !== void 0) return known;
+  return fallbackEm(character.codePointAt(0) ?? 0);
+};
+function measureLine(text, fontSize) {
+  let em = 0;
+  for (const character of text) em += emWidth(character);
+  return em * fontSize;
+}
+function wrapLines(text, fontSize, maxWidth) {
+  const paragraphs = text.split("\n");
+  const lines = [];
+  for (const paragraph of paragraphs) {
+    const words = paragraph.split(" ").filter((word) => word !== "");
+    if (words.length === 0) {
+      lines.push("");
+      continue;
+    }
+    let line = "";
+    for (const word of words) {
+      const candidate = line === "" ? word : `${line} ${word}`;
+      if (line !== "" && measureLine(candidate, fontSize) > maxWidth) {
+        lines.push(line);
+        line = word;
+      } else {
+        line = candidate;
+      }
+    }
+    lines.push(line);
+  }
+  return lines;
+}
+
+// src/adapters/excalidraw/text-metrics.ts
+var fontSizeOf = (fontString) => {
+  const match = /(\d+(?:\.\d+)?)px/.exec(fontString);
+  const size = match?.[1];
+  return size === void 0 ? 20 : Number.parseFloat(size);
+};
+var createTextMetricsProvider = () => ({
+  getLineWidth: (text, fontString) => measureLine(text, fontSizeOf(fontString))
+});
+
 // src/adapters/excalidraw/node-expander.ts
 var WARM_UP = [
   { type: "rectangle", id: "warmup-a", x: 0, y: 0, width: 10, height: 10, label: { text: "a" } },
@@ -1454,7 +1748,8 @@ var converter = null;
 async function loadConverter() {
   const uninstall = installDomShim();
   try {
-    const { convertToExcalidrawElements } = await import('./prod-KHI2WQT3.js');
+    const { convertToExcalidrawElements, setCustomTextMetricsProvider } = await import('./prod-KHI2WQT3.js');
+    setCustomTextMetricsProvider(createTextMetricsProvider());
     convertToExcalidrawElements([...WARM_UP], { regenerateIds: false });
     return ok(convertToExcalidrawElements);
   } catch (thrown) {
@@ -1511,6 +1806,6 @@ var stable = (element) => {
   return rest;
 };
 
-export { AnnotateInput, AnnotateOutput, ApiError, ArrangeOutput, ArrangeToolInput, BINDING_FIELDS, ClientMessage, ConnectOutput, ConnectToolInput, CreateElementsInput, CreateElementsOutput, DataUrl, 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-U2ZMSGNS.js.map
-//# sourceMappingURL=chunk-U2ZMSGNS.js.map
+export { AnnotateInput, AnnotateOutput, ApiError, ArrangeOutput, ArrangeToolInput, BINDING_FIELDS, ClientMessage, ConnectOutput, ConnectToolInput, CreateElementsInput, CreateElementsOutput, DataUrl, 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, iconNeedsAPlace, idCollision, isFail, isOk, measureLine, noBoundLabel, noBrowser, noScenes, notAPack, notARepo, ok, packInstallFailed, partition, pathOutsideRepo, point, portUnavailable, refusedFieldMessage, sceneFileMissing, staleVersion, storeUnavailable, unknownElement, unknownIcon, unknownScene, unknownSnapshot, unreadableSceneFile, wrapLines };
+//# sourceMappingURL=chunk-XFH76JS6.js.map
+//# sourceMappingURL=chunk-XFH76JS6.js.map