@pmeweb/content 1.0.0

package/README.md

@@ -0,0 +1,43 @@
+# @pmeweb/content
+
+The content contract every PmeWeb site and the client portal share. A site declares its
+collections in `src/content.schema.json`; this package is what reads that declaration.
+
+| Entry point | What | Who imports it |
+|---|---|---|
+| `@pmeweb/content/types` | `CollectionDecl`, `Field`, `ScheduleDecl`, `ContentSchema` | sites, portal |
+| `@pmeweb/content/zodFrom` | declaration -> Astro zod schema (needs `astro`) | sites |
+| `@pmeweb/content/fields` | `isDate`, `isDateTime`, `isTime`, `isDayDate`, `TIME_RE` | portal tier 1, `zodFrom` |
+| `@pmeweb/content/schedule` | `scheduleState`, `visibleOnSite`, `scheduleErrors`, `jourQuebec`, `quebecDay` | sites, portal |
+
+## Dated kinds
+
+- `date`: `2026-10-14`, a calendar day and nothing else.
+- `datetime`: `2026-10-14T13:00:00.000Z`, an instant with its zone. The portal edits it in Quebec time.
+- `time`: `09:05`, a time of day on 24 hours.
+
+## Scheduling
+
+```json
+"evenements": { "schedule": { "publishAt": "publierLe", "removeAt": ["fin", "debut"] } }
+```
+
+- `publishAt`: one `date`/`datetime` field. A `date` publishes at the start of its Quebec day,
+  a `datetime` at its instant.
+- `removeAt`: one path or several; the first that yields a value wins. `dates[].debut` takes the
+  latest value in the array. Always read as a Quebec day: the entry stays through that whole day
+  and comes off at the next day's rebuild. A site that declares a schedule needs a daily rebuild.
+
+## Versioning
+
+Sites and the portal pin an EXACT version. What `scheduleState` returns and what the field checks
+accept is a frozen contract: changing either is a major version. The portal must never accept a
+value a site's `zodFrom` refuses.
+
+## Develop
+
+```bash
+npm install        # .npmrc sets legacy-peer-deps (npm 10.9 arborist crash)
+npm test
+npm run build      # dist/ (JS + .d.ts)
+```

package/dist/fields.d.ts

@@ -0,0 +1,15 @@
+export declare const TIME_RE: RegExp;
+/** « HH:MM », 00:00 to 23:59. */
+export declare function isTime(value: unknown): value is string;
+/**
+ * « YYYY-MM-DD », and a day that exists. The round trip is what refuses `2026-02-30`, which
+ * `Date` would silently roll over to March 2nd.
+ */
+export declare function isDate(value: unknown): value is string;
+/**
+ * An ISO instant WITH ITS ZONE. A wall clock with no `Z` and no offset is refused: `Date.parse`
+ * would read it in the machine's zone, so its meaning would depend on where it was built.
+ */
+export declare function isDateTime(value: unknown): value is string;
+/** A `Date` that is a day as the site's loader produces one: exactly UTC midnight. */
+export declare function isDayDate(value: unknown): value is Date;

package/dist/fields.js

