@symbiote-native/vue 0.3.8 → 0.4.0

package/build/modules/animated/create-animated-component.js

@@ -1,25 +1,18 @@
-// createAnimatedComponent: the Vue twin of the React wrapper. It wraps a base component
-// (View / Text / Image / ScrollView / any) so it accepts AnimatedNodes in its props.
-// Same JS-driven path, NO native driver in the hot loop: a frame is the scoped commit
-// setNativeProps drives from the AnimatedProps leaf. The framework-agnostic
-// pieces (reduceProps / readPassthroughStyle / resolveHostNode / isAnimatedNode + the
-// AnimatedProps leaf itself) live in @symbiote-native/engine, shared verbatim with React; here
-// Vue supplies only the lifecycle.
-//
-// React → hooks: useMemo(leaf) + three useEffects + a callback ref. Vue → reactivity:
-// a render that rebuilds the leaf each pass (like React's per-render useMemo(rest)) + a
-// post-commit reconcile (onMounted/onUpdated, the Vue twin of a post-commit useEffect) +
-// a function ref. The per-frame path is unchanged and NEVER goes through Vue render:
-// value.setValue / animation -> flushValue -> AnimatedProps.update() -> setNativeProps(node).
+// createAnimatedComponent: the Vue twin of the React wrapper. Wraps a base component
+// (View/Text/Image/ScrollView/any) so it accepts AnimatedNodes in its props. Framework-agnostic
+// pieces (reduceProps/readPassthroughStyle/resolveHostNode/isAnimatedNode + the AnimatedProps
+// leaf) live in @symbiote-native/engine, shared verbatim with React; Vue supplies only the
+// lifecycle: a render that rebuilds the leaf each pass + a post-commit reconcile (onMounted/
+// onUpdated) + a function ref. The per-frame path is unchanged and NEVER goes through Vue
+// render: value.setValue / animation -> flushValue -> AnimatedProps.update() -> setNativeProps(node).
 import { defineComponent, h, onBeforeUnmount, onMounted, onUpdated, shallowRef, } from '@vue/runtime-core';
-import { AnimatedProps, attachNativeEventHandler, isNativeAnimatedAvailable, reduceProps, readPassthroughStyle, resolveHostNode, } from '@symbiote-native/engine';
+import { createAnimatedLeafLifecycle, isNativeAnimatedAvailable, isSymbioteNode, reduceProps, readPassthroughStyle, resolveHostNode, } from '@symbiote-native/engine';
 import { normalizeVueAttrs } from '../../utils/normalize-attrs.js';
 // RN's prop carrying explicit (already-rasterized) values that override the animated prop in
 // the COMMITTED props (sticky-header passthrough). Named once here so render/reconcile agree.
 const PASSTHROUGH_PROP = 'passthroughAnimatedPropExplicitValues';
