ata-validator 1.55.0 → 1.57.0

package/README.md

@@ -46,9 +46,19 @@ or set `ATA_NO_NATIVE=1` at runtime. Typical schemas compile to specialized JS;
 In Cloudflare Workers and Vercel Edge, where generated code cannot run, `ata-validator`
 resolves to an entry without the code generator through the `workerd` and `edge-light` export
 conditions: the same names and answers, and a Worker bundled by wrangler goes from 179.1 to
-70.4 KiB gzipped. On a page whose Content-Security-Policy blocks `unsafe-eval`, or in a
-browser extension, no condition tells the bundler, so import `ata-validator/lite` there: the
-same `Validator` on the interpreted engine alone.
+70.4 KiB gzipped.
+
+In a browser bundle the code generator is not part of the page. Every schema starts on the
+interpreted engine, which gives the same answers, and a validator called a thousand times within
+a second loads the generator in the background, through a dynamic import that Vite, webpack and
+Rollup put in a chunk of their own, and is rebuilt on generated code when the page is idle. A
+form, checked as the user types, never loads it. On a react-jsonschema-form page this takes the validator's
+share of the first load from 134.7 KB to about 57 KB gzipped; the generator chunk is about 78 KB
+more when it does load. Where `unsafe-eval` is blocked, on a page with a strict
+Content-Security-Policy or in a Manifest V3 extension, it is never fetched and every schema
+stays on the interpreted engine. To have generated code from the first call, import
+`ata-validator/codegen` once; it also makes `parse()` available in the browser, which otherwise
+waits for the generator.
 
 On Deno the same package is `npm:ata-validator` or `jsr:@ata/validator`; the JSR package
 re-exports the npm one at the same version, and CI runs the official suite under Deno. The
@@ -574,8 +584,11 @@ CLI options:
 | `-f, --format <fmt>` | `esm` | `esm` or `cjs` |
 | `--name <TypeName>` | from filename | Root type name in the `.d.ts` |
 | `--abort-early` | off | Generate the stub-error variant, about a third of the source |
+| `--order` | off | Hand errors out in the runtime's order (schema declaration order), not the order the collector found them in |
 | `--no-types` | off | Skip the `.d.mts` / `.d.cts` output |
 
