@beyondwork/docx-react-component 1.0.96 → 1.0.97

package/src/ui-tailwind/chrome-overlay/tw-scope-rail-layer.tsx

@@ -1,25 +1,23 @@
 /**
- * Scope rail layer — renders workflow scopes as a thin color stripe in
- * the reserved left-gutter lane plus a border-only line outline. The
- * visible scope ownership border lives on the PM inline text decoration.
+ * Scope rail layer — intentionally non-rendering in product chrome.
+ *
+ * Scoped text is now the only visible rest-state affordance for a set
+ * scope. The old gutter rail created duplicate markers, drifted away
+ * from the scoped text, and surfaced invisible/implementation scopes in
+ * production. Keep this component as a compatibility shim plus a home
+ * for the pure geometry helpers used by tests.
  *
  * Per runtime-rendering-and-chrome-phase.md §5 and
- * docs/plans/scope-card-overlay.md P0, the rail is a projection over
- * canonical workflow scopes; it never lives inside the PM NodeView
- * tree.  Positions come from the render kernel's per-line block data
- * (walked directly from `RenderFrame.pages[].regions.body.blocks[]`)
- * so multi-line scopes produce one tight tint per line rather than a
- * fat bounding-box union.
+ * docs/plans/scope-card-overlay.md P0, historical rail geometry came
+ * from the render kernel's per-line block data. The helpers remain for
+ * callers that need geometry, but the React layer no longer paints or
+ * reads scope data.
  */
 
 import * as React from "react";
-import {
-  projectRectToOverlay,
-  type OverlayCoordinateSpace,
-} from "./chrome-overlay-projector";
-import { useUiApi } from "../ui-api-context";
+import type { OverlayCoordinateSpace } from "./chrome-overlay-projector";
 import type { RenderFrame, RenderFrameRect } from "../../api/public-types.ts";
-import type { ScopeRailSegment, ScopeRailPosture } from "../../api/public-types.ts";
+import type { ScopeRailSegment } from "../../api/public-types.ts";
 import type { WorkflowFacet } from "../../api/public-types.ts";
 import type { GeometryFacet } from "../../api/public-types";
 
