dreamcontext 0.17.1 → 0.18.0

package/dist/skill-packs/excalidraw/examples/wireframe_board.js

@@ -0,0 +1,161 @@
+// wireframe_board.js — the device + product-UI kit, on one board.
+// Run:  node examples/wireframe_board.js   → examples/Wireframe Kit.excalidraw.md
+//
+// Doubles as the kit's smoke test. Note how each screen is composed: device() hands back `.inner`
+// (the safe region inside the bezel, below the island, above the home indicator) and everything is
+// flowed into it with stack()/row(). No screen coordinates are ever typed by hand.
+const path = require('path');
+const { buildExcalidraw } = require(path.resolve(__dirname, '../scripts/build_excalidraw.js'));
+const { sectionTitle, prose, stack, row, READ_W } = require(path.resolve(__dirname, '../scripts/lib/style.js'));
+const {
+  device, appBar, tabBar, icon, iconButton, iconNames,
+  listRow, toggle, segmented, slider, searchField,
+  button, input, textRows, imagePlaceholder, avatar, chip, navbar, windowFrame,
+} = require(path.resolve(__dirname, '../scripts/lib/wireframe.js'));
+
+const els = [];
+const P = (...a) => els.push(...a.flat());
+
+// flow the header — a hardcoded y let the wrapped title land on the prose (the audit caught it)
+P(stack({
+  x: 60, y: 40, gap: 12, items: [
+    (x, y) => sectionTitle({ x, y, text: 'Wireframe kit — cihaz kalıpları + UI kontrolleri', fontSize: 40, maxWidth: 1400 }),
+    (x, y) => prose({
+      x, y, width: READ_W, fontSize: 15,
+      text: 'Cihazlar gerçek oranlarda (iPhone 393×852, iPad 834×1194, Mac 1440×900). device() güvenli alanı .inner olarak döner — çocuklar oraya akar, chrome’a çarpamaz.',
+    }),
+  ],
+}));
+
+// ── iPhone: a feed screen ─────────────────────────────────────────────────
+const ph = device({ kind: 'iphone', x: 60, y: 180, label: 'iPhone — feed' });
+P(ph);
+P(stack({
+  x: ph.inner.x, y: ph.inner.y, gap: 10, items: [
+    (x, y) => appBar({ x, y, w: ph.inner.w, title: 'Discover', back: false, actions: ['bell', 'more-v'] }),
+    (x, y) => searchField({ x, y, w: ph.inner.w, placeholder: 'Ara…' }),
+    (x, y) => segmented({ x, y, w: ph.inner.w, items: ['Hepsi', 'Takip', 'Yeni'], active: 0 }),
+    (x, y) => imagePlaceholder({ x, y, w: ph.inner.w, h: 130, label: 'kapak' }),
+    (x, y) => textRows({ x, y, w: ph.inner.w, rows: 3 }),
+    (x, y) => row({
+      x, y, gap: 8, valign: 'middle', items: [
+        (x, y) => iconButton({ x, y, size: 32, icon: 'heart', variant: 'ghost', color: 'red' }),
+        (x, y) => iconButton({ x, y, size: 32, icon: 'share', variant: 'ghost' }),
+        (x, y) => iconButton({ x, y, size: 32, icon: 'bookmark', variant: 'ghost' }),
+        (x, y) => button({ x, y, w: 110, h: 32, text: 'Takip et', fontSize: 13 }),
+      ],
+    }),
+  ],
+}));
+// tab bar pinned to the bottom of the safe area
+P(tabBar({
+  x: ph.inner.x, y: ph.inner.y + ph.inner.h - 52, w: ph.inner.w, active: 0,
+  items: [{ icon: 'home', label: 'Akış' }, { icon: 'search', label: 'Ara' }, { icon: 'heart', label: 'Beğeni' }, { icon: 'user', label: 'Profil' }],
+}));
+
+// ── iPhone: a settings screen ─────────────────────────────────────────────
+const ph2 = device({ kind: 'iphone', x: 520, y: 180, label: 'iPhone — ayarlar' });
+P(ph2);
+P(stack({
+  x: ph2.inner.x, y: ph2.inner.y, gap: 0, items: [
+    (x, y) => appBar({ x, y, w: ph2.inner.w, title: 'Ayarlar', back: true }),
+    (x, y) => listRow({ x, y, w: ph2.inner.w, leading: 'avatar', title: 'Alex Doe', subtitle: 'Account, iCloud' }),
+    (x, y) => listRow({ x, y, w: ph2.inner.w, leading: 'bell', title: 'Bildirimler', trailing: 'toggle' }),
+    (x, y) => listRow({ x, y, w: ph2.inner.w, leading: 'lock', title: 'Gizlilik', trailing: 'chevron-right' }),
+    (x, y) => listRow({ x, y, w: ph2.inner.w, leading: 'settings', title: 'Genel', trailing: 'chevron-right' }),
+    (x, y) => listRow({ x, y, w: ph2.inner.w, leading: 'mail', title: 'Posta', trailing: '3', divider: false }),
+  ],
+}));
+
+// ── iPad: a split view ────────────────────────────────────────────────────
+const ip = device({ kind: 'ipad', x: 980, y: 180, label: 'iPad — split view' });
+P(ip);
+const sideW = Math.round(ip.inner.w * 0.34);
+P(stack({
+  x: ip.inner.x, y: ip.inner.y, gap: 0, items: [
+    (x, y) => listRow({ x, y, w: sideW, leading: 'home', title: 'Gelen kutusu', trailing: '12' }),
+    (x, y) => listRow({ x, y, w: sideW, leading: 'star', title: 'Yıldızlı' }),
+    (x, y) => listRow({ x, y, w: sideW, leading: 'bookmark', title: 'Kaydedilen' }),
+    (x, y) => listRow({ x, y, w: sideW, leading: 'trash', title: 'Çöp', divider: false }),
+  ],
+}));
+P(stack({
+  x: ip.inner.x + sideW + 16, y: ip.inner.y, gap: 12, items: [
+    (x, y) => appBar({ x, y, w: ip.inner.w - sideW - 16, title: 'Mesaj', back: false, actions: ['edit', 'trash'], border: false }),
+    (x, y) => imagePlaceholder({ x, y, w: ip.inner.w - sideW - 16, h: 150 }),
+    (x, y) => textRows({ x, y, w: ip.inner.w - sideW - 16, rows: 5 }),
+  ],
+}));
+
+// ── Mac: a desktop app ────────────────────────────────────────────────────
+// device({content}) is the safe pattern: widths derive from the `inner` you're handed, and anything
+// escaping the glass is reported. Hardcoding these columns overflowed the bezel by 26px.
+P(device({
+  kind: 'mac', x: 60, y: 1140, label: 'dreamcontext',
+  content: (inner) => {
+    const SIDE = Math.round(inner.w * 0.27), RIGHT = Math.round(inner.w * 0.25);
+    const MID = inner.w - SIDE - RIGHT - 32;
+    return stack({
+      x: inner.x, y: inner.y, gap: 12, items: [
+        (x, y) => navbar({ x, y, w: inner.w, brand: 'dreamcontext', items: ['Tasks', 'Knowledge', 'Roadmap'], cta: 'Sleep' }),
+        (x, y) => row({
+          x, y, gap: 16, valign: 'top', items: [
+            (x, y) => stack({
+              x, y, gap: 0, items: [
+                (x, y) => listRow({ x, y, w: SIDE, leading: 'home', title: 'Board' }),
+                (x, y) => listRow({ x, y, w: SIDE, leading: 'calendar', title: 'Roadmap' }),
+                (x, y) => listRow({ x, y, w: SIDE, leading: 'image', title: 'Diagrams', divider: false }),
+              ],
+            }),
+            (x, y) => stack({
+              x, y, gap: 12, items: [
+                (x, y) => searchField({ x, y, w: MID, placeholder: 'recall…' }),
+                (x, y) => textRows({ x, y, w: MID, rows: 4 }),
+                (x, y) => row({ x, y, gap: 10, items: [(x, y) => chip({ x, y, text: 'topic:excalidraw', color: 'blue' }), (x, y) => chip({ x, y, text: 'enhancement', color: 'green' })] }),
+              ],
+            }),
+            (x, y) => stack({
+              x, y, gap: 14, items: [
+                (x, y) => input({ x, y, w: RIGHT, label: 'Slug', placeholder: 'chart-kit' }),
+                (x, y) => slider({ x, y, w: RIGHT, value: 0.65 }),
+                (x, y) => row({ x, y, gap: 10, valign: 'middle', items: [(x, y) => toggle({ x, y, on: true }), (x, y) => toggle({ x, y, on: false })] }),
+                (x, y) => button({ x, y, w: RIGHT, text: 'Kaydet' }),
+                (x, y) => button({ x, y, w: RIGHT, text: 'Vazgeç', variant: 'outline', color: 'gray' }),
+              ],
+            }),
+          ],
+        }),
+      ],
+    });
+  },
+}));
+
+// ── icon set ──────────────────────────────────────────────────────────────
+const ICON_Y = 1900;
+P(sectionTitle({ x: 60, y: ICON_Y, text: `icon() — ${iconNames().length} glif`, fontSize: 26 }));
+const names = iconNames();
+const PER = 11, CELL = 92;
+names.forEach((n, i) => {
+  const cx = 60 + (i % PER) * CELL, cy = ICON_Y + 50 + Math.floor(i / PER) * 76;
+  P(icon({ name: n, x: cx + 18, y: cy, size: 26, color: '#1e1e1e' }));
+  P({ type: 'text', x: cx - 6, y: cy + 34, text: n, fontSize: 9, color: '#868e96', width: CELL - 6, align: 'center', fontFamily: 5 });
+});
+
+// ── iconButton variants ───────────────────────────────────────────────────
+const IB_Y = ICON_Y + 50 + Math.ceil(names.length / PER) * 76 + 30;
+P(sectionTitle({ x: 60, y: IB_Y, text: 'iconButton() — shape × variant', fontSize: 26 }));
+P(row({
+  x: 60, y: IB_Y + 46, gap: 18, valign: 'middle', items: [
+    (x, y) => iconButton({ x, y, icon: 'plus', shape: 'circle', variant: 'solid', color: 'blue' }),
+    (x, y) => iconButton({ x, y, icon: 'heart', shape: 'circle', variant: 'solid', color: 'red' }),
+    (x, y) => iconButton({ x, y, icon: 'check', shape: 'circle', variant: 'solid', color: 'green' }),
+    (x, y) => iconButton({ x, y, icon: 'search', shape: 'square', variant: 'outline' }),
+    (x, y) => iconButton({ x, y, icon: 'settings', shape: 'rounded', variant: 'outline' }),
+    (x, y) => iconButton({ x, y, icon: 'more-v', variant: 'ghost' }),
+    (x, y) => iconButton({ x, y, icon: 'share', variant: 'ghost' }),
+    (x, y) => iconButton({ x, y, icon: 'trash', shape: 'circle', variant: 'outline', color: 'red' }),
+  ],
+}));
+
+const res = buildExcalidraw({ out: path.resolve(__dirname, 'Wireframe Kit.excalidraw.md'), elements: els });
+console.log(`elements=${res.elements} texts=${res.texts} overlaps=${res.overlaps} buriedText=${res.buriedText} longLines=${res.longLines}`);

