@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/scrollValues.ts

@@ -0,0 +1,260 @@
+// REQ-API-037 — pure scroll-fed value helpers (pin setProgress / createScrollUpdater law).
+// RN-free so node-side probes and the hook share one authority: progress is offset / maxOffset
+// (zero range → 0), and applying offsets writes the four motion values without a React render.
+
+import { describeValue, type MotionValue } from '@unrulysystems/native-motion-core'
+
+export const USE_SCROLL_OWNER = 'useScroll' as const
+
+export interface ScrollMotionValues {
+  readonly scrollX: MotionValue<number>
+  readonly scrollY: MotionValue<number>
+  readonly scrollXProgress: MotionValue<number>
+  readonly scrollYProgress: MotionValue<number>
+}
+
+export interface ScrollOffsets {
+  readonly xOffset: number
+  readonly yOffset: number
+  readonly xMaxOffset: number
+  readonly yMaxOffset: number
+}
+
+/** Pin setProgress: zero offset OR zero max → 0; else offset / maxOffset (0→1). */
+export function scrollProgress(offset: number, maxOffset: number): number {
+  return !offset || !maxOffset ? 0 : offset / maxOffset
+}
+
+export function applyScrollOffsets(values: ScrollMotionValues, offsets: ScrollOffsets): void {
+  values.scrollX.set(offsets.xOffset)
+  values.scrollY.set(offsets.yOffset)
+  values.scrollXProgress.set(scrollProgress(offsets.xOffset, offsets.xMaxOffset))
+  values.scrollYProgress.set(scrollProgress(offsets.yOffset, offsets.yMaxOffset))
+}
+
+export type ScrollSourceKind = 'missing' | 'pending' | 'non-scrollable' | 'scrollable'
+
+/**
+ * Duck-type a hydrated host as scrollable: RN ScrollView exposes `scrollTo`; animated refs
+ * expose `getScrollableNode` / native tags. A plain View has none of these.
+ */
+export function classifyScrollSource(node: unknown): ScrollSourceKind {
+  if (node === null || node === undefined) return 'missing'
+  if (typeof node !== 'object') return 'non-scrollable'
+  const candidate = node as Record<string, unknown>
+  if (typeof candidate.scrollTo === 'function') return 'scrollable'
+  if (typeof candidate.getScrollableNode === 'function') return 'scrollable'
+  if (typeof candidate.scrollToOffset === 'function') return 'scrollable'
+  // AnimatedRef current often wraps the host; accept observe-capable refs at the ref level
+  // (checked separately) and treat a host with native tag methods as scrollable.
+  if (typeof candidate.getNativeScrollRef === 'function') return 'scrollable'
+  return 'non-scrollable'
+}
+
+export interface UseScrollOptions {
+  readonly container?: { readonly current: unknown } | null | undefined
+  /**
+   * Pin intersection-target progress. Native refuses this option this rung (deferred
+   * capability) — never silently ignored. Web forwards to the pin.
+   */
+  readonly target?: { readonly current: unknown } | null | undefined
+  readonly axis?: 'x' | 'y' | undefined
+  /**
+   * Pin scroll-offset intersection list. Native refuses this option this rung (deferred
+   * capability — container progress is always offset/maxOffset). Web forwards to the pin.
+   */
+  readonly offset?: readonly unknown[] | undefined
+}
+
+const ACCEPTED_OPTION_KEYS = new Set(['container', 'target', 'axis', 'offset'])
+
+export interface ScrollGate {
+  readonly severity: 'development' | 'production'
+  readonly report: (error: Error) => void
+}
+
+export function refuseScroll(gate: ScrollGate, message: string): void {
+  const error = new Error(message)
+  if (gate.severity === 'development') throw error
+  gate.report(error)
+}
+
+/**
+ * Native entry-gate for useScroll options. Pin vocabulary keys are accepted at the key
+ * level so unknown keys still fail loud; `target` / `offset` are then refused as deferred
+ * capabilities (never silently no-op — major c4a8f2e91b03). Web has its own gate and
+ * forwards both to the pin.
+ */
+export function gateUseScrollOptions(
+  options: Readonly<Record<string, unknown>> | undefined,
+  gate: ScrollGate,
+): UseScrollOptions {
+  if (options === undefined || options === null) return {}
+  if (typeof options !== 'object' || Array.isArray(options)) {
+    refuseScroll(
+      gate,
+      `${USE_SCROLL_OWNER}: options must be a plain object (REQ-API-037) — got ${describeValue(options)}.`,
+    )
+    return {}
+  }
+  for (const key of Object.keys(options)) {
+    if (options[key] === undefined) continue
+    if (!ACCEPTED_OPTION_KEYS.has(key)) {
+      refuseScroll(
+        gate,
+        `${USE_SCROLL_OWNER}: option '${key}' is outside the contracted useScroll surface ` +
+          '(REQ-API-037: container/target/axis/offset) — it fails loud rather than silently doing nothing.',
+      )
+    }
+  }
+  // Deferred on native: intersection-target progress and pin offset ranges. Refusing here
+  // (not stripping) is the fail-loud law — deleting these refuses must fail the suite.
+  if (options.target !== undefined) {
+    refuseScroll(
+      gate,
+      `${USE_SCROLL_OWNER}: option 'target' (intersection-target progress) is a deferred ` +
+        'capability on the native entry — not implemented this rung (REQ-API-037). Use ' +
+        'container-only scroll progress, or the web entry which forwards target to the pin.',
+    )
+  }
+  if (options.offset !== undefined) {
+    refuseScroll(
+      gate,
+      `${USE_SCROLL_OWNER}: option 'offset' (scroll-offset ranges) is a deferred capability ` +
+        'on the native entry — not implemented this rung (REQ-API-037). Native container ' +
+        'progress is always offset/maxOffset; the web entry forwards offset to the pin.',
+    )
+  }
+  const axis = options.axis
+  if (axis !== undefined && axis !== 'x' && axis !== 'y') {
+    refuseScroll(
+      gate,
+      `${USE_SCROLL_OWNER}: invalid axis = ${describeValue(axis)} — expected "x" | "y" (REQ-API-037).`,
+    )
+  }
+  return {
+    ...(options.container !== undefined
+      ? { container: options.container as UseScrollOptions['container'] }
+      : {}),
+    ...(axis === 'x' || axis === 'y' ? { axis } : {}),
+  }
+}
+
+/**
+ * A container can bind on the UI thread only when the ref is a reanimated animated ref
+ * (`useAnimatedRef`) that exposes `observe` for native-tag registration.
+ */
+export function isBindableScrollContainer(container: unknown): boolean {
+  // useAnimatedRef is a callback function with `.observe` / `.current` — typeof is
+  // 'function', not 'object'. Rejecting non-objects made every real animated ref
+  // look like a plain ScrollView host (U7i device: unbindable refuse, y=0).
+  if (container === null || container === undefined) return false
+  if (typeof container !== 'object' && typeof container !== 'function') return false
+  return typeof (container as { observe?: unknown }).observe === 'function'
+}
+
+/**
+ * Resolve whether the call has a feedable scroll source. Native has no window viewport, so a
+ * call without a container is missing. A defined ref with null current is pending (hydrate later);
+ * a hydrated non-scrollable fails loud. Bindability (`observe`) is checked separately so the
+ * pure source classification stays host-shape only.
+ */
+export function resolveNativeScrollSource(
+  options: UseScrollOptions,
+  gate: ScrollGate,
+): { readonly kind: ScrollSourceKind; readonly node: unknown } {
+  const container = options.container
+  if (container === null || container === undefined) {
+    refuseScroll(
+      gate,
+      `${USE_SCROLL_OWNER}: native entry requires a container ref to a scrollable source ` +
+        '(there is no window viewport analog; REQ-API-037) — pass { container: scrollRef }.',
+    )
+    return { kind: 'missing', node: null }
+  }
+  const node = container.current
+  if (node === null || node === undefined) {
+    return { kind: 'pending', node: null }
+  }
+  const kind = classifyScrollSource(node)
+  if (kind === 'non-scrollable') {
+    refuseScroll(
+      gate,
+      `${USE_SCROLL_OWNER}: container.current is not a scrollable source ` +
+        `(got ${describeValue(node)}; expected a ScrollView / scrollable host — REQ-API-037).`,
+    )
+  }
+  return { kind, node }
+}
+
+/** Owned refusal when a hydrated container cannot register UI-thread scroll events. */
+export function refuseUnbindableScrollContainer(gate: ScrollGate): void {
+  refuseScroll(
+    gate,
+    `${USE_SCROLL_OWNER}: container must be a react-native-reanimated useAnimatedRef ` +
+      '(exposes observe) so scroll binds on the UI thread — a plain ScrollView / useRef cannot ' +
+      'register native scroll events (REQ-API-037). Pass useAnimatedRef(ScrollView).',
+  )
+}
+
+/** Pin-equivalent: container ref defined but never hydrated after the settle window. */
+export function refuseUnhydratedScrollContainer(gate: ScrollGate): void {
+  refuseScroll(
+    gate,
+    `${USE_SCROLL_OWNER}: container ref is defined but not hydrated (pin use-scroll-ref; ` +
+      'REQ-API-037) — attach the ref to a mounted scrollable host before useScroll settles.',
+  )
+}
+
+export type AnimatedScrollContainer = {
+  readonly current: unknown
+  observe?: (callback: (tag: number | null) => (() => void) | void) => () => void
+}
+
+/**
+ * Pin-equivalent settle for a provided container ref: unhydrated → refuse; hydrated without
+ * observe → refuse; observe → register via onTag. Pure so unit probes delete the refusal and
+ * go red without a React act AggregateError.
+ */
+export function settleNativeScrollBinding(
+  container: AnimatedScrollContainer,
+  gate: ScrollGate,
+  onTag: (tag: number) => (() => void) | void,
+): (() => void) | undefined {
+  // Bindable animated refs observe-wait even while current is null. useAnimatedRef.observe
+  // fires immediately with a null tag, then re-invokes once the host attaches. Refusing
+  // on that first null (or on a one-microtask window) drops the subscription before the
+  // tag exists, so device onScroll never reaches the value channel.
+  if (isBindableScrollContainer(container)) {
+    return container.observe!((tag) => {
+      if (tag === null || tag === undefined) return
+      const node = container.current
+      if (node === null || node === undefined) return
+      const kind = classifyScrollSource(node)
+      if (kind === 'non-scrollable') {
+        refuseScroll(
+          gate,
+          `${USE_SCROLL_OWNER}: container.current is not a scrollable source ` +
+            `(got ${describeValue(node)}; expected a ScrollView / scrollable host — REQ-API-037).`,
+        )
+        return
+      }
+      return onTag(tag)
+    })
+  }
+  if (container.current === null || container.current === undefined) {
+    refuseUnhydratedScrollContainer(gate)
+    return undefined
+  }
+  const kind = classifyScrollSource(container.current)
+  if (kind === 'non-scrollable') {
+    refuseScroll(
+      gate,
+      `${USE_SCROLL_OWNER}: container.current is not a scrollable source ` +
+        `(got ${describeValue(container.current)}; expected a ScrollView / scrollable host — REQ-API-037).`,
+    )
+    return undefined
+  }
+  refuseUnbindableScrollContainer(gate)
+  return undefined
+}

