@printwithsynergy/artwork-pdf-editor 0.3.0 → 0.5.0

package/dist/components/ContrastLegibilityPanel.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Wave 4 P4 — Print contrast / legibility panel.
+ *
+ * Print contrast and screen contrast are different problems —
+ * what passes WCAG digital can fail on uncoated kraft. P4
+ * surfaces ink-vs-substrate Lab ΔE / neutral-density contrast,
+ * min legible text size, and reverse-on-busy-image warnings
+ * sourced from a host-supplied loader (typically lint-pdf's
+ * print-contrast analyzer).
+ *
+ * @public
+ */
+import type { ReactElement } from "react";
+/** @public */
+export type ContrastLegibilitySeverity = "error" | "warn" | "info";
+/** @public */
+export type ContrastLegibilityCategory = "contrast" | "text-size" | "reverse-on-image" | "neutral-density" | "other";
+/** @public */
+export type ContrastLegibilityFinding = {
+    id: string;
+    category: ContrastLegibilityCategory;
+    severity: ContrastLegibilitySeverity;
+    summary: string;
+    recommendation?: string;
+    objectId?: string;
+    deltaE?: number;
+};
+/** @public */
+export type ContrastLegibilityLoaderFn = () => Promise<readonly ContrastLegibilityFinding[]>;
+/** @public */
+export type ContrastLegibilityFilter = {
+    severity?: ContrastLegibilitySeverity;
+    category?: ContrastLegibilityCategory;
+};
+/** @public */
+export type ContrastLegibilityGroup = {
+    severity: ContrastLegibilitySeverity;
+    findings: readonly ContrastLegibilityFinding[];
+};
+/** @public */
+export declare const CONTRAST_LEGIBILITY_SEVERITY_ORDER: readonly ContrastLegibilitySeverity[];
+/**
+ * Pure helper — filters by severity / category. Returns a new
+ * array preserving input order. Pure function.
+ *
+ * @public
+ */
+export declare function filterContrastLegibilityFindings(findings: readonly ContrastLegibilityFinding[], filter: ContrastLegibilityFilter): readonly ContrastLegibilityFinding[];
+/**
+ * Pure helper — groups findings by severity in
+ * {@link CONTRAST_LEGIBILITY_SEVERITY_ORDER}. Always returns a
+ * stable three-bucket shape. Pure function.
+ *
+ * @public
+ */
+export declare function groupContrastLegibilityFindingsBySeverity(findings: readonly ContrastLegibilityFinding[]): readonly ContrastLegibilityGroup[];
+/** @public */
+export type ContrastLegibilityPanelProps = {
+    loader: ContrastLegibilityLoaderFn;
+    filterSeverity?: ContrastLegibilitySeverity;
+    filterCategory?: ContrastLegibilityCategory;
+    onSelect?: (finding: ContrastLegibilityFinding) => void;
+};
+/**
+ * Stateful panel — loads finding stream, surfaces filtered +
+ * grouped list, emits onSelect on row click.
+ *
+ * @public
+ */
+export declare function ContrastLegibilityPanel({ loader, filterSeverity, filterCategory, onSelect, }: ContrastLegibilityPanelProps): ReactElement;
+//# sourceMappingURL=ContrastLegibilityPanel.d.ts.map

