@shelamkoff/rector 1.0.0

package/dist/shared/inlineMarshal.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Inline widget marshalling.
+ *
+ * Model:
+ *   Every committed inline widget carries a stable instance id on its DOM
+ *   (`data-id` attribute), generated once at creation time and preserved
+ *   through save / load round-trips. That id is simultaneously:
+ *     - the key under which the widget's data is stored in the block-level
+ *       `inline` map on save;
+ *     - the placeholder referenced inline in the block's text field, as
+ *       `{{<id>}}`;
+ *     - the value written back to `data-id` when the widget is rehydrated
+ *       on load.
+ *
+ * Storage on save:
+ *   Live DOM    → `<span data-inline-plugin="mention" data-id="w_3k7a"
+ *                   data-value="1" class="oe-ip oe-ip--mention">@Anna</span>`
+ *   Serialized  → text field becomes `... {{w_3k7a}} ...` plus
+ *                   `inline["w_3k7a"] = { type: "mention", data: { id: "1", name: "Anna" } }`.
+ *
+ * Both directions dispatch polymorphically through the registered inline
+ * plugin's own `getData` (save) / `createWidget(data, id)` (load).
+ */
+/**
+ * @typedef {import('../renderer/types.js').InlineWidget} InlineWidget
+ * @typedef {import('../renderer/types.js').InlinePluginLike & { isCommitted?(element: HTMLElement): boolean }} MarshalInlinePlugin
+ * @typedef {{ get(type: string): MarshalInlinePlugin | undefined }} PluginLookup
+ */
+/**
+ * Generate a new inline widget instance id. Not cryptographic — just
+ * collision-resistant enough within a single document (a few tens of
+ * widgets per block at most).
+ *
+ * Implementation: two independent `Math.random()` samples concatenated
+ * and fixed-length padded. The two samples defend against the rare case
+ * where a single `Math.random()` yields a value whose base36 text form is
+ * unusually short (e.g. `(0.5).toString(36) === "0.i"`) — padding +
+ * doubling guarantees ~48 bits of entropy and a stable 10-char body.
+ *
+ * @returns {string}
+ */
+export function generateInlineId(): string;
+/**
+ * Walk `html` for inline-plugin widget spans, replace each with a
+ * `{{<widget-id>}}` text placeholder, and collect their data into an
+ * `inline` map keyed by widget id. Widgets without `data-id` get one
+ * generated on the fly.
+ *
+ * @param {string} html
+ * @param {PluginLookup | null | undefined} registry
+ * @param {Set<string>} [usedIds] IDs already allocated in sibling text fields
+ * @returns {{ html: string, inline: Record<string, InlineWidget> }}
+ */
+export function serializeInlineHtml(html: string, registry: PluginLookup | null | undefined, usedIds?: Set<string>): {
+    html: string;
+    inline: Record<string, InlineWidget>;
+};
+/**
+ * Expand `{{<id>}}` tokens back into widget DOM.
+ *
+ * For each token:
+ *   - look up `inline[id]` — if missing, leave the token text in place
+ *     (the user may have typed something that happens to look like one);
+ *   - dispatch to `registry.get(type).createWidget(data, id)` —
+ *     rebuilding the widget with its STABLE id preserved.
+ *
+ * Built as a DOM walk (not regex-over-string) so inserted widget
+ * elements don't disturb surrounding markup / nested elements.
+ *
+ * @param {string} html
+ * @param {Record<string, InlineWidget> | null | undefined} inline
+ * @param {PluginLookup | null | undefined} registry
+ * @returns {string}
+ */
+export function deserializeInlineHtml(html: string, inline: Record<string, InlineWidget> | null | undefined, registry: PluginLookup | null | undefined): string;
+export type InlineWidget = import("../renderer/types.js").InlineWidget;
+export type MarshalInlinePlugin = import("../renderer/types.js").InlinePluginLike & {
+    isCommitted?(element: HTMLElement): boolean;
+};
+export type PluginLookup = {
+    get(type: string): MarshalInlinePlugin | undefined;
+};

package/dist/shared/inlineMarshal.js

