@mapletip/data 0.1.0

package/NOTICE

@@ -0,0 +1,52 @@
+MapleTip public data SDK (@mapletip/data)
+Copyright (C) 2026 Stephen Liang. All rights reserved.
+
+This package is publicly downloadable from the npm registry, but it is proprietary
+software, not open-source software: no licence is granted to modify it, redistribute it,
+publish it, sublicense it, or incorporate it (in source or compiled form) into another
+product. Any use beyond installing it as a dependency requires the prior written
+permission of the copyright holder.
+
+SPDX-License-Identifier: UNLICENSED
+
+Third-party notices
+-------------------
+This package contains the following third-party material.
+
+1. Ajv runtime helper `ucs2length`
+
+   Generated standalone validators that enforce string length constraints inline
+   the `ucs2length` helper emitted by Ajv's standalone code generator, so that the
+   published package needs no runtime dependency on Ajv. Ajv is used as a
+   build-time dependency only; this inlined helper is the only Ajv code present in
+   the distributed files (27 of the 34 shipped validators; the others do not
+   enforce string lengths).
+
+   The MIT License (MIT)
+
+   Copyright (c) 2015-2021 Evgeny Poberezkin
+
+   Permission is hereby granted, free of charge, to any person obtaining a copy
+   of this software and associated documentation files (the "Software"), to deal
+   in the Software without restriction, including without limitation the rights
+   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+   copies of the Software, and to permit persons to whom the Software is
+   furnished to do so, subject to the following conditions:
+
+   The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+   SOFTWARE.
+
+Build-time dependencies that are not distributed with this package (Ajv,
+ajv-formats, json-schema-to-typescript, TypeScript) remain under their own
+licences; only the inlined helper above is present in the published files.
+
+Canonical MapleTip datasets, game assets, media and trademarks are not part of
+this package and are licensed separately.

package/README.md

