canopycms 0.2.0-int.119 → 0.2.0

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,7 @@
  */
 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';
 /**
@@ -25,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) {
@@ -50,6 +52,8 @@ export async function finalizeAsset(store, input) {
         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
@@ -62,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/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. */

package/dist/assets/store-s3.d.ts

@@ -5,7 +5,7 @@
  * six asset prefixes, plus a caller's output prefix for `copyPublicObject`.
  */
 import { type AssetPrefixes } from './keys.js';
-import type { AssetMeta, AssetStore, BeginUploadInput, CreateOnlyResult, HiddenAssetMarker, ListedAssetMeta, PublicObject, StagedUploadTarget } from './types.js';
+import type { AssetMeta, AssetStore, BeginUploadInput, CreateOnlyResult, HiddenAssetMarker, ListedAssetMeta, PresignedRead, PublicObject, StagedUploadTarget } from './types.js';
 export interface S3AssetStoreOptions {
     bucket: string;
     region: string;
@@ -103,8 +103,12 @@ export declare class S3AssetStore implements AssetStore {
     hasPublicObject(key: string): Promise<boolean>;
     listPublicObjectKeys(prefix: string): AsyncIterable<string>;
     private listKeys;
-    /** HEADs first: signing is local and succeeds for a missing key too. */
-    presignPublicObjectRead(key: string): Promise<string | null>;
+    /**
+     * HEADs first: signing is local and succeeds for a missing key too. A URL signed with temporary
+     * credentials dies when they expire, whatever its own expiry, so `maxAgeSeconds` also stops short
+     * of the credentials' `expiration` when the provider reports one.
+     */
+    presignPublicObjectRead(key: string): Promise<PresignedRead | null>;
     putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<CreateOnlyResult>;
     getMeta(hash32: string): Promise<AssetMeta | null>;
     /**

package/dist/assets/store-s3.js

@@ -14,8 +14,15 @@ const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
 /** What `metaKey` and `hiddenKey` put after the hash32. */
 const JSON_SUFFIX = '.json';
 const PRESIGN_EXPIRY_SECONDS = 15 * 60;
-/** A presigned read is followed by the browser at once; it is never stored or cached. */
-const PRESIGNED_READ_EXPIRY_SECONDS = 5 * 60;
+/**
+ * A presigned read is signed at the start of its window, so every read of one key inside a window
+ * gets the same URL, and a browser can reuse both the redirect to it and the object behind it.
+ */
+const PRESIGNED_READ_WINDOW_SECONDS = 60 * 60;
+/** Valid a full window past the window's end, so a redirect cached until then never expires first. */
+const PRESIGNED_READ_EXPIRY_SECONDS = 2 * PRESIGNED_READ_WINDOW_SECONDS;
+/** How long before its signing credentials expire a presigned read stops being reusable. */
+const CREDENTIAL_EXPIRY_MARGIN_SECONDS = 60;
 function matchesAwsError(err, name, httpStatusCode) {
     if (!(err instanceof Error))
         return false;
@@ -248,13 +255,25 @@ export class S3AssetStore {
             }
         }
     }
-    /** HEADs first: signing is local and succeeds for a missing key too. */
+    /**
+     * HEADs first: signing is local and succeeds for a missing key too. A URL signed with temporary
+     * credentials dies when they expire, whatever its own expiry, so `maxAgeSeconds` also stops short
+     * of the credentials' `expiration` when the provider reports one.
+     */
     async presignPublicObjectRead(key) {
         if (!(await this.hasPublicObject(key)))
             return null;
-        return getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), {
-            expiresIn: PRESIGNED_READ_EXPIRY_SECONDS,
-        });
+        // Read before signing: a provider refresh in between leaves the signing credentials the newer.
+        const { expiration } = await this.client.config.credentials();
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        const windowStart = nowSeconds - (nowSeconds % PRESIGNED_READ_WINDOW_SECONDS);
+        const url = await getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), { expiresIn: PRESIGNED_READ_EXPIRY_SECONDS, signingDate: new Date(windowStart * 1000) });
+        let maxAgeSeconds = windowStart + PRESIGNED_READ_WINDOW_SECONDS - nowSeconds;
+        if (expiration) {
+            const credentialSeconds = Math.floor(expiration.getTime() / 1000) - nowSeconds;
+            maxAgeSeconds = Math.min(maxAgeSeconds, credentialSeconds - CREDENTIAL_EXPIRY_MARGIN_SECONDS);
+        }
+        return { url, maxAgeSeconds: Math.max(0, maxAgeSeconds) };
     }
     async putMetaIfAbsent(hash32, meta) {
         return this.putIfAbsent({

package/dist/assets/types.d.ts

@@ -50,6 +50,11 @@ export interface PublicObject {
     contentDisposition?: string;
     cacheControl?: string;
 }
+/** A presigned GET, and how long a client may keep reusing that URL (0: not at all). */
+export interface PresignedRead {
+    url: string;
+    maxAgeSeconds: number;
+}
 /**
  * What a create-only write did. Every key the store writes this way is content-addressed, so no
  * correct writer ever replaces an object: `already-exists` means an object was already at the key
@@ -102,8 +107,8 @@ export interface AssetStore {
     hasPublicObject(key: string): Promise<boolean>;
     /** Every public object key under `prefix`, in the store's own pages. S3 only. */
     listPublicObjectKeys?(prefix: string): AsyncIterable<string>;
-    /** A short-lived URL a browser can GET `key` from directly, or `null` if absent. S3 only. */
-    presignPublicObjectRead?(key: string): Promise<string | null>;
+    /** A URL a browser can GET `key` from directly, or `null` if absent. S3 only. */
+    presignPublicObjectRead?(key: string): Promise<PresignedRead | null>;
     /**
      * Meta is create-only and never deleted: every transform not yet stored, at upload, release or
      * after a lazy output expires, is computed from it, and content anywhere may still name the file.

package/dist/cli/cli.js

@@ -13321,6 +13321,21 @@ var init_generate_ai_content = __esm({
   }
 });
 
+// dist/utils/logger.js
+function canopyLogWarn3(...args) {
+  active3.warn(...args);
+}
+function canopyLogError2(...args) {
+  active3.error(...args);
+}
+var active3;
+var init_logger3 = __esm({
+  "dist/utils/logger.js"() {
+    "use strict";
+    active3 = console;
+  }
+});
+
 // dist/assets/asset-prefixes.js
 var ASSET_PREFIXES;
 var init_asset_prefixes = __esm({
@@ -13339,21 +13354,6 @@ var init_asset_prefixes = __esm({
   }
 });
 
-// dist/utils/logger.js
-function canopyLogWarn3(...args) {
-  active3.warn(...args);
-}
-function canopyLogError2(...args) {
-  active3.error(...args);
-}
-var active3;
-var init_logger3 = __esm({
-  "dist/utils/logger.js"() {
-    "use strict";
-    active3 = console;
-  }
-});
-
 // dist/assets/sharp-loader.js
 function loadSharp() {
   if (!loading) {
@@ -13723,7 +13723,11 @@ var init_transform = __esm({
 
 // dist/assets/materialize.js
 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` };
   }
@@ -13741,7 +13745,7 @@ async function storeTransform(store, parsed, key, options = {}) {
   if (requestedFormat === void 0 && 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` };
   }
@@ -14144,7 +14148,7 @@ function matchesAwsError(err2, name, httpStatusCode) {
   const shaped = err2;
   return shaped.name === name || shaped.$metadata?.httpStatusCode === httpStatusCode;
 }
-var DEFAULT_MAX_UPLOAD_BYTES, JSON_SUFFIX, PRESIGN_EXPIRY_SECONDS, PRESIGNED_READ_EXPIRY_SECONDS, isPreconditionFailed, isConditionalRequestConflict, CONFLICT_ATTEMPTS, CONFLICT_BASE_DELAY_MS, isNoSuchKey, S3AssetStore;
+var DEFAULT_MAX_UPLOAD_BYTES, JSON_SUFFIX, PRESIGN_EXPIRY_SECONDS, PRESIGNED_READ_WINDOW_SECONDS, PRESIGNED_READ_EXPIRY_SECONDS, CREDENTIAL_EXPIRY_MARGIN_SECONDS, isPreconditionFailed, isConditionalRequestConflict, CONFLICT_ATTEMPTS, CONFLICT_BASE_DELAY_MS, isNoSuchKey, S3AssetStore;
 var init_store_s3 = __esm({
   "dist/assets/store-s3.js"() {
     "use strict";
@@ -14153,7 +14157,9 @@ var init_store_s3 = __esm({
     DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
     JSON_SUFFIX = ".json";
     PRESIGN_EXPIRY_SECONDS = 15 * 60;
-    PRESIGNED_READ_EXPIRY_SECONDS = 5 * 60;
+    PRESIGNED_READ_WINDOW_SECONDS = 60 * 60;
+    PRESIGNED_READ_EXPIRY_SECONDS = 2 * PRESIGNED_READ_WINDOW_SECONDS;
+    CREDENTIAL_EXPIRY_MARGIN_SECONDS = 60;
     isPreconditionFailed = (err2) => matchesAwsError(err2, "PreconditionFailed", 412);
     isConditionalRequestConflict = (err2) => err2 instanceof Error && err2.name === "ConditionalRequestConflict";
     CONFLICT_ATTEMPTS = 4;
@@ -14358,13 +14364,24 @@ var init_store_s3 = __esm({
           }
         }
       }
-      /** HEADs first: signing is local and succeeds for a missing key too. */
+      /**
+       * HEADs first: signing is local and succeeds for a missing key too. A URL signed with temporary
+       * credentials dies when they expire, whatever its own expiry, so `maxAgeSeconds` also stops short
+       * of the credentials' `expiration` when the provider reports one.
+       */
       async presignPublicObjectRead(key) {
         if (!await this.hasPublicObject(key))
           return null;
-        return getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), {
-          expiresIn: PRESIGNED_READ_EXPIRY_SECONDS
-        });
+        const { expiration } = await this.client.config.credentials();
+        const nowSeconds = Math.floor(Date.now() / 1e3);
+        const windowStart = nowSeconds - nowSeconds % PRESIGNED_READ_WINDOW_SECONDS;
+        const url = await getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), { expiresIn: PRESIGNED_READ_EXPIRY_SECONDS, signingDate: new Date(windowStart * 1e3) });
+        let maxAgeSeconds = windowStart + PRESIGNED_READ_WINDOW_SECONDS - nowSeconds;
+        if (expiration) {
+          const credentialSeconds = Math.floor(expiration.getTime() / 1e3) - nowSeconds;
+          maxAgeSeconds = Math.min(maxAgeSeconds, credentialSeconds - CREDENTIAL_EXPIRY_MARGIN_SECONDS);
+        }
+        return { url, maxAgeSeconds: Math.max(0, maxAgeSeconds) };
       }
       async putMetaIfAbsent(hash32, meta) {
         return this.putIfAbsent({

package/dist/config/types.d.ts

@@ -144,8 +144,9 @@ export interface ReferenceFieldConfig extends BaseFieldConfig {
 export interface ImageFieldConfig extends BaseFieldConfig {
     type: 'image';
     /**
-     * "W:H" aspect ratio (e.g. "16:9", "1:1") that triggers a crop step in the
-     * editor. Validated at config-parse time: positive integers on both sides.
+     * "W:H" aspect ratio (e.g. "16:9", "1:1"). Picking an image opens a crop step locked to it,
+     * and Crop keeps that shape. Without it, a pick isn't cropped and Crop is free-form.
+     * Validated at config-parse time: positive integers on both sides.
      */
     aspect?: string;
     /** Allow an empty `alt`. Default: alt text is required (accessibility). */

package/dist/dev-content-watcher.js

@@ -194,7 +194,14 @@ export function startDevContentWatcher(services, options = {}) {
             }
         }
     };
-    const watcher = chokidar.watch(workingTreeContentDir, { ignoreInitial: true });
+    // A save can truncate and then write. chokidar's 50 ms per-path throttle passes only the first
+    // `change`, which can land between the two steps: a check then reads a half-written file and
+    // reports a divergence nothing retracts. `awaitWriteFinish` emits only once the file's size has
+    // held still, and bypasses that throttle.
+    const watcher = chokidar.watch(workingTreeContentDir, {
+        ignoreInitial: true,
+        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 25 },
+    });
     watcher.on('add', () => void check());
     watcher.on('change', () => void check());
     watcher.on('unlink', () => void check());

package/dist/editor/Editor.js

@@ -9,6 +9,8 @@ const noop = () => { };
 import { EntryNavigator } from './EntryNavigator.js';
 import { FormRenderer } from './FormRenderer.js';
 import { PreviewPane } from './PreviewPane.js';
+import { displayPreviewPath, previewPageKey } from './preview-path.js';
+import { showPreviewLinkOutcome } from './components/PreviewLinkToast.js';
 import { clientOperatingStrategy } from '../operating-mode/client.js';
 import { EditorShell } from './shell/EditorShell.js';
 import { PaneLayout } from './shell/PaneLayout.js';
@@ -31,7 +33,7 @@ import { EntrySchemaUnavailableError } from './hooks/useEntryManager.js';
 import { useEntryLinkResolution } from './hooks/useEntryLinkResolution.js';
 import { useReferenceResolution } from './hooks/useReferenceResolution.js';
 import { usePreviewMarks } from './hooks/usePreviewMarks.js';
-import { BranchLockBanner, EditorHeader, EditorRail } from './components/index.js';
+import { BranchLockBanner, describeBranchLock, EditorHeader, EditorRail } from './components/index.js';
 import { showSaveAllResult } from './components/SaveAllResult.js';
 import { RenameEntryModal } from './components/RenameEntryModal.js';
 import { QuickOpenPalette } from './components/QuickOpenPalette.js';
@@ -60,6 +62,7 @@ import { findFieldTarget, focusFieldTarget } from './field-target.js';
 import { UndoToastMessage } from './components/UndoToastMessage.js';
 import { getNotificationDuration } from './utils/env.js';
 import { MayHaveLandedError } from './unanswered.js';
+import { sanitizeBranchName } from '../paths/branch-name.js';
 // Stable fallbacks, so reference resolution's memo and effect don't re-run on every render
 // while no entry is open.
 const EMPTY_SCHEMA = [];
@@ -155,7 +158,7 @@ const EditorContent = ({ entries, title, siteTitle = title, branchName = '', col
         labels: [],
     }));
     const applySubmitStampsRef = useRef(() => { });
-    const { branchName: branchNameState, setBranchName, branchSummaries, currentBranch, addCreatedBranch, handleSubmit, handleWithdraw, handleRequestChanges, handleDelete, handleReloadBranchData, loadBranches, } = useBranchManager({
+    const { branchName: branchNameState, setBranchName, branchSummaries, currentBranch, branchesLoadFailed, addCreatedBranch, handleSubmit, handleWithdraw, handleRequestChanges, handleDelete, handleReloadBranchData, loadBranches, } = useBranchManager({
         initialBranch: branchName,
         operatingMode,
         setBusy: setBranchesLoading,
@@ -176,6 +179,12 @@ const EditorContent = ({ entries, title, siteTitle = title, branchName = '', col
     // of unlocked that invites a click the server rejects -- and the pane shows a
     // loading state during that window anyway.
     const branchContentLocked = currentBranch?.writeBlocked ?? true;
+    const branchLoading = !currentBranch && (branchesLoading || branchSummaries.length === 0);
+    // A row's lock reason on an unanswered branch would be "details could not be loaded", which is
+    // not yet true; once the fetch has failed it is, and the lock says so.
+    const branchRowsPending = branchLoading && !branchesLoadFailed;
+    // Set once the branch actions below exist; they depend on the drafts, which depend on the entries.
+    const switchBranchRef = useRef(async () => { });
     // 2. Entry manager (depends on branchNameState, owns selectedPath)
     const { selectedPath, setSelectedPath, closeEntry, entries: entriesState, collections: collectionsFromApi, currentEntry, availableSchemas, entriesInitializing, entriesLoadFailed, navigatorOpen, setNavigatorOpen, refreshEntries, refreshContent, handleCreateEntry, renameEntry, loadEntry, readEntryValue, saveEntry, getEntryVersion, adoptEntryVersion, followMovedEntry, recreateEntry, createModalOpen, createModalCollection, createModalError, createModalCreating, createModalExistingSlugs, handleCreateModalSubmit, closeCreateModal, } = useEntryManager({
         initialEntries: entries,
@@ -191,6 +200,13 @@ const EditorContent = ({ entries, title, siteTitle = title, branchName = '', col
         }),
         resolvePreviewRoute: (entry) => buildPreviewRoute(entry, { previewBaseByCollection, contentRoot }),
         setBusy: setEntriesLoading,
+        switchBranch: (branch) => switchBranchRef.current(branch),
+        // To the entry menu, which names the entry opened; a dialog keeps focus.
+        onHistoryRestore: () => requestAnimationFrame(() => {
+            if (!document.activeElement?.closest('[role="dialog"]')) {
+                navigatorToggleRef.current?.focus({ preventScroll: true });
+            }
+        }),
     });
     // The content overlay and a maximized preview hide the form; `navigatorOpen` is only the
     // overlay's. Anything that focuses something in the form reveals it first. Opening an entry
@@ -205,6 +221,26 @@ const EditorContent = ({ entries, title, siteTitle = title, branchName = '', col
         setSelectedPath(path);
         setNavigatorOpen(false);
     };
+    // A preview link opens its entry, or a page no entry has in a new tab. The opener is cut by hand,
+    // since `noopener` would hide whether the browser blocked the tab.
+    const openPreviewLink = (href) => {
+        const mount = { basePath, previewPrefix };
+        const base = window.location.href;
+        const page = previewPageKey(href, mount, base);
+        const entry = page === undefined
+            ? undefined
+            : entriesState.find((e) => e.previewSrc && previewPageKey(e.previewSrc, mount, base) === page);
+        if (entry) {
+            openEntry(entry.path);
+            return;
+        }
+        const opened = window.open(href, '_blank');
+        if (opened)
+            opened.opener = null;
+        const url = new URL(href);
+        const shown = url.origin === window.location.origin ? `${url.pathname}${url.search}` : href;
+        showPreviewLinkOutcome(href, displayPreviewPath(shown, mount), Boolean(opened));
+    };
     // An open overlay docks open, as the URL's ask for no entry does at load; `navigatorOpen` is only
     // the overlay's, so a docked panel never resurfaces as one. Waits for the stored preferences, so
     // the open state it sets lands on them, not on the defaults they replace.
@@ -270,6 +306,17 @@ const EditorContent = ({ entries, title, siteTitle = title, branchName = '', col
         onBranchCreated: addCreatedBranch,
         userId: userContext?.userId,
     });
+    switchBranchRef.current = async (branch) => {
+        const listed = (name) => name === branch || name === sanitizeBranchName(branch);
+        if (branchSummaries.length > 0 && !branchSummaries.some((b) => listed(b.name))) {
+            notifications.show({
+                message: `Branch “${branch}” no longer exists or you can no longer open it, so you're still on “${branchNameState}”.`,
+                color: 'yellow',
+            });
+            throw new Error(`Branch ${branch} is not listed`);
+        }
+        await handleBranchChange(branch);
+    };
     // 5. Comment system (depends on branchNameState)
     const { comments, getCommentUser, focusedFieldPath, highlightThreadId, commentsPanelOpen, setCommentsPanelOpen, handleAddComment, handleResolveThread, handleJumpToField, handleJumpToEntry, handleJumpToBranch, } = useCommentSystem({
         branchName: branchNameState,
@@ -859,8 +906,8 @@ const EditorContent = ({ entries, title, siteTitle = title, branchName = '', col
                 setDeletingEntryReferencedBy(result.referencedBy);
                 return;
             }
-            if (result.ok && selectedPath === deletingEntryPath)
-                closeEntry();
+            if (result.ok)
+                closeEntry(deletingEntryPath, branchNameState);
             closeDeleteEntryModal();
         }
         finally {
@@ -1208,7 +1255,7 @@ const EditorContent = ({ entries, title, siteTitle = title, branchName = '', col
             if (maximized && !contentPanelDocked)
                 setNavigatorOpen(false);
             setPreviewMaximized(maximized);
-        }, resizing: paneResizing, siteChrome: siteChrome, onSiteChromeChange: setSiteChrome, notice: previewError && (_jsx(Alert, { color: "red", title: "Preview error", withCloseButton: true, onClose: () => setPreviewError(null), radius: 0, children: previewErrorField
+        }, resizing: paneResizing, siteChrome: siteChrome, onSiteChromeChange: setSiteChrome, onNavigate: openPreviewLink, notice: previewError && (_jsx(Alert, { color: "red", title: "Preview error", withCloseButton: true, onClose: () => setPreviewError(null), radius: 0, children: previewErrorField
                 ? `${previewErrorField}: ${previewError.message}`
                 : previewError.message })) })) : (_jsx(Paper, { withBorder: true, shadow: "xs", h: "100%", bg: "var(--mantine-color-body)", style: {
             display: 'flex',
@@ -1266,7 +1313,13 @@ const EditorContent = ({ entries, title, siteTitle = title, branchName = '', col
                         missing: e.status === 'missing' || undefined,
                         noPage: !e.previewSrc || undefined,
                         readOnly: e.canEdit === false || undefined,
-                    })), selectedPath: selectedPath, onSelect: openEntry, onTreeControllerReady: handleTreeControllerReady, expandedStateRef: treeExpandedStateRef, onExpandedStateChange: handleExpandedStateChange, onDeleteEntry: handleDeleteEntry, onRenameEntry: handleRenameEntry, onReorderEntry: userIsAdmin ? handleReorderEntry : undefined, hiddenRootPath: hiddenRootPath, loading: entriesInitializing, readOnly: branchContentLocked, dirtyPaths: dirtyPaths, revealCollection: collectionReveal, onRevealed: () => setCollectionReveal(undefined) }) }) }));
+                    })), selectedPath: selectedPath, onSelect: openEntry, onTreeControllerReady: handleTreeControllerReady, expandedStateRef: treeExpandedStateRef, onExpandedStateChange: handleExpandedStateChange, onDeleteEntry: handleDeleteEntry, onRenameEntry: handleRenameEntry, onReorderEntry: userIsAdmin ? handleReorderEntry : undefined, hiddenRootPath: hiddenRootPath, loading: entriesInitializing, readOnly: branchContentLocked, readOnlyReason: branchRowsPending
+                    ? undefined
+                    : describeBranchLock({
+                        branchStatus: currentBranch?.status,
+                        branchReadOnly: currentBranch?.readOnly,
+                        branchWriteBlocked: branchContentLocked,
+                    }), dirtyPaths: dirtyPaths, revealCollection: collectionReveal, onRevealed: () => setCollectionReveal(undefined) }) }) }));
     return (_jsx(CanopyCMSProvider, { ...(themeOptions ?? {}), children: _jsx(AssetContextProvider, { basePath: basePath, children: _jsx(EditorShell, { topBar: _jsx(EditorHeader, { currentEntry: currentEntry, branchName: branchNameState, operatingMode: operatingMode, branchStatus: currentBranch?.status, busy: busy, breadcrumbSegments: breadcrumbSegments, editedFiles: editedFiles, modifiedCount: modifiedCount, 
                     // A draft kept for an unavailable entry stays in storage but cannot be saved.
                     hasUnsavedChanges: !currentEntryUnavailable && !contentReadOnly && isSelectedDirty(), entryHasDraft: isSelectedDirty(), entryReadOnly: currentEntry?.canEdit === false, draftStorageFailed: draftStorageFailed, userContext: userContext, branchCreatedBy: currentBranch?.createdBy, branchAccess: currentBranch?.access, 
@@ -1279,7 +1332,7 @@ const EditorContent = ({ entries, title, siteTitle = title, branchName = '', col
                     // fail-closed computation of "are writes blocked" in this component.
                     branchIsProtected: currentBranch?.isProtected ?? true, branchReadOnly: currentBranch?.readOnly, branchWriteBlocked: branchContentLocked, 
                     // A failed fetch leaves the list empty too; the banner says that one.
-                    branchLoading: !currentBranch && (branchesLoading || branchSummaries.length === 0), onCollectionOpen: revealCollection, navigatorToggleRef: navigatorToggleRef, branchToggleRef: branchToggleRef, onFileReload: () => handleReload(() => navigatorToggleRef.current), onFileDiscardDraft: () => handleDiscardFileDraft(() => navigatorToggleRef.current), onEntryRename: () => currentEntry && handleRenameEntry(currentEntry.path, true), onEntryDelete: () => currentEntry && handleDeleteEntry(currentEntry.path, true), entryUnavailable: currentEntryUnavailable, onEntrySelect: openEntry, onBranchReloadData: () => {
+                    branchLoading: branchLoading, onCollectionOpen: revealCollection, navigatorToggleRef: navigatorToggleRef, branchToggleRef: branchToggleRef, onFileReload: () => handleReload(() => navigatorToggleRef.current), onFileDiscardDraft: () => handleDiscardFileDraft(() => navigatorToggleRef.current), onEntryRename: () => currentEntry && handleRenameEntry(currentEntry.path, true), onEntryDelete: () => currentEntry && handleDeleteEntry(currentEntry.path, true), entryUnavailable: currentEntryUnavailable, onEntrySelect: openEntry, onBranchReloadData: () => {
                         void Promise.all([handleReloadBranchData(), refreshEntries(branchNameState)]).catch(console.error);
                     }, onBranchDiscardDrafts: () => handleDiscardDrafts(() => branchToggleRef.current), onBranchManagerOpen: openBranchManager, onSave: currentEntryUnavailable ? noop : handleSave, onSaveAll: runSaveAll, saveAllProgress: saveAllProgress, saving: singleSaving?.branch === branchNameState &&
                         singleSaving.contentId === currentEntry?.contentId, savedSignal: lastSaved?.seq, savedHere: lastSaved?.branch === branchNameState &&

package/dist/editor/EntryNavigator.d.ts

@@ -62,12 +62,17 @@ export interface EntryNavigatorProps {
     /** When true and the tree is empty, show a loading indicator instead of "No content" */
     loading?: boolean;
     /**
-     * When true, hides all entry/collection mutation affordances (create,
-     * rename, delete, reorder, add/edit collection) -- selection/navigation
-     * stays enabled. Set on a read-only protected base branch, where writes
-     * would only 403 after the fact. Default false.
+     * When true, replaces each row's mutation menu (create, rename, delete, reorder, add/edit
+     * collection) with a lock -- selection/navigation stays enabled. Set on a branch that takes no
+     * writes, where they would only 403 after the fact. An entry the user may not edit keeps its own
+     * lock and gets none here. Default false.
      */
     readOnly?: boolean;
+    /**
+     * Why the branch takes no writes (`describeBranchLock`), the tooltip of each row's lock. While
+     * readOnly without one, the lock's slot stays empty.
+     */
+    readOnlyReason?: string;
     /** Entry paths with unsaved changes; each shows a dot, and so does every collection holding one. */
     dirtyPaths?: ReadonlySet<string>;
     /**