@vidact/runtime 0.2.0-beta.0 → 0.2.0-beta.10

package/src/metadata.ts

@@ -0,0 +1,212 @@
+import { registerCompiledCleanup } from './compiled/core.ts'
+import {
+  LINK_IDENTITY_PROPS,
+  META_IDENTITY_ATTRIBUTES,
+  META_IDENTITY_PROPS,
+} from './dom/attributes.ts'
+import { applyBaseDomProp, installDomPropHandler } from './dom/properties.ts'
+
+type MetadataEntry = {
+  readonly elements: Element[]
+  readonly baseline: number
+}
+
+type MetadataState = {
+  readonly entries: Map<string, MetadataEntry>
+  readonly stylePrecedence: string[]
+}
+
+type MetadataOwner = {
+  readonly element: Element
+  readonly state: MetadataState
+  entry: MetadataEntry
+  key: string
+}
+
+const metadataByDocument = new WeakMap<Document, MetadataState>()
+const metadataOwners = new WeakMap<Element, MetadataOwner>()
+let propRekeyingInstalled = false
+
+export function installFrameworkMetadataPropRekeying(): void {
+  if (propRekeyingInstalled) return
+  propRekeyingInstalled = true
+  installDomPropHandler((element, name, value) => {
+    const owner = metadataOwners.get(element)
+    if (owner === undefined || !isMetadataIdentityProp(element.localName, name)) return false
+    detachMetadataOwner(owner)
+    applyBaseDomProp(element, name, value)
+    if (name === 'precedence') {
+      element.setAttribute('data-precedence', String(value ?? 'default'))
+      element.removeAttribute('precedence')
+    }
+    attachMetadataOwner(owner)
+    return true
+  })
+}
+
+export function isFrameworkMetadataElement(
+  element: Element,
+  props: Readonly<Record<string, unknown>> | null = null,
+): boolean {
+  const name = element.localName
+  if (
+    (name === 'title' || name === 'meta' || name === 'link') &&
+    element.hasAttribute('itemprop')
+  ) {
+    return false
+  }
+  if (name === 'title' || name === 'meta') return true
+  if (name === 'link') {
+    if (
+      props !== null &&
+      ['onLoad', 'onError', 'disabled'].some((key) => Object.hasOwn(props, key))
+    ) {
+      return false
+    }
+    return element.getAttribute('rel') !== 'stylesheet' || element.hasAttribute('precedence')
+  }
+  if (name === 'style') return element.hasAttribute('href') && element.hasAttribute('precedence')
+  return name === 'script' && element.hasAttribute('async') && element.hasAttribute('src')
+}
+
+export function hoistFrameworkMetadata(element: Element): DocumentFragment {
+  const document = element.ownerDocument
+  const state = metadataState(document)
+  const key = metadataKey(element)
+  const owner: MetadataOwner = {
+    element,
+    state,
+    key,
+    entry: metadataEntry(document, state, key),
+  }
+  attachMetadataOwner(owner)
+  metadataOwners.set(element, owner)
+  element.removeAttribute('precedence')
+  registerCompiledCleanup(() => {
+    detachMetadataOwner(owner)
+    metadataOwners.delete(element)
+  })
+  return document.createDocumentFragment()
+}
+
+function metadataState(document: Document): MetadataState {
+  let state = metadataByDocument.get(document)
+  if (state !== undefined) return state
+  state = {
+    entries: new Map(),
+    stylePrecedence: [...document.head.children]
+      .filter((candidate) => metadataTier(candidate) === 2)
+      .map(stylePrecedence)
+      .filter((value, index, values) => values.indexOf(value) === index),
+  }
+  metadataByDocument.set(document, state)
+  return state
+}
+
+function metadataEntry(document: Document, state: MetadataState, key: string): MetadataEntry {
+  let entry = state.entries.get(key)
+  if (entry !== undefined) return entry
+  const existing = [...document.head.children].find(
+    (candidate) => isFrameworkMetadataElement(candidate) && metadataKey(candidate) === key,
+  )
+  entry = {
+    elements: existing === undefined ? [] : [existing],
+    baseline: existing === undefined ? 0 : 1,
+  }
+  state.entries.set(key, entry)
+  return entry
+}
+
+function attachMetadataOwner(owner: MetadataOwner): void {
+  const document = owner.element.ownerDocument
+  owner.key = metadataKey(owner.element)
+  owner.entry = metadataEntry(document, owner.state, owner.key)
+  owner.entry.elements.at(-1)?.remove()
+  owner.entry.elements.push(owner.element)
+  insertByPrecedence(document.head, owner.element, owner.state)
+}
+
+function detachMetadataOwner(owner: MetadataOwner): void {
+  const { element, entry, key, state } = owner
+  const index = entry.elements.indexOf(element)
+  if (index === -1) return
+  const visible = index === entry.elements.length - 1
+  entry.elements.splice(index, 1)
+  element.remove()
+  if (entry.elements.length === entry.baseline) {
+    if (visible && entry.elements.length !== 0) {
+      element.ownerDocument.head.append(entry.elements.at(-1)!)
+    }
+    if (state.entries.get(key) === entry) state.entries.delete(key)
+  } else if (visible) {
+    insertByPrecedence(element.ownerDocument.head, entry.elements.at(-1)!, state)
+  }
+}
+
+function isMetadataIdentityProp(elementName: string, propName: string): boolean {
+  if (propName === 'precedence') return elementName === 'link' || elementName === 'style'
+  if (elementName === 'meta') {
+    return (META_IDENTITY_PROPS as readonly string[]).includes(propName)
+  }
+  if (elementName === 'link') return (LINK_IDENTITY_PROPS as readonly string[]).includes(propName)
+  if (elementName === 'script') return propName === 'src'
+  return false
+}
+
+function metadataKey(element: Element): string {
+  const name = element.localName
+  if (name === 'title') return 'title'
+  if (name === 'meta') {
+    for (const attribute of META_IDENTITY_ATTRIBUTES) {
+      if (element.hasAttribute(attribute))
+        return `meta:${attribute}:${element.getAttribute(attribute)}`
+    }
+  }
+  if (name === 'link') {
+    return `link:${element.getAttribute('rel') ?? ''}:${element.getAttribute('href') ?? ''}:${element.getAttribute('as') ?? ''}`
+  }
+  if (name === 'style') return `style:${element.getAttribute('href') ?? ''}`
+  return `script:${element.getAttribute('src') ?? ''}`
+}
+
+function insertByPrecedence(head: HTMLHeadElement, element: Element, state: MetadataState): void {
+  const tier = metadataTier(element) ?? 1
+  const precedence = stylePrecedence(element)
+  if (tier === 2) {
+    if (!state.stylePrecedence.includes(precedence)) state.stylePrecedence.push(precedence)
+    element.setAttribute('data-precedence', precedence)
+  }
+  const before = [...head.children].find((candidate) => {
+    const candidateTier = metadataTier(candidate)
+    if (candidateTier === undefined) return false
+    if (candidateTier !== tier) return candidateTier > tier
+    return (
+      tier === 2 &&
+      state.stylePrecedence.indexOf(stylePrecedence(candidate)) >
+        state.stylePrecedence.indexOf(precedence)
+    )
+  })
+  head.insertBefore(element, before ?? null)
+}
+
+function metadataTier(element: Element): number | undefined {
+  const name = element.localName
+  if (name === 'style') return element.hasAttribute('data-precedence') ? 2 : undefined
+  if (name === 'script') return element.hasAttribute('src') ? 3 : undefined
+  if (name === 'link') {
+    const relation = element.getAttribute('rel')
+    if (relation === 'stylesheet') {
+      return element.hasAttribute('precedence') || element.hasAttribute('data-precedence')
+        ? 2
+        : undefined
+    }
+    if (['preconnect', 'dns-prefetch', 'preload', 'modulepreload'].includes(relation ?? ''))
+      return 0
+    return 1
+  }
+  return name === 'title' || name === 'meta' ? 1 : undefined
+}
+
+function stylePrecedence(element: Element): string {
+  return element.getAttribute('precedence') ?? element.getAttribute('data-precedence') ?? 'default'
+}

