@assetlib/sdk-expo 0.0.0-stage → 0.6.0-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,254 @@
-# Temporary Holding Version
+# @assetlib/sdk-expo
 
-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.
+Expo SDK 57 / React Native 0.86 image delivery adapter for `@assetlib/sdk-core`. One integration targets iOS, Android, and Expo web. This is a preview SDK, not separate Swift or Kotlin SDKs.
+
+Install **`@assetlib/sdk-core` and `@assetlib/sdk-expo` at the same exact version** as direct dependencies, from npm (`preview` dist-tag) or as the tarballs attached to the same GitHub release. The Expo package depends on that exact core version. The host app needs Expo 57, React 19, React Native 0.86, and matching `expo-file-system` and `expo-image` versions:
+
+```sh
+npx expo install expo-file-system expo-image
+```
+
+The package ships Metro-ready TypeScript/TSX source. It has no install-time generation, lifecycle downloads, or secrets. Metro selects the native or web adapter; a custom bundler must honor `.native` / `.web` module resolution.
+
+## Integration
+
+```tsx
+import { createExpoAssetClient, AssetlibImage } from '@assetlib/sdk-expo';
+import { parsePublicConfig } from '@assetlib/sdk-core';
+import { AppAssets } from './assets.generated';
+
+const client = createExpoAssetClient(parsePublicConfig(publicConfig));
+await client.initialize(); // Local persisted release only.
+await client.refresh(); // Explicit network check.
+
+<AssetlibImage
+  client={client}
+  asset={AppAssets.Travel.coast}
+  fallback={require('./assets/coast.png')}
+  revision={refreshCounter}
+  pixelWidth={600}
+  pixelHeight={450}
+  style={{ width: '100%', aspectRatio: 4 / 3 }}
+  contentFit="cover"
+  onStatus={(status) => console.log(status.source, status.sequence)}
+/>
+```
+
+Create a long-lived client outside repeated renders. After an explicit `refresh()`, increment `revision` to request the current artwork. `AssetlibImage` initially displays the bundled fallback, then a verified local image. A native/browser image decode error returns to the bundled image. Supply a stable `fallback` value, such as React Native's numeric `require()` result.
+
+`onStatus` reports source selection and verification, including the effective `arm` (`null` for control) and `armSource` (`explicit`, `decision`, `control`, or `invalid-decision`). Initial bundle and renderer-failure statuses use `arm: null` and `armSource: 'control'`; resolved statuses preserve the core's decision diagnostics. This callback is not a user impression or proof that the image was visible. Do not send experiment exposure events from this callback. App layout, accessibility labels, image sizing, and refresh policy remain app-owned. Rendering uses `expo-image` for downloaded PNG/WebP support on iOS and Android; props follow Expo Image except `cachePolicy`, which controls Assetlib's verified byte retention. The renderer's independent cache is always disabled. Pending resolution is cancelled when a component unmounts or changes its asset request.
+
+## Appearance variants
+
+Declare `"variants": { "appearance": ["dark"] }` on a checked-in catalog placement and regenerate its reference to enable a dark cell. `AssetlibImage`, `AssetlibStateImage`, and `AssetlibDynamicImage` accept `appearance="light"`, `"dark"`, or `"system"` (the default). System mode reads React Native's `useColorScheme()`; a null scheme sends no appearance preference. A change in the effective appearance cancels the previous request and resolves again automatically.
+
+```tsx
+<AssetlibImage
+  client={client}
+  asset={AppAssets.Travel.coast}
+  fallback={require('./assets/coast.png')}
+  fallbackDark={require('./assets/coast-dark.png')}
+  appearance="system"
+/>
+```
+
+Published placements resolve the requested appearance cell when bound, or inherit the placement's Any image. Stateful placements select one complete appearance family; individual states never borrow across appearances. `fallbackDark` is optional on image and dynamic-image components. State images accept an optional `fallbacksDark` map containing every declared state. Dark mode uses that complete bundle when supplied; otherwise it uses the existing `fallback` or `fallbacks`. Bundled accessibility metadata remains app-owned: provide descriptions suitable for the displayed fallback.
+
+Dynamic collection payloads have no appearance cells, so their verified image stays the same while their bundled placeholder can follow appearance. Animations continue using the Any cell. Appearance-scoped cache keys isolate light, dark, and no-preference image requests, including historical cache fallback.
+
+## Tintable icons
+
+Declare `"rendering": "template"` on a catalog placement and regenerate its reference. Assetlib then delivers a single-color shape, and your app supplies the color, for example from its theme or a selected state. `AssetlibImage` and `AssetlibStateImage` pass `tintColor` to Expo Image for both the bundled and the downloaded image, so switching between them keeps the same color.
+
+```tsx
+<AssetlibImage
+  client={client}
+  asset={AppAssets.Tabs.trips}
+  fallback={require('./assets/tab-trips.png')}
+  tintColor={focused ? colors.ink : colors.muted}
+  style={{ width: 24, height: 24 }}
+/>
+```
+
+- TypeScript requires `tintColor` when `asset` is a generated template reference. At runtime, a template reference without `tintColor` logs one development warning per placement key.
+- The bundled fallback must be a single-color shape too, such as a PNG with alpha.
+- Without `pixelWidth` and `pixelHeight`, a template reference requests the placement's logical size × `PixelRatio.get()`, rounded up, so small icons stay sharp. Other references keep requesting the logical size.
+- If the published artwork's rendering does not match the reference, the component keeps the bundled fallback without downloading (see [tintable icons](../sdk-core/README.md#tintable-icons) in the core guide).
+
+## Arms and app decisions
+
+Declare `"variants": { "arm": ["b", "c"], "appearance": ["dark"] }` on a catalog placement to enable arms alongside appearance. Arms contain 1–4 unique lowercase names matching `^[a-z][a-z0-9_-]{0,19}$`; `control`, `any`, `constructor`, `prototype`, and `__proto__` are reserved. Control remains the placement's existing image.
+
+`AssetlibImage` and `AssetlibStateImage` accept an optional `arm="b"` prop. An explicit arm bypasses the decision callback; `arm="control"` selects control. Changing the prop cancels the previous request and resolves again. Without an explicit arm, the client may ask the app's experiment tool for the assignment:
+
+```tsx
+const client = createExpoAssetClient(parsePublicConfig(publicConfig), {
+  decide: async ({ key, arms, appearance }) => {
+    // Read an assignment from app-owned state; do not record exposure here.
+    return assignments[key];
+  },
+});
+
+<AssetlibImage
+  client={client}
+  asset={AppAssets.Travel.coast}
+  arm="b"
+  appearance="dark"
+  fallback={require('./assets/coast.png')}
+/>
+```
+
+The callback receives the placement key, declared arms, and requested appearance. It runs once per resolution, including once for a complete state family, and never for placements without arms. It runs outside the client operation queue with a default deadline of 1,500 ms; configure `decisionTimeoutMs` from 100 to 10,000 ms on the client. Refresh, initialize, and explicit arm requests can proceed while a decision is pending. Afterward, the client revalidates durable state and resolves against the current release. A failed revalidation uses the bundle. An undefined, undeclared, throwing, or timed-out decision falls back to control with `armSource: 'invalid-decision'` and a reason in the status message. With no callback, control is used. If the app's assignment changes, update `arm` or increment `revision` to request it again. **Exposure must be logged by the app's experiment tool when its own visibility rules are met, never by `decide` or `onStatus`.**
+
+Resolution checks `(arm, appearance)`, `(arm, Any)`, `(control, appearance)`, then `(control, Any)`. It never borrows another arm's artwork or mixes state families. Status `arm` identifies the actual selected artwork: inheriting control or displaying a bundled fallback reports `null`, even when the request came from an explicit arm or decision. Image caches isolate both requested arm and appearance, including historical fallback. Dynamic collections and animations do not use arm cells. Bundled fallbacks remain control artwork; there are no per-arm bundled props.
+
+## Accessibility per usage
+
+Choose how each use of an image should behave. Descriptive images can opt into the localized metadata that matches the displayed artwork:
+
+```tsx
+<AssetlibImage
+  client={client}
+  asset={AppAssets.Travel.coast}
+  fallback={require('./assets/coast.png')}
+  accessibilityMode="description"
+  accessibilityLocale="en-GB"
+  fallbackAccessibility={{
+    defaultLocale: 'en',
+    descriptions: { en: 'An illustrated coastal escape' },
+  }}
+/>
+```
+
+`fallbackAccessibility` describes only the bundled image. It defaults to the reference's `bundledAccessibility` when supplied by the checked-in catalog. Remote and cached artwork use their own signed descriptions; after a decode failure or request change, both the image and description return to the corresponding bundle. Description mode keeps the bundle if a remote image has no description. Native `accessibilityLabel` remains an explicit app override, including for legacy releases without metadata. Supply a useful bundled description when choosing description mode.
+
+For decorative artwork, set `accessibilityMode="decorative"`; the image is hidden from accessibility services. If an image is inside a control, label the action on the control and make the artwork decorative. Omitting the mode preserves ordinary Expo accessibility props and does not attach a universal description. Use the app's active locale with `accessibilityLocale`; lookup tries exact locale, parent subtags, then the metadata's explicit default.
+
+`AssetlibDynamicImage` accepts the same props and an explicit `fallbackAccessibility` for its placeholder. `AssetlibStateImage` takes a `fallbackAccessibility` map keyed by state (or the catalog reference's `bundledStateAccessibility`); state selection switches image and description together. In description mode, if any state lacks remote metadata, the entire family stays bundled. The pure `resolveAccessibilityDescription()` helper and `AssetAccessibility` type are exported for custom renderers. These APIs do not generate descriptions or label raw images automatically.
+
+## Artwork states in one component
+
+Use a state set for artwork that belongs to a single placement, such as a plant progressing from sprout to full growth. The application chooses the state from its own business logic. Every declared state needs a bundled fallback.
+
+```tsx
+import { AssetlibStateImage, type StateSetRef } from '@assetlib/sdk-expo';
+
+const garden = {
+  key: 'tasks.garden', width: 120, height: 120,
+  states: ['empty', 'sprout', 'growing', 'complete'],
+} as const satisfies StateSetRef;
+
+<AssetlibStateImage
+  client={client}
+  asset={garden}
+  state={garden.states[completedCount]}
+  fallbacks={{
+    empty: require('./assets/garden-empty.png'),
+    sprout: require('./assets/garden-sprout.png'),
+    growing: require('./assets/garden-growing.png'),
+    complete: require('./assets/garden-complete.png'),
+  }}
+  style={{ width: 120, height: 120 }}
+/>
+```
+
+The component prepares the complete verified family before showing it. Changing only `state` selects from the pinned family without downloading again. A changed client, state-set contract, `revision`, pixel target, cache policy, arm, or effective appearance starts a new resolution. If preparing or displaying a member fails, the entire family uses its matching bundled states until the next resolution. It never substitutes another growth state for a missing one. App code is responsible for supplying a valid declared state.
+
+## Dynamic collections and retention
+
+Use `AssetlibDynamicImage` with an opaque runtime reference issued by this client's verified `loadAssetPage()` result. An arbitrary image URL or hand-built object is not a trusted runtime reference. It resolves on mount and cancels on unmount or reference change; use the application's list virtualization to load only visible or deliberately prefetched items.
+
+```tsx
+<AssetlibDynamicImage
+  client={client}
+  asset={verifiedRuntimeRef}
+  fallback={require('./assets/destination-placeholder.png')}
+  cachePolicy="none"
+  pixelWidth={600}
+  pixelHeight={450}
+  style={{ width: '100%', aspectRatio: 4 / 3 }}
+/>
+```
+
+Set `cachePolicy` on the client as a default, or override it on any of the three image components:
+
+| Policy | Verified image retention |
+| --- | --- |
+| `disk` (default) | Bounded persistent filesystem or IndexedDB cache. |
+| `memory` | Bounded cache for the client's lifetime; no persistent artwork reads or writes. |
+| `none` | No reusable byte cache; the currently rendered image or pinned state set still needs memory. |
+
+For example, `createExpoAssetClient(config, { cachePolicy: 'memory' })` keeps artwork ephemeral while preserving durable signed release metadata and replay protection. Native `memory`/`none` images use verified raster data URIs rather than image files; web images use ephemeral Blob URLs. Changing policy does not delete artwork saved by an earlier disk-caching request. No automatic reset or purge of app data is performed. Load timing and retention are independent: using `disk` does not download the entire library in advance.
+
+## Storage and networking
+
+Native uses the maintained Expo `File`, `Directory`, and `Paths` APIs for durable verification metadata and optional disk artwork, with private app-document storage and a recoverable state replacement journal. Native delivery uses streaming `expo/fetch`. Web uses transactional IndexedDB for durable metadata and optional cached artwork, browser Fetch, and ephemeral Blob image URLs, released when the component changes or unmounts. No credentials are attached to public delivery requests; the server must allow the web demo origin through CORS.
+
+Caches and durable replay state are isolated by manifest origin, organization, app, and environment. Changing pins or switching between the legacy and environment-scoped production manifest routes preserves that namespace. On first use, an empty namespace checks both previous URL/key formulas (single-key and sorted-key-set), verifies the complete stored history with the current pins, and moves valid state and bounded cached artwork into the new namespace. Invalid legacy state is left untouched. A persisted completion marker prevents re-migration; missing or corrupt current state fails closed. Persistent artwork storage, including cached Lottie JSON and MP4 clips, is bounded to 50 MiB / 100 entries per namespace; the core retains eight signed releases. Cached content is rehashed. When verified artwork cannot be fetched or found in an eligible cache, the component uses its bundled fallback.
+
+For the first upgrade from the old namespace scheme, retain the previous pinned set until migration has completed. Migration recognizes subsets of the current pins, including an expansion during upgrade, but cannot reconstruct an old sorted-set namespace containing a removed, unused pin from its one-way hash. Searches are limited to 4,096 namespace probes; exceeding this limit fails closed with bundled artwork instead of resetting replay protection. After migration, pin changes do not change storage identity; every retained release must still verify with the current pins.
+
+There is no automatic app-data reset API: disconnect the client to show bundled artwork while retaining the cache. Explicitly clearing app/browser data removes stored replay protection. Multiple native clients are serialized within one JavaScript process; cross-process synchronization is outside this preview's contract. Preview 0.2 supports PNG/WebP renditions selected by explicit pixel size. Logical placement dimensions still match the generated catalog. Native caches preserve compatibility with existing `.webp` entries. Web can opt into normalized SVG with `createExpoAssetClient(config, { allowVector: true })`; enabling that option on native throws. On native, `client.resolveAnimation(ref)` resolves verified Lottie JSON and, under the `disk` policy, caches it as `<sha256>.json` beside the cached images (at most 512 KiB per entry, inside the same budget) for a Lottie player that the app supplies. The SDK includes no player, and its image components show the still poster. Native SVG and PDF delivery are not implemented. Browser rendering checks decoded dimensions before handing the image to Expo; native Expo decode errors fall back to the bundled image. See the core README for signature, timeout, body-size, and compatibility limits.
+
+## Short looping video
+
+`AssetlibVideo` shows a placement's poster and plays its signed short looping MP4 clip over it. It ships from a separate entry point so `expo-video` stays an optional peer dependency; importing `@assetlib/sdk-expo` never loads it. **This has not been verified on a device, simulator, emulator or browser**; it is covered by Node unit tests with a simulated player only.
+
+```sh
+npx expo install expo-video
+```
+
+```tsx
+import { AssetlibVideo } from '@assetlib/sdk-expo/video';
+
+<AssetlibVideo
+  client={client}
+  asset={AppAssets.Cards.gold}
+  fallback={require('./assets/gold.png')}
+  revision={refreshCounter}
+  contentFit="cover"
+  style={{ width: '100%', aspectRatio: 4 / 3 }}
+/>
+```
+
+- **Poster first.** It takes `AssetlibImage`'s props and renders that image as the poster, bundled fallback first. `style` sizes the container; the poster and clip fill it. The poster stays visible until the clip's first frame renders and returns on any failure.
+- **Playback.** `expo-video`'s `useVideoPlayer` with `loop` and `muted` (screen not kept awake), in a `VideoView` with `nativeControls={false}` and the poster's `contentFit` (`none` and `scale-down` become `contain`).
+- **When it plays.** Only while `AccessibilityInfo.isReduceMotionEnabled()` reports `false` (it listens to `reduceMotionChanged`; an unknown or failing query counts as reduced), the app is active (`AppState`; `background` and `inactive` stop it), `paused` is not set, and the view holds one of two playback slots shared by every `AssetlibVideo` in the app. Other views show their poster and take a slot when one frees. A view resolves its clip only once it holds a slot. Off-screen detection is up to the app: pass `paused` for views that are not visible.
+- **Failures.** A missing clip, a failed check, a player error, or a rejected web `play()` (autoplay blocked, for example in iOS Low Power Mode) shows the poster until the request changes (client, asset, `revision` or `cachePolicy`).
+- **iOS and Android.** The native adapter caches verified clips as `<sha256>.mp4` in the namespaced cache directory (at most 4 MiB each, inside the 50 MiB / 100 entry budget) and the core returns the file's `file://` URI. Under the `memory` and `none` policies `resolveVideo` returns the poster without downloading, because the player needs a file.
+- **Web.** Verified bytes from IndexedDB, memory or the network become a `video/mp4` Blob URL, revoked when the clip changes or the component unmounts.
+- **Open risk.** `expo-video` documents `require()` assets and media-library URIs as local sources, not plain `file://` URIs. Its 57.0.5 source passes a string URI through unchanged: iOS builds an `AVURLAsset` from it (only `ph://` is special-cased) and Android hands it to Media3's `DefaultDataSource`, which reads `file://` URIs. Whether a cached file plays on devices is unverified.
+- Limits and the signed descriptor are in the core README's [Short looping video](../sdk-core/README.md#short-looping-video) section. `createExpoAssetClient(config, { videoTimeoutMs })` sets the clip deadline.
+
+
+Telemetry is **off by default**. Enable it explicitly to report which published placement artwork the app resolves and attaches to an image renderer:
+
+```tsx
+const client = createExpoAssetClient(publicConfig, {
+  telemetry: {
+    enabled: true,
+    build: { platform: 'ios', appVersion: '1.6.0', buildNumber: '231' },
+    flushIntervalMs: 60_000,
+    maxBatch: 200,
+  },
+});
+// Optional before a controlled shutdown:
+await client.flush();
+client.dispose(); // Remove the AppState listener and stop observation timers.
+```
+
+The adapter identifies itself as `sdk-expo` version `0.6.0-preview.1`. An explicit `telemetry.sdk` or `telemetry.build` takes precedence. When the runtime can optionally require `expo-application` or `expo-constants`, the adapter reads native app version and build number (falling back to Expo config version/build). Missing packages, unavailable runtime loaders, and throwing native bridges are ignored; no new dependency is required. Supply `build` explicitly for reliable production attribution, especially with bundlers that cannot resolve optional runtime requires or in Expo Go. Without complete runtime metadata or an explicit build, batches use platform `expo` and version/build `unknown`.
+
+Only the observation contract fields are sent: environment, SDK name/version, build platform/version/number, random install ID, send time, and coalesced events with placement key, kind/count, source, asset ID/release sequence when known, effective arm/appearance when selected, and fallback reason. Bundle outcomes send only `fallback` events without asset ID or sequence. Dynamic catalog references do not emit observations because they have no placement key. Image bytes, descriptions, URLs, device identifiers, account identifiers, and status/error messages are not included.
+
+`AssetlibImage`, `AssetlibStateImage`, and `AssetlibDynamicImage` forward renderer load/error signals to the core (the core ignores dynamic references). For eligible placement images, `display` is counted once per mounted component when a remote or cached image's `onLoad` fires, including after a prop or state change if nothing was loaded earlier. **Display means decoded and attached, not seen by a person.** It is not an experiment exposure or a unique viewer. A current verified image's renderer error reports a `decode` fallback and restores bundled artwork; stale renderer events and bundled-image loads/errors do not add observations. App `onLoad` and `onError` callbacks still run. For a state family, display and decode reports identify the selected state's asset, and changing state does not count another display within that mount.
+
+Events are held in bounded memory and coalesced by coordinate. Automatic flush runs while events are queued, on `refresh()`, and when React Native `AppState` reports `background` when available. Each request has a five-second timeout; failed batches remain queued for the next flush. Background execution is best effort and is not a delivery guarantee. `flush()` sends one bounded batch; `dispose()` drops pending events after stopping the reporter, so await a flush first when needed. Observation failures never fail image resolution.
+
+The generated ID is a random 32-character hexadecimal string persisted in dedicated metadata, independent of artwork cache policy. Native Expo uses its secure UUID generator when Web Crypto is unavailable. It is per installation and per delivery origin/organization/app, shared across environments and signing-key rotations. It is never derived from a device identifier. Clearing app/browser data resets it (and also removes release verification state). An app may instead supply an opaque `telemetry.installId` of 8–64 characters; never pass an account, advertising, or hardware identifier.
+
+Enabling telemetry changes the app's data collection behavior. Review Google Play Data safety, Apple App Privacy disclosures, your privacy policy, consent requirements, and any applicable iOS privacy manifest declarations for the app's actual use. These SDK options do not configure or satisfy those declarations automatically. The hosted service stores daily aggregates for 90 days and daily install hashes for 7 days, rather than raw events. See [optional runtime observations](../sdk-core/README.md#optional-runtime-observations) in the core guide for the complete fields, retention, and suggested Data safety wording. Install counts reflect reporting installations, not unique people or all app users.
+
+## Validation
+
+`npm test` exercises component lifecycle behavior with a React test renderer and mocked platform boundaries, including state-family activation, pinned selection, cancellation, fallback, native no-file data URI generation, and `AssetlibVideo`'s reduced-motion, app-state, two-slot and failure handling against a simulated player. `npm run typecheck` checks against the current Expo 57 APIs. Core security and offline tests run in the sibling package. Actual iOS/Android runtime and web delivery checks must be reported separately; these tests and typechecking are not evidence of a native device run.

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@assetlib/sdk-expo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.0-preview.1",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.tsx",
+  "types": "./src/index.tsx",
+  "react-native": "./src/index.tsx",
+  "exports": {
+    ".": "./src/index.tsx",
+    "./video": "./src/video.tsx"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@assetlib/sdk-core": "0.6.0-preview.1"
+  },
+  "peerDependencies": {
+    "expo": ">=57 <58",
+    "expo-file-system": ">=57 <58",
+    "expo-image": ">=57 <58",
+    "expo-video": ">=57 <58",
+    "react": ">=19 <20",
+    "react-native": ">=0.86 <0.87"
+  },
+  "peerDependenciesMeta": {
+    "expo-video": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "react": "19.2.3",
+    "react-test-renderer": "19.2.3",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AssetLib/sdk-js.git",
+    "directory": "packages/sdk-expo"
+  }
+}

package/src/index.tsx

@@ -0,0 +1,246 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { PixelRatio, useColorScheme } from 'react-native';
+import { Image, type ImageProps } from 'expo-image';
+import { createAssetClient, parsePublicConfig, resolveAccessibilityDescription, type AssetAccessibility, type AssetClient, type AssetlibConfig, type AssetRef, type AssetStatus, type CachePolicy, type ClientOptions, type DynamicAssetRef, type ResolvedAsset, type StateSetRef } from '@assetlib/sdk-core';
+import { createPlatformStorage, imageUri, platformFetch, vectorRenderingSupported } from './platform';
+import type { ImageUri } from './shared';
+import { expoTelemetry, flushOnBackground } from './telemetry';
+export { resolveAccessibilityDescription } from '@assetlib/sdk-core';
+export type { AssetAccessibility, AssetClient, AssetlibConfig, AssetRef, AssetRendering, AssetStatus, CachePolicy, ClientStatus, DynamicAssetRef, RefreshResult, ResolvedVideo, StateSetRef, TelemetryOptions } from '@assetlib/sdk-core';
+
+export function createExpoAssetClient(config: AssetlibConfig, options: { allowInsecureLoopback?: boolean; timeoutMs?: number; videoTimeoutMs?: number; decisionTimeoutMs?: number; allowVector?: boolean; cachePolicy?: CachePolicy; decide?: ClientOptions['decide']; telemetry?: ClientOptions['telemetry'] } = {}): AssetClient {
+  const validated = parsePublicConfig(config, options);
+  if (options.allowVector && !vectorRenderingSupported) throw new Error('SVG delivery is supported only by the browser adapter.');
+  const telemetry = expoTelemetry(options.telemetry);
+  const client = createAssetClient(validated, { ...options, telemetry, formats: options.allowVector ? ['image/webp', 'image/png', 'image/svg+xml'] : ['image/webp', 'image/png'], storage: createPlatformStorage(validated), fetch: platformFetch });
+  if (telemetry?.enabled) flushOnBackground(client);
+  return client;
+}
+
+type ImageSource = NonNullable<ImageProps['source']>;
+type DeliveryImageProps = Omit<ImageProps, 'source' | 'cachePolicy'> & {
+  client: AssetClient;
+  revision?: number;
+  pixelWidth?: number;
+  pixelHeight?: number;
+  /** Assetlib retention policy. The renderer's independent cache stays disabled. */
+  cachePolicy?: CachePolicy;
+  /** Follow the system appearance by default; an unknown system appearance means no preference. */
+  appearance?: 'light' | 'dark' | 'system';
+  /** Opt in per usage. Native accessibilityLabel remains an explicit app override. */
+  accessibilityMode?: 'description' | 'decorative';
+  accessibilityLocale?: string;
+  onStatus?: (status: AssetStatus) => void;
+};
+/** A tintable icon reference requires the app's tint color for its remote and bundled artwork. */
+type TemplateTint<R> = R extends { readonly rendering: 'template' } ? { tintColor: string } : unknown;
+export type AssetlibImageProps<R extends AssetRef = AssetRef> = DeliveryImageProps & { asset: R; arm?: string; fallback: ImageSource; fallbackDark?: ImageSource; fallbackAccessibility?: AssetAccessibility } & TemplateTint<R>;
+export type AssetlibDynamicImageProps = DeliveryImageProps & { asset: DynamicAssetRef; fallback: ImageSource; fallbackDark?: ImageSource; fallbackAccessibility?: AssetAccessibility };
+export type AssetlibStateImageProps<R extends StateSetRef = StateSetRef> = DeliveryImageProps & { asset: R; arm?: string; state: string; fallbacks: Readonly<Record<string, ImageSource>>; fallbacksDark?: Readonly<Record<string, ImageSource>>; fallbackAccessibility?: Readonly<Record<string, AssetAccessibility>> } & TemplateTint<R>;
+
+function useEffectiveAppearance(appearance: 'light' | 'dark' | 'system') {
+  const systemAppearance = useColorScheme();
+  if (appearance !== 'system') return appearance;
+  return systemAppearance === 'light' || systemAppearance === 'dark' ? systemAppearance : undefined;
+}
+
+/** Template masks are rasters: without an explicit target, request logical size × display scale. */
+function pixelTarget(asset: AssetRef, pixelWidth?: number, pixelHeight?: number): { pixelWidth?: number; pixelHeight?: number } {
+  if (asset.rendering !== 'template' || pixelWidth !== undefined || pixelHeight !== undefined) return { pixelWidth, pixelHeight };
+  const ratio = PixelRatio.get();
+  const scale = Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
+  return { pixelWidth: Math.min(8192, Math.ceil(asset.width * scale)), pixelHeight: Math.min(8192, Math.ceil(asset.height * scale)) };
+}
+
+const tintWarnings = new Set<string>();
+function useTemplateTintWarning(asset: AssetRef, tintColor: unknown) {
+  const missing = asset.rendering === 'template' && tintColor == null;
+  useEffect(() => {
+    if (!missing || typeof __DEV__ === 'undefined' || !__DEV__ || tintWarnings.has(asset.key)) return;
+    tintWarnings.add(asset.key);
+    console.warn(`Assetlib: ${asset.key} is a tintable icon. Pass tintColor so its remote and bundled artwork are drawn in your app's color.`);
+  }, [missing, asset.key]);
+}
+
+const bundled = (message: string): AssetStatus => ({ source: 'bundle', sequence: null, message, arm: null, armSource: 'control' });
+function assetStatus(result: AssetStatus): AssetStatus {
+  return { source: result.source, sequence: result.sequence, message: result.message, arm: result.arm, armSource: result.armSource, ...(result.appearance ? { appearance: result.appearance } : {}), ...(result.sha256 ? { sha256: result.sha256 } : {}), ...(result.assetId ? { assetId: result.assetId } : {}) };
+}
+
+function accessibilityProps(props: ImageProps, mode: DeliveryImageProps['accessibilityMode'], metadata?: AssetAccessibility, locale?: string): Partial<ImageProps> {
+  if (mode === 'decorative') return { accessible: false, accessibilityLabel: undefined, accessibilityElementsHidden: true, importantForAccessibility: 'no-hide-descendants', 'aria-hidden': true };
+  if (mode !== 'description') return {};
+  const label = props.accessibilityLabel ?? resolveAccessibilityDescription(metadata, locale);
+  return { accessibilityLabel: label, accessible: props.accessible ?? !!label };
+}
+
+/** Expo dispatches native events through current props; remount on source changes. */
+function useRendererKey(request: object, source: unknown, state?: string): number {
+  const generation = useRef(0);
+  return useMemo(() => ++generation.current, [request, source, state]);
+}
+
+function matchesLoadedSource(event: Parameters<NonNullable<ImageProps['onLoad']>>[0], uri: string): boolean {
+  return event?.source?.url === undefined || event.source.url === uri;
+}
+
+/** A request token hides the previous asset immediately when a recycled view changes identity. */
+function useResolvedImage(client: AssetClient, asset: AssetRef | DynamicAssetRef, request: object, resolve: (signal: AbortSignal) => Promise<ResolvedAsset>, fallback: ImageSource, fallbackAccessibility: AssetAccessibility | undefined, requireDescription: boolean, onStatus?: (status: AssetStatus) => void) {
+  const [resolved, setResolved] = useState<{ request: object; image: ImageUri; result: ResolvedAsset; accessibility?: AssetAccessibility } | null>(null);
+  const callbacks = useRef({ resolve, onStatus });
+  callbacks.current = { resolve, onStatus };
+  const currentUri = useRef<ImageUri | null>(null);
+  const currentRequest = useRef(request);
+  currentRequest.current = request;
+  const displayed = useRef(false);
+  useEffect(() => {
+    const controller = new AbortController();
+    let localUri: ImageUri | null = null;
+    setResolved(null);
+    callbacks.current.onStatus?.(bundled('Bundled artwork is ready while the image resolves.'));
+    callbacks.current.resolve(controller.signal).then(async result => {
+      if (controller.signal.aborted) return;
+      if (result.bytes) {
+        if (requireDescription && !result.accessibility) {
+          callbacks.current.onStatus?.(bundled('Using bundled artwork because the verified image has no accessibility description.'));
+          return;
+        }
+        localUri = await imageUri(client.config, result);
+        if (controller.signal.aborted) { localUri.release(); return; }
+        currentUri.current = localUri;
+        setResolved({ request, image: localUri, result, accessibility: result.accessibility });
+      }
+      callbacks.current.onStatus?.(assetStatus(result));
+    }).catch(() => {
+      if (controller.signal.aborted) return;
+      setResolved(null);
+      callbacks.current.onStatus?.(bundled('Using bundled artwork because the verified image could not be loaded.'));
+    });
+    return () => {
+      controller.abort();
+      localUri?.release();
+      if (currentUri.current === localUri) currentUri.current = null;
+    };
+  }, [client, request]);
+  const isCurrent = () => resolved?.request === request && currentRequest.current === request && currentUri.current === resolved.image;
+  const selected = resolved?.request === request ? resolved : null;
+  const rendererKey = useRendererKey(request, selected?.image ?? fallback);
+  return {
+    rendererKey,
+    source: resolved?.request === request ? { uri: resolved.image.uri } : fallback,
+    accessibility: resolved?.request === request ? resolved.accessibility : fallbackAccessibility,
+    loaded(event: Parameters<NonNullable<ImageProps['onLoad']>>[0]) {
+      if (!isCurrent() || displayed.current || resolved!.result.source === 'bundle' || !matchesLoadedSource(event, resolved!.image.uri)) return;
+      displayed.current = true;
+      client.reportDisplay(asset, resolved!.result);
+    },
+    fail() {
+      if (!isCurrent()) return;
+      client.reportFallback(asset, resolved!.result, 'decode');
+      setResolved(null);
+      currentUri.current?.release(); currentUri.current = null;
+      callbacks.current.onStatus?.(bundled('The image could not be displayed. Using bundled artwork.'));
+    },
+  };
+}
+
+export function AssetlibImage<R extends AssetRef>({ client, asset, arm, fallback, fallbackDark, appearance = 'system', fallbackAccessibility = asset.bundledAccessibility, accessibilityMode, accessibilityLocale, revision = 0, pixelWidth: requestedPixelWidth, pixelHeight: requestedPixelHeight, cachePolicy, onStatus, onError, onLoad, ...rest }: AssetlibImageProps<R>) {
+  const props: Omit<ImageProps, 'source' | 'cachePolicy'> = rest;
+  const effectiveAppearance = useEffectiveAppearance(appearance);
+  const { pixelWidth, pixelHeight } = pixelTarget(asset, requestedPixelWidth, requestedPixelHeight);
+  useTemplateTintWarning(asset, props.tintColor);
+  const requireDescription = accessibilityMode === 'description' && props.accessibilityLabel == null;
+  const request = useMemo(() => ({}), [client, asset.key, asset.width, asset.height, asset.rendering, arm, revision, pixelWidth, pixelHeight, cachePolicy, requireDescription, effectiveAppearance]);
+  const image = useResolvedImage(client, asset, request, signal => client.resolve(asset, { pixelWidth, pixelHeight, cachePolicy, appearance: effectiveAppearance, arm, signal }), effectiveAppearance === 'dark' ? fallbackDark ?? fallback : fallback, fallbackAccessibility, requireDescription, onStatus);
+  return <Image {...props} key={image.rendererKey} {...accessibilityProps(props, accessibilityMode, image.accessibility, accessibilityLocale)} cachePolicy="none" source={image.source} onLoad={event => { image.loaded(event); onLoad?.(event); }} onError={event => { image.fail(); onError?.(event); }} />;
+}
+
+/** Runtime references come from this client's verified collection page, never from an arbitrary URL. */
+export function AssetlibDynamicImage({ client, asset, fallback, fallbackDark, appearance = 'system', fallbackAccessibility, accessibilityMode, accessibilityLocale, revision = 0, pixelWidth, pixelHeight, cachePolicy, onStatus, onError, onLoad, ...props }: AssetlibDynamicImageProps) {
+  const effectiveAppearance = useEffectiveAppearance(appearance);
+  const requireDescription = accessibilityMode === 'description' && props.accessibilityLabel == null;
+  const request = useMemo(() => ({}), [client, asset, revision, pixelWidth, pixelHeight, cachePolicy, requireDescription, effectiveAppearance]);
+  const image = useResolvedImage(client, asset, request, signal => client.resolveAsset(asset, { pixelWidth, pixelHeight, cachePolicy, appearance: effectiveAppearance, signal }), effectiveAppearance === 'dark' ? fallbackDark ?? fallback : fallback, fallbackAccessibility, requireDescription, onStatus);
+  return <Image {...props} key={image.rendererKey} {...accessibilityProps(props, accessibilityMode, image.accessibility, accessibilityLocale)} recyclingKey={props.recyclingKey ?? `${asset.assetId}:${asset.sequence}`} cachePolicy="none" source={image.source} onLoad={event => { image.loaded(event); onLoad?.(event); }} onError={event => { image.fail(); onError?.(event); }} />;
+}
+
+/** Resolves a complete visual family once. Changing only `state` selects the pinned result. */
+export function AssetlibStateImage<R extends StateSetRef>({ client, asset, arm, state, fallbacks, fallbacksDark, appearance = 'system', fallbackAccessibility = asset.bundledStateAccessibility, accessibilityMode, accessibilityLocale, revision = 0, pixelWidth: requestedPixelWidth, pixelHeight: requestedPixelHeight, cachePolicy, onStatus, onError, onLoad, ...rest }: AssetlibStateImageProps<R>) {
+  const props: Omit<ImageProps, 'source' | 'cachePolicy'> = rest;
+  const effectiveAppearance = useEffectiveAppearance(appearance);
+  const { pixelWidth, pixelHeight } = pixelTarget(asset, requestedPixelWidth, requestedPixelHeight);
+  useTemplateTintWarning(asset, props.tintColor);
+  const statesKey = JSON.stringify(asset.states);
+  const requireDescription = accessibilityMode === 'description' && props.accessibilityLabel == null;
+  const request = useMemo(() => ({}), [client, asset.key, asset.width, asset.height, asset.rendering, statesKey, arm, revision, pixelWidth, pixelHeight, cachePolicy, requireDescription, effectiveAppearance]);
+  const [resolved, setResolved] = useState<{ request: object; images: Record<string, ImageUri>; results: Readonly<Record<string, ResolvedAsset>>; accessibility: Record<string, AssetAccessibility | undefined> } | null>(null);
+  const callbacks = useRef({ onStatus });
+  callbacks.current = { onStatus };
+  const currentUris = useRef<Record<string, ImageUri> | null>(null);
+  const currentSelection = useRef({ request, state });
+  currentSelection.current = { request, state };
+  const displayed = useRef(false);
+  if (!asset.states.includes(state)) throw new Error(`Unknown artwork state: ${state}.`);
+  if (asset.states.some(name => !Object.prototype.hasOwnProperty.call(fallbacks, name) || fallbacks[name] == null)) throw new Error('Every artwork state requires its own bundled fallback.');
+  if (fallbacksDark && asset.states.some(name => !Object.prototype.hasOwnProperty.call(fallbacksDark, name) || fallbacksDark[name] == null)) throw new Error('Every artwork state requires its own dark bundled fallback when fallbacksDark is supplied.');
+  useEffect(() => {
+    const controller = new AbortController();
+    const images: Record<string, ImageUri> = Object.create(null);
+    const accessibility: Record<string, AssetAccessibility | undefined> = Object.create(null);
+    const release = () => { for (const image of Object.values(images)) image.release(); };
+    setResolved(null);
+    callbacks.current.onStatus?.(bundled('Bundled states are ready while the complete artwork set resolves.'));
+    client.resolveStateSet(asset, { pixelWidth, pixelHeight, cachePolicy, appearance: effectiveAppearance, arm, signal: controller.signal }).then(async result => {
+      if (controller.signal.aborted) return;
+      if (result.source === 'bundle') {
+        callbacks.current.onStatus?.(assetStatus(result));
+        return;
+      }
+      if (requireDescription && asset.states.some(name => !result.states[name]?.accessibility)) {
+        callbacks.current.onStatus?.(bundled('Using bundled states because a verified state has no accessibility description.'));
+        return;
+      }
+      // Commit only after every state can be handed to the renderer.
+      for (const name of asset.states) {
+        if (!result.states[name]?.bytes) throw new Error('The verified state set is incomplete.');
+        images[name] = await imageUri(client.config, result.states[name]);
+        accessibility[name] = result.states[name].accessibility;
+        if (controller.signal.aborted) { release(); return; }
+      }
+      currentUris.current = images;
+      setResolved({ request, images, results: result.states, accessibility });
+      callbacks.current.onStatus?.(assetStatus(result));
+    }).catch(() => {
+      release();
+      if (controller.signal.aborted) return;
+      setResolved(null);
+      callbacks.current.onStatus?.(bundled('Using the complete bundled state set because verified artwork could not be loaded.'));
+    });
+    return () => {
+      controller.abort(); release();
+      if (currentUris.current === images) currentUris.current = null;
+    };
+  }, [client, request]);
+  const selected = resolved?.request === request ? resolved.images[state] : null;
+  const metadata = selected ? resolved!.accessibility[state] : fallbackAccessibility?.[state];
+  const fallback = (effectiveAppearance === 'dark' ? fallbacksDark ?? fallbacks : fallbacks)[state];
+  const rendererKey = useRendererKey(request, selected ?? fallback, state);
+  const isCurrent = () => selected && currentSelection.current.request === request && currentSelection.current.state === state && currentUris.current === resolved?.images;
+  return <Image {...props} key={rendererKey} {...accessibilityProps(props, accessibilityMode, metadata, accessibilityLocale)} cachePolicy="none" source={selected ? { uri: selected.uri } : fallback} onLoad={event => {
+    if (isCurrent() && !displayed.current && resolved!.results[state].source !== 'bundle' && matchesLoadedSource(event, selected!.uri)) {
+      displayed.current = true;
+      client.reportDisplay(asset, resolved!.results[state]);
+    }
+    onLoad?.(event);
+  }} onError={event => {
+    if (isCurrent()) {
+      client.reportFallback(asset, resolved!.results[state], 'decode');
+      // A decode failure returns the entire family to bundled artwork for this session.
+      setResolved(null);
+      if (currentUris.current) for (const image of Object.values(currentUris.current)) image.release();
+      currentUris.current = null;
+      callbacks.current.onStatus?.(bundled('A state image could not be displayed. Using the complete bundled state set.'));
+    }
+    onError?.(event);
+  }} />;
+}

package/src/platform.native.ts

@@ -0,0 +1,183 @@
+import { Directory, File, Paths } from 'expo-file-system';
+import { fetch as expoFetch } from 'expo/fetch';
+import { LOTTIE_LIMITS, SDK_LIMITS, verifyStoredState, type AssetlibConfig, type AssetStorage, type ResolvedAsset, type ResolvedVideo } from '@assetlib/sdk-core';
+import { namespace, legacyNamespaces, installStorageKey, rasterDataUri, validateCacheKey, type ImageUri } from './shared';
+
+export const vectorRenderingSupported = false;
+export const platformFetch = expoFetch as unknown as typeof globalThis.fetch;
+// Raster images, verified Lottie JSON and MP4 clips share one namespaced directory and its budget.
+const cacheFormats = new Map<string, { extension: string; maxBytes: number; label: string }>([
+  ['image/webp', { extension: 'webp', maxBytes: SDK_LIMITS.assetBytes, label: 'Image' }],
+  ['image/png', { extension: 'png', maxBytes: SDK_LIMITS.assetBytes, label: 'Image' }],
+  ['application/json', { extension: 'json', maxBytes: LOTTIE_LIMITS.bytes, label: 'Animation' }],
+  ['video/mp4', { extension: 'mp4', maxBytes: SDK_LIMITS.videoBytes, label: 'Clip' }],
+]);
+const locks = new Map<string, Promise<unknown>>();
+function exclusive<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const next = (locks.get(key) ?? Promise.resolve()).then(fn, fn);
+  locks.set(key, next.catch(() => {}));
+  return next;
+}
+function directories(config: AssetlibConfig) {
+  const root = new Directory(Paths.document, 'assetlib-v1', namespace(config));
+  const images = new Directory(root, 'images');
+  root.create({ intermediates: true, idempotent: true });
+  images.create({ intermediates: true, idempotent: true });
+  return { root, images };
+}
+export function createPlatformStorage(config: AssetlibConfig): AssetStorage {
+  const scope = namespace(config);
+  let migrationChecked = false;
+  const readState = async (root: Directory) => {
+    const candidates: string[] = [];
+    // Retain a recoverable journal during replacement. An interrupted write fails
+    // closed; it must never make the replay counter silently disappear.
+    for (const name of ['state.json', 'state.next']) {
+      const file = new File(root, name);
+      if (!file.exists) continue;
+      if (file.size > SDK_LIMITS.stateBytes) throw new Error('Stored state exceeds its bound.');
+      candidates.push(await file.text());
+    }
+    return candidates.sort((a, b) => JSON.parse(b).highestSequence - JSON.parse(a).highestSequence)[0] ?? null;
+  };
+  const writeState = async (root: Directory, serialized: string) => {
+    const next = new File(root, 'state.next');
+    next.create({ overwrite: true }); next.write(serialized);
+    // The journal already contains the full replay state before the marker is
+    // written. A crash at either step cannot make this look like a fresh install.
+    const marker = new File(root, 'migration.complete');
+    marker.create({ overwrite: true }); marker.write('1');
+    await next.move(new File(root, 'state.json'), { overwrite: true });
+  };
+  const loadState = async () => {
+    const { root, images } = directories(config);
+    const current = await readState(root);
+    if (current !== null) { migrationChecked = true; return current; }
+    if (new File(root, 'migration.complete').exists) throw new Error('Previously persisted replay state is missing.');
+    if (migrationChecked) return null;
+    let selected: { root: Directory; raw: string; sequence: number; payload: string } | undefined;
+    for (const legacy of legacyNamespaces(config)) {
+      const oldRoot = new Directory(Paths.document, 'assetlib-v1', legacy);
+      let raw: string | null, state: ReturnType<typeof verifyStoredState>;
+      try {
+        raw = await readState(oldRoot);
+        if (raw === null) continue;
+        state = verifyStoredState(raw, config);
+      } catch { continue; } // Invalid old state is ignored, never removed.
+      if (selected?.sequence === state.highestSequence && selected.payload !== state.history[0].payload) throw new Error('Conflicting legacy replay state.');
+      if (!selected || state.highestSequence > selected.sequence) selected = { root: oldRoot, raw, sequence: state.highestSequence, payload: state.history[0].payload };
+    }
+    if (!selected) { migrationChecked = true; return null; }
+    // Copy bounded artwork before publishing metadata. The core rehashes every
+    // copied cache entry before use, including arm and appearance cache keys.
+    const oldImages = new Directory(selected.root, 'images');
+    let count = 0, bytes = 0;
+    if (oldImages.exists) for (const entry of oldImages.list()) {
+      if (!(entry instanceof File) || !/^[a-f0-9]{64}\.(webp|png)$/.test(entry.name) || entry.size > SDK_LIMITS.assetBytes || entry.size < 1) continue;
+      if (count >= SDK_LIMITS.cacheEntries || bytes + entry.size > SDK_LIMITS.cacheBytes) continue;
+      await entry.copy(new File(images, entry.name), { overwrite: true });
+      count++; bytes += entry.size;
+    }
+    await writeState(root, selected.raw);
+    migrationChecked = true;
+    // Destination is durable before deleting any verified source. Interrupted
+    // cleanup is harmless: the destination prevents all future legacy reads.
+    try {
+      if (await readState(selected.root) === selected.raw) for (const name of ['state.json', 'state.next']) {
+        const file = new File(selected.root, name);
+        if (file.exists) file.delete();
+      }
+    } catch { /* Retain the old copy if cleanup fails. */ }
+    return selected.raw;
+  };
+  return {
+    getOrCreateInstallId: (key, create) => exclusive(`install:${installStorageKey(key)}`, async () => {
+      const root = new Directory(Paths.document, 'assetlib-installs-v1');
+      root.create({ intermediates: true, idempotent: true });
+      const name = installStorageKey(key);
+      for (const suffix of ['.id', '.next']) {
+        const file = new File(root, `${name}${suffix}`);
+        if (!file.exists || file.size > 64) continue;
+        const value = await file.text();
+        if (/^[a-f0-9]{32}$/.test(value)) return value;
+      }
+      let value: string;
+      try { value = create(); }
+      catch {
+        // Expo's native runtime supplies secure UUIDs even without Web Crypto.
+        const nativeUuid = (globalThis as typeof globalThis & { expo?: { uuidv4?: () => string } }).expo?.uuidv4?.();
+        if (typeof nativeUuid !== 'string') throw new Error('Secure install ID generation is unavailable.');
+        value = nativeUuid.replaceAll('-', '').toLowerCase();
+      }
+      if (!/^[a-f0-9]{32}$/.test(value)) throw new Error('Invalid random install ID.');
+      const next = new File(root, `${name}.next`);
+      next.create({ overwrite: true }); next.write(value);
+      await next.move(new File(root, `${name}.id`), { overwrite: true });
+      return value;
+    }),
+    loadState: () => exclusive(scope, loadState),
+    saveState: serialized => exclusive(scope, async () => {
+      if (new TextEncoder().encode(serialized).length > SDK_LIMITS.stateBytes) throw new Error('State exceeds its bound.');
+      const old = await loadState();
+      if (old) {
+        const previous = JSON.parse(old), next = JSON.parse(serialized);
+        if (previous.highestSequence > next.highestSequence || (previous.highestSequence === next.highestSequence && previous.history[0]?.payload !== next.history[0]?.payload)) throw new Error('A newer or conflicting sequence is already stored.');
+      }
+      await writeState(directories(config).root, serialized);
+    }),
+    getAsset: async hash => {
+      validateCacheKey(hash);
+      const { images } = directories(config);
+      for (const { extension, maxBytes } of cacheFormats.values()) {
+        const file = new File(images, `${hash}.${extension}`);
+        if (file.exists && file.size <= maxBytes) return file.bytes();
+      }
+      return null;
+    },
+    putAsset: (hash, bytes, mime = 'image/webp') => exclusive(scope, async () => {
+      const format = cacheFormats.get(mime);
+      if (!format) throw new Error('This native adapter caches PNG, WebP, Lottie JSON and MP4 only.');
+      const { extension } = format;
+      validateCacheKey(hash);
+      if (bytes.length > format.maxBytes) throw new Error(`${format.label} exceeds the cache entry bound.`);
+      const { images } = directories(config);
+      for (const entry of images.list()) if (entry instanceof File && entry.name.endsWith('.next')) entry.delete();
+      const entries = images.list().filter((entry): entry is File => entry instanceof File && /\.(webp|png|json|mp4)$/.test(entry.name) && entry.name !== `${hash}.${extension}`).sort((a, b) => (a.modificationTime ?? 0) - (b.modificationTime ?? 0));
+      let total = entries.reduce((sum, file) => sum + file.size, 0);
+      while (entries.length >= SDK_LIMITS.cacheEntries || total + bytes.length > SDK_LIMITS.cacheBytes) {
+        const oldest = entries.shift();
+        if (!oldest) break;
+        total -= oldest.size;
+        oldest.delete();
+      }
+      const next = new File(images, `${hash}.next`);
+      next.create({ overwrite: true }); next.write(bytes);
+      await next.move(new File(images, `${hash}.${extension}`), { overwrite: true });
+    }),
+    // The player opens clips from files, so the core returns this URI instead of clip bytes.
+    getAssetFileUri: async (hash, mime) => {
+      validateCacheKey(hash);
+      const format = cacheFormats.get(mime);
+      if (!format) return null;
+      const file = new File(directories(config).images, `${hash}.${format.extension}`);
+      return file.exists && file.size <= format.maxBytes ? file.uri : null;
+    },
+  };
+}
+export async function imageUri(config: AssetlibConfig, result: ResolvedAsset): Promise<ImageUri> {
+  if (!result.sha256) throw new Error('Missing verified image hash.');
+  validateCacheKey(result.sha256);
+  if (!['image/webp', 'image/png'].includes(result.mime ?? '')) throw new Error('Unsupported native image format.');
+  if (result.cachePolicy === 'memory' || result.cachePolicy === 'none') return rasterDataUri(result);
+  const cacheKey = result.cacheKey ?? result.sha256;
+  validateCacheKey(cacheKey);
+  const extension = result.mime === 'image/png' ? 'png' : 'webp';
+  const file = new File(directories(config).images, `${cacheKey}.${extension}`);
+  if (!file.exists) throw new Error('The verified image was evicted from the local cache.');
+  return { uri: file.uri, release() {} };
+}
+/** A verified cached clip as the player's local file. `memory` and `none` never reach here: the core gives the poster. */
+export async function videoUri(_config: AssetlibConfig, result: ResolvedVideo): Promise<ImageUri> {
+  if (result.source === 'poster' || typeof result.uri !== 'string' || !result.uri.startsWith('file://')) throw new Error('The verified clip is not available as a local file.');
+  return { uri: result.uri, release() {} };
+}

