smoodly 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laniakea Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# smoodly (core package)
+
+Define a component once in code — it's instantly a typed, editable,
+AI-addressable building block your editors can compose, within the rails you
+set. Content lives in Supabase; the admin mounts into your own Next.js app.
+
+    npx create-smoodly-app my-site
+
+A self-hosted app needs three environment variables: `SMOODLY_URL`,
+`SMOODLY_SECRET_KEY` and `SMOODLY_PUBLISHABLE_KEY`.
+Source and docs: https://github.com/laniakea-studio/smoodly-cms
+
+The registration runtime — the real implementation of the API designed in
+Phase 0 (`sketches/phase0/` remains the readable spec; `docs/DESIGN.md`
+holds the decisions). Test-driven; run with `npm test`.
+
+Implemented:
+
+- `f.*` field builders — inert, immutable, JSON-serializable descriptors
+  (ref thunks excepted); validation lives server/admin-side by design rule
+- `smoodly.schema.section/element` — descriptor capture + the
+  fields-only-`localized()` rule enforced at construction
+- `smoodly.section/element(schema, View)` — the typed pairing: returns a
+  real component carrying `.schema`; drift between schema and view is a
+  compile error at the pairing; style select defaults apply in hard-coded
+  JSX use; `Props<typeof schema>` infers required/optional/select types
+- `z.sections([...]).max(n)` / `z.freeform` / `z.locked` — component
+  references in, names stored
+- `smoodly.toolset` — plain values, element refs serialized to names
+- `smoodly.collection` — descriptors + admin hints; ref thunks resolve
+  post-evaluation and infer the target entry shape
+- `defineConfig` — registry name-uniqueness + the automatic standard-style
+  merge (`resolvedStyles`: section keys win, `styleDefaults: false|{omit}`)
+- `<smoodly.Section>` — root wrapper: `as`, string styles → kebab-cased
+  data attributes, className/style passthrough
+
+- `smoodly.schema.page` / `smoodly.page` / `<Zone>` / `renderPage` — the
+  pages runtime: policies normalized to plain data, tree nodes mapped to
+  registered components, fail-soft on unknown types
+- `collectionSQL` / `coreTablesSQL` — the stable schema (DESIGN.md §3):
+  `coreTablesSQL` emits the once-ever core tables including `entries`
+  (`collection` + `fields`/`i18n` jsonb, `space_id` multi-tenancy with
+  a default space for self-hosted, `sort` for manual ordering, ONE
+  generic slug-uniqueness index across all spaces and collections);
+  `collectionSQL` emits only the disposable per-collection guardrails —
+  a published-only read view over `entries` (typed casts, snake_case
+  aliases, refs as plain id values) and partial btree indexes for
+  declared orderBy fields
+- `PageStore` contract + `MemoryPageStore` — draft/publish semantics
+  (versions accumulate; publish moves a pointer; drafts never leak into
+  published reads). The contract is a reusable suite
+  (`test/page-store-contract.ts`); every adapter runs the same tests.
+- `SupabasePageStore` — the Supabase adapter over pages/page_versions
+  (a server-side client from `createSmoodlyClient`: the service role in
+  self-host, a write key in the cloud). Contract-tested against a
+  real local stack: `supabase start` at the repo root (the generated
+  DDL is its one migration), then `npm run test:supabase`; plain
+  `npm test` skips it and never needs Docker.
+- `resolveTree` — the batched ref-resolution pass: one fetch per
+  collection per round, ref-site depth modes (bare ref = entry only,
+  `.resolve(names)` = named refs one level, bare `.resolve()` = whole
+  chain), per-path cycle cutting with shallow copies, optional `maxDepth`
+  safety valve (default unlimited)
+
+- `collectEntryRefs` / `collectTreeRefs` — the refs-index feeders: walk
+  an entry or a page tree against its schemas and list every outgoing
+  reference edge (derived, rebuildable, never the source of truth)
+- Page saves feed the refs index — a page's rows are the UNION of its
+  draft and published trees' edges (source kind `page`), rewritten on
+  every `saveDraft`/`publish`, so cross-kind safe-delete holds while
+  either tree shows an entry. Publish integrity: `publish` walks the
+  draft tree directly and blocks on missing/unpublished entries.
+  Revalidation fan-out: `affectedPageSlugs` — reverse BFS over refs
+  (entry ← entry ← page, cycle-safe, optional `maxDepth`) returning
+  published slugs for the Next glue to `revalidateTag`. All wired via
+  store constructor options (`sections`, `entries`, shared
+  `MemoryRefIndex` in memory); the cross-store contract
+  (`test/page-refs-contract.ts`) runs against memory AND Supabase.
+- `EntryStore` contract + `MemoryEntryStore` + `SupabaseEntryStore` —
+  collection-entry persistence (status-only versioning in v1): saves
+  rewrite the entry's refs rows, `referencesTo` answers the reverse
+  question, `getMany` is the batched read whose signature is
+  `resolveTree`'s `EntryFetcher` (with `{ status: "published" }` for the
+  published-route read — a post-publish demotion resolves as missing
+  instead of leaking draft fields — DESIGN.md §3 "Page edges in refs"), deletes are blocked while
+  referenced,
+  and `reorder` rewrites sort 1..N through the `smoodly_reorder` SQL
+  function (one statement, `updated_at` untouched). Same
+  reusable-contract pattern as PageStore; `npm run test:supabase` runs
+  both adapters against the local stack
+
+- Proven end-to-end in `examples/site` — a real Next.js app wiring the
+  config + Supabase stores into routes: tag-cached resolved trees,
+  draft-mode preview, server-action writes with revalidation fan-out
+
+- The space layer (spec 2026-09-04 §3): `space_id` on every content
+  table, `smoodly_current_space()`, the insert trigger, the row cap, the
+  three cloud-state tables (`editors`, `space_keys`, `space_caps`) and
+  the policy set. Service role bypasses it; a write key is scoped to its
+  space. Contract suites run in both modes; `test/isolation.supabase.test.ts`
+  proves isolation. Generated per-collection views are `security_invoker`,
+  so they read through the same policy set rather than their owner's
+  privileges. Live acceptance test in `test/rls.supabase.test.ts`. Note
+  for self-host: the anon key now reads published rows straight off the
+  base tables (`pages`, `entries` including the `i18n` overlay, a page's
+  published `page_versions` tree, `global_sections`), not only through
+  the generated views.
+
+- Admin login: `supabaseAdminAuth` + `gateAdminOp` around the ops seam;
+  `LoginView` + `useAdminSession` in the shell; `createSmoodlyAdmin({ auth })`.
+  Env: `smoodlyEnv()` / `createSmoodlyClient()`.
+
+- The admin, real and mounted: `smoodly/admin` (the AdminOps seam —
+  `createAdminOps`/`runAdminOp` server-side over the stores,
+  `makeClientOps` client-side forwarding `{ path, args }` through one
+  server action; typed `OpResult`, never throws — `serializeAdminConfig`
+  turns the registry into the admin's nav/forms; `validateFields` +
+  tree-ops for pure canvas mutations), `smoodly/admin/next`
+  (`createSmoodlyAdmin` binds registry + op action into `AdminPage`/
+  `AdminLayout` for the app's `[[...segments]]` route group;
+  `createAdminOpHandler` is the one server action the client ops call),
+  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),
+  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
+  canvas — the iframe is the site's own draft route, pixel-identical by
+  construction; every gesture mutates client tree state through pure
+  ops, a debounced `saveDraft` persists, and the bridge refreshes the
+  iframe on the save ack — refresh-on-change preview, not a live DOM
+  sync) are all real, in-house. The autosave itself is a framework-free
+  controller (`createDraftAutosave`: debounce, doubling capped retry,
+  pre-publish `flush`) wrapped by `useDraftAutosave`; the controller is
+  unit-tested with fake timers, the hook only for its initial snapshot. Proven end-to-end in
+  `examples/site/app/(smoodly)/admin` against the local Supabase stack —
+  see its README's acceptance walk.
+
+- `smoodly/next` — `createPageRenderer`, the site-route seam: draft
+  branch, tag-cached published read, ref resolution, 404 and editor
+  bridge behind one `renderSmoodlyPage(Page, { slug?, searchParams? })`,
+  plus `smoodlyMetadata` for `generateMetadata`. Both await Next's
+  `connection()` before reading the stores, so a fixed-slug route is
+  request-rendered without a `force-dynamic` export and `next build`
+  never reaches the database (`test/next-page-renderer.test.tsx`). Bound
+  once by the app, like `createAdminOpHandler`. Page schemas may declare a fixed `slug`
+  (a singleton owned by one route file); the admin reads it to filter
+  New Page and protect the record. `defineConfig({ homePageSlug })`
+  (default `"home"`) names the slug the site root serves; the admin's
+  `pagePath()` maps it to `/` — canvas URL and Pages list — and every
+  other slug to `/<slug>`.
+
+- Locked zones are usable: `fillLockedZones` (a pure tree op) materializes
+  the one node of every empty locked zone from the component's `sample`
+  when the editor loads a draft, and the change rides the normal debounced
+  save. No gesture can insert into or remove from a locked zone, so this is
+  the only way the node gets there — it also covers pages that existed
+  before a locked zone was added to their schema.
+
+Not yet: richtext components (TipTap; `plainToRichtext`/
+`richtextToPlain` exist but no rich editor widget), drag-and-drop
+reordering (move-up/move-down buttons only), undo/redo, sample/
+placeholder content marking, editor localization (the
+locale switcher — examples/site is single-locale so it stays hidden).
+
+## Releasing
+
+Both packages move together. From the repo root:
+
+    npm version 0.0.2 -w smoodly -w create-smoodly-app --no-git-tag-version
+    npm run build
+    npm publish -w smoodly --access public
+    npm publish -w create-smoodly-app --access public
+    git commit -am "release: 0.0.2" && git tag v0.0.2 && git push --tags origin main
+
+`prepublishOnly` rebuilds each package; the CLI's template is regenerated from
+`examples/site` in that build, so the template always matches the example
+site at the tagged commit.
+
+## Follow-ups (logged 2026-09-04)
+
+- Cloud-ready foundation — done, including the self-host init
+  (`create-smoodly-app`, spec 2026-09-04). Remaining from the spec: none
+  in the package. The two-mode contract suites and the isolation suite
+  run in CI in the `smoodly-supabase` job (a local stack on the runner) — if that job
+  proves flaky, the fallback is a Postgres service container applying
+  the one migration.
+- Once the policy-based published read exists, decide whether it becomes the canonical headless read path and the generated per-collection views turn optional (cloud has no views).
+- Add an index on `pages(published_version_id)`: the `page_versions` read policy's `exists` probe runs on every anon/read-key read and has no supporting index.
+- A malformed `space_id`/`key_id` claim raises `22P02` inside the policy: fails closed but surfaces as a 500. Only reachable from a validly-signed key, so it is a cloud key-minting guard, not a request-path one.
+- Authorization trusts the JWT claims alone; `smoodly_space_key_revoked()` checks only `revoked_at`. When cloud key-minting exists, make it a full key check (the claims must match the `space_keys` row).
+- `isEditor` reads `editors` with no space filter: under a cloud write key RLS scopes it, but a service-role client bypasses RLS and would admit an editor of any space. Harmless in self-host (one space); never use a service-role client against the shared content project.
+- The `sb_secret_` branch of `clientOptions` is unit-tested for shape only; the local stack uses legacy JWT keys, so a new-format secret key has not been exercised live against PostgREST and the GoTrue admin API.
+- The migration is not re-appliable to a pre-rename (`project_id`) database: `create table if not exists` leaves it untouched and the `space_id` policies then fail. No installs predate the rename; fold into DESIGN.md OQ #2 (schema upgrades).
+- `examples/site/lib/smoodly/index.ts` should carry `import "server-only"` now that it also exports `publicAuth` — a client-side import would fail loudly at build instead of at runtime.
+- `exports` has no `"./package.json"` entry, so tooling that reads a dependency's `package.json` through the exports map cannot. One line to add when something needs it.
+- `src/ref-index.ts` contains two raw NUL bytes used as key separators, which makes git show the file as binary in diffs. Replacing them with `\0` escapes would make it diffable again.
+
+## Follow-ups (logged 2026-09-03)
+
+- Empty locked zones on the site side: `renderPage` renders nothing for a locked zone with no node. A page that predates the zone shows no prefooter on the published site until an editor opens it (the editor fills and saves). Options: render the component from `sample` when the zone is empty, or fill on `createPage`/schema load server-side. Fine for now — seeded and admin-created pages both arrive filled.
+
+- Editor canvas URL mapping: now `homePageSlug` config (done 2026-09-03); remaining follow-up is a registration-declared `path` for fixed pages at arbitrary paths.
+- `serialize.ts` structural cast duplicates `PageSchema`; tighten `Registered.schema` so the cast goes.
+- Pages list: no re-entrancy guard on a fast double-click of "New page" / a not-created row, and the row `onClick` promise is unhandled (a transport throw is an unhandled rejection); fix both together with a `.catch` → alert.
+- `pagesRows`: pin with a test the case of a record at a fixed slug whose `template` is an open registration (self-healing today: `/` 404s, `/<slug>` serves it, delete is allowed, then the singleton row reappears).
+- 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.
+- Next acceptance walk: start from a database with no `home` record so the "not created" singleton row is exercised.
+- `EditorView` split, remaining seams (autosave extracted 2026-09-03): 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).

