feat(super-editor): add w:lock support for StructuredContent nodes (SD-1616)

[tupizz]

Summary

Add ECMA-376 w:lock support for StructuredContent (inline) and StructuredContentBlock (block) nodes, enabling template variables to be read-only per the OOXML specification (§17.5.2.23).

Also adds grouped hover for multi-fragment block SDTs, stale fragment rebuild detection, inline SDT wrapping for geometry rendering path, and SDT utility extraction for better code organization.

Lock Modes

Lock Mode	SDT Wrapper	Content	Use Case
unlocked	Can delete	Can edit	Default, no restrictions
sdtLocked	Cannot delete	Can edit	Protect field structure
contentLocked	Can delete	Cannot edit	Read-only value, removable
sdtContentLocked	Cannot delete	Cannot edit	Fully protected field

Visual Comparison (Word vs SuperDoc)

Border behavior: Blue border (#629be7) appears on hover only, matching Word's behavior.

---

Architecture Decisions

1. Plugin-Only Defense (No contentEditable='false')

Decision: Block edits through the lock plugin instead of setting contentEditable='false' on locked content.

Why: Setting contentEditable='false' completely prevents cursor placement inside the node. This is poor UX because users:

• Can't select text to copy it
• Can't navigate through the document smoothly
• Experience jarring cursor behavior around locked regions

Solution: Keep content editable at the DOM level and rely on the plugin to block actual edits. Users can move cursor and select text freely while being prevented from modifying content.

2. Three-Layer Defense Strategy

The lock plugin uses three mechanisms to enforce locks:

Layer	Hook	Purpose
1	handleKeyDown	Block Delete/Backspace/Cut before transaction is created
2	handleTextInput	Block typing in content-locked nodes
3	filterTransaction	Safety net for paste, drag-drop, programmatic changes

Why handleKeyDown instead of just filterTransaction?

ProseMirror's transaction flow is:

User action → Browser event → handleKeyDown → Transaction created → filterTransaction → Applied

When filterTransaction blocks a transaction, the browser may have already modified DOM selection, causing the cursor to jump unexpectedly. By intercepting in handleKeyDown and calling event.preventDefault(), we prevent the browser from processing the event at all.

3. Step Relationship Analysis

To detect lock violations, we analyze the geometric relationship between a step's affected range and each SDT node:

Document: [----SDT----]
               pos    end

1. containsSDT: Would fully delete the SDT
   Step:    [================]
   SDT:        [--------]
   → Blocked for sdtLocked/sdtContentLocked

2. insideSDT: Modification entirely within SDT (but not deleting it)
   Step:          [--]
   SDT:        [--------]
   → Blocked for contentLocked/sdtContentLocked

3. crossesStart/crossesEnd: Step crosses SDT boundary
   Step:    [=======]        or        [=======]
   SDT:        [--------]         [--------]
   → Blocked for sdtLocked/sdtContentLocked (damages wrapper)

4. NodeView Provides Visual Feedback Only

The NodeView adds CSS classes for styling but does NOT set contentEditable:

updateContentEditability() {
  if (this.dom) {
    this.dom.classList.toggle('sd-structured-content--content-locked', this.isContentLocked());
    this.dom.classList.toggle('sd-structured-content--sdt-locked', this.isSdtLocked());
  }
}

---

Changes

Import/Export

• Parse w:lock element from w:sdtPr on DOCX import
• Export w:lock element to w:sdtPr on DOCX save
• Round-trip preservation of lock mode values

Editor Behavior

• Add lockMode attribute to StructuredContent and StructuredContentBlock extensions
• Add structuredContentLockPlugin with 3-layer defense:
  • handleKeyDown: Block Delete/Backspace/Cut before transaction
  • handleTextInput: Block typing in content-locked nodes
  • filterTransaction: Safety net for programmatic changes
• NodeView adds CSS classes for visual feedback (allows cursor movement)

Visual Styling (Presentation Mode)

• Add StructuredContentLockMode type to contracts
• Add lockMode to StructuredContentMetadata in style-engine
• Add data-lock-mode attribute rendering in DomPainter
• Add CSS styles matching Word's appearance for each lock mode
• Unified hover styles for block (.sdt-hover) and inline (:hover) SDTs with consistent !important overrides

Inline SDT Wrapping for Geometry Rendering Path

When a line contains tabs, the DomPainter uses a geometry-based rendering path where elements are absolutely positioned. Previously, inline SDT wrapping only worked in the run-based path, causing tabs inside inline SDTs to lose their visual wrapper. Now:

• appendToLineGeo helper routes all geometry-path elements (tabs, images, field annotations, text segments) through SDT wrapping logic
• The wrapper uses position: absolute with computed left/width to span all contained children
• PM position tracking (data-pm-start/data-pm-end) is maintained on the wrapper element
• TabRun contract type extended with optional sdt metadata; pm-adapter passes SDT metadata through to tab runs

Grouped Hover for Multi-Fragment Block SDTs

When a block SDT spans multiple paragraphs, each renders as a separate DOM fragment. Previously, CSS :hover only highlighted the individual fragment under the cursor. Now all fragments of the same SDT highlight simultaneously via JavaScript event delegation:

• SdtGroupedHover class (utils/sdt-hover.ts): Event delegation on mount container using mouseover/mouseleave. Finds all fragments sharing the same data-sdt-id and toggles .sdt-hover CSS class on all of them.
• Post-render re-apply: After DomPainter re-renders pages (e.g. during editing), newly created DOM elements lose the .sdt-hover class. SdtGroupedHover.reapply() is called at the end of updateVirtualWindow() to restore the class on all matching fragments.
• CSS: Block SDT rules changed from :hover to .sdt-hover selector. Inline SDTs remain :hover-based (single element, no grouping needed).

Stale Fragment Rebuild Detection

• shouldRebuildForSdtBoundary (moved to utils/sdt-helpers.ts): Detects when a fragment's SDT boundary attributes (data-sdt-container-start/end) are stale and need rebuilding. Now correctly handles the case where a fragment leaves an SDT group (attributes present but should be removed).
• mappingUnreliable check: After a full-document paste of identical content, ProseMirror's transaction mapping becomes degenerate — it maps all old positions to the insertion end. This corrupted data-pm-start/data-pm-end attributes on reused spans, breaking cursor/click navigation. The new check verifies mapping.map(oldPmStart) === fragment.pmStart and forces a full fragment rebuild when the mapping is unreliable.

Code Organization

• Extracted SdtGroupedHover class from renderer.ts into utils/sdt-hover.ts
• Moved shouldRebuildForSdtBoundary from renderer.ts into utils/sdt-helpers.ts
• Reduced renderer.ts SDT hover footprint from ~65 lines to 4 one-liner calls
• Removed unnecessary try/catch around removeEventListener in SdtGroupedHover
• Re-export StructuredContentLockMode from contracts instead of duplicating in node-attributes.ts

Visual Testing Story

• sdt-lock-modes.ts: New interaction story demonstrating all lock modes:
  • Creates inline SDTs with unlocked, sdtLocked, contentLocked modes via insertStructuredContentInline
  • Creates block SDT with sdtContentLocked via insertStructuredContentBlock
  • Demonstrates typing inside sdtLocked SDT (content editable)
  • Demonstrates typing blocked inside contentLocked SDT
  • Demonstrates updateStructuredContentById to change lock modes programmatically
  • 8 milestones capturing each interaction step

---

Test Coverage

35 tests covering all lock modes and operations:

• Wrapper deletion tests (4 modes × 2 node types = 8 tests)
• Content modification tests (4 modes × 2 node types = 8 tests)
• Boundary crossing tests (crosses start/end of SDT)
• Edge cases (empty document, multiple SDTs, collapsed selection)

Test Files  1 passed (1)
     Tests  35 passed (35)

---

Files Changed

Package	Files
contracts	src/index.ts — Add StructuredContentLockMode type, sdt on TabRun
style-engine	src/index.ts — Add lockMode normalization
pm-adapter	inline-converters/tab.ts — Pass SDT metadata to tab runs
painter-dom	renderer.ts — Grouped hover, post-render reapply, mapping reliability check, geometry-path SDT wrapping
painter-dom	styles.ts — Block SDT hover uses .sdt-hover class, unified hover styles with !important
painter-dom	utils/sdt-helpers.ts — Add shouldRebuildForSdtBoundary, fix stale attribute handling
painter-dom	utils/sdt-hover.ts — SdtGroupedHover class for multi-fragment hover
super-editor	Extensions — lockMode attribute for inline and block nodes
super-editor	NodeViews — CSS class toggling for lock state visual feedback
super-editor	Lock plugin — structured-content-lock-plugin.js (169 lines)
super-editor	Lock tests — structured-content-lock-plugin.test.js (416 lines, 35 tests)
super-editor	Import/Export — Parse and generate w:lock element
super-editor	Import/Export tests — Round-trip tests for lock modes
super-editor	Types — node-attributes.ts — Re-export StructuredContentLockMode from contracts
visual-testing	stories/structured-content/sdt-lock-modes.ts — Visual testing story for lock modes

---

Test Plan

• Unit tests for import parsing (all 4 lock modes)
• Unit tests for export generation
• Unit tests for lock plugin (35 tests covering all scenarios)
• Cursor movement works in locked content
• Manual test with DOCX containing locked SDTs
• Verify visual styling matches Word
• Grouped hover highlights all fragments of multi-line block SDTs
• Hover clears correctly on mouse leave
• Editing inside hovered SDT preserves hover on new fragments
• Full-document paste (Cmd+A, Cmd+C, Cmd+V) preserves cursor navigation
• Tab inside inline SDT preserves visual wrapper (both rendering paths)
• Visual testing story captures 8 milestones for all lock mode interactions

Related

• IT-336

Demo

CleanShot.2026-02-04.at.15.53.52.mp4

[Copilot]

Pull request overview

This PR adds comprehensive support for ECMA-376 w:lock functionality to StructuredContent nodes, enabling four lock modes (unlocked, sdtLocked, contentLocked, sdtContentLocked) that control whether the SDT wrapper can be deleted and whether the content can be edited. The implementation uses a three-layer defense strategy in the editor, full round-trip import/export support, and visual styling that differentiates lock modes.

Changes:

• Added lockMode attribute to StructuredContent and StructuredContentBlock nodes with DOM parsing/rendering
• Implemented lock enforcement plugin with handleKeyDown, handleTextInput, and filterTransaction hooks
• Added DOCX import parsing and export generation for w:lock elements
• Implemented visual styling with distinct background colors for each lock mode

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/super-editor/src/extensions/types/node-attributes.ts	Added StructuredContentLockMode type definition
packages/super-editor/src/extensions/structured-content/structured-content.js	Added lockMode attribute and registered lock plugin
packages/super-editor/src/extensions/structured-content/structured-content-block.js	Added lockMode attribute definition
packages/super-editor/src/extensions/structured-content/structured-content-lock-plugin.js	Implemented three-layer lock enforcement with step relationship analysis
packages/super-editor/src/extensions/structured-content/structured-content-lock-plugin.test.js	Comprehensive test suite with 35 tests covering all lock modes and scenarios
packages/super-editor/src/extensions/structured-content/StructuredContentViewBase.js	Added lock detection and CSS class application methods
packages/super-editor/src/extensions/structured-content/StructuredContentInlineView.js	Integrated updateContentEditability in view lifecycle
packages/super-editor/src/extensions/structured-content/StructuredContentBlockView.js	Integrated updateContentEditability in view lifecycle
packages/super-editor/src/core/super-converter/v3/handlers/w/sdt/helpers/handle-structured-content-node.js	Added w:lock parsing with validation of lock mode values
packages/super-editor/src/core/super-converter/v3/handlers/w/sdt/helpers/handle-structured-content-node.test.js	Tests for parsing all lock mode values and defaults
packages/super-editor/src/core/super-converter/v3/handlers/w/sdt/helpers/translate-structured-content.js	Added w:lock export generation and deduplication
packages/super-editor/src/core/super-converter/v3/handlers/w/sdt/helpers/translate-structured-content.test.js	Tests for exporting lock modes and preventing duplication
packages/layout-engine/style-engine/src/index.ts	Added lockMode to normalized StructuredContentMetadata
packages/layout-engine/painters/dom/src/utils/sdt-helpers.ts	Added lockMode data attribute rendering in SDT containers
packages/layout-engine/painters/dom/src/renderer.ts	Added lockMode to dataset attributes and rendering
packages/layout-engine/painters/dom/src/styles.ts	Added CSS styles for each lock mode with hover effects
packages/layout-engine/contracts/src/index.ts	Added StructuredContentLockMode type to contracts

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fb4a38c0cd

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[andrii-harbour]

overall very good! Nice job!
I have only minor comments/suggestions there

[andrii-harbour]

@tupizz it can also be a separate ticket as it's more about rendering than sdt logic itself - https://cdn.zappy.app/1bf739f84f32971a4be16dcc57ea71d7.mp4

clicking tab inside the sdt container - brakes the UI of the sdt

[linear]

SD-1616 Add lock support to StructuredContent variables

[andrii-harbour]

LGTM! Well done!

[caio-pizzol]

Hey, @tupizz. This is a great start!

A few things to note:

Make sure you are not pushing formatting changes to the remote repo. This affects the files we actually have to review versus the ones that are just formatting changes. A way to do that is actually have pre-commit installed in your local repo so the code will always be formatted automatically before committing changes.

I added a few comments across your implementation. Please try to address the ones that make sense.

Also, because we are adding visual interfaces, this PR will also require visual testing for rendering and interaction stories. Let me know if you have any questions on how to write those.

[tupizz]

@caio-pizzol

Also, because we are adding visual interfaces, this PR will also require visual testing for rendering and interaction stories. Let me know if you have any questions on how to write those.

This is already defined in the PR, please check:
https://github.com/superdoc-dev/superdoc/pull/1939/changes#diff-93ff67f20943e2b47a11c268cf8642caa55bd4bebb7fd3ec83abb7bfab817ff2

[harbournick]

LGTM

[superdoc-bot]

🎉 This PR is included in superdoc v1.12.0-next.12

The release is available on GitHub release

[harbournick]

🎉 This PR is included in superdoc v1.12.0

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in superdoc-cli v0.2.0

The release is available on GitHub release