studiograph 1.3.48-next.26 → 1.3.48-next.261

package/dist/core/artifact-frame-selectors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Artifact frame-selector roles — the single source of truth.
+ *
+ * Frames are detected by CSS selector in three distinct ROLES. They are
+ * deliberately not one constant: the stepper/export role includes bare
+ * `.slide` (defense-in-depth for decks authored before the
+ * `data-artifact-frame` contract), while the selection role excludes it so
+ * arbitrary `.slide`-classed elements never become selection frames.
+ *
+ *  - STEPPER: which elements page in fullscreen/present and in the
+ *    standalone export runtime. Honors the bundle's explicit
+ *    `display.controls.stepper.selector` override.
+ *  - EXPORT: which elements become per-frame screenshots/PDF pages in the
+ *    Playwright render path. Same chain as STEPPER (one frame vocabulary
+ *    across present + export).
+ *  - SELECTION: which ancestors count as the containing frame when
+ *    attributing an element selection in the editor canvas.
+ */
+export declare const FRAME_STEPPER_FALLBACK_SELECTOR = "[data-artifact-frame], [data-artifact-page], [data-artifact-slide], .slide, .page";
+export declare const FRAME_EXPORT_FALLBACK_SELECTOR = "[data-artifact-frame], [data-artifact-page], [data-artifact-slide], .slide, .page";
+export declare const FRAME_SELECTION_SELECTOR = "[data-artifact-frame],[data-artifact-page],[data-artifact-slide],.page";
+/** Resolve the stepper/export selector: a non-empty explicit override wins,
+ *  anything else (undefined, empty, whitespace) falls back to the shared
+ *  chain. Centralizes the trim/empty handling that previously differed
+ *  between call sites. */
+export declare function frameStepperSelector(explicit?: unknown): string;
+/**
+ * Fullscreen/present hide-show CSS for stepper frames, generated from the
+ * RESOLVED stepper selector. The stepper JS detects frames via this selector,
+ * so the CSS that hides inactive frames must target the same elements — a
+ * hardcoded `[data-artifact-frame]` rule next to a broader detection chain
+ * left `.slide`/`.page`/explicit-selector decks advancing their counter while
+ * every frame stayed visible.
+ *
+ * The active frame wins by appending `[data-studiograph-active-frame]` to each
+ * branch (one attribute of extra specificity beats the hide rule regardless of
+ * rule order, including id-bearing explicit selectors). Limitations, by
+ * design: top-level comma splitting only (commas inside `:is()`/`:not()` are
+ * not supported in stepper selectors), and branches containing CSS-invalid
+ * `<>{}` characters are dropped defensively.
+ */
+export declare function frameStepperVisibilityCss(selector: string, scope: string): string;

package/dist/core/artifact-frame-selectors.js

