@webview-native-ui/engine 1.0.1 → 1.0.2

package/src/native/updates.ts

@@ -0,0 +1,103 @@
+/** Send only replaceable state from an update pass, never user actions. */
+export type NativeUpdateSender = <T>(request: () => Promise<T>, validate?: (result: T) => void) => Promise<T | undefined>;
+
+/** Coalesce current-state reads and serialize them across asynchronous native acknowledgements. */
+export const createNativeUpdateQueue = (
+  window: Pick<Window, 'requestAnimationFrame' | 'cancelAnimationFrame'>,
+  options: {
+    update(send: NativeUpdateSender): Promise<void>;
+    failed(error: unknown): void | Promise<void>;
+    retry(): void;
+    reconnect?: boolean;
+  },
+) => {
+  let frame = 0;
+  let dirty = false;
+  let running = false;
+  let stopped = false;
+  let retrying = false;
+  let waiting = false;
+  let reconciled = false;
+  let passFailed = false;
+  const request = () => {
+    if (stopped) return;
+    dirty = true;
+    if (!running && !waiting && !frame) frame = window.requestAnimationFrame(() => void run());
+  };
+  const waitForConnection = (error: unknown) => {
+    if (!options.reconnect || reconciled) throw error;
+    waiting = true;
+    dirty = false;
+  };
+  const send: NativeUpdateSender = async (operation, validate) => {
+    if (stopped || waiting || passFailed) return;
+    let result;
+    try {
+      result = await operation();
+    } catch (error) {
+      if (stopped) return;
+      passFailed = true;
+      if (retrying) waitForConnection(error);
+      else {
+        retrying = true;
+        options.retry();
+        request();
+      }
+      return;
+    }
+    if (stopped) return;
+    try {
+      validate?.(result);
+    } catch (error) {
+      passFailed = true;
+      waitForConnection(error);
+      return;
+    }
+    return result;
+  };
+  const run = async () => {
+    frame = 0;
+    if (stopped || waiting) return;
+    dirty = false;
+    running = true;
+    passFailed = false;
+    try {
+      await options.update(send);
+      if (!passFailed) retrying = waiting = reconciled = false;
+    } catch (error) {
+      if (stopped) return;
+      // Retire the queue before reporting terminal failure; no late update can restart it.
+      stopped = true;
+      await options.failed(error);
+    } finally {
+      running = false;
+      if (dirty) request();
+    }
+  };
+  return {
+    request,
+    get dirty() {
+      return dirty;
+    },
+    get running() {
+      return running;
+    },
+    get waiting() {
+      return waiting;
+    },
+    reconnected() {
+      if (stopped) return;
+      if (waiting) {
+        reconciled = true;
+        retrying = waiting = false;
+      }
+      request();
+    },
+    destroy() {
+      stopped = true;
+      dirty = false;
+      window.cancelAnimationFrame(frame);
+      frame = 0;
+    },
+  };
+};

package/src/native/values.ts

@@ -0,0 +1,29 @@
+/** Reflect native state without inventing component-specific input events. */
+export interface NativeValueBinding {
+  property?: string;
+}
+
+export const applyNativeValues = (target: HTMLElement, values: Record<string, unknown>, bindings: Record<string, NativeValueBinding>) => {
+  for (const [key, value] of Object.entries(values)) {
+    if (!/^[a-z][a-z0-9-]*$/.test(key)) throw new TypeError('Native value keys must be lowercase attribute names');
+    const binding = Object.hasOwn(bindings, key) ? bindings[key] : undefined;
+    const property = binding?.property;
+    if (
+      property &&
+      (!/^[a-zA-Z][\w]*$/.test(property) ||
+        /^on/i.test(property) ||
+        ['innerHTML', 'outerHTML', 'textContent', 'innerText', 'style', 'constructor', 'prototype'].includes(property))
+    )
+      throw new TypeError('Native value binding requires a data property');
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined) throw new TypeError('Native values must be JSON values');
+    if (property) {
+      const element = target as unknown as Record<string, unknown>;
+      if (JSON.stringify(element[property]) !== serialized) element[property] = value;
+    } else {
+      const attribute = `data-native-ui-value-${key}`;
+      const text = typeof value === 'string' ? value : serialized;
+      if (target.getAttribute(attribute) !== text) target.setAttribute(attribute, text);
+    }
+  }
+};

