@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/vehicle/enginePolicy.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DECLARED_FIGURE_TOLERANCE = exports.GOVERNOR_FRACTION = void 0;
+exports.torquesNm = torquesNm;
+exports.powersKw = powersKw;
+exports.declaredCrankFigures = declaredCrankFigures;
+exports.authoredCurves = authoredCurves;
+exports.speedGovernorIssues = speedGovernorIssues;
+exports.declaredTorqueIssues = declaredTorqueIssues;
+exports.awdBiasIssues = awdBiasIssues;
+exports.enginePolicyIssues = enginePolicyIssues;
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+/** A limiter below this fraction of the ungoverned top speed is a market governor, not the car's physics. */
+exports.GOVERNOR_FRACTION = 0.9;
+/** The authored curve (and the fields that state it) may exceed the declared crank figure by this much. */
+exports.DECLARED_FIGURE_TOLERANCE = 0.05;
+const sourcedValue = (block) => (isRecord(block) && finite(block.value) ? block.value : null);
+// ── declared crank figures ──────────────────────────────────────────────────────────────────────────────────────────
+const NUM = String.raw `(\d{1,3}(?:,\d{3})+(?:\.\d+)?|\d+(?:\.\d+)?)`;
+const toNumber = (s) => Number(s.replace(/,/g, ''));
+const matchAll = (text, re) => [...text.matchAll(re)].map((m) => toNumber(m[1]));
+/** Peak torque figures quoted in `text`, as N·m. Accepts N·m / N.m / Nm, kgm and lb-ft. */
+function torquesNm(text) {
+    return [
+        ...matchAll(text, new RegExp(`${NUM}\\s*N\\s*[·.•\\-\\s]?\\s*m(?![a-z])`, 'gi')),
+        ...matchAll(text, new RegExp(`${NUM}\\s*kgf?\\s*[·.•\\-\\s]?\\s*m(?![a-z])`, 'gi')).map((v) => v * 9.80665),
+        ...matchAll(text, new RegExp(`${NUM}\\s*lb\\s*[·.•\\-\\s]?\\s*ft(?![a-z])`, 'gi')).map((v) => v * 1.355818),
+    ].filter((v) => v >= 20 && v <= 20000);
+}
+/** Peak power figures quoted in `text`, as kW. Accepts kW, PS / CV, hp / bhp. */
+function powersKw(text) {
+    return [
+        ...matchAll(text, new RegExp(`${NUM}\\s*kW(?![a-z])`, 'g')),
+        ...matchAll(text, new RegExp(`${NUM}\\s*(?:PS|CV)(?![a-z])`, 'g')).map((v) => v * 0.7355),
+        ...matchAll(text, new RegExp(`${NUM}\\s*(?:b?hp)(?![a-z])`, 'gi')).map((v) => v * 0.7457),
+    ].filter((v) => v >= 3 && v <= 20000);
+}
+/** A citation that states the AXLE or WHEEL output (a dyno), not the crank, is not a declared crank figure. */
+const WHEEL_FIGURE = /\b(at the wheels?|whp|wheel horsepower|chassis dyno|dyno|rwhp|awhp)\b/i;
+/**
+ * The maker's declared crank figures. A `manufacturer` citation that quotes them wins; with none, the package's own
+ * `physics.engine.peakTorqueNm` / `peakPowerKw` stand in. When several manufacturer citations quote different figures
+ * (variants), the largest is used: the check only ever flags a curve ABOVE every declared figure.
+ */
+function declaredCrankFigures(pkg) {
+    const p = isRecord(pkg) ? pkg : {};
+    const engine = isRecord(p.physics) && isRecord(p.physics.engine) ? p.physics.engine : {};
+    let torqueNm = null;
+    let powerKw = null;
+    let torqueFrom = null;
+    let powerFrom = null;
+    for (const c of Array.isArray(p.citations) ? p.citations : []) {
+        if (!isRecord(c) || c.kind !== 'manufacturer' || typeof c.title !== 'string' || WHEEL_FIGURE.test(c.title))
+            continue;
+        const id = typeof c.id === 'string' ? c.id : 'citation';
+        const t = torquesNm(c.title);
+        const w = powersKw(c.title);
+        if (t.length > 0 && (torqueNm === null || Math.max(...t) > torqueNm)) {
+            torqueNm = Math.max(...t);
+            torqueFrom = id;
+        }
+        if (w.length > 0 && (powerKw === null || Math.max(...w) > powerKw)) {
+            powerKw = Math.max(...w);
+            powerFrom = id;
+        }
+    }
+    if (torqueNm === null) {
+        const own = sourcedValue(engine.peakTorqueNm);
+        if (own !== null) {
+            torqueNm = own;
+            torqueFrom = 'physics.engine.peakTorqueNm';
+        }
+    }
+    if (powerKw === null) {
+        const own = sourcedValue(engine.peakPowerKw);
+        if (own !== null) {
+            powerKw = own;
+            powerFrom = 'physics.engine.peakPowerKw';
+        }
+    }
+    return { torqueNm, powerKw, torqueFrom, powerFrom };
+}
+const pairs = (lut) => Array.isArray(lut) ? lut.filter((pt) => Array.isArray(pt) && finite(pt[0]) && finite(pt[1])).map((pt) => [pt[0], pt[1]]) : [];
+/**
+ * Every authored crank curve. The package states one (`physics.engine.torqueCurve`) and the land solver runs another
+ * (`simulation.land.driveline.engine.torqueCurve.points`); editing only the first changes nothing in the simulation, so
+ * both are held to the declared figures.
+ */
+function authoredCurves(pkg) {
+    const p = isRecord(pkg) ? pkg : {};
+    const engine = isRecord(p.physics) && isRecord(p.physics.engine) ? p.physics.engine : {};
+    const land = isRecord(p.simulation) && isRecord(p.simulation.land) ? p.simulation.land : {};
+    const dl = isRecord(land.driveline) && isRecord(land.driveline.engine) ? land.driveline.engine : {};
+    const out = [];
+    const physics = pairs(isRecord(engine.torqueCurve) ? engine.torqueCurve.value : undefined);
+    if (physics.length >= 2)
+        out.push({ path: 'physics.engine.torqueCurve', points: physics });
+    const solver = pairs(isRecord(dl.torqueCurve) ? dl.torqueCurve.points : undefined);
+    if (solver.length >= 2)
+        out.push({ path: 'simulation.land.driveline.engine.torqueCurve.points', points: solver });
+    return out;
+}
+const f0 = (v) => String(Math.round(v));
+const pct = (v) => `${v >= 0 ? '+' : ''}${(v * 100).toFixed(1)} %`;
+/** The speed-governor rule. */
+function speedGovernorIssues(pkg, opts = {}) {
+    const p = isRecord(pkg) ? pkg : {};
+    const engine = isRecord(p.physics) && isRecord(p.physics.engine) ? p.physics.engine : {};
+    const limiter = sourcedValue(engine.speedLimiterKph);
+    if (limiter === null || limiter <= 0)
+        return [];
+    const targets = isRecord(p.targets) ? p.targets : {};
+    const declared = sourcedValue(targets.ungovernedTopSpeedKph);
+    const simulated = finite(opts.simulatedUngovernedKph) ? opts.simulatedUngovernedKph : null;
+    const reference = declared ?? simulated;
+    if (reference === null || reference <= 0 || limiter >= exports.GOVERNOR_FRACTION * reference)
+        return [];
+    const basis = declared !== null ? `targets.ungovernedTopSpeedKph ${f0(declared)} km/h` : `the instrument's ungoverned top speed ${f0(simulated)} km/h`;
+    const topTarget = sourcedValue(targets.topSpeedKph);
+    return [{
+            code: 'SPEED_LIMITER_IS_A_MARKET_GOVERNOR',
+            level: 'warn',
+            path: 'physics.engine.speedLimiterKph',
+            message: `speedLimiterKph ${f0(limiter)} km/h is below ${Math.round(exports.GOVERNOR_FRACTION * 100)} % of ${basis}: a market or agreement governor is not the car's physics. The platform car runs UNGOVERNED (the live land solver never applies this field; only the instrument does), so the limiter just pins simulate/validate and any top-speed target${topTarget !== null ? ` (targets.topSpeedKph ${f0(topTarget)})` : ''} at ${f0(limiter)} km/h while the car really drives at its drag-limited speed`,
+            fix: 'set physics.engine.speedLimiterKph.value to null, set targets.topSpeedKph to the ungoverned figure (the same as targets.ungovernedTopSpeedKph), and mention the real governor only in the description / market text. No add-on can toggle it: an ECU add-on has no op path for a speed limiter, and the live runtime has none to toggle — skills/helix-vehicles/references/physics-from-specs.md "Top speed: governed vs ungoverned"',
+        }];
+}
+/** The torque rule: no authored curve may exceed the declared crank figures by more than ~5 %. */
+function declaredTorqueIssues(pkg) {
+    const curves = authoredCurves(pkg);
+    if (curves.length === 0)
+        return [];
+    const declared = declaredCrankFigures(pkg);
+    const p = isRecord(pkg) ? pkg : {};
+    const engine = isRecord(p.physics) && isRecord(p.physics.engine) ? p.physics.engine : {};
+    const ownTorque = sourcedValue(engine.peakTorqueNm);
+    const ownPower = sourcedValue(engine.peakPowerKw);
+    const tol = 1 + exports.DECLARED_FIGURE_TOLERANCE;
+    const over = [];
+    for (const c of curves) {
+        const peakTorque = Math.max(...c.points.map((pt) => pt[1]));
+        const peakPower = Math.max(...c.points.map((pt) => (pt[1] * pt[0]) / 9549));
+        if (declared.torqueNm !== null && peakTorque > declared.torqueNm * tol)
+            over.push(`${c.path} peaks at ${f0(peakTorque)} N·m against the declared ${f0(declared.torqueNm)} N·m (${pct(peakTorque / declared.torqueNm - 1)}; ${declared.torqueFrom})`);
+        if (declared.powerKw !== null && peakPower > declared.powerKw * tol)
+            over.push(`${c.path} implies ${f0(peakPower)} kW against the declared ${f0(declared.powerKw)} kW (${pct(peakPower / declared.powerKw - 1)}; ${declared.powerFrom})`);
+        // The package's own peak fields must also describe its own curve.
+        if (c.path.startsWith('physics.') && ownTorque !== null && peakTorque > ownTorque * tol)
+            over.push(`${c.path} peaks at ${f0(peakTorque)} N·m, above its own physics.engine.peakTorqueNm ${f0(ownTorque)} N·m`);
+        if (c.path.startsWith('physics.') && ownPower !== null && peakPower > ownPower * tol)
+            over.push(`${c.path} implies ${f0(peakPower)} kW, above its own physics.engine.peakPowerKw ${f0(ownPower)} kW`);
+    }
+    if (declared.torqueNm !== null && ownTorque !== null && declared.torqueFrom !== 'physics.engine.peakTorqueNm' && ownTorque > declared.torqueNm * tol)
+        over.push(`physics.engine.peakTorqueNm is ${f0(ownTorque)} N·m against the declared ${f0(declared.torqueNm)} N·m (${pct(ownTorque / declared.torqueNm - 1)})`);
+    if (declared.powerKw !== null && ownPower !== null && declared.powerFrom !== 'physics.engine.peakPowerKw' && ownPower > declared.powerKw * tol)
+        over.push(`physics.engine.peakPowerKw is ${f0(ownPower)} kW against the declared ${f0(declared.powerKw)} kW (${pct(ownPower / declared.powerKw - 1)})`);
+    if (over.length === 0)
+        return [];
+    return [{
+            code: 'TORQUE_CURVE_EXCEEDS_DECLARED_CRANK_FIGURES',
+            level: 'warn',
+            path: 'physics.engine.torqueCurve',
+            message: `${over.join('; ')}. The engine is the maker's declared crank figure; it is not tuned to a dyno or a top-speed number`,
+            fix: `scale BOTH torque curves (physics.engine.torqueCurve and simulation.land.driveline.engine.torqueCurve.points, which must stay identical) and peakTorqueNm / peakPowerKw back to the declared crank figures (±${Math.round(exports.DECLARED_FIGURE_TOLERANCE * 100)} %); carry real-world losses in physics.engine.drivetrainEfficiency and aero drag, and meet 0-100 / top speed with grip, gearing and launch — never an inflated curve. If the published figure is a market cap that real cars exceed, still target the declared figure and say so in the description — skills/helix-vehicles/references/physics-from-specs.md "Torque: target the declared crank figures"`,
+        }];
+}
+/**
+ * AWD authoring: the land solver reads the split from `simulation.land.driveline.centre`, but each wheel's `powered` flag
+ * comes from `physics.driveBiasFront` (front wheels powered iff it is above 0, rear wheels iff it is below 1). An AWD car
+ * whose bias is exactly 0 or 1 therefore has an unpowered axle whatever its centre diff says (measured: the front axle
+ * got 0 % of the drive and the car lost a third of its top speed). Inside (0, 1) the bias is the nominal front share, so
+ * it should agree with `centre.torqueSplit`.
+ */
+function awdBiasIssues(pkg) {
+    const p = isRecord(pkg) ? pkg : {};
+    const land = isRecord(p.simulation) && isRecord(p.simulation.land) ? p.simulation.land : {};
+    const dl = isRecord(land.driveline) ? land.driveline : {};
+    if (!isRecord(dl.centre) || !isRecord(dl.front) || !isRecord(dl.rear))
+        return [];
+    const bias = isRecord(p.physics) ? sourcedValue(p.physics.driveBiasFront) : null;
+    if (bias === null)
+        return [];
+    const split = finite(dl.centre.torqueSplit) ? dl.centre.torqueSplit : null;
+    if (bias <= 0 || bias >= 1) {
+        return [{
+                code: 'AWD_DRIVE_BIAS_UNPOWERS_AN_AXLE',
+                level: 'warn',
+                path: 'physics.driveBiasFront',
+                message: `the driveline has a centre diff and both axle diffs (AWD) but physics.driveBiasFront is ${bias}: the ${bias <= 0 ? 'front' : 'rear'} wheels are flagged unpowered from it and receive no drive whatever the centre diff says`,
+                fix: `set physics.driveBiasFront to the nominal front share of drive torque at zero slip, strictly between 0 and 1 (e.g. 0.05 for a rear-biased clutch-pack car whose maker says 0:100, otherwise the declared split) and keep simulation.land.driveline.centre.torqueSplit equal to it — skills/helix-vehicles/references/physics-from-specs.md "All-wheel drive"`,
+            }];
+    }
+    if (split !== null && Math.abs(split - bias) > 0.05) {
+        return [{
+                code: 'AWD_DRIVE_BIAS_DISAGREES_WITH_CENTRE_SPLIT',
+                level: 'warn',
+                path: 'physics.driveBiasFront',
+                message: `physics.driveBiasFront ${bias} and simulation.land.driveline.centre.torqueSplit ${split} state two different front shares (the solver uses the centre diff; add-ons that move driveBiasFront scale the split)`,
+                fix: 'make them equal: both are the nominal front share of drive torque at zero slip — skills/helix-vehicles/references/physics-from-specs.md "All-wheel drive"',
+            }];
+    }
+    return [];
+}
+/** Every engine-policy finding for a package. */
+function enginePolicyIssues(pkg, opts = {}) {
+    return [...speedGovernorIssues(pkg, opts), ...declaredTorqueIssues(pkg), ...awdBiasIssues(pkg)];
+}
+//# sourceMappingURL=enginePolicy.js.map