@@ -0,0 +1,65 @@
+/**
+ * Artifact frame-selector roles — the single source of truth.
+ *
+ * Frames are detected by CSS selector in three distinct ROLES. They are
+ * deliberately not one constant: the stepper/export role includes bare
+ * `.slide` (defense-in-depth for decks authored before the
+ * `data-artifact-frame` contract), while the selection role excludes it so
+ * arbitrary `.slide`-classed elements never become selection frames.
+ *
+ *  - STEPPER: which elements page in fullscreen/present and in the
+ *    standalone export runtime. Honors the bundle's explicit
+ *    `display.controls.stepper.selector` override.
+ *  - EXPORT: which elements become per-frame screenshots/PDF pages in the
+ *    Playwright render path. Same chain as STEPPER (one frame vocabulary
+ *    across present + export).
+ *  - SELECTION: which ancestors count as the containing frame when
+ *    attributing an element selection in the editor canvas.
+ */
+export const FRAME_STEPPER_FALLBACK_SELECTOR = '[data-artifact-frame], [data-artifact-page], [data-artifact-slide], .slide, .page';
+export const FRAME_EXPORT_FALLBACK_SELECTOR = FRAME_STEPPER_FALLBACK_SELECTOR;
+export const FRAME_SELECTION_SELECTOR = '[data-artifact-frame],[data-artifact-page],[data-artifact-slide],.page';
+/** Resolve the stepper/export selector: a non-empty explicit override wins,
+ *  anything else (undefined, empty, whitespace) falls back to the shared
+ *  chain. Centralizes the trim/empty handling that previously differed
+ *  between call sites. */
+export function frameStepperSelector(explicit) {
+    if (typeof explicit === 'string' && explicit.trim())
+        return explicit.trim();
+    return FRAME_STEPPER_FALLBACK_SELECTOR;
+}
+/**
+ * Fullscreen/present hide-show CSS for stepper frames, generated from the
+ * RESOLVED stepper selector. The stepper JS detects frames via this selector,
+ * so the CSS that hides inactive frames must target the same elements — a
+ * hardcoded `[data-artifact-frame]` rule next to a broader detection chain
+ * left `.slide`/`.page`/explicit-selector decks advancing their counter while
+ * every frame stayed visible.
+ *
+ * The active frame wins by appending `[data-studiograph-active-frame]` to each
+ * branch (one attribute of extra specificity beats the hide rule regardless of
+ * rule order, including id-bearing explicit selectors). Limitations, by
+ * design: top-level comma splitting only (commas inside `:is()`/`:not()` are
+ * not supported in stepper selectors), and branches containing CSS-invalid
+ * `<>{}` characters are dropped defensively.
+ */
+export function frameStepperVisibilityCss(selector, scope) {
+    const branches = selector
+        .split(',')
+        .map((branch) => branch.trim())
+        .filter((branch) => branch && !/[<>{}]/.test(branch));
+    if (branches.length === 0)
+        return '';
+    const hide = branches.map((branch) => `${scope} ${branch}`).join(',\n');
+    const show = branches.map((branch) => `${scope} ${branch}[data-studiograph-active-frame]`).join(',\n');
+    return `${hide} {
+  display: none !important;
+  position: absolute !important;
+  inset: 0 auto auto 0 !important;
+  margin: 0 !important;
+}
+${show} {
+  display: block !important;
+}`;
+}
+//# sourceMappingURL=artifact-frame-selectors.js.map

package/dist/core/artifact-frame-selectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-frame-selectors.js","sourceRoot":"","sources":["../../src/core/artifact-frame-selectors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,CAAC,MAAM,+BAA+B,GAC1C,mFAAmF,CAAC;AAEtF,MAAM,CAAC,MAAM,8BAA8B,GAAG,+BAA+B,CAAC;AAE9E,MAAM,CAAC,MAAM,wBAAwB,GACnC,wEAAwE,CAAC;AAE3E;;;0BAG0B;AAC1B,MAAM,UAAU,oBAAoB,CAAC,QAAkB;IACrD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE;QAAE,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC5E,OAAO,+BAA+B,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAgB,EAAE,KAAa;IACvE,MAAM,QAAQ,GAAG,QAAQ;SACtB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;SAC9B,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACxD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxE,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,MAAM,iCAAiC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvG,OAAO,GAAG,IAAI;;;;;;EAMd,IAAI;;EAEJ,CAAC;AACH,CAAC"}

package/dist/core/artifact-libraries.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared document-assembly helpers consumed by the one frame-document builder
+ * (artifact-frame-document.ts) and the server/web library loaders:
+ *   - the curated-library source types + their `<script>` tag emitter, and
+ *   - the broken-image placeholder runtime tag.
+ *
+ * These are host-agnostic (no frame/bundle shape), so they live apart from the
+ * builder to keep the dependency one-directional (builder → here) and give the
+ * library loaders a stable type home that doesn't pull in the whole builder.
+ */
+import type { ArtifactLibraryKey } from './artifact-frame-model.js';
+export type ArtifactLibrarySourceKey = ArtifactLibraryKey | 'threeCore';
+export type ArtifactLibrarySources = Partial<Record<ArtifactLibrarySourceKey, string>>;
+/** `<script>` tags that load the requested curated libraries (d3 / motion inline,
+ *  three via an async ESM blob import) and publish a `__…_LIBRARIES_READY__`
+ *  promise the user scripts await before running. */
+export declare function libraryTags(libraries: ArtifactLibraryKey[], sources?: ArtifactLibrarySources): string;
+/** A runtime `<script>` that replaces any broken `<img>` with an inline labeled
+ *  placeholder (Carbon image-error glyph + "Original asset is no longer
+ *  available"), preserving the image's footprint/placement so the layout doesn't
+ *  shift. Injected into every assembled document so a missing workspace asset
+ *  degrades gracefully in-canvas, in present, and in static exports alike. */
+export declare function brokenImageScriptTag(): string;

package/dist/core/artifact-libraries.js

