@shelamkoff/rector 1.0.0

package/dist/plugins/image/uploader.js

@@ -0,0 +1,92 @@
+import { sanitizeMediaUrl } from '../../shared/sanitize/sanitizeUrl.js'
+
+/**
+ * @typedef {(file: File, context: { signal: AbortSignal }) => Promise<{ url: string, alt?: string }>} UploadFn
+ */
+
+/**
+ * Resolve an image file through the consumer upload callback or a local data
+ * URL fallback. The caller owns visual loading state so an older operation
+ * cannot clear the indicator for a newer one. Failures leave data unchanged.
+ */
+export class ImageUploader {
+  /** @type {UploadFn | undefined} */
+  #uploadFn
+
+  /** @param {{ uploadFile?: UploadFn }} config */
+  constructor(config) {
+    this.#uploadFn = config.uploadFile
+  }
+
+  /**
+   * @param {File} file
+   * @param {(result: { url: string, alt?: string }) => void} onResolve
+   * @param {AbortSignal | undefined} signal
+   * @returns {Promise<void>}
+   */
+  async handle(file, onResolve, signal) {
+    if (signal?.aborted) return
+    if (this.#uploadFn) {
+      await this.#uploadRemote(file, onResolve, signal)
+    } else {
+      await this.#readDataUrl(file, onResolve, signal)
+    }
+  }
+
+  /**
+   * @param {File} file
+   * @param {(result: { url: string, alt?: string }) => void} onResolve
+   * @param {AbortSignal | undefined} signal
+   * @returns {Promise<void>}
+   */
+  async #uploadRemote(file, onResolve, signal) {
+    if (!this.#uploadFn) return
+    try {
+      const result = await this.#uploadFn(file, { signal: signal ?? new AbortController().signal })
+      const url = sanitizeMediaUrl(result?.url || '')
+      if (!signal?.aborted && url) {
+        onResolve({ url, alt: typeof result?.alt === 'string' ? result.alt : undefined })
+      }
+    } catch {
+      // Upload failed or was cancelled; keep the current image data.
+    }
+  }
+
+  /**
+   * @param {File} file
+   * @param {(result: { url: string, alt?: string }) => void} onResolve
+   * @param {AbortSignal | undefined} signal
+   * @returns {Promise<void>}
+   */
+  #readDataUrl(file, onResolve, signal) {
+    return new Promise((resolve) => {
+      const reader = new FileReader()
+      let settled = false
+      const finish = () => {
+        if (settled) return
+        settled = true
+        signal?.removeEventListener('abort', abort)
+        resolve()
+      }
+      const abort = () => reader.abort()
+      signal?.addEventListener('abort', abort, { once: true })
+
+      reader.onload = () => {
+        try {
+          const url = typeof reader.result === 'string' ? sanitizeMediaUrl(reader.result) : ''
+          if (!signal?.aborted && url) onResolve({ url })
+        } finally {
+          finish()
+        }
+      }
+      reader.onerror = finish
+      reader.onabort = finish
+
+      try {
+        reader.readAsDataURL(file)
+      } catch {
+        finish()
+      }
+    })
+  }
+}

package/dist/plugins/image/view-empty.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @typedef {Object} EmptyViewDeps
+ * @property {(key: string, fallback: string) => string} t
+ * @property {boolean} readOnly
+ * @property {(file: File) => void} onFileDropped
+ * @property {() => void} onUploadClick
+ * @property {Array<{ icon?: string, label: string, handler: (context: { signal: AbortSignal }) => Promise<{url: string, alt?: string} | null> }>} customActions
+ * @property {(handler: (context: { signal: AbortSignal }) => Promise<{url: string, alt?: string} | null>) => Promise<void>} runCustomAction
+ */
+/**
+ * Render the empty-state dropzone view into `wrapper`.
+ * Replaces the wrapper's contents and removes the `filled` class.
+ *
+ * Listeners are attached with the state's AbortSignal so they're
+ * automatically removed on the next render or on disposal.
+ *
+ * @param {HTMLElement} wrapper
+ * @param {import('./state.js').ImageState} state
+ * @param {EmptyViewDeps} deps
+ * @returns {void}
+ */
+export function renderEmptyView(wrapper: HTMLElement, state: import("./state.js").ImageState, deps: EmptyViewDeps): void;
+export type EmptyViewDeps = {
+    t: (key: string, fallback: string) => string;
+    readOnly: boolean;
+    onFileDropped: (file: File) => void;
+    onUploadClick: () => void;
+    customActions: Array<{
+        icon?: string;
+        label: string;
+        handler: (context: {
+            signal: AbortSignal;
+        }) => Promise<{
+            url: string;
+            alt?: string;
+        } | null>;
+    }>;
+    runCustomAction: (handler: (context: {
+        signal: AbortSignal;
+    }) => Promise<{
+        url: string;
+        alt?: string;
+    } | null>) => Promise<void>;
+};

