@beyondwork/docx-react-component 1.0.56 → 1.0.57

package/src/ui-tailwind/chrome-overlay/tw-comment-balloon-layer.tsx

@@ -0,0 +1,74 @@
+import * as React from "react";
+import type { RenderBlockDecoration } from "../../runtime/render/render-frame-types";
+import { TwCommentPreview } from "../chrome/tw-comment-preview";
+
+const WIDE_BREAKPOINT_PX = 1024;
+const CONNECTOR_GAP_PX = 16;
+const BALLOON_MAX_WIDTH_PX = 240;
+
+export interface CommentBalloonData {
+  commentId: string;
+  authorName: string;
+  authorInitials?: string;
+  authorAvatarUrl?: string;
+  timestamp?: string;
+  excerpt: string;
+}
+
+export interface TwCommentBalloonLayerProps {
+  /** Decoration rects from `frame.decorationIndex.comments`. */
+  commentDecorations: readonly RenderBlockDecoration[];
+  /** Pre-resolved comment data keyed by commentId. */
+  commentDataById: ReadonlyMap<string, CommentBalloonData>;
+  /** Viewport width — balloons only render >= WIDE_BREAKPOINT_PX. */
+  viewportWidthPx: number;
+  /** Right edge of the page frame in overlay coordinates (px). */
+  pageRightEdgePx: number;
+  onOpenThread?: (commentId: string) => void;
+}
+
+export const TwCommentBalloonLayer = React.memo(function TwCommentBalloonLayer({
+  commentDecorations,
+  commentDataById,
+  viewportWidthPx,
+  pageRightEdgePx,
+  onOpenThread,
+}: TwCommentBalloonLayerProps) {
+  if (viewportWidthPx < WIDE_BREAKPOINT_PX) return null;
+  if (commentDecorations.length === 0) return null;
+
+  return (
+    <>
+      {commentDecorations.map((dec) => {
+        const data = commentDataById.get(dec.refId);
+        if (!data) return null;
+        return (
+          <div
+            key={dec.refId}
+            style={{
+              position: "absolute",
+              top: dec.frame.topPx,
+              left: pageRightEdgePx + CONNECTOR_GAP_PX,
+              width: BALLOON_MAX_WIDTH_PX,
+              pointerEvents: "auto",
+              zIndex: 10,
+            }}
+          >
+            <TwCommentPreview
+              author={{
+                name: data.authorName,
+                initials: data.authorInitials,
+                avatarUrl: data.authorAvatarUrl,
+              }}
+              timestamp={data.timestamp}
+              excerpt={data.excerpt}
+              onOpenThread={
+                onOpenThread ? () => onOpenThread(data.commentId) : undefined
+              }
+            />
+          </div>
+        );
+      })}
+    </>
+  );
+});

package/src/ui-tailwind/chrome-overlay/tw-locked-block-layer.tsx

@@ -0,0 +1,65 @@
+import * as React from "react";
+import { Lock } from "lucide-react";
+import type { RenderBlockDecoration } from "../../runtime/render/render-frame-types";
+
+const OUTLINE_INSET_PX = 2;
+const BADGE_SIZE_PX = 20;
+
+export interface TwLockedBlockLayerProps {
+  /** Decoration rects from `frame.decorationIndex.locked`. */
+  lockedDecorations: readonly RenderBlockDecoration[];
+}
+
+export const TwLockedBlockLayer = React.memo(function TwLockedBlockLayer({
+  lockedDecorations,
+}: TwLockedBlockLayerProps) {
+  if (lockedDecorations.length === 0) return null;
+
+  return (
+    <>
+      {lockedDecorations.map((dec, idx) => {
+        const { leftPx, topPx, widthPx, heightPx } = dec.frame;
+        return (
+          <React.Fragment key={`locked-${dec.refId}-${idx}`}>
+            {/* Dashed outline around the locked block */}
+            <div
+              aria-hidden
+              style={{
+                position: "absolute",
+                top: topPx + OUTLINE_INSET_PX,
+                left: leftPx + OUTLINE_INSET_PX,
+                width: widthPx - OUTLINE_INSET_PX * 2,
+                height: heightPx - OUTLINE_INSET_PX * 2,
+                border: "1.5px dashed var(--color-border-caution, #e8a020)",
+                borderRadius: 2,
+                pointerEvents: "none",
+              }}
+            />
+            {/* Lock badge in the top-right corner */}
+            <div
+              aria-label="Locked content"
+              role="img"
+              style={{
+                position: "absolute",
+                top: topPx - BADGE_SIZE_PX / 2,
+                left: leftPx + widthPx - BADGE_SIZE_PX / 2,
+                width: BADGE_SIZE_PX,
+                height: BADGE_SIZE_PX,
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                background: "var(--color-bg-surface, #fff)",
+                border: "1px solid var(--color-border-caution, #e8a020)",
+                borderRadius: "50%",
+                pointerEvents: "none",
+                zIndex: 1,
+              }}
+            >
+              <Lock size={10} strokeWidth={2.5} />
+            </div>
+          </React.Fragment>
+        );
+      })}
+    </>
+  );
+});

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

