@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/ui-tailwind/debug/layer11-consumer-readiness.ts

@@ -0,0 +1,272 @@
+export type Layer11SurfaceConsumer =
+  | "page-stack"
+  | "scope-card"
+  | "scope-rail"
+  | "object-selection"
+  | "selection-toolbar"
+  | "caret"
+  | "broad-scope"
+  | "comments"
+  | "field-matrix";
+
+export type Layer11FactSource =
+  | "ui-api"
+  | "l05-geometry"
+  | "l04-layout"
+  | "l10-overlay-lane"
+  | "runtime-readback";
+
+export type Layer11FallbackSource =
+  | "dom-measurement"
+  | "pm-dom"
+  | "workflow-facet"
+  | "diagnostic-evidence";
+
+export interface Layer11ConsumerReadinessInput {
+  consumer: Layer11SurfaceConsumer;
+  facts: readonly Layer11FactSource[];
+  fallbacks?: readonly Layer11FallbackSource[];
+  exactGeometryRequired?: boolean;
+}
+
+export interface Layer11ConsumerReadiness {
+  consumer: Layer11SurfaceConsumer;
+  status: "ready" | "guarded" | "blocked";
+  canPaintFromFacts: boolean;
+  degradedFallbacks: readonly Layer11FallbackSource[];
+  reason: string;
+}
+
+export type Layer11OpenWorkStatus =
+  | "closed"
+  | "ready"
+  | "blocked-upstream";
+
+export interface Layer11OpenWorkItem {
+  id: string;
+  owner: "L11" | "L04" | "L05" | "L10" | "architecture";
+  facts: readonly Layer11FactSource[];
+  requiredFacts?: readonly Layer11FactSource[];
+  completed?: boolean;
+  upstreamBlockers?: readonly string[];
+  ownerDecisionRequired?: boolean;
+}
+
+export interface Layer11OpenWorkReadiness {
+  id: string;
+  owner: Layer11OpenWorkItem["owner"];
+  status: Layer11OpenWorkStatus;
+  missingFacts: readonly Layer11FactSource[];
+  upstreamBlockers: readonly string[];
+  reason: string;
+}
+
+export interface Layer11OpenWorkSummary {
+  closedCount: number;
+  readyCount: number;
+  blockedUpstreamCount: number;
+  entries: readonly Layer11OpenWorkReadiness[];
+}
+
+export function evaluateLayer11ConsumerReadiness(
+  input: Layer11ConsumerReadinessInput,
+): Layer11ConsumerReadiness {
+  const facts = new Set(input.facts);
+  const fallbacks = Array.from(new Set(input.fallbacks ?? []));
+  const hasTypedFact =
+    facts.has("ui-api") ||
+    facts.has("l04-layout") ||
+    facts.has("l05-geometry") ||
+    facts.has("l10-overlay-lane") ||
+    facts.has("runtime-readback");
+  const hasExactGeometry = facts.has("l05-geometry") || facts.has("l04-layout");
+
+  if (!hasTypedFact) {
+    return {
+      consumer: input.consumer,
+      status: "blocked",
+      canPaintFromFacts: false,
+      degradedFallbacks: fallbacks,
+      reason: "No UI API, L04 layout, L05 geometry, L10 lane, or runtime readback fact is present.",
+    };
+  }
+
+  if (input.exactGeometryRequired && !hasExactGeometry) {
+    return {
+      consumer: input.consumer,
+      status: "guarded",
+      canPaintFromFacts: false,
+      degradedFallbacks: fallbacks,
+      reason: "Typed readback is present, but exact L04/L05 geometry is still required.",
+    };
+  }
+
+  if (fallbacks.length > 0) {
+    return {
+      consumer: input.consumer,
+      status: "guarded",
+      canPaintFromFacts: true,
+      degradedFallbacks: fallbacks,
+      reason: "Typed facts are present; fallback remains compatibility-only.",
+    };
+  }
+
+  return {
+    consumer: input.consumer,
+    status: "ready",
+    canPaintFromFacts: true,
+    degradedFallbacks: [],
+    reason: "Typed presentation facts are available and no degraded fallback is needed.",
+  };
+}
+
+export function summarizeLayer11OpenWork(
+  items: readonly Layer11OpenWorkItem[],
+): Layer11OpenWorkSummary {
+  const entries = items.map((item): Layer11OpenWorkReadiness => {
+    const facts = new Set(item.facts);
+    const missingFacts = (item.requiredFacts ?? []).filter((fact) => !facts.has(fact));
+    const upstreamBlockers = Array.from(new Set(item.upstreamBlockers ?? []));
+
+    if (item.completed) {
+      return {
+        id: item.id,
+        owner: item.owner,
+        status: "closed",
+        missingFacts: [],
+        upstreamBlockers,
+        reason: "L11 consumer slice is already complete.",
+      };
+    }
+
+    if (
+      item.owner !== "L11" ||
+      item.ownerDecisionRequired ||
+      missingFacts.length > 0 ||
+      upstreamBlockers.length > 0
+    ) {
+      return {
+        id: item.id,
+        owner: item.owner,
+        status: "blocked-upstream",
+        missingFacts,
+        upstreamBlockers,
+        reason: buildOpenWorkBlockedReason(item, missingFacts, upstreamBlockers),
+      };
+    }
+
+    return {
+      id: item.id,
+      owner: item.owner,
+      status: "ready",
+      missingFacts: [],
+      upstreamBlockers: [],
+      reason: "L11 owns the next consumer slice and all required facts are present.",
+    };
+  });
+
+  return {
+    closedCount: entries.filter((entry) => entry.status === "closed").length,
+    readyCount: entries.filter((entry) => entry.status === "ready").length,
+    blockedUpstreamCount: entries.filter((entry) => entry.status === "blocked-upstream").length,
+    entries,
+  };
+}
+
+function buildOpenWorkBlockedReason(
+  item: Layer11OpenWorkItem,
+  missingFacts: readonly Layer11FactSource[],
+  upstreamBlockers: readonly string[],
+): string {
+  if (item.owner !== "L11") {
+    return `Next action is owned by ${item.owner}; L11 should wait for the owning lane surface.`;
+  }
+  if (item.ownerDecisionRequired) {
+    return "Architecture/owning-layer decision is required before L11 can consume or delete this surface.";
+  }
+  if (missingFacts.length > 0) {
+    return `Missing required presentation fact(s): ${missingFacts.join(", ")}.`;
+  }
+  if (upstreamBlockers.length > 0) {
+    return `Blocked by upstream surface(s): ${upstreamBlockers.join(", ")}.`;
+  }
+  return "Blocked by an upstream owner before L11 can paint from typed facts.";
+}
+
+export type Layer11RenderEvidenceKind =
+  | "word-oracle"
+  | "render-word"
+  | "source-package"
+  | "graph-pdf"
+  | "render-libre"
+  | "runtime-dom";
+
+export interface Layer11RenderEvidenceEntry {
+  id: string;
+  kind: Layer11RenderEvidenceKind;
+  sourceFactPresent?: boolean;
+}
+
+export interface Layer11RenderCalibrationSummary {
+  primaryEvidenceCount: number;
+  secondaryEvidenceCount: number;
+  rejectedEvidenceCount: number;
+  assertionReady: boolean;
+  route: "presentation-check" | "lower-layer-fact-required" | "insufficient-evidence";
+}
+
+const PRIMARY_RENDER_EVIDENCE = new Set<Layer11RenderEvidenceKind>([
+  "word-oracle",
+  "render-word",
+  "source-package",
+]);
+
+const SECONDARY_RENDER_EVIDENCE = new Set<Layer11RenderEvidenceKind>([
+  "graph-pdf",
+  "render-libre",
+]);
+
+export function summarizeWordFirstRenderCalibration(
+  entries: readonly Layer11RenderEvidenceEntry[],
+): Layer11RenderCalibrationSummary {
+  const primaryEvidenceCount = entries.filter((entry) =>
+    PRIMARY_RENDER_EVIDENCE.has(entry.kind),
+  ).length;
+  const secondaryEvidenceCount = entries.filter((entry) =>
+    SECONDARY_RENDER_EVIDENCE.has(entry.kind),
+  ).length;
+  const rejectedEvidenceCount = entries.filter(
+    (entry) =>
+      !PRIMARY_RENDER_EVIDENCE.has(entry.kind) &&
+      !SECONDARY_RENDER_EVIDENCE.has(entry.kind),
+  ).length;
+  const hasSourceFact = entries.some((entry) => entry.sourceFactPresent === true);
+
+  if (primaryEvidenceCount === 0) {
+    return {
+      primaryEvidenceCount,
+      secondaryEvidenceCount,
+      rejectedEvidenceCount,
+      assertionReady: false,
+      route: "insufficient-evidence",
+    };
+  }
+
+  if (!hasSourceFact) {
+    return {
+      primaryEvidenceCount,
+      secondaryEvidenceCount,
+      rejectedEvidenceCount,
+      assertionReady: false,
+      route: "lower-layer-fact-required",
+    };
+  }
+
+  return {
+    primaryEvidenceCount,
+    secondaryEvidenceCount,
+    rejectedEvidenceCount,
+    assertionReady: true,
+    route: "presentation-check",
+  };
+}