+A module answers `validate()` as the runtime does, with two differences a caller reading the module directly should know. The runtime fills in `default` values before it checks (`useDefaults` is on unless turned off), and the module does not: where the schema declares a default the module exports `applyDefaults(data)`, the runtime's own pass, to call first. And the module returns its errors in the order its collector found them, which can put a field's `format` error before its `pattern` error, or behind a `$ref` a definition's `required` before its `properties`; `--order` sorts them as the runtime does. It is off by default because it costs bytes: 225 more gzipped for an eight-field form, about 1 KB for a small schema with references, whose key skeleton the module then carries, and 12.6% over 267 SchemaStore schemas. With both, a module matched the runtime's verdict, filled data and error list, in order, on every case of the official suites it compiles (1,500 groups, 5,324 cases across six dialects) and on 1,952 of SchemaStore's sample documents. `fromCompiled()` and modules that share the error runtime sort already and need neither.
+
 For a project with many schemas, `ata build <glob>` compiles them all in one command:
 
 ```bash

package/bin/ata.js

@@ -30,6 +30,9 @@ Compile options:
   --abort-early           Use stub errors (smallest bundle)
   --one-pass              Report errors with the runtime's one-pass function: faster on
                           rejected documents, a module 1.3 to 1.7x the size
+  --order                 Hand errors out in the runtime's order (schema declaration
+                          order) rather than the order they were found in; adds a sort,
+                          and for a schema with $ref its key skeleton
   --source                Embed schema source map (default in development)
   --no-source             Omit source map (default in production, NODE_ENV=production)
 
@@ -45,6 +48,10 @@ Build options:
   --abort-early           Use stub errors (smallest bundle)
   --one-pass              Report errors with the runtime's one-pass function: faster on
                           rejected documents, a module 1.3 to 1.7x the size
+  --order                 Hand errors out in the runtime's order (schema declaration
+                          order) rather than the order they were found in; adds a sort,
+                          and for a schema with $ref its key skeleton (modules that share
+                          the error runtime are in that order already)
   --errors <mode>         Where error detail comes from: auto | inline | shared. auto
                           (default) has modules share one error runtime file when that
                           makes the output smaller; production builds only (--no-source)
@@ -103,6 +110,7 @@ function parseArgs(argv) {
     if (a === '--no-types') { out.opts.types = false; continue; }
     if (a === '--abort-early') { out.opts.abortEarly = true; continue; }
     if (a === '--one-pass') { out.opts.onePass = true; continue; }
+    if (a === '--order') { out.opts.order = true; continue; }
     if (a === '--errors') { out.opts.errors = argv[++i]; continue; }
     if (a === '--mode') { out.opts.mode = argv[++i]; continue; }
     if (a === '--base-uri') { out.opts.baseUri = argv[++i]; continue; }
@@ -250,7 +258,7 @@ function cmdCompile(args) {
   }
   const schemaFile = path.relative(process.cwd(), input) || input;
   const compileWarnings = [];
-  const src = aot.toStandaloneModule(v, { format, abortEarly, source, sourceMap, schemaFile, onePass: args.opts.onePass === true ? true : undefined, onWarning: (w) => compileWarnings.push(w) });
+  const src = aot.toStandaloneModule(v, { format, abortEarly, source, sourceMap, schemaFile, onePass: args.opts.onePass === true ? true : undefined, order: args.opts.order === true ? true : undefined, onWarning: (w) => compileWarnings.push(w) });
   if (compileWarnings.length > 0) {
     if (args.opts.strict) {
       for (const w of compileWarnings) reportCompileError(input, w);
@@ -277,7 +285,7 @@ function cmdCompile(args) {
     const typeName = args.opts.name || path.basename(input, path.extname(input))
       .replace(/[^A-Za-z0-9_]/g, '_')
       .replace(/^([a-z])/, (m) => m.toUpperCase()) || 'Data';
-    const dts = toTypeScript(schema, { name: typeName });
+    const dts = toTypeScript(schema, { name: typeName, applyDefaults: /\nfunction applyDefaults\(/.test(src) });
     const ext = path.extname(output);
     const dtsExt = ext === '.mjs' ? '.d.mts'
       : ext === '.cjs' ? '.d.cts'
@@ -308,6 +316,7 @@ function cmdBuild(args) {
     suffix: args.opts.suffix,
     abortEarly: !!args.opts.abortEarly,
     onePass: args.opts.onePass === true ? true : undefined,
+    order: args.opts.order === true ? true : undefined,
     errors: args.opts.errors,
     mode: args.opts.mode,
     baseUri: args.opts.baseUri,

package/build.d.ts

@@ -116,6 +116,12 @@ export interface ToStandaloneModuleOptions {
    * older collector either way.
    */
   onePass?: boolean;
+  /**
+   * Hand errors out in the runtime's order, schema declaration order, rather
+   * than the order the collector found them in (`ata compile --order`). Adds a
+   * sort, and for a schema with `$ref` its key skeleton; off by default.
+   */
+  order?: boolean;
   source?: boolean;
   sourceMap?: unknown;
   schemaFile?: string;
@@ -190,7 +196,7 @@ export function compiledSchemaFor(schema: unknown): object;
  * {@link compiledEligible} declines, one the emitter cannot compile, and one
  * whose detailed errors the generator cannot produce.
  */
-export function compiledModuleFor(schema: unknown, opts?: { format?: 'esm' | 'cjs'; errorRuntime?: string }): string | null;
+export function compiledModuleFor(schema: unknown, opts?: { format?: 'esm' | 'cjs'; errorRuntime?: string; order?: boolean }): string | null;
 
 /**
  * The Validator options `fromCompiled()` reproduces, so a plugin can tell

package/codegen.d.ts

@@ -0,0 +1,3 @@
+// ata-validator/codegen registers the code generator as a side effect and
+// exports nothing. See codegen.js.
+export {};

package/codegen.js

@@ -0,0 +1,10 @@
+'use strict';
+
+// ata-validator/codegen: registers the code generator now. The browser build
+// loads it on demand, once a validator gets hot; importing this once at
+// startup has every schema compiled to generated code from its first call,
+// and makes parse() and the ahead-of-time bundle methods available in the
+// browser. On Node, ata-validator already includes it and this does nothing.
+const core = require('./lib/validator-core.js');
+if (!core._codegenRegistered()) core._registerCodegen(require('./lib/codegen-engine.js'));
+module.exports = {};

package/codegen.mjs

@@ -0,0 +1,2 @@
+// ata-validator/codegen, ES module form: see codegen.js.
+import './codegen.js';

package/index.browser.mjs

@@ -1,13 +1,19 @@
-// Browser ESM entry, for bundlers: the validator core with the code generator
-// registered, as index.js, but with each tool imported on its own (see
-// lib/tools.mjs) so that the tools an application does not import stay out
-// of its bundle. The native addon is stubbed by the package.json "browser"
-// field.
+// Browser ESM entry, for bundlers: the validator core, with each tool imported
+// on its own (see lib/tools.mjs) so that the tools an application does not
+// import stay out of its bundle. The native addon is stubbed by the
+// package.json "browser" field.
+//
+// The code generator is not in the page's bundle. Every schema starts on the
+// interpreted engine, which gives the same answers; a validator that gets hot
+// (lib/validator-core.js, TIER_CALLS) loads the generator through the dynamic
+// import below, which bundlers split into a chunk of its own, and rebuilds
+// itself on generated code. A page that wants generated code from the first
+// call imports 'ata-validator/codegen' once.
 import core from './lib/validator-core.js';
-import engine from './lib/codegen-engine.js';
+import tiering from './lib/tiering.js';
 import { toTypeScript, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON } from './lib/tools.mjs';
 
-core._registerCodegen(engine);
+core._registerTiering(tiering.createTiering(() => import('./lib/codegen-engine.js')));
 
 export const { Validator, compile, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, parseJSON, defineSchema } = core;
 export { toTypeScript, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON };

package/lib/aot-build.js

@@ -288,6 +288,7 @@ async function build(opts) {
       format,
       abortEarly: !!opts.abortEarly,
       onePass: opts.onePass === true ? true : undefined,
+      order: opts.order === true ? true : undefined,
       source,
       sourceMap,
       schemaFile,
@@ -465,7 +466,7 @@ async function build(opts) {
         const typeName = stem
           .replace(/[^A-Za-z0-9_]/g, '_')
           .replace(/^([a-z])/, (m) => m.toUpperCase()) || 'Data';
-        const dts = toTypeScript(e.schema, { name: typeName });
+        const dts = toTypeScript(e.schema, { name: typeName, applyDefaults: /\nfunction applyDefaults\(/.test(src) });
         const ext = path.extname(output);
         const dtsExt = ext === '.mjs' ? '.d.mts'
           : ext === '.cjs' ? '.d.cts'
@@ -646,6 +647,10 @@ function compiledModuleFor(schema, opts) {
   try {
     src = aot.toStandaloneModule(validatorFor(schema), {
       format: (opts && opts.format) || 'esm',
+      // Errors in the runtime's order, for a reader that does not sort them
+      // itself (a form resolver); fromCompiled sorts, so a plugin putting
+      // that wrapper around the module leaves it off.
+      order: !!(opts && opts.order === true),
       onWarning: (msg, info) => { if (info && info.kind === 'error-detail') degraded = true; },
     });
   } catch {

package/lib/aot-impl.js

@@ -346,6 +346,20 @@ function codeTableSource(keywords, formats) {
 
 const ABORT_SHAPE = Object.freeze({ valid: false, errors: Object.freeze([Object.freeze({ code: 'ATA9000', message: 'validation failed', keyword: '__abort_early__', path: '' })]) });
 
+// The runtime's defaults pass (preprocessSource in lib/codegen-engine.js),
+// over the schema the runtime builds it from, as a function the module
+// exports as applyDefaults. Not called by validate(): the runtime fills
+// defaults before checking because useDefaults is on unless turned off, and
+// a module cannot see that option, so the caller who wants the runtime's
+// answer calls applyDefaults(data) first. Empty where the schema has no
+// default, or where the pass declines it (a schema object containing itself).
+function defaultsDecl(validator) {
+  const { resolveSchemaForPreprocess } = require('./validator-core')._internals;
+  let src = null;
+  try { src = require('./codegen-engine').preprocessSource(resolveSchemaForPreprocess(validator._schemaObj, validator._schemaMap), { useDefaults: true }); } catch {}
+  return src === null ? '' : `function applyDefaults(d) {\n${src}\n}\n`;
+}
+
 function toStandaloneModule(validator, opts) {
   assertEmittable(validator, 'toStandaloneModule');
   validator._ensureCompiled();
@@ -374,6 +388,7 @@ function toStandaloneModule(validator, opts) {
   // notices a rejected document's cost. A build that validates large
   // documents against large schemas asks for it.
   let onePass = null;
+  let ordered = false;
   const wantOnePass = opts && opts.onePass === true ? 'always' : (opts && (opts.onePass === false || opts.noOnePass)) ? 'never' : 'auto';
   // Asked for explicitly, the one-pass function wins over schema-source
   // frames, which `ata compile` writes by default outside production; the
@@ -394,14 +409,20 @@ function toStandaloneModule(validator, opts) {
       `const _ER = function(e) { _ataStamp(e); this.valid = false; this.errors = e; };\n` +
       `${codeTableSource(onePass.keywords, onePass.formats)}const _vC = (function() {\n${onePass.core}\n})();\n`;
   } else if (!abortEarly) {
-    // A module returns the collector's errors as they are and never sorts
-    // them, so the ordinal the runtime sorts by (`_o`) has no reader there;
-    // it leaked into every error object a module reported.
+    // With `order: true` the module hands its errors out in the runtime's
+    // order (lib/aot-order.js); without it, in the collector's, as it always
+    // did, since the sort costs every module bytes (12.6% over SchemaStore's,
+    // gzipped, most of it the key skeleton of schemas with references) and a
+    // reader that sorts (fromCompiled) does not need it. Where the module
+    // sorts by each error site's ordinal, the collector writes it (`_o`).
+    const schemaForErrors = typeof validator._schemaObj === 'object' ? validator._schemaObj : {};
+    ordered = !!(opts && opts.order === true);
+    const noOrdinal = !ordered || !require(AOT_ORDER_MODULE).wantsOrdinals(schemaForErrors);
     jsErrFn = compileToJSCodegenWithErrors(
-      typeof validator._schemaObj === 'object' ? validator._schemaObj : {},
+      schemaForErrors,
       null,
       validator._userFormats,
-      (source && sourceMap && schemaFile) ? { sourceMap, schemaFile, frames: sourceFrames, noOrdinal: true } : { noOrdinal: true },
+      (source && sourceMap && schemaFile) ? { sourceMap, schemaFile, frames: sourceFrames, noOrdinal } : { noOrdinal },
     );
     const errSrc = jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : '';
     if (errSrc && jsErrFn._errFactory) {
@@ -537,12 +558,22 @@ function toStandaloneModule(validator, opts) {
     // module that only accepts costs no more to load than its verdict.
     compactCore = `let _ataErrs = null;\nfunction _ataErrors(d) { if (_ataErrs === null) _ataErrs = _ataCreateErrors(JSON.parse(${text})${rtOpts ? ', { ' + rtOpts + ' }' : ''}); return _ataErrs(d); }\n`;
   }
+  const orderDecl = errCore && ordered && errorRuntime === null && onePass === null
+    ? require(AOT_ORDER_MODULE).orderDecl(validator._schemaObj)
+    : '';
+  // Asked for and not given: stub errors, the one-pass function, or no error
+  // code generated. The caller is told rather than handed the collector's
+  // order as if it were the runtime's. Errors from the shared runtime come in
+  // the runtime's order already (errorsOf in lib/error-runtime-entry.js).
+  if (opts && opts.order === true && orderDecl === '' && errorRuntime === null && typeof opts.onWarning === 'function') {
+    opts.onWarning('errors are not in the runtime order: order applies to modules with generated error code, not to stub errors or the one-pass function', { kind: 'order' });
+  }
   const validBody = errorRuntime !== null
     ? 'if (_fn(data)) return VALID; const e = _ataErrors(data); return e === null ? ABORT : { valid: false, errors: e }'
     : onePass !== null
     ? 'return _vC(data)'
     : errCore
-      ? 'return _fn(data) ? VALID : { valid: false, errors: errFn(data, true).errors }'
+      ? (orderDecl !== '' ? 'return _fn(data) ? VALID : { valid: false, errors: _ataOrder(errFn(data, true).errors) }' : 'return _fn(data) ? VALID : { valid: false, errors: errFn(data, true).errors }')
       : 'return _fn(data) ? VALID : ABORT';
 
   // parse(): validate, then hand back a copy holding only the properties the
@@ -625,6 +656,8 @@ function validateJSON(text) {
   const hashDecl = `const schemaHash = ${JSON.stringify(hashSrc)};\nconst ataVersion = ${JSON.stringify(ATA_VERSION)};\n`;
 
   let names = fmt.exportsSetFormats ? baseNames + ', setFormats' : baseNames;
+  const fillDecl = defaultsDecl(validator);
+  if (fillDecl) names += ', applyDefaults';
   names += ', schemaHash, ataVersion';
   if (positionsCore) names += ', validateJSON';
   const parseAlias = cloneExpr ? ', _ataParse as parse' : '';
@@ -657,9 +690,9 @@ const ABORT = Object.freeze({
 ${closureDecls}${sharedBlock}${preambleDecls}${formatDecls}const _fn = function(d) {
   ${src}
 };
-${errCore}${compactCore}function isValid(data) { return _fn(data); }
+${errCore}${orderDecl}${compactCore}function isValid(data) { return _fn(data); }
 function validate(data) { ${validBody}; }
-${parseCore}${positionsCore}${hashDecl}${exports}`;
+${parseCore}${positionsCore}${fillDecl}${hashDecl}${exports}`;
 }
 
 // Why a validator cannot be written as a compact module, or null when it can.
@@ -673,6 +706,8 @@ ${parseCore}${positionsCore}${hashDecl}${exports}`;
 // along: 1.49.0 bundled for such runtimes, and the generator must not break
 // that.
 const ERROR_RUNTIME_MODULE = './error-runtime';
