@beyondwork/docx-react-component 1.0.37 → 1.0.39

package/src/ui-tailwind/chrome/tw-table-grip-layer.tsx

@@ -0,0 +1,284 @@
+/**
+ * TwTableGripLayer — column-resize and row-resize grips for the active table.
+ *
+ * Grips are positioned via the render-kernel anchor index (P4):
+ *   - Column grips:  `anchorIndex.byTableColumnEdge(blockId, colIndex)`
+ *   - Row grips:     `anchorIndex.byTableRowEdge(blockId, rowIndex)`
+ *
+ * This is a pure overlay consumer: no DOM measurement, no selection mutation,
+ * no PM transactions.  Drag deltas are converted from px → twips using the
+ * kernel's `pxPerTwip` ratio and dispatched through `onSetColumnWidth` /
+ * `onSetRowHeight` callbacks (which route to `ref.tables.apply(op)`).
+ *
+ * Drag state lives in `useRef` so moves don't trigger re-renders mid-drag.
+ */
+
+import React, { useCallback, useEffect, useRef } from "react";
+
+import type {
+  TableStructureContextSnapshot,
+  WordReviewEditorLayoutFacet,
+} from "../../api/public-types";
+import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
+import type { OverlayCoordinateSpace } from "../chrome-overlay/chrome-overlay-projector";
+import { projectRectToOverlay } from "../chrome-overlay/chrome-overlay-projector";
+import { DEFAULT_PX_PER_TWIP } from "../../runtime/render/render-frame-types";
+
+const GRIP_PX = 6;
+const MIN_COLUMN_TWIPS = 720;
+const MIN_ROW_TWIPS = 120;
+
+export interface TwTableGripLayerProps {
+  facet: WordReviewEditorLayoutFacet;
+  tableContext: TableStructureContextSnapshot | null;
+  space?: OverlayCoordinateSpace;
+  disabled?: boolean;
+  onSetColumnWidth?: (columnIndex: number, twips: number) => void;
+  onSetRowHeight?: (
+    rowIndex: number,
+    twips: number,
+    rule: "auto" | "atLeast" | "exact",
+  ) => void;
+}
+
+export function TwTableGripLayer({
+  facet,
+  tableContext,
+  space,
+  disabled,
+  onSetColumnWidth,
+  onSetRowHeight,
+}: TwTableGripLayerProps) {
+  if (!tableContext) return null;
+
+  const frame =
+    typeof facet.getRenderFrame === "function"
+      ? (facet.getRenderFrame() ?? null)
+      : null;
+  if (!frame) return null;
+
+  const blockId = `table-${tableContext.tableBlockIndex}`;
+  const pageIndex = facet.getFirstPageIndexForBlock(blockId) ?? 0;
+  const plan = facet.getTableRenderPlan(blockId, pageIndex);
+  if (!plan) return null;
+
+  const pxPerTwip =
+    typeof facet.getRenderZoom === "function"
+      ? (facet.getRenderZoom()?.pxPerTwip ?? DEFAULT_PX_PER_TWIP)
+      : DEFAULT_PX_PER_TWIP;
+
+  return (
+    <>
+      {plan.columnResizeHandles.map((handle) => {
+        const rect = frame.anchorIndex.byTableColumnEdge(
+          blockId,
+          handle.columnIndex,
+        );
+        if (!rect) return null;
+        const pos = projectRectToOverlay(rect, space);
+        return (
+          <ColResizeGrip
+            key={`col-${blockId}-${handle.columnIndex}`}
+            pos={pos}
+            colIndex={handle.columnIndex}
+            originalTwips={plan.columnsTwips[handle.columnIndex] ?? 720}
+            pxPerTwip={pxPerTwip}
+            disabled={!!disabled || !onSetColumnWidth}
+            onCommit={onSetColumnWidth}
+          />
+        );
+      })}
+      {Array.from({ length: tableContext.rowCount }, (_, rowIndex) => {
+        const rect = frame.anchorIndex.byTableRowEdge(blockId, rowIndex);
+        if (!rect) return null;
+        const pos = projectRectToOverlay(rect, space);
+        return (
+          <RowResizeGrip
+            key={`row-${blockId}-${rowIndex}`}
+            pos={pos}
+            rowIndex={rowIndex}
+            pxPerTwip={pxPerTwip}
+            disabled={!!disabled || !onSetRowHeight}
+            onCommit={onSetRowHeight}
+          />
+        );
+      })}
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Column resize grip
+// ---------------------------------------------------------------------------
+
+interface ColResizeGripProps {
+  pos: { left: string; top: string; width: string; height: string };
+  colIndex: number;
+  originalTwips: number;
+  pxPerTwip: number;
+  disabled: boolean;
+  onCommit?: (columnIndex: number, twips: number) => void;
+}
+
+function ColResizeGrip({
+  pos,
+  colIndex,
+  originalTwips,
+  pxPerTwip,
+  disabled,
+  onCommit,
+}: ColResizeGripProps) {
+  const dragRef = useRef<{
+    startX: number;
+    originalTwips: number;
+  } | null>(null);
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent<HTMLElement>) => {
+      if (disabled) return;
+      preserveEditorSelectionMouseDown(e);
+      dragRef.current = { startX: e.clientX, originalTwips };
+    },
+    [disabled, originalTwips],
+  );
+
+  useEffect(() => {
+    const handleMove = (e: MouseEvent) => {
+      if (!dragRef.current) return;
+      e.preventDefault();
+    };
+    const handleUp = (e: MouseEvent) => {
+      if (!dragRef.current) return;
+      const deltaX = e.clientX - dragRef.current.startX;
+      const deltaTwips = deltaX / pxPerTwip;
+      const newTwips = Math.max(
+        MIN_COLUMN_TWIPS,
+        Math.round(dragRef.current.originalTwips + deltaTwips),
+      );
+      dragRef.current = null;
+      onCommit?.(colIndex, newTwips);
+    };
+    window.addEventListener("mousemove", handleMove);
+    window.addEventListener("mouseup", handleUp);
+    return () => {
+      window.removeEventListener("mousemove", handleMove);
+      window.removeEventListener("mouseup", handleUp);
+    };
+  }, [colIndex, pxPerTwip, onCommit]);
+
+  return (
+    <div
+      role="separator"
+      aria-orientation="vertical"
+      aria-label={`Resize column ${colIndex + 1}`}
+      data-testid={`col-resize-grip-${colIndex}`}
+      className={[
+        "pointer-events-auto absolute",
+        disabled
+          ? "cursor-default opacity-0"
+          : "cursor-col-resize opacity-0 hover:opacity-100",
+        "transition-opacity",
+        "bg-accent",
+      ].join(" ")}
+      style={{
+        left: `calc(${pos.left} - ${GRIP_PX / 2}px)`,
+        top: pos.top,
+        width: `${GRIP_PX}px`,
+        height: pos.height,
+      }}
+      onMouseDown={handleMouseDown}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Row resize grip
+// ---------------------------------------------------------------------------
+
+interface RowResizeGripProps {
+  pos: { left: string; top: string; width: string; height: string };
+  rowIndex: number;
+  pxPerTwip: number;
+  disabled: boolean;
+  onCommit?: (
+    rowIndex: number,
+    twips: number,
+    rule: "auto" | "atLeast" | "exact",
+  ) => void;
+}
+
+function RowResizeGrip({
+  pos,
+  rowIndex,
+  pxPerTwip,
+  disabled,
+  onCommit,
+}: RowResizeGripProps) {
+  const dragRef = useRef<{
+    startY: number;
+    startHeightPx: number;
+  } | null>(null);
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent<HTMLElement>) => {
+      if (disabled) return;
+      preserveEditorSelectionMouseDown(e);
+      // Start height is the current visible row height from the grip rect.
+      // We use the grip's own top position vs. previous row edge as a proxy.
+      dragRef.current = { startY: e.clientY, startHeightPx: 0 };
+    },
+    [disabled],
+  );
+
+  useEffect(() => {
+    const handleMove = (e: MouseEvent) => {
+      if (!dragRef.current) return;
+      e.preventDefault();
+    };
+    const handleUp = (e: MouseEvent) => {
+      if (!dragRef.current) return;
+      const deltaY = e.clientY - dragRef.current.startY;
+      if (Math.abs(deltaY) < 2) {
+        dragRef.current = null;
+        return;
+      }
+      const deltaTwips = deltaY / pxPerTwip;
+      // We don't know the current row height from the grip alone; use atLeast
+      // so that a positive drag expands and a negative drag collapses to auto.
+      const newTwips = Math.max(MIN_ROW_TWIPS, Math.round(deltaTwips));
+      const rule = newTwips > 0 ? "atLeast" : "auto";
+      dragRef.current = null;
+      onCommit?.(rowIndex, newTwips, rule as "atLeast");
+    };
+    window.addEventListener("mousemove", handleMove);
+    window.addEventListener("mouseup", handleUp);
+    return () => {
+      window.removeEventListener("mousemove", handleMove);
+      window.removeEventListener("mouseup", handleUp);
+    };
+  }, [rowIndex, pxPerTwip, onCommit]);
+
+  return (
+    <div
+      role="separator"
+      aria-orientation="horizontal"
+      aria-label={`Resize row ${rowIndex + 1}`}
+      data-testid={`row-resize-grip-${rowIndex}`}
+      className={[
+        "pointer-events-auto absolute",
+        disabled
+          ? "cursor-default opacity-0"
+          : "cursor-row-resize opacity-0 hover:opacity-100",
+        "transition-opacity",
+        "bg-accent",
+      ].join(" ")}
+      style={{
+        left: pos.left,
+        top: `calc(${pos.top} - ${GRIP_PX / 2}px)`,
+        width: pos.width,
+        height: `${GRIP_PX}px`,
+      }}
+      onMouseDown={handleMouseDown}
+    />
+  );
+}

