@shelamkoff/rector 1.0.0

package/dist/core/Diagnostics.js

@@ -0,0 +1,62 @@
+/**
+ * Content-free, opt-in production diagnostics.
+ * Consumer callbacks are isolated and can never break editor execution.
+ */
+export class Diagnostics {
+  /** @type {import('./types').EditorConfig['onDiagnostic']} */ #report
+  /** @type {import('./types').DiagnosticThresholds} */ #thresholds
+
+  /**
+   * @param {import('./types').EditorConfig['onDiagnostic']} report
+   * @param {import('./types').EditorConfig['diagnosticThresholds']} thresholds
+   */
+  constructor(report, thresholds = {}) {
+    this.#report = report
+    for (const [name, value] of Object.entries(thresholds)) {
+      if (!['commandMs', 'saveMs', 'renderMs', 'pasteMs'].includes(name)) continue
+      if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw new RangeError(`diagnosticThresholds.${name} must be a finite number greater than or equal to 0`)
+      }
+    }
+    this.#thresholds = {
+      commandMs: thresholds.commandMs ?? Infinity,
+      saveMs: thresholds.saveMs ?? Infinity,
+      renderMs: thresholds.renderMs ?? Infinity,
+      pasteMs: thresholds.pasteMs ?? Infinity,
+    }
+  }
+
+  get enabled() { return typeof this.#report === 'function' }
+
+  /** @param {keyof import('./types').DiagnosticThresholds} name */
+  threshold(name) { return this.#thresholds[name] }
+
+  now() {
+    return typeof performance !== 'undefined' && typeof performance.now === 'function'
+      ? performance.now()
+      : Date.now()
+  }
+
+  /**
+   * @param {import('./types').EditorDiagnosticCode} code
+   * @param {Omit<import('./types').EditorDiagnostic, 'code' | 'timestamp'>} [details]
+   */
+  emit(code, details = {}) {
+    if (!this.#report) return
+    const diagnostic = Object.freeze({
+      code,
+      timestamp: Date.now(),
+      ...details,
+    })
+    try {
+      this.#report(diagnostic)
+    } catch {
+      // Diagnostics are observational and must never affect editor behavior.
+    }
+  }
+
+  /** @param {unknown} error */
+  errorName(error) {
+    return error instanceof Error && error.name ? error.name : 'UnknownError'
+  }
+}

package/dist/core/DocumentSchema.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Validates document envelopes and applies an explicit, deterministic
+ * migration chain before data reaches plugins or the live block model.
+ */
+export class DocumentSchema {
+    /**
+     * @param {{
+     *   currentVersion?: string,
+     *   versionPolicy?: 'preserve' | 'strict',
+     *   migrations?: import('./types.js').DocumentMigration[],
+     *   diagnostics?: import('./Diagnostics.js').Diagnostics,
+     * }} [options]
+     */
+    constructor(options?: {
+        currentVersion?: string;
+        versionPolicy?: "preserve" | "strict";
+        migrations?: import("./types.js").DocumentMigration[];
+        diagnostics?: import("./Diagnostics.js").Diagnostics;
+    });
+    get currentVersion(): string;
+    /**
+     * Return an isolated, structurally valid document suitable for rendering.
+     * Consumer input and each migration stage remain ownership boundaries.
+     * @param {unknown} input
+     * @returns {import('./types.js').EditorDocument}
+     */
+    normalize(input: unknown): import("./types.js").EditorDocument;
+    #private;
+}

package/dist/core/DocumentSchema.js

@@ -0,0 +1,147 @@
+import { cloneEditorData } from '../shared/cloneEditorData.js'
+import { EDITOR_VERSION } from './constants.js'
+
+/**
+ * Validates document envelopes and applies an explicit, deterministic
+ * migration chain before data reaches plugins or the live block model.
+ */
+export class DocumentSchema {
+  /** @type {string} */ #currentVersion
+  /** @type {'preserve' | 'strict'} */ #versionPolicy
+  /** @type {Map<string, import('./types').DocumentMigration>} */ #migrations = new Map()
+  /** @type {import('./Diagnostics').Diagnostics | null} */ #diagnostics
+
+  /**
+   * @param {{
+   *   currentVersion?: string,
+   *   versionPolicy?: 'preserve' | 'strict',
+   *   migrations?: import('./types').DocumentMigration[],
+   *   diagnostics?: import('./Diagnostics').Diagnostics,
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.#currentVersion = options.currentVersion ?? EDITOR_VERSION
+    this.#versionPolicy = options.versionPolicy ?? 'preserve'
+    this.#diagnostics = options.diagnostics ?? null
+
+    for (const migration of options.migrations ?? []) {
+      this.#register(migration)
+    }
+  }
+
+  get currentVersion() { return this.#currentVersion }
+
+  /**
+   * Return an isolated, structurally valid document suitable for rendering.
+   * Consumer input and each migration stage remain ownership boundaries.
+   * @param {unknown} input
+   * @returns {import('./types').EditorDocument}
+   */
+  normalize(input) {
+    let document = this.#normalizeEnvelope(input)
+    const visited = new Set()
+
+    while (document.version !== this.#currentVersion) {
+      if (visited.has(document.version)) {
+        throw new Error(`Document migration cycle detected at version "${document.version}"`)
+      }
+      visited.add(document.version)
+
+      const migration = this.#migrations.get(document.version)
+      if (!migration) {
+        if (this.#versionPolicy === 'strict') {
+          this.#diagnostics?.emit('migration.unavailable', {
+            fromVersion: document.version,
+            toVersion: this.#currentVersion,
+          })
+          throw new Error(
+            `No document migration from version "${document.version}" to "${this.#currentVersion}"`,
+          )
+        }
+        return document
+      }
+
+      const source = cloneEditorData(document)
+      let migrated
+      try {
+        migrated = migration.migrate(source)
+      } catch (cause) {
+        this.#diagnostics?.emit('migration.failed', {
+          fromVersion: migration.from,
+          toVersion: migration.to,
+          errorName: this.#diagnostics.errorName(cause),
+        })
+        throw new Error(
+          `Document migration "${migration.from}" -> "${migration.to}" failed`,
+          { cause },
+        )
+      }
+      document = this.#normalizeEnvelope(migrated, migration.to)
+      this.#diagnostics?.emit('migration.applied', {
+        fromVersion: migration.from,
+        toVersion: migration.to,
+      })
+    }
+
+    return document
+  }
+
+  /** @param {import('./types').DocumentMigration} migration */
+  #register(migration) {
+    if (!migration || typeof migration !== 'object') {
+      throw new TypeError('Document migrations must be objects')
+    }
+    const { from, to, migrate } = migration
+    if (typeof from !== 'string' || !from || typeof to !== 'string' || !to) {
+      throw new TypeError('Document migrations require non-empty "from" and "to" versions')
+    }
+    if (from === to) throw new Error(`Document migration cannot target its own version "${from}"`)
+    if (typeof migrate !== 'function') {
+      throw new TypeError(`Document migration "${from}" -> "${to}" requires migrate()`)
+    }
+    if (this.#migrations.has(from)) {
+      throw new Error(`Duplicate document migration source version "${from}"`)
+    }
+    this.#migrations.set(from, migration)
+  }
+
+  /**
+   * @param {unknown} input
+   * @param {string} [forcedVersion]
+   * @returns {import('./types').EditorDocument}
+   */
+  #normalizeEnvelope(input, forcedVersion) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+      if (this.#versionPolicy === 'strict' || forcedVersion !== undefined) {
+        throw new TypeError('Editor document must be an object')
+      }
+      input = { blocks: [] }
+    }
+
+    const candidate = /** @type {Record<string, unknown>} */ (input)
+    let blocks = candidate.blocks
+    if (!Array.isArray(blocks)) {
+      if (this.#versionPolicy === 'strict' || forcedVersion !== undefined) {
+        throw new TypeError('Editor document "blocks" must be an array')
+      }
+      blocks = []
+    }
+
+    const declaredVersion = forcedVersion ?? candidate.version
+    const version = typeof declaredVersion === 'string' && declaredVersion
+      ? declaredVersion
+      : this.#currentVersion
+    const normalizedBlocks = /** @type {import('./types').BlockData[]} */ (
+      cloneEditorData(blocks)
+    )
+    /** @type {import('./types').EditorDocument} */
+    const normalized = {
+      version,
+      blocks: normalizedBlocks,
+    }
+    if (typeof candidate.time === 'number' && Number.isFinite(candidate.time)) {
+      normalized.time = candidate.time
+    }
+    return normalized
+  }
+}

