studiograph 1.3.48-next.28 → 1.3.48-next.280

package/dist/core/artifact-patch.js

@@ -0,0 +1,327 @@
+/**
+ * Frame-addressable artifact patching (P4.1).
+ *
+ * `applyArtifactPatch` is the pure, surface-neutral core that lets an agent edit
+ * ONE frame (or one shared file / the token map) of a v2 artifact without
+ * re-emitting the whole bundle. Both `patch_artifact` surfaces — the in-app chat
+ * tool and the MCP tool — load the current bundle, call this to apply an ordered
+ * op list to a working copy, then hand the result to {@link
+ * (ArtifactStore:class).write} (the single write path, which re-validates as the
+ * authority and enforces the same OCC as a `create_artifact` update).
+ *
+ * The win is addressing, not storage: the bundle is still persisted whole, but
+ * the AGENT names "frame 7" instead of re-sending the deck. `patch_frame_content`
+ * is bounded to a single frame's text, so a substring edit can never corrupt the
+ * JSON envelope or a sibling frame — the failure mode that made `patch_entity` on
+ * an artifact body unsafe.
+ *
+ * This module owns op SHAPE + ADDRESSING validation only (unknown frame id, no
+ * substring match, non-permutation reorder, unsafe path, ...). It does NOT run
+ * the whole-bundle {@link validateArtifactBundle} — that stays the store's job,
+ * the single validation authority, so geometry/library/byte-cap rules are
+ * checked in exactly one place. Op input is accepted untyped (the tool boundary
+ * passes it through, mirroring how the `bundle` param is `unknown`) and parsed
+ * here, so the zod/typebox schemas never drift from the real contract.
+ */
+import { ARTIFACT_FRAME_LAYOUTS, ARTIFACT_DISPLAY_BACKGROUNDS, normalizeBackgroundValue, } from './artifact-frame-model.js';
+/** Op-level failure — a bad addressing/shape problem the agent can fix and
+ *  retry (unknown frame id, zero/ambiguous substring match, non-permutation
+ *  reorder, malformed op). Surface tools map this to a recoverable tool error,
+ *  never a thrown turn. Distinct from the store's whole-bundle
+ *  `ArtifactWriteError('invalid')`. */
+export class ArtifactPatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ArtifactPatchError';
+    }
+}
+export const ARTIFACT_PATCH_OP_KINDS = [
+    'set_frame_content',
+    'patch_frame_content',
+    'set_frame_meta',
+    'add_frame',
+    'remove_frame',
+    'reorder_frames',
+    'set_shared_file',
+    'remove_shared_file',
+    'set_tokens',
+];
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** Deep clone via JSON round-trip — the bundle is pure JSON (frames, shared
+ *  files, tokens are all strings/numbers), so this is exact and keeps the input
+ *  bundle untouched (ops mutate the copy). */
+function cloneBundle(bundle) {
+    return JSON.parse(JSON.stringify(bundle));
+}
+function frameLabel(frame) {
+    return frame.title ? `"${frame.title}" (${frame.id})` : frame.id;
+}
+function requireString(value, field, opKind) {
+    if (typeof value !== 'string') {
+        throw new ArtifactPatchError(`${opKind}.${field} must be a string`);
+    }
+    return value;
+}
+function findFrame(bundle, frameId, opKind) {
+    if (typeof frameId !== 'string' || !frameId.trim()) {
+        throw new ArtifactPatchError(`${opKind}.frameId must be a non-empty string`);
+    }
+    const frame = bundle.frames.find((f) => f.id === frameId);
+    if (!frame) {
+        const ids = bundle.frames.map((f) => f.id).join(', ');
+        throw new ArtifactPatchError(`${opKind}: no frame with id "${frameId}". Existing frame ids: ${ids}.`);
+    }
+    return frame;
+}
+/** Apply one op to the working bundle. Records touched/removed ids and the
+ *  reorder flag back through `acc`. Throws {@link ArtifactPatchError} on any
+ *  addressing/shape problem. */
+function applyOp(bundle, rawOp, index, acc) {
+    if (!isRecord(rawOp)) {
+        throw new ArtifactPatchError(`ops[${index}] must be an object`);
+    }
+    const kind = rawOp.op;
+    if (typeof kind !== 'string' || !ARTIFACT_PATCH_OP_KINDS.includes(kind)) {
+        throw new ArtifactPatchError(`ops[${index}].op must be one of: ${ARTIFACT_PATCH_OP_KINDS.join(', ')} (got ${JSON.stringify(rawOp.op)})`);
+    }
+    switch (kind) {
+        case 'set_frame_content': {
+            const frame = findFrame(bundle, rawOp.frameId, kind);
+            frame.content = requireString(rawOp.content, 'content', kind);
+            acc.changed.add(frame.id);
+            return;
+        }
+        case 'patch_frame_content': {
+            const frame = findFrame(bundle, rawOp.frameId, kind);
+            const find = requireString(rawOp.find, 'find', kind);
+            const replace = requireString(rawOp.replace, 'replace', kind);
+            if (find === '') {
+                throw new ArtifactPatchError(`${kind}: \`find\` must be a non-empty string`);
+            }
+            if (find === replace) {
+                throw new ArtifactPatchError(`${kind}: \`find\` and \`replace\` are identical — nothing to do on frame ${frameLabel(frame)}`);
+            }
+            const occurrences = countOccurrences(frame.content, find);
+            if (occurrences === 0) {
+                throw new ArtifactPatchError(`${kind}: \`find\` substring not present in frame ${frameLabel(frame)}.`);
+            }
+            if (rawOp.expectedCount !== undefined) {
+                if (typeof rawOp.expectedCount !== 'number' || !Number.isInteger(rawOp.expectedCount) || rawOp.expectedCount < 1) {
+                    throw new ArtifactPatchError(`${kind}.expectedCount must be a positive integer`);
+                }
+                if (rawOp.expectedCount !== occurrences) {
+                    throw new ArtifactPatchError(`${kind}: expected ${rawOp.expectedCount} occurrence(s) of \`find\` in frame ${frameLabel(frame)}, found ${occurrences}. Refine \`find\` or fix expectedCount so you don't edit the wrong text.`);
+                }
+            }
+            // Replace ALL occurrences (parity with patch_entity); literal, not regex.
+            frame.content = frame.content.split(find).join(replace);
+            acc.changed.add(frame.id);
+            return;
+        }
+        case 'set_frame_meta': {
+            const frame = findFrame(bundle, rawOp.frameId, kind);
+            let touched = false;
+            if (rawOp.title !== undefined) {
+                const title = requireString(rawOp.title, 'title', kind);
+                // Empty/whitespace title CLEARS it (falls back to "Frame N" chrome);
+                // a non-empty value sets it (the store re-validates length).
+                if (title.trim() === '')
+                    delete frame.title;
+                else
+                    frame.title = title.trim();
+                touched = true;
+            }
+            if (rawOp.layout !== undefined) {
+                if (typeof rawOp.layout !== 'string' || !ARTIFACT_FRAME_LAYOUTS.includes(rawOp.layout)) {
+                    throw new ArtifactPatchError(`${kind}.layout must be one of: ${ARTIFACT_FRAME_LAYOUTS.join(', ')}`);
+                }
+                frame.layout = rawOp.layout;
+                touched = true;
+            }
+            if (rawOp.geometry !== undefined) {
+                // geometry is REPLACED wholesale, not merged — require both fields so a
+                // `{ width }`-only op fails with a clear message here instead of a
+                // low-level "geometry.height must be…" from the store after it has
+                // silently dropped the existing height. Numeric bounds stay the store's
+                // whole-bundle validate (single authority for the geometry rules).
+                if (!isRecord(rawOp.geometry) || rawOp.geometry.width === undefined || rawOp.geometry.height === undefined) {
+                    throw new ArtifactPatchError(`${kind}.geometry must be a full { width, height } object (it replaces the frame's geometry, it does not merge)`);
+                }
+                frame.geometry = rawOp.geometry;
+                touched = true;
+            }
+            if (rawOp.background !== undefined) {
+                const bg = rawOp.background;
+                // Empty string clears the per-frame override (inherits display default).
+                if (bg === '' || bg === null) {
+                    delete frame.background;
+                }
+                else {
+                    // Same grammar as create_artifact: a keyword OR a safe custom CSS
+                    // color/gradient (shared normalizer — set_frame_meta used to reject
+                    // custom colors that create accepted, forcing a `transparent` workaround).
+                    const normalized = normalizeBackgroundValue(bg);
+                    if (normalized === null) {
+                        throw new ArtifactPatchError(`${kind}.background must be ${ARTIFACT_DISPLAY_BACKGROUNDS.join(' / ')}, a safe CSS color/gradient, or "" to clear`);
+                    }
+                    frame.background = normalized;
+                }
+                touched = true;
+            }
+            // `pages`-document letterhead/pagination frame fields — pageNumbers,
+            // furniture, pageMargins. Each is REPLACED wholesale by a provided object
+            // (merging a single sub-field is not expressible — re-send the field), or
+            // CLEARED by `null`/`''` (the field is removed → reverts to the platform
+            // default). Just like geometry, the value's shape/bounds AND the
+            // `pages`-only rule are enforced by the store's whole-bundle
+            // validateArtifactBundle (the single authority) — not re-checked here, so
+            // an invalid value or a non-`pages` frame fails the whole patch (fail-closed,
+            // no partial application).
+            for (const key of ['pageNumbers', 'furniture', 'pageMargins']) {
+                if (rawOp[key] !== undefined) {
+                    if (rawOp[key] === '' || rawOp[key] === null)
+                        delete frame[key];
+                    else
+                        frame[key] = rawOp[key];
+                    touched = true;
+                }
+            }
+            if (!touched) {
+                throw new ArtifactPatchError(`${kind}: nothing to change — pass at least one of title, layout, geometry, background, pageNumbers, furniture, pageMargins.`);
+            }
+            acc.changed.add(frame.id);
+            return;
+        }
+        case 'add_frame': {
+            if (!isRecord(rawOp.frame)) {
+                throw new ArtifactPatchError(`${kind}.frame must be a frame object ({ id, layout, geometry, content, ... })`);
+            }
+            const newId = rawOp.frame.id;
+            if (typeof newId !== 'string' || !newId.trim()) {
+                throw new ArtifactPatchError(`${kind}.frame.id must be a non-empty string`);
+            }
+            if (bundle.frames.some((f) => f.id === newId)) {
+                throw new ArtifactPatchError(`${kind}: a frame with id "${newId}" already exists. Pick a unique id.`);
+            }
+            // `content` must be a string up front: a later op in this batch (e.g.
+            // patch_frame_content on the new frame) would otherwise hit a generic
+            // TypeError instead of a recoverable ArtifactPatchError. The store's
+            // whole-bundle validate enforces the rest (layout enum, geometry bounds).
+            if (typeof rawOp.frame.content !== 'string') {
+                throw new ArtifactPatchError(`${kind}.frame.content must be a string`);
+            }
+            const frame = rawOp.frame;
+            let at = bundle.frames.length;
+            if (rawOp.atIndex !== undefined) {
+                if (typeof rawOp.atIndex !== 'number' || !Number.isInteger(rawOp.atIndex) || rawOp.atIndex < 0) {
+                    throw new ArtifactPatchError(`${kind}.atIndex must be a non-negative integer`);
+                }
+                at = Math.min(rawOp.atIndex, bundle.frames.length);
+            }
+            bundle.frames.splice(at, 0, frame);
+            acc.changed.add(newId);
+            // If this id was removed earlier in the same batch, it's a replacement,
+            // not a removal — don't report it as both removed and changed.
+            acc.removed.delete(newId);
+            return;
+        }
+        case 'remove_frame': {
+            const frame = findFrame(bundle, rawOp.frameId, kind);
+            if (bundle.frames.length === 1) {
+                throw new ArtifactPatchError(`${kind}: cannot remove the only frame — an artifact must have at least one frame. Replace its content instead, or delete the whole artifact entry.`);
+            }
+            bundle.frames = bundle.frames.filter((f) => f.id !== frame.id);
+            acc.removed.add(frame.id);
+            // A frame removed earlier in the batch should not also count as "changed".
+            acc.changed.delete(frame.id);
+            return;
+        }
+        case 'reorder_frames': {
+            if (!Array.isArray(rawOp.order) || rawOp.order.some((id) => typeof id !== 'string')) {
+                throw new ArtifactPatchError(`${kind}.order must be an array of frame ids`);
+            }
+            const order = rawOp.order;
+            const current = bundle.frames.map((f) => f.id);
+            if (order.length !== current.length || new Set(order).size !== order.length || !current.every((id) => order.includes(id))) {
+                throw new ArtifactPatchError(`${kind}.order must be a permutation of the current frame ids (each exactly once). Current order: [${current.join(', ')}].`);
+            }
+            const byId = new Map(bundle.frames.map((f) => [f.id, f]));
+            const next = order.map((id) => byId.get(id));
+            // OR, never assign: a later identity-reorder in the same batch must not
+            // clear an earlier real reorder's flag.
+            acc.reordered = acc.reordered || current.some((id, i) => id !== order[i]);
+            bundle.frames = next;
+            return;
+        }
+        case 'set_shared_file': {
+            const path = requireString(rawOp.path, 'path', kind);
+            const content = requireString(rawOp.content, 'content', kind);
+            // Path safety + extension allowlist is the store's whole-bundle validate.
+            const shared = bundle.shared ?? (bundle.shared = {});
+            const files = shared.files ?? (shared.files = {});
+            files[path] = content;
+            return;
+        }
+        case 'remove_shared_file': {
+            const path = requireString(rawOp.path, 'path', kind);
+            const files = bundle.shared?.files;
+            if (!files || !(path in files)) {
+                const existing = files ? Object.keys(files).join(', ') : '(none)';
+                throw new ArtifactPatchError(`${kind}: no shared file at "${path}". Existing shared files: ${existing}.`);
+            }
+            delete files[path];
+            if (Object.keys(files).length === 0)
+                delete bundle.shared.files;
+            return;
+        }
+        case 'set_tokens': {
+            if (!isRecord(rawOp.tokens)) {
+                throw new ArtifactPatchError(`${kind}.tokens must be an object of name → CSS value`);
+            }
+            // Replace the whole token map (it's a small global). Token-name/value
+            // validation is the store's whole-bundle validate. An empty object clears
+            // tokens (the store drops an empty map).
+            bundle.tokens = rawOp.tokens;
+            return;
+        }
+    }
+}
+function countOccurrences(haystack, needle) {
+    if (needle === '')
+        return 0;
+    let count = 0;
+    let from = 0;
+    for (;;) {
+        const at = haystack.indexOf(needle, from);
+        if (at === -1)
+            break;
+        count++;
+        from = at + needle.length;
+    }
+    return count;
+}
+/**
+ * Apply an ordered op list to a COPY of `bundle`, returning the mutated bundle +
+ * a change summary. Ops apply in order against the running result, so a later op
+ * sees an earlier op's edits (e.g. add_frame then reorder_frames including the
+ * new id). Throws {@link ArtifactPatchError} on the first op-level problem,
+ * leaving the input bundle untouched (it is never mutated; the copy is
+ * discarded by the caller on throw).
+ */
+export function applyArtifactPatch(bundle, ops) {
+    if (!Array.isArray(ops) || ops.length === 0) {
+        throw new ArtifactPatchError('ops must be a non-empty array of patch operations');
+    }
+    const working = cloneBundle(bundle);
+    const acc = { changed: new Set(), removed: new Set(), reordered: false };
+    ops.forEach((op, index) => applyOp(working, op, index, acc));
+    return {
+        bundle: working,
+        changedFrameIds: [...acc.changed],
+        removedFrameIds: [...acc.removed],
+        reordered: acc.reordered,
+    };
+}
+//# sourceMappingURL=artifact-patch.js.map

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

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

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

