caracms 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,434 @@
+/**
+ * The caracms integration.
+ *
+ * ## How the package loads the site (Decision 3; for Phase 2's builder)
+ *
+ * The package can't import the site, so the site hands itself over:
+ *
+ * 1. The site's `caracms.config.ts` is plain data (`defineSite`, from
+ *    `caracms/config`): field descriptors, and components named by path. Its
+ *    `astro.config.mjs` imports it and passes it in: `caracms(site)`.
+ * 2. In `astro:config:setup`, before the dev server or the build starts, the
+ *    integration validates it and resolves its paths (`resolveSite`); a bad config
+ *    throws a plain sentence and stops `astro dev` / `astro build`.
+ * 3. A Vite plugin serves four virtual modules from the resolved config. They work
+ *    the same in dev, in the build and in tests (Vite's container renders), and any
+ *    module, including routes the package injects, can import them:
+ *
+ *    - `virtual:caracms/config`     `{ site }`: the ResolvedSite as JSON (collections,
+ *                                   block schemas, text styles, brand slots,
+ *                                   phoneLinesWidth, absolute paths). No components.
+ *    - `virtual:caracms/blocks`     `{ blocks }`: block type → its Astro component,
+ *                                   imported by absolute path.
+ *    - `virtual:caracms/page`       `{ Page }`: the site's page component.
+ *    - `virtual:caracms/collections` `{ components }`: a list-of-fields collection's
+ *                                   name → its component (M5a Decision 7).
+ *    - `virtual:caracms/lockup.css` the lockup CSS with the site's phone-lines
+ *                                   width in its media query (lockup-css.ts).
+ *
+ *    They're split so nothing imports in a circle: a block's Lockup imports
+ *    `config`; the Blocks loop imports `blocks`; only RenderDocument imports `page`.
+ *    Types: `caracms/virtual` (src/virtual.d.ts), injected into the site's
+ *    `.astro/types.d.ts` by `injectTypes`.
+ * 4. Fonts: every text style's web font is registered with Astro's fonts API from
+ *    the style (`font-display: block`, Decision 14), so one definition drives the
+ *    CSS and the measurement. A page puts `<Fonts />` in its head.
+ *
+ * Tree-shaking: the public side is `config`, `blocks` and the package's components;
+ * nothing here imports editor code.
+ *
+ * ## The editor (Phase 2; src/editor/README.md)
+ *
+ * The integration injects the editor's routes (EDITOR_ROUTES: /admin, the preview,
+ * document and write routes, and M4's live-mode routes, all on demand) in dev and in
+ * the build (M4 Decision 1, reversing M3 Decision 4), with the editor's middleware.
+ * Under `astro dev` only, it also takes the collection folders out of Vite's watch
+ * (Decision 5) and has Vite pre-bundle the editor's browser deps. The public pages
+ * have no script, no React and no editor markers in either.
+ */
+import type { AstroIntegration } from 'astro';
+import { fontProviders } from 'astro/config';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { isAbsolute, join, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolveSite, SITE_SETTINGS_FILE, type ResolvedSite, type SiteConfig } from './config.ts';
+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 { GUARD_MIDDLEWARE, LOGIN_ROUTES } from './live/auth/routes.ts';
+
+
+export type { SiteConfig, ResolvedSite } from './config.ts';
+
+const VIRTUAL = {
+	config: 'virtual:caracms/config',
+	public: 'virtual:caracms/public',
+	blocks: 'virtual:caracms/blocks',
+	page: 'virtual:caracms/page',
+	collections: 'virtual:caracms/collections',
+	css: 'virtual:caracms/lockup.css',
+} as const;
+
+const resolvedId = (id: string) => `\0${id}`;
+
+/**
+ * What the public site's components learn at build time (M6): the site's address
+ * (`SITE_URL`, Decision 3), Turnstile's site key (read at build, Decision 6), and whether
+ * this is a production build (the Google tag goes only there, Decision 16).
+ */
+export interface PublicBuild {
+	/** Astro's `site` as it applies (the site's own, else `SITE_URL`), without a trailing slash; null when neither is set. */
+	siteUrl: string | null;
+	turnstileSiteKey: string | null;
+	/** `astro build` (and the built server), not `astro dev`. */
+	production: boolean;
+}
+
+/** The virtual modules' source, from a resolved site. Exported for tests. */
+export function virtualModules(site: ResolvedSite, build: PublicBuild = { siteUrl: null, turnstileSiteKey: null, production: false }): Record<string, string> {
+	const blockEntries = Object.values(site.blocks);
+	const fieldsCollections = Object.values(site.collections).filter((c) => c.kind === 'fields' && c.component);
+	return {
+		[VIRTUAL.config]: `export const site = ${JSON.stringify(site)};\n`,
+		[VIRTUAL.public]: `export const build = ${JSON.stringify(build)};\n`,
+		[VIRTUAL.blocks]:
+			blockEntries.map((b, i) => `import Block${i} from ${JSON.stringify(b.component)};`).join('\n') +
+			`\nexport const blocks = {${blockEntries.map((b, i) => `${JSON.stringify(b.type)}: Block${i}`).join(', ')}};\n`,
+		[VIRTUAL.page]: `import Page from ${JSON.stringify(site.page)};\nexport { Page };\n`,
+		[VIRTUAL.collections]:
+			fieldsCollections.map((c, i) => `import Collection${i} from ${JSON.stringify(c.component)};`).join('\n') +
+			`\nexport const components = {${fieldsCollections.map((c, i) => `${JSON.stringify(c.name)}: Collection${i}`).join(', ')}};\n`,
+		[VIRTUAL.css]: lockupCss(site.phoneLinesWidth),
+	};
+}
+
+/**
+ * The editor's routes, each on demand. M3 injected them under `astro dev` only; M4
+ * Decision 1 reverses that: they're in the build too, and the mode (local, live or
+ * unconfigured) is read at run time. The public pages still ship no script, no
+ * React and no markers. See editor/README.md for what each takes.
+ */
+export const EDITOR_ROUTES = [
+	{ pattern: '/admin/[...path]', entrypoint: 'editor/routes/admin.astro' },
+	{ pattern: '/_caracms/preview', entrypoint: 'editor/routes/preview.astro' },
+	{ pattern: '/_caracms/document', entrypoint: 'editor/routes/document.ts' },
+	{ pattern: '/_caracms/documents', entrypoint: 'editor/routes/documents.ts' },
+	{ pattern: '/_caracms/write', entrypoint: 'editor/routes/write.ts' },
+	// M5a Phase 3: creating and deleting documents, both modes (the guard's prefix rule covers them in live mode).
+	{ pattern: '/_caracms/create', entrypoint: 'editor/routes/create.ts' },
+	{ 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' },
+	// 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).
+	{ pattern: '/_caracms/github', entrypoint: 'editor/routes/github.ts' },
+	// M4 Phase 2, live mode (local mode: 404): the poll, locks, Publish, history, Try again, notices.
+	{ pattern: '/_caracms/status', entrypoint: 'editor/routes/status.ts' },
+	{ pattern: '/_caracms/lock', entrypoint: 'editor/routes/lock.ts' },
+	{ pattern: '/_caracms/publish', entrypoint: 'editor/routes/publish.ts' },
+	{ pattern: '/_caracms/history', entrypoint: 'editor/routes/history.ts' },
+	{ pattern: '/_caracms/try-again', entrypoint: 'editor/routes/try-again.ts' },
+	{ pattern: '/_caracms/notice', entrypoint: 'editor/routes/notice.ts' },
+	// M6 Decision 9: the inbox, both modes (the guard's prefix rule covers it in live mode).
+	{ pattern: '/_caracms/submissions/[...path]', entrypoint: 'editor/routes/submissions.ts' },
+] as const;
+
+/**
+ * The public site's own on-demand routes (M6): the forms' endpoint, public in every mode
+ * (the guard lets it through, the unconfigured 503 exempts it); and (M6c Decision 6) the
+ * library's files at `/files/<hash>/<name>.<ext>`, every path under `/files` reaching the
+ * route's own allow-list (files-route.ts), behind the pre-launch password like any page.
+ */
+export const PUBLIC_ROUTES = [
+	{ pattern: '/_caracms/form', entrypoint: 'forms/route.ts' },
+	{ pattern: '/files/[...path]', entrypoint: 'files-route.ts' },
+] as const;
+
+/** M6 Decision 12: the sitemap, prerendered, injected only when the site's address is known at build. */
+export const SITEMAP_ROUTE = { pattern: '/sitemap.xml', entrypoint: 'components/sitemap.xml.ts' } as const;
+
+/**
+ * M6 Decision 3: the site's public address. Astro's `site` when the site's config sets
+ * one, else `SITE_URL`; null when neither does (no sitemap, no canonical, a warning).
+ * `SITE_URL` must be an http(s) origin, optionally with a path.
+ */
+export function siteAddress(astroSite: string | undefined, env: Record<string, string | undefined> = process.env): { url: string | null; problem: string | null } {
+	const raw = astroSite ?? env['SITE_URL']?.trim();
+	if (!raw) return { url: null, problem: null };
+	let url: URL;
+	try {
+		url = new URL(raw);
+	} catch {
+		return { url: null, problem: `SITE_URL must be the site's address, like https://fernhill.ie (got "${raw}").` };
+	}
+	if (url.protocol !== 'https:' && url.protocol !== 'http:') return { url: null, problem: `SITE_URL must start with https:// (got "${raw}").` };
+	return { url: `${url.origin}${url.pathname}`.replace(/\/+$/, ''), problem: null };
+}
+
+/** Pre-M7 item 8: Site Settings' redirects, served as 301s on the public site. */
+export const REDIRECT_MIDDLEWARE = 'redirect-middleware.ts';
+
+/** M4 Phase 2: the unconfigured server's 503, registered before Phase 3's guard. */
+export const EDITOR_MIDDLEWARE = 'editor/middleware.ts';
+
+/**
+ * Content files out of Vite's watch (Decision 5): a write never reloads `/admin`
+ * or the preview. One matcher per declared collection folder, and one for the Site
+ * Settings file (M4 Decision 15), which sits in `content/` beside them. M6: and the
+ * local submissions folder (`.caracms/`), so a form post or marking one read doesn't
+ * reload the editor.
+ */
+export function contentWatchIgnores(site: Pick<ResolvedSite, 'collections' | 'root'>): ((path: string) => boolean)[] {
+	const settings = join(site.root, SITE_SETTINGS_FILE);
+	const local = join(site.root, '.caracms');
+	return [
+		// Every collection's folder, shared blocks' included; Site Settings is one file, matched below.
+		...Object.values(site.collections)
+			.filter((c) => c.kind !== 'settings')
+			.map(({ dir }) => (path: string) => path === dir || path.startsWith(dir + sep)),
+		(path: string) => path === settings,
+		(path: string) => path === local || path.startsWith(local + sep),
+	];
+}
+
+/**
+ * The hosts Astro may take a request's address from (`security.allowedDomains`).
+ * Without them, Astro ignores the Host header and every request reads as
+ * `localhost:<port>`. Behind Railway's edge that breaks the same-origin checks on the
+ * sign-in form and the editor's writes, and the addresses the pages show. Taken from
+ * Astro's `site`, then Railway's public domain: the same sources as emailed links
+ * (live/auth/index.ts → `publicOrigin`). A site's own `allowedDomains` wins.
+ * Read at build time: Astro puts the list in the server's manifest.
+ */
+export function trustedDomains(
+	astroSite: string | undefined,
+	own: readonly unknown[] | undefined,
+	env: Record<string, string | undefined> = process.env,
+): { hostname: string; protocol: string }[] {
+	if (own?.length) return [];
+	const domains: { hostname: string; protocol: string }[] = [];
+	if (astroSite) {
+		const url = new URL(astroSite);
+		domains.push({ hostname: url.hostname, protocol: url.protocol.replace(':', '') });
+	}
+	const railway = env['RAILWAY_PUBLIC_DOMAIN']?.trim();
+	if (railway && !domains.some((d) => d.hostname === railway)) domains.push({ hostname: railway, protocol: 'https' });
+	return domains;
+}
+
+/**
+ * The browser side of the editor imports React and idiomorph from the package.
+ * Pre-bundled up front (dev only), so Vite doesn't discover them on the first
+ * visit to /admin and reload the page to optimise them (a flicker, M2 Decision 9).
+ */
+/** Vite's cache for every command but `astro dev`, apart from dev's `node_modules/.vite` (see its use). Relative to the site's root. */
+export const BUILD_VITE_CACHE = 'node_modules/.vite-caracms-build';
+
+export const EDITOR_CLIENT_DEPS = [
+	'caracms > react',
+	'caracms > react/jsx-runtime',
+	'caracms > react/jsx-dev-runtime',
+	'caracms > react-dom/client',
+	'caracms > idiomorph',
+	// M5a: the rich-text field's editor (Tiptap on ProseMirror), browser only.
+	'caracms > @tiptap/core',
+	'caracms > @tiptap/pm/history',
+	'caracms > @tiptap/pm/model',
+	// The on-page editor's: left out, Vite finds them on the first /admin, optimizes again
+	// and reloads the page under whoever is on it (a browser test, mid-click).
+	'caracms > @tiptap/pm/state',
+	'caracms > @tiptap/pm/transform',
+	'caracms > @tiptap/pm/view',
+	// M5b: a clip's upload straight to Mux, imported on the first one (client/media/store.ts).
+	'caracms > @mux/upchunk',
+	// The date field's calendar (pre-M7 polish).
+	'caracms > react-day-picker',
+];
+
+/**
+ * The variables M5b Decision 5 names: the media pipeline's and Mux's. Only these are
+ * taken from the site's env files (copyMediaEnv); everything else in `.env` (the
+ * GitHub App, live mode) is left to the process's own environment, as before.
+ */
+export const MEDIA_ENV_NAMES = [
+	'CARACMS_MEDIA',
+	'CARACMS_MEDIA_URL',
+	'IMGPROXY_KEY',
+	'IMGPROXY_SALT',
+	'S3_ENDPOINT',
+	'S3_REGION',
+	'S3_BUCKET',
+	'S3_ACCESS_KEY_ID',
+	'S3_SECRET_ACCESS_KEY',
+	'MUX_TOKEN_ID',
+	'MUX_TOKEN_SECRET',
+] as const;
+
+/**
+ * M6's variables a local run may take from the site's `.env` too: the site's address,
+ * Turnstile's keys, and the tests' submissions store. Copied the same way (a set value wins).
+ */
+export const SITE_ENV_NAMES = ['SITE_URL', 'TURNSTILE_SITE_KEY', 'TURNSTILE_SECRET_KEY', 'CARACMS_SUBMISSIONS'] as const;
+
+/**
+ * Copy Decision 5's variables from the env files' values (`loaded`, Vite's loadEnv) into
+ * `env`, **never over a value already set**: a real environment (Railway) and a test's
+ * `CARACMS_MEDIA=memory` always win. Other names are ignored. Returns the names copied.
+ */
+export function copyMediaEnv(loaded: Record<string, string | undefined>, env: Record<string, string | undefined> = process.env, names: readonly string[] = MEDIA_ENV_NAMES): string[] {
+	const copied: string[] = [];
+	for (const name of names) {
+		const value = loaded[name];
+		if (value === undefined || value === '' || (env[name] !== undefined && env[name] !== '')) continue;
+		env[name] = value;
+		copied.push(name);
+	}
+	return copied;
+}
+
+/** The site's env files (`.env`, `.env.<mode>`, `.local` variants) through Vite's loadEnv, resolved from Astro's own Vite. */
+async function loadSiteEnv(mode: string, root: string): Promise<Record<string, string>> {
+	const vite = createRequire(createRequire(import.meta.url).resolve('astro/package.json')).resolve('vite');
+	// A native import, out of Vite's reach. Installed from npm, this module is compiled by the Vite runner that
+	// loaded astro.config, which rewrites `import()` to go through it, and Astro has closed it before the hooks run
+	// ("Vite module runner has been closed"; found by M8's pack-and-install check).
+	const nativeImport = new Function('url', 'return import(url)') as (url: string) => Promise<unknown>;
+	const { loadEnv } = (await nativeImport(pathToFileURL(vite).href)) as { loadEnv: (mode: string, dir: string, prefixes: string | string[]) => Record<string, string> };
+	return loadEnv(mode, root, '');
+}
+
+export default function caracms(config: SiteConfig): AstroIntegration {
+	let site: ResolvedSite;
+	return {
+		name: 'caracms',
+		hooks: {
+			'astro:config:setup': async ({ command, config: astroConfig, updateConfig, injectRoute, addMiddleware, addWatchFile, logger }) => {
+				site = resolveSite(config, fileURLToPath(astroConfig.root));
+				// A change to the site's caracms.config restarts the dev server, as one to astro.config does: the config
+				// is read once, here, and a new block would otherwise stay "Unknown block" until a hand restart.
+				// (A restart also regenerates schemas/, in astro:server:setup.) Only the config file itself: Astro's
+				// addWatchFile doesn't follow what it imports.
+				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));
+				// 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);
+				copyMediaEnv(siteEnv);
+				copyMediaEnv(siteEnv, process.env, SITE_ENV_NAMES);
+				const dev = command === 'dev';
+				// M6 Decision 3: SITE_URL is Astro's `site` unless the site's config sets one.
+				const address = siteAddress(astroConfig.site);
+				if (address.problem) throw new Error(`caracms: ${address.problem}`);
+				if (command === 'build' && !address.url) logger.warn('SITE_URL is not set, so this build has no sitemap and its pages have no canonical link or og:url. Set it to the site\'s public address.');
+				const modules = virtualModules(site, { siteUrl: address.url, turnstileSiteKey: process.env.TURNSTILE_SITE_KEY?.trim() || null, production: !dev });
+				// M4 Decision 1: the editor's routes in dev and in the build alike; the mode is read at run time (editor/server/mode.ts).
+				{
+					for (const route of [...EDITOR_ROUTES, ...PUBLIC_ROUTES]) {
+						injectRoute({ pattern: route.pattern, entrypoint: new URL(`./${route.entrypoint}`, import.meta.url), prerender: false });
+					}
+					// M6 Decision 12: the sitemap, only with an address to put in it.
+					if (address.url) injectRoute({ pattern: SITEMAP_ROUTE.pattern, entrypoint: new URL(`./${SITEMAP_ROUTE.entrypoint}`, import.meta.url), prerender: true });
+					// M4 Phase 3: the sign-in pages (live/auth/routes.ts).
+					for (const route of LOGIN_ROUTES) injectRoute({ pattern: route.pattern, entrypoint: new URL(`./${route.entrypoint}`, import.meta.url), prerender: false });
+					// M4 Phase 2: an unconfigured production server's 503 on /admin and /_caracms/*. First, so it runs before the guard.
+					addMiddleware({ order: 'pre', entrypoint: new URL(`./${EDITOR_MIDDLEWARE}`, import.meta.url) });
+					// M4 Phase 3: the sign-in guard on /admin and /_caracms/ (live mode only). Must stay after the 503 middleware.
+					addMiddleware({ order: 'pre', entrypoint: new URL(`./${GUARD_MIDDLEWARE}`, import.meta.url) });
+					// Pre-M7 item 8: Site Settings' redirects, as 301s, for a public path that would be a 404.
+					addMiddleware({ order: 'pre', entrypoint: new URL(`./${REDIRECT_MIDDLEWARE}`, import.meta.url) });
+				}
+
+				const fontsFromStyles = Object.values(site.textStyles).map((style) => ({
+					provider: fontProviders.local(),
+					name: style.family,
+					cssVariable: style.cssVariable,
+					fallbacks: style.fallbacks ?? ['sans-serif'],
+					optimizedFallbacks: true,
+					// Decision 14: block, never a fallback that could make a line overflow (M1 → E6).
+					display: 'block' as const,
+					options: {
+						variants: [
+							{
+								src: [isAbsolute(style.fontFile.web) ? style.fontFile.web : `./${style.fontFile.web}`],
+								weight: style.weightRange,
+								style: 'normal' as const,
+							},
+						],
+					},
+				}));
+
+				// measure.ts loads harfbuzzjs from here at runtime (see its comment).
+				const harfbuzz = pathToFileURL(createRequire(import.meta.url).resolve('harfbuzzjs')).href;
+
+				const domains = trustedDomains(astroConfig.site ?? address.url ?? undefined, astroConfig.security?.allowedDomains);
+				if (command === 'build' && !astroConfig.security?.allowedDomains?.length) {
+					if (domains.length) logger.info(`trusting the Host header for ${domains.map((d) => d.hostname).join(', ')}`);
+					else logger.warn("the site's public address isn't known (set Astro's `site`, or build on Railway): behind a proxy, sign-in and the editor's saves will be refused as cross-origin.");
+				}
+
+				updateConfig({
+					...(!astroConfig.site && address.url ? { site: address.url } : {}),
+					fonts: fontsFromStyles,
+					...(domains.length ? { security: { allowedDomains: domains } } : {}),
+					vite: {
+						// __CARACMS_PRODUCTION__: a production server is the build, so it's always live mode (M4 Decision 1; editor/server/mode.ts).
+						// __CARACMS_TOKENS_CSS__: editor/brand.ts reads its inks from tokens.css, which isn't beside the bundled chunk.
+						define: {
+							__CARACMS_HARFBUZZ__: JSON.stringify(harfbuzz),
+							__CARACMS_PRODUCTION__: JSON.stringify(!dev),
+							__CARACMS_TOKENS_CSS__: JSON.stringify(readFileSync(new URL('./editor/styles/tokens.css', import.meta.url), 'utf8')),
+						},
+						// Installed from npm, the package ships TypeScript and .astro source.
+						ssr: { noExternal: ['caracms'] },
+						...(dev
+							? {
+									server: { watch: { ignored: contentWatchIgnores(site) } },
+									optimizeDeps: { include: EDITOR_CLIENT_DEPS },
+								}
+							: {
+									// M8 review: `astro build` (and `astro sync`, `astro check`) starts a Vite server of its own, whose
+									// config differs from dev's, so Vite re-optimizes into the shared node_modules/.vite and deletes the
+									// running dev server's deps (react, idiomorph, the site's own): the editor and its preview answer 504
+									// "Outdated Optimize Dep" until dev restarts. Anything but dev keeps its cache apart.
+									cacheDir: BUILD_VITE_CACHE,
+								}),
+						plugins: [
+							{
+								name: 'caracms:virtual',
+								resolveId(id) {
+									return id in modules ? resolvedId(id) : undefined;
+								},
+								load(id) {
+									if (!id.startsWith('\0virtual:caracms/')) return undefined;
+									return modules[id.slice(1)];
+								},
+							},
+						],
+					},
+				});
+			},
+			// M8 Decision 14: a dev server (at start, and on the restart a config change makes) regenerates
+			// schemas/ from the config. Never content files: a dev run only changes what your code change derives.
+			'astro:server:setup': ({ logger }) => {
+				try {
+					const changed = writeSchemaFiles(site);
+					if (changed.length) logger.info(`updated ${changed.map((c) => c.file).join(', ')}`);
+				} catch (error) {
+					logger.warn(`couldn't write schemas/: ${(error as Error).message}`);
+				}
+			},
+			// Posts and tags, Decision 15: a production build reads each document once (read.ts). Never in dev.
+			'astro:build:start': () => shareBuildReads(true),
+			'astro:build:done': () => shareBuildReads(false),
+			'astro:config:done': ({ injectTypes }) => {
+				injectTypes({ filename: 'caracms.d.ts', content: '/// <reference types="caracms/virtual" />\n' });
+			},
+		},
+	};
+}

