@hla4ts/spacekit 0.1.0 → 0.1.1

package/README.md

@@ -1,154 +1,154 @@
-# @hla4ts/spacekit
-
-SEE-first application layer for HLA federates.
-
-`@hla4ts/spacekit` is now the default entry point for new users, especially for
-SEE and SpaceFOM federates. It sits on top of `@hla4ts/hla-api` and bundles the
-runtime pieces most users actually need:
-
-- `SpacekitApp`: opinionated SEE/SpaceFOM app runtime
-- canonical SpaceFOM entity and interaction classes
-- late-joiner bootstrap and typed bootstrap state
-- run loop, `tick()`, and logical-time send-time helpers
-- declarative object/interaction schemas and decorator-based registration
-- entity sync, environment parsing, and console logging helpers
-
-`@hla4ts/spacefom` is now the thinner helper layer underneath it. Use that
-package directly only when you need raw SpaceFOM assets such as bundled XML
-modules or low-level coders.
-
-## Install
-
-```bash
-bun add @hla4ts/spacekit
-```
-
-## Recommended Entry Point
-
-```ts
-import { PhysicalEntity, SpacekitApp } from "@hla4ts/spacekit";
-
-const app = new SpacekitApp({
-  federationName: "SpaceFederation",
-  federateName: "LunarRover-1",
-  federateType: "LunarRover",
-});
-
-const rover = new PhysicalEntity("LunarRover-1", {
-  parent_reference_frame: "AitkenBasinLocalFixed",
-});
-
-await app.start();
-await app.registerEntity(rover);
-
-await app.run({
-  entities: [rover],
-  onTick: ({ timeSeconds }) => {
-    rover.state = {
-      translation: {
-        position: [0.5 * timeSeconds, 0, 0],
-        velocity: [0.5, 0, 0],
-      },
-      rotation: {
-        attitude: { scalar: 1, vector: [0, 0, 0] },
-        angularVelocity: [0, 0, 0],
-      },
-      time: timeSeconds,
-    };
-  },
-});
-```
-
-## What `SpacekitApp` Adds
-
-- SEE-oriented environment defaults
-- built-in `SpaceFomLateJoinerBootstrap`
-- automatic reference-frame waiting for `PhysicalEntity` registration
-- `tick()` and `run()` for paced logical-time loops
-- `getSendTimeMicros()` for timestamped updates/interactions
-- `spacefomState` for typed bootstrap state access
-- configurable missing-reference-frame behavior via `missingReferenceFrameMode`
-- graceful shutdown wiring by default
-
-If you want an app to keep running when a configured parent reference frame is
-not yet available, set `missingReferenceFrameMode: "continue"` on
-`SpacekitApp`. The app will warn and proceed instead of throwing during entity
-registration.
-
-## Canonical SpaceFOM Types
-
-The canonical decorated SpaceFOM classes now live in `@hla4ts/spacekit`:
-
-- `ExecutionConfiguration`
-- `ReferenceFrame`
-- `PhysicalEntity`
-- `DynamicalEntity`
-- `ModeTransitionRequest`
-
-These classes are the single source of truth for the runtime adapters,
-bootstrap subscriptions, and extension-FOM generation.
-
-## Lower-Level Escape Hatches
-
-If you need to drop below the SEE-first app layer, `@hla4ts/spacekit` still
-exports the generic framework primitives:
-
-- `BaseSpacekitApp`
-- `SpacekitFederate`
-- `DeclarativeFom`
-- `DeclarativeRuntime`
-- `SpacekitEntity`
-- decorators such as `FomObjectClass` and `FomInteractionClass`
-
-## SpaceFOM Assets and Coders
-
-`@hla4ts/spacekit` re-exports the common SpaceFOM helpers so most SEE users do
-not need a second package import:
-
-```ts
-import {
-  HLAunicodeStringCoder,
-  SpaceFomExecutionMode,
-  encodeSpaceTimeCoordinateState,
-  loadSpaceFomModules,
-} from "@hla4ts/spacekit";
-```
-
-## E2E Validation
-
-The repo includes an opt-in real-stack validation path built around the
-`lunar-rover` and `lunar-rover-tracker` examples.
-
-Prerequisites:
-
-- target RTI already running
-- SpaceMaster already running
-- Root Reference Frame Publisher already running
-
-Command:
-
-```bash
-RTI_HOST=localhost bun run e2e:spacekit-see
-```
-
-The command fails on timeout or missing success markers and validates:
-
-- join/bootstrap completion
-- reference-frame discovery
-- rover state publication
-- tracker receipt of rover updates
-- interaction round-trip plus ACK
-- multiple logical ticks for both federates
-
-## Package Split
-
-- `@hla4ts/spacekit`: default SEE/SpaceFOM app layer
-- `@hla4ts/spacefom`: bundled SpaceFOM XML modules, coders, constants, and optional dashboard loader
-- `@hla4ts/hla-api`: direct HLA API surface when you do not want the framework
-
-## Test
-
-```bash
-cd packages/spacekit
-bun test
-```
+# @hla4ts/spacekit
+
+SEE-first application layer for HLA federates.
+
+`@hla4ts/spacekit` is now the default entry point for new users, especially for
+SEE and SpaceFOM federates. It sits on top of `@hla4ts/hla-api` and bundles the
+runtime pieces most users actually need:
+
+- `SpacekitApp`: opinionated SEE/SpaceFOM app runtime
+- canonical SpaceFOM entity and interaction classes
+- late-joiner bootstrap and typed bootstrap state
+- run loop, `tick()`, and logical-time send-time helpers
+- declarative object/interaction schemas and decorator-based registration
+- entity sync, environment parsing, and console logging helpers
+
+`@hla4ts/spacefom` is now the thinner helper layer underneath it. Use that
+package directly only when you need raw SpaceFOM assets such as bundled XML
+modules or low-level coders.
+
+## Install
+
+```bash
+bun add @hla4ts/spacekit
+```
+
+## Recommended Entry Point
+
+```ts
+import { PhysicalEntity, SpacekitApp } from "@hla4ts/spacekit";
+
+const app = new SpacekitApp({
+  federationName: "SpaceFederation",
+  federateName: "LunarRover-1",
+  federateType: "LunarRover",
+});
+
+const rover = new PhysicalEntity("LunarRover-1", {
+  parent_reference_frame: "AitkenBasinLocalFixed",
+});
+
+await app.start();
+await app.registerEntity(rover);
+
+await app.run({
+  entities: [rover],
+  onTick: ({ timeSeconds }) => {
+    rover.state = {
+      translation: {
+        position: [0.5 * timeSeconds, 0, 0],
+        velocity: [0.5, 0, 0],
+      },
+      rotation: {
+        attitude: { scalar: 1, vector: [0, 0, 0] },
+        angularVelocity: [0, 0, 0],
+      },
+      time: timeSeconds,
+    };
+  },
+});
+```
+
+## What `SpacekitApp` Adds
+
+- SEE-oriented environment defaults
+- built-in `SpaceFomLateJoinerBootstrap`
+- automatic reference-frame waiting for `PhysicalEntity` registration
+- `tick()` and `run()` for paced logical-time loops
+- `getSendTimeMicros()` for timestamped updates/interactions
+- `spacefomState` for typed bootstrap state access
+- configurable missing-reference-frame behavior via `missingReferenceFrameMode`
+- graceful shutdown wiring by default
+
+If you want an app to keep running when a configured parent reference frame is
+not yet available, set `missingReferenceFrameMode: "continue"` on
+`SpacekitApp`. The app will warn and proceed instead of throwing during entity
+registration.
+
+## Canonical SpaceFOM Types
+
+The canonical decorated SpaceFOM classes now live in `@hla4ts/spacekit`:
+
+- `ExecutionConfiguration`
+- `ReferenceFrame`
+- `PhysicalEntity`
+- `DynamicalEntity`
+- `ModeTransitionRequest`
+
+These classes are the single source of truth for the runtime adapters,
+bootstrap subscriptions, and extension-FOM generation.
+
+## Lower-Level Escape Hatches
+
+If you need to drop below the SEE-first app layer, `@hla4ts/spacekit` still
+exports the generic framework primitives:
+
+- `BaseSpacekitApp`
+- `SpacekitFederate`
+- `DeclarativeFom`
+- `DeclarativeRuntime`
+- `SpacekitEntity`
+- decorators such as `FomObjectClass` and `FomInteractionClass`
+
+## SpaceFOM Assets and Coders
+
+`@hla4ts/spacekit` re-exports the common SpaceFOM helpers so most SEE users do
+not need a second package import:
+
+```ts
+import {
+  HLAunicodeStringCoder,
+  SpaceFomExecutionMode,
+  encodeSpaceTimeCoordinateState,
+  loadSpaceFomModules,
+} from "@hla4ts/spacekit";
+```
+
+## E2E Validation
+
+The repo includes an opt-in real-stack validation path built around the
+`lunar-rover` and `lunar-rover-tracker` examples.
+
+Prerequisites:
+
+- target RTI already running
+- SpaceMaster already running
+- Root Reference Frame Publisher already running
+
+Command:
+
+```bash
+RTI_HOST=localhost bun run e2e:spacekit-see
+```
+
+The command fails on timeout or missing success markers and validates:
+
+- join/bootstrap completion
+- reference-frame discovery
+- rover state publication
+- tracker receipt of rover updates
+- interaction round-trip plus ACK
+- multiple logical ticks for both federates
+
+## Package Split
+
+- `@hla4ts/spacekit`: default SEE/SpaceFOM app layer
+- `@hla4ts/spacefom`: bundled SpaceFOM XML modules, coders, constants, and optional dashboard loader
+- `@hla4ts/hla-api`: direct HLA API surface when you do not want the framework
+
+## Test
+
+```bash
+cd packages/spacekit
+bun test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hla4ts/spacekit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "SEE-first starter kit and default application layer for hla4typescript federates",
   "type": "module",
   "main": "src/index.ts",
@@ -16,9 +16,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@hla4ts/hla-api": "^0.1.0",
-    "@hla4ts/fom-codegen": "^0.1.0",
-    "@hla4ts/spacefom": "^0.1.0"
+    "@hla4ts/hla-api": "^0.1.1",
+    "@hla4ts/fom-codegen": "^0.1.1",
+    "@hla4ts/spacefom": "^0.1.1"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/declarative.test.ts

@@ -46,4 +46,4 @@ test("DeclarativeFom registers object and interaction schemas", () => {
   expect(model.objectClasses[0]?.attributes?.[0]?.name).toBe("name");
   expect(model.interactionClasses[0]?.name).toBe("HLAinteractionRoot.TestInteraction");
   expect(model.interactionClasses[0]?.parameters?.[0]?.name).toBe("count");
-});
+});

package/src/declare-spacefom.ts

@@ -1,14 +1,14 @@
-import { buildDeclarativeFomFromDecorators, type FomClassConstructor } from "./decorators.ts";
-import type { DeclarativeFom } from "./declarative.ts";
-
-export interface DeclareSpaceFomOptions {
-  objectClasses?: FomClassConstructor[];
-  interactionClasses?: FomClassConstructor[];
-}
-
-export function declareSpaceFom(options: DeclareSpaceFomOptions = {}): DeclarativeFom {
-  return buildDeclarativeFomFromDecorators({
-    objectClasses: options.objectClasses ?? [],
-    interactionClasses: options.interactionClasses ?? [],
-  });
-}
+import { buildDeclarativeFomFromDecorators, type FomClassConstructor } from "./decorators.ts";
+import type { DeclarativeFom } from "./declarative.ts";
+
+export interface DeclareSpaceFomOptions {
+  objectClasses?: FomClassConstructor[];
+  interactionClasses?: FomClassConstructor[];
+}
+
+export function declareSpaceFom(options: DeclareSpaceFomOptions = {}): DeclarativeFom {
+  return buildDeclarativeFomFromDecorators({
+    objectClasses: options.objectClasses ?? [],
+    interactionClasses: options.interactionClasses ?? [],
+  });
+}

package/src/index.ts

@@ -1,51 +1,51 @@
-/**
- * @hla4ts/spacekit
- *
- * SEE-first lifecycle + declarative helpers for HLA federates.
- */
-
-export { SpacekitFederate } from "./federate.ts";
-export type { SpacekitFederateConfig, SpacekitFomConfig, FederateHandlers } from "./types.ts";
-export * from "./object-model.ts";
-export * from "./declarative.ts";
-export * from "./declarative-runtime.ts";
-export * from "./decorators.ts";
-export * from "./entity.ts";
-export {
-  SpacekitApp as BaseSpacekitApp,
-} from "./app.ts";
-export type {
-  SpacekitBootstrapper,
-  SpacekitAppConfig as BaseSpacekitAppConfig,
-  RegisterObjectOptions,
-  TrackOptions,
-  TrackRecord,
-} from "./app.ts";
-export { SpacekitApp } from "./see-app.ts";
-export type { MissingReferenceFrameMode, SpacekitAppOptions } from "./see-app.ts";
-export * from "./time-advance.ts";
-export * from "./env.ts";
-export * from "./logger.ts";
-export * from "./spacefom-entities.ts";
-export * from "./spacefom-interactions.ts";
-export * from "./spacefom-bootstrap.ts";
-export * from "./spacefom-config.ts";
-export * from "./declare-spacefom.ts";
-export {
-  HLAunicodeStringCoder,
-  SpaceFomExecutionMode,
-  SpaceFomMtrMode,
-  SpaceFomSyncPointLabels,
-  loadSpaceFomModules,
-  SpaceFomBaseModules,
-} from "@hla4ts/spacefom";
-export type {
-  SpaceFomBaseModuleName,
-  SpaceFomModuleFormat,
-  SpaceFomCoder,
-  AttitudeQuaternion,
-  Matrix3,
-  SpaceTimeCoordinateState,
-  Vector3,
-} from "@hla4ts/spacefom";
-export * from "@hla4ts/spacefom";
+/**
+ * @hla4ts/spacekit
+ *
+ * SEE-first lifecycle + declarative helpers for HLA federates.
+ */
+
+export { SpacekitFederate } from "./federate.ts";
+export type { SpacekitFederateConfig, SpacekitFomConfig, FederateHandlers } from "./types.ts";
+export * from "./object-model.ts";
+export * from "./declarative.ts";
+export * from "./declarative-runtime.ts";
+export * from "./decorators.ts";
+export * from "./entity.ts";
+export {
+  SpacekitApp as BaseSpacekitApp,
+} from "./app.ts";
+export type {
+  SpacekitBootstrapper,
+  SpacekitAppConfig as BaseSpacekitAppConfig,
+  RegisterObjectOptions,
+  TrackOptions,
+  TrackRecord,
+} from "./app.ts";
+export { SpacekitApp } from "./see-app.ts";
+export type { MissingReferenceFrameMode, SpacekitAppOptions } from "./see-app.ts";
+export * from "./time-advance.ts";
+export * from "./env.ts";
+export * from "./logger.ts";
+export * from "./spacefom-entities.ts";
+export * from "./spacefom-interactions.ts";
+export * from "./spacefom-bootstrap.ts";
+export * from "./spacefom-config.ts";
+export * from "./declare-spacefom.ts";
+export {
+  HLAunicodeStringCoder,
+  SpaceFomExecutionMode,
+  SpaceFomMtrMode,
+  SpaceFomSyncPointLabels,
+  loadSpaceFomModules,
+  SpaceFomBaseModules,
+} from "@hla4ts/spacefom";
+export type {
+  SpaceFomBaseModuleName,
+  SpaceFomModuleFormat,
+  SpaceFomCoder,
+  AttitudeQuaternion,
+  Matrix3,
+  SpaceTimeCoordinateState,
+  Vector3,
+} from "@hla4ts/spacefom";
+export * from "@hla4ts/spacefom";

package/src/object-model.ts

@@ -272,4 +272,4 @@ export class InteractionClassAdapter<T extends object> {
       await rti.sendInteraction(this.interactionHandle, payload, userSuppliedTag);
     }
   }
-}
+}

package/src/see-app.test.ts

@@ -1,62 +1,62 @@
-import { expect, test } from "bun:test";
-import { SpacekitApp } from "./see-app.ts";
-
-test("SpacekitApp exposes SEE timing helpers", () => {
-  const app = new SpacekitApp({
-    federationName: "SpaceFederation",
-    federateName: "TestFederate",
-    federateType: "TestFederate",
-    lookaheadMicros: 500_000n,
-    updatePeriodMicros: 1_000_000n,
-  });
-
-  expect(app.lookaheadMicros).toBe(500_000n);
-  expect(app.updatePeriodMicros).toBe(1_000_000n);
-  expect(app.getSendTimeMicros(10_000_000n)).toBe(10_500_000n);
-  expect(app.shouldLogTick(1)).toBe(true);
-});
-
-test("SpacekitApp can continue when a reference frame is missing", async () => {
-  const warnings: Array<{ message: string; data?: Record<string, unknown> }> = [];
-  const app = new SpacekitApp({
-    federationName: "SpaceFederation",
-    federateName: "TestFederate",
-    federateType: "TestFederate",
-    referenceFrameTimeoutMs: 1,
-    missingReferenceFrameMode: "continue",
-    logger: {
-      debug() {},
-      info() {},
-      warn(message, data) {
-        warnings.push({ message, data });
-      },
-      error() {},
-    },
-  });
-
-  (app as unknown as { _bootstrapState: unknown })._bootstrapState = {
-    referenceFrames: [],
-  };
-
-  await expect(app.waitForReferenceFrame("MissingFrame", 1)).resolves.toBeUndefined();
-  expect(
-    warnings.some((entry) => entry.message === "Proceeding without discovered reference frame.")
-  ).toBe(true);
-});
-
-test("SpacekitApp still errors by default when a reference frame is missing", async () => {
-  const app = new SpacekitApp({
-    federationName: "SpaceFederation",
-    federateName: "TestFederate",
-    federateType: "TestFederate",
-    referenceFrameTimeoutMs: 1,
-  });
-
-  (app as unknown as { _bootstrapState: unknown })._bootstrapState = {
-    referenceFrames: [],
-  };
-
-  await expect(app.waitForReferenceFrame("MissingFrame", 1)).rejects.toThrow(
-    "Reference frame not discovered: MissingFrame"
-  );
-});
+import { expect, test } from "bun:test";
+import { SpacekitApp } from "./see-app.ts";
+
+test("SpacekitApp exposes SEE timing helpers", () => {
+  const app = new SpacekitApp({
+    federationName: "SpaceFederation",
+    federateName: "TestFederate",
+    federateType: "TestFederate",
+    lookaheadMicros: 500_000n,
+    updatePeriodMicros: 1_000_000n,
+  });
+
+  expect(app.lookaheadMicros).toBe(500_000n);
+  expect(app.updatePeriodMicros).toBe(1_000_000n);
+  expect(app.getSendTimeMicros(10_000_000n)).toBe(10_500_000n);
+  expect(app.shouldLogTick(1)).toBe(true);
+});
+
+test("SpacekitApp can continue when a reference frame is missing", async () => {
+  const warnings: Array<{ message: string; data?: Record<string, unknown> }> = [];
+  const app = new SpacekitApp({
+    federationName: "SpaceFederation",
+    federateName: "TestFederate",
+    federateType: "TestFederate",
+    referenceFrameTimeoutMs: 1,
+    missingReferenceFrameMode: "continue",
+    logger: {
+      debug() {},
+      info() {},
+      warn(message, data) {
+        warnings.push({ message, data });
+      },
+      error() {},
+    },
+  });
+
+  (app as unknown as { _bootstrapState: unknown })._bootstrapState = {
+    referenceFrames: [],
+  };
+
+  await expect(app.waitForReferenceFrame("MissingFrame", 1)).resolves.toBeUndefined();
+  expect(
+    warnings.some((entry) => entry.message === "Proceeding without discovered reference frame.")
+  ).toBe(true);
+});
+
+test("SpacekitApp still errors by default when a reference frame is missing", async () => {
+  const app = new SpacekitApp({
+    federationName: "SpaceFederation",
+    federateName: "TestFederate",
+    federateType: "TestFederate",
+    referenceFrameTimeoutMs: 1,
+  });
+
+  (app as unknown as { _bootstrapState: unknown })._bootstrapState = {
+    referenceFrames: [],
+  };
+
+  await expect(app.waitForReferenceFrame("MissingFrame", 1)).rejects.toThrow(
+    "Reference frame not discovered: MissingFrame"
+  );
+});