package/src/ui-tailwind/chrome-overlay/chrome-overlay-projector.ts

@@ -0,0 +1,94 @@
+/**
+ * Chrome-overlay projector — maps `RenderFrameRect` values into CSS-absolute
+ * positions under a chrome overlay's own coordinate space.
+ *
+ * Per runtime-rendering-and-chrome-phase.md §6.2, every overlay child reads
+ * the same rect math so rails, balloons, toolbars, and handles stay aligned
+ * on scroll, zoom, and resize.  The projector is a tiny pure helper so the
+ * rect math can be unit-tested and reused.
+ */
+
+import type { RenderFrameRect } from "../../runtime/render/index.ts";
+import { recordPerfSample } from "../editor-surface/perf-probe.ts";
+
+export interface OverlayCoordinateSpace {
+  /** Top-left of the overlay in the document column's coordinate space. */
+  originLeftPx: number;
+  originTopPx: number;
+}
+
+export interface CSSRect {
+  left: string;
+  top: string;
+  width: string;
+  height: string;
+}
+
+/**
+ * Convert a RenderFrameRect (which is relative to the document column's
+ * top-left) into CSS absolute-position values relative to the overlay's own
+ * coordinate space.  Output uses `px` units so consumers can pass the
+ * result straight to inline `style={{...}}`.
+ */
+export function projectRectToOverlay(
+  rect: RenderFrameRect,
+  space: OverlayCoordinateSpace = { originLeftPx: 0, originTopPx: 0 },
+): CSSRect {
+  const t0 = typeof performance !== "undefined" ? performance.now() : 0;
+  const result: CSSRect = {
+    left: `${rect.leftPx - space.originLeftPx}px`,
+    top: `${rect.topPx - space.originTopPx}px`,
+    width: `${rect.widthPx}px`,
+    height: `${rect.heightPx}px`,
+  };
+  if (t0 > 0) recordPerfSample("chrome.overlay_reposition", performance.now() - t0);
+  return result;
+}
+
+/**
+ * Expand a page-interior rect outward by `padLeftPx` / `padRightPx` so a
+ * decoration can spill into the page margin (scope rail gutter).  The
+ * output rect width is adjusted accordingly.
+ */
+export function inflateRect(
+  rect: RenderFrameRect,
+  pad: {
+    leftPx?: number;
+    rightPx?: number;
+    topPx?: number;
+    bottomPx?: number;
+  },
+): RenderFrameRect {
+  const padLeft = pad.leftPx ?? 0;
+  const padRight = pad.rightPx ?? 0;
+  const padTop = pad.topPx ?? 0;
+  const padBottom = pad.bottomPx ?? 0;
+  return {
+    leftPx: rect.leftPx - padLeft,
+    topPx: rect.topPx - padTop,
+    widthPx: rect.widthPx + padLeft + padRight,
+    heightPx: rect.heightPx + padTop + padBottom,
+  };
+}
+
+/**
+ * Union of two rects; returns `null` if either input is nullish so callers
+ * can safely chain lookups.
+ */
+export function unionRect(
+  a: RenderFrameRect | null | undefined,
+  b: RenderFrameRect | null | undefined,
+): RenderFrameRect | null {
+  if (!a) return b ?? null;
+  if (!b) return a;
+  const left = Math.min(a.leftPx, b.leftPx);
+  const top = Math.min(a.topPx, b.topPx);
+  const right = Math.max(a.leftPx + a.widthPx, b.leftPx + b.widthPx);
+  const bottom = Math.max(a.topPx + a.heightPx, b.topPx + b.heightPx);
+  return {
+    leftPx: left,
+    topPx: top,
+    widthPx: right - left,
+    heightPx: bottom - top,
+  };
+}

