notectl

Every user interaction in notectl follows a predictable, unidirectional cycle that moves from raw input to a synchronized DOM. This cycle ensures that the editor state remains the single source of truth while allowing plugins and middleware to intercept and modify changes.

The Cycle Lifecycle:

1. User Input: Browser events (e.g., beforeinput, keydown) are captured.
2. Input/Keyboard Handling: InputHandler or KeyboardHandler maps events to specific editing commands.
3. Transaction Building: A Transaction containing Steps is created via a builder.
4. Middleware Execution: The transaction passes through a priority-ordered middleware chain.
5. State Application: EditorState.apply(transaction) produces a new immutable state.
6. History Recording: The History manager stores the transaction and its inverse for undo/redo.
7. DOM Reconciliation: The Reconciler performs block-level diffing to patch the DOM efficiently.
8. Selection Sync: The browser's cursor/selection is synchronized with the new model state.
9. Plugin Notification: Plugins are notified of the change via onStateChange().

User Input
    ↓
InputHandler / KeyboardHandler
    ↓
TransactionBuilder creates Transaction (Steps)
    ↓
PluginManager.dispatchWithMiddleware()
    ↓ (priority-ordered middleware chain)
EditorState.apply(transaction)
    ↓
New immutable EditorState
    ↓
Plugin.decorations?(state, tr) collected
    ↓
Reconciler patches DOM (block-level diff)
    ↓
SelectionSync updates cursor
    ↓
Plugins notified via onStateChange()

The PluginContext object provided during init() is the gateway to all editor extensions. It allows you to interact with the state, register new schema elements, and hook into user input.

Core Capabilities:

• State & Dispatch: Use context.getState() to read the current state and context.dispatch(tr) to apply a Transaction.
• Commands: Register named actions with context.registerCommand(id, handler) and trigger them with context.executeCommand(id).
• Schema Extension:
  • registerNodeSpec: Add new block types.
  • registerMarkSpec: Add new inline marks.
  • registerInlineNodeSpec: Add atomic inline elements (e.g., emojis).
  • registerNodeSpecExtension: Augment an existing node type owned by another plugin (e.g., allowing a callout inside a table_cell).
• Input & Keyboard:
  • registerKeymap: Bind keyboard shortcuts (use Mod for Cmd/Ctrl).
  • registerInputRule: Transform text patterns as the user types.
• UI Components:
  • registerToolbarItem: Add buttons to the toolbar.
  • registerBlockTypePickerEntry: Add entries to the block type dropdown (requires dependencies: ['heading']).
• Communication & Services:
  • getEventBus(): Emit/Listen to typed events using EventKey.
  • registerService / getService: Expose typed services via ServiceKey.
• Interception & Middleware:
  • registerMiddleware: Intercept transactions before they are applied.
  • registerPasteInterceptor: Transform pasted content.
• DOM & Styles:
  • getContainer(): Access the content-editable element.
  • getPluginContainer(area): Access 'top' or 'bottom' plugin areas.
  • registerStyleSheet: Inject CSS into the editor.
• Other:
  • registerFileHandler: Handle drag-and-drop/paste of files.
  • registerNodeView: Register custom rendering for a block type.
  • announce: Push accessibility announcements to screen readers.

Fragment-only URLs (e.g., #installation) target blocks using their semantic HTML id. These links are treated as document-local and do not receive target="_blank", even if openInNewTab is enabled.

Key Behaviors:

• Resolution: An unmodified left click resolves the target within the same editor and scrolls it into view.
• Targeting: The target is the semantic HTML id. The editor's internal BlockNode.id and data-block-id are not used as anchor names.
• Exporting:
  • HTML import/export preserves links.
  • PrintPlugin ensures fragment links remain document-local in print/PDF output.
  • Markdown export preserves targets via htmlFallback: true. Disabling this fallback will drop htmlId because standard Markdown lacks block-level ID syntax.

await editor.setContentHTML(`
  <p><a href="#installation">Go to installation</a></p>
  <h2 id="installation">Installation</h2>
`);

The TextDirectionAutoPlugin operates through three distinct middleware behaviors that manage the dir attribute of blocks:

1. Auto-Detect: When text is inserted or deleted in a block with dir="auto", the plugin detects the dominant direction from the first strong directional character (using Unicode Script property escapes) and updates the block's dir. It supports over 20 RTL scripts (e.g., Arabic, Hebrew, Syriac).
2. Inherit Direction: When a new block is inserted (via Enter, paste, or insertNode), the plugin attempts to detect direction from the new content. If detection fails, it inherits the dir from the nearest sibling, ensuring seamless RTL writing.
3. Preserve Direction: When a block's type is changed (e.g., changing a paragraph to a heading via setBlockType), the plugin copies the existing non-'auto' dir attribute into the new block attributes so the user's direction setting is not lost during the transformation.

The Video Plugin is designed with a 'zero-contact' privacy model by default.

• Facade (Click-to-load): Enabled by default. No requests (including thumbnails) are made to the video provider until the user clicks 'Play'.
• Thumbnails: To use provider-specific thumbnails instead of the local placeholder, set useProviderThumbnail: true. Note that this breaks the zero-contact guarantee as it triggers a third-party request.
• Privacy-enhanced URLs: By default, the plugin uses privacy-friendly embed URLs (e.g., youtube-nocookie.com for YouTube and ?dnt=1 for Vimeo). To disable this and use standard URLs, set privacy: false.
• HTML Export: When exporting to HTML, the plugin produces a progressive-enhancement <figure> element with data-* attributes. This allows a notectl renderer to upgrade it to a video facade, while in other contexts, it degrades to a safe, privacy-preserving link.
• Security (DOMPurify): The plugin uses a DOMPurify hook to validate <iframe> src attributes. It only allows HTTPS schemes and hostnames that match your configured providers.