+// Reads the library's files too, at build time (see lib/aot-order.js).
+const AOT_ORDER_MODULE = './aot-order';
 function loadErrorRuntime() { return require(ERROR_RUNTIME_MODULE); }
 
 // The schema hash a module stamps, once per validator: a plugin writes both
@@ -806,9 +841,11 @@ function toSchemaModule(validator, opts) {
     ? `import { createValidator as _ataCreateValidator } from ${spec};\n`
     : `const { createValidator: _ataCreateValidator } = require(${spec});\n`)
     + (regSpec === null ? '' : format === 'esm' ? `import _ataRegistry from ${regSpec};\n` : `const _ataRegistry = require(${regSpec});\n`);
+  const fillDecl = defaultsDecl(validator);
+  const expNames = 'validate, isValid' + (fillDecl ? ', applyDefaults' : '') + ', schemaHash, ataVersion';
   const exp = format === 'esm'
-    ? 'export { validate, isValid, schemaHash, ataVersion };\nexport default { validate, isValid, schemaHash, ataVersion };\n'
-    : 'module.exports = { validate, isValid, schemaHash, ataVersion };\nmodule.exports.default = module.exports;\n';
+    ? `export { ${expNames} };\nexport default { ${expNames} };\n`
+    : `module.exports = { ${expNames} };\nmodule.exports.default = module.exports;\n`;
   return `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit.
 // Schema module: the schema; the verdict and the errors come from the runtime it imports.
 // Re-run the build after upgrading ata: the version above is what wrote this.
@@ -819,7 +856,7 @@ let _ataV = null;
 function _ataGet() { return _ataV !== null ? _ataV : (_ataV = _ataCreateValidator(${ownId !== null ? 'null' : 'JSON.parse(' + text + ')'}${rtOpts ? ', { ' + rtOpts + ' }' : ''})); }
 function isValid(data) { return _ataGet().isValid(data); }
 function validate(data) { const v = _ataGet(); if (v.isValid(data)) return VALID; const e = v.errors(data); return e === null ? ABORT : { valid: false, errors: e }; }
-const schemaHash = ${JSON.stringify(hashSrc)};
+${fillDecl}const schemaHash = ${JSON.stringify(hashSrc)};
 const ataVersion = ${JSON.stringify(ATA_VERSION)};
 ${exp}`;
 }

package/lib/aot-order.js