package/dist/core/DocumentSnapshotStore.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Core-owned canonical document store.
+ *
+ * Internal snapshots structurally share unchanged block objects for history
+ * performance. Only isolated copies may cross the public API boundary.
+ */
+export class DocumentSnapshotStore {
+    /**
+     * @param {import('./types.js').IBlockReader} blocks
+     * @param {import('./InlinePluginRegistry.js').InlinePluginRegistry | null} inlinePluginRegistry
+     * @param {Pick<import('./types.js').EditorConfig, 'validationMode' | 'onValidationError'>} config
+     * @param {import('./Diagnostics.js').Diagnostics} [diagnostics]
+     * @param {string} [initialVersion]
+     */
+    constructor(blocks: import("./types.js").IBlockReader, inlinePluginRegistry: import("./InlinePluginRegistry.js").InlinePluginRegistry | null, config: Pick<import("./types.js").EditorConfig, "validationMode" | "onValidationError">, diagnostics?: import("./Diagnostics.js").Diagnostics, initialVersion?: string);
+    /** @param {string} version */
+    setDocumentVersion(version: string): void;
+    /** Return a consumer-owned document. */
+    save(): {
+        time: number;
+        version: string;
+        blocks: import("./types.js").BlockData<string, Record<string, unknown>>[];
+    };
+    /**
+     * Return a structurally shared core snapshot.
+     * @internal Never expose this result to consumers.
+     */
+    capture(): {
+        time: number;
+        version: string;
+        blocks: import("./types.js").BlockData<string, Record<string, unknown>>[];
+    };
+    #private;
+}

