@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/assets.js

@@ -0,0 +1,1121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RESOLUTION_KEY = exports.UnavailableCapabilityError = exports.MATERIAL_RENDITION_SELECTIONS = exports.DEFAULT_POLL_INTERVAL_MS = exports.DREAMER_JOB_DEFAULT_TIMEOUT_MS = exports.AUDIO_GENERATION_TIMEOUT_MS = exports.StrandedJobError = exports.VAULT_ASSET_KINDS = void 0;
+exports.materialResolutionOptions = materialResolutionOptions;
+exports.materialDefaultResolutionKey = materialDefaultResolutionKey;
+exports.matchMaterialResolution = matchMaterialResolution;
+exports.describeGateAdvance = describeGateAdvance;
+exports.formatStrandedJob = formatStrandedJob;
+exports.approveDreamerGate = approveDreamerGate;
+exports.reviseDreamerGate = reviseDreamerGate;
+exports.retryDreamerJob = retryDreamerJob;
+exports.generateAndPublishAsset = generateAndPublishAsset;
+exports.generateAndPublishAssetFromReference = generateAndPublishAssetFromReference;
+exports.startDreamerAssetGeneration = startDreamerAssetGeneration;
+exports.startDreamerAssetGenerationFromReference = startDreamerAssetGenerationFromReference;
+exports.getDreamerAssetGenerationJob = getDreamerAssetGenerationJob;
+exports.resumeAndPublishAsset = resumeAndPublishAsset;
+exports.generateStandaloneAsset = generateStandaloneAsset;
+exports.startStandaloneAssetGeneration = startStandaloneAssetGeneration;
+exports.getStandaloneAssetGenerationJob = getStandaloneAssetGenerationJob;
+exports.generateImage = generateImage;
+exports.generateAudio = generateAudio;
+exports.listDreamerVoices = listDreamerVoices;
+exports.searchVaultAssets = searchVaultAssets;
+exports.getVaultAsset = getVaultAsset;
+exports.getVaultAssetVersions = getVaultAssetVersions;
+exports.updateVaultAssetMetadata = updateVaultAssetMetadata;
+exports.getVaultAssetUsage = getVaultAssetUsage;
+exports.extensionFor = extensionFor;
+exports.saveGeneratedAsset = saveGeneratedAsset;
+exports.installVaultAsset = installVaultAsset;
+exports.listMaterials = listMaterials;
+exports.resolveMaterial = resolveMaterial;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const api_1 = require("./api");
+const pins_1 = require("./materials/pins");
+const availability_1 = require("./materials/availability");
+exports.VAULT_ASSET_KINDS = [
+    'prop',
+    'character',
+    'animation',
+    'audio',
+    'texture',
+    'material',
+    'environment',
+    'terrain',
+    'vfx',
+    'decal',
+    'sky',
+    'gaussian_splat',
+    'scene',
+    'interactive_item',
+    'unreal_package',
+];
+/**
+ * A job that is alive but cannot advance without an explicit, money-spending decision. Carries the
+ * job so callers can render the exact recovery command instead of a bare timeout.
+ */
+class StrandedJobError extends Error {
+    job;
+    constructor(job) {
+        super(formatStrandedJob(job));
+        this.job = job;
+        this.name = 'StrandedJobError';
+    }
+}
+exports.StrandedJobError = StrandedJobError;
+exports.AUDIO_GENERATION_TIMEOUT_MS = 30 * 60_000;
+// Default CLIENT-SIDE wait for `driveDreamerAssetJob` (prop/character mesh
+// pipeline: generate/generate-reference/resume) before it gives up polling.
+// This is not a job-failure timeout — the Dreamer job keeps running server-side
+// regardless — it only bounds how long this process blocks. Override per call
+// via `GenerateAssetOptions.timeoutMs`, or per CLI invocation via `--timeout`.
+exports.DREAMER_JOB_DEFAULT_TIMEOUT_MS = 20 * 60_000;
+// Default CLIENT-SIDE poll interval for `driveDreamerAssetJob`. Override via
+// `GenerateAssetOptions.pollIntervalMs`, or per CLI invocation via `--poll-interval`.
+exports.DEFAULT_POLL_INTERVAL_MS = 2_000;
+exports.MATERIAL_RENDITION_SELECTIONS = ['runtime', 'source', 'all'];
+class UnavailableCapabilityError extends Error {
+    capability;
+    code = 'CAPABILITY_UNAVAILABLE';
+    constructor(capability, message) {
+        super(message);
+        this.capability = capability;
+    }
+}
+exports.UnavailableCapabilityError = UnavailableCapabilityError;
+/**
+ * The label a schemaVersion-1 entry's single resolution gets. Such a pack never
+ * says how big its maps are, so naming it "1k" would be a guess presented as a
+ * fact — and a creator asking for "1k" would then be silently served whatever
+ * the pack happens to hold. "default" is the only honest label.
+ */
+exports.DEFAULT_RESOLUTION_KEY = 'default';
+const isMapTable = (value) => !!value &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.values(value).every((entry) => typeof entry === 'string');
+/**
+ * Every resolution a material offers, in catalog-declared order, normalized so
+ * that an old single-resolution pack and a new multi-resolution pack are the
+ * same shape to every caller above this line.
+ */
+function materialResolutionOptions(material) {
+    const declared = material.resolutions;
+    if (declared && typeof declared === 'object' && !Array.isArray(declared)) {
+        const options = Object.entries(declared)
+            .filter(([key, variant]) => key.trim() !== '' && isMapTable(variant?.maps))
+            .map(([key, variant]) => ({
+            key,
+            pixels: typeof variant.pixels === 'number' && Number.isFinite(variant.pixels) ? variant.pixels : null,
+            maps: variant.maps,
+        }));
+        if (options.length)
+            return options;
+    }
+    // schemaVersion 1 (or an entry with no `resolutions`): exactly one resolution,
+    // derived from the top-level maps that every existing client already reads.
+    if (isMapTable(material.maps)) {
+        return [
+            {
+                key: (typeof material.defaultResolution === 'string' && material.defaultResolution.trim()) || exports.DEFAULT_RESOLUTION_KEY,
+                pixels: null,
+                maps: material.maps,
+            },
+        ];
+    }
+    return [];
+}
+const sameMaps = (a, b) => {
+    const left = Object.entries(a).sort(([x], [y]) => x.localeCompare(y));
+    const right = Object.entries(b).sort(([x], [y]) => x.localeCompare(y));
+    return (left.length === right.length &&
+        left.every(([key, value], index) => right[index][0] === key && right[index][1] === value));
+};
+/** The key whose maps the pack mirrors at the top level — the default download. */
+function materialDefaultResolutionKey(material, options = materialResolutionOptions(material)) {
+    if (!options.length)
+        return null;
+    const declared = typeof material.defaultResolution === 'string' ? material.defaultResolution.trim().toLowerCase() : '';
+    if (declared) {
+        const named = options.find((option) => option.key.toLowerCase() === declared);
+        if (named)
+            return named.key;
+    }
+    if (isMapTable(material.maps)) {
+        const mirrored = options.find((option) => sameMaps(option.maps, material.maps));
+        if (mirrored)
+            return mirrored.key;
+    }
+    return options[0].key;
+}
+/**
+ * Match a requested resolution against what a material declares. Exact keys win
+ * (case-insensitively); `1024`/`2048` and `1k`/`2k` are accepted as aliases of
+ * each other so a caller never has to know which spelling a pack chose.
+ * Returns null when nothing matches — the caller MUST then fail loudly.
+ */
+function matchMaterialResolution(options, requested) {
+    const wanted = requested.trim().toLowerCase();
+    if (!wanted)
+        return null;
+    const exact = options.find((option) => option.key.toLowerCase() === wanted);
+    if (exact)
+        return exact;
+    // Numeric spelling ("2048", "2048px") → the variant authored at that edge, or
+    // the conventional "2k" key when the pack declares no pixel counts.
+    const numeric = /^(\d+)(?:px)?$/.exec(wanted);
+    if (numeric) {
+        const pixels = Number(numeric[1]);
+        const byPixels = options.find((option) => option.pixels === pixels);
+        if (byPixels)
+            return byPixels;
+        if (pixels > 0 && pixels % 1024 === 0) {
+            const derived = `${pixels / 1024}k`;
+            const byDerivedKey = options.find((option) => option.key.toLowerCase() === derived);
+            if (byDerivedKey)
+                return byDerivedKey;
+        }
+        return null;
+    }
+    // "k" spelling → the variant authored at that edge, for a pack whose keys are
+    // named something else entirely but which declares pixels.
+    const kilo = /^(\d+(?:\.\d+)?)k$/.exec(wanted);
+    if (kilo) {
+        const pixels = Math.round(Number(kilo[1]) * 1024);
+        const byPixels = options.find((option) => option.pixels === pixels);
+        if (byPixels)
+            return byPixels;
+    }
+    return null;
+}
+const renderResolutionList = (options) => options.length
+    ? options.map((option) => (option.pixels ? `${option.key} (${option.pixels}px)` : option.key)).join(', ')
+    : '(none)';
+const publicResolutions = (options) => options.map(({ key, pixels }) => ({ key, pixels }));
+/** Union of every resolution key in the pack, in first-seen order. */
+function packResolutionOptions(materials) {
+    const seen = new Map();
+    for (const material of materials) {
+        for (const option of materialResolutionOptions(material)) {
+            const id = option.key.toLowerCase();
+            const prior = seen.get(id);
+            if (!prior)
+                seen.set(id, { key: option.key, pixels: option.pixels });
+            else if (prior.pixels === null && option.pixels !== null)
+                prior.pixels = option.pixels;
+        }
+    }
+    return [...seen.values()];
+}
+function absoluteMaps(maps, assetBaseUrl) {
+    return Object.fromEntries(Object.entries(maps).map(([key, value]) => [
+        key,
+        /^https?:\/\//i.test(value) ? value : `${assetBaseUrl}/${value.replace(/^\/+/, '')}`,
+    ]));
+}
+/**
+ * Attach the resolution report (and, when asked, the resolved absolute map
+ * URLs) to one catalog entry. Throws when the caller asked for a resolution
+ * this material does not carry — never falls back to a different one.
+ */
+function describeMaterialResolution(material, assetBaseUrl, requested) {
+    const options = materialResolutionOptions(material);
+    const available = publicResolutions(options);
+    const defaultKey = materialDefaultResolutionKey(material, options);
+    if (!options.length) {
+        // Procedural (glass / water): no maps exist, so a resolution is not an
+        // error — it simply does not apply, and we say so out loud.
+        return {
+            ...material,
+            resolution: {
+                requested,
+                resolved: null,
+                pixels: null,
+                default: null,
+                available,
+                applicable: false,
+                ...(requested
+                    ? {
+                        note: `"${material.id}" is a procedural ${material.kind} material with no texture maps — resolution "${requested}" does not apply and was ignored.`,
+                    }
+                    : {}),
+            },
+        };
+    }
+    const selected = requested
+        ? matchMaterialResolution(options, requested)
+        : options.find((option) => option.key === defaultKey) ?? options[0];
+    if (!selected) {
+        throw new Error(`Material "${material.id}" does not offer resolution "${requested}" — available: ${renderResolutionList(available)}`);
+    }
+    return {
+        ...material,
+        resolvedMaps: absoluteMaps(selected.maps, assetBaseUrl),
+        resolution: {
+            requested,
+            resolved: selected.key,
+            pixels: selected.pixels,
+            default: defaultKey,
+            available,
+            applicable: true,
+        },
+    };
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isTerminalFailure(job) {
+    return ['failed', 'blocked_insufficient_spark', 'cancelled'].includes(job.status);
+}
+function normalizeDreamerAssetJob(job) {
+    const vaultAssetId = job.vaultAssetId ??
+        (typeof job.verification?.vaultAssetId === 'string'
+            ? job.verification.vaultAssetId
+            : null);
+    const vaultAutoPublish = job.vaultAutoPublish ??
+        (job.verification?.vaultAutoPublish === 'disabled'
+            ? 'disabled'
+            : vaultAssetId
+                ? 'published'
+                : undefined);
+    // `awaitingApproval` has been seen as a bare gate string as well as { gate }. Normalize to the
+    // object so callers never branch on the wire shape.
+    const awaiting = job.awaitingApproval;
+    const awaitingApproval = typeof awaiting === 'string'
+        ? { gate: awaiting }
+        : (awaiting ?? null);
+    // One job id under both keys — see the `jobId` field note.
+    const id = job.id ?? job.jobId;
+    return {
+        ...job,
+        ...(id ? { id, jobId: id } : {}),
+        awaitingApproval,
+        ...(vaultAssetId ? { vaultAssetId } : {}),
+        ...(vaultAutoPublish ? { vaultAutoPublish } : {}),
+    };
+}
+/**
+ * The exact commands that advance a job sitting at a gate.
+ *
+ * A gate used to be a dead end in the CLI: the server told you to "Revise it", `revise` existed in
+ * no command, and `resume` re-approved a gate the server had already refused — so the driver spun
+ * silently until a 20-minute timeout with the LIX already spent. Any awaiting-approval state now
+ * names the command that moves it.
+ *
+ * The list is SERVER-AUTHORED. `recovery.actions[]` wins when present; `awaitingApproval.options`
+ * is the older fallback. Neither is second-guessed, and an action this CLI has no command for is
+ * reported rather than silently dropped — a recovery menu that quietly omits the only verb that
+ * works is how a job looks dead when it isn't.
+ *
+ * Deliberately NOT a hardcoded verb list. `abandon` was specified, built, and then withdrawn from
+ * the platform before it ever deployed; because this reads the server's array, it simply never
+ * appears, and no client change was needed to stop offering it.
+ */
+/**
+ * Server recovery-action name → the CLI verb that performs it, where the two differ.
+ *
+ * The action array stays server-authored (see above); this only translates NAMES. A parked
+ * character job offers `{ action: "publish", endpoint: ".../publish" }`, and a cold run went
+ * looking for `helix assets publish`, which does not exist — the verb is `helix assets resume`,
+ * which drives the preview gate through to the publish call. The generic fallback printed
+ * `"publish" — no command in this CLI version; upgrade…`, so the CLI told a creator to reinstall
+ * in order to reach a command it already shipped.
+ *
+ * Add a row here ONLY when the CLI genuinely implements the action under another name. An action
+ * we do not implement must still reach the fallback.
+ */
+const SERVER_ACTION_TO_CLI_VERB = {
+    publish: 'resume',
+};
+/** The published package, for upgrade hints. `@helix3/…` is the environment scope, not the name. */
+const CLI_PACKAGE_NAME = '@hypersoniclabs/helix-cli';
+function describeGateAdvance(job) {
+    const fromRecovery = job.recovery?.actions?.map((a) => a.action);
+    const options = fromRecovery?.length
+        ? fromRecovery
+        : job.awaitingApproval?.gate
+            ? (job.awaitingApproval.options ?? ['approve', 'revise'])
+            : [];
+    if (!options.length)
+        return [];
+    const gate = job.awaitingApproval?.gate;
+    const id = job.jobId ?? job.id;
+    const costs = new Map((job.recovery?.actions ?? []).map((a) => [a.action, a.costsLix]));
+    // A verb that spends must SAY it spends. Default to warning when the server is silent: an
+    // unmarked spend read as free is the failure that actually costs someone money.
+    const fee = (action, fallback) => (costs.get(action) ?? fallback) ? '   (spends LIX)' : '';
+    const lines = [];
+    for (const action of options) {
+        if (action === 'approve') {
+            lines.push(`helix assets approve ${id}${gate ? ` --gate ${gate}` : ''}${fee(action, false)}`);
+        }
+        else if (action === 'revise') {
+            lines.push(`helix assets revise ${id}${gate ? ` --gate ${gate}` : ''} --prompt "<what to change>"${fee(action, true)}`);
+        }
+        else if (action === 'retry') {
+            lines.push(`helix assets retry ${id}${fee(action, true)}`);
+        }
+        else if (SERVER_ACTION_TO_CLI_VERB[action]) {
+            lines.push(`helix assets ${SERVER_ACTION_TO_CLI_VERB[action]} ${id}${fee(action, false)}`);
+        }
+        else {
+            // The server offers a recovery verb this CLI version does not implement. Say so with the
+            // endpoint rather than hiding it — an out-of-date CLI must not make a job look unrecoverable.
+            const endpoint = job.recovery?.actions?.find((a) => a.action === action)?.endpoint;
+            lines.push(`"${action}" — no command in this CLI version; upgrade with \`npm i -g ${CLI_PACKAGE_NAME}@latest\`` +
+                (endpoint ? ` (API: ${endpoint})` : ''));
+        }
+    }
+    return lines;
+}
+/** Rendered when a job cannot advance on its own — never auto-executed. */
+function formatStrandedJob(job) {
+    const advances = describeGateAdvance(job);
+    const spent = job.lixSpentTotal === undefined ? null : Number(job.lixSpentTotal);
+    const gate = job.awaitingApproval?.gate;
+    const lines = [
+        `Job ${job.jobId ?? job.id} is waiting at the "${gate ?? job.currentStage ?? 'unknown'}" gate and will not advance on its own.`,
+    ];
+    if (spent)
+        lines.push(`  ${spent} LIX already spent on this job.`);
+    if (job.openHoldLix) {
+        // There is no verb that releases a hold on demand. The economy's own 24h `hold_until` sweep is
+        // the only thing that returns one, so say that rather than implying an action exists.
+        lines.push(`  ${job.openHoldLix} LIX still escrowed by it — released automatically by the 24h hold sweep.`, '  No command releases a hold early.');
+    }
+    if (advances.length) {
+        lines.push('', '  Advance it with ONE of:');
+        for (const advance of advances)
+            lines.push(`    ${advance}`);
+    }
+    else {
+        lines.push('', '  The server offers no recovery action for this job.');
+    }
+    const options = job.recovery?.actions?.map((a) => a.action) ?? job.awaitingApproval?.options;
+    if (options?.length === 1 && options[0] === 'revise') {
+        lines.push('', '  The server rejected its own output at this gate, so it cannot be approved — only revised.');
+    }
+    if (advances.length) {
+        lines.push('', '  Nothing here retries automatically.');
+    }
+    return lines.join('\n');
+}
+/** Approve a gate. Explicit, caller-initiated — never called on a gate already approved this run. */
+function approveDreamerGate(creds, jobId, gate) {
+    return api_1.HelixApi.forCredentials(creds)
+        .request('POST', `/api/v1/dreamer/jobs/${encodeURIComponent(jobId)}/approve`, { gate })
+        .then(normalizeDreamerAssetJob);
+}
+/**
+ * Revise a gated stage with new guidance. CHARGES a fresh regeneration — it is a spend, not a free
+ * retry, and it is the only advance path when the server refused its own concept.
+ */
+function reviseDreamerGate(creds, jobId, gate, prompt) {
+    return api_1.HelixApi.forCredentials(creds)
+        .request('POST', `/api/v1/dreamer/jobs/${encodeURIComponent(jobId)}/revise`, { gate, ...(prompt ? { prompt } : {}) })
+        .then(normalizeDreamerAssetJob);
+}
+/** Retry a FAILED job. Distinct from revise: no new guidance, resumes from the mesh phase. */
+function retryDreamerJob(creds, jobId) {
+    return api_1.HelixApi.forCredentials(creds)
+        .request('POST', `/api/v1/dreamer/jobs/${encodeURIComponent(jobId)}/retry`, {})
+        .then(normalizeDreamerAssetJob);
+}
+// There is deliberately NO `abandonDreamerJob` here.
+//
+// `POST /dreamer/jobs/:jobId/abandon` was specified and built, then withdrawn before it deployed:
+// releasing the escrow meant a settle(0) → RefundEscrow, i.e. real money movement, which is outside
+// what this lane may ship. No platform verb releases a hold on demand today; the economy's own 24h
+// `hold_until` sweep is the only thing that returns one.
+//
+// Do not re-add a client call for it on the strength of a doc or a plan. If it ever ships, it will
+// appear in the job's `recovery.actions[]` and `describeGateAdvance` will surface it on its own —
+// that array is why this removal needed no other client change.
+async function generateAndPublishAsset(creds, input, options = {}) {
+    const api = api_1.HelixApi.forCredentials(creds);
+    const job = await startDreamerAssetGeneration(creds, withVisibility(input, options));
+    return driveDreamerAssetJob(api, job, options);
+}
+async function generateAndPublishAssetFromReference(creds, input, options = {}) {
+    const api = api_1.HelixApi.forCredentials(creds);
+    const job = await startDreamerAssetGenerationFromReference(creds, withVisibility(input, options));
+    return driveDreamerAssetJob(api, job, options);
+}
+/** The publish visibility also rides on the generation request, so the job records it. */
+function withVisibility(input, options) {
+    const visibility = input.visibility ?? options.visibility;
+    return visibility ? { ...input, visibility } : input;
+}
+async function startDreamerAssetGeneration(creds, input) {
+    const api = api_1.HelixApi.forCredentials(creds);
+    return normalizeDreamerAssetJob(await api.request('POST', '/api/v1/dreamer/generate', {
+        ...input,
+        kind: input.kind === 'prop' ? 'home_item' : 'avatar',
+    }));
+}
+async function startDreamerAssetGenerationFromReference(creds, input) {
+    const referenceSheet = await (0, promises_1.readFile)(input.referenceSheetPath);
+    if (referenceSheet.byteLength === 0 || referenceSheet.byteLength > 8 * 1024 * 1024) {
+        throw new Error('Reference sheet must be a non-empty PNG, JPEG, or WebP no larger than 8 MiB.');
+    }
+    const extension = (0, node_path_1.extname)(input.referenceSheetPath).toLowerCase();
+    const contentType = extension === '.png'
+        ? 'image/png'
+        : extension === '.jpg' || extension === '.jpeg'
+            ? 'image/jpeg'
+            : extension === '.webp'
+                ? 'image/webp'
+                : null;
+    if (!contentType) {
+        throw new Error('Reference sheet must use a .png, .jpg, .jpeg, or .webp extension.');
+    }
+    const form = new FormData();
+    form.append('prompt', input.prompt);
+    if (input.title)
+        form.append('title', input.title);
+    if (input.additionalPrompt)
+        form.append('additionalPrompt', input.additionalPrompt);
+    if (input.targetPolycount !== undefined) {
+        form.append('targetPolycount', String(input.targetPolycount));
+    }
+    if (input.visibility)
+        form.append('visibility', input.visibility);
+    form.append('referenceSheet', new Blob([new Uint8Array(referenceSheet)], { type: contentType }), (0, node_path_1.basename)(input.referenceSheetPath));
+    return normalizeDreamerAssetJob(await api_1.HelixApi.forCredentials(creds).postMultipart('/api/v1/dreamer/generate-from-reference', form));
+}
+function getDreamerAssetGenerationJob(creds, jobId) {
+    return api_1.HelixApi.forCredentials(creds)
+        .request('GET', `/api/v1/dreamer/jobs/${encodeURIComponent(jobId)}`)
+        .then(normalizeDreamerAssetJob);
+}
+async function resumeAndPublishAsset(creds, jobId, options = {}) {
+    const api = api_1.HelixApi.forCredentials(creds);
+    const job = await getDreamerAssetGenerationJob(creds, jobId);
+    return driveDreamerAssetJob(api, job, options);
+}
+async function driveDreamerAssetJob(api, initialJob, options) {
+    const pollIntervalMs = options.pollIntervalMs ?? exports.DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? exports.DREAMER_JOB_DEFAULT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    let job = initialJob;
+    const approved = new Set();
+    while (Date.now() < deadline) {
+        options.onProgress?.(job);
+        if (isTerminalFailure(job)) {
+            throw new Error(`Dreamer asset generation ${job.status}: ${job.error ?? 'no details'}`);
+        }
+        if (job.publishedItemId)
+            return job;
+        const gate = job.awaitingApproval?.gate;
+        if (gate) {
+            const options = job.awaitingApproval?.options;
+            // A gate the server says can only be REVISED is not approvable — revising charges a fresh
+            // regeneration, so it is the caller's decision, never the driver's. Stop here and say what
+            // advances it. Previously the driver fell through and spun until a 20-minute timeout.
+            if (options && !options.includes('approve')) {
+                throw new StrandedJobError(job);
+            }
+            if (!approved.has(gate)) {
+                job = normalizeDreamerAssetJob(await api.request('POST', `/api/v1/dreamer/jobs/${encodeURIComponent(job.id)}/approve`, { gate }));
+                approved.add(gate);
+                continue;
+            }
+            // Already approved this gate once in this run and the server still reports it awaiting:
+            // approving again would be a no-op at best. Spinning to the timeout hides a stranded job
+            // behind "still working" — surface it now, with the verb that moves it.
+            throw new StrandedJobError(job);
+        }
+        if (!job.awaitingApproval &&
+            (job.status === 'preview_ready' || job.currentStage === 'publish')) {
+            const published = await api.request('POST', `/api/v1/dreamer/jobs/${encodeURIComponent(job.id)}/publish`, 
+            // No client-side default: when the caller did not choose, the backend falls back to the
+            // visibility recorded at generation, then public. Defaulting to 'public' here is how a
+            // `--visibility private` generation resumed without the flag would have gone public.
+            options.visibility ? { visibility: options.visibility } : {});
+            // The publish endpoint returns the verified item and job together. Older
+            // deployments returned the job directly, so accept both shapes without
+            // ever replacing the active job with the response wrapper itself.
+            job = normalizeDreamerAssetJob('job' in published ? published.job : published);
+            if (job.publishedItemId)
+                return job;
+        }
+        await sleep(pollIntervalMs);
+        job = normalizeDreamerAssetJob(await api.request('GET', `/api/v1/dreamer/jobs/${encodeURIComponent(job.id)}`));
+    }
+    // A timeout at a gate is a stranded job, not a slow one — say what advances it.
+    if (job.awaitingApproval?.gate)
+        throw new StrandedJobError(job);
+    throw new Error(`Gave up waiting for Dreamer asset generation job ${job.id} after ${timeoutMs}ms ` +
+        `(still ${job.status}:${job.currentStage ?? 'unknown'}). ` +
+        `This is a CLIENT-SIDE wait giving up — the job itself is not necessarily dead or ` +
+        `failed and may still complete server-side. Check or continue it with:\n` +
+        `  helix assets resume ${job.id}\n` +
+        `To wait longer next time, pass --timeout <ms> (and optionally --poll-interval <ms>) ` +
+        `to generate/generate-reference/resume.`);
+}
+async function generateStandaloneAsset(creds, input, options = {}) {
+    const pollIntervalMs = options.pollIntervalMs ?? 2_000;
+    const deadline = Date.now() + (options.timeoutMs ?? 10 * 60_000);
+    const accepted = await startStandaloneAssetGeneration(creds, input);
+    while (Date.now() < deadline) {
+        const job = await getStandaloneAssetGenerationJob(creds, accepted.jobId);
+        options.onProgress?.(job);
+        if (job.status === 'succeeded')
+            return job;
+        if (job.status === 'failed') {
+            throw new Error(`Dreamer ${input.kind} generation failed: ${job.error ?? 'no details'}`);
+        }
+        await sleep(pollIntervalMs);
+    }
+    throw new Error(`Dreamer ${input.kind} generation job ${accepted.jobId} timed out after ${options.timeoutMs ?? 10 * 60_000}ms`);
+}
+async function startStandaloneAssetGeneration(creds, input) {
+    if (input.kind === 'animation') {
+        throw new UnavailableCapabilityError('animation_generation', 'Animation generation is not available yet. Use a published Vault animation or upload a skeleton-gated clip.');
+    }
+    const accepted = await api_1.HelixApi.forCredentials(creds).request('POST', '/api/v1/dreamer/assets/generate', input);
+    // `start character` returned {id} while `start material` returned {jobId} for the same command
+    // shape. Always emit both so neither reader breaks.
+    const id = accepted.jobId ?? accepted.id ?? '';
+    return { ...accepted, id, jobId: id, status: accepted.status };
+}
+function normalizeStandaloneAsset(job) {
+    const id = job.jobId ?? job.id;
+    return {
+        ...job,
+        ...(id ? { id, jobId: id } : {}),
+        // `units` IS LIX (the backend derives it from lixSpentTotal); surface the canonical name so a
+        // caller never has to know which route produced the receipt.
+        ...(job.lixSpentTotal === undefined && job.units !== undefined
+            ? { lixSpentTotal: job.units }
+            : {}),
+    };
+}
+function getStandaloneAssetGenerationJob(creds, jobId) {
+    return api_1.HelixApi.forCredentials(creds)
+        .request('GET', `/api/v1/dreamer/assets/jobs/${encodeURIComponent(jobId)}`)
+        .then(normalizeStandaloneAsset);
+}
+function generateImage(creds, input, options = {}) {
+    return generateStandaloneAsset(creds, { kind: 'image', ...input }, options);
+}
+/**
+ * Generate a sound effect, music track, or spoken line via the ElevenLabs-backed
+ * Dreamer audio route (`kind: 'audio'`) — one shared contract for all three modes.
+ * Polls to a terminal state and returns the same standalone-job shape as
+ * `generateImage`/`generateStandaloneAsset` (asset url/contentType/sizeBytes,
+ * `units` Spark charged, `providerCostUsd` measured vendor cost, `vaultAssetId`).
+ */
+function generateAudio(creds, input, options = {}) {
+    return generateStandaloneAsset(creds, { kind: 'audio', ...input }, { timeoutMs: exports.AUDIO_GENERATION_TIMEOUT_MS, ...options });
+}
+/**
+ * List/search the HELIX-safe text-to-speech voice catalog. The backend keeps
+ * vendor credentials and voice administration private; callers receive only
+ * the stable selection projection used by website, CLI, SDK, and MCP clients.
+ */
+function listDreamerVoices(creds, query = {}) {
+    const params = new URLSearchParams();
+    if (query.search)
+        params.set('search', query.search);
+    if (query.pageSize !== undefined)
+        params.set('pageSize', String(query.pageSize));
+    if (query.pageToken)
+        params.set('pageToken', query.pageToken);
+    if (query.category)
+        params.set('category', query.category);
+    const suffix = params.size ? `?${params}` : '';
+    return api_1.HelixApi.forCredentials(creds).request('GET', `/api/v1/dreamer/voices${suffix}`);
+}
+async function searchVaultAssets(apiUrl, query = {}, creds) {
+    const api = creds ? api_1.HelixApi.forCredentials(creds) : new api_1.HelixApi(apiUrl);
+    const params = new URLSearchParams();
+    if (query.q)
+        params.set('q', query.q);
+    for (const kind of query.kind ?? [])
+        params.append('kind', kind);
+    for (const key of [
+        'match',
+        'subtype',
+        'scope',
+        'format',
+        'performanceTier',
+        'rank',
+        'skeleton',
+        'engine',
+        'license',
+        'source',
+        'origin',
+        'creatorId',
+    ]) {
+        if (query[key])
+            params.set(key, String(query[key]));
+    }
+    // Explicit undefined check: `official: false` is a real filter (community assets), not an absent one.
+    if (query.official !== undefined)
+        params.set('official', String(query.official));
+    if (query.page)
+        params.set('page', String(query.page));
+    if (query.limit)
+        params.set('limit', String(query.limit));
+    const suffix = params.size ? `?${params}` : '';
+    return api.request('GET', `/api/v1/vault/assets${suffix}`);
+}
+function getVaultAsset(apiUrl, assetId, creds) {
+    const api = creds ? api_1.HelixApi.forCredentials(creds) : new api_1.HelixApi(apiUrl);
+    return api.request('GET', `/api/v1/vault/assets/${encodeURIComponent(assetId)}`);
+}
+function getVaultAssetVersions(apiUrl, assetId, creds) {
+    const api = creds ? api_1.HelixApi.forCredentials(creds) : new api_1.HelixApi(apiUrl);
+    return api.request('GET', `/api/v1/vault/assets/${encodeURIComponent(assetId)}/versions`);
+}
+function updateVaultAssetMetadata(creds, assetId, update) {
+    return api_1.HelixApi.forCredentials(creds).request('PATCH', `/api/v1/vault/assets/${encodeURIComponent(assetId)}`, update);
+}
+async function getVaultAssetUsage(apiUrl, assetId, creds) {
+    const detail = await getVaultAsset(apiUrl, assetId, creds);
+    return {
+        assetId: detail.assetId,
+        worldUsageCount: typeof detail.worldUsageCount === 'number' ? detail.worldUsageCount : 0,
+        usageCount: typeof detail.usageCount === 'number' ? detail.usageCount : 0,
+        lastUsedAt: typeof detail.lastUsedAt === 'string' ? detail.lastUsedAt : null,
+        usedInWorlds: detail.usedInWorlds ?? [],
+    };
+}
+function extensionFor(url, mimeType) {
+    const byMime = {
+        'model/gltf-binary': '.glb',
+        'model/gltf+json': '.gltf',
+        'image/png': '.png',
+        'image/jpeg': '.jpg',
+        'image/webp': '.webp',
+        'audio/mpeg': '.mp3',
+        'audio/ogg': '.ogg',
+        'application/json': '.json',
+        'application/vnd.helix.material+json': '.helix-material.json',
+        'application/vnd.helix.scene+json': '.helix-scene.json',
+        'application/vnd.helix.terrain+json': '.helix-terrain.json',
+        'application/vnd.helix.vfx+json': '.helix-vfx.json',
+        'application/vnd.helix.decal+json': '.helix-decal.json',
+        'image/ktx2': '.ktx2',
+        'image/vnd.radiance': '.hdr',
+        'image/x-exr': '.exr',
+        'model/vnd.gaussian-splat.spz': '.spz',
+        'application/x-spz': '.spz',
+    };
+    const semanticExtension = byMime[mimeType ?? ''];
+    if (semanticExtension?.includes('.helix-'))
+        return semanticExtension;
+    const fromUrl = (0, node_path_1.extname)(new URL(url).pathname).toLowerCase();
+    if (/^\.[a-z0-9]{2,5}$/.test(fromUrl))
+        return fromUrl;
+    return semanticExtension ?? '.bin';
+}
+function safeName(value, fallback) {
+    return (value
+        .replace(/[^a-z0-9_.-]+/gi, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase() || fallback);
+}
+const VAULT_ASSET_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function canonicalVaultAssetId(assetId) {
+    const canonical = assetId.trim().toLowerCase();
+    if (!VAULT_ASSET_ID_PATTERN.test(canonical)) {
+        throw new Error(`Vault asset id must be a UUID, got "${assetId}"`);
+    }
+    return canonical;
+}
+function resolveInside(root, ...parts) {
+    const target = (0, node_path_1.resolve)(root, ...parts);
+    const relativeTarget = (0, node_path_1.relative)(root, target);
+    if (!relativeTarget || relativeTarget.startsWith('..') || (0, node_path_1.isAbsolute)(relativeTarget)) {
+        throw new Error(`Refusing Vault install path outside ${root}`);
+    }
+    return target;
+}
+function materialRelatedFilename(descriptorBytes, related) {
+    let descriptor;
+    try {
+        descriptor = JSON.parse(descriptorBytes.toString('utf8'));
+    }
+    catch {
+        throw new Error('Vault material descriptor is not valid JSON');
+    }
+    const runtimePrefix = 'runtime.ktx2.';
+    const sourcePrefix = 'source.';
+    const family = related.role.startsWith(runtimePrefix)
+        ? 'runtime'
+        : related.role.startsWith(sourcePrefix)
+            ? 'source'
+            : null;
+    if (!family) {
+        throw new Error(`Vault material related artifact "${related.role}" has no known rendition family`);
+    }
+    const semantic = related.role.slice(family === 'runtime' ? runtimePrefix.length : sourcePrefix.length);
+    const normalizedSemantic = semantic.replace(/[^a-z0-9]/gi, '').toLowerCase();
+    const map = Object.entries(descriptor.maps ?? {}).find(([key, value]) => key.replace(/[^a-z0-9]/gi, '').toLowerCase() === normalizedSemantic ||
+        value.semantic?.replace(/[^a-z0-9]/gi, '').toLowerCase() === normalizedSemantic)?.[1];
+    if (!map) {
+        throw new Error(`Vault material descriptor has no map for related artifact "${related.role}"`);
+    }
+    const candidates = family === 'source'
+        ? [map.portableFallback, map, ...(map.renditions ?? [])]
+        : [map, ...(map.renditions ?? [])];
+    const candidate = candidates.find((entry) => entry?.checksumSha256?.toLowerCase() === related.checksumSha256.toLowerCase() &&
+        typeof entry.uri === 'string');
+    if (!candidate?.uri) {
+        throw new Error(`Vault material descriptor checksum does not bind related artifact "${related.role}"`);
+    }
+    let filename;
+    try {
+        filename = decodeURIComponent((0, node_path_1.basename)(new URL(candidate.uri).pathname));
+    }
+    catch {
+        throw new Error(`Vault material descriptor has an invalid URI for "${related.role}"`);
+    }
+    if (!/^[a-z0-9][a-z0-9._-]*$/i.test(filename) ||
+        filename === '.' ||
+        filename === '..' ||
+        (0, node_path_1.extname)(filename).toLowerCase() !== extensionFor(related.url ?? candidate.uri, related.mimeType)) {
+        throw new Error(`Vault material descriptor has an unsafe filename for "${related.role}"`);
+    }
+    return filename;
+}
+/**
+ * Download a succeeded standalone-generation artifact (e.g. `generateAudio`'s
+ * `asset`) to a local path. `asset.url` is normally an absolute CDN url; a
+ * bare/relative path is resolved against `apiUrl` so a backend-relative URL
+ * still works. Verifies the downloaded size against `asset.sizeBytes` when
+ * the server reported one (`> 0`) — a cheap corruption check, no checksum is
+ * available on this route (unlike the Vault install path).
+ */
+async function saveGeneratedAsset(asset, outputPath, opts = {}) {
+    const resolvedUrl = /^https?:\/\//i.test(asset.url)
+        ? asset.url
+        : `${(opts.apiUrl ?? '').replace(/\/+$/, '')}/${asset.url.replace(/^\/+/, '')}`;
+    const response = await fetch(resolvedUrl);
+    if (!response.ok) {
+        throw new Error(`Asset download failed (${response.status}): ${resolvedUrl}`);
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (asset.sizeBytes > 0 && bytes.length !== asset.sizeBytes) {
+        throw new Error(`Asset size mismatch: expected ${asset.sizeBytes} bytes, received ${bytes.length}`);
+    }
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(outputPath), { recursive: true });
+    await (0, promises_1.writeFile)(outputPath, bytes);
+    return { bytes: bytes.length };
+}
+async function downloadAndVerify(input) {
+    if (!/^[a-f0-9]{64}$/i.test(input.expectedChecksumSha256)) {
+        throw new Error(`${input.label} has no valid expected SHA-256 checksum`);
+    }
+    if (!Number.isSafeInteger(input.expectedSizeBytes) || input.expectedSizeBytes < 1) {
+        throw new Error(`${input.label} has no valid expected byte size`);
+    }
+    const response = await fetch(input.url, {
+        headers: input.token ? { authorization: `Bearer ${input.token}` } : {},
+    });
+    if (!response.ok) {
+        throw new Error(`${input.label} download failed (${response.status})`);
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const checksumSha256 = (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+    if (checksumSha256.toLowerCase() !== input.expectedChecksumSha256.toLowerCase()) {
+        throw new Error(`${input.label} checksum mismatch: expected ${input.expectedChecksumSha256}, received ${checksumSha256}`);
+    }
+    if (bytes.length !== input.expectedSizeBytes) {
+        throw new Error(`${input.label} size mismatch: expected ${input.expectedSizeBytes} bytes, received ${bytes.length}`);
+    }
+    return { bytes, checksumSha256 };
+}
+async function installVaultAsset(worldDir, apiUrl, assetId, creds, pin, materialRenditions = 'runtime') {
+    const canonicalAssetId = canonicalVaultAssetId(assetId);
+    if (!exports.MATERIAL_RENDITION_SELECTIONS.includes(materialRenditions)) {
+        throw new Error(`Material rendition selection must be one of: ${exports.MATERIAL_RENDITION_SELECTIONS.join(', ')}`);
+    }
+    if (pin &&
+        (!Number.isSafeInteger(pin.version) ||
+            pin.version < 1 ||
+            !/^[a-f0-9]{64}$/i.test(pin.checksumSha256) ||
+            !Number.isSafeInteger(pin.sizeBytes) ||
+            pin.sizeBytes < 1)) {
+        throw new Error(`Vault asset ${assetId} install pin is invalid`);
+    }
+    const [detail, history] = await Promise.all([
+        getVaultAsset(apiUrl, canonicalAssetId, creds),
+        getVaultAssetVersions(apiUrl, canonicalAssetId, creds),
+    ]);
+    const requestedVersion = pin?.version ?? detail.artifact?.version;
+    if (!Number.isSafeInteger(requestedVersion) || (requestedVersion ?? 0) < 1) {
+        throw new Error(`Vault asset ${assetId} has no valid immutable version`);
+    }
+    const selected = history.items.find((entry) => entry.version === requestedVersion);
+    if (!selected) {
+        throw new Error(`Vault asset ${assetId} version ${requestedVersion} is unavailable`);
+    }
+    if (!selected.checksumSha256 ||
+        !/^[a-f0-9]{64}$/i.test(selected.checksumSha256) ||
+        !Number.isSafeInteger(selected.sizeBytes) ||
+        selected.sizeBytes < 1 ||
+        !selected.url ||
+        !selected.mimeType) {
+        throw new Error(`Vault asset ${assetId} version ${requestedVersion} lacks checksum-protected artifact metadata`);
+    }
+    if (pin &&
+        (selected.checksumSha256.toLowerCase() !== pin.checksumSha256.toLowerCase() ||
+            selected.sizeBytes !== pin.sizeBytes)) {
+        throw new Error(`Vault asset ${assetId} version ${requestedVersion} does not match the requested checksum and size pin`);
+    }
+    if (detail.artifact.version === requestedVersion &&
+        (!detail.artifact.checksumSha256 ||
+            detail.artifact.checksumSha256.toLowerCase() !==
+                selected.checksumSha256.toLowerCase() ||
+            detail.artifact.sizeBytes !== selected.sizeBytes)) {
+        throw new Error(`Vault asset ${assetId} detail/version artifact metadata is inconsistent`);
+    }
+    const artifactUrl = selected.url;
+    if (!artifactUrl)
+        throw new Error(`Vault asset ${assetId} has no downloadable artifact`);
+    const version = selected.version;
+    const downloadUrl = `${apiUrl.replace(/\/+$/, '')}/api/v1/vault/assets/${encodeURIComponent(canonicalAssetId)}/download${version ? `?version=${version}` : ''}`;
+    const { bytes, checksumSha256 } = await downloadAndVerify({
+        url: downloadUrl,
+        token: creds?.token,
+        expectedChecksumSha256: selected.checksumSha256,
+        expectedSizeBytes: selected.sizeBytes,
+        label: `Vault asset ${canonicalAssetId}`,
+    });
+    const extension = extensionFor(artifactUrl, selected.mimeType);
+    const safeSlug = safeName(detail.slug || (0, node_path_1.basename)(new URL(artifactUrl).pathname, extension), 'asset');
+    const allRelatedArtifacts = detail.artifact.version === selected.version
+        ? detail.artifact.relatedArtifacts ?? []
+        : [];
+    const relatedArtifacts = detail.kind !== 'material' || materialRenditions === 'all'
+        ? allRelatedArtifacts
+        : allRelatedArtifacts.filter((related) => materialRenditions === 'runtime'
+            ? related.role.startsWith('runtime.ktx2.') && related.mimeType === 'image/ktx2'
+            : related.role.startsWith('source.') && related.mimeType === 'image/png');
+    if (detail.kind === 'material' &&
+        materialRenditions !== 'all' &&
+        relatedArtifacts.length === 0 &&
+        allRelatedArtifacts.length > 0) {
+        throw new Error(`Vault material ${assetId} has no ${materialRenditions} rendition family`);
+    }
+    const relatedInstallPlan = relatedArtifacts.map((related) => {
+        if (!related.url) {
+            throw new Error(`Vault asset ${canonicalAssetId} related artifact "${related.role}" is unavailable`);
+        }
+        const filename = detail.kind === 'material'
+            ? materialRelatedFilename(bytes, related)
+            : `${safeName(related.role, 'related')}${extensionFor(related.url, related.mimeType)}`;
+        return { related, filename };
+    });
+    if (new Set(relatedInstallPlan.map((entry) => entry.filename)).size !== relatedInstallPlan.length) {
+        throw new Error(`Vault asset ${canonicalAssetId} related artifacts resolve to duplicate filenames`);
+    }
+    const vaultRoot = (0, node_path_1.resolve)(worldDir, 'public', 'assets', 'vault');
+    const assetDir = resolveInside(vaultRoot, canonicalAssetId);
+    const relativePath = ['public', 'assets', 'vault', canonicalAssetId, `${safeSlug}${extension}`].join('/');
+    const outputPath = resolveInside(assetDir, `${safeSlug}${extension}`);
+    await (0, promises_1.mkdir)(assetDir, { recursive: true });
+    await (0, promises_1.writeFile)(outputPath, bytes);
+    const installedRelated = [];
+    for (const { related, filename } of relatedInstallPlan) {
+        const downloaded = await downloadAndVerify({
+            url: related.url,
+            token: creds?.token,
+            expectedChecksumSha256: related.checksumSha256,
+            expectedSizeBytes: related.sizeBytes,
+            label: `Vault asset ${canonicalAssetId} related artifact "${related.role}"`,
+        });
+        const relatedPath = ['public', 'assets', 'vault', canonicalAssetId, filename].join('/');
+        await (0, promises_1.writeFile)(resolveInside(assetDir, filename), downloaded.bytes);
+        installedRelated.push({
+            role: related.role,
+            path: relatedPath,
+            sourceUrl: related.url,
+            checksumSha256: downloaded.checksumSha256,
+            sizeBytes: downloaded.bytes.length,
+        });
+    }
+    const receiptPath = (0, node_path_1.join)(worldDir, 'public', 'helix.assets.json');
+    let prior = {
+        version: 1,
+        vaultAssets: [],
+        assets: [],
+    };
+    try {
+        prior = JSON.parse(await (0, promises_1.readFile)(receiptPath, 'utf8'));
+    }
+    catch {
+        // First installed Vault asset in this world.
+    }
+    const newRelatedPaths = new Set(installedRelated.map((entry) => entry.path));
+    const assetDirectory = assetDir;
+    const priorRelatedPaths = (prior.vaultAssets ?? [])
+        .find((entry) => entry.assetId === canonicalAssetId)
+        ?.relatedArtifacts?.map((entry) => entry.path) ?? [];
+    for (const priorPath of priorRelatedPaths) {
+        if (newRelatedPaths.has(priorPath))
+            continue;
+        const absolutePriorPath = (0, node_path_1.resolve)(worldDir, priorPath);
+        const relativeToAsset = (0, node_path_1.relative)(assetDirectory, absolutePriorPath);
+        if (!relativeToAsset || relativeToAsset.startsWith('..') || (0, node_path_1.isAbsolute)(relativeToAsset)) {
+            continue;
+        }
+        try {
+            await (0, promises_1.unlink)(absolutePriorPath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    const installed = {
+        assetId: canonicalAssetId,
+        slug: detail.slug,
+        kind: detail.kind,
+        version,
+        path: relativePath,
+        sourceUrl: downloadUrl,
+        checksumSha256,
+        sizeBytes: bytes.length,
+        ...(detail.kind === 'material' ? { materialRenditions } : {}),
+        relatedArtifacts: installedRelated,
+    };
+    const artifactKey = new URL(artifactUrl).pathname.replace(/^\/+/, '');
+    prior.vaultAssets = [
+        ...(prior.vaultAssets ?? []).filter((entry) => entry.assetId !== canonicalAssetId),
+        {
+            assetId: canonicalAssetId,
+            version,
+            kind: detail.kind,
+            artifactKey,
+            integrity: `sha256-${installed.checksumSha256}`,
+            checksumSha256: installed.checksumSha256,
+            ...(detail.kind === 'material' ? { materialRenditions } : {}),
+            relatedArtifacts: installedRelated,
+        },
+    ];
+    prior.assets = [
+        ...(prior.assets ?? []).filter((entry) => entry.assetId !== canonicalAssetId),
+        {
+            assetId: canonicalAssetId,
+            path: relativePath.replace(/^public[\\/]/, '').replaceAll('\\', '/'),
+            provenance: 'vault',
+            source: 'Vault',
+            ...(typeof detail.license === 'string' ? { licence: detail.license } : {}),
+        },
+    ];
+    const temporaryReceipt = `${receiptPath}.tmp-${process.pid}`;
+    await (0, promises_1.writeFile)(temporaryReceipt, `${JSON.stringify(prior, null, 2)}\n`);
+    await (0, promises_1.rename)(temporaryReceipt, receiptPath);
+    return installed;
+}
+function assetBaseFromManifest(manifest) {
+    const direct = manifest.assetBaseUrl;
+    if (typeof direct === 'string')
+        return direct;
+    const payload = manifest.payload;
+    if (payload && typeof payload === 'object') {
+        const nested = payload.assetBaseUrl;
+        if (typeof nested === 'string')
+            return nested;
+    }
+    throw new Error('Material pack manifest does not expose assetBaseUrl');
+}
+async function listMaterials(apiUrl, query = {}, slug = 'helix-materials') {
+    const api = new api_1.HelixApi(apiUrl);
+    const manifest = await api.requestItem('GET', `/api/v1/instant-packages/${encodeURIComponent(slug)}/versions/latest`);
+    const assetBaseUrl = assetBaseFromManifest(manifest).replace(/\/+$/, '');
+    const response = await fetch(`${assetBaseUrl}/catalog.json`);
+    if (!response.ok)
+        throw new Error(`Material catalog request failed (${response.status})`);
+    const catalog = (await response.json());
+    if (!Array.isArray(catalog.materials))
+        throw new Error('Material catalog is invalid');
+    const listable = catalog.materials.filter((material) => !material.hidden);
+    const unlistedIds = listable.filter((material) => (0, availability_1.materialUnavailableReason)(material) !== null).map((material) => material.id);
+    const offered = query.includeUnlisted
+        ? catalog.materials
+        : listable.filter((material) => (0, availability_1.materialUnavailableReason)(material) === null);
+    const requested = query.resolution?.trim() ? query.resolution.trim() : null;
+    const packResolutions = packResolutionOptions(offered);
+    // A resolution this pack does not carry ANYWHERE is a loud failure, not an
+    // empty result — an empty list reads as "no materials matched your search".
+    if (requested && !offered.some((material) => matchMaterialResolution(materialResolutionOptions(material), requested))) {
+        throw new Error(`Material pack "${catalog.pack?.slug ?? slug}"@${catalog.pack?.version ?? 'latest'} does not offer resolution "${requested}" — available: ${renderResolutionList(packResolutions)}`);
+    }
+    const needle = query.q?.trim().toLowerCase() ?? '';
+    const matched = offered.filter((material) => {
+        if (query.category && material.category !== query.category)
+            return false;
+        return (!needle ||
+            [material.id, material.name, material.category, ...(material.tags ?? [])]
+                .join(' ')
+                .toLowerCase()
+                .includes(needle));
+    });
+    let skippedWithoutResolution = 0;
+    let skippedProcedural = 0;
+    const carried = requested
+        ? matched.filter((material) => {
+            const options = materialResolutionOptions(material);
+            if (!options.length) {
+                skippedProcedural += 1;
+                return false;
+            }
+            if (!matchMaterialResolution(options, requested)) {
+                skippedWithoutResolution += 1;
+                return false;
+            }
+            return true;
+        })
+        : matched;
+    const limited = query.limit === undefined
+        ? carried
+        : carried.slice(0, Math.max(0, Math.floor(query.limit)));
+    const materials = limited.map((material) => describeMaterialResolution(material, assetBaseUrl, requested));
+    await (0, pins_1.attachMaterialPins)(apiUrl, materials, query.resolve !== false);
+    return {
+        slug: catalog.pack?.slug ?? slug,
+        version: catalog.pack?.version ?? 'latest',
+        schemaVersion: catalog.schemaVersion ?? null,
+        assetBaseUrl,
+        materials,
+        resolution: {
+            requested,
+            packResolutions,
+            matched: materials.length,
+            skippedWithoutResolution,
+            skippedProcedural,
+        },
+        unlisted: {
+            count: query.includeUnlisted ? 0 : unlistedIds.length,
+            ids: query.includeUnlisted ? [] : unlistedIds,
+            policy: availability_1.OFFERED_MATERIAL_POLICY,
+        },
+    };
+}
+async function resolveMaterial(apiUrl, id, slug = 'helix-materials', options = {}) {
+    // Resolve against the UNFILTERED catalog: the resolution check belongs to the
+    // named material, so `helix assets material <id> --resolution 4k` must say
+    // what THAT material offers, not "not found". Pins are left off that listing —
+    // one material is asked for, so only one is worth resolving.
+    const catalog = await listMaterials(apiUrl, { resolve: false, includeUnlisted: true }, slug);
+    const material = catalog.materials.find((candidate) => candidate.id === id);
+    if (!material)
+        throw new Error(`Material "${id}" was not found in ${slug}`);
+    const unavailable = (0, availability_1.materialUnavailableReason)(material);
+    if (unavailable && !options.includeUnlisted) {
+        throw new Error(`${unavailable}. Pick another from \`helix assets materials\`, or pass --include-unlisted to resolve it anyway.`);
+    }
+    const requested = options.resolution?.trim() ? options.resolution.trim() : null;
+    const { resolvedMaps: _ignored, resolution: _prior, vault: _vault, vaultWarning: _vaultWarning, continuum: _continuum, continuumWarning: _continuumWarning, ...entry } = material;
+    const resolved = describeMaterialResolution(entry, catalog.assetBaseUrl, requested);
+    await (0, pins_1.attachMaterialPins)(apiUrl, [resolved], options.resolve !== false);
+    return { assetBaseUrl: catalog.assetBaseUrl, ...resolved };
+}
+//# sourceMappingURL=assets.js.map