@hla4ts/spacekit 0.1.0 → 0.1.1

package/src/see-app.ts

@@ -1,460 +1,460 @@
-import { CallbackModel, encodeHLAinteger64Time, type LogicalTime } from "@hla4ts/hla-api";
-import {
-  buildDeclarativeFomFromDecorators,
-  registerDecoratedClasses,
-  type FomClassConstructor,
-} from "./decorators.ts";
-import { SpacekitApp as BaseSpacekitApp, type SpacekitAppConfig as BaseSpacekitAppConfig } from "./app.ts";
-import { parseSpacekitEnv, type LogLevel, type SpacekitEnvDefaults, type SpacekitLogger } from "./env.ts";
-import type { SpacekitEntity } from "./entity.ts";
-import { createConsoleLogger } from "./logger.ts";
-import { DynamicalEntity, ExecutionConfiguration, PhysicalEntity, ReferenceFrame } from "./spacefom-entities.ts";
-import { ModeTransitionRequest } from "./spacefom-interactions.ts";
-import { SpaceFomLateJoinerBootstrap, type SpaceFomBootstrapState } from "./spacefom-bootstrap.ts";
-
-export type MissingReferenceFrameMode = "error" | "continue";
-
-export interface SpacekitAppOptions {
-  federationName?: string;
-  federateName?: string;
-  federateType?: string;
-  rtiHost?: string;
-  rtiPort?: number;
-  rtiUseTls?: boolean;
-  lookaheadMicros?: bigint;
-  updatePeriodMicros?: bigint;
-  referenceFrameTimeoutMs?: number;
-  logLevel?: LogLevel;
-  logEveryN?: number;
-  debug?: boolean;
-  logStartup?: boolean;
-  logBootstrap?: boolean;
-  enableGracefulShutdown?: boolean;
-  callbackModel?: CallbackModel;
-  logger?: SpacekitLogger;
-  env?: Record<string, string | undefined>;
-  envDefaults?: SpacekitEnvDefaults;
-  bootstrap?: SpaceFomLateJoinerBootstrap;
-  waitForReferenceFrameTree?: boolean;
-  autoWaitForReferenceFrame?: boolean;
-  missingReferenceFrameMode?: MissingReferenceFrameMode;
-  declarative?: BaseSpacekitAppConfig["declarative"];
-  fomExport?: BaseSpacekitAppConfig["fomExport"];
-}
-
-const BASE_OBJECT_CLASSES = new Set<FomClassConstructor>([
-  ExecutionConfiguration,
-  ReferenceFrame,
-  PhysicalEntity,
-  DynamicalEntity,
-]);
-const BASE_INTERACTION_CLASSES = new Set<FomClassConstructor>([ModeTransitionRequest]);
-
-export class SpacekitApp extends BaseSpacekitApp {
-  private _logicalTimeMicros: bigint | null = null;
-  private readonly _lookaheadMicros: bigint;
-  private readonly _updatePeriodMicros: bigint;
-  private readonly _referenceFrameTimeoutMs: number;
-  private readonly _autoWaitForReferenceFrame: boolean;
-  private readonly _missingReferenceFrameMode: MissingReferenceFrameMode;
-  private readonly _referenceFrameGraceMs = 2000;
-  private _referenceFrameFallbackSubscribe = true;
-  private _referenceFrameNameProbe = true;
-  private readonly _logStartup: boolean;
-  private readonly _logBootstrap: boolean;
-  private readonly _logEveryN: number;
-  private readonly _startupInfo: {
-    federationName: string;
-    federateName: string;
-    federateType: string;
-    rtiHost: string;
-    rtiPort: number;
-    rtiUseTls: boolean;
-  };
-  private _bootstrapLogged = false;
-  private _tickCount = 0;
-
-  constructor(options: SpacekitAppOptions = {}) {
-    const env = parseSpacekitEnv({
-      env: options.env,
-      defaults: options.envDefaults ?? {
-        rtiHost: "localhost",
-        rtiPort: 15164,
-        rtiUseTls: false,
-        federationName: "SpaceFederation",
-        federateName: "SpacekitFederate",
-        federateType: "SpacekitFederate",
-        lookaheadMicros: 1_000_000n,
-        updatePeriodMicros: 1_000_000n,
-        referenceFrameTimeoutMs: 30_000,
-        logLevel: "info",
-        logEveryN: 1,
-        debug: false,
-      },
-    });
-
-    const resolved = {
-      ...env,
-      federationName: options.federationName ?? env.federationName,
-      federateName: options.federateName ?? env.federateName,
-      federateType: options.federateType ?? env.federateType,
-      rtiHost: options.rtiHost ?? env.rtiHost,
-      rtiPort: options.rtiPort ?? env.rtiPort,
-      rtiUseTls: options.rtiUseTls ?? env.rtiUseTls,
-      lookaheadMicros: options.lookaheadMicros ?? env.lookaheadMicros,
-      updatePeriodMicros: options.updatePeriodMicros ?? env.updatePeriodMicros,
-      referenceFrameTimeoutMs: options.referenceFrameTimeoutMs ?? env.referenceFrameTimeoutMs,
-      logLevel: options.logLevel ?? env.logLevel,
-      logEveryN: options.logEveryN ?? env.logEveryN,
-      debug: options.debug ?? env.debug,
-    };
-
-    const logger =
-      options.logger ??
-      createConsoleLogger({
-        level: resolved.logLevel,
-        scope: "spacekit",
-      });
-
-    const bootstrap =
-      options.bootstrap ??
-      new SpaceFomLateJoinerBootstrap({
-        lookaheadMicros: resolved.lookaheadMicros,
-        waitForReferenceFrameTree: options.waitForReferenceFrameTree ?? false,
-        referenceFrameTimeoutMs: resolved.referenceFrameTimeoutMs,
-        waitForInitializationCompleted: false,
-        waitForExco: false,
-        advanceToHltb: false,
-      });
-
-    const declarative =
-      options.declarative ??
-      buildDeclarativeFomFromDecorators({
-        objectClasses: [ExecutionConfiguration, ReferenceFrame, PhysicalEntity, DynamicalEntity],
-        interactionClasses: [ModeTransitionRequest],
-        register: false,
-      });
-
-    if (options.declarative) {
-      registerDecoratedClasses(declarative, {
-        objectClasses: [ExecutionConfiguration, ReferenceFrame, PhysicalEntity, DynamicalEntity],
-        interactionClasses: [ModeTransitionRequest],
-        register: false,
-      });
-    }
-
-    super({
-      federate: {
-        rti: { host: resolved.rtiHost, port: resolved.rtiPort, useTls: resolved.rtiUseTls },
-        connection: { callbackModel: options.callbackModel ?? CallbackModel.IMMEDIATE },
-        federationName: resolved.federationName,
-        federateType: resolved.federateType,
-        federateName: resolved.federateName,
-      },
-      bootstrap,
-      declarative,
-      logging: {
-        logger,
-        level: resolved.logLevel,
-        scope: "spacekit",
-      },
-      fomExport: {
-        inferParentStubs: options.fomExport?.inferParentStubs ?? true,
-        ...options.fomExport,
-      },
-    });
-
-    this._lookaheadMicros = resolved.lookaheadMicros;
-    this._updatePeriodMicros = resolved.updatePeriodMicros;
-    this._referenceFrameTimeoutMs = resolved.referenceFrameTimeoutMs;
-    this._autoWaitForReferenceFrame = options.autoWaitForReferenceFrame ?? true;
-    this._missingReferenceFrameMode = options.missingReferenceFrameMode ?? "error";
-    this._logStartup = options.logStartup ?? true;
-    this._logBootstrap = options.logBootstrap ?? true;
-    this._logEveryN = resolved.logEveryN ?? 1;
-    this._startupInfo = {
-      federationName: resolved.federationName,
-      federateName: resolved.federateName,
-      federateType: resolved.federateType,
-      rtiHost: resolved.rtiHost,
-      rtiPort: resolved.rtiPort,
-      rtiUseTls: resolved.rtiUseTls,
-    };
-    if (options.enableGracefulShutdown ?? true) {
-      this.enableGracefulShutdown();
-    }
-  }
-
-  get lookaheadMicros(): bigint {
-    return this._lookaheadMicros;
-  }
-
-  get updatePeriodMicros(): bigint {
-    return this._updatePeriodMicros;
-  }
-
-  get logicalTimeMicros(): bigint | null {
-    return this._logicalTimeMicros;
-  }
-
-  get spacefomState(): SpaceFomBootstrapState | undefined {
-    return this.bootstrapState as SpaceFomBootstrapState | undefined;
-  }
-
-  override async start(): Promise<void> {
-    if (this._logStartup) {
-      this.logger.info("Starting Spacekit SEE app.", {
-        federation: this._startupInfo.federationName,
-        federate: this._startupInfo.federateName,
-        federateType: this._startupInfo.federateType,
-        rti: `${this._startupInfo.rtiHost}:${this._startupInfo.rtiPort}`,
-        tls: this._startupInfo.rtiUseTls,
-      });
-    }
-    await super.start();
-    const state = this.spacefomState;
-    this._logicalTimeMicros = state?.lastGrantedTimeMicros ?? this.currentTimeMicros;
-  }
-
-  async tick(): Promise<bigint> {
-    const base = this._logicalTimeMicros ?? (await this.queryLogicalTimeMicros());
-    const next = base + this._updatePeriodMicros;
-    this._logicalTimeMicros = await this.advanceTo(next);
-    return this._logicalTimeMicros;
-  }
-
-  async run(options: {
-    entities?: SpacekitEntity<object>[];
-    onTick?: (payload: {
-      timeMicros: bigint;
-      sendTimeMicros: bigint | null;
-      timeSeconds: number;
-      deltaSeconds: number;
-      tick: number;
-      initial: boolean;
-    }) => void | Promise<void>;
-    sync?: boolean;
-    throwOnError?: boolean;
-    onError?: (err: unknown) => void;
-  } = {}): Promise<void> {
-    let runError: unknown;
-    const entities = options.entities ?? [];
-    try {
-      if (!this.isStarted) {
-        const registrations = entities.map((entity) => this.registerEntity(entity));
-        await this.start();
-        await Promise.all(registrations);
-      } else if (entities.length > 0) {
-        await this.registerEntities(entities);
-      }
-
-      let tick = 0;
-      this._tickCount = tick;
-      let timeMicros = this.logicalTimeMicros ?? (await this.queryLogicalTimeMicros());
-      const deltaSeconds = Number(this._updatePeriodMicros) / 1_000_000;
-      if (this._logBootstrap && !this._bootstrapLogged) {
-        const state = this.spacefomState;
-        this.logger.info("Spacekit SEE bootstrap complete.", {
-          lastGrantedTimeMicros: state?.lastGrantedTimeMicros?.toString() ?? "unknown",
-          lctsMicros: state?.lctsMicros?.toString() ?? "unknown",
-          rootFrame: state?.rootFrameName ?? "unknown",
-        });
-        this._bootstrapLogged = true;
-      }
-      if (options.onTick) {
-        await options.onTick({
-          timeMicros,
-          sendTimeMicros: this.getSendTimeMicros(timeMicros),
-          timeSeconds: Number(timeMicros) / 1_000_000,
-          deltaSeconds: 0,
-          tick,
-          initial: true,
-        });
-      }
-      if (options.sync !== false && entities.length > 0) {
-        await this.sync(entities);
-      }
-
-      while (!this.isShutdownRequested) {
-        tick += 1;
-        this._tickCount = tick;
-        timeMicros = await this.tick();
-        if (options.onTick) {
-          await options.onTick({
-            timeMicros,
-            sendTimeMicros: this.getSendTimeMicros(timeMicros),
-            timeSeconds: Number(timeMicros) / 1_000_000,
-            deltaSeconds,
-            tick,
-            initial: false,
-          });
-        }
-        if (options.sync !== false && entities.length > 0) {
-          await this.sync(entities);
-        }
-      }
-    } catch (err) {
-      runError = err;
-      this.logger.error("Spacekit SEE run failed.", { error: err });
-      options.onError?.(err);
-      this.requestShutdown("error");
-    } finally {
-      if (this.rtiAmbassador) {
-        try {
-          await this.stop();
-        } catch (err) {
-          this.logger.warn("Spacekit SEE shutdown error.", { error: err });
-        }
-      }
-    }
-
-    if (runError) {
-      process.exitCode = 1;
-      if (options.throwOnError) {
-        throw runError;
-      }
-    }
-  }
-
-  getSendTimeMicros(baseTimeMicros?: bigint): bigint | null {
-    const base = baseTimeMicros ?? this._logicalTimeMicros;
-    if (base === null || base === undefined) return null;
-    return base + this._lookaheadMicros;
-  }
-
-  shouldLog(updateCount: number): boolean {
-    if (!this._logEveryN || this._logEveryN <= 1) return true;
-    return updateCount % this._logEveryN === 0;
-  }
-
-  shouldLogTick(tick: number = this._tickCount): boolean {
-    return this.shouldLog(tick);
-  }
-
-  shouldLogUpdate(record: { updateCount: number }): boolean {
-    return this.shouldLog(record.updateCount);
-  }
-
-  override async syncEntity<T extends object>(
-    entity: SpacekitEntity<T>,
-    time?: LogicalTime | bigint,
-    userSuppliedTag?: Uint8Array
-  ): Promise<void> {
-    if (typeof time === "bigint") {
-      const logicalTime = encodeHLAinteger64Time(time + this._lookaheadMicros);
-      await super.syncEntity(entity, logicalTime, userSuppliedTag);
-      return;
-    }
-    if (!time) {
-      const base = this._logicalTimeMicros ?? (await this.queryLogicalTimeMicros());
-      const logicalTime = encodeHLAinteger64Time(base + this._lookaheadMicros);
-      await super.syncEntity(entity, logicalTime, userSuppliedTag);
-      return;
-    }
-    await super.syncEntity(entity, time, userSuppliedTag);
-  }
-
-  async waitForReferenceFrame(name: string, timeoutMs = this._referenceFrameTimeoutMs): Promise<void> {
-    const start = Date.now();
-    const effectiveTimeoutMs = timeoutMs === 0 ? this._referenceFrameGraceMs : timeoutMs;
-    let lastNames = "";
-    while (true) {
-      const state = this.spacefomState;
-      const frames = state?.referenceFrames ?? [];
-      const names = frames
-        .map((frame) => frame.name)
-        .filter((frameName): frameName is string => !!frameName)
-        .sort()
-        .join(",");
-      if (names && names !== lastNames) {
-        lastNames = names;
-        this.logger.debug("Reference frames discovered.", { names: names.split(",") });
-      }
-      if (frames.some((frame) => frame.name === name)) {
-        return;
-      }
-      if (
-        this._referenceFrameFallbackSubscribe &&
-        effectiveTimeoutMs > 0 &&
-        Date.now() - start > Math.min(effectiveTimeoutMs, 2000)
-      ) {
-        this._referenceFrameFallbackSubscribe = false;
-        await this._subscribeReferenceFrameFallback();
-      }
-      if (
-        this._referenceFrameNameProbe &&
-        effectiveTimeoutMs > 0 &&
-        Date.now() - start > Math.min(effectiveTimeoutMs, 1500)
-      ) {
-        this._referenceFrameNameProbe = false;
-        const found = await this._probeReferenceFrameByName(name);
-        if (found) {
-          this.logger.warn("Reference frame confirmed via name lookup.", { name });
-          return;
-        }
-      }
-      if (effectiveTimeoutMs >= 0 && Date.now() - start > effectiveTimeoutMs) {
-        const error = `Reference frame not discovered: ${name}. Known frames: ${names || "(none)"}`;
-        if (this._missingReferenceFrameMode === "continue") {
-          this.logger.warn("Proceeding without discovered reference frame.", {
-            name,
-            knownFrames: names ? names.split(",") : [],
-            timeoutMs: effectiveTimeoutMs,
-          });
-          return;
-        }
-        throw new Error(error);
-      }
-      await new Promise((resolve) => setTimeout(resolve, 200));
-    }
-  }
-
-  protected override shouldRegisterClassInFom(ctor: Function, kind: "object" | "interaction"): boolean {
-    if (kind === "object" && BASE_OBJECT_CLASSES.has(ctor as FomClassConstructor)) {
-      return false;
-    }
-    if (kind === "interaction" && BASE_INTERACTION_CLASSES.has(ctor as FomClassConstructor)) {
-      return false;
-    }
-    return true;
-  }
-
-  protected override async beforeRegisterEntity<T extends object>(entity: SpacekitEntity<T>): Promise<void> {
-    if (!this._autoWaitForReferenceFrame) return;
-    const parentName =
-      (entity as { parent_reference_frame?: string }).parent_reference_frame ??
-      (entity as { parent_name?: string }).parent_name;
-    if (!parentName) return;
-    await this.waitForReferenceFrame(parentName);
-  }
-
-  private async _subscribeReferenceFrameFallback(): Promise<void> {
-    const rti = this.rtiAmbassador;
-    if (!rti) return;
-    const adapter = this.declarative.getObjectAdapter<ReferenceFrame>(ReferenceFrame.className);
-    if (!adapter) return;
-    if (!adapter.isResolved) {
-      await adapter.resolve(rti);
-    }
-    await adapter.subscribe(rti);
-    this.logger.debug("Retrying ReferenceFrame subscribe fallback.");
-  }
-
-  private async _probeReferenceFrameByName(name: string): Promise<boolean> {
-    const rti = this.rtiAmbassador;
-    if (!rti) return false;
-    try {
-      const handle = await rti.getObjectInstanceHandle(name);
-      if (!handle || handle.length === 0) return false;
-      const adapter = this.declarative.getObjectAdapter<ReferenceFrame>(ReferenceFrame.className);
-      if (!adapter) return true;
-      if (!adapter.isResolved) {
-        await adapter.resolve(rti);
-      }
-      await rti.requestInstanceAttributeValueUpdate(handle, adapter.attributeHandleSet, new Uint8Array());
-      return true;
-    } catch {
-      return false;
-    }
-  }
-}
+import { CallbackModel, encodeHLAinteger64Time, type LogicalTime } from "@hla4ts/hla-api";
+import {
+  buildDeclarativeFomFromDecorators,
+  registerDecoratedClasses,
+  type FomClassConstructor,
+} from "./decorators.ts";
+import { SpacekitApp as BaseSpacekitApp, type SpacekitAppConfig as BaseSpacekitAppConfig } from "./app.ts";
+import { parseSpacekitEnv, type LogLevel, type SpacekitEnvDefaults, type SpacekitLogger } from "./env.ts";
+import type { SpacekitEntity } from "./entity.ts";
+import { createConsoleLogger } from "./logger.ts";
+import { DynamicalEntity, ExecutionConfiguration, PhysicalEntity, ReferenceFrame } from "./spacefom-entities.ts";
+import { ModeTransitionRequest } from "./spacefom-interactions.ts";
+import { SpaceFomLateJoinerBootstrap, type SpaceFomBootstrapState } from "./spacefom-bootstrap.ts";
+
+export type MissingReferenceFrameMode = "error" | "continue";
+
+export interface SpacekitAppOptions {
+  federationName?: string;
+  federateName?: string;
+  federateType?: string;
+  rtiHost?: string;
+  rtiPort?: number;
+  rtiUseTls?: boolean;
+  lookaheadMicros?: bigint;
+  updatePeriodMicros?: bigint;
+  referenceFrameTimeoutMs?: number;
+  logLevel?: LogLevel;
+  logEveryN?: number;
+  debug?: boolean;
+  logStartup?: boolean;
+  logBootstrap?: boolean;
+  enableGracefulShutdown?: boolean;
+  callbackModel?: CallbackModel;
+  logger?: SpacekitLogger;
+  env?: Record<string, string | undefined>;
+  envDefaults?: SpacekitEnvDefaults;
+  bootstrap?: SpaceFomLateJoinerBootstrap;
+  waitForReferenceFrameTree?: boolean;
+  autoWaitForReferenceFrame?: boolean;
+  missingReferenceFrameMode?: MissingReferenceFrameMode;
+  declarative?: BaseSpacekitAppConfig["declarative"];
+  fomExport?: BaseSpacekitAppConfig["fomExport"];
+}
+
+const BASE_OBJECT_CLASSES = new Set<FomClassConstructor>([
+  ExecutionConfiguration,
+  ReferenceFrame,
+  PhysicalEntity,
+  DynamicalEntity,
+]);
+const BASE_INTERACTION_CLASSES = new Set<FomClassConstructor>([ModeTransitionRequest]);
+
+export class SpacekitApp extends BaseSpacekitApp {
+  private _logicalTimeMicros: bigint | null = null;
+  private readonly _lookaheadMicros: bigint;
+  private readonly _updatePeriodMicros: bigint;
+  private readonly _referenceFrameTimeoutMs: number;
+  private readonly _autoWaitForReferenceFrame: boolean;
+  private readonly _missingReferenceFrameMode: MissingReferenceFrameMode;
+  private readonly _referenceFrameGraceMs = 2000;
+  private _referenceFrameFallbackSubscribe = true;
+  private _referenceFrameNameProbe = true;
+  private readonly _logStartup: boolean;
+  private readonly _logBootstrap: boolean;
+  private readonly _logEveryN: number;
+  private readonly _startupInfo: {
+    federationName: string;
+    federateName: string;
+    federateType: string;
+    rtiHost: string;
+    rtiPort: number;
+    rtiUseTls: boolean;
+  };
+  private _bootstrapLogged = false;
+  private _tickCount = 0;
+
+  constructor(options: SpacekitAppOptions = {}) {
+    const env = parseSpacekitEnv({
+      env: options.env,
+      defaults: options.envDefaults ?? {
+        rtiHost: "localhost",
+        rtiPort: 15164,
+        rtiUseTls: false,
+        federationName: "SpaceFederation",
+        federateName: "SpacekitFederate",
+        federateType: "SpacekitFederate",
+        lookaheadMicros: 1_000_000n,
+        updatePeriodMicros: 1_000_000n,
+        referenceFrameTimeoutMs: 30_000,
+        logLevel: "info",
+        logEveryN: 1,
+        debug: false,
+      },
+    });
+
+    const resolved = {
+      ...env,
+      federationName: options.federationName ?? env.federationName,
+      federateName: options.federateName ?? env.federateName,
+      federateType: options.federateType ?? env.federateType,
+      rtiHost: options.rtiHost ?? env.rtiHost,
+      rtiPort: options.rtiPort ?? env.rtiPort,
+      rtiUseTls: options.rtiUseTls ?? env.rtiUseTls,
+      lookaheadMicros: options.lookaheadMicros ?? env.lookaheadMicros,
+      updatePeriodMicros: options.updatePeriodMicros ?? env.updatePeriodMicros,
+      referenceFrameTimeoutMs: options.referenceFrameTimeoutMs ?? env.referenceFrameTimeoutMs,
+      logLevel: options.logLevel ?? env.logLevel,
+      logEveryN: options.logEveryN ?? env.logEveryN,
+      debug: options.debug ?? env.debug,
+    };
+
+    const logger =
+      options.logger ??
+      createConsoleLogger({
+        level: resolved.logLevel,
+        scope: "spacekit",
+      });
+
+    const bootstrap =
+      options.bootstrap ??
+      new SpaceFomLateJoinerBootstrap({
+        lookaheadMicros: resolved.lookaheadMicros,
+        waitForReferenceFrameTree: options.waitForReferenceFrameTree ?? false,
+        referenceFrameTimeoutMs: resolved.referenceFrameTimeoutMs,
+        waitForInitializationCompleted: false,
+        waitForExco: false,
+        advanceToHltb: false,
+      });
+
+    const declarative =
+      options.declarative ??
+      buildDeclarativeFomFromDecorators({
+        objectClasses: [ExecutionConfiguration, ReferenceFrame, PhysicalEntity, DynamicalEntity],
+        interactionClasses: [ModeTransitionRequest],
+        register: false,
+      });
+
+    if (options.declarative) {
+      registerDecoratedClasses(declarative, {
+        objectClasses: [ExecutionConfiguration, ReferenceFrame, PhysicalEntity, DynamicalEntity],
+        interactionClasses: [ModeTransitionRequest],
+        register: false,
+      });
+    }
+
+    super({
+      federate: {
+        rti: { host: resolved.rtiHost, port: resolved.rtiPort, useTls: resolved.rtiUseTls },
+        connection: { callbackModel: options.callbackModel ?? CallbackModel.IMMEDIATE },
+        federationName: resolved.federationName,
+        federateType: resolved.federateType,
+        federateName: resolved.federateName,
+      },
+      bootstrap,
+      declarative,
+      logging: {
+        logger,
+        level: resolved.logLevel,
+        scope: "spacekit",
+      },
+      fomExport: {
+        inferParentStubs: options.fomExport?.inferParentStubs ?? true,
+        ...options.fomExport,
+      },
+    });
+
+    this._lookaheadMicros = resolved.lookaheadMicros;
+    this._updatePeriodMicros = resolved.updatePeriodMicros;
+    this._referenceFrameTimeoutMs = resolved.referenceFrameTimeoutMs;
+    this._autoWaitForReferenceFrame = options.autoWaitForReferenceFrame ?? true;
+    this._missingReferenceFrameMode = options.missingReferenceFrameMode ?? "error";
+    this._logStartup = options.logStartup ?? true;
+    this._logBootstrap = options.logBootstrap ?? true;
+    this._logEveryN = resolved.logEveryN ?? 1;
+    this._startupInfo = {
+      federationName: resolved.federationName,
+      federateName: resolved.federateName,
+      federateType: resolved.federateType,
+      rtiHost: resolved.rtiHost,
+      rtiPort: resolved.rtiPort,
+      rtiUseTls: resolved.rtiUseTls,
+    };
+    if (options.enableGracefulShutdown ?? true) {
+      this.enableGracefulShutdown();
+    }
+  }
+
+  get lookaheadMicros(): bigint {
+    return this._lookaheadMicros;
+  }
+
+  get updatePeriodMicros(): bigint {
+    return this._updatePeriodMicros;
+  }
+
+  get logicalTimeMicros(): bigint | null {
+    return this._logicalTimeMicros;
+  }
+
+  get spacefomState(): SpaceFomBootstrapState | undefined {
+    return this.bootstrapState as SpaceFomBootstrapState | undefined;
+  }
+
+  override async start(): Promise<void> {
+    if (this._logStartup) {
+      this.logger.info("Starting Spacekit SEE app.", {
+        federation: this._startupInfo.federationName,
+        federate: this._startupInfo.federateName,
+        federateType: this._startupInfo.federateType,
+        rti: `${this._startupInfo.rtiHost}:${this._startupInfo.rtiPort}`,
+        tls: this._startupInfo.rtiUseTls,
+      });
+    }
+    await super.start();
+    const state = this.spacefomState;
+    this._logicalTimeMicros = state?.lastGrantedTimeMicros ?? this.currentTimeMicros;
+  }
+
+  async tick(): Promise<bigint> {
+    const base = this._logicalTimeMicros ?? (await this.queryLogicalTimeMicros());
+    const next = base + this._updatePeriodMicros;
+    this._logicalTimeMicros = await this.advanceTo(next);
+    return this._logicalTimeMicros;
+  }
+
+  async run(options: {
+    entities?: SpacekitEntity<object>[];
+    onTick?: (payload: {
+      timeMicros: bigint;
+      sendTimeMicros: bigint | null;
+      timeSeconds: number;
+      deltaSeconds: number;
+      tick: number;
+      initial: boolean;
+    }) => void | Promise<void>;
+    sync?: boolean;
+    throwOnError?: boolean;
+    onError?: (err: unknown) => void;
+  } = {}): Promise<void> {
+    let runError: unknown;
+    const entities = options.entities ?? [];
+    try {
+      if (!this.isStarted) {
+        const registrations = entities.map((entity) => this.registerEntity(entity));
+        await this.start();
+        await Promise.all(registrations);
+      } else if (entities.length > 0) {
+        await this.registerEntities(entities);
+      }
+
+      let tick = 0;
+      this._tickCount = tick;
+      let timeMicros = this.logicalTimeMicros ?? (await this.queryLogicalTimeMicros());
+      const deltaSeconds = Number(this._updatePeriodMicros) / 1_000_000;
+      if (this._logBootstrap && !this._bootstrapLogged) {
+        const state = this.spacefomState;
+        this.logger.info("Spacekit SEE bootstrap complete.", {
+          lastGrantedTimeMicros: state?.lastGrantedTimeMicros?.toString() ?? "unknown",
+          lctsMicros: state?.lctsMicros?.toString() ?? "unknown",
+          rootFrame: state?.rootFrameName ?? "unknown",
+        });
+        this._bootstrapLogged = true;
+      }
+      if (options.onTick) {
+        await options.onTick({
+          timeMicros,
+          sendTimeMicros: this.getSendTimeMicros(timeMicros),
+          timeSeconds: Number(timeMicros) / 1_000_000,
+          deltaSeconds: 0,
+          tick,
+          initial: true,
+        });
+      }
+      if (options.sync !== false && entities.length > 0) {
+        await this.sync(entities);
+      }
+
+      while (!this.isShutdownRequested) {
+        tick += 1;
+        this._tickCount = tick;
+        timeMicros = await this.tick();
+        if (options.onTick) {
+          await options.onTick({
+            timeMicros,
+            sendTimeMicros: this.getSendTimeMicros(timeMicros),
+            timeSeconds: Number(timeMicros) / 1_000_000,
+            deltaSeconds,
+            tick,
+            initial: false,
+          });
+        }
+        if (options.sync !== false && entities.length > 0) {
+          await this.sync(entities);
+        }
+      }
+    } catch (err) {
+      runError = err;
+      this.logger.error("Spacekit SEE run failed.", { error: err });
+      options.onError?.(err);
+      this.requestShutdown("error");
+    } finally {
+      if (this.rtiAmbassador) {
+        try {
+          await this.stop();
+        } catch (err) {
+          this.logger.warn("Spacekit SEE shutdown error.", { error: err });
+        }
+      }
+    }
+
+    if (runError) {
+      process.exitCode = 1;
+      if (options.throwOnError) {
+        throw runError;
+      }
+    }
+  }
+
+  getSendTimeMicros(baseTimeMicros?: bigint): bigint | null {
+    const base = baseTimeMicros ?? this._logicalTimeMicros;
+    if (base === null || base === undefined) return null;
+    return base + this._lookaheadMicros;
+  }
+
+  shouldLog(updateCount: number): boolean {
+    if (!this._logEveryN || this._logEveryN <= 1) return true;
+    return updateCount % this._logEveryN === 0;
+  }
+
+  shouldLogTick(tick: number = this._tickCount): boolean {
+    return this.shouldLog(tick);
+  }
+
+  shouldLogUpdate(record: { updateCount: number }): boolean {
+    return this.shouldLog(record.updateCount);
+  }
+
+  override async syncEntity<T extends object>(
+    entity: SpacekitEntity<T>,
+    time?: LogicalTime | bigint,
+    userSuppliedTag?: Uint8Array
+  ): Promise<void> {
+    if (typeof time === "bigint") {
+      const logicalTime = encodeHLAinteger64Time(time + this._lookaheadMicros);
+      await super.syncEntity(entity, logicalTime, userSuppliedTag);
+      return;
+    }
+    if (!time) {
+      const base = this._logicalTimeMicros ?? (await this.queryLogicalTimeMicros());
+      const logicalTime = encodeHLAinteger64Time(base + this._lookaheadMicros);
+      await super.syncEntity(entity, logicalTime, userSuppliedTag);
+      return;
+    }
+    await super.syncEntity(entity, time, userSuppliedTag);
+  }
+
+  async waitForReferenceFrame(name: string, timeoutMs = this._referenceFrameTimeoutMs): Promise<void> {
+    const start = Date.now();
+    const effectiveTimeoutMs = timeoutMs === 0 ? this._referenceFrameGraceMs : timeoutMs;
+    let lastNames = "";
+    while (true) {
+      const state = this.spacefomState;
+      const frames = state?.referenceFrames ?? [];
+      const names = frames
+        .map((frame) => frame.name)
+        .filter((frameName): frameName is string => !!frameName)
+        .sort()
+        .join(",");
+      if (names && names !== lastNames) {
+        lastNames = names;
+        this.logger.debug("Reference frames discovered.", { names: names.split(",") });
+      }
+      if (frames.some((frame) => frame.name === name)) {
+        return;
+      }
+      if (
+        this._referenceFrameFallbackSubscribe &&
+        effectiveTimeoutMs > 0 &&
+        Date.now() - start > Math.min(effectiveTimeoutMs, 2000)
+      ) {
+        this._referenceFrameFallbackSubscribe = false;
+        await this._subscribeReferenceFrameFallback();
+      }
+      if (
+        this._referenceFrameNameProbe &&
+        effectiveTimeoutMs > 0 &&
+        Date.now() - start > Math.min(effectiveTimeoutMs, 1500)
+      ) {
+        this._referenceFrameNameProbe = false;
+        const found = await this._probeReferenceFrameByName(name);
+        if (found) {
+          this.logger.warn("Reference frame confirmed via name lookup.", { name });
+          return;
+        }
+      }
+      if (effectiveTimeoutMs >= 0 && Date.now() - start > effectiveTimeoutMs) {
+        const error = `Reference frame not discovered: ${name}. Known frames: ${names || "(none)"}`;
+        if (this._missingReferenceFrameMode === "continue") {
+          this.logger.warn("Proceeding without discovered reference frame.", {
+            name,
+            knownFrames: names ? names.split(",") : [],
+            timeoutMs: effectiveTimeoutMs,
+          });
+          return;
+        }
+        throw new Error(error);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 200));
+    }
+  }
+
+  protected override shouldRegisterClassInFom(ctor: Function, kind: "object" | "interaction"): boolean {
+    if (kind === "object" && BASE_OBJECT_CLASSES.has(ctor as FomClassConstructor)) {
+      return false;
+    }
+    if (kind === "interaction" && BASE_INTERACTION_CLASSES.has(ctor as FomClassConstructor)) {
+      return false;
+    }
+    return true;
+  }
+
+  protected override async beforeRegisterEntity<T extends object>(entity: SpacekitEntity<T>): Promise<void> {
+    if (!this._autoWaitForReferenceFrame) return;
+    const parentName =
+      (entity as { parent_reference_frame?: string }).parent_reference_frame ??
+      (entity as { parent_name?: string }).parent_name;
+    if (!parentName) return;
+    await this.waitForReferenceFrame(parentName);
+  }
+
+  private async _subscribeReferenceFrameFallback(): Promise<void> {
+    const rti = this.rtiAmbassador;
+    if (!rti) return;
+    const adapter = this.declarative.getObjectAdapter<ReferenceFrame>(ReferenceFrame.className);
+    if (!adapter) return;
+    if (!adapter.isResolved) {
+      await adapter.resolve(rti);
+    }
+    await adapter.subscribe(rti);
+    this.logger.debug("Retrying ReferenceFrame subscribe fallback.");
+  }
+
+  private async _probeReferenceFrameByName(name: string): Promise<boolean> {
+    const rti = this.rtiAmbassador;
+    if (!rti) return false;
+    try {
+      const handle = await rti.getObjectInstanceHandle(name);
+      if (!handle || handle.length === 0) return false;
+      const adapter = this.declarative.getObjectAdapter<ReferenceFrame>(ReferenceFrame.className);
+      if (!adapter) return true;
+      if (!adapter.isResolved) {
+        await adapter.resolve(rti);
+      }
+      await rti.requestInstanceAttributeValueUpdate(handle, adapter.attributeHandleSet, new Uint8Array());
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}