@@ -0,0 +1,51 @@
+/**
+ * Structural warnings for an artifact write (P4.3) — browser-free lints that let
+ * the agent self-verify what it just produced, in the SAME turn, without a
+ * Playwright render.
+ *
+ * Paired with the P4.2 frame manifest, these back the "return-rich" create/patch
+ * returns: `summarizeArtifactWrite` hands both surfaces (agent chat + MCP) ONE
+ * identical `{ manifest, warnings }` payload so the two can't drift. The manifest
+ * is built WITHOUT a `frameId`, so it carries no per-frame `content` — the return
+ * is structure-only and safe to persist across turns (it does NOT trip the
+ * `compactArtifactHistory` MUST-NOT-PERSIST rule that elides full artifact source).
+ *
+ * The lints are deliberately conservative — high precision over recall — so a
+ * legitimate single-`app` artifact is never nagged into being split:
+ *   - `packed-slides`  — ONE non-deck frame whose content carries the fingerprints
+ *                        of a hand-rolled DECK (the agent freelancing a stepper
+ *                        inside one frame instead of one frame per slide).
+ *   - `packed-pages`   — ONE non-document frame whose content carries the
+ *                        fingerprints of a hand-rolled multi-page DOCUMENT (forced
+ *                        page breaks or a page-column grid, e.g. the observed
+ *                        `app` frame with a `repeat(var(--page-cols),816px)` grid)
+ *                        instead of a `pages` frame the platform paginates.
+ *   - `empty-frame`    — a frame that will render blank (objective).
+ *   - `near-byte-cap`  — the bundle is close to the 512KB ceiling, so the NEXT
+ *                        edit may be rejected (objective).
+ */
+import { type ArtifactBundle } from './artifact-frame-model.js';
+import { type ArtifactManifest } from './artifact-manifest.js';
+export type ArtifactWarningCode = 'packed-slides' | 'packed-pages' | 'empty-frame' | 'near-byte-cap';
+export interface ArtifactWarning {
+    code: ArtifactWarningCode;
+    message: string;
+    /** Present for frame-scoped warnings (`empty-frame`, `packed-slides`, `packed-pages`). */
+    frameId?: string;
+}
+/**
+ * Compute the structural warnings for a (already-validated) bundle. Pure — no IO,
+ * no browser. Order: the headline adherence lint first, then per-frame blanks,
+ * then the size ceiling.
+ */
+export declare function artifactStructuralWarnings(bundle: ArtifactBundle): ArtifactWarning[];
+/**
+ * THE return-rich payload both write surfaces attach to a create/patch result:
+ * the structural manifest (P4.2) + the lints. Built from the WRITTEN bundle so it
+ * reflects exactly what was persisted. The manifest carries no per-frame
+ * `content` (no `frameId` option) → the result is structure-only and persist-safe.
+ */
+export declare function summarizeArtifactWrite(bundle: ArtifactBundle): {
+    manifest: ArtifactManifest;
+    warnings: ArtifactWarning[];
+};

