@horizon36596/zenith-core 0.1.1

package/dist/geometry/quadrature.js

@@ -0,0 +1,57 @@
+const cache = new Map();
+/** P_n(x) and its derivative, by the standard three-term recurrence. */
+function legendre(n, x) {
+    let previous = 1;
+    let current = x;
+    for (let k = 2; k <= n; k += 1) {
+        const next = ((2 * k - 1) * x * current - (k - 1) * previous) / k;
+        previous = current;
+        current = next;
+    }
+    if (n === 0)
+        return { value: 1, derivative: 0 };
+    const derivative = (n * (x * current - previous)) / (x * x - 1);
+    return { value: current, derivative };
+}
+export function gaussLegendre(order) {
+    const cached = cache.get(order);
+    if (cached !== undefined)
+        return cached;
+    const nodes = [];
+    const weights = [];
+    const half = Math.floor((order + 1) / 2);
+    for (let i = 1; i <= half; i += 1) {
+        // Chebyshev-like first guess, then Newton to machine precision.
+        let x = Math.cos((Math.PI * (i - 0.25)) / (order + 0.5));
+        for (let iteration = 0; iteration < 100; iteration += 1) {
+            const { value, derivative } = legendre(order, x);
+            const step = value / derivative;
+            x -= step;
+            if (Math.abs(step) < 1e-15)
+                break;
+        }
+        const { derivative } = legendre(order, x);
+        const weight = 2 / ((1 - x * x) * derivative * derivative);
+        nodes.push(-x);
+        weights.push(weight);
+        if (i !== order - i + 1) {
+            nodes.push(x);
+            weights.push(weight);
+        }
+    }
+    const quadrature = { nodes, weights };
+    cache.set(order, quadrature);
+    return quadrature;
+}
+/** Integrates f over [a, b] with an `order`-point Gauss-Legendre rule. */
+export function integrate(f, a, b, order) {
+    const { nodes, weights } = gaussLegendre(order);
+    const half = (b - a) / 2;
+    const middle = (a + b) / 2;
+    let sum = 0;
+    for (let i = 0; i < nodes.length; i += 1) {
+        sum += weights[i] * f(middle + half * nodes[i]);
+    }
+    return sum * half;
+}
+//# sourceMappingURL=quadrature.js.map

package/dist/geometry/quadrature.js.map

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

package/dist/geometry/sat.d.ts

@@ -0,0 +1,40 @@
+import { type Vec2 } from "./vec.js";
+/** An axis-aligned box in the field frame: obstacles, zones and the field perimeter are these. */
+export interface Box2 {
+    minXIn: number;
+    maxXIn: number;
+    minYIn: number;
+    maxYIn: number;
+}
+/** A rectangle carried by the robot: centre, size and the heading it is rotated to. */
+export interface Rect {
+    centreIn: Vec2;
+    lengthIn: number;
+    widthIn: number;
+    headingRad: number;
+}
+/** The four corners, counter-clockwise, of a rotated rectangle. */
+export declare function rectCorners(rect: Rect): Vec2[];
+export declare const boxCorners: (box: Box2) => Vec2[];
+export interface OverlapResult {
+    overlaps: boolean;
+    /** How deep the overlap is on its shallowest separating axis, in inches; 0 when apart. */
+    penetrationIn: number;
+}
+/**
+ * Separating-axis test between a convex polygon (the robot's rotated footprint or a mouth box) and
+ * an axis-aligned box (an obstacle). site/docs/checks-and-findings.md asks for
+ * the deepest penetration, which is the smallest overlap over the candidate axes.
+ */
+export declare function polygonOverlapsBox(polygon: readonly Vec2[], box: Box2): OverlapResult;
+/** True when the point is inside the box, edges included. */
+export declare const pointInBox: (point: Vec2, box: Box2) => boolean;
+export interface OutsideResult {
+    outside: boolean;
+    /** The furthest any corner is outside the box, in inches. */
+    worstIn: number;
+    worstPointIn: Vec2 | null;
+}
+/** How far a polygon pokes out of a box. The PERIMETER check reads `worstIn`. */
+export declare function polygonOutsideBox(polygon: readonly Vec2[], box: Box2): OutsideResult;
+//# sourceMappingURL=sat.d.ts.map