@@ -0,0 +1,233 @@
+/**
+ * Lane 6d — Slice N5 (P11.6 + P11.7): page-border + column-separator overlay.
+ *
+ * Pure presentational component that paints the four page-border edges
+ * and any column-separator vertical lines for a single page.  All
+ * positioning math lives in `page-border-resolver.ts`; this component
+ * does no measurement and reads no DOM — it accepts a `PageLayoutSnapshot`
+ * + page rect (in px) and emits inline-styled `<div>`s.
+ *
+ * Designed to be mounted by a per-page chrome layer (one
+ * `<TwPageBorderOverlay>` per page) so each page can use its own section's
+ * `pageBorders` and `columnDefinitions` independently.
+ */
+
+import React from "react";
+import type { PageLayoutSnapshot } from "../../api/public-types";
+import {
+  resolveColumnSeparatorXOffsets,
+  resolvePageBorders,
+} from "./page-border-resolver";
+
+export interface TwPageBorderOverlayProps {
+  /** Section layout for the page (drives `pageBorders` + `columnSeparator`). */
+  layout: PageLayoutSnapshot | undefined;
+  /** Zero-based page index within its owning section (drives display policy). */
+  pageInSection: number;
+  /** Page rect in container-relative pixels. */
+  pageWidthPx: number;
+  pageHeightPx: number;
+  /** Inner content-box insets in pixels (text margin from page edge). */
+  marginLeftPx: number;
+  marginRightPx: number;
+  marginTopPx: number;
+  marginBottomPx: number;
+  /** Optional test id for assertion targeting. */
+  "data-testid"?: string;
+}
+
+/**
+ * Border edge geometry helpers — convert the resolved spec + page
+ * dimensions into the absolute `style` props for one positioned `<div>`.
+ */
+function styleForEdge(
+  edge: "top" | "right" | "bottom" | "left",
+  widthPx: number,
+  styleName: string,
+  color: string,
+  insetTop: number,
+  insetRight: number,
+  insetBottom: number,
+  insetLeft: number,
+): React.CSSProperties {
+  switch (edge) {
+    case "top":
+      return {
+        position: "absolute",
+        top: `${insetTop}px`,
+        left: `${insetLeft}px`,
+        right: `${insetRight}px`,
+        height: `${widthPx}px`,
+        borderTop: `${widthPx}px ${styleName} ${color}`,
+        pointerEvents: "none",
+      };
+    case "bottom":
+      return {
+        position: "absolute",
+        bottom: `${insetBottom}px`,
+        left: `${insetLeft}px`,
+        right: `${insetRight}px`,
+        height: `${widthPx}px`,
+        borderBottom: `${widthPx}px ${styleName} ${color}`,
+        pointerEvents: "none",
+      };
+    case "left":
+      return {
+        position: "absolute",
+        top: `${insetTop}px`,
+        bottom: `${insetBottom}px`,
+        left: `${insetLeft}px`,
+        width: `${widthPx}px`,
+        borderLeft: `${widthPx}px ${styleName} ${color}`,
+        pointerEvents: "none",
+      };
+    case "right":
+      return {
+        position: "absolute",
+        top: `${insetTop}px`,
+        bottom: `${insetBottom}px`,
+        right: `${insetRight}px`,
+        width: `${widthPx}px`,
+        borderRight: `${widthPx}px ${styleName} ${color}`,
+        pointerEvents: "none",
+      };
+  }
+}
+
+export function TwPageBorderOverlay(
+  props: TwPageBorderOverlayProps,
+): React.ReactElement | null {
+  const {
+    layout,
+    pageInSection,
+    pageWidthPx,
+    pageHeightPx,
+    marginLeftPx,
+    marginRightPx,
+    marginTopPx,
+    marginBottomPx,
+  } = props;
+
+  const borders = resolvePageBorders(layout, pageInSection);
+  const columnOffsets = resolveColumnSeparatorXOffsets(layout);
+
+  // Nothing to paint at all → return null so React can skip the subtree.
+  const hasBorderEdges = !!borders?.display && (
+    borders.top !== null ||
+    borders.right !== null ||
+    borders.bottom !== null ||
+    borders.left !== null
+  );
+  if (!hasBorderEdges && columnOffsets.length === 0) {
+    return null;
+  }
+
+  // Insets — `offsetFrom: "page"` anchors to the page edge (= 0 inset);
+  // `offsetFrom: "text"` anchors to the text margin.  Per-edge `space`
+  // pushes the border further inward from that anchor.
+  const usePageOffset = (borders?.offsetFrom ?? "page") === "page";
+  const baseInsetTop = usePageOffset ? 0 : marginTopPx;
+  const baseInsetRight = usePageOffset ? 0 : marginRightPx;
+  const baseInsetBottom = usePageOffset ? 0 : marginBottomPx;
+  const baseInsetLeft = usePageOffset ? 0 : marginLeftPx;
+
+  return (
+    <div
+      data-page-border-overlay=""
+      data-page-in-section={pageInSection}
+      aria-hidden="true"
+      data-testid={props["data-testid"] ?? "page-border-overlay"}
+      style={{
+        position: "absolute",
+        inset: 0,
+        // zOrder: "back" sits visually behind text; default ("front") sits
+        // above.  Using `pointer-events: none` on every child means content
+        // remains clickable in either case.
+        zIndex: borders?.zOrder === "back" ? -1 : 1,
+        pointerEvents: "none",
+      }}
+    >
+      {hasBorderEdges && borders?.top ? (
+        <div
+          data-edge="top"
+          style={styleForEdge(
+            "top",
+            borders.top.widthPx,
+            borders.top.style,
+            borders.top.color,
+            baseInsetTop + borders.top.spacePx,
+            baseInsetRight,
+            baseInsetBottom,
+            baseInsetLeft,
+          )}
+        />
+      ) : null}
+      {hasBorderEdges && borders?.right ? (
+        <div
+          data-edge="right"
+          style={styleForEdge(
+            "right",
+            borders.right.widthPx,
+            borders.right.style,
+            borders.right.color,
+            baseInsetTop,
+            baseInsetRight + borders.right.spacePx,
+            baseInsetBottom,
+            baseInsetLeft,
+          )}
+        />
+      ) : null}
+      {hasBorderEdges && borders?.bottom ? (
+        <div
+          data-edge="bottom"
+          style={styleForEdge(
+            "bottom",
+            borders.bottom.widthPx,
+            borders.bottom.style,
+            borders.bottom.color,
+            baseInsetTop,
+            baseInsetRight,
+            baseInsetBottom + borders.bottom.spacePx,
+            baseInsetLeft,
+          )}
+        />
+      ) : null}
+      {hasBorderEdges && borders?.left ? (
+        <div
+          data-edge="left"
+          style={styleForEdge(
+            "left",
+            borders.left.widthPx,
+            borders.left.style,
+            borders.left.color,
+            baseInsetTop,
+            baseInsetRight,
+            baseInsetBottom,
+            baseInsetLeft + borders.left.spacePx,
+          )}
+        />
+      ) : null}
+      {/* Column separators — vertical hairlines centered in column gaps,
+          inset by the text margins so they paint inside the content box. */}
+      {columnOffsets.map((xPxFromContentLeft, i) => (
+        <div
+          key={`col-sep-${i}`}
+          data-column-separator=""
+          data-column-separator-index={i}
+          style={{
+            position: "absolute",
+            top: `${marginTopPx}px`,
+            bottom: `${marginBottomPx}px`,
+            left: `${marginLeftPx + xPxFromContentLeft}px`,
+            width: "1px",
+            backgroundColor: "var(--color-border-default, currentColor)",
+            opacity: 0.6,
+            pointerEvents: "none",
+          }}
+        />
+      ))}
+    </div>
+  );
+}
+
+export default TwPageBorderOverlay;

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

