one 2.10.0 → 2.11.0

package/src/dom/browserBridge.ts

@@ -0,0 +1,185 @@
+import { DOMPeer } from './peer'
+import { DOM_PROTOCOL_VERSION, parseBootstrap, type DOMMessage } from './protocol'
+import { DOMBridgeError, serializeError, type DOMState } from './serialize'
+import type { DOMImperativeHandle } from './types'
+
+/** native installs this shim before application script and queues transport writes until ready. */
+export type DOMTransport = {
+  bootstrap: unknown
+  postMessage: (raw: string) => void
+  subscribe: (listener: (raw: string) => void) => () => void
+}
+
+export class DOMBrowserBridge {
+  readonly bootstrap: ReturnType<typeof parseBootstrap>
+  private peer: DOMPeer
+  private current: DOMState
+  private callbacks = new Map<string, (...args: unknown[]) => Promise<unknown>>()
+  private methods: DOMImperativeHandle = Object.create(null)
+  private unsubscribe?: () => void
+  private live = true
+  private started = false
+  private handleRegistered = false
+
+  constructor(
+    entryId: string,
+    private transport: DOMTransport,
+    private render: (props: Record<string, unknown>) => void,
+    private onDispose: () => void,
+    private onFailure: (error: unknown) => void,
+    private development = false
+  ) {
+    this.bootstrap = parseBootstrap(transport.bootstrap, entryId)
+    this.current = this.bootstrap
+    this.peer = new DOMPeer(
+      this.bootstrap.epoch,
+      'browser',
+      (raw) => transport.postMessage(raw),
+      (name) => {
+        return Object.hasOwn(this.methods, name) ? this.methods[name] : undefined
+      },
+      (message) => this.receiveControl(message),
+      onFailure,
+      development
+    )
+  }
+
+  start() {
+    if (this.started || !this.live)
+      throw new DOMBridgeError('DOM browser mount already started or disposed')
+    this.started = true
+    this.unsubscribe = this.transport.subscribe((raw) => {
+      try {
+        this.peer.receive(raw)
+      } catch (error) {
+        try {
+          this.onFailure(error)
+        } finally {
+          this.dispose()
+        }
+      }
+    })
+    this.render(this.props())
+    this.post({ type: 'ready', revision: this.current.revision })
+  }
+
+  private props(): Record<string, unknown> {
+    const props = { ...this.current.props }
+    const available = new Set(this.current.actions)
+    for (const name of this.callbacks.keys()) {
+      if (!available.has(name)) this.callbacks.delete(name)
+    }
+    for (const name of available) {
+      let callback = this.callbacks.get(name)
+      if (!callback) {
+        callback = (...args) => {
+          if (!this.current.actions.includes(name)) {
+            return Promise.reject(
+              new DOMBridgeError(
+                `DOM action ${name} was removed`,
+                'DOM_METHOD_UNAVAILABLE'
+              )
+            )
+          }
+          return this.peer.call(name, args)
+        }
+        this.callbacks.set(name, callback)
+      }
+      Object.defineProperty(props, name, {
+        value: callback,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      })
+    }
+    return props
+  }
+
+  private receiveControl(message: DOMMessage) {
+    if (message.type === 'state') {
+      if (message.revision <= this.current.revision) return
+      this.current = message
+      this.render(this.props())
+    } else if (message.type === 'dispose') {
+      this.dispose(false)
+    } else {
+      throw new DOMBridgeError('Unexpected native DOM message')
+    }
+  }
+
+  private post(
+    message:
+      | { type: 'ready'; revision: number }
+      | { type: 'handle'; methods: string[] }
+      | { type: 'size'; width: number; height: number }
+      | { type: 'dispose' }
+  ) {
+    this.peer.post({
+      version: DOM_PROTOCOL_VERSION,
+      epoch: this.bootstrap.epoch,
+      ...message,
+    })
+  }
+
+  setHandle(methods: DOMImperativeHandle): () => void {
+    if (!this.live) throw new DOMBridgeError('DOM document is disposed', 'DOM_DISPOSED')
+    if (this.handleRegistered)
+      throw new DOMBridgeError(
+        'Only one DOM imperative handle is supported per component'
+      )
+    if (Object.hasOwn(methods, 'then'))
+      throw new DOMBridgeError('Imperative method name "then" is reserved')
+    this.methods = methods
+    this.handleRegistered = true
+    this.post({ type: 'handle', methods: Object.keys(methods).sort() })
+    return () => {
+      if (this.methods !== methods) return
+      this.methods = Object.create(null)
+      this.handleRegistered = false
+      if (this.live) this.post({ type: 'handle', methods: [] })
+    }
+  }
+
+  measure(width: number, height: number) {
+    if (this.live) this.post({ type: 'size', width, height })
+  }
+
+  reportError(error: unknown) {
+    if (this.live)
+      this.transport.postMessage(
+        JSON.stringify({
+          version: DOM_PROTOCOL_VERSION,
+          epoch: this.bootstrap.epoch,
+          type: 'error',
+          error: serializeError(error, this.development),
+        })
+      )
+  }
+
+  dispose(notify = true) {
+    if (!this.live) return
+    this.live = false
+    this.peer.dispose()
+    this.unsubscribe?.()
+    this.unsubscribe = undefined
+    this.methods = Object.create(null)
+    this.callbacks.clear()
+    try {
+      if (notify) {
+        try {
+          this.transport.postMessage(
+            JSON.stringify({
+              version: DOM_PROTOCOL_VERSION,
+              epoch: this.bootstrap.epoch,
+              type: 'dispose',
+            })
+          )
+        } catch (error) {
+          this.onFailure(error)
+        }
+      }
+    } finally {
+      this.onDispose()
+    }
+  }
+}

