@symbiote-native/solid 0.0.1 → 0.1.0

package/build/primitives/create-window-dimensions.js

@@ -0,0 +1,34 @@
+// createWindowDimensions — the Solid twin of React's `useWindowDimensions` hook, Vue's composable,
+// Svelte's rune and Angular's WindowDimensionsService, over the framework-agnostic Dimensions
+// module (@symbiote-native/engine). See create-color-scheme.ts's header for why this bucket is
+// `primitives/` and why the name is `create*` rather than `use*`.
+//
+// Returns an ACCESSOR, never a snapshot — a Solid component body runs once, so a returned metrics
+// object would stay pinned to the boot orientation.
+//
+// Outside a component or `createRoot` the `onCleanup` has no owner: Solid warns and the Dimensions
+// listener lives for the process, while the accessor itself keeps tracking.
+import { createSignal, onCleanup } from 'solid-js';
+import { Dimensions, } from '@symbiote-native/engine';
+// Native re-emits a fresh metrics object on every 'change', including ones that touch the screen
+// but not the window. Comparing by field instead of identity keeps an unchanged window from waking
+// every consumer — the guard React/Vue/Angular/Svelte all write by hand, expressed here as the
+// signal's own equality (the idiomatic Solid spelling).
+function metricsEqual(a, b) {
+    return (a.width === b.width &&
+        a.height === b.height &&
+        a.scale === b.scale &&
+        a.fontScale === b.fontScale);
+}
+export function createWindowDimensions() {
+    const [dimensions, setDimensions] = createSignal(Dimensions.get('window'), { equals: metricsEqual });
+    // Seed and subscribe run in one synchronous tick, so — unlike the effect-based twins in the other
+    // adapters — there is no window between them for an update to be missed in, and no re-check.
+    const subscription = Dimensions.addEventListener('change', (set) => {
+        setDimensions(set.window);
+    });
+    onCleanup(() => {
+        subscription.remove();
+    });
+    return dimensions;
+}

package/build/render.d.ts

@@ -0,0 +1,7 @@
+import { type IRootTag, type SymbioteSurface } from '@symbiote-native/engine';
+import { type Component } from 'solid-js';
+export declare function mount(rootTag: IRootTag, RootComponent: Component): SymbioteSurface;
+export declare function unmount(rootTag: IRootTag): void;
+declare global {
+    var RN$stopSurface: ((surfaceId: number) => void) | undefined;
+}

package/build/render.js

