smoodly 0.0.10 → 0.0.12

package/dist/config.js

@@ -1,5 +1,9 @@
 import { assertSegment, fixedPageSegments, perLocaleSegments } from "./paths.js";
-const RESERVED_NAME = "shared"; // the placement node type and the admin route
+import { DEFAULT_MEDIA } from "./media.js";
+/** `shared`: the placement node type and an admin route; `asset`: the refs
+ *  target of every media edge; `media`: the admin's Media screen route. */
+export const RESERVED_NAMES = ["shared", "asset", "media"];
+const isReserved = (name) => RESERVED_NAMES.includes(name);
 function assertUniqueNames(config) {
     const seen = new Set();
     const sectionNameList = (config.registry.sections ?? []).map((s) => s.schema.name);
@@ -11,8 +15,8 @@ function assertUniqueNames(config) {
         ...(config.registry.pages ?? []).filter((p) => p.schema.kind !== "entryPage").map((p) => p.schema.name),
     ];
     for (const name of all) {
-        if (name === RESERVED_NAME)
-            throw new Error(`smoodly: "${RESERVED_NAME}" is a reserved name.`);
+        if (isReserved(name))
+            throw new Error(`smoodly: "${name}" is a reserved name.`);
         if (seen.has(name))
             throw new Error(`smoodly: duplicate registered name "${name}".`);
         seen.add(name);
@@ -29,8 +33,8 @@ function assertUniqueNames(config) {
     const sharedSeen = new Set();
     for (const item of config.registry.shared ?? []) {
         const ownSection = item.name === item.section && sectionNames.has(item.name);
-        if (item.name === RESERVED_NAME)
-            throw new Error(`smoodly: "${RESERVED_NAME}" is a reserved name.`);
+        if (isReserved(item.name))
+            throw new Error(`smoodly: "${item.name}" is a reserved name.`);
         if (sharedSeen.has(item.name) || (seen.has(item.name) && !ownSection)) {
             throw new Error(`smoodly: duplicate registered name "${item.name}".`);
         }
@@ -143,10 +147,18 @@ export function defineConfig(config) {
     }
     const standard = Object.fromEntries(Object.entries(config.styles?.sections ?? {}).map(([k, b]) => [k, b.descriptor]));
     const byName = new Map((config.registry.sections ?? []).map((s) => [s.schema.name, s.schema]));
+    const media = {
+        maxSize: config.media?.maxSize ?? DEFAULT_MEDIA.maxSize,
+        accept: config.media?.accept ? [...config.media.accept] : [...DEFAULT_MEDIA.accept],
+    };
+    if (!Number.isInteger(media.maxSize) || media.maxSize <= 0) {
+        throw new Error("smoodly: media.maxSize must be a positive integer of bytes.");
+    }
     return {
         ...config,
         homePageSlug,
         pageDepth: depth,
+        media,
         resolvedStyles(sectionName) {
             const schema = byName.get(sectionName);
             if (!schema)

package/dist/fields.d.ts

@@ -1,4 +1,5 @@
 import { type Toolset } from "./toolset.ts";
+import { type ResolvedFile, type ResolvedImage, type ResolvedVideo } from "./media.ts";
 export type Descriptor = {
     type: string;
     [key: string]: unknown;
@@ -49,16 +50,13 @@ export declare const f: {
     }) => FieldBuilder<string, {}>;
     date: () => FieldBuilder<string, {}>;
     number: () => FieldBuilder<number, {}>;
-    image: () => FieldBuilder<{
-        url: string;
-        alt?: string;
-    }, {}>;
-    video: () => FieldBuilder<{
-        url: string;
-    }, {}>;
-    file: () => FieldBuilder<{
-        url: string;
-    }, {}>;
+    /** `aspect`: one `"w:h"` or several the crop tool may lock to — a per-use
+     *  constraint, so the component knows its box before the image loads. */
+    image: (opts?: {
+        aspect?: string | string[];
+    }) => FieldBuilder<ResolvedImage, {}>;
+    video: () => FieldBuilder<ResolvedVideo, {}>;
+    file: () => FieldBuilder<ResolvedFile, {}>;
     richtext: (opts?: {
         toolset?: Toolset;
     }) => FieldBuilder<unknown, {}>;

package/dist/fields.js

@@ -2,6 +2,7 @@
 // f.text().max(40) is plain data; validation logic lives server/admin-side,
 // keyed by descriptor type. Chaining is immutable.
 import { DEFAULT_TOOLSET } from "./toolset.js";
+import { parseAspect } from "./media.js";
 function builder(descriptor) {
     const chain = (patch) => builder({ ...descriptor, ...patch });
     return {
@@ -56,7 +57,19 @@ export const f = {
     slug: (opts) => builder({ type: "slug", ...(opts?.from ? { from: opts.from } : {}) }),
     date: () => builder({ type: "date" }),
     number: () => builder({ type: "number" }),
-    image: () => builder({ type: "image" }),
+    /** `aspect`: one `"w:h"` or several the crop tool may lock to — a per-use
+     *  constraint, so the component knows its box before the image loads. */
+    image: (opts) => {
+        const aspect = opts?.aspect;
+        if (aspect !== undefined) {
+            const list = Array.isArray(aspect) ? aspect : [aspect];
+            if (list.length === 0)
+                throw new Error('smoodly: f.image aspect must name at least one "w:h" ratio.');
+            for (const a of list)
+                parseAspect(a);
+        }
+        return builder({ type: "image", ...(aspect !== undefined ? { aspect } : {}) });
+    },
     video: () => builder({ type: "video" }),
     file: () => builder({ type: "file" }),
     richtext: (opts) => builder({ type: "richtext", toolset: opts?.toolset ?? DEFAULT_TOOLSET }),

package/dist/image/SmoodlyImage.d.ts

@@ -0,0 +1,18 @@
+import type { CSSProperties, ReactElement } from "react";
+import type { ResolvedImage } from "../media.ts";
+import type { ImageLoader } from "./loaders.ts";
+export type SmoodlyImageProps = {
+    image: ResolvedImage;
+    /** Overrides the value's aspect for this placement (`"21:9"`). */
+    aspect?: string;
+    sizes?: string;
+    priority?: boolean;
+    loading?: "eager" | "lazy";
+    className?: string;
+    style?: CSSProperties;
+    /** Overrides the resolved alt (rarely right — the editor owns it). */
+    alt?: string;
+    loader?: ImageLoader;
+    unoptimized?: boolean;
+};
+export declare function SmoodlyImage({ image, aspect, sizes, priority, loading, className, style, alt, loader, unoptimized }: SmoodlyImageProps): ReactElement;

package/dist/image/SmoodlyImage.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// <SmoodlyImage>: a box at the aspect (declared, chosen or natural), the
+// image inside positioned by crop and hotspot, dimensions set so nothing
+// shifts. Wraps next/image; the only file besides SmoodlyVideo that a
+// site imports from the media layer. Server-safe — no "use client".
+import Image from "next/image";
+import { boxAspectOf, frameFor } from "./crop-math.js";
+export function SmoodlyImage({ image, aspect, sizes, priority, loading, className, style, alt, loader, unoptimized }) {
+    const box = boxAspectOf(image, aspect);
+    const frame = loader?.handlesCrop ? { left: 0, top: 0, width: 100, height: 100 } : frameFor(image, box);
+    const svg = image.mime === "image/svg+xml";
+    return (_jsx("span", { className: className, style: { display: "block", position: "relative", overflow: "hidden", aspectRatio: String(box), ...style }, children: _jsx(Image, { src: image.url, alt: alt ?? image.alt, width: image.width, height: image.height, sizes: sizes, priority: priority, loading: loading, unoptimized: unoptimized ?? svg, ...(loader ? { loader: ({ width, quality }) => loader.url(image, { width, quality }) } : {}), style: {
+                position: "absolute", left: `${frame.left}%`, top: `${frame.top}%`,
+                width: `${frame.width}%`, height: `${frame.height}%`, maxWidth: "none",
+            } }) }));
+}

package/dist/image/SmoodlyVideo.d.ts

@@ -0,0 +1,7 @@
+import type { ReactElement, VideoHTMLAttributes } from "react";
+import type { ResolvedVideo } from "../media.ts";
+export type SmoodlyVideoProps = {
+    video: ResolvedVideo;
+} & Omit<VideoHTMLAttributes<HTMLVideoElement>, "src" | "poster" | "width" | "height">;
+/** A <video> over the bucket's CDN with its poster and size. No transcoding (spec §9). */
+export declare function SmoodlyVideo({ video, ...rest }: SmoodlyVideoProps): ReactElement;

package/dist/image/SmoodlyVideo.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/** A <video> over the bucket's CDN with its poster and size. No transcoding (spec §9). */
+export function SmoodlyVideo({ video, ...rest }) {
+    return (_jsx("video", { src: video.url, poster: video.poster?.url, width: video.width, height: video.height, playsInline: true, ...rest }));
+}

package/dist/image/crop-math.d.ts

@@ -0,0 +1,14 @@
+import { type Crop, type Hotspot, type ResolvedImage } from "../media.ts";
+export type Frame = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+export declare function boxAspectOf(image: ResolvedImage, override?: string): number;
+export declare function frameFor(image: {
+    width: number;
+    height: number;
+    crop?: Crop;
+    hotspot?: Hotspot;
+}, boxAspect: number): Frame;

package/dist/image/crop-math.js

@@ -0,0 +1,38 @@
+// The render-side frame: where the image sits inside its box so the crop
+// covers it and the hotspot stays as central as the crop allows. Box
+// units: height 1, width = the box's aspect. Percentages out, so the
+// component never needs the box's pixel size (spec 2026-09-08 media §9).
+import { CENTER_HOTSPOT, FULL_CROP, clamp01, cropAspect, parseAspect } from "../media.js";
+export function boxAspectOf(image, override) {
+    if (override)
+        return parseAspect(override);
+    if (image.aspect)
+        return parseAspect(image.aspect);
+    const imageAspect = image.width / image.height;
+    return image.crop ? cropAspect(image.crop, imageAspect) : imageAspect;
+}
+export function frameFor(image, boxAspect) {
+    const crop = image.crop ?? FULL_CROP;
+    const hotspot = image.hotspot ?? CENTER_HOTSPOT;
+    const imageAspect = image.width / image.height;
+    const ca = cropAspect(crop, imageAspect);
+    // Scale the image so the crop covers the box: fit the crop's height when
+    // the crop is wider than the box, its width when it is taller.
+    let w, h;
+    if (ca >= boxAspect) {
+        h = 1 / crop.height;
+        w = h * imageAspect;
+    }
+    else {
+        w = boxAspect / crop.width;
+        h = w / imageAspect;
+    }
+    const cropW = crop.width * w, cropH = crop.height * h;
+    const hx = clamp01((hotspot.x - crop.left) / crop.width);
+    const hy = clamp01((hotspot.y - crop.top) / crop.height);
+    const winLeft = Math.min(Math.max(hx * cropW - boxAspect / 2, 0), Math.max(cropW - boxAspect, 0));
+    const winTop = Math.min(Math.max(hy * cropH - 0.5, 0), Math.max(cropH - 1, 0));
+    const left = -(crop.left * w) - winLeft;
+    const top = -(crop.top * h) - winTop;
+    return { left: (left / boxAspect) * 100, top: top * 100, width: (w / boxAspect) * 100, height: h * 100 };
+}

package/dist/image/index.d.ts

@@ -0,0 +1,6 @@
+export { SmoodlyImage, type SmoodlyImageProps } from "./SmoodlyImage.tsx";
+export { SmoodlyVideo, type SmoodlyVideoProps } from "./SmoodlyVideo.tsx";
+export { imageUrl, nextLoader, type ImageLoader, type ImageUrlOptions } from "./loaders.ts";
+export { frameFor, boxAspectOf, type Frame } from "./crop-math.ts";
+export { smoodlyImages, isPrivateHost, type RemotePattern, type SmoodlyImagesConfig } from "./next-config.ts";
+export type { ResolvedImage, ResolvedVideo, ResolvedFile, Crop, Hotspot } from "../media.ts";

package/dist/image/index.js

@@ -0,0 +1,5 @@
+export { SmoodlyImage } from "./SmoodlyImage.js";
+export { SmoodlyVideo } from "./SmoodlyVideo.js";
+export { imageUrl, nextLoader } from "./loaders.js";
+export { frameFor, boxAspectOf } from "./crop-math.js";
+export { smoodlyImages, isPrivateHost } from "./next-config.js";

package/dist/image/loaders.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedImage } from "../media.ts";
+export type ImageUrlOptions = {
+    width?: number;
+    quality?: number;
+    format?: string;
+};
+export type ImageLoader = {
+    name: string;
+    /** True when the URL already applies crop and hotspot. */
+    handlesCrop: boolean;
+    url(image: ResolvedImage, opts: ImageUrlOptions): string;
+};
+export declare const nextLoader: ImageLoader;
+/** The escape hatch: a URL for a width, through the loader. */
+export declare function imageUrl(image: ResolvedImage, opts?: ImageUrlOptions, loader?: ImageLoader): string;

package/dist/image/loaders.js

@@ -0,0 +1,5 @@
+export const nextLoader = { name: "next", handlesCrop: false, url: (image) => image.url };
+/** The escape hatch: a URL for a width, through the loader. */
+export function imageUrl(image, opts = {}, loader = nextLoader) {
+    return loader.url(image, opts);
+}

package/dist/image/next-config.d.ts

@@ -0,0 +1,15 @@
+export type RemotePattern = {
+    protocol: "http" | "https";
+    hostname: string;
+    port?: string;
+    pathname: string;
+};
+export type SmoodlyImagesConfig = {
+    remotePatterns: RemotePattern[];
+    dangerouslyAllowLocalIP?: true;
+};
+/** `localhost`, loopback and the RFC 1918 ranges — the hosts a local
+ * Supabase stack answers on. A public hostname that happens to resolve
+ * privately (a Docker alias) is not detected; set the flag by hand then. */
+export declare function isPrivateHost(hostname: string): boolean;
+export declare function smoodlyImages(url?: string | undefined): SmoodlyImagesConfig;

package/dist/image/next-config.js

@@ -0,0 +1,27 @@
+/** `localhost`, loopback and the RFC 1918 ranges — the hosts a local
+ * Supabase stack answers on. A public hostname that happens to resolve
+ * privately (a Docker alias) is not detected; set the flag by hand then. */
+export function isPrivateHost(hostname) {
+    const h = hostname.replace(/^\[|\]$/g, "");
+    if (h === "localhost" || h.endsWith(".localhost") || h === "::1")
+        return true;
+    const m = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(h);
+    if (!m)
+        return false;
+    const [a, b] = [Number(m[1]), Number(m[2])];
+    return a === 127 || a === 10 || (a === 192 && b === 168) || (a === 172 && b >= 16 && b <= 31);
+}
+export function smoodlyImages(url = process.env.SMOODLY_URL) {
+    if (!url) {
+        console.warn("smoodly: SMOODLY_URL is not set — next/image will refuse Supabase media URLs until it is.");
+        return { remotePatterns: [] };
+    }
+    const u = new URL(url);
+    const pattern = {
+        protocol: u.protocol === "http:" ? "http" : "https",
+        hostname: u.hostname,
+        ...(u.port ? { port: u.port } : {}),
+        pathname: "/storage/v1/object/public/media/**",
+    };
+    return { remotePatterns: [pattern], ...(isPrivateHost(u.hostname) ? { dangerouslyAllowLocalIP: true } : {}) };
+}

package/dist/image-dimensions.d.ts

@@ -0,0 +1,4 @@
+export declare function imageDimensions(bytes: Uint8Array): {
+    width: number;
+    height: number;
+} | null;

package/dist/image-dimensions.js

@@ -0,0 +1,25 @@
+// Header-only image dimensions for the two formats the starter ships
+// (JPEG, PNG). The seed and AssetStore.create use it server-side, where
+// there is no <img> to measure with and no sharp to depend on. Null for
+// anything else — the row then carries no dimensions.
+export function imageDimensions(bytes) {
+    if (bytes.length >= 24 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        return { width: view.getUint32(16), height: view.getUint32(20) };
+    }
+    if (bytes.length >= 4 && bytes[0] === 0xff && bytes[1] === 0xd8) {
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        let i = 2;
+        while (i + 9 < bytes.length) {
+            if (bytes[i] !== 0xff)
+                return null;
+            const marker = bytes[i + 1];
+            // SOF0..SOF15 except DHT (C4), JPG (C8) and DAC (CC) carry the frame size
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                return { height: view.getUint16(i + 5), width: view.getUint16(i + 7) };
+            }
+            i += 2 + view.getUint16(i + 2);
+        }
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -12,11 +12,17 @@ export type { PageSchema } from "./page.ts";
 export { fixedSlug } from "./page.ts";
 export type { EntryPageSchema, PairedEntryPage, EntryPageProps } from "./entry-page.tsx";
 export { f } from "./fields.ts";
+export { ASSET_COLLECTION, DEFAULT_MEDIA, MEDIA_TYPES, FULL_CROP, CENTER_HOTSPOT, parseAspect, cropAspect, clamp01, isMediaValue, collectAssetIds, applyAssets, } from "./media.ts";
+export type { Crop, Hotspot, AssetKind, ImageValue, VideoValue, FileValue, AssetMeta, AssetRecord, ResolvedImage, ResolvedVideo, ResolvedFile, } from "./media.ts";
 export { z } from "./zones.ts";
 export { defineConfig } from "./config.ts";
 export { collectionSQL, coreTablesSQL } from "./sql.ts";
 export { MemoryPageStore } from "./store.ts";
+export { MemoryAssetStore, assetErrors, kindOf, extensionFor, objectPath, withDownload, PAGE_SIZE as ASSET_PAGE_SIZE } from "./asset-store.ts";
+export type { AssetStore, UploadTicket, FinishInput, AssetQuery, AssetPage, BeginUploadInput, CreateAssetInput } from "./asset-store.ts";
+export { imageDimensions } from "./image-dimensions.ts";
 export { SupabasePageStore } from "./supabase-store.ts";
+export { SupabaseAssetStore } from "./supabase-asset-store.ts";
 export { collectEntryRefs, collectTreeRefs } from "./refs.ts";
 export type { RefEdge, SectionLike } from "./refs.ts";
 export { MemoryRefIndex } from "./ref-index.ts";
@@ -29,8 +35,8 @@ export type { EntryStore, EntryRecord, EntryLocale, EntryVersion, EntryUsage, Li
 export { entryErrors, compareEntries, DEFAULT_ENTRY_LOCALES, localizedKeys, splitFields, entryLocaleRow, entryFieldsIn, entryRefEdges, entryTitleIn, } from "./entry-store.ts";
 export { affectedTargets, pageTag, entryTag, sharedTag } from "./revalidate.ts";
 export type { AffectedTargets } from "./revalidate.ts";
-export { resolveTree, resolveFields } from "./resolve.ts";
-export type { EntryFetcher, ResolveFieldsOptions } from "./resolve.ts";
+export { resolveTree, resolveFields, resolveMedia } from "./resolve.ts";
+export type { EntryFetcher, ResolveFieldsOptions, AssetFetcher } from "./resolve.ts";
 export { SEGMENT_RE, isSegment, assertSegment, joinPath, splitPath, segmentFor, isHomeNode, pagePathIn, chainOf, assertDepth, pagePath, pagePathRows, entryPathRows, collectionSegment, buildPageTree, perLocaleSegments, assertSupportedLocale, unsupportedLocale, } from "./paths.ts";
 export type { LocaleSet, PathTarget, PathRow, PageLike, EntryLike, PageTreeNode, PagePathOptions } from "./paths.ts";
 export { fixedPathFor } from "./localize.ts";

package/dist/index.js

@@ -10,11 +10,15 @@ export { Zone, renderPage, EMPTY_PAGE_CONTEXT } from "./render.js";
 export { RichText } from "./richtext-render.js";
 export { fixedSlug } from "./page.js";
 export { f } from "./fields.js";
+export { ASSET_COLLECTION, DEFAULT_MEDIA, MEDIA_TYPES, FULL_CROP, CENTER_HOTSPOT, parseAspect, cropAspect, clamp01, isMediaValue, collectAssetIds, applyAssets, } from "./media.js";
 export { z } from "./zones.js";
 export { defineConfig } from "./config.js";
 export { collectionSQL, coreTablesSQL } from "./sql.js";
 export { MemoryPageStore } from "./store.js";
+export { MemoryAssetStore, assetErrors, kindOf, extensionFor, objectPath, withDownload, PAGE_SIZE as ASSET_PAGE_SIZE } from "./asset-store.js";
+export { imageDimensions } from "./image-dimensions.js";
 export { SupabasePageStore } from "./supabase-store.js";
+export { SupabaseAssetStore } from "./supabase-asset-store.js";
 export { collectEntryRefs, collectTreeRefs } from "./refs.js";
 export { MemoryRefIndex } from "./ref-index.js";
 export { MemoryPathIndex } from "./path-index.js";
@@ -23,7 +27,7 @@ export { SupabaseEntryStore } from "./supabase-entry-store.js";
 export { SupabasePathIndex } from "./supabase-path-index.js";
 export { entryErrors, compareEntries, DEFAULT_ENTRY_LOCALES, localizedKeys, splitFields, entryLocaleRow, entryFieldsIn, entryRefEdges, entryTitleIn, } from "./entry-store.js";
 export { affectedTargets, pageTag, entryTag, sharedTag } from "./revalidate.js";
-export { resolveTree, resolveFields } from "./resolve.js";
+export { resolveTree, resolveFields, resolveMedia } from "./resolve.js";
 export { SEGMENT_RE, isSegment, assertSegment, joinPath, splitPath, segmentFor, isHomeNode, pagePathIn, chainOf, assertDepth, pagePath, pagePathRows, entryPathRows, collectionSegment, buildPageTree, perLocaleSegments, assertSupportedLocale, unsupportedLocale, } from "./paths.js";
 export { fixedPathFor } from "./localize.js";
 export { pathOptions, pageErrors, localeRow, pageRefEdges, DEFAULT_LOCALES } from "./store.js";

package/dist/media.d.ts

@@ -0,0 +1,108 @@
+import type { Descriptor } from "./fields.ts";
+export type Crop = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+export type Hotspot = {
+    x: number;
+    y: number;
+};
+export type AssetKind = "image" | "video" | "file";
+export type ImageValue = {
+    asset: string;
+    alt?: string;
+    crop?: Crop;
+    hotspot?: Hotspot;
+    aspect?: string;
+};
+export type VideoValue = {
+    asset: string;
+    title?: string;
+};
+export type FileValue = {
+    asset: string;
+    title?: string;
+};
+export type AssetMeta = {
+    title?: string | null;
+    alt?: string | null;
+    caption?: string | null;
+    credit?: string | null;
+};
+export type AssetRecord = {
+    id: string;
+    kind: AssetKind;
+    status: "pending" | "ready";
+    /** The object path in the bucket: `<space_id>/<id>.<ext>`. */
+    path: string;
+    mime: string;
+    size: number;
+    width: number | null;
+    height: number | null;
+    duration: number | null;
+    posterId: string | null;
+    filename: string;
+    title: string | null;
+    alt: string | null;
+    caption: string | null;
+    credit: string | null;
+    /** Derived by the store from the bucket's public URL, never stored. */
+    url: string;
+    createdAt: number;
+    updatedAt: number;
+};
+export type ResolvedImage = {
+    url: string;
+    width: number;
+    height: number;
+    mime: string;
+    alt: string;
+    crop?: Crop;
+    hotspot?: Hotspot;
+    aspect?: string;
+};
+export type ResolvedVideo = {
+    url: string;
+    width?: number;
+    height?: number;
+    duration?: number;
+    mime: string;
+    poster?: ResolvedImage;
+    title?: string;
+};
+export type ResolvedFile = {
+    url: string;
+    mime: string;
+    size: number;
+    filename: string;
+    title?: string;
+};
+/** The refs target collection of every asset edge — a reserved registered name. */
+export declare const ASSET_COLLECTION = "asset";
+export declare const MEDIA_TYPES: ReadonlySet<string>;
+/** Cache lifetime of a media object, in seconds — a year. Objects are
+ *  immutable (no upsert; Replace picks a new id), so the CDN, the browser
+ *  and next/image may keep one for as long as they like. */
+export declare const MEDIA_CACHE_SECONDS = 31536000;
+export declare const DEFAULT_MEDIA: {
+    readonly maxSize: number;
+    readonly accept: readonly ["image/jpeg", "image/png", "image/webp", "image/avif", "image/gif", "image/svg+xml", "video/mp4", "video/webm", "application/pdf"];
+};
+export declare const FULL_CROP: Crop;
+export declare const CENTER_HOTSPOT: Hotspot;
+export declare const clamp01: (n: number) => number;
+/** `"16:9"` → 16/9. Throws on anything else, so a typo fails at registration. */
+export declare function parseAspect(s: string): number;
+/** The crop's own pixel ratio, given the image's. */
+export declare const cropAspect: (crop: Crop, imageAspect: number) => number;
+export declare const isMediaValue: (v: unknown) => v is {
+    asset: string;
+};
+/** Every asset id a value set references, walking lists and objects —
+ *  unlike refs, media may sit inside a container (spec §8). */
+export declare function collectAssetIds(values: Record<string, unknown> | undefined, descriptors: Record<string, Descriptor>, out: Set<string>): void;
+/** Replace every media value in place with its resolved object — or delete
+ *  it when the asset is missing or pending, so `image?.url` guards hold. */
+export declare function applyAssets(values: Record<string, unknown> | undefined, descriptors: Record<string, Descriptor>, assets: Map<string, AssetRecord>): void;

package/dist/media.js

@@ -0,0 +1,129 @@
+/** The refs target collection of every asset edge — a reserved registered name. */
+export const ASSET_COLLECTION = "asset";
+export const MEDIA_TYPES = new Set(["image", "video", "file"]);
+/** Cache lifetime of a media object, in seconds — a year. Objects are
+ *  immutable (no upsert; Replace picks a new id), so the CDN, the browser
+ *  and next/image may keep one for as long as they like. */
+export const MEDIA_CACHE_SECONDS = 31536000;
+export const DEFAULT_MEDIA = {
+    maxSize: 25 * 1024 * 1024,
+    accept: [
+        "image/jpeg", "image/png", "image/webp", "image/avif", "image/gif", "image/svg+xml",
+        "video/mp4", "video/webm", "application/pdf",
+    ],
+};
+export const FULL_CROP = { left: 0, top: 0, width: 1, height: 1 };
+export const CENTER_HOTSPOT = { x: 0.5, y: 0.5 };
+export const clamp01 = (n) => Math.min(1, Math.max(0, n));
+const ASPECT_RE = /^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?)$/;
+/** `"16:9"` → 16/9. Throws on anything else, so a typo fails at registration. */
+export function parseAspect(s) {
+    const m = ASPECT_RE.exec(s);
+    const w = m ? Number(m[1]) : 0;
+    const h = m ? Number(m[2]) : 0;
+    if (!m || w <= 0 || h <= 0)
+        throw new Error(`smoodly: "${s}" is not an aspect — use "w:h", like "16:9".`);
+    return w / h;
+}
+/** The crop's own pixel ratio, given the image's. */
+export const cropAspect = (crop, imageAspect) => (crop.width * imageAspect) / crop.height;
+export const isMediaValue = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && typeof v.asset === "string";
+/** Every asset id a value set references, walking lists and objects —
+ *  unlike refs, media may sit inside a container (spec §8). */
+export function collectAssetIds(values, descriptors, out) {
+    if (!values)
+        return;
+    for (const [key, d] of Object.entries(descriptors)) {
+        const value = values[key];
+        if (value == null)
+            continue;
+        if (MEDIA_TYPES.has(d.type)) {
+            if (isMediaValue(value))
+                out.add(value.asset);
+        }
+        else if (d.type === "object" && typeof value === "object" && !Array.isArray(value)) {
+            collectAssetIds(value, d.fields, out);
+        }
+        else if (d.type === "list" && Array.isArray(value)) {
+            const item = d.item;
+            for (const v of value) {
+                if (MEDIA_TYPES.has(item.type)) {
+                    if (isMediaValue(v))
+                        out.add(v.asset);
+                }
+                else if (item.type === "object" && v && typeof v === "object") {
+                    collectAssetIds(v, item.fields, out);
+                }
+            }
+        }
+    }
+}
+function resolvedImage(asset, value, d) {
+    if (asset.width === null || asset.height === null)
+        return undefined;
+    const declared = d.aspect;
+    const aspect = value.aspect ?? (typeof declared === "string" ? declared : undefined);
+    return {
+        url: asset.url, width: asset.width, height: asset.height, mime: asset.mime,
+        alt: value.alt ?? asset.alt ?? "",
+        ...(value.crop ? { crop: value.crop } : {}),
+        ...(value.hotspot ? { hotspot: value.hotspot } : {}),
+        ...(aspect ? { aspect } : {}),
+    };
+}
+function resolveOne(value, d, assets) {
+    if (!isMediaValue(value))
+        return undefined;
+    const asset = assets.get(value.asset);
+    if (!asset || asset.status !== "ready")
+        return undefined;
+    if (d.type === "image")
+        return resolvedImage(asset, value, d);
+    if (d.type === "video") {
+        const v = value;
+        const poster = asset.posterId ? assets.get(asset.posterId) : undefined;
+        const posterResolved = poster ? resolvedImage(poster, { asset: poster.id }, { type: "image" }) : undefined;
+        return {
+            url: asset.url, mime: asset.mime,
+            ...(asset.width !== null ? { width: asset.width } : {}),
+            ...(asset.height !== null ? { height: asset.height } : {}),
+            ...(asset.duration !== null ? { duration: asset.duration } : {}),
+            ...(v.title ? { title: v.title } : {}),
+            ...(posterResolved ? { poster: posterResolved } : {}),
+        };
+    }
+    const f = value;
+    return { url: asset.url, mime: asset.mime, size: asset.size, filename: asset.filename, ...(f.title ? { title: f.title } : {}) };
+}
+/** Replace every media value in place with its resolved object — or delete
+ *  it when the asset is missing or pending, so `image?.url` guards hold. */
+export function applyAssets(values, descriptors, assets) {
+    if (!values)
+        return;
+    for (const [key, d] of Object.entries(descriptors)) {
+        const value = values[key];
+        if (value == null)
+            continue;
+        if (MEDIA_TYPES.has(d.type)) {
+            const resolved = resolveOne(value, d, assets);
+            if (resolved === undefined)
+                delete values[key];
+            else
+                values[key] = resolved;
+        }
+        else if (d.type === "object" && typeof value === "object" && !Array.isArray(value)) {
+            applyAssets(value, d.fields, assets);
+        }
+        else if (d.type === "list" && Array.isArray(value)) {
+            const item = d.item;
+            if (MEDIA_TYPES.has(item.type)) {
+                values[key] = value.map((v) => resolveOne(v, item, assets)).filter((v) => v !== undefined);
+            }
+            else if (item.type === "object") {
+                for (const v of value)
+                    if (v && typeof v === "object")
+                        applyAssets(v, item.fields, assets);
+            }
+        }
+    }
+}

package/dist/refs.d.ts

@@ -11,10 +11,12 @@ export declare function collectEntryRefs(fields: Record<string, unknown>, schema
 export type SectionLike = {
     name: string;
     fields: Record<string, Descriptor>;
+    styles?: Record<string, Descriptor>;
 } | {
     schema: {
         name: string;
         fields: Record<string, Descriptor>;
+        styles?: Record<string, Descriptor>;
     };
 };
 export declare function collectTreeRefs(tree: PageTree, sections: SectionLike[]): RefEdge[];