@ccheever/exact-renderer 0.1.0

package/src/protocol/encoder.ts

@@ -0,0 +1,940 @@
+// @system @ref LLP 0003 — Renderer-to-kernel protocol encoding
+/**
+ * Protocol encoding helpers.
+ *
+ * This module keeps canonical-style and transition conversion near the
+ * BufferWriter without introducing a second encoder abstraction.
+ */
+
+import {
+  BufferWriter,
+  type Dimension,
+  type StyleProps,
+  type TransitionProps,
+} from '@exact/core/protocol/buffer-writer';
+import {
+  EventType,
+  NodeType,
+  PropId,
+  TransitionEasingId,
+  TransitionKindId,
+  TransitionPropertyId,
+} from '@exact/core/protocol/opcodes';
+import {
+  getWindowViewportForRoot,
+} from '@exact/core/window-state';
+import { recordProtocolFrame } from '@exact/core/agent';
+import type {
+  CanonicalStyle,
+  CanonicalProps,
+  CanonicalTransitionMap,
+  CanonicalTransitionConfig,
+  DimensionValue,
+  SelectableMode,
+} from '../types.js';
+import type { ElementNode, TextNode, RootNode } from '../nodes/node.js';
+import { getChildIds, NodeKind } from '../nodes/node.js';
+import { getTagConfig, defaultTagConfig } from '../tags/index.js';
+
+/**
+ * Development mode flag - gate verbose logging.
+ */
+const __DEV__ = process.env.NODE_ENV !== 'production';
+
+const STRING_PROP_ENCODINGS = [
+  ['imageSource', PropId.ImageSource],
+  ['svgSource', PropId.SvgSource],
+  ['svgColors', PropId.SvgColors],
+  ['svgPixelDensity', PropId.SvgPixelDensity],
+  ['svgObjectPosition', PropId.SvgObjectPosition],
+  ['videoPlayerId', PropId.VideoPlayerId],
+  ['videoViewConfig', PropId.VideoViewConfig],
+  ['selectionCopyText', PropId.SelectionCopyText],
+  ['nativeViewModuleName', PropId.NativeViewModuleName],
+  ['nativeViewProps', PropId.NativeViewProps],
+  ['nativeViewSelectionTier', PropId.NativeViewSelectionTier],
+  ['nativeViewGesturePolicy', PropId.NativeViewGesturePolicy],
+  ['placeholder', PropId.Placeholder],
+  ['accessibilityLabel', PropId.AccessibilityLabel],
+  ['tintColor', PropId.TintColor],
+  ['href', PropId.Href],
+] as const satisfies readonly (readonly [keyof CanonicalProps, PropId])[];
+
+const SCALAR_PROP_ENCODINGS = [
+  ['focusScope', PropId.FocusScope],
+  ['inert', PropId.Inert],
+  ['scrollLocked', PropId.ScrollLocked],
+  ['portalTarget', PropId.PortalTarget],
+  ['accessibilityRole', PropId.AccessibilityRole],
+  ['accessibilityHint', PropId.AccessibilityHint],
+  ['accessibilityModal', PropId.AccessibilityModal],
+  ['accessibilityExpanded', PropId.AccessibilityExpanded],
+  ['accessibilitySelected', PropId.AccessibilitySelected],
+  ['accessibilityChecked', PropId.AccessibilityChecked],
+  ['accessibilityDisabled', PropId.AccessibilityDisabled],
+  ['accessibilityLive', PropId.AccessibilityLive],
+  ['accessibilityValueNow', PropId.AccessibilityValueNow],
+  ['accessibilityValueMin', PropId.AccessibilityValueMin],
+  ['accessibilityValueMax', PropId.AccessibilityValueMax],
+  ['accessibilityValueText', PropId.AccessibilityValueText],
+  ['focusable', PropId.Focusable],
+  ['testId', PropId.TestId],
+  ['nativeID', PropId.NativeID],
+  ['accessibilityLabelledBy', PropId.AccessibilityLabelledBy],
+  ['accessibilityDescribedBy', PropId.AccessibilityDescribedBy],
+  ['accessibilityBusy', PropId.AccessibilityBusy],
+  ['accessibilityActions', PropId.AccessibilityActions],
+  ['accessibilityElementsHidden', PropId.AccessibilityElementsHidden],
+  ['accessibilityOrder', PropId.AccessibilityOrder],
+  ['tabIndex', PropId.TabIndex],
+  ['allowFontScaling', PropId.AllowFontScaling],
+  ['maxFontSizeMultiplier', PropId.MaxFontSizeMultiplier],
+  ['minimumFontSize', PropId.MinimumFontSize],
+  ['accessibilitySynthetic', PropId.AccessibilitySynthetic],
+  ['accessibilityHeadingLevel', PropId.AccessibilityHeadingLevel],
+  ['toggleValue', PropId.ToggleValue],
+  ['glassEffect', PropId.GlassEffect],
+  ['disabled', PropId.Disabled],
+  ['showsScrollIndicator', PropId.ShowsScrollIndicator],
+  ['selectionStart', PropId.SelectionStart],
+  ['selectionEnd', PropId.SelectionEnd],
+] as const satisfies readonly (readonly [keyof CanonicalProps, PropId])[];
+
+type CanonicalDimensionStyleKey = Extract<keyof CanonicalStyle,
+  | 'width'
+  | 'height'
+  | 'minWidth'
+  | 'minHeight'
+  | 'maxWidth'
+  | 'maxHeight'
+  | 'paddingTop'
+  | 'paddingRight'
+  | 'paddingBottom'
+  | 'paddingLeft'
+  | 'marginTop'
+  | 'marginRight'
+  | 'marginBottom'
+  | 'marginLeft'
+  | 'flexBasis'
+  | 'top'
+  | 'right'
+  | 'bottom'
+  | 'left'
+>;
+
+const STYLE_DIMENSION_ENCODINGS = [
+  'width',
+  'height',
+  'minWidth',
+  'minHeight',
+  'maxWidth',
+  'maxHeight',
+  'paddingTop',
+  'paddingRight',
+  'paddingBottom',
+  'paddingLeft',
+  'marginTop',
+  'marginRight',
+  'marginBottom',
+  'marginLeft',
+  'flexBasis',
+  'top',
+  'right',
+  'bottom',
+  'left',
+] as const satisfies readonly CanonicalDimensionStyleKey[];
+
+const STYLE_DIRECT_ENCODINGS = [
+  'flexDirection',
+  'flexWrap',
+  'justifyContent',
+  'alignItems',
+  'alignSelf',
+  'flexGrow',
+  'flexShrink',
+  'rowGap',
+  'columnGap',
+  'positionType',
+  'zIndex',
+  'transformX',
+  'transformY',
+  'transformScale',
+  'transformRotate',
+  'display',
+  'backgroundColor',
+  'opacity',
+  'borderRadius',
+  'borderTopLeftRadius',
+  'borderTopRightRadius',
+  'borderBottomLeftRadius',
+  'borderBottomRightRadius',
+  'borderWidth',
+  'borderColor',
+  'borderTopWidth',
+  'borderRightWidth',
+  'borderBottomWidth',
+  'borderLeftWidth',
+  'borderTopColor',
+  'borderRightColor',
+  'borderBottomColor',
+  'borderLeftColor',
+  'shadowColor',
+  'shadowOffsetX',
+  'shadowOffsetY',
+  'shadowRadius',
+  'shadowOpacity',
+  'backdropBlur',
+  'overflow',
+  'aspectRatio',
+  'resizeMode',
+  'fontFamily',
+  'fontSize',
+  'textColor',
+  'direction',
+  'writingMode',
+  'fontWeight',
+  'fontStyle',
+  'lineHeight',
+  'letterSpacing',
+  'textDecorationLine',
+  'numberOfLines',
+  'ellipsizeMode',
+] as const satisfies readonly (keyof CanonicalStyle & keyof StyleProps)[];
+
+function hasOwnEnumerableProperties(value: object): boolean {
+  for (const key in value) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Declare the global exact object provided by the native runtime.
+ */
+declare const exact: {
+  dispatch: (buffer: Uint8Array) => void;
+  dispatchWithDebugContext?: (buffer: Uint8Array, debugContextJSON: string) => void;
+  __resizeTraceContext?: unknown;
+  screenWidth?: number;
+  screenHeight?: number;
+};
+
+/**
+ * Convert a DimensionValue to the protocol Dimension format.
+ */
+function toProtocolDimension(dim: DimensionValue): Dimension {
+  switch (dim.type) {
+    case 'auto':
+      return { type: 'auto' };
+    case 'points':
+      return { type: 'points', value: dim.value };
+    case 'percent':
+      return { type: 'percent', value: dim.value };
+  }
+}
+
+/**
+ * Convert CanonicalStyle to StyleProps for the BufferWriter.
+ */
+function canonicalStyleToProtocol(style: CanonicalStyle): StyleProps {
+  const props: StyleProps = {};
+  const protocolProps = props as Record<string, unknown>;
+
+  for (const key of STYLE_DIMENSION_ENCODINGS) {
+    const value = style[key];
+    if (value !== undefined) {
+      protocolProps[key] = toProtocolDimension(value);
+    }
+  }
+
+  for (const key of STYLE_DIRECT_ENCODINGS) {
+    const value = style[key];
+    if (value !== undefined) {
+      protocolProps[key] = value;
+    }
+  }
+
+  if (style.fontVariantNumeric !== undefined && style.fontVariantNumeric !== 0) {
+    props.fontVariantNumeric = style.fontVariantNumeric;
+  }
+  if (style.textAlign !== undefined && style.textAlign !== 'auto') {
+    props.textAlign = style.textAlign;
+  }
+
+  return props;
+}
+
+function transitionPropertyToProtocol(property: keyof CanonicalTransitionMap): TransitionPropertyId {
+  switch (property) {
+    case 'opacity':
+      return TransitionPropertyId.Opacity;
+    case 'transform':
+      return TransitionPropertyId.Transform;
+    case 'backgroundColor':
+      return TransitionPropertyId.BackgroundColor;
+    case 'borderRadius':
+      return TransitionPropertyId.BorderRadius;
+  }
+}
+
+function transitionEasingToProtocol(config: CanonicalTransitionConfig): {
+  easingType: TransitionEasingId;
+  params: [number, number, number, number];
+} {
+  if (config.type !== 'timing') {
+    return {
+      easingType: TransitionEasingId.EaseInOut,
+      params: [config.damping, config.stiffness, config.mass, config.velocity],
+    };
+  }
+
+  if (typeof config.easing === 'string') {
+    switch (config.easing) {
+      case 'linear':
+        return { easingType: TransitionEasingId.Linear, params: [0, 0, 0, 0] };
+      case 'easeIn':
+        return { easingType: TransitionEasingId.EaseIn, params: [0, 0, 0, 0] };
+      case 'easeOut':
+        return { easingType: TransitionEasingId.EaseOut, params: [0, 0, 0, 0] };
+      case 'easeInOut':
+      default:
+        return { easingType: TransitionEasingId.EaseInOut, params: [0, 0, 0, 0] };
+    }
+  }
+
+  return {
+    easingType: TransitionEasingId.CubicBezier,
+    params: [config.easing[0], config.easing[1], config.easing[2], config.easing[3]],
+  };
+}
+
+function canonicalTransitionsToProtocol(transitions: CanonicalTransitionMap): TransitionProps[] {
+  const entries: TransitionProps[] = [];
+
+  for (const [property, config] of Object.entries(transitions) as Array<[keyof CanonicalTransitionMap, CanonicalTransitionConfig]>) {
+    if (config.type === 'timing') {
+      const { easingType, params } = transitionEasingToProtocol(config);
+      entries.push({
+        propertyId: transitionPropertyToProtocol(property),
+        kind: TransitionKindId.Timing,
+        durationMs: config.duration,
+        delayMs: config.delay,
+        respectsReducedMotion: config.respectsReducedMotion,
+        easingType,
+        params,
+      });
+      continue;
+    }
+
+    entries.push({
+      propertyId: transitionPropertyToProtocol(property),
+      kind: TransitionKindId.Spring,
+      durationMs: config.duration,
+      delayMs: config.delay,
+      respectsReducedMotion: config.respectsReducedMotion,
+      easingType: TransitionEasingId.EaseInOut,
+      params: [config.damping, config.stiffness, config.mass, config.velocity],
+    });
+  }
+
+  return entries;
+}
+
+export type ProtocolEncoder = BufferWriter;
+
+/**
+ * Create a protocol encoder backed directly by BufferWriter.
+ */
+export function createProtocolEncoder(
+  capacity: number = 1024 * 1024,
+  rootId: number = 0
+): ProtocolEncoder {
+  return new BufferWriter(capacity, 1, rootId);
+}
+
+/**
+ * Encode a SetStyle operation from canonical style.
+ */
+export function setStyle(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  style: CanonicalStyle
+): void {
+  const props = canonicalStyleToProtocol(style);
+  if (hasOwnEnumerableProperties(props)) {
+    encoder.setStyle(nodeId, props);
+  }
+}
+
+export function setTransform(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  transformX: number,
+  transformY: number,
+  transformScale: number,
+  transformRotate: number,
+): void {
+  encoder.setTransform(nodeId, transformX, transformY, transformScale, transformRotate);
+}
+
+export function setOpacity(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  opacity: number,
+): void {
+  encoder.setOpacity(nodeId, opacity);
+}
+
+export function setBackgroundColor(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  color: NonNullable<CanonicalStyle['backgroundColor']>,
+): void {
+  encoder.setBackgroundColor(nodeId, color);
+}
+
+/**
+ * Encode a SetTransition operation from canonical transition metadata.
+ */
+export function setTransition(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  transitions: CanonicalTransitionMap
+): void {
+  encoder.setTransition(nodeId, canonicalTransitionsToProtocol(transitions));
+}
+
+function setStringProp(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  propId: PropId,
+  value: string
+): void {
+  encoder.setPropString(nodeId, propId, value);
+}
+
+function setPropValue(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  propId: PropId,
+  value: string | number | boolean
+): void {
+  setStringProp(encoder, nodeId, propId, String(value));
+}
+
+function encodeStringPropTable(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  props: CanonicalProps,
+): void {
+  for (const [propName, propId] of STRING_PROP_ENCODINGS) {
+    const value = props[propName];
+    if (typeof value === 'string') {
+      setStringProp(encoder, nodeId, propId, value);
+    }
+  }
+}
+
+function encodeScalarPropTable(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  props: CanonicalProps,
+): void {
+  for (const [propName, propId] of SCALAR_PROP_ENCODINGS) {
+    const value = props[propName];
+    if (value !== undefined) {
+      setPropValue(encoder, nodeId, propId, value as string | number | boolean);
+    }
+  }
+}
+
+export function setTextContent(encoder: ProtocolEncoder, nodeId: number, text: string): void {
+  setStringProp(encoder, nodeId, PropId.TextContent, text);
+}
+
+export function setImageSource(encoder: ProtocolEncoder, nodeId: number, source: string): void {
+  setStringProp(encoder, nodeId, PropId.ImageSource, source);
+}
+
+export function setSvgSource(encoder: ProtocolEncoder, nodeId: number, source: string): void {
+  setStringProp(encoder, nodeId, PropId.SvgSource, source);
+}
+
+export function setSvgColors(encoder: ProtocolEncoder, nodeId: number, colors: string): void {
+  setStringProp(encoder, nodeId, PropId.SvgColors, colors);
+}
+
+export function setSvgPixelDensity(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  pixelDensity: string,
+): void {
+  setStringProp(encoder, nodeId, PropId.SvgPixelDensity, pixelDensity);
+}
+
+export function setSvgObjectPosition(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  objectPosition: string,
+): void {
+  setStringProp(encoder, nodeId, PropId.SvgObjectPosition, objectPosition);
+}
+
+export function setVideoPlayerId(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  playerId: string,
+): void {
+  setStringProp(encoder, nodeId, PropId.VideoPlayerId, playerId);
+}
+
+export function setVideoViewConfig(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  config: string,
+): void {
+  setStringProp(encoder, nodeId, PropId.VideoViewConfig, config);
+}
+
+export function setSelectionCopyText(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  text: string,
+): void {
+  setStringProp(encoder, nodeId, PropId.SelectionCopyText, text);
+}
+
+export function setLang(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  lang: string,
+): void {
+  setStringProp(encoder, nodeId, PropId.Lang, lang);
+}
+
+export function setNativeViewModuleName(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  moduleName: string,
+): void {
+  setStringProp(encoder, nodeId, PropId.NativeViewModuleName, moduleName);
+}
+
+export function setNativeViewProps(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  props: string,
+): void {
+  setStringProp(encoder, nodeId, PropId.NativeViewProps, props);
+}
+
+export function setNativeViewSelectionTier(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  tier: string,
+): void {
+  setStringProp(encoder, nodeId, PropId.NativeViewSelectionTier, tier);
+}
+
+export function setNativeViewGesturePolicy(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  gesturePolicy: string,
+): void {
+  setStringProp(encoder, nodeId, PropId.NativeViewGesturePolicy, gesturePolicy);
+}
+
+export function setPlaceholder(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  placeholder: string
+): void {
+  setStringProp(encoder, nodeId, PropId.Placeholder, placeholder);
+}
+
+export function setAccessibilityLabel(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  label: string
+): void {
+  setStringProp(encoder, nodeId, PropId.AccessibilityLabel, label);
+}
+
+export function setToggleValue(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  value: boolean
+): void {
+  setStringProp(encoder, nodeId, PropId.ToggleValue, value ? 'true' : 'false');
+}
+
+export function setGlassEffect(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  enabled: boolean
+): void {
+  setStringProp(encoder, nodeId, PropId.GlassEffect, enabled ? 'true' : 'false');
+}
+
+export function setTintColor(encoder: ProtocolEncoder, nodeId: number, color: string): void {
+  setStringProp(encoder, nodeId, PropId.TintColor, color);
+}
+
+export function setDisabled(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  disabled: boolean
+): void {
+  setStringProp(encoder, nodeId, PropId.Disabled, disabled ? 'true' : 'false');
+}
+
+export function setShowsScrollIndicator(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  showsScrollIndicator: boolean
+): void {
+  setStringProp(
+    encoder,
+    nodeId,
+    PropId.ShowsScrollIndicator,
+    showsScrollIndicator ? 'true' : 'false'
+  );
+}
+
+export function setSelectable(
+  encoder: ProtocolEncoder,
+  nodeId: number,
+  selectable: SelectableMode
+): void {
+  const value =
+    selectable === true
+      ? 'true'
+      : selectable === false
+        ? 'false'
+        : selectable;
+  setStringProp(encoder, nodeId, PropId.Selectable, value);
+}
+
+function isInteractiveSelectionBoundary(node: ElementNode): boolean {
+  return (
+    node.tagType === 'pressable' ||
+    node.originalTag === 'button' ||
+    node.events.has(EventType.Press) ||
+    node.events.has(EventType.PressIn) ||
+    node.events.has(EventType.PressOut) ||
+    node.events.has(EventType.LongPress)
+  );
+}
+
+function resolveInheritedSelectable(node: ElementNode): SelectableMode | undefined {
+  let current = node.parent as ElementNode | TextNode | RootNode | null;
+
+  while (current && current.kind !== NodeKind.Root) {
+    if (current.kind === NodeKind.Element && current.props.selectable !== undefined) {
+      return current.props.selectable;
+    }
+    current = current.parent as ElementNode | TextNode | RootNode | null;
+  }
+
+  return undefined;
+}
+
+function hasInteractiveAncestor(node: ElementNode): boolean {
+  let current = node.parent as ElementNode | TextNode | RootNode | null;
+
+  while (current && current.kind !== NodeKind.Root) {
+    if (current.kind === NodeKind.Element && isInteractiveSelectionBoundary(current)) {
+      return true;
+    }
+    current = current.parent as ElementNode | TextNode | RootNode | null;
+  }
+
+  return false;
+}
+
+function resolveSelectableMode(node: ElementNode): SelectableMode | undefined {
+  if (node.props.selectable !== undefined) {
+    return node.props.selectable;
+  }
+
+  const inherited = resolveInheritedSelectable(node);
+  if (inherited !== undefined) {
+    return inherited;
+  }
+
+  if (node.tagType === 'text') {
+    return hasInteractiveAncestor(node) ? false : true;
+  }
+
+  return undefined;
+}
+
+function shouldEncodeSelectable(node: ElementNode, selectable: SelectableMode | undefined): boolean {
+  if (node.props.selectable !== undefined) {
+    return true;
+  }
+
+  return node.tagType === 'text' && selectable === false;
+}
+
+function pixelOwnerIsDomMirror(): boolean {
+  // When the DOM mirror is installed (plain web, no protocol host), it owns
+  // pixels by rendering the host-ops node tree directly — the absence of a
+  // protocol consumer is expected then, not an error.
+  return (
+    (globalThis as typeof globalThis & { __exactDomMirror?: unknown }).__exactDomMirror !==
+    undefined
+  );
+}
+
+/**
+ * Dispatch the current buffer to the native runtime and reset it for reuse.
+ */
+export function dispatchProtocol(encoder: ProtocolEncoder): void {
+  const data = encoder.getUint8Array();
+  if (process.env.NODE_ENV !== 'production') {
+    recordProtocolFrame(data);
+  }
+  const debugContextJSON = getExactResizeTraceContextJSON();
+  markExactLoadTiming('protocolDispatchStart');
+
+  if (typeof exact !== 'undefined') {
+    if (debugContextJSON && typeof exact.dispatchWithDebugContext === 'function') {
+      exact.dispatchWithDebugContext(data, debugContextJSON);
+    } else if (typeof exact.dispatch === 'function') {
+      exact.dispatch(data);
+    } else if (process.env.NODE_ENV !== 'production' && !pixelOwnerIsDomMirror()) {
+      console.error('[ExactRenderer] Missing exact.dispatch during protocol flush', {
+        byteLength: data.byteLength,
+        hasExact: typeof exact !== 'undefined',
+        dispatchType: typeof (globalThis as typeof globalThis & {
+          exact?: {
+            dispatch?: unknown;
+          };
+        }).exact?.dispatch,
+      });
+    }
+  } else if (process.env.NODE_ENV !== 'production' && !pixelOwnerIsDomMirror()) {
+    console.error('[ExactRenderer] Missing exact.dispatch during protocol flush', {
+      byteLength: data.byteLength,
+      hasExact: typeof exact !== 'undefined',
+      dispatchType: typeof (globalThis as typeof globalThis & {
+        exact?: {
+          dispatch?: unknown;
+        };
+      }).exact?.dispatch,
+    });
+  }
+
+  markExactLoadTiming('protocolDispatchEnd');
+  encoder.reset();
+}
+
+function markExactLoadTiming(name: string): void {
+  const timings = (globalThis as typeof globalThis & {
+    __exactLoadTimings?: Record<string, number>;
+  }).__exactLoadTimings;
+  if (timings && timings[name] == null) {
+    timings[name] = Date.now();
+  }
+}
+
+function getExactResizeTraceContextJSON(): string | null {
+  if (typeof exact === 'undefined') {
+    return null;
+  }
+
+  const context = exact.__resizeTraceContext;
+  if (context == null) {
+    return null;
+  }
+
+  if (typeof context === 'string') {
+    return context.length > 0 ? context : null;
+  }
+
+  try {
+    const json = JSON.stringify(context);
+    return json && json.length > 0 ? json : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the screen dimensions from the runtime.
+ */
+export function getScreenDimensions(rootId: number = 0): { width: number; height: number } {
+  const runtimeViewport =
+    typeof exact !== 'undefined' &&
+    typeof exact.screenWidth === 'number' &&
+    isFinite(exact.screenWidth) &&
+    exact.screenWidth > 0 &&
+    typeof exact.screenHeight === 'number' &&
+    isFinite(exact.screenHeight) &&
+    exact.screenHeight > 0
+      ? {
+          width: exact.screenWidth,
+          height: exact.screenHeight,
+        }
+      : null;
+  const rootViewport = getWindowViewportForRoot(rootId);
+  if (
+    rootId === 0 &&
+    runtimeViewport &&
+    (rootViewport.width !== runtimeViewport.width || rootViewport.height !== runtimeViewport.height)
+  ) {
+    return runtimeViewport;
+  }
+  if (rootViewport.width > 0 && rootViewport.height > 0) {
+    return {
+      width: rootViewport.width,
+      height: rootViewport.height,
+    };
+  }
+
+  if (runtimeViewport) {
+    return runtimeViewport;
+  }
+
+  const hostWindow = (
+    globalThis as typeof globalThis & {
+      window?: {
+        innerWidth?: unknown;
+        innerHeight?: unknown;
+      };
+    }
+  ).window;
+  if (
+    typeof hostWindow?.innerWidth === 'number' &&
+    isFinite(hostWindow.innerWidth) &&
+    hostWindow.innerWidth > 0 &&
+    typeof hostWindow?.innerHeight === 'number' &&
+    isFinite(hostWindow.innerHeight) &&
+    hostWindow.innerHeight > 0
+  ) {
+    return {
+      width: hostWindow.innerWidth,
+      height: hostWindow.innerHeight,
+    };
+  }
+  return { width: 393, height: 852 };
+}
+
+// ===========================================================================
+// High-Level Encoding Functions
+// ===========================================================================
+
+/**
+ * Encode the creation of a new element node.
+ *
+ * @param encoder - The protocol encoder
+ * @param node - The element node to encode
+ */
+export function encodeCreateElement(encoder: ProtocolEncoder, node: ElementNode): void {
+  const config = getTagConfig(node.originalTag) ?? defaultTagConfig;
+
+  // Create the view
+  encoder.createView(node.id, config.nodeType);
+
+  // Set initial style
+  if (hasOwnEnumerableProperties(node.style)) {
+    setStyle(encoder, node.id, node.style);
+  }
+
+  if (hasOwnEnumerableProperties(node.transitions)) {
+    setTransition(encoder, node.id, node.transitions);
+  }
+
+  // Set props
+  encodeProps(encoder, node);
+
+  // Bind events
+  encodeEvents(encoder, node);
+}
+
+/**
+ * Encode the creation of a new text node.
+ *
+ * @param encoder - The protocol encoder
+ * @param node - The text node to encode
+ */
+export function encodeCreateText(encoder: ProtocolEncoder, node: TextNode): void {
+  encoder.createView(node.id, NodeType.Text);
+  setTextContent(encoder, node.id, node.text);
+}
+
+/**
+ * Encode props for an element node.
+ *
+ * @param encoder - The protocol encoder
+ * @param node - The element node
+ */
+export function encodeProps(encoder: ProtocolEncoder, node: ElementNode): void {
+  const props = node.props;
+  const selectable = resolveSelectableMode(node);
+
+  if (typeof props.lang === 'string' && props.lang.length > 0) {
+    setLang(encoder, node.id, node.resolvedLang);
+  }
+
+  if (props.textContent !== undefined) {
+    setTextContent(encoder, node.id, props.textContent);
+  }
+
+  if (props.value !== undefined) {
+    setTextContent(encoder, node.id, props.value);
+  }
+
+  encodeStringPropTable(encoder, node.id, props);
+  encodeScalarPropTable(encoder, node.id, props);
+
+  if (shouldEncodeSelectable(node, selectable) && selectable !== undefined) {
+    setSelectable(encoder, node.id, selectable);
+  }
+
+}
+
+/**
+ * Encode events for an element node.
+ *
+ * @param encoder - The protocol encoder
+ * @param node - The element node
+ */
+export function encodeEvents(encoder: ProtocolEncoder, node: ElementNode): void {
+  for (const [eventType, binding] of node.events) {
+    encoder.bindEvent(node.id, eventType, binding.handlerId);
+  }
+}
+
+/**
+ * Encode children for a node.
+ *
+ * @param encoder - The protocol encoder
+ * @param node - The parent node
+ */
+export function encodeChildren(encoder: ProtocolEncoder, node: RootNode | ElementNode): void {
+  if (node.kind === NodeKind.Root) {
+    // The native host can reset the kernel between JS bundles while the
+    // renderer process itself is still alive. Re-emitting the root create op
+    // on every root children sync makes root attachment idempotent, so later
+    // root children, style, and layout ops never target a missing root view
+    // after a reload/reset boundary.
+    encoder.createView(node.id, NodeType.View);
+  }
+
+  const childIds = getChildIds(node);
+  encoder.setChildren(node.id, childIds);
+}
+
+/**
+ * Encode the destruction of a node.
+ *
+ * @param encoder - The protocol encoder
+ * @param node - The node to destroy
+ */
+export function encodeDestroy(encoder: ProtocolEncoder, node: ElementNode | TextNode): void {
+  encoder.destroyView(node.id);
+}