smoodly 0.0.16 → 0.0.18

package/dist/custom/rows.js

@@ -0,0 +1,129 @@
+// The custom section's reconcile functions (spec 2026-09-14 §6): pure,
+// shared by the admin widget, the validator and the tests. Never silent
+// deletion — a removed column's content folds into the last survivor.
+import { ALIGN_STEPS, GAP_STEPS, MAX_COLUMNS, SPAN_TOTAL } from "./schema.js";
+export const EMPTY_DOC = { type: "doc", content: [{ type: "paragraph" }] };
+export function defaultRow(columns = 1) {
+    const n = Math.max(1, Math.min(MAX_COLUMNS, columns));
+    return { spans: renormalize(Array(n).fill(1)), gap: "md", align: "top", reverse: false, columns: Array.from({ length: n }, () => structuredClone(EMPTY_DOC)) };
+}
+/** Integers ≥ 1 summing to 12, proportions kept: scale, floor, hand the
+ *  remainder out by largest fraction (ties to the earlier column), then
+ *  lift any 0 to 1 from the largest column. */
+export function renormalize(spans) {
+    const n = spans.length;
+    if (n === 0)
+        return [];
+    if (n > SPAN_TOTAL)
+        return renormalize(spans.slice(0, SPAN_TOTAL));
+    const clean = spans.map((s) => (Number.isFinite(s) && s > 0 ? s : 1));
+    const total = clean.reduce((a, b) => a + b, 0);
+    const exact = clean.map((s) => (s / total) * SPAN_TOTAL);
+    const out = exact.map((e) => Math.floor(e));
+    let left = SPAN_TOTAL - out.reduce((a, b) => a + b, 0);
+    const order = exact.map((e, i) => [e - out[i], i]).sort((a, b) => b[0] - a[0] || a[1] - b[1]);
+    for (const [, i] of order) {
+        if (left <= 0)
+            break;
+        out[i]++;
+        left--;
+    }
+    for (let i = 0; i < n; i++) {
+        while (out[i] < 1) {
+            const largest = out.indexOf(Math.max(...out));
+            out[largest]--;
+            out[i]++;
+        }
+    }
+    return out;
+}
+export function setColumnCount(row, count) {
+    const n = Math.max(1, Math.min(MAX_COLUMNS, count));
+    const current = row.columns.length;
+    if (n === current)
+        return row;
+    if (n > current) {
+        const spans = [...row.spans];
+        const columns = [...row.columns];
+        while (spans.length < n) {
+            spans.push(spans[spans.length - 1] ?? 1);
+            columns.push(structuredClone(EMPTY_DOC));
+        }
+        return { ...row, spans: renormalize(spans), columns };
+    }
+    const keep = row.columns.slice(0, n);
+    const folded = row.columns.slice(n).reduce((acc, doc) => concatDocs(acc, doc), keep[n - 1]);
+    keep[n - 1] = folded;
+    return { ...row, spans: renormalize(row.spans.slice(0, n)), columns: keep };
+}
+/** The boundary between columns `handle` and `handle + 1` moved so the left side is `left` twelfths; both sides keep ≥ 1. */
+export function setSpan(spans, handle, left) {
+    if (handle < 0 || handle >= spans.length - 1)
+        return spans;
+    const pair = spans[handle] + spans[handle + 1];
+    const l = Math.max(1, Math.min(pair - 1, Math.round(left)));
+    const next = [...spans];
+    next[handle] = l;
+    next[handle + 1] = pair - l;
+    return next;
+}
+/** The left span a pointer at `x` over a bar `width` px wide asks for, for the handle between `handle` and `handle + 1`. */
+export function spanAtX(x, width, spans, handle) {
+    const before = spans.slice(0, handle).reduce((a, b) => a + b, 0);
+    const twelfth = Math.max(1, width) / SPAN_TOTAL;
+    const pair = spans[handle] + spans[handle + 1];
+    const wanted = Math.round(x / twelfth) - before;
+    return Math.max(1, Math.min(pair - 1, wanted));
+}
+export function presetsFor(n) {
+    if (n === 2)
+        return [{ label: "1/2 · 1/2", spans: [6, 6] }, { label: "1/3 · 2/3", spans: [4, 8] }, { label: "2/3 · 1/3", spans: [8, 4] }];
+    if (n === 3)
+        return [{ label: "1/3 · 1/3 · 1/3", spans: [4, 4, 4] }];
+    if (n === 4)
+        return [{ label: "1/4 × 4", spans: [3, 3, 3, 3] }];
+    return [];
+}
+const isDoc = (v) => typeof v === "object" && v !== null && v.type === "doc" && Array.isArray(v.content);
+/** A paragraph with no children: what an untouched column holds. Not content, so a fold never appends it. */
+const isBlankNode = (n) => typeof n === "object" && n !== null && n.type === "paragraph"
+    && (!Array.isArray(n.content) || (n.content.length === 0));
+const isBlankDoc = (v) => isDoc(v) && v.content.every(isBlankNode);
+export function concatDocs(a, b) {
+    if (!isDoc(a) || isBlankDoc(a))
+        return isDoc(b) ? b : structuredClone(EMPTY_DOC);
+    if (!isDoc(b) || isBlankDoc(b))
+        return a;
+    return { type: "doc", content: [...a.content, ...b.content] };
+}
+/** The structural problems the publish validator reports, by dotted path. */
+export function rowsProblems(rows) {
+    if (!Array.isArray(rows))
+        return [{ field: "rows", message: "Must be a list." }];
+    const out = [];
+    rows.forEach((row, i) => {
+        const r = row;
+        const columns = Array.isArray(r?.columns) ? r.columns : [];
+        const spans = Array.isArray(r?.spans) ? r.spans : [];
+        if (columns.length < 1 || columns.length > MAX_COLUMNS) {
+            out.push({ field: `rows.${i}.columns`, message: "Between 1 and 6 columns." });
+            return;
+        }
+        if (spans.length !== columns.length) {
+            out.push({ field: `rows.${i}.spans`, message: "One span per column." });
+            return;
+        }
+        if (!spans.every((s) => Number.isInteger(s) && s >= 1) || spans.reduce((a, b) => a + b, 0) !== SPAN_TOTAL)
+            out.push({ field: `rows.${i}.spans`, message: "Spans must sum to 12." });
+        if (r?.gap !== undefined && !GAP_STEPS.includes(r.gap))
+            out.push({ field: `rows.${i}.gap`, message: `Must be one of: ${GAP_STEPS.join(", ")}.` });
+        if (r?.align !== undefined && !ALIGN_STEPS.includes(r.align))
+            out.push({ field: `rows.${i}.align`, message: `Must be one of: ${ALIGN_STEPS.join(", ")}.` });
+    });
+    return out;
+}
+export function columnsLabel(rows) {
+    const first = Array.isArray(rows) ? rows[0] : undefined;
+    const n = Array.isArray(first?.columns) ? first.columns.length : 0;
+    return n === 0 ? "Custom section" : `Custom section · ${n} column${n === 1 ? "" : "s"}`;
+}