package/dist/plugins/image/view-empty.js

@@ -0,0 +1,61 @@
+import { renderDropzone } from '../shared/dropzone.js'
+import { isSupportedImageFile } from '../shared/fileInput.js'
+import { CSS } from './css.js'
+import { ICON_SELECT } from './icons.js'
+
+/**
+ * @typedef {Object} EmptyViewDeps
+ * @property {(key: string, fallback: string) => string} t
+ * @property {boolean} readOnly
+ * @property {(file: File) => void} onFileDropped
+ * @property {() => void} onUploadClick
+ * @property {Array<{ icon?: string, label: string, handler: (context: { signal: AbortSignal }) => Promise<{url: string, alt?: string} | null> }>} customActions
+ * @property {(handler: (context: { signal: AbortSignal }) => Promise<{url: string, alt?: string} | null>) => Promise<void>} runCustomAction
+ */
+
+/**
+ * Render the empty-state dropzone view into `wrapper`.
+ * Replaces the wrapper's contents and removes the `filled` class.
+ *
+ * Listeners are attached with the state's AbortSignal so they're
+ * automatically removed on the next render or on disposal.
+ *
+ * @param {HTMLElement} wrapper
+ * @param {import('./state.js').ImageState} state
+ * @param {EmptyViewDeps} deps
+ * @returns {void}
+ */
+export function renderEmptyView(wrapper, state, deps) {
+  state.resetTransient()
+
+  const signal = /** @type {AbortController} */ (state.abortController).signal
+
+  renderDropzone(wrapper, signal, {
+    select: CSS.select,
+    selectIcon: CSS.selectIcon,
+    selectText: CSS.selectText,
+    selectLink: CSS.selectLink,
+    selectActions: CSS.selectActions,
+    selectAction: CSS.selectAction,
+    dropzoneActive: CSS.dropzoneActive,
+    filled: CSS.filled,
+  }, {
+    iconHtml: ICON_SELECT,
+    uploadText: deps.t('dropzoneUpload', 'Upload'),
+    afterText: deps.t('dropzoneText', 'an image from your device or drag and drop it here'),
+    readOnly: deps.readOnly,
+    emptyText: deps.t('emptyReadonly', 'No image'),
+    onUploadClick: deps.onUploadClick,
+    actions: deps.customActions.map(action => ({
+      icon: action.icon,
+      label: action.label,
+      onSelect: () => { void deps.runCustomAction(action.handler) },
+    })),
+    onDrop: (dt) => {
+      const file = dt.files[0]
+      if (file && isSupportedImageFile(file)) {
+        deps.onFileDropped(file)
+      }
+    },
+  })
+}

package/dist/plugins/image/view-filled.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @typedef {Object} FilledViewDeps
+ * @property {(key: string, fallback: string) => string} t
+ * @property {boolean} readOnly
+ * @property {() => void} onTriggerFileInput
+ * @property {() => void} onPromptUrl
+ * @property {() => void} onDelete
+ * @property {(operation: () => void) => void} mutate
+ * @property {Array<{ icon?: string, label: string, handler: (context: { signal: AbortSignal }) => Promise<{url: string, alt?: string} | null> }>} customActions
+ * @property {(handler: (context: { signal: AbortSignal }) => Promise<{url: string, alt?: string} | null>) => Promise<void>} runCustomAction
+ */
+/**
+ * Render the filled-state image view: image + container + editable caption +
+ * action bar (settings, replace, delete). Replaces wrapper contents and
+ * adds the `filled` CSS class.
+ *
+ * Listeners use the state's AbortSignal — automatically removed on the next
+ * render or on disposal.
+ *
+ * @param {HTMLElement} wrapper
+ * @param {import('./state.js').ImageState} state
+ * @param {FilledViewDeps} deps
+ * @returns {void}
+ */
+export function renderFilledView(wrapper: HTMLElement, state: import("./state.js").ImageState, deps: FilledViewDeps): void;
+export type FilledViewDeps = {
+    t: (key: string, fallback: string) => string;
+    readOnly: boolean;
+    onTriggerFileInput: () => void;
+    onPromptUrl: () => void;
+    onDelete: () => void;
+    mutate: (operation: () => void) => void;
+    customActions: Array<{
+        icon?: string;
+        label: string;
+        handler: (context: {
+            signal: AbortSignal;
+        }) => Promise<{
+            url: string;
+            alt?: string;
+        } | null>;
+    }>;
+    runCustomAction: (handler: (context: {
+        signal: AbortSignal;
+    }) => Promise<{
+        url: string;
+        alt?: string;
+    } | null>) => Promise<void>;
+};