package/dist/admin/auth.d.ts

@@ -0,0 +1,10 @@
+import type { AdminOpCall, OpResult } from "./ops.ts";
+export type AdminAuth = {
+    /** The user behind a session token, or null when the auth project rejects it. */
+    verify(token: string): Promise<{
+        userId: string;
+    } | null>;
+    /** Does `editors` hold this user for the current space? */
+    isEditor(userId: string): Promise<boolean>;
+};
+export declare function gateAdminOp(auth: AdminAuth, call: AdminOpCall, run: (call: AdminOpCall) => Promise<OpResult<unknown>>): Promise<OpResult<unknown>>;

package/dist/admin/auth.js

@@ -0,0 +1,28 @@
+const unauthorized = (message) => ({ ok: false, code: "unauthorized", message });
+export async function gateAdminOp(auth, call, run) {
+    const token = typeof call === "object" && call !== null && typeof call.token === "string"
+        ? call.token
+        : null;
+    if (!token)
+        return unauthorized("smoodly: sign in to use the admin.");
+    let session;
+    let editor;
+    try {
+        session = await auth.verify(token);
+        if (!session)
+            return unauthorized("smoodly: your session has expired — sign in again.");
+        editor = await auth.isEditor(session.userId);
+    }
+    catch (e) {
+        console.error("smoodly: auth check failed", e);
+        return {
+            ok: false,
+            code: "internal",
+            message: "smoodly: could not check your session.",
+        };
+    }
+    if (!editor) {
+        return unauthorized("smoodly: this account is not an editor of this site.");
+    }
+    return run(call);
+}