package/src/projection/events.ts

@@ -0,0 +1,58 @@
+import type { ListenerHandle } from '../types.js';
+import { boundedListener } from '../native/bridge.js';
+
+export type ProjectionDestination = 'native' | 'web' | 'none';
+
+/** Notifications from the existing plugin proxy; public plugin methods are never intercepted. */
+export interface ProjectionEvents {
+  addListener(name: string, listener: (event: unknown) => void): Promise<ListenerHandle>;
+  update?: readonly string[];
+  projection?: Partial<Record<ProjectionDestination, readonly string[]>>;
+  /** Required when the plugin emits events for multiple independent surfaces. */
+  accepts?(event: unknown): boolean;
+}
+
+/** Subscribe once per event, including events that both update and change destination. */
+export const bindProjectionEvents = async (
+  events: ProjectionEvents,
+  receive: (destination: ProjectionDestination | undefined, updated: boolean) => void,
+): Promise<ListenerHandle> => {
+  const routes = new Map<string, { destination?: ProjectionDestination; updated: boolean }>();
+  for (const name of events.update ?? []) routes.set(name, { updated: true });
+  for (const destination of ['native', 'web', 'none'] as const) {
+    for (const name of events.projection?.[destination] ?? []) {
+      const route = routes.get(name) ?? { updated: false };
+      if (route.destination && route.destination !== destination)
+        throw new TypeError(`Projection event "${name}" has conflicting destinations`);
+      routes.set(name, { ...route, destination });
+    }
+  }
+  let stopped = false;
+  const handles: ListenerHandle[] = [];
+  const remove = async () => {
+    stopped = true;
+    const results = await Promise.allSettled(handles.splice(0).map((handle) => Promise.resolve().then(() => handle.remove())));
+    const failure = results.find((result) => result.status === 'rejected');
+    if (failure?.status === 'rejected') throw failure.reason;
+  };
+  // Start all registrations immediately, so one slow bridge reply does not delay other subscriptions.
+  const registrations = [...routes].map(async ([name, route]) => {
+    const handle = await boundedListener(
+      Promise.resolve().then(() =>
+        events.addListener(name, (event) => {
+          if (!stopped && (!events.accepts || events.accepts(event))) receive(route.destination, route.updated);
+        }),
+      ),
+    );
+    if (stopped) await handle.remove();
+    else handles.push(handle);
+  });
+  try {
+    await Promise.all(registrations);
+    return { remove };
+  } catch (error) {
+    // Disable callbacks immediately. Late successful registrations also remove themselves.
+    await remove().catch(() => {});
+    throw error;
+  }
+};

package/src/projection/pause.ts

@@ -0,0 +1,58 @@
+import { getOverlayCoordinator } from '../dom/overlays.js';
+
+const key = Symbol.for('@webview-native-ui/engine/projection-pause/v1');
+const createPause = (doc: Document) => {
+  const overlays = getOverlayCoordinator(doc);
+  const listeners = new Set<() => void>();
+  let depth = 0;
+  let releaseFrame = 0;
+  const paused = () => depth > 0 || releaseFrame !== 0;
+  const notify = () => {
+    for (const listener of listeners) listener();
+  };
+  const change = (delta: number) => {
+    if (delta < 0 && depth === 0) return;
+    const wasPaused = paused();
+    depth += delta;
+    const win = doc.defaultView;
+    if (releaseFrame && win) {
+      win.cancelAnimationFrame(releaseFrame);
+      releaseFrame = 0;
+    }
+    if (depth === 0 && win) {
+      // Give DOM dismissal a paint opportunity before requesting Native return.
+      // Keep all consumers paused meanwhile, including Ionic change callbacks.
+      releaseFrame = win.requestAnimationFrame(() => {
+        releaseFrame = win.requestAnimationFrame(() => {
+          releaseFrame = 0;
+          notify();
+        });
+      });
+    } else if (wasPaused !== paused()) notify();
+  };
+  return {
+    // Without a target, only the document-wide request applies; renderers own local coverage.
+    isPaused: (target?: HTMLElement) => paused() || (!!target && overlays.isCovered(target)),
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      const stopOverlays = overlays.subscribe(listener);
+      return () => {
+        listeners.delete(listener);
+        stopOverlays();
+      };
+    },
+    pause: () => change(1),
+    resume: () => change(-1),
+  };
+};
+
+export const getProjectionPause = (doc: Document) => {
+  const shared = doc as unknown as Record<symbol, ReturnType<typeof createPause>>;
+  return (shared[key] ??= createPause(doc));
+};
+
+/** Request temporary Web projection across this document. Pair each call with resume(). */
+export const pause = (): void => getProjectionPause(document).pause();
+
+/** Release one shared pause, regardless of caller; resume exactly once per pause(). */
+export const resume = (): void => getProjectionPause(document).resume();

