@assetlib/sdk-core 0.5.3-preview.1 → 0.6.0-preview.1

package/README.md

@@ -202,6 +202,27 @@ Limits: UTF-8 JSON up to 512 KiB, dimensions 1–2048, at most 4,194,304 pixels,
 
 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.
 
+## Short looping video
+
+A placement can carry a short, muted, looping MP4 clip beside its required still poster. `resolveVideo` is explicit; ordinary `resolve(ref)` never downloads a clip. This has been checked only by Node unit tests; it has not been verified on a device, simulator or emulator.
+
+```ts
+const clip = await client.resolveVideo(AppAssets.Cards.gold, { signal });
+if (clip.source === 'poster') {
+  // Show the poster: ordinary client.resolve(ref), then the bundled fallback.
+} else {
+  // clip.uri (file-backed adapters) or clip.bytes: a verified MP4 for the app's player.
+}
+```
+
+Success returns `{ source: 'remote' | 'cache', sequence, message, sha256, assetId, mime: 'video/mp4', width, height, durationMs, frameRate, bytes?, uri? }`; anything else returns `{ source: 'poster', sequence: null, message }`. Only the base placement's clip is used, never a variant cell or state member.
+
+- **Signed descriptor.** The optional top-level `videoSchemaVersion: 1` enables `video` on base placements: `format: 'mp4'`, `profile: 'h264-loop-v1'`, `mime: 'video/mp4'`, lowercase SHA-256, `bytes` 1–4,194,304 (`SDK_LIMITS.videoBytes`), even integer `width` and `height` of 16–1280 with at most 921,600 pixels and exactly the placement's aspect ratio, integer `durationMs` of 1,000–10,000, a finite `frameRate` of 1–30, and the exact same-origin URL `/api/delivery/{orgId}/{appId}/assets/{assetId}/videos/{sha256}` with no credentials, query or fragment. Any other `videoSchemaVersion` (including `null`), `video` without the marker, `video` together with `animation`, or `video` on a state member, variant cell or catalog page image rejects the release. Clients without video support ignore both fields and keep the poster.
+- **Checks before use.** Length and SHA-256 must match, then a bounded header check: `ftyp` first, `moov` before the first `mdat`, no `moof` or `mvex`, one track whose one sample entry is `avc1` at the signed width and height. No frame is decoded; the platform player still has to decode the clip. Cached clips are rehashed and rechecked on every read.
+- **Releases.** Only the current release downloads. If it has no clip for the placement, the result is the poster. If its clip can't be used (download failure or timeout, a failed check, or a missing cached file offline), verified cached clips of the same placement from older retained releases are tried newest first, without downloading, then the poster.
+- **Deadline.** Clips have their own deadline, `videoTimeoutMs` (default 30,000 ms, 20–30,000), separate from the image `timeoutMs`. Clip downloads share the client's concurrent transfer limit (default 4) with images. `signal` cancels.
+- **Storage.** Clips are cached under their SHA-256 through the storage adapter with `StorageMime` `'video/mp4'`, inside the same 50 MiB / 100 entry budget. An adapter that implements `getAssetFileUri(cacheKey, mime)` declares that its player opens files: `resolveVideo` then returns `uri` instead of `bytes`, and returns the poster under the `memory` and `none` policies without downloading. Otherwise `bytes` are returned under every policy.
+
 ## 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.
@@ -209,7 +230,7 @@ Verified cached animation works offline. Only the current descriptor may trigger
 - 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.
