@ingissa/navcore-simulator 1.0.3 → 1.0.7

package/dist/core/src/license/LicenseManager.js

@@ -0,0 +1,119 @@
+/**
+ * LicenseManager — Handles offline asymmetric license verification
+ * using P-256 + granular feature licensing.
+ *
+ * Matching nav-sdk/src/shared/LicenseManager.ts contract exactly.
+ */
+import { FEATURES } from '../features';
+import { verifyP256Signature } from './verifyP256Signature';
+export class LicenseManager {
+    constructor(licenseKey, isDev) {
+        this.status = 'MISSING';
+        this.payload = null;
+        this.enabledFeatures = new Set();
+        this.warnedFeatures = new Set();
+        this.isDev = false;
+        this.isDev = isDev ?? false;
+        if (licenseKey) {
+            this.validate(licenseKey);
+        }
+    }
+    // ── Validation ──────────────────────────────────────────────────────────────
+    async validate(key) {
+        try {
+            if (this.status === 'VALID' && this.payload?.bid === 'dev.bypass') {
+                return 'VALID'; // Already bypassed synchronously
+            }
+            const [payloadB64, signatureB64] = key.split('.');
+            if (!payloadB64 || !signatureB64) {
+                this.status = 'INVALID';
+                return this.status;
+            }
+            const payloadStr = atob(payloadB64);
+            this.payload = JSON.parse(payloadStr);
+            // Expiration check
+            if (!this.payload || this.payload.exp < Date.now()) {
+                this.status = 'EXPIRED';
+                return this.status;
+            }
+            // Signature check
+            const isValid = await this.verifySignature(payloadB64, signatureB64);
+            if (!isValid) {
+                this.status = 'INVALID';
+                return this.status;
+            }
+            this.status = 'VALID';
+            this.extractFeatures();
+            console.log(`🔑 [NavCore] License validation complete. Plan: ${this.isProEnabled() ? 'pro' : 'core'}`);
+        }
+        catch {
+            this.status = 'INVALID';
+        }
+        return this.status;
+    }
+    // ── Feature system ──────────────────────────────────────────────────────────
+    extractFeatures() {
+        this.enabledFeatures.clear();
+        if (!this.payload)
+            return;
+        // New granular feature flags
+        if (Array.isArray(this.payload.f)) {
+            for (const f of this.payload.f) {
+                this.enabledFeatures.add(f);
+            }
+        }
+        // Backward compatibility: pro tier = all features
+        if (this.payload.t === 'pro') {
+            this.enabledFeatures.add('*');
+        }
+    }
+    hasFeature(feature) {
+        if (this.isDev)
+            return true;
+        if (this.status !== 'VALID')
+            return false;
+        if (this.enabledFeatures.has('*'))
+            return true;
+        return this.enabledFeatures.has(feature);
+    }
+    /** Warn once per feature when a consumer tries to use a gated feature. */
+    warnOnce(feature) {
+        if (this.warnedFeatures.has(feature))
+            return;
+        console.warn(`[NavCore] Feature '${feature}' requires a Pro license`);
+        this.warnedFeatures.add(feature);
+    }
+    // ── Legacy / convenience helpers ────────────────────────────────────────────
+    /** Returns true if the license grants the full Pro tier (all features). */
+    isProEnabled() {
+        // Matches nav-sdk: checks for the wildcard '*' grant, not a specific feature
+        return this.hasFeature('*');
+    }
+    isAIEnabled() {
+        return this.hasFeature(FEATURES.NAV_AI);
+    }
+    getStatus() {
+        return this.status;
+    }
+    getPayload() {
+        return this.payload;
+    }
+    getEnabledFeatures() {
+        return Array.from(this.enabledFeatures);
+    }
+    // ── Crypto ──────────────────────────────────────────────────────────────────
+    async verifySignature(data, signature) {
+        try {
+            const encoder = new TextEncoder();
+            const encodedData = encoder.encode(data);
+            const signatureBin = Uint8Array.from(atob(signature), c => c.charCodeAt(0));
+            const publicKeyBin = Uint8Array.from(atob(LicenseManager.PUBLIC_KEY_RAW), c => c.charCodeAt(0));
+            return await verifyP256Signature(encodedData, signatureBin, publicKeyBin);
+        }
+        catch {
+            return false;
+        }
+    }
+}
+// SEC1 uncompressed form of the shared ECDSA P-256 public key.
+LicenseManager.PUBLIC_KEY_RAW = 'BJOqJyZiZFrURbrIkkuvXXHTjV+MS9kp5uAGTvnWI0sp3yYi+Me7axMvNDCJi37ZJwVk/6iNM+6MeEO1TS97Xug=';

