canopycms 0.1.0-int.115 → 0.2.0-int.119

package/README.md

@@ -87,7 +87,6 @@ export default defineCanopyConfig({
   gitBotAuthorEmail: 'canopy@example.com',
   editor: {
     title: 'CanopyCMS Editor', // optional UI defaults
-    subtitle: 'Edit content',
     theme: {
       colors: { brand: '#4f46e5' },
     },

package/dist/ai/references.js

@@ -10,6 +10,7 @@ import { getDefaultEntryType } from '../content-store.js';
 import { extractEntryTypeFromFilename } from '../content-id-index.js';
 import { RESTRICTED_REFERENCE_MARKER } from '../entry-schema.js';
 import { extractEntryLinkIds } from '../entry-link-resolver.js';
+import { trimSlashes } from '../paths/normalize.js';
 import { getErrorMessage } from '../utils/error.js';
 import { flattenGroupFields } from '../utils/flatten-group-fields.js';
 import { resolveEntryTitle } from '../utils/title-field.js';
@@ -183,7 +184,8 @@ export async function decideReferenceLinks(referenceLink, entries, subjectOf, en
  * this export wrote for the target (`files`: content id to output path), under `mountPath`.
  */
 export function createReferenceRendering(idIndex, flatSchema, entryLinkUrl, markdownCopies, linkFor) {
-    const mount = `/${markdownCopies.mountPath.replace(/^\/+|\/+$/g, '')}`.replace(/^\/$/, '');
+    const mountSegment = trimSlashes(markdownCopies.mountPath);
+    const mount = mountSegment === '' ? '' : `/${mountSegment}`;
     const entryTypeOf = (id) => {
         const location = typeof id === 'string' ? idIndex.findById(id) : null;
         if (!location?.collection)

package/dist/api/assets.d.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
 import type { RouteDefinition } from '../http/router.js';
-import type { AssetMeta, StagedUploadTarget } from '../assets/types.js';
+import type { ListedAssetMeta, StagedUploadTarget } from '../assets/types.js';
 /** An asset's persisted meta plus its computed, root-relative public URL. */
-export type AssetRecord = AssetMeta & {
+export type AssetRecord = ListedAssetMeta & {
     src: string;
 };
 /** Response type for listing assets */
@@ -19,9 +19,9 @@ export type PresignAssetResponse = ApiResponse<{
 export type FinalizeAssetResponse = ApiResponse<{
     asset: AssetRecord;
 }>;
-/** Response type for deleting an asset */
-export type AssetDeleteResponse = ApiResponse<{
-    deleted: boolean;
+/** Response type for removing a file from the library or restoring it: whether it is now hidden */
+export type AssetVisibilityResponse = ApiResponse<{
+    hidden: boolean;
 }>;
 declare const presignAssetBodySchema: z.ZodObject<{
     filename: z.ZodString;
@@ -48,6 +48,14 @@ declare const finalizeAssetBodySchema: z.ZodObject<{
     stagingKey: string;
 }>;
 export type FinalizeAssetBody = z.infer<typeof finalizeAssetBodySchema>;
+declare const assetKeyBodySchema: z.ZodObject<{
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+}, {
+    key: string;
+}>;
+export type AssetKeyBody = z.infer<typeof assetKeyBodySchema>;
 /**
  * Exported routes for router registration and client codegen.
  */
@@ -79,20 +87,32 @@ export declare const ASSET_ROUTES: {
     readonly list: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         cursor: z.ZodOptional<z.ZodString>;
         limit: z.ZodOptional<z.ZodNumber>;
+        /** Admin only: also list files removed from the library, each marked `hidden: true`. */
+        includeHidden: z.ZodOptional<z.ZodEnum<["true", "false"]>>;
     }, "strip", z.ZodTypeAny, {
         cursor?: string | undefined;
         limit?: number | undefined;
+        includeHidden?: "true" | "false" | undefined;
     }, {
         cursor?: string | undefined;
         limit?: number | undefined;
+        includeHidden?: "true" | "false" | undefined;
     }>, undefined, AssetsListResponse>;
-    readonly delete: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+    readonly hide: import("./route-builder.js").RouteDefinition<undefined, z.ZodObject<{
+        key: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+    }, {
+        key: string;
+    }>, AssetVisibilityResponse>;
+    readonly restore: import("./route-builder.js").RouteDefinition<undefined, z.ZodObject<{
         key: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         key: string;
     }, {
         key: string;
-    }>, undefined, AssetDeleteResponse>;
+    }>, AssetVisibilityResponse>;
+    readonly deleteGone: RouteDefinition;
 };
 /**
  * GET /assets/raw/{key...} - see `rawAssetHandler` above for why this is

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
- * .claude/future-tasks/asset-listing-cross-branch-exposure.md).
+ * 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
+ * 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.
  *
- * Coupled to the blob-GC follow-up in asset-review-followups.md: 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.
+ * 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
@@ -382,20 +418,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 +463,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/branch-merge.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
-/** @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md. */
+/** @internal No importer; deletion candidate in safeinsights/canopycms#725. */
 export interface MarkAsMergedParams {
     branch: string;
 }

package/dist/api/branch.js

@@ -514,7 +514,7 @@ export const deleteBranchHandler = async (ctx, req, params) => {
     // writableBranch/submittableBranch guards elsewhere use 403 for the same
     // "protected" category (tracked as a deferred, deliberately out-of-scope
     // cleanup in
-    // .claude/future-tasks/protected-branch-followup-cleanups.md); extending
+    // safeinsights/canopycms#781); extending
     // this check to 'approved' keeps it consistent with its own immediate
     // neighbour rather than introducing a fresh 400/403 split between two
     // arms of the same guard.

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/content.js

@@ -506,7 +506,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
                     ok: false,
                     status: 409,
                     error: err.message,
-                    ...(err.outcome === 'unknown' ? { code: 'WRITE_OUTCOME_UNKNOWN' } : {}),
+                    code: err.outcome === 'unknown' ? 'WRITE_OUTCOME_UNKNOWN' : 'BRANCH_SYNCING',
                 };
             }
             // [F1] Also not an editor collision: this content ID is quarantined on two files

package/dist/api/entries-constants.d.ts

@@ -14,7 +14,7 @@ export declare const DEFAULT_ENTRIES_LIMIT = 50;
  * The generic 409 for a conflicting change to an entry, usually its version moving on since the
  * caller read it. Shared with the editor, whose own pre-save staleness check reports the same.
  */
-export declare const ENTRY_CHANGED_MESSAGE = "This entry changed since you opened it. Reload to see the latest version (your unsaved edits will be lost).";
+export declare const ENTRY_CHANGED_MESSAGE = "This entry changed since you opened it. Choose \"Refresh from server\" to see the latest version (your unsaved edits will be lost).";
 /**
  * The 409 for an update whose entry is gone: deleted or moved since the caller read it (API code
  * `ENTRY_GONE`). The save is refused rather than re-creating the entry; re-creating it is a create

package/dist/api/entries-constants.js

@@ -14,7 +14,7 @@ export const DEFAULT_ENTRIES_LIMIT = 50;
  * The generic 409 for a conflicting change to an entry, usually its version moving on since the
  * caller read it. Shared with the editor, whose own pre-save staleness check reports the same.
  */
-export const ENTRY_CHANGED_MESSAGE = 'This entry changed since you opened it. Reload to see the latest version (your unsaved edits will be lost).';
+export const ENTRY_CHANGED_MESSAGE = 'This entry changed since you opened it. Choose "Refresh from server" to see the latest version (your unsaved edits will be lost).';
 /**
  * The 409 for an update whose entry is gone: deleted or moved since the caller read it (API code
  * `ENTRY_GONE`). The save is refused rather than re-creating the entry; re-creating it is a create

package/dist/api/entries.d.ts

@@ -5,7 +5,7 @@ import type { LogicalPath, PhysicalPath, Slug, ContentId } from '../paths/types.
 /**
  * Summary of an entry type for client display.
  * Simplified from EntryTypeConfig - doesn't include full field definitions.
- * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ * @internal No importer; deletion candidate in safeinsights/canopycms#725.
  */
 export interface EntryTypeSummary {
     name: string;
@@ -28,7 +28,7 @@ export interface CollectionItem {
     exists?: boolean;
     canEdit?: boolean;
 }
-/** @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md. */
+/** @internal No importer; deletion candidate in safeinsights/canopycms#725. */
 export interface ListEntriesParams {
     branch: string;
     collection?: LogicalPath;

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/api/permissions.d.ts

@@ -154,10 +154,10 @@ declare const batchGetUserMetadataBodySchema: z.ZodObject<{
     userIds: string[];
 }>;
 export type UpdatePermissionsBody = z.infer<typeof updatePermissionsBodySchema>;
-/** @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md. */
+/** @internal No importer; deletion candidate in safeinsights/canopycms#725. */
 export type SearchUsersParams = z.infer<typeof searchUsersParamsSchema>;
 export type BatchGetUserMetadataBody = z.infer<typeof batchGetUserMetadataBodySchema>;
-/** @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md. */
+/** @internal No importer; deletion candidate in safeinsights/canopycms#725. */
 export type GetUserMetadataParams = z.infer<typeof getUserMetadataParamsSchema>;
 /**
  * Exported routes for router registration

package/dist/api/types.d.ts

@@ -63,6 +63,7 @@ export interface ApiResponse<TData = unknown> {
  * server runs (a 412, see operating-mode/editor-mode-check.ts); only a rebuild fixes it.
  * `SETTINGS_CHANGED`: a groups or permissions save named a version the file has moved on from (a
  * 409, see `SettingsVersionConflictError`); nothing was saved, and a reload shows the other edit.
- * The other settings 409, a busy file lock, carries no code.
+ * The other settings 409, a busy file lock, carries no code. `BRANCH_SYNCING`: an entry save was
+ * refused because the branch is mid-rebase (a 409); nothing was saved, and a retry soon can pass.
  */
-export type ApiErrorCode = 'SCHEMA_UNAVAILABLE' | 'WORKER_FAILED' | 'WRITE_OUTCOME_UNKNOWN' | 'ENTRY_GONE' | 'EDITOR_MODE_MISMATCH' | 'SETTINGS_CHANGED';
+export type ApiErrorCode = 'SCHEMA_UNAVAILABLE' | 'WORKER_FAILED' | 'WRITE_OUTCOME_UNKNOWN' | 'ENTRY_GONE' | 'EDITOR_MODE_MISMATCH' | 'SETTINGS_CHANGED' | 'BRANCH_SYNCING';

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/finalize.js

@@ -5,6 +5,8 @@
  */
 import { runFinalizePipeline } from './pipeline.js';
 import { ASSET_PREFIXES } from './keys.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
@@ -37,8 +39,19 @@ 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)}`);
+        }
         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.

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/store-local.d.ts

@@ -3,9 +3,9 @@
  * bucket-prefix layout as S3AssetStore (see keys.ts) so content behaves
  * identically across adapters.
  */
-import type { AssetMeta, AssetStore, BeginUploadInput, CreateOnlyResult, PublicObject, StagedUploadTarget } from './types.js';
+import type { AssetMeta, AssetStore, BeginUploadInput, CreateOnlyResult, HiddenAssetMarker, ListedAssetMeta, PublicObject, StagedUploadTarget } from './types.js';
 export interface LocalAssetStoreOptions {
-    /** Root directory. The five bucket prefixes are created as subdirectories under it. */
+    /** Root directory. The six bucket prefixes are created as subdirectories under it. */
     root: string;
 }
 export declare class LocalAssetStore implements AssetStore {
@@ -33,11 +33,12 @@ export declare class LocalAssetStore implements AssetStore {
     /** Link `tempPath` in at `filePath`; `false` when something is already there. */
     private linkIfAbsent;
     /**
-     * Create-only write of a blob and its headers sidecar. Each is written whole to a temp file, then
-     * `link()`ed into place, which fails with EEXIST rather than replacing (see docs/concurrency.md).
-     * The sidecar is linked first, so a reader never finds a blob without its headers. A sidecar
-     * already there was linked by an earlier writer of this key and is kept, as the blob is: the
-     * first writer's headers win, as on S3 (a static's Content-Disposition names its uploaded file).
+     * Create-only write of a blob and, when `headers` is given, its headers sidecar. Each is written
+     * whole to a temp file, then `link()`ed into place, which fails with EEXIST rather than replacing
+     * (see docs/concurrency.md). The sidecar is linked first, so a reader never finds a blob without
+     * its headers. A sidecar already there was linked by an earlier writer of this key and is kept,
+     * as the blob is: the first writer's headers win, as on S3 (a static's Content-Disposition names
+     * its uploaded file).
      */
     private createExclusive;
     beginUpload(_input: BeginUploadInput): Promise<StagedUploadTarget>;
@@ -85,12 +86,20 @@ export declare class LocalAssetStore implements AssetStore {
      */
     putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<CreateOnlyResult>;
     getMeta(hash32: string): Promise<AssetMeta | null>;
+    /**
+     * The cursor names the last item returned, and the next page starts after it in sort order, so a
+     * page boundary holds when that item is hidden in between: its meta is never deleted, and the
+     * comparison needs only its place, not its presence in the filtered list.
+     */
     listMeta(input?: {
         cursor?: string;
         limit?: number;
+        includeHidden?: boolean;
     }): Promise<{
-        items: AssetMeta[];
+        items: ListedAssetMeta[];
         nextCursor?: string;
     }>;
-    deleteMeta(hash32: string): Promise<void>;
+    private hiddenHashes;
+    hideAsset(hash32: string, marker: HiddenAssetMarker): Promise<CreateOnlyResult>;
+    unhideAsset(hash32: string): Promise<boolean>;
 }