@glw907/cairn-cms 0.56.1 → 0.57.0

package/dist/content/types.d.ts

@@ -3,6 +3,7 @@ import type { IconSet } from '../render/glyph.js';
 import type { DatePrefix } from './ids.js';
 import type { ConceptSchema } from './schema.js';
 import type { LinkResolve } from './links.js';
+import type { VariantSpec } from '../media/transform-url.js';
 /** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
 interface FieldBase {
     /** Frontmatter key and form input name. */
@@ -63,11 +64,32 @@ export interface FreeTagsField extends FieldBase {
     placeholder?: string;
 }
 /**
- * The discriminated union the per-concept frontmatter form is generated from. Adding a
- * field type is one variant here plus one decode arm in `frontmatterFromForm` and one in
- * `validateFields`.
+ * A hero image set in frontmatter. The stored value is the nested object
+ * `{ src: string; alt: string; caption?: string }`, where `src` is a 2b `media:` reference, `alt`
+ * is the screen-reader description, and `caption` is an optional line the site template may show.
+ * One image serves two jobs: the template's lead image and the social-card image. The field feeding
+ * the social card is the `seo`-flagged one, defaulting to the field named `image`; a concept declares
+ * at most one SEO image field.
  */
-export type FrontmatterField = TextField | TextareaField | DateField | BooleanField | TagsField | FreeTagsField;
+export interface ImageField extends FieldBase {
+    type: 'image';
+    /** Whether this field feeds the social-card image. The field named `image` defaults to true. */
+    seo?: boolean;
+}
+/**
+ * The discriminated union the per-concept frontmatter form is generated from. A scalar field type
+ * is one variant here plus one decode arm in `frontmatterFromForm` and one in `validateFields`. The
+ * structured `image` field additionally needs a read-back arm in `formValues` and a type-inference
+ * arm in `schema.ts`, since its value is a nested object rather than a single string.
+ */
+export type FrontmatterField = TextField | TextareaField | DateField | BooleanField | TagsField | FreeTagsField | ImageField;
+/** The stored value of an `image` field: a `media:` reference, a screen-reader description, and an
+ *  optional caption. */
+export interface ImageValue {
+    src: string;
+    alt: string;
+    caption?: string;
+}
 /**
  * A validator's verdict. On success it carries the normalized frontmatter to commit; on
  * failure it carries field-keyed error messages (the empty key is a form-level error).
@@ -163,12 +185,28 @@ export interface PreviewConfig {
 /** The flat preview shape `editLoad` ships to the edit page: the top-level `PreviewConfig`
  *  values with the entry's concept override applied, and no `byConcept` map. */
 export type ResolvedPreview = Omit<PreviewConfig, 'byConcept'>;