package/src/projection/placement.ts

@@ -0,0 +1,34 @@
+/** Placement supplied synchronously before a native view returns from a Web image. */
+export interface ProjectionPlacementBinding {
+  readonly projected: boolean;
+  dispose(): void;
+}
+interface PlacementState {
+  projected: boolean;
+  owner?: object;
+  invalidate(): void;
+  measure(): Record<string, unknown>;
+}
+// The injected runtime and a plugin's bundled helper share the binding.
+const placementKey = Symbol.for('webview-native-ui-engine.projection-placement');
+type PlacementElement = HTMLElement & { [placementKey]?: PlacementState };
+export const bindProjectionPlacement = (
+  element: HTMLElement,
+  measure: () => Record<string, unknown>,
+  invalidate: () => void = () => {},
+): ProjectionPlacementBinding => {
+  const host = element as PlacementElement;
+  const state: PlacementState = { projected: false, measure, invalidate };
+  host[placementKey] = state;
+  return {
+    get projected() {
+      return host[placementKey] === state && state.projected;
+    },
+    dispose() {
+      if (host[placementKey] === state) delete host[placementKey];
+      state.projected = false;
+    },
+  };
+};
+export const projectionPlacement = (element: HTMLElement | undefined): PlacementState | undefined =>
+  (element as PlacementElement | undefined)?.[placementKey];

package/src/projection/scope.ts

@@ -0,0 +1,13 @@
+/** A fixed Web fallback element. A replacement element requires a new scope. */
+export const createWebProjectionScope = (element: HTMLElement, namespace: string) => {
+  if (element.nodeType !== 1 || element.namespaceURI !== 'http://www.w3.org/1999/xhtml' || !element.ownerDocument || !('style' in element))
+    throw new TypeError('A Web projection scope requires an HTMLElement fallback');
+  if (
+    element.matches(
+      'img, input, textarea, select, video, audio, canvas, iframe, embed, object, br, hr, area, base, link, meta, source, track, wbr',
+    )
+  )
+    throw new TypeError('A Web projection fallback must be a container element; use the existing fallback container');
+  return Object.freeze({ element, namespace });
+};
+export type WebProjectionScope = ReturnType<typeof createWebProjectionScope>;

package/src/projection/styles.ts

@@ -0,0 +1,26 @@
+/** Image presentation only; Native/Web ownership styling stays with the renderer. */
+const hidden = ':is([data-native-ui-snapshot-source], [data-native-ui-snapshot-prepared], [data-native-ui-snapshot-content])';
+
+export const snapshotStyles = `
+@layer native-ui-projection {
+${hidden}, ${hidden} *, ${hidden}::part(native) { visibility: hidden !important; }
+${hidden}::before, ${hidden}::after,
+${hidden} *::before, ${hidden} *::after {
+  visibility: hidden !important;
+}
+}
+[data-native-ui-snapshot-visible][data-native-ui-snapshot-positioned] { position:relative!important; }
+`;
+
+export const snapshotShadowStyles = `
+@layer native-ui-projection {
+:host([data-native-ui-snapshot-content]),
+:host([data-native-ui-snapshot-content])::before,
+:host([data-native-ui-snapshot-content])::after,
+:host([data-native-ui-snapshot-content]) *,
+:host([data-native-ui-snapshot-content]) *::before,
+:host([data-native-ui-snapshot-content]) *::after {
+  visibility: hidden !important;
+}
+}
+`;

package/src/projection/surface.ts

