smoodly 0.0.7 → 0.0.9

package/dist/config.js

@@ -1,17 +1,50 @@
 import { assertSegment, fixedPageSegments, perLocaleSegments } from "./paths.js";
+const RESERVED_NAME = "shared"; // the placement node type and the admin route
 function assertUniqueNames(config) {
     const seen = new Set();
+    const sectionNameList = (config.registry.sections ?? []).map((s) => s.schema.name);
+    const sectionNames = new Set(sectionNameList);
     const all = [
-        ...(config.registry.sections ?? []).map((s) => s.schema.name),
+        ...sectionNameList,
         ...(config.registry.elements ?? []).map((e) => e.schema.name),
         ...(config.registry.collections ?? []).map((c) => c.name),
         ...(config.registry.pages ?? []).filter((p) => p.schema.kind !== "entryPage").map((p) => p.schema.name),
     ];
     for (const name of all) {
+        if (name === RESERVED_NAME)
+            throw new Error(`smoodly: "${RESERVED_NAME}" is a reserved name.`);
         if (seen.has(name))
             throw new Error(`smoodly: duplicate registered name "${name}".`);
         seen.add(name);
     }
+    // Shared items get their own pass, after every other kind is settled: a
+    // shared item's name must be unique among shared items, and must not
+    // collide with any collection/element/page/section name above — EXCEPT a
+    // visual item may reuse the name of the registered section it renders
+    // (spec 2026-09-07 §2's example pairs a "footer" section with a "footer"
+    // item). That exemption is narrow: it only excuses a match against the
+    // item's own, actually-registered section — never against a collection,
+    // element, or page that happens to share the string, and never against a
+    // second shared item of the same name.
+    const sharedSeen = new Set();
+    for (const item of config.registry.shared ?? []) {
+        const ownSection = item.name === item.section && sectionNames.has(item.name);
+        if (item.name === RESERVED_NAME)
+            throw new Error(`smoodly: "${RESERVED_NAME}" is a reserved name.`);
+        if (sharedSeen.has(item.name) || (seen.has(item.name) && !ownSection)) {
+            throw new Error(`smoodly: duplicate registered name "${item.name}".`);
+        }
+        sharedSeen.add(item.name);
+    }
+}
+/** A visual item renders through a registered section. */
+function assertSharedSections(config) {
+    const sections = new Set((config.registry.sections ?? []).map((s) => s.schema.name));
+    for (const item of config.registry.shared ?? []) {
+        if (item.section !== undefined && !sections.has(item.section)) {
+            throw new Error(`smoodly: shared item "${item.name}" renders section "${item.section}", which is not registered.`);
+        }
+    }
 }
 /** Every root-level segment a registration claims, per locale: fixed page
  *  slugs and collection paths. Two claims on one (locale, segment) are a
@@ -91,6 +124,7 @@ function assertLocales(config) {
 export function defineConfig(config) {
     assertLocales(config);
     assertUniqueNames(config);
+    assertSharedSections(config);
     assertRootSegments(config);
     const depth = config.pages?.tree?.depth ?? 1;
     if (!Number.isInteger(depth) || depth < 1)

package/dist/entry-store.d.ts

@@ -1,4 +1,5 @@
 import type { CollectionSchema, EntryOrder } from "./collections.ts";
+import type { SharedSchema } from "./shared.ts";
 import { type RefEdge } from "./refs.ts";
 import { MemoryRefIndex } from "./ref-index.ts";
 import { type PathIndex } from "./path-index.ts";
@@ -61,6 +62,7 @@ export type AddEntryLocaleOptions = {
 export type EntryStoreOptions = {
     paths?: PathIndex;
     locales?: LocaleSet;
+    shared?: SharedSchema[];
 };
 export interface EntryStore {
     /** Creates the node and ONE locale row from the merged `fields`: shared
@@ -118,6 +120,8 @@ export interface EntryStore {
     pathsOf(collection: string, id: string): Promise<Record<string, string>>;
 }
 export declare function schemaOf(collections: CollectionSchema<any>[], name: string): CollectionSchema<any>;
+/** A shared item is a collection with exactly one entry (spec 2026-09-07). */
+export declare const isSharedSchema: (schema: CollectionSchema<any>) => boolean;
 export declare const DEFAULT_ENTRY_LOCALES: LocaleSet;
 export declare const entryErrors: {
     notFound: (collection: string, id: string) => Error;
@@ -135,6 +139,10 @@ export declare const entryErrors: {
     lastLocale: (id: string) => Error;
     localeInUse: (locale: string, titles: string[]) => Error;
     moveLocales: (locale: string) => Error;
+    singleton: (name: string) => Error;
+    owned: (name: string, verb: string) => Error;
+    noSlug: (name: string) => Error;
+    everyLocale: (name: string) => Error;
 };
 /** The keys a locale row owns: every field with .localized(), except
  *  `slug`, which is the row's own column (a segment is an address, per
@@ -174,7 +182,6 @@ export declare function entryTitleIn(record: EntryRecord, locale: string, schema
  */
 export declare function compareEntries(order: EntryOrder, seq: (e: EntryRecord) => number): (a: EntryRecord, b: EntryRecord) => number;
 export declare class MemoryEntryStore implements EntryStore {
-    private collections;
     private refs;
     private entries;
     private versions;
@@ -184,6 +191,7 @@ export declare class MemoryEntryStore implements EntryStore {
     private order;
     private paths;
     private locales;
+    private schemas;
     constructor(collections: CollectionSchema<any>[], refs?: MemoryRefIndex, options?: EntryStoreOptions);
     private schema;
     private row;

package/dist/entry-store.js

@@ -13,6 +13,8 @@ import { collectionDepth, collectionOrder } from "./collections.js";
 import { collectEntryRefs } from "./refs.js";
 import { MemoryRefIndex } from "./ref-index.js";
 import { MemoryPathIndex } from "./path-index.js";
+import { sharedEntryId } from "./shared-id.js";
+import { DEFAULT_SPACE_ID } from "./sql-space.js";
 import { assertDepth, assertSupportedLocale, chainOf, entryPathRows, slugOf, unsupportedLocale, } from "./paths.js";
 export function schemaOf(collections, name) {
     const schema = collections.find((c) => c.name === name);
@@ -20,6 +22,8 @@ export function schemaOf(collections, name) {
         throw new Error(`smoodly: no collection named "${name}".`);
     return schema;
 }
+/** A shared item is a collection with exactly one entry (spec 2026-09-07). */
+export const isSharedSchema = (schema) => schema.kind === "shared";
 let counter = 0;
 const uid = (prefix) => `${prefix}-${++counter}-${Date.now().toString(36)}`;
 export const DEFAULT_ENTRY_LOCALES = { default: "en", supported: ["en"] };
@@ -39,6 +43,11 @@ export const entryErrors = {
     lastLocale: (id) => new Error(`smoodly: entry "${id}" must exist in at least one locale — delete the entry instead.`),
     localeInUse: (locale, titles) => new Error(`smoodly: child entries still exist in locale "${locale}" — remove it from ${titles.map((t) => `"${t}"`).join(", ")} first.`),
     moveLocales: (locale) => new Error(`smoodly: the destination parent does not exist in locale "${locale}" — the entry cannot move under it.`),
+    // Shared items (spec 2026-09-07 §3): one row, no URL, every locale, code-owned.
+    singleton: (name) => new Error(`smoodly: shared item "${name}" already exists — it is a singleton.`),
+    owned: (name, verb) => new Error(`smoodly: shared item "${name}" is owned by code — ${verb}.`),
+    noSlug: (name) => new Error(`smoodly: shared item "${name}" has no URL — it cannot take a slug.`),
+    everyLocale: (name) => new Error(`smoodly: shared item "${name}" exists in every locale — it cannot be removed from one.`),
 };
 /** The keys a locale row owns: every field with .localized(), except
  *  `slug`, which is the row's own column (a segment is an address, per
@@ -128,7 +137,6 @@ export class MemoryEntryStore {
     constructor(collections, 
     // pass the SAME index to MemoryPageStore so cross-kind questions work
     refs = new MemoryRefIndex(), options = {}) {
-        this.collections = collections;
         this.refs = refs;
         this.entries = new Map();
         this.versions = new Map();
@@ -139,9 +147,10 @@ export class MemoryEntryStore {
         this.byId = (id) => this.entries.get(id);
         this.paths = options.paths ?? new MemoryPathIndex();
         this.locales = options.locales ?? DEFAULT_ENTRY_LOCALES;
+        this.schemas = [...collections, ...(options.shared ?? [])];
     }
     schema(collection) {
-        return schemaOf(this.collections, collection);
+        return schemaOf(this.schemas, collection);
     }
     row(collection, id) {
         const entry = this.entries.get(id);
@@ -253,13 +262,23 @@ export class MemoryEntryStore {
         const schema = this.schema(collection);
         assertSupportedLocale(options.locale, this.locales);
         const parentId = options.parentId ?? null;
+        if (isSharedSchema(schema)) {
+            if ([...this.entries.values()].some((e) => e.collection === collection))
+                throw entryErrors.singleton(collection);
+            if (slugOf(fields) !== null)
+                throw entryErrors.noSlug(collection);
+        }
         const parent = this.assertParent(collection, parentId, 1);
         this.assertParentHasLocale(parent, options.locale);
         const { shared, localized, slug } = splitFields(fields, schema);
         this.assertSiblingSlug(collection, parentId, options.locale, slug);
         const now = Date.now();
         const entry = {
-            id: uid("entry"), collection, parentId, fields: shared,
+            // A shared item's id is derived, not minted (spec 2026-09-07 §10):
+            // the same uuid v5 the Supabase adapter computes, so self-host and
+            // cloud agree on the row a materialization would create.
+            id: isSharedSchema(schema) ? await sharedEntryId(DEFAULT_SPACE_ID, collection) : uid("entry"),
+            collection, parentId, fields: shared,
             locales: {
                 [options.locale]: { slug, status: "draft", fields: localized, draftVersionId: null, publishedVersionId: null, updatedAt: now },
             },
@@ -322,6 +341,8 @@ export class MemoryEntryStore {
         const entry = this.must(collection, id);
         const row = entryLocaleRow(entry, locale);
         const { shared, localized, slug } = splitFields(fields, schema);
+        if (isSharedSchema(schema) && slug !== null)
+            throw entryErrors.noSlug(collection);
         this.assertSiblingSlug(collection, entry.parentId, locale, slug, id);
         const before = { fields: entry.fields, row: { ...row } };
         entry.fields = shared;
@@ -387,6 +408,8 @@ export class MemoryEntryStore {
     }
     async removeLocale(collection, id, locale) {
         const schema = this.schema(collection);
+        if (isSharedSchema(schema))
+            throw entryErrors.everyLocale(collection);
         const entry = this.must(collection, id);
         const row = entryLocaleRow(entry, locale);
         if (Object.keys(entry.locales).length === 1)
@@ -417,6 +440,8 @@ export class MemoryEntryStore {
             .map((v) => structuredClone(v));
     }
     async move(collection, id, to) {
+        if (isSharedSchema(this.schema(collection)))
+            throw entryErrors.owned(collection, "it has no tree position");
         const entry = this.must(collection, id);
         const subtree = this.subtree(entry);
         if (to.parentId !== null && (to.parentId === id || subtree.some((e) => e.id === to.parentId)))
@@ -454,6 +479,8 @@ export class MemoryEntryStore {
         const entry = this.row(collection, id);
         if (!entry)
             return;
+        if (isSharedSchema(this.schema(collection)))
+            throw entryErrors.owned(collection, "remove the registration to remove it");
         if ([...this.entries.values()].some((e) => e.parentId === id))
             throw entryErrors.hasChildren(collection, id);
         const usage = await this.referencesTo(collection, id);
@@ -467,7 +494,8 @@ export class MemoryEntryStore {
         this.refs.remove({ sourceKind: "entry", sourceId: id });
     }
     async reorder(collection, orderedIds) {
-        this.schema(collection);
+        if (isSharedSchema(this.schema(collection)))
+            throw entryErrors.owned(collection, "it has no order");
         orderedIds.forEach((id, i) => {
             const entry = this.row(collection, id);
             if (entry)

package/dist/fields.d.ts

@@ -31,6 +31,15 @@ export type BuilderFlags = {
     optional?: true;
     localized?: true;
 };
+/** A builder whose flags carry `localized: true` becomes `never` here, so
+ *  `f.list(f.text().localized())` and `f.object({ a: f.text().localized() })`
+ *  are type errors: localization is whole-value on lists and objects
+ *  (spec 2026-09-07, list field §2). */
+type NotLocalized<B> = B extends {
+    __flags?: infer Fl;
+} ? Fl extends {
+    localized: true;
+} ? never : B : B;
 export declare const f: {
     text: () => FieldBuilder<string, {}>;
     link: () => FieldBuilder<string, {}>;
@@ -54,7 +63,12 @@ export declare const f: {
     }) => FieldBuilder<unknown, {}>;
     dataAttributes: () => FieldBuilder<Record<string, string>, {}>;
     select: <const O extends readonly string[]>(options: O) => FieldBuilder<O[number], {}>;
-    object: <S extends Record<string, FieldBuilder<any, any>>>(shape: S) => FieldBuilder<{ [K in keyof S]: ValueOf<S[K]>; }, {}>;
+    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
+     *  300px sidebar cannot show one legibly (spec 2026-09-07, list field §1).
+     *  `.min`/`.max` count items. */
+    list: <B extends FieldBuilder<any, any>>(item: B & NotLocalized<B>) => FieldBuilder<ValueOf<B>[], {}>;
     ref: <T>(target: () => T) => FieldBuilder<Resolved<T>, {}>;
     refList: <T>(target: () => T) => FieldBuilder<Resolved<T>[], {}>;
 };
@@ -65,3 +79,4 @@ export type ValueOf<B> = B extends FieldBuilder<infer V, infer Flags> ? Flags ex
 export type Resolved<T> = T extends {
     __entry?: infer E;
 } ? E : Record<string, unknown>;
+export {};

package/dist/fields.js

@@ -20,6 +20,35 @@ function builder(descriptor) {
         tab: (tab) => chain({ tab }),
     };
 }
+const describePath = (path) => (path === "" ? "the item" : `"${path}"`);
+/** First path at which `matches` is true of the descriptor, walking into
+ *  object subfields and a list's item, or null. */
+function findMatch(d, matches, path = "") {
+    if (matches(d))
+        return path;
+    if (d.type === "object") {
+        for (const [k, sub] of Object.entries(d.fields)) {
+            const hit = findMatch(sub, matches, path ? `${path}.${k}` : k);
+            if (hit !== null)
+                return hit;
+        }
+    }
+    if (d.type === "list")
+        return findMatch(d.item, matches, path);
+    return null;
+}
+/** Refs are addressed by top-level key everywhere (resolver, refs index,
+ *  admin); `.localized()` decides storage per top-level field. Neither may
+ *  hide inside a container. */
+function assertContainerItem(kind, d, path = "") {
+    const ref = findMatch(d, (sub) => sub.type === "ref" || sub.type === "refList", path);
+    if (ref !== null)
+        throw new Error(`smoodly: ${kind} cannot hold a ref (at ${describePath(ref)}) — refs live at the top level of fields.`);
+    const loc = findMatch(d, (sub) => sub.localized === true, path);
+    if (loc !== null) {
+        throw new Error(`smoodly: .localized() inside ${kind} (at ${describePath(loc)}) — localize the ${kind === "f.list" ? "list" : "object"} itself.`);
+    }
+}
 export const f = {
     text: () => builder({ type: "text" }),
     link: () => builder({ type: "link" }),
@@ -32,10 +61,26 @@ export const f = {
     richtext: (opts) => builder({ type: "richtext", ...(opts?.toolset !== undefined ? { toolset: opts.toolset } : {}) }),
     dataAttributes: () => builder({ type: "dataAttributes" }),
     select: (options) => builder({ type: "select", options: [...options] }),
-    object: (shape) => builder({
-        type: "object",
-        fields: Object.fromEntries(Object.entries(shape).map(([k, v]) => [k, v.descriptor])),
-    }),
+    object: (shape) => {
+        for (const [k, v] of Object.entries(shape))
+            assertContainerItem("f.object", v.descriptor, k);
+        return builder({
+            type: "object",
+            fields: Object.fromEntries(Object.entries(shape).map(([k, v]) => [k, v.descriptor])),
+        });
+    },
+    /** 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
+     *  300px sidebar cannot show one legibly (spec 2026-09-07, list field §1).
+     *  `.min`/`.max` count items. */
+    list: (item) => {
+        const d = item.descriptor;
+        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.`);
+        assertContainerItem("f.list", d);
+        return builder({ type: "list", item: d });
+    },
     ref: (target) => builder({ type: "ref", target }),
     refList: (target) => builder({ type: "refList", target }),
 };

package/dist/index.d.ts

@@ -3,8 +3,10 @@ import { collection, toolset } from "./collections.ts";
 import { Section } from "./section-wrapper.tsx";
 import { page } from "./render.tsx";
 import { entryPage } from "./entry-page.tsx";
+import { shared } from "./shared.ts";
 export { Zone, renderPage, EMPTY_PAGE_CONTEXT } from "./render.tsx";
 export type { PageTree, TreeNode, ZoneContent, PairedPage, Registry, PageContext, PageContextLink, PageLink, PageViewProps } from "./render.tsx";
+export { RichText } from "./richtext-render.tsx";
 export type { PageSchema } from "./page.ts";
 export { fixedSlug } from "./page.ts";
 export type { EntryPageSchema, PairedEntryPage, EntryPageProps } from "./entry-page.tsx";
@@ -24,7 +26,7 @@ export { SupabaseEntryStore } from "./supabase-entry-store.ts";
 export { SupabasePathIndex } from "./supabase-path-index.ts";
 export type { EntryStore, EntryRecord, EntryLocale, EntryVersion, EntryUsage, ListOptions, CreateEntryOptions, AddEntryLocaleOptions, EntryStoreOptions, } from "./entry-store.ts";
 export { entryErrors, compareEntries, DEFAULT_ENTRY_LOCALES, localizedKeys, splitFields, entryLocaleRow, entryFieldsIn, entryRefEdges, entryTitleIn, } from "./entry-store.ts";
-export { affectedTargets, pageTag, entryTag } from "./revalidate.ts";
+export { affectedTargets, pageTag, entryTag, sharedTag } from "./revalidate.ts";
 export type { AffectedTargets } from "./revalidate.ts";
 export { resolveTree, resolveFields } from "./resolve.ts";
 export type { EntryFetcher, ResolveFieldsOptions } from "./resolve.ts";
@@ -40,6 +42,10 @@ export type { Props, PairedComponent } from "./pairing.tsx";
 export type { CollectionSchema, Toolset, EntryOrder } from "./collections.ts";
 export { collectionOrder, collectionDepth, DEFAULT_ORDER } from "./collections.ts";
 export type { ZonePolicy } from "./zones.ts";
+export { SHARED_NODE_TYPE, STYLES_KEY, sharedLink } from "./shared.ts";
+export { sharedEntryId } from "./shared-id.ts";
+export { DEFAULT_SPACE_ID } from "./sql-space.ts";
+export type { SharedSchema, SharedLink } from "./shared.ts";
 export declare const smoodly: {
     schema: {
         page: typeof import("./page.ts").pageSchema;
@@ -110,6 +116,7 @@ export declare const smoodly: {
     entryPage: typeof entryPage;
     collection: typeof collection;
     toolset: typeof toolset;
+    shared: typeof shared;
     Section: typeof Section;
 };
 export { resolveSmoodlyEnv, smoodlyEnv } from "./env.ts";

package/dist/index.js

@@ -4,7 +4,9 @@ import { collection, toolset } from "./collections.js";
 import { Section } from "./section-wrapper.js";
 import { page } from "./render.js";
 import { entryPage } from "./entry-page.js";
+import { shared } from "./shared.js";
 export { Zone, renderPage, EMPTY_PAGE_CONTEXT } from "./render.js";
+export { RichText } from "./richtext-render.js";
 export { fixedSlug } from "./page.js";
 export { f } from "./fields.js";
 export { z } from "./zones.js";
@@ -19,12 +21,15 @@ export { MemoryEntryStore } from "./entry-store.js";
 export { SupabaseEntryStore } from "./supabase-entry-store.js";
 export { SupabasePathIndex } from "./supabase-path-index.js";
 export { entryErrors, compareEntries, DEFAULT_ENTRY_LOCALES, localizedKeys, splitFields, entryLocaleRow, entryFieldsIn, entryRefEdges, entryTitleIn, } from "./entry-store.js";
-export { affectedTargets, pageTag, entryTag } from "./revalidate.js";
+export { affectedTargets, pageTag, entryTag, sharedTag } from "./revalidate.js";
 export { resolveTree, resolveFields } from "./resolve.js";
 export { SEGMENT_RE, isSegment, assertSegment, joinPath, splitPath, segmentFor, isHomeNode, pagePathIn, chainOf, assertDepth, pagePath, pagePathRows, entryPathRows, collectionSegment, buildPageTree, perLocaleSegments, assertSupportedLocale, unsupportedLocale, } from "./paths.js";
 export { fixedPathFor } from "./localize.js";
 export { pathOptions, pageErrors, localeRow, pageRefEdges, DEFAULT_LOCALES } from "./store.js";
 export { collectionOrder, collectionDepth, DEFAULT_ORDER } from "./collections.js";
+export { SHARED_NODE_TYPE, STYLES_KEY, sharedLink } from "./shared.js";
+export { sharedEntryId } from "./shared-id.js";
+export { DEFAULT_SPACE_ID } from "./sql-space.js";
 export const smoodly = {
     schema,
     section,
@@ -33,6 +38,7 @@ export const smoodly = {
     entryPage,
     collection,
     toolset,
+    shared,
     Section,
 };
 export { resolveSmoodlyEnv, smoodlyEnv } from "./env.js";

package/dist/next/page-renderer.d.ts

@@ -2,6 +2,7 @@ import type { ComponentType, ReactElement } from "react";
 import type { Metadata } from "next";
 import type { Descriptor } from "../fields.ts";
 import { type PairedPage } from "../render.tsx";
+import type { SharedSchema } from "../shared.ts";
 import { type SmoodlySite } from "../site.ts";
 /** A registered section, as renderPage's registry needs it. */
 type SectionEntry = ComponentType<any> & {
@@ -31,6 +32,9 @@ export type PathRenderOptions = {
     searchParams?: Promise<Record<string, string | string[] | undefined>>;
 };
 export declare function createPageRenderer(options: PageRendererOptions): {
+    getSmoodlyShared: <V>(item: SharedSchema<V>, opts?: {
+        locale?: string;
+    }) => Promise<V | null>;
     renderSmoodlyPath: (segments: string[], opts?: PathRenderOptions) => Promise<ReactElement<unknown, string | import("react").JSXElementConstructor<any>>>;
     smoodlyMetadata: (segments: string[], opts?: {
         locale?: string;

package/dist/next/page-renderer.js

@@ -7,7 +7,7 @@ import { EditorBridge } from "../admin/next/bridge.js";
 import { fixedPathFor } from "../localize.js";
 import { joinPath } from "../paths.js";
 import { renderPage } from "../render.js";
-import { entryTag, pageTag } from "../revalidate.js";
+import { entryTag, pageTag, sharedTag } from "../revalidate.js";
 import { pageContextOf } from "../site.js";
 import { metadataFrom } from "./meta.js";
 export function createPageRenderer(options) {
@@ -82,7 +82,20 @@ export function createPageRenderer(options) {
      *  error surfaces as a rejected promise like every other failure. */
     const fixedPath = (Page) => (locale) => fixedPathFor(Page.schema, locale, site.locales, site.homePageSlug);
     const literal = (segments) => () => joinPath(segments);
+    /** A shared item for a layout: cached per (item, locale) under the
+     *  shared tag outside draft mode, the live draft inside it. */
+    async function getSmoodlyShared(item, opts) {
+        await connection();
+        const locale = opts?.locale ?? site.locales.default;
+        const { isEnabled: draft } = await draftMode();
+        if (draft)
+            return site.getShared(item, { locale, draft: true });
+        return unstable_cache(() => site.getShared(item, { locale }), ["smoodly-shared", item.name, locale], {
+            tags: [sharedTag(item.name)],
+        })();
+    }
     return {
+        getSmoodlyShared,
         renderSmoodlyPath: (segments, opts) => page(literal(segments), opts, any),
         smoodlyMetadata: (segments, opts) => metadata(literal(segments), opts, any),
         /** A fixed registration rendered from the developer's own route file. */

package/dist/page.js

@@ -10,7 +10,11 @@ function normalizePolicy(p) {
         case "freeform":
             return { kind: "freeform", allow: p.allow, rows: p.rows };
         case "locked":
-            return { kind: "locked", component: p.component };
+            return {
+                kind: "locked",
+                component: p.component,
+                ...(typeof p.shared === "string" ? { shared: p.shared } : {}),
+            };
         default:
             throw new Error(`smoodly: unknown zone policy kind "${String(p.kind)}".`);
     }

package/dist/refs.js

@@ -4,6 +4,7 @@
 // and never the source of truth. Stores rewrite a source's edges on
 // every save; `refs` answers only the REVERSE question (who depends on
 // this?) — forward resolution stays resolveTree's job.
+import { sharedLink } from "./shared.js";
 function targetOf(d) {
     const t = d.target?.();
     if (!t?.name)
@@ -24,6 +25,11 @@ function collectFrom(values, descriptors, out) {
                     out.push({ field, targetCollection: targetOf(d), targetId: id });
             }
         }
+        else if (d.type === "object" || d.type === "list") {
+            // Deliberate: refs are top-level only — f.list/f.object refuse them at
+            // build time (spec 2026-09-07, list field §1), so there is nothing to walk.
+            continue;
+        }
     }
 }
 export function collectEntryRefs(fields, schema) {
@@ -39,6 +45,13 @@ export function collectTreeRefs(tree, sections) {
     const out = [];
     for (const nodes of Object.values(tree.zones ?? {})) {
         for (const node of nodes) {
+            // A placement (spec 2026-09-07 §5): one edge, keyed by the node id
+            // so two placements of one item on one page stay distinct rows.
+            const link = sharedLink(node);
+            if (link) {
+                out.push({ field: node.id, targetCollection: link.item, targetId: link.ref });
+                continue;
+            }
             const schema = byName.get(node.type);
             if (!schema)
                 continue; // fail-soft, same as renderPage

package/dist/resolve.d.ts

@@ -1,6 +1,7 @@
 import type { Descriptor } from "./fields.ts";
 import type { CollectionSchema } from "./collections.ts";
 import type { PageTree } from "./render.tsx";
+import { type SharedSchema } from "./shared.ts";
 export type EntryFetcher = (collection: string, ids: string[]) => Promise<Record<string, Record<string, unknown>>>;
 type SchemaLike = {
     name: string;
@@ -15,6 +16,8 @@ type ResolveOptions = {
     })[];
     collections: CollectionSchema<any>[];
     fetch: EntryFetcher;
+    /** The registered shared items a placement node may name (spec 2026-09-07 §4). */
+    shared?: SharedSchema[];
     /** Optional safety valve on chain length; unlimited by default. */
     maxDepth?: number;
 };

package/dist/resolve.js

@@ -6,6 +6,7 @@
 // Cycles are cut per path — a ref back to an entry already on its own
 // chain gets a shallow copy (refs as ids), so traversal terminates by
 // construction and the output stays JSON-serializable.
+import { sharedLink, SHARED_NODE_TYPE, STYLES_KEY } from "./shared.js";
 function targetOf(d) {
     const t = d.target?.();
     if (!t?.name)
@@ -27,6 +28,7 @@ export async function resolveTree(tree, options) {
         return [schema.name, schema];
     }));
     const resolved = structuredClone(tree);
+    await rewritePlacements(resolved, options.shared ?? [], options.fetch);
     const tasks = [];
     for (const nodes of Object.values(resolved.zones ?? {})) {
         for (const node of nodes) {
@@ -39,6 +41,42 @@ export async function resolveTree(tree, options) {
     await runResolution(tasks, { collections: options.collections, fetch: options.fetch, maxDepth });
     return resolved;
 }
+/** Placements first (spec 2026-09-07 §4): fetch every linked item in one
+ *  call per item, rewrite each node into the item's section node — the
+ *  placement's id stays, so the canvas selects it — and drop what the
+ *  site cannot render: an unpublished or dangling row, an object item
+ *  (no view), an unknown item. The normal pass then hydrates the
+ *  rewritten nodes' own refs. */
+async function rewritePlacements(tree, shared, fetch) {
+    const byName = new Map(shared.map((s) => [s.name, s]));
+    const wanted = new Map();
+    for (const nodes of Object.values(tree.zones ?? {})) {
+        for (const node of nodes) {
+            const link = sharedLink(node);
+            if (!link || !byName.get(link.item)?.section)
+                continue;
+            const ids = wanted.get(link.item) ?? new Set();
+            ids.add(link.ref);
+            wanted.set(link.item, ids);
+        }
+    }
+    const fetched = new Map();
+    await Promise.all([...wanted].map(async ([item, ids]) => fetched.set(item, await fetch(item, [...ids]))));
+    for (const [zone, nodes] of Object.entries(tree.zones ?? {})) {
+        tree.zones[zone] = nodes.flatMap((node) => {
+            const link = sharedLink(node);
+            if (!link)
+                return node.type === SHARED_NODE_TYPE ? [] : [node];
+            const schema = byName.get(link.item);
+            const row = fetched.get(link.item)?.[link.ref];
+            if (!schema?.section || !row)
+                return [];
+            const { [STYLES_KEY]: styles, ...fields } = structuredClone(row);
+            const isObject = styles !== null && typeof styles === "object";
+            return [{ id: node.id, type: schema.section, fields, ...(isObject ? { styles: styles } : {}) }];
+        });
+    }
+}
 /** One entry's fields, refs hydrated — the entry page's counterpart of
  *  resolveTree. Same rules, same batching, same cycle cut. */
 export async function resolveFields(fields, descriptors, options) {
@@ -136,5 +174,8 @@ function collectTasks(values, descriptors, out) {
         else if (d.type === "refList" && Array.isArray(value)) {
             out.push({ holder: values, key, collection: targetOf(d), id: value, isList: true, mode: modeOf(d), ancestors: [] });
         }
+        else if (d.type === "object" || d.type === "list") {
+            continue; // refs are top-level only; containers hold none (spec 2026-09-07)
+        }
     }
 }

package/dist/revalidate.d.ts

@@ -8,6 +8,10 @@ export type AffectedTargets = {
 };
 export declare const pageTag: (id: string) => string;
 export declare const entryTag: (id: string) => string;
+/** A shared item's cache unit, by NAME (a singleton has one row per
+ *  locale, and code owns the name): the Next glue's getSmoodlyShared
+ *  caches under it; ops.shared expires it. */
+export declare const sharedTag: (name: string) => string;
 export declare function affectedTargets(stores: {
     pages: PageStore;
     entries: EntryStore;

package/dist/revalidate.js

@@ -7,6 +7,10 @@
 // change (spec 2026-09-05 §5).
 export const pageTag = (id) => `page:${id}`;
 export const entryTag = (id) => `entry:${id}`;
+/** A shared item's cache unit, by NAME (a singleton has one row per
+ *  locale, and code owns the name): the Next glue's getSmoodlyShared
+ *  caches under it; ops.shared expires it. */
+export const sharedTag = (name) => `shared:${name}`;
 export async function affectedTargets(stores, entryId, options = {}) {
     const maxDepth = options.maxDepth ?? Infinity;
     const seen = new Set([entryId]);

package/dist/richtext-render.d.ts

@@ -0,0 +1,3 @@
+export declare function RichText({ doc }: {
+    doc: unknown;
+}): import("react").JSX.Element | null;