+- Default deadline: 8 seconds per request; configurable from 20 milliseconds to 30 seconds. Clips use `videoTimeoutMs` instead (default 30 seconds, same range). Maximum manifest response: 256 KiB. Maximum image: 8 MiB. Maximum clip: 4 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.
@@ -224,7 +245,7 @@ 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.
+Tests include the shared cross-platform contract corpus (`test/fixtures/shared`, byte-identical with the Swift and Kotlin SDKs' copies: 142 signed manifest cases, 43 public config cases exercised as strings and objects, 18 appearance/arm resolution cases, 10 tintable icon rendering cases, 2 video resolution and 2 video byte-failure 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, clip header checks, current-only clip downloads, cache-only clip history and the clip deadline, 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
 

package/dist/delivery.js

@@ -12,6 +12,9 @@ export function validateRendering(value) {
 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.');
+    // Clips belong to base placements only: never to state members, variant cells or catalog page images.
+    if ('video' in value)
+        throw new Error('Video is allowed only on a base placement.');
     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.');

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { AssetlibConfig, AssetRef, AssetPage, AssetPageOptions, AssetPagePayload, DynamicAssetRef, FallbackReason, StateSetRef, ResolvedStateSet, ClientOptions, ClientStatus, ManifestPayload, RefreshResult, ResolvedAsset, ResolvedAnimation, ResolveOptions, SignedManifest } from './types.js';
+import type { AssetlibConfig, AssetRef, AssetPage, AssetPageOptions, AssetPagePayload, DynamicAssetRef, FallbackReason, StateSetRef, ResolvedStateSet, ClientOptions, ClientStatus, ManifestPayload, RefreshResult, ResolvedAsset, ResolvedAnimation, ResolvedVideo, ResolveOptions, ResolveVideoOptions, SignedManifest } from './types.js';
 export type * from './types.js';
 export { selectAssetCandidates } from './renditions.js';
 export { validateLottie, validateLottieMetadata, LOTTIE_LIMITS } from './lottie.js';
@@ -16,6 +16,7 @@ export declare const SDK_LIMITS: Readonly<{
     stateBytes: number;
     cacheBytes: number;
     cacheEntries: 100;
+    videoBytes: number;
 }>;
 export declare const hashBytes: (bytes: Uint8Array) => string;
 export declare function parsePublicConfig(input: unknown, options?: {
@@ -49,6 +50,7 @@ export declare class AssetClient {
     private reporter?;
     private queue;
     private timeoutMs;
+    private videoTimeoutMs;
     private decisionTimeoutMs;
     private fetcher;
     private formats;
@@ -88,6 +90,8 @@ export declare class AssetClient {
     resolveAsset(ref: DynamicAssetRef, options?: ResolveOptions): Promise<ResolvedAsset>;
     /** Explicit opt-in. Image resolution never downloads an animation. */
     resolveAnimation(ref: AssetRef, options?: ResolveOptions): Promise<ResolvedAnimation>;
+    /** Explicit opt-in. Image resolution never downloads a clip. Uses the base placement only. */
+    resolveVideo(ref: AssetRef, options?: ResolveVideoOptions): Promise<ResolvedVideo>;
     private validBytes;
 }
 export declare function createAssetClient(config: AssetlibConfig, options: ClientOptions): AssetClient;

package/dist/index.js

@@ -6,12 +6,13 @@ import { ObservationReporter } from './telemetry.js';
 import { selectAssetCandidates, supportedFormats, targetPixels, validRenditionHeader, validateRenditions } from './renditions.js';
 export { selectAssetCandidates } from './renditions.js';
 import { validateAnimationExtension, verifiedAnimationData } from './animations.js';
+import { checkMp4Header, validateVideoExtension, VIDEO_BYTES } from './video.js';
 export { validateLottie, validateLottieMetadata, LOTTIE_LIMITS } from './lottie.js';
 export { selectCatalogReferences } from './catalog.js';
 import { assetIdPattern, catalogForSequence, validateAssetPage, validateDeliveryExtensions, validateRendering, validStateRef } from './delivery.js';
 import { validateAccessibility } from './accessibility.js';
 export { resolveAccessibilityDescription, validateAccessibility } from './accessibility.js';
-export const SDK_LIMITS = Object.freeze({ configBytes: 4096, pinnedKeys: 16, publicKeyBytes: 256, manifestBytes: 256 * 1024, assetBytes: 8 * 1024 * 1024, slots: 100, retainedReleases: 8, stateBytes: 3 * 1024 * 1024, cacheBytes: 50 * 1024 * 1024, cacheEntries: 100 });
+export const SDK_LIMITS = Object.freeze({ configBytes: 4096, pinnedKeys: 16, publicKeyBytes: 256, manifestBytes: 256 * 1024, assetBytes: 8 * 1024 * 1024, slots: 100, retainedReleases: 8, stateBytes: 3 * 1024 * 1024, cacheBytes: 50 * 1024 * 1024, cacheEntries: 100, videoBytes: VIDEO_BYTES });
 const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
 const hashPattern = /^[a-f0-9]{64}$/;
 const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
@@ -120,6 +121,7 @@ export function verifySignedManifest(input, config) {
             return fail('Asset URL is outside the configured app.');
         validateRenditions(payload, value, config);
         validateAnimationExtension(payload, value, config);
+        validateVideoExtension(payload, value, config);
         if ('accessibility' in value)
             validateAccessibility(value.accessibility);
         validateRendering(value);
@@ -255,6 +257,7 @@ export class AssetClient {
     reporter;
     queue = Promise.resolve();
     timeoutMs;
+    videoTimeoutMs;
     decisionTimeoutMs;
     fetcher;
     formats;
@@ -275,6 +278,9 @@ export class AssetClient {
         this.timeoutMs = options.timeoutMs ?? 8000;
         if (!integer(this.timeoutMs, 20, 30000))
             fail('timeoutMs must be between 20 and 30000.');
+        this.videoTimeoutMs = options.videoTimeoutMs ?? 30000;
+        if (!integer(this.videoTimeoutMs, 20, 30000))
+            fail('videoTimeoutMs must be between 20 and 30000.');
         this.decisionTimeoutMs = options.decisionTimeoutMs === undefined ? 1500 : options.decisionTimeoutMs;
         if (!integer(this.decisionTimeoutMs, 100, 10000))
             fail('decisionTimeoutMs must be between 100 and 10000.');
@@ -680,6 +686,70 @@ export class AssetClient {
         }
         return { source: 'poster', sequence: null, message: `Use the still poster. ${message}` };
     }
+    /** Explicit opt-in. Image resolution never downloads a clip. Uses the base placement only. */
+    async resolveVideo(ref, options = {}) {
+        if (!validKey(ref.key) || !integer(ref.width, 1, 8192) || !integer(ref.height, 1, 8192))
+            throw new Error('Invalid generated asset reference.');
+        const policy = cachePolicy(options.cachePolicy ?? this.policy);
+        throwIfAborted(options.signal);
+        const history = await this.snapshot();
+        throwIfAborted(options.signal);
+        const storage = this.options.storage;
+        const files = typeof storage.getAssetFileUri === 'function';
+        const poster = (message) => ({ source: 'poster', sequence: null, message: `Use the still poster. ${message}` });
+        if (files && policy !== 'disk')
+            return poster('This platform plays clips from local files, which needs the disk cache policy.');
+        let message = this.storageFailure ?? 'No compatible published clip is available.';
+        for (let index = 0; index < history.length; index++) {
+            const { payload } = history[index];
+            const slot = payload.slots.find(item => item.key === ref.key && item.width === ref.width && item.height === ref.height);
+            const video = slot?.video;
+            // Removing a clip is intentional publication state, not a failed download.
+            if (index === 0 && !video)
+                return { source: 'poster', sequence: null, message: 'The current release has no compatible clip. Use the still poster.' };
+            if (!slot || !video)
+                continue;
+            const verify = (bytes) => {
+                if (bytes.byteLength !== video.bytes || hashBytes(bytes) !== video.sha256)
+                    throw new Error('Clip bytes do not match the signed manifest.');
+                checkMp4Header(bytes, video.width, video.height);
+            };
+            const result = async (source, bytes) => {
+                const uri = files ? await storage.getAssetFileUri(video.sha256, video.mime) : null;
+                if (files && typeof uri !== 'string')
+                    throw new Error('The verified clip is not available as a local file.');
+                return { source, sequence: payload.sequence, message: index ? `Using verified clip from release ${payload.sequence}. ${message}` : source === 'cache' ? 'Verified clip loaded from the local cache.' : 'Downloaded clip; signature, hash and MP4 header verified.',
+                    sha256: video.sha256, assetId: slot.assetId, mime: 'video/mp4', width: video.width, height: video.height, durationMs: video.durationMs, frameRate: video.frameRate, ...(files ? { uri: uri } : { bytes }) };
+            };
+            try {
+                const cached = await this.cached(video.sha256, policy);
+                throwIfAborted(options.signal);
+                if (cached) {
+                    try {
+                        verify(cached);
+                        return await result('cache', cached);
+                    }
+                    catch (error) {
+                        message = error instanceof Error ? error.message : 'Cached clip is invalid.';
+                    }
+                }
+                // Older releases may be used only when already cached and reverified.
+                if (index !== 0)
+                    continue;
+                const bytes = await this.withTransfer(() => fetchBounded(this.fetcher, new URL(video.url, this.config.manifestUrl).href, video.bytes, this.videoTimeoutMs, video.mime, options.signal, policy !== 'disk'), options.signal);
+                throwIfAborted(options.signal);
+                verify(bytes);
+                await this.retain(video.sha256, bytes, video.mime, policy);
+                throwIfAborted(options.signal);
+                return await result('remote', bytes);
+            }
+            catch (error) {
+                throwIfAborted(options.signal);
+                message = error instanceof Error ? error.message : 'Clip could not be loaded.';
+            }
+        }
+        return poster(message);
+    }
     validBytes(bytes, candidate) {
         return bytes.byteLength === candidate.bytes && bytes.byteLength <= SDK_LIMITS.assetBytes && hashBytes(bytes) === candidate.sha256 && validRenditionHeader(bytes, candidate);
     }

package/dist/telemetry.js

@@ -28,7 +28,7 @@ export class ObservationReporter {
         this.fetcher = fetcher;
         this.interval = boundedInteger(options.flushIntervalMs, 60_000, 2_147_483_647);
         this.maxBatch = boundedInteger(options.maxBatch, 200, 200);
-        const sdk = options.sdk ?? { name: 'sdk-core', version: '0.5.3-preview.1' };
+        const sdk = options.sdk ?? { name: 'sdk-core', version: '0.6.0-preview.1' };
         const build = options.build ?? { platform: 'web', appVersion: 'unknown', buildNumber: 'unknown' };
         if (!version(sdk.name) || !version(sdk.version) || !['ios', 'android', 'web', 'expo'].includes(build.platform) || !version(build.appVersion) || !version(build.buildNumber) || (options.installId !== undefined && !validId(options.installId)))
             throw new Error('Invalid observation configuration.');

package/dist/types.d.ts

@@ -55,8 +55,8 @@ export type AssetStatus = {
     assetId?: string;
 };
 export type AssetMime = 'image/webp' | 'image/png' | 'image/svg+xml';
-/** Cache transport MIME types; animation is never an image format candidate. */
-export type StorageMime = AssetMime | 'application/json';
+/** Cache transport MIME types; animation and video are never image format candidates. */
+export type StorageMime = AssetMime | 'application/json' | 'video/mp4';
 export type ResolvedAsset = AssetStatus & {
     bytes?: Uint8Array;
     mime?: AssetMime;
@@ -102,6 +102,42 @@ export type ResolvedAnimation = {
     inPoint: number;
     outPoint: number;
 };
+export type VideoDescriptor = {
+    format: 'mp4';
+    profile: 'h264-loop-v1';
+    mime: 'video/mp4';
+    sha256: string;
+    url: string;
+    bytes: number;
+    width: number;
+    height: number;
+    durationMs: number;
+    frameRate: number;
+};
+export type ResolvedVideo = {
+    source: 'poster';
+    sequence: null;
+    message: string;
+} | {
+    source: 'cache' | 'remote';
+    sequence: number;
+    message: string;
+    sha256: string;
+    assetId: string;
+    mime: 'video/mp4';
+    width: number;
+    height: number;
+    durationMs: number;
+    frameRate: number;
+    /** Verified clip bytes, when the storage adapter has no `getAssetFileUri`. */
+    bytes?: Uint8Array;
+    /** Local file URI of the verified cached clip, from a storage adapter with `getAssetFileUri`. */
+    uri?: string;
+};
+export type ResolveVideoOptions = {
+    cachePolicy?: CachePolicy;
+    signal?: AbortSignal;
+};
 export type ResolveOptions = {
     pixelWidth?: number;
     pixelHeight?: number;
@@ -168,6 +204,7 @@ export type ManifestSlot = AssetDescriptor & {
     width: number;
     height: number;
     animation?: AnimationDescriptor;
+    video?: VideoDescriptor;
     states?: Record<string, AssetDescriptor>;
     defaultState?: string;
     variants?: AssetVariants;
@@ -195,6 +232,7 @@ export type ManifestPayload = {
     schemaVersion: 1;
     renditionSchemaVersion?: 1;
     animationSchemaVersion?: 1;
+    videoSchemaVersion?: 1;
     stateSchemaVersion?: 1;
     catalogSchemaVersion?: 1;
     variantSchemaVersion?: 1;
@@ -220,6 +258,9 @@ export type AssetStorage = {
     /** Opaque 64-hex identity; arm/appearance-scoped keys are not the content SHA-256. */
     getAsset(cacheKey: string): Promise<Uint8Array | null>;
     putAsset(cacheKey: string, bytes: Uint8Array, mime?: StorageMime): Promise<void>;
+    /** Optional: the local file URI of a cached entry, or null. An adapter with this method plays clips from
+     * files, so `resolveVideo` returns `uri` instead of bytes and needs the `disk` cache policy. */
+    getAssetFileUri?(cacheKey: string, mime: StorageMime): Promise<string | null>;
 };
 export type FallbackReason = 'offline' | 'verification' | 'decode' | 'missing' | 'other';
 export type TelemetryBuild = {
@@ -242,7 +283,8 @@ export type ClientOptions = {
     storage: AssetStorage;
     fetch?: typeof globalThis.fetch;
     allowInsecureLoopback?: boolean;
-    timeoutMs?: number; /** Decision callback deadline in milliseconds: 100-10000, default 1500. */
+    timeoutMs?: number; /** Clip download deadline in milliseconds: 20-30000, default 30000. */
+    videoTimeoutMs?: number; /** Decision callback deadline in milliseconds: 100-10000, default 1500. */
     decisionTimeoutMs?: number;
     cachePolicy?: CachePolicy;
     maxConcurrentDownloads?: number;

package/dist/video.d.ts

@@ -0,0 +1,9 @@
+import type { AssetlibConfig } from './types.js';
+/** Largest signed clip, `SDK_LIMITS.videoBytes`. */
+export declare const VIDEO_BYTES: number;
+/** Optional `videoSchemaVersion: 1` and a `video` descriptor on a base placement (envelope `h264-loop-v1`). */
+export declare function validateVideoExtension(payload: Record<string, unknown>, slot: Record<string, unknown>, config: AssetlibConfig): void;
+/** Bounded structural check, run only after byte count and SHA-256 matched: `ftyp` first, `moov` before
+ * the first `mdat`, not fragmented, and one track whose one sample entry is `avc1` at the signed size.
+ * It decodes no frames; the platform player still has to decode the clip. */
+export declare function checkMp4Header(bytes: Uint8Array, width: number, height: number): void;

package/dist/video.js

@@ -0,0 +1,96 @@
+/** Largest signed clip, `SDK_LIMITS.videoBytes`. */
+export const VIDEO_BYTES = 4 * 1024 * 1024;
+const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const integer = (value, min, max) => Number.isSafeInteger(value) && Number(value) >= min && Number(value) <= max;
+const dimension = (value) => integer(value, 16, 1280) && value % 2 === 0;
+/** Optional `videoSchemaVersion: 1` and a `video` descriptor on a base placement (envelope `h264-loop-v1`). */
+export function validateVideoExtension(payload, slot, config) {
+    if (own(payload, 'videoSchemaVersion') && payload.videoSchemaVersion !== 1)
+        throw new Error('Unsupported video schema.');
+    if (!own(slot, 'video'))
+        return;
+    const v = slot.video;
+    if (payload.videoSchemaVersion !== 1 || !record(v) || v.format !== 'mp4' || v.profile !== 'h264-loop-v1' || v.mime !== 'video/mp4' || typeof v.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(v.sha256) || typeof v.url !== 'string' || !integer(v.bytes, 1, VIDEO_BYTES))
+        throw new Error('Invalid signed video descriptor.');
+    if (!dimension(v.width) || !dimension(v.height) || v.width * v.height > 921600)
+        throw new Error('Video dimensions must be even, 16–1280, and at most 921,600 pixels.');
+    if (!integer(v.durationMs, 1000, 10000) || typeof v.frameRate !== 'number' || !Number.isFinite(v.frameRate) || v.frameRate < 1 || v.frameRate > 30)
+        throw new Error('Video timing must be 1,000–10,000 ms at 1–30 fps.');
+    if (own(slot, 'animation'))
+        throw new Error('A placement cannot carry both an animation and a video.');
+    if (v.width * Number(slot.height) !== v.height * Number(slot.width))
+        throw new Error('Video aspect ratio does not exactly match the placement.');
+    const url = new URL(v.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}/videos/${v.sha256}`)
+        throw new Error('Video URL is outside the configured app.');
+}
+const headerFailure = (message) => { throw new Error(`Clip header check failed: ${message}`); };
+function children(bytes, view, start, end, budget) {
+    const result = [];
+    for (let offset = start; offset < end;) {
+        if (--budget.boxes < 0)
+            headerFailure('too many boxes.');
+        if (end - offset < 8)
+            headerFailure('truncated box header.');
+        let size = view.getUint32(offset), header = 8;
+        if (size === 1) {
+            if (end - offset < 16)
+                headerFailure('truncated box header.');
+            size = view.getUint32(offset + 8) * 2 ** 32 + view.getUint32(offset + 12);
+            header = 16;
+        }
+        else if (size === 0)
+            size = end - offset;
+        if (size < header || size > end - offset)
+            headerFailure('a box overruns its parent.');
+        result.push({ type: String.fromCharCode(...bytes.subarray(offset + 4, offset + 8)), body: offset + header, end: offset + size });
+        offset += size;
+    }
+    return result;
+}
+/** Bounded structural check, run only after byte count and SHA-256 matched: `ftyp` first, `moov` before
+ * the first `mdat`, not fragmented, and one track whose one sample entry is `avc1` at the signed size.
+ * It decodes no frames; the platform player still has to decode the clip. */
+export function checkMp4Header(bytes, width, height) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (bytes.byteLength < 8 || String.fromCharCode(...bytes.subarray(4, 8)) !== 'ftyp')
+        headerFailure('the file must start with ftyp.');
+    const budget = { boxes: 1024 };
+    const top = children(bytes, view, 0, bytes.byteLength, budget);
+    let moov;
+    let mdat = false;
+    for (const box of top) {
+        if (box.type === 'moof')
+            headerFailure('fragmented MP4 is not supported.');
+        if (box.type === 'moov') {
+            if (moov)
+                headerFailure('more than one moov.');
+            moov = box;
+        }
+        if (box.type === 'mdat') {
+            if (!moov)
+                headerFailure('moov must come before mdat.');
+            mdat = true;
+        }
+    }
+    if (!moov || !mdat)
+        headerFailure('moov and mdat are required.');
+    const only = (parent, type) => {
+        const found = children(bytes, view, parent.body, parent.end, budget).filter(box => box.type === type);
+        return found.length === 1 ? found[0] : headerFailure(`expected exactly one ${type}.`);
+    };
+    if (children(bytes, view, moov.body, moov.end, budget).some(box => box.type === 'mvex'))
+        headerFailure('fragmented MP4 is not supported.');
+    const stsd = only(only(only(only(only(moov, 'trak'), 'mdia'), 'minf'), 'stbl'), 'stsd');
+    if (stsd.end - stsd.body < 8 || view.getUint32(stsd.body + 4) !== 1)
+        headerFailure('expected exactly one sample entry.');
+    const entries = children(bytes, view, stsd.body + 8, stsd.end, budget);
+    if (entries.length !== 1 || entries[0].type !== 'avc1')
+        headerFailure('the sample entry must be avc1.');
+    // VisualSampleEntry: 8 bytes SampleEntry, 16 bytes predefined/reserved, then 16-bit width and height.
+    if (entries[0].end - entries[0].body < 28)
+        headerFailure('truncated avc1 sample entry.');
+    if (view.getUint16(entries[0].body + 24) !== width || view.getUint16(entries[0].body + 26) !== height)
+        headerFailure('avc1 dimensions do not match the signed descriptor.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assetlib/sdk-core",
-  "version": "0.5.3-preview.1",
+  "version": "0.6.0-preview.1",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",