@effindomv2/runtime 0.1.0

package/src/find-on-page.ts

@@ -0,0 +1,284 @@
+const textEncoder = new TextEncoder();
+
+export interface FindOnPageDocument {
+  readonly handle: string;
+  readonly text: string;
+}
+
+export interface ResolvedFindSelection {
+  readonly handle: string;
+  readonly start: number;
+  readonly end: number;
+}
+
+function utf8ByteLength(text: string): number {
+  return textEncoder.encode(text).byteLength;
+}
+
+function closestElement(node: Node | null): Element | null {
+  if (node instanceof Element) {
+    return node;
+  }
+  return node?.parentElement ?? null;
+}
+
+function utf8ByteOffsetFromCodeUnitIndex(text: string, codeUnitIndex: number): number {
+  const clampedIndex = Math.max(0, Math.min(codeUnitIndex, text.length));
+  return utf8ByteLength(text.slice(0, clampedIndex));
+}
+
+function codeUnitIndexFromUtf8ByteOffset(text: string, byteOffset: number): number {
+  const target = Math.max(0, Math.min(byteOffset, utf8ByteLength(text)));
+  let currentByteOffset = 0;
+  let currentIndex = 0;
+  while (currentIndex < text.length) {
+    const codePoint = text.codePointAt(currentIndex) ?? 0;
+    const nextIndex = currentIndex + (codePoint > 0xFFFF ? 2 : 1);
+    const nextByteOffset = utf8ByteOffsetFromCodeUnitIndex(text, nextIndex);
+    if (nextByteOffset > target) {
+      break;
+    }
+    currentIndex = nextIndex;
+    currentByteOffset = nextByteOffset;
+    if (currentByteOffset === target) {
+      break;
+    }
+  }
+  return currentIndex;
+}
+
+function readBoundaryCodeUnitOffset(fragment: HTMLElement, container: Node, offset: number): number | null {
+  const range = document.createRange();
+  range.selectNodeContents(fragment);
+  try {
+    range.setEnd(container, offset);
+  } catch {
+    return null;
+  }
+  return range.toString().length;
+}
+
+function ensureProjectedElement(
+  layer: HTMLElement,
+  byHandle: Map<string, HTMLDivElement>,
+  canvasId: string,
+  entry: FindOnPageDocument,
+): HTMLDivElement {
+  const existing = byHandle.get(entry.handle);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const created = document.createElement('div');
+  created.setAttribute('data-ed-find-fragment', '1');
+  created.setAttribute('data-ed-canvas-id', canvasId);
+  created.style.display = 'block';
+  created.style.position = 'relative';
+  created.style.whiteSpace = 'pre-wrap';
+  created.style.wordBreak = 'break-word';
+  created.style.pointerEvents = 'none';
+  created.style.userSelect = 'text';
+  layer.appendChild(created);
+  byHandle.set(entry.handle, created);
+  return created;
+}
+
+export class FindOnPageProjector {
+  private readonly layer: HTMLDivElement;
+  private readonly content: HTMLDivElement;
+  private readonly canvasId: string;
+  private readonly elementsByHandle = new Map<string, HTMLDivElement>();
+
+  public constructor(canvas: HTMLCanvasElement, canvasId: string) {
+    const parent = canvas.parentElement;
+    if (!(parent instanceof HTMLElement)) {
+      throw new Error('Expected scene shell for Find-on-Page projection.');
+    }
+
+    const layer = document.createElement('div');
+    layer.id = `find-on-page-layer-${canvasId}`;
+    layer.style.position = 'absolute';
+    layer.style.left = '0';
+    layer.style.top = '0';
+    layer.style.pointerEvents = 'none';
+    layer.style.opacity = '0';
+    layer.style.overflow = 'hidden';
+    layer.style.userSelect = 'text';
+    layer.setAttribute('aria-hidden', 'true');
+    layer.setAttribute('data-ed-find-root', '1');
+    layer.setAttribute('data-ed-canvas-id', canvasId);
+
+    const content = document.createElement('div');
+    content.id = `find-on-page-content-${canvasId}`;
+    content.style.position = 'absolute';
+    content.style.left = '0';
+    content.style.top = '0';
+    content.style.width = '100%';
+    content.style.minHeight = '100%';
+    content.style.pointerEvents = 'none';
+    content.style.userSelect = 'text';
+    content.style.whiteSpace = 'pre-wrap';
+    content.style.color = 'transparent';
+    content.style.background = 'transparent';
+    layer.appendChild(content);
+    parent.appendChild(layer);
+
+    this.layer = layer;
+    this.content = content;
+    this.canvasId = canvasId;
+  }
+
+  public syncSize(logicalWidth: number, logicalHeight: number): void {
+    const width = `${String(logicalWidth)}px`;
+    const height = `${String(logicalHeight)}px`;
+    this.layer.style.width = width;
+    this.layer.style.height = height;
+  }
+
+  public update(documents: readonly FindOnPageDocument[]): void {
+    const seenHandles = new Set<string>();
+    const orderedElements: HTMLDivElement[] = [];
+
+    for (const entry of documents) {
+      seenHandles.add(entry.handle);
+      const element = ensureProjectedElement(this.content, this.elementsByHandle, this.canvasId, entry);
+      element.setAttribute('data-ed-handle', entry.handle);
+      element.setAttribute('data-ed-start', '0');
+      element.setAttribute('data-ed-end', String(utf8ByteLength(entry.text)));
+      if (element.textContent !== entry.text) {
+        element.textContent = entry.text;
+      }
+      orderedElements.push(element);
+    }
+
+    this.content.replaceChildren(...orderedElements);
+    for (const [handle] of this.elementsByHandle.entries()) {
+      if (seenHandles.has(handle)) {
+        continue;
+      }
+      this.elementsByHandle.delete(handle);
+    }
+  }
+
+  public resolveSelection(selection: Selection | null): ResolvedFindSelection | null {
+    if (
+      selection === null ||
+      selection.rangeCount === 0 ||
+      selection.isCollapsed ||
+      document.activeElement?.getAttribute('data-effindom-hidden-editor') === 'true'
+    ) {
+      return null;
+    }
+
+    const range = selection.getRangeAt(0);
+    const startElement = closestElement(range.startContainer);
+    const endElement = closestElement(range.endContainer);
+    if (
+      startElement?.closest('[data-effindom-hidden-editor="true"]') !== null ||
+      endElement?.closest('[data-effindom-hidden-editor="true"]') !== null
+    ) {
+      return null;
+    }
+
+    const startRoot = startElement?.closest('[data-ed-find-root="1"]');
+    const endRoot = endElement?.closest('[data-ed-find-root="1"]');
+    const startFragment = startElement?.closest('[data-ed-find-fragment="1"]');
+    const endFragment = endElement?.closest('[data-ed-find-fragment="1"]');
+    if (
+      !(startRoot instanceof HTMLElement) ||
+      !(endRoot instanceof HTMLElement) ||
+      !(startFragment instanceof HTMLElement) ||
+      !(endFragment instanceof HTMLElement) ||
+      startRoot !== endRoot ||
+      startFragment !== endFragment ||
+      startRoot.dataset.edCanvasId !== this.canvasId ||
+      startFragment.dataset.edCanvasId !== this.canvasId
+    ) {
+      return null;
+    }
+
+    const handle = startFragment.dataset.edHandle;
+    const fragmentStart = Number(startFragment.dataset.edStart);
+    const fragmentEnd = Number(startFragment.dataset.edEnd);
+    if (
+      handle === undefined ||
+      !Number.isFinite(fragmentStart) ||
+      !Number.isFinite(fragmentEnd) ||
+      fragmentStart < 0 ||
+      fragmentEnd < fragmentStart
+    ) {
+      return null;
+    }
+
+    const text = startFragment.textContent ?? '';
+    const localStart = readBoundaryCodeUnitOffset(startFragment, range.startContainer, range.startOffset);
+    const localEnd = readBoundaryCodeUnitOffset(startFragment, range.endContainer, range.endOffset);
+    if (localStart === null || localEnd === null) {
+      return null;
+    }
+
+    const start = fragmentStart + utf8ByteOffsetFromCodeUnitIndex(text, localStart);
+    const end = fragmentStart + utf8ByteOffsetFromCodeUnitIndex(text, localEnd);
+    if (start >= end || end > fragmentEnd) {
+      return null;
+    }
+
+    return {
+      handle,
+      start,
+      end,
+    };
+  }
+
+  public selectMatch(match: ResolvedFindSelection | null): boolean {
+    const selection = document.getSelection();
+    if (selection === null) {
+      return false;
+    }
+    if (match === null) {
+      selection.removeAllRanges();
+      return true;
+    }
+
+    const fragment = this.elementsByHandle.get(match.handle);
+    if (!(fragment instanceof HTMLElement)) {
+      return false;
+    }
+
+    const fragmentStart = Number(fragment.dataset.edStart);
+    const fragmentEnd = Number(fragment.dataset.edEnd);
+    if (
+      !Number.isFinite(fragmentStart) ||
+      !Number.isFinite(fragmentEnd) ||
+      match.start < fragmentStart ||
+      match.end > fragmentEnd ||
+      match.start >= match.end
+    ) {
+      return false;
+    }
+
+    const text = fragment.textContent ?? '';
+    const localStart = match.start - fragmentStart;
+    const localEnd = match.end - fragmentStart;
+    const startIndex = codeUnitIndexFromUtf8ByteOffset(text, localStart);
+    const endIndex = codeUnitIndexFromUtf8ByteOffset(text, localEnd);
+    const textNode = fragment.firstChild instanceof Text
+      ? fragment.firstChild
+      : document.createTextNode(text);
+    if (fragment.firstChild !== textNode) {
+      fragment.replaceChildren(textNode);
+    }
+
+    const range = document.createRange();
+    range.setStart(textNode, startIndex);
+    range.setEnd(textNode, endIndex);
+    selection.removeAllRanges();
+    selection.addRange(range);
+    return true;
+  }
+
+  public destroy(): void {
+    this.elementsByHandle.clear();
+    this.layer.remove();
+  }
+}

