@unitninety/site-kit 1.6.2 → 1.6.4

package/src/elements/define.ts

@@ -80,7 +80,7 @@ export type ExpandCtx = {
   /** The Single's read value, already expanded by the caller. */
   single(key: string): unknown
   entry(collection: string, id: Id, depth: number): EntryRead
-  query(collection: string, query: unknown): { entries: EntryRead[]; total: number }
+  query(collection: string, query: unknown): { entries: EntryRead[]; total: number; matches?: Id[] }
   inverse(collection: string, field: string, id: Id): EntryRead[]
 }
 export type SeedCtx = {
@@ -101,7 +101,9 @@ export type LeafDecl = {
   required?: boolean
   /** Seed shape. */
   default?: unknown
-  /** Sub-paths a client may not change, e.g. `['to']` on a link. */
+  /** Sub-paths a client may not change, e.g. `['to']` on a link. `['$']` fixes the whole
+   * value (including an absent value) on retained fields and omits its editor. Initial
+   * document seeding and new repeated items may initialise their values. */
   lock?: string[]
   renamedFrom?: string
   options?: Record<string, unknown>
@@ -112,12 +114,29 @@ export type ZoneDecl = { container: 'u90/zone'; label?: string; allow: string[];
 export type FieldDecl = LeafDecl | GroupDecl | ListDecl | ZoneDecl
 export const isLeaf = (d: FieldDecl): d is LeafDecl => 'element' in d
 
-export type BlockDecl = { name: string; label: string; fields: Record<string, FieldDecl>; entry?: string; order?: string[] }
+export type BlockDecl = { name: string; label: string; fields: Record<string, FieldDecl>; entry?: string; order?: string[]; shared?: { single: string; field: string; previewFields?: string[] } }
+/** Pinned content shown before or after a collection entry's editable page sections. */
+export type CollectionAuthoringAnchor = { label: string; fields: string[] } | { label: string; single: string }
+export type CollectionAuthoringSections = {
+  /** The collection template's sole fixed block, whose entry is this collection. */
+  block: string
+  /** A direct zone field on the wrapper; other fields must be whole-value-locked leaves. */
+  field: string
+  before?: CollectionAuthoringAnchor[]
+  after?: CollectionAuthoringAnchor[]
+}
+export type CollectionAuthoring = {
+  /** Concise creation form; omitted collections keep title-only creation. */
+  create?: { fields: string[] }
+  /** Exposes the wrapper's zone as page sections, with optional pinned content. */
+  sections?: CollectionAuthoringSections
+}
 export type CollectionDecl = {
   name: string
   label: string
   fields: Record<string, FieldDecl>
   template?: ZoneDecl
+  authoring?: CollectionAuthoring
   defaultSort?: { field: string; dir: 'asc' | 'desc' } | 'manual'
   order?: string[]
 }

package/src/elements/jsonSchema.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { isLeaf, type FieldDecl, type Schema } from './define'
+import { isLeaf, SLOT, type FieldDecl, type Schema } from './define'
 import { orderedEntries } from './order'
 import { ID_RE } from './path'
 import { getElement } from './registry'
@@ -29,8 +29,9 @@ export function toJSONSchema(decl: FieldDecl, schema?: Schema): JsonSchema {
   }
   const blocks = decl.allow.map((name) => {
     const block = schema?.blocks[name]
-    const fields = block ? (toJSONSchema({ container: 'u90/group', fields: block.fields, order: block.order }, schema).properties as object) : {}
-    return { type: 'object', properties: { _id: id, _block: { const: name }, ...fields }, required: ['_id', '_block'], additionalProperties: false }
+    const fields = block ? (toJSONSchema({ container: 'u90/group', fields: block.fields, order: block.order }, schema).properties as Record<string, JsonSchema>) : {}
+    if (block?.shared) fields[block.shared.field] = { oneOf: [{ type: 'null', description: 'Use the shared content.' }, fields[block.shared.field]] }
+    return { type: 'object', properties: { _id: id, _block: { const: name }, ...(!decl.fixed && name !== SLOT ? { _hidden: { type: 'boolean' } } : {}), ...fields }, required: ['_id', '_block'], additionalProperties: false }
   })
   return { type: 'array', items: { oneOf: blocks } }
 }

package/src/elements/leaves/link.ts

@@ -3,12 +3,13 @@ import { Id, TEL_RE, URL_RE, defineElement, requiredIssue, type ExpandCtx, type
 import { isDocumentId } from '../ids'
 
 const ANCHOR = z.string().regex(/^[A-Za-z][\w-]*$/)
-const KINDS = ['page', 'entry', 'url', 'email', 'tel'] as const
+const KINDS = ['page', 'entry', 'file', 'url', 'email', 'tel'] as const
 export type LinkKind = (typeof KINDS)[number]
 
 export const LinkTo = z.union([
   z.strictObject({ page: Id, anchor: ANCHOR.optional() }),
   z.strictObject({ entry: z.strictObject({ collection: z.string().min(1), id: Id }) }),
+  z.strictObject({ file: Id }),
   z.strictObject({ url: z.string().regex(URL_RE, 'Expected an absolute URL or a root-relative path.') }),
   z.strictObject({ email: z.email() }),
   z.strictObject({ tel: z.string().regex(TEL_RE, 'Expected a phone number.') }),
@@ -19,6 +20,7 @@ const LinkToSeed = z.union([
   z.strictObject({ page: z.union([Id, z.string().min(1)]), anchor: ANCHOR.optional() }),
   z.strictObject({ entry: z.strictObject({ collection: z.string().min(1), key: z.string().min(1) }) }),
   z.strictObject({ entry: z.strictObject({ collection: z.string().min(1), id: Id }) }),
+  z.strictObject({ file: z.union([Id, z.strictObject({ source: z.string().trim().min(1) })]) }),
   z.strictObject({ url: z.string().regex(URL_RE) }),
   z.strictObject({ email: z.email() }),
   z.strictObject({ tel: z.string().regex(TEL_RE) }),
@@ -71,7 +73,7 @@ export const withDraftLocale = (href: string, locale: string): string => {
 /** In draft with a `draftLocale`, an internal href keeps the language; every other href, and every href outside draft, is unchanged. */
 export const hrefOf = (to: LinkTo | null, ctx: ExpandCtx): { href: string | null; status: 'ready' | 'missing' } => {
   const r = targetOf(to, ctx)
-  return ctx.draftLocale && r.href && internal(r.href) ? { ...r, href: withDraftLocale(r.href, ctx.draftLocale) } : r
+  return ctx.draftLocale && r.href && !(to && 'file' in to) && internal(r.href) ? { ...r, href: withDraftLocale(r.href, ctx.draftLocale) } : r
 }
 const targetOf = (to: LinkTo | null, ctx: ExpandCtx): { href: string | null; status: 'ready' | 'missing' } => {
   if (!to) return { href: null, status: 'ready' }
@@ -83,6 +85,13 @@ const targetOf = (to: LinkTo | null, ctx: ExpandCtx): { href: string | null; sta
     const e = ctx.entry(to.entry.collection, to.entry.id, 0)
     return e.status === 'ready' && e.route ? { href: e.route, status: 'ready' } : { href: null, status: 'missing' }
   }
+  if ('file' in to) {
+    const media = ctx.media(to.file)
+    // Visibility is enforced by the platform's reference checks and media route. A resolver
+    // carrying additional visibility metadata must never turn a private file into a link.
+    const privateFile = media && 'visibility' in media && media.visibility === 'private'
+    return media?.url && !privateFile ? { href: media.url, status: 'ready' } : { href: null, status: 'missing' }
+  }
   if ('url' in to) return { href: to.url, status: 'ready' }
   if ('email' in to) return { href: `mailto:${to.email}`, status: 'ready' }
   return { href: `tel:${to.tel.replace(/[^+\d]/g, '')}`, status: 'ready' }
@@ -100,6 +109,10 @@ const isUnresolvedSeedRef = (to: SeedTo | null): boolean =>
 
 const expandSeed = (s: SeedValue, o: O, ctx: ExpandCtx): LinkRead => {
   if (s === null) return null
+  if (s.to && 'file' in s.to && typeof s.to.file === 'object') {
+    const source = s.to.file.source
+    return { label: s.label, href: source, newTab: s.newTab, to: { file: source }, status: 'ready', ...(ctx.draft ? { $path: ctx.at } : {}) }
+  }
   if (isUnresolvedSeedRef(s.to)) return { label: s.label, href: null, newTab: s.newTab, to: null, status: 'missing', ...(ctx.draft ? { $path: ctx.at } : {}) }
   return expand({ label: s.label, to: s.to as LinkTo | null, newTab: s.newTab }, o, ctx)
 }
@@ -124,6 +137,7 @@ export const link = defineElement({
     if (!v?.to) return []
     if ('page' in v.to) return [{ kind: 'page', id: v.to.page }]
     if ('entry' in v.to) return [{ kind: 'entry', collection: v.to.entry.collection, id: v.to.entry.id, depth: 0 }]
+    if ('file' in v.to) return [{ kind: 'media', id: v.to.file }]
     return []
   },
   toStored: async (s, _o, ctx: SeedCtx) => {
@@ -131,6 +145,7 @@ export const link = defineElement({
     let to: LinkTo | null = null
     if (s.to && 'page' in s.to) to = { page: typeof s.to.page === 'string' && !isDocumentId(s.to.page) ? ctx.resolvePage(s.to.page) : s.to.page, ...(s.to.anchor ? { anchor: s.to.anchor } : {}) }
     else if (s.to && 'entry' in s.to) to = { entry: { collection: s.to.entry.collection, id: 'key' in s.to.entry ? ctx.resolveEntry(s.to.entry.collection, s.to.entry.key) : s.to.entry.id } }
+    else if (s.to && 'file' in s.to) to = { file: typeof s.to.file === 'object' ? await ctx.importAsset(s.to.file.source) : s.to.file }
     else to = s.to
     return { label: s.label, to, newTab: s.newTab }
   },

package/src/elements/leaves/query.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import { Id, defineElement, type ExpandCtx, type Ref } from '../define'
 import { ELEMENT_IDS, type ElementId } from '../ids'
+import { ReferencePreviewFields } from './relation'
 import { EntriesReadSchema, type EntriesRead } from './selection'
 
 export const FILTERABLE: readonly ElementId[] = ['u90/choice', 'u90/boolean', 'u90/relation', 'u90/date', 'u90/number']
@@ -9,6 +10,7 @@ const OPS = ['eq', 'neq', 'in', 'not-in', 'is-set'] as const
 
 export const QueryOptions = z.strictObject({
   to: z.string().min(1),
+  previewFields: ReferencePreviewFields,
   /** field → element of the target collection; filled in by validateSchema from the CollectionDecl. */
   targetFields: z.record(z.string(), z.enum(ELEMENT_IDS)).optional(),
 })
@@ -77,7 +79,10 @@ const stored = (o: O) =>
         ctx.addIssue({ code: 'custom', path: [k], message: 'Each entry may be listed once.', params: { code: 'duplicate' } })
     }
   })
-const expand = (v: QueryStored, o: O, ctx: ExpandCtx): EntriesRead => ({ ...ctx.query(o.to, v), ...(ctx.draft ? { $path: ctx.at, $pins: (v.pin ?? []).map(String) } : {}) })
+const expand = (v: QueryStored, o: O, ctx: ExpandCtx): EntriesRead => {
+  const { matches, ...read } = ctx.query(o.to, v)
+  return { ...read, ...(ctx.draft ? { $path: ctx.at, $pins: (v.pin ?? []).map(String), ...(matches ? { $query: { matches, where: v.where ?? [], sort: v.sort ?? null, limit: v.limit ?? null } } : {}) } : {}) }
+}
 
 export const query = defineElement({
   id: 'u90/query',

package/src/elements/leaves/relation.ts

@@ -11,9 +11,12 @@ export const uniqueIds = (ids: unknown[], ctx: z.RefinementCtx) => {
     ctx.addIssue({ code: 'custom', message: 'Each entry may be referenced once.', params: { code: 'duplicate' } })
 }
 
+export const ReferencePreviewFields = z.array(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/)).min(1).max(20).refine(fields => new Set(fields).size === fields.length, 'Preview fields must be unique').optional()
+
 export const RelationOptions = z
   .strictObject({
     to: z.string().min(1),
+    previewFields: ReferencePreviewFields,
     cardinality: z.enum(['many-to-one', 'one-to-one', 'many-to-many', 'one-to-many']),
     inverseOf: z.string().min(1).optional(),
     depth: z.int().min(0).max(3).default(1),

package/src/elements/leaves/rich-text.ts

@@ -20,15 +20,16 @@ type O = z.infer<typeof RichTextOptions>
 const common = { direction: z.enum(['ltr', 'rtl']).nullable().default('ltr'), format: z.string().default(''), indent: z.int().default(0), version: z.int().default(1) }
 const TextNode = z.object({ type: z.literal('text'), text: z.string(), format: z.int().nonnegative().default(0), detail: z.int().default(0), mode: z.string().default('normal'), style: z.string().default('') , version: z.int().default(1) })
 const LineBreak = z.object({ type: z.literal('linebreak'), version: z.int().default(1) })
-const LinkNode = z.object({ type: z.literal('link'), fields: z.object({ to: LinkTo, newTab: z.boolean().default(false) }), children: z.array(z.union([TextNode, LineBreak])), ...common })
-const inlines = (o: O) => z.array(o.marks.includes('link') ? z.union([TextNode, LineBreak, LinkNode]) : z.union([TextNode, LineBreak]))
-const Paragraph = (o: O) => z.object({ type: z.literal('paragraph'), children: inlines(o), textFormat: z.int().default(0), ...common })
-const Heading = (o: O) => z.object({ type: z.literal('heading'), tag: z.enum(o.headings as [string, ...string[]]), children: inlines(o), ...common })
-const Quote = (o: O) => z.object({ type: z.literal('quote'), children: inlines(o), ...common })
-const ListItem = (o: O) => z.object({ type: z.literal('listitem'), children: inlines(o), value: z.int().default(1), ...common })
-const List = (o: O) => z.object({ type: z.literal('list'), listType: z.enum(['bullet', 'number']), tag: z.enum(['ul', 'ol']), start: z.int().default(1), children: z.array(ListItem(o)), ...common })
-const blockSchemas = (o: O) => {
-  const by = { paragraph: Paragraph(o), heading: Heading(o), list: List(o), quote: Quote(o) }
+const FileSeedTo = z.strictObject({ file: z.strictObject({ source: z.string().trim().min(1) }) })
+const LinkNode = (seed = false) => z.object({ type: z.literal('link'), fields: z.object({ to: seed ? z.union([LinkTo, FileSeedTo]) : LinkTo, newTab: z.boolean().default(false) }), children: z.array(z.union([TextNode, LineBreak])), ...common })
+const inlines = (o: O, seed = false) => z.array(o.marks.includes('link') ? z.union([TextNode, LineBreak, LinkNode(seed)]) : z.union([TextNode, LineBreak]))
+const Paragraph = (o: O, seed = false) => z.object({ type: z.literal('paragraph'), children: inlines(o, seed), textFormat: z.int().default(0), ...common })
+const Heading = (o: O, seed = false) => z.object({ type: z.literal('heading'), tag: z.enum(o.headings as [string, ...string[]]), children: inlines(o, seed), ...common })
+const Quote = (o: O, seed = false) => z.object({ type: z.literal('quote'), children: inlines(o, seed), ...common })
+const ListItem = (o: O, seed = false) => z.object({ type: z.literal('listitem'), children: inlines(o, seed), value: z.int().default(1), ...common })
+const List = (o: O, seed = false) => z.object({ type: z.literal('list'), listType: z.enum(['bullet', 'number']), tag: z.enum(['ul', 'ol']), start: z.int().default(1), children: z.array(ListItem(o, seed)), ...common })
+const blockSchemas = (o: O, seed = false) => {
+  const by = { paragraph: Paragraph(o, seed), heading: Heading(o, seed), list: List(o, seed), quote: Quote(o, seed) }
   const chosen = o.blocks.map((b) => by[b])
   return chosen.length === 1 ? chosen[0] : z.union(chosen as z.ZodTypeAny[] as [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]])
 }
@@ -44,9 +45,9 @@ const eachLink = (node: Node, f: (n: Node) => void) => {
   node.children?.forEach((c) => eachLink(c, f))
 }
 
-const stored = (o: O) =>
+const stored = (o: O, seed = false) =>
   z
-    .object({ root: z.object({ type: z.literal('root'), children: z.array(blockSchemas(o)), ...common }) })
+    .object({ root: z.object({ type: z.literal('root'), children: z.array(blockSchemas(o, seed)), ...common }) })
     .superRefine((v, ctx) => {
       const root = v.root as unknown as Node
       if (o.inline && (root.children!.length !== 1 || root.children![0].type !== 'paragraph'))
@@ -70,10 +71,16 @@ export const richTextToPlain = (v: Stored): string =>
   v ? (v.root.children as unknown as Node[]).map((b) => { const parts: string[] = []; eachText(b, [], (n) => parts.push(n.text ?? '')); return parts.join('') }).join('\n') : ''
 
 export type RichTextRead = ({ root: unknown; $path?: string }) | null
-const expand = (v: Stored, o: O, ctx: ExpandCtx): RichTextRead => {
+const expand = (v: Stored, o: O, ctx: ExpandCtx, seed = false): RichTextRead => {
   if (v === null) return null
   const root = structuredClone(v.root) as unknown as Node
-  eachLink(root, (n) => { const fields = n.fields as { to: z.infer<typeof LinkTo> }; Object.assign(fields, hrefOf(fields.to, ctx)) })
+  eachLink(root, (n) => {
+    const fields = n.fields as { to: z.infer<typeof LinkTo> | z.infer<typeof FileSeedTo> }
+    if (seed && 'file' in fields.to && typeof fields.to.file === 'object') {
+      const source = fields.to.file.source
+      Object.assign(fields, { to: { file: source }, href: source, status: 'ready' })
+    } else Object.assign(fields, hrefOf(fields.to as z.infer<typeof LinkTo>, ctx))
+  })
   const split = (node: Node) => {
     if (!node.children) return
     node.children.forEach(split)
@@ -118,7 +125,7 @@ export const richText = defineElement({
   label: 'Rich text',
   placement: 'any',
   options: RichTextOptions,
-  seed: stored,
+  seed: (o) => stored(o, true),
   stored,
   shape: () => SHAPE,
   read: () => z.object({ root: z.unknown(), $path: z.string().optional() }).nullable(),
@@ -132,12 +139,21 @@ export const richText = defineElement({
       const to = (n.fields as { to: z.infer<typeof LinkTo> }).to
       if ('page' in to) refs.push({ kind: 'page', id: to.page })
       else if ('entry' in to) refs.push({ kind: 'entry', collection: to.entry.collection, id: to.entry.id, depth: 0 })
+      else if ('file' in to) refs.push({ kind: 'media', id: to.file })
     })
     return refs
   },
-  toStored: async (seed) => seed,
+  toStored: async (seed, _o, ctx) => {
+    if (seed === null) return null
+    const copy = structuredClone(seed)
+    await Promise.all(linkNodes(copy).map(async (node) => {
+      const fields = node.fields as { to: z.infer<typeof LinkTo> | z.infer<typeof FileSeedTo> }
+      if ('file' in fields.to && typeof fields.to.file === 'object') fields.to = { file: await ctx.importAsset(fields.to.file.source) }
+    }))
+    return copy
+  },
   expand,
-  expandSeed: expand,
+  expandSeed: (s, o, ctx) => expand(s, o, ctx, true),
   toText: richTextToPlain,
   translatable: (v) => {
     const out: { path: (string | number)[]; value: string }[] = []

package/src/elements/leaves/selection.ts

@@ -1,12 +1,13 @@
 import { z, type ZodType } from 'zod'
 import { EntryReadSchema, Id, defineElement, requiredIssue, type EntryRead, type ExpandCtx, type Ref } from '../define'
-import { EntryRef, resolveEntryRef, uniqueIds } from './relation'
+import { EntryRef, ReferencePreviewFields, resolveEntryRef, uniqueIds } from './relation'
 
-export const SelectionOptions = z.strictObject({ to: z.string().min(1), many: z.boolean().default(false), max: z.int().positive().optional(), depth: z.int().min(0).max(3).default(1) })
+export const SelectionOptions = z.strictObject({ to: z.string().min(1), many: z.boolean().default(false), max: z.int().positive().optional(), depth: z.int().min(0).max(3).default(1), previewFields: ReferencePreviewFields })
 type O = z.infer<typeof SelectionOptions>
 /** How a selection and a query read: the entries in order, how many there are, and `$path` in draft. */
-export type EntriesRead = { entries: EntryRead[]; total: number; $path?: string; $pins?: string[] }
-export const EntriesReadSchema = z.object({ entries: z.array(EntryReadSchema), total: z.number(), $path: z.string().optional(), $pins: z.array(z.string()).optional() })
+export type QueryBaseline = { matches: (string | number)[]; where: unknown[]; sort: unknown; limit: number | null }
+export type EntriesRead = { entries: EntryRead[]; total: number; $path?: string; $pins?: string[]; $query?: QueryBaseline }
+export const EntriesReadSchema = z.object({ entries: z.array(EntryReadSchema), total: z.number(), $path: z.string().optional(), $pins: z.array(z.string()).optional(), $query: z.object({ matches: z.array(Id), where: z.array(z.unknown()), sort: z.unknown(), limit: z.number().nullable() }).optional() })
 
 const stored = (o: O) => (o.many ? (o.max ? z.array(Id).max(o.max) : z.array(Id)).superRefine(uniqueIds) : Id.nullable())
 type SeedValue = z.infer<typeof EntryRef> | z.infer<typeof EntryRef>[] | null

package/src/elements/ops/expand.ts

@@ -11,7 +11,7 @@ export type Resolved = {
   /** Singles already expanded to their read values by the caller. */
   singles?: Map<string, unknown>
   entries?: Map<string, EntryRecord>
-  queries?: Map<string, { ids: Id[]; total: number }>
+  queries?: Map<string, { ids: Id[]; total: number; matches?: Id[] }>
   inverses?: Map<string, Id[]>
 }
 export const entryKey = (collection: string, id: Id) => `${collection}:${id}`
@@ -40,7 +40,7 @@ export function makeCtx(schema: Schema, r: Resolved, at: string, draft: boolean,
     },
     query: (collection, q) => {
       const hit = r.queries?.get(queryKey(collection, q))
-      return hit ? { entries: hit.ids.map((id) => ctx.entry(collection, id, 1)), total: hit.total } : { entries: [], total: 0 }
+      return hit ? { entries: hit.ids.map((id) => ctx.entry(collection, id, 1)), total: hit.total, ...(draft && hit.matches ? { matches: hit.matches } : {}) } : { entries: [], total: 0 }
     },
     inverse: (collection, field, id) => (r.inverses?.get(inverseKey(collection, field, id)) ?? []).map((x) => ctx.entry(collection, x, 1)),
   }
@@ -61,8 +61,9 @@ export function expandField(schema: Schema, decl: FieldDecl, value: unknown, ctx
     if (decl.container === 'u90/list') return isLeaf(decl.item) ? inner : { _id: c.key, ...(ctx.draft ? { $path: path.child(ctx.at, c.key) } : {}), ...(inner as object) }
     const item = items[i]
     const block = record(item) ? String(item._block) : ''
-    if (block === SLOT || !Object.hasOwn(schema.blocks, block)) return { _id: c.key, _block: block }
-    return { _id: c.key, _block: block, ...(ctx.draft ? { $path: path.child(ctx.at, c.key) } : {}), ...(inner as object) }
+    const metadata = record(item) && typeof item._hidden === 'boolean' ? { _hidden: item._hidden } : {}
+    if (block === SLOT || !Object.hasOwn(schema.blocks, block)) return { _id: c.key, _block: block, ...metadata }
+    return { _id: c.key, _block: block, ...metadata, ...(ctx.draft ? { $path: path.child(ctx.at, c.key) } : {}), ...(inner as object) }
   })
 }
 

package/src/elements/ops/seed.ts

@@ -4,6 +4,7 @@ import { zodIssues } from '../leaf'
 import { path } from '../path'
 import { CURRENT_CONTRACT, getElement } from '../registry'
 import { record } from '../containers/group'
+import { blockFields } from '../containers/zone'
 import { orderedEntries } from '../order'
 
 export class SeedError extends Error {
@@ -19,6 +20,16 @@ const collector = () => {
   return { failures, fail }
 }
 
+/** Shared admission rules: visibility belongs only to block instances in non-fixed zones. */
+const visibilityIssues = (item: unknown, zone?: ZoneDecl): { code: string; message: string }[] => {
+  if (!record(item) || !Object.hasOwn(item, '_hidden')) return []
+  const issues: { code: string; message: string }[] = []
+  if (typeof item._hidden !== 'boolean') issues.push({ code: 'invalid_type', message: 'Block visibility must be a boolean.' })
+  if (!zone || item._block === SLOT) issues.push({ code: 'invalid-visibility', message: 'Only zone blocks can have visibility metadata.' })
+  else if (zone.fixed) issues.push({ code: 'fixed-visibility', message: 'Fixed blocks cannot have visibility metadata.' })
+  return issues
+}
+
 /** One declared field's stored value, from an explicit seed value or its declared default. */
 async function seedField(schema: Schema, decl: FieldDecl, v: unknown, ctx: SeedCtx, here: string, fail: Fail): Promise<unknown> {
   if (isLeaf(decl)) {
@@ -32,6 +43,7 @@ async function seedField(schema: Schema, decl: FieldDecl, v: unknown, ctx: SeedC
   }
   if (decl.container === 'u90/group') {
     const src = record(v) ? v : {}
+    visibilityIssues(src).forEach(i => fail(path.child(here, '_hidden'), i.message))
     const out: Record<string, unknown> = {}
     for (const [name, f] of orderedEntries(decl.fields, decl.order)) out[name] = await seedField(schema, f, src[name], ctx, path.child(here, name), fail)
     return out
@@ -50,18 +62,20 @@ async function seedField(schema: Schema, decl: FieldDecl, v: unknown, ctx: SeedC
 }
 async function seedListItem(schema: Schema, decl: ListDecl, item: unknown, ctx: SeedCtx, here: string, fail: Fail): Promise<Record<string, unknown>> {
   const _id = ctx.newId()
+  if (isLeaf(decl.item)) visibilityIssues(item).forEach(i => fail(path.child(here, _id, '_hidden'), i.message))
   const inner = await seedField(schema, decl.item, item, ctx, path.child(here, _id), fail)
   return isLeaf(decl.item) ? { _id, _value: inner } : { _id, ...(inner as object) }
 }
 async function seedZoneItem(schema: Schema, decl: ZoneDecl, item: unknown, ctx: SeedCtx, here: string, fail: Fail): Promise<Record<string, unknown> | null> {
   const _id = ctx.newId()
   const block = record(item) && typeof item._block === 'string' ? item._block : ''
+  visibilityIssues(item, decl).forEach(i => fail(path.child(here, _id, '_hidden'), i.message))
   if (block === SLOT) return { _id, _block: SLOT }
   const declared = Object.hasOwn(schema.blocks, block) ? schema.blocks[block] : undefined
   if (!declared) { fail(path.child(here, _id), `No block named "${block}".`); return null }
   if (!decl.allow.includes(block)) fail(path.child(here, _id), `"${block}" is not allowed here.`)
-  const { _block: _b, ...rest } = item as Record<string, unknown>
-  return { _id, _block: block, ...((await seedField(schema, { container: 'u90/group', fields: declared.fields, order: declared.order }, rest, ctx, path.child(here, _id), fail)) as object) }
+  const { _block: _b, _hidden, ...rest } = item as Record<string, unknown>
+  return { _id, _block: block, ...(typeof _hidden === 'boolean' ? { _hidden } : {}), ...((await seedField(schema, blockFields(declared, rest), rest, ctx, path.child(here, _id), fail)) as object) }
 }
 
 /** Declared defaults, or an explicit seed value, to stored JSON. Every failing path is collected before throwing. */
@@ -152,21 +166,26 @@ export function seedIssues(schema: Schema, docDecl: DocumentDecl, value: unknown
     }
     if (decl.container === 'u90/group') {
       if (!record(v)) return add(here, 'invalid_type', 'Expected an object of fields.')
-      for (const k of Object.keys(v)) if (!Object.hasOwn(decl.fields, k)) add(path.child(here, k), 'unknown-field', `No field named "${k}".`)
+      visibilityIssues(v).forEach(i => add(path.child(here, '_hidden'), i.code, i.message))
+      for (const k of Object.keys(v)) if (k !== '_hidden' && !Object.hasOwn(decl.fields, k)) add(path.child(here, k), 'unknown-field', `No field named "${k}".`)
       for (const [name, f] of orderedEntries(decl.fields, decl.order)) field(f, v[name], path.child(here, name))
       return
     }
     if (!Array.isArray(v)) return add(here, 'invalid_type', decl.container === 'u90/list' ? 'Expected a list.' : 'Expected a list of blocks.')
-    if (decl.container === 'u90/list') return v.forEach((item, i) => field(decl.item, item, path.child(here, i)))
+    if (decl.container === 'u90/list') return v.forEach((item, i) => {
+      if (isLeaf(decl.item)) visibilityIssues(item).forEach(issue => add(path.child(here, i, '_hidden'), issue.code, issue.message))
+      field(decl.item, item, path.child(here, i))
+    })
     v.forEach((item, i) => {
       const itemAt = path.child(here, i)
       const block = record(item) && typeof item._block === 'string' ? item._block : ''
+      visibilityIssues(item, decl).forEach(issue => add(path.child(itemAt, '_hidden'), issue.code, issue.message))
       if (block === SLOT) return
       const declared = Object.hasOwn(schema.blocks, block) ? schema.blocks[block] : undefined
       if (!declared) return add(itemAt, 'unknown-block', `No block named "${block}".`)
       if (!decl.allow.includes(block)) add(itemAt, 'not-allowed', `"${block}" is not allowed here.`)
-      const { _block: _b, ...rest } = item as Record<string, unknown>
-      field({ container: 'u90/group', fields: declared.fields, order: declared.order }, rest, itemAt)
+      const { _block: _b, _hidden: _h, ...rest } = item as Record<string, unknown>
+      field(blockFields(declared, rest), rest, itemAt)
     })
   }
   if (docDecl.kind === 'entry') {

package/src/elements/ops/validate.ts

@@ -1,3 +1,4 @@
+import { canonicalJson } from '../../site/wire'
 import { SLOT, type DocumentDecl, type Issue, type LeafIssue, type Mode, type Schema } from '../define'
 import { hasStoredShape, validateLeaf } from '../leaf'
 import { path } from '../path'
@@ -15,14 +16,39 @@ export function validate(schema: Schema, docDecl: DocumentDecl, doc: unknown, at
   const issues: Issue[] = []
   const push = (base: string, i: LeafIssue) => issues.push({ path: path.child(base, ...i.path), code: i.code, message: i.message, severity: i.severity ?? 'error' })
   const ids = new Map<string, string>()
+  const blockPaths = new Set<string>()
+  const hiddenPaths: string[] = []
   const layoutRoot = docDecl.kind === 'layout' ? path.child(at, 'blocks') : null
   const root = (p: string, code: string, message: string): Issue[] => [{ path: p, code, message, severity: 'error' }]
   if (!record(doc)) return root(at, 'invalid_type', 'A stored document is an object.')
   if (docDecl.kind === 'entry' && !Object.hasOwn(schema.collections, docDecl.collection)) return root(at, 'unknown-collection', `No collection named "${docDecl.collection}".`)
   if (docDecl.kind === 'single' && !Object.hasOwn(schema.singles, docDecl.key)) return root(at, 'unknown-single', `No Single named "${docDecl.key}".`)
   if (docDecl.kind === 'entry' && doc.fields !== undefined && !record(doc.fields)) return root(path.child(at, 'fields'), 'invalid_type', 'An entry stores its fields as an object.')
+  // Walking the old declaration also records absent fields. A new repeated item's path is
+  // absent from this map, so its defaults can initialise without unlocking retained fields.
+  const wholeLockedBefore = new Map<string, unknown>()
+  if (opts.previous !== undefined) walkDocument(schema, docDecl, opts.previous, {
+    leaf: ({ decl, value, at: here }) => { if (decl.lock?.includes('$')) wholeLockedBefore.set(here, value) },
+  }, at)
   walkDocument(schema, docDecl, doc, {
     enter: ({ container, decl, value, at: here }) => {
+      if (container.id === 'u90/zone' && Array.isArray(value)) {
+        for (const item of value) if (record(item)) {
+          const itemPath = path.child(here, String(item._id))
+          blockPaths.add(itemPath)
+          if (Object.hasOwn(item, '_hidden')) {
+            if (typeof item._hidden !== 'boolean') push(itemPath, { path: ['_hidden'], code: 'invalid_type', message: 'Block visibility must be a boolean.' })
+            if ('fixed' in decl && decl.fixed) push(itemPath, { path: ['_hidden'], code: 'fixed-visibility', message: 'Fixed blocks cannot have visibility metadata.' })
+            if (item._block === SLOT) push(itemPath, { path: ['_hidden'], code: 'invalid-visibility', message: 'SLOT cannot have visibility metadata.' })
+            if (item._hidden === true) hiddenPaths.push(itemPath)
+          }
+        }
+      }
+      if (record(value) && Object.hasOwn(value, '_hidden') && !blockPaths.has(here))
+        push(here, { path: ['_hidden'], code: 'invalid-visibility', message: 'Only zone blocks can have visibility metadata.' })
+      if (container.id === 'u90/list' && Array.isArray(value))
+        for (const item of value) if (record(item) && Object.hasOwn(item, '_hidden'))
+          push(path.child(here, String(item._id)), { path: ['_hidden'], code: 'invalid-visibility', message: 'List items cannot have visibility metadata.' })
       container.enter(decl, value, schema).forEach((i) => push(here, i))
       if (container.id === 'u90/zone' && slots(value) !== (here === layoutRoot ? 1 : 0))
         push(here, { path: [], code: 'slot', message: here === layoutRoot ? 'A layout holds exactly one SLOT.' : 'Only a layout may hold a SLOT.' })
@@ -34,8 +60,11 @@ export function validate(schema: Schema, docDecl: DocumentDecl, doc: unknown, at
           }
     },
     leaf: ({ entry, decl, value, at: here }) => {
-      validateLeaf(entry, decl, value, opts.mode).forEach((i) => push(here, i))
-      if (decl.lock?.length && opts.previous !== undefined) {
+      validateLeaf(entry, decl, value, hiddenPaths.some(p => here.startsWith(`${p}/`)) ? 'draft' : opts.mode).forEach((i) => push(here, i))
+      if (decl.lock?.includes('$') && wholeLockedBefore.has(here)) {
+        if (canonicalJson(wholeLockedBefore.get(here)) !== canonicalJson(value))
+          push(here, { path: [], code: 'locked', message: 'This field is set by the site and cannot be changed here.' })
+      } else if (decl.lock?.length && !decl.lock.includes('$') && opts.previous !== undefined) {
         const pointer = path.toPointer(opts.previous, here)
         const before = pointer === null ? undefined : valueAtPointer(opts.previous, pointer)
         if (before !== undefined)

package/src/legacy/cli.mjs

@@ -2,7 +2,7 @@
 import { readFile, writeFile } from 'node:fs/promises'
 
 /**
- * `npx --yes @unitninety/u90@1.0.1 pair <code>` — the one command an operator hands over. The u90 tool
+ * `npx --yes @unitninety/u90@1.0.4 pair <code>` — the one command an operator hands over. The u90 tool
  * runs this file for `u90 pair`. The command is scoped and pinned because an unscoped name, run in a
  * repository with no local bin, fetches whatever package npm holds under that name.
  *
@@ -115,7 +115,7 @@ const run = async () => {
   const args = process.argv.slice(2)
 
   if (args[0] !== 'pair' || !args[1]) {
-    fail('Usage: npx --yes @unitninety/u90@1.0.1 pair <code> --site https://example.com [--platform https://cms…]')
+    fail('Usage: npx --yes @unitninety/u90@1.0.4 pair <code> --site https://example.com [--platform https://cms…]')
   }
 
   const code = args[1]

package/src/legacy/content.ts

@@ -360,7 +360,7 @@ export const createContentClient = ({
             : !platformUrl
               ? 'PLATFORM_URL is unset'
               : 'PAYLOAD_API_KEY is unset'
-        }. Every page will render its committed fallback copy, and every collection route will 404. Set it in the site's environment — \`npx --yes @unitninety/u90@1.0.1 pair\` writes both.`,
+        }. Every page will render its committed fallback copy, and every collection route will 404. Set it in the site's environment — \`npx --yes @unitninety/u90@1.0.4 pair\` writes both.`,
       )
     }
     return true

package/src/seo/robots.ts

@@ -3,12 +3,12 @@ import type { SiteReply } from '../site/wire'
 import { siteUrlFor } from './metadata'
 
 /**
- * `robots.txt`: every crawler is allowed, and the sitemap named, unless the platform's
- * `allowIndexing` is off, when everything is disallowed and no sitemap is named. A `/site` read that
- * failed (`site` null) allows crawling, so a platform hiccup never takes a site out of search. With
- * no origin there is no absolute sitemap URL to name.
+ * Public pages remain crawlable even with indexing off: crawlers must fetch them to see
+ * metadata's noindex. Only indexable sites advertise a sitemap. Private previews are
+ * protected separately by the preview access gate and its X-Robots-Tag headers.
+ * A failed site read retains normal discovery rather than changing search policy.
  */
-export const robotsFor = ({ origin, site }: { origin: string | undefined; site: SiteReply | null }): MetadataRoute.Robots =>
-  site?.allowIndexing === false
-    ? { rules: { userAgent: '*', disallow: '/' } }
-    : { rules: { userAgent: '*', allow: '/' }, ...(origin ? { sitemap: siteUrlFor(origin, '/sitemap.xml') } : {}) }
+export const robotsFor = ({ origin, site }: { origin: string | undefined; site: SiteReply | null }): MetadataRoute.Robots => ({
+  rules: { userAgent: '*', allow: '/' },
+  ...(site?.allowIndexing !== false && origin ? { sitemap: siteUrlFor(origin, '/sitemap.xml') } : {}),
+})

package/src/seo/seeds.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod'
+import type { SiteManifest } from '../site/types'
+
+/** Portable SEO contains authored settings, never database IDs or Search Console credentials. */
+const text = z.string().max(10000).nullable().optional()
+const webUrl = z.string().max(400).refine(value => {
+  if (!value || /^\/(?!\/)\S*$/.test(value)) return true
+  try { const u = new URL(value); return ['http:', 'https:'].includes(u.protocol) && !u.username && !u.password } catch { return false }
+}, 'Expected an http or https URL, or a path on this site.').nullable().optional()
+const image = z.strictObject({ source: z.string().min(1).max(2048) }).nullable().optional()
+export const DocumentSeoSeedSchema = z.strictObject({
+  title: z.string().max(400).nullable().optional(), description: z.string().max(400).nullable().optional(), ogTitle: z.string().max(400).nullable().optional(), ogDescription: z.string().max(400).nullable().optional(),
+  ogImage: image, canonical: webUrl, noindex: z.boolean().optional(),
+})
+export const SiteSeoSeedSchema = z.strictObject({
+  allowIndexing: z.boolean().nullable().optional(), siteName: text, titleTemplate: text,
+  description: text, locale: text, ogImage: image, twitterHandle: text,
+  twitterCard: z.enum(['summary', 'summary_large_image']).optional(),
+  googleVerification: text, bingVerification: text,
+  organisation: z.strictObject({
+    legalName: text, logo: image, phone: text, email: text, address: text, legacyOpeningHours: text,
+    sameAs: z.array(z.string().max(2048)).max(100).optional(),
+    openingHours: z.array(z.strictObject({
+      day: z.enum(['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday']),
+      closed: z.boolean(), opens: text, closes: text,
+    })).max(7).optional(),
+  }).nullable().optional(),
+})
+export const SeoSeedsSchema = z.strictObject({
+  site: SiteSeoSeedSchema.optional(),
+  pages: z.record(z.string(), DocumentSeoSeedSchema).optional(),
+  entries: z.record(z.string(), z.record(z.string(), DocumentSeoSeedSchema)).optional(),
+})
+export type DocumentSeoSeed = z.infer<typeof DocumentSeoSeedSchema>
+export type SiteSeoSeed = z.infer<typeof SiteSeoSeedSchema>
+export type SeoSeeds = z.infer<typeof SeoSeedsSchema>
+
+/** SEO targets must exist and have a page; no silent loss into unrendered fields. */
+export function seoSeedIssues(seo: SeoSeeds | undefined, manifest: SiteManifest): { path: string; message: string }[] {
+  const issues: { path: string; message: string }[] = []
+  for (const key of Object.keys(seo?.pages ?? {}))
+    if (!Object.hasOwn(manifest.pages, key)) issues.push({ path: `seo/pages/${key}`, message: 'SEO names a page the manifest does not declare.' })
+  for (const [collection, entries] of Object.entries(seo?.entries ?? {})) {
+    if (!manifest.collections[collection]?.route) issues.push({ path: `seo/entries/${collection}`, message: 'SEO needs a collection with its own page route.' })
+    for (const slug of Object.keys(entries))
+      if (!manifest.entries[collection]?.some(e => e.slug === slug)) issues.push({ path: `seo/entries/${collection}/${slug}`, message: 'SEO names an entry the manifest does not declare.' })
+  }
+  return issues
+}
+
+/** All portable image sources, with their diagnostic paths, for packaging and seeding. */
+export function seoSeedAssets(seo: SeoSeeds | undefined): { source: string; path: string }[] {
+  const out: { source: string; path: string }[] = []
+  const add = (value: { source: string } | null | undefined, path: string) => { if (value) out.push({ source: value.source, path }) }
+  add(seo?.site?.ogImage, 'seo/site/ogImage')
+  add(seo?.site?.organisation?.logo, 'seo/site/organisation/logo')
+  for (const [key, doc] of Object.entries(seo?.pages ?? {})) add(doc.ogImage, `seo/pages/${key}/ogImage`)
+  for (const [collection, entries] of Object.entries(seo?.entries ?? {}))
+    for (const [slug, doc] of Object.entries(entries)) add(doc.ogImage, `seo/entries/${collection}/${slug}/ogImage`)
+  return out
+}

package/src/server/render.tsx

@@ -5,18 +5,18 @@ import type { LanguageLinks } from '../languages/routing'
 import { LanguageProvider } from '../switcher/LanguageSwitcher'
 import { DraftBlocks } from '../bridge/DraftBlocks'
 
-type BlockItem = { _id: string; _block: string; $path?: string } & Record<string, unknown>
+type BlockItem = { _id: string; _block: string; _hidden?: boolean; $path?: string } & Record<string, unknown>
 /** What a block declared with `entry:` receives, when the document being rendered is an entry page. */
 type EntryProp = { id: string; slug?: string; route?: string; fields?: Record<string, unknown> }
 
 export function createRender(site: Site) {
   const Blocks = ({ value, slot, entry }: { value: unknown; slot?: ReactNode; entry?: EntryProp }): ReactElement => {
-    const items = (Array.isArray(value) ? value : []) as BlockItem[]
+    const items = ((Array.isArray(value) ? value : []) as BlockItem[]).filter(item => item._hidden !== true)
     const renderedItems = items.map((item) => {
       if (item._block === 'SLOT') return createElement(Fragment, { key: item._id }, slot)
       const def = Object.hasOwn(site.blocks, item._block) ? site.blocks[item._block] : undefined
       if (!def) return item.$path ? createElement('div', { key: item._id, 'data-u90-block': item.$path, 'data-u90-missing': item._block }, `Block "${item._block}" was removed`) : null
-      const { _id, _block, $path, ...fields } = item
+      const { _id, _block, _hidden, $path, ...fields } = item
       // zones arrive rendered: replace each zone-typed field with <Blocks/>, threading `entry` through
       const props: Record<string, unknown> = { ...fields }
       for (const [name, decl] of Object.entries(def.fields)) if ('container' in (decl as object) && (decl as { container: string }).container === 'u90/zone') props[name] = createElement(Blocks, { value: fields[name], entry })