@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/debug/types.ts

@@ -0,0 +1,275 @@
+// @internal — Runtime debug projector types.
+//
+// These types are the JSON contract the React dev-drawer and the agentic
+// debug service (`services/debug/`) both consume. They compose already-shipped
+// public types — nothing here is a new schema invented for the projector
+// except the scope-discrimination fields on `ScopeDebugEntry`, which expose
+// information the runtime already tracks (`markerBackedScopeIds`,
+// `normalizeWorkflowOverlayForDocument` detach reasons) but has never
+// surfaced in typed form.
+//
+// Priority ordering follows user intent 2026-04-20:
+//   1. OOXML audit + scope debugging (top-priority signal)
+//   2. Rendering (secondary)
+
+import type {
+  CompatibilityReport,
+  DocumentLocationSnapshot,
+  EditorAnchorProjection,
+  EditorStoryTarget,
+  EditorWarning,
+  InteractionGuardSnapshot,
+  RuntimeContextAnalyticsSnapshot,
+  ScopeQueryResult,
+  ScopeVisibility,
+  WorkflowBlockedCommandReason,
+  WorkflowOverlay,
+  WorkflowScope,
+  WorkflowScopeMode,
+} from "../../api/public-types.ts";
+import type { FormattingDebugEntry } from "../formatting/projector.ts";
+import type { GeometryDebugEntry } from "../geometry/projector.ts";
+import type { LayoutDebugEntry } from "../layout/projector.ts";
+
+/* -------------------------------------------------------------------------- */
+/*  Query + channel discriminants                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Telemetry channels the runtime can emit on. All channels are off by default;
+ * consumers of the Phase 1 `TelemetryBus` turn them on per session. Zero cost
+ * when disabled — the bus bitmap-checks before allocating the event object.
+ *
+ * Per-channel emission status (as of F-1 wiring, 2026-04-20):
+ *   - `api` / `parse` / `serialize` / `io` — active, emit on every trigger.
+ *   - `scope` / `warning` / `selection`  — wired; emit only on triggering ops.
+ *   - `render` / `command` / `commit` / `collab` / `layout` — RESERVED. The
+ *     channel bits exist so `setChannels` calls stay API-stable, but no
+ *     emission sites exist in `src/` yet. Phase C of the doc-debug build plan
+ *     adds them. Subscribing to one of these today produces zero signal —
+ *     this is documented, not a bug. See
+ *     `services/debug/docs/substrate-code-review-2026-04-20.md` §F-2.
+ */
+export type TelemetryChannel =
+  | "api"        // every public-ref-method invocation (wraps useImperativeHandle)
+  | "parse"      // OOXML import dispatch per element
+  | "serialize"  // OOXML export dispatch per element
+  | "render"     // RESERVED (Phase C): PM projection entry
+  | "command"    // RESERVED (Phase C): internal command dispatch (src/core/commands/**)
+  | "scope"      // scope lifecycle (attach/detach/invalidate)
+  | "warning"    // warnings emitted
+  | "selection"  // selection commits
+  | "commit"     // RESERVED (Phase C): the single commit entry point in the runtime
+  | "collab"     // RESERVED (Phase C): remote-replay + mismatch events
+  | "layout"     // RESERVED (Phase C): coarse layout-facet recompute boundary
+  | "io"         // docx-session load/export
+  | "formatting"; // layer-03 cascade + theme + numbering + field resolution
+
+export interface DebugInspectorQuery {
+  /** Include the `textProjection` section. Expensive; default `false`. */
+  readonly includeTextProjection?: boolean;
+  /** Include a tail of recent telemetry events (Phase 1+ only). Default `false`. */
+  readonly includeEvents?: boolean;
+  /** Maximum events returned when `includeEvents` is true. Default 64. */
+  readonly maxEvents?: number;
+  /** Filter scopes before projecting `ScopeDebugEntry[]`. */
+  readonly scopeFilter?: {
+    readonly scopeIds?: readonly string[];
+    readonly modes?: readonly WorkflowScopeMode[];
+    readonly source?: ScopeDebugSource | readonly ScopeDebugSource[];
+    readonly onlyDetached?: boolean;
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Scope debug — the top-priority section                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The architectural fault line the plan must surface explicitly.
+ *
+ *   - `marker-backed`  — scope id is present in `collectScopeLocations(doc)`
+ *                        AND in the overlay. Anchor can be derived from
+ *                        marker positions; structural edits auto-update it.
+ *   - `overlay-only`   — scope id is in the overlay but not in the document's
+ *                        `collectScopeLocations` set. Anchor is static (from
+ *                        overlay JSON) and can drift across edits.
+ *   - `detached`       — scope id was marker-backed but its markers were
+ *                        removed by a structural edit; anchor is now a
+ *                        `detached` projection with `lastKnownRange`.
+ */
+export type ScopeDebugSource = "marker-backed" | "overlay-only" | "detached";
+
+/** Whether both marker nodes are present, only one, or neither. */
+export type ScopeMarkerState = "complete" | "start-only" | "end-only" | "missing";
+
+export interface ScopeDebugEntry {
+  readonly scopeId: string;
+  readonly label?: string;
+  readonly mode: WorkflowScopeMode;
+  readonly visibility: ScopeVisibility;
+  readonly storyTarget: EditorStoryTarget;
+  readonly source: ScopeDebugSource;
+  readonly liveAnchor: EditorAnchorProjection;
+  readonly storedOverlayAnchor: EditorAnchorProjection | null;
+  readonly trusted: boolean;
+  readonly markerState: ScopeMarkerState;
+  readonly detachedReason?:
+    | "deleted"
+    | "invalidatedByStructureChange"
+    | "importAmbiguity";
+  readonly warningId?: string;
+  readonly lastKnownRange?: { readonly from: number; readonly to: number };
+  readonly location: DocumentLocationSnapshot | null;
+  /**
+   * F-15: all metadata entries from the scope's overlay record, not just the
+   * first. One object per `overlayScope.metadata[i]` whose shape carries any
+   * of `key` / `storageRef` / `metadataVersion`. Absent when the scope has no
+   * `metadataRefs` / `metadata` attached.
+   */
+  readonly metadataLookups?: readonly {
+    readonly metadataId?: string;
+    readonly storageRef?: string;
+    readonly metadataVersion?: number;
+  }[];
+  readonly excerpt?: {
+    readonly before: string;
+    readonly inside: string;
+    readonly after: string;
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Projector bundle                                                          */
+/* -------------------------------------------------------------------------- */
+
+export interface DebugInspectorSessionSection {
+  readonly documentId: string;
+  readonly sessionId: string;
+  readonly dirty: boolean;
+  readonly exportBlocked: boolean;
+  readonly activeStory: EditorStoryTarget;
+  readonly workspaceMode: "canvas" | "page";
+  readonly viewMode: string;
+  readonly documentMode: string;
+  readonly measurementFidelity: string | null;
+  readonly currentPage: number | null;
+}
+
+export interface DebugInspectorHealthSection {
+  readonly compatibility: CompatibilityReport;
+  readonly warnings: readonly EditorWarning[];
+  readonly blockedReasons: readonly WorkflowBlockedCommandReason[];
+  readonly fatalError: { readonly code: string; readonly message: string } | null;
+  readonly readOnly: boolean;
+}
+
+export interface DebugInspectorSelectionSection {
+  readonly anchor: EditorAnchorProjection | null;
+  readonly location: DocumentLocationSnapshot | null;
+}
+
+export interface DebugInspectorWorkflowSection {
+  readonly overlay: WorkflowOverlay | null;
+  readonly activeWorkItemId: string | null;
+  readonly metadataPersistenceMode: string | null;
+  readonly candidateCount: number;
+  readonly scopeCount: number;
+  readonly markerBackedCount: number;
+  readonly overlayOnlyCount: number;
+  readonly detachedCount: number;
+  /**
+   * Layer-06 Slice 3 — richer projector (`WorkflowDebugEntry`) populated
+   * when `scope` or `warning` telemetry channels are on. Carries guard
+   * snapshot, tamper-gate state, AI-policy stats, and metadata counts in
+   * one object so the debug inspector does not need a separate second
+   * pass. Absent when neither channel is active.
+   */
+  readonly debugEntry?: import("../workflow/projector.ts").WorkflowDebugEntry;
+}
+
+export interface DebugInspectorReviewSection {
+  readonly unresolvedCommentCount: number;
+  readonly pendingRevisionCount: number;
+  readonly detachedCommentCount: number;
+  readonly detachedRevisionCount: number;
+}
+
+export interface DebugInspectorLayoutSection {
+  readonly pageCount: number | null;
+  readonly sectionCount: number | null;
+  readonly storyCount: number;
+}
+
+/**
+ * One telemetry event. Produced by hook-points throughout the runtime and
+ * pushed through `TelemetryBus` into per-channel ring buffers.
+ *
+ * `type` is a dotted identifier — e.g. `"parse.w:p.accepted"`,
+ * `"ref.addComment"`, `"scope.detached"`. The channel + type pair is the
+ * stable join key; `payload` is channel-specific and MAY change across
+ * versions.
+ *
+ * `seq` is bus-assigned; callers must not set it. `t` is filled by the bus
+ * if absent.
+ */
+export interface RuntimeTelemetryEvent {
+  readonly channel: TelemetryChannel;
+  readonly type: string;
+  readonly t: number;
+  readonly payload?: unknown;
+  readonly seq?: number;
+}
+
+export interface DebugInspectorSnapshot {
+  readonly schemaVersion: 1;
+  readonly generatedAtUtc: string;
+  readonly session: DebugInspectorSessionSection;
+  readonly health: DebugInspectorHealthSection;
+  readonly context: RuntimeContextAnalyticsSnapshot | null;
+  readonly selection: DebugInspectorSelectionSection;
+  readonly workflow: DebugInspectorWorkflowSection;
+  readonly scopes: readonly ScopeDebugEntry[];
+  readonly review: DebugInspectorReviewSection;
+  readonly layout: DebugInspectorLayoutSection;
+  readonly events?: readonly RuntimeTelemetryEvent[];
+  readonly textProjection?: unknown;
+  readonly partialFallbacks?: readonly string[];
+  readonly channels?: Record<TelemetryChannel, boolean>;
+  /**
+   * Layer 03 formatting-resolution summary. Populated when the
+   * `formatting` telemetry channel is enabled on the bus; absent
+   * otherwise. Produced by
+   * `src/runtime/formatting/projector.ts::buildFormattingDebugEntry`.
+   */
+  readonly formatting?: FormattingDebugEntry;
+  /**
+   * Layer 05 geometry-projection summary. Populated when the `layout`
+   * telemetry channel is enabled on the bus; absent otherwise.
+   * Produced by
+   * `src/runtime/geometry/projector.ts::buildGeometryDebugEntry`.
+   */
+  readonly geometry?: GeometryDebugEntry;
+  /**
+   * Layer 04 layout summary. Populated when the `layout` telemetry
+   * channel is enabled on the bus; absent otherwise. Produced by
+   * `src/runtime/layout/projector.ts::buildLayoutDebugEntry`.
+   * Complements `geometry?` — `geometry` describes the projected frame
+   * state (rects, caret, viewport); `layoutDebug` describes the
+   * pagination state (page count, sections, measurement fidelity,
+   * dirty-field families, engine version). Refactor/04 Slice 3.
+   */
+  readonly layoutDebug?: LayoutDebugEntry;
+}
+
+export interface ScopeDebugProjectionInputs {
+  readonly scopeQueryResult: ScopeQueryResult;
+  readonly overlayScope: WorkflowScope | null;
+  readonly markerBackedScopeIds: ReadonlySet<string>;
+  readonly markerPresence: {
+    readonly hasStart: boolean;
+    readonly hasEnd: boolean;
+  };
+  readonly location: DocumentLocationSnapshot | null;
+  readonly relatedWarning: EditorWarning | null;
+}

package/src/runtime/debug/wrap-ref-for-telemetry.ts

@@ -0,0 +1,118 @@
+// @internal — Wrap the public ref with a Proxy that emits `api`-channel
+// telemetry events on every method invocation, when the channel is on.
+//
+// Zero cost when the `api` channel is off:
+//   - The Proxy `get` trap still runs, but all it does is return the bound
+//     method OR the wrapped version. Method wrapping is memoized on a
+//     per-property WeakMap so we don't allocate a new closure per access.
+//   - The wrapped closure's first action is `bus.isEnabled("api")`. If off,
+//     it straight-calls the target and returns — one bitmask AND + one call.
+//
+// Used by `src/ui/WordReviewEditor.tsx` around the ref value returned from
+// `useImperativeHandle`. Not used inside `buildRefProjections` because all
+// facet methods ultimately dispatch through the ref, so a single wrap at
+// the top-level ref is enough to see every agent invocation.
+
+import type { TelemetryBus } from "./telemetry-bus.ts";
+
+/**
+ * Wrap any ref-like object. Only function properties are traced; getters /
+ * non-function values pass through untouched. A single shared cache ensures
+ * the Proxy returns stable function references per method name.
+ */
+export function wrapRefForTelemetry<T extends object>(ref: T, bus: TelemetryBus): T {
+  const cache = new Map<string | symbol, unknown>();
+  return new Proxy(ref, {
+    get(target, property) {
+      const original = Reflect.get(target, property, target);
+      if (typeof original !== "function") return original;
+      const cached = cache.get(property);
+      if (cached) return cached;
+      const methodName = typeof property === "symbol" ? property.description ?? "symbol" : property;
+      const wrapped = createTracedMethod(bus, target, methodName as string, original as Function);
+      cache.set(property, wrapped);
+      return wrapped;
+    },
+  }) as T;
+}
+
+function createTracedMethod(
+  bus: TelemetryBus,
+  thisArg: unknown,
+  methodName: string,
+  fn: Function,
+): Function {
+  return function tracedMethod(this: unknown, ...args: unknown[]) {
+    if (!bus.isEnabled("api")) {
+      return fn.apply(thisArg, args);
+    }
+    const start = now();
+    let ok = true;
+    let err: unknown;
+    let isAsync = false;
+    try {
+      const result = fn.apply(thisArg, args);
+      if (result != null && typeof (result as { then?: unknown }).then === "function") {
+        isAsync = true;
+        return (result as PromiseLike<unknown>).then(
+          (value) => {
+            emitApiEvent(bus, methodName, args, start, true, undefined, true);
+            return value;
+          },
+          (failure) => {
+            emitApiEvent(bus, methodName, args, start, false, failure, true);
+            throw failure;
+          },
+        );
+      }
+      return result;
+    } catch (caught) {
+      ok = false;
+      err = caught;
+      throw caught;
+    } finally {
+      if (!isAsync) {
+        emitApiEvent(bus, methodName, args, start, ok, err, false);
+      }
+    }
+  };
+}
+
+function emitApiEvent(
+  bus: TelemetryBus,
+  methodName: string,
+  args: unknown[],
+  start: number,
+  ok: boolean,
+  error: unknown,
+  async_: boolean,
+): void {
+  bus.emit({
+    channel: "api",
+    type: `ref.${methodName}`,
+    t: now(),
+    payload: {
+      ok,
+      ms: now() - start,
+      argc: args.length,
+      async: async_,
+      ...(ok ? {} : { error: stringifyError(error) }),
+    },
+  });
+}
+
+function now(): number {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+
+function stringifyError(err: unknown): string {
+  if (err instanceof Error) return `${err.name}: ${err.message}`;
+  try {
+    return String(err);
+  } catch {
+    return "<unstringifiable>";
+  }
+}

package/src/runtime/document-layout.ts

@@ -14,6 +14,7 @@ import type {
   SectionProperties,
   SubPartsCatalog,
 } from "../model/canonical-document.ts";
+import type { ResolvedDocumentSection } from "../model/layout/resolved-layout-types.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
 import { resolveDefaultPageSizeTwips } from "./layout/default-page-format.ts";
 import {
@@ -22,12 +23,13 @@ import {
 } from "./story-context.ts";
 import { storyTargetKey } from "./story-targeting.ts";
 
-export interface ResolvedDocumentSection {
-  index: number;
-  start: number;
-  end: number;
-  properties?: SectionProperties;
-}
+/**
+ * Pass 2 (2026-04-22) — relocated to
+ * `src/model/layout/resolved-layout-types.ts`. Re-exported here so
+ * existing consumers of `ResolvedDocumentSection` keep working
+ * unchanged.
+ */
+export type { ResolvedDocumentSection } from "../model/layout/resolved-layout-types.ts";
 
 export function buildResolvedSections(
   document: CanonicalDocumentEnvelope,