package/src/dom/client.tsx

@@ -0,0 +1,75 @@
+import { createElement, type ComponentType } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { DOMBrowserBridge, type DOMTransport } from './browserBridge'
+import { DOMBridgeContext } from './context'
+import { observeDOMSize } from './measure'
+import { DOMBridgeError } from './serialize'
+
+declare global {
+  var __oneDOM: DOMTransport | undefined
+}
+
+/** browser-only virtual entries call this once; inline web components use normal React. */
+export function mountDOMComponent(
+  Component: ComponentType<any>,
+  entryId: string
+): () => void {
+  const transport = globalThis.__oneDOM
+  if (
+    !transport ||
+    typeof transport.postMessage !== 'function' ||
+    typeof transport.subscribe !== 'function'
+  ) {
+    throw new DOMBridgeError(
+      'One DOM host transport was not installed before application script'
+    )
+  }
+  const container = document.getElementById('one-dom-root')
+  if (!container) throw new DOMBridgeError('One DOM entry requires #one-dom-root')
+  let stopMeasuring: (() => void) | undefined
+  let root: Root
+  const report = (error: unknown) => bridge.reportError(error)
+  const bridge = new DOMBrowserBridge(
+    entryId,
+    transport,
+    (props) => {
+      root.render(
+        createElement(
+          DOMBridgeContext.Provider,
+          { value: bridge },
+          createElement(Component, props)
+        )
+      )
+    },
+    () => {
+      stopMeasuring?.()
+      window.removeEventListener('pagehide', dispose)
+      window.removeEventListener('error', onError)
+      window.removeEventListener('unhandledrejection', onRejection)
+      root.unmount()
+    },
+    report,
+    import.meta.env.DEV
+  )
+  const dispose = () => bridge.dispose()
+  const onError = (event: ErrorEvent) => report(event.error || new Error(event.message))
+  const onRejection = (event: PromiseRejectionEvent) => report(event.reason)
+  root = createRoot(container, {
+    onUncaughtError: report,
+    onCaughtError: report,
+    onRecoverableError: report,
+  })
+  window.addEventListener('pagehide', dispose)
+  window.addEventListener('error', onError)
+  window.addEventListener('unhandledrejection', onRejection)
+  try {
+    bridge.start()
+    stopMeasuring = observeDOMSize(container, (width, height) =>
+      bridge.measure(width, height)
+    )
+  } catch (error) {
+    bridge.dispose()
+    throw error
+  }
+  return dispose
+}

package/src/dom/context.ts

@@ -0,0 +1,4 @@
+import { createContext } from 'react'
+import type { DOMBrowserBridge } from './browserBridge'
+
+export const DOMBridgeContext = createContext<DOMBrowserBridge | null>(null)

package/src/dom/host.native.tsx

