@shelamkoff/rector 1.0.0

package/dist/shared/sanitize/sanitizeStyle.js

@@ -0,0 +1,39 @@
+import { ALLOWED_STYLE_PROPS } from './allowlist.js'
+
+/**
+ * Sanitize an inline `style` attribute value.
+ * Keeps only whitelisted CSS properties and blocks values containing
+ * `expression(` or `url(` (defense against legacy IE expression and CSS fetching).
+ *
+ * @param {string} style
+ * @returns {string} Canonical `prop: value; prop: value;` string, or '' if nothing left.
+ */
+export function sanitizeStyle(style) {
+  if (!style) return ''
+
+  /** @type {string[]} */
+  const safe = []
+
+  for (const part of style.split(';')) {
+    const trimmed = part.trim()
+    if (!trimmed) continue
+
+    const colonIndex = trimmed.indexOf(':')
+    if (colonIndex === -1) continue
+
+    const property = trimmed.slice(0, colonIndex).trim().toLowerCase()
+    const value = trimmed.slice(colonIndex + 1).trim()
+
+    if (!ALLOWED_STYLE_PROPS.has(property)) continue
+    if (!value) continue
+    // Block known CSS attack vectors
+    if (value.includes('expression')) continue
+    if (value.includes('url(')) continue
+
+    safe.push(`${property}: ${value}`)
+  }
+
+  // Match CSSStyleDeclaration/innerHTML serialization so save → render → save
+  // remains byte-stable for formatting created through element.style.
+  return safe.length > 0 ? `${safe.join('; ')};` : ''
+}

package/dist/shared/sanitize/sanitizeUrl.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Sanitize a URL string — strip control chars, block dangerous schemes.
+ * Returns '#' for rejected URLs so callers can safely set it on an attribute.
+ * @param {string} url
+ * @returns {string}
+ */
+export function sanitizeUrl(url: string, options?: {}): string;
+/** @param {string} url */
+export function sanitizeExternalUrl(url: string): string;
+/** @param {string} url */
+export function sanitizeMediaUrl(url: string): string;
+/** @param {string} url */
+export function sanitizeDownloadUrl(url: string): string;
+/**
+ * Set or remove a URL-bearing DOM attribute according to a field policy.
+ * @param {Element} element
+ * @param {'href' | 'src' | 'poster'} attribute
+ * @param {string} url
+ * @param {UrlPolicy} [policy]
+ * @returns {string}
+ */
+export function setSafeUrlAttribute(element: Element, attribute: "href" | "src" | "poster", url: string, policy?: UrlPolicy): string;
+export type UrlPolicy = "link" | "external" | "media" | "download";
+export type SanitizeUrlOptions = {
+    policy?: UrlPolicy;
+    allowRelative?: boolean;
+    fallback?: string;
+};

package/dist/shared/sanitize/sanitizeUrl.js