package/dist/plugins/image/view-filled.js

@@ -0,0 +1,282 @@
+import { sanitizeHtml } from '../../core/sanitize.js'
+import { setSafeUrlAttribute } from '../../shared/sanitize/sanitizeUrl.js'
+import { makeActionBtn as _makeActionBtn, makeSep as _makeSep } from '../shared/actionBar.js'
+import { CSS } from './css.js'
+import {
+  ICON_BACK, ICON_CHEVRON_RIGHT, ICON_REPLACE, ICON_SETTINGS, ICON_TRASH,
+  ICON_UPLOAD, ICON_URL,
+} from './icons.js'
+import { applyInlineStyles } from './styles.js'
+import { buildSettingsPanel } from './settings.js'
+
+/**
+ * @typedef {Object} FilledViewDeps
+ * @property {(key: string, fallback: string) => string} t
+ * @property {boolean} readOnly
+ * @property {() => void} onTriggerFileInput
+ * @property {() => void} onPromptUrl
+ * @property {() => void} onDelete
+ * @property {(operation: () => void) => void} mutate
+ * @property {Array<{ icon?: string, label: string, handler: (context: { signal: AbortSignal }) => Promise<{url: string, alt?: string} | null> }>} customActions
+ * @property {(handler: (context: { signal: AbortSignal }) => Promise<{url: string, alt?: string} | null>) => Promise<void>} runCustomAction
+ */
+
+/**
+ * Render the filled-state image view: image + container + editable caption +
+ * action bar (settings, replace, delete). Replaces wrapper contents and
+ * adds the `filled` CSS class.
+ *
+ * Listeners use the state's AbortSignal — automatically removed on the next
+ * render or on disposal.
+ *
+ * @param {HTMLElement} wrapper
+ * @param {import('./state.js').ImageState} state
+ * @param {FilledViewDeps} deps
+ * @returns {void}
+ */
+export function renderFilledView(wrapper, state, deps) {
+  state.resetTransient()
+  wrapper.innerHTML = ''
+  wrapper.classList.add(CSS.filled)
+
+  const signal = /** @type {AbortController} */ (state.abortController).signal
+
+  const container = document.createElement('div')
+  container.className = CSS.imageContainer
+
+  const img = document.createElement('img')
+  img.className = CSS.image
+  setSafeUrlAttribute(img, 'src', state.data.file.url, 'media')
+  applyInlineStyles(state, img, container)
+  container.appendChild(img)
+
+  // Caption
+  const caption = renderCaption(state, signal, deps)
+  img.alt = caption.textContent?.trim() || ''
+  if (!deps.readOnly) {
+    caption.addEventListener('input', () => {
+      img.alt = caption.textContent?.trim() || ''
+    }, { signal })
+  }
+  container.appendChild(caption)
+  wrapper.appendChild(container)
+
+  // Action bar
+  if (!deps.readOnly) wrapper.appendChild(renderActions(wrapper, state, deps, signal))
+}
+
+/**
+ * @param {import('./state.js').ImageState} state
+ * @param {AbortSignal} signal
+ * @param {FilledViewDeps} deps
+ * @returns {HTMLElement}
+ */
+function renderCaption(state, signal, deps) {
+  const caption = document.createElement('div')
+  caption.className = CSS.caption
+  caption.contentEditable = deps.readOnly ? 'false' : 'true'
+  caption.dataset.placeholder = deps.t('caption', 'Caption')
+
+  if (state.data.caption) {
+    caption.innerHTML = sanitizeHtml(state.data.caption)
+  }
+  if (!caption.textContent?.trim()) {
+    state.data.caption = ''
+    caption.innerHTML = ''
+    caption.setAttribute('data-empty', 'true')
+  }
+
+  const syncEmpty = () => {
+    const hasText = !!caption.textContent?.trim()
+    state.data.caption = hasText ? caption.innerHTML : ''
+    if (hasText) {
+      caption.removeAttribute('data-empty')
+    } else {
+      caption.setAttribute('data-empty', 'true')
+    }
+  }
+
+  if (!deps.readOnly) {
+    caption.addEventListener('input', syncEmpty, { signal })
+    caption.addEventListener('focus', () => caption.removeAttribute('data-empty'), { signal })
+    caption.addEventListener('blur', () => {
+      if (!caption.textContent?.trim()) {
+        caption.innerHTML = ''
+        caption.setAttribute('data-empty', 'true')
+        state.data.caption = ''
+      }
+    }, { signal })
+    caption.addEventListener('keydown', (e) => {
+      if (e.key === 'Backspace' && !caption.textContent?.trim()) {
+        e.preventDefault()
+        e.stopPropagation()
+      }
+    }, { signal })
+  }
+
+  return caption
+}
+
+/**
+ * @param {HTMLElement} wrapper
+ * @param {import('./state.js').ImageState} state
+ * @param {FilledViewDeps} deps
+ * @param {AbortSignal} signal
+ * @returns {HTMLElement}
+ */
+function renderActions(wrapper, state, deps, signal) {
+  const actions = document.createElement('div')
+  actions.className = CSS.actions
+
+  const settingsDeps = { t: deps.t, mutate: deps.mutate }
+
+  // Settings dropdown
+  const dropdown = document.createElement('div')
+  dropdown.className = CSS.dropdown
+
+  const settingsBtn = document.createElement('button')
+  settingsBtn.type = 'button'
+  settingsBtn.className = CSS.actionBtn
+  settingsBtn.innerHTML = `${ICON_SETTINGS} ${deps.t('settings', 'Settings')}`
+  settingsBtn.setAttribute('aria-haspopup', 'true')
+  settingsBtn.setAttribute('aria-expanded', 'false')
+
+  const panel = buildSettingsPanel(wrapper, state, settingsDeps)
+  panel.setAttribute('role', 'group')
+  panel.setAttribute('aria-label', deps.t('settings', 'Settings'))
+
+  settingsBtn.addEventListener('click', (e) => {
+    e.stopPropagation()
+    const isOpen = dropdown.classList.contains(CSS.dropdownOpen)
+    if (isOpen) {
+      dropdown.classList.remove(CSS.dropdownOpen)
+      settingsBtn.setAttribute('aria-expanded', 'false')
+    } else {
+      panel.style.top = ''
+      panel.style.bottom = ''
+      dropdown.classList.add(CSS.dropdownOpen)
+      settingsBtn.setAttribute('aria-expanded', 'true')
+
+      const btnRect = settingsBtn.getBoundingClientRect()
+      const panelRect = panel.getBoundingClientRect()
+      const spaceBelow = window.innerHeight - btnRect.bottom - 8
+      if (spaceBelow < panelRect.height) {
+        panel.style.top = ''
+        panel.style.bottom = 'calc(100% + 8px)'
+      } else {
+        panel.style.top = 'calc(100% + 8px)'
+        panel.style.bottom = ''
+      }
+    }
+  }, { signal })
+
+  dropdown.append(settingsBtn, panel)
+
+  document.addEventListener('click', (e) => {
+    if (!dropdown.contains(/** @type {Node} */ (e.target))) {
+      dropdown.classList.remove(CSS.dropdownOpen)
+      settingsBtn.setAttribute('aria-expanded', 'false')
+    }
+  }, { signal })
+
+  dropdown.addEventListener('keydown', (event) => {
+    if (event.key !== 'Escape' || !dropdown.classList.contains(CSS.dropdownOpen)) return
+    event.preventDefault()
+    dropdown.classList.remove(CSS.dropdownOpen)
+    settingsBtn.setAttribute('aria-expanded', 'false')
+    settingsBtn.focus()
+  }, { signal })
+
+  const sep1 = makeSep()
+
+  // Main view container (for drill-down hide/show)
+  const mainView = document.createElement('div')
+  mainView.className = CSS.actionsView
+  mainView.style.display = 'contents'
+
+  mainView.append(dropdown, sep1)
+
+  // Replace (drill-down: Upload + URL)
+  const replaceBtn = makeActionBtn(
+    `${ICON_REPLACE} ${deps.t('replace', 'Replace')} ${ICON_CHEVRON_RIGHT}`,
+    () => showReplaceView(actions, mainView, deps, signal),
+    signal,
+  )
+  replaceBtn.querySelector('svg:last-child')?.classList.add(CSS.actionChevron)
+  mainView.appendChild(replaceBtn)
+
+  mainView.appendChild(makeSep())
+
+  // Delete (icon only)
+  const deleteBtn = document.createElement('button')
+  deleteBtn.type = 'button'
+  deleteBtn.className = `${CSS.actionBtn} ${CSS.actionBtnDanger}`
+  deleteBtn.innerHTML = ICON_TRASH
+  deleteBtn.setAttribute('aria-label', deps.t('delete', 'Delete'))
+  deleteBtn.addEventListener('mousedown', (e) => e.preventDefault(), { signal })
+  deleteBtn.addEventListener('click', (e) => {
+    e.stopPropagation()
+    deps.onDelete()
+  }, { signal })
+  mainView.appendChild(deleteBtn)
+
+  actions.appendChild(mainView)
+  return actions
+}
+
+/**
+ * Show the Replace drill-down: Back | Upload | Custom actions | URL.
+ *
+ * @param {HTMLElement} actions
+ * @param {HTMLElement} mainView
+ * @param {FilledViewDeps} deps
+ * @param {AbortSignal} signal
+ */
+function showReplaceView(actions, mainView, deps, signal) {
+  mainView.style.display = 'none'
+
+  const view = document.createElement('div')
+  view.className = CSS.actionsView
+  view.style.display = 'contents'
+
+  const restore = () => { view.remove(); mainView.style.display = 'contents' }
+
+  view.appendChild(makeActionBtn(
+    `${ICON_BACK} ${deps.t('back', 'Back')}`,
+    restore,
+    signal,
+  ))
+  view.appendChild(makeSep())
+
+  view.appendChild(makeActionBtn(
+    `${ICON_UPLOAD} ${deps.t('upload', 'Upload')}`,
+    () => { deps.onTriggerFileInput(); restore() },
+    signal,
+  ))
+
+  for (const action of deps.customActions) {
+    view.appendChild(makeActionBtn(
+      `${action.icon || ''} ${action.label}`.trim(),
+      async () => { await deps.runCustomAction(action.handler); restore() },
+      signal,
+    ))
+  }
+
+  view.appendChild(makeActionBtn(
+    `${ICON_URL} URL`,
+    () => { deps.onPromptUrl(); restore() },
+    signal,
+  ))
+
+  actions.appendChild(view)
+}
+
+/** @param {string} innerHTML @param {() => void} handler @param {AbortSignal} signal */
+function makeActionBtn(innerHTML, handler, signal) {
+  return _makeActionBtn(CSS.actionBtn, innerHTML, handler, signal)
+}
+
+/** @returns {HTMLDivElement} */
+function makeSep() {
+  return _makeSep(CSS.actionsSep)
+}