@@ -29,21 +27,18 @@ import type { GeometryFacet } from "../../api/public-types";
 
 export interface TwScopeRailLayerProps {
   /**
-   * Geometry facet — used for `getRenderFrame()`. Migrated from
-   * `facet: WordReviewEditorLayoutFacet` in refactor/05 cross-lane-coord
-   * §8.4 pass. Mounted rail/card data flows through `api.ui.scope.*`.
+   * Legacy prop kept for compatibility. The component no longer reads
+   * geometry because it does not paint the rail.
    */
   geometryFacet: GeometryFacet;
   /**
-   * Workflow facet — no-provider fallback for scope rail/card reads.
-   * Mounted editor paths prefer `api.ui.scope.*`; passing `null` makes
-   * fallback reads no-op.
+   * Legacy prop kept for compatibility. The component intentionally does
+   * not read workflow scope data.
    */
   workflowFacet: WorkflowFacet | null;
   /**
-   * Optional pre-read rail snapshot from `ui.scope.rail()`. When omitted,
-   * the layer reads the mounted UI API itself, then falls back to the
-   * workflow facet for no-provider paths.
+   * Legacy pre-read snapshot. Ignored so invisible implementation scopes
+   * cannot surface through the old rail path.
    */
   scopeRailSegments?: readonly ScopeRailSegment[];
   /** Overlay's coordinate space.  Defaults to the overlay's own origin. */
@@ -53,215 +48,22 @@ export interface TwScopeRailLayerProps {
   /** Scope id that should render with the `active` emphasis. */
   activeScopeId?: string | null;
   /**
-   * Fires when the user clicks the rail stripe — opens the scope card.
-   * P0 wires this directly; P1 replaces with card-layer-aware routing.
+   * Deprecated no-op. Scoped text selection/card flows replace rail clicks.
    */
   onStripeClick?: (segment: ScopeRailSegment) => void;
   /**
-   * Legacy click handler kept for existing consumers.  Called alongside
-   * `onStripeClick` so host apps that subscribed to the pre-stripe API
-   * continue to receive clicks.
+   * Deprecated no-op kept for existing consumers.
    */
   onSegmentClick?: (segment: ScopeRailSegment) => void;
   /** Test id applied to the layer root. */
   "data-testid"?: string;
 }
 
-// ---------------------------------------------------------------------------
-// Posture → visual grammar
-// ---------------------------------------------------------------------------
-
-interface PostureStyle {
-  labelText: string;
-  icon: string;
-  railToken: string;
-  tintToken: string;
-}
-
-const POSTURE_STYLES: Record<ScopeRailPosture, PostureStyle> = {
-  edit: { labelText: "EDIT", icon: "pencil", railToken: "accent", tintToken: "accent" },
-  suggest: { labelText: "SUGGEST", icon: "sparkles", railToken: "warning", tintToken: "warning" },
-  comment: { labelText: "COMMENT", icon: "message", railToken: "insert", tintToken: "insert" },
-  view: { labelText: "IN SCOPE", icon: "eye", railToken: "secondary", tintToken: "secondary" },
-  candidate: { labelText: "PROPOSED", icon: "flag", railToken: "warning", tintToken: "warning" },
-  "preserve-only": { labelText: "BLOCKED", icon: "lock", railToken: "danger", tintToken: "danger" },
-  "blocked-import": { labelText: "BLOCKED", icon: "lock", railToken: "danger", tintToken: "danger" },
-};
-
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
 
-const DEFAULT_RAIL_LANE_PX = 44;
-const STRIPE_WIDTH_PX = 4;
-const LABEL_WIDTH_PX = 28;
-const STACK_OFFSET_PX = 6;
-
-export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
-  geometryFacet,
-  workflowFacet,
-  scopeRailSegments,
-  space,
-  railLaneWidthPx = DEFAULT_RAIL_LANE_PX,
-  activeScopeId,
-  onStripeClick,
-  onSegmentClick,
-  "data-testid": testId,
-}) => {
-  const ui = useUiApi();
-  const frame = geometryFacet.getRenderFrame() ?? null;
-  const segments =
-    scopeRailSegments ??
-    ui?.scope.rail().segments ??
-    workflowFacet?.getAllRailSegments() ??
-    [];
-
-  if (!frame || segments.length === 0) {
-    return null;
-  }
-
-  // P2: which scopes currently have a `source: "ai"` candidate
-  // overlapping — drives the agent-pending shimmer class on their
-  // tints. Mounted surfaces read card projections through ui.scope.card;
-  // no-provider paths fall back to the workflow facet.
-  const cardModels = ui ? [] : workflowFacet?.getAllScopeCardModels() ?? [];
-  const agentPendingByScope = new Map<string, boolean>();
-  for (const model of cardModels) {
-    if (model.agentPending) {
-      agentPendingByScope.set(model.scopeId, true);
-    }
-  }
-  if (ui) {
-    for (const segment of segments) {
-      const model = ui.scope.card(segment.scopeId);
-      if (model?.agentPending) {
-        agentPendingByScope.set(segment.scopeId, true);
-      }
-    }
-  }
-
-  // P3c: stack offsets for overlapping scopes.  Two scopes whose
-  // offset ranges intersect on the same page render as stacked
-  // stripes in the gutter; the inner stripe shifts STACK_OFFSET_PX
-  // further right per overlap count so all are clickable.
-  const stackIndexByScope = computeStackIndices(segments);
-
-  const projectorSpace: OverlayCoordinateSpace = space ?? { originLeftPx: 0, originTopPx: 0 };
-
-  return (
-    <div
-      className="wre-scope-rail-layer pointer-events-none absolute inset-0 z-20"
-      data-testid={testId ?? "scope-rail-layer"}
-      aria-hidden="false"
-      role="group"
-      aria-label="Workflow scope rail"
-    >
-      {segments.map((segment) => {
-        const style = POSTURE_STYLES[segment.posture];
-        const lineRects = collectLineRectsForSegment(frame, segment);
-        if (lineRects.length === 0) return null;
-
-        const isActive =
-          activeScopeId === segment.scopeId || segment.isActiveWorkItem;
-
-        // Stripe + label span the vertical range of the scope's lines;
-        // they live in the gutter lane to the left of the first line.
-        const firstLine = lineRects[0];
-        const lastLine = lineRects[lineRects.length - 1];
-        const stripeTopPx = firstLine.topPx;
-        const stripeHeightPx =
-          lastLine.topPx + lastLine.heightPx - firstLine.topPx;
-        const stackIndex = stackIndexByScope.get(segment.scopeId) ?? 0;
-        const stackOffset = stackIndex * STACK_OFFSET_PX;
-        const stripeRect: RenderFrameRect = {
-          leftPx:
-            firstLine.leftPx
-              - railLaneWidthPx
-              + (railLaneWidthPx - STRIPE_WIDTH_PX) / 2
-              + stackOffset,
-          topPx: stripeTopPx,
-          widthPx: STRIPE_WIDTH_PX,
-          heightPx: Math.max(stripeHeightPx, 14),
-        };
-        const labelRect: RenderFrameRect = {
-          leftPx: firstLine.leftPx - railLaneWidthPx + stackOffset,
-          topPx: stripeTopPx,
-          widthPx: LABEL_WIDTH_PX,
-          heightPx: 20,
-        };
-
-        const handleActivate = () => {
-          onStripeClick?.(segment);
-          onSegmentClick?.(segment);
-        };
-        const handleStripeKey = (event: React.KeyboardEvent<HTMLButtonElement>) => {
-          if (event.key === "Enter" || event.key === " ") {
-            event.preventDefault();
-            handleActivate();
-          }
-        };
-
-        return (
-          <React.Fragment key={`${segment.scopeId}:${segment.pageIndex}:${segment.fromOffset}`}>
-            {/* Per-line tint behind the scoped text runs. */}
-            {lineRects.map((lineRect, index) => {
-              const agentPending = agentPendingByScope.get(segment.scopeId) === true;
-              const tintClassList = [
-                "wre-scope-rail-tint",
-                `wre-scope-rail-tint-${style.tintToken}`,
-              ];
-              if (isActive) tintClassList.push("wre-scope-rail-tint-active");
-              if (agentPending) {
-                tintClassList.push("wre-scope-rail-tint-agent-pending");
-              }
-              return (
-                <div
-                  key={`tint:${index}`}
-                  className={tintClassList.join(" ")}
-                  data-scope-id={segment.scopeId}
-                  data-posture={segment.posture}
-                  data-line-index={index}
-                  data-agent-pending={agentPending ? "true" : undefined}
-                  style={projectRectToOverlay(lineRect, projectorSpace)}
-                />
-              );
-            })}
-            {/* Rail stripe in the gutter. */}
-            <button
-              type="button"
-              className={`wre-scope-rail-stripe wre-scope-rail-label-${style.railToken} ${
-                isActive ? "wre-scope-rail-stripe-active" : ""
-              }`}
-              data-scope-id={segment.scopeId}
-              data-posture={segment.posture}
-              data-stack-index={stackIndex}
-              data-testid="scope-rail-stripe"
-              aria-label={`${style.labelText}${segment.label ? `: ${segment.label}` : ""}`}
-              aria-expanded={isActive ? "true" : "false"}
-              onClick={handleActivate}
-              onKeyDown={handleStripeKey}
-              style={projectRectToOverlay(stripeRect, projectorSpace)}
-            />
-            {/* Edit handle — revealed on stripe hover via CSS. */}
-            <button
-              type="button"
-              tabIndex={-1}
-              className={`wre-scope-rail-label wre-scope-rail-label-${style.railToken}`}
-              data-scope-id={segment.scopeId}
-              data-posture={segment.posture}
-              aria-label={`Edit scope${segment.label ? `: ${segment.label}` : ""}`}
-              onClick={handleActivate}
-              style={projectRectToOverlay(labelRect, projectorSpace)}
-            >
-              <span aria-hidden="true" className={`wre-scope-rail-icon wre-scope-rail-icon-${style.icon}`} />
-              <span className="wre-scope-rail-label-text">{style.labelText}</span>
-            </button>
-          </React.Fragment>
-        );
-      })}
-    </div>
-  );
-};
+export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = (_props) => null;
 
 // ---------------------------------------------------------------------------
 // Internals

