@glw907/cairn-cms 0.62.2 → 0.76.0

package/dist/content/fieldset.js

@@ -0,0 +1,386 @@
+import { datetimeInputValue, dateInputValue, isCalendarDate, referenceIdsFromValue } from './frontmatter.js';
+import { compilePattern, dateBoundsError, patternError, stringLengthError } from './field-rules.js';
+import { isValidId } from './ids.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]+$/;
+// 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, value) {
+    if (type === 'date' && value instanceof Date)
+        return dateInputValue(value);
+    if (type === 'datetime' && value instanceof Date)
+        return datetimeInputValue(value);
+    if (type === 'number' && typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    if (typeof value === 'string')
+        return value.trim();
+    return '';
+}
+// Build the structural key for a path by dropping numeric (row-index) segments, so a nested text
+// field's compiled pattern is found regardless of which row it sits in: ['faq', 2, 'code'] -> 'faq.code'.
+function structuralKey(path) {
+    return path.filter((seg) => typeof seg === 'string').join('.');
+}
+// Validate one descriptor against its raw value and return its outcome. Empty or absent is
+// "not provided" and is read BEFORE type coercion, uniformly: a required field returns an issue, an
+// optional field drops (no value, no issue). Only a non-empty value is coerced. boolean is the
+// exception: true stores true, anything else omits the value. number relies on the empty-first drop so
+// an empty optional number never becomes Number('') === 0. A container (object, array) recurses one
+// level, appending the leaf key or element index to `path` for each nested issue.
+function validateField(path, field, value, patterns) {
+    const label = field.label ?? '';
+    // object: validate each leaf one level down, assembling a nested object value and concatenating
+    // issues with the leaf key appended to the path. An empty (all-leaves-dropped) object omits the
+    // value; a required empty object is an error on the object's own path.
+    if (field.type === 'object') {
+        const obj = {};
+        const issues = [];
+        const raw = value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+        for (const [leafKey, leaf] of Object.entries(field.fields)) {
+            const outcome = validateField([...path, leafKey], leaf, raw[leafKey], patterns);
+            issues.push(...outcome.issues);
+            if ('value' in outcome)
+                obj[leafKey] = outcome.value;
+        }
+        if (issues.length > 0)
+            return { issues };
+        if (Object.keys(obj).length === 0) {
+            return field.required ? { issues: [{ path, message: `${label} is required` }] } : { issues: [] };
+        }
+        return { value: obj, issues };
+    }
+    // array: a reference item keeps the shipped id-list path; any other item recurses per element with
+    // the element index appended to the path. A required empty list errors on the array's own path.
+    if (field.type === 'array') {
+        if (field.item.type === 'reference') {
+            // array(reference): coerceToText returns '' for an array, so the empty-first drop below would
+            // silently lose an optional list or falsely error a required one. The canonicalizer coerces a
+            // lone scalar to one element and a Date element to its id. Each element must pass isValidId (the
+            // item's reference rule this phase); a required empty list errors; the value is set only when the
+            // list is non-empty.
+            const list = referenceIdsFromValue(value);
+            if (field.required && list.length === 0)
+                return { issues: [{ path, message: `${label} is required` }] };
+            const invalid = list.find((id) => !isValidId(id));
+            if (invalid !== undefined)
+                return { issues: [{ path, message: `${label} is not a valid reference` }] };
+            return list.length > 0 ? { value: list, issues: [] } : { issues: [] };
+        }
+        const elements = Array.isArray(value) ? value : [];
+        const out = [];
+        const issues = [];
+        elements.forEach((element, i) => {
+            const outcome = validateField([...path, i], field.item, element, patterns);
+            issues.push(...outcome.issues);
+            if ('value' in outcome)
+                out.push(outcome.value);
+        });
+        if (issues.length > 0)
+            return { issues };
+        if (out.length === 0) {
+            return field.required ? { issues: [{ path, message: `${label} is required` }] } : { issues: [] };
+        }
+        return { value: out, issues };
+    }
+    // boolean: presence is the value; an unchecked or absent box omits the value (no draft: false noise).
+    if (field.type === 'boolean') {
+        return value === true ? { value: true, issues: [] } : { issues: [] };
+    }
+    // multiselect: a string array; drop empties, reject an unknown value when options is closed. An empty
+    // list omits the value (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;
+        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) {
+            return { issues: [{ path, message: `${label} is required` }] };
+        }
+        const { options } = field;
+        if (options) {
+            const unknown = list.find((v) => !options.includes(v));
+            if (unknown !== undefined) {
+                return { issues: [{ path, message: `${label} contains an unknown value: ${unknown}` }] };
+            }
+        }
+        return list.length > 0 ? { value: list, issues: [] } : { issues: [] };
+    }
+    // image: the nested object arm, dropping the value on empty src. 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. A required image with an empty src is the one error this arm raises.
+    if (field.type === 'image') {
+        let src = '';
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            const obj = value;
+            src = typeof obj.src === 'string' ? obj.src.trim() : '';
+            if (src !== '') {
+                const normalized = {
+                    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;
+                return { value: normalized, issues: [] };
+            }
+        }
+        return field.required && src === '' ? { issues: [{ path, message: `${label} is required` }] } : { issues: [] };
+    }
+    // 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 === '') {
+        return field.required ? { issues: [{ path, message: `${label} is required` }] } : { issues: [] };
+    }
+    const key = structuralKey(path);
+    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))
+                return { issues: [{ path, message: `${label} must be a number` }] };
+            if (field.integer && !Number.isInteger(n))
+                return { issues: [{ path, message: `${label} must be a whole number` }] };
+            if (field.min != null && n < field.min)
+                return { issues: [{ path, message: `${label} must be at least ${field.min}` }] };
+            if (field.max != null && n > field.max)
+                return { issues: [{ path, message: `${label} must be at most ${field.max}` }] };
+            return { value: n, issues: [] };
+        }
+        case 'select': {
+            if (!field.options.includes(text))
+                return { issues: [{ path, message: `${label} contains an unknown value: ${text}` }] };
+            return { value: text, issues: [] };
+        }
+        case 'url': {
+            if (!URL_RE.test(text))
+                return { issues: [{ path, message: `${label} is not a valid URL` }] };
+            return { value: text, issues: [] };
+        }
+        case 'email': {
+            if (!EMAIL_RE.test(text))
+                return { issues: [{ path, message: `${label} is not a valid email address` }] };
+            return { value: text, issues: [] };
+        }
+        case 'date': {
+            if (!isCalendarDate(text))
+                return { issues: [{ path, message: `${label} must be a valid date (YYYY-MM-DD)` }] };
+            const boundsError = dateBoundsError(text, field, label);
+            if (boundsError != null)
+                return { issues: [{ path, message: boundsError }] };
+            return { value: text, issues: [] };
+        }
+        case 'reference': {
+            // A scalar edge: the empty-first drop above already handled an absent optional, so a non-empty
+            // value must be a valid id. An invalid token is a corrupted edge, not a coercible value.
+            if (!isValidId(text))
+                return { issues: [{ path, message: `${label} is not a valid reference` }] };
+            return { value: text, issues: [] };
+        }
+        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, label);
+                if (lengthError != null)
+                    return { issues: [{ path, message: lengthError }] };
+                const formatError = patternError(text, patterns.get(key), label);
+                if (formatError != null)
+                    return { issues: [{ path, message: formatError }] };
+            }
+            return { value: text, issues: [] };
+        }
+    }
+}
+// At most one image field may feed the social card, so the og:image is unambiguous. A v2 fieldset
+// marks that field with an explicit `seo: true`; there is no field-name default, since the record key
+// is arbitrary. Two seo images is a site config error, so fail loudly at declaration (v1 parity).
+// The delivery seo reader resolves the social card off a hardcoded top-level key list, so a nested
+// seo image cannot resolve at delivery; this phase forbids seo: true inside any container and defers
+// nested seo to the pass that generalizes delivery seo resolution.
+function checkSeoImageFields(record) {
+    const seo = [];
+    for (const [key, field] of Object.entries(record)) {
+        if (field.type === 'image' && field.seo === true)
+            seo.push(`"${key}"`);
+        else if (field.type === 'object') {
+            for (const [leafKey, leaf] of Object.entries(field.fields)) {
+                if (leaf.type === 'image' && leaf.seo === true) {
+                    throw new Error(`cairn: the image "${key}.${leafKey}" sets seo: true, but a nested seo image is not supported this phase. Put the social-card image at the top level.`);
+                }
+            }
+        }
+        else if (field.type === 'array') {
+            const item = field.item;
+            const nested = (item.type === 'image' && item.seo === true)
+                || (item.type === 'object' && Object.values(item.fields).some((l) => l.type === 'image' && l.seo === true));
+            if (nested) {
+                throw new Error(`cairn: the array field "${key}" declares an seo image, but an array would mean one social card per row. Put seo: true on a top-level image.`);
+            }
+        }
+    }
+    if (seo.length > 1) {
+        throw new Error(`cairn: a concept declares at most one SEO image field, but found ${seo.length} (${seo.join(', ')}). Set seo: false on all but one.`);
+    }
+}
+// A leaf is any non-container descriptor. A container (object, array) may hold leaves one level deep only.
+function isLeaf(field) {
+    return field.type !== 'object' && field.type !== 'array';
+}
+// Enforce the one-level nesting cap, the no-reference-in-object deferral, and the no-dot-in-key rule, all
+// loudly at declaration. A deeper nesting, a nested reference, or a dotted key would otherwise mis-save or
+// mis-decode at the edge, so fail here.
+function checkContainerNesting(record) {
+    const checkKey = (k, where) => {
+        if (k.includes('.'))
+            throw new Error(`cairn: ${where} "${k}" must not contain a dot; field keys address the nested form by dotted path.`);
+    };
+    const checkObjectLeaves = (fieldsRecord, where) => {
+        for (const [k, leaf] of Object.entries(fieldsRecord)) {
+            checkKey(k, where);
+            if (!isLeaf(leaf)) {
+                throw new Error(`cairn: ${where} "${k}" must be a leaf field; containers nest one level only.`);
+            }
+            if (leaf.type === 'reference') {
+                throw new Error(`cairn: ${where} "${k}" is a reference; a reference inside an object is not supported this phase. Model it as the parent's own concept, or use a top-level array(reference).`);
+            }
+        }
+    };
+    for (const [key, field] of Object.entries(record)) {
+        checkKey(key, 'the field');
+        if (field.type === 'object') {
+            checkObjectLeaves(field.fields, `the object field "${key}" sub-field`);
+        }
+        else if (field.type === 'array') {
+            const item = field.item;
+            if (item.type === 'object') {
+                checkObjectLeaves(item.fields, `the array field "${key}" row sub-field`);
+            }
+            else if (!isLeaf(item)) {
+                throw new Error(`cairn: the array field "${key}" item must be a leaf or a flat object; an array of arrays is not allowed.`);
+            }
+        }
+    }
+}
+/**
+ * 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(record, options = {}) {
+    checkSeoImageFields(record);
+    checkContainerNesting(record);
+    for (const key of Object.keys(options.behavior ?? {})) {
+        if (!(key in record))
+            throw new Error(`cairn: behavior names "${key}", which is not a declared field.`);
+    }
+    // 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 the structural path
+    // ('faq.code', 'address.zip') so a nested leaf's compiled pattern is found regardless of row index,
+    // recursing one level into an object and an array(object).
+    const patterns = new Map();
+    const compilePatternsIn = (rec, prefix) => {
+        for (const [k, f] of Object.entries(rec)) {
+            if ((f.type === 'text' || f.type === 'textarea') && f.pattern != null) {
+                patterns.set([...prefix, k].join('.'), compilePattern(f.pattern, f.label));
+            }
+            else if (f.type === 'object') {
+                compilePatternsIn(f.fields, [...prefix, k]);
+            }
+            else if (f.type === 'array' && f.item.type === 'object') {
+                compilePatternsIn(f.item.fields, [...prefix, k]);
+            }
+            else if (f.type === 'array' && (f.item.type === 'text' || f.item.type === 'textarea') && f.item.pattern != null) {
+                patterns.set([...prefix, k].join('.'), compilePattern(f.item.pattern, f.item.label));
+            }
+        }
+    };
+    compilePatternsIn(record, []);
+    const validate = (frontmatter, body) => {
+        const data = {};
+        const issues = [];
+        for (const [key, field] of Object.entries(record)) {
+            const outcome = validateField([key], field, frontmatter[key], patterns);
+            issues.push(...outcome.issues);
+            if ('value' in outcome)
+                data[key] = outcome.value;
+            if (outcome.issues.length === 0 && options.behavior?.[key]?.validate) {
+                let message = null;
+                try {
+                    message = options.behavior[key].validate('value' in outcome ? outcome.value : undefined, frontmatter);
+                }
+                catch (err) {
+                    console.warn(`cairn: behavior.validate for field "${key}" threw; treating it as valid.`, err);
+                }
+                if (typeof message === 'string')
+                    issues.push({ path: [key], message });
+            }
+        }
+        if (issues.length > 0) {
+            // Back-compat: derive the flat errors map from the located issues, keying each top-level field by
+            // the first message that mentions it, so a consumer reading `errors[fieldName]` still works.
+            const errors = {};
+            for (const issue of issues) {
+                const top = String(issue.path[0]);
+                if (!(top in errors))
+                    errors[top] = issue.message;
+            }
+            return { ok: false, errors, issues };
+        }
+        const refined = options.refine?.(data, body);
+        if (refined && Object.keys(refined).length > 0) {
+            return { ok: false, errors: refined, issues: Object.entries(refined).map(([k, m]) => ({ path: [k], message: m })) };
+        }
+        return { ok: true, data };
+    };
+    const standard = {
+        version: 1,
+        vendor: 'cairn',
+        validate: (value) => {
+            const { frontmatter = {}, body = '' } = (value ?? {});
+            const result = validate(frontmatter ?? {}, body ?? '');
+            return result.ok
+                ? { value: result.data }
+                : { issues: result.issues ?? Object.entries(result.errors).map(([key, message]) => ({ message, path: [key] })) };
+        },
+    };
+    return { fields: record, behavior: options.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, now) {
+    const values = {};
+    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;
+}

package/dist/content/frontmatter-region.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The split of fmBlock into its lines, each with its block-relative start and end offsets (the end
+ *  is the index of the trailing newline, or the block length for the last line). Block offsets are
+ *  already absolute since the frontmatter leads the document.
+ */
+export interface FmLine {
+    start: number;
+    end: number;
+}
+/**
+ * Split a leading frontmatter block off the markdown. `fmBlock` is the `---` fenced block including
+ *  both fences and the trailing newline (empty when there is none); `body` is everything after it.
+ *  The block leads the document, so a frontmatter offset is already absolute and a body offset needs
+ *  `fmBlock.length` added. Shared by every arm so they agree on the boundary.
+ */
+export declare function splitFrontmatter(markdown: string): {
+    fmBlock: string;
+    body: string;
+};
+/**
+ * Split fmBlock into lines once, so the locator helpers walk a shared structure instead of
+ *  re-scanning the block per call.
+ */
+export declare function fmLines(fmBlock: string): FmLine[];
+/**
+ * The inclusive line-index range `[lo, hi]` of the block-style mapping a top-level key opens: the
+ *  line `^<key>:` at indent 0 through the last line before the next top-level key (or the document
+ *  end). A flow-style value (`key: { ... }` all on one line) yields a single-line range. Returns null
+ *  when the key has no top-level line, which a malformed or non-canonical block can cause. Scoping the
+ *  per-key search to this range is what lets two image fields that share one hash, or an image field
+ *  whose hash also appears in a sibling text value, resolve to distinct, correct spans.
+ */
+export declare function frontmatterKeyRange(lines: FmLine[], fmBlock: string, key: string): [number, number] | null;
+/**
+ * Escape a literal string for safe interpolation into a RegExp source. A key name or an indent is
+ *  matched literally, so its characters must not act as metacharacters.
+ */
+export declare function escapeForRegExp(literal: string): string;

