@glw907/cairn-cms 0.62.1 → 0.68.0

package/src/lib/components/ComponentInsertDialog.svelte

@@ -317,11 +317,16 @@ trapping and Escape, following the dropdown's a11y conventions used elsewhere in
 
 {#if defs.length > 0}
   <dialog class="modal" aria-labelledby="cairn-insert-dialog-title" bind:this={dialog} onclose={onClose} oncancel={onCancel}>
-    <div class="modal-box {twoPane ? 'max-w-3xl' : ''}">
+    <!-- The box caps at 85vh and is a flex column so its header holds while only the body scrolls,
+         per the design system's dialog-sizing recipe. The cap rides Tailwind utilities (the utilities
+         layer) so it beats DaisyUI's `.modal-box` max-height: 100vh; a components-layer rule loses the
+         cascade. overflow-hidden keeps the box from being a second scroll container. Matches TidyReview. -->
+    <div class="modal-box flex max-h-[85vh] flex-col overflow-hidden {twoPane ? 'max-w-3xl' : ''}">
       <!-- The shared header: at the configure step it carries the Back control and the
            "Insert > group" eyebrow breadcrumb above the component label; while browsing it is the
-           plain "Insert a component" title. -->
-      <div class="mb-3 flex items-center gap-3">
+           plain "Insert a component" title. It holds (flex-none) while the body scrolls, per the
+           design system's dialog-sizing recipe. -->
+      <div class="mb-3 flex flex-none items-center gap-3">
         {#if picked && !editing}
           <button type="button" class="btn btn-ghost btn-sm btn-square" aria-label="Back to components" onclick={back}>
             <svg class="h-4 w-4" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true"><path d="M165.7 202.3a8 8 0 0 1-11.4 11.4l-80-80a8 8 0 0 1 0-11.4l80-80a8 8 0 0 1 11.4 11.4L91.3 128Z" /></svg>
@@ -339,6 +344,9 @@ trapping and Escape, following the dropdown's a11y conventions used elsewhere in
       </div>
 
       {#if picked}
+        <!-- The configure body is the box's scroll container (flex-1, min-h-0): the shared header
+             above holds while the form scrolls within the 85vh cap. -->
+        <div class="-mr-1 flex min-h-0 flex-1 flex-col overflow-y-auto pr-1">
         {#key picked}
           {#if twoPane}
             <!-- Two panes: the form on the left, the live preview on the right. Below the breakpoint
@@ -395,9 +403,10 @@ trapping and Escape, following the dropdown's a11y conventions used elsewhere in
             {@render configureForm(picked)}
           {/if}
         {/key}
+        </div>
       {:else}
         {#if showSearch}
-          <div class="mb-3 flex items-center gap-2 rounded-field border border-[var(--cairn-card-border)] bg-base-100 px-3 py-2">
+          <div class="mb-3 flex flex-none items-center gap-2 rounded-field border border-[var(--cairn-card-border)] bg-base-100 px-3 py-2">
             <svg class="ec-glyph h-4 w-4 text-[var(--color-muted)]" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true"><path d="M229.7 218.3 179.6 168.2A92.2 92.2 0 1 0 168.2 179.6l50.1 50.1a8 8 0 0 0 11.4-11.4ZM40 112a72 72 0 1 1 72 72 72.1 72.1 0 0 1-72-72Z" /></svg>
             <input
               type="search"
@@ -421,8 +430,10 @@ trapping and Escape, following the dropdown's a11y conventions used elsewhere in
             <button type="button" class="text-[0.8125rem] font-medium text-primary underline [text-underline-offset:2px]" onclick={() => (query = '')}>Clear search</button>
           </div>
         {:else}
-          <!-- One scroll region holds every group, so the arrow keys roam the whole catalog. -->
-          <div data-cairn-pk-list>
+          <!-- One scroll region holds every group, so the arrow keys roam the whole catalog. It
+               is the box's scroll container (flex-1, min-h-0): the header above holds while the
+               list scrolls within the 85vh cap. -->
+          <div data-cairn-pk-list class="-mr-1 min-h-0 flex-1 overflow-y-auto pr-1">
             {#each groups as group (group.heading)}
               <div class="mt-3 first:mt-0">
                 {#if group.heading}

package/src/lib/components/ConceptList.svelte

@@ -200,6 +200,38 @@ header button. Filtering, sorting, and paging run over the loaded entries in com
       ? `Published ${data.publishedAll} ${data.publishedAll === 1 ? 'entry' : 'entries'}.`
       : '',
   );
+
+  // The one lifecycle error to announce (the visible alerts below keep their own styling). A blocked
+  // delete leads, then a form error, then a load error, since the refusal is the most recent and most
+  // actionable outcome of the last submit. The refusal announcement carries the blocker count, so a
+  // screen reader hears the magnitude (matching the visible banner) before navigating to the list.
+  const lifecycleError = $derived(
+    deleteRefused
+      ? `This ${data.label.toLowerCase()} could not be deleted. ${deleteRefused.inboundLinks.length} ${deleteRefused.inboundLinks.length === 1 ? 'page links' : 'pages link'} to it.`
+      : (data.formError ?? data.error ?? ''),
+  );
+
+  // The polite live region's text re-announces only when it changes, so a repeated identical error
+  // (a second submit failing the same way) would go silent. An invisible nonce flips on every fresh
+  // error so the region text always mutates and the screen reader speaks again (the MediaPicker
+  // discipline). The nonce is a zero-width space, never voiced, so the heard sentence is unchanged.
+  let announceNonce = $state(0);
+  function nonce(): string {
+    return announceNonce % 2 === 0 ? '' : '​';
+  }
+  // Each submit hands a fresh `form` (or `data` on a load) object, so the nonce bumps once per submit,
+  // keying the re-announce to the submit rather than to a string change the live region would swallow.
+  // The guard reads a plain non-reactive `lastSubmit`, so the bump fires only when the submit identity
+  // changes, never on the re-render the bump itself causes; that is what keeps the effect from looping.
+  let lastSubmit: unknown;
+  $effect(() => {
+    const submit = form ?? data;
+    if (submit !== lastSubmit) {
+      lastSubmit = submit;
+      if (lifecycleError) announceNonce++;
+    }
+  });
+  const liveError = $derived(lifecycleError ? `${lifecycleError}${nonce()}` : '');
 </script>
 
 <!-- The non-color selected cue for the triage controls (WCAG 1.4.1): a small check glyph that
@@ -225,20 +257,25 @@ header button. Filtering, sorting, and paging run over the loaded entries in com
      {#if}-gated role element inserted fresh is announced inconsistently, so the visible alert
      below keeps its styling without a role and the message is announced once. -->
 <div class="sr-only" aria-live="polite">{publishedAllMessage}</div>
+<!-- One persistent polite region announces the lifecycle errors, re-announcing a repeat through the
+     nonce. The visible alerts below keep their styling and drop the live `role` (a fresh-inserted
+     role element announces inconsistently and clobbers a repeat), so the message is announced once. -->
+<div class="sr-only" aria-live="polite">{liveError}</div>
 {#if publishedAllMessage}
   <div class="alert alert-success mb-4 text-sm">{publishedAllMessage}</div>
 {/if}
 {#if data.formError}
-  <div role="alert" class="alert alert-error mb-4 text-sm">{data.formError}</div>
+  <div class="alert alert-error mb-4 text-sm">{data.formError}</div>
 {/if}
 {#if data.error}
-  <div role="alert" class="alert alert-warning mb-4 text-sm">{data.error}</div>
+  <div class="alert alert-warning mb-4 text-sm">{data.error}</div>
 {/if}
 
 {#if deleteRefused}
   <!-- A `?/delete` was refused: name the blockers up front, matching the editor's refusal banner,
-       so the author sees why without re-opening a dialog. -->
-  <div role="alert" aria-label="This {data.label.toLowerCase()} could not be deleted" class="alert alert-error mb-4 flex-col items-start text-sm">
+       so the author sees why without re-opening a dialog. The polite region above announces it, so
+       the box itself carries no role or label (a bare div with an aria-label gets no accessible name). -->
+  <div class="alert alert-error mb-4 flex-col items-start text-sm">
     <p class="font-medium">This {data.label.toLowerCase()} could not be deleted.</p>
     <p>{deleteRefused.inboundLinks.length} {deleteRefused.inboundLinks.length === 1 ? 'page links' : 'pages link'} to it. Remove or repoint the {deleteRefused.inboundLinks.length === 1 ? 'link' : 'links'} listed below, then delete again.</p>
     <ul class="mt-1 w-full">

package/src/lib/content/advisories.ts

@@ -1,7 +1,7 @@
 // cairn-cms: the entry editor's internal advisory channel (editor-help pass 3). An advisory is a
 // non-blocking, serializable notice that rides EditData across the SSR boundary, so it carries data
-// only and never a callback. Today's one notice is the cross-branch address collision: a warning,
-// not a gate, that another entry already resolves to the same public address (last-write-wins).
+// only and never a callback. Today's one notice is the address collision: a warning, not a gate,
+// that another entry already resolves to the same public address (last-write-wins).
 //
 // The address index mirrors buildUsageIndex (src/lib/media/usage.ts): a main arm that reads each
 // manifest entry's resolved permalink with no per-file read, and a branch arm that lists every open
@@ -9,7 +9,8 @@
 // and resolves its permalink. The map is keyed by permalink, so every entry that resolves to a given
 // address shares one bucket. The build fails open: a branch read that throws, or a dated entry whose
 // permalink cannot resolve, is skipped rather than thrown, so a transient failure degrades to no
-// notice and never blocks the editor or the publish.
+// notice and never blocks the editor or the publish. The scope splits by call site: the main arm at
+// edit-load (synchronous, no extra GitHub read per open) and the full cross-branch check at publish.
 import type { ConceptDescriptor } from './types.js';
 import type { RepoRef } from '../github/types.js';
 import type { Manifest } from './manifest.js';
@@ -63,6 +64,23 @@ function push(index: AddressIndex, permalink: string, entry: AddressEntry): void
   else index.set(permalink, [entry]);
 }
 
+/**
+ * The address index over main only: a synchronous reverse map of each manifest entry's resolved
+ * permalink. No backend read, so an edit-load can build it for free from the manifest it already holds.
+ */
+export function mainAddressIndex(manifest: Manifest): AddressIndex {
+  const index: AddressIndex = new Map();
+  for (const entry of manifest.entries) {
+    push(index, entry.permalink, {
+      concept: entry.concept,
+      id: entry.id,
+      title: entry.title,
+      source: 'main',
+    });
+  }
+  return index;
+}
+
 /**
  * Build the permalink-keyed address index over main (from each manifest entry's resolved permalink)
  * plus every open cairn/* branch (resolved from its edited markdown).
@@ -77,18 +95,9 @@ export async function buildAddressIndex(
   concepts: ConceptDescriptor[],
   manifest: Manifest,
 ): Promise<AddressIndex> {
-  const index: AddressIndex = new Map();
-
-  // The main arm: the manifest already carries each entry's resolved permalink, so this is a pure
-  // reverse map with no per-file read.
-  for (const entry of manifest.entries) {
-    push(index, entry.permalink, {
-      concept: entry.concept,
-      id: entry.id,
-      title: entry.title,
-      source: 'main',
-    });
-  }
+  // The main arm: the manifest already carries each entry's resolved permalink, so seed from the
+  // synchronous main-only index and union the branch arm on top.
+  const index = mainAddressIndex(manifest);
 
   // The branch arm: read each open cairn/* branch's one edited file and resolve its permalink. The
   // path is derivable from the branch name, so no tree-listing is needed.

package/src/lib/content/field-rules.ts

@@ -0,0 +1,40 @@
+// cairn-cms: the shared field constraint rules. Both the v1 `defineFields` validator and the v2
+// `fieldset` validator call these pure helpers, so the two validators cannot drift on the
+// constraint wording or the first-failing-rule-wins order. No I/O and no clock reads, so the
+// rules stay deterministic on Workers.
+
+/** Compile a field pattern once, throwing a labeled error when the source is not a valid regex. */
+export function compilePattern(source: string, label: string): RegExp {
+  try {
+    return new RegExp(source);
+  } catch (cause) {
+    throw new Error(`cairn: field "${label}" has an invalid pattern: ${source}`, { cause });
+  }
+}
+
+/** Return the first string-length violation message, or null when the value satisfies the bounds. */
+export function stringLengthError(
+  value: string,
+  constraints: { min?: number; max?: number; length?: number },
+  label: string,
+): string | null {
+  const { min, max, length } = constraints;
+  if (min != null && value.length < min) return `${label} must be at least ${min} characters`;
+  if (max != null && value.length > max) return `${label} must be at most ${max} characters`;
+  if (length != null && value.length !== length) return `${label} must be exactly ${length} characters`;
+  return null;
+}
+
+/** Return the format violation message when a compiled pattern rejects the value, else null. */
+export function patternError(value: string, compiled: RegExp | undefined, label: string): string | null {
+  if (compiled && !compiled.test(value)) return `${label} is not in the expected format`;
+  return null;
+}
+
+/** Return the first date-bounds violation message, or null when the value is within the bounds. */
+export function dateBoundsError(value: string, constraints: { min?: string; max?: string }, label: string): string | null {
+  const { min, max } = constraints;
+  if (min != null && value < min) return `${label} must be on or after ${min}`;
+  if (max != null && value > max) return `${label} must be on or before ${max}`;
+  return null;
+}

package/src/lib/content/fields.ts

@@ -0,0 +1,127 @@
+/** The stored value of an image field; re-exported so this module owns the image shape too. */
+export type { ImageValue } from './types.js';
+
+/** Common to every field descriptor: the form label and the universal options. */
+export interface FieldBase {
+  /** Form label. */
+  label: string;
+  /** One author-facing sentence shown under the field. */
+  help?: string;
+  /** A required field fails validation when empty. */
+  required?: boolean;
+  /** Form-render-time initial value; a sentinel like "today" resolves at render (Task 9). */
+  default?: string | boolean;
+}
+/** A single-line text input. */
+export interface TextField extends FieldBase {
+  type: 'text';
+  min?: number; max?: number; length?: number;
+  /** A regular-expression source string the value must match. */
+  pattern?: string;
+}
+/** A multi-line text input. */
+export interface TextareaField extends FieldBase {
+  type: 'textarea';
+  rows?: number; min?: number; max?: number; length?: number; pattern?: string;
+}
+/** A numeric input. */
+export interface NumberField extends FieldBase {
+  type: 'number';
+  min?: number; max?: number;
+  /** Constrain the value to whole numbers. */
+  integer?: boolean;
+}
+/** A single-choice input over a closed option list. */
+export interface SelectField extends FieldBase {
+  type: 'select';
+  /** The closed set of allowed values. */
+  options: readonly string[];
+}
+/** A multiple-choice input. */
+export interface MultiselectField extends FieldBase {
+  type: 'multiselect';
+  /** The allowed values; omitted leaves the set open. */
+  options?: readonly string[];
+  /** Allow the author to add values not in the list. */
+  creatable?: boolean;
+  /** Mark the field as a site-wide taxonomy whose values pool across entries. */
+  taxonomy?: boolean;
+}
+/** A URL input whose format the validator enforces. */
+export interface UrlField extends FieldBase {
+  type: 'url';
+}
+/** An email-address input whose format the validator enforces. */
+export interface EmailField extends FieldBase {
+  type: 'email';
+}
+/** A calendar-date input. */
+export interface DateField extends FieldBase {
+  type: 'date';
+  /** Earliest allowed date as YYYY-MM-DD. */
+  min?: string;
+  /** Latest allowed date as YYYY-MM-DD. */
+  max?: string;
+}
+/** A date-and-time input. */
+export interface DatetimeField extends FieldBase {
+  type: 'datetime';
+  /** Earliest allowed moment as an ISO string. */
+  min?: string;
+  /** Latest allowed moment as an ISO string. */
+  max?: string;
+}
+/** A checkbox; absent means false. */
+export interface BooleanField extends FieldBase {
+  type: 'boolean';
+}
+/** A hero image whose stored value is the nested ImageValue object. */
+export interface ImageField extends FieldBase {
+  type: 'image';
+  /** Whether this field feeds the social-card image. */
+  seo?: boolean;
+}
+/** The plain-data descriptor union the form, validator, and inference all read. Grows per task. */
+export type FieldDescriptor =
+  | TextField
+  | TextareaField
+  | NumberField
+  | SelectField
+  | MultiselectField
+  | UrlField
+  | EmailField
+  | DateField
+  | DatetimeField
+  | BooleanField
+  | ImageField;
+
+/**
+ * The constructor namespace a concept declares its fields with. Each constructor captures its
+ * argument with a `const` type parameter and intersects it onto the descriptor, so the call-site
+ * literals (`required: true`, a `select`/`multiselect` `options` union) survive into the descriptor
+ * type for `Infer` to read. The runtime value is unchanged: still `{ type, ...o }`.
+ */
+export const fields = {
+  /** A single-line text field. */
+  text: <const O extends Omit<TextField, 'type'>>(o: O): TextField & O => ({ type: 'text', ...o }),
+  /** A multi-line text field. */
+  textarea: <const O extends Omit<TextareaField, 'type'>>(o: O): TextareaField & O => ({ type: 'textarea', ...o }),
+  /** A numeric field. */
+  number: <const O extends Omit<NumberField, 'type'>>(o: O): NumberField & O => ({ type: 'number', ...o }),
+  /** A single-choice field over a closed option list, preserving the literal option union. */
+  select: <const O extends Omit<SelectField, 'type'>>(o: O): SelectField & O => ({ type: 'select', ...o }),
+  /** A multiple-choice field, preserving the literal option union when one is given. */
+  multiselect: <const O extends Omit<MultiselectField, 'type'>>(o: O): MultiselectField & O => ({ type: 'multiselect', ...o }),
+  /** A URL field. */
+  url: <const O extends Omit<UrlField, 'type'>>(o: O): UrlField & O => ({ type: 'url', ...o }),
+  /** An email-address field. */
+  email: <const O extends Omit<EmailField, 'type'>>(o: O): EmailField & O => ({ type: 'email', ...o }),
+  /** A calendar-date field. */
+  date: <const O extends Omit<DateField, 'type'>>(o: O): DateField & O => ({ type: 'date', ...o }),
+  /** A date-and-time field. */
+  datetime: <const O extends Omit<DatetimeField, 'type'>>(o: O): DatetimeField & O => ({ type: 'datetime', ...o }),
+  /** A boolean checkbox field. */
+  boolean: <const O extends Omit<BooleanField, 'type'>>(o: O): BooleanField & O => ({ type: 'boolean', ...o }),
+  /** An image field whose value is the nested ImageValue object. */
+  image: <const O extends Omit<ImageField, 'type'>>(o: O): ImageField & O => ({ type: 'image', ...o }),
+};

package/src/lib/content/fieldset.ts

@@ -0,0 +1,307 @@
+// cairn-cms: the fieldset primitive (Contract v2). A key-to-descriptor record becomes a schema
+// carrying the descriptors as plain data, a server-derived validator, and the Standard Schema
+// conformance property. The validator coerces per type, drops an empty optional field, and returns
+// field-keyed errors or normalized data. This is the additive v2 path alongside `defineFields`; the
+// inferred-type and default-resolution arms land in later tasks, and the cutover is a later plan.
+import type { FieldDescriptor, ImageValue } from './fields.js';
+import type { ValidationResult } from './types.js';
+import type { StandardInput, StandardSchemaV1 } from './schema.js';
+import { dateInputValue, isCalendarDate } from './frontmatter.js';
+import { compilePattern, dateBoundsError, patternError, stringLengthError } from './field-rules.js';
+
+/** Accept any URL using http or https with a non-empty rest, mirroring the conservative form check. */
+const URL_RE = /^https?:\/\/\S+$/;
+/** Accept a single address conservatively: exactly one at-sign and a dotted domain, nothing more. */
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+/**
+ * The behavior table co-bundled with a fieldset, keyed by field name. It holds function-valued
+ *  behavior a descriptor cannot carry as plain data (a cross-field validator, an array itemLabel).
+ *  Scalars have no behavior, so the table is empty for now and reserved for later co-bundled functions.
+ */
+export type BehaviorTable = Record<string, never>;
+
+/**
+ * Options for `fieldset`. `refine` runs after the per-field coercion and constraints pass, for
+ *  cross-field and body-dependent checks. It is validation-only: it returns field-keyed errors to
+ *  merge, or nothing, and never transforms the data. Server-only, since it may carry closures.
+ */
+export interface FieldsetOptions {
+  refine?: (data: Record<string, unknown>, body: string) => Record<string, string> | undefined;
+}
+
+/**
+ * A concept's fieldset: the plain-data descriptors, the co-bundled behavior table, the server-derived
+ *  validator, and the Standard Schema conformance property.
+ */
+export interface Fieldset<R extends Record<string, FieldDescriptor> = Record<string, FieldDescriptor>> {
+  /** The declared descriptors as plain serializable data, for the editor form. */
+  readonly fields: R;
+  /** Function-valued behavior keyed by field name; empty for a scalar-only fieldset. */
+  readonly behavior: BehaviorTable;
+  /** Validate raw frontmatter, returning field-keyed errors or the normalized data. */
+  validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
+  /** Standard Schema v1 conformance, for ecosystem interop. A thin adapter over `validate`. */
+  readonly '~standard': StandardSchemaV1<StandardInput, Record<string, unknown>>['~standard'];
+}
+
+/**
+ * Map one field descriptor to the TS type of its normalized value. number is number, boolean is
+ *  boolean, image is the nested ImageValue object; a select with a literal option list is that
+ *  option union, a multiselect with one is that union array (else string[]); everything else is a
+ *  string.
+ */
+type ValueOf<D extends FieldDescriptor> = D extends { type: 'number' }
+  ? number
+  : D extends { type: 'boolean' }
+    ? boolean
+    : D extends { type: 'image' }
+      ? ImageValue
+      : D extends { type: 'select'; options: readonly (infer O extends string)[] }
+        ? O
+        : D extends { type: 'multiselect'; options: readonly (infer O extends string)[] }
+          ? O[]
+          : D extends { type: 'multiselect' }
+            ? string[]
+            : string;
+
+/** Flatten an intersection into a single readable object type. */
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/**
+ * The normalized frontmatter type inferred from a fieldset's descriptor record. A descriptor
+ *  declared `required: true` is a required key; every other descriptor is optional.
+ */
+type Infer<R extends Record<string, FieldDescriptor>> = Prettify<
+  { -readonly [K in keyof R as R[K] extends { required: true } ? K : never]: ValueOf<R[K]> } & {
+    -readonly [K in keyof R as R[K] extends { required: true } ? never : K]?: ValueOf<R[K]>;
+  }
+>;
+
+/** Extract the inferred frontmatter type from a `Fieldset`. */
+export type InferFieldset<S> = S extends Fieldset<infer R> ? Infer<R> : never;
+
+// Coerce one image value to the stored `{ src, alt, caption?, decorative? }` shape, ported from
+// validate.ts. Default a missing alt to empty (alt is debt, never a save block), trim and drop a
+// blank caption, keep decorative only when an explicit true, and drop the whole key when src is empty.
+// A required image with an empty src is the one error this arm raises.
+function coerceImage(
+  field: Extract<FieldDescriptor, { type: 'image' }>,
+  key: string,
+  value: unknown,
+  data: Record<string, unknown>,
+  errors: Record<string, string>,
+): void {
+  let src = '';
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>;
+    src = typeof obj.src === 'string' ? obj.src.trim() : '';
+    if (src !== '') {
+      const normalized: ImageValue = {
+        src,
+        alt: typeof obj.alt === 'string' ? obj.alt : '',
+      };
+      const caption = typeof obj.caption === 'string' ? obj.caption.trim() : '';
+      if (caption !== '') normalized.caption = caption;
+      if (obj.decorative === true) normalized.decorative = true;
+      data[key] = normalized;
+    }
+  }
+  if (field.required && src === '') errors[key] = `${field.label} is required`;
+}
+
+// Coerce a raw value to the trimmed string the empty check and constraints run on. A parsed value may
+// arrive from parseMarkdown, not only a form string: a Date on a date or datetime field, a JS number on
+// a number field. A finite 0 coerces to '0', never read as empty, since 0 is a real number a YAML scalar
+// carries; a NaN or non-finite number stays '' and routes to the number error in validateField.
+function coerceToText(type: FieldDescriptor['type'], value: unknown): string {
+  if (type === 'date' && value instanceof Date) return dateInputValue(value);
+  if (type === 'datetime' && value instanceof Date) return value.toISOString();
+  if (type === 'number' && typeof value === 'number' && Number.isFinite(value)) return String(value);
+  if (typeof value === 'string') return value.trim();
+  return '';
+}
+
+// Validate one descriptor against its raw value, writing into `data` or `errors`. Empty or absent is
+// "not provided" and is read BEFORE type coercion, uniformly: a required field errors, an optional
+// field drops (no key, no error). Only a non-empty value is coerced. boolean is the exception: true
+// stores true, anything else omits the key. number relies on the empty-first drop so an empty optional
+// number never becomes Number('') === 0.
+function validateField(
+  key: string,
+  field: FieldDescriptor,
+  value: unknown,
+  data: Record<string, unknown>,
+  errors: Record<string, string>,
+  patterns: Map<string, RegExp>,
+): void {
+  // boolean: presence is the value; an unchecked or absent box omits the key (no draft: false noise).
+  if (field.type === 'boolean') {
+    if (value === true) data[key] = true;
+    return;
+  }
+
+  // multiselect: a string array; drop empties, reject an unknown value when options is closed. An empty
+  // list omits the key (a required empty errors); the array path is the one non-string coercion. A lone
+  // non-empty scalar (a single tag a YAML scalar carries) coerces to a single-element list, rather than
+  // dropping to [] and reading as "required" while present. An empty string or a non-string-non-array
+  // stays the empty list.
+  if (field.type === 'multiselect') {
+    let raw: string[];
+    if (Array.isArray(value)) raw = value.map(String);
+    else if (typeof value === 'string' && value.trim() !== '') raw = [value.trim()];
+    else raw = [];
+    const list = raw.map((v) => v.trim()).filter((v) => v !== '');
+    if (field.required && list.length === 0) {
+      errors[key] = `${field.label} is required`;
+      return;
+    }
+    const { options } = field;
+    if (options) {
+      const unknown = list.find((v) => !options.includes(v));
+      if (unknown !== undefined) {
+        errors[key] = `${field.label} contains an unknown value: ${unknown}`;
+        return;
+      }
+    }
+    if (list.length > 0) data[key] = list;
+    return;
+  }
+
+  // image: the nested object arm, dropping the key on empty src.
+  if (field.type === 'image') {
+    coerceImage(field, key, value, data, errors);
+    return;
+  }
+
+  // Every other type is "not provided when empty" first, then coerced. `coerceToText` turns a parsed
+  // value into its string form BEFORE the empty check, so a real parsed value (a Date on a date or
+  // datetime field, a number on a number field) is not read as empty.
+  const text = coerceToText(field.type, value);
+  if (text === '') {
+    if (field.required) errors[key] = `${field.label} is required`;
+    return;
+  }
+
+  switch (field.type) {
+    case 'number': {
+      const n = Number(text);
+      // Reject NaN and the non-finite values Number() yields for "Infinity"/"1e400", which an
+      // isNaN check alone would pass through and commit as a YAML .inf scalar.
+      if (!Number.isFinite(n)) errors[key] = `${field.label} must be a number`;
+      else if (field.integer && !Number.isInteger(n)) errors[key] = `${field.label} must be a whole number`;
+      else if (field.min != null && n < field.min) errors[key] = `${field.label} must be at least ${field.min}`;
+      else if (field.max != null && n > field.max) errors[key] = `${field.label} must be at most ${field.max}`;
+      else data[key] = n;
+      break;
+    }
+    case 'select': {
+      if (!field.options.includes(text)) errors[key] = `${field.label} contains an unknown value: ${text}`;
+      else data[key] = text;
+      break;
+    }
+    case 'url': {
+      if (!URL_RE.test(text)) errors[key] = `${field.label} is not a valid URL`;
+      else data[key] = text;
+      break;
+    }
+    case 'email': {
+      if (!EMAIL_RE.test(text)) errors[key] = `${field.label} is not a valid email address`;
+      else data[key] = text;
+      break;
+    }
+    case 'date': {
+      if (!isCalendarDate(text)) {
+        errors[key] = `${field.label} must be a valid date (YYYY-MM-DD)`;
+        break;
+      }
+      const boundsError = dateBoundsError(text, field, field.label);
+      if (boundsError != null) {
+        errors[key] = boundsError;
+        break;
+      }
+      data[key] = text;
+      break;
+    }
+    default: {
+      // text, textarea, datetime: a trimmed non-empty string. text and textarea also enforce the
+      // string-length and pattern constraints (v1 parity); datetime stays a plain string for now,
+      // since its bounds are out of scope this pass and v1 has no datetime equivalent to match.
+      if (field.type === 'text' || field.type === 'textarea') {
+        const lengthError = stringLengthError(text, field, field.label);
+        if (lengthError != null) {
+          errors[key] = lengthError;
+          break;
+        }
+        const formatError = patternError(text, patterns.get(key), field.label);
+        if (formatError != null) {
+          errors[key] = formatError;
+          break;
+        }
+      }
+      data[key] = text;
+    }
+  }
+}
+
+/**
+ * Build a fieldset from a key-to-descriptor record. The returned schema carries the descriptors, a
+ *  server-derived validator that coerces per type and returns field-keyed errors or normalized data,
+ *  and the Standard Schema conformance property whose issues map each error to a single-segment path.
+ */
+export function fieldset<const R extends Record<string, FieldDescriptor>>(
+  record: R,
+  options: FieldsetOptions = {},
+): Fieldset<R> {
+  // Compile each text/textarea pattern once at construction, so a malformed pattern fails loudly here
+  // (mirroring v1's compilePatterns) rather than on every save. Keyed by field name for validateField.
+  const patterns = new Map<string, RegExp>();
+  for (const [key, field] of Object.entries(record)) {
+    if ((field.type === 'text' || field.type === 'textarea') && field.pattern != null) {
+      patterns.set(key, compilePattern(field.pattern, field.label));
+    }
+  }
+  const validate = (frontmatter: Record<string, unknown>, body: string): ValidationResult => {
+    const data: Record<string, unknown> = {};
+    const errors: Record<string, string> = {};
+    for (const [key, field] of Object.entries(record)) {
+      validateField(key, field, frontmatter[key], data, errors, patterns);
+    }
+    if (Object.keys(errors).length > 0) return { ok: false, errors };
+    const refined = options.refine?.(data, body);
+    return refined && Object.keys(refined).length > 0 ? { ok: false, errors: refined } : { ok: true, data };
+  };
+  const standard: StandardSchemaV1<StandardInput, Record<string, unknown>>['~standard'] = {
+    version: 1,
+    vendor: 'cairn',
+    validate: (value) => {
+      const { frontmatter = {}, body = '' } = (value ?? {}) as Partial<StandardInput>;
+      const result = validate(frontmatter ?? {}, body ?? '');
+      return result.ok
+        ? { value: result.data }
+        : { issues: Object.entries(result.errors).map(([key, message]) => ({ message, path: [key] })) };
+    },
+  };
+  return { fields: record, behavior: {}, validate, '~standard': standard };
+}
+
+/**
+ * Resolve each descriptor's `default` to a form-initial value, so a fresh entry opens prefilled. The
+ *  `'today'` sentinel on a date field resolves through the passed `now` to its `YYYY-MM-DD` form; an
+ *  empty-string or `false` default is omitted, so an untouched field commits no key (the
+ *  minimal-frontmatter invariant). With no `now`, a `'today'` default is omitted rather than read off
+ *  a real clock, since library code must stay deterministic and Workers-safe.
+ */
+export function initialValues(fieldset: Fieldset, now?: Date): Record<string, unknown> {
+  const values: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(fieldset.fields)) {
+    const value = field.default;
+    if (value === undefined || value === '' || value === false) continue;
+    if (field.type === 'date' && value === 'today') {
+      if (now) values[key] = now.toISOString().slice(0, 10);
+      continue;
+    }
+    values[key] = value;
+  }
+  return values;
+}