package/dist/core/DocumentSnapshotStore.js

@@ -0,0 +1,153 @@
+import { EDITOR_VERSION } from './constants.js'
+import { serializeInlineHtml } from '../shared/inlineMarshal.js'
+import { cloneEditorData } from '../shared/cloneEditorData.js'
+
+/**
+ * Core-owned canonical document store.
+ *
+ * Internal snapshots structurally share unchanged block objects for history
+ * performance. Only isolated copies may cross the public API boundary.
+ */
+export class DocumentSnapshotStore {
+  /** @type {import('./types').IBlockReader} */
+  #blocks
+
+  /** @type {import('./InlinePluginRegistry').InlinePluginRegistry | null} */
+  #inlinePluginRegistry
+
+  /** @type {'preserve' | 'strict'} */
+  #validationMode
+
+  /** @type {import('./types').EditorConfig['onValidationError']} */
+  #onValidationError
+
+  /** @type {WeakMap<import('./types').IBlock, { version: number, data: import('./types').BlockData }>} */
+  #cache = new WeakMap()
+
+  /** @type {import('./Diagnostics').Diagnostics | null} */
+  #diagnostics
+
+  /** @type {string} */
+  #documentVersion
+
+  /**
+   * @param {import('./types').IBlockReader} blocks
+   * @param {import('./InlinePluginRegistry').InlinePluginRegistry | null} inlinePluginRegistry
+   * @param {Pick<import('./types').EditorConfig, 'validationMode' | 'onValidationError'>} config
+   * @param {import('./Diagnostics').Diagnostics} [diagnostics]
+   * @param {string} [initialVersion]
+   */
+  constructor(blocks, inlinePluginRegistry, config, diagnostics, initialVersion = EDITOR_VERSION) {
+    this.#blocks = blocks
+    this.#inlinePluginRegistry = inlinePluginRegistry
+    this.#validationMode = config.validationMode ?? 'preserve'
+    this.#onValidationError = config.onValidationError
+    this.#diagnostics = diagnostics ?? null
+    this.#documentVersion = initialVersion
+  }
+
+  /** @param {string} version */
+  setDocumentVersion(version) {
+    this.#documentVersion = version
+  }
+
+  /** Return a consumer-owned document. */
+  save() {
+    return this.#build(true)
+  }
+
+  /**
+   * Return a structurally shared core snapshot.
+   * @internal Never expose this result to consumers.
+   */
+  capture() {
+    return this.#build(false)
+  }
+
+  /** @param {boolean} isolate */
+  #build(isolate) {
+    const startedAt = this.#diagnostics?.enabled ? this.#diagnostics.now() : 0
+    const snapshots = []
+    for (const block of this.#blocks) {
+      const canonical = this.#snapshotBlock(block)
+      snapshots.push(isolate ? cloneEditorData(canonical) : canonical)
+    }
+
+    const document = {
+      time: Date.now(),
+      version: this.#documentVersion,
+      blocks: snapshots,
+    }
+    if (startedAt && this.#diagnostics) {
+      const durationMs = this.#diagnostics.now() - startedAt
+      if (durationMs >= this.#diagnostics.threshold('saveMs')) {
+        this.#diagnostics.emit('save.slow', { durationMs })
+      }
+    }
+    return document
+  }
+
+  /** @param {import('./types').IBlock} block */
+  #snapshotBlock(block) {
+    const cached = this.#cache.get(block)
+    if (cached?.version === block.version) return cached.data
+
+    let snapshot
+    try {
+      snapshot = block.save()
+    } catch (cause) {
+      this.#diagnostics?.emit('save.failed', {
+        blockType: block.type,
+        errorName: this.#diagnostics.errorName(cause),
+      })
+      throw new Error(`[DocumentSnapshotStore] Failed to save block ${block.id} (${block.type})`, { cause })
+    }
+
+    const registry = this.#inlinePluginRegistry
+    if (registry && typeof block.plugin.mapTextFields === 'function') {
+      /** @type {Record<string, import('../renderer/types').InlineWidget>} */
+      const inline = {}
+      const usedInlineIds = new Set()
+      block.plugin.mapTextFields(
+        /** @type {Record<string, unknown>} */ (snapshot.data),
+        (html) => {
+          const result = serializeInlineHtml(html, registry, usedInlineIds)
+          for (const [id, widget] of Object.entries(result.inline)) {
+            Object.defineProperty(inline, id, {
+              value: widget,
+              enumerable: true,
+              configurable: true,
+              writable: true,
+            })
+          }
+          return result.html
+        },
+      )
+      if (Object.keys(inline).length > 0) snapshot.inline = inline
+    }
+
+    if (typeof block.plugin.validate === 'function') {
+      let valid
+      try {
+        valid = block.plugin.validate(snapshot.data)
+      } catch {
+        valid = false
+      }
+      if (!valid) {
+        const issue = {
+          blockId: block.id,
+          type: block.type,
+          data: cloneEditorData(snapshot.data),
+        }
+        this.#onValidationError?.(issue)
+        if (this.#validationMode === 'strict') {
+          throw new Error('Invalid block data for "' + block.type + '" (' + block.id + ')')
+        }
+      }
+    }
+
+    const canonical = cloneEditorData(snapshot)
+    this.#cache.set(block, { version: block.version, data: canonical })
+    return canonical
+  }
+}

