@flemo/core 2.1.0 → 2.2.0

package/dist/core/TaskManger.d.ts

@@ -25,6 +25,7 @@ interface Task<T> {
     status: TaskStatus;
     dependencies: string[];
     instanceId: string;
+    scope: string;
     abortController?: AbortController;
     backstopTimer?: ReturnType<typeof setTimeout>;
     manualResolver?: {
@@ -33,19 +34,17 @@ interface Task<T> {
         result: T;
     };
 }
+export declare const BROWSER_HISTORY_LANE = "browser-history";
 export declare const TRANSITION_GATE_BACKSTOP_MS = 1200;
 declare class TaskManager {
     private tasks;
     private readonly instanceId;
-    private isLocked;
-    private currentTaskId;
-    private taskQueue;
     private signalListeners;
     private pendingTaskQueue;
+    private lanes;
+    private laneOf;
     get pendingTaskIds(): string[];
     private isProcessingPending;
-    private acquireLock;
-    private releaseLock;
     generateTaskId(): string;
     emitSignal(signalName: string): void;
     private processPendingTasks;
@@ -73,6 +72,7 @@ declare class TaskManager {
         rollback?: () => Promise<void>;
         dependencies?: string[];
         control?: Control;
+        scope?: string;
     }): Promise<TaskResult<T>>;
     private gatePhases;
     markGateHeld(taskId: string): void;

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

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

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

@@ -0,0 +1,39 @@
+/**
+ * Above the screens, below a morph.
+ *
+ * A morph is the focal shared element of a flight — an element the consumer
+ * pointed at — and a bar's chrome passing over it would be exactly backwards.
+ * The morph layer's own number (see @morph/attachMorph's `prepareLayer`) is the
+ * ceiling this sits under.
+ */
+export declare const PART_LAYER_LEVEL = 2147482000;
+export interface StagedBarParts {
+    /** Put every staged part back where it came from, exactly as it was. */
+    readonly release: () => void;
+}
+export interface StageBarPartsInput {
+    /** The screen scope the parts belong to — the passive side of the flight. */
+    readonly scope: HTMLElement;
+    /** This screen's shared bars; riding and absent ones are skipped. */
+    readonly bars: readonly (HTMLElement | null | undefined)[];
+    /** The Router's part layer, from resolvePartLayer. */
+    readonly layer: HTMLElement | null;
+    /**
+     * How long to wait before releasing a staging nothing came back for.
+     *
+     * A screen that is still transitional when it goes away — an aborted
+     * navigation, a replace that unmounts the side it replaced — never runs the
+     * COMPLETED drive that would return its parts, and a part left in the layer
+     * is a stale icon floating over the app for the rest of the session. The
+     * caller passes this flight's choreography span plus its own slack, so a
+     * long-authored part is never cut short by the backstop.
+     */
+    readonly strandedMs: number;
+}
+/**
+ * Lift this screen's matched-bar parts into the Router's part layer for the
+ * flight. Returns null when there is nothing to stage — no layer, no screen
+ * identity, or no part in a matched bar — so a flight that needs none of this
+ * pays for none of it.
+ */
+export declare const stageBarParts: (input: StageBarPartsInput) => StagedBarParts | null;

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

@@ -1,5 +1,11 @@
 import { VariantMotion } from '../../transition/variantMotion';
 export declare const RESUME_BUDGET = 4;
+/**
+ * Announce a re-parent that will cancel this element's animations, so
+ * cancel-resume treats the cancel as expected instead of recovering from it.
+ * The caller is responsible for the clock across its own move.
+ */
+export declare const expectAnimationCancel: (element: HTMLElement) => void;
 export interface CancelResumeConfig {
     element: HTMLElement;
     expectedName: string;

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

@@ -29,6 +29,16 @@ export interface SwipeControllerConfig {
     onDragProgress?: (progress: number) => void;
     /** The release: whether it committed, and the seconds the screens settle in. */
     onDragSettle?: (committed: boolean, seconds: number) => void;
+    /**
+     * The Router scope's part layer (see @screen/partLayer), for staging the
+     * covered side's matched shared-bar parts while the finger is down.
+     *
+     * A drag is not a flight: the navigate status stays COMPLETED throughout, so
+     * the engine's own staging never arms and the previous screen's bar parts
+     * cross-fade under the screen being dragged off them. Omitted by a binding
+     * that renders no layer; the drag then behaves as it did before.
+     */
+    getPartLayer?: () => HTMLElement | null;
 }
 export interface SwipeController {
     pointerDown: (event: PointerEvent) => void;

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

@@ -54,7 +54,7 @@ export interface FlightRouting {
      * drops and double-steps the eye reads as trembling.
      */
     readonly framePacingKeepalive: boolean;
-    /** Arm the creep head beside the governed one (`flemo:creep`). */
+    /** Arm the creep head beside the governed one. */
     readonly creepHead: boolean;
 }
 export interface FlightRoutingInput {
@@ -71,7 +71,7 @@ export interface FlightRoutingInput {
  * WHICH HEAD KIT this session plays, and how long its flat head is.
  *
  * Extracted so it has exactly one definition. It is a pure function of the
- * platform, the diagnostic flags and the status — nothing about the flight —
+ * platform and the status — nothing about the flight —
  * and the MORPH runtime needs the same answer at a moment when it cannot get
  * it from the DOM: the head is announced by an attribute on the root, and the
  * engine writes that attribute from the SAME commit the morph is staged in.

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

@@ -1,5 +1,4 @@
 import { Transition } from '../../transition/typing';
-export { resetResidentLayersForTesting } from './diagnosticFlags';
 export declare const LAYER_SETTLE_MS = 300;
 export declare const holdScopeLayer: (scope: HTMLElement, transitionLike: Pick<Transition, "initial" | "variants">, containment?: boolean, owner?: symbol) => void;
 export declare const releaseScopeLayerAfterSettle: (scope: HTMLElement, owner?: symbol) => void;

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

@@ -0,0 +1,28 @@
+import { VariantMotion } from '../../transition/variantMotion';
+export interface RiderSwipe {
+    /** Whether anything is actually being driven. */
+    readonly active: boolean;
+    /** Move every rider to this fraction of its travel (0 → 1). */
+    scrub: (progress: number) => void;
+    /**
+     * Hand the riders back at the speed the release settled at.
+     *
+     * `commit` plays them out to the arrival and marks each element so the
+     * navigation's own compiled keyframe does not replay it from its `from`
+     * pose — the contract the swipe already applies to the screen and the dim.
+     * Otherwise they run backwards and the compiled rest rule takes them over
+     * again.
+     */
+    settle: (commit: boolean, seconds: number) => void;
+}
+export interface RiderMotion {
+    readonly element: HTMLElement;
+    readonly motion: VariantMotion;
+}
+/**
+ * Stage the riders of a drag, paused at zero. Returns null when there is
+ * nothing to drive, so a gesture over chrome that declares no motion costs
+ * nothing.
+ */
+export declare const beginRiderSwipe: (riders: readonly RiderMotion[]) => RiderSwipe | null;
+export default beginRiderSwipe;

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

@@ -12,6 +12,7 @@ export interface ScreenLifecycleInput {
         decorator?: HTMLElement | null;
         bars?: (HTMLElement | null | undefined)[];
         screenContainer?: HTMLElement | null;
+        partLayer?: HTMLElement | null;
     };
     transitionName: TransitionName;
     prevTransitionName: TransitionName;

package/dist/dom/__tests__/staging.test.d.ts

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

package/dist/dom/attributes.d.ts

@@ -97,6 +97,38 @@ export declare const LAYER_OWNER_ATTR = "data-flemo-layer-owner";
  * the engine's participant scan can both find them.
  */
 export declare const PART_NAME_ATTR = "data-flemo-part-name";
+/**
+ * The per-Router PART LAYER: the box a shared bar's `<Part>` elements are staged
+ * in for a flight. Rendered by the binding, for the same reason the morph layer
+ * is (only a Router knows which box bounds its screens).
+ *
+ * Two screens that share a bar id each render their OWN copy of that bar inside
+ * their own screen container, and a screen container is an isolated stacking
+ * context carrying the screen's z-index. So the lower screen's parts are painted
+ * under the upper screen's opaque surface: both parts run their authored
+ * keyframes, but only one of them is ever seen, and the cross-fade the pair was
+ * written for never appears. Being covered is a property of being a descendant,
+ * so for the flight the covered side's parts stop being one.
+ */
+export declare const PART_LAYER_ATTR = "data-flemo-part-layer";
+/**
+ * On a staged part: the `data-flemo-screen` id of the screen it was lifted from.
+ * The engine's participant scan is otherwise structural (it walks out from the
+ * scope), and a staged part is no longer under any scope — without this it would
+ * drop out of the layer pin, the settle release and the COMPLETED inline clear,
+ * all of which must keep treating it as one of its screen's parts.
+ */
+export declare const PART_HOME_ATTR = "data-flemo-part-home";
+/**
+ * The box left behind in the bar while a part is staged.
+ *
+ * A part is a child of its bar's layout, so lifting it out shrinks the bar by
+ * exactly its size and everything after it slides over. That is invisible on
+ * the covered side and very visible on the other: a pop's staged part belongs
+ * to the RETURNING screen, whose bar is the one left on screen at the landing.
+ * Measured, it moved the title 56px and moved it back on release.
+ */
+export declare const PART_STAND_IN_ATTR = "data-flemo-part-stand-in";
 /**
  * Marks a registered morph element. Presence only — the value is the ROLE
  * (see MORPH_ROLE). Written by the binding, read by the morph runtime (to find
@@ -211,10 +243,31 @@ export declare const GOVERNED_ATTR = "data-flemo-governed";
 export declare const CREEP_ATTR = "data-flemo-creep";
 /** The desktop macOS Safari flat head, with its own lengths. */
 export declare const DESK_HEAD_ATTR = "data-flemo-desk-head";
-/** The compositor warm-up element. */
+/**
+ * The governed head PARKS instead of hiding — written on the entering screen's
+ * scope, not the root, because the decision is per-flight.
+ *
+ * The plain governed head holds the authored from-pose, which for an entering
+ * screen is fully off-screen, for `animation-delay` plus the head — 200ms on a
+ * PUSHING flight. WebKit drops a backing store that sits outside the coverage
+ * rect that long, so the pre-raster the park-over hold just paid for is thrown
+ * away and the slide reveals unrastered content (device-recorded 2026-08-30,
+ * iOS Safari: everything past the first ~512px tile row entered blank and the
+ * re-raster landed 183ms into the flight). Under this attribute the head holds
+ * the PARK pose instead — on-screen at the destination, near-zero opacity, the
+ * same place the hold already had it — so the tiles stay live across the wait.
+ *
+ * The binding writes it only where the park-over hold itself was granted (the
+ * covering screen's surface is verifiably opaque), so a translucent cover keeps
+ * the old off-screen head rather than showing a ghost.
+ */
+export declare const PARK_HEAD_ATTR = "data-flemo-park-head";
+/**
+ * The compositor warm-up element. Its VALUE says whether the warm-up is
+ * currently forcing frames (`"on"`) or resident but idle (`"idle"`) — the
+ * element outlives every hold, so its presence alone no longer answers that.
+ */
 export declare const WARM_ATTR = "data-flemo-warm";
-/** The warm-up's cadence video, when the desktop profile uses one. */
-export declare const WARM_VIDEO_ATTR = "data-flemo-warm-video";
 /** The one-shot GPU pipeline prewarm element. */
 export declare const GPU_PREWARM_ATTR = "data-flemo-gpu-prewarm";
 /**
@@ -236,4 +289,4 @@ export declare const attrValueSelector: (attribute: string, value: string) => st
  * a devtools build can assert against the shipped set instead of a hand-kept
  * copy — the drift this module exists to end.
  */
-export declare const FLEMO_ATTRIBUTES: readonly ["data-flemo-screen", "data-flemo-status", "data-flemo-active", "data-flemo-transition", "data-flemo-router", "data-flemo-skip-animation", "data-flemo-bar", "data-flemo-bar-active", "data-flemo-bar-status", "data-flemo-bar-riding", "data-flemo-bar-id", "data-flemo-bar-id-type", "data-flemo-bar-transition", "data-flemo-bar-spacer", "data-flemo-decorator", "data-flemo-decorator-name", "data-flemo-layer-host", "data-flemo-layer-owner", "data-flemo-layer-slot", "data-flemo-part-name", "data-flemo-morph", "data-flemo-morph-camera", "data-flemo-morph-ghost", "data-flemo-morph-layer", "data-flemo-morph-name", "data-flemo-morph-slot", "data-flemo-morph-stand-in", "data-flemo-morph-sheet", "data-flemo-anim-hold", "data-flemo-held-arrival", "data-flemo-img-hold", "data-flemo-governed", "data-flemo-creep", "data-flemo-desk-head", "data-flemo-warm", "data-flemo-warm-video", "data-flemo-gpu-prewarm", "data-flemo-image-src", "data-flemo-devtools-panel"];
+export declare const FLEMO_ATTRIBUTES: readonly ["data-flemo-screen", "data-flemo-status", "data-flemo-active", "data-flemo-transition", "data-flemo-router", "data-flemo-skip-animation", "data-flemo-bar", "data-flemo-bar-active", "data-flemo-bar-status", "data-flemo-bar-riding", "data-flemo-bar-id", "data-flemo-bar-id-type", "data-flemo-bar-transition", "data-flemo-bar-spacer", "data-flemo-decorator", "data-flemo-decorator-name", "data-flemo-layer-host", "data-flemo-layer-owner", "data-flemo-layer-slot", "data-flemo-part-name", "data-flemo-part-layer", "data-flemo-part-home", "data-flemo-part-stand-in", "data-flemo-morph", "data-flemo-morph-camera", "data-flemo-morph-ghost", "data-flemo-morph-layer", "data-flemo-morph-name", "data-flemo-morph-slot", "data-flemo-morph-stand-in", "data-flemo-morph-sheet", "data-flemo-anim-hold", "data-flemo-held-arrival", "data-flemo-img-hold", "data-flemo-governed", "data-flemo-creep", "data-flemo-desk-head", "data-flemo-park-head", "data-flemo-warm", "data-flemo-gpu-prewarm", "data-flemo-image-src", "data-flemo-devtools-panel"];

package/dist/dom/staging.d.ts

@@ -0,0 +1,33 @@
+export interface StagingRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * A viewport rect in a staging layer's own coordinates.
+ *
+ * The layer can sit inside a transformed ancestor (a demo bezel, a scaled
+ * preview), in which case a px it is positioned by is not a px on the glass.
+ * Its measured rect against its laid-out size gives the ratio, so a flight is
+ * expressed in the space it is actually staged in.
+ */
+export declare const intoLayerSpace: (rect: StagingRect, layer: HTMLElement) => StagingRect;
+export interface PreserveAnimationsOptions {
+    /**
+     * Carry the root element's OWN animations across the move too.
+     *
+     * Off by default, which is what a morph needs: the runtime writes the root's
+     * animation itself on both sides of the move and must stay its only author.
+     * A staged `<Part>` is the opposite case — the compiled part rule animates the
+     * part element itself, and that rule matches on name/status/active with no
+     * structural term, so the move restarts the very animation the flight is
+     * being watched for.
+     */
+    includeRoot?: boolean;
+}
+/**
+ * Runs `move` — the re-parent — and carries the subtree's animation clocks
+ * across it.
+ */
+export declare function preserveAnimations(root: Element, move: () => void, options?: PreserveAnimationsOptions): void;

package/dist/history/historyDriver.d.ts

@@ -10,5 +10,7 @@ export interface HistoryDriver {
     go(delta: number): void;
     back(): void;
     subscribe(listener: (event: HistoryNavEvent) => void): () => void;
+    readonly isolated?: boolean;
 }
+export declare const navigationLane: (driver: HistoryDriver) => string;
 export default function createBrowserHistoryDriver(routerKey?: string): HistoryDriver;

package/dist/index.d.ts

@@ -32,6 +32,7 @@ export { morphTransitionMap } from './transition/morphTransition/morphTransition
 export { DEFAULT_MORPH_TRANSITION_NAME } from './transition/morphTransition/typing';
 export { default as attachMorph, type AttachMorphOptions } from './morph/attachMorph';
 export { registerMorphLayer } from './morph/morphLayer';
+export { registerPartLayer, resolvePartLayer } from './screen/partLayer';
 export { beginMorphSwipe, type MorphSwipe } from './morph/morphSwipe';
 export { default as cupertino } from './transition/cupertino';
 export { default as material } from './transition/material';
@@ -49,10 +50,9 @@ export { default as animateInline, clearInlineAnimation } from './transition/ani
 export { default as createTransitionEngine } from './core/engine/createTransitionEngine';
 export { governedCompiledActive } from './platform/governedCompiled';
 export { startFlemoRuntime } from './runtime/flemoRuntime';
-export { resolvePlatformProfile, restLayerPromotionEnabled, type PlatformProfile, type PlatformProfileInput } from './platform/profile';
-export { FLEMO_ATTR_PREFIX, FLEMO_ATTRIBUTES, attrSelector, attrValueSelector, ANIM_HOLD, ANIM_HOLD_ATTR, ANIM_HOLD_PAUSED_VALUES, ACTIVE_ATTR, BAR_ACTIVE_ATTR, BAR_ATTR, BAR_ID_ATTR, BAR_ID_TYPE_ATTR, BAR_RIDING_ATTR, BAR_SPACER_ATTR, BAR_STATUS_ATTR, BAR_TRANSITION_ATTR, CREEP_ATTR, DECORATOR_ATTR, DECORATOR_NAME_ATTR, DESK_HEAD_ATTR, DEVTOOLS_PANEL_ATTR, GOVERNED_ATTR, GPU_PREWARM_ATTR, HELD_ARRIVAL_ATTR, IMAGE_HOLD_ATTR, LAYER_HOST_ATTR, LAYER_OWNER_ATTR, LAYER_SLOT_ATTR, MORPH_ATTR, MORPH_LAYER_ATTR, MORPH_NAME_ATTR, MORPH_ROLE, MORPH_SLOT_ATTR, MORPH_SHEET_ATTR, PART_NAME_ATTR, ROUTER_ATTR, SCREEN_ATTR, STATUS_ATTR, TRANSITION_ATTR, WARM_ATTR, WARM_VIDEO_ATTR } from './dom/attributes';
+export { resolvePlatformProfile, type PlatformProfile, type PlatformProfileInput } from './platform/profile';
+export { FLEMO_ATTR_PREFIX, FLEMO_ATTRIBUTES, attrSelector, attrValueSelector, ANIM_HOLD, ANIM_HOLD_ATTR, ANIM_HOLD_PAUSED_VALUES, ACTIVE_ATTR, BAR_ACTIVE_ATTR, BAR_ATTR, BAR_ID_ATTR, BAR_ID_TYPE_ATTR, BAR_RIDING_ATTR, BAR_SPACER_ATTR, BAR_STATUS_ATTR, BAR_TRANSITION_ATTR, CREEP_ATTR, DECORATOR_ATTR, DECORATOR_NAME_ATTR, DESK_HEAD_ATTR, DEVTOOLS_PANEL_ATTR, GOVERNED_ATTR, GPU_PREWARM_ATTR, HELD_ARRIVAL_ATTR, IMAGE_HOLD_ATTR, LAYER_HOST_ATTR, LAYER_OWNER_ATTR, LAYER_SLOT_ATTR, MORPH_ATTR, MORPH_LAYER_ATTR, MORPH_NAME_ATTR, MORPH_ROLE, MORPH_SLOT_ATTR, MORPH_SHEET_ATTR, PARK_HEAD_ATTR, PART_HOME_ATTR, PART_LAYER_ATTR, PART_NAME_ATTR, ROUTER_ATTR, SCREEN_ATTR, STATUS_ATTR, TRANSITION_ATTR, WARM_ATTR } from './dom/attributes';
 export { OVERLAY_LEVEL, SCREEN_STACKING_ORDER, UNNUMBERED_LEVEL } from './dom/stacking';
-export { DIAGNOSTIC_FLAGS, RETIRED_DIAGNOSTIC_FLAGS, type DiagnosticFlag, type DiagnosticFlagKind, type RetiredDiagnosticFlag } from './core/engine/diagnosticRegistry';
 export { TRANSITIONAL_STATUS_VALUES } from './navigate/store';
 export { SKIP_ANIMATION_ATTR, type TransitionEngine, type TransitionEngineDeps, type ScreenLifecycleInput } from './core/engine/types';
 export { default as createSwipeController } from './core/engine/createSwipeController';