@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/vehicle/addon.d.ts

@@ -0,0 +1,158 @@
+import type { CliCredentials } from '../config';
+import { type DriveEffect } from './drive';
+import { type BytesFetch, type ItemRead, type Json, type Requester } from './platform';
+export type AddOnIssueLevel = 'error' | 'warn';
+export interface AddOnIssue {
+    code: string;
+    level: AddOnIssueLevel;
+    path: string;
+    message: string;
+    fix: string;
+}
+export interface AddOnSpec {
+    title: string;
+    description?: string;
+    tags?: string[];
+    slug?: string;
+    version?: string;
+    fits: Json;
+    ops: Json[];
+    provenance?: {
+        kind?: string;
+        source?: string;
+    };
+    definition?: Json;
+}
+export interface AddOnDir {
+    dir: string;
+    addonFile: string;
+    glbFile?: string;
+    thumbnailFile?: string;
+    spec: AddOnSpec;
+}
+export declare function readAddOnDir(dirArg: string, overrides?: {
+    glb?: string;
+}): AddOnDir;
+/** Slots the runtime draws NO geometry for (a GLB there is never seen): nothing to anchor. A subset of the slots whose part may
+ * be pure tuning with no model at all (`TUNE_ONLY_VEHICLE_SLOT_TYPES`): an engine, exhaust or tyre may be tune-only OR modelled. */
+export declare const TUNE_ONLY_SLOTS: Set<string>;
+/** Metres: a socket-frame mesh must be centred on its mount this closely (on the axes it does not face along). */
+export declare const SOCKET_CENTRE_TOLERANCE_M = 0.03;
+export declare function globMatches(glob: string, value: string): boolean;
+/** The add-on's own model: frame declaration and where its geometry sits relative to that frame. */
+export declare function checkAddOnModel(spec: AddOnSpec, glb: Buffer | undefined): {
+    issues: AddOnIssue[];
+    frame?: Json;
+    box?: {
+        min: number[];
+        max: number[];
+    };
+};
+export interface SlotRow {
+    id: string;
+    slotType: string;
+    hide: string[];
+    instanceId?: string;
+}
+export interface SlotBoard {
+    itemId: string;
+    hostKind: string;
+    slots: SlotRow[];
+    surface?: {
+        paths?: string[];
+    } & Json;
+}
+export interface HostReport {
+    id: string;
+    title?: string;
+    creatorId?: string;
+    ownedByYou: boolean;
+    issues: AddOnIssue[];
+    /** Hide globs the add-on needs that the host board does not grant, keyed by the board slot id that would grant them. */
+    missingGrants: Record<string, string[]>;
+    granted?: Record<string, string[]>;
+    /** Host wheel hubs (model frame) when this is a wheel add-on, for reference. */
+    hostNodes?: number;
+    /** Which GLB the host checks read (the pinned Package's model, or the item web asset). */
+    modelSource?: string;
+    /** Tunable paths the add-on requires that the host surface does not expose (a performance part then fits ZERO hosts). */
+    missingPaths?: string[];
+    /** The part's measured drive effect on this host (tune ops only; `--no-measure` skips it). */
+    drive?: {
+        engineVersion: string | null;
+        moved: string[];
+        perOp: Array<{
+            op: string;
+            moved: string[];
+        }>;
+    };
+}
+export interface FitDryRun {
+    ok: boolean;
+    issues: Array<{
+        pointer: string;
+        message: string;
+    }>;
+    fitsCount: number;
+    sample: Array<{
+        id: string;
+        title: string;
+    }>;
+}
+export declare function validateFitDryRun(api: Requester, fits: Json, ops: Json[]): Promise<FitDryRun>;
+export declare function getSlotBoard(api: Requester, hostId: string): Promise<SlotBoard>;
+/**
+ * The standard vehicle board's own hide grants per slot id. A board row's `hide` = these + the host's
+ * hostGrantExtensions, so the difference reveals which grants a new Vehicle Package Version needs.
+ * SYNC OBLIGATION: helix-backend-api src/add-ons/vehicle-slot-pack.ts (`hide:` of every SlotDefinition).
+ */
+export declare const STANDARD_VEHICLE_HIDES: Readonly<Record<string, readonly string[]>>;
+/** The host's current hostGrantExtensions: the board's own field when the backend returns it, else board − standard. */
+export declare function boardExtensions(board: SlotBoard & {
+    hostGrantExtensions?: Record<string, {
+        hide?: string[];
+    }>;
+}): Record<string, string[]>;
+/**
+ * The model the host actually DRAWS: its pinned Package Version's web model variant. The item's own `web` asset can
+ * be stale (the live 993's still has identity wheel origins; its pinned 1.0.8 GLB is fixed), so it is only the
+ * fallback for an unpinned host.
+ */
+export declare function hostModel(api: Requester, host: ItemRead, fetchBytes: BytesFetch, apiUrl: string, readObject?: (sha: string) => Promise<Uint8Array | undefined>): Promise<{
+    glb?: Buffer;
+    pkg?: Json;
+    source?: string;
+}>;
+/** Per-host checks: the host is a vehicle, its wheels are at the hubs (wheel slots), the hide targets exist, the board grants them. */
+export declare function checkHost(api: Requester, hostId: string, spec: AddOnSpec, me: string | null, apiUrl: string, fetchBytes?: BytesFetch, frame?: Json): Promise<HostReport>;
+export interface AddOnCheckReport {
+    ok: boolean;
+    slotType: string;
+    local: AddOnIssue[];
+    model: {
+        frame?: Json;
+        box?: {
+            min: number[];
+            max: number[];
+        };
+    };
+    hosts: HostReport[];
+    dryRun?: FitDryRun;
+    errors: number;
+    warnings: number;
+}
+/**
+ * The web customizer's meshless guard on the exact definition `vehicle addon publish` would seal. With no GLB the Package
+ * seals no web variant, so the customizer equips it only when the root is a verified meshless definition. `addon.json`'s
+ * `definition` is spread LAST into the root, so it can override the schema or restore a mesh: judge the merged object.
+ */
+export declare function customizerGuardIssues(spec: AddOnSpec, glb: Buffer | undefined): AddOnIssue[];
+/** The whole pre-publish gate. With `grant`, missing hide grants on hosts YOU own are opened (then re-checked). */
+export declare function checkAddOn(dir: AddOnDir, creds: CliCredentials, deps: {
+    api: Requester;
+    fetchBytes?: BytesFetch;
+    onProgress?: (m: string) => void;
+    /** Measure the tune ops on each host with the live runtime's physics (src/vehicle/drive.ts). Absent = not measured. */
+    measureDrive?: (vehiclePackage: Json, ops: Json[], slotType: string) => Promise<DriveEffect>;
+}): Promise<AddOnCheckReport>;
+export declare function formatAddOnReport(r: AddOnCheckReport): string;

