@forgeax/engine-app 0.0.0-dev.8d955ade1c79

package/src/internal/component-introspection.ts

@@ -0,0 +1,116 @@
+import { type Component, componentDefinition, type FieldReflection } from '@forgeax/engine-ecs';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export interface ComponentIntrospectionField {
+  readonly type: string;
+  readonly default?: JsonValue;
+  readonly shape?: string;
+  readonly transient?: boolean;
+  readonly arrayMeta?: {
+    readonly elementType: string;
+    readonly length?: number;
+  };
+  readonly labels?: Readonly<Record<string, number>>;
+}
+
+export interface ComponentIntrospectionDescriptor {
+  readonly name: string;
+  readonly schema: Readonly<Record<string, string>>;
+  readonly fields: Readonly<Record<string, ComponentIntrospectionField>>;
+  readonly meta: Readonly<Record<string, JsonValue>>;
+}
+
+function projectJson(value: unknown, seen: Set<object>): JsonValue | undefined {
+  if (value === null) return null;
+  if (typeof value === 'boolean' || typeof value === 'string') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+  if (typeof value !== 'object') return undefined;
+  if (seen.has(value)) return undefined;
+  seen.add(value);
+
+  if (ArrayBuffer.isView(value)) {
+    const values = Array.from(value as unknown as ArrayLike<unknown>);
+    const projected = values.map((entry) => projectJson(entry, seen));
+    seen.delete(value);
+    return projected.every((entry) => entry !== undefined) ? (projected as JsonValue[]) : undefined;
+  }
+  if (Array.isArray(value)) {
+    const projected = value.map((entry) => projectJson(entry, seen));
+    seen.delete(value);
+    return projected.every((entry) => entry !== undefined) ? (projected as JsonValue[]) : undefined;
+  }
+
+  const object: Record<string, JsonValue> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const projected = projectJson(entry, seen);
+    if (projected !== undefined) object[key] = projected;
+  }
+  seen.delete(value);
+  return object;
+}
+
+function isJsonRecord(
+  value: JsonValue | undefined,
+): value is { readonly [key: string]: JsonValue } {
+  return (
+    value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value)
+  );
+}
+
+function projectMeta(meta: Readonly<Record<string, unknown>>): Readonly<Record<string, JsonValue>> {
+  const projected = projectJson(meta, new Set<object>());
+  return isJsonRecord(projected) ? projected : {};
+}
+
+function projectField(reflection: FieldReflection): ComponentIntrospectionField {
+  const field: ComponentIntrospectionField = { type: reflection.type };
+  const defaultValue = projectJson(reflection.default, new Set<object>());
+  if (defaultValue !== undefined) Object.assign(field, { default: defaultValue });
+  if (reflection.shape !== undefined) Object.assign(field, { shape: reflection.shape });
+  if (reflection.transient !== undefined) Object.assign(field, { transient: reflection.transient });
+  if (reflection.arrayMeta !== undefined) {
+    Object.assign(field, {
+      arrayMeta: {
+        elementType: reflection.arrayMeta.elementType,
+        ...(reflection.arrayMeta.length !== undefined
+          ? { length: reflection.arrayMeta.length }
+          : {}),
+      },
+    });
+  }
+  if (reflection.labels !== undefined) Object.assign(field, { labels: { ...reflection.labels } });
+  return Object.freeze(field);
+}
+
+function projectComponent(component: Component): ComponentIntrospectionDescriptor {
+  const definition = componentDefinition(component);
+  const fields: Record<string, ComponentIntrospectionField> = {};
+  for (const [name, reflection] of Object.entries(definition.fields)) {
+    fields[name] = projectField(reflection);
+  }
+  return Object.freeze({
+    name: component.name,
+    schema: Object.freeze({ ...componentSchema(component) }),
+    fields: Object.freeze(fields),
+    meta: Object.freeze(projectMeta(definition.policy.meta)),
+  });
+}
+
+/** Project one World-local component catalog into transport-safe data. */
+export function projectComponentIntrospection(
+  components: ReadonlyMap<string, Component>,
+): readonly ComponentIntrospectionDescriptor[] {
+  return Object.freeze(
+    [...components.values()]
+      .sort((left, right) => left.name.localeCompare(right.name))
+      .map(projectComponent),
+  );
+}

package/src/internal/debug-draw.ts