package/src/platform.ts

@@ -0,0 +1 @@
+export * from './platform.native';

package/src/platform.web.ts

@@ -0,0 +1,169 @@
+import { SDK_LIMITS, verifyStoredState, type AssetlibConfig, type AssetStorage, type ResolvedAsset, type ResolvedVideo } from '@assetlib/sdk-core';
+import { namespace, legacyNamespaces, installStorageKey, validateCacheKey, type ImageUri } from './shared';
+export const vectorRenderingSupported = true;
+export const platformFetch: typeof globalThis.fetch = (...args) => globalThis.fetch(...args);
+
+function database(config: AssetlibConfig, install = false, scope = namespace(config)): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    if (!globalThis.indexedDB) return reject(new Error('IndexedDB is required for persistent release verification.'));
+    const request = indexedDB.open(install ? 'assetlib-installs-v1' : `assetlib-v1-${scope}`, 1);
+    request.onupgradeneeded = () => { request.result.createObjectStore('meta'); if (!install) request.result.createObjectStore('images', { keyPath: 'hash' }); };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(new Error('Could not open the Assetlib cache.'));
+    request.onblocked = () => reject(new Error('Close other Assetlib tabs to update this cache.'));
+  });
+}
+export function createPlatformStorage(config: AssetlibConfig): AssetStorage {
+  let migrationChecked = false;
+  async function transaction<T>(storeName: 'meta' | 'images' | ['meta', 'images'], mode: IDBTransactionMode, work: (store: IDBObjectStore, done: (result: T) => void, abort: (error: Error) => void, tx: IDBTransaction) => void, install = false, scope = namespace(config)): Promise<T> {
+    const db = await database(config, install, scope);
+    return new Promise<T>((resolve, reject) => {
+      const tx = db.transaction(storeName, mode);
+      let result: T;
+      let failure: Error | null = null;
+      tx.oncomplete = () => { db.close(); resolve(result); };
+      tx.onabort = tx.onerror = () => { db.close(); reject(failure ?? new Error('Assetlib cache transaction failed.')); };
+      try { work(tx.objectStore(Array.isArray(storeName) ? storeName[0] : storeName), value => { result = value; }, error => { failure = error; tx.abort(); }, tx); }
+      catch (error) { failure = error instanceof Error ? error : new Error('Invalid cache operation.'); tx.abort(); }
+    });
+  }
+  const readCurrent = () => transaction<string | null>('meta', 'readonly', (store, done, abort) => {
+    const request = store.get('state');
+    request.onsuccess = () => {
+      if (request.result != null) return done(request.result);
+      const marker = store.get('migration-complete');
+      marker.onsuccess = () => marker.result ? abort(new Error('Previously persisted replay state is missing.')) : done(null);
+    };
+  });
+  const loadState = async (): Promise<string | null> => {
+    const current = await readCurrent();
+    if (current !== null) { migrationChecked = true; return current; }
+    if (migrationChecked) return null;
+    // Only probe namespaces calculated for this origin/app/environment. Signed
+    // manifests with relative URLs alone cannot establish an old cache's origin.
+    const existing = typeof globalThis.indexedDB.databases === 'function' ? new Set((await indexedDB.databases()).map(db => db.name)) : null;
+    let selected: { scope: string; raw: string; sequence: number; payload: string } | undefined;
+    for (const scope of legacyNamespaces(config)) {
+      if (existing && !existing.has(`assetlib-v1-${scope}`)) continue;
+      const raw = await transaction<string | null>('meta', 'readonly', (store, done) => { const request = store.get('state'); request.onsuccess = () => done(request.result ?? null); }, false, scope);
+      if (raw === null) continue;
+      let state: ReturnType<typeof verifyStoredState>;
+      try { state = verifyStoredState(raw, config); } catch { continue; }
+      if (selected?.sequence === state.highestSequence && selected.payload !== state.history[0].payload) throw new Error('Conflicting legacy replay state.');
+      if (!selected || state.highestSequence > selected.sequence) selected = { scope, raw, sequence: state.highestSequence, payload: state.history[0].payload };
+    }
+    if (!selected) { migrationChecked = true; return readCurrent(); }
+    const source = selected;
+    const entries = await transaction<{ hash: string; bytes: ArrayBuffer; savedAt: number }[]>('images', 'readonly', (store, done) => {
+      const request = store.getAll(); request.onsuccess = () => done(request.result);
+    }, false, source.scope);
+    const migrated = await transaction<string>(['meta', 'images'], 'readwrite', (store, done, abort, tx) => {
+      // Recheck inside the destination write transaction: another tab may have
+      // migrated or accepted a newer release while legacy state was being read.
+      const request = store.get('state');
+      request.onsuccess = () => {
+        if (request.result != null) return done(request.result);
+        const marker = store.get('migration-complete');
+        marker.onsuccess = () => {
+          if (marker.result) return abort(new Error('Previously persisted replay state is missing.'));
+          const images = tx.objectStore('images');
+          // No release is active yet. Replace interrupted migration cache data
+          // and commit bounded bytes, replay state, and marker in one transaction.
+          images.clear();
+          let count = 0, bytes = 0;
+          for (const entry of entries) {
+            if (!entry || !/^[a-f0-9]{64}$/.test(entry.hash) || !(entry.bytes instanceof ArrayBuffer) || entry.bytes.byteLength > SDK_LIMITS.assetBytes || entry.bytes.byteLength < 1) continue;
+            if (count >= SDK_LIMITS.cacheEntries || bytes + entry.bytes.byteLength > SDK_LIMITS.cacheBytes) continue;
+            images.put({ hash: entry.hash, bytes: entry.bytes, savedAt: Number.isFinite(entry.savedAt) ? entry.savedAt : 0 });
+            count++; bytes += entry.bytes.byteLength;
+          }
+          store.put(source.raw, 'state'); store.put(true, 'migration-complete'); done(source.raw);
+        };
+      };
+    });
+    migrationChecked = true;
+    if (migrated === source.raw) {
+      try {
+        await transaction<void>('meta', 'readwrite', (store, done) => {
+          const request = store.get('state'); request.onsuccess = () => { if (request.result === source.raw) store.delete('state'); done(undefined); };
+        }, false, source.scope);
+      } catch { /* Destination is durable; a leftover source is never read again. */ }
+    }
+    return migrated;
+  };
+  return {
+    getOrCreateInstallId: (key, create) => transaction('meta', 'readwrite', (store, done, abort) => {
+      const storedKey = installStorageKey(key);
+      const request = store.get(storedKey);
+      request.onsuccess = () => {
+        try {
+          if (typeof request.result === 'string' && /^[a-f0-9]{32}$/.test(request.result)) return done(request.result);
+          const value = create();
+          if (!/^[a-f0-9]{32}$/.test(value)) return abort(new Error('Invalid random install ID.'));
+          store.put(value, storedKey); done(value);
+        } catch { abort(new Error('Could not persist the random install ID.')); }
+      };
+    }, true),
+    loadState,
+    saveState: async value => {
+      await loadState();
+      return transaction('meta', 'readwrite', (store, done, abort) => {
+        if (new TextEncoder().encode(value).length > SDK_LIMITS.stateBytes) return abort(new Error('State exceeds its bound.'));
+        const request = store.get('state');
+        request.onsuccess = () => {
+          try {
+            if (request.result) {
+              const previous = JSON.parse(request.result), next = JSON.parse(value);
+              if (previous.highestSequence > next.highestSequence || (previous.highestSequence === next.highestSequence && previous.history[0]?.payload !== next.history[0]?.payload)) return abort(new Error('A newer or conflicting sequence is already stored.'));
+            }
+            const persist = () => { store.put(value, 'state'); store.put(true, 'migration-complete'); done(undefined); };
+            if (request.result != null) return persist();
+            const marker = store.get('migration-complete');
+            marker.onsuccess = () => marker.result ? abort(new Error('Previously persisted replay state is missing.')) : persist();
+          } catch { abort(new Error('Existing replay state is corrupt.')); }
+        };
+      });
+    },
+    getAsset: hash => transaction('images', 'readonly', (store, done) => {
+      validateCacheKey(hash);
+      const request = store.get(hash);
+      request.onsuccess = () => { const bytes = request.result?.bytes; done(bytes instanceof ArrayBuffer && bytes.byteLength <= SDK_LIMITS.assetBytes ? new Uint8Array(bytes) : null); };
+    }),
+    putAsset: (hash, bytes) => transaction('images', 'readwrite', (store, done, abort) => {
+      validateCacheKey(hash);
+      if (bytes.length > SDK_LIMITS.assetBytes) return abort(new Error('Image exceeds the cache entry bound.'));
+      const request = store.getAll();
+      request.onsuccess = () => {
+        const entries = request.result.filter(entry => entry.hash !== hash).sort((a, b) => a.savedAt - b.savedAt);
+        let total = entries.reduce((sum, entry) => sum + entry.bytes.byteLength, 0);
+        while (entries.length >= SDK_LIMITS.cacheEntries || total + bytes.length > SDK_LIMITS.cacheBytes) { const oldest = entries.shift(); if (!oldest) break; total -= oldest.bytes.byteLength; store.delete(oldest.hash); }
+        store.put({ hash, bytes: bytes.slice().buffer, savedAt: Date.now() }); done(undefined);
+      };
+    }),
+  };
+}
+export async function imageUri(_config: AssetlibConfig, result: ResolvedAsset): Promise<ImageUri> {
+  if (!result.bytes) throw new Error('Missing verified image bytes.');
+  const uri = URL.createObjectURL(new Blob([result.bytes.slice().buffer as ArrayBuffer], { type: result.mime ?? 'image/webp' }));
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const image = new globalThis.Image();
+      const timer = setTimeout(() => { image.onload = image.onerror = null; image.src = ''; reject(new Error('Image decoding exceeded its deadline.')); }, 8000);
+      image.onload = () => {
+        clearTimeout(timer);
+        const valid = image.naturalWidth > 0 && image.naturalHeight > 0 && image.naturalWidth <= 8192 && image.naturalHeight <= 8192 && image.naturalWidth * image.naturalHeight <= 16777216 &&
+          (result.pixelWidth === undefined || (image.naturalWidth === result.pixelWidth && image.naturalHeight === result.pixelHeight));
+        valid ? resolve() : reject(new Error('Decoded image dimensions do not match the signed rendition.'));
+      };
+      image.onerror = () => { clearTimeout(timer); reject(new Error('The verified image could not be decoded.')); };
+      image.src = uri;
+    });
+    return { uri, release: () => URL.revokeObjectURL(uri) };
+  } catch (error) { URL.revokeObjectURL(uri); throw error; }
+}
+/** Verified clip bytes from IndexedDB, memory or the network as a Blob URL; the component releases it on unmount. */
+export async function videoUri(_config: AssetlibConfig, result: ResolvedVideo): Promise<ImageUri> {
+  if (result.source === 'poster' || !result.bytes?.length || result.bytes.length > SDK_LIMITS.videoBytes) throw new Error('Missing verified clip bytes.');
+  const uri = URL.createObjectURL(new Blob([result.bytes.slice().buffer as ArrayBuffer], { type: 'video/mp4' }));
+  return { uri, release: () => URL.revokeObjectURL(uri) };
+}