package/dist/content/frontmatter-region.js

@@ -0,0 +1,75 @@
+// cairn-cms: the shared frontmatter-region helpers. A byte-preserving rewriter (media-rewrite's
+// `repointMediaRef`/`fillAltForHash`, references' `rewriteFrontmatterReference`) splices a
+// frontmatter value by source offset rather than round-tripping through gray-matter (which reformats
+// YAML and is not byte stable). These helpers locate the `---` fenced block, split it into lines with
+// absolute offsets, and find a top-level key's inclusive line range, so every such rewriter agrees on
+// the boundary, the CRLF handling, and the colon-anchored key scan.
+/**
+ * Split a leading frontmatter block off the markdown. `fmBlock` is the `---` fenced block including
+ *  both fences and the trailing newline (empty when there is none); `body` is everything after it.
+ *  The block leads the document, so a frontmatter offset is already absolute and a body offset needs
+ *  `fmBlock.length` added. Shared by every arm so they agree on the boundary.
+ */
+export function splitFrontmatter(markdown) {
+    const m = markdown.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+    const fmBlock = m ? m[0] : '';
+    return { fmBlock, body: markdown.slice(fmBlock.length) };
+}
+/**
+ * Split fmBlock into lines once, so the locator helpers walk a shared structure instead of
+ *  re-scanning the block per call.
+ */
+export function fmLines(fmBlock) {
+    const lines = [];
+    let pos = 0;
+    while (pos <= fmBlock.length) {
+        const nl = fmBlock.indexOf('\n', pos);
+        const end = nl === -1 ? fmBlock.length : nl;
+        lines.push({ start: pos, end });
+        if (nl === -1)
+            break;
+        pos = nl + 1;
+    }
+    return lines;
+}
+/**
+ * The inclusive line-index range `[lo, hi]` of the block-style mapping a top-level key opens: the
+ *  line `^<key>:` at indent 0 through the last line before the next top-level key (or the document
+ *  end). A flow-style value (`key: { ... }` all on one line) yields a single-line range. Returns null
+ *  when the key has no top-level line, which a malformed or non-canonical block can cause. Scoping the
+ *  per-key search to this range is what lets two image fields that share one hash, or an image field
+ *  whose hash also appears in a sibling text value, resolve to distinct, correct spans.
+ */
+export function frontmatterKeyRange(lines, fmBlock, key) {
+    const opener = new RegExp(`^${escapeForRegExp(key)}:`);
+    const topLevelKey = /^[^\s#][^:]*:/;
+    const isBoundary = (i) => {
+        const text = fmBlock.slice(lines[i].start, lines[i].end);
+        // A new top-level key or the closing `---` fence ends the current key's block.
+        return topLevelKey.test(text) || text === '---';
+    };
+    let lo = -1;
+    for (let i = 1; i < lines.length - 1; i += 1) {
+        // Skip the leading `---` fence (line 0) and the trailing empty line after the closing fence.
+        if (opener.test(fmBlock.slice(lines[i].start, lines[i].end))) {
+            lo = i;
+            break;
+        }
+    }
+    if (lo === -1)
+        return null;
+    let hi = lo;
+    for (let i = lo + 1; i < lines.length - 1; i += 1) {
+        if (isBoundary(i))
+            break;
+        hi = i;
+    }
+    return [lo, hi];
+}
+/**
+ * Escape a literal string for safe interpolation into a RegExp source. A key name or an indent is
+ *  matched literally, so its characters must not act as metacharacters.
+ */
+export function escapeForRegExp(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/content/frontmatter.d.ts

@@ -1,6 +1,16 @@
-import type { FrontmatterField } from './types.js';
+import type { NamedField } from './types.js';
+/**
+ * True when a multiselect field is a closed checkbox group: it declares an options vocabulary and is
+ *  not author-extendable. The save decoder and the editor render arm both call this, so the
+ *  closed-versus-open multiselect decision can never drift between decode and display.
+ */
+export declare function isClosedMultiselect(field: {
+    type: string;
+    options?: readonly string[];
+    creatable?: boolean;
+}): boolean;
 /** Decode submitted form data into raw frontmatter, one rule per field type. */
-export declare function frontmatterFromForm(fields: FrontmatterField[], form: FormData): Record<string, unknown>;
+export declare function frontmatterFromForm(fields: NamedField[], form: FormData): Record<string, unknown>;
 /**
  * Coerce a frontmatter date value to the `YYYY-MM-DD` an `<input type="date">` wants.
  * gray-matter parses an unquoted YAML date into a JS Date, so a string-only read would
@@ -8,6 +18,14 @@ export declare function frontmatterFromForm(fields: FrontmatterField[], form: Fo
  * slicing the ISO string avoids a local-timezone shift.
  */
 export declare function dateInputValue(value: unknown): string;
+/**
+ * Coerce a frontmatter datetime value to the naive-local, minute-precision `YYYY-MM-DDTHH:mm` an
+ * `<input type="datetime-local">` wants. A datetime is round-tripped as TEXT, so a stored value is
+ * already this string; the `Date` branch is the fallback for a value gray-matter parsed into a JS
+ * `Date` from an unquoted full-ISO scalar. UTC getters read the value back as it was written,
+ * avoiding a local-timezone shift.
+ */
+export declare function datetimeInputValue(value: unknown): string;
 /**
  * True when `s` is a canonical zero-padded `YYYY-MM-DD` string naming a real calendar date.
  * Rejects a wrong format, an impossible month or day, and a JS date-rollover such as
@@ -16,6 +34,21 @@ export declare function dateInputValue(value: unknown): string;
  * `dateInputValue` emit, so a value outside it is a hand-edit or odd-YAML error.
  */
 export declare function isCalendarDate(s: string): boolean;
+/**
+ * Canonicalize one raw reference value to its target id. A Date (a YAML-parsed unquoted date-shaped id)
+ * becomes its UTC-sliced `YYYY-MM-DD` string, so a stored id never depends on the reader's timezone; a
+ * string is trimmed; anything else is the empty string. `validate`, `extractReferenceEdges`, and
+ * `formValues` all read through this, so a hand-edited or rewriter-emitted value canonicalizes identically.
+ */
+export declare function referenceIdFromValue(value: unknown): string;
+/**
+ * Canonicalize a raw `array(reference)` value to its list of target ids. An array maps each element
+ * through `referenceIdFromValue`; a lone non-empty scalar is one element (a single id a YAML scalar
+ * carries, never dropped to an empty list); anything else is empty. Empty ids are dropped.
+ */
+export declare function referenceIdsFromValue(value: unknown): string[];
+/** Coerce parsed frontmatter to the form-ready values the editor inputs expect, one rule per field type. */
+export declare function formValues(fields: NamedField[], frontmatter: Record<string, unknown>): Record<string, unknown>;
 /** Reassemble a markdown file from frontmatter and body for committing. */
 export declare function serializeMarkdown(frontmatter: object, body: string): string;
 /** Parse a markdown file into its frontmatter and body: the read-side inverse of serialize. */