@texuli/deck 0.0.0-stage → 0.5.0

package/dist/schema/diagnostics.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The one issue shape of the deck engine (model-v2 §3.9): JSON validation, the
+ * Markdown dialect, lint and the untrusted loader all report `DeckDiagnostic`.
+ * This module owns the shape, the path formats and the schema kit's own codes.
+ */
+/** One step of a path: an object key or an array index. */
+export type PathSegment = string | number;
+export type DiagnosticSeverity = 'error' | 'warning';
+/** A source span, set by the Markdown dialect (line and column are 1-based). */
+export interface DiagnosticSource {
+    line: number;
+    column: number;
+    endLine?: number;
+    endColumn?: number;
+}
+/**
+ * One issue. `path` is canonical; `jsonPath` (`$.slides[2].props.title`) and
+ * `pointer` (RFC 6901, `/slides/2/props/title`) are derived from it. The model
+ * narrows `Code` and `Rule` to its documented unions.
+ */
+export interface DeckDiagnostic<Code extends string = string, Rule extends string = string> {
+    code: Code;
+    severity: DiagnosticSeverity;
+    path: PathSegment[];
+    jsonPath: string;
+    pointer: string;
+    message: string;
+    /** An actionable hint. */
+    fix?: string;
+    slideId?: string;
+    source?: DiagnosticSource;
+    /** Lint only: the rule that raised the issue. */
+    rule?: Rule;
+}
+/** The schema kit's own stable codes (kebab-case; the model adds its own). */
+export declare const SCHEMA_CODES: Readonly<{
+    readonly invalidType: "invalid-type";
+    readonly required: "required";
+    readonly unknownKey: "unknown-key";
+    readonly tooShort: "too-short";
+    readonly tooLong: "too-long";
+    readonly tooFew: "too-few";
+    readonly tooMany: "too-many";
+    readonly outOfRange: "out-of-range";
+    readonly notInteger: "not-integer";
+    readonly notFinite: "not-finite";
+    readonly pattern: "pattern";
+    readonly reserved: "reserved";
+    readonly enum: "enum";
+    readonly unknownKind: "unknown-kind";
+    readonly unsafeText: "unsafe-text";
+    readonly unsafeKey: "unsafe-key";
+    readonly tooDeep: "too-deep";
+    readonly cycle: "cycle";
+    readonly tooLarge: "too-large";
+    readonly invalidInput: "invalid-input";
+}>;
+export type SchemaCode = (typeof SCHEMA_CODES)[keyof typeof SCHEMA_CODES];
+/** At most this many diagnostics are kept by default; the rest set `truncated`. */
+export declare const MAX_DIAGNOSTICS = 200;
+/** `['slides', 2, 'props', 'title']` → `$.slides[2].props.title`; odd keys use `['…']`. */
+export declare function toJsonPath(path: readonly PathSegment[]): string;
+/** RFC 6901 JSON Pointer: `~` → `~0`, `/` → `~1`; the root is `''`. */
+export declare function toPointer(path: readonly PathSegment[]): string;
+export interface DiagnosticExtra {
+    severity?: DiagnosticSeverity;
+    fix?: string;
+    slideId?: string;
+    source?: DiagnosticSource;
+    rule?: string;
+}
+/** Build a diagnostic with both derived path forms (the path is copied). */
+export declare function createDiagnostic<Code extends string>(code: Code, message: string, path: readonly PathSegment[], extra?: DiagnosticExtra): DeckDiagnostic<Code>;
+/**
+ * One line for logs, CLIs and agent feedback:
+ * `error unknown-key at $.style.colour (3:5): Unknown key "colour". Fix: …`.
+ */
+export declare function formatDiagnostic(diagnostic: DeckDiagnostic): string;

package/dist/schema/diagnostics.js