package/src/shared.ts

@@ -0,0 +1,50 @@
+import { hashBytes, SDK_LIMITS, storageNamespace, type AssetlibConfig, type ResolvedAsset } from '@assetlib/sdk-core';
+export const namespace = storageNamespace;
+
+/** Both shipped formulas, including a former single pin and either production route. */
+export function* legacyNamespaces(config: AssetlibConfig): Generator<string> {
+  const keys = [...new Set(config.pinnedPublicKeys ?? (config.pinnedPublicKey ? [config.pinnedPublicKey] : []))].sort();
+  const pins = new Set<string | undefined>([config.pinnedPublicKey, ...keys, keys.length === 1 ? keys[0] : JSON.stringify(keys)]);
+  const base = `${new URL(config.manifestUrl).origin}/api/delivery/${config.orgId}/${config.appId}`;
+  const urls = new Set([config.manifestUrl, `${base}/environments/${config.environment}/manifest`]);
+  if (config.environment === 'production') urls.add(`${base}/manifest`);
+  let probes = 0;
+  const scopes = function* (pin: string | undefined) {
+    for (const url of urls) {
+      if (++probes > 4096) throw new Error('Legacy namespace migration exceeds its probe limit.');
+      yield hashBytes(new TextEncoder().encode([url, config.orgId, config.appId, config.environment, pin].join('\n'))).slice(0, 32);
+    }
+  };
+  for (const pin of pins) yield* scopes(pin);
+  // An upgrade can coincide with adding pins. The old sorted-set formula may
+  // therefore describe any subset of the current set, including unused pins.
+  // Generate lazily within a fixed work budget. Exhaustion fails closed rather
+  // than silently treating an unsearched previous namespace as a fresh install.
+  const subsets = function* (start: number, subset: string[]): Generator<string> {
+    for (let i = start; i < keys.length; i++) {
+      const next = [...subset, keys[i]];
+      if (next.length > 1 && next.length < keys.length) yield* scopes(JSON.stringify(next));
+      yield* subsets(i + 1, next);
+    }
+  };
+  yield* subsets(0, []);
+}
+/** The core supplies an origin/org/app key independent of environment and signing key. */
+export const installStorageKey = (key: string): string => hashBytes(new TextEncoder().encode(key));
+export type ImageUri = { uri: string; release(): void };
+export function validateCacheKey(key: string): void { if (!/^[a-f0-9]{64}$/.test(key)) throw new Error('Invalid cache key.'); }
+
+/** Encodes only already verified raster bytes; no file or additional network request is created. */
+export function rasterDataUri(result: ResolvedAsset): ImageUri {
+  if (!result.bytes?.length || result.bytes.length > SDK_LIMITS.assetBytes || !['image/png', 'image/webp'].includes(result.mime ?? '')) throw new Error('Missing or unsupported verified raster bytes.');
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  const parts: string[] = [];
+  let part = '';
+  for (let offset = 0; offset < result.bytes.length; offset += 3) {
+    const a = result.bytes[offset], b = result.bytes[offset + 1], c = result.bytes[offset + 2];
+    part += alphabet[a >> 2] + alphabet[((a & 3) << 4) | ((b ?? 0) >> 4)] + (b === undefined ? '=' : alphabet[((b & 15) << 2) | ((c ?? 0) >> 6)]) + (c === undefined ? '=' : alphabet[c & 63]);
+    if (part.length >= 16384) { parts.push(part); part = ''; }
+  }
+  if (part) parts.push(part);
+  return { uri: `data:${result.mime};base64,${parts.join('')}`, release() {} };
+}

