smoodly 0.0.15 → 0.0.17

package/dist/admin/ops-impl.js

@@ -1,12 +1,17 @@
 import { entryFieldsIn, entryTitleIn } from "../entry-store.js";
 import { ASSET_COLLECTION } from "../media.js";
 import { BASE } from "./shell/base.js";
-import { affectedTargets, collectionTag, entryTag, pageTag, pagesTreeTag, sharedTag } from "../revalidate.js";
+import { affectedTargets, collectionTag, entryTag, pageTag, pagesTreeTag, globalTag } from "../revalidate.js";
 import { ensureFixedNodes, fixedNodeOf } from "./fixed-nodes.js";
-import { ensureSharedItems } from "./shared-items.js";
-import { validateFields } from "./validate.js";
+import { ensureGlobalItems } from "./global-items.js";
+import { validateCustomNode, validateFields, validateNode } from "./validate.js";
+import { CUSTOM_NODE_TYPE, customSchema } from "../custom/index.js";
+import { SETTINGS_KEY, CSS_KEY } from "../global.js";
+import { withDefaults } from "../field-defaults.js";
 import { elementSchemas } from "../richtext-walk.js";
 const ok = (data) => ({ ok: true, data });
+/** A history row without its content (spec 2026-09-13 history §6). */
+const summary = ({ id, savedAt }) => ({ id, savedAt });
 const err = (code, message, fields) => ({ ok: false, code, message, ...(fields ? { fields } : {}) });
 /** Own-property, non-array plain object — same shape guard the tree checks
  * below and `runAdminOp`'s envelope check both lean on. */