@@ -0,0 +1,86 @@
+import { DANGEROUS_URL_RE } from './allowlist.js'
+
+const LINK_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:'])
+const EXTERNAL_PROTOCOLS = new Set(['http:', 'https:'])
+const MEDIA_PROTOCOLS = new Set(['http:', 'https:', 'blob:'])
+const DOWNLOAD_PROTOCOLS = new Set(['http:', 'https:', 'blob:'])
+const SAFE_IMAGE_DATA_RE = /^data:image\/(?:avif|gif|jpeg|png|webp);base64,[a-z0-9+/=\s]+$/i
+
+/**
+ * @typedef {'link' | 'external' | 'media' | 'download'} UrlPolicy
+ * @typedef {{
+ *   policy?: UrlPolicy,
+ *   allowRelative?: boolean,
+ *   fallback?: string,
+ * }} SanitizeUrlOptions
+ */
+
+/** @param {UrlPolicy} policy */
+function getAllowedProtocols(policy) {
+  if (policy === 'external') return EXTERNAL_PROTOCOLS
+  if (policy === 'media') return MEDIA_PROTOCOLS
+  if (policy === 'download') return DOWNLOAD_PROTOCOLS
+  return LINK_PROTOCOLS
+}
+
+/**
+ * Sanitize a URL string — strip control chars, block dangerous schemes.
+ * Returns '#' for rejected URLs so callers can safely set it on an attribute.
+ * @param {string} url
+ * @returns {string}
+ */
+export function sanitizeUrl(url, options = {}) {
+  const fallback = options.fallback ?? '#'
+  if (typeof url !== 'string' || !url) return fallback
+
+  const policy = options.policy ?? 'link'
+  const allowRelative = options.allowRelative ?? true
+  const stripped = url.replace(/[\x00-\x1f\x7f]/g, '').trim()
+  if (!stripped) return fallback
+
+  const normalized = stripped.replace(/[\t\n\r ]/g, '')
+  if (DANGEROUS_URL_RE.test(normalized)) return fallback
+
+  if ((policy === 'media' || policy === 'download') && SAFE_IMAGE_DATA_RE.test(stripped)) return stripped
+  if (/^data\s*:/i.test(normalized)) return fallback
+
+  if (stripped.startsWith('//')) return allowRelative ? stripped : fallback
+
+  const schemeMatch = normalized.match(/^([a-z][a-z0-9+.-]*):/i)
+  if (!schemeMatch) return allowRelative ? stripped : fallback
+
+  const protocol = String(schemeMatch[1]).toLowerCase() + ':'
+  if (!getAllowedProtocols(policy).has(protocol)) return fallback
+
+  return stripped
+}
+
+/** @param {string} url */
+export function sanitizeExternalUrl(url) {
+  return sanitizeUrl(url, { policy: 'external' })
+}
+
+/** @param {string} url */
+export function sanitizeMediaUrl(url) {
+  return sanitizeUrl(url, { policy: 'media', fallback: '' })
+}
+
+/** @param {string} url */
+export function sanitizeDownloadUrl(url) {
+  return sanitizeUrl(url, { policy: 'download', fallback: '' })
+}
+
+/**
+ * Set or remove a URL-bearing DOM attribute according to a field policy.
+ * @param {Element} element
+ * @param {'href' | 'src' | 'poster'} attribute
+ * @param {string} url
+ * @param {UrlPolicy} [policy]
+ * @returns {string}
+ */
+export function setSafeUrlAttribute(element, attribute, url, policy = 'link') {
+  const safe = sanitizeUrl(url, { policy, fallback: '' })
+  if (safe) element.setAttribute(attribute, safe)
+  else element.removeAttribute(attribute)
+  return safe
+}

package/dist/shared/sanitize/walker.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Recursively sanitize a DOM subtree in place.
+ *
+ * - Unknown tags are unwrapped (children preserved).
+ * - Disallowed attributes are stripped.
+ * - `<a>` href is sanitized and `rel="noopener noreferrer"` is forced.
+ * - `<span style>` is filtered through the style allowlist.
+ * - `<span data-inline-plugin>` subtrees keep all their attributes/styles intact
+ *   (inline plugins manage their own markup; style/class whitelisting here would
+ *   strip legitimate plugin state like color swatches). Their children are still
+ *   recursively sanitized so user-authored content inside plugin widgets is safe.
+ *
+ * @param {Node} node
+ */
+export function sanitizeSubtree(node: Node): void;

package/dist/shared/sanitize/walker.js

@@ -0,0 +1,98 @@
+import { ALLOWED_TAGS, ALLOWED_ATTRS, INLINE_PLUGIN_ATTRS } from './allowlist.js'
+import { sanitizeUrl } from './sanitizeUrl.js'
+import { sanitizeStyle } from './sanitizeStyle.js'
+
+/**
+ * Recursively sanitize a DOM subtree in place.
+ *
+ * - Unknown tags are unwrapped (children preserved).
+ * - Disallowed attributes are stripped.
+ * - `<a>` href is sanitized and `rel="noopener noreferrer"` is forced.
+ * - `<span style>` is filtered through the style allowlist.
+ * - `<span data-inline-plugin>` subtrees keep all their attributes/styles intact
+ *   (inline plugins manage their own markup; style/class whitelisting here would
+ *   strip legitimate plugin state like color swatches). Their children are still
+ *   recursively sanitized so user-authored content inside plugin widgets is safe.
+ *
+ * @param {Node} node
+ */
+export function sanitizeSubtree(node) {
+  let i = 0
+
+  while (i < node.childNodes.length) {
+    const child = /** @type {ChildNode} */ (node.childNodes[i])
+
+    if (child.nodeType === Node.TEXT_NODE) {
+      i++
+      continue
+    }
+
+    if (child.nodeType !== Node.ELEMENT_NODE) {
+      child.remove()
+      continue
+    }
+
+    const el = /** @type {HTMLElement} */ (child)
+    const tag = el.tagName.toLowerCase()
+
+    if (!ALLOWED_TAGS.has(tag)) {
+      // Unwrap: keep children, remove the tag itself.
+      // Don't advance i — the newly-inserted children must be revisited.
+      while (el.firstChild) {
+        node.insertBefore(el.firstChild, el)
+      }
+      el.remove()
+      continue
+    }
+
+    // Inline plugin span — preserve attributes/styles, recurse into children.
+    if (tag === 'span' && el.hasAttribute('data-inline-plugin')) {
+      for (const attr of Array.from(el.attributes)) {
+        if (!INLINE_PLUGIN_ATTRS.has(attr.name) || attr.name.startsWith('on')) {
+          el.removeAttribute(attr.name)
+        }
+      }
+      el.removeAttribute('style')
+      el.setAttribute('contenteditable', 'false')
+      sanitizeSubtree(el)
+      i++
+      continue
+    }
+
+    // Strip disallowed attributes
+    const allowedAttrs = ALLOWED_ATTRS[tag]
+    const attrs = Array.from(el.attributes)
+    for (const attr of attrs) {
+      if (!allowedAttrs?.has(attr.name)) {
+        el.removeAttribute(attr.name)
+      }
+    }
+
+    if (tag === 'a') {
+      const href = el.getAttribute('href') || ''
+      el.setAttribute('href', sanitizeUrl(href))
+      el.setAttribute('rel', 'noopener noreferrer')
+    }
+
+    if (el.hasAttribute('style')) {
+      const safeStyle = sanitizeStyle(el.getAttribute('style') || '')
+      if (safeStyle) {
+        el.setAttribute('style', safeStyle)
+      } else {
+        el.removeAttribute('style')
+      }
+    }
+
+    // Unwrap empty `<span>` with no meaningful attributes.
+    if (tag === 'span' && !el.getAttribute('style') && !el.getAttribute('class')) {
+      while (el.firstChild) {
+        node.insertBefore(el.firstChild, el)
+      }
+      el.remove()
+      continue
+    }
+
+    sanitizeSubtree(el)
+    i++
+  }
+}

