smoodly 0.0.8 → 0.0.10

package/README.md

@@ -194,7 +194,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
@@ -314,8 +317,31 @@ Implemented:
   with "used on N pages" from `refs`. Wired through the `shared` option
   on the entry store and the site layer.
 
-Not yet: richtext components (TipTap; `plainToRichtext`/
-`richtextToPlain` exist but no rich editor widget), drag-and-drop
+- Lists and editable objects (spec 2026-09-07 list field): `f.list(item)`
+  holds any builder but another list and refuses a ref or `.localized()`
+  anywhere inside (refs are top-level only; localization is whole-value on
+  a list or object). `.min`/`.max` count items. The admin edits an object
+  as an indented fieldset and a list as rows — summary, collapse, move up
+  and down, remove, "N of max", Add disabled at max — recursively through
+  `FieldWidget`, with the row logic as pure functions in `admin/forms/list.ts`.
+  `validateFields` recurses with dotted paths (`points.2.heading`) and
+  checks list length; the serializer ships a list's `item`.
+
+- 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; 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
@@ -336,6 +362,186 @@ 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).
+- 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.
+
+## 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
+  a layout cannot hand the footer the contact item or the header the locale
+  links through the paired `Footer`/`Header`; the starter's layouts render
+  `FooterView`/`HeaderView` directly with the extra prop. A supported way
+  to pass layout-only props through a paired component (or a `children`
+  slot) would let the layouts use the registered component.
+- Page views and entry pages receive no `locale`; the starter's views get
+  it from the app's strings seam (`next-intl`'s `getLocale`, or a constant
+  in the single-language scaffold). Adding `locale` to `PageContext` and
+  `EntryPageProps` would remove that dependency and let sections that
+  format dates stay synchronous.
+- The content API is published-only, so the Articles index in the editor
+  canvas lists published articles while the hero above it is the draft.
+  A draft-aware `getEntries` for draft mode is the fix if that confuses.
+- The image widget edits the URL only; `alt` is set by the seed and cannot
+  be changed in the admin.
+- A per-locale collection path or fixed slug must name the default locale;
+  the installer rewrites the starter's two lines to name exactly the
+  chosen locales (`articlesSegments` in `scaffold.ts`), since a path
+  claiming a locale the site lacks fails the index-page rule at config
+  load. A "fall back to the first declared segment" rule in
+  `defineConfig` would make the patch unnecessary.
+- The picker offers a shared item only in zones whose allow list includes
+  its section (`allowedShared` in `admin/tree-ops.ts`), so a shared item's
+  section is always also offered as an ordinary section. A "placeable
+  only" mode (a shared item whose section no zone lists) would let the
+  starter keep the quote shared-only.
+- Registry names are one namespace across sections, elements, collections
+  and page shapes (`assertUniqueNames`); the starter names its People
+  section `peopleSection` and its Articles page `articlesIndex` to stay
+  clear of the collections. Namespacing by kind would let a section and a
+  collection share a name.
+- The seed's early exit probes `/` alone, and `createPage` writes the path
+  row before the tree is published, so a crash between the home record and
+  the last page leaves a database every later run reports as "already
+  seeded"; recovery is `supabase db reset`. A probe on the last thing the
+  seed writes, or a per-step check, would make it resumable.
+- With `fi` as the default locale the seed writes the English content into
+  `fi`. Before this fix the index page was seeded at `posts`
+  while the collection's `fi` path is `artikkelit`, so `ensureFixedNodes`
+  materialized a second, empty Articles page at `artikkelit` and the
+  links pointed at `/posts`; the seed now derives the segment from the
+  collection's `path` per locale. Left: the starter's copy in a `fi`
+  default is still English.
+- Config-level section style defaults (`styles.sections` in `defineConfig`)
+  are not filled at render: a node saved without an explicit style emits
+  no `data-spacing`/`data-tone`, so a stylesheet cannot key the default
+  on the attribute. The starter pads body sections by element instead.
+  Filling the resolved defaults in the render pass (as the admin form
+  does) would make the attributes reliable (walk, 2026-09-07).
+- A new list item's `select` subfield shows the first option but stores
+  nothing (`emptyValue` leaves it undefined), so publish fails with
+  `points.3.icon: Required` until the editor re-picks the value that is
+  already on screen. Seed the first option, or render a blank option so
+  the screen matches the value (walk, 2026-09-07).
+- Publish validates the last saved draft, so a click inside the autosave
+  debounce reports fields the editor has just filled as `Required`. Flush
+  the pending save before validating, or disable Publish while a save is
+  pending (walk, 2026-09-07).
+- The entry form cannot republish a published entry's newer draft: Save
+  writes a new draft version, the status control's `setPublished` returns
+  early when the status is unchanged, and nothing shows that the draft
+  differs from the published version. The workaround unpublishes and
+  republishes, which 404s the entry in between. Needs a "Publish changes"
+  action and a draft-edits indicator like the page editor's (walk,
+  2026-09-07).
+- Versions accumulate (`entry_versions` grew to four rows after one edit)
+  but no admin screen lists or restores them (walk, 2026-09-07).
+- A list row's collapsed summary shows the item's first string subfield —
+  the header nav rows read `/`, `/posts` — where the label would identify
+  the row; `itemSummary` could prefer a `label`/`title`/`heading` key
+  (walk, 2026-09-07).
+- New page / New folder ask for the slug through `window.prompt`, which
+  browser automation blocks and which cannot validate as you type; an
+  inline field would do both (walk, 2026-09-07).
+
+## Follow-ups (logged 2026-09-07, list field spec)
+
+- Saving the interim richtext textarea drops marks (bold, italic, link);
+  flattens a hard break inside a heading, list item or blockquote line to a
+  space (a prefixed line cannot carry one, DESIGN.md §3 Richtext); and drops
+  anything the line syntax cannot express at all — nested lists,
+  multi-paragraph list items (joined with a space instead), and unknown
+  nodes such as a horizontal rule. All of it goes away with the TipTap
+  widget.
+- Refs inside lists and objects are refused at build time (`f.list`,
+  `f.object`). A list of objects each holding a ref (a featured entry with
+  its own caption) needs the resolver, the refs index and the admin's
+  ref-option loading to address nested paths; add when a site asks.
+- Heading levels 4–6 render but the line syntax writes `####`…`######`
+  for them; the spec names 1–3 as the supported set.
+- `emptyValue` for an `image`/`video`/`file` item is `undefined`, so a new
+  media row starts empty; a required image item is then a validation
+  error until filled, which is the intended nudge but reads as an error
+  on a row the editor just added.
+- `RichText` drops the anchor of a link mark whose href is not http(s),
+  mailto, tel or site-relative (`/`, `#`, `?`, `.`). The href is normalised
+  the way URL parsers do (tab, LF and CR removed) before the scheme test;
+  `javascript:`, `data:`, protocol-relative `//host` and the backslash form
+  `/\host` are rejected. The admin's link field does not validate on input yet.
+- The list widget has no test for an object item holding a nested list
+  subfield.
+- A list item's subtree still uses the row index as its React key, so a list
+  of objects each holding a list hands the inner rows another item's collapse
+  state when an outer row moves; fix with a stable per-item key when nested
+  lists get real use.
+
 ## Follow-ups (logged 2026-09-07, shared content spec)
 
 - `f.shared(() => item)` — a ref field on a section that renders a shared
