Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

33.7 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
//
// Shape validation for document fragments that arrive from OUTSIDE the deck.
//
// WHY THIS EXISTS. The system clipboard is not a trusted channel: any web page
// with a Copy button can put a Bento clip payload on it, and one ⌘V into an
// open editor used to splice whatever it carried straight into the document.
// That is worse than junk data, because model values are interpolated into
// markup and CSS all over the renderer.
//
// This is the SECOND layer, not the only one. render.ts now escapes and
// validates every value renderTableHtml writes into a `style` attribute
// (cssColor/cssNum/cssFont — see scripts/test-sanitize.ts), so the specific
// `red" onmouseover="…` cell colour no longer mints a handler. But that gate
// covers one function and one field family: `fit` still lands raw in an
// <img>'s cssText, a font's `weight` raw in an @font-face rule (fonts.ts),
// and every renderer written after this one inherits whatever the model was
// allowed to hold. A value that cannot BE in the document cannot be
// mis-rendered by code nobody has written yet, so the model itself is held to
// a shape here — and where the two layers judge the same kind of value, they
// judge it by the same rule (see `color` below).
//
// So a foreign fragment is REBUILT here, key by key, against the format's own
// key table (modelkeys.generated.ts — derived from model.ts and pinned by CI,
// so it cannot drift the way a hand-written list would). An unknown element
// type, an unknown key, an enum that is not one of the literals, a string
// where a number belongs: DROPPED, never repaired. Repairing an attacker's
// value keeps it in the document with our blessing; dropping it costs a paste
// one property, which renders as a plain element. The single exception is
// numeric coercion ("12" → 12), which cannot smuggle anything.
//
// Dropping a property is not always enough, though: an element the format
// requires a key for is not a plain element without it, it is one the renderer
// throws on. Those keys are named in REQUIRED_ELEMENT_KEYS and take the whole
// element with them; nested objects do the same through `shape`'s `required`.
//
// Deliberately DOM-free and with no idea what a clipboard is: the other
// untrusted intake — remote CRDT ops off the relay — can adopt the same
// checks, key by key, through `checkElementProp`.

import { stripEnvelope } from './envelope'
import type { Slide, SlideElement } from './model'
import { isWebUrl, REQUIRED_ELEMENT_KEYS } from './model'
import { parseThemeRef } from './palette.ts'
import { MODEL_KEYS } from './modelkeys.generated'
import { TIP_KINDS } from './tips'

/** Reject. JSON has no `undefined`, so it can never collide with a real value. */
const DROP = undefined
/**
 * A check carries a DESCRIPTION of what it accepts (a JSON Schema fragment) so
 * the same table that gates a paste can be printed for agents — schema.ts
 * builds `https://bento.page/schema/slides.json` and `window.bento.schema()`
 * from these, and CI pins the checked-in file to them. The description is
 * metadata on the function: attaching it changes nothing about what the
 * check does, and a check with none is emitted as an untyped value.
 */
export type JsonSchema = Record<string, unknown>
type Check = ((v: unknown) => unknown) & { schema?: JsonSchema }
const tag = (fn: (v: unknown) => unknown, schema: JsonSchema): Check => Object.assign(fn, { schema })

/**
 * The load report (compact input, round two). The gate drops silently by
 * design — that is right for a hostile file and wrong for an agent that
 * misspelled `fontSize`. `withDropReport` runs a gate call with a collector
 * attached; every drop names a JSON-pointer-ish path and a one-line reason.
 * Off by default: with no collector, `note()` is one null check and the path
 * stack is never touched, so a paste or a remote op costs what it did.
 */
export interface Dropped { path: string; reason: string }
let collector: Dropped[] | null = null
const trail: string[] = []
const note = (key: string | null, reason: string) => {
  if (!collector) return
  collector.push({ path: '/' + (key === null ? trail : [...trail, key]).join('/'), reason })
}
const within = <T>(key: string, fn: () => T): T => {
  if (!collector) return fn()
  trail.push(key)
  try { return fn() } finally { trail.pop() }
}
/** Add a segment to the report path around `fn` — for a caller that walks a
 *  list itself (compactload.ts adds /slides/<i>). No-op with no collector. */
export const withPathSegment = <T>(key: string, fn: () => T): T => within(key, fn)
/** Run `fn` collecting every drop the gate makes; returns the list. */
export function withDropReport<T>(fn: () => T): { result: T; dropped: Dropped[] } {
  // Nesting: an inner report gets its own list and a fresh trail, and the
  // outer one gets both of its back afterwards — so a gate call that itself
  // asks for a report (none does today) cannot truncate the caller's paths.
  const prevCollector = collector
  const prevTrail = trail.splice(0)
  const dropped: Dropped[] = []
  collector = dropped
  try { return { result: fn(), dropped } }
  finally { collector = prevCollector; trail.splice(0, trail.length, ...prevTrail) }
}

