@mapletip/data 0.2.0 → 0.5.0

package/README.md

@@ -55,6 +55,124 @@ 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 revisions `2.1` or `2.2`. `@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.
+
+### Monster drops and locations
+
+Monster catalog `2.2` keeps these summaries on every Monster row. The catalog-level
+`browseCoverage` carries the shared witnesses and conventions: `nativeDropsAbsentCoverageKey`
+is present exactly when at least one native drop row is `absent`; `historicalDrops` says whether
+the build has a historical overlay; `locationsAbsentCoverageKey` is present exactly when at
+least one location row is `absent`; and `locationScope` is `client-placements`. An absent row
+does not repeat the catalog coverage key.
+
+`drops.native` describes evidence from the selected build. Its `lowerBound: true` marker
+says a `known` count is a lower bound while native source coverage is partial.
+`unknown` means the count could not be established; it does not mean zero.
+`drops.historical` is present only when the build
+advertises historical overlay support. CW Launch reports native data separately from
+its historical entries, so a Monster can have no native data and still have historical
+drop assertions. GMS v83 reports historical drops as unsupported.
+
+The drop browse artifact stores each distinct item once in its sorted `items[]` table.
+Each record entry's `item` is an index into that table. Native entries describe this
+build; historical entries also carry `sourceBuild` and `confidence`. A resolved
+Equipment category is `{ kind: "equip-slot", code }`; display labels for that code come
+from the same build's Equipment product slot labels. Other resolved item categories use
+`{ kind: "item-class", value }`, where the value is `ItemBrowseClass`. Unresolved item
+references use `{ kind: "unknown" }`.
+
+`detail.dropEvidence.state` keeps its existing native-only meaning. It describes the
+native evidence collection for the Monster and is not changed by historical overlay
+assertions. Read the compact historical assertions from the drop browse artifact:
+
+```ts
+import { getMonsterDropBrowse } from '@mapletip/data/monsters';
+
+const dropBrowse = await getMonsterDropBrowse({
+  baseUrl: releaseRootUrl,
+  pin: releasePin,
+  buildId: 'cw-launch',
+});
+const itemKey = 'item-0123456789abcdef';
+const monstersWithItem = Object.entries(dropBrowse.records)
+  .filter(([, record]) => record?.entries.some((entry) => {
+    const item = dropBrowse.items[entry.item];
+    return item?.itemRef.state === 'resolved' && item.itemRef.key === itemKey;
+  }))
+  .map(([monsterKey]) => monsterKey);
+```
+
+Location summaries count client map placements, not live spawn rates. `known` carries
+distinct map and placement counts; `absent` carries neither count and uses the
+catalog-level coverage key; `unresolved` carries counts for the resolved portion when
+some placements could not be attributed. Location browse entries carry the public
+`mapKey`, map name and placement count, with no coordinates or media references.
+`regionCode` is the raw source classification code, not a geographic region.
+
+Filter by map key, then resolve that map's minimap through the same build's Media product.
+The Media record key is the map key; its `map.minimap` descriptor resolves to a
+content-addressed image URL:
+
+```ts
+import { getMonsterLocationBrowse } from '@mapletip/data/monsters';
+import { openRelease } from '@mapletip/data/release';
+import { resolveMediaUrl } from '@mapletip/data/media';
+
+const buildId = 'gms-v83';
+const locationBrowse = await getMonsterLocationBrowse({
+  baseUrl: releaseRootUrl,
+  pin: releasePin,
+  buildId,
+});
+const mapKey = 'map-0123456789abcdef';
+const monstersOnMap = Object.entries(locationBrowse.records)
+  .filter(([, record]) => record?.entries.some((entry) => entry.mapKey === mapKey))
+  .map(([monsterKey]) => monsterKey);
+
+const release = await openRelease({ baseUrl: releaseRootUrl, pin: releasePin });
+const media = await release.openMediaBuild(buildId);
+const mapMedia = (await media.loadCatalog()).records.find((record) => record.key === mapKey);
+const minimap = mapMedia?.media['map.minimap'];
+const minimapUrl = minimap?.state === 'known'
+  ? resolveMediaUrl(releaseRootUrl, minimap.value)
+  : undefined;
+```
+
+`0.3.0` reads catalog revisions `2.0` and `2.1` but rejects `2.2` with a typed
+`SCHEMA_VALIDATION_ERROR`. Use `0.4.0` before adopting a release with drop and location
+browse summaries.
+
 `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
