slidemind 0.3.19 → 0.4.0

package/src/builders/asset-fetch.mjs

@@ -0,0 +1,203 @@
+// The spec's assets, fetched the same way by both clients: the CLI's
+// `transcribe` and the add-in's slide preparation run THIS ladder, and each
+// hands in only its own transport (search, download). Mirrored into the add-in
+// by scripts/sync-transcription-runtime.mjs — no Node or CLI imports here.
+import { pickIconResult, iconNameHits, iconSearchQueries, iconMotifSize } from "./transcribe.mjs";
+
+// Transport failures are not evidence that a motif is absent. Retry the same
+// operation, sharing a cooldown across the workers in one fetch batch.
+export function engineFailure(error) {
+  const status = Number(error?.status ?? error?.statusCode);
+  const message = String(error?.message ?? error?.error ?? error);
+  const code = error?.code;
+  const limited = status === 429 || code === "rate_limited";
+  const transient = limited || error?.retryable === true || [408, 500, 502, 503, 504].includes(status) ||
+    /ECONNRESET|ETIMEDOUT|EAI_AGAIN|fetch failed|relay unreachable/i.test(message);
+  return { code: limited ? "rate_limited" : transient ? "transport_error" : "engine_error", retryable: transient, error: message };
+}
+
+export function retryAfterMs(value, now = Date.now()) {
+  if (value == null || value === "") return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  const date = Date.parse(String(value));
+  return Number.isFinite(date) ? Math.max(0, date - now) : null;
+}
+
+export function createEngineRetry({ sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), now = Date.now, attempts = 3, maxDelayMs = 120_000, onRetry = () => {} } = {}) {
+  let resumeAt = 0;
+  return async function retry(operation) {
+    for (let attempt = 1; ; attempt++) {
+      const wait = resumeAt - now();
+      if (wait > 0) await sleep(wait);
+      try {
+        const result = await operation();
+        if (result?.ok === false) {
+          throw Object.assign(new Error(result.error ?? "engine refused request"), result);
+        }
+        return result;
+      } catch (error) {
+        const failure = engineFailure(error);
+        const delay = error?.retryAfterMs ?? retryAfterMs(error?.headers?.["retry-after"], now()) ?? 2000 * 2 ** (attempt - 1);
+        // A rate limit is the engine asking for patience, not an outage: give
+        // it two more turns (x52: 26 icons reported missing were 429s).
+        const allowed = failure.code === "rate_limited" ? attempts + 2 : attempts;
+        if (!failure.retryable || attempt >= allowed || delay > maxDelayMs) {
+          throw Object.assign(new Error(failure.error), failure, { attempts: attempt, ...(failure.retryable ? { retryAfterMs: delay } : {}) });
+        }
+        resumeAt = Math.max(resumeAt, now() + delay);
+        onRetry({ ...failure, attempt, delay });
+      }
+    }
+  };
+}
+
+const engineText = (e) => `${e?.label ?? e?.name ?? ""} ${e?.description ?? ""} ${e?.kind ?? ""}`;
+const PHOTO = /photo|photograph|illustration/i;
+const ICON = /icon|pictogram|vector/i;
+
+/**
+ * The image engine for one row, chosen from the catalog's descriptive evidence
+ * (name, description), never from a provider- or brand-specific id. `engines`
+ * are the caller's searchable image engines, in catalog order; the order breaks
+ * ties, so a design with one image engine always gets that one.
+ */
+export function selectAssetEngine(engines, kind) {
+  const list = Array.isArray(engines) ? engines : [];
+  if (kind !== "image") return list.find((e) => ICON.test(engineText(e))) ?? list[0] ?? null;
+  return list.find((e) => PHOTO.test(engineText(e))) ?? list.find((e) => !ICON.test(engineText(e))) ?? list[0] ?? null;
+}
+
+/** A glyph is recoloured to the paint the transcriber resolved; a photo never is. */
+export function assetRecolor(group, engine) {
+  if (group.kind === "icon") return group.colorHex ?? undefined;
+  return PHOTO.test(engineText(engine)) ? undefined : group.tintHex ?? undefined;
+}
+
+/**
+ * Fetch every row's asset: one search ladder + one download per distinct
+ * (kind, query, colour); rows sharing it share the result.
+ *
+ * - `search({ engine, query })` → `{ searchId, results: [{ selection, title|sourceUrl }], collage? }`.
+ *   `collage` is the numbered contact sheet of the results (data URI), when
+ *   the transport has one. Throw (or return `{ ok: false }`) on a failed request.
+ * - `pick({ group, query, results, collage })` (optional) → the 1-based
+ *   selection a vision reader chose from the collage, or null when nothing in
+ *   it shows the motif. File names are often cryptic, so with a picker the
+ *   collage decides; a name that fully spells the motif still skips the call.
+ *   A thrown pick is no verdict: that rung falls back to the file names.
+ * - `download({ engine, searchId, selection, recolor, group })` → the caller's
+ *   handle for the bytes (truthy), or throw.
+ *
+ * Returns one entry per group: `{ group, engine, result, failure }` — exactly one of
+ * `result` / `failure` is set. A miss never removes anything; the caller keeps
+ * the unresolved reference and reports it.
+ */
+export async function fetchAssetGroups({ rows, engines, search, download, pick = null, retry = createEngineRetry(), onError = () => {}, concurrency = 6 }) {
+  const groups = new Map();
+  for (const r of rows ?? []) {
+    const key = `${r.kind ?? "icon"}|${String(r.query).toLowerCase()}|${r.colorHex ?? "source"}`;
+    if (!groups.has(key)) groups.set(key, { query: r.query, keywords: r.keywords ?? [], kind: r.kind ?? "icon", color: r.color, colorHex: r.colorHex, tintHex: r.tintHex ?? null, rows: [] });
+    groups.get(key).rows.push(r);
+  }
+  const work = [...groups.values()];
+  const out = [];
+  // undefined = no verdict (no picker, no collage, picker failed).
+  const visualPick = async (g, query, res, results) => {
+    if (!pick || !res.collage) return undefined;
+    try {
+      const selection = await pick({ group: g, query, results, collage: res.collage });
+      return Number.isInteger(selection) && results.some((r, i) => (r.selection ?? i + 1) === selection) ? selection : null;
+    } catch (err) {
+      onError(query, err);
+      return undefined;
+    }
+  };
+  let cursor = 0;
+  const worker = async () => {
+    for (;;) {
+      const g = work[cursor++];
+      if (!g) return;
+      const engine = selectAssetEngine(engines, g.kind);
+      if (!engine) { out.push({ group: g, engine: null, result: null, failure: { code: "no_engine", retryable: false, error: "no compatible image engine" } }); continue; }
+      let result = null;
+      let failure = { code: "no_semantic_match", retryable: false, error: "No engine result matched this motif; source another motif for what the element stands for, never an unrelated one." };
+      // Strip style words without losing compound motifs. Transport retries
+      // repeat the identical request and are separate from query refinement.
+      const queries = g.kind === "icon" ? iconSearchQueries(g.query, g.keywords) : [g.query];
+      // The best candidate seen so far, across attempts: the engine's ranking
+      // is noise (nine results inside 0.002), so the file name decides, and a
+      // set where NO name carries a query word is nine unrelated glyphs — the
+      // next, shorter query gets a different nine. A first attempt that fully
+      // names the motif stops the ladder, so a well-named motif costs one search.
+      let best = null;
+      // Keep climbing while the best set only half-names the motif ("shield
+      // check" → a plain shield stopped the ladder at attempt 0; x54: ~9 of 12
+      // slides carried such substitutes). The best set across attempts wins.
+      const full = g.kind === "image" ? 1 : iconMotifSize(g.query);
+      for (let attempt = 0; attempt < queries.length && !result; attempt++) {
+        try {
+          const res = await retry(() => search({ engine, query: queries[attempt] }));
+          const results = Array.isArray(res?.results) ? res.results : [];
+          if (res?.searchId && results.length) {
+            const named = g.kind === "image" ? null : pickIconResult(g.query, results, g.keywords);
+            const hits = named ? iconNameHits(g.query, named, g.keywords) : 0;
+            // A name that spells the whole motif needs no second opinion.
+            const verdict = named && hits >= full ? undefined : await visualPick(g, queries[attempt], res, results);
+            if (verdict) best = { hits: full, searchId: res.searchId, selection: verdict };
+            else if (verdict === undefined) {
+              const byName = g.kind === "image" ? results[0] : named;
+              const h = g.kind === "image" ? 1 : hits;
+              if (byName && (!best || h > best.hits)) best = { hits: h, searchId: res.searchId, selection: byName.selection ?? 1 };
+            }
+            // null: the reader looked and nothing here shows the motif.
+          }
+          if (!best || (best.hits < full && attempt < queries.length - 1)) continue;
+          result = await retry(() => download({ engine, searchId: best.searchId, selection: best.selection, recolor: assetRecolor(g, engine), group: g }));
+          if (!result) throw Object.assign(new Error("engine download returned no local artifact"), { code: "invalid_download" });
+        } catch (err) {
+          result = null;
+          failure = { ...engineFailure(err), code: err?.code ?? engineFailure(err).code, attempts: err?.attempts, retryAfterMs: err?.retryAfterMs };
+          onError(queries[attempt], err);
+          // Do not try a different motif when the service is unavailable.
+          break;
+        }
+      }
+      out.push(result ? { group: g, engine, result, failure: null } : { group: g, engine, result: null, failure });
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, work.length) }, worker));
+  return out;
+}
+
+/**
+ * Coalesce concurrent single calls into one batched call: every `call(input)`
+ * made within `waitMs` of the first (up to `max`) travels as one
+ * `run(inputs)`, which answers with one output per input in order — an `Error`
+ * in a slot rejects only that caller. The ladders run concurrently, so their
+ * searches and picks meet here: one engine request and one vision read per
+ * round instead of one per motif.
+ */
+export function createBatcher(run, { max = 8, waitMs = 25 } = {}) {
+  let queue = [];
+  let timer = null;
+  const flush = () => {
+    clearTimeout(timer);
+    timer = null;
+    const batch = queue.slice(0, max);
+    queue = queue.slice(max);
+    if (queue.length) timer = setTimeout(flush, 0);
+    Promise.resolve()
+      .then(() => run(batch.map((b) => b.input)))
+      .then(
+        (outs) => batch.forEach((b, i) => (outs?.[i] instanceof Error ? b.reject(outs[i]) : b.resolve(outs?.[i]))),
+        (err) => batch.forEach((b) => b.reject(err)),
+      );
+  };
+  return (input) =>
+    new Promise((resolve, reject) => {
+      queue.push({ input, resolve, reject });
+      if (queue.length >= max) flush();
+      else if (!timer) timer = setTimeout(flush, waitMs);
+    });
+}

