smoodly 0.0.10 → 0.0.11

package/README.md

@@ -131,6 +131,19 @@ Implemented:
   store constructor options (`sections`, `entries`, shared
   `MemoryRefIndex` in memory); the cross-store contract
   (`test/page-refs-contract.ts`) runs against memory AND Supabase.
+- Media (spec 2026-09-08): `f.image({ aspect? })` / `f.video()` / `f.file()`
+  store `{ asset, alt?, crop?, hotspot?, aspect? }`; `AssetStore` (memory +
+  `SupabaseAssetStore`: rows in `assets`, bytes in the public `media`
+  bucket, two-op signed uploads); the refs index carries `asset` edges
+  through lists, objects and styles, so delete is guarded and usage is
+  listed; `resolveTree`/`resolveFields`/the site layer resolve media to
+  `{ url, width, height, mime, alt, crop?, hotspot?, aspect? }` with one
+  fetch per page; `smoodly/image` ships `<SmoodlyImage>` (a box at the
+  aspect, the image framed by crop and hotspot over `next/image`),
+  `<SmoodlyVideo>`, `imageUrl` behind the loader seam (v1: the Next
+  loader only) and `smoodlyImages()` for next.config's `images`. Admin: the media
+  widget in every form, the library picker, the crop-and-hotspot editor,
+  the Media screen with metadata, usage links and guarded delete.
 - `EntryStore` contract + `MemoryEntryStore` + `SupabaseEntryStore` —
   collection-entry persistence over entries/entry_locales/entry_versions/paths
   — one node, one row per locale, each locale with its own slug, status
@@ -297,6 +310,13 @@ Implemented:
   derives every URL from it, and `pages.get(id)` hands the admin the
   finished `paths` (locale → CMS path) and `urls` (`href` applied), so the
   admin no longer derives a path of its own.
+- `smoodly/image` — the site's media components: `<SmoodlyImage>`,
+  `<SmoodlyVideo>`, `imageUrl(image, { width, quality? }, loader?)`,
+  `frameFor`/`boxAspectOf` (the crop math) and `smoodlyImages()` for
+  `next.config`'s `images`: the Supabase host as a remote pattern, plus
+  `dangerouslyAllowLocalIP` when that host is loopback or private — Next
+  16's optimizer refuses a private upstream otherwise, and the local stack
+  is one. Server-safe, no `"use client"`.
 
 - Locked zones are usable: `fillLockedZones` (a pure tree op) materializes
   the one node of every empty locked zone from the component's `sample`
@@ -398,10 +418,63 @@ site at the tagged commit.
 - Pre-generated image variants at upload time, for hosts without sharp.
 - Transform loaders beyond the Next default: Supabase Image
   Transformations, imgix, Cloudflare Images (DESIGN.md OQ 28).
+- Delivery caching (checked 2026-09-08): Supabase Storage's basic CDN
+  fronts every public-bucket object on a hosted project with no code on
+  our side, and the Smart CDN (Pro plan, automatic) only adds
+  invalidation on overwrite, which never happens — objects are
+  immutable, no upsert on either path, Replace picks a new id. So both
+  upload paths now set a year-long `cache-control`
+  (`MEDIA_CACHE_SECONDS`): the `cacheControl` option on the server-side
+  upload, the header on the browser's signed PUT (without it a signed
+  upload lands as `no-cache`; Storage's default is one hour). The live
+  suite reads the header back from the local stack. Not yet verified
+  against a hosted project's CDN edge; check `cf-cache-status` and
+  `cache-control` on a real upload there once. Remaining: in v1 the
+  site's `<SmoodlyImage>` goes through `next/image`, so the visitor hits
+  the app server's image cache and only its origin fetch touches the
+  CDN; video, files and SVGs hit the CDN directly. A Supabase Image
+  Transformations loader (`/storage/v1/render/image/public/...`, Pro
+  only, must stay optional) would move resizing to the CDN — the loader
+  bullet above.
 - The asset refs inherit the index's scope: it reflects the latest saved
   version of a source, so a published version still using an asset the
   draft dropped is not protected from delete — the same gap entry refs
   have today.
