@helix3/helix-cli 0.1.13-helix3.65 → 0.1.13-helix3.67

package/README.md

@@ -49,9 +49,11 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix thumbnail set <slug> <file>` | Upload a thumbnail or preview image through the CLI-owned media path. |
 | `helix assets search\|get\|versions\|track\|install\|update` | Search the typed Vault with explainable ranking; inspect/manage annotations and immutable versions; install by durable ID with verified SHA-256 receipts. |
 | `helix assets start\|status\|generate\|resume` | Start or poll generation without duplicates. Props/characters use the main Dreamer path; standalone assets use the shared broker and report the auto-published `vaultAssetId`. |
+| `helix assets voices [--search <text>] [--category premade\|professional] [--page-size <n>] [--page-token <token>] [--json]` | Discover safe text-to-speech voices through the authenticated HELIX catalog, including language, labels, preview, default/recommended selection, and pagination. |
 | `helix assets generate-image\|generate-material\|generate-audio\|generate-environment` | Run the supported standalone generation adapters. Material is a validated PBR bundle (1K default, explicit 2K); splats declare object/environment scope. Animation remains an explicit unavailable boundary. |
 | `helix assets start-reference\|generate-reference` | Start or fully drive a character job from a local four-view PNG/JPEG/WebP. The backend validates and reuses the exact sheet; it skips image generation while preserving mesh, texture, rig, LOD, thumbnail, billing, and Vault publication. |
-| `helix assets materials\|material` | Discover the small built-in material palette and resolve its immutable map URLs before searching or generating. |
+| `helix assets materials [--resolution <res>] [--human]` | Discover the small built-in material palette. `--resolution` keeps only materials carrying that texture resolution. |
+| `helix assets material <id> [--resolution <res>] [--human]` | Resolve one material to its immutable map URLs at the resolution you pick (default: the pack's own default). |
 | `helix assets credits\|check-loaders` | Render asset credits from provenance and reject models requiring unsupported loaders. |
 | `helix character retarget-animation <clip.fbx\|clip.glb>` | Retarget a raw Mixamo/Meshy clip directly to `helix-humanoid@1`. FBX conversion is deterministic and runs inside the CLI; no hidden Blender/DCC pre-export is required. |
 | `helix world audit\|source-audit\|perf-gate\|prove-live` | Run the blocking world QA, performance, and deployed-build identity gates. |
@@ -145,11 +147,15 @@ helix assets generate-audio "hopeful orchestral exploration theme" \
   --mode music --duration-seconds 180 --force-instrumental
 
 # Text to speech
+helix assets voices --search narrator --page-size 10
 helix assets generate-audio --mode text_to_speech \
-  --text "Welcome to HELIX." --voice-id 21m00Tcm4TlvDq8ikWAM \
+  --text "Welcome to HELIX." --voice-id <id-from-catalog> \
   --language-code en --stability 0.5 --speaker-boost
 ```
 
+Use the opaque `--page-token` printed by a page to continue. Voice cloning and
+voice administration are deliberately not exposed.
+
 Use a deterministic four-view sheet when you already have approved FRONT, BACK,
 LEFT, and RIGHT character art and do not want Dreamer to generate another image:
 
@@ -164,6 +170,47 @@ The reference endpoint is character-only. The file is image-guarded, normalized,
 checksum-bound to the job, semantically validated, and mirrored before approval.
 Retries reuse those same bytes and never invoke or charge the image provider.
 