@@ -0,0 +1,137 @@
+import {
+  forwardRef,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ComponentRef,
+} from 'react'
+import { getDevServer } from '../getDevServer.native'
+import OneDOMHost, { Commands } from '../platform/specs/OneDOMHostNativeComponent'
+import { DOMNativeBridge } from './nativeBridge'
+import { DOM_PROTOCOL_VERSION } from './protocol'
+import { DOMBridgeError, serializeError, serializeProps } from './serialize'
+import type { DOMProps } from './types'
+
+/** the native transform replaces only the default export with this host proxy. */
+export function createDOMComponent<
+  P extends object = Record<string, unknown>,
+  Handle extends object = Record<string, (...args: unknown[]) => Promise<unknown>>,
+>(entryId: string) {
+  const DOMComponent = forwardRef<Handle, P & { dom?: DOMProps }>((allProps, ref) => {
+    const { dom, ...props } = allProps
+    const host = useRef<ComponentRef<typeof OneDOMHost>>(null)
+    const options = useRef(dom)
+    const epoch = useRef<string | undefined>(undefined)
+    const mountGeneration = useRef(0)
+    const [handle, setHandle] = useState<Record<
+      string,
+      (...args: unknown[]) => Promise<unknown>
+    > | null>(null)
+    const [height, setHeight] = useState<number | undefined>(undefined)
+    const serialized = serializeProps(props)
+    const report = (error: unknown) => {
+      const detail = { entryId, epoch: epoch.current, ...serializeError(error, __DEV__) }
+      if (options.current?.onError) options.current.onError(detail)
+      else console.error('[one/dom]', detail)
+    }
+    const [bridge] = useState(
+      () =>
+        new DOMNativeBridge(
+          serialized,
+          (raw) => {
+            if (!host.current)
+              throw new DOMBridgeError('One DOM host is unmounted', 'DOM_DISPOSED')
+            Commands.post(host.current, raw)
+          },
+          (message) => {
+            if (message.type === 'document') {
+              epoch.current = message.epoch
+              setHandle(null)
+              setHeight(undefined)
+            } else if (message.type === 'handle') {
+              setHandle(
+                message.methods.length ? bridge.createHandle(message.methods) : null
+              )
+            } else if (message.type === 'size') {
+              setHeight((current) =>
+                current === message.height ? current : message.height
+              )
+            } else if (message.type === 'error') {
+              report(Object.assign(new Error(message.error.message), message.error))
+            }
+          },
+          report,
+          __DEV__
+        )
+    )
+    const prepared = bridge.prepare(serialized)
+    useLayoutEffect(() => {
+      options.current = dom
+      bridge.commit(prepared)
+    })
+    useLayoutEffect(() => {
+      const generation = ++mountGeneration.current
+      return () => {
+        // strict mode rehearses effect cleanup without replacing the host document.
+        queueMicrotask(() => {
+          if (mountGeneration.current === generation) bridge.dispose()
+        })
+      }
+    }, [bridge])
+    useImperativeHandle(ref, () => handle as Handle, [handle])
+    const guard = (callback: () => void) => {
+      try {
+        callback()
+      } catch (error) {
+        bridge.dispose()
+        report(error)
+      }
+    }
+    const developmentURL = __DEV__
+      ? new URL(`/_one/dom/${encodeURIComponent(entryId)}/`, getDevServer().url).href
+      : undefined
+    return (
+      <OneDOMHost
+        ref={host}
+        entryId={entryId}
+        developmentURL={developmentURL}
+        bootstrapState={JSON.stringify({
+          version: DOM_PROTOCOL_VERSION,
+          ...prepared.state,
+        })}
+        scrollEnabled={dom?.scrollEnabled ?? true}
+        style={[
+          dom?.style,
+          dom?.matchContents && height !== undefined ? { height } : undefined,
+        ]}
+        onDocumentStart={({ nativeEvent }) =>
+          guard(() => bridge.startDocument(nativeEvent.epoch, nativeEvent.revision))
+        }
+        onMessage={({ nativeEvent }) => guard(() => bridge.receive(nativeEvent.message))}
+        onLoad={({ nativeEvent }) => {
+          if (nativeEvent.epoch === epoch.current)
+            options.current?.onLoad?.({ entryId, epoch: nativeEvent.epoch })
+        }}
+        onError={({ nativeEvent }) => {
+          if (nativeEvent.epoch === epoch.current) {
+            bridge.dispose()
+            report(new DOMBridgeError(nativeEvent.message, nativeEvent.code))
+          }
+        }}
+        onProcessTerminated={({ nativeEvent }) => {
+          if (nativeEvent.epoch !== epoch.current) return
+          bridge.dispose()
+          report(
+            new DOMBridgeError(
+              'One DOM browser process terminated',
+              'DOM_PROCESS_TERMINATED'
+            )
+          )
+        }}
+      />
+    )
+  })
+  DOMComponent.displayName = `OneDOM(${entryId})`
+  return DOMComponent
+}

package/src/dom/index.ts