package/src/ui-tailwind/chrome-overlay/index.ts

@@ -0,0 +1,16 @@
+/**
+ * ChromeOverlay public module entry.
+ *
+ * Importers should pull the overlay + layer components from here; the
+ * internal layer files may be reorganized as the chrome phase continues.
+ */
+
+export { TwChromeOverlay, type TwChromeOverlayProps } from "./tw-chrome-overlay";
+export { TwScopeRailLayer, type TwScopeRailLayerProps } from "./tw-scope-rail-layer";
+export {
+  inflateRect,
+  projectRectToOverlay,
+  unionRect,
+  type CSSRect,
+  type OverlayCoordinateSpace,
+} from "./chrome-overlay-projector";

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

@@ -0,0 +1,96 @@
+/**
+ * ChromeOverlay — the single absolute-positioned overlay plane that hosts
+ * every over-document surface (scope rail, comment balloons, revision
+ * margin bars, object handles, workspace view-switcher dock).
+ *
+ * Per runtime-rendering-and-chrome-phase.md §6.2, every overlay child
+ * receives `ref.layout` and reads its position from the same render-frame
+ * anchor index — not DOM rects, not selection rects — so the chrome stays
+ * in place across scroll, zoom, and relayout.
+ *
+ * This component owns only the plane and the shared coordinate space.
+ * Each layer it composes is a pure consumer of the facet.
+ */
+
+import * as React from "react";
+import type { OverlayCoordinateSpace } from "./chrome-overlay-projector";
+import type { ScopeRailSegment } from "../../runtime/layout";
+import type {
+  TableStructureContextSnapshot,
+  WordReviewEditorLayoutFacet,
+} from "../../api/public-types";
+import { TwScopeRailLayer } from "./tw-scope-rail-layer";
+import { TwTableGripLayer } from "../chrome/tw-table-grip-layer";
+
+export interface TwChromeOverlayProps {
+  /** Layout facet the overlay layers read from. */
+  facet: WordReviewEditorLayoutFacet;
+  /** Optional coordinate space override.  Defaults to the overlay origin. */
+  space?: OverlayCoordinateSpace;
+  /** Active scope id (for emphasis + rail tab sync). */
+  activeScopeId?: string | null;
+  /** Click handler the rail layer forwards to consumers. */
+  onScopeSegmentClick?: (segment: ScopeRailSegment) => void;
+  /** Test id applied to the overlay root. */
+  "data-testid"?: string;
+  /** Optional extra children (e.g., future comment balloon layer). */
+  children?: React.ReactNode;
+
+  // Table grip props (P6) -----------------------------------------------
+  /** Active table context — when present, column/row resize grips are shown. */
+  tableContext?: TableStructureContextSnapshot | null;
+  /** Fires when a column grip drag completes. */
+  onSetColumnWidth?: (columnIndex: number, twips: number) => void;
+  /** Fires when a row grip drag completes. */
+  onSetRowHeight?: (
+    rowIndex: number,
+    twips: number,
+    rule: "auto" | "atLeast" | "exact",
+  ) => void;
+}
+
+/**
+ * Placement contract:
+ *   - The overlay is an absolutely positioned `div` that fills its parent.
+ *   - The parent must be `position: relative` so the overlay anchors to
+ *     the document column (not the viewport).
+ *   - Pointer events are disabled on the root so the editor surface under
+ *     the overlay continues to receive input; individual layers opt in to
+ *     pointer events on their interactive elements (buttons, handles).
+ */
+export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
+  facet,
+  space,
+  activeScopeId,
+  onScopeSegmentClick,
+  "data-testid": testId,
+  children,
+  tableContext,
+  onSetColumnWidth,
+  onSetRowHeight,
+}) => {
+  return (
+    <div
+      className="wre-chrome-overlay pointer-events-none absolute inset-0 z-30"
+      data-testid={testId ?? "chrome-overlay"}
+      role="presentation"
+    >
+      <TwScopeRailLayer
+        facet={facet}
+        space={space}
+        activeScopeId={activeScopeId}
+        onSegmentClick={onScopeSegmentClick}
+      />
+      <TwTableGripLayer
+        facet={facet}
+        tableContext={tableContext ?? null}
+        space={space}
+        onSetColumnWidth={onSetColumnWidth}
+        onSetRowHeight={onSetRowHeight}
+      />
+      {children}
+    </div>
+  );
+};
+
+export default TwChromeOverlay;

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