@@ -0,0 +1,91 @@
+// Mount a Solid app onto a Fabric surface. The native host hands us a rootTag; we create a surface
+// for it and let Solid's universal renderer drive the engine, which commits into
+// nativeFabricUIManager — RN's own renderer never in the path.
+import { createSurface, disposeRoot, dlog, reportUncaughtError, } from '@symbiote-native/engine';
+import { catchError, createRoot } from 'solid-js';
+import { createComponent, insert, setActiveSurface } from './renderer.js';
+// One Solid root per surface, so a surface can be torn down (unmount) or cleanly re-mounted on the
+// same rootTag: the bridgeless host stops and restarts a surface on Fast Refresh and on
+// lifecycle/focus changes, reusing the rootTag. The value is Solid's own dispose function — the
+// whole reactive root goes with it, effects and cleanups included.
+const roots = new Map();
+// Insertion-ordered, so the last entry is the most recently mounted surface. Kept alongside
+// `roots` only to answer one question: when a surface is torn down, is there another one still
+// live for the renderer to keep committing into?
+const surfaces = new Map();
+let activeRootTag;
+function teardown(rootTag) {
+    const dispose = roots.get(rootTag);
+    if (dispose === undefined)
+        return;
+    dispose();
+    roots.delete(rootTag);
+    surfaces.delete(rootTag);
+    // Cleared AFTER dispose() on purpose: disposing runs user cleanups, which can still mutate the
+    // tree, and those mutations should reach the surface they belong to rather than be dropped by
+    // renderer.ts's post-unmount guard.
+    //
+    // And cleared ONLY when the surface going away is the one the renderer is actually committing
+    // into. Clearing unconditionally killed a surface that was still mounted: with two surfaces up,
+    // unmounting the FIRST left the second alive but permanently uncommitted — every later mutation
+    // hit renderer.ts's "mutation after unmount" guard and was silently dropped. That is reachable
+    // from ordinary code the moment two surfaces exist, which is exactly the createTunnel case
+    // (../create-tunnel): the source surface stops, the target must keep painting.
+    if (activeRootTag !== rootTag) {
+        disposeRoot(rootTag);
+        return;
+    }
+    const remaining = Array.from(surfaces.entries()).pop();
+    activeRootTag = remaining?.[0];
+    setActiveSurface(remaining?.[1]);
+    disposeRoot(rootTag);
+}
+export function mount(rootTag, RootComponent) {
+    // A re-mount on a live rootTag starts clean; otherwise the stale root double-drives the surface.
+    teardown(rootTag);
+    const surface = createSurface(rootTag);
+    surfaces.set(rootTag, surface);
+    activeRootTag = rootTag;
+    setActiveSurface(surface);
+    // `createComponent(RootComponent, {})` is exactly what compiled JSX emits for `<RootComponent />`
+    // — written by hand here because this file is plain TS, deliberately: render.ts is the one module
+    // an app's entry point imports before any JSX has been compiled, so keeping it JSX-free means it
+    // needs no Babel pass of its own.
+    //
+    // The surface IS the render container: a top-level insert routes to surface.appendChild
+    // (renderer.ts's insertNode), and the engine wraps surface.children in its synthetic flex root.
+    //
+    // `createRoot` + `insert` IS renderer.ts's `render(code, surface)`, spelled out so `catchError`
+    // can sit BETWEEN them. Solid's own `render` runs `insert(element, code())` — the insert lands
+    // outside anything `code` wrapped, so a root component returning a bare accessor would build its
+    // render effect under an owner with no error handler and throw past this seam. Written this way
+    // the insert is inside, and every computation the mount creates inherits the handler.
+    let unwinding;
+    const dispose = createRoot(disposeRootScope => {
+        catchError(() => {
+            insert(surface, createComponent(RootComponent, {}));
+        }, error => {
+            if (unwinding?.error !== error) {
+                unwinding = { error };
+                reportUncaughtError(error, { origin: 'solid render' });
+            }
+            throw error;
+        });
+        return disposeRootScope;
+    });
+    roots.set(rootTag, dispose);
+    return surface;
+}
+// Tear down a surface by rootTag: the public pair of `mount`, and the JS half of the bridgeless
+// `RN$stopSurface` contract (see installStopSurfaceGlobal below).
+export function unmount(rootTag) {
+    dlog(`solid unmount root=${rootTag}`);
+    teardown(rootTag);
+}
+function installStopSurfaceGlobal() {
+    globalThis.RN$stopSurface = (surfaceId) => {
+        unmount(surfaceId);
+    };
+    dlog('installed global.RN$stopSurface');
+}
+installStopSurfaceGlobal();

package/build/renderer.d.ts

@@ -0,0 +1,7 @@
+import { SymbioteSurface, type ISymbioteNode } from '@symbiote-native/engine';
+type IHostNode = ISymbioteNode | SymbioteSurface;
+export declare function setActiveSurface(surface: SymbioteSurface | undefined): void;
+export declare function replaceText(textNode: IHostNode, value: string): void;
+export declare function removeNode(parent: IHostNode, node: IHostNode): void;
+export declare const render: (code: () => IHostNode, node: IHostNode) => () => void, effect: <T>(fn: (prev?: T) => T, init?: T) => void, memo: <T>(fn: () => T, equal: boolean) => () => T, createComponent: <T>(Comp: (props: T) => IHostNode, props: T) => IHostNode, createElement: (tag: string) => IHostNode, createTextNode: (value: string) => IHostNode, insertNode: (parent: IHostNode, node: IHostNode, anchor?: IHostNode | undefined) => void, insert: <T>(parent: any, accessor: T | (() => T), marker?: any | null, initial?: any) => IHostNode, spread: <T>(node: any, accessor: (() => T) | T, skipChildren?: boolean) => void, setProp: <T>(node: IHostNode, name: string, value: T, prev?: T | undefined) => T, mergeProps: (...sources: unknown[]) => unknown, use: <A, T>(fn: (element: IHostNode, arg: A) => T, element: IHostNode, arg: A) => T;
+export {};