package/dist/plugins/index.d.ts

@@ -0,0 +1,21 @@
+export { Paragraph } from "./paragraph/index.js";
+export { Heading } from "./heading/index.js";
+export { List } from "./list/index.js";
+export { Quote } from "./quote/index.js";
+export { Code } from "./code/index.js";
+export { Image } from "./image/index.js";
+export { Embed } from "./embed/index.js";
+export { Gallery } from "./gallery/index.js";
+export { Checklist } from "./checklist/index.js";
+export { Warning } from "./warning/index.js";
+export { Raw } from "./raw/index.js";
+export { Poll } from "./poll/index.js";
+export { Person } from "./person/index.js";
+export { Attaches } from "./attaches/index.js";
+export { LinkPreview } from "./link-preview/index.js";
+export { Toggle } from "./toggle/index.js";
+export { Columns } from "./columns/index.js";
+export { Spoiler } from "./spoiler/index.js";
+export { Delimiter } from "./delimiter/index.js";
+export { Table } from "./table/index.js";
+export { CarouselBlock, CarouselBlock as Carousel } from "./carousel/index.js";

package/dist/plugins/index.js

@@ -0,0 +1,22 @@
+export { Paragraph } from './paragraph/index.js'
+export { Heading } from './heading/index.js'
+export { List } from './list/index.js'
+export { Quote } from './quote/index.js'
+export { Code } from './code/index.js'
+export { Image } from './image/index.js'
+export { Embed } from './embed/index.js'
+export { Gallery } from './gallery/index.js'
+export { CarouselBlock } from './carousel/index.js'
+export { CarouselBlock as Carousel } from './carousel/index.js'
+export { Checklist } from './checklist/index.js'
+export { Warning } from './warning/index.js'
+export { Raw } from './raw/index.js'
+export { Poll } from './poll/index.js'
+export { Person } from './person/index.js'
+export { Attaches } from './attaches/index.js'
+export { LinkPreview } from './link-preview/index.js'
+export { Toggle } from './toggle/index.js'
+export { Columns } from './columns/index.js'
+export { Spoiler } from './spoiler/index.js'
+export { Delimiter } from './delimiter/index.js'
+export { Table } from './table/index.js'