package/src/harness.ts

@@ -0,0 +1,53 @@
+import type { BridgeRuntime } from './core-types';
+import { handleToBigInt } from './bridge/utils/encoding';
+
+const UI_SIZE_UNIT_PIXEL = 0;
+const UI_NODE_FLEX_BOX = 0;
+
+function waitForFrame(): Promise<void> {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        resolve();
+      });
+    });
+  });
+}
+
+async function runSmokeHarness(runtime: BridgeRuntime): Promise<void> {
+  const { canvas, ui } = runtime;
+  const rect = canvas.getBoundingClientRect();
+  const logicalWidth = rect.width;
+  const logicalHeight = rect.height;
+  const rootHandle = handleToBigInt(ui._ui_create_node(UI_NODE_FLEX_BOX));
+  if (rootHandle === 0n) {
+    throw new Error('ui_create_node returned UI_INVALID_HANDLE.');
+  }
+
+  ui._ui_set_root(rootHandle);
+  ui._ui_set_width(rootHandle, logicalWidth, UI_SIZE_UNIT_PIXEL);
+  ui._ui_set_height(rootHandle, logicalHeight, UI_SIZE_UNIT_PIXEL);
+  ui._ui_set_bg_color(rootHandle, 0xff0000ff);
+  ui._ui_commit_frame();
+
+  const commandWords = runtime.syncCommandBufferToCore();
+  await waitForFrame();
+
+  window.__bridgeState = {
+    commandWordCount: commandWords.length,
+    commandWords: Array.from(commandWords),
+    rootHandle: rootHandle.toString(),
+  };
+  window.__bridgeReady = true;
+  delete window.__bridgeError;
+}
+
+void window.EffinDomBrowserBridge?.ready.then(async (runtime) => {
+  await runSmokeHarness(runtime);
+}).catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  window.__bridgeError = message;
+  throw error;
+});
+
+export {};