package/dist/geometry/sat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sat.d.ts","sourceRoot":"","sources":["../../src/geometry/sat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,IAAI,EAAE,MAAM,UAAU,CAAC;AAElD,kGAAkG;AAClG,MAAM,WAAW,IAAI;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uFAAuF;AACvF,MAAM,WAAW,IAAI;IACnB,QAAQ,EAAE,IAAI,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,CAU9C;AAED,eAAO,MAAM,UAAU,GAAI,KAAK,IAAI,KAAG,IAAI,EAK1C,CAAC;AA+BF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,0FAA0F;IAC1F,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,aAAa,CAerF;AAED,6DAA6D;AAC7D,eAAO,MAAM,UAAU,GAAI,OAAO,IAAI,EAAE,KAAK,IAAI,KAAG,OAI3B,CAAC;AAE1B,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;CAC3B;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,aAAa,CAgBpF"}

package/dist/geometry/sat.js

@@ -0,0 +1,86 @@
+import { add, rotate } from "./vec.js";
+/** The four corners, counter-clockwise, of a rotated rectangle. */
+export function rectCorners(rect) {
+    const halfLength = rect.lengthIn / 2;
+    const halfWidth = rect.widthIn / 2;
+    const local = [
+        { xIn: halfLength, yIn: halfWidth },
+        { xIn: -halfLength, yIn: halfWidth },
+        { xIn: -halfLength, yIn: -halfWidth },
+        { xIn: halfLength, yIn: -halfWidth },
+    ];
+    return local.map((corner) => add(rect.centreIn, rotate(corner, rect.headingRad)));
+}
+export const boxCorners = (box) => [
+    { xIn: box.minXIn, yIn: box.minYIn },
+    { xIn: box.maxXIn, yIn: box.minYIn },
+    { xIn: box.maxXIn, yIn: box.maxYIn },
+    { xIn: box.minXIn, yIn: box.maxYIn },
+];
+function project(points, axis) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (const point of points) {
+        const value = point.xIn * axis.xIn + point.yIn * axis.yIn;
+        if (value < min)
+            min = value;
+        if (value > max)
+            max = value;
+    }
+    return { min, max };
+}
+function axesOf(polygon) {
+    const axes = [];
+    for (let i = 0; i < polygon.length; i += 1) {
+        const a = polygon[i];
+        const b = polygon[(i + 1) % polygon.length];
+        const edge = { xIn: b.xIn - a.xIn, yIn: b.yIn - a.yIn };
+        const normalLength = Math.hypot(edge.xIn, edge.yIn);
+        if (normalLength < 1e-12)
+            continue;
+        axes.push({ xIn: -edge.yIn / normalLength, yIn: edge.xIn / normalLength });
+    }
+    return axes;
+}
+/**
+ * Separating-axis test between a convex polygon (the robot's rotated footprint or a mouth box) and
+ * an axis-aligned box (an obstacle). site/docs/checks-and-findings.md asks for
+ * the deepest penetration, which is the smallest overlap over the candidate axes.
+ */
+export function polygonOverlapsBox(polygon, box) {
+    const worldAxes = [
+        { xIn: 1, yIn: 0 },
+        { xIn: 0, yIn: 1 },
+    ];
+    const corners = boxCorners(box);
+    let smallest = Infinity;
+    for (const axis of [...axesOf(polygon), ...worldAxes]) {
+        const a = project(polygon, axis);
+        const b = project(corners, axis);
+        const overlap = Math.min(a.max, b.max) - Math.max(a.min, b.min);
+        if (overlap <= 0)
+            return { overlaps: false, penetrationIn: 0 };
+        if (overlap < smallest)
+            smallest = overlap;
+    }
+    return { overlaps: true, penetrationIn: smallest };
+}
+/** True when the point is inside the box, edges included. */
+export const pointInBox = (point, box) => point.xIn >= box.minXIn &&
+    point.xIn <= box.maxXIn &&
+    point.yIn >= box.minYIn &&
+    point.yIn <= box.maxYIn;
+/** How far a polygon pokes out of a box. The PERIMETER check reads `worstIn`. */
+export function polygonOutsideBox(polygon, box) {
+    let worstIn = 0;
+    let worstPointIn = null;
+    for (const point of polygon) {
+        const out = Math.max(box.minXIn - point.xIn, point.xIn - box.maxXIn, box.minYIn - point.yIn, point.yIn - box.maxYIn);
+        if (out > worstIn) {
+            worstIn = out;
+            worstPointIn = point;
+        }
+    }
+    return { outside: worstPointIn !== null, worstIn, worstPointIn };
+}
+//# sourceMappingURL=sat.js.map

