@beyondwork/docx-react-component 1.0.56 → 1.0.58

package/src/runtime/object-grab/index.ts

@@ -0,0 +1,51 @@
+/**
+ * R.3 ObjectGrabLayer — runtime-side grab state for inline / floating
+ * objects (images, shapes). Lane 6 P11 paints the chrome handles; this
+ * module owns the state model so both sides reference one source of truth.
+ *
+ * Design invariants:
+ * 1. **Single-select.** One grabbed object at a time (matches LibreOffice
+ *    `SwFEShell::SelectObj`); multi-select for Alt+Shift drag selection
+ *    lands in a follow-up once user flows require it.
+ * 2. **Local-only, not collab-broadcast.** A remote peer's grab state is
+ *    surfaced via remote-cursor awareness, not via this layer — each peer
+ *    has their own grab state, matching the text-selection model.
+ * 3. **Pure state transitions.** Every mutation returns a new object; the
+ *    runtime stores the state alongside selection and emits on snapshot.
+ * 4. **String ids, not node references.** Grab state uses `objectId` so
+ *    the state survives snapshot replacement. The runtime resolves the id
+ *    to the current node when it needs to dispatch image commands.
+ *
+ * What this module deliberately does NOT do in Item C:
+ *   - Rotation / anchor-mode / z-order mutation — those are image.set-*
+ *     commands on the existing `image-commands.ts` module; the grab layer
+ *     is just "which object has focus". Host wires chrome interactions to
+ *     those commands via the ref methods.
+ *   - Hit-testing — chrome layer uses Lane 3a P9 `RenderAnchorIndex` to
+ *     convert click coords to an object id, then calls `selectObject(id)`.
+ */
+
+export interface ObjectGrabState {
+  /** The grabbed object's stable id (image.mediaId / shape.shapeId), or null. */
+  objectId: string | null;
+}
+
+export function createObjectGrabState(): ObjectGrabState {
+  return { objectId: null };
+}
+
+export function selectObject(state: ObjectGrabState, objectId: string): ObjectGrabState {
+  if (state.objectId === objectId) {
+    return state; // idempotent — same id, same state (reference-equal)
+  }
+  return { objectId };
+}
+
+export function deselectObject(state: ObjectGrabState): ObjectGrabState {
+  if (state.objectId === null) return state;
+  return { objectId: null };
+}
+
+export function getGrabbedObject(state: ObjectGrabState): string | null {
+  return state.objectId;
+}

package/src/runtime/paragraph-style-resolver.ts

