@abraca/convert 2.3.0

package/src/spec/index.ts

@@ -0,0 +1,7 @@
+// Spec registry — the executable mirror of SPEC.md. Parsers and
+// serialisers consult these tables instead of hardcoding node/mark
+// names. When the registry and SPEC.md disagree, the registry wins.
+
+export * from './nodes.ts'
+export * from './marks.ts'
+export * from './universal-meta.ts'

package/src/spec/marks.ts

@@ -0,0 +1,92 @@
+// MarkSpec registry — every inline mark supported by the converter,
+// paired with its canonical Markdown wire form.
+//
+// Marks are pure inline annotations on text runs; they have no
+// children. The parser sets these as `op.attributes` on Yjs delta
+// inserts; the serialiser wraps text runs with the matching wire
+// delimiters.
+//
+// See SPEC.md §3-4 for the rendered table and the disambiguation
+// rules between bold (`**…**`) and underline (`__…__`).
+
+export type MarkWireKind =
+  | 'delimited' // `**text**`, `*text*`, `~~text~~`, `` `text` ``
+  | 'link' // `[text](href)`
+  | 'mdc-span' // `:span[text]{prop=value}` for color/font/textStyle
+
+export interface MarkAttrSpec {
+  key: string
+  type: 'string' | 'number' | 'boolean'
+  optional?: boolean
+}
+
+export interface MarkSpec {
+  name: string
+  wire: MarkWireKind
+  /** For `delimited`: the markdown delimiter (e.g. `**`, `*`, `~~`, `` ` ``, `__`, `==`). */
+  delim?: string
+  attrs?: readonly MarkAttrSpec[]
+  doc?: string
+}
+
+export const MARK_SPECS: readonly MarkSpec[] = [
+  // Vanilla MD marks
+  { name: 'bold', wire: 'delimited', delim: '**' },
+  { name: 'italic', wire: 'delimited', delim: '*' },
+  { name: 'strike', wire: 'delimited', delim: '~~' },
+  { name: 'code', wire: 'delimited', delim: '`' },
+  {
+    name: 'link',
+    wire: 'link',
+    attrs: [
+      { key: 'href', type: 'string' },
+      { key: 'title', type: 'string', optional: true },
+    ],
+  },
+
+  // Extended marks (lossless via MDC syntax)
+  {
+    name: 'underline',
+    wire: 'delimited',
+    delim: '__',
+    doc: 'Disambiguated from bold by delimiter character. Two underscores = underline; two asterisks = bold.',
+  },
+  {
+    name: 'highlight',
+    wire: 'delimited',
+    delim: '==',
+    doc: 'Pandoc-style.',
+  },
+  {
+    name: 'subscript',
+    wire: 'delimited',
+    delim: '~',
+    doc: 'Single tilde; double tilde is strike.',
+  },
+  {
+    name: 'superscript',
+    wire: 'delimited',
+    delim: '^',
+  },
+  {
+    name: 'textStyle',
+    wire: 'mdc-span',
+    attrs: [
+      { key: 'color', type: 'string', optional: true },
+      { key: 'backgroundColor', type: 'string', optional: true },
+      { key: 'fontSize', type: 'string', optional: true },
+      { key: 'fontFamily', type: 'string', optional: true },
+    ],
+    doc: 'Wire form `:span[text]{color="…" font-size="…"}`. Any of the attrs may be set.',
+  },
+]
+
+export const MARK_SPEC_BY_NAME: ReadonlyMap<string, MarkSpec> = new Map(
+  MARK_SPECS.map(spec => [spec.name, spec]),
+)
+
+export const MARK_SPEC_BY_DELIM: ReadonlyMap<string, MarkSpec> = new Map(
+  MARK_SPECS
+    .filter((spec): spec is MarkSpec & { delim: string } => spec.wire === 'delimited' && !!spec.delim)
+    .map(spec => [spec.delim, spec]),
+)

package/src/spec/nodes.ts

