canopycms 0.0.67 → 0.0.68-int.100

package/README.md

@@ -45,7 +45,7 @@ you misunderstood, which is why it is worth resolving the ref rather than guessi
 
 ## Branch roots
 
-- Workspaces resolve per mode: `prod` uses `$CANOPYCMS_WORKSPACE_ROOT/content-branches` (default: `/mnt/efs/workspace/content-branches`), `dev` uses `.canopy-dev/content-branches/<branch>`.
+- Workspaces resolve per mode: `prod` uses `$CANOPYCMS_WORKSPACE_ROOT/content-branches` (default: `/mnt/efs/content-branches`), `dev` uses `.canopy-dev/content-branches/<branch>`.
 - For `prod` mode, you must set `defaultRemoteUrl`. For `dev`, `defaultRemoteUrl` is **optional** - if omitted, a local remote is auto-created at `.canopy-dev/remote.git`.
 - Optionally configure `defaultRemoteName` (default: `origin`) and `defaultBaseBranch` (default: `main`).
 - Git author identity is required for `prod` mode: set `gitBotAuthorName` and `gitBotAuthorEmail` so bot commits can be created reliably.
@@ -104,6 +104,7 @@ export default defineCanopyConfig({
       colors: { brand: '#4f46e5' },
     },
     // previewBase: { 'content/posts': '/blog' }, // optional overrides
+    // previewPrefix: '/preview', // optional, in front of every preview URL
   },
   // For prod mode, defaultRemoteUrl is required.
   // For dev, it's optional - if omitted, uses auto-initialized local remote at .canopy-dev/remote.git
@@ -323,7 +324,7 @@ name) works, but leaves the entry's real `urlPath` as
 URL-derived surface then has to be told about one at a time. The example app in this repo used to
 do that and no longer does.
 
-Both methods return `{ data, path }`. `read` throws if the content is missing; `readByUrlPath` returns `null` instead. Pass a `branch` option when you want branch-specific data (e.g., for preview); otherwise it defaults to your configured base branch. Both enforce the same branch/path access rules as the API handlers.
+Both methods return `{ data, path }`. `read` throws if the content is missing; `readByUrlPath` returns `null` instead. Pass a `branch` option when you want branch-specific data (e.g., for preview); otherwise it defaults to the active branch: `defaultActiveBranch`, or when that is unset, git HEAD in `dev` and your base branch in `prod`. Any other branch must already exist and be readable by the current user, or it reads as not found. Both enforce the same branch/path access rules as the API handlers.
 
 **Index entries and URL resolution**
 
@@ -387,7 +388,7 @@ import config from '../canopycms.config'
 export default CanopyEditorPage(config)
 ```
 
-The editor loads entries on the client from `/api/canopycms/[branch]/entries`, so server prefetch is optional. Use `previewBaseByCollection` to control preview URLs per collection.
+The editor loads entries on the client from `/api/canopycms/[branch]/entries`, so server prefetch is optional. Use `editor.previewBase` to override preview URLs.
 
 6. **Theme it**
    Wrap editor surfaces with `CanopyCMSProvider` to load Mantine styles and customize `brand`/`primary`/`neutral`/`accent` colors and color scheme. Pass `themeOptions` into `Editor` if desired.
@@ -401,7 +402,7 @@ _TODO_ show real examples of what to do
 
 ### Preview branch awareness
 
-- When building preview URLs, include the current branch as a query param (e.g., `/?branch=feature-foo` or `/posts/hello?branch=feature-foo`) so SSR preview pages read from the same branch workspace the editor is editing. The `Editor` component appends the branch param automatically to `previewBaseByCollection`; your page loaders should read `searchParams.branch` and pass it into `createContentReader`.
+- When building preview URLs, include the current branch as a query param (e.g., `/?branch=feature-foo` or `/posts/hello?branch=feature-foo`) so SSR preview pages read from the same branch workspace the editor is editing. The `Editor` component appends the branch param to the preview URLs it builds; your page loaders should read `searchParams.branch` and pass it as the `branch` option to `getCanopy()`'s `read`/`readByUrlPath`.
 - For public static builds, omit/ignore the branch param; this pattern is only for the editor/preview environment.
 - Likewise, include `branch` in your editor route (e.g., `/edit?branch=feature-foo`) and have your editor page pass it to `<Editor>` so reloads/links preserve the selected branch. The `Editor` will also reflect branch switches back into the query string.
 
@@ -503,7 +504,7 @@ The `isLoading` object mirrors your data structure:
   - **Auto-initialization**: If no `defaultRemoteUrl` is configured, CanopyCMS automatically creates a local remote at `.canopy-dev/remote.git` and seeds it with your current `baseBranch` (e.g., `main`). This allows fully local testing of branching and submission workflows without requiring an external GitHub remote.
   - **Manual remote**: You can still provide an explicit `defaultRemoteUrl` to use a real remote or custom local path.
   - Use `npx canopycms sync push` / `npx canopycms sync pull` to sync content between your working tree and the CMS.
-- **`prod`**: EFS-backed roots under `$CANOPYCMS_WORKSPACE_ROOT` (default: `/mnt/efs/workspace`). Requires `defaultRemoteUrl`.
+- **`prod`**: EFS-backed roots under `$CANOPYCMS_WORKSPACE_ROOT` (default: `/mnt/efs`). Requires `defaultRemoteUrl`.
 
 Branch metadata lives in `.canopy-meta/branch.json`; registry in `branches.json` at the branches root. Content APIs resolve the workspace root from branch state + mode instead of relying on `process.cwd()`.
 
@@ -596,9 +597,9 @@ export default defineCanopyConfig({
 
 ## Assets and media
 
-Uploaded images and PDFs go into a content-addressed asset store, and images are served
-through an on-demand transform layer. Both the **local** adapter (for development) and the
-**S3** adapter ship today.
+Uploaded images and PDFs go into a content-addressed asset store, and images are served as
+resized derivatives stored before each release. Both the **local** adapter (for development)
+and the **S3** adapter ship today.
 
 ```typescript
 // canopycms.config.ts — production
