@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/dist/visualQa/moveUx.js

@@ -0,0 +1,103 @@
+"use strict";
+// The creator-facing words around a version move on a listed item: publish-version (seals vN from a new GLB; the
+// move is refused) -> visual-qa --package-version vN --submit -> set-version. Every function here is pure so the
+// wording is unit-tested.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION_MOVE_FLOW_HELP = exports.VISUAL_QA_CANDIDATE_FORBIDDEN = void 0;
+exports.setVersionCommand = setVersionCommand;
+exports.nextStepAfterPass = nextStepAfterPass;
+exports.candidateForbiddenMessage = candidateForbiddenMessage;
+exports.isCandidateForbidden = isCandidateForbidden;
+exports.orderCandidateErrors = orderCandidateErrors;
+exports.versionNotFoundMessage = versionNotFoundMessage;
+exports.sealedVersionsFrom = sealedVersionsFrom;
+exports.describePendingVersions = describePendingVersions;
+exports.VISUAL_QA_CANDIDATE_FORBIDDEN = 'VISUAL_QA_CANDIDATE_FORBIDDEN';
+/** The one paragraph `item visual-qa --help`, `item set-version --help` and `item publish-version --help` carry. */
+exports.VERSION_MOVE_FLOW_HELP = '\nMoving a LISTED item to a new version (the visual-QA gate refuses the move until that version has a passing run):\n' +
+    '  1. helix item publish-version <id> <file> --reason "…"   seals vN from a new GLB; the move itself is refused and says so\n' +
+    '     (an authored Package descriptor is sealed instead with: helix continuum publish-package <descriptor.json> --stage)\n' +
+    '  2. helix item visual-qa <id> --package-version vN --submit   renders vN headless and records the verdict (creator only)\n' +
+    '  3. helix item set-version <id> --package-version vN --reason "…"   moves the item to vN once step 2 passed\n' +
+    '  (vehicles also pass --vehicle-package <file> to steps 2–3; helix item visual-qa <id> --status shows pending versions)\n';
+/** `helix item set-version …` for a version that just passed, ready to paste. */
+function setVersionCommand(itemId, packageVersion) {
+    return `helix item set-version ${itemId} --package-version ${packageVersion} --reason "<why>"`;
+}
+/** What to print after a candidate run that was submitted and passed. Empty when there is nothing to say. */
+function nextStepAfterPass(input) {
+    if (!input.candidate || !input.packageVersion || input.verdict !== 'pass')
+        return [];
+    if (!input.submitted)
+        return [];
+    return [`  next: ${setVersionCommand(input.itemId, input.packageVersion)}`];
+}
+function candidateForbiddenMessage(itemId, version) {
+    return `Version ${version} was refused for this login (403 ${exports.VISUAL_QA_CANDIDATE_FORBIDDEN}): only the item's creator, an admin or the hosted visual-QA runner can render a version the item is not pinned to yet. ` +
+        `The creator can: sign in as the creator (helix login) and run helix item visual-qa ${itemId} --package-version ${version} --submit.`;
+}
+/** The 403 the backend answers a non-owner's candidate request with, as seen by the browser routes (`{status, body}`). */
+function isCandidateForbidden(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const r = raw;
+    const body = typeof r.body === 'string' ? r.body : r.body ? JSON.stringify(r.body) : '';
+    return body.includes(exports.VISUAL_QA_CANDIDATE_FORBIDDEN) || (r.status === 403 && /preview a Package Version that is not the current/i.test(body));
+}
+/** Put the forbidden refusal first: it explains every other symptom (the page's vague "ITEM TRIAL UNAVAILABLE", missing frames). */
+function orderCandidateErrors(routeErrors, candidateErrors) {
+    const forbidden = candidateErrors.filter((e) => e.includes(exports.VISUAL_QA_CANDIDATE_FORBIDDEN));
+    const rest = candidateErrors.filter((e) => !forbidden.includes(e));
+    return [...forbidden, ...routeErrors, ...rest];
+}
+function versionNotFoundMessage(input) {
+    const known = input.sealed === null
+        ? 'the creator can list them with GET /api/v1/continuum/packages/<packageId>/versions (sign in with helix login as the creator to have this command do it)'
+        : input.sealed.length
+            ? `sealed versions: ${input.sealed.join(', ')}`
+            : 'it has no sealed versions';
+    return `Package ${input.packageId} has no version ${input.version}; ${known}`;
+}
+/** Sealed (or superseded) version strings from the owner's package-version listing, newest first as served. */
+function sealedVersionsFrom(body) {
+    const o = (body && typeof body === 'object' ? body : {});
+    const nested = (v) => (v && typeof v === 'object' ? v : {});
+    // The owner listing answers `{ state, data: { items } }`; older/other shapes are tolerated.
+    const list = Array.isArray(body) ? body : [o.items, o.versions, o.data, nested(o.data).items, nested(o.page).items].find(Array.isArray);
+    if (!Array.isArray(list))
+        return null;
+    const out = [];
+    for (const row of list) {
+        if (typeof row?.version !== 'string')
+            continue;
+        if (row.lifecycle !== undefined && row.lifecycle !== 'sealed' && row.lifecycle !== 'superseded')
+            continue;
+        out.push(row.version);
+    }
+    return out;
+}
+/** `--status` lines for the backend's `pendingVersions` (sealed versions of the item's package that are not current). */
+function describePendingVersions(itemId, pending) {
+    if (!pending?.length)
+        return [];
+    const lines = ['pending versions (sealed, not current):'];
+    for (const p of pending) {
+        const run = p.latestRun;
+        const job = p.hostedJob;
+        const parts = [];
+        parts.push(run ? `${String(run.verdict ?? 'run').toUpperCase()}${run.createdAt ? ` (${run.createdAt})` : ''}` : 'no run');
+        if (job?.status)
+            parts.push(`hosted job ${job.status}${job.attempts ? ` · attempt ${job.attempts}` : ''}`);
+        lines.push(`  ${p.packageVersion}  ${parts.join(' · ')}`);
+        if (run?.contactSheetUrl)
+            lines.push(`    contact sheet: ${run.contactSheetUrl}`);
+        if (run?.verdict === 'pass')
+            lines.push(`    next: ${setVersionCommand(itemId, p.packageVersion)}`);
+        else if (run?.verdict === 'fail')
+            lines.push(`    failed: fix the item and ship a corrected version (re-render this one only if the verdict is wrong: helix item visual-qa ${itemId} --package-version ${p.packageVersion} --submit)`);
+        else
+            lines.push(`    render: helix item visual-qa ${itemId} --package-version ${p.packageVersion} --submit`);
+    }
+    return lines;
+}
+//# sourceMappingURL=moveUx.js.map