+## Material texture resolution
+
+A platform material can ship more than one texture resolution. `--resolution` picks which one you
+get; without it you get the pack's declared default, byte-for-byte what every earlier CLI returned.
+
+```bash
+helix assets material brick-block                      # the pack's default resolution
+helix assets material brick-block --resolution 2k      # the 2K variant's map URLs
+helix assets material brick-block --resolution 2048    # same thing — numeric spelling
+helix assets materials --resolution 2k --human         # only materials that carry 2K
+```
+
+Accepted values are the keys the catalog itself declares (`1k`, `2k`, …), case-insensitively, plus
+the numeric aliases `1024`/`2048`, which map onto the variant authored at that pixel edge.
+
+Both commands print JSON by default (agents and the MCP delegation parse it); `--human` prints a
+readable summary instead. Either way the output states **which resolution was resolved and which
+ones the material offers**, under `resolution`:
+
+```jsonc
+"resolution": {
+  "requested": "2k", "resolved": "2k", "pixels": 2048, "default": "1k",
+  "available": [{ "key": "1k", "pixels": 1024 }, { "key": "2k", "pixels": 2048 }],
+  "applicable": true
+}
+```
+
+Three rules make this safe to rely on:
+
+- **No silent fallback, ever.** Asking for a resolution the material does not carry is an error that
+  names the ones it does. You never receive a different resolution than the one you asked for.
+- **Old packs keep working.** A catalog with no `resolutions` block (`schemaVersion: 1`) is treated
+  as having exactly one resolution, keyed `default`, derived from its existing `maps`. Such a pack
+  never claims to be "1k" — it does not say how big its textures are, so neither do we.
+- **Procedural materials are not an error.** `glass` and `procedural_water` carry no texture maps;
+  a resolution request against them is ignored and the output says so in `resolution.note`.
+
+`helix assets install` has no resolution flag: Vault related-artifact roles are semantic
+(`source.albedo`, `runtime.ktx2.normal`, `sky.backdrop`), never resolution-tagged, so a filter there
+would filter nothing.
+
 ## Item publish flow
 
 `helix item publish` is a different shape from a world publish: one mesh, one round trip, an

package/dist/assets.d.ts

@@ -14,6 +14,48 @@ export type DreamerAudioVoiceSettings = {
     speed?: number;
     speakerBoost?: boolean;
 };