package/src/index.ts

@@ -0,0 +1,40 @@
+export type {
+  BridgeRuntime,
+  BridgeState,
+  EffinDomCallbacks,
+  WasmHandleLike,
+} from './core-types';
+
+export {
+  computeModifiers,
+  handleToBigInt,
+  toHeapPointer,
+  normalizePointerForWasm,
+  pointerToHeapOffset,
+} from './bridge/utils/encoding';
+
+export {
+  getPointerPosition,
+} from './bridge/events/canvas-geometry';
+
+export {
+  writeBytesToHeap,
+} from './bridge/utils/heap';
+
+export type {
+  EffinDomRuntimeAssetUrls,
+  EffinDomRuntimeConfig,
+} from './runtime-config';
+
+export {
+  EFFINDOM_RUNTIME_ARTIFACT_DIR,
+  EFFINDOM_RUNTIME_BRIDGE_SCRIPT,
+  EFFINDOM_RUNTIME_DIST_DIR,
+  EFFINDOM_RUNTIME_FONTS_DIR,
+  EFFINDOM_RUNTIME_HARNESS_SCRIPT,
+  EFFINDOM_RUNTIME_MANIFEST_FILE,
+  applyRuntimeConfig,
+  createRuntimeConfig,
+  createRuntimeConfigScript,
+  resolveRuntimeAssetUrls,
+} from './runtime-config';

