@rafaelaugusto/jolt 0.1.0-beta.9 → 0.1.0-rc.2

package/src/sampling.ts

@@ -0,0 +1,173 @@
+/** Maximum linear interpolation error in property units, not screen pixels. */
+export interface SamplingOptions {
+  duration: number
+  position(time: number): number
+  tolerance: number
+  /** Bound on linear interpolation error across this complete interval. */
+  errorBound?(start: number, end: number): number
+  /** Playback milliseconds per source millisecond. */
+  slowdown?: number
+  /** Unknown user functions retain at least 120 uniform intervals per second. */
+  custom?: boolean
+  /** Mandatory times in source milliseconds, including piecewise curve seams. */
+  breakpoints?: readonly number[]
+  /** Non-expansive property clamp and the values where its slope changes. */
+  projection?: { apply(value: number): number; breaks: readonly number[] }
+}
+
+export const MAX_SAMPLE_INTERVALS = 6000
+const MAX_EVALUATIONS = 24000
+const MAX_DEPTH = 24
+const MAX_INTERVAL_MS = 100
+const PROBES = [0.25, 0.5, 0.75] as const
+const NO_BREAKS: readonly number[] = []
+
+export interface SampledCurve {
+  times: number[]
+  values: number[]
+  sampling: {
+    method: 'adaptive' | 'uniform-fallback'
+    tolerance: number
+    /** Only true when every accepted interval passed an analytical bound. */
+    bounded: boolean
+    evaluations: number
+    reason?: 'sample-limit' | 'evaluation-limit' | 'invalid-bound'
+  }
+}
+
+/** Curves are sampled only at setup. Work and output are bounded independently. */
+export function sampleCurve(options: SamplingOptions): SampledCurve {
+  const {
+    duration,
+    position,
+    tolerance,
+    errorBound,
+    custom = false,
+    slowdown = 1,
+  } = options
+  let evaluations = 0
+  const project = options.projection?.apply ?? ((value: number) => value)
+  const at = (time: number) => {
+    evaluations++
+    return position(time)
+  }
+  const maxInterval = (custom ? 1000 / 120 : MAX_INTERVAL_MS) / slowdown
+  const seeds = Math.max(1, Math.ceil(duration / maxInterval))
+  let reason: SampledCurve['sampling']['reason']
+  const initial = at(0)
+  const times = [0],
+    values = [project(initial)]
+  const append = (time: number, value: number) => {
+    if (times.length >= MAX_SAMPLE_INTERVALS + 1) {
+      reason = 'sample-limit'
+      return
+    }
+    times.push(duration > 0 ? time / duration : 1)
+    values.push(project(value))
+  }
+  const split = (a: number, b: number, va: number, vb: number, depth: number) => {
+    if (reason) return
+    if (evaluations >= MAX_EVALUATIONS) {
+      reason = 'evaluation-limit'
+      return
+    }
+    let accepted: boolean
+    if (errorBound) {
+      let bound = errorBound(a, b)
+      // Clamping is non-expansive, but clamping a chord's endpoints can create a
+      // different chord. Bound that extra error at each crossed clamp boundary.
+      let clampError = 0
+      for (const edge of options.projection?.breaks ?? NO_BREAKS) {
+        const fraction = (edge - va) / (vb - va)
+        if (fraction > 0 && fraction < 1)
+          clampError = Math.max(
+            clampError,
+            Math.abs(
+              project(edge) - (project(va) + (project(vb) - project(va)) * fraction),
+            ),
+          )
+      }
+      bound += clampError
+      if (!Number.isFinite(bound) || bound < 0) {
+        reason = 'invalid-bound'
+        return
+      }
+      accepted = bound <= tolerance
+    } else {
+      // Three probes plus a safety margin, never a mathematical guarantee for a user function.
+      let error = 0
+      for (const fraction of PROBES)
+        error = Math.max(
+          error,
+          Math.abs(
+            project(at(a + (b - a) * fraction)) -
+              (project(va) + (project(vb) - project(va)) * fraction),
+          ),
+        )
+      accepted = error <= tolerance * 0.5
+    }
+    if (accepted) {
+      append(b, vb)
+      return
+    }
+    const mid = (a + b) / 2
+    if (depth >= MAX_DEPTH || mid === a || mid === b) {
+      reason = 'sample-limit'
+      return
+    }
+    const vm = at(mid)
+    split(a, mid, va, vm, depth + 1)
+    split(mid, b, vm, vb, depth + 1)
+  }
+  if (seeds > MAX_SAMPLE_INTERVALS || !Number.isFinite(duration)) reason = 'sample-limit'
+  else if (duration === 0) append(0, at(0))
+  else {
+    const boundaries = [
+      ...new Set([
+        ...Array.from({ length: seeds + 1 }, (_, i) =>
+          i === seeds ? duration : (duration * i) / seeds,
+        ),
+        ...(options.breakpoints ?? []).filter((t) => t > 0 && t < duration),
+      ]),
+    ].sort((a, b) => a - b)
+    let previous = initial
+    for (let i = 0; i < boundaries.length - 1 && !reason; i++) {
+      const a = boundaries[i]!,
+        b = boundaries[i + 1]!
+      const value = at(b)
+      split(a, b, previous, value, 0)
+      previous = value
+    }
+  }
+  if (!reason)
+    return {
+      times,
+      values,
+      sampling: { method: 'adaptive', tolerance, bounded: !!errorBound, evaluations },
+    }
+  // Preserve the old capped 60 Hz representation if refinement cannot meet its budget.
+  // Explicit segment endpoints are still retained by the caller. No precision claim on fallback.
+  const steps = Math.max(
+    1,
+    Math.min(MAX_SAMPLE_INTERVALS, Math.ceil((duration * slowdown * 60) / 1000)),
+  )
+  const fallbackTimes = [
+    ...new Set([
+      ...Array.from({ length: steps + 1 }, (_, i) => i / steps),
+      ...(options.breakpoints ?? [])
+        .filter((t) => t > 0 && t < duration)
+        .map((t) => t / duration),
+    ]),
+  ].sort((a, b) => a - b)
+  return {
+    times: fallbackTimes,
+    values: fallbackTimes.map((t) => project(at(t * duration))),
+    sampling: {
+      method: 'uniform-fallback',
+      tolerance,
+      bounded: false,
+      evaluations,
+      reason,
+    },
+  }
+}

