smoodly 0.0.18 → 0.0.20

package/dist/admin/shell/router.js

@@ -1,20 +1,20 @@
 "use client";
 // packages/smoodly/src/admin/shell/router.ts
 // The admin's own router (spec 2026-09-08 client routing): the route is
-// the URL under BASE, held in React state and moved with pushState, so
-// the shell stays mounted and a click is a state change, not a document
-// load. The URL is the only source: the shell's first render is the
+// the URL under the admin path, held in React state and moved with
+// pushState, so the shell stays mounted and a click is a state change,
+// not a document load. The URL is the only source: the shell's first render is the
 // session gate, so no view exists before the mount effect has read it.
 // Next's router is not involved — native pushState updates its
 // usePathname without a refetch — and the admin core stays
 // framework-agnostic.
 import { useEffect, useState } from "react";
-import { BASE } from "./base.js";
+import { DEFAULT_ADMIN_PATH } from "../../admin-path.js";
 /** The segments under `base`: "/admin/articles/x" → ["articles", "x"];
  *  the mount itself, or a pathname outside it, → []. Segments stay as
  *  written; the shell decodes the ones it uses, as it does for the
  *  catch-all's params. */
-export function segmentsOf(pathname, base = BASE) {
+export function segmentsOf(pathname, base = DEFAULT_ADMIN_PATH) {
     if (pathname !== base && !pathname.startsWith(`${base}/`))
         return [];
     return pathname.slice(base.length).split("/").filter((s) => s !== "");
@@ -40,10 +40,13 @@ export function mayLeave(guards, confirm) {
 // ── the live router ──────────────────────────────────────────────────
 const guards = new Set();
 const listeners = new Set();
-function currentRoute() {
-    return { segments: segmentsOf(window.location.pathname), search: window.location.search };
+function currentRoute(base) {
+    const { pathname, search } = window.location;
+    return { pathname, segments: segmentsOf(pathname, base), search };
 }
-const sameRoute = (a, b) => a.search === b.search && a.segments.length === b.segments.length && a.segments.every((s, i) => s === b.segments[i]);
+// The segments derive from the pathname and a base that never changes
+// under a mounted shell, so two strings decide sameness.
+const sameRoute = (a, b) => a.pathname === b.pathname && a.search === b.search;
 /** Move to `href` in place; true when the move happened. A push asks the
  *  leave guard; a replace never leaves the view, so it does not ask.
  *  `force` skips the guard for a view that has just saved or deleted its
@@ -56,17 +59,17 @@ export function navigate(href, opts = {}) {
         listener();
     return true;
 }
-/** The current route: empty until mount, then the URL, re-read on
- *  popstate and after navigate(). */
-export function useRoute() {
-    const [route, setRoute] = useState({ segments: [], search: "" });
+/** The current route under `base`: empty until mount, then the URL,
+ *  re-read on popstate and after navigate(). */
+export function useRoute(base) {
+    const [route, setRoute] = useState({ pathname: "", segments: [], search: "" });
     useEffect(() => {
-        const sync = () => setRoute((prev) => { const next = currentRoute(); return sameRoute(prev, next) ? prev : next; });
+        const sync = () => setRoute((prev) => { const next = currentRoute(base); return sameRoute(prev, next) ? prev : next; });
         sync();
         listeners.add(sync);
         window.addEventListener("popstate", sync);
         return () => { listeners.delete(sync); window.removeEventListener("popstate", sync); };
-    }, []);
+    }, [base]);
     return route;
 }
 /** Register the calling view as dirty: navigate() asks before leaving,

package/dist/admin/ui/Combobox.d.ts

@@ -0,0 +1,30 @@
+import { type KeyboardEvent, type ReactNode } from "react";
+import { type ComboOption } from "./combo-box.ts";
+export type ComboboxProps = {
+    options: ComboOption[];
+    onPick(value: string): void;
+    /** Accessible name of the input. */
+    label: string;
+    placeholder?: string;
+    disabled?: boolean;
+    /** Stay open with the query cleared after a pick (multi-select). */
+    keepOpen?: boolean;
+    /** Shown when there are no options at all; "No matches" covers a filter that leaves nothing. */
+    emptyText?: string;
+    renderOption?(o: ComboOption): ReactNode;
+    /** Free text: Enter with no active row submits the query, and no row starts active. */
+    onSubmit?(query: string): void;
+    /** With `onSubmit`: a last row, `Create "query"`, unless an option's label equals the query. */
+    createRow?: boolean;
+    /** Every query change passes through; the return value is the query kept. */
+    onQueryChange?(next: string): string;
+    /** Keys the owner wants first; return true when handled. */
+    onInputKey?(e: KeyboardEvent<HTMLInputElement>, query: string): boolean;
+    /** Escape, or focus leaving the control; `query` is what was typed and not picked. */
+    onClose?(query: string, reason: "escape" | "blur"): void;
+    autoFocus?: boolean;
+    /** Start open: the tags input, and static-markup tests. */
+    initialOpen?: boolean;
+    className?: string;
+};
+export declare function Combobox({ options, onPick, label, placeholder, disabled, keepOpen, emptyText, renderOption, onSubmit, createRow, onQueryChange, onInputKey, onClose, autoFocus, initialOpen, className, }: ComboboxProps): import("react").JSX.Element;

package/dist/admin/ui/Combobox.js

@@ -0,0 +1,89 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A text input with a listbox under it (spec 2026-09-17 §1): the reference
+// picker and the tags input are both this. It knows nothing about entries
+// or tags — options in, a pick out. Decisions live in ./combo-box.ts.
+// Rows keep the input focused (mousedown is swallowed), so "focus left the
+// control" is the one close signal besides Escape.
+import { useId, useLayoutEffect, useRef, useState } from "react";
+import { ChevronDown } from "lucide-react";
+import { cx } from "./primitives.js";
+import { filterOptions, opensUp, showsCreate, stepActive } from "./combo-box.js";
+const keepFocus = (e) => e.preventDefault();
+/** The vertical band the list may occupy: the nearest clipping ancestor's box, cut to the viewport. */
+function clipBand(el) {
+    let top = 0;
+    let bottom = window.innerHeight;
+    for (let p = el.parentElement; p; p = p.parentElement) {
+        if (/(auto|scroll|hidden|clip)/.test(getComputedStyle(p).overflowY)) {
+            const r = p.getBoundingClientRect();
+            top = Math.max(top, r.top);
+            bottom = Math.min(bottom, r.bottom);
+            break;
+        }
+    }
+    return { top, bottom };
+}
+export function Combobox({ options, onPick, label, placeholder, disabled, keepOpen, emptyText, renderOption, onSubmit, createRow, onQueryChange, onInputKey, onClose, autoFocus, initialOpen = false, className, }) {
+    const rest = onSubmit ? -1 : 0; // the active row a fresh query starts from
+    const [query, setQuery] = useState("");
+    const [open, setOpen] = useState(initialOpen);
+    const [active, setActive] = useState(rest);
+    const root = useRef(null);
+    const list = useRef(null);
+    const [up, setUp] = useState(false);
+    const id = useId();
+    const shown = filterOptions(options, query);
+    const create = onSubmit !== undefined && createRow === true && showsCreate(options, query);
+    const count = shown.length + (create ? 1 : 0);
+    // Free text with nothing to offer shows no popover; a picker says why it is empty.
+    const popover = open && !disabled && (count > 0 || !onSubmit);
+    // A field at the bottom of a scrolling form has no room under it: the list hangs above instead.
+    useLayoutEffect(() => {
+        if (!popover || !root.current || !list.current)
+            return;
+        const box = root.current.getBoundingClientRect();
+        const band = clipBand(root.current);
+        setUp(opensUp({ below: band.bottom - box.bottom - 4, above: box.top - band.top - 4, height: list.current.offsetHeight }));
+    }, [popover, count]);
+    const reset = () => { setQuery(""); setActive(rest); };
+    const close = (reason) => {
+        setOpen(false);
+        onClose?.(query, reason);
+        reset();
+    };
+    const pick = (i) => {
+        if (i < shown.length)
+            onPick(shown[i].value);
+        else
+            onSubmit?.(query);
+        reset();
+        if (!keepOpen)
+            setOpen(false);
+    };
+    const onKeyDown = (e) => {
+        if (onInputKey?.(e, query))
+            return;
+        if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+            e.preventDefault();
+            setOpen(true);
+            setActive((a) => stepActive(a, count, e.key === "ArrowDown" ? 1 : -1));
+        }
+        else if (e.key === "Enter") {
+            e.preventDefault();
+            if (open && active >= 0 && active < count)
+                pick(active);
+            else if (onSubmit && query.trim() !== "") {
+                onSubmit(query);
+                reset();
+            }
+        }
+        else if (e.key === "Escape") {
+            if (open)
+                e.stopPropagation(); // a modal behind it stays open
+            close("escape");
+        }
+    };
+    return (_jsxs("div", { ref: root, className: cx("sm-combo", className), children: [_jsx("input", { className: "sm-input", role: "combobox", "aria-label": label, "aria-autocomplete": "list", "aria-expanded": popover, "aria-controls": `${id}-list`, "aria-activedescendant": popover && active >= 0 ? `${id}-opt-${active}` : undefined, placeholder: placeholder, disabled: disabled, autoFocus: autoFocus, value: query, onFocus: () => setOpen(true), onClick: () => setOpen(true), onChange: (e) => { setQuery(onQueryChange ? onQueryChange(e.target.value) : e.target.value); setActive(rest); setOpen(true); }, onKeyDown: onKeyDown, onBlur: (e) => { if (open && !root.current?.contains(e.relatedTarget))
+                    close("blur"); } }), _jsx(ChevronDown, { className: "sm-combo__chevron", size: 14, strokeWidth: 1.75, "aria-hidden": "true" }), popover && (_jsxs("div", { ref: list, id: `${id}-list`, role: "listbox", "aria-label": label, className: cx("sm-picker sm-combo__list", up && "sm-combo__list--up"), children: [count === 0 && _jsx("div", { className: "sm-combo__empty", children: options.length === 0 ? emptyText ?? "No matches" : "No matches" }), shown.map((o, i) => (_jsx("button", { id: `${id}-opt-${i}`, type: "button", role: "option", "aria-selected": i === active, className: cx("sm-picker__item", i === active && "sm-picker__item--active"), onMouseDown: keepFocus, onClick: () => pick(i), children: renderOption ? renderOption(o) : o.label }, o.value))), create && (_jsxs("button", { id: `${id}-opt-${shown.length}`, type: "button", role: "option", "aria-selected": active === shown.length, className: cx("sm-picker__item", active === shown.length && "sm-picker__item--active"), onMouseDown: keepFocus, onClick: () => pick(shown.length), children: ["Create \u201C", query.trim(), "\u201D"] }))] }))] }));
+}

package/dist/admin/ui/combo-box.d.ts

@@ -0,0 +1,16 @@
+export type ComboOption = {
+    value: string;
+    label: string;
+};
+/** A case-insensitive substring match on the label; an empty query keeps every option. */
+export declare function filterOptions(options: ComboOption[], query: string): ComboOption[];
+/** Whether `Create "query"` is offered: something is typed and no label equals it. */
+export declare function showsCreate(options: ComboOption[], query: string): boolean;
+/** The next active row, wrapping. -1 is "no row" (free text): ↓ enters at the top, ↑ at the bottom. */
+export declare function stepActive(active: number, count: number, dir: 1 | -1): number;
+/** Whether the list hangs above the input: only when it does not fit below and there is more room above. */
+export declare const opensUp: (room: {
+    below: number;
+    above: number;
+    height: number;
+}) => boolean;

package/dist/admin/ui/combo-box.js

@@ -0,0 +1,21 @@
+const fold = (s) => s.trim().toLocaleLowerCase();
+/** A case-insensitive substring match on the label; an empty query keeps every option. */
+export function filterOptions(options, query) {
+    const q = fold(query);
+    return q === "" ? options : options.filter((o) => o.label.toLocaleLowerCase().includes(q));
+}
+/** Whether `Create "query"` is offered: something is typed and no label equals it. */
+export function showsCreate(options, query) {
+    const q = fold(query);
+    return q !== "" && !options.some((o) => fold(o.label) === q);
+}
+/** The next active row, wrapping. -1 is "no row" (free text): ↓ enters at the top, ↑ at the bottom. */
+export function stepActive(active, count, dir) {
+    if (count === 0)
+        return -1;
+    if (active < 0)
+        return dir === 1 ? 0 : count - 1;
+    return (active + dir + count) % count;
+}
+/** Whether the list hangs above the input: only when it does not fit below and there is more room above. */
+export const opensUp = (room) => room.height > room.below && room.above > room.below;

package/dist/admin/ui/theme.js

@@ -858,6 +858,42 @@ body:has(.sm-admin){margin:0}
   width:26px;height:26px;flex:none;border-radius:var(--radius-sm);background:var(--accent-soft);
   color:var(--accent);display:grid;place-items:center;font-size:13px;
 }
