@drawnagency/primitives 0.1.113 → 0.1.114

package/src/lib/nav.ts

@@ -4,7 +4,9 @@ import { audiencePasses, pageDisplayTitle } from "./pages";
 import { navEntries } from "./nav-tree";
 import { getContainerChildren } from "./container-ops";
 import type { SiteIndex } from "../schemas/site-config";
+import type { Section } from "../schemas/sections";
 import type { SiteDocument } from "./documents";
+import { expandReferences, referenceItems, REFERENCE_TYPE, type ReferenceContent, type ReferenceQuery } from "./references";
 
 export interface NavItem {
   href: string;
@@ -41,35 +43,114 @@ function flattenForNav(sections: LoadedSection[]): LoadedSection[] {
   const walk = (loaded: LoadedSection) => {
     flat.push(loaded);
     for (const child of getContainerChildren(loaded.section)) {
-      walk({ section: child, meta: loaded.meta });
+      walk({ section: child, meta: loaded.meta, referencedBy: loaded.referencedBy });
     }
   };
   sections.forEach(walk);
   return flat;
 }
 
-export function generateNavLinks(
-  sections: LoadedSection[],
-  registry?: SectionRegistry,
-): NavItem[] {
+/**
+ * The TL;DR / Summary section (`section_summary`) is the one non-heading type
+ * that can put itself in the nav, as a Heading (h1 role) or Subheading (h2 role)
+ * under its own label. Deliberately special-cased by type rather than added to
+ * the registry: the nav-entry option is scoped to this section only.
+ */
+const SUMMARY_TYPE = "section_summary";
+
+export type SummaryNavLevel = "off" | "heading" | "subheading";
+
+function summaryNav(section: LoadedSection["section"]): { role: "h1" | "h2"; label: string } | null {
+  if (section.type !== SUMMARY_TYPE) return null;
+  const options = ("options" in section ? section.options : undefined) as
+    | { nav?: SummaryNavLevel; navLabel?: string }
+    | undefined;
+  const label = options?.navLabel?.trim() ?? "";
+  // The label is required while nav is on; without one there is nothing to show.
+  if (!label || (options?.nav !== "heading" && options?.nav !== "subheading")) return null;
+  return { role: options.nav === "heading" ? "h1" : "h2", label };
+}
+
+type RoleLookup = (type: string) => "h1" | "h2" | "h3" | undefined;
+
+function roleLookup(registry?: SectionRegistry): RoleLookup {
+  return (type) => (registry ? registry.getSection(type) : getSection(type))?.navRole;
+}
+
+/**
+ * Every anchor the page renders, aligned with `flat` (undefined = none).
+ *
+ * Headings render id={toSectionId(heading)} unconditionally (even when excluded
+ * from nav) and never move, so every native heading anchor is reserved first.
+ * Summary anchors are derived from the nav label, so they can collide with a
+ * heading's or another summary's: summaries claim theirs next, in document
+ * order, suffixing -2, -3… on collision. Copies a Reference pulled in
+ * (`referencedBy`) claim last — `<anchor>-<reference id>`, then -2, -3… — for
+ * their headings and nav-on summaries alike, so adding a Reference never moves
+ * an anchor the page already had. Keying on the Reference rather than a bare
+ * suffix keeps two References showing the same section apart, and keeps each
+ * copy's anchor stable when References are reordered.
+ *
+ * Positional rather than keyed by section id: a Reference repeats its sources'
+ * ids, so one page can hold the same section twice.
+ */
+function assignAnchors(flat: LoadedSection[], lookupRole: RoleLookup): (string | undefined)[] {
+  const anchors: (string | undefined)[] = new Array(flat.length);
+  const taken = new Set<string>();
+  const claim = (i: number, base: string) => {
+    let anchor = base;
+    for (let n = 2; taken.has(anchor); n++) anchor = `${base}-${n}`;
+    taken.add(anchor);
+    anchors[i] = anchor;
+  };
+  const headingOf = (section: LoadedSection["section"]) => {
+    const heading = (section.content as { heading?: string }).heading;
+    return heading && lookupRole(section.type) ? heading : undefined;
+  };
+
+  flat.forEach(({ section, referencedBy }, i) => {
+    const heading = headingOf(section);
+    if (referencedBy || !heading) return;
+    anchors[i] = toSectionId(heading);
+    taken.add(anchors[i]);
+  });
+  flat.forEach(({ section, referencedBy }, i) => {
+    const entry = summaryNav(section);
+    if (!referencedBy && entry) claim(i, toSectionId(entry.label));
+  });
+  flat.forEach(({ section, referencedBy }, i) => {
+    const text = summaryNav(section)?.label ?? headingOf(section);
+    if (referencedBy && text) claim(i, `${toSectionId(text)}-${toSectionId(referencedBy)}`);
+  });
+  return anchors;
+}
+
+function buildNavLinks(flat: LoadedSection[], lookupRole: RoleLookup, anchors: (string | undefined)[]): NavItem[] {
   const nav: NavItem[] = [];
   let currentParent: NavItem | null = null;
   let currentChild: NavItem | null = null;
 
-  const lookupRole = (type: string) => {
-    const def = registry ? registry.getSection(type) : getSection(type);
-    return def?.navRole;
-  };
-
-  for (const { section, meta } of flattenForNav(sections)) {
-    const content = section.content as { heading?: string; excludeFromNav?: boolean };
-    if (!content.heading) continue;
+  for (const [i, { section, meta }] of flat.entries()) {
+    let role: "h1" | "h2" | "h3" | undefined;
+    let label: string;
+    let excluded = false;
 
-    const role = lookupRole(section.type);
-    if (!role) continue;
+    const summary = summaryNav(section);
+    if (summary) {
+      role = summary.role;
+      label = summary.label;
+    } else {
+      const content = section.content as { heading?: string; excludeFromNav?: boolean };
+      if (!content.heading) continue;
+      role = lookupRole(section.type);
+      label = content.heading;
+      excluded = !!content.excludeFromNav;
+    }
+    const anchor = anchors[i];
+    if (!role || !anchor) continue;
 
     if (role === "h1") {
-      if (content.excludeFromNav) {
+      if (excluded) {
         currentParent = null;
         // Clear the child cursor too: leaving it pointing into the PREVIOUS
         // h1's subtree made an h3 following an excluded h1 nest under that
@@ -77,44 +158,123 @@ export function generateNavLinks(
         currentChild = null;
         continue;
       }
-      currentParent = {
-        href: `#${toSectionId(content.heading)}`,
-        label: content.heading,
-        status: meta.status,
-        children: [],
-      };
+      currentParent = { href: `#${anchor}`, label, status: meta.status, children: [] };
       currentChild = null;
       nav.push(currentParent);
     } else if (role === "h2") {
       // Same cursor reset as the excluded h1 above — an h3 under an excluded
       // h2 belongs nowhere, not under the preceding h2.
-      if (content.excludeFromNav) {
+      if (excluded) {
         currentChild = null;
         continue;
       }
       if (!currentParent) continue;
-      currentChild = {
-        href: `#${toSectionId(content.heading)}`,
-        label: content.heading,
-        status: meta.status,
-        children: [],
-      };
+      currentChild = { href: `#${anchor}`, label, status: meta.status, children: [] };
       currentParent.children.push(currentChild);
     } else if (role === "h3") {
-      if (content.excludeFromNav) continue;
+      if (excluded) continue;
       if (!currentChild) continue;
-      currentChild.children.push({
-        href: `#${toSectionId(content.heading)}`,
-        label: content.heading,
-        status: meta.status,
-        children: [],
-      });
+      currentChild.children.push({ href: `#${anchor}`, label, status: meta.status, children: [] });
     }
   }
 
   return nav;
 }
 
+export function generateNavLinks(
+  sections: LoadedSection[],
+  registry?: SectionRegistry,
+): NavItem[] {
+  const flat = flattenForNav(sections);
+  const lookupRole = roleLookup(registry);
+  return buildNavLinks(flat, lookupRole, assignAnchors(flat, lookupRole));
+}
+
+export interface SummaryNavAnchor {
+  anchor: string;
+  /** False for a Subheading with no Link Heading above it: it renders its
+   *  anchor but is dropped from the nav, so the editor hints about it. */
+  inNav: boolean;
+}
+
+/** Per summary section id (nav on, label set): the anchor it renders and
+ *  whether it made it into the nav. Same derivation generateNavLinks uses. */
+export function summaryNavAnchors(
+  sections: LoadedSection[],
+  registry?: SectionRegistry,
+): Record<string, SummaryNavAnchor> {
+  const flat = flattenForNav(sections);
+  const lookupRole = roleLookup(registry);
+  const anchors = assignAnchors(flat, lookupRole);
+  const hrefs = new Set<string>();
+  const collect = (items: NavItem[]) => items.forEach((i) => { hrefs.add(i.href); collect(i.children); });
+  collect(buildNavLinks(flat, lookupRole, anchors));
+  const out: Record<string, SummaryNavAnchor> = {};
+  flat.forEach(({ section, referencedBy }, i) => {
+    const anchor = anchors[i];
+    if (!referencedBy && anchor && summaryNav(section)) out[section.id] = { anchor, inNav: hrefs.has(`#${anchor}`) };
+  });
+  return out;
+}
+
+/**
+ * Render-only copy of the page's sections with `navAnchor` stamped on every
+ * section whose rendered anchor it cannot derive alone — nav-bearing summaries
+ * and everything a Reference pulled in (container children included) — for
+ * renderers that can't share React context with the page: the SSR viewer
+ * renders each section as its own React tree. Never written back: the editor
+ * reads summary anchors from SummaryAnchorsContext instead, so stored content
+ * stays clean.
+ *
+ * `navAnchor` is not part of any section schema: it survives only because the
+ * viewer's later passes (media resolve, sanitizeLoadedSections) spread sections.
+ * A Zod re-parse after this point would strip it and leave the section without
+ * the id its nav entry links to — stamp after any parse, never before.
+ */
+export function withNavAnchors(sections: LoadedSection[], registry?: SectionRegistry): LoadedSection[] {
+  const anchors = assignAnchors(flattenForNav(sections), roleLookup(registry));
+  // Walks in flattenForNav's order (each section, then its children), so the
+  // running position lines up with `anchors`.
+  let at = 0;
+  const stamp = (section: Section, referenced: boolean): Section => {
+    const anchor = anchors[at++];
+    const children = getContainerChildren(section);
+    let out = section;
+    if (children.length > 0) {
+      out = { ...out, content: { ...(out.content as object), children: children.map((c) => stamp(c, referenced)) } } as Section;
+    }
+    return anchor && (referenced || summaryNav(section)) ? ({ ...out, navAnchor: anchor } as Section) : out;
+  };
+  return sections.map((s) => ({ ...s, section: stamp(s.section, !!s.referencedBy) }));
+}
+
+/**
+ * Every copy the editor renders for each Reference on the page, keyed by
+ * Reference id then source id, with anchors stamped over the WHOLE page — so
+ * the editor nav (built from expandReferences) links to exactly these ids, and
+ * two References showing one section never share a DOM id. Copies the
+ * published site drops (drafts, archived pages) claim after the rest, so a
+ * greyed copy can't take an anchor a published one would have.
+ * Lives here rather than in references.ts because it needs withNavAnchors, and
+ * references.ts importing nav.ts would cycle.
+ */
+export function pageReferenceCopies(
+  pageSections: LoadedSection[],
+  opts: Omit<ReferenceQuery, "referenceId" | "content">,
+): Record<string, Record<string, Section>> {
+  const greyed = pageSections
+    .filter((s) => s.section.type === REFERENCE_TYPE)
+    .flatMap((r) =>
+      referenceItems({ ...opts, referenceId: r.section.id, content: r.section.content as unknown as ReferenceContent, audiences: [] })
+        .flatMap((i) => (i.source && i.excluded ? [{ ...i.source, referencedBy: r.section.id }] : [])),
+    );
+  const out: Record<string, Record<string, Section>> = {};
+  for (const s of withNavAnchors([...expandReferences(pageSections, { ...opts, audience: null }), ...greyed])) {
+    if (s.referencedBy) (out[s.referencedBy] ??= {})[s.section.id] = s.section;
+  }
+  return out;
+}
+
 export interface PageNavItem {
   id: string;
   title: string;

package/src/lib/platform-broker.ts

@@ -2,6 +2,10 @@ import { env } from "./env";
 
 const ATTEMPTS = 3;
 const RETRY_BASE_MS = 150;
+const REQUEST_TIMEOUT_MS = 10_000;
+// Gateway failures mean the request never reached a handler, so even a write
+// is safe to replay. A 500 may have failed after the write landed; it isn't.
+const GATEWAY_STATUSES = new Set([502, 503, 504]);
 
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -16,8 +20,8 @@ function sleep(ms: number): Promise<void> {
  * request never got a response at all.
  */
 export class PlatformBrokerError extends Error {
-  constructor(public readonly status: number | null, message: string) {
-    super(message);
+  constructor(public readonly status: number | null, message: string, options?: ErrorOptions) {
+    super(message, options);
     this.name = "PlatformBrokerError";
   }
 }
@@ -31,7 +35,9 @@ export function isPlatformMode(): boolean {
  * Call a platform broker endpoint scoped to this site. The platform authorizes
  * the op against the site that owns PLATFORM_API_KEY — the client never names
  * another tenant. Retries network/5xx (transient); 4xx is a real auth/config
- * error and is surfaced immediately. Mirrors fetchInstallationToken().
+ * error and is surfaced immediately. Writes are retried only on a gateway
+ * status: an unconfirmed write (timeout, dropped connection, 500) may already
+ * have landed. Mirrors fetchInstallationToken().
  */
 export async function platformBroker<T = unknown>(
   path: string,
@@ -52,15 +58,18 @@ export async function platformBroker<T = unknown>(
     serializedBody = JSON.stringify(opts.body);
   }
 
-  let lastError: unknown;
   for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
     const isLast = attempt === ATTEMPTS - 1;
     let res: Response;
     try {
-      res = await fetch(url, { method, headers, body: serializedBody });
+      res = await fetch(url, { method, headers, body: serializedBody, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
     } catch (err) {
-      lastError = err;
-      if (isLast) throw err;
+      // A timed-out write may already have landed. Do not automatically replay it.
+      if (method !== "GET" || isLast) {
+        throw new PlatformBrokerError(null, method === "GET"
+          ? "Platform request failed — check your connection and try again."
+          : "Platform request wasn't confirmed — check its status before trying again.", { cause: err });
+      }
       await sleep(RETRY_BASE_MS * 2 ** attempt);
       continue;
     }
@@ -68,14 +77,17 @@ export async function platformBroker<T = unknown>(
     if (res.ok) {
       if (res.status === 204) return undefined as T;
       try {
-        return (await res.json()) as T;
-      } catch {
-        return undefined as T;
+        // Some endpoints (e.g. bug-report's 201) succeed with an empty body.
+        const text = await res.text();
+        return (text ? JSON.parse(text) : undefined) as T;
+      } catch (err) {
+        throw new PlatformBrokerError(null, method === "GET"
+          ? "Platform response couldn't be read — try again."
+          : "Platform response couldn't be read — check the operation's status before trying again.", { cause: err });
       }
     }
 
-    if (res.status >= 500 && !isLast) {
-      lastError = new PlatformBrokerError(res.status, `Platform broker error (${res.status})`);
+    if (!isLast && (method === "GET" ? res.status >= 500 : GATEWAY_STATUSES.has(res.status))) {
       await sleep(RETRY_BASE_MS * 2 ** attempt);
       continue;
     }
@@ -83,7 +95,8 @@ export async function platformBroker<T = unknown>(
     throw new PlatformBrokerError(res.status, `Platform broker error (${res.status}): ${await res.text()}`);
   }
 
-  throw lastError instanceof Error ? lastError : new PlatformBrokerError(null, "Platform broker unreachable");
+  // Unreachable: every final attempt returns or throws above.
+  throw new PlatformBrokerError(null, "Platform broker unreachable");
 }
 
 /**
@@ -104,18 +117,23 @@ export async function platformBrokerStream(
   let lastError: unknown;
   for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
     let res: Response;
+    // Bound only connection establishment; an active LLM stream may take longer.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
     try {
       res = await fetch(url, {
+        signal: controller.signal,
         method: "POST",
         headers: { "x-api-key": apiKey, "x-site-id": siteId, "Content-Type": "application/json" },
         body: JSON.stringify(body),
       });
     } catch (err) {
       lastError = err;
+      if (controller.signal.aborted) throw new PlatformBrokerError(null, "Chat connection timed out — try again.");
       if (attempt === ATTEMPTS - 1) throw err;
       await sleep(RETRY_BASE_MS * 2 ** attempt);
       continue;
-    }
+    } finally { clearTimeout(timer); }
     if (!res.ok || !res.body) throw new Error(`Platform broker error (${res.status})`);
     return res.body;
   }

package/src/lib/reference-type.ts

@@ -0,0 +1,3 @@
+// A leaf of its own so modules that only need to recognise a Reference (drag
+// rules, container ops, save validation) don't import the resolution engine.
+export const REFERENCE_TYPE = "reference" as const;

package/src/lib/reference-validation.ts

@@ -0,0 +1,69 @@
+import type { SiteIndex } from "../schemas/site-config";
+import { REFERENCE_TYPE } from "./reference-type";
+
+/** What one Reference names that it can never show. */
+export interface ReferenceProblem {
+  referenceId: string;
+  unknownTagIds: string[];
+  /** Not a top-level section on any page: deleted, or a container's child. */
+  unplacedSectionIds: string[];
+  /** Picks that are themselves References, which are never shown. */
+  referencePickIds: string[];
+  picksItself: boolean;
+}
+
+const strings = (v: unknown): string[] =>
+  Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+
+/**
+ * The dangling-id check for Reference sections — what save_sections rejects on,
+ * and what validate_site and `authoring validate` warn about.
+ *
+ * Deliberately NOT part of applyContentWrite or the schema: on the viewer and in
+ * the editor a dangling pick or a deleted tag is ordinary (someone deleted the
+ * source), so it drops silently and an editor save must keep succeeding. This
+ * is for whoever just chose the ids, where a bad one is a mistake.
+ *
+ * `sections` are full section bodies; anything that is not a Reference (by body
+ * type or index type) is ignored. `tagIds` null means the registry could not
+ * be read whole, so tag ids go unchecked rather than being misreported.
+ */
+export function referenceProblems(
+  sections: readonly { id: string; content: unknown }[],
+  index: Pick<SiteIndex, "pages" | "sections">,
+  tagIds: ReadonlySet<string> | null,
+): ReferenceProblem[] {
+  const onPage = new Set(index.pages.flatMap((p) => p.order));
+  const problems: ReferenceProblem[] = [];
+  for (const { id, content } of sections) {
+    const body = content as { type?: unknown; content?: { tagIds?: unknown; sectionIds?: unknown } } | null;
+    if (body?.type !== REFERENCE_TYPE && index.sections[id]?.type !== REFERENCE_TYPE) continue;
+    const picks = strings(body?.content?.sectionIds).filter((pick) => pick !== id);
+    const problem: ReferenceProblem = {
+      referenceId: id,
+      unknownTagIds: tagIds ? strings(body?.content?.tagIds).filter((tag) => !tagIds.has(tag)) : [],
+      unplacedSectionIds: picks.filter((pick) => !onPage.has(pick)),
+      referencePickIds: picks.filter((pick) => onPage.has(pick) && index.sections[pick]?.type === REFERENCE_TYPE),
+      picksItself: strings(body?.content?.sectionIds).includes(id),
+    };
+    if (
+      problem.unknownTagIds.length || problem.unplacedSectionIds.length ||
+      problem.referencePickIds.length || problem.picksItself
+    ) problems.push(problem);
+  }
+  return problems;
+}
+
+/** One line per Reference, naming every bad id. */
+export function describeReferenceProblem(problem: ReferenceProblem): string {
+  const list = (ids: string[]) => ids.map((id) => `"${id}"`).join(", ");
+  const issues = [
+    ...(problem.unknownTagIds.length ? [`tagIds ${list(problem.unknownTagIds)} are not tags on this site`] : []),
+    ...(problem.unplacedSectionIds.length
+      ? [`sectionIds ${list(problem.unplacedSectionIds)} are not top-level sections on any page (a container's child cannot be picked — pick the container)`]
+      : []),
+    ...(problem.referencePickIds.length ? [`sectionIds ${list(problem.referencePickIds)} are References, which a Reference never shows`] : []),
+    ...(problem.picksItself ? ["sectionIds includes the Reference itself"] : []),
+  ];
+  return `Reference "${problem.referenceId}": ${issues.join("; ")}.`;
+}

package/src/lib/references.ts

@@ -0,0 +1,130 @@
+import type { LoadedSection } from "./loader";
+import type { Page, SiteIndex } from "../schemas/site-config";
+import { audiencePasses } from "./pages";
+import { pagesInNavOrder } from "./nav-tree";
+import { siteTags } from "./tags";
+import { REFERENCE_TYPE } from "./reference-type";
+
+export { REFERENCE_TYPE };
+
+export interface ReferenceContent {
+  tagIds: string[];
+  sectionIds: string[];
+}
+
+/** Why the published site leaves a referenced section out entirely. */
+export type ReferenceExclusion =
+  /** Deleted, its file failed to load, or not a top-level section. */
+  | "missing"
+  /** Another Reference — never nested. */
+  | "reference"
+  | "archived-page"
+  /** A draft or archived section. */
+  | "not-live";
+
+/** What a Reference is resolved against. */
+export interface ReferenceQuery {
+  referenceId: string;
+  content: ReferenceContent;
+  index: SiteIndex;
+  allSections: LoadedSection[];
+}
+
+export interface ReferenceItem {
+  sectionId: string;
+  /** The page the section sits on; null when it is on none (deleted, or an
+   *  id that was never a top-level section). */
+  page: Page | null;
+  source: LoadedSection | null;
+  excluded: ReferenceExclusion | null;
+  /** Of the audiences asked about, those who can't see it on its own page.
+   *  Always empty for an excluded item. */
+  hiddenFrom: string[];
+}
+
+/**
+ * Everything a Reference points at, as the editor lists it: in site order,
+ * with what the viewer would silently drop kept and marked `excluded`, and
+ * with `hiddenFrom` naming which of `audiences` its source page and section
+ * keep it from. Picks that are on no page trail, in stored order. Only the
+ * Reference itself is left out. resolveReference is this list filtered, so
+ * the two can never disagree about what a Reference shows.
+ */
+export function referenceItems(opts: ReferenceQuery & { audiences: string[] }): ReferenceItem[] {
+  const { referenceId, content, index, allSections, audiences } = opts;
+
+  const wanted = new Set(content.sectionIds);
+  const tagIds = new Set(content.tagIds);
+  for (const tag of siteTags(index)) {
+    if (tagIds.has(tag.id)) for (const id of tag.sectionIds) wanted.add(id);
+  }
+  wanted.delete(referenceId);
+  if (wanted.size === 0) return [];
+
+  const byId = new Map(allSections.map((s) => [s.section.id, s]));
+  const item = (sectionId: string, page: Page | null): ReferenceItem => {
+    const source = byId.get(sectionId) ?? null;
+    const excluded: ReferenceExclusion | null =
+      !source || !page ? "missing"
+      : source.section.type === REFERENCE_TYPE ? "reference"
+      : page.status !== "live" ? "archived-page"
+      : source.meta.status !== "live" ? "not-live"
+      : null;
+    const hiddenFrom = excluded || !source || !page ? [] : audiences.filter(
+      (a) => !audiencePasses(page.access, a) || !audiencePasses(source.meta.access, a),
+    );
+    return { sectionId, page, source, excluded, hiddenFrom };
+  };
+
+  const items: ReferenceItem[] = [];
+  const placed = new Set<string>();
+  for (const page of pagesInNavOrder(index)) {
+    for (const id of page.order) {
+      if (!wanted.has(id)) continue;
+      items.push(item(id, page));
+      placed.add(id);
+    }
+  }
+  for (const id of wanted) if (!placed.has(id)) items.push(item(id, null));
+  return items;
+}
+
+/**
+ * The sections a Reference shows: the union of its tagged and picked sections,
+ * resolved against the content it is given (the published content, on every
+ * viewer path) in site order — pages in nav order, then position on the page.
+ *
+ * A Reference stores pointers rather than copies because the index puts each
+ * section id on exactly one page. Resolving them is where every exposure rule
+ * lives, so a Reference can never widen what a viewer sees:
+ *  - an item must pass its SOURCE page's access and its source section's access
+ *    for `audience` (the viewer has already passed the referencing page's and
+ *    the Reference's own, so the result is the intersection of all four);
+ *  - only live sections on live pages — hidden (not-in-nav) pages count,
+ *    archived ones do not;
+ *  - References in the source set are skipped, the Reference itself included,
+ *    so there are no cycles. Containers come whole, children and all.
+ * Dangling picks and deleted tags drop silently. Items are the source entries
+ * marked with `referencedBy`, which is what gives their anchors the
+ * `-<reference id>` suffix (lib/nav.ts).
+ */
+export function resolveReference(opts: ReferenceQuery & { audience: string | null }): LoadedSection[] {
+  const { audience, ...rest } = opts;
+  return referenceItems({ ...rest, audiences: audience === null ? [] : [audience] }).flatMap((i) =>
+    i.source && !i.excluded && i.hiddenFrom.length === 0 ? [{ ...i.source, referencedBy: opts.referenceId }] : [],
+  );
+}
+
+/** A page's sections with each Reference replaced, in place, by the copies it
+ *  shows `audience` — what the viewer renders and what the page nav is built
+ *  from, on both the viewer and the editor. */
+export function expandReferences(
+  pageSections: LoadedSection[],
+  opts: Omit<ReferenceQuery, "referenceId" | "content"> & { audience: string | null },
+): LoadedSection[] {
+  return pageSections.flatMap((s) =>
+    s.section.type === REFERENCE_TYPE
+      ? resolveReference({ ...opts, referenceId: s.section.id, content: s.section.content as unknown as ReferenceContent })
+      : [s],
+  );
+}

package/src/lib/registry.ts

@@ -2,7 +2,9 @@ import type { ZodType, z } from "zod";
 import type { ComponentType, ReactNode } from "react";
 import type { Audience } from "../schemas/auth";
 import type { LinkValue } from "../schemas/link";
+import type { ImageBackground } from "../schemas/shared";
 import type { SectionContent } from "../schemas/sections";
+import type { TagEntry } from "../schemas/tags";
 import type { VideoSource } from "../components/sections/Video/VideoBlock";
 
 // --- Settings field types ---
@@ -71,6 +73,16 @@ export type SettingsFieldDef =
       label: string;
       default: { documentId: string };
       target?: "content" | "options";
+    }
+  | {
+      /** Per-placement backdrop behind an image (ImageBackgroundField). Leave
+       *  `default` unset: an absent value is "None" and must stay absent on save. */
+      type: "image-background";
+      label: string;
+      default?: ImageBackground;
+      target?: "content" | "options";
+      /** Hide the field for the current values (e.g. when the ref is a video). */
+      hidden?: (values: Record<string, unknown>) => boolean;
     };
 
 export type SettingsSchema = Record<string, SettingsFieldDef>;
@@ -105,6 +117,20 @@ export interface SectionProps<T = unknown> {
   onDelete?: () => void;
 }
 
+/** The site's tag registry and its edits, as the editor shell hands them to
+ *  the canvas and Site settings. */
+export interface SiteTagging {
+  /** Already reconciled (siteTags). */
+  tags: TagEntry[];
+  /** False when the registry was never loaded or loaded degraded: a save would
+   *  wholesale-replace tags.json with what this session couldn't fully read. */
+  editable: boolean;
+  onCreate: (label: string, sectionId?: string) => void;
+  onRename: (tagId: string, label: string) => void;
+  onDelete: (tagId: string) => void;
+  onToggle: (sectionId: string, tagId: string, tagged: boolean) => void;
+}
+
 export interface WrapperProps {
   sectionId: string;
   sectionType: string;
@@ -112,6 +138,8 @@ export interface WrapperProps {
   dirty?: boolean;
   index: number;
   isLast: boolean;
+  /** Total sections on the page — Move up/down's "N of M" and end-disabling. */
+  sectionCount?: number;
   containerId: string;
   isContainerBlock: boolean;
   definition: SectionDefinition;
@@ -119,6 +147,15 @@ export interface WrapperProps {
   audiences: Audience[];
   access: string[];
   onAccessChange?: (access: string[]) => void;
+  /** Section tags (the tags.json sidecar). Only root sections get a
+   *  SectionWrapper — container children are not index sections and cannot be
+   *  tagged. Absent handlers make the Tags pill read-only. */
+  tagging: {
+    tags: TagEntry[];
+    assignedIds: string[];
+    onToggle?: (tagId: string, tagged: boolean) => void;
+    onCreate?: (label: string) => void;
+  };
   onStatusChange?: (status: "draft" | "live" | "archived") => void;
   onSectionChange?: (options: Record<string, unknown>) => void;
   onReorder?: (fromIndex: number, toIndex: number) => void;