package/src/open-canvas.ts

@@ -0,0 +1,108 @@
+/**
+ * Opaque host-side identity for a retained node or document snapshot.
+ *
+ * The runtime owns handles as 64-bit values. The browser bridge exposes them as strings so:
+ * - JavaScript never loses precision on wasm64 / native 64-bit handles
+ * - extensions and hosts can persist and compare identities without reaching into wasm internals
+ *
+ * A handle is:
+ * - stable for the lifetime of the realized retained node
+ * - local to the current runtime instance
+ * - not a DOM node id, CSS selector, or application-level business id
+ */
+export type OpenCanvasHandle = string;
+
+export interface SemanticBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface SemanticState {
+  readonly checked?: 'false' | 'true' | 'mixed';
+  readonly selected?: boolean;
+  readonly expanded?: boolean;
+  readonly disabled?: boolean;
+  readonly readonly?: boolean;
+  readonly multiline?: boolean;
+  readonly orientation?: 'horizontal' | 'vertical';
+  readonly valueNow?: number;
+  readonly valueMin?: number;
+  readonly valueMax?: number;
+}
+
+/**
+ * Flattened semantic snapshot of one retained node as exposed to hosts.
+ *
+ * This is intentionally a bridge-friendly read model rather than a DOM clone:
+ * - `role` is the engine enum value
+ * - `roleName` is the host-readable role label
+ * - `handle` is the retained node identity token
+ * - `bounds` are logical canvas bounds for the realized node snapshot
+ * - `label` is the semantic label/text payload currently exposed for this node
+ * - `state` carries role-relevant flags without forcing consumers to inspect bridge DOM internals
+ */
+export interface SemanticNode {
+  readonly role: number;
+  readonly roleName: string;
+  readonly handle: OpenCanvasHandle;
+  readonly bounds: SemanticBounds;
+  readonly label: string;
+  readonly state: SemanticState;
+}
+
+export interface OpenCanvasTextDocument {
+  readonly handle: OpenCanvasHandle;
+  readonly text: string;
+}
+
+export interface OpenCanvasFindMatch {
+  readonly handle: OpenCanvasHandle;
+  readonly start: number;
+  readonly end: number;
+}
+
+export interface OpenCanvasFindOptions {
+  readonly highlightAll?: boolean;
+  readonly matchCase?: boolean;
+  readonly matchDiacritics?: boolean;
+  readonly wholeWords?: boolean;
+}
+
+export interface OpenCanvasResolvedFindOptions {
+  readonly highlightAll: boolean;
+  readonly matchCase: boolean;
+  readonly matchDiacritics: boolean;
+  readonly wholeWords: boolean;
+}
+
+export interface OpenCanvasFindResults {
+  readonly query: string;
+  readonly options: OpenCanvasResolvedFindOptions;
+  readonly matches: readonly OpenCanvasFindMatch[];
+}
+
+export interface OpenCanvasFindState extends OpenCanvasFindResults {
+  readonly activeMatchIndex: number;
+}
+
+/**
+ * Current shipped browser-host contract.
+ *
+ * This interface only covers the runtime surface that is actually wired today.
+ * Proposed mutation and callback/event contracts are documented in
+ * `docs/v2/browser-bridge/OPEN_CANVAS_API.md` until they are implemented.
+ */
+export interface OpenCanvasApi {
+  getSemanticTree(): SemanticNode[];
+  getBoundingBox(handle: OpenCanvasHandle): SemanticBounds | null;
+  getTextVisibleBounds(handle: OpenCanvasHandle): SemanticBounds | null;
+  getTextDocument(handle: OpenCanvasHandle): OpenCanvasTextDocument | null;
+  getRangeRects(handle: OpenCanvasHandle, start: number, end: number): readonly SemanticBounds[];
+  findText(query: string, options?: OpenCanvasFindOptions): OpenCanvasFindResults;
+  setFindState(state: OpenCanvasFindState | null, revealActive?: boolean): boolean;
+  getFindState(): OpenCanvasFindState | null;
+  setFindMatch(match: OpenCanvasFindMatch | null): boolean;
+  revealRange(handle: OpenCanvasHandle, start: number, end: number): boolean;
+}

