Skip to content

armgit / fx0

Public Imported from GitHub
0

A lightweight design agent built with libfx. Describe a page and an agent writes it as one HTML file.

TypeScript
19.1 KB
Raw Blame
export const PREVIEW_PROTOCOL = 1
export const PREVIEW_PREPARE_MS = 10_000

// The HTTP status a failed preview frame reports (app/api/artifact-frame/route.ts).
export function isPreviewErrorStatus(value: unknown): value is number {
  return typeof value === 'number' && Number.isInteger(value) && value >= 400 && value <= 599
}

export interface PreviewPayload {
  protocol: 1
  sessionId: string
  revision: number
  sourceHtml: string
  renderHtml: string
  images: { marker: string; src: string }[]
}

export interface PreviewSeed {
  sessionId: string
  revision: number
  sourceHtml: string
  renderHtml: string
  documentId: string
  parentOrigin: string
  token: string
}

// Serialized into the opaque child with .toString(); all runtime dependencies stay inside.
export function previewUpdateRuntime(seed: PreviewSeed): void {
  const htmlNamespace = 'http://www.w3.org/1999/xhtml'
  const sourceLimit = 512 * 1024
  const renderLimit = 8 * 1024 * 1024
  const textTags = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'span', 'li', 'button', 'a', 'label'])
  type Snapshot = {
    source: Document
    render: Document
    authored: Map<Element, Element>
    ids: Map<string, Element | null>
  }
  type Change = { kind: 'css' | 'style' | 'text'; before: Element; after: Element }
  let baseline: Snapshot | undefined
  let bindings = new Map<Element, Element>()
  const sheets = new Map<Element, { sheet: CSSStyleSheet | null; domText: string | null; renderText: string | null }>()
  let revision = seed.revision
  let initialized = false
  let failed = false
  let busy = false
  let lastRequestId = ''

  function reject(reason: string): never { throw new Error(reason) }
  function sameElement(a: Element, b: Element): boolean {
    return a.namespaceURI === b.namespaceURI && a.localName === b.localName && a.id === b.id
  }
  function sameAttributes(a: Element, b: Element): boolean {
    return a.attributes.length === b.attributes.length && [...a.attributes].every(attribute => {
      const other = b.getAttributeNodeNS(attribute.namespaceURI, attribute.localName)
      return other?.name === attribute.name && other.value === attribute.value
    })
  }
  function children(node: Node): Node[] {
    // Template contents must also be compared, but can never be live patch targets.
    return [...(node instanceof HTMLTemplateElement ? node.content : node).childNodes]
  }
  function sameType(a: Node, b: Node): void {
    if (a.nodeType !== b.nodeType) reject('tree-shape-changed')
    if (a.nodeType === 1 && !sameElement(a as Element, b as Element)) reject('element-identity-changed')
    if (a.nodeType === 10) {
      const left = a as DocumentType, right = b as DocumentType
      if (left.name !== right.name || left.publicId !== right.publicId || left.systemId !== right.systemId) reject('doctype-changed')
    }
  }
  function isStyle(element: Element): element is HTMLStyleElement {
    return element.namespaceURI === htmlNamespace && element.localName === 'style'
  }
  function textOnly(element: Element): boolean {
    return [...element.childNodes].every(node => node.nodeType === 3)
  }
  function bounded(source: unknown, render: unknown): source is string {
    return typeof source === 'string' && source.length <= sourceLimit &&
      typeof render === 'string' && render.length <= renderLimit &&
      new TextEncoder().encode(source).byteLength <= sourceLimit
  }
  function snapshot(source: string, render: string): Snapshot {
    const parser = new DOMParser()
    const result: Snapshot = {
      source: parser.parseFromString(source, 'text/html'),
      render: parser.parseFromString(render, 'text/html'),
      authored: new Map(), ids: new Map(),
    }
    if (result.source.doctype?.name !== 'html' || result.render.doctype?.name !== 'html') reject('missing-doctype')
    function pair(a: Node, b: Node): void {
      sameType(a, b)
      if (a.nodeType === 1) {
        const authored = a as Element, rendered = b as Element
        result.authored.set(rendered, authored)
        if (authored.id) result.ids.set(authored.id, result.ids.has(authored.id) ? null : authored)
        // Embedding CSS images may change raw style text, including an empty style.
        if (isStyle(authored) && textOnly(authored) && textOnly(rendered)) return
      }
      const left = children(a), right = children(b)
      if (left.length !== right.length) reject('source-render-shape-mismatch')
      left.forEach((node, index) => pair(node, right[index]))
    }
    pair(result.source, result.render)
    return result
  }
  function editable(element: Element): boolean {
    for (let current: Element | null = element; current; current = current.parentElement) {
      const value = current.getAttribute('contenteditable')?.toLowerCase()
      if (value === 'false') return false
      if (value === '' || value === 'true' || value === 'plaintext-only') return true
    }
    return false
  }
  function standard(element: Element): boolean {
    return element.namespaceURI === htmlNamespace && element instanceof HTMLElement && !(element instanceof HTMLUnknownElement) &&
      !element.localName.includes('-') && !element.hasAttribute('is')
  }
  function identified(element: Element, state: Snapshot, rendered: boolean): boolean {
    const authored = rendered ? state.authored.get(element) : element
    return !!authored?.id && state.ids.get(authored.id) === authored && standard(authored) &&
      standard(element) && !editable(authored) && !editable(element)
  }
  function compare(previous: Snapshot, next: Snapshot, rendered: boolean, changes: Change[], successors: Map<Element, Element>): void {
    function walk(a: Node, b: Node, inert: boolean): void {
      sameType(a, b)
      if (a.nodeType === 1) {
        const before = a as Element, after = b as Element
        if (rendered) successors.set(before, after)
        const locked = inert || before.localName === 'script'
        let styleChanged = false
        for (const attribute of [...before.attributes, ...after.attributes]) {
          const left = before.getAttributeNodeNS(attribute.namespaceURI, attribute.localName)
          const right = after.getAttributeNodeNS(attribute.namespaceURI, attribute.localName)
          if (left?.name === right?.name && left?.value === right?.value) continue
          if (locked || attribute.namespaceURI !== null || attribute.name !== 'style' ||
            !identified(before, previous, rendered) || !identified(after, next, rendered)) reject('unsupported-attribute-change')
          styleChanged = true
        }
        if (rendered && styleChanged) changes.push({ kind: 'style', before, after })
        if (!locked && isStyle(before) && textOnly(before) && textOnly(after)) {
          if (before.textContent !== after.textContent && rendered) changes.push({ kind: 'css', before, after })
          return
        }
        if (!locked && before.childNodes.length === 1 && after.childNodes.length === 1 &&
          before.firstChild!.nodeType === 3 && after.firstChild!.nodeType === 3 && before.textContent !== after.textContent) {
          if (!textTags.has(before.localName) || !identified(before, previous, rendered) || !identified(after, next, rendered)) reject('unsupported-text-change')
          if (rendered) changes.push({ kind: 'text', before, after })
          return
        }
        inert = inert || before.localName === 'template'
      } else if (a.nodeValue !== b.nodeValue) reject('unsupported-content-change')
      const left = children(a), right = children(b)
      if (left.length !== right.length) reject('tree-shape-changed')
      left.forEach((node, index) => walk(node, right[index], inert))
    }
    walk(rendered ? previous.render : previous.source, rendered ? next.render : next.source, false)
  }
  function liveIds(): Map<string, Element | null> {
    const ids = new Map<string, Element | null>()
    for (const element of document.querySelectorAll('[id]')) {
      if (element.id) ids.set(element.id, ids.has(element.id) ? null : element)
    }
    return ids
  }
  function styleText(element: HTMLStyleElement): string | null {
    const tracked = sheets.get(element)
    // CSSOM edits leave the physical text alone. Project only our own unchanged
    // bindings; an authored DOM edit or a newly inserted style still speaks for itself.
    return tracked && element.sheet === tracked.sheet && element.textContent === tracked.domText ? tracked.renderText : element.textContent
  }
  function locate(element: Element, state: Snapshot, ids: Map<string, Element | null>): Element | null {
    const authored = state.authored.get(element)!
    if (authored.id) {
      if (state.ids.get(authored.id) !== authored) return null
      const live = ids.get(authored.id)
      return live && sameElement(element, live) ? live : null
    }
    if (!isStyle(element)) return null
    const expected = [...state.authored.keys()].filter(candidate => isStyle(candidate) &&
      candidate.textContent === element.textContent && sameAttributes(candidate, element))
    const matches = [...document.querySelectorAll('style')].filter(candidate => isStyle(candidate) &&
      styleText(candidate) === element.textContent && sameAttributes(candidate, element))
    return expected.length === 1 && matches.length === 1 ? matches[0] : null
  }
  function rules(sheet: CSSStyleSheet): string {
    return JSON.stringify([...sheet.cssRules].map(rule => rule.cssText))
  }
  function parseSheet(expected: Element): CSSStyleSheet {
    // An inactive document parses ordinary sheet rules without touching the live tree.
    // Unlike constructed replaceSync(), it does not silently discard @import rules.
    const scratch = document.implementation.createHTMLDocument('')
    const style = scratch.createElement('style')
    style.media = expected.getAttribute('media') ?? ''
    style.textContent = expected.textContent
    scratch.head.append(style)
    const sheet = style.sheet
    if (!sheet || [...sheet.cssRules].some(rule => rule.type === CSSRule.IMPORT_RULE)) reject('unsupported-stylesheet-rules')
    return sheet
  }
  function checkSheet(live: HTMLStyleElement, expected: Element, canonical: CSSStyleSheet): CSSStyleSheet {
    const sheet = live.sheet, tracked = sheets.get(live)
    if (!sheet || tracked?.sheet !== sheet) reject('stylesheet-replaced')
    if (live.textContent !== tracked.domText || tracked.renderText !== expected.textContent) reject('stylesheet-text-conflict')
    for (const name of ['media', 'type', 'title']) {
      if (live.getAttribute(name) !== expected.getAttribute(name)) reject('stylesheet-state-conflict')
    }
    if (sheet.ownerNode !== live || sheet.disabled || sheet.href !== null || sheet.ownerRule !== null ||
      sheet.parentStyleSheet !== null || sheet.media.mediaText !== canonical.media.mediaText || rules(sheet) !== rules(canonical)) reject('stylesheet-cssom-conflict')
    return sheet
  }
  function preflight(changes: Change[], state: Snapshot): (() => void)[] {
    const ids = liveIds()
    return changes.map(change => {
      const { before, after, kind } = change
      const live = locate(before, state, ids)
      if (!live || !live.isConnected || bindings.get(before) !== live) reject('target-missing-or-replaced')
      if (kind === 'css') {
        if (!isStyle(live)) reject('stylesheet-target-mismatch')
        const scratch = parseSheet(before), next = parseSheet(after), sheet = checkSheet(live, before, scratch)
        const previousRules = [...scratch.cssRules].map(rule => rule.cssText), nextRules = [...next.cssRules].map(rule => rule.cssText)
        const splices: { start: number; deleteCount: number; rules: string[] }[] = []
        // Canonical no-ops retain every rule, even when identical rules are repeated.
        if (previousRules.length !== nextRules.length || previousRules.some((text, index) => text !== nextRules[index])) {
          const positions = new Map<string, number | null>()
          previousRules.forEach((text, index) => positions.set(text, positions.has(text) ? null : index))
          let previousStart = 0, nextStart = 0
          // The trailing boundary closes the last gap without replacing any shared anchor.
          for (let index = 0; index <= nextRules.length; index++) {
            const previousIndex = index === nextRules.length ? previousRules.length : positions.get(nextRules[index])
            if (previousIndex === undefined) continue
            if (previousIndex === null || previousIndex < previousStart) reject('ambiguous-or-reordered-stylesheet-rules')
            if (previousIndex > previousStart || index > nextStart) {
              for (let removed = previousStart; removed < previousIndex; removed++) {
                const rule = scratch.cssRules[removed] as CSSRule & { cssRules?: CSSRuleList }
                // Replacing a parent would detach cached, possibly unchanged descendants.
                if (rule.cssRules?.length) reject('unsupported-stylesheet-change')
              }
              splices.push({ start: previousStart, deleteCount: previousIndex - previousStart, rules: nextRules.slice(nextStart, index) })
            }
            previousStart = previousIndex + 1
            nextStart = index + 1
          }
        }
        const splice = (target: CSSStyleSheet) => {
          // Right-to-left edits leave every earlier splice's original indices valid.
          for (let index = splices.length - 1; index >= 0; index--) {
            const edit = splices[index]
            for (let offset = edit.deleteCount - 1; offset >= 0; offset--) target.deleteRule(edit.start + offset)
            for (let offset = 0; offset < edit.rules.length; offset++) target.insertRule(edit.rules[offset], edit.start + offset)
          }
        }
        // Dry-run the complete plan before any operation writes to the live document.
        // Valid CSS can still violate insertRule's ordering/namespace constraints.
        splice(scratch)
        if (rules(scratch) !== rules(next)) reject('unsupported-stylesheet-change')
        return () => {
          // Retain the sheet and all shared unchanged rules that authored code may cache.
          splice(sheet)
          sheets.get(live)!.renderText = after.textContent
          checkSheet(live, after, next)
        }
      }
      if (!standard(live) || editable(live) || (live as HTMLElement).isContentEditable || document.designMode === 'on') reject('editable-or-custom-target')
      if (kind === 'style') {
        if (live.getAttribute('style') !== before.getAttribute('style')) reject('inline-style-conflict')
        const value = after.getAttribute('style')
        return () => { if (value === null) live.removeAttribute('style'); else live.setAttribute('style', value) }
      }
      if (live.childNodes.length !== 1 || live.firstChild!.nodeType !== 3 || live.firstChild!.nodeValue !== before.firstChild!.nodeValue) reject('leaf-text-conflict')
      const text = live.firstChild!
      return () => { text.nodeValue = after.firstChild!.nodeValue }
    })
  }
  function result(requestId: string, status: 'applied' | 'reload', appliedRevision: number, reason?: string): void {
    parent.postMessage({ type: 'fx0-preview-result', protocol: 1, token: seed.token, documentId: seed.documentId,
      requestId, status, revision: appliedRevision, ...(reason ? { reason } : {}) }, seed.parentOrigin)
  }

  // This runs before authored scripts. Never reconstruct either baseline from the live DOM.
  try {
    if (!Number.isSafeInteger(revision) || revision < 0 || typeof seed.sessionId !== 'string' || !seed.sessionId ||
      typeof seed.documentId !== 'string' || !seed.documentId || typeof seed.token !== 'string' || !seed.token ||
      typeof seed.parentOrigin !== 'string' || !seed.parentOrigin || seed.parentOrigin === '*' || seed.parentOrigin === 'null' ||
      !bounded(seed.sourceHtml, seed.renderHtml)) reject('invalid-seed')
    baseline = snapshot(seed.sourceHtml, seed.renderHtml)
  } catch { failed = true }

  function loaded(): void {
    try {
      if (!baseline || failed) reject('baseline-unavailable')
      const ids = liveIds()
      for (const element of baseline.authored.keys()) {
        const live = locate(element, baseline, ids)
        if (live) {
          bindings.set(element, live)
          if (isStyle(live)) sheets.set(live, { sheet: live.sheet, domText: element.textContent, renderText: element.textContent })
        }
      }
      initialized = true
    } catch { failed = true }
    parent.postMessage({ type: 'fx0-preview-ready', protocol: 1, token: seed.token, documentId: seed.documentId,
      revision: seed.revision, ready: initialized && !failed }, seed.parentOrigin)
  }
  if (document.readyState === 'complete') loaded()
  else addEventListener('load', loaded, { once: true })

  addEventListener('message', event => {
    if (event.source !== parent || event.origin !== seed.parentOrigin) return
    const data = event.data
    const keys = ['type', 'protocol', 'token', 'documentId', 'requestId', 'baseRevision', 'revision', 'sourceHtml', 'renderHtml']
    if (!data || typeof data !== 'object' || Array.isArray(data) || Object.keys(data).length !== keys.length ||
      !Object.keys(data).every(key => keys.includes(key)) || data.type !== 'fx0-preview-apply' || data.protocol !== 1 ||
      data.token !== seed.token || data.documentId !== seed.documentId || typeof data.requestId !== 'string' ||
      !data.requestId.length || data.requestId.length > 128 || !Number.isSafeInteger(data.baseRevision) || data.baseRevision < 0 ||
      !Number.isSafeInteger(data.revision) || data.revision <= data.baseRevision || !bounded(data.sourceHtml, data.renderHtml)) return
    const requestId: string = data.requestId, requestedRevision: number = data.revision
    if (busy) { result(requestId, 'reload', revision, 'update-busy'); return }
    if (requestId === lastRequestId) { result(requestId, 'reload', revision, 'duplicate-request'); return }
    if (data.baseRevision !== revision) { result(requestId, 'reload', revision, 'stale-base-revision'); return }
    if (!initialized || failed || !baseline) { result(requestId, 'reload', revision, 'baseline-unavailable'); return }
    busy = true
    lastRequestId = requestId
    try {
      const next = snapshot(data.sourceHtml, data.renderHtml)
      const changes: Change[] = [], successors = new Map<Element, Element>()
      compare(baseline, next, false, changes, successors)
      // Even an authored no-op must account for every fully embedded render difference.
      compare(baseline, next, true, changes, successors)
      const operations = preflight(changes, baseline)
      const nextBindings = new Map<Element, Element>()
      for (const [before, after] of successors) {
        const live = bindings.get(before)
        if (live) nextBindings.set(after, live)
      }
      for (const apply of operations) apply()
      baseline = next
      bindings = nextBindings
      revision = requestedRevision
      // Capture this request's revision; a later message must not change its ACK.
      requestAnimationFrame(() => requestAnimationFrame(() => {
        result(requestId, 'applied', requestedRevision)
        busy = false
      }))
    } catch (error) {
      // A partial write cannot safely be rolled back in the presence of authored code.
      failed = true
      busy = false
      result(requestId, 'reload', revision, error instanceof Error ? error.message : 'update-exception')
    }
  })
}