caracms 0.0.0-stage → 0.2.0

package/src/editor/routes/admin.astro

@@ -0,0 +1,80 @@
+---
+/**
+ * /admin and /admin/<collection>/<path> (addresses, Decision 19). Injected in dev and
+ * in the build (M4 Decision 1); live mode needs a session (Phase 3's guard).
+ *
+ * The shell is React, rendered here on the server (Decision 2), so the chrome is in
+ * the HTML before any script runs: the pane with the Pages groups as the cookie
+ * says (Decision 20), the stage with the iframes already loading, the bar. The
+ * browser then hydrates it (client/main.tsx) from the same props.
+ *
+ * Content is read now (Decision 5), through the mode's drafts store (server/mode.ts):
+ * the disk in local mode, the `drafts` copy with autosaves on top in live mode.
+ */
+import '../styles/fonts.css';
+import '../styles/tokens.css';
+import '../styles/editor.css';
+// Each pane level's own CSS, if it needs any beyond the mockup's (styles/levels/<level>.css).
+import.meta.glob('../styles/levels/*.css', { eager: true });
+import geistMono from '../fonts/geist-mono-latin-wght-normal.woff2?url';
+import instrumentSans from '../fonts/instrument-sans-latin-wght-normal.woff2?url';
+import { site } from 'virtual:caracms/config';
+import { monogramIcon } from '../brand.ts';
+import { adminProps } from '../server/admin-props.ts';
+import { personOf } from '../../live/locals.ts';
+import { editorMode, editorStore } from '../server/mode.ts';
+import { renderEditor } from '../server/render.tsx';
+import { UI_COOKIE } from '../ui-state.ts';
+
+export const prerender = false;
+
+Astro.response.headers.set('Cache-Control', 'no-store');
+
+// Defence in depth: the guard (Phase 3) signs people in; with no person here, nothing is shown.
+if (editorMode().kind === 'live' && !personOf(Astro.locals)) {
+	return new Response('<!doctype html><meta charset="utf-8"><title>Sign in</title><p>Sign in to use the editor.</p><p><a href="/admin/login">Sign in</a></p>', {
+		status: 401,
+		headers: { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' },
+	});
+}
+
+const result = await adminProps({ site, store: await editorStore(site), url: Astro.url, cookie: (name) => Astro.cookies.get(name)?.value, person: personOf(Astro.locals) });
+if (!result.ok) {
+	const escape = (s: string) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]!);
+	return new Response(
+		`<!doctype html><meta charset="utf-8"><title>Not found</title><p>${escape(result.message)}</p><p><a href="/admin">Open the editor</a></p>`,
+		{ status: result.status, headers: { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' } },
+	);
+}
+const { props } = result;
+// The server's view of the per-browser state (the open document's groups opened, Recent updated) goes back in the cookie.
+Astro.cookies.set(UI_COOKIE, JSON.stringify(props.ui), { path: '/', maxAge: 60 * 60 * 24 * 365, sameSite: 'lax' });
+
+const html = renderEditor(props);
+// The props travel as JSON in the page; `<` escaped so no text can close the tag.
+const json = JSON.stringify(props).replace(/</g, '\\u003c');
+const { brand } = props.site;
+// M6: the inbox names itself (it has no document of its own).
+const title = `${props.inbox ? 'Submissions' : props.opened.document.title || props.opened.entry.label} · ${brand.name}`;
+const accent = `--accent:${brand.accent};--accent-ink:${brand.accentInk};--accent-edge:${brand.accentEdge}`;
+---
+
+<!doctype html>
+<html lang="en" style={accent}>
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta name="robots" content="noindex" />
+		<title>{title}</title>
+		<link rel="icon" href={brand.tabIcon ?? brand.icon ?? brand.logo ?? monogramIcon(brand.name, brand.accent)} />
+		<link rel="preload" href={instrumentSans} as="font" type="font/woff2" crossorigin />
+		<link rel="preload" href={geistMono} as="font" type="font/woff2" crossorigin />
+	</head>
+	<body>
+		<div id="viewport" set:html={html} />
+		<script type="application/json" id="caracms-props" set:html={json} />
+		<script>
+			import '../client/main.tsx';
+		</script>
+	</body>
+</html>

package/src/editor/routes/create.ts

@@ -0,0 +1,19 @@
+/**
+ * POST /_caracms/create: `{ collection, path, title, blockType? }` →
+ * `{ ok, collection, path, file, url, version }`, or `{ error, code }` (M5a Phase 3,
+ * Decision 11; shapes and codes: ../types.ts → CreateRequest, CreateDeleteRefusal).
+ * The rules, and why it's a security boundary, are in ../server/create.ts; the store is
+ * the mode's (server/mode.ts): an exclusive create on disk in local mode, the lock and
+ * an autosave with no base in live mode, where the request carries `X-Caracms-Tab`
+ * and the guard has checked the session (M4 Decision 14's path prefix).
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { personOf } from '../../live/locals.ts';
+import { handleCreate } from '../server/create.ts';
+import { editorStore } from '../server/mode.ts';
+
+export const prerender = false;
+
+/** POST, and every other method (405). */
+export const ALL: APIRoute = async ({ request, locals }) => handleCreate(request, await editorStore(site), { person: personOf(locals) });

package/src/editor/routes/delete.ts

@@ -0,0 +1,19 @@
+/**
+ * POST /_caracms/delete: `{ collection, path }` → `{ ok, collection, path, file }`, or
+ * `{ error, code }` (M5a Phase 3, Decision 12; shapes and codes: ../types.ts →
+ * DeleteRequest, CreateDeleteRefusal). The rules, and why it's a security boundary,
+ * are in ../server/create.ts; the store is the mode's (server/mode.ts): the file and
+ * its emptied folders on disk in local mode, the lock and a "gone" autosave in live
+ * mode, where the request carries `X-Caracms-Tab` and the guard has checked the
+ * session (M4 Decision 14's path prefix).
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { personOf } from '../../live/locals.ts';
+import { handleDelete } from '../server/create.ts';
+import { editorStore } from '../server/mode.ts';
+
+export const prerender = false;
+
+/** POST, and every other method (405). */
+export const ALL: APIRoute = async ({ request, locals }) => handleDelete(request, await editorStore(site), { person: personOf(locals) });

package/src/editor/routes/document.ts

@@ -0,0 +1,39 @@
+/**
+ * GET /_caracms/document?collection=<name>&path=<path>: one document as the editor
+ * opens it, through the mode's drafts store (server/mode.ts): the file on disk in
+ * local mode; the `drafts` copy with its autosave on top in live mode (M4 Decision 4).
+ *
+ *   200 { entry, text, document, mtimeMs, version, lastChange? }   (types.ts → OpenedDocument; lastChange in live mode, Decision 11)
+ *   400/404 { error, code }                                        (content.ts → DocumentError)
+ *   401 { error: 'signed-out' } (live mode, no person); 503 { error, code: 'unavailable' } (Redis out)
+ *
+ * `text` is the serializer's base for the editing session, and what the keeper
+ * compares held edits with.
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { DocumentError } from '../../content.ts';
+import { personOf } from '../../live/locals.ts';
+import { editorMode, editorStore } from '../server/mode.ts';
+import { WriteRefused } from '../server/write.ts';
+
+export const prerender = false;
+
+const headers = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' };
+
+export const GET: APIRoute = async ({ url, locals }) => {
+	if (editorMode().kind === 'live' && !personOf(locals)) return new Response(JSON.stringify({ error: 'signed-out', code: 'signed-out' }), { status: 401, headers });
+	const collection = url.searchParams.get('collection') ?? '';
+	const path = url.searchParams.get('path') ?? '';
+	try {
+		const store = await editorStore(site);
+		return new Response(JSON.stringify(await store.read(collection, path)), { headers });
+	} catch (error) {
+		if (error instanceof DocumentError) {
+			const status = error.code === 'not-found' ? 404 : 400;
+			return new Response(JSON.stringify({ error: error.message, code: error.code }), { status, headers });
+		}
+		if (error instanceof WriteRefused) return new Response(JSON.stringify({ error: error.message, ...error.body }), { status: error.status, headers });
+		throw error;
+	}
+};

package/src/editor/routes/documents.ts

@@ -0,0 +1,30 @@
+/**
+ * GET /_caracms/documents: every document, in the editor's order, with warnings and
+ * times (drafts-store.ts → list), through the mode's store (server/mode.ts). For
+ * refreshing the documents level (editor.refreshDocuments).
+ *
+ * M6 Decision 9: the inbox's unread count comes with it, in `X-Caracms-Unread` (absent
+ * when the production server has no submissions bucket, or the count couldn't be read).
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { submissionsSetupQuick, UNREAD_HEADER } from '../../forms/inbox.ts';
+import { personOf } from '../../live/locals.ts';
+import { editorMode, editorStore } from '../server/mode.ts';
+import { WriteRefused } from '../server/write.ts';
+import { withCards } from '../server/cards.ts';
+
+export const prerender = false;
+
+const headers = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' };
+
+export const GET: APIRoute = async ({ locals }) => {
+	if (editorMode().kind === 'live' && !personOf(locals)) return new Response(JSON.stringify({ error: 'signed-out', code: 'signed-out' }), { status: 401, headers });
+	try {
+		const [documents, submissions] = await Promise.all([(await editorStore(site)).list().then((all) => withCards(site, all)), submissionsSetupQuick({ site })]);
+		return new Response(JSON.stringify(documents), { headers: { ...headers, ...(submissions.unread !== null ? { [UNREAD_HEADER]: String(submissions.unread) } : {}) } });
+	} catch (error) {
+		if (error instanceof WriteRefused) return new Response(JSON.stringify({ error: error.message, ...error.body }), { status: error.status, headers });
+		throw error;
+	}
+};

package/src/editor/routes/github.ts

@@ -0,0 +1,23 @@
+/**
+ * POST /_caracms/github: GitHub's push webhook (M4 Decision 14). It only prompts the
+ * check that keeps `drafts` up to date with `main` (Decision 8); the logic, and what
+ * it refuses, is in ../../live/webhook.ts.
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { liveEditor } from '../../live/editor.ts';
+import { handleGithubWebhook } from '../../live/webhook.ts';
+import { editorMode } from '../server/mode.ts';
+
+export const prerender = false;
+
+export const ALL: APIRoute = ({ request }) => {
+	const mode = editorMode(); // local mode: 404 (no secret)
+	if (mode.kind !== 'live') return handleGithubWebhook(request, { secret: null, trigger: async () => {} });
+	const { settings } = mode;
+	return handleGithubWebhook(request, {
+		secret: settings.webhookSecret,
+		// The editor, not just the runtime: the merge commits pending autosaves first (the sweep fills that hook).
+		trigger: async () => (await liveEditor(site, settings)).runtime.git.check({ force: true }),
+	});
+};

package/src/editor/routes/history.ts

@@ -0,0 +1,9 @@
+/**
+ * GET /_caracms/history: the newest 20 publishes (Decision 12).
+ * Live mode only (M4 Phase 2); the handler is ../../live/editor.ts → `history`. Shapes: ../types.ts.
+ */
+import { liveRoute } from './_live.ts';
+
+export const prerender = false;
+
+export const ALL = liveRoute('history');

package/src/editor/routes/lock.ts

@@ -0,0 +1,9 @@
+/**
+ * POST /_caracms/lock { file, action: 'take' | 'release' }: Edit here, and a closing tab's release (Decision 9).
+ * Live mode only (M4 Phase 2); the handler is ../../live/editor.ts → `lock`. Shapes: ../types.ts.
+ */
+import { liveRoute } from './_live.ts';
+
+export const prerender = false;
+
+export const ALL = liveRoute('lock');

package/src/editor/routes/login/assets.d.ts

@@ -0,0 +1,10 @@
+// Vite's asset imports the sign-in route uses (Vite's own client types aren't in the
+// package's tsconfig): a font's URL in the bundle, and a stylesheet's text.
+declare module '*.woff2?url' {
+	const url: string;
+	export default url;
+}
+declare module '*.css?raw' {
+	const css: string;
+	export default css;
+}

package/src/editor/routes/login/login.ts

@@ -0,0 +1,43 @@
+/**
+ * Every `/admin/login…` page (M4 Phase 3). The logic is ../../../live/auth/login.ts;
+ * this route hands it the site's brand, the editor's tokens and its face, and the
+ * process's Auth. In local mode there's no sign-in: every page goes to the editor.
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import instrumentSansExt from '../../fonts/instrument-sans-latin-ext-wght-normal.woff2?url';
+import instrumentSans from '../../fonts/instrument-sans-latin-wght-normal.woff2?url';
+import tokensCss from '../../styles/tokens.css?raw';
+import { monogramIcon } from '../../brand.ts';
+import { editorMode } from '../../server/mode.ts';
+import { currentBrand, editorBrand } from '../../server/settings.ts';
+import { authFor } from '../../../live/auth/index.ts';
+import { handleLogin, localLoginRedirect } from '../../../live/auth/login.ts';
+import type { Brand, PageAssets } from '../../../live/auth/views.ts';
+
+export const prerender = false;
+
+/** The brand as it applies now (M5a Decision 10: Site Settings' name and accent, as committed). */
+async function brandNow(): Promise<Brand> {
+	const brand = editorBrand(await currentBrand(site));
+	return { ...brand, icon: brand.icon ?? brand.logo ?? monogramIcon(brand.name, brand.accent) };
+}
+
+// The chrome's face, as fonts.css declares it (latin, then latin-ext), with the bundle's URLs.
+const face = (src: string, range: string) =>
+	`@font-face{font-family:'Instrument Sans';font-style:normal;font-display:block;font-weight:400 700;src:url('${src}') format('woff2-variations');unicode-range:${range}}`;
+const assets: PageAssets = {
+	tokensCss,
+	fontsCss: [
+		face(instrumentSans, 'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD'),
+		face(instrumentSansExt, 'U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF'),
+	].join('\n'),
+};
+
+export const ALL: APIRoute = async (context) => {
+	const mode = editorMode();
+	if (mode.kind === 'local') return localLoginRedirect();
+	if (mode.kind !== 'live') return new Response("The editor isn't set up on this server yet.", { status: 503, headers: { 'Cache-Control': 'private, no-store' } });
+	const auth = await authFor(site, mode.settings, context.site);
+	return handleLogin(context.request, { auth, brand: await brandNow(), assets, clientAddress: () => context.clientAddress });
+};

package/src/editor/routes/media.ts

@@ -0,0 +1,16 @@
+/**
+ * `/_caracms/media/*`: the media library, uploads and Mux (M5b Phase 2). Both modes:
+ * in live mode the guard's prefix rule has checked the session and, for a POST, the
+ * origin; local mode has no sign-in. Every route and shape: ../types.ts →
+ * MEDIA_ENDPOINTS; the rules: ../server/media/handler.ts.
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { personOf } from '../../live/locals.ts';
+import { handleMedia } from '../server/media/handler.ts';
+import { editorMode, editorStore } from '../server/mode.ts';
+
+export const prerender = false;
+
+export const ALL: APIRoute = async ({ request, locals }) =>
+	handleMedia(request, { site, store: await editorStore(site), mode: editorMode().kind === 'live' ? 'live' : 'local', person: personOf(locals) });

package/src/editor/routes/move.ts

@@ -0,0 +1,17 @@
+/**
+ * POST /_caracms/move: `{ collection, path, to }` → MoveResponse, or `{ error, code }`
+ * (pre-M7 item 8; shapes: ../types.ts → MoveRequest). The rules are in ../server/move.ts;
+ * the store is the mode's (server/mode.ts), as for create and delete: on disk in local
+ * mode, autosaves under this tab's locks in live mode, where the request carries
+ * `X-Caracms-Tab` and the guard has checked the session (its `/_caracms/` prefix rule).
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { personOf } from '../../live/locals.ts';
+import { handleMove } from '../server/move.ts';
+import { editorStore } from '../server/mode.ts';
+
+export const prerender = false;
+
+/** POST, and every other method (405). */
+export const ALL: APIRoute = async ({ request, locals }) => handleMove(request, await editorStore(site), { person: personOf(locals) });

package/src/editor/routes/notice.ts

@@ -0,0 +1,9 @@
+/**
+ * POST /_caracms/notice { id }: dismiss a notice.
+ * Live mode only (M4 Phase 2); the handler is ../../live/editor.ts → `notice`. Shapes: ../types.ts.
+ */
+import { liveRoute } from './_live.ts';
+
+export const prerender = false;
+
+export const ALL = liveRoute('notice');

package/src/editor/routes/preview.astro

@@ -0,0 +1,77 @@
+---
+/**
+ * The preview route: the real page, through the site's page
+ * component (RenderDocument), with preview markers (Decision 17).
+ *
+ * - GET ?collection=<name>&path=<path> renders the document as the mode's drafts store
+ *   reads it now (disk in local mode; the `drafts` copy with its autosave in live
+ *   mode): an iframe's first load, version 0.
+ * - POST { version, collection, path, document } renders the document it's sent (the
+ *   editor's copy); `path` (optional) is where it is in its collection, for the page
+ *   component's `path` (MEC trial item 2). The response carries the version it rendered in
+ *   `X-Preview-Version` (Decision 13: latest edit wins).
+ *
+ * Any kind of document a page shows (M5a): a section builder's, a list-of-fields
+ * document through its collection's component, a shared block alone in the page's
+ * frame (Decision 8). Site Settings has no page of its own (404). The render reads
+ * other documents (Decision 9: shared blocks, a case-study list) from the mode's
+ * store with its autosaves on top (`store.source()`), never the disk under live mode.
+ *
+ * Keeps no state and writes nothing. Never cached.
+ */
+import RenderDocument from '../../components/RenderDocument.astro';
+import { site } from 'virtual:caracms/config';
+import { DocumentError } from '../../content.ts';
+import { personOf } from '../../live/locals.ts';
+import { editorMode, editorStore } from '../server/mode.ts';
+import { normaliseAnyDocument, type AnyDocument, type PageDocument } from '../../document.ts';
+import { setRenderSource } from '../../read.ts';
+
+export const prerender = false;
+
+const plain = (status: number, message: string) =>
+	new Response(message, { status, headers: { 'Cache-Control': 'no-store', 'Content-Type': 'text/plain; charset=utf-8' } });
+
+if (editorMode().kind === 'live' && !personOf(Astro.locals)) return plain(401, 'signed-out');
+
+let version = 0;
+let collection: string;
+let document: AnyDocument;
+let path: string | undefined;
+const store = await editorStore(site);
+
+if (Astro.request.method === 'POST') {
+	let body: { version?: unknown; collection?: unknown; path?: unknown; document?: unknown };
+	try {
+		body = await Astro.request.json();
+	} catch {
+		return plain(400, 'Send JSON: { version, collection, document }.');
+	}
+	if (!Number.isSafeInteger(body.version) || (body.version as number) < 0) return plain(400, 'version must be a non-negative integer.');
+	if (typeof body.collection !== 'string' || !Object.hasOwn(site.collections, body.collection)) return plain(400, 'collection must be a declared collection.');
+	if (!body.document || typeof body.document !== 'object') return plain(400, 'document must be an object.');
+	version = body.version as number;
+	collection = body.collection;
+	if (typeof body.path === 'string') path = body.path;
+	document = normaliseAnyDocument(body.document, site, site.collections[collection]!);
+} else if (Astro.request.method === 'GET') {
+	collection = Astro.url.searchParams.get('collection') ?? '';
+	path = Astro.url.searchParams.get('path') ?? '';
+	try {
+		document = (await store.read(collection, path)).document;
+	} catch (error) {
+		if (error instanceof DocumentError) return plain(error.code === 'not-found' ? 404 : 400, error.message);
+		throw error;
+	}
+} else {
+	return new Response('GET or POST.', { status: 405, headers: { Allow: 'GET, POST' } });
+}
+
+if (document.kind === 'settings') return plain(404, 'Site Settings has no page of its own.');
+setRenderSource(Astro.locals, await store.source());
+
+Astro.response.headers.set('Cache-Control', 'no-store');
+Astro.response.headers.set('X-Preview-Version', String(version));
+---
+
+<RenderDocument document={document as PageDocument} collection={collection} previewPath={path} preview />

package/src/editor/routes/publish.ts

@@ -0,0 +1,9 @@
+/**
+ * POST /_caracms/publish: Publish (Decision 10).
+ * Live mode only (M4 Phase 2); the handler is ../../live/editor.ts → `publish`. Shapes: ../types.ts.
+ */
+import { liveRoute } from './_live.ts';
+
+export const prerender = false;
+
+export const ALL = liveRoute('publish');

package/src/editor/routes/status.ts

@@ -0,0 +1,9 @@
+/**
+ * GET /_caracms/status?file=<open document's file>: the poll (Decision 13).
+ * Live mode only (M4 Phase 2); the handler is ../../live/editor.ts → `status`. Shapes: ../types.ts.
+ */
+import { liveRoute } from './_live.ts';
+
+export const prerender = false;
+
+export const ALL = liveRoute('status');

package/src/editor/routes/submissions.ts

@@ -0,0 +1,16 @@
+/**
+ * `/_caracms/submissions/*`: the inbox (M6 Decision 9). Both modes: in live mode the
+ * guard's prefix rule has checked the session and, for a POST, the origin; local mode
+ * has no sign-in and reads `.caracms/submissions/`. Every route and shape:
+ * ../../forms/inbox.ts.
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { handleSubmissions } from '../../forms/inbox.ts';
+import { personOf } from '../../live/locals.ts';
+import { editorMode } from '../server/mode.ts';
+
+export const prerender = false;
+
+export const ALL: APIRoute = ({ request, locals }) =>
+	handleSubmissions(request, { site, mode: editorMode().kind === 'live' ? 'live' : 'local', person: personOf(locals)?.email ?? null });

package/src/editor/routes/try-again.ts

@@ -0,0 +1,9 @@
+/**
+ * POST /_caracms/try-again: redeploy a failed publish through Railway (Decision 12).
+ * Live mode only (M4 Phase 2); the handler is ../../live/editor.ts → `tryAgain`. Shapes: ../types.ts.
+ */
+import { liveRoute } from './_live.ts';
+
+export const prerender = false;
+
+export const ALL = liveRoute('tryAgain');

package/src/editor/routes/write.ts

@@ -0,0 +1,18 @@
+/**
+ * POST /_caracms/write: `{ file, base, document }` → `{ ok, file, changed, mtimeMs, version }`,
+ * or `{ error, code? }` with 400/401/403/404/405/409/413/415/503. The logic, and why it's
+ * a security boundary, is in ../server/write.ts; the store is the mode's
+ * (server/mode.ts): the disk in local mode, the Redis autosave in live mode (M4
+ * Decision 4), where the request also carries `X-Caracms-Tab` (and
+ * `X-Caracms-Release: 1` on a closing tab's last write).
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import { personOf } from '../../live/locals.ts';
+import { editorStore } from '../server/mode.ts';
+import { handleWrite } from '../server/write.ts';
+
+export const prerender = false;
+
+/** POST, and every other method (405). */
+export const ALL: APIRoute = async ({ request, locals }) => handleWrite(request, await editorStore(site), { person: personOf(locals) });

package/src/editor/server/admin-props.ts

@@ -0,0 +1,151 @@
+/**
+ * What /admin server-renders from (and hydrates with): the site as the browser may
+ * see it, the document list, the open document as read now, and the per-browser
+ * sidebar state from the cookie (Decision 20).
+ */
+import { createHash } from 'node:crypto';
+import { relative } from 'node:path';
+import type { Brand, ResolvedSite } from '../../config.ts';
+import { DocumentError } from '../../content.ts';
+import { inboxFromAddress, refFromAddress } from '../addresses.ts';
+import { handleSubmissions, SUBMISSIONS_PREFIX, submissionsSetupQuick, type SubmissionResponse, type SubmissionsListResponse } from '../../forms/inbox.ts';
+import { ENDPOINTS, type AdminProps, type DocRef, type EditorSite, type ListedDocument, type LiveProps, type MediaSetup, type EditorForm, type Person, type StatusResponse } from '../types.ts';
+import { parseUiState, UI_COOKIE, unsentCookieName, withOpenAncestors, withRecent, withSide } from '../ui-state.ts';
+import type { DraftsStore } from './drafts-store.ts';
+import { editorMode, liveEditorOf } from './mode.ts';
+import { readImagesConfig, readMuxConfig } from './media/config.ts';
+import { currentBrand, editorBrand } from './settings.ts';
+import { withCards } from './cards.ts';
+
+/** Home: the top `index` of the first nested collection, else the first document that opens. */
+export function homeOf(site: Pick<ResolvedSite, 'collections'>, documents: readonly ListedDocument[]): DocRef {
+	for (const collection of Object.values(site.collections)) {
+		if (collection.nested && documents.some((d) => d.collection === collection.name && d.path === 'index' && !d.warning)) {
+			return { collection: collection.name, path: 'index' };
+		}
+	}
+	const first = documents.find((d) => !d.warning && d.kind === 'sections');
+	return first ? { collection: first.collection, path: first.path } : { collection: Object.keys(site.collections)[0]!, path: 'index' };
+}
+
+/**
+ * `brand`: the brand as it applies now (settings.ts → currentBrand: Site Settings as
+ * committed, M5a Decision 10).
+ */
+export function editorSite(site: ResolvedSite, documents: readonly ListedDocument[], host: string, brand: Brand): EditorSite {
+	// Every kind of collection (M5a Phase 5): the site's own in config order, then `shared` and `settings`.
+	const collections = Object.values(site.collections).map(({ name, label, kind, urlBase, nested, fields, columns, sort, view, blocks }) => ({ name, label, kind, urlBase, nested, fields, columns, sort: sort ?? null, view: view ?? null, blocks: blocks ?? null }));
+	return {
+		collections,
+		allCollections: collections,
+		blocks: Object.fromEntries(
+			Object.entries(site.blocks).map(([type, block]) => [type, { ...block, component: relative(site.root, block.component).split('\\').join('/') }]),
+		),
+		textStyles: Object.fromEntries(
+			Object.values(site.textStyles).map((style) => [style.name, { name: style.name, sizePx: style.sizePx, minSizePx: style.minSizePx }]),
+		),
+		brand: editorBrand(brand),
+		phoneLinesWidth: site.phoneLinesWidth,
+		home: homeOf(site, documents),
+		host,
+		storageKey: createHash('sha256').update(site.root).digest('base64url').slice(0, 10),
+		timeZone: site.timeZone,
+		codeRoutes: site.codeRoutes ?? [],
+	};
+}
+
+export type AdminPropsResult = { ok: true; props: AdminProps } | { ok: false; status: number; message: string };
+
+export async function adminProps(input: {
+	site: ResolvedSite;
+	store: DraftsStore;
+	url: URL;
+	/** Read a cookie by name (Astro.cookies). */
+	cookie: (name: string) => string | undefined;
+	/** Live mode: the signed-in person (the guard's, locals.ts). Absent or null in local mode. */
+	person?: Person | null;
+}): Promise<AdminPropsResult> {
+	const { site, store, url } = input;
+	const documents = withCards(site, await store.list());
+	const editor = editorSite(site, documents, url.host, await currentBrand(site));
+	// M6 Decision 9: /admin/submissions[/<id>] opens the editor on the inbox, over Home.
+	const inbox = inboxFromAddress(url.pathname);
+	if (inbox === 'bad') return { ok: false, status: 404, message: `There's no submission at ${url.pathname}.` };
+	const ref = inbox ? editor.home : refFromAddress(url.pathname, editor.collections.map((c) => c.name), editor.home);
+	if (!ref) return { ok: false, status: 404, message: `There's no document at ${url.pathname}.` };
+	try {
+		const opened = await store.read(ref.collection, ref.path);
+		// A hidden sidebar stays hidden only for a section-builder page; any other kind of
+		// document is edited in the sidebar, so it paints shown (the client's bringSideBack).
+		const painted = withRecent(withOpenAncestors(parseUiState(input.cookie(UI_COOKIE)), ref), ref);
+		const ui = opened.entry.kind === 'sections' ? painted : withSide(painted, false);
+		const unsent = input.cookie(unsentCookieName(editor.storageKey)) === '1';
+		const live = await liveProps(site, url, opened.entry.file, input.person ?? null);
+		const submissions = await submissionsSetupQuick({ site });
+		// The inbox's first page (and the submission the address names) in the first paint: no empty list that fills in.
+		const inboxFirst = inbox && submissions.unread !== null ? await inboxFirstPaint(site, url, inbox.id, input.person ?? null) : null;
+		return { ok: true, props: { site: editor, documents, opened, ui, unsent, live, media: mediaSetup(), inbox, submissions, forms: formsOf(site), inboxFirst } };
+	} catch (error) {
+		if (error instanceof DocumentError) return { ok: false, status: error.code === 'not-found' ? 404 : 400, message: error.message };
+		throw error;
+	}
+}
+
+/**
+ * Live mode's start for the page (M4 Phase 4): who is signed in and the status as the
+ * poll would answer it, so the bar's waiting count, Publish, the avatar and a lock's
+ * veil are in the first paint (no skeletons). Read with no tab, so presence isn't
+ * recorded and a lock of your own reads as another tab's until the tab's first poll.
+ * Null in local mode.
+ */
+async function liveProps(site: ResolvedSite, url: URL, file: string, person: Person | null): Promise<LiveProps | null> {
+	const mode = editorMode();
+	if (mode.kind !== 'live' || !person) return null;
+	let status: StatusResponse | null = null;
+	try {
+		const live = await liveEditorOf(site);
+		const response = await live!.status(new Request(`${url.origin}${ENDPOINTS.status}?file=${encodeURIComponent(file)}`), person);
+		if (response.ok) status = (await response.json()) as StatusResponse;
+	} catch (error) {
+		console.warn(`[caracms] /admin couldn't read the status for its first paint (${error instanceof Error ? error.message : String(error)}); the first poll fills it`);
+	}
+	return { you: person, status, pollMs: mode.settings.timings.pollMs };
+}
+
+/**
+ * M6: what /admin/submissions[/<id>] paints first, read through the inbox's own handler
+ * (so the same checks run): the first page, and the submission the address names. A read
+ * that fails leaves its part null, and the browser reads it again.
+ */
+async function inboxFirstPaint(site: ResolvedSite, url: URL, id: string | null, person: Person | null): Promise<NonNullable<AdminProps['inboxFirst']>> {
+	const ctx = { site, mode: editorMode().kind === 'live' ? ('live' as const) : ('local' as const), person: person?.email ?? null };
+	const read = async <T,>(path: string): Promise<T | null> => {
+		try {
+			const response = await handleSubmissions(new Request(`${url.origin}${SUBMISSIONS_PREFIX}${path}`), ctx);
+			return response.ok ? ((await response.json()) as T) : null;
+		} catch {
+			return null;
+		}
+	};
+	const [list, open] = await Promise.all([read<SubmissionsListResponse>(''), id ? read<SubmissionResponse>(`/${encodeURIComponent(id)}`) : Promise.resolve(null)]);
+	return { list, open };
+}
+
+/** M6: the site's forms as the editor needs them (Site Settings' Form emails, the Form block's picker): id, label and fields. */
+export function formsOf(site: Pick<ResolvedSite, 'forms'>): EditorForm[] {
+	return Object.values(site.forms).map(({ id, label, fields }) => ({ id, label, fields }));
+}
+
+/**
+ * M5b Decision 5: whether the media routes are set up, for the media field's first paint
+ * (the 503's sentence in place of its controls). Only the sentence and the missing names
+ * reach the browser, never a value.
+ */
+export function mediaSetup(): MediaSetup {
+	const images = readImagesConfig();
+	const clips = readMuxConfig();
+	return {
+		images: images.kind === 'unset' ? { error: images.message, code: 'media-unset', missing: images.missing } : null,
+		clips: clips.kind === 'unset' ? { error: clips.message, code: 'mux-unset', missing: clips.missing } : null,
+	};
+}