@@ -0,0 +1,178 @@
+/**
+ * Scope rail layer — renders workflow scopes as a continuous zone with a
+ * gutter icon + label column OUTSIDE the document flow plus a flat block-
+ * level tint BEHIND the scoped paragraphs.
+ *
+ * Per runtime-rendering-and-chrome-phase.md §5, the rail is a projection
+ * over canonical workflow scopes; it never lives inside the PM NodeView
+ * tree.  Positions come from the render kernel's anchor index — not from
+ * DOM rect math — so the rail stays aligned across scroll, zoom, resize,
+ * and through predicted-text reconciliation.
+ */
+
+import * as React from "react";
+import {
+  inflateRect,
+  projectRectToOverlay,
+  unionRect,
+  type OverlayCoordinateSpace,
+} from "./chrome-overlay-projector";
+import type { RenderFrameRect } from "../../runtime/render";
+import type { ScopeRailSegment, ScopeRailPosture } from "../../runtime/layout";
+import type { WordReviewEditorLayoutFacet } from "../../runtime/layout";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TwScopeRailLayerProps {
+  /** Layout facet that provides segments + anchor index. */
+  facet: WordReviewEditorLayoutFacet;
+  /** Overlay's coordinate space.  Defaults to the overlay's own origin. */
+  space?: OverlayCoordinateSpace;
+  /** Horizontal padding (px) the rail gutter occupies to the left of body. */
+  railLaneWidthPx?: number;
+  /** Optional click handler for a segment label (open-scope drawer, etc). */
+  onSegmentClick?: (segment: ScopeRailSegment) => void;
+  /** Scope id that should render with the `active` emphasis. */
+  activeScopeId?: string | null;
+  /** Test id applied to the layer root. */
+  "data-testid"?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Posture → visual grammar
+// ---------------------------------------------------------------------------
+
+interface PostureStyle {
+  labelText: string;
+  icon: string; // lucide-style key; CSS ::before handles glyph in production
+  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 = 120;
+const LABEL_WIDTH_PX = 92;
+
+export const TwScopeRailLayer: React.FC<TwScopeRailLayerProps> = ({
+  facet,
+  space,
+  railLaneWidthPx = DEFAULT_RAIL_LANE_PX,
+  onSegmentClick,
+  activeScopeId,
+  "data-testid": testId,
+}) => {
+  // Read the render frame once per paint cycle.  The facet.subscribe path
+  // already invalidates the caller's React state on layout changes, so we
+  // just read on render.
+  const frame = typeof facet.getRenderFrame === "function"
+    ? facet.getRenderFrame() ?? null
+    : null;
+  const segments = facet.getAllScopeRailSegments();
+
+  if (!frame || segments.length === 0) {
+    return null;
+  }
+
+  // Group segments by scopeId so multi-page scopes render one contiguous
+  // tint per page range.  (Per-page render happens below because each
+  // scope may span pages.)
+  const items = segments.map((segment) => {
+    const rect = resolveSegmentRect(facet, frame, segment);
+    if (!rect) return null;
+    const style = POSTURE_STYLES[segment.posture];
+    return { segment, rect, style };
+  }).filter((item): item is NonNullable<typeof item> => item !== null);
+
+  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"
+    >
+      {items.map(({ segment, rect, style }) => {
+        const isActive = activeScopeId === segment.scopeId || segment.isActiveWorkItem;
+        const tintRect = inflateRect(rect, { leftPx: 4, rightPx: 4, topPx: 2, bottomPx: 2 });
+        const labelRect: RenderFrameRect = {
+          leftPx: rect.leftPx - railLaneWidthPx,
+          topPx: rect.topPx,
+          widthPx: LABEL_WIDTH_PX,
+          heightPx: Math.max(20, Math.min(rect.heightPx, 48)),
+        };
+
+        return (
+          <React.Fragment key={`${segment.scopeId}:${segment.pageIndex}:${segment.fromOffset}`}>
+            {/* Flat tint behind the scoped block region */}
+            <div
+              className={`wre-scope-rail-tint wre-scope-rail-tint-${style.tintToken} absolute ${
+                isActive ? "wre-scope-rail-tint-active" : ""
+              }`}
+              data-scope-id={segment.scopeId}
+              data-posture={segment.posture}
+              style={projectRectToOverlay(tintRect, projectorSpace)}
+            />
+            {/* Gutter label + icon outside the page frame */}
+            <button
+              type="button"
+              className={`wre-scope-rail-label wre-scope-rail-label-${style.railToken} pointer-events-auto absolute flex flex-col items-center justify-center gap-1 rounded-md text-[10px] font-semibold uppercase tracking-[0.08em] ${
+                isActive ? "wre-scope-rail-label-active" : ""
+              }`}
+              data-scope-id={segment.scopeId}
+              data-posture={segment.posture}
+              data-icon={style.icon}
+              aria-label={`${style.labelText}${segment.label ? `: ${segment.label}` : ""}`}
+              onClick={onSegmentClick ? () => onSegmentClick(segment) : undefined}
+              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>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function resolveSegmentRect(
+  facet: WordReviewEditorLayoutFacet,
+  _frame: { anchorIndex: { byRuntimeOffset: (offset: number) => RenderFrameRect | null } },
+  segment: ScopeRailSegment,
+): RenderFrameRect | null {
+  const fromRect = _frame.anchorIndex.byRuntimeOffset(segment.fromOffset);
+  const toRect = _frame.anchorIndex.byRuntimeOffset(Math.max(segment.fromOffset, segment.toOffset - 1));
+  const unioned = unionRect(fromRect, toRect);
+  if (unioned) return unioned;
+  // Fall back to the page rect so long scopes that can't resolve per-line
+  // still render a posture in the gutter.
+  const fallbackPage = facet.getPage(segment.pageIndex);
+  if (!fallbackPage) return null;
+  // Approximate: derive a rect from the page's body region by asking the
+  // render frame for the page rect.  Without a render kernel kernel this
+  // function returns null and the segment is skipped.
+  return null;
+}
+
+export default TwScopeRailLayer;

package/src/ui-tailwind/editor-surface/fast-text-edit-lane.ts

@@ -103,6 +103,10 @@ export function createFastTextEditLane(
     intent: PredictedIntent,
     buildTx: (tr: Transaction) => Transaction | null,
   ): void {
+    // IME composition holds the DOM range; predicting through it would
+    // fight the browser's composition DOM mutations. The bridge's
+    // compositionstart/end handlers toggle this flag on the session.
+    if (options.session.isComposing()) return;
     const view = options.getView();
     const positionMap = options.getPositionMap();
     if (!view || !positionMap) return;