package/dist/geometry/sat.js.map

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

package/dist/geometry/vec.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Points and poses in the field frame. Units are inches and radians throughout core, and every key
+ * names its unit, the same as the files do (CLAUDE.md rule 3).
+ */
+export interface Vec2 {
+    xIn: number;
+    yIn: number;
+}
+export interface Pose extends Vec2 {
+    headingRad: number;
+}
+export declare const vec: (xIn: number, yIn: number) => Vec2;
+export declare const pose: (xIn: number, yIn: number, headingRad: number) => Pose;
+export declare const add: (a: Vec2, b: Vec2) => Vec2;
+export declare const sub: (a: Vec2, b: Vec2) => Vec2;
+export declare const scale: (a: Vec2, k: number) => Vec2;
+export declare const dot: (a: Vec2, b: Vec2) => number;
+/** The 2-D cross product's z component; positive when b is counter-clockwise from a. */
+export declare const cross: (a: Vec2, b: Vec2) => number;
+export declare const length: (a: Vec2) => number;
+export declare const distance: (a: Vec2, b: Vec2) => number;
+export declare function normalize(a: Vec2): Vec2;
+/** Rotates about the origin by `rad`, counter-clockwise, which is the field's positive direction. */
+export declare function rotate(a: Vec2, rad: number): Vec2;
+/** Straight-line interpolation. Headings are interpolated by lerpAngle, not by this. */
+export declare const lerp: (a: Vec2, b: Vec2, t: number) => Vec2;
+//# sourceMappingURL=vec.d.ts.map

package/dist/geometry/vec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vec.d.ts","sourceRoot":"","sources":["../../src/geometry/vec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,IAAI;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,IAAK,SAAQ,IAAI;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,GAAG,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,IAAsB,CAAC;AAEtE,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,YAAY,MAAM,KAAG,IAIlE,CAAC;AAEH,eAAO,MAAM,GAAG,GAAI,GAAG,IAAI,EAAE,GAAG,IAAI,KAAG,IAAoD,CAAC;AAE5F,eAAO,MAAM,GAAG,GAAI,GAAG,IAAI,EAAE,GAAG,IAAI,KAAG,IAAoD,CAAC;AAE5F,eAAO,MAAM,KAAK,GAAI,GAAG,IAAI,EAAE,GAAG,MAAM,KAAG,IAA4C,CAAC;AAExF,eAAO,MAAM,GAAG,GAAI,GAAG,IAAI,EAAE,GAAG,IAAI,KAAG,MAAuC,CAAC;AAE/E,wFAAwF;AACxF,eAAO,MAAM,KAAK,GAAI,GAAG,IAAI,EAAE,GAAG,IAAI,KAAG,MAAuC,CAAC;AAEjF,eAAO,MAAM,MAAM,GAAI,GAAG,IAAI,KAAG,MAAkC,CAAC;AAEpE,eAAO,MAAM,QAAQ,GAAI,GAAG,IAAI,EAAE,GAAG,IAAI,KAAG,MAAkD,CAAC;AAE/F,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAGvC;AAED,qGAAqG;AACrG,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAIjD;AAED,wFAAwF;AACxF,eAAO,MAAM,IAAI,GAAI,GAAG,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,KAAG,IAGjD,CAAC"}

