@elytracms/studio 0.0.64 → 0.0.65

package/dist/lib/assets/backfill-thumbs.js

@@ -0,0 +1,120 @@
+import { generateVariants, planLqip, planThumb } from './thumbnail.js';
+/**
+ * The assets-rail "Generate previews" backfill (EC-400 AD-1 + EC-420 AD-4).
+ * Existing libraries predate the upload-time previews, so an explicit,
+ * deterministic maintenance action fetches each original ONCE, runs the SAME
+ * decode path as upload, and patches the record. It is idempotent PER VARIANT
+ * (EC-420 AD-4): an asset needing only the lqip gets one fetch of the original
+ * and fills just what's missing; an asset that already has both is skipped;
+ * non-images / SVGs / (for the thumb) already-small images never qualify. The run
+ * is sequential with visible progress and cancellable. Opportunistic per-open
+ * generation was REJECTED (it hides egress in random editor sessions and is
+ * untestable).
+ *
+ * The write goes through the injected {@link AssetRepository} — in the studio the
+ * EC-141 operations facade — so the patch flows through the one operations layer /
+ * TanStack Query cache (AD-5 / AD-17), never a direct backend client. The pure
+ * cores ({@link assetsNeedingVariants}, {@link assetVariantUpsertInput}) are
+ * node-tested; the byte fetch + canvas encode stay in the injectable shell.
+ */
+/** An image record still missing a thumb whose {@link planThumb} decision is `encode`. */
+function needsThumb(asset) {
+    return asset.thumb === undefined && planThumb(asset).kind === 'encode';
+}
+/** An image record still missing an lqip whose {@link planLqip} decision is `encode`. */
+function needsLqip(asset) {
+    return asset.lqip === undefined && planLqip(asset).kind === 'encode';
+}
+/**
+ * The assets that still need at least one variant (pure, node-tested idempotence
+ * core, EC-420 AD-4): an image record missing a needed thumb OR a needed lqip.
+ * Records already carrying both, non-images, SVGs, and (for the thumb) already-
+ * small images are silently excluded — re-running on a done library is a no-op.
+ */
+export function assetsNeedingVariants(assets) {
+    return assets.filter((asset) => needsThumb(asset) || needsLqip(asset));
+}
+/** The variants an asset is missing — what the per-variant backfill asks the encoder for. */
+export function variantWantFor(asset) {
+    return { thumb: needsThumb(asset), lqip: needsLqip(asset) };
+}
+/**
+ * The full upsert input that re-states an existing record with freshly generated
+ * variants attached — the targeted patch path for the backfill, within the
+ * existing repository/`assets.upsert` contract (EC-400 AD-4 / EC-420). Mirrors
+ * `assetMetadataUpsertInput`: every current column is restated so the full-replace
+ * upsert preserves it. A newly generated variant overlays; a variant the record
+ * ALREADY had (the other half of a per-variant fill) is preserved from `current`.
+ */
+export function assetVariantUpsertInput(current, variants) {
+    const thumb = variants.thumb ?? current.thumb;
+    const lqip = variants.lqip ?? current.lqip;
+    return {
+        id: current.id,
+        filename: current.filename,
+        contentType: current.contentType,
+        byteSize: current.byteSize,
+        storageKey: current.storageKey,
+        ...(current.width !== undefined ? { width: current.width } : {}),
+        ...(current.height !== undefined ? { height: current.height } : {}),
+        ...(current.url !== undefined ? { url: current.url } : {}),
+        ...(current.alt !== undefined ? { alt: current.alt } : {}),
+        ...(current.title !== undefined ? { title: current.title } : {}),
+        ...(current.focalPoint !== undefined ? { focalPoint: current.focalPoint } : {}),
+        ...(current.meta !== undefined ? { meta: current.meta } : {}),
+        ...(thumb !== undefined ? { thumb } : {}),
+        ...(lqip !== undefined ? { lqip } : {}),
+    };
+}
+/**
+ * Run the backfill sequentially over a project's images that still need a variant.
+ * Resolves with the final tally; never throws (per-asset failures are counted, not
+ * fatal). One fetch per candidate serves both variants; only the missing ones are
+ * (re)generated (EC-420 AD-4), so an asset with a thumb but no lqip is patched with
+ * just the lqip and its existing thumb blob is left untouched.
+ */
+export async function runVariantBackfill(deps, projectId) {
+    const all = await deps.assets.listAssets(projectId);
+    const candidates = assetsNeedingVariants(all);
+    const generate = deps.generate ??
+        ((source, meta, want) => generateVariants({ blobs: deps.blobs }, source, meta, want));
+    const progress = { total: candidates.length, done: 0, generated: 0, skipped: 0, failed: 0 };
+    deps.onProgress?.({ ...progress });
+    for (const asset of candidates) {
+        if (deps.signal?.cancelled) {
+            progress.cancelled = true;
+            break;
+        }
+        deps.onProgress?.({ ...progress, current: asset.filename });
+        try {
+            const bytes = await deps.blobs.get(asset.storageKey);
+            if (!bytes) {
+                progress.failed += 1;
+            }
+            else {
+                const source = new Blob([bytes], { type: asset.contentType });
+                const variants = await generate(source, {
+                    contentType: asset.contentType,
+                    ...(asset.width !== undefined ? { width: asset.width } : {}),
+                    ...(asset.height !== undefined ? { height: asset.height } : {}),
+                }, variantWantFor(asset));
+                if (variants.thumb === undefined && variants.lqip === undefined) {
+                    progress.skipped += 1;
+                }
+                else {
+                    const patched = await deps.assets.upsertAsset(projectId, assetVariantUpsertInput(asset, variants));
+                    deps.onGenerated?.(patched);
+                    progress.generated += 1;
+                }
+            }
+        }
+        catch {
+            progress.failed += 1;
+        }
+        progress.done += 1;
+        deps.onProgress?.({ ...progress });
+    }
+    deps.onProgress?.({ ...progress });
+    return progress;
+}
+//# sourceMappingURL=backfill-thumbs.js.map

