@beyondwork/docx-react-component 1.0.105 → 1.0.108

package/src/ui-tailwind/chrome-overlay/tw-page-stack-overlay-layer.tsx

@@ -47,13 +47,19 @@
  */
 
 import * as React from "react";
-import type { WordReviewEditorLayoutFacet } from "../../api/public-types";
-import { incrementInvalidationCounter } from "../editor-surface/perf-probe";
+import type {
+  GeometryFacet,
+  PageLayoutSnapshot,
+  WordReviewEditorLayoutFacet,
+} from "../../api/public-types";
+import { DEFAULT_PX_PER_TWIP } from "../../api/public-types";
+import { buildPageAnchorAttributes } from "../../api/v3/_page-anchor-id.ts";
 import {
   resolvePageOverlayRectsFromGeometry as resolvePageOverlayRectsFromGeometryImpl,
-  type GeometryFacet,
   type OverlayVisiblePageIndexRange,
-} from "../../runtime/geometry/index.ts";
+} from "../../api/geometry-overlay-rects.ts";
+import { PAGE_CHROME_DEFAULTS } from "../editor-surface/pm-page-break-decorations.ts";
+import { incrementInvalidationCounter } from "../editor-surface/perf-probe";
 import type { ApiV3Ui } from "../../api/v3/ui";
 import { useUiApi } from "../ui-api-context";
 
