@flemo/core 1.29.0 → 2.0.0

package/dist/platform/profile.d.ts

@@ -0,0 +1,70 @@
+export interface PlatformProfile {
+    /**
+     * This engine presents its compiled screen animations FROM THE MAIN THREAD
+     * (WebKit) rather than off the compositor (Blink). Everything about
+     * protecting a flight's opening follows from this one fact: where the clock
+     * is stamped on the main thread, a heavy commit between the stamp and the
+     * first paint is aged away rather than ridden through.
+     */
+    readonly mainThreadPresented: boolean;
+    /**
+     * Flip the hold attribute straight onto the DOM inside the readiness rAF
+     * instead of routing the release through a state commit. A rAF callback and
+     * its own frame's rendering update are atomic, so clock-start and first paint
+     * become simultaneous by construction.
+     *
+     * Device-verified on three populations; see readDesktopReleaseFlipFlag. An
+     * authored `driver: "native"` transition takes it too — pass
+     * `authoredNativeDriver` to fold that in.
+     */
+    readonly atomicReleaseFlip: boolean;
+    /**
+     * Hand the release's reconcile to the NEXT frame rather than flushing it
+     * synchronously, so it stops competing with the flight's first present.
+     * Only meaningful where the flip already released the hold — without the
+     * flip, the state commit IS the release.
+     */
+    readonly deferReleaseCommit: boolean;
+    /**
+     * Hold the release until the entering screen's mount render quiesces, so a
+     * heavy screen's own commit storm cannot eat the opening frames.
+     */
+    readonly renderSettleGate: boolean;
+    /**
+     * Park a push's entering screen ON TOP at near-zero opacity (so the browser
+     * genuinely paints its tiles during the hold) rather than beneath its cover.
+     */
+    readonly parkOver: boolean;
+    /**
+     * Keep the screen scope's layer promoted at REST. Off everywhere by default:
+     * a promotion is also a stacking context, and at rest it outranks any
+     * consumer overlay inside the screen.
+     */
+    readonly restLayerPromotion: boolean;
+    /**
+     * Rewrite oversized `<img>` sources to decoded-to-scale blobs off the main
+     * thread. Auto on legacy Android Blink only — it touches consumer content,
+     * so it must never run where the paint is already cheap.
+     */
+    readonly imageDecodeOffload: boolean;
+}
+export interface PlatformProfileInput {
+    /**
+     * The transition being flown authored `driver: "native"` — an explicit opt-in
+     * to clock surgery, which carries the atomic release flip with it. The
+     * binding knows this and core does not, so it is the one input the profile
+     * takes.
+     */
+    readonly authoredNativeDriver?: boolean;
+}
+export declare const resolvePlatformProfile: (input?: PlatformProfileInput) => PlatformProfile;
+/**
+ * The REST-promotion decision on its own, as a module-stable function.
+ *
+ * A binding that server-renders must read this through a hydration-scoped
+ * snapshot (it reaches the DOM as an inline style, so a render-phase read
+ * mismatches the server HTML), and React's `useSyncExternalStore` requires the
+ * reader identity to be stable across renders — which an inline
+ * `() => resolvePlatformProfile().restLayerPromotion` would not be.
+ */
+export declare const restLayerPromotionEnabled: () => boolean;

package/dist/{core/engine → platform}/steadySixtyCadence.d.ts

@@ -1,5 +1,5 @@
 export declare const HIGH_REFRESH_MAX_INTERVAL_MS = 12;
 export declare const reportInFlightCadence: (rawMedianMs: number, rawMaxMs?: number) => void;
 export declare const steadySixtyVerified: () => boolean;
-export declare const steadySixtyPlayerEligible: () => boolean;
+export declare const steadySixtyDesktopProfile: () => boolean;
 export declare const resetSteadySixtyForTests: () => void;

package/dist/runtime/__tests__/flemoRuntime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/flemoRuntime.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Start flemo's ambient machinery, and return the release for this holder.
+ *
+ * A binding calls this once per Router mount and releases on unmount. Repeat
+ * calls share one runtime; the last release tears it down. Safe on the server:
+ * every piece degrades to a no-op without a document.
+ */
+export declare const startFlemoRuntime: () => (() => void);
+export declare const resetFlemoRuntimeForTests: () => void;