@@ -0,0 +1,88 @@
+import { createWebProjectionBatch, type WebProjectionOptions } from './web.js';
+import { createWebProjectionScope, type WebProjectionScope } from './scope.js';
+import type { WebProjectionSource, WebProjectionTransport } from '../types.js';
+
+export interface WebProjectionSurfaceOptions extends WebProjectionOptions {
+  namespace: string;
+  target(source: WebProjectionSource): HTMLElement | undefined;
+  /** Only renderer-owned fallback hosts may move into another overlay layer. */
+  canRelocate?(target: HTMLElement): boolean;
+}
+
+/** A renderer supplies placement policy; the Engine owns the complete image handoff. */
+export const createWebProjectionSurface = async (transport: WebProjectionTransport, options: WebProjectionSurfaceOptions) => {
+  const scopes = new WeakMap<HTMLElement, WebProjectionScope>();
+  const moved = new Map<HTMLElement, { parent: Node; next: ChildNode | null; layer: HTMLElement }>();
+  const restorePlacement = () => {
+    for (const [element, saved] of [...moved].reverse()) {
+      if (element.parentNode === saved.layer && saved.parent.isConnected)
+        saved.parent.insertBefore(element, saved.next?.parentNode === saved.parent ? saved.next : null);
+    }
+    moved.clear();
+  };
+  const projection = await createWebProjectionBatch(transport, {
+    ...options,
+    wake: () => {
+      if (!projection.token && !projection.restoring) restorePlacement();
+      options.wake();
+    },
+  });
+  let latest: WebProjectionSource[] = [];
+  const { consider, begin, updated, invalidate, destroy } = projection;
+  return Object.assign(projection, {
+    consider(revision: number, sources: WebProjectionSource[]) {
+      latest = sources;
+      consider(
+        revision,
+        sources.flatMap((source) => {
+          const target = options.target(source);
+          if (!target?.isConnected || target.ownerDocument !== source.element.ownerDocument) return [];
+          let scope = scopes.get(target);
+          if (!scope) {
+            scope = createWebProjectionScope(target, options.namespace);
+            scopes.set(target, scope);
+          }
+          return [{ ...source, scope }];
+        }),
+      );
+    },
+    begin(layer?: HTMLElement) {
+      if (layer && !layer.isConnected) return;
+      if (layer && !projection.token) {
+        for (const source of latest) {
+          if (!projection.preparedOwners.includes(source.element)) continue;
+          const target = options.target(source);
+          if (
+            !target?.isConnected ||
+            !target.parentNode ||
+            target.ownerDocument !== layer.ownerDocument ||
+            layer.contains(target) ||
+            target.contains(layer) ||
+            !options.canRelocate?.(target)
+          )
+            continue;
+          if (!moved.has(target)) moved.set(target, { parent: target.parentNode, next: target.nextSibling, layer });
+          layer.append(target);
+        }
+      }
+      begin();
+      if (!projection.token) restorePlacement();
+    },
+    updated(token: string | undefined, ids?: string[], revision?: number) {
+      updated(token, ids, revision);
+      if (!projection.restoring && !projection.token) restorePlacement();
+    },
+    invalidate(nativeHidden?: boolean) {
+      invalidate(nativeHidden);
+      restorePlacement();
+    },
+    async destroy() {
+      try {
+        await destroy();
+      } finally {
+        restorePlacement();
+      }
+    },
+  });
+};
+export type WebProjectionSurface = Awaited<ReturnType<typeof createWebProjectionSurface>>;

package/src/projection/surfaces.ts