@@ -0,0 +1,229 @@
+/**
+ * Shared document-assembly helpers consumed by the one frame-document builder
+ * (artifact-frame-document.ts) and the server/web library loaders:
+ *   - the curated-library source types + their `<script>` tag emitter, and
+ *   - the broken-image placeholder runtime tag.
+ *
+ * These are host-agnostic (no frame/bundle shape), so they live apart from the
+ * builder to keep the dependency one-directional (builder → here) and give the
+ * library loaders a stable type home that doesn't pull in the whole builder.
+ */
+import { encodeBase64, escapeScript } from './artifact-escape.js';
+/** `<script>` tags that load the requested curated libraries (d3 / motion inline,
+ *  three via an async ESM blob import) and publish a `__…_LIBRARIES_READY__`
+ *  promise the user scripts await before running. */
+export function libraryTags(libraries, sources = {}) {
+    if (libraries.length === 0)
+        return '';
+    const tags = [];
+    for (const library of libraries) {
+        if (library === 'd3' || library === 'motion') {
+            const source = sources[library];
+            if (!source)
+                continue;
+            tags.push(`<script data-artifact-library="${library}">\n${escapeScript(source)}\n</script>`);
+        }
+    }
+    const asyncInitializers = [];
+    if (libraries.includes('three') && sources.three) {
+        asyncInitializers.push(`
+      const decodeLibrarySource = (base64) => {
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+        return new TextDecoder().decode(bytes);
+      };
+      const threeSource = decodeLibrarySource(${JSON.stringify(encodeBase64(sources.three))});
+      const threeCoreSource = ${sources.threeCore ? `decodeLibrarySource(${JSON.stringify(encodeBase64(sources.threeCore))})` : "''"};
+      const threeCoreUrl = threeCoreSource
+        ? URL.createObjectURL(new Blob([threeCoreSource], { type: 'text/javascript' }))
+        : null;
+      const threeModuleSource = threeCoreUrl
+        ? threeSource.replace(/from\\s*(['"])\\.\\/three\\.core\\.min\\.js\\1/g, 'from ' + JSON.stringify(threeCoreUrl))
+        : threeSource;
+      const threeUrl = URL.createObjectURL(new Blob([threeModuleSource], { type: 'text/javascript' }));
+      try {
+        window.THREE = await import(threeUrl);
+      } finally {
+        URL.revokeObjectURL(threeUrl);
+        if (threeCoreUrl) URL.revokeObjectURL(threeCoreUrl);
+      }
+    `);
+    }
+    tags.push(`<script data-artifact-libraries-ready>
+window.__STUDIOGRAPH_ARTIFACT_LIBRARIES__ = ${JSON.stringify(libraries)};
+window.__STUDIOGRAPH_ARTIFACT_LIBRARIES_READY__ = (async () => {
+${asyncInitializers.join('\n')}
+  return true;
+})().catch((error) => {
+  console.error('Artifact library load failed', error);
+  throw error;
+});
+</script>`);
+    return tags.join('\n');
+}
+/** A runtime `<script>` that replaces any broken `<img>` with an inline labeled
+ *  placeholder (Carbon image-error glyph + "Original asset is no longer
+ *  available"), preserving the image's footprint/placement so the layout doesn't
+ *  shift. Injected into every assembled document so a missing workspace asset
+ *  degrades gracefully in-canvas, in present, and in static exports alike. */
+export function brokenImageScriptTag() {
+    const js = `
+(() => {
+  var MESSAGE = 'Original asset is no longer available';
+  var GLYPH = [
+    'M16,30H8a2,2,0,0,1-2-2V4A2,2,0,0,1,8,2h10a1,1,0,0,1,.71.29l5,5A1,1,0,0,1,24,8v6H22V9H17a1,1,0,0,1-1-1V4H8V28h8Z',
+    'M24.5,29A2.5,2.5,0,1,1,27,26.5,2.5,2.5,0,0,1,24.5,29Zm0-3.5a1,1,0,1,0,1,1A1,1,0,0,0,24.5,25.5Z',
+    'M24.5,23a1,1,0,0,1-1-1V21a2.5,2.5,0,1,0-2.5-2.5,1,1,0,0,1-2,0A4.5,4.5,0,1,1,25,22.79V22A1,1,0,0,1,24.5,23Z'
+  ];
+  var NS = 'http://www.w3.org/2000/svg';
+  function replace(img) {
+    try {
+      if (!img || img.tagName !== 'IMG' || img.hasAttribute('data-sg-broken')) return;
+      if (img.complete && img.naturalWidth > 0) return; // recovered (e.g. a retry swapped src)
+      img.setAttribute('data-sg-broken', '');
+      var cs = window.getComputedStyle ? getComputedStyle(img) : null;
+      var rect = img.getBoundingClientRect();
+      // getComputedStyle returns a USED px length ("695px") only for a laid-out
+      // element. Inside a display:none subtree — an INACTIVE FRAME in present /
+      // fullscreen mode — it returns the COMPUTED value verbatim ("100%"),
+      // which is not a pixel box; parseFloat("100%") === 100 would bake a bogus
+      // 100x100 footprint (the small glyph-only box seen in present mode). So
+      // accept a computed length ONLY when it is in px; it still dodges the
+      // collapsed broken-img rendered box and the "numeric width attr that CSS
+      // overrides" trap. Then a unitless pixel attribute, the rendered box, a
+      // default. A percentage means the image fills its slot — mirrored below.
+      var pxLen = function (cssVal) {
+        if (typeof cssVal === 'string' && /px$/.test(cssVal)) {
+          var c = parseFloat(cssVal);
+          if (isFinite(c) && c > 1) return Math.round(c);
+        }
+        return null;
+      };
+      var dim = function (cssVal, attr, rectVal, dflt) {
+        var c = pxLen(cssVal);
+        if (c != null) return c;
+        if (attr && /^\\s*\\d+(?:\\.\\d+)?\\s*$/.test(attr)) return parseFloat(attr);
+        if (rectVal > 1) return Math.round(rectVal);
+        return dflt;
+      };
+      var w = dim(cs && cs.width, img.getAttribute('width'), rect.width, 240);
+      var h = dim(cs && cs.height, img.getAttribute('height'), rect.height, 160);
+      // Fill case: the computed size is a percentage we could NOT resolve to px
+      // (the img lives in a display:none present-mode frame). Mirror the
+      // percentage onto the placeholder so it fills the same slot once the frame
+      // is revealed + self-fit-scaled, instead of the default box. w/h keep
+      // their defaults purely to select the large (glyph+label) tier, since a
+      // fill image is content-sized.
+      var fillW = (pxLen(cs && cs.width) == null && cs && /%$/.test(cs.width)) ? cs.width : null;
+      var fillH = (pxLen(cs && cs.height) == null && cs && /%$/.test(cs.height)) ? cs.height : null;
+      var radius = (cs && cs.borderRadius && cs.borderRadius !== '0px') ? cs.borderRadius : '4px';
+      // Degrade by available footprint so a tiny broken embed stays tiny instead
+      // of blowing out the layout with text it can't hold: large -> glyph +
+      // label; small -> glyph only; tiny -> just the box. The aria-label always
+      // carries the full message regardless of what is drawn.
+      var minDim = w < h ? w : h;
+      var showGlyph = minDim >= 40;
+      var showText = w >= 130 && h >= 70;
+      var pad = showText ? 12 : (showGlyph ? 6 : 0);
+      // Block-level images (incl. flex/grid items) get a block-level flex box so
+      // full-width layout and margin:auto centering survive; inline images stay
+      // inline-flex.
+      var disp = (cs && /^inline/.test(cs.display)) ? 'inline-flex' : 'flex';
+      var note = document.createElement('div');
+      note.setAttribute('data-sg-broken-image', '');
+      note.setAttribute('role', 'img');
+      var alt = (img.getAttribute('alt') || '').trim();
+      note.setAttribute('aria-label', alt ? alt + ' \\u2014 ' + MESSAGE : MESSAGE);
+      // width holds the footprint; the text tier uses min-height (not a fixed
+      // height) so the label can grow rather than clip, while the glyph/box
+      // tiers keep the exact footprint. overflow:hidden only rounds the corners
+      // (the grown/exact height always fits whatever is drawn).
+      var widthCss = 'width:' + (fillW || (w + 'px')) + ';';
+      var heightCss = fillH ? 'height:' + fillH + ';' : (showText ? 'min-height:' + h + 'px;' : 'height:' + h + 'px;');
+      note.style.cssText = 'box-sizing:border-box;display:' + disp + ';flex-direction:column;align-items:center;justify-content:center;gap:8px;' + widthCss + heightCss + 'padding:' + pad + 'px;background:rgba(128,128,128,0.12);border:1px solid rgba(128,128,128,0.25);border-radius:' + radius + ';color:rgba(120,120,120,0.95);font:500 13px/1.35 system-ui,-apple-system,sans-serif;text-align:center;overflow:hidden';
+      // Preserve the image's placement so a broken absolutely-positioned,
+      // floated, centered, or grid/flex-placed image keeps its slot instead of
+      // dropping into normal flow and shifting the whole artifact.
+      if (cs) {
+        var keep = ['position','top','right','bottom','left','transform','transformOrigin','float','marginTop','marginRight','marginBottom','marginLeft','verticalAlign','alignSelf','justifySelf','gridColumn','gridRow'];
+        for (var k = 0; k < keep.length; k++) {
+          var val = cs[keep[k]];
+          if (val && val !== 'auto' && val !== 'normal' && val !== 'static' && val !== 'none' && val !== '0px') {
+            try { note.style[keep[k]] = val; } catch (e) {}
+          }
+        }
+      }
+      if (showGlyph) {
+        var svg = document.createElementNS(NS, 'svg');
+        svg.setAttribute('viewBox', '0 0 32 32');
+        svg.setAttribute('width', '20');
+        svg.setAttribute('height', '20');
+        svg.setAttribute('fill', 'currentColor');
+        svg.setAttribute('aria-hidden', 'true');
+        svg.style.cssText = 'flex:none;opacity:0.85';
+        for (var i = 0; i < GLYPH.length; i++) {
+          var p = document.createElementNS(NS, 'path');
+          p.setAttribute('d', GLYPH[i]);
+          svg.appendChild(p);
+        }
+        note.appendChild(svg);
+      }
+      if (showText) {
+        var label = document.createElement('span');
+        label.textContent = MESSAGE;
+        label.style.maxWidth = '100%';
+        note.appendChild(label);
+      }
+      var prevDisplay = img.style.display;
+      img.style.display = 'none';
+      if (img.parentNode) img.parentNode.insertBefore(note, img.nextSibling);
+      // Self-heal: if the same <img> later loads (an artifact's own onerror
+      // retry swapped src to a working URL), drop the placeholder and restore
+      // the image to its PRIOR inline display rather than leave a valid image
+      // hidden behind the note.
+      img.addEventListener('load', function onload() {
+        if (img.naturalWidth > 0) {
+          img.removeEventListener('load', onload);
+          if (note.parentNode) note.parentNode.removeChild(note);
+          img.style.display = prevDisplay;
+          img.removeAttribute('data-sg-broken');
+        }
+      });
+    } catch (e) {}
+  }
+  // Schedule on the window receiver (a detached rAF call can throw in strict
+  // contexts) and never let scheduling throw out of the capture listener.
+  function defer(fn) {
+    try { if (window.requestAnimationFrame) { window.requestAnimationFrame(fn); return; } } catch (e) {}
+    try { window.setTimeout(fn, 0); } catch (e) {}
+  }
+  document.addEventListener('error', function (e) {
+    var t = e && e.target;
+    // Defer a frame so an artifact's own onerror retry can swap src first; the
+    // load-time sweep below still inserts the note synchronously before a
+    // headless capture (which waits for load + rAF), so the export never races.
+    if (t && t.tagName === 'IMG') defer(function () { replace(t); });
+  }, true);
+  // Sweep images already broken before the listener registered (cached 404s, or
+  // the standalone tag running at body end after parse).
+  function sweep() {
+    try {
+      var imgs = document.querySelectorAll('img');
+      for (var i = 0; i < imgs.length; i++) {
+        var im = imgs[i];
+        if (im.complete && im.naturalWidth === 0 && im.getAttribute('src')) replace(im);
+      }
+    } catch (e) {}
+  }
+  // Run once now — catches images already parsed + broken when this tag
+  // executes (the standalone tag sits at body end, after the markup), so a
+  // user/library script running next sees the placeholder, not the raw broken
+  // img. Run again on load for cached 404s that completed before the capture
+  // listener registered.
+  sweep();
+  window.addEventListener('load', sweep);
+})();`;
+    return `<script data-artifact-broken-image>${escapeScript(js)}</script>`;
+}
+//# sourceMappingURL=artifact-libraries.js.map