package/dist/shared/styleRegistry.d.ts

@@ -0,0 +1,4 @@
+/** @param {string[]} urls */
+export function acquireStyleUrls(urls: string[]): {
+    destroy(): void;
+};

package/dist/shared/styleRegistry.js

@@ -0,0 +1,38 @@
+/** Reference-counted stylesheet ownership shared by editor and renderer. */
+const entries = new Map()
+
+/** @param {string[]} urls */
+export function acquireStyleUrls(urls) {
+  const tracked = []
+  for (const url of new Set(urls)) {
+    const existing = entries.get(url)
+    if (existing) {
+      existing.count++
+    } else {
+      const link = document.createElement('link')
+      link.rel = 'stylesheet'
+      link.href = url
+      link.dataset.oeStyle = ''
+      document.head.appendChild(link)
+      entries.set(url, { count: 1, link })
+    }
+    tracked.push(url)
+  }
+
+  let released = false
+  return {
+    destroy() {
+      if (released) return
+      released = true
+      for (const url of tracked) {
+        const entry = entries.get(url)
+        if (!entry) continue
+        entry.count--
+        if (entry.count <= 0) {
+          entry.link.remove()
+          entries.delete(url)
+        }
+      }
+    },
+  }
+}

package/dist/shared/textFormat.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Return a serialized text field only when it is a string.
+ *
+ * Renderers run before document validation so invalid external documents can
+ * still be inspected and reported. Normalizing at the rendering boundary
+ * prevents objects and arrays from leaking into the DOM as "[object Object]".
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeTextValue(value: unknown): string;
+/**
+ * Check whether a value is a supported serialized text alignment.
+ * @param {unknown} value
+ * @returns {value is 'left' | 'center' | 'right' | 'justify'}
+ */
+export function isTextAlign(value: unknown): value is "left" | "center" | "right" | "justify";
+/**
+ * Return a supported text alignment or an empty string for invalid input.
+ * @param {unknown} value
+ * @returns {'' | 'left' | 'center' | 'right' | 'justify'}
+ */
+export function normalizeTextAlign(value: unknown): "" | "left" | "center" | "right" | "justify";
+/**
+ * Normalize a heading level to the supported H2-H6 range.
+ * Non-integer and non-finite values fall back to H2.
+ * @param {unknown} value
+ * @returns {2 | 3 | 4 | 5 | 6}
+ */
+export function normalizeHeadingLevel(value: unknown): 2 | 3 | 4 | 5 | 6;
+/** Supported CSS text-align values in serialized block data. */
+export const TEXT_ALIGNS: readonly string[];

package/dist/shared/textFormat.js