@@ -74,12 +74,50 @@ export interface PageOverlayRect {
 export interface PageBoundaryMeasurement {
   prevPageId: string;
   nextPageId: string;
+  boundaryIndex?: number;
   /** Widget top edge = bottom of the previous page. */
   topPx: number;
   /** Widget bottom edge = top of the next page. */
   bottomPx: number;
 }
 
+export interface VisiblePageIndexRange {
+  start: number;
+  end: number;
+}
+
+function normalizeVisiblePageIndexRange(
+  range: VisiblePageIndexRange | null | undefined,
+  pageCount: number,
+): VisiblePageIndexRange | null {
+  if (!range || pageCount <= 0) return null;
+  const start = Math.max(0, Math.min(range.start, pageCount));
+  const end = Math.max(start, Math.min(range.end, pageCount));
+  if (start >= end) return null;
+  return { start, end };
+}
+
+function collectBoundaryIndicesForVisibleRange(
+  range: VisiblePageIndexRange,
+  pageCount: number,
+): number[] {
+  if (pageCount <= 1) return [];
+  const startBoundaryIndex = Math.max(0, range.start - 1);
+  const endBoundaryIndex = Math.min(pageCount - 2, range.end - 1);
+  if (startBoundaryIndex > endBoundaryIndex) return [];
+  const indices: number[] = [];
+  for (let index = startBoundaryIndex; index <= endBoundaryIndex; index += 1) {
+    indices.push(index);
+  }
+  return indices;
+}
+
+function parsePageBoundaryIndex(prevPageId: string): number | undefined {
+  const match = /^page-(\d+)$/.exec(prevPageId);
+  if (!match) return undefined;
+  return Number.parseInt(match[1] ?? "", 10);
+}
+
 /**
  * Pure helper: turn pre-measured page-boundary widget positions into
  * one `PageOverlayRect` per page.  No DOM access — the caller supplies
@@ -104,6 +142,8 @@ export function resolvePageOverlayRects(
         pageCount: number;
         /** Total scroll-root height in the overlay's coordinate space. */
         scrollHeight: number;
+        /** Optional viewport-bounded page range. */
+        visiblePageIndexRange?: VisiblePageIndexRange | null;
       }
     // Legacy two-arg path preserved for backward compat.  Walks
     // offsetTop chain inside the scroll-root; used by harness code
