@assetlib/sdk-core 0.0.0-stage → 0.5.3-preview.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Assetlib contributors
+
+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.

package/README.md

@@ -1,3 +1,237 @@
-# Temporary Holding Version
+# @assetlib/sdk-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An early TypeScript client for signed Assetlib image delivery. Works with the current schema-v1 HTTP delivery API. The Expo adapter supplies native and browser persistence; this package is also usable with your own storage adapter.
+
+The additive JavaScript animation preview (browsers, and Expo on web, iOS and Android) supports a restricted, validated Lottie profile with a mandatory still poster. `resolveAnimation` returns verified JSON for a Lottie player that the app supplies; the SDK plays nothing itself. Image components and the native Swift and Kotlin SDKs continue using that poster.
+
+This preview is on npm under the `preview` dist-tag, and each GitHub release attaches the same package as a tarball. Install core and Expo at the same exact version. A catalog generation step reads local JSON; app builds do not contact Assetlib.
+
+## Client
+
+```ts
+import { createAssetClient, parsePublicConfig } from '@assetlib/sdk-core';
+import { AppAssets } from './assets.generated';
+
+const config = parsePublicConfig(publicConfig);
+const client = createAssetClient(config, { storage: durableStorage });
+await client.initialize(); // Verify persisted state; no network request.
+const release = await client.refresh(); // Fetch and verify the manifest.
+const asset = await client.resolve(AppAssets.Travel.coast, { pixelWidth: 600, pixelHeight: 450 });
+// source is 'remote', 'cache', or 'bundle'. Render a bundled image for 'bundle'.
+```
+
+`refresh()` returns `{ updated, sequence, error? }`. Errors preserve the previous accepted release. `resolve()` returns `{ source, sequence, message, arm, armSource, bytes?, sha256?, assetId?, mime?, pixelWidth?, pixelHeight?, rendering? }`. `getStatus()` returns `{ initialized, sequence, lastError }`. Use one long-lived client per configured app.
+
+Public config: `{ schemaVersion: 1, orgId, appId, environment: 'staging' | 'production', manifestUrl, pinnedPublicKey?, keyId?, pinnedPublicKeys?, keyIds? }`. Supply `pinnedPublicKey` or a `pinnedPublicKeys` array of 1–16 distinct exact-PEM Ed25519 SPKI public keys. Each PEM is limited to 256 UTF-8 bytes. When both are present, the single key must exactly match a member of the set. Configurations with only `pinnedPublicKey` retain their existing behavior and parsed shape.
+
+`parsePublicConfig` accepts a JSON string or an object. JSON is limited to 4096 UTF-8 bytes: strings are measured exactly, including whitespace; objects are measured and parsed using their `JSON.stringify` serialization. Unknown fields are ignored after counting their serialized bytes. Explicit `null` values for recognized fields are rejected, including the optional pin and ID fields.
+
+`keyId`, when supplied, must match the single key and requires `pinnedPublicKey`. Each ID is the first 16 lowercase hexadecimal characters of SHA-256 over the exact UTF-8 PEM text. Optional `keyIds` must match the pinned keys in array order (or the single key when no set is supplied). `parsePublicConfig` derives missing IDs, omitting added IDs when needed to keep its result within 4096 bytes for reuse by a client. Supplied IDs are preserved. Manifests and asset pages may be signed by any member of the pinned set; each envelope's `publicKey` must exactly match that member and its `keyId` must match that key's derived ID. A supplied ID never authorizes an unpinned key.
+
+Use the matching `/api/delivery/{orgId}/{appId}/environments/{environment}/manifest` URL; the legacy `/api/delivery/{orgId}/{appId}/manifest` URL remains valid for production. Signed manifests and asset pages must match the configured environment. Every pinned key must come from a trusted provisioning step independent of the delivery response. Public config contains no admin credentials. Importing it from an untrusted source changes the trust anchor; verification cannot establish that the source belongs to your organization.
+
+To prepare a signing-key rotation, ship a trusted configuration containing both the current and next keys before the server starts signing with the next key. Keep retiring keys pinned while retained releases still need to verify. The SDK does not discover or download replacement trust anchors. `storageNamespace(config)` scopes durable replay state to the manifest origin, organization, app, and environment. Key-set changes and switching between the production manifest routes preserve that identity; staging remains separate. Expo migrates verified state from its previous single-key and sorted-key-set namespaces once when the new namespace is empty. Custom durable adapters should use this identity and `verifyStoredState(serialized, config)` when migrating their prior namespace.
+
+## Optional runtime observations
+
+Telemetry is **off by default**. Opt in when creating the client, and supply your application's registered build metadata:
+
+```ts
+const client = createAssetClient(config, {
+  storage: durableStorage,
+  telemetry: {
+    enabled: true,
+    build: { platform: 'web', appVersion: '1.6.0', buildNumber: '231' },
+    // flushIntervalMs: 60_000, maxBatch: 200
+  },
+});
+const image = await client.resolve(AppAssets.Travel.coast);
+// Call only after your renderer has decoded and attached this remote/cached image.
+client.reportDisplay(AppAssets.Travel.coast, image);
+// On renderer failure: client.reportFallback(AppAssets.Travel.coast, image, 'decode');
+await client.flush();
+```
+
+Each batch goes to the configured manifest origin's `/api/delivery/{orgId}/{appId}/observations` route without credentials. It contains only schema version, environment, SDK name/version, build platform/version/number, a random install ID, send time, and coalesced event counts. Event coordinates contain the placement key, event kind, effective source, asset ID and release sequence when available, effective arm/appearance when selected, and a fallback reason (`offline`, `verification`, `decode`, `missing`, or `other`). Image bytes, image URLs, hashes, descriptions, diagnostic messages, user accounts, device identifiers, and experiment callback data are not sent. Default metadata is `sdk-core` with this package's version and `{ platform: 'web', appVersion: 'unknown', buildNumber: 'unknown' }`; supply actual build metadata for useful build comparisons.
+
+Successful placement resolutions record `resolve`; a successfully resolved state set records its committed members, never a partially discarded family. A bundled outcome records only `fallback`, without an asset ID or sequence. Dynamic catalog references have no placement key and are omitted from observations, including explicit display/fallback reports. `display` is emitted only when the adapter calls `reportDisplay`: it means decoded and attached, **not seen by a person**, and is not experiment exposure or a unique-user count. Animation playback is not observed.
+
+Without an explicit `installId`, the SDK generates a random 32-character hexadecimal ID and stores it under a dedicated per-origin, per-organization, per-app key through `storage.getOrCreateInstallId(key, create)`. Custom durable adapters must implement this optional method atomically: return the existing ID or persist the new `create()` value before returning. The same install shares its ID across staging and production. Clearing app data resets it. `createMemoryStorage()` preserves it only for that adapter instance; use durable storage to retain it across app restarts. An adapter without this method, a persistence failure, or an unavailable secure random source suppresses generated-ID telemetry. The app can instead supply its own persistent, random, opaque `installId` of 8–64 characters. Never use a device, account, advertising, or other personal identifier.
+
+Events coalesce in memory, with at most 2,000 pending coordinates. `flush()` sends one batch of at most 200 events (or a smaller `maxBatch`), capped at 64 KiB, with each count capped at 10,000. Excess count remains queued for subsequent batches. Pending events flush every 60 seconds by default and when `refresh()` runs; explicit `flush()` is useful before backgrounding. A request has a five-second deadline; failed batches stay in memory for the next flush and are not immediately retried. Reporting never blocks or fails artwork resolution. A successful send removes only the sent counts, preserving events recorded during the request. Pending events are not persisted and may be lost when the process exits; a lost response can result in duplicate counts on a later retry. `dispose()` stops telemetry timers and discards its pending observations when the client is no longer needed.
+
+Nonpositive or noninteger interval/batch settings use the defaults; `maxBatch` is capped at 200. Build versions and SDK names/versions accept 1–64 characters from letters, digits, `.`, `_`, `+`, and `-`. Invalid build, SDK, or install-ID metadata disables reporting without changing artwork resolution.
+
+The hosted Assetlib service validates each batch as a whole, accepts at most 64 KiB per request, and stores no raw event log and no raw install ID. Accepted counts are added to daily aggregates keyed by the UTC day of receipt, kept for 90 UTC days. For install coverage it keeps a SHA-256 hash of the install ID and UTC day, per app, environment and day, for 7 UTC days. Expired rows are removed when later batches arrive, not on a fixed schedule. Reporting installs summed over several days are install-days, not unique installations or people. Request infrastructure handles network addresses and headers; they are not stored in the aggregates.
+
+Enabling reporting changes your app's data collection. Review Google Play Data safety disclosures, App Store privacy disclosures and any applicable privacy manifest requirements against your app's actual use. A random install identifier is still sent to the service; enabling this option does not automatically update those declarations or establish consent. Hashing an identifier does not by itself make it anonymous or remove disclosure requirements. Suggested wording for an app team's data inventory, to adapt to your actual configuration:
+
+> When enabled, Assetlib sends app/build version information, placement and asset identifiers, image resolution/display/fallback counts, and a random app-install identifier to our configured Assetlib service for asset-delivery diagnostics. Telemetry is disabled by default. The service stores daily aggregates and day-specific install hashes, not raw event logs or the raw install identifier. A display report means the renderer decoded and attached an image, not that a person viewed it.
+
+## Image descriptions
+
+Image descriptors optionally carry signed `accessibility: { defaultLocale, descriptions }` metadata. Descriptions travel with the image descriptor in the release, including state members and dynamic collection images. `resolve()` returns the metadata for the image it actually selects: a cached image from an older release has that older description. Missing remote metadata never inherits the bundled image's description. Existing descriptors without the field remain valid; no extension version is required.
+
+```ts
+import { resolveAccessibilityDescription } from '@assetlib/sdk-core';
+
+const result = await client.resolve(AppAssets.Travel.coast);
+const description = resolveAccessibilityDescription(result.accessibility, 'en-GB');
+// The application decides whether this usage needs a description or is decorative.
+```
+
+The pure resolver tries a case-insensitive exact locale, progressively removes subtags, then uses `defaultLocale`. There is no filename-derived description or automatic accessibility behavior. Metadata requires 1–32 unique locale tags (case-insensitive), each at most 63 characters and matching `[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*`. The default must name an existing locale. Descriptions must contain non-whitespace text and be at most 1,000 UTF-16 code units. A present null or invalid metadata field rejects the descriptor.
+
+App-owned catalog placements may include `bundledAccessibility` with the same shape. It is returned only for bundled fallback artwork. For state sets, `bundledStateAccessibility` maps declared states to their own bundled metadata for the adapter. Offline code generation validates and preserves both fields. Keep these descriptions synchronized with checked-in bundled images. App controls should describe their action; descriptive artwork and decorative artwork remain choices made by each usage.
+
+## Image formats and sizes
+
+Preview 0.2 accepts the optional signed `renditionSchemaVersion: 1` extension. Existing schema-1 manifests still work; older clients can use the mandatory WebP fallback in new manifests. By default, the client selects PNG or WebP. Ask for physical pixels with both `pixelWidth` and `pixelHeight`; without a target, selection uses the generated placement dimensions. Layout and display density remain the application's responsibility.
+
+Selection uses the smallest rendition covering both dimensions, then byte size and hash. If every rendition is smaller, the largest is preferred. Failed candidates advance to the next candidate, then the legacy fallback. Historical releases remain cache-only. The result describes the actual selected MIME, hash and pixel dimensions. It does not convert one format into another on the device.
+
+A browser renderer can opt into normalized SVG with `formats: ['image/webp', 'image/png', 'image/svg+xml']`. SVG is then preferred. Generic/native clients should retain the raster defaults. The core validates signed metadata, hash, byte length and basic headers; adapters must decode images and verify dimensions before rendering. The Expo web adapter performs browser decoding, while the standalone Swift/Kotlin SDKs use native decoders.
+
+## Tintable icons
+
+A catalog placement can declare `"rendering": "template"`. Assetlib then delivers a single-color shape, and the app supplies the color when it draws it, for example from its theme or a selected state. Values are `original` (the default when absent) and `template`. Code generation adds `rendering: 'template'` to that placement's reference and omits the field otherwise, so catalogs without it generate the same output as before.
+
+```json
+{ "key": "tab.trips", "symbol": ["Tabs", "trips"], "width": 24, "height": 24, "rendering": "template" }
+```
+
+Signed image descriptors (placements, state members, variant cells and catalog page images) may carry `rendering`. A present value that is not a string matching `^[a-z][a-z0-9-]{0,31}$` rejects the release; absent means `original`. Resolution compares the reference's rendering with the descriptor actually selected after arm, appearance and state selection. If they differ, or the descriptor names a value this client does not know, that release's descriptor is skipped as for an incompatible size: its cache entry is not read and nothing is downloaded. Resolution continues with the usual order, a compatible verified cached image from an older retained release and then the bundled fallback (`fallbackReason: 'missing'`). Other placements are unaffected. Catalog page images resolve as `original`. `ResolvedAsset.rendering` reports the delivered descriptor's rendering, `'original'` or `'template'`.
+
+The bundled fallback must also be a single-color shape, such as a PNG with alpha, because the app applies the same tint to remote and bundled artwork. Remote masks are rasters, so request physical pixels with `pixelWidth` and `pixelHeight` (logical size × display scale); the Expo adapter does this for template references. Template rendering needs this SDK and CLI or newer: older code generation drops the field, and older runtimes do not check it. Publishing template descriptors from the hosted console is planned; until then releases carry no `rendering` field.
+
+## Offline typed references
+
+Check a catalog into your application:
+
+```json
+{
+  "schemaVersion": 1,
+  "placements": [
+    { "key": "travel.coast", "symbol": ["Travel", "coast"], "width": 1200, "height": 900 }
+  ]
+}
+```
+
+```sh
+node node_modules/@assetlib/sdk-core/bin/codegen.mjs assetlib.catalog.json > src/assets.generated.ts
+```
+
+Use `AppAssets.Travel.coast` in application code. Existing compatible artwork updates do not require regenerating this catalog. Adding a new application placement does. Schema v1 identifies placements by key and exact width/height; stable placement IDs and separately versioned contracts are not implemented yet. Renaming a key requires a coordinated migration, not simply renaming it in the console.
+
+## Appearance and arm variants
+
+A catalog placement can declare either or both axes: `"variants": { "appearance": ["dark"], "arm": ["b", "c"] }`. Code generation preserves this declaration on `AssetRef` and `StateSetRef`; `assetlib sync` includes it in build registration. Appearance accepts one or two unique `light`/`dark` values. Arms accept one to four unique strings matching `^[a-z][a-z0-9_-]{0,19}$`, excluding `control`, `any`, `constructor`, `prototype`, and `__proto__`. Unknown axes and empty declarations are rejected. Control is implicit and is never listed in `variants.arm`.
+
+```ts
+const image = await client.resolve(AppAssets.Travel.coast, { arm: 'b', appearance: 'dark' });
+const family = await client.resolveStateSet(AppAssets.Tasks.garden, { arm: 'b', appearance: 'dark' });
+```
+
+Signed manifests retain `variantSchemaVersion: 1` and provide each placement's `variants` and bound `cells`. Cells omit `arm` for control and omit `appearance` for Any; at least one coordinate must be present. Duplicate coordinates, undeclared values, and incomplete state families reject the manifest. Resolution selects the first bound coordinate in this order:
+
+1. Requested arm and appearance.
+2. Requested arm and Any appearance.
+3. Control arm and requested appearance.
+4. The placement's legacy fields (Control/Any).
+
+Omitting `appearance` requests Any. An explicit `arm: 'control'` bypasses decisions and requests control. An undeclared explicit arm inherits control through the same order. No other arm or appearance supplies artwork. Each stateful coordinate supplies an entire family; individual states are never mixed between coordinates or releases. Descriptions and renditions belong to the selected descriptor.
+
+Image cache keys include the requested arm and appearance, even when the artwork inherits control. Retained releases use the same selection order and the same decision, with cached bytes only. `ResolvedAsset.sha256` remains the content hash; `cacheKey`, when present, identifies the storage entry. Custom adapters that open cached files should use `cacheKey ?? sha256`. Existing manifests and control cache keys remain supported. `resolveAnimation` continues to use Control/Any and never calls `decide`; asset-page payloads remain unchanged.
+
+## App-supplied decisions
+
+```ts
+const client = createAssetClient(config, {
+  storage: durableStorage,
+  decide: async ({ key, arms, appearance }) => {
+    // Read an assignment from your app's experiment tool without logging exposure.
+    return experimentAssignments[key];
+  },
+});
+const image = await client.resolve(AppAssets.Travel.coast, { appearance: 'dark' });
+```
+
+`decide` may return a declared arm or a promise for one. It runs once per `resolve` or `resolveStateSet` call when no explicit arm was supplied and the current compatible signed slot declares arms. The callback receives the placement key, an immutable array of declared arms, and the requested appearance when present. It never runs for slots without arms, missing slots, or before any signed manifest is available. The SDK does not persist assignment decisions; the app's experiment tool controls assignment stability.
+
+The callback runs outside the client's operation queue with a 1,500 millisecond deadline. Set `decisionTimeoutMs` to an integer from 100 through 10,000 to change it. A pending callback never blocks refresh, initialization, or explicit arm/control requests. After it settles, the client revalidates durable state and selects from the current accepted release, including a newer release accepted by another client sharing storage. Failed revalidation uses the bundled fallback.
+
+An undefined, undeclared, throwing/rejected, or timed-out result selects control, returns `armSource: 'invalid-decision'`, and explains why in `message`. Arm declarations are checked against the current release after the callback. Without a callback, omitted arms use `armSource: 'control'`. Explicit requests use `'explicit'`; accepted callback assignments use `'decision'`.
+
+Every resolved image and state family reports `arm: string | null`: the arm of the artwork actually selected, or `null` for control or bundled fallback. `armSource` records how the request was chosen even when it inherits control or uses the bundle. State members carry the family's arm metadata. These are resolution diagnostics. **Exposure must be logged by the app's experiment tool after the intended artwork is rendered, never from this callback.** A decision can lead to a cache lookup, fallback, cancellation, or artwork that is never displayed.
+
+## Select only the user's assigned catalog entries
+
+The host backend determines card ownership/assignment. Match its artwork keys against references checked into the application, then resolve only those references:
+
+```ts
+import { selectCatalogReferences } from '@assetlib/sdk-core';
+
+const catalog = [AppAssets.Cards.gold, AppAssets.Cards.blue, AppAssets.Cards.green];
+const { references, unknownKeys } = selectCatalogReferences(catalog, backendArtworkKeys);
+await client.refresh(); // Downloads a signed manifest, no image or animation bodies.
+const selectedImages = await Promise.all(references.map(ref => client.resolve(ref)));
+// Show a generic bundled placeholder for unknownKeys; never construct URLs from them.
+```
+
+The helper preserves assignment order, removes duplicates, and accepts at most 100 catalog entries and 100 keys. Unknown strings produce no reference and no request. It does not establish authorization. Public artwork must not contain account data; the app renders customer labels and handles assignment independently. Ship a small generic bundled fallback rather than every catalog image if install size matters. Measure app binary size separately from downloaded payload bytes.
+
+## Explicit Lottie resolution
+
+```ts
+const animation = await client.resolveAnimation(AppAssets.Cards.gold);
+if (animation.source === 'poster') {
+  // Use ordinary client.resolve(ref), then the generic bundled placeholder if needed.
+} else {
+  // animation.data is validated JSON for a compatible Lottie player that the app supplies.
+  // animation.source is 'remote' or 'cache'; bytes and verified metadata are included.
+}
+```
+
+`resolveAnimation(ref)` never plays content automatically. Respect reduced motion, display the still poster while loading or on playback failure, and dispose the player on selection changes/unmount. Ordinary `resolve(ref)` never fetches animation bytes. Use one client and a storage adapter accepting `StorageMime` (`AssetMime | 'application/json'`); JSON is not an image format candidate. Under the `disk` policy the Expo adapter caches verified JSON in the same bounded store as images: IndexedDB on web and `<sha256>.json` files on iOS and Android.
+
+The optional signed `animationSchemaVersion: 1` enables a per-slot `animation` descriptor containing `format: 'lottie'`, `profile: 'vector-v1'`, `mime: 'application/json'`, SHA-256, URL, bytes, width/height, frameRate, inPoint and outPoint. The SDK verifies same-origin app-scoped URLs, exact aspect ratio, signed byte count/hash, and equality between the signed metadata and parsed JSON before exposing data. Unknown schema/profile versions fail closed. Existing image-only clients can ignore the extension and use the mandatory WebP poster.
+
+`vector-v1` accepts self-contained 2D shape layers with groups, paths, rectangles, ellipses, fills, strokes, transforms and trim paths. Static and bounded numeric/shape keyframes are supported. Animated properties require at least two strictly ordered keyframes, array-valued starts/ends (one element for scalars), consistent dimensions/path topology and complete easing for interpolated segments. Transforms require opacity, rotation, position, anchor and scale. It rejects images, fonts/text, precompositions, external resources, expressions, effects, masks, 3D content, unusual blending/time stretching and unknown extensions. `validateLottie(bytes)` exposes the same parser for tools and upload services, returning `{ data, width, height, frameRate, inPoint, outPoint }` without rewriting the original bytes. Rejection messages identify unsupported structure.
+
+Limits: UTF-8 JSON up to 512 KiB, dimensions 1–2048, at most 4,194,304 pixels, 1–60 fps, duration up to 30 seconds / 1,800 frames, 32 layers, 2,048 shapes, 4,096 keyframes/vertices, 30,000 document values and nesting depth 32. An arbitrary hash-valid JSON file is never sufficient for playback.
+
+Verified cached animation works offline. Only the current descriptor may trigger a download; if it fails, retained historical releases may supply an already cached compatible animation. Historical bytes are reverified and never downloaded. If the current release removes animation or its placement, resolution returns `source: 'poster'` immediately instead of reviving an old animation. First-use offline and unsupported/failed animations also return that poster outcome.
+
+## Verification and operating limits
+
+- Ed25519 signatures are checked against an independently pinned key from the configured single key or set using strict RFC 8032 verification. An envelope cannot add or replace a pinned key.
+- Schema, app, organization, environment, key ID, sequence, placement dimensions, and delivery URLs are checked. Image bytes must match the signed SHA-256 and byte count.
+- Public config: at most 4096 UTF-8 JSON bytes, 1–16 distinct exact-PEM pins, and 256 UTF-8 bytes per Ed25519 SPKI PEM. These limits are exported as `SDK_LIMITS.configBytes`, `pinnedKeys`, and `publicKeyBytes`.
+- HTTPS is required. `{ allowInsecureLoopback: true }` permits HTTP only for `localhost`, `127.0.0.1`, or `::1`; it does not permit arbitrary LAN hosts.
+- Delivery is credentialless. Redirects are rejected. A streaming Fetch implementation is required so chunked responses can be bounded. The Expo adapter uses `expo/fetch` on native.
+- Default deadline: 8 seconds per request; configurable from 20 milliseconds to 30 seconds. Maximum manifest response: 256 KiB. Maximum image: 8 MiB. Maximum placements: 100.
+- Persistent state keeps the highest accepted sequence and eight signed releases, up to 3 MiB. A lower sequence or different payload reusing a sequence is rejected. Legitimate server rollback must publish a new, higher sequence.
+- A failed current image resolves to a compatible cached image from the retained release history, then to the app's bundled fallback. Older releases never cause a new download. Eviction or more than eight accepted releases can remove a previous fallback.
+- Cache bytes are rehashed before use. The supplied adapters bound image storage to 50 MiB and 100 entries per configuration. Persistence is required before activating a new release. Corrupt replay state fails closed; it is not automatically discarded.
+
+Clearing app data, uninstalling the app, or browser storage eviction can reset local replay protection across restarts. Changing pinned keys or the production manifest route does not reset it. An active client fails closed if accepted durable state disappears, moves backwards, conflicts, or cannot be verified. This preview does not claim protection against a compromised device or browser. Storage adapters must enforce atomic, nondecreasing state replacement. No background manifest refresh, resumable download, HTTP content negotiation, experiment assignment, or automatic signing-key distribution is implemented. Opt-in observation counts do not establish experiment exposure. Rendering support is supplied by the platform; a valid hash does not prove an image is decodable.
+
+## Development
+
+```sh
+npm ci
+npm test
+npm pack
+```
+
+Tests include the shared cross-platform contract corpus (`test/fixtures/shared`, byte-identical with the Swift and Kotlin SDKs' copies: 115 signed manifest cases, 43 public config cases exercised as strings and objects, 18 appearance/arm resolution cases, 10 tintable icon rendering cases, staging configuration, stateful replay, byte-failure and rendition selection cases), separate JavaScript key-set fixtures for a second trusted signer and an untrusted signer, catalog subset requests, Lottie profile rejection/metadata verification, animation cache/offline/rollback/removal behavior, selection, PNG/SVG bytes and offline fallback, plus real Node Ed25519 signatures and bounded mock delivery streams. They cover signature and byte tampering, independent pins, replay across client restarts, corrupt storage, offline cache fallback, contract mismatch, URL boundaries, deadlines, and offline code generation. The npm pack contains built JavaScript and declarations; it does not require TypeScript compilation when installed.
+
+## State sets, catalog pages, and cache policies
+
+Release 0.4.0-preview.1 adds `StateSetRef` / `resolveStateSet`, signed `loadAssetPage` / `resolveAsset` runtime handles, and `cachePolicy: 'disk' | 'memory' | 'none'`. The default remains `disk`; ephemeral image policies preserve durable signed release state. Image requests are cancellable and bounded to four concurrent transfers by default. `clearMemoryCache()` releases retained session bytes.
+
+A state set declares 2–16 unique states in the checked-in catalog (`placements[].states`); code generation preserves those literal names. Resolve the complete family once and select its returned state. If any required member is unavailable, the whole family uses an eligible older cached release or the bundled family. Do not substitute one progress stage for another.
+
+Catalog metadata pages are signed, scoped to the app/release/request cursor, and contain at most 50 image references. They fetch no image bodies. Preserve the first page's `sequence` on continuation requests. Runtime handles are bound to their issuing client and cannot be serialized or reconstructed as trusted references. Use the Expo virtualized-list example for visible-only image resolution.
+
+These additions currently apply to JavaScript/Expo. Swift/Kotlin retain legacy image APIs. Catalog-only manifests with no slots are unsupported by those older clients. No production-scale catalog capacity is implied.

package/bin/codegen.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { validateAccessibility } from '../dist/accessibility.js';
+
+try {
+  if (process.argv.includes('--help')) {
+    console.log('Usage: node codegen.mjs <checked-in-catalog.json>\nPrints typed AppAssets to stdout. No network calls or automatic file writes.');
+  } else {
+    if (process.argv.length !== 3) throw new Error('Provide one checked-in catalog JSON path. Use --help.');
+    const text = await readFile(process.argv[2], 'utf8');
+    if (Buffer.byteLength(text) > 128 * 1024) throw new Error('Catalog exceeds 128 KiB.');
+    const catalog = JSON.parse(text);
+    if (catalog.schemaVersion !== 1 || !Array.isArray(catalog.placements) || !catalog.placements.length || catalog.placements.length > 100) throw new Error('Expected catalog schemaVersion 1 with 1–100 placements.');
+    const tree = Object.create(null);
+    const keys = new Set();
+    for (const placement of catalog.placements) {
+      if (typeof placement.key !== 'string' || !/^[a-zA-Z][a-zA-Z0-9_.-]{0,119}$/.test(placement.key) || keys.has(placement.key) || ![placement.width, placement.height].every(value => Number.isSafeInteger(value) && value > 0 && value <= 8192) || !Array.isArray(placement.symbol) || placement.symbol.length < 1 || placement.symbol.length > 5 || placement.symbol.some(value => typeof value !== 'string' || !/^[A-Za-z_$][\w$]{0,63}$/.test(value) || ['__proto__', 'constructor', 'prototype'].includes(value))) throw new Error('Invalid or duplicate catalog placement.');
+      keys.add(placement.key);
+      if ('variants' in placement) {
+        const variants = placement.variants;
+        if (!variants || typeof variants !== 'object' || Array.isArray(variants) || !Object.keys(variants).length || Object.keys(variants).some(axis => axis !== 'appearance' && axis !== 'arm')) throw new Error('Variants support only appearance and arm axes.');
+        if ('appearance' in variants && (!Array.isArray(variants.appearance) || !variants.appearance.length || new Set(variants.appearance).size !== variants.appearance.length || variants.appearance.some(value => value !== 'light' && value !== 'dark'))) throw new Error('Variants appearance requires unique light or dark values.');
+        if ('arm' in variants && (!Array.isArray(variants.arm) || variants.arm.length < 1 || variants.arm.length > 4 || new Set(variants.arm).size !== variants.arm.length || variants.arm.some(value => typeof value !== 'string' || value !== value.trim() || !/^[a-z][a-z0-9_-]{0,19}$/.test(value) || ['control', 'any', 'constructor', 'prototype', '__proto__'].includes(value)))) throw new Error('Variants arm requires 1–4 unique valid arm names.');
+      }
+      if (placement.states !== undefined && (!Array.isArray(placement.states) || placement.states.length < 2 || placement.states.length > 16 || new Set(placement.states).size !== placement.states.length || placement.states.some(value => typeof value !== 'string' || !/^[a-z][a-z0-9_-]{0,39}$/.test(value) || ['constructor', 'prototype', '__proto__'].includes(value)))) throw new Error('State sets require 2–16 unique named states.');
+      if ('rendering' in placement && placement.rendering !== 'original' && placement.rendering !== 'template') throw new Error(`Placement ${placement.key} rendering must be "original" or "template".`);
+      if ('bundledAccessibility' in placement) validateAccessibility(placement.bundledAccessibility);
+      if ('bundledStateAccessibility' in placement) {
+        if (!placement.states || !placement.bundledStateAccessibility || typeof placement.bundledStateAccessibility !== 'object' || Array.isArray(placement.bundledStateAccessibility)) throw new Error('Bundled state descriptions require a state set.');
+        for (const [state, metadata] of Object.entries(placement.bundledStateAccessibility)) {
+          if (!placement.states.includes(state)) throw new Error('Bundled description has an unknown state.');
+          validateAccessibility(metadata);
+        }
+      }
+      let node = tree;
+      for (const name of placement.symbol.slice(0, -1)) {
+        if (node[name]?.key) throw new Error('Catalog symbols overlap.');
+        node = node[name] ??= Object.create(null);
+      }
+      const leaf = placement.symbol.at(-1);
+      if (Object.hasOwn(node, leaf)) throw new Error('Catalog symbols overlap.');
+      node[leaf] = { key: placement.key, width: placement.width, height: placement.height, ...(placement.rendering === 'template' ? { rendering: 'template' } : {}), ...(placement.states ? { states: placement.states } : {}), ...(placement.variants ? { variants: placement.variants } : {}), ...(placement.bundledAccessibility ? { bundledAccessibility: placement.bundledAccessibility } : {}), ...(placement.bundledStateAccessibility ? { bundledStateAccessibility: placement.bundledStateAccessibility } : {}) };
+    }
+    console.log('// Generated from the checked-in Assetlib catalog. Regenerate instead of editing.\n// No network dependency during compilation.\nexport const AppAssets = ' + JSON.stringify(tree, null, 2) + ' as const;\n');
+  }
+} catch (error) { console.error(`Assetlib codegen: ${error.message}`); process.exitCode = 1; }

package/dist/accessibility.d.ts

@@ -0,0 +1,5 @@
+import type { AssetAccessibility } from './types.js';
+/** Validate metadata before accepting it as part of a signed image descriptor. */
+export declare function validateAccessibility(value: unknown): asserts value is AssetAccessibility;
+/** Exact locale, then progressively less specific subtags, then the explicit default. */
+export declare function resolveAccessibilityDescription(metadata: AssetAccessibility | undefined, locale?: string): string | undefined;

package/dist/accessibility.js

@@ -0,0 +1,32 @@
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const validLocale = (value) => typeof value === 'string' && value.length <= 63 && /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*(?![\s\S])/.test(value);
+/** Validate metadata before accepting it as part of a signed image descriptor. */
+export function validateAccessibility(value) {
+    if (!record(value) || !validLocale(value.defaultLocale) || !record(value.descriptions))
+        throw new Error('Invalid image accessibility metadata.');
+    const entries = Object.entries(value.descriptions), locales = new Set();
+    if (!entries.length || entries.length > 32)
+        throw new Error('Image accessibility requires 1–32 descriptions.');
+    for (const [locale, description] of entries) {
+        if (!validLocale(locale) || locales.has(locale.toLowerCase()) || typeof description !== 'string' || !description.trim() || description.length > 1000)
+            throw new Error('Invalid image accessibility description.');
+        locales.add(locale.toLowerCase());
+    }
+    if (!locales.has(value.defaultLocale.toLowerCase()))
+        throw new Error('The default image accessibility locale must have a description.');
+}
+/** Exact locale, then progressively less specific subtags, then the explicit default. */
+export function resolveAccessibilityDescription(metadata, locale) {
+    if (!metadata)
+        return undefined;
+    const descriptions = new Map(Object.entries(metadata.descriptions).map(([key, value]) => [key.toLowerCase(), value]));
+    let candidate = locale?.toLowerCase();
+    while (candidate) {
+        const description = descriptions.get(candidate);
+        if (description !== undefined)
+            return description;
+        const separator = candidate.lastIndexOf('-');
+        candidate = separator < 0 ? undefined : candidate.slice(0, separator);
+    }
+    return descriptions.get(metadata.defaultLocale.toLowerCase());
+}

package/dist/animations.d.ts

@@ -0,0 +1,5 @@
+import { type ValidatedLottie } from './lottie.js';
+import type { AnimationDescriptor, AssetlibConfig } from './types.js';
+export declare function validateAnimationExtension(payload: Record<string, unknown>, slot: Record<string, unknown>, config: AssetlibConfig): void;
+/** Call only after byte count and SHA-256 have matched the signed descriptor. */
+export declare function verifiedAnimationData(bytes: Uint8Array, descriptor: AnimationDescriptor): ValidatedLottie;

package/dist/animations.js

@@ -0,0 +1,28 @@
+import { LOTTIE_LIMITS, validateLottie, validateLottieMetadata } from './lottie.js';
+const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const hashPattern = /^[a-f0-9]{64}$/;
+export function validateAnimationExtension(payload, slot, config) {
+    if (own(payload, 'animationSchemaVersion') && payload.animationSchemaVersion !== 1)
+        throw new Error('Unsupported animation schema.');
+    if (!own(slot, 'animation'))
+        return;
+    const a = slot.animation;
+    if (payload.animationSchemaVersion !== 1 || !record(a) || a.format !== 'lottie' || a.profile !== 'vector-v1' || a.mime !== 'application/json' || typeof a.sha256 !== 'string' || !hashPattern.test(a.sha256) || typeof a.url !== 'string' || !Number.isSafeInteger(a.bytes) || Number(a.bytes) < 1 || Number(a.bytes) > LOTTIE_LIMITS.bytes)
+        throw new Error('Invalid signed animation descriptor.');
+    validateLottieMetadata(a);
+    if (Number(a.width) * Number(slot.height) !== Number(a.height) * Number(slot.width))
+        throw new Error('Animation aspect ratio does not exactly match the placement.');
+    const url = new URL(a.url, config.manifestUrl);
+    if (url.origin !== new URL(config.manifestUrl).origin || url.username || url.password || url.search || url.hash || url.pathname !== `/api/delivery/${config.orgId}/${config.appId}/assets/${slot.assetId}/animations/${a.sha256}`)
+        throw new Error('Animation URL is outside the configured app.');
+}
+/** Call only after byte count and SHA-256 have matched the signed descriptor. */
+export function verifiedAnimationData(bytes, descriptor) {
+    const parsed = validateLottie(bytes);
+    for (const key of ['width', 'height', 'frameRate', 'inPoint', 'outPoint']) {
+        if (parsed[key] !== descriptor[key])
+            throw new Error('Animation JSON metadata does not match the signed descriptor.');
+    }
+    return parsed;
+}

package/dist/catalog.d.ts

@@ -0,0 +1,7 @@
+import type { AssetRef } from './types.js';
+/** Match backend assignments against app-owned, checked-in references. This
+ * performs no requests and does not establish customer authorization. */
+export declare function selectCatalogReferences(catalog: readonly AssetRef[], keys: readonly string[]): {
+    references: AssetRef[];
+    unknownKeys: string[];
+};

package/dist/catalog.js

@@ -0,0 +1,27 @@
+/** Match backend assignments against app-owned, checked-in references. This
+ * performs no requests and does not establish customer authorization. */
+export function selectCatalogReferences(catalog, keys) {
+    if (!Array.isArray(catalog) || catalog.length > 100 || !Array.isArray(keys) || keys.length > 100)
+        throw new Error('Catalog selections must be arrays of at most 100 items.');
+    const byKey = new Map();
+    const validKey = (key) => typeof key === 'string' && /^[a-zA-Z][a-zA-Z0-9_.-]{0,119}$/.test(key);
+    for (const ref of catalog) {
+        if (!ref || !validKey(ref.key) || !Number.isSafeInteger(ref.width) || ref.width < 1 || ref.width > 8192 || !Number.isSafeInteger(ref.height) || ref.height < 1 || ref.height > 8192 || byKey.has(ref.key))
+            throw new Error('The trusted catalog has an invalid or duplicate reference.');
+        byKey.set(ref.key, ref);
+    }
+    const references = [], unknownKeys = [], seen = new Set();
+    for (const key of keys) {
+        if (typeof key !== 'string' || key.length > 120)
+            throw new Error('Assignment keys must be strings no longer than 120 characters.');
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const ref = validKey(key) ? byKey.get(key) : undefined;
+        if (ref)
+            references.push(ref);
+        else
+            unknownKeys.push(key);
+    }
+    return { references, unknownKeys };
+}

package/dist/delivery.d.ts

@@ -0,0 +1,12 @@
+import type { AssetlibConfig, AssetPagePayload, ManifestPayload } from './types.js';
+export declare const stateName: (value: unknown) => value is string;
+export declare const assetIdPattern: RegExp;
+/** A malformed rendering rejects the release. A well-formed unknown value is resolved as incompatible, per descriptor. */
+export declare function validateRendering(value: Record<string, unknown>): void;
+export declare function validateDescriptor(value: unknown, width: number, height: number, config: AssetlibConfig, renditionSchemaVersion?: unknown): void;
+export declare function validateDeliveryExtensions(payload: Record<string, unknown>, config: AssetlibConfig): void;
+export declare function validateAssetPage(payload: unknown, config: AssetlibConfig): AssetPagePayload;
+export declare function validStateRef(states: readonly string[]): boolean;
+export declare function catalogForSequence(history: readonly {
+    payload: ManifestPayload;
+}[], sequence: number | undefined): ManifestPayload | undefined;

package/dist/delivery.js

@@ -0,0 +1,148 @@
+import { validateRenditions } from './renditions.js';
+import { validateAccessibility } from './accessibility.js';
+export const stateName = (value) => typeof value === 'string' && /^[a-z][a-z0-9_-]{0,39}$/.test(value) && !['constructor', 'prototype', '__proto__'].includes(value);
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const integer = (value, min, max) => Number.isSafeInteger(value) && Number(value) >= min && Number(value) <= max;
+export const assetIdPattern = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+/** A malformed rendering rejects the release. A well-formed unknown value is resolved as incompatible, per descriptor. */
+export function validateRendering(value) {
+    if ('rendering' in value && (typeof value.rendering !== 'string' || !/^[a-z][a-z0-9-]{0,31}$/.test(value.rendering)))
+        throw new Error('Invalid image rendering.');
+}
+export function validateDescriptor(value, width, height, config, renditionSchemaVersion) {
+    if (!record(value) || typeof value.assetId !== 'string' || !assetIdPattern.test(value.assetId) || typeof value.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(value.sha256) || value.mime !== 'image/webp' || !integer(value.bytes, 1, 8 * 1024 * 1024) || typeof value.url !== 'string')
+        throw new Error('Invalid image descriptor.');
+    const url = new URL(value.url, config.manifestUrl);
+    if (url.origin !== new URL(config.manifestUrl).origin || url.username || url.password || url.search || url.hash || url.pathname !== `/api/delivery/${config.orgId}/${config.appId}/assets/${value.assetId}`)
+        throw new Error('Image descriptor URL is outside the configured app.');
+    validateRenditions(renditionSchemaVersion === undefined ? {} : { renditionSchemaVersion }, { ...value, width, height }, config);
+    if ('accessibility' in value)
+        validateAccessibility(value.accessibility);
+    validateRendering(value);
+}
+function validateStateImages(states, slot, config, renditionSchemaVersion) {
+    for (const value of Object.values(states))
+        validateDescriptor(value, Number(slot.width), Number(slot.height), config, renditionSchemaVersion);
+    const maximumBytes = Object.values(states).reduce((sum, value) => {
+        const descriptor = value;
+        return sum + Math.max(descriptor.bytes, ...(descriptor.renditions ?? []).map(item => item.bytes));
+    }, 0);
+    if (maximumBytes > 50 * 1024 * 1024)
+        throw new Error('State set exceeds the complete-group byte budget.');
+}
+function equivalent(left, right) {
+    if (left === right)
+        return true;
+    if (Array.isArray(left) && Array.isArray(right))
+        return left.length === right.length && left.every((item, index) => equivalent(item, right[index]));
+    if (!record(left) || !record(right))
+        return false;
+    const names = Object.keys(left);
+    return names.length === Object.keys(right).length && names.every(name => Object.hasOwn(right, name) && equivalent(left[name], right[name]));
+}
+function validateCells(slot, payload, config) {
+    if (!('variants' in slot)) {
+        if ('cells' in slot)
+            throw new Error('Variant cells require declared variants.');
+        return;
+    }
+    const variants = slot.variants;
+    if (payload.variantSchemaVersion !== 1 || !record(variants) || !Object.keys(variants).length || Object.keys(variants).some(name => name !== 'appearance' && name !== 'arm'))
+        throw new Error('Invalid variant axes.');
+    if ('appearance' in variants && (!Array.isArray(variants.appearance) || variants.appearance.length < 1 || variants.appearance.length > 2 || variants.appearance.some(value => value !== 'light' && value !== 'dark') || new Set(variants.appearance).size !== variants.appearance.length))
+        throw new Error('Invalid appearance variants.');
+    if ('arm' in variants && (!Array.isArray(variants.arm) || variants.arm.length < 1 || variants.arm.length > 4 || variants.arm.some(value => typeof value !== 'string' || value !== value.trim() || !/^[a-z][a-z0-9_-]{0,19}$/.test(value) || ['control', 'any', 'constructor', 'prototype', '__proto__'].includes(value)) || new Set(variants.arm).size !== variants.arm.length))
+        throw new Error('Invalid arm variants.');
+    const appearances = Array.isArray(variants.appearance) ? variants.appearance : [];
+    const arms = Array.isArray(variants.arm) ? variants.arm : [];
+    if (!('cells' in slot))
+        return;
+    if (!Array.isArray(slot.cells) || slot.cells.length > (arms.length + 1) * (appearances.length + 1) - 1)
+        throw new Error('Invalid variant cells.');
+    const coordinates = new Set();
+    for (const cell of slot.cells) {
+        if (!record(cell) || !('appearance' in cell || 'arm' in cell))
+            throw new Error('Variant cells require at least one arm or appearance coordinate.');
+        if ('appearance' in cell && !appearances.includes(cell.appearance))
+            throw new Error('Variant cell appearance is not declared.');
+        if ('arm' in cell && !arms.includes(cell.arm))
+            throw new Error('Variant cell arm is not declared.');
+        const coordinate = JSON.stringify([cell.arm ?? null, cell.appearance ?? null]);
+        if (coordinates.has(coordinate))
+            throw new Error('Duplicate variant cell coordinates.');
+        coordinates.add(coordinate);
+        validateDescriptor(cell, Number(slot.width), Number(slot.height), config, payload.renditionSchemaVersion);
+        if ('defaultState' in cell)
+            throw new Error('Variant cells use the placement default state.');
+        if (record(slot.states)) {
+            if (!record(cell.states) || Object.keys(cell.states).length !== Object.keys(slot.states).length || Object.keys(slot.states).some(name => !Object.hasOwn(cell.states, name)))
+                throw new Error('Variant state family must contain every declared state.');
+            validateStateImages(cell.states, slot, config, payload.renditionSchemaVersion);
+            const fallback = cell.states[String(slot.defaultState)];
+            if (['assetId', 'sha256', 'url', 'mime', 'bytes', 'renditions', 'accessibility'].some(name => !equivalent(cell[name], fallback[name])))
+                throw new Error('Variant artwork must match its default state.');
+        }
+        else if ('states' in cell)
+            throw new Error('A stateless placement cannot have variant states.');
+    }
+}
+export function validateDeliveryExtensions(payload, config) {
+    if ('stateSchemaVersion' in payload && payload.stateSchemaVersion !== 1)
+        throw new Error('Unsupported state schema.');
+    if ('catalogSchemaVersion' in payload && payload.catalogSchemaVersion !== 1)
+        throw new Error('Unsupported catalog schema.');
+    if ('variantSchemaVersion' in payload && payload.variantSchemaVersion !== 1)
+        throw new Error('Unsupported variant schema.');
+    if ('catalog' in payload) {
+        if (payload.catalogSchemaVersion !== 1 || !record(payload.catalog) || !integer(payload.catalog.count, 0, 1_000_000) || typeof payload.catalog.url !== 'string')
+            throw new Error('Invalid catalog descriptor.');
+        const url = new URL(payload.catalog.url, config.manifestUrl);
+        const deliveryPath = `/api/delivery/${config.orgId}/${config.appId}`;
+        const environmentPath = `${deliveryPath}/environments/${config.environment}/releases/${payload.sequence}/assets`;
+        const legacyProductionPath = config.environment === 'production' && url.pathname === `${deliveryPath}/releases/${payload.sequence}/assets`;
+        if (url.origin !== new URL(config.manifestUrl).origin || url.username || url.password || url.search || url.hash || (url.pathname !== environmentPath && !legacyProductionPath))
+            throw new Error('Catalog URL is outside the configured release.');
+    }
+    for (const slot of payload.slots) {
+        if (!('states' in slot)) {
+            if ('defaultState' in slot)
+                throw new Error('A default state requires a state set.');
+            validateCells(slot, payload, config);
+            continue;
+        }
+        if (payload.stateSchemaVersion !== 1 || !record(slot.states) || !stateName(slot.defaultState))
+            throw new Error('Invalid state set.');
+        const names = Object.keys(slot.states);
+        if (names.length < 2 || names.length > 16 || names.some(name => !stateName(name)) || !Object.hasOwn(slot.states, slot.defaultState))
+            throw new Error('Invalid state declarations.');
+        validateStateImages(slot.states, slot, config, payload.renditionSchemaVersion);
+        const fallback = slot.states[slot.defaultState];
+        if (fallback.assetId !== slot.assetId || fallback.sha256 !== slot.sha256 || fallback.bytes !== slot.bytes || fallback.mime !== slot.mime || fallback.url !== slot.url)
+            throw new Error('Legacy artwork must match the default state.');
+        validateCells(slot, payload, config);
+    }
+}
+export function validateAssetPage(payload, config) {
+    if (!record(payload) || payload.kind !== 'asset-page' || payload.schemaVersion !== 1 || payload.orgId !== config.orgId || payload.appId !== config.appId || payload.environment !== config.environment || !integer(payload.sequence, 1, 2_147_483_647) || typeof payload.createdAt !== 'string' || !Number.isFinite(Date.parse(payload.createdAt)) || !Array.isArray(payload.assets) || payload.assets.length > 50 || !(payload.nextCursor === null || typeof payload.nextCursor === 'string' && assetIdPattern.test(payload.nextCursor)))
+        throw new Error('Invalid or cross-app asset page.');
+    if ('renditionSchemaVersion' in payload && payload.renditionSchemaVersion !== 1)
+        throw new Error('Unsupported rendition schema.');
+    if (!(payload.cursor === null || typeof payload.cursor === 'string' && assetIdPattern.test(payload.cursor)))
+        throw new Error('Invalid catalog request cursor.');
+    let previous = '';
+    for (const asset of payload.assets) {
+        if (!record(asset) || !integer(asset.width, 1, 8192) || !integer(asset.height, 1, 8192) || asset.width * asset.height > 16_777_216 || typeof asset.assetId !== 'string' || asset.assetId <= previous || ('name' in asset && (typeof asset.name !== 'string' || asset.name.length > 200)))
+            throw new Error('Invalid or unordered catalog asset.');
+        validateDescriptor(asset, asset.width, asset.height, config, payload.renditionSchemaVersion);
+        previous = asset.assetId;
+    }
+    if (payload.nextCursor !== null && (!previous || payload.nextCursor !== previous))
+        throw new Error('Invalid catalog continuation.');
+    return payload;
+}
+export function validStateRef(states) {
+    return Array.isArray(states) && states.length >= 2 && states.length <= 16 && new Set(states).size === states.length && states.every(stateName);
+}
+export function catalogForSequence(history, sequence) {
+    return sequence === undefined ? history[0]?.payload : history.find(entry => entry.payload.sequence === sequence)?.payload;
+}