@@ -0,0 +1,115 @@
+'use strict';
+
+// How a module written ahead of time hands out its errors in the order the
+// runtime does: schema declaration order (sortErrorsBySchemaOrder in
+// lib/rejections.js). A module used to return them in the order its collector
+// found them, which put `additionalProperties` before `properties` and
+// `format` before `pattern`, and behind a reference a definition's `required`
+// before its `properties`; the first error of a field could differ from the
+// runtime's.
+//
+// The runtime orders by the ordinal of each error's schema path and breaks
+// ties by the path's rank, and comparing ranks alone gives the same order
+// (lib/schema-order.js). Two ways to know them in a module:
+//
+// - Without a reference, the collector writes each error site's ordinal into
+//   the error (`_o`, noteOrdinal in lib/js-compiler-errors.js) and no two
+//   paths share one, so a stable sort by it is the runtime's order.
+// - With one, an error behind a shared definition has its path built when the
+//   definition runs and carries no ordinal, and paths through a `$ref` share
+//   the ordinal of the `$ref`. The module ranks each path itself with
+//   lib/schema-order.js's own functions, embedded as their text so module and
+//   runtime rank with one source, over the schema's skeleton: its schema
+//   objects with every key, subschemas kept, every other value 0, which ranks
+//   every path an error can name exactly as the schema does.
+//
+// Node only, at build time: it reads the library's own files.
+const fs = require('fs');
+const path = require('path');
+
+const _files = new Map();
+function take(file, names) {
+  let src = _files.get(file);
+  if (src === undefined) { src = fs.readFileSync(path.join(__dirname, file), 'utf8'); _files.set(file, src); }
+  return names.map((n) => {
+    const m = new RegExp('^function ' + n + ' ?\\([^]*?^}$', 'm').exec(src);
+    if (m === null) throw new Error('aot-order: lib/' + file + ' has no top-level function ' + n);
+    return m[0].replace(/^\s*\/\/.*\n/gm, '');
+  }).join('\n');
+}
+
+// Keywords whose value is a schema, an array of schemas, or an object of them:
+// the only places an error's schema path goes below a schema object.
+const ONE = new Set(['additionalProperties', 'additionalItems', 'items', 'contains', 'propertyNames', 'if', 'then', 'else', 'not', 'unevaluatedItems', 'unevaluatedProperties']);
+const LIST = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems', 'items']);
+const MAP = new Set(['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas', 'dependencies']);
+
+function skeleton(node) {
+  if (node === null || typeof node !== 'object' || Array.isArray(node)) return 0;
+  const out = {};
+  for (const k of Object.keys(node)) {
+    const v = node[k];
+    let s = 0;
+    if (k === '$ref' && typeof v === 'string') s = v;
+    else if (Array.isArray(v) && LIST.has(k)) s = v.map(skeleton);
+    else if (MAP.has(k) && v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      s = {};
+      for (const name of Object.keys(v)) Object.defineProperty(s, name, { value: Array.isArray(v[name]) ? 0 : skeleton(v[name]), enumerable: true, writable: true, configurable: true });
+    } else if (ONE.has(k) && v !== null && typeof v === 'object') s = skeleton(v);
+    Object.defineProperty(out, k, { value: s, enumerable: true, writable: true, configurable: true });
+  }
+  return out;
+}
+
+function hasReference(schemaObj) {
+  const text = JSON.stringify(schemaObj);
+  return text.includes('"$ref"') || text.includes('"$dynamicRef"') || text.includes('"$recursiveRef"');
+}
+
+// Whether the collector should write ordinals into the errors: only where the
+// module sorts by them.
+function wantsOrdinals(schemaObj) { return !hasReference(schemaObj); }
+
+// The sort, by a key per error, stable as the runtime's insertion sort is, and
+// the copies the caller gets, without the ordinal; a collapsed error's branch
+// errors are ordered and copied the same way.
+const ORDER = (key, cmp) => `function _ataOrder(list) {
+  const n = list.length, out = new Array(n), keys = new Array(n);
+  let prev = ${key === '_o' ? '0' : 'null'};
+  for (let i = 0; i < n; i++) {
+    const src = list[i];
+    const { _o, ...e } = src;
+    if (Array.isArray(e.branchErrors)) e.branchErrors = _ataOrder(e.branchErrors);
+    let k = ${key === '_o' ? "typeof src._o === 'number' ? src._o : prev" : '_ataRank(src.schemaPath)'};
+    prev = k;
+    let j = i - 1;
+    while (j >= 0 && ${cmp}) { keys[j + 1] = keys[j]; out[j + 1] = out[j]; j--; }
+    keys[j + 1] = k;
+    out[j + 1] = e;
+  }
+  return out;
+}
+`;
+
+// Source declaring `_ataOrder(errors)`: the errors sorted as the runtime sorts
+// them, without their ordinals.
+function orderDecl(schemaObj) {
+  if (!hasReference(schemaObj)) return ORDER('_o', 'keys[j] > k');
+  const sk = JSON.stringify(skeleton(schemaObj));
+  return `const _ataSkeleton = JSON.parse(${JSON.stringify(sk).replace(/</g, '\\u003c')});
+const _keyIndexCache = new WeakMap();
+const _rankCache = new WeakMap();
+const _documents = new WeakMap();
+const CONFLICT = null;
+${take('schema-order.js', ['keyIndex', 'unescapePointerSegment', 'rankFor', 'computeRank', 'localTarget'])}
+function _ataRank(p) { return rankFor(_ataSkeleton, p); }
+function _ataAfter(a, b) {
+  if (a === null || b === null) return false;
+  const m = Math.min(a.length, b.length);
+  for (let i = 0; i < m; i++) if (a[i] !== b[i]) return a[i] > b[i];
+  return a.length > b.length;
+}
+${ORDER('rank', '_ataAfter(keys[j], k)')}`;
+}
+
+module.exports = { orderDecl, wantsOrdinals };

package/lib/codegen-engine.js

@@ -857,8 +857,10 @@ function emitDefaults(node, ov, lines, st) {
   st.seen.delete(node);
 }
 