@@ -113,6 +231,66 @@ It rejects any content ID that is not a 64-character lowercase SHA-256 digest wi
 `SCHEMA_VALIDATION_ERROR`, so a row's `icon.value` can be used without building a
 make-believe descriptor.
 
+### Player facts and related identities
+
+Item Browse 2.1 adds sparse typed player facts. An omitted sparse fact means its value is
+unknown, unless that field's per-build coverage says `unsupported`; it does not mean
+zero. A recorded `sellPrice: 0` is a real zero. Use
+`hasItemPlayerFacts` to narrow a browse result before relying on the 2.1 coverage block;
+older pinned 2.0 products remain readable. `coverage.playerFacts.requirementJobs` is
+`unsupported` in both current builds because neither has a normalized non-equipment job
+requirement source. NPC shop purchase prices are deferred: sell price is not a shop price.
+
+`requirement.level` is the item's direct use-level requirement. The separate
+`levelRange` fact carries GMS Monster Crystal `monsterLevelMin`/`monsterLevelMax` and
+Secret Crystal `requirementLevelDelta`; these values are never folded into
+`requirement.level`. Recovery keeps flat `recovery.hp`/`mp` distinct from percentage
+`recovery.hpPercent`/`mpPercent`. Buff effects use the closed `ItemBrowseBuffStat`
+vocabulary, and unknown source `spec` keys fail the publication gate unless they have
+an explicit exclusion.
+
+Related identities are stored in one lazy roster artifact per relationship kind. The
+Items manifest pins each artifact by digest and byte length. In a roster,
+`targets` is the target index table and `records[itemKey]` contains indices into that
+table. Load only the kind needed for the current view. For example, this resolves the
+`Dropped by` names for one item without loading all seven rosters:
+
+```ts
+import {
+  getItemBrowse,
+  getItemRelatedEntities,
+  hasItemPlayerFacts,
+} from '@mapletip/data/items';
+import type { GetItemBrowseOptions } from '@mapletip/data/items';
+
+declare const releaseRootUrl: GetItemBrowseOptions['baseUrl'];
+declare const releasePin: GetItemBrowseOptions['pin'];
+
+const browse = await getItemBrowse({
+  baseUrl: releaseRootUrl,
+  pin: releasePin,
+  buildId: 'gms-v83',
+});
+if (!hasItemPlayerFacts(browse)) throw new Error('this pin predates Item player facts');
+
+const item = browse.records.find((row) => row.sourceId === '02022001');
+if (!item) throw new Error('item is not present in this build');
+const roster = await getItemRelatedEntities({
+  baseUrl: releaseRootUrl,
+  pin: releasePin,
+  buildId: 'gms-v83',
+  kind: 'monster-drop',
+});
+const droppedBy = (roster.records[item.key] ?? []).flatMap((targetIndex) => {
+  const target = roster.targets[targetIndex];
+  return target ? [{ key: target.key, name: target.displayName ?? target.key }] : [];
+});
+```
+
+The `droppedBy` result can be rendered as the row's `Dropped by` names. Target names may
+be unknown, in which case the stable target key remains available. The roster read is
+digest-verified, build-scoped, uncached and has no fallback to another build.
+
 ## What each entry loads
 
 Monster catalog validation and the release/manifest/index validators are imported
