@volter/editor-core 0.5.57

package/src/asset-workflow/folder-preview.ts

@@ -0,0 +1,345 @@
+/**
+ * Folder preview content discovery.
+ *
+ * Scans a project folder (breadth-first, via the storage-backend-agnostic
+ * `listAssets`) and picks up to four representative assets whose thumbnails a
+ * folder tile can composite. Selection ranks candidates in two tiers —
+ * tier 1 renders a real content thumbnail ('model', 'image' — including
+ * capability-kind 'source' files whose extension the model-thumbnail pipeline
+ * can render, see FOLDER_PREVIEW_MODEL_EXTENSIONS), tier 2 renders a
+ * synthetic glyph ('audio', 'prefab', 'json') — preferring
+ * tier 1, then shallower depth, then breadth-first directory listing order.
+ *
+ * Variety heuristic: within a tier, a first pass takes at most one candidate
+ * per top-level subtree (the candidate's first path segment below the scanned
+ * folder — a file directly inside the folder is its own subtree); remaining
+ * slots are then filled from that tier in rank order. Tier 1 is exhausted
+ * (both passes) before tier 2 is consulted, so tier preference dominates
+ * variety.
+ *
+ * Termination: the traversal itself never early-stops on item count — it
+ * walks everything the safety caps allow so `totalAssets` stays a useful
+ * count, and item selection runs over the collected candidates afterwards.
+ * `scannedAll` is false exactly when a cap (depth or listing budget) hid part
+ * of the tree, letting the UI render an "N+" style count.
+ */
+
+import { type AssetEntry, listAssets as defaultListAssets, type Listing } from '../editor-api';
+import { type AssetCapabilityKind, assetCapabilities } from './asset-capabilities';
+
+/** Maximum number of preview items a folder summary carries. */
+export const FOLDER_PREVIEW_MAX_ITEMS = 4;
+/** Maximum directory depth entered below the scanned folder (folder itself = 0). */
+export const FOLDER_PREVIEW_MAX_DEPTH = 4;
+/** Maximum number of directory listings a single scan may perform. */
+export const FOLDER_PREVIEW_MAX_LISTINGS = 24;
+/** Bound on concurrent `listAssets` calls within one scan. */
+export const FOLDER_PREVIEW_LIST_CONCURRENCY = 4;
+/** Bound on concurrent scans across all `getFolderPreview` callers. */
+export const FOLDER_PREVIEW_SCAN_CONCURRENCY = 3;
+
+/** Kinds that render a real content thumbnail. */
+export const FOLDER_PREVIEW_TIER1_KINDS: ReadonlySet<AssetCapabilityKind> = new Set([
+  'model',
+  'image',
+]);
+/**
+ * File extensions the model-thumbnail pipeline can render live. Some of these
+ * are kind 'source' in the capability registry (fbx/obj/dae/stl/ply/3ds/bvh),
+ * but they still produce a real content thumbnail, so folder scans promote
+ * them to tier-1 'model' candidates. Kept as a local list — importing
+ * `modelThumbnailFormat` would drag three.js into this data-only module — and
+ * pinned against `modelThumbnailFormat`'s supported set by a test.
+ */
+export const FOLDER_PREVIEW_MODEL_EXTENSIONS: ReadonlySet<string> = new Set([
+  'glb',
+  'gltf',
+  'fbx',
+  'obj',
+  'dae',
+  'stl',
+  'ply',
+  'spz',
+  'bvh',
+  '3ds',
+]);
+
+function hasPreviewableModelExtension(name: string): boolean {
+  const dot = name.lastIndexOf('.');
+  return dot > 0 && FOLDER_PREVIEW_MODEL_EXTENSIONS.has(name.slice(dot + 1).toLowerCase());
+}
+/** Kinds that render a synthetic glyph thumbnail. */
+export const FOLDER_PREVIEW_TIER2_KINDS: ReadonlySet<AssetCapabilityKind> = new Set([
+  'audio',
+  'video',
+  'prefab',
+  'json',
+]);
+
+export interface FolderPreviewItem {
+  /** Path relative to the asset root — usable directly to build the asset URL. */
+  path: string;
+  name: string;
+  kind: AssetCapabilityKind;
+}
+
+export interface FolderPreviewSummary {
+  items: FolderPreviewItem[];
+  /** Every non-hidden file seen by the (possibly capped) traversal. */
+  totalAssets: number;
+  /** False when a safety cap truncated the traversal (render counts as "N+"). */
+  scannedAll: boolean;
+  /** How many directory listings FAILED during the scan. Non-zero means this
+   *  summary under-reports for a reason that is not "the folder is empty" —
+   *  the counts below it are a floor, not a measurement. */
+  failedListings: number;
+}
+
+export interface FolderPreviewOptions {
+  /** Injectable listing function (tests); defaults to the editor API. */
+  listAssets?: (root: string, dir: string) => Promise<Listing<AssetEntry>>;
+  maxItems?: number;
+  maxDepth?: number;
+  maxListings?: number;
+  listConcurrency?: number;
+}
+
+/** Minimal FIFO limiter bounding how many tasks run concurrently. */
+function createLimiter(concurrency: number): <T>(task: () => Promise<T>) => Promise<T> {
+  let active = 0;
+  const waiting: Array<() => void> = [];
+  return async <T>(task: () => Promise<T>): Promise<T> => {
+    if (active >= concurrency) await new Promise<void>((release) => waiting.push(release));
+    active++;
+    try {
+      return await task();
+    } finally {
+      active--;
+      waiting.shift()?.();
+    }
+  };
+}
+
+function normalizeFolderPath(path: string): string {
+  // Strip only explicit `./` and `/` prefixes — a bare `[./]+` class would eat
+  // the leading dot of a real top-level dot-folder name (`.generated` →
+  // `generated`: wrong directory AND a cache-key collision with `generated`).
+  return path.replace(/^(?:\.\/|\/)+/, '').replace(/\/+$/, '');
+}
+
+/** First path segment below the scanned folder; a direct file is its own subtree. */
+function subtreeKey(base: string, path: string): string {
+  const relative = base ? path.slice(base.length + 1) : path;
+  return relative.split('/', 1)[0] ?? relative;
+}
+
+interface Candidate extends FolderPreviewItem {
+  tier: 1 | 2;
+  depth: number;
+  seq: number;
+  subtree: string;
+}
+
+function rank(a: Candidate, b: Candidate): number {
+  return a.tier - b.tier || a.depth - b.depth || a.seq - b.seq;
+}
+
+/** Variety pass (one candidate per subtree) then a fill pass, both in rank order. */
+function pickFromTier(
+  tierList: Candidate[],
+  picked: Candidate[],
+  usedSubtrees: Set<string>,
+  maxItems: number,
+): void {
+  for (const candidate of tierList) {
+    if (picked.length >= maxItems) break;
+    if (usedSubtrees.has(candidate.subtree)) continue;
+    usedSubtrees.add(candidate.subtree);
+    picked.push(candidate);
+  }
+  for (const candidate of tierList) {
+    if (picked.length >= maxItems) break;
+    if (!picked.includes(candidate)) picked.push(candidate);
+  }
+}
+
+function selectItems(candidates: Candidate[], maxItems: number): FolderPreviewItem[] {
+  const sorted = [...candidates].sort(rank);
+  const picked: Candidate[] = [];
+  const usedSubtrees = new Set<string>();
+  for (const tier of [1, 2] as const) {
+    const tierList = sorted.filter((candidate) => candidate.tier === tier);
+    pickFromTier(tierList, picked, usedSubtrees, maxItems);
+  }
+  picked.sort(rank);
+  return picked.map(({ path, name, kind }) => ({ path, name, kind }));
+}
+
+function previewTier(kind: AssetCapabilityKind): 0 | 1 | 2 {
+  if (FOLDER_PREVIEW_TIER1_KINDS.has(kind)) return 1;
+  return FOLDER_PREVIEW_TIER2_KINDS.has(kind) ? 2 : 0;
+}
+
+interface PendingDir {
+  dir: string;
+  depth: number;
+}
+
+interface ScanState {
+  base: string;
+  maxDepth: number;
+  candidates: Candidate[];
+  totalAssets: number;
+  truncated: boolean;
+  failedListings: number;
+  seq: number;
+}
+
+/** Fold one directory listing into the scan, queueing subdirectories on `next`. */
+function ingestListing(
+  state: ScanState,
+  entry: PendingDir,
+  assets: AssetEntry[],
+  next: PendingDir[],
+): void {
+  for (const asset of assets) {
+    if (asset.name.startsWith('.')) continue; // hidden, including .vgai
+    const path = entry.dir ? `${entry.dir}/${asset.name}` : asset.name;
+    if (asset.type === 'directory') {
+      if (entry.depth + 1 > state.maxDepth) state.truncated = true;
+      else next.push({ dir: path, depth: entry.depth + 1 });
+      continue;
+    }
+    state.totalAssets++;
+    const kind = hasPreviewableModelExtension(asset.name)
+      ? 'model'
+      : assetCapabilities(asset.name).kind;
+    const tier = previewTier(kind);
+    if (tier === 0) continue;
+    state.candidates.push({
+      path,
+      name: asset.name,
+      kind,
+      tier,
+      depth: entry.depth,
+      seq: state.seq++,
+      subtree: subtreeKey(state.base, path),
+    });
+  }
+}
+
+/**
+ * Breadth-first scan of `folderPath` (relative to `root`) producing a
+ * deterministic preview summary. Hidden entries (leading '.', including
+ * `.vgai`) are skipped entirely; safety caps bound depth and listing count.
+ */
+export async function collectFolderPreview(
+  root: string,
+  folderPath: string,
+  options: FolderPreviewOptions = {},
+): Promise<FolderPreviewSummary> {
+  const list = options.listAssets ?? defaultListAssets;
+  const maxItems = options.maxItems ?? FOLDER_PREVIEW_MAX_ITEMS;
+  const maxListings = options.maxListings ?? FOLDER_PREVIEW_MAX_LISTINGS;
+  const limit = createLimiter(options.listConcurrency ?? FOLDER_PREVIEW_LIST_CONCURRENCY);
+  const base = normalizeFolderPath(folderPath);
+  const state: ScanState = {
+    base,
+    maxDepth: options.maxDepth ?? FOLDER_PREVIEW_MAX_DEPTH,
+    candidates: [],
+    totalAssets: 0,
+    truncated: false,
+    failedListings: 0,
+    seq: 0,
+  };
+
+  let listings = 0;
+  let level: PendingDir[] = [{ dir: base, depth: 0 }];
+  while (level.length > 0) {
+    const budget = Math.max(0, maxListings - listings);
+    const toList = level.slice(0, budget);
+    if (toList.length < level.length) state.truncated = true;
+    listings += toList.length;
+    // Concurrency is bounded by `limit`; Promise.all preserves queue order, so
+    // results are processed deterministically regardless of resolution order.
+    const results = await Promise.all(toList.map((entry) => limit(() => list(root, entry.dir))));
+    const next: PendingDir[] = [];
+    for (const [index, entry] of toList.entries()) {
+      const listing = results[index];
+      // A listing that FAILED is counted, not folded in as an empty directory.
+      // Treating it as empty is how a backend hiccup rendered as "this folder
+      // has nothing in it" — with `scannedAll: true` beside it, claiming the
+      // traversal was complete.
+      if (!listing || !listing.ok) {
+        state.failedListings += 1;
+        continue;
+      }
+      ingestListing(state, entry, listing.entries, next);
+    }
+    level = next;
+  }
+
+  return {
+    items: selectItems(state.candidates, maxItems),
+    totalAssets: state.totalAssets,
+    scannedAll: !state.truncated && state.failedListings === 0,
+    failedListings: state.failedListings,
+  };
+}
+
+const CACHE_KEY_SEPARATOR = '\u0000';
+const previewCache = new Map<string, Promise<FolderPreviewSummary>>();
+const sharedScanLimiter = createLimiter(FOLDER_PREVIEW_SCAN_CONCURRENCY);
+
+/**
+ * Memoized `collectFolderPreview` per root+path. Concurrent calls for the same
+ * folder share one in-flight scan, and scans across different folders are
+ * bounded by a shared limiter so many visible tiles cannot stampede the
+ * storage backend. A failed scan is evicted so the next call retries.
+ */
+export function getFolderPreview(
+  root: string,
+  folderPath: string,
+  options?: FolderPreviewOptions,
+): Promise<FolderPreviewSummary> {
+  const key = `${root}${CACHE_KEY_SEPARATOR}${normalizeFolderPath(folderPath)}`;
+  const cached = previewCache.get(key);
+  if (cached) return cached;
+  const promise = sharedScanLimiter(() => collectFolderPreview(root, folderPath, options));
+  previewCache.set(key, promise);
+  const evict = () => {
+    if (previewCache.get(key) === promise) previewCache.delete(key);
+  };
+  promise.then((summary) => {
+    // A scan whose listings FAILED is not a folder that is empty; serve what we
+    // got, but never memoize it — the next call retries. (An empty summary is
+    // evicted too: re-checking a genuinely empty folder is one cheap listing,
+    // and it is cheaper than pinning a stale emptiness.)
+    if (summary.failedListings > 0) evict();
+    else if (summary.items.length === 0 && summary.totalAssets === 0) evict();
+  }, evict);
+  return promise;
+}
+
+/** True when one path is an ancestor of, equal to, or a descendant of the other. */
+function pathsRelated(a: string, b: string): boolean {
+  return a === b || a === '' || b === '' || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+
+/**
+ * Drop cached previews. With no argument, clears everything. Given a changed
+ * path, drops every cached entry that is an ancestor of, equal to, or a
+ * descendant of that path — ancestors' composites may include the changed
+ * subtree's contents, and descendants may themselves have changed.
+ */
+export function invalidateFolderPreviews(changedPath?: string): void {
+  if (changedPath === undefined) {
+    previewCache.clear();
+    return;
+  }
+  const changed = normalizeFolderPath(changedPath);
+  for (const key of [...previewCache.keys()]) {
+    const cachedPath = key.slice(key.indexOf(CACHE_KEY_SEPARATOR) + 1);
+    if (pathsRelated(cachedPath, changed)) previewCache.delete(key);
+  }
+}

package/src/asset-workflow/hosted-asset-materialization.ts

@@ -0,0 +1,236 @@
+/**
+ * Materialize a project's DECLARED asset packs (`asset-manifest.json`, D-AP1)
+ * from the `cloud-asset-library` Worker into a `StorageBackend`, recording
+ * the same provenance ledger (`.vgai/assets.json`, D-AP3) every other
+ * materialization site writes.
+ *
+ * This is the D-AP4 mechanism: a project's DECLARED packs are materialized
+ * from the `cloud-asset-library` worker (existing manifest + object routes),
+ * writing the same ledger.
+ *
+ * Exported for the open path to CALL rather than
+ * wired into `seedIfEmpty` here, so any declared pack (in the template or an
+ * example) reuses it without change. The template's `asset-manifest.json` is
+ * `{"packs": {}}` today, so calling this against the shipped template is a
+ * documented, harmless no-op: `declared` reports 0 and nothing is fetched.
+ *
+ * FAIL CLOSED AND LOUD, never fabricate (the anti-shim rule): a network
+ * failure, a 404, or a sha256 mismatch aborts THAT entry only — nothing is
+ * written for it — and is reported in the returned result; it never blocks
+ * the other declared entries and never substitutes placeholder bytes.
+ *
+ * ## The expected digest comes from the DECLARATION, never from the response
+ *
+ * Every entry pins `sha256` in `asset-manifest.json` (see
+ * `asset-pack-manifest.ts`), and that pin is the only authority here. Reading
+ * the expected digest out of the worker's own `/v1/assets/<id>` record instead
+ * would authenticate nothing on the FIRST fetch — a moved or tampered library
+ * answers self-consistently (its record and its bytes agree), the bytes get
+ * written, and its digest becomes the project's permanent `sourceHash` in the
+ * ledger. So: the record's digest must MATCH the pin (a disagreement is a
+ * refusal naming the asset), the fetched bytes are verified against the pin,
+ * and the pin is what the ledger records.
+ *
+ * ## "Already materialized" means the FILE is there, not just the record
+ *
+ * Idempotent and retry-safe: an entry is skipped only when the ledger has it
+ * AND its destination exists. Skipping on the ledger record alone made the
+ * broken case unrepairable — a project whose bytes were deleted, or whose
+ * ledger outlived a failed write, reported success forever, and the reopen
+ * retry (`project-manager.ts`) plus the Retry banner both skipped exactly the
+ * entry they existed to refetch.
+ */
+
+import { sha256Hex } from '../bytes-codec';
+import type { StorageBackend } from '../storage/types';
+import { normalizeLedgerPath } from './asset-ledger';
+import {
+  readAssetLedgerFromBackend,
+  recordAssetMaterializationInBackend,
+} from './asset-ledger-backend';
+/** Project-relative path of the pack declaration (D-AP1) — sibling of
+ *  `vgai.project.json` in the template/every example, and (per D-AP4) one of
+ *  the plain-text files the browser build's seed writes alongside the rest
+ *  of the template source. */
+import {
+  ASSET_MANIFEST_PATH,
+  type FlattenedPackEntry,
+  flattenAssetPacks,
+  parseAssetPackManifest,
+} from './asset-pack-manifest';
+import {
+  cloudAssetObjectUrl,
+  DEFAULT_CLOUD_ASSET_BASE_URL,
+  fetchCloudAssetRecord,
+} from './cloud-asset-client';
+
+export { ASSET_MANIFEST_PATH };
+
+export interface AssetPackMaterializationFailure {
+  readonly entry: FlattenedPackEntry;
+  readonly reason: string;
+}
+
+export interface AssetPackMaterializationResult {
+  /** Total entries declared across every pack. */
+  readonly declared: number;
+  readonly materialized: FlattenedPackEntry[];
+  /** Recorded in the ledger AND present on disk — nothing to do, not a failure. */
+  readonly alreadyPresent: FlattenedPackEntry[];
+  readonly failed: AssetPackMaterializationFailure[];
+}
+
+export interface MaterializeAssetPacksOptions {
+  /** Test-only override of the deployed worker's base URL. */
+  readonly baseUrl?: string;
+  readonly signal?: AbortSignal;
+  /** Called once per entry, after it is attempted. */
+  readonly onProgress?: (
+    entry: FlattenedPackEntry,
+    outcome: 'materialized' | 'already-present' | 'failed',
+  ) => void;
+}
+
+/**
+ * Materialize every pack entry `backend` declares in its own
+ * `asset-manifest.json` that is not already in the ledger.
+ *
+ * Reads the manifest from `backend` itself (not the repo), whichever backend
+ * the caller is already using.
+ */
+export async function materializeDeclaredAssetPacks(
+  backend: StorageBackend,
+  options: MaterializeAssetPacksOptions = {},
+): Promise<AssetPackMaterializationResult> {
+  const entries = await declaredPackEntries(backend);
+  const result: AssetPackMaterializationResult = {
+    declared: entries.length,
+    materialized: [],
+    alreadyPresent: [],
+    failed: [],
+  };
+  if (entries.length === 0) return result;
+
+  const ledger = await readAssetLedgerFromBackend(backend);
+  for (const entry of entries) {
+    if (options.signal?.aborted) break;
+    // A ledger record is a record, not the bytes — see the module header.
+    if (ledger[normalizeLedgerPath(entry.dest)] && (await backend.exists(entry.dest))) {
+      result.alreadyPresent.push(entry);
+      options.onProgress?.(entry, 'already-present');
+      continue;
+    }
+    try {
+      await materializeOne(backend, entry, options);
+      result.materialized.push(entry);
+      options.onProgress?.(entry, 'materialized');
+    } catch (error) {
+      result.failed.push({ entry, reason: error instanceof Error ? error.message : String(error) });
+      options.onProgress?.(entry, 'failed');
+    }
+  }
+  return result;
+}
+
+async function declaredPackEntries(backend: StorageBackend): Promise<FlattenedPackEntry[]> {
+  if (!(await backend.exists(ASSET_MANIFEST_PATH))) return [];
+  const raw = await backend.read(ASSET_MANIFEST_PATH);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `${ASSET_MANIFEST_PATH} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  return flattenAssetPacks(parseAssetPackManifest(parsed));
+}
+
+async function materializeOne(
+  backend: StorageBackend,
+  entry: FlattenedPackEntry,
+  options: MaterializeAssetPacksOptions,
+): Promise<void> {
+  const fetched = await fetchVerifiedPackEntry(entry, options);
+  await backend.write(entry.dest, fetched.bytes);
+  await recordAssetMaterializationInBackend(backend, {
+    destPath: entry.dest,
+    key: entry.key,
+    license: fetched.license,
+    // The PIN, not the library's reported digest — identical here by the
+    // check inside `fetchVerifiedPackEntry`, and the pin is the fact this
+    // project reviewed.
+    sourceSha256: entry.sha256,
+  });
+}
+
+/** The bytes of one declared pack entry, plus the library's license string. */
+export interface VerifiedPackEntryBytes {
+  readonly bytes: Uint8Array;
+  /** The library's own license string, for the ledger. */
+  readonly license: string;
+}
+
+/**
+ * Fetch and VERIFY one declared pack entry, writing nothing.
+ *
+ * This is the whole network + trust sequence — record lookup, pin/record
+ * cross-check, byte fetch, digest verification — with the destination IO left
+ * to the caller, because the two materialization sites differ only in where the
+ * bytes land: this module writes through a `StorageBackend` (browser/hosted),
+ * and `packages/vgai-cli/src/asset-packs.ts` writes to the filesystem for an
+ * on-disk project `vgai add` just declared a pack into. Extracted so neither
+ * site can drift from the other on the part that matters — a second copy of
+ * "fetch then trust" is exactly how trust-on-first-use gets reintroduced.
+ *
+ * Throws on every failure and never returns partial bytes.
+ */
+export async function fetchVerifiedPackEntry(
+  entry: FlattenedPackEntry,
+  options: MaterializeAssetPacksOptions = {},
+): Promise<VerifiedPackEntryBytes> {
+  const separator = entry.key.indexOf(':');
+  if (separator < 0) throw new Error(`Malformed asset key "${entry.key}" (expected "source:id").`);
+  const source = entry.key.slice(0, separator);
+  const assetId = entry.key.slice(separator + 1);
+  if (source !== 'local') {
+    throw new Error(
+      `Asset key "${entry.key}": only the "local" (cloud-hosted) source can be materialized ` +
+        'from the cloud worker.',
+    );
+  }
+  const baseUrl = options.baseUrl ?? DEFAULT_CLOUD_ASSET_BASE_URL;
+  const fetchOptions = options.signal ? { baseUrl, signal: options.signal } : { baseUrl };
+  const record = await fetchCloudAssetRecord(assetId, fetchOptions);
+  if (!record) throw new Error(`"${entry.key}" is not hosted by the cloud asset library.`);
+  const file = record.files[0];
+  if (!file) throw new Error(`"${entry.key}" has no files in the cloud library.`);
+  if (file.dependencies.length > 0) {
+    throw new Error(
+      `"${entry.key}" has ${file.dependencies.length} dependency file(s) — a pack entry names ` +
+        'exactly one destination file.',
+    );
+  }
+  // The cloud record must AGREE with the checked-in pin before a byte is
+  // fetched. A library that has moved on is a legitimate event; silently
+  // adopting its new bytes is not (see the module header).
+  if (file.main.sha256 !== entry.sha256) {
+    throw new Error(
+      `"${entry.key}" → ${entry.dest}: the cloud library reports sha256:${file.main.sha256} but ` +
+        `${ASSET_MANIFEST_PATH} pins sha256:${entry.sha256}. Nothing was fetched or written; ` +
+        'the pin is only re-cut by a reviewed change to the declaration.',
+    );
+  }
+  const url = cloudAssetObjectUrl(baseUrl, assetId, 0);
+  const response = await fetch(url, options.signal ? { signal: options.signal } : {});
+  if (!response.ok) throw new Error(`${url} returned ${response.status} ${response.statusText}.`);
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  const actual = await sha256Hex(bytes);
+  if (actual !== entry.sha256) {
+    throw new Error(
+      `"${entry.key}" → ${entry.dest}: ${url} delivered sha256:${actual} but the declaration ` +
+        `pins sha256:${entry.sha256}. Nothing was written.`,
+    );
+  }
+  return { bytes, license: record.license };
+}

package/src/asset-workflow/image-view-scale.ts

@@ -0,0 +1,32 @@
+/**
+ * Integer zoom for pixel art. Transcribed from the sprite-lab stage
+ * (`fitScale`): a fractional factor resamples the art, and a resampled
+ * sheet is a blur with the correct pixels still in the file.
+ */
+
+/** Largest scale that fits `src` inside `box` without resampling. */
+export function integerFitScale(
+  srcWidth: number,
+  srcHeight: number,
+  boxWidth: number,
+  boxHeight: number,
+): number {
+  if (srcWidth <= 0 || srcHeight <= 0 || boxWidth <= 0 || boxHeight <= 0) return 1;
+  const growX = srcWidth <= boxWidth ? Math.floor(boxWidth / srcWidth) : 0;
+  const growY = srcHeight <= boxHeight ? Math.floor(boxHeight / srcHeight) : 0;
+  const grow = Math.min(growX, growY);
+  if (grow >= 1) return grow;
+  return 1 / Math.max(Math.ceil(srcWidth / boxWidth), Math.ceil(srcHeight / boxHeight));
+}
+
+export type ImageScaleMode = 'fit' | 1 | 4 | 8;
+
+export function resolveImageScale(
+  mode: ImageScaleMode,
+  srcWidth: number,
+  srcHeight: number,
+  boxWidth: number,
+  boxHeight: number,
+): number {
+  return mode === 'fit' ? integerFitScale(srcWidth, srcHeight, boxWidth, boxHeight) : mode;
+}