package/src/ui-tailwind/debug/README.md

@@ -1,57 +1,19 @@
-# Phase Q — Debug UX (reserved)
+# Debug UX (internal only)
 
-Target for the runtime-embedded debug UX consumed through `ui.debug.attach()`
-(layer 10, refactor/10 Slice 5). This directory is **reserved** — the Slice 5
-ship includes the UI API substrate (`src/api/v3/ui/debug.ts` +
-`UiController.attachDebug` hook), while the React presentation components +
-the public `debugMode` prop + the visibility invariant test are a **Phase Q
-follow-up** per `docs/plans/refactor/10-ui-api.md` Risk #3:
+Runtime debug chrome is not a production API surface. `WordReviewEditor` does
+not expose a `debugMode` prop, `api.ui.debug.attach()` is a hard-disabled
+runtime API call, and `ChromePosture.debugMode` is production-forced to
+`"off"`.
 
-> **Phase Q UX surface area.** `src/ui-tailwind/debug/**` is a new substantial
-> UI surface. *Mitigation:* ship substrate in M4 Slice 5; polish in follow-up.
+The supported local diagnostic surface is the mounted runtime REPL keyboard
+shortcut. These components remain in the tree for internal harness/story
+experiments only; do not wire them into `WordReviewEditor` or public API paths.
 
