caracms 0.0.0-stage → 0.2.0

package/src/components/Form.astro

@@ -0,0 +1,221 @@
+---
+/**
+ * A public form (M6 Decision 17), from the site's config (`defineSite({ forms })`):
+ *
+ *   <Form form="contact" preview={cms.preview} />
+ *
+ * Plain, accessible markup with classes the site styles (`.cms-form`, `.cms-form-field`,
+ * `.cms-form-label`, `.cms-form-help`, `.cms-form-error`, `.cms-form-status`). A field
+ * with a `prefix` wraps it and its input in `.cms-form-prefixed` (style the two as one
+ * box), the prefix in `.cms-form-prefix`; the input names it in `aria-describedby`, since
+ * the package can't know whether the label already says it. A `placeholder` goes on the
+ * input; the `<label>` stays either way (a site that hides labels hides them visually,
+ * never from screen readers). **It posts
+ * without JavaScript**, files included (`multipart/form-data` only when the form has a
+ * files field), to `POST /_caracms/form` with its hidden `form` and `return` fields and
+ * the honeypot (rules.ts → HONEYPOT, the name the endpoint reads). A field's error line
+ * shows by CSS alone (`:user-invalid`).
+ *
+ * One small script (form-client.ts) enhances it: `fetch`, the thanks line, the file
+ * limits, `?sent=1`, and the Turnstile widget when `TURNSTILE_SITE_KEY` was set at build.
+ * With it, a files field's picks add up, listed under the input (`.cms-form-files`, each
+ * `.cms-form-file` with its name, size and a Remove button); without it, the native input.
+ * Only a page with a form carries it. In a preview the form is `inert`: nothing in the
+ * editor can send it, and a click falls through to the block.
+ *
+ * An id that isn't one of the site's forms renders nothing (and says so in a preview).
+ *
+ * **A site that draws its own look** (M9 port friction 10) has these hooks, each optional;
+ * left out, the form renders exactly as above:
+ *
+ * - `class` and any other attribute (`data-*`, `id`, `aria-*`…) go on the `<form>`;
+ *   the ones the form sets itself (`action`, `method`, `enctype`, `inert`, its own
+ *   `data-caracms-*`, `data-max-*`, `data-file-kinds`, `data-thanks`, `data-failed`) can't be replaced;
+ * - `submitClass`: classes on the submit button, beside `cms-form-submit`;
+ * - `thanks`: the line after a send (default "Thanks, we'll be in touch shortly.");
+ *   `failed`: the line when a send fails without the endpoint's own sentence
+ *   (default "Something went wrong. Please email us directly.");
+ * - `errors`: the error line by field type (`{ email: 'Please check your email.' }`),
+ *   in place of the package's wording; a field's own `error` in the config still wins;
+ * - `actions`: wrap the submit button and the status line in `<div class="cms-form-actions">`,
+ *   so site CSS can lay them out in a row;
+ * - `labelPlaceholders`: a text, email, tel or textarea field with no `placeholder` of its
+ *   own uses its label as one (the `<label>` stays in the markup).
+ *
+ * A textarea's height is its field's `rows` in the config (default 6).
+ */
+import { site } from 'virtual:caracms/config';
+import { build } from 'virtual:caracms/public';
+import { cleanReturn, FILE_ACCEPT, FILE_KINDS, HONEYPOT, MAX_FILE_BYTES, MAX_FILES, PLACEHOLDER_TYPES, type FormFieldType, type ResolvedFormField } from '../forms/rules.ts';
+import { passThrough } from './attributes.ts';
+
+interface Props {
+	/** The form's id in the site's config. */
+	form: string;
+	/** A preview render (the block's `cms.preview`). */
+	preview?: boolean;
+	/** The submit button's text. Default "Send". */
+	submit?: string;
+	/** Classes on the `<form>`, beside `cms-form`. */
+	class?: string;
+	/** Classes on the submit button, beside `cms-form-submit`. */
+	submitClass?: string;
+	/** The line after a send. Default "Thanks, we'll be in touch shortly." */
+	thanks?: string;
+	/** The line when a send fails and the endpoint gave no sentence of its own. Default "Something went wrong. Please email us directly." */
+	failed?: string;
+	/** The error line by field type, in place of the package's wording. A field's own `error` (config) still wins. */
+	errors?: Partial<Record<FormFieldType, string>>;
+	/** Wrap the submit button and the status line in `<div class="cms-form-actions">`. */
+	actions?: boolean;
+	/** A field that takes a placeholder and sets none uses its label as one. */
+	labelPlaceholders?: boolean;
+	/** Anything else (`data-*`, `id`, `aria-*`…) goes on the `<form>`. */
+	[attribute: string]: unknown;
+}
+
+const {
+	form: id,
+	preview = false,
+	submit = 'Send',
+	class: className,
+	submitClass,
+	thanks,
+	failed,
+	errors,
+	actions = false,
+	labelPlaceholders = false,
+	...given
+} = Astro.props;
+// The form's own attributes stay its own: a pass-through can't replace them.
+const OWN = new Set(['action', 'method', 'enctype', 'inert', 'data-max-files', 'data-max-bytes', 'data-file-kinds', 'data-thanks', 'data-failed']);
+const rest = passThrough(Object.fromEntries(Object.entries(given).filter(([name]) => !OWN.has(name.toLowerCase()) && !name.toLowerCase().startsWith('data-caracms-'))));
+const form = Object.hasOwn(site.forms, id) ? site.forms[id]! : null;
+const files = form?.fields.some((f) => f.type === 'files') ?? false;
+const back = cleanReturn(preview ? '/' : Astro.url.pathname);
+const turnstileKey = build.turnstileSiteKey;
+const fieldId = (name: string) => `cms-form-${id}-${name}`;
+
+const DEFAULT_ERROR: Record<ResolvedFormField['type'], string> = {
+	text: 'Please fill this in.',
+	email: 'Please enter your email address, like name@example.com.',
+	tel: 'Please enter a phone number.',
+	textarea: 'Please write a message.',
+	select: 'Please choose one.',
+	files: 'Please attach a file.',
+};
+const placeholderOf = (f: ResolvedFormField) => f.placeholder ?? (labelPlaceholders && PLACEHOLDER_TYPES.includes(f.type) ? f.label : undefined);
+const errorOf = (f: ResolvedFormField) => f.error || errors?.[f.type] || DEFAULT_ERROR[f.type];
+const described = (f: ResolvedFormField) =>
+	[f.prefix ? `${fieldId(f.name)}-prefix` : '', f.help ? `${fieldId(f.name)}-help` : '', `${fieldId(f.name)}-error`].filter(Boolean).join(' ');
+---
+
+{
+	form ? (
+		<form
+			{...rest}
+			class:list={['cms-form', className]}
+			action="/_caracms/form"
+			method="post"
+			enctype={files ? 'multipart/form-data' : undefined}
+			data-caracms-form={id}
+			data-max-files={files ? MAX_FILES : undefined}
+			data-max-bytes={files ? MAX_FILE_BYTES : undefined}
+			data-file-kinds={files ? FILE_KINDS : undefined}
+			data-thanks={thanks || undefined}
+			data-failed={failed || undefined}
+			inert={preview || undefined}
+		>
+			<input type="hidden" name="form" value={id} />
+			<input type="hidden" name="return" value={back} />
+			<div class="cms-form-hp" aria-hidden="true">
+				<label>
+					{HONEYPOT}
+					<input type="text" name={HONEYPOT} tabindex="-1" autocomplete="off" />
+				</label>
+			</div>
+			{form.fields.map((f) => (
+				<div class="cms-form-field" data-type={f.type}>
+					<label class="cms-form-label" for={fieldId(f.name)}>
+						{f.label}
+						{f.optional && <span class="cms-form-optional"> (optional)</span>}
+					</label>
+					{f.type === 'textarea' ? (
+						<textarea id={fieldId(f.name)} name={f.name} rows={String(f.rows ?? 6)} required={!f.optional} autocomplete={f.autocomplete} placeholder={placeholderOf(f)} aria-describedby={described(f)} />
+					) : f.type === 'select' ? (
+						<select id={fieldId(f.name)} name={f.name} required={!f.optional} autocomplete={f.autocomplete} aria-describedby={described(f)}>
+							<option value="">Choose…</option>
+							{f.options!.map((o) => (
+								<option value={o.value}>{o.label}</option>
+							))}
+						</select>
+					) : f.type === 'files' ? (
+						<>
+							<input id={fieldId(f.name)} type="file" name={f.name} multiple accept={FILE_ACCEPT} required={!f.optional} aria-describedby={described(f)} />
+							<ul class="cms-form-files" data-caracms-files aria-label={`${f.label}: chosen files`} hidden />
+						</>
+					) : f.prefix ? (
+						<div class="cms-form-prefixed">
+							<span class="cms-form-prefix" id={`${fieldId(f.name)}-prefix`}>
+								{f.prefix}
+							</span>
+							<input id={fieldId(f.name)} type={f.type} name={f.name} required={!f.optional} autocomplete={f.autocomplete} placeholder={placeholderOf(f)} aria-describedby={described(f)} />
+						</div>
+					) : (
+						<input id={fieldId(f.name)} type={f.type} name={f.name} required={!f.optional} autocomplete={f.autocomplete} placeholder={placeholderOf(f)} aria-describedby={described(f)} />
+					)}
+					{f.help && (
+						<p class="cms-form-help" id={`${fieldId(f.name)}-help`}>
+							{f.help}
+						</p>
+					)}
+					<p class="cms-form-error" id={`${fieldId(f.name)}-error`}>
+						{errorOf(f)}
+					</p>
+				</div>
+			))}
+			{turnstileKey && <div class="cms-form-turnstile" data-caracms-turnstile data-sitekey={turnstileKey} />}
+			{actions ? (
+				<div class="cms-form-actions">
+					<button type="submit" class:list={['cms-form-submit', submitClass]}>
+						{submit}
+					</button>
+					<p class="cms-form-status" role="status" aria-live="polite" data-caracms-form-status />
+				</div>
+			) : (
+				<>
+					<button type="submit" class:list={['cms-form-submit', submitClass]}>
+						{submit}
+					</button>
+					<p class="cms-form-status" role="status" aria-live="polite" data-caracms-form-status />
+				</>
+			)}
+		</form>
+	) : preview ? (
+		<p class="cms-form-missing">There's no form "{id}" in the site's config.</p>
+	) : null
+}
+
+<script>
+	import { initForms } from './form-client.ts';
+
+	initForms();
+</script>
+
+<style is:global>
+	.cms-form-hp {
+		position: absolute;
+		left: -10000px;
+		width: 1px;
+		height: 1px;
+		overflow: hidden;
+	}
+
+	.cms-form-error {
+		display: none;
+	}
+
+	.cms-form-field:has(:user-invalid) .cms-form-error {
+		display: block;
+	}
+</style>