@@ -121,8 +299,8 @@ 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` | product manifest only (every Item validator is on demand) | browse, catalog, detail, relationship and evidence packs, plus the release client behind `getItemBrowse` |
+| `/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, per-kind related-entity roster, catalog, detail, relationship and evidence packs, plus the release client behind `getItemBrowse` and `getItemRelatedEntities` |
 | `/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 | — |
@@ -256,3 +434,27 @@ const evPage = await client.getEvidencePage('quest-ev-1000');
 
 The Quest client supports lazy per-operation validator loading via dynamic `import()` to ensure that only the validator required for a specific operation is fetched. Browse records and detail records are lazily addressed through bounded key-range descriptors without per-record eager loads or mandatory catalog fetching for direct detail lookups.
 
+## Map geography
+
+Map geography uses a build-scoped, digest-verified read model. `getMapGeography` reads that model from the `maps` product; `openMapProduct` returns a product with `loadGeography()`, and `release.openDomainBuild(buildId, 'maps')` provides the same operation when an opened release is reused. Map catalog rows carry compact geography keys and provenance, while the geography model stores the labels once.
+
+The derivation layers run in order: reviewed placements, the build-family region allowlist, area names from Map marks (Hidden Street marks are excluded), then collection classification. Maps with no applicable layer have provenance `none`. Provenance values are `reviewed-overlay`, `source-region-allowlist`, `source-map-mark`, `source-classification`, and `none`.
+
+Reviewed placement status `supported` means local witnesses support the entrance and placement. Citation register entries that could not be fetched remain inactive; they are not treated as verified external evidence. The carried-over placements in these builds use `supported` status.
+
+Geography keys are stable filters: `region:<slug>`, `area:<region-slug>/<area-slug>`, and `collection:<slug>`. Monster catalog 2.3 rows contain the union of their location entries' region and location keys. A Region filter can use those keys directly:
+
+```ts
+import { getMonsterBrowse, hasMonsterGeography } from '@mapletip/data/monsters';
+
+const catalog = await getMonsterBrowse({
+  baseUrl: releaseRootUrl,
+  pin: releasePin,
+  buildId: 'gms-v83',
+});
+if (!hasMonsterGeography(catalog)) throw new Error('This release predates Monster geography');
+
+const regionKey = 'region:henesys';
+const monstersInRegion = catalog.records.filter((row) => row.geography.regionKeys.includes(regionKey));
+```
+

package/client/contract-compatibility.mjs

@@ -8,11 +8,16 @@ const MINIMUM_VERSION_BY_CAPABILITY = new Map([
   ['product-input-identity-v1', { major: 1, minor: 2 }],
   ['release-manifest-v1', { major: 1, minor: 2 }],
   ['monster-core-v1', { major: 2, minor: 0 }],
+  ['monster-drop-browse-v1', { major: 2, minor: 0 }],
+  ['monster-location-browse-v1', { major: 2, minor: 0 }],
+  ['item-player-facts-v1', { major: 2, minor: 0 }],
+  ['item-related-entities-v1', { major: 2, minor: 0 }],
   ['quests-v1', { major: 2, minor: 0 }],
   ['items-v1', { major: 2, minor: 0 }],
   ['equipment-v1', { major: 2, minor: 0 }],
   ['media-v1', { major: 2, minor: 0 }],
   ['maps-v1', { major: 2, minor: 0 }],
+  ['map-geography-v1', { major: 2, minor: 0 }],
   ['npcs-v1', { major: 2, minor: 0 }],
   ['reactors-v1', { major: 2, minor: 0 }],
   ['skills-v1', { major: 2, minor: 0 }],
@@ -33,11 +38,16 @@ const supportedClientCapabilities = new Set([
   'product-input-identity-v1',
   'release-manifest-v1',
   'monster-core-v1',
+  'monster-drop-browse-v1',
+  'monster-location-browse-v1',
+  'item-player-facts-v1',
+  'item-related-entities-v1',
   'quests-v1',
   'items-v1',
   'equipment-v1',
   'media-v1',
   'maps-v1',
+  'map-geography-v1',
   'npcs-v1',
   'reactors-v1',
   'skills-v1',

package/client/core.d.ts

@@ -120,6 +120,11 @@ 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

@@ -127,6 +127,16 @@ export function resolveReleasePath(baseUrl, path) {
 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 {
         return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));

package/client/items.d.ts

@@ -5,7 +5,8 @@
  * 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 { ItemBrowsePack, ItemBrowseCoverage, ItemBrowsePlayerFactCoverage, ItemBrowseBuff, ItemBrowseBuffEffect, ItemBrowseBuffStat, ItemBrowseBuffUnit, ItemBrowseCoverageState, ItemBrowseJobFamily, ItemBrowseLevelRange, ItemBrowseRecovery, ItemBrowseRequirement, ItemBrowseRecord } from '../generated/item-browse-pack-2.d.ts';
+import type { ItemBrowseRelationshipKind, ItemRelatedEntityBrowsePack, ItemRelatedEntityTarget } from '../generated/item-related-entity-browse-1.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';
@@ -15,22 +16,37 @@ import { type GetRelationshipOptions, type OpenProductOptions, type OperationOpt
 export type StaticItemCatalog = ItemCatalog;
 export type StaticItemDetail = ItemDetailRecord;
 export type { GetRelationshipOptions };
-export type { ItemBrowsePack, ItemBrowseCoverage, ItemBrowseRecord };
+export type { ItemBrowsePack, ItemBrowseCoverage, ItemBrowsePlayerFactCoverage, ItemBrowseBuff, ItemBrowseBuffEffect, ItemBrowseBuffStat, ItemBrowseBuffUnit, ItemBrowseCoverageState, ItemBrowseJobFamily, ItemBrowseLevelRange, ItemBrowseRecovery, ItemBrowseRequirement, ItemBrowseRecord, ItemBrowseRelationshipKind, ItemRelatedEntityBrowsePack, ItemRelatedEntityTarget, };
 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 {
+/** Verified Item Browse 2.0, retained for older pinned products. */
+export interface StaticItemBrowseV2_0 {
+    readonly contractVersion: '2.0';
+    readonly scope: ProductScope;
+    readonly coverage: Omit<ItemBrowseCoverage, 'playerFacts'>;
+    readonly records: readonly ItemBrowseRow[];
+}
+/** Verified Item Browse 2.1 with its per-build player-fact coverage. */
+export interface StaticItemBrowseV2_1 {
+    readonly contractVersion: '2.1';
     readonly scope: ProductScope;
-    readonly coverage: ItemBrowseCoverage;
+    readonly coverage: ItemBrowseCoverage & {
+        readonly playerFacts: ItemBrowsePlayerFactCoverage;
+    };
     readonly records: readonly ItemBrowseRow[];
 }
+/** The whole verified browse roster of one Item build. */
+export type StaticItemBrowse = StaticItemBrowseV2_0 | StaticItemBrowseV2_1;
+/** Narrow an Item browse result to contract 2.1, which carries player-fact coverage. */
+export declare function hasItemPlayerFacts(browse: StaticItemBrowse): browse is StaticItemBrowseV2_1;
 export interface StaticItemProductClient {
     readonly manifest: StaticProductManifest;
     loadCatalog(options?: OperationOptions): Promise<StaticItemCatalog>;
     loadBrowse(options?: OperationOptions): Promise<StaticItemBrowse>;
+    loadRelatedEntities(kind: ItemBrowseRelationshipKind, options?: OperationOptions): Promise<ItemRelatedEntityBrowsePack>;
     getDetail(key: string, options?: OperationOptions): Promise<StaticItemDetail>;
     getRelationshipPage(pageKey: string, options?: GetRelationshipOptions): Promise<ItemRelationshipPage>;
     getEvidencePage(pageKey: string, options?: OperationOptions): Promise<ItemEvidencePage>;
@@ -54,5 +70,12 @@ export type GetItemBrowseOptions = OpenReleaseOptions & {
  * client is imported on demand so the Item browse entry stays narrow.
  */
 export declare function getItemBrowse(options: GetItemBrowseOptions): Promise<StaticItemBrowse>;
+/** Options for one verified, one-shot related-entity roster read. */
+export type GetItemRelatedEntitiesOptions = OpenReleaseOptions & {
+    readonly buildId: string;
+    readonly kind: ItemBrowseRelationshipKind;
+};
+/** Read one build's manifest-pinned roster for exactly one Item relationship kind. */
+export declare function getItemRelatedEntities(options: GetItemRelatedEntitiesOptions): Promise<ItemRelatedEntityBrowsePack>;
 /** 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,5 +1,10 @@
-import { MissingPageError, MissingRecordError, SchemaValidationError, ScopeError, UnsupportedCapabilityError, UnsupportedProductError, lazyValidator, memoized, openProductContext, rangeDescriptor, recordRangeDescriptor, resolveReleasePath, } from './core.js';
+import { MissingPageError, MissingRecordError, SchemaValidationError, ScopeError, UnsupportedCapabilityError, UnsupportedProductError, assertSameScope, lazyValidator, memoized, openProductContext, rangeDescriptor, recordRangeDescriptor, resolveMediaContentUrl, } from './core.js';
+/** Narrow an Item browse result to contract 2.1, which carries player-fact coverage. */
+export function hasItemPlayerFacts(browse) {
+    return browse.contractVersion === '2.1' && browse.coverage.playerFacts !== undefined;
+}
 const loadBrowsePackValidator = lazyValidator(() => import('../generated/item-browse-pack-2.validator.js'));
+const loadRelatedEntityBrowseValidator = lazyValidator(() => import('../generated/item-related-entity-browse-1.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'));
@@ -7,7 +12,7 @@ const loadRelationshipPackValidator = lazyValidator(() => import('../generated/i
 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;
+    const { manifest, fetchJson, fetchEnvelope } = context;
     if (manifest.productId !== 'items')
         throw new UnsupportedProductError(manifest.productId);
     let catalogPromise;
@@ -37,9 +42,13 @@ export function itemProductClient(context) {
                 const rows = [];
                 let previousKey;
                 const coverage = packs[0].coverage;
+                const contractVersion = packs[0].contractVersion;
                 const coverageJson = JSON.stringify(coverage);
                 for (const [index, pack] of packs.entries()) {
                     const descriptor = descriptors[index];
+                    if (pack.contractVersion !== contractVersion) {
+                        throw new SchemaValidationError(descriptor.path, 'browse pack contract version does not match the first browse pack');
+                    }
                     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}`);