package/dist/core/artifact-libraries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-libraries.js","sourceRoot":"","sources":["../../src/core/artifact-libraries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAKlE;;qDAEqD;AACrD,MAAM,UAAU,WAAW,CAAC,SAA+B,EAAE,UAAkC,EAAE;IAC/F,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEtC,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;QAChC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;YAChC,IAAI,CAAC,MAAM;gBAAE,SAAS;YACtB,IAAI,CAAC,IAAI,CAAC,kCAAkC,OAAO,OAAO,YAAY,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;IAED,MAAM,iBAAiB,GAAa,EAAE,CAAC;IACvC,IAAI,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QACjD,iBAAiB,CAAC,IAAI,CAAC;;;;;;;gDAOqB,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gCAC3D,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI;;;;;;;;;;;;;;KAc/H,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,IAAI,CAAC;8CACkC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC;;EAErE,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;UAMpB,CAAC,CAAC;IAEV,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED;;;;8EAI8E;AAC9E,MAAM,UAAU,oBAAoB;IAClC,MAAM,EAAE,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA2JP,CAAC;IACL,OAAO,sCAAsC,YAAY,CAAC,EAAE,CAAC,WAAW,CAAC;AAC3E,CAAC"}

package/dist/core/artifact-manifest.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Frame manifest (P4.2) — a cheap, browser-free structural read of an artifact.
+ *
+ * `read_artifact` returns the whole bundle (every frame's full HTML — heavy);
+ * `inspect_artifact` renders pixels with Playwright. Between them sits a gap: an
+ * agent that just wants to answer "which frame is the pricing slide?" so it can
+ * target a `patch_artifact` had no light, always-available way to read the
+ * structure. The manifest fills it — per-frame index / layout / title / geometry
+ * plus a short `keyText` snippet pulled straight from the source markup (no
+ * browser), and the OCC `hash` so it doubles as the read-before-patch step.
+ *
+ * `buildArtifactManifest` is THE structural builder: the `get_artifact_manifest`
+ * tool and `inspect_artifact`'s browser-free degraded fallback both go through
+ * it, so the two structural reads can't drift (they did before, as separate
+ * code). Pure — no IO, no browser, no agent/MCP coupling.
+ */
+import type { ArtifactBundle, ArtifactFrameGeometry, ArtifactFrameLayout, ArtifactFrameOrigin } from './artifact-frame-model.js';
+export interface ArtifactManifestFrame {
+    index: number;
+    id: string;
+    title?: string;
+    /** The frame's layout — its structural role (slides | pages | artboard | app | whiteboard). */
+    layout: ArtifactFrameLayout;
+    /** Every PERSISTED frame is `authored`; `derived` is a render-only projection
+     *  (paginated document pages) and never appears in a stored bundle. Surfaced
+     *  so the manifest speaks the same provenance vocabulary as the render path. */
+    origin: ArtifactFrameOrigin;
+    geometry: ArtifactFrameGeometry;
+    /** A short plain-text snippet extracted from the frame's source markup so the
+     *  agent can recognize the frame without pulling its full content. */
+    keyText: string;
+    contentChars: number;
+    /** The frame's FULL HTML content — included ONLY for the frame named by
+     *  `buildArtifactManifest`'s `frameId` option (the targeted single-frame read
+     *  that precedes a `patch_frame_content`). Omitted for every other frame. */
+    content?: string;
+}
+export interface ArtifactManifest {
+    artifactId: string;
+    title: string;
+    frameCount: number;
+    frames: ArtifactManifestFrame[];
+}
+export interface BuildManifestOptions {
+    /** Include this one frame's full `content` in its manifest entry. Throws if no
+     *  frame has this id (clear error listing the existing ids) — same
+     *  fail-loud-on-unknown-frame contract as the patch ops. */
+    frameId?: string;
+}
+/**
+ * Extract a short, plain-text recognizer from a frame's HTML source — NO browser
+ * (regex strip, not rendered innerText). Drops script/style content, unwraps
+ * tags, decodes a few common entities, collapses whitespace, and caps the result.
+ * Text is kept in source order (a slide's heading naturally leads), so the
+ * snippet is predictable. Returns '' for empty/markup-only frames.
+ */
+export declare function extractFrameKeyText(content: string, max?: number): string;
+/**
+ * Build the structural manifest for a (parsed, validated) bundle. Pure: declared
+ * geometry from the model, `keyText` from the source markup — never a browser.
+ * The OCC `hash` is NOT added here (the builder has no body string); the reading
+ * tool wraps the manifest with the hash it computed from the body it read.
+ */
+export declare function buildArtifactManifest(bundle: ArtifactBundle, opts?: BuildManifestOptions): ArtifactManifest;