@@ -0,0 +1,38 @@
+import type { DebugDraw } from '@forgeax/engine-debug-draw';
+import { createDebugDraw } from '@forgeax/engine-debug-draw';
+import type { RendererHostAssembly } from '@forgeax/engine-render/internal/construct-renderer';
+import type { TextureFormat } from '@forgeax/engine-rhi';
+import { selectSwapChainFormat } from '../../../render/src/record/render-context';
+
+export type RendererDebugDrawHost = Pick<
+  RendererHostAssembly['debugDrawHost'],
+  'initialization' | 'device' | '_internal_createShaderModule' | '_internal_setRenderOverlay'
+>;
+
+/** Create the App-owned debug overlay after the renderer has initialized. */
+export async function createDebugDrawOnReady(
+  context: RendererDebugDrawHost,
+  format?: TextureFormat,
+): Promise<DebugDraw> {
+  const ready = await context.initialization;
+  if (!ready.ok) throw ready.error;
+
+  const resolvedFormat =
+    format ??
+    (selectSwapChainFormat(context.device.caps.storageBuffer).view as unknown as TextureFormat);
+  const result = await createDebugDraw({
+    device: context.device,
+    queue: context.device.queue,
+    createShaderModule: context._internal_createShaderModule,
+    format: resolvedFormat,
+  });
+  if (!result.ok) throw result.error;
+  context._internal_setRenderOverlay(result.value);
+  return result.value;
+}
+
+/** Release the App-owned debug overlay and clear its Render capability. */
+export function releaseDebugDraw(context: RendererDebugDrawHost, debugDraw: DebugDraw): void {
+  context._internal_setRenderOverlay(undefined);
+  debugDraw.destroy();
+}

package/src/internal/ecs-import.ts

@@ -0,0 +1,41 @@
+// @forgeax/engine-app/internal/ecs-import — host-owned capability projection.
+//
+// The remote transport deliberately has no engine-package vocabulary. Hosts
+// that expose ECS to eval inject this narrow projection at the transport seam,
+// keeping the ECS wire surface and its dependency ownership in one place.
+
+const ECS_MODULE_SPECIFIER = '@forgeax/engine-ecs';
+
+export const ECS_PUBLIC_SYMBOLS = Object.freeze([
+  'World',
+  'Entity',
+  'Update',
+  'FixedUpdate',
+  'Time',
+  'FixedTime',
+] as const);
+
+export type EcsPublicSymbol = (typeof ECS_PUBLIC_SYMBOLS)[number];
+export type EcsPublicModule = Readonly<Partial<Record<EcsPublicSymbol, unknown>>>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object';
+}
+
+export function projectEcsPublicModule(value: unknown): EcsPublicModule {
+  if (!isRecord(value)) return {};
+  const projected: Record<string, unknown> = {};
+  for (const symbol of ECS_PUBLIC_SYMBOLS) {
+    if (symbol in value) projected[symbol] = value[symbol];
+  }
+  return projected;
+}
+
+export function createEcsImportModule(
+  importModule: (specifier: string) => Promise<unknown>,
+): (specifier: string) => Promise<unknown> {
+  return async (specifier: string): Promise<unknown> => {
+    const moduleValue = await importModule(specifier);
+    return specifier === ECS_MODULE_SPECIFIER ? projectEcsPublicModule(moduleValue) : moduleValue;
+  };
+}

package/src/internal/engine-profile-common.ts

@@ -0,0 +1,9 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { Plugin } from '@forgeax/engine-plugin';
+import type { Renderer } from '@forgeax/engine-render';
+
+export interface EngineProfileBase {
+  readonly renderer: Renderer;
+  readonly assets?: AssetRegistry;
+  readonly extensions?: readonly Plugin[];
+}

package/src/internal/error-fanout.ts