@@ -11,11 +11,13 @@
  */
 
 import type {
+  CanonicalFontTable,
   CanonicalParagraphFormatting,
   CanonicalRunFormatting,
   CharacterStyleDefinition,
   ParagraphStyleDefinition,
   StylesCatalog,
+  TableStyleDefinition,
 } from "../model/canonical-document.ts";
 
 export function resolveParagraphStyleChain(
@@ -192,3 +194,106 @@ export function resolveNumberingMarkerRunFormatting(
   acc = mergeRun(acc, input.levelRunProperties);
   return acc ?? {};
 }
+
+/**
+ * Return the `w:next` style ID for `styleId` — the paragraph style Word
+ * applies after pressing Enter at the end of a paragraph of this style.
+ * Used by Lane 1's suggest-paragraph-split command.
+ */
+export function getNextStyleId(
+  styleId: string,
+  catalog: StylesCatalog | undefined,
+): string | undefined {
+  return catalog?.paragraphs[styleId]?.nextStyle;
+}
+
+/**
+ * Resolve the effective font family name for a run.
+ *
+ * Walks the ECMA-376 §17.3.2.26 precedence for `<w:rFonts>`: `ascii` →
+ * `hAnsi` → `eastAsia` → `cs`. When none of those resolve on the direct
+ * run formatting, layers the paragraph/character style cascade for the
+ * same four fields, then falls back to the caller-supplied
+ * `themeMinorFont` (ECMA-376 default for body text).
+ *
+ * `fontTable`, when supplied, is consulted only for presence — an entry
+ * whose `w:name` does not appear in `fontTable.fonts` is still returned
+ * as-is (Word behavior: substitute at render time, not at model resolve).
+ * Lane 3a's measurement backend owns the substitution decision.
+ *
+ * Returns undefined only when no source in the cascade supplies a family
+ * name (rare — production docs always hit docDefaults or the theme).
+ */
+export function resolveRunFontFamily(
+  input: RunResolveInput,
+  catalog: StylesCatalog | undefined,
+  themeMinorFont: string | undefined,
+  fontTable?: CanonicalFontTable | undefined,
+): string | undefined {
+  // `fontTable` is currently unused inside this resolver; the ECMA-376
+  // rFonts precedence does not require consulting the package's fontTable
+  // to pick a name. It is reserved so Lane 3a's measurement backend can
+  // layer substitution (e.g. pick a monospace fallback when the resolved
+  // name has `pitch === "fixed"`) by threading the same table through.
+  void fontTable;
+  const resolved = resolveEffectiveRunFormatting(input, catalog);
+  const name =
+    resolved.fontFamilyAscii ??
+    resolved.fontFamilyHAnsi ??
+    resolved.fontFamilyEastAsia ??
+    resolved.fontFamilyCs ??
+    resolved.fontFamily ??
+    themeMinorFont;
+  return name;
+}
+
+function resolveTableStyleChain(
+  styleId: string,
+  catalog: StylesCatalog | undefined,
+): TableStyleDefinition[] {
+  const chain: TableStyleDefinition[] = [];
+  if (!catalog) return chain;
+  const visited = new Set<string>();
+  let current: string | undefined = styleId;
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    const def: TableStyleDefinition | undefined = catalog.tables[current];
+    if (!def) break;
+    chain.push(def);
+    current = def.basedOn;
+  }
+  return chain;
+}
+
+/**
+ * Resolve the paragraph + run formatting that applies to a cell's body text
+ * when only the table style is known (no cell-paragraph-level overrides).
+ *
+ * Cascade (lowest to highest priority):
+ *   1. `catalog.docDefaults.paragraph` / `.run`
+ *   2. Table style's `basedOn` chain, walked root-to-leaf, projecting each
+ *      style's `formatting.paragraphProperties` / `.runProperties`.
+ *
+ * Conditional-region pPr/rPr (`<w:tblStylePr w:type="...">`) is intentionally
+ * NOT layered here — callers that need region-aware cell-text cascade must
+ * extend this once the conditional region parser captures pPr/rPr (Lane 3a
+ * follow-up). Per-paragraph and per-run formatting from the cell's content
+ * is layered by `resolveEffectiveParagraphFormatting` /
+ * `resolveEffectiveRunFormatting`; this function only returns the floor.
+ */
+export function resolveTableCellTextFormatting(
+  tableStyleId: string | undefined,
+  catalog: StylesCatalog | undefined,
+): { paragraph: CanonicalParagraphFormatting; run: CanonicalRunFormatting } {
+  let paragraph: CanonicalParagraphFormatting | undefined = catalog?.docDefaults?.paragraph;
+  let run: CanonicalRunFormatting | undefined = catalog?.docDefaults?.run;
+  if (catalog && tableStyleId) {
+    const chain = resolveTableStyleChain(tableStyleId, catalog);
+    for (let i = chain.length - 1; i >= 0; i -= 1) {
+      const formatting = chain[i]!.formatting;
+      paragraph = mergeParagraph(paragraph, formatting?.paragraphProperties);
+      run = mergeRun(run, formatting?.runProperties);
+    }
+  }
+  return { paragraph: paragraph ?? {}, run: run ?? {} };
+}

package/src/runtime/query-scopes.ts

