@czap/core 0.1.0

package/src/easing.ts

@@ -0,0 +1,334 @@
+/**
+ * Easing -- pure math easing functions.
+ *
+ * All functions map t in [0,1] to value in [0,1].
+ * Zero dependencies -- pure arithmetic.
+ *
+ * @module
+ */
+
+import { EASING_SPRING_STEPS } from './defaults.js';
+
+type EasingFnShape = (t: number) => number;
+
+interface SpringConfigShape {
+  readonly stiffness: number;
+  readonly damping: number;
+  readonly mass?: number;
+}
+
+interface EasingFns {
+  readonly linear: EasingFnShape;
+  readonly easeInCubic: EasingFnShape;
+  readonly easeOutCubic: EasingFnShape;
+  readonly easeInOutCubic: EasingFnShape;
+  readonly easeOutExpo: EasingFnShape;
+  readonly easeOutBack: EasingFnShape;
+  readonly easeOutElastic: EasingFnShape;
+  readonly easeOutBounce: EasingFnShape;
+  readonly ease: EasingFnShape;
+  readonly easeIn: EasingFnShape;
+  readonly easeOut: EasingFnShape;
+  readonly easeInOut: EasingFnShape;
+  spring(config: SpringConfigShape): EasingFnShape;
+  cubicBezier(x1: number, y1: number, x2: number, y2: number): EasingFnShape;
+  springToLinearCSS(config: SpringConfigShape, sampleCount?: number): string;
+  springNaturalDuration(config: SpringConfigShape, epsilon?: number): number;
+}
+
+/**
+ * Linear easing -- no acceleration, constant rate of change.
+ *
+ * @example
+ * ```ts
+ * Easing.linear(0.5); // 0.5
+ * ```
+ */
+const linear: EasingFnShape = (t) => t;
+
+/**
+ * Cubic ease-in -- starts slow, accelerates.
+ *
+ * @example
+ * ```ts
+ * Easing.easeInCubic(0.5); // 0.125
+ * ```
+ */
+const easeInCubic: EasingFnShape = (t) => t * t * t;
+
+/**
+ * Cubic ease-out -- starts fast, decelerates.
+ *
+ * @example
+ * ```ts
+ * Easing.easeOutCubic(0.5); // 0.875
+ * ```
+ */
+const easeOutCubic: EasingFnShape = (t) => {
+  const u = 1 - t;
+  return 1 - u * u * u;
+};
+
+/**
+ * Cubic ease-in-out -- slow start and end, fast middle.
+ *
+ * @example
+ * ```ts
+ * Easing.easeInOutCubic(0.25); // 0.0625
+ * Easing.easeInOutCubic(0.75); // 0.9375
+ * ```
+ */
+const easeInOutCubic: EasingFnShape = (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
+
+/**
+ * Exponential ease-out -- very fast deceleration.
+ *
+ * @example
+ * ```ts
+ * Easing.easeOutExpo(0.5); // ~0.969
+ * ```
+ */
+const easeOutExpo: EasingFnShape = (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t));
+
+/**
+ * Ease-out with overshoot -- overshoots target, then settles.
+ *
+ * @example
+ * ```ts
+ * Easing.easeOutBack(0.8); // ~1.037 (overshoots past 1.0)
+ * Easing.easeOutBack(1.0); // 1.0
+ * ```
+ */
+const easeOutBack: EasingFnShape = (t) => {
+  /** Penner's back easing overshoot coefficient — controls how far the animation overshoots before settling. */
+  const BACK_OVERSHOOT = 1.70158;
+  const c3 = BACK_OVERSHOOT + 1;
+  return 1 + c3 * Math.pow(t - 1, 3) + BACK_OVERSHOOT * Math.pow(t - 1, 2);
+};
+
+/**
+ * Elastic ease-out -- spring-like oscillation that settles at 1.
+ *
+ * @example
+ * ```ts
+ * Easing.easeOutElastic(0.5); // ~1.015 (oscillates around target)
+ * Easing.easeOutElastic(1.0); // 1.0
+ * ```
+ */
+const easeOutElastic: EasingFnShape = (t) => {
+  if (t === 0 || t === 1) return t;
+  /** One-third rotation for elastic oscillation — produces ~3 bounces in elastic easing. */
+  const ELASTIC_PERIOD = (2 * Math.PI) / 3;
+  return Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * ELASTIC_PERIOD) + 1;
+};
+
+/**
+ * Bounce ease-out -- simulates a bouncing ball settling at target.
+ *
+ * @example
+ * ```ts
+ * Easing.easeOutBounce(0.5);  // 0.765625
+ * Easing.easeOutBounce(1.0);  // 1.0
+ * ```
+ */
+const easeOutBounce: EasingFnShape = (t) => {
+  /** Penner bounce easing coefficients — BOUNCE_AMPLITUDE controls peak height, BOUNCE_DIVISOR controls number of bounces. */
+  const BOUNCE_AMPLITUDE = 7.5625;
+  const BOUNCE_DIVISOR = 2.75;
+  if (t < 1 / BOUNCE_DIVISOR) return BOUNCE_AMPLITUDE * t * t;
+  if (t < 2 / BOUNCE_DIVISOR) {
+    const u = t - 1.5 / BOUNCE_DIVISOR;
+    return BOUNCE_AMPLITUDE * u * u + 0.75;
+  }
+  if (t < 2.5 / BOUNCE_DIVISOR) {
+    const u = t - 2.25 / BOUNCE_DIVISOR;
+    return BOUNCE_AMPLITUDE * u * u + 0.9375;
+  }
+  const u = t - 2.625 / BOUNCE_DIVISOR;
+  return BOUNCE_AMPLITUDE * u * u + 0.984375;
+};
+
+/**
+ * Creates a CSS cubic-bezier easing function from four control points.
+ * Uses binary search to approximate the bezier curve evaluation.
+ *
+ * @example
+ * ```ts
+ * const customEase = Easing.cubicBezier(0.42, 0, 0.58, 1);
+ * customEase(0.5); // ~0.5 (equivalent to CSS ease-in-out)
+ * customEase(0.0); // 0.0
+ * customEase(1.0); // 1.0
+ * ```
+ */
+function cubicBezier(x1: number, y1: number, x2: number, y2: number): EasingFnShape {
+  return (t: number): number => {
+    if (t <= 0) return 0;
+    if (t >= 1) return 1;
+    let lo = 0,
+      hi = 1;
+    /** Binary search iterations for cubic-bezier — 20 iterations converges to `<0.001` error for any control points. */
+    const BEZIER_ITERATIONS = 20;
+    for (let i = 0; i < BEZIER_ITERATIONS; i++) {
+      const mid = (lo + hi) / 2;
+      const x = 3 * (1 - mid) * (1 - mid) * mid * x1 + 3 * (1 - mid) * mid * mid * x2 + mid * mid * mid;
+      if (x < t) lo = mid;
+      else hi = mid;
+    }
+    const u = (lo + hi) / 2;
+    return 3 * (1 - u) * (1 - u) * u * y1 + 3 * (1 - u) * u * u * y2 + u * u * u;
+  };
+}
+
+const ease = cubicBezier(0.25, 0.1, 0.25, 1.0);
+const easeIn = cubicBezier(0.42, 0, 1, 1);
+const easeOut = cubicBezier(0, 0, 0.58, 1);
+const easeInOut = cubicBezier(0.42, 0, 0.58, 1);
+
+/**
+ * Evaluate raw spring physics at time `t` (in the spring's natural time domain,
+ * not normalized). Used internally by both `spring` and `springNaturalDuration`
+ * to avoid circular dependency.
+ */
+function springRaw(t: number, omega: number, zeta: number): number {
+  if (zeta < 1) {
+    // Underdamped
+    const omegaD = omega * Math.sqrt(1 - zeta * zeta);
+    return 1 - Math.exp(-zeta * omega * t) * (Math.cos(omegaD * t) + ((zeta * omega) / omegaD) * Math.sin(omegaD * t));
+  }
+  if (zeta === 1) {
+    // Critically damped
+    return 1 - (1 + omega * t) * Math.exp(-omega * t);
+  }
+  // Overdamped (zeta > 1)
+  const s = Math.sqrt(zeta * zeta - 1);
+  const r1 = -omega * (zeta + s);
+  const r2 = -omega * (zeta - s);
+  const c1 = r2 / (r2 - r1);
+  const c2 = -r1 / (r2 - r1);
+  return 1 - (c1 * Math.exp(r1 * t) + c2 * Math.exp(r2 * t));
+}
+
+/**
+ * Find the natural settling duration of a spring (in the spring's own time domain).
+ * Returns the smallest `t` where `|springRaw(t')|` is within epsilon of 1 for all `t' >= t`.
+ * Scans backward at 0.5ms resolution up to 2 seconds.
+ *
+ * @example
+ * ```ts
+ * const duration = Easing.springNaturalDuration({ stiffness: 200, damping: 15 });
+ * // duration is ~0.4 (seconds in spring time domain)
+ * ```
+ */
+function _validateSpringConfig(config: SpringConfigShape): void {
+  if (config.stiffness <= 0 || !Number.isFinite(config.stiffness)) {
+    throw new RangeError(`Easing.spring: stiffness must be a positive finite number, got ${config.stiffness}`);
+  }
+  if (config.damping < 0 || !Number.isFinite(config.damping)) {
+    throw new RangeError(`Easing.spring: damping must be a non-negative finite number, got ${config.damping}`);
+  }
+  if (config.mass !== undefined && (config.mass <= 0 || !Number.isFinite(config.mass))) {
+    throw new RangeError(`Easing.spring: mass must be a positive finite number, got ${config.mass}`);
+  }
+}
+
+function springNaturalDuration(config: SpringConfigShape, epsilon = 0.001): number {
+  _validateSpringConfig(config);
+  const { stiffness, damping, mass = 1 } = config;
+  const omega = Math.sqrt(stiffness / mass);
+  const zeta = damping / (2 * Math.sqrt(stiffness * mass));
+  // Scan steps (at 1ms resolution) to find spring settling point
+  const steps = EASING_SPRING_STEPS;
+  for (let ms = steps; ms > 0; ms--) {
+    const t = ms / steps;
+    if (Math.abs(springRaw(t, omega, zeta) - 1) >= epsilon) return t + 0.025;
+  }
+  // Fallback 300ms duration if spring never settles within scan window
+  return 0.3;
+}
+
+/**
+ * Creates a physics-based spring easing function.
+ * Maps t in [0,1] through a damped spring simulation.
+ *
+ * @example
+ * ```ts
+ * const bounce = Easing.spring({ stiffness: 200, damping: 10 });
+ * bounce(0.0);  // 0.0
+ * bounce(0.5);  // overshoots past 1.0 before settling
+ * bounce(1.0);  // 1.0
+ * ```
+ */
+function spring(config: SpringConfigShape): EasingFnShape {
+  _validateSpringConfig(config);
+  const { stiffness, damping, mass = 1 } = config;
+  const omega = Math.sqrt(stiffness / mass);
+  const zeta = damping / (2 * Math.sqrt(stiffness * mass));
+  const naturalDuration = springNaturalDuration(config);
+
+  return (t: number): number => {
+    if (t <= 0) return 0;
+    if (t >= 1) return 1;
+    const scaledT = t * naturalDuration;
+    return springRaw(scaledT, omega, zeta);
+  };
+}
+
+/**
+ * Sample a spring easing at `sampleCount` evenly-spaced points and
+ * return a CSS `linear()` timing function string for off-main-thread animation.
+ *
+ * @example
+ * ```ts
+ * const css = Easing.springToLinearCSS({ stiffness: 200, damping: 15 }, 16);
+ * // css is 'linear(0.0000, 0.1234, ..., 1.0000)' with 17 sample points
+ * element.style.transitionTimingFunction = css;
+ * ```
+ */
+function springToLinearCSS(config: SpringConfigShape, sampleCount = 32): string {
+  const fn = spring(config);
+  const points: string[] = [];
+  for (let i = 0; i <= sampleCount; i++) {
+    points.push(fn(i / sampleCount).toFixed(4));
+  }
+  return `linear(${points.join(', ')})`;
+}
+
+/**
+ * Easing -- pure math easing functions mapping t in [0,1] to value in [0,1].
+ * Includes standard CSS easings, cubic-bezier, spring physics, and CSS linear() export.
+ *
+ * @example
+ * ```ts
+ * const t = 0.5;
+ * Easing.easeOutCubic(t);  // 0.875
+ * Easing.linear(t);        // 0.5
+ * const spring = Easing.spring({ stiffness: 200, damping: 15 });
+ * spring(t);               // spring-physics interpolated value
+ * const css = Easing.springToLinearCSS({ stiffness: 200, damping: 15 });
+ * ```
+ */
+export const Easing: EasingFns = {
+  linear,
+  easeInCubic,
+  easeOutCubic,
+  easeInOutCubic,
+  easeOutExpo,
+  easeOutBack,
+  easeOutElastic,
+  easeOutBounce,
+  ease,
+  easeIn,
+  easeOut,
+  easeInOut,
+  spring,
+  cubicBezier,
+  springToLinearCSS,
+  springNaturalDuration,
+};
+
+export declare namespace Easing {
+  /** Signature of an easing function: `(t: [0..1]) => [0..1]`. */
+  export type Fn = EasingFnShape;
+  /** Spring parameters: stiffness, damping, mass. */
+  export type Config = SpringConfigShape;
+}

