Skip to content

feat: trap-free introspection primitives (isProxy, brand checks, descriptor reads) - #24

Merged
TooTallNate merged 2 commits into
mainfrom
introspection-primitives
Jul 23, 2026
Merged

TooTallNate merged 2 commits into
mainfrom
introspection-primitives

Conversation

@TooTallNate

Copy link
Copy Markdown
Collaborator

Summary

Adds an engine-level introspection surface to JSValueHandle whose unifying contract is: none of these primitives execute guest code (no proxy traps, no getters, no Symbol.hasInstance, no prototype-chain method lookups), and none can be spoofed or broken by guest-side prototype/constructor mutation. This makes them safe to call on hostile or unknown values — the two motivating consumers are inspector UIs (see the browser example changes here) and side-effect-free serialization of guest values (needed for deterministic-replay use cases, where accidentally running a getter during serialization corrupts replayability).

All primitives are thin wrappers over quickjs-ng APIs that already existed in the engine (JS_IsProxy, JS_IsMap, JS_GetOwnProperty, JS_GetProxyTarget, …) but were not plumbed through the WASM interface.

New JSValueHandle API

  • Brand checks: isProxy, isMap, isSet, isDate, isRegExp, isWeakRef, isWeakMap, isWeakSet, isDataView, classId
    • isProxy is the crown jewel: proxy detection is impossible from within JS by spec
    • A Proxy wrapping a Map is not isMap — unwrap via getProxyTarget() (matches quickjs-ng's JS_IsArray behavior, which no longer punches through proxies)
  • getProxyTarget() / getProxyHandler(): [[ProxyTarget]]/[[ProxyHandler]] access without firing traps (DevTools-style)
  • getOwnPropertyKeys(): Reflect.ownKeys semantics — string and symbol keys, including non-enumerable (the existing get_own_property_names* exports are string-only)
  • getOwnPropertyDescriptor(key): descriptor reads without invoking getters; accepts string or symbol keys; accessor properties yield get/set handles that can be invoked later on demand

Browser example

Upgraded to react-inspector 8.1.0 (adds a descriptor-aware DataAccessor — vercel-labs/react-inspector#data-accessor-abstraction, vendored as a tarball under examples/browser/vendor/) and reworked jsValueAccessor so rendering is now fully side-effect free:

  • isDate/isRegExp use brand checks instead of the spoofable, getter-invoking constructorName lookup
  • Proxies render Chrome DevTools-style with synthetic [[Target]]/[[Handler]] rows — previously every render fired ownKeys/get/getPrototypeOf traps
  • Getter properties render as a lazy, clickable (...) (Chrome-style) instead of being eagerly invoked during render
  • isIterable trusts isMap/isSet brands and never probes proxies

Tests

19 new tests in test/introspection.test.ts. The two that spec the core contract:

  • a proxy whose handler is itself a proxy with a counting get trap (every engine-initiated trap lookup is counted) — asserts trapCount === 0 across isProxy, brand checks, and getProxyTarget/Handler
  • a side-effect-counting getter — asserts getterCalls === 0 after a descriptor read

Plus spoof-resistance ({constructor: Date}, Symbol.hasInstance, Symbol.toStringTag, prototype nulling, globalThis.Date reassignment), nested proxies, symbol-keyed descriptors, and snapshot/restore survival.

Validation

  • make quickjs.wasm clean
  • tsc clean (root + example); example vite build clean
  • Full vitest suite: 31 files, 1815 tests passing

…riptor reads)

New engine-level introspection surface that never executes guest code
and cannot be spoofed by prototype/constructor mutation:

- Brand checks: isProxy, isMap, isSet, isDate, isRegExp, isWeakRef,
  isWeakMap, isWeakSet, isDataView, and classId
- getProxyTarget()/getProxyHandler(): [[ProxyTarget]]/[[ProxyHandler]]
  access without firing traps
- getOwnPropertyKeys(): Reflect.ownKeys semantics (string + symbol
  keys, including non-enumerable)
- getOwnPropertyDescriptor(): descriptor reads without invoking
  getters; accepts string or symbol keys

Browser example: upgraded to react-inspector 8.1.0 (descriptor-aware
DataAccessor) and reworked the accessor to render side-effect free —
brand-based Date/RegExp detection, DevTools-style [[Target]]/[[Handler]]
proxy rows, and Chrome-style lazy "(...)" getters.
@vercel

vercel Bot commented Jul 23, 2026 •

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
quickjs-wasi Ready Ready Preview, Comment Jul 23, 2026 9:42am

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new engine-level introspection surface on JSValueHandle for “no guest-code execution” inspection (brand checks, Proxy internals access, symbol-aware key enumeration, and getter-safe descriptor reads), and updates the browser inspector example + documentation/tests to use these primitives.

Changes:

  • Introduces trap-free brand checks (isProxy, isMap, isSet, isDate, etc.), classId, Proxy target/handler accessors, and safe own-key/descriptor reads on JSValueHandle.
  • Updates the browser example’s DataAccessor to avoid side effects (Proxy-safe rendering, lazy getter display via descriptors).
  • Adds a comprehensive test suite for the new primitives and updates docs/changeset + vendored react-inspector dependency.

Reviewed changes

Copilot reviewed 7 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
c/interface.c Exposes quickjs-ng engine primitives (brand checks, Proxy internals, own-key/descriptor reads) to WASM.
src/index.ts Adds new JSValueHandle APIs (is* brand checks, classId, getProxyTarget/Handler, getOwnPropertyKeys, getOwnPropertyDescriptor).
test/introspection.test.ts New tests covering trap-free guarantees, spoof resistance, symbols, descriptors, and snapshot/restore behavior.
examples/browser/main.tsx Reworks inspector integration to be side-effect free and Proxy-aware; uses descriptor reads for accessors.
examples/browser/package.json Switches react-inspector dependency to a vendored tarball.
pnpm-lock.yaml Lockfile updates for the vendored react-inspector tarball.
README.md Documents the new introspection APIs.
.changeset/trap-free-introspection.md Declares a minor release for the new API surface.
Files not reviewed (1)
  • pnpm-lock.yaml: Generated file

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread test/introspection.test.ts Resolved
Comment thread README.md Resolved
Comment thread examples/browser/main.tsx Resolved
- Dispose temporary evalCode handles in proxy identity test
- README: qualify the trap-free guarantee — property-inspection helpers
  fire ownKeys/getOwnPropertyDescriptor traps on Proxies
- Browser example: dispose discarded guest-undefined get/set handles
  when translating descriptors

This branch was successfully deployed

1 active deployment
Preview — a2ec696e Deployed Jul 23, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants