@flemo/core 1.29.0 → 1.30.0

package/dist/navigate/store.d.ts

@@ -1,5 +1,6 @@
 import { StoreApi } from 'zustand/vanilla';
 export type NavigateStatus = "IDLE" | "PUSHING" | "REPLACING" | "POPPING" | "COMPLETED";
+export declare const TRANSITIONAL_STATUS_VALUES: readonly ["PUSHING", "POPPING", "REPLACING"];
 export interface NavigateStore {
     status: NavigateStatus;
     transitionTaskId: string | null;

package/dist/platform/__tests__/displayCadence.test.d.ts

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

package/dist/platform/__tests__/displayProbe.test.d.ts

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

package/dist/platform/__tests__/engineProbes.test.d.ts

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

package/dist/platform/__tests__/legacyBlinkGate.test.d.ts

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

package/dist/platform/__tests__/profile.test.d.ts

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

package/dist/platform/__tests__/steadySixtyCadence.test.d.ts

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

package/dist/platform/displayCadence.d.ts

@@ -0,0 +1,3 @@
+export declare const learnedFrameIntervalMs: () => number;
+export declare const reportDisplayIntervalMs: (intervalMs: number) => void;
+export declare const resetDisplayCadenceForTests: () => void;

package/dist/platform/displayProbe.d.ts

@@ -0,0 +1,5 @@
+export declare const COMPILED_TIER_MAX_INTERVAL_MS = 12;
+export declare const armFramePacingKeepalive: () => (() => void);
+export declare const cancelDisplayIntervalProbe: () => void;
+export declare const resetDisplayProbeForTests: () => void;
+export declare const armDisplayIntervalProbe: () => void;

package/dist/platform/engineProbes.d.ts

@@ -0,0 +1,4 @@
+export declare const detectBlinkEngine: () => boolean;
+export declare const isLegacyAndroidBlink: () => boolean;
+export declare const isDesktopMacWebKit: () => boolean;
+export declare const isDesktopBlink: () => boolean;

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,12 @@
 import { AnimationOptions } from './cssTypes';
 export type EasingFunction = (progress: number) => number;
 export declare const cubicBezier: (x1: number, y1: number, x2: number, y2: number) => 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/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": "1.30.0",
   "description": "Framework-agnostic primitives for flemo: history, navigation, transitions, task manager.",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
@@ -45,8 +45,8 @@
     "vite": "^8.2.1",
     "vite-plugin-dts": "^5.0.3",
     "vitest": "^4.1.10",
-    "@flemo/tsconfig": "0.0.0",
-    "@flemo/eslint-config": "0.0.0"
+    "@flemo/eslint-config": "0.0.0",
+    "@flemo/tsconfig": "0.0.0"
   },
   "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[];
-    }
-}