package/dist/core/src/license/verifyP256Signature.d.ts

@@ -0,0 +1,2 @@
+export declare function verifyP256Signature(message: Uint8Array, signature: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
+//# sourceMappingURL=verifyP256Signature.d.ts.map

package/dist/core/src/license/verifyP256Signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyP256Signature.d.ts","sourceRoot":"","sources":["../../../../../core/src/license/verifyP256Signature.ts"],"names":[],"mappings":"AAQA,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC,CA+BlB"}

package/dist/core/src/license/verifyP256Signature.js

@@ -0,0 +1,26 @@
+import { p256 } from '@noble/curves/nist.js';
+function toArrayBuffer(bytes) {
+    const buffer = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(buffer).set(bytes);
+    return buffer;
+}
+export async function verifyP256Signature(message, signature, publicKey) {
+    if (signature.length !== 64 || publicKey.length !== 65 || publicKey[0] !== 4) {
+        return false;
+    }
+    try {
+        const subtle = typeof crypto !== 'undefined' ? crypto.subtle : undefined;
+        if (subtle) {
+            const importedKey = await subtle.importKey('raw', toArrayBuffer(publicKey), { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
+            return await subtle.verify({ name: 'ECDSA', hash: { name: 'SHA-256' } }, importedKey, toArrayBuffer(signature), toArrayBuffer(message));
+        }
+        return p256.verify(signature, message, publicKey, {
+            format: 'compact',
+            lowS: false,
+            prehash: true,
+        });
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/src/off-route/NavigationFSM.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Module 9a: NavigationFSM
+ * Navigation lifecycle state machine. Pure deterministic transitions.
+ */
+export type NavLifecycleState = 'IDLE' | 'OVERVIEW' | 'APPROACHING_ROUTE' | 'ON_ROUTE';
+export type LifecycleEvent = {
+    type: 'ROUTE_LOADED';
+} | {
+    type: 'USER_START_NAVIGATION';
+} | {
+    type: 'ROUTE_JOINED';
+    data: {
+        index: number;
+    };
+} | {
+    type: 'NAVIGATION_FINISHED';
+} | {
+    type: 'CANCEL_NAVIGATION';
+} | {
+    type: 'RESET';
+};
+export interface LifecycleContext {
+    resumeIndex: number | null;
+}
+export interface LifecycleOutput {
+    state: NavLifecycleState;
+    context: LifecycleContext;
+}
+/**
+ * Pure lifecycle FSM — no React, no side effects.
+ */
+export declare class NavigationFSM {
+    private _state;
+    private _context;
+    get state(): NavLifecycleState;
+    get context(): LifecycleContext;
+    /** Dispatch an event and return the new output */
+    dispatch(event: LifecycleEvent): LifecycleOutput;
+    /** Reset to initial state */
+    reset(): void;
+}
+//# sourceMappingURL=NavigationFSM.d.ts.map

package/dist/core/src/off-route/NavigationFSM.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavigationFSM.d.ts","sourceRoot":"","sources":["../../../../../core/src/off-route/NavigationFSM.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,UAAU,GACV,mBAAmB,GACnB,UAAU,CAAC;AAEf,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,uBAAuB,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,qBAAqB,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,iBAAiB,CAAC;IACzB,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAA2C;IAE3D,IAAI,KAAK,IAAI,iBAAiB,CAAwB;IACtD,IAAI,OAAO,IAAI,gBAAgB,CAAiC;IAEhE,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe;IAqChD,6BAA6B;IAC7B,KAAK,IAAI,IAAI;CAId"}

package/dist/core/src/off-route/NavigationFSM.js

@@ -0,0 +1,56 @@
+/**
+ * Module 9a: NavigationFSM
+ * Navigation lifecycle state machine. Pure deterministic transitions.
+ */
+/**
+ * Pure lifecycle FSM — no React, no side effects.
+ */
+export class NavigationFSM {
+    constructor() {
+        this._state = 'IDLE';
+        this._context = { resumeIndex: null };
+    }
+    get state() { return this._state; }
+    get context() { return { ...this._context }; }
+    /** Dispatch an event and return the new output */
+    dispatch(event) {
+        const prev = this._state;
+        switch (prev) {
+            case 'IDLE':
+                if (event.type === 'ROUTE_LOADED')
+                    this._state = 'OVERVIEW';
+                if (event.type === 'USER_START_NAVIGATION')
+                    this._state = 'APPROACHING_ROUTE';
+                break;
+            case 'OVERVIEW':
+                if (event.type === 'USER_START_NAVIGATION')
+                    this._state = 'APPROACHING_ROUTE';
+                break;
+            case 'APPROACHING_ROUTE':
+                if (event.type === 'ROUTE_JOINED') {
+                    this._state = 'ON_ROUTE';
+                    this._context.resumeIndex = event.data.index;
+                }
+                if (event.type === 'NAVIGATION_FINISHED')
+                    this._state = 'IDLE';
+                break;
+            case 'ON_ROUTE':
+                if (event.type === 'NAVIGATION_FINISHED')
+                    this._state = 'IDLE';
+                if (event.type === 'ROUTE_JOINED') {
+                    this._context.resumeIndex = event.data.index;
+                }
+                break;
+        }
+        if (event.type === 'RESET' || event.type === 'CANCEL_NAVIGATION') {
+            this._state = 'IDLE';
+            this._context = { resumeIndex: null };
+        }
+        return { state: this._state, context: { ...this._context } };
+    }
+    /** Reset to initial state */
+    reset() {
+        this._state = 'IDLE';
+        this._context = { resumeIndex: null };
+    }
+}

package/dist/core/src/off-route/OffRouteFSM.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Module 9b: OffRouteFSM
+ * Deviation → Reroute → Rejoin state machine. Pure deterministic transitions.
+ * Extracted from useOffRouteSystem / NavigationStateManager (stripped of React).
+ */
+import type { Coordinate } from '../geo/haversine';
+export type OffRouteState = 'ON_ROUTE' | 'DEVIATING' | 'OFF_ROUTE' | 'REROUTING' | 'REJOINING' | 'REJOINED' | 'FAILED';
+export interface TempRoute {
+    geometry: Coordinate[];
+    distance: number;
+    duration: number;
+}
+export interface RejoinTarget {
+    coordinates: Coordinate;
+    index: number;
+}
+export interface OffRouteContext {
+    deviationSegmentIdx: number | null;
+    deviationStartMs: number | null;
+    tempRoute: TempRoute | null;
+    rejoinTarget: RejoinTarget | null;
+    lastRerouteMs: number | null;
+    rejoinedAtMs: number | null;
+    rejoinDwellFrames: number;
+    failureReason: string | null;
+}
+export type OffRouteEvent = {
+    type: 'DEVIATION_SUSPECTED';
+    deviationSegmentIdx: number;
+} | {
+    type: 'DEVIATION_CONFIRMED';
+    deviationSegmentIdx: number;
+} | {
+    type: 'REROUTE_STARTED';
+} | {
+    type: 'REROUTE_SUCCESS';
+    tempRoute: TempRoute;
+    rejoinTarget: RejoinTarget;
+} | {
+    type: 'REROUTE_FAILED';
+    reason: string;
+} | {
+    type: 'REJOIN_DETECTED';
+} | {
+    type: 'REJOIN_CONFIRMED';
+} | {
+    type: 'RESUME';
+} | {
+    type: 'RESET';
+};
+export interface OffRouteOutput {
+    state: OffRouteState;
+    context: OffRouteContext;
+}
+/**
+ * Pure off-route FSM — no React, no side effects.
+ */
+export declare class OffRouteFSM {
+    private _state;
+    private _context;
+    get state(): OffRouteState;
+    get context(): OffRouteContext;
+    /** Dispatch an event and return the new output */
+    dispatch(event: OffRouteEvent, nowMs?: number): OffRouteOutput;
+    /** Full reset */
+    reset(): void;
+    /** Check if deviation confirmation time has elapsed */
+    isDeviationConfirmed(nowMs?: number): boolean;
+}
+//# sourceMappingURL=OffRouteFSM.d.ts.map

package/dist/core/src/off-route/OffRouteFSM.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OffRouteFSM.d.ts","sourceRoot":"","sources":["../../../../../core/src/off-route/OffRouteFSM.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,MAAM,aAAa,GACrB,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,QAAQ,CAAC;AAEb,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,UAAU,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,SAAS,CAAC;IAAC,YAAY,EAAE,YAAY,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,eAAe,CAAC;CAC1B;AAgBD;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAA2C;IAE3D,IAAI,KAAK,IAAI,aAAa,CAAwB;IAClD,IAAI,OAAO,IAAI,eAAe,CAAiC;IAE/D,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,cAAc;IAwH9D,iBAAiB;IACjB,KAAK,IAAI,IAAI;IAKb,uDAAuD;IACvD,oBAAoB,CAAC,KAAK,GAAE,MAAmB,GAAG,OAAO;CAI1D"}

package/dist/core/src/off-route/OffRouteFSM.js

@@ -0,0 +1,151 @@
+/**
+ * Module 9b: OffRouteFSM
+ * Deviation → Reroute → Rejoin state machine. Pure deterministic transitions.
+ * Extracted from useOffRouteSystem / NavigationStateManager (stripped of React).
+ */
+const INITIAL_CONTEXT = {
+    deviationSegmentIdx: null,
+    deviationStartMs: null,
+    tempRoute: null,
+    rejoinTarget: null,
+    lastRerouteMs: null,
+    rejoinedAtMs: null,
+    rejoinDwellFrames: 0,
+    failureReason: null,
+};
+const DEVIATION_CONFIRM_MS = 2000;
+const REJOIN_DWELL_THRESHOLD = 3;
+/**
+ * Pure off-route FSM — no React, no side effects.
+ */
+export class OffRouteFSM {
+    constructor() {
+        this._state = 'ON_ROUTE';
+        this._context = { ...INITIAL_CONTEXT };
+    }
+    get state() { return this._state; }
+    get context() { return { ...this._context }; }
+    /** Dispatch an event and return the new output */
+    dispatch(event, nowMs) {
+        const now = nowMs ?? Date.now();
+        switch (this._state) {
+            case 'ON_ROUTE':
+                if (event.type === 'DEVIATION_SUSPECTED') {
+                    this._state = 'DEVIATING';
+                    this._context.deviationSegmentIdx = event.deviationSegmentIdx;
+                    this._context.deviationStartMs = now;
+                }
+                break;
+            case 'DEVIATING':
+                if (event.type === 'DEVIATION_CONFIRMED') {
+                    const elapsed = this._context.deviationStartMs !== null
+                        ? now - this._context.deviationStartMs
+                        : 0;
+                    if (elapsed >= DEVIATION_CONFIRM_MS) {
+                        this._state = 'OFF_ROUTE';
+                        this._context.deviationSegmentIdx = event.deviationSegmentIdx;
+                    }
+                }
+                if (event.type === 'RESUME' || event.type === 'RESET') {
+                    this._state = 'ON_ROUTE';
+                    // RESUME preserves lastRerouteMs (cooldown), RESET clears everything
+                    if (event.type === 'RESET') {
+                        this._context = { ...INITIAL_CONTEXT };
+                    }
+                    else {
+                        this._context.deviationSegmentIdx = null;
+                        this._context.deviationStartMs = null;
+                    }
+                }
+                break;
+            case 'OFF_ROUTE':
+                if (event.type === 'REROUTE_STARTED') {
+                    this._state = 'REROUTING';
+                    this._context.lastRerouteMs = now;
+                }
+                if (event.type === 'RESUME') {
+                    this._state = 'ON_ROUTE';
+                    this._context.deviationSegmentIdx = null;
+                    this._context.deviationStartMs = null;
+                }
+                if (event.type === 'RESET') {
+                    this._state = 'ON_ROUTE';
+                    this._context = { ...INITIAL_CONTEXT };
+                }
+                break;
+            case 'REROUTING':
+                if (event.type === 'REROUTE_SUCCESS') {
+                    this._state = 'REJOINING';
+                    this._context.tempRoute = event.tempRoute;
+                    this._context.rejoinTarget = event.rejoinTarget;
+                }
+                if (event.type === 'REROUTE_FAILED') {
+                    this._state = 'FAILED';
+                    this._context.failureReason = event.reason;
+                }
+                break;
+            case 'REJOINING':
+                if (event.type === 'REJOIN_DETECTED') {
+                    this._context.rejoinDwellFrames++;
+                }
+                if (event.type === 'REJOIN_CONFIRMED' ||
+                    this._context.rejoinDwellFrames >= REJOIN_DWELL_THRESHOLD) {
+                    this._state = 'REJOINED';
+                    this._context.rejoinedAtMs = now;
+                    this._context.rejoinDwellFrames = 0;
+                }
+                if (event.type === 'RESUME') {
+                    this._state = 'ON_ROUTE';
+                    this._context.tempRoute = null;
+                    this._context.rejoinTarget = null;
+                    this._context.rejoinedAtMs = null;
+                    this._context.deviationSegmentIdx = null;
+                    this._context.deviationStartMs = null;
+                    this._context.rejoinDwellFrames = 0;
+                }
+                if (event.type === 'RESET') {
+                    this._state = 'ON_ROUTE';
+                    this._context = { ...INITIAL_CONTEXT };
+                }
+                break;
+            case 'REJOINED':
+                if (event.type === 'RESUME') {
+                    this._state = 'ON_ROUTE';
+                    this._context.tempRoute = null;
+                    this._context.rejoinTarget = null;
+                    this._context.rejoinedAtMs = null;
+                    this._context.deviationSegmentIdx = null;
+                    this._context.deviationStartMs = null;
+                }
+                if (event.type === 'RESET') {
+                    this._state = 'ON_ROUTE';
+                    this._context = { ...INITIAL_CONTEXT };
+                }
+                break;
+            case 'FAILED':
+                if (event.type === 'RESUME') {
+                    this._state = 'ON_ROUTE';
+                    this._context.failureReason = null;
+                    this._context.deviationSegmentIdx = null;
+                    this._context.deviationStartMs = null;
+                }
+                if (event.type === 'RESET') {
+                    this._state = 'ON_ROUTE';
+                    this._context = { ...INITIAL_CONTEXT };
+                }
+                break;
+        }
+        return { state: this._state, context: { ...this._context } };
+    }
+    /** Full reset */
+    reset() {
+        this._state = 'ON_ROUTE';
+        this._context = { ...INITIAL_CONTEXT };
+    }
+    /** Check if deviation confirmation time has elapsed */
+    isDeviationConfirmed(nowMs = Date.now()) {
+        if (!this._context.deviationStartMs)
+            return false;
+        return (nowMs - this._context.deviationStartMs) >= DEVIATION_CONFIRM_MS;
+    }
+}

package/dist/core/src/predictor/RouteOffsetPredictor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Module 8: RouteOffsetPredictor
+ * Linear distance-based position predictor for smooth rendering between GPS fixes.
+ */
+import { type Coordinate } from '../geo/haversine';
+/**
+ * Advance the predictor's offset by speed * dt.
+ */
+export declare function advancePredictor(currentOffset: number, speedMps: number, dtSec: number): number;
+/**
+ * Correct the predictor when a new GPS fix arrives.
+ * Blend towards the actual measured offset using betaCorrection.
+ */
+export declare function applyGpsCorrection(predictedOffset: number, measuredOffset: number, betaCorrection?: number): number;
+/**
+ * Given a linear offset (metres from route start), find the [lng, lat] on the route.
+ *
+ * @param offset           Linear distance from route start in metres
+ * @param cumulativeDistances Forward cumulative distance array
+ * @param route             Route coordinates
+ * @returns Interpolated coordinate on the route
+ */
+export declare function pointAtOffset(offset: number, cumulativeDistances: Float64Array, route: Coordinate[]): Coordinate;
+//# sourceMappingURL=RouteOffsetPredictor.d.ts.map

package/dist/core/src/predictor/RouteOffsetPredictor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteOffsetPredictor.d.ts","sourceRoot":"","sources":["../../../../../core/src/predictor/RouteOffsetPredictor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,eAAe,EAAE,MAAM,EACvB,cAAc,EAAE,MAAM,EACtB,cAAc,GAAE,MAAa,GAC5B,MAAM,CAGR;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,mBAAmB,EAAE,YAAY,EACjC,KAAK,EAAE,UAAU,EAAE,GAClB,UAAU,CA2BZ"}

package/dist/core/src/predictor/RouteOffsetPredictor.js

@@ -0,0 +1,55 @@
+/**
+ * Module 8: RouteOffsetPredictor
+ * Linear distance-based position predictor for smooth rendering between GPS fixes.
+ */
+import { interpolatePoint } from '../geo/bearing';
+/**
+ * Advance the predictor's offset by speed * dt.
+ */
+export function advancePredictor(currentOffset, speedMps, dtSec) {
+    return currentOffset + speedMps * dtSec;
+}
+/**
+ * Correct the predictor when a new GPS fix arrives.
+ * Blend towards the actual measured offset using betaCorrection.
+ */
+export function applyGpsCorrection(predictedOffset, measuredOffset, betaCorrection = 0.15) {
+    const error = measuredOffset - predictedOffset;
+    return predictedOffset + betaCorrection * error;
+}
+/**
+ * Given a linear offset (metres from route start), find the [lng, lat] on the route.
+ *
+ * @param offset           Linear distance from route start in metres
+ * @param cumulativeDistances Forward cumulative distance array
+ * @param route             Route coordinates
+ * @returns Interpolated coordinate on the route
+ */
+export function pointAtOffset(offset, cumulativeDistances, route) {
+    if (route.length === 0)
+        return [0, 0];
+    if (offset <= 0)
+        return route[0];
+    const totalLength = cumulativeDistances[cumulativeDistances.length - 1] ?? 0;
+    if (offset >= totalLength)
+        return route[route.length - 1];
+    // Binary search for the segment containing this offset
+    let lo = 0;
+    let hi = cumulativeDistances.length - 1;
+    while (lo < hi - 1) {
+        const mid = (lo + hi) >> 1;
+        if (cumulativeDistances[mid] <= offset) {
+            lo = mid;
+        }
+        else {
+            hi = mid;
+        }
+    }
+    const segStart = cumulativeDistances[lo];
+    const segEnd = cumulativeDistances[hi];
+    const segLength = segEnd - segStart;
+    if (segLength === 0)
+        return route[lo];
+    const t = (offset - segStart) / segLength;
+    return interpolatePoint(route[lo], route[hi], t);
+}

package/dist/core/src/progress/InstructionEditor.d.ts

@@ -0,0 +1,77 @@
+/**
+ * InstructionEditor — Fluent builder for NavInstruction arrays.
+ *
+ * Create, edit, and annotate navigation instructions for custom routes.
+ * Supports standard turn instructions and exam-specific annotations.
+ *
+ * @example
+ * ```typescript
+ * const editor = new InstructionEditor();
+ * editor
+ *   .addTurn([2.347, 48.859], 'Turn left onto Rue de Rivoli', 42)
+ *   .addExamPoint([2.350, 48.860], 'Check mirrors before changing lane', 50)
+ *   .addCheckpoint([2.355, 48.861], 65);
+ *
+ * editor.attachToCumulative(routeGeometry);
+ * engine.setRoute(routeGeometry, editor.toArray());
+ * ```
+ */
+import type { Coordinate } from '../geo/haversine';
+import type { NavInstruction } from './InstructionResolver';
+export type InstructionType = 'turn' | 'exam_point' | 'checkpoint' | 'depart' | 'arrive' | 'custom';
+export interface RichInstruction extends NavInstruction {
+    /** Instruction category */
+    type: InstructionType;
+    /** Unique id for referencing in edit operations */
+    id: string;
+    /** Display text (same as NavInstruction.text) */
+    text: string;
+    /** Whether to suppress voice read-out */
+    silent?: boolean;
+    /** Exam-specific severity level */
+    severity?: 'info' | 'warning' | 'critical';
+    /** Custom metadata for integrators */
+    meta?: Record<string, unknown>;
+}
+export declare class InstructionEditor {
+    private instructions;
+    /** Add a turn instruction at the given route geometry index */
+    addTurn(location: Coordinate, text: string, geometryIndex: number, opts?: {
+        silent?: boolean;
+        meta?: Record<string, unknown>;
+    }): this;
+    /** Add an exam-specific point (e.g. "Check mirrors", "Yield here") */
+    addExamPoint(location: Coordinate, text: string, geometryIndex: number, opts?: {
+        severity?: RichInstruction['severity'];
+        silent?: boolean;
+        meta?: Record<string, unknown>;
+    }): this;
+    /** Add a silent progress checkpoint (does not trigger voice) */
+    addCheckpoint(location: Coordinate, geometryIndex: number, meta?: Record<string, unknown>): this;
+    /** Add a departure instruction (auto-inserted at index 0) */
+    addDepart(location: Coordinate, text?: string): this;
+    /** Add an arrival instruction */
+    addArrive(location: Coordinate, text?: string): this;
+    /** Update any field of an instruction by id */
+    update(id: string, patch: Partial<Omit<RichInstruction, 'id'>>): this;
+    /** Remove an instruction by id */
+    remove(id: string): this;
+    /** Move an instruction to a new position in the list */
+    reorder(id: string, newIndex: number): this;
+    /** Sort instructions by geometryIndex ascending */
+    sort(): this;
+    /** Remove all instructions */
+    clear(): this;
+    /**
+     * Compute and attach `cumulativeOffset` and `bearingBefore`/`bearingAfter`
+     * from the route geometry. Call this after loading the route but before
+     * passing instructions to the engine.
+     */
+    attachToCumulative(route: Coordinate[]): this;
+    /** Export as plain NavInstruction[] for use with engine.setRoute() */
+    toArray(): NavInstruction[];
+    /** Export rich instructions with all metadata */
+    toRichArray(): ReadonlyArray<RichInstruction>;
+    get size(): number;
+}
+//# sourceMappingURL=InstructionEditor.d.ts.map

package/dist/core/src/progress/InstructionEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstructionEditor.d.ts","sourceRoot":"","sources":["../../../../../core/src/progress/InstructionEditor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,YAAY,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEpG,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,2BAA2B;IAC3B,IAAI,EAAE,eAAe,CAAC;IACtB,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAC3C,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAOD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,YAAY,CAAyB;IAI7C,+DAA+D;IAC/D,OAAO,CACL,QAAQ,EAAE,UAAU,EACpB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAC1D,IAAI;IASP,sEAAsE;IACtE,YAAY,CACV,QAAQ,EAAE,UAAU,EACpB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAClG,IAAI;IAWP,gEAAgE;IAChE,aAAa,CAAC,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAShG,6DAA6D;IAC7D,SAAS,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,SAAqB,GAAG,IAAI;IAShE,iCAAiC;IACjC,SAAS,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,SAAqB,GAAG,IAAI;IAWhE,+CAA+C;IAC/C,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI;IAOrE,kCAAkC;IAClC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAOxB,wDAAwD;IACxD,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQ3C,mDAAmD;IACnD,IAAI,IAAI,IAAI;IAKZ,8BAA8B;IAC9B,KAAK,IAAI,IAAI;IAOb;;;;OAIG;IACH,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI;IA0B7C,sEAAsE;IACtE,OAAO,IAAI,cAAc,EAAE;IAI3B,iDAAiD;IACjD,WAAW,IAAI,aAAa,CAAC,eAAe,CAAC;IAI7C,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}