@beyondwork/docx-react-component 1.0.95 → 1.0.97

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

@@ -14,7 +14,7 @@
 
 import * as React from "react";
 import type { OverlayCoordinateSpace } from "./chrome-overlay-projector";
-import type { ScopeRailPosture, ScopeRailSegment } from "../../api/public-types.ts";
+import type { ScopeRailSegment } from "../../api/public-types.ts";
 import type {
   EditorRole,
   EditorStoryTarget,
@@ -23,12 +23,10 @@ import type {
   WordReviewEditorLayoutFacet,
   WorkflowScopeMode,
 } from "../../api/public-types";
-import { TwScopeRailLayer } from "./tw-scope-rail-layer";
 import { TwScopeCardLayer } from "./tw-scope-card-layer";
 import { TwPageStackChromeLayer, type PmPortalView } from "../page-stack/tw-page-stack-chrome-layer";
 import { TwTableGripLayer } from "../chrome/tw-table-grip-layer";
 import { TwObjectSelectionOverlay } from "./tw-object-selection-overlay";
-import { useUiApi } from "../ui-api-context";
 
 export interface TwChromeOverlayProps {
   /** Layout facet the overlay layers read from (layout-semantic data). */
@@ -49,17 +47,13 @@ export interface TwChromeOverlayProps {
   space?: OverlayCoordinateSpace;
   /** Active scope id (for emphasis + rail tab sync). */
   activeScopeId?: string | null;
-  /** Posture filters shared with the Workflow rail. Omitted means all scopes render. */
-  visibleScopePostures?: ReadonlySet<ScopeRailPosture>;
   /**
-   * Click handler fired when the user clicks a scope rail stripe.
-   * P0 wires this to open the scope card (P1 ships the card layer).
+   * Deprecated no-op. Scope rails are no longer visible in the product
+   * overlay; scoped text itself is the visible affordance.
    */
   onScopeStripeClick?: (segment: ScopeRailSegment) => void;
   /**
-   * Legacy click handler kept for compatibility with consumers that
-   * subscribed before the stripe affordance existed.  Called alongside
-   * `onScopeStripeClick` on a stripe click.
+   * Deprecated no-op kept for prop compatibility with pre-inline-scope hosts.
    */
   onScopeSegmentClick?: (segment: ScopeRailSegment) => void;
   /**
@@ -185,6 +179,12 @@ export interface TwChromeOverlayProps {
    * See `useVisiblePageIndexRange` in `src/ui-tailwind/page-stack/use-visible-block-range.ts`.
    */
   visiblePageIndexRange?: { start: number; end: number } | null;
+  /**
+   * Visual-fidelity/chrome-less hosts still need page-stack measurement and
+   * story content, but they should not paint editor-only header/footer band
+   * tints over the captured document.
+   */
+  plainPageBands?: boolean;
   /** Preview catalog threaded into the page-stack chrome so header /
    *  footer / footnote / endnote regions render real <img>s. */
   mediaPreviews?: Record<string, import("../editor-surface/pm-state-from-snapshot").MediaPreviewDescriptor>;
@@ -215,7 +215,6 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   geometryFacet,
   space,
   activeScopeId,
-  visibleScopePostures,
   onScopeStripeClick,
   onScopeSegmentClick,
   onScopeCardClose,
@@ -242,28 +241,10 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   pmSurfaceElement,
   pmView,
   visiblePageIndexRange,
+  plainPageBands,
   mediaPreviews,
   activeBandRibbonProps,
 }) => {
-  const ui = useUiApi();
-  const scopeRailSegments = React.useMemo(
-    () =>
-      ui?.scope.rail().segments ??
-      workflowFacet?.getAllRailSegments() ??
-      [],
-    [ui, workflowFacet, renderFrameRevision],
-  );
-  const visibleScopeIds = React.useMemo(() => {
-    if (!visibleScopePostures) return undefined;
-    const ids = new Set<string>();
-    for (const segment of scopeRailSegments) {
-      if (visibleScopePostures.has(segment.posture)) {
-        ids.add(segment.scopeId);
-      }
-    }
-    return ids;
-  }, [scopeRailSegments, visibleScopePostures]);
-
   return (
     <div
       className="wre-chrome-overlay pointer-events-none absolute inset-0 z-30"
@@ -281,25 +262,15 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
           pmSurfaceElement={pmSurfaceElement}
           pmView={pmView}
           visiblePageIndexRange={visiblePageIndexRange ?? null}
+          plainPageBands={plainPageBands ?? false}
           mediaPreviews={mediaPreviews}
           activeBandRibbonProps={activeBandRibbonProps ?? null}
         />
       ) : null}
-      <TwScopeRailLayer
-        geometryFacet={geometryFacet}
-        workflowFacet={workflowFacet}
-        scopeRailSegments={scopeRailSegments}
-        space={space}
-        activeScopeId={activeScopeId}
-        visibleScopePostures={visibleScopePostures}
-        onStripeClick={onScopeStripeClick}
-        onSegmentClick={onScopeSegmentClick}
-      />
       <TwScopeCardLayer
         facet={facet}
         workflowFacet={workflowFacet}
         activeScopeId={activeScopeId ?? null}
-        visibleScopeIds={visibleScopeIds}
         onClose={onScopeCardClose ?? noop}
         onModeChange={onScopeCardModeChange ?? noopModeChange}
         onIssueAction={onScopeCardIssueAction ?? noopIssueAction}

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

@@ -3,8 +3,8 @@
  * layer resolves which card is visible from two inputs:
  *
  *   1. `activeScopeId` — the currently opened scope, set by the
- *      workspace when the user clicks a rail stripe.  Resets on
- *      click-outside / Escape / close button.
+ *      workspace or host workflow chrome. Resets on click-outside /
+ *      Escape / close button.
  *   2. internal `pinnedScopeId` — when the user clicks the pin button
  *      on a card, that scope persists across `activeScopeId` changes
  *      until explicitly unpinned or the scope disappears from the
@@ -53,8 +53,6 @@ export interface TwScopeCardLayerProps {
    */
   workflowFacet: WorkflowFacet | null;
   activeScopeId: string | null;
-  /** Scope ids currently visible under the Workflow rail layer filters. */
-  visibleScopeIds?: ReadonlySet<string>;
   onClose: () => void;
   onModeChange: (scopeId: string, mode: WorkflowScopeMode) => void;
   onIssueAction: (
@@ -94,7 +92,6 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   facet,
   workflowFacet,
   activeScopeId,
-  visibleScopeIds,
   onClose,
   onModeChange,
   onIssueAction,
@@ -131,11 +128,10 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   const getVisibleScopeCardModel = React.useCallback(
     (scopeId: string | null): ScopeCardModel | null => {
       if (!scopeId) return null;
-      if (visibleScopeIds && !visibleScopeIds.has(scopeId)) return null;
       if (ui) return ui.scope.card(scopeId);
       return getWorkflowScopeCardModel(scopeId);
     },
-    [getWorkflowScopeCardModel, ui, visibleScopeIds],
+    [getWorkflowScopeCardModel, ui],
   );
 
   // The effective scope is the pinned one if it still resolves to a

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

@@ -1,6 +1,6 @@
 /**
  * TwScopeCard — inline floating card shown above a scoped region when
- * the user activates the rail stripe.  Displays scope label + mode
+ * the user activates that scope.  Displays scope label + mode
  * selector + (when an `IssueMetadataValue` is attached via
  * `ScopeCardModel.issue`) the R2 issue severity, owner, title, and
  * resolve/waive/escalate actions.

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

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

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

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

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

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

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

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

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

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