@assetlib/sdk-expo 0.7.6-preview.1 → 0.7.7-preview.1

package/README.md

@@ -26,8 +26,6 @@ await client.refresh(); // Explicit network check.
   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)}
@@ -36,7 +34,11 @@ await client.refresh(); // Explicit network check.
 
 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.
+### Sizing
+
+A placement's width and height are a reference size: they fix the aspect ratio and identify the placement; the SDK sizes requests from the view. Without `pixelWidth` and `pixelHeight`, `AssetlibImage` and `AssetlibStateImage` request the view's measured layout (`onLayout`) × `PixelRatio.get()`, enough to cover the view (to fit it for `contentFit` `contain` or `scale-down`), rounded up to the console's rendition tiers: 512, 1024 or 2048 pixels on the long edge, or 24, 48, 72, 96, 192 or 512 for tintable icons. The request asks for 98% of the tier, so a rendition a few pixels short of its tier still serves it, and an unusual aspect ratio whose rendition falls further short gets the next larger one. A new view starts from the largest tier this client has measured for the placement, else from the reference size × `PixelRatio.get()`; its first layout replaces that reference-based estimate, so a first mount can resolve twice (`decide` and `onStatus` run again). After that a view's tier only grows, so rotating or resizing for split view never requests a smaller image; growing into a larger tier starts a new resolution, which shows the bundled fallback until the larger image is ready. Pass both `pixelWidth` and `pixelHeight` to request exact pixels instead. `AssetlibDynamicImage` keeps requesting its reference's own size unless you pass them.
+
+`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, 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
 
@@ -72,7 +74,7 @@ Declare `"rendering": "template"` on a catalog placement and regenerate its refe
 
 - 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.
+- Without `pixelWidth` and `pixelHeight`, a template reference requests the measured view × `PixelRatio.get()` on the icon tiers ([Sizing](#sizing)), so small icons stay sharp.
 - 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
@@ -188,7 +190,7 @@ Caches and durable replay state are isolated by manifest origin, organization, a
 
 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.
+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. PNG/WebP renditions are selected by requested pixel size ([Sizing](#sizing)); the placement's reference 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
 
@@ -237,7 +239,7 @@ await client.flush();
 client.dispose(); // Remove the AppState listener and stop observation timers.
 ```
 