-/** Reserved asset slot (seam 4). Typed and unused in the rebuild; R7/R9 read it later with no contract change. */
+/** A site's media configuration (seam 4). A site sets this to turn on R2-backed media: uploads,
+ *  content-addressed storage, and Cloudflare Images variants. Omitting it leaves media off. The
+ *  engine normalizes this into a `ResolvedAssetConfig` and merges the named variants over the
+ *  built-in thumb, inline, card, and hero presets. */
 export interface AssetConfig {
-    /** Repo-relative asset roots, e.g. ["static/images"]. */
-    roots: string[];
-    /** Public URL base, e.g. "/images". */
-    publicBase: string;
+    /** The R2 bucket binding name on the Worker, e.g. "MEDIA_BUCKET". Required when a site declares media. */
+    bucketBinding: string;
+    /** The delivery base path. Defaults to "/media". */
+    publicBase?: string;
+    /** Whether the public URL carries the slug ("slug") or stays opaque ("opaque"). Defaults to "slug". */
+    urlForm?: 'slug' | 'opaque';
+    /** The maximum accepted upload size in bytes. Defaults to 25 MB. */
+    maxUploadBytes?: number;
+    /** The accepted upload MIME types. Defaults to the common web image types. */
+    allowedTypes?: string[];
+    /** Named transform presets, merged over the built-in thumb/inline/card/hero presets. */
+    variants?: Record<string, VariantSpec>;
+    /** Whether Cloudflare Image Transformations are enabled for the zone (default false). The feature
+     *  is a per-zone setting that the dashboard or API turns on; it cannot be flipped from a Worker. With
+     *  it off, the media resolver serves the bare full-size delivery path and ignores any preset, so
+     *  thumbnails stay correct (full-size-but-correct) rather than pointing at a dead /cdn-cgi/image URL. */
+    transformations?: boolean;
 }
 /** The single seam the engine consumes. A site implements this at `src/lib/cairn.config.ts`. */
 export interface CairnAdapter {
@@ -185,14 +223,19 @@ export interface CairnAdapter {
     sender: SenderConfig;
     /** The site's one renderer: the editor preview and every public page call it (design decision 4).
      *  `resolve` rewrites cairn: links to live permalinks; the build passes a site-resolver-backed
-     *  one, the preview a manifest one. */
+     *  one, the preview a manifest one. The trailing `resolveMedia` is additive and optional: the build
+     *  passes a site-resolver-backed media resolver, the preview a manifest-backed one. */
     render(md: string, opts?: {
         stagger?: boolean;
         resolve?: LinkResolve;
+        resolveMedia?: import('../render/resolve-media.js').MediaResolve;
     }): string | Promise<string>;
     /** Repo-relative path to the committed content manifest. Defaults to src/content/.cairn/index.json
      *  in composeRuntime. It sits outside any concept directory, so content enumeration never globs it. */
     manifestPath?: string;
+    /** Repo-relative path to the committed media manifest. Defaults to src/content/.cairn/media.json,
+     *  applied in composeRuntime. Sits outside any concept directory, like the content manifest. */
+    mediaManifestPath?: string;
     /** Directive component registry; the renderer and the future palette derive from it (seam 3). */
     registry?: ComponentRegistry;
     /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
@@ -289,12 +332,20 @@ export interface CairnRuntime {
     concepts: ConceptDescriptor[];
     backend: BackendConfig;
     sender: SenderConfig;
-    /** The site's one renderer: the editor preview and every public page call it (design decision 4). */
+    /** The site's one renderer: the editor preview and every public page call it (design decision 4).
+     *  The trailing `resolveMedia` is additive and optional: the build passes a site-resolver-backed
+     *  media resolver, the preview a manifest-backed one. */
     render(md: string, opts?: {
         stagger?: boolean;
         resolve?: LinkResolve;
+        resolveMedia?: import('../render/resolve-media.js').MediaResolve;
     }): string | Promise<string>;
     manifestPath: string;
+    /** The repo-relative path to the committed media manifest, defaulted in composeRuntime. */
+    mediaManifestPath: string;
+    /** The adapter's asset config resolved once at compose: `{ enabled: false }` for a no-media site,
+     *  otherwise the filled config the upload, storage, delivery, and resolver paths read. */
+    resolvedAssets: import('../media/config.js').ResolvedAssetConfig;
     registry?: ComponentRegistry;
     /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
     icons?: IconSet;

package/dist/content/validate.js

@@ -39,6 +39,33 @@ export function validateFields(fields, frontmatter) {
                     data[field.name] = list;
                 break;
             }
+            case 'image': {
+                // A hero is the nested object { src, alt, caption }. Normalize a well-formed value (default
+                // a missing alt to empty, since alt is debt and never a save block), and drop the key when
+                // src is empty or absent. A malformed value (a string, or an object without a string src)
+                // drops the key rather than throwing, so a hand-edit never breaks a save.
+                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;
+                        data[field.name] = normalized;
+                    }
+                }
+                // A required image needs a src (the presence check), like the other arms; alt is never
+                // required, since alt is debt. The inferred type makes a required image non-optional, so the
+                // validator must enforce it or a save could omit it against the type.
+                if (field.required && src === '')
+                    errors[field.name] = `${field.label} is required`;
+                break;
+            }
             case 'date': {
                 const text = value instanceof Date ? dateInputValue(value) : typeof value === 'string' ? value.trim() : '';
                 if (field.required && text === '')

package/dist/delivery/public-routes.d.ts

@@ -2,6 +2,7 @@ import type { ContentSummary, ContentEntry } from './content-index.js';
 import type { SiteResolver } from './site-resolver.js';
 import type { SeoMeta } from './seo.js';
 import type { LinkResolve } from '../content/links.js';
+import type { MediaResolve } from '../render/resolve-media.js';
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
     site: SiteResolver;
@@ -22,6 +23,10 @@ export interface PublicRoutesDeps {
     /** A site-wide default OG image, used when an entry declares none. Resolved to absolute like the
      *  canonical URL, so a relative path such as "/og/default.png" works. */
     defaultImage?: string;
+    /** Resolve a frontmatter `media:` hero reference to its delivery path. The site builds this from its
+     *  committed `media.json` exactly as it builds the body resolver (`makeMediaResolver`). When absent,
+     *  media is off and no `heroImage` projection is derived. */
+    resolveMedia?: MediaResolve;
 }
 /** The archive and tag list data: summaries the template renders. */
 export interface ListData {
@@ -47,6 +52,17 @@ export interface EntryData {
     seo: SeoMeta;
     newer?: ContentSummary;
     older?: ContentSummary;
+    /** The resolved hero image, a derived projection of the frontmatter `image` field. `url` is the
+     *  root-relative delivery path for an `<img>`, `absoluteUrl` the origin-anchored form for the
+     *  og:image, and `alt`/`caption` carry from the stored object. The canonical token is untouched:
+     *  `entry.frontmatter.image.src` stays the `media:` token. Undefined when no hero is set, media is
+     *  off, the reference does not parse, or the resolver finds no asset. */
+    heroImage?: {
+        url: string;
+        absoluteUrl?: string;
+        alt: string;
+        caption?: string;
+    };
 }
 /** Build the public loaders for a site's unified index. */
 export declare function createPublicRoutes(deps: PublicRoutesDeps): {

package/dist/delivery/public-routes.js

@@ -7,9 +7,46 @@ import { error } from '@sveltejs/kit';
 import { buildSeoMeta } from './seo.js';
 import { readSeoFields, resolveImageUrl } from './seo-fields.js';
 import { buildLinkResolver } from './site-resolver.js';
+import { parseMediaToken } from '../media/reference.js';
 /** Build the public loaders for a site's unified index. */
 export function createPublicRoutes(deps) {
-    const { site, render, origin, siteName, description, feeds, defaultImage } = deps;
+    const { site, render, origin, siteName, description, feeds, defaultImage, resolveMedia } = deps;
+    /** Derive the hero projection from an entry's frontmatter, without mutating it (locked decision 5).
+     *  The hero lives at the conventional `image` key as the validated nested object `{ src, alt, caption }`;
+     *  only an image field's validate arm produces an object-with-string-`src` shape, so detecting that
+     *  structure is enough (a text field stores a string, a tags field an array). Returns undefined when
+     *  media is off, no hero is set, the token does not parse, or the resolver finds no asset.
+     *
+     *  Scope: this resolves the `image` key, which is the back-compat SEO default the schema's `seo`
+     *  flag also defaults to. A concept that renames its hero (e.g. `cover`) with `seo: true` validates
+     *  and renders in the editor, but its delivery resolution is not wired here yet, since the field
+     *  declarations are not reachable in the delivery read path. Honoring a renamed `seo`-flagged field
+     *  (and a second image field per concept) at delivery is a carried follow-up; every consumer today
+     *  uses `image`. */
+    function deriveHeroImage(frontmatter) {
+        if (!resolveMedia)
+            return undefined;
+        const value = frontmatter.image;
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const obj = value;
+        if (typeof obj.src !== 'string' || obj.src === '')
+            return undefined;
+        const ref = parseMediaToken(obj.src);
+        if (!ref)
+            return undefined;
+        const path = resolveMedia(ref);
+        if (!path)
+            return undefined;
+        const hero = {
+            url: path,
+            absoluteUrl: resolveImageUrl(path, origin),
+            alt: typeof obj.alt === 'string' ? obj.alt : '',
+        };
+        if (typeof obj.caption === 'string' && obj.caption !== '')
+            hero.caption = obj.caption;
+        return hero;
+    }
     /** Resolve one concept's index by id, or a 404 (the route names an unconfigured concept). */
     function indexOf(conceptId) {
         const index = site.concept(conceptId);
@@ -25,8 +62,13 @@ export function createPublicRoutes(deps) {
         const { newer, older } = site.adjacent(entry);
         const canonicalUrl = origin + entry.permalink;
         const fields = readSeoFields(entry.frontmatter);
+        const heroImage = deriveHeroImage(entry.frontmatter);
+        // The SEO unify (locked decision 3): a resolved structured hero is the social card and wins over
+        // the back-compat string `image` field and the site default. A bare-string `image` keeps its
+        // origin-anchored behavior. An empty hero alt emits no twitter:image:alt.
         const rawImage = fields.image ?? defaultImage;
-        const image = rawImage ? resolveImageUrl(rawImage, origin) : undefined;
+        const image = heroImage?.absoluteUrl ?? (rawImage ? resolveImageUrl(rawImage, origin) : undefined);
+        const imageAlt = heroImage?.alt && heroImage.alt.trim() !== '' ? heroImage.alt : undefined;
         // A dated entry is an article; an undated one (a page) is a website.
         const seo = buildSeoMeta({
             title: entry.title,
@@ -37,11 +79,12 @@ export function createPublicRoutes(deps) {
             ...(entry.date ? { published: entry.date } : {}),
             ...(entry.updated ? { modified: entry.updated } : {}),
             ...(image ? { image } : {}),
+            ...(imageAlt ? { imageAlt } : {}),
             ...(fields.robots ? { robots: fields.robots } : {}),
             ...(fields.author ? { author: fields.author } : {}),
             ...(entry.date ? { feeds } : {}),
         });
-        return { concept: entry.concept, entry, html: await render(entry.body, { stagger: true, resolve: buildLinkResolver(site) }), canonicalUrl, seo, newer, older };
+        return { concept: entry.concept, entry, html: await render(entry.body, { stagger: true, resolve: buildLinkResolver(site) }), canonicalUrl, seo, newer, older, ...(heroImage ? { heroImage } : {}) };
     }
     /** The chronological archive for one concept: every non-draft summary, newest-first. */
     function archiveLoad(conceptId) {

package/dist/delivery/seo-fields.js

@@ -24,7 +24,13 @@ export function readSeoFields(frontmatter) {
  *  that path, per the WHATWG URL rules. */
 export function resolveImageUrl(image, origin) {
     try {
-        return new URL(image, origin).href;
+        const url = new URL(image, origin);
+        // Guard the unresolved-`media:`-token failure mode: `media:photo.<hash>` is a valid URL scheme,
+        // so `new URL(...).href` returns the token verbatim and it would otherwise ship as the og:image.
+        // Only an http or https result is a real social-card URL; anything else degrades to no image.
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return undefined;
+        return url.href;
     }
     catch {
         return undefined;

package/dist/delivery/seo.d.ts

@@ -12,6 +12,8 @@ export interface SeoInput {
         json?: string;
     };
     image?: string;
+    /** The social image's alt text, emitted as twitter:image:alt. Used only when image is also set. */
+    imageAlt?: string;
     /** A robots meta directive, e.g. "noindex, nofollow". Omitted from the head when absent. */
     robots?: string;
     /** Author name, emitted as article:author for the article type. */

package/dist/delivery/seo.js

@@ -16,6 +16,9 @@ export function buildSeoMeta(input) {
     if (input.image) {
         meta.push({ property: 'og:image', content: input.image });
         meta.push({ name: 'twitter:image', content: input.image });
+        if (input.imageAlt) {
+            meta.push({ name: 'twitter:image:alt', content: input.imageAlt });
+        }
     }
     if (input.robots) {
         meta.push({ name: 'robots', content: input.robots });

package/dist/doctor/checks-local.d.ts

@@ -1,5 +1,6 @@
 import type { DoctorCheck } from './types.js';
 export declare const configBindings: DoctorCheck;
+export declare const configMediaBucket: DoctorCheck;
 export declare const configObservability: DoctorCheck;
 export declare const configCsrfDisable: DoctorCheck;
 export declare const configPublicOrigin: DoctorCheck;

package/dist/doctor/checks-local.js

@@ -26,6 +26,27 @@ export const configBindings = {
         return pass('EMAIL and AUTH_DB are declared');
     },
 };
+// The R2 media bucket is never added to the hard config.bindings check, so a no-media site never
+// fails on a missing media binding (decision 9). This conditional runs only when the adapter
+// declares assets, matching the adapter's bucketBinding against wrangler's r2_buckets. It reuses the
+// config.bindings-missing condition rather than registering a new one, so the readiness count holds.
+export const configMediaBucket = {
+    id: 'config.media-bucket',
+    conditionId: 'config.bindings-missing',
+    title: 'Media bucket binding',
+    async run(ctx) {
+        const binding = ctx.mediaBucketBinding;
+        if (binding === undefined)
+            return skip('no media assets configured');
+        const facts = await readWranglerConfig(ctx.readFile);
+        if (facts === null)
+            return NO_WRANGLER;
+        if (!facts.r2Buckets.includes(binding)) {
+            return fail(`adapter declares media bucket ${binding} but no matching r2_buckets binding is in wrangler`);
+        }
+        return pass(`media bucket ${binding} is declared`);
+    },
+};
 export const configObservability = {
     id: 'config.observability',
     conditionId: 'config.observability-off',

package/dist/doctor/index.d.ts

@@ -22,11 +22,13 @@ export declare function contextFromEnv(env: Record<string, string | undefined>,
  *  Vite resolution and the wrangler config's account_id. Each runs only when an input it feeds
  *  is still missing, so a doctor run with full flags touches neither. */
 export interface DerivationSources {
-    /** Returns { owner, repo, from } off the adapter, or null when nothing is derivable. */
+    /** Returns { owner, repo, from, mediaBucketBinding } off the adapter, or null when nothing is
+     *  derivable. */
     adapterFacts: () => Promise<{
         owner?: string;
         repo?: string;
         from?: string;
+        mediaBucketBinding?: string;
     } | null>;
     /** Returns the wrangler config's account_id, or undefined when none is declared. */
     wranglerAccountId: () => Promise<string | undefined>;

package/dist/doctor/index.js

@@ -1,4 +1,4 @@
-import { configBindings, configObservability, configCsrfDisable, configSiteConfig, configPublicOrigin, } from './checks-local.js';
+import { configBindings, configMediaBucket, configObservability, configCsrfDisable, configSiteConfig, configPublicOrigin, } from './checks-local.js';
 import { configDependencyFloors } from './check-floors.js';
 import { emailSenderOnboarded, edgeHttpsForced, edgeHsts, authStore } from './checks-cloudflare.js';
 import { githubApp } from './checks-github.js';
@@ -69,7 +69,12 @@ export function contextFromEnv(env, args, cwd) {
  */
 export async function deriveMissingInputs(ctx, sources) {
     const out = { ...ctx };
-    if (out.from === undefined || out.repo === undefined) {
+    // The adapter read also carries the media bucket binding, which has no env source, so it runs
+    // when from, repo, or the media binding is still missing. A failure leaves each input absent so
+    // its check skips with the usual remediation rather than the doctor crashing.
+    if (out.from === undefined ||
+        out.repo === undefined ||
+        out.mediaBucketBinding === undefined) {
         const facts = await sources.adapterFacts().catch(() => null);
         if (out.from === undefined && typeof facts?.from === 'string') {
             out.from = facts.from;
@@ -79,6 +84,9 @@ export async function deriveMissingInputs(ctx, sources) {
             typeof facts?.repo === 'string') {
             out.repo = `${facts.owner}/${facts.repo}`;
         }
+        if (out.mediaBucketBinding === undefined && typeof facts?.mediaBucketBinding === 'string') {
+            out.mediaBucketBinding = facts.mediaBucketBinding;
+        }
     }
     if (out.cfAccountId === undefined) {
         const accountId = await sources.wranglerAccountId().catch(() => undefined);
@@ -95,6 +103,7 @@ export async function deriveMissingInputs(ctx, sources) {
 export function defaultChecks() {
     return [
         configBindings,
+        configMediaBucket,
         configObservability,
         configCsrfDisable,
         configSiteConfig,

package/dist/doctor/types.d.ts

@@ -30,6 +30,9 @@ export interface DoctorContext {
     cfAccountId?: string;
     /** PUBLIC_ORIGIN, the env fallback when the wrangler vars carry none. */
     publicOrigin?: string;
+    /** The adapter's media bucket binding (cairn.assets.bucketBinding), derived off the adapter.
+     *  Undefined when the site declares no media assets; the media-bucket check skips in that case. */
+    mediaBucketBinding?: string;
     /** GITHUB_APP_ID / GITHUB_APP_INSTALLATION_ID / GITHUB_APP_PRIVATE_KEY_B64. */
     github?: {
         appId: string;

package/dist/doctor/wrangler-config.d.ts

@@ -12,5 +12,8 @@ export interface WranglerFacts {
     publicOrigin?: string;
     /** The top-level account_id, when declared; a fallback for CLOUDFLARE_ACCOUNT_ID. */
     accountId?: string;
+    /** The declared r2_buckets binding names; the conditional media check matches the adapter's
+     *  bucketBinding against this. Not part of the hard config.bindings check (decision 9). */
+    r2Buckets: string[];
 }
 export declare function readWranglerConfig(readFile: DoctorContext['readFile']): Promise<WranglerFacts | null>;

package/dist/doctor/wrangler-config.js

@@ -64,10 +64,17 @@ function factsFromJsonc(text) {
     const databases = Array.isArray(config.d1_databases) ? config.d1_databases : [];
     const authDb = databases.find((entry) => typeof entry === 'object' && entry !== null && entry.binding === 'AUTH_DB');
     const observability = config.observability;
+    const r2 = Array.isArray(config.r2_buckets) ? config.r2_buckets : [];
+    const r2Buckets = r2
+        .map((entry) => typeof entry === 'object' && entry !== null && typeof entry.binding === 'string'
+        ? entry.binding
+        : undefined)
+        .filter((binding) => binding !== undefined);
     const facts = {
         hasEmailBinding,
         hasAuthDb: authDb !== undefined,
         observabilityEnabled: observability?.enabled === true,
+        r2Buckets,
     };
     if (typeof authDb?.database_id === 'string')
         facts.authDbId = authDb.database_id;
@@ -87,10 +94,12 @@ function factsFromToml(text) {
         hasEmailBinding: false,
         hasAuthDb: false,
         observabilityEnabled: false,
+        r2Buckets: [],
     };
     let section = '';
     let d1Binding;
     let d1Id;
+    let r2Binding;
     const flushD1 = () => {
         if (d1Binding === 'AUTH_DB') {
             facts.hasAuthDb = true;
@@ -100,10 +109,16 @@ function factsFromToml(text) {
         d1Binding = undefined;
         d1Id = undefined;
     };
+    const flushR2 = () => {
+        if (r2Binding !== undefined)
+            facts.r2Buckets.push(r2Binding);
+        r2Binding = undefined;
+    };
     for (const line of text.split('\n')) {
         const header = line.match(/^\s*(\[\[?[\w.]+\]?\])\s*(?:#.*)?$/);
         if (header) {
             flushD1();
+            flushR2();
             section = header[1];
             continue;
         }
@@ -121,6 +136,10 @@ function factsFromToml(text) {
             if (key === 'database_id')
                 d1Id = str;
         }
+        else if (section === '[[r2_buckets]]') {
+            if (key === 'binding' && str !== undefined)
+                r2Binding = str;
+        }
         else if (section === '[observability]' && key === 'enabled' && value.startsWith('true')) {
             facts.observabilityEnabled = true;
         }
@@ -132,5 +151,6 @@ function factsFromToml(text) {
         }
     }
     flushD1();
+    flushR2();
     return facts;
 }

package/dist/env.d.ts

@@ -1,4 +1,5 @@
 import type { D1Database } from '@cloudflare/workers-types';
+import type { DeliveryBucket } from './media/delivery-bucket.js';
 /**
  * Returns the site's public origin from configuration.
  *
@@ -22,3 +23,21 @@ export declare function requireOrigin(env: {
 export declare function requireDb(env: {
     AUTH_DB?: D1Database;
 }): D1Database;
+/**
+ * Returns the media R2 bucket named by `bindingName`, or throws a clear error when a site has not
+ * wired it. The binding name is config-derived (the adapter's `bucketBinding`), so it is read off
+ * `env` dynamically rather than as a fixed key.
+ *
+ * The return type is the narrow structural `DeliveryBucket` seam, never the `@cloudflare/workers-types`
+ * `R2Bucket`, so no workers-types name reaches the public `.d.ts` (the delivery route is a public
+ * export and that package is only a devDependency). The cast through `unknown` is sound because the
+ * seam models a subset of the real R2 bucket API.
+ *
+ * The guard rejects a value wired to the wrong kind of binding too (a KV namespace, a string var),
+ * which is truthy but carries no callable `get`. Without that check the cast would succeed and the
+ * first `bucket.get(...)` would throw an uncaught 500 rather than the drained 503 a missing binding
+ * earns.
+ *
+ * @throws CairnError (`config.bindings-missing`) when the named binding is absent or not an R2 bucket.
+ */
+export declare function requireBucket(env: Record<string, unknown>, bindingName: string): DeliveryBucket;

package/dist/env.js

@@ -47,3 +47,29 @@ export function requireDb(env) {
     }
     return env.AUTH_DB;
 }
+/**
+ * Returns the media R2 bucket named by `bindingName`, or throws a clear error when a site has not
+ * wired it. The binding name is config-derived (the adapter's `bucketBinding`), so it is read off
+ * `env` dynamically rather than as a fixed key.
+ *
+ * The return type is the narrow structural `DeliveryBucket` seam, never the `@cloudflare/workers-types`
+ * `R2Bucket`, so no workers-types name reaches the public `.d.ts` (the delivery route is a public
+ * export and that package is only a devDependency). The cast through `unknown` is sound because the
+ * seam models a subset of the real R2 bucket API.
+ *
+ * The guard rejects a value wired to the wrong kind of binding too (a KV namespace, a string var),
+ * which is truthy but carries no callable `get`. Without that check the cast would succeed and the
+ * first `bucket.get(...)` would throw an uncaught 500 rather than the drained 503 a missing binding
+ * earns.
+ *
+ * @throws CairnError (`config.bindings-missing`) when the named binding is absent or not an R2 bucket.
+ */
+export function requireBucket(env, bindingName) {
+    const bucket = env[bindingName];
+    if (!bucket || typeof bucket.get !== 'function') {
+        throw new CairnError('config.bindings-missing', {
+            message: `${bindingName} binding is not configured`,
+        });
+    }
+    return bucket;
+}

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { requireOrigin } from './env.js';
 export type { Role, Editor, AuthEnv } from './auth/types.js';
 export type { AuthBranding, MagicLinkMessage, SendMagicLink } from './email.js';
 export { buildMagicLinkMessage, cloudflareSend } from './email.js';
-export type { CairnAdapter, ConceptConfig, FrontmatterField, TextField, TextareaField, DateField, BooleanField, TagsField, FreeTagsField, ValidationResult, BackendConfig, SenderConfig, NavMenuConfig, PreviewConfig, ResolvedPreview, AssetConfig, RoutingRule, ConceptDescriptor, ConceptUrlPolicy, CairnExtension, CairnRuntime, AdminPanel, FieldTypeDef, } from './content/types.js';
+export type { CairnAdapter, ConceptConfig, FrontmatterField, TextField, TextareaField, DateField, BooleanField, TagsField, FreeTagsField, ImageField, ImageValue, ValidationResult, BackendConfig, SenderConfig, NavMenuConfig, PreviewConfig, ResolvedPreview, AssetConfig, RoutingRule, ConceptDescriptor, ConceptUrlPolicy, CairnExtension, CairnRuntime, AdminPanel, FieldTypeDef, } from './content/types.js';
 export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
 export { composeRuntime } from './content/compose.js';
 export type { ComposeInput } from './content/compose.js';

package/dist/log/events.d.ts

@@ -1 +1 @@
-export type CairnLogEvent = 'auth.link.requested' | 'auth.link.send_failed' | 'auth.token.minted' | 'auth.token.confirmed' | 'auth.session.created' | 'auth.session.destroyed' | 'commit.succeeded' | 'commit.failed' | 'config.invalid' | 'entry.published' | 'entry.discarded' | 'publish.failed' | 'github.unreachable' | 'guard.rejected';
+export type CairnLogEvent = 'auth.link.requested' | 'auth.link.send_failed' | 'auth.token.minted' | 'auth.token.confirmed' | 'auth.session.created' | 'auth.session.destroyed' | 'commit.succeeded' | 'commit.failed' | 'config.invalid' | 'entry.published' | 'entry.discarded' | 'publish.failed' | 'github.unreachable' | 'guard.rejected' | 'media.uploaded' | 'media.upload_failed' | 'media.delivery_failed' | 'media.orphan_reconcile' | 'media.resolve_missing' | 'media.deleted' | 'media.delete_blocked';

package/dist/media/config.d.ts

@@ -0,0 +1,24 @@
+import type { AssetConfig } from '../content/types.js';
+import type { VariantSpec } from './transform-url.js';
+/** The resolved media config the engine serves from. When a site declares no assets block, media is
+ *  off and the value is `{ enabled: false }`; otherwise every field is filled from the AssetConfig
+ *  or its default. */
+export type ResolvedAssetConfig = {
+    enabled: false;
+} | {
+    enabled: true;
+    bucketBinding: string;
+    publicBase: string;
+    urlForm: 'slug' | 'opaque';
+    maxUploadBytes: number;
+    allowedTypes: string[];
+    variants: Record<string, VariantSpec>;
+    /** Whether Cloudflare Image Transformations are enabled for the zone. With it false, the media
+     *  resolver serves the bare full-size delivery path and ignores any preset. */
+    transformations: boolean;
+};
+/** Validate a site's AssetConfig and resolve it into a ResolvedAssetConfig. An undefined block leaves
+ *  media off and returns `{ enabled: false }` rather than throwing. A declared block must name its R2
+ *  bucket and carry a known urlForm and valid variant fit and gravity values; each failure throws a
+ *  cairn:-prefixed error. The named variants merge over the built-in presets. */
+export declare function normalizeAssets(assets: AssetConfig | undefined): ResolvedAssetConfig;