package/src/components/Head.astro

@@ -0,0 +1,62 @@
+---
+/**
+ * The page's head (M6 Decisions 15 and 16): the site's page component puts it in its
+ * `<head>`, as it does `<Fonts />`, and keeps its own icon links:
+ *
+ *   <Head document={document} collection={collection} preview={preview} listPage={listPage} />
+ *
+ * It writes `<title>`, the description, the canonical link, `og:` and `twitter:` tags
+ * and the Google tag (the rules: ../head.ts). Site Settings is read from the file the
+ * build or the preview renders from (read.ts → renderSourceOf), so a preview shows the
+ * drafts' defaults and a build the deployed ones. The Google tag never goes into a
+ * preview or a dev build; the canonical link and `og:url` only with `SITE_URL`.
+ */
+import { join } from 'node:path';
+import { site } from 'virtual:caracms/config';
+import { build } from 'virtual:caracms/public';
+import { documentUrl } from '../content.ts';
+import type { PageProps } from '../document.ts';
+import { googleTagSnippet, headOf } from '../head.ts';
+import { readMediaConfig } from '../media.ts';
+import { renderSourceOf } from '../read.ts';
+import { SITE_SETTINGS_FILE } from '../reserved.ts';
+
+/** The page component's props; `data` (its own fields) and `settings` aren't needed here. */
+type Props = Omit<PageProps, 'data' | 'settings' | 'listPage' | 'read' | 'path'> & { data?: PageProps['data']; settings?: PageProps['settings']; listPage?: number; read?: PageProps['read']; path?: PageProps['path'] };
+const { document, collection, preview = false } = Astro.props;
+// Posts and tags, Decision 16: page 2 onwards says so in its title. A preview is always page 1.
+const listPage = !preview && Number.isInteger(Astro.props.listPage) && Astro.props.listPage! >= 1 ? Astro.props.listPage! : 1;
+
+const settingsText = await renderSourceOf(Astro.locals).readText(join(site.root, SITE_SETTINGS_FILE));
+// A public page's path is its own address; a preview's is the document's: the page component's
+// `path` when it's passed on, else the GET's `?path=` (for the home page's title).
+const previewPath = () => {
+	if (Astro.props.path !== undefined) return Astro.props.path;
+	const c = Object.hasOwn(site.collections, collection) ? site.collections[collection]! : null;
+	const path = Astro.url.searchParams.get('path');
+	return c && path ? documentUrl(c, path) : null;
+};
+const head = headOf({
+	document,
+	settingsText,
+	path: preview ? previewPath() : Astro.url.pathname,
+	siteUrl: preview ? null : build.siteUrl,
+	media: readMediaConfig(),
+	tagAllowed: build.production && !preview,
+	listPage,
+	titleSeparator: site.titleSeparator,
+	titleFallback: site.titleFallback,
+});
+---
+
+<title>{head.title}</title>
+{head.description && <meta name="description" content={head.description} />}
+{head.canonical && <link rel="canonical" href={head.canonical} />}
+<meta property="og:title" content={head.title} />
+{head.description && <meta property="og:description" content={head.description} />}
+{head.canonical && <meta property="og:url" content={head.canonical} />}
+{head.image && <meta property="og:image" content={head.image.url} />}
+{head.image?.width && <meta property="og:image:width" content={String(head.image.width)} />}
+{head.image?.height && <meta property="og:image:height" content={String(head.image.height)} />}
+<meta name="twitter:card" content={head.twitterCard} />
+{head.googleTag && <Fragment set:html={googleTagSnippet(head.googleTag)} />}