+/* Combobox (spec 2026-09-17 §1): the input owns the width, the list hangs under it. */
+.sm-combo{position:relative}
+.sm-combo .sm-input{width:100%;padding-right:30px}
+.sm-combo__chevron{position:absolute;right:10px;top:50%;transform:translateY(-50%);pointer-events:none;color:var(--text-muted)}
+.sm-combo__list{position:absolute;top:calc(100% + 4px);left:0;right:0;width:auto;max-height:280px;overflow-y:auto;z-index:60}
+.sm-combo__list--up{top:auto;bottom:calc(100% + 4px)}
+.sm-combo__empty{padding:8px 10px;color:var(--text-muted);font-size:var(--text-sm)}
+/* Reference picker (spec 2026-09-17 §2): the picked entries under the search input. */
+.sm-refpicker{display:flex;flex-direction:column;gap:6px;min-width:0}
+.sm-refpicker__rows{display:flex;flex-direction:column;gap:4px}
+.sm-refpicker__title{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.sm-refrow{
+  display:flex;align-items:center;gap:6px;height:var(--control-h-sm);padding:0 6px 0 10px;
+  border:1px solid var(--line);border-radius:var(--radius-md);background:var(--surface);min-width:0;
+}
+.sm-refrow:has(.sm-grip){padding-left:6px}
+.sm-refrow:hover .sm-grip{opacity:1}
+.sm-refrow--muted .sm-refpicker__title{color:var(--text-muted)}
+.sm-refrow__note{font-size:var(--text-sm)}
+.sm-refrow a.sm-iconbtn{text-decoration:none}
+/* Tags (spec 2026-09-17 §5): chips that wrap, a dashed + Add, the inline input in its place. */
+.sm-tags{display:flex;flex-wrap:wrap;gap:6px;align-items:center}
+.sm-tag{
+  display:inline-flex;align-items:center;gap:6px;height:var(--control-h-sm);padding:0 10px;border:0;
+  border-radius:var(--radius-sm);background:var(--surface-inset);color:var(--text);font:inherit;font-size:var(--text-sm);white-space:nowrap;
+  transition:background .2s;
+}
+.sm-tag--flash{background:var(--accent-soft)}
+.sm-tag__x{border:0;background:transparent;padding:0;color:var(--text-muted);cursor:pointer;font:inherit;line-height:1}
+.sm-tag__x:hover{color:var(--text)}
+.sm-tag--add{background:transparent;border:1px dashed var(--line);color:var(--text-muted);cursor:pointer}
+.sm-tag--add:hover{color:var(--text);border-color:var(--text-muted)}
+.sm-combo--tag{width:180px}
+.sm-combo--tag .sm-input{height:var(--control-h-sm);padding-right:10px}
+.sm-combo--tag .sm-combo__chevron{display:none}
+.sm-combo--tag .sm-combo__list{right:auto;width:240px}
 .sm-dashed{
   border:1px dashed var(--line-dashed);border-radius:var(--radius-lg);
   display:flex;align-items:center;justify-content:center;gap:8px;color:var(--text-subtle);

package/dist/admin/validate.js

@@ -8,6 +8,7 @@
 import { optionValues } from "../fields.js";
 import { isHidden } from "../conditions.js";
 import { cssProblem } from "../css.js";
+import { normalizeTag, sameTag } from "../tags.js";
 import { hasContent } from "./richtext-doc.js";
 import { ELEMENT_NODE, richtextBlocks } from "../richtext-walk.js";
 import { rowsProblems } from "../custom/rows.js";
@@ -89,6 +90,44 @@ function validateValue(path, value, d, errors, elements, scope) {
         }
         return;
     }
+    // Refs (spec 2026-09-17 §3): the shape and the count. Whether a target exists
+    // and is published is publish integrity's question (store.ts), not this one's.
+    if (d.type === "ref") {
+        if (typeof value !== "string")
+            errors.push({ field: path, message: "Must be an entry." });
+        return;
+    }
+    if (d.type === "refList") {
+        if (!Array.isArray(value) || value.some((v) => typeof v !== "string" || v === "")) {
+            errors.push({ field: path, message: "Must be a list of entries." });
+            return;
+        }
+        if (typeof d.min === "number" && value.length < d.min)
+            errors.push({ field: path, message: `At least ${plural(d.min, "item")}.` });
+        if (typeof d.max === "number" && value.length > d.max)
+            errors.push({ field: path, message: `At most ${plural(d.max, "item")}.` });
+        // The refs index keys on (source, field, target): a repeat renders twice and indexes once.
+        if (new Set(value).size !== value.length)
+            errors.push({ field: path, message: "The same entry is listed twice." });
+        return;
+    }
+    if (d.type === "tags") {
+        if (!Array.isArray(value)) {
+            errors.push({ field: path, message: "Must be a list of tags." });
+            return;
+        }
+        if (typeof d.min === "number" && value.length < d.min)
+            errors.push({ field: path, message: `At least ${plural(d.min, "item")}.` });
+        if (typeof d.max === "number" && value.length > d.max)
+            errors.push({ field: path, message: `At most ${plural(d.max, "item")}.` });
+        value.forEach((v, i) => {
+            if (typeof v !== "string" || v === "" || normalizeTag(v) !== v)
+                errors.push({ field: `${path}.${i}`, message: "Must be a trimmed, non-empty tag." });
+            else if (value.slice(0, i).some((u) => typeof u === "string" && sameTag(u, v)))
+                errors.push({ field: `${path}.${i}`, message: "Duplicate tag." });
+        });
+        return;
+    }
     if (d.type === "checkboxes") {
         if (!Array.isArray(value)) {
             errors.push({ field: path, message: "Must be a list." });

package/dist/admin-path.d.ts

@@ -0,0 +1,17 @@
+export declare const DEFAULT_ADMIN_PATH = "/admin";
+/** `/` plus exactly one segment (spec 2026-09-17 slug guard §1): with one
+ *  segment only a ROOT slug can collide with the admin, so the guard is a
+ *  string comparison. */
+export declare function assertAdminPath(path: unknown): asserts path is string;
+/** True when `slug` is the admin's own segment: Next serves the static
+ *  admin folder before the site catch-all, so a root page, a collection
+ *  path or a fixed slug that takes it can never be opened. */
+export declare const isAdminSlug: (slug: string, adminPath: string) => boolean;
+/** What an editor reads when a root page would take the admin's segment. */
+export declare const adminSlugTaken: (adminPath: string) => string;
+/** `path` is "" or starts with "/": adminHref("/studio", "/pages") → "/studio/pages". */
+export declare const adminHref: (base: string, path: string) => string;
+/** The message for a shell mounted outside its base — the route folder
+ *  and `admin.path` disagree (spec §4). Null inside the base, and before
+ *  mount, when the pathname is still "". */
+export declare function mountMismatch(pathname: string, base: string): string | null;

package/dist/admin-path.js

@@ -0,0 +1,32 @@
+// packages/smoodly/src/admin-path.ts
+// The admin's mount path (spec 2026-09-17): "/admin" unless the config
+// moves it. Pure and framework-free — the config, the ops and the shell
+// all read it from here.
+import { isSegment } from "./paths.js";
+export const DEFAULT_ADMIN_PATH = "/admin";
+/** `/` plus exactly one segment (spec 2026-09-17 slug guard §1): with one
+ *  segment only a ROOT slug can collide with the admin, so the guard is a
+ *  string comparison. */
+export function assertAdminPath(path) {
+    const ok = typeof path === "string" && path.startsWith("/") && isSegment(path.slice(1));
+    if (!ok) {
+        throw new Error(`smoodly: admin.path "${String(path)}" is not a valid path — use one /segment of lowercase letters, digits and single hyphens, like "/admin" or "/studio".`);
+    }
+}
+/** True when `slug` is the admin's own segment: Next serves the static
+ *  admin folder before the site catch-all, so a root page, a collection
+ *  path or a fixed slug that takes it can never be opened. */
+export const isAdminSlug = (slug, adminPath) => slug === adminPath.slice(1);
+/** What an editor reads when a root page would take the admin's segment. */
+export const adminSlugTaken = (adminPath) => `smoodly: "${adminPath}" is where the admin lives (admin.path) — pick another slug.`;
+/** `path` is "" or starts with "/": adminHref("/studio", "/pages") → "/studio/pages". */
+export const adminHref = (base, path) => `${base}${path}`;
+/** The message for a shell mounted outside its base — the route folder
+ *  and `admin.path` disagree (spec §4). Null inside the base, and before
+ *  mount, when the pathname is still "". */
+export function mountMismatch(pathname, base) {
+    if (pathname === "" || pathname === base || pathname.startsWith(`${base}/`))
+        return null;
+    const suggestion = `/${pathname.split("/").filter((s) => s !== "")[0] ?? ""}`;
+    return `The admin is open at ${pathname}, but admin.path in the Smoodly config is ${base}. Set admin: { path: "${suggestion}" } in the config, or move the route folder back.`;
+}

package/dist/config.d.ts

@@ -57,8 +57,13 @@ export type SmoodlyConfig = {
         maxSize?: number;
         accept?: string[];
     };
+    /** Where the admin is mounted (spec 2026-09-17): must match the route
+     *  folder under app/(smoodly)/. Default "/admin". */
+    admin?: {
+        path?: string;
+    };
 };
-export type ResolvedConfig = Omit<SmoodlyConfig, "styles" | "custom"> & {
+export type ResolvedConfig = Omit<SmoodlyConfig, "styles" | "custom" | "admin"> & {
     homePageSlug: string;
     /** How deep editors may nest pages in the tree. Default 1 (flat). */
     pageDepth: number;
@@ -74,6 +79,10 @@ export type ResolvedConfig = Omit<SmoodlyConfig, "styles" | "custom"> & {
         maxSize: number;
         accept: string[];
     };
+    /** The admin's mount path, always present. */
+    admin: {
+        path: string;
+    };
 };
 /** `global`: the placement node type and an admin route; `asset`: the refs
  *  target of every media edge; `media`: the admin's Media screen route. */

package/dist/config.js

@@ -1,5 +1,6 @@
 import { assertSegment, fixedPageSegments, perLocaleSegments } from "./paths.js";
 import { DEFAULT_MEDIA } from "./media.js";
+import { DEFAULT_ADMIN_PATH, assertAdminPath, isAdminSlug } from "./admin-path.js";
 import { resolveStyleValues, styleDescriptors } from "./styles.js";
 import { resolveCustom } from "./custom/index.js";
 /** `global`: the placement node type and an admin route; `asset`: the refs
@@ -55,8 +56,9 @@ function assertGlobalSections(config) {
 /** Every root-level segment a registration claims, per locale: fixed page
  *  slugs and collection paths. Two claims on one (locale, segment) are a
  *  conflict — except a fixed page sitting at a collection's segment in
- *  EVERY locale of that path, which is the collection's index page. */
-function assertRootSegments(config) {
+ *  EVERY locale of that path, which is the collection's index page. The
+ *  admin's own segment is refused outright (spec 2026-09-17 slug guard §5). */
+function assertRootSegments(config, adminPath) {
     const { default: def, supported } = config.locales;
     // Mounts claim exactly the locales their path names; fixed pages fill an
     // omitted locale from the default one, so the check must fill the same
@@ -72,6 +74,9 @@ function assertRootSegments(config) {
         }
         for (const [locale, segment] of Object.entries(pageSegments(slug))) {
             assertSegment(segment, `page "${p.schema.name}" fixed slug`);
+            if (isAdminSlug(segment, adminPath)) {
+                throw new Error(`smoodly: page "${p.schema.name}" has the fixed slug "${segment}", where the admin lives — change its slug or admin.path.`);
+            }
             const owner = owners.get(`${locale} ${segment}`);
             if (owner) {
                 throw new Error(`smoodly: page registrations "${owner}" and "${p.schema.name}" both claim the fixed slug "${segment}" (${locale}).`);
@@ -93,6 +98,9 @@ function assertRootSegments(config) {
         const segments = perLocale(c.path);
         for (const [locale, segment] of Object.entries(segments)) {
             assertSegment(segment, `collection "${c.name}" path`);
+            if (isAdminSlug(segment, adminPath)) {
+                throw new Error(`smoodly: collection "${c.name}" is mounted at "${adminPath}", where the admin lives — change its path or admin.path.`);
+            }
             const other = collectionOwners.get(`${locale} ${segment}`);
             if (other) {
                 throw new Error(`smoodly: collections "${other}" and "${c.name}" both claim the root segment "${segment}" (${locale}).`);
@@ -169,7 +177,9 @@ export function defineConfig(config) {
     assertUniqueNames(config);
     assertGlobalSections(config);
     assertToolsetElements(config);
-    assertRootSegments(config);
+    const adminPath = config.admin?.path ?? DEFAULT_ADMIN_PATH;
+    assertAdminPath(adminPath);
+    assertRootSegments(config, adminPath);
     const depth = config.pages?.tree?.depth ?? 1;
     if (!Number.isInteger(depth) || depth < 1)
         throw new Error("smoodly: pages.tree.depth must be a positive integer.");
@@ -200,6 +210,7 @@ export function defineConfig(config) {
         homePageSlug,
         pageDepth: depth,
         media,
+        admin: { path: adminPath },
         styles,
         css: config.css === true,
         custom,

package/dist/entry-store.js

@@ -19,7 +19,7 @@ import { assertDepth, assertSupportedLocale, chainOf, entryPathRows, slugOf, uns
 /** The field types whose value is an array: a scalar `where` on one is
  *  containment, and any-of on one is refused by the site layer (both
  *  adapters read the text form of the whole array, never its elements). */
-export const ARRAY_FIELD_TYPES = new Set(["checkboxes", "refList", "list"]);
+export const ARRAY_FIELD_TYPES = new Set(["checkboxes", "refList", "list", "tags"]);
 /** PostgREST's `->>`: a scalar's text, an array's or object's JSON text (Postgres
  *  spaces an object's text differently, but no scalar equals either form). */
 const textForm = (value) => (value !== null && typeof value === "object" ? JSON.stringify(value) : String(value));

package/dist/fields.d.ts

@@ -94,6 +94,9 @@ export declare const f: {
     radio: <const O extends readonly OptionInput[]>(options: O) => FieldBuilder<OptionValue<O[number]>, {}>;
     /** Several values from a list, stored as an array, shown as a checkbox list. */
     checkboxes: <const O extends readonly OptionInput[]>(options: O) => FieldBuilder<OptionValue<O[number]>[], {}>;
+    /** Short labels edited as chips, stored as a string array: trimmed, no
+     *  case-insensitive duplicates (spec 2026-09-17 §4). `.min`/`.max` count tags. */
+    tags: () => FieldBuilder<string[], {}>;
     object: <S extends Record<string, FieldBuilder<any, any>>>(shape: S & { [K in keyof S]: NotLocalized<S[K]>; }) => FieldBuilder<{ [K in keyof S]: ValueOf<S[K]>; }, {}>;
     /** A repeating item: any builder, but no list at any depth inside the item
      *  — a list in an object in a list is still a nested list on screen, and a

package/dist/fields.js

@@ -107,6 +107,9 @@ export const f = {
     radio: (options) => builder({ type: "radio", options: normalizeOptions(options) }),
     /** Several values from a list, stored as an array, shown as a checkbox list. */
     checkboxes: (options) => builder({ type: "checkboxes", options: normalizeOptions(options) }),
+    /** Short labels edited as chips, stored as a string array: trimmed, no
+     *  case-insensitive duplicates (spec 2026-09-17 §4). `.min`/`.max` count tags. */
+    tags: () => builder({ type: "tags" }),
     object: (shape) => {
         for (const [k, v] of Object.entries(shape))
             assertContainerItem("f.object", v.descriptor, k);
@@ -124,6 +127,8 @@ export const f = {
         const nested = findMatch(d, (sub) => sub.type === "list");
         if (nested !== null)
             throw new Error(`smoodly: f.list cannot hold another list (at ${describePath(nested)}) — nested lists are not supported.`);
+        if (d.type === "tags")
+            throw new Error("smoodly: f.list cannot hold f.tags() — a list of tag lists is a nested list; put the tags in an object item.");
         assertContainerItem("f.list", d);
         return builder({ type: "list", item: d });
     },

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export * from "./custom/index.ts";
 export type { Condition, ConditionOp, ConditionScope } from "./conditions.ts";
 export { defaultsOf, withDefaults } from "./field-defaults.ts";
 export { filterPageTree } from "./page-tree.ts";
+export { DEFAULT_ADMIN_PATH } from "./admin-path.ts";
 export { ASSET_COLLECTION, DEFAULT_MEDIA, MEDIA_TYPES, FULL_CROP, CENTER_HOTSPOT, parseAspect, cropAspect, clamp01, isMediaValue, collectAssetIds, applyAssets, } from "./media.ts";
 export type { Crop, Hotspot, AssetKind, ImageValue, VideoValue, FileValue, AssetMeta, AssetRecord, ResolvedImage, ResolvedVideo, ResolvedFile, } from "./media.ts";
 export { z } from "./zones.ts";

package/dist/index.js

@@ -16,6 +16,7 @@ export { DEFAULT_STYLE_VALUES, STYLE_KEYS, SPACING_NONE, resolveStyleValues, sty
 export * from "./custom/index.js";
 export { defaultsOf, withDefaults } from "./field-defaults.js";
 export { filterPageTree } from "./page-tree.js";
+export { DEFAULT_ADMIN_PATH } from "./admin-path.js";
 export { ASSET_COLLECTION, DEFAULT_MEDIA, MEDIA_TYPES, FULL_CROP, CENTER_HOTSPOT, parseAspect, cropAspect, clamp01, isMediaValue, collectAssetIds, applyAssets, } from "./media.js";
 export { z } from "./zones.js";
 export { defineConfig } from "./config.js";

package/dist/page.js

@@ -1,6 +1,6 @@
 import { describePath, findMatch } from "./fields.js";
 /** What a page field may be: a settings form, never a ref, a list or a document (spec 2026-09-10 page fields §1). */
-const PAGE_FIELD_TYPES = new Set(["text", "link", "date", "number", "boolean", "select", "radio", "checkboxes", "image", "video", "file", "object"]);
+const PAGE_FIELD_TYPES = new Set(["text", "link", "date", "number", "boolean", "select", "radio", "checkboxes", "tags", "image", "video", "file", "object"]);
 /** The descriptor at a dotted path below `d` (object subfields only — page fields hold no lists). */
 function descriptorAt(d, path) {
     let cur = d;

package/dist/supabase-entry-store.js

@@ -365,7 +365,7 @@ export class SupabaseEntryStore {
         }
         for (const [key, want] of Object.entries(options?.where ?? {})) {
             // Any-of compares the text form (`->>`). A scalar is JSONB containment;
-            // an array-valued field (checkboxes, refList, list) contains `[value]`,
+            // an array-valued field (checkboxes, refList, list, tags) contains `[value]`,
             // a scalar field `value` — the memory adapter's matchesWhere agrees.
             if (Array.isArray(want)) {
                 query = query.in(`fields->>${key}`, want.map(String));

package/dist/tags.d.ts

@@ -0,0 +1,19 @@
+/** Trimmed, inner whitespace runs collapsed to one space. */
+export declare const normalizeTag: (s: string) => string;
+/** Tags are one tag when they differ only in case. */
+export declare const sameTag: (a: string, b: string) => boolean;
+/** Commit typed or pasted text: split on commas, normalize, drop empties and
+ *  duplicates of what is already there, stop at `max`. A part that matches a
+ *  `known` tag takes its casing. `duplicate` is the existing tag the first
+ *  dropped part hit, so the widget can flash that chip. */
+export declare function addTags(current: readonly string[], input: string, opts?: {
+    max?: number;
+    known?: readonly string[];
+}): {
+    tags: string[];
+    duplicate: string | null;
+};
+/** Every tag in a set of field values (each a tag array, or anything else), sorted. Where
+ *  entries disagree on a tag's casing the most used one wins, a tie going to plain string
+ *  order — never to the order the values arrived in, which is the store's business. */
+export declare function distinctTags(values: readonly unknown[]): string[];

package/dist/tags.js

@@ -0,0 +1,50 @@
+// The rules of an f.tags() value (spec 2026-09-17 §4) as pure functions:
+// the chip widget, the validator and the suggestions op all go through
+// these, so a tag means the same thing on every side.
+/** Trimmed, inner whitespace runs collapsed to one space. */
+export const normalizeTag = (s) => s.trim().replace(/\s+/g, " ");
+const fold = (s) => s.toLocaleLowerCase();
+/** Tags are one tag when they differ only in case. */
+export const sameTag = (a, b) => fold(a) === fold(b);
+/** Commit typed or pasted text: split on commas, normalize, drop empties and
+ *  duplicates of what is already there, stop at `max`. A part that matches a
+ *  `known` tag takes its casing. `duplicate` is the existing tag the first
+ *  dropped part hit, so the widget can flash that chip. */
+export function addTags(current, input, opts = {}) {
+    const tags = [...current];
+    let duplicate = null;
+    for (const part of input.split(",")) {
+        const typed = normalizeTag(part);
+        if (typed === "")
+            continue;
+        const tag = opts.known?.find((k) => sameTag(k, typed)) ?? typed;
+        const hit = tags.find((t) => sameTag(t, tag));
+        if (hit !== undefined) {
+            duplicate ?? (duplicate = hit);
+            continue;
+        }
+        if (typeof opts.max === "number" && tags.length >= opts.max)
+            break;
+        tags.push(tag);
+    }
+    return { tags, duplicate };
+}
+/** Every tag in a set of field values (each a tag array, or anything else), sorted. Where
+ *  entries disagree on a tag's casing the most used one wins, a tie going to plain string
+ *  order — never to the order the values arrived in, which is the store's business. */
+export function distinctTags(values) {
+    const variants = new Map();
+    for (const value of values) {
+        if (!Array.isArray(value))
+            continue;
+        for (const tag of value) {
+            if (typeof tag !== "string" || tag === "")
+                continue;
+            const counts = variants.get(fold(tag)) ?? new Map();
+            counts.set(tag, (counts.get(tag) ?? 0) + 1);
+            variants.set(fold(tag), counts);
+        }
+    }
+    const pick = (counts) => [...counts].sort(([a, n], [b, m]) => m - n || (a < b ? -1 : 1))[0][0];
+    return [...variants.values()].map(pick).sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoodly",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "Open-source, code-first CMS for Next.js on Supabase: define a component once, it becomes a typed, editable building block.",
   "license": "MIT",
   "repository": {