-The adapter identifies itself as `sdk-expo` version `0.7.6-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`.
+The adapter identifies itself as `sdk-expo` version `0.7.7-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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assetlib/sdk-expo",
-  "version": "0.7.6-preview.1",
+  "version": "0.7.7-preview.1",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.tsx",
@@ -20,7 +20,7 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "@assetlib/sdk-core": "0.7.6-preview.1"
+    "@assetlib/sdk-core": "0.7.7-preview.1"
   },
   "peerDependencies": {
     "expo": ">=54 <58",

package/src/index.tsx

@@ -44,12 +44,74 @@ function useEffectiveAppearance(appearance: 'light' | 'dark' | 'system') {
   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 };
+// The console's rendition tiers (long edge in pixels): artwork, then tintable icon masks.
+const ARTWORK_TIERS = [512, 1024, 2048];
+const ICON_TIERS = [24, 48, 72, 96, 192, 512];
+/** The largest tier measured per placement in this client's session; it seeds new mounts. */
+const sessionTiers = new WeakMap<AssetClient, Map<string, number>>();
+type MeasuredTier = { client: AssetClient; id: string; tier: number; measured: boolean };
+
+const tiersFor = (asset: AssetRef) => asset.rendering === 'template' ? ICON_TIERS : ARTWORK_TIERS;
+function tierFor(asset: AssetRef, longEdge: number): number {
+  const tiers = tiersFor(asset);
+  // Half a pixel absorbs float layout values, such as 341.333 points at 3x.
+  const index = tiers.findIndex(tier => tier + 0.5 >= longEdge);
+  return index < 0 ? tiers.length - 1 : index;
+}
+function displayScale(): number {
   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)) };
+  return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
+}
+
+/**
+ * 98% of the tier: core picks the tier's rendition when an integer aspect ratio leaves it a few
+ * pixels short, and the next larger one when an unusual ratio leaves it further short.
+ */
+function tierTarget(asset: AssetRef, tier: number): { pixelWidth: number; pixelHeight: number } {
+  const longEdge = Math.floor(tiersFor(asset)[tier] * 0.98);
+  const long = Math.max(asset.width, asset.height);
+  return { pixelWidth: Math.max(1, Math.ceil(longEdge * asset.width / long)), pixelHeight: Math.max(1, Math.ceil(longEdge * asset.height / long)) };
+}
+
+/** The tier a view needs: its layout × display scale, enough to cover the box (or fit it for contain). */
+function measuredTier(asset: AssetRef, layout: { width: number; height: number }, ratio: number, contentFit?: ImageProps['contentFit']): number | undefined {
+  if (!(layout.width > 0 && layout.height > 0 && Number.isFinite(layout.width) && Number.isFinite(layout.height))) return undefined;
+  const fit = contentFit === 'contain' || contentFit === 'scale-down' ? Math.min : Math.max;
+  return tierFor(asset, fit(layout.width / asset.width, layout.height / asset.height) * Math.max(asset.width, asset.height) * ratio);
+}
+
+/**
+ * Without an explicit target, request the measured view × PixelRatio snapped to a tier. A mount starts
+ * from the session's tier for this placement, else from the reference size × PixelRatio, which its first
+ * layout replaces. After that only this view's own layout changes its tier, and only upward.
+ */
+function usePixelTarget(client: AssetClient, asset: AssetRef, pixelWidth: number | undefined, pixelHeight: number | undefined, contentFit: ImageProps['contentFit'], onLayout: ImageProps['onLayout']) {
+  const explicit = pixelWidth !== undefined || pixelHeight !== undefined;
+  const id = `${asset.key}:${asset.width}x${asset.height}:${asset.rendering ?? 'original'}`;
+  const tiers = sessionTiers.get(client) ?? new Map<string, number>();
+  sessionTiers.set(client, tiers);
+  const seed = (): MeasuredTier => {
+    const known = tiers.get(id);
+    return { client, id, measured: known !== undefined, tier: known ?? tierFor(asset, Math.max(asset.width, asset.height) * displayScale()) };
+  };
+  const [stored, setStored] = useState(seed);
+  let current = stored;
+  if (stored.client !== client || stored.id !== id) setStored(current = seed());
+  return {
+    ...(explicit ? { pixelWidth, pixelHeight } : tierTarget(asset, current.tier)),
+    onLayout(event: Parameters<NonNullable<ImageProps['onLayout']>>[0]) {
+      const measured = explicit ? undefined : measuredTier(asset, event.nativeEvent.layout, displayScale(), contentFit);
+      if (measured !== undefined) {
+        tiers.set(id, Math.max(tiers.get(id) ?? measured, measured));
+        setStored(previous => {
+          const base = previous.client === client && previous.id === id ? previous : current;
+          const tier = base.measured ? Math.max(base.tier, measured) : measured;
+          return base.measured && tier === base.tier ? base : { client, id, measured: true, tier };
+        });
+      }
+      onLayout?.(event);
+    },
+  };
 }
 
 const tintWarnings = new Set<string>();
@@ -147,12 +209,12 @@ function useResolvedImage(client: AssetClient, asset: AssetRef | DynamicAssetRef
 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);
+  const { pixelWidth, pixelHeight, onLayout } = usePixelTarget(client, asset, requestedPixelWidth, requestedPixelHeight, props.contentFit, props.onLayout);
   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); }} />;
+  return <Image {...props} key={image.rendererKey} {...accessibilityProps(props, accessibilityMode, image.accessibility, accessibilityLocale)} cachePolicy="none" source={image.source} onLayout={onLayout} 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. */
@@ -168,7 +230,7 @@ export function AssetlibDynamicImage({ client, asset, fallback, fallbackDark, ap
 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);
+  const { pixelWidth, pixelHeight, onLayout } = usePixelTarget(client, asset, requestedPixelWidth, requestedPixelHeight, props.contentFit, props.onLayout);
   useTemplateTintWarning(asset, props.tintColor);
   const statesKey = JSON.stringify(asset.states);
   const requireDescription = accessibilityMode === 'description' && props.accessibilityLabel == null;
@@ -226,7 +288,7 @@ export function AssetlibStateImage<R extends StateSetRef>({ client, asset, arm,
   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 => {
+  return <Image {...props} key={rendererKey} {...accessibilityProps(props, accessibilityMode, metadata, accessibilityLocale)} cachePolicy="none" source={selected ? { uri: selected.uri } : fallback} onLayout={onLayout} onLoad={event => {
     if (isCurrent() && !displayed.current && resolved!.results[state].source !== 'bundle' && matchesLoadedSource(event, selected!.uri)) {
       displayed.current = true;
       client.reportDisplay(asset, resolved!.results[state]);

package/src/telemetry.ts

@@ -48,7 +48,7 @@ export function expoTelemetry(telemetry: ClientOptions['telemetry']): ClientOpti
   if (!telemetry?.enabled) return telemetry;
   return {
     ...telemetry,
-    sdk: telemetry.sdk ?? { name: 'sdk-expo', version: '0.7.6-preview.1' },
+    sdk: telemetry.sdk ?? { name: 'sdk-expo', version: '0.7.7-preview.1' },
     build: telemetry.build ?? runtimeBuild() ?? { platform: 'expo', appVersion: 'unknown', buildNumber: 'unknown' },
   };
 }