@effindomv2/fui-as 0.1.0

package/browser/src/host-events.ts

@@ -0,0 +1,97 @@
+import type { HostServiceTypeName } from "./host-services";
+
+type HostEventTypeValue<T extends HostServiceTypeName> =
+  T extends "string" ? string :
+  T extends "bool" ? boolean :
+  T extends "void" ? void :
+  number;
+
+type HostEventArgsValues<TArgs extends readonly HostServiceTypeName[]> = {
+  readonly [K in keyof TArgs]: HostEventTypeValue<TArgs[K] & HostServiceTypeName>;
+};
+
+export interface HostEventMethodDefinition<
+  TArgs extends readonly HostServiceTypeName[] = readonly HostServiceTypeName[],
+> {
+  readonly args: TArgs;
+  readonly subscribe: (emit: (...args: HostEventArgsValues<TArgs>) => void) => (() => void) | void;
+}
+
+export type HostEventsDefinition = Record<string, Record<string, HostEventMethodDefinition>>;
+
+export interface NormalizedHostEventMethod {
+  readonly serviceName: string;
+  readonly methodName: string;
+  readonly eventName: string;
+  readonly exportName: string;
+  readonly args: readonly HostServiceTypeName[];
+  readonly subscribe: (emit: (...args: readonly unknown[]) => void) => (() => void) | void;
+}
+
+const IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export function hostEvent<
+  TArgs extends readonly HostServiceTypeName[],
+>(definition: HostEventMethodDefinition<TArgs>): HostEventMethodDefinition<TArgs> {
+  return definition;
+}
+
+export function defineHostEvents<TEvents extends HostEventsDefinition>(events: TEvents): TEvents {
+  return events;
+}
+
+function assertIdentifier(value: string, context: string): void {
+  if (!IDENTIFIER_RE.test(value)) {
+    throw new Error(`${context} "${value}" must be a valid identifier.`);
+  }
+}
+
+function capitalize(value: string): string {
+  return value.length == 0 ? value : `${value[0].toUpperCase()}${value.slice(1)}`;
+}
+
+function buildEventName(serviceName: string, methodName: string): string {
+  return `${serviceName}${capitalize(methodName)}`;
+}
+
+function buildExportName(eventName: string): string {
+  return `__fui_host_event_${eventName}`;
+}
+
+function validateEventType(type: string, context: string): asserts type is HostServiceTypeName {
+  if (type === "string" || type === "bool" || type === "i32" || type === "f64") {
+    return;
+  }
+  throw new Error(`${context} uses unsupported host-event type "${type}".`);
+}
+
+export function listHostEventMethods(events: HostEventsDefinition | undefined): ReadonlyArray<NormalizedHostEventMethod> {
+  if (events === undefined) {
+    return [];
+  }
+  const methods: Array<NormalizedHostEventMethod> = [];
+  const seenEvents = new Set<string>();
+  for (const [serviceName, serviceMethods] of Object.entries(events)) {
+    assertIdentifier(serviceName, "Host event service");
+    for (const [methodName, definition] of Object.entries(serviceMethods)) {
+      assertIdentifier(methodName, `Host event ${serviceName} method`);
+      const eventName = buildEventName(serviceName, methodName);
+      if (seenEvents.has(eventName)) {
+        throw new Error(`Duplicate host-event name "${eventName}".`);
+      }
+      seenEvents.add(eventName);
+      const args = [...definition.args];
+      args.forEach((type, index) => validateEventType(type, `Host event ${serviceName}.${methodName} arg ${String(index)}`));
+      methods.push({
+        serviceName,
+        methodName,
+        eventName,
+        exportName: buildExportName(eventName),
+        args,
+        subscribe: definition.subscribe as (emit: (...args: readonly unknown[]) => void) => (() => void) | void,
+      });
+    }
+  }
+  methods.sort((left, right) => left.eventName.localeCompare(right.eventName));
+  return methods;
+}