/**
 * Assigning `out['__proto__'] = x` on a plain object walks the setter and
 * changes the prototype — so this key is skipped everywhere a foreign object
 * is copied, including inside a chart option's free-form JSON.
 */
const PROTO = '__proto__'

/**
 * Ceilings. None of these is a security boundary on its own; they exist so a
 * payload that passes every shape check still cannot be a denial of service —
 * an editor that hangs on ⌘V is as lost as one that runs a script.
 */
export const LIMITS = {
  /** ids, group tags, asset keys, a slide's `background` shorthand */
  scalar: 200,
  /** one colour notation. The longest seen in a real deck (one converted from
   *  a design tool) is 45: `color(srgb 0.156863 0.188235 … / 0.55)`.
   *  render.ts:cssColor caps at 48 — it FALLS BACK past that, this DROPS, so a
   *  little more headroom here costs a degraded colour rather than a lost one. */
  color: 64,
  /** palette references on one element — far above any real element */
  themeRefs: 64,
  /** a CSS font stack names several families */
  fontStack: 300,
  /** placeholder prompts and comment prose */
  prose: 4_000,
  /** rich text of one text element or table cell */
  html: 64 * 1024,
  /** raw <svg> markup of one svg element (a detailed map runs to ~1MB) */
  markup: 4 * 1024 * 1024,
  /** css injected inside one svg element */
  css: 128 * 1024,
  /** one asset: a data: URI (image, font, embedded clip) or raw svg markup */
  asset: 32 * 1024 * 1024,
  assets: 2_000,
  /** the whole clipboard string, before it is even parsed. Sized off what a
   *  legitimate copy can reach, not off a round number: one embedded clip is
   *  MEDIA_EMBED_BUDGET (8MB) → ~10.7MB of base64, so five media slides is
   *  ~54MB. Costs nothing at that size — JSON.parse of a 64MB payload measured
   *  21ms (node 24, M-series, 2026-08-09) — and the 40MB it replaces turned an
   *  oversized-but-real slide copy into 4000 characters of raw JSON pasted as
   *  a text element (editor.ts's plain-text fallback). */
  clipText: 64 * 1024 * 1024,
  elements: 5_000,
  slides: 500,
  rows: 2_000,
  cols: 200,
  comments: 500,
  stops: 64,
  speeds: 2_000,
  /** a chart option is free-form JSON — bounded, not typed */
  optionNodes: 20_000,
  optionDepth: 12,
}

/**
 * Characters that end a CSS value or an HTML attribute early. A colour, a
 * blend mode or a font weight never needs one; a payload that carries one is
 * aiming at the unescaped interpolations in render.ts / fonts.ts.
 */