@@ -616,8 +617,10 @@ media: { adapter: 's3', bucket: 'my-site-assets', region: 'us-east-1' }
   immutable and deduplicated. A draft branch references its images immediately; publishing
   needs no separate asset step.
 - **Delivery** — images are served from `/assets/t/{directives}/…` URLs that resize, crop and
-  convert to WebP on first request, then cache immutably. Build responsive markup with the
-  exported helpers, which are client-safe:
+  convert, written before release by `canopycms collect-asset-refs <outDir>` then
+  `canopycms materialize-assets --refs <file>`, and cached immutably. Every `/assets/t/` URL a
+  page can request must appear as text in the build output. Build responsive markup with the
+  exported helpers, which are client-safe and take any width from 1 to 8192:
 
   ```typescript
   import { assetUrl, assetSrcSet } from 'canopycms'
@@ -632,7 +635,9 @@ media: { adapter: 's3', bucket: 'my-site-assets', region: 'us-east-1' }
   />
   ```
 
-  SVGs and PDFs are served statically, with no transform.
+  Passing an `image` field value applies its stored crop (`opts.crop` overrides it). Its `width`
+  and `height` are the uncropped original's, so scale them by `crop.w` and `crop.h` for a cropped
+  value. SVGs and PDFs are served statically, with no transform.
 
 - **Where `/assets` is mounted** — the URLs above are root-relative, because that is what gets
   stored in content and content moves between branches and environments. If your renderer sees
@@ -669,8 +674,10 @@ to enable the interactive crop step, or `altOptional: true` for decorative image
 > CanopyCMS" as visible to your whole editorial team.
 
 For deployment, the `canopycms-cdk` package ships an `AssetSupport` construct that provisions