package/dist/admin/client-ops.d.ts

@@ -0,0 +1,2 @@
+import type { AdminOpAction, AdminOps } from "./ops.ts";
+export declare function makeClientOps(action: AdminOpAction, token?: () => string | null): AdminOps;

package/dist/admin/client-ops.js

@@ -0,0 +1,18 @@
+const GROUPS = {
+    pages: ["list", "get", "create", "saveDraft", "publish", "delete"],
+    entries: ["list", "get", "create", "save", "setStatus", "delete"],
+    preview: ["enable", "disable"],
+};
+export function makeClientOps(action, token) {
+    const out = {};
+    for (const [group, methods] of Object.entries(GROUPS)) {
+        out[group] = {};
+        for (const method of methods) {
+            out[group][method] = (...args) => {
+                const t = token?.() ?? null;
+                return action({ path: `${group}.${method}`, args, ...(t ? { token: t } : {}) });
+            };
+        }
+    }
+    return out;
+}

package/dist/admin/editor/EditorView.d.ts

@@ -0,0 +1,7 @@
+import type { AdminOps } from "../ops.ts";
+import type { AdminRegistry } from "../serialize.ts";
+export declare function EditorView({ ops, registry, slug }: {
+    ops: AdminOps;
+    registry: AdminRegistry;
+    slug: string;
+}): import("react").JSX.Element;