-## Planned files (follow-up)
+## Files
 
 | File | Purpose |
 |---|---|
-| `tw-debug-top-bar.tsx` | Minimal top bar when `debugMode: "top-bar"` — document hash, scope count, invalidation counter |
-| `tw-debug-overlay.tsx` | Full overlay when `debugMode: "full"` — renders `DebugInspectorSnapshot` sections |
-| `tw-debug-repl.tsx` | REPL with `api`, `runtime`, `debug` in scope; localStorage-persisted history |
+| `tw-debug-top-bar.tsx` | Internal minimal top bar for harness/story experiments |
+| `tw-debug-overlay.tsx` | Internal overlay rendering `DebugInspectorSnapshot` sections |
+| `tw-debug-repl.tsx` | Legacy placeholder; production diagnostics use `tw-runtime-repl-dialog.tsx` |
 | `tw-debug-event-tail.tsx` | Tail of the last N events on active telemetry channels |
-| `keybindings.ts` | Cmd/Ctrl+Shift+D toggles top-bar ↔ full |
-
-## Planned prop (follow-up)
-
-Add `debugMode?: "off" | "top-bar" | "full"` to `WordReviewEditorProps`.
-**Default MUST be `"off"`** per CLAUDE.md Protected Invariants § "Phase Q
-placeholder" — this default has regressed multiple times in predecessor
-surfaces (`showUnsupportedObjectPreviews`, `unsupportedPreviewsPolicy`).
-
-## Planned test (follow-up)
-
-`test/ui/debug-mode-visibility-invariant.test.ts` — asserts:
-- `debugMode: "off"` → no debug UI renders
-- `debugMode: "top-bar"` → only the top bar renders
-- `debugMode: "full"` → overlay renders
-
-## How Slice 5 consumers wire today
-
-Until the Phase Q React components land, Slice 5 ships only the contract:
-
-```ts
-import { createUiApi } from "@beyondwork/docx-react-component/api/v3/ui";
-
-const ui = createUiApi(handle);
-ui.session.bind({
-  kind: "runtime-direct",
-  id: "my-mount",
-  attachDebug(session) {
-    // bind-side: wire runtime.debug.bus + getSnapshot to your debug surface
-    const off = runtime.debug.bus.on(/* ... */, (evt) => {/* render */});
-    return () => off();
-  },
-});
-const attachment = ui.debug.attach({ id: "s1", channels: ["api", "render"] });
-// later:
-attachment.detach();
-```

package/src/ui-tailwind/debug/tw-debug-overlay.tsx

@@ -1,9 +1,9 @@
 /**
  * Phase Q — Debug overlay.
  *
- * Full-screen tabbed panel shown when
- * `WordReviewEditorProps.debugMode === "full"`.  Renders the top bar
- * (reused from `tw-debug-top-bar.tsx`) + three content panes:
+ * Internal full-screen tabbed panel for harness/story experiments.
+ * Production `WordReviewEditor` does not mount this component. Renders
+ * the top bar (reused from `tw-debug-top-bar.tsx`) + three content panes:
  *
  *   - **Inspector** — pretty-prints the bound `DebugInspectorSnapshot`
  *     (canonical / layout / geometry / scope / review / diagnostics
@@ -32,8 +32,8 @@ export interface TwDebugOverlayProps {
   sessionId: string | null;
   snapshot: TwDebugTopBarProps["snapshot"];
   /**
-   * Raw `DebugInspectorSnapshot` the host wired through
-   * `ui.debug.attach()`.  Rendered as pretty-printed JSON in the
+   * Raw `DebugInspectorSnapshot` supplied by an internal harness/story.
+   * Rendered as pretty-printed JSON in the
    * Inspector pane.  Large snapshots are clipped to the first 16 KB
    * to keep the DOM responsive.
    */
