@aura3d/editor-runtime 1.0.6

package/src/LocalizationAccessibilityFixtures.ts

@@ -0,0 +1,368 @@
+export type EditorLocaleDirection = "ltr" | "rtl";
+export type EditorPluralCategory = "zero" | "one" | "two" | "few" | "many" | "other";
+export type EditorAccessibilityRole = "button" | "navigation" | "slider" | "textbox" | "status" | "dialog";
+
+export interface EditorLocaleDescriptor {
+  readonly code: string;
+  readonly displayName: string;
+  readonly direction: EditorLocaleDirection;
+  readonly currencySymbol: string;
+  readonly decimalSeparator: string;
+  readonly thousandsSeparator: string;
+  readonly currencyPosition: "before" | "after";
+}
+
+export interface EditorLocalizedStringSample {
+  readonly locale: string;
+  readonly direction: EditorLocaleDirection;
+  readonly title: string;
+  readonly assetCount: string;
+  readonly fallbackTitle: string;
+  readonly missingKey: string;
+  readonly formattedNumber: string;
+  readonly formattedCurrency: string;
+  readonly pluralCategory: EditorPluralCategory;
+}
+
+export interface EditorAccessibilityElementSample {
+  readonly id: string;
+  readonly role: EditorAccessibilityRole;
+  readonly label: string;
+  readonly tabIndex: number;
+  readonly focusable: boolean;
+  readonly disabled?: boolean;
+  readonly ariaLive?: "polite" | "assertive";
+  readonly contrastRatio: number;
+  readonly contrastPassesAA: boolean;
+}
+
+export interface EditorLocalizationAccessibilityFixture {
+  readonly source: "origin-master-localization-ui-accessibility-adapted";
+  readonly sourceFiles: readonly string[];
+  readonly localeCount: number;
+  readonly rtlLocaleCount: number;
+  readonly tableKeyCount: number;
+  readonly jsonLoaderValidated: boolean;
+  readonly csvLoaderValidated: boolean;
+  readonly hotSwapLocale: {
+    readonly from: string;
+    readonly to: string;
+    readonly directionChanged: boolean;
+    readonly listenerNotifications: readonly string[];
+  };
+  readonly samples: readonly EditorLocalizedStringSample[];
+  readonly missingKeys: readonly string[];
+  readonly accessibility: {
+    readonly elementCount: number;
+    readonly labelledControls: number;
+    readonly focusOrder: readonly string[];
+    readonly focusWalk: readonly string[];
+    readonly liveRegionAnnouncements: readonly string[];
+    readonly highContrastMode: boolean;
+    readonly minContrastRatio: number;
+    readonly aaContrastPasses: boolean;
+  };
+  readonly blockedClaims: readonly string[];
+  readonly claimBoundary: string;
+  readonly hash: string;
+}
+
+type StringTable = Record<string, string>;
+
+const sourceFiles = [
+  "origin/master:src/localization/LocalizationManager.ts",
+  "origin/master:src/localization/StringTable.ts",
+  "origin/master:src/localization/Locale.ts",
+  "origin/master:src/localization/Pluralization.ts",
+  "origin/master:src/localization/loaders/JSONLocaleLoader.ts",
+  "origin/master:src/localization/loaders/CSVLocaleLoader.ts",
+  "origin/master:src/ui/UIAccessibility.ts"
+] as const;
+
+const blockedClaims = [
+  "full localization pipeline",
+  "ICU MessageFormat parity",
+  "bidirectional text shaping parity",
+  "screen-reader certification",
+  "WCAG conformance certification",
+  "Unity UI Toolkit parity",
+  "Unreal UMG parity"
+] as const;
+
+const locales: readonly EditorLocaleDescriptor[] = [
+  {
+    code: "en-US",
+    displayName: "English (United States)",
+    direction: "ltr",
+    currencySymbol: "$",
+    decimalSeparator: ".",
+    thousandsSeparator: ",",
+    currencyPosition: "before"
+  },
+  {
+    code: "es-ES",
+    displayName: "Spanish (Spain)",
+    direction: "ltr",
+    currencySymbol: "EUR",
+    decimalSeparator: ",",
+    thousandsSeparator: ".",
+    currencyPosition: "after"
+  },
+  {
+    code: "ar-SA",
+    displayName: "Arabic (Saudi Arabia)",
+    direction: "rtl",
+    currencySymbol: "SAR",
+    decimalSeparator: ".",
+    thousandsSeparator: ",",
+    currencyPosition: "after"
+  }
+] as const;
+
+const stringTables: Record<string, StringTable> = {
+  "en-US": {
+    "editor.title": "Aura3D Editor",
+    "assets.count.one": "{count} imported asset",
+    "assets.count.other": "{count} imported assets",
+    "status.saved": "Saved",
+    "panel.inspector": "Inspector"
+  },
+  "es-ES": {
+    "editor.title": "Editor Aura3D",
+    "assets.count.one": "{count} recurso importado",
+    "assets.count.other": "{count} recursos importados",
+    "status.saved": "Guardado"
+  },
+  "ar-SA": {
+    "editor.title": "Aura3D RTL Editor",
+    "assets.count.zero": "no imported assets",
+    "assets.count.one": "{count} imported asset",
+    "assets.count.two": "{count} imported assets",
+    "assets.count.few": "{count} imported assets",
+    "assets.count.many": "{count} imported assets",
+    "assets.count.other": "{count} imported assets",
+    "status.saved": "Saved RTL"
+  }
+};
+
+const accessibilityElements: readonly EditorAccessibilityElementSample[] = [
+  createAccessibilityElement("command-menu", "navigation", "Command menu", 1, "#f7fafc", "#101820"),
+  createAccessibilityElement("viewport", "status", "Editor WebGL viewport", 2, "#f5f7fb", "#07111c", "polite"),
+  createAccessibilityElement("inspector-name", "textbox", "Selected node name", 3, "#111827", "#f9fafb"),
+  createAccessibilityElement("timeline-scrub", "slider", "Timeline scrub time", 4, "#0f172a", "#e0f2fe"),
+  createAccessibilityElement("export-project", "button", "Export Project", 5, "#ffffff", "#1d4ed8")
+];
+
+export function sampleLocalizationAccessibilityFixture(options: {
+  readonly assetCount?: number;
+  readonly hotSwapFrom?: string;
+  readonly hotSwapTo?: string;
+} = {}): EditorLocalizationAccessibilityFixture {
+  const assetCount = Math.max(0, Math.floor(options.assetCount ?? 2));
+  const hotSwapFrom = options.hotSwapFrom ?? "en-US";
+  const hotSwapTo = options.hotSwapTo ?? "ar-SA";
+  const fromLocale = requireLocale(hotSwapFrom);
+  const toLocale = requireLocale(hotSwapTo);
+  const listenerNotifications = [fromLocale.code, toLocale.code];
+  const samples = locales.map((locale) => sampleLocale(locale, assetCount));
+  const missingKeys = findMissingKeys(stringTables["en-US"] ?? {}, stringTables["es-ES"] ?? {});
+  const focusOrder = accessibilityElements
+    .filter((element) => element.focusable && !element.disabled)
+    .sort((left, right) => left.tabIndex - right.tabIndex)
+    .map((element) => element.id);
+  const focusWalk = [focusOrder[0], focusOrder[1], focusOrder[2], focusOrder[1]].filter((id): id is string => Boolean(id));
+  const minContrastRatio = Math.min(...accessibilityElements.map((element) => element.contrastRatio));
+  const fixtureWithoutHash = {
+    source: "origin-master-localization-ui-accessibility-adapted" as const,
+    sourceFiles,
+    localeCount: locales.length,
+    rtlLocaleCount: locales.filter((locale) => locale.direction === "rtl").length,
+    tableKeyCount: Object.values(stringTables).reduce((sum, table) => sum + Object.keys(table).length, 0),
+    jsonLoaderValidated: validateJsonTableShape(stringTables),
+    csvLoaderValidated: validateCsvTableShape(toCsv(stringTables)),
+    hotSwapLocale: {
+      from: fromLocale.code,
+      to: toLocale.code,
+      directionChanged: fromLocale.direction !== toLocale.direction,
+      listenerNotifications
+    },
+    samples,
+    missingKeys,
+    accessibility: {
+      elementCount: accessibilityElements.length,
+      labelledControls: accessibilityElements.filter((element) => element.label.trim().length > 0).length,
+      focusOrder,
+      focusWalk,
+      liveRegionAnnouncements: ["Focused: Command menu", "Focused: Editor WebGL viewport", "Saved"],
+      highContrastMode: true,
+      minContrastRatio,
+      aaContrastPasses: accessibilityElements.every((element) => element.contrastPassesAA)
+    },
+    blockedClaims,
+    claimBoundary: "This fixture ports bounded old localization and UI accessibility concepts into deterministic editor-runtime evidence. It does not certify WCAG compliance, native assistive technology behavior, ICU parity, or Unity/Unreal UI parity."
+  };
+  return {
+    ...fixtureWithoutHash,
+    hash: stableHash(JSON.stringify(fixtureWithoutHash))
+  };
+}
+
+function sampleLocale(locale: EditorLocaleDescriptor, assetCount: number): EditorLocalizedStringSample {
+  const pluralCategory = cardinalPluralCategory(locale.code, assetCount);
+  const table = stringTables[locale.code] ?? {};
+  const fallback = stringTables["en-US"] ?? {};
+  return {
+    locale: locale.code,
+    direction: locale.direction,
+    title: lookup(table, fallback, "editor.title", {}),
+    assetCount: lookup(table, fallback, `assets.count.${pluralCategory}`, { count: assetCount }),
+    fallbackTitle: lookup(table, fallback, "panel.inspector", {}),
+    missingKey: lookup(table, fallback, "missing.key", {}),
+    formattedNumber: formatNumber(locale, 1234.5, 2),
+    formattedCurrency: formatCurrency(locale, 1234.5),
+    pluralCategory
+  };
+}
+
+function lookup(table: StringTable, fallback: StringTable, key: string, params: Record<string, number | string>): string {
+  const template = table[key] ?? fallback[key];
+  if (!template) return `[${key}]`;
+  return template.replace(/\{([^}]+)\}/g, (match, name) => String(params[name] ?? match));
+}
+
+function cardinalPluralCategory(localeCode: string, count: number): EditorPluralCategory {
+  const language = localeCode.split("-")[0] ?? localeCode;
+  if (language === "ar") {
+    if (count === 0) return "zero";
+    if (count === 1) return "one";
+    if (count === 2) return "two";
+    if (count % 100 >= 3 && count % 100 <= 10) return "few";
+    if (count % 100 >= 11 && count % 100 <= 99) return "many";
+    return "other";
+  }
+  return count === 1 ? "one" : "other";
+}
+
+function formatNumber(locale: EditorLocaleDescriptor, value: number, decimals: number): string {
+  const fixed = value.toFixed(decimals);
+  const [integer = "0", decimal = ""] = fixed.split(".");
+  const grouped = integer.replace(/\B(?=(\d{3})+(?!\d))/g, locale.thousandsSeparator);
+  return decimal.length > 0 ? `${grouped}${locale.decimalSeparator}${decimal}` : grouped;
+}
+
+function formatCurrency(locale: EditorLocaleDescriptor, value: number): string {
+  const formatted = formatNumber(locale, value, 2);
+  return locale.currencyPosition === "before" ? `${locale.currencySymbol}${formatted}` : `${formatted} ${locale.currencySymbol}`;
+}
+
+function findMissingKeys(reference: StringTable, target: StringTable): readonly string[] {
+  return Object.keys(reference).filter((key) => target[key] === undefined).sort();
+}
+
+function requireLocale(code: string): EditorLocaleDescriptor {
+  const locale = locales.find((candidate) => candidate.code === code);
+  if (!locale) throw new Error(`Unknown editor locale fixture: ${code}`);
+  return locale;
+}
+
+function validateJsonTableShape(tables: Record<string, StringTable>): boolean {
+  return Object.values(tables).every((table) => Object.values(table).every((value) => typeof value === "string" && value.length > 0));
+}
+
+function validateCsvTableShape(csv: string): boolean {
+  const rows = csv.split("\n").filter((line) => line.trim().length > 0);
+  if (rows.length < 2) return false;
+  const expectedColumns = parseCsvLine(rows[0] ?? "").length;
+  return expectedColumns >= 2 && rows.slice(1).every((line) => parseCsvLine(line).length === expectedColumns);
+}
+
+function toCsv(tables: Record<string, StringTable>): string {
+  const localeCodes = Object.keys(tables).sort();
+  const keys = [...new Set(localeCodes.flatMap((locale) => Object.keys(tables[locale] ?? {})))].sort();
+  return [
+    ["Key", ...localeCodes].join(","),
+    ...keys.map((key) => [key, ...localeCodes.map((locale) => escapeCsv(tables[locale]?.[key] ?? ""))].join(","))
+  ].join("\n");
+}
+
+function parseCsvLine(line: string): readonly string[] {
+  const columns: string[] = [];
+  let current = "";
+  let quoted = false;
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index];
+    const next = line[index + 1];
+    if (char === "\"") {
+      if (quoted && next === "\"") {
+        current += "\"";
+        index += 1;
+      } else {
+        quoted = !quoted;
+      }
+    } else if (char === "," && !quoted) {
+      columns.push(current);
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  columns.push(current);
+  return columns;
+}
+
+function escapeCsv(value: string): string {
+  return value.includes(",") || value.includes("\"") || value.includes("\n") ? `"${value.replace(/"/g, "\"\"")}"` : value;
+}
+
+function createAccessibilityElement(
+  id: string,
+  role: EditorAccessibilityRole,
+  label: string,
+  tabIndex: number,
+  foreground: string,
+  background: string,
+  ariaLive?: "polite" | "assertive"
+): EditorAccessibilityElementSample {
+  const contrastRatio = Number(contrast(foreground, background).toFixed(2));
+  return {
+    id,
+    role,
+    label,
+    tabIndex,
+    focusable: true,
+    ...(ariaLive ? { ariaLive } : {}),
+    contrastRatio,
+    contrastPassesAA: contrastRatio >= 4.5
+  };
+}
+
+function contrast(foreground: string, background: string): number {
+  const foregroundLum = luminance(hexToRgb(foreground));
+  const backgroundLum = luminance(hexToRgb(background));
+  const light = Math.max(foregroundLum, backgroundLum);
+  const dark = Math.min(foregroundLum, backgroundLum);
+  return (light + 0.05) / (dark + 0.05);
+}
+
+function hexToRgb(hex: string): readonly [number, number, number] {
+  const normalized = hex.replace("#", "");
+  return [
+    Number.parseInt(normalized.slice(0, 2), 16) / 255,
+    Number.parseInt(normalized.slice(2, 4), 16) / 255,
+    Number.parseInt(normalized.slice(4, 6), 16) / 255
+  ];
+}
+
+function luminance(rgb: readonly [number, number, number]): number {
+  const [r, g, b] = rgb.map((channel) => channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * (r ?? 0) + 0.7152 * (g ?? 0) + 0.0722 * (b ?? 0);
+}
+
+function stableHash(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}

package/src/MaterialVariantWorkflow.ts

@@ -0,0 +1,101 @@
+export interface MaterialVariantState {
+  readonly assetId: string;
+  readonly variants: readonly string[];
+  readonly selected: string | null;
+}
+
+export interface MaterialVariantRenderOptions {
+  readonly materialVariant?: string;
+}
+
+export class MaterialVariantWorkflow {
+  private readonly states = new Map<string, MaterialVariantState>();
+
+  register(assetId: string, variants: readonly string[], selected: string | null = null): MaterialVariantState {
+    const normalizedAssetId = normalizeAssetId(assetId);
+    const normalizedVariants = normalizeVariants(variants);
+    const normalizedSelected = selected === null ? null : normalizeVariantName(selected);
+    if (normalizedSelected !== null && !normalizedVariants.includes(normalizedSelected)) {
+      throw new Error(`Material variant ${normalizedSelected} is not available for asset ${normalizedAssetId}.`);
+    }
+    const state = {
+      assetId: normalizedAssetId,
+      variants: normalizedVariants,
+      selected: normalizedSelected
+    };
+    this.states.set(normalizedAssetId, state);
+    return state;
+  }
+
+  unregister(assetId: string): void {
+    this.states.delete(normalizeAssetId(assetId));
+  }
+
+  select(assetId: string, variant: string | null): MaterialVariantState {
+    const normalizedAssetId = normalizeAssetId(assetId);
+    const state = this.states.get(normalizedAssetId);
+    if (!state) {
+      throw new Error(`Material variant asset ${normalizedAssetId} is not registered.`);
+    }
+    const selected = variant === null ? null : normalizeVariantName(variant);
+    if (selected !== null && !state.variants.includes(selected)) {
+      throw new Error(`Material variant ${selected} is not available for asset ${normalizedAssetId}.`);
+    }
+    const next = { ...state, selected };
+    this.states.set(normalizedAssetId, next);
+    return next;
+  }
+
+  state(assetId: string): MaterialVariantState {
+    const normalizedAssetId = normalizeAssetId(assetId);
+    const state = this.states.get(normalizedAssetId);
+    if (!state) {
+      throw new Error(`Material variant asset ${normalizedAssetId} is not registered.`);
+    }
+    return state;
+  }
+
+  snapshot(): readonly MaterialVariantState[] {
+    return [...this.states.values()].map((state) => ({
+      assetId: state.assetId,
+      variants: [...state.variants],
+      selected: state.selected
+    }));
+  }
+
+  renderOptions(assetId: string): MaterialVariantRenderOptions {
+    const selected = this.state(assetId).selected;
+    return selected === null ? {} : { materialVariant: selected };
+  }
+
+  clear(): void {
+    this.states.clear();
+  }
+}
+
+function normalizeAssetId(assetId: string): string {
+  const normalized = assetId.trim();
+  if (normalized.length === 0) {
+    throw new Error("Material variant asset id cannot be empty.");
+  }
+  return normalized;
+}
+
+function normalizeVariantName(variant: string): string {
+  const normalized = variant.trim();
+  if (normalized.length === 0) {
+    throw new Error("Material variant name cannot be empty.");
+  }
+  return normalized;
+}
+
+function normalizeVariants(variants: readonly string[]): readonly string[] {
+  if (variants.length === 0) {
+    throw new Error("Material variant list cannot be empty.");
+  }
+  const normalized = variants.map(normalizeVariantName);
+  if (new Set(normalized).size !== normalized.length) {
+    throw new Error("Material variant list cannot contain duplicate names.");
+  }
+  return normalized;
+}

package/src/PickingService.ts

@@ -0,0 +1,174 @@
+import type { Ray } from "@aura3d/math";
+import type { SceneNode } from "@aura3d/scene";
+
+type Tuple3 = readonly [number, number, number];
+
+export interface EditorPickTarget {
+  readonly id: string;
+  readonly node: SceneNode;
+  readonly bounds: {
+    readonly min: Tuple3;
+    readonly max: Tuple3;
+  };
+}
+
+export interface EditorPickHit {
+  readonly target: EditorPickTarget;
+  readonly distance: number;
+}
+
+export interface EditorPickingColorId {
+  readonly targetId: string;
+  readonly encodedId: number;
+  readonly color: readonly [number, number, number, number];
+}
+
+export interface EditorPickingEvidenceSnapshot {
+  readonly source: "origin-master-gpu-picking-adapted";
+  readonly registeredTargetCount: number;
+  readonly width: number;
+  readonly height: number;
+  readonly needsUpdate: boolean;
+  readonly idCapacity: number;
+  readonly sampleColorId: EditorPickingColorId | null;
+  readonly decodedSampleTargetId: string | null;
+  readonly colorIds: readonly EditorPickingColorId[];
+  readonly evidence: {
+    readonly colorIdEncoding: boolean;
+    readonly colorIdDecoding: boolean;
+    readonly framebufferResizeBoundary: boolean;
+    readonly raycastFallback: boolean;
+  };
+  readonly blockedClaims: readonly string[];
+}
+
+export class PickingService {
+  private readonly targets = new Map<string, EditorPickTarget>();
+  private width = 1024;
+  private height = 768;
+  private needsUpdate = true;
+
+  setTargets(targets: readonly EditorPickTarget[]): void {
+    this.targets.clear();
+    for (const target of targets) {
+      this.targets.set(target.id, target);
+    }
+    this.needsUpdate = true;
+  }
+
+  addTarget(target: EditorPickTarget): void {
+    this.targets.set(target.id, target);
+    this.needsUpdate = true;
+  }
+
+  removeTarget(id: string): void {
+    this.targets.delete(id);
+    this.needsUpdate = true;
+  }
+
+  pick(ray: Ray): EditorPickHit | undefined {
+    const hit = [...this.targets.values()]
+      .map((target) => ({ target, distance: intersectBounds(ray, target.bounds) }))
+      .filter((hit): hit is EditorPickHit => hit.distance !== undefined)
+      .sort((a, b) => a.distance - b.distance)[0];
+    this.needsUpdate = false;
+    return hit;
+  }
+
+  resizePickingBuffer(width: number, height: number): void {
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
+      throw new RangeError("Picking buffer dimensions must be positive integers.");
+    }
+    this.width = width;
+    this.height = height;
+    this.needsUpdate = true;
+  }
+
+  invalidatePickingBuffer(): void {
+    this.needsUpdate = true;
+  }
+
+  colorIdForTarget(targetId: string): EditorPickingColorId | undefined {
+    const ids = this.colorIds();
+    return ids.find((entry) => entry.targetId === targetId);
+  }
+
+  targetIdFromColor(color: readonly [number, number, number] | readonly [number, number, number, number]): string | undefined {
+    const encodedId = PickingService.colorToId(color[0] ?? 0, color[1] ?? 0, color[2] ?? 0);
+    const entry = this.colorIds().find((candidate) => candidate.encodedId === encodedId);
+    return entry?.targetId;
+  }
+
+  snapshot(): EditorPickingEvidenceSnapshot {
+    const colorIds = this.colorIds();
+    const sampleColorId = colorIds[0] ?? null;
+    const decodedSampleTargetId = sampleColorId ? this.targetIdFromColor(sampleColorId.color) ?? null : null;
+    return {
+      source: "origin-master-gpu-picking-adapted",
+      registeredTargetCount: this.targets.size,
+      width: this.width,
+      height: this.height,
+      needsUpdate: this.needsUpdate,
+      idCapacity: 0xffffff,
+      sampleColorId,
+      decodedSampleTargetId,
+      colorIds,
+      evidence: {
+        colorIdEncoding: colorIds.every((entry) => entry.color[3] === 255 && entry.encodedId >= 1),
+        colorIdDecoding: sampleColorId !== null && decodedSampleTargetId === sampleColorId.targetId,
+        framebufferResizeBoundary: this.width > 0 && this.height > 0,
+        raycastFallback: true
+      },
+      blockedClaims: [
+        "production GPU framebuffer picking pass",
+        "depth-buffer world-position reconstruction",
+        "GPU picking performance parity with Unity Scene View",
+        "GPU picking performance parity with Unreal Editor viewport"
+      ]
+    };
+  }
+
+  static idToColor(id: number): readonly [number, number, number, number] {
+    if (!Number.isInteger(id) || id < 1 || id > 0xffffff) {
+      throw new RangeError("Picking color id must be an integer in the 1..16777215 range.");
+    }
+    return [id & 0xff, (id >> 8) & 0xff, (id >> 16) & 0xff, 255];
+  }
+
+  static colorToId(red: number, green: number, blue: number): number {
+    return (red & 0xff) | ((green & 0xff) << 8) | ((blue & 0xff) << 16);
+  }
+
+  private colorIds(): readonly EditorPickingColorId[] {
+    return [...this.targets.keys()].map((targetId, index) => {
+      const encodedId = index + 1;
+      return { targetId, encodedId, color: PickingService.idToColor(encodedId) };
+    });
+  }
+}
+
+function intersectBounds(ray: Ray, bounds: EditorPickTarget["bounds"]): number | undefined {
+  let tmin = Number.NEGATIVE_INFINITY;
+  let tmax = Number.POSITIVE_INFINITY;
+
+  for (const axis of [0, 1, 2] as const) {
+    const origin = axis === 0 ? ray.origin.x : axis === 1 ? ray.origin.y : ray.origin.z;
+    const direction = axis === 0 ? ray.direction.x : axis === 1 ? ray.direction.y : ray.direction.z;
+    const min = bounds.min[axis];
+    const max = bounds.max[axis];
+    if (Math.abs(direction) < 1e-8) {
+      if (origin < min || origin > max) return undefined;
+      continue;
+    }
+    const invD = 1 / direction;
+    let near = (min - origin) * invD;
+    let far = (max - origin) * invD;
+    if (near > far) [near, far] = [far, near];
+    tmin = Math.max(tmin, near);
+    tmax = Math.min(tmax, far);
+    if (tmin > tmax) return undefined;
+  }
+
+  const distance = tmin >= 0 ? tmin : tmax;
+  return distance >= 0 ? distance : undefined;
+}

package/src/PlayModeBridge.ts

@@ -0,0 +1,27 @@
+export interface SnapshotAdapter<T> {
+  capture(): T;
+  restore(snapshot: T): void;
+}
+
+export class PlayModeBridge<TSnapshot> {
+  private snapshot?: TSnapshot;
+
+  constructor(private readonly adapter: SnapshotAdapter<TSnapshot>) {}
+
+  enter(): void {
+    if (this.snapshot !== undefined) {
+      throw new Error("Play mode is already active");
+    }
+    this.snapshot = this.adapter.capture();
+  }
+
+  exit({ restore = true } = {}): void {
+    if (this.snapshot === undefined) {
+      return;
+    }
+    if (restore) {
+      this.adapter.restore(this.snapshot);
+    }
+    this.snapshot = undefined;
+  }
+}