slidemind 0.3.20 → 0.4.1

package/src/lib/image-derivatives.mjs

@@ -0,0 +1,234 @@
+// What a source image needs before a renderer can ship it — recorded as data,
+// never performed here.
+//
+// The CLI owns no decoder and no converter (design decision: "do not add an
+// independent image-processing service", and this package has no image
+// dependency at all). What it CAN do is read a header and say, deterministically,
+// what the picture pipeline will have to do with those bytes:
+//
+//   * a JPEG whose EXIF says it is rotated is presented rotated — a RENDERING
+//     transform, so the stored digest still hashes the raw imported bytes;
+//   * an animated source is presented as its first frame, with a static-output
+//     note, because a PPTX picture promises no animation;
+//   * a format the OOXML adapter cannot embed as-is (WebP, SVG) ships as a
+//     derivative while the source stays in the workspace, untouched.
+//
+// Each of those produces a DERIVATIVE RECORD — parent hash, format, transform
+// version — which is the contract's evidence that the thing embedded in the
+// .pptx descends from the registered source. The bytes of the derivative are
+// produced at capture by the image decoration both clients run (the add-in's
+// build-pptx/image-decorate.ts, served to the CLI in the capture engine): it
+// asks `renderTransforms` below about the same bytes, so the declaration here
+// and the picture that ships cannot disagree, and the export check accepts the
+// derivative only by the parent digest the capture recorded for it.
+//
+// Mirrored byte-identically into the add-in (shared/plan-contract/lib), which
+// renders with it and words the same notes from it.
+//
+// Every derivative is PNG. One rule instead of three: it is lossless (a JPEG
+// re-encode for a rotation is not), it keeps alpha (a transparent PNG must never
+// come back flattened), and every renderer on both sides embeds it natively.
+
+/** Bumped when a transform's OUTPUT changes, so old derivatives are recognised as stale. */
+export const IMAGE_TRANSFORM_VERSION = 1;
+
+// What the OOXML adapter embeds without conversion; the add-in's image
+// decoration and export check take their list from here. Anything else the
+// contract supports — WebP — needs a derivative. An SVG ships as itself: the
+// file rides in the picture's `asvg:svgBlip`, with the capture's raster as the
+// fallback blip, so it needs none.
+export const NATIVE_RASTER_MIME_TYPES = ["image/png", "image/jpeg", "image/gif"];
+const SHIPS_AS_ITSELF = new Set([...NATIVE_RASTER_MIME_TYPES, "image/svg+xml"]);
+
+export const DERIVATIVE_FORMAT = "image/png";
+
+const startsWith = (buf, offset, bytes) =>
+  buf.length >= offset + bytes.length && bytes.every((b, i) => buf[offset + i] === b);
+
+const ascii = (s) => [...s].map((c) => c.charCodeAt(0));
+
+// ---------------------------------------------------------------------------
+// EXIF orientation
+// ---------------------------------------------------------------------------
+
+// The Orientation tag out of a TIFF header that starts at `base` (just past
+// "Exif\0\0"). Values 1..8; 5..8 are the ones that swap width and height.
+function orientationFromTiff(buf, base) {
+  if (base + 8 > buf.length) return null;
+  const byteOrder = String.fromCharCode(buf[base], buf[base + 1]);
+  const le = byteOrder === "II";
+  if (!le && byteOrder !== "MM") return null;
+  const u16 = (o) => (le ? buf.readUInt16LE(o) : buf.readUInt16BE(o));
+  const u32 = (o) => (le ? buf.readUInt32LE(o) : buf.readUInt32BE(o));
+  if (u16(base + 2) !== 42) return null;
+  const ifd = base + u32(base + 4);
+  if (ifd + 2 > buf.length) return null;
+  const entries = u16(ifd);
+  for (let i = 0; i < entries; i++) {
+    const at = ifd + 2 + i * 12;
+    if (at + 12 > buf.length) return null;
+    if (u16(at) !== 0x0112) continue;
+    const value = u16(at + 8); // SHORT, so the value sits inline
+    return value >= 1 && value <= 8 ? value : null;
+  }
+  return null;
+}
+
+/**
+ * A JPEG's EXIF orientation (1..8), or null when it carries none.
+ *
+ * Walks the marker segments the same way `imageSizeFromBuffer` does, and stops
+ * at the start of scan data — EXIF never appears after it.
+ */
+export function exifOrientation(buf) {
+  if (!buf || !startsWith(buf, 0, [0xff, 0xd8, 0xff])) return null;
+  let pos = 2;
+  while (pos + 4 <= buf.length) {
+    if (buf[pos] !== 0xff) {
+      pos++;
+      continue;
+    }
+    const marker = buf[pos + 1];
+    if (marker === 0xff) {
+      pos++; // fill byte
+      continue;
+    }
+    if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+      pos += 2; // standalone, no payload
+      continue;
+    }
+    if (marker === 0xda || marker === 0xd9) return null; // scan data / end
+    const length = buf.readUInt16BE(pos + 2);
+    if (length < 2) return null;
+    if (marker === 0xe1 && buf.length >= pos + 10 && buf.toString("latin1", pos + 4, pos + 10) === "Exif\0\0") {
+      return orientationFromTiff(buf, pos + 10);
+    }
+    pos += 2 + length;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// animation
+// ---------------------------------------------------------------------------
+
+/**
+ * Does this GIF carry more than one frame?
+ *
+ * Walks the block structure and stops at the second image descriptor — no
+ * decoding, so an unparseable stream answers "not animated" and is embedded as
+ * it stands rather than being declared a derivative on a guess.
+ */
+export function gifIsAnimated(buf) {
+  if (!buf || !startsWith(buf, 0, ascii("GIF8")) || buf.length < 14) return false;
+  const flags = buf[10];
+  let pos = 13;
+  if (flags & 0x80) pos += 3 * 2 ** ((flags & 0x07) + 1); // global colour table
+  const skipSubBlocks = () => {
+    while (pos < buf.length) {
+      const size = buf[pos++];
+      if (size === 0) return true;
+      pos += size;
+    }
+    return false;
+  };
+  let frames = 0;
+  while (pos < buf.length) {
+    const block = buf[pos];
+    if (block === 0x3b) return false; // trailer
+    if (block === 0x21) {
+      pos += 2; // introducer + label
+      if (!skipSubBlocks()) return false;
+      continue;
+    }
+    if (block !== 0x2c) return false; // not a structure we can walk
+    if (++frames > 1) return true;
+    if (pos + 10 > buf.length) return false;
+    const local = buf[pos + 9];
+    pos += 10;
+    if (local & 0x80) pos += 3 * 2 ** ((local & 0x07) + 1); // local colour table
+    pos += 1; // LZW minimum code size
+    if (!skipSubBlocks()) return false;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// the plan
+// ---------------------------------------------------------------------------
+
+/**
+ * The transforms a renderer must apply to ship these bytes, in the order the
+ * plan names them: `exif-orientation` (a rotated JPEG ships upright),
+ * `first-frame` (an animated GIF ships its first frame), `format-conversion`
+ * (a format the adapter cannot embed). Empty when the source ships as itself.
+ * The one decision both the plan's notes and the capture's image decoration
+ * read.
+ *
+ * @param {string} mimeType the sniffed type of `bytes`
+ * @param {Buffer} bytes
+ */
+export function renderTransforms(mimeType, bytes) {
+  const transforms = [];
+  if (mimeType === "image/jpeg") {
+    const orientation = exifOrientation(bytes);
+    if (orientation && orientation !== 1) transforms.push("exif-orientation");
+  } else if (mimeType === "image/gif" && gifIsAnimated(bytes)) {
+    transforms.push("first-frame");
+  }
+  if (!SHIPS_AS_ITSELF.has(mimeType)) transforms.push("format-conversion");
+  return transforms;
+}
+
+/**
+ * How `asset`'s bytes reach a slide: as themselves, or through a declared
+ * derivative.
+ *
+ * Returns `{native, presented, transforms, derivative, notes}`. `presented` is
+ * the asset's own size: the registry on both clients records the
+ * orientation-corrected size a viewer sees — the one a crop fraction and an
+ * `<img>` box are expressed in — while the digest hashes the raw bytes.
+ * `derivative` is null when the source ships untouched.
+ *
+ * @param {{sha256: string, mimeType: string, width: number, height: number}} asset
+ * @param {Buffer} bytes the asset's raw imported bytes
+ */
+export function imageRenderPlan(asset, bytes) {
+  const transforms = renderTransforms(asset.mimeType, bytes);
+  const notes = [];
+  const presented = { width: asset.width, height: asset.height };
+
+  if (transforms.includes("exif-orientation")) {
+    const orientation = exifOrientation(bytes);
+    notes.push(
+      `EXIF orientation ${orientation}: the render ships the picture upright, as a PNG derivative. ` +
+        `The stored digest hashes the raw imported bytes, so it does not change.`,
+    );
+  }
+  if (transforms.includes("first-frame")) {
+    notes.push(
+      "Animated source: the slide shows its first frame, shipped as a PNG derivative. A PowerPoint picture " +
+        "is static here — the animation is not promised, and the full source stays in the workspace.",
+    );
+  }
+  if (transforms.includes("format-conversion")) {
+    notes.push(
+      `${asset.mimeType} cannot be embedded as it stands: the render ships a PNG derivative of it, ` +
+        `and the source is kept unchanged.`,
+    );
+  }
+
+  const derivative = transforms.length
+    ? {
+        parentSha256: asset.sha256,
+        parentMimeType: asset.mimeType,
+        format: DERIVATIVE_FORMAT,
+        transformVersion: IMAGE_TRANSFORM_VERSION,
+        transforms: [...transforms],
+        width: presented.width,
+        height: presented.height,
+      }
+    : null;
+
+  return { native: derivative === null, presented, transforms, derivative, notes };
+}

package/src/lib/image-intent-fingerprint.mjs

@@ -0,0 +1,70 @@
+// The SHA-256 half of the image-intent contract (design decision 6).
+//
+// Split out of `image-intent.mjs` for one reason: that module is concatenated
+// into the plan gate's browser bundle and may not touch `node:crypto`. The
+// projection — which fields count, in what order — lives there, in
+// `imageIntentFingerprintInput()`; only the hashing lives here.
+//
+// `canonicalJson` is a line-for-line port of the add-in's
+// `src/ui/src/node/agent/storage/canonical-hash.ts`, which the add-in side
+// reuses as-is: recursively sorted object keys, array order preserved, UTF-8
+// JSON, `undefined` object properties dropped, non-finite numbers and
+// `undefined` array entries as `null`. The two implementations are held
+// together by `test/fixtures/image-intent/contract.json`, which carries the
+// expected canonical string AND digest for each case — not by shared code,
+// since the CLI cannot import from the sibling repository.
+
+import { createHash } from "node:crypto";
+
+import { imageIntentFingerprintInput } from "./image-intent.mjs";
+
+function normalize(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) =>
+      entry === undefined || typeof entry === "function" ? null : normalize(entry),
+    );
+  }
+  if (typeof value === "object") {
+    const normalized = {};
+    for (const key of Object.keys(value).sort()) {
+      const entry = value[key];
+      if (entry === undefined || typeof entry === "function" || typeof entry === "symbol") {
+        continue;
+      }
+      normalized[key] = normalize(entry);
+    }
+    return normalized;
+  }
+  throw new TypeError("Value is not JSON-compatible");
+}
+
+/** Canonical JSON: sorted keys, preserved array order. */
+export function canonicalJson(value) {
+  return JSON.stringify(normalize(value));
+}
+
+export function sha256Hex(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function canonicalSha256(value) {
+  return sha256Hex(canonicalJson(value));
+}
+
+/**
+ * The fingerprint a concept, spec or validation record is keyed by.
+ *
+ * Changing an instruction, a source's bytes, a crop or the set of uses changes
+ * it; renaming the file or moving the workspace does not.
+ *
+ * @param {{uses?: Array, assets?: Array, context?: unknown}} args
+ */
+export function imageIntentFingerprint(args = {}) {
+  return canonicalSha256(imageIntentFingerprintInput(args));
+}

package/src/lib/image-intent-tags.mjs

@@ -0,0 +1,176 @@
+// Image provenance through the deck-embedded source tags — one slide's
+// approved image obligations, baked into the .pptx it was rendered into and
+// read back out when that file is adopted again (design decision 8, A27).
+//
+// Why it rides the slide's own tags rather than a sidecar: the .pptx is the
+// only thing that travels. A rendered deck is mailed, opened, saved and handed
+// back, and `slidemind adopt` rebuilds a workspace from it alone. Everything
+// else about a slide already survives that round trip — its jsx, its assets,
+// its identity, its drift baseline. An obligation that did not would come back
+// as a picture nobody could prove was the user's own.
+//
+// Two halves, both narrow:
+//
+//   BAKE   `imageIntentTagMeta` projects the slide's effective uses and the
+//          registry entries they name into `SRC_META.imageIntent`. The BYTES
+//          need no arrangement: the jsx references `./assets/local/<id>.<ext>`,
+//          so `referencedAssets` already embeds them within the tag budget.
+//   RESTORE `restoreImageIntentFromTags` puts both back — registry entries
+//          through `registerImageAssets` (identity preserved, bytes proved),
+//          uses through `setSlideImageUses` keyed by the slide's own GUID.
+//
+// The restore is deliberately conservative in three ways:
+//
+//   * **A file with no `imageIntent` gains nothing.** A plain imported .pptx —
+//     one slidemind never rendered, or one from before this contract — is
+//     legacy and stays legacy. An obligation is never manufactured from a
+//     picture that happens to be on a slide (design decision 8, A27).
+//   * **Only a slide restored from its own proved-current source is restored at
+//     all.** A slide that had to be re-converted from its edited self is
+//     rebuilt content — adopt itself judged the embedded source stale — and its
+//     picture may have been moved, replaced or deleted in PowerPoint. Asserting
+//     the old obligation over it would refuse every later build for an edit
+//     nobody made to the picture. The bytes are still in the file; rebinding is
+//     a deliberate act, through the plan.
+//   * **Nothing is overwritten.** A known assetId with different bytes, a
+//     colliding useId, an asset whose bytes did not survive — each is reported
+//     and skipped. A partial restore says what it dropped.
+//
+// One known property, not a bug (confirmed with the add-in 2026-09-21): the
+// add-in's own bake builds a FRESH meta from its own input (spec §5.3 write
+// point 2 — a live insert or replace), so a slide re-pushed from the add-in
+// comes back without this key. Its obligations are not lost — the add-in keeps
+// its own record in its workspace, and the deck's registry and plan here are
+// untouched — so the next CLI build re-writes the key from the registry rather
+// than from the tags. What does not survive is that one slide's provenance
+// INSIDE a .pptx pushed from the add-in and adopted without a CLI build in
+// between; it adopts as a slide with a picture and no obligation, which is the
+// legacy case and refuses nothing.
+
+import {
+  findAssetById,
+  readImageAssetManifest,
+  registerImageAssets,
+} from "./image-assets.mjs";
+import { setSlideImageUses } from "./image-use-overrides.mjs";
+import { IMAGE_INTENT_VERSION, validateSlideUses } from "./image-intent.mjs";
+import { effectiveUsesForSlides } from "../bridge/image-intent-envelope.mjs";
+
+export const IMAGE_INTENT_META_KEY = "imageIntent";
+
+/**
+ * The `SRC_META.imageIntent` payload for each of `slides`, as
+ * `Map<slide, meta>` — a slide with no image use is absent, which keeps its
+ * tags byte-identical to what they were before this contract existed.
+ *
+ * Resolved for the WHOLE bake in one call on purpose: the effective-use lookup
+ * re-reads and re-hashes every slide file to map overrides onto slide numbers,
+ * so asking it per slide makes a deck pay for that once per slide.
+ *
+ * @param {string} deckDir the deck workspace
+ * @param {number[]} slides 1-based slide numbers (each file's NN- prefix)
+ */
+export function imageIntentTagMetaForSlides(deckDir, slides, { planMarkdown = null } = {}) {
+  const out = new Map();
+  const wanted = (slides ?? []).filter((n) => Number.isInteger(n) && n > 0);
+  if (!wanted.length) return out;
+  let bySlide;
+  let manifest;
+  try {
+    bySlide = effectiveUsesForSlides(deckDir, wanted, { planMarkdown });
+    manifest = readImageAssetManifest(deckDir);
+  } catch {
+    // An unreadable registry is reported by the commands that need it (the
+    // draft check, the envelope build). A bake is bookkeeping: it must not be
+    // the thing that fails a render.
+    return out;
+  }
+  for (const [slide, uses] of bySlide) {
+    if (!uses.length) continue;
+    const assets = [];
+    for (const assetId of [...new Set(uses.map((u) => u.assetId))].sort()) {
+      const asset = findAssetById(manifest, assetId);
+      if (asset) assets.push(asset);
+    }
+    if (assets.length) out.set(slide, { v: IMAGE_INTENT_VERSION, uses, assets });
+  }
+  return out;
+}
+
+/** One slide's payload, or null. */
+export function imageIntentTagMeta(deckDir, slide, opts = {}) {
+  return imageIntentTagMetaForSlides(deckDir, [slide], opts).get(slide) ?? null;
+}
+
+/**
+ * Restore the image provenance a set of adopted slides carried.
+ *
+ * @param {string} deckDir the deck being adopted into
+ * @param {Array<{slideId: string|null, intent: object|null, restoreUses: boolean,
+ *                renames?: Map<string,string>}>} entries
+ *   one per adopted slide. `renames` is adopt's asset-collision map
+ *   (`assets/local/x.png` → the name actually written), so a restored entry
+ *   points at the file that really landed.
+ * @returns {{assets: number, slides: number, notes: string[]}}
+ */
+export function restoreImageIntentFromTags(deckDir, entries) {
+  const notes = [];
+  const wanted = (entries ?? []).filter((e) => e?.intent && Array.isArray(e.intent.assets));
+  if (!wanted.length) return { assets: 0, slides: 0, notes };
+
+  // Every slide's assets in one manifest write — a re-adopted deck has one
+  // registry, not one per slide.
+  const descriptors = new Map();
+  for (const entry of wanted) {
+    if (entry.intent.v !== IMAGE_INTENT_VERSION) {
+      notes.push(
+        `a slide records image intent version ${entry.intent.v} — this CLI speaks version ${IMAGE_INTENT_VERSION}; its obligations were not restored`,
+      );
+      entry.unsupported = true;
+      continue;
+    }
+    for (const asset of entry.intent.assets) {
+      if (!asset?.assetId) continue;
+      const placed = entry.renames?.get(asset.workspacePath);
+      descriptors.set(asset.assetId, placed ? { ...asset, workspacePath: placed } : asset);
+    }
+  }
+  const { added, reused, rejected } = registerImageAssets(deckDir, [...descriptors.values()]);
+  for (const bad of rejected) {
+    notes.push(`image source ${bad.assetId ?? "(unnamed)"} was not restored: ${bad.reason}`);
+  }
+  const usable = new Set([...added, ...reused]);
+
+  let slides = 0;
+  for (const entry of wanted) {
+    if (entry.unsupported || !entry.restoreUses) continue;
+    if (!entry.slideId) {
+      notes.push("a slide with recorded image obligations has no durable identity — its uses were not restored");
+      continue;
+    }
+    const uses = Array.isArray(entry.intent.uses) ? entry.intent.uses : [];
+    if (!uses.length) continue;
+    const missing = uses.filter((use) => !usable.has(use?.assetId));
+    if (missing.length) {
+      notes.push(
+        `slide ${entry.slideId}: its image obligation names ${missing[0]?.assetId ?? "an asset"}, which this deck does not have — the use was not restored`,
+      );
+      continue;
+    }
+    // Shape-check before writing: the record came out of an untrusted file.
+    const parsed = validateSlideUses(uses, {
+      assetIds: readImageAssetManifest(deckDir).assets.map((a) => a.assetId),
+    });
+    if (!parsed.value) {
+      notes.push(`slide ${entry.slideId}: ${parsed.issues[0]?.message ?? "invalid image uses"} — not restored`);
+      continue;
+    }
+    try {
+      setSlideImageUses(deckDir, entry.slideId, parsed.value);
+      slides += 1;
+    } catch (err) {
+      notes.push(`slide ${entry.slideId}: ${err?.message ?? err} — its image uses were not restored`);
+    }
+  }
+  return { assets: added.length, slides, notes };
+}