@@ -0,0 +1,42 @@
+// The stored shape of each dated kind, as one definition read by every check.
+//
+// THE SITE'S BUILD AND THE PORTAL'S TIER 1 BOTH CALL THESE, which is the reason they live in a
+// package: « a draft the portal accepts is a draft the site accepts » used to hold because two
+// copies of a regex agreed, and now it holds because there is one.
+//
+//   date      `2026-10-14`                a calendar day, nothing else (strict since 2026-09-27)
+//   datetime  `2026-10-14T13:00:00.000Z`  an instant, with Z or an offset
+//   time      `09:05`                     a time of day on 24 hours
+//
+// A STRING IS WHAT THE PORTAL HOLDS; A `Date` IS WHAT A SITE MAY HOLD. The portal reads YAML with
+// `yaml` v2, which keeps `2026-10-14` a string. Astro's loader can hand zod a `Date` for the same
+// text (a YAML timestamp). `isDayDate` is the site-side reading of « this is a day »: the loader
+// turns a day into UTC midnight, so a `Date` anywhere else carried a time.
+export const TIME_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$/;
+/** « HH:MM », 00:00 to 23:59. */
+export function isTime(value) {
+    return typeof value === 'string' && TIME_RE.test(value);
+}
+/**
+ * « YYYY-MM-DD », and a day that exists. The round trip is what refuses `2026-02-30`, which
+ * `Date` would silently roll over to March 2nd.
+ */
+export function isDate(value) {
+    if (typeof value !== 'string' || !DATE_RE.test(value))
+        return false;
+    const d = new Date(`${value}T00:00:00.000Z`);
+    return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === value;
+}
+/**
+ * An ISO instant WITH ITS ZONE. A wall clock with no `Z` and no offset is refused: `Date.parse`
+ * would read it in the machine's zone, so its meaning would depend on where it was built.
+ */
+export function isDateTime(value) {
+    return typeof value === 'string' && DATETIME_RE.test(value) && !Number.isNaN(Date.parse(value));
+}
+/** A `Date` that is a day as the site's loader produces one: exactly UTC midnight. */
+export function isDayDate(value) {
+    return value instanceof Date && !Number.isNaN(value.getTime()) && value.getTime() % 86_400_000 === 0;
+}

package/dist/schedule.d.ts

@@ -0,0 +1,53 @@
+/** The zone every PmeWeb client lives in. One constant, named where it is used. */
+export declare const QUEBEC = "America/Toronto";
+export type ScheduleState = 'scheduled' | 'live' | 'removed';
+/**
+ * The slice of a declaration this module reads. STRUCTURAL AND LOOSE on purpose: a site passes
+ * its imported `content.schema.json` (whose `kind`s TypeScript widens to `string`) and the portal
+ * its own parsed schema, and neither should need a cast to ask when an entry is on.
+ */
+export interface FieldLike {
+    kind: string;
+    of?: Record<string, FieldLike>;
+}
+export interface SchedulableLike {
+    fields: Record<string, FieldLike>;
+    schedule?: {
+        publishAt?: unknown;
+        removeAt?: unknown;
+    };
+}
+/**
+ * The Quebec calendar day `now` falls on, as UTC midnight of that day -- the same shape a `date`
+ * field has once a site's zod has read it, so the two compare directly (`fin >= jourQuebec(now)`).
+ */
+export declare function jourQuebec(now: Date): Date;
+/**
+ * A stored value's Quebec day, read by its field's kind; null when empty or unreadable.
+ *
+ * A `date` IS its day, whichever spelling it arrives in (the portal's string, a site's UTC-midnight
+ * `Date`). A `datetime` is converted to Quebec FIRST and then truncated, so an event ending at
+ * 21:00 on the 14th is the 14th, not the 15th it already is in UTC.
+ */
+export declare function quebecDay(value: unknown, kind: string): string | null;
+/**
+ * Everything wrong with a collection's `schedule`, one French sentence each; `[]` means valid.
+ *
+ * The site's `zodFrom` THROWS on any of these, so a bad declaration fails the build that
+ * introduced it. The portal DROPS the declaration with a warning: a list that hid nothing is a
+ * better failure than a page that does not open.
+ */
+export declare function scheduleErrors(c: SchedulableLike): string[];
+/**
+ * Where an entry stands at `now`.
+ *
+ * `scheduled` BEATS `removed`. An entry whose publication is after its removal was mis-entered,
+ * and « Programmé » is the state that makes someone look at it; « Retiré » would bury it behind
+ * the portal's filter. An invalid declaration answers `live`: it must never hide anything.
+ */
+export declare function scheduleState(data: Record<string, unknown>, c: SchedulableLike, now: Date): ScheduleState;
+/**
+ * What a site builds. The portal's PRIVATE preview (`PMEWEB_PORTAL_PREVIEW === '1'`) shows a
+ * scheduled entry early so the client can check it; it never brings back a removed one.
+ */
+export declare function visibleOnSite(state: ScheduleState, portalPreview: boolean): boolean;

package/dist/schedule.js

