@nfcard/validation 0.23.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nfcard/validation",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Shared Zod validation schemas for the NFCard product family.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "dependencies": {
     "zod": "^3.24.0",
-    "@nfcard/types": "0.17.0"
+    "@nfcard/types": "0.19.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0"

package/src/profileLayout.test.ts

@@ -0,0 +1,259 @@
+/**
+ * NFCARD-656 — write-side guards for `DigitalConfig.layout`.
+ *
+ * The abuse cases matter more than the happy path here: every style value
+ * eventually composes into a CSS rule block, so the assertion of record is
+ * "nothing non-primitive survives the schema", with the injection-shaped
+ * strings spelled out.
+ */
+import { describe, expect, it } from 'vitest'
+import { CANONICAL_OBJECT_ORDER, PROFILE_OBJECT_KINDS, ctaObjectIndex, type ProfileLayout } from '@nfcard/types'
+import { MAX_CTA_BUTTONS, digitalConfigSchema } from './index'
+import { STYLE_SCHEMA_FOR_KIND, profileLayoutSchema, safeProfileLayout } from './profileLayout'
+
+const okLayout: ProfileLayout = {
+  v: 1,
+  sectionOrder: ['identity', 'social', 'contact', 'bio', 'actions', 'cta', 'footer'],
+  objectOrder: {
+    social: ['social-x', 'social-linkedin'],
+    actions: ['act-share', 'act-save', 'act-exchange'],
+  },
+  objects: {
+    name: { style: { color: '#112233', sizeStep: 'lg', weight: 'bold' } },
+    avatar: { style: { crop: { x: 0.5, y: 0.25, zoom: 1.6 }, borderColor: '#ffffff', borderPx: 3 } },
+    'cta-0': { style: { bg: '#16a34a', color: '#ffffff' } },
+    booking: { style: { weight: 'bold' } },
+  },
+  ownedObjects: [{ id: 'ft-abcd', kind: 'freeText', section: 'bio', text: 'Hello there' }],
+}
+
+describe('profileLayoutSchema — accepts real intent', () => {
+  it('parses a full document and the result is a ProfileLayout', () => {
+    const parsed = profileLayoutSchema.parse(okLayout)
+    const typed: ProfileLayout = parsed
+    expect(typed.objectOrder?.social).toEqual(['social-x', 'social-linkedin'])
+  })
+
+  it('parses the boring derived document and the empty-intent forms', () => {
+    expect(profileLayoutSchema.parse({ v: 1 })).toEqual({ v: 1 })
+    expect(profileLayoutSchema.safeParse({ v: 1, objectOrder: {} }).success).toBe(true)
+  })
+
+  it('order entries tolerate well-formed ids this vintage does not know (skew safety)', () => {
+    const r = profileLayoutSchema.safeParse({
+      v: 1,
+      objectOrder: { social: ['social-threads', 'social-x'] },
+    })
+    expect(r.success).toBe(true)
+  })
+})
+
+describe('profileLayoutSchema — rejects abuse', () => {
+  const bad = (layout: unknown) => profileLayoutSchema.safeParse(layout).success
+
+  it('version and unknown keys', () => {
+    expect(bad({ v: 2 })).toBe(false)
+    expect(bad({ v: 1, extra: true })).toBe(false)
+    expect(bad({ v: 1, objects: { name: { style: {}, accent: {} } } })).toBe(false)
+  })
+
+  it('sectionOrder: duplicates and unknown sections', () => {
+    expect(bad({ v: 1, sectionOrder: ['social', 'social'] })).toBe(false)
+    expect(bad({ v: 1, sectionOrder: ['hero'] })).toBe(false)
+  })
+
+  it('objectOrder: malformed ids and oversize lists', () => {
+    expect(bad({ v: 1, objectOrder: { social: ['a.b'] } })).toBe(false)
+    expect(bad({ v: 1, objectOrder: { social: ['x'.repeat(33)] } })).toBe(false)
+    expect(bad({ v: 1, objectOrder: { social: Array.from({ length: 25 }, (_, i) => `id-${i}`) } })).toBe(false)
+    expect(bad({ v: 1, objectOrder: { unknownSection: ['social-x'] } })).toBe(false)
+  })
+
+  it('objects: unknown ids, off-vocabulary props, injection-shaped values', () => {
+    expect(bad({ v: 1, objects: { 'not-a-thing': { style: {} } } })).toBe(false)
+    // contactRow is TEXT-stylable since the any-text wave, but `bg` never
+    // joined its vocabulary — a row has no fill of its own.
+    expect(bad({ v: 1, objects: { 'contact-email': { style: { bg: '#112233' } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { name: { style: { color: 'red;}{' } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { name: { style: { color: '#12345' } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { avatar: { style: { borderPx: 99 } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { avatar: { style: { crop: { x: 0.5, y: 0.5, zoom: 9 } } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { 'cta-0': { style: { bg: 'url(javascript:1)' } } } })).toBe(false)
+    expect(bad({ v: 1, objects: { name: { style: { fontKey: '../evil' } } } })).toBe(false)
+  })
+
+  it('objects: the override cap and the distinct-font cap', () => {
+    const many = Object.fromEntries(
+      Array.from({ length: 65 }, (_, i) => [`ft-over${String(i).padStart(4, '0')}`, { style: {} }]),
+    )
+    expect(bad({ v: 1, objects: many })).toBe(false)
+
+    const fonts = Object.fromEntries(
+      ['name', 'role', 'bio', 'ft-aaaa', 'ft-bbbb'].map((id, i) => [
+        id,
+        { style: { fontKey: `font-${i}` } },
+      ]),
+    )
+    expect(bad({ v: 1, objects: fonts })).toBe(false)
+  })
+
+  it('ownedObjects: caps, duplicate ids, non-hosting sections, dissolving text', () => {
+    const ft = (id: string, section = 'bio', text = 'ok') => ({ id, kind: 'freeText', section, text })
+    expect(bad({ v: 1, ownedObjects: Array.from({ length: 6 }, (_, i) => ft(`ft-num${i}x`)) })).toBe(false)
+    expect(bad({ v: 1, ownedObjects: [ft('ft-abcd'), ft('ft-abcd')] })).toBe(false)
+    expect(bad({ v: 1, ownedObjects: [ft('ft-abcd', 'contact')] })).toBe(false)
+    expect(bad({ v: 1, ownedObjects: [ft('ft-abcd', 'bio', '<b></b>')] })).toBe(false)
+  })
+
+  it('freeText text is sanitised, not just bounded', () => {
+    const r = profileLayoutSchema.parse({
+      v: 1,
+      ownedObjects: [
+        { id: 'ft-abcd', kind: 'freeText', section: 'bio', text: '  <b>Szia</b> világ  ' },
+      ],
+    })
+    expect(r.ownedObjects?.[0].text).toBe('Szia világ')
+  })
+})
+
+describe('the any-text wave: per-kind style vocabulary (kind × prop matrix)', () => {
+  const style = (id: string, s: Record<string, unknown>) =>
+    profileLayoutSchema.safeParse({ v: 1, objects: { [id]: { style: s } } }).success
+
+  it('rows (contactRow / socialLink) take the text vocabulary minus align/sizeStep', () => {
+    const full = {
+      color: '#112233',
+      weight: 'bold',
+      italic: true,
+      underline: true,
+      fontKey: 'inter',
+    }
+    expect(style('contact-email', full)).toBe(true)
+    expect(style('social-instagram', full)).toBe(true)
+    // Row alignment is the template's grid — align stays refused. And a row
+    // is a compound (label/value spans with own px sizes), so sizeStep has
+    // nothing honest to render — refused rather than stored dead.
+    expect(style('contact-email', { align: 'center' })).toBe(false)
+    expect(style('social-instagram', { align: 'start' })).toBe(false)
+    expect(style('contact-email', { sizeStep: 'sm' })).toBe(false)
+    expect(style('social-instagram', { sizeStep: 'lg' })).toBe(false)
+  })
+
+  it('buttons take label styling; geometry props stay out', () => {
+    const label = { color: '#112233', weight: 'bold', italic: true, fontKey: 'inter' }
+    expect(style('cta-0', { ...label, bg: '#16a34a' })).toBe(true)
+    expect(style('booking', { ...label, bg: '#16a34a' })).toBe(true)
+    // No sizeStep (button geometry is the template's), no underline, no align.
+    expect(style('cta-0', { sizeStep: 'lg' })).toBe(false)
+    expect(style('cta-0', { underline: true })).toBe(false)
+    expect(style('booking', { align: 'center' })).toBe(false)
+  })
+
+  it('🔴 variant is GONE for every button kind — no surface could ever write it', () => {
+    expect(style('act-share', { color: '#112233', bg: '#16a34a', weight: 'bold' })).toBe(true)
+    for (const id of ['cta-0', 'booking', 'act-share']) {
+      expect(style(id, { variant: 'solid' })).toBe(false)
+    }
+  })
+
+  it('🔴 the vocabulary is TOTAL: every kind dispatches to a schema', () => {
+    // Driven off PROFILE_OBJECT_KINDS, not a hardcoded list — a NINTH kind
+    // added to types without a row here fails THIS line, not a production
+    // render. (tsc would catch it too, but tsc does not run on the publish
+    // path — validation 0.24.0 shipped while tsc was red.)
+    for (const kind of PROFILE_OBJECT_KINDS) {
+      expect(STYLE_SCHEMA_FOR_KIND[kind], `no style schema for kind '${kind}'`).toBeDefined()
+    }
+    // And through the real dispatch: one id per kind; `{}` is the least
+    // style. (The empty-style accept is also the additive guarantee: old
+    // documents keep parsing as vocabularies widen.)
+    const representative: Record<string, string> = {
+      text: 'name',
+      freeText: 'ft-abcd',
+      contactRow: 'contact-email',
+      socialLink: 'social-instagram',
+      image: 'avatar',
+      ctaButton: 'cta-0',
+      linkOut: 'booking',
+      action: 'act-share',
+    }
+    for (const kind of PROFILE_OBJECT_KINDS) {
+      const id = representative[kind]
+      expect(id, `no representative id for kind '${kind}' — extend this test`).toBeDefined()
+      expect(style(id, {})).toBe(true)
+    }
+  })
+
+  it('🔴 a kind the table misses is a REFUSAL, never a throw', () => {
+    // The cross-package skew case: a types vintage that knows a kind this
+    // validation build does not. The guard must add an issue — an exception
+    // in superRefine ESCAPES safeParse (zod 3.25), and safeProfileLayout's
+    // "the public page never 500s over decoration" contract dies with it.
+    const stolen = STYLE_SCHEMA_FOR_KIND.action
+    delete (STYLE_SCHEMA_FOR_KIND as Partial<typeof STYLE_SCHEMA_FOR_KIND>).action
+    try {
+      const r = profileLayoutSchema.safeParse({
+        v: 1,
+        objects: { 'act-share': { style: { weight: 'bold' } } },
+      })
+      expect(r.success).toBe(false)
+      // A style-LESS override on the unknown kind keeps the old accept.
+      expect(
+        profileLayoutSchema.safeParse({ v: 1, objects: { 'act-share': {} } }).success,
+      ).toBe(true)
+    } finally {
+      STYLE_SCHEMA_FOR_KIND.action = stolen
+    }
+  })
+
+  it('the distinct-font cap counts row and button fontKeys too', () => {
+    const fonts = Object.fromEntries(
+      ['name', 'contact-email', 'social-instagram', 'cta-0', 'booking'].map((id, i) => [
+        id,
+        { style: { fontKey: `font-${i}` } },
+      ]),
+    )
+    expect(profileLayoutSchema.safeParse({ v: 1, objects: fonts }).success).toBe(false)
+  })
+})
+
+describe('digitalConfigSchema integration', () => {
+  const baseConfig = {
+    templateId: 'classic',
+    accentColor: '#16a34a',
+    fontKey: 'inter',
+    showAvatar: true,
+  }
+
+  it('validates existing profiles unchanged (no layout key)', () => {
+    expect(digitalConfigSchema.safeParse(baseConfig).success).toBe(true)
+  })
+
+  it('accepts and KEEPS a valid layout — the strip-mode guard the web store needs', () => {
+    const r = digitalConfigSchema.parse({ ...baseConfig, layout: okLayout })
+    expect(r.layout?.objectOrder?.social).toEqual(['social-x', 'social-linkedin'])
+  })
+
+  it('rejects a config whose layout is malformed rather than silently dropping it', () => {
+    expect(digitalConfigSchema.safeParse({ ...baseConfig, layout: { v: 7 } }).success).toBe(false)
+  })
+})
+
+describe('safeProfileLayout (render-side gate)', () => {
+  it('null/undefined/garbage → null; valid → data', () => {
+    expect(safeProfileLayout(undefined)).toBeNull()
+    expect(safeProfileLayout(null)).toBeNull()
+    expect(safeProfileLayout('layout')).toBeNull()
+    expect(safeProfileLayout({ v: 2 })).toBeNull()
+    expect(safeProfileLayout({ v: 1 })).toEqual({ v: 1 })
+  })
+})
+
+describe('cross-package constants stay in lockstep', () => {
+  it('CANONICAL_OBJECT_ORDER.cta carries exactly MAX_CTA_BUTTONS cta slots', () => {
+    // types cannot import validation, so the canonical array hard-codes five
+    // slots; this is the test that keeps the two declarations honest.
+    const ctaSlots = CANONICAL_OBJECT_ORDER.cta.filter((id) => ctaObjectIndex(id) !== null)
+    expect(ctaSlots.length).toBe(MAX_CTA_BUTTONS)
+  })
+})

package/src/profileLayout.ts

@@ -0,0 +1,297 @@
+/**
+ * NFCARD-656 — the write-side schema for `DigitalConfig.layout`, the stored
+ * object/section document. The vocabulary (section ids, object ids, kinds,
+ * caps) lives in @nfcard/types; this file only decides what a WRITE may
+ * contain.
+ *
+ * Posture, and why it differs between the two order surfaces:
+ *  · `objects` (style overrides) is STRICT — every key must name an object
+ *    this schema's vintage knows, because styles are rendered into CSS and
+ *    an un-dispatchable style cannot be validated per kind. Version skew is
+ *    covered by the deploy order (api ships before web, so the accepting
+ *    schema is never older than the writing client).
+ *  · `sectionOrder` / `objectOrder` entries are validated by SHAPE only
+ *    (charset + length). An order entry naming nothing is harmless by
+ *    construction — `resolveObjectOrder` filters to what is present at
+ *    render — and rejecting it would turn "the user once ordered a thing
+ *    that later disappeared" into a 400 on an unrelated save.
+ *
+ * ⚠ NOT the XSS boundary. FreeText is rendered through Nunjucks with
+ * autoescape ON (FOXHOLE-587); the hygiene here (tag/control strip, caps)
+ * is defense-in-depth, same standing as the rest of @nfcard/validation.
+ */
+import { z } from 'zod'
+import {
+  MAX_DISTINCT_OBJECT_FONTS,
+  MAX_FREE_TEXT_LENGTH,
+  MAX_LAYOUT_OBJECT_OVERRIDES,
+  MAX_OBJECT_ORDER_LENGTH,
+  MAX_OWNED_OBJECTS,
+  FREE_TEXT_ID_RE,
+  PROFILE_SECTIONS,
+  PROFILE_SECTION_IDS,
+  objectKindOf,
+  type ProfileLayout,
+  type ProfileObjectKind,
+  type ProfileSectionId,
+} from '@nfcard/types'
+// ⚠ Deliberate import cycle (index.ts imports this file for
+// `digitalConfigSchema.layout`). It is init-safe: `sanitizeText` is a
+// hoisted function DECLARATION referenced only inside parse-time closures,
+// never called while modules initialise. Importing it beats re-implementing
+// it — a second, weaker copy of a sanitizer is the recurring 624/626/627
+// failure mode.
+import { sanitizeText } from './index'
+
+const HEX_RE = /^#[0-9A-Fa-f]{6}$/
+
+/** Order entries and override keys share the token grammar's id budget. */
+const OBJECT_ID_SHAPE_RE = /^[A-Za-z0-9_-]{1,32}$/
+
+export const textObjectStyleSchema = z
+  .object({
+    color: z.string().regex(HEX_RE).optional(),
+    sizeStep: z.enum(['sm', 'md', 'lg']).optional(),
+    align: z.enum(['start', 'center']).optional(),
+    weight: z.enum(['normal', 'bold']).optional(),
+    italic: z.boolean().optional(),
+    underline: z.boolean().optional(),
+    // Resolved through the api's font map at render; an unknown key falls
+    // back to the template pairing, so membership is not validated here.
+    fontKey: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(/^[A-Za-z0-9-]+$/)
+      .optional(),
+  })
+  .strict()
+
+export const imageObjectStyleSchema = z
+  .object({
+    crop: z
+      .object({
+        x: z.number().min(0).max(1),
+        y: z.number().min(0).max(1),
+        zoom: z.number().min(1).max(3),
+      })
+      .strict()
+      .optional(),
+    borderColor: z.string().regex(HEX_RE).optional(),
+    borderPx: z.number().int().min(0).max(8).optional(),
+    shape: z.enum(['circle', 'rounded', 'square']).optional(),
+  })
+  .strict()
+
+/**
+ * Contact rows and social chips: text minus `align` and `sizeStep`. Row
+ * alignment is the template's grid; and a row is a COMPOUND (label/value
+ * spans with their own px sizes), so no wrapper-level em can scale it
+ * without destroying the internal hierarchy — either would be a
+ * stored-but-dead field.
+ */
+export const rowTextStyleSchema = textObjectStyleSchema.omit({
+  align: true,
+  sizeStep: true,
+})
+
+/** Label styling (the text vocabulary's `color`/`weight`/`italic`/`fontKey`,
+ *  DERIVED so the validators stay in lockstep) + `bg` fill. No `sizeStep`
+ *  in v1 — button geometry is the template's. `variant` is GONE (0.24.0
+ *  accepted it and the render did style it): NO SURFACE COULD EVER WRITE IT
+ *  — the toolbar exposes no variant control and none is planned — and a
+ *  stored-but-unwritable field is dead weight on every future vintage. No
+ *  deployed tag ever accepted one, so nothing stored carries it. */
+export const buttonObjectStyleSchema = textObjectStyleSchema
+  .pick({ color: true, weight: true, italic: true, fontKey: true })
+  .extend({ bg: z.string().regex(HEX_RE).optional() })
+  .strict()
+
+/**
+ * Which style vocabulary each kind accepts — TOTAL over the kind vocabulary
+ * since the any-text wave, so "unknown kind" can only mean an id this
+ * schema's vintage cannot dispatch (already refused by `objectKindOf`).
+ *
+ * EXPORTED for the web toolbar: `toolbarControlsFor` derives its control
+ * matrix from these shapes instead of hand-mirroring them, so a vocabulary
+ * change here reshapes the UI by construction.
+ */
+export const STYLE_SCHEMA_FOR_KIND: Record<
+  ProfileObjectKind,
+  z.ZodObject<z.ZodRawShape>
+> = {
+  text: textObjectStyleSchema,
+  freeText: textObjectStyleSchema,
+  contactRow: rowTextStyleSchema,
+  socialLink: rowTextStyleSchema,
+  image: imageObjectStyleSchema,
+  ctaButton: buttonObjectStyleSchema,
+  linkOut: buttonObjectStyleSchema,
+  action: buttonObjectStyleSchema,
+}
+
+const orderListSchema = z
+  .array(z.string().regex(OBJECT_ID_SHAPE_RE))
+  .max(MAX_OBJECT_ORDER_LENGTH)
+
+const freeTextObjectSchema = z
+  .object({
+    id: z.string().regex(FREE_TEXT_ID_RE),
+    kind: z.literal('freeText'),
+    section: z.enum(PROFILE_SECTION_IDS),
+    text: z
+      .string()
+      .max(2000) // raw guard; the transform caps to the real bound below
+      .transform((v) => sanitizeText(v, MAX_FREE_TEXT_LENGTH)),
+  })
+  .strict()
+
+export const profileLayoutSchema = z
+  .object({
+    v: z.literal(1),
+    sectionOrder: z
+      .array(z.enum(PROFILE_SECTION_IDS))
+      .max(PROFILE_SECTION_IDS.length)
+      .optional(),
+    objectOrder: z
+      .object(
+        Object.fromEntries(
+          PROFILE_SECTION_IDS.map((id) => [id, orderListSchema.optional()]),
+        ) as Record<ProfileSectionId, z.ZodOptional<typeof orderListSchema>>,
+      )
+      .strict()
+      .partial()
+      .optional(),
+    objects: z.record(z.string().regex(OBJECT_ID_SHAPE_RE), z.unknown()).optional(),
+    ownedObjects: z.array(freeTextObjectSchema).max(MAX_OWNED_OBJECTS).optional(),
+  })
+  .strict()
+  .superRefine((layout, ctx) => {
+    // A duplicated section is a client bug — loud beats silently reordered.
+    if (layout.sectionOrder) {
+      const seen = new Set(layout.sectionOrder)
+      if (seen.size !== layout.sectionOrder.length) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['sectionOrder'],
+          message: 'duplicate section id',
+        })
+      }
+    }
+
+    if (layout.objects) {
+      const keys = Object.keys(layout.objects)
+      if (keys.length > MAX_LAYOUT_OBJECT_OVERRIDES) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['objects'],
+          message: `more than ${MAX_LAYOUT_OBJECT_OVERRIDES} overrides`,
+        })
+        return
+      }
+      const fonts = new Set<string>()
+      for (const key of keys) {
+        const kind = objectKindOf(key)
+        if (!kind) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['objects', key],
+            message: 'unknown object id',
+          })
+          continue
+        }
+        const styleSchema = STYLE_SCHEMA_FOR_KIND[kind]
+        const override = layout.objects[key]
+        const overrideParsed = z
+          .object({ style: z.unknown().optional() })
+          .strict()
+          .safeParse(override)
+        if (!overrideParsed.success) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['objects', key],
+            message: 'override must be { style? }',
+          })
+          continue
+        }
+        const style = overrideParsed.data.style
+        if (style === undefined) continue
+        // The table is TOTAL by type, but tsc does not run on the publish
+        // path and `objectKindOf` lives in @nfcard/types behind a ^range —
+        // a types vintage that knows a NINTH kind can resolve under a
+        // validation build whose table stops at eight. Without this guard
+        // that skew is a TypeError that ESCAPES safeParse (verified against
+        // zod 3.25), turning `safeProfileLayout`'s promised null into a 500
+        // on the public render. Refusal, never a throw.
+        if (!styleSchema) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['objects', key, 'style'],
+            message: `kind '${kind}' has no style vocabulary in this build`,
+          })
+          continue
+        }
+        const parsed = styleSchema.safeParse(style)
+        if (!parsed.success) {
+          for (const issue of parsed.error.issues) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              path: ['objects', key, 'style', ...issue.path],
+              message: issue.message,
+            })
+          }
+          continue
+        }
+        const fontKey = (parsed.data as { fontKey?: string }).fontKey
+        if (fontKey) fonts.add(fontKey)
+      }
+      if (fonts.size > MAX_DISTINCT_OBJECT_FONTS) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['objects'],
+          message: `more than ${MAX_DISTINCT_OBJECT_FONTS} distinct fonts`,
+        })
+      }
+    }
+
+    if (layout.ownedObjects) {
+      const ids = new Set<string>()
+      layout.ownedObjects.forEach((obj, i) => {
+        if (ids.has(obj.id)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['ownedObjects', i, 'id'],
+            message: 'duplicate freeText id',
+          })
+        }
+        ids.add(obj.id)
+        if (!PROFILE_SECTIONS[obj.section].hosts.includes('freeText')) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['ownedObjects', i, 'section'],
+            message: `section '${obj.section}' does not host freeText`,
+          })
+        }
+        if (obj.text.length === 0) {
+          // Post-sanitise emptiness: a tags-only submission dissolves here.
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['ownedObjects', i, 'text'],
+            message: 'empty after sanitisation',
+          })
+        }
+      })
+    }
+  })
+
+/**
+ * Render-side gate: a stored layout that no longer parses (a vintage this
+ * build predates, a hand-corrupted blob) renders as CANONICAL rather than
+ * failing the whole page. Mirrors the lenient posture of
+ * `resolveRenderBackground` — the public page never 500s over decoration.
+ */
+export function safeProfileLayout(value: unknown): ProfileLayout | null {
+  if (value === undefined || value === null) return null
+  const parsed = profileLayoutSchema.safeParse(value)
+  return parsed.success ? (parsed.data as ProfileLayout) : null
+}