slidemind 0.3.20 → 0.4.0

package/src/builders/legacy-reference-uses.mjs

@@ -0,0 +1,179 @@
+// `--concept` / `--style` as adapters onto the image-intent contract.
+//
+// Both flags predate the contract: they read a file inline and shipped it to
+// the concept model as a transient `{role, image}` reference that nothing
+// recorded. The image was gone the moment the request came back, so a resumed
+// session, a re-run or the .pptx itself had no idea it ever existed.
+//
+// They keep working, and they now mean something durable (migration plan step
+// 5):
+//
+//   --concept file@2,3   import the file, then a reconstruct/slide use on 2 and 3
+//   --style   file@2,3   import the file, then a reference use on 2 and 3
+//   (no @)               the CURRENT planned set — never an evergreen
+//                        "all future slides" record
+//
+// Four rules the implementation exists to keep:
+//
+//   * **Import first, plan second.** The bytes are registered before any use
+//     names them, so a use can never point at something the deck does not have.
+//   * **Idempotent.** The registry deduplicates by digest and this deduplicates
+//     equivalent uses, so the same flag with the same bytes and the same scope
+//     twice is a no-op — which is what leaves an approved plan approved.
+//   * **A conflict is refused, not guessed.** If the slide already carries a
+//     canonical use of those bytes with a different obligation, the flag and
+//     the plan disagree about what the picture is FOR. Picking one silently is
+//     how an `original` becomes a mood board. `image_intent_conflict` names
+//     both choices and the agent resolves it in the plan.
+//   * **No approval is bypassed.** This writes a PENDING plan revision. The
+//     existing plan hash gate then re-arms by itself (the storyboard record is
+//     part of the story hash), so the user re-signs the plan that now carries
+//     the obligation. Nothing here touches plan-review.json.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { importImageAsset } from "../lib/image-assets.mjs";
+import { describeUse } from "../lib/image-intent.mjs";
+import { replaceStoryboardSegment, splitPlanMarkdownIntoSegments } from "./storyboard-markdown.mjs";
+
+/** `--concept` → a whole-slide blueprint; `--style` → guidance only. */
+const ROLE_USES = {
+  concept: {
+    fidelity: "reconstruct",
+    reconstructionScope: "slide",
+    suffix: "rc",
+    instruction: (name) => `Rebuild this slide from ${name} (supplied with --concept).`,
+  },
+  style: {
+    fidelity: "reference",
+    suffix: "rf",
+    instruction: (name) => `Use ${name} as a visual reference for this slide (supplied with --style).`,
+  },
+};
+
+function conflict(message, extra) {
+  return {
+    code: "image_intent_conflict",
+    message,
+    action: "Resolve the competing record in the plan before generating mockups.",
+    ...extra,
+  };
+}
+
+/** The slide numbers the plan currently names — the scope of a flag with no `@`. */
+export function plannedSlidesInPlan(planMarkdown) {
+  return splitPlanMarkdownIntoSegments(planMarkdown)
+    .filter((segment) => segment.type === "storyboard" && segment.data?.slide)
+    .map((segment) => segment.data.slide);
+}
+
+/**
+ * Turn legacy reference flags into imported assets plus plan uses.
+ *
+ * Pure with respect to the plan: it returns the next markdown, it does not
+ * write it. The caller decides what to do with a changed plan (`concepts` lets
+ * the existing sign-off gate refuse the run).
+ *
+ * @param {string} deckDir
+ * @param {Array<{role: "concept"|"style", file: string, slides?: number[]}>} flags
+ * @param {{planMarkdown: string}} ctx
+ * @returns {Promise<{planMarkdown: string, changed: boolean,
+ *                    imported: Array, added: Array, issues: Array}>}
+ */
+export async function applyLegacyReferenceFlags(deckDir, flags, { planMarkdown }) {
+  const out = { planMarkdown, changed: false, imported: [], added: [], issues: [] };
+  if (!flags?.length) return out;
+
+  const planned = plannedSlidesInPlan(planMarkdown);
+  for (const flag of flags) {
+    const spec = ROLE_USES[flag.role];
+    if (!spec) continue;
+
+    // Import BEFORE planning. Same bytes as an earlier import reuse the entry
+    // they already have, which is what makes the whole adapter idempotent.
+    const { asset, reused } = await importImageAsset(deckDir, flag.file, {
+      displayName: path.basename(flag.file),
+      provenance: { kind: "local" },
+    });
+    out.imported.push({ file: flag.file, assetId: asset.assetId, reused });
+
+    const targets = flag.slides?.length ? flag.slides : planned;
+    for (const slide of targets) {
+      const board = splitPlanMarkdownIntoSegments(out.planMarkdown).find(
+        (segment) => segment.type === "storyboard" && segment.data?.slide === slide,
+      );
+      if (!board) {
+        out.issues.push(
+          conflict(
+            `--${flag.role} names slide ${slide}, which the plan has no storyboard for.`,
+            { slide, assetId: asset.assetId },
+          ),
+        );
+        continue;
+      }
+      const existing = board.data.assetUses ?? [];
+
+      // Equivalent to something already recorded → nothing to do.
+      const same = existing.find(
+        (use) =>
+          use.assetId === asset.assetId &&
+          use.fidelity === spec.fidelity &&
+          use.reconstructionScope === spec.reconstructionScope,
+      );
+      if (same) continue;
+
+      // Same bytes, different obligation: the flag and the plan disagree about
+      // what this picture is for.
+      const other = existing.find((use) => use.assetId === asset.assetId);
+      if (other) {
+        out.issues.push(
+          conflict(
+            `slide ${slide} already uses ${asset.displayName} as ${describeUse(other)}, ` +
+              `but --${flag.role} asks for ${describeUse(spec)}.`,
+            { slide, assetId: asset.assetId, useId: other.useId },
+          ),
+        );
+        continue;
+      }
+
+      // A slide takes one whole-slide blueprint. The contract's own parser
+      // would refuse a second one; catching it here names the other source.
+      if (spec.reconstructionScope === "slide") {
+        const blueprint = existing.find(
+          (use) => use.fidelity === "reconstruct" && use.reconstructionScope === "slide",
+        );
+        if (blueprint) {
+          out.issues.push(
+            conflict(
+              `slide ${slide} already rebuilds from another source (${blueprint.useId}); ` +
+                `--concept ${path.basename(flag.file)} would be a second whole-slide blueprint.`,
+              { slide, assetId: asset.assetId, useId: blueprint.useId },
+            ),
+          );
+          continue;
+        }
+      }
+
+      const use = {
+        useId: `${asset.assetId}_s${slide}_${spec.suffix}`,
+        assetId: asset.assetId,
+        fidelity: spec.fidelity,
+        instruction: spec.instruction(asset.displayName),
+        ...(spec.reconstructionScope ? { reconstructionScope: spec.reconstructionScope } : {}),
+      };
+      out.planMarkdown = replaceStoryboardSegment(out.planMarkdown, board, {
+        ...board.data,
+        assetUses: [...existing, use],
+      });
+      out.changed = true;
+      out.added.push({ slide, useId: use.useId, fidelity: use.fidelity, assetId: asset.assetId });
+    }
+  }
+  return out;
+}
+
+/** Persist a pending plan revision. The sign-off gate re-arms by itself. */
+export function writePlanMarkdown(deckDir, markdown) {
+  fs.writeFileSync(path.join(deckDir, "plan.md"), markdown);
+}

