@tarhnama/core 0.1.0

package/src/shortcuts.ts

@@ -0,0 +1,280 @@
+import { resolveFeatures, type OutlineFeatureName, type OutlineFeatures } from './features.js';
+
+/**
+ * The keyboard shortcuts, as DATA.
+ *
+ * A hard-coded `addKeyboardShortcuts` in the editor extension has three problems, and each
+ * one lands on a different person:
+ *
+ *   1. A host cannot CHANGE it. Every embedder inherits `Tab` and `Mod-.` whether those
+ *      collide with their own application or not — and `Tab` in particular is the web's
+ *      focus key, so an editor that eats it is one a keyboard user cannot leave.
+ *   2. A host cannot READ it. Rendering a shortcuts sheet means retyping the list by hand,
+ *      and the copy drifts from the bindings the moment either changes.
+ *   3. Nobody can turn it off, per binding or at all.
+ *
+ * So the table is plain serializable data — no closures, no editor reference — and the
+ * Tiptap extension is generated from it. A settings screen can render it, store it, diff
+ * it and hand back an override map.
+ */
+
+/** The commands a shortcut can be bound to. Names, not functions — see the note above. */
+export type ShortcutCommand =
+  | 'indent'
+  | 'outdent'
+  | 'setLevel1'
+  | 'setLevel2'
+  | 'setLevel3'
+  | 'setLevel4'
+  | 'setLevel5'
+  | 'setLevel6'
+  | 'setBodyText'
+  | 'toggleCollapse'
+  | 'collapseSiblings'
+  | 'insertZwnj'
+  | 'undo'
+  | 'redo'
+  | 'bold'
+  | 'italic'
+  | 'underline'
+  | 'strike'
+  | 'moveUp'
+  | 'moveDown';
+
+export interface ShortcutBinding {
+  readonly command: ShortcutCommand;
+  /** ProseMirror's spelling: `Mod-` is ⌘ on Apple and Ctrl elsewhere. */
+  readonly key: string;
+  /** For grouping in a help sheet. */
+  readonly group: 'structure' | 'collapse' | 'formatting' | 'editing' | 'persian';
+  /**
+   * The feature this binding belongs to, if any.
+   *
+   * Lets `features={{ collapse: false }}` drop `Mod-.` without the host having to know
+   * which key that was. A binding with no feature is structural and always survives —
+   * indent and outdent ARE the outline, not a feature of it.
+   */
+  readonly feature?: OutlineFeatureName;
+  /** Shown in a help sheet. English; a host translates via its own label pack. */
+  readonly description: string;
+}
+
+/**
+ * The defaults.
+ *
+ * `Mod-1…6` rather than 1…9: levels 7–9 exist in the model because Word documents contain
+ * them, but no keyboard has a comfortable ninth digit and the ladder covers the rest.
+ */
+export const DEFAULT_SHORTCUTS: readonly ShortcutBinding[] = [
+  { command: 'indent', key: 'Tab', group: 'structure', description: 'Indent block' },
+  { command: 'outdent', key: 'Shift-Tab', group: 'structure', description: 'Outdent block' },
+  { command: 'setLevel1', key: 'Mod-1', group: 'structure', description: 'Heading 1' },
+  { command: 'setLevel2', key: 'Mod-2', group: 'structure', description: 'Heading 2' },
+  { command: 'setLevel3', key: 'Mod-3', group: 'structure', description: 'Heading 3' },
+  { command: 'setLevel4', key: 'Mod-4', group: 'structure', description: 'Heading 4' },
+  { command: 'setLevel5', key: 'Mod-5', group: 'structure', description: 'Heading 5' },
+  { command: 'setLevel6', key: 'Mod-6', group: 'structure', description: 'Heading 6' },
+  { command: 'setBodyText', key: 'Mod-0', group: 'structure', description: 'Body text' },
+  { command: 'moveUp', key: 'Alt-ArrowUp', group: 'structure', description: 'Move block up' },
+  { command: 'moveDown', key: 'Alt-ArrowDown', group: 'structure', description: 'Move block down' },
+
+  {
+    command: 'toggleCollapse',
+    key: 'Mod-.',
+    group: 'collapse',
+    feature: 'collapse',
+    description: 'Collapse or expand this node',
+  },
+  {
+    command: 'collapseSiblings',
+    key: 'Mod-Shift-.',
+    group: 'collapse',
+    feature: 'collapse',
+    description: 'Collapse every sibling at this level',
+  },
+
+  {
+    command: 'bold',
+    key: 'Mod-b',
+    group: 'formatting',
+    feature: 'formatting',
+    description: 'Bold',
+  },
+  {
+    command: 'italic',
+    key: 'Mod-i',
+    group: 'formatting',
+    feature: 'formatting',
+    description: 'Italic',
+  },
+  {
+    command: 'underline',
+    key: 'Mod-u',
+    group: 'formatting',
+    feature: 'formatting',
+    description: 'Underline',
+  },
+  {
+    command: 'strike',
+    key: 'Mod-Shift-x',
+    group: 'formatting',
+    feature: 'formatting',
+    description: 'Strikethrough',
+  },
+
+  { command: 'undo', key: 'Mod-z', group: 'editing', feature: 'history', description: 'Undo' },
+  {
+    command: 'redo',
+    key: 'Mod-Shift-z',
+    group: 'editing',
+    feature: 'history',
+    description: 'Redo',
+  },
+
+  /**
+   * نیم‌فاصله. Not a convenience: this is how Persian compound words are written at all —
+   * می‌شود, نمی‌توان, دانش‌آموزان — and an editor without it cannot be used for real Persian.
+   */
+  {
+    command: 'insertZwnj',
+    key: 'Shift-Space',
+    group: 'persian',
+    description: 'Half-space (ZWNJ)',
+  },
+];
+
+const COMMANDS = new Set<string>(DEFAULT_SHORTCUTS.map((b) => b.command));
+
+export interface ShortcutOptions {
+  /** `false` binds nothing at all. */
+  readonly enabled?: boolean;
+  /**
+   * Rebind (`'Mod-Shift-c'`) or unbind (`null`) by command name.
+   *
+   * By command rather than by key, because the host knows what they want to move, not
+   * what it is currently bound to — and the current binding is exactly the thing they
+   * would have to keep in sync by hand.
+   */
+  readonly overrides?: Readonly<Partial<Record<ShortcutCommand, string | null>>>;
+  /** Bindings whose feature is off are dropped. */
+  readonly features?: Partial<OutlineFeatures> | readonly OutlineFeatureName[];
+}
+
+/**
+ * Apply a host's overrides and feature set to the default table.
+ *
+ * Collisions THROW. Letting a rebinding silently win means the losing command stops
+ * working with nothing logged, discoverable only by someone trying it and wondering what
+ * broke — and by then the override is somewhere in the host's configuration, far from the
+ * symptom.
+ */
+export function resolveShortcuts(options?: ShortcutOptions): readonly ShortcutBinding[] {
+  if (options?.enabled === false) return [];
+
+  const features = resolveFeatures(options?.features);
+  const overrides = options?.overrides ?? {};
+
+  for (const name of Object.keys(overrides)) {
+    if (!COMMANDS.has(name)) {
+      throw new Error(
+        `Unknown shortcut command ${JSON.stringify(name)}. Known: ${[...COMMANDS].join(', ')}.`,
+      );
+    }
+  }
+
+  const resolved: ShortcutBinding[] = [];
+  for (const binding of DEFAULT_SHORTCUTS) {
+    if (binding.feature !== undefined && !features[binding.feature]) continue;
+
+    const override = Object.hasOwn(overrides, binding.command)
+      ? overrides[binding.command]
+      : undefined;
+    // An explicit null unbinds; `undefined` means the host said nothing about it.
+    if (override === null) continue;
+    resolved.push(override === undefined ? binding : { ...binding, key: override });
+  }
+
+  /*
+   * Collisions are checked AFTER every override is applied, not while applying them, so
+   * that swapping two commands works in a single call. Checking as we go would reject
+   * `{ indent: null, toggleCollapse: 'Tab' }` depending on table order, which is a rule
+   * nobody could predict.
+   */
+  const seen = new Map<string, ShortcutCommand>();
+  for (const binding of resolved) {
+    const previous = seen.get(binding.key);
+    if (previous !== undefined) {
+      throw new Error(
+        `Shortcut collision on ${binding.key}: ${previous} and ${binding.command}. ` +
+          `Unbind one with { ${previous}: null }.`,
+      );
+    }
+    seen.set(binding.key, binding.command);
+  }
+
+  return resolved;
+}
+
+export interface ShortcutGroup {
+  readonly group: ShortcutBinding['group'];
+  readonly bindings: readonly ShortcutBinding[];
+}
+
+/** Stable group order for a help sheet — structure first, because it is the product. */
+const GROUP_ORDER: readonly ShortcutBinding['group'][] = [
+  'structure',
+  'collapse',
+  'formatting',
+  'editing',
+  'persian',
+];
+
+/**
+ * Group the live bindings for display.
+ *
+ * The order is fixed rather than derived from the data: a sheet that reshuffles between
+ * openings cannot be learned, and learning it is the only reason it exists.
+ */
+export function shortcutsFor(bindings: readonly ShortcutBinding[]): readonly ShortcutGroup[] {
+  return GROUP_ORDER.map((group) => ({
+    group,
+    bindings: bindings.filter((binding) => binding.group === group),
+  })).filter((entry) => entry.bindings.length > 0);
+}
+
+/** Which glyph set to render. Callers pass their own platform check. */
+export type ShortcutPlatform = 'apple' | 'other';
+
+const APPLE_GLYPHS: Readonly<Record<string, string>> = {
+  Mod: '⌘',
+  Shift: '⇧',
+  Alt: '⌥',
+  Ctrl: '⌃',
+};
+
+const ARROWS: Readonly<Record<string, string>> = {
+  ArrowUp: '↑',
+  ArrowDown: '↓',
+  ArrowLeft: '←',
+  ArrowRight: '→',
+};
+
+/**
+ * A binding as a person reads it.
+ *
+ * `Mod` is ProseMirror's platform-agnostic spelling and must never reach a user: nobody
+ * has a Mod key. Apple users read glyphs with no separator, everyone else reads words
+ * joined by `+`, and getting that backwards is one of the small things that makes software
+ * feel foreign.
+ */
+export function formatShortcut(key: string, platform: ShortcutPlatform): string {
+  const parts = key.split('-');
+  const last = parts.pop() ?? '';
+  // A single letter is shown capitalised — `Mod-b` is written ⌘B on every key cap.
+  const final = ARROWS[last] ?? (last.length === 1 ? last.toUpperCase() : last);
+
+  if (platform === 'apple') {
+    return parts.map((part) => APPLE_GLYPHS[part] ?? part).join('') + final;
+  }
+  return [...parts.map((part) => (part === 'Mod' ? 'Ctrl' : part)), final].join('+');
+}