-the bucket, the transform Lambda and the CloudFront behaviors. Fuller documentation — every
-config option, the transform directive syntax, and the AWS wiring — is in the project README's
-`#media-configuration` section and in `docs/deploying-to-aws.md`. Read both at the ref this
+the bucket and serves `/assets/*` from S3 only: an unmaterialized URL is a 403, and
+`lazyPublicTransforms: true` transforms misses in a Lambda instead. Fuller documentation — every
+config option, the release steps and their IAM grants, and the AWS wiring — is in the project
+README's `#media-configuration` section, `docs/deploying-to-aws.md` and
+`docs/adopter-migration.md`. Read them at the ref this
 build came from, not at `main` — see
 [Which documentation matches this build](#which-documentation-matches-this-build).

package/dist/ai/handler.js

@@ -13,6 +13,7 @@
 import { ContentStore } from '../content-store.js';
 import { BranchSchemaCache } from '../branch-schema-cache.js';
 import { getErrorMessage } from '../utils/error.js';
+import { workerNotReadyResponse } from '../http/worker-not-ready.js';
 import { generateAIContent } from './generate.js';
 import { resolveBranchRoot } from './resolve-branch.js';
 /**
@@ -76,6 +77,13 @@ export function createAIContentHandler(options) {
         catch (error) {
             // Log the real error server-side; don't leak internals to unauthenticated callers
             console.error('AI content handler error:', getErrorMessage(error));
+            const notReady = workerNotReadyResponse(error);
+            if (notReady) {
+                return new Response(JSON.stringify({ error: notReady.body.error }), {
+                    status: notReady.status,
+                    headers: { 'Content-Type': 'application/json', ...notReady.headers },
+                });
+            }
             return new Response(JSON.stringify({ error: 'Internal server error' }), {
                 status: 500,
                 headers: { 'Content-Type': 'application/json' },

package/dist/api/admin-branch-health.js

@@ -17,19 +17,18 @@ import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../bran
 // Same constants the reader uses, rather than a second copy of the two string
 // literals.
 import { BRANCH_META_DIR, BRANCH_META_FILE } from '../branch-metadata-file.js';
-import { scanBranchHealth } from '../branch-health.js';
+import { ORPHAN_YOUTH_THRESHOLD_MS, scanBranchHealth, } from '../branch-health.js';
+import { formatDirStamp } from '../branch-provisioning.js';
 import { ContentIdIndex } from '../content-id-index.js';
 import { invalidateContentIndexesDurable } from '../content-index-generation.js';
 import { getDefaultBranchBase, sanitizeBranchName } from '../paths/index.js';
 import { withOccFileLock } from '../utils/occ-json-write.js';
-import { tryAcquireProvisioningLock } from '../utils/provisioning-lock.js';
+import { branchProvisioningLockName, tryAcquireProvisioningLock } from '../utils/provisioning-lock.js';
 import { withContentWriteLock, ContentWriteLockBusyError, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, } from '../utils/content-write-lock.js';
 import { getErrorMessage, isNodeError, isNotFoundError } from '../utils/error.js';
 import { defineEndpoint } from './route-builder.js';
 /** [H1] A fresh (< 5 min old) init lock blocks purge -- provisioning may be running. */
 const PROVISIONING_LOCK_FRESH_MS = 5 * 60_000;
-/** An orphan dir younger than this may still be a clone in progress; corrupt dirs are exempt. */
-const ORPHAN_YOUTH_THRESHOLD_MS = 15 * 60_000;
 // Mirrors deleteTaskHandler's fileName pattern in admin.ts: conservative
 // charset plus explicit traversal/dot-prefix refinements (the regex alone
 // technically excludes '/' already, but the refinements keep intent explicit
@@ -40,13 +39,6 @@ const dirNameSchema = z
     .refine((v) => !v.includes('..'), { message: 'dirName must not contain ..' })
     .refine((v) => !v.startsWith('.'), { message: 'dirName must not be dot-prefixed' });
 const branchDirParamsSchema = z.object({ dirName: dirNameSchema });
-/** Compact UTC stamp for trash/archive names: `YYYYMMDDTHHMMSSZ` (no colons -- portability). */
-function formatTrashStamp(date) {
-    return date
-        .toISOString()
-        .replace(/[-:]/g, '')
-        .replace(/\.\d{3}Z$/, 'Z');
-}
 /**
  * Re-resolve dirName under baseRoot and enforce containment (belt-and-
  * suspenders on top of the zod regex, matching deleteTaskHandler's pattern
@@ -147,12 +139,17 @@ const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
     // True orphan (no branch.json, no load error) vs. corrupt-metadata
     // (loadOnly threw). Only true orphans are subject to the youth rail below.
     const isTrueOrphan = !hadLoadError;
-    // [H1] freshness rail: a fresh init lock means provisioning may genuinely
-    // be in progress; a stale one is just crash debris and does not block.
-    const lockPath = path.join(baseRoot, `.${params.dirName}.init.lock`);
+    // [H1] freshness rail: a fresh init lock means provisioning, or the worker's
+    // sync of this branch, may genuinely be in progress; a stale one is just
+    // crash debris and does not block.
+    const lockPath = path.join(baseRoot, branchProvisioningLockName(params.dirName));
     const lockStat = await fs.stat(lockPath).catch(() => null);
     if (lockStat && Date.now() - lockStat.mtimeMs < PROVISIONING_LOCK_FRESH_MS) {
-        return { ok: false, status: 409, error: 'Provisioning may be in progress' };
+        return {
+            ok: false,
+            status: 409,
+            error: 'Provisioning, or the worker syncing this branch, may be in progress',
+        };
     }
     // Youth rail: a brand-new orphan dir may be a clone that just hasn't
     // written branch.json yet. Corrupt-metadata dirs are exempt -- a
@@ -171,7 +168,7 @@ const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
     // contention instead of hanging the request for ~5 minutes.
     let releaseProvisioningLock;
     try {
-        releaseProvisioningLock = await tryAcquireProvisioningLock(baseRoot, `.${params.dirName}.init.lock`);
+        releaseProvisioningLock = await tryAcquireProvisioningLock(baseRoot, branchProvisioningLockName(params.dirName));
     }
     catch (err) {
         if (isNodeError(err) && err.code === 'ELOCKED') {
@@ -197,7 +194,7 @@ const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
             // [C1] The timestamp lives in the NAME, not the dir's mtime: rename()
             // preserves the original mtime, so mtime-based retention would delete
             // a months-stale orphan's trash on the very first cleanup pass.
-            const trashName = `.trash-${params.dirName}-${formatTrashStamp(new Date())}`;
+            const trashName = `.trash-${params.dirName}-${formatDirStamp(new Date())}`;
             const trashPath = path.join(baseRoot, trashName);
             try {
                 await fs.rename(dirPath, trashPath);
@@ -279,7 +276,7 @@ const repairBranchDirHandler = async (_gc, ctx, req, params) => {
     // Held until the `finally` below, AFTER save() completes.
     let releaseProvisioningLock;
     try {
-        releaseProvisioningLock = await tryAcquireProvisioningLock(baseRoot, `.${params.dirName}.init.lock`);
+        releaseProvisioningLock = await tryAcquireProvisioningLock(baseRoot, branchProvisioningLockName(params.dirName));
     }
     catch (err) {
         if (isNodeError(err) && err.code === 'ELOCKED') {
@@ -301,7 +298,7 @@ const repairBranchDirHandler = async (_gc, ctx, req, params) => {
                 if (recheck === 'missing') {
                     throw new RepairPreconditionError('No metadata file -- use purge for orphans', 409);
                 }
-                const archivedName = `${BRANCH_META_FILE}.corrupt-${formatTrashStamp(new Date())}`;
+                const archivedName = `${BRANCH_META_FILE}.corrupt-${formatDirStamp(new Date())}`;
                 await fs.rename(branchJsonPath, path.join(dirPath, BRANCH_META_DIR, archivedName));
                 return archivedName;
             });
@@ -444,7 +441,7 @@ const repairContentDuplicatesHandler = async (_gc, ctx, _req, params) => {
             if (duplicates.length === 0) {
                 return { ok: false, status: 409, error: 'No duplicate content IDs found' };
             }
-            const stamp = formatTrashStamp(new Date());
+            const stamp = formatDirStamp(new Date());
             try {
                 for (const dup of duplicates) {
                     const archivedAs = [];

package/dist/api/admin.d.ts

@@ -8,7 +8,7 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
 import type { Task, QueueStats, CorruptTaskFile } from '../task-queue/cms-task-queue.js';
-import type { WorkerStatusReport } from '../types.js';
+import type { BuildIdentity, WorkerStatusReport } from '../types.js';
 import type { OperatingMode } from '../operating-mode/index.js';
 export type { BranchHealthResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse, } from './admin-branch-health.js';
 type WorkerLivenessState = 'alive' | 'stale' | 'absent';
@@ -31,6 +31,27 @@ export interface AdminStatusData {
     worker: WorkerLiveness;
     workerStatus: WorkerStatusReport | null;
     statusReadError?: string;
+    /**
+     * Why this process cannot provision the settings workspace (groups and path rules), when it
+     * cannot. Its requests that resolve a user answer 503 meanwhile; bootstrap admins still reach
+     * /admin.
+     */
+    settingsWorkspaceError?: string;
+    /** Build of the API process answering this request. */
+    build: BuildIdentity;
+    /** Whether `media` is configured; without it every upload returns 501. */
+    assetStore: {
+        configured: boolean;
+    };
+    /**
+     * Whether THIS API process can load sharp. When false, any editor image not yet stored (a new
+     * crop, thumbnail or preview size, transformed on demand here) fails, and raster uploads are
+     * accepted without decode validation. Speaks only for the process that answers the request.
+     */
+    imageProcessing: {
+        available: boolean;
+        error?: string;
+    };
 }
 /** Response type for GET /admin/status */
 export type AdminStatusResponse = ApiResponse<AdminStatusData>;