@@ -0,0 +1,215 @@
+// @ts-check
+/**
+ * Inline widget marshalling.
+ *
+ * Model:
+ *   Every committed inline widget carries a stable instance id on its DOM
+ *   (`data-id` attribute), generated once at creation time and preserved
+ *   through save / load round-trips. That id is simultaneously:
+ *     - the key under which the widget's data is stored in the block-level
+ *       `inline` map on save;
+ *     - the placeholder referenced inline in the block's text field, as
+ *       `{{<id>}}`;
+ *     - the value written back to `data-id` when the widget is rehydrated
+ *       on load.
+ *
+ * Storage on save:
+ *   Live DOM    → `<span data-inline-plugin="mention" data-id="w_3k7a"
+ *                   data-value="1" class="oe-ip oe-ip--mention">@Anna</span>`
+ *   Serialized  → text field becomes `... {{w_3k7a}} ...` plus
+ *                   `inline["w_3k7a"] = { type: "mention", data: { id: "1", name: "Anna" } }`.
+ *
+ * Both directions dispatch polymorphically through the registered inline
+ * plugin's own `getData` (save) / `createWidget(data, id)` (load).
+ */
+
+/**
+ * @typedef {import('../renderer/types').InlineWidget} InlineWidget
+ * @typedef {import('../renderer/types').InlinePluginLike & { isCommitted?(element: HTMLElement): boolean }} MarshalInlinePlugin
+ * @typedef {{ get(type: string): MarshalInlinePlugin | undefined }} PluginLookup
+ */
+
+/**
+ * Generate a new inline widget instance id. Not cryptographic — just
+ * collision-resistant enough within a single document (a few tens of
+ * widgets per block at most).
+ *
+ * Implementation: two independent `Math.random()` samples concatenated
+ * and fixed-length padded. The two samples defend against the rare case
+ * where a single `Math.random()` yields a value whose base36 text form is
+ * unusually short (e.g. `(0.5).toString(36) === "0.i"`) — padding +
+ * doubling guarantees ~48 bits of entropy and a stable 10-char body.
+ *
+ * @returns {string}
+ */
+export function generateInlineId() {
+  const a = Math.random().toString(36).slice(2).padEnd(6, '0').slice(0, 6)
+  const b = Math.random().toString(36).slice(2).padEnd(4, '0').slice(0, 4)
+  return 'w_' + a + b
+}
+
+/**
+ * Matches `{{<id>}}` tokens. Ids are alphanumeric + `_` + `-` (matches
+ * our own `generateInlineId` output plus any reasonable external id).
+ */
+const PLACEHOLDER_RE = /\{\{([A-Za-z0-9_-]+)\}\}/g
+const INLINE_ID_RE = /^[A-Za-z0-9_-]+$/
+const RESERVED_INLINE_IDS = new Set(['__proto__', 'constructor', 'prototype'])
+
+/**
+ * @param {string | null} preferred
+ * @param {Set<string>} usedIds
+ */
+function allocateInlineId(preferred, usedIds) {
+  let id = preferred
+  if (!id || !INLINE_ID_RE.test(id) || RESERVED_INLINE_IDS.has(id) || usedIds.has(id)) {
+    do {
+      id = generateInlineId()
+    } while (usedIds.has(id) || RESERVED_INLINE_IDS.has(id))
+  }
+  usedIds.add(id)
+  return id
+}
+
+/**
+ * Walk `html` for inline-plugin widget spans, replace each with a
+ * `{{<widget-id>}}` text placeholder, and collect their data into an
+ * `inline` map keyed by widget id. Widgets without `data-id` get one
+ * generated on the fly.
+ *
+ * @param {string} html
+ * @param {PluginLookup | null | undefined} registry
+ * @param {Set<string>} [usedIds] IDs already allocated in sibling text fields
+ * @returns {{ html: string, inline: Record<string, InlineWidget> }}
+ */
+export function serializeInlineHtml(html, registry, usedIds = new Set()) {
+  /** @type {Array<[string, InlineWidget]>} */
+  const entries = []
+  const source = String(html || '')
+  if (!source || !registry) return { html: source, inline: {} }
+
+  const tpl = document.createElement('template')
+  tpl.innerHTML = source
+
+  const widgets = tpl.content.querySelectorAll('[data-inline-plugin]')
+  for (const widget of widgets) {
+    const el = /** @type {HTMLElement} */ (widget)
+    const type = el.getAttribute('data-inline-plugin')
+    if (!type) continue
+    const plugin = registry.get(type)
+    if (!plugin) continue
+
+    // Trigger-driven widgets can temporarily look like a widget while the
+    // user is editing a query, but they do not yet have valid persistent
+    // identity. Save their visible text instead of manufacturing an invalid
+    // inline-map entry. The plugin owns this decision because only it knows
+    // when its transient state becomes committed.
+    if (plugin.isCommitted?.(el) === false) {
+      el.replaceWith(document.createTextNode(el.textContent || ''))
+      continue
+    }
+
+    const id = allocateInlineId(el.getAttribute('data-id'), usedIds)
+    const data = plugin.getData(el)
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      throw new TypeError(`Inline plugin "${type}" getData() must return a data object`)
+    }
+    entries.push([id, {
+      type,
+      data,
+    }])
+
+    // Placeholder is a plain text token. It survives sanitization as-is
+    // (text content is untouched by the tag/attribute allowlist) and
+    // round-trips cleanly through innerHTML serialization.
+    el.replaceWith(document.createTextNode(`{{${id}}}`))
+  }
+
+  return { html: tpl.innerHTML, inline: Object.fromEntries(entries) }
+}
+
+/**
+ * Expand `{{<id>}}` tokens back into widget DOM.
+ *
+ * For each token:
+ *   - look up `inline[id]` — if missing, leave the token text in place
+ *     (the user may have typed something that happens to look like one);
+ *   - dispatch to `registry.get(type).createWidget(data, id)` —
+ *     rebuilding the widget with its STABLE id preserved.
+ *
+ * Built as a DOM walk (not regex-over-string) so inserted widget
+ * elements don't disturb surrounding markup / nested elements.
+ *
+ * @param {string} html
+ * @param {Record<string, InlineWidget> | null | undefined} inline
+ * @param {PluginLookup | null | undefined} registry
+ * @returns {string}
+ */
+export function deserializeInlineHtml(html, inline, registry) {
+  const source = String(html || '')
+  if (!source) return ''
+  if (!inline || typeof inline !== 'object' || !registry || !source.includes('{{')) return source
+
+  const tpl = document.createElement('template')
+  tpl.innerHTML = source
+
+  /** Visit every text node and expand placeholder tokens in place. */
+  const walker = document.createTreeWalker(tpl.content, NodeFilter.SHOW_TEXT)
+  /** @type {Text[]} */
+  const textNodes = []
+  let cur = walker.nextNode()
+  while (cur) {
+    textNodes.push(/** @type {Text} */ (cur))
+    cur = walker.nextNode()
+  }
+
+  for (const textNode of textNodes) {
+    const text = textNode.data
+    if (!text.includes('{{')) continue
+
+    // Build a fragment: alternating plain-text runs + widget nodes.
+    const frag = document.createDocumentFragment()
+    let lastIndex = 0
+    PLACEHOLDER_RE.lastIndex = 0
+    /** @type {RegExpExecArray | null} */
+    let match
+    while ((match = PLACEHOLDER_RE.exec(text)) !== null) {
+      const [token, id] = match
+      const ref = Object.prototype.hasOwnProperty.call(inline, id) ? inline[id] : undefined
+      if (!ref || typeof ref !== 'object' || typeof ref.type !== 'string') continue
+      const plugin = registry.get(ref.type)
+      if (!plugin) continue   // leave untouched text — user-typed lookalike
+
+      let widget
+      try {
+        const data = ref.data && typeof ref.data === 'object'
+          ? /** @type {Record<string, unknown>} */ (ref.data)
+          : {}
+        widget = plugin.createWidget(data, id)
+      } catch {
+        // Preserve malformed legacy entries as their original plain token.
+        continue
+      }
+      if (!(widget instanceof HTMLElement)) continue
+
+      // Preserve the text before the placeholder.
+      if (match.index > lastIndex) {
+        frag.appendChild(document.createTextNode(text.slice(lastIndex, match.index)))
+      }
+      // Instantiate the widget with its stable id preserved.
+      frag.appendChild(widget)
+      lastIndex = match.index + token.length
+    }
+
+    // Nothing matched → leave the text node alone.
+    if (lastIndex === 0) continue
+
+    // Trailing text after the last match.
+    if (lastIndex < text.length) {
+      frag.appendChild(document.createTextNode(text.slice(lastIndex)))
+    }
+    textNode.replaceWith(frag)
+  }
+
+  return tpl.innerHTML
+}