package/dist/lib/assets/backfill-thumbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill-thumbs.js","sourceRoot":"","sources":["../../../src/lib/assets/backfill-thumbs.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  AssetRecord,\n  AssetRepository,\n  BlobStorageAdapter,\n  NewAssetInput,\n} from '@elytracms/core/persistence'\nimport { generateVariants, planLqip, planThumb } from './thumbnail'\nimport type { GeneratedVariants, ThumbSource, VariantWant } from './thumbnail'\n\n/**\n * The assets-rail \"Generate previews\" backfill (EC-400 AD-1 + EC-420 AD-4).\n * Existing libraries predate the upload-time previews, so an explicit,\n * deterministic maintenance action fetches each original ONCE, runs the SAME\n * decode path as upload, and patches the record. It is idempotent PER VARIANT\n * (EC-420 AD-4): an asset needing only the lqip gets one fetch of the original\n * and fills just what's missing; an asset that already has both is skipped;\n * non-images / SVGs / (for the thumb) already-small images never qualify. The run\n * is sequential with visible progress and cancellable. Opportunistic per-open\n * generation was REJECTED (it hides egress in random editor sessions and is\n * untestable).\n *\n * The write goes through the injected {@link AssetRepository} — in the studio the\n * EC-141 operations facade — so the patch flows through the one operations layer /\n * TanStack Query cache (AD-5 / AD-17), never a direct backend client. The pure\n * cores ({@link assetsNeedingVariants}, {@link assetVariantUpsertInput}) are\n * node-tested; the byte fetch + canvas encode stay in the injectable shell.\n */\n\n/** An image record still missing a thumb whose {@link planThumb} decision is `encode`. */\nfunction needsThumb(asset: AssetRecord): boolean {\n  return asset.thumb === undefined && planThumb(asset).kind === 'encode'\n}\n\n/** An image record still missing an lqip whose {@link planLqip} decision is `encode`. */\nfunction needsLqip(asset: AssetRecord): boolean {\n  return asset.lqip === undefined && planLqip(asset).kind === 'encode'\n}\n\n/**\n * The assets that still need at least one variant (pure, node-tested idempotence\n * core, EC-420 AD-4): an image record missing a needed thumb OR a needed lqip.\n * Records already carrying both, non-images, SVGs, and (for the thumb) already-\n * small images are silently excluded — re-running on a done library is a no-op.\n */\nexport function assetsNeedingVariants(assets: readonly AssetRecord[]): AssetRecord[] {\n  return assets.filter((asset) => needsThumb(asset) || needsLqip(asset))\n}\n\n/** The variants an asset is missing — what the per-variant backfill asks the encoder for. */\nexport function variantWantFor(asset: AssetRecord): VariantWant {\n  return { thumb: needsThumb(asset), lqip: needsLqip(asset) }\n}\n\n/**\n * The full upsert input that re-states an existing record with freshly generated\n * variants attached — the targeted patch path for the backfill, within the\n * existing repository/`assets.upsert` contract (EC-400 AD-4 / EC-420). Mirrors\n * `assetMetadataUpsertInput`: every current column is restated so the full-replace\n * upsert preserves it. A newly generated variant overlays; a variant the record\n * ALREADY had (the other half of a per-variant fill) is preserved from `current`.\n */\nexport function assetVariantUpsertInput(\n  current: AssetRecord,\n  variants: GeneratedVariants,\n): NewAssetInput {\n  const thumb = variants.thumb ?? current.thumb\n  const lqip = variants.lqip ?? current.lqip\n  return {\n    id: current.id,\n    filename: current.filename,\n    contentType: current.contentType,\n    byteSize: current.byteSize,\n    storageKey: current.storageKey,\n    ...(current.width !== undefined ? { width: current.width } : {}),\n    ...(current.height !== undefined ? { height: current.height } : {}),\n    ...(current.url !== undefined ? { url: current.url } : {}),\n    ...(current.alt !== undefined ? { alt: current.alt } : {}),\n    ...(current.title !== undefined ? { title: current.title } : {}),\n    ...(current.focalPoint !== undefined ? { focalPoint: current.focalPoint } : {}),\n    ...(current.meta !== undefined ? { meta: current.meta } : {}),\n    ...(thumb !== undefined ? { thumb } : {}),\n    ...(lqip !== undefined ? { lqip } : {}),\n  }\n}\n\n/** Live tally the \"Generate previews\" UI renders (EC-400 AD-1). */\nexport interface BackfillProgress {\n  /** How many assets need at least one variant (the candidate set size). */\n  total: number\n  /** How many candidates have been processed (generated + skipped + failed). */\n  done: number\n  /** How many candidates had at least one variant generated and patched in. */\n  generated: number\n  /** Candidates the re-plan/encode declined (e.g. undecodable) — silent, valid. */\n  skipped: number\n  /** Candidates whose fetch/encode/patch errored — surfaced, not fatal. */\n  failed: number\n  /** Filename of the asset currently in flight (for the progress label). */\n  current?: string\n  /** Set once the run stops early because the caller cancelled. */\n  cancelled?: boolean\n}\n\n/** A mutable cancellation flag the UI flips to stop the sequential run (AD-1). */\nexport interface BackfillSignal {\n  cancelled: boolean\n}\n\nexport interface BackfillDeps {\n  /** Metadata reads + the variant patch write (the operations facade in the studio). */\n  assets: AssetRepository\n  /** Blob boundary: fetch each original's bytes, store the thumb variant. */\n  blobs: BlobStorageAdapter\n  /**\n   * Injectable variant producer; defaults to {@link generateVariants} over `blobs`.\n   * Receives the per-asset `want` so it produces ONLY the missing variants. Tests\n   * pass a deterministic fake so the iterator runs in node.\n   */\n  generate?: (source: Blob, meta: ThumbSource, want: VariantWant) => Promise<GeneratedVariants>\n  /** Fired with each patched record so the caller can update its cache in place. */\n  onGenerated?: (asset: AssetRecord) => void\n  /** Fired after each candidate (and once at the end) to drive the progress UI. */\n  onProgress?: (progress: BackfillProgress) => void\n  /** Cooperative cancellation — checked before each candidate (AD-1). */\n  signal?: BackfillSignal\n}\n\n/**\n * Run the backfill sequentially over a project's images that still need a variant.\n * Resolves with the final tally; never throws (per-asset failures are counted, not\n * fatal). One fetch per candidate serves both variants; only the missing ones are\n * (re)generated (EC-420 AD-4), so an asset with a thumb but no lqip is patched with\n * just the lqip and its existing thumb blob is left untouched.\n */\nexport async function runVariantBackfill(\n  deps: BackfillDeps,\n  projectId: string,\n): Promise<BackfillProgress> {\n  const all = await deps.assets.listAssets(projectId)\n  const candidates = assetsNeedingVariants(all)\n  const generate =\n    deps.generate ??\n    ((source: Blob, meta: ThumbSource, want: VariantWant) =>\n      generateVariants({ blobs: deps.blobs }, source, meta, want))\n\n  const progress: BackfillProgress = { total: candidates.length, done: 0, generated: 0, skipped: 0, failed: 0 }\n  deps.onProgress?.({ ...progress })\n\n  for (const asset of candidates) {\n    if (deps.signal?.cancelled) {\n      progress.cancelled = true\n      break\n    }\n    deps.onProgress?.({ ...progress, current: asset.filename })\n    try {\n      const bytes = await deps.blobs.get(asset.storageKey)\n      if (!bytes) {\n        progress.failed += 1\n      } else {\n        const source = new Blob([bytes as BlobPart], { type: asset.contentType })\n        const variants = await generate(\n          source,\n          {\n            contentType: asset.contentType,\n            ...(asset.width !== undefined ? { width: asset.width } : {}),\n            ...(asset.height !== undefined ? { height: asset.height } : {}),\n          },\n          variantWantFor(asset),\n        )\n        if (variants.thumb === undefined && variants.lqip === undefined) {\n          progress.skipped += 1\n        } else {\n          const patched = await deps.assets.upsertAsset(projectId, assetVariantUpsertInput(asset, variants))\n          deps.onGenerated?.(patched)\n          progress.generated += 1\n        }\n      }\n    } catch {\n      progress.failed += 1\n    }\n    progress.done += 1\n    deps.onProgress?.({ ...progress })\n  }\n\n  deps.onProgress?.({ ...progress })\n  return progress\n}\n"]}

