caracms 0.3.4 → 0.5.0

package/src/editor/styles/levels/arrange.css

@@ -0,0 +1,152 @@
+/*
+  Arrange pages (notes/2026-10-25-arrange-pages.md; the mockup's notes/mockups/arrange-pages.html, as drawn).
+  The screen takes the preview's place as a light sheet over the stage, the way a collection's table does
+  (collections.css → .stage-table); the pane holds its level ("Arrange pages", then "Review").
+  Rows are the Pages tree's rows grown wide: a grip, the name at its depth (16px steps), the address, the row's end.
+  Marks are washes, full rings, chips and labels. No side rails anywhere (M2 Decision 10).
+*/
+:root{
+  --arr-max-w:940px;     /* the tree's width on the stage: names and addresses side by side, left-aligned under its head */
+  --arr-row-h:32px;      /* a row: a touch taller than the sidebar's 30px, a bigger target to drag and drop on */
+  --arr-grip-w:24px;     /* the grip's column; a row's icon starts after it, then one --tree-indent per depth */
+  --arr-addr-w:300px;    /* the address column, at its widest */
+  --arr-addr-min:140px;  /* the address column at its narrowest (the editor's 1,024px floor), where it gives way to the name first */
+  --arr-name-min:200px;  /* the name column's narrowest: an icon, a name cut short, and a mark or two */
+  --arr-end-w:184px;     /* a row's end: its actions (Rename…, Remove), the inside tag, the twisty */
+  --arr-mark:2px;        /* the beside line's weight; the inside ring is the same 2px, all the way round */
+  --arr-ghost-w:300px;   /* the dragged card's widest */
+}
+.stage.is-arrange .frame{visibility:hidden}
+.arr{position:absolute;inset:0;z-index:3;display:flex;flex-direction:column;min-height:0;background:var(--surface);color:var(--text);animation:fade-in var(--dur-base) var(--ease-out)}
+.arr-head{flex:none;padding:var(--space-4) var(--space-6) var(--space-3);border-bottom:1px solid var(--border)}
+.arr-head-in{max-width:var(--arr-max-w);display:grid;grid-template-columns:minmax(0,1fr) auto;align-items:center;gap:var(--space-2) var(--space-3)}
+.arr-title{display:flex;align-items:baseline;gap:var(--space-2);min-width:0}
+.arr-title h2{margin:0;font-size:var(--text-xl);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);white-space:nowrap}
+.arr-title .n-chip{font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--text-subtle);white-space:nowrap}
+.arr-hint{grid-column:1 / -1;display:flex;flex-wrap:wrap;align-items:center;gap:var(--space-1-5) var(--space-5);font-size:var(--text-sm);color:var(--text-muted)}
+.arr-ro{display:inline-flex;align-items:center;gap:var(--space-1-5);font-size:var(--text-sm);color:var(--text-muted)}
+/* The two markers' key, drawn as the markers themselves */
+.key{display:inline-flex;align-items:center;gap:var(--space-2);white-space:nowrap}
+.key-line{position:relative;width:26px;height:var(--arr-mark);border-radius:2px;background:var(--select)}
+.key-line::before{content:"";position:absolute;left:-3px;top:50%;width:6px;height:6px;translate:0 -50%;border:2px solid var(--select);border-radius:50%;background:var(--surface)}
+.key-ring{width:26px;height:14px;border-radius:var(--radius-sm);background:var(--select-wash);box-shadow:0 0 0 var(--arr-mark) var(--select)}
+.arr-scroll{flex:1;min-height:0;overflow:auto;overscroll-behavior:contain;padding:0 var(--space-6) var(--space-10);scrollbar-width:thin;scrollbar-color:var(--border-hover) transparent}
+.arr-cols{position:sticky;top:0;z-index:2;max-width:var(--arr-max-w);display:grid;grid-template-columns:var(--arr-grip-w) minmax(var(--arr-name-min),1fr) minmax(var(--arr-addr-min),var(--arr-addr-w)) var(--arr-end-w);align-items:center;height:34px;margin-bottom:var(--space-1);background:var(--surface);border-bottom:1px solid var(--border);font-size:var(--text-xs);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-caps);text-transform:uppercase;color:var(--text-subtle)}
+.arr-tree{position:relative;max-width:var(--arr-max-w)}
+/* A row */
+.arow{position:relative;display:grid;grid-template-columns:var(--arr-grip-w) minmax(var(--arr-name-min),1fr) minmax(var(--arr-addr-min),var(--arr-addr-w)) var(--arr-end-w);align-items:center;min-height:var(--arr-row-h);border:1px solid transparent;border-radius:var(--radius-md);transition:background var(--dur-fast),border-color var(--dur-fast),box-shadow var(--dur-fast)}
+.arow:hover{background:var(--surface-hover)}
+.arow[data-drag]{cursor:grab}
+.ag{display:grid;place-items:center;align-self:stretch;color:var(--icon)}
+.arow[data-drag]:hover .ag{color:var(--text)}
+.an{display:flex;align-items:center;gap:var(--space-2);min-width:0;overflow:hidden;padding-left:calc(var(--depth,0) * var(--tree-indent));padding-right:var(--space-2)}
+.an>.i{flex:none;color:var(--icon)}
+.an .nm{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.an .meta{display:inline-flex;flex:0 1 auto;align-items:center;gap:var(--space-1-5);min-width:0;overflow:hidden;font-size:var(--text-xs);color:var(--text-subtle);white-space:nowrap}
+.an .meta .chip{flex:none;height:18px;font-size:var(--text-2xs)}
+.an .meta>:not(.chip){min-width:0;overflow:hidden;text-overflow:ellipsis}
+.an .cnt{font-variant-numeric:tabular-nums}
+.aa{min-width:0;padding-right:var(--space-2);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:var(--text-xs)/1.3 var(--font-mono);color:var(--text-muted)}
+.aa .new{color:var(--select-strong);font-weight:var(--weight-medium)}
+.aa .was{margin-left:var(--space-2);color:var(--text-subtle);font-family:var(--font-ui)}
+.aa .was .mono{font-family:var(--font-mono)}
+.ae{display:flex;align-items:center;justify-content:flex-end;gap:var(--space-1);min-width:0;padding-right:var(--space-1)}
+.ae .act{opacity:0;transition:opacity var(--dur-fast)}
+.arow:hover .ae .act,.arow:focus-within .ae .act{opacity:1}
+.ae .carried{font-size:var(--text-xs);color:var(--text-subtle);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.atw{display:grid;place-items:center;width:calc(var(--tree-twisty) + 6px);height:calc(var(--tree-twisty) + 6px);flex:none;padding:0;border:0;border-radius:var(--radius-sm);background:none;color:var(--icon);transition:background var(--dur-fast),color var(--dur-fast)}
+.atw:hover{background:var(--surface-pressed);color:var(--text)}
+.atw .i{transition:rotate var(--dur-fast) var(--ease-out)}
+.atw[aria-expanded="true"] .i{rotate:90deg}
+.atw-gap{width:calc(var(--tree-twisty) + 6px);flex:none}
+/* Home: fixed, first, takes nothing */
+.arow.is-home .an .nm{font-weight:var(--weight-medium)}
+/* A held collection's row: moves with its page; nothing drags it, nothing drops on it */
+.arow.is-held{color:var(--text-muted)}
+.arow.is-held:hover{background:none}
+/* Marks for what's changed here and not applied yet: the tool's blue in a chip, and the new address in blue */
+.arow.is-gone .an .nm,.arow.is-gone .an>.i{color:var(--text-subtle)}
+.arow.is-gone .aa{color:var(--text-subtle);font-family:var(--font-ui)}
+/* A new group with nothing in it: a full dashed ring (an empty slot, like .empty and .add-row), and its line under it */
+.arow.is-empty{border:1px dashed var(--border-strong)}
+.arow-sub{display:flex;align-items:center;flex-wrap:wrap;gap:var(--space-1-5) var(--space-2);min-height:24px;margin:0 0 var(--space-1);padding-left:calc(var(--arr-grip-w) + var(--depth,0) * var(--tree-indent) + 24px);font-size:var(--text-sm);color:var(--text-muted)}
+.arow-sub.err{color:var(--status-danger);font-weight:var(--weight-medium)}
+.arow-sub .i{flex:none}
+/* Naming a new group, or renaming one, in its row */
+.arow.is-naming{background:var(--surface-sunken);border-color:var(--border)}
+.arow.is-naming:hover{background:var(--surface-sunken)}
+.arow.is-naming .an .input{width:min(260px,100%);min-height:26px;height:26px;padding:2px 8px;font-size:var(--text-base)}
+.arow.is-naming .ae .btn{flex:none}
+/* Linked from the review: hovering an entry there washes its row here */
+.arow.is-linked{background:var(--select-wash)}
+/* Dragging. The row being dragged keeps its place as a dashed outline (the block list's ghost, .brow.is-ghost); what's under it goes with it. */
+.arow.is-src{background:none;border:1px dashed var(--border-strong)}
+.arow.is-src>*{visibility:hidden}
+/* Inside: the row it goes into gets the selection's wash and a full 2px ring, and says so at its end */
+.arow.is-into,.arow.is-into:hover{background:var(--select-wash);border-color:var(--select);box-shadow:0 0 0 1px var(--select)}
+.arow.is-into .an .nm{color:var(--select-strong);font-weight:var(--weight-semibold)}
+.arow.is-into .an>.i{color:var(--select-strong)}
+.tag{display:inline-flex;align-items:center;gap:var(--space-1);height:20px;padding:0 var(--space-2);border-radius:var(--radius-pill);background:var(--select);color:var(--on-fill);font-size:var(--text-xs);font-weight:var(--weight-semibold);white-space:nowrap}
+/* Refused: a danger wash and a full thin ring, and the reason in one line across the address and the end */
+.arow.is-refused,.arow.is-refused:hover{background:var(--status-danger-wash);border-color:var(--status-danger-border)}
+.arow-why{grid-column:3 / 5;display:flex;align-items:center;gap:var(--space-1-5);min-width:0;padding-right:var(--space-2);font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--status-danger);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+/* Beside: a 2px line between two rows, starting where that level's icons start (so its indent says which level), a ring at its
+   start, and the level it lands in at its end. The line is a marker across the row, never a bar down a card's side. */
+.amark{position:absolute;right:0;z-index:4;height:var(--arr-mark);border-radius:2px;background:var(--select);box-shadow:0 0 0 2px var(--surface);pointer-events:none}
+.amark::before{content:"";position:absolute;left:-4px;top:50%;width:8px;height:8px;translate:0 -50%;border:2px solid var(--select);border-radius:50%;background:var(--surface)}
+.amark .tag{position:absolute;right:var(--space-1);top:50%;translate:0 -50%;box-shadow:0 0 0 2px var(--surface)}
+/* The card under the pointer while dragging */
+.adrag{position:fixed;left:0;top:0;z-index:70;display:grid;grid-template-columns:16px minmax(0,1fr);align-items:center;gap:2px var(--space-2);min-width:220px;max-width:var(--arr-ghost-w);padding:var(--space-2) var(--space-3) var(--space-2) var(--space-2-5);background:var(--surface);border:1px solid var(--border-strong);border-radius:var(--radius-md);box-shadow:var(--shadow-drag);pointer-events:none;font-size:var(--text-base)}
+.adrag>.i{color:var(--icon)}
+.adrag .nm{display:flex;align-items:baseline;gap:var(--space-1-5);min-width:0;font-weight:var(--weight-semibold);white-space:nowrap;overflow:hidden}
+.adrag .nm small{font-size:var(--text-xs);font-weight:var(--weight-regular);color:var(--text-subtle);overflow:hidden;text-overflow:ellipsis}
+.adrag .to{grid-column:2;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:var(--text-xs)/1.35 var(--font-mono);color:var(--select-strong)}
+.adrag .to.plain{font-family:var(--font-ui);color:var(--text-muted)}
+.adrag.no{border-color:var(--status-danger-border)}
+.adrag.no .to{display:flex;align-items:center;gap:var(--space-1);font-family:var(--font-ui);font-weight:var(--weight-medium);color:var(--status-danger)}
+body.is-dragging,body.is-dragging *{cursor:grabbing!important;user-select:none}
+body.is-dragging.is-no,body.is-dragging.is-no *{cursor:not-allowed!important}
+
+/* The pane's levels: Arrange pages, then Review */
+.arr-none{font-size:var(--text-sm);color:var(--text-muted)}
+.chg{list-style:none;margin:0 calc(-1 * var(--space-1));padding:0;display:flex;flex-direction:column;gap:1px}
+.chg li{display:grid;grid-template-columns:16px minmax(0,1fr);gap:var(--space-2);padding:var(--space-1-5) var(--space-1);border-radius:var(--radius-md);font-size:var(--text-sm);color:var(--text-muted);line-height:1.4}
+.chg li .i{margin-top:1px;color:var(--icon)}
+.chg li b{color:var(--text);font-weight:var(--weight-semibold)}
+.chg li.is-muted b{color:var(--text-muted)}
+.arr-foot{flex:none;padding:var(--space-3) var(--space-4) var(--space-4);border-top:1px solid var(--border);background:var(--surface)}
+.arr-foot .why{display:grid;grid-template-columns:16px minmax(0,1fr);gap:var(--space-1-5);margin-bottom:var(--space-3);font-size:var(--text-sm);color:var(--text-muted)}
+.arr-foot .why .i{margin-top:1px;color:var(--icon)}
+.arr-foot .why b{color:var(--text);font-weight:var(--weight-semibold)}
+.arr-foot .busy{margin-bottom:var(--space-3);font-size:var(--text-sm);color:var(--status-waiting)}
+.arr-foot .acts{display:flex;justify-content:flex-end;gap:var(--space-2)}
+/* The review: what moves, where, and whether old links keep working */
+.rv-lead{margin-bottom:var(--space-4);font-size:var(--text-md);font-weight:var(--weight-semibold);line-height:1.35}
+.rv-lead small{display:block;margin-top:2px;font-size:var(--text-sm);font-weight:var(--weight-regular);color:var(--text-muted)}
+.rv{list-style:none;margin:0 calc(-1 * var(--space-1));padding:0;display:flex;flex-direction:column;gap:1px}
+.rv-e{display:grid;grid-template-columns:16px minmax(0,1fr);column-gap:var(--space-2);row-gap:1px;margin-left:calc(var(--in,0) * var(--tree-indent));padding:var(--space-1-5) var(--space-1);border-radius:var(--radius-md);transition:background var(--dur-fast)}
+.rv-e:hover{background:var(--surface-hover)}
+.rv-e>.i{margin-top:1px;color:var(--icon)}
+.rv-e .t{display:flex;align-items:center;flex-wrap:wrap;gap:var(--space-1) var(--space-1-5);min-width:0;font-weight:var(--weight-semibold);line-height:1.35}
+.rv-e .t .chip{height:18px;font-size:var(--text-2xs)}
+.rv-e.is-carried .t,.rv-e.is-held .t{font-weight:var(--weight-medium)}
+.rv-e.is-gone .t{font-weight:var(--weight-medium);color:var(--text-muted)}
+.rv-e.is-gone>.i{color:var(--text-subtle)}
+.mv{grid-column:2;display:flex;flex-wrap:wrap;column-gap:var(--space-1);min-width:0;font:var(--text-xs)/1.5 var(--font-mono);color:var(--text-subtle);overflow-wrap:anywhere}
+.mv .to{color:var(--text)}
+.rv-more{margin-left:auto;font-size:var(--text-xs)}
+.rv-more .i{transition:rotate var(--dur-fast) var(--ease-out)}
+.rv-more[aria-expanded="true"] .i{rotate:90deg}
+.rv-docs{grid-column:2;list-style:none;margin:var(--space-1-5) 0 0;padding:var(--space-1-5) var(--space-2);border:1px solid var(--border);border-radius:var(--radius-md);background:var(--surface-sunken);font:var(--text-xs)/1.6 var(--font-mono);color:var(--text-muted);overflow-wrap:anywhere}
+.rv-docs li.is-new{color:var(--status-warning-strong);font-weight:var(--weight-medium)}
+.rv-tick{margin-top:var(--space-4);padding-top:var(--space-4);border-top:1px solid var(--border)}
+.rv-tick .field-help{margin-bottom:0}
+/* Shared pieces the mockup draws outside a dialog or a level's own CSS: the tick, and the order-only panel's fixed line */
+.rv-tick .check{display:flex;align-items:center;gap:var(--space-2);font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--text);cursor:pointer}
+.rv-tick .check input{flex:none;width:16px;height:16px;margin:0;accent-color:var(--select);cursor:inherit}
+.rv-tick .check + .field-help{margin-top:var(--space-1);padding-left:calc(16px + var(--space-2))}
+.rv-tick .check:has(input:disabled){cursor:not-allowed;color:var(--text-muted)}
+.side-level[data-pane-level="arrange"] .sec-h .n{font-weight:var(--weight-medium);letter-spacing:0;color:var(--text-subtle)}
+.arow.is-naming .input[aria-invalid="true"]{border-color:var(--status-danger);box-shadow:0 0 0 3px var(--status-danger-halo)}
+.arr-foot .progress{margin:0 0 var(--space-2-5)}
+.mv .fr{margin-top:0}

package/src/editor/styles/levels/collections.css

@@ -37,6 +37,8 @@
 .ct-open:focus-visible{outline:2px solid var(--select);outline-offset:2px;border-radius:var(--radius-xs)}
 .ct-title-cell .meta{display:inline-flex;align-items:center;gap:var(--space-1);margin-left:var(--space-1-5)}
 .ct-title-cell .meta:empty{display:none}
+/* Hidden (M9 Decision 7; collections under pages, Decision 11): the sidebar row's mark, small and grey, not part of the title. */
+.ct-title-cell .hmark{font-size:var(--text-xs);font-weight:var(--weight-regular);color:var(--text-subtle);white-space:nowrap}
 .ct-extra{margin-left:var(--space-2);font-size:var(--text-xs);color:var(--text-subtle)}
 .ct tr.is-warned .ct-open{color:var(--text-muted)}
 .ct tr.is-current .ct-open{color:var(--select-strong);font-weight:var(--weight-semibold)}

package/src/editor/styles/levels/m5a-documents.css

@@ -11,6 +11,21 @@
 .ptype.sm .i{color:var(--icon)}
 .ptype[aria-checked="true"]{border-color:var(--select);background:var(--select-wash)}
 .ptype[aria-checked="true"] b,.ptype[aria-checked="true"] .i{color:var(--select-strong)}
+/* Collections under pages (Decision 9): Change address…'s list of every address that changes */
+.mv-list{list-style:none;margin:var(--space-2) 0 0;padding:var(--space-1) var(--space-2);max-height:11rem;overflow:auto;border:1px solid var(--border);border-radius:var(--radius-md);font-size:var(--text-sm);line-height:1.6}
+.mv-list li{overflow-wrap:anywhere}
+/* In a short window the dialog stays inside it, the list the part that gives (down to about
+   two addresses), so Cancel and Change address always show. A column, not a scrolling dialog:
+   the Inside picker's popover must not be clipped. The margins keep the block layout's gaps
+   (no margins collapse in a column). */
+.dialog[data-dialog="move"]{display:flex;flex-direction:column;max-height:calc(100dvh - 2 * var(--space-4))}
+.dialog[data-dialog="move"]>form{display:flex;flex-direction:column;min-height:0}
+.dialog[data-dialog="move"]>form>*{flex:none}
+.dialog[data-dialog="move"]>form>h2+.field{margin-top:var(--space-2)}
+.dialog[data-dialog="move"]>form>.field>:last-child{margin-bottom:0}
+.dialog[data-dialog="move"]>form>[data-moving]{flex:0 1 auto;display:flex;flex-direction:column;min-height:0}
+.dialog[data-dialog="move"]>form>[data-moving]>*{flex:none}
+.dialog[data-dialog="move"]>form>[data-moving]>.mv-list{flex:0 1 auto;min-height:3rem;margin-top:0}
 .dlg-list{display:flex;flex-direction:column;gap:2px;margin-top:var(--space-3);padding:var(--space-1);border:1px solid var(--border);border-radius:var(--radius-md)}
 /* Site Settings (M5a): a fixed form with no page of its own */
 .set-sec{margin:0 calc(-1 * var(--space-4));padding:var(--space-4) var(--space-4) var(--space-1);border-top:1px solid var(--border)}

package/src/editor/types.ts

@@ -54,6 +54,16 @@ export interface EditorAnyCollection {
 	sort?: import('../columns.ts').SortConfig | null;
 	/** A section builder's offered blocks (config.ts); null or absent for every block. */
 	blocks?: string[] | null;
+	/**
+	 * Collections under pages (Decision 7): the nested collection whose page holds this one, set
+	 * only on a held collection. Its `urlBase` is then the server's resolved base (the holder's
+	 * address + `/`), or null while `problem` says why it has none.
+	 */
+	heldBy?: string | null;
+	/** A held collection's holder (held.ts → HeldBase); null or absent when none holds it, and on any other collection. */
+	holder?: { collection: string; path: string } | null;
+	/** Decision 13's sentence for a held collection with no addresses (shown on its sidebar entry); null or absent otherwise. */
+	problem?: string | null;
 }
 
 /**
@@ -176,6 +186,11 @@ export interface AdminProps {
 	 * document's address. `opened` is then Home, the page under the inbox.
 	 */
 	inbox?: { id: string | null } | null;
+	/**
+	 * Arrange pages (Decision 15): the address opened the arrange screen (`/admin/arrange`),
+	 * with nothing arranged. `opened` is then Home, the page under it.
+	 */
+	arrange?: boolean;
 	/**
 	 * M6 Decision 9: the unread count for the Site-wide row, read as /admin renders; or,
 	 * when the production server has no submissions bucket, the sentence naming what's
@@ -271,6 +286,8 @@ export const ENDPOINTS = {
 	delete: '/_caracms/delete',
 	// Pre-M7 item 8: changing a document's address, both modes.
 	move: '/_caracms/move',
+	// Arrange pages (Contracts): the arrange screen's Apply, both modes.
+	arrange: '/_caracms/arrange',
 	// M5b Phase 2: the media routes, both modes (MEDIA_ENDPOINTS below has each one).
 	media: '/_caracms/media',
 	// M4 Phase 2 (live mode only; local mode answers 404).
@@ -486,14 +503,22 @@ export interface StatusResponse {
 	 * Runs-anywhere Decision 5: what's wrong with the site's GitHub access, for every
 	 * person, while it holds (not dismissable, unlike `notices`): a refused credential, a
 	 * missing permission, or a token expiring within 14 days. `message` names the fix,
-	 * for the developer it's forwarded to. Null when nothing is wrong.
+	 * for the developer it's forwarded to. Null when nothing is wrong. `cloud` (caracms-cloud
+	 * M2 Decision 14): CaraCMS Cloud refused a token; `message` is the cloud's sentence and
+	 * `link` the install link it names, if any, which the note shows as a link.
 	 */
-	githubAccess: { kind: 'refused' | 'permission' | 'expiring'; title: string; message: string } | null;
+	githubAccess: { kind: 'refused' | 'permission' | 'expiring' | 'cloud'; title: string; message: string; link?: string | null } | null;
 	/**
 	 * The brand as committed in Site Settings (M5a Decision 10: read from `drafts`, never
 	 * an autosave), so the chrome picks up a change on the next poll with no reload.
 	 */
 	brand: EditorBrand;
+	/**
+	 * Arrange pages (Decision 18): a short hash of Site Settings' `pageOrder` as it stands in
+	 * the store (the autosave on top of `drafts`); `""` when there's none. When it changes,
+	 * the tab re-reads the listing, as it does when the waiting list's keys change.
+	 */
+	pageOrderStamp: string;
 }
 
 /** POST /_caracms/lock `{ file, action }`. */