@@ -158,12 +198,26 @@ export function resolvePageOverlayRects(
   // emits widgets out-of-order (it doesn't today, but the cost is
   // negligible).
   const boundaries = [...widgets].sort((a, b) => a.topPx - b.topPx);
+  const normalizedVisiblePageIndexRange = Array.isArray(input)
+    ? null
+    : normalizeVisiblePageIndexRange(input.visiblePageIndexRange, pageCount);
+  const boundaryByIndex = new Map<number, PageBoundaryMeasurement>();
+  boundaries.forEach((boundary, index) => {
+    const boundaryIndex =
+      boundary.boundaryIndex ??
+      parsePageBoundaryIndex(boundary.prevPageId) ??
+      index;
+    boundaryByIndex.set(boundaryIndex, boundary);
+  });
+  const pageStart = normalizedVisiblePageIndexRange?.start ?? 0;
+  const pageEnd = normalizedVisiblePageIndexRange?.end ?? pageCount;
 
   const rects: PageOverlayRect[] = [];
-  for (let pageIndex = 0; pageIndex < pageCount; pageIndex += 1) {
-    const boundaryBefore = pageIndex === 0 ? null : boundaries[pageIndex - 1];
+  for (let pageIndex = pageStart; pageIndex < pageEnd; pageIndex += 1) {
+    const boundaryBefore =
+      pageIndex === 0 ? null : (boundaryByIndex.get(pageIndex - 1) ?? null);
     const boundaryAfter =
-      pageIndex === pageCount - 1 ? null : boundaries[pageIndex];
+      pageIndex === pageCount - 1 ? null : (boundaryByIndex.get(pageIndex) ?? null);
 
     let pageId: string | null = null;
     if (boundaryBefore) pageId = boundaryBefore.nextPageId;
@@ -204,14 +258,36 @@ export function resolvePageOverlayRects(
  * ancestor.
  */
 export function measureWidgetsViaBoundingRect(
-  queryRoot: Pick<HTMLElement, "querySelectorAll"> | null,
+  queryRoot: Pick<HTMLElement, "querySelectorAll"> &
+    Partial<Pick<HTMLElement, "querySelector">> | null,
   originElement: HTMLElement | null,
+  options?: {
+    pageCount?: number;
+    visiblePageIndexRange?: VisiblePageIndexRange | null;
+  },
 ): PageBoundaryMeasurement[] {
   if (!queryRoot || !originElement) return [];
   const originRect = originElement.getBoundingClientRect();
-  const widgets = Array.from(
-    queryRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+  const normalizedVisiblePageIndexRange = normalizeVisiblePageIndexRange(
+    options?.visiblePageIndexRange,
+    options?.pageCount ?? 0,
   );
+  const queryOne =
+    typeof queryRoot.querySelector === "function"
+      ? queryRoot.querySelector.bind(queryRoot)
+      : null;
+  const widgets = normalizedVisiblePageIndexRange && queryOne && options?.pageCount
+    ? collectBoundaryIndicesForVisibleRange(
+        normalizedVisiblePageIndexRange,
+        options.pageCount,
+      )
+        .map((boundaryIndex) =>
+          queryOne(`[data-page-frame-end="page-${boundaryIndex}"]`),
+        )
+        .filter((widget): widget is HTMLElement => widget !== null)
+    : Array.from(
+        queryRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+      );
   const out: PageBoundaryMeasurement[] = [];
   for (const widget of widgets) {
     const prevPageId = widget.getAttribute("data-page-frame-end");
@@ -221,6 +297,7 @@ export function measureWidgetsViaBoundingRect(
     out.push({
       prevPageId,
       nextPageId,
+      boundaryIndex: parsePageBoundaryIndex(prevPageId),
       topPx: rect.top - originRect.top,
       bottomPx: rect.bottom - originRect.top,
     });
@@ -242,11 +319,33 @@ export function measureWidgetsViaBoundingRect(
  * "scroll root is often not the right origin", not about arithmetic.
  */
 export function measureWidgetsViaOffsetChain(
-  scrollRoot: Pick<HTMLElement, "clientHeight" | "querySelectorAll">,
+  scrollRoot: Pick<HTMLElement, "clientHeight" | "querySelectorAll"> &
+    Partial<Pick<HTMLElement, "querySelector">>,
+  options?: {
+    pageCount?: number;
+    visiblePageIndexRange?: VisiblePageIndexRange | null;
+  },
 ): PageBoundaryMeasurement[] {
-  const widgets = Array.from(
-    scrollRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+  const normalizedVisiblePageIndexRange = normalizeVisiblePageIndexRange(
+    options?.visiblePageIndexRange,
+    options?.pageCount ?? 0,
   );
+  const queryOne =
+    typeof scrollRoot.querySelector === "function"
+      ? scrollRoot.querySelector.bind(scrollRoot)
+      : null;
+  const widgets = normalizedVisiblePageIndexRange && queryOne && options?.pageCount
+    ? collectBoundaryIndicesForVisibleRange(
+        normalizedVisiblePageIndexRange,
+        options.pageCount,
+      )
+        .map((boundaryIndex) =>
+          queryOne(`[data-page-frame-end="page-${boundaryIndex}"]`),
+        )
+        .filter((widget): widget is HTMLElement => widget !== null)
+    : Array.from(
+        scrollRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+      );
   const out: PageBoundaryMeasurement[] = [];
   for (const widget of widgets) {
     const prevPageId = widget.getAttribute("data-page-frame-end");
@@ -254,7 +353,13 @@ export function measureWidgetsViaOffsetChain(
     if (!prevPageId || !nextPageId) continue;
     const topPx = resolveOffsetTop(widget, scrollRoot);
     const bottomPx = topPx + resolveOffsetHeight(widget);
-    out.push({ prevPageId, nextPageId, topPx, bottomPx });
+    out.push({
+      prevPageId,
+      nextPageId,
+      boundaryIndex: parsePageBoundaryIndex(prevPageId),
+      topPx,
+      bottomPx,
+    });
   }
   return out;
 }
@@ -297,6 +402,7 @@ export interface TwPageStackOverlayLayerProps {
    * time this changes so the overlays stay aligned with content.
    */
   renderFrameRevision: number;
+  visiblePageIndexRange?: VisiblePageIndexRange | null;
   /** Optional test id applied to the overlay root. */
   "data-testid"?: string;
 }
@@ -313,6 +419,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   facet,
   scrollRoot,
   renderFrameRevision,
+  visiblePageIndexRange,
   "data-testid": testId,
 }) => {
   const [rects, setRects] = React.useState<readonly PageOverlayRect[]>([]);
@@ -351,7 +458,10 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     const origin = overlayRootRef.current;
     const pageCount = facet.getPageCount();
     if (origin) {
-      const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin);
+      const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
+        pageCount,
+        visiblePageIndexRange,
+      });
       const originRect = origin.getBoundingClientRect();
       setRects(
         resolvePageOverlayRects({
@@ -359,12 +469,24 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
           pageCount,
           scrollHeight:
             origin.clientHeight > 0 ? origin.clientHeight : originRect.height,
+          visiblePageIndexRange,
         }),
       );
     } else {
-      setRects(resolvePageOverlayRects([scrollRoot, pageCount]));
+      const widgets = measureWidgetsViaOffsetChain(scrollRoot, {
+        pageCount,
+        visiblePageIndexRange,
+      });
+      setRects(
+        resolvePageOverlayRects({
+          widgets,
+          pageCount,
+          scrollHeight: scrollRoot.clientHeight,
+          visiblePageIndexRange,
+        }),
+      );
     }
-  }, [facet, scrollRoot]);
+  }, [facet, scrollRoot, visiblePageIndexRange]);
 
   const refreshRects = React.useCallback(() => {
     if (!scrollRoot) {

package/src/ui-tailwind/chrome-overlay/tw-revision-margin-bar-layer.tsx

@@ -0,0 +1,51 @@
+import * as React from "react";
+import type { RenderBlockDecoration } from "../../runtime/render/render-frame-types";
+import { AUTHOR_PALETTE } from "../../ui/headless/revision-decoration-model";
+
+const BAR_WIDTH_PX = 3;
+const BAR_LEFT_OFFSET_PX = 8;
+
+export interface TwRevisionMarginBarLayerProps {
+  /** Decoration rects from `frame.decorationIndex.revisions`. */
+  revisionDecorations: readonly RenderBlockDecoration[];
+  /**
+   * Author palette index keyed by revisionId.
+   * Build from `RevisionDecorationEntry.authorPaletteIndex` before passing.
+   */
+  authorPaletteIndexById: ReadonlyMap<string, number>;
+  /** Left edge of the page body in overlay coordinates (px). */
+  pageBodyLeftPx: number;
+}
+
+export const TwRevisionMarginBarLayer = React.memo(function TwRevisionMarginBarLayer({
+  revisionDecorations,
+  authorPaletteIndexById,
+  pageBodyLeftPx,
+}: TwRevisionMarginBarLayerProps) {
+  if (revisionDecorations.length === 0) return null;
+
+  return (
+    <>
+      {revisionDecorations.map((dec, idx) => {
+        const paletteIdx = authorPaletteIndexById.get(dec.refId) ?? 0;
+        const color = AUTHOR_PALETTE[paletteIdx % AUTHOR_PALETTE.length];
+        return (
+          <div
+            key={`rev-bar-${dec.refId}-${idx}`}
+            aria-hidden
+            style={{
+              position: "absolute",
+              top: dec.frame.topPx,
+              left: pageBodyLeftPx - BAR_LEFT_OFFSET_PX - BAR_WIDTH_PX,
+              width: BAR_WIDTH_PX,
+              height: dec.frame.heightPx,
+              backgroundColor: color,
+              borderRadius: 1,
+              pointerEvents: "none",
+            }}
+          />
+        );
+      })}
+    </>
+  );
+});

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

@@ -114,10 +114,18 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   const pinnedModel = pinnedScopeId
     ? models.find((m) => m.scopeId === pinnedScopeId) ?? null
     : null;
-  if (pinnedScopeId && !pinnedModel) {
-    // Async cleanup via effect to avoid setState during render.
-    queueMicrotask(() => setPinnedScopeId(null));
-  }
+
+  // R2.b — when a pinned scope disappears from the model list (e.g. the
+  // host cleared the overlay), drop the pin. Must run in an effect, not
+  // inline in render: a render-phase setState call violates React's
+  // render-purity contract and can trigger "Maximum update depth
+  // exceeded" in React 18 concurrent mode where renders are retried
+  // before commit.
+  React.useEffect(() => {
+    if (pinnedScopeId && !models.find((m) => m.scopeId === pinnedScopeId)) {
+      setPinnedScopeId(null);
+    }
+  }, [pinnedScopeId, models]);
 
   const effectiveScopeId = pinnedModel ? pinnedScopeId : activeScopeId;
   if (!effectiveScopeId) return null;