[kungfooman]

Fixes #316

Primer

Runtime Type Inspector validates values where the engine runs and reports where the panel reads, often across an iframe boundary that shares values live without cloning. Two prototype systems then disagree: the checking realm's Array (or Map, Set, Promise, class) constructor is not the panel realm's, so every instanceof check against a realm-local constructor fails for a genuine foreign value, and every prototype-identity gate (Object.getPrototypeOf(value) === Object.prototype) rejects foreign plain objects. The validators and the on-click differ both contained such gates at exactly the places where a verdict turns: container acceptance (validateArray, validateMap, validateSet, validateTuple, validatePromise, validateIArguments, validateGlobalConstructor), template inference collection (collectCandidates), snapshot tagging and traversal (tagSnapshot, snapshotTag), and log serialization (stringifyValue). The fast-path scans added a second, independent verdict hazard: firstBadIndex and firstBadEntry skip the full validation loop when their cheap predicates report clean, which is only sound when the predicates mirror the full loop exactly — and neither consulted element-level userland hooks (customTypes, customValidations), so a rejecting hook was silently bypassed. The union differ had the mirror-image flaw: it picked the closest structural match with no validator consultation, printing "matches no union member" for values the validator accepted (nominal trust, option leniency), which is exactly the phantom-row class from production (data.anchor, data.color, data.margin each flagged closest is number[] with 1 problem while the checker passed them).

What changed

1. src-runtime/isPromiseValue.js (new, barrel-exported, spec-pinned in realmBrand.spec.js): brand check (Object.prototype.toString is [object Promise]) replacing instanceof Promise in validatePromise. Thenables still fail (no duck-typing); foreign promises pass.
2. src-runtime/validateGlobalConstructor.js keeps instanceof for same-realm subclasses, then falls back to constructor-name equality for live-shared platform instances (foreign Float32Array validates; plain impostor shapes fail). validateGlobalConstructor.spec.js (new) pins local, foreign, impostor, and unknown-name cases.
3. src-runtime/validateIArguments.js checks typeof value[Symbol.iterator] === 'function' instead of instanceof Function, so foreign iterables pass the protocol check.
4. src-runtime/collectCandidates.js uses isArrayValue in its object, tuple, and array branches, so template inference collects positionally from foreign arrays and stops treating foreign arrays as objects with named properties.
5. src-runtime/tagSnapshot.js traverses and excludes by brand (isMapValue/isSetValue) instead of instanceof Map/Set, so instances nested in foreign maps keep their $type tags and foreign maps serialize by entries.
6. src-runtime/stringifyValue.js gates its Map/Set branches on the same brands, so foreign maps log as {Map, entries} instead of collapsing to keyless {}.
7. src-runtime/firstBadIndex.js bails to a full scan (returns 0) when customValidations is non-empty or customTypes holds the scanned primitive (customTypes.number for number, and so on). Reproduced before the fix: customTypes.number = () => false plus [1, 2] vs number[] validated true.
8. src-runtime/firstBadEntry.js bails to -2 when a customTypes hook shadows a registered class name, in all three class branches (keys, bare values, single-arg references). Reproduced before the fix: customTypes.LiveBox = () => false plus Map<string, LiveBox> of genuine instances validated clean.
9. src-runtime/explainMismatch.js gains the last-resort union passes-gate: when every member fails structurally, each member is probed with the validator itself, and a passing member diffs clean. The gate only ever converts would-be rows to clean, never the reverse, so structurally clean members (with their informational children) keep flowing through the existing loop untouched. Reproduced before the fix: {a: 1, typo: 2} vs {a: number} | {b: string} with Exact objects off printed "matches no union member" for a passing value.
10. src-runtime/plugin-windowed/windowedOptions.js corrects the spend-budget doc to what the code does: the accumulated scan total restarts on size changes; same-size value replacements keep riding until the next scheduled full scan (at most one window away, bounded by mapCheckWindowCap), because observing content without scanning is exactly what riding skips.
11. src-runtime/liveSharing.spec.js (new, 21 tests) is the hostile local-vs-foreign battery: every verdict runs the same shape twice (local build plus vm.runInNewContext live-shared build) and asserts agreement — arrays, tuples, nested members, Maps/Sets with entry checks, promises vs thenables, foreign iterables, IArguments, positional template candidates, tag traversal through foreign maps, Map serialization, mistyped-foreign still fails, wrong-tag fails, foreign same-spelled instances under Partial, deep foreign nesting pinpointing, frozen/sparse/proxied arrays, array-likes, constructor-name platform checks, and display survival. firstBadIndex.spec.js gains the hook-bypass pins; firstBadEntry.spec.js gains the class-hook shadowing pin.

Proof

1. The tmp/repro-windowing.mjs harness (scratch, not committed) showed got true, want false on the hook-rejection cases before the fix and got false after, with the production cross-realm matrix (tmp/repro-matrix.mjs, foreign arrays plus tagged snapshot) diffing to exactly the one genuine alignment row in all four environments (same-realm, cloned, foreign live-shared, missing classes).
2. Every fix is mutation-pinned: stashing firstBadIndex.js fails exactly the two hook tests; stashing firstBadEntry.js fails exactly the shadowing test; reverting any brand swap fails exactly its live-sharing tests; dropping the union gate fails exactly testExcessUnionStaysClean; reverting snapshotTag.js fails 13 tag specs; narrowing unwrapTransparent fails 8 nominal tests. Restores verified green after each.
3. tmp/repro-real-color.mjs (scratch) diffs the real 12-method engine Color harvest (parsed out of playcanvas-engine's own .rti.mjs) against the tagged snapshot with both registries present and absent: clean in both, matching the worker's nominal accept.

Latent holes

1. The windowed map ride still skips up to one window of checks after a same-size value mutation: the spend/size proxy cannot observe content without scanning, which is the documented tradeoff (windowedOptions states the latency bound; rides stay off by default with a 100ms earn budget). Verdict: tolerated deliberately — detection is bounded, never lost, and false positives stay impossible.
2. The differ still reports genuine data defects on live instances the validator passes nominally (a mistyped prop on a live LiveBox diffs data.rows[0].get("a").w while validation trusts the identity, same as tsc trusting the declared type). The union gate suppresses only the misleading "no member matches" verdict; a direct member row names a real defect. Verdict: tolerated deliberately and pinned (testDeepForeignNestingPinpoints asserts both halves).
3. describeValue, Warning, typeTree, and DisplayAnything keep realm-local instanceof branches: they render, never decide, and foreign values degrade to generic-but-correct displays instead of throwing (pinned by testForeignDisplaysSurvive). Verdict: tolerated deliberately — display-only, no verdict path reads them.
4. validateTypeof keeps nominal identity for class targets: a foreign same-named class correctly fails, since nominal identity cannot cross realms. Verdict: tolerated deliberately — typeof X is about the registered constructor, not the brand.