@@ -582,12 +607,15 @@ export interface DeleteResponse {
  * POST /_caracms/move (pre-M7 item 8): change a document's address. `to` is its new
  * path in the same collection (`studio/visit`), its new parts made with slug.ts as a
  * new document's are. Every link and reference to it is rewritten, and a redirect from
- * the old address to the new is added to Site Settings.
+ * the old address to the new is added to Site Settings unless `redirect` is false
+ * (Change address…'s "Leave a redirect from …", on unless it's unticked).
  */
 export interface MoveRequest {
 	collection: string;
 	path: string;
 	to: string;
+	/** Whether to leave a redirect from the old address (default true). A document that was never live gets none either way. */
+	redirect?: boolean;
 }
 
 /** 200: the document is at its new path (live mode: as autosaves, all going out at the next Publish). */
@@ -602,8 +630,49 @@ export interface MoveResponse {
 	from: { path: string; file: string; url: string };
 	/** The other documents whose links (or references) to it were rewritten, with their titles. */
 	relinked: { collection: string; path: string; title: string }[];
-	/** The redirect added: null for a document that was never live (made since the last Publish). */
+	/** The redirect added: null when none was asked for, or for a document that was never live (made since the last Publish). */
 	redirect: { from: string; to: string } | null;
+	/**
+	 * Collections under pages (Decision 9): every address that changed, this document's first,
+	 * then the pages under it and the documents of a collection held under it (`from` = `to`:
+	 * a held document's file stays where it is).
+	 */
+	moved: { collection: string; from: string; to: string; title: string; fromUrl: string; toUrl: string }[];
+	/** Every redirect added, one per address that was live (none when none was asked for). */
+	redirects: { from: string; to: string }[];
+}
+
+/**
+ * POST /_caracms/arrange (arrange pages, Contracts): the arrangement as its result.
+ * - `moves`: the roots only, each page whose path changes and isn't carried by a root above
+ *   it (its old path under that root's `fromPath`, its new path that root's `toPath` + the
+ *   same rest). The server expands each to everything under it (pages at any depth, a held
+ *   collection's documents) except what's under another root, which wins for its own subtree.
+ * - `order`: the full child list for every parent whose children or order changed, keyed by
+ *   the parent's path after the moves (`""` the top level); an empty list drops the key.
+ *   Every other saved list is re-keyed after the moves by the server.
+ * - `redirect: false`: no redirects from the old addresses (the review's tick unticked).
+ */
+export interface ArrangeRequest {
+	moves: ArrangeMove[];
+	order: Record<string, string[]>;
+	redirect?: boolean;
+	/**
+	 * Collection name → page-order.ts's `listingStamp` of every document path in that
+	 * collection (hidden ones included) as the review's listing had them: Pages, and each
+	 * collection held by a page that moves. Any difference at Apply refuses with 409
+	 * `changed` and nothing is written (Decision 10). Absent: no check.
+	 */
+	expect?: Record<string, string>;
+}
+export interface ArrangeMove {
+	collection: string;
+	fromPath: string;
+	toPath: string;
+}
+/** 200: the moves and the order landed together (live mode: as autosaves, out at the next Publish). Refused: an ApiError like the move route's (`{ error, code }`, a lock refusal's state with `locked`). */
+export interface ArrangeResponse {
+	ok: true;
 }
 
 /**
@@ -613,9 +682,10 @@ export interface MoveResponse {
  *   isn't an address `slugify` leaves as it is, or nothing left), `index`,
  *   `reserved-address` (under `/admin` or `/_caracms`), `below-collection` (strictly
  *   under another collection's address), `not-allowed` (Site Settings, Home, a shared
- *   block with no or an unknown block type);
+ *   block with no or an unknown block type), `not-held` (collections under pages, Decision 7: a
+ *   held collection no page holds, or whose holding is a problem; the message is held.ts's sentence);
  * - 404 `not-found` (delete: no such document);
- * - 409 `exists` (create: the document is already there), `address-taken` (another
+ * - 409 `changed` (arrange: the listing isn't the one the review was planned on), `exists` (create: the document is already there), `address-taken` (another
  *   document has that address: "There's already a page at /services/packaging"),
  *   `in-use` (a shared block something still uses; `usedOn` says where), `locked`
  *   (live: someone else holds the document's lock: "Aoife is editing Contact"; the
@@ -636,12 +706,18 @@ export type CreateDeleteCode =
 	| 'reserved-address'
 	| 'below-collection'
 	| 'not-allowed'
+	| 'not-held'
 	| 'not-found'
 	| 'exists'
 	| 'address-taken'
 	| 'in-use'
+	| 'holds'
 	| 'locked'
-	| 'same';
+	| 'same'
+	// Arrange pages (Decision 10): the listing changed since the review (ArrangeRequest.expect).
+	| 'changed'
+	// Arrange pages: an order-only Apply when Site Settings, which holds the order, isn't valid JSON.
+	| 'invalid-json';
 
 // ── Media (M5b Phase 2: Decisions 6, 7 and 12) ────────────────────────────────
 

package/src/held.ts

@@ -0,0 +1,116 @@
+/**
+ * Collections under pages (Decisions 2, 7, 11, 13): a held collection's address is the
+ * address of the page that holds it, worked out from a listing, never from the config.
+ *
+ * - **The mount is in the content:** a page of the collection `heldBy` names says
+ *   `"holds": "<collection>"` (content.ts reads it into the entry's `holds`). The
+ *   collection's base is that page's address + `/` (`/journal/`), so its documents follow
+ *   the page wherever it moves.
+ * - **One holder or none.** No page holding it, two pages holding it, Home holding it, or
+ *   the holder's own file unopenable (invalid JSON, no title): the collection has no
+ *   addresses (base null) and `problem` says why, naming the files. `validate` reports the
+ *   same sentence as an error; the editor shows it on the collection's sidebar entry.
+ * - **A hidden holder hides its documents** (Decision 11), as a hidden page hides the pages
+ *   under it: `hidden` here, and content.ts marks each document.
+ * - **Pure and browser-safe** (no imports): the server resolves bases for the editor's
+ *   payload, and the browser can do the same from a fresh listing.
+ */
+
+/** What resolving needs of a collection (config.ts → ResolvedCollection, the editor's payload). */
+export interface HoldableCollection {
+	name: string;
+	label: string;
+	urlBase: string | null;
+	heldBy?: string | null;
+}
+
+/** What resolving needs of a listed document (content.ts → DocumentEntry). */
+export interface HoldingEntry {
+	collection: string;
+	path: string;
+	file: string;
+	url: string | null;
+	label: string;
+	warning: { message: string } | null;
+	hidden?: true;
+	/** The collection key the page's file says it holds (`"holds"`), even when the file can't be opened. */
+	holds?: string;
+}
+
+export interface HeldBase {
+	collection: string;
+	/** The holder's address + `/` (`/journal/`); null while no page holds it, or the holding is a problem. */
+	base: string | null;
+	/** The page that holds it; null when none does (or two do). */
+	holder: { collection: string; path: string; file: string; label: string } | null;
+	/** The holder is hidden from the site (itself, or a page above it), so the documents are too (Decision 11). */
+	hidden: boolean;
+	/** Decision 13's sentence when the collection has no addresses, naming the files; null when it's held. */
+	problem: string | null;
+}
+
+const and = (items: readonly string[]): string => (items.length <= 1 ? (items[0] ?? '') : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`);
+
+/** Every held collection's base, from a listing that has (at least) every document of the collections their `heldBy` names. */
+export function heldBases(collections: Readonly<Record<string, HoldableCollection>>, entries: readonly HoldingEntry[]): Record<string, HeldBase> {
+	const out: Record<string, HeldBase> = {};
+	for (const collection of Object.values(collections)) {
+		if (!collection.heldBy) continue;
+		const { name, label } = collection;
+		const holders = entries.filter((e) => e.collection === collection.heldBy && e.holds === name);
+		const none: HeldBase = { collection: name, base: null, holder: null, hidden: false, problem: null };
+		if (holders.length === 0) {
+			out[name] = { ...none, problem: `No page holds ${label}, so its documents have no addresses and aren't on the site. Add "holds": "${name}" to the page they go under.` };
+			continue;
+		}
+		if (holders.length > 1) {
+			const files = holders.map((h) => h.file);
+			out[name] = { ...none, problem: `${and(files)} ${files.length === 2 ? 'both' : 'all'} hold ${label}, but only one page can hold it, so its documents have no addresses. Take "holds" out of ${files.length === 2 ? 'one of them' : 'all but one'}.` };
+			continue;
+		}
+		const page = holders[0]!;
+		const holder = { collection: page.collection, path: page.path, file: page.file, label: page.label };
+		if (page.path === 'index') {
+			out[name] = { ...none, holder, problem: `${page.file} is Home, which can't hold ${label} (its address is the whole site's), so ${label}'s documents have no addresses. Put "holds": "${name}" on another page.` };
+			continue;
+		}
+		if (page.warning || page.url === null) {
+			const why = page.warning ? ` ${page.warning.message}` : '';
+			out[name] = { ...none, holder, problem: `${page.file} holds ${label}, but it can't be opened, so ${label}'s documents have no addresses until it's fixed.${why}` };
+			continue;
+		}
+		out[name] = { collection: name, base: `${page.url.replace(/\/+$/, '')}/`, holder, hidden: page.hidden === true, problem: null };
+	}
+	return out;
+}
+
+/** The site with each held collection's `urlBase` as resolved (null while it has a problem): what every address rule and the editor read. */
+export function withHeldBases<C extends HoldableCollection, S extends { collections: Record<string, C> }>(site: S, bases: Readonly<Record<string, HeldBase>>): S {
+	const held = Object.values(bases);
+	if (held.length === 0) return site;
+	const collections = { ...site.collections };
+	for (const b of held) if (Object.hasOwn(collections, b.collection)) collections[b.collection] = { ...collections[b.collection]!, urlBase: b.base };
+	return { ...site, collections };
+}
+
+/** Does the site have a collection a page holds? (Most don't, and skip the extra listing.) */
+export const hasHeld = (collections: Readonly<Record<string, HoldableCollection>>): boolean => Object.values(collections).some((c) => !!c.heldBy);
+
+/**
+ * A held collection's word for its documents, as the editor's `singular` (documents/actions.ts)
+ * names one: a plural label as it is ("case studies", "posts"), any other with "entries"
+ * ("journal entries"). A held collection is flat and never shared blocks, so the label is all it takes.
+ */
+export function documentsNoun(label: string): string {
+	const l = label.toLowerCase();
+	return /ies$/.test(l) || /[^s]s$/.test(l) ? l : `${l} entries`;
+}
+
+/**
+ * Decision 12's sentence: "Journal holds the journal entries. Delete the “holds” line in its
+ * file, or move the journal entries to another page, first." Delete… on the page says it instead of asking.
+ */
+export function holdsMessage(page: string, collection: string): string {
+	const noun = documentsNoun(collection);
+	return `${page} holds the ${noun}. Delete the “holds” line in its file, or move the ${noun} to another page, first.`;
+}