package/src/components/Link.astro

@@ -0,0 +1,68 @@
+---
+/**
+ * A link field (M5a Decision 4): `{ label, href }` as an `<a>`.
+ *
+ *   <Link cms={cms} field="cta" value={block.cta} class="cta-link" />
+ *
+ * - Both a label and an href that passes the link rule: `<a href>label</a>`.
+ * - A label with an href that fails the rule: the label as plain text, in a
+ *   `<span>` (Decision 15: kept as typed, flagged on the field, ignored here).
+ * - Half a link (no label, or no href): nothing. The field says so.
+ * - The anchor's content is the label, or the default slot when given (an icon
+ *   beside it, say).
+ * - Preview render only (M3 Decision 17): `data-cms-field="<path>.label"
+ *   data-cms-kind="link"` on the element (Decision 16: `cta.label`). Edited in
+ *   the sidebar (Decision 13). `field` may be a dotted path into a list.
+ *
+ * M6c (G9): an address-only link (`link({ addressOnly: true })`) has no label: its
+ * value is `{ href }` or null, and the anchor's content is the default slot (an image,
+ * an icon). Without a usable href the slot shows in a `<span>`, unlinked. Its marker
+ * is `<path>.href`.
+ *
+ * M6c Decision 11: a file link carries the site's behaviour (`fileLinkAttributes`): a
+ * PDF without `?download` gets `target="_blank" rel="noopener"` and a visually hidden
+ * " (opens in a new tab)" after the content; any other file link gets `download`. The
+ * same in a preview render; the markers don't change. A class or attribute passed in
+ * wins over these.
+ */
+import { site } from 'virtual:caracms/config';
+import type { BlockContext } from '../document.ts';
+import { parseField, usableHref, type AddressValue, type LinkValue } from '../fields.ts';
+import { fileLinkAttributes, NEW_TAB_NOTE_HTML } from '../rich-text.ts';
+import { requireField } from './descriptor.ts';
+import { passThrough } from './attributes.ts';
+
+interface Props {
+	cms: BlockContext;
+	field: string;
+	value: LinkValue | AddressValue | null;
+	class?: string;
+	[attribute: string]: unknown;
+}
+
+const { cms, field, value, class: className, ...given } = Astro.props;
+// M8 trial (item 4): a bare attribute stays bare, false is none (attributes.ts).
+const rest = passThrough(given);
+const descriptor = requireField(site, cms, field, 'link', 'Link');
+const addressOnly = descriptor.addressOnly === true;
+const link = parseField(descriptor, value) as LinkValue;
+const href = usableHref(link.href);
+const show = addressOnly || (link.label !== '' && link.href !== '');
+const file = href ? fileLinkAttributes(href) : { attributes: {}, newTab: false };
+const fileAttributes = Object.fromEntries(Object.entries(file.attributes).map(([name, v]) => [name, v === '' ? true : v]));
+const markers = cms.preview ? { 'data-cms-field': `${field}.${addressOnly ? 'href' : 'label'}`, 'data-cms-kind': 'link' } : {};
+---
+
+{
+	show &&
+		(href ? (
+			<a href={href} class={className} {...fileAttributes} {...rest} {...markers}>
+				<slot>{link.label}</slot>
+				{file.newTab && <Fragment set:html={NEW_TAB_NOTE_HTML} />}
+			</a>
+		) : (
+			<span class={className} {...rest} {...markers}>
+				<slot>{link.label}</slot>
+			</span>
+		))
+}

