Repository navigation
feat: trap-free introspection primitives (isProxy, brand checks, descriptor reads) - #24
Merged
Merged
Conversation
…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.
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
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 onJSValueHandle. - Updates the browser example’s
DataAccessorto 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-inspectordependency.
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.
- 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
Merged
This was referenced Jul 27, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an engine-level introspection surface to
JSValueHandlewhose unifying contract is: none of these primitives execute guest code (no proxy traps, no getters, noSymbol.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
JSValueHandleAPIisProxy,isMap,isSet,isDate,isRegExp,isWeakRef,isWeakMap,isWeakSet,isDataView,classIdisProxyis the crown jewel: proxy detection is impossible from within JS by specisMap— unwrap viagetProxyTarget()(matches quickjs-ng'sJS_IsArraybehavior, which no longer punches through proxies)getProxyTarget()/getProxyHandler():[[ProxyTarget]]/[[ProxyHandler]]access without firing traps (DevTools-style)getOwnPropertyKeys():Reflect.ownKeyssemantics — string and symbol keys, including non-enumerable (the existingget_own_property_names*exports are string-only)getOwnPropertyDescriptor(key): descriptor reads without invoking getters; accepts string or symbol keys; accessor properties yieldget/sethandles that can be invoked later on demandBrowser example
Upgraded to react-inspector 8.1.0 (adds a descriptor-aware
DataAccessor— vercel-labs/react-inspector#data-accessor-abstraction, vendored as a tarball underexamples/browser/vendor/) and reworkedjsValueAccessorso rendering is now fully side-effect free:isDate/isRegExpuse brand checks instead of the spoofable, getter-invokingconstructorNamelookup[[Target]]/[[Handler]]rows — previously every render firedownKeys/get/getPrototypeOftraps(...)(Chrome-style) instead of being eagerly invoked during renderisIterabletrustsisMap/isSetbrands and never probes proxiesTests
19 new tests in
test/introspection.test.ts. The two that spec the core contract:gettrap (every engine-initiated trap lookup is counted) — assertstrapCount === 0acrossisProxy, brand checks, andgetProxyTarget/HandlergetterCalls === 0after a descriptor readPlus spoof-resistance (
{constructor: Date},Symbol.hasInstance,Symbol.toStringTag, prototype nulling,globalThis.Datereassignment), nested proxies, symbol-keyed descriptors, and snapshot/restore survival.Validation
make quickjs.wasmcleantscclean (root + example); examplevite buildclean