@beyondwork/docx-react-component 1.0.106 → 1.0.108

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

@@ -0,0 +1,259 @@
+import * as React from "react";
+
+import type {
+  ApiV3Ui,
+  GeometryRect,
+  UiOverlayLaneEntry,
+  UiOverlayLaneKind,
+  UiOverlayLaneSnapshot,
+} from "../../api/v3/ui/index.ts";
+import { AUTHOR_PALETTE } from "../../ui/headless/revision-decoration-model";
+import { useUiApi } from "../ui-api-context.tsx";
+import type { OverlayCoordinateSpace } from "./chrome-overlay-projector.ts";
+
+type ReviewLaneKind = Extract<UiOverlayLaneKind, "comments" | "issues" | "redlines">;
+
+const REVIEW_LANE_KINDS: readonly ReviewLaneKind[] = ["comments", "issues", "redlines"];
+const ZERO_SPACE: OverlayCoordinateSpace = { originLeftPx: 0, originTopPx: 0 };
+const REDLINE_BAR_WIDTH_PX = 3;
+const REDLINE_BAR_LEFT_OFFSET_PX = 8;
+
+export interface TwReviewOverlayLaneMarkersProps {
+  space?: OverlayCoordinateSpace;
+}
+
+/**
+ * L11 painter for review overlay lanes surfaced by L10.
+ *
+ * L06 owns comment/issue/redline semantics and L05/L10 own anchor geometry.
+ * This layer only joins resolved lane entries to `ui.overlays.getAnchor(...)`
+ * rects and paints non-interactive markers; unavailable or rehydration-only
+ * entries stay invisible.
+ */
+export function TwReviewOverlayLaneMarkers({
+  space = ZERO_SPACE,
+}: TwReviewOverlayLaneMarkersProps): React.ReactElement | null {
+  const ui = useUiApi();
+  const [lanes, setLanes] = React.useState<Readonly<Record<ReviewLaneKind, UiOverlayLaneSnapshot | null>>>(() =>
+    readReviewLanes(ui),
+  );
+  const [overlayRevision, setOverlayRevision] = React.useState(0);
+
+  React.useEffect(() => {
+    if (!ui) {
+      setLanes(readReviewLanes(null));
+      return undefined;
+    }
+
+    setLanes(readReviewLanes(ui));
+    const unsubscribers: Array<() => void> = [];
+
+    for (const kind of REVIEW_LANE_KINDS) {
+      try {
+        unsubscribers.push(
+          ui.overlays.subscribeLane(kind, (lane) => {
+            setLanes((current) => ({ ...current, [kind]: lane }));
+          }),
+        );
+      } catch {
+        // A cold controller already reports `unavailable` through getLane.
+      }
+    }
+
+    try {
+      unsubscribers.push(
+        ui.overlays.subscribe(() => {
+          setOverlayRevision((revision) => revision + 1);
+        }),
+      );
+    } catch {
+      // Overlay invalidation is best-effort; lane updates still repaint.
+    }
+
+    return () => {
+      for (const unsubscribe of unsubscribers) unsubscribe();
+    };
+  }, [ui]);
+
+  const markers = React.useMemo(
+    () => resolveReviewLaneMarkers(ui, lanes, space),
+    [ui, lanes, overlayRevision, space],
+  );
+
+  if (markers.length === 0) return null;
+
+  return (
+    <div
+      aria-hidden="true"
+      className="wre-review-overlay-lane-markers pointer-events-none absolute inset-0"
+      data-review-overlay-lane-markers=""
+      data-overlay-revision={overlayRevision}
+    >
+      {markers.map((marker) => (
+        <div
+          className="wre-review-overlay-lane-marker pointer-events-none absolute flex items-center justify-center rounded-sm border bg-white text-[10px] font-semibold leading-none shadow-sm"
+          data-review-lane-kind={marker.kind}
+          data-review-lane-entry-id={marker.entryId}
+          data-review-lane-marker-shape={marker.shape}
+          key={`${marker.kind}:${marker.entryId}`}
+          style={marker.style}
+          title={marker.title}
+        >
+          {marker.label}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+interface ReviewLaneMarker {
+  kind: ReviewLaneKind;
+  entryId: string;
+  label: string;
+  shape: "badge" | "bar";
+  title: string;
+  style: React.CSSProperties;
+}
+
+export function resolveReviewLaneMarkers(
+  ui: ApiV3Ui | null,
+  lanes: Readonly<Record<ReviewLaneKind, UiOverlayLaneSnapshot | null>>,
+  space: OverlayCoordinateSpace = ZERO_SPACE,
+): ReviewLaneMarker[] {
+  if (!ui) return [];
+
+  const markers: ReviewLaneMarker[] = [];
+  for (const kind of REVIEW_LANE_KINDS) {
+    const lane = lanes[kind];
+    if (!lane || lane.kind !== kind || lane.status === "unavailable") continue;
+
+    for (const entry of lane.entries) {
+      if (entry.status !== "resolved" || !entry.anchor) continue;
+      const rect = ui.overlays.getAnchor(entry.anchor);
+      if (!rect) continue;
+      markers.push(markerFromEntry(kind, entry, rect, space));
+    }
+  }
+  return markers;
+}
+
+function readReviewLanes(
+  ui: ApiV3Ui | null,
+): Readonly<Record<ReviewLaneKind, UiOverlayLaneSnapshot | null>> {
+  if (!ui) {
+    return { comments: null, issues: null, redlines: null };
+  }
+  return {
+    comments: ui.overlays.getLane("comments"),
+    issues: ui.overlays.getLane("issues"),
+    redlines: ui.overlays.getLane("redlines"),
+  };
+}
+
+function markerFromEntry(
+  kind: ReviewLaneKind,
+  entry: UiOverlayLaneEntry,
+  rect: GeometryRect,
+  space: OverlayCoordinateSpace,
+): ReviewLaneMarker {
+  if (kind === "redlines") {
+    return redlineMarkerFromEntry(entry, rect, space);
+  }
+
+  const issueSeverity = stringValue(entry.data?.severity);
+  const color =
+    kind === "issues"
+      ? issueColor(issueSeverity)
+      : "var(--color-semantic-info, #2563eb)";
+  const title =
+    kind === "comments"
+      ? stringValue(entry.data?.excerpt) ?? stringValue(entry.data?.anchorLabel) ?? entry.id
+      : stringValue(entry.data?.title) ?? stringValue(entry.data?.label) ?? entry.id;
+
+  return {
+    kind,
+    entryId: entry.id,
+    label: kind === "comments" ? "C" : "!",
+    shape: "badge",
+    title,
+    style: {
+      left: `${rect.leftPx - space.originLeftPx + Math.max(rect.widthPx, 0) + 4}px`,
+      top: `${rect.topPx - space.originTopPx}px`,
+      width: "18px",
+      height: "18px",
+      color,
+      borderColor: color,
+      zIndex: 9,
+    },
+  };
+}
+
+function redlineMarkerFromEntry(
+  entry: UiOverlayLaneEntry,
+  rect: GeometryRect,
+  space: OverlayCoordinateSpace,
+): ReviewLaneMarker {
+  const color = revisionColor(entry);
+  return {
+    kind: "redlines",
+    entryId: entry.id,
+    label: "",
+    shape: "bar",
+    title:
+      stringValue(entry.data?.label) ??
+      stringValue(entry.data?.excerpt) ??
+      stringValue(entry.data?.revisionKind) ??
+      entry.id,
+    style: {
+      left: `${rect.leftPx - space.originLeftPx - REDLINE_BAR_LEFT_OFFSET_PX - REDLINE_BAR_WIDTH_PX}px`,
+      top: `${rect.topPx - space.originTopPx}px`,
+      width: `${REDLINE_BAR_WIDTH_PX}px`,
+      height: `${Math.max(rect.heightPx, 12)}px`,
+      backgroundColor: color,
+      borderColor: color,
+      borderRadius: "1px",
+      zIndex: 8,
+    },
+  };
+}
+
+function revisionColor(entry: UiOverlayLaneEntry): string {
+  const paletteIndex = numberValue(entry.data?.authorPaletteIndex);
+  if (paletteIndex !== null) {
+    return AUTHOR_PALETTE[paletteIndex % AUTHOR_PALETTE.length];
+  }
+  const seed = stringValue(entry.data?.authorId) ?? stringValue(entry.data?.revisionId) ?? entry.id;
+  return AUTHOR_PALETTE[hashString(seed) % AUTHOR_PALETTE.length];
+}
+
+function issueColor(severity: string | null): string {
+  switch (severity) {
+    case "high":
+    case "critical":
+    case "fatal":
+      return "var(--color-semantic-error, #dc2626)";
+    case "medium":
+    case "warning":
+      return "var(--color-semantic-warning, #d97706)";
+    default:
+      return "var(--color-semantic-info, #2563eb)";
+  }
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function numberValue(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : null;
+}
+
+function hashString(value: string): number {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash * 31 + value.charCodeAt(index)) >>> 0;
+  }
+  return hash;
+}
+
+export default TwReviewOverlayLaneMarkers;

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

@@ -120,6 +120,9 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
 
   const getWorkflowScopeCardModel = React.useCallback(
     (scopeId: string): ScopeCardModel | null =>
+      // Compatibility fallback for no-provider tests/headless mounts.
+      // Mounted editor surfaces must prefer `api.ui.scope.card(...)`
+      // through `getVisibleScopeCardModel`.
       workflowFacet?.getAllScopeCardModels().find((m) => m.scopeId === scopeId) ??
       null,
     [workflowFacet],
@@ -177,7 +180,7 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
 
   const projectorSpace: OverlayCoordinateSpace =
     space ?? { originLeftPx: 0, originTopPx: 0 };
-  const positioned = resolveCardPosition(
+  const positioned = resolveScopeCardPosition(
     model.primaryAnchorRect,
     projectorSpace,
     viewportTopPx,
@@ -246,7 +249,7 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
  * own shadow token tweaks) can key off to verify which placement the
  * layer chose.
  */
-function resolveCardPosition(
+export function resolveScopeCardPosition(
   anchor: RenderFrameRect | null,
   space: OverlayCoordinateSpace,
   viewportTopPx: number,

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

@@ -0,0 +1,314 @@
+import * as React from "react";
+
+import type {
+  ApiV3Ui,
+  GeometryRect,
+  UiOverlayLaneEntry,
+  UiOverlayLaneKind,
+  UiOverlayLaneSnapshot,
+} from "../../api/v3/ui/index.ts";
+import { useUiApi } from "../ui-api-context.tsx";
+import type { OverlayCoordinateSpace } from "./chrome-overlay-projector.ts";
+
+type SubstrateLaneKind = Extract<
+  UiOverlayLaneKind,
+  | "selection"
+  | "caret"
+  | "field-scopes"
+  | "broad-scopes"
+  | "tables"
+  | "objects"
+  | "search"
+>;
+
+const SUBSTRATE_LANE_KINDS: readonly SubstrateLaneKind[] = [
+  "selection",
+  "caret",
+  "field-scopes",
+  "broad-scopes",
+  "tables",
+  "objects",
+  "search",
+];
+const ZERO_SPACE: OverlayCoordinateSpace = { originLeftPx: 0, originTopPx: 0 };
+
+export interface TwSubstrateOverlayLanesProps {
+  space?: OverlayCoordinateSpace;
+}
+
+/**
+ * L11 painter for the non-review L10 overlay lanes.
+ *
+ * L10 owns lane snapshots and L05 owns resolved rects/anchors. This component
+ * only paints entries already exposed through `ui.overlays`; unresolved,
+ * unavailable, anchorless, and unprojected entries remain invisible.
+ */
+export function TwSubstrateOverlayLanes({
+  space = ZERO_SPACE,
+}: TwSubstrateOverlayLanesProps): React.ReactElement | null {
+  const ui = useUiApi();
+  const [lanes, setLanes] = React.useState<Readonly<Record<SubstrateLaneKind, UiOverlayLaneSnapshot | null>>>(() =>
+    readSubstrateLanes(ui),
+  );
+  const [overlayRevision, setOverlayRevision] = React.useState(0);
+
+  React.useEffect(() => {
+    if (!ui) {
+      setLanes(readSubstrateLanes(null));
+      return undefined;
+    }
+
+    setLanes(readSubstrateLanes(ui));
+    const unsubscribers: Array<() => void> = [];
+
+    for (const kind of SUBSTRATE_LANE_KINDS) {
+      try {
+        unsubscribers.push(
+          ui.overlays.subscribeLane(kind, (lane) => {
+            setLanes((current) => ({ ...current, [kind]: lane }));
+          }),
+        );
+      } catch {
+        // Cold controllers report unavailable lanes through getLane.
+      }
+    }
+
+    try {
+      unsubscribers.push(
+        ui.overlays.subscribe(() => {
+          setOverlayRevision((revision) => revision + 1);
+        }),
+      );
+    } catch {
+      // Lane updates still repaint; coarse overlay ticks are best-effort.
+    }
+
+    return () => {
+      for (const unsubscribe of unsubscribers) unsubscribe();
+    };
+  }, [ui]);
+
+  const markers = React.useMemo(
+    () => resolveSubstrateLaneMarkers(ui, lanes, space),
+    [ui, lanes, overlayRevision, space],
+  );
+
+  if (markers.length === 0) return null;
+
+  return (
+    <div
+      aria-hidden="true"
+      className="wre-substrate-overlay-lanes pointer-events-none absolute inset-0"
+      data-substrate-overlay-lanes=""
+      data-overlay-revision={overlayRevision}
+    >
+      {markers.map((marker) => (
+        <div
+          className="wre-substrate-overlay-lane-marker pointer-events-none absolute"
+          data-substrate-lane-kind={marker.kind}
+          data-substrate-lane-entry-id={marker.entryId}
+          data-substrate-lane-shape={marker.shape}
+          key={marker.key}
+          style={marker.style}
+          title={marker.title}
+        />
+      ))}
+    </div>
+  );
+}
+
+interface SubstrateLaneMarker {
+  kind: SubstrateLaneKind;
+  entryId: string;
+  key: string;
+  shape: "rect" | "caret" | "outline" | "handle";
+  title: string;
+  style: React.CSSProperties;
+}
+
+export function resolveSubstrateLaneMarkers(
+  ui: ApiV3Ui | null,
+  lanes: Readonly<Record<SubstrateLaneKind, UiOverlayLaneSnapshot | null>>,
+  space: OverlayCoordinateSpace = ZERO_SPACE,
+): SubstrateLaneMarker[] {
+  if (!ui) return [];
+
+  const markers: SubstrateLaneMarker[] = [];
+  for (const kind of SUBSTRATE_LANE_KINDS) {
+    const lane = lanes[kind];
+    if (!lane || lane.kind !== kind || lane.status === "unavailable") continue;
+
+    for (const entry of lane.entries) {
+      if (entry.status !== "resolved") continue;
+      const rects = resolveEntryRects(ui, entry);
+      rects.forEach((rect, index) => {
+        markers.push(markerFromEntry(kind, entry, rect, index, space));
+      });
+    }
+  }
+  return markers;
+}
+
+function readSubstrateLanes(
+  ui: ApiV3Ui | null,
+): Readonly<Record<SubstrateLaneKind, UiOverlayLaneSnapshot | null>> {
+  if (!ui) {
+    return {
+      selection: null,
+      caret: null,
+      "field-scopes": null,
+      "broad-scopes": null,
+      tables: null,
+      objects: null,
+      search: null,
+    };
+  }
+  return {
+    selection: ui.overlays.getLane("selection"),
+    caret: ui.overlays.getLane("caret"),
+    "field-scopes": ui.overlays.getLane("field-scopes"),
+    "broad-scopes": ui.overlays.getLane("broad-scopes"),
+    tables: ui.overlays.getLane("tables"),
+    objects: ui.overlays.getLane("objects"),
+    search: ui.overlays.getLane("search"),
+  };
+}
+
+function resolveEntryRects(ui: ApiV3Ui, entry: UiOverlayLaneEntry): readonly GeometryRect[] {
+  if (entry.rects && entry.rects.length > 0) return entry.rects;
+  if (!entry.anchor) return [];
+  const rect = ui.overlays.getAnchor(entry.anchor);
+  return rect ? [rect] : [];
+}
+
+function markerFromEntry(
+  kind: SubstrateLaneKind,
+  entry: UiOverlayLaneEntry,
+  rect: GeometryRect,
+  index: number,
+  space: OverlayCoordinateSpace,
+): SubstrateLaneMarker {
+  const left = rect.leftPx - space.originLeftPx;
+  const top = rect.topPx - space.originTopPx;
+  const width = Math.max(rect.widthPx, kind === "caret" ? 2 : 1);
+  const height = Math.max(rect.heightPx, kind === "caret" ? 12 : 1);
+  const shape = markerShape(kind);
+  const color = markerColor(kind);
+  const title = stringValue(entry.data?.label) ?? stringValue(entry.data?.title) ?? entry.id;
+
+  return {
+    kind,
+    entryId: entry.id,
+    key: `${kind}:${entry.id}:${index}`,
+    shape,
+    title,
+    style: markerStyle({ kind, shape, left, top, width, height, color }),
+  };
+}
+
+function markerShape(kind: SubstrateLaneKind): SubstrateLaneMarker["shape"] {
+  switch (kind) {
+    case "caret":
+      return "caret";
+    case "field-scopes":
+    case "broad-scopes":
+    case "tables":
+      return "outline";
+    case "objects":
+      return "handle";
+    default:
+      return "rect";
+  }
+}
+
+function markerColor(kind: SubstrateLaneKind): string {
+  switch (kind) {
+    case "selection":
+      return "var(--color-selection, #93c5fd)";
+    case "caret":
+      return "var(--color-accent-primary, #2563eb)";
+    case "field-scopes":
+      return "var(--color-semantic-info, #2563eb)";
+    case "broad-scopes":
+      return "var(--color-semantic-success, #16a34a)";
+    case "tables":
+      return "var(--color-semantic-warning, #d97706)";
+    case "objects":
+      return "var(--color-accent-primary, #2563eb)";
+    case "search":
+      return "var(--color-search-highlight, #facc15)";
+  }
+}
+
+function markerStyle(input: {
+  kind: SubstrateLaneKind;
+  shape: SubstrateLaneMarker["shape"];
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  color: string;
+}): React.CSSProperties {
+  const base: React.CSSProperties = {
+    left: `${input.left}px`,
+    top: `${input.top}px`,
+    width: `${input.width}px`,
+    height: `${input.height}px`,
+    zIndex: zIndexForKind(input.kind),
+  };
+
+  switch (input.shape) {
+    case "caret":
+      return {
+        ...base,
+        width: "2px",
+        minHeight: "12px",
+        backgroundColor: input.color,
+        borderRadius: "1px",
+      };
+    case "outline":
+      return {
+        ...base,
+        border: `1px solid ${input.color}`,
+        borderRadius: input.kind === "tables" ? "2px" : "3px",
+        backgroundColor: "transparent",
+      };
+    case "handle":
+      return {
+        ...base,
+        border: `1px solid ${input.color}`,
+        backgroundColor: "color-mix(in srgb, var(--color-bg-canvas, #ffffff) 75%, transparent)",
+        boxShadow: `0 0 0 1px ${input.color}`,
+      };
+    case "rect":
+      return {
+        ...base,
+        backgroundColor:
+          input.kind === "search"
+            ? "color-mix(in srgb, var(--color-search-highlight, #facc15) 45%, transparent)"
+            : "color-mix(in srgb, var(--color-selection, #93c5fd) 35%, transparent)",
+        borderRadius: "2px",
+      };
+  }
+}
+
+function zIndexForKind(kind: SubstrateLaneKind): number {
+  switch (kind) {
+    case "caret":
+      return 12;
+    case "objects":
+      return 11;
+    case "selection":
+      return 5;
+    case "search":
+      return 4;
+    default:
+      return 7;
+  }
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+export default TwSubstrateOverlayLanes;

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

@@ -6,7 +6,10 @@ runtime API call, and `ChromePosture.debugMode` is production-forced to
 `"off"`.
 
 The supported local diagnostic surface is the mounted runtime REPL keyboard
-shortcut. These components remain in the tree for internal harness/story
+shortcut. Open it with `Cmd/Ctrl+Alt+P`; its `Agent layer view` shares the
+L01-L11 layer map with the harness debug pane, including `Alt+1`...`Alt+9`,
+`Alt+0`, and `Alt+-` navigation plus snippets that evaluate against
+`runtime`/`ref`. These components remain in the tree for internal harness/story
 experiments only; do not wire them into `WordReviewEditor` or public API paths.
 
 ## Files