@@ -0,0 +1,209 @@
+# MapleTip public data contracts
+
+## Install
+
+```sh
+npm install @mapletip/data
+```
+
+`@mapletip/data` is an ESM-only package with TypeScript declarations and no runtime
+dependencies. It is one package with domain-scoped entry points, so a consumer only
+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 { openEquipmentProduct } from '@mapletip/data/equipment';
+import { openQuestProduct } from '@mapletip/data/quests';
+import { openMediaProduct, resolveMediaUrl } from '@mapletip/data/media';
+import { assertManifestCompatibility } from '@mapletip/data/contract-compatibility';
+
+// Compatibility: the same implementations, all domains in one graph.
+import { getMonsterBrowse, openRelease, openProduct } from '@mapletip/data';
+import { openRelease } from '@mapletip/data/client';
+```
+
+Every entry point shares one verified release/transport/integrity core. Importing a
+domain never re-implements hashing, scope, capability or contract checks, and the
+compatibility root is a view over the same modules rather than a second implementation.
+
+## Isomorphic Monster browse
+
+`getMonsterBrowse` reads one build's verified Monster catalog in a single call:
+
+```ts
+import { getMonsterBrowse } from '@mapletip/data/monsters';
+
+const catalog = await getMonsterBrowse({
+  baseUrl: releaseRootUrl,
+  pin: releasePin,
+  buildId: 'cw-launch',
+  signal: abortController.signal,
+});
+```
+
+It is exactly `openRelease(options)` → `openBuild(options.buildId)` → `loadCatalog()`:
+it adds no cache, no fallback build selection and no alternate data path, and it returns
+the canonical Rust-owned catalog with its `known`/`unknown`/`absent`/`unsupported` fact
+and collection states and build scope intact. The optional `fetch`, `signal`, `onRequest`
+and validated `preloaded` options behave exactly as they do on `openRelease`, and every
+existing typed failure (`UNKNOWN_BUILD`, `UNSUPPORTED_PRODUCT`, `SCOPE_ERROR`,
+`INTEGRITY_ERROR`, `SCHEMA_VALIDATION_ERROR`, `UNSUPPORTED_CAPABILITY`,
+`CONTRACT_VERSION_ERROR`, `AbortError`, …) propagates unchanged.
+
+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.
+
+`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
+pin, so a consumer chooses exactly one immutable release and one explicit build.
+
+The same import runs in Node (SSR, prerendering, scripts) and in browsers using standard
+`fetch`, `URL`, `AbortSignal` and WebCrypto. Browser reads require a secure context
+(HTTPS or localhost) because SHA-256 verification has no fallback. Rendering mode,
+routing, caching and UI adaptation stay with the consumer.
+
+## What each entry loads
+
+Monster catalog validation and the release/manifest/index validators are imported
+eagerly: a browse cannot complete without them. Everything else loads on the first
+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 | — |
+| `/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 |
+
+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
+the pre-modularization package.
+
+Publication to the public npm registry is a manual, owner-approved step; the procedure
+lives in `PUBLISHING.md` in the repository and is not shipped in the tarball.
+
+## License
+
+`@mapletip/data` is **proprietary software**, published for public download on npm but
+not open source (`"license": "UNLICENSED"` in `package.json`). The copyright holder
+reserves all rights: no licence is granted to modify, redistribute, publish, sublicense or
+incorporate the package into another product, and any use beyond installing it as a
+dependency requires prior written permission, as stated in the `NOTICE` file shipped with
+the package.
+
+`NOTICE` also preserves the third-party attribution for the Ajv runtime helper inlined
+into the generated validators.
+
+Canonical MapleTip datasets, game assets, media and trademarks are **not** part of this
+package and are licensed separately.
+
+## Compiler and product store
+
+The `maplekit-public materialize-product` command stores local products under
+`$XDG_DATA_HOME/mapletip/products` by default, falling back to
+`$HOME/.local/share/mapletip/products`. Set `MAPLETIP_PRODUCT_STORE` or pass
+`--store-root` to select another store.
+
+`maplekit-public assemble-release` accepts exactly two `--product-id` values
+from that product store: the completed CW Launch product with its historical
+overlay and native GMS v83. It writes an immutable local static release under
+`$XDG_DATA_HOME/mapletip/releases`, falling back to
+`$HOME/.local/share/mapletip/releases`; `MAPLETIP_RELEASE_STORE` or
+`--release-store` selects another store. The release manifest advertises
+`release-manifest-v1`, `local-diagnostic`/partial for incomplete local output,
+or `production`/complete when the exact hard-cutover roster is assembled. Its
+separate `pin.json` names the content-addressed manifest path, SHA-256, and
+byte length.
+
+Products emitted by the D identity materializer advertise contract version `1.2` and require `product-input-identity-v1`. Generated wire schemas accept a well-formed minor version under major `1`; typed consumers must also enforce the minimum minor implied by each required capability and reject required capabilities they do not implement. `wire-1.1`, `evidence-pages-v1`, and `historical-drop-overlay-v1` require minor `1` or later; `product-input-identity-v1` and `release-manifest-v1` require minor `2` or later.
+
+TypeScript consumers can import `assertManifestCompatibility` and `assertCompatibleContractVersion` from `@mapletip/data/contract-compatibility`. Validate the manifest first, then use its returned minimum minor when validating each child envelope.
+
+The historical drop overlay is optional. A product advertises `historical-drop-overlay-v1` only when it contains that overlay. A consumer that does not implement the overlay can consume a native product that does not require the capability and can ignore unknown optional fields.
+
+The generated validators at `ba9c525` pinned `contractVersion` to exactly `1.0`. They reject a new `1.1` product even when it has no historical overlay. This was a pre-existing schema defect, not a capability incompatibility. Regenerate or update consumers to use the major-compatible version pattern and check `requiredClientCapabilities` before consuming `1.1` products. Those previous validators cannot accept `1.1` until updated.
+
+The cross-version test in `pnpm test` runs when `MAPLETIP_PREVIOUS_VALIDATOR_DIR` points to a temporary extraction of the generated validators from `ba9c525`; otherwise that historical comparison is skipped.
+
+## Static Monster client
+
+The browser-safe ESM client is available from `@mapletip/data/client`. It consumes one product directory selected by the caller's immutable release pin and build scope:
+
+```ts
+import { openProduct } from '@mapletip/data/client';
+
+const client = await openProduct({
+  baseUrl: releaseProductBaseUrl,
+  manifest: releaseProductDescriptor,
+  expectedScope: { family_id: 'classic-world', build_id: 'cw-launch' },
+  onRequest: (entry) => requestLog.push(entry),
+});
+
+const catalog = await client.loadCatalog();
+const detail = await client.getDetail(catalog.records[0].key);
+const locations = await client.getRelationshipPage(detail.locations.pages[0]);
+```
+
+`releaseProductDescriptor` supplies the manifest path, SHA-256, and byte length from the selected release/product index. The client verifies those manifest bytes and every selected catalog, detail, relationship, or evidence pack against its descriptor before decoding or parsing JSON. It validates each envelope with the generated Ajv validator, checks contract capabilities and exact build scope, and fetches only the pack that addresses the requested key or page. The request hook records the file kind, relative path, and resolved URL.
+
+Digest verification requires a secure browser context with WebCrypto SHA-256 available. If `globalThis.isSecureContext` is `false` or `crypto.subtle` is unavailable, reads reject with `SecureContextRequiredError` (`SECURE_CONTEXT_REQUIRED`). There is no hashing fallback or unverified-data path. Serve the site over HTTPS, or use localhost during local development.
+
+Detail records use generated TypeScript declarations. Optional `evidenceAttribution` on drop entries is exposed to callers as typed data. The client does not render it. The client supports `product-input-identity-v1` and enforces the capability's contract-version floor when opening a product manifest.
+
+## Static release client
+
+Use `openRelease` when the application is pinned to an immutable multi-build release. The `baseUrl` is the release directory root, and `pin` is the parsed `pin.json` object:
+
+```ts
+import { openRelease } from '@mapletip/data/client';
+
+const release = await openRelease({
+  baseUrl: '/releases/release-a299223e/release/',
+  pin,
+});
+
+for (const { family, build, monsterProductDescriptor, questProductDescriptor } of release.builds) {
+  console.log(family, build, monsterProductDescriptor?.productManifest.path, questProductDescriptor?.productManifest.path);
+}
+
+const client = await release.openBuild('cw-launch'); // Monster client
+const questClient = await release.openQuestBuild('cw-launch'); // Quest client
+const mediaClient = await release.openMediaBuild('cw-launch'); // Media client
+```
+
+The client validates the pin, verifies the release-manifest bytes against its pinned SHA-256 and byte length before parsing, validates the manifest with its generated schema, and requires the `release-manifest-v1` capability. It then verifies and validates the build index and checks that both identify the pinned release.
+
+Build product independence: `openRelease` supports releases with any valid product roster (including Monster-less builds containing only Quest products). Each build entry in `release.builds` exposes `productCapabilities`, `monsterProductDescriptor`, `questProductDescriptor`, `mediaProductDescriptor`, and legacy alias `productDescriptor` (for Monster product). Calling `openBuild`, `openQuestBuild`, or `openMediaBuild` on a build missing that product throws `UnsupportedProductError`. Absent build IDs reject with `UnknownBuildError` and never fall back to another product.
+
+## Static Quest client
+
+The Quest client is available via `openQuestProduct` or `openRelease`:
+
+```ts
+import { openQuestProduct, isQuestProductClient } from '@mapletip/data/client';
+
+const client = await openQuestProduct({
+  baseUrl: releaseProductBaseUrl,
+  manifest: questProductDescriptor,
+  expectedScope: { family_id: 'classic-world', build_id: 'cw-launch' },
+  onRequest: (entry) => requestLog.push(entry),
+  onValidatorLoad: (validatorName) => console.log('Validator loaded:', validatorName),
+});
+
+// Lazy per-operation validation: each operation loads only its required validator
+const catalog = await client.loadCatalog();
+const browsePacks = await client.loadBrowsePacks();
+const browseRecord = await client.getBrowseRecord('quest-1000');
+const detail = await client.getDetail('quest-1000');
+const relPage = await client.getRelationshipPage('quest-rel-1000', { expectedOwnerKey: 'quest-1000' });
+const auxPage = await client.getAuxiliaryPage('quest-aux-1000');
+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.
+