package/browser/src/host-services.ts

@@ -0,0 +1,203 @@
+export type HostServiceTypeName = "string" | "bool" | "i32" | "f64" | "void";
+
+type HostServiceTypeValue<T extends HostServiceTypeName> =
+  T extends "string" ? string :
+  T extends "bool" ? boolean :
+  T extends "void" ? void :
+  number;
+
+type HostServiceArgsValues<TArgs extends readonly HostServiceTypeName[]> = {
+  readonly [K in keyof TArgs]: HostServiceTypeValue<TArgs[K] & HostServiceTypeName>;
+};
+
+export interface HostServiceMethodDefinition<
+  TArgs extends readonly HostServiceTypeName[] = readonly HostServiceTypeName[],
+  TResult extends HostServiceTypeName = HostServiceTypeName,
+> {
+  readonly args: TArgs;
+  readonly returns: TResult;
+  readonly implementation: (...args: HostServiceArgsValues<TArgs>) => HostServiceTypeValue<TResult>;
+}
+
+export type HostServicesDefinition = Record<string, Record<string, HostServiceMethodDefinition>>;
+
+export interface NormalizedHostServiceMethod {
+  readonly serviceName: string;
+  readonly methodName: string;
+  readonly importName: string;
+  readonly args: readonly HostServiceTypeName[];
+  readonly returns: HostServiceTypeName;
+  readonly implementation: (...args: readonly unknown[]) => unknown;
+}
+
+export interface HostServiceImportIo {
+  readString(ptr: number, len: number): string;
+  writeString(ptr: number, capacity: number, text: string, context: string): number;
+}
+
+const IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export function hostService<
+  TArgs extends readonly HostServiceTypeName[],
+  TResult extends HostServiceTypeName,
+>(definition: HostServiceMethodDefinition<TArgs, TResult>): HostServiceMethodDefinition<TArgs, TResult> {
+  return definition;
+}
+
+export function defineHostServices<TServices extends HostServicesDefinition>(services: TServices): TServices {
+  return services;
+}
+
+function assertIdentifier(value: string, context: string): void {
+  if (!IDENTIFIER_RE.test(value)) {
+    throw new Error(`${context} "${value}" must be a valid identifier.`);
+  }
+}
+
+function capitalize(value: string): string {
+  return value.length == 0 ? value : `${value[0].toUpperCase()}${value.slice(1)}`;
+}
+
+function buildImportName(serviceName: string, methodName: string): string {
+  return `${serviceName}${capitalize(methodName)}`;
+}
+
+function validateServiceType(type: string, context: string): asserts type is HostServiceTypeName {
+  if (type === "string" || type === "bool" || type === "i32" || type === "f64" || type === "void") {
+    return;
+  }
+  throw new Error(`${context} uses unsupported host-service type "${type}".`);
+}
+
+export function listHostServiceMethods(services: HostServicesDefinition | undefined): ReadonlyArray<NormalizedHostServiceMethod> {
+  if (services === undefined) {
+    return [];
+  }
+  const methods: Array<NormalizedHostServiceMethod> = [];
+  const seenImports = new Set<string>();
+  for (const [serviceName, serviceMethods] of Object.entries(services)) {
+    assertIdentifier(serviceName, "Host service");
+    for (const [methodName, definition] of Object.entries(serviceMethods)) {
+      assertIdentifier(methodName, `Host service ${serviceName} method`);
+      const importName = buildImportName(serviceName, methodName);
+      if (seenImports.has(importName)) {
+        throw new Error(`Duplicate host-service import name "${importName}".`);
+      }
+      seenImports.add(importName);
+      const args = [...definition.args];
+      args.forEach((type, index) => validateServiceType(type, `Host service ${serviceName}.${methodName} arg ${String(index)}`));
+      validateServiceType(definition.returns, `Host service ${serviceName}.${methodName} return`);
+      methods.push({
+        serviceName,
+        methodName,
+        importName,
+        args,
+        returns: definition.returns,
+        implementation: definition.implementation as (...args: readonly unknown[]) => unknown,
+      });
+    }
+  }
+  methods.sort((left, right) => left.importName.localeCompare(right.importName));
+  return methods;
+}
+
+export function getHostServiceImportNames(services: HostServicesDefinition | undefined): ReadonlySet<string> {
+  return new Set(listHostServiceMethods(services).map((method) => method.importName));
+}
+
+function expectNumber(value: unknown, context: string): number {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    throw new Error(`${context} must be a number.`);
+  }
+  return value;
+}
+
+function expectBoolean(value: unknown, context: string): boolean {
+  if (typeof value !== "boolean") {
+    throw new Error(`${context} must be a boolean.`);
+  }
+  return value;
+}
+
+function expectString(value: unknown, context: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`${context} must be a string.`);
+  }
+  return value;
+}
+
+function expectI32(value: unknown, context: string): number {
+  const numberValue = expectNumber(value, context);
+  if (!Number.isInteger(numberValue) || numberValue < -2147483648 || numberValue > 2147483647) {
+    throw new Error(`${context} must be a signed 32-bit integer.`);
+  }
+  return numberValue;
+}
+
+function decodeHostServiceArgs(
+  method: NormalizedHostServiceMethod,
+  rawArgs: readonly unknown[],
+  io: HostServiceImportIo,
+): ReadonlyArray<unknown> {
+  const decodedArgs: Array<unknown> = [];
+  let index = 0;
+  method.args.forEach((type, argIndex) => {
+    const context = `Host service ${method.serviceName}.${method.methodName} arg ${String(argIndex)}`;
+    if (type === "string") {
+      const ptr = expectNumber(rawArgs[index], `${context} ptr`);
+      const len = expectNumber(rawArgs[index + 1], `${context} len`);
+      decodedArgs.push(len <= 0 ? "" : io.readString(ptr, len));
+      index += 2;
+      return;
+    }
+    const rawValue = rawArgs[index];
+    if (type === "bool") {
+      decodedArgs.push(expectNumber(rawValue, context) !== 0);
+    } else if (type === "i32") {
+      decodedArgs.push(expectI32(rawValue, context));
+    } else if (type === "f64") {
+      decodedArgs.push(expectNumber(rawValue, context));
+    } else {
+      throw new Error(`${context} uses unsupported type ${type}.`);
+    }
+    index += 1;
+  });
+  return decodedArgs;
+}
+
+export function createHostServiceImportModule(
+  services: HostServicesDefinition | undefined,
+  io: HostServiceImportIo,
+): Record<string, (...rawArgs: Array<unknown>) => number | void> {
+  const module: Record<string, (...rawArgs: Array<unknown>) => number | void> = {};
+  for (const method of listHostServiceMethods(services)) {
+    module[method.importName] = (...rawArgs: Array<unknown>): number | void => {
+      const decodedArgs = decodeHostServiceArgs(method, rawArgs, io);
+      const result = method.implementation(...decodedArgs);
+      const resultContext = `Host service ${method.serviceName}.${method.methodName} result`;
+      if (method.returns === "void") {
+        return;
+      }
+      if (method.returns === "string") {
+        let outputIndex = 0;
+        method.args.forEach((type) => {
+          outputIndex += type === "string" ? 2 : 1;
+        });
+        const ptr = expectNumber(rawArgs[outputIndex], `${resultContext} ptr`);
+        const capacity = expectNumber(rawArgs[outputIndex + 1], `${resultContext} capacity`);
+        return io.writeString(ptr, capacity, expectString(result, resultContext), resultContext);
+      }
+      if (method.returns === "bool") {
+        return expectBoolean(result, resultContext) ? 1 : 0;
+      }
+      if (method.returns === "i32") {
+        return expectI32(result, resultContext);
+      }
+      if (method.returns === "f64") {
+        return expectNumber(result, resultContext);
+      }
+      throw new Error(`${resultContext} uses unsupported type ${method.returns}.`);
+    };
+  }
+  return module;
+}

