@symbiote-native/components 1.0.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/components",
-  "version": "1.0.0",
+  "version": "3.0.0",
   "description": "Framework-agnostic component logic (state machines + render functions) for SymbioteNative — written once, inherited by every adapter (React, Vue, Angular, ...).",
   "license": "MIT",
   "repository": {
@@ -40,43 +40,30 @@
       "types": "./host-primitives.d.cts",
       "default": "./host-primitives.cjs"
     },
-    "./specialize-state-style": "./specialize-state-style.cjs",
-    "./lowering-fixtures": {
-      "types": "./lowering-fixtures.d.cts",
-      "default": "./lowering-fixtures.cjs"
-    },
-    "./state-style": {
-      "types": "./build/state-style.d.ts",
-      "default": "./build/state-style.js"
-    },
-    "./fold-host-bag": {
-      "types": "./build/fold-host-bag.d.ts",
-      "default": "./build/fold-host-bag.js"
-    },
     "./resolve-intrinsic": {
       "types": "./build/resolve-intrinsic.d.ts",
       "default": "./build/resolve-intrinsic.js"
+    },
+    "./register": {
+      "types": "./build/register.d.ts",
+      "default": "./build/register.js"
     }
   },
   "files": [
     "build",
     "host-primitives.cjs",
-    "host-primitives.d.cts",
-    "specialize-state-style.cjs",
-    "specialize-state-style.d.cts",
-    "lowering-fixtures.cjs",
-    "lowering-fixtures.d.cts"
+    "host-primitives.d.cts"
   ],
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
     "react-native": ">=0.86",
