From 4e1fd200663f84dfb177035f6fc43e88bc22f5ef Mon Sep 17 00:00:00 2001
From: Shri H <shri.h@contractors.scale.com>
Date: Fri, 19 Jun 2026 11:12:59 +0100
Subject: [PATCH 1/2] feat(linked-styles): redefine named paragraph styles
 ("Update to match")
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a supported way to redefine a named paragraph style's run-level look
(font family, size, weight, color) so it updates live and survives .docx
export — the editor equivalent of Google Docs' "Update Heading 1 to match".

- editor.commands.updateLinkedStyle(styleId, formatting) rewrites the style
  across all three converter representations (linkedStyles definition,
  translatedLinkedStyles, word/styles.xml) under one snapshot/rollback; never
  throws.
- Read helpers: getLinkedStyleFormatting(styleId) and
  getEffectiveFormattingAtSelection().
- Repaint on every redefinition in both render modes — a linked-styles plugin
  meta signal (ProseMirror decorations) plus PresentationEditor.refreshLinkedStyles()
  (clears the FlowBlockCache and re-lays out the painted view).
- Styles dropdown gains a per-row "Update to match" (pencil) action.

Pure shape conversions are isolated in style-formatting.js. Covered by unit
tests (pure mappers) and integration tests (engine, command, helpers, repaint,
and export round-trip).
---
 .../v1/components/toolbar/LinkedStyle.test.js |  38 +++
 .../v1/components/toolbar/LinkedStyle.vue     |  51 +++-
 .../v1/components/toolbar/defaultItems.js     |  15 +
 .../presentation-editor/PresentationEditor.ts |  13 +
 .../extensions/linked-styles/linked-styles.js |  37 +++
 .../v1/extensions/linked-styles/plugin.js     |   9 +
 .../linked-styles/style-formatting.js         | 188 +++++++++++++
 .../linked-styles/style-formatting.test.js    | 145 ++++++++++
 .../linked-styles/update-linked-style.js      | 127 +++++++++
 .../linked-styles/update-linked-style.test.js | 263 ++++++++++++++++++
 10 files changed, 885 insertions(+), 1 deletion(-)
 create mode 100644 packages/super-editor/src/editors/v1/components/toolbar/LinkedStyle.test.js
 create mode 100644 packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.js
 create mode 100644 packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.test.js
 create mode 100644 packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.js
 create mode 100644 packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.test.js

diff --git a/packages/super-editor/src/editors/v1/components/toolbar/LinkedStyle.test.js b/packages/super-editor/src/editors/v1/components/toolbar/LinkedStyle.test.js
new file mode 100644
index 0000000000..9ca4b21559
--- /dev/null
+++ b/packages/super-editor/src/editors/v1/components/toolbar/LinkedStyle.test.js
@@ -0,0 +1,38 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { mount } from '@vue/test-utils';
+
+// Mock the extension helpers so the component can mount without a real editor.
+vi.mock('@extensions/linked-styles/index.js', () => ({
+  getQuickFormatList: () => [
+    { id: 'Normal', definition: { attrs: { name: 'Normal' }, styles: {} } },
+    { id: 'Heading1', definition: { attrs: { name: 'Heading 1' }, styles: {} } },
+  ],
+  generateLinkedStyleString: () => '',
+}));
+
+import LinkedStyle from './LinkedStyle.vue';
+
+describe('LinkedStyle dropdown', () => {
+  let wrapper;
+  beforeEach(() => {
+    wrapper = mount(LinkedStyle, { props: { editor: {}, selectedOption: 'Normal' } });
+  });
+
+  it('emits "select" with the style when a row name is clicked', async () => {
+    await wrapper.findAll('.style-name')[1].trigger('click');
+    const events = wrapper.emitted('select');
+    expect(events).toBeTruthy();
+    expect(events[0][0].id).toBe('Heading1');
+  });
+
+  it('emits "update" with the style when the row update action is clicked', async () => {
+    const updateBtn = wrapper.findAll('[data-item="btn-linkedStyles-update"]')[1];
+    expect(updateBtn.exists()).toBe(true);
+    await updateBtn.trigger('click');
+    const events = wrapper.emitted('update');
+    expect(events).toBeTruthy();
+    expect(events[0][0].id).toBe('Heading1');
+    // Clicking update must NOT also apply the style.
+    expect(wrapper.emitted('select')).toBeFalsy();
+  });
+});
diff --git a/packages/super-editor/src/editors/v1/components/toolbar/LinkedStyle.vue b/packages/super-editor/src/editors/v1/components/toolbar/LinkedStyle.vue
index 8487d98906..6745fa2bfb 100644
--- a/packages/super-editor/src/editors/v1/components/toolbar/LinkedStyle.vue
+++ b/packages/super-editor/src/editors/v1/components/toolbar/LinkedStyle.vue
@@ -3,7 +3,7 @@ import { computed, ref, onMounted } from 'vue';
 import { toolbarIcons } from './toolbarIcons.js';
 import { generateLinkedStyleString, getQuickFormatList } from '@extensions/linked-styles/index.js';
 
