@mapletip/data 0.1.0 → 0.3.0

package/README.md

@@ -13,7 +13,7 @@ bundles the domains it imports:
 ```ts
 import { getMonsterBrowse, openMonsterProduct } from '@mapletip/data/monsters';
 import { openRelease, resolveTargetAvailability } from '@mapletip/data/release';
-import { openItemProduct } from '@mapletip/data/items';
+import { getItemBrowse, openItemProduct } from '@mapletip/data/items';
 import { openEquipmentProduct } from '@mapletip/data/equipment';
 import { openQuestProduct } from '@mapletip/data/quests';
 import { openMediaProduct, resolveMediaUrl } from '@mapletip/data/media';
@@ -55,6 +55,38 @@ existing typed failure (`UNKNOWN_BUILD`, `UNSUPPORTED_PRODUCT`, `SCOPE_ERROR`,
 Supported builds are `cw-launch` (`classic-world`) and `gms-v83` (`gms`). When several
 reads share one release, keep using `openRelease` and reuse the opened release client.
 
+### Monster sprites
+
+Monster catalog contract `2.1` gives every row a `sprite` fact: when `known`, its value
+is the content ID (PNG SHA-256) of the `monster.sprite` image that the same build's Media
+product selects. `monsterSpriteUrl` turns it into the blob URL under the release root, so
+a browse page needs no Media catalog, Media detail pack or second product:
+
+```ts
+import { getMonsterBrowse, hasMonsterSprites, monsterSpriteUrl } from '@mapletip/data/monsters';
+
+const catalog = await getMonsterBrowse({ baseUrl: releaseRootUrl, pin: releasePin, buildId: 'gms-v83' });
+if (!hasMonsterSprites(catalog)) throw new Error('this pin predates Monster sprites');
+const rows = catalog.records.map((row) => ({
+  key: row.key,
+  spriteUrl: row.sprite.state === 'known' ? monsterSpriteUrl(releaseRootUrl, row.sprite.value) : undefined,
+}));
+```
+
+The `sprite` state mirrors Media exactly: `unknown` (for example, a monster with only
+stub frames), `absent` with its coverage key, or `unsupported`. Never substitute a
+placeholder or another build's image for a non-known state. Release assembly fails unless
+every row agrees with Media and every known content ID names a blob in the release.
+`monsterSpriteUrl` throws `SCHEMA_VALIDATION_ERROR` for anything but a lowercase 64-hex
+digest. `getMonsterBrowse` still requests only the release manifest named by the pin, the
+build index, the product manifest and the Monster catalog.
+
+Releases built before revision `2.1` carry contract-`2.0` catalogs without `sprite`; this
+SDK reads both, and `hasMonsterSprites` narrows a catalog to `2.1`. `@mapletip/data`
+`0.2.0` and older reject a `2.1` catalog with a typed `SCHEMA_VALIDATION_ERROR` instead of
+returning rows without sprites, so upgrade to `0.3.0` before adopting a pin that carries
+it.
+
 `pin` is the parsed `pin.json` published next to the release root by whoever assembled
 the release: it names the manifest path, SHA-256 and byte length and is the caller's
 trust anchor. The SDK never resolves a "current" release on its own and never fetches a
@@ -65,6 +97,54 @@ The same import runs in Node (SSR, prerendering, scripts) and in browsers using
 (HTTPS or localhost) because SHA-256 verification has no fallback. Rendering mode,
 routing, caching and UI adaptation stay with the consumer.
 
+## Items browse
+
+`getItemBrowse` reads one build's verified Item browse roster in a single call:
+
+```ts
+import { getItemBrowse, itemIconUrl } from '@mapletip/data/items';
+
+const browse = await getItemBrowse({
+  baseUrl: releaseRootUrl,
+  pin: releasePin,
+  buildId: 'gms-v83',
+  signal: abortController.signal,
+});
+
+for (const row of browse.records) {
+  console.log(row.key, row.name.state === 'known' ? row.name.value : row.key);
+  if (row.icon.state === 'known') image.src = itemIconUrl(releaseRootUrl, row.icon.value);
+}
+```
+
+It is exactly `openRelease(options)` → `openItemBuild(options.buildId)` → `loadBrowse()`:
+it adds no cache, no fallback build selection and no latest lookup. The read is
+build-scoped: it fetches only the browse packs named by that build's Item product
+manifest, and a build ID that the pinned release does not carry rejects with
+`UNKNOWN_BUILD` instead of falling back to another build. Each row is the compact
+Rust-owned browse record plus its stable public `key`; `scope` and `coverage` come from
+the verified packs, every pack must agree on `coverage`, and the roster must match the
+manifest's `totalEntityCount`, so a short roster never resolves. `fetch`, `signal`,
+`onRequest` and the validated `preloaded` release metadata behave exactly as they do on
+`openRelease`.
+
+Omitted row fields are coverage claims, not zeroes:
+
+- An omitted relationship count means zero recorded entities when
+  `coverage.relationships[key]` is `complete`. `unsupported` is not zero: it means the
+  producer cannot supply that relationship for this build. `partial` means the recorded
+  count is a lower bound, so `monster-drop` on `gms-v83` is `partial`.
+- An omitted `scroll.tier` is unresolved, not absent, when `coverage.scrollTier` is
+  `complete`; an omitted `scroll.cursed` means the Scroll has no cursed property.
+- `scroll.targets` are verified identities. `scroll.targetLabel` is a label derived from
+  the Scroll's name and is never an identity.
+
+`itemIconUrl(baseUrl, contentId)` resolves a Media blob through the same core path
+resolver as `resolveMediaUrl` and returns `<baseUrl>/media/images/<ab>/<contentId>.png`.
+It rejects any content ID that is not a 64-character lowercase SHA-256 digest with
+`SCHEMA_VALIDATION_ERROR`, so a row's `icon.value` can be used without building a
+make-believe descriptor.
+
 ## What each entry loads
 
 Monster catalog validation and the release/manifest/index validators are imported
@@ -73,12 +153,13 @@ operation that needs it, as a separate on-demand chunk:
 
 | Entry | Eager generated validators | Loaded on demand |
 | --- | --- | --- |
-| `/monsters` | release pin, release manifest, build index, product manifest, Monster catalog 1.x and 2.0 | Monster detail, location/relationship, core-relationship and evidence packs |
-| `/items`, `/equipment` | that domain's catalog, detail, relationship and evidence packs | — |
+| `/monsters` | release pin, release manifest, build index, product manifest, Monster catalog 1.x, 2.0 and 2.1 | Monster detail, location/relationship, core-relationship and evidence packs |
+| `/items` | product manifest only (every Item validator is on demand) | browse, catalog, detail, relationship and evidence packs, plus the release client behind `getItemBrowse` |
+| `/equipment` | that domain's catalog, detail, relationship and evidence packs | — |
 | `/quests` | none (Quest validators are always on demand) | catalog, browse, detail, relationship, auxiliary and evidence packs |
 | `/media` | that domain's catalog, detail packs | — |
 | `/release` | release pin, release manifest, build index, product manifest, Monster catalog (Monster is the release client's build selector) | Item, Equipment, Media, Quest and static-domain clients |
-| `.` and `/client` | every domain's eager validators (compatibility view) | Quest and Monster detail/relationship/evidence validators |
+| `.` and `/client` | every domain's eager validators (compatibility view) | every Item validator, plus Quest and Monster detail/relationship/evidence validators |
 
 A Monster-browse-only browser consumer therefore ships the release and Monster catalog
 code and nothing else; the repository's `tools/benchmark-bundle.mjs` measures it against

package/client/core.d.ts

@@ -118,7 +118,13 @@ export declare class MissingPageError extends StaticClientError {
 }
 export declare function normalizedBaseUrl(value: string | URL): URL;
 export declare function verifyBlob(bytes: Uint8Array, descriptor: IntegrityDescriptor): Promise<void>;
+export declare function resolveReleasePath(baseUrl: URL | string, path: string): string;
 export declare function resolveMediaUrl(baseUrl: URL | string, descriptor: IntegrityDescriptor): string;
+/**
+ * Resolve a Media content ID (the PNG's lowercase SHA-256 digest) to its blob URL under
+ * the release root. `subject` names the caller's field in the validation error.
+ */
+export declare function resolveMediaContentUrl(baseUrl: URL | string, contentId: string, subject: string): string;
 export declare function assertCompatibleManifest(manifest: ConnectedProductManifest | ReleaseManifest): number;
 export declare function createJsonFetcher(options: {
     readonly baseUrl: URL;

package/client/core.js

@@ -120,9 +120,22 @@ export async function verifyBlob(bytes, descriptor) {
         throw new IntegrityError(`Byte length mismatch for ${descriptor.path}: expected ${descriptor.byteLength}, got ${bytes.byteLength}`);
     }
 }
-export function resolveMediaUrl(baseUrl, descriptor) {
+export function resolveReleasePath(baseUrl, path) {
     const base = baseUrl instanceof URL ? baseUrl : normalizedBaseUrl(baseUrl);
-    return resolveDescriptorUrl(base, descriptor.path).toString();
+    return resolveDescriptorUrl(base, path).toString();
+}
+export function resolveMediaUrl(baseUrl, descriptor) {
+    return resolveReleasePath(baseUrl, descriptor.path);
+}
+/**
+ * Resolve a Media content ID (the PNG's lowercase SHA-256 digest) to its blob URL under
+ * the release root. `subject` names the caller's field in the validation error.
+ */
+export function resolveMediaContentUrl(baseUrl, contentId, subject) {
+    if (!/^[0-9a-f]{64}$/.test(contentId)) {
+        throw new SchemaValidationError(contentId, `${subject} content ID must be a SHA-256 hex digest`);
+    }
+    return resolveReleasePath(baseUrl, `media/images/${contentId.slice(0, 2)}/${contentId}.png`);
 }
 function parseJson(bytes, path) {
     try {

package/client/items.d.ts

@@ -1,14 +1,36 @@
+/**
+ * `@mapletip/data/items` — Item browse and Item product operations.
+ *
+ * Every Item validator is loaded on the first operation that needs it and the release
+ * client is imported on demand, so a browse-only consumer never downloads catalog,
+ * detail, relationship, evidence validators or the Monster client.
+ */
+import type { ItemBrowsePack, ItemBrowseCoverage, ItemBrowseRecord } from '../generated/item-browse-pack-2.d.ts';
 import type { ItemCatalog } from '../generated/item-catalog-2.d.ts';
 import type { ItemDetailRecord } from '../generated/item-detail-2.d.ts';
 import type { ItemRelationshipPage } from '../generated/item-relationship-pack-2.d.ts';
 import type { ItemEvidencePage } from '../generated/item-evidence-pack-2.d.ts';
-import { type GetRelationshipOptions, type OpenProductOptions, type OperationOptions, type StaticProductManifest, type VerifiedProductContext } from './core.js';
+import type { OpenReleaseOptions } from './release.js';
+import { type GetRelationshipOptions, type OpenProductOptions, type OperationOptions, type ProductScope, type StaticProductManifest, type VerifiedProductContext } from './core.js';
 export type StaticItemCatalog = ItemCatalog;
 export type StaticItemDetail = ItemDetailRecord;
 export type { GetRelationshipOptions };
+export type { ItemBrowsePack, ItemBrowseCoverage, ItemBrowseRecord };
+export type { OpenReleaseOptions };
+/** One browse row: the compact record plus its stable public key. */
+export type ItemBrowseRow = ItemBrowseRecord & {
+    readonly key: string;
+};
+/** The whole verified browse roster of one Item build. */
+export interface StaticItemBrowse {
+    readonly scope: ProductScope;
+    readonly coverage: ItemBrowseCoverage;
+    readonly records: readonly ItemBrowseRow[];
+}
 export interface StaticItemProductClient {
     readonly manifest: StaticProductManifest;
     loadCatalog(options?: OperationOptions): Promise<StaticItemCatalog>;
+    loadBrowse(options?: OperationOptions): Promise<StaticItemBrowse>;
     getDetail(key: string, options?: OperationOptions): Promise<StaticItemDetail>;
     getRelationshipPage(pageKey: string, options?: GetRelationshipOptions): Promise<ItemRelationshipPage>;
     getEvidencePage(pageKey: string, options?: OperationOptions): Promise<ItemEvidencePage>;
@@ -20,3 +42,17 @@ export declare function openItemProduct(options: OpenProductOptions): Promise<St
 export declare function isItemProductClient(client: {
     readonly manifest: StaticProductManifest;
 }): client is StaticItemProductClient;
+/** Options for the one-shot Item browse read: an opened release plus the build to read. */
+export type GetItemBrowseOptions = OpenReleaseOptions & {
+    readonly buildId: string;
+};
+/**
+ * Read one build's verified Item browse roster in a single call.
+ *
+ * Equivalent to `openRelease(options)` → `openItemBuild(options.buildId)` →
+ * `loadBrowse()`; it adds no caching, fallback or alternate data path. The release
+ * client is imported on demand so the Item browse entry stays narrow.
+ */
+export declare function getItemBrowse(options: GetItemBrowseOptions): Promise<StaticItemBrowse>;
+/** Resolve one Item icon blob URL from its content-addressed media digest. */
+export declare function itemIconUrl(baseUrl: URL | string, contentId: string): string;

package/client/items.js

@@ -1,41 +1,98 @@
-import validateItemCatalog from '../generated/item-catalog-2.validator.js';
-import validateItemDetail from '../generated/item-detail-2.validator.js';
-import validateItemDetailPack from '../generated/item-pack-2.validator.js';
-import validateItemRelationshipPack from '../generated/item-relationship-pack-2.validator.js';
-import validateItemEvidencePack from '../generated/item-evidence-pack-2.validator.js';
-import { MissingPageError, MissingRecordError, SchemaValidationError, ScopeError, UnsupportedProductError, memoized, openProductContext, rangeDescriptor, recordRangeDescriptor, } from './core.js';
+import { MissingPageError, MissingRecordError, SchemaValidationError, ScopeError, UnsupportedCapabilityError, UnsupportedProductError, lazyValidator, memoized, openProductContext, rangeDescriptor, recordRangeDescriptor, resolveMediaContentUrl, } from './core.js';
+const loadBrowsePackValidator = lazyValidator(() => import('../generated/item-browse-pack-2.validator.js'));
+const loadCatalogValidator = lazyValidator(() => import('../generated/item-catalog-2.validator.js'));
+const loadDetailValidator = lazyValidator(() => import('../generated/item-detail-2.validator.js'));
+const loadDetailPackValidator = lazyValidator(() => import('../generated/item-pack-2.validator.js'));
+const loadRelationshipPackValidator = lazyValidator(() => import('../generated/item-relationship-pack-2.validator.js'));
+const loadEvidencePackValidator = lazyValidator(() => import('../generated/item-evidence-pack-2.validator.js'));
 /** Build an Item client over an already verified product manifest. */
 export function itemProductClient(context) {
     const { manifest, fetchEnvelope } = context;
     if (manifest.productId !== 'items')
         throw new UnsupportedProductError(manifest.productId);
     let catalogPromise;
+    let browsePromise;
     const detailPackCache = new Map();
     const relationshipPackCache = new Map();
     const evidencePackCache = new Map();
     async function loadCatalog(operation) {
         if (!catalogPromise) {
-            catalogPromise = fetchEnvelope(manifest.catalog, 'catalog', validateItemCatalog, operation);
+            catalogPromise = (async () => {
+                const validator = await loadCatalogValidator();
+                return fetchEnvelope(manifest.catalog, 'catalog', validator, operation);
+            })();
             void catalogPromise.catch(() => { catalogPromise = undefined; });
         }
         return catalogPromise;
     }
+    async function loadBrowse(operation) {
+        const descriptors = manifest.browsePacks;
+        if (!descriptors || descriptors.length === 0) {
+            throw new UnsupportedCapabilityError('Item product manifest does not provide browse packs');
+        }
+        if (!browsePromise) {
+            browsePromise = (async () => {
+                const validator = await loadBrowsePackValidator();
+                const packs = await Promise.all(descriptors.map((descriptor) => (fetchEnvelope(descriptor, 'browse', validator, operation))));
+                const rows = [];
+                let previousKey;
+                const coverage = packs[0].coverage;
+                const coverageJson = JSON.stringify(coverage);
+                for (const [index, pack] of packs.entries()) {
+                    const descriptor = descriptors[index];
+                    const keys = Object.keys(pack.records);
+                    if (keys.length !== descriptor.count) {
+                        throw new SchemaValidationError(descriptor.path, `browse pack has ${keys.length} records but its descriptor declares ${descriptor.count}`);
+                    }
+                    const packCoverageJson = JSON.stringify(pack.coverage);
+                    if (packCoverageJson !== coverageJson) {
+                        throw new SchemaValidationError(descriptor.path, 'browse pack coverage does not match the first browse pack');
+                    }
+                    if (keys[0] !== descriptor.firstKey || keys.at(-1) !== descriptor.lastKey) {
+                        throw new SchemaValidationError(descriptor.path, `browse pack keys do not match the descriptor range ${descriptor.firstKey}..${descriptor.lastKey}`);
+                    }
+                    // One strictly increasing walk across packs rejects duplicate keys and
+                    // overlapping or out-of-order ranges.
+                    for (const key of keys) {
+                        const record = pack.records[key];
+                        if (!record) {
+                            throw new SchemaValidationError(descriptor.path, `browse pack is missing record ${key}`);
+                        }
+                        if (previousKey !== undefined && key <= previousKey) {
+                            throw new SchemaValidationError(descriptor.path, `browse record key ${key} is out of order`);
+                        }
+                        previousKey = key;
+                        rows.push({ ...record, key });
+                    }
+                }
+                if (rows.length !== manifest.totalEntityCount) {
+                    throw new SchemaValidationError(manifest.catalog.path, `browse roster has ${rows.length} rows but the manifest declares ${manifest.totalEntityCount}`);
+                }
+                return { scope: manifest.scope, coverage, records: rows };
+            })();
+            void browsePromise.catch(() => { browsePromise = undefined; });
+        }
+        return browsePromise;
+    }
     async function getDetail(key, operation) {
         const descriptor = recordRangeDescriptor(manifest.detailPacks, key, 'detail', 'Item');
-        const pack = await memoized(detailPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'detail', validateItemDetailPack, operation)));
+        const packValidator = await loadDetailPackValidator();
+        const pack = await memoized(detailPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'detail', packValidator, operation)));
         if (!Object.hasOwn(pack.records, key))
             throw new MissingRecordError(key, 'Item');
         const detail = pack.records[key];
         if (!detail)
             throw new MissingRecordError(key, 'Item');
-        if (!validateItemDetail(detail)) {
-            throw new SchemaValidationError(descriptor.path, JSON.stringify(validateItemDetail.errors ?? []));
+        const validator = await loadDetailValidator();
+        if (!validator(detail)) {
+            throw new SchemaValidationError(descriptor.path, JSON.stringify(validator.errors ?? []));
         }
         return detail;
     }
     async function getRelationshipPage(pageKey, operation) {
         const descriptor = rangeDescriptor(manifest.relationshipPacks, pageKey, 'relationship');
-        const pack = await memoized(relationshipPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'relationship', validateItemRelationshipPack, operation)));
+        const validator = await loadRelationshipPackValidator();
+        const pack = await memoized(relationshipPackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'relationship', validator, operation)));
         const page = pack.records[pageKey];
         if (!page)
             throw new MissingPageError(pageKey, 'relationship');
@@ -46,13 +103,14 @@ export function itemProductClient(context) {
     }
     async function getEvidencePage(pageKey, operation) {
         const descriptor = rangeDescriptor(manifest.evidencePacks ?? [], pageKey, 'evidence');
-        const pack = await memoized(evidencePackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'evidence', validateItemEvidencePack, operation)));
+        const validator = await loadEvidencePackValidator();
+        const pack = await memoized(evidencePackCache, descriptor.path, () => (fetchEnvelope(descriptor, 'evidence', validator, operation)));
         const page = pack.records[pageKey];
         if (!page)
             throw new MissingPageError(pageKey, 'evidence');
         return page;
     }
-    return { manifest, loadCatalog, getDetail, getRelationshipPage, getEvidencePage };
+    return { manifest, loadCatalog, loadBrowse, getDetail, getRelationshipPage, getEvidencePage };
 }
 /** Open one pinned Item product. */
 export async function openItemProduct(options) {
@@ -61,3 +119,20 @@ export async function openItemProduct(options) {
 export function isItemProductClient(client) {
     return client.manifest.productId === 'items';
 }
+/**
+ * Read one build's verified Item browse roster in a single call.
+ *
+ * Equivalent to `openRelease(options)` → `openItemBuild(options.buildId)` →
+ * `loadBrowse()`; it adds no caching, fallback or alternate data path. The release
+ * client is imported on demand so the Item browse entry stays narrow.
+ */
+export async function getItemBrowse(options) {
+    const { openRelease } = await import('./release.js');
+    const release = await openRelease(options);
+    const items = await release.openItemBuild(options.buildId);
+    return items.loadBrowse({ signal: options.signal });
+}
+/** Resolve one Item icon blob URL from its content-addressed media digest. */
+export function itemIconUrl(baseUrl, contentId) {
+    return resolveMediaContentUrl(baseUrl, contentId, 'Item icon');
+}

package/client/monster-client.d.ts

@@ -8,6 +8,7 @@
  */
 import type { MonsterCatalog } from '../generated/monster-catalog.d.ts';
 import type { MonsterCatalogV2 } from '../generated/monster-catalog-2.d.ts';
+import type { MonsterCatalogV2_1 } from '../generated/monster-catalog-2-1.d.ts';
 import type { MonsterDetailRecord, PageDescriptor } from '../generated/monster-detail.d.ts';
 import type { MonsterDetailRecordV2 } from '../generated/monster-detail-2.d.ts';
 import type { MonsterEvidencePage } from '../generated/monster-evidence-pack.d.ts';
@@ -15,7 +16,11 @@ import type { MonsterEvidencePageV2 } from '../generated/monster-evidence-pack-2
 import type { MonsterLocationOccurrence } from '../generated/monster-relationship-pack.d.ts';
 import type { MonsterCoreRelationshipPackV2 } from '../generated/monster-core-relationship-pack-2.d.ts';
 import { type OpenProductOptions, type OperationOptions, type StaticProductManifest, type VerifiedProductContext } from './core.js';
-export type StaticMonsterCatalog = MonsterCatalog | MonsterCatalogV2;
+/**
+ * A verified Monster catalog. Contract 2.1 records carry `sprite`, a Media content ID
+ * fact for the monster's representative image; 2.0 and 1.x records have none.
+ */
+export type StaticMonsterCatalog = MonsterCatalog | MonsterCatalogV2 | MonsterCatalogV2_1;
 export type StaticMonsterDetail = MonsterDetailRecord | MonsterDetailRecordV2;
 export type StaticMonsterEvidencePage = MonsterEvidencePage | MonsterEvidencePageV2;
 export interface StaticProductClient {

package/client/monster-client.js

@@ -1,6 +1,19 @@
 import validateCatalog from '../generated/monster-catalog.validator.js';
 import validateCatalogV2 from '../generated/monster-catalog-2.validator.js';
+import validateCatalogV2_1 from '../generated/monster-catalog-2-1.validator.js';
 import { MissingPageError, MissingRecordError, SchemaValidationError, UnsupportedProductError, assertEnvelopeVersion, assertSameScope, lazyValidator, memoized, openProductContext, rangeDescriptor, recordRangeDescriptor, } from './core.js';
+/**
+ * Contract-2 catalog validator that picks the revision's strict schema from the document's
+ * own `contractVersion`. Unsupported revisions fail the 2.0 schema with a typed error.
+ */
+const validateCatalogRevision = Object.assign((data) => {
+    const validator = (data?.contractVersion === '2.1'
+        ? validateCatalogV2_1
+        : validateCatalogV2);
+    const valid = validator(data);
+    validateCatalogRevision.errors = validator.errors;
+    return valid;
+}, { errors: undefined });
 const loadDetailPack = lazyValidator(() => import('../generated/monster-pack.validator.js'));
 const loadDetail = lazyValidator(() => import('../generated/monster-detail.validator.js'));
 const loadDetailPackV2 = lazyValidator(() => import('../generated/monster-pack-2.validator.js'));
@@ -26,7 +39,7 @@ export function monsterProductClient(context) {
     async function loadCatalog(operation) {
         if (!catalogPromise) {
             catalogPromise = contract2
-                ? fetchEnvelope(manifest.catalog, 'catalog', validateCatalogV2, operation)
+                ? fetchEnvelope(manifest.catalog, 'catalog', validateCatalogRevision, operation)
                 : fetchEnvelope(manifest.catalog, 'catalog', validateCatalog, operation);
             void catalogPromise.catch(() => { catalogPromise = undefined; });
         }

package/client/monsters.d.ts

@@ -1,14 +1,9 @@
-/**
- * `@mapletip/data/monsters` — Monster browse and Monster product operations.
- *
- * This entry pulls the verified release core and the Monster client (with its catalog
- * validators) and nothing else: Item, Equipment, Media, Quest, static-domain code and
- * Monster detail/relationship/evidence validators stay out of the initial graph.
- */
+import type { MonsterCatalogV2_1 } from '../generated/monster-catalog-2-1.d.ts';
 import type { StaticMonsterCatalog } from './monster-client.js';
 import { type OpenReleaseOptions } from './release.js';
 export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
 export type { StaticMonsterCatalog, StaticMonsterDetail, StaticMonsterEvidencePage, StaticProductClient, } from './monster-client.js';
+export type { MonsterCatalogV2_1 };
 export type { OpenReleaseOptions };
 /** Options for the one-shot Monster catalog read: an opened release plus the build to read. */
 export type GetMonsterBrowseOptions = OpenReleaseOptions & {
@@ -22,3 +17,16 @@ export type GetMonsterBrowseOptions = OpenReleaseOptions & {
  * lower-level release client when several domain reads share one release.
  */
 export declare function getMonsterBrowse(options: GetMonsterBrowseOptions): Promise<StaticMonsterCatalog>;
+/**
+ * Resolve one Monster sprite blob URL from a catalog row's known `sprite` content ID.
+ *
+ * The blob lives under the same release root as the catalog, so no Media product is
+ * opened. Throws `SchemaValidationError` for anything but a lowercase SHA-256 digest.
+ */
+export declare function monsterSpriteUrl(baseUrl: URL | string, contentId: string): string;
+/**
+ * Narrow a verified catalog to contract 2.1, whose every row carries `sprite`. Earlier
+ * pins return 1.x or 2.0 catalogs without it; the loose 1.x type keeps a plain field
+ * check from narrowing.
+ */
+export declare function hasMonsterSprites(catalog: StaticMonsterCatalog): catalog is MonsterCatalogV2_1;

package/client/monsters.js

@@ -1,3 +1,11 @@
+/**
+ * `@mapletip/data/monsters` — Monster browse and Monster product operations.
+ *
+ * This entry pulls the verified release core and the Monster client (with its catalog
+ * validators) and nothing else: Item, Equipment, Media, Quest, static-domain code and
+ * Monster detail/relationship/evidence validators stay out of the initial graph.
+ */
+import { resolveMediaContentUrl } from './core.js';
 import { openRelease } from './release.js';
 export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
 /**
@@ -12,3 +20,20 @@ export async function getMonsterBrowse(options) {
     const monster = await release.openBuild(options.buildId);
     return monster.loadCatalog({ signal: options.signal });
 }
+/**
+ * Resolve one Monster sprite blob URL from a catalog row's known `sprite` content ID.
+ *
+ * The blob lives under the same release root as the catalog, so no Media product is
+ * opened. Throws `SchemaValidationError` for anything but a lowercase SHA-256 digest.
+ */
+export function monsterSpriteUrl(baseUrl, contentId) {
+    return resolveMediaContentUrl(baseUrl, contentId, 'Monster sprite');
+}
+/**
+ * Narrow a verified catalog to contract 2.1, whose every row carries `sprite`. Earlier
+ * pins return 1.x or 2.0 catalogs without it; the loose 1.x type keeps a plain field
+ * check from narrowing.
+ */
+export function hasMonsterSprites(catalog) {
+    return catalog.format === 'mapletip.monster-catalog-2' && catalog.contractVersion === '2.1';
+}

package/client/static-client.d.ts

@@ -17,8 +17,8 @@ export { ContractVersionError, IntegrityError, InvalidJsonError, InvalidPathErro
 export type { GetRelationshipOptions, IntegrityDescriptor, OpenProductOptions, OperationOptions, ProductIdentity, ProductManifestDescriptor, ProductScope, RequestKind, RequestLogEntry, RequestLogHook, StaticProductManifest, } from './core.js';
 export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
 export type { StaticMonsterCatalog, StaticMonsterDetail, StaticMonsterEvidencePage, StaticProductClient, } from './monster-client.js';
-export { isItemProductClient, openItemProduct } from './items.js';
-export type { StaticItemCatalog, StaticItemDetail, StaticItemProductClient } from './items.js';
+export { getItemBrowse, isItemProductClient, itemIconUrl, openItemProduct } from './items.js';
+export type { GetItemBrowseOptions, ItemBrowseCoverage, ItemBrowsePack, ItemBrowseRecord, ItemBrowseRow, StaticItemBrowse, StaticItemCatalog, StaticItemDetail, StaticItemProductClient, } from './items.js';
 export { isEquipmentProductClient, openEquipmentProduct } from './equipment.js';
 export type { StaticEquipmentCatalog, StaticEquipmentDetail, StaticEquipmentProductClient, } from './equipment.js';
 export { isMediaProductClient, openMediaProduct } from './media.js';
@@ -28,7 +28,7 @@ export type { QuestAuxiliaryPack, QuestAuxiliaryPage, QuestBrowsePack, QuestBrow
 export type { StaticDomainCatalog, StaticDomainCatalogRecord, StaticDomainDetailRecord, StaticDomainFactState, StaticDomainProductClient, StaticDomainSourceIdentity, } from './static-domains.js';
 export { openRelease, resolveTargetAvailability } from './release.js';
 export type { OpenReleaseOptions, ReleaseProductDescriptor, StaticReleaseBuild, StaticReleaseClient, TargetAvailability, } from './release.js';
-export { getMonsterBrowse } from './monsters.js';
+export { getMonsterBrowse, hasMonsterSprites, monsterSpriteUrl } from './monsters.js';
 export type { GetMonsterBrowseOptions } from './monsters.js';
 export type AnyProductClient = StaticProductClient | StaticMediaProductClient | StaticQuestProductClient | StaticItemProductClient | StaticEquipmentProductClient | StaticDomainProductClient;
 /**

package/client/static-client.js

@@ -15,12 +15,12 @@ import { questProductClient } from './quests.js';
 import { staticDomainProductClient } from './static-domains.js';
 export { ContractVersionError, IntegrityError, InvalidJsonError, InvalidPathError, MissingPageError, MissingRecordError, RequestError, SchemaValidationError, ScopeError, SecureContextRequiredError, StaticClientError, UnknownBuildError, UnsupportedCapabilityError, UnsupportedProductError, resolveMediaUrl, verifyBlob, } from './core.js';
 export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
-export { isItemProductClient, openItemProduct } from './items.js';
+export { getItemBrowse, isItemProductClient, itemIconUrl, openItemProduct } from './items.js';
 export { isEquipmentProductClient, openEquipmentProduct } from './equipment.js';
 export { isMediaProductClient, openMediaProduct } from './media.js';
 export { isQuestProductClient, openQuestProduct } from './quests.js';
 export { openRelease, resolveTargetAvailability } from './release.js';
-export { getMonsterBrowse } from './monsters.js';
+export { getMonsterBrowse, hasMonsterSprites, monsterSpriteUrl } from './monsters.js';
 /**
  * Open one pinned product of any supported domain.
  *