feat(runtime): perry/tui handles are ordinary objects (#10821 row 3)

changelog.d/honest-handle-tag-tui.md

@@ -0,0 +1,44 @@
+`perry/tui` now hands TypeScript real objects instead of small registry
+integers. Every value the module returned — a widget from `Text` / `Box` /
+`Table` / `Tabs` / …, a `state(initial)` container, a `useRef` box, and the
+`useApp()` / `useStdout()` / `useFocusManager()` singletons — used to be an id
+NaN-boxed with `POINTER_TAG`, a number pretending to be a pointer. Three
+registries minted those ids and three more were plain constants, so SIX id
+spaces shared one encoding and they collided:
+
+    useApp()          -> 1     Text("hi")   -> 1     useRef(x), first  -> 1
+    useStdout()       -> 2     Box()        -> 2     useRef(y), second -> 2
+    useFocusManager() -> 3     Spacer()     -> 3
+    state(0), first   -> 0     <- POINTER_TAG | 0, a null pointer wearing
+                                  the pointer tag
+
+`useApp() === Text("hi")` was therefore `true`, a `Map` or `Set` keyed on two
+different handles kept one entry, a `WeakMap` entry stored under a widget was
+readable through the App handle, and the first `state(0)` of a program was a
+tagged null. None of it was reachable through a type error: the values are
+indistinguishable at run time, because the encoding carries no provenance.
+
+Each kind is now a `GC_TYPE_OBJECT` with its own class id, a real ShapeId and
+ZERO own keys, so `typeof` is `"object"`, `Object.keys` is `[]`,
+`JSON.stringify` is `{}` (it was `null`), spread and `Object.assign` copy
+nothing, and two handles are two values. `useApp()`, `useStdout()` and
+`useFocusManager()` still answer the SAME object on every call — ink's do, and
+perry's did too while they were constants — so they are per-realm singletons in
+rooted slots rather than re-minted per call. `useRef` is likewise stable across
+renders: the hook slot owns its handle object.
+
+`state.get()` / `.set(v)`, `ref.get()` / `.set(v)`, `app.exit()` /
+`.waitUntilExit()`, `stdout.write()` / `.columns()` / `.rows()` and
+`focusManager.focusNext()` / `.focusPrevious()` / `.focus(id)` are now real
+methods on a per-kind prototype as well as the statically lowered
+`class_filter` rows they already were. Before this they existed ONLY as static
+lowerings, so a handle reached through an untyped value (`const s: any = state(0)`)
+answered `undefined` for every one of them.
+
+The registry ids are unchanged and stay the module's internal currency: the
+widget tree, the Taffy layout pass, the paint pass and the hook slots all still
+speak ids, and only the value that crosses the FFI boundary changed. A handle
+of one kind can no longer address another kind's registry entry, which the
+overlapping id spaces previously allowed — `tui::is_known_handle` and the three
+`contains_handle` probes it unioned are deleted, because a class-id load answers
+the same question without asking three mutexes.

crates/perry-runtime/src/event_target.rs

@@ -14,16 +14,16 @@ use crate::{
 use std::collections::HashSet;
 use std::sync::{Mutex, OnceLock};
 
-pub const CLASS_ID_EVENT: u32 = 0xFFFF_2403;
-pub const CLASS_ID_CUSTOM_EVENT: u32 = 0xFFFF_2404;
-pub const CLASS_ID_DOM_EXCEPTION: u32 = 0xFFFF_2405;
+pub const CLASS_ID_EVENT: u32 = crate::native_class_ids::EVENT;
+pub const CLASS_ID_CUSTOM_EVENT: u32 = crate::native_class_ids::CUSTOM_EVENT;
+pub const CLASS_ID_DOM_EXCEPTION: u32 = crate::native_class_ids::DOM_EXCEPTION;
 /// `EventTarget` base class. Stamped on `new EventTarget()` instances and used
 /// as the PARENT class id of a user `class X extends EventTarget` (wired by
 /// `js_register_class_parent_dynamic` via `global_builtin_constructor_class_id`).
 /// Walking to it through the class chain is what lets a subclass instance be
 /// recognized as an event target (#6301). Keep in sync with the reserved id in
 /// perry-codegen/src/expr/instance_misc1.rs.
-pub const CLASS_ID_EVENT_TARGET: u32 = 0xFFFF_2406;
+pub const CLASS_ID_EVENT_TARGET: u32 = crate::native_class_ids::EVENT_TARGET;
 
 const TAG_UNDEFINED: u64 = 0x7FFC_0000_0000_0001;
 const TAG_NULL: u64 = 0x7FFC_0000_0000_0002;

crates/perry-runtime/src/hot_diag/receiver_repr.rs

@@ -206,10 +206,13 @@ fn observe_pointer(addr: usize) {
     // receiver can be a small band id any more and this family can never be
     // marked old again. The fixture below asserts `observed_old == 0` for it;
     // that inversion is the per-family record that the migration landed.
+    // #340/#341 GATE A: `tui` has migrated, so its arm is gone from here too.
+    // `tui::is_known_handle` survives for the ledger's own question ("does any
+    // small id still reach a funnel?") but is no longer consulted on this
+    // path: a tui handle is a heap object, and asking three registries whether
+    // an arbitrary heap address is one of their ids took three mutexes to
+    // answer "no".
     // Each remaining family deletes its arm here as it moves.
-    if crate::tui::is_known_handle(addr as i64) {
-        mark_old(ReceiverReprFamily::Tui);
-    }
     if crate::async_hooks::is_async_hook_handle(addr as i64) {
         mark_old(ReceiverReprFamily::AsyncHook);
     }
@@ -375,9 +378,10 @@ mod tests {
     /// It is a gate only from HERE, because the fixture calls the funnels
     /// directly. A compiled program's `observed_old` proves nothing for this
     /// family — a statically lowered `d.encoding` (codegen's
-    /// `Expr::TextDecoderEncoding`) never reaches an instrumented funnel, so
-    /// the counter read 0 before the migration too. Gate B (the producer-side
-    /// band assertion in `text.rs`'s own tests) covers those reads.
+    /// `Expr::TextDecoderEncoding`) or a `class_filter`-lowered `state.get()`
+    /// never reaches an instrumented funnel, so the counter read 0 before the
+    /// migration too. Gate B (the producer-side band assertion in the
+    /// family's own tests) covers those reads.
     fn assert_fixture_migrated(family: ReceiverReprFamily, construct: impl FnOnce() -> usize) {
         receiver_repr_test_reset();
         receiver_repr_test_arm(true);
@@ -436,12 +440,12 @@ mod tests {
         assert_fixture_migrated(ReceiverReprFamily::Text, || {
             crate::text::js_text_encoder_new() as usize
         });
-        assert_fixture(ReceiverReprFamily::Tui, || {
-            let mut handle = crate::tui::state::js_perry_tui_state_alloc(0.0);
-            if handle == 0 {
-                handle = crate::tui::state::js_perry_tui_state_alloc(0.0);
-            }
-            (handle as usize, false)
+        // #340/#341: `tui` is migrated — gate A, inverted (see `text`).
+        // Note what the pre-migration fixture had to do: retry when the handle
+        // came back 0, because the FIRST `state(0)` of a program was slot 0
+        // and `POINTER_TAG | 0` is a tagged null. It cannot be 0 now.
+        assert_fixture_migrated(ReceiverReprFamily::Tui, || {
+            crate::tui::state::js_perry_tui_state_alloc(0.0) as usize
         });
         assert_fixture(ReceiverReprFamily::AsyncHook, || {
             let options = crate::object::js_object_alloc(0, 0);

crates/perry-runtime/src/lib.rs

@@ -281,6 +281,9 @@ pub mod tty;
 /// always available; no separate cargo dep, no async-runtime, no
 /// per-program link flag.
 pub mod tui;
+// #340/#341: the class ids of every runtime class whose instances are
+// ordinary objects. Declared before the families that alias it.
+pub(crate) mod native_class_ids;
 /// HarmonyOS perry/ui FFI no-op stubs (#395). Auto-generated by
 /// build.rs from perry-dispatch tables. Compiled only when `ohos-napi`
 /// is on so the platform UI crates' definitions own the symbols on

crates/perry-runtime/src/native_class_ids.rs

@@ -0,0 +1,162 @@
+//! The class ids of runtime classes whose instances are ORDINARY objects
+//! (#340/#341) — one place that says which id belongs to which family.
+//!
+//! Honest tags gives every native-backed value a `GC_TYPE_OBJECT` carrying a
+//! family class id, and those ids were being minted family by family as bare
+//! constants in the family's own module. There is no central allocator for
+//! class ids in the tree, per-module class-id collisions are a known open
+//! problem (#10824: a class id must also never alias a live `ShapeId`), and
+//! the worker-transfer guard had grown into a range spelled
+//! `TEXT_ENCODER_CLASS_ID..=IMMEDIATE_CLASS_ID` **inside `text.rs`** — a check
+//! about every family, living in one family's file, widened by hand each time
+//! a family landed.
+//!
+//! This module owns the `0xFFFF_24xx` web-builtin block instead. A family
+//! declares its own alias from here (so its call sites are unchanged), the
+//! range is closed by construction, and the const assertions below fail the
+//! build rather than a test if two families ever name one id or if an id
+//! wanders into the `ShapeId` window.
+//!
+//! **Allocating an id: take the next value, add it to `ALL` and to the
+//! `is_native_backed_class_id` range if the family owns native state.** Do not
+//! reuse a retired id: a stale compiled artifact naming it would brand the
+//! wrong family.
+
+/// Web-builtin block start. `ShapeId`s live in `[0x8000_0000, 0xC000_0000)`
+/// (`object/shapes.rs`), so this block is far above them; the assertion at the
+/// bottom of the file pins that rather than trusting the comment (#10824).
+pub(crate) const WEB_BUILTIN_BLOCK_START: u32 = 0xFFFF_2401;
+
+// --- Pre-existing, declared elsewhere and aliased here so the block is one
+// --- list. These six are ordinary objects already, but their state is own
+// --- fields rather than prototype accessors (#10823-shaped), so they are not
+// --- yet `is_native_backed_class_id`.
+pub(crate) const ABORT_CONTROLLER: u32 = 0xFFFF_2401;
+pub(crate) const ABORT_SIGNAL: u32 = 0xFFFF_2402;
+pub(crate) const EVENT: u32 = 0xFFFF_2403;
+pub(crate) const CUSTOM_EVENT: u32 = 0xFFFF_2404;
+pub(crate) const DOM_EXCEPTION: u32 = 0xFFFF_2405;
+pub(crate) const EVENT_TARGET: u32 = 0xFFFF_2406;
+
+// --- Migrated families. Each carries native state in `ObjectMeta.native_state`
+// --- and is therefore refused by the worker-transfer guard.
+pub(crate) const TEXT_ENCODER: u32 = 0xFFFF_2407;
+pub(crate) const TEXT_DECODER: u32 = 0xFFFF_2408;
+pub(crate) const TIMEOUT: u32 = 0xFFFF_2409;
+pub(crate) const IMMEDIATE: u32 = 0xFFFF_240A;
+pub(crate) const TUI_WIDGET: u32 = 0xFFFF_240B;
+pub(crate) const TUI_STATE: u32 = 0xFFFF_240C;
+pub(crate) const TUI_REF_BOX: u32 = 0xFFFF_240D;
+pub(crate) const TUI_APP: u32 = 0xFFFF_240E;
+pub(crate) const TUI_STDOUT: u32 = 0xFFFF_240F;
+pub(crate) const TUI_FOCUS_MANAGER: u32 = 0xFFFF_2410;
+
+/// The first id in the native-state range and the last one, inclusive. Every
+/// family between them carries a `native_state` word the far side of a
+/// `postMessage` could not reconstruct.
+const NATIVE_BACKED_FIRST: u32 = TEXT_ENCODER;
+const NATIVE_BACKED_LAST: u32 = TUI_FOCUS_MANAGER;
+
+/// Class ids whose instances are ordinary objects carrying native state that
+/// cannot cross a thread boundary (#340/#341).
+///
+/// A contiguous range, so a family joins it by taking the next id rather than
+/// by editing the transfer path. `thread.rs` calls this in its
+/// `GC_TYPE_OBJECT` arm: an ordinary object no longer hits the "kinds 13-16
+/// are native handles" rejection, so without this a `postMessage`d handle
+/// would arrive as a plain `{}` with no native state instead of the named
+/// `TypeError` #6185 made these surface.
+pub(crate) fn is_native_backed_class_id(class_id: u32) -> bool {
+    (NATIVE_BACKED_FIRST..=NATIVE_BACKED_LAST).contains(&class_id)
+}
+
+/// Every id this module hands out, newest last. Used by the assertions below
+/// and by the uniqueness test.
+const ALL: &[u32] = &[
+    ABORT_CONTROLLER,
+    ABORT_SIGNAL,
+    EVENT,
+    CUSTOM_EVENT,
+    DOM_EXCEPTION,
+    EVENT_TARGET,
+    TEXT_ENCODER,
+    TEXT_DECODER,
+    TIMEOUT,
+    IMMEDIATE,
+    TUI_WIDGET,
+    TUI_STATE,
+    TUI_REF_BOX,
+    TUI_APP,
+    TUI_STDOUT,
+    TUI_FOCUS_MANAGER,
+];
+
+/// Strictly ascending ⟹ no two families share an id, and the block stays
+/// dense so `is_native_backed_class_id` can remain one range compare. A
+/// `const fn` loop rather than a test: a duplicated id must not be able to
+/// reach a build at all, and a `debug_assert` would enforce nothing in release
+/// (#10824 was a SHIPPED aliasing bug).
+const fn strictly_ascending(ids: &[u32]) -> bool {
+    let mut i = 1;
+    while i < ids.len() {
+        if ids[i - 1] >= ids[i] {
+            return false;
+        }
+        i += 1;
+    }
+    true
+}
+
+const _: () = assert!(strictly_ascending(ALL), "two families claim one class id");
+const _: () = assert!(ALL[0] == WEB_BUILTIN_BLOCK_START);
+// A class id must never alias a live ShapeId: the shape store mints into
+// `[0x8000_0000, 0xC000_0000)` and a collision would make a shape compare
+// answer for a family brand.
+const _: () = assert!(NATIVE_BACKED_FIRST >= 0xC000_0000);
+const _: () = assert!(NATIVE_BACKED_LAST == ALL[ALL.len() - 1]);
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Every family that owns a `native_state` word is inside the transfer
+    /// guard's range, and the classes that do NOT own one are outside it. The
+    /// second half is what a new family gets wrong: taking the next id makes
+    /// it non-transferable automatically, which is right, but an id added
+    /// BELOW the range would silently ship a family that deep-copies into a
+    /// worker as an empty object.
+    #[test]
+    fn the_transfer_guard_covers_exactly_the_migrated_families() {
+        for id in [
+            TEXT_ENCODER,
+            TEXT_DECODER,
+            TIMEOUT,
+            IMMEDIATE,
+            TUI_WIDGET,
+            TUI_STATE,
+            TUI_REF_BOX,
+            TUI_APP,
+            TUI_STDOUT,
+            TUI_FOCUS_MANAGER,
+        ] {
+            assert!(
+                is_native_backed_class_id(id),
+                "{id:#x} carries native state but crosses a thread boundary"
+            );
+        }
+        for id in [
+            ABORT_CONTROLLER,
+            ABORT_SIGNAL,
+            EVENT,
+            CUSTOM_EVENT,
+            DOM_EXCEPTION,
+            EVENT_TARGET,
+            0,
+            1,
+            0x8000_0000,
+        ] {
+            assert!(!is_native_backed_class_id(id), "{id:#x} is not migrated");
+        }
+    }
+
+}

crates/perry-runtime/src/object/mod.rs

@@ -1339,6 +1339,12 @@ pub fn scan_object_cache_roots_mut(visitor: &mut crate::gc::RuntimeRootVisitor<'
     // and be rewritten when they move — the same contract as the iterator
     // tower above.
     crate::timer::scan_timer_prototype_roots_mut(visitor);
+    // #340/#341: the five `perry/tui` prototypes and the three singleton
+    // handles (`useApp` / `useStdout` / `useFocusManager`). The singletons are
+    // a resource -> object mapping, not just a prototype: `useApp()` must be
+    // the SAME object on every call, so the object lives here rather than
+    // being re-minted.
+    crate::tui::handle_object::scan_tui_handle_roots_mut(visitor);
     #[cfg(feature = "regex-engine")]
     regex_proto_thunks::scan_canonical_test_site_roots_mut(visitor);
 }

crates/perry-runtime/src/text.rs

@@ -85,8 +85,8 @@ struct DecoderState {
 
 /// Class ids in the web-builtin block (`0xFFFF_24xx`); `0x2401..=0x2406` are
 /// AbortController/AbortSignal/Event/CustomEvent/DOMException/EventTarget.
-pub(crate) const TEXT_ENCODER_CLASS_ID: u32 = 0xFFFF_2407;
-pub(crate) const TEXT_DECODER_CLASS_ID: u32 = 0xFFFF_2408;
+pub(crate) const TEXT_ENCODER_CLASS_ID: u32 = crate::native_class_ids::TEXT_ENCODER;
+pub(crate) const TEXT_DECODER_CLASS_ID: u32 = crate::native_class_ids::TEXT_DECODER;
 
 const STATE_PRESENT: u64 = 1;
 const STATE_FATAL: u64 = 1 << 1;
@@ -790,14 +790,6 @@ static KEEP_TEXT_DECODER_IGNORE_BOM: extern "C" fn(f64) -> f64 = js_text_decoder
 // does, instead of silently decoding as utf-8.
 // ---------------------------------------------------------------------------
 
-/// Class ids whose instances are ordinary objects carrying native state that
-/// cannot cross a thread boundary (#340/#341). A contiguous range so the
-/// remaining handle families join it without touching the transfer path again
-/// — `timer.rs` adds `Timeout`/`Immediate` at `0x2409/A` by extending the end.
-pub(crate) fn is_native_backed_class_id(class_id: u32) -> bool {
-    (TEXT_ENCODER_CLASS_ID..=crate::timer::IMMEDIATE_CLASS_ID).contains(&class_id)
-}
-
 #[cfg(feature = "global-text")]
 fn require_text_brand(value: f64, class_id: u32, message: &[u8]) {
     if text_native_state(value, class_id).is_none() {

crates/perry-runtime/src/thread.rs

@@ -446,14 +446,17 @@ pub unsafe fn serialize_nanbox_for_thread(bits: u64) -> SerializedValue {
                 if fs_thread_codec().is_some_and(|codec| (codec.is_filehandle)(value)) {
                     return SerializedValue::DetachedFileHandle;
                 }
-                // #340/#341: a native-backed builtin (TextEncoder/TextDecoder
-                // today) is an ORDINARY object now, so the GC kind no longer
-                // rejects it the way kinds 13-16 do below. Refuse it by class
-                // id instead — deep-copying one would hand the other thread a
-                // plain `{}` with no native state, which is exactly the silent
-                // shape #6185 made these surface a named TypeError for.
+                // #340/#341: a native-backed builtin (TextEncoder/TextDecoder,
+                // Timeout/Immediate, the six `perry/tui` handle kinds) is an
+                // ORDINARY object now, so the GC kind no longer rejects it the
+                // way kinds 13-16 do below. Refuse it by class id instead —
+                // deep-copying one would hand the other thread a plain `{}`
+                // with no native state, which is exactly the silent shape
+                // #6185 made these surface a named TypeError for. The id range
+                // is owned by `native_class_ids`, so a family joins this guard
+                // by taking the next id rather than by editing this file.
                 let class_id = (*(raw_ptr as *const crate::object::ObjectHeader)).class_id;
-                if crate::text::is_native_backed_class_id(class_id) {
+                if crate::native_class_ids::is_native_backed_class_id(class_id) {
                     return SerializedValue::Unsupported("native handle");
                 }
                 return serialize_object(raw_ptr as *const crate::object::ObjectHeader);

crates/perry-runtime/src/timer.rs

@@ -409,7 +409,7 @@ use ownership::{has_refed_callback_timer, has_refed_interval_timer, has_refed_pr
 pub(crate) use ownership::{purge_agent_timers, timer_phase_work_pending};
 
 pub(crate) use gc_scan::{new_timer_root_scan_state, scan_timer_roots_mut_step};
-pub(crate) use handle_object::{scan_timer_prototype_roots_mut, IMMEDIATE_CLASS_ID};
+pub(crate) use handle_object::scan_timer_prototype_roots_mut;
 // `crate::timer::`-qualified only from unit tests (`timer/tests_inline.rs`,
 // `gc/tests/handle_bound_method_name.rs`, `timer/ref_states.rs`'s test module);
 // an unconditional `pub(crate) use` would be an unused import in a lib build

crates/perry-runtime/src/timer/handle_object.rs

@@ -39,8 +39,8 @@ use super::*;
 /// Class ids in the web-builtin block. `0x2401..=0x2406` are
 /// AbortController/AbortSignal/Event/CustomEvent/DOMException/EventTarget and
 /// `0x2407/8` are TextEncoder/TextDecoder.
-pub(crate) const TIMEOUT_CLASS_ID: u32 = 0xFFFF_2409;
-pub(crate) const IMMEDIATE_CLASS_ID: u32 = 0xFFFF_240A;
+pub(crate) const TIMEOUT_CLASS_ID: u32 = crate::native_class_ids::TIMEOUT;
+pub(crate) const IMMEDIATE_CLASS_ID: u32 = crate::native_class_ids::IMMEDIATE;
 
 const TIMER_STATE_PRESENT: u64 = 1;
 const TIMER_STATE_IMMEDIATE: u64 = 1 << 1;

crates/perry-runtime/src/timer/tests_inline.rs

@@ -443,7 +443,7 @@ mod honest_tag_tests {
             ),
             (
                 js_set_immediate_callback(0),
-                crate::timer::IMMEDIATE_CLASS_ID,
+                crate::native_class_ids::IMMEDIATE,
                 true,
             ),
         ] {