package/dist/shared/jsonData.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Assert that a value can cross the persisted Rector document boundary
+ * without changing meaning during JSON serialization.
+ *
+ * Shared references are allowed (JSON duplicates them), circular references
+ * and non-JSON objects are not.
+ *
+ * @param {unknown} value
+ * @param {string} [path]
+ */
+export function assertJsonValue(value: unknown, path?: string): void;

package/dist/shared/jsonData.js

@@ -0,0 +1,53 @@
+// @ts-check
+
+/**
+ * Assert that a value can cross the persisted Rector document boundary
+ * without changing meaning during JSON serialization.
+ *
+ * Shared references are allowed (JSON duplicates them), circular references
+ * and non-JSON objects are not.
+ *
+ * @param {unknown} value
+ * @param {string} [path]
+ */
+export function assertJsonValue(value, path = '$') {
+  /** @type {Set<object>} */
+  const ancestors = new Set()
+
+  /** @param {unknown} current @param {string} currentPath */
+  const visit = (current, currentPath) => {
+    if (current === null || typeof current === 'string' || typeof current === 'boolean') return
+    if (typeof current === 'number') {
+      if (!Number.isFinite(current)) throw new TypeError(`${currentPath} must contain a finite JSON number`)
+      return
+    }
+    if (typeof current !== 'object') {
+      throw new TypeError(`${currentPath} contains a non-JSON ${typeof current} value`)
+    }
+    if (ancestors.has(current)) throw new TypeError(`${currentPath} contains a circular reference`)
+
+    const prototype = Object.getPrototypeOf(current)
+    if (!Array.isArray(current) && prototype !== Object.prototype && prototype !== null) {
+      const name = /** @type {{ constructor?: { name?: string } }} */ (current).constructor?.name || 'object'
+      throw new TypeError(`${currentPath} contains non-JSON object ${name}`)
+    }
+
+    ancestors.add(current)
+    if (Array.isArray(current)) {
+      for (let index = 0; index < current.length; index++) {
+        if (!(index in current)) throw new TypeError(`${currentPath}[${index}] is an array hole`)
+        visit(current[index], `${currentPath}[${index}]`)
+      }
+    } else {
+      for (const key of Object.keys(current)) visit(current[key], `${currentPath}.${key}`)
+      for (const key of Object.getOwnPropertySymbols(current)) {
+        if (Object.prototype.propertyIsEnumerable.call(current, key)) {
+          throw new TypeError(`${currentPath} contains an enumerable symbol key`)
+        }
+      }
+    }
+    ancestors.delete(current)
+  }
+
+  visit(value, path)
+}