@@ -0,0 +1,183 @@
+// When an entry is on the site: a collection's `schedule` (types.ts), read the same way by the
+// site's build and by the portal's list.
+//
+// ONE FUNCTION, TWO READERS, AND THAT IS THE POINT. jessyoga and yoga-unique each carried
+// `fin ?? debut` and a `publierLe` rule by hand, and the portal knew neither -- so its list kept
+// past events forever and never said an entry was waiting. A site that builds with
+// `scheduleState` and a portal that badges with it cannot disagree about an entry.
+//
+// THE UNIT IS THE QUEBEC CALENDAR DAY, not the UTC one. A day stored as `2026-11-01` parses as UTC
+// midnight, which is 20:00 the evening before in Quebec: compared in UTC, an event disappears
+// during the evening it describes. So `now` is turned into the day it is in `America/Toronto`,
+// with Intl doing the clock changes, and compared as a `YYYY-MM-DD` string.
+//
+// A STATIC SITE APPLIES THIS WHEN IT BUILDS. `now` is build time; the daily rebuild (06:00
+// Quebec) is what makes an entry come off « the morning after ». A collection that declares a
+// schedule on a site with no daily rebuild keeps showing it until someone publishes.
+import { isDate, isDateTime } from './fields.js';
+/** The zone every PmeWeb client lives in. One constant, named where it is used. */
+export const QUEBEC = 'America/Toronto';
+const DAY = new Intl.DateTimeFormat('en-CA', {
+    timeZone: QUEBEC, year: 'numeric', month: '2-digit', day: '2-digit',
+});
+/** « YYYY-MM-DD » of this instant in Quebec. */
+function quebecDayOf(ms) {
+    const p = {};
+    for (const part of DAY.formatToParts(new Date(ms)))
+        p[part.type] = part.value;
+    return `${p.year}-${p.month}-${p.day}`;
+}
+/**
+ * The Quebec calendar day `now` falls on, as UTC midnight of that day -- the same shape a `date`
+ * field has once a site's zod has read it, so the two compare directly (`fin >= jourQuebec(now)`).
+ */
+export function jourQuebec(now) {
+    return new Date(`${quebecDayOf(now.getTime())}T00:00:00.000Z`);
+}
+function instant(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value.getTime();
+    if (isDateTime(value))
+        return Date.parse(value);
+    return null;
+}
+/**
+ * A stored value's Quebec day, read by its field's kind; null when empty or unreadable.
+ *
+ * A `date` IS its day, whichever spelling it arrives in (the portal's string, a site's UTC-midnight
+ * `Date`). A `datetime` is converted to Quebec FIRST and then truncated, so an event ending at
+ * 21:00 on the 14th is the 14th, not the 15th it already is in UTC.
+ */
+export function quebecDay(value, kind) {
+    if (kind === 'date') {
+        if (isDate(value))
+            return value;
+        if (value instanceof Date && !Number.isNaN(value.getTime()))
+            return value.toISOString().slice(0, 10);
+        return null;
+    }
+    if (kind === 'datetime') {
+        const ms = instant(value);
+        return ms === null ? null : quebecDayOf(ms);
+    }
+    return null;
+}
+const PATH_RE = /^([A-Za-z_$][\w$]*)(?:\[\]\.([A-Za-z_$][\w$]*))?$/;
+const DATED = new Set(['date', 'datetime']);
+function paths(v) {
+    if (v === undefined)
+        return [];
+    return Array.isArray(v) ? v : [v];
+}
+/**
+ * Everything wrong with a collection's `schedule`, one French sentence each; `[]` means valid.
+ *
+ * The site's `zodFrom` THROWS on any of these, so a bad declaration fails the build that
+ * introduced it. The portal DROPS the declaration with a warning: a list that hid nothing is a
+ * better failure than a page that does not open.
+ */
+export function scheduleErrors(c) {
+    const s = c.schedule;
+    if (s === undefined)
+        return [];
+    if (typeof s !== 'object' || s === null || Array.isArray(s))
+        return ['schedule : ce n’est pas un objet'];
+    const out = [];
+    const check = (key, p, allowArray) => {
+        const m = typeof p === 'string' ? PATH_RE.exec(p) : null;
+        if (!m) {
+            out.push(`schedule.${key} : « ${String(p)} » n’est pas un chemin de champ`);
+            return;
+        }
+        const [, top, sub] = m;
+        const f = c.fields[top];
+        if (!f) {
+            out.push(`schedule.${key} : « ${top} » n’est pas un champ`);
+            return;
+        }
+        if (sub !== undefined) {
+            if (!allowArray)
+                out.push(`schedule.${key} : « ${p} », un tableau n’est permis que pour removeAt`);
+            else if (f.kind !== 'array' || !f.of?.[sub])
+                out.push(`schedule.${key} : « ${p} » n’est pas un champ de tableau`);
+            else if (!DATED.has(f.of[sub].kind))
+                out.push(`schedule.${key} : « ${p} » n’est pas une date`);
+            return;
+        }
+        if (!DATED.has(f.kind))
+            out.push(`schedule.${key} : « ${top} » n’est pas une date`);
+    };
+    if (s.publishAt !== undefined)
+        check('publishAt', s.publishAt, false);
+    for (const p of paths(s.removeAt))
+        check('removeAt', p, true);
+    return out;
+}
+/** The day `removeAt` resolves to: the first path that yields one; an array path yields its latest. */
+function removeDay(data, c) {
+    for (const p of paths(c.schedule?.removeAt)) {
+        const m = typeof p === 'string' ? PATH_RE.exec(p) : null;
+        if (!m)
+            continue;
+        const [, top, sub] = m;
+        const f = c.fields[top];
+        if (!f)
+            continue;
+        if (sub === undefined) {
+            const d = quebecDay(data[top], f.kind);
+            if (d)
+                return d;
+            continue;
+        }
+        const kind = f.of?.[sub]?.kind ?? '';
+        const items = Array.isArray(data[top]) ? data[top] : [];
+        let latest = null;
+        for (const item of items) {
+            if (typeof item !== 'object' || item === null)
+                continue;
+            const d = quebecDay(item[sub], kind);
+            if (d && (latest === null || d > latest))
+                latest = d;
+        }
+        if (latest)
+            return latest;
+    }
+    return null;
+}
+/** A `date` publishes at the start of its Quebec day; a `datetime` at its instant. */
+function isScheduled(data, c, now) {
+    const key = c.schedule?.publishAt;
+    if (typeof key !== 'string')
+        return false;
+    const f = c.fields[key];
+    if (!f)
+        return false;
+    if (f.kind === 'datetime') {
+        const ms = instant(data[key]);
+        return ms !== null && ms > now.getTime();
+    }
+    const d = quebecDay(data[key], f.kind);
+    return d !== null && d > quebecDayOf(now.getTime());
+}
+/**
+ * Where an entry stands at `now`.
+ *
+ * `scheduled` BEATS `removed`. An entry whose publication is after its removal was mis-entered,
+ * and « Programmé » is the state that makes someone look at it; « Retiré » would bury it behind
+ * the portal's filter. An invalid declaration answers `live`: it must never hide anything.
+ */
+export function scheduleState(data, c, now) {
+    if (!c.schedule || scheduleErrors(c).length > 0)
+        return 'live';
+    if (isScheduled(data, c, now))
+        return 'scheduled';
+    const d = removeDay(data, c);
+    return d !== null && quebecDayOf(now.getTime()) > d ? 'removed' : 'live';
+}
+/**
+ * What a site builds. The portal's PRIVATE preview (`PMEWEB_PORTAL_PREVIEW === '1'`) shows a
+ * scheduled entry early so the client can check it; it never brings back a removed one.
+ */
+export function visibleOnSite(state, portalPreview) {
+    return state === 'live' || (state === 'scheduled' && portalPreview);
+}

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+/** Every field kind, and the whole vocabulary a site may use. Widening this is a spec
+ *  decision, not a convenience: see § 4 of the design. */
+export type FieldKind = 'line' | 'paragraph' | 'markdown' | 'slug' | 'image' | 'date' | 'datetime' | 'select' | 'multiselect' | 'number' | 'boolean' | 'array' | 'reference' | 'url' | 'time';
+/** Where an enum's vocabulary lives. A POINTER at a data file, never a copy -- the portal's
+ *  blog pipeline reads AND WRITES that file (design § 4). */
+export interface OptionsRef {
+    from: string;
+}
+/** What every field carries, whatever its kind. NOT a member of the union and deliberately
+ *  carries no `kind`: see the note under `Field`. */
+export interface FieldCommon {
+    /** French, client-facing. The one thing that cannot be inferred. */
+    label: string;
+    /** Help text under the input. */
+    description?: string;
+    required?: boolean;
+    /** Declared and generated, but never rendered for the client. `draft` is the case. */
+    editable?: boolean;
+    /**
+     * Clearing this field REMOVES the key rather than writing `""`. Defaults to true for
+     * optional strings. `ogImageAlt` is why it is named: `ogImageAlt: ''` tells a screen
+     * reader the image is decorative, which is a different claim from « no alt was given »,
+     * and it stops the template's fallback to the post title from firing. Read by the
+     * portal's writer; `zodFrom` ignores it.
+     */
+    absentSafe?: boolean;
+    /**
+     * The value on disk is a map from language code to what this field would otherwise hold.
+     *
+     * ORTHOGONAL TO `kind`, not a kind of its own: a localized `line` or `paragraph` both work,
+     * and each language's value is still held to the field's own rules. THE LANGUAGE SET IS NOT
+     * DECLARED HERE -- it is the site's own, read from `pmeweb.json`'s `content.dictionaries`,
+     * because a site's languages are a property of the site and a second declaration is a second
+     * place for the same fact to be wrong.
+     */
+    localized?: boolean;
+    max?: number;
+}
+/**
+ * A field, as a DISCRIMINATED UNION on `kind`.
+ *
+ * The discriminant has to live on each member rather than on a shared base: a base declaring
+ * `kind: FieldKind` makes every member's `kind` the full union, so `switch (f.kind)` narrows
+ * nothing and `zodFrom` needs a cast in every branch -- which is precisely where a wrong one
+ * would go unnoticed. Written this way, `case 'reference':` gives TypeScript `collection`
+ * for free and a missing case is a compile error.
+ */
+export type Field = (FieldCommon & {
+    kind: 'line' | 'paragraph' | 'markdown' | 'slug' | 'url' | 'time' | 'date' | 'datetime' | 'boolean' | 'image';
+}) | (FieldCommon & {
+    kind: 'number';
+    int?: boolean;
+}) | (FieldCommon & {
+    kind: 'select' | 'multiselect';
+    options: OptionsRef;
+}) | (FieldCommon & {
+    kind: 'reference';
+    collection: string;
+}) | (FieldCommon & {
+    kind: 'array';
+    of: Record<string, Field>;
+    itemLabel?: string;
+});
+/**
+ * Which existing fields say when an entry goes on and comes off the site. OPT-IN: a collection
+ * that declares none is simply always on. Checked by `scheduleErrors` (schedule.ts), read by
+ * `scheduleState` -- on the site's build and in the portal's list alike.
+ *
+ * Both point at fields the collection already has, so no date is ever typed twice: a blog's
+ * `date` IS its publication, an event's end IS its removal.
+ */
+export interface ScheduleDecl {
+    /** One top-level `date` or `datetime` field. Before it, the entry is `scheduled`. */
+    publishAt?: string;
+    /**
+     * One path or several, THE FIRST THAT YIELDS A VALUE WINS (`["fin", "debut"]`: the end, or
+     * else the start). A path is `field` or `arrayField[].subField`; the array form yields the
+     * latest filled value. Read as a Quebec calendar day: visible through that whole day.
+     */
+    removeAt?: string | string[];
+}
+export interface CollectionDecl {
+    label: string;
+    /** Directory holding the entries, no trailing slash. */
+    path: string;
+    /** The file inside each entry's directory. `index.md` for blog, `index.yaml` for authors. */
+    entryFile: string;
+    /** The field the slug is derived from AT CREATION. Never re-derived on edit (design § 6). */
+    slugField: string;
+    /** Which field is the Markdown body. ABSENT on a collection that has no body -- `authors`
+     *  is frontmatter only. Excluded from the generated zod: Astro's body is not a field. */
+    contentField?: string;
+    /** The list view. */
+    columns: string[];
+    fields: Record<string, Field>;
+    /**
+     * The order and grouping of the portal's form. READ BY THE PORTAL ONLY -- `zodFrom` ignores
+     * it, since it changes where a field is drawn and nothing about what it accepts. `type` says
+     * what a group IS; the portal decides where each type goes.
+     */
+    groups?: Array<{
+        key: string;
+        label: string;
+        type?: 'content' | 'metadata' | 'media' | 'seo';
+        collapsed?: boolean;
+        fields: string[];
+    }>;
+    schedule?: ScheduleDecl;
+}
+export type ContentSchema = Record<string, CollectionDecl>;

