tsquare 0.5.0 → 0.6.0

package/dist/chunks/{chunk-B6KIVOSH.js → chunk-HDSKRKDL.js}

@@ -204,12 +204,13 @@ var wireframeSchema = defineSchema(
   }),
   {
     defaultRules: [
-      "The root element MUST be a Board. A Board's children are Screens (and optional Notes placed beside them).",
+      "The root element MUST be a Board. A Board's children are Screens (and optional Notes placed beside them, and Flow elements after them).",
       "Every Screen MUST be a direct child of the Board. Each Screen is one view of the product; use several Screens to show several views or states.",
       "Screens lay out their children top to bottom. Use Stack (direction row/column) and Grid inside a Screen to arrange content.",
       "Modal, Drawer and Toast are overlays. They MUST be direct children of a Screen, and SHOULD be listed last in the Screen's children so they draw on top.",
       "NavBar goes first in a Screen's children and TabBar goes last (before any overlay).",
-      "Any element except Board, Screen and Note can take a tooltip prop (text) to show a tooltip next to it. Select (with options), Input with type date, and Button, ListItem or NavBar (with menu) take open to show their list, calendar or menu over the screen.",
+      "To show how screens connect, give elements or screens an id prop and add Flow elements as Board children (after the Screens), with from and to set to those ids.",
+      "Any element except Board, Screen, Note and Flow can take a tooltip prop (text) to show a tooltip next to it. Select (with options), Input with type date, and Button, ListItem or NavBar (with menu) take open to show their list, calendar or menu over the screen.",
       "This is a low-fidelity wireframe: prefer placeholders (Image boxes, Text with lines) over invented copy, unless the copy matters to the design.",
       'Every element MUST include a "children" array. Leaf elements use an empty array: "children": [].',
       "Every id listed in a children array MUST exist as its own element."
@@ -224,11 +225,14 @@ var justify = z.enum(["start", "center", "end", "between", "around"]);
 var iconName = z.string().refine(isIcon, { error: (iss) => unknownIconMessage(String(iss.input)) }).describe("Lucide icon name in kebab-case, e.g. menu, search, arrow-left, settings, bell, user");
 var day = z.number().int().min(1).max(31);
 var percent = z.number().min(0).max(100);
+var flowEnd = z.enum(["none", "arrow", "dot", "circle", "bar"]);
 var menuItem = z.union([z.string(), z.strictObject({ label: z.string(), icon: o(iconName) })]);
 var UNIVERSAL_PROPS = {
   tooltip: z.string().describe("Show a tooltip with this text next to the element")
 };
-var takesUniversalProps = (type) => type !== "Board" && type !== "Screen" && type !== "Note";
+var ID_PATTERN = /^[A-Za-z][\w-]*$/;
+var takesId = (type) => type !== "Board" && type !== "Note" && type !== "Flow";
+var takesUniversalProps = (type) => type !== "Board" && type !== "Screen" && type !== "Note" && type !== "Flow";
 function universalPropMessage(type, key) {
   const base = `${key}s go on elements inside a screen`;
   return type === "Note" ? `${base}; a note is already an annotation, so put the text in the note` : `${base}, not on the ${type.toLowerCase()} itself`;
@@ -252,7 +256,7 @@ var componentDefinitions = {
       )
     }),
     slots: ["default"],
-    description: "Root canvas (artboard). Holds Screens side by side, plus optional Notes. Must be the root element.",
+    description: "Root canvas (artboard). Holds Screens side by side, plus optional Notes and Flow lines. Must be the root element.",
     example: { title: "Checkout flow", layout: "row", gap: 64 }
   },
   Screen: {
@@ -279,6 +283,23 @@ var componentDefinitions = {
     description: "Sticky-note annotation. Put it on the Board beside screens, or inside a Screen next to what it explains.",
     example: { text: "Empty state TBD", color: "yellow" }
   },
+  Flow: {
+    props: z.object({
+      from: z.string().describe("The id where the arrow starts (written before ->)"),
+      to: z.string().describe("The id it points at (written after ->)"),
+      label: o(z.string()),
+      start: o(flowEnd).describe("Default none"),
+      end: o(flowEnd).describe("Default arrow"),
+      line: o(z.enum(["rounded", "hard", "curved", "straight"])).describe("Default rounded: right angles with rounded corners"),
+      dashed: o(z.boolean()),
+      color: o(z.string().refine((v) => v === "accent" || isAccent(v), { error: (iss) => `${accentMessage(String(iss.input))}, or accent for the board's` })).describe(
+        `Default gray. ${Object.keys(ACCENTS).join(", ")}, a hex color, or accent for the board's`
+      )
+    }),
+    slots: [],
+    description: 'An arrow between two elements or screens, named with #id. Written at the board level after the screens: flow signin -> home "Tap Sign in".',
+    example: { from: "signin", to: "home", label: "Tap Sign in" }
+  },
   // ── Layout ────────────────────────────────────────────────────────────
   Stack: {
     props: z.object({
@@ -736,7 +757,7 @@ function IconGlyph({ name, size = 20, color = theme.ink, strokeWidth = 2 }) {
 function Board({ element, children }) {
   const p = element.props;
   const gap = p.gap ?? BOARD_GAP;
-  const items = Children.toArray(children);
+  const items = Children.toArray(children).filter((c) => !(isValidElement(c) && c.props.element?.type === "Flow"));
   const perRow = p.layout === "grid" ? Math.max(1, p.columns ?? 3) : Math.max(1, items.length);
   const rows = [];
   for (let i = 0; i < items.length; i += perRow) rows.push(items.slice(i, i + perRow));
@@ -1037,9 +1058,9 @@ function Bullets({ element }) {
     const { label, icon, muted } = typeof item === "string" ? { label: item, icon: null, muted: false } : item;
     const color = muted ? theme.muted : theme.text;
     const glyph = icon ?? p.icon;
-    const marker = glyph ? /* @__PURE__ */ jsx(IconGlyph, { name: glyph, size: 18, color }) : p.numbered ? /* @__PURE__ */ jsx(Box, { style: { minWidth: 18, color, fontWeight: 600 }, children: `${i + 1}.` }) : /* @__PURE__ */ jsx(Box, { style: { width: 18, height: 22, alignItems: "center", justifyContent: "center" }, children: /* @__PURE__ */ jsx(Box, { style: { width: 6, height: 6, borderRadius: 3, backgroundColor: color } }) });
+    const marker2 = glyph ? /* @__PURE__ */ jsx(IconGlyph, { name: glyph, size: 18, color }) : p.numbered ? /* @__PURE__ */ jsx(Box, { style: { minWidth: 18, color, fontWeight: 600 }, children: `${i + 1}.` }) : /* @__PURE__ */ jsx(Box, { style: { width: 18, height: 22, alignItems: "center", justifyContent: "center" }, children: /* @__PURE__ */ jsx(Box, { style: { width: 6, height: 6, borderRadius: 3, backgroundColor: color } }) });
     return /* @__PURE__ */ jsxs(Box, { style: { gap: 10, alignItems: glyph ? "center" : "flex-start", fontSize: 15, lineHeight: 1.45, color }, children: [
-      marker,
+      marker2,
       /* @__PURE__ */ jsx(Box, { style: { flexShrink: 1 }, children: label })
     ] }, i);
   }) });
@@ -1758,8 +1779,12 @@ function Toast({ element, aboveTabBar }) {
     p.action ? /* @__PURE__ */ jsx(Box, { style: { fontWeight: 700, marginLeft: 8, flexShrink: 0 }, children: p.action }) : null
   ] }) });
 }