package/dist/components/ContrastLegibilityPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContrastLegibilityPanel.d.ts","sourceRoot":"","sources":["../../src/components/ContrastLegibilityPanel.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAG1C,cAAc;AACd,MAAM,MAAM,0BAA0B,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AACnE,cAAc;AACd,MAAM,MAAM,0BAA0B,GAClC,UAAU,GACV,WAAW,GACX,kBAAkB,GAClB,iBAAiB,GACjB,OAAO,CAAC;AACZ,cAAc;AACd,MAAM,MAAM,yBAAyB,GAAG;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,0BAA0B,CAAC;IACrC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AACF,cAAc;AACd,MAAM,MAAM,0BAA0B,GAAG,MAAM,OAAO,CAAC,SAAS,yBAAyB,EAAE,CAAC,CAAC;AAC7F,cAAc;AACd,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,EAAE,0BAA0B,CAAC;IACtC,QAAQ,CAAC,EAAE,0BAA0B,CAAC;CACvC,CAAC;AACF,cAAc;AACd,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;CAChD,CAAC;AAEF,cAAc;AACd,eAAO,MAAM,kCAAkC,EAAE,SAAS,0BAA0B,EAInF,CAAC;AAQF;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,SAAS,yBAAyB,EAAE,EAC9C,MAAM,EAAE,wBAAwB,GAC/B,SAAS,yBAAyB,EAAE,CAMtC;AAED;;;;;;GAMG;AACH,wBAAgB,yCAAyC,CACvD,QAAQ,EAAE,SAAS,yBAAyB,EAAE,GAC7C,SAAS,uBAAuB,EAAE,CASpC;AAED,cAAc;AACd,MAAM,MAAM,4BAA4B,GAAG;IACzC,MAAM,EAAE,0BAA0B,CAAC;IACnC,cAAc,CAAC,EAAE,0BAA0B,CAAC;IAC5C,cAAc,CAAC,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,CAAC;CACzD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,MAAM,EACN,cAAc,EACd,cAAc,EACd,QAAQ,GACT,EAAE,4BAA4B,GAAG,YAAY,CAgI7C"}