package/src/ecs.ts

@@ -0,0 +1,382 @@
+/**
+ * ECS -- Entity, Part, System, World.
+ *
+ * Composition over inheritance. Entities are bags of parts,
+ * systems operate on entities matching part queries.
+ *
+ * @module
+ */
+
+import type { Scope, Schema } from 'effect';
+import { Effect, Ref } from 'effect';
+
+/** Nominal-typed identifier for an ECS entity — a branded string minted via the {@link EntityId} helper. */
+export type EntityId = string & { readonly _brand: 'EntityId' };
+
+/** Brand an arbitrary string as an `EntityId`. Sanctioned single-site cast. */
+export const EntityId = (value: string): EntityId => value as EntityId;
+
+import { fnv1a } from './fnv.js';
+
+interface EntityShape {
+  readonly id: EntityId;
+  readonly components: ReadonlyMap<string, unknown>;
+}
+
+interface PartShape<T = unknown> {
+  readonly name: string;
+  readonly schema: Schema.Schema<T>;
+}
+
+// ---------------------------------------------------------------------------
+// Dense Component Storage -- Float64Array-backed, zero-allocation iteration
+// ---------------------------------------------------------------------------
+
+const DENSE_SENTINEL = -Infinity;
+
+interface DenseStoreShape {
+  readonly name: string;
+  readonly capacity: number;
+  readonly _dense: true;
+  /** Entity ID `->` index in the data array */
+  readonly entityToIndex: Map<EntityId, number>;
+  /** Index `->` Entity ID (for iteration) */
+  readonly indexToEntity: EntityId[];
+  /** The raw Float64Array backing store */
+  readonly data: Float64Array;
+  /** Current number of live entries */
+  count: number;
+
+  get(entityId: EntityId): number | undefined;
+  set(entityId: EntityId, value: number): void;
+  has(entityId: EntityId): boolean;
+  delete(entityId: EntityId): boolean;
+  reset(): void;
+  /** Direct typed array view for tight-loop iteration (length = count) */
+  view(): Float64Array;
+  /** All entity IDs with values, in dense order */
+  entities(): readonly EntityId[];
+}
+
+function _makeDenseStore(name: string, capacity: number): DenseStoreShape {
+  const entityToIndex = new Map<EntityId, number>();
+  const indexToEntity: EntityId[] = [];
+  const data = new Float64Array(capacity);
+  data.fill(DENSE_SENTINEL);
+
+  const store: DenseStoreShape = {
+    name,
+    capacity,
+    _dense: true,
+    entityToIndex,
+    indexToEntity,
+    data,
+    count: 0,
+
+    get(entityId: EntityId): number | undefined {
+      const idx = entityToIndex.get(entityId);
+      if (idx === undefined) return undefined;
+      return data[idx];
+    },
+
+    set(entityId: EntityId, value: number): void {
+      let idx = entityToIndex.get(entityId);
+      if (idx !== undefined) {
+        data[idx] = value;
+        return;
+      }
+      if (store.count >= capacity) {
+        throw new RangeError(`Dense store "${name}" at capacity (${capacity}). Cannot add entity ${entityId}.`);
+      }
+      idx = store.count;
+      entityToIndex.set(entityId, idx);
+      indexToEntity[idx] = entityId;
+      data[idx] = value;
+      store.count++;
+    },
+
+    has(entityId: EntityId): boolean {
+      return entityToIndex.has(entityId);
+    },
+
+    delete(entityId: EntityId): boolean {
+      const idx = entityToIndex.get(entityId);
+      if (idx === undefined) return false;
+
+      const lastIdx = store.count - 1;
+      if (idx !== lastIdx) {
+        // Swap-remove: move last element into the vacated slot
+        const lastEntity = indexToEntity[lastIdx]!;
+        data[idx] = data[lastIdx]!;
+        indexToEntity[idx] = lastEntity;
+        entityToIndex.set(lastEntity, idx);
+      }
+      data[lastIdx] = DENSE_SENTINEL;
+      indexToEntity.length = lastIdx;
+      entityToIndex.delete(entityId);
+      store.count--;
+      return true;
+    },
+
+    reset(): void {
+      entityToIndex.clear();
+      indexToEntity.length = 0;
+      data.fill(DENSE_SENTINEL);
+      store.count = 0;
+    },
+
+    view(): Float64Array {
+      return data.subarray(0, store.count);
+    },
+
+    entities(): readonly EntityId[] {
+      return indexToEntity;
+    },
+  };
+
+  return store;
+}
+
+// ---------------------------------------------------------------------------
+// Dense System -- operates directly on Float64Array data
+// ---------------------------------------------------------------------------
+
+interface DenseSystemShape {
+  readonly name: string;
+  readonly query: readonly string[];
+  readonly _denseSystem: true;
+  /**
+   * Execute receives dense stores keyed by component name.
+   * Systems iterate the typed arrays directly -- zero allocation per tick.
+   */
+  execute(stores: ReadonlyMap<string, DenseStoreShape>): Effect.Effect<void>;
+}
+
+// ---------------------------------------------------------------------------
+// System types
+// ---------------------------------------------------------------------------
+
+interface SystemShape {
+  readonly name: string;
+  readonly query: readonly string[];
+  readonly _denseSystem?: undefined;
+  /** Second argument is the world — use it to write computed output components back. */
+  execute(entities: readonly EntityShape[], world?: WorldShape): Effect.Effect<void>;
+}
+
+type AnySystemShape = SystemShape | DenseSystemShape;
+
+// ---------------------------------------------------------------------------
+// World
+// ---------------------------------------------------------------------------
+
+interface WorldShape {
+  spawn(components?: Record<string, unknown>): Effect.Effect<EntityId>;
+  despawn(id: EntityId): Effect.Effect<void>;
+  addComponent<T>(id: EntityId, component: PartShape<T>, value: T): Effect.Effect<void>;
+  /** Schema-free component write — used by systems to persist computed output values. */
+  setComponent(id: EntityId, name: string, value: unknown): Effect.Effect<void>;
+  removeComponent(id: EntityId, name: string): Effect.Effect<void>;
+  query(...componentNames: string[]): Effect.Effect<readonly EntityShape[]>;
+  addSystem(system: AnySystemShape): Effect.Effect<void>;
+  tick(): Effect.Effect<void>;
+  /** Register a dense store so the world can wire it into dense systems */
+  addDenseStore(store: DenseStoreShape): Effect.Effect<void>;
+}
+
+function _makeWorld(): Effect.Effect<WorldShape, never, Scope.Scope> {
+  return Effect.gen(function* () {
+    const entitiesRef = yield* Ref.make<Map<EntityId, Map<string, unknown>>>(new Map());
+    const systemsRef = yield* Ref.make<AnySystemShape[]>([]);
+    const denseStoresRef = yield* Ref.make<Map<string, DenseStoreShape>>(new Map());
+    let nextEntitySeq = 0;
+
+    const world: WorldShape = {
+      spawn(components?: Record<string, unknown>): Effect.Effect<EntityId> {
+        return Effect.gen(function* () {
+          const seq = nextEntitySeq++;
+          const id = EntityId(`entity-${seq}:${fnv1a(JSON.stringify(components ?? {}))}`);
+          const componentMap = new Map<string, unknown>();
+          if (components) {
+            for (const [name, value] of Object.entries(components)) {
+              componentMap.set(name, value);
+            }
+          }
+          yield* Ref.update(entitiesRef, (m) => {
+            const next = new Map(m);
+            next.set(id, componentMap);
+            return next;
+          });
+          return id;
+        });
+      },
+
+      despawn(id: EntityId): Effect.Effect<void> {
+        return Effect.gen(function* () {
+          // Remove from entity map
+          yield* Ref.update(entitiesRef, (m) => {
+            const next = new Map(m);
+            next.delete(id);
+            return next;
+          });
+          // Remove from all dense stores
+          const denseStores = yield* Ref.get(denseStoresRef);
+          for (const store of denseStores.values()) {
+            store.delete(id);
+          }
+        });
+      },
+
+      addComponent<T>(id: EntityId, component: PartShape<T>, value: T): Effect.Effect<void> {
+        return Ref.update(entitiesRef, (m) => {
+          const next = new Map(m);
+          const entity = next.get(id);
+          if (entity) {
+            const updated = new Map(entity);
+            updated.set(component.name, value);
+            next.set(id, updated);
+          }
+          return next;
+        });
+      },
+
+      setComponent(id: EntityId, name: string, value: unknown): Effect.Effect<void> {
+        return Ref.update(entitiesRef, (m) => {
+          const next = new Map(m);
+          const entity = next.get(id);
+          if (entity) {
+            const updated = new Map(entity);
+            updated.set(name, value);
+            next.set(id, updated);
+          }
+          return next;
+        });
+      },
+
+      removeComponent(id: EntityId, name: string): Effect.Effect<void> {
+        return Ref.update(entitiesRef, (m) => {
+          const next = new Map(m);
+          const entity = next.get(id);
+          if (entity) {
+            const updated = new Map(entity);
+            updated.delete(name);
+            next.set(id, updated);
+          }
+          return next;
+        });
+      },
+
+      query(...componentNames: string[]): Effect.Effect<readonly EntityShape[]> {
+        return Effect.gen(function* () {
+          const entities = yield* Ref.get(entitiesRef);
+          const results: EntityShape[] = [];
+
+          for (const [id, components] of entities) {
+            const hasAll = componentNames.every((name) => components.has(name));
+            if (hasAll) {
+              const componentsCopy = new Map(components) as ReadonlyMap<string, unknown>;
+              // Spread component values as direct properties so systems can access
+              // computed output fields (e.g. `_opacity`, `_phase`, `_blend`) directly.
+              const entity = Object.assign(
+                { id, components: componentsCopy },
+                Object.fromEntries(componentsCopy),
+              ) as EntityShape;
+              results.push(entity);
+            }
+          }
+
+          return results;
+        });
+      },
+
+      addSystem(system: AnySystemShape): Effect.Effect<void> {
+        return Ref.update(systemsRef, (systems) => [...systems, system]);
+      },
+
+      addDenseStore(store: DenseStoreShape): Effect.Effect<void> {
+        return Ref.update(denseStoresRef, (m) => {
+          const next = new Map(m);
+          next.set(store.name, store);
+          return next;
+        });
+      },
+
+      tick(): Effect.Effect<void> {
+        return Effect.gen(function* () {
+          const systems = yield* Ref.get(systemsRef);
+          const denseStores = yield* Ref.get(denseStoresRef);
+
+          for (const system of systems) {
+            if (isDenseSystem(system)) {
+              // Dense path: collect the stores this system queries
+              const queriedStores = new Map<string, DenseStoreShape>();
+              for (const name of system.query) {
+                const store = denseStores.get(name);
+                if (store) queriedStores.set(name, store);
+              }
+              // Only execute if all queried stores exist
+              if (queriedStores.size === system.query.length) {
+                yield* system.execute(queriedStores);
+              }
+            } else {
+              // Regular path: entity-component query
+              const matched = yield* world.query(...system.query);
+              yield* system.execute(matched, world);
+            }
+          }
+        });
+      },
+    };
+
+    return world;
+  });
+}
+
+function isDenseSystem(system: AnySystemShape): system is DenseSystemShape {
+  return '_denseSystem' in system && system._denseSystem === true;
+}
+
+// ---------------------------------------------------------------------------
+// Part namespace -- factories and types
+// ---------------------------------------------------------------------------
+
+function _makeDensePart(name: string, capacity: number): DenseStoreShape {
+  return _makeDenseStore(name, capacity);
+}
+
+/**
+ * Part namespace — factories for ECS component stores.
+ *
+ * Currently exposes the dense `Float64Array`-backed store used for hot-path
+ * numeric state; sparse/object-valued parts are registered ad-hoc via
+ * {@link World}.`addComponent`.
+ */
+export const Part = {
+  /** Allocate a dense component store with fixed capacity. */
+  dense: _makeDensePart,
+} as { dense: (name: string, capacity: number) => DenseStoreShape } & Record<string, never>;
+
+/** World namespace — construct the ECS world that ticks systems over entities. */
+export const World = {
+  /** Scoped Effect that produces a fresh ECS {@link World.Shape}. */
+  make: _makeWorld,
+};
+
+export declare namespace Part {
+  /** Structural shape of a typed component definition (`name` + schema). */
+  export type Shape<T = unknown> = PartShape<T>;
+  /** Alias for the dense `Float64Array`-backed store. */
+  export type Dense = DenseStoreShape;
+}
+
+export declare namespace World {
+  /** Structural shape of an ECS world: spawn/despawn, components, queries, systems, tick. */
+  export type Shape = WorldShape;
+}
+
+export type {
+  EntityShape as Entity,
+  SystemShape as System,
+  DenseSystemShape as DenseSystem,
+  DenseStoreShape as DenseStore,
+};