@moewolf/moe-icons-cli 0.0.1 → 0.0.2

package/dist/core/pro-selected-download.js

@@ -0,0 +1,269 @@
+import { sha256Bytes } from "../project/install-metadata.js";
+import { gunzipSync } from "node:zlib";
+import { join } from "node:path";
+import { readFileSync, mkdirSync, writeFileSync, existsSync, renameSync, rmSync, readdirSync, } from "node:fs";
+import { CliError } from "../errors/index.js";
+import { runAccessTokenUseCase } from "./auth.js";
+import { downloadSignedArtifact, parseSignedDescriptor } from "./signed-artifact.js";
+import { parseResourceRefs, parseResourceIndex, planSelectedResources, downloadSelectedResources, } from "./selected-resources.js";
+import { resolveProDescriptorEndpoint, proSignedDownloadOptions, extractProMetadata, fetchProDescriptor, } from "./pro-download.js";
+import { validateConfigDocument, } from "../project/config.js";
+import { parseCatalog } from "../catalog/catalog.js";
+import { cacheArtifact } from "./cache.js";
+import { homedir } from "node:os";
+export async function downloadProSelected(context, auth, descriptor, selection, deps) {
+    const fetchFn = deps.fetch ?? fetch;
+    const endpointInfo = resolveProDescriptorEndpoint(context.env);
+    const endpoint = new URL(endpointInfo.url.replace(/\/artifact-descriptor$/, "/resource-descriptor"));
+    if (endpoint.origin !== "https://api.moeicons.com" && !endpointInfo.allowLoopback)
+        throw new CliError("VALIDATION_ERROR", "resource descriptor endpoint must be the trusted API or a test loopback");
+    const getDescriptor = async (kind) => {
+        let token = await runAccessTokenUseCase(context, auth);
+        let refreshed = false;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            let response;
+            try {
+                response = await fetchFn(endpoint, {
+                    method: "POST",
+                    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+                    body: JSON.stringify({
+                        version: descriptor.version,
+                        descriptorSha256: descriptor.descriptorSha256,
+                        kind,
+                    }),
+                    redirect: "error",
+                    signal: AbortSignal.any([context.signal, AbortSignal.timeout(30000)]),
+                });
+            }
+            catch {
+                if (context.signal.aborted)
+                    throw new CliError("CANCELLED", "selected resource download cancelled");
+                if (attempt === 2)
+                    throw new CliError("NETWORK_ERROR", "resource authorization request failed after 3 attempts; retry the same fixed release");
+                await new Promise((resolve) => setTimeout(resolve, 200 * (attempt + 1)));
+                continue;
+            }
+            if (response.status === 401 && !refreshed) {
+                await response.body?.cancel();
+                token = await runAccessTokenUseCase(context, auth, true);
+                refreshed = true;
+                continue;
+            }
+            if (response.status === 403) {
+                await response.body?.cancel();
+                throw new CliError("FORBIDDEN", "active pro entitlement required for selected resources");
+            }
+            // Bound JSON reads independently of Content-Length.
+            const reader = response.body?.getReader();
+            const chunks = [];
+            let size = 0;
+            if (!reader)
+                throw new CliError("NETWORK_ERROR", "empty resource descriptor response");
+            try {
+                for (;;) {
+                    const part = await reader.read();
+                    if (part.done)
+                        break;
+                    size += part.value.length;
+                    if (size > 8192) {
+                        await reader.cancel();
+                        throw new CliError("VALIDATION_ERROR", "resource descriptor exceeds 8 KiB");
+                    }
+                    chunks.push(part.value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            let value;
+            try {
+                const parsed = JSON.parse(Buffer.concat(chunks).toString());
+                if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+                    throw new Error("invalid JSON object");
+                value = parsed;
+            }
+            catch {
+                throw new CliError("VALIDATION_ERROR", "invalid resource descriptor JSON");
+            }
+            if (response.status === 404 && value?.code === "RESOURCE_NOT_AVAILABLE")
+                return undefined;
+            if (response.status === 401)
+                throw new CliError("AUTH_ERROR", "resource authentication failed after refresh; run moeicons login");
+            if ([429, 500, 502, 503, 504].includes(response.status) && attempt < 2) {
+                await new Promise((resolve) => setTimeout(resolve, 200 * (attempt + 1)));
+                continue;
+            }
+            if (response.status !== 200)
+                throw new CliError("NETWORK_ERROR", `resource descriptor request failed (${response.status}); no full archive was downloaded`);
+            const filename = kind === "resource-index"
+                ? `moe-icons-pro-resource-index-${descriptor.version}.json.gz`
+                : `moe-icons-pro-resources-${descriptor.version}.bin`;
+            if (!value ||
+                Array.isArray(value) ||
+                value.ok !== true ||
+                value.tier !== "pro" ||
+                value.kind !== kind ||
+                value.version !== descriptor.version ||
+                value.descriptorSha256 !== descriptor.descriptorSha256 ||
+                value.parentArtifactSha256 !== descriptor.sha256 ||
+                value.filename !== filename ||
+                (kind === "resource-index" &&
+                    (value.sha256 !== descriptor.resources.index.sha256 ||
+                        value.size !== descriptor.resources.index.size)) ||
+                Object.keys(value).some((k) => ![
+                    "ok",
+                    "tier",
+                    "kind",
+                    "version",
+                    "descriptorSha256",
+                    "filename",
+                    "parentArtifactSha256",
+                    "url",
+                    "expiresAt",
+                    "size",
+                    "sha256",
+                ].includes(k)))
+                throw new CliError("VALIDATION_ERROR", "resource descriptor identity changed; retry the original fixed release");
+            const signed = parseSignedDescriptor({ url: value.url, expiresAt: value.expiresAt, size: value.size, sha256: value.sha256 }, context.now().getTime(), { allowLoopback: endpointInfo.allowLoopback });
+            return { ...signed, filename, parentArtifactSha256: descriptor.sha256 };
+        }
+        throw new CliError("NETWORK_ERROR", "resource descriptor retry budget exhausted");
+    };
+    const indexDescriptor = await getDescriptor("resource-index");
+    if (!indexDescriptor)
+        throw new CliError("VALIDATION_ERROR", "release advertises selected resources but the resource endpoint is unavailable; retry the same release or explicitly set downloadMode=full. No full archive was downloaded");
+    if (indexDescriptor.size > 8 * 1024 * 1024)
+        throw new CliError("VALIDATION_ERROR", "compressed resource index exceeds 8 MiB");
+    if (!descriptor.metadata)
+        throw new CliError("VALIDATION_ERROR", "pro metadata is missing");
+    const downloadOptions = proSignedDownloadOptions(context, deps);
+    const expired = (error) => error instanceof CliError &&
+        /HTTP (?:401|403)\b|failed with (?:401|403)\b|expired/i.test(error.message);
+    const originalMetadata = descriptor.metadata;
+    let currentMetadata = originalMetadata;
+    let metadataBytes;
+    for (let attempt = 0; attempt < 3; attempt++)
+        try {
+            metadataBytes = await downloadSignedArtifact(currentMetadata, downloadOptions);
+            break;
+        }
+        catch (error) {
+            if (!expired(error) || attempt === 2)
+                throw error;
+            const renewed = await fetchProDescriptor(context, auth, { version: descriptor.version, descriptorSha256: descriptor.descriptorSha256 }, deps);
+            if (renewed.sha256 !== descriptor.sha256 ||
+                !renewed.metadata ||
+                renewed.metadata.sha256 !== originalMetadata.sha256 ||
+                renewed.metadata.size !== originalMetadata.size ||
+                JSON.stringify(renewed.resources) !== JSON.stringify(descriptor.resources))
+                throw new CliError("VALIDATION_ERROR", "release identity changed during metadata URL renewal");
+            currentMetadata = renewed.metadata;
+        }
+    if (!metadataBytes)
+        throw new CliError("NETWORK_ERROR", "metadata URL renewal failed");
+    const metadata = extractProMetadata(metadataBytes, descriptor.catalogSha256, descriptor.version);
+    const catalog = parseCatalog(JSON.parse(metadata.catalogJson));
+    const strict = validateConfigDocument(selection.document, catalog);
+    if (strict.kind !== "ok")
+        throw new CliError("VALIDATION_ERROR", strict.kind === "invalid" ? strict.message : `config state: ${strict.kind}`);
+    const cacheDir = context.env.MOEICONS_CACHE_DIR ?? join(homedir(), ".moeicons", "cache");
+    const io = {
+        mkdirSync: (path) => {
+            mkdirSync(path, { recursive: true });
+        },
+        writeFileSync,
+        readFileSync,
+        existsSync,
+        renameSync,
+        rmSync,
+        readdirSync,
+    };
+    const cached = join(cacheDir, "resources", "pro", descriptor.version, indexDescriptor.sha256, "index.json.gz");
+    let indexBytes = existsSync(cached) ? readFileSync(cached) : undefined;
+    if (!indexBytes ||
+        indexBytes.length !== indexDescriptor.size ||
+        sha256Bytes(indexBytes) !== indexDescriptor.sha256) {
+        let signed = indexDescriptor;
+        for (let attempt = 0; attempt < 3; attempt++)
+            try {
+                indexBytes = Buffer.from(await downloadSignedArtifact({
+                    url: signed.url,
+                    expiresAt: signed.expiresAt,
+                    size: signed.size,
+                    sha256: signed.sha256,
+                }, downloadOptions));
+                break;
+            }
+            catch (error) {
+                if (!expired(error) || attempt === 2)
+                    throw error;
+                const renewed = await getDescriptor("resource-index");
+                if (!renewed ||
+                    renewed.sha256 !== indexDescriptor.sha256 ||
+                    renewed.size !== indexDescriptor.size)
+                    throw new CliError("VALIDATION_ERROR", "resource index changed during URL renewal");
+                signed = renewed;
+            }
+    }
+    if (!indexBytes)
+        throw new CliError("NETWORK_ERROR", "resource index URL renewal failed");
+    let bundle;
+    try {
+        const parsed = JSON.parse(gunzipSync(indexBytes, { maxOutputLength: 64 * 1024 * 1024 }).toString());
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            throw new Error("invalid index object");
+        bundle = parsed.bundle;
+    }
+    catch {
+        throw new CliError("VALIDATION_ERROR", "invalid compressed resource index");
+    }
+    const refs = parseResourceRefs({
+        schemaVersion: 1,
+        index: {
+            filename: indexDescriptor.filename,
+            size: indexDescriptor.size,
+            sha256: indexDescriptor.sha256,
+        },
+        bundle,
+    });
+    if (refs.bundle.sha256 !== descriptor.resources.bundle.sha256 ||
+        refs.bundle.size !== descriptor.resources.bundle.size ||
+        refs.bundle.filename !== descriptor.resources.bundle.filename)
+        throw new CliError("VALIDATION_ERROR", "resource index bundle does not match advertised release");
+    const index = parseResourceIndex(indexBytes, refs, {
+        version: descriptor.version,
+        tier: "pro",
+        artifactSha256: descriptor.sha256,
+    });
+    const plan = planSelectedResources(strict.config, catalog, index);
+    context.ui.note(`Download plan: pro/${strict.config.target}, ${strict.config.icons.length} registered icons, ${Object.keys(strict.config.themes).length} themes, ${plan.paths.length} resource files, up to ${plan.payloadBytes} compressed bytes (verified cache reduces network traffic).${plan.fallbacks.length ? ` Fallbacks: ${plan.fallbacks.join("; ")}` : ""}`, context.signal);
+    cacheArtifact(io, cached, indexBytes, refs.index.sha256);
+    const downloaded = await downloadSelectedResources(index, refs.index.sha256, plan.paths, {
+        io,
+        cacheDir,
+        fetch: fetchFn,
+        signal: context.signal,
+        allowedHosts: downloadOptions.allowedHosts,
+        ...(endpointInfo.allowLoopback ? { allowLoopback: true } : {}),
+        getBundleUrl: async () => {
+            const signed = await getDescriptor("resource-bundle");
+            if (!signed ||
+                signed.sha256 !== refs.bundle.sha256 ||
+                signed.size !== refs.bundle.size ||
+                signed.filename !== refs.bundle.filename)
+                throw new CliError("VALIDATION_ERROR", "resource bundle changed after index verification");
+            return signed.url;
+        },
+    });
+    return {
+        ...metadata,
+        metadataBytes,
+        selected: {
+            ...downloaded,
+            refs,
+            indexBytes,
+            payloadBytes: plan.payloadBytes,
+            fallbacks: plan.fallbacks,
+        },
+    };
+}

package/dist/core/release-descriptor.d.ts

@@ -1,3 +1,4 @@
+import { type ResourceRefs } from "./selected-resources.js";
 export type ReleaseTarget = "react" | "vue" | "vanilla" | "assets";
 export declare const RELEASE_TARGETS: readonly ReleaseTarget[];
 /** Per-target subtree metadata written by the code-library release packer. */
@@ -7,13 +8,40 @@ export interface ReleaseTargetMetadata {
     readonly fileCount: number;
     readonly byteCount: number;
 }
+/** Per-file digest inside a metadata archive. */
+export interface ReleaseFileDigest {
+    readonly size: number;
+    readonly sha256: string;
+}
+/** Reference to a tier's metadata archive (MANUAL.md / catalog.json / manifest.json). */
+export interface ReleaseMetadataRef {
+    readonly filename: string;
+    readonly sha256: string;
+    readonly size: number;
+    readonly files: {
+        readonly "MANUAL.md": ReleaseFileDigest;
+        readonly "catalog.json": ReleaseFileDigest;
+        readonly "manifest.json": ReleaseFileDigest;
+    };
+}
+/** Optional assets-only archive reference (ICON-E2E-0907 / E2E-C7). */
+export interface ReleaseAssetsRef {
+    readonly filename: string;
+    readonly sha256: string;
+    readonly size: number;
+}
 export interface ReleaseTierArtifact {
+    readonly resources?: ResourceRefs;
     readonly filename: string;
     readonly sha256: string;
+    readonly size?: number;
     readonly styleGroups?: readonly string[];
     readonly styleGroupCount?: number;
     readonly targets?: readonly ReleaseTarget[];
     readonly targetMetadata?: Readonly<Partial<Record<ReleaseTarget, ReleaseTargetMetadata>>>;
+    readonly metadata?: ReleaseMetadataRef;
+    /** Present on new descriptors; absent on legacy four-archive descriptors. */
+    readonly assets?: ReleaseAssetsRef;
 }
 export interface ReleaseCatalogRef {
     readonly filename: string;
@@ -26,15 +54,28 @@ export interface ReleaseDescriptor {
     readonly fullVersion: string;
     readonly free: ReleaseTierArtifact;
     readonly catalog: ReleaseCatalogRef;
+    /** ICON-E2E-0907 / E2E-E2: present only on local-test candidates. */
+    readonly channel?: "local-test";
+    readonly publishable?: boolean;
+    readonly schemaVersion?: number;
+    readonly baseVersion?: string;
 }
 /** Parse release-descriptor.json. Never invent free.filename. */
 export declare function parseReleaseDescriptor(bytes: Uint8Array): ReleaseDescriptor;
+/** True when a fullVersion is a `X.Y.Z-test` local candidate version. */
+export declare function isLocalTestVersion(fullVersion: string): boolean;
+/**
+ * Reject local-test candidate descriptors unless they are explicitly local and
+ * non-publishable: an HTTP/remote source, a missing `local-test` channel, or
+ * `publishable: true` must never be accepted by the free install flow.
+ */
+export declare function assertLocalCandidateAllowed(descriptor: ReleaseDescriptor, viaLocalFixture: boolean): void;
 /** Parse `hex  filename` sidecar produced next to the descriptor. */
 export declare function parseSha256Sidecar(text: string): string;
 export declare const PUBLIC_FREE_REPO: {
     readonly owner: "moewolf-dev";
     readonly name: "moe-icons";
 };
-export declare const FREE_DOWNLOAD_HOSTS: readonly ["github.com", "objects.githubusercontent.com"];
+export declare const FREE_DOWNLOAD_HOSTS: readonly ["github.com", "objects.githubusercontent.com", "release-assets.githubusercontent.com"];
 export declare function githubReleaseAssetUrl(tag: string, filename: string): string;
 export declare function cacheKey(fullVersion: string, sha256: string): string;

package/dist/core/release-descriptor.js

@@ -1,7 +1,9 @@
+import { parseResourceRefs } from "./selected-resources.js";
 const SHA256_HEX = /^[0-9a-f]{64}$/i;
 const SAFE_FILENAME = /^[A-Za-z0-9._-]+$/;
 const SAFE_SUBTREE_PATH = /^[A-Za-z0-9._/-]+$/;
 export const RELEASE_TARGETS = ["react", "vue", "vanilla", "assets"];
+const LOCAL_TEST_VERSION = /^(\d+)\.(\d+)\.(\d+)-test$/;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -34,10 +36,14 @@ function parseTargetMetadata(value, field) {
         if (typeof entry.path !== "string" || !SAFE_SUBTREE_PATH.test(entry.path)) {
             throw new Error(`${field}.${key}.path must be a safe subtree path`);
         }
-        if (typeof entry.fileCount !== "number" || !Number.isSafeInteger(entry.fileCount) || entry.fileCount < 0) {
+        if (typeof entry.fileCount !== "number" ||
+            !Number.isSafeInteger(entry.fileCount) ||
+            entry.fileCount < 0) {
             throw new Error(`${field}.${key}.fileCount must be a non-negative integer`);
         }
-        if (typeof entry.byteCount !== "number" || !Number.isSafeInteger(entry.byteCount) || entry.byteCount < 0) {
+        if (typeof entry.byteCount !== "number" ||
+            !Number.isSafeInteger(entry.byteCount) ||
+            entry.byteCount < 0) {
             throw new Error(`${field}.${key}.byteCount must be a non-negative integer`);
         }
         result[target] = {
@@ -49,22 +55,80 @@ function parseTargetMetadata(value, field) {
     }
     return result;
 }
-function parseTier(value, field) {
+function parseFileDigest(value, field) {
     if (!isRecord(value))
         throw new Error(`${field} must be an object`);
+    if (typeof value.size !== "number" || !Number.isSafeInteger(value.size) || value.size < 1) {
+        throw new Error(`${field}.size must be a positive integer`);
+    }
+    return { size: value.size, sha256: requireSha(value.sha256, `${field}.sha256`) };
+}
+function parseMetadataRef(value, field) {
+    if (!isRecord(value))
+        throw new Error(`${field} must be an object`);
+    if (!isRecord(value.files))
+        throw new Error(`${field}.files must be an object`);
+    const files = {
+        "MANUAL.md": parseFileDigest(value.files["MANUAL.md"], `${field}.files.MANUAL.md`),
+        "catalog.json": parseFileDigest(value.files["catalog.json"], `${field}.files.catalog.json`),
+        "manifest.json": parseFileDigest(value.files["manifest.json"], `${field}.files.manifest.json`),
+    };
+    if (typeof value.size !== "number" || !Number.isSafeInteger(value.size) || value.size < 1) {
+        throw new Error(`${field}.size must be a positive integer`);
+    }
+    return {
+        filename: requireFilename(value.filename, `${field}.filename`),
+        sha256: requireSha(value.sha256, `${field}.sha256`),
+        size: value.size,
+        files,
+    };
+}
+function parseAssetsRef(value, field) {
+    if (!isRecord(value))
+        throw new Error(`${field} must be an object`);
+    if (typeof value.size !== "number" || !Number.isSafeInteger(value.size) || value.size < 1) {
+        throw new Error(`${field}.size must be a positive integer`);
+    }
+    return {
+        filename: requireFilename(value.filename, `${field}.filename`),
+        sha256: requireSha(value.sha256, `${field}.sha256`),
+        size: value.size,
+    };
+}
+function parseTier(value, field, version) {
+    if (!isRecord(value))
+        throw new Error(`${field} must be an object`);
+    const resources = value.resources !== undefined ? parseResourceRefs(value.resources) : undefined;
+    if (resources &&
+        (resources.index.filename !== `moe-icons-${field}-resource-index-${version}.json.gz` ||
+            resources.bundle.filename !== `moe-icons-${field}-resources-${version}.bin`))
+        throw new Error(`${field}.resources filenames do not match tier/version`);
     return {
+        ...(resources ? { resources } : {}),
         filename: requireFilename(value.filename, `${field}.filename`),
         sha256: requireSha(value.sha256, `${field}.sha256`),
-        ...(Array.isArray(value.styleGroups) && value.styleGroups.every((item) => typeof item === "string")
+        ...(typeof value.size === "number" && Number.isSafeInteger(value.size) && value.size > 0
+            ? { size: value.size }
+            : {}),
+        ...(Array.isArray(value.styleGroups) &&
+            value.styleGroups.every((item) => typeof item === "string")
             ? { styleGroups: value.styleGroups }
             : {}),
-        ...(typeof value.styleGroupCount === "number" ? { styleGroupCount: value.styleGroupCount } : {}),
+        ...(typeof value.styleGroupCount === "number"
+            ? { styleGroupCount: value.styleGroupCount }
+            : {}),
         ...(Array.isArray(value.targets)
             ? { targets: value.targets.map((item) => requireTarget(item, `${field}.targets[]`)) }
             : {}),
         ...(value.targetMetadata !== undefined
             ? { targetMetadata: parseTargetMetadata(value.targetMetadata, `${field}.targetMetadata`) }
             : {}),
+        ...(value.metadata !== undefined
+            ? { metadata: parseMetadataRef(value.metadata, `${field}.metadata`) }
+            : {}),
+        ...(value.assets !== undefined
+            ? { assets: parseAssetsRef(value.assets, `${field}.assets`) }
+            : {}),
     };
 }
 /** Parse release-descriptor.json. Never invent free.filename. */
@@ -83,18 +147,56 @@ export function parseReleaseDescriptor(bytes) {
     }
     if (!isRecord(parsed.catalog))
         throw new Error("release-descriptor.json missing catalog");
+    const channel = parsed.channel === "local-test" ? "local-test" : undefined;
+    const publishable = parsed.publishable === true || parsed.publishable === false ? parsed.publishable : undefined;
     return {
         fullVersion: parsed.fullVersion,
-        free: parseTier(parsed.free, "free"),
+        free: parseTier(parsed.free, "free", parsed.fullVersion),
         catalog: {
             filename: requireFilename(parsed.catalog.filename, "catalog.filename"),
             sha256: requireSha(parsed.catalog.sha256, "catalog.sha256"),
             schemaVersion: typeof parsed.catalog.schemaVersion === "number" ? parsed.catalog.schemaVersion : 1,
-            ...(typeof parsed.catalog.iconCount === "number" ? { iconCount: parsed.catalog.iconCount } : {}),
-            ...(typeof parsed.catalog.styleGroupCount === "number" ? { styleGroupCount: parsed.catalog.styleGroupCount } : {}),
+            ...(typeof parsed.catalog.iconCount === "number"
+                ? { iconCount: parsed.catalog.iconCount }
+                : {}),
+            ...(typeof parsed.catalog.styleGroupCount === "number"
+                ? { styleGroupCount: parsed.catalog.styleGroupCount }
+                : {}),
         },
+        ...(channel ? { channel } : {}),
+        ...(publishable !== undefined ? { publishable } : {}),
+        ...(typeof parsed.schemaVersion === "number" ? { schemaVersion: parsed.schemaVersion } : {}),
+        ...(typeof parsed.baseVersion === "string" ? { baseVersion: parsed.baseVersion } : {}),
     };
 }
+/** True when a fullVersion is a `X.Y.Z-test` local candidate version. */
+export function isLocalTestVersion(fullVersion) {
+    return LOCAL_TEST_VERSION.test(fullVersion);
+}
+/**
+ * Reject local-test candidate descriptors unless they are explicitly local and
+ * non-publishable: an HTTP/remote source, a missing `local-test` channel, or
+ * `publishable: true` must never be accepted by the free install flow.
+ */
+export function assertLocalCandidateAllowed(descriptor, viaLocalFixture) {
+    if (!isLocalTestVersion(descriptor.fullVersion))
+        return;
+    if (!viaLocalFixture) {
+        throw new Error("local-test candidate descriptors are only accepted from a local release directory");
+    }
+    if (descriptor.channel !== "local-test") {
+        throw new Error("local-test candidate descriptor must declare channel local-test");
+    }
+    if (descriptor.publishable !== false) {
+        throw new Error("local-test candidate descriptor must declare publishable: false");
+    }
+    if (descriptor.schemaVersion !== 2) {
+        throw new Error("local-test candidate descriptor must be schemaVersion 2");
+    }
+    if (descriptor.baseVersion !== descriptor.fullVersion.replace(/-test$/, "")) {
+        throw new Error("local-test candidate descriptor baseVersion must match fullVersion");
+    }
+}
 /** Parse `hex  filename` sidecar produced next to the descriptor. */
 export function parseSha256Sidecar(text) {
     const token = text.trim().split(/\s+/)[0] ?? "";
@@ -103,7 +205,13 @@ export function parseSha256Sidecar(text) {
     return token.toLowerCase();
 }
 export const PUBLIC_FREE_REPO = { owner: "moewolf-dev", name: "moe-icons" };
-export const FREE_DOWNLOAD_HOSTS = ["github.com", "objects.githubusercontent.com"];
+// GitHub Release assets currently redirect through release-assets.githubusercontent.com;
+// keep the legacy objects host for older releases and CDN routing variants.
+export const FREE_DOWNLOAD_HOSTS = [
+    "github.com",
+    "objects.githubusercontent.com",
+    "release-assets.githubusercontent.com",
+];
 export function githubReleaseAssetUrl(tag, filename) {
     if (!tag.startsWith("v"))
         throw new Error("release tag must be v<fullVersion>");

package/dist/core/resource-variant.d.ts

@@ -1,10 +1,15 @@
 /**
- * G0/G1/G2: styleGroupId vs resourceVariantId.
- * Variant ids are deterministic: `<styleGroupId>-<webp|png>-<64|128|256|512>`.
- * Parse from the right: size, then format, remainder is styleGroupId.
+ * MEDIA-FORMAT-V2: styleGroupId vs resourceVariantId.
+ *
+ * Canonical variant ids are the actual source directory names:
+ * `<styleGroupId>-<imageSize>-<format>` (e.g. `example-bitmap-style-256-webp`). Parsing
+ * is controlled keyword-token based, never substring based; `3d` is an ordinary
+ * token. The legacy `<group ending -3d>-<format>-<size>` form is only readable
+ * through the explicit `parseLegacyResourceVariantId` compatibility branch.
  */
 export declare const BITMAP_STYLE_GROUP_RE: RegExp;
-export declare const BITMAP_FORMATS: readonly ["webp", "png"];
+export declare const LEGACY_BITMAP_STYLE_GROUP_RE: RegExp;
+export declare const BITMAP_FORMATS: readonly ["png", "webp"];
 export declare const BITMAP_SIZES: readonly [64, 128, 256, 512];
 export type BitmapFormat = (typeof BITMAP_FORMATS)[number];
 export type BitmapSize = (typeof BITMAP_SIZES)[number];
@@ -16,17 +21,29 @@ export interface ResourceVariant {
 }
 export declare const DEFAULT_BITMAP_FORMAT: BitmapFormat;
 export declare const DEFAULT_BITMAP_SIZE: BitmapSize;
-export declare function isBitmapStyleGroupId(id: string): boolean;
 export declare function isBitmapFormat(value: string): value is BitmapFormat;
 export declare function isBitmapSize(value: number): value is BitmapSize;
-/** Build a resourceVariantId; never invent aliases. */
-export declare function buildResourceVariantId(styleGroupId: string, format?: BitmapFormat, imageSize?: BitmapSize): string;
+/** Build the canonical v2 resourceVariantId (`<group>-<size>-<format>`). */
+export declare function buildResourceVariantId(styleGroupId: string, format?: string, imageSize?: number): string;
 /**
- * Parse `<styleGroupId>-<format>-<size>` from the right.
- * Rejects guessing by scanning for an arbitrary `-3d` substring.
+ * Parse a v2 name using complete `-` tokens. Returns undefined when the name is
+ * not a bitmap candidate (no format token); throws on duplicate/conflicting
+ * keywords; returns undefined when the canonical rebuilt id differs (e.g. the
+ * legacy format-before-size order).
  */
+export declare function parseBitmapName(name: string): ResourceVariant | undefined;
+/** Parse a canonical v2 resourceVariantId or throw. */
 export declare function parseResourceVariantId(resourceVariantId: string): ResourceVariant;
-/** Resolve format/size for a bitmap theme, applying catalog defaults when omitted. */
+/**
+ * Explicit v1 compatibility branch: legacy ids are
+ * `<styleGroupId ending -3d>-<format>-<size>`. Never guessed by the v2 parser.
+ */
+export declare function parseLegacyResourceVariantId(resourceVariantId: string): ResourceVariant;
+/**
+ * Build a canonical variant from a group id and optional format/size, applying
+ * the schema defaults `webp`/`256`. Availability must still be checked against
+ * the catalog by the caller (MEDIA-FORMAT-V2 D-05/B6).
+ */
 export declare function resolveResourceVariant(styleGroupId: string, options?: {
     readonly format?: string;
     readonly imageSize?: number;