package/dist/geometry/vec.js

@@ -0,0 +1,30 @@
+export const vec = (xIn, yIn) => ({ xIn, yIn });
+export const pose = (xIn, yIn, headingRad) => ({
+    xIn,
+    yIn,
+    headingRad,
+});
+export const add = (a, b) => ({ xIn: a.xIn + b.xIn, yIn: a.yIn + b.yIn });
+export const sub = (a, b) => ({ xIn: a.xIn - b.xIn, yIn: a.yIn - b.yIn });
+export const scale = (a, k) => ({ xIn: a.xIn * k, yIn: a.yIn * k });
+export const dot = (a, b) => a.xIn * b.xIn + a.yIn * b.yIn;
+/** The 2-D cross product's z component; positive when b is counter-clockwise from a. */
+export const cross = (a, b) => a.xIn * b.yIn - a.yIn * b.xIn;
+export const length = (a) => Math.hypot(a.xIn, a.yIn);
+export const distance = (a, b) => Math.hypot(a.xIn - b.xIn, a.yIn - b.yIn);
+export function normalize(a) {
+    const len = length(a);
+    return len === 0 ? { xIn: 0, yIn: 0 } : { xIn: a.xIn / len, yIn: a.yIn / len };
+}
+/** Rotates about the origin by `rad`, counter-clockwise, which is the field's positive direction. */
+export function rotate(a, rad) {
+    const cos = Math.cos(rad);
+    const sin = Math.sin(rad);
+    return { xIn: a.xIn * cos - a.yIn * sin, yIn: a.xIn * sin + a.yIn * cos };
+}
+/** Straight-line interpolation. Headings are interpolated by lerpAngle, not by this. */
+export const lerp = (a, b, t) => ({
+    xIn: a.xIn + (b.xIn - a.xIn) * t,
+    yIn: a.yIn + (b.yIn - a.yIn) * t,
+});
+//# sourceMappingURL=vec.js.map

package/dist/geometry/vec.js.map

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

package/dist/heading.d.ts

