@printwithsynergy/artwork-pdf-editor 0.2.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,62 @@
+artworkPDF — WYSIWYG label & packaging artwork editor
+Copyright (C) 2024-2026 Think Neverland LLC
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public
+License along with this program. If not, see
+<https://www.gnu.org/licenses/>.
+
+---
+
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), to help you ensure that you receive source code or can
+get it if you want it, to help you ensure that you can give other people
+a copy of it, and let you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in individual component, which are widely deployed on
+network servers, become available to improve those servers too. Whether
+this happens depends on what the server software does with the
+modifications made in it.  The GNU Affero General Public License
+requires that modified source code be made available to the users.
+In the case of a network server, this is relatively easy to achieve.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+  See <https://www.gnu.org/licenses/agpl-3.0.txt> for the full license text.

package/dist/components/AccessibilityHintsPanel.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Wave 4 AI5 — Accessibility hints panel.
+ *
+ * Fourth panel in the Wave 4 AI family alongside AI1
+ * {@link DesignSuggestionsPanel} (proactive design hints), AI2
+ * {@link SmartSpotMatchPanel} (ΔE-ranked PANTONE matcher), and AI3
+ * {@link PreflightAutoFixPanel} (preflight remediation). AI5 surfaces
+ * accessibility findings (low contrast, missing alt text, text-size
+ * minimums, color-only signalling) sourced from a host-supplied
+ * loader. Rules-engine, ML adapter, or a tenant-deployed lint-pdf
+ * accessibility profile all fit the same loader contract.
+ *
+ * Findings carry an optional `objectId` so the host can scroll the
+ * offending canvas object into view, and an optional `severity` for
+ * triage. The same three-tier severity vocabulary as B2
+ * BrandConsistencyPanel — kept identical on purpose so a single host
+ * triage UI can render both panels' rows the same way.
+ *
+ * @public
+ */
+import type { ReactElement } from "react";
+/**
+ * Severity of an accessibility finding. Mirrors B2's vocabulary
+ * verbatim so hosts that surface both panels in one triage list get
+ * consistent ordering and colors.
+ *
+ * @public
+ */
+export type AccessibilitySeverity = "error" | "warn" | "info";
+/**
+ * Category an accessibility finding belongs to. Hosts can render
+ * category chips for quick scanning; the panel groups findings by
+ * severity, not category.
+ *
+ * @public
+ */
+export type AccessibilityCategory = "contrast" | "alt-text" | "text-size" | "color-only" | "structure" | "other";
+/**
+ * One accessibility finding. The optional `recommendation` is a
+ * single short remediation hint surfaced as a secondary line in the
+ * row; the optional `objectId` lets the host wire a focus / scroll
+ * affordance to the offending canvas object.
+ *
+ * @public
+ */
+export type AccessibilityFinding = {
+    /** Stable identifier — the panel uses it as the React key and
+     *  exposes it through `onSelect`. */
+    id: string;
+    category: AccessibilityCategory;
+    severity: AccessibilitySeverity;
+    summary: string;
+    /** Optional short remediation hint (one line). */
+    recommendation?: string;
+    /** Optional id of the canvas object the finding applies to. */
+    objectId?: string;
+};
+/**
+ * Host adapter — resolves the full accessibility finding list for the
+ * active document. Rejects on transport / validation errors and the
+ * panel surfaces the message inline. Hosts should memoize the
+ * function with `useCallback` so an unrelated parent re-render doesn't
+ * trigger a spurious refetch.
+ *
+ * @public
+ */
+export type AccessibilityHintsLoaderFn = () => Promise<readonly AccessibilityFinding[]>;
+/**
+ * Filter spec accepted by {@link filterAccessibilityFindings}.
+ *
+ * @public
+ */
+export type AccessibilityFilter = {
+    /** Pre-filter to a single severity. Absent → all severities. */
+    severity?: AccessibilitySeverity;
+    /** Pre-filter to a single category. Absent → all categories. */
+    category?: AccessibilityCategory;
+};
+/**
+ * Result row from {@link groupAccessibilityFindingsBySeverity}.
+ *
+ * @public
+ */
+export type AccessibilityGroup = {
+    severity: AccessibilitySeverity;
+    findings: readonly AccessibilityFinding[];
+};
+/**
+ * Canonical severity order — errors first so press-blocking issues
+ * surface at the top. Identical to B2's order on purpose.
+ *
+ * @public
+ */
+export declare const ACCESSIBILITY_SEVERITY_ORDER: readonly AccessibilitySeverity[];
+/**
+ * Pure helper — filters findings by severity / category. Returns a
+ * new array; preserves input order. Pure function.
+ *
+ * @public
+ */
+export declare function filterAccessibilityFindings(findings: readonly AccessibilityFinding[], filter: AccessibilityFilter): readonly AccessibilityFinding[];
+/**
+ * Pure helper — groups findings by severity in
+ * {@link ACCESSIBILITY_SEVERITY_ORDER}. Returns a stable three-bucket
+ * shape so renderers iterate without absent-key checks.
+ *
+ * Pure function.
+ *
+ * @public
+ */
+export declare function groupAccessibilityFindingsBySeverity(findings: readonly AccessibilityFinding[]): readonly AccessibilityGroup[];
+/**
+ * Configuration for the {@link AccessibilityHintsPanel}. The host
+ * always supplies the {@link AccessibilityHintsLoaderFn}; the
+ * optional `onSelect` callback lets the host wire a focus affordance
+ * (jump to the offending canvas object, focus the matching property
+ * editor row, etc.).
+ *
+ * @public
+ */
+export type AccessibilityHintsPanelProps = {
+    loader: AccessibilityHintsLoaderFn;
+    /** Optional severity pre-filter applied before grouping. */
+    filterSeverity?: AccessibilitySeverity;
+    /** Optional category pre-filter applied before grouping. */
+    filterCategory?: AccessibilityCategory;
+    /** Id of the currently active finding — the matching row renders
+     *  in the "active" style. Hosts wire this to whichever surface
+     *  drives selection. */
+    activeFindingId?: string;
+    /** Fired when the user clicks a row. */
+    onSelect?: (finding: AccessibilityFinding) => void;
+};
+/**
+ * Stateful panel — loads the finding stream on mount, surfaces the
+ * filtered + grouped list, and emits `onSelect` on row click.
+ * Handles loading / error / empty states inline.
+ *
+ * @public
+ */
+export declare function AccessibilityHintsPanel({ loader, filterSeverity, filterCategory, activeFindingId, onSelect, }: AccessibilityHintsPanelProps): ReactElement;
+//# sourceMappingURL=AccessibilityHintsPanel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AccessibilityHintsPanel.d.ts","sourceRoot":"","sources":["../../src/components/AccessibilityHintsPanel.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAG1C;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAC7B,UAAU,GACV,UAAU,GACV,WAAW,GACX,YAAY,GACZ,WAAW,GACX,OAAO,CAAC;AAEZ;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;yCACqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,qBAAqB,CAAC;IAChC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,0BAA0B,GAAG,MAAM,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAAC;AAExF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,qBAAqB,CAAC;IAChC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,qBAAqB,EAIxE,CAAC;AAcF;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,EACzC,MAAM,EAAE,mBAAmB,GAC1B,SAAS,oBAAoB,EAAE,CAMjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,SAAS,oBAAoB,EAAE,GACxC,SAAS,kBAAkB,EAAE,CAW/B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,MAAM,EAAE,0BAA0B,CAAC;IACnC,4DAA4D;IAC5D,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,4DAA4D;IAC5D,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC;;4BAEwB;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAC;CACpD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,MAAM,EACN,cAAc,EACd,cAAc,EACd,eAAe,EACf,QAAQ,GACT,EAAE,4BAA4B,GAAG,YAAY,CA8G7C"}