package/dist/plugins/link-preview/README.md

@@ -0,0 +1,69 @@
+# LinkPreview block plugin
+
+Link preview card with seven visual templates and optional application-provided metadata.
+
+## Install and register
+
+```bash
+npm install @shelamkoff/rector
+```
+
+```js
+import { createEditor } from '@shelamkoff/rector'
+import { LinkPreview } from '@shelamkoff/rector/plugins/link-preview'
+import '@shelamkoff/rector/styles/editor.css'
+
+const editor = createEditor({
+  holder: document.querySelector('#editor'),
+  plugins: [new LinkPreview()],
+})
+```
+
+The registered block type is `linkPreview`. The class is also exported by the complete `@shelamkoff/rector/plugins` preset and can be loaded through `@shelamkoff/rector/plugins/async`.
+
+## Data
+
+```json
+{
+  "url": "https://example.com",
+  "title": "Example",
+  "description": "",
+  "image": "",
+  "favicon": "",
+  "domain": "example.com",
+  "template": "notion"
+}
+```
+
+### Field reference
+
+| Field | Required | Meaning and constraints |
+| --- | --- | --- |
+| `url` | yes | Canonical HTTP(S) external URL. |
+| `title`, `description`, `domain` | no | Metadata strings; empty values are allowed. |
+| `image`, `favicon` | no | Empty strings or canonical media-policy URLs. |
+| `template` | no | `horizontal`, `compact`, `large-top`, `minimal`, `twitter`, `notion`, or `split`; the editor and renderer default to `notion`. |
+
+`template` accepts `horizontal`, `compact`, `large-top`, `minimal`, `twitter`, `notion`, or `split`. Only HTTP(S) links are accepted. Returned image and favicon addresses pass the shared media URL policy.
+
+## Configuration
+
+Every built-in block plugin accepts two style ownership options: `injectStyles?: boolean` defaults to `true`; set it to `false` when the host bundles that plugin's CSS. `css?: string` adds one host-provided stylesheet URL after the plugin default, or acts as the replacement URL when default injection is disabled.
+
+`fetchMeta?: (url: string, context: { signal: AbortSignal }) => Promise<{ title?: string; description?: string; image?: string; favicon?: string; domain?: string }>` resolves metadata in application code and must stop work when the supplied signal is aborted. Without this callback, the plugin performs no metadata request: it keeps the sanitized URL, derives `domain`, and leaves the other metadata fields empty until the application or a loaded document supplies them.
+
+When `fetchMeta` is configured, entering a new URL starts one cancellable resolution. The plugin commits the URL and the normalized metadata together after the callback settles, so one URL entry remains one undo/redo step. If resolution fails, the sanitized URL is still committed without optional metadata. A newer URL or block disposal aborts the older request and prevents stale data from being committed.
+
+## Capabilities
+
+URL paste; async metadata; template selector; safe URL assignment and cleanup. Clicking the card never navigates away while the block is editable. The card becomes a normal external link in read-only editor mode and in rendered output.
+
+## Undo, lifecycle, and styles
+
+User actions exposed by the plugin enter the command pipeline through the supplied `context.mutate()` capability, so each completed action is one undo/redo step. The editor reference-counts the plugin's declared stylesheet URLs. Removing a block calls its cleanup hook; removing the editor calls `destroy()` for every remaining block and then releases shared plugin resources.
+
+Do not remove the editor holder without first calling `editor.destroy()`.
+
+## Document output
+
+Use the matching renderer from `@shelamkoff/rector/renderer/renderers/link-preview`. The VitePress guide documents configuration, commands and history, extension contracts, document migrations, styling, security, and lifecycle in a sequential form.