smoodly 0.0.9 → 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
@@ -194,7 +207,10 @@ Implemented:
   and `smoodly/bridge` (`EditorBridge`, the only piece that ships to the
   SITE side — runs inside the draft-route iframe, reports node/zone
   geometry, forwards select/hover, executes refresh/scroll). Shell
-  (registry-derived nav, list views, segment-based internal routing),
+  (registry-derived nav, list views, its own client-side router —
+  `shell/router.ts`, `RouteLink`, a leave guard for dirty forms; the
+  shell mounts from the layout and the catch-all page only makes the
+  URL exist, spec 2026-09-08),
   entry form (widgets by field type, validation errors surfaced inline,
   save/publish/unpublish/delete with the safe-delete guard's message
   shown verbatim), and the editor view (dark instrument around a bright
@@ -294,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`
@@ -324,18 +347,21 @@ Implemented:
   `validateFields` recurses with dotted paths (`points.2.heading`) and
   checks list length; the serializer ships a list's `item`.
 
-- Richtext renders and round-trips: `RichText` (package root, pure React,
-  no wrapper) turns the TipTap document into paragraphs, headings, lists,
+- Richtext, both directions: `RichText` (package root, pure React, no
+  wrapper) turns the TipTap document into paragraphs, headings, lists,
   blockquotes, hard breaks and bold/italic/link marks, unknown nodes
-  degrading to their children. The interim textarea widget speaks a line
-  syntax (`#` headings, `- ` and `1. ` lists, `> ` quotes, blank line
-  between paragraphs, hard break between adjacent lines) over the same
-  JSON, so seeded structure survives an edit.
-  A link mark reaches the page only with a safe scheme (http(s), mailto,
-  tel, site-relative).
-
-Not yet: the TipTap richtext widget (the textarea's line syntax is the
-interim editor; `RichText` renders), Elements in richtext, drag-and-drop
+  degrading to their children; a link mark reaches the page only with a
+  safe scheme (http(s), mailto, tel, site-relative). The admin edits it
+  with a TipTap widget under a fixed toolbar (`admin/forms/RichtextWidget.tsx`,
+  spec 2026-09-08): the schema is always the full one, and the field's
+  toolset — typed names, `DEFAULT_TOOLSET` when a field declares none —
+  gates only creation (toolbar, shortcuts, input rules, paste), so content
+  a toolset forbids survives every round trip. Links carry `href` only. An
+  empty document is missing for a required field. The widget emits plain
+  JSON: ProseMirror's node attrs have a null prototype, which a server
+  action cannot serialize.
+
+Not yet: Elements in richtext, drag-and-drop
 reordering (move-up/move-down buttons in the editor, Move up / Move down
 in the Pages list's row menu), undo/redo, sample/placeholder content
 marking, per-locale section visibility conditions (OQ #3 — each locale
@@ -356,6 +382,130 @@ Both packages move together. From the repo root:
 `examples/site` in that build, so the template always matches the example
 site at the tagged commit.
 
+## Follow-ups (logged 2026-09-08, client routing spec)
+
+- Keep the previous view painted until the next one has data: today a
+  navigation switches instantly and the new view shows its own loading
+  state; a transition that holds the old view, or prefetches the next
+  view's ops call on hover, is the next step.
+- Browser Back with unsaved changes is not guarded: `popstate` cannot be
+  cancelled cleanly, so a dirty form only asks on a click and on reload.
+  Re-pushing the current URL and asking is possible if editors lose work.
+- Every revalidating op (publish, delete, a save of published content)
+  answers with a fresh RSC render of the admin route — the layout's
+  styles included, ~30 KB — because `updateTag` runs inside the server
+  action and Next re-renders the tree it was posted to. Harmless now
+  that the shell lives in the layout (the empty page subtree is what
+  remounts), but it is the price of server actions as the transport.
+- The bundle split: the editor bridge out of the admin tree and the
+  editor lazy-loaded, so site pages stop loading the admin chunk (the
+  richtext widget register entry below measures it). Its own spec.
+- `SharedForm` and `EntryForm` now share the locale helpers; the rest
+  of the fork (`applyResult`, `InfoRow`, the ref-options effect) is still
+  the 2026-09-07 entry below.
+
+## Follow-ups (logged 2026-09-08, media library spec)
+
+- Video transcoding and adaptive streaming: a Mux or Cloudflare Stream
+  loader behind the `media.loader` seam, if a site ever needs more than
+  an MP4 over Storage's CDN.
+- Richtext images: the `image` node from the Phase 0 sketch, using the
+  media picker once it exists.
+- Sweeping abandoned `pending` asset rows (an upload that began and
+  never called `finishUpload`); a periodic op or a cleanup on `list`.
+- A private bucket with signed reads, for sites that must not expose
+  draft-only media by URL before publish.
+- 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)
+
+- Drag-to-resize the inspector: `--inspector-w` is one variable (380px
+  since the widget); a handle on the column edge writing it, persisted
+  per browser like the theme, is the follow-up.
+- A page and entry picker in the link popover: a link inside a richtext
+  document is a reference the refs index, the resolver and the localizer
+  cannot see (they address refs by top-level key). Its own spec.
+- Elements in richtext: a registered Element as a TipTap node view with a
+  small form for its fields, rendered on the site by `RichText` through
+  the registry. The next spec.
+- Images in richtext: the Phase 0 sketch's `image` node; waits for media.
+- Escape inside any inspector control bubbles to the editor's window
+  handler and clears the block selection — the link popover stops it, a
+  textarea or the TipTap content does not. A `keydown` guard on
+  `.sm-inspector` would fix it for every control.
+- Every richtext descriptor now carries its toolset, so the serialized
+  registry grew by a few bytes per field; if the AI-facing schema wants
+  the vocabulary once instead of per field, dedupe there.
+- The entry form's column is narrower than the inspector, so the default
+  toolbar wraps to two rows there; the inspector shows it on one.
+- The example site's production bundle loads one shared chunk (~750 KB)
+  on every site page holding the package's admin client modules — the
+  shell, the Supabase client and now the TipTap widget — because
+  `next/page-renderer.tsx` imports the editor bridge from
+  `admin/next/bridge.tsx` and Turbopack bundles the package's client
+  modules together. Measured on the 2026-09-08 build; whether the shell
+  was already there before the widget is unverified. The fix is to give
+  the bridge its own entry outside the admin tree and re-measure.
+
 ## Follow-ups (logged 2026-09-07, starter)
 
 - A paired component (`smoodly.section`) accepts only its schema's props, so
@@ -497,11 +647,10 @@ site at the tagged commit.
   a duplicate beside it. Re-materializing such an item (delete the row in
   SQL, reload the admin) moves it onto the derived id.
 - `SharedForm.tsx` is a near-verbatim fork of `EntryForm.tsx`
-  (`localeFromUrl`, `writeLocaleToUrl`, `applyResult`, `InfoRow`, the
-  ref-options effect) and `SharedList.tsx` is the third copy of the
-  remembered-locale block (`EntriesList`, `PagesList`); extract
-  `shell/locale-url.ts` and a `useFormLocale` hook when the next form
-  arrives.
+  (`applyResult`, `InfoRow`, the ref-options effect; the locale helpers
+  are shared since 2026-09-08) and `SharedList.tsx` is the third copy of
+  the remembered-locale block (`EntriesList`, `PagesList`); extract a
+  `useFormLocale` hook when the next form arrives.
 - A placement selected in a bound locked zone shows the canvas toolbar's
   "fields only" label though a placement has no page-level fields; the
   inspector notice is the real message.
@@ -960,4 +1109,4 @@ site at the tagged commit.
 - `serialize.ts` structural cast duplicates `PageSchema`; tighten `Registered.schema` so the cast goes.
 - Catch-all `templates` map should filter to open registrations to state its intent (unreachable today).
 - The no-database build is the real proof that routes never prerender against the stores; the unit test only stubs `next/server`. Script it (`SUPABASE_URL=http://127.0.0.1:9 npx next build` in `examples/site`, expect `ƒ /`) and add it to CI, which today runs only the package's tests and typecheck — so a regression is caught when Next changes `connection()` semantics.
-- `EditorView` split, remaining seams (autosave extracted 2026-09-03): the locale lifecycle — `localeFromUrl`, `LocaleSwitcher`, `switchLocale`, `doAddLocale`, `doRemoveLocale` — is the cleanest extraction available now (self-contained, no canvas geometry); pull the canvas overlay and the insert picker into components when the dnd-kit outline work starts; the sidebar form stays put until inline editing lands (DESIGN.md §3 puts TipTap in the canvas, not the sidebar). (logged 2026-09-06)
+- `EditorView` split (autosave extracted 2026-09-03; the rest 2026-09-08, before the TipTap widget): `usePageLocale` (switch/add/remove, over `locale-url.ts`), `useCanvasBridge` (geometry, select/hover, `postToCanvas`, the geometry timeout), `CanvasOverlay` over `overlay-geometry.ts` (`plusButtonsFor`, pure and tested), `InsertPicker`, `Outline`, `NoticePane`. `EditorView.tsx` is ~660 lines of load, gestures, publish and layout. Remaining seam: the inspector's field form (`FieldWidget` rows plus the tabs) stays put until inline editing lands (DESIGN.md §3 puts TipTap in the canvas, not the sidebar); the ref-option loading (`refTargets` + the `ops.entries.list` effect) duplicates `EntryForm`'s and could be one hook. (logged 2026-09-06, updated 2026-09-08)

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/editor/CanvasOverlay.d.ts

@@ -0,0 +1,21 @@
+import type { TreeNode } from "../../render.tsx";
+import type { PlusButton } from "./overlay-geometry.ts";
+import type { BridgeRect, ZoneRect } from "./protocol.ts";
+export type OverlaySelection = {
+    node: TreeNode;
+    rect: BridgeRect;
+    title: string;
+    shared: boolean;
+    locked: boolean;
+};
+export declare function CanvasOverlay({ emptyZones, hoverRect, selection, plusButtons, onPlus, onMove, onDuplicate, onRemove, }: {
+    emptyZones: ZoneRect[];
+    hoverRect: BridgeRect | undefined;
+    selection: OverlaySelection | null;
+    plusButtons: PlusButton[];
+    /** A "+" was clicked, at these viewport coordinates. */
+    onPlus(button: PlusButton, clientX: number, clientY: number): void;
+    onMove(id: string, dir: -1 | 1): void;
+    onDuplicate(node: TreeNode): void;
+    onRemove(id: string): void;
+}): import("react").JSX.Element;

package/dist/admin/editor/CanvasOverlay.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+// The overlay layer above the canvas iframe — every pixel of chrome is
+// ours: empty-zone placeholders, the hover and selection outlines, the
+// selected block's tag and toolbar, and a "+" per insertable boundary.
+// Positions come from the geometry the bridge reported; the layer
+// itself never touches the iframe.
+import { useState } from "react";
+import { IconButton } from "../ui/primitives.js";
+export function CanvasOverlay({ emptyZones, hoverRect, selection, plusButtons, onPlus, onMove, onDuplicate, onRemove, }) {
+    const [hoverPlus, setHoverPlus] = useState(null);
+    return (_jsxs("div", { style: { position: "absolute", inset: 0, pointerEvents: "none" }, children: [emptyZones.map((z) => (_jsxs("div", { className: "sm-dashed sm-mono", style: {
+                    position: "absolute", left: z.x + 12, top: z.y, width: Math.max(0, z.w - 24),
+                    height: Math.max(56, z.h), fontSize: "var(--text-xs)",
+                    letterSpacing: ".04em", textTransform: "uppercase", color: "var(--gray-500)",
+                    borderColor: "var(--gray-300)",
+                }, children: [z.zone, " \u00B7 empty"] }, `empty-${z.zone}`))), hoverRect && (_jsx("div", { style: {
+                    position: "absolute", left: hoverRect.x, top: hoverRect.y,
+                    width: hoverRect.w, height: hoverRect.h,
+                    outline: "1.5px solid color-mix(in srgb, var(--selection) 45%, transparent)",
+                    outlineOffset: -1.5, borderRadius: "var(--radius-sm)",
+                } })), selection && (_jsxs(_Fragment, { children: [_jsx("div", { style: {
+                            position: "absolute", left: selection.rect.x, top: selection.rect.y,
+                            width: selection.rect.w, height: selection.rect.h,
+                            outline: "var(--outline-selection)", outlineOffset: -1.5,
+                            borderRadius: "var(--radius-sm)",
+                        } }), _jsxs("span", { className: "sm-blocktag", style: { position: "absolute", left: selection.rect.x, top: selection.rect.y }, children: [selection.title, selection.shared && " · shared", selection.locked && " · locked"] }), _jsx("div", { className: "sm-blocktoolbar", style: {
+                            position: "absolute", left: selection.rect.x + selection.rect.w - 8, top: selection.rect.y + 8,
+                            transform: "translateX(-100%)", pointerEvents: "auto",
+                        }, children: selection.locked ? (_jsx("span", { className: "sm-mono", style: { fontSize: "var(--text-xs)", color: "#8C94A8", padding: "4px 8px" }, children: "fields only" })) : (_jsxs(_Fragment, { children: [_jsx(IconButton, { label: "Move up", tone: "inverse", onClick: () => onMove(selection.node.id, -1), children: "\u2191" }), _jsx(IconButton, { label: "Move down", tone: "inverse", onClick: () => onMove(selection.node.id, 1), children: "\u2193" }), _jsx(IconButton, { label: "Duplicate", tone: "inverse", onClick: () => onDuplicate(selection.node), children: "\u29C9" }), _jsx(IconButton, { label: "Remove", tone: "inverse", onClick: () => onRemove(selection.node.id), children: "\u00D7" })] })) })] })), plusButtons.map((p) => {
+                const key = `${p.zone}-${p.index}`;
+                const hot = hoverPlus === key;
+                return (_jsxs("div", { style: { position: "absolute", left: 0, right: 0, top: p.y }, children: [hot && _jsx("div", { className: "sm-guide", style: { margin: "0 12px" } }), _jsxs("div", { style: {
+                                position: "absolute", left: "50%", top: 0, transform: "translate(-50%,-50%)",
+                                display: "flex", flexDirection: "column", alignItems: "center", gap: 6,
+                                pointerEvents: "auto",
+                            }, children: [_jsx("button", { className: "sm-plus", "aria-label": `Add to ${p.zone}`, onMouseEnter: () => setHoverPlus(key), onMouseLeave: () => setHoverPlus((k) => (k === key ? null : k)), onClick: (e) => onPlus(p, e.clientX, e.clientY), children: "+" }), hot && _jsxs("span", { className: "sm-tooltip", children: ["Add to ", p.zone] })] })] }, key));
+            })] }));
+}