package/dist/types.js

@@ -0,0 +1,8 @@
+// @pmeweb/content/types
+// The shape of a site's src/content.schema.json -- the one place a site declares what its
+// collections are. Types only: the generator is zodFrom.ts and the data is the JSON.
+//
+// WHY THE JSON IS TYPED AT ALL. A mistyped `kind` is otherwise a runtime throw during
+// `astro build`, in a file with no line number that a reader associates with content. With
+// this, `npm run check` names the field.
+export {};

package/dist/zodFrom.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'astro/zod';
+import type { CollectionDecl } from './types.js';
+export interface ZodFromContext {
+    /** Astro's SchemaContext `image`. */
+    image: () => z.ZodTypeAny;
+    /** Astro's `reference`, passed in from content.config.ts. */
+    reference: (collection: string) => z.ZodTypeAny;
+    /** Enum vocabularies by the path their `options.from` names. Static imports, because
+     *  `import(someString)` does not bundle -- Vite needs the specifier at build time. */
+    vocabularies: Record<string, ReadonlyArray<{
+        value: string;
+        label: string;
+    }>>;
+    /**
+     * The site's languages, in the order it declares them -- what a `localized` field is keyed by.
+     *
+     * PASSED IN, never derived here, and read from ONE declaration: `pmeweb.json`'s
+     * `content.dictionaries`, which is also where the client portal reads it. A second list would
+     * be a second place for the same fact to be wrong, and the failure would be silent in the
+     * worst direction: a language missing from it is a language whose copy the build stops
+     * validating and every template stops finding.
+     *
+     * Empty means « this site declares none », and a localized field is then generated as an
+     * ordinary one -- there is no language to key it by, so refusing would fail a build over a
+     * declaration that simply does not apply here.
+     */
+    locales: readonly string[];
+}
+/**
+ * Build one collection's schema.
+ *
+ * `contentField` is EXCLUDED. It names the Markdown body, which the portal renders as a box
+ * and which Astro does not treat as a schema field at all -- declaring it would make every
+ * entry fail for a missing `body` key that lives below the frontmatter.
+ *
+ * `T` IS THE ONE THING THE DECLARATION CANNOT CARRY, and the cast below is where it is
+ * admitted rather than hidden. TypeScript widens every string in an imported `.json` to
+ * `string` -- probed 2026-09-21: `typeof schema.blog.fields.title.kind` accepts
+ * `'pas-line'` -- so `kind` is not a literal in the type system and no conditional type can
+ * recover the shape from the file. Without `T`, `post.data` is `Record<string, unknown>`
+ * and `post.data.date.getTime()` stops compiling across the whole site.
+ *
+ * So the caller states the parsed shape once, beside its loader, and
+ * tests/contentSchemaDeclaration.test.ts holds that statement to the JSON's field names --
+ * the one drift a reader would not otherwise see (a field added to the declaration and not
+ * to the type is silently unreachable in every template).
+ */
+export declare function zodFrom<T = Record<string, unknown>>(decl: CollectionDecl, ctx: ZodFromContext): z.ZodType<T>;