package/browser/src/index.ts

@@ -0,0 +1,62 @@
+export {
+  startHarness,
+  startManagedHarness,
+  canManagedNavigateBack,
+  canManagedNavigateForward,
+  pushManagedHistoryEntry,
+  readManagedHistoryState,
+  replaceManagedHistoryEntry,
+  setCurrentManagedHistorySnapshotId,
+  syncManagedHistoryPop,
+} from './common-harness';
+
+export type {
+  HarnessAppOptions,
+  HarnessContext,
+  HarnessController,
+  HarnessDebugApi,
+  HarnessExports,
+  HarnessNavigationMode,
+  HarnessOptions,
+  HarnessState,
+  ManagedHarnessOptions,
+  ManagedHistoryState,
+} from './common-harness';
+
+export {
+  startRoutedHarness,
+} from './routed-harness';
+
+export type {
+  RoutedHarnessConfig,
+  RoutedHarnessManagerState,
+  RoutedHarnessRoute,
+} from './routed-harness';
+
+export {
+  defineHostEvents,
+  hostEvent,
+} from './host-events';
+
+export type {
+  HostEventMethodDefinition,
+  HostEventsDefinition,
+  NormalizedHostEventMethod,
+} from './host-events';
+
+export {
+  defineHostServices,
+  hostService,
+} from './host-services';
+
+export type {
+  HostServiceImportIo,
+  HostServiceMethodDefinition,
+  HostServiceTypeName,
+  HostServicesDefinition,
+  NormalizedHostServiceMethod,
+} from './host-services';
+
+export type {
+  WorkerHostServicesBundleConfig,
+} from './worker-types';