@@ -0,0 +1,109 @@
+import {
+  useContext,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useState,
+  type DependencyList,
+  type Ref,
+} from 'react'
+import { DOMBridgeContext } from './context'
+import {
+  deserializeError,
+  DOMBridgeError,
+  serializeData,
+  serializeError,
+} from './serialize'
+import type { DOMImperativeHandle, DOMValue } from './types'
+
+export type {
+  DOMProps,
+  DOMValue,
+  DOMError,
+  DOMErrorEvent,
+  DOMLoadEvent,
+  DOMImperativeHandle,
+  DOMAction,
+} from './types'
+
+/** expose async methods on both inline web components and hosted native components. */
+export function useDOMImperativeHandle<
+  T extends { [K in keyof T]: (...args: any[]) => Promise<DOMValue | void> },
+>(ref: Ref<T> | undefined, factory: () => T, deps: DependencyList) {
+  const bridge = useContext(DOMBridgeContext)
+  const [lifetime] = useState(() => ({
+    live: false,
+    methods: null as DOMImperativeHandle | null,
+    pending: new Set<(error: Error) => void>(),
+  }))
+  const binding = useMemo(() => {
+    const methods = factory()
+    const wrapped: DOMImperativeHandle = Object.create(null)
+    for (const name of Object.keys(methods)) {
+      if (
+        typeof (methods as DOMImperativeHandle)[name] !== 'function' ||
+        name === 'then'
+      ) {
+        throw new DOMBridgeError(`Invalid DOM imperative method ${name}`)
+      }
+      wrapped[name] = (...args) =>
+        new Promise((resolve, reject) => {
+          if (!lifetime.live)
+            throw new DOMBridgeError('DOM handle is disposed', 'DOM_DISPOSED')
+          const committed = lifetime.methods
+          if (!committed || !Object.hasOwn(committed, name)) {
+            throw new DOMBridgeError(
+              `DOM method ${name} is unavailable`,
+              'DOM_METHOD_UNAVAILABLE'
+            )
+          }
+          const method = committed[name]
+          const input = serializeData(args, 'arguments') as DOMValue[]
+          lifetime.pending.add(reject)
+          void Promise.resolve()
+            .then(() => {
+              if (!lifetime.live)
+                throw new DOMBridgeError('DOM handle is disposed', 'DOM_DISPOSED')
+              return method.apply(committed, input)
+            })
+            .then(
+              (result) => {
+                if (!lifetime.pending.delete(reject)) return
+                try {
+                  resolve(
+                    result === undefined ? undefined : serializeData(result, 'result')
+                  )
+                } catch (error) {
+                  reject(error)
+                }
+              },
+              (error) => {
+                if (lifetime.pending.delete(reject))
+                  reject(
+                    deserializeError(
+                      serializeError(error, process.env.NODE_ENV !== 'production')
+                    )
+                  )
+              }
+            )
+        })
+    }
+    return { wrapped: wrapped as T, methods: methods as DOMImperativeHandle }
+  }, deps)
+
+  useLayoutEffect(() => {
+    lifetime.live = true
+    return () => {
+      lifetime.live = false
+      lifetime.methods = null
+      for (const reject of lifetime.pending)
+        reject(new DOMBridgeError('DOM handle is disposed', 'DOM_DISPOSED'))
+      lifetime.pending.clear()
+    }
+  }, [bridge, lifetime])
+  useLayoutEffect(() => {
+    lifetime.methods = binding.methods
+    return bridge?.setHandle(binding.wrapped)
+  }, [bridge, binding, lifetime])
+  useImperativeHandle(ref, () => binding.wrapped, [binding])
+}

package/src/dom/measure.ts

@@ -0,0 +1,32 @@
+/** measure browser height at the native-constrained width, once per animation frame. */
+export function observeDOMSize(
+  root: HTMLElement,
+  report: (width: number, height: number) => void
+): () => void {
+  const view = root.ownerDocument.defaultView!
+  let frame: number | undefined
+  let previous = ''
+  const measure = () => {
+    frame = undefined
+    const bounds = root.getBoundingClientRect()
+    const width = Math.ceil(bounds.width)
+    const height = Math.ceil(Math.max(bounds.height, root.scrollHeight))
+    if (![width, height].every((value) => Number.isFinite(value) && value >= 0)) return
+    const next = `${width}:${height}`
+    if (previous === next) return
+    previous = next
+    report(width, height)
+  }
+  const schedule = () => {
+    if (frame === undefined) frame = view.requestAnimationFrame(measure)
+  }
+  const observer = new ResizeObserver(schedule)
+  observer.observe(root)
+  view.addEventListener('resize', schedule)
+  schedule()
+  return () => {
+    observer.disconnect()
+    view.removeEventListener('resize', schedule)
+    if (frame !== undefined) view.cancelAnimationFrame(frame)
+  }
+}

