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

package/dist/layout/identity.d.cts

@@ -0,0 +1,67 @@
+import { type SpringConfig } from "../transition.cjs";
+import { type TimingConfig } from "../timing.cjs";
+import type { MotionGraph } from "../types.cjs";
+import { type LayoutIdToken, type Transform, type WindowSpaceRect } from "./types.cjs";
+export type LayoutIdentityRole = 'sole' | 'lead';
+/**
+ * Opaque pre-resolved holder handle, minted once per holder at enter() (round-7 major 4): the
+ * per-frame readInto(handle, out) dereferences it O(1) instead of re-resolving the token through
+ * a linear holder scan per painted holder per frame (H painted holders on one id were H×H
+ * comparisons, REQ-DRIVER-015/021). Valid while the registry tracks the holder (holders ∪
+ * exiting); a departed holder's handle fails loud exactly like the by-token read discipline.
+ * The brand keeps the internals private — callers never construct or inspect one.
+ */
+export interface IdentityHolderHandle {
+    readonly __identityHolderHandle: true;
+}
+/** The result of enter(): the one-time role plus the durable per-holder handle. */
+export interface IdentityEnterResult {
+    readonly role: LayoutIdentityRole;
+    readonly handle: IdentityHolderHandle;
+}
+export interface IdentityRead {
+    readonly transform: Transform;
+    readonly opacity: number;
+}
+export interface IdentityHolderWrite {
+    translateX: number;
+    translateY: number;
+    scaleX: number;
+    scaleY: number;
+    opacity: number;
+    zLifted: boolean;
+}
+export interface LayoutIdentityRegistryOptions {
+    readonly graph: MotionGraph;
+    readonly spring?: SpringConfig;
+}
+/**
+ * Per-edge flight options for layout-identity lifecycle (enter / commitRect / leave).
+ * `instant: true` settles the shared flight + crossfade on the same edge — pin `type: false`
+ * under MotionConfig reducedMotion / skipAnimations / isStatic (REQ-API-035 layout lane).
+ * `timing` (family-3): duration/ease tween for the shared projection flight + crossfade scalar
+ * when a layoutId host authors `transition={{ duration }}` (TimingConfig is ms, not seconds).
+ * `spring` (T22): a per-flight engine SpringConfig (ms — physics or time-defined) when the host
+ * authors `type: 'spring'`; absent, the registry-global default flies. One edge carries at most
+ * one of `timing`/`spring` — the host resolver is single-outcome (fail loud on both).
+ */
+export interface LayoutIdentityFlightOptions {
+    readonly instant?: boolean;
+    readonly timing?: TimingConfig;
+    readonly spring?: SpringConfig;
+}
+export interface LayoutIdentityRegistry {
+    enter(id: string, holder: LayoutIdToken, rect: WindowSpaceRect | null, options?: LayoutIdentityFlightOptions): IdentityEnterResult;
+    commitRect(id: string, holder: LayoutIdToken, rect: WindowSpaceRect, options?: LayoutIdentityFlightOptions): void;
+    leave(id: string, holder: LayoutIdToken, options?: LayoutIdentityFlightOptions): void;
+    read(id: string, holder: LayoutIdToken): IdentityRead;
+    readInto(handle: IdentityHolderHandle, out: IdentityHolderWrite): void;
+    releasable(id: string, holder: LayoutIdToken): boolean;
+    zLifted(id: string, holder: LayoutIdToken): boolean;
+    isSettled(id: string): boolean;
+    holds(id: string, holder: LayoutIdToken): boolean;
+    isLead(id: string, holder: LayoutIdToken): boolean;
+    tickExclusiveHandoffs(): void;
+    hasPendingExclusiveHandoffs(): boolean;
+}
+export declare function createLayoutIdentityRegistry(options: LayoutIdentityRegistryOptions): LayoutIdentityRegistry;

package/dist/layout/identity.d.ts

@@ -0,0 +1,67 @@
+import { type SpringConfig } from "../transition.js";
+import { type TimingConfig } from "../timing.js";
+import type { MotionGraph } from "../types.js";
+import { type LayoutIdToken, type Transform, type WindowSpaceRect } from "./types.js";
+export type LayoutIdentityRole = 'sole' | 'lead';
+/**
+ * Opaque pre-resolved holder handle, minted once per holder at enter() (round-7 major 4): the
+ * per-frame readInto(handle, out) dereferences it O(1) instead of re-resolving the token through
+ * a linear holder scan per painted holder per frame (H painted holders on one id were H×H
+ * comparisons, REQ-DRIVER-015/021). Valid while the registry tracks the holder (holders ∪
+ * exiting); a departed holder's handle fails loud exactly like the by-token read discipline.
+ * The brand keeps the internals private — callers never construct or inspect one.
+ */
+export interface IdentityHolderHandle {
+    readonly __identityHolderHandle: true;
+}
+/** The result of enter(): the one-time role plus the durable per-holder handle. */
+export interface IdentityEnterResult {
+    readonly role: LayoutIdentityRole;
+    readonly handle: IdentityHolderHandle;
+}
+export interface IdentityRead {
+    readonly transform: Transform;
+    readonly opacity: number;
+}
+export interface IdentityHolderWrite {
+    translateX: number;
+    translateY: number;
+    scaleX: number;
+    scaleY: number;
+    opacity: number;
+    zLifted: boolean;
+}
+export interface LayoutIdentityRegistryOptions {
+    readonly graph: MotionGraph;
+    readonly spring?: SpringConfig;
+}
+/**
+ * Per-edge flight options for layout-identity lifecycle (enter / commitRect / leave).
+ * `instant: true` settles the shared flight + crossfade on the same edge — pin `type: false`
+ * under MotionConfig reducedMotion / skipAnimations / isStatic (REQ-API-035 layout lane).
+ * `timing` (family-3): duration/ease tween for the shared projection flight + crossfade scalar
+ * when a layoutId host authors `transition={{ duration }}` (TimingConfig is ms, not seconds).
+ * `spring` (T22): a per-flight engine SpringConfig (ms — physics or time-defined) when the host
+ * authors `type: 'spring'`; absent, the registry-global default flies. One edge carries at most
+ * one of `timing`/`spring` — the host resolver is single-outcome (fail loud on both).
+ */
+export interface LayoutIdentityFlightOptions {
+    readonly instant?: boolean;
+    readonly timing?: TimingConfig;
+    readonly spring?: SpringConfig;
+}
+export interface LayoutIdentityRegistry {
+    enter(id: string, holder: LayoutIdToken, rect: WindowSpaceRect | null, options?: LayoutIdentityFlightOptions): IdentityEnterResult;
+    commitRect(id: string, holder: LayoutIdToken, rect: WindowSpaceRect, options?: LayoutIdentityFlightOptions): void;
+    leave(id: string, holder: LayoutIdToken, options?: LayoutIdentityFlightOptions): void;
+    read(id: string, holder: LayoutIdToken): IdentityRead;
+    readInto(handle: IdentityHolderHandle, out: IdentityHolderWrite): void;
+    releasable(id: string, holder: LayoutIdToken): boolean;
+    zLifted(id: string, holder: LayoutIdToken): boolean;
+    isSettled(id: string): boolean;
+    holds(id: string, holder: LayoutIdToken): boolean;
+    isLead(id: string, holder: LayoutIdToken): boolean;
+    tickExclusiveHandoffs(): void;
+    hasPendingExclusiveHandoffs(): boolean;
+}
+export declare function createLayoutIdentityRegistry(options: LayoutIdentityRegistryOptions): LayoutIdentityRegistry;