@@ -0,0 +1,81 @@
+/**
+ * The one issue shape of the deck engine (model-v2 §3.9): JSON validation, the
+ * Markdown dialect, lint and the untrusted loader all report `DeckDiagnostic`.
+ * This module owns the shape, the path formats and the schema kit's own codes.
+ */
+/** The schema kit's own stable codes (kebab-case; the model adds its own). */
+export const SCHEMA_CODES = Object.freeze({
+    invalidType: 'invalid-type',
+    required: 'required',
+    unknownKey: 'unknown-key',
+    tooShort: 'too-short',
+    tooLong: 'too-long',
+    tooFew: 'too-few',
+    tooMany: 'too-many',
+    outOfRange: 'out-of-range',
+    notInteger: 'not-integer',
+    notFinite: 'not-finite',
+    pattern: 'pattern',
+    reserved: 'reserved',
+    enum: 'enum',
+    unknownKind: 'unknown-kind',
+    unsafeText: 'unsafe-text',
+    unsafeKey: 'unsafe-key',
+    tooDeep: 'too-deep',
+    cycle: 'cycle',
+    tooLarge: 'too-large',
+    invalidInput: 'invalid-input',
+});
+/** At most this many diagnostics are kept by default; the rest set `truncated`. */
+export const MAX_DIAGNOSTICS = 200;
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** `['slides', 2, 'props', 'title']` → `$.slides[2].props.title`; odd keys use `['…']`. */
+export function toJsonPath(path) {
+    let out = '$';
+    for (const segment of path) {
+        if (typeof segment === 'number')
+            out += `[${segment}]`;
+        else if (IDENTIFIER.test(segment))
+            out += `.${segment}`;
+        else
+            out += `['${segment.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}']`;
+    }
+    return out;
+}
+/** RFC 6901 JSON Pointer: `~` → `~0`, `/` → `~1`; the root is `''`. */
+export function toPointer(path) {
+    let out = '';
+    for (const segment of path) {
+        out += `/${String(segment).replaceAll('~', '~0').replaceAll('/', '~1')}`;
+    }
+    return out;
+}
+/** Build a diagnostic with both derived path forms (the path is copied). */
+export function createDiagnostic(code, message, path, extra = {}) {
+    const diagnostic = {
+        code,
+        severity: extra.severity ?? 'error',
+        path: [...path],
+        jsonPath: toJsonPath(path),
+        pointer: toPointer(path),
+        message,
+    };
+    if (extra.fix !== undefined)
+        diagnostic.fix = extra.fix;
+    if (extra.slideId !== undefined)
+        diagnostic.slideId = extra.slideId;
+    if (extra.source !== undefined)
+        diagnostic.source = { ...extra.source };
+    if (extra.rule !== undefined)
+        diagnostic.rule = extra.rule;
+    return diagnostic;
+}
+/**
+ * One line for logs, CLIs and agent feedback:
+ * `error unknown-key at $.style.colour (3:5): Unknown key "colour". Fix: …`.
+ */
+export function formatDiagnostic(diagnostic) {
+    const where = diagnostic.source ? ` (${diagnostic.source.line}:${diagnostic.source.column})` : '';
+    const fix = diagnostic.fix ? ` Fix: ${diagnostic.fix}` : '';
+    return `${diagnostic.severity} ${diagnostic.code} at ${diagnostic.jsonPath}${where}: ${diagnostic.message}${fix}`;
+}