package/browser/src/persisted-ui-state.ts

@@ -0,0 +1,206 @@
+export const PERSISTED_UI_STATE_DB_NAME = 'effindom-ui-state';
+export const PERSISTED_UI_STATE_DB_VERSION = 1;
+export const PERSISTED_UI_STATE_SNAPSHOT_SCHEMA_VERSION = 1;
+export const PERSISTED_UI_STATE_SNAPSHOTS_STORE = 'snapshots';
+export const PERSISTED_UI_STATE_ROUTE_HEADS_STORE = 'route-heads';
+export const PERSISTED_SCROLL_ENTRY_KIND = 'scroll-position';
+export const PERSISTED_SCROLL_ENTRY_VERSION = 1;
+
+const SNAPSHOT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+export interface PersistedSnapshotEntry {
+  readonly nodeId: string;
+  readonly kind: string;
+  readonly version: number;
+  readonly payload: unknown;
+}
+
+export interface PersistedScrollPayload {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface PersistedSnapshotRecord {
+  readonly snapshotId: string;
+  readonly appKey: string;
+  readonly routeHref: string;
+  readonly createdAt: number;
+  readonly lastAccessedAt: number;
+  readonly schemaVersion: number;
+  readonly entries: readonly PersistedSnapshotEntry[];
+}
+
+export interface PersistedRouteHeadRecord {
+  readonly routeKey: string;
+  readonly appKey: string;
+  readonly routeHref: string;
+  readonly snapshotId: string;
+  readonly updatedAt: number;
+}
+
+export interface PersistedUiStateStore {
+  saveSnapshot(record: PersistedSnapshotRecord): Promise<void>;
+  loadSnapshot(snapshotId: string): Promise<PersistedSnapshotRecord | null>;
+  loadRouteHead(appKey: string, routeHref: string): Promise<PersistedRouteHeadRecord | null>;
+  deleteSnapshot(snapshotId: string): Promise<void>;
+  collectGarbage(now: number): Promise<void>;
+}
+
+export function buildPersistedUiRouteKey(appKey: string, routeHref: string): string {
+  return `${appKey}\n${routeHref}`;
+}
+
+function requestToPromise<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('IndexedDB request failed.'));
+  });
+}
+
+function transactionToPromise(transaction: IDBTransaction): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    transaction.oncomplete = () => resolve();
+    transaction.onabort = () => reject(transaction.error ?? new Error('IndexedDB transaction aborted.'));
+    transaction.onerror = () => reject(transaction.error ?? new Error('IndexedDB transaction failed.'));
+  });
+}
+
+function openDatabase(factory: IDBFactory): Promise<IDBDatabase> {
+  return new Promise<IDBDatabase>((resolve, reject) => {
+    const request = factory.open(PERSISTED_UI_STATE_DB_NAME, PERSISTED_UI_STATE_DB_VERSION);
+    request.onupgradeneeded = () => {
+      const database = request.result;
+      let snapshots = database.objectStoreNames.contains(PERSISTED_UI_STATE_SNAPSHOTS_STORE)
+        ? request.transaction?.objectStore(PERSISTED_UI_STATE_SNAPSHOTS_STORE) ?? null
+        : null;
+      if (snapshots === null) {
+        snapshots = database.createObjectStore(PERSISTED_UI_STATE_SNAPSHOTS_STORE, {
+          keyPath: 'snapshotId',
+        });
+      }
+      if (!snapshots.indexNames.contains('byLastAccessedAt')) {
+        snapshots.createIndex('byLastAccessedAt', 'lastAccessedAt');
+      }
+
+      let routeHeads = database.objectStoreNames.contains(PERSISTED_UI_STATE_ROUTE_HEADS_STORE)
+        ? request.transaction?.objectStore(PERSISTED_UI_STATE_ROUTE_HEADS_STORE) ?? null
+        : null;
+      if (routeHeads === null) {
+        routeHeads = database.createObjectStore(PERSISTED_UI_STATE_ROUTE_HEADS_STORE, {
+          keyPath: 'routeKey',
+        });
+      }
+      if (!routeHeads.indexNames.contains('byUpdatedAt')) {
+        routeHeads.createIndex('byUpdatedAt', 'updatedAt');
+      }
+      if (!routeHeads.indexNames.contains('bySnapshotId')) {
+        routeHeads.createIndex('bySnapshotId', 'snapshotId');
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('Failed to open IndexedDB database.'));
+  });
+}
+
+class IndexedDbPersistedUiStateStore implements PersistedUiStateStore {
+  private readonly databasePromise: Promise<IDBDatabase>;
+
+  constructor(factory: IDBFactory) {
+    this.databasePromise = openDatabase(factory);
+  }
+
+  async saveSnapshot(record: PersistedSnapshotRecord): Promise<void> {
+    const database = await this.databasePromise;
+    const transaction = database.transaction(
+      [PERSISTED_UI_STATE_SNAPSHOTS_STORE, PERSISTED_UI_STATE_ROUTE_HEADS_STORE],
+      'readwrite',
+    );
+    const snapshots = transaction.objectStore(PERSISTED_UI_STATE_SNAPSHOTS_STORE);
+    const routeHeads = transaction.objectStore(PERSISTED_UI_STATE_ROUTE_HEADS_STORE);
+    snapshots.put(record);
+    const updatedAt = Math.max(record.createdAt, record.lastAccessedAt);
+    routeHeads.put({
+      routeKey: buildPersistedUiRouteKey(record.appKey, record.routeHref),
+      appKey: record.appKey,
+      routeHref: record.routeHref,
+      snapshotId: record.snapshotId,
+      updatedAt,
+    } satisfies PersistedRouteHeadRecord);
+    await transactionToPromise(transaction);
+  }
+
+  async loadSnapshot(snapshotId: string): Promise<PersistedSnapshotRecord | null> {
+    const database = await this.databasePromise;
+    const loadTransaction = database.transaction(PERSISTED_UI_STATE_SNAPSHOTS_STORE, 'readonly');
+    const snapshots = loadTransaction.objectStore(PERSISTED_UI_STATE_SNAPSHOTS_STORE);
+    const existing = await requestToPromise<PersistedSnapshotRecord | undefined>(snapshots.get(snapshotId));
+    await transactionToPromise(loadTransaction);
+    if (existing === undefined) {
+      return null;
+    }
+
+    const updatedRecord: PersistedSnapshotRecord = {
+      ...existing,
+      lastAccessedAt: Date.now(),
+    };
+    const saveTransaction = database.transaction(PERSISTED_UI_STATE_SNAPSHOTS_STORE, 'readwrite');
+    saveTransaction.objectStore(PERSISTED_UI_STATE_SNAPSHOTS_STORE).put(updatedRecord);
+    await transactionToPromise(saveTransaction);
+    return updatedRecord;
+  }
+
+  async loadRouteHead(appKey: string, routeHref: string): Promise<PersistedRouteHeadRecord | null> {
+    const database = await this.databasePromise;
+    const transaction = database.transaction(PERSISTED_UI_STATE_ROUTE_HEADS_STORE, 'readonly');
+    const routeHeads = transaction.objectStore(PERSISTED_UI_STATE_ROUTE_HEADS_STORE);
+    const routeHead = await requestToPromise<PersistedRouteHeadRecord | undefined>(
+      routeHeads.get(buildPersistedUiRouteKey(appKey, routeHref)),
+    );
+    await transactionToPromise(transaction);
+    return routeHead ?? null;
+  }
+
+  async deleteSnapshot(snapshotId: string): Promise<void> {
+    const database = await this.databasePromise;
+    const transaction = database.transaction(PERSISTED_UI_STATE_SNAPSHOTS_STORE, 'readwrite');
+    transaction.objectStore(PERSISTED_UI_STATE_SNAPSHOTS_STORE).delete(snapshotId);
+    await transactionToPromise(transaction);
+  }
+
+  async collectGarbage(now: number): Promise<void> {
+    const database = await this.databasePromise;
+    const transaction = database.transaction(
+      [PERSISTED_UI_STATE_SNAPSHOTS_STORE, PERSISTED_UI_STATE_ROUTE_HEADS_STORE],
+      'readwrite',
+    );
+    const snapshots = transaction.objectStore(PERSISTED_UI_STATE_SNAPSHOTS_STORE);
+    const routeHeads = transaction.objectStore(PERSISTED_UI_STATE_ROUTE_HEADS_STORE);
+    const snapshotRecords = await requestToPromise<Array<PersistedSnapshotRecord>>(snapshots.getAll());
+    const routeHeadRecords = await requestToPromise<Array<PersistedRouteHeadRecord>>(routeHeads.getAll());
+    const retainedSnapshotIds = new Set(routeHeadRecords.map((record) => record.snapshotId));
+    const knownSnapshotIds = new Set(snapshotRecords.map((record) => record.snapshotId));
+    const pruneBefore = now - SNAPSHOT_MAX_AGE_MS;
+
+    for (const routeHead of routeHeadRecords) {
+      if (!knownSnapshotIds.has(routeHead.snapshotId)) {
+        routeHeads.delete(routeHead.routeKey);
+      }
+    }
+
+    for (const snapshot of snapshotRecords) {
+      if (snapshot.lastAccessedAt >= pruneBefore || retainedSnapshotIds.has(snapshot.snapshotId)) {
+        continue;
+      }
+      snapshots.delete(snapshot.snapshotId);
+    }
+
+    await transactionToPromise(transaction);
+  }
+}
+
+export function createPersistedUiStateStore(): PersistedUiStateStore | null {
+  if (typeof globalThis.indexedDB === 'undefined') {
+    return null;
+  }
+  return new IndexedDbPersistedUiStateStore(globalThis.indexedDB);
+}