package/dist/components/ContrastLegibilityPanel.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from "react";
+/** @public */
+export const CONTRAST_LEGIBILITY_SEVERITY_ORDER = [
+    "error",
+    "warn",
+    "info",
+];
+const SEVERITY_COLORS = {
+    error: "#a00",
+    warn: "#a60",
+    info: "#06a",
+};
+/**
+ * Pure helper — filters by severity / category. Returns a new
+ * array preserving input order. Pure function.
+ *
+ * @public
+ */
+export function filterContrastLegibilityFindings(findings, filter) {
+    return findings.filter((f) => {
+        if (filter.severity && f.severity !== filter.severity)
+            return false;
+        if (filter.category && f.category !== filter.category)
+            return false;
+        return true;
+    });
+}
+/**
+ * Pure helper — groups findings by severity in
+ * {@link CONTRAST_LEGIBILITY_SEVERITY_ORDER}. Always returns a
+ * stable three-bucket shape. Pure function.
+ *
+ * @public
+ */
+export function groupContrastLegibilityFindingsBySeverity(findings) {
+    const buckets = new Map(CONTRAST_LEGIBILITY_SEVERITY_ORDER.map((s) => [s, []]));
+    for (const f of findings)
+        buckets.get(f.severity)?.push(f);
+    return CONTRAST_LEGIBILITY_SEVERITY_ORDER.map((severity) => ({
+        severity,
+        findings: buckets.get(severity) ?? [],
+    }));
+}
+/**
+ * Stateful panel — loads finding stream, surfaces filtered +
+ * grouped list, emits onSelect on row click.
+ *
+ * @public
+ */
+export function ContrastLegibilityPanel({ loader, filterSeverity, filterCategory, onSelect, }) {
+    const [findings, setFindings] = useState(null);
+    const [error, setError] = useState(null);
+    const [loading, setLoading] = useState(true);
+    useEffect(() => {
+        let disposed = false;
+        setLoading(true);
+        setError(null);
+        setFindings(null);
+        void (async () => {
+            try {
+                const next = await loader();
+                if (!disposed)
+                    setFindings(next);
+            }
+            catch (err) {
+                if (!disposed)
+                    setError(err instanceof Error ? err.message : String(err));
+            }
+            finally {
+                if (!disposed)
+                    setLoading(false);
+            }
+        })();
+        return () => {
+            disposed = true;
+        };
+    }, [loader]);
+    const groups = useMemo(() => {
+        if (!findings)
+            return null;
+        const filtered = filterContrastLegibilityFindings(findings, {
+            ...(filterSeverity && { severity: filterSeverity }),
+            ...(filterCategory && { category: filterCategory }),
+        });
+        return groupContrastLegibilityFindingsBySeverity(filtered);
+    }, [findings, filterSeverity, filterCategory]);
+    if (loading) {
+        return (_jsx("output", { "data-testid": "contrast-legibility-panel", "aria-live": "polite", style: { display: "block", padding: "0.5rem", opacity: 0.6 }, children: "Loading contrast / legibility findings\u2026" }));
+    }
+    if (error) {
+        return (_jsxs("div", { "data-testid": "contrast-legibility-panel", role: "alert", style: { padding: "0.5rem", color: "#a00" }, children: ["Couldn't load contrast / legibility findings: ", error] }));
+    }
+    if (!groups)
+        return _jsx("div", { "data-testid": "contrast-legibility-panel" });
+    const total = groups.reduce((s, g) => s + g.findings.length, 0);
+    return (_jsxs("div", { "data-testid": "contrast-legibility-panel", style: { padding: "0.5rem" }, children: [_jsx("header", { style: { marginBottom: "0.5rem" }, children: _jsxs("h3", { style: { margin: 0, fontSize: "0.875rem" }, children: ["Contrast & legibility (", total, ")"] }) }), total === 0 && (_jsx("div", { style: { opacity: 0.6, fontSize: "0.875rem" }, children: findings && findings.length > 0
+                    ? "No findings match the current filter."
+                    : "No contrast or legibility issues detected." })), groups.map((group) => {
+                if (group.findings.length === 0)
+                    return null;
+                return (_jsxs("section", { "data-testid": `contrast-legibility-group-${group.severity}`, style: { marginBottom: "0.75rem" }, children: [_jsxs("h4", { style: {
+                                margin: "0 0 0.25rem 0",
+                                fontSize: "0.75rem",
+                                color: SEVERITY_COLORS[group.severity],
+                                textTransform: "uppercase",
+                                letterSpacing: "0.05em",
+                            }, children: [group.severity, " (", group.findings.length, ")"] }), _jsx("ul", { style: { listStyle: "none", padding: 0, margin: 0 }, children: group.findings.map((finding) => (_jsx("li", { style: { marginBottom: "0.25rem" }, children: onSelect ? (_jsxs("button", { type: "button", onClick: () => onSelect(finding), style: {
+                                        display: "block",
+                                        width: "100%",
+                                        padding: "0.375rem 0.5rem",
+                                        background: "transparent",
+                                        border: "1px solid #ddd",
+                                        borderRadius: 4,
+                                        textAlign: "left",
+                                        cursor: "pointer",
+                                        fontSize: "0.8125rem",
+                                    }, children: [finding.summary, finding.deltaE !== undefined && (_jsxs("span", { style: { color: "#595959", marginLeft: "0.375rem" }, children: ["(\u0394E ", finding.deltaE.toFixed(2), ")"] }))] })) : (_jsx("div", { style: { padding: "0.375rem 0.5rem", fontSize: "0.8125rem" }, children: finding.summary })) }, finding.id))) })] }, group.severity));
+            })] }));
+}
+//# sourceMappingURL=ContrastLegibilityPanel.js.map

package/dist/components/ContrastLegibilityPanel.js.map

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