@@ -361,21 +567,17 @@ site at the tagged commit.
 - `getSmoodlyShared` reads the store per request in draft mode and once
   per (item, locale) otherwise; a layout calling it for several items
   makes one round trip each — batch if it shows.
-- The Supabase entry store's singleton check is SELECT-then-INSERT with
-  no unique index; two admin loads racing on an item's first
-  materialization can create two rows. `ensureSharedItems` reads the
-  first row either way, and the duplicate cannot be removed through the
-  API — `delete` refuses every shared row. Two ways to make the race
-  impossible: a deterministic row id (uuid v5 of the item name, so the
-  second insert fails on the primary key — no schema change), or a
-  per-item partial unique index emitted by the SQL generator the way
-  `collectionSQL` emits the rest.
+- A shared item's row id is now uuid v5 of (space, name), so the primary
+  key ends the materialization race — but only for rows created from now
+  on: an item materialized before this change keeps its random
+  `gen_random_uuid()` id, and a second load would still be able to insert
+  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.
@@ -408,6 +610,14 @@ site at the tagged commit.
 - `ops.entries.move` expires entry tags directly and does not `fanOut`,
   so a reorder that changes what a shared item's `refList` renders does
   not expire `shared:<name>`.
+- The package root (`src/index.ts`) must stay free of Node builtins:
+  every scaffolded section does `import { f, smoodly } from "smoodly"`,
+  and a `"use client"` section's browser build would fail on one.
+  `sharedEntryId` (`src/shared-id.ts`) moved off `node:crypto` onto Web
+  Crypto for this reason (fix pass, 2026-09-07). Nothing tests the
+  invariant itself — a future addition that reaches for `node:fs`,
+  `node:crypto`, etc. from a module reachable through the root would
+  regress it silently.
 
 ## Follow-ups (logged 2026-09-06)
 
@@ -826,4 +1036,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/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));
+            })] }));
+}