@@ -0,0 +1,48 @@
+/** Supported CSS text-align values in serialized block data. */
+export const TEXT_ALIGNS = Object.freeze(['left', 'center', 'right', 'justify'])
+
+const TEXT_ALIGN_SET = new Set(TEXT_ALIGNS)
+
+/**
+ * Return a serialized text field only when it is a string.
+ *
+ * Renderers run before document validation so invalid external documents can
+ * still be inspected and reported. Normalizing at the rendering boundary
+ * prevents objects and arrays from leaking into the DOM as "[object Object]".
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeTextValue(value) {
+  return typeof value === 'string' ? value : ''
+}
+
+/**
+ * Check whether a value is a supported serialized text alignment.
+ * @param {unknown} value
+ * @returns {value is 'left' | 'center' | 'right' | 'justify'}
+ */
+export function isTextAlign(value) {
+  return typeof value === 'string' && TEXT_ALIGN_SET.has(value)
+}
+
+/**
+ * Return a supported text alignment or an empty string for invalid input.
+ * @param {unknown} value
+ * @returns {'' | 'left' | 'center' | 'right' | 'justify'}
+ */
+export function normalizeTextAlign(value) {
+  return isTextAlign(value) ? value : ''
+}
+
+/**
+ * Normalize a heading level to the supported H2-H6 range.
+ * Non-integer and non-finite values fall back to H2.
+ * @param {unknown} value
+ * @returns {2 | 3 | 4 | 5 | 6}
+ */
+export function normalizeHeadingLevel(value) {
+  const number = Number(value)
+  if (!Number.isInteger(number)) return 2
+  return /** @type {2 | 3 | 4 | 5 | 6} */ (Math.min(Math.max(number, 2), 6))
+}

package/dist/shared/zipRuntime.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @returns {ZipRuntime | null}
+ */
+export function getZipRuntime(): ZipRuntime | null;
+/**
+ * @param {ZipRuntime} value
+ */
+export function setZipRuntime(value: ZipRuntime): void;
+/**
+ * Load the browser-native local distribution once.
+ * @returns {Promise<ZipRuntime>}
+ */
+export function loadZipRuntime(): Promise<ZipRuntime>;
+export type ZipRuntime = new () => {
+    file(name: string, content: Blob): unknown;
+    generateAsync(options: {
+        type: "blob";
+    }): Promise<Blob>;
+};

package/dist/shared/zipRuntime.js

@@ -0,0 +1,54 @@
+// @ts-check
+
+/**
+ * @typedef {new () => {
+ *   file(name: string, content: Blob): unknown,
+ *   generateAsync(options: { type: 'blob' }): Promise<Blob>
+ * }} ZipRuntime
+ */
+
+/** @type {ZipRuntime | null} */
+let runtime = null
+/** @type {Promise<ZipRuntime> | null} */
+let loadPromise = null
+
+/**
+ * @returns {ZipRuntime | null}
+ */
+export function getZipRuntime() {
+  if (!runtime && typeof globalThis !== 'undefined') {
+    const globalRuntime = /** @type {{ JSZip?: ZipRuntime }} */ (globalThis).JSZip
+    if (globalRuntime) runtime = globalRuntime
+  }
+  return runtime
+}
+
+/**
+ * @param {ZipRuntime} value
+ */
+export function setZipRuntime(value) {
+  runtime = value
+}
+
+/**
+ * Load the browser-native local distribution once.
+ * @returns {Promise<ZipRuntime>}
+ */
+export function loadZipRuntime() {
+  const current = getZipRuntime()
+  if (current) return Promise.resolve(current)
+  if (loadPromise) return loadPromise
+
+  loadPromise = import('./runtime/jszip.js')
+    .then(() => {
+      const loaded = getZipRuntime()
+      if (!loaded) throw new Error('JSZip runtime failed to initialize')
+      return loaded
+    })
+    .catch(error => {
+      loadPromise = null
+      throw error
+    })
+
+  return loadPromise
+}

package/dist/styles/editor.css

@@ -0,0 +1,3 @@
+@import '../core/themes/variables.css';
+@import '../core/themes/light.css';
+@import '../core/themes/dark.css';

package/dist/types.d.ts

@@ -0,0 +1 @@
+export * from './core/types.js'

package/package.json