@@ -126,7 +126,7 @@ export function TwDebugOverlay(props: TwDebugOverlayProps): React.ReactElement {
           <ul className="flex flex-col gap-0.5 font-mono text-[10px] text-[var(--color-text-secondary)]">
             {(props.events ?? []).length === 0 ? (
               <li className="italic text-[var(--color-text-tertiary)]">
-                (no events — wire `ui.debug.attach()` with a DebugBus listener)
+                (no events)
               </li>
             ) : (
               props.events!.slice(-200).map((e, i) => (

package/src/ui-tailwind/debug/tw-debug-presentation.tsx

@@ -1,34 +1,24 @@
 /**
  * Phase Q — DebugMode router.
  *
- * Single mount point `WordReviewEditor.tsx` consumes.  Picks between
- * the minimal top-bar, the full overlay, or nothing depending on the
- * public `debugMode` prop.  Keeping the router in one file means the
- * invariant test + CI guard can target a single surface.
- *
- * Data flow (consumers wire through `ui.debug.attach()` per refactor/10
- * Slice 5):
- *
- *   host → `ui.debug.attach({ id, channels })` →
- *           controller.attachDebug(session) →
- *             { sessionId, snapshot, events } → this component
- *
- * Slice 7 ships the visibility scaffold; the full REPL + event-tail
- * wiring to `runtime.debug.bus` + `DebugInspectorSnapshot` lives in a
- * follow-up (see `src/ui-tailwind/debug/README.md`).
+ * Internal-only debug presentation router. Production `WordReviewEditor`
+ * does not mount this component and does not expose a prop or runtime API
+ * that can enable it; the supported local diagnostic surface is the runtime
+ * REPL keyboard shortcut.
  */
 
 import React from "react";
 
-import type { DebugMode } from "../../api/public-types.ts";
 import { TwDebugTopBar, type TwDebugTopBarProps } from "./tw-debug-top-bar.tsx";
 import { TwDebugOverlay, type TwDebugOverlayProps } from "./tw-debug-overlay.tsx";
 
+export type DebugMode = "off" | "top-bar" | "full";
+
 export interface TwDebugPresentationProps {
   mode: DebugMode;
   /**
-   * Debug session id — mirrors what the host passed into
-   * `ui.debug.attach({ id })`.  `null` when no attachment is active.
+   * Debug session id for internal harness/storybook experiments.
+   * Production runtime mounting never supplies an active attachment.
    */
   sessionId?: string | null;
   snapshot?: TwDebugTopBarProps["snapshot"];
@@ -36,8 +26,7 @@ export interface TwDebugPresentationProps {
   events?: TwDebugOverlayProps["events"];
   onReplEval?: TwDebugOverlayProps["onReplEval"];
   /**
-   * Optional override for the mode toggle — host supplies when it
-   * owns the `debugMode` state (e.g. harness with a keyboard shortcut).
+   * Optional override for internal harness/storybook mode toggles.
    */
   onModeChange?: (next: DebugMode) => void;
 }

package/src/ui-tailwind/debug/tw-debug-top-bar.tsx

@@ -1,11 +1,10 @@
 /**
  * Phase Q — Debug top bar.
  *
- * Minimal always-on status strip shown when
- * `WordReviewEditorProps.debugMode === "top-bar"` (or as the header of
- * the "full" overlay).  Renders the bound debug session id + a small
- * set of counters derived from the `DebugInspectorSnapshot` the host
- * supplies through `ui.debug.attach()` wiring.
+ * Internal status strip for harness/story experiments. Production
+ * `WordReviewEditor` does not mount this component or expose a public
+ * debugMode prop/API. Renders the bound debug session id + a small set
+ * of counters derived from a supplied `DebugInspectorSnapshot`.
  *
  * Slice 7 ships the minimal surface; the REPL + event-tail panes live
  * in `tw-debug-overlay.tsx` (full mode only).  Future telemetry (scope
@@ -17,7 +16,7 @@ import React from "react";
 
 export interface TwDebugTopBarProps {
   /**
-   * The debug-session id the host passed into `ui.debug.attach()`.
+   * The debug-session id the internal harness/story surface supplies.
    * Shown verbatim so operators can correlate with Railway debug-
    * service logs.  `null` when no attachment is active.
    */

package/src/ui-tailwind/editor-surface/chart-node-view.tsx

@@ -12,7 +12,6 @@
  */
 
 import React from "react";
-import { flushSync } from "react-dom";
 import { createRoot, type Root } from "react-dom/client";
 import type { Node as PMNode } from "prosemirror-model";
 import type { NodeViewConstructor } from "prosemirror-view";
@@ -83,9 +82,7 @@ class ChartNodeViewInstance {
     if (!this._root) {
       this._root = createRoot(this.dom);
     }
-    flushSync(() => {
-      this._root?.render(el);
-    });
+    this._root.render(el);
     this._mountedChartId = parsedChartId;
   }
 

package/src/ui-tailwind/editor-surface/picture-effects.ts

@@ -0,0 +1,96 @@
+import {
+  EMU_PER_PX,
+  ROTATION_UNITS_PER_DEGREE,
+} from "../../api/public-types.ts";
+
+type LumEffect = {
+  bright?: number;
+  contrast?: number;
+};
+
+type DropShadowEffect = {
+  blurRad: number;
+  dist: number;
+  dir: number;
+  color?: string | null;
+};
+
+type GlowEffect = {
+  radius: number;
+  color?: string | null;
+};
+
+export interface CssPictureFilterEffects {
+  lum?: LumEffect | null;
+  softEdgeRadius?: number | null;
+  glow?: GlowEffect | null;
+  outerShadow?: DropShadowEffect | null;
+}
+
+export function buildPictureFilterCss(
+  effects: CssPictureFilterEffects | null | undefined,
+): string | undefined {
+  if (!effects) return undefined;
+  const parts: string[] = [];
+  parts.push(...buildLumFilterParts(effects.lum));
+  if (effects.softEdgeRadius) {
+    parts.push(`blur(${(effects.softEdgeRadius / EMU_PER_PX).toFixed(2)}px)`);
+  }
+  const glowColor = safeFilterHexColor(effects.glow?.color);
+  if (effects.glow && glowColor) {
+    parts.push(`drop-shadow(0 0 ${(effects.glow.radius / EMU_PER_PX).toFixed(2)}px ${glowColor})`);
+  }
+  const shadowColor = safeFilterHexColor(effects.outerShadow?.color);
+  if (effects.outerShadow && shadowColor) {
+    const blurPx = (effects.outerShadow.blurRad / EMU_PER_PX).toFixed(2);
+    const distPx = effects.outerShadow.dist / EMU_PER_PX;
+    const dirRad = (effects.outerShadow.dir / ROTATION_UNITS_PER_DEGREE) * (Math.PI / 180);
+    const dx = (distPx * Math.cos(dirRad)).toFixed(2);
+    const dy = (distPx * Math.sin(dirRad)).toFixed(2);
+    parts.push(`drop-shadow(${dx}px ${dy}px ${blurPx}px ${shadowColor})`);
+  }
+  return parts.length > 0 ? parts.join(" ") : undefined;
+}
+
+function buildLumFilterParts(lum: LumEffect | null | undefined): string[] {
+  if (!lum || (lum.bright === undefined && lum.contrast === undefined)) {
+    return [];
+  }
+  const bright = clamp((lum.bright ?? 0) / 100000, -1, 1);
+  const contrast = clamp((lum.contrast ?? 0) / 100000, -1, 1);
+  const parts: string[] = [];
+  if (lum.bright !== undefined) {
+    // OOXML luminance bright is closer to an additive wash than a raw CSS
+    // brightness multiplier. CSS cannot express that affine transform in a
+    // single filter, so we keep the Word-like bright wash and pair it with
+    // contrast/saturation compensation below.
+    if (Math.abs(bright) >= 0.0005) {
+      parts.push(`brightness(${Math.max(0, 1 + bright).toFixed(3)})`);
+    }
+  }
+  if (lum.contrast !== undefined) {
+    const cssContrast = contrast < 0
+      ? Math.max(0, 1 + contrast * 0.928571)
+      : 1 + contrast;
+    if (Math.abs(cssContrast - 1) >= 0.0005) {
+      parts.unshift(`contrast(${cssContrast.toFixed(3)})`);
+    }
+  }
+  if (bright > 0 && contrast < 0) {
+    const cssSaturate = 1 + bright * Math.abs(contrast) * 0.1;
+    if (Math.abs(cssSaturate - 1) >= 0.0005) {
+      parts.push(`saturate(${cssSaturate.toFixed(3)})`);
+    }
+  }
+  return parts;
+}
+
+function safeFilterHexColor(raw: string | null | undefined): string {
+  return typeof raw === "string" && /^[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$/.test(raw)
+    ? `#${raw.toUpperCase()}`
+    : "";
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}