package/src/telemetry.ts

@@ -0,0 +1,68 @@
+import { AppState, Platform } from 'react-native';
+import type { AssetClient, ClientOptions } from '@assetlib/sdk-core';
+
+declare const require: (name: string) => unknown;
+type Telemetry = NonNullable<ClientOptions['telemetry']>;
+type OptionalModule = {
+  default?: OptionalModule;
+  nativeApplicationVersion?: unknown;
+  nativeBuildVersion?: unknown;
+  nativeAppVersion?: unknown;
+  expoConfig?: { version?: unknown; ios?: { buildNumber?: unknown }; android?: { versionCode?: unknown } };
+};
+
+function optionalApplication(): OptionalModule | undefined {
+  try {
+    // Expo Metro marks literal requires directly in try/catch as optional.
+    const value = require('expo-application') as OptionalModule | undefined;
+    return value?.default ?? value;
+  } catch { return undefined; }
+}
+
+function optionalConstants(): OptionalModule | undefined {
+  try {
+    const value = require('expo-constants') as OptionalModule | undefined;
+    return value?.default ?? value;
+  } catch { return undefined; }
+}
+
+function runtimeBuild(): Telemetry['build'] {
+  try {
+    const application = optionalApplication();
+    const constants = optionalConstants();
+    const os = Platform?.OS;
+    const platform = os === 'ios' || os === 'android' || os === 'web' ? os : 'expo';
+    const appVersion = application?.nativeApplicationVersion ?? constants?.nativeAppVersion ?? constants?.expoConfig?.version;
+    const nativeBuild = application?.nativeBuildVersion ?? constants?.nativeBuildVersion;
+    const configuredBuild = os === 'ios' ? constants?.expoConfig?.ios?.buildNumber : os === 'android' ? constants?.expoConfig?.android?.versionCode : undefined;
+    const buildNumber = nativeBuild ?? configuredBuild;
+    if (typeof appVersion === 'string' && /^[A-Za-z0-9._+-]{1,64}$/.test(appVersion) && !/\s/.test(appVersion) &&
+      (typeof buildNumber === 'string' || typeof buildNumber === 'number') && /^[A-Za-z0-9._+-]{1,64}$/.test(String(buildNumber)) && !/\s/.test(String(buildNumber))) {
+      return { platform, appVersion, buildNumber: String(buildNumber) };
+    }
+  } catch { /* Optional module getters and native bridges can also throw. */ }
+  return undefined;
+}
+
+export function expoTelemetry(telemetry: ClientOptions['telemetry']): ClientOptions['telemetry'] {
+  if (!telemetry?.enabled) return telemetry;
+  return {
+    ...telemetry,
+    sdk: telemetry.sdk ?? { name: 'sdk-expo', version: '0.6.0-preview.1' },
+    build: telemetry.build ?? runtimeBuild() ?? { platform: 'expo', appVersion: 'unknown', buildNumber: 'unknown' },
+  };
+}
+
+export function flushOnBackground(client: AssetClient): void {
+  try {
+    const subscription = AppState?.addEventListener?.('change', state => {
+      if (state === 'background') void client.flush().catch(() => {});
+    });
+    if (!subscription) return;
+    const dispose = client.dispose.bind(client);
+    client.dispose = () => {
+      try { subscription.remove(); } catch { /* Teardown must not affect the client. */ }
+      dispose();
+    };
+  } catch { /* AppState is optional in non-native renderers. */ }
+}