+export type DreamerVoiceCategory = 'premade' | 'professional';
+export type DreamerVoiceLanguage = {
+    code: string;
+    locale: string | null;
+    accent: string | null;
+    previewUrl: string | null;
+};
+export type DreamerCatalogVoice = {
+    id: string;
+    name: string;
+    description: string | null;
+    category: DreamerVoiceCategory;
+    labels: {
+        accent: string | null;
+        age: string | null;
+        gender: string | null;
+        useCase: string | null;
+    };
+    languages: DreamerVoiceLanguage[];
+    previewUrl: string | null;
+    curated: true;
+};
+export type DreamerVoiceCatalogQuery = {
+    search?: string;
+    pageSize?: number;
+    pageToken?: string;
+    category?: DreamerVoiceCategory;
+};
+export type DreamerVoiceCatalogResponse = {
+    voices: DreamerCatalogVoice[];
+    selection: {
+        defaultVoiceId: string | null;
+        curatedVoiceIds: string[];
+    };
+    pageInfo: {
+        pageSize: number;
+        hasMore: boolean;
+        nextPageToken: string | null;
+        totalCount: number | null;
+    };
+    stale: boolean;
+};
 export type DreamerAssetJob = {
     id: string;
     status: string;
@@ -229,25 +271,108 @@ export declare class UnavailableCapabilityError extends Error {
     readonly code = "CAPABILITY_UNAVAILABLE";
     constructor(capability: string, message: string);
 }
+export type MaterialMaps = {
+    albedo: string;
+    normal: string;
+    orm: string;
+};
+/**
+ * One texture-resolution variant a catalog entry declares (pack catalog
+ * schemaVersion 2+). `pixels` is the authored square edge, e.g. 2048 for "2k".
+ */
+export type MaterialResolutionVariant = {
+    pixels?: number;
+    maps: MaterialMaps;
+};
 export type MaterialCatalogEntry = {
     id: string;
     name: string;
     category: string;
     kind: 'texture' | 'glass' | 'procedural_water';
     tags: string[];
-    maps?: {
-        albedo: string;
-        normal: string;
-        orm: string;
-    };
+    /** The DEFAULT resolution's maps. Unchanged across schema versions. */
+    maps?: MaterialMaps;
+    /** Catalog schemaVersion 2+: names which `resolutions` key `maps` mirrors. */
+    defaultResolution?: string;
+    /** Catalog schemaVersion 2+: every texture resolution this material carries. */
+    resolutions?: Record<string, MaterialResolutionVariant>;
     [key: string]: unknown;
 };
+/** One resolvable resolution of one material, normalized across schema versions. */
+export type MaterialResolutionOption = {
+    key: string;
+    pixels: number | null;
+    maps: MaterialMaps;
+};
+/**
+ * What a command actually resolved, and what else it could have. Present on
+ * every material this CLI returns so a caller can SEE the choice it has
+ * instead of guessing — and so a silent downgrade is impossible.
+ */
+export type MaterialResolutionReport = {
+    /** Exactly what the caller passed, or null when they did not ask. */
+    requested: string | null;
+    /** The catalog key whose maps were used; null when the material has none. */
+    resolved: string | null;
+    /** Authored square edge of the resolved variant when the pack declares it. */
+    pixels: number | null;
+    /** The key this material treats as its default. */
+    default: string | null;
+    available: Array<{
+        key: string;
+        pixels: number | null;
+    }>;
+    /** false for procedural materials — they carry no texture maps at all. */
+    applicable: boolean;
+    note?: string;
+};
+export type ResolvedMaterial = MaterialCatalogEntry & {
+    resolvedMaps?: Record<string, string>;
+    resolution: MaterialResolutionReport;
+};
 export type MaterialCatalogResult = {
     slug: string;
     version: string;
+    /** The catalog's own schemaVersion, verbatim (1 = no per-resolution variants). */
+    schemaVersion: string | number | null;
     assetBaseUrl: string;
-    materials: MaterialCatalogEntry[];
+    materials: ResolvedMaterial[];
+    resolution: {
+        requested: string | null;
+        /** Every resolution key offered by ANY material in this pack. */
+        packResolutions: Array<{
+            key: string;
+            pixels: number | null;
+        }>;
+        matched: number;
+        /** Texture materials dropped because they lack the requested resolution. */
+        skippedWithoutResolution: number;
+        /** Procedural materials dropped because they carry no texture maps. */
+        skippedProcedural: number;
+    };
 };
+/**
+ * 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.
+ */
+export declare const DEFAULT_RESOLUTION_KEY = "default";
+/**
+ * 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.
+ */
+export declare function materialResolutionOptions(material: MaterialCatalogEntry): MaterialResolutionOption[];
+/** The key whose maps the pack mirrors at the top level — the default download. */
+export declare function materialDefaultResolutionKey(material: MaterialCatalogEntry, options?: MaterialResolutionOption[]): string | null;
+/**
+ * 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.
+ */
+export declare function matchMaterialResolution(options: MaterialResolutionOption[], requested: string): MaterialResolutionOption | null;
 export declare function generateAndPublishAsset(creds: CliCredentials, input: GenerateAssetInput, options?: GenerateAssetOptions): Promise<DreamerAssetJob>;
 export declare function generateAndPublishAssetFromReference(creds: CliCredentials, input: GenerateAssetFromReferenceInput, options?: GenerateAssetOptions): Promise<DreamerAssetJob>;
 export declare function startDreamerAssetGeneration(creds: CliCredentials, input: GenerateAssetInput): Promise<DreamerAssetJob>;
@@ -293,6 +418,12 @@ export declare function generateAudio(creds: CliCredentials, input: GenerateAudi
     timeoutMs?: number;
     onProgress?: (job: StandaloneGeneratedAsset) => void;
 }): Promise<StandaloneGeneratedAsset>;