package/src/scene-appearance.ts

@@ -0,0 +1,92 @@
+/// <reference types="@nativescript/types-ios/lib/ios/objc-x86_64/objc!SceneKit" preserve="true" />
+import { Color } from '@nativescript/core'
+import { colorMixer, parseColor, type ColorValue } from './color.js'
+import { registerNativeProperty, type NativeProperty } from './native-property.js'
+
+const clamp = (n: number) => Math.max(0, Math.min(1, n))
+function scalar(name: string, maximum: number, create: (target: object) => object) {
+  return registerNativeProperty<number>({
+    name: `jolt.scenekit/${name}`,
+    units: [
+      name === 'light-intensity'
+        ? 'lumens (PBR); 1000 = unit multiplier otherwise'
+        : 'opacity fraction',
+    ],
+    platforms: ['ios'],
+    encode: (value) => [value],
+    decode: (values) => values[0]!,
+    validate(value) {
+      if (!Number.isFinite(value) || value < 0 || value > maximum)
+        throw new RangeError(`${name} needs a finite value in 0..${maximum}.`)
+    },
+    interpolate: (a, b, t) => Math.max(0, Math.min(maximum, a + (b - a) * t)),
+    create,
+  })
+}
+function color(name: string, create: (target: object) => object) {
+  return registerNativeProperty<ColorValue>({
+    name: `jolt.scenekit/${name}`,
+    // Premultiply the sampled sRGB channels, so native linear interpolation also handles zero alpha.
+    units: [
+      'premultiplied sRGB red',
+      'premultiplied sRGB green',
+      'premultiplied sRGB blue',
+      'alpha',
+    ],
+    platforms: ['ios'],
+    encode(value) {
+      const argb = parseColor(value),
+        alpha = (argb >>> 24) / 255
+      return [
+        (((argb >>> 16) & 255) / 255) * alpha,
+        (((argb >>> 8) & 255) / 255) * alpha,
+        ((argb & 255) / 255) * alpha,
+        alpha,
+      ]
+    },
+    decode(values) {
+      const alpha = clamp(values[3]!)
+      const channel = (i: number) =>
+        Math.round(clamp(alpha ? values[i]! / alpha : 0) * 255)
+      return new Color(
+        ((Math.round(alpha * 255) << 24) |
+          (channel(0) << 16) |
+          (channel(1) << 8) |
+          channel(2)) >>>
+          0,
+      )
+    },
+    interpolate: (a, b, t) => new Color(colorMixer(parseColor(a), parseColor(b))(t)),
+    create,
+  })
+}
+
+/** SCNLight intensity, finite and nonnegative. Non-spatial: retains timing under reduced motion. */
+export const sceneKitLightIntensity: (light: SCNLight) => NativeProperty<number> = scalar(
+  'light-intensity',
+  Infinity,
+  (target) => JoltReferenceProperties.sceneLightIntensity(target as NSObject),
+)
+/** Solid UIColor/CGColor light color. Returns a normalized sRGB Color from get(). */
+export const sceneKitLightColor: (light: SCNLight) => NativeProperty<ColorValue> = color(
+  'light-color',
+  (target) => JoltReferenceProperties.sceneLightColor(target as NSObject),
+)
+/** SCNMaterial transparency in 0..1; does not change transparencyMode/transparent contents. */
+export const sceneKitMaterialTransparency: (
+  material: SCNMaterial,
+) => NativeProperty<number> = scalar('material-transparency', 1, (target) =>
+  JoltReferenceProperties.sceneMaterialTransparency(target as NSObject),
+)
+/** Solid color diffuse contents only; never converts a texture into a color. */
+export const sceneKitMaterialDiffuse: (
+  material: SCNMaterial,
+) => NativeProperty<ColorValue> = color('material-diffuse', (target) =>
+  JoltReferenceProperties.sceneMaterialDiffuse(target as NSObject),
+)
+/** Solid color emission contents only; does not make the material illuminate nearby geometry. */
+export const sceneKitMaterialEmission: (
+  material: SCNMaterial,
+) => NativeProperty<ColorValue> = color('material-emission', (target) =>
+  JoltReferenceProperties.sceneMaterialEmission(target as NSObject),
+)