+- Deviations from the spec, decided while building: the starter's Hero
+  declares `aspect: "4:5"` (the design's own ratio), not `16:9`; `assets.list`
+  pages by a `created_at` cursor, 60 per page; the loader seam is the
+  `loader` prop of `<SmoodlyImage>` and `imageUrl`'s third argument — a
+  config-level `media.loader` waits for a second loader to exist.
+- Image dimensions server-side cover JPEG and PNG (`imageDimensions`); a
+  WebP or AVIF seeded through `AssetStore.create` lands without a size
+  and resolves to nothing until the row is edited. Browser uploads
+  measure every type.
+- A section's `styles` are walked for media, the config's standard style
+  set is not (it holds selects). A standard-set image would need the
+  walk to read `resolvedStyles`.
+- `<SmoodlyImage>` sizes the image by the crop factor, so `sizes` picks a
+  candidate for the box, not for the framed image; a CDN loader with
+  `handlesCrop` removes the overfetch.
+- `smoodlyImages()` returns the whole `images` config, not just the
+  patterns (decided 2026-09-08 in the browser walk): Next 16's optimizer
+  answers 400 for an upstream that resolves to a private IP unless
+  `images.dangerouslyAllowLocalIP` is set, and the local stack is
+  `127.0.0.1`. The helper sets the flag only for `localhost`, loopback
+  and RFC 1918 hosts, so a hosted project stays strict; a Docker alias
+  that resolves privately needs the flag by hand. The spec's "a helper
+  on `smoodly/next`" lives on `smoodly/image` instead, beside the
+  components it serves.
+- Build deviations from the plan (2026-09-08, sessions A–C):
+  `test/admin-pages-tree.test.ts` builds its `AdminRegistry` literal by
+  hand and carries `media: { maxSize: 1, accept: [] }`; `MediaPicker`'s
+  `filters` is `readonly KindFilter[]` and the `Segmented` calls pin
+  `<KindFilter>`; `MediaScreen` seeds its metadata state from
+  `initialSelected` because the plan's effect never runs under
+  `renderToStaticMarkup`; `forms/measure.ts` is browser-only and
+  untested by design (`putSigned` is unit-tested over a stubbed fetch
+  and exercised live since 2026-09-08); the installer's templates are
+  generated (gitignored), so "templates rebuilt" is a build step, not a
+  diff.
 
 ## Follow-ups (logged 2026-09-08, richtext widget spec)
 

package/dist/admin/client-ops.js

@@ -2,6 +2,7 @@ const GROUPS = {
     pages: ["list", "get", "create", "saveDraft", "publish", "delete", "rename", "move", "setTemplate", "addLocale", "removeLocale"],
     entries: ["list", "get", "create", "save", "setStatus", "delete", "move", "addLocale", "removeLocale"],
     shared: ["list", "get", "save", "setStatus"],
+    assets: ["list", "get", "beginUpload", "finishUpload", "update", "delete", "usage"],
     preview: ["enable", "disable"],
 };
 export function makeClientOps(action, token) {

package/dist/admin/forms/CropEditor.d.ts

@@ -0,0 +1,10 @@
+import { type ReactElement } from "react";
+import type { AssetRecord, ImageValue } from "../../media.ts";
+import type { AdminField } from "../serialize.ts";
+export declare function CropEditor({ asset, descriptor, value, onSave, onClose }: {
+    asset: AssetRecord;
+    descriptor: AdminField;
+    value: ImageValue;
+    onSave(next: ImageValue): void;
+    onClose(): void;
+}): ReactElement;

package/dist/admin/forms/CropEditor.js

@@ -0,0 +1,61 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// The crop and hotspot modal (spec 2026-09-08 media §10): the full image,
+// a draggable rectangle (locked to the declared aspect, a segmented
+// switch when several), a draggable hotspot, the per-use alt override
+// and a live preview at the chosen aspect. Pointer deltas become image
+// fractions through the stage's width; the math is in crop-editor.ts.
+import { useRef, useState } from "react";
+import { parseAspect } from "../../media.js";
+import { frameFor } from "../../image/crop-math.js";
+import { Button, Field, Segmented } from "../ui/primitives.js";
+import { Modal } from "../ui/Modal.js";
+import { initialState, moveCrop, placeHotspot, relock, resizeCrop } from "./crop-editor.js";
+const pct = (n) => `${n * 100}%`;
+export function CropEditor({ asset, descriptor, value, onSave, onClose }) {
+    const declared = descriptor.aspect;
+    const options = Array.isArray(declared) ? declared : typeof declared === "string" ? [declared] : [];
+    const width = asset.width ?? 1, height = asset.height ?? 1;
+    const imageAspect = width / height;
+    const [chosen, setChosen] = useState(options.includes(value.aspect ?? "") ? value.aspect : options[0]);
+    const aspect = chosen ? parseAspect(chosen) : undefined;
+    const [state, setState] = useState(() => initialState(value, aspect, imageAspect));
+    const [alt, setAlt] = useState(value.alt ?? "");
+    const stage = useRef(null);
+    const drag = useRef(null);
+    const pick = (next) => { setChosen(next); setState((s) => relock(s, parseAspect(next), imageAspect)); };
+    const begin = (kind) => (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        e.currentTarget.setPointerCapture(e.pointerId);
+        drag.current = { kind, x: e.clientX, y: e.clientY, start: state };
+    };
+    const move = (e) => {
+        const d = drag.current, el = stage.current;
+        if (!d || !el)
+            return;
+        const dx = (e.clientX - d.x) / el.clientWidth, dy = (e.clientY - d.y) / el.clientHeight;
+        const lock = aspect === undefined ? undefined : aspect / imageAspect;
+        if (d.kind === "move") {
+            const crop = moveCrop(d.start.crop, dx, dy);
+            setState({ crop, hotspot: placeHotspot(d.start.hotspot, crop) });
+        }
+        else if (d.kind === "hotspot") {
+            setState({ crop: d.start.crop, hotspot: placeHotspot({ x: d.start.hotspot.x + dx, y: d.start.hotspot.y + dy }, d.start.crop) });
+        }
+        else {
+            const crop = resizeCrop(d.start.crop, d.kind, dx, dy, lock);
+            setState({ crop, hotspot: placeHotspot(d.start.hotspot, crop) });
+        }
+    };
+    const end = () => { drag.current = null; };
+    const { crop, hotspot } = state;
+    const previewAspect = aspect ?? (crop.width * imageAspect) / crop.height;
+    const frame = frameFor({ width, height, crop, hotspot }, previewAspect);
+    const save = () => onSave({
+        ...value, crop, hotspot,
+        ...(alt.trim() ? { alt: alt.trim() } : { alt: undefined }),
+        ...(options.length > 1 && chosen ? { aspect: chosen } : { aspect: undefined }),
+    });
+    return (_jsx(Modal, { title: "Crop and focus", width: 900, onClose: onClose, footer: _jsxs(_Fragment, { children: [_jsx(Button, { variant: "secondary", onClick: onClose, children: "Cancel" }), _jsx(Button, { onClick: save, children: "Save" })] }), children: _jsxs("div", { className: "sm-crop", children: [_jsxs("div", { className: "sm-crop__stage", ref: stage, onPointerMove: move, onPointerUp: end, onPointerCancel: end, children: [_jsx("img", { src: asset.url, alt: "", draggable: false }), _jsx("div", { className: "sm-crop__shade", style: { clipPath: `polygon(0 0, 100% 0, 100% 100%, 0 100%, 0 ${pct(crop.top)}, ${pct(crop.left)} ${pct(crop.top)}, ${pct(crop.left)} ${pct(crop.top + crop.height)}, ${pct(crop.left + crop.width)} ${pct(crop.top + crop.height)}, ${pct(crop.left + crop.width)} ${pct(crop.top)}, 0 ${pct(crop.top)})` } }), _jsx("div", { className: "sm-crop__rect", style: { left: pct(crop.left), top: pct(crop.top), width: pct(crop.width), height: pct(crop.height) }, onPointerDown: begin("move"), children: ["nw", "ne", "sw", "se"].map((h) => (_jsx("span", { className: `sm-crop__handle sm-crop__handle--${h}`, onPointerDown: begin(h) }, h))) }), _jsx("div", { className: "sm-crop__hotspot", title: "Focus point", style: { left: pct(hotspot.x), top: pct(hotspot.y) }, onPointerDown: begin("hotspot") })] }), _jsxs("div", { className: "sm-crop__side", children: [options.length > 1 && (_jsx(Field, { label: "Aspect", asDiv: true, children: _jsx(Segmented, { options: options, value: chosen ?? options[0], onChange: pick }) })), _jsx(Field, { label: "Preview", asDiv: true, children: _jsx("div", { className: "sm-crop__preview", style: { aspectRatio: String(previewAspect) }, children: _jsx("img", { src: asset.url, alt: "", style: { left: `${frame.left}%`, top: `${frame.top}%`, width: `${frame.width}%`, height: `${frame.height}%` } }) }) }), _jsx(Field, { label: "Alt text for this use", hint: "Empty uses the asset's own alt.", children: _jsx("input", { className: "sm-input", value: alt, placeholder: asset.alt ?? "", onChange: (e) => setAlt(e.target.value) }) })] })] }) }));
+}

package/dist/admin/forms/FieldWidget.js

@@ -7,6 +7,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // logic lives in ./list.ts as pure functions.
 import { useState } from "react";
 import { RichtextWidget } from "./RichtextWidget.js";
+import { MediaWidget } from "./MediaWidget.js";
 import { Button, Field, IconButton } from "../ui/primitives.js";
 import { addItem, itemSummary, moveIndex, moveItem, patchObject, removeIndex, removeItem } from "./list.js";
 const label = (key) => key.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase());
@@ -47,11 +48,10 @@ export function FieldWidget({ descriptor: d, value, onChange, errors, path: path
             break;
         case "image":
         case "video":
-        case "file": {
-            const url = value?.url ?? "";
-            control = (_jsx("input", { className: "sm-input", placeholder: "https://\u2026", value: url, onChange: (e) => onChange(e.target.value ? { url: e.target.value } : undefined) }));
+        case "file":
+            asDiv = true; // buttons inside
+            control = _jsx(MediaWidget, { descriptor: d, value: value, onChange: onChange });
             break;
-        }
         case "ref":
             control = (_jsxs("select", { className: "sm-select", value: String(value ?? ""), onChange: (e) => onChange(e.target.value || undefined), children: [_jsx("option", { value: "", children: "\u2014" }), refOptions.map((o) => _jsx("option", { value: o.id, children: optionTitle(o) }, o.id))] }));
             break;

package/dist/admin/forms/MediaGrid.d.ts

@@ -0,0 +1,11 @@
+import type { ReactElement } from "react";
+import type { AssetRecord } from "../../media.ts";
+export declare function AssetThumb({ asset, className }: {
+    asset: AssetRecord;
+    className?: string;
+}): ReactElement;
+export declare function MediaGrid({ items, selectedId, onSelect }: {
+    items: AssetRecord[];
+    selectedId?: string | null;
+    onSelect(asset: AssetRecord): void;
+}): ReactElement;

package/dist/admin/forms/MediaGrid.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { formatBytes } from "../shell/media-list.js";
+export function AssetThumb({ asset, className }) {
+    if (asset.kind === "image")
+        return _jsx("img", { className: className, src: asset.url, alt: "", loading: "lazy" });
+    if (asset.kind === "video") {
+        return asset.posterId
+            ? _jsx("video", { className: className, src: asset.url, muted: true, playsInline: true, preload: "metadata" })
+            : _jsx("span", { className: `${className ?? ""} sm-thumb--chip`, children: "Video" });
+    }
+    return _jsx("span", { className: `${className ?? ""} sm-thumb--chip`, children: asset.filename.split(".").pop()?.toUpperCase() ?? "File" });
+}
+export function MediaGrid({ items, selectedId, onSelect }) {
+    return (_jsxs("div", { className: "sm-mediagrid", children: [items.map((asset) => (_jsxs("button", { type: "button", className: "sm-mediacard", "aria-pressed": asset.id === selectedId, onClick: () => onSelect(asset), children: [_jsx("span", { className: "sm-mediacard__thumb", children: _jsx(AssetThumb, { asset: asset, className: "sm-mediacard__img" }) }), _jsx("span", { className: "sm-mediacard__name", children: asset.title ?? asset.filename }), _jsxs("span", { className: "sm-mediacard__meta", children: [asset.width && asset.height ? `${asset.width}×${asset.height} · ` : "", formatBytes(asset.size)] })] }, asset.id))), items.length === 0 && _jsx("div", { className: "sm-empty", children: "No media yet." })] }));
+}

package/dist/admin/forms/MediaPicker.d.ts

@@ -0,0 +1,8 @@
+import { type ReactElement } from "react";
+import type { AssetKind, AssetRecord } from "../../media.ts";
+export declare function MediaPicker({ kinds, onPick, onClose, initialItems }: {
+    kinds: AssetKind[];
+    onPick(asset: AssetRecord): void;
+    onClose(): void;
+    initialItems?: AssetRecord[];
+}): ReactElement;

package/dist/admin/forms/MediaPicker.js

@@ -0,0 +1,44 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The library modal (spec 2026-09-08 media §10): grid first, an upload
+// zone above it that uploads and selects in one motion, search and a
+// kind filter. `initialItems` seeds the grid (tests and the widget's
+// optimistic reopen); the effect loads the real list.
+import { useCallback, useEffect, useState } from "react";
+import { Banner, Segmented } from "../ui/primitives.js";
+import { Modal } from "../ui/Modal.js";
+import { useAssets } from "./assets-context.js";
+import { uploadFile } from "./upload.js";
+import { MediaGrid } from "./MediaGrid.js";
+import { KIND_FILTERS, acceptFor, kindOfFilter } from "../shell/media-list.js";
+export function MediaPicker({ kinds, onPick, onClose, initialItems = [] }) {
+    const assets = useAssets();
+    const [items, setItems] = useState(initialItems);
+    const [search, setSearch] = useState("");
+    const [filter, setFilter] = useState(kinds.length === 1 ? (kinds[0] === "image" ? "Images" : kinds[0] === "video" ? "Video" : "Files") : "All");
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    const filters = kinds.length === 1 ? [filter] : KIND_FILTERS;
+    const load = useCallback(() => {
+        assets.ops.list({ kind: kindOfFilter(filter), search: search || undefined })
+            .then((r) => (r.ok ? setItems(r.data.items.filter((a) => kinds.includes(a.kind))) : setError(r.message)))
+            .catch(() => setError("Couldn't reach the server."));
+    }, [assets, filter, search, kinds]);
+    useEffect(load, [load]);
+    const onFiles = async (files) => {
+        const file = files?.[0];
+        if (!file)
+            return;
+        setBusy(true);
+        setError(null);
+        const r = await uploadFile(assets.ops, file, assets.upload);
+        setBusy(false);
+        if (!r.ok) {
+            setError(r.message);
+            return;
+        }
+        assets.remember(r.data);
+        onPick(r.data);
+    };
+    return (_jsxs(Modal, { title: "Media", onClose: onClose, children: [_jsxs("div", { className: "sm-picker-bar", children: [_jsx("input", { className: "sm-input", placeholder: "Search media", value: search, onChange: (e) => setSearch(e.target.value), style: { maxWidth: 260 } }), filters.length > 1 && _jsx(Segmented, { options: filters, value: filter, onChange: setFilter }), _jsxs("label", { className: "sm-btn sm-btn--primary", style: { marginLeft: "auto" }, children: [busy ? "Uploading…" : "Upload", _jsx("input", { type: "file", accept: acceptFor(kinds, assets.media.accept), hidden: true, disabled: busy, onChange: (e) => { void onFiles(e.target.files); } })] })] }), error && _jsx(Banner, { tone: "error", onDismiss: () => setError(null), children: error }), _jsx("div", { className: "sm-dropzone sm-dropzone--bar", onDragOver: (e) => e.preventDefault(), onDrop: (e) => { e.preventDefault(); void onFiles(e.dataTransfer.files); }, children: "Drop a file here to upload it" }), _jsx(MediaGrid, { items: items, onSelect: onPick })] }));
+}

package/dist/admin/forms/MediaWidget.d.ts

@@ -0,0 +1,9 @@
+import { type ReactElement } from "react";
+import type { AssetRecord } from "../../media.ts";
+import type { AdminField } from "../serialize.ts";
+export declare function MediaWidget({ descriptor, value, onChange, asset: preloaded }: {
+    descriptor: AdminField;
+    value: unknown;
+    onChange(value: unknown): void;
+    asset?: AssetRecord | null;
+}): ReactElement;

package/dist/admin/forms/MediaWidget.js

@@ -0,0 +1,83 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// The media field widget (spec 2026-09-08 media §10): empty is a drop
+// zone (upload straight away, or open the library); filled is the
+// thumbnail with the crop applied, the alt, and Replace / Edit / Remove.
+// The record comes from the assets context (cached per id); `asset`
+// preloads it for static renders.
+import { useEffect, useState } from "react";
+import { frameFor, boxAspectOf } from "../../image/crop-math.js";
+import { Button } from "../ui/primitives.js";
+import { acceptFor, formatBytes } from "../shell/media-list.js";
+import { useAssets } from "./assets-context.js";
+import { uploadFile } from "./upload.js";
+import { MediaPicker } from "./MediaPicker.js";
+import { CropEditor } from "./CropEditor.js";
+import { AssetThumb } from "./MediaGrid.js";
+export function MediaWidget({ descriptor, value, onChange, asset: preloaded }) {
+    const assets = useAssets();
+    const kind = descriptor.type;
+    const id = typeof value?.asset === "string" ? value.asset : null;
+    const [asset, setAsset] = useState(preloaded ?? null);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    const [picker, setPicker] = useState(false);
+    const [crop, setCrop] = useState(false);
+    useEffect(() => {
+        if (!id) {
+            setAsset(null);
+            return;
+        }
+        if (preloaded?.id === id) {
+            setAsset(preloaded);
+            return;
+        }
+        let live = true;
+        assets.get(id).then((r) => { if (live)
+            setAsset(r); });
+        return () => { live = false; };
+    }, [id, assets, preloaded]);
+    const select = (record) => {
+        assets.remember(record);
+        setAsset(record);
+        setPicker(false);
+        onChange({ asset: record.id });
+    };
+    const onFiles = async (files) => {
+        const file = files?.[0];
+        if (!file)
+            return;
+        setBusy(true);
+        setError(null);
+        const r = await uploadFile(assets.ops, file, assets.upload);
+        setBusy(false);
+        if (!r.ok) {
+            setError(r.message);
+            return;
+        }
+        select(r.data);
+    };
+    const accept = acceptFor([kind], assets.media.accept);
+    const fileInput = (label, variant = "secondary") => (_jsxs("label", { className: `sm-btn sm-btn--${variant}`, children: [busy ? "Uploading…" : label, _jsx("input", { type: "file", accept: accept, hidden: true, disabled: busy, onChange: (e) => { void onFiles(e.target.files); } })] }));
+    let body;
+    if (!id) {
+        body = (_jsxs("div", { className: "sm-dropzone", onDragOver: (e) => e.preventDefault(), onDrop: (e) => { e.preventDefault(); void onFiles(e.dataTransfer.files); }, children: [_jsx("span", { children: "Drop a file here" }), _jsxs("div", { className: "sm-media__actions", children: [fileInput("Upload", "primary"), _jsx(Button, { variant: "secondary", onClick: () => setPicker(true), children: "Choose from library" })] })] }));
+    }
+    else if (!asset) {
+        body = _jsx("div", { className: "sm-media__chip", children: "Loading\u2026" });
+    }
+    else if (asset.status === "pending") {
+        body = _jsx("div", { className: "sm-media__chip", children: "Uploading\u2026" });
+    }
+    else {
+        const v = value;
+        const preview = asset.kind === "image" && asset.width && asset.height ? (() => {
+            const image = { url: asset.url, width: asset.width, height: asset.height, mime: asset.mime, alt: "", crop: v.crop, hotspot: v.hotspot, aspect: v.aspect ?? (typeof descriptor.aspect === "string" ? descriptor.aspect : undefined) };
+            const box = boxAspectOf(image);
+            const f = frameFor(image, box);
+            return (_jsx("div", { className: "sm-media__thumb", style: { aspectRatio: String(box) }, children: _jsx("img", { src: asset.url, alt: "", style: { left: `${f.left}%`, top: `${f.top}%`, width: `${f.width}%`, height: `${f.height}%` } }) }));
+        })() : asset.kind === "video" ? (_jsx("div", { className: "sm-media__thumb", style: { aspectRatio: asset.width && asset.height ? `${asset.width} / ${asset.height}` : "16 / 9" }, children: _jsx(AssetThumb, { asset: asset, className: "sm-mediacard__img" }) })) : (_jsxs("div", { className: "sm-media__chip", children: [_jsx("span", { style: { fontWeight: 500 }, children: asset.filename }), _jsx("span", { className: "sm-media__alt", children: formatBytes(asset.size) })] }));
+        body = (_jsxs("div", { className: "sm-media", children: [preview, asset.kind === "image" && _jsx("span", { className: "sm-media__alt", children: v.alt ?? asset.alt ?? "No alt text" }), _jsxs("div", { className: "sm-media__actions", children: [_jsx(Button, { variant: "secondary", onClick: () => setPicker(true), children: "Replace" }), asset.kind === "image" && _jsx(Button, { variant: "secondary", onClick: () => setCrop(true), children: "Edit" }), _jsx(Button, { variant: "secondary", onClick: () => onChange(undefined), children: "Remove" })] })] }));
+    }
+    return (_jsxs(_Fragment, { children: [body, error && _jsx("span", { className: "sm-error", children: error }), picker && _jsx(MediaPicker, { kinds: [kind], onPick: select, onClose: () => setPicker(false) }), crop && asset && (_jsx(CropEditor, { asset: asset, descriptor: descriptor, value: value, onSave: (next) => { onChange(next); setCrop(false); }, onClose: () => setCrop(false) }))] }));
+}

package/dist/admin/forms/assets-context.d.ts

@@ -0,0 +1,19 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { AdminOps } from "../ops.ts";
+import type { AdminRegistry } from "../serialize.ts";
+import type { AssetRecord } from "../../media.ts";
+import { type UploadDeps } from "./upload.ts";
+export type AssetsApi = {
+    ops: AdminOps["assets"];
+    get(id: string): Promise<AssetRecord | null>;
+    remember(record: AssetRecord): void;
+    upload: UploadDeps;
+    media: AdminRegistry["media"];
+};
+export declare function AssetsProvider({ ops, media, upload, children }: {
+    ops: AdminOps;
+    media: AdminRegistry["media"];
+    upload?: UploadDeps;
+    children: ReactNode;
+}): ReactElement;
+export declare function useAssets(): AssetsApi;

package/dist/admin/forms/assets-context.js

@@ -0,0 +1,35 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// The one place widgets reach the assets ops: a context with a small
+// record cache (an id fetched once per shell lifetime), the field
+// limits from the registry, and the injectable upload deps.
+import { createContext, useContext, useMemo, useRef } from "react";
+import { putSigned } from "./upload.js";
+import { measureFile } from "./measure.js";
+const Ctx = createContext(null);
+export function AssetsProvider({ ops, media, upload, children }) {
+    const cache = useRef(new Map());
+    const api = useMemo(() => ({
+        ops: ops.assets,
+        media,
+        upload: upload ?? { put: putSigned, measure: measureFile },
+        remember: (record) => { cache.current.set(record.id, record); },
+        get: async (id) => {
+            const hit = cache.current.get(id);
+            if (hit)
+                return hit;
+            const r = await ops.assets.get(id);
+            if (!r.ok)
+                return null;
+            cache.current.set(id, r.data);
+            return r.data;
+        },
+    }), [ops, media, upload]);
+    return _jsx(Ctx.Provider, { value: api, children: children });
+}
+export function useAssets() {
+    const api = useContext(Ctx);
+    if (!api)
+        throw new Error("smoodly: useAssets() needs an <AssetsProvider> above it.");
+    return api;
+}

package/dist/admin/forms/crop-editor.d.ts

@@ -0,0 +1,13 @@
+import { type Crop, type Hotspot, type ImageValue } from "../../media.ts";
+export type Handle = "nw" | "ne" | "sw" | "se";
+export type CropState = {
+    crop: Crop;
+    hotspot: Hotspot;
+};
+export declare const MIN_SIDE = 0.05;
+export declare function fitAspect(aspect: number, imageAspect: number): Crop;
+export declare function moveCrop(crop: Crop, dx: number, dy: number): Crop;
+export declare function resizeCrop(crop: Crop, handle: Handle, dx: number, dy: number, lock?: number, min?: number): Crop;
+export declare function placeHotspot(h: Hotspot, crop: Crop): Hotspot;
+export declare function relock(state: CropState, aspect: number | undefined, imageAspect: number): CropState;
+export declare function initialState(value: ImageValue | undefined, aspect: number | undefined, imageAspect: number): CropState;

package/dist/admin/forms/crop-editor.js

@@ -0,0 +1,72 @@
+// The crop editor's math, pure (spec 2026-09-08 media §10): everything in
+// fractions of the original image. A "lock" is the wanted pixel ratio
+// divided by the image's own, i.e. the ratio crop.width / crop.height
+// must keep.
+import { CENTER_HOTSPOT, FULL_CROP, clamp01 } from "../../media.js";
+export const MIN_SIDE = 0.05;
+export function fitAspect(aspect, imageAspect) {
+    const fa = aspect / imageAspect;
+    const width = fa <= 1 ? fa : 1;
+    const height = fa <= 1 ? 1 : 1 / fa;
+    return { left: (1 - width) / 2, top: (1 - height) / 2, width, height };
+}
+export function moveCrop(crop, dx, dy) {
+    return {
+        ...crop,
+        left: Math.min(Math.max(crop.left + dx, 0), 1 - crop.width),
+        top: Math.min(Math.max(crop.top + dy, 0), 1 - crop.height),
+    };
+}
+export function resizeCrop(crop, handle, dx, dy, lock, min = MIN_SIDE) {
+    const right = crop.left + crop.width, bottom = crop.top + crop.height;
+    const ax = handle.includes("w") ? right : crop.left; // anchor: the opposite corner
+    const ay = handle.includes("n") ? bottom : crop.top;
+    const mx = clamp01((handle.includes("w") ? crop.left : right) + dx);
+    const my = clamp01((handle.includes("n") ? crop.top : bottom) + dy);
+    // Signed: a corner dragged past its anchor collapses to `min`, never flips.
+    let width = Math.max(handle.includes("w") ? ax - mx : mx - ax, min);
+    let height = Math.max(handle.includes("n") ? ay - my : my - ay, min);
+    const roomX = handle.includes("w") ? ax : 1 - ax; // how far the moving corner may go
+    const roomY = handle.includes("n") ? ay : 1 - ay;
+    if (lock !== undefined) {
+        height = width / lock;
+        if (height > roomY) {
+            height = roomY;
+            width = height * lock;
+        }
+        if (width > roomX) {
+            width = roomX;
+            height = width / lock;
+        }
+        if (height < min) {
+            height = min;
+            width = height * lock;
+        }
+    }
+    else {
+        width = Math.min(width, roomX);
+        height = Math.min(height, roomY);
+    }
+    return {
+        left: handle.includes("w") ? ax - width : ax,
+        top: handle.includes("n") ? ay - height : ay,
+        width, height,
+    };
+}
+export function placeHotspot(h, crop) {
+    return {
+        x: Math.min(Math.max(h.x, crop.left), crop.left + crop.width),
+        y: Math.min(Math.max(h.y, crop.top), crop.top + crop.height),
+    };
+}
+const atRatio = (crop, lock) => Math.abs(crop.width / crop.height - lock) < 1e-3;
+export function relock(state, aspect, imageAspect) {
+    if (aspect === undefined)
+        return { crop: state.crop, hotspot: placeHotspot(state.hotspot, state.crop) };
+    const lock = aspect / imageAspect;
+    const crop = atRatio(state.crop, lock) ? state.crop : fitAspect(aspect, imageAspect);
+    return { crop, hotspot: placeHotspot(state.hotspot, crop) };
+}
+export function initialState(value, aspect, imageAspect) {
+    return relock({ crop: value?.crop ?? FULL_CROP, hotspot: value?.hotspot ?? CENTER_HOTSPOT }, aspect, imageAspect);
+}

package/dist/admin/forms/measure.d.ts

@@ -0,0 +1,2 @@
+import type { Measured } from "./upload.ts";
+export declare function measureFile(file: Blob, mime: string): Promise<Measured>;

package/dist/admin/forms/measure.js

@@ -0,0 +1,39 @@
+const objectUrl = (file) => URL.createObjectURL(file);
+function measureImage(file) {
+    return new Promise((resolve) => {
+        const url = objectUrl(file);
+        const img = new Image();
+        img.onload = () => { resolve({ width: img.naturalWidth, height: img.naturalHeight }); URL.revokeObjectURL(url); };
+        img.onerror = () => { resolve({}); URL.revokeObjectURL(url); };
+        img.src = url;
+    });
+}
+function measureVideo(file) {
+    return new Promise((resolve) => {
+        const url = objectUrl(file);
+        const video = document.createElement("video");
+        video.preload = "metadata";
+        video.muted = true;
+        const done = (m) => { resolve(m); URL.revokeObjectURL(url); };
+        video.onerror = () => done({});
+        video.onloadedmetadata = () => {
+            const base = { width: video.videoWidth, height: video.videoHeight, duration: video.duration };
+            video.onseeked = () => {
+                const canvas = document.createElement("canvas");
+                canvas.width = video.videoWidth;
+                canvas.height = video.videoHeight;
+                canvas.getContext("2d")?.drawImage(video, 0, 0);
+                canvas.toBlob((blob) => done(blob ? { ...base, poster: blob } : base), "image/jpeg", 0.85);
+            };
+            video.currentTime = Math.min(1, video.duration / 2);
+        };
+        video.src = url;
+    });
+}
+export function measureFile(file, mime) {
+    if (mime.startsWith("image/"))
+        return measureImage(file);
+    if (mime.startsWith("video/"))
+        return measureVideo(file);
+    return Promise.resolve({});
+}

package/dist/admin/forms/upload.d.ts

@@ -0,0 +1,17 @@
+import type { AdminOps, OpResult } from "../ops.ts";
+import { type AssetRecord } from "../../media.ts";
+export type Measured = {
+    width?: number;
+    height?: number;
+    duration?: number;
+    poster?: Blob;
+};
+export type UploadDeps = {
+    put(url: string, file: Blob, mime: string): Promise<void>;
+    measure(file: Blob, mime: string): Promise<Measured>;
+};
+export declare function uploadFile(ops: AdminOps["assets"], file: File, deps: UploadDeps): Promise<OpResult<AssetRecord>>;
+/** A raw PUT to the signed URL: the body is the file, the type its mime,
+ *  and the year-long cache-control Storage serves back (without the
+ *  header a signed upload lands as `no-cache`). */
+export declare function putSigned(url: string, file: Blob, mime: string): Promise<void>;

package/dist/admin/forms/upload.js

@@ -0,0 +1,33 @@
+import { MEDIA_CACHE_SECONDS } from "../../media.js";
+const stem = (name) => name.replace(/\.[^.]+$/, "");
+export async function uploadFile(ops, file, deps) {
+    const begun = await ops.beginUpload({ name: file.name, mime: file.type, size: file.size });
+    if (!begun.ok)
+        return begun;
+    try {
+        await deps.put(begun.data.uploadUrl, file, file.type);
+    }
+    catch (e) {
+        return { ok: false, code: "internal", message: `smoodly: upload failed — ${e instanceof Error ? e.message : String(e)}` };
+    }
+    const m = await deps.measure(file, file.type);
+    let posterId;
+    if (m.poster) {
+        const poster = await uploadFile(ops, new File([m.poster], `${stem(file.name)}-poster.jpg`, { type: "image/jpeg" }), deps);
+        if (poster.ok)
+            posterId = poster.data.id;
+    }
+    return ops.finishUpload(begun.data.id, { width: m.width, height: m.height, duration: m.duration, posterId });
+}
+/** A raw PUT to the signed URL: the body is the file, the type its mime,
+ *  and the year-long cache-control Storage serves back (without the
+ *  header a signed upload lands as `no-cache`). */
+export async function putSigned(url, file, mime) {
+    const res = await fetch(url, {
+        method: "PUT",
+        headers: { "content-type": mime, "x-upsert": "false", "cache-control": `max-age=${MEDIA_CACHE_SECONDS}` },
+        body: file,
+    });
+    if (!res.ok)
+        throw new Error(`${res.status} ${(await res.text()).slice(0, 200)}`);
+}

package/dist/admin/index.d.ts

@@ -1,4 +1,4 @@
-export type { AdminOps, AdminOpCall, AdminOpAction, OpResult, OpError, PageCreateInput, PageGetResult, SharedListItem, SharedGetResult } from "./ops.ts";
+export type { AdminOps, AdminOpCall, AdminOpAction, OpResult, OpError, PageCreateInput, PageGetResult, SharedListItem, SharedGetResult, AssetUsageItem } from "./ops.ts";
 export { createAdminOps, runAdminOp, type AdminEffects } from "./ops-impl.ts";
 export { fixedNodeSpecs, fixedNodeOf, ensureFixedNodes, type FixedNode } from "./fixed-nodes.ts";
 export { ensureSharedItems, initialSharedFields } from "./shared-items.ts";