smoodly 0.0.9 → 0.0.11

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

@@ -1,5 +1,6 @@
 import { section, element } from "./pairing.tsx";
-import { collection, toolset } from "./collections.ts";
+import { collection } from "./collections.ts";
+import { toolset } from "./toolset.ts";
 import { Section } from "./section-wrapper.tsx";
 import { page } from "./render.tsx";
 import { entryPage } from "./entry-page.tsx";
@@ -11,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";
@@ -28,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";
@@ -39,7 +46,8 @@ export type { SmoodlyConfig, ResolvedConfig } from "./config.ts";
 export type { FieldBuilder, Descriptor, ValueOf } from "./fields.ts";
 export type { SectionSchema, ElementSchema, BuilderMap } from "./schema.ts";
 export type { Props, PairedComponent } from "./pairing.tsx";
-export type { CollectionSchema, Toolset, EntryOrder } from "./collections.ts";
+export type { CollectionSchema, EntryOrder } from "./collections.ts";
+export { DEFAULT_TOOLSET, type Toolset, type ToolsetMark, type ToolsetNode } from "./toolset.ts";
 export { collectionOrder, collectionDepth, DEFAULT_ORDER } from "./collections.ts";
 export type { ZonePolicy } from "./zones.ts";
 export { SHARED_NODE_TYPE, STYLES_KEY, sharedLink } from "./shared.ts";

package/dist/index.js

@@ -1,6 +1,7 @@
 import { schema } from "./schema.js";
 import { section, element } from "./pairing.js";
-import { collection, toolset } from "./collections.js";
+import { collection } from "./collections.js";
+import { toolset } from "./toolset.js";
 import { Section } from "./section-wrapper.js";
 import { page } from "./render.js";
 import { entryPage } from "./entry-page.js";
@@ -9,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";
@@ -22,10 +27,11 @@ 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";
+export { DEFAULT_TOOLSET } from "./toolset.js";
 export { collectionOrder, collectionDepth, DEFAULT_ORDER } from "./collections.js";
 export { SHARED_NODE_TYPE, STYLES_KEY, sharedLink } from "./shared.js";
 export { sharedEntryId } from "./shared-id.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[];

package/dist/refs.js

@@ -5,12 +5,32 @@
 // every save; `refs` answers only the REVERSE question (who depends on
 // this?) — forward resolution stays resolveTree's job.
 import { sharedLink } from "./shared.js";
+import { ASSET_COLLECTION, isMediaValue, MEDIA_TYPES } from "./media.js";
 function targetOf(d) {
     const t = d.target?.();
     if (!t?.name)
         throw new Error("smoodly: ref descriptor has no resolvable target.");
     return t.name;
 }
+/** Media edges walk into containers (spec 2026-09-08 media §8); `field`
+ *  stays the top-level key so the edge is addressable like a ref. */
+function collectMedia(field, value, d, out) {
+    if (value == null)
+        return;
+    if (MEDIA_TYPES.has(d.type)) {
+        if (isMediaValue(value))
+            out.push({ field, targetCollection: ASSET_COLLECTION, targetId: value.asset });
+    }
+    else if (d.type === "object" && typeof value === "object" && !Array.isArray(value)) {
+        for (const [k, sub] of Object.entries(d.fields)) {
+            collectMedia(field, value[k], sub, out);
+        }
+    }
+    else if (d.type === "list" && Array.isArray(value)) {
+        for (const v of value)
+            collectMedia(field, v, d.item, out);
+    }
+}
 function collectFrom(values, descriptors, out) {
     for (const [field, d] of Object.entries(descriptors)) {
         const value = values[field];
@@ -25,10 +45,9 @@ function collectFrom(values, descriptors, out) {
                     out.push({ field, targetCollection: targetOf(d), targetId: id });
             }
         }
-        else if (d.type === "object" || d.type === "list") {
-            // Deliberate: refs are top-level only — f.list/f.object refuse them at
-            // build time (spec 2026-09-07, list field §1), so there is nothing to walk.
-            continue;
+        else {
+            // Refs are top-level only (f.list/f.object refuse them); media is not.
+            collectMedia(field, value, d, out);
         }
     }
 }
@@ -56,6 +75,8 @@ export function collectTreeRefs(tree, sections) {
             if (!schema)
                 continue; // fail-soft, same as renderPage
             collectFrom(node.fields, schema.fields, out);
+            if (schema.styles && node.styles)
+                collectFrom(node.styles, schema.styles, out);
         }
     }
     return out;

package/dist/resolve.d.ts

@@ -2,29 +2,44 @@ import type { Descriptor } from "./fields.ts";
 import type { CollectionSchema } from "./collections.ts";
 import type { PageTree } from "./render.tsx";
 import { type SharedSchema } from "./shared.ts";
+import { type AssetRecord } from "./media.ts";
 export type EntryFetcher = (collection: string, ids: string[]) => Promise<Record<string, Record<string, unknown>>>;
+export type AssetFetcher = (ids: string[]) => Promise<Record<string, AssetRecord>>;
 type SchemaLike = {
     name: string;
     fields: Record<string, Descriptor>;
+    styles?: Record<string, Descriptor>;
+};
+/** One value set whose media resolves in place: a node's fields or styles,
+ *  an entry's fields, or an entry hydrated through a ref. */
+export type MediaSet = {
+    values: Record<string, unknown> | undefined;
+    descriptors: Record<string, Descriptor>;
 };
 type ResolveOptions = {
-    sections: ({
-        name: string;
-        fields: Record<string, Descriptor>;
-    } | {
+    sections: (SchemaLike | {
         schema: SchemaLike;
     })[];
     collections: CollectionSchema<any>[];
     fetch: EntryFetcher;
+    /** Media (spec 2026-09-08 §9): one batched asset fetch per page, values become resolved objects. */
+    assets?: AssetFetcher;
     /** The registered shared items a placement node may name (spec 2026-09-07 §4). */
     shared?: SharedSchema[];
     /** Optional safety valve on chain length; unlimited by default. */
     maxDepth?: number;
 };
 export declare function resolveTree(tree: PageTree, options: ResolveOptions): Promise<PageTree>;
+/** One value set's media, resolved in place. Exported for the site layer's shared-item styles. */
+export declare function resolveMedia(values: Record<string, unknown>, descriptors: Record<string, Descriptor>, fetch: AssetFetcher): Promise<void>;
+/** Many value sets, one asset round (plus one for posters): the tree's
+ *  nodes and every entry hydrated through a ref, or a list page's items.
+ *  Exported for the site layer's content API. */
+export declare function resolveMediaSets(sets: MediaSet[], fetch: AssetFetcher): Promise<void>;
 export type ResolveFieldsOptions = {
     collections: CollectionSchema<any>[];
     fetch: EntryFetcher;
+    assets?: AssetFetcher;
     maxDepth?: number;
 };
 /** One entry's fields, refs hydrated — the entry page's counterpart of