package/dist/vehicle/enginePolicy.js.map

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

package/dist/vehicle/hostFrame.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The HOST-FRAME BIND CONTRACT — which nodes of the car's GLB a host-frame add-on's bind needs, and the check that
+ * they are there.
+ *
+ * WHY THIS EXISTS. A meshed add-on authored in the host's frame carries `scene.extras.helixMeshFrame.bind
+ * { socket, root, matrix }`. The engine's `applyComposition` (CompositionPreview.ts) resolves it against the car's
+ * OWN nodes before it touches anything, and THROWS when the car lacks one:
+ *
+ *   - the mount node: the node the host's socket table resolves `bind.socket` to (`vehicleHostSockets` over the
+ *     node names, through `resolveSocketName`) — an offered socket the GLB has no node for is an unresolved mount,
+ *     and an unresolved mount is not drawn;
+ *   - `bind.root`: a node of that name must exist ("host mesh bind root '…' is absent");
+ *   - ownership: the mount node must sit inside `bind.root`'s subtree ("… does not own socket '…'").
+ *
+ * The throw happens while the car is being composed, so the car is never presented: no frame, no page error, and a
+ * preview that waits out its whole presentation timeout. A blind R34 run lost about an hour to a wing bound to a
+ * `vehicle_root` the host GLB did not have; a Ferrari F40 run lost the same hour to a missing `boot` mount node.
+ * Neither the host's validate nor its rail check said anything, because nothing on the host side stated the rule.
+ *
+ * Two entry points share one core:
+ *   - `checkBindAgainstHost`: one add-on's declared bind against the host's nodes. Exactly the engine's three tests.
+ *     Used by `vehicle addon check` (a directory against its hosts), `vehicle preview` (preflight) and the
+ *     published-rail check (`vehicle addon check --host`).
+ *   - `checkHostOffersBindableNodes`: the host alone (`vehicle validate --glb`). The add-on is not known, so the bind
+ *     root it will name is not either; this states what a host that offers a lid socket must carry for ANY add-on to
+ *     bind to it: the lid's mount node, and the host-frame root node, which owns the mount node. The root's name is the
+ *     documented host-frame origin (`vehicle_root`: what the BeamNG bridge writes and what the preview harness
+ *     measures the host frame from).
+ *
+ * Pure: node facts in, issues out. No I/O, no import of validate.ts at run time (validate.ts calls into this).
+ */
+import type { NodeFacts, VehicleIssue } from './validate';
+type Json = Record<string, unknown>;
+/** The documented host-frame root: the node a host-frame bind names as `root`, and the origin the host frame is measured from. */
+export declare const HOST_FRAME_ROOT = "vehicle_root";
+/** The lid sockets whose add-ons follow a moving panel (a wing rides the boot, a scoop rides the bonnet): the ones a host-frame bind names. */
+export declare const BINDABLE_PANEL_SOCKETS: readonly string[];
+/** The slice of the vendored engine validator this needs (its socket resolver, the same one the runtime composes with). */
+export interface SocketResolver {
+    resolveSocketName(raw: string, prefix?: string): {
+        id?: string;
+        warning?: string;
+    };
+    detectNodePrefix(names: readonly string[]): string | undefined;
+}
+export interface HostFrameIndex {
+    /** Node name → its facts (first in scene order wins, as `getObjectByName` does). */
+    byName: Map<string, NodeFacts>;
+    /** Canonical socket id → the host's own node name for it, built the way the engine's `vehicleHostSockets` builds it. */
+    socketNode: Map<string, string>;
+    facts: Map<number, NodeFacts>;
+    engine: SocketResolver;
+}
+export declare function buildHostFrameIndex(facts: Map<number, NodeFacts>, engine: SocketResolver): HostFrameIndex;
+export interface BindSubject {
+    /** Who is binding, for the message: `add-on "Wing" (vehicle.spoiler@1)`. */
+    label: string;
+    /** Where the bind was read from, for the issue path. */
+    path: string;
+    /** `host` (published car name or the candidate) for the message. */
+    hostLabel: string;
+}
+/** The engine's three bind tests (mount node, bind root, ownership) for ONE add-on's declared bind. */
+export declare function checkBindAgainstHost(bind: unknown, index: HostFrameIndex, subject: BindSubject): VehicleIssue[];
+/**
+ * The host alone: for every lid socket it OFFERS (a `boot`/`bonnet` socket in `asset.extras.HELIX_vehicle`, by name or
+ * through an alias), the mount node must exist and sit inside the host-frame root, and that root must exist. An add-on
+ * that binds to the lid (a wing, a scoop) can then compose.
+ */
+export declare function checkHostOffersBindableNodes(input: {
+    offered: readonly string[];
+    index: HostFrameIndex;
+}): VehicleIssue[];
+/** The socket keys `asset.extras.HELIX_vehicle` offers: `sockets` (an object of positions, or an array of names) and `socketNodes`. */
+export declare function offeredSocketKeys(manifest: unknown): string[];
+/** The `bind` an add-on GLB's scene declares, when it is a host-frame part; undefined otherwise. */
+export declare function declaredHostBind(sceneExtras: Json | undefined): Json | undefined;
+export {};

package/dist/vehicle/hostFrame.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BINDABLE_PANEL_SOCKETS = exports.HOST_FRAME_ROOT = void 0;
+exports.buildHostFrameIndex = buildHostFrameIndex;
+exports.checkBindAgainstHost = checkBindAgainstHost;
+exports.checkHostOffersBindableNodes = checkHostOffersBindableNodes;
+exports.offeredSocketKeys = offeredSocketKeys;
+exports.declaredHostBind = declaredHostBind;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The documented host-frame root: the node a host-frame bind names as `root`, and the origin the host frame is measured from. */
+exports.HOST_FRAME_ROOT = 'vehicle_root';
+/** The lid sockets whose add-ons follow a moving panel (a wing rides the boot, a scoop rides the bonnet): the ones a host-frame bind names. */
+exports.BINDABLE_PANEL_SOCKETS = ['boot', 'bonnet'];
+function buildHostFrameIndex(facts, engine) {
+    const names = [...facts.values()].map((f) => f.name);
+    const prefix = engine.detectNodePrefix(names);
+    const byName = new Map();
+    const socketNode = new Map();
+    for (const fact of facts.values()) {
+        if (!byName.has(fact.name))
+            byName.set(fact.name, fact);
+        const id = engine.resolveSocketName(fact.name, prefix).id;
+        // First name wins, as in the engine: `rim_lf` and `tyre_lf` both resolve to `wheel_lf`.
+        if (id !== undefined && !socketNode.has(id))
+            socketNode.set(id, fact.name);
+    }
+    return { byName, socketNode, facts, engine };
+}
+/** Is `node` the root or inside the root's subtree? */
+function isWithin(index, node, root) {
+    for (let cursor = node; cursor; cursor = cursor.parent === undefined ? undefined : index.facts.get(cursor.parent)) {
+        if (cursor.index === root.index)
+            return true;
+    }
+    return false;
+}
+const sampleNames = (index) => [...index.byName.keys()].slice(0, 8).map((n) => `'${n}'`).join(', ');
+const ROOT_FIX = (root) => `add an empty node named '${root}' to the car's GLB at the origin of the host frame, as the parent of every top-level node (the part's `
+    + `vertices are then posed in the car's own frame and still ride a moving lid), or re-author the add-on's bind.root onto a node the car has`;
+/** The engine's three bind tests (mount node, bind root, ownership) for ONE add-on's declared bind. */
+function checkBindAgainstHost(bind, index, subject) {
+    if (!isRecord(bind))
+        return [];
+    const issues = [];
+    const socket = typeof bind.socket === 'string' ? bind.socket : '';
+    const root = typeof bind.root === 'string' ? bind.root : '';
+    const { label, path, hostLabel } = subject;
+    let mount;
+    if (socket !== '') {
+        const id = index.engine.resolveSocketName(socket).id;
+        const nodeName = id !== undefined ? index.socketNode.get(id) : undefined;
+        mount = nodeName !== undefined ? index.byName.get(nodeName) : undefined;
+        if (id !== undefined && id !== socket) {
+            issues.push({ code: 'HOST_BIND_SOCKET_NOT_CANONICAL', level: 'warn', path: `${path}.socket`,
+                message: `${label} binds to socket '${socket}', which the runtime resolves to '${id}'; the engine compares the bind's socket to the resolved id by exact string, so a mount on '${id}' will refuse it`,
+                fix: `write bind.socket as '${id}'` });
+        }
+        if (mount === undefined) {
+            issues.push({ code: 'HOST_BIND_MOUNT_NODE_MISSING', level: 'error', path: `${path}.socket`,
+                message: `${label} binds to socket '${socket}', but ${hostLabel} has no node that resolves to ${id !== undefined && id !== socket ? `'${id}'` : `'${socket}'`} (a manifest position is not enough: the runtime mounts a part on a NODE), so the part has nothing to mount on and is not drawn`,
+                fix: `add a node named '${id ?? socket}' to the car's GLB, with its origin at the mount (for a lid, on the hinge line), and keep the manifest socket position equal to it` });
+        }
+    }
+    const rootNode = root !== '' ? index.byName.get(root) : undefined;
+    if (rootNode === undefined) {
+        issues.push({ code: 'HOST_BIND_ROOT_MISSING', level: 'error', path: `${path}.root`,
+            message: `${label} binds with root '${root}', but ${hostLabel} has no node of that name (it has e.g. ${sampleNames(index)}); the runtime throws "host mesh bind root '${root}' is absent" while composing the car, so the car is never presented and a preview waits out its whole timeout with no error`,
+            fix: ROOT_FIX(root || exports.HOST_FRAME_ROOT) });
+    }
+    else if (mount !== undefined && !isWithin(index, mount, rootNode)) {
+        issues.push({ code: 'HOST_BIND_ROOT_NOT_OWNER', level: 'error', path: `${path}.root`,
+            message: `${label} binds with root '${root}', but socket '${socket}' (node '${mount.name}') is not inside '${root}' in ${hostLabel}; the runtime throws "host mesh bind root '${root}' does not own socket '${socket}'" and the car is never presented`,
+            fix: `parent the '${root}' node over '${mount.name}' (an empty node that holds every top-level node does this), or bind to a root that contains it` });
+    }
+    return issues;
+}
+/**
+ * The host alone: for every lid socket it OFFERS (a `boot`/`bonnet` socket in `asset.extras.HELIX_vehicle`, by name or
+ * through an alias), the mount node must exist and sit inside the host-frame root, and that root must exist. An add-on
+ * that binds to the lid (a wing, a scoop) can then compose.
+ */
+function checkHostOffersBindableNodes(input) {
+    const { index } = input;
+    const lids = new Map(); // canonical id → the manifest key that offered it
+    for (const key of input.offered) {
+        const id = index.engine.resolveSocketName(key).id;
+        if (id !== undefined && exports.BINDABLE_PANEL_SOCKETS.includes(id) && !lids.has(id))
+            lids.set(id, key);
+    }
+    if (lids.size === 0)
+        return [];
+    const issues = [];
+    const root = index.byName.get(exports.HOST_FRAME_ROOT);
+    const offeredList = [...lids.keys()].map((id) => `'${id}'`).join(' and ');
+    if (root === undefined) {
+        issues.push({ code: 'HOST_BIND_ROOT_MISSING', level: 'error', path: `glb:node:${exports.HOST_FRAME_ROOT}`,
+            message: `the host offers the ${offeredList} socket${lids.size > 1 ? 's' : ''} (so wings, scoops and kits may bind to a moving lid) but its GLB has no '${exports.HOST_FRAME_ROOT}' node, the host-frame root a bind names; an add-on bound with root '${exports.HOST_FRAME_ROOT}' makes the runtime throw "host mesh bind root '${exports.HOST_FRAME_ROOT}' is absent" while composing the car, so the car is never presented and every preview and equip hangs without an error`,
+            fix: ROOT_FIX(exports.HOST_FRAME_ROOT) });
+    }
+    for (const [id, key] of lids) {
+        const nodeName = index.socketNode.get(id);
+        const mount = nodeName !== undefined ? index.byName.get(nodeName) : undefined;
+        if (mount === undefined) {
+            issues.push({ code: 'HOST_BIND_MOUNT_NODE_MISSING', level: 'error', path: `glb:asset.extras.HELIX_vehicle.sockets.${key}`,
+                message: `the host offers the '${id}' socket${key !== id ? ` (as '${key}')` : ''} as a position, but no node in its GLB resolves to '${id}'; the runtime mounts a part on a NODE, so any add-on bound to '${id}' has nothing to mount on and is not drawn`,
+                fix: `add a node named '${id}' (the lid itself, or an empty node on its hinge line) to the GLB; keep the manifest position equal to its origin` });
+        }
+        else if (root !== undefined && !isWithin(index, mount, root)) {
+            issues.push({ code: 'HOST_BIND_ROOT_NOT_OWNER', level: 'error', path: `glb:node:${mount.name}`,
+                message: `the '${id}' mount node '${mount.name}' is not inside '${exports.HOST_FRAME_ROOT}'; a bind with root '${exports.HOST_FRAME_ROOT}' makes the runtime throw "… does not own socket '${id}'" and the car is never presented`,
+                fix: `parent '${exports.HOST_FRAME_ROOT}' over '${mount.name}' (an empty node that holds every top-level node does this)` });
+        }
+    }
+    return issues;
+}
+/** The socket keys `asset.extras.HELIX_vehicle` offers: `sockets` (an object of positions, or an array of names) and `socketNodes`. */
+function offeredSocketKeys(manifest) {
+    if (!isRecord(manifest))
+        return [];
+    const keys = [];
+    if (Array.isArray(manifest.sockets))
+        keys.push(...manifest.sockets.filter((s) => typeof s === 'string').map((s) => s.trim()));
+    else if (isRecord(manifest.sockets))
+        keys.push(...Object.keys(manifest.sockets));
+    if (isRecord(manifest.socketNodes))
+        keys.push(...Object.keys(manifest.socketNodes));
+    return keys;
+}
+/** The `bind` an add-on GLB's scene declares, when it is a host-frame part; undefined otherwise. */
+function declaredHostBind(sceneExtras) {
+    const frame = isRecord(sceneExtras?.helixMeshFrame) ? sceneExtras.helixMeshFrame : undefined;
+    if (!frame || frame.authoringFrame !== 'host')
+        return undefined;
+    return isRecord(frame.bind) ? frame.bind : undefined;
+}
+//# sourceMappingURL=hostFrame.js.map