@@ -54,10 +75,10 @@ declare const listAdminTasksParamsSchema: z.ZodObject<{
     status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
     limit: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+    status: "failed" | "corrupt" | "pending" | "processing" | "completed";
     limit?: number | undefined;
 }, {
-    status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+    status: "failed" | "corrupt" | "pending" | "processing" | "completed";
     limit?: number | undefined;
 }>;
 export type ListAdminTasksParams = z.infer<typeof listAdminTasksParamsSchema>;
@@ -65,10 +86,10 @@ declare const deleteTaskParamsSchema: z.ZodObject<{
     status: z.ZodEnum<["pending", "failed", "corrupt"]>;
     fileName: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
-    status: "pending" | "failed" | "corrupt";
+    status: "failed" | "corrupt" | "pending";
     fileName: string;
 }, {
-    status: "pending" | "failed" | "corrupt";
+    status: "failed" | "corrupt" | "pending";
     fileName: string;
 }>;
 export type DeleteTaskParams = z.infer<typeof deleteTaskParamsSchema>;
@@ -108,10 +129,10 @@ export declare const ADMIN_ROUTES: {
         status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
         limit: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+        status: "failed" | "corrupt" | "pending" | "processing" | "completed";
         limit?: number | undefined;
     }, {
-        status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+        status: "failed" | "corrupt" | "pending" | "processing" | "completed";
         limit?: number | undefined;
     }>, undefined, AdminTasksResponse>;
     readonly retryTask: import("./route-builder.js").RouteDefinition<z.ZodObject<{
@@ -125,10 +146,10 @@ export declare const ADMIN_ROUTES: {
         status: z.ZodEnum<["pending", "failed", "corrupt"]>;
         fileName: z.ZodEffects<z.ZodString, string, string>;
     }, "strip", z.ZodTypeAny, {
-        status: "pending" | "failed" | "corrupt";
+        status: "failed" | "corrupt" | "pending";
         fileName: string;
     }, {
-        status: "pending" | "failed" | "corrupt";
+        status: "failed" | "corrupt" | "pending";
         fileName: string;
     }>, undefined, AdminDeleteTaskResponse>;
 };