-// A base component is either a functional component (View / Text / Image, a function) or a
-// stateful defineComponent (ScrollView, an object). Read its display name without a cast for
-// the wrapper's devtools name.
+// Reads either a functional component's or a stateful defineComponent's display name, without a
+// cast, for the wrapper's devtools name.
 function baseName(component) {
     if (component === null || (typeof component !== 'function' && typeof component !== 'object')) {
         return 'Anonymous';
@@ -37,86 +30,35 @@ export function createAnimatedComponent(Component) {
         name: `Animated(${baseName(Component)})`,
         inheritAttrs: false,
         setup(_props, { attrs: rawAttrs, slots, expose }) {
-            // The committed host node, held by IDENTITY in a shallowRef (the reactivity rule: a deep
-            // ref() would run it through toReactive() and hand back a Proxy, so AnimatedProps.setNativeView
-            // / attachNativeEventHandler would miss the engine's WeakMap mirror, keyed on the raw node).
-            // Same rule as Switch / ScrollView host nodes.
+            // shallowRef, not ref: a deep ref() would run it through toReactive() and hand back a
+            // Proxy, missing the engine's WeakMap mirror. Same rule as Switch / ScrollView host nodes.
             const nodeRef = shallowRef(null);
-            // The base component's public instance (a ScrollView handle, or the host node for View).
-            // Forwarded to a parent ref via expose(). shallowRef: it may itself BE an engine node.
+            // The base component's public instance (a ScrollView handle, or the host node for View),
+            // forwarded to a parent ref via expose(). shallowRef: it may itself BE an engine node.
             const instanceRef = shallowRef(null);
-            // The AnimatedProps leaf the next reconcile should wire in, rebuilt by render each pass
-            // (like React's per-render useMemo(rest)). Plain (non-reactive) so writing it in render
-            // triggers no reactive effect. `attached` is the leaf currently in the value graph.
-            let pendingLeaf = null;
-            let attached = null;
-            // The current non-passthrough props, kept so the post-commit event-attach can re-scan them.
+            // The leaf lifecycle - build/swap/bind/detach, and the rebuild-vs-skip decision - is the
+            // engine's, shared by every adapter (core/engine/src/animated/leaf-lifecycle.ts). Vue owns
+            // only WHEN to run it: after mount and after every re-render, which is when `currentRest`
+            // has just been refreshed by the render function below.
+            const lifecycle = createAnimatedLeafLifecycle('vue');
+            // The props the next reconcile should wire in, refreshed by render each pass.
             let currentRest = {};
             let wantsNative = false;
-            // Detachers for any Animated.event prop bound natively to the committed node (JS path: none).
-            let eventDetachers = [];
-            function detachEvents() {
-                for (const detach of eventDetachers)
-                    detach();
-                eventDetachers = [];
-            }
-            // Native-attach any Animated.event prop (e.g. onScroll={Animated.event(…,{useNativeDriver:true})})
-            // to the committed node. attachNativeEventHandler no-ops (returns undefined) unless the prop is a
-            // native event handler with a committed tag, so the JS path stays the fallback. Rebound on every
-            // reconcile so a new inline event re-attaches; detached first to avoid leaking the prior binding.
-            function attachEvents() {
-                detachEvents();
-                const node = nodeRef.value;
-                if (node === null)
-                    return;
-                for (const key of Object.keys(currentRest)) {
-                    const attachment = attachNativeEventHandler(node, key, currentRest[key]);
-                    if (attachment !== undefined)
-                        eventDetachers.push(attachment.detach);
-                }
-            }
-            // Post-commit reconcile (onMounted first paint, onUpdated every re-render, the Vue twin of a
-            // post-commit useEffect). Attach the NEW leaf BEFORE detaching the OLD one: order is load-bearing.
-            // A shared Value self-detaches (and drops its native node) the instant its child count hits
-            // zero, so detaching first would kill a running native animation on any unrelated re-render
-            // (mirrors RN's AnimatedComponent._attachProps). Then bind the captured node, go native if wanted,
-            // and rebind native events.
             function reconcile() {
-                const newLeaf = pendingLeaf;
-                if (newLeaf === null)
-                    return;
-                newLeaf.__attach();
-                if (attached !== null && attached !== newLeaf)
-                    attached.__detach();
-                attached = newLeaf;
-                const node = nodeRef.value;
-                if (node !== null)
-                    newLeaf.setNativeView(node);
-                if (wantsNative)
-                    newLeaf.__makeNative();
-                attachEvents();
+                lifecycle.reconcile(currentRest, isSymbioteNode(nodeRef.value) ? nodeRef.value : null, wantsNative);
             }
             onMounted(reconcile);
             onUpdated(reconcile);
-            // Final teardown: detach the last-attached leaf and any native events on unmount.
-            onBeforeUnmount(() => {
-                detachEvents();
-                if (attached !== null) {
-                    attached.__detach();
-                    attached = null;
-                }
-            });
-            // Function ref (held stably, so Vue doesn't re-invoke it per patch). On mount the base hands
-            // back its public instance; resolve it to the underlying host node (unwrapping a scroll-container
-            // handle via getScrollNode), record THAT for the leaf binding / event attach, and keep the
-            // ORIGINAL instance for ref forwarding. Vue calls it with null on unmount, node clears.
+            onBeforeUnmount(() => lifecycle.teardown());
+            // On mount the base hands back its public instance; resolve it to the underlying host node
+            // (unwrapping a scroll-container handle via getScrollNode) for the leaf binding / event
+            // attach, and keep the ORIGINAL instance for ref forwarding.
             const captureRef = (instance) => {
                 instanceRef.value = instance;
                 nodeRef.value = resolveHostNode(instance);
             };
-            // Forward the caller's ref to the base instance: a parent ref on Animated.ScrollView still gets
-            // scrollTo (the exposed handle), on Animated.View the host node. A delegating proxy because the
-            // instance is captured async (after mount), so a snapshot exposed at setup time would be null.
+            // A delegating proxy because the instance is captured async (after mount), so a snapshot
+            // exposed at setup time would be null.
             expose(new Proxy(Object.create(null), {
                 get: (_target, key) => {
                     const instance = instanceRef.value;
@@ -130,11 +72,9 @@ export function createAnimatedComponent(Component) {
                 },
             }));
             return () => {
-                // Fold kebab template props to camelCase before splitting (idempotent: the base component
-                // normalizes too, but keep `rest`/reduceProps on the RN contract here as well).
                 const attrs = normalizeVueAttrs(rawAttrs);
-                // Split the incoming attrs into the passthrough (consumed) and the rest (forwarded). The
-                // passthrough never reaches the base as a prop; it only overrides the committed style below.
+                // Split into the passthrough (consumed) and the rest (forwarded). The passthrough never
+                // reaches the base as a prop; it only overrides the committed style below.
                 const rest = {};
                 let passthrough;
                 for (const key of Object.keys(attrs)) {
@@ -146,16 +86,13 @@ export function createAnimatedComponent(Component) {
                 }
                 currentRest = rest;
                 // Native driving is opt-in per the passthrough prop AND requires a real native module;
-                // headless / unsupported hosts keep the JS flush path (and the JS smokes green).
+                // headless/unsupported hosts keep the JS flush path.
                 wantsNative = passthrough != null && isNativeAnimatedAvailable();
-                // One AnimatedProps leaf per render pass (rebuilt like React's useMemo(rest)); the post-commit
-                // reconcile wires it into the graph and swaps the previous one out.
-                pendingLeaf = new AnimatedProps(rest);
-                // Reduced props are concrete (animated nodes replaced by their current values) so the first
-                // paint carries real values, exactly like React's first render.
+                // Reduced props are concrete (animated nodes replaced by their current values) so the
+                // first paint carries real values.
                 const reduced = reduceProps(rest);
-                // Override the committed style with the explicit passthrough values (last wins via the style
-                // array, which the commit layer flattens) so the ShadowTree carries the current transform.
+                // Override the committed style with the explicit passthrough values (last wins via the
+                // style array) so the ShadowTree carries the current transform.
                 const passthroughStyle = readPassthroughStyle(passthrough);
                 if (passthroughStyle !== undefined) {
                     reduced.style =

package/build/modules/animated/index.js

@@ -1,8 +1,8 @@
-// The Animated namespace for @symbiote-native/vue: the Vue twin of adapters/react/src/animated/index.ts.
-// createAnimatedComponent applied to the Vue primitives gives Animated.View / Text / Image; the
-// value graph, easing and imperative drivers come from @symbiote-native/engine (framework-agnostic,
-// JS-driven), spread in verbatim. Both halves meet here so the familiar surface,
-// `Animated.timing(new Animated.Value(0), …).start()`, works against the Vue-driven engine.
+// The Animated namespace for @symbiote-native/vue. createAnimatedComponent applied to the Vue
+// primitives gives Animated.View/Text/Image; the value graph, easing and imperative drivers come
+// from @symbiote-native/engine (framework-agnostic, JS-driven), spread in verbatim. Both halves
+// meet here so `Animated.timing(new Animated.Value(0), ...).start()` works against the
+// Vue-driven engine.
 import { AnimatedValue, AnimatedValueXY, AnimatedColor, AnimatedMock, Easing, Platform, timing, spring, decay, parallel, sequence, stagger, loop, delay, add, subtract, multiply, divide, modulo, diffClamp, event, forkEvent, unforkEvent, } from '@symbiote-native/engine';
 import { View, Text } from '../../components.js';
 import { Image } from '../../components/image.js';
@@ -14,15 +14,12 @@ export { createAnimatedComponent } from './create-animated-component.js';
 const AnimatedView = createAnimatedComponent(View);
 const AnimatedText = createAnimatedComponent(Text);
 const AnimatedImage = createAnimatedComponent(Image);
-// ScrollView is wrapped behind a LAZY, memoized getter, mirroring RN's `get ScrollView()` and the
-// React adapter: ScrollView's module chain imports this Animated namespace back (sticky headers,
-// Phase 3), so a static createAnimatedComponent(ScrollView) at init could read ScrollView inside
-// its own TDZ. A memoized getter defers the wrap past module init, so the cycle never fires.
+// LAZY, memoized getter, mirroring RN's `get ScrollView()`: ScrollView's module chain imports
+// this Animated namespace back (sticky headers), so a static createAnimatedComponent(ScrollView)
+// at init could read ScrollView inside its own TDZ. Deferring the wrap past module init avoids the cycle.
 let animatedScrollView;
-// FlatList / SectionList: DEFERRED. The Vue adapter has no FlatList/SectionList base component yet
-// (the React adapter does), so there is nothing to wrap; Animated.FlatList / Animated.SectionList
-// are intentionally OMITTED, not faked. They land once those base components exist (you cannot wrap
-// a component that does not exist). This is a named gap, not a silent drop.
+// Animated.FlatList / Animated.SectionList are intentionally OMITTED, not faked - a named gap,
+// not a silent drop.
 // The live, JS-driven driver namespace (real frames). RN's AnimatedImplementation.
 const liveDrivers = {
     Value: AnimatedValue,
@@ -48,10 +45,9 @@ const liveDrivers = {
     unforkEvent,
 };
 // RN swaps the WHOLE driver namespace for the mock when the host reports isDisableAnimations
-// (reduced motion / test env): the mock keeps the same surface but jumps each animation to its
-// final value synchronously, no frames. The animated COMPONENTS (View/Text/Image + the lazy
-// ScrollView getter) are live in both branches; only the drivers/value/operators/events half is
-// swapped, exactly like RN spreading `...Animated` (impl or mock) over the same component getters.
+// (reduced motion/test env): the mock keeps the same surface but jumps each animation to its
+// final value synchronously, no frames. The animated COMPONENTS stay live in both branches; only
+// the drivers/value/operators/events half is swapped.
 const drivers = Platform.isDisableAnimations ? AnimatedMock : liveDrivers;
 export const Animated = {
     View: AnimatedView,

package/build/modules/app-registry/index.js

@@ -2,11 +2,9 @@
 //   AppRegistry.registerComponent(appKey, () => App)
 // The registry bookkeeping (sections, host-registrar bridge, headless tasks) is
 // framework-agnostic and lives in @symbiote-native/engine's createAppRegistry; this file supplies
-// only the one Vue-specific seam — building a runnable from a component provider via a
-// synthetic functional root (h() has no createElement-style prop/children spread of its
-// own targets, so the wrap step is a render function rather than an object merge) — so
-// examples/vue-sfc's own registerRunnable + mount call can move onto the same entry point
-// React already has.
+// only the one Vue-specific seam - building a runnable from a component provider via a synthetic
+// functional root (h() has no createElement-style prop/children spread of its own targets, so
+// the wrap step is a render function rather than an object merge).
 import { h } from '@vue/runtime-core';
 import { createAppRegistry, dlog, } from '@symbiote-native/engine';
 import { mount } from '../../render.js';
@@ -15,12 +13,10 @@ function runnableFor(componentProvider, getWrapperComponentProvider) {
         dlog(`AppRegistry: mounting on rootTag ${String(appParameters.rootTag)}`);
         const rootComponent = componentProvider();
         const renderRoot = () => h(rootComponent, appParameters.initialProps);
-        // Wrap the root when a provider is set, mirroring RN's `registerComponent` passing
-        // `wrapperComponentProvider && wrapperComponentProvider(...)` into renderApplication
-        // (AppRegistryImpl.js:80) — Vue's equivalent of React's createElement(Wrapper, null,
-        // element) is a default-slot render, since Vue has no standalone element value to nest.
-        // Read live (not at registration time) so setWrapperComponentProvider affects every
-        // runnable's next run, not just future ones.
+        // Wrap the root when a provider is set, mirroring RN's `registerComponent`. Vue's equivalent
+        // of React's createElement(Wrapper, null, element) is a default-slot render, since Vue has
+        // no standalone element value to nest. Read live so setWrapperComponentProvider affects
+        // every runnable's next run, not just future ones.
         const wrapperComponentProvider = getWrapperComponentProvider();
         const mounted = wrapperComponentProvider === undefined
             ? renderRoot

package/build/modules/status-bar.js

@@ -1,14 +1,11 @@
 // StatusBar, the Vue lifecycle half. The native StatusBarManager driving (applyStatusBarProps),
-// the imperative statics (statusBarImperative), and the Android bar-height constant all live in
-// @symbiote-native/engine, shared verbatim with React; Metro selects the engine's status-bar.ios.ts /
-// status-bar.android.ts per host, so the platform divergence never reaches this file. Vue supplies
-// only the declarative shape: a component that renders NOTHING and re-applies the props through a
-// watchEffect on mount + every prop change, with the imperative statics attached to the component
-// object (RN's StatusBar: the value doubles as the imperative namespace, like the Vue Image).
+// the imperative statics, and the Android bar-height constant all live in @symbiote-native/engine,
+// shared verbatim with React; Metro selects the engine's status-bar.ios.ts/.android.ts per host,
+// so platform divergence never reaches this file. Vue supplies only the declarative shape: a
+// component that renders NOTHING and re-applies the props through a watchEffect on mount + every
+// prop change, with the imperative statics attached to the component object.
 //
-// Renders null (no Fabric view), so it follows neither the descriptor split nor a host-node ref:
-// the "else keep its current shape" path of the StatusBar component. Inputs arrive as attrs
-// (untyped) and run through normalizeVueAttrs (kebab→camel) before each is narrowed by a guard.
+// Inputs arrive as attrs (untyped) and run through normalizeVueAttrs before each is narrowed by a guard.
 import { defineComponent, watchEffect } from '@vue/runtime-core';
 import { applyStatusBarProps, statusBarImperative, statusBarCurrentHeight, isOpaqueColorValue, } from '@symbiote-native/engine';
 import { normalizeVueAttrs } from '../utils/normalize-attrs.js';
@@ -20,8 +17,6 @@ function asBarStyle(value) {
         ? value
         : undefined;
 }
-// backgroundColor is a string / int / opaque PlatformColor; any other shape is dropped. A runtime
-// guard at the untyped-attrs boundary, not a cast.
 function asColorValue(value) {
     if (typeof value === 'string')
         return value;
@@ -43,13 +38,11 @@ const StatusBarComponent = defineComponent({
     name: 'StatusBar',
     inheritAttrs: false,
     setup(_props, { attrs: rawAttrs }) {
-        // watchEffect tracks rawAttrs (reactive), so reading it here re-applies on every prop change:
-        // the Vue twin of React's useEffect over the prop deps. Resolution is lazy inside the engine
-        // (a missing StatusBarManager is a no-op), so this never crashes a render.
+        // watchEffect tracks rawAttrs (reactive), so reading it here re-applies on every prop change.
+        // Resolution is lazy inside the engine (a missing StatusBarManager is a no-op).
         watchEffect(() => {
             applyStatusBarProps(buildProps(normalizeVueAttrs(rawAttrs)));
         });
-        // Renders nothing: StatusBar has no Fabric view, exactly like React's `return null`.
         return () => null;
     },
 });

package/build/renderer/index.js

@@ -51,6 +51,13 @@ export function createSymbioteRenderer(surface) {
         setElementText(el, text) {
             if (isSurface(el))
                 return;
+            // Same invariant insert() enforces, on the other route text can reach a node: Vue calls
+            // this instead of insert() when an element's children collapse to a single string, so
+            // without the check a raw text lands under a non-Text parent - an invalid Fabric tree
+            // built silently, which is worse than the throw insert() would have given.
+            if (!el.isText) {
+                throw new Error(`Text string "${text}" must be rendered inside a <Text>`);
+            }
             // An RCTText carries its string as a single raw-text child. Reuse a lone existing
             // one to avoid churn; otherwise replace all children with a fresh raw-text node.
             const [first] = el.children;
@@ -103,12 +110,10 @@ export function createSymbioteRenderer(surface) {
         patchProp(el, key, _prev, next) {
             if (isSurface(el))
                 return;
-            // routeProp makes the prop-vs-event decision from the node's ViewConfig (onPress on
-            // a View becomes a listener; onTintColor on a Switch stays a prop): identical to
-            // the React host config, so the whole event layer is shared. `class`/`style` merge
-            // (explicit :style always winning over class-derived style, regardless of which of
-            // Vue's two independent patchProp calls lands last) is centralized in routeProp too
-            // (core/engine/src/node.ts) — every adapter gets it, not just this one.
+            // routeProp makes the prop-vs-event decision from the node's ViewConfig (onPress on a
+            // View becomes a listener; onTintColor on a Switch stays a prop), shared with React. The
+            // class/style merge (explicit :style always winning, regardless of which of Vue's two
+            // independent patchProp calls lands last) is centralized there too (core/engine/src/node.ts).
             routeProp(el, key, next);
             surface.requestCommit();
         },

package/build/runtime-helpers/index.js

@@ -1,28 +1,21 @@
 // Metro rewrites every compiled `from 'vue'` import to point HERE instead of at bare
-// `@vue/runtime-core` (see examples/*/metro-vue-transformer.js). Most of the compiler's injected
-// helpers (ref, computed, withDirectives, openBlock, …) already live in runtime-core untouched —
-// re-exported below. But two Vue template directives compile to a runtime-helper import that
-// ONLY exists in `@vue/runtime-dom` (vShow, vModelText, vModelCheckbox, vModelSelect), written
-// directly against a real HTMLElement (el.style.display, el.value, addEventListener). We have no
-// DOM, so those don't exist for us — rewriting straight to runtime-core leaves `v-show` either
-// failing at import time or silently resolving to `undefined` (a no-op directive). This module is
-// the interception point: it supplies our OWN implementation under the same export name, so the
-// compiler's import keeps resolving and the directive actually does something.
+// @vue/runtime-core (see examples/*/metro-vue-transformer.js). Most compiler-injected helpers
+// (ref, computed, withDirectives, openBlock, ...) live in runtime-core untouched, re-exported
+// below. But two Vue template directives compile to a runtime-helper import that ONLY exists in
+// @vue/runtime-dom (vShow, vModelText, vModelCheckbox, vModelSelect), written directly against a
+// real HTMLElement - we have no DOM, so this module supplies our OWN implementation under the
+// same export name instead of leaving `v-show` a silent no-op.
 //
 // Scope: this covers only Vue's own template directives (v-show, Teleport); native-element
 // v-model is a separate, out-of-scope case.
 export * from '@vue/runtime-core';
 import { defineComponent, h, Teleport as VueTeleport, } from '@vue/runtime-core';
 import { isSymbioteNode, setNativeProps, whenCommitted, } from '@symbiote-native/engine';
-// setNativeProps merges a partial `style` object onto the node's current one (never clobbering
-// other declarative style fields) and re-commits via the node's OWN tracked rootTag — no
-// SymbioteSurface reference needed here, which a directive hook has no access to anyway.
-//
 // whenCommitted, not a direct call: Vue's `mounted` hook fires synchronously during the patch
 // pass, but this renderer coalesces the actual Fabric commit onto a microtask
-// (surface.requestCommit()), so the node may have no committed tag yet — the same async-commit
-// race TextInput's autoFocus guards against. A bare setNativeProps
-// here would silently no-op with no retry on the very first mount.
+// (surface.requestCommit()), so the node may have no committed tag yet - the same async-commit
+// race TextInput's autoFocus guards against. A bare setNativeProps here would silently no-op
+// with no retry on the very first mount.
 const pendingShowCommits = new WeakMap();
 function applyShow(el, value) {
     pendingShowCommits.get(el)?.();
@@ -36,16 +29,13 @@ export const vShow = {
     unmounted: el => pendingShowCommits.get(el)?.(),
 };
 // Teleport's `to` in the DOM world is usually a CSS-selector string ('body', '#modal-root'); we
-// have no querySelector (renderer.ts stubs it to null, same as insertStaticContent), so `to` here
-// must be an already-mounted host node — e.g. a ref to a persistent "overlay host" View rendered
-// once near the app root — not a selector string. This wrapper shadows runtime-core's own
-// `Teleport` (which the SFC compiler imports from 'vue' like vShow) purely to validate `to` BEFORE
-// handing it to the real Teleport: a wrong value (string, plain object, an unrendered/reactive-
-// wrapped node) throws immediately here instead of silently corrupting the retained tree deep
-// inside insert/remove — the "don't let a dev accidentally break everything" case this exists for.
-// Scope: same-surface targets only (see the React createPortal twin, create-portal.ts) — Vue's own
-// Teleport internals (disabled toggling, move-on-update) work unmodified once `to` resolves to a
-// real ISymbioteNode, since insert/remove/parentNode/nextSibling are already fully generic.
+// have no querySelector, so `to` here must be an already-mounted host node - e.g. a ref to a
+// persistent "overlay host" View rendered once near the app root. This wrapper shadows
+// runtime-core's own Teleport purely to validate `to` BEFORE handing it to the real Teleport: a
+// wrong value throws immediately here instead of silently corrupting the retained tree deep
+// inside insert/remove. Scope: same-surface targets only (see the React createPortal twin,
+// create-portal.ts) - Vue's own Teleport internals work unmodified once `to` resolves to a real
+// ISymbioteNode.
 export const Teleport = defineComponent({
     name: 'Teleport',
     inheritAttrs: false,

package/metro-css-parser.cjs

@@ -1,17 +1,12 @@
 // Re-exports @symbiote-native/css-parser verbatim from INSIDE this package, so a consuming app's own
 // require('@symbiote-native/vue/metro-css-parser') resolves css-parser relative to THIS file's
-// location (adapters/vue/node_modules, where css-parser IS a real dependency — see
-// package.json), not relative to the app's own node_modules, which does not and should not
-// need to declare @symbiote-native/css-parser itself. Node resolves each require() relative to the
-// requiring FILE's own location, so this indirection is what actually removes the extra install
-// step, not pnpm hoisting (which does not propagate this transitively across workspace packages
-// the way a flat classic node_modules would). .cjs, not .js: this package is "type": "module",
-// and Metro's babelTransformerPath loading expects a require()-able module. Used as
-// vue-tsx's babelTransformerPath for standalone .css/.module.css file imports —
-// metro-vue-transformer.cjs (the .vue SFC transformer) requires @symbiote-native/css-parser
-// directly instead, since it needs the individual parse/compile functions, not a Metro
-// transformer object.
-// createCssMetroTransformer is a factory, not a ready transformer — Metro's
-// babelTransformerPath needs the actual {transform, getCacheKey} object it returns,
-// not the css-parser package barrel.
+// location (adapters/vue/node_modules, where css-parser IS a real dependency), not relative to
+// the app's own node_modules — Node resolves each require() relative to the requiring FILE, so
+// this indirection is what removes the app's extra install step, not pnpm hoisting. .cjs, not
+// .js: this package is "type": "module", and Metro's babelTransformerPath loading expects a
+// require()-able module. Used as vue-tsx's babelTransformerPath for standalone .css/.module.css
+// imports; metro-vue-transformer.cjs (the .vue SFC transformer) requires @symbiote-native/css-parser
+// directly instead, since it needs the individual parse/compile functions, not a Metro transformer
+// object. createCssMetroTransformer is a factory — babelTransformerPath needs the actual
+// {transform, getCacheKey} object it returns, not the css-parser package barrel.
 module.exports = require('@symbiote-native/css-parser').createCssMetroTransformer();