package/dist/zodFrom.js

@@ -0,0 +1,149 @@
+// @pmeweb/content/zodFrom
+// A collection's declaration (src/content.schema.json) -> the z.ZodObject that Astro's
+// defineCollection requires. THE ONLY PLACE `z.` APPEARS IN A SITE.
+//
+// A PACKAGE SINCE 2026-09-27. It was a byte-identical copy in the boilerplate and four sites, and
+// the portal's tier 1 held its rules a third time; the field checks (`fields.ts`) and the
+// schedule check (`schedule.ts`) are now one definition both sides import.
+//
+// WHY ZOD AT ALL, since the rules are now data: `schema?: S extends zCore.$ZodType` is
+// Astro's signature (node_modules/astro/dist/content/config.d.ts), and `image()` itself
+// returns a ZodObject -- so anything holding one has to be one. And the schema does not only
+// validate, it TRANSFORMS: `z.coerce.date()` is why `post.data.date.toISOString()` works and
+// `image()` is why `<Image src={post.data.ogImage}/>` gets ImageMetadata rather than a string.
+// Remove it and the site renders wrong, twice out of three times in silence.
+//
+// `image` AND `reference` ARE ARGUMENTS, NOT IMPORTS. `reference` lives in 'astro:content', a
+// virtual module that resolves only inside an Astro build; importing it here would make this
+// file untestable -- content.config.ts cannot be imported by a test for exactly that
+// reason, which is why the generator lives here and takes what it needs as arguments.
+import { z } from 'astro/zod';
+import { TIME_RE, isDate, isDateTime, isDayDate } from './fields.js';
+import { scheduleErrors } from './schedule.js';
+function values(from, ctx) {
+    const vocab = ctx.vocabularies[from];
+    // THROWS rather than falling back to z.string(). A silent fallback accepts any value, and
+    // the only writer that would notice is a person reading a published page.
+    if (!vocab || vocab.length === 0) {
+        throw new Error(`zodFrom: no vocabulary passed for "${from}". Add a static import for it in `
+            + 'src/content.config.ts and pass it in `vocabularies`.');
+    }
+    const list = vocab.map((v) => v.value);
+    return [list[0], ...list.slice(1)];
+}
+/**
+ * A localized field: an object of the field's own schema, keyed by the site's languages.
+ *
+ * `required` STAYS AT THE FIELD LEVEL, which is the whole of the shape. A required localized
+ * field is a required map; an optional one is an optional map -- `.optional()`, which accepts
+ * the key being ABSENT and refuses `null`, and that is why the migration omits an empty field
+ * rather than writing one. There is no third state where the map exists holding nothing.
+ *
+ * EACH LANGUAGE INSIDE IT IS REQUIRED, whatever the field says, because a present map is a
+ * claim that the site says this -- and a site that says it in one language only is the exact
+ * defect this shape exists to close. « Not filled » is spelled by the map being absent, once,
+ * rather than by each language being separately allowed to be empty.
+ */
+function localizedSchema(f, ctx) {
+    const inner = fieldSchema({ ...f, localized: false, required: true }, ctx);
+    const map = z.object(Object.fromEntries(ctx.locales.map((lang) => [lang, inner])));
+    return f.required === true ? map : map.optional();
+}
+function fieldSchema(f, ctx) {
+    if (f.localized === true && ctx.locales.length > 0)
+        return localizedSchema(f, ctx);
+    const req = f.required === true;
+    switch (f.kind) {
+        case 'line':
+        case 'paragraph':
+        case 'markdown':
+        case 'slug': {
+            const base = req ? z.string().min(1) : z.string();
+            const capped = typeof f.max === 'number' ? base.max(f.max) : base;
+            return req ? capped : capped.optional();
+        }
+        case 'url':
+            // `z.url()`, not `z.string().url()`, which zod v4 deprecates.
+            return req ? z.url() : z.url().optional();
+        case 'date': {
+            // A DAY AND NOTHING ELSE (strict since 2026-09-27). Astro's loader may already have made
+            // the YAML a Date, which for a day is UTC midnight -- a Date anywhere else carried a time,
+            // and a time belongs in a `datetime`. Either spelling comes out as that UTC-midnight Date.
+            const d = z
+                .custom((v) => isDate(v) || isDayDate(v), { message: 'Date attendue (AAAA-MM-JJ).' })
+                .transform((v) => new Date(typeof v === 'string' ? `${v}T00:00:00.000Z` : v.getTime()));
+            return req ? d : d.optional();
+        }
+        case 'datetime': {
+            // An instant with its zone (`fields.ts`). The portal edits it in Quebec time and stores UTC.
+            const d = z
+                .custom((v) => isDateTime(v) || (v instanceof Date && !Number.isNaN(v.getTime())), { message: 'Date et heure attendues (ISO, avec fuseau).' })
+                .transform((v) => new Date(typeof v === 'string' ? Date.parse(v) : v.getTime()));
+            return req ? d : d.optional();
+        }
+        case 'time': {
+            // « HH:MM » on 24 hours, 00:00 to 23:59 -- the portal's `<input type="time">` writes
+            // exactly this, and its tier 1 reads the same `TIME_RE`. The site formats it for display.
+            const t = z.string().regex(TIME_RE);
+            return req ? t : t.optional();
+        }
+        case 'boolean':
+            return z.boolean().default(false);
+        case 'number': {
+            const n = f.int === true ? z.number().int() : z.number();
+            return req ? n : n.optional();
+        }
+        case 'image':
+            // Always optional: an image cannot be required while upload is Phase 4 (design § 8).
+            return ctx.image().optional();
+        case 'reference': {
+            const r = ctx.reference(f.collection);
+            return req ? r : r.optional();
+        }
+        case 'select': {
+            const e = z.enum(values(f.options.from, ctx));
+            return req ? e : e.optional();
+        }
+        case 'multiselect':
+            return z.array(z.enum(values(f.options.from, ctx))).default([]);
+        case 'array':
+            return z.array(objectSchema(f.of, ctx)).default([]);
+    }
+}
+// The shape is built MUTABLY and typed as a plain record, not as `z.ZodRawShape`: zod v4
+// declares that alias `Readonly<...>`, so assigning into it is a compile error. `z.object`
+// accepts the record either way.
+function objectSchema(fields, ctx) {
+    const shape = {};
+    for (const [key, f] of Object.entries(fields))
+        shape[key] = fieldSchema(f, ctx);
+    return z.object(shape);
+}
+/**
+ * Build one collection's schema.
+ *
+ * `contentField` is EXCLUDED. It names the Markdown body, which the portal renders as a box
+ * and which Astro does not treat as a schema field at all -- declaring it would make every
+ * entry fail for a missing `body` key that lives below the frontmatter.
+ *
+ * `T` IS THE ONE THING THE DECLARATION CANNOT CARRY, and the cast below is where it is
+ * admitted rather than hidden. TypeScript widens every string in an imported `.json` to
+ * `string` -- probed 2026-09-21: `typeof schema.blog.fields.title.kind` accepts
+ * `'pas-line'` -- so `kind` is not a literal in the type system and no conditional type can
+ * recover the shape from the file. Without `T`, `post.data` is `Record<string, unknown>`
+ * and `post.data.date.getTime()` stops compiling across the whole site.
+ *
+ * So the caller states the parsed shape once, beside its loader, and
+ * tests/contentSchemaDeclaration.test.ts holds that statement to the JSON's field names --
+ * the one drift a reader would not otherwise see (a field added to the declaration and not
+ * to the type is silently unreachable in every template).
+ */
+export function zodFrom(decl, ctx) {
+    // A schedule pointing at a field that is not a date fails the build that introduced it. The
+    // portal drops the same declaration with a warning instead (`scheduleErrors`).
+    const errors = scheduleErrors(decl);
+    if (errors.length > 0)
+        throw new Error(`zodFrom: ${errors.join(' ; ')}`);
+    const fields = Object.fromEntries(Object.entries(decl.fields).filter(([key]) => key !== decl.contentField));
+    return objectSchema(fields, ctx);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@pmeweb/content",
+  "version": "1.0.0",
+  "description": "PmeWeb content contract: content.schema.json types, zodFrom, field checks, scheduling. Read by every site's build and by the client portal.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./fields": {
+      "types": "./dist/fields.d.ts",
+      "default": "./dist/fields.js"
+    },
+    "./schedule": {
+      "types": "./dist/schedule.d.ts",
+      "default": "./dist/schedule.js"
+    },
+    "./zodFrom": {
+      "types": "./dist/zodFrom.d.ts",
+      "default": "./dist/zodFrom.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build && vitest run"
+  },
+  "devDependencies": {
+    "astro": "7.2.9",
+    "typescript": "6.0.3",
+    "vite": "8.3.0",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "peerDependencies": {
+    "astro": ">=7"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    }
+  }
+}