package/dist/core/artifact-manifest.js

@@ -0,0 +1,88 @@
+/**
+ * Frame manifest (P4.2) — a cheap, browser-free structural read of an artifact.
+ *
+ * `read_artifact` returns the whole bundle (every frame's full HTML — heavy);
+ * `inspect_artifact` renders pixels with Playwright. Between them sits a gap: an
+ * agent that just wants to answer "which frame is the pricing slide?" so it can
+ * target a `patch_artifact` had no light, always-available way to read the
+ * structure. The manifest fills it — per-frame index / layout / title / geometry
+ * plus a short `keyText` snippet pulled straight from the source markup (no
+ * browser), and the OCC `hash` so it doubles as the read-before-patch step.
+ *
+ * `buildArtifactManifest` is THE structural builder: the `get_artifact_manifest`
+ * tool and `inspect_artifact`'s browser-free degraded fallback both go through
+ * it, so the two structural reads can't drift (they did before, as separate
+ * code). Pure — no IO, no browser, no agent/MCP coupling.
+ */
+const KEY_TEXT_MAX = 160;
+/** keyText needs only a short snippet, so the strip regexes scan at most this
+ *  prefix of a frame's content. Without the bound, a pathological frame (e.g.
+ *  megabytes of unbalanced `<`) makes `/<[^>]+>/` and the script/style strip
+ *  backtrack quadratically and stall the event loop — and the manifest runs this
+ *  on EVERY frame. 4000 source chars comfortably yields a 160-char text snippet. */
+const KEY_TEXT_SCAN_LIMIT = 4000;
+/**
+ * Extract a short, plain-text recognizer from a frame's HTML source — NO browser
+ * (regex strip, not rendered innerText). Drops script/style content, unwraps
+ * tags, decodes a few common entities, collapses whitespace, and caps the result.
+ * Text is kept in source order (a slide's heading naturally leads), so the
+ * snippet is predictable. Returns '' for empty/markup-only frames.
+ */
+export function extractFrameKeyText(content, max = KEY_TEXT_MAX) {
+    if (!content)
+        return '';
+    // Bound the regex work to a prefix (see KEY_TEXT_SCAN_LIMIT) so a huge or
+    // malformed frame body can't stall the event loop.
+    const scan = content.length > KEY_TEXT_SCAN_LIMIT ? content.slice(0, KEY_TEXT_SCAN_LIMIT) : content;
+    // Strip script/style wholesale — their bodies are code, not readable text.
+    // First paired open→close, then any UNCLOSED/cut-off open tag to end-of-scan
+    // (a malformed frame, or a long <script> whose close sits past the scan limit),
+    // so code never leaks into the snippet.
+    const withoutCode = scan
+        .replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, ' ')
+        .replace(/<(script|style)\b[^>]*>[\s\S]*$/i, ' ');
+    const text = decodeBasicEntities(withoutCode.replace(/<[^>]+>/g, ' '))
+        .replace(/\s+/g, ' ')
+        .trim();
+    return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
+}
+function decodeBasicEntities(s) {
+    // &amp; LAST so a doubly-escaped source like "&amp;lt;" decodes to the literal
+    // "&lt;" (HTML-correct) rather than being double-decoded to "<".
+    return s
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+/**
+ * Build the structural manifest for a (parsed, validated) bundle. Pure: declared
+ * geometry from the model, `keyText` from the source markup — never a browser.
+ * The OCC `hash` is NOT added here (the builder has no body string); the reading
+ * tool wraps the manifest with the hash it computed from the body it read.
+ */
+export function buildArtifactManifest(bundle, opts = {}) {
+    if (opts.frameId !== undefined && !bundle.frames.some((f) => f.id === opts.frameId)) {
+        const ids = bundle.frames.map((f) => f.id).join(', ');
+        throw new Error(`No frame with id "${opts.frameId}". Existing frame ids: ${ids}.`);
+    }
+    return {
+        artifactId: bundle.artifactId,
+        title: bundle.title,
+        frameCount: bundle.frames.length,
+        frames: bundle.frames.map((frame, index) => ({
+            index,
+            id: frame.id,
+            ...(frame.title ? { title: frame.title } : {}),
+            layout: frame.layout,
+            origin: 'authored',
+            geometry: { ...frame.geometry },
+            keyText: extractFrameKeyText(frame.content),
+            contentChars: frame.content.length,
+            ...(opts.frameId === frame.id ? { content: frame.content } : {}),
+        })),
+    };
+}
+//# sourceMappingURL=artifact-manifest.js.map

package/dist/core/artifact-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-manifest.js","sourceRoot":"","sources":["../../src/core/artifact-manifest.ts"],"names":[],"mappings":"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"}

package/dist/core/artifact-paged-css.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Sanitize author CSS before it is handed to Paged.js's `previewer.preview()`.
+ *
+ * WHY: Paged.js preprocesses every stylesheet it is given and calls
+ * `new URL(value)` — with NO base argument — on each `url()` token. A scheme-less
+ * / root-relative value (`url('/api/assets/x.otf')`, `url('./logo.png')`, a bare
+ * `url(foo.png)`, a protocol-relative `url('//cdn/x')`, or a fragment
+ * `url('#g')`) makes `new URL()` throw `TypeError: Failed to construct 'URL'`
+ * synchronously, which aborts the ENTIRE pagination run. The catch in the
+ * pagination bootstrap then falls back to an un-paginated, `overflow:hidden`,
+ * margin-less single page — the user-visible "single page, missing margins" bug.
+ *
+ * FIX: neutralize every NON-absolute `url()` token to `url(about:blank)` in the
+ * copy handed to Paged.js. We do NOT absolutize: this Paged-fed copy exists for
+ * `@page` / break / named-page / running-element rules, and the body content's
+ * fonts/backgrounds paint from the head `<style>` sheet (a separate reader that
+ * keeps the real `url()`s) — so neutralizing here is visually invisible for the
+ * common case. (Empirically verified: a same-family `@font-face{src:url(about:blank)}`
+ * does NOT shadow the valid head face — text keeps its font.) ACCEPTED LIMITATION:
+ * an image that lives ONLY in the Paged-generated structure and is styled by a rule
+ * only Paged.js applies — a relative `url()` background in an `@page` margin-box
+ * (`@bottom-right { background: url('./x.png') }`) or a `position:running()` element —
+ * is blanked here (the head sheet's `@page` rules aren't honored by native CSS). An
+ * *absolute* url() in those spots still paints; an `<img>`-based letterhead logo is
+ * untouched (the scanner only rewrites CSS `url()`, never element `src`). Net: a
+ * working multi-page document with one missing relative margin-box image, vs. the
+ * prior behavior where that same CSS crashed pagination entirely. This is why the
+ * decision is neutralize-not-absolutize (no base-URL coupling); see the plan's D2.
+ *
+ * "Absolute" = exactly what `new URL(value)` (no base) accepts without throwing:
+ * a value carrying a URI scheme (`data:`, `blob:`, `http:`, `https:`, `file:`,
+ * `about:`, …). Anything else throws in Paged.js and is neutralized here, so this
+ * helper's predicate mirrors the crash predicate one-to-one.
+ *
+ * The parser is a real `url()` token scanner (not a regex): it skips CSS comments
+ * and string literals so it never matches `url(` inside them, honors `\` escapes
+ * inside the value, and passes absolute tokens through VERBATIM so a `data:` URI
+ * containing parens is never corrupted.
+ *
+ * Out of scope: a `url(` token whose FUNCTION NAME is spelled with an identifier
+ * escape (`u\72l(...)`) is not recognized here, so a relative ref written that way
+ * would still reach Paged.js. No author or tool emits that; if it ever happens the
+ * pagination-failure backstop (the bootstrap catch → host "couldn't paginate" hint)
+ * makes it observable rather than a silent clip — not a silent crash.
+ *
+ * RUNTIME TWIN: the pagination bootstrap can't import this module — it runs inside
+ * a sandboxed iframe. It injects {@link SANITIZE_CSS_URLS_TWIN} (a hand-mirror of
+ * this function, written with `String.raw` so no bundler helper like esbuild's
+ * `__name` and no escaping artifact can leak into the browser copy). The two are
+ * pinned together by `artifact-paged-css.parity.test.ts`, which runs both over a
+ * fixture set and asserts identical output — so a change to one that isn't
+ * mirrored in the other fails CI.
+ */
+export declare function sanitizeCssUrlsForPagination(css: string): string;
+/**
+ * The runtime twin of {@link sanitizeCssUrlsForPagination}, injected verbatim into
+ * the pagination bootstrap (which runs inside the sandboxed iframe and can't import
+ * this module). It defines a `sanitizeCssUrlsForPagination(css)` function with
+ * behavior identical to the exported helper above. Written with `String.raw` so
+ * regex escapes (`\s`, `\\`) and the helper's own logic survive untouched — and so
+ * no bundler-injected helper (esbuild `__name`, etc.) can leak in. Kept in lock-step
+ * with the canonical helper by the parity test.
+ */
+export declare const SANITIZE_CSS_URLS_TWIN: string;