@unrulysystems/native-motion-core 0.1.0-alpha.0

package/dist/motion-value-driver-port.d.cts

@@ -0,0 +1,406 @@
+import type { Clock, MotionGraph, MotionValue } from "./types.cjs";
+export type DirectPublicInitializerProvenance = {
+    readonly kind: 'finite-number';
+} | {
+    readonly kind: 'ineligible';
+    readonly reason: 'non-finite-number' | 'non-number';
+};
+export type MotionValueDriverCreation = {
+    readonly kind: 'direct-public';
+    readonly initializer: DirectPublicInitializerProvenance;
+} | {
+    readonly kind: 'unrecognized';
+};
+export type MotionValueDriverBindingEligibility = {
+    readonly kind: 'eligible';
+    readonly creationKind: 'direct-public';
+    readonly initializerProvenance: 'finite-number';
+    readonly currentValue: number;
+} | {
+    readonly kind: 'ineligible';
+    readonly reason: 'not-direct-public' | 'initializer-not-finite-number' | 'current-not-finite-number';
+};
+export type PrimitiveNumericHistory = {
+    readonly kind: 'single-sample';
+    readonly currentValue: number;
+    readonly currentTimestampMs: number;
+} | {
+    readonly kind: 'finite-difference';
+    readonly currentValue: number;
+    readonly previousValue: number;
+    readonly currentTimestampMs: number;
+    readonly previousTimestampMs: number;
+};
+export type CachedNumericHistory = {
+    readonly kind: 'unavailable';
+} | PrimitiveNumericHistory;
+/**
+ * Collector-silent raw state supplied by the creating/owning runtime. Attaching the private port
+ * must not call public `get()` (which participates in dependency collection), and an attach with no
+ * authored sample history must not manufacture a timestamp from the current clock.
+ */
+export interface CollectorSilentMotionValueRawSnapshot<T> {
+    readonly kind: 'collector-silent-motion-value-raw-snapshot';
+    readonly currentValue: T;
+    readonly history: CachedNumericHistory;
+    readonly directOperationEpoch: number;
+    readonly authoritativeSequence: number;
+}
+export interface PrimitiveMotionValueSnapshot {
+    readonly kind: 'numeric-motion-value-snapshot';
+    readonly snapshotSequence: number;
+    readonly directOperationEpoch: number;
+    readonly authoritativeSequence: number;
+    readonly history: PrimitiveNumericHistory;
+}
+export type TransportedSampleOrigin = 'ui-frame' | 'js-local-frame' | 'js-fallback-frame' | 'js-pending-update' | 'js-orphan-drain-frame';
+interface TransportedMotionValueEntryIdentity {
+    readonly channelId: number;
+    readonly origin: TransportedSampleOrigin;
+    readonly authoritativeSequence: number;
+}
+export interface TransportedExecutionGeneratorSample extends TransportedMotionValueEntryIdentity {
+    readonly kind: 'generator-sample';
+    readonly executionId: number;
+    readonly directOperationEpoch: number;
+    readonly executionLease: number;
+    readonly writeSequence: number;
+    readonly history: PrimitiveNumericHistory;
+    readonly completion: {
+        readonly kind: 'unarmed';
+    } | {
+        readonly kind: 'armed';
+        readonly completionSequence: number;
+        readonly lifecycleEventSequence: number;
+    };
+}
+export type TokenlessMotionValueTaskKind = 'instant-target' | 'equal-reassertion' | 'carrier' | 'idle-direct-write';
+export interface TransportedTokenlessTaskWrite extends TransportedMotionValueEntryIdentity {
+    readonly kind: 'tokenless-task-write';
+    readonly taskKind: TokenlessMotionValueTaskKind;
+    readonly taskSequence: number;
+    readonly writeSequence: number;
+    readonly history: PrimitiveNumericHistory;
+}
+export type TransportedTaskCallbackKind = 'transition-on-update' | 'transition-on-complete' | 'animation-complete';
+interface TransportedTokenlessTaskCallbackIdentity extends TransportedMotionValueEntryIdentity {
+    readonly kind: 'tokenless-task-callback';
+    readonly taskKind: 'instant-target';
+    readonly taskSequence: number;
+    /**
+     * Task delivery is tokenless, but callback-time cache adoption is not. These guards describe
+     * the candidate history only; rejecting it must never suppress the immutable callback event.
+     */
+    readonly candidateDirectOperationEpoch: number;
+    readonly candidateWriteSequence: number;
+    readonly eventSequence: number;
+    readonly history: PrimitiveNumericHistory;
+}
+export type TransportedTokenlessTaskCallback = (TransportedTokenlessTaskCallbackIdentity & {
+    readonly callbackKind: 'transition-on-update' | 'transition-on-complete';
+    readonly completionSequence?: never;
+}) | (TransportedTokenlessTaskCallbackIdentity & {
+    readonly callbackKind: 'animation-complete';
+    readonly completionSequence: number;
+});
+/** One update-ordered mailbox entry: execution samples plus every tokenless task/write class. */
+export type TransportedMotionValueSample = TransportedExecutionGeneratorSample | TransportedTokenlessTaskWrite | TransportedTokenlessTaskCallback;
+export interface PrimitiveTransitionEvent {
+    readonly kind: 'transition-on-update' | 'transition-on-complete';
+    readonly channelId: number;
+    readonly executionId: number;
+    readonly directOperationEpoch: number;
+    readonly executionLease: number;
+    readonly writeSequence: number;
+    readonly eventSequence: number;
+    readonly history: PrimitiveNumericHistory;
+}
+export interface MotionValueLifecycleTerminalEvent {
+    readonly kind: 'animation-complete';
+    readonly channelId: number;
+    readonly executionId: number;
+    readonly directOperationEpoch: number;
+    readonly executionLease: number;
+    readonly writeSequence: number;
+    readonly eventSequence: number;
+    readonly completionSequence: number;
+    readonly history: PrimitiveNumericHistory;
+}
+export type DirectMotionValueOperation = {
+    readonly kind: 'set';
+    readonly commandSequence: number;
+    readonly value: number;
+} | {
+    readonly kind: 'jump';
+    readonly commandSequence: number;
+    readonly value: number;
+} | {
+    readonly kind: 'stop';
+    readonly commandSequence: number;
+} | {
+    readonly kind: 'destroy';
+    readonly commandSequence: number;
+} | {
+    readonly kind: 'start';
+    readonly commandSequence: number;
+    readonly executionId: number;
+};
+/**
+ * Private public-control-slot identity. The physical execution is retained elsewhere: clearing
+ * this slot changes `isAnimating()` only and must never imply that its execution was stopped.
+ */
+export type MotionValuePublicControlSlotState = {
+    readonly kind: 'empty';
+} | {
+    readonly kind: 'installed';
+    readonly controlId: number;
+    readonly executionId: number;
+};
+export interface MotionValuePublicControlSlotInstallation {
+    readonly controlId: number;
+    readonly executionId: number;
+    /** Stops only this installed control when a direct public stop/jump reaches it. */
+    readonly stopPhysicalExecution: () => void;
+}
+export type MotionValueDriverPortInvariant = 'rehydrated-public-control-slot-installation-required' | 'rehydrated-public-control-slot-installation-unexpected' | 'rehydrated-public-control-slot-reference-mismatch' | 'value-not-graph-motion-value' | 'direct-operation-kind-unrecognized' | 'transported-sample-kind-unrecognized';
+export declare const MOTION_VALUE_DRIVER_PORT_INVARIANT: "NATIVE_MOTION_CORE_MOTION_VALUE_DRIVER_PORT_INVARIANT";
+/** Typed fail-closed refusal for an unusable restored public-control slot. */
+export declare class MotionValueDriverPortInvariantError extends Error {
+    readonly code: "NATIVE_MOTION_CORE_MOTION_VALUE_DRIVER_PORT_INVARIANT";
+    readonly invariant: MotionValueDriverPortInvariant;
+    constructor(invariant: MotionValueDriverPortInvariant);
+}
+export interface MotionValuePublicControlSlotReceipt {
+    readonly kind: 'public-control-slot-updated';
+    readonly publicControlSlot: MotionValuePublicControlSlotState;
+    readonly physicalExecution: 'retained';
+}
+export interface MotionValueDriverPortState {
+    readonly channelId: number;
+    readonly rawCurrentValue: unknown;
+    readonly history: CachedNumericHistory;
+    readonly directOperationEpoch: number;
+    readonly authoritativeSequence: number;
+    readonly currentExecutionId: number | null;
+    readonly executionLease: number;
+    readonly publicControlSlot: MotionValuePublicControlSlotState;
+    readonly acceptedWriteSequence: number;
+    readonly demandedWriteSequence: number;
+    readonly deliveredEventWatermark: number;
+    readonly synchronousSnapshotReadCount: number;
+    readonly outboundOriginCommandCount: number;
+}
+export interface MotionValueDriverPortObservation {
+    readonly channelId: number;
+    readonly creationKind: MotionValueDriverCreation['kind'];
+    readonly initializerProvenance: 'finite-number' | 'non-finite-number' | 'non-number' | 'unrecognized';
+    readonly currentValueKind: 'finite-number' | 'non-finite-number' | 'non-number';
+    readonly cachedCurrentValue: number | null;
+    readonly cachedPreviousValue: number | null;
+    readonly cachedCurrentTimestampMs: number | null;
+    readonly cachedPreviousTimestampMs: number | null;
+    readonly directOperationEpoch: number;
+    readonly authoritativeSequence: number;
+    readonly currentExecutionId: number | null;
+    readonly executionLease: number;
+    readonly publicControlSlotControlId: number | null;
+    readonly publicControlSlotExecutionId: number | null;
+    readonly acceptedWriteSequence: number;
+    readonly demandedWriteSequence: number;
+    readonly deliveredEventWatermark: number;
+    readonly synchronousSnapshotReadCount: number;
+    readonly outboundOriginCommandCount: number;
+}
+export interface TokenlessCallbackReplaySuppression {
+    readonly kind: 'event-replay-rejected';
+    readonly reason: 'stale-event-sequence';
+    readonly callbackKind: TransportedTaskCallbackKind;
+    readonly callbackDelivery: 'suppressed-replay';
+    readonly candidateCache: 'unchanged';
+    readonly progress: 'unchanged';
+    readonly originEcho: 'suppressed';
+}
+export type TransportedSampleApplication = {
+    readonly kind: 'applied';
+    readonly finiteDifferenceVelocity: number;
+    readonly changeNotification: 'emitted' | 'suppressed-equal-value' | 'suppressed-no-observer';
+    readonly derivedDependents: 'marked-dirty' | 'unchanged';
+    readonly derivedFrame: 'requested' | 'not-requested';
+    readonly originEcho: 'suppressed';
+} | {
+    readonly kind: 'rejected';
+    readonly reason: 'stale-direct-operation-epoch' | 'stale-execution-lease' | 'stale-write-sequence';
+    readonly armedCompletion: 'retained' | 'not-armed';
+    readonly originEcho: 'suppressed';
+} | {
+    readonly kind: 'callback-delivered';
+    readonly callbackKind: TransportedTaskCallbackKind;
+    readonly callbackDelivery: 'required';
+    readonly candidateCache: 'adopted' | 'rejected-stale-direct-operation-epoch' | 'rejected-stale-write-sequence';
+    readonly originEcho: 'suppressed';
+} | TokenlessCallbackReplaySuppression;
+export interface DirectMotionValueOperationReceipt {
+    readonly kind: 'direct-operation-begun';
+    readonly operation: DirectMotionValueOperation['kind'];
+    readonly directOperationEpoch: number;
+    readonly outboundOriginCommand: 'required' | 'not-required';
+}
+export interface SynchronousSnapshotAdoption {
+    readonly kind: 'synchronous-snapshot-adopted';
+    readonly callbackDelivery: 'silent';
+    readonly demandedWriteSequence: 'unchanged';
+    readonly publicControlSlot: 'unchanged';
+}
+export interface SynchronousSnapshotRejection {
+    readonly kind: 'synchronous-snapshot-rejected';
+    readonly reason: 'stale-direct-operation-epoch' | 'stale-authoritative-sequence';
+    readonly callbackDelivery: 'silent';
+    readonly demandedWriteSequence: 'unchanged';
+    readonly publicControlSlot: 'unchanged';
+}
+export type GuardedSynchronousSnapshotAdoption = SynchronousSnapshotAdoption | SynchronousSnapshotRejection;
+export type TransportedTerminalApplication = {
+    readonly kind: 'candidate-adopted';
+    readonly callbackDelivery: 'required';
+    readonly armedCompletion: 'retained';
+} | {
+    readonly kind: 'event-replay-rejected';
+    readonly reason: 'stale-event-sequence';
+    readonly callbackDelivery: 'suppressed-replay';
+    readonly armedCompletion: 'retained';
+} | {
+    readonly kind: 'candidate-cache-rejected';
+    readonly reason: 'stale-direct-operation-epoch' | 'stale-execution-lease' | 'stale-write-sequence';
+    readonly callbackDelivery: 'required';
+    readonly armedCompletion: 'retained';
+};
+/**
+ * Drain-local progress writer used when a transported sample crosses arbitrary user callbacks.
+ * State adoption is irreversible even when a later observer throws; the owning drain finalizes
+ * its delivered watermark without replaying that write (REQ-VALUE-015).
+ */
+export type TransportedSampleIrreversibleSubphase = 'cache-history-adopted' | 'change-observer-delivered' | 'dependent-dirtying-complete';
+export type TransportedSampleProgressEntry = {
+    readonly channelId: number;
+    readonly entryKind: 'generator-sample';
+    readonly executionId: number;
+    readonly deliverySequence: number;
+} | {
+    readonly channelId: number;
+    readonly entryKind: 'tokenless-task-write';
+    readonly taskKind: TokenlessMotionValueTaskKind;
+    readonly taskSequence: number;
+    readonly deliverySequence: number;
+} | {
+    readonly channelId: number;
+    readonly entryKind: 'transition-terminal';
+    readonly callbackKind: 'transition-on-update' | 'transition-on-complete';
+    readonly executionId: number;
+    readonly deliverySequence: number;
+} | {
+    readonly channelId: number;
+    readonly entryKind: 'lifecycle-terminal';
+    readonly callbackKind: 'animation-complete';
+    readonly executionId: number;
+    readonly deliverySequence: number;
+} | {
+    readonly channelId: number;
+    readonly entryKind: 'tokenless-task-callback';
+    readonly taskKind: 'instant-target';
+    readonly callbackKind: TransportedTaskCallbackKind;
+    readonly taskSequence: number;
+    readonly deliverySequence: number;
+};
+export interface TransportedSampleProgressState {
+    readonly activeEntry: TransportedSampleProgressEntry | null;
+    readonly lastIrreversibleSubphase: TransportedSampleIrreversibleSubphase | null;
+    readonly deliveredWriteWatermark: number;
+    readonly deliveredEventWatermark: number;
+    readonly retentionFinalization: 'pending' | 'finalized';
+}
+export interface TransportedSampleProgressWriter {
+    beginEntry(entry: TransportedSampleProgressEntry): void;
+    markIrreversibleSubphase(subphase: TransportedSampleIrreversibleSubphase): void;
+    finalizeDeliveredWriteWatermarkAndRetention(channelId: number, deliveredWriteWatermark: number): void;
+    finalizeDeliveredEventWatermarkAndRetention(channelId: number, deliveredEventWatermark: number): void;
+    clearEntry(): void;
+    observe(): TransportedSampleProgressState;
+}
+export interface LocalFrameEventPort {
+    observe(): LocalFrameEventPortObservation;
+    stageTransitionOnUpdate(event: PrimitiveTransitionEvent): void;
+    stageTransitionOnComplete(event: PrimitiveTransitionEvent): void;
+    drainTransitionEvents(): readonly PrimitiveTransitionEvent[];
+    guardAndAdoptTransitionTerminalCandidateCacheAtMailboxPosition(event: PrimitiveTransitionEvent, mailboxPosition: number, progress: TransportedSampleProgressWriter): TransportedTerminalApplication;
+    guardAndAdoptLifecycleTerminalCandidateCacheAtMailboxPosition(event: MotionValueLifecycleTerminalEvent, mailboxPosition: number, progress: TransportedSampleProgressWriter): TransportedTerminalApplication;
+}
+/**
+ * Serializable local-frame event state. Native owns scheduling and mailbox allocation; CORE owns
+ * only the deterministic event ordering/candidate-cache transition represented by this record.
+ */
+export interface LocalFrameEventPortState {
+    readonly stagedTransitionEvents: readonly PrimitiveTransitionEvent[];
+    readonly drainedEventSequences: readonly number[];
+    readonly lastGuardedMailboxPosition: number | null;
+}
+export interface LocalFrameEventPortObservation {
+    readonly stagedTransitionEventCount: number;
+    readonly stagedEventSequences: readonly number[];
+    readonly drainedEventSequences: readonly number[];
+    readonly lastGuardedMailboxPosition: number | null;
+}
+export interface CreateLocalFrameEventPortOptions {
+    readonly initialState?: LocalFrameEventPortState;
+    /** The exact value port whose cache/replay guard runs at this event's mailbox position. */
+    readonly candidateCacheGuard: MotionValueTerminalCandidateCacheGuard;
+}
+export type MotionValueDriverPortOperation = 'evaluate-binding-eligibility' | 'begin-direct-operation' | 'install-public-control-slot' | 'clear-public-control-slot-token-blind' | 'apply-transported-sample' | 'adopt-synchronous-snapshot' | 'read-cached-velocity' | 'apply-transition-terminal' | 'apply-lifecycle-terminal' | 'local-frame-stage-transition-on-update' | 'local-frame-stage-transition-on-complete' | 'local-frame-drain-transition-events' | 'local-frame-guard-transition-terminal-candidate-cache' | 'local-frame-guard-lifecycle-terminal-candidate-cache';
+export declare const MOTION_VALUE_DRIVER_PORT_UNIMPLEMENTED: "NATIVE_MOTION_CORE_MOTION_VALUE_DRIVER_PORT_UNIMPLEMENTED";
+export declare class MotionValueDriverPortUnimplementedError extends Error {
+    readonly code: "NATIVE_MOTION_CORE_MOTION_VALUE_DRIVER_PORT_UNIMPLEMENTED";
+    readonly operation: MotionValueDriverPortOperation;
+    constructor(operation: MotionValueDriverPortOperation);
+}
+export interface MotionValueTerminalCandidateCacheGuard {
+    applyTransitionTerminal(event: PrimitiveTransitionEvent, mailboxPosition: number, progress: TransportedSampleProgressWriter): TransportedTerminalApplication;
+    applyLifecycleTerminal(event: MotionValueLifecycleTerminalEvent, mailboxPosition: number, progress: TransportedSampleProgressWriter): TransportedTerminalApplication;
+}
+export interface MotionValueDriverPort<T> extends MotionValueTerminalCandidateCacheGuard {
+    readonly value: MotionValue<T>;
+    observe(): MotionValueDriverPortObservation;
+    evaluateBindingEligibility(currentValue: unknown): MotionValueDriverBindingEligibility;
+    beginDirectOperation(operation: DirectMotionValueOperation): DirectMotionValueOperationReceipt;
+    installPublicControlSlot(installation: MotionValuePublicControlSlotInstallation): MotionValuePublicControlSlotReceipt;
+    clearPublicControlSlotTokenBlind(causedByExecutionId: number): MotionValuePublicControlSlotReceipt;
+    applyTransportedSample(sample: TransportedMotionValueSample, progress: TransportedSampleProgressWriter): TransportedSampleApplication;
+    adoptSynchronousSnapshot(snapshot: PrimitiveMotionValueSnapshot): GuardedSynchronousSnapshotAdoption;
+    readCachedVelocity(atTimestampMs: number): number;
+    applyTransitionTerminal(event: PrimitiveTransitionEvent, mailboxPosition: number, progress: TransportedSampleProgressWriter): TransportedTerminalApplication;
+    applyLifecycleTerminal(event: MotionValueLifecycleTerminalEvent, mailboxPosition: number, progress: TransportedSampleProgressWriter): TransportedTerminalApplication;
+}
+export interface CreateMotionValueDriverPortOptions<T> {
+    readonly value: MotionValue<T>;
+    readonly clock: Clock;
+    readonly channelId: number;
+    readonly rawSnapshot: CollectorSilentMotionValueRawSnapshot<T>;
+    readonly initialState?: MotionValueDriverPortState;
+    /**
+     * Required when `initialState.publicControlSlot` is installed. The primitive state intentionally
+     * carries only stable ids; this non-serializable companion restores the exact stop capability.
+     */
+    readonly initialPublicControlSlotInstallation?: MotionValuePublicControlSlotInstallation;
+}
+/**
+ * The one private direct-public creation seam used by native `useMotionValue`. It returns the exact
+ * graph object and records immutable initializer provenance without widening the public graph API.
+ */
+export declare function createDirectPublicMotionValue<T>(graph: MotionGraph, initial: T): MotionValue<T>;
+/**
+ * Private mount-time routing predicate for the identity channel. It reads only the immutable
+ * creation brand plus the caller's collector-silent mount snapshot; behavioral eligibility remains
+ * owned by `MotionValueDriverPort.evaluateBindingEligibility` once the canonical port is attached.
+ */
+export declare function isDirectPublicNumericMotionValue(value: MotionValue<unknown>, currentValue: unknown): value is MotionValue<number>;
+export declare function createLocalFrameEventPort(options: CreateLocalFrameEventPortOptions): LocalFrameEventPort;
+export declare function createMotionValueDriverPort<T>(options: CreateMotionValueDriverPortOptions<T>): MotionValueDriverPort<T>;
+export {};