@@ -0,0 +1,333 @@
+// NodeSpec registry — every TipTap node supported by the converter,
+// paired with its canonical Markdown / MDC wire form.
+//
+// This is **data**, not behaviour. The parser and serialiser
+// (markdown-to-yjs.ts, yjs-to-markdown.ts) consult this table to
+// decide what to do; when the spec and the runtime disagree the
+// registry wins (per SPEC.md).
+//
+// Wire kinds:
+//   - vanilla        Standard Markdown (paragraph, heading, list, …).
+//   - fence          Fenced code block with a language tag.
+//   - mdc-container  `:name{props}\n…children…\n::` block with children.
+//   - mdc-slotted    `:name\n  :name-item{…}\n…\n  ::\n…\n::` slotted container.
+//   - mdc-atom-block `:name{props}` single-line block atom.
+//   - mdc-atom-inl   `:name[label]{props}` or `:name{props}` inline atom.
+//   - special        Has bespoke parsing/serialising (doc-link, doc-embed,
+//                    file-block, image, mention, math).
+
+import type { DocPageMeta } from '../types.ts'
+
+export type NodeWireKind =
+  | 'vanilla'
+  | 'fence'
+  | 'mdc-container'
+  | 'mdc-slotted'
+  | 'mdc-atom-block'
+  | 'mdc-atom-inl'
+  | 'special'
+
+export interface NodeAttrSpec {
+  /** Attribute name on the Y.XmlElement and on the MDC prop. */
+  key: string
+  /** Wire type — controls how the attr is parsed/serialised in props. */
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'json'
+  /** Optional default value omitted from serialised output when equal. */
+  default?: unknown
+  /** Allowed values for enum-like string attrs. */
+  values?: readonly string[]
+  /** Whether the attr is allowed to be omitted entirely. */
+  optional?: boolean
+}
+
+export interface NodeSpec {
+  /** Y.XmlElement nodeName. */
+  name: string
+  /** Block vs inline. */
+  group: 'block' | 'inline'
+  /** Wire form on Markdown. */
+  wire: NodeWireKind
+  /**
+   * For slotted containers: name of the child element used as a slot
+   * (e.g. `accordion-item` under `accordion`).
+   */
+  slotChild?: string
+  /** Declared attributes. */
+  attrs?: readonly NodeAttrSpec[]
+  /**
+   * For `mdc-container` and `mdc-slotted`: what MDC tag name to emit.
+   * Defaults to `name` (kebab-cased — `accordionItem` → `accordion-item`).
+   */
+  mdcTag?: string
+  /**
+   * Whether the node is content-bearing (paragraph, listItem, etc.)
+   * or a child wrapper (tableRow, tableHeader).
+   */
+  contentBearing?: boolean
+  doc?: string
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+const BOOL_FALSE_DEFAULT: NodeAttrSpec = {
+  key: '',
+  type: 'boolean',
+  default: false,
+  optional: true,
+}
+
+const bool = (key: string): NodeAttrSpec => ({ ...BOOL_FALSE_DEFAULT, key })
+const str = (key: string, def?: string): NodeAttrSpec => ({
+  key,
+  type: 'string',
+  default: def,
+  optional: true,
+})
+const num = (key: string): NodeAttrSpec => ({ key, type: 'number', optional: true })
+const int = (key: string): NodeAttrSpec => ({ key, type: 'integer', optional: true })
+
+// ── Vanilla block nodes ─────────────────────────────────────────────────────
+
+const VANILLA_BLOCKS: readonly NodeSpec[] = [
+  { name: 'documentHeader', group: 'block', wire: 'special', doc: 'Holds the title; hoisted to frontmatter on serialise.' },
+  { name: 'documentMeta', group: 'block', wire: 'special', doc: 'Holds page-level meta; serialised into frontmatter.' },
+  { name: 'paragraph', group: 'block', wire: 'vanilla', contentBearing: true },
+  { name: 'heading', group: 'block', wire: 'vanilla', attrs: [int('level')], contentBearing: true },
+  { name: 'blockquote', group: 'block', wire: 'vanilla', contentBearing: true },
+  { name: 'codeBlock', group: 'block', wire: 'fence', attrs: [str('language', '')] },
+  { name: 'bulletList', group: 'block', wire: 'vanilla' },
+  { name: 'orderedList', group: 'block', wire: 'vanilla' },
+  { name: 'listItem', group: 'block', wire: 'vanilla', contentBearing: true },
+  { name: 'taskList', group: 'block', wire: 'vanilla' },
+  { name: 'taskItem', group: 'block', wire: 'vanilla', attrs: [bool('checked')], contentBearing: true },
+  { name: 'table', group: 'block', wire: 'vanilla' },
+  { name: 'tableRow', group: 'block', wire: 'vanilla' },
+  { name: 'tableHeader', group: 'block', wire: 'vanilla', contentBearing: true },
+  { name: 'tableCell', group: 'block', wire: 'vanilla', contentBearing: true },
+  { name: 'horizontalRule', group: 'block', wire: 'vanilla' },
+  {
+    name: 'image',
+    group: 'block',
+    wire: 'special',
+    attrs: [str('src'), str('alt', ''), int('width'), int('height')],
+  },
+  { name: 'hardBreak', group: 'inline', wire: 'vanilla' },
+]
+
+// ── MDC custom containers ───────────────────────────────────────────────────
+
+const MDC_CONTAINERS: readonly NodeSpec[] = [
+  {
+    name: 'callout',
+    group: 'block',
+    wire: 'mdc-container',
+    attrs: [
+      { key: 'type', type: 'string', default: 'note', optional: true,
+        values: ['note', 'tip', 'warning', 'danger', 'info', 'caution', 'alert', 'success', 'error'] },
+      str('title'),
+      str('icon'),
+    ],
+  },
+  {
+    name: 'collapsible',
+    group: 'block',
+    wire: 'mdc-container',
+    attrs: [str('label', 'Details'), bool('open')],
+  },
+  {
+    name: 'accordion',
+    group: 'block',
+    wire: 'mdc-slotted',
+    slotChild: 'accordionItem',
+  },
+  {
+    name: 'accordionItem',
+    group: 'block',
+    wire: 'mdc-container',
+    mdcTag: 'accordion-item',
+    attrs: [str('label', 'Item'), str('icon')],
+  },
+  {
+    name: 'tabs',
+    group: 'block',
+    wire: 'mdc-slotted',
+    slotChild: 'tabsItem',
+  },
+  {
+    name: 'tabsItem',
+    group: 'block',
+    wire: 'mdc-container',
+    mdcTag: 'tabs-item',
+    attrs: [str('label'), str('icon')],
+  },
+  { name: 'steps', group: 'block', wire: 'mdc-container' },
+  {
+    name: 'card',
+    group: 'block',
+    wire: 'mdc-container',
+    attrs: [str('title'), str('icon'), str('to')],
+  },
+  {
+    name: 'cardGroup',
+    group: 'block',
+    wire: 'mdc-slotted',
+    mdcTag: 'card-group',
+    slotChild: 'card',
+  },
+  {
+    name: 'field',
+    group: 'block',
+    wire: 'mdc-container',
+    attrs: [str('name'), str('type', 'string'), bool('required')],
+  },
+  {
+    name: 'fieldGroup',
+    group: 'block',
+    wire: 'mdc-slotted',
+    mdcTag: 'field-group',
+    slotChild: 'field',
+  },
+  { name: 'codeGroup', group: 'block', wire: 'mdc-slotted', mdcTag: 'code-group', slotChild: 'codeBlock' },
+  { name: 'codeCollapse', group: 'block', wire: 'mdc-container', mdcTag: 'code-collapse' },
+  { name: 'codePreview', group: 'block', wire: 'mdc-container', mdcTag: 'code-preview' },
+  {
+    name: 'codeTree',
+    group: 'block',
+    wire: 'mdc-atom-block',
+    mdcTag: 'code-tree',
+    attrs: [{ key: 'files', type: 'json' }],
+  },
+  {
+    name: 'figure',
+    group: 'block',
+    wire: 'mdc-container',
+    attrs: [str('src'), str('alt', ''), str('caption')],
+  },
+  {
+    name: 'video',
+    group: 'block',
+    wire: 'mdc-atom-block',
+    attrs: [str('src'), str('poster'), bool('autoplay'), bool('loop'), bool('controls')],
+  },
+  {
+    name: 'embed',
+    group: 'block',
+    wire: 'mdc-atom-block',
+    attrs: [str('src'), str('title')],
+  },
+  {
+    name: 'svgEmbed',
+    group: 'block',
+    wire: 'fence',
+    attrs: [str('title')],
+    mdcTag: 'svg',
+    doc: 'Serialised as a ```svg fenced block; the SVG markup is the body.',
+  },
+  {
+    name: 'divider',
+    group: 'block',
+    wire: 'mdc-atom-block',
+    attrs: [str('label'), str('icon')],
+  },
+  { name: 'quote', group: 'block', wire: 'mdc-container', attrs: [str('cite')] },
+  { name: 'progress', group: 'block', wire: 'mdc-atom-block', attrs: [num('value'), num('max'), str('label')] },
+  { name: 'spoiler', group: 'block', wire: 'mdc-container', attrs: [str('label')] },
+  { name: 'colorSwatch', group: 'block', wire: 'mdc-atom-block', mdcTag: 'color-swatch', attrs: [str('color'), str('label')] },
+  { name: 'stat', group: 'block', wire: 'mdc-container', attrs: [str('label'), str('value'), str('icon')] },
+  { name: 'statGroup', group: 'block', wire: 'mdc-slotted', mdcTag: 'stat-group', slotChild: 'stat' },
+  { name: 'button', group: 'block', wire: 'mdc-atom-block', attrs: [str('label'), str('to'), str('icon'), str('variant')] },
+  { name: 'buttonGroup', group: 'block', wire: 'mdc-slotted', mdcTag: 'button-group', slotChild: 'button' },
+  { name: 'timeline', group: 'block', wire: 'mdc-slotted', slotChild: 'timelineItem' },
+  { name: 'timelineItem', group: 'block', wire: 'mdc-container', mdcTag: 'timeline-item', attrs: [str('label'), str('icon'), str('date')] },
+  { name: 'diff', group: 'block', wire: 'mdc-atom-block', attrs: [str('language', ''), { key: 'value', type: 'string' }] },
+]
+
+// ── Inline atoms / special nodes ────────────────────────────────────────────
+
+const INLINE_AND_SPECIAL: readonly NodeSpec[] = [
+  {
+    name: 'docLink',
+    group: 'inline',
+    wire: 'special',
+    attrs: [str('docId')],
+    doc: 'Wire form `[[uuid|label]]`; label regenerated on export.',
+  },
+  {
+    name: 'docEmbed',
+    group: 'block',
+    wire: 'special',
+    attrs: [str('docId'), bool('collapsed'), bool('tall'), bool('seamless')],
+    doc: 'Wire form `![[uuid|label]]{collapsed tall seamless}`.',
+  },
+  {
+    name: 'mention',
+    group: 'inline',
+    wire: 'special',
+    attrs: [str('userId')],
+    doc: 'Wire form `@[label](user:uuid)`; label regenerated on export.',
+  },
+  {
+    name: 'mathInline',
+    group: 'inline',
+    wire: 'special',
+    attrs: [{ key: 'expression', type: 'string' }],
+    doc: 'Wire form `$expression$`.',
+  },
+  {
+    name: 'mathBlock',
+    group: 'block',
+    wire: 'fence',
+    attrs: [{ key: 'expression', type: 'string' }],
+    mdcTag: 'math',
+    doc: 'Wire form ``` ```math\\nexpression\\n``` ```.',
+  },
+  {
+    name: 'fileBlock',
+    group: 'block',
+    wire: 'mdc-atom-block',
+    mdcTag: 'file',
+    attrs: [str('src'), str('mime'), str('uploadId'), str('filename')],
+    doc: 'Wire form `:file{src=… mime=… upload-id=… filename=…}`; binary in sidecar.',
+  },
+  {
+    name: 'badge',
+    group: 'inline',
+    wire: 'mdc-atom-inl',
+    attrs: [str('label'), str('color'), str('variant', 'subtle')],
+    doc: 'Wire form `:badge[Label]{color=… variant=…}`.',
+  },
+  {
+    name: 'proseIcon',
+    group: 'inline',
+    wire: 'mdc-atom-inl',
+    mdcTag: 'icon',
+    attrs: [str('name')],
+    doc: 'Wire form `:icon{name=…}`.',
+  },
+  {
+    name: 'kbd',
+    group: 'inline',
+    wire: 'mdc-atom-inl',
+    attrs: [str('value')],
+    doc: 'Wire form `:kbd{value=…}`.',
+  },
+]
+
+export const NODE_SPECS: readonly NodeSpec[] = [
+  ...VANILLA_BLOCKS,
+  ...MDC_CONTAINERS,
+  ...INLINE_AND_SPECIAL,
+]
+
+export const NODE_SPEC_BY_NAME: ReadonlyMap<string, NodeSpec> = new Map(
+  NODE_SPECS.map(spec => [spec.name, spec]),
+)
+
+/** Derive the MDC tag for a node — `mdcTag` override or kebab-case of `name`. */
+export function mdcTagOf(spec: NodeSpec): string {
+  if (spec.mdcTag) return spec.mdcTag
+  return spec.name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
+}
+
+/** Type-only re-export so consumers can build typed meta without a second import. */
+export type { DocPageMeta }

package/src/spec/universal-meta.ts

@@ -0,0 +1,147 @@
+// Universal-meta registry.
+//
+// Mirrors `@abraca/schema/src/types/universal.ts` — the canonical
+// source. We don't import @abraca/schema here to keep this package
+// dependency-free, but the keys MUST stay in sync. A future codegen
+// step in @abraca/schema can verify this file is up to date.
+//
+// Order is significant — it's the canonical key order in serialised
+// YAML frontmatter (see SPEC.md §2). Adding new keys appends to the
+// end so existing fixtures don't churn.
+
+export type MetaValueType =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'string[]'
+  | 'string-enum'
+  | 'iso-date'
+  | 'iso-datetime'
+  | 'hh-mm'
+  | 'members'
+  | 'json'
+
+export interface UniversalMetaKey {
+  key: string
+  type: MetaValueType
+  /** Allowed values for `string-enum`. */
+  values?: readonly string[]
+  /** Inclusive minimum for `number` / `integer`. */
+  min?: number
+  /** Inclusive maximum for `number` / `integer`. */
+  max?: number
+  /**
+   * Alternate YAML key names recognised on parse — for backwards
+   * compatibility with hand-written frontmatter (e.g. `date` → `dateStart`).
+   * Serialise always uses the canonical `key`.
+   */
+  parseAliases?: readonly string[]
+  /** Human-readable hint, surfaced in documentation. */
+  doc?: string
+}
+
+export const UNIVERSAL_META_KEYS: readonly UniversalMetaKey[] = [
+  // Identity / display
+  { key: 'title', type: 'string', doc: 'Display title; the first H1 is hoisted into this field on import.' },
+  { key: 'type', type: 'string', doc: 'Page type (doc, kanban, table, …). Omitted on serialise when "doc".' },
+  { key: 'color', type: 'string', doc: 'Hex or CSS color name.' },
+  { key: 'icon', type: 'string', doc: 'Lucide icon name in kebab-case.' },
+
+  // Datetime
+  { key: 'datetimeStart', type: 'iso-datetime' },
+  { key: 'datetimeEnd', type: 'iso-datetime' },
+  { key: 'allDay', type: 'boolean' },
+  { key: 'dateTaken', type: 'iso-datetime' },
+  { key: 'dateStart', type: 'iso-date', parseAliases: ['date', 'created'] },
+  { key: 'dateEnd', type: 'iso-date', parseAliases: ['due'] },
+  { key: 'timeStart', type: 'hh-mm' },
+  { key: 'timeEnd', type: 'hh-mm' },
+
+  // Generic
+  { key: 'tags', type: 'string[]' },
+  { key: 'checked', type: 'boolean', parseAliases: ['done'] },
+  {
+    key: 'priority',
+    type: 'integer',
+    min: 0,
+    max: 4,
+    doc: 'Numeric or named (low/medium/high/urgent → 1/2/3/4).',
+  },
+  { key: 'status', type: 'string' },
+  { key: 'rating', type: 'number', min: 0, max: 5 },
+  { key: 'url', type: 'string' },
+  { key: 'email', type: 'string' },
+  { key: 'phone', type: 'string' },
+  { key: 'number', type: 'number' },
+  { key: 'unit', type: 'string' },
+  { key: 'subtitle', type: 'string', parseAliases: ['description'] },
+  { key: 'note', type: 'string' },
+  { key: 'taskProgress', type: 'integer', min: 0, max: 100 },
+  { key: 'members', type: 'members' },
+
+  // Cover
+  { key: 'coverUploadId', type: 'string' },
+  { key: 'coverDocId', type: 'string' },
+  { key: 'coverMimeType', type: 'string' },
+
+  // Geo / map
+  { key: 'geoType', type: 'string-enum', values: ['marker', 'line', 'measure'] },
+  { key: 'geoLat', type: 'number' },
+  { key: 'geoLng', type: 'number' },
+  { key: 'geoDescription', type: 'string' },
+
+  // Dashboard / mindmap / graph layout
+  { key: 'deskX', type: 'number' },
+  { key: 'deskY', type: 'number' },
+  { key: 'deskZ', type: 'number' },
+  { key: 'deskMode', type: 'string-enum', values: ['icon', 'widget-sm', 'widget-lg'] },
+  { key: 'mmX', type: 'number' },
+  { key: 'mmY', type: 'number' },
+  { key: 'graphX', type: 'number' },
+  { key: 'graphY', type: 'number' },
+  { key: 'graphPinned', type: 'boolean' },
+
+  // Spatial
+  { key: 'spX', type: 'number' },
+  { key: 'spY', type: 'number' },
+  { key: 'spZ', type: 'number' },
+  { key: 'spRX', type: 'number' },
+  { key: 'spRY', type: 'number' },
+  { key: 'spRZ', type: 'number' },
+  { key: 'spSX', type: 'number' },
+  { key: 'spSY', type: 'number' },
+  { key: 'spSZ', type: 'number' },
+  {
+    key: 'spShape',
+    type: 'string-enum',
+    values: ['box', 'sphere', 'cylinder', 'cone', 'plane', 'torus', 'glb'],
+  },
+  { key: 'spOpacity', type: 'integer', min: 0, max: 100 },
+  { key: 'spModelUploadId', type: 'string' },
+  { key: 'spModelDocId', type: 'string' },
+
+  // Slides
+  { key: 'slidesTransition', type: 'string-enum', values: ['none', 'fade', 'slide'] },
+  { key: 'slidesTheme', type: 'string-enum', values: ['dark', 'light'] },
+
+  // Migration version (last so unknown keys ahead of it surface clearly)
+  { key: '__schemaVersion', type: 'integer', min: 0 },
+] as const
+
+export const UNIVERSAL_META_KEY_NAMES: ReadonlySet<string> = new Set(
+  UNIVERSAL_META_KEYS.map(k => k.key),
+)
+
+/**
+ * Build a map of every recognised input key (canonical + aliases) to
+ * its canonical key. Used by the frontmatter parser.
+ */
+export function buildAliasMap(): ReadonlyMap<string, string> {
+  const map = new Map<string, string>()
+  for (const entry of UNIVERSAL_META_KEYS) {
+    map.set(entry.key, entry.key)
+    for (const alias of entry.parseAliases ?? []) map.set(alias, entry.key)
+  }
+  return map
+}

package/src/types.ts

@@ -0,0 +1,89 @@
+// Shared types for the markdown ↔ Y.js converter.
+//
+// `DocPageMeta` is the metadata bag this package reads/writes in YAML
+// frontmatter. It mirrors the universal-meta surface in
+// `@abraca/schema/types/universal.ts` — the schema package is the
+// source of truth; this declaration stays minimal and additive so the
+// converter can be used standalone without pulling in schema.
+//
+// Universal fields cover every page-type; renderer-specific fields are
+// included so round-trip works for kanban cards, calendar events,
+// timeline tasks, spatial nodes, etc.
+
+export interface DocPageMeta extends Record<string, unknown> {
+  // Universal color + icon
+  color?: string
+  icon?: string
+
+  // Datetime / date / time fields
+  datetimeStart?: string
+  datetimeEnd?: string
+  allDay?: boolean
+  dateTaken?: string
+  dateStart?: string
+  dateEnd?: string
+  timeStart?: string
+  timeEnd?: string
+
+  // Progress / member references
+  taskProgress?: number
+  members?: { id: string, label: string }[]
+
+  // Generic fields
+  tags?: string[]
+  checked?: boolean
+  priority?: number
+  status?: string
+  rating?: number
+  url?: string
+  email?: string
+  phone?: string
+  number?: number
+  unit?: string
+  subtitle?: string
+  note?: string
+
+  // Gallery / cover
+  coverUploadId?: string
+  coverDocId?: string
+  coverMimeType?: string
+
+  // Map / geo
+  geoType?: 'marker' | 'line' | 'measure'
+  geoLat?: number
+  geoLng?: number
+  geoDescription?: string
+
+  // Dashboard / mindmap / graph
+  deskX?: number
+  deskY?: number
+  deskZ?: number
+  deskMode?: string
+  mmX?: number
+  mmY?: number
+  graphX?: number
+  graphY?: number
+  graphPinned?: boolean
+
+  // Spatial
+  spX?: number
+  spY?: number
+  spZ?: number
+  spRX?: number
+  spRY?: number
+  spRZ?: number
+  spSX?: number
+  spSY?: number
+  spSZ?: number
+  spShape?: string
+  spOpacity?: number
+  spModelUploadId?: string
+  spModelDocId?: string
+
+  // Slides
+  slidesTransition?: 'none' | 'fade' | 'slide'
+  slidesTheme?: 'dark' | 'light'
+
+  // Schema migration version
+  __schemaVersion?: number
+}