package/src/dom/nativeBridge.ts

@@ -0,0 +1,143 @@
+import { DOMPeer } from './peer'
+import { DOM_PROTOCOL_VERSION, type DOMMessage } from './protocol'
+import { DOMBridgeError, type DOMState, serializeProps } from './serialize'
+
+type Prepared = ReturnType<typeof serializeProps> & { state: DOMState }
+
+/** React commits state here; rendering a speculative update never replaces handlers. */
+export class DOMNativeBridge {
+  private sequence = 0
+  private committed: Prepared
+  private peer?: DOMPeer
+  private epoch?: string
+  private ready = false
+  private sentRevision = -1
+  private epochs = new Set<string>()
+
+  constructor(
+    initial: ReturnType<typeof serializeProps>,
+    private send: (raw: string) => void,
+    private notify: (message: DOMMessage | { type: 'document'; epoch?: string }) => void,
+    private onFailure: (error: unknown) => void,
+    private development = false
+  ) {
+    this.committed = {
+      ...initial,
+      actions: new Map(),
+      state: { revision: 0, props: initial.props, actions: [...initial.actions.keys()] },
+    }
+  }
+
+  prepare(serialized: ReturnType<typeof serializeProps>): Prepared {
+    const state =
+      serialized.key === this.committed.key
+        ? this.committed.state
+        : {
+            revision: ++this.sequence,
+            props: serialized.props,
+            actions: [...serialized.actions.keys()],
+          }
+    return { ...serialized, state }
+  }
+
+  commit(prepared: Prepared) {
+    this.committed = prepared
+    this.reconcile()
+  }
+
+  startDocument(epoch: string, revision: number) {
+    if (
+      !epoch ||
+      !Number.isSafeInteger(revision) ||
+      revision < 0 ||
+      revision > this.committed.state.revision
+    ) {
+      throw new DOMBridgeError('Invalid native document snapshot')
+    }
+    if (this.epochs.has(epoch))
+      throw new DOMBridgeError('A new document must have a fresh epoch')
+    this.epochs.add(epoch)
+    this.dispose()
+    this.epoch = epoch
+    this.sentRevision = revision
+    this.peer = new DOMPeer(
+      epoch,
+      'native',
+      this.send,
+      (name) => {
+        if (!this.ready)
+          throw new DOMBridgeError('DOM document is not ready', 'DOM_NOT_READY')
+        return this.committed.actions.get(name)
+      },
+      (message) => {
+        if (message.type === 'dispose') {
+          this.dispose()
+          return
+        } else if (message.type === 'ready') {
+          if (this.ready || message.revision !== revision)
+            throw new DOMBridgeError('Invalid DOM ready revision')
+          this.ready = true
+          this.reconcile()
+        } else if (
+          (!this.ready && message.type !== 'error') ||
+          message.type === 'state'
+        ) {
+          throw new DOMBridgeError('Unexpected browser DOM message')
+        }
+        this.notify(message)
+      },
+      this.onFailure,
+      this.development
+    )
+    this.notify({ type: 'document', epoch })
+  }
+
+  private reconcile() {
+    if (this.ready && this.peer && this.committed.state.revision > this.sentRevision) {
+      this.peer.post({
+        version: DOM_PROTOCOL_VERSION,
+        epoch: this.epoch!,
+        type: 'state',
+        ...this.committed.state,
+      })
+      this.sentRevision = this.committed.state.revision
+    }
+  }
+
+  receive(raw: string) {
+    try {
+      this.peer?.receive(raw)
+    } catch (error) {
+      this.dispose()
+      throw error
+    }
+  }
+
+  createHandle(
+    methods: string[]
+  ): Record<string, (...args: unknown[]) => Promise<unknown>> {
+    const peer = this.peer
+    const handle: Record<string, (...args: unknown[]) => Promise<unknown>> =
+      Object.create(null)
+    for (const method of methods) {
+      if (method === 'then')
+        throw new DOMBridgeError('Imperative method name "then" is reserved')
+      handle[method] = (...args) =>
+        peer && this.ready
+          ? peer.call(method, args)
+          : Promise.reject(
+              new DOMBridgeError('DOM document is not ready', 'DOM_NOT_READY')
+            )
+    }
+    return Object.freeze(handle)
+  }
+
+  dispose() {
+    this.peer?.dispose()
+    this.peer = undefined
+    this.epoch = undefined
+    this.ready = false
+    this.sentRevision = -1
+    this.notify({ type: 'document' })
+  }
+}