-// Generate a fast preprocess function via codegen instead of closure arrays
-function buildPreprocessCodegen(schema, options) {
+// The source of the preprocess pass, or null when there is nothing to do or
+// the closure passes must take the schema. A module written ahead of time
+// embeds it as applyDefaults (lib/aot-impl.js), so it runs the runtime's code.
+function preprocessSource(schema, options) {
   if (typeof schema !== 'object' || schema === null || !schema.properties) return null;
   const lines = [];
 
@@ -889,13 +891,19 @@ function buildPreprocessCodegen(schema, options) {
   // Data may legitimately be null or a non-object (e.g. a `['object','null']`
   // schema), so the per-property mutations must not run on it.
   lines.unshift(`if(d===null||typeof d!=='object')return`);
+  return lines.join('\n');
+}
+
+// Generate a fast preprocess function via codegen instead of closure arrays
+function buildPreprocessCodegen(schema, options) {
+  const src = preprocessSource(schema, options);
+  if (src === null) return null;
   // The pass depends on property names, types, defaults and which objects
   // are closed, not on the constraints the verdict checks, so routes that
   // take the same shape with different limits (a page/limit querystring, an
   // id param) emit the same source. Compiling it is most of what building the
   // pass costs, so the function is kept by its source and compiled once. It
   // holds no state: it rewrites the object it is given and nothing else.
-  const src = lines.join('\n');
   let fn = _preprocessBySource.get(src);
   if (fn === undefined) {
     try {
@@ -1020,6 +1028,7 @@ module.exports = {
   compileVerdict: installCodegenPaths.compileVerdict,
   installScanner: installCodegenPaths.installScanner,
   buildPreprocess: buildPreprocessCodegen,
+  preprocessSource,
   buildParse,
   aot: () => require('./aot.js'),
 };

package/lib/interpreter-core.js

@@ -13,6 +13,34 @@
 let _safeRe = null;
 const compileSafe = (src) => (_safeRe || (_safeRe = require('./safe-regex'))).compileSafe(src);
 
+// A pattern with no group or alternation, few bounded choices in all, and at
+// most one unbounded repeat, on one character or class and only when the
+// pattern starts with `^`, runs in linear time on a backtracking RegExp, so it
+// takes the platform's: built in about a microsecond where the linear engine's
+// automaton took 40 to 100, and faster to test. Every pattern accepted here
+// also gets a RegExp from the code generator (lib/regex-linear.js), so both
+// engines answer with the same matcher; tests/test_regex_plain_linear.js holds
+// that and the answers.
+const PLAIN_ATOM = /(?:\\[dDwWsS\\/.^$|?*+()[\]{}-]|\[\^?(?:[^\\\][^\ud800-\udfff]|\\[dws\\/.^$[\]-])(?:[^\\\][\ud800-\udfff]|\\[dws\\/.^$[\]-])*\]|[^\\[\](){}|*+?^$\ud800-\udfff])(\?|[*+]|\{(\d{1,3})(?:,(\d{1,3}))?\})?/y;
+function plainLinear(src) {
+  const n = src.length, anchored = src[0] === '^';
+  if (n > 256) return false;
+  let i = anchored ? 1 : 0, choices = 1, loops = 0;
+  while (i < n) {
+    if (src[i] === '$' && i === n - 1) return true;
+    PLAIN_ATOM.lastIndex = i;
+    const m = PLAIN_ATOM.exec(src);
+    if (m === null) return false;
+    i = PLAIN_ATOM.lastIndex;
+    const q = m[1];
+    if (q === '?') choices *= 2;
+    else if (q === '*' || q === '+') { if (!anchored || ++loops > 1) return false; }
+    else if (q !== undefined) { const lo = +m[2], hi = m[3] === undefined ? lo : +m[3]; if (hi < lo) return false; choices *= hi - lo + 1; }
+    if (choices > 64) return false;
+  }
+  return true;
+}
+
 const SCHEMA_KEYWORDS = {
   single: ['additionalProperties', 'contains', 'propertyNames', 'if', 'then', 'else', 'not', 'items', 'unevaluatedItems', 'unevaluatedProperties'],
   maps: ['$defs', 'definitions', 'properties', 'patternProperties', 'dependentSchemas'],
@@ -912,6 +940,8 @@ class Interpreter {
         // Unicode property escapes need a real RegExp in unicode mode; the
         // linear engine does not understand them.
         try { re = new RegExp(src, 'u'); } catch { re = new RegExp(src); }
+      } else if (plainLinear(src)) {
+        re = new RegExp(src);
       } else {
         try {
           re = compileSafe(src);
@@ -1534,6 +1564,7 @@ function createInterpreter(schema, options) {
 }
 
 module.exports = { createInterpreter };
+Object.defineProperty(module.exports, '_plainLinear', { value: plainLinear, enumerable: false });
 Object.defineProperty(module.exports, '_setPlanCompiler', { value: setPlanCompiler, enumerable: false });
 Object.defineProperty(module.exports, '_setCompat', { value: setCompat, enumerable: false });
 // The resolver, for the code generator: it resolves references at compile

package/lib/tiering.js

@@ -0,0 +1,236 @@
+'use strict';
+
+// The browser build's code generator, loaded on demand. index.browser.mjs
+// registers this with the core and hands it a loader (a dynamic import, which
+// bundlers split into a chunk of its own), so a page starts with the
+// interpreted engine alone. A validator counts its calls; one that reaches
+// TIER_CALLS asks for the generator and, once it has arrived, rebuilds itself
+// on generated code. Answers are the same on either engine; what changes is
+// the speed and what the page downloads. Validators that stay cold, a form
+// checked as the user types, never cause the download.
+//
+// Kept out of lib/validator-core.js so the entries that never load the
+// generator on demand (lite, edge, Node) carry none of this.
+const core = require('./validator-core.js');
+const { compileFunction } = require('./compile-fn.js');
+
+// Hot means TIER_CALLS calls within WINDOW_MS. A count alone is not enough:
+// a form checked as the user types reaches a thousand calls over a long
+// session, and generated code saves it nothing it would notice (tens of
+// nanoseconds a check) while the page pays for the download and the compile.
+// Measured on a form schema: interpreted 58 ns, generated 18 ns, loading the
+// generator about 3.5 ms and compiling the schema 2.4 ms.
+const TIER_CALLS = 1000;
+const WINDOW_MS = 1000;
+const now = typeof performance !== 'undefined' && typeof performance.now === 'function' ? () => performance.now() : Date.now;
+// Recompiling takes a few milliseconds a validator. Each runs as its own
+// task, when the page is idle where the browser says so, so that several
+// validators turning hot together do not hold the main thread for all of
+// them at once, and none compiles inside the call that crossed the line.
+const later = typeof requestIdleCallback === 'function' ? (f) => requestIdleCallback(f, { timeout: 1000 }) : (f) => setTimeout(f, 0);
+
+function createTiering (load) {
+  let loading = null;
+  // Validators that turned hot, waiting for the generator or for their turn.
+  const waiting = new Set();
+  let draining = null;
+
+  function drain () {
+    if (draining !== null) return draining;
+    draining = new Promise((resolve) => {
+      const step = () => {
+        const next = waiting.values().next();
+        if (next.done) { draining = null; resolve(); return; }
+        waiting.delete(next.value);
+        tierUp(next.value);
+        later(step);
+      };
+      later(step);
+    });
+    return draining;
+  }
+
+  function loadCodegen () {
+    if (loading !== null) return loading;
+    let allowed;
+    try { allowed = compileFunction('return 1')() === 1; } catch { allowed = false; }
+    loading = !allowed
+      // Code generation is blocked here (a strict Content-Security-Policy):
+      // the generator would decline every schema, so it is not downloaded.
+      ? Promise.resolve(false)
+      : Promise.resolve().then(load).then((mod) => {
+        if (!core._codegenRegistered()) core._registerCodegen(mod && mod.default ? mod.default : mod);
+        return true;
+      }, () => false);
+    loading.then((ok) => { if (ok) drain(); else waiting.clear(); });
+    return loading;
+  }
+
+  // The fields the constructor sets, the same for every validator; anything
+  // else on an instance was put there by compiling it, or by a method's first
+  // call, and is dropped when it is compiled again.
+  let ctorKeys = null;
+  const SCHEMA_KEYS = new Set(['_schemaObj', '_usesKeywords', '_schemaIsCallers']);
+
+  // Rebuilt on generated code, in place: what compiling put on the validator
+  // is dropped and it compiles again, now with the generator. In place rather
+  // than by copying from a second validator because the compiled methods
+  // close over the instance they were built for and swap themselves on it
+  // after their first calls (the one-pass and result-factory stages); copied
+  // across, those swaps would land on the copy. A caller holding a method
+  // taken earlier (`const check = v.isValidObject`) keeps the interpreted
+  // one, which answers the same.
+  function tierUp (v) {
+    if (!core._codegenRegistered() || v._tieredUp) return;
+    if (ctorKeys === null) ctorKeys = new Set(Reflect.ownKeys(new core.Validator(true, {})));
+    // Reset without `delete`: deleting properties turns a V8 object into a
+    // slow dictionary, and every method read on the validator got slower,
+    // 20 ns a check against 17 for one compiled directly (in any order; V8
+    // did not step back even for the newest property). Values are swapped
+    // instead, which keeps the object's shape: a method the prototype makes
+    // on first use gets a fresh one, as a new validator would; any other
+    // field the compile put there reads as undefined, as if absent. What the
+    // schema itself resolved to (_schemaObj and the flags read with it) does
+    // not change and stays.
+    const proto = Object.getPrototypeOf(v);
+    for (const k of Reflect.ownKeys(v)) {
+      if (ctorKeys.has(k) || SCHEMA_KEYS.has(k)) continue;
+      let d = null;
+      for (let p = proto; p !== null && d === null; p = Object.getPrototypeOf(p)) d = Object.getOwnPropertyDescriptor(p, k) || null;
+      if (d !== null && typeof d.get === 'function') d.get.call(v);
+      else v[k] = d !== null ? d.value : undefined;
+    }
+    v._initialized = false;
+    v._engine = undefined;
+    v._preprocess = null;
+    v._applyDefaults = null;
+    Object.defineProperty(v, '_tieredUp', { value: true, writable: true, configurable: true, enumerable: false });
+    v._ensureCompiled();
+  }
+
+  // A call counter for one validator: the TIER_CALLS-th call asks for the
+  // generator and has the validator rebuilt once it is in.
+  function counter (v) {
+    if (warm === 1) warm = 2;
+    let calls = 0, start = 0;
+    return () => {
+      if (++calls < TIER_CALLS) { if (calls === 1) start = now(); return; }
+      if (calls !== TIER_CALLS) return;
+      // Too slow to be hot: start a new window.
+      if (now() - start > WINDOW_MS) { calls = 0; return; }
+      waiting.add(v);
+      if (core._codegenRegistered()) drain();
+      else loadCodegen();
+    };
+  }
+
+  // A page's first check pays for V8 compiling the engine and the error
+  // builders (3.1 ms of an eight-field form's first submit, 0.4 ms once any
+  // other schema had been checked) and for building its own schema's engine.
+  // Both move to when the page is idle, or 200 ms later where there is no
+  // requestIdleCallback (Safari, workers): one check of a small schema, once
+  // per page and dropped when a validator compiles first, then the engine for
+  // each validator built since, at most eight, kept aside. A validator adopts
+  // it at its first check only if every input is still the same, its schema
+  // text included, so addSchema() or a change to the schema in between is
+  // honored as before.
+  // warm: 0 none, 1 scheduled, 2 done or dropped.
+  let warm = 0, scheduled = false, warming = false, adopted = 0;
+  const pending = [];
+  const shadows = new WeakMap();
+  const idle = (f) => {
+    if (typeof requestIdleCallback === 'function') return requestIdleCallback(f, { timeout: 2000 });
+    const t = setTimeout(f, 200);
+    if (t && typeof t.unref === 'function') t.unref();
+  };
+  function built (v) {
+    if (warming) return;
+    if (warm === 0) warm = 1;
+    if (pending.length < 8 && typeof WeakRef === 'function') pending.push(new WeakRef(v));
+    if (!scheduled) { scheduled = true; idle(run); }
+  }
+  function run (deadline) {
+    scheduled = false;
+    if (warm === 1) {
+      warm = 2;
+      warming = true;
+      try { warmUp(); } catch { /* a warm-up never reaches the page */ }
+      warming = false;
+    }
+    while (pending.length > 0) {
+      if (deadline !== undefined && deadline.timeRemaining() < 1) { scheduled = true; idle(run); return; }
+      const v = pending.shift().deref();
+      if (v === undefined || core._codegenRegistered()) continue;
+      let s = null;
+      try { s = prebuild(v); } catch { /* built as usual at the first check */ }
+      if (s !== null) shadows.set(v, s);
+    }
+  }
+
+  // One check of a small schema, rejected and accepted, compiles the engine's
+  // code for the page: the plan builder, the walk, the regex and format
+  // checks, the error builders.
+  function warmUp () {
+    const v = new core.Validator({
+      type: 'object',
+      properties: {
+        a: { type: 'string', minLength: 2, maxLength: 9, pattern: '^[a-z]+$', format: 'email' },
+        b: { type: 'integer', minimum: 1, maximum: 9 },
+        c: { type: 'array', items: { type: 'string' }, maxItems: 3 },
+        d: { const: true },
+        e: { type: 'object', properties: { f: { type: 'string' } }, required: ['f'] },
+      },
+      required: ['a', 'b'],
+    });
+    void v.validate({ a: '1', b: 0, c: [1], d: false, e: {} }).errors.length;
+    v.validate({ a: 'ab@c.de', b: 2, c: ['x'], d: true, e: { f: 'x' } });
+  }
+
+  // The engine a validator will build at its first check, built now from the
+  // same inputs and kept aside; null where something besides the schema object
+  // decides the build: custom keywords (their compile functions are the
+  // caller's code), registered schemas, a schema that needs rewriting.
+  function prebuild (v) {
+    if (v._initialized || v._keywords !== null || v._schemaMap.size !== 0) return null;
+    const raw = v._rawSchema;
+    const { _interpArgs, _normalizeCallerSchemaUncached } = core._internals;
+    if (raw === null || typeof raw !== 'object' || _normalizeCallerSchemaUncached(raw) !== raw) return null;
+    const args = _interpArgs(v, raw);
+    return { schema: raw, text: JSON.stringify(raw), args, interp: require('./interpreter').createInterpreter(raw, args) };
+  }
+
+  function adopt (v, schemaObj, args) {
+    const s = shadows.get(v);
+    if (s === undefined) return null;
+    shadows.delete(v);
+    if (s.schema !== schemaObj || s.text !== v._schemaStr) return null;
+    for (const k of Object.keys(args)) if (args[k] !== s.args[k]) return null;
+    adopted++;
+    return s.interp;
+  }
+
+  // Count the interpreted engine's calls for this validator.
+  function watch (v, interp) {
+    if (warm === 1) warm = 2;
+    const v0 = interp.validate, i0 = interp.isValid;
+    const tick = counter(v);
+    interp.validate = (d) => { tick(); return v0.call(interp, d); };
+    interp.isValid = (d) => { tick(); return i0.call(interp, d); };
+  }
+
+  // The emitters stay out of the page, as they did when the generator was in
+  // it (the package.json browser field maps lib/aot.js to this stub); loading
+  // a built module works.
+  const aotStub = () => require('./aot.browser.js');
+
+  // Resolves once the generator has loaded (or failed to) and every validator
+  // waiting for it has been rebuilt. For tests, and a page that wants to wait.
+  async function settled () {
+    if (loading !== null) await loading;
+    while (draining !== null) await draining;
+  }
+
+  return { watch, counter, built, aotStub, loadCodegen, settled, TIER_CALLS, WINDOW_MS, get loading () { return loading; }, get warm () { return warm; }, get adopted () { return adopted; }, adopt };
+}
+
+module.exports = { createTiering, TIER_CALLS };

package/lib/ts-gen.js

@@ -197,6 +197,8 @@ function renderJsDoc(schema, indent) {
 function toTypeScript(schema, opts) {
   const options = opts || {};
   const rootName = toTypeName(options.name || 'Data');
+  // Whether the module beside these types exports applyDefaults (lib/aot-impl.js).
+  const fill = options.applyDefaults === true;
   const defs = schema && (schema.$defs || schema.definitions);
 
   const defLines = [];
@@ -240,9 +242,11 @@ export type Result = ValidResult | InvalidResult;
 
 export declare function isValid(data: unknown): data is ${rootName};
 export declare function validate(data: unknown): Result;
-export declare const schemaHash: string;
+${fill ? `/** Fills in the schema's \`default\` values where a key is missing, as the runtime Validator does before checking. Call it before validate() for the runtime's answer. */
+export declare function applyDefaults(data: unknown): void;
+` : ''}export declare const schemaHash: string;
 export declare const ataVersion: string;
-declare const _default: { validate: typeof validate; isValid: typeof isValid; schemaHash: typeof schemaHash; ataVersion: typeof ataVersion };
+declare const _default: { validate: typeof validate; isValid: typeof isValid; ${fill ? 'applyDefaults: typeof applyDefaults; ' : ''}schemaHash: typeof schemaHash; ataVersion: typeof ataVersion };
 export default _default;
 `;
 }

package/lib/validator-core.js

@@ -30,6 +30,10 @@ function _registerCodegen(engine) {
 // `ata build` or Validator.bundle() load where generated code cannot run.
 // The emitters stay out, as they do in a browser bundle of the full package.
 let _aotLoader = null;
+// The browser build's on-demand code generator (lib/tiering.js): set by
+// index.browser.mjs, null in every other entry, which then carry none of it.
+let _tiering = null;
+function _registerTiering(t) { _tiering = t; }
 function _registerAot(load) {
   _aotLoader = load;
 }
@@ -329,7 +333,13 @@ function resolveSchemaByPath(rootSchema, schemaPath) {
 //
 // A failing route sees the same handful of schemaPaths over and over, which is
 // what makes the first one worth having.
-const { LazyRejection, RichRejection, LazyJsonRejection, _enrichLazy, presentErrors, needsOrdering, sortErrorsBySchemaOrder, stripOrdinal } = require('./rejections');
+// Loaded at the first compile, where every use below is, rather than with the
+// core: with it came the schema order and diagnostic modules, run at import
+// by every page that loads the package, validating or not.
+let LazyRejection, RichRejection, LazyJsonRejection, _enrichLazy, presentErrors, needsOrdering, sortErrorsBySchemaOrder, stripOrdinal;
+function _loadRejections() {
+  ({ LazyRejection, RichRejection, LazyJsonRejection, _enrichLazy, presentErrors, needsOrdering, sortErrorsBySchemaOrder, stripOrdinal } = require('./rejections'));
+}
 
 // Text that does not parse, reported the same way on every path and platform:
 // ATA9001 with the parser's own message. The native addon used to say only
@@ -712,6 +722,21 @@ function resolveSchemaForPreprocess(schema, schemaMap) {
 // touched), `format` stripped under `assertFormat: false`, and the custom
 // keyword scan. The accessors then step aside for own data properties, so
 // every later read is a plain field.
+// What the interpreted engine is built from, besides the schema.
+function _interpArgs(self, schemaObj) {
+  const options = self._options;
+  return {
+    schemaMap: self._schemaMap.size > 0 ? self._schemaMap : null,
+    formats: self._userFormats,
+    v1: isV1Dialect(schemaObj),
+    keywords: self._keywords,
+    // compat's coercion where each type is checked (see the interpreter).
+    coerce: self._interpretOnly ? options._coerceInWalk : undefined,
+    discriminator: self._interpretOnly && options._discriminator === true,
+    numberFormats: self._interpretOnly ? options._numberFormats : undefined,
+  };
+}
+
 function _materializeSchema(self) {
   const raw = self._rawSchema;
   const options = self._options;
@@ -891,6 +916,8 @@ class Validator {
     this._verdictTail = null;
     this._validateTail = null;
     this._entryExt = null;
+    // The browser build warms the engine once, when the page is idle (lib/tiering.js).
+    if (_tiering !== null) _tiering.built(this);
 
     // Public methods start as memoized accessors on the prototype; nothing is
     // allocated per instance until one is first read. See _defineLazyMethod
@@ -943,6 +970,7 @@ class Validator {
 
   _ensureCompiled() {
     if (this._initialized) return;
+    if (LazyRejection === undefined) _loadRejections();
     this._ensureVocabularies();
     this._initialized = true;
     // Errors behind a reference into a registered document are ordered as
@@ -1197,18 +1225,12 @@ class Validator {
       // No JS codegen: the interpreted engine, with or without the addon. The
       // buffer APIs come from _installBufferApis on first use, as they do on
       // every other path.
-      const { createInterpreter } = require('./interpreter');
-      const interp = createInterpreter(schemaObj, {
-        schemaMap: this._schemaMap.size > 0 ? this._schemaMap : null,
-        formats: this._userFormats,
-        v1: isV1Dialect(schemaObj),
-        keywords: this._keywords,
-        // compat's coercion where each type is checked (see the interpreter).
-        coerce: this._interpretOnly ? options._coerceInWalk : undefined,
-        discriminator: this._interpretOnly && options._discriminator === true,
-        numberFormats: this._interpretOnly ? options._numberFormats : undefined,
-      });
+      const iargs = _interpArgs(this, schemaObj);
+      // The browser build may have built it while the page was idle, from
+      // the same inputs (lib/tiering.js).
+      const interp = (_tiering !== null && _tiering.adopt(this, schemaObj, iargs)) || require('./interpreter').createInterpreter(schemaObj, iargs);
       this._engine = 'interpreter';
+      if (_codegen === null && _tiering !== null && !_forceNapi && !this._v1Dynamic) _tiering.watch(this, interp);
       // A keyword that reads its data's context may also change the data (a
       // request validator deserializing a date, say). Such a schema is run
       // once per call: deciding first and walking again for the errors would
@@ -1703,7 +1725,7 @@ class Validator {
   static fromStandalone(mod, schema, opts) {
     // It loads what Validator.bundleStandalone() writes, and compiles an error
     // function when the module carries none, so it goes with those methods.
-    if (_codegen === null && _aotLoader === null) throw new TypeError('Validator.fromStandalone is not part of ata-validator/lite, like the bundle methods it loads for. Import it from ata-validator, or import a module from `ata build` directly.');
+    if (_codegen === null && _aotLoader === null && _tiering === null) throw new TypeError('Validator.fromStandalone is not part of ata-validator/lite, like the bundle methods it loads for. Import it from ata-validator, or import a module from `ata build` directly.');
     const options = opts || {};
     const schemaObj = typeof schema === "string" ? JSON.parse(schema) : schema;
 
@@ -1891,6 +1913,10 @@ function version() {
 function _aot() {
   if (_codegen !== null) return _codegen.aot();
   if (_aotLoader !== null) return _aotLoader();
+  // The browser build: emitters stay out of the page, as they did when the
+  // generator was in it (the package.json browser field maps lib/aot.js to
+  // this file); loading a built module works.
+  if (_tiering !== null) return _tiering.aotStub();
   throw new TypeError('The ahead-of-time bundle methods are not part of ata-validator/lite. Import them from ata-validator.');
 }
 Validator.bundle = function (schemas, opts) {
@@ -2280,7 +2306,9 @@ Validator.prototype.parse = function (data) {
   let fn = this._parseFn;
   if (fn === undefined) {
     fn = _buildParse(this);
-    Object.defineProperty(this, '_parseFn', { value: fn, writable: true, configurable: true, enumerable: false });
+    // A refusal only because the generator has not loaded yet is not kept:
+    // the next call, after it has, builds the copy.
+    if (!fn._untilCodegen) Object.defineProperty(this, '_parseFn', { value: fn, writable: true, configurable: true, enumerable: false });
   }
   return fn(data);
 };
@@ -2302,6 +2330,11 @@ function _buildParse(self) {
   // isValidObject, which runs them, and a property they check with instanceof
   // is carried over as it is (see clone-emit).
   const extended = self._verdictTail !== null || self._validateTail !== null;
+  if (_codegen === null && _tiering !== null) {
+    const later = decline('in the browser build the code generator loads on demand', "Import 'ata-validator/codegen' once at startup to have it from the first call.");
+    later._untilCodegen = true;
+    return later;
+  }
   if (_codegen === null) return decline('this entry has no code generator to build the copy with', 'Use validate(); a valid result carries the input as it is.');
   return _codegen.buildParse(self, decline, extended);
 }
@@ -2408,7 +2441,14 @@ _defineLazyMethod('isValidObject', (self) => {
     const { buildTier0Plan, tier0Validate } = require("./tier0");
     const _plan = buildTier0Plan(self._schemaObj);
     let _n = 0;
-    _bindVerdict(self, (d) => {
+    // In the browser build the generator is not there yet: count the calls
+    // like the interpreted engine does, or a schema checked only through
+    // this method stays on the plan walk, four times slower, for good.
+    const _tick = _codegen === null && _tiering !== null && !self._interpretOnly && !env('ATA_FORCE_NAPI') ? _tiering.counter(self) : null;
+    _bindVerdict(self, _tick !== null ? (d) => {
+      _tick();
+      return tier0Validate(_plan, d);
+    } : (d) => {
       const r = tier0Validate(_plan, d);
       if (++_n === 2) {
         try { self._ensureCodegen(); } catch {}
@@ -2478,6 +2518,9 @@ module.exports = {
 // How an entry registers the code generator. Not enumerable, so the exported
 // surface of `require('ata-validator')` is what it was.
 Object.defineProperty(module.exports, '_registerCodegen', { value: _registerCodegen, enumerable: false });
+Object.defineProperty(module.exports, '_registerTiering', { value: _registerTiering, enumerable: false });
+Object.defineProperty(module.exports, '_codegenRegistered', { value: () => _codegen !== null, enumerable: false });
+Object.defineProperty(module.exports, '_tiering', { get: () => _tiering, enumerable: false });
 Object.defineProperty(module.exports, '_registerAot', { value: _registerAot, enumerable: false });
 // What the compiled paths in index.js need from this module.
-Object.defineProperty(module.exports, '_internals', { value: { _jsonSyntaxRejection, ABORT_EARLY_RESULT, HYBRID_TIER_CALLS, SIMDJSON_THRESHOLD, VALID_RESULT, _bindEntry, _bindVerdict, _compileCache, _compileCacheSet, _mustReject, _rememberInstance, _verboseWrap, compileCacheKey, getNative, isV1Dialect, resolveSchemaByPath }, enumerable: false });
+Object.defineProperty(module.exports, '_internals', { value: { _interpArgs, _normalizeCallerSchemaUncached, resolveSchemaForPreprocess, _jsonSyntaxRejection, ABORT_EARLY_RESULT, HYBRID_TIER_CALLS, SIMDJSON_THRESHOLD, VALID_RESULT, _bindEntry, _bindVerdict, _compileCache, _compileCacheSet, _mustReject, _rememberInstance, _verboseWrap, compileCacheKey, getNative, isV1Dialect, resolveSchemaByPath }, enumerable: false });

package/lib/version.js

@@ -7,4 +7,4 @@
 //
 // Kept in lockstep with package.json by `tests/test_version_sync.js`.
 
-module.exports = '1.55.0';
+module.exports = '1.57.0';

package/lite.d.ts

@@ -1,4 +1,6 @@
-// ata-validator/lite: the same Validator and one-shot functions as
+// ata-validator/lite, kept for code that already imports it; new code imports
+// ata-validator, whose browser build loads the code generator on demand.
+// The same Validator and one-shot functions as
 // ata-validator, on the interpreted engine and without the code generator.
 // Validator#parse and the static bundle methods throw a TypeError here.
 export {

package/lite.js

@@ -1,6 +1,11 @@
 'use strict';
 
-// ata-validator/lite: the Validator without the code generator. Every schema
+// ata-validator/lite, kept for code that already imports it. The browser build
+// of ata-validator now starts on the interpreted engine and loads the code
+// generator only on demand, so a page needs nothing else; new code imports
+// ata-validator.
+//
+// The Validator without the code generator. Every schema
 // runs on the interpreted engine, which passes the same official test suite as
 // the compiled path and never calls `new Function`, so it also runs under a
 // strict Content-Security-Policy. The results are the ones `ata-validator`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.55.0",
+  "version": "1.57.0",
   "description": "JSON Schema validator that compiles to plain JavaScript, still runs where code generation is blocked, and can be compiled away at build time. Passes the full official test suite.",
   "type": "commonjs",
   "main": "index.js",
@@ -70,9 +70,17 @@
       "import": "./error-runtime.mjs",
       "require": "./error-runtime.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./codegen": {
+      "types": "./codegen.d.ts",
+      "import": "./codegen.mjs",
+      "require": "./codegen.js"
+    }
   },
-  "sideEffects": false,
+  "sideEffects": [
+    "./codegen.js",
+    "./codegen.mjs"
+  ],
   "bin": {
     "ata": "bin/ata.js"
   },
@@ -171,16 +179,19 @@
     "error-runtime.d.ts",
     "bin/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "codegen.js",
+    "codegen.mjs",
+    "codegen.d.ts"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.55.0",
-    "@ata-validator/native-darwin-x64": "1.55.0",
-    "@ata-validator/native-linux-arm64-gnu": "1.55.0",
-    "@ata-validator/native-linux-arm64-musl": "1.55.0",
-    "@ata-validator/native-linux-x64-gnu": "1.55.0",
-    "@ata-validator/native-linux-x64-musl": "1.55.0",
-    "@ata-validator/native-win32-x64": "1.55.0"
+    "@ata-validator/native-darwin-arm64": "1.57.0",
+    "@ata-validator/native-darwin-x64": "1.57.0",
+    "@ata-validator/native-linux-arm64-gnu": "1.57.0",
+    "@ata-validator/native-linux-arm64-musl": "1.57.0",
+    "@ata-validator/native-linux-x64-gnu": "1.57.0",
+    "@ata-validator/native-linux-x64-musl": "1.57.0",
+    "@ata-validator/native-win32-x64": "1.57.0"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"
@@ -192,7 +203,7 @@
   },
   "devDependencies": {
     "@sinclair/typebox": "^0.34.49",
-    "@types/node": "^25.8.0",
+    "@types/node": "^26.6.5",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "cmake-js": "^8.0.0",