package/build/renderer.js

@@ -0,0 +1,195 @@
+// A Solid custom renderer over @symbiote-native/engine, built on solid-js/universal's official
+// createRenderer — the framework-agnostic seam Solid itself ships for non-DOM targets. Each
+// RendererOptions method maps onto the engine's tiny mutation API; the engine owns all Fabric
+// clone-on-write, so Solid drives the exact same retained tree React, Vue, Angular and Svelte do.
+//
+// THIS MODULE IS ALSO A COMPILER TARGET, which is why it exports what it exports. babel-preset-solid
+// with `generate: 'universal'` rewrites every JSX element into direct calls imported from the
+// `moduleName` it was configured with (../babel-preset.cjs points it here, at the ./renderer
+// subpath). A component like
+//
+//   <symbiote-view style={{ flex: 1 }}>count {n()}</symbiote-view>
+//
+// compiles to `createElement('symbiote-view')` + `setProp(...)` + `createTextNode('count ')` +
+// `insert(el, n, null)`, all imported from this file. So the named exports at the bottom are a
+// hard contract with the compiler, not a matter of taste: drop one and the app fails to bundle
+// with a module-not-found on an import nobody typed. The 11 names were verified by running
+// babel.transformSync over representative JSX (elements, dynamic text, <Show>, <For>, spread,
+// ref) rather than read off the docs.
+import { createRenderer } from 'solid-js/universal';
+import { appendChild, createAnchor, createElement as createEngineElement, createRawText, dlog, insertBefore, removeChild as removeEngineChild, routeProp, setText as setEngineText, toPublicInstance, RAW_TEXT_COMPONENT, SymbioteSurface, } from '@symbiote-native/engine';
+import { descriptorFor } from '@symbiote-native/components';
+function isSurface(node) {
+    return node instanceof SymbioteSurface;
+}
+function isRawText(node) {
+    return !isSurface(node) && node.component === RAW_TEXT_COMPONENT;
+}
+// One active surface per process. This is FORCED here, not chosen: the compiled-JSX contract above
+// means every mutation arrives through module-level functions with no surface argument, so there is
+// nowhere for a per-surface renderer instance to be threaded through (Vue can close over its
+// surface because Vue's createRenderer is called by US, per mount). Threading it per node instead
+// would mean walking `parent` to the root on EVERY setProperty to find which surface to recommit —
+// too hot for the prop path. Same single-root-per-process conclusion the Svelte adapter reached for
+// its own reasons (svelte-adapter-dom-shim §10).
+let activeSurface;
+export function setActiveSurface(surface) {
+    activeSurface = surface;
+}
+// Every mutation asks the surface to (microtask-coalesced) recommit. Solid updates fine-grained and
+// often — a single signal write can touch several props across several nodes — so a burst within one
+// tick collapses into a single completeRoot, which is exactly what requestCommit() is for.
+//
+// A missing surface is not an error: Solid disposes its reactive graph asynchronously, so a
+// cleanup-driven removeNode can legitimately land after unmount() cleared the surface. Dropping the
+// commit is correct there (nothing to commit into), but it stays logged rather than silent.
+function requestCommit() {
+    if (activeSurface === undefined) {
+        dlog('solid mutation after unmount — commit skipped');
+        return;
+    }
+    activeSurface.requestCommit();
+}
+function siblingsOf(node) {
+    if (node.parent !== undefined)
+        return node.parent.children;
+    return activeSurface?.children ?? [];
+}
+// Hoisted out of nodeOps and exported because descriptor-to-solid.ts needs the same text-update
+// path for a Descriptor's string child, and createRenderer() only hands back the 11 names the JSX
+// compiler imports — replaceText is not among them. Going through here rather than calling the
+// engine's setText directly is what keeps the mutation paired with requestCommit().
+export function replaceText(textNode, value) {
+    if (isSurface(textNode))
+        return;
+    setEngineText(textNode, asText(value));
+    requestCommit();
+}
+// solid-js/universal hands createTextNode/replaceText the JSX child value UNCONVERTED, not a
+// stringified one: normalizeIncomingArray() pushes `createTextNode(item)` straight from the
+// children array, so `<Text>{list().length} tiles</Text>` arrives here as the NUMBER 3. On the DOM
+// that is invisible — document.createTextNode coerces — which is why upstream never had to, and why
+// React's and Vue's adapters (whose frameworks stringify first) never saw it either. Here the value
+// lands on RCTRawText's `text`, which Fabric parses as a std::string: a number fails the
+// conversion, convertRawProp logs and falls back to the DEFAULT empty string, and an empty first
+// fragment then ABORTS the app inside BaseTextShadowNode::buildAttributedString — a native SIGABRT
+// with nothing in the JS stack to point at. Diagnosed on the iOS simulator 2026-08-19. The
+// parameter is typed `string` by RendererOptions, so the guard reads as redundant; it is not, and
+// `unknown` is what makes that honest rather than a cast.
+function asText(value) {
+    return typeof value === 'string' ? value : String(value);
+}
+// Hoisted and exported for the same reason as replaceText above: createRenderer() hands back only
+// the 11 names the JSX compiler imports, and removeNode is not among them — but create-portal.tsx
+// has to DETACH its anchor host from the portal target on cleanup. Going through here rather than
+// calling the engine's removeChild directly is what keeps the mutation paired with requestCommit(),
+// and keeps the surface-vs-node branch in one place.
+export function removeNode(parent, node) {
+    if (isSurface(node))
+        return;
+    if (isSurface(parent))
+        parent.removeChild(node);
+    else
+        removeEngineChild(parent, node);
+    requestCommit();
+}
+const nodeOps = {
+    createElement(tag) {
+        const descriptor = descriptorFor(tag);
+        const node = createEngineElement(descriptor.component, descriptor.isText);
+        // Graft the imperative public-instance API (measure / setNativeProps / focus / …) onto the raw
+        // node so a `ref` to a host element exposes it exactly like React's getPublicInstance.
+        // toPublicInstance mutates in place and returns the SAME node identity, so the engine's commit
+        // mirror (keyed on the raw node) still resolves it. Solid hands a plain `ref={el}` this object
+        // by assignment, so identity survives — but it must never be put in a createStore(), whose deep
+        // proxy would become a different WeakMap key and silently break every imperative command.
+        dlog(`solid createElement ${descriptor.component} -> public instance`);
+        return toPublicInstance(node);
+    },
+    // Two callers, one signature. Real content: `createTextNode('count ')` for a text literal, which
+    // is genuine RCTRawText and must live inside a <Text>. A PLACEHOLDER: solid-js/universal's
+    // cleanChildren() does `replacement || createTextNode("")` to hold the position of a dynamic
+    // expression (<Show>, <For>, any `{...}` with following siblings) while it has nothing to show.
+    // An empty RCTRawText would actually PAINT in Fabric, so an empty string maps to an engine
+    // anchor: a real retained node that keeps sibling order correct and is skipped by the commit walk.
+    // Identical call and identical fix as Vue's createText (adapters/vue/src/renderer/index.ts).
+    createTextNode(value) {
+        const text = asText(value);
+        return text === '' ? createAnchor() : createRawText(text);
+    },
+    replaceText,
+    // Answers "is this node one I can write a string into", NOT "did createTextNode make it" — and
+    // the difference is load-bearing. solid-js/universal's insertExpression() does
+    // `if (node && isTextNode(node)) replaceText(node, value)` where `node` is whatever cleanChildren
+    // left in place, i.e. usually the empty-string ANCHOR from createTextNode above. Answering true
+    // for an anchor would send the runtime down replaceText() to write text into a node that is not
+    // an RCTRawText and never reaches Fabric at all; answering false sends it down its other branch,
+    // which replaces the anchor with a fresh raw-text node — the correct outcome. So this checks the
+    // component name, and an anchor ('#anchor') is excluded by construction.
+    isTextNode(node) {
+        return isRawText(node);
+    },
+    setProperty(node, name, value) {
+        if (isSurface(node))
+            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), and centralizes the class+style
+        // merge. Shared with React and Vue — never re-implement an `onX` check here
+        // (symbiote-engine-core §2).
+        routeProp(node, name, value);
+        requestCommit();
+    },
+    insertNode(parent, node, anchor) {
+        // The surface is only ever the root CONTAINER, never a child or a sibling marker. Both guards
+        // are narrowing, not defensive: RendererOptions types every position as the same NodeType, so
+        // the union has to be discharged before the engine calls, which take a node.
+        if (isSurface(node))
+            return;
+        const before = anchor !== undefined && !isSurface(anchor) ? anchor : undefined;
+        if (isRawText(node) && (isSurface(parent) || !parent.isText)) {
+            // Fabric has no bare-text host: RCTRawText is only valid as a <Text> child. Reached by a
+            // dynamic expression that resolves to a string outside a <Text>, e.g.
+            // `<symbiote-view>{label()}</symbiote-view>`. Failing loudly at mount beats building an
+            // invalid tree that crashes deeper in native with a far less legible error.
+            throw new Error(`Text string "${String(node.props.text)}" must be rendered inside a <Text>`);
+        }
+        if (isSurface(parent)) {
+            if (before !== undefined)
+                parent.insertBefore(node, before);
+            else
+                parent.appendChild(node);
+        }
+        else if (before !== undefined) {
+            insertBefore(parent, node, before);
+        }
+        else {
+            appendChild(parent, node);
+        }
+        requestCommit();
+    },
+    removeNode,
+    getParentNode(node) {
+        if (isSurface(node))
+            return undefined;
+        return node.parent ?? activeSurface;
+    },
+    // Anchors are NOT filtered out of this or getNextSibling, deliberately. solid-js/universal keeps
+    // its own record of which nodes it put where and re-derives positions through these two lookups
+    // (cleanChildren walks getFirstChild to empty a parent; insertExpression reaches for
+    // getFirstChild(parent) to replace text in place). Hiding a node the runtime itself inserted
+    // desyncs that record from the real tree. Anchors are invisible to FABRIC — the commit walk skips
+    // them — not to tree traversal.
+    getFirstChild(node) {
+        return node.children[0];
+    },
+    getNextSibling(node) {
+        if (isSurface(node))
+            return undefined;
+        const siblings = siblingsOf(node);
+        const index = siblings.indexOf(node);
+        return index >= 0 ? siblings[index + 1] : undefined;
+    },
+};
+// The compiled-JSX contract. See the module header: these names are imported by generated code,
+// so the list is fixed by babel-preset-solid, not by us.
+export const { render, effect, memo, createComponent, createElement, createTextNode, insertNode, insert, spread, setProp, mergeProps, use, } = createRenderer(nodeOps);

package/build/utils/host-ref.d.ts

@@ -0,0 +1,3 @@
+import type { Ref } from 'solid-js';
+import type { IHostInstance } from '../host-instance';
+export declare function applyHostRef(ref: Ref<IHostInstance> | undefined, node: IHostInstance): void;

package/build/utils/host-ref.js

@@ -0,0 +1,22 @@
+// How a caller's `ref` on one of our components reaches the host element.
+//
+// Solid's `ref` is a COMPILE-TIME construct, not a runtime object, and that is the whole reason
+// this helper exists. On a component the compiler rewrites `ref={el}` into a callback prop:
+//
+//   <View ref={el} />   ->   createComponent(View, { ref(r$) { … el = r$ } })
+//
+// so by the time a component body reads `props.ref`, a variable target has ALREADY become a
+// function. React's RefObject / Vue's template ref have no counterpart here — there is nothing to
+// write a `.current` into, and nothing for the adapter to allocate. The component's only job is to
+// call what it was handed with the host node.
+//
+// The declared type still has to be solid-js's own `Ref<T>` union (`T | ((val: T) => void)`),
+// because type-checking happens on the SOURCE the author wrote: `ref={el}` passes a variable of
+// type T, and a callback-only signature would reject it before the compiler ever gets to rewrite
+// it. So the union is a call-site typing requirement, and the runtime value is always the
+// function branch — a non-function can only arrive from a hand-written createComponent() call,
+// where there is no variable binding to assign back into, so it is ignored rather than guessed at.
+export function applyHostRef(ref, node) {
+    if (typeof ref === 'function')
+        ref(node);
+}