package/dist/api/admin.js

@@ -12,7 +12,9 @@ import { getQueueStats, listTasks, listCorruptTaskFiles, requeueFailedTask, } fr
 import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
 import { WORKER_STATUS_FILE } from '../task-queue/worker-status.js';
 import { defineEndpoint } from './route-builder.js';
-import { getErrorMessage, isNotFoundError } from '../utils/error.js';
+import { getErrorMessage, isNotFoundError, redactCredentials } from '../utils/error.js';
+import { getBuildIdentity } from '../build-identity.js';
+import { loadSharp } from '../assets/sharp-loader.js';
 import { ADMIN_BRANCH_HEALTH_ROUTES } from './admin-branch-health.js';
 /**
  * 60_000 = DEFAULT_LOCK_STALE_MS in worker/cms-worker.ts, hardcoded rather
@@ -72,6 +74,15 @@ async function readWorkerStatus(taskDir) {
         return { workerStatus: null, statusReadError: getErrorMessage(err) };
     }
 }
+async function readSettingsWorkspaceError(ctx) {
+    try {
+        await ctx.services.getSettingsBranchRoot();
+        return undefined;
+    }
+    catch (err) {
+        return redactCredentials(getErrorMessage(err));
+    }
+}
 /** Age (ms) of the oldest file in pending/, or undefined if empty/missing. */
 async function getOldestPendingAgeMs(taskDir) {
     const pendingDir = path.join(taskDir, 'pending');
@@ -123,14 +134,26 @@ const deleteTaskParamsSchema = z.object({
         .regex(/^[A-Za-z0-9._-]{1,120}\.json$/)
         .refine((v) => !v.includes('..'), { message: 'fileName must not contain ..' }),
 });
+/** Loads sharp in this process; a failure is reported, never thrown. */
+async function probeImageProcessing() {
+    try {
+        await loadSharp();
+        return { available: true };
+    }
+    catch (err) {
+        return { available: false, error: getErrorMessage(err) };
+    }
+}
 const getAdminStatusHandler = async (_gc, ctx, _req) => {
     const taskDir = getTaskQueueDir(ctx.services.config);
     try {
-        const [queueStats, oldestPendingAgeMs, worker, { workerStatus, statusReadError }] = await Promise.all([
+        const [queueStats, oldestPendingAgeMs, worker, { workerStatus, statusReadError }, settingsWorkspaceError, imageProcessing,] = await Promise.all([
             getQueueStats(taskDir),
             getOldestPendingAgeMs(taskDir),
             classifyWorkerLiveness(taskDir),
             readWorkerStatus(taskDir),
+            readSettingsWorkspaceError(ctx),
+            probeImageProcessing(),
         ]);
         return {
             ok: true,
@@ -145,6 +168,10 @@ const getAdminStatusHandler = async (_gc, ctx, _req) => {
                 worker,
                 workerStatus,
                 ...(statusReadError ? { statusReadError } : {}),
+                ...(settingsWorkspaceError ? { settingsWorkspaceError } : {}),
+                build: getBuildIdentity(),
+                assetStore: { configured: !!ctx.assetStore },
+                imageProcessing,
             },
         };
     }
@@ -255,6 +282,9 @@ const getAdminStatus = defineEndpoint({
         queue: { pending: 0, processing: 0, completed: 0, failed: 0, corrupt: 0 },
         worker: { state: 'absent' },
         workerStatus: null,
+        build: { canopycmsVersion: '0.0.0' },
+        assetStore: { configured: false },
+        imageProcessing: { available: true },
     },
     guards: ['admin'],
     handler: getAdminStatusHandler,

package/dist/api/assets.js

@@ -4,8 +4,8 @@ import { ASSET_PREFIXES } from '../assets/keys.js';
 import { ALLOWED_UPLOAD_CONTENT_TYPES } from '../assets/pipeline.js';
 import { finalizeStagedUpload } from '../assets/finalize.js';
 import { assetSrc } from '../assets/asset-src.js';
-import { formatDirectives, parseTransformPath } from '../assets/transform-directives.js';
-import { applyTransform } from '../assets/transform.js';
+import { canonicalizeTransformPath } from '../assets/transform-directives.js';
+import { storeTransform, TRANSFORM_CACHE_CONTROL } from '../assets/materialize.js';
 import { isAdmin } from '../authorization/helpers.js';
 function toAssetRecord(meta) {
     return { ...meta, src: assetSrc(meta) };
@@ -212,63 +212,41 @@ const deleteAssetHandler = async (ctx, req, params) => {
     await ctx.assetStore.deleteMeta(params.key);
     return { ok: true, status: 200, data: { deleted: true } };
 };
-/** Cache-Control applied to every transform output this route writes/serves - matches finalize.ts's PUBLIC_CACHE_CONTROL for static public objects. */
-const TRANSFORM_CACHE_CONTROL = 'public, max-age=31536000, immutable';
 /**
- * Lazy dev-mode emulation of the prod transform Lambda (reuses `parseTransformPath`/
- * `formatDirectives`/`applyTransform` unchanged): parse, load the original, transform, write the
- * result back under its CANONICAL key (so a non-canonically-ordered directive string still
- * dedupes with any equivalent request), then serve the bytes just computed.
- *
- * `key` here already starts with `assets/t/` and already missed `rawAssetHandler`'s cache-hit
- * `readPublicObject` check.
+ * The largest body this route returns inline. The CMS Lambda's Function URL buffers its response
+ * and caps it at 6 MiB after base64 encoding, which inflates by 4/3, so 4 MiB leaves headroom.
+ * Same bound and reasoning as the transform Lambda's `INLINE_BODY_LIMIT_BYTES`.
  */
-async function serveLazyTransform(assetStore, key) {
-    const rest = key.slice(ASSET_PREFIXES.transform.length + 1);
-    const parsed = parseTransformPath(rest.split('/'));
-    if (!parsed.ok) {
-        return { ok: false, status: 400, error: parsed.error };
-    }
-    const meta = await assetStore.getMeta(parsed.hash32);
-    if (!meta) {
-        return { ok: false, status: 404, error: 'Not found' };
-    }
-    if (meta.kind !== 'raster') {
-        return { ok: false, status: 400, error: 'Not a raster asset - svg/pdf are served statically' };
-    }
-    // The slug is decorative in the URL but load-bearing in the stored key, so it must equal the
-    // asset's real slug — the parser only enforces `[a-z0-9-]+`, and any other string that passes
-    // it aliases the same image into a new cache key. Mirrors the prod transform Lambda's check
-    // (assets/asset-url.ts); the two paths must agree, or dev accepts URLs prod 404s.
-    if (parsed.slug !== meta.slug) {
-        return { ok: false, status: 404, error: 'Not found' };
-    }
-    // When the URL omits an explicit `f=` format, the transform preserves the
-    // source format, so the URL's `{ext}` must match the source's real ext
-    // exactly - the parser alone can't check this (it doesn't know the source
-    // format until this meta lookup).
-    const requestedFormat = parsed.directives.identity ? undefined : parsed.directives.format;
-    if (requestedFormat === undefined && parsed.ext !== meta.ext) {
-        return { ok: false, status: 400, error: 'Extension does not match the source format' };
-    }
-    const original = await assetStore.readOriginal(parsed.hash32);
-    if (!original) {
-        return { ok: false, status: 404, error: 'Not found' };
-    }
-    const transformed = await applyTransform({ data: original.data, ext: original.ext }, parsed.directives);
+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.
+ */
+function presignedRedirect(url) {
+    return {
+        kind: 'binary',
+        status: 302,
+        body: new Uint8Array(),
+        headers: { location: url, cacheControl: 'no-store' },
+    };
+}
+/**
+ * This route's own lazy transform: `storeTransform` computes and stores the output, then this
+ * serves the bytes just computed. `parsed` is the canonical parse from `canonicalizeTransformPath`,
+ * and `canonicalKey` already missed `rawAssetHandler`'s cache check.
+ */
+async function serveLazyTransform(assetStore, parsed, canonicalKey) {
+    const transformed = await storeTransform(assetStore, parsed, canonicalKey);
     if (!transformed.ok) {
-        // Pass the real status through instead of flattening every rejection to 502:
-        // `applyTransform` already distinguishes client-input errors (400/413) from a genuine decode
-        // failure (422), none of which are "this server failed." Mirrors the prod transform Lambda.
-        return { ok: false, status: transformed.status, error: transformed.error };
+        // The real status, not a flat 502: none of these rejections is "this server failed".
+        const error = transformed.status === 404 ? 'Not found' : transformed.error;
+        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 canonicalKey = `${ASSET_PREFIXES.transform}/${formatDirectives(parsed.directives)}/${parsed.hash32}/${parsed.slug}.${parsed.ext}`;
-    await assetStore.putPublicObject({
-        key: canonicalKey,
-        data: transformed.data,
-        contentType: transformed.contentType,
-        cacheControl: TRANSFORM_CACHE_CONTROL,
-    });
     return {
         kind: 'binary',
         status: 200,
@@ -276,16 +254,47 @@ async function serveLazyTransform(assetStore, key) {
         headers: { contentType: transformed.contentType, cacheControl: TRANSFORM_CACHE_CONTROL },
     };
 }
+/** 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 object = await assetStore.readPublicObject(key);
+    if (!object)
+        return null;
+    return {
+        kind: 'binary',
+        status: 200,
+        body: object.data,
+        headers: {
+            contentType: object.contentType,
+            contentDisposition: object.contentDisposition,
+            cacheControl: object.cacheControl,
+        },
+    };
+}
 /**
  * Serve a public asset object (sanitized svg/pdf finalize wrote, or a cached transform output)
- * for dev-mode `/assets/*` rewrites. Hand-built (not `defineEndpoint`), not registered in
- * `ASSET_ROUTES`/the client generator: this returns raw bytes (`CanopyBinaryResponse`), not a
- * JSON envelope, so a generated `response.json()` client method would be wrong. Consumers hit
- * this route directly (`<img>`/`<a>` src, or a framework rewrite), never through `client.ts`.
+ * to the editor, the live preview, and `withCanopy`'s `/assets/*` rewrite. Hand-built (not
+ * `defineEndpoint`), not registered in `ASSET_ROUTES`/the client generator: this returns raw bytes
+ * (`CanopyBinaryResponse`), not a JSON envelope, so a generated `response.json()` client method
+ * would be wrong. Consumers hit this route directly (`<img>`/`<a>` src, or a framework rewrite),
+ * never through `client.ts`.
  *
- * Transform outputs (`assets/t/...`) are cache-checked like any other public object first — only
- * a MISS under `assets/t/` falls through to `serveLazyTransform`. Mirrors prod (CloudFront
- * origin-group -> S3 -> Lambda on miss).
+ * A transform key (`assets/t/...`) is resolved to its canonical key first, and that key is what is
+ * cache-checked and, on a miss, computed by `serveLazyTransform`. Mirrors `AssetSupport`'s lazy
+ * mode (CloudFront origin-group -> S3 -> Lambda on miss), except that a non-canonical spelling is
+ * served the canonical bytes rather than the Lambda's 301: this route is authenticated, and
+ * redirecting to `/assets/t/...` would bounce the request onto the public path.
+ *
+ * A stored object on a store that can presign (S3) is answered with a 302 to a presigned GET, so
+ * its bytes never pass through this process: the CMS Lambda is concurrency-capped and uncached,
+ * the live preview asks for every image on a page at once, and its Function URL cannot return a
+ * body over about 6 MiB. The redirect never targets the public `/assets/...` URL, because whether
+ * that URL reaches this route again is topology: `withCanopy` rewrites `/assets/:path*` here, so
+ * on any deployment where Next serves `/assets` the redirect would loop. Other stores stream the
+ * bytes, as does a fresh transform no larger than `INLINE_BODY_LIMIT_BYTES`.
  */
 const rawAssetHandler = async (ctx, _req, params) => {
     if (!ctx.assetStore)
@@ -300,23 +309,22 @@ const rawAssetHandler = async (ctx, _req, params) => {
     if (!key.startsWith(publicPrefix) || key.includes('..')) {
         return { ok: false, status: 404, error: 'Not found' };
     }
-    const object = await ctx.assetStore.readPublicObject(key);
-    if (object) {
-        return {
-            kind: 'binary',
-            status: 200,
-            body: object.data,
-            headers: {
-                contentType: object.contentType,
-                contentDisposition: object.contentDisposition,
-                cacheControl: object.cacheControl,
-            },
-        };
+    let readKey = key;
+    let transform;
+    if (key.startsWith(transformPrefix)) {
+        const canonical = canonicalizeTransformPath(key.slice(transformPrefix.length).split('/'), 'any');
+        if (!canonical.ok)
+            return { ok: false, status: 400, error: canonical.error };
+        readKey = `${transformPrefix}${canonical.canonicalPath}`;
+        transform = canonical;
     }
-    if (!key.startsWith(transformPrefix)) {
+    const stored = await serveStoredObject(ctx.assetStore, readKey);
+    if (stored)
+        return stored;
+    if (!transform) {
         return { ok: false, status: 404, error: 'Not found' };
     }
-    return serveLazyTransform(ctx.assetStore, key);
+    return serveLazyTransform(ctx.assetStore, transform, readKey);
 };
 // Deliberately no 'writableBranch' guard on any endpoint below: none take a
 // :branch param -- the asset store is branch-agnostic (a single global store,

package/dist/api/branch-create-window.d.ts

@@ -0,0 +1,12 @@
+/**
+ * How long a create of a branch name its own creator just made answers with that branch rather
+ * than a 409, so a request killed between publishing the branch and responding is safe to retry.
+ * Dependency-free: the editor applies the same rule when it settles an unanswered create.
+ * @internal Exported for tests.
+ */
+export declare const IDEMPOTENT_CREATE_WINDOW_MS: number;
+/** Whether `branch` can be the result of `userId`'s create: theirs, and inside the window. */
+export declare function isCreatorsRecentBranch(branch: {
+    createdBy: string;
+    createdAt: string;
+}, userId: string | undefined): boolean;

package/dist/api/branch-create-window.js

@@ -0,0 +1,13 @@
+/**
+ * How long a create of a branch name its own creator just made answers with that branch rather
+ * than a 409, so a request killed between publishing the branch and responding is safe to retry.
+ * Dependency-free: the editor applies the same rule when it settles an unanswered create.
+ * @internal Exported for tests.
+ */
+export const IDEMPOTENT_CREATE_WINDOW_MS = 5 * 60_000;
+/** Whether `branch` can be the result of `userId`'s create: theirs, and inside the window. */
+export function isCreatorsRecentBranch(branch, userId) {
+    return (userId !== undefined &&
+        branch.createdBy === userId &&
+        Date.now() - Date.parse(branch.createdAt) < IDEMPOTENT_CREATE_WINDOW_MS);
+}