@beyondwork/docx-react-component 1.0.48 → 1.0.49

package/src/runtime/collab/workflow-shared.ts

@@ -0,0 +1,247 @@
+import * as Y from "yjs";
+
+import type { CollabBlockReason } from "../../api/comment-negotiation-types.ts";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface SharedWorkflowState {
+  lockedMode?: "editing" | "suggesting" | "commenting" | "viewing";
+  roundDeadline?: string; // ISO-8601
+  assignedReviewers?: string[]; // userIds
+  workItemId?: string;
+}
+
+export interface CreateWorkflowSharedOptions {
+  ydoc: Y.Doc;
+  role: "author" | "reviewer" | "observer";
+  /**
+   * Reserved for future audit use — emit `{ actor: localAuthorId }` on
+   * writes once the audit path lands. Currently unused at runtime;
+   * optional so callers without an author-id scheme don't have to
+   * fabricate one.
+   */
+  localAuthorId?: string;
+}
+
+export type WorkflowSharedResult =
+  | { ok: true }
+  | { ok: false; reason: CollabBlockReason };
+
+export interface WorkflowSharedHandle {
+  get(): SharedWorkflowState;
+  setLockedMode(mode: SharedWorkflowState["lockedMode"]): WorkflowSharedResult;
+  setRoundDeadline(deadline: string | undefined): WorkflowSharedResult;
+  setAssignedReviewers(reviewers: string[]): WorkflowSharedResult;
+  setWorkItemId(id: string | undefined): WorkflowSharedResult;
+  subscribe(listener: (state: SharedWorkflowState) => void): () => void;
+  destroy(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Y.Map key constants
+// ---------------------------------------------------------------------------
+
+const WORKFLOW_MAP_NAME = "workflow";
+const KEY_LOCKED_MODE = "lockedMode";
+const KEY_ROUND_DEADLINE = "roundDeadline";
+const KEY_ASSIGNED_REVIEWERS = "assignedReviewers";
+const KEY_WORK_ITEM_ID = "workItemId";
+
+// ---------------------------------------------------------------------------
+// Shallow-equality helpers
+// ---------------------------------------------------------------------------
+
+function arrayShallowEqual(
+  a: string[] | undefined,
+  b: string[] | undefined,
+): boolean {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+function stateShallowEqual(
+  a: SharedWorkflowState,
+  b: SharedWorkflowState,
+): boolean {
+  return (
+    a.lockedMode === b.lockedMode &&
+    a.roundDeadline === b.roundDeadline &&
+    a.workItemId === b.workItemId &&
+    arrayShallowEqual(a.assignedReviewers, b.assignedReviewers)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a handle over `ydoc.getMap<unknown>("workflow")` that propagates
+ * shared workflow state — `lockedMode`, `roundDeadline`, `assignedReviewers`,
+ * and `workItemId` — across collab peers via per-key Yjs LWW conflict
+ * resolution.
+ *
+ * Role-gating (§7 lane plan):
+ * - observer: all writes refused with `collab_observer_readonly`.
+ * - reviewer: only `setAssignedReviewers` allowed; other writes refused with
+ *   `collab_role_restricted`.
+ * - author: all writes allowed.
+ */
+export function createWorkflowShared(
+  options: CreateWorkflowSharedOptions,
+): WorkflowSharedHandle {
+  const { ydoc, role } = options;
+  // Reserved for future audit path — see CreateWorkflowSharedOptions.localAuthorId.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const _localAuthorId = options.localAuthorId;
+
+  const yMap = ydoc.getMap<unknown>(WORKFLOW_MAP_NAME);
+
+  const listeners = new Set<(state: SharedWorkflowState) => void>();
+  let destroyed = false;
+  let lastEmitted: SharedWorkflowState | null = null;
+
+  // -------------------------------------------------------------------------
+  // Read helper
+  // -------------------------------------------------------------------------
+
+  function readState(): SharedWorkflowState {
+    const state: SharedWorkflowState = {};
+    const lockedMode = yMap.get(KEY_LOCKED_MODE);
+    if (lockedMode !== undefined) {
+      state.lockedMode = lockedMode as SharedWorkflowState["lockedMode"];
+    }
+    const roundDeadline = yMap.get(KEY_ROUND_DEADLINE);
+    if (roundDeadline !== undefined) {
+      state.roundDeadline = roundDeadline as string;
+    }
+    const assignedReviewers = yMap.get(KEY_ASSIGNED_REVIEWERS);
+    if (assignedReviewers !== undefined) {
+      state.assignedReviewers = [...(assignedReviewers as string[])];
+    }
+    const workItemId = yMap.get(KEY_WORK_ITEM_ID);
+    if (workItemId !== undefined) {
+      state.workItemId = workItemId as string;
+    }
+    return state;
+  }
+
+  // -------------------------------------------------------------------------
+  // Observer — dedup-fires listeners on any Y.Map change
+  // -------------------------------------------------------------------------
+
+  function onMapChange(): void {
+    if (destroyed) return;
+    if (listeners.size === 0) {
+      lastEmitted = null;
+      return;
+    }
+    const next = readState();
+    if (lastEmitted !== null && stateShallowEqual(lastEmitted, next)) {
+      return; // deduplicated — same state, skip fire
+    }
+    lastEmitted = next;
+    for (const listener of [...listeners]) {
+      try {
+        listener(next);
+      } catch {
+        // Listener exceptions are isolated; the handle continues.
+      }
+    }
+  }
+
+  yMap.observe(onMapChange);
+
+  // -------------------------------------------------------------------------
+  // Role-gating helpers
+  // -------------------------------------------------------------------------
+
+  function checkObserver(): WorkflowSharedResult | null {
+    if (role === "observer") {
+      return { ok: false, reason: "collab_observer_readonly" };
+    }
+    return null;
+  }
+
+  function checkReviewerRestricted(): WorkflowSharedResult | null {
+    if (role === "reviewer") {
+      return { ok: false, reason: "collab_role_restricted" };
+    }
+    return null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Handle
+  // -------------------------------------------------------------------------
+
+  return {
+    get(): SharedWorkflowState {
+      return readState();
+    },
+
+    setLockedMode(mode): WorkflowSharedResult {
+      const denied = checkObserver() ?? checkReviewerRestricted();
+      if (denied) return denied;
+      if (mode === undefined) {
+        yMap.delete(KEY_LOCKED_MODE);
+      } else {
+        yMap.set(KEY_LOCKED_MODE, mode);
+      }
+      return { ok: true };
+    },
+
+    setRoundDeadline(deadline): WorkflowSharedResult {
+      const denied = checkObserver() ?? checkReviewerRestricted();
+      if (denied) return denied;
+      if (deadline === undefined) {
+        yMap.delete(KEY_ROUND_DEADLINE);
+      } else {
+        yMap.set(KEY_ROUND_DEADLINE, deadline);
+      }
+      return { ok: true };
+    },
+
+    setAssignedReviewers(reviewers): WorkflowSharedResult {
+      const denied = checkObserver();
+      if (denied) return denied;
+      // reviewer is allowed here — do NOT call checkReviewerRestricted().
+      yMap.set(KEY_ASSIGNED_REVIEWERS, [...reviewers]);
+      return { ok: true };
+    },
+
+    setWorkItemId(id): WorkflowSharedResult {
+      const denied = checkObserver() ?? checkReviewerRestricted();
+      if (denied) return denied;
+      if (id === undefined) {
+        yMap.delete(KEY_WORK_ITEM_ID);
+      } else {
+        yMap.set(KEY_WORK_ITEM_ID, id);
+      }
+      return { ok: true };
+    },
+
+    subscribe(listener): () => void {
+      listeners.add(listener);
+      // Reset dedup baseline so the next change always fires fresh.
+      lastEmitted = null;
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    destroy(): void {
+      if (destroyed) return;
+      destroyed = true;
+      yMap.unobserve(onMapChange);
+      listeners.clear();
+      lastEmitted = null;
+    },
+  };
+}

package/src/runtime/document-locations.ts

@@ -18,6 +18,7 @@ import type {
 } from "../api/public-types";
 import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
 import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+import { createPublicRangeAnchor } from "../core/selection/anchor-conversion.ts";
 import {
   createDocumentSectionSnapshots,
   findBookmarkNameForOffset,
@@ -47,15 +48,6 @@ function createLocationId(anchor: EditorAnchorProjection, storyTarget?: EditorSt
   }
 }
 
-function createPublicRangeAnchor(from: number, to: number): EditorAnchorProjection {
-  return {
-    kind: "range",
-    from,
-    to,
-    assoc: { start: -1, end: 1 },
-  };
-}
-
 function resolveOffsetMetadata(
   navigation: DocumentNavigationSnapshot,
   offset: number,

package/src/runtime/document-outline.ts

@@ -18,6 +18,7 @@ import type {
 import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
 import { createSelectionSnapshot } from "../core/state/editor-state.ts";
 import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+import { createPublicRangeAnchor } from "../core/selection/anchor-conversion.ts";
 import { parseTocLevelRange } from "../io/ooxml/parse-fields.ts";
 import { buildPageLayoutSnapshot, buildResolvedSections } from "./document-layout.ts";
 import { createDocumentNavigationSnapshot } from "./document-navigation.ts";
@@ -34,15 +35,6 @@ function getAnchorOffset(anchor: EditorAnchorProjection): number | undefined {
   }
 }
 
-function createPublicRangeAnchor(from: number, to: number): EditorAnchorProjection {
-  return {
-    kind: "range",
-    from,
-    to,
-    assoc: { start: -1, end: 1 },
-  };
-}
-
 export function resolveHeadingPath(
   headings: readonly DocumentHeadingSnapshot[],
   offset: number | undefined,

package/src/runtime/document-runtime.ts

@@ -30,6 +30,7 @@ import type {
   DocumentTextToken,
   EditorSessionState,
   EditorAnchorProjection,
+  TextFormattingDirective,
   EditorError,
   EditorStoryTarget,
   EditorViewStateSnapshot,
@@ -104,7 +105,14 @@ import {
   storyTargetsEqual,
   type EditorAnchorProjection as InternalEditorAnchorProjection,
 } from "../core/selection/mapping.ts";
-import { canCreateDocxCommentAnchor } from "../core/selection/review-anchors.ts";
+import {
+  toInternalAnchorProjection,
+  toPublicAnchorProjection,
+} from "../core/selection/anchor-conversion.ts";
+import {
+  commentAnchorRejectionReason,
+  snapCommentAnchorAwayFromTable,
+} from "../core/selection/review-anchors.ts";
 import { buildBookmarkNameMap } from "../legal/bookmarks.ts";
 import {
   describeOpaqueFragment,
@@ -232,6 +240,7 @@ import type {
 } from "../api/editor-state-types.ts";
 import { collectEditorStateForSerialize } from "./editor-state-integration.ts";
 import type { EditorStatePayload } from "../io/ooxml/workflow-payload.ts";
+import type { SharedWorkflowState } from "./collab/workflow-shared.ts";
 
 /** Internal extension of ExportDocxOptions that threads the collected
  *  editorState payload from the runtime to the docx serializer. */
@@ -265,7 +274,7 @@ export interface DocumentRuntime {
   getRenderSnapshot(): RuntimeRenderSnapshot;
   getCanonicalDocument(): CanonicalDocumentEnvelope;
   getSourcePackage(): EditorSessionState["sourcePackage"] | undefined;
-  replaceText(text: string, target?: EditorAnchorProjection): void;
+  replaceText(text: string, target?: EditorAnchorProjection, formatting?: TextFormattingDirective): void;
   applyActiveStoryTextCommand(command: ActiveStoryTextCommand): TextCommandAck;
   dispatch(command: EditorCommand): void;
   /**
@@ -359,6 +368,7 @@ export interface DocumentRuntime {
   setWorkflowOverlay(overlay: WorkflowOverlay): void;
   clearWorkflowOverlay(): void;
   getWorkflowOverlay(): WorkflowOverlay | null;
+  setSharedWorkflowState(state: SharedWorkflowState | null): void;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
@@ -629,6 +639,9 @@ export function createDocumentRuntime(
     ?? options.initialSnapshot?.workflowMetadata?.entries
     ?? [];
   let hostAnnotationOverlay: HostAnnotationOverlay | null = null;
+  // P13 Slice B: shared workflow state from the collab Y.Map "workflow".
+  // Set via setSharedWorkflowState(); observed by evaluateWorkflowBlockedReasons.
+  let sharedWorkflowState: SharedWorkflowState | null = null;
   const initialPersistedSnapshot = options.initialSessionState
     ? persistedSnapshotFromEditorSessionState(options.initialSessionState, {
         savedAt: options.initialSessionState.updatedAt,
@@ -873,6 +886,7 @@ export function createDocumentRuntime(
         documentMode: DocumentMode;
         protectionSnapshot: ProtectionSnapshot;
         workflowOverlay: WorkflowOverlay | null;
+        sharedWorkflowState: SharedWorkflowState | null;
         snapshot: InteractionGuardSnapshot;
       }
     | undefined;
@@ -1140,6 +1154,29 @@ export function createDocumentRuntime(
     commandType?: string,
   ): WorkflowBlockedCommandReason[] {
     const reasons: WorkflowBlockedCommandReason[] = [];
+    // P13 Slice B: shared lockedMode overrides all other scope checks when
+    // non-editing. Short-circuit: no other scope reason applies when the round
+    // is locked (the round state supersedes scope/overlay-level gating).
+    // Emit a reason code whose effectiveMode mapping matches the mode intent:
+    //   "commenting" → workflow_comment_only (maps to effectiveMode: "comment")
+    //   "viewing"    → workflow_view_only    (maps to effectiveMode: "view")
+    //   "suggesting" → workflow_round_locked (no existing mapping; stays "blocked"
+    //                   for this slice — full suggesting-mode semantics will be a
+    //                   future slice that hooks getEffectiveDocumentMode instead).
+    if (sharedWorkflowState?.lockedMode && sharedWorkflowState.lockedMode !== "editing") {
+      const lockedMode = sharedWorkflowState.lockedMode;
+      const code: WorkflowBlockedCommandReason["code"] =
+        lockedMode === "commenting"
+          ? "workflow_comment_only"
+          : lockedMode === "viewing"
+            ? "workflow_view_only"
+            : "workflow_round_locked";
+      reasons.push({
+        code,
+        message: `Round is locked to ${lockedMode} mode.`,
+      });
+      return reasons;
+    }
     const selectionBounds = {
       from: Math.min(selection.anchor, selection.head),
       to: Math.max(selection.anchor, selection.head),
@@ -1552,7 +1589,8 @@ export function createDocumentRuntime(
       cachedInteractionGuardSnapshot.readOnly === state.readOnly &&
       cachedInteractionGuardSnapshot.documentMode === viewState.documentMode &&
       cachedInteractionGuardSnapshot.protectionSnapshot === protectionSnapshot &&
-      cachedInteractionGuardSnapshot.workflowOverlay === workflowOverlay
+      cachedInteractionGuardSnapshot.workflowOverlay === workflowOverlay &&
+      cachedInteractionGuardSnapshot.sharedWorkflowState === sharedWorkflowState
     ) {
       return cachedInteractionGuardSnapshot.snapshot;
     }
@@ -1613,6 +1651,7 @@ export function createDocumentRuntime(
       documentMode: viewState.documentMode,
       protectionSnapshot,
       workflowOverlay,
+      sharedWorkflowState,
       snapshot,
     };
     return snapshot;
@@ -2256,13 +2295,14 @@ export function createDocumentRuntime(
     getDefaultAuthorId() {
       return defaultAuthorId;
     },
-    replaceText(text, target) {
+    replaceText(text, target, formatting) {
       try {
         const timestamp = clock();
         applyTextCommandInActiveStory(
           {
             type: "text.insert",
             text,
+            ...(formatting ? { formatting } : {}),
             origin: createOrigin("api", timestamp),
           },
           {
@@ -2309,22 +2349,39 @@ export function createDocumentRuntime(
         throw toStructuredRuntimeException(error);
       }
       const commentId = createEntityId("comment", state.document.review.comments, clock());
-      const anchor = params.anchor
+      let anchor = params.anchor
         ? toInternalAnchorProjection(params.anchor)
         : state.selection.activeRange;
-      const selection = params.anchor
+      let selection = params.anchor
         ? createSelectionFromPublicAnchor(params.anchor)
         : state.selection;
-      if (!canCreateDocxCommentAnchor(cachedRenderSnapshot.surface, anchor)) {
+      if (params.snapToSafeBoundary === true) {
+        const snapped = snapCommentAnchorAwayFromTable(
+          cachedRenderSnapshot.surface,
+          anchor,
+        );
+        if (snapped !== null && snapped !== anchor) {
+          anchor = snapped;
+          selection = createSelectionFromPublicAnchor(toPublicAnchorProjection(snapped));
+        }
+      }
+      const rejectionReason = commentAnchorRejectionReason(
+        cachedRenderSnapshot.surface,
+        anchor,
+      );
+      if (rejectionReason !== null) {
+        const message =
+          rejectionReason === "comment_anchor_table_adjacent"
+            ? "DOCX comments cannot currently anchor mid-run within a paragraph adjacent to a table boundary — snap the range to a paragraph or word boundary and retry."
+            : "DOCX comments must use a non-empty range that stays within a single story and does not cross table or opaque-fragment boundaries.";
         const error: InternalEditorError = {
           errorId: createSessionId("comment-anchor", clock()),
           code: "validation_failed",
           isFatal: false,
-          message:
-            "DOCX comments must use a non-empty range that stays within a single story and does not cross table or opaque-fragment boundaries.",
+          message,
           source: "runtime",
           details: {
-            reason: "invalid_comment_anchor",
+            reason: rejectionReason,
           },
         };
         emitError(error);
@@ -2954,6 +3011,13 @@ export function createDocumentRuntime(
     getWorkflowOverlay() {
       return workflowOverlay;
     },
+    setSharedWorkflowState(state) {
+      if (state === sharedWorkflowState) return;
+      sharedWorkflowState = state;
+      // Invalidate guard/scope caches so next derivation reflects the new state.
+      cachedInteractionGuardSnapshot = undefined;
+      cachedWorkflowScopeSnapshot = undefined;
+    },
     getWorkflowScopeSnapshot() {
       return getCachedWorkflowScopeSnapshot();
     },
@@ -4152,45 +4216,6 @@ function toPublicSelectionSnapshot(
   };
 }
 
-function toPublicAnchorProjection(
-  anchor: InternalEditorAnchorProjection,
-): EditorAnchorProjection {
-  switch (anchor.kind) {
-    case "range":
-      return {
-        kind: "range",
-        from: anchor.range.from,
-        to: anchor.range.to,
-        assoc: anchor.assoc,
-      };
-    case "node":
-      return {
-        kind: "node",
-        at: anchor.at,
-        assoc: anchor.assoc,
-      };
-    case "detached":
-      return {
-        kind: "detached",
-        lastKnownRange: anchor.lastKnownRange,
-        reason: anchor.reason,
-      };
-  }
-}
-
-function toInternalAnchorProjection(
-  anchor: EditorAnchorProjection,
-): InternalEditorAnchorProjection {
-  switch (anchor.kind) {
-    case "range":
-      return createRangeAnchor(anchor.from, anchor.to, anchor.assoc);
-    case "node":
-      return createNodeAnchor(anchor.at, anchor.assoc);
-    case "detached":
-      return createDetachedAnchor(anchor.lastKnownRange, anchor.reason);
-  }
-}
-
 function createSelectionFromPublicAnchor(
   anchor: EditorAnchorProjection,
 ): import("../core/state/editor-state.ts").SelectionSnapshot {

package/src/runtime/hyperlink-color-resolver.ts

@@ -0,0 +1,119 @@
+/**
+ * Lane 3 V7 — hyperlink color cascade.
+ *
+ * OOXML convention: runs inside `<w:hyperlink>` inherit the `Hyperlink`
+ * character style implicitly, EVEN WHEN source XML does not declare an
+ * explicit `<w:rStyle w:val="Hyperlink"/>` on each run. Word applies the
+ * style based on the containing hyperlink element's context alone.
+ *
+ * Our existing cascade (`resolveEffectiveRunFormatting`) only applies the
+ * character-style chain when `input.characterStyleId` is populated — so
+ * runs inside hyperlinks that lacked explicit rStyle were inheriting
+ * whatever the paragraph style said (usually black body text).
+ *
+ * This module closes that gap by resolving hyperlink color via a
+ * four-tier fallback chain:
+ *
+ *   1. Direct color on the run (`colorHex !== "auto"`) — wins outright.
+ *   2. Character-style cascade — forces Hyperlink style participation.
+ *   3. Theme hlink slot (`ResolvedTheme.colors.hlink`).
+ *   4. Hardcoded Word default `#0563C1`.
+ *
+ * The resolver also honors `colorThemeSlot` + `colorThemeTint`/`colorThemeShade`
+ * from L2.c by delegating to `resolveThemeColorHex`.
+ *
+ * Contract: the returned `CanonicalRunFormatting` is the effective cascade
+ * result with `colorHex` concretized to a non-theme hex (or `"auto"`). The
+ * original `colorThemeSlot` / `colorThemeTint` / `colorThemeShade` fields
+ * are preserved on the returned object so downstream code (or re-export
+ * via the canonical document) still sees the theme reference.
+ */
+
+import type {
+  CanonicalRunFormatting,
+  ResolvedTheme,
+  StylesCatalog,
+} from "../model/canonical-document.ts";
+import { resolveThemeColor } from "../io/ooxml/parse-theme.ts";
+import { resolveThemeColorHex } from "./theme-color-resolver.ts";
+import {
+  resolveEffectiveRunFormatting,
+  type RunResolveInput,
+} from "./paragraph-style-resolver.ts";
+
+export const HYPERLINK_CHARACTER_STYLE_ID = "Hyperlink";
+
+/**
+ * Microsoft Word's default hyperlink color (applied when neither the
+ * Hyperlink character style nor the theme's `hlink` slot supplies one).
+ * Matches Word 2013+ fresh-document rendering.
+ */
+export const DEFAULT_HYPERLINK_COLOR_HEX = "0563C1";
+
+/**
+ * Resolve effective run formatting for a hyperlink-inner run. Honors the
+ * Hyperlink character style implicitly, resolves any theme-slot color
+ * references, and applies the Word-default fallback when upstream data
+ * is absent.
+ *
+ * `input.characterStyleId` is respected when the caller already passed
+ * one (e.g., source XML had an explicit `<w:rStyle>` overriding the
+ * implicit Hyperlink). Only when it is absent does the resolver inject
+ * `"Hyperlink"` itself.
+ */
+export function resolveHyperlinkRunFormatting(
+  input: RunResolveInput,
+  catalog: StylesCatalog | undefined,
+  theme: ResolvedTheme | undefined,
+): CanonicalRunFormatting {
+  // V7a — auto-apply the Hyperlink character style when the caller did
+  // not supply one (runs inside <w:hyperlink> typically lack explicit
+  // rStyle; Word applies the style by context).
+  const augmentedInput: RunResolveInput =
+    input.characterStyleId === undefined
+      ? { ...input, characterStyleId: HYPERLINK_CHARACTER_STYLE_ID }
+      : input;
+
+  const cascade = resolveEffectiveRunFormatting(augmentedInput, catalog);
+
+  // V7b — concretize the color through the theme resolver + Word default.
+  const resolvedColor = resolveHyperlinkColorHex(cascade, theme);
+  if (resolvedColor && resolvedColor !== cascade.colorHex) {
+    return { ...cascade, colorHex: resolvedColor };
+  }
+  return cascade;
+}
+
+/**
+ * Four-tier hyperlink color fallback. Exported for targeted testing; use
+ * `resolveHyperlinkRunFormatting` as the primary entry point.
+ */
+export function resolveHyperlinkColorHex(
+  cascade: Pick<
+    CanonicalRunFormatting,
+    "colorHex" | "colorThemeSlot" | "colorThemeTint" | "colorThemeShade"
+  >,
+  theme: ResolvedTheme | undefined,
+): string | undefined {
+  // Tier 1 — direct non-auto hex wins.
+  if (cascade.colorHex && cascade.colorHex !== "auto") {
+    return cascade.colorHex;
+  }
+  // Tier 2 — theme-slot reference from the cascade (which now includes the
+  // Hyperlink style's rPr — typically `<w:color w:themeColor="hlink"/>`).
+  if (cascade.colorThemeSlot) {
+    const viaTheme = resolveThemeColorHex(cascade, theme);
+    if (viaTheme && viaTheme !== "auto") {
+      return viaTheme;
+    }
+  }
+  // Tier 3 — theme hlink slot even when the cascade never wrote a slot
+  // reference. This catches docs whose Hyperlink style lacks a color
+  // declaration entirely but whose theme defines hlink.
+  const themeHlink = resolveThemeColor(theme, "hlink");
+  if (themeHlink) {
+    return themeHlink;
+  }
+  // Tier 4 — Word's hardcoded default.
+  return DEFAULT_HYPERLINK_COLOR_HEX;
+}