package/src/spine.ts

@@ -0,0 +1,214 @@
+import { ancestors, buildIndex, hasChildren, subtreeRange, visibleIndices } from './tree.js';
+import { BODY, type Blocks, type OutlineLevel, type TreeIndex } from './types.js';
+
+/**
+ * Operations behind the collapse spine.
+ *
+ * Collapse is the most-used interaction in the product and the mechanism the whole
+ * performance strategy rests on (a collapsed subtree is *unmounted*, never hidden), so its
+ * operations live together rather than scattered through `ops.ts`.
+ *
+ * All of them are pure and return the SAME list when nothing changed, like every other
+ * structural operation here — downstream memoization depends on it.
+ */
+
+/**
+ * How many blocks a heading would fold away.
+ *
+ * This is what the spine's scope line is a picture of, and what the count pill states. It
+ * excludes the heading itself: the question a reader is asking is "how much disappears if
+ * I click this", and the heading does not.
+ */
+export function subtreeSize(blocks: Blocks, blockId: string, index?: TreeIndex): number {
+  const at = blocks.findIndex((block) => block.id === blockId);
+  if (at === -1) return 0;
+  const [start, end] = subtreeRange(index ?? buildIndex(blocks), at);
+  return Math.max(0, end - start - 1);
+}
+
+/**
+ * Collapse or expand every sibling at one heading's level, within its parent.
+ *
+ * Bound to ⌥click. "Siblings" means blocks with the same parent AND the same level — not
+ * every block at that level in the document, which would fold unrelated branches the user
+ * cannot see and did not ask about.
+ *
+ * The clicked heading decides the direction for all of them: if it is open, they all
+ * close. Deriving each one independently would produce a checkerboard.
+ */
+export function collapseSiblings<C>(
+  blocks: Blocks<C>,
+  blockId: string,
+  collapsed?: boolean,
+): Blocks<C> {
+  const index = buildIndex(blocks);
+  const at = blocks.findIndex((block) => block.id === blockId);
+  if (at === -1) return blocks;
+
+  const level = blocks[at]?.level ?? BODY;
+  if (level === BODY) return blocks;
+  const parent = index.parent[at] ?? -1;
+
+  const target = collapsed ?? !(blocks[at]?.collapsed ?? false);
+  const wanted = new Set<number>();
+  for (let i = 0; i < blocks.length; i++) {
+    if ((blocks[i]?.level ?? BODY) !== level) continue;
+    if ((index.parent[i] ?? -1) !== parent) continue;
+    // A heading with nothing under it has no collapsed state worth setting.
+    if (!hasChildren(index, i)) continue;
+    wanted.add(i);
+  }
+
+  let changed = false;
+  const next = blocks.map((block, i) => {
+    if (!wanted.has(i) || (block.collapsed ?? false) === target) return block;
+    changed = true;
+    return { ...block, collapsed: target };
+  });
+  return changed ? next : blocks;
+}
+
+/**
+ * Open the tree down to `level`, closing everything deeper.
+ *
+ * Bound to ⌘⌥1…6 and to the ladder control. `level` 0 means "close everything" — every
+ * heading that governs a subtree folds; a level above the deepest heading means "open
+ * everything".
+ *
+ * Headings with no children are left alone: a collapsed flag on a leaf is invisible, and
+ * setting it would make the ladder's state depend on blocks the reader cannot see.
+ */
+export function openToLevel<C>(blocks: Blocks<C>, level: number): Blocks<C> {
+  const index = buildIndex(blocks);
+  let changed = false;
+
+  const next = blocks.map((block, i) => {
+    const blockLevel = block.level ?? BODY;
+    if (blockLevel === BODY || !hasChildren(index, i)) return block;
+    /*
+     * A heading AT the target level COLLAPSES: "open to level 2" means level-2 headings
+     * are the deepest thing visible, so their own children are folded away. The heading
+     * itself is still on screen — it is its subtree that closes.
+     */
+    const shouldCollapse = blockLevel >= level;
+    if ((block.collapsed ?? false) === shouldCollapse) return block;
+    changed = true;
+    return { ...block, collapsed: shouldCollapse };
+  });
+
+  return changed ? next : blocks;
+}
+
+/**
+ * Open a document as deep as a mounted-block budget allows.
+ *
+ * For a large import. A real 20,407-block book opened fully mounts every block — the cost the
+ * whole scale strategy exists to avoid (CLAUDE.md §2) — so it opens to the deepest level whose
+ * mounted window fits, and the ladder takes the reader further. Returns the SAME list when it
+ * already fits, stored collapse state included: an author's own folds are not overridden.
+ *
+ * Never shallower than level 1. Folding the top level away too would leave nothing on screen
+ * but the chapters' absence; one row per chapter is the floor, over budget or not.
+ */
+export function openToFit<C>(blocks: Blocks<C>, budget: number): Blocks<C> {
+  const mounted = (candidate: Blocks<C>) => visibleIndices(candidate, buildIndex(candidate)).length;
+  if (mounted(blocks) <= budget) return blocks;
+
+  for (let level = deepestParentLevel(blocks); level > 1; level--) {
+    const candidate = openToLevel(blocks, level);
+    if (mounted(candidate) <= budget) return candidate;
+  }
+  return openToLevel(blocks, 1);
+}
+
+/**
+ * The deepest level in the document that governs a subtree.
+ *
+ * The ladder offers rungs only for levels that exist: a document of H1s and H2s should not
+ * show six of them, because four of the buttons would do nothing.
+ */
+export function deepestParentLevel(blocks: Blocks): OutlineLevel {
+  const index = buildIndex(blocks);
+  let deepest = 0;
+  for (let i = 0; i < blocks.length; i++) {
+    const level = blocks[i]?.level ?? BODY;
+    if (level !== BODY && hasChildren(index, i) && level > deepest) deepest = level;
+  }
+  return deepest as OutlineLevel;
+}
+
+/**
+ * Which level the tree is currently open to, or null when the state is mixed.
+ *
+ * The ladder highlights a rung only when the document actually matches it. Reporting a
+ * best guess would leave the control lit while the tree says otherwise, and the user would
+ * stop trusting it.
+ */
+export function currentOpenLevel(blocks: Blocks): number | null {
+  const index = buildIndex(blocks);
+  let deepestOpen = 0;
+  let shallowestCollapsed = Number.POSITIVE_INFINITY;
+
+  for (let i = 0; i < blocks.length; i++) {
+    const block = blocks[i];
+    const level = block?.level ?? BODY;
+    if (level === BODY || !hasChildren(index, i)) continue;
+    if (block?.collapsed) shallowestCollapsed = Math.min(shallowestCollapsed, level);
+    else deepestOpen = Math.max(deepestOpen, level);
+  }
+
+  if (shallowestCollapsed === Number.POSITIVE_INFINITY) return deepestOpen + 1;
+  if (deepestOpen === 0) return 0;
+  // Consistent only when every open heading is shallower than every collapsed one.
+  return deepestOpen < shallowestCollapsed ? shallowestCollapsed : null;
+}
+
+/**
+ * Whether a block is inside a collapsed ancestor, and therefore not rendered.
+ *
+ * Needed by anything that wants to reveal a block: a scroll target that is currently
+ * unmounted has no geometry, so callers must open the way to it first.
+ */
+export function isHidden(blocks: Blocks, blockId: string): boolean {
+  const at = blocks.findIndex((block) => block.id === blockId);
+  if (at === -1) return false;
+  const index = buildIndex(blocks);
+  return ancestors(index, at).some((i) => blocks[i]?.collapsed === true);
+}
+
+/**
+ * Close everything except the path to one subtree, and the subtree itself.
+ *
+ * Frame 3a's node menu calls this «فقط این زیردرخت باز بماند». It is the one command that
+ * makes a 50,000-block document usable for a single afternoon's work: every other branch
+ * unmounts, so what is left on screen is exactly the part being written.
+ *
+ * The heading's ANCESTORS have to stay open too, or the isolated subtree would itself be
+ * inside a fold and the command would blank the document — the most obvious way to write
+ * this, and wrong.
+ *
+ * Other branches fold at EVERY depth, not just at their topmost heading. Stopping at the
+ * first fold leaves the old open state buried inside it, so re-opening that branch later
+ * spills exactly what the user had just asked to put away.
+ */
+export function isolateSubtree<C>(blocks: Blocks<C>, blockId: string): Blocks<C> {
+  const at = blocks.findIndex((block) => block.id === blockId);
+  if (at === -1) return blocks;
+
+  const index = buildIndex(blocks);
+  const [, end] = subtreeRange(index, at);
+  const open = new Set<number>(ancestors(index, at));
+  for (let i = at; i < end; i++) open.add(i);
+
+  let changed = false;
+  const next = blocks.map((block, i) => {
+    // A leaf's collapsed flag is invisible, so leave it exactly as it was.
+    if (!hasChildren(index, i)) return block;
+    const collapsed = !open.has(i);
+    if ((block.collapsed === true) === collapsed) return block;
+    changed = true;
+    return { ...block, collapsed };
+  });
+
+  return changed ? next : blocks;
+}