package/src/builders/block-dividers.mjs

@@ -0,0 +1,83 @@
+// A divider drawn between two lines of ONE text block — the rule under a
+// card's title, over its body (x105 GTM 2 / cloud 2: 34 such rules in 21
+// specs; 86 across x101–x105). The reader gives the lines one `block` and the
+// rule as its own stroke; foldTextBlocks writes the lines as one `T` with a
+// paragraph each, so the rule belongs to the BOUNDARY between two paragraphs
+// of that block: when the block's measured text is taller or shorter than the
+// painting, the rule rides with that boundary instead of keeping its painted
+// y (where it ended up under the body). The relation is containment in a
+// declared structure — the block's lines define the boundary, the rule lies
+// in it — not symmetry read into geometry; it keeps its drawn fraction of the
+// gap between the two paragraphs.
+import { linePoints, moveLine as moveLineDefault } from "./repeat-groups.mjs";
+
+const half = (v) => Math.round(v * 2) / 2;
+
+const horizontal = (c) => {
+  const pts = linePoints(c);
+  if (pts.length < 2) return null;
+  const ys = pts.map((p) => p.y);
+  if (Math.max(...ys) - Math.min(...ys) > 2) return null;
+  return { y: (Math.min(...ys) + Math.max(...ys)) / 2, x0: Math.min(...pts.map((p) => p.x)), x1: Math.max(...pts.map((p) => p.x)) };
+};
+
+/**
+ * The dividers drawn between consecutive `lines` (sorted, the members of one
+ * block, each contributing `count(line)` paragraphs): `[{ id, after, frac }]`
+ * with `after` the index of the paragraph the divider follows and `frac` its
+ * drawn fraction of the gap to the next one. Lines are connectors with an id.
+ */
+export function recordBlockDividers(lines, connectors, count = () => 1) {
+  const x0 = Math.min(...lines.map((c) => c.x));
+  const x1 = Math.max(...lines.map((c) => c.x + c.w));
+  const out = [];
+  for (const c of connectors) {
+    if (!c?.id) continue;
+    const h = horizontal(c);
+    if (!h || !(h.x0 < x1 && x0 < h.x1)) continue;
+    let after = 0;
+    for (let i = 0; i < lines.length - 1; i++) {
+      after += count(lines[i]);
+      const a = lines[i].y + lines[i].h;
+      const b = lines[i + 1].y;
+      if (h.y >= a - 1 && h.y <= b + 1) {
+        out.push({ id: c.id, after: after - 1, frac: b > a ? Math.min(1, Math.max(0, (h.y - a) / (b - a))) : 0.5 });
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Place every block divider at its boundary on the MEASURED paragraphs
+ * (`measured.get(block).paraRects`, settle.mjs measuredFromRender). Returns
+ * one line per divider moved. `moveLine(c, dx, dy)` is the caller's.
+ */
+export function placeBlockDividers(spec, measured, { moveLine = moveLineDefault } = {}) {
+  const changes = [];
+  const byId = new Map((spec.connectors ?? []).filter((c) => c?.id).map((c) => [c.id, c]));
+  for (const e of spec.elements ?? []) {
+    if (!e.dividers?.length) continue;
+    const m = measured.get(e.id);
+    const rects = m?.paraRects;
+    // Only when the render shows one box per paragraph: anything else is left where it is.
+    if (!rects || rects.length !== (e.paragraphs?.length ?? 0)) continue;
+    for (const d of e.dividers) {
+      const c = byId.get(d.id);
+      const a = rects[d.after];
+      const b = rects[d.after + 1];
+      if (!c || !a || !b) continue;
+      const bottom = a.y + a.h;
+      const next = b.y;
+      const want = half(bottom + Math.max(0, next - bottom) * d.frac);
+      const h = horizontal(c);
+      if (!h) continue;
+      const dy = half(want - h.y);
+      if (!dy) continue;
+      moveLine(c, 0, dy);
+      changes.push(`${d.id}: ${dy >= 0 ? "+" : ""}${dy}px to its place between the paragraphs of ${e.id}`);
+    }
+  }
+  return changes;
+}