@@ -0,0 +1,77 @@
+import type { Heading, HeadingRange } from "@horizon36596/zenith-schema";
+import type { PathGeometry } from "./geometry/path.js";
+/** The direction of travel at t, wrapped to (-pi, pi]. */
+export declare function tangentHeading(path: PathGeometry, t: number): number;
+type LinearHeading = Extract<Heading, {
+    mode: "linear";
+}>;
+/**
+ * How far past half a turn a piece may ask before HEADING calls it reversed. Canonical form rounds
+ * radians to four decimals, so the half turn the editor writes, 3.1416, is a hair over pi; either
+ * way round is the same half turn to the person who wrote it, and the robot's choice is drawn.
+ */
+export declare const HALF_TURN_TOLERANCE_RAD = 0.001;
+/** One segment's share of a `linear` heading, the way the robot runtime hands it to Pedro. */
+export interface LinearHeadingPiece {
+    /** Where the piece starts and ends along the step, as arc-length fractions. */
+    startT: number;
+    endT: number;
+    /** The headings the runtime passes to Pedro's `Path.linear(from, to)` for this segment. */
+    fromRad: number;
+    toRad: number;
+    /** The turn the robot actually makes over the piece: the short way from `fromRad` to `toRad`. */
+    turnRad: number;
+    /**
+     * True when the piece asks for more than half a turn (past `HALF_TURN_TOLERANCE_RAD`), so the
+     * robot turns the other way round from the one the file wrote.
+     */
+    reversed: boolean;
+}
+/**
+ * The pieces of a `linear` heading, one per segment, cut exactly as
+ * `robot/auto-runtime/PathBuilder.withHeading` cuts them: the sweep `toRad - fromRad` the file wrote
+ * is shared out by arc length, and each segment gets `Path.linear(from, to)` over its share. Pedro's
+ * `Interpolator.linear` then turns the short way, so a share of
+ * more than half a turn goes the other way round on the robot. A deliberate 270 degree sweep split
+ * over two segments of equal length therefore does turn 270 degrees, and the same sweep on one
+ * segment turns 90 degrees the other way.
+ */
+export declare function linearHeadingPieces(heading: LinearHeading, path: PathGeometry): LinearHeadingPiece[];
+/**
+ * h(t) for a heading mode (site/docs/file-format.md, Heading modes). Always wrapped to (-pi, pi].
+ *
+ * `linear` turns the way the robot turns: each segment's share of the sweep the short way round
+ * (`linearHeadingPieces`), because that is what Pedro does with the numbers the runtime gives it,
+ * and the preview must show what the robot does. A share of more than half a turn is what the
+ * HEADING warning points out. `tangent` and `facePoint` interpolate nothing: they read the geometry
+ * at t.
+ */
+export declare function headingFunction(heading: Heading, path: PathGeometry): (t: number) => number;
+/**
+ * The heading at arc-length fraction t of a step, for any mode: `headingFunction` for one sample.
+ * Pure and cheap enough to call per frame; the ideal playback and the canvas both read it.
+ */
+export declare function headingAtT(heading: Heading, path: PathGeometry, t: number): number;
+/**
+ * Which range of a `piecewise` heading owns t, the way Pedro's `PiecewiseInterpolator` picks one:
+ * the first range whose end is at or past t (`ceilingEntry`), so a boundary belongs to the range it
+ * ends. Past the last end, the last range. The ranges are taken in file order.
+ */
+export declare function rangeIndexAt(ranges: readonly HeadingRange[], t: number): number;
+/**
+ * h(t) inside one range, with t still the step's own. `linear` turns the short way from `fromRad`
+ * at the range's start to `toRad` at its end, which is what the runtime's range interpolator does;
+ * every other mode reads the whole path at t, exactly as it would outside a range.
+ */
+export declare function rangeHeadingFunction(range: HeadingRange, path: PathGeometry): (t: number) => number;
+/** How close two range ends must be to count as the same t. Canonical form keeps t exact. */
+export declare const RANGE_T_TOLERANCE = 0.000001;
+/**
+ * What is wrong with a `piecewise` heading's ranges, in one sentence, or null when Pedro will take
+ * them: they must start at 0, each start where the one before ended, each end after it starts, and
+ * the last end at exactly 1 (`PiecewiseInterpolator.until` refuses a t that does not increase, and
+ * `interpolate` refuses to run until the ranges reach 1).
+ */
+export declare function rangeProblem(ranges: readonly HeadingRange[]): string | null;
+export {};
+//# sourceMappingURL=heading.d.ts.map

package/dist/heading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading.d.ts","sourceRoot":"","sources":["../src/heading.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAgB,MAAM,6BAA6B,CAAC;AAEvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,0DAA0D;AAC1D,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAUpE;AAED,KAAK,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAO,CAAC;AAQ5C,8FAA8F;AAC9F,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,GAAG,kBAAkB,EAAE,CAcpG;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAkC3F;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAElF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CASnG;AAED,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,WAAO,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,GAAG,IAAI,CA0B3E"}

package/dist/heading.js