package/dist/skill-packs/excalidraw/scripts/build_excalidraw.js

@@ -21,11 +21,79 @@
 //   "elements": [ <ElementSpec>, ... ]
 // }
 // ElementSpec.type: text | image | rectangle | ellipse | diamond | line | arrow | frame
+//   ...plus any COMPOSITE type (chart / house-style widget / layout) — see COMPOSITES below. A
+//   composite element is expanded into primitives before the build, so the CLI can draw a whole
+//   lineChart or funnel declaratively without writing a generator script.
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const { generateNKeysBetween } = require('./lib/fractional-indexing.js');
 const { imageSize } = require('./lib/imagesize.js');
+const STYLE = require('./lib/style.js');
+const CHARTS = require('./lib/charts.js');
+const WF = require('./lib/wireframe.js');
+
+// ---------- composite element types (declarative surface) ----------
+// Every entry maps a spec `type` to a builder that returns an ElementSpec[]. The expander runs BEFORE
+// the primitive loop and is recursive, so composites may emit composites. This is what makes the JSON
+// surface as capable as the JS API — the same builders back both.
+const COMPOSITES = {
+  // charts
+  lineChart: CHARTS.lineChart, barChart: CHARTS.barChart, barCompare: CHARTS.barCompare,
+  stackedBar: CHARTS.stackedBar, gantt: CHARTS.gantt, quadrant: CHARTS.quadrant,
+  donut: CHARTS.donut, pie: (o) => CHARTS.donut(Object.assign({ inner: 0 }, o)),
+  sparkline: CHARTS.sparkline, heatmap: CHARTS.heatmap, table: CHARTS.table,
+  timeline: CHARTS.timeline, kpi: CHARTS.kpi, callout: CHARTS.callout,
+  // house style
+  funnel: STYLE.funnel, card: STYLE.card, node: STYLE.node, column: STYLE.column, hub: STYLE.hub,
+  connector: STYLE.connector, annotate: STYLE.annotate, chip: STYLE.chip, divider: STYLE.divider,
+  prose: STYLE.prose, bullets: STYLE.bullets, sectionTitle: STYLE.sectionTitle,
+  // wireframe kit
+  windowFrame: STYLE.windowFrame, navbar: STYLE.navbar, button: STYLE.button, input: STYLE.input,
+  textRows: STYLE.textRows, imagePlaceholder: STYLE.imagePlaceholder, avatar: STYLE.avatar,
+  // device + product-UI kit
+  device: WF.device, appBar: WF.appBar, tabBar: WF.tabBar, icon: WF.icon, iconButton: WF.iconButton,
+  listRow: WF.listRow, toggle: WF.toggle, segmented: WF.segmented, slider: WF.slider,
+  searchField: WF.searchField, roundRect: WF.roundRect,
+};
+// Layout composites take `items` (child specs) rather than scalar props, so they expand differently.
+const LAYOUTS = { stack: STYLE.stack, row: STYLE.row };
+
+function expandElements(list) {
+  const out = [];
+  for (const e of (list || [])) {
+    if (!e || typeof e !== 'object' || Array.isArray(e)) { if (e) out.push(e); continue; }
+    if (LAYOUTS[e.type]) {
+      // each item is itself a spec (or array of specs) → expand first, then let stack/row measure it
+      const items = (e.items || []).map((it) => expandElements(Array.isArray(it) ? it : [it]));
+      out.push(...expandElements(LAYOUTS[e.type](Object.assign({}, e, { items }))));
+    } else if (COMPOSITES[e.type]) {
+      out.push(...expandElements(COMPOSITES[e.type](e)));
+    } else {
+      out.push(e);
+    }
+  }
+  return out;
+}
+
+// ---------- frontmatter YAML ----------
+// Minimal, dependency-free emitters. Only what frontmatter needs: a safe scalar and a folded block
+// for long prose (a description is often a paragraph, and an unquoted one with `:` breaks the parse).
+function yamlScalar(v) {
+  const s = String(v);
+  return /^[\w][\w .\-/()]*$/.test(s) ? s : JSON.stringify(s);
+}
+function yamlFolded(key, text, width = 96) {
+  // `>-` folds newlines to spaces on read, so wrap freely; indent 2 marks the block.
+  const words = String(text).replace(/\s+/g, ' ').trim().split(' ');
+  const lines = [];
+  let cur = '';
+  for (const w of words) {
+    if (cur && (cur + ' ' + w).length > width) { lines.push(cur); cur = w; } else cur = cur ? cur + ' ' + w : w;
+  }
+  if (cur) lines.push(cur);
+  return [`${key}: >-`, ...lines.map((l) => '  ' + l)];
+}
 
 // ---------- deterministic PRNG (stable seeds => clean git diffs) ----------
 function mulberry32(seed) {
@@ -71,28 +139,52 @@ function isWideGlyph(code) {
 function glyphW(ch, fontSize) { return fontSize * (isWideGlyph(ch.codePointAt(0)) ? 1.05 : 0.58); }
 function measureText(s, fontSize) { let w = 0; for (const ch of String(s)) w += glyphW(ch, fontSize); return w; }
 
-// When a fixedWidth is given the text element is treated as WRAPPING (autoResize off downstream),
-// so height must reflect word-wrapped line count — otherwise long captions render as one wide line
-// and overlap their neighbours. Honors explicit \n and greedily wraps each logical line to width.
-function sizeText(text, fontSize, fixedWidth) {
-  const rawLines = String(text).split('\n');
-  if (fixedWidth != null) {
-    let totalLines = 0;
-    for (const ln of rawLines) {
-      const words = ln.split(/\s+/).filter(Boolean);
-      if (!words.length) { totalLines += 1; continue; }
-      let cur = '', lc = 1;
-      for (const w of words) {
-        if (!cur) { cur = w; continue; }
-        if (measureText(cur + ' ' + w, fontSize) > fixedWidth) { lc++; cur = w; }
-        else cur += ' ' + w;
+// Greedy word-wrap to a pixel width. Honors existing \n and HARD-breaks any single word wider than
+// the box (e.g. a long URL). Returns the text WITH newlines baked in — mirrors wrapToWidth() in
+// scripts/lib/style.js. Baking is what actually fixes over-wide text: a width-set text element with no
+// hard newlines is re-flowed by the renderer into ONE line wider than its box (captions then overlap
+// their neighbours). Baking the breaks makes every wrapped label render at the intended measure.
+// A logical line's LEADING INDENT is preserved and re-applied to every line it wraps into — that is
+// what keeps a hanging indent (bullets(), indented notes) intact through the bake. Without it the
+// wrap would collapse the author's indentation and continuation lines would snap to the left margin.
+function wrapText(text, fontSize, width) {
+  const out = [];
+  for (const logical of String(text).split('\n')) {
+    const indent = (logical.match(/^[ \t]*/) || [''])[0];
+    const avail = Math.max(1, width - measureText(indent, fontSize));
+    const push = (s) => out.push(indent + s);
+    const words = logical.slice(indent.length).split(/\s+/).filter(Boolean);
+    if (!words.length) { out.push(''); continue; }
+    let cur = '';
+    for (let word of words) {
+      while (measureText(word, fontSize) > avail) {
+        let acc = '';
+        for (const ch of word) { if (acc && measureText(acc + ch, fontSize) > avail) break; acc += ch; }
+        if (cur) { push(cur); cur = ''; }
+        push(acc); word = word.slice(acc.length); if (!word) break;
       }
-      totalLines += lc;
+      if (!word) continue;
+      const cand = cur ? cur + ' ' + word : word;
+      if (cur && measureText(cand, fontSize) > avail) { push(cur); cur = word; }
+      else cur = cand;
     }
-    return { width: fixedWidth, height: Math.max(Math.round(fontSize * 1.25), Math.round(totalLines * fontSize * 1.25)) };
+    if (cur) push(cur);
+  }
+  return out.join('\n');
+}
+
+// When a fixedWidth is given the text WRAPS to it (autoResize off) and the wrapped text is baked with
+// newlines, so it renders at the intended measure and its height reflects the real line count.
+// Returns { width, height, text } — `text` carries the baked newlines when a width was given.
+function sizeText(text, fontSize, fixedWidth) {
+  if (fixedWidth != null) {
+    const wrapped = wrapText(text, fontSize, fixedWidth);
+    const lc = wrapped.split('\n').length;
+    return { width: fixedWidth, height: Math.max(Math.round(fontSize * 1.25), Math.round(lc * fontSize * 1.25)), text: wrapped };
   }
+  const rawLines = String(text).split('\n');
   const maxW = rawLines.reduce((m, l) => Math.max(m, measureText(l, fontSize)), 0);
-  return { width: Math.max(10, Math.round(maxW)), height: Math.round(rawLines.length * fontSize * 1.25) };
+  return { width: Math.max(10, Math.round(maxW)), height: Math.round(rawLines.length * fontSize * 1.25), text: String(text) };
 }
 
 // ---------- element factory ----------
@@ -123,10 +215,159 @@ function baseEl(rng, type, x, y, w, h, overrides) {
   }, overrides || {});
 }
 
+// ---------- overlap auditor ----------
+// Overlapping opaque boxes are the #1 thing that makes a generated board look broken. After the scene
+// is built we scan for it and warn — so a hand-authored spec that miscomputed a coordinate gets caught
+// at generate time instead of in the reader's face. We flag SIBLING COLLISIONS: two comparable filled
+// boxes (rect / ellipse / diamond, or images) that partially overlap or fully stack. We do NOT flag
+// CONTAINMENT — a small box nested inside a much larger one (a button inside a window, a dot inside a
+// title bar, content inside a frame) is the normal parent/child relationship. Grouped composites (a
+// card's own label, a window's own chrome) and connectors / transparent shapes are skipped too.
+// Disable with `spec.audit === false`.
+function auditOverlaps(elements) {
+  const label = (e) => {
+    if (e.type === 'text') return JSON.stringify(String(e.text).split('\n')[0].slice(0, 24));
+    return `${e.type}@(${Math.round(e.x)},${Math.round(e.y)})`;
+  };
+  const grp = (e) => (e.groupIds && e.groupIds[0]) || null;
+  const isOpaqueBox = (e) => (
+    ((e.type === 'rectangle' || e.type === 'ellipse' || e.type === 'diamond') && e.backgroundColor && e.backgroundColor !== 'transparent') ||
+    e.type === 'image'
+  );
+  const area = (e) => Math.max(0, e.width) * Math.max(0, e.height);
+  const overlap = (a, b) => {
+    const ix = Math.max(0, Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x));
+    const iy = Math.max(0, Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y));
+    return ix * iy;
+  };
+  const boxes = elements.filter(isOpaqueBox);
+  const hits = [];
+  for (let i = 0; i < boxes.length; i++) {
+    for (let j = i + 1; j < boxes.length; j++) {
+      const a = boxes[i], b = boxes[j];
+      if (grp(a) && grp(a) === grp(b)) continue;         // same composite ⇒ intentional
+      const ov = overlap(a, b); if (ov <= 0) continue;
+      const minA = Math.min(area(a), area(b)), maxA = Math.max(area(a), area(b));
+      const cover = ov / Math.max(1, minA);              // fraction of the SMALLER box that is covered
+      const sizeRatio = minA / Math.max(1, maxA);        // ~1 = comparable boxes, ~0 = tiny-in-huge
+      if (cover > 0.85 && sizeRatio < 0.5) continue;      // small box nested in a big container ⇒ intentional
+      if (cover > 0.12) hits.push({ a, b, frac: cover });  // sibling boxes covering >12% of the smaller ⇒ collision
+    }
+  }
+  if (hits.length) {
+    const sample = hits.slice(0, 5).map((h) => `  ${label(h.a)} ↔ ${label(h.b)} (${Math.round(h.frac * 100)}%)`).join('\n');
+    try {
+      console.warn(`[excalidraw] ${hits.length} overlap(s) detected — boards read cleaner when boxes don't stack.\n${sample}${hits.length > 5 ? '\n  …' : ''}\n  Fix: lay out with stack()/row() (flow layout) or move the boxes apart.`);
+    } catch (e) {}
+  }
+  return hits.length;
+}
+
+// A text element buried under a foreign opaque box. The box-vs-box audit above cannot see this: a
+// section title swallowed by a card is text-vs-box, and it ships looking like `overlaps: 0`.
+//
+// Z-ORDER is the discriminator, and it is what keeps this check honest. Excalidraw paints in array
+// order, so a box only BURIES text that was pushed BEFORE it. Text pushed after a box is drawn on top
+// — that's just a label on a shape (the `hello.spec.json` pattern), which is fine and must not warn.
+// Text inside its OWN composite (same group) never flags either.
+function auditTextCollisions(elements) {
+  const zOf = new Map();
+  elements.forEach((e, i) => zOf.set(e, i));
+  const isOpaqueBox = (e) => (
+    ((e.type === 'rectangle' || e.type === 'ellipse' || e.type === 'diamond') && e.backgroundColor && e.backgroundColor !== 'transparent') ||
+    e.type === 'image'
+  );
+  const grp = (e) => (e.groupIds && e.groupIds[0]) || null;
+  const texts = elements.filter((e) => e.type === 'text' && e.width > 0 && e.height > 0);
+  const boxes = elements.filter(isOpaqueBox);
+  const hits = [];
+  for (const t of texts) {
+    // Check EACH LINE, not the element as a whole: a 2-line title with its second line swallowed only
+    // scores ~18% element-wide and would slip through, yet that line is just as unreadable. A line is
+    // also only as wide as its glyphs — measuring the full `width` box would over-report centered text.
+    const lines = String(t.text).split('\n');
+    const lh = (t.fontSize || 20) * 1.25;
+    let worst = null;
+    for (let i = 0; i < lines.length; i++) {
+      const lw = measureText(lines[i], t.fontSize || 20);
+      if (lw <= 0) continue;
+      const align = t.textAlign || 'left';
+      const lx = align === 'center' ? t.x + (t.width - lw) / 2 : align === 'right' ? t.x + t.width - lw : t.x;
+      const ly = t.y + i * lh;
+      const lArea = Math.max(1, lw * lh);
+      for (const b of boxes) {
+        if (grp(t) && grp(t) === grp(b)) continue;        // its own composite's chrome
+        if (zOf.get(b) < zOf.get(t)) continue;            // box painted first ⇒ text sits ON it (a label)
+        const ix = Math.max(0, Math.min(lx + lw, b.x + b.width) - Math.max(lx, b.x));
+        const iy = Math.max(0, Math.min(ly + lh, b.y + b.height) - Math.max(ly, b.y));
+        const frac = (ix * iy) / lArea;
+        if (frac > 0.3 && (!worst || frac > worst.frac)) worst = { t, b, frac, line: lines[i] };
+      }
+      // Text-on-text. Two texts have no reason to share pixels — this is always a defect, and z-order
+      // can't save it (both are painted, so they just tangle). A wrapped title landing on the subtitle
+      // beneath it is the classic case, and neither the box audit nor the measure audit can see it.
+      for (const u of texts) {
+        if (u === t) continue;
+        if (grp(t) && grp(t) === grp(u)) continue;
+        if (zOf.get(u) < zOf.get(t)) continue;            // report the pair once, from the lower element
+        const ulines = String(u.text).split('\n');
+        const ulh = (u.fontSize || 20) * 1.25;
+        for (let k = 0; k < ulines.length; k++) {
+          const uw = measureText(ulines[k], u.fontSize || 20);
+          if (uw <= 0) continue;
+          const ua = u.textAlign || 'left';
+          const ux = ua === 'center' ? u.x + (u.width - uw) / 2 : ua === 'right' ? u.x + u.width - uw : u.x;
+          const uy = u.y + k * ulh;
+          const ix = Math.max(0, Math.min(lx + lw, ux + uw) - Math.max(lx, ux));
+          const iy = Math.max(0, Math.min(ly + lh, uy + ulh) - Math.max(ly, uy));
+          const frac = (ix * iy) / lArea;
+          if (frac > 0.3 && (!worst || frac > worst.frac)) worst = { t, b: u, frac, line: lines[i], vsText: true };
+        }
+      }
+    }
+    if (worst) hits.push(worst);
+  }
+  if (hits.length) {
+    const sample = hits.slice(0, 5).map((h) => {
+      const onto = h.vsText ? `text ${JSON.stringify(String(h.b.text).split('\n')[0].slice(0, 22))}` : `${h.b.type}@(${Math.round(h.b.x)},${Math.round(h.b.y)})`;
+      return `  ${JSON.stringify(String(h.line).slice(0, 30))} collides with ${onto} (${Math.round(h.frac * 100)}%)`;
+    }).join('\n');
+    try {
+      console.warn(`[excalidraw] ${hits.length} text element(s) collide — the label is unreadable.\n${sample}${hits.length > 5 ? '\n  …' : ''}\n  Fix: flow the region with stack()/row(); a wrapped title landing on the text below is the usual cause.`);
+    } catch (e) {}
+  }
+  return hits.length;
+}
+
+// Body copy that runs past the reading measure. This is the skill's headline rule and it was, until
+// now, unenforced — a board could ship 1400px lines reporting a clean audit. Display type (>= 28px)
+// is scanned, not read, so it is exempt; a 10% tolerance keeps borderline headings quiet.
+function auditMeasure(elements, limit) {
+  const cap = (limit || STYLE.READ_W) * 1.1;
+  const hits = [];
+  for (const e of elements) {
+    if (e.type !== 'text' || !e.text || e.fontSize >= 28) continue;
+    let longest = 0;
+    for (const line of String(e.text).split('\n')) longest = Math.max(longest, STYLE.measureText(line, e.fontSize));
+    if (longest > cap) hits.push({ e, longest });
+  }
+  if (hits.length) {
+    hits.sort((a, b) => b.longest - a.longest);
+    const sample = hits.slice(0, 5).map((h) => `  ${Math.round(h.longest)}px  ${JSON.stringify(String(h.e.text).split('\n')[0].slice(0, 36))}`).join('\n');
+    try {
+      console.warn(`[excalidraw] ${hits.length} text block(s) exceed the reading measure (${Math.round(cap)}px) — long lines are the #1 readability killer.\n${sample}${hits.length > 5 ? '\n  …' : ''}\n  Fix: use prose()/bullets()/callout() (they cap at READ_W), or set an explicit \`width\` on the text element.`);
+    } catch (e) {}
+  }
+  return hits.length;
+}
+
 // ---------- main build ----------
 function buildExcalidraw(spec) {
   const outPath = spec.out;
   if (!outPath) throw new Error('spec.out (output .excalidraw.md path) is required');
+  // Expand composite types (charts, house-style widgets, stack/row) down to primitives first, so the
+  // rest of the build only ever sees text/image/rectangle/line/… — one code path for JSON and JS.
+  spec = Object.assign({}, spec, { elements: expandElements(spec.elements) });
   const boardDir = path.dirname(path.resolve(outPath));
   const vaultRoot = spec.vaultRoot || findVaultRoot(boardDir) || boardDir;
   const attachDir = spec.attachDir || 'Attachments';
@@ -201,12 +442,12 @@ function buildExcalidraw(spec) {
     const type = e.type;
     if (type === 'text') {
       const fontSize = e.fontSize || 20;
-      const { width, height } = sizeText(e.text, fontSize, e.width);
+      const { width, height, text: baked } = sizeText(e.text, fontSize, e.width);
       const el = baseEl(rng, 'text', e.x || 0, e.y || 0, width, height, {
         strokeColor: e.color || '#1e1e1e',
-        text: String(e.text),
-        rawText: String(e.text),
-        originalText: String(e.text),
+        text: baked,
+        rawText: baked,
+        originalText: baked,
         fontSize,
         fontFamily: e.fontFamily || 5,
         textAlign: e.align || 'left',
@@ -238,7 +479,7 @@ function buildExcalidraw(spec) {
         strokeColor: e.strokeColor || '#1e1e1e',
         backgroundColor: e.backgroundColor || 'transparent',
         fillStyle: e.fillStyle || 'solid',
-        strokeWidth: e.strokeWidth || 2,
+        strokeWidth: e.strokeWidth != null ? e.strokeWidth : 2,
         strokeStyle: e.strokeStyle || 'solid',
         roundness: e.roundness ? { type: 3 } : null,
       });
@@ -249,10 +490,16 @@ function buildExcalidraw(spec) {
       const minX = Math.min(...xs); const minY = Math.min(...ys);
       const norm = pts.map((p) => [p[0] - minX, p[1] - minY]);
       const w = Math.max(...xs) - minX; const h = Math.max(...ys) - minY;
+      // A `line` may be a FILLED polygon: pass backgroundColor + fillStyle and close the path
+      // (first point repeated as last) and Excalidraw fills it — this is how funnel trapezoids and
+      // custom regions are drawn. Arrows never fill. roundness softens polygon corners when asked.
       const el = baseEl(rng, type, (e.x || 0) + minX, (e.y || 0) + minY, w, h, {
         strokeColor: e.strokeColor || '#1e1e1e',
-        strokeWidth: e.strokeWidth || 2,
+        backgroundColor: type === 'line' ? (e.backgroundColor || 'transparent') : 'transparent',
+        fillStyle: e.fillStyle || 'solid',
+        strokeWidth: e.strokeWidth != null ? e.strokeWidth : 2,
         strokeStyle: e.strokeStyle || 'solid',
+        roundness: e.roundness ? { type: 2 } : null,
         points: norm,
         lastCommittedPoint: null,
         startBinding: null,
@@ -280,6 +527,15 @@ function buildExcalidraw(spec) {
   const keys = generateNKeysBetween(null, null, elements.length);
   elements.forEach((el, i) => { el.index = keys[i]; });
 
+  // Catch the three ways a board ships broken (opt out with spec.audit === false):
+  //   overlaps       — two opaque boxes stacked
+  //   buriedText     — a label swallowed by a foreign box (box-vs-box audit is blind to this)
+  //   longLines      — body copy past the reading measure
+  const doAudit = spec.audit !== false;
+  const overlaps = doAudit ? auditOverlaps(elements) : 0;
+  const buriedText = doAudit ? auditTextCollisions(elements) : 0;
+  const longLines = doAudit ? auditMeasure(elements, spec.measure) : 0;
+
   const scene = {
     type: 'excalidraw',
     version: 2,
@@ -291,7 +547,16 @@ function buildExcalidraw(spec) {
 
   // ---------- assemble markdown ----------
   const L = [];
-  L.push('---', '', 'excalidraw-plugin: parsed', 'tags: [excalidraw]', '', '---');
+  // Frontmatter. dreamcontext REQUIRES `name` + `description` to index/recall a board — memory reads
+  // frontmatter + `## Text Elements`, never the scene JSON — so emit them when given rather than
+  // making every generator hand-patch the file afterwards.
+  L.push('---', '');
+  if (spec.name) L.push(`name: ${yamlScalar(spec.name)}`);
+  if (spec.description) L.push(...yamlFolded('description', spec.description));
+  const tags = spec.tags && spec.tags.length ? spec.tags : ['excalidraw'];
+  L.push(`tags: [${tags.join(', ')}]`);
+  for (const [k, v] of Object.entries(spec.frontmatter || {})) L.push(`${k}: ${yamlScalar(v)}`);
+  L.push('excalidraw-plugin: parsed', '', '---');
   L.push("==⚠  Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠== You can decompress Drawing data with the command palette: 'Decompress current Excalidraw file'. For more info check in plugin settings under 'Saving'");
   L.push('', '', '# Excalidraw Data', '');
   L.push('## Text Elements');
@@ -309,7 +574,7 @@ function buildExcalidraw(spec) {
   fs.mkdirSync(boardDir, { recursive: true });
   fs.writeFileSync(outPath, md, 'utf8');
 
-  return { outPath, elements: elements.length, images: embedded.size, texts: textEntries.length, vaultRoot };
+  return { outPath, elements: elements.length, images: embedded.size, texts: textEntries.length, overlaps, buriedText, longLines, vaultRoot };
 }
 
 // ---------- layout helpers (JS API) ----------
@@ -392,5 +657,5 @@ if (require.main === module) {
   const spec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
   if (out) spec.out = out;
   const res = buildExcalidraw(spec);
-  console.log(`OK  ${res.outPath}\n    elements=${res.elements} images=${res.images} texts=${res.texts}\n    vaultRoot=${res.vaultRoot}`);
+  console.log(`OK  ${res.outPath}\n    elements=${res.elements} images=${res.images} texts=${res.texts} overlaps=${res.overlaps} buriedText=${res.buriedText} longLines=${res.longLines}\n    vaultRoot=${res.vaultRoot}`);
 }