@symbiote-native/engine 0.3.0 → 0.4.0

package/build/style-registry/index.d.ts

@@ -12,5 +12,7 @@ export interface IStyleRule {
 export declare function registerRules(rules: readonly IStyleRule[]): void;
 export declare function clearGlobalStyles(): void;
 export declare function isClassNameValue(value: unknown): value is IClassNameValue;
+export declare function canonicalClassName(className: IClassNameValue): IClassNameValue;
 export declare function resolveClassName(className: IClassNameValue): IResolvedStyle;
+export declare function resolveActiveClassName(className: IClassNameValue): IResolvedStyle;
 export {};

package/build/style-registry/index.js

@@ -61,16 +61,40 @@ const resolvedCache = new Map();
 // Overflow drops everything rather than evicting one entry: the cache is a warm-up optimization,
 // not a working set, and an LRU's bookkeeping costs more than the rebuild it saves.
 const RESOLVED_CACHE_LIMIT = 512;
+// The pressed variant, keyed by the SAME authored string. Separate from `resolvedCache` so the two
+// can never collide on one key, and string-keyed for the same reason that one is: identity is the
+// whole point. `isAlreadyPublished` (node.ts) turns a re-push away by comparing slot 0 with
+// Object.is, so a thousand unpressed rows only cost zero writes if they all publish the SAME
+// object. Resolve an array or an object instead and every call returns a fresh one, the guard can
+// never fire, and the re-push storm it was added for comes back with a new cause.
+//
+// This doubles the distinct strings a screen can hold. A SECOND state would multiply them, and the
+// cache clears WHOLE on overflow rather than evicting — so a drop breaks identity for every node at
+// once. That is the wall a `:focus` or `:hover` would hit, and it would read as an unexplained
+// regression rather than as a cache limit.
+const activeCache = new Map();
+// The token the css-parser emits for `:active` (its `STATE_TOKEN`). Duplicated as a literal rather
+// than imported: the engine does not depend on the parser, and a CSS identifier cannot carry an
+// unescaped `:`, so this can never collide with a real class name.
+const STATE_TOKEN = ':active';
+// Whether ANY registered rule carries the state token. Not derivable from `ruleIndex`, which hooks
+// a rule on `tokens[0]` — for `.btn:active` that is `btn`, so `ruleIndex.has(':active')` is always
+// false and a gate built on it silently disables the whole feature. Found by a test, not by
+// reading: the wrong gate makes pressing a no-op with everything green.
+let hasActiveRules = false;
 // Every registration is a cascade change, so nothing resolved before it can be trusted. Clearing
 // wholesale beats versioning each entry — registration happens at import time, resolution happens
 // per commit, and only the second one is hot.
 function invalidateResolved() {
     resolvedCache.clear();
+    activeCache.clear();
 }
 export function registerRules(rules) {
     invalidateResolved();
     const epoch = ruleEpoch++;
     for (const rule of rules) {
+        if (rule.tokens.includes(STATE_TOKEN))
+            hasActiveRules = true;
         const hook = rule.tokens[0];
         // The empty set is a subset of every element's tokens, so a token-less rule would paint
         // everything. It names no class and can only come from a broken compile.
@@ -87,6 +111,7 @@ export function registerRules(rules) {
 // Used between tests to reset registry state.
 export function clearGlobalStyles() {
     ruleIndex.clear();
+    hasActiveRules = false;
     ruleEpoch = 0;
     invalidateResolved();
 }
@@ -97,6 +122,26 @@ export function clearGlobalStyles() {
 export function isClassNameValue(value) {
     return (typeof value === 'string' || (typeof value === 'object' && value !== null));
 }
+// An ARRAY of plain strings joined into one, so it takes the memoised string path like any other
+// class. Everything downstream keys off identity — `resolveClassName`'s cache, the `:active`
+// variant, and `isAlreadyPublished`'s Object.is on slot 0 — and the array branch below reduces
+// into a FRESH object on every call, so an array class silently opted out of all three: no pressed
+// styling, and a re-push that re-dirties the node on every update.
+//
+// Only an ALL-STRING array converts. A mixed array carries IResolvedStyle entries — the channel
+// ScrollView / VirtualizedList / FlatList / ImageBackground use to pass a style through the class
+// prop — and those are not tokens; folding them into a string would be a category error rather
+// than a fix. No adapter produces an all-string array today (Vue's createVNode normalises class to
+// a string, Angular joins its accumulated tokens, React's className is a string by convention), so
+// this closes a gap an APPLICATION can reach rather than one we can.
+export function canonicalClassName(className) {
+    if (typeof className === 'string' || !Array.isArray(className)) {
+        return className;
+    }
+    return className.every(part => typeof part === 'string')
+        ? className.join(' ')
+        : className;
+}
 export function resolveClassName(className) {
     if (!className)
         return {};
@@ -104,6 +149,11 @@ export function resolveClassName(className) {
         return className;
     }
     if (Array.isArray(className)) {
+        // Direct callers (an adapter resolving a class prop itself) get the same canonicalisation as
+        // routeProp's path, so an all-string array is memoised for them too.
+        const canonical = canonicalClassName(className);
+        if (typeof canonical === 'string')
+            return resolveClassName(canonical);
         return className.reduce((acc, item) => {
             return { ...acc, ...resolveClassName(item) };
         }, {});
@@ -117,6 +167,35 @@ export function resolveClassName(className) {
     resolvedCache.set(className, resolved);
     return resolved;
 }
+// The same element's style with `:active` added to its token list — so a `.btn:active` rule joins
+// the cascade exactly as its specificity says, merged by the SAME matcher. That makes the result a
+// complete REPLACEMENT for the unpressed style rather than an overlay, which is why no extra style
+// slot is needed on the node: pressing swaps what sits in slot 0.
+//
+// Non-string input resolves to the plain style, unchanged. An object or array has no stable key to
+// cache under, and the guard above is worthless without one.
+export function resolveActiveClassName(className) {
+    if (typeof className !== 'string')
+        return resolveClassName(className);
+    // No `:active` rule anywhere in the app — hand back the very SAME object the unpressed path
+    // returns, not an equal one. Two cache keys give two objects even when their contents are
+    // byte-identical, and `isAlreadyPublished` compares with Object.is: pressing a node that has no
+    // pressed styling would otherwise publish a fresh base, dirty the node and pay a walk for a
+    // payload Fabric then rejects as unchanged. One node rather than a thousand, so not a storm —
+    // but it is a cost for literally nothing, and this makes the whole feature free for every app
+    // that does not use it.
+    if (!hasActiveRules)
+        return resolveClassName(className);
+    const cached = activeCache.get(className);
+    if (cached !== undefined)
+        return cached;
+    const parts = className.trim().split(/\s+/).filter(Boolean);
+    const resolved = parts.length === 0 ? {} : (matchRules([...parts, STATE_TOKEN]) ?? {});
+    if (activeCache.size >= RESOLVED_CACHE_LIMIT)
+        activeCache.clear();
+    activeCache.set(className, resolved);
+    return resolved;
+}
 function resolveClassString(className) {
     const parts = className.trim().split(/\s+/).filter(Boolean);
     if (parts.length === 0)

package/build/surface.js

@@ -4,7 +4,7 @@
 import { commitChildren } from './commit.js';
 import { dlog } from './debug.js';
 import { installEventHandler } from './events/index.js';
-import { markDirty } from './node.js';
+import { markStructureDirty } from './node.js';
 export class SymbioteSurface {
     rootTag;
     children = [];
@@ -48,16 +48,19 @@ export class SymbioteSurface {
         });
     }
     // Splices `parent.children` directly instead of going through node.ts's removeChild, so it
-    // owes the same dirty-mark - otherwise a node pulled out of a subtree here leaves that subtree
-    // looking clean and the commit walk skips right over the hole.
+    // owes the same marks - otherwise a node pulled out of a subtree here leaves that subtree
+    // looking clean and the commit walk skips right over the hole, and commitTargeted would rebuild
+    // that parent's child set from a snapshot that still contains the removed node.
     detach(child) {
         const parent = child.parent;
         if (parent) {
+            // Marks before the splice, like node.ts's own structural ops: the committed record may be
+            // aliasing `parent.children`, and this call is what copies it out of the way.
+            markStructureDirty(parent);
             const index = parent.children.indexOf(child);
             if (index >= 0)
                 parent.children.splice(index, 1);
             child.parent = undefined;
-            markDirty(parent);
             return;
         }
         const topIndex = this.children.indexOf(child);

package/build/view-config.js

@@ -30,6 +30,12 @@ const BASE_EVENTS = [
     'press',
     'pressIn',
     'pressOut',
+    // Synthesized from the touch stream like its four siblings, and omitted here until 2026-09-02.
+    // A name the press machine OWNS but the engine does not route is dead on the lowered path only:
+    // `routeProp` hands an `on*` prop to `setEventListener` (and thus to the behavior's stash) only
+    // for a registered event, so `onPressMove` landed in `node.props` where nothing reads it, while
+    // a wrapper passes the same callback to the machine directly and stayed correct.
+    'pressMove',
     'longPress',
     'layout',
     'focus',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/engine",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "SymbioteNative's retained shadow-tree engine — clone-on-write commit path + event normalization over React Native Fabric, shared by every framework adapter.",
   "license": "MIT",
   "repository": {
@@ -17,6 +17,16 @@
   "main": "./build/index.js",
   "module": "./build/index.js",
   "types": "./build/index.d.ts",
+  "keywords": [
+    "react-native",
+    "symbiote-native",
+    "fabric",
+    "shadow-tree",
+    "renderer-core",
+    "jsi",
+    "yoga",
+    "cross-platform"
+  ],
   "exports": {
     ".": {
       "types": "./build/index.d.ts",
@@ -33,7 +43,7 @@
     "react-native": ">=0.86"
   },
   "devDependencies": {
-    "@symbiote-native/test-utils": "0.2.0"
+    "@symbiote-native/test-utils": "0.3.0"
   },
   "scripts": {
     "typecheck": "tsc --build",