package/build/utils/stable-keys.d.ts

@@ -0,0 +1 @@
+export declare function withStableKeys(props: () => Record<string, unknown>): () => Record<string, unknown>;

package/build/utils/stable-keys.js

@@ -0,0 +1,31 @@
+// Solid's `spread` walks only the CURRENT key set (`for (const prop in props)` in its
+// spreadExpression) and has no removal pass, so a key that VANISHES between runs keeps its last
+// value on the native view forever. Not hypothetical: resolveAccessibilityProps has two branches
+// with different key sets — it returns the input untouched while no aria-* alias holds a value,
+// and `{...props, role: undefined, …every alias blanked, accessibilityLabel: <folded>}` once one
+// does (hasAnyAriaKey tests the VALUE, not key presence). So a caller whose `aria-label` signal
+// goes undefined drops the `accessibilityLabel` KEY, and a screen reader keeps announcing a label
+// the app already removed. React and Vue never meet this: they hand their reconciler a whole new
+// prop object, and the engine's diffProps sends a vanished key down as literal null
+// (symbiote-engine-core §8). Widening the bag to every key ever seen restores that — a vanished
+// key arrives as `undefined`, which routeProp treats as a delete, and `spread` keeps doing all
+// the actual diffing. Never hand-roll that diff instead.
+//
+// Lives here rather than beside either caller because BOTH reach for it: descriptorToSolid wraps
+// a render fn's Descriptor props, and the host primitives (View, Text) wrap their own
+// resolveAccessibilityProps output — the same function, the same two-branch key set. Any future
+// Solid component that folds props through a whole-object transform belongs on this too.
+export function withStableKeys(props) {
+    const seen = new Set();
+    return () => {
+        const next = props();
+        const widened = {};
+        for (const key of seen)
+            widened[key] = undefined;
+        for (const key of Object.keys(next)) {
+            seen.add(key);
+            widened[key] = next[key];
+        }
+        return widened;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/solid",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "SymbioteNative's Solid adapter — a solid-js/universal createRenderer driving real native iOS/Android views through the same engine as every other adapter.",
   "license": "MIT",
   "repository": {
@@ -52,8 +52,8 @@
   "dependencies": {
     "babel-preset-solid": "^1.9.12",
     "typescript": "~6.0.0",
-    "@symbiote-native/css-parser": "0.3.0",
-    "@symbiote-native/components": "0.4.0"
+    "@symbiote-native/components": "0.5.0",
+    "@symbiote-native/css-parser": "0.4.0"
   },
   "peerDependencies": {
     "@symbiote-native/engine": ">=0.1.7",
@@ -62,8 +62,8 @@
   },
   "devDependencies": {
     "solid-js": "^1.9.14",
-    "@symbiote-native/engine": "0.2.0",
-    "@symbiote-native/test-utils": "0.1.6"
+    "@symbiote-native/engine": "0.3.0",
+    "@symbiote-native/test-utils": "0.2.0"
   },
   "scripts": {
     "typecheck": "tsc --build",