package/dist/schema/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @texuli/deck/schema: the owned schema kit (ADR-009, model-v2 §2.1 option B).
+ *
+ * Combinators are data: `t.*` builds frozen plain objects describing a shape,
+ * `validate` walks them (all issues, `DeckDiagnostic` with `jsonPath` and
+ * RFC 6901 `pointer`, capped at 200, never throws), `toJsonSchema` writes
+ * JSON Schema 2020-12 from the same data, and `Infer<typeof S>` gives the
+ * TypeScript type. String lengths count Unicode code points everywhere.
+ */
+export { type CodeOptions, type Described, JSON_DEFAULTS, type JsonOptions, type LazyOptions, type NumberOptions, type ObjectOptions, type OptionalOptions, objectOf, type RecordOptions, type RefineOptions, type SizeOptions, type StringOptions, t, UNSAFE_KEYS, type UnionOptions, } from './builders.js';
+export { createDiagnostic, type DeckDiagnostic, type DiagnosticExtra, type DiagnosticSeverity, type DiagnosticSource, formatDiagnostic, MAX_DIAGNOSTICS, type PathSegment, SCHEMA_CODES, type SchemaCode, toJsonPath, toPointer, } from './diagnostics.js';
+export { codePointLength, unsafeTextIndex } from './internal.js';
+export { JSON_SCHEMA_DIALECT, type JsonSchema, type JsonSchemaOptions, toJsonSchema, } from './json-schema.js';
+export type { ArraySchema, BooleanSchema, EnumSchema, Infer, InferShape, JsonValue, JsonValueSchema, LazySchema, LiteralSchema, LiteralValue, NullableSchema, NullSchema, NumberSchema, ObjectSchema, OptionalSchema, RecordSchema, RefineContext, RefineIssue, RefineSchema, Schema, SchemaKind, SchemaNode, Shape, StringSchema, TextMode, UnionSchema, } from './types.js';
+export { DEFAULT_MAX_DEPTH, DEFAULT_MAX_NODES, is, type SchemaNormalization, type ValidateOptions, type ValidateResult, validate, } from './validate.js';

package/dist/schema/index.js

@@ -0,0 +1,14 @@
+/**
+ * @texuli/deck/schema: the owned schema kit (ADR-009, model-v2 §2.1 option B).
+ *
+ * Combinators are data: `t.*` builds frozen plain objects describing a shape,
+ * `validate` walks them (all issues, `DeckDiagnostic` with `jsonPath` and
+ * RFC 6901 `pointer`, capped at 200, never throws), `toJsonSchema` writes
+ * JSON Schema 2020-12 from the same data, and `Infer<typeof S>` gives the
+ * TypeScript type. String lengths count Unicode code points everywhere.
+ */
+export { JSON_DEFAULTS, objectOf, t, UNSAFE_KEYS, } from "./builders.js";
+export { createDiagnostic, formatDiagnostic, MAX_DIAGNOSTICS, SCHEMA_CODES, toJsonPath, toPointer, } from "./diagnostics.js";
+export { codePointLength, unsafeTextIndex } from "./internal.js";
+export { JSON_SCHEMA_DIALECT, toJsonSchema, } from "./json-schema.js";
+export { DEFAULT_MAX_DEPTH, DEFAULT_MAX_NODES, is, validate, } from "./validate.js";

package/dist/schema/internal.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Helpers shared by the builders, the validator and the JSON Schema emitter.
+ * Derived lookups (compiled patterns, discriminator maps) live in caches here
+ * so the schema nodes themselves stay plain frozen data.
+ */
+import type { LiteralValue, ObjectSchema, Schema, TextMode, UnionSchema } from './types.js';
+/** Keys never accepted as data, in any object or record (prototype pollution). */
+export declare const UNSAFE_KEYS: readonly string[];
+export declare function isUnsafeKey(key: string): boolean;
+/** Length in Unicode code points (a surrogate pair counts once, a lone surrogate once). */
+export declare function codePointLength(value: string): number;
+/**
+ * True when `value` has more than `max` code points. Strings longer than
+ * `2 × max` UTF-16 units are refused without counting.
+ */
+export declare function exceedsCodePoints(value: string, max: number): boolean;
+/** Index of the first character `mode` refuses, or `-1`. */
+export declare function unsafeTextIndex(value: string, mode: TextMode): number;
+/** The same rule as `unsafeTextIndex`, as a JSON Schema pattern source. */
+export declare function textPattern(mode: TextMode): string;
+export declare function describeChar(value: string, index: number): string;
+/** Patterns compile once, with the `u` flag (no `g`/`y`, so `test` is stateless). */
+export declare function compilePattern(source: string): RegExp;
+/** Follow refine wrappers down to an object schema, if there is one. */
+export declare function unwrapObject(schema: Schema): ObjectSchema | undefined;
+export interface DiscriminatorIndex {
+    /** Discriminator value → option index. */
+    readonly map: ReadonlyMap<LiteralValue, number>;
+    /** Options whose discriminator is a plain string schema, tried in order. */
+    readonly fallbacks: readonly number[];
+    /** Every mapped value, in declaration order. */
+    readonly values: readonly LiteralValue[];
+}
+/** Build (once) the lookup of a discriminated union; throws on a malformed union. */
+export declare function discriminatorIndex(union: UnionSchema): DiscriminatorIndex;
+export type JsonType = 'string' | 'number' | 'boolean' | 'null' | 'array' | 'object';
+/** The JSON types a schema can accept, used to pick the relevant union option. */
+export declare function acceptedTypes(schema: Schema): ReadonlySet<JsonType>;
+/** The JSON type name of a value, or a JS name (`undefined`, `function`…) for non-JSON. */
+export declare function typeName(value: unknown): string;

