@beyondwork/docx-react-component 1.0.96 → 1.0.97

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.96",
+  "version": "1.0.97",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/public-types.ts

@@ -81,6 +81,15 @@ export type { CanonicalDocumentEnvelope };
 export type * from "../model/chart-types.ts";
 export type { ResolvedTheme } from "../model/canonical-document.ts";
 
+/**
+ * Type-only re-export of the canonical `BlockNode` union.  Exposes the
+ * shape to presentation-layer consumers that need it for identity caching
+ * (refactor/11b Slice A) without forcing them to reach into
+ * `src/model/**` directly — which is flagged by the layer-11 boundary
+ * guard.  This is a TYPE-ONLY re-export: no runtime dependency is added.
+ */
+export type { BlockNode } from "../model/canonical-document.ts";
+
 /**
  * Workflow-rail types re-exported for the Layer-11 scope-rail + scope-
  * card overlays (refactor/11 Slice 6 retirement).  `WorkflowFacet` +
@@ -1198,6 +1207,8 @@ export interface SurfaceDrawingAnchor {
  * degree (OOXML `a:xfrm a:rot`).
  */
 export interface SurfacePictureEffects {
+  /** DrawingML a:lum brightness/contrast adjustments. Values are OOXML fixed percentages. */
+  lum?: { bright?: number; contrast?: number };
   srcRect?: { top: number; bottom: number; left: number; right: number };
   rotation?: number;
   flipH?: boolean;
@@ -1390,10 +1401,32 @@ export type SurfaceInlineSegment =
           };
       line?: { color?: string; widthEmu?: number; noLine?: boolean };
       isTextBox?: boolean;
+      /** Text box body layout from `wps:bodyPr` / `a:bodyPr`. */
+      textBoxBody?: SurfaceTextBoxBodyProperties;
       /** First-paragraph plain-text preview when `isTextBox` is true. */
       txbxText?: string;
+      /** Run-level marks from the first text-box text run, when available. */
+      txbxMarks?: SurfaceTextMark[];
+      /** Run-level visual attrs from the first text-box text run, when available. */
+      txbxMarkAttrs?: {
+        backgroundColor?: string;
+        charSpacing?: number;
+        kerning?: number;
+        textFill?: string;
+        fontFamily?: string;
+        fontSize?: number;
+        textColor?: string;
+      };
     };
 
+export interface SurfaceTextBoxBodyProperties {
+  anchor?: "t" | "ctr" | "b";
+  insetLeftEmu?: number;
+  insetTopEmu?: number;
+  insetRightEmu?: number;
+  insetBottomEmu?: number;
+}
+
 export interface SurfaceTableCellSnapshot {
   gridSpan: number;
   verticalMerge: "restart" | "continue" | null;
@@ -5758,27 +5791,8 @@ export interface WordReviewEditorProps {
    * unless this prop suppresses it).
    */
   commandPaletteDisabled?: boolean;
-  /**
-   * Phase Q runtime-embedded debug UX (refactor/11 Slice 7 + refactor/10
-   * Slice 5).  Default is `"off"` — the editor mounts no debug chrome
-   * and silently ignores the `ui.debug.attach()` hook.  Flip to
-   * `"top-bar"` to mount a slim status bar showing the active session
-   * + scope telemetry, or to `"full"` to mount the tabbed overlay with
-   * inspector / events / REPL panes.
-   *
-   * **CLAUDE.md Protected Invariant** — the default MUST be `"off"`.
-   * Predecessor debug-preview props (`showUnsupportedObjectPreviews`,
-   * `unsupportedPreviewsPolicy`) have regressed their safe defaults
-   * multiple times; keep this one strict.
-   */
-  debugMode?: DebugMode;
 }
 
-/**
- * Phase Q debug-UX visibility mode.  Consumed by
- * `WordReviewEditorProps.debugMode` + `src/ui-tailwind/debug/**`.
- */
-export type DebugMode = "off" | "top-bar" | "full";
 
 /**
  * Selection context handed to host-delegated shortcut callbacks

package/src/api/v3/ui/_types.ts

@@ -18,7 +18,8 @@
  *   U3 — selection + viewport are the only bidirectional channels.
  *   U4 — overlays derive anchors from geometry, never DOM.
  *   U5 — chrome posture composed once per read.
- *   U6 — debug attachment opt-in; gated by `debugMode` prop, default "off".
+ *   U6 — runtime debug attachment is production-disabled; local diagnostics
+ *        use the mounted keyboard shortcut.
  *   U7 — subscribers fire on runtime state changes + coalesced rAF.
  *   U8 — no access to internal controllers.
  */