@@ -0,0 +1,164 @@
+import { wrapAngle } from "./geometry/angle.js";
+/** The direction of travel at t, wrapped to (-pi, pi]. */
+export function tangentHeading(path, t) {
+    let tangent = path.tangentAt(t);
+    if (Math.hypot(tangent.xIn, tangent.yIn) < 1e-9) {
+        // A cusp or a repeated control point: look a little way along the path instead. The sample is
+        // not negated at the far end, because `tangentAt` is the derivative with respect to u and so
+        // already points the way the robot is travelling wherever it is taken.
+        const nudged = t < 0.5 ? Math.min(t + 1e-4, 1) : Math.max(t - 1e-4, 0);
+        tangent = path.tangentAt(nudged);
+    }
+    return wrapAngle(Math.atan2(tangent.yIn, tangent.xIn));
+}
+/**
+ * How far past half a turn a piece may ask before HEADING calls it reversed. Canonical form rounds
+ * radians to four decimals, so the half turn the editor writes, 3.1416, is a hair over pi; either
+ * way round is the same half turn to the person who wrote it, and the robot's choice is drawn.
+ */
+export const HALF_TURN_TOLERANCE_RAD = 1e-3;
+/** Pedro's `Angle.normalizeSigned`: [-pi, pi), so an exact half turn goes clockwise, as it does on the robot. */
+const pedroSigned = (rad) => {
+    const wrapped = wrapAngle(rad);
+    return wrapped === Math.PI ? -Math.PI : wrapped;
+};
+/**
+ * The pieces of a `linear` heading, one per segment, cut exactly as
+ * `robot/auto-runtime/PathBuilder.withHeading` cuts them: the sweep `toRad - fromRad` the file wrote
+ * is shared out by arc length, and each segment gets `Path.linear(from, to)` over its share. Pedro's
+ * `Interpolator.linear` then turns the short way, so a share of
+ * more than half a turn goes the other way round on the robot. A deliberate 270 degree sweep split
+ * over two segments of equal length therefore does turn 270 degrees, and the same sweep on one
+ * segment turns 90 degrees the other way.
+ */
+export function linearHeadingPieces(heading, path) {
+    const sweep = heading.toRad - heading.fromRad;
+    const total = path.lengthIn;
+    const pieces = [];
+    for (let index = 0; index + 1 < path.breaks.length; index += 1) {
+        const startT = total === 0 ? 0 : path.breaks[index] / total;
+        const endT = total === 0 ? 1 : path.breaks[index + 1] / total;
+        const fromRad = heading.fromRad + sweep * startT;
+        const toRad = heading.fromRad + sweep * endT;
+        const turnRad = pedroSigned(toRad - fromRad);
+        const reversed = Math.abs(toRad - fromRad) > Math.PI + HALF_TURN_TOLERANCE_RAD;
+        pieces.push({ startT, endT, fromRad, toRad, turnRad, reversed });
+    }
+    return pieces;
+}
+/**
+ * h(t) for a heading mode (site/docs/file-format.md, Heading modes). Always wrapped to (-pi, pi].
+ *
+ * `linear` turns the way the robot turns: each segment's share of the sweep the short way round
+ * (`linearHeadingPieces`), because that is what Pedro does with the numbers the runtime gives it,
+ * and the preview must show what the robot does. A share of more than half a turn is what the
+ * HEADING warning points out. `tangent` and `facePoint` interpolate nothing: they read the geometry
+ * at t.
+ */
+export function headingFunction(heading, path) {
+    switch (heading.mode) {
+        case "piecewise": {
+            const ranges = heading.ranges;
+            const inner = ranges.map((range) => rangeHeadingFunction(range, path));
+            return (t) => {
+                const index = rangeIndexAt(ranges, t);
+                return inner[index](t);
+            };
+        }
+        case "tangent":
+            return (t) => tangentHeading(path, t);
+        case "tangentReversed":
+            return (t) => wrapAngle(tangentHeading(path, t) + Math.PI);
+        case "constant":
+            return () => wrapAngle(heading.headingRad);
+        case "linear": {
+            const pieces = linearHeadingPieces(heading, path);
+            return (t) => {
+                const clamped = t < 0 ? 0 : t > 1 ? 1 : t;
+                const piece = pieces.find((candidate) => clamped <= candidate.endT) ?? pieces[pieces.length - 1];
+                const span = piece.endT - piece.startT;
+                const local = span <= 0 ? 1 : (clamped - piece.startT) / span;
+                return wrapAngle(piece.fromRad + piece.turnRad * local);
+            };
+        }
+        case "facePoint":
+            return (t) => {
+                const point = path.pointAt(t);
+                const bearing = Math.atan2(heading.yIn - point.yIn, heading.xIn - point.xIn);
+                return wrapAngle(bearing + (heading.offsetRad ?? 0));
+            };
+    }
+}
+/**
+ * The heading at arc-length fraction t of a step, for any mode: `headingFunction` for one sample.
+ * Pure and cheap enough to call per frame; the ideal playback and the canvas both read it.
+ */
+export function headingAtT(heading, path, t) {
+    return headingFunction(heading, path)(t);
+}
+/**
+ * Which range of a `piecewise` heading owns t, the way Pedro's `PiecewiseInterpolator` picks one:
+ * the first range whose end is at or past t (`ceilingEntry`), so a boundary belongs to the range it
+ * ends. Past the last end, the last range. The ranges are taken in file order.
+ */
+export function rangeIndexAt(ranges, t) {
+    for (let index = 0; index < ranges.length; index += 1) {
+        if (t <= ranges[index].endT + 1e-12)
+            return index;
+    }
+    return Math.max(0, ranges.length - 1);
+}
+/**
+ * h(t) inside one range, with t still the step's own. `linear` turns the short way from `fromRad`
+ * at the range's start to `toRad` at its end, which is what the runtime's range interpolator does;
+ * every other mode reads the whole path at t, exactly as it would outside a range.
+ */
+export function rangeHeadingFunction(range, path) {
+    const heading = range.heading;
+    if (heading.mode !== "linear")
+        return headingFunction(heading, path);
+    const span = range.endT - range.startT;
+    const turnRad = pedroSigned(heading.toRad - heading.fromRad);
+    return (t) => {
+        const local = span <= 0 ? 1 : Math.min(1, Math.max(0, (t - range.startT) / span));
+        return wrapAngle(heading.fromRad + turnRad * local);
+    };
+}
+/** How close two range ends must be to count as the same t. Canonical form keeps t exact. */
+export const RANGE_T_TOLERANCE = 1e-6;
+/**
+ * What is wrong with a `piecewise` heading's ranges, in one sentence, or null when Pedro will take
+ * them: they must start at 0, each start where the one before ended, each end after it starts, and
+ * the last end at exactly 1 (`PiecewiseInterpolator.until` refuses a t that does not increase, and
+ * `interpolate` refuses to run until the ranges reach 1).
+ */
+export function rangeProblem(ranges) {
+    if (ranges.length === 0)
+        return "A piecewise heading needs at least one range.";
+    const first = ranges[0];
+    if (Math.abs(first.startT) > RANGE_T_TOLERANCE) {
+        return `The first range starts at t ${String(first.startT)}; it must start at 0, or the robot has no heading before it.`;
+    }
+    for (const [index, range] of ranges.entries()) {
+        const label = `Range ${String(index + 1)}`;
+        if (range.endT <= range.startT + RANGE_T_TOLERANCE) {
+            return `${label} ends at t ${String(range.endT)}, which is not after its start at ${String(range.startT)}.`;
+        }
+        const next = ranges[index + 1];
+        if (next === undefined)
+            continue;
+        const gap = next.startT - range.endT;
+        if (gap > RANGE_T_TOLERANCE) {
+            return `${label} ends at t ${String(range.endT)} but range ${String(index + 2)} starts at ${String(next.startT)}, leaving a gap with no heading.`;
+        }
+        if (gap < -RANGE_T_TOLERANCE) {
+            return `${label} ends at t ${String(range.endT)} but range ${String(index + 2)} starts earlier, at ${String(next.startT)}; ranges must not overlap.`;
+        }
+    }
+    const last = ranges[ranges.length - 1];
+    if (Math.abs(last.endT - 1) > RANGE_T_TOLERANCE) {
+        return `The last range ends at t ${String(last.endT)}; it must end at 1, or the robot has no heading for the rest of the path.`;
+    }
+    return null;
+}
+//# sourceMappingURL=heading.js.map