package/dist/vehicle/addon.js

@@ -0,0 +1,441 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STANDARD_VEHICLE_HIDES = exports.SOCKET_CENTRE_TOLERANCE_M = exports.TUNE_ONLY_SLOTS = void 0;
+exports.readAddOnDir = readAddOnDir;
+exports.globMatches = globMatches;
+exports.checkAddOnModel = checkAddOnModel;
+exports.validateFitDryRun = validateFitDryRun;
+exports.getSlotBoard = getSlotBoard;
+exports.boardExtensions = boardExtensions;
+exports.hostModel = hostModel;
+exports.checkHost = checkHost;
+exports.customizerGuardIssues = customizerGuardIssues;
+exports.checkAddOn = checkAddOn;
+exports.formatAddOnReport = formatAddOnReport;
+/**
+ * Vehicle add-ons: prove local fit and host compatibility before sealing a Package.
+ *
+ *   `helix vehicle addon check <dir>`     local contract + anchoring + per-host checks + the backend's fit dry run
+ *
+ * Three silent failures this exists for, each seen live on the 993:
+ *   - a wheel add-on whose `hide` names `rim_*` fits ZERO hosts until the host's board grants `rim_*` (the standard
+ *     board grants only `wheel_stock_*`); correcting it requires a new sealed Vehicle Package Version;
+ *   - a socket-frame wheel anchors at the HOST wheel node's origin, so a host whose wheel origins are not at the hubs
+ *     draws all four wheels at the car's centre while every structural check passes;
+ *   - an unpinned add-on is hidden.
+ *
+ * Directory layout: `addon.json` { title, fits, ops, description?, tags?, slug?, version?, provenance?, definition? },
+ * an optional `model.glb` (or the single *.glb; clip-set slots ship none), optional `thumbnail.{png,jpg,webp}`.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const item_1 = require("../item");
+const addOnDefinition_1 = require("./addOnDefinition");
+const addonDefinitionGuard_1 = require("./addonDefinitionGuard");
+const drive_1 = require("./drive");
+const platform_1 = require("./platform");
+const validate_1 = require("./validate");
+const hostFrame_1 = require("./hostFrame");
+function readAddOnDir(dirArg, overrides = {}) {
+    const dir = (0, node_path_1.resolve)(dirArg);
+    const addonFile = ['addon.json', 'add-on.json'].map((f) => (0, node_path_1.join)(dir, f)).find(node_fs_1.existsSync);
+    if (!addonFile)
+        throw new Error(`${dir} has no addon.json ({ title, fits, ops, ... })`);
+    const spec = JSON.parse((0, node_fs_1.readFileSync)(addonFile, 'utf8'));
+    if (!(0, platform_1.isRecord)(spec) || typeof spec.title !== 'string' || !spec.title.trim())
+        throw new Error(`${addonFile} needs a "title"`);
+    if (!(0, platform_1.isRecord)(spec.fits))
+        throw new Error(`${addonFile} needs "fits" ({ slotType, requires, only: { items: [<host id>] } })`);
+    spec.ops = Array.isArray(spec.ops) ? spec.ops : [];
+    let glbFile = overrides.glb ? (0, node_path_1.resolve)(overrides.glb) : undefined;
+    if (!glbFile) {
+        const glbs = (0, node_fs_1.readdirSync)(dir).filter((f) => f.toLowerCase().endsWith('.glb'));
+        if (glbs.includes('model.glb'))
+            glbFile = (0, node_path_1.join)(dir, 'model.glb');
+        else if (glbs.length === 1)
+            glbFile = (0, node_path_1.join)(dir, glbs[0]);
+        else if (glbs.length > 1)
+            throw new Error(`${dir} has ${glbs.length} .glb files; name the add-on model.glb`);
+    }
+    const thumbnailFile = ['thumbnail.png', 'thumbnail.jpg', 'thumbnail.jpeg', 'thumbnail.webp'].map((f) => (0, node_path_1.join)(dir, f)).find(node_fs_1.existsSync);
+    return { dir, addonFile, glbFile, thumbnailFile, spec };
+}
+const WHEEL_SLOTS = new Set(['vehicle.wheel@1', 'vehicle.tyre@1']);
+/** Slots where a part that changes nothing about the drive is a defect: it must carry a tune op (or a sound mount). */
+const PERFORMANCE_SLOT = /engine|ecu|exhaust|transmission|gearbox|driveline|induction|intake|suspension|brake|arb|steering|diff|turbo|supercharger/i;
+/** Slots the runtime draws NO geometry for (a GLB there is never seen): nothing to anchor. A subset of the slots whose part may
+ * be pure tuning with no model at all (`TUNE_ONLY_VEHICLE_SLOT_TYPES`): an engine, exhaust or tyre may be tune-only OR modelled. */
+exports.TUNE_ONLY_SLOTS = new Set(['vehicle.ecu@1', 'vehicle.transmission@1', 'vehicle.suspension@1', 'vehicle.brakes@1', 'vehicle.arb@1', 'vehicle.steering@1', 'vehicle.driveline@1']);
+const HUB_ERRORS = new Set(['WHEEL_PIVOT_NOT_AT_HUB', 'WHEEL_ORIGINS_NOT_DISTINCT', 'WHEEL_NODES_MISSING']);
+/** Metres: a socket-frame mesh must be centred on its mount this closely (on the axes it does not face along). */
+exports.SOCKET_CENTRE_TOLERANCE_M = 0.03;
+function globMatches(glob, value) {
+    const escaped = glob.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`, 'i').test(value);
+}
+const hideGlobs = (ops) => ops.flatMap((op) => (op.v === 'hide' && Array.isArray(op.nodes) ? op.nodes.filter((n) => typeof n === 'string') : []));
+const hostIds = (fits) => ((0, platform_1.isRecord)(fits.only) && Array.isArray(fits.only.items) ? fits.only.items.filter((v) => typeof v === 'string') : []);
+/** The add-on's own model: frame declaration and where its geometry sits relative to that frame. */
+function checkAddOnModel(spec, glb) {
+    const issues = [];
+    const slotType = String(spec.fits.slotType ?? '');
+    if (!glb) {
+        if (item_1.CLIP_SET_SLOT_TYPES.includes(slotType))
+            return { issues };
+        if (item_1.TUNE_ONLY_VEHICLE_SLOT_TYPES.includes(slotType)) {
+            // A tune-only part: no geometry, its tune ops are the whole product. The backend admits it with no mesh only when every
+            // op is a `tune` (at least one; helix-backend-api#1675) — say so here, before anything is uploaded.
+            const ops = spec.ops ?? [];
+            const other = [...new Set(ops.map((op) => String(op.v)).filter((v) => v !== 'tune'))];
+            if (!ops.length) {
+                issues.push({ code: 'ADDON_TUNE_ONLY_NO_OPS', level: 'error', path: 'addon.json:ops', message: `a ${slotType} add-on with no model.glb is pure tuning, but it has no ops: it would change nothing`, fix: 'add { "v": "tune", "path": "<one of the slot\'s tunable paths>", "op": "mul|add", "value": ... } ops' });
+            }
+            else if (other.length) {
+                issues.push({ code: 'ADDON_TUNE_ONLY_GEOMETRY_OP', level: 'error', path: 'addon.json:ops', message: `a ${slotType} add-on with no model.glb may carry only "tune" ops; ${other.map((v) => `"${v}"`).join(', ')} needs geometry`, fix: 'add model.glb, or drop those ops' });
+            }
+            return { issues };
+        }
+        issues.push({ code: 'ADDON_MODEL_MISSING', level: 'error', path: 'model.glb', message: `a ${slotType} add-on draws geometry, but the directory has no .glb`, fix: 'add model.glb' });
+        return { issues };
+    }
+    if (exports.TUNE_ONLY_SLOTS.has(slotType)) {
+        issues.push({ code: 'ADDON_MODEL_ON_TUNE_SLOT', level: 'warn', path: 'model.glb',
+            message: `${slotType} is a tune-only slot; the runtime draws no geometry for it, so this model is never seen`,
+            fix: 'delete model.glb: a tune-only part needs no model (its ops are the product, and the server pictures it with its slot card)' });
+    }
+    const facts = (0, validate_1.glbSceneFacts)(glb);
+    const frame = (0, platform_1.isRecord)(facts.sceneExtras?.helixMeshFrame) ? facts.sceneExtras.helixMeshFrame : undefined;
+    if (!frame) {
+        if (!exports.TUNE_ONLY_SLOTS.has(slotType)) {
+            issues.push({ code: 'ADDON_FRAME_MISSING', level: 'error', path: 'glb:scene.extras.helixMeshFrame',
+                message: 'the model declares no helixMeshFrame, so the runtime cannot tell whether its vertices are socket-local or host-frame',
+                fix: WHEEL_SLOTS.has(slotType)
+                    ? 'set scenes[0].extras.helixMeshFrame = { contract: "helix.mesh-frame/1", authoringFrame: "socket", outboardAxis: "+x" } and centre the wheel on the origin'
+                    : 'set scenes[0].extras.helixMeshFrame = { contract: "helix.mesh-frame/1", authoringFrame: "host", bind: { socket, root, matrix } } for a part authored in the host frame' });
+        }
+        return { issues, box: facts.box };
+    }
+    if (frame.contract !== 'helix.mesh-frame/1') {
+        issues.push({ code: 'ADDON_FRAME_CONTRACT', level: 'error', path: 'glb:scene.extras.helixMeshFrame.contract', message: `contract is ${JSON.stringify(frame.contract)}, not "helix.mesh-frame/1"`, fix: 'set contract: "helix.mesh-frame/1"' });
+    }
+    if (frame.authoringFrame === 'socket') {
+        if (facts.box) {
+            const c = [0, 1, 2].map((a) => (facts.box.min[a] + facts.box.max[a]) / 2);
+            const outboard = typeof frame.outboardAxis === 'string' ? frame.outboardAxis.replace(/^[+-]/, '') : 'x';
+            const axes = ['x', 'y', 'z'];
+            const off = axes.map((name, i) => ({ name, d: c[i] })).filter((a) => a.name !== outboard && Math.abs(a.d) > exports.SOCKET_CENTRE_TOLERANCE_M);
+            if (off.length) {
+                issues.push({ code: 'ADDON_NOT_CENTRED_ON_MOUNT', level: 'error', path: 'glb',
+                    message: `authoringFrame "socket" means the mesh is centred on its mount, but its bounds centre is off by ${off.map((a) => `${a.d.toFixed(3)} m on ${a.name}`).join(', ')}; it will draw offset from the ${WHEEL_SLOTS.has(slotType) ? 'hub' : 'socket'}`,
+                    fix: 'translate the vertices so the part is centred on the origin (the hub for a wheel), then re-export' });
+            }
+        }
+    }
+    else if (frame.authoringFrame === 'host') {
+        const bind = (0, platform_1.isRecord)(frame.bind) ? frame.bind : undefined;
+        if (!bind || typeof bind.socket !== 'string') {
+            issues.push({ code: 'ADDON_HOST_FRAME_UNBOUND', level: 'warn', path: 'glb:scene.extras.helixMeshFrame.bind',
+                message: 'a host-frame part without bind { socket, root, matrix } stays static at the host root (a wing will not follow the boot lid)',
+                fix: 'add bind { socket: "<host node it moves with>", root, matrix }' });
+        }
+        if (WHEEL_SLOTS.has(slotType)) {
+            issues.push({ code: 'ADDON_WHEEL_HOST_FRAME', level: 'error', path: 'glb:scene.extras.helixMeshFrame.authoringFrame',
+                message: 'a wheel set is drawn once per corner; a host-frame wheel puts all four copies at one place',
+                fix: 'author one wheel centred on the origin with authoringFrame "socket", outboardAxis "+x"' });
+        }
+    }
+    else {
+        issues.push({ code: 'ADDON_FRAME_UNKNOWN', level: 'error', path: 'glb:scene.extras.helixMeshFrame.authoringFrame', message: `authoringFrame ${JSON.stringify(frame.authoringFrame)} is neither "socket" nor "host"`, fix: 'use "socket" or "host"' });
+    }
+    return { issues, frame, box: facts.box };
+}
+async function validateFitDryRun(api, fits, ops) {
+    return api.request('POST', '/api/v1/universal-items/validate-fit', { fits, ops });
+}
+async function getSlotBoard(api, hostId) {
+    return api.request('GET', `/api/v1/universal-items/${hostId}/slots`);
+}
+/**
+ * The standard vehicle board's own hide grants per slot id. A board row's `hide` = these + the host's
+ * hostGrantExtensions, so the difference reveals which grants a new Vehicle Package Version needs.
+ * SYNC OBLIGATION: helix-backend-api src/add-ons/vehicle-slot-pack.ts (`hide:` of every SlotDefinition).
+ */
+exports.STANDARD_VEHICLE_HIDES = {
+    'pwr.engine': ['engine_stock_*'], 'pwr.intake': ['intake_stock_*'], 'pwr.exhaust': ['exhaust_stock_*'],
+    'drv.driveline': ['driveline_stock_*'], 'hnd.suspension': ['suspension_stock_*'], 'whl.wheel': ['wheel_stock_*'],
+    'ext.bodykit': ['body_stock_*'], 'ext.bumper_f': ['bumper_f_stock_*'], 'ext.bumper_r': ['bumper_r_stock_*'],
+    'ext.spoiler': ['wing_stock_*'], 'ext.canards': ['canard_blank_*'], 'lgt.headlight': ['headlight_stock_*'],
+    'lgt.taillight': ['taillight_stock_*'], 'int.seats': ['seat_stock_*'], 'int.steering_wheel': ['steering_stock_*'],
+    'int.dash': ['dash_stock_*'],
+};
+/** The host's current hostGrantExtensions: the board's own field when the backend returns it, else board − standard. */
+function boardExtensions(board) {
+    if ((0, platform_1.isRecord)(board.hostGrantExtensions)) {
+        return Object.fromEntries(Object.entries(board.hostGrantExtensions).map(([k, v]) => [k, [...(v?.hide ?? [])]]).filter(([, v]) => v.length));
+    }
+    const out = {};
+    for (const row of board.slots ?? []) {
+        const standard = new Set(exports.STANDARD_VEHICLE_HIDES[row.id] ?? []);
+        const extra = (row.hide ?? []).filter((g) => !standard.has(g));
+        if (!extra.length)
+            continue;
+        out[row.id] = [...new Set([...(out[row.id] ?? []), ...extra])];
+    }
+    return out;
+}
+/**
+ * The model the host actually DRAWS: its pinned Package Version's web model variant. The item's own `web` asset can
+ * be stale (the live 993's still has identity wheel origins; its pinned 1.0.8 GLB is fixed), so it is only the
+ * fallback for an unpinned host.
+ */
+async function hostModel(api, host, fetchBytes, apiUrl, readObject) {
+    const pkg = (0, platform_1.isRecord)(host.properties?.vehiclePackage) ? host.properties.vehiclePackage : undefined;
+    const pin = host.continuumPackagePin;
+    if (pin) {
+        try {
+            const pv = await api.request('GET', `/api/v1/continuum/public/packages/${pin.packageId}/versions/${encodeURIComponent(pin.version)}`);
+            const variant = (pv.manifest?.variants ?? []).find((v) => v.object?.mediaType === 'model/gltf-binary' && /model/.test(String(v.object?.role)))
+                ?? (pv.manifest?.variants ?? []).find((v) => v.object?.mediaType === 'model/gltf-binary');
+            const cid = variant?.object?.cid;
+            if (cid) {
+                const sha = cid.slice('cid:sha256:'.length);
+                const bytes = await (readObject ?? ((s) => (0, platform_1.fetchPublicObject)(apiUrl, s, fetchBytes)))(sha);
+                if (bytes)
+                    return { glb: Buffer.from(bytes), pkg, source: `${pin.packageId}@${pin.version} ${cid}` };
+            }
+        }
+        catch { /* fall back to the item's web asset */ }
+    }
+    const web = (host.assets ?? []).find((a) => String(a.rendition).toLowerCase() === 'web' && a.status === 'ready' && a.cdnUrl);
+    if (!web?.cdnUrl)
+        return { pkg };
+    const got = await fetchBytes(web.cdnUrl);
+    return { glb: got.status === 200 ? Buffer.from(got.bytes) : undefined, pkg, source: `item web asset ${web.id}` };
+}
+/** Per-host checks: the host is a vehicle, its wheels are at the hubs (wheel slots), the hide targets exist, the board grants them. */
+async function checkHost(api, hostId, spec, me, apiUrl, fetchBytes = platform_1.defaultBytesFetch, frame) {
+    const issues = [];
+    const path = `fits.only.items[${hostId}]`;
+    let host;
+    try {
+        host = await (0, platform_1.getItem)(api, hostId);
+    }
+    catch (error) {
+        return { id: hostId, ownedByYou: false, missingGrants: {}, issues: [{ code: 'HOST_NOT_FOUND', level: 'error', path, message: `host ${hostId} could not be read: ${error.message}`, fix: 'name a published vehicle item id' }] };
+    }
+    const report = { id: hostId, title: host.title, creatorId: host.creatorId, ownedByYou: !!me && host.creatorId === me, issues, missingGrants: {} };
+    if (host.kind !== 'vehicle') {
+        issues.push({ code: 'HOST_NOT_VEHICLE', level: 'error', path, message: `host ${hostId} ("${host.title}") is a ${host.kind}, not a vehicle`, fix: 'fits.only.items must name vehicle items' });
+        return report;
+    }
+    const slotType = String(spec.fits.slotType ?? '');
+    const globs = hideGlobs(spec.ops);
+    const { glb, pkg, source } = await hostModel(api, host, fetchBytes, apiUrl);
+    report.modelSource = source;
+    let nodeNames = [];
+    if (glb) {
+        nodeNames = (0, validate_1.glbSceneFacts)(glb).nodeNames;
+        report.hostNodes = nodeNames.length;
+        if (WHEEL_SLOTS.has(slotType) && pkg) {
+            const v = await (0, validate_1.validateVehicle)(pkg, glb);
+            for (const issue of v.issues.filter((i) => HUB_ERRORS.has(i.code))) {
+                issues.push({ code: 'HOST_WHEELS_NOT_AT_HUBS', level: 'error', path: `${path}:${issue.path}`,
+                    message: `host "${host.title}": ${issue.message} — a socket-frame wheel anchors at the host wheel node's origin, so this add-on would draw at the wrong place (the vehicle centre when origins are at identity)`,
+                    fix: `the HOST must be fixed and republished first: ${issue.fix}` });
+            }
+        }
+        // A host-frame bind is composed against the car's own nodes; a missing one makes the runtime throw and never present the car.
+        const bind = frame?.authoringFrame === 'host' && (0, platform_1.isRecord)(frame.bind) ? frame.bind : undefined;
+        if (bind) {
+            try {
+                const index = (0, validate_1.hostFrameIndexOfGlb)(glb, await (0, validate_1.loadVehicleValidator)());
+                issues.push(...(0, hostFrame_1.checkBindAgainstHost)(bind, index, { label: `this ${slotType || 'add-on'} part`, path: 'glb:scene.extras.helixMeshFrame.bind', hostLabel: `host "${host.title}"` }));
+            }
+            catch (error) {
+                issues.push({ code: 'HOST_BIND_UNCHECKED', level: 'warn', path, message: `host "${host.title}": the host-frame bind could not be checked against the car's nodes (${error.message})`, fix: 'check the host GLB loads' });
+            }
+        }
+        for (const glob of globs) {
+            if (!nodeNames.some((n) => globMatches(glob, n))) {
+                issues.push({ code: 'HIDE_TARGET_ABSENT', level: 'error', path: `ops.hide:${glob}`,
+                    message: `host "${host.title}" has no node matching "${glob}", so nothing is hidden and the stock part shows through`,
+                    fix: `use the host's real node names (it has e.g. ${nodeNames.slice(0, 12).join(', ')})` });
+            }
+        }
+    }
+    else {
+        issues.push({ code: 'HOST_MODEL_UNREADABLE', level: 'warn', path, message: `host "${host.title}" has no readable web GLB, so hub and node checks were skipped`, fix: 'check the host item renders' });
+    }
+    const requiredPaths = (0, platform_1.isRecord)(spec.fits.requires) && Array.isArray(spec.fits.requires.paths)
+        ? spec.fits.requires.paths.filter((p) => typeof p === 'string') : [];
+    if (requiredPaths.length) {
+        const board = await getSlotBoard(api, hostId).catch(() => null);
+        const exposed = new Set(board?.surface?.paths ?? []);
+        const missing = requiredPaths.filter((p) => !exposed.has(p));
+        if (board && missing.length) {
+            report.missingPaths = missing;
+            // A car published before helix-backend-api#1677 got a board with surface.paths [] (its mesh could not declare them);
+            // every car published since exposes the tunable paths its vehicle package resolves.
+            issues.push({ code: 'HOST_PATHS_MISSING', level: 'error', path: `${path}:surface.paths`,
+                message: `host "${host.title}" does not expose ${missing.join(', ')}${exposed.size ? '' : ' (its board exposes no tunable paths at all)'}; an add-on that requires them fits ZERO hosts, so this part would never appear on the car`,
+                fix: report.ownedByYou
+                    ? `expose them on the host (seal a new Vehicle Package Version whose board surface includes them, pass visual QA, then move Item ${hostId}; an owner may also widen surface.paths with PUT /api/v1/universal-items/${hostId}/slots)`
+                    : `the host's creator must expose ${missing.join(', ')} on its board` });
+        }
+    }
+    if (globs.length) {
+        const board = await getSlotBoard(api, hostId);
+        const rows = (board.slots ?? []).filter((r) => r.slotType === slotType);
+        if (!rows.length) {
+            issues.push({ code: 'HOST_HAS_NO_SLOT', level: 'error', path, message: `host "${host.title}" exposes no ${slotType} opening`, fix: 'the host must publish a board with this slot (hostKind vehicle + standard slots)' });
+        }
+        else {
+            for (const glob of globs) {
+                const targets = nodeNames.filter((n) => globMatches(glob, n));
+                const granted = rows.some((row) => (row.hide ?? []).some((g) => g.toLowerCase() === glob.toLowerCase()
+                    || (targets.length > 0 && targets.every((t) => globMatches(g, t)))));
+                if (!granted) {
+                    const slotId = rows[0].id;
+                    (report.missingGrants[slotId] ??= []).push(glob);
+                }
+            }
+            if (Object.keys(report.missingGrants).length) {
+                const grants = JSON.stringify(Object.fromEntries(Object.entries(report.missingGrants).map(([k, v]) => [k, { hide: v }])));
+                issues.push({ code: 'HOST_GRANT_MISSING', level: 'error', path,
+                    message: `host "${host.title}" does not grant hiding ${Object.values(report.missingGrants).flat().join(', ')} in ${Object.keys(report.missingGrants).join(', ')}; without the grant this add-on fits ZERO hosts`,
+                    fix: report.ownedByYou
+                        ? `seal a new Vehicle Package Version with hostGrantExtensions ${grants}, pass visual QA, then move Item ${hostId}`
+                        : `the host's creator must seal a new Vehicle Package Version with hostGrantExtensions ${grants}` });
+            }
+        }
+    }
+    return report;
+}
+/**
+ * The web customizer's meshless guard on the exact definition `vehicle addon publish` would seal. With no GLB the Package
+ * seals no web variant, so the customizer equips it only when the root is a verified meshless definition. `addon.json`'s
+ * `definition` is spread LAST into the root, so it can override the schema or restore a mesh: judge the merged object.
+ */
+function customizerGuardIssues(spec, glb) {
+    if (glb || !(0, platform_1.isRecord)(spec.fits))
+        return [];
+    const root = JSON.parse(JSON.stringify((0, addOnDefinition_1.addOnDefinition)(spec, null)));
+    const error = (0, addonDefinitionGuard_1.meshlessAddOnManifestError)({ variantMediaTypes: [], root: { role: 'addon-definition', mediaType: 'application/json' } })
+        ?? (0, addonDefinitionGuard_1.meshlessAddOnDefinitionError)(root);
+    if (error === null)
+        return [];
+    return [{ code: 'ADDON_CUSTOMIZER_REFUSES', level: 'error', path: 'addon.json:definition',
+            message: `${error} The web customizer would refuse to equip or save this add-on (it seals no web GLB, and its definition is not a verified meshless one)`,
+            fix: 'add model.glb if the part has geometry; otherwise drop `definition` overrides that restore a mesh or change the schema, and keep every op a `tune` (or a sound mount)' }];
+}
+/** The whole pre-publish gate. With `grant`, missing hide grants on hosts YOU own are opened (then re-checked). */
+async function checkAddOn(dir, creds, deps) {
+    const say = deps.onProgress ?? (() => undefined);
+    const spec = dir.spec;
+    const local = [];
+    try {
+        (0, item_1.validateAddOnContract)(spec.fits, spec.ops);
+    }
+    catch (error) {
+        local.push({ code: 'ADDON_CONTRACT', level: 'error', path: 'addon.json', message: error.message, fix: 'fix fits/ops (read_doc vehicles §11)' });
+    }
+    const ids = hostIds(spec.fits);
+    if (!ids.length)
+        local.push({ code: 'ADDON_NO_HOST', level: 'error', path: 'fits.only.items', message: 'fits.only.items names no host; universal vehicle add-ons are refused', fix: 'list the vehicle item ids this part fits' });
+    const glb = dir.glbFile ? (0, node_fs_1.readFileSync)(dir.glbFile) : undefined;
+    const model = checkAddOnModel(spec, glb);
+    local.push(...model.issues);
+    local.push(...customizerGuardIssues(spec, glb));
+    const me = (0, platform_1.tokenSubject)(creds.token);
+    const hosts = [];
+    for (const id of ids) {
+        const report = await checkHost(deps.api, id, spec, me, creds.apiUrl, deps.fetchBytes, model.frame);
+        hosts.push(report);
+    }
+    const tuneOps = (spec.ops ?? []).filter((op) => op.v === 'tune');
+    // A performance-slot part (engine, ECU, gearbox, exhaust, brakes, …) that carries no tune op and no sound mount
+    // changes nothing about how the car drives. Round 5 sold a "competition exhaust" that was a hide + a mesh and no
+    // tune op — a part that does nothing. Refuse it up front, before any drive measurement (which only runs when there
+    // ARE tune ops, so a no-op exhaust would otherwise pass silently).
+    const slotType = String(spec.fits.slotType ?? '');
+    const hasSoundMount = (spec.ops ?? []).some((op) => op.v === 'mount' && (0, platform_1.isRecord)(op.row) && op.row.type === 'sound');
+    if (PERFORMANCE_SLOT.test(slotType) && tuneOps.length === 0 && !hasSoundMount) {
+        local.push({ code: 'ADDON_PERFORMANCE_NO_EFFECT', level: 'error', path: 'addon.json:ops',
+            message: `a ${slotType} add-on is a performance part but carries no tune op (and no sound mount): it changes nothing about how the car drives`,
+            fix: 'add at least one { "v": "tune", "path", "op", "value" } op that measurably moves a drive figure (an exhaust changes power or weight: drivetrain.engine.torqueCurve / limiterRpm, or chassis.mass), or sell it as a cosmetic part with a sound mount { v: "mount", row: { type: "sound", id } }' });
+    }
+    if (deps.measureDrive && tuneOps.length) {
+        for (const report of hosts) {
+            if (report.issues.some((i) => i.code === 'HOST_NOT_FOUND' || i.code === 'HOST_NOT_VEHICLE'))
+                continue;
+            const path = `drive:${report.id}`;
+            try {
+                const host = await (0, platform_1.getItem)(deps.api, report.id);
+                const pkg = (0, platform_1.isRecord)(host.properties?.vehiclePackage) ? host.properties.vehiclePackage : undefined;
+                if (!pkg) {
+                    report.issues.push({ code: 'ADDON_DRIVE_UNMEASURED', level: 'warn', path, message: `host "${report.title ?? report.id}" carries no vehicle package, so the drive effect was not measured`, fix: 'check the host is a published vehicle' });
+                    continue;
+                }
+                say(`measuring the drive effect on "${report.title ?? report.id}" with the live runtime's physics`);
+                const effect = await deps.measureDrive(pkg, tuneOps, String(spec.fits.slotType ?? ''));
+                report.drive = {
+                    engineVersion: effect.engineVersion,
+                    moved: effect.moved.map(drive_1.fmtDelta),
+                    perOp: effect.perOp.map((p) => ({ op: p.op, moved: p.deltas.filter((d) => d.moved).map(drive_1.fmtDelta) })),
+                };
+                for (const f of effect.findings) {
+                    if (f.level === 'info')
+                        continue;
+                    report.issues.push({ code: f.code, level: f.level, path, message: `on "${report.title ?? report.id}": ${f.message}`,
+                        fix: f.code === 'ADDON_DRIVE_NO_EFFECT'
+                            ? 'make the change large enough to matter, or tune paths that move what this part is for (brakes: maxTorque; sway bars: land.antiRollBar.*; ECU: torqueCurve as well as limiterRpm)'
+                            : f.code === 'ADDON_DRIVE_OP_CANCELS' ? 'drop or reverse that op so every op pushes the same way' : 'read the warning; the engine applied the rest' });
+                }
+            }
+            catch (error) {
+                report.issues.push({ code: 'ADDON_DRIVE_UNMEASURED', level: 'warn', path, message: `the drive effect could not be measured: ${error.message}`, fix: 're-run; or pass --no-measure to skip' });
+            }
+        }
+    }
+    let dryRun;
+    if (!local.some((i) => i.code === 'ADDON_CONTRACT')) {
+        dryRun = await validateFitDryRun(deps.api, spec.fits, spec.ops);
+        if (!dryRun.ok) {
+            for (const i of dryRun.issues)
+                local.push({ code: 'BACKEND_FIT_REFUSED', level: 'error', path: i.pointer, message: i.message, fix: 'the backend will refuse this publish; fix the field it names' });
+        }
+        else {
+            const fitting = new Set(dryRun.sample.map((s) => s.id));
+            for (const id of ids) {
+                if (!fitting.has(id) && dryRun.fitsCount < ids.length) {
+                    local.push({ code: 'FITS_ZERO_HOSTS', level: 'error', path: `fits.only.items[${id}]`,
+                        message: `the backend dry run says this add-on fits ${dryRun.fitsCount} host(s) and not ${id}; a published copy would never appear on that car`,
+                        fix: 'read the HOST_* findings above (a missing hide grant is the usual cause)' });
+                }
+            }
+        }
+    }
+    const all = [...local, ...hosts.flatMap((h) => h.issues)];
+    const errors = all.filter((i) => i.level === 'error').length;
+    return { ok: errors === 0, slotType: String(spec.fits.slotType ?? ''), local, model: { frame: model.frame, box: model.box }, hosts, dryRun, errors, warnings: all.length - errors };
+}
+function formatAddOnReport(r) {
+    const lines = [];
+    if (r.model.frame)
+        lines.push(`  frame: ${JSON.stringify(r.model.frame)}`);
+    if (r.model.box)
+        lines.push(`  bounds: min ${r.model.box.min.map((n) => n.toFixed(3)).join(',')} max ${r.model.box.max.map((n) => n.toFixed(3)).join(',')}`);
+    for (const h of r.hosts) {
+        lines.push(`  host ${h.id} "${h.title ?? '?'}"${h.ownedByYou ? ' (yours)' : ''}${h.modelSource ? ` — model ${h.modelSource}` : ''}${h.granted ? ` — granted ${JSON.stringify(h.granted)}` : ''}`);
+        if (h.drive)
+            lines.push(`    drive (runtime ${h.drive.engineVersion ?? '?'}): ${h.drive.moved.length ? h.drive.moved.join(', ') : 'no measurable change'}`);
+    }
+    if (r.dryRun)
+        lines.push(`  backend dry run: ${r.dryRun.ok ? `fits ${r.dryRun.fitsCount} host(s)${r.dryRun.sample.length ? ` (${r.dryRun.sample.map((s) => s.title).join(', ')})` : ''}` : 'refused'}`);
+    for (const issue of [...r.local, ...r.hosts.flatMap((h) => h.issues)]) {
+        lines.push(`${issue.level === 'error' ? '✖' : '⚠'} [${issue.code}] ${issue.path}: ${issue.message}\n    fix: ${issue.fix}`);
+    }
+    lines.push(`${r.ok ? '✔' : '✖'} ${r.slotType} add-on: ${r.errors} error${r.errors === 1 ? '' : 's'}, ${r.warnings} warning${r.warnings === 1 ? '' : 's'}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=addon.js.map