@@ -72,6 +78,8 @@ export interface PageOverlayRect {
   bottomPx: number;
   /** Rendered height = bottomPx - topPx. */
   heightPx: number;
+  /** Cold fallback marker; omitted for UI/geometry/DOM-derived rects. */
+  source?: "skeletal";
 }
 
 /**
@@ -108,7 +116,8 @@ function pageOverlayRectsEqual(
       left.pageIndex !== right.pageIndex ||
       left.topPx !== right.topPx ||
       left.bottomPx !== right.bottomPx ||
-      left.heightPx !== right.heightPx
+      left.heightPx !== right.heightPx ||
+      left.source !== right.source
     ) {
       return false;
     }
@@ -116,6 +125,81 @@ function pageOverlayRectsEqual(
   return true;
 }
 
+function resolvePageFrameHeightPx(layout: PageLayoutSnapshot): number | null {
+  if (!Number.isFinite(layout.pageHeight) || layout.pageHeight <= 0) {
+    return null;
+  }
+  return Math.max(1, Math.round(layout.pageHeight * DEFAULT_PX_PER_TWIP));
+}
+
+function resolvePageFrameHeightPxFromLayoutPage(
+  page: ReturnType<WordReviewEditorLayoutFacet["getPage"]>,
+): number | null {
+  if (!page) return null;
+  const frameHeightTwips = page.frame?.physicalBoundsTwips.heightTwips;
+  if (
+    typeof frameHeightTwips === "number" &&
+    Number.isFinite(frameHeightTwips) &&
+    frameHeightTwips > 0
+  ) {
+    return Math.max(1, Math.round(frameHeightTwips * DEFAULT_PX_PER_TWIP));
+  }
+  return resolvePageFrameHeightPx(page.layout);
+}
+
+/**
+ * L11 page-stack consumers receive the mounted L04 page-frame substrate through
+ * the public layout facet. This mirrors the records exposed by
+ * `runtime.layout.getPageFrames()` without making the React painter depend on a
+ * runtime handle; DOM page-frame markers stay a degraded cold-open fallback.
+ */
+export function resolvePageOverlayPageIdsFromLayout(
+  facet: Pick<WordReviewEditorLayoutFacet, "getPageCount" | "getPage">,
+): readonly string[] | null {
+  const pageCount = facet.getPageCount();
+  if (pageCount <= 0) return [];
+  const pageIds: string[] = [];
+  for (let pageIndex = 0; pageIndex < pageCount; pageIndex += 1) {
+    const page = facet.getPage(pageIndex);
+    if (!page) return null;
+    pageIds.push(page.frame?.pageId ?? page.pageId);
+  }
+  return pageIds;
+}
+
+/**
+ * Cold geometry fallback: before the render kernel or UI anchor provider binds,
+ * the public layout facet can still tell us how many pages exist and which
+ * L04 page frame / canonical section layout owns each page. Use only public
+ * frame or section sizing to draw paper cards, then upgrade in place when
+ * UI/geometry/DOM rects arrive.
+ */
+export function resolveSkeletalPageOverlayRectsFromLayout(
+  facet: Pick<WordReviewEditorLayoutFacet, "getPageCount" | "getPage">,
+): readonly PageOverlayRect[] {
+  const pageCount = facet.getPageCount();
+  if (pageCount <= 0) return [];
+
+  const rects: PageOverlayRect[] = [];
+  let topPx = 0;
+  for (let pageIndex = 0; pageIndex < pageCount; pageIndex += 1) {
+    const page = facet.getPage(pageIndex);
+    if (!page) return [];
+    const heightPx = resolvePageFrameHeightPxFromLayoutPage(page);
+    if (heightPx === null) return [];
+    rects.push({
+      pageId: page.frame?.pageId ?? page.pageId,
+      pageIndex,
+      topPx,
+      bottomPx: topPx + heightPx,
+      heightPx,
+      source: "skeletal",
+    });
+    topPx += heightPx + PAGE_CHROME_DEFAULTS.interGapPx;
+  }
+  return rects;
+}
+
 function pageOverlayLastBottom(rects: readonly PageOverlayRect[]): number {
   let bottom = 0;
   for (const rect of rects) {
@@ -239,6 +323,19 @@ function collectTableEmbeddedBoundaryIndices(
   return indices;
 }
 
+function containsTableBoundaryRisk(queryRoot: HTMLElement | null): boolean {
+  if (!queryRoot) return false;
+  if (queryRoot.getElementsByTagName("table").length > 0) return true;
+  const descendants = queryRoot.getElementsByTagName("*");
+  for (let i = 0; i < descendants.length; i += 1) {
+    const element = descendants[i] as HTMLElement;
+    if (element.getAttribute("data-pm-table-root") === "true") {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Pure helper: turn pre-measured page-boundary widget positions into
  * one `PageOverlayRect` per page.  No DOM access — the caller supplies
@@ -553,6 +650,58 @@ function readOverlayFlowHeight(origin: HTMLElement | null): number {
   return readElementFlowHeight(origin, { includeScrollHeight: false });
 }
 
+export function reconcilePageStackRectsWithFlow(input: {
+  baseRects: readonly PageOverlayRect[];
+  pageCount: number;
+  scrollRoot: HTMLElement | null;
+  originElement: HTMLElement | null;
+}): readonly PageOverlayRect[] {
+  const { baseRects, pageCount, scrollRoot, originElement } = input;
+  if (baseRects.length === 0 || pageCount <= 0) return baseRects;
+  const flowHeight = readOverlayFlowHeight(originElement);
+  if (flowHeight <= 0) return baseRects;
+
+  const geometryBottom = pageOverlayLastBottom(baseRects);
+  const tableBoundaryRisk = containsTableBoundaryRisk(scrollRoot);
+  if (!tableBoundaryRisk && flowHeight <= geometryBottom + 1) {
+    return extendFinalPageOverlayRectToFlowHeight(baseRects, flowHeight);
+  }
+
+  const bridgedBase = extendPageOverlayRectsAcrossTableBoundaryGaps(
+    baseRects,
+    tableBoundaryRisk ? collectTableEmbeddedBoundaryIndices(scrollRoot) : [],
+  );
+
+  const extendedBase = extendFinalPageOverlayRectToFlowHeight(
+    bridgedBase,
+    flowHeight,
+  );
+  if (!originElement || !scrollRoot) return extendedBase;
+
+  // The common warm path has geometry and DOM flow in agreement. Avoid the
+  // full boundary-widget scan unless the PM flow is visibly taller than the
+  // geometry stack. When it is taller, page-stack consumers must follow the
+  // in-flow boundaries so content remains on page chrome instead of canvas.
+  if (flowHeight <= pageOverlayLastBottom(bridgedBase) + 1) {
+    return extendedBase;
+  }
+
+  const widgets = measureWidgetsViaBoundingRect(scrollRoot, originElement, {
+    pageCount,
+    visiblePageIndexRange: null,
+  });
+  if (widgets.length === 0) return extendedBase;
+
+  const flowRects = resolvePageOverlayRects({
+    widgets,
+    pageCount,
+    scrollHeight: flowHeight,
+    visiblePageIndexRange: null,
+  });
+  const merged = mergePageOverlayRectsByPageIndex(extendedBase, flowRects);
+  return extendFinalPageOverlayRectToFlowHeight(merged, flowHeight);
+}
+
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
@@ -681,31 +830,34 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   // null here when headless / off-provider; the overlay then falls
   // through to the existing geometry-facet / DOM paths.
   const ui = useUiApi();
-  // Flicker-remediation 2026-04-22: compute initial rects synchronously
-  // from the geometry facet when the kernel is already warm, so the
-  // first paint has correct paper cards instead of an empty overlay
-  // that only populates after `useEffect` ticks. Cold-open paths where
-  // `geometryFacet` isn't passed / returns null still fall back to
-  // the empty initial state + the fallback paper rendered below.
+  // Flicker-remediation 2026-04-22 + Pass-7 hardening 2026-04-27:
+  // compute initial rects synchronously from the geometry facet when
+  // the kernel is already warm. If geometry is cold or absent, draw
+  // skeletal page cards from canonical section sizing so first paint
+  // still shows the document outline.
   const [rects, setRects] = React.useState<readonly PageOverlayRect[]>(() => {
-    if (!geometryFacet) return [];
     const pageCount = facet.getPageCount();
     if (pageCount <= 0) return [];
     // Paper-card backgrounds are cheap and must stay ahead of scroll. Heavy
     // header/footer/footnote chrome still consumes `visiblePageIndexRange`;
     // this decorative white-paper layer renders every card so fast scrolls
     // never expose the gray canvas while the page window catches up.
-    const warm = resolvePageOverlayRectsFromGeometry(
-      geometryFacet,
-      pageCount,
-      null,
-    );
-    return warm
-      ? extendPageOverlayRectsAcrossTableBoundaryGaps(
+    if (geometryFacet) {
+      const warm = resolvePageOverlayRectsFromGeometry(
+        geometryFacet,
+        pageCount,
+        null,
+      );
+      if (warm) {
+        return extendPageOverlayRectsAcrossTableBoundaryGaps(
           warm,
-          collectTableEmbeddedBoundaryIndices(scrollRoot),
-        )
-      : [];
+          containsTableBoundaryRisk(scrollRoot)
+            ? collectTableEmbeddedBoundaryIndices(scrollRoot)
+            : [],
+        );
+      }
+    }
+    return resolveSkeletalPageOverlayRectsFromLayout(facet);
   });
   // P3.d fix: the overlay root acts as the **measurement origin** so
   // widget `topPx` / `bottomPx` are expressed in the exact coordinate
@@ -746,49 +898,19 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
       baseRects: readonly PageOverlayRect[],
       pageCount: number,
     ): readonly PageOverlayRect[] => {
-      if (baseRects.length === 0 || pageCount <= 0) return baseRects;
-      const origin = overlayRootRef.current;
-      const flowHeight = readOverlayFlowHeight(origin);
-      const bridgedBase = extendPageOverlayRectsAcrossTableBoundaryGaps(
+      return reconcilePageStackRectsWithFlow({
         baseRects,
-        collectTableEmbeddedBoundaryIndices(scrollRoot),
-      );
-      if (flowHeight <= 0) return bridgedBase;
-
-      const extendedBase = extendFinalPageOverlayRectToFlowHeight(
-        bridgedBase,
-        flowHeight,
-      );
-      if (!origin || !scrollRoot) return extendedBase;
-
-      // The common warm path has geometry and DOM flow in agreement. Avoid the
-      // full boundary-widget scan unless the PM flow is visibly taller than the
-      // geometry stack. When it is taller, the paper-card layer must follow the
-      // in-flow boundaries so content remains on paper instead of canvas.
-      if (flowHeight <= pageOverlayLastBottom(bridgedBase) + 1) {
-        return extendedBase;
-      }
-
-      const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
-        pageCount,
-        visiblePageIndexRange: null,
-      });
-      if (widgets.length === 0) return extendedBase;
-
-      const flowRects = resolvePageOverlayRects({
-        widgets,
         pageCount,
-        scrollHeight: flowHeight,
-        visiblePageIndexRange: null,
+        scrollRoot,
+        originElement: overlayRootRef.current,
       });
-      const merged = mergePageOverlayRectsByPageIndex(extendedBase, flowRects);
-      return extendFinalPageOverlayRectToFlowHeight(merged, flowHeight);
     },
     [scrollRoot],
   );
 
   const refreshRectsNow = React.useCallback(() => {
     const pageCount = facet.getPageCount();
+    const skeletalRects = resolveSkeletalPageOverlayRectsFromLayout(facet);
 
     // DS-C2 — first try the UI API seam so presentation code does not
     // reach into the geometry facet directly. Page-ids come from the
@@ -805,7 +927,8 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     // threshold during steady-state typing (follow-up work — bench
     // setup for F01/F08 typing scenarios is a separate task).
     if (ui) {
-      const pageIds: string[] | null = geometryFacet
+      const layoutPageIds = resolvePageOverlayPageIdsFromLayout(facet);
+      const geometryPageIds: string[] | null = geometryFacet
         ? Array.from({ length: pageCount }, (_, i) => {
             const page = geometryFacet.getPage(i);
             return page?.pageId ?? `page-${i}`;
@@ -815,7 +938,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
         ui,
         pageCount,
         null,
-        pageIds,
+        layoutPageIds ?? geometryPageIds,
       );
       if (uiRects !== null) {
         incrementInvalidationCounter("overlay.page.ui_api.hit");
@@ -843,10 +966,11 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
         setRectsIfChanged(reconcilePaperRectsWithFlow(geometryRects, pageCount));
         return;
       }
+      incrementInvalidationCounter("overlay.page.geometry.fallthrough");
     }
 
     if (!scrollRoot) {
-      setRectsIfChanged([]);
+      setRectsIfChanged(skeletalRects);
       return;
     }
     const origin = overlayRootRef.current;
@@ -854,6 +978,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     // Cold-open / pre-paint DOM fallback — warm path early-returned
     // above via `geometryFacet` or the UI-API resolver. Lines below
     // fire only before the first render frame.
+    incrementInvalidationCounter("overlay.page.dom_fallback");
     if (origin) {
       incrementInvalidationCounter("overlay.page.dom.degraded");
       const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
@@ -870,7 +995,8 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
           origin.clientHeight > 0 ? origin.clientHeight : originRect.height,
         visiblePageIndexRange: null,
       });
-      setRectsIfChanged(reconcilePaperRectsWithFlow(domRects, pageCount));
+      const reconciled = reconcilePaperRectsWithFlow(domRects, pageCount);
+      setRectsIfChanged(reconciled.length > 0 ? reconciled : skeletalRects);
     } else {
       incrementInvalidationCounter("overlay.page.dom.degraded");
       const widgets = measureWidgetsViaOffsetChain(scrollRoot, {
@@ -884,7 +1010,8 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
         scrollHeight: scrollRoot.clientHeight,
         visiblePageIndexRange: null,
       });
-      setRectsIfChanged(reconcilePaperRectsWithFlow(domRects, pageCount));
+      const reconciled = reconcilePaperRectsWithFlow(domRects, pageCount);
+      setRectsIfChanged(reconciled.length > 0 ? reconciled : skeletalRects);
     }
   }, [
     facet,
@@ -1007,15 +1134,9 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   // root element present + empty is cheap (one `<div>`) and makes the
   // ref resolve during the first layout-effect pass.
   //
-  // Flicker-remediation 2026-04-22: when rects are not yet available
-  // (cold-open; geometry facet has no kernel yet; DOM not measured),
-  // paint a full-area paper-color fallback card so the user sees a
-  // white page rather than the gray workspace canvas flashing through.
-  // The fallback uses the same paper chrome (bg / border / shadow /
-  // radius) as individual page cards, rendered as `inset-0` so it
-  // spans whatever region the scroll root currently occupies. When
-  // `rects` populates on the next refresh pass the fallback is
-  // replaced by N discrete cards.
+  // Flicker-remediation 2026-04-22: if even canonical section sizing is not
+  // available yet, paint a full-area paper-color fallback card so the user
+  // sees white paper rather than the gray workspace canvas flashing through.
   if (rects.length === 0) {
     return (
       <div
@@ -1041,6 +1162,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     );
   }
 
+  const rectsAreSkeletal = rects.every((rect) => rect.source === "skeletal");
   return (
     <div
       ref={overlayRootRef}
@@ -1048,31 +1170,38 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
       aria-hidden="true"
       data-testid={testId ?? "page-stack-overlay"}
       data-page-count={rects.length}
+      data-fallback-paper={rectsAreSkeletal ? "skeletal" : undefined}
     >
-      {rects.map((rect) => (
-        <div
-          key={rect.pageId}
-          className="wre-page-stack-overlay-frame absolute"
-          data-page-index={rect.pageIndex}
-          data-page-id={rect.pageId}
-          style={{
-            top: `${rect.topPx}px`,
-            height: `${rect.heightPx}px`,
-            left: 0,
-            right: 0,
-            // N1 (L8 Phase D): this component is placed at z-0 BEFORE
-            // the z-10 PM wrapper inside `wre-page-surface`, so an opaque
-            // page background here sits behind PM text rather than on top
-            // of it.  White card + border + shadow gives the 'N distinct
-            // papers on a gray canvas' appearance.
-            backgroundColor: "var(--color-page-bg, white)",
-            border: "1px solid var(--color-page-border, rgba(148,163,184,0.2))",
-            borderRadius: "var(--radius-page, 4px)",
-            boxShadow:
-              "0 8px 24px -20px var(--color-page-shadow, rgba(15,23,42,0.38))",
-          }}
-        />
-      ))}
+      {rects.map((rect) => {
+        const anchorAttrs = buildPageAnchorAttributes(rect.pageId, rect.pageIndex);
+        return (
+          <div
+            key={rect.pageId}
+            {...anchorAttrs}
+            className={`wre-page-stack-overlay-frame absolute${
+              rect.source === "skeletal"
+                ? " wre-page-stack-overlay-frame--skeletal"
+                : ""
+            }`}
+            style={{
+              top: `${rect.topPx}px`,
+              height: `${rect.heightPx}px`,
+              left: 0,
+              right: 0,
+              // N1 (L8 Phase D): this component is placed at z-0 BEFORE
+              // the z-10 PM wrapper inside `wre-page-surface`, so an opaque
+              // page background here sits behind PM text rather than on top
+              // of it.  White card + border + shadow gives the 'N distinct
+              // papers on a gray canvas' appearance.
+              backgroundColor: "var(--color-page-bg, white)",
+              border: "1px solid var(--color-page-border, rgba(148,163,184,0.2))",
+              borderRadius: "var(--radius-page, 4px)",
+              boxShadow:
+                "0 8px 24px -20px var(--color-page-shadow, rgba(15,23,42,0.38))",
+            }}
+          />
+        );
+      })}
     </div>
   );
 };

package/src/ui-tailwind/chrome-overlay/tw-presence-overlay-lane.tsx

@@ -0,0 +1,157 @@
+import * as React from "react";
+
+import type {
+  GeometryRect,
+  UiOverlayLaneEntry,
+  UiOverlayLaneSnapshot,
+} from "../../api/v3/ui/_types.ts";
+import { useUiApi } from "../ui-api-context.tsx";
+
+const FALLBACK_CURSOR_COLOR = "#6b7280";
+
+/**
+ * L11 lane painter for L10's presence overlay lane.
+ *
+ * The runtime/shell owns awareness and cursor projection. This component is
+ * deliberately only a painter: it consumes `ui.overlays.getLane("presence")`
+ * snapshots, subscribes to the same lane, and renders resolved overlay rects.
+ */
+export function TwPresenceOverlayLane(): React.ReactElement | null {
+  const ui = useUiApi();
+  const [lane, setLane] = React.useState<UiOverlayLaneSnapshot | null>(() =>
+    ui?.overlays.getLane("presence") ?? null,
+  );
+
+  React.useEffect(() => {
+    if (!ui) {
+      setLane(null);
+      return undefined;
+    }
+
+    setLane(ui.overlays.getLane("presence"));
+
+    try {
+      return ui.overlays.subscribeLane("presence", setLane);
+    } catch {
+      return undefined;
+    }
+  }, [ui]);
+
+  const markers = React.useMemo(() => resolvedPresenceMarkers(lane), [lane]);
+  if (markers.length === 0) return null;
+
+  return (
+    <div
+      aria-hidden="true"
+      className="wre-presence-overlay-lane pointer-events-none absolute inset-0"
+      data-presence-overlay-lane=""
+      data-lane-source={lane?.source ?? "unavailable"}
+      data-lane-revision={lane?.revision ?? 0}
+    >
+      {markers.map((marker) => (
+        <div
+          className="wre-presence-overlay-lane__marker pointer-events-none absolute"
+          data-presence-cursor={marker.userId}
+          key={marker.key}
+          style={marker.style}
+          title={marker.displayName}
+        >
+          <span
+            className="wre-presence-overlay-lane__caret absolute"
+            style={marker.caretStyle}
+          />
+          {marker.displayName ? (
+            <span
+              className="wre-presence-overlay-lane__label absolute whitespace-nowrap rounded-sm px-1 py-0 text-[11px] font-medium leading-tight text-white shadow-sm"
+              style={marker.labelStyle}
+            >
+              {marker.displayName}
+            </span>
+          ) : null}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+interface PresenceMarker {
+  key: string;
+  userId: string;
+  displayName: string;
+  style: React.CSSProperties;
+  caretStyle: React.CSSProperties;
+  labelStyle: React.CSSProperties;
+}
+
+export function resolvedPresenceMarkers(
+  lane: UiOverlayLaneSnapshot | null,
+): PresenceMarker[] {
+  if (!lane || lane.kind !== "presence" || lane.status !== "resolved") {
+    return [];
+  }
+
+  const markers: PresenceMarker[] = [];
+  for (const entry of lane.entries) {
+    if (entry.status !== "resolved" || !entry.rects?.length) continue;
+
+    const data = entry.data ?? {};
+    const userId = stringValue(data.userId) ?? entry.id;
+    const displayName = stringValue(data.displayName) ?? userId;
+    const color = safePresenceColor(data.color);
+
+    entry.rects.forEach((rect, index) => {
+      markers.push({
+        key: `${entry.id}:${index}`,
+        userId,
+        displayName,
+        style: markerStyle(rect),
+        caretStyle: caretStyle(rect, color),
+        labelStyle: labelStyle(color),
+      });
+    });
+  }
+  return markers;
+}
+
+function markerStyle(rect: GeometryRect): React.CSSProperties {
+  return {
+    left: `${rect.leftPx}px`,
+    top: `${rect.topPx}px`,
+    width: `${Math.max(rect.widthPx, 2)}px`,
+    height: `${Math.max(rect.heightPx, 12)}px`,
+  };
+}
+
+function caretStyle(rect: GeometryRect, color: string): React.CSSProperties {
+  return {
+    left: 0,
+    top: 0,
+    width: "2px",
+    height: `${Math.max(rect.heightPx, 12)}px`,
+    backgroundColor: color,
+    borderRadius: "1px",
+  };
+}
+
+function labelStyle(color: string): React.CSSProperties {
+  return {
+    left: 0,
+    top: "-1.35em",
+    backgroundColor: color,
+  };
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function safePresenceColor(raw: unknown): string {
+  if (typeof raw !== "string") return FALLBACK_CURSOR_COLOR;
+  const value = raw.trim();
+  if (value.length === 0 || value.length > 32) return FALLBACK_CURSOR_COLOR;
+  if (/^#[0-9a-fA-F]{3}$|^#[0-9a-fA-F]{6}$|^#[0-9a-fA-F]{8}$/.test(value)) return value;
+  if (/^rgba?\(\s*\d+(\.\d+)?%?(\s*,\s*\d+(\.\d+)?%?){2,3}\s*\)$/.test(value)) return value;
+  return FALLBACK_CURSOR_COLOR;
+}
+
+export default TwPresenceOverlayLane;