package/dist/vehicle/hostFrame.js.map

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

package/dist/vehicle/inspectionSheets.d.ts

@@ -0,0 +1,42 @@
+import type { VisualQaAssert, VisualQaFrame } from '../visualQa/types';
+export declare const INSPECTION_SCHEMA = "helix.vehicle-inspection/1";
+/** Sheet width in px. Tiles are downscaled to fit; a sheet is a JPEG of a few hundred KB, readable in one image turn. */
+export declare const SHEET_WIDTH = 1280;
+export interface InspectionSheet {
+    id: string;
+    file: string;
+    title: string;
+    look: string[];
+    tiles: number;
+    missing: string[];
+}
+export interface InspectionIndex {
+    schema: typeof INSPECTION_SCHEMA;
+    verdict: 'pass' | 'fail';
+    car: string;
+    engineVersion: string | null;
+    /** Read the sheets in this order; each `look` is the question to answer from that sheet alone. */
+    sheets: InspectionSheet[];
+    /** The executable occupant asserts (vehicle.occupants.*) and preview.inspection.complete. */
+    asserts: Array<{
+        id: string;
+        pass: boolean;
+        severity: 'block' | 'warn';
+        detail: string;
+    }>;
+}
+export declare const LOOK: Record<string, string>;
+export interface WriteInspectionInput {
+    out: string;
+    carName: string;
+    engineVersion: string | null;
+    frames: VisualQaFrame[];
+    facts: Record<string, unknown>;
+    asserts: VisualQaAssert[];
+}
+/** Lay out the sheets and the index; returns the index and the `preview.inspection.complete` assert. */
+export declare function writeInspectionSheets(input: WriteInspectionInput): Promise<{
+    index: InspectionIndex;
+    complete: VisualQaAssert;
+    dir: string;
+}>;