@ccheever/exact-ibex-runtime 0.1.0

package/src/core/accessibility-state.ts

@@ -0,0 +1,263 @@
+// @system @ref LLP 0011#state-modules — startup imports only accessibility state.
+export interface ExactAccessibilitySnapshot {
+  readonly prefersReducedMotion: boolean;
+  readonly isBoldTextEnabled: boolean;
+  readonly prefersHighContrast: boolean;
+  readonly prefersReducedTransparency: boolean;
+  readonly fontScale: number;
+  readonly isScreenReaderEnabled: boolean;
+  readonly colorScheme: "light" | "dark";
+  readonly isInvertColorsEnabled: boolean;
+  readonly isGrayscaleEnabled: boolean;
+  readonly dynamicTypeSize: string | null;
+}
+
+export interface NativeAccessibilitySnapshot {
+  readonly prefersReducedMotion?: boolean;
+  readonly isBoldTextEnabled?: boolean;
+  readonly prefersHighContrast?: boolean;
+  readonly prefersReducedTransparency?: boolean;
+  readonly fontScale?: number;
+  readonly isScreenReaderEnabled?: boolean;
+  readonly colorScheme?: "light" | "dark";
+  readonly isInvertColorsEnabled?: boolean;
+  readonly isGrayscaleEnabled?: boolean;
+  readonly dynamicTypeSize?: string | null;
+}
+
+export type AccessibilityInfoKey = keyof ExactAccessibilitySnapshot;
+export type AccessibilityInfoEvent =
+  | "change"
+  | "reduceMotionChanged"
+  | "boldTextChanged"
+  | "highContrastChanged"
+  | "reducedTransparencyChanged"
+  | "fontScaleChanged"
+  | "screenReaderChanged"
+  | "colorSchemeChanged"
+  | "invertColorsChanged"
+  | "grayscaleChanged"
+  | "dynamicTypeSizeChanged";
+
+export type ExactAccessibilityListener = (snapshot: ExactAccessibilitySnapshot) => void;
+export type AccessibilityEventListener = (value: unknown) => void;
+
+interface ExactAccessibilityRuntimeState {
+  snapshot: ExactAccessibilitySnapshot;
+  listeners: Set<ExactAccessibilityListener>;
+  eventListeners: Map<AccessibilityInfoEvent, Set<AccessibilityEventListener>>;
+  changeTimer: ReturnType<typeof setTimeout> | null;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __exactAccessibilityState: ExactAccessibilityRuntimeState | undefined;
+  // eslint-disable-next-line no-var
+  var __exactAccessibilitySnapshot: NativeAccessibilitySnapshot | undefined;
+  // eslint-disable-next-line no-var
+  var __exactAccessibilityChanged:
+    | ((snapshot?: NativeAccessibilitySnapshot | null) => void)
+    | undefined;
+  // eslint-disable-next-line no-var
+  var __exactAppearanceState:
+    | {
+        colorScheme?: "light" | "dark";
+        reducedMotion?: boolean;
+      }
+    | undefined;
+  // eslint-disable-next-line no-var
+  var __exactWindowNotifyMediaChange:
+    | ((next: { colorScheme?: "light" | "dark"; reducedMotion?: boolean }) => void)
+    | undefined;
+}
+
+function freezeSnapshot(snapshot: ExactAccessibilitySnapshot): ExactAccessibilitySnapshot {
+  return Object.freeze({ ...snapshot });
+}
+
+function normalizeFontScale(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 1;
+}
+
+export function readNativeAccessibilitySnapshot(): NativeAccessibilitySnapshot | null {
+  const nativeSnapshot = globalThis.__exactAccessibilitySnapshot;
+  if (nativeSnapshot && typeof nativeSnapshot === "object") {
+    return nativeSnapshot;
+  }
+
+  const appearanceState = globalThis.__exactAppearanceState;
+  if (appearanceState && typeof appearanceState === "object") {
+    return {
+      colorScheme: appearanceState.colorScheme === "dark" ? "dark" : "light",
+      prefersReducedMotion: appearanceState.reducedMotion === true,
+    };
+  }
+
+  return null;
+}
+
+function buildAccessibilitySnapshot(
+  value: NativeAccessibilitySnapshot | null,
+): ExactAccessibilitySnapshot {
+  return freezeSnapshot({
+    prefersReducedMotion: value?.prefersReducedMotion === true,
+    isBoldTextEnabled: value?.isBoldTextEnabled === true,
+    prefersHighContrast: value?.prefersHighContrast === true,
+    prefersReducedTransparency: value?.prefersReducedTransparency === true,
+    fontScale: normalizeFontScale(value?.fontScale),
+    isScreenReaderEnabled: value?.isScreenReaderEnabled === true,
+    colorScheme: value?.colorScheme === "dark" ? "dark" : "light",
+    isInvertColorsEnabled: value?.isInvertColorsEnabled === true,
+    isGrayscaleEnabled: value?.isGrayscaleEnabled === true,
+    dynamicTypeSize:
+      typeof value?.dynamicTypeSize === "string" && value.dynamicTypeSize.length > 0
+        ? value.dynamicTypeSize
+        : null,
+  });
+}
+
+function createDefaultState(): ExactAccessibilityRuntimeState {
+  return {
+    snapshot: buildAccessibilitySnapshot(readNativeAccessibilitySnapshot()),
+    listeners: new Set(),
+    eventListeners: new Map(),
+    changeTimer: null,
+  };
+}
+
+function getAccessibilityState(): ExactAccessibilityRuntimeState {
+  if (!globalThis.__exactAccessibilityState) {
+    globalThis.__exactAccessibilityState = createDefaultState();
+  }
+  return globalThis.__exactAccessibilityState;
+}
+
+function dispatchAccessibilityChange(state: ExactAccessibilityRuntimeState): void {
+  const snapshot = state.snapshot;
+  for (const listener of state.listeners) {
+    try {
+      listener(snapshot);
+    } catch {
+      // Ignore listener failures.
+    }
+  }
+}
+
+function emitNamedEvent(
+  state: ExactAccessibilityRuntimeState,
+  event: AccessibilityInfoEvent,
+  value: unknown,
+): void {
+  const listeners = state.eventListeners.get(event);
+  if (!listeners) {
+    return;
+  }
+
+  for (const listener of listeners) {
+    try {
+      listener(value);
+    } catch {
+      // Ignore listener failures.
+    }
+  }
+}
+
+function scheduleAccessibilityChange(state: ExactAccessibilityRuntimeState): void {
+  if (state.changeTimer != null) {
+    clearTimeout(state.changeTimer);
+  }
+
+  state.changeTimer = setTimeout(() => {
+    state.changeTimer = null;
+    dispatchAccessibilityChange(state);
+  }, 100);
+}
+
+function updateAppearanceMirror(snapshot: ExactAccessibilitySnapshot): void {
+  globalThis.__exactAppearanceState = {
+    colorScheme: snapshot.colorScheme,
+    reducedMotion: snapshot.prefersReducedMotion,
+  };
+  globalThis.__exactWindowNotifyMediaChange?.({
+    colorScheme: snapshot.colorScheme,
+    reducedMotion: snapshot.prefersReducedMotion,
+  });
+}
+
+export function updateAccessibilitySnapshot(
+  value: NativeAccessibilitySnapshot | null,
+  notify: boolean,
+): ExactAccessibilitySnapshot {
+  const state = getAccessibilityState();
+  const previous = state.snapshot;
+  const next = buildAccessibilitySnapshot(value);
+  state.snapshot = next;
+  updateAppearanceMirror(next);
+
+  const changedEntries = ([
+    ["prefersReducedMotion", "reduceMotionChanged"],
+    ["isBoldTextEnabled", "boldTextChanged"],
+    ["prefersHighContrast", "highContrastChanged"],
+    ["prefersReducedTransparency", "reducedTransparencyChanged"],
+    ["fontScale", "fontScaleChanged"],
+    ["isScreenReaderEnabled", "screenReaderChanged"],
+    ["colorScheme", "colorSchemeChanged"],
+    ["isInvertColorsEnabled", "invertColorsChanged"],
+    ["isGrayscaleEnabled", "grayscaleChanged"],
+    ["dynamicTypeSize", "dynamicTypeSizeChanged"],
+  ] as const).filter(([key]) => previous[key] !== next[key]);
+
+  if (notify && changedEntries.length > 0) {
+    scheduleAccessibilityChange(state);
+    for (const [key, event] of changedEntries) {
+      emitNamedEvent(state, event, next[key]);
+    }
+    emitNamedEvent(state, "change", next);
+  }
+
+  return next;
+}
+
+export function subscribeExactAccessibilityChanges(
+  listener: ExactAccessibilityListener,
+): () => void {
+  const state = getAccessibilityState();
+  state.listeners.add(listener);
+  return () => {
+    state.listeners.delete(listener);
+  };
+}
+
+export function addExactAccessibilityEventListener(
+  event: AccessibilityInfoEvent,
+  listener: AccessibilityEventListener,
+): () => void {
+  const state = getAccessibilityState();
+  const listeners = state.eventListeners.get(event) ?? new Set<AccessibilityEventListener>();
+  listeners.add(listener);
+  state.eventListeners.set(event, listeners);
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0) {
+      state.eventListeners.delete(event);
+    }
+  };
+}
+
+export function getExactAccessibilitySnapshot(): ExactAccessibilitySnapshot {
+  return getAccessibilityState().snapshot;
+}
+
+export function refreshExactAccessibility(): ExactAccessibilitySnapshot {
+  return updateAccessibilitySnapshot(readNativeAccessibilitySnapshot(), true);
+}
+
+export function _resetExactAccessibilityForTests(): void {
+  const state = globalThis.__exactAccessibilityState;
+  if (state?.changeTimer != null) {
+    clearTimeout(state.changeTimer);
+  }
+  delete globalThis.__exactAccessibilityState;
+  delete globalThis.__exactAccessibilityChanged;
+  delete globalThis.__exactAccessibilitySnapshot;
+}