package/dist/core/DragManager.d.ts

@@ -0,0 +1,17 @@
+export class DragManager {
+    /**
+     * @param {HTMLElement} rootEl
+     * @param {import('./types.js').IBlockManager} blocks
+     * @param {HTMLElement} dragHandle
+     * @param {import('./types.js').IEventBus} events
+     * @param {{ threshold: number }} [tuning]
+     */
+    constructor(rootEl: HTMLElement, blocks: import("./types.js").IBlockManager, dragHandle: HTMLElement, events: import("./types.js").IEventBus, tuning?: {
+        threshold: number;
+    });
+    /**
+     * Clean up.
+     */
+    destroy(): void;
+    #private;
+}

package/dist/core/DragManager.js

@@ -0,0 +1,223 @@
+import { el } from './dom.js'
+import { EditorEvent } from './editorEvents.js'
+
+export class DragManager {
+  /** @type {HTMLElement} */
+  #rootEl
+
+  /** @type {import('./types').IBlockManager} */
+  #blocks
+
+  /** @type {HTMLElement} */
+  #dragHandle
+
+  /** @type {import('./types').IEventBus} */
+  #events
+
+  /** @type {import('./types').IBlock | null} */
+  #draggingBlock = null
+
+  /** @type {HTMLElement} */
+  #dropIndicator
+
+  /** @type {number} */
+  #dropIndex = -1
+
+  /** @type {boolean} */
+  #isDragging = false
+
+  /** @type {boolean} track if mousedown handled the current interaction */
+  #mouseDownHandled = false
+
+  /** @type {number} */
+  #startX = 0
+
+  /** @type {number} */
+  #startY = 0
+
+  /** @type {number} */
+  #threshold
+
+  /**
+   * @param {HTMLElement} rootEl
+   * @param {import('./types').IBlockManager} blocks
+   * @param {HTMLElement} dragHandle
+   * @param {import('./types').IEventBus} events
+   * @param {{ threshold: number }} [tuning]
+   */
+  constructor(rootEl, blocks, dragHandle, events, tuning) {
+    this.#rootEl = rootEl
+    this.#blocks = blocks
+    this.#dragHandle = dragHandle
+    this.#events = events
+    this.#threshold = tuning?.threshold ?? 5
+
+    this.#dropIndicator = el('div', 'oe-drop-indicator')
+    this.#dropIndicator.style.display = 'none'
+    rootEl.appendChild(this.#dropIndicator)
+
+    this.#dragHandle.addEventListener('mousedown', this.#onMouseDown)
+    // Capture-phase click: stop propagation to prevent BlockSettingsMenu
+    // from closing the menu that was just opened by the mouseup callback
+    this.#dragHandle.addEventListener('click', this.#onClick, true)
+  }
+
+  /**
+   * Clean up.
+   */
+  destroy() {
+    if (this.#isDragging && this.#draggingBlock) {
+      this.#draggingBlock.element.classList.remove('oe-block--dragging')
+      this.#draggingBlock = null
+      this.#isDragging = false
+      this.#dragHandle.style.cursor = ''
+      document.body.style.cursor = ''
+    }
+
+    this.#dragHandle.removeEventListener('mousedown', this.#onMouseDown)
+    this.#dragHandle.removeEventListener('click', this.#onClick, true)
+    this.#dropIndicator.remove()
+    document.removeEventListener('mousemove', this.#onMouseMove)
+    document.removeEventListener('mouseup', this.#onMouseUp)
+  }
+
+  /**
+   * Fallback: handle click when mousedown wasn't fired.
+   * Skipped if mousedown already handled the interaction.
+   * @param {MouseEvent} e
+   */
+  #onClick = (e) => {
+    // Always stop propagation on the drag handle click
+    // to prevent BlockSettingsMenu from closing a just-opened menu
+    e.stopPropagation()
+    if (this.#mouseDownHandled) {
+      this.#mouseDownHandled = false
+    }
+  }
+
+  /**
+   * @param {MouseEvent} e
+   */
+  #onMouseDown = (e) => {
+    if (e.button !== 0) return
+    e.preventDefault()
+    e.stopPropagation()
+
+    this.#mouseDownHandled = true
+    this.#startX = e.clientX
+    this.#startY = e.clientY
+    this.#isDragging = false
+
+    document.addEventListener('mousemove', this.#onMouseMove)
+    document.addEventListener('mouseup', this.#onMouseUp)
+  }
+
+  /**
+   * @param {MouseEvent} e
+   */
+  #onMouseMove = (e) => {
+    if (!this.#isDragging) {
+      const dx = Math.abs(e.clientX - this.#startX)
+      const dy = Math.abs(e.clientY - this.#startY)
+      if (dx + dy < this.#threshold) return
+
+      // Threshold exceeded: start dragging only when another block exists.
+      if (this.#blocks.getBlockCount() <= 1) return
+      this.#isDragging = true
+      this.#startDrag()
+    }
+
+    this.#updateDragPosition(e)
+  }
+
+  /**
+   * @param {MouseEvent} _e
+   */
+  #onMouseUp = (_e) => {
+    document.removeEventListener('mousemove', this.#onMouseMove)
+    document.removeEventListener('mouseup', this.#onMouseUp)
+
+    if (this.#isDragging) {
+      this.#endDrag()
+    } else {
+      // No drag: the mousedown was just a click on the handle.
+      // Announce via event bus so Toolbar (or any listener) can open its menu.
+      this.#events.emit(EditorEvent.DRAG_HANDLE_CLICKED)
+    }
+
+    this.#isDragging = false
+  }
+
+  #startDrag() {
+    const block = this.#blocks.getCurrentBlock()
+    if (!block) return
+
+    this.#draggingBlock = block
+    block.element.classList.add('oe-block--dragging')
+    this.#dragHandle.style.cursor = 'grabbing'
+    document.body.style.cursor = 'grabbing'
+  }
+
+  /**
+   * @param {MouseEvent} e
+   */
+  #updateDragPosition(e) {
+    if (!this.#draggingBlock) return
+
+    const editorRect = this.#rootEl.getBoundingClientRect()
+    const children = []
+    for (let index = 0; index < this.#blocks.getBlockCount(); index++) {
+      const block = this.#blocks.getBlockByIndex(index)
+      if (block) children.push(block.element)
+    }
+
+    let closestIndex = children.length
+    let closestDist = Infinity
+
+    for (let i = 0; i < children.length; i++) {
+      const child = /** @type {HTMLElement} */ (children[i])
+      const rect = child.getBoundingClientRect()
+      const midY = rect.top + rect.height / 2
+
+      const dist = Math.abs(e.clientY - midY)
+      if (dist < closestDist) {
+        closestDist = dist
+        closestIndex = e.clientY < midY ? i : i + 1
+      }
+    }
+
+    this.#dropIndex = closestIndex
+
+    this.#dropIndicator.style.display = ''
+
+    if (closestIndex < children.length) {
+      const referenceElement = /** @type {HTMLElement} */ (children[closestIndex])
+      const refRect = referenceElement.getBoundingClientRect()
+      this.#dropIndicator.style.top = `${refRect.top - editorRect.top - 2}px`
+    } else if (children.length > 0) {
+      const lastElement = /** @type {HTMLElement} */ (children[children.length - 1])
+      const lastRect = lastElement.getBoundingClientRect()
+      this.#dropIndicator.style.top = `${lastRect.bottom - editorRect.top + 2}px`
+    }
+  }
+
+  #endDrag() {
+    this.#dropIndicator.style.display = 'none'
+    this.#dragHandle.style.cursor = ''
+    document.body.style.cursor = ''
+
+    if (this.#draggingBlock) {
+      this.#draggingBlock.element.classList.remove('oe-block--dragging')
+
+      const fromIndex = this.#blocks.getBlockIndex(this.#draggingBlock.id)
+      const toIndex = this.#dropIndex
+
+      if (fromIndex >= 0 && toIndex >= 0 && fromIndex !== toIndex && toIndex !== fromIndex + 1) {
+        this.#blocks.move(fromIndex, toIndex)
+      }
+
+      this.#draggingBlock = null
+      this.#dropIndex = -1
+    }
+  }
+}