package/dist/lib/assets/delete-asset.d.ts

@@ -6,7 +6,8 @@ import type { AssetRepository, BlobStorageAdapter, ReferenceIndexRepository } fr
  * `{ type: 'asset' }` target) — index-accurate, replacing the interim string
  * scan (`find-asset-usages`), which could miss rich-text asset hrefs and
  * false-positive on unrelated strings. Deleting an unused asset removes bytes
- * (blob) AND the metadata record. Results are structured data — never throws.
+ * (blob) — original AND the EC-400 thumb variant blob — plus the metadata
+ * record. Results are structured data — never throws.
  */
 export interface DeleteAssetDeps {
     assets: AssetRepository;

package/dist/lib/assets/delete-asset.js

@@ -15,6 +15,18 @@ export async function deleteAsset(deps, projectId, assetId, options = {}) {
         // Bytes first, metadata last: a failure midway leaves a visible metadata
         // record (re-deletable) rather than invisible orphaned bytes.
         await deps.blobs.delete(asset.storageKey);
+        // EC-400 (AD-4): the downscaled preview is a SECOND stored blob — delete it
+        // too. Best-effort: a leftover thumb blob is harmless wasted storage (its
+        // metadata is going), so a thumb-delete failure must not block removing the
+        // asset the way an orphaned original would.
+        if (asset.thumb) {
+            try {
+                await deps.blobs.delete(asset.thumb.storageKey);
+            }
+            catch {
+                // Swallow — the asset delete proceeds; the orphaned thumb blob is inert.
+            }
+        }
         await deps.assets.removeAsset(projectId, assetId);
         return { outcome: 'deleted' };
     }

package/dist/lib/assets/delete-asset.js.map

@@ -1 +1 @@
-{"version":3,"file":"delete-asset.js","sourceRoot":"","sources":["../../../src/lib/assets/delete-asset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAoCjE,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAqB,EACrB,SAAiB,EACjB,OAAe,EACf,UAA8B,EAAE;IAEhC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QAC7D,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAA;QAE3C,8EAA8E;QAC9E,iFAAiF;QACjF,mFAAmF;QACnF,IAAI,OAAO,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;YAClE,IAAI,UAAU,GAAG,CAAC;gBAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,CAAA;QAC/D,CAAC;QAED,yEAAyE;QACzE,8DAA8D;QAC9D,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;QACzC,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QACjD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAA;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,mBAAmB;YAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAA;QACzE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;IAC9F,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,eAAe,CAC5B,IAAqB,EACrB,SAAiB,EACjB,OAAe;IAEf,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;IACxF,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAChF,CAAA;IACD,OAAO,QAAQ,CAAC,IAAI,CAAA;AACtB,CAAC","sourcesContent":["import { RecordNotFoundError } from '@elytracms/core/persistence'\nimport type {\n  AssetRepository,\n  BlobStorageAdapter,\n  ReferenceIndexRepository,\n} from '@elytracms/core/persistence'\n\n/**\n * Reference-respecting asset deletion (EC-151, reworked EC-202). Deleting an\n * asset that is referenced is blocked until explicitly confirmed; the usage\n * count comes from the **EC-155 reference index** (`references.inbound` for the\n * `{ type: 'asset' }` target) — index-accurate, replacing the interim string\n * scan (`find-asset-usages`), which could miss rich-text asset hrefs and\n * false-positive on unrelated strings. Deleting an unused asset removes bytes\n * (blob) AND the metadata record. Results are structured data — never throws.\n */\n\nexport interface DeleteAssetDeps {\n  assets: AssetRepository\n  blobs: BlobStorageAdapter\n  /** The EC-155 reference index — the accurate inbound-usage source (EC-202). */\n  references: Pick<ReferenceIndexRepository, 'inbound'>\n}\n\nexport type DeleteAssetResult =\n  | { outcome: 'deleted' }\n  /** The asset is referenced and `confirmInUse` was not set: nothing was removed. */\n  | { outcome: 'blocked'; usageCount: number }\n  | { outcome: 'not-found' }\n  | { outcome: 'error'; message: string }\n\nexport interface DeleteAssetOptions {\n  /** Caller has seen the usage count and explicitly confirmed deletion. */\n  confirmInUse?: boolean\n}\n\nexport async function deleteAsset(\n  deps: DeleteAssetDeps,\n  projectId: string,\n  assetId: string,\n  options: DeleteAssetOptions = {},\n): Promise<DeleteAssetResult> {\n  try {\n    const asset = await deps.assets.findAsset(projectId, assetId)\n    if (!asset) return { outcome: 'not-found' }\n\n    // Only consult the reference index when the caller has NOT already confirmed.\n    // The delete dialog enumerates usages up-front and confirms with `confirmInUse`,\n    // so a confirmed delete skips this redundant inbound query entirely (EC-301 perf).\n    if (options.confirmInUse !== true) {\n      const usageCount = await assetUsageCount(deps, projectId, assetId)\n      if (usageCount > 0) return { outcome: 'blocked', usageCount }\n    }\n\n    // Bytes first, metadata last: a failure midway leaves a visible metadata\n    // record (re-deletable) rather than invisible orphaned bytes.\n    await deps.blobs.delete(asset.storageKey)\n    await deps.assets.removeAsset(projectId, assetId)\n    return { outcome: 'deleted' }\n  } catch (error) {\n    if (error instanceof RecordNotFoundError) return { outcome: 'not-found' }\n    return { outcome: 'error', message: error instanceof Error ? error.message : String(error) }\n  }\n}\n\n/**\n * Distinct inbound usages of an asset from the reference index (EC-202). One\n * `source + path` (e.g. `post:hello · values/cover`) can carry both a draft and\n * a published index entry — that is a single usage, so variants collapse before\n * counting (the gate is \"is this referenced\", not \"how many index rows\").\n */\nasync function assetUsageCount(\n  deps: DeleteAssetDeps,\n  projectId: string,\n  assetId: string,\n): Promise<number> {\n  const inbound = await deps.references.inbound(projectId, { type: 'asset', id: assetId })\n  const distinct = new Set(\n    inbound.map((entry) => `${entry.source.type}:${entry.source.id}:${entry.path}`),\n  )\n  return distinct.size\n}\n"]}
+{"version":3,"file":"delete-asset.js","sourceRoot":"","sources":["../../../src/lib/assets/delete-asset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAqCjE,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAqB,EACrB,SAAiB,EACjB,OAAe,EACf,UAA8B,EAAE;IAEhC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QAC7D,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAA;QAE3C,8EAA8E;QAC9E,iFAAiF;QACjF,mFAAmF;QACnF,IAAI,OAAO,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;YAClE,IAAI,UAAU,GAAG,CAAC;gBAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,CAAA;QAC/D,CAAC;QAED,yEAAyE;QACzE,8DAA8D;QAC9D,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;QACzC,4EAA4E;QAC5E,0EAA0E;QAC1E,4EAA4E;QAC5E,4CAA4C;QAC5C,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;YACjD,CAAC;YAAC,MAAM,CAAC;gBACP,yEAAyE;YAC3E,CAAC;QACH,CAAC;QACD,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QACjD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAA;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,mBAAmB;YAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAA;QACzE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;IAC9F,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,eAAe,CAC5B,IAAqB,EACrB,SAAiB,EACjB,OAAe;IAEf,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;IACxF,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAChF,CAAA;IACD,OAAO,QAAQ,CAAC,IAAI,CAAA;AACtB,CAAC","sourcesContent":["import { RecordNotFoundError } from '@elytracms/core/persistence'\nimport type {\n  AssetRepository,\n  BlobStorageAdapter,\n  ReferenceIndexRepository,\n} from '@elytracms/core/persistence'\n\n/**\n * Reference-respecting asset deletion (EC-151, reworked EC-202). Deleting an\n * asset that is referenced is blocked until explicitly confirmed; the usage\n * count comes from the **EC-155 reference index** (`references.inbound` for the\n * `{ type: 'asset' }` target) — index-accurate, replacing the interim string\n * scan (`find-asset-usages`), which could miss rich-text asset hrefs and\n * false-positive on unrelated strings. Deleting an unused asset removes bytes\n * (blob) — original AND the EC-400 thumb variant blob — plus the metadata\n * record. Results are structured data — never throws.\n */\n\nexport interface DeleteAssetDeps {\n  assets: AssetRepository\n  blobs: BlobStorageAdapter\n  /** The EC-155 reference index — the accurate inbound-usage source (EC-202). */\n  references: Pick<ReferenceIndexRepository, 'inbound'>\n}\n\nexport type DeleteAssetResult =\n  | { outcome: 'deleted' }\n  /** The asset is referenced and `confirmInUse` was not set: nothing was removed. */\n  | { outcome: 'blocked'; usageCount: number }\n  | { outcome: 'not-found' }\n  | { outcome: 'error'; message: string }\n\nexport interface DeleteAssetOptions {\n  /** Caller has seen the usage count and explicitly confirmed deletion. */\n  confirmInUse?: boolean\n}\n\nexport async function deleteAsset(\n  deps: DeleteAssetDeps,\n  projectId: string,\n  assetId: string,\n  options: DeleteAssetOptions = {},\n): Promise<DeleteAssetResult> {\n  try {\n    const asset = await deps.assets.findAsset(projectId, assetId)\n    if (!asset) return { outcome: 'not-found' }\n\n    // Only consult the reference index when the caller has NOT already confirmed.\n    // The delete dialog enumerates usages up-front and confirms with `confirmInUse`,\n    // so a confirmed delete skips this redundant inbound query entirely (EC-301 perf).\n    if (options.confirmInUse !== true) {\n      const usageCount = await assetUsageCount(deps, projectId, assetId)\n      if (usageCount > 0) return { outcome: 'blocked', usageCount }\n    }\n\n    // Bytes first, metadata last: a failure midway leaves a visible metadata\n    // record (re-deletable) rather than invisible orphaned bytes.\n    await deps.blobs.delete(asset.storageKey)\n    // EC-400 (AD-4): the downscaled preview is a SECOND stored blob — delete it\n    // too. Best-effort: a leftover thumb blob is harmless wasted storage (its\n    // metadata is going), so a thumb-delete failure must not block removing the\n    // asset the way an orphaned original would.\n    if (asset.thumb) {\n      try {\n        await deps.blobs.delete(asset.thumb.storageKey)\n      } catch {\n        // Swallow — the asset delete proceeds; the orphaned thumb blob is inert.\n      }\n    }\n    await deps.assets.removeAsset(projectId, assetId)\n    return { outcome: 'deleted' }\n  } catch (error) {\n    if (error instanceof RecordNotFoundError) return { outcome: 'not-found' }\n    return { outcome: 'error', message: error instanceof Error ? error.message : String(error) }\n  }\n}\n\n/**\n * Distinct inbound usages of an asset from the reference index (EC-202). One\n * `source + path` (e.g. `post:hello · values/cover`) can carry both a draft and\n * a published index entry — that is a single usage, so variants collapse before\n * counting (the gate is \"is this referenced\", not \"how many index rows\").\n */\nasync function assetUsageCount(\n  deps: DeleteAssetDeps,\n  projectId: string,\n  assetId: string,\n): Promise<number> {\n  const inbound = await deps.references.inbound(projectId, { type: 'asset', id: assetId })\n  const distinct = new Set(\n    inbound.map((entry) => `${entry.source.type}:${entry.source.id}:${entry.path}`),\n  )\n  return distinct.size\n}\n"]}

package/dist/lib/assets/index.d.ts

@@ -5,5 +5,7 @@
  */
 export * from './upload-state.js';
 export * from './image-dimensions.js';
+export * from './thumbnail.js';
+export * from './backfill-thumbs.js';
 export * from './upload.js';
 export * from './delete-asset.js';

package/dist/lib/assets/index.js

@@ -5,6 +5,8 @@
  */
 export * from './upload-state.js';
 export * from './image-dimensions.js';
+export * from './thumbnail.js';
+export * from './backfill-thumbs.js';
 export * from './upload.js';
 export * from './delete-asset.js';
 //# sourceMappingURL=index.js.map

package/dist/lib/assets/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/assets/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA","sourcesContent":["/**\n * Asset upload, deletion, and usage logic (EC-151). Pure/injectable modules:\n * the studio UI consumes these; storage is reached only through the\n * `BlobStorageAdapter` boundary.\n */\nexport * from './upload-state'\nexport * from './image-dimensions'\nexport * from './upload'\nexport * from './delete-asset'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/assets/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA","sourcesContent":["/**\n * Asset upload, deletion, and usage logic (EC-151). Pure/injectable modules:\n * the studio UI consumes these; storage is reached only through the\n * `BlobStorageAdapter` boundary.\n */\nexport * from './upload-state'\nexport * from './image-dimensions'\nexport * from './thumbnail'\nexport * from './backfill-thumbs'\nexport * from './upload'\nexport * from './delete-asset'\n"]}

package/dist/lib/assets/thumbnail.d.ts

@@ -0,0 +1,145 @@
+import type { AssetThumbVariant, BlobStorageAdapter } from '@elytracms/core/persistence';
+/**
+ * Client-side preview generation (EC-400 thumb + EC-420 LQIP). Every studio image
+ * surface used to stream the full-size Convex serve URL in a plain `<img>`, so a
+ * page of big originals cost heavy egress. At the moment an upload already has the
+ * bytes in hand — and again from the assets rail's "Generate previews" backfill —
+ * ONE `createImageBitmap` decode yields BOTH variants:
+ *
+ * - **thumb** (EC-400): a ≤480px-long-edge re-encode stored as a SECOND blob;
+ *   editorial-only (studio grids/pickers/table cells render it instead of the
+ *   original). NEVER leaves the studio.
+ * - **lqip** (EC-420): a ≤24px, low-quality re-encode base64'd into a tiny `data:`
+ *   URI (hard-capped at {@link ASSET_LQIP_MAX_LENGTH} chars) and stored INLINE on
+ *   the record. Unlike the thumb it rides the delivery wire (AD-2): the
+ *   `@elytracms/next` image seam feeds it to `next/image` as `placeholder="blur"`.
+ *
+ * The decisions (`planThumb` / `planLqip`) are pure, node-testable cores; the
+ * canvas re-encode (`canvasVariantEncoder`) is a thin, injectable DOM shell that
+ * decodes once and draws each requested target; the orchestrator
+ * (`generateVariants`) plans → encodes (one decode) → stores the thumb blob +
+ * builds the lqip data URI, and is testable in node with a fake encoder over an
+ * in-memory blob store.
+ *
+ * Ratified spec: thumb ≤480px, quality ~0.8 (EC-400 AD-2). lqip ≤24px, quality
+ * ~0.45 (EC-420 AD-1); UNLIKE the thumb it is generated even for images already
+ * ≤480px (any raster benefits from blur-up). Both prefer `image/webp` with an
+ * `image/jpeg` fallback (the ACTUAL returned blob type is recorded — Safari has
+ * historically ignored the requested type). Skips are silent and valid — not
+ * validation issues; a generation failure never fails the upload.
+ */
+/** The ratified maximum thumbnail long-edge, in pixels (EC-400 AD-2). */
+export declare const THUMB_MAX_EDGE = 480;
+/** The ratified re-encode quality for the lossy thumbnail codecs (EC-400 AD-2). */
+export declare const THUMB_QUALITY = 0.8;
+/** The ratified maximum LQIP long-edge, in pixels (EC-420 AD-1). */
+export declare const LQIP_MAX_EDGE = 24;
+/** The ratified re-encode quality for the LQIP placeholder (EC-420 AD-1). */
+export declare const LQIP_QUALITY = 0.45;
+/** The re-encode target size a variant needs, or the reason it is skipped. */
+export type ThumbPlan = {
+    kind: 'skip';
+    reason: 'non-image' | 'vector' | 'no-dimensions' | 'already-small';
+} | {
+    kind: 'encode';
+    width: number;
+    height: number;
+};
+/** The LQIP plan — like {@link ThumbPlan} but WITHOUT the `already-small` skip (AD-3). */
+export type LqipPlan = {
+    kind: 'skip';
+    reason: 'non-image' | 'vector' | 'no-dimensions';
+} | {
+    kind: 'encode';
+    width: number;
+    height: number;
+};
+/** The metadata `planThumb` / `planLqip` and the encoders reason over. */
+export interface ThumbSource {
+    contentType: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * Decide whether an asset needs a downscaled thumb, and to what size (EC-400
+ * AD-2/AD-3). Pure and deterministic — the node-tested core of the skip rules.
+ * A returned `encode` plan preserves aspect ratio, fitting the long edge to
+ * {@link THUMB_MAX_EDGE}; the short edge rounds to at least one pixel.
+ */
+export declare function planThumb(source: ThumbSource): ThumbPlan;
+/**
+ * Decide whether an asset needs an LQIP blur placeholder, and to what size (EC-420
+ * AD-1/AD-3). Pure and deterministic. Mirrors {@link planThumb}'s skips (non-image,
+ * SVG, no dimensions) but — UNLIKE the thumb — has NO `already-small` skip: any
+ * raster benefits from delivery blur-up, so even a ≤480px image gets one (fit to
+ * {@link LQIP_MAX_EDGE}, never upscaled).
+ */
+export declare function planLqip(source: ThumbSource): LqipPlan;
+/** The bytes + ACTUAL mime type + dimensions an encoder produced for one variant. */
+export interface EncodedVariant {
+    bytes: Uint8Array;
+    /** The blob's real type — NOT necessarily the requested one (AD-2 Safari note). */
+    contentType: string;
+    width: number;
+    height: number;
+}
+/** A re-encode target the encoder draws into (per-variant quality). */
+export interface EncodeTarget {
+    width: number;
+    height: number;
+    quality: number;
+}
+/** Which variants to draw+encode from the single decode, at their target sizes. */
+export interface VariantTargets {
+    thumb?: EncodeTarget;
+    lqip?: EncodeTarget;
+}
+/** The encoded output of one decode: whichever requested variants encoded. */
+export interface EncodedVariants {
+    thumb?: EncodedVariant;
+    lqip?: EncodedVariant;
+}
+/**
+ * Turn source image bytes into downscaled preview bytes for BOTH variants from a
+ * single decode. Returns whichever variants encoded (an empty object when the
+ * source cannot be decoded/encoded) — never throws; the caller treats a missing
+ * variant as "no preview", never a failure. Injectable so the orchestrator + the
+ * upload/backfill flows unit-test in node without a browser.
+ */
+export type VariantEncoder = (source: Blob, targets: VariantTargets) => Promise<EncodedVariants>;
+/**
+ * The default browser encoder: ONE `createImageBitmap` decode → per-variant 2D
+ * canvas → `toBlob` (EC-420: the same decode yields thumb AND lqip). A thin DOM
+ * shell, deliberately untested in node (the orchestrator is tested with a fake
+ * encoder). Any failure resolves an empty object, so a preview never breaks an
+ * upload.
+ */
+export declare const canvasVariantEncoder: VariantEncoder;
+/** Blob storage + the (optionally injected) encoder the orchestrator needs. */
+export interface VariantGenerationDeps {
+    blobs: BlobStorageAdapter;
+    /** Defaults to {@link canvasVariantEncoder}; tests inject a deterministic fake. */
+    encode?: VariantEncoder;
+}
+/** Which variants the orchestrator should PRODUCE (backfill fills only the missing ones). */
+export interface VariantWant {
+    thumb?: boolean;
+    lqip?: boolean;
+}
+/** The stored/inlined variants a generation run produced (either may be absent). */
+export interface GeneratedVariants {
+    /** The stored downscaled thumb (a second blob's key/url + dims), or absent. */
+    thumb?: AssetThumbVariant;
+    /** The LQIP blur-placeholder `data:` URI (≤ cap), or absent. */
+    lqip?: string;
+}
+/**
+ * Plan → encode (ONE decode) → store/inline BOTH variants (EC-400 + EC-420). The
+ * thumb rides a SECOND `store()` call (the same blob boundary the upload uses); the
+ * lqip is inlined as a capped base64 `data:` URI needing no blob store at all.
+ * `want` narrows which variants to produce — the per-variant backfill (AD-4) asks
+ * for only the missing one so an existing thumb/lqip is never regenerated. Returns
+ * whichever variants succeeded; any skip/failure simply omits that variant (never
+ * throws — a preview must never fail an upload).
+ */
+export declare function generateVariants(deps: VariantGenerationDeps, source: Blob, meta: ThumbSource, want?: VariantWant): Promise<GeneratedVariants>;

package/dist/lib/assets/thumbnail.js

@@ -0,0 +1,220 @@
+import { ASSET_LQIP_MAX_LENGTH } from '@elytracms/core/persistence';
+/**
+ * Client-side preview generation (EC-400 thumb + EC-420 LQIP). Every studio image
+ * surface used to stream the full-size Convex serve URL in a plain `<img>`, so a
+ * page of big originals cost heavy egress. At the moment an upload already has the
+ * bytes in hand — and again from the assets rail's "Generate previews" backfill —
+ * ONE `createImageBitmap` decode yields BOTH variants:
+ *
+ * - **thumb** (EC-400): a ≤480px-long-edge re-encode stored as a SECOND blob;
+ *   editorial-only (studio grids/pickers/table cells render it instead of the
+ *   original). NEVER leaves the studio.
+ * - **lqip** (EC-420): a ≤24px, low-quality re-encode base64'd into a tiny `data:`
+ *   URI (hard-capped at {@link ASSET_LQIP_MAX_LENGTH} chars) and stored INLINE on
+ *   the record. Unlike the thumb it rides the delivery wire (AD-2): the
+ *   `@elytracms/next` image seam feeds it to `next/image` as `placeholder="blur"`.
+ *
+ * The decisions (`planThumb` / `planLqip`) are pure, node-testable cores; the
+ * canvas re-encode (`canvasVariantEncoder`) is a thin, injectable DOM shell that
+ * decodes once and draws each requested target; the orchestrator
+ * (`generateVariants`) plans → encodes (one decode) → stores the thumb blob +
+ * builds the lqip data URI, and is testable in node with a fake encoder over an
+ * in-memory blob store.
+ *
+ * Ratified spec: thumb ≤480px, quality ~0.8 (EC-400 AD-2). lqip ≤24px, quality
+ * ~0.45 (EC-420 AD-1); UNLIKE the thumb it is generated even for images already
+ * ≤480px (any raster benefits from blur-up). Both prefer `image/webp` with an
+ * `image/jpeg` fallback (the ACTUAL returned blob type is recorded — Safari has
+ * historically ignored the requested type). Skips are silent and valid — not
+ * validation issues; a generation failure never fails the upload.
+ */
+/** The ratified maximum thumbnail long-edge, in pixels (EC-400 AD-2). */
+export const THUMB_MAX_EDGE = 480;
+/** The ratified re-encode quality for the lossy thumbnail codecs (EC-400 AD-2). */
+export const THUMB_QUALITY = 0.8;
+/** The ratified maximum LQIP long-edge, in pixels (EC-420 AD-1). */
+export const LQIP_MAX_EDGE = 24;
+/** The ratified re-encode quality for the LQIP placeholder (EC-420 AD-1). */
+export const LQIP_QUALITY = 0.45;
+/** Fit `width`×`height` so its long edge is ≤ `maxEdge` (never upscaling); short edge ≥ 1px. */
+function fitLongEdge(width, height, maxEdge) {
+    const scale = Math.min(1, maxEdge / Math.max(width, height));
+    return { width: Math.max(1, Math.round(width * scale)), height: Math.max(1, Math.round(height * scale)) };
+}
+/**
+ * Decide whether an asset needs a downscaled thumb, and to what size (EC-400
+ * AD-2/AD-3). Pure and deterministic — the node-tested core of the skip rules.
+ * A returned `encode` plan preserves aspect ratio, fitting the long edge to
+ * {@link THUMB_MAX_EDGE}; the short edge rounds to at least one pixel.
+ */
+export function planThumb(source) {
+    if (!source.contentType.startsWith('image/'))
+        return { kind: 'skip', reason: 'non-image' };
+    // SVG is vector — rasterizing loses fidelity and saves nothing (AD-3).
+    if (source.contentType === 'image/svg+xml')
+        return { kind: 'skip', reason: 'vector' };
+    const { width, height } = source;
+    if (!width || !height || width <= 0 || height <= 0)
+        return { kind: 'skip', reason: 'no-dimensions' };
+    // Already small enough — a variant would be a no-op; consumers just use `url`.
+    if (Math.max(width, height) <= THUMB_MAX_EDGE)
+        return { kind: 'skip', reason: 'already-small' };
+    return { kind: 'encode', ...fitLongEdge(width, height, THUMB_MAX_EDGE) };
+}
+/**
+ * Decide whether an asset needs an LQIP blur placeholder, and to what size (EC-420
+ * AD-1/AD-3). Pure and deterministic. Mirrors {@link planThumb}'s skips (non-image,
+ * SVG, no dimensions) but — UNLIKE the thumb — has NO `already-small` skip: any
+ * raster benefits from delivery blur-up, so even a ≤480px image gets one (fit to
+ * {@link LQIP_MAX_EDGE}, never upscaled).
+ */
+export function planLqip(source) {
+    if (!source.contentType.startsWith('image/'))
+        return { kind: 'skip', reason: 'non-image' };
+    if (source.contentType === 'image/svg+xml')
+        return { kind: 'skip', reason: 'vector' };
+    const { width, height } = source;
+    if (!width || !height || width <= 0 || height <= 0)
+        return { kind: 'skip', reason: 'no-dimensions' };
+    return { kind: 'encode', ...fitLongEdge(width, height, LQIP_MAX_EDGE) };
+}
+/** Promisify the callback-style `HTMLCanvasElement.toBlob`. */
+function canvasToBlob(canvas, type, quality) {
+    return new Promise((resolve) => canvas.toBlob((blob) => resolve(blob), type, quality));
+}
+/**
+ * Draw an already-decoded bitmap into a target-sized 2D canvas and encode it.
+ * Prefers `image/webp`; when the browser silently substitutes another type
+ * (Safari), retries `image/jpeg` and records whatever type actually came back.
+ * Resolves `undefined` on any failure (a valid skip, never a throw).
+ */
+async function encodeFromBitmap(bitmap, target) {
+    const canvas = document.createElement('canvas');
+    canvas.width = target.width;
+    canvas.height = target.height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        return undefined;
+    ctx.drawImage(bitmap, 0, 0, target.width, target.height);
+    let blob = await canvasToBlob(canvas, 'image/webp', target.quality);
+    if (!blob || blob.type !== 'image/webp') {
+        blob = await canvasToBlob(canvas, 'image/jpeg', target.quality);
+    }
+    if (!blob)
+        return undefined;
+    const bytes = new Uint8Array(await blob.arrayBuffer());
+    // Zero-length re-encodes are worthless; discard them.
+    if (bytes.byteLength === 0)
+        return undefined;
+    return {
+        bytes,
+        // Record the ACTUAL type — never assume the requested one landed (AD-2).
+        contentType: blob.type || 'image/jpeg',
+        width: target.width,
+        height: target.height,
+    };
+}
+/**
+ * The default browser encoder: ONE `createImageBitmap` decode → per-variant 2D
+ * canvas → `toBlob` (EC-420: the same decode yields thumb AND lqip). A thin DOM
+ * shell, deliberately untested in node (the orchestrator is tested with a fake
+ * encoder). Any failure resolves an empty object, so a preview never breaks an
+ * upload.
+ */
+export const canvasVariantEncoder = async (source, targets) => {
+    const out = {};
+    try {
+        if (typeof createImageBitmap !== 'function' || typeof document === 'undefined')
+            return out;
+        const bitmap = await createImageBitmap(source);
+        try {
+            if (targets.thumb) {
+                const encoded = await encodeFromBitmap(bitmap, targets.thumb);
+                if (encoded)
+                    out.thumb = encoded;
+            }
+            if (targets.lqip) {
+                const encoded = await encodeFromBitmap(bitmap, targets.lqip);
+                if (encoded)
+                    out.lqip = encoded;
+            }
+        }
+        finally {
+            bitmap.close?.();
+        }
+    }
+    catch {
+        // Undecodable — a silent, valid skip, never a thrown failure.
+        return out;
+    }
+    return out;
+};
+/** Base64-encode bytes for a `data:` URI. `undefined` when no encoder is available. */
+function bytesToBase64(bytes) {
+    // `btoa` exists in browsers and Node ≥16; absence (exotic runtime) → no lqip.
+    if (typeof btoa !== 'function')
+        return undefined;
+    let binary = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+/** Build a `data:<type>;base64,<payload>` URI from encoded bytes; `undefined` on failure. */
+function toDataUri(encoded) {
+    const b64 = bytesToBase64(encoded.bytes);
+    return b64 ? `data:${encoded.contentType};base64,${b64}` : undefined;
+}
+/**
+ * Plan → encode (ONE decode) → store/inline BOTH variants (EC-400 + EC-420). The
+ * thumb rides a SECOND `store()` call (the same blob boundary the upload uses); the
+ * lqip is inlined as a capped base64 `data:` URI needing no blob store at all.
+ * `want` narrows which variants to produce — the per-variant backfill (AD-4) asks
+ * for only the missing one so an existing thumb/lqip is never regenerated. Returns
+ * whichever variants succeeded; any skip/failure simply omits that variant (never
+ * throws — a preview must never fail an upload).
+ */
+export async function generateVariants(deps, source, meta, want = { thumb: true, lqip: true }) {
+    const thumbPlan = want.thumb === false ? { kind: 'skip', reason: 'already-small' } : planThumb(meta);
+    const lqipPlan = want.lqip === false ? { kind: 'skip', reason: 'no-dimensions' } : planLqip(meta);
+    const targets = {};
+    if (thumbPlan.kind === 'encode') {
+        targets.thumb = { width: thumbPlan.width, height: thumbPlan.height, quality: THUMB_QUALITY };
+    }
+    if (lqipPlan.kind === 'encode') {
+        targets.lqip = { width: lqipPlan.width, height: lqipPlan.height, quality: LQIP_QUALITY };
+    }
+    if (!targets.thumb && !targets.lqip)
+        return {};
+    const encode = deps.encode ?? canvasVariantEncoder;
+    let encoded;
+    try {
+        encoded = await encode(source, targets);
+    }
+    catch {
+        return {};
+    }
+    const result = {};
+    // Thumb: a SECOND stored blob (needs a key-minting backend; a put-only backend
+    // simply gets no thumb — the lqip still ships).
+    if (encoded.thumb && deps.blobs.store) {
+        try {
+            const storageKey = await deps.blobs.store(encoded.thumb.bytes, encoded.thumb.contentType);
+            const url = (await deps.blobs.resolveUrl?.(storageKey)) ?? deps.blobs.url(storageKey);
+            result.thumb = { storageKey, url, width: encoded.thumb.width, height: encoded.thumb.height };
+        }
+        catch {
+            // No thumb — never fail the run.
+        }
+    }
+    // Lqip: inline data URI, no blob. Enforce the hard cap; over-cap → skip (AD-1)
+    // rather than silently persist an oversized value the schema would reject anyway.
+    if (encoded.lqip) {
+        const dataUri = toDataUri(encoded.lqip);
+        if (dataUri && dataUri.length <= ASSET_LQIP_MAX_LENGTH)
+            result.lqip = dataUri;
+    }
+    return result;
+}
+//# sourceMappingURL=thumbnail.js.map