+function Flow() {
+  return null;
+}
 var registry = {
   Board,
+  Flow,
   Screen,
   Note,
   Stack,
@@ -1824,6 +1849,7 @@ var PRIMARY_PROP = {
   Modal: "title",
   Drawer: "title",
   Accordion: "title",
+  Flow: "label",
   Toast: "text"
 };
 function unwrap(t) {
@@ -2079,8 +2105,19 @@ function parseWireframeText(source) {
       return;
     }
     const props = {};
+    let rest = m[2];
+    if (info.name === "Flow") {
+      const ends = rest.match(/^\s*#?([A-Za-z][\w-]*)\s*->\s*#?([A-Za-z][\w-]*)(?=\s|$)(.*)$/);
+      if (!ends) {
+        issues.push({ line: lineNo, message: `a flow line looks like: flow <from> -> <to> "label", where from and to are ids written #name after an element or screen` });
+        return;
+      }
+      props.from = ends[1];
+      props.to = ends[2];
+      rest = ends[3];
+    }
     try {
-      const c = new Cursor(tokenize(m[2]), m[2]);
+      const c = new Cursor(tokenize(rest), rest);
       while (!c.done()) {
         c.skipCommas();
         if (c.done()) break;
@@ -2120,6 +2157,11 @@ function parseWireframeText(source) {
           props[ANTONYMS[t.value]] = false;
         } else if (t.kind === "word" && WORD_PRIMARY.has(info.name) && !(PRIMARY_PROP[info.name] in props)) {
           props[PRIMARY_PROP[info.name]] = t.value;
+        } else if (t.kind === "word" && t.value.startsWith("#") && ID_PATTERN.test(t.value.slice(1)) && takesId(info.name)) {
+          if (props.id != null) issues.push({ line: lineNo, message: `two ids (#${props.id} and ${t.value}); an element has one` });
+          else props.id = t.value.slice(1);
+        } else if (t.kind === "word" && t.value.startsWith("#") && ID_PATTERN.test(t.value.slice(1))) {
+          issues.push({ line: lineNo, message: `${info.name} can't have an id (${t.value}); ids name elements and screens for flow arrows` });
         } else if (t.kind === "word" && t.value.startsWith("#")) {
           issues.push({ line: lineNo, message: `"${t.value}": a comment must be on its own line, starting with #; to show # as text, quote it` });
           break;
@@ -2422,6 +2464,191 @@ function overlayLayer(spec, anchors, boxes, c, Calendar2) {
   }) }, "__overlays");
 }
 
+// src/flows.tsx
+import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+var DIR = { left: { x: -1, y: 0 }, right: { x: 1, y: 0 }, top: { x: 0, y: -1 }, bottom: { x: 0, y: 1 } };
+var port = (b, s) => s === "left" ? { x: b.x, y: b.y + b.h / 2 } : s === "right" ? { x: b.x + b.w, y: b.y + b.h / 2 } : s === "top" ? { x: b.x + b.w / 2, y: b.y } : { x: b.x + b.w / 2, y: b.y + b.h };
+var add = (p, d, k) => ({ x: p.x + d.x * k, y: p.y + d.y * k });
+var LANE_GAP = 16;
+var flowMargin = (flows) => 40 + LANE_GAP * Math.max(0, flows - 1);
+var same = (a, b) => a.x === b.x && a.y === b.y && a.w === b.w && a.h === b.h;
+var overlapsY = (a, b) => a.y < b.y + b.h && b.y < a.y + a.h;
+function route(ends, screens, gap, lane = 0, track = 0, nudge = 0) {
+  const { from: a, to: b, fromScreen: sa, toScreen: sb } = ends;
+  if (same(sa, sb)) {
+    if (b.x >= a.x + a.w - 1) {
+      const s3 = port(a, "right"), e3 = port(b, "left"), mx = (s3.x + e3.x) / 2;
+      return { from: "right", to: "left", points: [s3, { x: mx, y: s3.y }, { x: mx, y: e3.y }, e3] };
+    }
+    if (b.x + b.w <= a.x + 1) {
+      const s3 = port(a, "left"), e3 = port(b, "right"), mx = (s3.x + e3.x) / 2;
+      return { from: "left", to: "right", points: [s3, { x: mx, y: s3.y }, { x: mx, y: e3.y }, e3] };
+    }
+    const down = b.y >= a.y + a.h / 2;
+    const s2 = port(a, down ? "bottom" : "top"), e2 = port(b, down ? "top" : "bottom"), my = (s2.y + e2.y) / 2;
+    return { from: down ? "bottom" : "top", to: down ? "top" : "bottom", points: [s2, { x: s2.x, y: my }, { x: e2.x, y: my }, e2] };
+  }
+  const right = sb.x >= sa.x + sa.w, left = sb.x + sb.w <= sa.x;
+  const from = right ? "right" : "left", to = right ? "left" : "right";
+  const s = port(a, from), e = port(b, to);
+  const level = (y, r) => Math.max(r.y + 24, Math.min(r.y + r.h - 24, y));
+  if (same(b, sb) && !same(a, sa)) e.y = level(s.y + nudge, sb);
+  if (same(a, sa) && !same(b, sb)) s.y = level(e.y + nudge, sa);
+  const shift = Math.max(-(gap / 2 - 8), Math.min(gap / 2 - 8, TRACKS[track % TRACKS.length]));
+  const lo = right ? sa : sb, hi = right ? sb : sa;
+  const between = screens.some((r) => !same(r, sa) && !same(r, sb) && overlapsY(r, sa) && r.x >= lo.x + lo.w && r.x + r.w <= hi.x);
+  if ((right || left) && !between && overlapsY(sa, sb)) {
+    const mx = (lo.x + lo.w + hi.x) / 2 + shift;
+    return { from, to, points: [s, { x: mx, y: s.y }, { x: mx, y: e.y }, e] };
+  }
+  const below = Math.max(...screens.map((r) => r.y + r.h)) + 24 + lane * LANE_GAP;
+  const gx1 = right ? sa.x + sa.w + gap / 2 + shift : sa.x - gap / 2 + shift;
+  const gx2 = right ? sb.x - gap / 2 + shift : sb.x + sb.w + gap / 2 + shift;
+  return { from, to, lane: below, points: [s, { x: gx1, y: s.y }, { x: gx1, y: below }, { x: gx2, y: below }, { x: gx2, y: e.y }, e] };
+}
+var runs = (r) => r.points.slice(1).flatMap((p, i) => {
+  const q = r.points[i];
+  return Math.abs(p.y - q.y) < 0.5 && Math.abs(p.x - q.x) > 0.5 ? [{ y: p.y, x1: Math.min(p.x, q.x), x2: Math.max(p.x, q.x) }] : [];
+});
+var TRACKS = [0, -10, 10, -20, 20, -5, 5, -15, 15];
+function simplify(points) {
+  const out = [];
+  for (const p of points) {
+    const last = out[out.length - 1];
+    if (last && Math.abs(last.x - p.x) < 0.5 && Math.abs(last.y - p.y) < 0.5) continue;
+    if (out.length >= 2) {
+      const a = out[out.length - 2], b = out[out.length - 1];
+      if (Math.abs(a.x - b.x) < 0.5 && Math.abs(b.x - p.x) < 0.5 || Math.abs(a.y - b.y) < 0.5 && Math.abs(b.y - p.y) < 0.5) out.pop();
+    }
+    out.push(p);
+  }
+  return out;
+}
+function polylinePath(points, radius) {
+  const pts = simplify(points);
+  let d = `M${pts[0].x} ${pts[0].y}`;
+  for (let i = 1; i < pts.length; i++) {
+    const p = pts[i];
+    if (radius > 0 && i < pts.length - 1) {
+      const prev = pts[i - 1], next = pts[i + 1];
+      const r = Math.min(radius, Math.hypot(p.x - prev.x, p.y - prev.y) / 2, Math.hypot(next.x - p.x, next.y - p.y) / 2);
+      const into = { x: Math.sign(p.x - prev.x), y: Math.sign(p.y - prev.y) }, out = { x: Math.sign(next.x - p.x), y: Math.sign(next.y - p.y) };
+      d += ` L${p.x - into.x * r} ${p.y - into.y * r} Q${p.x} ${p.y} ${p.x + out.x * r} ${p.y + out.y * r}`;
+    } else d += ` L${p.x} ${p.y}`;
+  }
+  return d;
+}
+function along(points, t) {
+  const pts = simplify(points);
+  const lengths = pts.slice(1).map((p, i) => Math.hypot(p.x - pts[i].x, p.y - pts[i].y));
+  let left = lengths.reduce((a, b) => a + b, 0) * t;
+  for (let i = 0; i < lengths.length; i++) {
+    if (left <= lengths[i]) {
+      const f = lengths[i] ? left / lengths[i] : 0;
+      return { x: pts[i].x + (pts[i + 1].x - pts[i].x) * f, y: pts[i].y + (pts[i + 1].y - pts[i].y) * f };
+    }
+    left -= lengths[i];
+  }
+  return pts[pts.length - 1];
+}
+var INSET = { none: 0, arrow: 9, dot: 4, circle: 9, bar: 0 };
+function marker(kind, p, out, color, key) {
+  if (kind === "none") return null;
+  const perp = { x: -out.y, y: out.x };
+  if (kind === "arrow") {
+    const base = add(p, out, 10);
+    const pts = [p, add(base, perp, 5.5), add(base, perp, -5.5)].map((q) => `${q.x},${q.y}`).join(" ");
+    return /* @__PURE__ */ jsx3("polygon", { points: pts, fill: color }, key);
+  }
+  if (kind === "dot") {
+    const c = add(p, out, 4);
+    return /* @__PURE__ */ jsx3("circle", { cx: c.x, cy: c.y, r: 4, fill: color }, key);
+  }
+  if (kind === "circle") {
+    const c = add(p, out, 5);
+    return /* @__PURE__ */ jsx3("circle", { cx: c.x, cy: c.y, r: 4.5, fill: theme.paper, stroke: color, strokeWidth: 2 }, key);
+  }
+  const a = add(p, perp, 7), b = add(p, perp, -7);
+  return /* @__PURE__ */ jsx3("line", { x1: a.x, y1: a.y, x2: b.x, y2: b.y, stroke: color, strokeWidth: 2.5, strokeLinecap: "round" }, key);
+}
+var GRAY2 = "#5f6770";
+function linePath(r, pts, line) {
+  const s0 = pts[0], e0 = pts[pts.length - 1];
+  if (r.lane == null && line === "straight") {
+    return { d: `M${s0.x} ${s0.y} L${e0.x} ${e0.y}`, at: (t) => ({ x: s0.x + (e0.x - s0.x) * t, y: s0.y + (e0.y - s0.y) * t }) };
+  }
+  if (r.lane == null && line === "curved") {
+    const k = Math.max(40, Math.hypot(e0.x - s0.x, e0.y - s0.y) * 0.4);
+    const c1 = add(s0, DIR[r.from], k), c2 = add(e0, DIR[r.to], k);
+    const bez = (a, b, c, e, t) => (1 - t) ** 3 * a + 3 * (1 - t) ** 2 * t * b + 3 * (1 - t) * t ** 2 * c + t ** 3 * e;
+    return { d: `M${s0.x} ${s0.y} C${c1.x} ${c1.y} ${c2.x} ${c2.y} ${e0.x} ${e0.y}`, at: (t) => ({ x: bez(s0.x, c1.x, c2.x, e0.x, t), y: bez(s0.y, c1.y, c2.y, e0.y, t) }) };
+  }
+  return { d: polylinePath(pts, line === "curved" ? 40 : line === "rounded" ? 14 : 0), at: (t) => along(pts, t) };
+}
+var flowLabelWidth = (label) => Math.min(220, Math.ceil(label.length * 7.2) + 20);
+function flowColor(color, palette) {
+  if (color == null) return GRAY2;
+  if (color === "accent") return palette.accent;
+  const s = String(color);
+  return ACCENTS[s] ?? s;
+}
+function flowLayer(spec, flows, screens, gap, palette, size) {
+  const shapes = [];
+  const labels = [];
+  const placed = [];
+  const drawn = [];
+  const tips = flows.flatMap(({ ends: ends2 }) => {
+    const r = route(ends2, screens, gap);
+    return [...same(ends2.from, ends2.fromScreen) ? [] : [r.points[0]], ...same(ends2.to, ends2.toScreen) ? [] : [r.points[r.points.length - 1]]];
+  });
+  let lanes = 0, tracks = 0;
+  const routes = flows.map(({ ends: ends2 }) => {
+    let r = route(ends2, screens, gap, lanes, tracks);
+    const clash = (r2) => runs(r2).some((h) => drawn.some((g) => Math.abs(g.y - h.y) < 8 && g.x1 < h.x2 && h.x1 < g.x2)) || [r2.points[0], r2.points[r2.points.length - 1]].some((p) => tips.some((q) => q !== p && Math.hypot(p.x - q.x, p.y - q.y) > 0.5 && Math.hypot(p.x - q.x, p.y - q.y) < 24));
+    for (let k = 1; k <= 4 && clash(r); k++) r = route(ends2, screens, gap, lanes, tracks, 48 * k);
+    drawn.push(...runs(r));
+    tips.push(r.points[0], r.points[r.points.length - 1]);
+    if (r.lane != null) lanes++;
+    if (!same(ends2.fromScreen, ends2.toScreen)) tracks++;
+    return r;
+  });
+  const ends = routes.flatMap((r) => [r.points[0], r.points[r.points.length - 1]]);
+  flows.forEach(({ key }, i) => {
+    const r = routes[i];
+    const p = spec.elements[key].props ?? {};
+    const color = flowColor(p.color, palette);
+    const start = p.start ?? "none", end = p.end ?? "arrow";
+    const pts = [...r.points];
+    pts[0] = add(pts[0], DIR[r.from], INSET[start]);
+    pts[pts.length - 1] = add(pts[pts.length - 1], DIR[r.to], INSET[end]);
+    const { d, at } = linePath(r, pts, p.line ?? "rounded");
+    shapes.push(
+      /* @__PURE__ */ jsx3("path", { d, fill: "none", stroke: color, strokeWidth: 2, strokeLinejoin: "round", strokeLinecap: "round", ...p.dashed ? { strokeDasharray: "7 6" } : {} }, `${key}-line`),
+      marker(start, r.points[0], DIR[r.from], color, `${key}-start`),
+      marker(end, r.points[r.points.length - 1], DIR[r.to], color, `${key}-end`)
+    );
+    if (p.label) {
+      const w = flowLabelWidth(String(p.label));
+      const covers = (c) => placed.filter((q) => c.x - w / 2 < q.x + q.w && q.x < c.x + w / 2 && c.y - 14 < q.y + q.h && q.y < c.y + 14).length + ends.filter((q) => Math.abs(q.x - c.x) < w / 2 + 12 && Math.abs(q.y - c.y) < 24).length;
+      let mid = at(0.5), best = covers(mid);
+      for (const t of [0.4, 0.6, 0.3, 0.7, 0.2, 0.8, 0.12, 0.88]) {
+        if (!best) break;
+        const c = at(t), n = covers(c);
+        if (n < best) [mid, best] = [c, n];
+      }
+      const top = mid.y - 12;
+      placed.push({ x: mid.x - w / 2, y: top, w, h: 24 });
+      labels.push(
+        /* @__PURE__ */ jsx3("div", { style: { position: "absolute", left: mid.x - w / 2, top, width: w, height: 24, display: "flex", alignItems: "center", justifyContent: "center", borderRadius: 12, backgroundColor: theme.paper, border: `1.5px solid ${color}`, color, fontSize: 12, fontWeight: 600 }, children: p.label }, `${key}-label`)
+      );
+    }
+  });
+  return /* @__PURE__ */ jsxs3("div", { style: { position: "absolute", top: 0, left: 0, width: size.width, height: size.height, display: "flex" }, children: [
+    /* @__PURE__ */ jsx3("svg", { width: size.width, height: size.height, viewBox: `0 0 ${size.width} ${size.height}`, style: { position: "absolute", top: 0, left: 0 }, children: shapes }),
+    labels
+  ] }, "__flows");
+}
+
 // src/render.ts
 var fontFile = (name) => createRequire(import.meta.url).resolve(`@fontsource/inter/files/${name}`);
 var fontCache = null;
@@ -2485,6 +2712,11 @@ function checkSpec(spec) {
         }
       }
       for (const key of Object.keys(el.props ?? {})) {
+        if (key === "id" && takesId(el.type)) {
+          const v = el.props.id;
+          if (typeof v !== "string" || !ID_PATTERN.test(v)) issues.push(`${id}: the id "${v}" should be a word: letters, digits, - and _, starting with a letter`);
+          continue;
+        }
         if (key in UNIVERSAL_PROPS) {
           if (!takesUniversalProps(el.type)) issues.push(`${id}: ${universalPropMessage(el.type, key)}`);
           else {
@@ -2565,14 +2797,50 @@ function checkSpec(spec) {
       }
     }
   }
+  const owners = /* @__PURE__ */ new Map();
+  for (const [key, el] of Object.entries(spec.elements)) {
+    const ref = el.props?.id;
+    if (typeof ref !== "string" || !takesId(el.type)) continue;
+    const other = owners.get(ref.toLowerCase());
+    if (other) issues.push(`${key}: the id #${ref} is also used by ${spec.elements[other.key].type} "${other.key}"${other.id === ref ? "" : ` (as #${other.id}; ids ignore case)`}; ids must be unique`);
+    else owners.set(ref.toLowerCase(), { key, id: ref });
+  }
+  const written = [...owners.values()].map((o2) => o2.id);
+  const parentOf = /* @__PURE__ */ new Map();
+  for (const [k, el] of Object.entries(spec.elements)) for (const c of el.children ?? []) parentOf.set(c, k);
+  for (const [key, el] of Object.entries(spec.elements)) {
+    if (el.type !== "Flow") continue;
+    if (!(root.children ?? []).includes(key)) issues.push(`${key}: flow lines go at the board level, after the screens (indented like a screen)`);
+    const p = el.props ?? {};
+    for (const end of ["from", "to"]) {
+      if (typeof p[end] !== "string") continue;
+      const owner = owners.get(p[end].toLowerCase());
+      if (owner) {
+        for (let k = parentOf.get(owner.key); k; k = parentOf.get(k)) {
+          const el2 = spec.elements[k];
+          if (el2?.type === "Accordion" && !el2.props?.open) {
+            issues.push(`${key}: #${owner.id} is inside Accordion "${k}", which is closed, so it isn't drawn; add open to the accordion, or give the accordion the id instead`);
+            break;
+          }
+        }
+        continue;
+      }
+      const close = closeMatches(p[end], written);
+      issues.push(
+        `${key}: no element has the id #${p[end]}` + (close.length ? ` (did you mean ${close.map((c) => "#" + c).join(", ")}?)` : owners.size ? ` (ids on this board: ${written.map((c) => "#" + c).join(", ")})` : "; name an element by writing #name after it")
+      );
+    }
+    if (typeof p.from === "string" && typeof p.to === "string" && p.from.toLowerCase() === p.to.toLowerCase()) issues.push(`${key}: a flow needs two different ends (both are #${p.from})`);
+  }
   return issues;
 }
-function boardLayout(spec) {
+function boardLayout(spec, opts = {}) {
   const board = spec.elements[spec.root];
   const p = board.props ?? {};
-  const gap = p.gap ?? BOARD_GAP;
   const pad = p.padding ?? BOARD_PADDING;
-  const kids = (board.children ?? []).map((id) => spec.elements[id]).filter(Boolean);
+  const laidOut = (board.children ?? []).filter((id) => spec.elements[id]?.type === "Screen" || spec.elements[id]?.type === "Note");
+  const kids = laidOut.map((id) => spec.elements[id]);
+  const gap = p.gap ?? (opts.flows !== false ? Math.max(BOARD_GAP, flowLabelGap(spec, laidOut, p.layout === "grid" ? Math.max(1, p.columns ?? 3) : laidOut.length)) : BOARD_GAP);
   const boxes = kids.map((el) => {
     const props = el.props ?? {};
     if (el.type === "Screen") {
@@ -2600,10 +2868,33 @@ function boardLayout(spec) {
     width = Math.max(width, row.reduce((sum, b) => sum + (b?.w ?? 0), 0) + gap * (row.length - 1));
     y += Math.max(...row.map((b) => b?.h ?? 0));
   }
-  return { width: Math.ceil(width + pad * 2), height: Math.ceil(y + pad), items };
+  const flowCount = (board.children ?? []).filter((id) => spec.elements[id]?.type === "Flow").length;
+  const flowRoom = opts.flows !== false && flowCount ? flowMargin(flowCount) : 0;
+  return { width: Math.ceil(width + pad * 2), height: Math.ceil(y + pad + flowRoom), items, gap };
+}
+function flowLabelGap(spec, laidOut, perRow) {
+  const els = spec.elements;
+  const parent = /* @__PURE__ */ new Map();
+  for (const [key, el] of Object.entries(els)) for (const c of el.children ?? []) parent.set(c, key);
+  const ids = /* @__PURE__ */ new Map();
+  for (const [key, el] of Object.entries(els)) if (typeof el.props?.id === "string") ids.set(el.props.id.toLowerCase(), key);
+  const slot = (id) => {
+    let k = ids.get(String(id).toLowerCase());
+    while (k && els[k]?.type !== "Screen") k = parent.get(k);
+    return k ? laidOut.indexOf(k) : -1;
+  };
+  let widest = 0;
+  for (const key of els[spec.root].children ?? []) {
+    const f = els[key];
+    if (f?.type !== "Flow" || !f.props?.label) continue;
+    const a = slot(f.props.from), b = slot(f.props.to);
+    if (a < 0 || b < 0 || Math.abs(a - b) !== 1 || Math.floor(a / perRow) !== Math.floor(b / perRow)) continue;
+    widest = Math.max(widest, flowLabelWidth(String(f.props.label)));
+  }
+  return widest ? widest + 32 : 0;
 }
-function boardSize(spec) {
-  const { width, height } = boardLayout(spec);
+function boardSize(spec, opts = {}) {
+  const { width, height } = boardLayout(spec, opts);
   return { width, height };
 }
 async function renderWireframeSvg(spec, opts = {}) {
@@ -2612,20 +2903,64 @@ async function renderWireframeSvg(spec, opts = {}) {
     const issues = checkSpec(spec);
     if (issues.length) throw new SpecError(issues);
   }
-  const { width, height } = boardSize(spec);
+  const flowsOn = opts.flows !== false;
+  const { width, height, gap } = boardLayout(spec, { flows: opts.flows });
+  const board = spec.elements[spec.root];
+  if ((board.props ?? {}).gap == null && gap !== BOARD_GAP)
+    spec = { ...spec, elements: { ...spec.elements, [spec.root]: { ...board, props: { ...board.props, gap } } } };
   const palette = paletteFor(spec.elements[spec.root]?.props?.accent);
   const registry2 = withPalette(palette);
   const draw = async (s, reg) => renderToSvg(s, { registry: reg, includeStandard: false, fonts: await loadFonts(), width, height });
-  const { anchors, boxes } = await measureAnchors(spec);
-  if (!anchors.length) return draw(spec, registry2);
-  return draw(spec, withTopLayer(registry2, overlayLayer(spec, anchors, boxes, palette, registry2.Calendar)));
+  const flows = flowsOn ? flowEnds(spec) : null;
+  const { anchors, boxes } = await measureAnchors(spec, flows?.measure ?? []);
+  if (!anchors.length && !flows?.list.length) return draw(spec, registry2);
+  const layers = [];
+  if (flows?.list.length) {
+    const resolved = flows.list.map(({ key, from, to }) => ({ key, ends: { from: flows.box(from, boxes) ?? flows.screenBox(from), to: flows.box(to, boxes) ?? flows.screenBox(to), fromScreen: flows.screenBox(from), toScreen: flows.screenBox(to) } })).filter((f) => !!(f.ends.from && f.ends.to && f.ends.fromScreen && f.ends.toScreen));
+    layers.push(flowLayer(spec, resolved, flows.screens, flows.gap, palette, { width, height }));
+  }
+  if (anchors.length) layers.push(overlayLayer(spec, anchors, boxes, palette, registry2.Calendar));
+  return draw(spec, withTopLayer(registry2, layers));
+}
+function flowEnds(spec) {
+  const els = spec.elements;
+  const byId = /* @__PURE__ */ new Map();
+  for (const [key, el] of Object.entries(els)) if (typeof el.props?.id === "string") byId.set(el.props.id.toLowerCase(), key);
+  const parent = /* @__PURE__ */ new Map();
+  for (const [key, el] of Object.entries(els)) for (const c of el.children ?? []) parent.set(c, key);
+  const screenOf = (key) => {
+    let k = key;
+    while (k && els[k]?.type !== "Screen") k = parent.get(k);
+    return k;
+  };
+  const { items } = boardLayout(spec);
+  const laidOut = (els[spec.root].children ?? []).filter((k) => els[k]?.type === "Screen" || els[k]?.type === "Note");
+  const screenRects = /* @__PURE__ */ new Map();
+  laidOut.forEach((k, i) => {
+    const it = items[i];
+    if (it && els[k].type === "Screen") screenRects.set(k, { x: it.x, y: it.y + LABEL_H, w: it.width, h: it.height - LABEL_H });
+  });
+  const list = (els[spec.root].children ?? []).filter((k) => els[k]?.type === "Flow").map((key) => {
+    const p = els[key].props ?? {};
+    return { key, from: byId.get(String(p.from).toLowerCase()), to: byId.get(String(p.to).toLowerCase()) };
+  }).filter((f) => !!f.from && !!f.to);
+  const measure = [...new Set(list.flatMap((f) => [f.from, f.to]))].filter((k) => els[k].type !== "Screen");
+  return {
+    list,
+    measure,
+    screens: [...screenRects.values()],
+    screenBox: (key) => screenRects.get(screenOf(key) ?? ""),
+    gap: (els[spec.root].props ?? {}).gap ?? BOARD_GAP,
+    box: (key, boxes) => els[key].type === "Screen" ? screenRects.get(key) : boxes[key]
+  };
 }
-async function measureAnchors(spec) {
+async function measureAnchors(spec, extra = []) {
   const anchors = findAnchors(spec);
-  if (!anchors.length) return { anchors, boxes: {} };
+  const extras = extra.map((id) => ({ id, screen: id, kind: "tooltip", field: false }));
+  if (!anchors.length && !extras.length) return { anchors, boxes: {} };
   const { width, height } = boardSize(spec);
   const registry2 = withPalette(paletteFor());
-  const { tagged, colors } = tagForMeasuring(spec, anchors);
+  const { tagged, colors } = tagForMeasuring(spec, [...anchors, ...extras]);
   const svg = await renderToSvg(tagged, { registry: withMarkers(registry2), includeStandard: false, fonts: await loadFonts(), width, height });
   return { anchors, boxes: readMarkers(svg, colors) };
 }
@@ -2676,7 +3011,7 @@ ${formatIssues(issues)}`);
 async function renderWireframe(source, opts = {}) {
   const { spec, issues } = compileWireframe(source);
   if (!spec || issues.length) throw new WireframeError(issues);
-  return opts.format === "png" ? renderWireframePng(spec, { skipValidation: true, scale: opts.scale }) : renderWireframeSvg(spec, { skipValidation: true });
+  return opts.format === "png" ? renderWireframePng(spec, { skipValidation: true, scale: opts.scale, flows: opts.flows }) : renderWireframeSvg(spec, { skipValidation: true, flows: opts.flows });
 }
 
 // src/print.ts
@@ -2719,6 +3054,13 @@ function printWireframeText(spec, indentUnit = "  ") {
     const el = spec.elements[id];
     const props = { ...el.props ?? {} };
     const parts = [el.type.toLowerCase()];
+    if (el.type === "Flow") {
+      parts.push(`${props.from} -> ${props.to}`);
+      delete props.from;
+      delete props.to;
+    }
+    const elementId = typeof props.id === "string" ? props.id : null;
+    delete props.id;
     const enums = bareEnums(el.type);
     const bools = booleans(el.type);
     const primary = PRIMARY_PROP[el.type];
@@ -2737,6 +3079,7 @@ function printWireframeText(spec, indentUnit = "  ") {
       if (v === true && bools.has(k)) parts.push(k);
       else parts.push(`${k}=${fmt(v)}`);
     }
+    if (elementId) parts.push(`#${elementId}`);
     out.push(indentUnit.repeat(depth) + parts.join(" "));
     for (const c of el.children ?? []) walk(c, depth + 1);
   };
@@ -2839,15 +3182,16 @@ function componentReference() {
   return lines.join("\n");
 }
 var RULES = `## Rules
-1. The top element is a Board. The Board's children are Screens, plus optional Notes beside them.
+1. The top element is a Board. The Board's children are Screens, plus optional Notes beside them and Flow lines after them (rule 10).
 2. Each Screen is one view of the product. Use several Screens to show several views or states.
 3. A Screen lays out its children top to bottom. Use Stack (direction row or column) and Grid to arrange content.
 4. NavBar is pinned to the top of its Screen and TabBar to the bottom.
 5. Modal, Drawer and Toast are overlays. They must be direct children of a Screen.
 6. This is a low-fidelity wireframe. Prefer placeholders (Image boxes, Text with lines) over invented copy unless the copy matters.
 7. Only use the components and props listed below. All props are optional unless marked required.
-8. Wireframes are grayscale. The only UI colors: Board accent (one color for primary buttons, checked controls, toggles, active tabs and ghost buttons), Badge tone (success, warning, danger) and Input error. Only add an accent if the request asks for color or a brand.
-9. Any element except Board, Screen and Note can take tooltip="text" to show a tooltip next to it. Select (with options), Input type=date, and Button, ListItem or NavBar (with menu) take open to show their list, calendar or menu over the screen.`;
+8. Wireframes are grayscale. The only UI colors: Board accent (one color for primary buttons, checked controls, toggles, active tabs and ghost buttons), Badge tone (success, warning, danger), Input error and Flow color. Only add an accent if the request asks for color or a brand.
+9. Any element except Board, Screen, Note and Flow can take tooltip="text" to show a tooltip next to it. Select (with options), Input type=date, and Button, ListItem or NavBar (with menu) take open to show their list, calendar or menu over the screen.
+10. To show how screens connect, name elements or screens by writing #name after them (button primary "Sign in" #signin, screen phone "Home" #home), then add board-level lines after the screens: flow signin -> home "Tap Sign in".`;
 var TEXT_FORMAT = `## Output format: wireframe text
 One element per line. Indent children two spaces under their parent. The first line is the board.
 

package/dist/cli.js

@@ -6,14 +6,14 @@ import {
   printWireframeText,
   renderWireframe,
   wireframePrompt
-} from "./chunks/chunk-B6KIVOSH.js";
+} from "./chunks/chunk-HDSKRKDL.js";
 
 // src/cli.ts
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 var USAGE = `tsquare \u2014 render wireframe text to SVG or PNG
 
-  tsquare render <file.tsq|-> [-o out.svg|out.png] [--scale 2]
+  tsquare render <file.tsq|-> [-o out.svg|out.png] [--scale 2] [--no-flows]
   tsquare check  <file.tsq|->      report problems by line number
   tsquare fmt    <file.tsq|-> [-w] print in canonical form (-w rewrites the file; drops comments)
   tsquare prompt                   print the system prompt for models
@@ -69,7 +69,7 @@ async function main(argv) {
   }
   const out = flag("-o") ?? (file === "-" ? "wireframe.svg" : file.replace(/\.(tsq|wf)$/, "") + ".svg");
   const png = out.endsWith(".png");
-  const data = await renderWireframe(source, { format: png ? "png" : "svg", scale: Number(flag("--scale") ?? 1) });
+  const data = await renderWireframe(source, { format: png ? "png" : "svg", scale: Number(flag("--scale") ?? 1), flows: !rest.includes("--no-flows") });
   await writeFile(out, data);
   console.log(`\u2713 wrote ${path.relative(process.cwd(), out)}`);
 }

package/dist/compile.d.ts

@@ -21,4 +21,5 @@ export declare class WireframeError extends Error {
 export declare function renderWireframe(source: string, opts?: {
     format?: "svg" | "png";
     scale?: number;
+    flows?: boolean;
 }): Promise<string | Buffer<ArrayBufferLike>>;

package/dist/components.d.ts

@@ -75,8 +75,11 @@ declare function Drawer({ element, children }: Props): React.JSX.Element;
 declare function Toast({ element, aboveTabBar }: Props & {
     aboveTabBar?: boolean;
 }): React.JSX.Element;
+/** Flow lines draw nothing in place; flows.tsx draws them over the board. */
+declare function Flow(): null;
 export declare const registry: {
     Board: typeof Board;
+    Flow: typeof Flow;
     Screen: typeof Screen;
     Note: typeof Note;
     Stack: typeof Stack;