const CSS_BREAKOUT = /["'<>{};]/
/** Path data is numbers and command letters. Nothing else is a path. */
const PATH_DATA = /^[MmLlHhVvCcSsQqTtAaZz0-9\s,.+\-eE]*$/
/** A scheme we know how to serve; anything else (javascript:, …) is dropped. */
const SAFE_SCHEME = /^(?:data|asset|blob|https?):/i
const HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i

const isPlainObject = (v: unknown): v is Record<string, unknown> =>
  typeof v === 'object' && v !== null && !Array.isArray(v)

/** Finite number, or a numeric string coerced to one. Out of range = DROP. */
const num = (min: number, max: number): Check => tag((v) => {
  const n = typeof v === 'string' && v.trim() !== '' ? Number(v) : v
  return typeof n === 'number' && Number.isFinite(n) && n >= min && n <= max ? n : DROP
}, { type: 'number', minimum: min, maximum: max })
const bool: Check = tag((v) => (typeof v === 'boolean' ? v : DROP), { type: 'boolean' })
const oneOf = (...allowed: string[]): Check => tag((v) =>
  typeof v === 'string' && allowed.includes(v) ? v : DROP, { type: 'string', enum: allowed })
/** Free text that reaches the DOM as text, never as markup. */
const str = (max: number): Check => tag((v) => (typeof v === 'string' && v.length <= max ? v : DROP), { type: 'string', maxLength: max })
/** A value that ends up inside a CSS declaration or an HTML attribute. */
const cssValue = (max = LIMITS.scalar): Check => tag((v) =>
  typeof v === 'string' && v.length <= max && !CSS_BREAKOUT.test(v) ? v : DROP,
  { type: 'string', maxLength: max, pattern: '^[^"\'<>{};]*$' })
/**
 * A COLOUR, judged by exactly the rule render.ts:cssColor applies when it
 * writes one into markup — same allowlist, same `url(`/`expression`/`@`/`\`
 * rejection. Kept in step deliberately: CSS_BREAKOUT alone permits `(`, `)`
 * and `:`, which is strictly weaker, and the weaker of two layers is the one
 * that decides. Measured on the pre-change validator: a shadow colour of
 * `red) url(https://evil/f.svg#f` passed here and reached `style.filter`
 * through render.ts:applyElementFrame, which interpolates it raw — a paste
 * that fetches a remote file. Colours are the one model field that reaches
 * CSS in a dozen places, so they get one rule rather than a per-site one.
 */
const COLOR_CHARS = /^[#a-zA-Z0-9(),.%\s/-]+$/
const COLOR_TRICKS = /url\s*\(|expression|@|\\/i
const color = (max = LIMITS.color): Check => tag((v) => {
  if (typeof v !== 'string') return DROP
  const s = v.trim()
  return s && s.length <= max && COLOR_CHARS.test(s) && !COLOR_TRICKS.test(s) ? v : DROP
}, { type: 'string', maxLength: max, description: 'CSS colour; no url()' })
/**
 * An svg PAINT (`fill` / `stroke`): a colour, or a reference to a gradient or
 * filter defined inside this document's own markup. The quoted form is what
 * real files carry — a shape in a real deck paints `fill: url("#core-glow")`,
 * and the pre-change validator dropped it (CSS_BREAKOUT rejects `"`),
 * leaving render.ts:shapeSvg to write
 * `fill="undefined"` and paint the shape BLACK. Only a bare fragment id is
 * allowed: `url(https://evil/track.svg#g)` is a network fetch the paste never
 * asked for, and it is a colour rule that would otherwise wave it through.
 */
const LOCAL_PAINT_REF = /^url\(\s*(?:"#[\w.:-]+"|'#[\w.:-]+'|#[\w.:-]+)\s*\)$/
const paint: Check = tag((v) =>
  typeof v === 'string' && v.length <= LIMITS.color && LOCAL_PAINT_REF.test(v.trim()) ? v : color()(v),
  { type: 'string', maxLength: LIMITS.color, description: 'CSS colour or url(#local-id)' })
/**
 * A font stack, which legitimately quotes multi-word families ('Segoe UI').
 * Quotes are therefore allowed here — renderTableHtml escapes them, and
 * injectFonts passes the family through JSON.stringify — but a brace or a
 * semicolon still ends a declaration, so those are not.
 */
const fontStack: Check = tag((v) =>
  typeof v === 'string' && v.length <= LIMITS.fontStack && !/[<>{};]/.test(v) ? v : DROP,
  { type: 'string', maxLength: LIMITS.fontStack })
const pathData: Check = tag((v) =>
  typeof v === 'string' && v.length <= LIMITS.html && PATH_DATA.test(v) ? v : DROP,
  { type: 'string', maxLength: LIMITS.html, description: 'SVG path data' })
/**
 * src / poster: a data: URI, an asset: key, a URL, or a relative path.
 *
 * A schemed value is NOT held to CSS_BREAKOUT — a data: URI legitimately
 * carries quotes and semicolons, so demanding they be absent would reject the
 * embedded-image case this field exists for. That means `https://evil/a">…`
 * survives, and it is safe only because of a property of the CONSUMERS: every
 * one of them assigns it as a DOM property (`img.src`, `video.src`,
 * resolveAsset → the same), where the string is a value and never re-parsed as
 * markup. A renderer that string-builds `<img src="${el.src}">` would turn
 * this into an attribute breakout, so it must escape or re-check — noted here
 * because the safety lives at the call site, not in this value.
 */
const mediaRef: Check = tag((v) => {
  if (typeof v !== 'string' || v.length > LIMITS.asset) return DROP
  if (HAS_SCHEME.test(v)) return SAFE_SCHEME.test(v) ? v : DROP
  return CSS_BREAKOUT.test(v) ? DROP : v // a bare path still lands in an attribute
}, { type: 'string', maxLength: LIMITS.asset, description: 'data: URI, asset:<key> or URL' })

/**
 * Rebuild an object from a key table, dropping every key and value it fails.
 *
 * `required` names the keys the format does not make optional. Without it a
 * nested object whose every key failed came back as `{}` — a shadow with no
 * blur, a gradient with no stops — and the renderer then interpolated
 * `undefined` into a CSS declaration or called `.map` on nothing. Measured:
 * `colorGradient:{angle:90}` survived the pre-change validator and
 * render.ts:cssLinearGradient threw "Cannot read properties of undefined
 * (reading 'map')". A half-object is not a repairable object.
 */
function shape(
  keys: readonly string[], checks: Record<string, Check>, required: readonly string[] = [],
): Check {
  return tag((v) => {
    if (!isPlainObject(v)) return DROP
    const out: Record<string, unknown> = {}
    for (const key of Object.keys(v)) {
      if (key === PROTO || !keys.includes(key)) { note(key, 'unknown key'); continue }
      const val = within(key, () => checks[key]?.(v[key]))
      if (val !== DROP) out[key] = val
      else note(key, 'invalid value')
    }
    const missing = required.filter((key) => out[key] === DROP)
    if (missing.length) { note(null, `missing required ${missing.join(', ')} — object dropped`); return DROP }
    return out
  }, objectSchema(keys, checks, required))
}

/** The schema of a `shape`: exactly the keys it keeps, each as its check says. */
export function objectSchema(
  keys: readonly string[], checks: Record<string, Check>, required: readonly string[] = [],
): JsonSchema {
  const properties: Record<string, JsonSchema> = {}
  for (const key of keys) if (checks[key]) properties[key] = checks[key].schema ?? {}
  const out: JsonSchema = { type: 'object', properties, additionalProperties: false }
  if (required.length) out.required = [...required]
  return out
}

/**
 * A homogeneous array. One bad entry drops the WHOLE array, because these
 * arrays are positional — a table's cells line up with its columns, a chart's
 * data with its labels — and silently closing a hole would misalign the rest.
 */
const list = (max: number, item: Check): Check => tag((v) => {
  if (!Array.isArray(v) || v.length > max) { note(null, Array.isArray(v) ? `more than ${max} entries` : 'not a list'); return DROP }
  const out: unknown[] = []
  for (let i = 0; i < v.length; i++) {
    const val = within(String(i), () => item(v[i]))
    if (val === DROP) { note(String(i), 'invalid entry — the whole list is dropped'); return DROP }
    out.push(val)
  }
  return out
}, { type: 'array', maxItems: max, items: item.schema ?? {} })

const gradient = shape(MODEL_KEYS.gradient, {
  angle: num(-3600, 3600),
  stops: list(LIMITS.stops, shape(
    ['at', 'color'], { at: num(0, 1), color: color() }, ['at', 'color'],
  )),
}, ['stops'])

const shadowSpec = shape(MODEL_KEYS.shadow, {
  x: num(-1e4, 1e4), y: num(-1e4, 1e4), blur: num(0, 1e4), color: color(),
}, ['blur', 'color'])

const fx = shape(MODEL_KEYS.fx, {
  enter: oneOf('fade-up', 'fade', 'fade-down', 'slide-left', 'slide-right', 'slide-up', 'slide-down'),
  enterDur: num(0, 600),
  order: num(-1e4, 1e4),
  step: num(0, 1e4),
  countUp: bool,
  typeWriter: bool,
  ambient: oneOf('kenburns'),
  ken: shape(MODEL_KEYS.fxKen, {
    dir: oneOf('drift', 'out', 'in'), scale: num(0, 100), duration: num(0, 3600),
  }),
  loop: shape(MODEL_KEYS.fxLoop, {
    type: oneOf('dash-march', 'motion-path'),
    path: pathData,
    duration: num(0, 3600),
    delay: num(0, 3600),
    distance: num(-1e5, 1e5),
    ease: cssValue(64),
    speeds: list(LIMITS.speeds, num(0.001, 1000)),
  }, ['type']), // anim.ts dispatches on it; a loop with no type animates nothing
})

const tableStyle = shape(MODEL_KEYS.tableStyle, {
  headerBg: color(), headerColor: color(), zebra: color(),
  borderColor: color(), borderWidth: num(0, 1e3),
  cellPadX: num(0, 1e3), cellPadY: num(0, 1e3),
  fontSize: num(0, 4000), fontFamily: fontStack, color: color(), radius: num(0, 1e5),
})

// `cells` is required: renderTableHtml walks `row.cells.map` with no guard
const tableRows = list(LIMITS.rows, shape(MODEL_KEYS.tableRow, {
  cells: list(LIMITS.cols, shape(MODEL_KEYS.tableCell, {
    html: str(LIMITS.html),
    align: oneOf('left', 'center', 'right'),
    color: color(), bg: color(), bold: bool,
  })),
}, ['cells']))

/**
 * A chart option is free-form ECharts-shaped JSON that charts-lite interprets
 * key by key, so there is no key table to check it against. What CAN be
 * checked is that it IS plain, bounded JSON — nothing exotic, nothing so deep
 * or so large that drawing it hangs the editor. Anything unexpected anywhere
 * inside drops the WHOLE option (a chart without one renders as an empty svg;
 * chartSnapshotSvg already catches), because a half-pruned option is still an
 * attacker's shape, kept.
 */
const chartOption: Check = tag((v) => {
  if (!isPlainObject(v)) return DROP
  let nodes = LIMITS.optionNodes
  const pure = (node: unknown, depth: number): boolean => {
    if (--nodes < 0 || depth < 0) return false
    if (node === null) return true
    switch (typeof node) {
      case 'boolean': return true
      case 'number': return Number.isFinite(node)
      case 'string': return node.length <= LIMITS.html
      case 'object': break
      default: return false // functions and symbols never survive JSON anyway
    }
    if (Array.isArray(node)) return node.every((entry) => pure(entry, depth - 1))
    if (!isPlainObject(node)) return false
    return Object.keys(node).every(
      (key) => key !== PROTO && key.length <= LIMITS.scalar && pure(node[key], depth - 1),
    )
  }
  return pure(v, LIMITS.optionDepth) ? v : DROP
}, { type: 'object', description: 'ECharts-shaped option, plain JSON' })

/**
 * The `embed` element. `url` is what a live iframe LOADS, so it
 * is held to http(s) and nothing else: a `javascript:` or `data:` page in a
 * sandboxed frame cannot reach this document, but it would still be a page
 * of someone else's choosing running on the reader's screen. `view` is svg
 * markup or an `asset:` ref and gets the svg element's own ceiling; what the
 * renderer does with the markup is the renderer's business (sanitizeSvg).
 * `doc` is the source: an asset ref, or the same bounded plain JSON a chart
 * option is held to: a source is data, never code (docs/format.md).
 */
// Not held to CSS_BREAKOUT: a query string legitimately carries `;` and
// quotes, and the one consumer assigns it as a DOM property (`iframe.src`),
// where it is a value and never re-parsed as markup (the mediaRef argument).
const webUrl: Check = tag((v) =>
  typeof v === 'string' && v.length <= LIMITS.prose && isWebUrl(v) ? v : DROP,
  { type: 'string', maxLength: LIMITS.prose, pattern: '^https?://' })
// An embedded document is another deck's JSON, and a deck's envelope carries
// its collaboration secrets: `collab` (room, read key, private halves, and the
// saved sync state) and `docId`. Neither is content. Left in place they would
// pass this gate, survive every save by additivity, and travel with every copy
// and export — and the export-secrets rig reads the top-level block only. So
// an object source leaves here without them, whatever put them there — by the
// same rule the export strip applies on the way out (envelope.ts).
const embedDoc: Check = tag((v) => (typeof v === 'string' ? cssValue()(v) : stripEnvelope(chartOption(v))),
  { anyOf: [{ type: 'string', maxLength: LIMITS.scalar }, { type: 'object' }] })

// `el` is required: a connector end with no element to anchor to is dangling,
// and editor.syncConnectors drops those anyway
const connectorEnd = shape(MODEL_KEYS.connectorEnd, {
  el: cssValue(), side: oneOf('auto', 'top', 'right', 'bottom', 'left'),
}, ['el'])

/**
 * One check per property the format defines on an element, keyed by property
 * name — the names do not collide across element types (`loop` is a media
 * boolean; the animation loop lives under `fx`, checked by its own table).
 *
 * Every name in MODEL_KEYS.element must appear here or it is dropped as if it
 * were unknown; scripts/test-clipboard.ts asserts the coverage, so adding a
 * field to model.ts fails the rig until it is taught here too.
 */
/**
 * Palette references: a map of property PATH → palette token.
 *
 * Two reasons this cannot be waved through. The paths are WALKED by
 * palette.ts to write a resolved colour, so a path segment of `__proto__` or
 * `constructor` is reaching for the prototype chain — the writer refuses to
 * create anything that is not already a string, which blocks it, but a paste
 * boundary should not be relying on a downstream guard. And a token that does
 * not parse is dead weight the validator will report forever, so it is dropped
 * here rather than carried.
 */
const themeRefs: Check = tag((v) => {
  if (!isPlainObject(v)) return DROP
  const out: Record<string, string> = {}
  let n = 0
  for (const key of Object.keys(v)) {
    if (++n > LIMITS.themeRefs) break
    const token = v[key]
    if (typeof token !== 'string' || token.length > LIMITS.scalar) continue
    if (key.length > LIMITS.scalar) continue
    // path segments: identifiers and array indices only
    const segs = key.split('.')
    if (!segs.length || !segs.every((sg) => /^[A-Za-z_$][A-Za-z0-9_$]*$|^\d+$/.test(sg))) continue
    if (segs.some((sg) => sg === PROTO || sg === 'constructor' || sg === 'prototype')) continue
    if (!parseThemeRef(token)) continue
    out[key] = token
  }
  return Object.keys(out).length ? out : DROP
}, { type: 'object', additionalProperties: { type: 'string' }, maxProperties: LIMITS.themeRefs, description: 'property path → palette token' })

export const ELEMENT_CHECKS: Record<string, Check> = {
  themeRefs,
  // identity + geometry
  id: cssValue(), morphId: cssValue(), role: cssValue(), group: cssValue(),
  groupId: cssValue(), showOnHover: cssValue(),
  // a slide id, or an http(s) URL — the same test the renderer and the show apply
  link: tag((v) => (isWebUrl(v) ? v : cssValue()(v)), { type: 'string', maxLength: LIMITS.prose, description: 'slide id or http(s) URL' }),
  x: num(-1e6, 1e6), y: num(-1e6, 1e6), w: num(0, 1e6), h: num(0, 1e6),
  rotation: num(-3600, 3600), opacity: num(0, 1),
  shadow: tag((v) => (Array.isArray(v) ? list(16, shadowSpec)(v) : shadowSpec(v)), { anyOf: [shadowSpec.schema!, { type: 'array', maxItems: 16, items: shadowSpec.schema! }] }),
  blur: num(0, 1000), backdropFilter: num(0, 1000), blend: cssValue(64),
  fx,
  // text
  html: str(LIMITS.html), placeholder: str(LIMITS.prose),
  fontSize: num(0, 4000), fontFamily: fontStack, fontWeight: num(1, 1000),
  lineHeight: num(0, 100), letterSpacing: num(-1000, 1000),
  color: color(), colorGradient: gradient,
  align: oneOf('left', 'center', 'right'), valign: oneOf('top', 'middle', 'bottom'),
  textStroke: shape(['width', 'color', 'fill'], {
    width: num(0, 1e3), color: color(), fill: color(),
  }, ['width', 'color']),
  // shape
  shape: oneOf('rect', 'ellipse', 'triangle', 'arrow', 'line', 'path'),
  heads: num(2, 2),
  fill: paint, fillGradient: gradient, stroke: paint,
  strokeWidth: num(0, 1e4), strokeDash: num(0, 1e4),
  strokeStyle: oneOf('solid', 'dashed', 'dotted'),
  // the tip list is tips.ts's — one catalogue for the gate, the panel and the renderer
  lineStart: oneOf(...TIP_KINDS), lineEnd: oneOf(...TIP_KINDS),
  radius: num(0, 1e5), d: pathData,
  pathBox: tag((v) => (Array.isArray(v) && v.length === 4 ? list(4, num(-1e6, 1e6))(v) : DROP), { type: 'array', minItems: 4, maxItems: 4, items: { type: 'number' } }),
  from: connectorEnd, to: connectorEnd,
  // image / svg / media
  src: mediaRef, poster: mediaRef, asset: cssValue(),
  fit: oneOf('contain', 'cover', 'fill'), keepAspectRatio: bool,
  crop: shape(MODEL_KEYS.imageCrop, { x: num(0, 1), y: num(0, 1), scale: num(1, 64) }, ['x', 'y', 'scale']),
  markup: str(LIMITS.markup), css: str(LIMITS.css),
  kind: oneOf('video', 'audio'),
  autoplay: bool, loop: bool, muted: bool, controls: bool,
  // chart / table
  preset: cssValue(), option: chartOption,
  source: shape(['tableId'], { tableId: cssValue() }, ['tableId']),
  columns: list(LIMITS.cols, shape(['w'], { w: num(0, 1e6) }, ['w'])),
  rows: tableRows, header: bool, style: tableStyle,
  // embed
  app: cssValue(), view: str(LIMITS.markup), doc: embedDoc, url: webUrl, live: bool,
  // code — the raw snippet is text (code.ts tokenizes it, never innerHTML);
  // grammar/theme names and asset ids land in lookups, not markup. Not in
  // REQUIRED_ELEMENT_KEYS: renderCodeInto returns false without content and
  // the caller falls back to plain text — a degrade, not a throw.
  content: str(LIMITS.html), grammarName: cssValue(64), themeName: cssValue(64),
  grammarAssetId: cssValue(), themeAssetId: cssValue(),
  type: oneOf(...Object.keys(MODEL_KEYS.element)),
}

/**
 * The keys each element type cannot render WITHOUT. Hand-written because
 * modelkeys.generated.ts records names, not optionality; scripts/test-clipboard.ts
 * pins every entry to a measured failure and asserts each name is real.
 *
 * All six were reproduced against the pre-change validator, which emitted the
 * element anyway (`{type:'table',id:'t'}` came back as `{type:'table',id:'t'}`):
 *
 *   table   columns → renderTableHtml "…(reading 'reduce')" on el.columns
 *           rows    → same, "…(reading 'map')" once columns is supplied
 *   text    html    → resolveFields (render.ts) "…(reading 'indexOf')"
 *   image   src     → resolveAsset "…(reading 'startsWith')"
 *   shape   shape   → shapeSvg's switch matches nothing, node stays undefined
 *           fill    → shapeSvg writes fill="undefined" and the shape paints
 *                     BLACK — the same corruption a rejected `url("#core-glow")`
 *                     used to cause, arriving by the other door
 *   chart   option  → charts-lite has no series to read
 *   media   kind    → the poster/icon still branches on it
 *           src     → nothing to play
 *
 * Not listed, deliberately: values that only DEGRADE. Geometry
 * (x/y/w/h/rotation/opacity) and strokeWidth stringify to "undefinedpx"/"NaN",
 * which CSS and SVG ignore, so the element lands at a default frame instead of
 * throwing — losing a whole pasted element over a defaultable number is the
 * worse trade. `svg` is absent for a different reason: its content comes from
 * `markup` OR `asset` (2 of the 4780 elements in a real deck use the asset
 * form), and svgMarkup already falls back to ''. `embed` is
 * absent for the same reason: an empty or refused `view` paints a
 * placeholder, never throws.
 */
// The table itself lives in model.ts: parseDoc holds a FILE to the same rule
// (an element that cannot render is dropped there too), and one list cannot
// drift from itself.

/** Exported so the rig can prove each name is a real key of that element type. */
export const REQUIRED_KEYS: Readonly<Record<string, readonly string[]>> = REQUIRED_ELEMENT_KEYS

/**
 * Check ONE element property in isolation — the entry point for property-level
 * intake such as remote CRDT ops, where a whole element is never in hand.
 * Returns the value to store; `ok:false` means the op must be ignored.
 */
export function checkElementProp(
  type: string, key: string, value: unknown,
): { ok: boolean; value?: unknown } {
  const known = (MODEL_KEYS.element as Record<string, readonly string[]>)[type]
  if (!known || !known.includes(key) || key === PROTO) return { ok: false }
  const val = ELEMENT_CHECKS[key]?.(value)
  return val === DROP ? { ok: false } : { ok: true, value: val }
}

/** Rebuild a foreign element, or null if it is not one. */
export function sanitizeElement(value: unknown): SlideElement | null {
  if (!isPlainObject(value)) { note(null, 'not an object — element dropped'); return null }
  const type = value.type
  if (typeof type !== 'string') { note('type', 'missing — element dropped'); return null }
  const known = (MODEL_KEYS.element as Record<string, readonly string[]>)[type]
  if (!known) { note('type', `unknown element type "${type}" — element dropped`); return null }
  // Identity is not optional: ids anchor selection, morph, comments and the
  // CRDT node key, and a slide paste keeps them (only slide ids are reminted).
  const id = ELEMENT_CHECKS.id(value.id)
  if (typeof id !== 'string' || !id) { note('id', 'missing or invalid — element dropped'); return null }
  const out: Record<string, unknown> = { type, id }
  for (const key of Object.keys(value)) {
    if (key === 'type' || key === 'id') continue
    if (key === PROTO || !known.includes(key)) { note(key, `unknown key for a ${type} element`); continue }
    const val = within(key, () => ELEMENT_CHECKS[key]?.(value[key]))
    if (val !== DROP) out[key] = val
    else note(key, 'invalid value')
  }
  // An element missing what its type needs is not a degraded element, it is one
  // the format cannot express — and the renderer throws on it (see above), which
  // takes the whole slide down, not just the paste.
  const missing = (REQUIRED_ELEMENT_KEYS[type] ?? []).filter((key) => out[key] === DROP)
  if (missing.length) { note(null, `missing required ${missing.join(', ')} — element dropped`); return null }
  return out as unknown as SlideElement
}


export const SLIDE_CHECKS: Record<string, Check> = {
  id: cssValue(), name: str(LIMITS.prose), stateOf: cssValue(), themeRefs,
  // background is a CSS `background` shorthand, so it gets the colour rule at
  // the shorthand's length — wide enough for a multi-stop linear-gradient(),
  // still no url() reaching for the network from a pasted slide
  background: color(LIMITS.scalar), notes: str(LIMITS.html),
  hidden: bool, unnumbered: bool,
  transition: oneOf('none', 'fade', 'slide', 'zoom', 'morph'),
  hover: shape(['type', 'dim', 'default'], {
    type: oneOf('focus-group', 'reveal'), dim: num(0, 1), default: cssValue(),
  }, ['type']),
  comments: list(LIMITS.comments, shape(MODEL_KEYS.comment, {
    id: cssValue(), elementId: cssValue(), x: num(-1e6, 1e6), y: num(-1e6, 1e6),
    author: str(LIMITS.prose), text: str(LIMITS.prose), at: str(LIMITS.scalar), resolved: bool,
    replies: list(LIMITS.comments, shape(['id', 'author', 'text', 'at'], {
      id: cssValue(), author: str(LIMITS.prose), text: str(LIMITS.prose), at: str(LIMITS.scalar),
    })),
  })),
  // elements are dropped INDIVIDUALLY: one hostile element must not cost the
  // author the rest of a legitimately copied slide
  elements: tag((v) => (Array.isArray(v) && v.length <= LIMITS.elements
    ? v.map((el, i) => within(String(i), () => sanitizeElement(el))).filter((el): el is SlideElement => el !== null)
    : DROP), { type: 'array', maxItems: LIMITS.elements, items: { $ref: '#/$defs/element' } }),
}

/**
 * The property names checked above. scripts/test-clipboard.ts asserts that
 * every name in MODEL_KEYS covers one — a field added to model.ts and not
 * taught here would be dropped from every paste, silently, which is exactly
 * the class of failure this file exists to stop.
 */
export const CHECKED_KEYS = {
  element: Object.keys(ELEMENT_CHECKS),
  slide: Object.keys(SLIDE_CHECKS),
}

/** Rebuild a foreign slide, or null if it is not one. */
export function sanitizeSlide(value: unknown): Slide | null {
  if (!isPlainObject(value)) { note(null, 'not an object — slide dropped'); return null }
  const id = SLIDE_CHECKS.id(value.id)
  if (typeof id !== 'string' || !id) { note('id', 'missing or invalid — slide dropped'); return null }
  const out = shape(MODEL_KEYS.slide, SLIDE_CHECKS)(value) as Record<string, unknown>
  if (!Array.isArray(out.elements)) out.elements = []
  return out as unknown as Slide
}

/**
 * Rebuild a foreign asset table. Keys become `asset:` references and object
 * keys; values are opaque bytes (a data: URI) or raw svg markup, so they are
 * checked for type and size only — what the renderer does with markup is the
 * renderer's business.
 */
export function sanitizeAssets(value: unknown): Record<string, string> {
  const out: Record<string, string> = {}
  if (!isPlainObject(value)) return out
  let n = 0
  for (const key of Object.keys(value)) {
    if (key === PROTO || !key || key.length > LIMITS.scalar || CSS_BREAKOUT.test(key)) continue
    const v = value[key]
    if (typeof v !== 'string' || v.length > LIMITS.asset) continue
    if (++n > LIMITS.assets) break
    out[key] = v
  }
  return out
}

/**
 * Rebuild a foreign font table. `weight` and `style` are interpolated RAW into
 * an @font-face rule by fonts.ts, so they get the CSS-value treatment; family
 * and asset must both be present or the record cannot load anything.
 */
export function sanitizeFonts(value: unknown): Array<{ family: string; asset: string }> {
  if (!Array.isArray(value)) return []
  const out: Array<{ family: string; asset: string }> = []
  for (const entry of value.slice(0, LIMITS.assets)) {
    const font = shape(['family', 'asset', 'weight', 'style'], {
      family: fontStack, asset: cssValue(), weight: cssValue(64), style: cssValue(64),
    })(entry) as Record<string, unknown> | undefined
    if (typeof font?.family === 'string' && typeof font.asset === 'string' && font.asset) {
      out.push(font as unknown as { family: string; asset: string })
    }
  }
  return out
}