package/dist/custom/schema.d.ts

@@ -0,0 +1,32 @@
+import type { Descriptor } from "../fields.ts";
+import { type Toolset } from "../toolset.ts";
+export declare const CUSTOM_NODE_TYPE = "custom";
+export declare const MAX_COLUMNS = 6;
+export declare const SPAN_TOTAL = 12;
+export declare const DEFAULT_BREAKPOINT = "48rem";
+export declare const GAP_STEPS: readonly ["sm", "md", "lg"];
+export type GapStep = (typeof GAP_STEPS)[number];
+export declare const GAP_VALUES: Record<GapStep, string>;
+export declare const ALIGN_STEPS: readonly ["top", "center", "bottom", "stretch"];
+export type AlignStep = (typeof ALIGN_STEPS)[number];
+/** CSS `align-items` per step — the only keywords the emitter writes. */
+export declare const ALIGN_VALUES: Record<AlignStep, string>;
+export type CustomRow = {
+    spans: number[];
+    gap: GapStep;
+    align: AlignStep;
+    reverse: boolean;
+    columns: unknown[];
+};
+export type CustomFields = {
+    rows: CustomRow[];
+};
+/** The columns' toolset: the developer's, or the richtext default plus the image node. */
+export declare function customToolset(toolset?: Toolset): Toolset;
+export declare function customFields(toolset: Toolset): Record<string, Descriptor>;
+/** What every section map gets for the node type: the walks, the resolver and the validator read it like a section's schema. */
+export declare function customSchema(toolset: Toolset): {
+    name: string;
+    fields: Record<string, Descriptor>;
+    settings: Record<string, Descriptor>;
+};

