@lexical/fast-check 0.0.0-bootstrap.0 → 0.51.1-nightly.20260918.0

package/README.md

@@ -1,3 +1,121 @@
-# @lexical/fast-check
+# `@lexical/fast-check`
 
-This 0.0.0-bootstrap.0 placeholder was published only to claim the npm package name so trusted publishing can be configured on npmjs.com. It contains no code; a future release will replace it.
+[![See API Documentation](https://lexical.dev/img/see-api-documentation.svg)](https://lexical.dev/docs/api/modules/lexical_fast-check)
+
+This package derives [fast-check](https://fast-check.dev) arbitraries from the
+serialization schemas Lexical nodes declare on `$config`, so property-based tests
+generate exactly the serialized JSON a node's parser accepts.
+
+Install it alongside `fast-check`, which is a peer dependency:
+
+```sh
+npm install --save-dev @lexical/fast-check fast-check
+```
+
+## Usage
+
+[`nodeArbitrary(NodeClass)`](https://lexical.dev/docs/api/modules/lexical_fast-check#nodearbitrary) generates the node-specific properties of a
+serialized node, composing the schemas the class inherits (an element-based
+node also gets `direction`/`format`/`indent`/… from `ElementNode`). Every
+property is generated independently as present or absent, because that is the
+domain parsers actually face: an older document predates a property, and a
+compact export omits one whose value equals its default.
+
+The values are typed as the parse shape of the class's own serialized type —
+`LexicalParseJSON<SerializedMyNode>` for a `MyNode` that declares
+`exportJSON(): SerializedMyNode` — which is what its `updateFromJSON` accepts,
+so they can be handed to it without a cast.
+
+```ts
+import {nodeArbitrary} from '@lexical/fast-check';
+import * as fc from 'fast-check';
+
+fc.assert(
+  fc.property(nodeArbitrary(MyNode), props => {
+    const json = {...props, type: 'my-node'};
+    // importing and re-exporting is a fixed point
+    expect(exportOf(importOf(json))).toEqual(exportOf(importOf(exportOf(importOf(json)))));
+  }),
+);
+```
+
+[`nodeArbitrary`](https://lexical.dev/docs/api/modules/lexical_fast-check#nodearbitrary) reads the class's `$config`, so no editor or node instance is
+required — but resolving it injects the class's synthesized statics and compiles
+its accessor tables, so a class whose schema names an accessor it does not have
+throws here. To inspect what a node declares without generating anything, call
+`getComposedSchemaFields(NodeClass)` from `lexical` directly.
+
+## Example: proving a clone carries your node's properties
+
+A custom node has to copy its own properties in `afterCloneFrom`, which Lexical
+calls whenever `getWritable()` clones the node. Declaring a new property and
+forgetting to copy it there is a silent bug: the field still exists on the clone
+because the constructor set it, so nothing throws — the node just reverts that
+one property to its default the next time anything writes to it.
+
+This is a good fit for a generated test, because a hand-written fixture tends to
+use default values, and a dropped property compares equal to its default. The
+test looks like it passed precisely when the bug is invisible. [`nodeArbitrary`](https://lexical.dev/docs/api/modules/lexical_fast-check#nodearbitrary)
+draws from the schema's own domain instead, so the values are in-domain and
+mostly not the default:
+
+```ts
+import {nodeArbitrary} from '@lexical/fast-check';
+import * as fc from 'fast-check';
+import {
+  $create,
+  $createParagraphNode,
+  $getNodeByKey,
+  $getRoot,
+  createEditor,
+  TextNode,
+} from 'lexical';
+
+test('a clone carries every property TextNode declares', () => {
+  fc.assert(
+    fc.property(nodeArbitrary(TextNode), props => {
+      const editor = createEditor({
+        nodes: [TextNode],
+        onError: e => {
+          throw e;
+        },
+      });
+      let key, before, original;
+
+      // A node is only cloned *across* updates. Within one, getWritable()
+      // hands back the same object, so a single-update test never reaches
+      // afterCloneFrom at all.
+      editor.update(() => {
+        const node = $create(TextNode);
+        // Everything but `text` is used exactly as generated. An empty
+        // TextNode is removed by normalization between the two updates, so
+        // there would be nothing left to clone; a leaf also cannot be a child
+        // of the root, hence the paragraph.
+        node.updateFromJSON({...props, text: 'x'});
+        $getRoot().clear().append($createParagraphNode().append(node));
+        [key, original, before] = [node.getKey(), node, node.exportJSON()];
+      }, {discrete: true});
+
+      editor.update(() => {
+        const writable = $getNodeByKey(key).getWritable();
+        expect(writable).not.toBe(original); // a clone really happened
+        expect(writable.exportJSON()).toEqual(before);
+      }, {discrete: true});
+    }),
+  );
+});
+```
+
+When it fails, fast-check shrinks to the smallest value that exposes it, which
+names the property for you. Deleting `this.__style = prevNode.__style` from
+`TextNode.afterCloneFrom` reports:
+
+```
+Counterexample: [{"style":" "}]
+
+-   "style": " ",
++   "style": "",
+```
+
+A single space — the smallest style that is not the default `''`, and the only
+kind of value that can catch this.

package/dist/LexicalFastCheck.dev.js

@@ -0,0 +1,233 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import * as fc from 'fast-check';
+import { getComposedSchemaFields, declaredAccepts } from 'lexical';
+
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+
+/**
+ * Derive a fast-check arbitrary for the node-specific properties of `klass`'s
+ * serialized JSON, composing the schemas it inherits
+ * — so an element-based node generates the properties it gets from ElementNode
+ * as well as its own. Spread the result with `type`/`version` to feed
+ * `importJSON`. Because each property's schema is the same one the node uses
+ * to parse its JSON, the generated values are exactly what the node's parser
+ * accepts — a single declaration powers both parsing and example generation.
+ *
+ * Every property is generated independently as present or absent
+ * (`requiredKeys: []`), because that is the domain the parsers actually face:
+ * a `SerializedPartial` may omit any node-specific property — older documents
+ * predate a property, and a compact export omits one whose value equals its
+ * default. Generating complete records only would leave the defaulting path
+ * (the whole point of a schema carrying a `defaultValue`) untested.
+ *
+ * The values are typed as what the class's schemas *accept*, composed across
+ * its `$config` chain — not as what they parse to. The two differ wherever a
+ * schema reads more than it writes, and this generator produces exactly that
+ * difference: an `aliasedValue`'s legacy spellings are in the generated domain
+ * (see the `aliased` case below), so a type describing the parsed output would
+ * be wrong about the values it hands back.
+ */
+function nodeArbitrary(klass) {
+  const fields = getComposedSchemaFields(klass);
+  const record = {};
+  for (const key of Object.keys(fields)) {
+    record[key] = schemaArbitrary(fields[key]);
+  }
+  // Both sides now read the same `$config` chain — the value through
+  // `getComposedSchemaFields`, the type through `LexicalSchemaInput` — so the
+  // cast is asserting that two walks of one declaration agree. Where they can
+  // still part company is a config that names no `extends`: the runtime walk
+  // falls back to the prototype parent, the type walk has nothing to follow
+  // and stops, and the type comes back missing the properties the value
+  // carries. Naming `extends` is what keeps them together.
+  //
+  // What the cast is *not* covering is a flat NodeState: this generates the
+  // JSON that carries one, and `LexicalSchemaInput` types those keys `unknown`
+  // for the same reason `StateConfig.parse` takes `unknown` — nothing records
+  // what a state accepted on the way in. It said `V` until recently, which the
+  // cast would have asserted away: a `string`-to-`Date` state generated strings
+  // that a caller could have read as dates.
+  return fc.record(record, {
+    requiredKeys: []
+  });
+}
+
+/**
+ * The arbitrary for one schema: what its metadata describes, narrowed to what
+ * the schema itself admits.
+ *
+ * The metadata describes what the *combinator* accepts, and a schema whose
+ * author installed a membership predicate of its own admits less than that —
+ * a `nullable(stringValue())` that takes only `#`-prefixed strings still
+ * carries `nullable` metadata, so generating from the metadata alone produced
+ * values it declines. A round-trip property then failed on values this claimed
+ * were in domain, or passed while a sibling union member silently rewrote
+ * them.
+ *
+ * Filtered rather than generated differently, because the predicate is an
+ * opaque function: what it admits can only be discovered by asking it.
+ */
+function schemaArbitrary(schema) {
+  const arbitrary = metaArbitrary(schema.meta);
+  const accepts = declaredAccepts(schema);
+  if (accepts === undefined) {
+    return arbitrary;
+  }
+  const claims = value => accepts.call(schema, value);
+  // `filter` retries without a cap, so a predicate the metadata's domain
+  // cannot satisfy makes generation spin rather than fail — synchronously, so
+  // a test runner's own timeout cannot interrupt it and nothing names the
+  // property responsible. A `rawValue()` narrowed to strings is exactly that:
+  // its metadata describes no domain, so `raw` generates `undefined` alone and
+  // no draw is ever accepted. Probing first turns the hang into a diagnostic.
+  //
+  // Asked once per schema: the answer cannot change, and this recurses, so a
+  // node with five narrowed properties otherwise burned five thousand
+  // discarded draws every time its arbitrary was built.
+  let satisfiable = SATISFIABLE.get(schema);
+  if (satisfiable === undefined) {
+    satisfiable = fc.sample(arbitrary, {
+      numRuns: FILTER_PROBE_RUNS,
+      seed: 0
+    }).some(claims);
+    SATISFIABLE.set(schema, satisfiable);
+  }
+  if (!satisfiable) {
+    throw new Error(`nodeArbitrary: a schema of kind ${String(schema.meta.kind)} declares a membership predicate that rejected all ${FILTER_PROBE_RUNS} values its metadata generates, so no example can be drawn for it. Widen the predicate, or describe the narrowed domain in the schema's metadata.`);
+  }
+  return arbitrary.filter(claims);
+}
+
+/**
+ * Whether a schema's declared predicate can be satisfied over its metadata's
+ * domain — a property of the schema alone, so it is asked once, the same
+ * reason the core memoizes `$isCatchAll`.
+ */
+const SATISFIABLE = new WeakMap();
+
+/**
+ * How many draws {@link schemaArbitrary} tries before calling a declared
+ * predicate unsatisfiable over its metadata's domain. Large enough that a
+ * predicate accepting a reasonable fraction is never mistaken for one that
+ * accepts nothing, small enough to cost nothing next to a property run.
+ */
+const FILTER_PROBE_RUNS = 1000;
+function metaArbitrary(meta) {
+  switch (meta.kind) {
+    case 'string':
+      return fc.string();
+    case 'number':
+      {
+        const {
+          min,
+          max,
+          integer
+        } = meta;
+        if (!integer) {
+          return fc.double({
+            max,
+            min,
+            noDefaultInfinity: true,
+            noNaN: true
+          });
+        }
+        // `fc.integer` takes an integral interval within the safe integers, and
+        // `numberValue` accepts a domain that is neither: an absent bound is
+        // unbounded, where fc.integer's own absent bound is the 32-bit range —
+        // so a domain starting past 2^31 - 1 arrived as a maximum below its own
+        // minimum and threw instead of generating.
+        //
+        // Clamping to the safe integers is what keeps the values exact: past
+        // 2^53 the integers are no longer adjacent — `1e16 + 1 === 1e16` — so
+        // generating there would produce values the schema's own `Number
+        // .isInteger` test cannot distinguish. The rounding is belt and braces:
+        // `numberValue` already rounds an integer domain's bounds inward, so a
+        // fractional one reaches here only from a meta built by hand.
+        const low = Math.max(min === undefined ? Number.MIN_SAFE_INTEGER : Math.ceil(min), Number.MIN_SAFE_INTEGER);
+        const high = Math.min(max === undefined ? Number.MAX_SAFE_INTEGER : Math.floor(max), Number.MAX_SAFE_INTEGER);
+        if (low <= high) {
+          return fc.integer({
+            max: high,
+            min: low
+          });
+        }
+        // Nothing survived: the domain lies entirely outside the safe integers
+        // (`{integer: true, min: 1e16}`), or holds no integer at all
+        // (`{integer: true, min: 0.5, max: 0.7}`) — which `numberValue` refuses
+        // to build, so it arrives only from a meta written by hand. Its own
+        // rounded bound is the closest thing to a member it has: in domain for
+        // the first, and for the second parsed back to the schema's default,
+        // which is what every value of an empty domain does.
+        return fc.constant(min === undefined ? high : Math.ceil(min));
+      }
+    case 'boolean':
+      return fc.boolean();
+    case 'enum':
+      return fc.constantFrom(...meta.values);
+    case 'array':
+      return fc.array(schemaArbitrary(meta.item));
+    case 'nullable':
+      return fc.option(schemaArbitrary(meta.inner), {
+        nil: null
+      });
+    case 'optional':
+      return fc.option(schemaArbitrary(meta.inner), {
+        nil: undefined
+      });
+    case 'union':
+      return fc.oneof(...meta.members.map(member => schemaArbitrary(member)));
+    case 'aliased':
+      {
+        // The aliases are legacy input spellings the schema still accepts, so
+        // they belong in the generated domain exactly as much as the inner one
+        // does — that is what makes them worth stating as data.
+        const inner = schemaArbitrary(meta.inner);
+        const aliases = Object.keys(meta.aliases);
+        // `fc.constantFrom()` with nothing to choose from throws, so a schema
+        // that declares no alias generates its inner domain alone — which is
+        // what it accepts. An empty table parses fine, so it must generate fine.
+        return aliases.length === 0 ? inner : fc.oneof(inner, fc.constantFrom(...aliases));
+      }
+    case 'transform':
+      // What is generated here is serialized *input*, and a transform changes
+      // only the output, so the domain to draw from is the inner one — the
+      // same answer inheriting the inner meta used to give, now reached
+      // deliberately rather than by the transform being invisible.
+      return schemaArbitrary(meta.inner);
+    case 'raw':
+      // The schema deliberately does not describe this value's domain (its
+      // owner validates it), so there is nothing to generate from.
+      return fc.constant(undefined);
+    case 'object':
+      {
+        const fields = {};
+        for (const key of Object.keys(meta.fields)) {
+          fields[key] = schemaArbitrary(meta.fields[key]);
+        }
+        return fc.record(fields);
+      }
+    default:
+      // Unreachable for the schemas `lexical` defines — the switch is
+      // exhaustive over SerializationSchemaMeta — but a hand-rolled schema
+      // (or one from a newer core) can carry a kind this build has never
+      // heard of. Say so, rather than returning undefined and failing inside
+      // fast-check's record builder.
+      throw new Error(`nodeArbitrary: unsupported serialization schema kind ${String(meta.kind)}`);
+  }
+}
+
+export { nodeArbitrary };

package/dist/LexicalFastCheck.js

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import * as modDev from './LexicalFastCheck.dev.js';
+import * as modProd from './LexicalFastCheck.prod.js';
+const mod = process.env.NODE_ENV !== 'production' ? modDev : modProd;
+export const nodeArbitrary = mod.nodeArbitrary;

package/dist/LexicalFastCheck.js.flow

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ */
+
+import type {LexicalNode} from 'lexical';
+
+// fast-check has no Flow types; the arbitrary is opaque here.
+declare export function nodeArbitrary(
+  klass: Class<LexicalNode>,
+): $FlowFixMe;

package/dist/LexicalFastCheck.prod.js

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import*as e from"fast-check";import{getComposedSchemaFields as n,declaredAccepts as r}from"lexical";function t(r){const t=n(r),o={};for(const e of Object.keys(t))o[e]=a(t[e]);return e.record(o,{requiredKeys:[]})}function a(n){const t=function(n){switch(n.kind){case"string":return e.string();case"number":{const{min:r,max:t,integer:a}=n;if(!a)return e.double({max:t,min:r,noDefaultInfinity:!0,noNaN:!0});const o=Math.max(void 0===r?Number.MIN_SAFE_INTEGER:Math.ceil(r),Number.MIN_SAFE_INTEGER),i=Math.min(void 0===t?Number.MAX_SAFE_INTEGER:Math.floor(t),Number.MAX_SAFE_INTEGER);return o<=i?e.integer({max:i,min:o}):e.constant(void 0===r?i:Math.ceil(r))}case"boolean":return e.boolean();case"enum":return e.constantFrom(...n.values);case"array":return e.array(a(n.item));case"nullable":return e.option(a(n.inner),{nil:null});case"optional":return e.option(a(n.inner),{nil:void 0});case"union":return e.oneof(...n.members.map(e=>a(e)));case"aliased":{const r=a(n.inner),t=Object.keys(n.aliases);return 0===t.length?r:e.oneof(r,e.constantFrom(...t))}case"transform":return a(n.inner);case"raw":return e.constant(void 0);case"object":{const r={};for(const e of Object.keys(n.fields))r[e]=a(n.fields[e]);return e.record(r)}default:throw new Error(`nodeArbitrary: unsupported serialization schema kind ${String(n.kind)}`)}}(n.meta),s=r(n);if(void 0===s)return t;const c=e=>s.call(n,e);let m=o.get(n);if(void 0===m&&(m=e.sample(t,{numRuns:i,seed:0}).some(c),o.set(n,m)),!m)throw new Error(`nodeArbitrary: a schema of kind ${String(n.meta.kind)} declares a membership predicate that rejected all ${i} values its metadata generates, so no example can be drawn for it. Widen the predicate, or describe the narrowed domain in the schema's metadata.`);return t.filter(c)}const o=new WeakMap,i=1e3;export{t as nodeArbitrary};

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import type { Klass, LexicalNode, LexicalSchemaInput } from 'lexical';
+import * as fc from 'fast-check';
+/**
+ * Derive a fast-check arbitrary for the node-specific properties of `klass`'s
+ * serialized JSON, composing the schemas it inherits
+ * — so an element-based node generates the properties it gets from ElementNode
+ * as well as its own. Spread the result with `type`/`version` to feed
+ * `importJSON`. Because each property's schema is the same one the node uses
+ * to parse its JSON, the generated values are exactly what the node's parser
+ * accepts — a single declaration powers both parsing and example generation.
+ *
+ * Every property is generated independently as present or absent
+ * (`requiredKeys: []`), because that is the domain the parsers actually face:
+ * a `SerializedPartial` may omit any node-specific property — older documents
+ * predate a property, and a compact export omits one whose value equals its
+ * default. Generating complete records only would leave the defaulting path
+ * (the whole point of a schema carrying a `defaultValue`) untested.
+ *
+ * The values are typed as what the class's schemas *accept*, composed across
+ * its `$config` chain — not as what they parse to. The two differ wherever a
+ * schema reads more than it writes, and this generator produces exactly that
+ * difference: an `aliasedValue`'s legacy spellings are in the generated domain
+ * (see the `aliased` case below), so a type describing the parsed output would
+ * be wrong about the values it hands back.
+ */
+export declare function nodeArbitrary<T extends LexicalNode>(klass: Klass<T>): fc.Arbitrary<LexicalSchemaInput<T>>;

package/dist/typescript-too-old.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+// You are seeing this declaration file because your TypeScript cannot read
+// Lexical's types through the package.json "exports" field.
+//
+// Lexical requires TypeScript >= 5.2 with "moduleResolution" set to
+// "bundler", "node16", or "nodenext". To fix this:
+//   1. Upgrade TypeScript to >= 5.2.
+//   2. In tsconfig.json set "moduleResolution" to "bundler" (recommended for
+//      apps/bundlers) or "node16" / "nodenext", and a matching "module".
+import 'Lexical requires TypeScript >=5.2 with moduleResolution bundler, node16, or nodenext';
+export {};

package/package.json

@@ -1,11 +1,69 @@
 {
-  "description": "Placeholder published to claim the npm name during trusted publishing setup. Do not install.",
-  "homepage": "https://lexical.dev",
-  "license": "MIT",
   "name": "@lexical/fast-check",
+  "description": "fast-check arbitraries derived from the JSON schemas Lexical nodes declare on $config, for property-based tests.",
+  "keywords": [
+    "lexical",
+    "editor",
+    "rich-text",
+    "fast-check",
+    "property-based testing",
+    "serialization"
+  ],
+  "license": "MIT",
+  "version": "0.51.1-nightly.20260918.0",
+  "main": "./dist/LexicalFastCheck.js",
+  "types": "./dist/typescript-too-old.d.ts",
+  "dependencies": {
+    "lexical": "0.51.1-nightly.20260918.0"
+  },
+  "peerDependencies": {
+    "fast-check": ">=4.0.0",
+    "typescript": ">=5.2"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "fast-check": "^4.8.0"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/facebook/lexical.git"
+    "url": "git+https://github.com/facebook/lexical.git",
+    "directory": "packages/lexical-fast-check"
+  },
+  "module": "./dist/LexicalFastCheck.js",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types@<5.2": "./dist/typescript-too-old.d.ts",
+      "types": "./dist/index.d.ts",
+      "development": "./dist/LexicalFastCheck.dev.js",
+      "production": "./dist/LexicalFastCheck.prod.js",
+      "default": "./dist/LexicalFastCheck.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/__tests__",
+    "!src/__bench__",
+    "!src/__mocks__",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.bench.ts",
+    "!src/**/*.bench.tsx",
+    "README.md",
+    "LICENSE"
+  ],
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/typescript-too-old.d.ts"
+      ]
+    }
   },
-  "version": "0.0.0-bootstrap.0"
-}
+  "type": "module"
+}

package/src/index.ts

@@ -0,0 +1,236 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type {
+  AnySerializationSchema,
+  Klass,
+  LexicalNode,
+  LexicalSchemaInput,
+  SerializationSchemaMeta,
+} from 'lexical';
+
+import * as fc from 'fast-check';
+// `declaredAccepts` is `@internal`, re-exported from the package entry the way
+// `getComposedSchemaFields` is: a deep `lexical/src/*` import resolves only
+// through this repo's tsconfig paths, so it does not build and would give a
+// consumer a second copy of the module — and a second `DERIVED_ACCEPTS`, which
+// is module-scope state the answer depends on.
+import {declaredAccepts, getComposedSchemaFields} from 'lexical';
+
+/**
+ * Derive a fast-check arbitrary for the node-specific properties of `klass`'s
+ * serialized JSON, composing the schemas it inherits
+ * — so an element-based node generates the properties it gets from ElementNode
+ * as well as its own. Spread the result with `type`/`version` to feed
+ * `importJSON`. Because each property's schema is the same one the node uses
+ * to parse its JSON, the generated values are exactly what the node's parser
+ * accepts — a single declaration powers both parsing and example generation.
+ *
+ * Every property is generated independently as present or absent
+ * (`requiredKeys: []`), because that is the domain the parsers actually face:
+ * a `SerializedPartial` may omit any node-specific property — older documents
+ * predate a property, and a compact export omits one whose value equals its
+ * default. Generating complete records only would leave the defaulting path
+ * (the whole point of a schema carrying a `defaultValue`) untested.
+ *
+ * The values are typed as what the class's schemas *accept*, composed across
+ * its `$config` chain — not as what they parse to. The two differ wherever a
+ * schema reads more than it writes, and this generator produces exactly that
+ * difference: an `aliasedValue`'s legacy spellings are in the generated domain
+ * (see the `aliased` case below), so a type describing the parsed output would
+ * be wrong about the values it hands back.
+ */
+export function nodeArbitrary<T extends LexicalNode>(
+  klass: Klass<T>,
+): fc.Arbitrary<LexicalSchemaInput<T>> {
+  const fields = getComposedSchemaFields(klass);
+  const record: {[key: string]: fc.Arbitrary<unknown>} = {};
+  for (const key of Object.keys(fields)) {
+    record[key] = schemaArbitrary(fields[key]);
+  }
+  // Both sides now read the same `$config` chain — the value through
+  // `getComposedSchemaFields`, the type through `LexicalSchemaInput` — so the
+  // cast is asserting that two walks of one declaration agree. Where they can
+  // still part company is a config that names no `extends`: the runtime walk
+  // falls back to the prototype parent, the type walk has nothing to follow
+  // and stops, and the type comes back missing the properties the value
+  // carries. Naming `extends` is what keeps them together.
+  //
+  // What the cast is *not* covering is a flat NodeState: this generates the
+  // JSON that carries one, and `LexicalSchemaInput` types those keys `unknown`
+  // for the same reason `StateConfig.parse` takes `unknown` — nothing records
+  // what a state accepted on the way in. It said `V` until recently, which the
+  // cast would have asserted away: a `string`-to-`Date` state generated strings
+  // that a caller could have read as dates.
+  return fc.record(record, {requiredKeys: []}) as fc.Arbitrary<
+    LexicalSchemaInput<T>
+  >;
+}
+
+/**
+ * The arbitrary for one schema: what its metadata describes, narrowed to what
+ * the schema itself admits.
+ *
+ * The metadata describes what the *combinator* accepts, and a schema whose
+ * author installed a membership predicate of its own admits less than that —
+ * a `nullable(stringValue())` that takes only `#`-prefixed strings still
+ * carries `nullable` metadata, so generating from the metadata alone produced
+ * values it declines. A round-trip property then failed on values this claimed
+ * were in domain, or passed while a sibling union member silently rewrote
+ * them.
+ *
+ * Filtered rather than generated differently, because the predicate is an
+ * opaque function: what it admits can only be discovered by asking it.
+ */
+function schemaArbitrary(
+  schema: AnySerializationSchema,
+): fc.Arbitrary<unknown> {
+  const arbitrary = metaArbitrary(schema.meta);
+  const accepts = declaredAccepts(schema);
+  if (accepts === undefined) {
+    return arbitrary;
+  }
+  const claims = (value: unknown) => accepts.call(schema, value);
+  // `filter` retries without a cap, so a predicate the metadata's domain
+  // cannot satisfy makes generation spin rather than fail — synchronously, so
+  // a test runner's own timeout cannot interrupt it and nothing names the
+  // property responsible. A `rawValue()` narrowed to strings is exactly that:
+  // its metadata describes no domain, so `raw` generates `undefined` alone and
+  // no draw is ever accepted. Probing first turns the hang into a diagnostic.
+  //
+  // Asked once per schema: the answer cannot change, and this recurses, so a
+  // node with five narrowed properties otherwise burned five thousand
+  // discarded draws every time its arbitrary was built.
+  let satisfiable = SATISFIABLE.get(schema);
+  if (satisfiable === undefined) {
+    satisfiable = fc
+      .sample(arbitrary, {numRuns: FILTER_PROBE_RUNS, seed: 0})
+      .some(claims);
+    SATISFIABLE.set(schema, satisfiable);
+  }
+  if (!satisfiable) {
+    throw new Error(
+      `nodeArbitrary: a schema of kind ${String(
+        schema.meta.kind,
+      )} declares a membership predicate that rejected all ${FILTER_PROBE_RUNS} values its metadata generates, so no example can be drawn for it. Widen the predicate, or describe the narrowed domain in the schema's metadata.`,
+    );
+  }
+  return arbitrary.filter(claims);
+}
+
+/**
+ * Whether a schema's declared predicate can be satisfied over its metadata's
+ * domain — a property of the schema alone, so it is asked once, the same
+ * reason the core memoizes `$isCatchAll`.
+ */
+const SATISFIABLE = new WeakMap<AnySerializationSchema, boolean>();
+
+/**
+ * How many draws {@link schemaArbitrary} tries before calling a declared
+ * predicate unsatisfiable over its metadata's domain. Large enough that a
+ * predicate accepting a reasonable fraction is never mistaken for one that
+ * accepts nothing, small enough to cost nothing next to a property run.
+ */
+const FILTER_PROBE_RUNS = 1000;
+
+function metaArbitrary(meta: SerializationSchemaMeta): fc.Arbitrary<unknown> {
+  switch (meta.kind) {
+    case 'string':
+      return fc.string();
+    case 'number': {
+      const {min, max, integer} = meta;
+      if (!integer) {
+        return fc.double({max, min, noDefaultInfinity: true, noNaN: true});
+      }
+      // `fc.integer` takes an integral interval within the safe integers, and
+      // `numberValue` accepts a domain that is neither: an absent bound is
+      // unbounded, where fc.integer's own absent bound is the 32-bit range —
+      // so a domain starting past 2^31 - 1 arrived as a maximum below its own
+      // minimum and threw instead of generating.
+      //
+      // Clamping to the safe integers is what keeps the values exact: past
+      // 2^53 the integers are no longer adjacent — `1e16 + 1 === 1e16` — so
+      // generating there would produce values the schema's own `Number
+      // .isInteger` test cannot distinguish. The rounding is belt and braces:
+      // `numberValue` already rounds an integer domain's bounds inward, so a
+      // fractional one reaches here only from a meta built by hand.
+      const low = Math.max(
+        min === undefined ? Number.MIN_SAFE_INTEGER : Math.ceil(min),
+        Number.MIN_SAFE_INTEGER,
+      );
+      const high = Math.min(
+        max === undefined ? Number.MAX_SAFE_INTEGER : Math.floor(max),
+        Number.MAX_SAFE_INTEGER,
+      );
+      if (low <= high) {
+        return fc.integer({max: high, min: low});
+      }
+      // Nothing survived: the domain lies entirely outside the safe integers
+      // (`{integer: true, min: 1e16}`), or holds no integer at all
+      // (`{integer: true, min: 0.5, max: 0.7}`) — which `numberValue` refuses
+      // to build, so it arrives only from a meta written by hand. Its own
+      // rounded bound is the closest thing to a member it has: in domain for
+      // the first, and for the second parsed back to the schema's default,
+      // which is what every value of an empty domain does.
+      return fc.constant(min === undefined ? high : Math.ceil(min));
+    }
+    case 'boolean':
+      return fc.boolean();
+    case 'enum':
+      return fc.constantFrom(...meta.values);
+    case 'array':
+      return fc.array(schemaArbitrary(meta.item));
+    case 'nullable':
+      return fc.option(schemaArbitrary(meta.inner), {nil: null});
+    case 'optional':
+      return fc.option(schemaArbitrary(meta.inner), {nil: undefined});
+    case 'union':
+      return fc.oneof(...meta.members.map(member => schemaArbitrary(member)));
+    case 'aliased': {
+      // The aliases are legacy input spellings the schema still accepts, so
+      // they belong in the generated domain exactly as much as the inner one
+      // does — that is what makes them worth stating as data.
+      const inner = schemaArbitrary(meta.inner);
+      const aliases = Object.keys(meta.aliases);
+      // `fc.constantFrom()` with nothing to choose from throws, so a schema
+      // that declares no alias generates its inner domain alone — which is
+      // what it accepts. An empty table parses fine, so it must generate fine.
+      return aliases.length === 0
+        ? inner
+        : fc.oneof(inner, fc.constantFrom(...aliases));
+    }
+    case 'transform':
+      // What is generated here is serialized *input*, and a transform changes
+      // only the output, so the domain to draw from is the inner one — the
+      // same answer inheriting the inner meta used to give, now reached
+      // deliberately rather than by the transform being invisible.
+      return schemaArbitrary(meta.inner);
+    case 'raw':
+      // The schema deliberately does not describe this value's domain (its
+      // owner validates it), so there is nothing to generate from.
+      return fc.constant(undefined);
+    case 'object': {
+      const fields: {[key: string]: fc.Arbitrary<unknown>} = {};
+      for (const key of Object.keys(meta.fields)) {
+        fields[key] = schemaArbitrary(meta.fields[key]);
+      }
+      return fc.record(fields);
+    }
+    default:
+      // Unreachable for the schemas `lexical` defines — the switch is
+      // exhaustive over SerializationSchemaMeta — but a hand-rolled schema
+      // (or one from a newer core) can carry a kind this build has never
+      // heard of. Say so, rather than returning undefined and failing inside
+      // fast-check's record builder.
+      throw new Error(
+        `nodeArbitrary: unsupported serialization schema kind ${String(
+          (meta as {kind?: unknown}).kind,
+        )}`,
+      );
+  }
+}