package/src/json-source.ts

@@ -0,0 +1,116 @@
+/**
+ * A JSON parser that remembers where every value sits in the source text, so the
+ * serializer can copy untouched values back byte for byte (Decision 7).
+ *
+ * Validity is JSON.parse's: the text is checked with it first, so error messages
+ * are the platform's and nothing this parser accepts is invalid JSON.
+ */
+
+export type JsonNode = ObjectNode | ArrayNode | ScalarNode;
+
+interface Span {
+	/** Offset of the value's first character. */
+	start: number;
+	/** Offset just past its last character. */
+	end: number;
+}
+
+export interface ObjectNode extends Span {
+	kind: 'object';
+	members: MemberNode[];
+}
+
+export interface MemberNode {
+	key: string;
+	value: JsonNode;
+}
+
+export interface ArrayNode extends Span {
+	kind: 'array';
+	items: JsonNode[];
+}
+
+export interface ScalarNode extends Span {
+	kind: 'scalar';
+	value: string | number | boolean | null;
+}
+
+export interface ParsedSource {
+	text: string;
+	root: JsonNode;
+	/** The plain value, as JSON.parse gives it. */
+	value: unknown;
+}
+
+export function parseSource(text: string): ParsedSource {
+	const value = JSON.parse(text);
+	let i = 0;
+
+	const ws = () => {
+		while (i < text.length && (text[i] === ' ' || text[i] === '\n' || text[i] === '\r' || text[i] === '\t')) i++;
+	};
+
+	const string = (): string => {
+		const start = i;
+		i++; // opening quote
+		while (text[i] !== '"') i += text[i] === '\\' ? 2 : 1;
+		i++; // closing quote
+		return JSON.parse(text.slice(start, i)) as string;
+	};
+
+	const node = (): JsonNode => {
+		ws();
+		const start = i;
+		const c = text[i];
+		if (c === '{') {
+			i++;
+			const members: MemberNode[] = [];
+			ws();
+			if (text[i] === '}') {
+				i++;
+				return { kind: 'object', start, end: i, members };
+			}
+			for (;;) {
+				ws();
+				const key = string();
+				ws();
+				i++; // ':'
+				members.push({ key, value: node() });
+				ws();
+				if (text[i++] === '}') return { kind: 'object', start, end: i, members };
+			}
+		}
+		if (c === '[') {
+			i++;
+			const items: JsonNode[] = [];
+			ws();
+			if (text[i] === ']') {
+				i++;
+				return { kind: 'array', start, end: i, items };
+			}
+			for (;;) {
+				items.push(node());
+				ws();
+				if (text[i++] === ']') return { kind: 'array', start, end: i, items };
+			}
+		}
+		if (c === '"') {
+			const s = string();
+			return { kind: 'scalar', start, end: i, value: s };
+		}
+		// number, true, false, null
+		while (i < text.length && !/[\s,\]}]/.test(text[i]!)) i++;
+		return { kind: 'scalar', start, end: i, value: JSON.parse(text.slice(start, i)) };
+	};
+
+	const root = node();
+	return { text, root, value };
+}
+
+/** The last member with this key (JSON.parse's rule for duplicate keys). */
+export function member(node: ObjectNode, key: string): MemberNode | undefined {
+	for (let k = node.members.length - 1; k >= 0; k--) if (node.members[k]!.key === key) return node.members[k];
+	return undefined;
+}
+
+export const slice = (source: ParsedSource, node: JsonNode) => source.text.slice(node.start, node.end);

