@compilr-dev/sdk 0.18.10 → 0.19.0

package/dist/canvas/assets.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Canvas assets — images stored beside a canvas, not inside it.
+ *
+ * ⚠️ WHY NOT JUST A data: URI IN THE HTML. The sandbox CSP is `img-src data: blob:`, so a
+ * data URI is the ONLY thing that renders — but the canvas document is stored in sqlite
+ * and edited with `canvas_edit`'s str_replace. Four product photos inline is a few hundred
+ * KB of base64 sitting in the middle of the document the agent has to read an outline of
+ * and patch by hand. The editing discipline that makes canvases reliable stops working.
+ *
+ * So the markup carries a REFERENCE and the bytes live in a side table:
+ *
+ *     <img src="asset:hero" alt="…">
+ *
+ * and the host substitutes real data URIs at the two moments the canvas becomes pixels:
+ * rendering into the iframe, and exporting to PDF/HTML/PNG. `resolveCanvasAssets` below is
+ * that substitution, shared by both so they cannot disagree — the same reason the token
+ * block had to be extracted.
+ *
+ * ⚠️ `asset:` IS NOT A REAL SCHEME. If a host forgets to substitute, the CSP blocks it and
+ * the image silently does not render. That is the failure mode to design against, which is
+ * why `canvas_validate` errors on a reference with no matching asset, and why the renderer
+ * and exporter share one function rather than each implementing the regex.
+ */
+/** An image stored against a canvas. */
+export interface CanvasAsset {
+    id: number;
+    canvasId: number;
+    /** The handle the markup references as `asset:<ref>`. */
+    ref: string;
+    mediaType: string;
+    /** base64, no data: prefix. */
+    data: string;
+    width?: number;
+    height?: number;
+    /** Encoded size in bytes — what the canvas actually costs to render. */
+    bytes: number;
+    /** Where it came from, for provenance when someone asks "which file is this?". */
+    sourcePath?: string;
+    createdAt: Date;
+}
+export interface CreateCanvasAssetInput {
+    canvasId: number;
+    ref: string;
+    mediaType: string;
+    data: string;
+    width?: number;
+    height?: number;
+    bytes: number;
+    sourcePath?: string;
+}
+/**
+ * A ref is a short handle an agent types into markup, so it has to be safe to embed in an
+ * attribute and easy to get right: lowercase word characters and dashes.
+ */
+export declare const ASSET_REF: RegExp;
+export declare const isValidAssetRef: (ref: string) => boolean;
+/** Every asset ref the markup uses, deduplicated, in document order. */
+export declare function referencedAssets(html: string): string[];
+/**
+ * Replace every `asset:<ref>` with a real data URI.
+ *
+ * A reference with no matching asset is LEFT ALONE rather than blanked: the CSP will drop
+ * it either way, and leaving it makes the cause visible in devtools instead of presenting
+ * an empty `src` that looks like an authoring mistake.
+ */
+export declare function resolveCanvasAssets(html: string, assets: readonly Pick<CanvasAsset, 'ref' | 'mediaType' | 'data'>[]): string;
+/**
+ * Refs used by the markup that no asset satisfies.
+ *
+ * ⚠️ This is the check that makes the indirection safe. Without it a typo produces a
+ * canvas that renders with a hole in it and no error anywhere.
+ */
+export declare function missingAssetRefs(html: string, assets: readonly Pick<CanvasAsset, 'ref'>[]): string[];
+/**
+ * The total encoded weight of the assets a canvas actually uses.
+ * Unreferenced assets are excluded — they cost storage, not render time.
+ */
+export declare function assetPayloadBytes(html: string, assets: readonly Pick<CanvasAsset, 'ref' | 'bytes'>[]): number;
+/**
+ * ⚠️ A BUDGET, because every byte here is paid twice — once in the stored canvas and once
+ * in every export. Four photos at card size land around 200KB; a single un-resized phone
+ * photo is 4MB on its own. The tool refuses above this and says what to do.
+ */
+export declare const ASSET_BUDGET_BYTES = 2000000;
+/** Display width an image is resized to before storing, unless the caller says otherwise. */
+export declare const DEFAULT_ASSET_WIDTH = 640;
+/**
+ * The inverse of `resolveCanvasAssets`: turn embedded data URIs back into `asset:<ref>`.
+ *
+ * ⚠️ THIS IS NOT OPTIONAL, it is what keeps the indirection from unravelling. The host
+ * bridge serializes the live iframe's DOM back to be persisted after a visual edit — and
+ * that DOM holds the RESOLVED data URIs. Without this pass, one visual edit writes every
+ * image into the stored document as base64: exactly the state the asset table exists to
+ * prevent, arrived at by the back door, and silently.
+ *
+ * Matching is on the base64 payload rather than the whole URI, so a media type rewritten
+ * by the browser still maps home.
+ */
+export declare function dereferenceCanvasAssets(html: string, assets: readonly Pick<CanvasAsset, 'ref' | 'data'>[]): string;