package/dist/schema/internal.js

@@ -0,0 +1,209 @@
+/** Keys never accepted as data, in any object or record (prototype pollution). */
+export const UNSAFE_KEYS = Object.freeze([
+    '__proto__',
+    'constructor',
+    'prototype',
+]);
+const UNSAFE = new Set(UNSAFE_KEYS);
+export function isUnsafeKey(key) {
+    return UNSAFE.has(key);
+}
+/** Length in Unicode code points (a surrogate pair counts once, a lone surrogate once). */
+export function codePointLength(value) {
+    let count = 0;
+    for (let i = 0; i < value.length; i++) {
+        const unit = value.charCodeAt(i);
+        if (unit >= 0xd800 && unit <= 0xdbff && i + 1 < value.length) {
+            const next = value.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff)
+                i++;
+        }
+        count++;
+    }
+    return count;
+}
+/**
+ * True when `value` has more than `max` code points. Strings longer than
+ * `2 × max` UTF-16 units are refused without counting.
+ */
+export function exceedsCodePoints(value, max) {
+    if (value.length <= max)
+        return false;
+    if (value.length > max * 2)
+        return true;
+    return codePointLength(value) > max;
+}
+/** Index of the first character `mode` refuses, or `-1`. */
+export function unsafeTextIndex(value, mode) {
+    const multiline = mode === 'multiline';
+    for (let i = 0; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        if (c < 0x20) {
+            if (multiline && (c === 0x09 || c === 0x0a || c === 0x0d))
+                continue;
+            return i;
+        }
+        if (c < 0x7f)
+            continue;
+        if (c <= 0x9f)
+            return i;
+        if (c < 0x2028)
+            continue;
+        if (c <= 0x2029) {
+            if (multiline)
+                continue;
+            return i;
+        }
+        if ((c >= 0x202a && c <= 0x202e) || (c >= 0x2066 && c <= 0x2069))
+            return i;
+    }
+    return -1;
+}
+/** The same rule as `unsafeTextIndex`, as a JSON Schema pattern source. */
+export function textPattern(mode) {
+    return mode === 'multiline'
+        ? '^[^\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F\\u007F-\\u009F\\u202A-\\u202E\\u2066-\\u2069]*$'
+        : '^[^\\u0000-\\u001F\\u007F-\\u009F\\u2028\\u2029\\u202A-\\u202E\\u2066-\\u2069]*$';
+}
+export function describeChar(value, index) {
+    const code = value.codePointAt(index) ?? 0;
+    return `U+${code.toString(16).toUpperCase().padStart(4, '0')}`;
+}
+const patterns = new Map();
+/** Patterns compile once, with the `u` flag (no `g`/`y`, so `test` is stateless). */
+export function compilePattern(source) {
+    let compiled = patterns.get(source);
+    if (!compiled) {
+        compiled = new RegExp(source, 'u');
+        patterns.set(source, compiled);
+    }
+    return compiled;
+}
+/** Follow refine wrappers down to an object schema, if there is one. */
+export function unwrapObject(schema) {
+    let node = schema;
+    for (let guard = 0; guard < 64; guard++) {
+        if (node.kind === 'object')
+            return node;
+        if (node.kind === 'refine')
+            node = node.inner;
+        else
+            return undefined;
+    }
+    return undefined;
+}
+const discriminators = new WeakMap();
+/** Build (once) the lookup of a discriminated union; throws on a malformed union. */
+export function discriminatorIndex(union) {
+    const cached = discriminators.get(union);
+    if (cached)
+        return cached;
+    const key = union.discriminator;
+    if (key === undefined)
+        throw new TypeError('The union has no discriminator.');
+    const map = new Map();
+    const fallbacks = [];
+    const values = [];
+    union.options.forEach((option, index) => {
+        const object = unwrapObject(option);
+        const field = object?.shape[key];
+        if (!field) {
+            throw new TypeError(`Union option ${index} is not an object with a "${key}" field.`);
+        }
+        const add = (value) => {
+            if (map.has(value)) {
+                throw new TypeError(`Union options share the "${key}" value ${JSON.stringify(value)}.`);
+            }
+            map.set(value, index);
+            values.push(value);
+        };
+        if (field.kind === 'literal')
+            add(field.value);
+        else if (field.kind === 'enum')
+            for (const value of field.values)
+                add(value);
+        else if (field.kind === 'string')
+            fallbacks.push(index);
+        else {
+            throw new TypeError(`Union option ${index}: "${key}" must be a literal, an enum or a string schema.`);
+        }
+    });
+    const index = Object.freeze({ map, fallbacks, values });
+    discriminators.set(union, index);
+    return index;
+}
+const ALL_TYPES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'null',
+    'array',
+    'object',
+]);
+const accepted = new WeakMap();
+/** The JSON types a schema can accept, used to pick the relevant union option. */
+export function acceptedTypes(schema) {
+    const cached = accepted.get(schema);
+    if (cached)
+        return cached;
+    const node = schema;
+    let types;
+    switch (node.kind) {
+        case 'string':
+        case 'enum':
+            types = new Set(['string']);
+            break;
+        case 'number':
+            types = new Set(['number']);
+            break;
+        case 'boolean':
+            types = new Set(['boolean']);
+            break;
+        case 'null':
+            types = new Set(['null']);
+            break;
+        case 'literal':
+            types = new Set([node.value === null ? 'null' : typeof node.value]);
+            break;
+        case 'array':
+            types = new Set(['array']);
+            break;
+        case 'object':
+        case 'record':
+            types = new Set(['object']);
+            break;
+        case 'union': {
+            const all = new Set();
+            for (const option of node.options)
+                for (const type of acceptedTypes(option))
+                    all.add(type);
+            types = all;
+            break;
+        }
+        case 'nullable':
+            types = new Set([...acceptedTypes(node.inner), 'null']);
+            break;
+        case 'optional':
+        case 'refine':
+            types = acceptedTypes(node.inner);
+            break;
+        default:
+            // lazy (resolving it here could recurse forever) and json accept anything.
+            types = ALL_TYPES;
+    }
+    accepted.set(schema, types);
+    return types;
+}
+/** The JSON type name of a value, or a JS name (`undefined`, `function`…) for non-JSON. */
+export function typeName(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value !== 'object')
+        return typeof value;
+    try {
+        return Array.isArray(value) ? 'array' : 'object';
+    }
+    catch {
+        return 'object';
+    }
+}