package/dist/shared/localeTypes.d.ts

@@ -0,0 +1,11 @@
+/** CLDR plural variants accepted by editor and renderer dictionaries. */
+export interface PluralForms {
+  zero?: string
+  one?: string
+  two?: string
+  few?: string
+  many?: string
+  other: string
+}
+
+export type LocaleValue = string | PluralForms

package/dist/shared/mapTextFields.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Text-field traversal belongs to the document model, not to either the
+ * editable plugin layer or the document renderer layer. Keeping the mappers
+ * here makes both sides consume the same transformation contract.
+ */
+/**
+ * @param {{ text?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapParagraphTextFields(data: {
+    text?: string;
+}, transform: (html: string) => string): void;
+/**
+ * @param {{ text?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapHeadingTextFields(data: {
+    text?: string;
+}, transform: (html: string) => string): void;
+/**
+ * @param {{ items?: unknown }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapListTextFields(data: {
+    items?: unknown;
+}, transform: (html: string) => string): void;
+/**
+ * @param {{ text?: string, caption?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapQuoteTextFields(data: {
+    text?: string;
+    caption?: string;
+}, transform: (html: string) => string): void;
+/**
+ * @param {{ items?: unknown }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapChecklistTextFields(data: {
+    items?: unknown;
+}, transform: (html: string) => string): void;
+/**
+ * @param {{ content?: unknown }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapTableTextFields(data: {
+    content?: unknown;
+}, transform: (html: string) => string): void;
+/**
+ * @param {{ columns?: unknown }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapColumnsTextFields(data: {
+    columns?: unknown;
+}, transform: (html: string) => string): void;
+/**
+ * @param {{ title?: string, message?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapWarningTextFields(data: {
+    title?: string;
+    message?: string;
+}, transform: (html: string) => string): void;
+/**
+ * @param {{ title?: string, content?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapToggleTextFields(data: {
+    title?: string;
+    content?: string;
+}, transform: (html: string) => string): void;
+/**
+ * @param {{ label?: string, content?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapSpoilerTextFields(data: {
+    label?: string;
+    content?: string;
+}, transform: (html: string) => string): void;

package/dist/shared/mapTextFields.js

@@ -0,0 +1,119 @@
+// @ts-check
+import { normalizeTextValue } from './textFormat.js'
+
+/**
+ * Text-field traversal belongs to the document model, not to either the
+ * editable plugin layer or the document renderer layer. Keeping the mappers
+ * here makes both sides consume the same transformation contract.
+ */
+
+/**
+ * @param {{ text?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapParagraphTextFields(data, transform) {
+  data.text = transform(normalizeTextValue(data.text))
+}
+
+/**
+ * @param {{ text?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapHeadingTextFields(data, transform) {
+  data.text = transform(normalizeTextValue(data.text))
+}
+
+/**
+ * @param {{ items?: unknown }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapListTextFields(data, transform) {
+  if (Array.isArray(data.items)) {
+    data.items = data.items.map(item => typeof item === 'string' ? transform(item) : item)
+  }
+}
+
+/**
+ * @param {{ text?: string, caption?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapQuoteTextFields(data, transform) {
+  if (typeof data.text === 'string') data.text = transform(data.text)
+  if (typeof data.caption === 'string') data.caption = transform(data.caption)
+}
+
+/**
+ * @param {{ items?: unknown }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapChecklistTextFields(data, transform) {
+  if (!Array.isArray(data.items)) return
+  for (const item of data.items) {
+    if (item && typeof item === 'object' && typeof (/** @type {{ text?: unknown }} */ (item)).text === 'string') {
+      const checklistItem = /** @type {{ text: string }} */ (item)
+      checklistItem.text = transform(checklistItem.text)
+    }
+  }
+}
+
+/**
+ * @param {{ content?: unknown }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapTableTextFields(data, transform) {
+  if (!Array.isArray(data.content)) return
+  data.content = data.content.map(row => Array.isArray(row)
+    ? row.map(cell => typeof cell === 'string' ? transform(cell) : cell)
+    : row)
+}
+
+/**
+ * @param {{ columns?: unknown }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapColumnsTextFields(data, transform) {
+  if (!Array.isArray(data.columns)) return
+  for (const column of data.columns) {
+    if (column && typeof column === 'object' && typeof (/** @type {{ content?: unknown }} */ (column)).content === 'string') {
+      const richTextColumn = /** @type {{ content: string }} */ (column)
+      richTextColumn.content = transform(richTextColumn.content)
+    }
+  }
+}
+
+/**
+ * @param {{ title?: string, message?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapWarningTextFields(data, transform) {
+  if (typeof data.title === 'string') data.title = transform(data.title)
+  if (typeof data.message === 'string') data.message = transform(data.message)
+}
+
+/**
+ * @param {{ title?: string, content?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapToggleTextFields(data, transform) {
+  if (typeof data.title === 'string') data.title = transform(data.title)
+  if (typeof data.content === 'string') data.content = transform(data.content)
+}
+
+/**
+ * @param {{ label?: string, content?: string }} data
+ * @param {(html: string) => string} transform
+ * @returns {void}
+ */
+export function mapSpoilerTextFields(data, transform) {
+  if (typeof data.label === 'string') data.label = transform(data.label)
+  if (typeof data.content === 'string') data.content = transform(data.content)
+}