package/src/nested-prop.ts

@@ -0,0 +1,27 @@
+import { binding, isCompiledBinding } from './compiled/core.ts'
+
+const DEV = typeof __VIDACT_DEV__ === 'undefined' || __VIDACT_DEV__
+
+type ContainerFallback = (() => unknown) | null
+
+export function nestedProp(
+  input: unknown,
+  path: readonly string[],
+  containerFallbacks: readonly ContainerFallback[],
+): unknown {
+  const read = (): unknown => {
+    let value = isCompiledBinding(input) ? input[1]() : input
+    for (const [index, name] of path.entries()) {
+      if (value === undefined) value = containerFallbacks[index]?.()
+      if (value === null || value === undefined) {
+        throw new TypeError(
+          DEV ? `cannot destructure nested prop ${name} from a nullish value` : 'V015',
+        )
+      }
+      value = (value as Record<string, unknown>)[name]
+    }
+    return value
+  }
+
+  return isCompiledBinding(input) ? binding(input[2], input[3], read, input[4], input[5]) : read()
+}

package/src/profiling.ts

@@ -0,0 +1,43 @@
+import {
+  captureCompiledOwnerStack,
+  enableProfiling,
+  profiled,
+  recordCompiledDebugValue,
+} from './compiled/core.ts'
+import type {
+  CompiledBinding,
+  CompiledRenderValue,
+  ProfilerOnRender,
+  StructuralBinding,
+} from './compiled/types.ts'
+
+export interface ProfilerProps {
+  readonly children?: (() => CompiledRenderValue) | readonly [() => CompiledRenderValue]
+  readonly id: string | CompiledBinding<string>
+  readonly onRender: ProfilerOnRender | CompiledBinding<ProfilerOnRender>
+}
+
+export function Profiler(props: ProfilerProps): StructuralBinding {
+  const render = Array.isArray(props.children) ? props.children[0] : props.children
+  if (typeof render !== 'function') {
+    throw new TypeError('Profiler children must be a compiler-generated render function')
+  }
+  enableProfiling()
+  return profiled(props.id, props.onRender, render)
+}
+
+export function useDebugValue<Value>(
+  value: Value | CompiledBinding<Value>,
+  format?: (value: Value) => unknown,
+): void {
+  if (format !== undefined && typeof format !== 'function') {
+    throw new TypeError('useDebugValue formatter must be a function')
+  }
+  enableProfiling()
+  recordCompiledDebugValue(value, format)
+}
+
+export function captureOwnerStack(): string | null {
+  enableProfiling()
+  return captureCompiledOwnerStack()
+}