package/src/native/motion/serializablePayload.ts

@@ -0,0 +1,151 @@
+// The layout-animation crossing's payload law (iOS AUTO SIGABRT wedge investigation). Worklets'
+// SerializableObject::toJSValue recurses with NO cycle guard and NO memoization: a cyclic or
+// effectively unbounded record captured into a produced worklet does not fail at schedule time —
+// it pegs the main thread forever inside materialization (the soak's wedge stack:
+// SerializableObject::toJSValue recursing on the main-thread UI scheduler, process alive). Every
+// record handed to a produced worklet's closure must therefore be a FINITE, ACYCLIC graph of
+// primitives, plain records, arrays, Maps/Sets, and {value} cells — this walker is the boundary
+// assertion, run at the factory edge so a violating payload fails loud at the SOURCE (dev:
+// throw; prod: report + degrade) instead of pegging the UI scheduler two minutes into a walk.
+
+// Budgets sit orders of magnitude above the real produced payloads (tens of nodes) and orders
+// below anything that could keep a materialization busy: a payload past either bound is a bug,
+// never a legitimate config. The node budget counts EVERY visited entry (seal r12, F1 —
+// primitives included; seal r13, F1 — terminal functions and opaque branded leaves included):
+// Worklets' serializer recurses every container entry exactly like this walker, so a flat
+// container of 5,000 primitives, functions, or branded leaves is as unbounded as a deep graph.
+const MAX_PAYLOAD_NODES = 4096
+const MAX_PAYLOAD_DEPTH = 128
+
+// Genuinely branded host/shareable values — the ONLY payloads the worklets serializer passes
+// through without recursive descent, with its predicates matched EXACTLY (seal r5 F1, r6 F2):
+// - host objects and TurboModule-like objects carry the REANIMATED_MAGIC_KEY brand
+//   (serializable.native.ts:26-33 isHostObject / :57-60 isTurboModuleLike);
+// - __serializableRef === true — strict true (:35-45 isSerializableRef);
+// - __synchronizableRef — TRUTHY (isSynchronizable.ts:12);
+// - __workletContextObjectFactory — TRUTHY and only on a PLAIN object (:175).
+// NOT branded (and therefore walked): __shareableRef — isShareable.ts is only exported, the
+// serializer has no branch for it, so a plain record carrying the marker is recursively
+// serialized; __remoteFunction on a RECORD — the RemoteFunction identity applies inside
+// `isFunction` only (:152), and functions are handled by visit's own branch. A falsy marker
+// (false/null/0) brands NOTHING — the serializer recursively enumerates the record, cycle and
+// all — and every other unbranded object is traversed by this walker for the same reason (the
+// LEGACY path descends Object.entries at :813-820).
+const HOST_OBJECT_MAGIC_KEY = 'REANIMATED_MAGIC_KEY'
+
+function isOpaqueLeaf(value: object): boolean {
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return true
+  if (HOST_OBJECT_MAGIC_KEY in value) return true
+  const prototype = Object.getPrototypeOf(value) as object | null
+  if (prototype !== null && HOST_OBJECT_MAGIC_KEY in prototype) return true
+  const record = value as Record<string, unknown>
+  if (record['__serializableRef'] === true) return true
+  if (record['__synchronizableRef']) return true
+  return (
+    Object.getPrototypeOf(value) === Object.prototype && !!record['__workletContextObjectFactory']
+  )
+}
+
+/**
+ * Walk the payload graph; returns a short violation string naming the offending path
+ * (`cycle at …` / `budget at …`), or null when the payload is finite, acyclic, and in budget.
+ * Complexity is O(nodes visited) with early exit — the factory edge calls this per build, so the
+ * walk must never allocate unboundedly itself: the visiting set and node counter bound it.
+ */
+export function findUnsafeSerializablePayloadPath(root: unknown): string | null {
+  // `visiting` is the current-path set (cycle detection): an object already on the walk's own
+  // stack is a back-edge. DAG-shaped sharing (the same record referenced twice) is legal — the
+  // budget, not the set, bounds it — so nodes leave the set when their subtree completes.
+  const visiting = new Set<object>()
+  let nodes = 0
+
+  function visit(value: unknown, path: string, depth: number): string | null {
+    // Every visit counts BEFORE any terminal classification (seal r12 F1: primitives; seal r13
+    // F1: functions and opaque branded leaves): Worklets' serializer recurses every container
+    // entry regardless of how terminal its per-entry serialization is, so the walk's bound must
+    // cover every entry it can reach — no allocation is added (the counter and the entry's path
+    // string already exist).
+    nodes += 1
+    if (nodes > MAX_PAYLOAD_NODES) return `budget at ${path} (>${MAX_PAYLOAD_NODES} nodes)`
+    if (value === null || (typeof value !== 'object' && typeof value !== 'function')) return null
+    if (typeof value === 'function') {
+      const fn = value as unknown as Record<string, unknown>
+      // The RemoteFunction identity: a TRUTHY __remoteFunction on a FUNCTION is already
+      // serialized (serializable.native.ts:152); a plain UNTAGGED function becomes one
+      // (cloneNonWorkletFunction, :156-160) — both terminal, never walked.
+      if (fn['__remoteFunction']) return null
+      if (!fn['__workletHash']) return null
+      // A worklet (isWorkletFunction: truthy __workletHash on a function — workletFunction.ts):
+      // cloneWorklet recurses its enumerable properties — __closure AND __initData included
+      // (:428-481, :345-365) — so this walker must descend through the same properties: the
+      // cycle/budget law applies to the captured closure exactly as to any record.
+      if (visiting.has(value)) return `cycle at ${path}`
+      if (depth > MAX_PAYLOAD_DEPTH) return `budget at ${path} (>${MAX_PAYLOAD_DEPTH} deep)`
+      visiting.add(value)
+      for (const [key, entry] of Object.entries(value)) {
+        const violation = visit(entry, path === '' ? key : `${path}.${key}`, depth + 1)
+        if (violation !== null) return violation
+      }
+      visiting.delete(value)
+      return null
+    }
+    // Container types must be walked BEFORE the opaque-leaf test: Array/Map/Set prototypes are
+    // not Object.prototype, so the leaf test would otherwise skip them and hide their cycles.
+    const isContainer = Array.isArray(value) || value instanceof Map || value instanceof Set
+    if (!isContainer && isOpaqueLeaf(value)) return null
+    if (visiting.has(value)) return `cycle at ${path}`
+    if (depth > MAX_PAYLOAD_DEPTH) return `budget at ${path} (>${MAX_PAYLOAD_DEPTH} deep)`
+    visiting.add(value)
+    if (Array.isArray(value)) {
+      for (let index = 0; index < value.length; index += 1) {
+        const violation = visit(value[index], `${path}[${index}]`, depth + 1)
+        if (violation !== null) return violation
+      }
+    } else if (value instanceof Map) {
+      for (const [key, entry] of value) {
+        const keyViolation = visit(key, `${path}.<key>`, depth + 1)
+        if (keyViolation !== null) return keyViolation
+        const entryViolation = visit(entry, `${path}.${String(key)}`, depth + 1)
+        if (entryViolation !== null) return entryViolation
+      }
+    } else if (value instanceof Set) {
+      let index = 0
+      for (const entry of value) {
+        const violation = visit(entry, `${path}.<set ${index}>`, depth + 1)
+        if (violation !== null) return violation
+        index += 1
+      }
+    } else {
+      for (const [key, entry] of Object.entries(value)) {
+        const violation = visit(entry, path === '' ? key : `${path}.${key}`, depth + 1)
+        if (violation !== null) return violation
+      }
+    }
+    visiting.delete(value)
+    return null
+  }
+
+  return visit(root, '', 0)
+}
+
+// The ambient severity law, mirrored from motion/severity.ts (this module stays motion-import-
+// free like the rest of the driver/motion boundary): development throws, production reports
+// through the console channel and lets the caller DEGRADE — a refused payload never reaches the
+// UI scheduler, so the refusal, not the materialization, is the failure surface.
+declare const __DEV__: boolean | undefined
+
+/**
+ * The factory-edge assertion. Returns the violation string (so the caller can degrade to its
+ * safe path), or null when the payload is clean. Dev lane throws at the source; production
+ * reports the Error and continues into the caller's degradation — never a silent hand-off.
+ */
+export function refuseUnsafeSerializablePayload(payload: unknown, label: string): string | null {
+  const violation = findUnsafeSerializablePayloadPath(payload)
+  if (violation === null) return null
+  const error = new Error(
+    `native-motion: unsafe layout-animation payload (${label}): ${violation} — refusing to hand it to the UI scheduler (iOS AUTO SIGABRT wedge law)`,
+  )
+  if (typeof __DEV__ === 'undefined' || __DEV__ !== false) throw error
+  console.error(error)
+  return violation
+}

package/src/native/motion/severity.ts

@@ -0,0 +1,16 @@
+// Ambient severity for the native runtime (the ratified severity law: development throws;
+// production reports through the error channel and refuses the offending property). React
+// Native defines __DEV__; anywhere it is absent (vitest, node) the default is development —
+// fail-loud is the safe default.
+import type { NativeSeverity } from './motionViewController'
+
+declare const __DEV__: boolean | undefined
+
+export function ambientNativeSeverity(): NativeSeverity {
+  return typeof __DEV__ !== 'undefined' && __DEV__ === false ? 'production' : 'development'
+}
+
+/* The default error channel: loud in the console, never swallowed (the web shim's pattern). */
+export function consoleReporter(error: Error): void {
+  console.error(error)
+}