package/src/ui-tailwind/debug/layer11-word-field-matrix-evidence.ts

@@ -0,0 +1,160 @@
+import type {
+  UiDebugEvidenceLaneEntry,
+  UiDebugEvidenceLaneSnapshot,
+} from "../../api/v3/ui/_types.ts";
+
+export interface Layer11WordFieldMatrixEvidenceEntry {
+  id: string;
+  status: UiDebugEvidenceLaneEntry["status"];
+  source: string;
+  docId?: string;
+  factId?: string;
+  owner?: string;
+  route:
+    | "render-visibility-evidence"
+    | "lower-layer-fact-required"
+    | "unavailable";
+  assertion: "evidence-only" | "assertion-ready" | "unavailable";
+}
+
+export interface Layer11WordFieldMatrixEvidenceSummary {
+  status: UiDebugEvidenceLaneSnapshot["status"];
+  revision: number;
+  renderVisibilityEvidenceCount: number;
+  lowerLayerGapCount: number;
+  assertionReadyCount: number;
+  entries: readonly Layer11WordFieldMatrixEvidenceEntry[];
+}
+
+function classifyEntry(
+  entry: UiDebugEvidenceLaneEntry,
+): Layer11WordFieldMatrixEvidenceEntry["route"] {
+  if (entry.status !== "available") {
+    return "unavailable";
+  }
+
+  const source = entry.source ?? "";
+  const payload = payloadRecord(entry);
+  const artifactKind = payload.artifactKind;
+  if (source === "pe2.word-field-matrix" || artifactKind === "pe2.word-field-matrix") {
+    return "render-visibility-evidence";
+  }
+
+  return "lower-layer-fact-required";
+}
+
+function payloadRecord(entry: UiDebugEvidenceLaneEntry): Record<string, unknown> {
+  return entry.payload && typeof entry.payload === "object"
+    ? entry.payload as Record<string, unknown>
+    : {};
+}
+
+function payloadOwner(entry: UiDebugEvidenceLaneEntry): string | undefined {
+  const owner = payloadRecord(entry).owner;
+  return typeof owner === "string" && owner.length > 0 ? owner : undefined;
+}
+
+export function summarizeLayer11WordFieldMatrixEvidence(
+  lane: UiDebugEvidenceLaneSnapshot,
+  options: {
+    assertionReadyEntryIds?: readonly string[];
+    renderWordDocIds?: readonly string[];
+  } = {},
+): Layer11WordFieldMatrixEvidenceSummary {
+  if (lane.kind !== "word-field-matrix") {
+    return {
+      status: "unavailable",
+      revision: lane.revision,
+      renderVisibilityEvidenceCount: 0,
+      lowerLayerGapCount: 0,
+      assertionReadyCount: 0,
+      entries: [],
+    };
+  }
+
+  const assertionReadyIds = new Set(options.assertionReadyEntryIds ?? []);
+  const renderWordDocIds = new Set(options.renderWordDocIds ?? []);
+  const entries = lane.entries.map((entry) => {
+    const route = classifyEntry(entry);
+    const payload = payloadRecord(entry);
+    const docId = payloadDocId(payload);
+    const factId = payloadTableFrameContextFactId(payload);
+    const hasTableFrameRenderWordEvidence =
+      factId !== undefined && docId !== undefined && renderWordDocIds.has(docId);
+    const assertion: Layer11WordFieldMatrixEvidenceEntry["assertion"] =
+      route === "unavailable"
+        ? "unavailable"
+        : assertionReadyIds.has(entry.id) || hasTableFrameRenderWordEvidence
+          ? "assertion-ready"
+          : "evidence-only";
+    return {
+      id: entry.id,
+      status: entry.status,
+      source: entry.source ?? lane.source,
+      ...(docId ? { docId } : {}),
+      ...(factId ? { factId } : {}),
+      owner: payloadOwner(entry),
+      route,
+      assertion,
+    };
+  });
+
+  return {
+    status: lane.status,
+    revision: lane.revision,
+    renderVisibilityEvidenceCount: entries.filter(
+      (entry) => entry.route === "render-visibility-evidence",
+    ).length,
+    lowerLayerGapCount: entries.filter(
+      (entry) => entry.route === "lower-layer-fact-required",
+    ).length,
+    assertionReadyCount: entries.filter(
+      (entry) => entry.assertion === "assertion-ready",
+    ).length,
+    entries,
+  };
+}
+
+function payloadDocId(payload: Record<string, unknown>): string | undefined {
+  const direct = payload.docId;
+  if (typeof direct === "string" && direct.length > 0) {
+    return direct;
+  }
+
+  const doc = payload.doc;
+  if (doc && typeof doc === "object") {
+    const docId = (doc as Record<string, unknown>).docId;
+    if (typeof docId === "string" && docId.length > 0) {
+      return docId;
+    }
+  }
+
+  return undefined;
+}
+
+function payloadTableFrameContextFactId(
+  payload: Record<string, unknown>,
+): string | undefined {
+  const direct = payload.tableFrameContextFactId;
+  if (typeof direct === "string" && direct.length > 0) {
+    return direct;
+  }
+
+  const factKind = payload.factKind ?? payload.contextKind;
+  const namesTableFrameContext =
+    factKind === "tableFrameContext" ||
+    payload.tableFrameContext !== undefined ||
+    payload.tableFrameContextAvailable === true;
+  if (!namesTableFrameContext) {
+    return undefined;
+  }
+
+  for (const key of ["factId", "namedFactId", "sourceFactId", "rowId"]) {
+    const value = payload[key];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+
+  return undefined;
+}

package/src/ui-tailwind/editor-surface/perf-probe.ts

@@ -1,215 +1,14 @@
-export type PerfProbeKind =
-  | "typing"
-  | "typing.predicted"
-  | "typing.reconcile"
-  | "typing.divergence"
-  | "selection"
-  | "runtime.create"
-  | "loadSession.laycacheProbe"
-  | "loadSession.compatReportCached"
-  | "snapshot.surface"
-  | "snapshot.compatibility"
-  | "snapshot.navigation"
-  | "pm.rebuild"
-  | "pm.decorations"
-  | "pm.decorations.comments"
-  | "pm.decorations.revisions"
-  | "pm.decorations.workflow"
-  | "pm.mount"
-  | "shell.render"
-  | "workspace.chrome"
-  | "selection.sync"
-  | "layout.incremental"
-  | "layout.full"
-  | "render.frame_build"
-  | "render.frame_diff"
-  | "render.decoration_resolve"
-  | "chrome.overlay_reposition"
-  | "chrome.hit_test"
-  | "rail.segment_project";
-
-/**
- * Counter names the FastTextEditLane emits via `incrementInvalidationCounter`.
- * Expose them as a const so integrators can read the shape without duplicating
- * strings.
- */
-export const PREDICTED_LANE_COUNTERS = {
-  applied: "predictions.applied",
-  equivalent: "predictions.equivalent",
-  adjusted: "predictions.adjusted",
-  rejected: "predictions.rejected",
-  rollback: "predictions.rollback",
-  structuralDivergence: "predictions.structuralDivergence",
-  bailBeforePredict: "predictions.bailBeforePredict",
-  refreshSelectionOnly: "predictions.refresh.selectionOnly",
-  refreshLocalTextEquivalent: "predictions.refresh.localTextEquivalent",
-  refreshSurfaceOnly: "predictions.refresh.surfaceOnly",
-  refreshFullProjection: "predictions.refresh.fullProjection",
-  refreshBlocked: "predictions.refresh.blocked",
-} as const;
-
-export interface PerfProbeSample {
-  token: string;
-  kind: PerfProbeKind;
-  durationMs: number;
-  recordedAt: number;
-}
-
-interface PendingProbe {
-  kind: PerfProbeKind;
-  startedAt: number;
-}
-
-interface PerfProbeState {
-  enabled?: boolean;
-  nextToken?: number;
-  pending?: Record<string, PendingProbe>;
-  samples?: PerfProbeSample[];
-  maxSamples?: number;
-  invalidationCounts?: Record<string, number>;
-}
-
-export interface PerfProbeSummary {
-  samples: PerfProbeSample[];
-  latest: Partial<Record<PerfProbeKind, PerfProbeSample | null>>;
-  invalidationCounts: Record<string, number>;
-}
-
-declare global {
-  interface Window {
-    __DOCX_REACT_PERF_PROBE__?: PerfProbeState;
-  }
-}
-
-export function startPerfProbe(kind: PerfProbeKind): string | null {
-  const state = getEnabledState();
-  if (!state) {
-    return null;
-  }
-
-  const token = `${kind}-${state.nextToken ?? 0}`;
-  state.nextToken = (state.nextToken ?? 0) + 1;
-  state.pending ??= {};
-  state.pending[token] = {
-    kind,
-    startedAt: performance.now(),
-  };
-  return token;
-}
-
-export function finishPerfProbe(token: string | null | undefined): PerfProbeSample | null {
-  if (!token) {
-    return null;
-  }
-  const state = getEnabledState();
-  if (!state?.pending?.[token]) {
-    return null;
-  }
-
-  const pending = state.pending[token];
-  delete state.pending[token];
-
-  const sample: PerfProbeSample = {
-    token,
-    kind: pending.kind,
-    durationMs: performance.now() - pending.startedAt,
-    recordedAt: Date.now(),
-  };
-
-  pushSample(state, sample);
-
-  return sample;
-}
-
-export function recordPerfSample(
-  kind: PerfProbeKind,
-  durationMs = 0,
-): PerfProbeSample | null {
-  const state = getEnabledState();
-  if (!state) {
-    return null;
-  }
-
-  const token = `${kind}-${state.nextToken ?? 0}`;
-  state.nextToken = (state.nextToken ?? 0) + 1;
-  const sample: PerfProbeSample = {
-    token,
-    kind,
-    durationMs,
-    recordedAt: Date.now(),
-  };
-  pushSample(state, sample);
-  return sample;
-}
-
-export function incrementInvalidationCounter(
-  counter: string,
-  amount = 1,
-): number {
-  const state = getEnabledState();
-  if (!state) {
-    return 0;
-  }
-
-  state.invalidationCounts ??= {};
-  state.invalidationCounts[counter] =
-    (state.invalidationCounts[counter] ?? 0) + amount;
-  return state.invalidationCounts[counter]!;
-}
-
-export function getLatestPerfSummary(): PerfProbeSummary | null {
-  const state = getEnabledState();
-  const samples = state?.samples ?? [];
-  if (!state || samples.length === 0) {
-    return null;
-  }
-
-  return {
-    samples: [...samples],
-    latest: buildLatestSampleMap(samples),
-    invalidationCounts: { ...(state.invalidationCounts ?? {}) },
-  };
-}
-
-export function resetPerfProbeState(): void {
-  const state = getEnabledState();
-  if (!state) {
-    return;
-  }
-  state.nextToken = 0;
-  state.pending = {};
-  state.samples = [];
-  state.invalidationCounts = {};
-}
-
-function getEnabledState(): PerfProbeState | null {
-  if (typeof window === "undefined") {
-    return null;
-  }
-  const state = window.__DOCX_REACT_PERF_PROBE__;
-  if (!state?.enabled) {
-    return null;
-  }
-  return state;
-}
-
-function pushSample(state: PerfProbeState, sample: PerfProbeSample): void {
-  state.samples ??= [];
-  state.samples.push(sample);
-  const maxSamples = state.maxSamples ?? 20;
-  if (state.samples.length > maxSamples) {
-    state.samples.splice(0, state.samples.length - maxSamples);
-  }
-}
-
-function buildLatestSampleMap(
-  samples: PerfProbeSample[],
-): Partial<Record<PerfProbeKind, PerfProbeSample | null>> {
-  const latest: Partial<Record<PerfProbeKind, PerfProbeSample | null>> = {};
-  for (const sample of [...samples].reverse()) {
-    if (latest[sample.kind] === undefined) {
-      latest[sample.kind] = sample;
-    }
-  }
-  return latest;
-}
+export {
+  finishPerfProbe,
+  getLatestPerfSummary,
+  incrementInvalidationCounter,
+  PREDICTED_LANE_COUNTERS,
+  recordPerfSample,
+  resetPerfProbeState,
+  startPerfProbe,
+} from "../../api/v3/runtime/perf-probe.ts";
+export type {
+  PerfProbeKind,
+  PerfProbeSample,
+  PerfProbeSummary,
+} from "../../api/v3/runtime/perf-probe.ts";

package/src/ui-tailwind/editor-surface/pm-decorations.ts

@@ -840,3 +840,45 @@ export function buildDecorations(
 
   return DecorationSet.create(doc, decorations);
 }
+
+export interface RuntimeDecorationBuildInput {
+  doc: PMNode;
+  positionMap: PositionMap;
+  commentModel: CommentDecorationModel | undefined;
+  revisionModel: RevisionDecorationModel | undefined;
+  markupDisplay: MarkupDisplay;
+  showTrackedChanges: boolean;
+  suggestionsEnabled: boolean;
+  workflowScopes: readonly WorkflowScope[] | undefined;
+  activeStory: EditorStoryTarget;
+  workflowCandidates: readonly WorkflowCandidateRange[] | undefined;
+  workflowBlockedReasons: readonly WorkflowBlockedCommandReason[] | undefined;
+  workflowLockedZones: readonly WorkflowLockedZone[] | undefined;
+  activeWorkflowWorkItemId: string | null | undefined;
+  activeWorkflowScopeIds: readonly string[] | undefined;
+  workflowMetadata: readonly WorkflowMetadataMarkup[] | undefined;
+  revisionDisplayByOffset?: ReadonlyMap<number, RevisionDisplayFlags>;
+}
+
+export function buildRuntimeDecorations(
+  input: RuntimeDecorationBuildInput,
+): DecorationSet {
+  return buildDecorations(
+    input.doc,
+    input.positionMap,
+    input.commentModel,
+    input.revisionModel,
+    input.markupDisplay,
+    input.showTrackedChanges,
+    input.suggestionsEnabled,
+    input.workflowScopes,
+    input.activeStory,
+    input.workflowCandidates,
+    input.workflowBlockedReasons,
+    input.workflowLockedZones,
+    input.activeWorkflowWorkItemId,
+    input.activeWorkflowScopeIds,
+    input.workflowMetadata,
+    input.revisionDisplayByOffset,
+  );
+}