canopycms 0.1.0 → 0.2.0-int.121

package/dist/api/assets.js

@@ -42,12 +42,14 @@ const finalizeAssetBodySchema = z.object({
 const listAssetsParamsSchema = z.object({
     cursor: z.string().optional(),
     limit: z.coerce.number().int().positive().max(100).optional(),
+    /** Admin only: also list files removed from the library, each marked `hidden: true`. */
+    includeHidden: z.enum(['true', 'false']).optional(),
 });
 /** hash32 is a sha-256 truncated to 32 hex chars (keys.ts's `hashBytes`) - never any other shape. */
 const hash32Schema = z
     .string()
     .regex(/^[a-f0-9]{32}$/, 'key must be a 32-character lowercase hex string');
-const deleteAssetParamsSchema = z.object({ key: hash32Schema });
+const assetKeyBodySchema = z.object({ key: hash32Schema });
 /**
  * Presign a direct (or proxied) upload target. Any authenticated user - there
  * is no finer "editor" role, and upload needs to work for every non-admin
@@ -75,7 +77,8 @@ const presignAssetHandler = async (ctx, _req, body) => {
 /**
  * Finalize a staged upload: read the staged bytes, run the finalize pipeline
  * (sniff/hash/dims/sanitize), write originals + meta, and return the result.
- * Any authenticated user (same rationale as presign).
+ * Any authenticated user (same rationale as presign). Uploading a file that was
+ * removed from the library puts it back; `finalizeAsset` says why.
  */
 const finalizeAssetHandler = async (ctx, req, body) => {
     if (!ctx.assetStore)
@@ -168,49 +171,82 @@ const uploadProxiedHandler = async (ctx, req) => {
 /**
  * List assets - any authenticated user can list assets (key enumeration is
  * accepted: unlisted != private, see .claude/future-tasks/resolved/assets-media-system.md).
+ * Files removed from the library are left out; only an admin may ask for them too.
  */
-const listAssetsHandler = async (ctx, _req, params) => {
+const listAssetsHandler = async (ctx, req, params) => {
     if (!ctx.assetStore)
         return { ok: false, status: 501, error: 'Asset store not configured' };
+    const includeHidden = params.includeHidden === 'true';
+    if (includeHidden && !isAdmin(req.user.groups)) {
+        return { ok: false, status: 403, error: 'Only admins can list removed files' };
+    }
     const { items, nextCursor } = await ctx.assetStore.listMeta({
         cursor: params.cursor,
         limit: params.limit,
+        includeHidden,
     });
     return { ok: true, status: 200, data: { assets: items.map(toAssetRecord), nextCursor } };
 };
 /**
- * Delete asset - an Admin may delete any asset; anyone else may delete only an asset whose
- * recorded `uploadedBy` is them. `key` (hash32) is pre-validated by `deleteAssetParamsSchema`.
- * Deletes the meta sidecar only - blobs are immortal until a future GC worker task (see
- * .claude/future-tasks/resolved/assets-media-system.md).
+ * Who may remove a file from the library or restore it: an admin may act on any file; anyone else
+ * only on a file whose recorded `uploadedBy` is them. `null` when the caller may act.
  *
- * The ownership check lives here, not in a declarative guard, because it needs the asset's meta,
- * which guards can't read. Two fail-closed choices:
+ * The check lives here, not in a declarative guard, because it needs the asset's meta, which
+ * guards can't read. Two fail-closed choices:
  * - Meta with no `uploadedBy` (the field is optional) is admin-only — defaulting to "anyone may
- *   delete" would open every legacy asset to everyone.
+ *   act" would open every legacy asset to everyone.
  * - A missing asset returns the same 403 as an unowned one for non-admins, so the endpoint isn't
- *   an existence oracle over a content-addressed keyspace.
+ *   an existence oracle over a content-addressed keyspace. An admin, who can list every file,
+ *   gets a 404, so no marker is ever written for a file that does not exist.
  *
  * `uploadedBy` records the FIRST uploader only: finalizeAsset dedups on content hash, so a second
- * person uploading an identical file gains no delete rights over it — benign (a 403 where they
- * expected success, never the reverse; see
- * safeinsights/canopycms#572).
+ * person uploading an identical file gains no rights over it — benign (a 403 where they expected
+ * success, never the reverse; see safeinsights/canopycms#572).
  *
  * Coupled to the blob-GC follow-up in safeinsights/canopycms#575: this permission is safe because
- * delete is a de-list, not a destroy — nothing another branch references breaks. If GC ever makes
- * delete destroy the blob, this needs a reference check too.
+ * removal hides a file and destroys nothing, so nothing any branch or build references breaks. If
+ * GC ever deletes blobs, it needs a reference check of its own.
+ */
+async function visibilityRefusal(store, req, key, verb) {
+    const meta = await store.getMeta(key);
+    if (isAdmin(req.user.groups)) {
+        return meta ? null : { ok: false, status: 404, error: 'File not found' };
+    }
+    if (!meta?.uploadedBy || meta.uploadedBy !== req.user.userId) {
+        return { ok: false, status: 403, error: `You can only ${verb} files you uploaded` };
+    }
+    return null;
+}
+/**
+ * Remove a file from the library: write its hidden marker and leave its meta, originals and
+ * public objects alone, so every URL and every transform, stored or not yet computed, keeps
+ * working for content on any branch and in any build. `visibilityRefusal` says who may.
+ *
+ * The marker is create-only, so a second remove finds it and changes nothing. Remove, restore
+ * and a re-upload's un-hide touch only the marker, and nothing but the library listing reads it:
+ * the worst interleaving of two of them lists or omits one file until the next action.
  */
-const deleteAssetHandler = async (ctx, req, params) => {
+const hideAssetHandler = async (ctx, req, body) => {
     if (!ctx.assetStore)
         return { ok: false, status: 501, error: 'Asset store not configured' };
-    if (!isAdmin(req.user.groups)) {
-        const meta = await ctx.assetStore.getMeta(params.key);
-        if (!meta?.uploadedBy || meta.uploadedBy !== req.user.userId) {
-            return { ok: false, status: 403, error: 'You can only delete assets you uploaded' };
-        }
-    }
-    await ctx.assetStore.deleteMeta(params.key);
-    return { ok: true, status: 200, data: { deleted: true } };
+    const refusal = await visibilityRefusal(ctx.assetStore, req, body.key, 'remove');
+    if (refusal)
+        return refusal;
+    await ctx.assetStore.hideAsset(body.key, {
+        hiddenAt: new Date().toISOString(),
+        hiddenBy: req.user.userId,
+    });
+    return { ok: true, status: 200, data: { hidden: true } };
+};
+/** Put a removed file back in the library by deleting its hidden marker; see `hideAssetHandler`. */
+const restoreAssetHandler = async (ctx, req, body) => {
+    if (!ctx.assetStore)
+        return { ok: false, status: 501, error: 'Asset store not configured' };
+    const refusal = await visibilityRefusal(ctx.assetStore, req, body.key, 'restore');
+    if (refusal)
+        return refusal;
+    await ctx.assetStore.unhideAsset(body.key);
+    return { ok: true, status: 200, data: { hidden: false } };
 };
 /**
  * The largest body this route returns inline. The CMS Lambda's Function URL buffers its response
@@ -219,15 +255,19 @@ const deleteAssetHandler = async (ctx, req, params) => {
  */
 const INLINE_BODY_LIMIT_BYTES = 4 * 1024 * 1024;
 /**
- * A 302 to a presigned store URL. `no-store` because the URL expires: a cached redirect would
- * outlive it, and a browser revisiting the page would follow it to a 403.
+ * A 302 to a presigned store URL, cacheable by this browser alone for as long as the store says
+ * the URL stays reusable: the redirect then outlives a sign-out by at most that long, which is
+ * accepted because the target is a public-prefix object under an unguessable key.
  */
-function presignedRedirect(url) {
+function presignedRedirect({ url, maxAgeSeconds }) {
     return {
         kind: 'binary',
         status: 302,
         body: new Uint8Array(),
-        headers: { location: url, cacheControl: 'no-store' },
+        headers: {
+            location: url,
+            cacheControl: maxAgeSeconds > 0 ? `private, max-age=${maxAgeSeconds}` : 'no-store',
+        },
     };
 }
 /**
@@ -243,9 +283,9 @@ async function serveLazyTransform(assetStore, parsed, canonicalKey) {
         return { ok: false, status: transformed.status, error };
     }
     if (transformed.data.byteLength > INLINE_BODY_LIMIT_BYTES && assetStore.presignPublicObjectRead) {
-        const url = await assetStore.presignPublicObjectRead(canonicalKey);
-        if (url)
-            return presignedRedirect(url);
+        const presigned = await assetStore.presignPublicObjectRead(canonicalKey);
+        if (presigned)
+            return presignedRedirect(presigned);
     }
     return {
         kind: 'binary',
@@ -254,11 +294,17 @@ async function serveLazyTransform(assetStore, parsed, canonicalKey) {
         headers: { contentType: transformed.contentType, cacheControl: TRANSFORM_CACHE_CONTROL },
     };
 }
+/**
+ * For a streamed object stored without a Cache-Control of its own. Every key under the public
+ * prefix is content-addressed, so its bytes never change; `private` because this route is
+ * authenticated.
+ */
+const STREAMED_OBJECT_CACHE_CONTROL = 'private, max-age=31536000, immutable';
 /** A redirect to, or the bytes of, the public object stored at `key`; `null` when there is none. */
 async function serveStoredObject(assetStore, key) {
     if (assetStore.presignPublicObjectRead) {
-        const url = await assetStore.presignPublicObjectRead(key);
-        return url ? presignedRedirect(url) : null;
+        const presigned = await assetStore.presignPublicObjectRead(key);
+        return presigned ? presignedRedirect(presigned) : null;
     }
     const object = await assetStore.readPublicObject(key);
     if (!object)
@@ -270,7 +316,7 @@ async function serveStoredObject(assetStore, key) {
         headers: {
             contentType: object.contentType,
             contentDisposition: object.contentDisposition,
-            cacheControl: object.cacheControl,
+            cacheControl: object.cacheControl ?? STREAMED_OBJECT_CACHE_CONTROL,
         },
     };
 }
@@ -382,20 +428,43 @@ const listAssets = defineEndpoint({
     defaultMockData: { assets: [] },
     handler: listAssetsHandler,
 });
-/**
- * DELETE /assets?key={hash32}
- */
-const deleteAsset = defineEndpoint({
+const hideAsset = defineEndpoint({
     namespace: 'assets',
-    name: 'delete',
-    method: 'DELETE',
-    path: '/assets',
-    params: deleteAssetParamsSchema,
-    responseType: 'AssetDeleteResponse',
+    name: 'hide',
+    method: 'POST',
+    path: '/assets/hide',
+    body: assetKeyBodySchema,
+    bodyType: 'AssetKeyBody',
+    responseType: 'AssetVisibilityResponse',
     response: {},
-    defaultMockData: { deleted: true },
-    handler: deleteAssetHandler,
+    defaultMockData: { hidden: true },
+    handler: hideAssetHandler,
 });
+const restoreAsset = defineEndpoint({
+    namespace: 'assets',
+    name: 'restore',
+    method: 'POST',
+    path: '/assets/restore',
+    body: assetKeyBodySchema,
+    bodyType: 'AssetKeyBody',
+    responseType: 'AssetVisibilityResponse',
+    response: {},
+    defaultMockData: { hidden: false },
+    handler: restoreAssetHandler,
+});
+/**
+ * DELETE /assets answers 410 instead of falling through to `DELETE /:branch` as a branch named
+ * "assets". Hand-built like `assetRawRoute`, so the client generator emits no method for it.
+ */
+const deleteAssetGone = {
+    method: 'DELETE',
+    pattern: ['assets'],
+    handler: async () => ({
+        ok: false,
+        status: 410,
+        error: 'DELETE /assets is gone: remove a file from the library with POST /assets/hide',
+    }),
+};
 /**
  * Exported routes for router registration and client codegen.
  */
@@ -404,7 +473,9 @@ export const ASSET_ROUTES = {
     finalize: finalizeAsset,
     uploadProxied,
     list: listAssets,
-    delete: deleteAsset,
+    hide: hideAsset,
+    restore: restoreAsset,
+    deleteGone: deleteAssetGone,
 };
 /**
  * GET /assets/raw/{key...} - see `rawAssetHandler` above for why this is

package/dist/api/client.d.ts

@@ -15,7 +15,7 @@ import type { ContentReadResponse, ContentWriteResponse, ReferenceValidationResp
 import type { ReferenceOptionsResponse } from './reference-options.js';
 import type { ResolveReferencesBody, ResolveReferencesResponse } from './resolve-references.js';
 import type { DeleteEntryResponse, EntriesResponse } from './entries.js';
-import type { AssetDeleteResponse, AssetsListResponse, FinalizeAssetBody, FinalizeAssetResponse, PresignAssetBody, PresignAssetResponse } from './assets.js';
+import type { AssetKeyBody, AssetVisibilityResponse, AssetsListResponse, FinalizeAssetBody, FinalizeAssetResponse, PresignAssetBody, PresignAssetResponse } from './assets.js';
 import type { BatchGetUserMetadataBody, BatchGetUserMetadataResponse, GetUserMetadataResponse, ListGroupsResponse, PermissionsResponse, SearchUsersResponse, UpdatePermissionsBody } from './permissions.js';
 import type { ExternalGroupsResponse, InternalGroupsResponse, UpdateInternalGroupsBody, UpdateInternalGroupsResponse } from './groups.js';
 import type { UserInfoResponse } from './user.js';
@@ -131,8 +131,10 @@ export declare class CanopyApiClient {
         } & RequestOptions) => Promise<FinalizeAssetResponse>;
         /** GET /assets */
         list: (params: Record<string, string>, options?: RequestOptions) => Promise<AssetsListResponse>;
-        /** DELETE /assets */
-        delete: (params: Record<string, string>, options?: RequestOptions) => Promise<AssetDeleteResponse>;
+        /** POST /assets/hide */
+        hide: (body: AssetKeyBody, options?: RequestOptions) => Promise<AssetVisibilityResponse>;
+        /** POST /assets/restore */
+        restore: (body: AssetKeyBody, options?: RequestOptions) => Promise<AssetVisibilityResponse>;
     };
     readonly permissions: {
         /** GET /permissions */

package/dist/api/client.js

@@ -139,9 +139,13 @@ export class CanopyApiClient {
             list: (params, options) => {
                 return this.request('GET', this.buildPath('/assets', params), undefined, 'standard', options);
             },
-            /** DELETE /assets */
-            delete: (params, options) => {
-                return this.request('DELETE', this.buildPath('/assets', params), undefined, 'standard', options);
+            /** POST /assets/hide */
+            hide: (body, options) => {
+                return this.request('POST', '/assets/hide', body, 'standard', options);
+            },
+            /** POST /assets/restore */
+            restore: (body, options) => {
+                return this.request('POST', '/assets/restore', body, 'standard', options);
             },
         };
         this.permissions = {

package/dist/api/index.d.ts

@@ -5,7 +5,7 @@ export type { CommentsResponse, AddCommentResponse, ResolveCommentResponse } fro
 export type { EntriesResponse, ListEntriesResponse, CollectionItem, ListEntriesParams, DeleteEntryResponse, } from './entries.js';
 export type { PermissionsResponse, UpdatePermissionsBody, SearchUsersParams, GetUserMetadataResponse, GetUserMetadataParams, } from './permissions.js';
 export type { UserInfoResponse } from './user.js';
-export type { AssetRecord, AssetsListResponse, PresignAssetResponse, PresignAssetBody, FinalizeAssetResponse, FinalizeAssetBody, AssetDeleteResponse, } from './assets.js';
+export type { AssetRecord, AssetsListResponse, PresignAssetResponse, PresignAssetBody, FinalizeAssetResponse, FinalizeAssetBody, AssetKeyBody, AssetVisibilityResponse, } from './assets.js';
 export type { InternalGroupsResponse, ExternalGroupsResponse, UpdateInternalGroupsBody, SearchExternalGroupsParams, ExternalGroup, } from './groups.js';
 export type { ReferenceOptionsResponse } from './reference-options.js';
 export type { ResolveReferencesResponse } from './resolve-references.js';

package/dist/assets/asset-prefixes.d.ts

@@ -1,5 +1,5 @@
 /**
- * The five S3/local bucket-prefix strings (see keys.ts's module doc for the full layout).
+ * The six S3/local bucket-prefix strings (see keys.ts's module doc for the full layout).
  *
  * Split into its own dependency-free file so isomorphic modules (transform-directives.ts,
  * asset-url.ts) can import the prefixes without pulling keys.ts's `node:crypto` import into a
@@ -9,6 +9,8 @@ export declare const ASSET_PREFIXES: {
     readonly originals: "asset-originals";
     readonly staging: "asset-staging";
     readonly meta: "asset-meta";
+    /** One marker per file removed from the media library; its meta stays (see `hideAsset`). */
+    readonly hidden: "asset-hidden";
     readonly public: "assets";
     /** Transform-output prefix; directive-aware key building lives in transform-directives.ts. */
     readonly transform: "assets/t";
@@ -21,6 +23,7 @@ export interface AssetPrefixes {
     originals: string;
     staging: string;
     meta: string;
+    hidden: string;
     public: string;
     transform: string;
 }

package/dist/assets/asset-prefixes.js

@@ -1,5 +1,5 @@
 /**
- * The five S3/local bucket-prefix strings (see keys.ts's module doc for the full layout).
+ * The six S3/local bucket-prefix strings (see keys.ts's module doc for the full layout).
  *
  * Split into its own dependency-free file so isomorphic modules (transform-directives.ts,
  * asset-url.ts) can import the prefixes without pulling keys.ts's `node:crypto` import into a
@@ -9,6 +9,8 @@ export const ASSET_PREFIXES = {
     originals: 'asset-originals',
     staging: 'asset-staging',
     meta: 'asset-meta',
+    /** One marker per file removed from the media library; its meta stays (see `hideAsset`). */
+    hidden: 'asset-hidden',
     public: 'assets',
     /** Transform-output prefix; directive-aware key building lives in transform-directives.ts. */
     transform: 'assets/t',

package/dist/assets/editor-thumbnail-widths.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The widths the editor's media UI requests through the raw route: a library list row, a library
+ * card and an image field's preview. Finalize stores each for a still raster upload, new or
+ * re-uploaded (`storeEditorThumbnails`), so a first view reads a stored object instead of
+ * transforming in the request. Isomorphic: the editor components and finalize both import it.
+ */
+export declare const EDITOR_THUMBNAIL_WIDTHS: {
+    readonly listRow: 80;
+    readonly card: 160;
+    readonly imageField: 320;
+};

package/dist/assets/editor-thumbnail-widths.js

@@ -0,0 +1,7 @@
+/**
+ * The widths the editor's media UI requests through the raw route: a library list row, a library
+ * card and an image field's preview. Finalize stores each for a still raster upload, new or
+ * re-uploaded (`storeEditorThumbnails`), so a first view reads a stored object instead of
+ * transforming in the request. Isomorphic: the editor components and finalize both import it.
+ */
+export const EDITOR_THUMBNAIL_WIDTHS = { listRow: 80, card: 160, imageField: 320 };

package/dist/assets/finalize.d.ts

@@ -15,12 +15,13 @@ export type FinalizeAssetResult = {
  * Run the finalize pipeline over raw bytes and persist the result.
  *
  * Order matters here too: dedup FIRST (after hashing, inside the pipeline) -
- * if an identical blob already exists, return the existing meta and skip all
- * writes entirely (first-name-wins). Otherwise write the original, then the
- * optional public object, then `putMetaIfAbsent` LAST: meta is the commit
- * point for an asset's existence, so a crash between `putOriginal` and here
- * leaves only orphaned (harmless, content-addressed) blobs, never a meta
- * record pointing at a missing blob.
+ * if an identical blob already exists, return the existing meta, touching
+ * only its hidden marker and any editor thumbnails it lacks (first-name-wins).
+ * Otherwise write the original, then the optional public object, then
+ * `putMetaIfAbsent` LAST: meta is the commit point for an asset's existence,
+ * so a crash between `putOriginal` and here leaves only orphaned (harmless,
+ * content-addressed) blobs, never a meta record pointing at a missing blob.
+ * The editor thumbnails come after the commit.
  * @internal Exported for tests.
  */
 export declare function finalizeAsset(store: AssetStore, input: FinalizeInput): Promise<FinalizeAssetResult>;

package/dist/assets/finalize.js

@@ -5,6 +5,9 @@
  */
 import { runFinalizePipeline } from './pipeline.js';
 import { ASSET_PREFIXES } from './keys.js';
+import { storeEditorThumbnails } from './materialize.js';
+import { getErrorMessage } from '../utils/error.js';
+import { canopyLogWarn } from '../utils/logger.js';
 /**
  * A client-supplied staging key must be exactly `asset-staging/{uuid}` — the
  * shape beginUpload generates. Without this check, finalize's read + cleanup
@@ -23,12 +26,13 @@ export function isValidStagingKey(key) {
  * Run the finalize pipeline over raw bytes and persist the result.
  *
  * Order matters here too: dedup FIRST (after hashing, inside the pipeline) -
- * if an identical blob already exists, return the existing meta and skip all
- * writes entirely (first-name-wins). Otherwise write the original, then the
- * optional public object, then `putMetaIfAbsent` LAST: meta is the commit
- * point for an asset's existence, so a crash between `putOriginal` and here
- * leaves only orphaned (harmless, content-addressed) blobs, never a meta
- * record pointing at a missing blob.
+ * if an identical blob already exists, return the existing meta, touching
+ * only its hidden marker and any editor thumbnails it lacks (first-name-wins).
+ * Otherwise write the original, then the optional public object, then
+ * `putMetaIfAbsent` LAST: meta is the commit point for an asset's existence,
+ * so a crash between `putOriginal` and here leaves only orphaned (harmless,
+ * content-addressed) blobs, never a meta record pointing at a missing blob.
+ * The editor thumbnails come after the commit.
  * @internal Exported for tests.
  */
 export async function finalizeAsset(store, input) {
@@ -37,8 +41,21 @@ export async function finalizeAsset(store, input) {
         return result;
     const { meta, data, publicObject } = result;
     const existing = await store.getMeta(meta.hash32);
-    if (existing)
+    if (existing) {
+        // Uploading a file removed from the library puts it back. Hiding is a de-list, not access
+        // control: whoever uploads the bytes has the file, and a picker selecting an upload the
+        // library never shows would be a dead end. A failed un-hide only leaves the file out of the
+        // listing, so the upload still succeeds.
+        try {
+            await store.unhideAsset(meta.hash32);
+        }
+        catch (err) {
+            canopyLogWarn(`[canopycms] could not restore removed asset ${meta.hash32} to the library on re-upload: ${getErrorMessage(err)}`);
+        }
+        // Stores any thumbnail the existing asset lacks; this upload's bytes are its original's.
+        await storeEditorThumbnails(store, existing, data, { skipStored: true });
         return { ok: true, meta: existing };
+    }
     // Either put may find its key taken (`already-exists`): by an earlier attempt that stopped
     // before the meta commit, or by a concurrent identical upload. The object kept there is this
     // content's, so finalize goes on to commit the meta either way.
@@ -49,11 +66,13 @@ export async function finalizeAsset(store, input) {
     const putResult = await store.putMetaIfAbsent(meta.hash32, meta);
     if (putResult === 'already-exists') {
         // Lost a race against a concurrent identical upload - the winner's meta
-        // (already committed) is authoritative; return it rather than ours.
+        // (already committed) is authoritative; return it rather than ours. The
+        // winner's own finalize stores its thumbnails.
         const winner = await store.getMeta(meta.hash32);
-        if (winner)
-            return { ok: true, meta: winner };
+        return { ok: true, meta: winner ?? meta };
     }
+    // After the commit point: a thumbnail is keyed by the committed meta's slug.
+    await storeEditorThumbnails(store, meta, data);
     return { ok: true, meta };
 }
 /**

package/dist/assets/keys.d.ts

@@ -7,6 +7,7 @@
  *   asset-originals/{hash32}.{ext}          private; full-fidelity originals
  *   asset-staging/{uuid}                    presigned-POST target
  *   asset-meta/{hash32}.json                private; filename/uploader/dims/mime
+ *   asset-hidden/{hash32}.json              private; marks a file removed from the library
  *   assets/t/{directives}/{hash32}/{slug}   transform outputs (see transform-directives.ts)
  *   assets/{hash32}/{slug}.{ext}            public static: sanitized SVG + PDF only
  *
@@ -50,8 +51,10 @@ export declare function createKeyBuilders(prefixes?: AssetPrefixes): {
     stagingKey: (uuid: string) => string;
     metaKey: (hash32: string) => string;
     metaPrefix: () => string;
+    hiddenKey: (hash32: string) => string;
+    hiddenPrefix: () => string;
     publicKey: (hash32: string, slug: string, ext: string) => string;
 };
-export declare const originalKey: (hash32: string, ext: string) => string, stagingKey: (uuid: string) => string, metaKey: (hash32: string) => string, publicKey: (hash32: string, slug: string, ext: string) => string;
+export declare const originalKey: (hash32: string, ext: string) => string, stagingKey: (uuid: string) => string, metaKey: (hash32: string) => string, hiddenKey: (hash32: string) => string, publicKey: (hash32: string, slug: string, ext: string) => string;
 /** @internal Exported for tests. */
 export declare const originalPrefix: (hash32: string) => string, metaPrefix: () => string;

package/dist/assets/keys.js

@@ -7,6 +7,7 @@
  *   asset-originals/{hash32}.{ext}          private; full-fidelity originals
  *   asset-staging/{uuid}                    presigned-POST target
  *   asset-meta/{hash32}.json                private; filename/uploader/dims/mime
+ *   asset-hidden/{hash32}.json              private; marks a file removed from the library
  *   assets/t/{directives}/{hash32}/{slug}   transform outputs (see transform-directives.ts)
  *   assets/{hash32}/{slug}.{ext}            public static: sanitized SVG + PDF only
  *
@@ -81,10 +82,12 @@ export function createKeyBuilders(prefixes = ASSET_PREFIXES) {
         stagingKey: (uuid) => `${prefixes.staging}/${uuid}`,
         metaKey: (hash32) => `${prefixes.meta}/${hash32}.json`,
         metaPrefix: () => `${prefixes.meta}/`,
+        hiddenKey: (hash32) => `${prefixes.hidden}/${hash32}.json`,
+        hiddenPrefix: () => `${prefixes.hidden}/`,
         publicKey: (hash32, slug, ext) => `${prefixes.public}/${hash32}/${slug}.${ext}`,
     };
 }
 const keyBuilders = createKeyBuilders();
-export const { originalKey, stagingKey, metaKey, publicKey } = keyBuilders;
+export const { originalKey, stagingKey, metaKey, hiddenKey, publicKey } = keyBuilders;
 /** @internal Exported for tests. */
 export const { originalPrefix, metaPrefix } = keyBuilders;

package/dist/assets/materialize.d.ts

@@ -6,7 +6,7 @@
  * before that build is released) and canopycms-cdk's lazy transform Lambda.
  */
 import { type ParsedTransformPath } from './transform-directives.js';
-import type { AssetStore, CreateOnlyResult } from './types.js';
+import type { AssetMeta, AssetStore, CreateOnlyResult } from './types.js';
 /** Every transform output is stored under a content-addressed key, so it never changes. */
 export declare const TRANSFORM_CACHE_CONTROL = "public, max-age=31536000, immutable";
 /**
@@ -39,11 +39,26 @@ export type StoreTransformResult = {
  * `canonicalizeTransformPath`, so the stored pixels always match their key. A rejection is a fact
  * about the asset or the URL and is never worth retrying; a thrown error belongs to the store or
  * the environment. A 404's `error` names what was missing, so a caller answering a browser
- * replaces it.
+ * replaces it. A caller already holding the asset's committed meta and original bytes passes them
+ * as `source`, and the store is not read.
  */
 export declare function storeTransform(store: AssetStore, parsed: ParsedTransformPath, key: string, options?: {
     tags?: Readonly<Record<string, string>>;
+    source?: {
+        meta: AssetMeta;
+        data: Uint8Array;
+    };
 }): Promise<StoreTransformResult>;
+/**
+ * Store the editor thumbnails of a raster asset whose meta is committed, from `data`, its
+ * original's bytes. Best effort: the raw route computes a missing one on first view, so a failure
+ * is logged, never thrown, and the first one stops the rest, which would decode the same bytes in
+ * the same environment. One width at a time, so one decode is in memory. A multi-page (animated)
+ * source is skipped. `skipStored` HEADs each key first, for an asset that may already have them.
+ */
+export declare function storeEditorThumbnails(store: AssetStore, meta: AssetMeta, data: Uint8Array, options?: {
+    skipStored?: boolean;
+}): Promise<void>;
 /** One key a build references, and where it was referenced, for the failure report. */
 export interface MaterializeTarget {
     /** `assets/t/{directives}/{hash32}/{slug}.{ext}`. */

package/dist/assets/materialize.js

@@ -6,10 +6,12 @@
  * before that build is released) and canopycms-cdk's lazy transform Lambda.
  */
 import { getErrorMessage, isNodeError } from '../utils/error.js';
+import { canopyLogWarn } from '../utils/logger.js';
 import { ASSET_PREFIXES } from './asset-prefixes.js';
 import { loadSharp } from './sharp-loader.js';
 import { applyTransform } from './transform.js';
-import { canonicalizeTransformPath } from './transform-directives.js';
+import { EDITOR_THUMBNAIL_WIDTHS } from './editor-thumbnail-widths.js';
+import { canonicalizeTransformPath, formatDirectives, } from './transform-directives.js';
 /** Every transform output is stored under a content-addressed key, so it never changes. */
 export const TRANSFORM_CACHE_CONTROL = 'public, max-age=31536000, immutable';
 /**
@@ -25,10 +27,15 @@ export const LAZY_TRANSFORM_TAG = { key: 'canopy-transform', value: 'lazy' };
  * `canonicalizeTransformPath`, so the stored pixels always match their key. A rejection is a fact
  * about the asset or the URL and is never worth retrying; a thrown error belongs to the store or
  * the environment. A 404's `error` names what was missing, so a caller answering a browser
- * replaces it.
+ * replaces it. A caller already holding the asset's committed meta and original bytes passes them
+ * as `source`, and the store is not read.
  */
 export async function storeTransform(store, parsed, key, options = {}) {
-    const meta = await store.getMeta(parsed.hash32);
+    const { source } = options;
+    if (source && source.meta.hash32 !== parsed.hash32) {
+        throw new Error(`source is asset ${source.meta.hash32}, not ${parsed.hash32}`);
+    }
+    const meta = source?.meta ?? (await store.getMeta(parsed.hash32));
     if (!meta) {
         return { ok: false, status: 404, error: `Asset ${parsed.hash32} has no meta in the store` };
     }
@@ -51,7 +58,9 @@ export async function storeTransform(store, parsed, key, options = {}) {
     if (requestedFormat === undefined && parsed.ext !== meta.ext) {
         return { ok: false, status: 400, error: 'Extension does not match the source format' };
     }
-    const original = await store.readOriginal(parsed.hash32, meta.ext);
+    const original = source
+        ? { data: source.data, ext: meta.ext }
+        : await store.readOriginal(parsed.hash32, meta.ext);
     if (!original) {
         return { ok: false, status: 404, error: `Asset ${parsed.hash32} has no original in the store` };
     }
@@ -68,6 +77,50 @@ export async function storeTransform(store, parsed, key, options = {}) {
     });
     return { ok: true, data: transformed.data, contentType: transformed.contentType, stored };
 }
+/** The canonical keys of an asset's `EDITOR_THUMBNAIL_WIDTHS`, the keys the raw route reads them at. */
+function editorThumbnailTargets(meta) {
+    return Object.values(EDITOR_THUMBNAIL_WIDTHS).map((width) => {
+        const canonical = canonicalizeTransformPath([formatDirectives({ identity: false, width }), meta.hash32, `${meta.slug}.${meta.ext}`], 'any');
+        if (!canonical.ok)
+            throw new Error(canonical.error);
+        return { key: `${ASSET_PREFIXES.transform}/${canonical.canonicalPath}`, parsed: canonical };
+    });
+}
+/**
+ * Store the editor thumbnails of a raster asset whose meta is committed, from `data`, its
+ * original's bytes. Best effort: the raw route computes a missing one on first view, so a failure
+ * is logged, never thrown, and the first one stops the rest, which would decode the same bytes in
+ * the same environment. One width at a time, so one decode is in memory. A multi-page (animated)
+ * source is skipped. `skipStored` HEADs each key first, for an asset that may already have them.
+ */
+export async function storeEditorThumbnails(store, meta, data, options = {}) {
+    if (meta.kind !== 'raster')
+        return;
+    let failure;
+    try {
+        // An animated source re-encodes every frame at every width, over 15 s for a large GIF: too
+        // long to hold an upload for, so its first view transforms it instead. The probe decodes no
+        // pixels.
+        const sharp = await loadSharp();
+        if (((await sharp(data).metadata()).pages ?? 1) > 1)
+            return;
+        for (const { key, parsed } of editorThumbnailTargets(meta)) {
+            if (options.skipStored && (await store.hasPublicObject(key)))
+                continue;
+            const result = await storeTransform(store, parsed, key, { source: { meta, data } });
+            if (!result.ok) {
+                failure = `${key}: ${result.error}`;
+                break;
+            }
+        }
+    }
+    catch (err) {
+        failure = getErrorMessage(err);
+    }
+    if (failure !== undefined) {
+        canopyLogWarn(`[canopycms] could not store editor thumbnails of ${meta.hash32}: ${failure}`);
+    }
+}
 /** The `schemaVersion` of every `MaterializeReport`; a consumer gating on the JSON checks it. */
 export const MATERIALIZE_REPORT_SCHEMA_VERSION = 1;
 /** sharp cannot load in this process, so nothing missing can be produced here. */