package/src/styles.ts

@@ -0,0 +1,201 @@
+import type { Block, Blocks, BlockFormat, NamedStyle, OutlineLevel } from './types.js';
+
+/**
+ * Named-style resolution.
+ *
+ * Word's model, reproduced exactly: a paragraph's effective formatting is its style's
+ * formatting, merged with the style that style is based on, and so on to the root, with
+ * the paragraph's own direct formatting winning over all of it. Getting the precedence
+ * backwards is invisible on most documents and catastrophic on the one where an author
+ * overrode a heading's spacing.
+ */
+
+/** Depth limit for `basedOn` walking. Real Word documents contain cycles. */
+const MAX_CHAIN = 32;
+
+/**
+ * The chain from `styleId` to its root, nearest first.
+ *
+ * Cycles are broken rather than trusted not to exist: `w:basedOn` pointing back into its
+ * own ancestry is a documented corruption in files produced by older converters, and a
+ * naive walk hangs on it.
+ */
+export function styleChain(
+  styleId: string | undefined,
+  styles: readonly NamedStyle[] | undefined,
+): NamedStyle[] {
+  if (!styleId || !styles || styles.length === 0) return [];
+  const byId = new Map(styles.map((style) => [style.id, style]));
+  const chain: NamedStyle[] = [];
+  const seen = new Set<string>();
+
+  let current = byId.get(styleId);
+  while (current && !seen.has(current.id) && chain.length < MAX_CHAIN) {
+    seen.add(current.id);
+    chain.push(current);
+    current = current.basedOn ? byId.get(current.basedOn) : undefined;
+  }
+  return chain;
+}
+
+/**
+ * A block's effective paragraph formatting: the style chain, then direct overrides.
+ *
+ * Merged field by field rather than by object spread of the whole chain, because a style
+ * that sets only `spaceAfterTwips` must not blank out an ancestor's `align`.
+ */
+export function effectiveFormat(
+  block: Block<unknown>,
+  styles: readonly NamedStyle[] | undefined,
+): BlockFormat {
+  const chain = styleChain(block.styleId, styles);
+  let out: BlockFormat = {};
+  // Root first, so a nearer style overrides a more distant one.
+  for (let i = chain.length - 1; i >= 0; i--) {
+    out = { ...out, ...definedOnly(chain[i]!.format) };
+  }
+  return { ...out, ...definedOnly(block.format) };
+}
+
+/** Run-level defaults a style contributes, resolved down its chain. */
+export function effectiveRunStyle(
+  styleId: string | undefined,
+  styles: readonly NamedStyle[] | undefined,
+): { font?: string; sizeHalfPt?: number; bold?: boolean; italic?: boolean; color?: string } {
+  const chain = styleChain(styleId, styles);
+  let out: Record<string, unknown> = {};
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const style = chain[i]!;
+    out = {
+      ...out,
+      ...definedOnly({
+        font: style.font,
+        sizeHalfPt: style.sizeHalfPt,
+        bold: style.bold,
+        italic: style.italic,
+        color: style.color,
+      }),
+    };
+  }
+  return out;
+}
+
+/**
+ * The outline level a style implies, from the nearest ancestor that states one.
+ *
+ * Returns `undefined` rather than 0 when nothing in the chain says: 0 is body text, a
+ * real answer, and defaulting to it would silently demote every heading whose style table
+ * failed to load.
+ */
+export function styleOutlineLevel(
+  styleId: string | undefined,
+  styles: readonly NamedStyle[] | undefined,
+): OutlineLevel | undefined {
+  for (const style of styleChain(styleId, styles)) {
+    if (style.outlineLevel !== undefined) return style.outlineLevel;
+  }
+  return undefined;
+}
+
+export interface StyleUsage {
+  readonly style: NamedStyle;
+  /** Blocks referencing this style directly. */
+  readonly count: number;
+  /** Of those, how many also carry direct formatting that overrides it. */
+  readonly overridden: number;
+}
+
+/**
+ * How many blocks each style governs.
+ *
+ * The number is what makes "redefine this style across the document" a decision rather
+ * than a gamble — "this changes 412 paragraphs" and "this changes 2" are different
+ * actions, and the UI cannot tell them apart without counting.
+ */
+export function styleUsage(
+  blocks: Blocks<unknown>,
+  styles: readonly NamedStyle[] | undefined,
+): StyleUsage[] {
+  if (!styles || styles.length === 0) return [];
+  const counts = new Map<string, { count: number; overridden: number }>();
+
+  for (const block of blocks) {
+    if (!block.styleId) continue;
+    const entry = counts.get(block.styleId) ?? { count: 0, overridden: 0 };
+    entry.count += 1;
+    if (block.format && Object.keys(definedOnly(block.format)).length > 0) entry.overridden += 1;
+    counts.set(block.styleId, entry);
+  }
+
+  return styles
+    .map((style) => ({
+      style,
+      count: counts.get(style.id)?.count ?? 0,
+      overridden: counts.get(style.id)?.overridden ?? 0,
+    }))
+    // Used styles first, then alphabetically — an unused style is still worth listing,
+    // because it is what an author reaches for next.
+    .sort((a, b) => b.count - a.count || a.style.name.localeCompare(b.style.name));
+}
+
+/**
+ * Redefine a style, and report what it touched.
+ *
+ * Returns the SAME document reference when nothing changed, as every structural op in
+ * this project does, so downstream memoization holds.
+ */
+export function redefineStyle(
+  styles: readonly NamedStyle[] | undefined,
+  styleId: string,
+  patch: Partial<Omit<NamedStyle, 'id'>>,
+): readonly NamedStyle[] | undefined {
+  if (!styles) return styles;
+  let changed = false;
+  const next = styles.map((style) => {
+    if (style.id !== styleId) return style;
+    const merged = { ...style, ...definedOnly(patch), format: { ...style.format, ...definedOnly(patch.format) } };
+    if (shallowEqual(merged, style) && shallowEqual(merged.format ?? {}, style.format ?? {})) {
+      return style;
+    }
+    changed = true;
+    return merged;
+  });
+  return changed ? next : styles;
+}
+
+/**
+ * Drop direct formatting from every block using a style, so the style governs again.
+ *
+ * This is what "reset to the style" means in Word, and it is the other half of redefining
+ * one: a redefinition has no visible effect on paragraphs whose direct formatting already
+ * overrides the field being changed.
+ */
+export function clearDirectFormat<C>(blocks: Blocks<C>, styleId: string): Blocks<C> {
+  let changed = false;
+  const next = blocks.map((block) => {
+    if (block.styleId !== styleId || !block.format) return block;
+    changed = true;
+    const { format: _dropped, ...rest } = block;
+    return rest as Block<C>;
+  });
+  return changed ? next : blocks;
+}
+
+/** Strip `undefined` values so a spread does not blank out an inherited field. */
+function definedOnly<T extends object>(value: T | undefined): Partial<T> {
+  if (!value) return {};
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry !== undefined) out[key] = entry;
+  }
+  return out as Partial<T>;
+}
+
+function shallowEqual(a: object, b: object): boolean {
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every(
+    (key) => (a as Record<string, unknown>)[key] === (b as Record<string, unknown>)[key],
+  );
+}