package/src/scene-camera.ts

@@ -0,0 +1,30 @@
+/// <reference types="@nativescript/types-ios/lib/ios/objc-x86_64/objc!SceneKit" preserve="true" />
+import { registerNativeProperty, type NativeProperty } from './native-property.js'
+
+/** Perspective SCNCamera field of view in degrees (1..179), on its projectionDirection axis. */
+export const sceneKitFieldOfView: (camera: SCNCamera) => NativeProperty<number> =
+  registerNativeProperty<number>({
+    name: 'jolt.scenekit/field-of-view',
+    units: ['degrees on the camera projectionDirection axis'],
+    platforms: ['ios'],
+    spatial: true,
+    encode: (value) => [value],
+    decode: (values) => values[0]!,
+    validate(value) {
+      if (!Number.isFinite(value) || value < 1 || value > 179)
+        throw new RangeError(
+          'SceneKit field of view needs a finite angle in 1..179 degrees.',
+        )
+    },
+    interpolate: (a, b, t) => Math.max(1, Math.min(179, a + (b - a) * t)),
+    create(target) {
+      if (
+        typeof JoltReferenceProperties === 'undefined' ||
+        typeof JoltReferenceProperties.sceneFieldOfView !== 'function'
+      )
+        throw new Error(
+          'SceneKit field of view requires an updated @rafaelaugusto/jolt-native plugin. Update both packages and rebuild the native app.',
+        )
+      return JoltReferenceProperties.sceneFieldOfView(target as NSObject)
+    },
+  })

package/src/scene-shader.ts