@@ -68,12 +77,51 @@ export function itemProductClient(context) {
                 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 };
+                if (contractVersion === '2.1') {
+                    const playerFacts = coverage.playerFacts;
+                    if (!playerFacts) {
+                        throw new SchemaValidationError(descriptors[0].path, 'Item Browse 2.1 is missing player-fact coverage');
+                    }
+                    return {
+                        contractVersion,
+                        scope: manifest.scope,
+                        coverage: { ...coverage, playerFacts },
+                        records: rows,
+                    };
+                }
+                if (contractVersion === '2.0') {
+                    if ((manifest.requiredClientCapabilities ?? []).includes('item-player-facts-v1')) {
+                        throw new SchemaValidationError(descriptors[0].path, 'Item product requires player facts but the browse pack is contract 2.0');
+                    }
+                    const { playerFacts: _playerFacts, ...legacyCoverage } = coverage;
+                    return { contractVersion, scope: manifest.scope, coverage: legacyCoverage, records: rows };
+                }
+                throw new SchemaValidationError(descriptors[0].path, `unsupported Item Browse contract ${contractVersion}`);
             })();
             void browsePromise.catch(() => { browsePromise = undefined; });
         }
         return browsePromise;
     }
+    async function loadRelatedEntities(kind, operation) {
+        if (!(manifest.requiredClientCapabilities ?? []).includes('item-related-entities-v1')) {
+            throw new UnsupportedCapabilityError('Item product manifest does not require item-related-entities-v1');
+        }
+        const descriptor = manifest.relatedEntityBrowsePacks?.[kind];
+        if (!descriptor) {
+            throw new UnsupportedCapabilityError(`Item product manifest does not provide ${kind} related entities`);
+        }
+        const validator = await loadRelatedEntityBrowseValidator();
+        const raw = await fetchJson(descriptor, 'browse', operation);
+        if (!validator(raw)) {
+            throw new SchemaValidationError(descriptor.path, JSON.stringify(validator.errors ?? []));
+        }
+        const pack = raw;
+        assertSameScope(pack.scope, manifest.scope, descriptor.path);
+        if (pack.relationshipKind !== kind) {
+            throw new SchemaValidationError(descriptor.path, `related-entity roster kind ${pack.relationshipKind} does not match requested ${kind}`);
+        }
+        return pack;
+    }
     async function getDetail(key, operation) {
         const descriptor = recordRangeDescriptor(manifest.detailPacks, key, 'detail', 'Item');
         const packValidator = await loadDetailPackValidator();
@@ -110,7 +158,7 @@ export function itemProductClient(context) {
             throw new MissingPageError(pageKey, 'evidence');
         return page;
     }
-    return { manifest, loadCatalog, loadBrowse, getDetail, getRelationshipPage, getEvidencePage };
+    return { manifest, loadCatalog, loadBrowse, loadRelatedEntities, getDetail, getRelationshipPage, getEvidencePage };
 }
 /** Open one pinned Item product. */
 export async function openItemProduct(options) {
@@ -132,10 +180,14 @@ export async function getItemBrowse(options) {
     const items = await release.openItemBuild(options.buildId);
     return items.loadBrowse({ signal: options.signal });
 }
+/** Read one build's manifest-pinned roster for exactly one Item relationship kind. */
+export async function getItemRelatedEntities(options) {
+    const { openRelease } = await import('./release.js');
+    const release = await openRelease(options);
+    const items = await release.openItemBuild(options.buildId);
+    return items.loadRelatedEntities(options.kind, { signal: options.signal });
+}
 /** Resolve one Item icon blob URL from its content-addressed media digest. */
 export function itemIconUrl(baseUrl, contentId) {
-    if (!/^[0-9a-f]{64}$/.test(contentId)) {
-        throw new SchemaValidationError(contentId, 'Item icon content ID must be a SHA-256 hex digest');
-    }
-    return resolveReleasePath(baseUrl, `media/images/${contentId.slice(0, 2)}/${contentId}.png`);
+    return resolveMediaContentUrl(baseUrl, contentId, 'Item icon');
 }

package/client/map-geography.d.ts

@@ -0,0 +1,4 @@
+export type { MapGeographyFact, MapGeographyProvenance, MapGeographyReviewStatus, } from '../generated/map-catalog-2-1.d.ts';
+export type { MapGeographyArea, MapGeographyCitation, MapGeographyCollection, MapGeographyEntryPoint, MapGeographyModel, MapGeographyRegion, MapGeographyReviewedPlacement, MapGeographyWitnessCount, } from '../generated/map-geography.d.ts';
+export { default as validateMapCatalogV2_1 } from '../generated/map-catalog-2-1.validator.js';
+export { default as validateMapGeography } from '../generated/map-geography.validator.js';

package/client/map-geography.js

@@ -0,0 +1,2 @@
+export { default as validateMapCatalogV2_1 } from '../generated/map-catalog-2-1.validator.js';
+export { default as validateMapGeography } from '../generated/map-geography.validator.js';

package/client/maps.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@mapletip/data/maps` — verified Map geography and Map catalog reads.
+ */
+import { isMapGeographyModel, type MapGeographyModel, type StaticDomainProductClient } from './static-domains.js';
+import { type OpenProductOptions, type StaticProductManifest } from './core.js';
+import { type OpenReleaseOptions } from './release.js';
+export { isMapGeographyModel };
+export type { MapGeographyModel, StaticDomainProductClient };
+export type StaticMapProductClient = Omit<StaticDomainProductClient, 'manifest'> & {
+    readonly manifest: StaticProductManifest & {
+        readonly productId: 'maps';
+    };
+};
+/** Open a pinned Maps domain product directly. */
+export declare function openMapProduct(options: OpenProductOptions): Promise<StaticMapProductClient>;
+export declare function isMapProductClient(product: StaticDomainProductClient): product is StaticMapProductClient;
+/** Options for the one-shot, manifest-pinned geography model read. */
+export type GetMapGeographyOptions = OpenReleaseOptions & {
+    readonly buildId: string;
+};
+/** Read the selected build's digest-verified Map geography model. */
+export declare function getMapGeography(options: GetMapGeographyOptions): Promise<MapGeographyModel>;

package/client/maps.js

@@ -0,0 +1,25 @@
+/**
+ * `@mapletip/data/maps` — verified Map geography and Map catalog reads.
+ */
+import { isMapGeographyModel, } from './static-domains.js';
+import { UnsupportedProductError, } from './core.js';
+import { openStaticDomainProduct } from './static-domains.js';
+import { openRelease } from './release.js';
+export { isMapGeographyModel };
+/** Open a pinned Maps domain product directly. */
+export async function openMapProduct(options) {
+    const product = await openStaticDomainProduct(options);
+    if (product.manifest.productId !== 'maps') {
+        throw new UnsupportedProductError(product.manifest.productId);
+    }
+    return product;
+}
+export function isMapProductClient(product) {
+    return product.manifest.productId === 'maps';
+}
+/** Read the selected build's digest-verified Map geography model. */
+export async function getMapGeography(options) {
+    const release = await openRelease(options);
+    const maps = await release.openDomainBuild(options.buildId, 'maps');
+    return maps.loadGeography({ signal: options.signal });
+}

package/client/monster-client.d.ts

@@ -8,6 +8,12 @@
  */
 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 { MonsterCatalogV2_2 } from '../generated/monster-catalog-2-2.d.ts';
+import type { MonsterCatalogV2_3 } from '../generated/monster-catalog-2-3.d.ts';
+import type { MonsterDropBrowseV1 } from '../generated/monster-drop-browse.d.ts';
+import type { MonsterLocationBrowseV1 } from '../generated/monster-location-browse.d.ts';
+import type { MonsterLocationBrowseV1_1 } from '../generated/monster-location-browse-1-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,12 +21,19 @@ 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. Contracts 2.1 and 2.2 carry the Media content ID fact
+ * for a monster's representative image; 2.0 and 1.x records have none.
+ */
+export type StaticMonsterCatalog = MonsterCatalog | MonsterCatalogV2 | MonsterCatalogV2_1 | MonsterCatalogV2_2 | MonsterCatalogV2_3;
+export type StaticMonsterLocationBrowse = MonsterLocationBrowseV1 | MonsterLocationBrowseV1_1;
 export type StaticMonsterDetail = MonsterDetailRecord | MonsterDetailRecordV2;
 export type StaticMonsterEvidencePage = MonsterEvidencePage | MonsterEvidencePageV2;
 export interface StaticProductClient {
     readonly manifest: StaticProductManifest;
     loadCatalog(options?: OperationOptions): Promise<StaticMonsterCatalog>;
+    loadDropBrowse(options?: OperationOptions): Promise<MonsterDropBrowseV1>;
+    loadLocationBrowse(options?: OperationOptions): Promise<StaticMonsterLocationBrowse>;
     getDetail(key: string, options?: OperationOptions): Promise<StaticMonsterDetail>;
     getRelationshipPage(page: PageDescriptor, options?: OperationOptions): Promise<MonsterLocationOccurrence[]>;
     getEvidencePage(page: PageDescriptor, options?: OperationOptions): Promise<StaticMonsterEvidencePage>;