package/dist/canvas/assets.js

@@ -0,0 +1,111 @@
+/**
+ * Canvas assets — images stored beside a canvas, not inside it.
+ *
+ * ⚠️ WHY NOT JUST A data: URI IN THE HTML. The sandbox CSP is `img-src data: blob:`, so a
+ * data URI is the ONLY thing that renders — but the canvas document is stored in sqlite
+ * and edited with `canvas_edit`'s str_replace. Four product photos inline is a few hundred
+ * KB of base64 sitting in the middle of the document the agent has to read an outline of
+ * and patch by hand. The editing discipline that makes canvases reliable stops working.
+ *
+ * So the markup carries a REFERENCE and the bytes live in a side table:
+ *
+ *     <img src="asset:hero" alt="…">
+ *
+ * and the host substitutes real data URIs at the two moments the canvas becomes pixels:
+ * rendering into the iframe, and exporting to PDF/HTML/PNG. `resolveCanvasAssets` below is
+ * that substitution, shared by both so they cannot disagree — the same reason the token
+ * block had to be extracted.
+ *
+ * ⚠️ `asset:` IS NOT A REAL SCHEME. If a host forgets to substitute, the CSP blocks it and
+ * the image silently does not render. That is the failure mode to design against, which is
+ * why `canvas_validate` errors on a reference with no matching asset, and why the renderer
+ * and exporter share one function rather than each implementing the regex.
+ */
+/**
+ * A ref is a short handle an agent types into markup, so it has to be safe to embed in an
+ * attribute and easy to get right: lowercase word characters and dashes.
+ */
+export const ASSET_REF = /^[a-z0-9][a-z0-9-]{0,39}$/;
+export const isValidAssetRef = (ref) => ASSET_REF.test(ref);
+/**
+ * ⚠️ Matches `asset:<ref>` ONLY inside an attribute value, not anywhere in the document.
+ * A canvas that mentions `asset:hero` in a code sample or a caption must not have its text
+ * rewritten into a 200KB base64 blob.
+ */
+const REFERENCE = /(["'])asset:([a-z0-9][a-z0-9-]{0,39})\1/gi;
+/** Every asset ref the markup uses, deduplicated, in document order. */
+export function referencedAssets(html) {
+    const seen = new Set();
+    for (const m of html.matchAll(REFERENCE))
+        seen.add(m[2].toLowerCase());
+    return [...seen];
+}
+/**
+ * Replace every `asset:<ref>` with a real data URI.
+ *
+ * A reference with no matching asset is LEFT ALONE rather than blanked: the CSP will drop
+ * it either way, and leaving it makes the cause visible in devtools instead of presenting
+ * an empty `src` that looks like an authoring mistake.
+ */
+export function resolveCanvasAssets(html, assets) {
+    if (assets.length === 0)
+        return html;
+    const byRef = new Map(assets.map((a) => [a.ref.toLowerCase(), a]));
+    return html.replace(REFERENCE, (whole, quote, ref) => {
+        const asset = byRef.get(ref.toLowerCase());
+        if (!asset)
+            return whole;
+        return `${quote}data:${asset.mediaType};base64,${asset.data}${quote}`;
+    });
+}
+/**
+ * Refs used by the markup that no asset satisfies.
+ *
+ * ⚠️ This is the check that makes the indirection safe. Without it a typo produces a
+ * canvas that renders with a hole in it and no error anywhere.
+ */
+export function missingAssetRefs(html, assets) {
+    const have = new Set(assets.map((a) => a.ref.toLowerCase()));
+    return referencedAssets(html).filter((ref) => !have.has(ref));
+}
+/**
+ * The total encoded weight of the assets a canvas actually uses.
+ * Unreferenced assets are excluded — they cost storage, not render time.
+ */
+export function assetPayloadBytes(html, assets) {
+    const used = new Set(referencedAssets(html));
+    return assets
+        .filter((a) => used.has(a.ref.toLowerCase()))
+        .reduce((total, a) => total + a.bytes, 0);
+}
+/**
+ * ⚠️ A BUDGET, because every byte here is paid twice — once in the stored canvas and once
+ * in every export. Four photos at card size land around 200KB; a single un-resized phone
+ * photo is 4MB on its own. The tool refuses above this and says what to do.
+ */
+export const ASSET_BUDGET_BYTES = 2_000_000;
+/** Display width an image is resized to before storing, unless the caller says otherwise. */
+export const DEFAULT_ASSET_WIDTH = 640;
+/**
+ * The inverse of `resolveCanvasAssets`: turn embedded data URIs back into `asset:<ref>`.
+ *
+ * ⚠️ THIS IS NOT OPTIONAL, it is what keeps the indirection from unravelling. The host
+ * bridge serializes the live iframe's DOM back to be persisted after a visual edit — and
+ * that DOM holds the RESOLVED data URIs. Without this pass, one visual edit writes every
+ * image into the stored document as base64: exactly the state the asset table exists to
+ * prevent, arrived at by the back door, and silently.
+ *
+ * Matching is on the base64 payload rather than the whole URI, so a media type rewritten
+ * by the browser still maps home.
+ */
+export function dereferenceCanvasAssets(html, assets) {
+    let out = html;
+    for (const asset of assets) {
+        if (!asset.data)
+            continue;
+        // `data:<anything>;base64,<payload>` → asset:<ref>, in any attribute quoting.
+        const pattern = new RegExp(`data:[^"'\\s]*?base64,${asset.data.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'g');
+        out = out.replace(pattern, `asset:${asset.ref}`);
+    }
+    return out;
+}

package/dist/canvas/color.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Colour arithmetic for canvas checks and for the host's surface ramp.
+ *
+ * ⚠️ WHY THIS EXISTS. Three real terminal palettes, as the host injects them today:
+ * Tokyo Night puts `--canvas-card` 2.1% from `--canvas-bg`, Catppuccin Latte 0.0%,
+ * Gruvbox Dark 1.8%. A card that shares its ground's value is a rectangle of text, and
+ * no prompt has ever prevented it — the values simply are not far apart enough. The
+ * agent is not doing anything wrong.
+ *
+ * So the numbers have to be computed somewhere. Here, as pure functions with no I/O, so
+ * the same maths serves the validator (does this canvas fail?) and the host (what ramp
+ * should I inject?) without either owning it.
+ *
+ * ⚠️ OKLab lightness, not HSL's. HSL calls #FFFF00 and #0000FF both "50% lightness",
+ * which would rate yellow-on-blue as a zero-contrast pair. OKLab's L tracks perceived
+ * lightness, which is what "5–7% apart" has to mean to be worth asserting.
+ *
+ * WCAG contrast is separate and deliberately NOT OKLab — the 4.5:1 threshold is defined
+ * against sRGB relative luminance, so using anything else would be asserting a different
+ * rule than the one being cited.
+ */
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * A CSS colour literal → rgb in 0..1, or null when it is not one.
+ *
+ * ⚠️ Returns null for `var(--x)` ON PURPOSE, and callers depend on it: a custom property
+ * has no value until the host resolves it, and guessing one would produce confident
+ * arithmetic about a colour nobody has chosen yet.
+ */
+export declare function parseColor(input: string): Rgb | null;
+/** sRGB relative luminance, per WCAG 2.x. */
+export declare function relativeLuminance({ r, g, b }: Rgb): number;
+/** WCAG contrast ratio, 1..21. Order-independent. */
+export declare function contrastRatio(a: Rgb, b: Rgb): number;
+/**
+ * OKLab lightness, 0..1 — perceived lightness, which is what the 5–7% target means.
+ * Coefficients from Björn Ottosson's OKLab definition.
+ */
+export declare function oklabLightness({ r, g, b }: Rgb): number;
+/** Perceived lightness distance between two colours, in percentage points. */
+export declare function lightnessDeltaPct(a: Rgb, b: Rgb): number;
+/**
+ * Is this colour a neutral (a grey), rather than a hue?
+ *
+ * Used to count "non-neutral hues": greys are the ground the composition sits on and
+ * never count against the accent budget, however many of them there are.
+ */
+export declare function isNeutral({ r, g, b }: Rgb, tolerance?: number): boolean;
+/** Hue angle in degrees, 0..360. Meaningless for a neutral — check `isNeutral` first. */
+export declare function hueAngle({ r, g, b }: Rgb): number;
+/** The floor for text, per WCAG AA at normal size. */
+export declare const AA_TEXT = 4.5;
+/**
+ * The target separation between adjacent surfaces, in OKLab percentage points.
+ *
+ * Below MIN it disappears; above MAX the card reads as a separate page rather than a
+ * raised surface. Exported so the host's ramp and the validator cannot disagree.
+ *
+ * ⚠️ MIN IS CALIBRATED TO THE HANDOFF'S SPECIMENS, NOT TO ITS STATED NUMBER, and the
+ * difference matters. Section 01 says "below 3%" and reports its three palettes at 2.1%,
+ * 0.0% and 1.8% — but those figures reproduce under no standard metric: Tokyo Night's
+ * pair measures 3.5 in OKLab, 4.0 in CIE L*, 3.9 in HSL. The formula behind them is not
+ * stated, so adopting the number would be asserting arithmetic nobody can check.
+ *
+ * The SPECIMENS are sound, though — they are real palettes a designer looked at and
+ * judged muddy, and the same section gives a corrected ramp for each. So MIN is set where
+ * it separates the two groups in the metric actually used here:
+ *
+ *     as injected (must fail)   3.5 · 0.0 · 3.4
+ *     derived ramp (must pass)  5.6 · 7.5 · 6.1
+ *
+ * 4 sits between them with room on both sides. `canvas-color.test.ts` asserts that
+ * separation directly rather than any single figure, so a future metric change has to
+ * keep sorting the real palettes correctly instead of matching a constant.
+ */
+export declare const SURFACE_DELTA_MIN = 4;
+export declare const SURFACE_DELTA_TARGET = 6;
+export declare const SURFACE_DELTA_MAX = 12;
+/** A hairline sits this far toward the foreground — never more. */
+export declare const HAIRLINE_MIN_PCT = 10;
+export declare const HAIRLINE_MAX_PCT = 15;

package/dist/canvas/color.js

@@ -0,0 +1,216 @@
+/**
+ * Colour arithmetic for canvas checks and for the host's surface ramp.
+ *
+ * ⚠️ WHY THIS EXISTS. Three real terminal palettes, as the host injects them today:
+ * Tokyo Night puts `--canvas-card` 2.1% from `--canvas-bg`, Catppuccin Latte 0.0%,
+ * Gruvbox Dark 1.8%. A card that shares its ground's value is a rectangle of text, and
+ * no prompt has ever prevented it — the values simply are not far apart enough. The
+ * agent is not doing anything wrong.
+ *
+ * So the numbers have to be computed somewhere. Here, as pure functions with no I/O, so
+ * the same maths serves the validator (does this canvas fail?) and the host (what ramp
+ * should I inject?) without either owning it.
+ *
+ * ⚠️ OKLab lightness, not HSL's. HSL calls #FFFF00 and #0000FF both "50% lightness",
+ * which would rate yellow-on-blue as a zero-contrast pair. OKLab's L tracks perceived
+ * lightness, which is what "5–7% apart" has to mean to be worth asserting.
+ *
+ * WCAG contrast is separate and deliberately NOT OKLab — the 4.5:1 threshold is defined
+ * against sRGB relative luminance, so using anything else would be asserting a different
+ * rule than the one being cited.
+ */
+const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
+const HEX = /^#?([0-9a-f]{3,8})$/i;
+/** `#abc` · `#aabbcc` · `#aabbccdd` → rgb. Alpha is parsed and discarded, not rejected. */
+function parseHex(input) {
+    const m = HEX.exec(input.trim());
+    if (!m)
+        return null;
+    let hex = m[1];
+    // 3 and 4 digit forms double each nibble; 4 and 8 carry alpha we drop.
+    if (hex.length === 3 || hex.length === 4) {
+        hex = hex
+            .split('')
+            .map((c) => c + c)
+            .join('');
+    }
+    if (hex.length !== 6 && hex.length !== 8)
+        return null;
+    return {
+        r: parseInt(hex.slice(0, 2), 16) / 255,
+        g: parseInt(hex.slice(2, 4), 16) / 255,
+        b: parseInt(hex.slice(4, 6), 16) / 255,
+    };
+}
+/** One `rgb()`/`rgba()` channel: `200`, `78%`, or `.5` for alpha (which we drop). */
+function channel(raw) {
+    const t = raw.trim();
+    if (!t)
+        return null;
+    const pct = t.endsWith('%');
+    const n = Number.parseFloat(pct ? t.slice(0, -1) : t);
+    if (!Number.isFinite(n))
+        return null;
+    return clamp01(pct ? n / 100 : n / 255);
+}
+const FUNC = /^(rgba?|hsla?)\s*\(([^)]*)\)$/i;
+/**
+ * ⚠️ Splits on commas AND whitespace, because both spellings are legal and in the wild:
+ * `rgb(10, 20, 30)` and `rgb(10 20 30 / 50%)`. The slash-separated alpha is dropped with
+ * the rest — every caller here asks about hue and lightness, never transparency.
+ */
+const parts = (body) => body
+    .replace(/\//g, ' ')
+    .split(/[,\s]+/)
+    .map((p) => p.trim())
+    .filter(Boolean);
+function hueToRgb(p, q, t) {
+    let x = t;
+    if (x < 0)
+        x += 1;
+    if (x > 1)
+        x -= 1;
+    if (x < 1 / 6)
+        return p + (q - p) * 6 * x;
+    if (x < 1 / 2)
+        return q;
+    if (x < 2 / 3)
+        return p + (q - p) * (2 / 3 - x) * 6;
+    return p;
+}
+function parseHsl(body) {
+    const p = parts(body);
+    if (p.length < 3)
+        return null;
+    const h = Number.parseFloat(p[0]);
+    const s = Number.parseFloat(p[1]) / 100;
+    const l = Number.parseFloat(p[2]) / 100;
+    if (!Number.isFinite(h) || !Number.isFinite(s) || !Number.isFinite(l))
+        return null;
+    const hn = (((h % 360) + 360) % 360) / 360;
+    const sn = clamp01(s);
+    const ln = clamp01(l);
+    if (sn === 0)
+        return { r: ln, g: ln, b: ln };
+    const q = ln < 0.5 ? ln * (1 + sn) : ln + sn - ln * sn;
+    const pp = 2 * ln - q;
+    return {
+        r: hueToRgb(pp, q, hn + 1 / 3),
+        g: hueToRgb(pp, q, hn),
+        b: hueToRgb(pp, q, hn - 1 / 3),
+    };
+}
+/**
+ * A CSS colour literal → rgb in 0..1, or null when it is not one.
+ *
+ * ⚠️ Returns null for `var(--x)` ON PURPOSE, and callers depend on it: a custom property
+ * has no value until the host resolves it, and guessing one would produce confident
+ * arithmetic about a colour nobody has chosen yet.
+ */
+export function parseColor(input) {
+    const t = input.trim();
+    if (!t)
+        return null;
+    const hex = parseHex(t);
+    if (hex)
+        return hex;
+    const m = FUNC.exec(t);
+    if (!m)
+        return null;
+    const fn = m[1].toLowerCase();
+    if (fn === 'hsl' || fn === 'hsla')
+        return parseHsl(m[2]);
+    const p = parts(m[2]);
+    if (p.length < 3)
+        return null;
+    const [r, g, b] = [channel(p[0]), channel(p[1]), channel(p[2])];
+    if (r === null || g === null || b === null)
+        return null;
+    return { r, g, b };
+}
+const linear = (c) => c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+/** sRGB relative luminance, per WCAG 2.x. */
+export function relativeLuminance({ r, g, b }) {
+    return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+/** WCAG contrast ratio, 1..21. Order-independent. */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const [hi, lo] = la >= lb ? [la, lb] : [lb, la];
+    return (hi + 0.05) / (lo + 0.05);
+}
+/**
+ * OKLab lightness, 0..1 — perceived lightness, which is what the 5–7% target means.
+ * Coefficients from Björn Ottosson's OKLab definition.
+ */
+export function oklabLightness({ r, g, b }) {
+    const lr = linear(r);
+    const lg = linear(g);
+    const lb = linear(b);
+    const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+    const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+    const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+    return clamp01(0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s);
+}
+/** Perceived lightness distance between two colours, in percentage points. */
+export function lightnessDeltaPct(a, b) {
+    return Math.abs(oklabLightness(a) - oklabLightness(b)) * 100;
+}
+/**
+ * Is this colour a neutral (a grey), rather than a hue?
+ *
+ * Used to count "non-neutral hues": greys are the ground the composition sits on and
+ * never count against the accent budget, however many of them there are.
+ */
+export function isNeutral({ r, g, b }, tolerance = 0.06) {
+    return Math.max(r, g, b) - Math.min(r, g, b) <= tolerance;
+}
+/** Hue angle in degrees, 0..360. Meaningless for a neutral — check `isNeutral` first. */
+export function hueAngle({ r, g, b }) {
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const d = max - min;
+    if (d === 0)
+        return 0;
+    let h;
+    if (max === r)
+        h = ((g - b) / d) % 6;
+    else if (max === g)
+        h = (b - r) / d + 2;
+    else
+        h = (r - g) / d + 4;
+    h *= 60;
+    return h < 0 ? h + 360 : h;
+}
+/** The floor for text, per WCAG AA at normal size. */
+export const AA_TEXT = 4.5;
+/**
+ * The target separation between adjacent surfaces, in OKLab percentage points.
+ *
+ * Below MIN it disappears; above MAX the card reads as a separate page rather than a
+ * raised surface. Exported so the host's ramp and the validator cannot disagree.
+ *
+ * ⚠️ MIN IS CALIBRATED TO THE HANDOFF'S SPECIMENS, NOT TO ITS STATED NUMBER, and the
+ * difference matters. Section 01 says "below 3%" and reports its three palettes at 2.1%,
+ * 0.0% and 1.8% — but those figures reproduce under no standard metric: Tokyo Night's
+ * pair measures 3.5 in OKLab, 4.0 in CIE L*, 3.9 in HSL. The formula behind them is not
+ * stated, so adopting the number would be asserting arithmetic nobody can check.
+ *
+ * The SPECIMENS are sound, though — they are real palettes a designer looked at and
+ * judged muddy, and the same section gives a corrected ramp for each. So MIN is set where
+ * it separates the two groups in the metric actually used here:
+ *
+ *     as injected (must fail)   3.5 · 0.0 · 3.4
+ *     derived ramp (must pass)  5.6 · 7.5 · 6.1
+ *
+ * 4 sits between them with room on both sides. `canvas-color.test.ts` asserts that
+ * separation directly rather than any single figure, so a future metric change has to
+ * keep sorting the real palettes correctly instead of matching a constant.
+ */
+export const SURFACE_DELTA_MIN = 4;
+export const SURFACE_DELTA_TARGET = 6;
+export const SURFACE_DELTA_MAX = 12;
+/** A hairline sits this far toward the foreground — never more. */
+export const HAIRLINE_MIN_PCT = 10;
+export const HAIRLINE_MAX_PCT = 15;

package/dist/canvas/index.d.ts

@@ -4,3 +4,11 @@
  */
 export * from './types.js';
 export * from './validate.js';
+export { parseColor, relativeLuminance, contrastRatio, oklabLightness, lightnessDeltaPct, isNeutral, hueAngle, AA_TEXT, SURFACE_DELTA_MIN, SURFACE_DELTA_TARGET, SURFACE_DELTA_MAX, HAIRLINE_MIN_PCT, HAIRLINE_MAX_PCT, } from './color.js';
+export type { Rgb } from './color.js';
+export { runQualityChecks, checkSurfaceTokens, checkTextContrast, checkHueCount, checkDeadTweaks, primaryVarNames, } from './quality-checks.js';
+export type { QualityIssue } from './quality-checks.js';
+export { deriveSurfaceRamp, withLightness } from './ramp.js';
+export type { SurfaceRamp } from './ramp.js';
+export { resolveCanvasAssets, dereferenceCanvasAssets, referencedAssets, missingAssetRefs, assetPayloadBytes, isValidAssetRef, ASSET_BUDGET_BYTES, DEFAULT_ASSET_WIDTH, } from './assets.js';
+export type { CanvasAsset, CreateCanvasAssetInput } from './assets.js';

package/dist/canvas/index.js

@@ -4,3 +4,19 @@
  */
 export * from './types.js';
 export * from './validate.js';
+/*
+  ⚠️ Renderer-safe on purpose. Both modules are pure arithmetic with no imports beyond
+  each other, so Desktop's renderer can use them for the surface ramp without pulling the
+  SDK main entry (which reaches node:util and breaks a browser bundle). The host and the
+  validator must agree on the ramp's targets, so they share the constants rather than
+  each keeping a copy.
+*/
+export { parseColor, relativeLuminance, contrastRatio, oklabLightness, lightnessDeltaPct, isNeutral, hueAngle, AA_TEXT, SURFACE_DELTA_MIN, SURFACE_DELTA_TARGET, SURFACE_DELTA_MAX, HAIRLINE_MIN_PCT, HAIRLINE_MAX_PCT, } from './color.js';
+export { runQualityChecks, checkSurfaceTokens, checkTextContrast, checkHueCount, checkDeadTweaks, primaryVarNames, } from './quality-checks.js';
+export { deriveSurfaceRamp, withLightness } from './ramp.js';
+/*
+  Assets — images stored beside a canvas. `resolveCanvasAssets` is renderer-safe and is
+  shared by the host's live iframe AND its export path; they must not each implement the
+  substitution, for the same reason the theme token block had to be extracted.
+*/
+export { resolveCanvasAssets, dereferenceCanvasAssets, referencedAssets, missingAssetRefs, assetPayloadBytes, isValidAssetRef, ASSET_BUDGET_BYTES, DEFAULT_ASSET_WIDTH, } from './assets.js';

package/dist/canvas/quality-checks.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The deterministic half of canvas quality.
+ *
+ * ⚠️ WHY THESE ARE CODE AND NOT PROMPT. Each one is arithmetic on values the canvas
+ * declares, and each has already failed to hold as prose. The surface check in
+ * particular is the defect no prompt has ever prevented, because the agent is not doing
+ * anything wrong — it uses the token it was given, and on a terminal-derived palette
+ * `--canvas-card` lands within a few percent of `--canvas-bg`.
+ *
+ * ⚠️ WHAT IS DELIBERATELY MISSING: contrast between two *tokens*. The SDK never sees the
+ * theme palette — `canvas_validate` takes html and type, and nothing in the platform
+ * context carries colours — so `var(--canvas-muted)` on `var(--canvas-surface-2)` cannot
+ * be resolved here. Rather than plumb a palette through on spec, the checks below cover
+ * the two cases that need no palette: token PAIRINGS that are wrong whatever they
+ * resolve to, and literal colours, whose values are right there in the markup.
+ */
+import type { ControlManifest } from './types.js';
+export interface QualityIssue {
+    level: 'error' | 'warn';
+    message: string;
+}
+/**
+ * The custom properties a value actually USES — primaries only, never fallbacks.
+ *
+ * ⚠️ THIS EXISTS BECAUSE A SUBSTRING TEST GETS IT BACKWARDS. The handoff tells authors to
+ * write `var(--canvas-surface-1, var(--canvas-card))` so a canvas degrades on a host
+ * without the ramp, and to KEEP that fallback afterwards. A plain
+ * `/var\(--canvas-card/` test matches the fallback and fires the surface error on the
+ * exact corrected form the error message asks for — a validator that punishes compliance
+ * teaches an agent to ignore it. Caught by the negative test, not by reading the regex.
+ *
+ * So: walk to each `var(`, take the name up to the first comma, then skip the whole
+ * fallback by tracking paren depth.
+ */
+export declare function primaryVarNames(value: string): string[];
+/**
+ * A card that shares its ground's value is a rectangle of text.
+ *
+ * ⚠️ This flags the TOKEN PAIRING, not a measured delta, and that is the whole point:
+ * whether `--canvas-card` is 0.0% or 2.1% from `--canvas-bg` depends on the user's
+ * theme, and it is under 4% on every palette anyone measured. The fix is the same in
+ * all of them — use the ramp — so the check needs no palette to be right.
+ */
+export declare function checkSurfaceTokens(html: string): QualityIssue[];
+/**
+ * Text that cannot be read on the surface it actually sits on.
+ *
+ * Two halves, both palette-free:
+ *   - a literal colour on a literal background, measured exactly;
+ *   - white on `var(--canvas-accent)`, which is a pairing rather than a measurement —
+ *     the accent is a mid-tone in every theme we ship (#FF5722 gives 3.2:1), so the pair
+ *     is wrong whatever it resolves to.
+ */
+export declare function checkTextContrast(html: string): QualityIssue[];
+/**
+ * More hues than reasons.
+ *
+ * ⚠️ Greys never count. They are the ground a composition sits on, and a palette of six
+ * greys is a perfectly good canvas — what makes one look machine-made is four competing
+ * *hues* with nothing to distinguish. Warn, never error: multiple hues are legitimate
+ * when they encode categories a reader must tell apart.
+ */
+export declare function checkHueCount(html: string): QualityIssue[];
+/**
+ * A Tweak the user can drag that changes nothing.
+ *
+ * ⚠️ SKIPPED ENTIRELY WHEN THE CANVAS DEFINES `applyParams`. That is the host bridge's
+ * fourth binding path — a canvas can take the whole params object in JS and do what it
+ * likes with it, in which case no static reference to the param name need exist. Without
+ * this guard the check would report confident errors about a legitimate pattern, which is
+ * worse than not checking at all.
+ */
+export declare function checkDeadTweaks(html: string, manifest?: ControlManifest): QualityIssue[];
+/** Every quality check, in the order their messages should be read. */
+export declare function runQualityChecks(html: string, manifest?: ControlManifest): QualityIssue[];