@flemo/core 2.1.0 → 2.2.0

package/dist/platform/profile.d.ts

@@ -13,7 +13,7 @@ export interface PlatformProfile {
      * 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
+     * Device-verified on three populations; see the resolver below. An
      * authored `driver: "native"` transition takes it too — pass
      * `authoredNativeDriver` to fold that in.
      */
@@ -35,12 +35,6 @@ export interface PlatformProfile {
      * 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,
@@ -57,14 +51,46 @@ export interface PlatformProfileInput {
      */
     readonly authoredNativeDriver?: boolean;
 }
-export declare const resolvePlatformProfile: (input?: PlatformProfileInput) => PlatformProfile;
 /**
- * The REST-promotion decision on its own, as a module-stable function.
+ * The render-settle entry gate, as its own predicate — the flight routing asks
+ * for it directly (a PUSH only forces the compiled tier behind the gate), and
+ * the profile publishes it as `renderSettleGate`. One definition, because the
+ * two drifted apart once already: the ARMING widened in the react binding while
+ * core's stayed WebKit-only, and Android ran ungated for two release rounds.
+ *
+ * ON for touch WebKit (governedCompiledActive — the governed-compiled tier
+ * ships with it), for steady-60 desktop Blink sessions, for touch Blink, AND
+ * for desktop macOS Safari.
  *
- * 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.
+ * The steady-60 desktop term is a PROFILE, not a driver claim. It was written
+ * when a verified steady-60 session routed to the player, whose main-thread
+ * per-frame write the entering mount commit would stall; that routing is gone
+ * (Blink runs compiled everywhere since 2026-08-19) but the term stays, because
+ * the reason that survives is the tier-independent one: the measured ~50ms
+ * desktop mount hitch ages a wall-clocked compiled animation just as it starved
+ * the player.
+ *
+ * Touch Blink was the gap: the pop-convergence round (de35c13) widened the
+ * arming to "ALL engines" after a device A/B on a demoted Note 9 falsified the
+ * WebKit-only reading — its heavy detail mount runs a ~290ms main-thread task
+ * that stalls even the compositor's initial commit, so gating the release to
+ * AFTER that task measurably helped. Re-confirmed on the same device class
+ * 2026-08-19.
+ *
+ * Desktop macOS Safari was the same gap one platform over. It runs the compiled
+ * tier on purpose (macOS Safari caps rAF at 60Hz), but WebKit presents compiled
+ * animations from the MAIN THREAD, so a heavy entering mount eats the opening
+ * exactly as it does on a phone. Frame-level measurement of the docs site's own
+ * Home -> Showcase push (2026-08-20, production build, WebKit): the entering
+ * screen's mount blocked the main thread for 103-135ms while the animation's
+ * clock ran, so the FIRST presented frame already stood at 48-77% progress; the
+ * release commit then re-anchored the animation and it replayed from zero — a
+ * jump followed by a rewind, both visible. The same flight on Chromium was
+ * clean, which is why it read as Safari-only.
+ *
+ * The gate is adaptive, which is why this is safe to arm widely: with no
+ * qualifying mount commit inside firstWaitMs it releases with no felt delay, so
+ * a fast phone pays nothing for carrying it.
  */
-export declare const restLayerPromotionEnabled: () => boolean;
+export declare const settleGateActive: () => boolean;
+export declare const resolvePlatformProfile: (input?: PlatformProfileInput) => PlatformProfile;

package/dist/screen/__tests__/partLayer.test.d.ts

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

package/dist/screen/computeScreenFreeze.d.ts

@@ -1,5 +1,4 @@
 import { NavigateStatus } from '../navigate/store';
-export { resetShallowFreezeForTesting } from '../core/engine/diagnosticFlags';
 export interface ScreenFreezeInput {
     isActive: boolean;
     isPrev: boolean;

package/dist/screen/partLayer.d.ts

@@ -0,0 +1,14 @@
+import { NavigateStoreApi } from '../navigate/store';
+/**
+ * Publish the element a scope's shared-bar parts should be staged in. A binding
+ * calls this from its Router lifecycle — the Router is the only thing that knows
+ * which box bounds its screens.
+ */
+export declare const registerPartLayer: (store: NavigateStoreApi, element: HTMLElement | null) => void;
+/**
+ * The layer to stage a flight's bar parts in, creating a document-level fallback
+ * for a binding that publishes none. The fallback is correct for a root Router
+ * (its screens fill the viewport anyway) and wrong only for a CONTAINED one,
+ * which is exactly the case a binding is expected to publish.
+ */
+export declare const resolvePartLayer: (store: NavigateStoreApi) => HTMLElement | null;

package/dist/transition/__tests__/partClockInheritance.test.d.ts

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

package/dist/transition/compileTransitionStyles.d.ts

@@ -9,9 +9,17 @@ export type CssDecl = {
 export declare const collectAnimatedProperties: (transition: Pick<Transition, "initial" | "variants">) => string[];
 export declare const targetToDecls: (target: TransitionVariantValue["value"] | InitialTarget, ride?: boolean) => CssDecl[];
 export declare const easingToCss: (ease: AnimationOptions["ease"] | undefined) => string;
+export declare const dedupeKeyframeBlocks: (css: string) => string;
 export declare const animationName: (scope: "screen" | "decorator" | "part", name: string, variant: TransitionVariant) => string;
 export declare const decoratorAnimationName: (transitionName: string, decoratorName: string, variant: TransitionVariant) => string;
-export declare const HEAD_ANIMATION_SUFFIXES: readonly ["-gov", "-deskhead", "-govcreep"];
+export declare const HEAD_SUFFIXES: {
+    readonly governed: "gov";
+    readonly desktop: "deskhead";
+    readonly creep: "govcreep";
+    readonly governedPark: "govpark";
+    readonly desktopPark: "deskpark";
+};
+export declare const HEAD_ANIMATION_SUFFIXES: string[];
 export declare const matchesFlightAnimationName: (eventName: string, expectedName: string) => boolean;
 export declare const compileTransitionStyles: (transitions: Iterable<Transition>, decorators: Iterable<Decorator>, partTransitions?: Iterable<PartTransition>) => string;
 export declare const variantHasAnimation: (transitionLike: Pick<Transition, "initial" | "variants">, variant: TransitionVariant) => boolean;

package/dist/transition/gestureScrub.d.ts

@@ -0,0 +1,33 @@
+import { AnimationOptions } from './cssTypes';
+export interface ScrubClock {
+    /** Seconds from the animation's zero to the first frame of travel. */
+    readonly start: number;
+    readonly duration: number;
+    readonly ease: AnimationOptions["ease"];
+}
+/**
+ * Put every animation at one time and keep it there.
+ *
+ * Paused first: an animation the browser is still running would otherwise
+ * advance between the seek and the next pointer move.
+ */
+export declare const holdScrubAt: (animations: readonly Animation[], seconds: number) => void;
+/**
+ * Move to a fraction of the TRAVEL, not of the clock.
+ *
+ * Those are the same number only for a linear ease; under the built-in curve a
+ * finger a tenth of the way across moves the element a fiftieth, and the
+ * release is left to rush the rest.
+ */
+export declare const scrubTo: (animations: readonly Animation[], clock: ScrubClock, progress: number) => void;
+/**
+ * Hand the animations back to the browser at the speed the release settled at.
+ *
+ * `commit` plays them out to the arrival — the gesture became a navigation.
+ * Otherwise they run BACKWARDS to where they started.
+ *
+ * `onReverseFinish` exists because backwards an animation finishes at its start
+ * and fires no `animationend`. Anything listening for one has to be told
+ * explicitly instead.
+ */
+export declare const settleScrubbed: (animations: readonly Animation[], clock: ScrubClock, commit: boolean, seconds: number, onReverseFinish?: () => void) => void;

package/dist/transition/partTransition/__tests__/resolvePartDefinition.test.d.ts

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

package/dist/transition/partTransition/createPartTransition.d.ts

@@ -1,12 +1,11 @@
 import { InitialTarget } from '../cssTypes';
-import { TransitionVariantValue } from '../typing';
-import { PartTransition, PartTransitionName, PartTransitionOptions } from './typing';
+import { PartTransition, PartTransitionName, PartTransitionOptions, PartVariantValue } from './typing';
 interface CreatePartProps {
     name: PartTransitionName;
     initial: InitialTarget;
-    idle: TransitionVariantValue;
-    enter: TransitionVariantValue;
-    exit: TransitionVariantValue;
+    idle: PartVariantValue;
+    enter: PartVariantValue;
+    exit: PartVariantValue;
     options?: PartTransitionOptions;
 }
 export default function createPartTransition({ name, initial, idle, enter, exit, options }: CreatePartProps): PartTransition;

package/dist/transition/partTransition/createRawPartTransition.d.ts

@@ -1,18 +1,17 @@
 import { InitialTarget } from '../cssTypes';
-import { TransitionVariantValue } from '../typing';
-import { PartTransition, PartTransitionName, PartTransitionOptions } from './typing';
+import { PartTransition, PartTransitionName, PartTransitionOptions, PartVariantValue } from './typing';
 interface CreateRawPartProps {
     name: PartTransitionName;
     initial: InitialTarget;
-    idle: TransitionVariantValue;
-    pushOnEnter: TransitionVariantValue;
-    pushOnExit: TransitionVariantValue;
-    replaceOnEnter: TransitionVariantValue;
-    replaceOnExit: TransitionVariantValue;
-    popOnEnter: TransitionVariantValue;
-    popOnExit: TransitionVariantValue;
-    completedOnEnter: TransitionVariantValue;
-    completedOnExit: TransitionVariantValue;
+    idle: PartVariantValue;
+    pushOnEnter: PartVariantValue;
+    pushOnExit: PartVariantValue;
+    replaceOnEnter: PartVariantValue;
+    replaceOnExit: PartVariantValue;
+    popOnEnter: PartVariantValue;
+    popOnExit: PartVariantValue;
+    completedOnEnter: PartVariantValue;
+    completedOnExit: PartVariantValue;
     options?: PartTransitionOptions;
 }
 export default function createRawPartTransition({ name, initial, idle, pushOnEnter, pushOnExit, replaceOnEnter, replaceOnExit, popOnEnter, popOnExit, completedOnEnter, completedOnExit, options }: CreateRawPartProps): PartTransition;

package/dist/transition/partTransition/partTransition.d.ts

@@ -1,2 +1,19 @@
+import { BaseTransition, Transition } from '../typing';
 import { PartTransition, PartTransitionName } from './typing';
 export declare const partTransitionMap: Map<PartTransitionName, PartTransition>;
+/**
+ * A registered part, with the clock the CURRENT flight gives it.
+ *
+ * Every reader of a part's timing goes through here, because the compiled CSS
+ * does: the rule a part actually runs carries the resolved clock (see
+ * resolvePartClock and the pair pass in compileTransitionStyles), so a reader
+ * that resolved the authored variants instead would disagree with the glass.
+ * That disagreement is not cosmetic — the choreography span decides how long
+ * the whole flight stays open, and the layer pin decides what stays promoted
+ * across the COMPLETED flip.
+ *
+ * `transition` is null only where there is no flight to inherit from, which is
+ * a part mounted outside any screen. It then reads exactly what it authored,
+ * matching the by-name rule that is the only one such a part selects.
+ */
+export declare const resolvePartDefinition: (name: string | null, transition: Pick<Transition, "variants"> | null) => Pick<BaseTransition, "initial" | "variants"> | undefined;

package/dist/transition/partTransition/resolvePartClock.d.ts

@@ -0,0 +1,41 @@
+import { BaseTransition, Transition } from '../typing';
+import { PartTransition } from './typing';
+/**
+ * A part's variant table with its clock filled in from the screen transition
+ * carrying the flight.
+ *
+ * A `<Part>` declares a POSE: what the piece of chrome looks like on each side
+ * of a hand-over. How long it takes to get there is not its own question — it
+ * is the flight's, and the flight already answered it. Authoring the length a
+ * second time is how the two drift apart, and an omitted length was worse than
+ * drift: it resolved to zero and the part SNAPPED while the screen carrying it
+ * took three quarters of a second.
+ *
+ * This is the rule `resolveDecoratorClock` already applies to decorators, for
+ * the same reason and by the same mapping: the SAME VARIANT KEY. A part's
+ * PUSHING-false sits with the screen's PUSHING-false, so a preset whose push
+ * and pop differ (material runs 0.35s and 0.25s) gives its parts the same
+ * asymmetry without the author restating it.
+ *
+ * WHERE IT DIFFERS from a decorator, and why this could not simply reuse it: a
+ * decorator is reached through `transition.decoratorName`, so it belongs to one
+ * transition and can be resolved once. A part is referenced by NAME and may
+ * appear under any transition in the Router, so the pair is resolved per
+ * transition and the compiled rule carries a `data-flemo-transition` term to
+ * select the right one. A part mounted outside any screen has no transition to
+ * inherit from and keeps what it authored.
+ *
+ * `transition` is null where there is no flight to inherit from — the by-name
+ * pass, and a part mounted outside any screen. It then normalizes rather than
+ * inherits: every variant comes back with a clock, so nothing downstream has to
+ * carry the optional shape. That normalization is the reason PartVariantValue's
+ * looseness stops here, exactly as DecoratorVariantValue's does.
+ *
+ * Resolution is COMPILE TIME and produces a literal. It must never become a
+ * `var()` in `animation-duration`: timing that depended on custom properties
+ * lost WebKit's accelerated playback and collapsed to a 2-frame snap under
+ * main-thread starvation (device-bisected 2026-08-13, see
+ * compileTransitionStyles.ts).
+ */
+export declare const resolvePartClock: (transition: Pick<Transition, "variants"> | null, part: Pick<PartTransition, "initial" | "variants">) => Pick<BaseTransition, "initial" | "variants">;
+export default resolvePartClock;

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

@@ -1,4 +1,9 @@
-import { BaseTransition, SwipeAnimate } from '../typing';
+import { AnimationOptions, TransitionTarget } from '../cssTypes';
+import { BaseTransition, SwipeAnimate, TransitionVariant } from '../typing';
+export type PartVariantValue = {
+    value: TransitionTarget;
+    options?: AnimationOptions;
+};
 export interface RegisterPartTransition {
 }
 export type PartTransitionName = RegisterPartTransition[keyof RegisterPartTransition] | (string & {});
@@ -19,6 +24,7 @@ export type PartTransitionOptions = {
         active: boolean;
     }) => void;
 };
-export interface PartTransition extends Omit<BaseTransition, "name">, PartTransitionOptions {
+export interface PartTransition extends Omit<BaseTransition, "name" | "variants">, PartTransitionOptions {
     name: PartTransitionName;
+    variants: Record<TransitionVariant, PartVariantValue>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flemo/core",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Framework-agnostic primitives for flemo: history, navigation, transitions, task manager.",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",

package/dist/core/engine/__tests__/diagnosticRegistry.test.d.ts

@@ -1,10 +0,0 @@
-declare global {
-    interface ImportMeta {
-        glob(pattern: string, options: {
-            query: string;
-            import: string;
-            eager: true;
-        }): Record<string, string>;
-    }
-}
-export {};

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

@@ -1,16 +0,0 @@
-export declare const readImageHoldFlag: () => "on" | "off" | null;
-export declare const morphTraceArmed: () => boolean;
-export declare const readSettleGateFlag: () => boolean;
-export declare const readArrivalHoldFlag: () => boolean;
-export declare const readDesktopReleaseFlipFlag: () => boolean;
-export declare const readCreepHeadFlag: () => boolean;
-export declare const readDeferReleaseCommitFlag: () => boolean;
-export declare const readDesktopHeadFlag: () => boolean;
-export declare const readPrerasterFlag: () => boolean;
-export declare const readRestLayerPromotionFlag: () => boolean;
-export declare const readImageOffloadOverride: () => "on" | "off" | null;
-export declare const readBlinkGovernedOverride: () => "on" | "off" | null;
-export declare const residentScreenLayers: () => boolean;
-export declare const resetResidentLayersForTesting: () => void;
-export declare const shallowFreeze: () => boolean;
-export declare const resetShallowFreezeForTesting: () => void;

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

@@ -1,38 +0,0 @@
-/**
- * What kind of thing a flag is — which decides how a report should read it.
- *
- * - `production-state`: written by the library itself (a learned ledger). Never
- *   set by hand; the KEY STRINGS are frozen, since users' devices carry
- *   persisted values.
- * - `production-default-with-override`: the library computes a default and the
- *   key overrides it both ways, for field debugging.
- * - `opt-in-diagnostic`: default OFF. A measurement instrument that ships so a
- *   device session can be probed without a custom build.
- */
-export type DiagnosticFlagKind = "production-state" | "production-default-with-override" | "opt-in-diagnostic";
-export interface DiagnosticFlag {
-    readonly key: string;
-    readonly storage: "session" | "local";
-    readonly kind: DiagnosticFlagKind;
-    /** Accepted values, for a report or a panel to offer. */
-    readonly values: string;
-    /** The default when the key is unset. */
-    readonly fallback: string;
-    readonly effect: string;
-}
-/** Every `flemo:*` key the library reads today. */
-export declare const DIAGNOSTIC_FLAGS: readonly DiagnosticFlag[];
-export interface RetiredDiagnosticFlag {
-    readonly key: string;
-    readonly storage: "session" | "local";
-    /** What it used to do, and when it stopped doing it. */
-    readonly retiredWith: string;
-}
-/**
- * Keys the library once read and no longer does. Declared so a report can say
- * "this is set, and it does nothing" — residue that is merely unknown reads as
- * a lead worth chasing, and one such key once burned a multi-day investigation.
- *
- * Values persisted on users' devices are never read again.
- */
-export declare const RETIRED_DIAGNOSTIC_FLAGS: readonly RetiredDiagnosticFlag[];

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

@@ -1,2 +0,0 @@
-export declare function beginImageRevealHold(scope: Element | null, backstopMs: number, unpaintedOnly?: boolean): () => void;
-export default beginImageRevealHold;

package/dist/morph/morphAnimations.d.ts

@@ -1,2 +0,0 @@
-export declare function preserveDescendantAnimations(root: Element, move: () => void): void;
-export default preserveDescendantAnimations;