package/dist/transition/compileTransitionStyles.d.ts

@@ -9,7 +9,6 @@ export type CssDecl = {
 export declare const collectAnimatedProperties: (transition: Pick<Transition, "initial" | "variants">) => string[];
 export declare const targetToDecls: (target: TransitionVariantValue["value"] | InitialTarget) => CssDecl[];
 export declare const easingToCss: (ease: AnimationOptions["ease"] | undefined) => string;
-export declare const softenFrontLoadedEasing: (easingCss: string, durationS: number) => string | null;
 export declare const animationName: (scope: "screen" | "decorator" | "part", name: string, variant: TransitionVariant) => string;
 export declare const HEAD_ANIMATION_SUFFIXES: readonly ["-gov", "-deskhead", "-govcreep"];
 export declare const matchesFlightAnimationName: (eventName: string, expectedName: string) => boolean;

package/dist/transition/cubicBezier.d.ts

@@ -1,4 +1,29 @@
 import { AnimationOptions } from './cssTypes';
 export type EasingFunction = (progress: number) => number;
 export declare const cubicBezier: (x1: number, y1: number, x2: number, y2: number) => EasingFunction;
+/**
+ * The INVERSE of a CSS timing function: given the value progress you want to
+ * see, the time progress that produces it.
+ *
+ * A scrubbed animation needs this. Setting an animation's clock to the drag's
+ * fraction moves the CLOCK linearly, and what the eye follows is the curve's
+ * output — with an ease that opens slowly, a finger a tenth of the way across
+ * moves the element a fiftieth, and everything it did not do is left for the
+ * release to rush through. Inverting the curve makes the element track the
+ * finger and leaves the release only what is really left.
+ *
+ * Binary search on y, the same shape as `cubicBezier`'s search on x. An
+ * overshooting curve (`backOut`, `anticipate`) is not monotonic in y, so the
+ * search returns the first crossing — which is the one before the overshoot,
+ * and the only one a drag can mean.
+ */
+export declare const invertEasing: (ease: AnimationOptions["ease"] | undefined) => EasingFunction;
+/**
+ * The control points behind an authored ease, named or spelled out — `null`
+ * for `linear`, which has no handles to work with.
+ *
+ * Exported for the swipe release, which re-aims an authored curve's opening
+ * slope onto the gesture that produced it (see swipeSettle.ts).
+ */
+export declare const easeControlPoints: (ease: AnimationOptions["ease"] | undefined) => [number, number, number, number] | null;
 export declare const resolveEasing: (ease: AnimationOptions["ease"] | undefined) => EasingFunction;

package/dist/transition/morphTransition/__tests__/createMorphTransition.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transition/morphTransition/createMorphTransition.d.ts

@@ -0,0 +1,13 @@
+import { InitialTarget } from '../cssTypes';
+import { TransitionVariantValue } from '../typing';
+import { MorphTransition, MorphTransitionName, MorphTransitionOptions } from './typing';
+interface CreateMorphProps {
+    name: MorphTransitionName;
+    initial: InitialTarget;
+    idle: TransitionVariantValue;
+    enter: TransitionVariantValue;
+    exit: TransitionVariantValue;
+    options?: MorphTransitionOptions;
+}
+export default function createMorphTransition({ name, initial, idle, enter, exit, options }: CreateMorphProps): MorphTransition;
+export {};

package/dist/transition/morphTransition/createRawMorphTransition.d.ts

@@ -0,0 +1,17 @@
+import { InitialTarget } from '../cssTypes';
+import { TransitionVariantValue } from '../typing';
+import { MorphTransition, MorphTransitionName, MorphTransitionOptions } from './typing';
+interface CreateRawMorphProps {
+    name: MorphTransitionName;
+    initial: InitialTarget;
+    idle: TransitionVariantValue;
+    pushOnEnter: TransitionVariantValue;
+    pushOnExit: TransitionVariantValue;
+    replaceOnEnter: TransitionVariantValue;
+    replaceOnExit: TransitionVariantValue;
+    popOnEnter: TransitionVariantValue;
+    popOnExit: TransitionVariantValue;
+    options?: MorphTransitionOptions;
+}
+export default function createRawMorphTransition({ name, initial, idle, pushOnEnter, pushOnExit, replaceOnEnter, replaceOnExit, popOnEnter, popOnExit, options }: CreateRawMorphProps): MorphTransition;
+export {};

package/dist/transition/morphTransition/morphTransition.d.ts

@@ -0,0 +1,2 @@
+import { MorphTransition, MorphTransitionName } from './typing';
+export declare const morphTransitionMap: Map<MorphTransitionName, MorphTransition>;

package/dist/transition/morphTransition/shared.d.ts

@@ -0,0 +1,2 @@
+declare const shared: import('./typing').MorphTransition;
+export default shared;

package/dist/transition/morphTransition/text.d.ts

@@ -0,0 +1,2 @@
+declare const text: import('./typing').MorphTransition;
+export default text;

package/dist/transition/morphTransition/typing.d.ts

@@ -0,0 +1,72 @@
+import { BaseTransition, TransitionVariant } from '../typing';
+export interface RegisterMorphTransition {
+}
+export type MorphTransitionName = RegisterMorphTransition[keyof RegisterMorphTransition] | "shared" | "text" | "zoom" | (string & {});
+/** The preset every morph falls back to when no name is given. */
+export declare const DEFAULT_MORPH_TRANSITION_NAME = "shared";
+export type MorphTransitionOptions = {
+    /**
+     * The share of the flight over which the GHOST dissolves — the copy of the
+     * element being replaced that the runtime carries inside the flight (0–1,
+     * default 0.55).
+     *
+     * It is what makes a travel show the right thing at both ends: the flight
+     * begins as an exact copy of what was on glass and dissolves into the real
+     * arriving element while the box moves. Set it to 0 to carry no copy, which
+     * cuts straight to the arrival's content on the first frame.
+     *
+     * The arriving element stays opaque underneath throughout. Fading both would
+     * bleed the background through the pair by a(1 - a) — a luminance dip
+     * peaking at 25% in the middle of the hand-over.
+     *
+     * THE WINDOW IS WHAT THE DEPARTURE'S OWN CONTENT LEAVES OVER. This used to be
+     * 0.22 — three frames of a short flight — on the reasoning that holding the
+     * copy longer let the two layouts drift apart underneath it and print as
+     * doubled text. That reasoning was written when the copy painted everything,
+     * including the paired elements. It does not now: a paired descendant is
+     * already invisible in the copy (the real one is morphing underneath it), so
+     * all the copy is holding is content with NO counterpart — a caption, a body
+     * paragraph, a button that exists on one side only. Three frames is not that
+     * content leaving; it is that content being cut, which is exactly what a pop
+     * looked like next to the arrival it was supposed to reverse.
+     */
+    crossFade?: number;
+    /**
+     * Interpolate `border-radius` across the flight (default true). Nothing is
+     * scaled, so the two ends' own values are the whole story.
+     *
+     * It rides the CONTENT animation, never the geometry one: a keyframe that
+     * lists a property the compositor cannot animate drops that whole animation
+     * to the main thread, and the geometry keyframe is the one that must never
+     * leave the compositor.
+     */
+    radius?: boolean;
+    /**
+     * Move the whole screen with the element, not just the element (default off).
+     *
+     * A plain morph flies ALONE: the element crosses while the screens do
+     * whatever their own transition says, which is right when the element is one
+     * thing among many. It is wrong when the element IS the navigation — a grid
+     * cell opening into a full-screen view. There the eye reads the tap as
+     * "the camera moved to this card", and a grid that stays put underneath
+     * reads as the card escaping from it.
+     *
+     * `"screen"` gives the flight a camera: the screen the element is SMALL on
+     * (the grid — the departing screen on a push, the arriving one on a pop) is
+     * scaled and translated by exactly the zoom that takes the element from one
+     * end to the other, so every other card moves as though the viewport had
+     * pushed in on the tapped one. Material calls the pattern a container
+     * transform; iOS 18 calls its version a zoom transition.
+     *
+     * It SUPERSEDES that screen's own transform for the length of the flight —
+     * the camera IS the screen's motion here, and two authors of one transform
+     * is not a thing CSS can compose. Pair it with a transition that does not
+     * move the screen itself (`none`, or an opacity-only one); a slide would be
+     * replaced rather than combined.
+     */
+    carry?: "screen";
+};
+export interface MorphTransition extends Omit<BaseTransition, "name">, MorphTransitionOptions {
+    name: MorphTransitionName;
+}
+export declare const MORPH_FROM_VARIANT: Record<TransitionVariant, "initial" | "IDLE-true" | "self">;

package/dist/transition/morphTransition/zoom.d.ts

@@ -0,0 +1,2 @@
+declare const zoom: import('./typing').MorphTransition;
+export default zoom;

package/dist/transition/registerTransitionDefinitions.d.ts

@@ -1,4 +1,5 @@
 import { Transition } from './typing';
 import { Decorator } from './decorator/typing';
+import { MorphTransition } from './morphTransition/typing';
 import { PartTransition } from './partTransition/typing';
-export default function registerTransitionDefinitions(transitions: Transition[], decorators: Decorator[], partTransitions?: PartTransition[]): () => void;
+export default function registerTransitionDefinitions(transitions: Transition[], decorators: Decorator[], partTransitions?: PartTransition[], morphTransitions?: MorphTransition[]): () => void;

package/dist/transition/swipeSettle.d.ts

@@ -1,4 +1,22 @@
 export declare const MIN_SETTLE_SECONDS = 0.12;
+/**
+ * The initial slope a release curve is allowed to reach, as a multiple of its
+ * own average speed — the ceiling on "the finger was going fast".
+ *
+ * It is also what the by-speed length is derived from: a curve that starts at
+ * the finger's speed and decelerates to rest covers the remaining distance in
+ * `slope x remaining / speed`, not `remaining / speed`. The old formula solved
+ * for a motion that never slows down, which no landing does.
+ */
+export declare const RELEASE_LAUNCH_SLOPE = 1.6;
+/**
+ * The floor on that slope. A very slow drag with most of the screen left
+ * cannot be honored literally — matching 150 px/s over 310px would take two
+ * seconds — so the settle does accelerate away from it. It leaves at half its
+ * average rather than at 2.25x, which is the difference between the system
+ * taking over and the screen being snatched.
+ */
+export declare const MIN_LAUNCH_SLOPE = 0.5;
 export declare const MIN_REVERSAL_SECONDS = 0.28;
 export interface SwipeSettleInput {
     remainingPx: number;
@@ -6,6 +24,69 @@ export interface SwipeSettleInput {
     velocityPxPerSecond: number;
     reversing?: boolean;
     authoredSeconds: number;
+    /**
+     * The authored curve's control points. Given them, the distance term is the
+     * time that curve itself spends on the stretch that is left; without them it
+     * falls back to reading the motion as linear, which is what this used to do
+     * for every transition.
+     */
+    authoredEase?: readonly [number, number, number, number];
     minSeconds?: number;
 }
-export declare const swipeSettleSeconds: ({ remainingPx, spanPx, velocityPxPerSecond, authoredSeconds, reversing, minSeconds }: SwipeSettleInput) => number;
+/**
+ * How long the authored curve takes to travel its LAST `1 - progress` — the
+ * stretch a release that let go at `progress` still has to cover.
+ *
+ * The curve maps time to distance, so this inverts it: find the time at which
+ * it has covered `progress`, and return what is left of the duration. Both
+ * searches are on a monotone function.
+ */
+export declare const authoredTailSeconds: (progress: number, authoredSeconds: number, ease: readonly [number, number, number, number]) => number;
+export declare const swipeSettleSeconds: ({ remainingPx, spanPx, velocityPxPerSecond, authoredSeconds, authoredEase, reversing, minSeconds }: SwipeSettleInput) => number;
+/**
+ * The release curve's normalized initial slope: the speed the settle leaves at,
+ * as a multiple of its own average. `velocity x seconds / remaining` is exactly
+ * the finger's speed expressed in those units.
+ *
+ * ONE RULE, INCLUDING THE CANCEL. A reversal's finger was going the other way,
+ * so the speed it contributes to the settle's own direction is not its own
+ * speed — it is zero or less. Zero is what this reads it as, which puts every
+ * reversal on the floor: the screen is standing still when the settle begins,
+ * and it opens like something standing still.
+ *
+ * Full velocity continuity for a reversal would mean OVERSHOOT — the screen
+ * carrying on the way the finger was pushing for a hair before it returns,
+ * which is what a real spring does. That is a different primitive, not a
+ * re-aimed bezier, and it is deliberately not attempted here. Clamping at zero
+ * is the closest a monotone curve gets.
+ */
+export declare const releaseLaunchSlope: ({ remainingPx, velocityPxPerSecond, seconds, authoredSlope, reversing }: {
+    remainingPx: number;
+    velocityPxPerSecond: number;
+    seconds: number;
+    /**
+     * The opening slope the transition's author drew. The floor never rises
+     * above it: a release that the gesture cannot support must not come out
+     * HARDER than the authored motion — the floor is there to stop a crawl, not
+     * to add energy the author did not ask for. The ceiling is not capped this
+     * way; a finger genuinely moving fast should leave fast, even out of a curve
+     * drawn to open gently, or the screen reads as braking the moment it is let
+     * go.
+     */
+    authoredSlope?: number;
+    reversing?: boolean;
+}) => number | null;
+/**
+ * Re-aim an authored cubic-bezier so it LEAVES at `slope` times its average
+ * speed, keeping its x handles and its landing.
+ *
+ * Only `y1` moves. `x1`/`x2` are the authored ones, so the result is still a
+ * valid CSS timing function by construction (x monotonicity is a property of
+ * the x handles alone) and still lands the way the transition's author drew it
+ * — the release differs from the authored curve exactly where the gesture
+ * differs from a standing start, and nowhere else.
+ *
+ * `y1` is capped below 1 so the curve cannot overshoot its own target; where a
+ * steep slope would need more, `x1` shrinks to buy it instead.
+ */
+export declare const reaimReleaseEase: (authored: readonly [number, number, number, number], slope: number) => [number, number, number, number];

package/dist/transition/typing.d.ts

@@ -30,7 +30,7 @@ export interface SwipeInfo {
 export type SwipeAnimate = (target: HTMLElement, value: TransitionTarget, options?: AnimationOptions) => Promise<void>;
 export type TransitionOptions = {
     decoratorName?: DecoratorName;
-    driver?: "native" | "player";
+    driver?: "native";
     swipeDirection: "x" | "y";
     onSwipeStart: (event: PointerEvent, info: SwipeInfo, options: {
         animate: SwipeAnimate;
@@ -52,7 +52,7 @@ export type TransitionOptions = {
     }) => Promise<boolean>;
 } | {
     decoratorName?: DecoratorName;
-    driver?: "native" | "player";
+    driver?: "native";
     swipeDirection?: never;
 };
 export interface BaseTransition {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flemo/core",
-  "version": "1.29.0",
+  "version": "2.0.0",
   "description": "Framework-agnostic primitives for flemo: history, navigation, transitions, task manager.",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
@@ -33,20 +33,20 @@
   "license": "MIT",
   "dependencies": {
     "path-to-regexp": "^8.4.2",
-    "zustand": "^5.0.14"
+    "zustand": "^5.0.15"
   },
   "devDependencies": {
+    "@flemo/eslint-config": "0.0.0",
+    "@flemo/tsconfig": "0.0.0",
     "@types/node": "^24.13.1",
-    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.11",
     "csstype": "^3.2.3",
     "eslint": "^9.39.5",
     "jsdom": "^29.1.1",
     "typescript": "^6.0.3",
-    "vite": "^8.2.1",
+    "vite": "^8.2.2",
     "vite-plugin-dts": "^5.0.3",
-    "vitest": "^4.1.10",
-    "@flemo/tsconfig": "0.0.0",
-    "@flemo/eslint-config": "0.0.0"
+    "vitest": "^4.1.11"
   },
   "publishConfig": {
     "access": "public"

package/dist/core/engine/driverPolicy.d.ts

@@ -1,12 +0,0 @@
-export declare const FORCE_PIN_TTL_MS: number;
-export interface DriverPolicy {
-    playerAllowed: () => boolean;
-    pinnedDriver: () => "css" | "raf" | null;
-}
-export declare const detectBlinkEngine: () => boolean;
-export declare const isLegacyAndroidBlink: () => boolean;
-export declare const isDesktopMacWebKit: () => boolean;
-export declare const isDesktopBlink: () => boolean;
-export declare const createDriverPolicy: (playerByDefault?: boolean) => DriverPolicy;
-declare const driverPolicy: DriverPolicy;
-export default driverPolicy;

package/dist/core/engine/landingPixelSnap.d.ts

@@ -1,10 +0,0 @@
-import { VariantMotion } from '../../transition/variantMotion';
-import { PerceptualBox } from './perceptualSpan';
-export declare const SNAP_VELOCITY_DEVICE_PX_PER_FRAME = 40;
-export declare const SNAP_BAND_MAX_DEVICE_PX = 480;
-export declare const snappedEasingForMotion: (motion: VariantMotion, box: PerceptualBox, devicePixelRatio: number) => string | null;
-export declare const governedEasingForMotion: (motion: VariantMotion, box: PerceptualBox, devicePixelRatio: number, frameIntervalMs: number) => string | null;
-export declare const governedBezierForMotion: (motion: VariantMotion | null, box: PerceptualBox, devicePixelRatio: number, frameIntervalMs: number) => {
-    easing: string;
-    durationMs: number;
-} | null;

package/dist/core/engine/motionDriverKind.d.ts

@@ -1,7 +0,0 @@
-import { Transition } from '../../transition/typing';
-import { VariantMotion } from '../../transition/variantMotion';
-import { PerceptualBox } from './perceptualSpan';
-export declare const NATIVE_PEAK_CSS_PX_PER_FRAME = 6;
-export declare const peakTranslationPxPerFrame: (motion: VariantMotion, box: PerceptualBox) => number | null;
-export type MotionDriverKind = "native" | "player";
-export declare const classifyTransitionDriver: (transition: Transition, _status: string, _box: PerceptualBox) => MotionDriverKind;

package/dist/core/engine/transitionPlayer.d.ts

@@ -1,40 +0,0 @@
-import { VariantMotion } from '../../transition/variantMotion';
-export { resetSessionOverrideCachesForTests } from './diagnosticFlags';
-export declare const isPlayerDrivable: (motion: VariantMotion) => boolean;
-export interface SnapMemory {
-    x: number | null;
-    y: number | null;
-    landingX?: number | null;
-    landingY?: number | null;
-    writtenX?: number | null;
-    writtenY?: number | null;
-    pendingLanding?: boolean;
-    glide?: boolean;
-}
-export declare const learnedFrameIntervalMs: () => number;
-export declare const reportDisplayIntervalMs: (intervalMs: number) => void;
-export interface PlayerScheduler {
-    request: (callback: (time: number) => void) => number;
-    cancel: (handle: number) => void;
-    devicePixelRatio: () => number;
-}
-export interface TrackInput {
-    element: HTMLElement;
-    motion: VariantMotion;
-    role: "active" | "passive";
-    onComplete?: () => void;
-    status?: string;
-}
-export interface TransitionPlayerRegistry {
-    join: (taskId: string, input: TrackInput) => (() => void) | null;
-    dispose: (taskId: string) => void;
-    onFrameGap?: (gapMs: number) => void;
-}
-export declare const createTransitionPlayerRegistry: (scheduler?: PlayerScheduler) => TransitionPlayerRegistry;
-declare const transitionPlayers: TransitionPlayerRegistry;
-export default transitionPlayers;
-declare global {
-    interface Window {
-        __flemoPlayerGaps?: number[];
-    }
-}