-const emit = defineEmits(['select']);
+const emit = defineEmits(['select', 'update']);
 const styleRefs = ref([]);
 const props = defineProps({
   editor: {
@@ -19,6 +19,10 @@ const select = (style) => {
   emit('select', style);
 };
 
+const update = (style) => {
+  emit('update', style);
+};
+
 const moveToNextStyle = (index) => {
   if (index === styleRefs.value.length - 1) {
     return;
@@ -78,21 +82,66 @@ onMounted(() => {
       >
         {{ style.definition.attrs.name }}
       </div>
+      <button
+        type="button"
+        class="style-update"
+        :title="`Update ${style.definition.attrs.name} to match selection`"
+        :aria-label="`Update ${style.definition.attrs.name} to match selection`"
+        data-item="btn-linkedStyles-update"
+        @click.stop="update(style)"
+      >
+        ✎
+      </button>
     </div>
   </div>
 </template>
 
 <style scoped>
+.style-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
 .style-name {
+  flex: 1;
+  min-width: 0;
   padding: 16px 10px;
   color: var(--sd-ui-dropdown-text, #47484a);
 }
 
+.style-item:hover {
+  background-color: var(--sd-ui-dropdown-hover-bg, #d8dee5);
+}
+
 .style-name:hover {
   background-color: var(--sd-ui-dropdown-hover-bg, #d8dee5);
   color: var(--sd-ui-dropdown-hover-text, #47484a);
 }
 
+.style-update {
+  flex-shrink: 0;
+  margin-right: 8px;
+  padding: 4px 8px;
+  border: none;
+  border-radius: 4px;
+  background: transparent;
+  color: var(--sd-ui-dropdown-text, #47484a);
+  font-size: 14px;
+  line-height: 1;
+  cursor: pointer;
+  visibility: hidden;
+}
+
+.style-item:hover .style-update,
+.style-update:focus {
+  visibility: visible;
+}
+
+.style-update:hover {
+  background-color: var(--sd-ui-active-bg, #c3cdd8);
+}
+
 .linked-style-buttons {
   display: flex;
   flex-direction: column;
diff --git a/packages/super-editor/src/editors/v1/components/toolbar/defaultItems.js b/packages/super-editor/src/editors/v1/components/toolbar/defaultItems.js
index bae87dc72f..ee1b00847c 100644
--- a/packages/super-editor/src/editors/v1/components/toolbar/defaultItems.js
+++ b/packages/super-editor/src/editors/v1/components/toolbar/defaultItems.js
@@ -1009,10 +1009,25 @@ export const makeDefaultItems = ({
             selectedLinkedStyle.value = style.id;
           };
 
+          // "Update <style> to match selection": redefine the named style's look
+          // from the current selection (Google-Docs behaviour). Goes straight to
+          // the editor command + helper rather than the toolbar's single-argument
+          // emitCommand path, since this takes (styleId, formatting).
+          const handleUpdate = (style) => {
+            closeDropdown(linkedStyles);
+            const editor = superToolbar.activeEditor;
+            if (!editor || !style?.id) return;
+            const formatting = editor.helpers?.linkedStyles?.getEffectiveFormattingAtSelection?.();
+            if (!formatting) return;
+            editor.commands?.updateLinkedStyle?.(style.id, formatting);
+            editor.view?.focus?.();
+          };
+
           return h('div', {}, [
             h(LinkedStyle, {
               editor: superToolbar.activeEditor,
               onSelect: handleSelect,
+              onUpdate: handleUpdate,
               selectedOption: selectedLinkedStyle.value,
             }),
           ]);
diff --git a/packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts b/packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts
index b076d00114..899f8b7ddc 100644
--- a/packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts
+++ b/packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts
@@ -3569,6 +3569,19 @@ export class PresentationEditor extends EventEmitter {
     this.#scheduleRerender();
   }
 
+  /**
+   * Re-render after a linked style's definition was redefined in place
+   * (e.g. "Update Heading 1 to match"). The document did not change, so the
+   * FlowBlockCache — keyed on node identity — would otherwise return stale
+   * blocks resolved against the old style. Clear it and re-layout, mirroring
+   * other non-edit render changes (see {@link setShowBookmarks}).
+   */
+  refreshLinkedStyles(): void {
+    this.#flowBlockCache?.clear();
+    this.#pendingDocChange = true;
+    this.#scheduleRerender();
+  }
+
   setShowFormattingMarks(showFormattingMarks: boolean): void {
     const next = !!showFormattingMarks;
     if (this.#layoutOptions.showFormattingMarks === next) return;
diff --git a/packages/super-editor/src/editors/v1/extensions/linked-styles/linked-styles.js b/packages/super-editor/src/editors/v1/extensions/linked-styles/linked-styles.js
index 7138f7e131..dce1c8a55d 100644
--- a/packages/super-editor/src/editors/v1/extensions/linked-styles/linked-styles.js
+++ b/packages/super-editor/src/editors/v1/extensions/linked-styles/linked-styles.js
@@ -4,6 +4,8 @@ import { applyLinkedStyleToTransaction, generateLinkedStyleString } from './help
 import { createLinkedStylesPlugin, LinkedStylesPluginKey } from './plugin.js';
 import { findParentNodeClosestToPos } from '@core/helpers';
 import { getResolvedParagraphProperties } from '@extensions/paragraph/resolvedPropertiesCache.js';
+import { updateLinkedStyleDefinition, readEffectiveRunFormatting } from './update-linked-style.js';
+import { definitionStylesToFormatting } from './style-formatting.js';
 
 /**
  * Style definition from Word document
@@ -104,6 +106,17 @@ export const LinkedStyles = Extension.create({
 
         return applyLinkedStyleToTransaction(tr, this.editor, style);
       },
+
+      /**
+       * Redefine a named paragraph style's look (Google-Docs "Update to match").
+       * @category Command
+       * @param {string} styleId - The style ID to redefine (e.g., 'Heading1')
+       * @param {Object} formatting - CapturedFormatting (bold, italic, underline, fontSizePt, fontFamily, colorHex)
+       * @example
+       * editor.commands.updateLinkedStyle('Heading1', { bold: true, fontSizePt: 28, colorHex: '1F3864' });
+       * @note Updates every paragraph using the style; never throws.
+       */
+      updateLinkedStyle: (styleId, formatting) => () => updateLinkedStyleDefinition(this.editor, styleId, formatting),
     };
   },
 
@@ -151,6 +164,30 @@ export const LinkedStyles = Extension.create({
         if (!style) return '';
         return generateLinkedStyleString(style);
       },
+
+      /**
+       * Read a named style's current run formatting as CapturedFormatting.
+       * @category Helper
+       * @param {string} styleId - The style ID to read
+       * @returns {Object|null} CapturedFormatting, or null when the style is unknown
+       * @example
+       * const fmt = editor.helpers.linkedStyles.getLinkedStyleFormatting('Heading1');
+       */
+      getLinkedStyleFormatting: (styleId) => {
+        const style = this.editor.helpers[this.name].getStyleById(styleId);
+        if (!style?.definition?.styles) return null;
+        return definitionStylesToFormatting(style.definition.styles);
+      },
+
+      /**
+       * Read the run formatting at the current selection as CapturedFormatting.
+       * @category Helper
+       * @returns {Object} CapturedFormatting describing the current selection
+       * @example
+       * const fmt = editor.helpers.linkedStyles.getEffectiveFormattingAtSelection();
+       * editor.commands.updateLinkedStyle('Heading1', fmt);
+       */
+      getEffectiveFormattingAtSelection: () => readEffectiveRunFormatting(this.editor),
     };
   },
 });
diff --git a/packages/super-editor/src/editors/v1/extensions/linked-styles/plugin.js b/packages/super-editor/src/editors/v1/extensions/linked-styles/plugin.js
index ddb9dc0361..8a6d5a3958 100644
--- a/packages/super-editor/src/editors/v1/extensions/linked-styles/plugin.js
+++ b/packages/super-editor/src/editors/v1/extensions/linked-styles/plugin.js
@@ -56,6 +56,15 @@ export const createLinkedStylesPlugin = (editor) => {
         if (editor.presentationEditor) {
           return { ...prev, decorations: DecorationSet.empty };
         }
+
+        // Redefinition signal: a style's definition was mutated in place (no doc
+        // change). Regenerate decorations from the current styles so the
+        // redefinition becomes visible without faking a document edit.
+        if (tr.getMeta(LinkedStylesPluginKey)?.stylesChanged) {
+          const styles = editor.converter?.linkedStyles || [];
+          return { ...prev, styles, decorations: generateDecorations(newEditorState, styles) };
+        }
+
         let decorations = prev.decorations || DecorationSet.empty;
 
         // Only regenerate decorations when styles are affected
diff --git a/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.js b/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.js
new file mode 100644
index 0000000000..aeae456836
--- /dev/null
+++ b/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.js
@@ -0,0 +1,188 @@
+// @ts-check
+// Pure conversions between a neutral CapturedFormatting shape and the
+// converter's flat `definition.styles` map. No editor/DOM/PM imports, so this
+// module is unit-testable in isolation.
+
+/**
+ * @typedef {Object} CapturedFormatting
+ * @property {boolean} bold
+ * @property {boolean} italic
+ * @property {boolean} underline
+ * @property {number|null} fontSizePt  Font size in points, or null when unset.
+ * @property {string|null} fontFamily
+ * @property {string|null} colorHex    Bare uppercase hex, no leading '#', or null.
+ */
+
+/**
+ * Normalise a colour value into bare uppercase 6-digit hex, or null.
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function normaliseHex(value) {
+  if (typeof value !== 'string') return null;
+  const hex = value.trim().replace(/^#/, '');
+  return /^[0-9a-fA-F]{6}$/.test(hex) ? hex.toUpperCase() : null;
+}
+
+/**
+ * Parse a font-size value ("16pt", "16", 16) into points, or null.
+ * @param {unknown} value
+ * @returns {number|null}
+ */
+export function parseFontSizePt(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value !== 'string') return null;
+  const raw = value.trim().match(/^(\d+(?:\.\d+)?)/)?.[1];
+  if (!raw) return null;
+  const pt = Number.parseFloat(raw);
+  return Number.isFinite(pt) ? pt : null;
+}
+
+/**
+ * Mutate the flat `definition.styles` map in place to reflect run-level
+ * formatting. Boolean marks are presence-keyed ({} when on, absent when off),
+ * matching the importer's shape. Block-level keys (spacing/indent/tabStops) are
+ * deliberately left untouched.
+ * @param {Record<string, any>} styles
+ * @param {CapturedFormatting} captured
+ */
+export function applyToDefinitionStyles(styles, captured) {
+  const setPresence = (key, on) => {
+    if (on) styles[key] = styles[key] ?? {};
+    else delete styles[key];
+  };
+  setPresence('bold', captured.bold);
+  setPresence('italic', captured.italic);
+  setPresence('underline', captured.underline);
+
+  if (captured.fontSizePt != null) styles['font-size'] = `${captured.fontSizePt}pt`;
+  else delete styles['font-size'];
+  if (captured.fontFamily) styles['font-family'] = captured.fontFamily;
+  else delete styles['font-family'];
+  if (captured.colorHex) styles.color = `#${captured.colorHex}`;
+  else delete styles.color;
+}
+
+/**
+ * Inverse of applyToDefinitionStyles: read a flat styles map into neutral fields.
+ * @param {Record<string, any>} styles
+ * @returns {CapturedFormatting}
+ */
+export function definitionStylesToFormatting(styles) {
+  const s = styles || {};
+  return {
+    bold: 'bold' in s,
+    italic: 'italic' in s,
+    underline: 'underline' in s,
+    fontSizePt: parseFontSizePt(s['font-size']),
+    fontFamily: typeof s['font-family'] === 'string' ? s['font-family'] : null,
+    colorHex: normaliseHex(s.color),
+  };
+}
+
+/**
+ * Mutate `translatedLinkedStyles.styles[styleId]` (representation #2) run channel
+ * in place. Font size is stored in OOXML half-points; font family is the
+ * ascii/hAnsi/cs triple. Block-level paragraphProperties are left untouched.
+ * @param {Record<string, any>} styleDef
+ * @param {CapturedFormatting} captured
+ */
+export function applyToTranslatedStyle(styleDef, captured) {
+  const run = { ...(styleDef.runProperties ?? {}) };
+  run.bold = captured.bold;
+  run.italic = captured.italic;
+  if (captured.underline) run.underline = run.underline ?? { value: 'single' };
+  else delete run.underline;
+  if (captured.fontSizePt != null) run.fontSize = Math.round(captured.fontSizePt * 2);
+  else delete run.fontSize;
+  if (captured.fontFamily) {
+    run.fontFamily = { ascii: captured.fontFamily, hAnsi: captured.fontFamily, cs: captured.fontFamily };
+  } else {
+    delete run.fontFamily;
+  }
+  if (captured.colorHex) run.color = { val: captured.colorHex };
+  else delete run.color;
+  styleDef.runProperties = run;
+}
+
+// --- word/styles.xml (representation #3) ------------------------------------
+// The parsed tree uses the SuperConverter element shape:
+//   { type: 'element', name: 'w:rPr', attributes: {}, elements: [ ...children ] }
+
+/**
+ * @typedef {Object} XmlElement
+ * @property {string} [type]
+ * @property {string} [name]
+ * @property {Record<string,string>} [attributes]
+ * @property {XmlElement[]} [elements]
+ */
+
+/** @param {XmlElement} parent @param {string} name @returns {XmlElement} */
+function ensureChild(parent, name) {
+  if (!parent.elements) parent.elements = [];
+  let child = parent.elements.find((el) => el.name === name);
+  if (!child) {
+    child = { type: 'element', name, attributes: {}, elements: [] };
+    parent.elements.push(child);
+  }
+  return child;
+}
+
+/** @param {XmlElement} parent @param {string} name */
+function removeChild(parent, name) {
+  if (!parent.elements) return;
+  parent.elements = parent.elements.filter((el) => el.name !== name);
+}
+
+/** @param {XmlElement} rpr @param {string} name @param {boolean} on */
+function setBooleanProp(rpr, name, on) {
+  if (on) ensureChild(rpr, name).attributes = {};
+  else removeChild(rpr, name);
+}
+
+/**
+ * Patch a single `w:style` element's `w:rPr` (run-level) to reflect the captured
+ * formatting, so the redefinition survives `.docx` export. Mutates in place.
+ * @param {XmlElement} styleEl
+ * @param {CapturedFormatting} captured
+ */
+export function patchStyleXmlElement(styleEl, captured) {
+  const rpr = ensureChild(styleEl, 'w:rPr');
+  setBooleanProp(rpr, 'w:b', captured.bold);
+  setBooleanProp(rpr, 'w:i', captured.italic);
+  if (captured.underline) ensureChild(rpr, 'w:u').attributes = { 'w:val': 'single' };
+  else removeChild(rpr, 'w:u');
+
+  if (captured.fontSizePt != null) {
+    const halfPoints = String(Math.round(captured.fontSizePt * 2));
+    ensureChild(rpr, 'w:sz').attributes = { 'w:val': halfPoints };
+    ensureChild(rpr, 'w:szCs').attributes = { 'w:val': halfPoints };
+  } else {
+    removeChild(rpr, 'w:sz');
+    removeChild(rpr, 'w:szCs');
+  }
+  if (captured.fontFamily) {
+    ensureChild(rpr, 'w:rFonts').attributes = {
+      'w:ascii': captured.fontFamily,
+      'w:hAnsi': captured.fontFamily,
+      'w:cs': captured.fontFamily,
+    };
+  } else {
+    removeChild(rpr, 'w:rFonts');
+  }
+  if (captured.colorHex) ensureChild(rpr, 'w:color').attributes = { 'w:val': captured.colorHex };
+  else removeChild(rpr, 'w:color');
+}
+
+/**
+ * Locate the `w:style` element with the given `w:styleId` inside the parsed
+ * `word/styles.xml` document. Returns undefined when not found.
+ * @param {XmlElement|undefined} stylesXml
+ * @param {string} styleId
+ * @returns {XmlElement|undefined}
+ */
+export function findStyleXmlElement(stylesXml, styleId) {
+  const root = stylesXml?.elements?.[0];
+  const styleEls = root?.elements?.filter((el) => el.name === 'w:style') ?? [];
+  return styleEls.find((el) => el.attributes?.['w:styleId'] === styleId);
+}
diff --git a/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.test.js b/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.test.js
new file mode 100644
index 0000000000..ebf0ba02c5
--- /dev/null
+++ b/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.test.js
@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'vitest';
+import {
+  applyToDefinitionStyles,
+  definitionStylesToFormatting,
+  parseFontSizePt,
+  normaliseHex,
+  patchStyleXmlElement,
+  findStyleXmlElement,
+  applyToTranslatedStyle,
+} from './style-formatting.js';
+
+describe('style-formatting (pure)', () => {
+  it('normaliseHex strips # and uppercases, rejects junk', () => {
+    expect(normaliseHex('#ff0000')).toBe('FF0000');
+    expect(normaliseHex('abcdef')).toBe('ABCDEF');
+    expect(normaliseHex('red')).toBeNull();
+  });
+
+  it('parseFontSizePt parses "20pt", "20", 20', () => {
+    expect(parseFontSizePt('20pt')).toBe(20);
+    expect(parseFontSizePt('20')).toBe(20);
+    expect(parseFontSizePt(20)).toBe(20);
+    expect(parseFontSizePt(undefined)).toBeNull();
+  });
+
+  it('applyToDefinitionStyles writes run-level keys and removes cleared ones', () => {
+    const styles = { bold: {} };
+    applyToDefinitionStyles(styles, {
+      bold: false,
+      italic: true,
+      underline: false,
+      fontSizePt: 18,
+      fontFamily: 'Arial',
+      colorHex: 'FF0000',
+    });
+    expect(styles.bold).toBeUndefined();
+    expect(styles.italic).toEqual({});
+    expect(styles['font-size']).toBe('18pt');
+    expect(styles['font-family']).toBe('Arial');
+    expect(styles.color).toBe('#FF0000');
+  });
+
+  it('applyToDefinitionStyles leaves block-level keys untouched', () => {
+    const styles = { spacing: { lineSpaceAfter: 10 }, indent: {}, tabStops: null };
+    applyToDefinitionStyles(styles, {
+      bold: true,
+      italic: false,
+      underline: false,
+      fontSizePt: 16,
+      fontFamily: null,
+      colorHex: null,
+    });
+    expect(styles.spacing).toEqual({ lineSpaceAfter: 10 });
+    expect(styles.indent).toEqual({});
+    expect(styles.tabStops).toBeNull();
+  });
+
+  it('definitionStylesToFormatting is the inverse of applyToDefinitionStyles', () => {
+    const styles = {};
+    const fmt = {
+      bold: true,
+      italic: false,
+      underline: true,
+      fontSizePt: 16,
+      fontFamily: 'Calibri',
+      colorHex: '2E74B5',
+    };
+    applyToDefinitionStyles(styles, fmt);
+    expect(definitionStylesToFormatting(styles)).toEqual(fmt);
+  });
+});
+
+describe('styles.xml patch (pure)', () => {
+  const fmt = (o) => ({
+    bold: false,
+    italic: false,
+    underline: false,
+    fontSizePt: null,
+    fontFamily: null,
+    colorHex: null,
+    ...o,
+  });
+
+  it('writes w:rPr children for the captured formatting (size in half-points)', () => {
+    const styleEl = {
+      type: 'element',
+      name: 'w:style',
+      attributes: { 'w:styleId': 'Heading1' },
+      elements: [{ type: 'element', name: 'w:pPr', elements: [] }],
+    };
+    patchStyleXmlElement(styleEl, fmt({ bold: true, fontSizePt: 20, fontFamily: 'Arial', colorHex: 'FF0000' }));
+    const rpr = styleEl.elements.find((e) => e.name === 'w:rPr');
+    expect(rpr).toBeTruthy();
+    // rPr must come after pPr (CT_Style order)
+    expect(styleEl.elements.findIndex((e) => e.name === 'w:rPr')).toBeGreaterThan(
+      styleEl.elements.findIndex((e) => e.name === 'w:pPr'),
+    );
+    expect(rpr.elements.find((e) => e.name === 'w:b')).toBeTruthy();
+    expect(rpr.elements.find((e) => e.name === 'w:sz')?.attributes['w:val']).toBe('40');
+    expect(rpr.elements.find((e) => e.name === 'w:szCs')?.attributes['w:val']).toBe('40');
+    expect(rpr.elements.find((e) => e.name === 'w:rFonts')?.attributes['w:ascii']).toBe('Arial');
+    expect(rpr.elements.find((e) => e.name === 'w:color')?.attributes['w:val']).toBe('FF0000');
+  });
+
+  it('removes cleared boolean props from w:rPr', () => {
+    const styleEl = {
+      type: 'element',
+      name: 'w:style',
+      attributes: { 'w:styleId': 'Heading1' },
+      elements: [{ type: 'element', name: 'w:rPr', elements: [{ type: 'element', name: 'w:b', attributes: {} }] }],
+    };
+    patchStyleXmlElement(styleEl, fmt({ bold: false }));
+    const rpr = styleEl.elements.find((e) => e.name === 'w:rPr');
+    expect(rpr.elements.find((e) => e.name === 'w:b')).toBeFalsy();
+  });
+
+  it('findStyleXmlElement locates a style by w:styleId', () => {
+    const xml = {
+      elements: [
+        {
+          name: 'w:styles',
+          elements: [
+            { type: 'element', name: 'w:style', attributes: { 'w:styleId': 'Normal' }, elements: [] },
+            { type: 'element', name: 'w:style', attributes: { 'w:styleId': 'Heading1' }, elements: [] },
+          ],
+        },
+      ],
+    };
+    expect(findStyleXmlElement(xml, 'Heading1')?.attributes['w:styleId']).toBe('Heading1');
+    expect(findStyleXmlElement(xml, 'Missing')).toBeUndefined();
+  });
+
+  it('applyToTranslatedStyle writes the run channel (half-points, font object)', () => {
+    const def = { styleId: 'Heading1', type: 'paragraph' };
+    applyToTranslatedStyle(
+      def,
+      fmt({ bold: true, underline: true, fontSizePt: 18, fontFamily: 'Georgia', colorHex: 'AA0000' }),
+    );
+    expect(def.runProperties.bold).toBe(true);
+    expect(def.runProperties.underline).toEqual({ value: 'single' });
+    expect(def.runProperties.fontSize).toBe(36);
+    expect(def.runProperties.fontFamily).toEqual({ ascii: 'Georgia', hAnsi: 'Georgia', cs: 'Georgia' });
+    expect(def.runProperties.color).toEqual({ val: 'AA0000' });
+  });
+});
diff --git a/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.js b/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.js
new file mode 100644
index 0000000000..bbcf89b619
--- /dev/null
+++ b/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.js
@@ -0,0 +1,127 @@
+// @ts-check
+import { LinkedStylesPluginKey } from './plugin.js';
+import {
+  applyToDefinitionStyles,
+  applyToTranslatedStyle,
+  findStyleXmlElement,
+  parseFontSizePt,
+  patchStyleXmlElement,
+  normaliseHex,
+} from './style-formatting.js';
+
+/** Deep-clone plain (JSON-serialisable) style data for snapshot/rollback. */
+const cloneData = (value) => JSON.parse(JSON.stringify(value));
+
+/**
+ * Repaint after a style's definition was mutated in place. A redefinition does
+ * not change the document, so the two render paths need distinct, non-document
+ * signals (neither mutates nodes, so neither re-enters the command's dispatch):
+ *
+ *  - Plain ProseMirror mode: dispatch a stepless meta transaction; the
+ *    linked-styles plugin regenerates its decorations from the updated styles.
+ *  - Layout/presentation mode: PM decorations are unused (the layout engine
+ *    paints from a FlowBlockCache keyed on node identity, which a definition
+ *    change does not invalidate). Ask the PresentationEditor to clear that cache
+ *    and re-render — the same mechanism used by other non-edit render changes
+ *    (e.g. show-bookmarks). Both signals are safe to fire; the inactive path
+ *    is a no-op. Never throws.
+ * @param {Object} editor
+ */
+function repaintStyle(editor) {
+  try {
+    const view = editor?.view;
+    if (view) view.dispatch(view.state.tr.setMeta(LinkedStylesPluginKey, { stylesChanged: true }));
+  } catch {
+    /* decoration repaint is best-effort */
+  }
+  try {
+    editor?.presentationEditor?.refreshLinkedStyles?.();
+  } catch {
+    /* layout repaint is best-effort */
+  }
+}
+
+/**
+ * Redefine a named paragraph style's run-level look across all three converter
+ * representations (live decoration source, translated layout, and the OOXML that
+ * survives export) and repaint. Snapshots every representation it touches and
+ * rolls all of them back on any failure. Never throws.
+ * @param {Object} editor
+ * @param {string} styleId
+ * @param {import('./style-formatting.js').CapturedFormatting} formatting
+ * @returns {boolean} true when the style was found and updated.
+ */
+export function updateLinkedStyleDefinition(editor, styleId, formatting) {
+  try {
+    const converter = editor?.converter;
+    const linkedStyles = converter?.linkedStyles;
+    if (!Array.isArray(linkedStyles) || !styleId) return false;
+    const entry = linkedStyles.find((s) => String(s?.id) === String(styleId));
+    if (!entry || entry.type !== 'paragraph') return false;
+
+    if (!entry.definition) entry.definition = { attrs: {}, styles: {} };
+    if (!entry.definition.styles) entry.definition.styles = {};
+
+    const translatedStyles = converter?.translatedLinkedStyles?.styles;
+    const stylesXml = converter?.convertedXml?.['word/styles.xml'];
+    const xmlEl = findStyleXmlElement(stylesXml, styleId);
+
+    const snapshot = {
+      definitionStyles: cloneData(entry.definition.styles),
+      translated: translatedStyles && styleId in translatedStyles ? cloneData(translatedStyles[styleId]) : undefined,
+      xmlElements: xmlEl ? cloneData(xmlEl.elements ?? []) : undefined,
+    };
+
+    try {
+      // 1. live decoration source
+      applyToDefinitionStyles(entry.definition.styles, formatting);
+      // 2. translated layout / resolution chain
+      if (translatedStyles) {
+        if (!translatedStyles[styleId]) translatedStyles[styleId] = { styleId, type: 'paragraph' };
+        applyToTranslatedStyle(translatedStyles[styleId], formatting);
+      }
+      // 3. export survival
+      if (xmlEl) patchStyleXmlElement(xmlEl, formatting);
+      // 4. repaint both render paths (PM decorations + layout cache)
+      repaintStyle(editor);
+      return true;
+    } catch {
+      entry.definition.styles = snapshot.definitionStyles;
+      if (translatedStyles && snapshot.translated !== undefined) translatedStyles[styleId] = snapshot.translated;
+      if (xmlEl && snapshot.xmlElements !== undefined) xmlEl.elements = snapshot.xmlElements;
+      return false;
+    }
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the run formatting at the current selection from editor marks.
+ * Never throws; returns a complete CapturedFormatting.
+ * @param {Object} editor
+ * @returns {import('./style-formatting.js').CapturedFormatting}
+ */
+export function readEffectiveRunFormatting(editor) {
+  const isActive = (name) => {
+    try {
+      return Boolean(editor.isActive?.(name));
+    } catch {
+      return false;
+    }
+  };
+  let textStyle = {};
+  try {
+    textStyle = editor.getAttributes?.('textStyle') ?? {};
+  } catch {
+    /* noop */
+  }
+  return {
+    bold: isActive('bold'),
+    italic: isActive('italic'),
+    underline: isActive('underline'),
+    fontSizePt: parseFontSizePt(textStyle.fontSize),
+    fontFamily: typeof textStyle.fontFamily === 'string' ? textStyle.fontFamily : null,
+    colorHex: normaliseHex(textStyle.color),
+  };
+}
diff --git a/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.test.js b/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.test.js
new file mode 100644
index 0000000000..c9a4726b57
--- /dev/null
+++ b/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.test.js
@@ -0,0 +1,263 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { initTestEditor, loadTestDataForEditorTests } from '../../tests/helpers/helpers.js';
+import { updateLinkedStyleDefinition } from './update-linked-style.js';
+import { findStyleXmlElement } from './style-formatting.js';
+import { LinkedStylesPluginKey } from './plugin.js';
+
+// CHARACTERIZATION (Task 1): the shapes recorded here are the baseline that the
+// mapper + engine tasks assert against. Re-verify if the SuperDoc style shapes
+// change on upgrade (this is exactly what broke the al-pmo overlay).
+//
+// RECORDED 2026-06-18 (paragraph_spacing_missing.docx):
+//   getStyles() ids include: Normal, Heading1..6, Title, Subtitle, Quote, ...
+//   Heading1.definition.styles is a FLAT map; out of the box here it holds only
+//   block keys: { spacing: { lineSpaceAfter, lineSpaceBefore }, indent: {}, tabStops: null }.
+//   Run-level keys are NOT present initially; our mapper writes them as:
+//     bold/italic/underline -> presence ({} when on, key absent when off)
+//     'font-size' -> "<pt>pt",  'font-family' -> "<family>",  color -> "#RRGGBB"
+//   generateLinkedStyleString() reads those run keys into CSS (e.g. "font-size: 30pt").
+
+describe('updateLinkedStyle', () => {
+  const filename = 'paragraph_spacing_missing.docx';
+  let docx, media, mediaFiles, fonts, editor;
+  beforeAll(async () => ({ docx, media, mediaFiles, fonts } = await loadTestDataForEditorTests(filename)));
+  beforeEach(() => {
+    ({ editor } = initTestEditor({ content: docx, media, mediaFiles, fonts }));
+  });
+
+  it('exposes Heading1 with a flat definition.styles map', () => {
+    const style = editor.helpers.linkedStyles.getStyleById('Heading1');
+    expect(style).toBeTruthy();
+    expect(style.id).toBe('Heading1');
+    expect(style.type).toBe('paragraph');
+    expect(style.definition).toBeTruthy();
+    expect(typeof style.definition.styles).toBe('object');
+  });
+});
+
+describe('updateLinkedStyleDefinition (run-level)', () => {
+  const filename = 'paragraph_spacing_missing.docx';
+  let docx, media, mediaFiles, fonts, editor;
+  beforeAll(async () => ({ docx, media, mediaFiles, fonts } = await loadTestDataForEditorTests(filename)));
+  beforeEach(() => {
+    ({ editor } = initTestEditor({ content: docx, media, mediaFiles, fonts }));
+  });
+
+  it('redefines a style definition and reflects it in the CSS string', () => {
+    const id = 'Heading1';
+    const before = editor.helpers.linkedStyles.getLinkedStyleString(id);
+    const ok = updateLinkedStyleDefinition(editor, id, {
+      bold: true,
+      italic: false,
+      underline: false,
+      fontSizePt: 30,
+      fontFamily: 'Times New Roman',
+      colorHex: 'FF0000',
+    });
+    expect(ok).toBe(true);
+    const after = editor.helpers.linkedStyles.getLinkedStyleString(id);
+    expect(after).not.toBe(before);
+    expect(after).toContain('30pt');
+    expect(after.toLowerCase()).toContain('times new roman');
+  });
+
+  it('returns false for an unknown style and does not throw', () => {
+    expect(
+      updateLinkedStyleDefinition(editor, 'NoSuchStyle', {
+        bold: false,
+        italic: false,
+        underline: false,
+        fontSizePt: null,
+        fontFamily: null,
+        colorHex: null,
+      }),
+    ).toBe(false);
+  });
+});
+
+// Regression guard for the "only repaints once" bug. A redefinition changes no
+// document content, so each render path needs its own non-document repaint
+// signal, and it must fire on EVERY call — not just the first.
+describe('updateLinkedStyle repaint signals', () => {
+  const filename = 'paragraph_spacing_missing.docx';
+  let docx, media, mediaFiles, fonts, editor;
+  beforeAll(async () => ({ docx, media, mediaFiles, fonts } = await loadTestDataForEditorTests(filename)));
+  beforeEach(() => {
+    ({ editor } = initTestEditor({ content: docx, media, mediaFiles, fonts }));
+  });
+
+  const headingDecoStrings = () => {
+    const set = LinkedStylesPluginKey.getState(editor.state).decorations;
+    return set
+      .find()
+      .map((d) => d.type?.attrs?.style)
+      .filter(Boolean);
+  };
+
+  it('regenerates plain-PM decorations on EVERY redefinition (not just the first)', () => {
+    editor.commands.setStyleById('Heading1');
+
+    editor.commands.updateLinkedStyle('Heading1', {
+      bold: false,
+      italic: false,
+      underline: false,
+      fontSizePt: 30,
+      fontFamily: 'Arial',
+      colorHex: 'FF0000',
+    });
+    expect(headingDecoStrings().some((s) => s.includes('30pt'))).toBe(true);
+
+    editor.commands.updateLinkedStyle('Heading1', {
+      bold: false,
+      italic: false,
+      underline: false,
+      fontSizePt: 40,
+      fontFamily: 'Georgia',
+      colorHex: '00FF00',
+    });
+    const after = headingDecoStrings();
+    expect(after.some((s) => s.includes('40pt'))).toBe(true);
+    expect(after.some((s) => s.includes('30pt'))).toBe(false); // second update took effect
+  });
+});
+
+// Layout/presentation mode paints from a FlowBlockCache keyed on node identity,
+// which a definition change does not invalidate. The engine must ask the
+// PresentationEditor to clear that cache and re-render — on every call.
+describe('updateLinkedStyle layout-mode repaint hook', () => {
+  it('calls presentationEditor.refreshLinkedStyles on each redefinition', () => {
+    const refreshLinkedStyles = vi.fn();
+    const fakeEditor = {
+      presentationEditor: { refreshLinkedStyles },
+      converter: {
+        linkedStyles: [{ id: 'Heading1', type: 'paragraph', definition: { attrs: {}, styles: {} } }],
+        translatedLinkedStyles: { styles: {} },
+        convertedXml: {},
+      },
+      // no `view` => the PM-decoration signal is skipped, isolating the layout hook
+    };
+    const fmt = { bold: false, italic: false, underline: false, fontSizePt: null, fontFamily: null, colorHex: null };
+    expect(updateLinkedStyleDefinition(fakeEditor, 'Heading1', { ...fmt, fontSizePt: 20 })).toBe(true);
+    expect(updateLinkedStyleDefinition(fakeEditor, 'Heading1', { ...fmt, fontSizePt: 28 })).toBe(true);
+    expect(refreshLinkedStyles).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('updateLinkedStyle command', () => {
+  const filename = 'paragraph_spacing_missing.docx';
+  let docx, media, mediaFiles, fonts, editor;
+  beforeAll(async () => ({ docx, media, mediaFiles, fonts } = await loadTestDataForEditorTests(filename)));
+  beforeEach(() => {
+    ({ editor } = initTestEditor({ content: docx, media, mediaFiles, fonts }));
+  });
+
+  it('is callable via editor.commands and updates the style', () => {
+    const ok = editor.commands.updateLinkedStyle('Heading1', {
+      bold: true,
+      italic: false,
+      underline: false,
+      fontSizePt: 28,
+      fontFamily: 'Arial',
+      colorHex: '1F3864',
+    });
+    expect(ok).toBe(true);
+    expect(editor.helpers.linkedStyles.getLinkedStyleString('Heading1')).toContain('28pt');
+  });
+});
+
+describe('style formatting read helpers', () => {
+  const filename = 'paragraph_spacing_missing.docx';
+  let docx, media, mediaFiles, fonts, editor;
+  beforeAll(async () => ({ docx, media, mediaFiles, fonts } = await loadTestDataForEditorTests(filename)));
+  beforeEach(() => {
+    ({ editor } = initTestEditor({ content: docx, media, mediaFiles, fonts }));
+  });
+
+  it('round-trips a redefinition through getLinkedStyleFormatting', () => {
+    editor.commands.updateLinkedStyle('Heading1', {
+      bold: true,
+      italic: false,
+      underline: false,
+      fontSizePt: 22,
+      fontFamily: 'Georgia',
+      colorHex: 'AA0000',
+    });
+    const fmt = editor.helpers.linkedStyles.getLinkedStyleFormatting('Heading1');
+    expect(fmt).toMatchObject({ bold: true, fontSizePt: 22, fontFamily: 'Georgia', colorHex: 'AA0000' });
+  });
+
+  it('getEffectiveFormattingAtSelection returns a CapturedFormatting object', () => {
+    const fmt = editor.helpers.linkedStyles.getEffectiveFormattingAtSelection();
+    expect(fmt).toHaveProperty('bold');
+    expect(fmt).toHaveProperty('fontSizePt');
+    expect(fmt).toHaveProperty('colorHex');
+  });
+});
+
+describe('export representations (characterization)', () => {
+  const filename = 'paragraph_spacing_missing.docx';
+  let docx, media, mediaFiles, fonts, editor;
+  beforeAll(async () => ({ docx, media, mediaFiles, fonts } = await loadTestDataForEditorTests(filename)));
+  beforeEach(() => {
+    ({ editor } = initTestEditor({ content: docx, media, mediaFiles, fonts }));
+  });
+
+  it('exposes the two export representations', () => {
+    const c = editor.converter;
+    expect(typeof c.translatedLinkedStyles).toBe('object');
+    expect(c.translatedLinkedStyles?.styles?.Heading1?.styleId).toBe('Heading1');
+    const xml = c.convertedXml?.['word/styles.xml'];
+    expect(xml).toBeTruthy();
+    expect(xml.elements?.[0]?.name).toBe('w:styles');
+  });
+
+  // RECORDED 2026-06-18 (paragraph_spacing_missing.docx):
+  //   translatedLinkedStyles.styles.Heading1 = { type:'paragraph', styleId, name, basedOn,
+  //     next, uiPriority, qFormat, paragraphProperties: { spacing, outlineLvl } }  (no runProperties yet)
+  //     -> run channel: runProperties.{ bold, italic, underline:{value:'single'}, fontSize:<halfPoints:int>,
+  //        fontFamily:{ascii,hAnsi,cs}, color:{val:<hex no #>} }
+  //   word/styles.xml root = w:styles; Heading1 = w:style[@w:styleId='Heading1'] with children
+  //     w:name, w:basedOn, w:next, w:uiPriority, w:qFormat, w:pPr (no w:rPr yet).
+  //     -> append w:rPr (correct CT_Style order is after w:pPr) with w:b/w:i/w:u, w:sz+w:szCs (halfPoints),
+  //        w:rFonts{w:ascii,w:hAnsi,w:cs}, w:color{w:val}.
+});
+
+describe('redefinition survives in the export representations', () => {
+  const filename = 'paragraph_spacing_missing.docx';
+  let docx, media, mediaFiles, fonts, editor;
+  beforeAll(async () => ({ docx, media, mediaFiles, fonts } = await loadTestDataForEditorTests(filename)));
+  beforeEach(() => {
+    ({ editor } = initTestEditor({ content: docx, media, mediaFiles, fonts }));
+  });
+
+  it('patches word/styles.xml (size in half-points) on redefinition', () => {
+    editor.commands.updateLinkedStyle('Heading1', {
+      bold: true,
+      italic: false,
+      underline: false,
+      fontSizePt: 30,
+      fontFamily: 'Arial',
+      colorHex: 'FF0000',
+    });
+    const xml = editor.converter.convertedXml['word/styles.xml'];
+    const styleEl = findStyleXmlElement(xml, 'Heading1');
+    const rpr = styleEl.elements.find((e) => e.name === 'w:rPr');
+    expect(rpr.elements.find((e) => e.name === 'w:sz')?.attributes['w:val']).toBe('60');
+    expect(rpr.elements.find((e) => e.name === 'w:color')?.attributes['w:val']).toBe('FF0000');
+  });
+
+  it('patches translatedLinkedStyles run channel on redefinition', () => {
+    editor.commands.updateLinkedStyle('Heading1', {
+      bold: true,
+      italic: false,
+      underline: false,
+      fontSizePt: 24,
+      fontFamily: 'Georgia',
+      colorHex: 'AA0000',
+    });
+    const def = editor.converter.translatedLinkedStyles.styles.Heading1;
+    expect(def.runProperties.fontSize).toBe(48);
+    expect(def.runProperties.fontFamily).toEqual({ ascii: 'Georgia', hAnsi: 'Georgia', cs: 'Georgia' });
+    expect(def.runProperties.color).toEqual({ val: 'AA0000' });
+  });
+});

From 7b4a5920f9faf93b039e563bdc3fb2ea01064e69 Mon Sep 17 00:00:00 2001
From: Shri H <shri.h@contractors.scale.com>
Date: Fri, 19 Jun 2026 13:01:21 +0100
Subject: [PATCH 2/2] fix(linked-styles): resolve effective formatting and use
 explicit boolean-off

Address review feedback on "Update to match":

- readEffectiveRunFormatting now resolves the selection paragraph's named style
  (merged over its basedOn parent) as the base and layers direct marks on top,
  instead of reading marks only. Previously, formatting that came purely from a
  named style (the common .docx case) was captured as empty and wiped the style.
- Cleared booleans (bold/italic/underline) are now stored as explicit off
  ({ value: '0' } in definition styles, w:val="0"/w:u w:val="none" in OOXML)
  rather than deleting the key, so a redefined style overrides an inherited
  basedOn value instead of falling back to it. definitionStylesToFormatting
  reads explicit-off back as false.
---
 .../linked-styles/style-formatting.js         | 43 ++++++++----
 .../linked-styles/style-formatting.test.js    | 18 +++--
 .../linked-styles/update-linked-style.js      | 68 ++++++++++++++++---
 .../linked-styles/update-linked-style.test.js | 25 +++++++
 4 files changed, 128 insertions(+), 26 deletions(-)

diff --git a/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.js b/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.js
index aeae456836..70fc8c6471 100644
--- a/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.js
+++ b/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.js
@@ -47,13 +47,16 @@ export function parseFontSizePt(value) {
  * @param {CapturedFormatting} captured
  */
 export function applyToDefinitionStyles(styles, captured) {
-  const setPresence = (key, on) => {
-    if (on) styles[key] = styles[key] ?? {};
-    else delete styles[key];
+  // On => presence ({}); off => explicit { value: '0' } rather than removing the
+  // key, so a redefined style overrides (not inherits) a basedOn boolean.
+  // generateLinkedStyleString reads value '0'/false as off (and a present key
+  // blocks basedOn inheritance).
+  const setBool = (key, on) => {
+    styles[key] = on ? {} : { value: '0' };
   };
-  setPresence('bold', captured.bold);
-  setPresence('italic', captured.italic);
-  setPresence('underline', captured.underline);
+  setBool('bold', captured.bold);
+  setBool('italic', captured.italic);
+  setBool('underline', captured.underline);
 
   if (captured.fontSizePt != null) styles['font-size'] = `${captured.fontSizePt}pt`;
   else delete styles['font-size'];
@@ -70,10 +73,17 @@ export function applyToDefinitionStyles(styles, captured) {
  */
 export function definitionStylesToFormatting(styles) {
   const s = styles || {};
+  // A boolean is on when its key is present and not an explicit off ('0'/false);
+  // absent or explicit-off both read as false.
+  const boolOn = (v) => {
+    if (v == null) return false;
+    const val = typeof v === 'object' ? v.value : v;
+    return val !== '0' && val !== false;
+  };
   return {
-    bold: 'bold' in s,
-    italic: 'italic' in s,
-    underline: 'underline' in s,
+    bold: boolOn(s.bold),
+    italic: boolOn(s.italic),
+    underline: boolOn(s.underline),
     fontSizePt: parseFontSizePt(s['font-size']),
     fontFamily: typeof s['font-family'] === 'string' ? s['font-family'] : null,
     colorHex: normaliseHex(s.color),
@@ -134,10 +144,14 @@ function removeChild(parent, name) {
   parent.elements = parent.elements.filter((el) => el.name !== name);
 }
 
-/** @param {XmlElement} rpr @param {string} name @param {boolean} on */
+/**
+ * Set an OOXML run-property toggle. On => present with no val (`<w:b/>`);
+ * off => explicit `<w:b w:val="0"/>` so a basedOn style's value is overridden
+ * rather than inherited (absent would inherit).
+ * @param {XmlElement} rpr @param {string} name @param {boolean} on
+ */
 function setBooleanProp(rpr, name, on) {
-  if (on) ensureChild(rpr, name).attributes = {};
-  else removeChild(rpr, name);
+  ensureChild(rpr, name).attributes = on ? {} : { 'w:val': '0' };
 }
 
 /**
@@ -150,8 +164,9 @@ export function patchStyleXmlElement(styleEl, captured) {
   const rpr = ensureChild(styleEl, 'w:rPr');
   setBooleanProp(rpr, 'w:b', captured.bold);
   setBooleanProp(rpr, 'w:i', captured.italic);
-  if (captured.underline) ensureChild(rpr, 'w:u').attributes = { 'w:val': 'single' };
-  else removeChild(rpr, 'w:u');
+  // Underline off is explicit (w:val="none") for the same reason as w:b/w:i:
+  // an absent w:u would inherit a basedOn underline.
+  ensureChild(rpr, 'w:u').attributes = captured.underline ? { 'w:val': 'single' } : { 'w:val': 'none' };
 
   if (captured.fontSizePt != null) {
     const halfPoints = String(Math.round(captured.fontSizePt * 2));
diff --git a/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.test.js b/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.test.js
index ebf0ba02c5..cae0a747e5 100644
--- a/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.test.js
+++ b/packages/super-editor/src/editors/v1/extensions/linked-styles/style-formatting.test.js
@@ -23,7 +23,7 @@ describe('style-formatting (pure)', () => {
     expect(parseFontSizePt(undefined)).toBeNull();
   });
 
-  it('applyToDefinitionStyles writes run-level keys and removes cleared ones', () => {
+  it('applyToDefinitionStyles writes run-level keys and sets explicit-off for cleared booleans', () => {
     const styles = { bold: {} };
     applyToDefinitionStyles(styles, {
       bold: false,
@@ -33,13 +33,23 @@ describe('style-formatting (pure)', () => {
       fontFamily: 'Arial',
       colorHex: 'FF0000',
     });
-    expect(styles.bold).toBeUndefined();
+    // Cleared booleans become explicit off ({ value: '0' }) so they override an
+    // inherited basedOn value instead of falling back to it.
+    expect(styles.bold).toEqual({ value: '0' });
+    expect(styles.underline).toEqual({ value: '0' });
     expect(styles.italic).toEqual({});
     expect(styles['font-size']).toBe('18pt');
     expect(styles['font-family']).toBe('Arial');
     expect(styles.color).toBe('#FF0000');
   });
 
+  it('definitionStylesToFormatting reads explicit-off booleans as false', () => {
+    expect(definitionStylesToFormatting({ bold: { value: '0' }, italic: {} })).toMatchObject({
+      bold: false,
+      italic: true,
+    });
+  });
+
   it('applyToDefinitionStyles leaves block-level keys untouched', () => {
     const styles = { spacing: { lineSpaceAfter: 10 }, indent: {}, tabStops: null };
     applyToDefinitionStyles(styles, {
@@ -102,7 +112,7 @@ describe('styles.xml patch (pure)', () => {
     expect(rpr.elements.find((e) => e.name === 'w:color')?.attributes['w:val']).toBe('FF0000');
   });
 
-  it('removes cleared boolean props from w:rPr', () => {
+  it('writes explicit-off (w:val="0") for cleared booleans so basedOn is not inherited', () => {
     const styleEl = {
       type: 'element',
       name: 'w:style',
@@ -111,7 +121,7 @@ describe('styles.xml patch (pure)', () => {
     };
     patchStyleXmlElement(styleEl, fmt({ bold: false }));
     const rpr = styleEl.elements.find((e) => e.name === 'w:rPr');
-    expect(rpr.elements.find((e) => e.name === 'w:b')).toBeFalsy();
+    expect(rpr.elements.find((e) => e.name === 'w:b')?.attributes['w:val']).toBe('0');
   });
 
   it('findStyleXmlElement locates a style by w:styleId', () => {
diff --git a/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.js b/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.js
index bbcf89b619..e051b3fb3f 100644
--- a/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.js
+++ b/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.js
@@ -1,8 +1,10 @@
 // @ts-check
+import { getLinkedStyle } from './helpers.js';
 import { LinkedStylesPluginKey } from './plugin.js';
 import {
   applyToDefinitionStyles,
   applyToTranslatedStyle,
+  definitionStylesToFormatting,
   findStyleXmlElement,
   parseFontSizePt,
   patchStyleXmlElement,
@@ -96,13 +98,61 @@ export function updateLinkedStyleDefinition(editor, styleId, formatting) {
   }
 }
 
+/** The paragraph styleId applied at the current selection, or null. */
+function getParagraphStyleIdAtSelection(editor) {
+  try {
+    const $from = editor?.state?.selection?.$from;
+    if (!$from) return null;
+    for (let depth = $from.depth; depth > 0; depth--) {
+      const node = $from.node(depth);
+      if (node?.type?.name === 'paragraph') {
+        return node.attrs?.paragraphProperties?.styleId ?? null;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the run formatting the selection's paragraph style contributes
+ * (the named style merged over its basedOn parent), or null when unstyled.
+ * @param {Object} editor
+ * @returns {import('./style-formatting.js').CapturedFormatting|null}
+ */
+function resolveStyleRunFormatting(editor) {
+  try {
+    const styleId = getParagraphStyleIdAtSelection(editor);
+    if (!styleId) return null;
+    const styles = editor?.converter?.linkedStyles ?? [];
+    const { linkedStyle, basedOnStyle } = getLinkedStyle(styleId, styles);
+    if (!linkedStyle?.definition?.styles) return null;
+    const merged = { ...(basedOnStyle?.definition?.styles ?? {}), ...linkedStyle.definition.styles };
+    return definitionStylesToFormatting(merged);
+  } catch {
+    return null;
+  }
+}
+
 /**
- * Read the run formatting at the current selection from editor marks.
- * Never throws; returns a complete CapturedFormatting.
+ * Read the EFFECTIVE run formatting at the current selection: the formatting the
+ * paragraph's named style resolves to, with any direct marks layered on top.
+ * This is what "update to match" must capture — formatting that comes purely from
+ * a named style (the common .docx case) has no direct marks, so a marks-only read
+ * would capture nothing and wipe the style. Never throws.
  * @param {Object} editor
  * @returns {import('./style-formatting.js').CapturedFormatting}
  */
 export function readEffectiveRunFormatting(editor) {
+  const base = resolveStyleRunFormatting(editor) ?? {
+    bold: false,
+    italic: false,
+    underline: false,
+    fontSizePt: null,
+    fontFamily: null,
+    colorHex: null,
+  };
   const isActive = (name) => {
     try {
       return Boolean(editor.isActive?.(name));
@@ -116,12 +166,14 @@ export function readEffectiveRunFormatting(editor) {
   } catch {
     /* noop */
   }
+  const markFamily = typeof textStyle.fontFamily === 'string' ? textStyle.fontFamily : null;
+  // Direct marks win where present; otherwise fall back to the resolved style.
   return {
-    bold: isActive('bold'),
-    italic: isActive('italic'),
-    underline: isActive('underline'),
-    fontSizePt: parseFontSizePt(textStyle.fontSize),
-    fontFamily: typeof textStyle.fontFamily === 'string' ? textStyle.fontFamily : null,
-    colorHex: normaliseHex(textStyle.color),
+    bold: isActive('bold') || base.bold,
+    italic: isActive('italic') || base.italic,
+    underline: isActive('underline') || base.underline,
+    fontSizePt: parseFontSizePt(textStyle.fontSize) ?? base.fontSizePt,
+    fontFamily: markFamily ?? base.fontFamily,
+    colorHex: normaliseHex(textStyle.color) ?? base.colorHex,
   };
 }
diff --git a/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.test.js b/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.test.js
index c9a4726b57..a7c7cfee7d 100644
--- a/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.test.js
+++ b/packages/super-editor/src/editors/v1/extensions/linked-styles/update-linked-style.test.js
@@ -192,6 +192,31 @@ describe('style formatting read helpers', () => {
     expect(fmt).toHaveProperty('fontSizePt');
     expect(fmt).toHaveProperty('colorHex');
   });
+
+  it('captures style-resolved formatting when the selection has no direct marks', () => {
+    // Put the cursor in a paragraph, make it Heading1 (which clears direct marks),
+    // and give Heading1 a distinctive look. The cursor now has NO direct marks, so
+    // the visible formatting comes entirely from the named style.
+    let pos = null;
+    editor.state.doc.descendants((node, p) => {
+      if (pos == null && node.type.name === 'paragraph') pos = p + 1;
+      return pos == null;
+    });
+    editor.commands.setTextSelection(pos);
+    editor.commands.setStyleById('Heading1');
+    editor.commands.updateLinkedStyle('Heading1', {
+      bold: true,
+      italic: false,
+      underline: false,
+      fontSizePt: 21,
+      fontFamily: 'Georgia',
+      colorHex: '112233',
+    });
+
+    const fmt = editor.helpers.linkedStyles.getEffectiveFormattingAtSelection();
+    // Must reflect the style, not empty/false (the bug: marks-only read wiped it).
+    expect(fmt).toMatchObject({ bold: true, fontSizePt: 21, fontFamily: 'Georgia', colorHex: '112233' });
+  });
 });
 
 describe('export representations (characterization)', () => {