package/src/builders/line-fit.mjs

@@ -0,0 +1,224 @@
+// Trace utilities for the line fitter (line-native.mjs) and the line intake
+// (concept-lines.mjs): the strokes an element draws, cleaned of what runs
+// inside its own nodes, and the ordered distance between two paths. WHICH
+// native object draws a stroke is line-native's business.
+//
+// Shared by both clients; mirrored by scripts/sync-transcription-runtime.mjs —
+// no Node or CLI imports here.
+
+import { repairCommands } from "./concept-geometry.mjs";
+
+
+const dist = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+const rectCenter = (r) => ({ x: r.x + r.w / 2, y: r.y + r.h / 2 });
+
+/**
+ * Which side of its node a line end sits on: the nearest edge of a box, or
+ * one of eight 45° sectors of a round node. Two ends on the same side are the
+ * same attachment for the line's shape; a different side is a different line.
+ */
+export function sideOf(p, rect, round = false) {
+  const c = rectCenter(rect);
+  const dx = (p.x - c.x) / Math.max(1, rect.w / 2), dy = (p.y - c.y) / Math.max(1, rect.h / 2);
+  if (round) {
+    const k = Math.round(Math.atan2(dy, dx) / (Math.PI / 4));
+    return ["right", "bottom-right", "bottom", "bottom-left", "left", "top-left", "top", "top-right"][((k % 8) + 8) % 8];
+  }
+  return Math.abs(dx) >= Math.abs(dy) ? (dx >= 0 ? "right" : "left") : dy >= 0 ? "bottom" : "top";
+}
+const inside = (p, r, e = 0.5) => p.x > r.x + e && p.x < r.x + r.w - e && p.y > r.y + e && p.y < r.y + r.h - e;
+const finite = (p) => Number.isFinite(p?.x) && Number.isFinite(p?.y);
+const r1 = (v) => Math.round(v * 10) / 10;
+
+/** A point end as written in JSX (`data-from="x,y"`) and read back. */
+export const pointRef = (p) => `${r1(p.x)},${r1(p.y)}`;
+export function parsePointRef(ref) {
+  const m = /^\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*$/.exec(String(ref ?? ""));
+  return m ? { x: Number(m[1]), y: Number(m[2]) } : null;
+}
+
+export function traceLength(points) {
+  let len = 0;
+  for (let i = 1; i < points.length; i++) len += dist(points[i], points[i - 1]);
+  return len;
+}
+
+// Ordered distance between two paths (px): both resampled to the same number
+// of points by arc length, then compared point for point, start to end. An
+// unordered nearest-point distance let a square around the corners pass for
+// a circle through them (14px against a 24px tolerance, x58 GTM 3); in order,
+// the corner cuts far from the arc and the shape difference counts.
+export function pathDistance(a, b, n = 32) {
+  return pathErrors(a, b, n).max;
+}
+
+/** Both measures of the ordered comparison: the worst point and the RMS. */
+export function pathErrors(a, b, n = 32) {
+  // Linear interpolation by arc length along the polyline itself.
+  const resample = (pts) => {
+    const d = pts;
+    const cum = [0];
+    for (let i = 1; i < d.length; i++) cum.push(cum[i - 1] + dist(d[i], d[i - 1]));
+    const total = cum.at(-1) || 1;
+    const out = [];
+    let j = 0;
+    for (let k = 0; k < n; k++) {
+      const t = (total * k) / (n - 1);
+      while (j < cum.length - 2 && cum[j + 1] < t) j++;
+      const seg = cum[j + 1] - cum[j] || 1;
+      const f = Math.min(1, Math.max(0, (t - cum[j]) / seg));
+      out.push({ x: d[j].x + (d[j + 1]?.x - d[j].x || 0) * f, y: d[j].y + (d[j + 1]?.y - d[j].y || 0) * f });
+    }
+    return out;
+  };
+  if (a.length < 2 || b.length < 2) return { max: Infinity, rms: Infinity };
+  const A = resample(a), B = resample(b);
+  // The worst point decides: a corner cut short of a curve is ONE place, and
+  // an average hides it. The RMS is the smooth measure a search descends on.
+  const d = A.map((p, i) => dist(p, B[i]));
+  return { max: Math.max(...d), rms: Math.sqrt(d.reduce((s, v) => s + v * v, 0) / d.length) };
+}
+
+export const segmentHitsRect = (p, q, r) => {
+  // Axis-aligned or diagonal segment vs rect: sample along the segment.
+  const n = Math.max(2, Math.ceil(dist(p, q) / 4));
+  for (let i = 0; i <= n; i++) {
+    const t = i / n;
+    if (inside({ x: p.x + (q.x - p.x) * t, y: p.y + (q.y - p.y) * t }, r)) return true;
+  }
+  return false;
+};
+export const contains = (outer, inner) => inner.x >= outer.x - 0.5 && inner.y >= outer.y - 0.5 && inner.x + inner.w <= outer.x + outer.w + 0.5 && inner.y + inner.h <= outer.y + outer.h + 0.5;
+
+// ---- Traces.
+
+// Inside the node's own outline: its ellipse when it is round (a disc's
+// bounding-box corners are empty slide).
+const insideNode = (p, r, round) => {
+  if (!round) return inside(p, r);
+  const rx = r.w / 2 - 0.5, ry = r.h / 2 - 0.5;
+  if (rx <= 0 || ry <= 0) return false;
+  const dx = (p.x - r.x - r.w / 2) / rx, dy = (p.y - r.y - r.h / 2) / ry;
+  return dx * dx + dy * dy < 1;
+};
+
+// Where a walk from `a` (inside) toward `b` (outside) leaves the node.
+function exitPoint(a, b, r, round) {
+  let lo = 0, hi = 1;
+  for (let i = 0; i < 24; i++) {
+    const mid = (lo + hi) / 2;
+    if (insideNode({ x: a.x + (b.x - a.x) * mid, y: a.y + (b.y - a.y) * mid }, r, round)) lo = mid;
+    else hi = mid;
+  }
+  return { x: a.x + (b.x - a.x) * hi, y: a.y + (b.y - a.y) * hi };
+}
+
+function clipStart(pts, r, round) {
+  let k = -1;
+  for (let i = 0; i < pts.length - 1; i++) if (insideNode(pts[i], r, round)) k = i;
+  if (k < 0) return pts;
+  return [exitPoint(pts[k], pts[k + 1], r, round), ...pts.slice(k + 1)];
+}
+
+/**
+ * The trace with everything that runs INSIDE its own source or target cut
+ * away: a line is drawn between the nodes, not through them. A reader that put
+ * a fan's bus inside the source disc (2d9503ca slide 2) otherwise pulled two
+ * edges up through the disc and its label.
+ */
+export function sanitizeTrace(points, fromRect, toRect, { fromRound = false, toRound = false } = {}) {
+  const raw = (points ?? []).filter(finite).map((p) => ({ x: p.x, y: p.y }));
+  if (raw.length < 2) return raw;
+  let pts = raw;
+  if (fromRect?.w > 0 && fromRect?.h > 0) pts = clipStart(pts, fromRect, fromRound);
+  if (toRect?.w > 0 && toRect?.h > 0) pts = clipStart([...pts].reverse(), toRect, toRound).reverse();
+  // Nothing left between the nodes (they overlap, or the reader traced only
+  // inside them): the reader's own trace is the better evidence.
+  return traceLength(pts) >= 8 ? pts : raw;
+}
+
+const bezier = (p0, c1, c2, p1, t) => {
+  const u = 1 - t;
+  return { x: u * u * u * p0.x + 3 * u * u * t * c1.x + 3 * u * t * t * c2.x + t * t * t * p1.x, y: u * u * u * p0.y + 3 * u * u * t * c1.y + 3 * u * t * t * c2.y + t * t * t * p1.y };
+};
+
+/**
+ * The open strokes a `kind:path` element draws, each as an ordered point list
+ * (curves sampled), or [] when it is a closed or filled shape — which stays a
+ * drawn shape. Several subpaths are several lines.
+ */
+export function strokeTraces(e) {
+  if (e?.kind !== "path" || (e.text != null && String(e.text).trim() !== "")) return [];
+  const g = e.geometry;
+  const filled = e.fill && e.fill !== "none";
+  // Only a closed outline holds paint (the transcriber's own rule): an open
+  // spline, arc or path is a stroke whatever fill the reader named.
+  if (g?.type === "spline") return g.closed || !(g.points?.length >= 2) ? [] : [g.points.filter(finite)];
+  if (g?.type === "arc") {
+    // A full ring is a closed outline; a filled arc with a hole is a band.
+    if (Math.abs(g.sweep) >= 360 || (filled && (g.innerRatio ?? 0) > 0 && g.innerRatio < 1)) return [];
+    const at = (a) => ({ x: g.cx + g.rx * Math.cos((a * Math.PI) / 180), y: g.cy + g.ry * Math.sin((a * Math.PI) / 180) });
+    const n = Math.max(4, Math.ceil(Math.abs(g.sweep) / 10));
+    return [Array.from({ length: n + 1 }, (_, i) => at(g.start + (g.sweep * i) / n))];
+  }
+  if (g?.type === "path") {
+    // The commands as the transcriber draws them (the reader writes `M` as a
+    // whole segment, start in x1/y1).
+    const cmds = repairCommands(g.commands ?? [], e) ?? [];
+    if (cmds.some((c) => c?.op === "Z")) return [];
+    const out = [];
+    let cur = null, pen = null;
+    for (const c of cmds) {
+      const p = { x: c.x, y: c.y };
+      if (!finite(p)) continue;
+      if (c.op === "M") { if (cur?.length >= 2) out.push(cur); cur = [p]; }
+      else if (!cur) cur = [p];
+      else if (c.op === "C" || c.op === "Q") {
+        const c1 = { x: c.x1, y: c.y1 }, c2 = c.op === "C" ? { x: c.x2, y: c.y2 } : c1;
+        if (finite(c1) && finite(c2)) for (let k = 1; k <= 8; k++) cur.push(bezier(pen, c1, c2, p, k / 8));
+        else cur.push(p);
+      } else cur.push(p);
+      pen = p;
+    }
+    if (cur?.length >= 2) out.push(cur);
+    return out;
+  }
+  if (g || (filled && e.points?.length >= 3) || !(e.points?.length >= 2)) return [];
+  return [e.points.filter(finite)];
+}
+
+/**
+ * A few plain strokes the size of an icon with no arrowhead — a tick, a cross,
+ * a chevron — are a glyph mark (the intake's role `mark`), not a line between
+ * things: never glued, written as a chain of native pieces with round caps.
+ */
+export function isGlyphStroke(e, traces = strokeTraces(e)) {
+  if (!traces.length) return false;
+  // A declared cap, or an end the reader says touches an element, makes it a
+  // line whatever its size.
+  const heads = e.ends && ["start", "end"].some((k) => e.ends[k] && e.ends[k] !== "none");
+  const declared = e.strokeEnds && ["start", "end"].some((k) => {
+    const s = e.strokeEnds[k];
+    return s && ((s.cap && s.cap !== "none") || (s.element && s.contact === "touches"));
+  });
+  if (heads || declared) return false;
+  const pts = traces.flat();
+  const w = Math.max(...pts.map((p) => p.x)) - Math.min(...pts.map((p) => p.x));
+  const h = Math.max(...pts.map((p) => p.y)) - Math.min(...pts.map((p) => p.y));
+  return Math.max(w, h) <= 32;
+}
+
+/** The point halfway along a trace, by length. */
+export function traceMidpoint(pts) {
+  const total = traceLength(pts);
+  let acc = 0;
+  for (let i = 1; i < pts.length; i++) {
+    const seg = dist(pts[i], pts[i - 1]);
+    if (acc + seg >= total / 2) {
+      const f = seg ? (total / 2 - acc) / seg : 0;
+      return { x: pts[i - 1].x + (pts[i].x - pts[i - 1].x) * f, y: pts[i - 1].y + (pts[i].y - pts[i - 1].y) * f };
+    }
+    acc += seg;
+  }
+  return pts[0];
+}