package/src/core/accessibility.ts

@@ -0,0 +1,184 @@
+// @system @ref LLP 0011#state-modules — accessibility preferences in shared runtime state.
+import { hostCallBridge } from "./host-call-bridge.js";
+import {
+  addExactAccessibilityEventListener,
+  getExactAccessibilitySnapshot,
+  readNativeAccessibilitySnapshot,
+  subscribeExactAccessibilityChanges,
+  updateAccessibilitySnapshot,
+  type AccessibilityEventListener,
+  type AccessibilityInfoEvent,
+  type AccessibilityInfoKey,
+  type ExactAccessibilitySnapshot,
+  type NativeAccessibilitySnapshot,
+} from "./accessibility-state.js";
+
+export {
+  _resetExactAccessibilityForTests,
+  getExactAccessibilitySnapshot,
+  refreshExactAccessibility,
+  subscribeExactAccessibilityChanges,
+  type AccessibilityInfoEvent,
+  type AccessibilityInfoKey,
+  type ExactAccessibilitySnapshot,
+} from "./accessibility-state.js";
+
+interface ExactAccessibilityNamespace {
+  readonly prefersReducedMotion: boolean;
+  readonly isBoldTextEnabled: boolean;
+  readonly prefersHighContrast: boolean;
+  readonly prefersReducedTransparency: boolean;
+  readonly fontScale: number;
+  readonly isScreenReaderEnabled: boolean;
+  readonly colorScheme: "light" | "dark";
+  readonly isInvertColorsEnabled: boolean;
+  readonly isGrayscaleEnabled: boolean;
+  readonly dynamicTypeSize: string | null;
+  get<K extends AccessibilityInfoKey>(key: K): ExactAccessibilitySnapshot[K];
+  addEventListener(event: AccessibilityInfoEvent, listener: AccessibilityEventListener): () => void;
+  announce(message: string, options?: { queue?: boolean }): boolean;
+}
+
+function createAccessibilityNamespace(): ExactAccessibilityNamespace {
+  return {
+    get prefersReducedMotion() {
+      return getExactAccessibilitySnapshot().prefersReducedMotion;
+    },
+    get isBoldTextEnabled() {
+      return getExactAccessibilitySnapshot().isBoldTextEnabled;
+    },
+    get prefersHighContrast() {
+      return getExactAccessibilitySnapshot().prefersHighContrast;
+    },
+    get prefersReducedTransparency() {
+      return getExactAccessibilitySnapshot().prefersReducedTransparency;
+    },
+    get fontScale() {
+      return getExactAccessibilitySnapshot().fontScale;
+    },
+    get isScreenReaderEnabled() {
+      return getExactAccessibilitySnapshot().isScreenReaderEnabled;
+    },
+    get colorScheme() {
+      return getExactAccessibilitySnapshot().colorScheme;
+    },
+    get isInvertColorsEnabled() {
+      return getExactAccessibilitySnapshot().isInvertColorsEnabled;
+    },
+    get isGrayscaleEnabled() {
+      return getExactAccessibilitySnapshot().isGrayscaleEnabled;
+    },
+    get dynamicTypeSize() {
+      return getExactAccessibilitySnapshot().dynamicTypeSize;
+    },
+    get(key) {
+      return getExactAccessibilitySnapshot()[key];
+    },
+    addEventListener(event, listener) {
+      return addExactAccessibilityEventListener(event, listener);
+    },
+    announce(message, options) {
+      return announceForAccessibility(message, options);
+    },
+  };
+}
+
+export function installExactAccessibilityGlobal(): ExactAccessibilityNamespace {
+  const g = globalThis as typeof globalThis & {
+    Exact?: Record<string, unknown>;
+  };
+
+  if (typeof g.Exact !== "object" || g.Exact === null) {
+    g.Exact = {};
+  }
+
+  const exact = g.Exact as Record<string, unknown>;
+  const existing = exact.accessibility;
+  if (
+    existing &&
+    typeof existing === "object" &&
+    typeof (existing as ExactAccessibilityNamespace).addEventListener === "function"
+  ) {
+    return existing as ExactAccessibilityNamespace;
+  }
+
+  updateAccessibilitySnapshot(readNativeAccessibilitySnapshot(), false);
+
+  const accessibility = createAccessibilityNamespace();
+  Object.defineProperty(exact, "accessibility", {
+    value: accessibility,
+    writable: true,
+    configurable: true,
+    enumerable: true,
+  });
+
+  globalThis.__exactAccessibilityChanged = (snapshot?: NativeAccessibilitySnapshot | null) => {
+    if (snapshot && typeof snapshot === "object") {
+      globalThis.__exactAccessibilitySnapshot = snapshot;
+    }
+    updateAccessibilitySnapshot(snapshot ?? readNativeAccessibilitySnapshot(), true);
+  };
+
+  return accessibility;
+}
+
+export function announceForAccessibility(
+  message: string,
+  options: { queue?: boolean } = {},
+): boolean {
+  if (typeof message !== "string" || message.trim().length === 0) {
+    return false;
+  }
+
+  const hostCall = hostCallBridge();
+  if (!hostCall) {
+    return false;
+  }
+
+  try {
+    const result = hostCall(
+      "accessibility.announce",
+      JSON.stringify({
+        message,
+        queue: options.queue !== false,
+      }),
+    );
+    return result !== false;
+  } catch {
+    return false;
+  }
+}
+
+export function focusElementForAccessibility(
+  target:
+    | { readonly viewId: number }
+    | { readonly nativeID: string }
+    | { readonly testId: string },
+): boolean {
+  const hostCall = hostCallBridge();
+  if (!hostCall) {
+    return false;
+  }
+
+  try {
+    const result = hostCall("accessibility.focus", JSON.stringify(target));
+    return result !== false;
+  } catch {
+    return false;
+  }
+}
+
+export const AccessibilityInfo = {
+  get<K extends AccessibilityInfoKey>(key: K): ExactAccessibilitySnapshot[K] {
+    return getExactAccessibilitySnapshot()[key];
+  },
+  addEventListener(
+    event: AccessibilityInfoEvent,
+    listener: AccessibilityEventListener,
+  ): () => void {
+    return addExactAccessibilityEventListener(event, listener);
+  },
+  announce(message: string, options?: { queue?: boolean }): boolean {
+    return announceForAccessibility(message, options);
+  },
+} as const;