package/dist/components/DirectionIndicatorsOverlay.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Wave 4 S6 — Direction indicators overlay.
+ *
+ * Production needs to see non-printing context indicators that
+ * never make it into the final artwork: corrugated-flute axis,
+ * paper-grain axis, web-direction arrow, and an
+ * inside-vs-outside-print badge. None of these get written into
+ * the PDF — they're a non-printing overlay the editor renders on
+ * top of the canvas so the operator catches mirroring / grain
+ * mismatches before the file leaves the design seat.
+ *
+ * Pure-render component. Hosts pass in a
+ * {@link DirectionIndicatorsSpec}; the overlay positions a small
+ * legend chip + the four indicator markers at the page extents.
+ *
+ * @public
+ */
+import { type ReactElement } from "react";
+/**
+ * Direction-context spec emitted by the host (typically derived
+ * from `printContext.substrate` + per-page metadata).
+ *
+ * @public
+ */
+export type DirectionIndicatorsSpec = {
+    /** Page extents in pixels — matches the canvas viewport. */
+    widthPx: number;
+    heightPx: number;
+    /** Flute / grain axis. Absent = unknown (not rendered). */
+    fluteAxis?: "horizontal" | "vertical";
+    grainAxis?: "horizontal" | "vertical";
+    /** Web direction — the direction the substrate travels through
+     *  the press. Absent = unknown (not rendered). */
+    webDirection?: "left-to-right" | "right-to-left" | "top-to-bottom" | "bottom-to-top";
+    /** Print side. When `"inside"`, the canvas should render the
+     *  page mirrored — the editor surfaces this badge so the
+     *  operator can confirm the right side is being authored. */
+    printSide?: "outside" | "inside";
+};
+/**
+ * Props for the {@link DirectionIndicatorsOverlay}.
+ *
+ * @public
+ */
+export type DirectionIndicatorsOverlayProps = {
+    spec: DirectionIndicatorsSpec;
+};
+/**
+ * Pure-render overlay. Anchored absolutely; consumers wrap the
+ * canvas + this in a relatively-positioned container.
+ *
+ * @public
+ */
+export declare function DirectionIndicatorsOverlay({ spec, }: DirectionIndicatorsOverlayProps): ReactElement;
+//# sourceMappingURL=DirectionIndicatorsOverlay.d.ts.map

package/dist/components/DirectionIndicatorsOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DirectionIndicatorsOverlay.d.ts","sourceRoot":"","sources":["../../src/components/DirectionIndicatorsOverlay.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAS,MAAM,OAAO,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACtC,SAAS,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACtC;sDACkD;IAClD,YAAY,CAAC,EAAE,eAAe,GAAG,eAAe,GAAG,eAAe,GAAG,eAAe,CAAC;IACrF;;iEAE6D;IAC7D,SAAS,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;CAClC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,uBAAuB,CAAC;CAC/B,CAAC;AAKF;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,IAAI,GACL,EAAE,+BAA+B,GAAG,YAAY,CAoFhD"}