@@ -0,0 +1,139 @@
+/// <reference types="@nativescript/types-ios/lib/ios/objc-x86_64/objc!SceneKit" preserve="true" />
+import {
+  nativePropertyTarget,
+  registerNativeProperty,
+  type NativeProperty,
+} from './native-property.js'
+
+export type SceneUniformType = 'float' | 'float2' | 'float3' | 'float4'
+export type SceneUniformValue<T extends SceneUniformType> = T extends 'float'
+  ? number
+  : T extends 'float2'
+    ? readonly [number, number]
+    : T extends 'float3'
+      ? readonly [number, number, number]
+      : readonly [number, number, number, number]
+export interface SceneUniformOptions<T extends SceneUniformType> {
+  type: T
+  /** Finite inclusive limits applied to every component; spring overshoot is clamped. */
+  range: readonly [number, number]
+  /** One application-defined unit per component. Vectors have no implicit color conversion. */
+  units: readonly string[]
+  /** Spatial uniforms jump under Reduced Motion; appearance uniforms keep their timing. */
+  motion: 'spatial' | 'appearance'
+}
+function runtime() {
+  if (typeof JoltSceneShaderProperties === 'undefined')
+    throw new Error(
+      'Update @rafaelaugusto/jolt-native and rebuild the native app to use SceneKit environment and shader adapters.',
+    )
+  return JoltSceneShaderProperties
+}
+function sink(
+  create: (error: interop.Reference<NSError>) => JoltPropertySink | null,
+): JoltPropertySink {
+  const error = new interop.Reference<NSError>()
+  const result = create(error)
+  if (!result)
+    throw new Error(
+      error.value?.localizedDescription ??
+        'Invalid SceneKit property target or shader schema.',
+    )
+  return result
+}
+
+/** Scene environment multiplier, nonnegative; leaves the environment/background images untouched. */
+export const sceneKitEnvironmentIntensity: (scene: SCNScene) => NativeProperty<number> =
+  registerNativeProperty<number>({
+    name: 'jolt.scenekit/environment-intensity',
+    units: ['environment illumination multiplier'],
+    platforms: ['ios'],
+    encode: (value) => [value],
+    decode: (values) => values[0]!,
+    validate(value) {
+      if (!Number.isFinite(value) || value < 0)
+        throw new RangeError('Environment intensity must be finite and nonnegative.')
+    },
+    interpolate: (a, b, t) => Math.max(0, a + (b - a) * t),
+    create: (target) =>
+      sink((error) => runtime().environmentError(target as NSObject, error)),
+  })
+
+/** Declared Metal shaderModifiers input, initialized by the application before attachment. */
+export function sceneKitUniform<T extends SceneUniformType>(
+  target: SCNMaterial | SCNGeometry,
+  name: string,
+  options: SceneUniformOptions<T>,
+): NativeProperty<SceneUniformValue<T>> {
+  if (
+    typeof name !== 'string' ||
+    !/^[A-Za-z][A-Za-z0-9_]*$/.test(name) ||
+    /^(u_|a_|v_|scn_)/.test(name)
+  )
+    throw new TypeError(
+      'Use a declared custom uniform identifier without a reserved SceneKit prefix or KVC path.',
+    )
+  if (!options || !['float', 'float2', 'float3', 'float4'].includes(options.type))
+    throw new TypeError('Shader uniforms support float, float2, float3 and float4.')
+  const count = options.type === 'float' ? 1 : Number(options.type.slice(-1))
+  const range = options.range
+  if (
+    !Array.isArray(range) ||
+    range.length !== 2 ||
+    !range.every((n) => Number.isFinite(n) && Math.abs(n) <= 3.4028234663852886e38) ||
+    range[0] >= range[1]
+  )
+    throw new RangeError('Declare an ordered finite range for the shader components.')
+  if (
+    !Array.isArray(options.units) ||
+    options.units.length !== count ||
+    options.units.some((unit) => typeof unit !== 'string' || !unit.trim())
+  )
+    throw new TypeError('Declare one nonempty unit for each shader component.')
+  if (!['spatial', 'appearance'].includes(options.motion))
+    throw new TypeError('Declare whether the shader motion is spatial or appearance.')
+  // Copy the schema: caller mutation cannot change an already attached native sink.
+  const [low, high] = range,
+    type = options.type,
+    units = [...options.units]
+  const vector = (value: SceneUniformValue<T>): number[] => {
+    const values = type === 'float' ? [value] : value
+    if (
+      !Array.isArray(values) ||
+      values.length !== count ||
+      values.some(
+        (n) => typeof n !== 'number' || !Number.isFinite(n) || n < low || n > high,
+      )
+    )
+      throw new RangeError(
+        `${name} needs ${count} finite component(s) in ${low}..${high}.`,
+      )
+    return [...values] as number[]
+  }
+  return nativePropertyTarget(target, {
+    name: `jolt.scenekit/uniform-${name}`,
+    units,
+    platforms: ['ios'],
+    spatial: options.motion === 'spatial',
+    encode: vector,
+    decode: (values) =>
+      (type === 'float' ? values[0]! : [...values]) as SceneUniformValue<T>,
+    interpolate(a, b, t) {
+      const first = vector(a),
+        last = vector(b)
+      const result = first.map((value, i) =>
+        Math.max(low, Math.min(high, value + (last[i]! - value) * t)),
+      )
+      return (type === 'float' ? result[0]! : result) as SceneUniformValue<T>
+    },
+    create: (object) =>
+      sink((error) =>
+        runtime().uniformNameConfigurationError(
+          object as NSObject,
+          name,
+          JSON.stringify({ type, low, high }),
+          error,
+        ),
+      ),
+  })
+}