package/dist/core/artifact-warnings.js

@@ -0,0 +1,165 @@
+/**
+ * Structural warnings for an artifact write (P4.3) — browser-free lints that let
+ * the agent self-verify what it just produced, in the SAME turn, without a
+ * Playwright render.
+ *
+ * Paired with the P4.2 frame manifest, these back the "return-rich" create/patch
+ * returns: `summarizeArtifactWrite` hands both surfaces (agent chat + MCP) ONE
+ * identical `{ manifest, warnings }` payload so the two can't drift. The manifest
+ * is built WITHOUT a `frameId`, so it carries no per-frame `content` — the return
+ * is structure-only and safe to persist across turns (it does NOT trip the
+ * `compactArtifactHistory` MUST-NOT-PERSIST rule that elides full artifact source).
+ *
+ * The lints are deliberately conservative — high precision over recall — so a
+ * legitimate single-`app` artifact is never nagged into being split:
+ *   - `packed-slides`  — ONE non-deck frame whose content carries the fingerprints
+ *                        of a hand-rolled DECK (the agent freelancing a stepper
+ *                        inside one frame instead of one frame per slide).
+ *   - `packed-pages`   — ONE non-document frame whose content carries the
+ *                        fingerprints of a hand-rolled multi-page DOCUMENT (forced
+ *                        page breaks or a page-column grid, e.g. the observed
+ *                        `app` frame with a `repeat(var(--page-cols),816px)` grid)
+ *                        instead of a `pages` frame the platform paginates.
+ *   - `empty-frame`    — a frame that will render blank (objective).
+ *   - `near-byte-cap`  — the bundle is close to the 512KB ceiling, so the NEXT
+ *                        edit may be rejected (objective).
+ */
+import { ARTIFACT_BUNDLE_MAX_BYTES, } from './artifact-frame-model.js';
+import { buildArtifactManifest } from './artifact-manifest.js';
+/** Fraction of the hard byte cap at which `near-byte-cap` starts warning. */
+const NEAR_CAP_FRACTION = 0.9;
+/** `data-artifact-frame` is the PLATFORM's own frame-splitting attribute — a
+ *  single authored frame should never contain it. Two or more inside ONE frame's
+ *  content means the agent hand-declared multiple frames in one (the exact
+ *  hand-rolled-deck failure `packed-slides` exists to catch). */
+const PACKED_SUBFRAME_THRESHOLD = 2;
+/** ...or this many FORCED page breaks: a multi-page document crammed into a
+ *  non-`pages` frame instead of authored as a paginating `pages` frame. */
+const PACKED_PAGEBREAK_THRESHOLD = 2;
+/** Bound the regex scans so a pathological multi-hundred-KB frame can't stall the
+ *  event loop (mirrors artifact-manifest's KEY_TEXT_SCAN_LIMIT rationale). A cut
+ *  match can only UNDERcount → at worst a missed warning, never a false positive. */
+const PACKED_SCAN_LIMIT = 64 * 1024;
+/** Forced page break, old (`page-break-before:always`) and modern
+ *  (`break-before:page`) syntax — the fingerprint of paginating by hand. */
+const PAGE_BREAK_RE = /(?:page-break-(?:before|after)\s*:\s*always|break-(?:before|after)\s*:\s*page)/gi;
+/** A MULTI-page CSS variable — `--page-cols`, `--page-count`, etc. The observed
+ *  bug grid was `grid-template-columns: repeat(var(--page-cols),816px)`; a var that
+ *  names a page COUNT/COLUMN only exists to fake a multi-page grid. Deliberately
+ *  excludes the SINGULAR `--page-width`/`--page-height`/`--page-size` (a legit
+ *  single content column declares its own page dimensions) and `--page-color`
+ *  (the `\b` after the keyword guards it). */
+const PAGE_COLUMN_VAR_RE = /--page-(?:col|cols|count|num)\b/i;
+/** ...or a `repeat()` whose track is a BARE page-width px literal
+ *  (US-Letter/A4/Legal @96dpi) directly after a count of TWO OR MORE — `repeat(3,
+ *  816px)`, the shape of a hand-built MULTI-page-column grid. Kept tight for
+ *  precision: the count must be ≥2 (or `auto-fill`/`auto-fit`) so a single
+ *  page-width content column `repeat(1, 816px)` does NOT match; the page literal
+ *  must follow the comma with a left boundary, so a card grid whose track is
+ *  `minmax(1056px, 1fr)` (the literal is nested, not bare) does NOT match, and
+ *  `21056px` does not match `1056`. The `repeat(var(--page-cols),816px)` form is
+ *  caught by PAGE_COLUMN_VAR_RE instead. */
+const PAGE_COLUMN_GRID_RE = /repeat\(\s*(?:[2-9]|\d{2,}|auto-fill|auto-fit)\s*,\s*(?:816|1056|794|1123|1344)px\b/i;
+function byteSizeOf(bundle) {
+    // Compact JSON — byte-identical to validateArtifactBundle's cap measurement, so
+    // the advisory tracks the exact ceiling the next edit's validator enforces.
+    return new TextEncoder().encode(JSON.stringify(bundle)).length;
+}
+function countMatches(text, re) {
+    const matches = text.match(re);
+    return matches ? matches.length : 0;
+}
+/**
+ * Classify a SINGLE non-deck/non-document frame whose content looks like a deck or
+ * a multi-page document hand-rolled inside one frame. High precision over recall
+ * (the founder's explicit priority): only the unambiguous fingerprints, NOT signals
+ * a legitimate single-`app` artifact uses for its own reasons — a `.slide` class
+ * (image carousels), repeated `height:100vh` (landing-page sections), or a plain
+ * `repeat(3,1fr)` card grid are common in real apps, so they are NOT counted.
+ *
+ * Returns the kind of artifact the frame is impersonating, or null. `pages` is
+ * checked first: a forced-page-break / page-grid document is the headline observed
+ * bug, and it can also carry stray `data-artifact-frame` markers.
+ */
+function packedKind(frame) {
+    if (frame.layout !== 'app' && frame.layout !== 'artboard')
+        return null;
+    const scan = frame.content.length > PACKED_SCAN_LIMIT
+        ? frame.content.slice(0, PACKED_SCAN_LIMIT)
+        : frame.content;
+    // pages: a multi-page document faked inside one frame.
+    if (countMatches(scan, PAGE_BREAK_RE) >= PACKED_PAGEBREAK_THRESHOLD)
+        return 'pages';
+    if (PAGE_COLUMN_VAR_RE.test(scan) || PAGE_COLUMN_GRID_RE.test(scan))
+        return 'pages';
+    // slides: the platform frame-splitter attribute hand-declared multiple times.
+    if (countMatches(scan, /data-artifact-frame/gi) >= PACKED_SUBFRAME_THRESHOLD)
+        return 'slides';
+    return null;
+}
+/**
+ * Compute the structural warnings for a (already-validated) bundle. Pure — no IO,
+ * no browser. Order: the headline adherence lint first, then per-frame blanks,
+ * then the size ceiling.
+ */
+export function artifactStructuralWarnings(bundle) {
+    const warnings = [];
+    // packed-slides / packed-pages: only a SINGLE frame can be "a deck/document
+    // crammed into one frame"; a real multi-frame artifact is already doing the
+    // right thing.
+    if (bundle.frames.length === 1) {
+        const only = bundle.frames[0];
+        const kind = packedKind(only);
+        if (kind === 'slides') {
+            warnings.push({
+                code: 'packed-slides',
+                frameId: only.id,
+                message: `This is a single "${only.layout}" frame but its content looks like multiple slides. `
+                    + 'If you meant a deck, author one "slides" frame per slide so the platform steps, '
+                    + 'arranges, and exports them — do not hand-roll a stepper/filmstrip inside one frame.',
+            });
+        }
+        else if (kind === 'pages') {
+            warnings.push({
+                code: 'packed-pages',
+                frameId: only.id,
+                message: `This is a single "${only.layout}" frame but its content looks like a multi-page document `
+                    + '(forced page breaks or a page-column grid). Author a "pages" frame (a fixed page box, '
+                    + 'e.g. 816×1056 US-Letter) holding the document body and let the platform paginate, number, '
+                    + 'and PDF-scroll it — do not build your own page grid or page breaks inside an app/artboard frame.',
+            });
+        }
+    }
+    bundle.frames.forEach((frame, index) => {
+        if (frame.content.trim().length === 0) {
+            warnings.push({
+                code: 'empty-frame',
+                frameId: frame.id,
+                message: `Frame "${frame.id}" (index ${index}) has no content — it will render blank.`,
+            });
+        }
+    });
+    const byteSize = byteSizeOf(bundle);
+    if (byteSize > NEAR_CAP_FRACTION * ARTIFACT_BUNDLE_MAX_BYTES) {
+        const kb = Math.round(byteSize / 1024);
+        const capKb = Math.round(ARTIFACT_BUNDLE_MAX_BYTES / 1024);
+        warnings.push({
+            code: 'near-byte-cap',
+            message: `Bundle is ${kb}KB, near the ${capKb}KB limit — the next edit may be rejected; split or trim content.`,
+        });
+    }
+    return warnings;
+}
+/**
+ * THE return-rich payload both write surfaces attach to a create/patch result:
+ * the structural manifest (P4.2) + the lints. Built from the WRITTEN bundle so it
+ * reflects exactly what was persisted. The manifest carries no per-frame
+ * `content` (no `frameId` option) → the result is structure-only and persist-safe.
+ */
+export function summarizeArtifactWrite(bundle) {
+    return {
+        manifest: buildArtifactManifest(bundle),
+        warnings: artifactStructuralWarnings(bundle),
+    };
+}
+//# sourceMappingURL=artifact-warnings.js.map

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

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

package/dist/core/breakpoints.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical responsive breakpoint queries — the single source of truth for
+ * BOTH CSS and JS so they can never drift.
+ *
+ *  - CSS consumes the same strings as `@custom-media --mobile / --touch`,
+ *    declared in `web/src/styles/media.css` (for component <style> blocks, via
+ *    @csstools/postcss-global-data) AND in-file at the top of `web/src/app.css`
+ *    (for the Tailwind/lightningcss pass — see the plan's build-pipeline note).
+ *  - JS consumes them via `matchMedia(MOBILE_MEDIA_QUERY)` and Svelte 5
+ *    `new MediaQuery(MOBILE_MEDIA_QUERY)`. Web code imports through the
+ *    `@core/breakpoints` alias.
+ *
+ * `src/core/__tests__/breakpoints-sync.test.ts` asserts all three CSS copies
+ * stay byte-identical to these constants.
+ *
+ * --mobile = LAYOUT TOPOLOGY (drawers vs docked). Primary `pointer: coarse`, so
+ * a keyboard-attached iPad (trackpad primary) reads as desktop. `767.98px` (not
+ * 768) dodges the exact overlap with Tailwind's `md` = min-width:768 and keeps a
+ * classic 768px iPad on desktop. The `max-height: 500px` arm catches landscape
+ * phones (≤~480 tall) while letting short tablets (≥600) fall through to desktop.
+ *
+ * --touch = TOUCH ERGONOMICS (44px tap targets, 16px inputs to dodge iOS focus
+ * auto-zoom). `any-pointer: coarse` so a touch device still counts even when its
+ * PRIMARY pointer is a trackpad (keyboard-attached iPad).
+ */
+export declare const MOBILE_MEDIA_QUERY = "(max-width: 767.98px), (hover: none) and (pointer: coarse) and (max-height: 500px)";
+export declare const TOUCH_MEDIA_QUERY = "(any-pointer: coarse)";

package/dist/core/breakpoints.js

@@ -0,0 +1,28 @@
+/**
+ * Canonical responsive breakpoint queries — the single source of truth for
+ * BOTH CSS and JS so they can never drift.
+ *
+ *  - CSS consumes the same strings as `@custom-media --mobile / --touch`,
+ *    declared in `web/src/styles/media.css` (for component <style> blocks, via
+ *    @csstools/postcss-global-data) AND in-file at the top of `web/src/app.css`
+ *    (for the Tailwind/lightningcss pass — see the plan's build-pipeline note).
+ *  - JS consumes them via `matchMedia(MOBILE_MEDIA_QUERY)` and Svelte 5
+ *    `new MediaQuery(MOBILE_MEDIA_QUERY)`. Web code imports through the
+ *    `@core/breakpoints` alias.
+ *
+ * `src/core/__tests__/breakpoints-sync.test.ts` asserts all three CSS copies
+ * stay byte-identical to these constants.
+ *
+ * --mobile = LAYOUT TOPOLOGY (drawers vs docked). Primary `pointer: coarse`, so
+ * a keyboard-attached iPad (trackpad primary) reads as desktop. `767.98px` (not
+ * 768) dodges the exact overlap with Tailwind's `md` = min-width:768 and keeps a
+ * classic 768px iPad on desktop. The `max-height: 500px` arm catches landscape
+ * phones (≤~480 tall) while letting short tablets (≥600) fall through to desktop.
+ *
+ * --touch = TOUCH ERGONOMICS (44px tap targets, 16px inputs to dodge iOS focus
+ * auto-zoom). `any-pointer: coarse` so a touch device still counts even when its
+ * PRIMARY pointer is a trackpad (keyboard-attached iPad).
+ */
+export const MOBILE_MEDIA_QUERY = '(max-width: 767.98px), (hover: none) and (pointer: coarse) and (max-height: 500px)';
+export const TOUCH_MEDIA_QUERY = '(any-pointer: coarse)';
+//# sourceMappingURL=breakpoints.js.map

package/dist/core/breakpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakpoints.js","sourceRoot":"","sources":["../../src/core/breakpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC9B,oFAAoF,CAAC;AAEtF,MAAM,CAAC,MAAM,iBAAiB,GAAG,uBAAuB,CAAC"}