@@ -62,6 +67,8 @@ const classify = (e) => {
         return err("blocked", message);
     if (message.includes("cannot publish"))
         return err("blocked", message);
+    if (message.includes("nothing published"))
+        return err("blocked", message);
     if (message.includes("already taken"))
         return err("conflict", message);
     if (message.includes("already has a template"))
@@ -88,13 +95,15 @@ const classify = (e) => {
 export function createAdminOps(deps) {
     const { config, pages, entries, effects } = deps;
     const href = deps.href ?? ((path) => path);
+    const by = deps.actor?.email ?? undefined;
     const collectionFields = (name) => config.registry.collections?.find((c) => c.name === name)?.fields ?? null;
     // Element nodes inside richtext validate against these (spec 2026-09-08 block nodes §2).
-    const elementDescs = elementSchemas((config.registry.elements ?? []).map((e) => ({ name: e.schema.name, fields: e.schema.fields ?? {}, styles: e.schema.styles })));
-    const sectionFields = (type) => config.registry.sections?.find((s) => s.schema.name === type)?.schema;
-    const sharedItem = (name) => config.registry.shared?.find((s) => s.name === name) ?? null;
+    const elementDescs = elementSchemas((config.registry.elements ?? []).map((e) => ({ name: e.schema.name, fields: e.schema.fields ?? {}, settings: e.schema.settings })));
+    // The custom section (spec 2026-09-14 §6) validates like a section, over its own schema.
+    const sectionFields = (type) => (type === CUSTOM_NODE_TYPE ? customSchema(config.custom.toolset) : config.registry.sections?.find((s) => s.schema.name === type)?.schema);
+    const globalItem = (name) => config.registry.globals?.find((s) => s.name === name) ?? null;
     /** One row per registration; null when materialization could not create it. */
-    const sharedRecord = async (name) => (await entries.list(name))[0] ?? null;
+    const globalRecord = async (name) => (await entries.list(name))[0] ?? null;
     const fanOut = async (entryId) => {
         if (!effects?.revalidate)
             return;
@@ -103,28 +112,28 @@ export function createAdminOps(deps) {
             effects.revalidate(entryTag(id));
         for (const id of pageIds)
             effects.revalidate(pageTag(id));
-        // A shared item's row is an entry like any other: when the item
+        // A global item's row is an entry like any other: when the item
         // itself changes OR when something it REFERENCES does, the unit
-        // `getSmoodlyShared` caches under `shared:<name>` is stale too — and
+        // `getSmoodlyGlobal` caches under `global:<name>` is stale too — and
         // that unit is a layout, on every page. `affectedTargets` returns row
         // ids, so resolve name → row id here. Once per fan-out, not memoized
         // per ops instance: a row can be materialized between two calls, and
         // an entry write is rare enough that one `entries.list` per
         // registration beats reasoning about a stale cache. Last, so the
         // existing entry-then-page order is untouched.
-        const registered = config.registry.shared ?? [];
+        const registered = config.registry.globals ?? [];
         if (registered.length === 0)
             return;
         const touched = new Set(entryIds);
         for (const item of registered) {
             const row = (await entries.list(item.name))[0];
             if (row && touched.has(row.id))
-                effects.revalidate(sharedTag(item.name));
+                effects.revalidate(globalTag(item.name));
         }
     };
     /** An asset's metadata (alt, title, caption, credit) is read wherever media
      *  resolves (spec 2026-09-08 §9): the entry and page units that reference the
-     *  asset, directly or through an entry, the shared items among those rows,
+     *  asset, directly or through an entry, the global items among those rows,
      *  and the list units of every referencing entry's collection. The walk is
      *  the entry fan-out's, seeded with the asset's id — which is no entry, so
      *  it gets no tag of its own. */
@@ -138,10 +147,10 @@ export function createAdminOps(deps) {
         for (const id of pageIds)
             effects.revalidate(pageTag(id));
         const touched = new Set(users);
-        for (const item of config.registry.shared ?? []) {
+        for (const item of config.registry.globals ?? []) {
             const row = (await entries.list(item.name))[0];
             if (row && touched.has(row.id))
-                effects.revalidate(sharedTag(item.name));
+                effects.revalidate(globalTag(item.name));
         }
         for (const c of config.registry.collections ?? []) {
             for (const id of users) {
@@ -200,9 +209,9 @@ export function createAdminOps(deps) {
                 return { title: sourceId, href: null };
             return { title: record.locales[def]?.title ?? Object.values(record.locales)[0]?.title ?? sourceId, href: `${BASE}/pages/${sourceId}` };
         }
-        for (const item of config.registry.shared ?? []) {
+        for (const item of config.registry.globals ?? []) {
             if (await entries.get(item.name, sourceId))
-                return { title: item.title, href: `${BASE}/shared/${encodeURIComponent(item.name)}` };
+                return { title: item.title, href: `${BASE}/globals/${encodeURIComponent(item.name)}` };
         }
         for (const c of config.registry.collections ?? []) {
             const record = await entries.get(c.name, sourceId);
@@ -281,7 +290,7 @@ export function createAdminOps(deps) {
                 const created = await pages.createPage({
                     locale: input.locale, slug: input.slug, template: input.template, parentId: input.parentId,
                     ...(input.title !== undefined ? { title: input.title } : {}),
-                });
+                }, by);
                 expireTree();
                 return ok(created);
             }),
@@ -293,7 +302,7 @@ export function createAdminOps(deps) {
                     return err("validation", "smoodly: malformed page tree.");
                 if (!(await pages.getPage(id)))
                     return err("not_found", `smoodly: no page "${id}".`);
-                return ok({ versionId: (await pages.saveDraft(id, locale, tree)).id });
+                return ok({ versionId: (await pages.saveDraft(id, locale, tree, by)).id });
             }),
             publish: (id, locale) => guard(async () => {
                 const unsupported = supportedLocale(locale);
@@ -317,7 +326,11 @@ export function createAdminOps(deps) {
                         const schema = sectionFields(node.type);
                         if (!schema?.fields)
                             continue;
-                        for (const fe of validateFields(node.fields ?? {}, schema.fields, elementDescs)) {
+                        // Fields, settings (prefixed) and the css snippet (spec 2026-09-14 §3, §4); a custom section adds its row structure (§6).
+                        const errors = node.type === CUSTOM_NODE_TYPE
+                            ? validateCustomNode(node, schema.fields, elementDescs)
+                            : validateNode(node, { fields: schema.fields, settings: schema.settings }, elementDescs);
+                        for (const fe of errors) {
                             fieldErrors.push({ field: `${node.id}.${fe.field}`, message: fe.message });
                         }
                     }
@@ -330,12 +343,75 @@ export function createAdminOps(deps) {
                 if (fieldErrors.length > 0) {
                     return err("validation", `smoodly: cannot publish "${row.slug}" — fix the listed fields first.`, fieldErrors);
                 }
-                const published = await pages.publish(id, locale);
+                const published = await pages.publish(id, locale, by);
                 // The parent's cached unit lists its published children.
                 expirePages([published.id, published.parentId]);
                 expireTree();
                 return ok(published);
             }),
+            unpublish: (id, locale) => guard(async () => {
+                const unsupported = supportedLocale(locale);
+                if (unsupported)
+                    return unsupported;
+                const record = await pages.getPage(id);
+                if (!record)
+                    return err("not_found", `smoodly: no page "${id}".`);
+                if (!record.locales[locale])
+                    return err("not_found", `smoodly: page "${id}" does not exist in locale "${locale}".`);
+                if (isHomeNode(record))
+                    return err("blocked", `smoodly: "${nameOf(record)}" is the site root — it cannot be unpublished.`);
+                if (fixedNodeOf(record, config))
+                    return owned(record, "it stays published");
+                const off = await pages.unpublish(id, locale, by);
+                // The parent's cached unit lists its published children; the tree listing shows status.
+                expirePages([off.id, off.parentId]);
+                expireTree();
+                return ok(off);
+            }),
+            discardDraft: (id, locale) => guard(async () => {
+                const unsupported = supportedLocale(locale);
+                if (unsupported)
+                    return unsupported;
+                const record = await pages.getPage(id);
+                if (!record)
+                    return err("not_found", `smoodly: no page "${id}".`);
+                const row = record.locales[locale];
+                if (!row)
+                    return err("not_found", `smoodly: page "${id}" does not exist in locale "${locale}".`);
+                if (!row.publishedVersionId) {
+                    return err("blocked", `smoodly: "${nameOf(record)}" has nothing published in ${locale} — there is no version to restore.`);
+                }
+                const restored = await pages.discardDraft(id, locale, by);
+                expirePages([restored.id]); // the draft-mode render of this page changed
+                return ok(restored);
+            }),
+            listVersions: (id, locale) => guard(async () => {
+                const unsupported = supportedLocale(locale);
+                if (unsupported)
+                    return unsupported;
+                if (!(await pages.getPage(id)))
+                    return err("not_found", `smoodly: no page "${id}".`);
+                return ok((await pages.listVersions(id, locale)).map(summary));
+            }),
+            restore: (id, locale, versionId) => guard(async () => {
+                const unsupported = supportedLocale(locale);
+                if (unsupported)
+                    return unsupported;
+                const record = await pages.getPage(id);
+                if (!record)
+                    return err("not_found", `smoodly: no page "${id}".`);
+                if (!record.locales[locale])
+                    return err("not_found", `smoodly: page "${id}" does not exist in locale "${locale}".`);
+                if (record.template === null)
+                    return err("blocked", `smoodly: "${nameOf(record)}" is a folder — it has no versions.`);
+                const version = typeof versionId === "string" ? await pages.getVersion(versionId) : null;
+                if (!version || version.pageId !== id || version.locale !== locale) {
+                    return err("not_found", `smoodly: no version "${String(versionId)}" of this page in ${locale}.`);
+                }
+                const restored = await pages.restore(id, locale, versionId, by);
+                expirePages([restored.id]); // the draft-mode render of this page changed
+                return ok(restored);
+            }),
             delete: (id) => guard(async () => {
                 const record = await pages.getPage(id);
                 if (!record)
@@ -364,7 +440,7 @@ export function createAdminOps(deps) {
                 const unsupported = supportedLocale(patch.locale);
                 if (unsupported)
                     return unsupported;
-                const renamed = await pages.rename(id, patch);
+                const renamed = await pages.rename(id, patch, by);
                 // Every descendant's path changed with this segment; the parent
                 // lists this node's title and path.
                 expirePages([...(await subtreeIds(id)), record.parentId]);
@@ -408,7 +484,7 @@ export function createAdminOps(deps) {
                 if (registration.schema.slug !== undefined) {
                     return err("validation", `smoodly: page template "${template}" is fixed — Smoodly creates that page for you.`);
                 }
-                const withTemplate = await pages.setTemplate(id, template);
+                const withTemplate = await pages.setTemplate(id, template, by);
                 expireTree();
                 return ok(withTemplate);
             }),
@@ -419,7 +495,7 @@ export function createAdminOps(deps) {
                 if (!(await pages.getPage(id)))
                     return err("not_found", `smoodly: no page "${id}".`);
                 // A new locale is a draft: nothing public changes but the tree listing (spec 2026-09-11 §2).
-                const added = await pages.addLocale(id, locale, { from: options.from });
+                const added = await pages.addLocale(id, locale, { from: options.from }, by);
                 expireTree();
                 return ok(added);
             }),
@@ -455,7 +531,9 @@ export function createAdminOps(deps) {
                 const parentLocales = record.parentId === null
                     ? config.locales.supported
                     : Object.keys((await entries.get(collection, record.parentId))?.locales ?? {});
-                return ok({ record, locale, fields, parentLocales });
+                const paths = await entries.pathsOf(collection, id);
+                const urls = Object.fromEntries(Object.entries(paths).map(([l, p]) => [l, href(p, l)]));
+                return ok({ record, locale, fields, parentLocales, urls });
             }),
             create: (collection, input) => guard(async () => {
                 const unsupported = supportedLocale(input.locale);
@@ -464,10 +542,7 @@ export function createAdminOps(deps) {
                 const descriptors = collectionFields(collection);
                 if (!descriptors)
                     return err("not_found", `smoodly: no collection named "${collection}".`);
-                const fieldErrors = validateFields(input.fields, descriptors, elementDescs);
-                if (fieldErrors.length > 0)
-                    return err("validation", "Some fields need attention.", fieldErrors);
-                const created = await entries.create(collection, input.fields, { locale: input.locale, parentId: input.parentId ?? null });
+                const created = await entries.create(collection, withDefaults(input.fields, descriptors), { locale: input.locale, parentId: input.parentId ?? null }, by);
                 expireCollection(collection);
                 return ok(created);
             }),
@@ -478,10 +553,7 @@ export function createAdminOps(deps) {
                 const descriptors = collectionFields(collection);
                 if (!descriptors)
                     return err("not_found", `smoodly: no collection named "${collection}".`);
-                const fieldErrors = validateFields(fields, descriptors, elementDescs);
-                if (fieldErrors.length > 0)
-                    return err("validation", "Some fields need attention.", fieldErrors);
-                const entry = await entries.update(collection, id, locale, fields);
+                const entry = await entries.update(collection, id, locale, fields, by);
                 await fanOut(id);
                 expireCollection(collection);
                 return ok(entry);
@@ -490,11 +562,62 @@ export function createAdminOps(deps) {
                 const unsupported = supportedLocale(locale);
                 if (unsupported)
                     return unsupported;
-                const entry = await entries.setStatus(collection, id, locale, status);
+                if (status === "published") {
+                    // A draft may be incomplete; what goes live may not (spec 2026-09-14 §2).
+                    const descriptors = collectionFields(collection);
+                    if (!descriptors)
+                        return err("not_found", `smoodly: no collection named "${collection}".`);
+                    const record = await entries.get(collection, id);
+                    if (!record)
+                        return err("not_found", `smoodly: no entry "${id}" in "${collection}".`);
+                    if (!record.locales[locale])
+                        return err("not_found", `smoodly: entry "${id}" does not exist in locale "${locale}".`);
+                    const fieldErrors = validateFields(entryFieldsIn(record, locale), descriptors, elementDescs);
+                    if (fieldErrors.length > 0)
+                        return err("validation", "Some fields need attention.", fieldErrors);
+                }
+                const entry = await entries.setStatus(collection, id, locale, status, by);
                 await fanOut(id);
                 expireCollection(collection);
                 return ok(entry);
             }),
+            discardDraft: (collection, id, locale) => guard(async () => {
+                const unsupported = supportedLocale(locale);
+                if (unsupported)
+                    return unsupported;
+                const restored = await entries.discardDraft(collection, id, locale, by);
+                await fanOut(id);
+                expireCollection(collection);
+                return ok(restored);
+            }),
+            listVersions: (collection, id, locale) => guard(async () => {
+                const unsupported = supportedLocale(locale);
+                if (unsupported)
+                    return unsupported;
+                if (!(await entries.get(collection, id)))
+                    return err("not_found", `smoodly: no entry "${id}" in "${collection}".`);
+                return ok((await entries.listVersions(collection, id, locale)).map(summary));
+            }),
+            getVersion: (collection, id, versionId) => guard(async () => {
+                const version = typeof versionId === "string" ? await entries.getVersion(collection, versionId) : null;
+                if (!version || version.entryId !== id) {
+                    return err("not_found", `smoodly: no version "${String(versionId)}" of entry "${id}" in "${collection}".`);
+                }
+                return ok({ ...summary(version), fields: version.fields });
+            }),
+            restore: (collection, id, locale, versionId) => guard(async () => {
+                const unsupported = supportedLocale(locale);
+                if (unsupported)
+                    return unsupported;
+                const version = typeof versionId === "string" ? await entries.getVersion(collection, versionId) : null;
+                if (!version || version.entryId !== id || version.locale !== locale) {
+                    return err("not_found", `smoodly: no version "${String(versionId)}" of entry "${id}" in "${collection}", locale ${locale}.`);
+                }
+                const restored = await entries.restore(collection, id, locale, versionId, by);
+                await fanOut(id);
+                expireCollection(collection);
+                return ok(restored);
+            }),
             // The tag expires only after the delete succeeded; a blocked delete expires nothing.
             delete: (collection, id) => guard(async () => (await entries.delete(collection, id), await fanOut(id), expireCollection(collection), ok(null))),
             move: (collection, id, to) => guard(async () => {
@@ -512,7 +635,7 @@ export function createAdminOps(deps) {
                 const unsupported = supportedLocale(locale);
                 if (unsupported)
                     return unsupported;
-                const added = await entries.addLocale(collection, id, locale, { from: options.from });
+                const added = await entries.addLocale(collection, id, locale, { from: options.from }, by);
                 expireCollection(collection);
                 return ok(added);
             }),
@@ -526,22 +649,22 @@ export function createAdminOps(deps) {
                 return ok(entry);
             }),
         },
-        shared: {
+        globals: {
             list: () => guard(async () => {
-                const records = await ensureSharedItems(entries, config);
-                return ok((config.registry.shared ?? []).flatMap((s) => (records[s.name] ? [{ name: s.name, record: records[s.name] }] : [])));
+                const records = await ensureGlobalItems(entries, config);
+                return ok((config.registry.globals ?? []).flatMap((s) => (records[s.name] ? [{ name: s.name, record: records[s.name] }] : [])));
             }),
             get: (name, locale) => guard(async () => {
                 const unsupported = supportedLocale(locale);
                 if (unsupported)
                     return unsupported;
-                const item = sharedItem(name);
+                const item = globalItem(name);
                 if (!item)
-                    return err("not_found", `smoodly: no shared item named "${name}".`);
-                await ensureSharedItems(entries, config);
-                const record = await sharedRecord(name);
+                    return err("not_found", `smoodly: no global item named "${name}".`);
+                await ensureGlobalItems(entries, config);
+                const record = await globalRecord(name);
                 if (!record?.locales[locale])
-                    return err("not_found", `smoodly: shared item "${name}" does not exist in locale "${locale}".`);
+                    return err("not_found", `smoodly: global item "${name}" does not exist in locale "${locale}".`);
                 const usage = await entries.referencesTo(name, record.id);
                 return ok({ name, record, locale, fields: entryFieldsIn(record, locale), usage });
             }),
@@ -549,17 +672,14 @@ export function createAdminOps(deps) {
                 const unsupported = supportedLocale(locale);
                 if (unsupported)
                     return unsupported;
-                const item = sharedItem(name);
+                const item = globalItem(name);
                 if (!item)
-                    return err("not_found", `smoodly: no shared item named "${name}".`);
-                const fieldErrors = validateFields(fields, item.fields, elementDescs);
-                if (fieldErrors.length > 0)
-                    return err("validation", "Some fields need attention.", fieldErrors);
-                const record = await sharedRecord(name);
+                    return err("not_found", `smoodly: no global item named "${name}".`);
+                const record = await globalRecord(name);
                 if (!record)
-                    return err("not_found", `smoodly: shared item "${name}" is not materialized — open Shared content first.`);
-                const saved = await entries.update(name, record.id, locale, fields);
-                // fanOut expires `shared:<name>` itself — this row IS the item's.
+                    return err("not_found", `smoodly: global item "${name}" is not materialized — open Globals first.`);
+                const saved = await entries.update(name, record.id, locale, fields, by);
+                // fanOut expires `global:<name>` itself — this row IS the item's.
                 await fanOut(record.id);
                 return ok(saved);
             }),
@@ -567,16 +687,82 @@ export function createAdminOps(deps) {
                 const unsupported = supportedLocale(locale);
                 if (unsupported)
                     return unsupported;
-                if (!sharedItem(name))
-                    return err("not_found", `smoodly: no shared item named "${name}".`);
-                const record = await sharedRecord(name);
+                const item = globalItem(name);
+                if (!item)
+                    return err("not_found", `smoodly: no global item named "${name}".`);
+                const record = await globalRecord(name);
                 if (!record)
-                    return err("not_found", `smoodly: shared item "${name}" is not materialized — open Shared content first.`);
-                const changed = await entries.setStatus(name, record.id, locale, status);
+                    return err("not_found", `smoodly: global item "${name}" is not materialized — open Globals first.`);
+                if (status === "published") {
+                    // A draft may be incomplete; what goes live may not (spec 2026-09-14 §2).
+                    if (!record.locales[locale])
+                        return err("not_found", `smoodly: global item "${name}" does not exist in locale "${locale}".`);
+                    // A visual item validates like a tree node: its fields, its section's settings under `$settings`
+                    // (prefixed `settings.`), its `$css` (spec 2026-09-14 §3, §4).
+                    const { [SETTINGS_KEY]: settings, [CSS_KEY]: css, ...fields } = entryFieldsIn(record, locale);
+                    const settingsDescs = item.section !== undefined ? sectionFields(item.section)?.settings : undefined;
+                    const fieldErrors = validateNode({ fields, settings: settings !== null && typeof settings === "object" ? settings : {}, css }, { fields: item.fields, settings: settingsDescs }, elementDescs);
+                    if (fieldErrors.length > 0)
+                        return err("validation", "Some fields need attention.", fieldErrors);
+                }
+                const changed = await entries.setStatus(name, record.id, locale, status, by);
                 // see save: the fan-out carries the item's own tag.
                 await fanOut(record.id);
                 return ok(changed);
             }),
+            discardDraft: (name, locale) => guard(async () => {
+                const unsupported = supportedLocale(locale);
+                if (unsupported)
+                    return unsupported;
+                if (!globalItem(name))
+                    return err("not_found", `smoodly: no global item named "${name}".`);
+                const record = await globalRecord(name);
+                if (!record)
+                    return err("not_found", `smoodly: global item "${name}" is not materialized — open Globals first.`);
+                const restored = await entries.discardDraft(name, record.id, locale, by);
+                await fanOut(record.id);
+                return ok(restored);
+            }),
+            listVersions: (name, locale) => guard(async () => {
+                const unsupported = supportedLocale(locale);
+                if (unsupported)
+                    return unsupported;
+                if (!globalItem(name))
+                    return err("not_found", `smoodly: no global item named "${name}".`);
+                const record = await globalRecord(name);
+                if (!record)
+                    return err("not_found", `smoodly: global item "${name}" is not materialized — open Globals first.`);
+                return ok((await entries.listVersions(name, record.id, locale)).map(summary));
+            }),
+            getVersion: (name, versionId) => guard(async () => {
+                if (!globalItem(name))
+                    return err("not_found", `smoodly: no global item named "${name}".`);
+                const record = await globalRecord(name);
+                if (!record)
+                    return err("not_found", `smoodly: global item "${name}" is not materialized — open Globals first.`);
+                const version = typeof versionId === "string" ? await entries.getVersion(name, versionId) : null;
+                if (!version || version.entryId !== record.id) {
+                    return err("not_found", `smoodly: no version "${String(versionId)}" of global item "${name}".`);
+                }
+                return ok({ ...summary(version), fields: version.fields });
+            }),
+            restore: (name, locale, versionId) => guard(async () => {
+                const unsupported = supportedLocale(locale);
+                if (unsupported)
+                    return unsupported;
+                if (!globalItem(name))
+                    return err("not_found", `smoodly: no global item named "${name}".`);
+                const record = await globalRecord(name);
+                if (!record)
+                    return err("not_found", `smoodly: global item "${name}" is not materialized — open Globals first.`);
+                const version = typeof versionId === "string" ? await entries.getVersion(name, versionId) : null;
+                if (!version || version.entryId !== record.id || version.locale !== locale) {
+                    return err("not_found", `smoodly: no version "${String(versionId)}" of global item "${name}" in ${locale}.`);
+                }
+                const restored = await entries.restore(name, record.id, locale, versionId, by);
+                await fanOut(record.id);
+                return ok(restored);
+            }),
         },
         assets: {
             list: (query) => guard(async () => (assets ? ok(await assets.list(query)) : noMedia())),

package/dist/admin/ops.d.ts

@@ -55,23 +55,34 @@ export type EntryGetResult = {
     locale: string;
     /** That locale's merged draft fields; null when the entry has no row in `locale`. */
     fields: Record<string, unknown> | null;
+    /** locale → site URL (`href` applied server-side) for the locales the entry has a path in; empty for a collection without a path. */
+    urls: Record<string, string>;
     /** The locales the PARENT exists in (every supported locale for a root) — the form disables the rest with a reason. */
     parentLocales: string[];
 };
-export type SharedListItem = {
+export type GlobalListItem = {
     name: string;
     record: EntryRecord;
 };
-export type SharedGetResult = {
+export type GlobalGetResult = {
     name: string;
     /** The node with ALL its locale rows (every supported one, by construction). */
     record: EntryRecord;
     locale: string;
-    /** That locale's merged draft fields — a visual item's styles under `$styles`. */
+    /** That locale's merged draft fields — a visual item's settings under `$settings`. */
     fields: Record<string, unknown>;
     /** Who links it: "used on N pages". */
     usage: EntryUsage[];
 };
+/** A history row: the version id and when its content last changed (spec 2026-09-13 history §5). */
+export type VersionSummary = {
+    id: string;
+    savedAt: number;
+};
+/** A stored entry snapshot for the disabled form. */
+export type EntryVersionResult = VersionSummary & {
+    fields: Record<string, unknown>;
+};
 /** One place an asset is used: the source row, the field, a label and an admin link. */
 export type AssetUsageItem = {
     sourceKind: string;
@@ -91,6 +102,10 @@ export type AdminOps = {
             versionId: string;
         }>>;
         publish(id: string, locale: string): Promise<OpResult<PageRecord>>;
+        /** Takes the locale off the site; status draft, pointers kept. Never the site root or a fixed node (spec 2026-09-13 publish flow §5). */
+        unpublish(id: string, locale: string): Promise<OpResult<PageRecord>>;
+        /** The draft back to the published version (§4); `blocked` when nothing is published in the locale. */
+        discardDraft(id: string, locale: string): Promise<OpResult<PageRecord>>;
         delete(id: string): Promise<OpResult<null>>;
         rename(id: string, patch: {
             locale: string;
@@ -109,6 +124,10 @@ export type AdminOps = {
         }): Promise<OpResult<PageRecord>>;
         /** Deletes the locale's row, versions and paths. Never on fixed nodes or the site root. */
         removeLocale(id: string, locale: string): Promise<OpResult<PageRecord>>;
+        /** The locale's versions newest first, without their trees. */
+        listVersions(id: string, locale: string): Promise<OpResult<VersionSummary[]>>;
+        /** The version's tree becomes the draft (spec 2026-09-13 history §6); `not_found` for a version of another page or locale, `blocked` on a folder. */
+        restore(id: string, locale: string, versionId: string): Promise<OpResult<PageRecord>>;
     };
     entries: {
         list(collection: string): Promise<OpResult<EntryRecord[]>>;
@@ -117,6 +136,8 @@ export type AdminOps = {
         create(collection: string, input: EntryCreateInput): Promise<OpResult<EntryRecord>>;
         save(collection: string, id: string, locale: string, fields: Record<string, unknown>): Promise<OpResult<EntryRecord>>;
         setStatus(collection: string, id: string, locale: string, status: "draft" | "published"): Promise<OpResult<EntryRecord>>;
+        /** The live row back to the published snapshot (§4); `blocked` when the locale has no published version. */
+        discardDraft(collection: string, id: string, locale: string): Promise<OpResult<EntryRecord>>;
         delete(collection: string, id: string): Promise<OpResult<null>>;
         move(collection: string, id: string, to: {
             parentId: string | null;
@@ -128,13 +149,24 @@ export type AdminOps = {
         }): Promise<OpResult<EntryRecord>>;
         /** Deletes the locale's row, versions and paths; fans out like a save. */
         removeLocale(collection: string, id: string, locale: string): Promise<OpResult<EntryRecord>>;
+        /** Newest first; empty for a collection without `versions`. */
+        listVersions(collection: string, id: string, locale: string): Promise<OpResult<VersionSummary[]>>;
+        /** One snapshot's fields; `not_found` unless it belongs to `id`. */
+        getVersion(collection: string, id: string, versionId: string): Promise<OpResult<EntryVersionResult>>;
+        /** The snapshot becomes the draft (§6); `not_found` for a foreign version. Fans out like a save. */
+        restore(collection: string, id: string, locale: string, versionId: string): Promise<OpResult<EntryRecord>>;
     };
-    shared: {
+    globals: {
         /** Materializes every registered item in every supported locale, then lists them in registry order. */
-        list(): Promise<OpResult<SharedListItem[]>>;
-        get(name: string, locale: string): Promise<OpResult<SharedGetResult>>;
+        list(): Promise<OpResult<GlobalListItem[]>>;
+        get(name: string, locale: string): Promise<OpResult<GlobalGetResult>>;
         save(name: string, locale: string, fields: Record<string, unknown>): Promise<OpResult<EntryRecord>>;
         setStatus(name: string, locale: string, status: "draft" | "published"): Promise<OpResult<EntryRecord>>;
+        /** The item's live row back to its published snapshot (§4); `blocked` before the first publish. */
+        discardDraft(name: string, locale: string): Promise<OpResult<EntryRecord>>;
+        listVersions(name: string, locale: string): Promise<OpResult<VersionSummary[]>>;
+        getVersion(name: string, versionId: string): Promise<OpResult<EntryVersionResult>>;
+        restore(name: string, locale: string, versionId: string): Promise<OpResult<EntryRecord>>;
     };
     assets: {
         /** Ready assets, newest first, paged by cursor; `kind` and `search` filter. */