package/dist/components/AccessibilityHintsPanel.js

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from "react";
+/**
+ * Canonical severity order — errors first so press-blocking issues
+ * surface at the top. Identical to B2's order on purpose.
+ *
+ * @public
+ */
+export const ACCESSIBILITY_SEVERITY_ORDER = [
+    "error",
+    "warn",
+    "info",
+];
+const SEVERITY_LABELS = {
+    error: "Errors",
+    warn: "Warnings",
+    info: "Info",
+};
+const SEVERITY_COLORS = {
+    error: "#a00",
+    warn: "#a60",
+    info: "#06a",
+};
+/**
+ * Pure helper — filters findings by severity / category. Returns a
+ * new array; preserves input order. Pure function.
+ *
+ * @public
+ */
+export function filterAccessibilityFindings(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 ACCESSIBILITY_SEVERITY_ORDER}. Returns a stable three-bucket
+ * shape so renderers iterate without absent-key checks.
+ *
+ * Pure function.
+ *
+ * @public
+ */
+export function groupAccessibilityFindingsBySeverity(findings) {
+    const buckets = new Map(ACCESSIBILITY_SEVERITY_ORDER.map((s) => [s, []]));
+    for (const f of findings) {
+        buckets.get(f.severity)?.push(f);
+    }
+    return ACCESSIBILITY_SEVERITY_ORDER.map((severity) => ({
+        severity,
+        findings: buckets.get(severity) ?? [],
+    }));
+}
+/**
+ * Stateful panel — loads the finding stream on mount, surfaces the
+ * filtered + grouped list, and emits `onSelect` on row click.
+ * Handles loading / error / empty states inline.
+ *
+ * @public
+ */
+export function AccessibilityHintsPanel({ loader, filterSeverity, filterCategory, activeFindingId, 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)
+                    return;
+                setFindings(next);
+            }
+            catch (err) {
+                if (disposed)
+                    return;
+                setError(err instanceof Error ? err.message : String(err));
+            }
+            finally {
+                if (!disposed)
+                    setLoading(false);
+            }
+        })();
+        return () => {
+            disposed = true;
+        };
+    }, [loader]);
+    const visibleGroups = useMemo(() => {
+        if (!findings)
+            return null;
+        const filtered = filterAccessibilityFindings(findings, {
+            ...(filterSeverity && { severity: filterSeverity }),
+            ...(filterCategory && { category: filterCategory }),
+        });
+        return groupAccessibilityFindingsBySeverity(filtered);
+    }, [findings, filterSeverity, filterCategory]);
+    if (loading) {
+        return (_jsx("output", { "data-testid": "accessibility-hints-panel", "aria-live": "polite", style: { display: "block", padding: "0.5rem", opacity: 0.6 }, children: "Loading accessibility hints\u2026" }));
+    }
+    if (error) {
+        return (_jsxs("div", { "data-testid": "accessibility-hints-panel", role: "alert", style: { padding: "0.5rem", color: "#a00" }, children: ["Couldn't load accessibility hints: ", error] }));
+    }
+    if (!visibleGroups)
+        return _jsx("div", { "data-testid": "accessibility-hints-panel" });
+    const totalVisible = visibleGroups.reduce((s, g) => s + g.findings.length, 0);
+    return (_jsxs("div", { "data-testid": "accessibility-hints-panel", style: { padding: "0.5rem" }, children: [_jsx("header", { style: { marginBottom: "0.5rem" }, children: _jsxs("h3", { style: { margin: 0, fontSize: "0.875rem" }, children: ["Accessibility hints (", totalVisible, ")"] }) }), totalVisible === 0 && (_jsx("div", { "data-testid": "accessibility-hints-panel-empty", style: { opacity: 0.6, fontSize: "0.875rem" }, children: findings && findings.length > 0
+                    ? "No findings match the current filter."
+                    : "No accessibility issues detected." })), visibleGroups.map((group) => {
+                if (group.findings.length === 0)
+                    return null;
+                return (_jsxs("section", { "data-testid": `accessibility-hints-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: [SEVERITY_LABELS[group.severity], " (", group.findings.length, ")"] }), _jsx("ul", { style: { listStyle: "none", padding: 0, margin: 0 }, children: group.findings.map((finding) => (_jsx(AccessibilityRow, { finding: finding, isActive: finding.id === activeFindingId, onSelect: onSelect }, finding.id))) })] }, group.severity));
+            })] }));
+}
+/**
+ * Renders one finding row. Intra-package helper — surface
+ * (category chip, summary, optional recommendation) is intentionally
+ * minimal so {@link AccessibilityHintsPanel} can swap it without
+ * downstream consumers depending on the shape.
+ */
+function AccessibilityRow({ finding, isActive, onSelect, }) {
+    const rowStyle = {
+        display: "block",
+        width: "100%",
+        padding: "0.375rem 0.5rem",
+        background: isActive ? "#e0ecff" : "transparent",
+        border: isActive ? "1px solid #2563eb" : "1px solid #ddd",
+        borderRadius: 4,
+        marginBottom: "0.25rem",
+        textAlign: "left",
+        cursor: onSelect ? "pointer" : "default",
+    };
+    const contents = (_jsxs(_Fragment, { children: [_jsxs("div", { style: { fontSize: "0.8125rem", fontWeight: 500 }, children: [_jsx("span", { style: {
+                            display: "inline-block",
+                            fontSize: "0.625rem",
+                            padding: "0.0625rem 0.375rem",
+                            borderRadius: 999,
+                            background: "#eee",
+                            color: "#595959",
+                            marginRight: "0.375rem",
+                        }, children: finding.category }), finding.summary] }), finding.recommendation && (_jsx("div", { style: { fontSize: "0.75rem", color: "#595959", marginTop: "0.125rem" }, children: finding.recommendation }))] }));
+    return (_jsx("li", { children: onSelect ? (_jsx("button", { type: "button", onClick: () => onSelect(finding), style: rowStyle, children: contents })) : (_jsx("div", { style: rowStyle, children: contents })) }));
+}
+//# sourceMappingURL=AccessibilityHintsPanel.js.map

package/dist/components/AccessibilityHintsPanel.js.map

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

package/dist/components/AnnotationOverlay.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Wave 4 X3 — Annotation overlay.
+ *
+ * Renders pinned author annotations from `PageV3.annotations` on top
+ * of the canvas. Three kinds, discriminated by `kind`:
+ *   - `"point"` — anchor pin with optional note
+ *   - `"area"`  — bounded rectangle with optional note
+ *   - `"text"`  — anchor pin with a required text body
+ *
+ * Pure controlled SVG overlay. No state, no DOM events beyond an
+ * optional `onSelect` click — the host owns selection / hover /
+ * popover UI and writes back to `document.pages[i].annotations`.
+ *
+ * Pairs with the discriminated union in `@artworkpdf/document-model`'s
+ * `Annotation` type. The component duplicates the wire shape locally
+ * (same pattern as `BrandAsset` / `PreflightFinding`) so the editor
+ * stays consumable without the doc-model SDK.
+ *
+ * @public
+ */
+import type { ReactElement } from "react";
+/**
+ * Fields shared by every annotation variant. Mirrors document-model's
+ * internal `AnnotationBase` shape.
+ *
+ * @public
+ */
+export type AnnotationBaseInput = {
+    id: string;
+    x: number;
+    y: number;
+    author?: string;
+    createdAt: string;
+    resolved?: boolean;
+};
+/**
+ * Pinpoint annotation — single x/y marker with an optional note.
+ * Width / height are forbidden by the union discrimination.
+ *
+ * @public
+ */
+export type PointAnnotationInput = AnnotationBaseInput & {
+    kind: "point";
+    text?: string;
+};
+/**
+ * Bounded-region annotation. `width` / `height` define a rectangle
+ * anchored at (`x`, `y`) in page coordinates. `text` is the optional
+ * note body.
+ *
+ * @public
+ */
+export type AreaAnnotationInput = AnnotationBaseInput & {
+    kind: "area";
+    width: number;
+    height: number;
+    text?: string;
+};
+/**
+ * Inline text annotation — anchor pin with a required text body.
+ * Use {@link PointAnnotationInput} when the note is optional.
+ *
+ * @public
+ */
+export type TextAnnotationInput = AnnotationBaseInput & {
+    kind: "text";
+    text: string;
+};
+/**
+ * One annotation, discriminated on `kind`. Structurally compatible
+ * with document-model's `Annotation` union.
+ *
+ * @public
+ */
+export type AnnotationOverlayAnnotation = PointAnnotationInput | AreaAnnotationInput | TextAnnotationInput;
+/**
+ * @public
+ */
+export type AnnotationOverlayProps = {
+    /** Annotations to render. Typically `PageV3.annotations ?? []`. */
+    annotations: readonly AnnotationOverlayAnnotation[];
+    /** Width of the underlying page in CSS pixels. The SVG overlay
+     *  matches the host's page-rendering surface so annotation anchors
+     *  land where the user placed them. */
+    pageWidthPx: number;
+    /** Height of the underlying page in CSS pixels. */
+    pageHeightPx: number;
+    /** When `true`, also render annotations whose `resolved` flag is
+     *  `true`. Absent / `false`: resolved annotations are hidden so
+     *  the canvas stays focused on open conversations. */
+    showResolved?: boolean;
+    /** Id of the annotation to render in the "active" style (host-
+     *  controlled hover / selection affordance). */
+    activeAnnotationId?: string;
+    /** Optional click callback. Hosts wire it to open their own
+     *  popover / sidebar showing the annotation body, author, etc. */
+    onSelect?: (annotation: AnnotationOverlayAnnotation) => void;
+};
+/**
+ * Build a screen-reader-friendly description of an annotation.
+ *
+ * Pattern: `"<status> <kind> annotation[: <truncated body>]"`. The
+ * resolved status comes first so screen readers announce it ahead of
+ * the body (matching the visual cue: greyed-out marker = resolved).
+ * Body text is truncated to 60 chars so long comments don't blow up
+ * the announcement. The internal `id` is intentionally omitted —
+ * opaque ids carry no meaning for assistive tech.
+ *
+ * Pure function; exposed so hosts that render their own annotation
+ * affordances (e.g. a sidebar list) can describe rows consistently
+ * with the overlay's pin labels.
+ *
+ * @public
+ */
+export declare function describeAnnotation(annotation: AnnotationOverlayAnnotation): string;
+/**
+ * Filter resolved annotations unless `showResolved` is set. Pure
+ * function; exposed for hosts that drive their own renderer.
+ *
+ * @public
+ */
+export declare function visibleAnnotations(annotations: readonly AnnotationOverlayAnnotation[], showResolved: boolean): readonly AnnotationOverlayAnnotation[];
+/**
+ * Hit-test an annotation at a point. Point / text annotations use a
+ * circular hit zone of {@link HIT_RADIUS_PX} around `(x, y)`; area
+ * annotations use the inclusive bounding rectangle. Pure function;
+ * exposed so hosts can hit-test against the same algorithm the
+ * overlay uses for click handling.
+ *
+ * @public
+ */
+export declare function isPointInsideAnnotation(annotation: AnnotationOverlayAnnotation, px: number, py: number): boolean;
+/**
+ * Renders the annotation layer as an absolutely-positioned SVG over
+ * the page surface. Pointer events propagate through transparent
+ * areas; hosts can stack the overlay over interactive layers without
+ * blocking selection of canvas objects.
+ *
+ * @public
+ */
+export declare function AnnotationOverlay({ annotations, pageWidthPx, pageHeightPx, showResolved, activeAnnotationId, onSelect, }: AnnotationOverlayProps): ReactElement;
+//# sourceMappingURL=AnnotationOverlay.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AnnotationOverlay.d.ts","sourceRoot":"","sources":["../../src/components/AnnotationOverlay.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAiB,YAAY,EAAE,MAAM,OAAO,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,GAAG;IACvD,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,GAAG;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,GAAG;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,2BAA2B,GACnC,oBAAoB,GACpB,mBAAmB,GACnB,mBAAmB,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,mEAAmE;IACnE,WAAW,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACpD;;2CAEuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB;;0DAEsD;IACtD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;oDACgD;IAChD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;sEACkE;IAClE,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,2BAA2B,KAAK,IAAI,CAAC;CAC9D,CAAC;AAsBF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,2BAA2B,GAAG,MAAM,CAOlF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,SAAS,2BAA2B,EAAE,EACnD,YAAY,EAAE,OAAO,GACpB,SAAS,2BAA2B,EAAE,CAGxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,2BAA2B,EACvC,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,OAAO,CAYT;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,WAAW,EACX,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,QAAQ,GACT,EAAE,sBAAsB,GAAG,YAAY,CAsCvC"}

package/dist/components/AnnotationOverlay.js

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Pixel hit radius around a point / text annotation's anchor. Pretty
+ * small so adjacent pins don't fight; hosts that want larger targets
+ * can scale the overlay with CSS transforms.
+ */
+const HIT_RADIUS_PX = 8;
+/** Visual marker size (radius) for point + text pins. Slightly
+ *  smaller than the hit radius so the cursor finds the center even
+ *  on the marker's edge. */
+const MARKER_RADIUS_PX = 6;
+const COLORS = {
+    open: "#dc2626",
+    resolved: "#9ca3af",
+    active: "#2563eb",
+    textBackground: "#fde68a",
+    textForeground: "#78350f",
+};
+/**
+ * Build a screen-reader-friendly description of an annotation.
+ *
+ * Pattern: `"<status> <kind> annotation[: <truncated body>]"`. The
+ * resolved status comes first so screen readers announce it ahead of
+ * the body (matching the visual cue: greyed-out marker = resolved).
+ * Body text is truncated to 60 chars so long comments don't blow up
+ * the announcement. The internal `id` is intentionally omitted —
+ * opaque ids carry no meaning for assistive tech.
+ *
+ * Pure function; exposed so hosts that render their own annotation
+ * affordances (e.g. a sidebar list) can describe rows consistently
+ * with the overlay's pin labels.
+ *
+ * @public
+ */
+export function describeAnnotation(annotation) {
+    const status = annotation.resolved ? "Resolved" : "Open";
+    const body = "text" in annotation && annotation.text ? annotation.text : undefined;
+    const truncatedBody = body !== undefined && body.length > 60 ? `${body.slice(0, 60)}…` : body;
+    return truncatedBody
+        ? `${status} ${annotation.kind} annotation: ${truncatedBody}`
+        : `${status} ${annotation.kind} annotation`;
+}
+/**
+ * Filter resolved annotations unless `showResolved` is set. Pure
+ * function; exposed for hosts that drive their own renderer.
+ *
+ * @public
+ */
+export function visibleAnnotations(annotations, showResolved) {
+    if (showResolved)
+        return annotations;
+    return annotations.filter((a) => !a.resolved);
+}
+/**
+ * Hit-test an annotation at a point. Point / text annotations use a
+ * circular hit zone of {@link HIT_RADIUS_PX} around `(x, y)`; area
+ * annotations use the inclusive bounding rectangle. Pure function;
+ * exposed so hosts can hit-test against the same algorithm the
+ * overlay uses for click handling.
+ *
+ * @public
+ */
+export function isPointInsideAnnotation(annotation, px, py) {
+    if (annotation.kind === "area") {
+        return (px >= annotation.x &&
+            px <= annotation.x + annotation.width &&
+            py >= annotation.y &&
+            py <= annotation.y + annotation.height);
+    }
+    const dx = px - annotation.x;
+    const dy = py - annotation.y;
+    return dx * dx + dy * dy <= HIT_RADIUS_PX * HIT_RADIUS_PX;
+}
+/**
+ * Renders the annotation layer as an absolutely-positioned SVG over
+ * the page surface. Pointer events propagate through transparent
+ * areas; hosts can stack the overlay over interactive layers without
+ * blocking selection of canvas objects.
+ *
+ * @public
+ */
+export function AnnotationOverlay({ annotations, pageWidthPx, pageHeightPx, showResolved, activeAnnotationId, onSelect, }) {
+    const visible = visibleAnnotations(annotations, showResolved ?? false);
+    return (_jsx("svg", { "data-testid": "annotation-overlay", width: pageWidthPx, height: pageHeightPx, viewBox: `0 0 ${pageWidthPx} ${pageHeightPx}`, style: {
+            position: "absolute",
+            top: 0,
+            left: 0,
+            pointerEvents: "none",
+        }, 
+        // `role="img"` declares "no semantic children" — browsers apply
+        // role="presentation" to every descendant, which would hide the
+        // interactive markers from screen readers. When `onSelect` is
+        // wired we switch to `role="group"` so the buttons stay reachable;
+        // the static (read-only) case keeps `role="img"` so a screen
+        // reader announces "Page annotations: 5 visible" as a single
+        // labelled image, not a navigable list.
+        role: onSelect ? "group" : "img", "aria-label": visible.length === 0
+            ? "Page annotations: none visible"
+            : `Page annotations: ${visible.length} visible`, children: visible.map((a) => (_jsx(AnnotationMarker, { annotation: a, isActive: a.id === activeAnnotationId, onSelect: onSelect }, a.id))) }));
+}
+/**
+ * Renders a single annotation marker. Switches on `kind`: area
+ * draws a translucent rectangle, point + text draw a circular pin.
+ * Text annotations get a small badge so the operator can distinguish
+ * them from notes-optional points at a glance.
+ *
+ * Intra-package helper — not exported.
+ */
+function AnnotationMarker({ annotation, isActive, onSelect, }) {
+    const color = isActive ? COLORS.active : annotation.resolved ? COLORS.resolved : COLORS.open;
+    const cursor = onSelect ? "pointer" : "default";
+    const handleClick = onSelect ? () => onSelect(annotation) : undefined;
+    // Enter / Space activate the marker via keyboard — keeps the SVG
+    // overlay accessible to keyboard-only users while the host still
+    // owns higher-level focus management (tab order, roving index).
+    const handleKey = onSelect
+        ? (e) => {
+            if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                onSelect(annotation);
+            }
+        }
+        : undefined;
+    const interactiveProps = onSelect
+        ? {
+            role: "button",
+            tabIndex: 0,
+            "aria-label": describeAnnotation(annotation),
+        }
+        : {};
+    if (annotation.kind === "area") {
+        return (_jsx("g", { "data-testid": `annotation-${annotation.id}`, style: { pointerEvents: "auto", cursor }, onClick: handleClick, onKeyDown: handleKey, ...interactiveProps, children: _jsx("rect", { x: annotation.x, y: annotation.y, width: annotation.width, height: annotation.height, fill: color, fillOpacity: 0.1, stroke: color, strokeWidth: isActive ? 2 : 1, strokeDasharray: annotation.resolved ? "4 2" : undefined }) }));
+    }
+    const isTextKind = annotation.kind === "text";
+    return (_jsxs("g", { "data-testid": `annotation-${annotation.id}`, style: { pointerEvents: "auto", cursor }, onClick: handleClick, onKeyDown: handleKey, ...interactiveProps, children: [_jsx("circle", { cx: annotation.x, cy: annotation.y, r: MARKER_RADIUS_PX, fill: isTextKind ? COLORS.textBackground : color, stroke: color, strokeWidth: isActive ? 2 : 1 }), isTextKind && (
+            // biome-ignore lint/a11y/noAriaHiddenOnFocusable: nested SVG <text> inside a focusable <g role="button"> is treated as focusable by the rule, but it's a purely decorative badge and the parent owns the a11y contract — without aria-hidden a screen reader would redundantly announce a literal "T".
+            _jsx("text", { x: annotation.x, y: annotation.y + 3, textAnchor: "middle", fontSize: "7", fontWeight: "bold", fill: COLORS.textForeground, "aria-hidden": "true", children: "T" }))] }));
+}
+//# sourceMappingURL=AnnotationOverlay.js.map