@holoscript/core 8.0.8 → 8.0.9

package/dist/traitDocs/traitDocs.cjs

@@ -1,33 +1,33 @@
 'use strict';
 
-var chunk5FSKKMR7_cjs = require('../chunk-5FSKKMR7.cjs');
-require('../chunk-HCCQLAA4.cjs');
+var chunk7IDJDMPU_cjs = require('../chunk-7IDJDMPU.cjs');
+require('../chunk-ZHPMP447.cjs');
 
-chunk5FSKKMR7_cjs.init_traitDocs();
+chunk7IDJDMPU_cjs.init_traitDocs();
 
 Object.defineProperty(exports, "TRAIT_DOCS", {
   enumerable: true,
-  get: function () { return chunk5FSKKMR7_cjs.TRAIT_DOCS; }
+  get: function () { return chunk7IDJDMPU_cjs.TRAIT_DOCS; }
 });
 Object.defineProperty(exports, "formatTraitDocAsMarkdown", {
   enumerable: true,
-  get: function () { return chunk5FSKKMR7_cjs.formatTraitDocAsMarkdown; }
+  get: function () { return chunk7IDJDMPU_cjs.formatTraitDocAsMarkdown; }
 });
 Object.defineProperty(exports, "formatTraitDocCompact", {
   enumerable: true,
-  get: function () { return chunk5FSKKMR7_cjs.formatTraitDocCompact; }
+  get: function () { return chunk7IDJDMPU_cjs.formatTraitDocCompact; }
 });
 Object.defineProperty(exports, "getAllTraitNames", {
   enumerable: true,
-  get: function () { return chunk5FSKKMR7_cjs.getAllTraitNames; }
+  get: function () { return chunk7IDJDMPU_cjs.getAllTraitNames; }
 });
 Object.defineProperty(exports, "getTraitDoc", {
   enumerable: true,
-  get: function () { return chunk5FSKKMR7_cjs.getTraitDoc; }
+  get: function () { return chunk7IDJDMPU_cjs.getTraitDoc; }
 });
 Object.defineProperty(exports, "getTraitsByCategory", {
   enumerable: true,
-  get: function () { return chunk5FSKKMR7_cjs.getTraitsByCategory; }
+  get: function () { return chunk7IDJDMPU_cjs.getTraitsByCategory; }
 });
 //# sourceMappingURL=traitDocs.cjs.map
 //# sourceMappingURL=traitDocs.cjs.map

package/dist/traitDocs/traitDocs.d.ts