package/dist/heading.js.map

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

package/dist/headingRanges.d.ts

@@ -0,0 +1,48 @@
+import type { Heading, HeadingRange, RangeHeading } from "@horizon36596/zenith-schema";
+/**
+ * Pure edits on a `piecewise` heading's ranges (site/docs/file-format.md, "Piecewise heading"): turn a
+ * heading into ranges, split a range at a t, move the boundary between two ranges, delete a range and
+ * change one range's mode. The inspector and the canvas both call these, and every one keeps the
+ * ranges covering 0 to 1 in order with no gap and no overlap, so an edit can never produce the
+ * HEADING_RANGES error; only a hand-edited file can.
+ *
+ * t is the step's arc-length fraction, as everywhere else in a heading.
+ */
+type Piecewise = Extract<Heading, {
+    mode: "piecewise";
+}>;
+/** The narrowest range an edit may leave, as a fraction of the path. */
+export declare const MIN_RANGE_T = 0.02;
+/**
+ * The same heading as one range from 0 to 1, or the heading itself when it is piecewise already.
+ * A step with no heading starts as one tangent range, the editor's default mode.
+ */
+export declare function toPiecewise(heading: Heading | undefined): Piecewise;
+/** The range that holds `t` strictly inside it, or -1 when t is on a boundary or outside 0..1. */
+export declare function rangeContaining(heading: Piecewise, t: number): number;
+/**
+ * Splits the range that holds `t` into two at `t`. Both halves keep the range's mode; a `linear`
+ * range is cut at the heading it passes through at `t`, so the robot turns exactly as before until
+ * either half is changed. Returns the heading unchanged when either half would be narrower than
+ * `MIN_RANGE_T`.
+ */
+export declare function splitRange(heading: Piecewise, t: number): Piecewise;
+/**
+ * Moves the boundary between range `index` and range `index + 1` to `t`, clamped so neither range
+ * gets narrower than `MIN_RANGE_T`. The two ranges keep their modes and values.
+ */
+export declare function moveBoundary(heading: Piecewise, index: number, t: number): Piecewise;
+/**
+ * Deletes range `index`; the range before it grows to cover the gap, or the one after it when it is
+ * the first. The last range cannot be deleted: a piecewise heading needs one.
+ */
+export declare function deleteRange(heading: Piecewise, index: number): Piecewise;
+/** Replaces range `index`'s own heading, keeping where it starts and ends. */
+export declare function setRangeHeading(heading: Piecewise, index: number, inner: RangeHeading): Piecewise;
+/**
+ * A heading of `mode` for a range, carrying over the angle the range already holds where the new
+ * mode has one: a linear range starts where the old range started and ends where it ended.
+ */
+export declare function rangeHeadingForMode(mode: RangeHeading["mode"], range: HeadingRange): RangeHeading;
+export {};
+//# sourceMappingURL=headingRanges.d.ts.map

package/dist/headingRanges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headingRanges.d.ts","sourceRoot":"","sources":["../src/headingRanges.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEvF;;;;;;;;GAQG;AAEH,KAAK,SAAS,GAAG,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,CAAC;AAEzD,wEAAwE;AACxE,eAAO,MAAM,WAAW,OAAO,CAAC;AAiBhC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAInE;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAoBnE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAcpF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAcxE;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,CAMjG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,CAajG"}