package/dist/custom/schema.js

@@ -0,0 +1,39 @@
+import { DEFAULT_TOOLSET } from "../toolset.js";
+export const CUSTOM_NODE_TYPE = "custom";
+export const MAX_COLUMNS = 6;
+export const SPAN_TOTAL = 12;
+export const DEFAULT_BREAKPOINT = "48rem";
+export const GAP_STEPS = ["sm", "md", "lg"];
+export const GAP_VALUES = { sm: "1rem", md: "2rem", lg: "3rem" };
+export const ALIGN_STEPS = ["top", "center", "bottom", "stretch"];
+/** CSS `align-items` per step — the only keywords the emitter writes. */
+export const ALIGN_VALUES = { top: "start", center: "center", bottom: "end", stretch: "stretch" };
+/** The columns' toolset: the developer's, or the richtext default plus the image node. */
+export function customToolset(toolset) {
+    if (toolset)
+        return toolset;
+    return { ...DEFAULT_TOOLSET, nodes: [...(DEFAULT_TOOLSET.nodes ?? []), "image"] };
+}
+const radio = (options, labels, fallback) => ({ type: "radio", options: options.map((value) => ({ value, label: labels[value] })), default: fallback });
+export function customFields(toolset) {
+    return {
+        rows: {
+            type: "list", widget: "rows", min: 1,
+            item: {
+                type: "object",
+                fields: {
+                    spans: { type: "spans" },
+                    gap: radio(GAP_STEPS, { sm: "S", md: "M", lg: "L" }, "md"),
+                    align: radio(ALIGN_STEPS, { top: "Top", center: "Center", bottom: "Bottom", stretch: "Stretch" }, "top"),
+                    reverse: { type: "boolean", default: false },
+                    // An empty column publishes (it is spacing); the row structure is rowsProblems' job.
+                    columns: { type: "list", min: 1, max: MAX_COLUMNS, item: { type: "richtext", toolset, optional: true } },
+                },
+            },
+        },
+    };
+}
+/** What every section map gets for the node type: the walks, the resolver and the validator read it like a section's schema. */
+export function customSchema(toolset) {
+    return { name: CUSTOM_NODE_TYPE, fields: customFields(toolset), settings: {} };
+}

package/dist/entry-page.d.ts

@@ -1,14 +1,19 @@
 import type { ComponentType, ReactElement } from "react";
 import type { CollectionSchema } from "./collections.ts";
 import type { EntryRecord } from "./entry-store.ts";
+import type { LocaleAlternate } from "./paths.ts";
 export type EntryPageSchema = {
     kind: "entryPage";
     name: string;
     collection: string;
 };