package/dist/visualQa/moveUx.js.map

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

package/dist/visualQa/pinnedChrome.d.ts

@@ -0,0 +1,63 @@
+export declare const CFT_LAST_KNOWN_GOOD_URL = "https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json";
+export type CftPlatform = 'mac-arm64' | 'mac-x64' | 'linux64' | 'win64';
+/** Re-resolve stable when the pin is older than this (best effort: an offline host keeps the build it has). */
+export declare const PIN_MAX_AGE_MS: number;
+export interface PinnedChrome {
+    version: string;
+    platform: CftPlatform;
+    /** Path as the launching OS sees it (a Windows path for win64 installed from WSL). */
+    executablePath: string;
+    /** Where the install lives as THIS process sees it. */
+    dir: string;
+    resolvedFrom: string;
+    resolvedAt: string;
+}
+export declare function cftPlatform(platform?: NodeJS.Platform, arch?: string): CftPlatform;
+/** Path of the executable inside an unpacked CfT zip, relative to the install dir. */
+export declare function executableRel(platform: CftPlatform): string;
+/** Default cache dir for this OS. `HELIX_VQA_CHROME_CACHE` overrides. */
+export declare function defaultCacheDir(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, home?: string): string;
+/** The current Stable build for a platform, from the official last-known-good endpoint. Pure over the parsed JSON. */
+export declare function stableFromJson(json: unknown, platform: CftPlatform): {
+    version: string;
+    url: string;
+};
+export declare function resolveStable(platform: CftPlatform, fetchImpl?: typeof fetch): Promise<{
+    version: string;
+    url: string;
+}>;
+/** The pin recorded in `cacheDir`, if its executable is still there. `toLocal` maps a recorded path to one this process can stat. */
+export declare function readPin(cacheDir: string, platform: CftPlatform): PinnedChrome | null;
+export interface InstallOptions {
+    platform?: CftPlatform;
+    /** Cache dir as THIS process sees it. */
+    cacheDir?: string;
+    /** Turn the local executable path into the one the launching OS uses (WSL → Windows path for win64). */
+    toLaunchPath?: (localPath: string) => string;
+    /** Re-resolve stable even when a fresh pin exists. */
+    refresh?: boolean;
+    log?: (msg: string) => void;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Make sure the current-stable Chrome for Testing is installed and pinned; return it. Idempotent and cheap when the
+ * pin is fresh (no network). A pin older than PIN_MAX_AGE_MS (or `refresh`) re-resolves stable; if that fails the
+ * existing pin is kept, so an offline host still renders on the last stable it had.
+ */
+export declare function ensurePinnedChrome(opts?: InstallOptions): Promise<PinnedChrome>;
+/** Where the executable came from, recorded in every bundle as `harness.browser.channel`. */
+export type BrowserChannel = 'pinned-cft' | 'env-override' | 'explicit' | 'remote-cdp';
+export interface ResolvedExecutable {
+    executablePath: string;
+    channel: BrowserChannel;
+    pinned?: PinnedChrome;
+}
+/**
+ * The executable a local (non-CDP) render launches: an explicit path, else `HELIX_VQA_CHROME`, else the pinned
+ * current-stable Chrome for Testing (installed on first use). Never Playwright's bundled build, never the system Chrome.
+ */
+export declare function resolveVqaExecutable(opts?: {
+    explicit?: string;
+    env?: NodeJS.ProcessEnv;
+    log?: (m: string) => void;
+}): Promise<ResolvedExecutable>;

package/dist/visualQa/pinnedChrome.js

@@ -0,0 +1,214 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PIN_MAX_AGE_MS = exports.CFT_LAST_KNOWN_GOOD_URL = void 0;
+exports.cftPlatform = cftPlatform;
+exports.executableRel = executableRel;
+exports.defaultCacheDir = defaultCacheDir;
+exports.stableFromJson = stableFromJson;
+exports.resolveStable = resolveStable;
+exports.readPin = readPin;
+exports.ensurePinnedChrome = ensurePinnedChrome;
+exports.resolveVqaExecutable = resolveVqaExecutable;
+// The browser every visual-QA render runs on: a Chrome for Testing build that matches CURRENT STABLE Chrome, pinned in
+// a cache dir of its own (never the user's Chrome, never their profile).
+//
+// Why not Playwright's bundled Chromium: Playwright ships a pre-stable Chrome for Testing build, and that build can
+// carry a bug real users never see. Measured 2026-10-03: chromium-1243 (153.0.8010.12) fails to compile any WGSL that
+// reads a component off a swizzle (`v.xy.x`) on Metal ("swizzle view instruction still has usages after lowering"),
+// three r185 emits exactly that for every lit node material, so every WebGPU render in that build went black or
+// bodyless while stable 153.0.8010.52 and 154 drew the body. A gate that renders on a build no user has judges the
+// browser, not the item. So the gate resolves "current stable" from Google's own Chrome for Testing endpoint at install
+// time and renders on that build. `HELIX_VQA_CHROME` still overrides (and is recorded as such).
+//
+// Layout: `<cache>/<platform>-<version>/<zip root>/...` plus `<cache>/pinned-<platform>.json` naming the build in use.
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+exports.CFT_LAST_KNOWN_GOOD_URL = 'https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json';
+/** Re-resolve stable when the pin is older than this (best effort: an offline host keeps the build it has). */
+exports.PIN_MAX_AGE_MS = 14 * 24 * 3600 * 1000;
+function cftPlatform(platform = process.platform, arch = process.arch) {
+    if (platform === 'darwin')
+        return arch === 'arm64' ? 'mac-arm64' : 'mac-x64';
+    if (platform === 'win32')
+        return 'win64';
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux64';
+    throw new Error(`no Chrome for Testing build for ${platform}/${arch}; set HELIX_VQA_CHROME to a Chromium matching stable`);
+}
+/** Path of the executable inside an unpacked CfT zip, relative to the install dir. */
+function executableRel(platform) {
+    switch (platform) {
+        case 'mac-arm64': return 'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing';
+        case 'mac-x64': return 'chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing';
+        case 'linux64': return 'chrome-linux64/chrome';
+        case 'win64': return 'chrome-win64\\chrome.exe';
+    }
+}
+/** Default cache dir for this OS. `HELIX_VQA_CHROME_CACHE` overrides. */
+function defaultCacheDir(env = process.env, platform = process.platform, home = node_os_1.default.homedir()) {
+    if (env.HELIX_VQA_CHROME_CACHE)
+        return env.HELIX_VQA_CHROME_CACHE;
+    if (platform === 'darwin')
+        return node_path_1.default.join(home, 'Library', 'Caches', 'helix', 'vqa-chrome');
+    if (platform === 'win32')
+        return node_path_1.default.join(env.LOCALAPPDATA || node_path_1.default.join(home, 'AppData', 'Local'), 'helix', 'vqa-chrome');
+    return node_path_1.default.join(env.XDG_CACHE_HOME || node_path_1.default.join(home, '.cache'), 'helix', 'vqa-chrome');
+}
+/** The current Stable build for a platform, from the official last-known-good endpoint. Pure over the parsed JSON. */
+function stableFromJson(json, platform) {
+    const stable = json?.channels?.Stable;
+    const version = stable?.version;
+    const url = stable?.downloads?.chrome?.find((d) => d.platform === platform)?.url;
+    if (!version || !/^\d+\.\d+\.\d+\.\d+$/.test(version) || !url)
+        throw new Error(`Chrome for Testing endpoint has no Stable chrome download for ${platform}`);
+    return { version, url };
+}
+async function resolveStable(platform, fetchImpl = fetch) {
+    const res = await fetchImpl(exports.CFT_LAST_KNOWN_GOOD_URL);
+    if (!res.ok)
+        throw new Error(`Chrome for Testing endpoint answered ${res.status}`);
+    return stableFromJson(await res.json(), platform);
+}
+function markerFile(cacheDir, platform) { return node_path_1.default.join(cacheDir, `pinned-${platform}.json`); }
+/** The pin recorded in `cacheDir`, if its executable is still there. `toLocal` maps a recorded path to one this process can stat. */
+function readPin(cacheDir, platform) {
+    let pin;
+    try {
+        pin = JSON.parse(node_fs_1.default.readFileSync(markerFile(cacheDir, platform), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!pin?.version || pin.platform !== platform)
+        return null;
+    const dir = node_path_1.default.join(cacheDir, `${platform}-${pin.version}`);
+    const local = node_path_1.default.join(dir, ...executableRel(platform).split(/[\\/]/));
+    if (!node_fs_1.default.existsSync(local))
+        return null;
+    return { ...pin, dir };
+}
+function unzip(zip, dest) {
+    node_fs_1.default.mkdirSync(dest, { recursive: true });
+    // `unzip` keeps the .app's framework symlinks on macOS; bsdtar (macOS/Windows `tar`) is the fallback.
+    let r = (0, node_child_process_1.spawnSync)('unzip', ['-q', '-o', zip, '-d', dest], { stdio: ['ignore', 'ignore', 'pipe'], encoding: 'utf8' });
+    if (r.status !== 0)
+        r = (0, node_child_process_1.spawnSync)('tar', ['-xf', zip, '-C', dest], { stdio: ['ignore', 'ignore', 'pipe'], encoding: 'utf8' });
+    if (r.status !== 0)
+        throw new Error(`could not unpack ${node_path_1.default.basename(zip)}: ${String(r.stderr ?? r.error ?? '').slice(0, 300)}`);
+}
+/**
+ * Make sure the current-stable Chrome for Testing is installed and pinned; return it. Idempotent and cheap when the
+ * pin is fresh (no network). A pin older than PIN_MAX_AGE_MS (or `refresh`) re-resolves stable; if that fails the
+ * existing pin is kept, so an offline host still renders on the last stable it had.
+ */
+async function ensurePinnedChrome(opts = {}) {
+    const platform = opts.platform ?? cftPlatform();
+    const cacheDir = opts.cacheDir ?? defaultCacheDir();
+    const log = opts.log ?? (() => undefined);
+    const existing = readPin(cacheDir, platform);
+    const fresh = existing && Date.now() - Date.parse(existing.resolvedAt) < exports.PIN_MAX_AGE_MS;
+    if (existing && fresh && !opts.refresh)
+        return existing;
+    let stable;
+    try {
+        stable = await resolveStable(platform, opts.fetchImpl);
+    }
+    catch (e) {
+        if (existing) {
+            log(`could not re-resolve stable (${String(e?.message ?? e)}); keeping ${existing.version}`);
+            return existing;
+        }
+        throw e;
+    }
+    const dir = node_path_1.default.join(cacheDir, `${platform}-${stable.version}`);
+    const localExe = node_path_1.default.join(dir, ...executableRel(platform).split(/[\\/]/));
+    if (!node_fs_1.default.existsSync(localExe)) {
+        node_fs_1.default.mkdirSync(cacheDir, { recursive: true });
+        const tag = node_crypto_1.default.randomBytes(4).toString('hex');
+        const zip = node_path_1.default.join(cacheDir, `.download-${platform}-${stable.version}-${tag}.zip`);
+        const partial = node_path_1.default.join(cacheDir, `.partial-${platform}-${stable.version}-${tag}`);
+        try {
+            log(`downloading Chrome for Testing ${stable.version} (${platform}) from ${stable.url}`);
+            const res = await (opts.fetchImpl ?? fetch)(stable.url);
+            if (!res.ok)
+                throw new Error(`download answered ${res.status}`);
+            node_fs_1.default.writeFileSync(zip, Buffer.from(await res.arrayBuffer()));
+            unzip(zip, partial);
+            if (!node_fs_1.default.existsSync(node_path_1.default.join(partial, ...executableRel(platform).split(/[\\/]/))))
+                throw new Error(`unpacked zip has no ${executableRel(platform)}`);
+            try {
+                node_fs_1.default.renameSync(partial, dir);
+            }
+            catch (e) {
+                // Another process finished the same install first: use theirs.
+                if (!node_fs_1.default.existsSync(localExe))
+                    throw e;
+            }
+        }
+        finally {
+            node_fs_1.default.rmSync(zip, { force: true });
+            node_fs_1.default.rmSync(partial, { recursive: true, force: true });
+        }
+    }
+    const pin = {
+        version: stable.version,
+        platform,
+        executablePath: (opts.toLaunchPath ?? ((p) => p))(localExe),
+        dir,
+        resolvedFrom: exports.CFT_LAST_KNOWN_GOOD_URL,
+        resolvedAt: new Date().toISOString(),
+    };
+    const { dir: _local, ...record } = pin;
+    void _local;
+    const tmp = `${markerFile(cacheDir, platform)}.${node_crypto_1.default.randomBytes(4).toString('hex')}`;
+    node_fs_1.default.writeFileSync(tmp, JSON.stringify(record, null, 2));
+    node_fs_1.default.renameSync(tmp, markerFile(cacheDir, platform));
+    log(`pinned Chrome for Testing ${pin.version} (${platform}) at ${pin.executablePath}`);
+    return pin;
+}
+/**
+ * The executable a local (non-CDP) render launches: an explicit path, else `HELIX_VQA_CHROME`, else the pinned
+ * current-stable Chrome for Testing (installed on first use). Never Playwright's bundled build, never the system Chrome.
+ */
+async function resolveVqaExecutable(opts = {}) {
+    const env = opts.env ?? process.env;
+    if (opts.explicit)
+        return { executablePath: opts.explicit, channel: 'explicit' };
+    if (env.HELIX_VQA_CHROME)
+        return { executablePath: env.HELIX_VQA_CHROME, channel: 'env-override' };
+    const pinned = await ensurePinnedChrome({ log: opts.log });
+    return { executablePath: pinned.executablePath, channel: 'pinned-cft', pinned };
+}
+/**
+ * `node dist/visualQa/pinnedChrome.js [--platform <p>] [--cache <dir>] [--refresh]`: install/refresh and print the pin.
+ * `--windows` (from WSL): the Windows-side pin the hosted worker renders on (`%LOCALAPPDATA%\\helix\\vqa-chrome`).
+ */
+async function main(argv) {
+    if (argv.includes('--windows')) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { findWindowsChrome } = require('./winChrome');
+        const r = await findWindowsChrome({ refresh: argv.includes('--refresh') });
+        console.log(JSON.stringify(r));
+        return;
+    }
+    const arg = (name) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; };
+    const platform = arg('--platform') ?? cftPlatform();
+    const cacheDir = arg('--cache') ?? defaultCacheDir();
+    const winRoot = arg('--windows-path');
+    const pin = await ensurePinnedChrome({
+        platform, cacheDir, refresh: argv.includes('--refresh'), log: (m) => console.error(`[vqa-chrome] ${m}`),
+        // From WSL: `--windows-path 'C:\Users\me\AppData\Local\helix\vqa-chrome'` names the same dir as Windows sees it.
+        toLaunchPath: winRoot ? (p) => `${winRoot.replace(/[\\/]+$/, '')}\\${node_path_1.default.relative(cacheDir, p).split(node_path_1.default.sep).join('\\')}` : undefined,
+    });
+    console.log(JSON.stringify({ version: pin.version, platform: pin.platform, executablePath: pin.executablePath, resolvedAt: pin.resolvedAt }));
+}
+if (require.main === module) {
+    main(process.argv.slice(2)).catch((e) => { console.error(String(e?.stack ?? e)); process.exit(1); });
+}
+//# sourceMappingURL=pinnedChrome.js.map

package/dist/visualQa/pinnedChrome.js.map

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

package/dist/visualQa/resolve.d.ts

@@ -0,0 +1,88 @@
+import { type CandidateRequest } from './candidate';
+import type { VisualQaCategory, VisualQaItemIdentity } from './types';
+export interface ResolvedItem {
+    identity: VisualQaItemIdentity;
+    item: Record<string, unknown>;
+    /** Parsed package root document when it is JSON (vehicle package, add-on descriptor); null for a bare GLB root. */
+    root: Record<string, unknown> | null;
+    rootRole: string | null;
+    /** Immutable root definition/model and Package type named by the resolved manifest. */
+    rootCid?: string | null;
+    packageType?: string | null;
+    /** CID (sha256:<hex>) of the model GLB the runtime draws for this version, when there is one. */
+    modelCid: string | null;
+    /** Vehicles: every model rendition the version's manifest declares (`vehicle.model.web.*` variants), id/role/cid. */
+    modelVariants?: Array<{
+        id: string;
+        role: string;
+        cid: string;
+    }>;
+    /** Hosts (vehicle add-ons) or bases (character add-ons / wearables) declared by the item. */
+    hostIds: string[];
+    /** True for tune-only add-ons that carry no renderable model, and for any Version the backend reports `exempt: 'meshless'`
+     *  (an OG pending-rendition deed such as Parallel City Land). */
+    meshless: boolean;
+    /** Why the backend exempts the item from visual QA, when it does (`meshless`, `non_visual_slot`, `look`); null otherwise.
+     *  A Look (an item pinned to a Build Package) is judged through its parts and Try Now does not serve it. */
+    exempt?: string | null;
+    /** Set when a version the item is NOT pinned to was resolved (`--package-version`): what the item points at today,
+     *  and the vehicle package the version move carries. The identity above describes the candidate. */
+    candidate?: {
+        currentVersion: string | null;
+        currentManifestCid: string | null;
+        vehiclePackage: Record<string, unknown> | null;
+    } | null;
+}
+export declare function categoryFor(item: {
+    itemType?: unknown;
+    hostKind?: unknown;
+    slotType?: unknown;
+    kind?: unknown;
+}): VisualQaCategory;
+export declare const hexOf: (cid: string | null | undefined) => string | null;
+export declare class HttpStatusError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** A sealed Package Version. The public route serves only a PUBLIC Package (`assertCanResolvePackage` refuses even the
+ *  owner of a private one, 403), so on 403/404 with a login the owner/authenticated route is asked instead: a private
+ *  avatar held for visual QA must still be judgeable by its creator (and by an admin or the leased runner). */
+export declare function getPackageVersion<T>(api: string, packageId: string, version: string, token?: string | null, itemId?: string): Promise<T>;
+/** A Package Version's object (a JSON root definition), public first, then the authenticated version-scoped route. */
+export declare function getPackageObject<T>(api: string, packageId: string, version: string, cid: string, token?: string | null): Promise<T>;
+type Manifest = {
+    package?: {
+        id?: string;
+        type?: string;
+    };
+    version?: string;
+    root?: {
+        cid?: string;
+        role?: string;
+        mediaType?: string;
+    };
+    variants?: Array<{
+        id?: string;
+        object?: {
+            cid?: string;
+            role?: string;
+            mediaType?: string;
+        };
+    }>;
+};
+/** A candidate must be a sealed revision of the item's own typed Package, with an exact manifest identity. */
+export declare function validateCandidateVersion(itemType: unknown, packageId: string, version: string, body: {
+    packageId?: string;
+    version?: string;
+    lifecycle?: string;
+    manifestCid?: string;
+    manifest?: Manifest;
+}): void;
+/** Pick the model GLB the runtime draws for this version, by root role. */
+export declare function modelCidFor(rootRole: string | null, rootMedia: string | null, root: Record<string, unknown> | null, manifest: Manifest): string | null;
+/** `token` lets the hosted runner (a bot account with read-only rights) resolve an item that is not public yet.
+ *  `candidate.packageVersion` resolves THAT version of the item's pinned package instead of the pin (a version move
+ *  being judged before the pointer moves); the identity then describes the candidate, and its vehicle checksum and
+ *  version row id stay null until Try Now names them (`trial.candidate`). */
+export declare function resolveItem(apiBase: string, itemId: string, token?: string | null, candidateReq?: CandidateRequest): Promise<ResolvedItem>;
+export {};