package/src/video.tsx

@@ -0,0 +1,118 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { AccessibilityInfo, AppState, StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+import { useVideoPlayer, VideoView, type VideoContentFit } from 'expo-video';
+import type { AssetRef } from '@assetlib/sdk-core';
+import { AssetlibImage, type AssetlibImageProps } from './index';
+import { videoUri } from './platform';
+import type { ImageUri } from './shared';
+
+export type AssetlibVideoProps<R extends AssetRef = AssetRef> = AssetlibImageProps<R> & {
+  /** Show the poster instead of playing, for example while the view is off screen. */
+  paused?: boolean;
+};
+
+/** At most two clips play at once across every AssetlibVideo; the others show their poster until a slot frees. */
+const maxPlaying = 2;
+let playing = 0;
+const waiting: (() => void)[] = [];
+function acquirePlaybackSlot(granted: () => void): () => void {
+  let state: 'waiting' | 'playing' | 'released' = 'waiting';
+  const start = () => { state = 'playing'; playing++; granted(); };
+  if (playing < maxPlaying) start(); else waiting.push(start);
+  return () => {
+    if (state === 'waiting') waiting.splice(waiting.indexOf(start), 1);
+    else if (state === 'playing') { playing--; while (playing < maxPlaying && waiting.length) waiting.shift()!(); }
+    state = 'released';
+  };
+}
+
+/** Unknown counts as reduced: no clip plays until the system says motion is allowed. */
+function useReduceMotion(): boolean {
+  const [reduced, setReduced] = useState<boolean | null>(null);
+  useEffect(() => {
+    let mounted = true;
+    const subscription = AccessibilityInfo.addEventListener('reduceMotionChanged', enabled => setReduced(enabled !== false));
+    AccessibilityInfo.isReduceMotionEnabled().then(enabled => { if (mounted) setReduced(value => value ?? enabled !== false); }, () => { if (mounted) setReduced(value => value ?? true); });
+    return () => { mounted = false; subscription?.remove(); };
+  }, []);
+  return reduced !== false;
+}
+
+function useAppActive(): boolean {
+  const [state, setState] = useState<string | null | undefined>(() => AppState.currentState);
+  useEffect(() => {
+    try { const subscription = AppState.addEventListener('change', setState); return () => subscription.remove(); }
+    catch { return undefined; }
+  }, []);
+  return state !== 'background' && state !== 'inactive';
+}
+
+const videoFit = (fit: AssetlibImageProps['contentFit']): VideoContentFit => fit === 'contain' || fit === 'fill' ? fit : fit === 'none' || fit === 'scale-down' ? 'contain' : 'cover';
+type PlayableElement = { play?: () => Promise<void> | void };
+
+function LoopingClip({ uri, contentFit, onFirstFrame, onFailure }: { uri: string; contentFit: VideoContentFit; onFirstFrame: () => void; onFailure: () => void }) {
+  const view = useRef<VideoView>(null);
+  const callbacks = useRef({ onFirstFrame, onFailure });
+  callbacks.current = { onFirstFrame, onFailure };
+  const player = useVideoPlayer(uri, created => { created.loop = true; created.muted = true; created.keepScreenOnWhilePlaying = false; });
+  useEffect(() => {
+    let mounted = true;
+    const fail = () => { if (mounted) callbacks.current.onFailure(); };
+    const subscription = player.addListener('statusChange', ({ status }) => { if (status === 'error') fail(); });
+    try {
+      if (player.status === 'error') fail();
+      // On web, VideoView exposes its <video> element, whose play() promise rejects when autoplay is blocked.
+      const element = (view.current as unknown as { nativeRef?: { current?: PlayableElement | null } } | null)?.nativeRef?.current;
+      if (typeof element?.play === 'function') Promise.resolve(element.play()).catch(fail);
+      else player.play();
+    } catch { fail(); }
+    return () => { mounted = false; subscription.remove(); };
+  }, [player]);
+  return <VideoView ref={view} player={player} nativeControls={false} contentFit={contentFit} allowsPictureInPicture={false} playsInline style={StyleSheet.absoluteFill} onFirstFrameRender={() => callbacks.current.onFirstFrame()} />;
+}
+
+/**
+ * The placement's poster (an AssetlibImage, bundled fallback first) with its signed short looping clip over it.
+ * The clip resolves and plays only while motion is allowed, the app is active, `paused` is false and this view
+ * holds one of the two playback slots. It plays muted and looping with no controls; any failure shows the poster
+ * until the request (client, asset, revision or cache policy) changes. `style` sizes the container.
+ */
+export function AssetlibVideo<R extends AssetRef>({ paused = false, ...props }: AssetlibVideoProps<R>) {
+  const { client, asset, cachePolicy, revision = 0, style, contentFit } = props;
+  const reduceMotion = useReduceMotion();
+  const active = useAppActive();
+  const request = useMemo(() => ({}), [client, asset.key, asset.width, asset.height, revision, cachePolicy]);
+  const [failed, setFailed] = useState<object | null>(null);
+  const wantsSlot = !paused && !reduceMotion && active && failed !== request;
+  const [slot, setSlot] = useState(false);
+  useEffect(() => {
+    if (!wantsSlot) return;
+    const release = acquirePlaybackSlot(() => setSlot(true));
+    return () => { release(); setSlot(false); };
+  }, [wantsSlot]);
+  const [clip, setClip] = useState<{ request: object; media: ImageUri } | null>(null);
+  useEffect(() => () => clip?.media.release(), [clip]);
+  useEffect(() => {
+    if (clip && clip.request !== request) { setClip(null); return; }
+    if (clip || !wantsSlot || !slot) return;
+    const controller = new AbortController();
+    client.resolveVideo(asset, { cachePolicy, signal: controller.signal }).then(async result => {
+      if (controller.signal.aborted) return;
+      if (result.source === 'poster') { setFailed(request); return; }
+      const media = await videoUri(client.config, result);
+      if (controller.signal.aborted) { media.release(); return; }
+      setClip({ request, media });
+    }).catch(() => { if (!controller.signal.aborted) setFailed(request); });
+    return () => controller.abort();
+  }, [client, request, wantsSlot, slot, clip]);
+  const play = wantsSlot && slot && clip?.request === request;
+  const [frame, setFrame] = useState(false);
+  useEffect(() => { if (!play) setFrame(false); }, [play]);
+  const poster = { ...props, style: [StyleSheet.absoluteFill, { opacity: play && frame ? 0 : 1 }] } as AssetlibImageProps<R>;
+  return (
+    <View style={[{ overflow: 'hidden' }, style as StyleProp<ViewStyle>]}>
+      {play && <LoopingClip uri={clip!.media.uri} contentFit={videoFit(contentFit)} onFirstFrame={() => setFrame(true)} onFailure={() => { setFailed(request); setClip(null); }} />}
+      <AssetlibImage<R> {...poster} />
+    </View>
+  );
+}