@symbiote-native/vue 3.0.2 → 3.0.4

package/README.md

@@ -20,20 +20,79 @@ mutation-oriented framework driving the already-validated engine.
 
 ## Install
 
+```bash
+npx @symbiote-native/cli new my-app --framework vue --vue-flavor sfc   # or --vue-flavor tsx
+```
+
+One command, nothing to wire by hand: scaffolds the Metro config (the SFC transformer, or the TSX
+Babel plugin below), the entry seam below, and `@symbiote-native/vue`/`react-native`/`vue` as your
+app's own dependencies.
+
+<details>
+<summary>Manual install (no generator — an existing app, or you want to wire it yourself)</summary>
+
 ```bash
 npm install @symbiote-native/vue react-native vue
 ```
 
 `react-native` and `vue` stay your app's own top-level dependencies — this package only replaces
-the JS renderer that drives them. **TSX** needs nothing beyond the install above; **SFC**
-additionally needs a Metro transformer for `.vue` files (see
-[`examples/vue-sfc`](../../examples/vue-sfc)'s `metro.config.js`) — `npx @symbiote-native/cli new`
-wires this for a new app; an existing app still needs it copied in by hand.
+the JS renderer that drives them. **SFC** additionally needs a Metro transformer for `.vue` files
+— see [`examples/vue-sfc`](../../examples/vue-sfc)'s `metro.config.js`.
+
+**TSX** needs one more Babel plugin beyond the install above, or a dev-mode Vue warning can crash
+the mount to a blank screen. RN's dev React-JSX transform tags every `JSXElement` with `__self`/
+`__source` (inert under React); `@vue/babel-plugin-jsx` copies them verbatim into the vnode's
+props, and at module scope `__self`'s `this` is the Hermes global `HostObject` — the first Vue dev
+warning that formats that prop for a component trace throws reading `Symbol.toStringTag` off it,
+unwinding the whole mount. Strip both attributes on `JSXOpeningElement` exit, after Babel's
+`__self`/`__source` plugins add them but before `@vue/babel-plugin-jsx` reads them (see
+[`examples/vue-tsx`](../../examples/vue-tsx)'s `babel.config.js`, `stripReactJsxDevAttrs`) — SFC
+doesn't need this, since its compiler never sees RN's React-JSX transform at all.
+
+</details>
 
 ---
 
 ## Use it
 
+The app is ordinary Vue. The primitives are TAGS — `<view>`, `<text>`, `<pressable>` — so there is
+nothing to import for them at all; both Vue compilers resolve them as elements and the renderer
+maps each to its Fabric view. Styling is a CSS class (a plain `.css` file in TSX, an SFC's own
+`<style>` block otherwise) — the convention every example app here follows. A tap→increment
+counter, authored in TSX:
+
+```jsx
+import { ref } from '@vue/runtime-core';
+import './App.css';
+
+export default {
+  setup() {
+    const count = ref(0);
+    return () => (
+      <safe-area-view class="screen">
+        <text>Taps: {count.value}</text>
+        <pressable onPress={() => count.value++}>
+          <text>Tap me</text>
+        </pressable>
+      </safe-area-view>
+    );
+  },
+};
+```
+
+```css
+/* App.css */
+.screen {
+  flex: 1;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+}
+```
+
+<details>
+<summary>Native entry point (index.js) — already scaffolded by <code>npx @symbiote-native/cli new --framework vue</code></summary>
+
 The zero-config entry mirrors real Vue's own `createApp(App).mount(...)` idiom and wires the same
 RN-backed host seams React's `registerApp` does — this is what
 [`examples/vue-tsx`](../../examples/vue-tsx) and [`examples/vue-sfc`](../../examples/vue-sfc)
@@ -41,6 +100,11 @@ actually use:
 
 ```js
 // index.js
+
+// Registers host behaviors (Image, Pressable, Switch, ...) that /bootstrap alone doesn't
+// reach; deleting this breaks them silently (Metro's production inlineRequires makes a
+// side-effect-only barrel import go lazy, see register.ts).
+import '@symbiote-native/vue';
 import { createApp } from '@symbiote-native/vue/bootstrap';
 import App from './App';
 import { name as appName } from './app.json';
@@ -66,27 +130,7 @@ RNAppRegistry.registerRunnable(appName, ({ rootTag }) => {
 });
 ```
 
-The app is ordinary Vue. The primitives are TAGS — `<view>`, `<text>`, `<pressable>` — so there is
-nothing to import for them at all; both Vue compilers resolve them as elements and the renderer
-maps each to its Fabric view. A tap→increment counter, authored in TSX:
-
-```jsx
-import { ref } from '@vue/runtime-core';
-
-export default {
-  setup() {
-    const count = ref(0);
-    return () => (
-      <view style={{ padding: 24 }}>
-        <text>Taps: {count.value}</text>
-        <pressable onPress={() => count.value++}>
-          <text>Tap me</text>
-        </pressable>
-      </view>
-    );
-  },
-};
-```
+</details>
 
 ### Two example apps
 
@@ -101,9 +145,9 @@ the demo above is the first one running on the iOS simulator:
 
 ## Parity — and the one gap
 
-Both adapters reach the same primitives, runtime modules, `Animated` on both drivers, gestures,
-accessibility, and the `VirtualizedList` family, verified on-device on iOS and Android. That
-parity is **structural, not hand-copied**: the
+Vue reaches the same primitives, runtime modules, `Animated` on both drivers, gestures,
+accessibility, and the `VirtualizedList` family as React, Svelte, Solid, and Angular, verified
+on-device on iOS and Android. That parity is **structural, not hand-copied**: the
 component logic (state machines + render functions) is written **once** in `@symbiote-native/components`,
 and each adapter supplies only its lifecycle (Vue's `ref`/`watch` + the descriptor→`h()` bridge).
 

package/build/components/virtualized-list/index.js

@@ -492,16 +492,9 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
                     ? INVERTED_X_STYLE
                     : INVERTED_Y_STYLE
                 : undefined;
-            // Wraps one cell identically whether it's the force-mounted sticky cell ahead of the
-            // window or an in-window cell from the loop below — same measuring View, same key shape.
-            // RN renders the separator INSIDE the cell's own measuring wrapper
-            // (VirtualizedListCellRenderer.js:218-221), and that placement is load-bearing rather than
-            // cosmetic. As a SIBLING it is an extra flex child, so the chrome between two cells becomes
-            // gap + separator + gap while a spacer collapsing that region replaces it with one gap —
-            // the leading spacer then lands every cell below it short by (separator + gap), and the
-            // content visibly jumps by that amount each time the window's first index moves. Measured
-            // at exactly 17px on device 2026-08-19 (a 1px divider under a 16px container gap); see
-            // .claude/rules/list-geometry-feedback-loop.md.
+            // The separator lives INSIDE the cell's own measuring wrapper, not as a sibling: a sibling
+            // is an extra flex child, so a leading-spacer collapse would land every cell below it
+            // short by (separator + gap). See .claude/rules/list-geometry-feedback-loop.md.
             const pushCell = (cell) => {
                 const item = p.getItem(p.data, cell.index);
                 const content = p.renderItem?.({
@@ -510,11 +503,9 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
                     separators: makeSeparators(cell.index),
                 });
                 const separator = 
-                // RN gates the separator on the last index of the DATA, not of the WINDOW
-                // (VirtualizedList.js:793 `const end = getItemCount(data) - 1`), and now that the separator
-                // lives INSIDE the measuring wrapper that distinction is load-bearing: gating on the window
-                // would make a cell's own measured height change as the window slides past it. Device-measured
-                // 2026-08-19 as a run of cells all shifting by exactly the divider's 1px.
+                // Gated on the last index of the DATA, not the WINDOW: since the separator lives
+                // inside the measuring wrapper, gating on the window would make a cell's own
+                // measured height change as the window slides past it.
                 cell.index < m.count - 1
                     ? renderSeparatorElement(p.itemSeparatorComponent, item, p.getItem(p.data, cell.index + 1), separatorOverrides.get(cell.index))
                     : undefined;

package/build/intrinsic-elements.js

@@ -1 +1,3 @@
+// The tag alphabet, declared to vue-tsc and Volar. Vue's template checker resolves an unknown
+// lowercase tag as a component, so declaring it here makes the bare spelling first-class.
 export {};

package/build/renderer/index.js

@@ -3,7 +3,7 @@
 // drives the exact same retained tree React does: the proof the core is framework-
 // agnostic.
 import { callWithErrorHandling, createRenderer, ErrorCodes, markRaw, } from '@vue/runtime-core';
-import { appendChild, createAnchor, createElement, createRawText, childrenOf, dlog, insertBefore, isRawTextNode, isTextContainer, nextSiblingOf, parentOf, removeChild, routeProp, setProp, setText, textOf, toPublicInstance, SymbioteSurface, } from '@symbiote-native/engine';
+import { appendChild, createAnchor, createElement, createRawText, childrenOf, dlog, insertBefore, isRawTextNode, isTextContainer, nextSiblingOf, parentOf, removeChild, routeProp, setText, textOf, toPublicInstance, SymbioteSurface, } from '@symbiote-native/engine';
 import { descriptorFor } from '@symbiote-native/components';
 import { normalizeVueAttrKey } from '../utils/normalize-attrs.js';
 function isSurface(parent) {
@@ -12,20 +12,10 @@ function isSurface(parent) {
 function isRawText(node) {
     return isRawTextNode(node);
 }
-// RN's two Text defaults left this renderer entirely on 2026-09-18, in two steps a month apart. The
-// CREATE seed went first, because writing them as props cost a crossing every time the app authored
-// the same value — 6 000 per 1 000-row create, measured with `writesOfUnchanged`. What stayed was a
-// clear-back: an explicit `undefined` at patch time was substituted for the default, since RN treats
-// a missing prop and an explicit `undefined` alike.
-//
-// That substitution is gone too, and it was redundant rather than wrong. The rule reads the AUTHORED
-// bag at payload time (`foldTextDefaults`, `SymbioteFabricProps.cpp`), so it cannot tell a cleared
-// prop from one never written — both are absent by the time it looks, and both get the default. The
-// adapter was re-supplying an answer the layer below already had.
-// `PROP_ALIASES` (`id` -> `nativeID`) left this renderer on 2026-09-18 — `routeProp` resolves it
-// for every adapter now, and carries the per-node state the caveat here said was not worth it: with
-// both names on one element upstream gives `id` unconditional priority, where a per-key rename
-// resolved it by write order.
+// RN's two Text defaults are `foldTextDefaults`'s rule now (`SymbioteFabricProps.cpp`), reading
+// the AUTHORED bag at payload time — this renderer keeps no seed or clear-back of either default.
+// `id` -> `nativeID` is `routeProp`'s fold for every adapter now; with both names on one element
+// it gives `id` unconditional priority.
 // RN-style event prop naming ('onPress', 'onValueChange', ...), the same convention JSX itself
 // uses to separate an event from a plain value prop — good enough to decide whether to wrap,
 // without duplicating routeProp's own ViewConfig-derived event lists here.
@@ -87,15 +77,9 @@ export function createSymbioteRenderer(surface) {
             // one benchmark press — and a literal is built at the call site before dlog can decide
             // anything (see core/engine/src/debug.ts).
             dlog(() => `vue createElement ${descriptor.component} -> public instance`);
-            // markRaw is load-bearing, not an optimization: useTemplateRef()'s return value is
-            // `readonly(shallowRef(null))` (runtime-core.cjs.js), and Vue's readonly() wraps ANY
-            // `.value` whose Object.prototype.toString reads "[object Object]" — true of a plain class
-            // instance, unlike a real DOM Element, which fails that check for free. Unmarked, a node
-            // reached through useTemplateRef() (not a plain ref()/shallowRef(), both of which skip the
-            // wrap) came back as a deep-readonly Proxy: reads worked, so `committedOf`/`whenCommitted`
-            // saw a "committed" node, but `setNativeProps`'s `node.props.style = …` silently no-op'd
-            // with a dev-only "Set operation… target is readonly" warning — device-reported 2026-09-11
-            // as "flash the right chip" doing nothing on press.
+            // markRaw is load-bearing: useTemplateRef()'s `readonly(shallowRef(null))` wraps any
+            // `.value` that isn't a real DOM Element, and unmarked, `setNativeProps` silently
+            // no-ops against the resulting readonly Proxy.
             return markRaw(toPublicInstance(node));
         },
         createText(text) {

package/build/runtime-helpers/index.d.ts

@@ -22,22 +22,6 @@ type IModifierGuardableEvent = {
 type IEventHandler<TEvent> = ((event: TEvent, ...args: never[]) => unknown) & {
     _withMods?: Record<string, IEventHandler<TEvent>>;
 };
-/**
- * Render-function/compiled-template equivalent of `v-on.stop`/`.prevent`/`.self`/etc. `fn` is
- * typed as required, matching upstream Vue's own declaration — its runtime-only `!fn` guard below
- * (for a compiler-generated call site that could pass a falsy handler) isn't reflected in the
- * type there either.
- *
- * `@press.self` on an element reaches this, and both halves were measured 2026-09-11 rather
- * than assumed — the question arose because a modifier on a COMPONENT takes Vue's own event path
- * and only an element emits the helper. `<pressable @press.self>` compiles to
- * `_withModifiers(fn, ["self"])` imported `from "@symbiote-native/vue/runtime-helpers"` (the Metro
- * transformer retargets every compiled `from 'vue'`), so the compiler-emitted call lands here and
- * not on @vue/runtime-dom's. And `ISymbioteEvent` (`core/engine/src/node.ts`) declares `target`,
- * `currentTarget` and `stopPropagation` as REQUIRED fields with the DOM semantics these guards
- * read, so `.self` genuinely filters a bubbled press instead of degenerating to
- * `undefined !== undefined`.
- */
 export declare function withModifiers<TEvent extends IModifierGuardableEvent>(fn: IEventHandler<TEvent>, modifiers: readonly IEventModifier[]): IEventHandler<TEvent>;
 type IKeyedEvent = {
     key?: string;

package/build/runtime-helpers/index.js

@@ -37,9 +37,9 @@ import { descriptorFor, SWITCH_TAG } from '@symbiote-native/components';
 // idiom the engine resolves in `routeProp` (`isStyleCallback`); Vue's normaliser is DOM-shaped and
 // cannot know that.
 //
-// Measured 2026-09-01 through the real SFC pipeline, which is the ONLY path that reaches this:
-// `h(Component, { ...bag })` skips `normalizeProps` entirely and shows the style arriving intact,
-// so a probe written that way reports the bug as absent.
+// Reachable only through the real SFC pipeline: `h(Component, { ...bag })` skips
+// `normalizeProps` entirely and shows the style arriving intact, so a probe written that way
+// reports the bug as absent.
 //
 //   <View v-bind="bag">       fn style   committed {testID}              <- style gone
 //   <Pressable v-bind="bag">  fn style   committed {testID}              <- style gone
@@ -204,11 +204,9 @@ function syncModelListener(el, state) {
     state.appListener = isValueChangeListener(current) ? current : undefined;
     setProp(el, 'onValueChange', state.listener);
 }
-// Vue's compiler picks the directive by ELEMENT, and for anything it does not recognise as a DOM
-// input it emits `vModelText` — `<switch>` included. Stringifying there is what
-// upstream must do (a DOM input's value IS a string) and what we must not: the Switch behavior
-// reads `props.value === true`, so `String(true)` pins the control OFF and no tap can move it.
-// Device-confirmed on `examples/vue-sfc` 2026-09-02, both switches on `CanaryScreen`.
+// Vue's compiler picks the directive by ELEMENT: anything not recognised as a DOM input gets
+// `vModelText` — `<switch>` included. Stringifying is fatal here: Switch reads
+// `props.value === true`, so `String(true)` pins the control OFF and no tap can move it.
 //
 // Resolved through the shared descriptor table rather than a literal Fabric name, so the check
 // follows the platform the bundle actually loaded (iOS `Switch`, Android `AndroidSwitch`) instead
@@ -287,22 +285,11 @@ const MODIFIER_GUARDS = {
     right: event => event.button !== 2,
     exact: (event, modifiers) => SYSTEM_MODIFIERS.some(modifier => event[`${modifier}Key`] && !modifiers.includes(modifier)),
 };
-/**
- * Render-function/compiled-template equivalent of `v-on.stop`/`.prevent`/`.self`/etc. `fn` is
- * typed as required, matching upstream Vue's own declaration — its runtime-only `!fn` guard below
- * (for a compiler-generated call site that could pass a falsy handler) isn't reflected in the
- * type there either.
- *
- * `@press.self` on an element reaches this, and both halves were measured 2026-09-11 rather
- * than assumed — the question arose because a modifier on a COMPONENT takes Vue's own event path
- * and only an element emits the helper. `<pressable @press.self>` compiles to
- * `_withModifiers(fn, ["self"])` imported `from "@symbiote-native/vue/runtime-helpers"` (the Metro
- * transformer retargets every compiled `from 'vue'`), so the compiler-emitted call lands here and
- * not on @vue/runtime-dom's. And `ISymbioteEvent` (`core/engine/src/node.ts`) declares `target`,
- * `currentTarget` and `stopPropagation` as REQUIRED fields with the DOM semantics these guards
- * read, so `.self` genuinely filters a bubbled press instead of degenerating to
- * `undefined !== undefined`.
- */
+// Render-function/compiled-template equivalent of `v-on.stop`/`.prevent`/`.self`/etc. `fn` is
+// typed as required, matching upstream Vue's own declaration.
+// `@press.self` on an element reaches this — a modifier on a COMPONENT takes Vue's own event
+// path, only an element emits the helper. `ISymbioteEvent` declares `target`/`currentTarget`/
+// `stopPropagation` as REQUIRED fields with DOM semantics, so `.self` genuinely filters.
 export function withModifiers(fn, modifiers) {
     if (!fn)
         return fn;

package/intrinsic-tags.cjs

@@ -6,12 +6,9 @@
 // compiles to `resolveComponent("text-input")` with its children as a slot the element path never
 // reads, which renders a blank subtree with no error.
 //
-// DERIVED, never enumerated. Until 2026-09-07 this was the prefix test `tag.startsWith('symbiote-')`
-// in ./babel-jsx.cjs — correct while every intrinsic carried that marker, and answering FALSE for
-// every tag since the prefix was dropped (`core/components/src/component-names/shared.ts` says why
-// it went). What hid it is the tag alphabet: `view` / `text` / `image` / `switch` are real SVG
-// element names, so both compilers resolve those four as elements with no configuration at all, and
-// only the hyphenated half degraded.
+// DERIVED, never enumerated — the tag alphabet has no shared marker to test for.
+// `view`/`text`/`image`/`switch` are real SVG element names, so both compilers resolve those four
+// as elements with no configuration at all; only the hyphenated half needs this table.
 //
 // SCOPE, stated because it is smaller than `ISymbioteIntrinsic`. That union also holds
 // `scroll-view`, `modal`, `activity-indicator` and the rest, but it is a TypeScript type and these
@@ -19,16 +16,9 @@
 // runtime-readable table reachable from here, so a hand-written `<scroll-view>` still resolves as a
 // component. Closing that needs a CJS intrinsic table in `core/components`.
 //
-// WHAT THAT GAP COSTS, measured 2026-09-11 rather than reasoned, because the first guess was that
-// the tag simply would not work. It works: `resolveComponent` falls back to the tag STRING, and
-// `normalizeChildren` then unwraps the `withCtx` default slot for an element shapeFlag, so
-// `<scroll-view><text>hi</text></scroll-view>` committed `RCTView > RCTScrollView > RCTText >
-// RCTRawText`. What it costs is a dev-mode `[Vue warn]: Failed to resolve component: scroll-view`
-// on every such element plus the component codegen path (a slot closure per element) instead of
-// `_createElementBlock`. That is a divergence from every other tag, so `ScrollView`,
-// `TouchableOpacity` and `TouchableHighlight` stay COMPONENTS on Vue until their
-// `HOST_PRIMITIVES` entries land — and `intrinsic-elements.ts` already types all three as valid
-// markup off `ISymbioteIntrinsic`, so vue-tsc accepts what the runtime compiler warns about.
+// WHAT THAT GAP COSTS: `resolveComponent` falls back to the tag STRING and still commits the
+// right tree, paying only a dev-mode `[Vue warn]` plus the component codegen path — so
+// `ScrollView`/`TouchableOpacity`/`TouchableHighlight` stay COMPONENTS until they join this table.
 //
 // The tell that the three are still wrapped rather than merely unlisted: `src/register.ts` does
 // NOT call their behaviors, because a registered behavior plus a surviving wrapper is two owners

package/metro-vue-transformer.cjs

@@ -280,11 +280,9 @@ async function compileSfc(src, filename) {
   // re-parse, which is what we need anyway.
 
   parseCache.clear();
-  // element-vs-component is decided by the PARSER, not by the later `isCustomElement` in
+  // element-vs-component is decided by the PARSER, not the later `isCustomElement` in
   // templateOptions — `compileScript` reuses this descriptor's already-parsed AST, where `tagType`
-  // is already fixed. So a hand-written `<pressable>` needs the answer here or it stays a component
-  // whatever templateOptions says, which is how it read until 2026-09-07:
-  // `resolveComponent("pressable")`, a blank subtree with no error.
+  // is fixed. Without the answer here, `<pressable>` stays a component: `resolveComponent(...)`.
   const { descriptor, errors } = parse(src, {
     filename,
     templateParseOptions: { isCustomElement: tag => INTRINSIC_TAGS.has(tag) },
@@ -362,13 +360,9 @@ async function compileSfc(src, filename) {
   ];
   if (scopedClassNames.size > 0)
     nodeTransforms.push(createScopeClassNodeTransform(scopedClassNames));
-  // UNCONDITIONAL, and covering EVERY intrinsic rather than the ones this file happens to import.
-  // Both narrowings were live until 2026-09-07 and both broke a hand-written tag: a file importing
-  // no wrapper got no `isCustomElement` at all, and a file importing one got an answer scoped to
-  // that import, so `<pressable>` written by hand compiled to `resolveComponent("pressable")` —
-  // a blank subtree with no error — whichever way the file was written. `<switch v-model>` failed
-  // louder: `@vue/compiler-dom`'s transformModel rejects v-model on an element that is neither
-  // input/textarea/select nor a custom element, so it was a hard compile error.
+  // UNCONDITIONAL, and covering EVERY intrinsic rather than the ones this file happens to import:
+  // a narrower `isCustomElement` leaves `<pressable>` compiling to `resolveComponent(...)` (blank
+  // subtree, no error), and `<switch v-model>` a hard compile error (non-custom, non-form element).
   const templateOptions = {
     compilerOptions: {
       ...(nodeTransforms.length > 0 ? { nodeTransforms } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/vue",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "SymbioteNative's Vue adapter — a @vue/runtime-core createRenderer driving real native iOS/Android views through the same engine as the React adapter.",
   "license": "MIT",
   "repository": {
@@ -70,18 +70,18 @@
     "@vue/compiler-sfc": "^3.5.13",
     "@vue/runtime-core": "^3.5.13",
     "typescript": "~6.0.0",
-    "@symbiote-native/components": "3.1.0",
-    "@symbiote-native/css-parser": "0.5.0"
+    "@symbiote-native/components": "3.1.2",
+    "@symbiote-native/css-parser": "0.5.2"
   },
   "peerDependencies": {
     "vue": ">=3.5.0",
     "react-native": ">=0.86",
-    "@symbiote-native/engine": "^1.3.0"
+    "@symbiote-native/engine": "^1.3.1"
   },
   "devDependencies": {
     "@babel/core": "^7.25.2",
-    "@symbiote-native/engine": "1.3.0",
-    "@symbiote-native/test-utils": "0.4.2"
+    "@symbiote-native/engine": "1.3.1",
+    "@symbiote-native/test-utils": "0.4.4"
   },
   "scripts": {
     "typecheck": "tsc --build",