package/src/protocol.ts

@@ -0,0 +1,8 @@
+export const VIDACT_RUNTIME_PROTOCOL = 'vidact-runtime-v2'
+
+export function assertRuntimeProtocol(expected: string): void {
+  if (expected === VIDACT_RUNTIME_PROTOCOL) return
+  throw new Error(
+    `Vidact compiler/runtime protocol mismatch: compiled for ${expected}, runtime provides ${VIDACT_RUNTIME_PROTOCOL}`,
+  )
+}

package/src/raw-html.ts

@@ -0,0 +1,206 @@
+import {
+  isCompiledBinding,
+  mountCompiledPropTransition,
+  type CompiledPropTransition,
+} from './compiled/core.ts'
+import { HYDRATION_PREFIX, HydrationMismatch, isHydrating } from './hydration-bridge.ts'
+
+const RAW_HTML_PUBLICATION_PRIORITY = 100
+const rawHtmlHosts = new WeakSet<HTMLElement>()
+const DEV = typeof __VIDACT_DEV__ === 'undefined' || __VIDACT_DEV__
+
+export function mountRawHtmlProp(
+  element: HTMLElement,
+  value: unknown,
+  children: readonly unknown[],
+): void {
+  if (value === null || value === undefined) return
+  if (isCompiledBinding(value)) {
+    mountCompiledPropTransition(
+      value,
+      (initial) => mountRawHtml(element, initial, children),
+      (next, previous) => prepareRawHtml(element, next, previous, children),
+    )
+    return
+  }
+  mountRawHtml(element, value, children)
+}
+
+function mountRawHtml(element: HTMLElement, value: unknown, children: readonly unknown[]): void {
+  const html = readRawHtml(element, value, children)
+  if (html === null || html === undefined) return
+  const container = rawHtmlContainer(element)
+  const staged = parseRawHtml(element, html)
+  if (isHydrating()) {
+    if (!hasEqualHydrationRawChildren(container, staged)) {
+      throw new HydrationMismatch('server raw HTML does not match the client value')
+    }
+  } else {
+    container.replaceChildren(adoptRawHtml(element, staged))
+  }
+  rawHtmlHosts.add(element)
+}
+
+function hasEqualHydrationRawChildren(container: Node, expected: DocumentFragment): boolean {
+  const start = container.firstChild
+  const end = container.lastChild
+  if (
+    !(start instanceof Comment) ||
+    start.data !== `${HYDRATION_PREFIX}:h` ||
+    !(end instanceof Comment) ||
+    end.data !== `/${HYDRATION_PREFIX}:h`
+  ) {
+    return false
+  }
+  const actual: Node[] = []
+  for (let node = start.nextSibling; node !== null && node !== end; node = node.nextSibling) {
+    actual.push(node)
+  }
+  if (actual.length !== expected.childNodes.length) return false
+  for (let index = 0; index < actual.length; index += 1) {
+    if (!actual[index]?.isEqualNode(expected.childNodes[index] ?? null)) return false
+  }
+  return true
+}
+
+function prepareRawHtml(
+  element: HTMLElement,
+  nextValue: unknown,
+  previousValue: unknown,
+  children: readonly unknown[],
+): CompiledPropTransition | undefined {
+  const nextHtml = readRawHtml(element, nextValue, children)
+  const previousHtml = readRawHtml(element, previousValue, children)
+  if (nextHtml === null || nextHtml === undefined || nextHtml === previousHtml) return undefined
+
+  const staged = parseRawHtml(element, nextHtml)
+  const container = rawHtmlContainer(element)
+  const wasRawHtmlHost = rawHtmlHosts.has(element)
+  let previousNodes: Node[] | undefined
+  return [
+    () => {
+      // A reactive script `type` prop commits before the raw subtree.
+      assertExecutableRawHtmlTarget(element)
+      const adopted = adoptRawHtml(element, staged)
+      previousNodes = [...container.childNodes]
+      container.replaceChildren(adopted)
+      rawHtmlHosts.add(element)
+    },
+    () => {
+      if (previousNodes === undefined) return
+      container.replaceChildren(...previousNodes)
+      if (!wasRawHtmlHost) rawHtmlHosts.delete(element)
+      previousNodes = undefined
+    },
+    undefined,
+    undefined,
+    RAW_HTML_PUBLICATION_PRIORITY,
+  ]
+}
+
+export function validateRawHtmlRelatedProp(element: HTMLElement, name: string): void {
+  if (name === 'type' && rawHtmlHosts.has(element)) assertExecutableRawHtmlTarget(element)
+}
+
+function readRawHtml(element: HTMLElement, value: unknown, children: readonly unknown[]): unknown {
+  if (value === null || value === undefined) return undefined
+  assertRawHtmlPropTarget(element)
+  if (typeof value !== 'object' || !('__html' in value)) {
+    throw new Error(
+      DEV
+        ? '`props.dangerouslySetInnerHTML` must be in the form `{__html: ...}`. Please visit https://react.dev/link/dangerously-set-inner-html for more information.'
+        : 'V601',
+    )
+  }
+  const html = value['__html']
+  if (html === null || html === undefined) return html
+  if (children.some((child) => child !== null && child !== undefined)) {
+    throw new Error(
+      DEV ? 'Can only set one of `children` or `props.dangerouslySetInnerHTML`.' : 'V602',
+    )
+  }
+  assertExecutableRawHtmlTarget(element)
+  return html
+}
+
+function assertRawHtmlPropTarget(element: HTMLElement): void {
+  const tag = element.localName
+  if (isVoidHtmlElement(tag)) {
+    throw new Error(
+      DEV
+        ? `${tag} is a void element tag and must neither have \`children\` nor use \`dangerouslySetInnerHTML\`.`
+        : 'V603',
+    )
+  }
+  if (tag === 'textarea') {
+    throw new Error(DEV ? '`dangerouslySetInnerHTML` does not make sense on <textarea>.' : 'V604')
+  }
+}
+
+function assertExecutableRawHtmlTarget(element: HTMLElement): void {
+  const tag = element.localName
+  if (tag === 'script' && isExecutableScript(element as HTMLScriptElement)) {
+    throw new Error(
+      DEV
+        ? 'dangerouslySetInnerHTML on an executable <script> is unsupported because direct-created scripts execute when connected; use a non-executable data MIME type'
+        : 'V605',
+    )
+  }
+}
+
+function isVoidHtmlElement(tag: string): boolean {
+  return (
+    tag === 'area' ||
+    tag === 'base' ||
+    tag === 'br' ||
+    tag === 'col' ||
+    tag === 'embed' ||
+    tag === 'hr' ||
+    tag === 'img' ||
+    tag === 'input' ||
+    tag === 'keygen' ||
+    tag === 'link' ||
+    tag === 'menuitem' ||
+    tag === 'meta' ||
+    tag === 'param' ||
+    tag === 'source' ||
+    tag === 'track' ||
+    tag === 'wbr'
+  )
+}
+
+function isExecutableScript(element: HTMLScriptElement): boolean {
+  const type = element.type.trim().toLowerCase().split(';', 1)[0] ?? ''
+  if (type === '' || type === 'module' || type === 'importmap' || type === 'speculationrules') {
+    return true
+  }
+  return (
+    /^(?:application|text)\/(?:x-)?(?:java|ecma)script(?:1\.[0-5])?$/.test(type) ||
+    type === 'text/jscript' ||
+    type === 'text/livescript'
+  )
+}
+
+function parseRawHtml(element: HTMLElement, html: unknown): DocumentFragment {
+  const stagingDocument = element.ownerDocument.implementation.createHTMLDocument()
+  const staging =
+    element.localName === 'noscript'
+      ? (element.cloneNode(false) as HTMLElement)
+      : stagingDocument.createElement(element.localName.includes('-') ? 'div' : element.localName)
+  Reflect.set(staging, 'innerHTML', html)
+  const fragment = staging.ownerDocument.createDocumentFragment()
+  fragment.append(...rawHtmlContainer(staging).childNodes)
+  return fragment
+}
+
+function rawHtmlContainer(element: HTMLElement): HTMLElement | DocumentFragment {
+  return element instanceof HTMLTemplateElement ? element.content : element
+}
+
+function adoptRawHtml(element: HTMLElement, staged: DocumentFragment): DocumentFragment {
+  if (staged.ownerDocument === element.ownerDocument) return staged
+  const adopted = element.ownerDocument.createDocumentFragment()
+  adopted.append(...staged.childNodes)
+  element.ownerDocument.defaultView?.customElements.upgrade(adopted)
+  return adopted
+}

