has no value console.log(hasValueTarget(null)) // false, not a crash // The usage: no cast, and no crash when the value is missing. const e = inputEvent console.log(hasValueTarget(e) ? e.target.value : undefined) // hi ``` "Pure" means it changes nothing; "total" means it gives an answer for every input. That predicate is exactly what the verifier accepts: `verifyPredicate` (from `tjs-lang/lang`) reports it safe, because member access and `typeof` are pure. It compiles to native JavaScript, and it is **serializable**: it is source text, so it can be captured in one place and used in another (see the next section). Hand-writing a predicate for every host object you touch is tedious, and the result drifts from what the browser really does. So the thought: could tooling **probe a real ambient environment and derive the predicate contracts automatically?** ## The payoff: author against an environment you're not running in The headline use: **type-checking and autocompletion against a non-ambient runtime — editing in a Node-based toolchain while _targeting_ the browser** (or the reverse, or Electron, or a specific Bun). Normally you have no target environment to introspect, so you fall back to a hand-maintained `.d.ts` (`lib.dom`: TypeScript's hand-written description of the browser APIs) that drifts from what the engine actually does. Because a probed contract is a **serializable predicate**, it decouples _capture_ from _consumption_ in time and space: probe the real target once (locally or in CI), bottle the contract, and a Node-side editor/typechecker consumes it with **no target present**. It beats a `.d.ts` on three axes: - **Grounded in reality, not a drifting spec** — it's what the target _actually_ exposes. happy-dom, a simulated browser used for testing in Node, reported about 1 own key on an element's `style` where real Chrome reports 678 (see the real-browser findings below); a captured contract records the real one. - **Target-specific and versioned** — capture from the _actual_ target (this browser, this Electron, this Bun), selectable/pinned, not a lowest-common- denominator lib. - **The same artifact validates at runtime** — a `.d.ts` evaporates; a predicate contract can stay as a runtime check, and it can feed autocomplete: `suggest()` (from `tjs-lang/lang`) reads a predicate and lists the concrete values it accepts, so a check for `x === 'red' || x === 'blue'` yields the completions `red` and `blue`. Why it's plausible _here_ and not a research project: TJS can already embed a predicate inside a JSON Schema (the `$predicate` keyword, via `tjs-lang/schema`), so the contract format exists. The playground's autocomplete already asks a live object for its members; it could ask a captured contract instead. And a planned feature, argument-type-driven completion (for example, knowing that `createElement('input')` returns an input element), needs exactly this metadata, taken from reality instead of written by hand. ## Contract vs. shim — the distinction that decides feasibility "A predicate that stands in for the DOM" can mean two very different things: 1. **A contract / validator** — "does this value behave enough like an `HTMLElement` / an input event / a `CSSStyleDeclaration`?" Predicates are _pure validators_, so this is squarely in scope: shape, property presence, method arity, pure invariants. 2. **A behavioral substitute** — something that, when code calls `document.createElement('div')`, actually _does_ it. Predicates **cannot** be this (they're pure, stateless, effect-free). That's a shim — happy-dom/jsdom territory. The valuable, on-thesis move is **#1 as the bridge to #2**: probe the real environment, emit a serializable predicate _contract_, and use it to **certify a stand-in** in whatever setting. The predicate isn't the DOM — it's the portable, verifiable spec a substitute must satisfy, auto-derived from reality and from the surface a given program actually touches. ## Why it fits this project - **The introspection probe already exists.** The autocomplete work runs code in a real iframe and reads live scope (`introspect-value.ts`, `introspection-bridge.ts`), and any automated real browser (a headless Chrome, say) can do the same against the real target. That's the "kick the tires" mechanism. - **Predicates are the serializable contract form** — verified, compile to native, and travel as data (the `$predicate` keyword already embeds them in JSON Schema, evaluated by `tosijs-schema` via `tjs-lang/schema`). See the trust constraint below. - **The AJS VM already models this as capabilities.** AJS, TJS's sister language, runs code in a sandbox (the VM) that gets outside powers such as `fetch` or a store only when the host passes them in explicitly. "The DOM as a capability, checked by a predicate where it is passed in" is the same pattern: a headless setting passes in a stub, and the predicate catches where it differs from the real thing. - **"Types are examples" already.** In TJS, `function greet(name: 'Alice')` means "name is a string like `'Alice'`": the type comes from an example. A probed contract does the same, with the example taken from the real environment instead of written in the source. ## The honest constraints - **Most of the DOM's contract is _behavioral_** (layout, events, mutation), which a pure predicate can't capture — only shape + pure invariants. So: - **Scope to the used surface.** Trace which ambient APIs the code actually touches (in the real iframe) and derive a contract for _that slice_, not all of `lib.dom.d.ts`. - **Behavioral conformance is a separate, impure harness** — run the same probe battery against the real env and a candidate stub, diff the outputs. The predicate is the pure shape-gate; the harness is the behavior-gate. - **A contract is code, so trust matters.** TJS's `$predicate` paths run a predicate's source only if you have marked it trusted (registered with `trustPredicate`, or the `trustAllPredicates` option). Verification is a promise to the author about their own code, not a sandbox for hostile source. So share contracts only from probes you ran yourself; accepting untrusted ones would need predicates to run on the AJS VM, which is planned, not built. - **Snapshots drift.** Browsers evolve; a captured contract is a dated snapshot. Fine — it's re-derivable, and versioning it is a feature (conformance over time). - **Non-determinism / side effects** must stay outside predicates (the `effects` tag already enforces this): a predicate validates the _data_ crossing the boundary, never performs the effect. ## Shape of the tooling (sketch) 1. **Probe** — in a real environment (an automated real browser, or the introspection iframe), walk an ambient object / a program's used surface and record: property names + `typeof`, method names + `.length` (arity), and a few sampled input→output pairs for getters whose value depends only on the object. 2. **Derive** — turn the probe record into a predicate cluster (shape checks + `typeof` guards + membership sets), run it through `verifyPredicate` (so the emitted contract is itself certified safe), and `suggest()`-mine it for the enumerable leaves. 3. **Emit** — a `$predicate` schema (naive validators see structure, aware ones run the contract) + optionally a `.d.ts`-ish view for editors. 4. **Conform** — a harness that validates a stand-in (happy-dom, a hand stub, a VM capability) against the contract, failing loud where it diverges. This is what lets you test code that expects `HTMLElement` to exist from Node, where it doesn't. ## First spike — CSS + DOM (the convergence point) Both parts of this spike were built; the results are under Findings below. `element.style` (`CSSStyleDeclaration`) is the ideal first target: it's an object the browser provides, its contents change as styles are set, and we _already have a full CSS value grammar as predicates_ (`tjs-lang/css`). So the loop is concrete and small: - **`event.target` demo** — show the `hasValueTarget` predicate compiles, is verified pure, is total, and validates a real input event while rejecting a click on a `