@@ -0,0 +1,129 @@
+// @forgeax/engine-app -- error fan-out registry + console.error fallback (M4 / w11).
+//
+// Public surface (consumed only by createApp + frame-loop -- this module
+// lives under `internal/` and is not re-exported from the package barrel):
+//
+//   const fan = new ErrorFanoutRegistry({ silenceUnhandledErrors: false });
+//   const off = fan.add(cb);    // add listener; returns idempotent unsubscribe
+//   off();                      // remove listener (safe to call twice)
+//   fan.fire(err);              // fan out to all listeners; if none AND
+//                               // silenceUnhandledErrors !== true, call
+//                               // console.error(err)
+//
+// Wiring (per plan-strategy D-9 + research section 7.3
+// createRenderer.ts:532-566 LostListenerRegistry side-evidence):
+//
+//   - Listener set is a Set so duplicate add() is idempotent (set semantics).
+//   - fire() iterates over a snapshot so a listener that calls .add()/.remove()
+//     mid-fire does not perturb the iteration.
+//   - When the listener set is empty AND silenceUnhandledErrors !== true,
+//     console.error(err) is invoked once with the structured error object as
+//     the single argument. Tests pin reference equality via mock.calls[0][0]
+//     so the AI-user contract (.code / .expected / .hint structure preserved)
+//     is observable in browser devtools.
+//   - late-attach replay is deliberately NOT implemented. rAF errors are
+//     frame-time stream (each tick generates a fresh event); a replay
+//     semantic would surface stale state to a freshly registered listener.
+//     This is a deliberate divergence from runtime/createRenderer.ts:337-345
+//     LostListenerRegistry which DOES replay (because device.lost is a
+//     one-shot lifecycle event); see plan-strategy D-9 for the divergence
+//     rationale.
+//
+// Architecture principle SSOT: the listener set + the silence flag are the
+// only state owned by this module; createApp passes the silence flag in via
+// constructor options and never reads it again, so the SSOT is the Registry
+// instance state.
+
+import type { AppDispatchError } from '../types';
+
+/**
+ * Listener callback for app-shell error fan-out.
+ *
+ * The narrow union (`AppDispatchError` = AppError | RhiError | RuntimeError)
+ * deliberately excludes raw `Error` (charter P3 explicit failure: AI users
+ * walk `.code` not message strings). `RuntimeError` is included so a
+ * runtime-layer error fanned out by `Renderer.onError` (e.g.
+ * `'equirect-projection-failed'`) reaches host App listeners verbatim
+ * (feat-20260531-skybox-env-background F-1). `EngineEnvironmentError` does not
+ * appear here because construction-time failure flows through
+ * `Promise<Result<App, ...>>` of `createApp(canvas)` before the App handle
+ * exists; once an App handle is alive, only frame-time errors (this union)
+ * reach onError.
+ */
+export type ErrorFanoutListener = (err: AppDispatchError) => void;
+
+/**
+ * Constructor options for ErrorFanoutRegistry. Mirrors the
+ * `silenceUnhandledErrors` field on CreateAppOptions / AppAssembleArgs;
+ * createApp threads the field down into the registry verbatim.
+ */
+export interface ErrorFanoutOptions {
+  readonly silenceUnhandledErrors?: boolean;
+}
+
+/**
+ * ErrorFanoutRegistry shares its shape with the LostListenerRegistry
+ * implementation in `packages/runtime/src/createRenderer.ts:532-566` per
+ * plan-strategy D-9 -- listener set + fan-out fire + idempotent unsubscribe.
+ * The two divergences from the runtime registry are intentional:
+ *
+ *   1. Late-attach replay is NOT implemented -- rAF errors are a frame-time
+ *      stream (each tick produces fresh state) so replay semantics are
+ *      meaningless and would mislead newly registered listeners.
+ *   2. `console.error(err)` fallback fires when the listener set is empty
+ *      and `silenceUnhandledErrors !== true` -- a charter P3 tribute that
+ *      makes "unhandled" errors loud rather than silent.
+ */
+export class ErrorFanoutRegistry {
+  private readonly listeners: Set<ErrorFanoutListener> = new Set();
+  private readonly silenceUnhandledErrors: boolean;
+
+  constructor(opts: ErrorFanoutOptions = {}) {
+    this.silenceUnhandledErrors = opts.silenceUnhandledErrors === true;
+  }
+
+  /**
+   * Register a listener. Returns an unsubscribe function. Calling
+   * unsubscribe more than once is a safe no-op (Set.delete returns
+   * false on the second call but does not throw). Re-registering the
+   * same listener function is a no-op (Set semantics).
+   */
+  add(cb: ErrorFanoutListener): () => void {
+    this.listeners.add(cb);
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+
+  /**
+   * Iterate over a snapshot of the listener set so a listener that
+   * mutates the set mid-fire does not perturb the iteration. When the
+   * set is empty AND silenceUnhandledErrors !== true, call
+   * console.error(err) so the unhandled error is visible in devtools
+   * (charter P3 explicit failure: silent drop is a footgun).
+   */
+  fire(err: AppDispatchError): void {
+    if (this.listeners.size === 0) {
+      if (!this.silenceUnhandledErrors) {
+        // eslint-disable-next-line no-console -- charter P3 fallback
+        console.error(err);
+      }
+      return;
+    }
+    const snapshot = Array.from(this.listeners);
+    for (const cb of snapshot) {
+      cb(err);
+    }
+  }
+
+  /**
+   * Number of currently registered listeners. Reserved for diagnostics +
+   * test fixtures (e.g. asserting cleanup paths reach the registry); not
+   * part of the public app-shell surface.
+   *
+   * @internal
+   */
+  _size(): number {
+    return this.listeners.size;
+  }
+}