package/src/components/Lockup.astro

@@ -0,0 +1,116 @@
+---
+/**
+ * A lockup field: display text set as lines that never wrap; the text gets smaller
+ * instead (Spec → Text → Lockups; lifted from M1's Lockup.astro).
+ *
+ *   <Lockup cms={cms} field="heading" value={block.heading} />
+ *
+ * - One heading element. It's the page's `h1` when this field holds the page's
+ *   first heading (Decision 16, from `cms.h1Field`), otherwise `h2`; `as` overrides.
+ * - Main lines, and phone lines when the value has them (Decisions 10–11): both
+ *   sets inside the one heading, each its own size container with its own
+ *   `--longest-line`, each measured on its own; a media query at the site's
+ *   phone-lines width shows one and sets the other `display: none` (lockup-css.ts).
+ * - Measured here, during render, from the font file (measure.ts), so the
+ *   prerendered page and the preview render share one code path.
+ * - The fit: `min(var(--cms-size), calc(100cqi / var(--longest-line)))`, no floor.
+ *
+ * Preview renders only (Decision 17), for the editor (Phases 3 and E7's warning):
+ *   on the heading   data-cms-field="<field>" data-cms-kind="lockup"
+ *                    data-cms-style, data-cms-size (design px), data-cms-min-size (px)
+ *   on each set      data-cms-lines="main" | "phone", data-cms-longest (em),
+ *                    data-cms-uncovered='["✨"]' (Decision 15; only when some are)
+ * The size a set computed is `getComputedStyle(set.querySelector('.cms-lockup-fit')).fontSize`
+ * (in px); compare it with `data-cms-min-size`. In the 375 preview the visible set
+ * is the phone set when there is one, the main set otherwise.
+ * A lockup is edited in the sidebar only (Decision 12), so never contenteditable.
+ * `field` may be a dotted path into a list (M5a Decision 16): the marker carries it.
+ */
+import 'virtual:caracms/lockup.css';
+import { site } from 'virtual:caracms/config';
+import { own, type BlockContext } from '../document.ts';
+import { requireField } from './descriptor.ts';
+import type { LockupValue } from '../fields.ts';
+import { measureLockup } from '../measure.ts';
+import { variationSettings } from '../text-styles.ts';
+import { passThrough } from './attributes.ts';
+
+interface Props {
+	cms: BlockContext;
+	/** The field's key in the block's schema, or a dotted path into a list (`team.0.name`). */
+	field: string;
+	value: LockupValue;
+	/** The heading element. Default: `h1` for the page's first heading, otherwise `h2`. */
+	as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
+	class?: string;
+	/** Anything else (such as the caller's scoped-style attribute) goes on the heading. */
+	[attribute: string]: unknown;
+}
+
+const { cms, field, value, as, class: className, ...given } = Astro.props;
+// M8 trial (item 4): a bare attribute stays bare, false is none (attributes.ts).
+const rest = passThrough(given);
+const descriptor = requireField(site, cms, field, 'lockup', 'Lockup');
+const style = own(site.textStyles, descriptor.style)!;
+const Tag = as ?? (cms.h1Field === field ? 'h1' : 'h2');
+
+const main = measureLockup(value?.lines ?? [], style);
+const phone = value?.phone ? measureLockup(value.phone, style) : null;
+const hasPhone = !!phone && phone.lines.length > 0;
+
+/** Round the fitting width up, never down: four decimals is well under 0.01% of a line. */
+const fitWidth = (em: number) => (Math.ceil(em * 1e4) / 1e4).toFixed(4);
+
+const vars = [
+	`--cms-size: ${style.sizePx}px`,
+	`--cms-tracking: ${style.trackingEm}em`,
+	`--cms-leading: ${style.leading}`,
+	`--cms-transform: ${style.textTransform}`,
+	`--cms-variation: ${variationSettings(style)}`,
+	`--cms-weight: ${style.axes.wght ?? 400}`,
+	`--cms-family: var(${style.cssVariable})`,
+].join('; ');
+
+const p = cms.preview;
+const headingMarkers = p
+	? {
+			'data-cms-field': field,
+			'data-cms-kind': 'lockup',
+			'data-cms-style': style.name,
+			'data-cms-size': String(style.sizePx),
+			'data-cms-min-size': String(style.minSizePx),
+		}
+	: {};
+const setMarkers = (name: 'main' | 'phone', m: { longest: number; uncovered: string[] }) =>
+	p
+		? {
+				'data-cms-lines': name,
+				'data-cms-longest': m.longest.toFixed(4),
+				...(m.uncovered.length > 0 ? { 'data-cms-uncovered': JSON.stringify(m.uncovered) } : {}),
+			}
+		: {};
+
+const sets = [
+	{ name: 'main' as const, m: main },
+	...(hasPhone ? [{ name: 'phone' as const, m: phone! }] : []),
+];
+---
+
+{
+	main.lines.length > 0 && (
+		<Tag class:list={['cms-lockup', hasPhone && 'cms-lockup--has-phone', className]} style={vars} {...rest} {...headingMarkers}>
+			{sets.map(({ name, m }) => (
+				<span class={`cms-lockup-set cms-lockup-${name}`} style={`--longest-line: ${fitWidth(m.longest)}`} {...setMarkers(name, m)}>
+					<span class="cms-lockup-fit">
+						{m.lines.map((line, i) => (
+							<>
+								{i > 0 && ' '}
+								<span class="cms-lockup-line">{line.text}</span>
+							</>
+						))}
+					</span>
+				</span>
+			))}
+		</Tag>
+	)
+}