package/dist/components/DirectionIndicatorsOverlay.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Wave 4 S6 — Direction indicators overlay.
+ *
+ * Production needs to see non-printing context indicators that
+ * never make it into the final artwork: corrugated-flute axis,
+ * paper-grain axis, web-direction arrow, and an
+ * inside-vs-outside-print badge. None of these get written into
+ * the PDF — they're a non-printing overlay the editor renders on
+ * top of the canvas so the operator catches mirroring / grain
+ * mismatches before the file leaves the design seat.
+ *
+ * Pure-render component. Hosts pass in a
+ * {@link DirectionIndicatorsSpec}; the overlay positions a small
+ * legend chip + the four indicator markers at the page extents.
+ *
+ * @public
+ */
+import { useId } from "react";
+const BADGE_BG = "rgba(20, 20, 20, 0.78)";
+const BADGE_FG = "#f4ece6";
+/**
+ * Pure-render overlay. Anchored absolutely; consumers wrap the
+ * canvas + this in a relatively-positioned container.
+ *
+ * @public
+ */
+export function DirectionIndicatorsOverlay({ spec, }) {
+    const { widthPx, heightPx, fluteAxis, grainAxis, webDirection, printSide, } = spec;
+    // Compose the legend line by line, skipping rows the host left
+    // unset so dieless-print jobs don't see a stub legend.
+    const legend = [];
+    if (fluteAxis)
+        legend.push(`flute: ${fluteAxis}`);
+    if (grainAxis)
+        legend.push(`grain: ${grainAxis}`);
+    if (webDirection)
+        legend.push(`web: ${webDirection}`);
+    if (printSide)
+        legend.push(`side: ${printSide}-print`);
+    return (_jsxs("div", { "data-testid": "direction-indicators-overlay", "aria-hidden": "true", style: {
+            position: "absolute",
+            top: 0,
+            left: 0,
+            width: widthPx,
+            height: heightPx,
+            pointerEvents: "none",
+        }, children: [fluteAxis && (_jsx(FluteHatch, { axis: fluteAxis, widthPx: widthPx, heightPx: heightPx })), webDirection && (_jsx(WebArrow, { direction: webDirection, widthPx: widthPx, heightPx: heightPx })), printSide === "inside" && (_jsx("div", { "data-testid": "direction-indicators-mirror-warning", style: {
+                    position: "absolute",
+                    top: 12,
+                    right: 12,
+                    padding: "0.25rem 0.5rem",
+                    fontSize: "0.6875rem",
+                    background: "#a00",
+                    color: "#fff",
+                    borderRadius: 4,
+                    fontWeight: 600,
+                    letterSpacing: "0.04em",
+                    textTransform: "uppercase",
+                }, children: "INSIDE-PRINT \u2014 mirror before output" })), legend.length > 0 && (_jsx("div", { "data-testid": "direction-indicators-legend", style: {
+                    position: "absolute",
+                    bottom: 12,
+                    left: 12,
+                    padding: "0.375rem 0.5rem",
+                    background: BADGE_BG,
+                    color: BADGE_FG,
+                    fontSize: "0.6875rem",
+                    lineHeight: 1.4,
+                    borderRadius: 4,
+                    fontFamily: "monospace",
+                }, children: legend.map((row) => (_jsx("div", { children: row }, row))) }))] }));
+}
+function FluteHatch({ axis, widthPx, heightPx, }) {
+    // 16-line hatch across the page, faint enough not to obscure
+    // artwork. Horizontal flute → vertical hatch (perpendicular)
+    // and vice-versa — the hatch direction tracks the corrugated
+    // peak ridges, not the channel-axis.
+    const lines = 16;
+    const isVerticalHatch = axis === "horizontal";
+    return (_jsxs("svg", { "data-testid": "direction-indicators-flute-hatch", width: widthPx, height: heightPx, style: { position: "absolute", top: 0, left: 0, opacity: 0.18 }, children: [_jsx("title", { children: `flute hatch (${axis})` }), Array.from({ length: lines }, (_, i) => {
+                const t = (i + 0.5) / lines;
+                if (isVerticalHatch) {
+                    const x = t * widthPx;
+                    return (_jsx("line", { x1: x, y1: 0, x2: x, y2: heightPx, stroke: "#06a", strokeWidth: 1 }, i));
+                }
+                const y = t * heightPx;
+                return (_jsx("line", { x1: 0, y1: y, x2: widthPx, y2: y, stroke: "#06a", strokeWidth: 1 }, i));
+            })] }));
+}
+function WebArrow({ direction, widthPx, heightPx, }) {
+    // Per-instance marker id so multiple overlays in the same DOM
+    // (e.g. a multi-page editor with one indicator per page) don't
+    // collide on a shared `id="web-arrowhead"` — only one definition
+    // would be honoured and the rest would render unarrowed lines.
+    const rawId = useId();
+    const markerId = `web-arrowhead-${rawId.replace(/[^a-zA-Z0-9_-]/g, "")}`;
+    const cx = widthPx / 2;
+    const cy = heightPx / 2;
+    const len = Math.min(widthPx, heightPx) * 0.5;
+    let x1 = cx;
+    let y1 = cy;
+    let x2 = cx;
+    let y2 = cy;
+    switch (direction) {
+        case "left-to-right":
+            x1 = cx - len / 2;
+            x2 = cx + len / 2;
+            break;
+        case "right-to-left":
+            x1 = cx + len / 2;
+            x2 = cx - len / 2;
+            break;
+        case "top-to-bottom":
+            y1 = cy - len / 2;
+            y2 = cy + len / 2;
+            break;
+        case "bottom-to-top":
+            y1 = cy + len / 2;
+            y2 = cy - len / 2;
+            break;
+    }
+    return (_jsxs("svg", { "data-testid": "direction-indicators-web-arrow", width: widthPx, height: heightPx, style: { position: "absolute", top: 0, left: 0, opacity: 0.5 }, children: [_jsx("title", { children: `web direction (${direction})` }), _jsx("defs", { children: _jsx("marker", { id: markerId, viewBox: "0 0 10 10", refX: 8, refY: 5, markerWidth: 6, markerHeight: 6, orient: "auto", children: _jsx("path", { d: "M0 0 L10 5 L0 10 z", fill: "#fc5102" }) }) }), _jsx("line", { x1: x1, y1: y1, x2: x2, y2: y2, stroke: "#fc5102", strokeWidth: 3, markerEnd: `url(#${markerId})` })] }));
+}
+//# sourceMappingURL=DirectionIndicatorsOverlay.js.map