@@ -0,0 +1,119 @@
+import type { WebProjectionSurface } from './surface.js';
+
+/** Owns asynchronous projection creation and disposal for DOM-backed surfaces. */
+export const createWebProjectionSurfaces = <Owner extends Node, Surface extends WebProjectionSurface>(
+  options: { ignoreTarget?(element: Element): boolean } = {},
+) => {
+  type Entry = { surface?: Surface; ready: Promise<Surface | undefined> };
+  const entries = new Map<Owner, Entry>();
+  const retiring = new Set<Promise<unknown>>();
+  const retire = (disposal: Promise<unknown>) => {
+    const pending = disposal.finally(() => retiring.delete(pending));
+    retiring.add(pending);
+    return pending;
+  };
+  let stopped = false;
+  const values = (): Surface[] => [...entries.values()].flatMap((entry) => (entry.surface ? [entry.surface] : []));
+  let doc: Document | undefined;
+  let listeners: AbortController | undefined;
+  let motionFrame = 0;
+  const invalidate = () => values().forEach((surface) => surface.invalidate());
+  const changed = (owner?: EventTarget) => values().forEach((surface) => surface.changed(owner));
+  const observe = (owner: Owner) => {
+    const ownerDocument = owner.nodeType === 9 ? (owner as unknown as Document) : owner.ownerDocument!;
+    if (doc && doc !== ownerDocument) throw new TypeError('Projection surfaces must share one Document');
+    if (doc) return;
+    doc = ownerDocument;
+    const win = doc.defaultView!;
+    listeners = new win.AbortController();
+    const subscription = { signal: listeners.signal };
+    win.addEventListener('resize', invalidate, subscription);
+    win.addEventListener('orientationchange', invalidate, subscription);
+    doc.addEventListener(
+      'visibilitychange',
+      () => {
+        if (doc!.hidden) invalidate();
+      },
+      subscription,
+    );
+    const appearance = (event: Event) => {
+      const target = event.target instanceof win.Element ? event.target : undefined;
+      if (target?.closest('style[data-native-ui-snapshot], [data-native-ui-projection-node]') || (target && options.ignoreTarget?.(target)))
+        return;
+      if (target?.hasAttribute('data-native-ui-snapshot') && (event as TransitionEvent).pseudoElement) return;
+      changed();
+    };
+    for (const name of ['load', 'transitionrun', 'transitionend', 'transitioncancel', 'animationstart', 'animationend', 'animationcancel'])
+      doc.addEventListener(name, appearance, { ...subscription, capture: name === 'load' });
+  };
+  const followMotion = (moving: ReadonlyMap<HTMLElement, unknown>, target: (source: HTMLElement) => HTMLElement = (source) => source) => {
+    if (motionFrame || stopped || !moving.size || !doc?.defaultView) return;
+    // Ancestor transforms already carry the image. Only the host's own motion needs rebasing.
+    const surfaces = values().filter(
+      (surface) =>
+        (surface.token || surface.restoring) &&
+        (surface.restoring ? surface.visibleOwners : surface.owners).some((owner) => moving.has(target(owner))),
+    );
+    if (!surfaces.length) return;
+    motionFrame = doc.defaultView.requestAnimationFrame(() => {
+      motionFrame = 0;
+      surfaces.forEach((surface) => surface.moved());
+      followMotion(moving, target);
+    });
+  };
+  const remove = async (owner: Owner) => {
+    const entry = entries.get(owner);
+    if (!entry) return;
+    entries.delete(owner);
+    await retire(entry.surface ? entry.surface.destroy() : entry.ready.catch(() => {}));
+  };
+  return {
+    get: (owner: Owner) => entries.get(owner)?.surface,
+    keys: () => entries.keys(),
+    values,
+    changed,
+    invalidate,
+    followMotion,
+    end: () => values().forEach((surface) => surface.end()),
+    consider: (...args: Parameters<WebProjectionSurface['consider']>) => values().forEach((surface) => surface.consider(...args)),
+    updated: (...args: Parameters<WebProjectionSurface['updated']>) => values().forEach((surface) => surface.updated(...args)),
+    get restoring() {
+      return values().some((surface) => surface.restoring);
+    },
+    get handoffPending() {
+      return values().some((surface) => surface.handoffPending);
+    },
+    ensure(owner: Owner, create: () => Promise<Surface>): Promise<Surface | undefined> {
+      if (stopped || !owner.isConnected) return Promise.resolve(undefined);
+      observe(owner);
+      const existing = entries.get(owner);
+      if (existing) return existing.ready;
+      const entry: Entry = {
+        ready: Promise.resolve()
+          .then(create)
+          .then(async (surface) => {
+            if (stopped || entries.get(owner) !== entry || !owner.isConnected) {
+              if (entries.get(owner) === entry) entries.delete(owner);
+              await retire(surface.destroy());
+              return undefined;
+            }
+            entry.surface = surface;
+            return surface;
+          })
+          .catch((error) => {
+            if (entries.get(owner) === entry) entries.delete(owner);
+            throw error;
+          }),
+      };
+      entries.set(owner, entry);
+      return entry.ready;
+    },
+    delete: remove,
+    async destroy() {
+      stopped = true;
+      listeners?.abort();
+      if (motionFrame) doc?.defaultView?.cancelAnimationFrame(motionFrame);
+      await Promise.all([...retiring, ...[...entries.keys()].map(remove)]);
+    },
+  };
+};