@symbiote-native/engine 0.1.3 → 0.1.5

package/build/style-registry/index.js

@@ -1,17 +1,16 @@
 // Runtime style registry. Side-effect CSS imports (compiled by the sibling CSS-to-style
 // build package, not this module) call registerStyles() with camelCase keys; components
-// look them up by resolveClassName(). No CSS parsing happens here — this is a
-// Map<string, ...> lookup, nothing more.
+// look them up via resolveClassName(). No CSS parsing here - just a Map<string, ...> lookup.
 //
-// This registry has no Tailwind-utility detection layer — this repo's style surface has
-// no Tailwind layer, so the compound lookup below always runs for 2-4-part class strings
-// instead of being gated behind "no part looks like a utility class".
+// No Tailwind-utility detection layer: this repo's style surface has no Tailwind layer,
+// so the compound lookup below always runs for 2-4-part class strings instead of being
+// gated behind "no part looks like a utility class".
 //
 // kebab-case authoring: a CSS selector `.section-label` always registers under the
 // camelCase key `sectionLabel` (@symbiote-native/css-parser's extractClassName), so a template
-// can write EITHER `class="sectionLabel"` OR `class="section-label"` — resolveOne below
-// falls back to the kebab->camel form on a miss. The fallback matters because assuming
-// authors would always match the camelCase key exactly proved wrong in practice.
+// can write EITHER `class="sectionLabel"` OR `class="section-label"` - resolveOne below
+// falls back to the kebab->camel form on a miss, since authors don't reliably write the
+// exact camelCase key.
 // Compound lookup tries every ordering of 2-4 space-separated class parts joined by
 // '.' (e.g. "btn primary" -> "btn.primary" / "primary.btn") before falling back to a
 // per-class merge, mirroring CSS compound-selector registration (`.btn.primary { }`).
@@ -25,14 +24,14 @@ export function registerStyles(styles) {
         globalStyles.set(name, style);
     }
 }
-// Clears every registration; used between tests for isolation.
+// Used between tests to reset registry state.
 export function clearGlobalStyles() {
     globalStyles.clear();
 }
 // A `class`/`className` prop arrives as `unknown` at the routeProp boundary (any adapter can
 // hand over anything); this narrows before resolveClassName without an `as` cast. Shared with
 // adapters/vue/src/components/scroll-view/shared.ts's identical need, rather than each keeping
-// its own copy — that file imports this one instead of redeclaring it.
+// its own copy - that file imports this one instead of redeclaring it.
 export function isClassNameValue(value) {
     return typeof value === 'string' || (typeof value === 'object' && value !== null);
 }
@@ -101,10 +100,14 @@ function capitalize(value) {
 }
 // Duplicated from @symbiote-native/css-parser's identical helper rather than imported: css-parser
 // pulls in postcss and is build-time only (never shipped in the app bundle), and this registry
-// is the opposite — pure runtime, in every app bundle — so importing it here would leak a
+// is the opposite - pure runtime, in every app bundle - so importing it here would leak a
 // build-time dependency into the shipped app. The conversion itself is two lines; keeping both
 // copies in sync is a smaller cost than the alternative.