package/src/links.ts

@@ -0,0 +1,121 @@
+/**
+ * The one link rule (M5a Decision 4), lifted from the template
+ * (`tina-astro-template/src/lib/links.ts` → `validateLink`). The editor's link
+ * inputs and the render both import it, so a link the field flags is exactly a
+ * link the page shows as plain text.
+ *
+ * Browser-safe: no node imports.
+ *
+ *   validateLink(value)            the rule's message, or undefined (blank passes)
+ *   isLinkHref(value)              true when the value is a usable href: non-blank and passes
+ *   missingLinkTarget(href, urls)  "Links to /contact, which no page or route serves", or undefined
+ *
+ * Anything that fails the rule is kept as typed, with the message on the field,
+ * and renders as plain text (Decision 15).
+ */
+
+const RELATIVE_PATH = /^\/(?!\/)\S*$/;
+const ABSOLUTE_URL = /^https?:\/\/\S+$/;
+const MAILTO = /^mailto:[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const TEL = /^tel:\+?[0-9][0-9\s().-]*$/;
+/**
+ * A fragment: `#` alone (the top of the page, a placeholder link), or `#` then an HTML
+ * id (any characters but spaces, HTML's own rule for an id).
+ */
+const ANCHOR = /^#\S*$/;
+
+/** The rule's message: what the field says under a link that fails it. */
+export const LINK_RULE_MESSAGE =
+	'Enter a path starting with "/" (e.g. /contact), a full https:// URL, mailto:someone@example.com, tel:+353210000000, or an anchor on the page (#contact, or # alone).';
+
+/**
+ * The link rule: a `/path`, an `http(s)://` URL, `mailto:`, `tel:`, or a fragment (`#`, `#anchor`).
+ * Blank passes (an empty link is a different matter: it shows nothing). Returns
+ * the rule's message, or undefined when the value passes.
+ */
+export function validateLink(value: unknown): string | undefined {
+	if (typeof value !== 'string' || value.trim() === '') return undefined;
+	const candidate = value.trim();
+	if (RELATIVE_PATH.test(candidate) || ABSOLUTE_URL.test(candidate) || MAILTO.test(candidate) || TEL.test(candidate) || ANCHOR.test(candidate)) {
+		return undefined;
+	}
+	return LINK_RULE_MESSAGE;
+}
+
+/** A usable href: a non-blank string that passes the rule. What the render checks before writing `<a href>`. */
+export function isLinkHref(value: unknown): value is string {
+	return typeof value === 'string' && value.trim() !== '' && validateLink(value) === undefined;
+}
+
+/**
+ * The site path an internal link points at, for comparing with documents'
+ * addresses: `/contact/?x#y` → `/contact`. Null for anything that isn't checked:
+ * not a `/path`, or a path to a file (an extension in its last part, such as
+ * `/brochure.pdf`, a file in `public/`).
+ */
+export function internalLinkPath(href: unknown): string | null {
+	if (typeof href !== 'string') return null;
+	const candidate = href.trim();
+	if (!RELATIVE_PATH.test(candidate)) return null;
+	let path = candidate.replace(/[?#].*$/, '');
+	const last = path.split('/').pop() ?? '';
+	if (/\.[A-Za-z0-9]+$/.test(last)) return null;
+	path = normaliseAddress(path);
+	return path;
+}
+
+/** `/services/branding/` → `/services/branding`; `/` stays `/`. */
+export function normaliseAddress(url: string): string {
+	const trimmed = url.replace(/\/+$/, '');
+	return trimmed === '' ? '/' : trimmed;
+}
+
+/**
+ * Decision 4's warning: a `/path` with no file extension that matches no
+ * document. `addresses` are the site's documents' URLs (DocumentEntry.url:
+ * `/`, `/about`, `/journal/my-first-post`), from the store's listing (Phase 2
+ * wires it). Never an error: a warning the field shows.
+ */
+/** M9 Decision 7: the hidden pages in a listing, as `WarningContext.hiddenPages` takes them (address → name). */
+export function hiddenPages(entries: Iterable<{ url: string | null; label: string; hidden?: true }>): Map<string, string> {
+	const out = new Map<string, string>();
+	for (const e of entries) if (e.hidden && e.url !== null) out.set(normaliseAddress(e.url), e.label);
+	return out;
+}
+
+/** M9 Decision 7: the hidden documents in a listing, as `WarningContext.hiddenDocuments` takes them (`collection/path` → name and address). */
+export function hiddenDocuments(entries: Iterable<{ collection: string; path: string; url: string | null; label: string; hidden?: true }>): Map<string, { label: string; url: string | null }> {
+	const out = new Map<string, { label: string; url: string | null }>();
+	for (const e of entries) if (e.hidden) out.set(`${e.collection}/${e.path}`, { label: e.label, url: e.url === null ? null : normaliseAddress(e.url) });
+	return out;
+}
+
+/**
+ * M9 Decision 7's warning for a reference (a `reference()` field) to a hidden page, worded as
+ * the link one is. Never an error: unhiding the page fixes it.
+ */
+export function hiddenReferenceTarget(collection: string, path: string, hidden: ReadonlyMap<string, { label: string; url: string | null }>): string | undefined {
+	const doc = hidden.get(`${collection}/${path}`);
+	if (!doc) return undefined;
+	return `Points at ${doc.url ?? path}, the ${doc.label || path} page, which is hidden from the site. Visitors get its 404 until it's shown again.`;
+}
+
+/**
+ * M9 Decision 7's warning: a link to a hidden page. `hidden` maps a hidden page's address
+ * (normalised) to its name. Never an error: unhiding the page fixes it.
+ */
+export function hiddenLinkTarget(href: unknown, hidden: ReadonlyMap<string, string>): string | undefined {
+	const path = internalLinkPath(href);
+	if (path === null) return undefined;
+	const name = hidden.get(path);
+	return name === undefined ? undefined : `Links to ${path}, the ${name} page, which is hidden from the site. Visitors get its 404 until it's shown again.`;
+}
+
+export function missingLinkTarget(href: unknown, addresses: Iterable<string | null | undefined>): string | undefined {
+	const path = internalLinkPath(href);
+	if (path === null) return undefined;
+	for (const address of addresses) {
+		if (typeof address === 'string' && normaliseAddress(address) === path) return undefined;
+	}
+	return `Links to ${path}, which no page or route serves.`;
+}