package/src/runtime-config.ts

@@ -0,0 +1,96 @@
+export const EFFINDOM_RUNTIME_DIST_DIR = 'dist';
+export const EFFINDOM_RUNTIME_MANIFEST_FILE = 'effindom.v2.manifest.json';
+export const EFFINDOM_RUNTIME_BRIDGE_SCRIPT = 'bridge.js';
+export const EFFINDOM_RUNTIME_HARNESS_SCRIPT = 'harness.js';
+export const EFFINDOM_RUNTIME_ARTIFACT_DIR = 'runtime';
+export const EFFINDOM_RUNTIME_FONTS_DIR = 'fonts';
+
+export interface EffinDomRuntimeConfig {
+  readonly manifestUrl: string;
+}
+
+export interface EffinDomRuntimeAssetUrls {
+  readonly packageBaseUrl: string;
+  readonly distBaseUrl: string;
+  readonly manifestUrl: string;
+  readonly bridgeScriptUrl: string;
+  readonly harnessScriptUrl: string;
+  readonly runtimeBaseUrl: string;
+  readonly fontsBaseUrl: string;
+}
+
+interface RuntimeWindowLike {
+  __effindomRuntime?: Partial<EffinDomRuntimeConfig>;
+}
+
+function ensureTrailingSlash(url: string): string {
+  return url.endsWith('/') ? url : `${url}/`;
+}
+
+function resolveFromBase(
+  value: string | URL,
+  base?: string | URL,
+): URL {
+  if (value instanceof URL) {
+    return new URL(value.toString());
+  }
+  if (base !== undefined) {
+    return new URL(value, base);
+  }
+  if (typeof document !== 'undefined') {
+    return new URL(value, document.baseURI);
+  }
+  return new URL(value);
+}
+
+export function resolveRuntimeAssetUrls(
+  packageBaseUrl: string | URL,
+  relativeTo?: string | URL,
+): EffinDomRuntimeAssetUrls {
+  const packageBase = resolveFromBase(packageBaseUrl, relativeTo);
+  packageBase.pathname = ensureTrailingSlash(packageBase.pathname);
+  const distBase = new URL(`${EFFINDOM_RUNTIME_DIST_DIR}/`, packageBase);
+  const runtimeBase = new URL(`${EFFINDOM_RUNTIME_ARTIFACT_DIR}/`, distBase);
+  const fontsBase = new URL(`${EFFINDOM_RUNTIME_FONTS_DIR}/`, distBase);
+
+  return {
+    packageBaseUrl: packageBase.toString(),
+    distBaseUrl: distBase.toString(),
+    manifestUrl: new URL(EFFINDOM_RUNTIME_MANIFEST_FILE, distBase).toString(),
+    bridgeScriptUrl: new URL(EFFINDOM_RUNTIME_BRIDGE_SCRIPT, distBase).toString(),
+    harnessScriptUrl: new URL(EFFINDOM_RUNTIME_HARNESS_SCRIPT, distBase).toString(),
+    runtimeBaseUrl: runtimeBase.toString(),
+    fontsBaseUrl: fontsBase.toString(),
+  };
+}
+
+export function createRuntimeConfig(
+  packageBaseUrl: string | URL,
+  relativeTo?: string | URL,
+): EffinDomRuntimeConfig {
+  const urls = resolveRuntimeAssetUrls(packageBaseUrl, relativeTo);
+  return {
+    manifestUrl: urls.manifestUrl,
+  };
+}
+
+export function applyRuntimeConfig(
+  config: EffinDomRuntimeConfig,
+  target?: RuntimeWindowLike,
+): EffinDomRuntimeConfig {
+  const destination = target ?? (typeof window !== 'undefined' ? (window as RuntimeWindowLike) : undefined);
+  if (destination === undefined) {
+    throw new Error('applyRuntimeConfig requires a browser window-like target outside browser contexts.');
+  }
+  destination.__effindomRuntime = Object.assign({}, destination.__effindomRuntime, config);
+  return {
+    manifestUrl: destination.__effindomRuntime.manifestUrl ?? config.manifestUrl,
+  };
+}
+
+export function createRuntimeConfigScript(
+  config: EffinDomRuntimeConfig,
+): string {
+  const manifest = JSON.stringify(config.manifestUrl);
+  return `window.__effindomRuntime = Object.assign({}, window.__effindomRuntime, {\n  manifestUrl: ${manifest},\n});\n`;
+}