package/src/core/agent-state.ts

@@ -0,0 +1,37 @@
+const activeAnimationFrames = new Set<number>();
+let lastAnimationActivityAt = 0;
+
+function currentTimestamp(): number {
+  return Date.now();
+}
+
+export function trackAnimationFrameRequested(id: number): void {
+  activeAnimationFrames.add(id);
+  lastAnimationActivityAt = currentTimestamp();
+}
+
+export function trackAnimationFrameCancelled(id: number): void {
+  if (activeAnimationFrames.delete(id)) {
+    lastAnimationActivityAt = currentTimestamp();
+  }
+}
+
+export function trackAnimationFrameExecuted(ids: number[]): void {
+  let changed = false;
+  for (const id of ids) {
+    changed = activeAnimationFrames.delete(id) || changed;
+  }
+  if (changed) {
+    lastAnimationActivityAt = currentTimestamp();
+  }
+}
+
+export function getAnimationTrackingState(): {
+  activeCount: number;
+  lastActivityAt: number;
+} {
+  return {
+    activeCount: activeAnimationFrames.size,
+    lastActivityAt: lastAnimationActivityAt,
+  };
+}

package/src/core/diagnostics-logs.ts

@@ -0,0 +1,144 @@
+export type AgentLogLevel = "debug" | "info" | "warn" | "error" | string;
+export type AgentLogSource = "runtime" | "renderer" | "host" | "agent" | string;
+
+export interface AgentLogEntry {
+  entryId: string;
+  timestamp: number;
+  source: AgentLogSource;
+  level: AgentLogLevel;
+  message: string;
+  stack?: string;
+  componentStack?: string;
+  context?: Record<string, unknown>;
+  rootId?: number;
+  snapshotId?: string;
+  count: number;
+  firstTimestamp: number;
+  lastTimestamp: number;
+}
+
+const MAX_AGENT_LOG_ENTRIES = 1000;
+const DEDUP_WINDOW_MS = 1000;
+
+type AgentLogListener = (entry: AgentLogEntry) => void;
+
+export interface AgentLogInput {
+  source: AgentLogSource;
+  level: AgentLogLevel;
+  message: string;
+  stack?: string;
+  componentStack?: string;
+  context?: Record<string, unknown>;
+  rootId?: number;
+  snapshotId?: string;
+  timestamp?: number;
+}
+
+const entries: AgentLogEntry[] = [];
+const listeners = new Set<AgentLogListener>();
+let nextEntryId = 1;
+
+function currentTimestamp(): number {
+  return Date.now();
+}
+
+function cloneContext(
+  context: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!context) {
+    return undefined;
+  }
+  return { ...context };
+}
+
+function canCollapse(
+  previous: AgentLogEntry | undefined,
+  next: AgentLogInput,
+  timestamp: number,
+): previous is AgentLogEntry {
+  if (!previous) {
+    return false;
+  }
+
+  if (timestamp - previous.lastTimestamp > DEDUP_WINDOW_MS) {
+    return false;
+  }
+
+  return (
+    previous.source === next.source &&
+    previous.level === next.level &&
+    previous.message === next.message &&
+    previous.stack === next.stack &&
+    previous.componentStack === next.componentStack &&
+    previous.rootId === next.rootId
+  );
+}
+
+export function recordAgentLog(
+  input: AgentLogInput,
+): { entry: AgentLogEntry; created: boolean } {
+  const timestamp = input.timestamp ?? currentTimestamp();
+  const previous = entries.length > 0 ? entries[entries.length - 1] : undefined;
+
+  if (canCollapse(previous, input, timestamp)) {
+    previous.count += 1;
+    previous.lastTimestamp = timestamp;
+    previous.timestamp = timestamp;
+    if (input.snapshotId) {
+      previous.snapshotId = input.snapshotId;
+    }
+    if (input.context) {
+      previous.context = cloneContext(input.context);
+    }
+    return { entry: previous, created: false };
+  }
+
+  const entry: AgentLogEntry = {
+    entryId: String(nextEntryId),
+    timestamp,
+    source: input.source,
+    level: input.level,
+    message: input.message,
+    stack: input.stack,
+    componentStack: input.componentStack,
+    context: cloneContext(input.context),
+    rootId: input.rootId,
+    snapshotId: input.snapshotId,
+    count: 1,
+    firstTimestamp: timestamp,
+    lastTimestamp: timestamp,
+  };
+  nextEntryId += 1;
+
+  entries.push(entry);
+  if (entries.length > MAX_AGENT_LOG_ENTRIES) {
+    entries.shift();
+  }
+
+  for (const listener of listeners) {
+    try {
+      listener(entry);
+    } catch (error) {
+      console.error("[AgentLogs] listener failed:", error);
+    }
+  }
+
+  return { entry, created: true };
+}
+
+export function getAgentLogEntries(): AgentLogEntry[] {
+  return entries.slice();
+}
+
+export function subscribeAgentLogs(listener: AgentLogListener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function _resetAgentLogState(): void {
+  entries.length = 0;
+  listeners.clear();
+  nextEntryId = 1;
+}

package/src/core/host-call-bridge.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared helper for looking up the host bridge function exposed on
+ * `globalThis.__hostCall`.
+ */
+
+export function hostCallBridge():
+  | ((operation: string, argsJson: string) => unknown)
+  | null {
+  const hostCall = (
+    globalThis as {
+      __hostCall?: ((operation: string, argsJson: string) => unknown) | undefined;
+    }
+  ).__hostCall;
+
+  return typeof hostCall === 'function' ? hostCall : null;
+}