smartrte-react 0.3.5 → 1.0.0-beta.1

package/dist/components/ClassicEditorAuthority.d.ts

@@ -1,38 +1,109 @@
 import React from "react";
-import { type PersistedEditorDocument } from "smartrte-core/foundation";
-import { type CanonicalAuthorityContext } from "../canonicalAuthorityFlag.js";
-import type { SmartEditorChange, SmartEditorHandle } from "../canonicalEditorRuntime.js";
+import type { SmartEditorHandle } from "../canonicalEditorRuntime.js";
 import type { MediaProvider } from "../mediaProvider.js";
 import type { MediaPickerComponent } from "./MediaPicker.js";
 import { type CanonicalAuthorityEditorProps } from "./CanonicalAuthorityEditor.js";
-import { type ClassicEditorProps as LegacyClassicEditorProps } from "./ClassicEditor.js";
-export type ClassicEditorProps = Omit<LegacyClassicEditorProps, "value" | "onChange"> & {
-    /** Initial-only under canonical authority. Use replaceValue for external changes. */
-    defaultValue?: string | PersistedEditorDocument;
-    /** Legacy HTML value. Ignored after canonical construction. */
+export type ClassicEditorProps = Omit<CanonicalAuthorityEditorProps, "onChange" | "onHtmlChange"> & {
+    /** Legacy HTML value. Superseded by defaultValue; retained for source compatibility. */
     value?: string;
-    onChange?: ((change: SmartEditorChange) => void) | ((html: string) => void);
-    onHtmlChange?: (html: string) => void;
-    canonicalAuthority?: boolean;
-    authorityContext?: CanonicalAuthorityContext;
+    /**
+     * Legacy-compat: always fires with a plain HTML string, matching every
+     * real pre-canonical caller's actual usage (e.g. Sootr's
+     * RichTextEditor.tsx: `onChange: (html: string) => void`, used directly
+     * as form state and passed to autosave/upload-on-save pipelines expecting
+     * a string). This used to be typed as a union also accepting the new
+     * canonical `SmartEditorChange` object, but the implementation only ever
+     * invoked it with that object regardless of which shape the caller's
+     * function actually expected - a real, live bug (a legacy caller
+     * expecting a string got an object with no type error), not just an
+     * imprecise type. Fixed by wiring this to the existing debounced HTML
+     * serialization (`onHtmlChange`, ~250ms after the last edit - see
+     * canonicalEditorRuntime.ts's `scheduleHtmlChange`) instead of the
+     * per-transaction `onChange`, since that's the mechanism already built
+     * for exactly this purpose. Callers who need the structured
+     * per-transaction event should use `CanonicalAuthorityEditorProps`
+     * directly, not this legacy-compat surface.
+     */
+    onChange?: (html: string) => void;
     mediaProvider?: MediaProvider;
     mediaPicker?: MediaPickerComponent;
     onRuntime?: CanonicalAuthorityEditorProps["onRuntime"];
+    /**
+     * `table={false}` selects the "simple" capability preset (see
+     * capabilityPresets.ts) unless `preset` is also explicitly given, in
+     * which case `preset` wins. This is the one legacy toggle real callers
+     * actually vary - Sootr's MCQ/Anomaly/PYEQ editors all pass
+     * `enableTable={false}` (see docs/SOOTR_MIGRATION_READINESS.md gap #3);
+     * nothing in this project's history has ever needed `media`/`formula` to
+     * vary independently of each other (both are owned by the single "atom"
+     * plugin today), so those two remain accepted-but-ignored, same as
+     * before.
+     */
+    table?: boolean;
+    media?: unknown;
+    formula?: unknown;
+    fonts?: unknown;
+    defaultFont?: unknown;
+    preserveFontFamily?: unknown;
+    preserveColors?: unknown;
+    preserveDocxStyles?: unknown;
+    theme?: unknown;
+    showFontSize?: unknown;
 };
 /**
- * Uncontrolled by default in canonical mode. The runtime flag supplies a
- * reversible legacy path during rollout; direct prop override has precedence.
+ * Canonical authority is unconditionally the only implementation as of
+ * Phase 8b closeout (2026-08-12) — the DOM-authoritative legacy rollback
+ * path (LegacyClassicEditor, its four rollback bridges, and the
+ * canonicalAuthorityFlag rollback switch itself) was retired once the
+ * Gate 13/14 replay and production-surface gates passed. This wrapper
+ * remains the stable public import path and continues to accept (and
+ * ignore) legacy-only configuration props below so existing call sites
+ * keep compiling.
  */
-export declare const ClassicEditor: React.ForwardRefExoticComponent<Omit<LegacyClassicEditorProps, "value" | "onChange"> & {
-    /** Initial-only under canonical authority. Use replaceValue for external changes. */
-    defaultValue?: string | PersistedEditorDocument;
-    /** Legacy HTML value. Ignored after canonical construction. */
+export declare const ClassicEditor: React.ForwardRefExoticComponent<Omit<CanonicalAuthorityEditorProps, "onChange" | "onHtmlChange"> & {
+    /** Legacy HTML value. Superseded by defaultValue; retained for source compatibility. */
     value?: string;
-    onChange?: ((change: SmartEditorChange) => void) | ((html: string) => void);
-    onHtmlChange?: (html: string) => void;
-    canonicalAuthority?: boolean;
-    authorityContext?: CanonicalAuthorityContext;
+    /**
+     * Legacy-compat: always fires with a plain HTML string, matching every
+     * real pre-canonical caller's actual usage (e.g. Sootr's
+     * RichTextEditor.tsx: `onChange: (html: string) => void`, used directly
+     * as form state and passed to autosave/upload-on-save pipelines expecting
+     * a string). This used to be typed as a union also accepting the new
+     * canonical `SmartEditorChange` object, but the implementation only ever
+     * invoked it with that object regardless of which shape the caller's
+     * function actually expected - a real, live bug (a legacy caller
+     * expecting a string got an object with no type error), not just an
+     * imprecise type. Fixed by wiring this to the existing debounced HTML
+     * serialization (`onHtmlChange`, ~250ms after the last edit - see
+     * canonicalEditorRuntime.ts's `scheduleHtmlChange`) instead of the
+     * per-transaction `onChange`, since that's the mechanism already built
+     * for exactly this purpose. Callers who need the structured
+     * per-transaction event should use `CanonicalAuthorityEditorProps`
+     * directly, not this legacy-compat surface.
+     */
+    onChange?: (html: string) => void;
     mediaProvider?: MediaProvider;
     mediaPicker?: MediaPickerComponent;
     onRuntime?: CanonicalAuthorityEditorProps["onRuntime"];
+    /**
+     * `table={false}` selects the "simple" capability preset (see
+     * capabilityPresets.ts) unless `preset` is also explicitly given, in
+     * which case `preset` wins. This is the one legacy toggle real callers
+     * actually vary - Sootr's MCQ/Anomaly/PYEQ editors all pass
+     * `enableTable={false}` (see docs/SOOTR_MIGRATION_READINESS.md gap #3);
+     * nothing in this project's history has ever needed `media`/`formula` to
+     * vary independently of each other (both are owned by the single "atom"
+     * plugin today), so those two remain accepted-but-ignored, same as
+     * before.
+     */
+    table?: boolean;
+    media?: unknown;
+    formula?: unknown;
+    fonts?: unknown;
+    defaultFont?: unknown;
+    preserveFontFamily?: unknown;
+    preserveColors?: unknown;
+    preserveDocxStyles?: unknown;
+    theme?: unknown;
+    showFontSize?: unknown;
 } & React.RefAttributes<SmartEditorHandle>>;

package/dist/components/ClassicEditorAuthority.js

@@ -1,49 +1,17 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { forwardRef, useRef, useSyncExternalStore } from "react";
-import { foundationSchema, parseCanonicalListHtml, serializeCanonicalListHtml } from "smartrte-core/foundation";
-import { canonicalAuthorityFlag } from "../canonicalAuthorityFlag.js";
+import { forwardRef } from "react";
 import { CanonicalAuthorityEditor } from "./CanonicalAuthorityEditor.js";
-import { LegacyClassicEditor } from "./ClassicEditor.js";
 /**
- * Uncontrolled by default in canonical mode. The runtime flag supplies a
- * reversible legacy path during rollout; direct prop override has precedence.
+ * Canonical authority is unconditionally the only implementation as of
+ * Phase 8b closeout (2026-08-12) — the DOM-authoritative legacy rollback
+ * path (LegacyClassicEditor, its four rollback bridges, and the
+ * canonicalAuthorityFlag rollback switch itself) was retired once the
+ * Gate 13/14 replay and production-surface gates passed. This wrapper
+ * remains the stable public import path and continues to accept (and
+ * ignore) legacy-only configuration props below so existing call sites
+ * keep compiling.
  */
 export const ClassicEditor = forwardRef(function ClassicEditor(props, ref) {
-    useSyncExternalStore((listener) => canonicalAuthorityFlag.subscribe(listener), () => canonicalAuthorityFlag.getVersion(), () => canonicalAuthorityFlag.getVersion());
-    const enabled = canonicalAuthorityFlag.enabled(props.authorityContext, props.canonicalAuthority);
-    const latestEnvelope = useRef(typeof props.defaultValue === "object" ? props.defaultValue : undefined);
-    const latestHtml = useRef(typeof props.defaultValue === "string" ? props.defaultValue : props.value);
-    const runtime = useRef(null);
-    if (!enabled) {
-        if (runtime.current) {
-            // Capture once at the authority boundary, not once per keystroke. This is
-            // the ID-preserving rollback envelope; clean HTML remains the legacy view.
-            latestEnvelope.current = runtime.current.getValue();
-            latestHtml.current = serializeCanonicalListHtml(latestEnvelope.current.document, { clean: true });
-            runtime.current = null;
-        }
-        const { defaultValue, onHtmlChange, canonicalAuthority: _canonical, authorityContext: _context, onRuntime: _runtime, mediaProvider: _provider, mediaPicker: _picker, ...legacy } = props;
-        const value = latestEnvelope.current
-            // Internal rollback HTML retains stable IDs. External callbacks receive
-            // the clean representation below.
-            ? serializeCanonicalListHtml(latestEnvelope.current.document, { clean: false })
-            : latestHtml.current ?? (typeof props.value === "string" ? props.value : typeof defaultValue === "string" ? defaultValue : undefined);
-        return _jsx(LegacyClassicEditor, { ...legacy, value: value, onChange: (html) => {
-                const document = parseCanonicalListHtml(html);
-                latestEnvelope.current = {
-                    schemaVersion: foundationSchema.version,
-                    revision: (latestEnvelope.current?.revision || 0) + 1,
-                    document,
-                };
-                const cleanHtml = serializeCanonicalListHtml(document, { clean: true });
-                latestHtml.current = cleanHtml;
-                onHtmlChange?.(cleanHtml);
-                const callback = props.onChange;
-                callback?.(cleanHtml);
-            } });
-    }
-    const { value, canonicalAuthority: _canonical, authorityContext: _context, table: _table, media: _media, formula: _formula, features: _features, plugins: _plugins, formats: _formats, formatDefinitions: _definitions, mediaManager: _manager, fonts: _fonts, defaultFont: _font, preserveFontFamily: _preserveFont, preserveColors: _preserveColors, preserveDocxStyles: _preserveDocx, theme: _theme, showFontSize: _showFontSize, ...canonical } = props;
-    return _jsx(CanonicalAuthorityEditor, { ...canonical, ref: ref, defaultValue: latestEnvelope.current ?? latestHtml.current ?? props.defaultValue ?? value, onChange: (change) => {
-            props.onChange?.(change);
-        }, onHtmlChange: (html) => { latestHtml.current = html; props.onHtmlChange?.(html); }, onRuntime: (value) => { runtime.current = value; props.onRuntime?.(value); } });
+    const { value, onChange, table, preset, media: _media, formula: _formula, fonts: _fonts, defaultFont: _font, preserveFontFamily: _preserveFont, preserveColors: _preserveColors, preserveDocxStyles: _preserveDocx, theme: _theme, showFontSize: _showFontSize, ...canonical } = props;
+    return _jsx(CanonicalAuthorityEditor, { ...canonical, ref: ref, defaultValue: props.defaultValue ?? (typeof value === "string" ? value : undefined), preset: preset ?? (table === false ? "simple" : "full"), onHtmlChange: onChange });
 });

package/dist/components/ColorPickerPopover.d.ts

@@ -0,0 +1,39 @@
+export interface ColorPickerPopoverProps {
+    x: number;
+    y: number;
+    label: string;
+    initialValue?: string;
+    /**
+     * Continuous live-preview callback, fired on every drag frame of the
+     * saturation/value square or hue slider (and on every valid typed hex) -
+     * distinct from `onApply`, which fires once, when the popover is actually
+     * dismissed with a real change staged.
+     */
+    onPreview?: (hex: string) => void;
+    /** Up to 4 previously-committed colors for this same picker context, most-recent first. */
+    recentColors?: readonly string[];
+    onApply: (hex: string) => void;
+    /** Discard: revert to the color the popover opened with. The only way to *not* commit - every other dismissal (outside click, Escape, the close button) commits whatever is currently staged. */
+    onCancel: () => void;
+}
+/**
+ * Phase 11.5 §2.4 originally shipped a native `<input type="color">` as the
+ * primary picker (see git history) - reverted here in favor of a fully
+ * in-page saturation/value square + hue strip, specifically so the drag
+ * surface is visible on the very first click (a native color input needs a
+ * *second* click to open its own OS-level dialog) and so every drag frame
+ * is a real, page-owned pointer event this component fully controls -
+ * sidestepping the whole "which native event means the user is actually
+ * done" problem a native input can never answer reliably (see
+ * docs/bugs/color-popover-closes-on-first-native-picker-interaction.md and
+ * docs/bugs/color-preview-render-steals-focus-from-popover.md, both about
+ * that exact native-event ambiguity).
+ *
+ * Commit model: there is no separate Apply button. Dragging (or typing a
+ * valid hex, or clicking a recent swatch) stages a live preview via
+ * `onPreview`; closing the popover *any* way other than the explicit
+ * Discard button - outside click, Escape, the × button - commits whatever
+ * is currently staged via `onApply`. Discard is the only way back to the
+ * color the popover opened with.
+ */
+export declare function ColorPickerPopover({ x, y, label, initialValue, recentColors, onPreview, onApply, onCancel }: ColorPickerPopoverProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ColorPickerPopover.js

@@ -0,0 +1,285 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+const HEX_PATTERN = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+const normalizeHex = (value) => {
+    if (!HEX_PATTERN.test(value))
+        return null;
+    if (value.length === 4)
+        return `#${value[1]}${value[1]}${value[2]}${value[2]}${value[3]}${value[3]}`.toLowerCase();
+    return value.toLowerCase();
+};
+const hsvToRgb = (h, s, v) => {
+    const sf = s / 100, vf = v / 100;
+    const c = vf * sf;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = vf - c;
+    const [r, g, b] = h < 60 ? [c, x, 0] : h < 120 ? [x, c, 0] : h < 180 ? [0, c, x] : h < 240 ? [0, x, c] : h < 300 ? [x, 0, c] : [c, 0, x];
+    return [Math.round((r + m) * 255), Math.round((g + m) * 255), Math.round((b + m) * 255)];
+};
+const rgbToHex = (r, g, b) => `#${[r, g, b].map((channel) => Math.max(0, Math.min(255, channel)).toString(16).padStart(2, "0")).join("")}`;
+const hexToRgb = (hex) => {
+    const normalized = normalizeHex(hex);
+    if (!normalized)
+        return null;
+    const value = Number.parseInt(normalized.slice(1), 16);
+    return [(value >> 16) & 255, (value >> 8) & 255, value & 255];
+};
+const rgbToHsv = (r, g, b) => {
+    const rf = r / 255, gf = g / 255, bf = b / 255;
+    const max = Math.max(rf, gf, bf), min = Math.min(rf, gf, bf), d = max - min;
+    let h = 0;
+    if (d !== 0) {
+        if (max === rf)
+            h = 60 * (((gf - bf) / d) % 6);
+        else if (max === gf)
+            h = 60 * ((bf - rf) / d + 2);
+        else
+            h = 60 * ((rf - gf) / d + 4);
+    }
+    if (h < 0)
+        h += 360;
+    return [h, max === 0 ? 0 : (d / max) * 100, max * 100];
+};
+const hexToHsv = (hex) => {
+    const rgb = hexToRgb(hex);
+    return rgb ? rgbToHsv(...rgb) : [0, 0, 0];
+};
+const buttonStyle = {
+    minHeight: 32,
+    padding: "0 12px",
+    border: "1px solid var(--srte-input-border)",
+    borderRadius: 8,
+    background: "var(--srte-input-bg)",
+    color: "var(--srte-menu-text)",
+    cursor: "pointer",
+    fontWeight: 500,
+    fontSize: 13,
+};
+const inputStyle = {
+    width: "100%",
+    height: 32,
+    boxSizing: "border-box",
+    padding: "0 10px",
+    border: "1px solid var(--srte-input-border)",
+    borderRadius: 8,
+    outline: "none",
+    background: "var(--srte-input-bg)",
+    color: "var(--srte-input-text)",
+    font: "inherit",
+};
+/** Drives a square/slider from pointer drag - shared by the SV square and the hue strip below, differing only in how a client offset maps to a value. */
+const useDrag = (onMove) => {
+    const ref = useRef(null);
+    const onPointerDown = (event) => {
+        const rect = event.currentTarget.getBoundingClientRect();
+        onMove(event.clientX, event.clientY, rect);
+        const move = (moveEvent) => onMove(moveEvent.clientX, moveEvent.clientY, rect);
+        const up = () => {
+            window.removeEventListener("pointermove", move);
+            window.removeEventListener("pointerup", up);
+        };
+        window.addEventListener("pointermove", move);
+        window.addEventListener("pointerup", up);
+    };
+    return { ref, onPointerDown };
+};
+/**
+ * Phase 11.5 §2.4 originally shipped a native `<input type="color">` as the
+ * primary picker (see git history) - reverted here in favor of a fully
+ * in-page saturation/value square + hue strip, specifically so the drag
+ * surface is visible on the very first click (a native color input needs a
+ * *second* click to open its own OS-level dialog) and so every drag frame
+ * is a real, page-owned pointer event this component fully controls -
+ * sidestepping the whole "which native event means the user is actually
+ * done" problem a native input can never answer reliably (see
+ * docs/bugs/color-popover-closes-on-first-native-picker-interaction.md and
+ * docs/bugs/color-preview-render-steals-focus-from-popover.md, both about
+ * that exact native-event ambiguity).
+ *
+ * Commit model: there is no separate Apply button. Dragging (or typing a
+ * valid hex, or clicking a recent swatch) stages a live preview via
+ * `onPreview`; closing the popover *any* way other than the explicit
+ * Discard button - outside click, Escape, the × button - commits whatever
+ * is currently staged via `onApply`. Discard is the only way back to the
+ * color the popover opened with.
+ */
+export function ColorPickerPopover({ x, y, label, initialValue = "#000000", recentColors, onPreview, onApply, onCancel }) {
+    const [hsv, setHsv] = useState(() => hexToHsv(initialValue));
+    const hex = rgbToHex(...hsvToRgb(hsv[0], hsv[1], hsv[2]));
+    const [hexText, setHexText] = useState(hex);
+    const [error, setError] = useState("");
+    const rootRef = useRef(null);
+    const titleId = useId();
+    const errorId = useId();
+    const [placement, setPlacement] = useState(null);
+    // Nothing has actually changed until a drag frame, a valid typed hex, or a
+    // recent-swatch click stages one - closing without ever touching anything
+    // must be a true no-op, not commit an identical "new" color as a fresh
+    // history entry.
+    const stagedRef = useRef(false);
+    const hexRef = useRef(hex);
+    hexRef.current = hex;
+    const onApplyRef = useRef(onApply);
+    onApplyRef.current = onApply;
+    const onCancelRef = useRef(onCancel);
+    onCancelRef.current = onCancel;
+    useEffect(() => { setHexText(hex); }, [hex]);
+    useLayoutEffect(() => {
+        const el = rootRef.current;
+        if (!el)
+            return;
+        const margin = 8;
+        const { width, height } = el.getBoundingClientRect();
+        const viewportWidth = window.innerWidth;
+        const viewportHeight = window.innerHeight;
+        const overflowsRight = x + width > viewportWidth - margin;
+        const left = overflowsRight ? x - width : x;
+        const clampedLeft = Math.min(Math.max(margin, left), Math.max(margin, viewportWidth - width - margin));
+        const overflowsBottom = y + height > viewportHeight - margin;
+        const top = overflowsBottom ? y - height : y;
+        const clampedTop = Math.min(Math.max(margin, top), Math.max(margin, viewportHeight - margin));
+        setPlacement({ left: clampedLeft, top: clampedTop });
+    }, [x, y]);
+    const stage = (nextHsv) => {
+        stagedRef.current = true;
+        setHsv(nextHsv);
+        onPreview?.(rgbToHex(...hsvToRgb(nextHsv[0], nextHsv[1], nextHsv[2])));
+    };
+    const svDrag = useDrag((clientX, clientY, rect) => {
+        const s = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width)) * 100;
+        const v = 100 - Math.max(0, Math.min(1, (clientY - rect.top) / rect.height)) * 100;
+        stage([hsv[0], s, v]);
+    });
+    const hueDrag = useDrag((clientX, _clientY, rect) => {
+        const h = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width)) * 360;
+        stage([h, hsv[1], hsv[2]]);
+    });
+    const commitAndClose = () => {
+        if (stagedRef.current)
+            onApplyRef.current(hexRef.current);
+        else
+            onCancelRef.current();
+    };
+    useEffect(() => {
+        const dismissIfOutside = (event) => {
+            if (rootRef.current && !rootRef.current.contains(event.target))
+                commitAndClose();
+        };
+        window.addEventListener("pointerdown", dismissIfOutside, true);
+        window.addEventListener("mousedown", dismissIfOutside, true);
+        return () => {
+            window.removeEventListener("pointerdown", dismissIfOutside, true);
+            window.removeEventListener("mousedown", dismissIfOutside, true);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    useEffect(() => {
+        const onWindowKeyDown = (event) => {
+            if (event.key === "Escape")
+                commitAndClose();
+        };
+        window.addEventListener("keydown", onWindowKeyDown);
+        return () => window.removeEventListener("keydown", onWindowKeyDown);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const applyRecentColor = (swatch) => {
+        const rgb = hexToRgb(swatch);
+        if (!rgb)
+            return;
+        stage(rgbToHsv(...rgb));
+    };
+    return (_jsxs("div", { ref: rootRef, "data-srte-color-popover": "true", role: "dialog", "aria-labelledby": titleId, style: {
+            position: "fixed",
+            left: placement?.left ?? x,
+            top: placement?.top ?? y,
+            visibility: placement ? "visible" : "hidden",
+            zIndex: 70,
+            width: 224,
+            boxSizing: "border-box",
+            background: "var(--srte-menu-bg)",
+            color: "var(--srte-menu-text)",
+            border: "1px solid var(--srte-border)",
+            borderRadius: 12,
+            boxShadow: "var(--srte-menu-shadow)",
+            padding: 14,
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between", marginBottom: 10 }, children: [_jsx("div", { id: titleId, style: { fontWeight: 650 }, children: label }), _jsx("button", { type: "button", "aria-label": "Close color picker", title: "Close (keeps the current color)", onClick: commitAndClose, style: { ...buttonStyle, minWidth: 28, minHeight: 28, padding: 0, border: 0, background: "transparent", fontSize: 18 }, children: "\u00D7" })] }), _jsx("div", { ref: svDrag.ref, "data-srte-color-sv-square": "true", role: "slider", "aria-label": "Saturation and brightness", tabIndex: 0, 
+                // Without this, clicking to drag focuses this div (it's a focusable
+                // slider for keyboard access), which collapses the editor's own
+                // native selection before the preview can apply a mark to it - the
+                // same focus-stealing class of bug fixed for LinkEditorPopover
+                // (docs/bugs/link-overlay-autofocus-steals-editor-focus-on-plain-click.md)
+                // and the toolbar dropdowns (docs/bugs/toolbar-dropdown-summary-steals-editor-focus.md).
+                onMouseDown: (event) => event.preventDefault(), onPointerDown: svDrag.onPointerDown, onKeyDown: (event) => {
+                    const step = event.shiftKey ? 10 : 2;
+                    if (event.key === "ArrowRight")
+                        stage([hsv[0], Math.min(100, hsv[1] + step), hsv[2]]);
+                    else if (event.key === "ArrowLeft")
+                        stage([hsv[0], Math.max(0, hsv[1] - step), hsv[2]]);
+                    else if (event.key === "ArrowUp")
+                        stage([hsv[0], hsv[1], Math.min(100, hsv[2] + step)]);
+                    else if (event.key === "ArrowDown")
+                        stage([hsv[0], hsv[1], Math.max(0, hsv[2] - step)]);
+                    else
+                        return;
+                    event.preventDefault();
+                }, style: {
+                    position: "relative",
+                    width: "100%",
+                    height: 130,
+                    borderRadius: 8,
+                    marginBottom: 10,
+                    cursor: "crosshair",
+                    touchAction: "none",
+                    background: `linear-gradient(to top, #000, transparent), linear-gradient(to right, #fff, hsl(${hsv[0]}, 100%, 50%))`,
+                }, children: _jsx("div", { "aria-hidden": "true", style: {
+                        position: "absolute",
+                        left: `${hsv[1]}%`, top: `${100 - hsv[2]}%`,
+                        width: 14, height: 14, borderRadius: "50%",
+                        border: "2px solid #fff", boxShadow: "0 0 0 1px rgba(0,0,0,0.4)",
+                        transform: "translate(-50%, -50%)",
+                        background: hex,
+                        pointerEvents: "none",
+                    } }) }), _jsx("div", { ref: hueDrag.ref, "data-srte-color-hue-slider": "true", role: "slider", "aria-label": "Hue", "aria-valuemin": 0, "aria-valuemax": 360, "aria-valuenow": Math.round(hsv[0]), tabIndex: 0, onMouseDown: (event) => event.preventDefault(), onPointerDown: hueDrag.onPointerDown, onKeyDown: (event) => {
+                    const step = event.shiftKey ? 15 : 3;
+                    if (event.key === "ArrowRight")
+                        stage([Math.min(360, hsv[0] + step), hsv[1], hsv[2]]);
+                    else if (event.key === "ArrowLeft")
+                        stage([Math.max(0, hsv[0] - step), hsv[1], hsv[2]]);
+                    else
+                        return;
+                    event.preventDefault();
+                }, style: {
+                    position: "relative",
+                    width: "100%",
+                    height: 16,
+                    borderRadius: 8,
+                    marginBottom: 12,
+                    cursor: "pointer",
+                    touchAction: "none",
+                    background: "linear-gradient(to right, #f00, #ff0, #0f0, #0ff, #00f, #f0f, #f00)",
+                }, children: _jsx("div", { "aria-hidden": "true", style: {
+                        position: "absolute",
+                        left: `${(hsv[0] / 360) * 100}%`, top: "50%",
+                        width: 16, height: 16, borderRadius: "50%",
+                        border: "2px solid #fff", boxShadow: "0 0 0 1px rgba(0,0,0,0.4)",
+                        transform: "translate(-50%, -50%)",
+                        background: `hsl(${hsv[0]}, 100%, 50%)`,
+                        pointerEvents: "none",
+                    } }) }), _jsxs("label", { style: { display: "flex", alignItems: "center", gap: 8, marginBottom: error ? 6 : 12 }, children: [_jsx("div", { "aria-hidden": "true", style: { width: 32, height: 32, borderRadius: 8, border: "1px solid var(--srte-input-border)", background: hex, flexShrink: 0 } }), _jsx("input", { "data-srte-color-hex-input": "true", value: hexText, autoComplete: "off", autoCapitalize: "none", autoCorrect: "off", spellCheck: false, placeholder: "#336699", "aria-label": "Hex color", "aria-invalid": Boolean(error), "aria-describedby": error ? errorId : undefined, onChange: (event) => {
+                            const value = event.target.value;
+                            setHexText(value);
+                            const normalized = normalizeHex(value);
+                            if (normalized) {
+                                setError("");
+                                const rgb = hexToRgb(normalized);
+                                stage(rgbToHsv(...rgb));
+                            }
+                            else if (value.length >= 4) {
+                                setError("Enter a valid hex color, e.g. #336699.");
+                            }
+                        }, style: { ...inputStyle, borderColor: error ? "var(--srte-danger)" : "var(--srte-input-border)" } })] }), error && (_jsx("div", { id: errorId, "data-srte-color-error": "true", role: "alert", style: { color: "var(--srte-danger)", fontSize: 12, marginBottom: 10 }, children: error })), recentColors && recentColors.length > 0 && (_jsxs("div", { style: { marginBottom: 12 }, children: [_jsx("div", { style: { fontSize: 12, fontWeight: 600, marginBottom: 6 }, children: "Recently used" }), _jsx("div", { "data-srte-recent-colors": "true", style: { display: "flex", gap: 6 }, children: recentColors.slice(0, 4).map((swatch) => (_jsx("button", { type: "button", "data-srte-recent-color": swatch, "aria-label": `Recently used colour ${swatch}`, title: swatch, onClick: () => applyRecentColor(swatch), style: {
+                                width: 24, height: 24, padding: 0, borderRadius: 6,
+                                border: "1px solid var(--srte-input-border)",
+                                background: swatch, cursor: "pointer",
+                            } }, swatch))) })] })), _jsx("div", { style: { display: "flex", justifyContent: "flex-end" }, children: _jsx("button", { type: "button", "data-srte-color-discard": "true", onClick: onCancel, style: buttonStyle, children: "Discard" }) })] }));
+}

package/dist/components/CommentMarkers.d.ts

@@ -0,0 +1,25 @@
+import type { CommentThread, ModelDomMapping, PositionLookup } from "smartrte-core/foundation";
+export interface CommentMarkersProps {
+    positions: PositionLookup;
+    mapping: ModelDomMapping;
+    containerElement: HTMLElement;
+    threads: readonly CommentThread[];
+    activeThreadId: string | null;
+    onSelectThread: (threadId: string) => void;
+}
+/**
+ * Live inline markers for comment threads, following `TableResizeHandles`'
+ * precedent (Phase 12a §1.2 finding): comments need many simultaneous
+ * persistent anchors, not the single-instance overlay pattern the other
+ * popovers use, so this measures real DOM rects from the live document and
+ * re-measures via ResizeObserver/MutationObserver/scroll, exactly like that
+ * component's column/row handles do for table boundaries.
+ *
+ * A thread's range is resolved fresh on every recompute via
+ * `resolveAnnotationRange` (not cached) - it is the authoritative "is this
+ * thread still anchored to real content" check, matching every other
+ * AnnotationRange consumer. A thread whose range no longer resolves (fully
+ * orphaned - the content it anchored to is gone) renders nothing here; it
+ * still exists in `threads` for a host's thread-list UI to surface.
+ */
+export declare function CommentMarkers({ positions, mapping, containerElement, threads, activeThreadId, onSelectThread }: CommentMarkersProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/CommentMarkers.js

@@ -0,0 +1,105 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from "react";
+import { resolveAnnotationRange } from "smartrte-core/foundation";
+/**
+ * Live inline markers for comment threads, following `TableResizeHandles`'
+ * precedent (Phase 12a §1.2 finding): comments need many simultaneous
+ * persistent anchors, not the single-instance overlay pattern the other
+ * popovers use, so this measures real DOM rects from the live document and
+ * re-measures via ResizeObserver/MutationObserver/scroll, exactly like that
+ * component's column/row handles do for table boundaries.
+ *
+ * A thread's range is resolved fresh on every recompute via
+ * `resolveAnnotationRange` (not cached) - it is the authoritative "is this
+ * thread still anchored to real content" check, matching every other
+ * AnnotationRange consumer. A thread whose range no longer resolves (fully
+ * orphaned - the content it anchored to is gone) renders nothing here; it
+ * still exists in `threads` for a host's thread-list UI to surface.
+ */
+export function CommentMarkers({ positions, mapping, containerElement, threads, activeThreadId, onSelectThread }) {
+    const [rects, setRects] = useState([]);
+    const [badges, setBadges] = useState([]);
+    const recompute = useCallback(() => {
+        if (!threads.length) {
+            setRects([]);
+            setBadges([]);
+            return;
+        }
+        const nextRects = [];
+        const nextBadges = [];
+        threads.forEach((thread) => {
+            const range = resolveAnnotationRange(thread.range, positions);
+            if (!range)
+                return;
+            const fromDom = mapping.posToDom(range.from);
+            const toDom = mapping.posToDom(range.to);
+            if (!fromDom || !toDom)
+                return;
+            const domRange = containerElement.ownerDocument.createRange();
+            try {
+                domRange.setStart(fromDom.node, fromDom.offset);
+                domRange.setEnd(toDom.node, toDom.offset);
+            }
+            catch {
+                return;
+            }
+            const clientRects = [...domRange.getClientRects()];
+            clientRects.forEach((rect) => {
+                nextRects.push({ threadId: thread.id, resolved: thread.resolved, left: rect.left, top: rect.top, width: rect.width, height: rect.height });
+            });
+            const anchor = clientRects[clientRects.length - 1] || domRange.getBoundingClientRect();
+            nextBadges.push({ threadId: thread.id, resolved: thread.resolved, replyCount: thread.replies.length, left: anchor.right, top: anchor.top });
+        });
+        setRects(nextRects);
+        setBadges(nextBadges);
+    }, [positions, mapping, containerElement, threads]);
+    useEffect(() => {
+        recompute();
+        const observer = new ResizeObserver(recompute);
+        observer.observe(containerElement);
+        const mutationObserver = new MutationObserver(recompute);
+        mutationObserver.observe(containerElement, { childList: true, subtree: true, characterData: true });
+        const ownerWindow = containerElement.ownerDocument.defaultView;
+        ownerWindow?.addEventListener("scroll", recompute, true);
+        ownerWindow?.addEventListener("resize", recompute);
+        return () => {
+            observer.disconnect();
+            mutationObserver.disconnect();
+            ownerWindow?.removeEventListener("scroll", recompute, true);
+            ownerWindow?.removeEventListener("resize", recompute);
+        };
+    }, [containerElement, recompute]);
+    return (_jsxs("div", { "data-srte-comment-markers": "true", style: { position: "fixed", inset: 0, pointerEvents: "none", zIndex: 55 }, children: [rects.map((rect, index) => (_jsx("div", { "data-srte-comment-highlight": rect.threadId, onPointerDown: () => onSelectThread(rect.threadId), style: {
+                    position: "fixed",
+                    left: rect.left,
+                    top: rect.top,
+                    width: rect.width,
+                    height: rect.height,
+                    background: rect.resolved
+                        ? "var(--srte-comment-highlight-resolved, rgba(148, 148, 148, 0.18))"
+                        : activeThreadId === rect.threadId
+                            ? "var(--srte-comment-highlight-active, rgba(245, 180, 0, 0.55))"
+                            : "var(--srte-comment-highlight, rgba(245, 180, 0, 0.28))",
+                    cursor: "pointer",
+                    pointerEvents: "auto",
+                } }, `${rect.threadId}-${index}`))), badges.map((badge) => (_jsx("button", { type: "button", "aria-label": badge.resolved ? "Open resolved comment thread" : "Open comment thread", "data-srte-comment-badge": badge.threadId, onClick: () => onSelectThread(badge.threadId), style: {
+                    position: "fixed",
+                    left: badge.left + 4,
+                    top: badge.top - 4,
+                    minWidth: 16,
+                    height: 16,
+                    padding: "0 4px",
+                    borderRadius: 8,
+                    border: "1px solid var(--srte-border, #d0d0d0)",
+                    background: badge.resolved
+                        ? "var(--srte-comment-badge-resolved, #e3e3e3)"
+                        : activeThreadId === badge.threadId
+                            ? "var(--srte-primary)"
+                            : "var(--srte-comment-badge, #f5b400)",
+                    color: badge.resolved ? "#555" : "#1a1300",
+                    fontSize: 10,
+                    lineHeight: "14px",
+                    cursor: "pointer",
+                    pointerEvents: "auto",
+                }, children: badge.replyCount }, badge.threadId)))] }));
+}