package/src/ref.ts

@@ -0,0 +1,13 @@
+export interface MutableRef<T> {
+  current: T
+}
+
+/** Creates the plain ref object used by dependency initialization outside component hooks. */
+export function createRef<T>(): MutableRef<T | null> {
+  return { current: null }
+}
+
+/** Creates the stable ref cell captured by a component's one-time execution. */
+export function useRef<T>(initialValue: T): MutableRef<T> {
+  return { current: initialValue }
+}

package/src/renderable-protocol.ts

@@ -0,0 +1,63 @@
+export const RENDERABLE = Symbol.for('vidact.v1.Renderable')
+
+export interface RenderableProtocol {
+  readonly [RENDERABLE]: {
+    readonly identity: unknown
+    readonly input: unknown
+    readonly reconcile: boolean
+    readonly construct: (input: never) => unknown
+  }
+}
+
+/**
+ * Cloning a renderable pulls in the element-construction module, which most
+ * compiled apps never touch. The renderable module registers its clone the
+ * first time an element capability is created, so `jsx` can reach it without
+ * importing it, and bundles that never build elements leave it out.
+ */
+export type RenderableClone = (
+  value: RenderableProtocol,
+  overrides: Record<string, unknown>,
+) => unknown
+
+let renderableClone: RenderableClone | undefined
+
+export function installRenderableClone(clone: RenderableClone): void {
+  renderableClone = clone
+}
+
+export function renderableCloneHandler(): RenderableClone | undefined {
+  return renderableClone
+}
+
+export function isRenderableProtocol(value: unknown): value is RenderableProtocol {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.hasOwn(value, RENDERABLE) &&
+    typeof (value as RenderableProtocol)[RENDERABLE]?.construct === 'function'
+  )
+}
+
+export function materializeRenderable(value: RenderableProtocol): unknown {
+  const internals = value[RENDERABLE]
+  return internals.construct(internals.input as never)
+}
+
+export function materializeRenderableWithInput(value: RenderableProtocol, input: unknown): unknown {
+  return value[RENDERABLE].construct(input as never)
+}
+
+export function renderableIdentity(value: RenderableProtocol): unknown {
+  return value[RENDERABLE].identity
+}
+
+export function canReconcileRenderable(value: RenderableProtocol): boolean {
+  return value[RENDERABLE].reconcile
+}
+
+export function renderablePropsSnapshot(value: RenderableProtocol): Record<PropertyKey, unknown> {
+  const props = (value as RenderableProtocol & { readonly props: Record<PropertyKey, unknown> })
+    .props
+  return Object.fromEntries(Reflect.ownKeys(props).map((name) => [name, Reflect.get(props, name)]))
+}