@czap/core 0.1.0

package/dist/easing.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Easing -- pure math easing functions.
+ *
+ * All functions map t in [0,1] to value in [0,1].
+ * Zero dependencies -- pure arithmetic.
+ *
+ * @module
+ */
+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;
+}
+/**
+ * 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 declare const Easing: EasingFns;
+export declare namespace Easing {
+    /** Signature of an easing function: `(t: [0..1]) => [0..1]`. */
+    type Fn = EasingFnShape;
+    /** Spring parameters: stiffness, damping, mass. */
+    type Config = SpringConfigShape;
+}
+export {};
+//# sourceMappingURL=easing.d.ts.map

package/dist/easing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"easing.d.ts","sourceRoot":"","sources":["../src/easing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,KAAK,aAAa,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;AAE3C,UAAU,iBAAiB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,SAAS;IACjB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,aAAa,CAAC;IACjD,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAAC;IAC3E,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3E,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5E;AAmQD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM,EAAE,SAiBpB,CAAC;AAEF,MAAM,CAAC,OAAO,WAAW,MAAM,CAAC;IAC9B,gEAAgE;IAChE,KAAY,EAAE,GAAG,aAAa,CAAC;IAC/B,mDAAmD;IACnD,KAAY,MAAM,GAAG,iBAAiB,CAAC;CACxC"}

package/dist/easing.js

@@ -0,0 +1,291 @@
+/**
+ * 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';
+/**
+ * Linear easing -- no acceleration, constant rate of change.
+ *
+ * @example
+ * ```ts
+ * Easing.linear(0.5); // 0.5
+ * ```
+ */
+const linear = (t) => t;
+/**
+ * Cubic ease-in -- starts slow, accelerates.
+ *
+ * @example
+ * ```ts
+ * Easing.easeInCubic(0.5); // 0.125
+ * ```
+ */
+const easeInCubic = (t) => t * t * t;
+/**
+ * Cubic ease-out -- starts fast, decelerates.
+ *
+ * @example
+ * ```ts
+ * Easing.easeOutCubic(0.5); // 0.875
+ * ```
+ */
+const easeOutCubic = (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 = (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 = (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 = (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 = (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 = (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, y1, x2, y2) {
+    return (t) => {
+        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, omega, zeta) {
+    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) {
+    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, epsilon = 0.001) {
+    _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) {
+    _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) => {
+        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, sampleCount = 32) {
+    const fn = spring(config);
+    const points = [];
+    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 = {
+    linear,
+    easeInCubic,
+    easeOutCubic,
+    easeInOutCubic,
+    easeOutExpo,
+    easeOutBack,
+    easeOutElastic,
+    easeOutBounce,
+    ease,
+    easeIn,
+    easeOut,
+    easeInOut,
+    spring,
+    cubicBezier,
+    springToLinearCSS,
+    springNaturalDuration,
+};
+//# sourceMappingURL=easing.js.map

package/dist/easing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"easing.js","sourceRoot":"","sources":["../src/easing.ts"],"names":[],"mappings":"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"}

package/dist/ecs.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 } 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 declare const EntityId: (value: string) => EntityId;
+interface EntityShape {
+    readonly id: EntityId;
+    readonly components: ReadonlyMap<string, unknown>;
+}
+interface PartShape<T = unknown> {
+    readonly name: string;
+    readonly schema: Schema.Schema<T>;
+}
+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[];
+}
+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>;
+}
+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;
+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>;
+}
+declare function _makeWorld(): Effect.Effect<WorldShape, never, Scope.Scope>;
+/**
+ * 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 declare const Part: {
+    dense: (name: string, capacity: number) => DenseStoreShape;
+} & Record<string, never>;
+/** World namespace — construct the ECS world that ticks systems over entities. */
+export declare const World: {
+    /** Scoped Effect that produces a fresh ECS {@link World.Shape}. */
+    make: typeof _makeWorld;
+};
+export declare namespace Part {
+    /** Structural shape of a typed component definition (`name` + schema). */
+    type Shape<T = unknown> = PartShape<T>;
+    /** Alias for the dense `Float64Array`-backed store. */
+    type Dense = DenseStoreShape;
+}
+export declare namespace World {
+    /** Structural shape of an ECS world: spawn/despawn, components, queries, systems, tick. */
+    type Shape = WorldShape;
+}
+export type { EntityShape as Entity, SystemShape as System, DenseSystemShape as DenseSystem, DenseStoreShape as DenseStore, };
+//# sourceMappingURL=ecs.d.ts.map

package/dist/ecs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecs.d.ts","sourceRoot":"","sources":["../src/ecs.ts"],"names":[],"mappings":"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"}