package/src/scroll-header/geometry.ts

@@ -0,0 +1,88 @@
+export interface ScrollHeaderGeometry {
+  expanded: number
+  minimum: number
+  section: number
+  range: number
+  spacer: number
+  rowHeight: number
+  parallax: number
+  divider: number
+  handoff: number
+  titleFade: readonly [number, number]
+  toolbarFade: readonly [number, number]
+}
+
+export function headerGeometry(
+  expanded: number,
+  minimum: number,
+  section: number,
+  rowHeight: number,
+  parallax: number,
+  divider = 0,
+  titleFade: readonly [number, number] = [0, 0.7],
+  toolbarFade: readonly [number, number] = [0.55, 0.95],
+): ScrollHeaderGeometry {
+  if (
+    ![expanded, minimum, section, rowHeight, parallax, divider].every(Number.isFinite) ||
+    divider < 0 ||
+    minimum <= 0 ||
+    expanded <= minimum ||
+    section < 0 ||
+    rowHeight <= 0 ||
+    parallax < 0 ||
+    parallax > expanded - minimum
+  )
+    throw new RangeError(
+      'scrollHeader needs expanded > minimum > 0, a positive rowHeight, and parallax within the collapse range.',
+    )
+  for (const interval of [titleFade, toolbarFade]) {
+    if (
+      !Array.isArray(interval) ||
+      interval.length !== 2 ||
+      !interval.every(Number.isFinite) ||
+      interval[0] < 0 ||
+      interval[1] > 1 ||
+      interval[0] >= interval[1]
+    )
+      throw new RangeError('Fade intervals must increase within [0, 1].')
+  }
+  return {
+    divider,
+    handoff: (toolbarFade[0] + toolbarFade[1]) / 2,
+    titleFade: [...titleFade],
+    toolbarFade: [...toolbarFade],
+    expanded,
+    minimum,
+    section,
+    rowHeight,
+    parallax,
+    range: expanded - minimum,
+    spacer: expanded + section,
+  }
+}
+
+/** Keep the visible rows anchored when late artwork/text changes the header height. */
+export function resizedOffset(
+  offset: number,
+  before: ScrollHeaderGeometry,
+  after: ScrollHeaderGeometry,
+) {
+  return offset <= 0 ? 0 : Math.max(0, offset + after.spacer - before.spacer)
+}
+
+export function restoredOffset(
+  offset: number,
+  before: ScrollHeaderGeometry,
+  after: ScrollHeaderGeometry,
+  previousIndex: number,
+  nextIndex: number,
+) {
+  if (offset <= 0) return 0
+  return Math.max(
+    0,
+    offset +
+      after.spacer -
+      before.spacer +
+      (nextIndex - previousIndex) * (after.rowHeight + after.divider),
+  )
+}