@@ -23,6 +23,7 @@ export interface PropertyDoc {
     description: string;
     default?: string;
     required?: boolean;
+    range?: [number, number];
 }
 export interface MethodDoc {
     name: string;

package/dist/traitDocs/traitDocs.js

@@ -1,6 +1,6 @@
-import { init_traitDocs } from '../chunk-THCK6ECW.js';
-export { TRAIT_DOCS, formatTraitDocAsMarkdown, formatTraitDocCompact, getAllTraitNames, getTraitDoc, getTraitsByCategory } from '../chunk-THCK6ECW.js';
-import '../chunk-OL46QLBJ.js';
+import { init_traitDocs } from '../chunk-B3CWTCK2.js';
+export { TRAIT_DOCS, formatTraitDocAsMarkdown, formatTraitDocCompact, getAllTraitNames, getTraitDoc, getTraitsByCategory } from '../chunk-B3CWTCK2.js';
+import '../chunk-W4GABFCR.js';
 
 init_traitDocs();
 //# sourceMappingURL=traitDocs.js.map

package/dist/traits/ControlLoopTrait.d.ts

@@ -0,0 +1,154 @@
+/**
+ * ControlLoopTrait — PID and Model-Predictive Control (MPC) in a single trait (H2).
+ *
+ * ## PID controller
+ *
+ * Classic discrete-time PID with anti-windup integral clamping and optional
+ * derivative filtering:
+ *
+ *   u[k] = Kp·e[k] + Ki·Σe·dt + Kd·(e[k]-e[k-1])/dt
+ *
+ * Anti-windup: integral is clamped to [-iMax, iMax] every step.
+ * Derivative filter: optional first-order low-pass on the derivative term
+ *   (d_filtered = α·d_raw + (1-α)·d_prev, α = filterCoeff ∈ (0,1]).
+ * Output saturation: optional [outputMin, outputMax] clamp on the final u.
+ *
+ * ## Linear MPC (receding-horizon)
+ *
+ * State-space: x[k+1] = A·x[k] + B·u[k]
+ * Objective  : min Σ_{i=0}^{H-1}(x[i]^T Q x[i] + u[i]^T R u[i]) + x[H]^T Qf x[H]
+ * Constraint : u ∈ [uMin, uMax] (element-wise, applied after unconstrained solve)
+ *
+ * Unconstrained horizon solution via recursive Riccati descent, then project
+ * each u_i into [uMin, uMax]. Linear MPC is returned as the optimal first
+ * control action u[0] from the computed horizon.
+ *
+ * ## Domain-neutrality
+ *
+ * No domain nouns appear here. The controllers apply to robotics, HVAC,
+ * process control, animation, or any closed-loop system.
+ *
+ * ## Trait usage
+ *
+ *   onAttach: resets internal state.
+ *   onEvent 'control_loop.step':
+ *     - type='pid' → PID step → result on node.__control_output.
+ *     - type='mpc' → MPC horizon solve → result on node.__control_output.
+ *   onEvent 'control_loop.reset': clears integral/derivative state.
+ */
+import type { TraitHandler } from './TraitTypes';
+/** Result of a single control step. */
+export interface ControlOutput {
+    /** Computed control action. */
+    u: number;
+    /** Type of controller that produced this output. */
+    type: 'pid' | 'mpc';
+    /** PID-only: proportional contribution. */
+    proportional?: number;
+    /** PID-only: integral contribution (post-windup). */
+    integral?: number;
+    /** PID-only: derivative contribution (post-filter). */
+    derivative?: number;
+    /** MPC-only: full computed horizon [u0, u1, ..., u_{H-1}]. */
+    horizon?: number[];
+}
+/** PID tuning parameters. */
+export interface PIDParams {
+    /** Proportional gain. */
+    Kp: number;
+    /** Integral gain. */
+    Ki: number;
+    /** Derivative gain. */
+    Kd: number;
+    /** Integral anti-windup clamp (magnitude). Default: Infinity. */
+    iMax?: number;
+    /** Derivative low-pass filter coefficient α ∈ (0,1]. 1 = no filter. Default: 1. */
+    filterCoeff?: number;
+    /** Output lower bound. Default: -Infinity. */
+    outputMin?: number;
+    /** Output upper bound. Default: +Infinity. */
+    outputMax?: number;
+}
+/**
+ * Input for a PID step event (`control_loop.pid_step`).
+ * The `type` field on the event itself is the event name; this interface
+ * carries only the step payload.
+ */
+export interface PIDStepRequest {
+    /** PID tuning. Falls back to config.pid when omitted. */
+    params?: PIDParams;
+    /** Setpoint (reference). */
+    setpoint: number;
+    /** Measured process variable. */
+    measurement: number;
+    /** Time step Δt (same units as Ki/Kd). Default: 1. */
+    dt?: number;
+}
+/** Internal PID state (stored on the trait). */
+export interface PIDState {
+    integralAccum: number;
+    prevError: number;
+    prevDerivative: number;
+}
+/** Linear time-invariant state-space matrices for MPC. */
+export interface MPCModel {
+    /** State transition matrix A (n×n, row-major). */
+    A: number[];
+    /** Input matrix B (n×m, row-major). */
+    B: number[];
+    /** State dimension n. */
+    n: number;
+    /** Input dimension m. */
+    m: number;
+}
+/** MPC tuning and horizon parameters. */
+export interface MPCParams {
+    /** State-space model. */
+    model: MPCModel;
+    /** Prediction horizon. Default: 10. */
+    horizon?: number;
+    /** State cost matrix Q (n×n, row-major). Default: identity. */
+    Q?: number[];
+    /** Terminal state cost matrix Qf (n×n, row-major). Default: Q. */
+    Qf?: number[];
+    /** Input cost matrix R (m×m, row-major). Default: identity. */
+    R?: number[];
+    /** Element-wise input lower bound (length m). Default: -Infinity. */
+    uMin?: number[];
+    /** Element-wise input upper bound (length m). Default: +Infinity. */
+    uMax?: number[];
+}
+/**
+ * Input for an MPC step event (`control_loop.mpc_step`).
+ * The `type` field on the event itself is the event name; this interface
+ * carries only the step payload.
+ */
+export interface MPCStepRequest {
+    /** MPC parameters. Falls back to config.mpc when omitted. */
+    params?: MPCParams;
+    /** Current state vector x (length n). */
+    state: number[];
+    /** Reference state trajectory (H×n, row-major). Defaults to all-zero. */
+    reference?: number[];
+}
+/** Trait configuration — at least one of pid or mpc must be set to use events. */
+export interface ControlLoopConfig {
+    /** Default PID parameters (used when event omits params). */
+    pid?: PIDParams;
+    /** Default MPC parameters (used when event omits params). */
+    mpc?: MPCParams;
+}
+/**
+ * Discrete-time PID step. Mutates `state` in place.
+ */
+export declare function stepPid(params: PIDParams, setpoint: number, measurement: number, dt: number, state: PIDState): ControlOutput;
+/**
+ * Linear MPC with receding horizon.
+ *
+ * Uses backward Riccati recursion to compute unconstrained optimal gains,
+ * then projects each control input into [uMin, uMax] element-wise.
+ * Returns the first control action u[0] as `u`, with the full horizon in
+ * `output.horizon`.
+ */
+export declare function stepMpc(params: MPCParams, state: number[]): ControlOutput;
+export declare const controlLoopHandler: TraitHandler<ControlLoopConfig>;

package/dist/traits/KinematicChainTrait.d.ts

@@ -0,0 +1,116 @@
+/**
+ * KinematicChainTrait — DH-parameter FK + damped Jacobian IK (H2).
+ *
+ * Provides forward kinematics (FK) and inverse kinematics (IK) for serial
+ * kinematic chains described by standard Denavit-Hartenberg parameters.
+ *
+ * ## DH Convention (Standard)
+ *
+ * Each row of the DH table defines the transform from frame i-1 to frame i:
+ *
+ *   T_{i-1,i} = Rot_z(θ_i) · Trans_z(d_i) · Trans_x(a_i) · Rot_x(α_i)
+ *
+ * Row-major 4×4 matrix form:
+ *   [ cos θ,  -sin θ cos α,   sin θ sin α,  a cos θ ]
+ *   [ sin θ,   cos θ cos α,  -cos θ sin α,  a sin θ ]
+ *   [   0,       sin α,         cos α,        d     ]
+ *   [   0,         0,             0,           1    ]
+ *
+ * where θ = thetaOffset + jointAngle (constant offset + variable q_i).
+ *
+ * ## IK: damped Jacobian (Levenberg-Marquardt)
+ *
+ * Position-only IK. 3×n Jacobian column j: J[:,j] = z_{j-1} × (p_ee - p_{j-1}).
+ * Update: dq = J^T (JJ^T + λ²I)⁻¹ Δp. Converges in ≤ 100 iterations for
+ * well-conditioned chains.
+ *
+ * ## Domain-neutrality
+ *
+ * No domain nouns appear here. The solver applies to robotics, animation,
+ * biomechanics, and any articulated structure.
+ *
+ * ## Trait usage
+ *
+ *   onAttach: pre-computes FK from initial config if links/angles are set.
+ *   onEvent 'kinematic_chain.solve_fk': FK → result on node.__kinematic_fk.
+ *   onEvent 'kinematic_chain.solve_ik': IK → result on node.__kinematic_ik.
+ */
+import type { TraitHandler } from './TraitTypes';
+/** One row of the standard Denavit-Hartenberg parameter table. */
+export interface DHParameter {
+    /** Link length (scene units). */
+    a: number;
+    /** Link twist α (radians). */
+    alpha: number;
+    /** Joint offset d along z (scene units). */
+    d: number;
+    /** Constant joint angle offset (radians). Added to the variable q_i. */
+    theta: number;
+}
+/** Trait configuration — DH table plus current joint angles. */
+export interface KinematicChainConfig {
+    /** DH table — one row per joint. */
+    links: DHParameter[];
+    /** Current joint angles q (radians). Length must equal `links.length`. */
+    jointAngles: number[];
+}
+/** Result of forward kinematics. */
+export interface FKResult {
+    /** End-effector position in the base frame. */
+    endEffectorPosition: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Full 4×4 end-effector transform (row-major, 16 elements). */
+    endEffectorTransform: number[];
+    /** Per-joint frame transforms (row-major 4×4), indexed 0..n-1. */
+    frameTransforms: number[][];
+}
+/** Input to the IK solver. */
+export interface IKRequest {
+    /** DH table — one row per joint. */
+    links: DHParameter[];
+    /** Target end-effector position in the base frame. */
+    target: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Initial joint angles. Defaults to all-zero. */
+    initialAngles?: number[];
+    /** Maximum iterations. Default: 100. */
+    maxIterations?: number;
+    /** Convergence tolerance (scene units). Default: 1e-4. */
+    tolerance?: number;
+    /** Damping factor λ for LM update. Default: 0.01. */
+    damping?: number;
+}
+/** Result of inverse kinematics. */
+export interface IKResult {
+    /** Joint angles that achieve (approximately) the target. */
+    jointAngles: number[];
+    /** True when final error is below tolerance. */
+    converged: boolean;
+    /** Final end-effector position error. */
+    finalError: number;
+    /** Iterations used. */
+    iterations: number;
+}
+/**
+ * Standard DH homogeneous transform (row-major, 16 elements).
+ * Index [row*4 + col].
+ */
+export declare function dhTransform(a: number, alpha: number, d: number, theta: number): number[];
+/**
+ * Forward kinematics — compute end-effector pose from DH table + joint angles.
+ */
+export declare function solveFk(links: DHParameter[], jointAngles: number[]): FKResult;
+/**
+ * Position-only IK using a damped Jacobian (Levenberg-Marquardt).
+ *
+ * Converges in ≤ `maxIterations` steps. Returns `converged: true` when the
+ * end-effector position is within `tolerance` of `target`.
+ */
+export declare function solveIk(req: IKRequest): IKResult;
+export declare const kinematicChainHandler: TraitHandler<KinematicChainConfig>;

package/dist/traits/SensorSamplingTrait.d.ts

@@ -0,0 +1,154 @@
+/**
+ * SensorSamplingTrait — domain-neutral signal acquisition with noise models
+ * and ring-buffer windowing (H2 'sensor' family).
+ *
+ * Sensors are identified by string IDs. Each sensor has a configurable noise
+ * model applied to incoming raw readings before buffering. A fixed-capacity
+ * ring buffer stores the last N readings per sensor, enabling simple windowed
+ * statistics (mean, variance, min, max) without external state management.
+ *
+ * ## Noise models
+ *
+ *   - `'none'`       — raw value passed through unchanged.
+ *   - `'gaussian'`   — additive Gaussian noise N(0, σ²) via Box-Muller.
+ *   - `'uniform'`    — additive uniform noise U(−range, +range).
+ *   - `'quantized'`  — round to nearest `step`, then optional gaussian.
+ *
+ * ## Domain-neutrality
+ *
+ * No domain nouns appear here. The same trait covers:
+ *   - Robotics: joint-angle encoders, IMU, force/torque sensors.
+ *   - IoT: temperature, pressure, humidity, flow.
+ *   - Scientific: spectral intensity, particle count, magnetic field.
+ *   - Quantum: qubit readout (binary sensor, bit-flip noise via bernoulli).
+ *
+ * ## Trait usage
+ *
+ *   onAttach: initialises per-sensor ring buffers from config.
+ *   onEvent 'sensor.record': record a raw reading → apply noise → buffer →
+ *     write result to node.__sensor_last[sensorId].
+ *   onEvent 'sensor.read_window': compute windowed stats for a sensor →
+ *     write to node.__sensor_window[sensorId].
+ *   onEvent 'sensor.reset': clear all buffers.
+ */
+import type { TraitHandler } from './TraitTypes';
+/** Gaussian noise: additive N(0, σ²). */
+export interface GaussianNoise {
+    type: 'gaussian';
+    /** Standard deviation σ. */
+    sigma: number;
+}
+/** Uniform noise: additive U(−range, +range). */
+export interface UniformNoise {
+    type: 'uniform';
+    /** Half-width of the uniform distribution. */
+    range: number;
+}
+/**
+ * Quantization noise: round to nearest `step`, then optional Gaussian.
+ * Models ADC quantization (and binary sensors when step=1).
+ */
+export interface QuantizedNoise {
+    type: 'quantized';
+    /** Quantization step (e.g. 0.01 for a 2-decimal sensor). */
+    step: number;
+    /** Optional residual Gaussian σ after quantization. Default: 0. */
+    residualSigma?: number;
+}
+/** No noise — raw value passed through. */
+export interface NoNoise {
+    type: 'none';
+}
+export type NoiseModel = GaussianNoise | UniformNoise | QuantizedNoise | NoNoise;
+/** Configuration for one sensor channel. */
+export interface SensorChannelConfig {
+    /** Unique sensor identifier. */
+    id: string;
+    /** Human-readable unit label (e.g. 'm/s²', '°C', 'rad'). Not interpreted. */
+    unit?: string;
+    /** Noise model applied to incoming raw readings. Default: none. */
+    noise?: NoiseModel;
+    /** Ring-buffer capacity (number of readings to keep). Default: 32. */
+    bufferSize?: number;
+}
+/** Trait configuration — list of sensor channels. */
+export interface SensorSamplingConfig {
+    /** Sensor channels to initialise. */
+    sensors: SensorChannelConfig[];
+}
+/** A raw + noisy reading for one sensor. */
+export interface SensorReading {
+    /** Sensor identifier. */
+    sensorId: string;
+    /** Raw (pre-noise) value. */
+    rawValue: number;
+    /** Value after noise application. */
+    noisyValue: number;
+    /** Monotonic timestamp (caller-supplied, e.g. simulation tick). */
+    timestamp: number;
+}
+/** Windowed statistics over a sensor's ring buffer. */
+export interface SensorWindowResult {
+    sensorId: string;
+    /** All buffered readings (oldest → newest). */
+    readings: ReadonlyArray<SensorReading>;
+    /** Number of readings in the buffer. */
+    count: number;
+    /** Arithmetic mean of noisyValue. NaN if buffer empty. */
+    mean: number;
+    /** Sample variance of noisyValue. NaN if fewer than 2 readings. */
+    variance: number;
+    /** Minimum noisyValue. Infinity if buffer empty. */
+    min: number;
+    /** Maximum noisyValue. -Infinity if buffer empty. */
+    max: number;
+}
+/** Payload for `sensor.record` event. */
+export interface SensorRecordRequest {
+    /** Target sensor. If omitted and config has exactly one sensor, uses that. */
+    sensorId?: string;
+    /** Raw measured value. */
+    rawValue: number;
+    /** Monotonic timestamp. Default: 0. */
+    timestamp?: number;
+    /** Override noise model for this recording only. */
+    noise?: NoiseModel;
+}
+/** Payload for `sensor.read_window` event. */
+export interface SensorReadWindowRequest {
+    /** Target sensor. If omitted, uses the first configured sensor. */
+    sensorId?: string;
+}
+/**
+ * Box-Muller transform: generates one N(0,1) sample using two U(0,1) inputs.
+ * Pure function — callers supply the uniform random values to enable testing.
+ */
+export declare function boxMuller(u1: number, u2: number): number;
+/**
+ * Apply a noise model to a raw value. Uses `Math.random()` for stochastic
+ * models — determinism in tests can be achieved by mocking Math.random.
+ */
+export declare function applyNoise(raw: number, noise: NoiseModel): number;
+/** Fixed-capacity circular buffer of SensorReadings. */
+export declare class SensorRingBuffer {
+    readonly capacity: number;
+    private readonly buf;
+    private head;
+    private _size;
+    constructor(capacity: number);
+    push(r: SensorReading): void;
+    get size(): number;
+    /** Returns readings oldest-first. */
+    toArray(): SensorReading[];
+    latest(): SensorReading | undefined;
+    clear(): void;
+}
+/**
+ * Record one reading: apply noise, return the SensorReading.
+ * Callers are responsible for buffering (the TraitHandler does this via the
+ * node's internal buffer map).
+ */
+export declare function recordReading(rawValue: number, noise: NoiseModel, sensorId: string, timestamp: number): SensorReading;
+/** Compute windowed statistics over a ring buffer's current contents. */
+export declare function computeWindowStats(sensorId: string, buffer: SensorRingBuffer): SensorWindowResult;
+export declare const sensorSamplingHandler: TraitHandler<SensorSamplingConfig>;