package/src/index.ts

@@ -58,7 +58,8 @@ import { lockupCss } from './lockup-css.ts';
 import { shareBuildReads } from './read.ts';
 import { writeSchemaFiles } from './cli/schemas.ts';
 import { configFile } from './cli/site.ts';
-import { readCodeRoutes } from './code-routes-disk.ts';
+import { pagesRoutes } from './code-routes-disk.ts';
+import { codeRoutesFrom } from './code-routes.ts';
 import { GUARD_MIDDLEWARE, LOGIN_ROUTES } from './live/auth/routes.ts';
 import { HOST_COMMIT_VARIABLES } from './live/mode.ts';
 
@@ -124,6 +125,8 @@ export const EDITOR_ROUTES = [
 	{ pattern: '/_caracms/delete', entrypoint: 'editor/routes/delete.ts' },
 	// Pre-M7 item 8: changing a document's address, both modes.
 	{ pattern: '/_caracms/move', entrypoint: 'editor/routes/move.ts' },
+	// Arrange pages: the arrange screen's Apply, both modes.
+	{ pattern: '/_caracms/arrange', entrypoint: 'editor/routes/arrange.ts' },
 	// M5b Phase 2: the media library, uploads and Mux, both modes (types.ts → MEDIA_ENDPOINTS).
 	{ pattern: '/_caracms/media/[...path]', entrypoint: 'editor/routes/media.ts' },
 	// M4 Decision 14: GitHub's push webhook (signature-checked; 404 with no secret).
@@ -352,7 +355,8 @@ export default function caracms(config: SiteConfig): AstroIntegration {
 				const configName = configFile(site.root);
 				if (configName) addWatchFile(join(site.root, configName));
 				// M8 Decision 10: the site's own routes, read once here, for the editor's server and browser alike.
-				site.codeRoutes = readCodeRoutes(site.root, astroConfig.srcDir ? fileURLToPath(astroConfig.srcDir) : 'src', Object.values(site.collections));
+				site.pageRoutes = pagesRoutes(site.root, astroConfig.srcDir ? fileURLToPath(astroConfig.srcDir) : 'src');
+				site.codeRoutes = codeRoutesFrom(site.pageRoutes, Object.values(site.collections));
 				// M5b Decision 5: local dev (and a local build) read the media variables from the site's
 				// `.env`, which Astro doesn't put in process.env. Only those names; a set value wins.
 				const siteEnv = await loadSiteEnv(command === 'dev' ? 'development' : 'production', site.root);

package/src/live/README.md

@@ -7,7 +7,7 @@ live drafts store, sweep, locks and status route, and Phase 3's sign-in, sit on
 | File | What |
 |---|---|
 | `mode.ts` | `readMode(env, production)` → `local`, `live` (with `LiveSettings`) or `unconfigured` (`missing`, `problems`); `unconfiguredMessage()` for the 503 |
-| `runtime.ts` | `liveRuntime(site, settings)`: one per process, lazy. `createLiveRuntime({...})` for tests (inject backend, Redis, clock). `CARACMS_GITHUB=memory`: a MemoryBackend seeded from disk (`siteFiles`), refused in production |
+| `runtime.ts` | `liveRuntime(site, settings)`: one per process, lazy. With a cloud key it reads the repo from the cloud and takes its first token before anything else, so a refusal stops the start (the guard answers 503 with the cloud's sentence; the next request tries again). `createLiveRuntime({...})` for tests (inject backend, Redis, clock). `CARACMS_GITHUB=memory`: a MemoryBackend seeded from disk (`siteFiles`), refused in production |
 | `git.ts` | `LiveGit`: the `drafts` copy (`files()`, `read()`, `contentSource()`), `commitDrafts()`, `check()`, `publish()` and its `commitPending` hook, `waiting()`, `publishStatus()`, `history()`, `tryAgain()`. M5a: a draft entry with `text` null removes the file; "Contact (deleted)" in the headlines; `mainHas`, `changeOf` (new, deleted or changed), `titleFor` |
 | `timings.ts` | `LiveTimings` and `DEFAULT_TIMINGS`: every timing, Phase 2's sweep and lock ones included |
 | `merge.ts` | `mergeFile({ base, draft, other })`: the per-key three-way merge, pure and byte-preserving |
@@ -18,7 +18,8 @@ live drafts store, sweep, locks and status route, and Phase 3's sign-in, sit on
 | `notices.ts` | Redis diet. `Notices`: "published as it stood" notices and dismissed "draft kept" ones, written through the status cache |
 | `backend.ts` | `GitBackend`; `GitHubBackend`, `MemoryBackend` (test helpers: `seed`, `push`, `file`, `deployments`, `beforeRequest`); `StaleHeadError` |
 | `branches.ts` | `Branch` (a role: `main` or `drafts`), `BranchNames` (the refs behind them), `DEFAULT_BRANCHES`. `CARACMS_MAIN_BRANCH` and `CARACMS_DRAFTS_BRANCH` (read by `mode.ts`, M9 Decision 6) name the branch Publish commits to and the one autosaves land on; unset, `main` and `drafts`. They're set together or not at all: one alone is a problem, so the mode is unconfigured (`/admin` answers 503 saying both must be set; the public site still serves). Only the backends turn a role into a ref name, so with both set a branch called `main` is never read or moved. `MemoryBackend.refs` is keyed by name |
-| `github.ts` | The App's JWT, the installation token (one repo, refreshed early), `Tracker` (request counts) |
+| `github.ts` | The App's JWT, the installation token (one repo, refreshed early), `Tracker` (request counts). A third credential, `cloud`: the token from CaraCMS Cloud, refreshed the same way; its refusals are an access problem of kind `cloud` |
+| `cloud.ts` | CaraCMS Cloud (`CARACMS_CLOUD_KEY`; caracms-cloud M2): `DEFAULT_CLOUD_URL`, `cloudSettings()` (the repo, at start), `cloudToken()`, `CloudRefusal` (the cloud's `error`, `message`, `installUrl`), and `cloudUnavailable()`, the sign-in guard's 503 for a refusal at start |
 | `webhook.ts` | `handleGithubWebhook()`, behind `POST /_caracms/github` (`../editor/routes/github.ts`) |
 | `autosaves.ts` | Phase 2. Autosaves in Redis (`caracms:autosave:<file>`, a week; stored compare-and-set, ordered per tab by `X-Caracms-Seq`), the session's last commit (the merge's ancestor) and who last changed a document (Decision 11; no expiry, and `known: false` when neither Redis nor git can say). M5a: a new document's autosave carries `created: { over }` (its ancestor until committed), a deletion is a "gone" autosave (`text` and `document` null, `gone: { title }`) |
 | `locks.ts` | Phase 2. `Locks`: taken by the first write, heartbeat on the poll (Redis diet: only when `needsBeat`), lapse only once committed, releasing, Edit here; presence, each record holding for twice its tab's poll interval plus 3 s |

package/src/live/auth/middleware.ts

@@ -14,11 +14,18 @@
  *   answering 503 here until the GitHub App's variables were set). A GET to it is as
  *   unavailable as any other guarded path, as live mode's let-through is POST-only too.
  *
+ * - **A start that fails** answers 503 and the next request tries again (runtime.ts). When
+ *   CaraCMS Cloud refused the start or couldn't be reached (caracms-cloud M2 Decision 14), the
+ *   answer is the cloud's own sentence, as an HTML page with its install link as a link
+ *   (JSON under `/_caracms/`, as ../../editor/middleware.ts answers); any other failure keeps
+ *   the plain sentence. Neither the log line nor the page carries the site key or a token.
+ *
  * The mode is Phase 2's `editorMode()`, so the two agree on live and local.
  */
 import type { MiddlewareHandler } from 'astro';
 import { site } from 'virtual:caracms/config';
 import { editorMode } from '../../editor/server/mode.ts';
+import { CloudRefusal, cloudUnavailable } from '../cloud.ts';
 import { setPerson } from '../locals.ts';
 import { guard, isFormEndpoint, isGuardedPath } from './guard.ts';
 import { authFor } from './index.ts';
@@ -35,6 +42,10 @@ export const onRequest: MiddlewareHandler = async (context, next) => {
 	try {
 		auth = await authFor(site, mode.settings, context.site);
 	} catch (error) {
+		if (error instanceof CloudRefusal) {
+			console.error(`[caracms] sign-in: the live runtime could not start: CaraCMS Cloud (${error.error}): ${error.message}`);
+			return cloudUnavailable(error, context.url.pathname.startsWith('/_caracms/'));
+		}
 		console.error('[caracms] sign-in: the live runtime could not start:', error);
 		return unavailable("The editor couldn't start. Try again in a moment.");
 	}