package/dist/components/DirectionIndicatorsOverlay.js.map

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

package/dist/components/StreamingRenderProgress.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Wave 3 O3 — Streaming render progress panel.
+ *
+ * Shows live per-page progress for a long render that returns
+ * `text/event-stream` via `POST /v1/compose/stream`. The host wires
+ * a {@link StreamingRenderConnectFn} adapter (typically backed by an
+ * `EventSource` or a stubbed `AsyncIterable` for tests); the panel
+ * owns the event accumulator and renders the summary returned by
+ * {@link summarizeStreamingProgress}.
+ *
+ * @public
+ */
+import type { ReactElement } from "react";
+import { type StreamingRenderEvent } from "../lib/streaming-render";
+/**
+ * Host adapter — opens a stream and returns an async iterable of
+ * events plus a `close()` to abort. The shape lets a host wire an
+ * `EventSource` over `/v1/compose/stream`, a `fetch()` with
+ * `ReadableStream`, or a test mock interchangeably.
+ *
+ * The panel iterates events until the stream ends; on unmount it
+ * calls `close()` to abort.
+ *
+ * @public
+ */
+export type StreamingRenderConnectFn = () => {
+    events: AsyncIterable<StreamingRenderEvent>;
+    close: () => void;
+};
+/**
+ * Configuration for the {@link StreamingRenderProgress}.
+ *
+ * @public
+ */
+export type StreamingRenderProgressProps = {
+    /** Connect adapter. When absent the panel renders in
+     *  "ready to connect" mode and never opens a stream. */
+    connect?: StreamingRenderConnectFn;
+    /** Fires when the stream's `done` event lands — typically used
+     *  to redirect to the rendered PDF or refresh the job list. */
+    onDone?: (info: {
+        pdfSha256: string;
+        cacheKey: string;
+    }) => void;
+    /** Fires when the stream emits an error event — typically used
+     *  for telemetry / fallback to non-streaming render. */
+    onError?: (info: {
+        message: string;
+        code: string;
+    }) => void;
+};
+/**
+ * Stateful streaming-progress panel. Connects on mount when
+ * `connect` is supplied, accumulates events, surfaces summary +
+ * per-page badge list, and calls `onDone` / `onError` once.
+ *
+ * @public
+ */
+export declare function StreamingRenderProgress({ connect, onDone, onError, }: StreamingRenderProgressProps): ReactElement;
+//# sourceMappingURL=StreamingRenderProgress.d.ts.map

