@vectoriox/iox-ui 5.54.0 → 5.56.0

package/src/generation-core/audit-site.ts

@@ -0,0 +1,386 @@
+import { ELEMENT_ACTION_DESCRIPTORS, resolveActionAvailability } from '@vectoriox/iox-ui/actions-core';
+import { auditDesignContrast, DesignTokenLike } from '@vectoriox/iox-ui/design-core';
+import { collectFormSpec, ControlType, FIELD_NODE_TYPE, FORM_NODE_TYPE } from '@vectoriox/iox-ui/forms-core';
+
+import { blocksPublish, ComposedPlaceholder, PlaceholderKind } from './compose-site';
+import { navShapeOf } from './nav-shape';
+import { PatternGlobalPosition } from './patterns';
+import { SerializedNode, walkSerialized } from './serialized-node';
+
+/**
+ * THE Publishable gate (AI plan §3e, M1-7): ONE pure function over a snapshot of a site — its pages, globals, the
+ * connectors' health, the look's token rows, what a build left to fill — run by the Publish dialog, the builder's
+ * Needs attention and the server on publish (iox-cms refuses with the same findings). Works on any site, generated
+ * or hand-built. Severity is decision D8: an unfilled fact, a policy placeholder or an action that points at nothing
+ * BLOCKS; samples, copy placeholders and stock photos ASK ("Publish anyway"); the rest WARN. Design advice
+ * (harness-core `lintDesign`) is not one of the eight — the caller adds it, and it never blocks.
+ */
+
+export enum SiteCheckId {
+    Navigation = 'navigation',
+    Forms = 'forms',
+    Consent = 'consent',
+    Seo = 'seo',
+    Facts = 'facts',
+    Accessibility = 'accessibility',
+    Tokens = 'tokens',
+    Actions = 'actions',
+}
+
+/** The eight, in §3e's order. */
+export const SITE_CHECKS: ReadonlyArray<SiteCheckId> = Object.values(SiteCheckId);
+
+export enum CheckSeverity {
+    Block = 'block',
+    Ask = 'ask',
+    Warn = 'warn',
+}
+
+export enum SiteFindingCode {
+    NoHeader = 'no-header',
+    NoPhoneMenu = 'no-phone-menu',
+    FormWithoutId = 'form-without-id',
+    EmailNeedsMailer = 'email-needs-mailer',
+    TrackerWithoutBanner = 'tracker-without-banner',
+    NoTitle = 'no-title',
+    NoDescription = 'no-description',
+    UnfilledFact = 'unfilled-fact',
+    CopyPlaceholder = 'copy-placeholder',
+    SampleItems = 'sample-items',
+    StockPhoto = 'stock-photo',
+    NoPrivacyPage = 'no-privacy-page',
+    PrivacyPagePlaceholder = 'privacy-page-placeholder',
+    LowContrast = 'low-contrast',
+    HeadingOrder = 'heading-order',
+    ImageWithoutAlt = 'image-without-alt',
+    LiteralColour = 'literal-colour',
+    DeadLink = 'dead-link',
+    DeadDialogTarget = 'dead-dialog-target',
+    ActionNeedsConnector = 'action-needs-connector',
+}
+
+/** Each finding's severity — one table (D8), never decided at a call site. */
+export const FINDING_SEVERITY: Readonly<Record<SiteFindingCode, CheckSeverity>> = {
+    [SiteFindingCode.NoHeader]: CheckSeverity.Warn,
+    [SiteFindingCode.NoPhoneMenu]: CheckSeverity.Warn,
+    [SiteFindingCode.FormWithoutId]: CheckSeverity.Block,
+    [SiteFindingCode.EmailNeedsMailer]: CheckSeverity.Warn,
+    [SiteFindingCode.TrackerWithoutBanner]: CheckSeverity.Warn,
+    [SiteFindingCode.NoTitle]: CheckSeverity.Warn,
+    [SiteFindingCode.NoDescription]: CheckSeverity.Warn,
+    [SiteFindingCode.UnfilledFact]: CheckSeverity.Block,
+    [SiteFindingCode.CopyPlaceholder]: CheckSeverity.Ask,
+    [SiteFindingCode.SampleItems]: CheckSeverity.Ask,
+    [SiteFindingCode.StockPhoto]: CheckSeverity.Ask,
+    [SiteFindingCode.NoPrivacyPage]: CheckSeverity.Ask,
+    [SiteFindingCode.PrivacyPagePlaceholder]: CheckSeverity.Block,
+    [SiteFindingCode.LowContrast]: CheckSeverity.Warn,
+    [SiteFindingCode.HeadingOrder]: CheckSeverity.Warn,
+    [SiteFindingCode.ImageWithoutAlt]: CheckSeverity.Warn,
+    [SiteFindingCode.LiteralColour]: CheckSeverity.Warn,
+    [SiteFindingCode.DeadLink]: CheckSeverity.Block,
+    [SiteFindingCode.DeadDialogTarget]: CheckSeverity.Block,
+    [SiteFindingCode.ActionNeedsConnector]: CheckSeverity.Block,
+};
+
+const CHECK_OF: Readonly<Record<SiteFindingCode, SiteCheckId>> = {
+    [SiteFindingCode.NoHeader]: SiteCheckId.Navigation,
+    [SiteFindingCode.NoPhoneMenu]: SiteCheckId.Navigation,
+    [SiteFindingCode.FormWithoutId]: SiteCheckId.Forms,
+    [SiteFindingCode.EmailNeedsMailer]: SiteCheckId.Forms,
+    [SiteFindingCode.TrackerWithoutBanner]: SiteCheckId.Consent,
+    [SiteFindingCode.NoTitle]: SiteCheckId.Seo,
+    [SiteFindingCode.NoDescription]: SiteCheckId.Seo,
+    [SiteFindingCode.UnfilledFact]: SiteCheckId.Facts,
+    [SiteFindingCode.CopyPlaceholder]: SiteCheckId.Facts,
+    [SiteFindingCode.SampleItems]: SiteCheckId.Facts,
+    [SiteFindingCode.StockPhoto]: SiteCheckId.Facts,
+    [SiteFindingCode.NoPrivacyPage]: SiteCheckId.Facts,
+    [SiteFindingCode.PrivacyPagePlaceholder]: SiteCheckId.Facts,
+    [SiteFindingCode.LowContrast]: SiteCheckId.Accessibility,
+    [SiteFindingCode.HeadingOrder]: SiteCheckId.Accessibility,
+    [SiteFindingCode.ImageWithoutAlt]: SiteCheckId.Accessibility,
+    [SiteFindingCode.LiteralColour]: SiteCheckId.Tokens,
+    [SiteFindingCode.DeadLink]: SiteCheckId.Actions,
+    [SiteFindingCode.DeadDialogTarget]: SiteCheckId.Actions,
+    [SiteFindingCode.ActionNeedsConnector]: SiteCheckId.Actions,
+};
+
+export interface SiteFinding {
+    check: SiteCheckId;
+    severity: CheckSeverity;
+    code: SiteFindingCode;
+    /** In plain words, for the screen. */
+    message: string;
+    pageId?: string;
+    nodeId?: string;
+    /** The global slot (`header` / `footer`) when it is in a global. */
+    owner?: string;
+}
+
+export interface SiteCheck {
+    id: SiteCheckId;
+    passed: boolean;
+    findings: SiteFinding[];
+}
+
+export interface SiteAudit {
+    checks: SiteCheck[];
+    blocking: number;
+    asking: number;
+}
+
+/** A page as the gate reads it. */
+export interface AuditPage {
+    id: string;
+    name: string;
+    route: string;
+    layout: ReadonlyArray<SerializedNode>;
+    seo?: unknown;
+}
+
+/** A placeholder a build left, and whether the node still shows it (the caller compares the node's text). */
+export interface AuditPlaceholder extends ComposedPlaceholder {
+    pageId?: string;
+    filled: boolean;
+}
+
+export interface SiteAuditSnapshot {
+    pages: ReadonlyArray<AuditPage>;
+    globals: ReadonlyArray<SerializedNode>;
+    /** Connector type → usable (configured or provided, and healthy). */
+    connectors: Readonly<Record<string, boolean>>;
+    /** Connector types that set a tracker (a consent category) and are configured. */
+    trackers?: ReadonlyArray<string>;
+    /** The look's token rows and the mode(s) the site wears. */
+    design?: { rows: ReadonlyArray<DesignTokenLike>; modes: ReadonlyArray<'light' | 'dark'> } | null;
+    placeholders?: ReadonlyArray<AuditPlaceholder>;
+    /** Sample items still in the site (`isSample`). */
+    samples?: ReadonlyArray<{ contentType: string; id: string; label?: string }>;
+    /** Stock photos a build placed that are still on the page. */
+    stock?: ReadonlyArray<{ nodeId: string; pageId?: string; owner?: string }>;
+}
+
+export interface SiteAuditOptions {
+    /** Audit as if only this page were being published (its own page checks + every site-wide one). */
+    pageId?: string;
+}
+
+const LINKING_TYPES = new Set(['Link', 'Heading', 'Button', 'ButtonBlock', 'LinkedContainer', 'Image']);
+const PAGE_LINK = 'page';
+const PERSONAL_CONTROLS: ReadonlySet<string> = new Set([ControlType.Email, ControlType.Tel, ControlType.Text, ControlType.Textarea]);
+const PRIVACY_PAGE = /privacy|פרטיות|מדיניות/i;
+const MAILER = 'mailer';
+const EMAIL_DELIVERY = 'email';
+const LITERAL_COLOUR = /#[0-9a-f]{3,8}\b|rgba?\(|hsla?\(/i;
+const COLOUR_TRAITS = /color|Color|^background$|boxShadow|textShadow/;
+const HEADING_LEVEL = /^h([1-6])$/;
+const DIALOG_TYPE = 'Dialog';
+const SELF = 'self';
+
+/** A route pattern (`/work/:slug`) matches a concrete path (`/work/blue-bowl`). */
+export function routeMatches(pattern: string, path: string): boolean {
+    const a = pattern.split('/').filter(Boolean);
+    const b = String(path ?? '').split(/[?#]/)[0].split('/').filter(Boolean);
+    return a.length === b.length && a.every((seg, i) => seg.startsWith(':') || seg === b[i]);
+}
+
+const nonEmpty = (v: unknown) => typeof v === 'string' && v.trim() !== '';
+
+/** A stored SEO field (a string, or `{ override, binding, auto }`) has a value, or may be derived. */
+function seoField(raw: unknown, derivable: boolean): boolean {
+    if (nonEmpty(raw)) return true;
+    if (raw && typeof raw === 'object') {
+        const v = raw as { override?: unknown; binding?: unknown; auto?: unknown };
+        if (nonEmpty(v.override) || v.binding) return true;
+        if (v.auto === false) return false;
+    }
+    return derivable;
+}
+
+function hasContent(layout: ReadonlyArray<SerializedNode>, type: string): boolean {
+    let found = false;
+    walkSerialized(layout, n => {
+        if (n.type !== type || found) return;
+        found = nonEmpty(n.props['content']) || n.bindings.some(b => b.prop === 'content');
+    });
+    return found;
+}
+
+interface Ctx {
+    out: SiteFinding[];
+    routes: string[];
+    nodeIds: Map<string, string>;
+}
+
+function add(ctx: Ctx, code: SiteFindingCode, message: string, where: { pageId?: string; nodeId?: string; owner?: string } = {}): void {
+    ctx.out.push({ check: CHECK_OF[code], severity: FINDING_SEVERITY[code], code, message, ...where });
+}
+
+/** Every node of a page or a global, with where it lives. */
+function eachNode(snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>, visit: (n: SerializedNode, where: { pageId?: string; owner?: string }) => void): void {
+    for (const page of pages) walkSerialized(page.layout, n => visit(n, { pageId: page.id }));
+    for (const global of snapshot.globals) {
+        const owner = global.globalPosition === PatternGlobalPosition.Before ? 'header' : 'footer';
+        walkSerialized([global], n => visit(n, { owner }));
+    }
+}
+
+function checkNavigation(ctx: Ctx, snapshot: SiteAuditSnapshot): void {
+    const header = snapshot.globals.find(g => g.globalPosition === PatternGlobalPosition.Before);
+    if (!header) return add(ctx, SiteFindingCode.NoHeader, 'The site has no header, so visitors have no menu to move around with.');
+    if (!navShapeOf(snapshot.globals)) add(ctx, SiteFindingCode.NoPhoneMenu, 'The header has no phone menu — on a phone its links are hard to reach.', { owner: 'header', nodeId: header.id });
+}
+
+function checkForms(ctx: Ctx, snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>): boolean {
+    let personal = false;
+    eachNode(snapshot, pages, (n, where) => {
+        if (n.type !== FORM_NODE_TYPE) return;
+        const spec = collectFormSpec(n as never);
+        if (!spec || !nonEmpty(spec.formId)) add(ctx, SiteFindingCode.FormWithoutId, 'A form has no id, so what visitors send is never stored.', { ...where, nodeId: n.id });
+        if (spec?.actions.some(a => a.type === EMAIL_DELIVERY) && snapshot.connectors[MAILER] !== true) {
+            add(ctx, SiteFindingCode.EmailNeedsMailer, 'A form emails what visitors send, but Email is not connected — it is stored and never sent.', { ...where, nodeId: n.id });
+        }
+        walkSerialized(n.children ?? [], f => {
+            if (f.type === FIELD_NODE_TYPE && PERSONAL_CONTROLS.has(String(f.props['control'] ?? ControlType.Text))) personal = true;
+        });
+    });
+    return personal;
+}
+
+function checkConsent(ctx: Ctx, snapshot: SiteAuditSnapshot): void {
+    if (!snapshot.trackers?.length) return;
+    let banner = false;
+    for (const g of snapshot.globals) walkSerialized([g], n => { if (n.type === DIALOG_TYPE && n.props['consentRole'] === true) banner = true; });
+    if (!banner) add(ctx, SiteFindingCode.TrackerWithoutBanner, `${snapshot.trackers.join(', ')} is connected, but the site has no cookie banner — it stays off for every visitor.`);
+}
+
+function checkSeo(ctx: Ctx, pages: ReadonlyArray<AuditPage>): void {
+    for (const page of pages) {
+        const seo = (page.seo ?? {}) as Record<string, unknown>;
+        if (!seoField(seo['title'], hasContent(page.layout, 'Heading'))) add(ctx, SiteFindingCode.NoTitle, `"${page.name}" has no title for search results.`, { pageId: page.id });
+        if (!seoField(seo['description'], hasContent(page.layout, 'Text'))) add(ctx, SiteFindingCode.NoDescription, `"${page.name}" has no description for search results.`, { pageId: page.id });
+    }
+}
+
+function checkFacts(ctx: Ctx, snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>, personal: boolean): void {
+    const inScope = (p: { pageId?: string }) => !p.pageId || pages.some(page => page.id === p.pageId);
+    for (const p of (snapshot.placeholders ?? []).filter(p => !p.filled && inScope(p))) {
+        const where = { pageId: p.pageId, nodeId: p.nodeId, ...(p.pageId ? {} : { owner: p.owner }) };
+        if (blocksPublish(p.kind)) add(ctx, SiteFindingCode.UnfilledFact, `"${p.text || p.fact || p.kind}" is still blank — fill it in before the site goes live.`, where);
+        else if (p.kind === PlaceholderKind.Copy) add(ctx, SiteFindingCode.CopyPlaceholder, 'Some words are still the template\'s.', where);
+    }
+    for (const s of snapshot.samples ?? []) add(ctx, SiteFindingCode.SampleItems, `"${s.label ?? s.id}" is a sample — replace or remove it.`, { nodeId: s.id });
+    for (const s of (snapshot.stock ?? []).filter(inScope)) add(ctx, SiteFindingCode.StockPhoto, 'A stock photo stands in for one of yours.', { pageId: s.pageId, nodeId: s.nodeId, owner: s.owner });
+    if (!personal) return;
+    const privacy = snapshot.pages.find(p => PRIVACY_PAGE.test(p.route) || PRIVACY_PAGE.test(p.name));
+    if (!privacy) return add(ctx, SiteFindingCode.NoPrivacyPage, 'A form asks for personal details, and the site has no privacy page saying what you do with them.');
+    if ((snapshot.placeholders ?? []).some(p => p.pageId === privacy.id && !p.filled)) {
+        add(ctx, SiteFindingCode.PrivacyPagePlaceholder, 'The privacy page still holds template words — only you can write it.', { pageId: privacy.id });
+    }
+}
+
+function checkAccessibility(ctx: Ctx, snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>): void {
+    for (const mode of snapshot.design?.modes ?? []) {
+        const failing = auditDesignContrast(snapshot.design!.rows, mode).filter(f => !f.pass);
+        if (failing.length) add(ctx, SiteFindingCode.LowContrast, `${failing.length} text and background pair(s) are hard to read in ${mode} mode.`);
+    }
+    for (const page of pages) {
+        let last = 0;
+        let h1 = 0;
+        walkSerialized(page.layout, n => {
+            const level = n.type === 'Heading' ? HEADING_LEVEL.exec(String(n.props['level'] ?? ''))?.[1] : undefined;
+            if (!level) return;
+            const l = Number(level);
+            if (l === 1) h1++;
+            if (last && l > last + 1) add(ctx, SiteFindingCode.HeadingOrder, `A heading on "${page.name}" skips a level (h${last} → h${l}).`, { pageId: page.id, nodeId: n.id });
+            last = l;
+        });
+        if (h1 > 1) add(ctx, SiteFindingCode.HeadingOrder, `"${page.name}" has ${h1} main headings (h1); one is clearer.`, { pageId: page.id });
+    }
+    eachNode(snapshot, pages, (n, where) => {
+        if (n.type !== 'Image') return;
+        const decorative = n.props['alt'] === '' && n.props['decorative'] === true;
+        const bound = n.bindings.some(b => b.prop === 'alt');
+        if (!decorative && !bound && !nonEmpty(n.props['alt'])) add(ctx, SiteFindingCode.ImageWithoutAlt, 'A picture has no description for people who cannot see it.', { ...where, nodeId: n.id });
+    });
+}
+
+function checkTokens(ctx: Ctx, snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>): void {
+    eachNode(snapshot, pages, (n, where) => {
+        if (!n.elementStyle) return;
+        const maps: Array<Record<string, unknown> | undefined> = [n.styleProps, ...Object.values(n.stateStyles ?? {}), ...Object.values(n.responsive ?? {}).map(l => l?.styleProps)];
+        const literal = maps.some(map => Object.entries(map ?? {}).some(([k, v]) =>
+            COLOUR_TRAITS.test(k) && LITERAL_COLOUR.test(String(v)) && !(k === 'borderColor' && n.styleProps['borderWidth'] === '0px')));
+        if (literal) add(ctx, SiteFindingCode.LiteralColour, 'An element paints a fixed colour, so a new look will not reach it.', { ...where, nodeId: n.id });
+    });
+}
+
+function checkActions(ctx: Ctx, snapshot: SiteAuditSnapshot, pages: ReadonlyArray<AuditPage>): void {
+    const routeExists = (route: unknown) => typeof route === 'string' && ctx.routes.some(r => routeMatches(r, route));
+    eachNode(snapshot, pages, (n, where) => {
+        if (LINKING_TYPES.has(n.type) && n.props['linkType'] === PAGE_LINK && !routeExists(n.props['pageRoute'])) {
+            add(ctx, SiteFindingCode.DeadLink, `"${String(n.props['label'] ?? n.props['content'] ?? n.label ?? n.type)}" links to ${String(n.props['pageRoute'] || 'no page')}, which is not a page of the site.`, { ...where, nodeId: n.id });
+        }
+        for (const ix of (n.interactions ?? []) as Array<{ actions?: Array<{ type?: string; target?: string; params?: Record<string, unknown>; disabled?: boolean }> }>) {
+            for (const action of ix?.actions ?? []) {
+                if (!action || action.disabled) continue;
+                const descriptor = ELEMENT_ACTION_DESCRIPTORS.find(d => d.type === action.type);
+                if (!descriptor) continue;
+                const types = descriptor.target?.types;
+                if (descriptor.target?.required && action.target !== SELF) {
+                    const targetType = action.target ? ctx.nodeIds.get(action.target) : undefined;
+                    if (!targetType || (types && !types.includes(targetType))) {
+                        add(ctx, SiteFindingCode.DeadDialogTarget, `"${n.label ?? n.type}" opens something that is no longer on the site.`, { ...where, nodeId: n.id });
+                    }
+                }
+                if (action.type === 'navigate' && action.params?.['navigateTo'] === PAGE_LINK && !routeExists(action.params?.['page'])) {
+                    add(ctx, SiteFindingCode.DeadLink, `"${n.label ?? n.type}" goes to a page the site does not have.`, { ...where, nodeId: n.id });
+                }
+                // A connector the snapshot does not say is usable is not: unknown is never "fine".
+                const connectors = descriptor.connector ? { [descriptor.connector]: snapshot.connectors[descriptor.connector] === true } : {};
+                const availability = resolveActionAvailability(descriptor, { connectors });
+                if (availability.state === 'connector-missing') {
+                    add(ctx, SiteFindingCode.ActionNeedsConnector, `"${n.label ?? n.type}" needs ${availability.connector} connected.`, { ...where, nodeId: n.id });
+                }
+            }
+        }
+    });
+}
+
+/** Run the eight checks. `pageId` narrows the page checks to the page being published; site-wide ones always run. */
+export function auditSite(snapshot: SiteAuditSnapshot, options: SiteAuditOptions = {}): SiteAudit {
+    const pages = options.pageId ? snapshot.pages.filter(p => p.id === options.pageId) : snapshot.pages;
+    const nodeIds = new Map<string, string>();
+    eachNode(snapshot, snapshot.pages, n => nodeIds.set(n.id, n.type));
+    const ctx: Ctx = { out: [], routes: snapshot.pages.map(p => p.route), nodeIds };
+    checkNavigation(ctx, snapshot);
+    const personal = checkForms(ctx, snapshot, pages);
+    checkConsent(ctx, snapshot);
+    checkSeo(ctx, pages);
+    checkFacts(ctx, snapshot, pages, personal);
+    checkAccessibility(ctx, snapshot, pages);
+    checkTokens(ctx, snapshot, pages);
+    checkActions(ctx, snapshot, pages);
+    const checks = SITE_CHECKS.map(id => {
+        const findings = ctx.out.filter(f => f.check === id);
+        return { id, passed: !findings.some(f => f.severity !== CheckSeverity.Warn), findings };
+    });
+    return {
+        checks,
+        blocking: ctx.out.filter(f => f.severity === CheckSeverity.Block).length,
+        asking: ctx.out.filter(f => f.severity === CheckSeverity.Ask).length,
+    };
+}
+
+/** What a publish request must acknowledge: every ASK finding's code (a BLOCK cannot be acknowledged). */
+export function requiredAcknowledgements(audit: SiteAudit): SiteFindingCode[] {
+    return [...new Set(audit.checks.flatMap(c => c.findings).filter(f => f.severity === CheckSeverity.Ask).map(f => f.code))];
+}
+
+/** The publish verdict: blocked (never acknowledgeable), needs these acknowledgements, or free to go. */
+export function publishVerdict(audit: SiteAudit, acknowledged: ReadonlyArray<string> = []): { ok: boolean; blocked: boolean; missing: SiteFindingCode[] } {
+    const missing = requiredAcknowledgements(audit).filter(code => !acknowledged.includes(code));
+    const blocked = audit.blocking > 0;
+    return { ok: !blocked && missing.length === 0, blocked, missing };
+}

package/src/generation-core/json-schema.ts

@@ -0,0 +1,97 @@
+import { requiredShapeKeys, ShapeEntry, shapeKeys } from './shape-check';
+
+/**
+ * The ONE set of builders every structured-output format is written with (AI plan §3c, M0-5 / M1-1 / M1-3 / M1-5):
+ * the SiteAnalysis, the reading, the Site Plan and the plan edits. Each object is built FROM a documented shape table
+ * (`shape-check`): its keys are the table's keys, the required ones are the table's required ones, each described in
+ * the table's own words — and a builder handed a key list that disagrees with its table THROWS, so a shape that gains
+ * a key cannot ship a format that silently lacks it. The subset is the strictest both providers' native strict modes
+ * accept (Anthropic `output_config.format`, OpenRouter `json_schema` + `strict`): every object closed
+ * (`additionalProperties: false`), unions as `anyOf`, single values as a one-entry `enum`, no length / count / number
+ * bounds, no `$ref`. The format is a hint the provider enforces; the shared validator stays the gate.
+ */
+
+export type JsonSchema = { [key: string]: unknown };
+
+const OPTIONAL_MARK = '?';
+
+export class JsonSchemaShapeError extends Error {}
+
+export const jsonText = (): JsonSchema => ({ type: 'string' });
+export const jsonBoolean = (): JsonSchema => ({ type: 'boolean' });
+export const jsonInteger = (): JsonSchema => ({ type: 'integer' });
+export const jsonOneOf = (values: ReadonlyArray<string>): JsonSchema => ({ type: 'string', enum: [...values] });
+export const jsonListOf = (items: JsonSchema): JsonSchema => ({ type: 'array', items });
+export const jsonAnyOf = (options: ReadonlyArray<JsonSchema>): JsonSchema => ({ anyOf: [...options] });
+
+/** A closed object with exactly these properties. */
+export function jsonClosedObject(properties: Record<string, JsonSchema>, required: ReadonlyArray<string>, description?: string): JsonSchema {
+    return {
+        type: 'object',
+        properties,
+        required: [...required],
+        additionalProperties: false,
+        ...(description ? { description } : {}),
+    };
+}
+
+/** The table's own words for a key (`key` or `key?`). */
+export function describeShapeKey(entry: ShapeEntry, key: string): string {
+    return String(entry[key] ?? entry[`${key}${OPTIONAL_MARK}`] ?? '');
+}
+
+/** An entry's `[name]` keys (the object's own field names) written as ONE list on the wire — no strict mode can say
+ *  "any key", so the map travels as `[{ name, value }]` under `key` and the decoder turns it back. */
+export interface DynamicKeysAsList {
+    /** The wire key holding the list. */
+    key: string;
+    /** The list's schema. */
+    schema: JsonSchema;
+}
+
+/**
+ * An object of one shape-table entry: exactly its fixed keys, its required keys required, each described by the
+ * table; an entry's `[name]` keys are not object keys — `dynamic` writes them as one list. Throws when the properties
+ * given are not the table's keys.
+ */
+export function jsonShapedObject(entry: ShapeEntry, properties: Record<string, JsonSchema>, name = 'shape', dynamic?: DynamicKeysAsList): JsonSchema {
+    const expected = [...shapeKeys(entry)].sort();
+    const given = Object.keys(properties).sort();
+    if (expected.join() !== given.join()) {
+        throw new JsonSchemaShapeError(`${name}: the format's keys (${given.join(', ')}) are not the shape table's (${expected.join(', ')})`);
+    }
+    const dynamicKey = Object.keys(entry).find(k => /^\[[^\]]+\]\??$/.test(k));
+    if (!!dynamic !== !!dynamicKey) throw new JsonSchemaShapeError(`${name}: ${dynamicKey ? `its ${dynamicKey} keys need a list on the wire` : 'it has no [name] keys to list'}`);
+    const described = Object.fromEntries(Object.entries(properties).map(([key, schema]) => [key, { ...schema, description: describeShapeKey(entry, key) }]));
+    if (dynamic && dynamicKey) described[dynamic.key] = { ...dynamic.schema, description: `${dynamicKey}: ${entry[dynamicKey]}` };
+    return jsonClosedObject(described, requiredShapeKeys(entry));
+}
+
+/** Every keyword a schema uses — what a spec checks against the strict subset. */
+export function jsonSchemaKeywords(node: unknown, out = new Set<string>()): Set<string> {
+    if (Array.isArray(node)) node.forEach(n => jsonSchemaKeywords(n, out));
+    else if (node && typeof node === 'object') {
+        for (const [k, v] of Object.entries(node)) {
+            out.add(k);
+            if (k === 'properties') Object.values(v as object).forEach(p => jsonSchemaKeywords(p, out));
+            else if (k !== 'enum' && k !== 'required' && k !== 'description') jsonSchemaKeywords(v, out);
+        }
+    }
+    return out;
+}
+
+/** The keywords the strict subset never uses. */
+export const JSON_SCHEMA_BANNED_KEYWORDS: ReadonlyArray<string> = [
+    'minLength', 'maxLength', 'minimum', 'maximum', 'minItems', 'maxItems', 'pattern', 'oneOf', '$ref', 'const', 'format',
+];
+
+/** Every object node of a schema (through properties, items and anyOf). */
+export function jsonSchemaObjects(node: unknown, out: JsonSchema[] = []): JsonSchema[] {
+    if (!node || typeof node !== 'object') return out;
+    const n = node as JsonSchema;
+    if (n['type'] === 'object') out.push(n);
+    for (const p of Object.values((n['properties'] as object | undefined) ?? {})) jsonSchemaObjects(p, out);
+    if (n['items']) jsonSchemaObjects(n['items'], out);
+    for (const option of (n['anyOf'] as unknown[] | undefined) ?? []) jsonSchemaObjects(option, out);
+    return out;
+}