package/src/components/Media.astro

@@ -0,0 +1,124 @@
+---
+/**
+ * One media slot (M5b Decision 4): an image or a Mux clip, whichever it holds.
+ *
+ *   <Media cms={cms} field="media" value={block.media} sizes="…" ratio={3 / 2} class="tm-media" />
+ *
+ * - **An image is exactly one `<img>`**: no `<picture>`, no wrapper. The caller's
+ *   `class` and `style` go on it, so the block's CSS sizes the box.
+ *   - Fluid (pass `sizes`, optionally `ratio`): a `w` srcset over the ladder;
+ *     with a ratio, `rs:fill` at it with the focal point's gravity; without, `rs:fit`.
+ *   - Fixed (pass a CSS `width` and/or `height`): 1×, 2×, 3×; both sides `rs:fill`,
+ *     or `rs:fit` with `fit="contain"`.
+ *   - `object-position: x% y%` only when a focal point is set (before the caller's style).
+ *   - `width`/`height` from the stored size, scaled to the ratio.
+ *   - `alt` from the value (`""` when decorative: decorative wins).
+ * - **A loop**: `<video autoplay muted loop playsinline>` on Mux's MP4, with its poster,
+ *   `aria-hidden`, and no script. Its source carries
+ *   `media="(prefers-reduced-motion: no-preference)"`, so with reduced motion no
+ *   source matches and only the poster shows.
+ * - **A player**: MediaPlayer.astro (its poster and a "Play video: {name}" button);
+ *   only it carries a script, so a page with no player has none.
+ * - **PNG** (M9 Decision 8): a field declared `media({ format: 'png' })` gets `@png`
+ *   URLs at every width; every other image is WebP.
+ * - **Loading** (Decision 4): eager in the first two rendered blocks (`cms.eager`),
+ *   `fetchpriority="high"` only on the image at `cms.priority`; lazy otherwise. Props
+ *   override both.
+ * - **Preview markers**: `data-cms-field="<path>" data-cms-kind="media"` on the element,
+ *   preview renders only, when `field` is given (a dotted path into a list works).
+ *   Without `field` (a card showing another document's cover) there's no marker.
+ * - **An empty slot** (M9 port friction, item 12): nothing for visitors. In a preview, with
+ *   `field`, a placeholder carrying the markers, so the slot can be clicked on the page
+ *   (it selects the field, as a placed image does): a `<span>` (valid inside a `<p>` or a
+ *   link) with the caller's `class`, at `ratio` when given (else the fixed `width`/`height`,
+ *   else at least 6rem square), drawn as a dashed box in the text's own colour. So a block
+ *   that wants its empty slot clickable calls `<Media>` even when the value is empty
+ *   (`{(block.media || cms.preview) && <Media … />}`); the visitors' page is unchanged.
+ * - **Without the media variables** (Decision 5): a preview (and `astro dev`) renders an
+ *   image slot as nothing; a build throws the one sentence naming them.
+ *
+ * Server-only: the signing happens here, in the server render.
+ */
+import { site } from 'virtual:caracms/config';
+import { renderValue, type MediaField } from '../fields.ts';
+import { failedOnce, fixedImage, fluidImage, isProductionBuild, mediaUnsetMessage, readMediaConfig } from '../media.ts';
+import { renderMedia, type RenderMedia } from '../media-value.ts';
+import { requireField } from './descriptor.ts';
+import MediaPlayer from './MediaPlayer.astro';
+import { passThrough } from './attributes.ts';
+import type { MediaProps } from './media-props.ts';
+
+/** Its props: media-props.ts (M8 trial, item 13: the element's own attributes type-check too). */
+type Props = MediaProps;
+
+const { cms, field, value, sizes, ratio, minWidth, maxWidth, width, height, fit, loading, fetchpriority, class: className, style, ...given } = Astro.props;
+// M8 trial (item 4): a bare attribute stays bare, false is none (attributes.ts).
+const rest = passThrough(given);
+const descriptor: MediaField | null = field ? requireField(site, cms, field, 'media', 'Media') : null;
+const media: RenderMedia | null = descriptor ? (renderValue(descriptor, value) as RenderMedia | null) : renderMedia(value);
+const markers = cms.preview && field ? { 'data-cms-field': field, 'data-cms-kind': 'media' } : {};
+const load = loading ?? (cms.eager ? 'eager' : 'lazy');
+const priority = fetchpriority ?? (field && cms.priority === field ? 'high' : undefined);
+const fixed = width !== undefined || height !== undefined;
+// M9 Decision 8: the field's own format (PNG for flat artwork), WebP otherwise.
+const format = descriptor?.format;
+
+let img: (ReturnType<typeof fluidImage> & { alt: string; style?: string }) | null = null;
+if (media?.kind === 'image') {
+	const config = readMediaConfig();
+	if (config.kind !== 'ready') {
+		// A missing deploy setting: the build stops with one sentence; a preview (and dev) shows nothing.
+		// Once per process: the page's other slots render in parallel, and a second throw would be an unhandled rejection.
+		if (!cms.preview && isProductionBuild() && !failedOnce()) throw new Error(`caracms: ${mediaUnsetMessage(config)}`);
+	} else {
+		if (!fixed && !sizes) throw new Error(`<Media>: a fluid image needs \`sizes\` (${cms.collection ? `collection "${cms.collection}"` : `block "${cms.type}"`}${field ? `, field "${field}"` : ''}).`);
+		const built = fixed ? fixedImage(config.settings, media, { width, height, fit, format }) : fluidImage(config.settings, media, { sizes: sizes!, ratio, minWidth, maxWidth, format });
+		const styles = media.position ? [`object-position: ${media.position}`, style].filter(Boolean).join('; ') : style;
+		img = { ...built, alt: media.alt, style: styles };
+	}
+}
+const clip = media?.kind === 'video' ? media : null;
+// An empty slot in a preview: something to click (see above). Never in the public render.
+const placeholderStyle = cms.preview && field && !media ? emptySlotStyle({ ratio, width, height, style }) : null;
+
+function emptySlotStyle(size: { ratio?: number; width?: number; height?: number; style?: string }): string {
+	const box =
+		size.ratio !== undefined
+			? [`aspect-ratio: ${size.ratio}`, 'min-width: 6rem']
+			: size.width !== undefined || size.height !== undefined
+				? [size.width !== undefined ? `width: ${size.width}px` : 'min-width: 6rem', size.height !== undefined ? `height: ${size.height}px` : 'min-height: 6rem']
+				: ['min-width: 6rem', 'min-height: 6rem'];
+	const look = ['background: color-mix(in srgb, currentColor 6%, transparent)', 'outline: 1.5px dashed color-mix(in srgb, currentColor 40%, transparent)', 'outline-offset: -1.5px', 'cursor: pointer'];
+	return ['display: block', 'box-sizing: border-box', ...box, size.style, ...look].filter(Boolean).join('; ');
+}
+---
+
+{placeholderStyle !== null && <span class={className} style={placeholderStyle} aria-hidden="true" data-cms-placeholder="" {...rest} {...markers} />}
+
+{
+	img && (
+		<img
+			src={img.src}
+			srcset={img.srcset}
+			sizes={img.sizes}
+			width={img.width}
+			height={img.height}
+			alt={img.alt}
+			loading={load}
+			fetchpriority={priority}
+			decoding="async"
+			class={className}
+			style={img.style}
+			{...rest}
+			{...markers}
+		/>
+	)
+}
+{
+	clip && clip.play === 'loop' && (
+		<video autoplay muted loop playsinline preload="metadata" poster={clip.poster} width={clip.w ?? undefined} height={clip.h ?? undefined} aria-hidden="true" class={className} style={style} {...rest} {...markers}>
+			<source src={clip.mp4} type="video/mp4" media="(prefers-reduced-motion: no-preference)" />
+		</video>
+	)
+}
+{clip && clip.play === 'player' && <MediaPlayer clip={clip} loading={load} fetchpriority={priority} class={className} style={style} markers={{ ...rest, ...markers }} />}