@@ -0,0 +1,186 @@
+import type {
+  EditorStoryTarget,
+  ScopeQueryFilter,
+  ScopeQueryResult,
+  WorkflowMetadataEntry,
+  WorkflowOverlay,
+  WorkflowScope,
+  WorkflowWorkItem,
+} from "../api/public-types.ts";
+import type { CanonicalDocument } from "../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+import { collectScopeLocations } from "./scope-resolver.ts";
+
+function storyTargetsEqual(a: EditorStoryTarget, b: EditorStoryTarget): boolean {
+  if (a.kind !== b.kind) return false;
+  switch (a.kind) {
+    case "main":
+      return true;
+    case "header":
+    case "footer":
+      return (
+        a.relationshipId === (b as typeof a).relationshipId &&
+        a.variant === (b as typeof a).variant &&
+        a.sectionIndex === (b as typeof a).sectionIndex
+      );
+    case "footnote":
+    case "endnote":
+      return a.noteId === (b as typeof a).noteId;
+  }
+}
+
+const MAIN_STORY: EditorStoryTarget = { kind: "main" };
+
+export interface ScopeQueryInputs {
+  readonly overlay: WorkflowOverlay | null;
+  readonly entries: readonly WorkflowMetadataEntry[];
+  readonly document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope;
+}
+
+/**
+ * Phase C §C2 helper — project an ordered list of scopeIds (already produced
+ * by a geometric walk like `findAllScopesAt` / `findScopesIntersecting`)
+ * into `ScopeQueryResult[]`. Preserves incoming order. Filters out scopeIds
+ * that are not in the overlay (e.g. orphan markers). Applies the §C8
+ * visibility filter via `includeHidden` / `includeInvisible`.
+ */
+export function projectScopeQueryResults(
+  inputs: ScopeQueryInputs,
+  scopeIds: readonly string[],
+  options: { includeHidden?: boolean; includeInvisible?: boolean } = {},
+): ScopeQueryResult[] {
+  const overlay = inputs.overlay;
+  if (!overlay) return [];
+  const includeHidden = options.includeHidden === true;
+  const includeInvisible = options.includeInvisible === true;
+
+  const scopesById = new Map<string, WorkflowScope>();
+  for (const scope of overlay.scopes) scopesById.set(scope.scopeId, scope);
+
+  const entriesByScope = new Map<string, WorkflowMetadataEntry[]>();
+  for (const entry of inputs.entries) {
+    if (!entry.scopeId) continue;
+    let list = entriesByScope.get(entry.scopeId);
+    if (!list) {
+      list = [];
+      entriesByScope.set(entry.scopeId, list);
+    }
+    list.push(entry);
+  }
+
+  const workItemsById = new Map<string, WorkflowWorkItem>();
+  for (const item of overlay.workItems ?? []) {
+    workItemsById.set(item.workItemId, item);
+  }
+
+  const results: ScopeQueryResult[] = [];
+  for (const scopeId of scopeIds) {
+    const scope = scopesById.get(scopeId);
+    if (!scope) continue;
+    const visibility = (scope as WorkflowScope & { visibility?: string }).visibility;
+    if (visibility === "hidden" && !includeHidden) continue;
+    if (visibility === "invisible" && !includeInvisible) continue;
+    const entries = entriesByScope.get(scopeId) ?? [];
+    const workItem = scope.workItemId
+      ? workItemsById.get(scope.workItemId) ?? null
+      : null;
+    results.push({ scope, entries, workItem });
+  }
+  return results;
+}
+
+/**
+ * Pure §C1 projector — filter + join scopes with entries + workItem, ordered
+ * by start-marker document position (scopeId ASC tiebreak). Snapshot-based;
+ * no runtime state mutation.
+ */
+export function queryScopes(
+  inputs: ScopeQueryInputs,
+  filter: ScopeQueryFilter | undefined,
+): ScopeQueryResult[] {
+  const overlay = inputs.overlay;
+  if (!overlay) return [];
+
+  const normalizedStoryFilter = filter?.storyTarget ?? MAIN_STORY;
+  const workItemIdSet = filter?.workItemIds ? new Set(filter.workItemIds) : null;
+  const modeSet = filter?.modes ? new Set(filter.modes) : null;
+  const domainSet = filter?.domains ? new Set(filter.domains) : null;
+  const labelPrefix = filter?.labelPrefix?.toLowerCase();
+  const metadataId = filter?.metadataId;
+  const hasValue = filter?.hasValue;
+  const limit = filter?.limit;
+  const includeHidden = filter?.includeHidden === true;
+  const includeInvisible = filter?.includeInvisible === true;
+
+  const entriesByScope = new Map<string, WorkflowMetadataEntry[]>();
+  for (const entry of inputs.entries) {
+    if (!entry.scopeId) continue;
+    let list = entriesByScope.get(entry.scopeId);
+    if (!list) {
+      list = [];
+      entriesByScope.set(entry.scopeId, list);
+    }
+    list.push(entry);
+  }
+
+  const workItemsById = new Map<string, WorkflowWorkItem>();
+  for (const item of overlay.workItems ?? []) {
+    workItemsById.set(item.workItemId, item);
+  }
+
+  const locations = collectScopeLocations(inputs.document);
+
+  const candidates: Array<{ scope: WorkflowScope; startPos: number }> = [];
+  for (const scope of overlay.scopes) {
+    // §C8 pre-wire: respect visibility flags. Visibility field itself lands
+    // in §C8; treating missing as "visible" keeps this forward-compatible.
+    const visibility = (scope as WorkflowScope & { visibility?: string }).visibility;
+    if (visibility === "hidden" && !includeHidden) continue;
+    if (visibility === "invisible" && !includeInvisible) continue;
+
+    if (normalizedStoryFilter !== "*") {
+      const scopeStory = scope.storyTarget ?? MAIN_STORY;
+      if (!storyTargetsEqual(scopeStory, normalizedStoryFilter)) continue;
+    }
+    if (modeSet && !modeSet.has(scope.mode)) continue;
+    if (domainSet && !(scope.domain && domainSet.has(scope.domain))) continue;
+    if (workItemIdSet) {
+      if (!scope.workItemId || !workItemIdSet.has(scope.workItemId)) continue;
+    }
+    if (labelPrefix) {
+      const label = scope.label?.toLowerCase() ?? "";
+      if (!label.startsWith(labelPrefix)) continue;
+    }
+
+    const scopeEntries = entriesByScope.get(scope.scopeId) ?? [];
+
+    if (metadataId && !scopeEntries.some((e) => e.metadataId === metadataId)) continue;
+    if (hasValue) {
+      const anyMatch = scopeEntries.some(
+        (e) => e.value !== undefined && hasValue(e.value, e),
+      );
+      if (!anyMatch) continue;
+    }
+
+    const loc = locations.get(scope.scopeId);
+    const startPos =
+      loc?.startPos ?? loc?.endPos ?? Number.POSITIVE_INFINITY;
+    candidates.push({ scope, startPos });
+  }
+
+  candidates.sort((a, b) => {
+    if (a.startPos !== b.startPos) return a.startPos - b.startPos;
+    return a.scope.scopeId < b.scope.scopeId ? -1 : a.scope.scopeId > b.scope.scopeId ? 1 : 0;
+  });
+
+  const results: ScopeQueryResult[] = [];
+  for (const { scope } of candidates) {
+    if (limit !== undefined && results.length >= limit) break;
+    const entries = entriesByScope.get(scope.scopeId) ?? [];
+    const workItem = scope.workItemId
+      ? workItemsById.get(scope.workItemId) ?? null
+      : null;
+    results.push({ scope, entries, workItem });
+  }
+  return results;
+}

