@jxsuite/schema 5.4.0 → 5.6.0

package/class-schema.json

@@ -8,6 +8,7 @@
           "type": "string"
         },
         "body": {
+          "description": "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
           "oneOf": [
             {
               "type": "string"
@@ -120,6 +121,7 @@
           "type": "string"
         },
         "body": {
+          "description": "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
           "oneOf": [
             {
               "type": "string"

package/defs/class-def.schema.ts

@@ -67,6 +67,8 @@ export const classConstructorDefSchema = {
   properties: {
     $prototype: { const: "Function", type: "string" },
     body: {
+      description:
+        "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
       oneOf: [{ type: "string" }, { items: { type: "string" }, type: "array" }],
     },
     description: { type: "string" },
@@ -103,6 +105,8 @@ export const classMethodDefSchema = {
     $prototype: { const: "Function", type: "string" },
     access: { enum: ["public", "private", "protected"], type: "string" },
     body: {
+      description:
+        "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
       oneOf: [{ type: "string" }, { items: { type: "string" }, type: "array" }],
     },
     description: { type: "string" },

package/defs/function-def.schema.ts

@@ -2,8 +2,9 @@ export const functionDefSchema = {
   additionalProperties: false,
   description:
     'A function declaration. $prototype must be "Function". ' +
-    "body (inline) and $src (external) are mutually exclusive. " +
+    "body (inline) and $src (external) are mutually exclusive; declaring both is an error. " +
     "First parameter is always state (the reactive scope).",
+  not: { required: ["body", "$src"] },
   properties: {
     $export: {
       description: "Named export in $src module. Defaults to the state key name.",
@@ -32,11 +33,12 @@ export const functionDefSchema = {
     },
     body: {
       description:
-        "Inline function body: an opaque JS source string (first implicit parameter is state), or a structured statement array (spec §20) — explicit structured function declaration, analyzable by tooling and editable visually. The escalation ladder within the shape is structured statements → JS string.",
+        "Inline function body: a source string in erasable TypeScript, which plain JavaScript already is (spec §23.1; types are erased before it is analysed or run; first implicit parameter is state), or a structured statement array (spec §20) — explicit structured function declaration, analyzable by tooling and editable visually. The escalation ladder within the shape is structured statements → source string.",
       examples: [
         "state.count++",
         'state.items.push({ id: Date.now(), text: "", done: false })',
         'return state.score >= 90 ? "gold" : "silver"',
+        "const input = event.target as HTMLInputElement; state.label = input.value",
         [
           { operator: "push", target: { $ref: "#/state/cart" }, value: 1 },
           { dispatchEvent: "cart-changed", detail: { $ref: "#/state/cart" } },

package/package.json

@@ -18,6 +18,7 @@
     "./project-schemas": "./src/project-schemas.ts",
     "./validate-project": "./src/validate-project.ts",
     "./types": "./types.ts",
+    "./function-role": "./src/function-role.ts",
     "./guards": "./src/guards.ts",
     "./locale": "./src/locale.ts",
     "./intl": "./src/intl.ts",
@@ -29,6 +30,7 @@
     "./ijson": "./src/ijson.ts",
     "./parse": "./src/parse.ts",
     "./jxn": "./src/jxn/index.ts",
+    "./virtual-types": "./src/jxn/virtual-types.ts",
     "./project-file": "./src/project-file.ts",
     "./project-file/node": "./src/project-file-node.ts",
     "./doc-ops": "./src/doc-ops.ts",
@@ -66,7 +68,7 @@
     "upgrade": "bun update --latest && bun install"
   },
   "type": "module",
-  "version": "5.4.0",
+  "version": "5.6.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/schema.json

@@ -205,7 +205,13 @@
     },
     "FunctionDef": {
       "additionalProperties": false,
-      "description": "A function declaration. $prototype must be \"Function\". body (inline) and $src (external) are mutually exclusive. First parameter is always state (the reactive scope).",
+      "description": "A function declaration. $prototype must be \"Function\". body (inline) and $src (external) are mutually exclusive; declaring both is an error. First parameter is always state (the reactive scope).",
+      "not": {
+        "required": [
+          "body",
+          "$src"
+        ]
+      },
       "properties": {
         "$export": {
           "description": "Named export in $src module. Defaults to the state key name.",
@@ -241,11 +247,12 @@
           "type": "array"
         },
         "body": {
-          "description": "Inline function body: an opaque JS source string (first implicit parameter is state), or a structured statement array (spec §20) — explicit structured function declaration, analyzable by tooling and editable visually. The escalation ladder within the shape is structured statements → JS string.",
+          "description": "Inline function body: a source string in erasable TypeScript, which plain JavaScript already is (spec §23.1; types are erased before it is analysed or run; first implicit parameter is state), or a structured statement array (spec §20) — explicit structured function declaration, analyzable by tooling and editable visually. The escalation ladder within the shape is structured statements → source string.",
           "examples": [
             "state.count++",
             "state.items.push({ id: Date.now(), text: \"\", done: false })",
             "return state.score >= 90 ? \"gold\" : \"silver\"",
+            "const input = event.target as HTMLInputElement; state.label = input.value",
             [
               {
                 "operator": "push",
@@ -506,6 +513,7 @@
           "type": "string"
         },
         "body": {
+          "description": "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
           "oneOf": [
             {
               "type": "string"
@@ -577,6 +585,7 @@
           "type": "string"
         },
         "body": {
+          "description": "The member's body in erasable TypeScript, which plain JavaScript already is (spec §23.1), as one string or as an array of lines.",
           "oneOf": [
             {
               "type": "string"

package/src/component-meta.ts

@@ -32,6 +32,11 @@ export interface ComponentPropDef {
   /** Absent for a full-form entry that declares no `default`. */
   default?: JsonValue | undefined;
   format?: unknown;
+  /**
+   * The values the entry admits, read from its JSON Schema `enum` (spec.md §5.3). Absent when the
+   * entry declares none, so a prop with a closed set of values is told apart from free text.
+   */
+  enum?: JsonValue[];
 }
 
 /** What discovery reports for one component document. */
@@ -150,12 +155,16 @@ function propFrom(name: string, def: JsonValue): ComponentPropDef | null {
   if (fields.$prototype || fields.$handler || fields.$compute) {
     return null;
   }
-  return {
+  const prop: ComponentPropDef = {
     default: fields.default,
     format: fields.format,
     name,
     type: fields.type,
   };
+  if (Array.isArray(fields.enum)) {
+    prop.enum = fields.enum;
+  }
+  return prop;
 }
 
 /**

package/src/function-role.ts

@@ -0,0 +1,182 @@
+/**
+ * One verdict per `$prototype: "Function"` entry: is it a **computed** value, read reactively, or a
+ * **callable**, invoked by an event, a call site or the host?
+ *
+ * Every tier reads this one classifier (the interpreter's `buildScope`, both compiled targets and
+ * the build-time scope), so a document means the same thing in Studio and in production. It reads
+ * the document, never an imported function's arity or source: a compiler has only the document, and
+ * `fn.toString()` of a bundled import is not a stable input (spec.md §5.3 4b, 4d).
+ *
+ * @docs framework/concepts/functions
+ */
+import {
+  bodyReturnsValue,
+  hasStructuredBody,
+  isFunctionDef,
+  isJsonObject,
+  isRef,
+  isString,
+  paramNames,
+} from "./guards";
+import type { JsonValue, JxElement, JxFunctionDef } from "../types";
+
+/** What a Function entry is to the tiers that read it. */
+export type FunctionRole = "computed" | "callable";
+
+/** Lifecycle hooks the generated element calls itself, so they are never `$ref`'d (spec.md §16.4). */
+export const LIFECYCLE_KEYS: ReadonlySet<string> = new Set(["onMount", "onUnmount", "onAdopted"]);
+
+/**
+ * The state keys a document uses as a _callable_, at any depth: bound to an `on*` event (a
+ * definition's root-level handlers included, §16.1), invoked by an `$expression` `call` node
+ * (§19.4c), called as `state.key(…)` from a template string or another function's body, or named as
+ * a lifecycle hook (§16.4). `$defs` holds JSON Schema, not usage, and is skipped.
+ *
+ * Anything not used as a callable has its return value read reactively. Defaulting the other way
+ * round would turn a called helper into a value and break its call site.
+ */
+function collectCallableKeys(doc: JxElement): Set<string> {
+  const keys = new Set<string>();
+  const seen = new Set<object>();
+
+  const addStateRef = (ref: string): void => {
+    if (ref.startsWith("#/state/")) {
+      /* SAFETY: `String.prototype.split` always returns at least one element (the whole string
+         when the separator is absent), so index 0 is present. */
+      keys.add(ref.slice("#/state/".length).split("/")[0] as string);
+    }
+  };
+
+  const visit = (node: JsonValue | undefined): void => {
+    if (isString(node)) {
+      // `${state.formatDate(d)}` in a template, or `state.helper(x)` in another function's body.
+      for (const call of node.matchAll(/\bstate\.([A-Za-z_$][\w$]*)\s*\(/gu)) {
+        /* SAFETY: the pattern's one capture group is not optional, so every match fills index 1
+           with the called member's name. */
+        keys.add(call[1] as string);
+      }
+      return;
+    }
+    if (Array.isArray(node)) {
+      if (!seen.has(node)) {
+        seen.add(node);
+        for (const item of node) {
+          visit(item);
+        }
+      }
+      return;
+    }
+    if (!isJsonObject(node) || seen.has(node)) {
+      return;
+    }
+    seen.add(node);
+    // An `$expression` `call` node names its callee in `target` (spec.md §19.4c).
+    if (node.operator === "call" && isRef(node.target)) {
+      addStateRef(node.target.$ref);
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "$defs") {
+        continue;
+      }
+      if (key.startsWith("on") && isRef(value)) {
+        addStateRef(value.$ref);
+      }
+      visit(value);
+    }
+  };
+
+  // SAFETY: a Jx element is JSON data; its type names what it holds.
+  visit(doc as JsonValue);
+  for (const hook of LIFECYCLE_KEYS) {
+    if (isJsonObject(doc.state) && hook in doc.state) {
+      keys.add(hook);
+    }
+  }
+  return keys;
+}
+
+/**
+ * Does a Function declaration name both a `body` and a `$src`? The two are mutually exclusive
+ * (spec.md §5.3 4d), and the test is presence, as the `FunctionDef` schema's `not` is, so an empty
+ * `body: ""` beside a `$src` is refused too and `jx validate` agrees with every tier.
+ *
+ * @param def A Function declaration, a `state` entry or a handler written inline on an `on*` key.
+ */
+export function declaresBodyAndSrc(def: JxFunctionDef): boolean {
+  return "body" in def && "$src" in def;
+}
+
+/**
+ * Does a Function declaration list any parameter of its own, by `parameters` or the legacy
+ * `arguments`? An inline handler that does not is rewritten to read `state` as the handler's alias,
+ * and one that does is built with {@link handlerParamNames}.
+ *
+ * @param def A Function declaration.
+ */
+export function declaresParameters(def: JxFunctionDef): boolean {
+  return paramNames(def.parameters ?? def.arguments).length > 0;
+}
+
+/**
+ * The formal parameters a string `body` is built with, in every tier (spec.md §5.3 4d): `state`
+ * first, then the other declared names in declared order. Binding is by position, as ECMAScript's
+ * is, so a name that is not `state` receives whatever the call site passes in that position. An
+ * event binding calls a handler `(state, event)`, so the first other name is the event and a later
+ * one is `undefined` from an event (a call with too few arguments), filled by a call site that
+ * passes it. A declared `state` is moved to the front rather than repeated, since a duplicate
+ * parameter is a sloppy-mode quirk in which the later one wins and `state` would be `undefined`.
+ *
+ * @param def A Function declaration, a `state` entry or a handler written inline on an `on*` key.
+ */
+export function handlerParamNames(def: JxFunctionDef): string[] {
+  const list = ["state"];
+  for (const name of paramNames(def.parameters ?? def.arguments)) {
+    if (name !== "state") {
+      list.push(name);
+    }
+  }
+  return list;
+}
+
+/** The rules in order: the first that applies decides. */
+function functionEntryRole(
+  key: string,
+  def: JxFunctionDef,
+  callableKeys: () => Set<string>,
+): FunctionRole {
+  if (hasStructuredBody(def)) {
+    return "callable";
+  }
+  // Declared parameters or arguments make an entry callable wherever it is used (§19.4c).
+  if (paramNames(def.parameters ?? def.arguments).length > 0) {
+    return "callable";
+  }
+  if (isString(def.body)) {
+    return bodyReturnsValue(def.body) ? "computed" : "callable";
+  }
+  if (def.$src) {
+    return callableKeys().has(key) ? "callable" : "computed";
+  }
+  return "callable";
+}
+
+/**
+ * Classify every Function entry in a document's `state`. Other state shapes get no verdict. The
+ * document is the one a tier builds, after the project-state merge, so a project-global entry one
+ * page calls and another only reads is a function on the first and a computed on the second.
+ *
+ * The walk for usage runs at most once, and only when a bodyless `$src` entry reaches it.
+ *
+ * @param doc The document (or just `{ state }`) being built.
+ */
+export function classifyFunctionEntries(doc: JxElement): Map<string, FunctionRole> {
+  const roles = new Map<string, FunctionRole>();
+  let callable: Set<string> | null = null;
+  const callableKeys = (): Set<string> => (callable ??= collectCallableKeys(doc));
+  for (const [key, def] of Object.entries(doc.state ?? {})) {
+    if (isFunctionDef(def)) {
+      roles.set(key, functionEntryRole(key, def, callableKeys));
+    }
+  }
+  return roles;
+}

package/src/guards.ts

@@ -242,7 +242,131 @@ export function isTemplateString(value?: unknown): value is string {
  * because a newline after `return` is an ASI bare return.
  */
 export function bodyReturnsValue(body: string): boolean {
-  return /\breturn\b[^\S\n]*(?![;}\s]|$)/.test(body);
+  return /\breturn\b[^\S\n]*(?![;}\s]|$)/.test(maskCode(body));
+}
+
+/**
+ * Whether an object is a function entry, whose `body` is code (`spec.md` §23.1): a `Function`
+ * entry, or a class member, which a `.class.json` names by its `role` alone. A field is a member
+ * with no body. Any other `body` may be data, so it is never read as code.
+ *
+ * @param value An object in a document or class definition.
+ */
+export function isFunctionEntry(value: JsonObject): boolean {
+  return value.$prototype === "Function" || (isString(value.role) && value.role !== "field");
+}
+
+/**
+ * A function body with its comments and the contents of its strings blanked, so a pattern reads
+ * only code (`spec.md` §23.1). The result is the same length, every newline kept, so an offset in
+ * it is an offset in the body. A string keeps its quotes, so `return "x"` still returns a value,
+ * and a template literal's `${…}` keeps its contents, which are code.
+ *
+ * A scanner and not a parser, because the interpreter must answer the same way and cannot carry
+ * one. Its known limit: a regular expression literal is read as code, so a quote inside one can
+ * blank what follows it.
+ *
+ * @param body The body, already JavaScript.
+ */
+export function maskCode(body: string): string {
+  // Nothing can open a comment or a string: the body is all code, and most handlers are.
+  if (!/[/'"`]/u.test(body)) {
+    return body;
+  }
+  const known = masked.get(body);
+  if (known !== undefined) {
+    return known;
+  }
+  const result = scanCode(body);
+  if (masked.size >= MASKED_LIMIT) {
+    masked.clear();
+  }
+  masked.set(body, result);
+  return result;
+}
+
+/**
+ * Bodies already masked. Every pattern a compile runs over a body reads it masked, and a dev server
+ * compiles the same bodies again on every change, so the scan is done once per text. Bounded,
+ * because a long session sees many texts.
+ */
+const masked = new Map<string, string>();
+const MASKED_LIMIT = 2048;
+
+/** The scan {@link maskCode} caches. */
+function scanCode(body: string): string {
+  /* UTF-16 units, as `at` counts them. Code points (`[...body]`) made an astral character in a
+     string one element for two offsets, so the result came back short and every offset after it,
+     which is what a caller splices the body at, was off by one. */
+  const out = body.split("");
+  const blank = (at: number): void => {
+    if (out[at] !== undefined && out[at] !== "\n") {
+      out[at] = " ";
+    }
+  };
+  /** The brace depth of each template substitution still open, innermost last. */
+  const substitutions: number[] = [];
+  let inTemplate = false;
+  let at = 0;
+  while (at < body.length) {
+    const char = body.charAt(at);
+    if (inTemplate) {
+      if (char === "\\") {
+        blank(at);
+        blank(at + 1);
+        at += 2;
+      } else if (char === "`") {
+        inTemplate = false;
+        at += 1;
+      } else if (char === "$" && body.charAt(at + 1) === "{") {
+        substitutions.push(0);
+        inTemplate = false;
+        at += 2;
+      } else {
+        blank(at);
+        at += 1;
+      }
+    } else if (char === "/" && body.charAt(at + 1) === "/") {
+      while (at < body.length && body.charAt(at) !== "\n") {
+        blank(at);
+        at += 1;
+      }
+    } else if (char === "/" && body.charAt(at + 1) === "*") {
+      const end = body.indexOf("*/", at + 2);
+      const stop = end === -1 ? body.length : end + 2;
+      for (; at < stop; at += 1) {
+        blank(at);
+      }
+    } else if (char === "'" || char === '"') {
+      at += 1;
+      while (at < body.length && body.charAt(at) !== char && body.charAt(at) !== "\n") {
+        if (body.charAt(at) === "\\") {
+          blank(at);
+          at += 1;
+        }
+        blank(at);
+        at += 1;
+      }
+      at += 1;
+    } else if (char === "`") {
+      inTemplate = true;
+      at += 1;
+    } else {
+      const open = substitutions.length - 1;
+      if (open >= 0 && char === "{") {
+        substitutions[open] = (substitutions[open] ?? 0) + 1;
+      } else if (open >= 0 && char === "}") {
+        if (substitutions[open] === 0) {
+          substitutions.pop();
+          inTemplate = true;
+        } else {
+          substitutions[open] = (substitutions[open] ?? 1) - 1;
+        }
+      }
+      at += 1;
+    }
+  }
+  return out.join("");
 }
 
 // ─── Style guards & accessors ───────────────────────────────────────────────────

package/src/jxn/virtual-types.ts

@@ -0,0 +1,280 @@
+/**
+ * The TypeScript a checker reads for one function body (`spec.md` §23.3).
+ *
+ * A body is the inside of a function, so no checker can read it alone: `return` is not allowed at
+ * the top of a file, and `state` is not declared anywhere. This module writes the file around it. A
+ * checker is handed {@link VirtualBody.text}, finds its errors there, and {@link bodyOffsetOf} puts
+ * each one back at its place in the body the author wrote. The body is copied into the file
+ * verbatim, so that mapping is a single shift and cannot drift.
+ *
+ * It is pure and has no dependency on a compiler, a DOM or Node, so every surface that checks types
+ * (Studio's editor, and later a mapper for `tsc`) reads the same file and cannot disagree about
+ * what a document's types are.
+ *
+ * **What `State` says is what the document can prove, and no more.** A literal gives its type, an
+ * object its shape and an array the types of its items. Anything a document does not determine (a
+ * `$prototype` instance, an `$expression`, a template, a `timing: "server"` call, a `null`) is
+ * `any`, because an error about code the author cannot fix teaches them to ignore the checker. What
+ * `State` does not declare is an error: `state.nope = 1` is the case this exists to catch.
+ *
+ * @docs framework/concepts/functions
+ */
+import { classifyFunctionEntries } from "../function-role";
+import {
+  isBoolean,
+  isExpressionDef,
+  isFunctionDef,
+  isJsonObject,
+  isNumber,
+  isServerFnDef,
+  isString,
+  paramNames,
+  hasSchemaKeywords,
+} from "../guards";
+import type { JsonValue, JxElement } from "../../types";
+
+/** Where a body sits in a document. */
+export type VirtualTarget =
+  | {
+      /** A `state` entry of the document root. */
+      kind: "state";
+      key: string;
+    }
+  | {
+      /** An inline `on*` handler on the element at `path`. */
+      kind: "event";
+      eventKey: string;
+      path: readonly (string | number)[];
+    };
+
+/** One body, wrapped for a checker. */
+export interface VirtualBody {
+  /** The file a checker reads. */
+  text: string;
+  /** Where the body's first character is in {@link VirtualBody.text}. */
+  bodyStart: number;
+  /** One past the body's last character in {@link VirtualBody.text}. */
+  bodyEnd: number;
+  /** The names the function is called with, as the runtime binds them. */
+  params: string[];
+}
+
+/**
+ * Diagnostic codes that say a module could not be found. A body is not a module: it cannot `import`
+ * statically, and a dynamic `import("x")` resolves in the browser, not in the checker, so an
+ * unresolved specifier is not something the author can fix from here (`studio.md` §16.7).
+ */
+export const UNRESOLVED_MODULE_CODES: ReadonlySet<number> = new Set([2307, 2792, 7016]);
+
+/** The most levels of an object's shape written out before it is `any`. */
+const MAX_NESTING = 4;
+
+/** The most distinct item types an array's type is built from. */
+const MAX_ITEM_TYPES = 6;
+
+/** Whether a key can be written as a bare property name. */
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/u;
+
+/** A property name as TypeScript writes it. */
+function propertyName(key: string): string {
+  return IDENTIFIER.test(key) ? key : JSON.stringify(key);
+}
+
+/** The type a value's shape gives it, widened the way a mutable binding widens. */
+function typeOfValue(value: JsonValue | undefined, depth: number): string {
+  if (isString(value)) {
+    return "string";
+  }
+  if (isNumber(value)) {
+    return "number";
+  }
+  if (isBoolean(value)) {
+    return "boolean";
+  }
+  if (Array.isArray(value)) {
+    const types = [...new Set(value.map((item) => typeOfValue(item, depth + 1)))];
+    if (types.length === 0 || types.length > MAX_ITEM_TYPES || types.includes("any")) {
+      return "any[]";
+    }
+    return types.length === 1 ? `${types[0]}[]` : `(${types.join(" | ")})[]`;
+  }
+  if (isJsonObject(value) && depth < MAX_NESTING) {
+    const members = Object.entries(value).map(
+      ([key, item]) => `${propertyName(key)}: ${typeOfValue(item, depth + 1)}`,
+    );
+    return members.length === 0 ? "Record<string, any>" : `{ ${members.join("; ")} }`;
+  }
+  return "any";
+}
+
+/** The type a JSON Schema `type` keyword names. */
+function typeOfKeyword(type: JsonValue | undefined): string {
+  switch (type) {
+    case "string": {
+      return "string";
+    }
+    case "number":
+    case "integer": {
+      return "number";
+    }
+    case "boolean": {
+      return "boolean";
+    }
+    case "array": {
+      return "any[]";
+    }
+    default: {
+      return "any";
+    }
+  }
+}
+
+/** The type of one `state` entry, by the shapes of `spec.md` §5. */
+function typeOfEntry(
+  entry: JsonValue | undefined,
+  role: "computed" | "callable" | undefined,
+): string {
+  if (isString(entry)) {
+    // A template is a computed value of a type the document does not give.
+    return entry.includes("${") ? "any" : "string";
+  }
+  if (!isJsonObject(entry)) {
+    return typeOfValue(entry, 0);
+  }
+  if (isFunctionDef(entry)) {
+    return role === "computed" ? "any" : "(...args: any[]) => any";
+  }
+  if (isString(entry.$prototype) || isExpressionDef(entry) || isServerFnDef(entry)) {
+    return "any";
+  }
+  if ("default" in entry) {
+    const { default: initial } = entry;
+    return initial === null ? typeOfKeyword(entry.type) : typeOfValue(initial, 0);
+  }
+  return hasSchemaKeywords(entry) ? typeOfKeyword(entry.type) : typeOfValue(entry, 0);
+}
+
+/** The `state` object of an element, when it has one. */
+function stateOf(node: JsonValue | undefined): Record<string, JsonValue> | null {
+  return isJsonObject(node) && isJsonObject(node.state) ? node.state : null;
+}
+
+/**
+ * The elements whose `state` a body can read, outermost first: the root, then each element on the
+ * way down to the one holding the handler. A nested element's scope extends its parent's.
+ */
+function scopeChain(doc: JxElement, path: readonly (string | number)[]): JsonValue[] {
+  // SAFETY: a document is JSON data; its types name what it holds.
+  let current: JsonValue | undefined = doc as JsonValue;
+  const chain: JsonValue[] = [current];
+  for (const segment of path) {
+    current = Array.isArray(current)
+      ? current[Number(segment)]
+      : isJsonObject(current)
+        ? current[String(segment)]
+        : undefined;
+    if (stateOf(current)) {
+      // SAFETY: `stateOf` only answers for an object.
+      chain.push(current as JsonValue);
+    }
+  }
+  return chain;
+}
+
+/** The function entry a target names. */
+function definitionOf(doc: JxElement, target: VirtualTarget): JsonValue | undefined {
+  // SAFETY: a document is JSON data; its types name what it holds.
+  const root = doc as JsonValue;
+  if (target.kind === "state") {
+    return stateOf(root)?.[target.key];
+  }
+  let owner: JsonValue | undefined = root;
+  for (const segment of target.path) {
+    owner = Array.isArray(owner)
+      ? owner[Number(segment)]
+      : isJsonObject(owner)
+        ? owner[String(segment)]
+        : undefined;
+  }
+  return isJsonObject(owner) ? owner[target.eventKey] : undefined;
+}
+
+/** The names a function is called with: `state` first, then the declared names (`spec.md` §5.3). */
+function parametersOf(definition: JsonValue | undefined): string[] {
+  if (!isJsonObject(definition)) {
+    return ["state"];
+  }
+  const declared = Array.isArray(definition.parameters)
+    ? // SAFETY: `parameters` holds bare names or CEM parameter objects, the form `paramNames` reads.
+      paramNames(definition.parameters as Parameters<typeof paramNames>[0])
+    : (Array.isArray(definition.arguments) ? definition.arguments : []).filter(
+        (name): name is string => isString(name),
+      );
+  return declared[0] === "state" ? declared : ["state", ...declared];
+}
+
+/** The members of `State`, each from the innermost element that declares it. */
+function stateMembers(chain: readonly JsonValue[]): Map<string, string> {
+  const members = new Map<string, string>();
+  for (const node of chain) {
+    // SAFETY: a document is JSON data, and the chain holds only elements that carry state.
+    const roles = classifyFunctionEntries(node as JxElement);
+    for (const [key, entry] of Object.entries(stateOf(node) ?? {})) {
+      members.set(propertyName(key), typeOfEntry(entry, roles.get(key)));
+    }
+  }
+  return members;
+}
+
+/**
+ * Wrap one body for a checker.
+ *
+ * @param doc The document the body is in.
+ * @param target Which body: a root `state` entry, or an inline handler on an element.
+ * @param body The body's text, which need not be the text the document holds yet (an editor's
+ *   buffer is checked as typed).
+ * @returns The file to check, and where the body sits in it.
+ */
+export function generateBodyTypes(
+  doc: JxElement,
+  target: VirtualTarget,
+  body: string,
+): VirtualBody {
+  const params = parametersOf(definitionOf(doc, target));
+  const chain = scopeChain(doc, target.kind === "event" ? target.path : []);
+  const members = [...stateMembers(chain)].map(([name, type]) => `  ${name}: ${type};`);
+  /* A page with a layout inherits state the page does not name, so its `State` is open. Without
+     one, only the `$` members the host adds (`$media`, `$props`) are. */
+  members.push(doc.$layout === undefined ? "  [key: `$${string}`]: any;" : "  [key: string]: any;");
+  const signature = params.map((name) => `${name}: ${name === "state" ? "State" : "any"}`);
+  /* The event a handler receives is bound to a name only when the entry declares one, though the
+     runtime passes it and `window.event` holds it. Not declaring it would call a working handler
+     an error, so it is `any` wherever it is not a parameter. */
+  const head = [
+    "export {};",
+    "interface State {",
+    ...members,
+    "}",
+    "declare const event: any;",
+    `async function body(${["this: any", ...signature].join(", ")}) {`,
+    "",
+  ].join("\n");
+  return {
+    bodyEnd: head.length + body.length,
+    bodyStart: head.length,
+    params,
+    text: `${head}${body}\n}\n`,
+  };
+}
+
+/**
+ * Where a position in {@link VirtualBody.text} is in the body, or null when it is outside it (the
+ * wrapper, which the author did not write).
+ *
+ * @param unit The wrapped body.
+ * @param offset An offset in `unit.text`.
+ * @returns An offset in the body, or null.
+ */
+export function bodyOffsetOf(unit: VirtualBody, offset: number): number | null {
+  return offset >= unit.bodyStart && offset <= unit.bodyEnd ? offset - unit.bodyStart : null;
+}

package/src/project-file.ts

@@ -37,7 +37,7 @@ export type ProjectFileName = (typeof PROJECT_FILE_NAMES)[number];
  * What a new project's file is called (`site-architecture.md` §2.4). Never what an existing
  * project's is: that is whichever of {@link PROJECT_FILE_NAMES} its folder holds.
  */
-export const NEW_PROJECT_FILE_NAME: ProjectFileName = "project.json";
+export const NEW_PROJECT_FILE_NAME: ProjectFileName = "project.jxn";
 
 /**
  * Whether a file name is one a project file may have.