-function kebabToCamel(value) {
+//
+// Exported (not just local to this file) because ./scope.ts's Vue `<style scoped>` name
+// rewriter needs the same kebab->camel normalization and is a different responsibility living
+// in a sibling module - see that file's own doc comment for why it's split out of this one.
+export function kebabToCamel(value) {
     return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 }
 function tryCompoundLookup(parts) {
@@ -123,39 +126,3 @@ function resolveOne(name) {
         return {};
     return globalStyles.get(trimmed) ?? globalStyles.get(kebabToCamel(trimmed)) ?? {};
 }
-// Pure NAME rewriter for Vue `<style scoped>`: suffixes every class token that this
-// file's scoped block locally defines with `__${scopeId}`, leaving unrecognized tokens
-// (globals, external classes) untouched. Runs at the compiled call site BEFORE Vue's own
-// normalizeClass() collapses string/object/array `class` values to a final string, so it
-// must pre-process all three shapes normalizeClass understands. No registry lookup here —
-// resolveClassName still does the actual style lookup, unchanged, against the rewritten name.
-export function scopeClassName(value, localNames, scopeId) {
-    if (value === undefined || value === null)
-        return value;
-    if (Array.isArray(value)) {
-        return value.map(item => scopeClassEntry(item, localNames, scopeId));
-    }
-    return scopeClassEntry(value, localNames, scopeId);
-}
-// A token arrives as either the camelCase registry key (`sectionLabel`) or its kebab-case
-// authoring form (`section-label`) — normalize to camelCase FIRST, then decide scoping, so
-// `localNames` (always camelCase, built from the css-parser's registered keys) recognizes a
-// kebab-written token. The emitted (possibly suffixed) name is always the camelCase form.
-function scopeToken(token, localNames, scopeId) {
-    const camelToken = kebabToCamel(token);
-    return localNames.has(camelToken) ? `${camelToken}__${scopeId}` : camelToken;
-}
-function scopeClassEntry(value, localNames, scopeId) {
-    if (typeof value === 'object') {
-        const scoped = {};
-        for (const [name, enabled] of Object.entries(value)) {
-            scoped[scopeToken(name, localNames, scopeId)] = enabled;
-        }
-        return scoped;
-    }
-    return value
-        .split(/\s+/)
-        .filter(Boolean)
-        .map(token => scopeToken(token, localNames, scopeId))
-        .join(' ');
-}

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

@@ -0,0 +1,3 @@
+export type IClassToggleMap = Record<string, boolean | undefined>;
+export type IScopableClassValue = string | IClassToggleMap | Array<string | IClassToggleMap> | undefined | null;
+export declare function scopeClassName(value: IScopableClassValue, localNames: ReadonlySet<string>, scopeId: string): IScopableClassValue;

package/build/style-registry/scope.js

@@ -0,0 +1,41 @@
+// Vue `<style scoped>` class-name rewriter. Distinct responsibility from the sibling
+// ./index.ts (the CSS class -> style registry): this module does pure NAME rewriting,
+// no registry lookup, no CSS parsing. It runs at the compiled call site of a Vue SFC's
+// scoped-style template - `adapters/vue/metro-vue-transformer.cjs` emits calls to
+// scopeClassName (imported there as `__scopeClass`) - BEFORE Vue's own normalizeClass()
+// collapses string/object/array `class` values to a final string, so it must pre-process
+// all three shapes normalizeClass understands. resolveClassName in ./index.ts still does
+// the actual style lookup, unchanged, against the rewritten (possibly suffixed) name.
+import { kebabToCamel } from './index.js';
+// Suffixes every class token that this file's scoped block locally defines with
+// `__${scopeId}`, leaving unrecognized tokens (globals, external classes) untouched.
+export function scopeClassName(value, localNames, scopeId) {
+    if (value === undefined || value === null)
+        return value;
+    if (Array.isArray(value)) {
+        return value.map(item => scopeClassEntry(item, localNames, scopeId));
+    }
+    return scopeClassEntry(value, localNames, scopeId);
+}
+// A token arrives as either the camelCase registry key (`sectionLabel`) or its kebab-case
+// authoring form (`section-label`) - normalize to camelCase FIRST, then decide scoping, so
+// `localNames` (always camelCase, built from the css-parser's registered keys) recognizes a
+// kebab-written token. The emitted (possibly suffixed) name is always the camelCase form.
+function scopeToken(token, localNames, scopeId) {
+    const camelToken = kebabToCamel(token);
+    return localNames.has(camelToken) ? `${camelToken}__${scopeId}` : camelToken;
+}
+function scopeClassEntry(value, localNames, scopeId) {
+    if (typeof value === 'object') {
+        const scoped = {};
+        for (const [name, enabled] of Object.entries(value)) {
+            scoped[scopeToken(name, localNames, scopeId)] = enabled;
+        }
+        return scoped;
+    }
+    return value
+        .split(/\s+/)
+        .filter(Boolean)
+        .map(token => scopeToken(token, localNames, scopeId))
+        .join(' ');
+}

package/build/touch-history.d.ts

@@ -0,0 +1,23 @@
+interface ITouchRecord {
+    touchActive: boolean;
+    startPageX: number;
+    startPageY: number;
+    startTimeStamp: number;
+    currentPageX: number;
+    currentPageY: number;
+    currentTimeStamp: number;
+    previousPageX: number;
+    previousPageY: number;
+    previousTimeStamp: number;
+}
+interface ITouchHistory {
+    touchBank: ITouchRecord[];
+    numberActiveTouches: number;
+    indexOfSingleActiveTouch: number;
+    mostRecentTimeStamp: number;
+}
+export declare const touchHistory: ITouchHistory;
+export declare function recordTouchTrack(kind: 'start' | 'move' | 'end', nativeEvent: Record<string, unknown>): void;
+export declare function resetTouchHistory(): void;
+export declare function attachTouchHistory(nativeEvent: Record<string, unknown>): void;
+export {};

package/build/touch-history.js

@@ -0,0 +1,150 @@
+// Per-touch position/time tracking, ported from RN's
+// react-native-renderer/.../legacy-events/ResponderTouchHistoryStore.js. PanResponder's
+// multitouch dx/vx math needs each touch's own previous->current delta (RN counts only
+// touches that moved since `_accountsForMovesUpTo`), which a grant-relative centroid of
+// ALL live touches cannot reconstruct. We maintain the bank as touches flow and ATTACH
+// `touchHistory` onto the nativeEvent reaching responder handlers, exactly how
+// ResponderEventPlugin.js sets `*.touchHistory`.
+//
+// events/index.ts consumes only this file's public surface (recordTouchTrack,
+// attachTouchHistory, resetTouchHistory, touchHistory); everything else here is a
+// private implementation detail of the bank.
+import { isRecord } from './type-guards.js';
+// RN's bank is indexed by touch identifier and warns above 20; we never warn (headless
+// events may carry larger or absent ids), we just skip anything out of a sane range.
+const MAX_TOUCH_BANK = 20;
+const touchBank = [];
+export const touchHistory = {
+    touchBank,
+    numberActiveTouches: 0,
+    indexOfSingleActiveTouch: -1,
+    mostRecentTimeStamp: 0,
+};
+function toFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+// Pull a recordable touch out of an untyped entry. RN's getTouchIdentifier throws on
+// a null id; we skip instead, so events without touch geometry leave the bank untouched.
+function normalizeTouch(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const identifier = toFiniteNumber(raw.identifier);
+    const pageX = toFiniteNumber(raw.pageX);
+    const pageY = toFiniteNumber(raw.pageY);
+    if (identifier === undefined || pageX === undefined || pageY === undefined)
+        return undefined;
+    if (identifier < 0 || identifier > MAX_TOUCH_BANK)
+        return undefined;
+    return { identifier, pageX, pageY, timestamp: toFiniteNumber(raw.timestamp) ?? 0 };
+}
+// The changed touches for this frame (start/move/end), defensively read.
+function changedTouchesOf(nativeEvent) {
+    const raw = nativeEvent.changedTouches;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const touch = normalizeTouch(entry);
+        if (touch !== undefined)
+            out.push(touch);
+    }
+    return out;
+}
+// Count of all touches still down (RN reads nativeEvent.touches.length directly).
+function activeTouchCount(nativeEvent) {
+    const raw = nativeEvent.touches;
+    return Array.isArray(raw) ? raw.length : 0;
+}
+function recordTouchStart(touch) {
+    const record = touchBank[touch.identifier];
+    if (record) {
+        record.touchActive = true;
+        record.startPageX = touch.pageX;
+        record.startPageY = touch.pageY;
+        record.startTimeStamp = touch.timestamp;
+        record.currentPageX = touch.pageX;
+        record.currentPageY = touch.pageY;
+        record.currentTimeStamp = touch.timestamp;
+        record.previousPageX = touch.pageX;
+        record.previousPageY = touch.pageY;
+        record.previousTimeStamp = touch.timestamp;
+    }
+    else {
+        touchBank[touch.identifier] = {
+            touchActive: true,
+            startPageX: touch.pageX,
+            startPageY: touch.pageY,
+            startTimeStamp: touch.timestamp,
+            currentPageX: touch.pageX,
+            currentPageY: touch.pageY,
+            currentTimeStamp: touch.timestamp,
+            previousPageX: touch.pageX,
+            previousPageY: touch.pageY,
+            previousTimeStamp: touch.timestamp,
+        };
+    }
+    touchHistory.mostRecentTimeStamp = touch.timestamp;
+}
+// Move and end share the previous<-current shift; only `touchActive` differs.
+function shiftTouchRecord(touch, active) {
+    const record = touchBank[touch.identifier];
+    if (!record)
+        return;
+    record.touchActive = active;
+    record.previousPageX = record.currentPageX;
+    record.previousPageY = record.currentPageY;
+    record.previousTimeStamp = record.currentTimeStamp;
+    record.currentPageX = touch.pageX;
+    record.currentPageY = touch.pageY;
+    record.currentTimeStamp = touch.timestamp;
+    touchHistory.mostRecentTimeStamp = touch.timestamp;
+}
+function arrayFirst(value) {
+    return Array.isArray(value) ? value[0] : undefined;
+}
+// Maintain the bank as a touch frame flows. Mirrors RN's recordTouchTrack: moveish
+// shifts records, startish records + recomputes numberActiveTouches, endish marks the
+// record inactive + rescans for the single remaining touch. `kind` is the touch phase.
+export function recordTouchTrack(kind, nativeEvent) {
+    if (kind === 'move') {
+        for (const touch of changedTouchesOf(nativeEvent))
+            shiftTouchRecord(touch, true);
+        return;
+    }
+    if (kind === 'start') {
+        for (const touch of changedTouchesOf(nativeEvent))
+            recordTouchStart(touch);
+        touchHistory.numberActiveTouches = activeTouchCount(nativeEvent);
+        if (touchHistory.numberActiveTouches === 1) {
+            const first = normalizeTouch(arrayFirst(nativeEvent.touches));
+            touchHistory.indexOfSingleActiveTouch = first?.identifier ?? -1;
+        }
+        return;
+    }
+    for (const touch of changedTouchesOf(nativeEvent))
+        shiftTouchRecord(touch, false);
+    touchHistory.numberActiveTouches = activeTouchCount(nativeEvent);
+    if (touchHistory.numberActiveTouches === 1) {
+        for (let i = 0; i < touchBank.length; i++) {
+            const record = touchBank[i];
+            if (record !== undefined && record.touchActive) {
+                touchHistory.indexOfSingleActiveTouch = i;
+                break;
+            }
+        }
+    }
+}
+// Drop all touch state. Called on a fully-released / cancelled gesture so a stale bank
+// never leaks geometry into the next gesture's first frame.
+export function resetTouchHistory() {
+    touchBank.length = 0;
+    touchHistory.numberActiveTouches = 0;
+    touchHistory.indexOfSingleActiveTouch = -1;
+    touchHistory.mostRecentTimeStamp = 0;
+}
+// Attach the live touch history onto the event the responder handlers receive, matching
+// ResponderEventPlugin.js (`grantEvent.touchHistory = ...`, etc.). PanResponder reads
+// it for the per-touch dx/vx math; handlers that ignore it are unaffected.
+export function attachTouchHistory(nativeEvent) {
+    nativeEvent.touchHistory = touchHistory;
+}

package/build/type-guards.d.ts

@@ -0,0 +1,4 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isBoolean(value: unknown): value is boolean;
+export declare function isNumber(value: unknown): value is number;
+export declare function isString(value: unknown): value is string;

package/build/type-guards.js

@@ -0,0 +1,15 @@
+// Runtime guards to narrow `unknown` at trust boundaries (native payloads, ViewConfig
+// attributes, style values) without an `as` cast. `isRecord` excludes arrays - most
+// call sites mean "a native payload keyed by string," never a list.
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isBoolean(value) {
+    return typeof value === 'boolean';
+}
+export function isNumber(value) {
+    return typeof value === 'number';
+}
+export function isString(value) {
+    return typeof value === 'string';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/engine",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "SymbioteNative's retained shadow-tree engine — clone-on-write commit path + event normalization over React Native Fabric, shared by every framework adapter.",
   "repository": {
     "type": "git",
@@ -32,7 +32,7 @@
     "react-native": ">=0.86"
   },
   "devDependencies": {
-    "@symbiote-native/test-utils": "0.1.3"
+    "@symbiote-native/test-utils": "0.1.5"
   },
   "scripts": {
     "typecheck": "tsc --build",