package/dist/components/StreamingRenderProgress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamingRenderProgress.d.ts","sourceRoot":"","sources":["../../src/components/StreamingRenderProgress.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAE1C,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM;IAC3C,MAAM,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC;4DACwD;IACxD,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC;mEAC+D;IAC/D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACjE;4DACwD;IACxD,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC7D,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,OAAO,EACP,MAAM,EACN,OAAO,GACR,EAAE,4BAA4B,GAAG,YAAY,CAwI7C"}

package/dist/components/StreamingRenderProgress.js

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { summarizeStreamingProgress, } from "../lib/streaming-render";
+/**
+ * Stateful streaming-progress panel. Connects on mount when
+ * `connect` is supplied, accumulates events, surfaces summary +
+ * per-page badge list, and calls `onDone` / `onError` once.
+ *
+ * @public
+ */
+export function StreamingRenderProgress({ connect, onDone, onError, }) {
+    const [events, setEvents] = useState([]);
+    const handlersRef = useRef({ onDone, onError });
+    handlersRef.current = { onDone, onError };
+    useEffect(() => {
+        if (!connect)
+            return;
+        const handle = connect();
+        let disposed = false;
+        void (async () => {
+            try {
+                for await (const ev of handle.events) {
+                    if (disposed)
+                        return;
+                    setEvents((prev) => [...prev, ev]);
+                    if (ev.kind === "done") {
+                        handlersRef.current.onDone?.({
+                            pdfSha256: ev.pdfSha256,
+                            cacheKey: ev.cacheKey,
+                        });
+                    }
+                    else if (ev.kind === "error") {
+                        handlersRef.current.onError?.({ message: ev.message, code: ev.code });
+                    }
+                }
+            }
+            catch {
+                // Stream tear-down — surface as a synthetic error event so
+                // the summarizer flips to "error" status without the
+                // consumer having to special-case missing events.
+                if (!disposed) {
+                    setEvents((prev) => [
+                        ...prev,
+                        { kind: "error", message: "Stream closed unexpectedly.", code: "E_STREAM_ABORTED" },
+                    ]);
+                }
+            }
+        })();
+        return () => {
+            disposed = true;
+            handle.close();
+        };
+    }, [connect]);
+    const summary = summarizeStreamingProgress(events);
+    return (_jsxs("div", { "data-testid": "streaming-render-progress", style: { padding: "0.5rem" }, children: [_jsxs("header", { style: {
+                    display: "flex",
+                    justifyContent: "space-between",
+                    alignItems: "baseline",
+                    marginBottom: "0.375rem",
+                }, children: [_jsx("h3", { style: { margin: 0, fontSize: "0.875rem" }, children: "Render progress" }), _jsxs("span", { style: { fontSize: "0.75rem", color: "#595959" }, children: [summary.percent, "% \u00B7 ", summary.completedPages, "/", summary.totalPages || "?"] })] }), _jsx("div", { "aria-label": "Render progress", role: "progressbar", "aria-valuenow": summary.percent, "aria-valuemin": 0, "aria-valuemax": 100, style: {
+                    background: "#eee",
+                    height: 6,
+                    borderRadius: 3,
+                    overflow: "hidden",
+                    marginBottom: "0.5rem",
+                }, children: _jsx("div", { style: {
+                        width: `${summary.percent}%`,
+                        height: "100%",
+                        background: summary.status === "error"
+                            ? "#a00"
+                            : summary.status === "done"
+                                ? "#080"
+                                : "#06a",
+                        transition: "width 200ms linear",
+                    } }) }), summary.status === "error" && summary.errorMessage && (_jsx("div", { role: "alert", style: { fontSize: "0.75rem", color: "#a00", marginBottom: "0.375rem" }, children: summary.errorMessage })), summary.status !== "error" && summary.totalPages > 0 && (_jsx("ul", { "aria-label": "Per-page status", style: {
+                    display: "flex",
+                    flexWrap: "wrap",
+                    gap: "0.25rem",
+                    listStyle: "none",
+                    padding: 0,
+                    margin: 0,
+                }, children: Array.from({ length: summary.totalPages }, (_, i) => {
+                    // O(1) lookup against the pre-computed Set so we don't
+                    // re-scan the raw events array on every badge.
+                    const done = summary.completedPageIndices.has(i);
+                    const active = summary.currentPage === i;
+                    const bg = done ? "#080" : active ? "#06a" : "#ccc";
+                    return (_jsx("li", { title: `Page ${i + 1}: ${done ? "done" : active ? "rendering" : "pending"}`, style: {
+                            width: 16,
+                            height: 16,
+                            borderRadius: 2,
+                            background: bg,
+                            border: "1px solid #999",
+                        } }, i));
+                }) })), summary.receivedBytes > 0 && (_jsxs("div", { style: { fontSize: "0.6875rem", color: "#595959", marginTop: "0.375rem" }, children: [(summary.receivedBytes / 1024).toFixed(1), " KB received"] })), !connect && (_jsx("div", { style: { fontSize: "0.75rem", color: "#595959" }, children: "Streaming adapter not wired." }))] }));
+}
+//# sourceMappingURL=StreamingRenderProgress.js.map

