@1agh/maude 0.58.2 → 0.59.0

package/apps/studio/figma/assets.ts

@@ -0,0 +1,452 @@
+/**
+ * @file       figma/assets.ts — resolving image + vector fills (DDR-216 T8).
+ * @scope      apps/studio/figma/assets.ts
+ * @purpose    Turn `pendingImages` / `pendingExports` into real, local,
+ *             content-addressed assets — batched, capped, and through the
+ *             existing gates rather than a second download path.
+ *
+ * @invariant  BATCH, NEVER ONE CALL PER NODE. `IMAGE_COST = 200` ⇒ ~30 req/min
+ *             on the images endpoint — the tight one. Figma's own translator
+ *             emitted 22 exports for a trivial 990×648 frame; a real page would
+ *             be hundreds. `to-artboard`'s vector-cluster collapse is the other
+ *             half of this mitigation.
+ *
+ * @invariant  DOWNLOADS GO THROUGH `_fetch-asset.mjs`, WITH THE FIGMA LANE'S
+ *             NARROWING. The URLs `/v1/images` returns are RESPONSE-CONTROLLED
+ *             — Maude did not choose them. They get the full resolved-IP gate
+ *             plus a host allowlist, a pinned port, and a tight byte cap. There
+ *             is no second downloader here.
+ *
+ * @invariant  FAIL CLOSED. A vector goes through TWO processes in TWO runtimes
+ *             (node for the download, bun for the DDR-167 SVG lane). DDR-177
+ *             documents that runtime-spawned helpers have shipped broken inside
+ *             the packaged `.app` more than once. If the sanitize step is
+ *             unavailable, the staged bytes are DELETED and the node is reported
+ *             `asset-skipped` — never "we already have the bytes", which is the
+ *             natural and wrong recovery.
+ *
+ * @invariant  DOWNLOADS STAGE OUTSIDE THE DESIGN ROOT. The caller's per-run
+ *             staging directory lives under the OS temp root, never under
+ *             `<designRoot>/_history/` — "gitignored" is not "not replicated",
+ *             and `~/git/.stignore` excludes neither.
+ *
+ * @limitation ASSETS PROMOTE PER-ASSET, NOT ONCE AT THE END. `deps.promote`
+ *             writes into `<designRoot>/assets/` as each download completes, so
+ *             a failure on frame 7 of 60 leaves earlier assets committed while
+ *             the report says the import failed. D5 asked for a single
+ *             directory rename; this is N renames. Stated as a KNOWN GAP rather
+ *             than described as the guarantee it is not (post-implementation
+ *             review F6) — content-addressing makes the residue harmless-but-
+ *             untidy (orphan assets, no wrong content), which is why it is a
+ *             limitation and not a blocker.
+ */
+
+import { fetchImageUrls, MAX_IMAGE_BATCH } from './client.ts';
+import type { Disposition, ImportReport } from './sanitize.ts';
+
+/** Hosts the Figma image lane may reach. Exact-or-dotted-suffix, frozen. */
+export const FIGMA_ASSET_HOSTS = Object.freeze([
+  'figma.com',
+  'figma-alpha-api.s3.us-west-2.amazonaws.com',
+]);
+
+/**
+ * D5 — total DISTINCT assets per import (post-dedupe).
+ *
+ * Raised from 200 on measurement, not on request. A normal 6-page product file
+ * — the live StudyFi onboarding file — carries 984 vector clusters that dedupe
+ * to ~530 distinct component renders. At 200 it dropped a THIRD of the file's
+ * artwork, which is not a backstop against an engineered document, it is a
+ * refusal to import normal work.
+ *
+ * The bound that actually protects the tree is `MAX_ASSET_BYTES_PER_IMPORT`:
+ * 530 icons are a few MB, while one photo-heavy board is tens. A count cap is
+ * the wrong dimension for vector art and was calibrated before anyone had run
+ * the thing on a real file.
+ */
+export const MAX_ASSETS_PER_IMPORT = 1500;
+/** D5 — cumulative bytes, the cap the per-item ones do not give you. */
+export const MAX_ASSET_BYTES_PER_IMPORT = 64 * 1024 * 1024;
+/**
+ * A UI vector export is kilobytes. The shared helper's 10 MB default was sized
+ * for a hero photograph; this lane pins far below it, which is also what closes
+ * the "200 assets × 10 MB = 2 GB into a replicated tree" shape.
+ */
+export const FIGMA_ASSET_MAX_BYTES = 2 * 1024 * 1024;
+/** D11 — well below DDR-167's 5 MB, because these bytes are now REMOTE. */
+export const FIGMA_SVG_MAX_BYTES = 1 * 1024 * 1024;
+/** Politeness + bounded local work. */
+export const MAX_CONCURRENT_DOWNLOADS = 4;
+
+/**
+ * SVGs handed to ONE `promoteSvgBatch` call.
+ *
+ * The DDR-167 execution canary launches a browser per call, which is why the
+ * batch exists at all — a per-file promote made a real icon set a ~40-minute
+ * import. But the batch runs under `agent-browser`'s fixed 20 s spawn budget
+ * (`_import-asset.mjs`), so an UNBOUNDED batch trades one pathology for another:
+ * at 272 frame renders the canary timed out and the caller's fail-closed rule
+ * discarded every asset in one go.
+ *
+ * 24 is deliberately well under where it was measured to break (60 timed out;
+ * the same run had previously survived 272 by luck of timing) — the cost of a
+ * chunk too small is a few extra browser launches, and the cost of a chunk too
+ * large is losing the chunk.
+ */
+export const MAX_SVG_PROMOTE_CHUNK = 24;
+
+export interface AssetRequest {
+  nodeId: string;
+  format: 'svg' | 'png';
+  /** What the emitted source currently references. */
+  placeholder: string;
+}
+
+/**
+ * Per-call knobs for the render-first lane. Both default to the icon-export
+ * behaviour, so the existing fill/vector path is byte-identical without them.
+ */
+export interface ResolveOptions {
+  /**
+   * `false` keeps real `<text>` runs in a rendered SVG instead of converting
+   * them to outlines. Whole-frame renders want that — an artboard whose text is
+   * curves is a picture of a screen, not a screen you can search.
+   */
+  outlineText?: boolean;
+  /**
+   * Overrides `FIGMA_SVG_MAX_BYTES`. A single icon is kilobytes, but a whole
+   * rendered frame carries its raster fills inline as data URIs, so the 1 MB
+   * icon ceiling would reject perfectly normal screens.
+   */
+  svgMaxBytes?: number;
+}
+
+/** D11 — the whole-frame ceiling. Still far under DDR-167's own 5 MB. */
+export const FIGMA_RENDER_MAX_BYTES = 4 * 1024 * 1024;
+
+export interface ResolvedAsset {
+  nodeId: string;
+  placeholder: string;
+  /** The canvas reference path, e.g. `/assets/<sha8>.png`. */
+  ref: string;
+  bytes: number;
+}
+
+export interface ResolveDeps {
+  /**
+   * Download to a staged path under the FULL gate. Injected so this module is
+   * testable without the network — the real implementation is
+   * `_fetch-asset.mjs`'s `fetchAsset({ rawOut })`.
+   */
+  stage(url: string, outPath: string, maxBytes: number): Promise<{ bytes: number; ext: string }>;
+  /**
+   * Sanitize + promote a staged file into `assets/`, returning the canvas ref.
+   * The real implementation routes SVG through `_import-asset.mjs`'s DDR-167
+   * lane and rasters through the content-addressed write.
+   */
+  promote(stagedPath: string, kind: 'svg' | 'png'): Promise<{ ref: string }>;
+  /**
+   * Optional: promote MANY svg files in one pass. The DDR-167 execution canary
+   * launches a browser per call, so a per-file promote made a real icon set a
+   * ~40-minute import. When present this is used for every staged SVG; when
+   * absent the per-file `promote` is, so a caller that has not been updated
+   * still works.
+   */
+  promoteSvgBatch?(stagedPaths: readonly string[]): Promise<Array<string | null>>;
+  /** Where staged bytes live — OUTSIDE the design root (D5). */
+  stagingPath(nodeId: string, ext: string): string;
+  /** Drop a staged file on any failure path. */
+  discard(path: string): void;
+}
+
+/**
+ * The caps, as ONE mutable budget for a whole import.
+ *
+ * They were function-locals of `resolveAssets`, which reads correctly and is
+ * wrong: `importFrames` calls it once PER FRAME, so the ceiling reset every
+ * frame and 60 frames reconstructed exactly the multi-GB, Syncthing-replicated
+ * shape D5 says it closed — while spending a browser launch per SVG canary.
+ * A budget you can only bound by asking "who owns the counter?" is not a bound
+ * (post-implementation review F4).
+ */
+export interface AssetBudget {
+  count: number;
+  bytes: number;
+}
+
+export function makeAssetBudget(): AssetBudget {
+  return { count: 0, bytes: 0 };
+}
+
+export interface ResolveResult {
+  resolved: ResolvedAsset[];
+  /** placeholder → ref, for rewriting the emitted source in one pass. */
+  rewrites: Map<string, string>;
+  totalBytes: number;
+}
+
+/**
+ * The id to RENDER for a node — an instance renders as its component.
+ *
+ * Figma scopes a node inside a component instance as `I<instancePath>;<compId>`,
+ * so 40 placements of one icon are 40 distinct node ids that render to
+ * byte-identical SVG. Measured on a live StudyFi file: 984 vector clusters
+ * across 6 pages collapsed to a small fraction once keyed this way. Without it
+ * the 200-asset cap eats a real file's icon set alive, and every duplicate also
+ * costs a download AND a browser canary.
+ *
+ * Content-addressing already dedupes on DISK; this dedupes the WORK.
+ */
+export function renderKey(nodeId: string): string {
+  const semi = nodeId.lastIndexOf(';');
+  return semi > 0 ? nodeId.slice(semi + 1) : nodeId;
+}
+
+/** Split ids into `/v1/images`-sized batches. Never one call per node. */
+export function batchIds(ids: readonly string[], size = MAX_IMAGE_BATCH): string[][] {
+  const out: string[][] = [];
+  for (let i = 0; i < ids.length; i += size) out.push([...ids.slice(i, i + size)]);
+  return out;
+}
+
+/** Run `tasks` with bounded concurrency, preserving input order in the result. */
+async function pooled<T, R>(
+  items: readonly T[],
+  limit: number,
+  run: (item: T, index: number) => Promise<R>
+): Promise<R[]> {
+  const out: R[] = new Array(items.length);
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (true) {
+      const i = cursor++;
+      if (i >= items.length) return;
+      out[i] = await run(items[i], i);
+    }
+  });
+  await Promise.all(workers);
+  return out;
+}
+
+/**
+ * Resolve every pending asset for one import.
+ *
+ * Caps are enforced BEFORE work is done where possible (asset count) and
+ * during it where they cannot be (cumulative bytes) — and a cap trip is a
+ * REPORTED bounded degradation (`asset-cap-reached`), not a silent stop: the
+ * import continues without that asset and the summary names it.
+ */
+export async function resolveAssets(
+  fileKey: string,
+  requests: readonly AssetRequest[],
+  deps: ResolveDeps,
+  report: ImportReport,
+  budget: AssetBudget = makeAssetBudget(),
+  opts: ResolveOptions = {}
+): Promise<ResolveResult> {
+  const rewrites = new Map<string, string>();
+  const resolved: ResolvedAsset[] = [];
+  let totalBytes = 0;
+
+  if (requests.length === 0) return { resolved, rewrites, totalBytes };
+
+  // Dedupe by RENDER KEY first — the cap should bound distinct artwork, not
+  // repeated placements of the same icon.
+  const byKey = new Map<string, AssetRequest[]>();
+  for (const r of requests) {
+    const key = `${renderKey(r.nodeId)}:${r.format}`;
+    const list = byKey.get(key);
+    if (list) list.push(r);
+    else byKey.set(key, [r]);
+  }
+  const unique = [...byKey.values()].map((group) => group[0]);
+
+  const room = Math.max(0, MAX_ASSETS_PER_IMPORT - budget.count);
+  const accepted = unique.slice(0, room);
+  budget.count += accepted.length;
+  for (const dropped of unique.slice(room)) {
+    report.add(dropped.nodeId, 'ASSET', 'asset-cap-reached', `>${MAX_ASSETS_PER_IMPORT}`);
+  }
+
+  // ── Batched URL resolution, per format ──
+  const urlByNode = new Map<string, string>();
+  /** Effective format per node — an SVG that fell back to raster is tracked here. */
+  const formatByNode = new Map<string, 'svg' | 'png'>();
+  for (const format of ['svg', 'png'] as const) {
+    const ids = accepted.filter((r) => r.format === format).map((r) => r.nodeId);
+    if (ids.length === 0) continue;
+    for (const batch of batchIds(ids)) {
+      const { images } = await fetchImageUrls(
+        fileKey,
+        batch,
+        format,
+        2,
+        opts.outlineText !== undefined ? { outlineText: opts.outlineText } : {}
+      );
+      for (const [nodeId, url] of Object.entries(images)) {
+        if (typeof url === 'string' && url.length > 0) {
+          urlByNode.set(nodeId, url);
+          formatByNode.set(nodeId, format);
+        }
+      }
+    }
+  }
+
+  // RASTER FALLBACK. Figma answers `null` — not an error — for nodes it will
+  // not vectorize, and a null with no retry is an artboard whose <img> points
+  // at a placeholder that never resolves: a broken image where a screen should
+  // be. Ask for the same node as PNG before giving up on it.
+  const missing = accepted
+    .filter((r) => r.format === 'svg' && !urlByNode.has(r.nodeId))
+    .map((r) => r.nodeId);
+  for (const batch of batchIds(missing)) {
+    const { images } = await fetchImageUrls(fileKey, batch, 'png', 2);
+    for (const [nodeId, url] of Object.entries(images)) {
+      if (typeof url === 'string' && url.length > 0) {
+        urlByNode.set(nodeId, url);
+        formatByNode.set(nodeId, 'png');
+        report.add(nodeId, 'ASSET', 'asset-degraded', 'vector unavailable — rasterized');
+      }
+    }
+  }
+
+  // ── Bounded-concurrency download; SVG promotes are batched afterwards ──
+  const stagedSvgs: Array<{ req: AssetRequest; staged: string }> = [];
+
+  await pooled(accepted, MAX_CONCURRENT_DOWNLOADS, async (req) => {
+    const url = urlByNode.get(req.nodeId);
+    if (!url) {
+      report.add(req.nodeId, 'ASSET', 'asset-skipped', 'figma declined to render');
+      return;
+    }
+    if (budget.bytes >= MAX_ASSET_BYTES_PER_IMPORT) {
+      report.add(req.nodeId, 'ASSET', 'asset-cap-reached', 'total bytes');
+      return;
+    }
+
+    // What we ACTUALLY got, which is not always what we asked for — see the
+    // raster fallback above.
+    const eff = formatByNode.get(req.nodeId) ?? req.format;
+    const staged = deps.stagingPath(req.nodeId, eff);
+    try {
+      const cap = eff === 'svg' ? (opts.svgMaxBytes ?? FIGMA_SVG_MAX_BYTES) : FIGMA_ASSET_MAX_BYTES;
+      const { bytes, ext } = await deps.stage(url, staged, cap);
+      // Counted HERE, not after a successful promote: bytes that crossed the
+      // network and landed on disk cost the same whether the promote succeeded.
+      budget.bytes += bytes;
+      // The staged kind must agree with what we asked Figma to render. A
+      // mismatch means the response is not what the request implied — refuse
+      // rather than promote something into a versioned, peer-synced tree.
+      const kindOk = eff === 'svg' ? ext === 'svg' : ext !== 'svg';
+      if (!kindOk) {
+        deps.discard(staged);
+        report.add(req.nodeId, 'ASSET', 'asset-skipped', 'format mismatch');
+        return;
+      }
+      if (eff === 'svg' && deps.promoteSvgBatch) {
+        // Defer — one browser session for all of them beats one each.
+        stagedSvgs.push({ req, staged });
+        totalBytes += bytes;
+        return;
+      }
+      const { ref } = await deps.promote(staged, eff);
+      totalBytes += bytes;
+      resolved.push({ nodeId: req.nodeId, placeholder: req.placeholder, ref, bytes });
+      // Every placement that shares this render key gets the same asset.
+      for (const sibling of byKey.get(`${renderKey(req.nodeId)}:${req.format}`) ?? [req]) {
+        rewrites.set(sibling.placeholder, ref);
+      }
+    } catch {
+      // FAIL CLOSED — including when the bun-side sanitizer is simply not
+      // available in a packaged app (DDR-177). Delete the staged bytes and
+      // report; never keep them and never reference them.
+      deps.discard(staged);
+      report.add(req.nodeId, 'ASSET', 'asset-skipped', 'download or sanitize failed');
+    }
+  });
+
+  if (stagedSvgs.length > 0 && deps.promoteSvgBatch) {
+    const refs: Array<string | null> = [];
+    // CHUNKED, because "fail closed for the whole batch" and "one batch for the
+    // whole import" together turn a single browser timeout into total asset
+    // loss. Measured on a live 6-page import: the DDR-167 execution canary
+    // spawns `agent-browser` with a fixed 20 s budget (`_import-asset.mjs`), one
+    // session for the whole array — at 272 frame renders it blew that budget,
+    // the promote threw, and every one of the 272 became `asset-skipped`. The
+    // import still exited 0, so it reported success while producing a folder of
+    // broken images. Reproduced at 60 SVGs, and it reproduces WITHOUT any of the
+    // Figma-lane changes, so this is the shared lane's shape, not the caller's.
+    //
+    // Fail-closed is KEPT — it is the DDR-177 rule and it is right. What changes
+    // is the blast radius: a timeout now costs its own chunk, and the rest of
+    // the artwork still lands.
+    for (let start = 0; start < stagedSvgs.length; start += MAX_SVG_PROMOTE_CHUNK) {
+      const chunk = stagedSvgs.slice(start, start + MAX_SVG_PROMOTE_CHUNK);
+      let got: Array<string | null> | null = null;
+      // ONE RETRY, because the canary's failure is measurably TRANSIENT rather
+      // than a property of the input. Measured on a cleaned machine: the same
+      // lane promoted 4/4 (30.7 s) and 24/24 (42.3 s) but threw on 12 (24.3 s) —
+      // the budget is per `agent-browser` invocation, and a big frame render
+      // flirts with it. A chunk lost to a coin-flip is a permanently broken
+      // image in a versioned artifact, and a second attempt is one browser
+      // launch. Bounded at one: a lane that is genuinely down must still fail
+      // fast rather than retry 12 chunks into a multi-minute stall.
+      for (let attempt = 0; attempt < 2 && got === null; attempt += 1) {
+        try {
+          got = await deps.promoteSvgBatch(chunk.map((x) => x.staged));
+        } catch {
+          got = null;
+        }
+      }
+      if (got === null) {
+        // FAIL CLOSED, same rule as the per-file path: the bun-side lane being
+        // unavailable must never become "we already have the bytes"
+        // (DDR-177's packaged-app failure mode).
+        for (let i = 0; i < chunk.length; i += 1) refs.push(null);
+        continue;
+      }
+      // A short return would silently shift every later ref onto the wrong
+      // node — pad rather than trust the length.
+      for (let i = 0; i < chunk.length; i += 1) refs.push(got[i] ?? null);
+    }
+    for (let i = 0; i < stagedSvgs.length; i += 1) {
+      const { req, staged } = stagedSvgs[i];
+      const ref = refs[i];
+      if (!ref) {
+        deps.discard(staged);
+        report.add(req.nodeId, 'ASSET', 'asset-skipped', 'sanitize refused');
+        continue;
+      }
+      resolved.push({ nodeId: req.nodeId, placeholder: req.placeholder, ref, bytes: 0 });
+      for (const sibling of byKey.get(`${renderKey(req.nodeId)}:svg`) ?? [req]) {
+        rewrites.set(sibling.placeholder, ref);
+      }
+    }
+  }
+
+  return { resolved, rewrites, totalBytes };
+}
+
+/**
+ * Rewrite placeholders in emitted source. A placeholder that never resolved is
+ * left in place deliberately — the canvas shows a visibly broken image, which
+ * is a far better failure than a silently-missing element, and the summary
+ * already names the node.
+ */
+export function applyRewrites(source: string, rewrites: ReadonlyMap<string, string>): string {
+  let out = source;
+  for (const [placeholder, ref] of rewrites) {
+    out = out.split(placeholder).join(ref);
+  }
+  return out;
+}
+
+/** The disposition set this module can emit — kept in sync with `sanitize.ts`.
+ *  `asset-degraded` was missing here as well as from the union; both halves of
+ *  the drift are closed together (DDR-219 D9). */
+export const ASSET_DISPOSITIONS: readonly Disposition[] = [
+  'asset-pending',
+  'asset-skipped',
+  'asset-cap-reached',
+  'asset-degraded',
+];