package/client/contract-compatibility.d.mts

@@ -0,0 +1,27 @@
+import type { ConnectedProductManifest } from '../generated/product-manifest.d.ts';
+import type { ReleaseManifest } from '../generated/release-manifest.d.ts';
+
+export declare const SUPPORTED_CLIENT_CAPABILITIES: ReadonlySet<string>;
+
+export interface ContractVersionFloor {
+  readonly major: number;
+  readonly minor: number;
+}
+
+export declare function assertCompatibleContractVersion(
+  version: string,
+  minimumVersion?: number | ContractVersionFloor,
+): void;
+
+export declare function assertManifestCompatibility(
+  manifest: ConnectedProductManifest | ReleaseManifest,
+  supportedCapabilities?: ReadonlySet<string>,
+): number;
+
+export declare function minimumPackContractMinor(
+  manifest: ConnectedProductManifest,
+): number;
+
+export declare function minimumPackContractVersion(
+  manifest: ConnectedProductManifest | ReleaseManifest,
+): ContractVersionFloor;

package/client/contract-compatibility.mjs

@@ -0,0 +1,159 @@
+const CONTRACT_VERSION_PATTERN = /^(1|2)\.(0|[1-9][0-9]*)$/;
+
+const MINIMUM_VERSION_BY_CAPABILITY = new Map([
+  ['record-packs-v1', { major: 1, minor: 0 }],
+  ['wire-1.1', { major: 1, minor: 1 }],
+  ['evidence-pages-v1', { major: 1, minor: 1 }],
+  ['historical-drop-overlay-v1', { major: 1, minor: 1 }],
+  ['product-input-identity-v1', { major: 1, minor: 2 }],
+  ['release-manifest-v1', { major: 1, minor: 2 }],
+  ['monster-core-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 }],
+  ['npcs-v1', { major: 2, minor: 0 }],
+  ['reactors-v1', { major: 2, minor: 0 }],
+  ['skills-v1', { major: 2, minor: 0 }],
+  ['jobs-v1', { major: 2, minor: 0 }],
+  ['recipes-v1', { major: 2, minor: 0 }],
+  ['cash-shop-v1', { major: 2, minor: 0 }],
+  ['avatars-v1', { major: 2, minor: 0 }],
+  ['evidence-pages-v2', { major: 2, minor: 0 }],
+  ['wire-2.0', { major: 2, minor: 0 }],
+]);
+const MANIFEST_ONLY_CAPABILITIES = new Set(['product-input-identity-v1']);
+
+const supportedClientCapabilities = new Set([
+  'record-packs-v1',
+  'wire-1.1',
+  'evidence-pages-v1',
+  'historical-drop-overlay-v1',
+  'product-input-identity-v1',
+  'release-manifest-v1',
+  'monster-core-v1',
+  'quests-v1',
+  'items-v1',
+  'equipment-v1',
+  'media-v1',
+  'maps-v1',
+  'npcs-v1',
+  'reactors-v1',
+  'skills-v1',
+  'jobs-v1',
+  'recipes-v1',
+  'cash-shop-v1',
+  'avatars-v1',
+  'evidence-pages-v2',
+  'wire-2.0',
+]);
+
+export const SUPPORTED_CLIENT_CAPABILITIES = new Proxy(supportedClientCapabilities, {
+  get(target, property) {
+    if (property === 'add' || property === 'delete' || property === 'clear') return undefined;
+    const value = Reflect.get(target, property, target);
+    return typeof value === 'function' ? value.bind(target) : value;
+  },
+});
+
+function parseContractVersion(version) {
+  const match = typeof version === 'string' ? CONTRACT_VERSION_PATTERN.exec(version) : null;
+  if (!match) throw new Error(`Unsupported contract version: ${String(version)}`);
+  return { major: Number(match[1]), minor: Number(match[2]) };
+}
+
+function isLessThan(actual, required) {
+  return actual.major < required.major
+    || (actual.major === required.major && actual.minor < required.minor);
+}
+
+function maximumVersion(left, right) {
+  return isLessThan(left, right) ? right : left;
+}
+
+function floorFromArgument(minimumVersion) {
+  if (typeof minimumVersion === 'number') return { major: 1, minor: minimumVersion };
+  if (minimumVersion && Number.isSafeInteger(minimumVersion.major)
+      && Number.isSafeInteger(minimumVersion.minor)
+      && minimumVersion.major >= 1 && minimumVersion.minor >= 0) {
+    return { major: minimumVersion.major, minor: minimumVersion.minor };
+  }
+  throw new Error('Invalid minimum contract version');
+}
+
+export function assertCompatibleContractVersion(version, minimumVersion = 0) {
+  const actual = parseContractVersion(version);
+  const required = floorFromArgument(minimumVersion);
+  if (typeof minimumVersion === 'number' && actual.major !== 1) {
+    throw new Error(`Unsupported contract version: ${version}`);
+  }
+  if (isLessThan(actual, required)) {
+    if (typeof minimumVersion === 'number') {
+      throw new Error(`Contract version ${version} is below required minor ${minimumVersion}`);
+    }
+    throw new Error(`Contract version ${version} is below required contract ${required.major}.${required.minor}`);
+  }
+}
+
+export function assertManifestCompatibility(manifest, supportedCapabilities = SUPPORTED_CLIENT_CAPABILITIES) {
+  let minimumVersion = { major: 1, minor: 0 };
+  const requiredCapabilities = manifest.requiredClientCapabilities ?? [];
+  for (const capability of requiredCapabilities) {
+    const capabilityMinimumVersion = MINIMUM_VERSION_BY_CAPABILITY.get(capability);
+    if (capabilityMinimumVersion === undefined) {
+      throw new Error(`Unknown required client capability: ${capability}`);
+    }
+    if (!supportedCapabilities.has(capability)) {
+      throw new Error(`Unsupported client capability: ${capability}`);
+    }
+    minimumVersion = maximumVersion(minimumVersion, capabilityMinimumVersion);
+  }
+
+  const actual = parseContractVersion(manifest.contractVersion);
+  if (actual.major === 2 && !requiredCapabilities.includes('wire-2.0')) {
+    throw new Error('Contract 2.0 requires the wire-2.0 client capability');
+  }
+  if (actual.major === 2) {
+    for (const required of ['evidence-pages-v2']) {
+      if (!requiredCapabilities.includes(required)) {
+        throw new Error(`Contract 2.0 requires the ${required} client capability`);
+      }
+    }
+    if (!requiredCapabilities.some((capability) => [
+      'monster-core-v1', 'quests-v1', 'items-v1', 'equipment-v1', 'media-v1',
+      'maps-v1', 'npcs-v1', 'reactors-v1', 'skills-v1', 'jobs-v1', 'recipes-v1',
+      'cash-shop-v1', 'avatars-v1',
+    ].includes(capability))) {
+      throw new Error('Contract 2.0 requires a product capability');
+    }
+  }
+  assertCompatibleContractVersion(
+    manifest.contractVersion,
+    minimumVersion.major === 1 ? minimumVersion.minor : minimumVersion,
+  );
+  // Keep the legacy minor-only return value for 1.x callers. Version floors
+  // for pack envelopes use minimumPackContractVersion below.
+  return minimumVersion.major === 2 ? minimumVersion.major : minimumVersion.minor;
+}
+
+export function minimumPackContractVersion(manifest) {
+  let minimumVersion = { major: 1, minor: 0 };
+  for (const capability of manifest.requiredClientCapabilities ?? []) {
+    if (MANIFEST_ONLY_CAPABILITIES.has(capability)) continue;
+    const capabilityMinimumVersion = MINIMUM_VERSION_BY_CAPABILITY.get(capability);
+    if (capabilityMinimumVersion === undefined) {
+      throw new Error(`Unknown required client capability: ${capability}`);
+    }
+    if (!SUPPORTED_CLIENT_CAPABILITIES.has(capability)) {
+      throw new Error(`Unsupported client capability: ${capability}`);
+    }
+    minimumVersion = maximumVersion(minimumVersion, capabilityMinimumVersion);
+  }
+  return minimumVersion;
+}
+
+/** Backwards-compatible minor-only helper for contract-1.x consumers. */
+export function minimumPackContractMinor(manifest) {
+  return minimumPackContractVersion(manifest).minor;
+}

package/client/core.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared verified-data core: standard fetch/URL handling, SHA-256 and byte-length
+ * verification, manifest and pin validation, descriptor path safety, contract and
+ * capability compatibility, build/product scope checks, typed errors, request
+ * tracing and memoization.
+ *
+ * Every domain module imports this module; this module imports no domain module.
+ * Trust operations are implemented exactly once, here.
+ */
+import type { ConnectedProductManifest, PackDescriptor } from '../generated/product-manifest.d.ts';
+import type { ReleaseManifest } from '../generated/release-manifest.d.ts';
+import { type ContractVersionFloor } from './contract-compatibility.mjs';
+export type ProductScope = ConnectedProductManifest['scope'];
+export type ProductIdentity = Readonly<NonNullable<ConnectedProductManifest['identity']>>;
+export interface StaticProductManifest extends ConnectedProductManifest {
+    readonly identity?: ProductIdentity | null;
+}
+/** A manifest pin supplied by the immutable release/product index. */
+export interface ProductManifestDescriptor {
+    readonly path: string;
+    readonly sha256: string;
+    readonly byteLength: number;
+}
+export interface IntegrityDescriptor {
+    readonly path: string;
+    readonly sha256: string;
+    readonly byteLength: number;
+}
+export type RequestKind = 'release-manifest' | 'build-index' | 'manifest' | 'catalog' | 'detail' | 'browse' | 'relationship' | 'core-relationship' | 'auxiliary' | 'evidence' | 'blob';
+export interface RequestLogEntry {
+    readonly kind: RequestKind;
+    readonly path: string;
+    readonly url: string;
+    readonly source: 'network' | 'preloaded';
+}
+export type RequestLogHook = (entry: RequestLogEntry) => void;
+export interface OpenProductOptions {
+    /** Directory URL containing the selected product's manifest and assets. */
+    readonly baseUrl: string | URL;
+    /** Immutable product-manifest pin from the release/product descriptor. */
+    readonly manifest: ProductManifestDescriptor;
+    /** Exact build expected from the caller's release pin. */
+    readonly expectedScope: ProductScope;
+    readonly signal?: AbortSignal;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly onRequest?: RequestLogHook;
+}
+export interface OperationOptions {
+    readonly signal?: AbortSignal;
+}
+export interface GetRelationshipOptions extends OperationOptions {
+    readonly expectedOwnerKey?: string;
+}
+export interface ContractEnvelope {
+    readonly contractVersion: string;
+    readonly scope: ProductScope;
+}
+export interface RuntimeValidator<T> {
+    (data: unknown): data is T;
+    readonly errors?: readonly unknown[] | null;
+}
+/** A product manifest that has already passed pin, schema, capability and scope checks. */
+export interface VerifiedProductContext {
+    readonly manifest: StaticProductManifest;
+    /** Contract floor implied by the product's required client capabilities. */
+    readonly minimumVersion: ContractVersionFloor;
+    /** True for contract-2.0 products, which carry identity metadata and 2.0 packs. */
+    readonly contract2: boolean;
+    /** Fetch, verify bytes and parse one descriptor without schema validation. */
+    fetchJson(descriptor: IntegrityDescriptor | PackDescriptor, kind: RequestKind, operation?: OperationOptions): Promise<unknown>;
+    /** Fetch, verify, parse, schema-validate and scope-check one envelope. */
+    fetchEnvelope<T extends ContractEnvelope>(descriptor: PackDescriptor, kind: Exclude<RequestKind, 'manifest'>, validator: RuntimeValidator<T>, operation?: OperationOptions): Promise<T>;
+    /** Fetch and verify raw bytes (media blobs). */
+    fetchBlob(descriptor: IntegrityDescriptor, operation?: OperationOptions): Promise<Uint8Array>;
+}
+export declare class StaticClientError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+export declare class SecureContextRequiredError extends StaticClientError {
+    constructor();
+}
+export declare class IntegrityError extends StaticClientError {
+    constructor(message: string);
+}
+export declare class RequestError extends StaticClientError {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class InvalidPathError extends StaticClientError {
+    constructor(message: string);
+}
+export declare class InvalidJsonError extends StaticClientError {
+    constructor(path: string, options?: ErrorOptions);
+}
+export declare class SchemaValidationError extends StaticClientError {
+    constructor(path: string, details: string);
+}
+export declare class ContractVersionError extends StaticClientError {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class UnsupportedCapabilityError extends StaticClientError {
+    constructor(message: string);
+}
+export declare class UnsupportedProductError extends StaticClientError {
+    constructor(productId: string);
+}
+export declare class UnknownBuildError extends StaticClientError {
+    constructor(buildId: string);
+}
+export declare class ScopeError extends StaticClientError {
+    constructor(message: string);
+}
+export declare class MissingRecordError extends StaticClientError {
+    constructor(key: string, domain?: string);
+}
+export declare class MissingPageError extends StaticClientError {
+    constructor(key: string, kind: string);
+}
+export declare function normalizedBaseUrl(value: string | URL): URL;
+export declare function verifyBlob(bytes: Uint8Array, descriptor: IntegrityDescriptor): Promise<void>;
+export declare function resolveMediaUrl(baseUrl: URL | string, descriptor: IntegrityDescriptor): string;
+export declare function assertCompatibleManifest(manifest: ConnectedProductManifest | ReleaseManifest): number;
+export declare function createJsonFetcher(options: {
+    readonly baseUrl: URL;
+    readonly fetcher: typeof globalThis.fetch;
+    readonly onRequest?: RequestLogHook;
+    readonly signal?: AbortSignal;
+}): (descriptor: IntegrityDescriptor | PackDescriptor, kind: RequestKind, operation?: OperationOptions) => Promise<unknown>;
+export declare function parsePreloadedJson(value: Uint8Array | string, descriptor: IntegrityDescriptor, kind: RequestKind, baseUrl: URL, onRequest?: RequestLogHook): Promise<unknown>;
+export declare function assertEnvelopeVersion(version: string, minimumVersion: ContractVersionFloor, path: string): void;
+export declare function assertSameScope(actual: ProductScope, expected: ProductScope, path: string): void;
+export declare function rangeDescriptor(descriptors: readonly PackDescriptor[], key: string, kind: string): PackDescriptor;
+export declare function recordRangeDescriptor(descriptors: readonly PackDescriptor[], key: string, kind: string, domain?: string): PackDescriptor;
+export declare function memoized<T>(cache: Map<string, Promise<T>>, key: string, load: () => Promise<T>): Promise<T>;
+/**
+ * Wrap a static `import()` of one generated validator in a memoized loader.
+ * The import specifier stays literal so bundlers keep the validator in its own
+ * on-demand chunk; a rejected load is evicted so the next call retries.
+ */
+export declare function lazyValidator<T>(load: () => Promise<{
+    default: RuntimeValidator<T>;
+}>): () => Promise<RuntimeValidator<T>>;
+export declare function isStaticDomain(domain: string): boolean;
+/** Product capability implied by a content-addressed product ID. */
+export declare function productCapability(productId: string): string | undefined;
+/**
+ * Fetch, verify and validate one product manifest, then hand back the verified
+ * context that domain clients build on. This is the single manifest trust gate.
+ */
+export declare function openProductContext(options: OpenProductOptions): Promise<VerifiedProductContext>;