+/**
+ * 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.
+ */
+export declare function listDreamerVoices(creds: CliCredentials, query?: DreamerVoiceCatalogQuery): Promise<DreamerVoiceCatalogResponse>;
 export declare function searchVaultAssets(apiUrl: string, query?: VaultAssetSearch, creds?: CliCredentials): Promise<{
     items: VaultAssetSummary[];
     totalItems: number;
@@ -326,7 +457,8 @@ export declare function listMaterials(apiUrl: string, query?: {
     q?: string;
     category?: string;
     limit?: number;
+    resolution?: string;
 }, slug?: string): Promise<MaterialCatalogResult>;
-export declare function resolveMaterial(apiUrl: string, id: string, slug?: string): Promise<MaterialCatalogEntry & {
-    resolvedMaps?: Record<string, string>;
-}>;
+export declare function resolveMaterial(apiUrl: string, id: string, slug?: string, options?: {
+    resolution?: string;
+}): Promise<ResolvedMaterial>;

package/dist/assets.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnavailableCapabilityError = exports.AUDIO_GENERATION_TIMEOUT_MS = exports.VAULT_ASSET_KINDS = void 0;
+exports.DEFAULT_RESOLUTION_KEY = exports.UnavailableCapabilityError = exports.AUDIO_GENERATION_TIMEOUT_MS = exports.VAULT_ASSET_KINDS = void 0;
+exports.materialResolutionOptions = materialResolutionOptions;
+exports.materialDefaultResolutionKey = materialDefaultResolutionKey;
+exports.matchMaterialResolution = matchMaterialResolution;
 exports.generateAndPublishAsset = generateAndPublishAsset;
 exports.generateAndPublishAssetFromReference = generateAndPublishAssetFromReference;
 exports.startDreamerAssetGeneration = startDreamerAssetGeneration;
@@ -12,6 +15,7 @@ exports.startStandaloneAssetGeneration = startStandaloneAssetGeneration;
 exports.getStandaloneAssetGenerationJob = getStandaloneAssetGenerationJob;
 exports.generateImage = generateImage;
 exports.generateAudio = generateAudio;
+exports.listDreamerVoices = listDreamerVoices;
 exports.searchVaultAssets = searchVaultAssets;
 exports.getVaultAsset = getVaultAsset;
 exports.getVaultAssetVersions = getVaultAssetVersions;
@@ -52,6 +56,184 @@ class UnavailableCapabilityError extends Error {
     }
 }
 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);
@@ -199,6 +381,24 @@ function generateImage(creds, input, options = {}) {
 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();
@@ -492,6 +692,13 @@ async function listMaterials(apiUrl, query = {}, slug = 'helix-materials') {
     const catalog = (await response.json());
     if (!Array.isArray(catalog.materials))
         throw new Error('Material catalog is invalid');
+    const requested = query.resolution?.trim() ? query.resolution.trim() : null;
+    const packResolutions = packResolutionOptions(catalog.materials);
+    // 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 && !catalog.materials.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 = catalog.materials.filter((material) => {
         if (query.category && material.category !== query.category)
@@ -502,29 +709,51 @@ async function listMaterials(apiUrl, query = {}, slug = 'helix-materials') {
                 .toLowerCase()
                 .includes(needle));
     });
-    const materials = query.limit === undefined
-        ? matched
-        : matched.slice(0, Math.max(0, Math.floor(query.limit)));
+    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));
     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,
+        },
     };
 }
-async function resolveMaterial(apiUrl, id, slug = 'helix-materials') {
+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".
     const catalog = await listMaterials(apiUrl, {}, slug);
     const material = catalog.materials.find((candidate) => candidate.id === id);
     if (!material)
         throw new Error(`Material "${id}" was not found in ${slug}`);
-    const resolvedMaps = material.maps
-        ? Object.fromEntries(Object.entries(material.maps).map(([key, value]) => [
-            key,
-            /^https?:\/\//i.test(value)
-                ? value
-                : `${catalog.assetBaseUrl}/${value.replace(/^\/+/, '')}`,
-        ]))
-        : undefined;
-    return { ...material, ...(resolvedMaps ? { resolvedMaps } : {}) };
+    const requested = options.resolution?.trim() ? options.resolution.trim() : null;
+    const { resolvedMaps: _ignored, resolution: _prior, ...entry } = material;
+    return describeMaterialResolution(entry, catalog.assetBaseUrl, requested);
 }
 //# sourceMappingURL=assets.js.map