package/dist/components/StreamingRenderProgress.js.map

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

package/dist/components/SubstrateSimOverlay.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Wave 4 P2 — Substrate show-through simulation overlay.
+ *
+ * White artboards hide everything the substrate will affect:
+ * kraft tints unprinted regions brown, metallised film reflects
+ * through low-opacity art, clear PE shows nothing where ink
+ * doesn't cover. P2 paints a substrate-coloured rectangle
+ * underneath the canvas so the operator sees what the press will
+ * actually deliver before exporting. Pairs with C2 (white
+ * underbase) — host can toggle the underbase on/off above this
+ * overlay to confirm masking.
+ *
+ * Pure-render component — host passes the substrate descriptor
+ * (mirrors `printContext.substrate`); the overlay is anchored
+ * absolutely. Consumers wrap canvas + overlay in a
+ * relatively-positioned container with the substrate sim *behind*
+ * the canvas (lower z-index).
+ *
+ * @public
+ */
+import type { ReactElement } from "react";
+/**
+ * Substrate descriptor that drives the simulation. Four fields
+ * map directly to `printContext.substrate`.
+ *
+ * @public
+ */
+export type SubstrateSimSpec = {
+    widthPx: number;
+    heightPx: number;
+    /** CSS color of the substrate (e.g. `"#d2b48c"` kraft,
+     *  `"#c0c0c0"` metallised, `"transparent"` clear PE). */
+    color: string;
+    /** 0..1. 1 = fully opaque (paper); < 1 = substrate colour
+     *  shows through unprinted regions but ink dominates printed. */
+    opacity: number;
+    /** Finish modifier — gloss adds a subtle sheen, satin a
+     *  weaker one, matte / uncoated render flat (uncoated adds
+     *  faint pulp-paper noise). */
+    finish: "matte" | "gloss" | "satin" | "uncoated";
+};
+/**
+ * Props for the {@link SubstrateSimOverlay}.
+ *
+ * @public
+ */
+export type SubstrateSimOverlayProps = {
+    spec: SubstrateSimSpec;
+};
+/**
+ * Pure-render substrate simulation overlay.
+ *
+ * @public
+ */
+export declare function SubstrateSimOverlay({ spec }: SubstrateSimOverlayProps): ReactElement;
+//# sourceMappingURL=SubstrateSimOverlay.d.ts.map

package/dist/components/SubstrateSimOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubstrateSimOverlay.d.ts","sourceRoot":"","sources":["../../src/components/SubstrateSimOverlay.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB;6DACyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd;qEACiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB;;mCAE+B;IAC/B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,CAAC;CAClD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,gBAAgB,CAAC;CACxB,CAAC;AAeF;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,IAAI,EAAE,EAAE,wBAAwB,GAAG,YAAY,CA4BpF"}