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

[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, 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

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

---

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
style-engine	src/index.ts — Add lockMode normalization
painter-dom	renderer.ts — Grouped hover binding, post-render reapply, mapping reliability check
painter-dom	styles.ts — Block SDT hover uses .sdt-hover class, updated label styling
painter-dom	utils/sdt-helpers.ts — Add shouldRebuildForSdtBoundary, fix stale attribute handling
painter-dom	utils/sdt-hover.ts — New 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 — Add lockMode to type interface

---

Commit History

Commit	Description
3e5377e7	feat: Initial w:lock support — attribute, import/export, lock plugin, NodeView, styling, tests
d04f6c6a	perf: Optimize lock plugin to use nodesBetween() on changed ranges instead of full descendants()
786e5b77	fix: Clamp nodesBetween range to valid document bounds
9137b9c5	refactor: Remove unused isSdtLocked() method and updateLockStateClasses() (no CSS rules existed)
fb4a38c0	fix: Switch from contentEditable=false to plugin-only defense for cursor movement UX
0646a2f4	feat: Grouped hover for multi-fragment SDTs, stale fragment rebuild detection, code extraction

---

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

Related

• IT-336

Demo

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

[github-actions]

Based on my review of the code and my knowledge of the ECMA-376 specification, I can provide a detailed review:

Status: FAIL

The implementation has spec violations in the w:lock element handling:

Issues Found

1. Invalid enumeration values (Critical)

Files:

• packages/super-editor/src/core/super-converter/v3/handlers/w/sdt/helpers/handle-structured-content-node.js:25
• packages/super-editor/src/core/super-converter/v3/handlers/w/sdt/helpers/translate-structured-content.js:62

Problem: The code uses 'unlocked' as a valid value for w:lock/@w:val, but this is not a valid ECMA-376 enumeration value.

According to ECMA-376 Part 1 §17.5.2.20 (CT_Lock), the w:lock element's w:val attribute accepts ST_Lock enumeration values:

• sdtLocked - SDT cannot be deleted
• contentLocked - SDT contents cannot be edited
• sdtContentLocked - Both SDT and contents are locked
• unlocked is NOT a valid value in the spec

Spec violation: When an SDT is unlocked, the w:lock element should be omitted entirely, not set to 'unlocked'.

2. Incorrect default handling (Major)

File: packages/super-editor/src/core/super-converter/v3/handlers/w/sdt/helpers/handle-structured-content-node.js:26

Problem: The code defaults missing w:lock elements to 'unlocked':

const lockMode = validModes.includes(lockValue) ? lockValue : 'unlocked';

Correct behavior: When w:lock is absent, the lock mode should be represented as undefined or null internally, and no w:lock element should be written on export.

3. Correct export logic (passes validation)

File: packages/super-editor/src/core/super-converter/v3/handlers/w/sdt/helpers/translate-structured-content.js:69

Good news: The export logic correctly omits the w:lock element when lockMode === 'unlocked':

if (attrs.lockMode && attrs.lockMode !== 'unlocked') resultElements.push(lock);

This partially compensates for issue #1, but the internal representation still uses an invalid spec value.

Recommendations

1. Remove 'unlocked' from valid modes - Use null/undefined to represent unlocked state
2. Update the valid modes list to only include the three actual ECMA-376 values:

   const validModes = ['sdtLocked', 'contentLocked', 'sdtContentLocked'];
   const lockMode = validModes.includes(lockValue) ? lockValue : null;

3. Update TypeScript types in packages/layout-engine/contracts/src/index.ts:59 to make lockMode nullable or remove 'unlocked' from the union

Reference

See ECMA-376 Part 1 §17.5.2.20 for full specification: https://ooxml.dev/spec?q=w:lock

The implementation is close but needs the "unlocked" value removed from the internal data model to fully comply with OOXML.

[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".