-    "@symbiote-native/engine": "^0.4.0"
+    "@symbiote-native/engine": "^1.0.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
-    "@symbiote-native/engine": "0.4.0"
+    "@symbiote-native/engine": "1.0.0"
   },
   "scripts": {
     "typecheck": "tsc --build",

package/build/fold-host-bag.d.ts

@@ -1,15 +0,0 @@
-import { type IFoldOp } from '../host-primitives.cjs';
-export type IHostBag = Record<string, unknown>;
-interface IFoldPlan {
-    readonly aliases: ReadonlyArray<readonly [string, string]>;
-    readonly defaults: ReadonlyArray<readonly [string, IFoldOp]>;
-}
-export declare const FOLD_PLAN_BY_TAG: ReadonlyMap<string, IFoldPlan>;
-/**
- * Apply a primitive's aliases and defaults to a bag, copy-on-write.
- *
- * Never mutates the input: the bag belongs to whoever built it, and a framework may hand the same
- * object back on a re-render, so writing into it would leak a fold into the author's own state.
- */
-export declare function foldHostBag(tagName: string, bag: IHostBag): IHostBag;
-export {};

package/build/fold-host-bag.js

@@ -1,99 +0,0 @@
-// The RUNTIME half of `HOST_PRIMITIVES` — RN's prop folds applied to a props bag on its way into
-// the engine, keyed by intrinsic tag.
-//
-// Why it exists at all. A primitive's host node is produced by THREE paths, and the compile-time
-// fold in a lowering transform covers exactly one of them:
-//
-//   lowered `<View>`         the transform folded it     covered by the transform
-//   `<View>` it refused      the wrapper folds it        covered by the wrapper
-//   a hand-authored tag      nobody folds it             covered by NOTHING
-//
-// The third path is not hypothetical: Svelte's `components/button.svelte` writes `<symbiote-text>`
-// directly rather than composing `Text.svelte`, so its title reached Fabric with no
-// `ellipsizeMode` and clipped mid-word where every other adapter ellipsised (2026-08-31). Angular
-// shipped the identical defect from the identical cause, and both fixed it the same way — a seed
-// in the layer every path crosses.
-//
-// Why it is SHARED rather than one copy per adapter: an adapter that lowers has a transform doing
-// this at compile time, an adapter that does not has only this, and a primitive with no wrapper at
-// all (a bare intrinsic tag) has only this everywhere. Three producers of one answer is the shape
-// `<adapters_stay_thin>` exists to stop. Both halves read the same spec, so they cannot drift into
-// two different answers — only into one answer applied twice, which every operation here is
-// idempotent under (`(x ?? 'tail') ?? 'tail'`, `(x !== false) !== false`).
-import { HOST_PRIMITIVES, } from '../host-primitives.cjs';
-const planFor = (primitive) => ({
-    aliases: Object.entries(primitive.aliases),
-    defaults: Object.entries(primitive.defaults),
-});
-// The wrapper's spelling of a tag whose behavior must attach to the LOWERED path only
-// (`component-names/shared.ts`). A suffix rather than a spec field because it cannot go stale: the
-// next primitive to grow a `-managed` twin is covered the day it is named, with no edit here.
-// `managed-tags-fold.test.ts` pins the convention against the platform tables, so a twin named some
-// other way fails rather than silently losing its folds.
-const managedSpellingOf = (tag) => `${tag}-managed`;
-// EVERY spelling a primitive commits under, and the two axes are independent.
-//
-// `intrinsicWhen` lets one primitive commit two different tags (`TextInput` ->
-// `symbiote-text-input` / `…-multiline`). `-managed` is the wrapper's twin of each of those. A map
-// keyed on the lowered spellings alone folds the lowered path and silently skips the component one
-// — which is exactly what shipped: TextInput and Switch committed a raw `id`, a key no ViewConfig
-// declares, so Fabric dropped it and the nativeID was lost on device with nothing red. Found by
-// Svelte's equivalence arm, 2026-09-01, and it is the two paths of ONE adapter disagreeing.
-//
-// Folding a bag the wrapper already folded is a no-op — an alias deletes its source key, so the
-// second pass finds nothing to rename — which is what makes covering both paths from one plan safe.
-function tagsOf(primitive) {
-    const alternate = primitive.intrinsicWhen?.intrinsic;
-    const lowered = alternate === undefined
-        ? [primitive.intrinsic]
-        : [primitive.intrinsic, alternate];
-    return [...lowered, ...lowered.map(managedSpellingOf)];
-}
-export const FOLD_PLAN_BY_TAG = new Map(Object.values(HOST_PRIMITIVES).flatMap(primitive => {
-    const plan = planFor(primitive);
-    return tagsOf(primitive).map((tag) => [tag, plan]);
-}));
-// The runtime twin of a transform's `foldExpression`, which emits these same two operations as
-// SOURCE. `notFalse` is RN's own encoding (`allowFontScaling !== false`): an explicit `undefined`
-// reads as "not set" and only a literal `false` opts out, which is why it is not a `??`.
-function fold(op, authored) {
-    return op.op === 'notFalse' ? authored !== false : (authored ?? op.value);
-}
-/**
- * Apply a primitive's aliases and defaults to a bag, copy-on-write.
- *
- * Never mutates the input: the bag belongs to whoever built it, and a framework may hand the same
- * object back on a re-render, so writing into it would leak a fold into the author's own state.
- */
-export function foldHostBag(tagName, bag) {
-    const plan = FOLD_PLAN_BY_TAG.get(tagName);
-    if (plan === undefined)
-        return bag;
-    let next = bag;
-    for (const [from, to] of plan.aliases) {
-        if (!(from in next))
-            continue;
-        if (next === bag)
-            next = { ...bag };
-        // RN gives the alias unconditional priority when both are set (View.js:77-79,
-        // `processedProps.nativeID = id`), and the raw key must not survive — no ViewConfig declares
-        // `id`, so Fabric would drop it silently.
-        next[to] = next[from];
-        delete next[from];
-    }
-    // Seeded whether or not the key was authored: a default that only applies to a key already
-    // present is not a default.
-    //
-    // A bag a transform already folded takes the `continue` on every key and never reaches the copy —
-    // which is what keeps the compile-time fold worth having once this one exists. It is no longer
-    // the mechanism, but it does keep the hot path allocation-free.
-    for (const [key, op] of plan.defaults) {
-        const folded = fold(op, next[key]);
-        if (key in next && Object.is(next[key], folded))
-            continue;
-        if (next === bag)
-            next = { ...bag };
-        next[key] = folded;
-    }
-    return next;
-}

package/build/state-style.d.ts

@@ -1,15 +0,0 @@
-export interface IPressStateArgument {
-    pressed: boolean;
-}
-export interface IResolvedStateStyle {
-    style: unknown;
-    activeStyle: unknown;
-}
-/**
- * Splits an authored `style` into its resting and pressed halves, reading the value once.
- *
- * A non-callback passes through untouched with no active variant, which the engine reads as "leave
- * slot 1 alone" — that is what makes one emission safe for an expression whose value cannot be
- * known at compile time.
- */
-export declare function resolveStateStyle(value: unknown): IResolvedStateStyle;

package/build/state-style.js

@@ -1,47 +0,0 @@
-// The runtime half of state-style lowering: splits an authored `style` into its resting and pressed
-// halves. Referenced by the code every lowering transform EMITS, never by app code.
-//
-// SHARED for the same reason `HOST_PRIMITIVES` and `specializeStateStyle` are — two adapters had
-// written byte-identical copies within an hour of each other, which is the duplication
-// `<adapters_stay_thin>` exists to stop. Each adapter re-exports it from its own `./state-style`
-// subpath so the emitted import specifier stays inside the package the app already depends on.
-//
-// WHY A HELPER EXISTS BESIDE THE INLINE GUARD, since a transform may emit either. Building the pair
-// needs the authored `style` expression, and the two emissions are NOT equivalent:
-//
-//   inline    typeof e === 'function' ? e({pressed:false}) : e   prints `e` on both props, so a
-//             `getStyle()` runs twice and a `flag ? a : b` can take DIFFERENT branches
-//   helper    resolveStateStyle(e)                               prints `e` once and calls its
-//             RESULT twice
-//
-// The rule the two must satisfy is `REFUSAL_CATEGORIES.emitStyleExpressionOnce`, and it is about
-// the output rather than the input: **an expression capable of DOING WORK is printed once.** A bare
-// name or a non-computed dotted path is a read, not work, so the inline form is legitimate there —
-// and it matters, because a helper returns one object, which a framework must spread, and a spread
-// costs the element its patch flag (Vue measured `12 /* STYLE, PROPS */` becoming
-// `16 /* FULL_PROPS */` plus a `mergeProps` per render on the hottest element in the tree).
-//
-// So the VERDICT is identical across adapters — every shape lowers — and only the cost differs,
-// exactly as compile-time substitution differs between a JSX path and an SFC one. The verdicts are
-// what `@symbiote-native/components/lowering-fixtures` pins.
-//
-// THE CONTRACT THIS IMPOSES ON APP CODE: a style callback must be PURE in `pressed`. Its result is
-// invoked twice under every emission, so a side-effecting body is observable now.
-function isStyleCallback(value) {
-    return typeof value === 'function';
-}
-/**
- * Splits an authored `style` into its resting and pressed halves, reading the value once.
- *
- * A non-callback passes through untouched with no active variant, which the engine reads as "leave
- * slot 1 alone" — that is what makes one emission safe for an expression whose value cannot be
- * known at compile time.
- */
-export function resolveStateStyle(value) {
-    if (!isStyleCallback(value))
-        return { style: value, activeStyle: undefined };
-    return {
-        style: value({ pressed: false }),
-        activeStyle: value({ pressed: true }),
-    };
-}

package/build/view/render-activity-indicator.d.ts

@@ -1,25 +0,0 @@
-import type { IStyleProp, IViewStyle, ISymbioteEvent } from '@symbiote-native/engine';
-import type { IDescriptor } from '../descriptor';
-import type { IAccessibilityProps, IAriaProps } from '../accessibility-props';
-export type IActivityIndicatorSize = 'small' | 'large' | number;
-export interface IActivityIndicatorProps extends IAccessibilityProps, IAriaProps {
-    animating?: boolean;
-    color?: string;
-    size?: IActivityIndicatorSize;
-    hidesWhenStopped?: boolean;
-    style?: IStyleProp<IViewStyle>;
-    onLayout?: (event: ISymbioteEvent) => void;
-}
-export type IActivityIndicatorViewProps = {
-    animating: boolean;
-    hidesWhenStopped: boolean;
-    size: IActivityIndicatorSize;
-    color?: string;
-    style?: IStyleProp<IViewStyle>;
-    passthrough: Record<string, unknown>;
-};
-export type IActivityIndicatorPlatform = {
-    defaultColor: string | null;
-    nativeExtras: Readonly<Record<string, unknown>>;
-};
-export declare function renderActivityIndicator(view: IActivityIndicatorViewProps, platform: IActivityIndicatorPlatform): IDescriptor;

package/build/view/render-activity-indicator.js

@@ -1,88 +0,0 @@
-// ACTIVITYINDICATOR IS NOT A LOWERABLE PRIMITIVE, AND WILL NOT BECOME ONE. Decided 2026-09-01.
-// It stays a component in every adapter; do not add it to `HOST_PRIMITIVES`.
-//
-// The reason is the `el('symbiote-view', wrapperProps, [el('symbiote-activity-indicator', …)])` at
-// the bottom of this file: the render SYNTHESIZES a node that is not the primitive itself. A lowered
-// tag is ONE engine node, and a host behavior's `foldPayload` maps props to props on that node — it
-// cannot create a child. Lowering would therefore drop the centering container and change layout,
-// which is an optimisation moving the observable surface, the one thing this design may not do.
-//
-// The wrapper is not over-building: RN's own `ActivityIndicator.js:112` renders a `<View>` around
-// the native spinner too, so the two nodes are inherent. And the container cannot be folded INTO the
-// spinner — it carries `alignItems`/`justifyContent`, which centre the spinner inside the space it
-// was given; moved onto the spinner they would centre its children, of which it has none.
-//
-// The two alternatives were priced and both cost more than the primitive is worth. A behavior that
-// CREATES a node needs a commit hook, i.e. a machine, i.e. a `-managed` tag split — a new category,
-// not a fold. Synthesising the container inside the engine's commit walk is NOT the `RCTVirtualText`
-// precedent it resembles: `viewNameFor` changes what one node IS and never ADDS one, so adding one
-// would make the retained and committed trees disagree on node count — which every counter, census
-// probe and benchmark in this repo assumes. Spinners are rare on a screen, so the per-instance cost
-// lowering removes is not measurably paid here; the objection to leaving it is uniformity, not speed.
-//
-// Under half A this costs an app NOTHING: `View` and `ActivityIndicator` are both ordinary imports
-// from the adapter barrel, so which one is internally a tag and which a component is invisible at
-// the call site. The general rule is in `.claude/rules/host-primitive-tier.md`.
-//
-// ActivityIndicator: the render half (framework-agnostic). RN wraps the native spinner
-// in a centering View and translates `size` in JS: 'small'/'large' map to a native size
-// enum AND a fixed box style; a numeric size never reaches native (it sizes the spinner
-// via style only). That translation is platform-invariant and lives here.
-//
-// What IS platform-specific: Android's AndroidProgressBar needs
-// `styleAttr` (which triggers its setStyle(), without it the view throws "setStyle() not
-// called") plus `indeterminate: true`, and its default color is the theme (null), whereas
-// iOS's ActivityIndicatorView takes neither and defaults to GRAY. The adapter's per-host
-// file supplies those bits via `platform`.
-import { dlog } from '@symbiote-native/engine';
-import { el } from '../descriptor.js';
-// Fixed pixel boxes RN gives the two named sizes (styles.sizeSmall/sizeLarge).
-const SIZE_SMALL_PX = 20;
-const SIZE_LARGE_PX = 36;
-// Centering wrapper RN puts around the spinner (styles.container).
-const CONTAINER_STYLE = {
-    alignItems: 'center',
-    justifyContent: 'center',
-};
-function resolveSize(size) {
-    if (size === 'small') {
-        return {
-            sizeStyle: { width: SIZE_SMALL_PX, height: SIZE_SMALL_PX },
-            sizeProp: 'small',
-        };
-    }
-    if (size === 'large') {
-        return {
-            sizeStyle: { width: SIZE_LARGE_PX, height: SIZE_LARGE_PX },
-            sizeProp: 'large',
-        };
-    }
-    return { sizeStyle: { width: size, height: size } };
-}
-export function renderActivityIndicator(view, platform) {
-    const { sizeStyle, sizeProp } = resolveSize(view.size);
-    dlog(sizeProp !== undefined
-        ? `ActivityIndicator size '${sizeProp}' -> native size enum '${sizeProp}'`
-        : `ActivityIndicator size ${String(view.size)} -> style only, native size not set`);
-    const nativeProps = {
-        animating: view.animating,
-        hidesWhenStopped: view.hidesWhenStopped,
-        style: sizeStyle,
-        ...platform.nativeExtras,
-    };
-    // Omit color entirely when neither given nor defaulted (Android's theme default is
-    // null); a null color prop would be rejected by Fabric's color parser.
-    const resolvedColor = view.color ?? platform.defaultColor;
-    if (resolvedColor !== null)
-        nativeProps.color = resolvedColor;
-    if (sizeProp !== undefined)
-        nativeProps.size = sizeProp;
-    dlog('ActivityIndicator -> RCTView(spinner)');
-    const wrapperProps = {
-        ...view.passthrough,
-        style: [CONTAINER_STYLE, view.style],
-    };
-    return el('symbiote-view', wrapperProps, [
-        el('symbiote-activity-indicator', nativeProps),
-    ]);
-}

package/build/view/render-image-background.d.ts

@@ -1,9 +0,0 @@
-import { type IStyleProp, type IViewStyle } from '@symbiote-native/engine';
-import { type IDescriptor } from '../descriptor';
-import { type IImageViewProps } from './render-image';
-export type IImageBackgroundViewProps = {
-    style?: IStyleProp<IViewStyle>;
-    imageStyle?: IStyleProp<IViewStyle>;
-    image: IImageViewProps;
-};
-export declare function renderImageBackground(view: IImageBackgroundViewProps): IDescriptor;

package/build/view/render-image-background.js

@@ -1,48 +0,0 @@
-// ImageBackground: the render half (framework-agnostic). Pure JS composition, no native
-// component of its own (mirrors react-native/Libraries/Image/ImageBackground.js): an outer
-// View receives the wrapper `style`; an absolutely-filled Image sits behind it; the user's
-// `children` paint on top (as siblings AFTER the image in the wrapper's child order, injected
-// by the adapter). Shared verbatim across adapters: React and Vue both bridge this Descriptor.
-//
-// The inner Image is positioned absolute-fill and has the wrapper's width/height reapplied:
-// RN's Image overwrites its own width/height from the source's intrinsic size, which would
-// fight the wrapper's explicit dimensions, so we proxy them back onto the Image so it fills
-// the box. `imageStyle` wins last.
-import { dlog, flattenStyle, } from '@symbiote-native/engine';
-import { el } from '../descriptor.js';
-import { renderImage } from './render-image/index.js';
-// The inner Image's positioning: absolute-fill behind the wrapper's children.
-const IMAGE_BACKGROUND_ABSOLUTE_FILL = {
-    position: 'absolute',
-    left: 0,
-    right: 0,
-    top: 0,
-    bottom: 0,
-};
-// Read one explicit dimension off the (already-flattened) wrapper style. A dp number or a
-// percentage string is a valid IDimensionValue; anything else (auto / undefined) yields undefined.
-function readDimension(style, key) {
-    const value = Object.hasOwn(style, key) ? Reflect.get(style, key) : undefined;
-    if (typeof value === 'number' || typeof value === 'string')
-        return value;
-    return undefined;
-}
-export function renderImageBackground(view) {
-    // Flatten only to read the wrapper's explicit dimensions; RN copies these onto the Image so
-    // it fills the box rather than collapsing to the source's intrinsic size. `imageStyle` last.
-    const flattenedWrapper = flattenStyle(view.style);
-    const imageMergedStyle = [
-        IMAGE_BACKGROUND_ABSOLUTE_FILL,
-        {
-            width: readDimension(flattenedWrapper, 'width'),
-            height: readDimension(flattenedWrapper, 'height'),
-        },
-        view.imageStyle,
-    ];
-    dlog('ImageBackground -> View(RCTView) > Image(RCTImageView absolute-fill) + children');
-    // The wrapper View holds the inner Image as its only structural child; the adapter appends
-    // the user children after it (so they paint on top).
-    return el('symbiote-view', { style: view.style }, [
-        renderImage({ ...view.image, style: imageMergedStyle }),
-    ]);
-}

package/build/view/render-text-input.d.ts

@@ -1,11 +0,0 @@
-import type { IDescriptor } from '../descriptor';
-import type { IFoldedTextInputProps, ITextInputSelection } from '../state/text-input';
-export type ITextInputViewProps = {
-    multiline: boolean;
-    text: string | undefined;
-    mostRecentEventCount: number;
-    selection?: ITextInputSelection;
-    folded: IFoldedTextInputProps;
-    passthrough: Record<string, unknown>;
-};
-export declare function renderTextInput(view: ITextInputViewProps): IDescriptor;

package/build/view/render-text-input.js

@@ -1,39 +0,0 @@
-// TextInput: the render half (framework-agnostic). Picks the intrinsic (single- vs multiline)
-// and maps the resolved props onto it: the controlled value rides as the private `text` prop
-// plus `mostRecentEventCount`, the W3C/alias folds arrive pre-resolved in `folded`, and the
-// ref + the change/focus/blur handlers + every pass-through prop (accessibility, testID, the
-// remaining native events) arrive folded into `passthrough` and land on the host untouched.
-// Pure and prop-driven; no hooks, no events. The adapter owns those.
-import { dlog } from '@symbiote-native/engine';
-import { el } from '../descriptor.js';
-// One host element per native input class. Text carries the only non-trivial nesting elsewhere;
-// here the choice is binary and runtime (the `multiline` prop), so the module stays flat.
-// The `-managed` spelling, NOT the plain one the lowering transforms emit. Both resolve to the
-// same native view; the tag is what decides whether the engine's TextInput machine attaches, and
-// on this path the adapter's own lifecycle already owns that state. Sharing the tag would run both
-// copies at once. Full reasoning in `component-names/shared.ts`.
-const SINGLELINE_INTRINSIC = 'symbiote-text-input-managed';
-const MULTILINE_INTRINSIC = 'symbiote-text-input-multiline-managed';
-export function renderTextInput(view) {
-    const intrinsic = view.multiline ? MULTILINE_INTRINSIC : SINGLELINE_INTRINSIC;
-    dlog(`TextInput render multiline=${String(view.multiline)} ` +
-        `text=${JSON.stringify(view.text)} count=${view.mostRecentEventCount}`);
-    const props = {
-        ...view.passthrough,
-        text: view.text,
-        mostRecentEventCount: view.mostRecentEventCount,
-        selection: view.selection,
-        keyboardType: view.folded.keyboardType,
-        returnKeyType: view.folded.returnKeyType,
-        editable: view.folded.editable,
-        submitBehavior: view.folded.submitBehavior,
-        selectionColor: view.folded.selectionColor,
-        cursorColor: view.folded.cursorColor,
-        selectionHandleColor: view.folded.selectionHandleColor,
-        underlineColorAndroid: view.folded.underlineColorAndroid,
-        autoComplete: view.folded.autoComplete,
-        textContentType: view.folded.textContentType,
-        showSoftInputOnFocus: view.folded.showSoftInputOnFocus,
-    };
-    return el(intrinsic, props);
-}