@beyondwork/docx-react-component 1.0.106 → 1.0.109

package/src/api/v3/runtime/perf-probe.ts

@@ -0,0 +1,14 @@
+export {
+  finishPerfProbe,
+  getLatestPerfSummary,
+  incrementInvalidationCounter,
+  PREDICTED_LANE_COUNTERS,
+  recordPerfSample,
+  resetPerfProbeState,
+  startPerfProbe,
+} from "../../../runtime/telemetry/perf-probe.ts";
+export type {
+  PerfProbeKind,
+  PerfProbeSample,
+  PerfProbeSummary,
+} from "../../../runtime/telemetry/perf-probe.ts";

package/src/api/v3/runtime/viewport.ts

@@ -21,21 +21,22 @@
  * reads; `stateClass: "A-canonical"` + `persistsTo: "canonical"` — the
  * layout facet is derived canonical state.
  *
- * `elementId` stays `null` until L11's per-page content wrapper (coord-11
- * §19 / §P) lands with a stable `data-page-frame-start="page-<section>-<page>"`
- * id. Until then callers rely on `scrollY` / `pageRect` for positioning.
+ * `elementId` matches the stable per-page card anchor id that L11 paints on the
+ * page-card layer. Callers can prefer the element when mounted and fall back to
+ * `scrollY` / `pageRect` in headless or prerender paths.
  */
 
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import { DEFAULT_PX_PER_TWIP } from "../../public-types.ts";
+import { buildPageAnchorElementId } from "../_page-anchor-id.ts";
 
 /**
  * Resolves a 1-based page number to a stable scroll target.
  *
- * - `elementId`: DOM id L11 populates on the per-page content wrapper.
- *   Returns `null` while the L11 wrapper contract (coord-11 §19 / §P)
- *   is still in flight — callers fall back to `scrollY`.
+ * - `elementId`: DOM id L11 populates on the per-page card anchor.
+ *   Mounted callers can scroll/focus by element; headless callers still use
+ *   `scrollY`.
  * - `scrollY`: scroll-container-relative Y offset of the page's top
  *   edge in CSS px. Computed as the sum of prior pages' heights via
  *   the layout facet's page graph.
@@ -94,7 +95,7 @@ export const getPageAnchorMetadata: ApiV3FnMetadata = {
   stateClass: "A-canonical",
   persistsTo: "canonical",
   rwdReference:
-    "§Runtime API § runtime.viewport.getPageAnchor. Reads the kernel-authoritative page frame from `handle.geometry.getPage(index).frame` — same source `ui.viewport.scrollToPage(n)` consumes (coord-10 §γ shipment `b8116b97`), so values stay consistent across the two surfaces. `elementId` stays null until L11's per-page content wrapper (coord-11 §19 / §P) lands; until then callers position off `scrollY` / `pageRect`. Promotes to `live` when the geometry facet surfaces a direct `getPageAnchor(pageNumber)` reader or when elementId is populated.",
+    "§Runtime API § runtime.viewport.getPageAnchor. Reads the kernel-authoritative page frame from `handle.geometry.getPage(index).frame` — same source `ui.viewport.scrollToPage(n)` consumes (coord-10 §γ shipment `b8116b97`), so values stay consistent across the two surfaces. `elementId` is the stable L11 page-card anchor id; mounted callers can resolve it when the page-card layer is present and fall back to `scrollY` / `pageRect` otherwise. Promotes to `live` when the geometry facet surfaces a direct `getPageAnchor(pageNumber)` reader.",
 };
 
 /* ================================================================== */