@@ -0,0 +1,149 @@
+{
+  "name": "@shelamkoff/rector",
+  "version": "1.0.0",
+  "description": "Extensible browser-native block editor with atomic history, versioned JSON, and document rendering",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts"
+    },
+    "./plugins": {
+      "types": "./dist/plugins/index.d.ts",
+      "import": "./dist/plugins/index.js"
+    },
+    "./plugins/async": {
+      "types": "./dist/plugins/async.d.ts",
+      "import": "./dist/plugins/async.js"
+    },
+    "./plugins/*": {
+      "types": "./dist/plugins/*/index.d.ts",
+      "import": "./dist/plugins/*/index.js"
+    },
+    "./inline-plugins/color": {
+      "types": "./dist/inline-plugins/color.d.ts",
+      "import": "./dist/inline-plugins/color.js"
+    },
+    "./inline-plugins/mention": {
+      "types": "./dist/inline-plugins/mention/index.d.ts",
+      "import": "./dist/inline-plugins/mention/index.js"
+    },
+    "./inline-tools": {
+      "types": "./dist/inline-tools/defaults.d.ts",
+      "import": "./dist/inline-tools/defaults.js"
+    },
+    "./inline-tools/*": {
+      "types": "./dist/inline-tools/*.d.ts",
+      "import": "./dist/inline-tools/*.js"
+    },
+    "./renderer": {
+      "types": "./dist/renderer/index.d.ts",
+      "import": "./dist/renderer/index.js"
+    },
+    "./renderer/types": {
+      "types": "./dist/renderer/types.d.ts"
+    },
+    "./renderer/async": {
+      "types": "./dist/renderer/async.d.ts",
+      "import": "./dist/renderer/async.js"
+    },
+    "./renderer/renderers": {
+      "types": "./dist/renderer/renderers/index.d.ts",
+      "import": "./dist/renderer/renderers/index.js"
+    },
+    "./renderer/renderers/async": {
+      "types": "./dist/renderer/renderers/async.d.ts",
+      "import": "./dist/renderer/renderers/async.js"
+    },
+    "./renderer/renderers/*": {
+      "types": "./dist/renderer/renderers/*/index.d.ts",
+      "import": "./dist/renderer/renderers/*/index.js"
+    },
+    "./locale/*": {
+      "types": "./dist/locale/*.d.ts",
+      "import": "./dist/locale/*.js"
+    },
+    "./styles/editor.css": "./dist/styles/editor.css",
+    "./styles/renderer.css": "./dist/renderer/styles/base.css",
+    "./styles/themes/*": "./dist/core/themes/*.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD_PARTY_LICENSES.txt"
+  ],
+  "scripts": {
+    "build": "npm run docs:validate-readmes && node scripts/build-package.mjs",
+    "build:types": "node scripts/generate-declarations.mjs --out dist",
+    "typecheck": "node node_modules/typescript/bin/tsc -p jsconfig.json",
+    "docs:validate-readmes": "node scripts/validate-extension-readmes.mjs",
+    "docs:sync": "npm run docs:validate-readmes && node scripts/sync-vitepress-readmes.mjs",
+    "docs:dev": "npm run docs:sync && vitepress dev docs --host 127.0.0.1",
+    "docs:build": "npm run docs:sync && vitepress build docs",
+    "docs:preview": "vitepress preview docs --host 127.0.0.1",
+    "docs:check": "npm run docs:build && node scripts/vitepress-docs-smoke.mjs && node scripts/vitepress-browser-smoke.mjs",
+    "test": "node --test",
+    "test:browser": "node tests/browser/run.mjs && node tests/browser/physical-history.mjs && node tests/browser/heap-gate.mjs",
+    "test:plugin-source": "node scripts/plugin-source-audit.mjs",
+    "test:plugin-locales": "node scripts/plugin-locale-audit.mjs",
+    "test:docs": "npm run docs:validate-readmes && npm run test:plugin-source && npm run test:plugin-locales && node scripts/documentation-contract-audit.mjs && node scripts/readme-smoke.mjs",
+    "test:types": "node --test shared/declarationParity.test.js",
+    "test:package": "node scripts/package-consumer-gate.mjs",
+    "prepublishOnly": "npm run typecheck && npm test && npm run test:browser && npm run test:docs && npm run test:types && npm run test:package",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@shelamkoff/color-picker": "^1.0.0",
+    "@shelamkoff/event-bus": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@shelamkoff/carousel": "^1.0.0",
+    "@shelamkoff/cropper": "^1.0.0",
+    "@shelamkoff/expose": "^1.0.0"
+  },
+  "devDependencies": {
+    "@tabler/icons-vue": "^3.41.1",
+    "typescript": "~5.9.3",
+    "vite": "^7.0.0",
+    "vitepress": "2.0.0-alpha.17"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "editor",
+    "block-editor",
+    "rich-text",
+    "renderer",
+    "plugins",
+    "framework-agnostic",
+    "esm"
+  ],
+  "author": "Shelamkoff",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shelamkoff/editor.git"
+  },
+  "homepage": "https://shelamkoff.github.io/editor/",
+  "bugs": {
+    "url": "https://github.com/Shelamkoff/editor/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}