package/dist/shared/pollData.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Normalize an untrusted runtime result without retaining arbitrary fields.
+ * Unknown option ids and active avatar URLs are discarded.
+ * @param {unknown} input
+ * @param {string[]} optionIds
+ * @param {number} [maxVoters]
+ * @param {'single' | 'multiple'} [selectionType]
+ * @returns {PollResults}
+ */
+export function normalizePollResults(input: unknown, optionIds: string[], maxVoters?: number, selectionType?: "single" | "multiple"): PollResults;
+/**
+ * @param {unknown} input
+ * @param {() => string} createId
+ * @returns {PollData}
+ */
+export function normalizePollData(input: unknown, createId: () => string): PollData;
+/** @param {unknown} data */
+export function validatePollData(data: unknown): boolean;
+/**
+ * Apply a local vote and return a new immutable runtime snapshot.
+ * @param {PollResults | undefined} current
+ * @param {string[]} previousIds
+ * @param {string[]} nextIds
+ * @param {string[]} optionIds
+ * @returns {PollResults}
+ */
+export function applyLocalPollVote(current: PollResults | undefined, previousIds: string[], nextIds: string[], optionIds: string[]): PollResults;
+/**
+ * Decide whether a runtime result may replace the currently displayed revision.
+ * Opaque unequal revisions follow arrival order unless the host supplies an
+ * ordering function. Equal revisions are idempotent and therefore ignored.
+ *
+ * @param {string | undefined} next
+ * @param {string | undefined} current
+ * @param {((next: string, current: string) => number) | undefined} compare
+ */
+export function shouldAcceptPollRevision(next: string | undefined, current: string | undefined, compare: ((next: string, current: string) => number) | undefined): boolean;
+/**
+ * @typedef {{ id: string, text: string }} PollOption Author-owned option with a stable document id and inline-text label.
+ * @typedef {{ id: string, votes: number }} PollOptionResult Vote count for one author-owned option id.
+ * @typedef {{ id: string, name?: string, avatar?: string, optionIds?: string[] }} PollVoter Optional application-owned voter summary.
+ * @typedef {{ revision?: string, total: number, options: PollOptionResult[], voters?: PollVoter[], votersTotal?: number, currentUserVote?: string[] }} PollResults Runtime result snapshot. `total` is the ballot-count denominator used for percentages; multiple-choice option percentages may therefore sum above 100%.
+ * @typedef {{ pollId?: string, question: string, type: 'single' | 'multiple', options: PollOption[], resultsMode: 'always' | 'afterVote' | 'hidden', initialResults?: PollResults }} PollData Persisted poll authoring data plus an optional initial/local result snapshot.
+ */
+export const POLL_RESULTS_MODES: readonly string[];
+/**
+ * Author-owned option with a stable document id and inline-text label.
+ */
+export type PollOption = {
+    id: string;
+    text: string;
+};
+/**
+ * Vote count for one author-owned option id.
+ */
+export type PollOptionResult = {
+    id: string;
+    votes: number;
+};
+/**
+ * Optional application-owned voter summary.
+ */
+export type PollVoter = {
+    id: string;
+    name?: string;
+    avatar?: string;
+    optionIds?: string[];
+};
+/**
+ * Runtime result snapshot. `total` is the ballot-count denominator used for percentages; multiple-choice option percentages may therefore sum above 100%.
+ */
+export type PollResults = {
+    revision?: string;
+    total: number;
+    options: PollOptionResult[];
+    voters?: PollVoter[];
+    votersTotal?: number;
+    currentUserVote?: string[];
+};
+/**
+ * Persisted poll authoring data plus an optional initial/local result snapshot.
+ */
+export type PollData = {
+    pollId?: string;
+    question: string;
+    type: "single" | "multiple";
+    options: PollOption[];
+    resultsMode: "always" | "afterVote" | "hidden";
+    initialResults?: PollResults;
+};