package/src/runtime/resolved-numbering-geometry.ts

@@ -12,16 +12,28 @@ import type {
 
 export const DEFAULT_NUMBERING_START_AT = 1;
 
+/**
+ * Resolved numbering geometry. **All numeric distance values are in OOXML
+ * twips (1/1440 in)** — the same unit `w:ind`/`w:tabs`/`w:spacing` carry on
+ * the parse side. Render consumers convert to display units at the boundary
+ * (`pt = twips / 20`, `px = twips × FRAME_PX_PER_TWIP_AT_96DPI`) — see
+ * `src/ui-tailwind/editor-surface/pm-schema.ts:331` and
+ * `tw-page-block-view.helpers.ts:179` for the canonical conversion sites.
+ * Do not pre-convert here; the runtime stays in OOXML units so cache keys
+ * and serializer round-trips stay byte-identical.
+ */
 export interface ResolvedNumberingGeometry {
   markerJustification?: NumberingLevelParagraphGeometry["justification"];
   spacing?: ParagraphSpacing;
   indentation?: ParagraphIndentation;
   tabStops?: TabStop[];
+  /** All fields in twips. */
   markerLane?: {
     start: number;
     width: number;
     textStart: number;
   };
+  /** All fields in twips. */
   textColumn?: {
     start: number;
     right?: number;

package/src/runtime/scope-resolver.ts

@@ -146,3 +146,63 @@ export function findScopeAt(
   }
   return best;
 }
+
+/**
+ * Phase C §C2 — every enclosing scope at `position`, ordered outermost →
+ * innermost (lowest startPos first; ties broken on scopeId ASC). Includes
+ * scopes that touch the position exactly (`startPos <= position <= endPos`).
+ * Companion to `findScopeAt`, which keeps the innermost-only contract.
+ */
+export function findAllScopesAt(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+  position: number,
+): ResolvedScopeLocation[] {
+  const locations = collectScopeLocations(document);
+  const hits: ResolvedScopeLocation[] = [];
+  for (const [scopeId, loc] of locations) {
+    if (loc.startPos === undefined || loc.endPos === undefined) continue;
+    if (position < loc.startPos || position > loc.endPos) continue;
+    hits.push({ scopeId, startPos: loc.startPos, endPos: loc.endPos });
+  }
+  hits.sort((a, b) => {
+    if (a.startPos !== b.startPos) return a.startPos - b.startPos;
+    return a.scopeId < b.scopeId ? -1 : a.scopeId > b.scopeId ? 1 : 0;
+  });
+  return hits;
+}
+
+/**
+ * Phase C §C2 — every scope whose marker range intersects `[rangeFrom,
+ * rangeTo]`. `mode: "overlap"` (default) accepts any intersection including
+ * touching endpoints; `mode: "contain"` requires the scope's entire marker
+ * range to lie within `[rangeFrom, rangeTo]`. Deterministic order: startPos
+ * ASC, scopeId ASC.
+ */
+export function findScopesIntersecting(
+  document: Pick<CanonicalDocument, "content"> | CanonicalDocumentEnvelope,
+  rangeFrom: number,
+  rangeTo: number,
+  mode: "overlap" | "contain" = "overlap",
+): ResolvedScopeLocation[] {
+  const from = Math.min(rangeFrom, rangeTo);
+  const to = Math.max(rangeFrom, rangeTo);
+  const locations = collectScopeLocations(document);
+  const hits: ResolvedScopeLocation[] = [];
+  for (const [scopeId, loc] of locations) {
+    if (loc.startPos === undefined || loc.endPos === undefined) continue;
+    const sFrom = Math.min(loc.startPos, loc.endPos);
+    const sTo = Math.max(loc.startPos, loc.endPos);
+    if (mode === "contain") {
+      if (sFrom < from || sTo > to) continue;
+    } else {
+      // overlap — any intersection including touching endpoints
+      if (sTo < from || sFrom > to) continue;
+    }
+    hits.push({ scopeId, startPos: loc.startPos, endPos: loc.endPos });
+  }
+  hits.sort((a, b) => {
+    if (a.startPos !== b.startPos) return a.startPos - b.startPos;
+    return a.scopeId < b.scopeId ? -1 : a.scopeId > b.scopeId ? 1 : 0;
+  });
+  return hits;
+}

package/src/runtime/selection/cursor-ops.ts

@@ -1,27 +1,27 @@
 /**
- * R.1 Phase 6a — SelectionLayer cursor primitives.
+ * R.1 SelectionLayer cursor primitives.
+ *
+ * Phase 6a (shipped) — layout-independent primitives over
+ * `(DocumentRootNode, CursorSelection, op) → CursorSelection` using the
+ * canonical story layer (`createPlainText(parseTextStory(doc))`) and
+ * `Intl.Segmenter` for word boundaries.
+ *
+ * Phase 6b (this module) — layout-aware primitives (`moveUp` / `moveDown` /
+ * `moveLineStart` / `moveLineEnd`) that consult a `RenderAnchorIndex` from
+ * Lane 3a P9 to resolve line boundaries. When no index is supplied the
+ * primitives degrade gracefully (see per-function docs).
  *
- * Pure functions over `(DocumentRootNode, CursorSelection, op) → CursorSelection`.
  * `extend: true` keeps the anchor fixed and moves only the head — the
  * LibreOffice `SwPaM` head/anchor split that matches Shift+arrow semantics.
  *
- * Positions are 0-based logical positions per the canonical story layer
- * (`createPlainText(parseTextStory(doc))`). Scope markers are zero-width;
- * paragraph breaks are 1 wide; text / tab / hard_break / image / opaque are 1
- * wide. The plain-text string produced by `createPlainText` is a 1:1 mapping
- * of those logical positions to characters, which makes position-math trivial
- * and makes `Intl.Segmenter` (for word boundaries) a drop-in fit.
- *
- * What this module deliberately does NOT ship yet:
- *   - `moveUp` / `moveDown` — genuinely layout-dependent (need column tracking
- *     + line-wrap info). Follows Phase 6b once Lane 3a P9 exposes the per-run
- *     layout facet needed for column-preserving movement.
- *   - `moveLineStart` / `moveLineEnd` — same; these need soft-wrap info that
- *     the canonical story layer does not expose.
+ * Positions are 0-based logical positions per the canonical story layer.
+ * Scope markers are zero-width; paragraph breaks are 1 wide; text / tab /
+ * hard_break / image / opaque are 1 wide.
  */
 
 import { createPlainText, parseTextStory } from "../../core/schema/text-schema.ts";
 import type { DocumentRootNode } from "../../model/canonical-document.ts";
+import type { RenderAnchorIndex, RenderFrameRect } from "../render/render-frame-types.ts";
 
 export interface CursorSelection {
   anchor: number;
@@ -35,6 +35,13 @@ export interface CursorMoveOptions {
    * anchor and head land at the new head, collapsing any range selection.
    */
   extend?: boolean;
+  /**
+   * R.1 Phase 6b — optional. Layout-aware primitives
+   * (`moveUp` / `moveDown` / `moveLineStart` / `moveLineEnd`) consult this
+   * index to resolve line boundaries via `byRuntimeOffset(offset)`. Absent
+   * in pure unit-test contexts; primitives degrade gracefully without it.
+   */
+  anchorIndex?: RenderAnchorIndex;
 }
 
 export function moveCharLeft(
@@ -148,6 +155,170 @@ export function moveWordLeft(
   return finalize(selection, prevBoundary, options);
 }
 
+// ─── Phase 6b — layout-aware primitives ────────────────────────────────────
+
+/**
+ * Move the head to the character on the next line at the nearest column X
+ * to the current head. Requires an anchor index; without one, this is a
+ * no-op (graceful degradation for pure unit-test contexts).
+ *
+ * Algorithm: probe the current head's rect for its `topPx` + `leftPx` (the
+ * anchor column). Scan forward through offsets; the first offset whose
+ * rect has a strictly-greater `topPx` marks the start of the next line.
+ * From that offset, continue while `topPx` matches the next-line top,
+ * tracking which offset has the smallest `|leftPx - anchorLeftPx|`.
+ */
+export function moveDown(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const index = options.anchorIndex;
+  if (!index) return finalize(selection, selection.head, options);
+
+  const text = documentPlainText(doc);
+  const startHead = options.extend
+    ? selection.head
+    : Math.max(selection.anchor, selection.head);
+  const currentRect = index.byRuntimeOffset(startHead);
+  if (!currentRect) return finalize(selection, startHead, options);
+
+  const anchorLeft = currentRect.leftPx;
+  const currentTop = currentRect.topPx;
+
+  // Find first offset with a different (higher) topPx.
+  let nextLineStart = -1;
+  let nextLineTop = Number.POSITIVE_INFINITY;
+  for (let i = startHead + 1; i <= text.length; i += 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r) continue;
+    if (r.topPx > currentTop) {
+      nextLineStart = i;
+      nextLineTop = r.topPx;
+      break;
+    }
+  }
+  if (nextLineStart < 0) return finalize(selection, startHead, options);
+
+  // Scan the next line for the offset with leftPx closest to anchorLeft.
+  let bestOffset = nextLineStart;
+  let bestDelta = Math.abs((index.byRuntimeOffset(nextLineStart)?.leftPx ?? 0) - anchorLeft);
+  for (let i = nextLineStart + 1; i <= text.length; i += 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r || r.topPx !== nextLineTop) break;
+    const delta = Math.abs(r.leftPx - anchorLeft);
+    if (delta < bestDelta) {
+      bestDelta = delta;
+      bestOffset = i;
+    }
+  }
+  return finalize(selection, bestOffset, options);
+}
+
+/** Mirror of `moveDown`, scanning upward. */
+export function moveUp(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const index = options.anchorIndex;
+  if (!index) return finalize(selection, selection.head, options);
+
+  const startHead = options.extend
+    ? selection.head
+    : Math.min(selection.anchor, selection.head);
+  const currentRect = index.byRuntimeOffset(startHead);
+  if (!currentRect) return finalize(selection, startHead, options);
+
+  const anchorLeft = currentRect.leftPx;
+  const currentTop = currentRect.topPx;
+
+  let prevLineEnd = -1;
+  let prevLineTop = Number.NEGATIVE_INFINITY;
+  for (let i = startHead - 1; i >= 0; i -= 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r) continue;
+    if (r.topPx < currentTop) {
+      prevLineEnd = i;
+      prevLineTop = r.topPx;
+      break;
+    }
+  }
+  if (prevLineEnd < 0) return finalize(selection, startHead, options);
+
+  let bestOffset = prevLineEnd;
+  let bestDelta = Math.abs((index.byRuntimeOffset(prevLineEnd)?.leftPx ?? 0) - anchorLeft);
+  for (let i = prevLineEnd - 1; i >= 0; i -= 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r || r.topPx !== prevLineTop) break;
+    const delta = Math.abs(r.leftPx - anchorLeft);
+    if (delta < bestDelta) {
+      bestDelta = delta;
+      bestOffset = i;
+    }
+  }
+  return finalize(selection, bestOffset, options);
+}
+
+/**
+ * Move the head to the first offset on the current visual line. Requires an
+ * anchor index; without one, collapses to document start (offset 0), which
+ * is a common keyboard fallback (matches "Home" at the start of an unwrapped
+ * document).
+ */
+export function moveLineStart(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const index = options.anchorIndex;
+  if (!index) return finalize(selection, 0, options);
+
+  const startHead = selection.head;
+  const currentRect = index.byRuntimeOffset(startHead);
+  if (!currentRect) return finalize(selection, startHead, options);
+
+  const currentTop = currentRect.topPx;
+  let lineStart = startHead;
+  for (let i = startHead - 1; i >= 0; i -= 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r) continue;
+    if (r.topPx !== currentTop) break;
+    lineStart = i;
+  }
+  return finalize(selection, lineStart, options);
+}
+
+/**
+ * Move the head to the last offset on the current visual line. Without an
+ * anchor index, collapses to document end.
+ */
+export function moveLineEnd(
+  doc: DocumentRootNode,
+  selection: CursorSelection,
+  options: CursorMoveOptions = {},
+): CursorSelection {
+  const text = documentPlainText(doc);
+  const index = options.anchorIndex;
+  if (!index) return finalize(selection, text.length, options);
+
+  const startHead = selection.head;
+  const currentRect = index.byRuntimeOffset(startHead);
+  if (!currentRect) return finalize(selection, startHead, options);
+
+  const currentTop = currentRect.topPx;
+  let lineEnd = startHead;
+  for (let i = startHead + 1; i <= text.length; i += 1) {
+    const r = index.byRuntimeOffset(i);
+    if (!r) continue;
+    if (r.topPx !== currentTop) break;
+    lineEnd = i;
+  }
+  return finalize(selection, lineEnd, options);
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
 function finalize(
   selection: CursorSelection,
   head: number,