package/dist/schema/json-schema.d.ts

@@ -0,0 +1,12 @@
+import type { Schema } from './types.js';
+export type JsonSchema = {
+    [key: string]: unknown;
+};
+export declare const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+export interface JsonSchemaOptions {
+    $id?: string;
+    title?: string;
+    description?: string;
+}
+/** The JSON Schema 2020-12 document for `schema`. */
+export declare function toJsonSchema(schema: Schema, options?: JsonSchemaOptions): JsonSchema;

package/dist/schema/json-schema.js

@@ -0,0 +1,213 @@
+/**
+ * JSON Schema 2020-12 from the same schema data the validator walks, so the
+ * export never drifts. Lengths are code points on both sides (JSON Schema
+ * `minLength`/`maxLength` count code points). Refinements and trimming cannot
+ * be expressed, so they are documented in `description`.
+ */
+import { discriminatorIndex, textPattern, UNSAFE_KEYS } from "./internal.js";
+export const JSON_SCHEMA_DIALECT = 'https://json-schema.org/draft/2020-12/schema';
+/** The JSON Schema 2020-12 document for `schema`. */
+export function toJsonSchema(schema, options = {}) {
+    const state = { defs: {}, names: new Map() };
+    const body = emit(schema, state);
+    const doc = { $schema: JSON_SCHEMA_DIALECT };
+    if (options.$id !== undefined)
+        doc.$id = options.$id;
+    if (options.title !== undefined)
+        doc.title = options.title;
+    Object.assign(doc, body);
+    if (options.description !== undefined)
+        doc.description = options.description;
+    if (Object.keys(state.defs).length > 0)
+        doc.$defs = state.defs;
+    return doc;
+}
+function described(out, description) {
+    if (description === undefined)
+        return out;
+    const existing = out.description;
+    out.description = typeof existing === 'string' ? `${description} ${existing}` : description;
+    return out;
+}
+function appendDescription(out, text) {
+    const existing = out.description;
+    out.description = typeof existing === 'string' ? `${existing} ${text}` : text;
+    return out;
+}
+function emitString(node) {
+    const out = { type: 'string' };
+    if (node.min !== undefined)
+        out.minLength = node.min;
+    if (node.max !== undefined)
+        out.maxLength = node.max;
+    const patterns = [];
+    if (node.pattern !== undefined)
+        patterns.push(node.pattern);
+    if (node.text !== undefined)
+        patterns.push(textPattern(node.text));
+    if (patterns.length === 1)
+        out.pattern = patterns[0];
+    else if (patterns.length > 1)
+        out.allOf = patterns.map((pattern) => ({ pattern }));
+    if (node.not && node.not.length > 0)
+        out.not = { enum: [...node.not] };
+    described(out, node.description);
+    if (node.trim)
+        appendDescription(out, 'Leading and trailing whitespace is trimmed before the length check.');
+    return out;
+}
+function emit(node, state) {
+    switch (node.kind) {
+        case 'string':
+            return emitString(node);
+        case 'number': {
+            const out = { type: node.int ? 'integer' : 'number' };
+            if (node.min !== undefined)
+                out.minimum = node.min;
+            if (node.max !== undefined)
+                out.maximum = node.max;
+            return described(out, node.description);
+        }
+        case 'boolean':
+            return described({ type: 'boolean' }, node.description);
+        case 'null':
+            return described({ type: 'null' }, node.description);
+        case 'literal':
+            return described({ const: node.value }, node.description);
+        case 'enum':
+            return described({ type: 'string', enum: [...node.values] }, node.description);
+        case 'array': {
+            const out = { type: 'array', items: emit(node.item, state) };
+            if (node.min !== undefined)
+                out.minItems = node.min;
+            if (node.max !== undefined)
+                out.maxItems = node.max;
+            return described(out, node.description);
+        }
+        case 'object': {
+            const properties = {};
+            const required = [];
+            for (const key of Object.keys(node.shape)) {
+                const field = node.shape[key];
+                if (field.kind === 'optional') {
+                    const property = described(emit(field.inner, state), field.description);
+                    if (field.hasDefault)
+                        property.default = field.default;
+                    properties[key] = property;
+                }
+                else {
+                    properties[key] = emit(field, state);
+                    required.push(key);
+                }
+            }
+            const out = { type: 'object', properties };
+            if (required.length > 0)
+                out.required = required;
+            if (node.strict)
+                out.additionalProperties = false;
+            return described(out, node.description);
+        }
+        case 'record': {
+            const names = node.key ? emitString(node.key) : { type: 'string' };
+            names.not = { enum: [...UNSAFE_KEYS, ...(node.key?.not ?? [])] };
+            const out = {
+                type: 'object',
+                propertyNames: names,
+                additionalProperties: emit(node.value, state),
+            };
+            if (node.min !== undefined)
+                out.minProperties = node.min;
+            if (node.max !== undefined)
+                out.maxProperties = node.max;
+            return described(out, node.description);
+        }
+        case 'union': {
+            if (node.discriminator === undefined) {
+                return described({ anyOf: node.options.map((option) => emit(option, state)) }, node.description);
+            }
+            const key = node.discriminator;
+            const index = discriminatorIndex(node);
+            const fallbacks = new Set(index.fallbacks);
+            const oneOf = node.options.map((option, i) => {
+                const out = emit(option, state);
+                const properties = out.properties;
+                const field = properties?.[key];
+                if (fallbacks.has(i) && field && index.values.length > 0) {
+                    // A pattern branch must not also match the listed values, or oneOf breaks.
+                    const refused = [...index.values, ...(field.not?.enum ?? [])];
+                    field.not = { enum: refused };
+                }
+                return out;
+            });
+            return described({ oneOf }, node.description);
+        }
+        case 'nullable':
+            return described({ anyOf: [emit(node.inner, state), { type: 'null' }] }, node.description);
+        case 'optional':
+            return described(emit(node.inner, state), node.description);
+        case 'lazy':
+            return emitLazy(node, state);
+        case 'refine': {
+            const out = described(emit(node.inner, state), node.description);
+            if (node.description === undefined)
+                appendDescription(out, `Checked by rule "${node.code}".`);
+            else
+                appendDescription(out, `(rule "${node.code}")`);
+            return out;
+        }
+        case 'json':
+            return emitJson(node, state);
+        default:
+            return {};
+    }
+}
+function uniqueName(state, base) {
+    let name = base;
+    for (let i = 2; Object.hasOwn(state.defs, name); i++)
+        name = `${base}${i}`;
+    return name;
+}
+function emitLazy(node, state) {
+    let name = state.names.get(node);
+    if (name === undefined) {
+        name = uniqueName(state, node.name ?? 'Lazy');
+        state.names.set(node, name);
+        state.defs[name] = {}; // placeholder: a recursive reference resolves to it
+        let target;
+        try {
+            target = node.get();
+        }
+        catch {
+            target = undefined; // unresolvable: the definition stays `{}` (accepts anything)
+        }
+        if (target)
+            state.defs[name] = emit(target, state);
+    }
+    return described({ $ref: `#/$defs/${name}` }, node.description);
+}
+/** Bounded JSON unrolls into one definition per remaining depth (exact limits). */
+function emitJson(node, state) {
+    const id = `Json_d${node.depth}_k${node.maxKeys}_i${node.maxItems}_s${node.maxString}_n${node.maxKeyLength}${node.text ? `_${node.text}` : ''}`;
+    const name = (depth) => `${id}_${depth}`;
+    if (!Object.hasOwn(state.defs, name(node.depth))) {
+        const text = { type: 'string', maxLength: node.maxString };
+        if (node.text !== undefined)
+            text.pattern = textPattern(node.text);
+        const scalars = [text, { type: 'number' }, { type: 'boolean' }, { type: 'null' }];
+        for (let depth = 0; depth <= node.depth; depth++) {
+            const options = [...scalars.map((scalar) => ({ ...scalar }))];
+            if (depth > 0) {
+                const child = { $ref: `#/$defs/${name(depth - 1)}` };
+                options.push({ type: 'array', maxItems: node.maxItems, items: child });
+                options.push({
+                    type: 'object',
+                    maxProperties: node.maxKeys,
+                    propertyNames: { maxLength: node.maxKeyLength, not: { enum: [...UNSAFE_KEYS] } },
+                    additionalProperties: child,
+                });
+            }
+            state.defs[name(depth)] = { anyOf: options };
+        }
+    }
+    return described({ $ref: `#/$defs/${name(node.depth)}` }, node.description);
+}