+/** What an entry page renders: the entry in the render locale, its path
+ *  there, and its address in every supported locale (spec 2026-09-15 §1). */
 export type EntryPageProps = {
     entry: EntryRecord;
     path: string;
+    locale: string;
+    locales: Record<string, LocaleAlternate | null>;
 };
 export type PairedEntryPage = ((props: EntryPageProps) => ReactElement) & {
     schema: EntryPageSchema;

package/dist/entry-page.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 export function entryPage(collection, View) {
-    const Component = ((props) => _jsx(View, { entry: props.entry, path: props.path }));
+    const Component = ((props) => _jsx(View, { ...props }));
     Component.schema = { kind: "entryPage", name: `entry:${collection.name}`, collection: collection.name };
     return Component;
 }

package/dist/entry-store.d.ts

@@ -1,5 +1,5 @@
 import type { CollectionSchema, EntryOrder } from "./collections.ts";
-import type { SharedSchema } from "./shared.ts";
+import type { GlobalSchema } from "./global.ts";
 import { type RefEdge, type SectionLike } from "./refs.ts";
 import { MemoryRefIndex } from "./ref-index.ts";
 import { type PathIndex } from "./path-index.ts";
@@ -82,7 +82,7 @@ export type AddEntryLocaleOptions = {
 export type EntryStoreOptions = {
     paths?: PathIndex;
     locales?: LocaleSet;
-    shared?: SharedSchema[];
+    globals?: GlobalSchema[];
     /** Registered Elements a richtext document may embed (spec 2026-09-08 block nodes §2). */
     elements?: SectionLike[];
 };
@@ -154,8 +154,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;
+/** A global item is a collection with exactly one entry (spec 2026-09-07). */
+export declare const isGlobalSchema: (schema: CollectionSchema<any>) => boolean;
 export declare const DEFAULT_ENTRY_LOCALES: LocaleSet;
 export declare const entryErrors: {
     notFound: (collection: string, id: string) => Error;

package/dist/entry-store.js

@@ -13,7 +13,7 @@ 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 { globalEntryId } from "./global-id.js";
 import { DEFAULT_SPACE_ID } from "./sql-space.js";
 import { assertDepth, assertSupportedLocale, chainOf, entryPathRows, slugOf, unsupportedLocale, } from "./paths.js";
 /** The field types whose value is an array: a scalar `where` on one is
@@ -40,8 +40,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";
+/** A global item is a collection with exactly one entry (spec 2026-09-07). */
+export const isGlobalSchema = (schema) => schema.kind === "global";
 let counter = 0;
 const uid = (prefix) => `${prefix}-${++counter}-${Date.now().toString(36)}`;
 export const DEFAULT_ENTRY_LOCALES = { default: "en", supported: ["en"] };
@@ -62,11 +62,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.`),
+    // Global items (spec 2026-09-07 §3): one row, no URL, every locale, code-owned.
+    singleton: (name) => new Error(`smoodly: global item "${name}" already exists — it is a singleton.`),
+    owned: (name, verb) => new Error(`smoodly: global item "${name}" is owned by code — ${verb}.`),
+    noSlug: (name) => new Error(`smoodly: global item "${name}" has no URL — it cannot take a slug.`),
+    everyLocale: (name) => new Error(`smoodly: global item "${name}" exists in every locale — it cannot be removed from one.`),
     foreignVersion: (collection, id, locale, versionId) => new Error(`smoodly: "${versionId}" is not a version of entry "${id}" in "${collection}", locale "${locale}".`),
 };
 /** The keys a locale row owns: every field with .localized(), except
@@ -167,7 +167,7 @@ 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 ?? [])];
+        this.schemas = [...collections, ...(options.globals ?? [])];
         this.elements = options.elements;
     }
     schema(collection) {
@@ -304,7 +304,7 @@ export class MemoryEntryStore {
         const schema = this.schema(collection);
         assertSupportedLocale(options.locale, this.locales);
         const parentId = options.parentId ?? null;
-        if (isSharedSchema(schema)) {
+        if (isGlobalSchema(schema)) {
             if ([...this.entries.values()].some((e) => e.collection === collection))
                 throw entryErrors.singleton(collection);
             if (slugOf(fields) !== null)
@@ -316,10 +316,10 @@ export class MemoryEntryStore {
         this.assertSiblingSlug(collection, parentId, options.locale, slug);
         const now = Date.now();
         const entry = {
-            // A shared item's id is derived, not minted (spec 2026-09-07 §10):
+            // A global 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"),
+            id: isGlobalSchema(schema) ? await globalEntryId(DEFAULT_SPACE_ID, collection) : uid("entry"),
             collection, parentId, fields: shared,
             locales: {
                 [options.locale]: {
@@ -393,7 +393,7 @@ export class MemoryEntryStore {
         const row = entryLocaleRow(entry, locale);
         this.ensureLiveSnapshot(entry, locale);
         const { shared, localized, slug } = splitFields(fields, schema);
-        if (isSharedSchema(schema) && slug !== null)
+        if (isGlobalSchema(schema) && slug !== null)
             throw entryErrors.noSlug(collection);
         this.assertSiblingSlug(collection, entry.parentId, locale, slug, id);
         const before = { fields: entry.fields, row: { ...row } };
@@ -479,7 +479,7 @@ export class MemoryEntryStore {
     }
     async removeLocale(collection, id, locale) {
         const schema = this.schema(collection);
-        if (isSharedSchema(schema))
+        if (isGlobalSchema(schema))
             throw entryErrors.everyLocale(collection);
         const entry = this.must(collection, id);
         const row = entryLocaleRow(entry, locale);
@@ -533,7 +533,7 @@ export class MemoryEntryStore {
         return v ? structuredClone(v) : null;
     }
     async move(collection, id, to) {
-        if (isSharedSchema(this.schema(collection)))
+        if (isGlobalSchema(this.schema(collection)))
             throw entryErrors.owned(collection, "it has no tree position");
         const entry = this.must(collection, id);
         const subtree = this.subtree(entry);
@@ -572,7 +572,7 @@ export class MemoryEntryStore {
         const entry = this.row(collection, id);
         if (!entry)
             return;
-        if (isSharedSchema(this.schema(collection)))
+        if (isGlobalSchema(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);
@@ -587,7 +587,7 @@ export class MemoryEntryStore {
         this.refs.remove({ sourceKind: "entry", sourceId: id });
     }
     async reorder(collection, orderedIds) {
-        if (isSharedSchema(this.schema(collection)))
+        if (isGlobalSchema(this.schema(collection)))
             throw entryErrors.owned(collection, "it has no order");
         orderedIds.forEach((id, i) => {
             const entry = this.row(collection, id);

package/dist/fields.d.ts

@@ -1,5 +1,6 @@
 import { type Toolset } from "./toolset.ts";
 import { type ResolvedFile, type ResolvedImage, type ResolvedVideo } from "./media.ts";
+import { type Condition, when } from "./conditions.ts";
 export type Descriptor = {
     type: string;
     [key: string]: unknown;
@@ -43,7 +44,8 @@ export type FieldBuilder<Value = unknown, Flags extends BuilderFlags = {}> = {
      * - no call — hydrate the entry itself; its refs stay ids
      */
     resolve(...projection: (string | Record<string, unknown>)[]): FieldBuilder<Value, Flags>;
-    tab(tab: "content" | "styles" | "media" | "meta"): FieldBuilder<Value, Flags>;
+    /** Hide the field while the condition holds (spec 2026-09-14 §12): it leaves the form and validation skips it; the stored value is kept. */
+    hidden(condition: Condition): FieldBuilder<Value, Flags>;
     /** phantom, type-level only */
     readonly __value?: Value;
     readonly __flags?: Flags;
@@ -83,7 +85,8 @@ export declare const f: {
     richtext: (opts?: {
         toolset?: Toolset;
     }) => FieldBuilder<unknown, {}>;
-    dataAttributes: () => FieldBuilder<Record<string, string>, {}>;
+    /** A condition for `.hidden()`: `f.when("settings.mediaType").is("video")`. */
+    when: typeof when;
     boolean: () => FieldBuilder<boolean, {}>;
     /** One value from a list, shown as a dropdown. */
     select: <const O extends readonly OptionInput[]>(options: O) => FieldBuilder<OptionValue<O[number]>, {}>;

package/dist/fields.js

@@ -3,6 +3,7 @@
 // keyed by descriptor type. Chaining is immutable.
 import { DEFAULT_TOOLSET } from "./toolset.js";
 import { parseAspect } from "./media.js";
+import { when } from "./conditions.js";
 /** Normalizes a schema's option list to objects; refuses an empty list,
  *  since a choice with nothing to choose is a schema bug (spec 2026-09-10
  *  page fields §1). */
@@ -43,7 +44,7 @@ function builder(descriptor) {
                 return chain({ resolve: projection[0] });
             return chain({ resolve: Object.fromEntries(projection.map((k) => [k, true])) });
         },
-        tab: (tab) => chain({ tab }),
+        hidden: (condition) => chain({ hidden: condition }),
     };
 }
 export const describePath = (path) => (path === "" ? "the item" : `"${path}"`);
@@ -97,7 +98,8 @@ export const f = {
     video: () => builder({ type: "video" }),
     file: () => builder({ type: "file" }),
     richtext: (opts) => builder({ type: "richtext", toolset: opts?.toolset ?? DEFAULT_TOOLSET }),
-    dataAttributes: () => builder({ type: "dataAttributes" }),
+    /** A condition for `.hidden()`: `f.when("settings.mediaType").is("video")`. */
+    when,
     boolean: () => builder({ type: "boolean" }),
     /** One value from a list, shown as a dropdown. */
     select: (options) => builder({ type: "select", options: normalizeOptions(options) }),

package/dist/{shared-id.d.ts → global-id.d.ts}

@@ -1,3 +1,3 @@
 /** RFC 4122 §4.3 uuid v5: sha1(namespace bytes ‖ name bytes), version 5,
  *  variant 10xx, first 16 bytes of the digest. */
-export declare function sharedEntryId(space: string, name: string): Promise<string>;
+export declare function globalEntryId(space: string, name: string): Promise<string>;

package/dist/{shared-id.js → global-id.js}

@@ -1,8 +1,8 @@
-// The row id of a shared item (spec 2026-09-07 §10 "§3 row id"): uuid v5
+// The row id of a global item (spec 2026-09-07 §10 "§3 row id"): uuid v5
 // of (space id as the namespace, item name as the name). Deterministic in
 // both adapters, so a second concurrent materialization of the same item
 // hits the `entries` primary key instead of adding an unremovable
-// duplicate — `delete` refuses every shared row. The space is part of it
+// duplicate — `delete` refuses every global row. The space is part of it
 // because the primary key is `id` alone and, in the cloud, many spaces
 // share one table: a name-only id would make space B's footer collide
 // with space A's.
@@ -16,7 +16,7 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 /** The namespace's 16 raw bytes — RFC 4122 hashes the bytes, not the text. */
 function uuidBytes(uuid) {
     if (!UUID_RE.test(uuid))
-        throw new Error(`smoodly: "${uuid}" is not a uuid — a shared item's namespace is the space id.`);
+        throw new Error(`smoodly: "${uuid}" is not a uuid — a global item's namespace is the space id.`);
     const hex = uuid.replace(/-/g, "");
     const bytes = new Uint8Array(16);
     for (let i = 0; i < 16; i++)
@@ -25,7 +25,7 @@ function uuidBytes(uuid) {
 }
 /** RFC 4122 §4.3 uuid v5: sha1(namespace bytes ‖ name bytes), version 5,
  *  variant 10xx, first 16 bytes of the digest. */
-export async function sharedEntryId(space, name) {
+export async function globalEntryId(space, name) {
     const input = new Uint8Array([...uuidBytes(space), ...new TextEncoder().encode(name)]);
     const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-1", input));
     const bytes = digest.subarray(0, 16);

package/dist/global.d.ts

@@ -0,0 +1,57 @@
+import type { CollectionSchema } from "./collections.ts";
+import type { Descriptor } from "./fields.ts";
+import type { PairedComponent } from "./pairing.tsx";
+import type { BuilderMap, NamespaceValues, SectionSchema } from "./schema.ts";
+import type { StyleProps } from "./styles.ts";
+/** The reserved tree node type of a placement. */
+export declare const GLOBAL_NODE_TYPE = "global";
+/** The reserved keys a visual item's settings, styles steps and css live under in its row (spec 2026-09-14 §8). */
+export declare const SETTINGS_KEY = "$settings";
+export declare const STYLES_KEY = "$styles";
+export declare const CSS_KEY = "$css";
+/** The node id a layout-rendered visual item carries (spec 2026-09-13 §1):
+ *  `getGlobal` stamps it into the styles' `__smd`, the section wrapper emits it,
+ *  the canvas selects by it. A placement keeps its own tree node id
+ *  (`global-xxxxxxxx`, no colon). */
+export declare const GLOBAL_NODE_PREFIX = "global:";
+export declare const globalNodeId: (name: string) => string;
+/** The item a layout node id names, or null for any other id. */
+export declare function globalNameOf(id: string): string | null;
+export type GlobalSchema<V = Record<string, unknown>, N extends string = string> = CollectionSchema<any, N> & {
+    kind: "global";
+    /** The registered section a visual item renders through; absent = an object item. */
+    section?: string;
+    /** The section's settings descriptors (empty for an object item). */
+    settings: Record<string, Descriptor>;
+    sample?: Record<string, unknown>;
+    /** phantom: what getGlobal returns */
+    readonly __value?: V;
+};
+export type GlobalLink = {
+    item: string;
+    ref: string;
+};
+/** The placement a tree node is, or null for any other node. Accepts a
+ *  bare `{ type, fields }` shape or a full tree node — `id` (and any
+ *  other tree-node property) is ignored. */
+export declare function globalLink(node: {
+    id?: string;
+    type: string;
+    fields?: Record<string, unknown>;
+}): GlobalLink | null;
+type GlobalInput<N extends string = string> = {
+    name: N;
+    title: string;
+};
+export declare function globalItem<F extends BuilderMap, const N extends string = string>(input: GlobalInput<N> & {
+    fields: F;
+    section?: undefined;
+}): GlobalSchema<NamespaceValues<F>, N>;
+export declare function globalItem<F extends BuilderMap, St extends BuilderMap, const N extends string = string>(input: GlobalInput<N> & {
+    section: PairedComponent<SectionSchema<F, St>, F, St>;
+    fields?: undefined;
+}): GlobalSchema<NamespaceValues<F> & {
+    settings: NamespaceValues<St>;
+    styles: StyleProps;
+}, N>;
+export {};

package/dist/global.js

@@ -0,0 +1,51 @@
+/** The reserved tree node type of a placement. */
+export const GLOBAL_NODE_TYPE = "global";
+/** The reserved keys a visual item's settings, styles steps and css live under in its row (spec 2026-09-14 §8). */
+export const SETTINGS_KEY = "$settings";
+export const STYLES_KEY = "$styles";
+export const CSS_KEY = "$css";
+const RESERVED_KEYS = [SETTINGS_KEY, STYLES_KEY, CSS_KEY];
+/** The node id a layout-rendered visual item carries (spec 2026-09-13 §1):
+ *  `getGlobal` stamps it into the styles' `__smd`, the section wrapper emits it,
+ *  the canvas selects by it. A placement keeps its own tree node id
+ *  (`global-xxxxxxxx`, no colon). */
+export const GLOBAL_NODE_PREFIX = "global:";
+export const globalNodeId = (name) => `${GLOBAL_NODE_PREFIX}${name}`;
+/** The item a layout node id names, or null for any other id. */
+export function globalNameOf(id) {
+    return id.startsWith(GLOBAL_NODE_PREFIX) && id.length > GLOBAL_NODE_PREFIX.length ? id.slice(GLOBAL_NODE_PREFIX.length) : null;
+}
+/** The placement a tree node is, or null for any other node. Accepts a
+ *  bare `{ type, fields }` shape or a full tree node — `id` (and any
+ *  other tree-node property) is ignored. */
+export function globalLink(node) {
+    if (node.type !== GLOBAL_NODE_TYPE)
+        return null;
+    const { item, ref } = node.fields ?? {};
+    return typeof item === "string" && typeof ref === "string" ? { item, ref } : null;
+}
+/** `smoodly.global()`: named `globalItem` here so nothing shadows the `global` idiom. */
+export function globalItem(input) {
+    if (!input?.name)
+        throw new Error("smoodly: a global item requires a name.");
+    if ((input.fields === undefined) === (input.section === undefined)) {
+        throw new Error(`smoodly: global item "${input.name}" must declare exactly one of \`section\` or \`fields\`.`);
+    }
+    const fields = input.section
+        ? input.section.schema.fields
+        : Object.fromEntries(Object.entries(input.fields).map(([k, b]) => [k, b.descriptor]));
+    for (const key of RESERVED_KEYS) {
+        if (Object.prototype.hasOwnProperty.call(fields, key)) {
+            throw new Error(`smoodly: global item "${input.name}" has a field named "${key}" — that key is reserved for a visual item's ${key === SETTINGS_KEY ? "settings" : key === STYLES_KEY ? "styles" : "css"}.`);
+        }
+    }
+    return {
+        kind: "global",
+        name: input.name,
+        title: input.title,
+        fields,
+        settings: input.section ? input.section.schema.settings : {},
+        ...(input.section ? { section: input.section.schema.name } : {}),
+        ...(input.section?.schema.sample ? { sample: input.section.schema.sample } : {}),
+    };
+}