@@ -147,14 +148,13 @@ export interface UiController {
   readonly getOverlayRects?: (query: OverlayAnchorQuery) => readonly GeometryRect[];
   /**
    * Host-provided chrome posture slice — the fields that live outside the
-   * runtime (host props like reviewMode / markupDisplay / debugMode /
-   * chromePreset). `ui.chrome.getPosture` composes this with the runtime's
+   * runtime (host props like reviewMode / markupDisplay / chromePreset).
+   * `ui.chrome.getPosture` composes this with the runtime's
    * guard snapshot + session/render state into the final ChromePosture.
    *
    * Default values when the hook is missing or returns undefined:
    *   reviewMode      — "observer"
    *   markupDisplay   — "final"
-   *   debugMode       — "off"  (gated per U6; default MUST remain "off")
    *   chromePreset    — undefined
    */
   readonly getHostPosture?: () => ChromeHostPosture | undefined;
@@ -172,14 +172,6 @@ export interface UiController {
   readonly subscribeChrome?: (
     listener: UiListener<ChromePosture>,
   ) => UiUnsubscribe;
-  /**
-   * Debug attachment. The bind-side wires the runtime's telemetry bus and
-   * projector to the mounted debug surface (Phase Q — see
-   * `src/ui-tailwind/debug/`). Returns a cleanup function. Omitting the
-   * hook causes `ui.debug.attach` to throw rather than silently ignoring
-   * the request.
-   */
-  readonly attachDebug?: (session: DebugSession) => () => void;
 }
 
 /**
@@ -317,6 +309,7 @@ export interface ChromePosture {
   readonly readOnly: boolean;
   readonly reviewMode: ChromeReviewMode;
   readonly markupDisplay: ChromeMarkupDisplay;
+  /** Always "off" in production; runtime debug chrome is not API-enabled. */
   readonly debugMode: ChromeDebugMode;
   readonly chromePreset?: string;
   readonly blockedReasons: readonly string[];
@@ -346,8 +339,6 @@ export interface ChromeSurface {
 export interface ChromeHostPosture {
   readonly reviewMode?: ChromeReviewMode;
   readonly markupDisplay?: ChromeMarkupDisplay;
-  /** MUST default to "off" at the caller level (U6); see CLAUDE.md Protected Invariants. */
-  readonly debugMode?: ChromeDebugMode;
   readonly chromePreset?: string;
 }
 
@@ -466,9 +457,8 @@ export interface ApiV3UiOverlays {
   /**
    * U9 · Composed overlay visibility. Merges the class-A policy from
    * `handle.getVisibilityPolicy(kind)` with the class-C local preference
-   * stored per UI API instance. `"debug-panel"` has an extra gate:
-   * local preference is ignored when `ChromePosture.debugMode === "off"`
-   * (CLAUDE.md Protected Invariant).
+   * stored per UI API instance. `"debug-panel"` is production-forced off;
+   * local preference and legacy host posture values cannot unlock it.
    */
   getVisibility(kind: OverlayKind): OverlayVisibility;
   /** Set the per-session local preference (class C). */
@@ -478,9 +468,9 @@ export interface ApiV3UiOverlays {
   /**
    * Subscribe to visibility changes for a specific `OverlayKind`. Fires
    * when the local preference for that kind changes (via
-   * `setLocalPreference` / `resetLocalPreference`). Policy changes and
-   * `debugMode` changes are not fanned out in this slice — consumers
-   * that need those should re-read on their own cadence. Returns an
+   * `setLocalPreference` / `resetLocalPreference`). Policy changes are
+   * also fanned out through the handle when the runtime exposes the policy
+   * subscription hook. Returns an
    * unsubscribe function.
    */
   subscribeVisibility(
@@ -493,7 +483,7 @@ export interface ApiV3UiChrome {
   /**
    * Runtime-sourced chrome posture (U5.a). Narrow slice — effectiveMode,
    * documentMode, readOnly, blocked reasons, plus the host-provided
-   * reviewMode / markupDisplay / debugMode / chromePreset.
+   * reviewMode / markupDisplay / chromePreset. debugMode is always "off".
    */
   getPosture(): ChromePosture;
   /**

package/src/api/v3/ui/chrome.ts

@@ -7,10 +7,10 @@
  *                          `handle.getInteractionGuardSnapshot()` and the
  *                          mode/readOnly from `handle.getRenderSnapshot()`;
  *                          overlays the host-provided slice (reviewMode,
- *                          markupDisplay, debugMode, chromePreset) via
+ *                          markupDisplay, chromePreset) via
  *                          `controller.getHostPosture()`. Host defaults
- *                          applied at this layer — debugMode defaults to
- *                          "off" per U6 + CLAUDE.md Protected Invariants.
+ *                          applied at this layer; debugMode is forced
+ *                          "off" in production.
  *   - getPinnedSurfaces  — live-with-adapter. Delegates to
  *                          `controller.getPinnedSurfaces()`; returns [] when
  *                          unbound or the hook is absent. The existing
@@ -59,7 +59,7 @@ export const getPostureMetadata: ApiV3FnMetadata = {
   stateClass: "C-local",
   persistsTo: "none",
   rwdReference:
-    "§UI API § ui.chrome.getPosture. Composes handle.getInteractionGuardSnapshot() + handle.getRenderSnapshot() with controller.getHostPosture() at a single site. debugMode defaults 'off' per U6.",
+    "§UI API § ui.chrome.getPosture. Composes handle.getInteractionGuardSnapshot() + handle.getRenderSnapshot() with controller.getHostPosture() at a single site. debugMode is production-forced 'off'.",
 };
 
 export const getCompositionMetadata: ApiV3FnMetadata = {
@@ -103,7 +103,7 @@ export const subscribeMetadata: ApiV3FnMetadata = {
     commit: "refactor-07-slice-2",
   },
   // Stream-form bidirectional channel (U5 + U7). Posture changes
-  // (guard-snapshot updates, host posture flips like debugMode toggle)
+  // (guard-snapshot updates, host posture flips like reviewMode)
   // fan out through this listener. Coalescing is microtask — posture
   // composes at most once per render tick, no rAF batching needed.
   uxIntent: {
@@ -328,13 +328,12 @@ export function createChromeFamily(ctx: UiApiContext) {
         : "edit";
       const readOnly = render?.readOnly === true;
 
-      // Host-provided slice — reviewMode / markupDisplay / debugMode /
-      // chromePreset. Defaults applied here; U6 — debugMode MUST default
-      // to "off" (CLAUDE.md Protected Invariants).
+      // Host-provided slice — reviewMode / markupDisplay / chromePreset.
+      // Runtime debug chrome is not host-controllable in production.
       const host = ctx.binding?.controller.getHostPosture?.() ?? undefined;
       const reviewMode = host?.reviewMode ?? "observer";
       const markupDisplay = host?.markupDisplay ?? "final";
-      const debugMode = host?.debugMode ?? "off";
+      const debugMode = "off";
       const chromePreset = host?.chromePreset;
 
       return {

package/src/api/v3/ui/debug.ts

@@ -1,28 +1,14 @@
 /**
  * @endStateApi v3 — `ui.debug` family (layer 10).
  *
- * Slice 5 wiring:
- *   - attach  — live-with-adapter. Delegates to the bound controller's
- *               `attachDebug` hook, which on the bind-side wires
- *               `runtime.debug.bus` + `runtime.debug.getSnapshot` to the
- *               mounted debug surface. Returns a DebugAttachment whose
- *               `detach` invokes the controller-provided cleanup and
- *               clears the UI API's attachment record.
- *   - detach  — live-with-adapter. Ends the current attachment (if any)
- *               by invoking its controller-provided cleanup. Idempotent
- *               — calling detach without an attachment is a no-op.
+ * Production hardening:
+ *   - attach  — intentionally disabled. Runtime debug chrome is no longer
+ *               activatable through the public UI API.
+ *   - detach  — retained as an idempotent no-op for callers that defensively
+ *               clean up a previously attempted attachment.
  *
- * Phase Q (runtime-embedded debug UX at `src/ui-tailwind/debug/**`) is the
- * presentation consumer of this surface. Per refactor plan 10 risk register
- * #3 and §9 finishing-development-branch discipline, Slice 5 ships the
- * substrate; the Phase Q React components + `debugMode` public prop +
- * `test/ui/debug-mode-visibility-invariant.test.ts` land in a follow-up.
- * `src/ui-tailwind/debug/README.md` documents the reserved scope.
- *
- * Contract U6 — debug attachment is opt-in and scoped. Default state:
- * no debug UX. The `debugMode` prop gate (to-be-added) defaults to
- * `"off"`. CLAUDE.md Protected Invariants flag this has regressed
- * multiple times.
+ * The only supported local diagnostic surface in the mounted editor is the
+ * runtime REPL keyboard shortcut.
  */
 
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
@@ -42,7 +28,7 @@ export const attachMetadata: ApiV3FnMetadata = {
   stateClass: "C-local",
   persistsTo: "none",
   rwdReference:
-    "§UI API § ui.debug.attach. Adapter delegates to UiController.attachDebug which on the bind-side wires runtime.debug.bus + getSnapshot to the mounted debug surface. Throws when no controller is bound or the hook is absent.",
+    "§UI API § ui.debug.attach. Production-disabled hard stop: always throws and never routes to a controller hook. Use the mounted runtime REPL keyboard shortcut for local diagnostics.",
 };
 
 export const detachMetadata: ApiV3FnMetadata = {
@@ -58,67 +44,19 @@ export const detachMetadata: ApiV3FnMetadata = {
   stateClass: "C-local",
   persistsTo: "none",
   rwdReference:
-    "§UI API § ui.debug.detach. Idempotent — invokes the controller-provided cleanup from the active attachment (if any) and clears the record.",
+    "§UI API § ui.debug.detach. Production-disabled companion no-op retained for defensive cleanup compatibility.",
 };
 
-interface DebugAttachmentState {
-  session: DebugSession;
-  cleanup: () => void;
-}
-
-export function createDebugFamily(ctx: UiApiContext) {
-  // Per-instance attachment state. One UI API holds at most one active
-  // debug attachment; re-attaching tears down the prior attachment first.
-  let current: DebugAttachmentState | null = null;
-
-  function detachInternal(): void {
-    if (current) {
-      try {
-        current.cleanup();
-      } finally {
-        current = null;
-      }
-    }
-  }
+const DEBUG_ATTACH_DISABLED_MESSAGE =
+  "ui.debug.attach is disabled in production; use the runtime REPL keyboard shortcut instead.";
 
+export function createDebugFamily(_ctx: UiApiContext) {
   return {
-    attach(session: DebugSession): DebugAttachment {
-      const controller = ctx.binding?.controller;
-      if (!controller) {
-        throw new Error(
-          "ui.debug.attach: no controller bound — call ui.session.bind(controller) first",
-        );
-      }
-      if (!controller.attachDebug) {
-        throw new Error(
-          `ui.debug.attach: controller of kind "${controller.kind}" did not provide an attachDebug hook`,
-        );
-      }
-      // Tear down any prior attachment so re-attaching does not leak
-      // subscriptions or telemetry-bus listeners.
-      detachInternal();
-      const cleanup = controller.attachDebug(session);
-      current = { session, cleanup };
-      // NOTE: `DebugAttachment.detach` is aliased to `detachInternal`,
-      // which detaches **whatever is currently attached** — not
-      // specifically the session this attachment was created with. At
-      // most one attachment is live per UI API instance, so this is
-      // semantically correct under the "single attachment at a time"
-      // model. Callers that hold onto an older `attachment` ref and
-      // call its `.detach()` after a re-attach will tear down the
-      // NEWER attachment. Typical hosts create + detach in lockstep
-      // (attach on mount, detach on unmount), so this is fine; the
-      // debug service's RPC driver re-attaches on every session, which
-      // matches this model.
-      return {
-        session,
-        detach: detachInternal,
-      };
+    attach(_session: DebugSession): DebugAttachment {
+      throw new Error(DEBUG_ATTACH_DISABLED_MESSAGE);
     },
     detach(): void {
-      // Idempotent — no-op when nothing is attached. See U6; the default
-      // state is "no debug UX", so repeated detach calls must stay safe.
-      detachInternal();
+      // Idempotent compatibility no-op.
     },
   };
 }

package/src/api/v3/ui/overlays-visibility.ts

@@ -20,8 +20,8 @@
  *   policy = handle.getVisibilityPolicy(kind)        // may be null
  *   pref   = localPrefs.get(kind)                    // may be undefined
  *
- *   # debug-panel special case: debugMode gate wins over everything.
- *   if kind === "debug-panel" and debugMode === "off":
+ *   # debug-panel special case: production debug gate wins over everything.
+ *   if kind === "debug-panel":
  *     → { state: "forced-off", reason: "policy-enforcement" }
  *
  *   # Policy enforcement is a hard override.
@@ -39,7 +39,7 @@
  *   → defaultOn ? visible : hidden, reason: "policy-default"
  *
  * Subscribe fan-out is local-preference-only in this slice. Policy
- * changes and debugMode changes do not wake listeners yet — consumers
+ * changes do not wake listeners yet — consumers
  * that depend on either re-read visibility on their own cadence.
  * Follow-up slice will subscribe to the L06 policy telemetry bus and
  * fan out on `workflow.visibility_policy_changed`.
@@ -85,13 +85,12 @@ export function createOverlaysVisibilityState(): OverlaysVisibilityState {
 }
 
 /**
- * Read the current effective debugMode from the bound controller's host
- * posture slice. Mirrors the default handling in `chrome.ts::getPosture`
- * — unbound / no hook / no debugMode field all resolve to `"off"` per
- * U6 + CLAUDE.md Protected Invariants.
+ * Runtime debug chrome is production-disabled. Legacy host posture values
+ * must not unlock the debug panel.
  */
 function readDebugMode(ctx: UiApiContext): "off" | "top-bar" | "full" {
-  return ctx.binding?.controller.getHostPosture?.()?.debugMode ?? "off";
+  void ctx;
+  return "off";
 }
 
 function readPolicy(
@@ -115,8 +114,8 @@ export function composeOverlayVisibility(
   state: OverlaysVisibilityState,
   kind: OverlayKind,
 ): OverlayVisibility {
-  // debug-panel: when debugMode is "off" the panel is forced off
-  // regardless of policy or preference (CLAUDE.md Protected Invariant).
+  // debug-panel: runtime debug chrome is forced off in production
+  // regardless of policy, preference, or legacy host posture.
   if (kind === "debug-panel" && readDebugMode(ctx) === "off") {
     return { state: "forced-off", reason: "policy-enforcement" };
   }

package/src/api/v3/ui/overlays.ts

@@ -39,7 +39,6 @@
 
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import type {
-  ChromePosture,
   GeometryRect,
   OverlayAnchorQuery,
   OverlayVisibility,
@@ -210,7 +209,7 @@ export const getVisibilityMetadata: ApiV3FnMetadata = {
   agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-overlays-read" },
   stateClass: "C-local",
   persistsTo: "none",
-  rwdReference: "§UI API § ui.overlays.getVisibility (U9). Single composition site merging class-A policy (handle.getVisibilityPolicy) with class-C local preference. debug-panel is additionally gated on ChromePosture.debugMode per CLAUDE.md Protected Invariant.",
+  rwdReference: "§UI API § ui.overlays.getVisibility (U9). Single composition site merging class-A policy (handle.getVisibilityPolicy) with class-C local preference. debug-panel is production-forced off.",
 };
 
 export const setLocalPreferenceMetadata: ApiV3FnMetadata = {
@@ -273,7 +272,7 @@ export const subscribeVisibilityMetadata: ApiV3FnMetadata = {
     payloadType: "OverlayVisibility",
     coalescing: "microtask",
   },
-  rwdReference: "§UI API § ui.overlays.subscribeVisibility (U9). Fires on THREE channels: (a) local-preference mutation, (b) class-A policy-change (chained to L06's `handle.subscribeVisibilityPolicy`, shipped 2026-04-22), (c) `ChromePosture.debugMode` transitions on the `debug-panel` kind (chained to the bound controller's `subscribeChrome`, shipped 2026-04-24 closing KI-007). Chrome fan-out is lazy — registered on the first `debug-panel` subscriber, torn down on the last. debugMode-comparison-based firing avoids false fan-out on unrelated chrome ticks (reviewMode, markupDisplay).",
+  rwdReference: "§UI API § ui.overlays.subscribeVisibility (U9). Fires on local-preference mutation and class-A policy-change (chained to L06's `handle.subscribeVisibilityPolicy`, shipped 2026-04-22). debug-panel remains production-forced off and does not subscribe to chrome debugMode changes.",
 };
 
 export function createOverlaysFamily(ctx: UiApiContext) {
@@ -313,59 +312,13 @@ export function createOverlaysFamily(ctx: UiApiContext) {
     }
   });
 
-  // KI-007 close — chrome-change fan-out for `debug-panel` visibility.
-  //
-  // The composed `debug-panel` visibility depends on three inputs:
-  // (a) class-A policy, (b) class-C local preference, and (c)
-  // ChromePosture.debugMode. Fan-out for (a) + (b) was already wired;
-  // (c) was the missing channel. Now registered lazily on the first
-  // `subscribeVisibility("debug-panel", …)` call and torn down when the
-  // last such subscriber unsubscribes, so the chrome-listener cost only
-  // applies when someone is actually listening.
-  //
-  // Comparison-based firing: we compare `ChromePosture.debugMode` to
-  // the previous value on each chrome tick and only re-notify when it
-  // changes. This avoids firing debug-panel visibility subscribers on
-  // unrelated chrome changes (reviewMode flip, markup-display change,
-  // etc.) — cost-efficient + semantically correct.
-  //
-  // Note on re-bind: if the host calls `ui.session.release()` then
-  // `bind(newController)`, the chrome-listener's underlying hook is
-  // torn down with the old controller. Consumers already subscribed to
-  // debug-panel visibility continue holding their listeners but stop
-  // receiving chrome-tick fan-out until they unsubscribe and re-
-  // subscribe. Release+rebind is a lifecycle event hosts handle
-  // explicitly; documented here rather than auto-re-registering
-  // because a full bind-cycle integration would also require reading
-  // the initial posture to seed `lastKnownDebugMode`, which is out of
-  // scope for this targeted fix.
-  let chromeUnsubscribe: (() => void) | null = null;
-  let lastKnownDebugMode: ChromePosture["debugMode"] | undefined;
-
   function ensureChromeFanout(): void {
-    if (chromeUnsubscribe) return;
-    const controller = ctx.binding?.controller;
-    if (!controller?.subscribeChrome) return;
-    // Seed last-known from the current posture so the first real change
-    // doesn't false-fire against undefined.
-    const posture = readPostureForDebugModeSeed(ctx);
-    lastKnownDebugMode = posture?.debugMode;
-    chromeUnsubscribe = controller.subscribeChrome((next) => {
-      const nextMode = next?.debugMode;
-      if (nextMode === lastKnownDebugMode) return;
-      lastKnownDebugMode = nextMode;
-      notifyVisibilitySubscribers(ctx, visibilityState, "debug-panel");
-    });
+    // Runtime debug chrome is production-disabled, so debug-panel
+    // visibility is constant forced-off and never depends on chrome ticks.
   }
 
   function releaseChromeFanoutIfEmpty(): void {
-    const debugPanelSubs = visibilityState.subscribers.get("debug-panel");
-    if (debugPanelSubs && debugPanelSubs.size > 0) return;
-    if (chromeUnsubscribe) {
-      chromeUnsubscribe();
-      chromeUnsubscribe = null;
-      lastKnownDebugMode = undefined;
-    }
+    // Paired no-op for the disabled debug-panel chrome fan-out.
   }
 
   // KI-006 close — per-query coalesced subscribe channel.
@@ -653,9 +606,8 @@ export function createOverlaysFamily(ctx: UiApiContext) {
         visibilityState.subscribers.set(kind, listeners);
       }
       listeners.add(listener);
-      // KI-007 — lazy-register the chrome-change fan-out when the first
-      // debug-panel subscriber lands. No-op for other kinds + idempotent
-      // when a chrome listener is already active.
+      // Runtime debug chrome is production-disabled; this remains a no-op
+      // for debug-panel subscribers and other kinds.
       if (kind === "debug-panel") {
         ensureChromeFanout();
       }
@@ -672,8 +624,7 @@ export function createOverlaysFamily(ctx: UiApiContext) {
         if (!current) return;
         current.delete(listener);
         if (current.size === 0) visibilityState.subscribers.delete(kind);
-        // KI-007 — tear down the chrome-change fan-out when the last
-        // debug-panel subscriber unsubscribes.
+        // Paired no-op for the disabled debug-panel chrome fan-out.
         if (kind === "debug-panel") {
           releaseChromeFanoutIfEmpty();
         }
@@ -681,21 +632,3 @@ export function createOverlaysFamily(ctx: UiApiContext) {
     },
   };
 }
-
-/**
- * KI-007 helper — read the current `ChromePosture.debugMode` value so
- * the chrome-change fan-out can seed its `lastKnownDebugMode` tracker
- * without false-firing on the first tick. Mirrors the logic in
- * `chrome.ts::getPosture` but only extracts `debugMode` + returns
- * `undefined` on any missing piece (rather than composing a full
- * posture). Keeps the debug-panel fan-out path cheap.
- */
-function readPostureForDebugModeSeed(
-  ctx: UiApiContext,
-): { debugMode: ChromePosture["debugMode"] } | null {
-  const hook = ctx.binding?.controller.getHostPosture;
-  if (!hook) return null;
-  const host = hook();
-  if (!host) return null;
-  return { debugMode: host.debugMode ?? "off" };
-}

package/src/io/ooxml/parse-main-document.ts

@@ -2749,6 +2749,36 @@ function parseRun(
         );
         break;
       }
+      case "AlternateContent": {
+        const altXml = sourceXml.slice(child.start, child.end);
+        try {
+          const frame = parseDrawingFrame(altXml, {
+            relationships,
+            mediaParts,
+            sourcePartPath,
+            chartPartLookup: activeChartPartLookup,
+            blockParser: (xml) =>
+              parseBlockStreamFromXml(xml, {
+                relationships,
+                mediaParts,
+                sourcePartPath,
+                depth: activeTxbxBlockStreamDepth + 1,
+              }) as unknown as ReadonlyArray<{ type: string; [key: string]: unknown }>,
+          });
+          if (frame) {
+            result.push(frame);
+            break;
+          }
+        } catch {
+          // Fall through to opaque preservation below.
+        }
+        encounteredUnsupportedChild = true;
+        result.push({
+          type: "opaque_inline",
+          rawXml: altXml,
+        });
+        break;
+      }
       case "pict": {
         const pictXml = sourceXml.slice(child.start, child.end);
         try {

package/src/io/ooxml/parse-picture.ts

@@ -49,6 +49,13 @@ export function parsePicture(graphicDataEl: XmlElementNode): PictureContent | nu
   const blipRef = blipEmbed ?? blipLink ?? "";
   if (!blipRef) return null;
   const isLinked = !blipEmbed && !!blipLink;
+  const lumEl = findFirstChild(blip, "lum");
+  const lum = lumEl
+    ? {
+        bright: readIntAttr(lumEl, "bright"),
+        contrast: readIntAttr(lumEl, "contrast"),
+      }
+    : undefined;
 
   // srcRect (percentage crop: 0..100000 = 0..100%)
   const srcRectEl = findFirstChild(blipFill, "srcRect");
@@ -95,6 +102,9 @@ export function parsePicture(graphicDataEl: XmlElementNode): PictureContent | nu
 
   const result: PictureContent = { type: "picture", blipRef };
   if (isLinked) result.isLinked = true;
+  if (lum && (lum.bright !== undefined || lum.contrast !== undefined)) {
+    result.lum = lum;
+  }
   if (srcRect) result.srcRect = srcRect;
   if (stretch !== undefined) result.stretch = stretch;
   if (tile !== undefined) result.tile = tile;
@@ -109,6 +119,10 @@ export function parsePicture(graphicDataEl: XmlElementNode): PictureContent | nu
 }
 
 function readEmuAttr(el: XmlElementNode, name: string): number | undefined {
+  return readIntAttr(el, name);
+}
+
+function readIntAttr(el: XmlElementNode, name: string): number | undefined {
   const v = el.attributes[name];
   if (v === undefined) return undefined;
   const n = parseInt(v, 10);