@@ -145,7 +146,7 @@ export function createViewportFamily(runtime: RuntimeApiHandle) {
       const page = geometry?.getPage(pageIndex);
       if (!page) return null;
       return {
-        elementId: null,
+        elementId: buildPageAnchorElementId(page.pageId, pageIndex),
         scrollY: page.frame.topPx,
         pageRect: {
           left: page.frame.leftPx,

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

@@ -35,6 +35,14 @@ import type {
   WorkflowMarkupMode,
 } from "../../public-types.ts";
 import type { GeometryRect } from "../../../runtime/geometry/geometry-types.ts";
+import type {
+  WorkflowOverlayAnchorQuery,
+  WorkflowOverlayLaneEntry,
+  WorkflowOverlayLaneKind,
+  WorkflowOverlayLaneSnapshot,
+  WorkflowOverlayLaneSource,
+  WorkflowOverlayLaneStatus,
+} from "../../../runtime/workflow/overlay-lane-types.ts";
 import type {
   ChromeComposition,
   ChromeCompositionInput,
@@ -104,6 +112,15 @@ export interface UiController {
    * the scroll settles (or immediately for `behavior: "instant"`).
    */
   readonly dispatchScroll?: (target: ScrollTarget) => Promise<void>;
+  /**
+   * Object-drag lifecycle for mounted object handles. The bind-side owns the
+   * concrete mutation path (image resize/reposition today) and returns a
+   * session object with update/commit/cancel methods. Missing hook means the
+   * mounted surface has not wired object drag.
+   */
+  readonly beginObjectDrag?: (
+    input: UiObjectDragStartInput,
+  ) => UiObjectDragSession;
   /**
    * Viewport provider. Optional. Slice 2 reads viewport through this when
    * present; a geometry-backed path lands when `RuntimeApiHandle` gains a
@@ -202,6 +219,23 @@ export interface UiController {
   readonly subscribeChrome?: (
     listener: UiListener<ChromePosture>,
   ) => UiUnsubscribe;
+  /**
+   * KI-010 debug-inspector evidence lane read. Debug infra owns the
+   * evidence adapters; L10 owns the mounted UI API seam that exposes
+   * their plain snapshots without layout/cache ownership.
+   */
+  readonly getDebugEvidenceLane?: (
+    kind: UiDebugEvidenceLaneKind,
+  ) => UiDebugEvidenceLaneSnapshot;
+  /**
+   * KI-010 debug-inspector evidence lane subscription. Fan-out is UI
+   * state only; bind-side implementations must not dispatch PM
+   * transactions or invalidate L04 layout.
+   */
+  readonly subscribeDebugEvidenceLane?: (
+    kind: UiDebugEvidenceLaneKind,
+    listener: UiListener<UiDebugEvidenceLaneSnapshot>,
+  ) => UiUnsubscribe;
 }
 
 /**
@@ -296,10 +330,14 @@ export type ScrollTarget =
  *     that want to verify their own scroll container landed at the
  *     expected coordinate (visual-fidelity harness: deterministic
  *     per-page capture).
+ *   - `elementId` is the stable mounted page-card anchor id produced by
+ *     Layer 11. Mounted consumers can resolve it directly and fall back to
+ *     `scrollY` in headless / pre-mount paths.
  */
 export interface ScrollToPageResult {
   readonly actualPage: number;
   readonly scrollY: number;
+  readonly elementId: string;
 }
 
 export interface SelectionRangeInput {
@@ -309,71 +347,79 @@ export interface SelectionRangeInput {
 }
 
 /* ================================================================== */
-/*  Overlays — U4: anchor derivation from geometry                    */
+/*  Object drag — mounted object handles                              */
 /* ================================================================== */
 
-export type OverlayAnchorQuery =
-  | { kind: "block"; value: string }
-  | { kind: "scope"; value: string }
-  | { kind: "comment"; value: string }
-  | { kind: "revision"; value: string }
-  | { kind: "page"; value: number }
-  | { kind: "selection" };
+export type UiObjectDragHandle =
+  | "move"
+  | "rotate"
+  | "nw"
+  | "n"
+  | "ne"
+  | "w"
+  | "e"
+  | "sw"
+  | "s"
+  | "se";
+
+export interface UiObjectDragPoint {
+  readonly clientX: number;
+  readonly clientY: number;
+}
 
-/* ================================================================== */
-/*  PE2 overlay lanes                                                  */
-/* ================================================================== */
+export interface UiObjectDragStartInput extends UiObjectDragPoint {
+  readonly objectId: string;
+  readonly handle: UiObjectDragHandle;
+  readonly initialRect: GeometryRect;
+}
 
-export type UiOverlayLaneKind =
-  | "selection"
-  | "caret"
-  | "redlines"
-  | "field-scopes"
-  | "broad-scopes"
-  | "comments"
-  | "issues"
-  | "tables"
-  | "objects"
-  | "search"
-  | "presence";
-
-export type UiOverlayLaneStatus =
-  | "resolved"
-  | "requires-rehydration"
-  | "unavailable";
+export interface UiObjectDragUpdateInput extends Partial<UiObjectDragPoint> {
+  readonly deltaX?: number;
+  readonly deltaY?: number;
+}
 
-export type UiOverlayLaneSource =
-  | "geometry"
-  | "workflow"
-  | "search"
-  | "awareness"
-  | "controller"
-  | "unavailable";
+export interface UiObjectDragSnapshot {
+  readonly objectId: string;
+  readonly handle: UiObjectDragHandle;
+  readonly status: "active" | "committed" | "cancelled";
+  readonly deltaPx: { readonly x: number; readonly y: number };
+  readonly previewRect?: GeometryRect;
+}
 
-export interface UiOverlayLaneEntry {
-  readonly id: string;
-  readonly status: UiOverlayLaneStatus;
-  readonly anchor?: OverlayAnchorQuery;
-  readonly rects?: readonly GeometryRect[];
+export interface UiObjectDragCommitResult extends UiObjectDragSnapshot {
+  readonly changed: boolean;
   readonly reason?: string;
-  /**
-   * Lane-specific plain payload. Examples: peer identity for presence,
-   * issue severity, search rank, table/object classification. Kept plain
-   * so non-React consumers and debug runners can serialize snapshots.
-   */
-  readonly data?: Readonly<Record<string, unknown>>;
 }
 
-export interface UiOverlayLaneSnapshot {
-  readonly __mock?: true;
-  readonly kind: UiOverlayLaneKind;
-  readonly status: UiOverlayLaneStatus;
-  readonly entries: readonly UiOverlayLaneEntry[];
-  readonly revision: number;
-  readonly source: UiOverlayLaneSource;
-  readonly reason?: string;
+export interface UiObjectDragSession {
+  readonly id: string;
+  readonly objectId: string;
+  readonly handle: UiObjectDragHandle;
+  update(input: UiObjectDragUpdateInput): UiObjectDragSnapshot;
+  commit(input?: UiObjectDragUpdateInput): UiObjectDragCommitResult;
+  cancel(): UiObjectDragCommitResult;
 }
 
+/*  Overlays — U4: anchor derivation from geometry                    */
+/* ================================================================== */
+
+export type OverlayAnchorQuery = WorkflowOverlayAnchorQuery;
+
+/* ================================================================== */
+/*  PE2 overlay lanes                                                  */
+/* ================================================================== */
+
+/**
+ * L10 re-exports the plain PE2 overlay lane contract, but the canonical
+ * snapshot shape lives in Layer 6 workflow because durable review/workflow
+ * lanes are authored there and consumed by L10/L11.
+ */
+export type UiOverlayLaneKind = WorkflowOverlayLaneKind;
+export type UiOverlayLaneStatus = WorkflowOverlayLaneStatus;
+export type UiOverlayLaneSource = WorkflowOverlayLaneSource;
+export type UiOverlayLaneEntry = WorkflowOverlayLaneEntry;
+export type UiOverlayLaneSnapshot = WorkflowOverlayLaneSnapshot;
+
 /* ================================================================== */
 /*  Overlay visibility — U9 (state-classes X3)                        */
 /* ================================================================== */
@@ -463,6 +509,48 @@ export interface DebugAttachment {
   readonly detach: () => void;
 }
 
+export const UI_DEBUG_EVIDENCE_LANE_KINDS = [
+  "artifact-integrity",
+  "pe2-runtime-projection",
+  "visual-manifest",
+  "cross-oracle",
+  "overlay-invalidation",
+  "word-field-matrix",
+] as const;
+
+export type UiDebugEvidenceLaneKind =
+  typeof UI_DEBUG_EVIDENCE_LANE_KINDS[number];
+
+export type UiDebugEvidenceLaneStatus =
+  | "available"
+  | "requires-rehydration"
+  | "unavailable"
+  | "infra-blocked";
+
+export type UiDebugEvidenceLaneSource =
+  | "controller"
+  | "unavailable";
+
+export interface UiDebugEvidenceLaneEntry {
+  readonly id: string;
+  readonly status: UiDebugEvidenceLaneStatus;
+  readonly label?: string;
+  readonly source?: string;
+  readonly summary?: string;
+  readonly reason?: string;
+  readonly payload?: unknown;
+}
+
+export interface UiDebugEvidenceLaneSnapshot {
+  readonly __mock?: true;
+  readonly kind: UiDebugEvidenceLaneKind;
+  readonly status: UiDebugEvidenceLaneStatus;
+  readonly revision: number;
+  readonly source: UiDebugEvidenceLaneSource;
+  readonly entries: readonly UiDebugEvidenceLaneEntry[];
+  readonly reason?: string;
+}
+
 /* ================================================================== */
 /*  Subscription                                                      */
 /* ================================================================== */
@@ -485,6 +573,7 @@ export interface ApiV3UiSurface {
   setSelection(range: SelectionRangeInput): void;
   getViewport(): ViewportState;
   scrollTo(target: ScrollTarget): Promise<void>;
+  beginObjectDrag(input: UiObjectDragStartInput): UiObjectDragSession;
 }
 
 export interface ApiV3UiViewport {
@@ -510,7 +599,7 @@ export interface ApiV3UiViewport {
    * Scroll the mounted surface to a specific 1-based page number.
    * Resolves via `handle.geometry.getPage`; dispatches through the
    * bound controller's `dispatchScroll` hook. Returns the settled
-   * `{ actualPage, scrollY }` or `null` when geometry cannot resolve
+   * `{ actualPage, scrollY, elementId }` or `null` when geometry cannot resolve
    * any page / no controller bound / no dispatchScroll hook.
    * Clamps pageNumber to the document's valid range; `actualPage`
    * reflects the clamp. coord-10 §γ first-class replacement for the
@@ -680,6 +769,11 @@ export interface ApiV3UiChrome {
 export interface ApiV3UiDebug {
   attach(session: DebugSession): DebugAttachment;
   detach(): void;
+  getEvidenceLane(kind: UiDebugEvidenceLaneKind): UiDebugEvidenceLaneSnapshot;
+  subscribeEvidenceLane(
+    kind: UiDebugEvidenceLaneKind,
+    listener: UiListener<UiDebugEvidenceLaneSnapshot>,
+  ): UiUnsubscribe;
 }
 
 export interface UiScopeListFilter {

package/src/api/v3/ui/chrome-preset-model.ts

@@ -127,7 +127,7 @@ export function resolveChromeVisibilityForPreset(input: {
       pageChrome: true,
       statusBar: true,
       reviewRail: false,
-      shellHeader: true,
+      shellHeader: false,
     },
     advanced: {
       toolbar: true,
@@ -138,7 +138,7 @@ export function resolveChromeVisibilityForPreset(input: {
       pageChrome: true,
       statusBar: true,
       reviewRail: true,
-      shellHeader: true,
+      shellHeader: false,
     },
     review: {
       toolbar: true,
@@ -149,7 +149,7 @@ export function resolveChromeVisibilityForPreset(input: {
       pageChrome: true,
       statusBar: true,
       reviewRail: options.showReviewRail,
-      shellHeader: true,
+      shellHeader: false,
     },
     workflow: {
       toolbar: true,
@@ -160,7 +160,7 @@ export function resolveChromeVisibilityForPreset(input: {
       pageChrome: true,
       statusBar: true,
       reviewRail: options.showReviewRail,
-      shellHeader: true,
+      shellHeader: false,
     },
     collab: {
       toolbar: true,
@@ -171,7 +171,7 @@ export function resolveChromeVisibilityForPreset(input: {
       pageChrome: true,
       statusBar: true,
       reviewRail: options.showReviewRail,
-      shellHeader: true,
+      shellHeader: false,
     },
   };
 

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

@@ -12,7 +12,15 @@
  */
 
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
-import type { DebugSession, DebugAttachment } from "./_types.ts";
+import { emitUxResponse } from "../_ux-response.ts";
+import type {
+  DebugSession,
+  DebugAttachment,
+  UiDebugEvidenceLaneKind,
+  UiDebugEvidenceLaneSnapshot,
+  UiListener,
+  UiUnsubscribe,
+} from "./_types.ts";
 import type { UiApiContext } from "./_context.ts";
 
 export const attachMetadata: ApiV3FnMetadata = {
@@ -47,10 +55,82 @@ export const detachMetadata: ApiV3FnMetadata = {
     "§UI API § ui.debug.detach. Production-disabled companion no-op retained for defensive cleanup compatibility.",
 };
 
+export const getEvidenceLaneMetadata: ApiV3FnMetadata = {
+  name: "ui.debug.getEvidenceLane",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/debug-evidence-lanes.test.ts",
+    commit: "refactor-10-ki-010",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription:
+      "Unavailable UiDebugEvidenceLaneSnapshot with entries:[] and revision:0 when the mounted controller has not wired the requested debug evidence lane yet.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "session",
+    auditCategory: "ui-debug-evidence-read",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§UI API § KI-010 debug inspector evidence lanes. Reads a mounted controller-provided plain evidence lane snapshot for artifact integrity, PE2 runtime projection, visual manifest, cross-oracle, overlay invalidation, or Word-first field matrix evidence. Returns explicit status:'unavailable' when unwired; never dispatches PM transactions or invalidates layout.",
+};
+
+export const subscribeEvidenceLaneMetadata: ApiV3FnMetadata = {
+  name: "ui.debug.subscribeEvidenceLane",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/debug-evidence-lanes.test.ts",
+    commit: "refactor-10-ki-010",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta:
+      "debug evidence lane subscriber attached; future plain evidence snapshots propagate through the listener without PM document transactions or layout invalidation",
+  },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "session",
+    auditCategory: "ui-debug-evidence-subscribe",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  subscriptionShape: {
+    eventType: "ui.debug.evidence_lane_changed",
+    payloadType: "UiDebugEvidenceLaneSnapshot",
+    coalescing: "raf",
+  },
+  rwdReference:
+    "§UI API § KI-010 debug inspector evidence lanes. Adapter delegates to UiController.subscribeDebugEvidenceLane(kind, listener). Debug infra owns evidence adapters; L10 exposes only plain snapshots and subscription fan-out.",
+};
+
 const DEBUG_ATTACH_DISABLED_MESSAGE =
   "ui.debug.attach is disabled in production; use the runtime REPL keyboard shortcut instead.";
 
-export function createDebugFamily(_ctx: UiApiContext) {
+function unavailableEvidenceLane(
+  kind: UiDebugEvidenceLaneKind,
+): UiDebugEvidenceLaneSnapshot {
+  return {
+    __mock: true,
+    kind,
+    status: "unavailable",
+    revision: 0,
+    source: "unavailable",
+    entries: [],
+    reason: "debug evidence lane is unavailable until the mounted controller wires it",
+  };
+}
+
+export function createDebugFamily(ctx: UiApiContext) {
   return {
     attach(_session: DebugSession): DebugAttachment {
       throw new Error(DEBUG_ATTACH_DISABLED_MESSAGE);
@@ -58,5 +138,38 @@ export function createDebugFamily(_ctx: UiApiContext) {
     detach(): void {
       // Idempotent compatibility no-op.
     },
+    getEvidenceLane(kind: UiDebugEvidenceLaneKind): UiDebugEvidenceLaneSnapshot {
+      return ctx.binding?.controller.getDebugEvidenceLane?.(kind) ??
+        unavailableEvidenceLane(kind);
+    },
+    subscribeEvidenceLane(
+      kind: UiDebugEvidenceLaneKind,
+      listener: UiListener<UiDebugEvidenceLaneSnapshot>,
+    ): UiUnsubscribe {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.debug.subscribeEvidenceLane: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.subscribeDebugEvidenceLane) {
+        throw new Error(
+          `ui.debug.subscribeEvidenceLane: controller of kind "${controller.kind}" did not provide a subscribeDebugEvidenceLane hook`,
+        );
+      }
+      const unsubscribe = controller.subscribeDebugEvidenceLane(kind, listener);
+      emitUxResponse(ctx.handle, {
+        apiFn: subscribeEvidenceLaneMetadata.name,
+        intent: subscribeEvidenceLaneMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: subscribeEvidenceLaneMetadata.uxIntent.expectedDelta,
+        actualDelta: {
+          kind: "surface-refresh",
+          payload: { subscribed: "ui.debug.evidenceLane", lane: kind },
+        },
+      });
+      return unsubscribe;
+    },
   };
 }

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

@@ -6,6 +6,7 @@
  */
 
 export { createUiApi } from "./_create.ts";
+export { UI_DEBUG_EVIDENCE_LANE_KINDS } from "./_types.ts";
 export type {
   ApiV3Ui,
   ApiV3UiSession,
@@ -32,6 +33,13 @@ export type {
   ScrollTargetBehavior,
   ScrollToPageResult,
   SelectionRangeInput,
+  UiObjectDragCommitResult,
+  UiObjectDragHandle,
+  UiObjectDragPoint,
+  UiObjectDragSession,
+  UiObjectDragSnapshot,
+  UiObjectDragStartInput,
+  UiObjectDragUpdateInput,
   OverlayAnchorQuery,
   OverlayKind,
   OverlayVisibility,
@@ -46,6 +54,11 @@ export type {
   ChromeDebugMode,
   DebugSession,
   DebugAttachment,
+  UiDebugEvidenceLaneEntry,
+  UiDebugEvidenceLaneKind,
+  UiDebugEvidenceLaneSnapshot,
+  UiDebugEvidenceLaneSource,
+  UiDebugEvidenceLaneStatus,
   GeometryRect,
   UiOverlayLaneEntry,
   UiOverlayLaneKind,

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

@@ -207,13 +207,6 @@ export const getLaneMetadata: ApiV3FnMetadata = {
     runnerTest: "test/api/v3/ui/overlays-lanes.test.ts",
     commit: "refactor-10-pe2-overlay-lanes",
   },
-  mockShape: {
-    deterministic: true,
-    seededFrom: "fixed",
-    shapeDescription:
-      "Unavailable UiOverlayLaneSnapshot with entries:[] and revision:0 when the mounted controller has not wired the requested PE2 overlay lane yet.",
-    carriesMockFlag: true,
-  },
   uxIntent: { uiVisible: false },
   agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-overlays-lane-read" },
   stateClass: "C-local",
@@ -412,7 +405,6 @@ export function createOverlaysFamily(ctx: UiApiContext) {
     reason = "overlay lane is not wired on the active controller",
   ): UiOverlayLaneSnapshot {
     return {
-      __mock: true,
       kind,
       status: "unavailable",
       entries: Object.freeze([]),

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

@@ -24,6 +24,7 @@ import type { SelectionSnapshot } from "../../public-types.ts";
 import type {
   SelectionRangeInput,
   ScrollTarget,
+  UiObjectDragStartInput,
   ViewportState,
 } from "./_types.ts";
 import type { UiApiContext } from "./_context.ts";
@@ -105,6 +106,31 @@ export const scrollToMetadata: ApiV3FnMetadata = {
   rwdReference: "§UI API § ui.surface.scrollTo. Adapter delegates to UiController.dispatchScroll. Slice 3 adds geometry-backed target resolution for block/scope/comment/revision kinds prior to dispatch.",
 };
 
+export const beginObjectDragMetadata: ApiV3FnMetadata = {
+  name: "ui.surface.beginObjectDrag",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/object-drag.test.ts",
+    commit: "refactor-10-object-drag-lifecycle",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "object drag lifecycle starts for a mounted object handle",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "selection",
+    auditCategory: "ui-surface-object-drag",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  rwdReference:
+    "§UI API § object handles. Adapter delegates mounted object drag to UiController.beginObjectDrag; commit routes through host-owned runtime mutation and layout invalidation paths.",
+};
+
 export function createSurfaceFamily(ctx: UiApiContext) {
   return {
     getSelection(): SelectionSnapshot | null {
@@ -166,5 +192,35 @@ export function createSurfaceFamily(ctx: UiApiContext) {
         actualDelta: { kind: "surface-refresh", payload: { kind: target.kind, value: target.kind === "scope" || target.kind === "comment" || target.kind === "revision" || target.kind === "block" ? target.value : undefined } },
       });
     },
+    beginObjectDrag(input: UiObjectDragStartInput) {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.surface.beginObjectDrag: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.beginObjectDrag) {
+        throw new Error(
+          `ui.surface.beginObjectDrag: controller of kind "${controller.kind}" did not provide a beginObjectDrag hook`,
+        );
+      }
+      const session = controller.beginObjectDrag(input);
+      emitUxResponse(ctx.handle, {
+        apiFn: beginObjectDragMetadata.name,
+        intent: beginObjectDragMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: beginObjectDragMetadata.uxIntent.expectedDelta,
+        actualDelta: {
+          kind: "surface-refresh",
+          payload: {
+            objectId: input.objectId,
+            handle: input.handle,
+            sessionId: session.id,
+          },
+        },
+      });
+      return session;
+    },
   };
 }