kuinetic 0.1.3 → 0.2.0

package/dist/types/core/derived/diagnostics.d.ts

@@ -0,0 +1,51 @@
+import type { AnimatorPort } from './types.js';
+import type { CompiledTarget } from '../compile.js';
+import type { AttributeLedger } from '../owned-styles.js';
+/**
+ * D(a): write `data-kui-unmatched="<sel>, <sel>"` on `host`, listing every `target:` group selector
+ * that matched nothing (plus 9b's suspect segments) — the one host-visible signal that a `target:`
+ * declaration silently found nothing to animate. Through `attributes` when given, so the write is
+ * unwound on release like every other library-owned attribute; a plain `setAttribute`/
+ * `removeAttribute` when the host has no ledger at all (it failed outright and was never given
+ * one).
+ *
+ * An empty `selectors` removes the attribute rather than writing an empty string. `AttributeLedger`
+ * has no `remove`, so that branch always goes straight through `host.removeAttribute` even when a
+ * ledger is given — safe, because a ledger only ever records an attribute's original value on its
+ * first `set`; if this call never calls `set`, `restore()` has nothing of ours to unwind here.
+ *
+ * @param host - The element to stamp.
+ * @param selectors - Every selector that matched nothing, in authored order. `[]` removes the
+ *   attribute rather than writing an empty one.
+ * @param attributes - The host's own attribute ledger, when it has one.
+ * @complexity O(n) time in `selectors.length` (the join); O(1) space beyond the joined string.
+ * @overallScore 100
+ */
+export declare function markUnmatched(host: Element, selectors: string[], attributes?: AttributeLedger): void;
+/**
+ * Warn when a derived match whose effects establish a 3D rendering context (`Preset.establishes3d`)
+ * sits inside an element — the host, or a live-state ancestor — that is also running one
+ * (memory: no-nested-3d). `preserve-3d`/`perspective` contexts do not compose when nested, so this
+ * is surfaced as early as possible rather than left to look like a broken effect.
+ *
+ * @param port - The animator's narrow window.
+ * @param host - The `target:` host installing `match`.
+ * @param match - The derived match being installed.
+ * @param target - The compiled group `match` was claimed by (its own group, or 2b's union).
+ * @complexity O(d) time in DOM depth, bounded by `ANCESTOR_WALK_BOUND`; O(1) space.
+ * @overallScore 100
+ */
+export declare function warnNested3d(port: AnimatorPort, host: Element, match: Element, target: CompiledTarget): void;
+/**
+ * Warn when a `cloak: true` preset is retargeted with `scope:page` while `<html data-kui-cloak>`
+ * is present — a page-scope match can sit anywhere in the document, including outside the host's
+ * own subtree, so the pre-JS cloak selector (9a) cannot reach it and it will flash unstyled before
+ * the animator ever runs.
+ *
+ * @param port - The animator's narrow window.
+ * @param host - The `target:` host.
+ * @param target - The compiled `scope:page` group carrying a `cloak: true` preset.
+ * @complexity O(n) time in the group's effect count; O(1) space.
+ * @overallScore 100
+ */
+export declare function warnPageScopeCloak(port: AnimatorPort, host: Element, target: CompiledTarget): void;

package/dist/types/core/derived/group-gate.d.ts

@@ -0,0 +1,62 @@
+import type { AnimatorPort, DerivedInstallContext } from './types.js';
+import type { CompiledTarget } from '../compile.js';
+import type { InstanceState } from '../types.js';
+/**
+ * Owned by phase 3b — B-a's "one host binding when grouped" rule. A `target:` group whose
+ * effective stagger keys carry `cascade:`/`spread:`/`order:` is read across the whole group at
+ * once, so it gets one activation binding on the *host* that fans out to every member in document
+ * order, instead of each member independently binding its own gate the way an ordinary derived
+ * match does.
+ */
+/**
+ * The gate owner for one derived group: the host itself, when the group's effective stagger keys
+ * are grouped (`isGroupedKeys`); `undefined` otherwise, meaning each member binds its own gate as
+ * an ordinary derived install would.
+ *
+ * The effective keys follow the same "each key decided on its own" rule the rest of `target:`
+ * uses: the group's own scoped hoists (`target.hoists`) override the host's element-wide keys
+ * per key, via {@link staggerKeysFor}/{@link elementStaggerKeys} — the identical recipe
+ * `restageTargets` uses to index the group, so a group that reads as "grouped" for stagger
+ * indexing reads as "grouped" for gating too.
+ *
+ * @param port - The animator's narrow window. Unused: the decision only needs the group's own
+ *   keys, not anything the animator itself knows — kept in the signature for parity with every
+ *   other derived-host module function, all of which take it.
+ * @param context - The host's derived-install context.
+ * @param target - The group being installed.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function groupGateOwner(port: AnimatorPort, context: DerivedInstallContext, target: CompiledTarget): Element | undefined;
+/**
+ * Whether `Animator.openGate` must skip binding this (deferred-gate) element's own activation,
+ * because a grouped derived match's gate is owned by its host instead (`groupGateOwner`) —
+ * `state.gateOwner` names that host.
+ *
+ * `openGate` only ever reaches this check once it has already established `stylePlan.gate ===
+ * 'deferred'` (see `animator.ts`), so this needs no gate check of its own: `gateOwner` being set
+ * at all is sufficient.
+ *
+ * @param state - The element's instance state.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function skipsOwnBinding(state: InstanceState): boolean;
+/**
+ * Install one activation binding on `host` per grouped live `target:` group, activating (and, for
+ * a paired exit, deactivating) every member in document order through `port.activateOne`/
+ * `port.deactivateOne` rather than each member's own gate. Registers its own release in
+ * `port.book.cleanups` so the binding is torn down when the host is released.
+ *
+ * Only groups `groupGateOwner` (via 2a) named `host` as the owner of are candidates — `host`'s
+ * other live groups, if any, are ungrouped and already bind per-member through the ordinary
+ * `openGate` path.
+ *
+ * @param port - The animator's narrow window.
+ * @param host - The `target:` host whose live groups may need a group binding.
+ * @complexity O(g) time in the host's live group count (each binding's own fan-out is amortized
+ *   into its later `activate`/`deactivate` calls, not this call); O(1) space beyond what each
+ *   binding retains.
+ * @overallScore 100
+ */
+export declare function bindGroups(port: AnimatorPort, host: Element): void;

package/dist/types/core/derived/install.d.ts

@@ -0,0 +1,110 @@
+import type { CompiledTarget } from '../compile.js';
+import type { ElementConfig } from '../element-config.js';
+import type { AnimatorPort, DerivedInstallContext, InstallRequest, ResolvedGroup } from './types.js';
+/**
+ * Install `request.el` the derived-host way: resolve every `target:` group's matches, apply the
+ * collision rules (D-D) to decide what this host may actually claim, install every claimed match as
+ * its own derived state, then the host's own group (or a zero-instance aggregate).
+ *
+ * A host with no own (untargeted) segment and nothing claimed has real compiled effects — `process`
+ * already ruled out zero effects entirely — but nowhere for any of them to run, so this is the
+ * `'failed'` outcome below.
+ *
+ * @param port - The animator's narrow window (see `AnimatorPort`).
+ * @param request - The would-be host's install request.
+ * Returns nothing: every non-empty-selector document is fully handled here, whether that means a
+ * real install or the `'failed'` outcome above, so `Animator.install` never falls through to its own
+ * body for a request it routed here.
+ * @complexity O(g * m) time in group count and matches per group (the resolve + claim passes); O(g +
+ *   m) space.
+ * @overallScore 100
+ */
+export declare function installWithTargets(port: AnimatorPort, request: InstallRequest): void;
+/**
+ * Release a derived-host's bookkeeping, called at the very start of `Animator.release(el)`, before
+ * `el`'s own teardown runs. A host and a match are mutually exclusive — a match is never itself
+ * claimable as a `target:` host, because `claimMatches` refuses any candidate that already carries
+ * its own `data-kui` — so at most one of the two branches below ever does anything.
+ *
+ * @param port - The animator's narrow window.
+ * @param el - The element being released — a host, a derived match, or neither.
+ * @complexity O(1) time and space for a match; O(c) for a host, in its claimed-match and cleanup
+ *   counts.
+ * @overallScore 100
+ */
+export declare function releaseDerived(port: AnimatorPort, el: Element): void;
+/**
+ * Called once at the end of `Animator.releaseTree`, after every removed candidate in the batch has
+ * had its own teardown run (and so its own `releaseDerived` match-branch, recording its former host
+ * via {@link rememberFormerHost}). Re-indexes every surviving host that lost one or more derived
+ * matches in this removal — the derived-host analogue of `restageAfterRemoval` for ordinary stagger
+ * groups — and lets it re-derive its aggregate status now that its membership has changed.
+ *
+ * @param port - The animator's narrow window.
+ * @param removed - Every element `releaseTree` visited while tearing down one removal batch.
+ * @complexity O(r) time in the removed-candidate count, plus each surviving host's own restage;
+ *   O(h) space in the distinct former-host count.
+ * @overallScore 100
+ */
+export declare function restageAfterTreeRelease(port: AnimatorPort, removed: Element[]): void;
+/**
+ * Apply the collision rules (D-D) over one host's resolved `target:` groups, deciding which matched
+ * elements this host is actually allowed to claim.
+ *
+ * A match is skipped, with an aggregated warning naming the selector and the group's effects, when
+ * it is the host itself, when it already carries its own `data-kui` (an authored element animates
+ * itself, never a host's group), or when another host has already claimed it (first wins — whichever
+ * host's `scan()` reached it first). A match this same host has already claimed under an earlier
+ * group in the same resolution is joined into that claim silently — that is the ordinary "one
+ * element, several groups" case `compileUnion` exists for, not a collision.
+ *
+ * @param port - The animator's narrow window.
+ * @param host - The element whose `target:` groups are being resolved.
+ * @param groups - Every non-empty-selector group's `CompiledTarget` and its resolved matches.
+ * @returns Each claimed match mapped to every group of *this* host that claims it, in authored
+ *   group order; the map's own iteration order is document order.
+ * @complexity O(g * m) time in groups and matches per group; O(m) space.
+ * @overallScore 100
+ */
+export declare function claimMatches(port: AnimatorPort, host: Element, groups: ResolvedGroup[]): Map<Element, CompiledTarget[]>;
+/**
+ * Install every claimed match as its own derived host — a single group installs directly, two or
+ * more recompile through `compileUnion` first — and record the result in `port.book` (the host's
+ * `derived` set, each match's `hosts` entry, and the owning group's `members`).
+ *
+ * Used both by `installWithTargets` (the initial install) and by phase 6's `adoptLateMatches` (a
+ * late-inserted match joining an already-live group).
+ *
+ * @param port - The animator's narrow window.
+ * @param context - The host's derived-install context (fingerprint, parsed value, base config).
+ * @param claims - `claimMatches`'s output: each match to install, and which of the host's groups
+ *   claim it.
+ * @param cache - Group-config memoization, shared with `installWithTargets`'s own group resolution
+ *   pass when one is available; a caller with no group-level pass of its own (a late adoption
+ *   joining an already-live group) may omit it and get a fresh one, since there is nothing else in
+ *   that case to share it with.
+ * @returns The matches actually installed, in claim order.
+ * @complexity O(m) time in the claimed-match count, plus each union's own compile on a cache miss;
+ *   O(m) space.
+ * @overallScore 100
+ */
+export declare function installDerivedMatches(port: AnimatorPort, context: DerivedInstallContext, claims: Map<Element, CompiledTarget[]>, cache?: Map<CompiledTarget, ElementConfig>): Element[];
+/**
+ * Re-run `indexTargetGroup` for every one of a host's live `target:` groups, over its *current*
+ * members — each match's own `--kui-i` through its own ledger, the host's `--kui-stagger`/`-count`
+ * through the host's. Called whenever a group's membership changes after its initial install: a late
+ * adoption (phase 6) or a removal (`restageAfterTreeRelease`), as well as once at the end of the
+ * initial install itself.
+ *
+ * A group with no members is skipped outright — nothing to number, and nothing for `indexTargetGroup`
+ * to derive a step from. Two live groups on one host both write the host's `--kui-stagger`/`-count`;
+ * the second's write wins, matching HEAD's own single-group behaviour (there was never more than one
+ * write to race against before `target:` existed).
+ *
+ * @param port - The animator's narrow window.
+ * @param host - The `target:` host to re-index.
+ * @complexity O(g * m) time in the host's live groups and their member counts; O(1) space beyond
+ *   `indexTargetGroup`'s own.
+ * @overallScore 100
+ */
+export declare function restageTargets(port: AnimatorPort, host: Element): void;

package/dist/types/core/derived/late-matches.d.ts

@@ -0,0 +1,19 @@
+import type { AnimatorPort } from './types.js';
+/**
+ * C(a): a node was inserted under `observe:true`. Walk its ancestors (bounded) for a live
+ * `target:` host with `scope:'self'` groups, and for each, claim and install only matches it did
+ * not already have, then restage. Never re-processes a host: one straight-line ancestor walk from
+ * `node.parentElement` visits each ancestor at most once.
+ *
+ * `node` itself is skipped outright when it carries `ATTR.part`: 7a's injected flip-card control
+ * (and any other library-injected part) must never itself be adopted as a `target:` match, no
+ * matter what selector it happens to satisfy.
+ *
+ * @param port - The animator's narrow window.
+ * @param node - The newly inserted element.
+ * @complexity O(d * g * m) time in the walk depth (bounded by `ANCESTOR_WALK_BOUND`), each
+ *   ancestor's live group count, and each group's match count; O(1) space beyond what each host's
+ *   own reindex retains.
+ * @overallScore 100
+ */
+export declare function adoptLateMatches(port: AnimatorPort, node: Element): void;

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

@@ -0,0 +1,108 @@
+import type { ActivationBinder } from '../activation.js';
+import type { Capabilities } from '../capabilities.js';
+import type { CompiledDocument, CompiledPlan, CompiledTarget } from '../compile.js';
+import type { LifecycleEventType, LifecycleReason } from '../control.js';
+import type { ElementConfig } from '../element-config.js';
+import type { Registry } from '../registry.js';
+import type { Reporter } from '../reporter.js';
+import type { Activation, InstanceState, ParsedValue, Timeline } from '../types.js';
+export type { StaggerGroupKeys } from '../stagger-config.js';
+/** Everything `Animator.install` needs. Moved here verbatim from `animator.ts`'s own
+ *  `InstallRequest`, plus three optional fields that are absent for every HEAD code path. */
+export interface InstallRequest {
+    el: Element;
+    fingerprint: string;
+    parsed: ParsedValue;
+    /** The element's config with its activation already resolved against its own group. */
+    config: ElementConfig;
+    document: CompiledDocument;
+    /** `resolveConfig`'s output BEFORE `resolveActivation` mutated `activation` — what each derived
+     *  group's config is built from (`resolveGroupConfig(baseConfig, target.hoists)`). Set by
+     *  `process()`; absent on a derived install. */
+    baseConfig?: ElementConfig;
+    /** Set only on a derived install: the authored element whose `target:` group installed `el`.
+     *  `install` copies it to `InstanceState.host`. */
+    host?: Element;
+    /** Set only on a derived install of a *grouped* target (`cascade:`/`spread:`/`order:`): the
+     *  element that owns the activation binding for it (always the host). `install` copies it to
+     *  `InstanceState.gateOwner`; `openGate` then skips binding `el` itself. */
+    gateOwner?: Element;
+}
+/** One `CompiledTarget` and the live elements its selector resolved to. Moved from `animator.ts`'s
+ *  own `ResolvedGroup`. */
+export interface ResolvedGroup {
+    target: CompiledTarget;
+    matches: Element[];
+}
+/** Everything needed to install (more) derived matches for one host later — recorded by 2a at
+ *  install, read by 2b (`compileUnion`), 3b (`bindGroups`), 6 (`adoptLateMatches`). */
+export interface DerivedInstallContext {
+    host: Element;
+    /** The host's own fingerprint; a derived match's is `${fingerprint}\u0000${scope} ${selector}`. */
+    fingerprint: string;
+    /** The host's parsed value (after `scopeHoists`): element-wide `rm`, stagger keys. */
+    parsed: ParsedValue;
+    /** The host's un-resolved config (see `InstallRequest.baseConfig`). */
+    baseConfig: ElementConfig;
+    /** `baseConfig.timeline` — what `compileUnion` recompiles against. */
+    timeline: Timeline;
+}
+/** One `target:` group as installed on one host. */
+export interface LiveTargetGroup {
+    /** As the host compiled it (non-empty `selector`, its `scope`, `hoists`, `specs`, `plan`). */
+    target: CompiledTarget;
+    /** `resolveGroupConfig(baseConfig, target.hoists)` with `activation` resolved for this group. */
+    config: ElementConfig;
+    /** The host when this group is grouped (Phase 3b), else undefined. */
+    gateOwner?: Element;
+    /** Derived matches currently installed from this group, in document order. Mutated by 2a on
+     *  release and by 6 on adoption. */
+    members: Element[];
+}
+/** The animator's derived-host bookkeeping. One instance per Animator; all WeakMaps so a removed
+ *  element takes its entries with it. Written ONLY through the 2a/2b/3b/6 module functions. */
+export interface DerivedBook {
+    /** host → its derived matches (insertion order = document order at install). */
+    readonly derived: WeakMap<Element, Set<Element>>;
+    /** derived match → its host. Presence means "claimed" (collision rule D-D). */
+    readonly hosts: WeakMap<Element, Element>;
+    /** host → its live target groups. */
+    readonly groups: WeakMap<Element, LiveTargetGroup[]>;
+    /** host → what `installWithTargets` installed it with. */
+    readonly contexts: WeakMap<Element, DerivedInstallContext>;
+    /** host → union-compile cache keyed by sorted `${scope} ${selector}` list joined with `\u0001`. */
+    readonly unions: WeakMap<Element, Map<string, CompiledTarget>>;
+    /** host → cleanups to run when the host is released (group bindings, target-group-host claim). */
+    readonly cleanups: WeakMap<Element, Array<() => void>>;
+}
+/**
+ * The narrow window a derived-host module gets onto one Animator. Built once in the Animator
+ * constructor; every member delegates to the existing private method of the same name. Modules take
+ * this, never `Animator`, so each is unit-testable with a hand-built fake.
+ */
+export interface AnimatorPort {
+    readonly registry: Registry;
+    readonly reporter: Reporter;
+    readonly binder: ActivationBinder;
+    readonly capabilities: Capabilities;
+    readonly respectReducedMotion: boolean;
+    readonly book: DerivedBook;
+    stateOf(el: Element): InstanceState | undefined;
+    /** `Animator.install` — installs `request.el` from a document. Re-enters `installWithTargets` only
+     *  when the document has a non-empty selector; a derived install's document never does. */
+    install(request: InstallRequest): void;
+    /** `Animator.installAggregate` — a zero-instance host state (no own group). */
+    installAggregate(request: InstallRequest): void;
+    /** `Animator.resolveGroupMatches` — validate + query + warn "matched nothing"/too broad. */
+    resolveGroupMatches(host: Element, target: CompiledTarget): Element[];
+    /** `Animator.resolveActivation`. */
+    resolveActivation(el: Element, config: ElementConfig, plan: CompiledPlan): Activation;
+    release(el: Element): void;
+    /** Start ONE element (no fan-out). */
+    activateOne(el: Element): void;
+    /** The per-element exit half (`Animator.deactivate`). */
+    deactivateOne(el: Element): void;
+    /** `state.status = next` + `data-kui-state` through the state's own ledger. No aggregate sync. */
+    writeStatus(el: Element, state: InstanceState, next: InstanceState['status']): void;
+    emit(el: Element, state: InstanceState, type: LifecycleEventType, reason: LifecycleReason): void;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Resolve one authored easing token to the value a stylesheet can hold.
+ *
+ * @param easing - A native keyword, a kUInetic keyword, a CSS easing function, or `spring(...)`.
+ * @returns A valid `animation-timing-function` / `transition-timing-function` value. Never the
+ *   author's own text for a `spring(...)`: that path emits digits generated from clamped numbers,
+ *   so nothing authored survives into the declaration.
+ * @complexity O(1) amortised — a `spring(...)` curve is built once per distinct damping ratio and
+ *   cached; every other form is a set lookup. O(1) space beyond the cache.
+ * @overallScore 100
+ */
+export declare function cssEasingValue(easing: string): string;
+/**
+ * Resolve one authored easing token to a value `Element.animate` will actually accept.
+ *
+ * The Web Animations sibling of {@link cssEasingValue}, and it exists because the two APIs screen
+ * easings at different moments. A stylesheet resolves `var(--kui-ease-back-out, ease-out)` through
+ * the cascade at computed-value time; `KeyframeEffect`'s `easing` option is parsed as a bare
+ * `<easing-function>` the instant it is handed over, with no cascade to consult — so `var(...)` is
+ * as invalid there as `back-out` itself. Neither one degrades: Chrome throws
+ * `TypeError: 'back-out' is not a valid value for easing` out of `animate()`, which took the whole
+ * FLIP with it and left the layout change to happen instantly and silently.
+ *
+ * So the custom property is read here instead of deferred to the browser. Reading it — rather than
+ * mirroring `base.css`'s ten definitions into a table here — is what keeps the open half of the
+ * vocabulary working: `params.ts`'s `EASING_KEYWORD` accepts any `[a-z]+-(in|out|in-out)`, so an
+ * author may define `--kui-ease-swift-out` and write `ease:swift-out`, and a table could only ever
+ * know the names this repo happens to ship. It also cannot drift from `base.css`, because it *is*
+ * `base.css`. The cost is that it only answers correctly once the library's stylesheet has been
+ * applied, which is why the three callers resolve at prepare time rather than at module load.
+ *
+ * @param easing - A native keyword, a kUInetic keyword, a CSS easing function, or `spring(...)`.
+ * @param el - Element the token is resolved against, so a `--kui-ease-*` scoped to a subtree wins
+ *   exactly as it would in the cascade.
+ * @param warn - Called once when a named token resolves to nothing.
+ * @returns A literal easing value, or `undefined` when the author named none — which leaves each
+ *   caller's own default standing rather than substituting a house one for it.
+ * @complexity O(1) amortised; a bare keyword costs one `getComputedStyle` read.
+ * @overallScore 100
+ */
+export declare function waapiEasingValue(easing: string, el: Element, warn: (message: string) => void): string | undefined;
+/**
+ * Everything wrong with a `spring(...)` token, named one problem at a time.
+ *
+ * Separate from {@link cssEasingValue} because the two answer different questions and have
+ * different callers: `parse.ts` has the author's text and a warnings sink at the moment the
+ * attribute is read, which is where every other grammar diagnostic in this library is raised.
+ * Nothing here is fatal — a refused value is clamped or dropped and a curve is always produced —
+ * so this is a warning list, never a rejection.
+ *
+ * @param token - Any easing token. A token that is not a `spring(...)` has no problems by
+ *   definition, so callers need no guard of their own.
+ * @returns One message per malformed, unknown, duplicated, or out-of-range argument.
+ * @complexity O(a) time and space in the argument count.
+ * @overallScore 100
+ */
+export declare function springTokenProblems(token: string): string[];

package/dist/types/core/element-config.d.ts

@@ -1,4 +1,5 @@
-import type { Activation, ParsedValue, Timeline } from './types.js';
+import type { ToggleActions } from './toggle-actions.js';
+import type { Activation, ParsedValue, SegmentHoists, Timeline } from './types.js';
 /** The subset of an element's attributes this module needs. Keeps resolution DOM-free. */
 export interface ElementAttributes {
     source: string;
@@ -10,6 +11,16 @@ export interface ElementConfig {
     activation: Activation;
     /** Whether the author named an activation, so a primitive default may fill in when not. */
     activationAuthored: boolean;
+    /** Optional selector for the event source named by `data-kui-on`'s `from:` refinement. */
+    activationSource?: string;
+    /**
+     * What to do at each of the observer's four crossings, when the author wrote `actions:`.
+     *
+     * Absent — not a defaulted four-way table — because absent and "the default four-way table" are
+     * genuinely different bindings: without this the observer keeps its two-way delivery and its
+     * one-shot release, which is what every piece of existing markup depends on.
+     */
+    actions?: ToggleActions;
     timeline: Timeline;
     /** Trailing tokens of `data-kui-timeline`, e.g. `entry 0% cover 60%`. */
     range: string;
@@ -42,11 +53,41 @@ export declare function readAttributes(el: Element): ElementAttributes;
  */
 export declare function resolveConfig(attributes: ElementAttributes, parsed: ParsedValue): ElementConfig;
 /**
- * Convert an IntersectionObserver threshold from `"30%"` or `"0.3"` into a clamped ratio.
+ * Keep a source selector only when its longhand activation won the precedence decision.
  *
- * @param raw - Authored threshold value.
- * @returns A ratio in [0, 1]; unparseable input yields 0 rather than throwing.
- * @complexity O(1) time, O(1) space.
+ * Applying `from:` after an inline `on:` wins would pair two independently authored activations.
+ *
+ * @param input - Parsed inline and longhand activation settings.
+ * @returns The optional source field for the resolved element configuration.
+ * @complexity O(1) time and space.
+ */
+/**
+ * Read only the head keyword off a raw `timeline:` value, falling back when it is absent or not a
+ * recognised timeline — the same extraction `resolveConfig` does inline for the element-wide
+ * attribute, duplicated here (against the same {@link TIMELINES} set) rather than refactored into
+ * it, so a per-group caller (`compile.ts`'s `scopeHoists`/`compileTargets`) can reuse the logic
+ * without touching `resolveConfig`'s own body and risking its passing tests.
+ *
+ * @param raw - A group's scoped `timeline:` hoist, or `undefined` when it scoped none.
+ * @param fallback - The element-wide timeline to use when `raw` is absent or unrecognised.
+ * @complexity O(k) time in the value's length; O(1) space.
+ * @overallScore 100
+ */
+export declare function resolveTimelineHead(raw: string | undefined, fallback: Timeline): Timeline;
+/**
+ * Build a derived host's own `ElementConfig` from the element-wide base plus its `target:` group's
+ * scoped hoists — not yet wired into `animator.ts` (that is Phase 2's job, once each group installs
+ * as its own host); landed now so `CompiledTarget.hoists` has a documented consumer shape.
+ *
+ * Each field the group scoped a value for overrides the base; anything the group left unscoped
+ * inherits the element-wide answer unchanged, matching D-B's "hoists written in an untargeted
+ * segment stay element-wide and are inherited by every target group unless the group overrides
+ * them".
+ *
+ * @param base - The host element's own resolved config, from `resolveConfig`.
+ * @param hoists - The group's merged scoped hoists (`CompiledTarget.hoists`), or absent when the
+ *   group scoped none — the identity path, returning `base` unchanged.
+ * @complexity O(1) time and space.
  * @overallScore 100
  */
-export declare function toThresholdRatio(raw: string): number;
+export declare function resolveGroupConfig(base: ElementConfig, hoists: SegmentHoists | undefined): ElementConfig;

package/dist/types/core/element-size.d.ts

@@ -0,0 +1,23 @@
+import type { Cleanup } from './types.js';
+/** A resize subscription whose observed elements can change as an effect changes targets. */
+export interface SizeWatch {
+    observe(element: Element): void;
+    unobserve(element: Element): void;
+    disconnect: Cleanup;
+}
+/**
+ * Watch element boxes, including the window-resize fallback for browsers without ResizeObserver.
+ *
+ * @complexity O(1) per observed element and notification; O(n) space in observed elements.
+ * @overallScore 100
+ */
+export declare function watchElementSize(win: Window, onChange: () => void): SizeWatch;
+/**
+ * Coalesce notifications into one callback in the next animation frame; cancel on teardown.
+ * @complexity O(1) time and space per request.
+ * @overallScore 100
+ */
+export declare function frameScheduler(win: Window, callback: () => void): {
+    request(): void;
+    cancel: Cleanup;
+};

package/dist/types/core/event-sources.d.ts

@@ -0,0 +1,39 @@
+import type { Reporter } from './reporter.js';
+import type { Cleanup } from './types.js';
+/** Everything needed to retain callbacks for a group of source elements and event types. */
+export interface EventSourceBindingRequest {
+    sources: readonly Element[];
+    types: readonly string[];
+    run(): void;
+}
+/** Owns shared foreign-event listeners and releases all of them on destruction. */
+export interface EventSourceBindings {
+    bind(request: EventSourceBindingRequest): Cleanup;
+    destroy(): void;
+}
+/**
+ * Create a registry that shares one native listener per source/event pair.
+ *
+ * @returns A registry for binding callbacks and releasing every foreign listener it owns.
+ * @complexity O(1) to build; retained listener costs are documented on the nested functions.
+ */
+export declare function createEventSourceBindings(): EventSourceBindings;
+/** Everything needed to resolve an optional foreign event source against the animated element's document. */
+export interface EventSourceResolutionRequest {
+    el: Element;
+    from?: string;
+    reporter?: Reporter;
+}
+/**
+ * Resolve an event source selector once while an animation is installed.
+ *
+ * `from:` deliberately resolves only at install time. The existing `observe: true` watcher tracks
+ * animated elements, not arbitrary potential source nodes, so pretending that a missing source
+ * would bind later would create a silent and unbounded document-wide observer. A named warning is
+ * the established selector convention and gives the author an immediate correction path.
+ *
+ * @param request - Animated element, optional selector, and diagnostic sink.
+ * @returns The event source elements, or an empty list when the selector is unusable or unmatched.
+ * @complexity O(n) in document size for a selector query; O(s) space for s matching sources.
+ */
+export declare function resolveEventSources({ el, from, reporter }: EventSourceResolutionRequest): Element[];

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

@@ -21,6 +21,17 @@ export interface FlipSnapshot {
 }
 export interface FlipOptions {
     durationMs?: number;
+    /**
+     * Hold the inverted (pre-move) position this long before playing the move.
+     *
+     * `fill: 'backwards'` comes with it and is what makes it a delay rather than a glitch: by the
+     * time a FLIP runs the browser has *already* laid the elements out at their destination, so an
+     * unfilled delay would show them there for the wait and then snap back to animate. Filling
+     * backwards holds the first keyframe — the invert — for exactly the delay, which is what
+     * `animation-fill-mode: both` does for a delayed CSS effect. The end is unaffected either way:
+     * `backwards` does not fill forwards, so the stylesheet still owns the resting position.
+     */
+    delayMs?: number;
     easing?: string;
     /** Animate width/height differences as a scale. Off for elements with visible borders. */
     scale?: boolean;
@@ -56,6 +67,28 @@ export declare function domMeasure(el: Element): Box;
  * @overallScore 100
  */
 export declare function createFlipEngine(deps?: Partial<FlipDeps>): FlipEngine;
+/**
+ * Hold every FLIP run that is still playing, so teardown can stop all of them.
+ *
+ * A `FlipRun` outlives the call that started it: `engine.play` hands back live Web Animations and
+ * returns immediately. Dropping that handle means teardown has nothing to cancel, and the moves
+ * keep playing on elements the animator has already released — with `duration:10s` that is ten
+ * seconds of motion after `destroy()`.
+ *
+ * A single "latest run" slot is not enough. FLIP durations are author-controlled and mutations
+ * arrive whenever the page says so, so a second reorder can easily land while the first is still
+ * mid-flight; keeping only the newest would leave the older one running past teardown, which is
+ * the same bug one step removed. Each run drops itself on completion, so the set holds only what
+ * is genuinely in flight rather than growing with the page's history.
+ *
+ * @returns `track` to register a run, and `cancelAll` for teardown.
+ * @complexity O(1) per run tracked; O(k) space in runs currently playing.
+ * @overallScore 100
+ */
+export declare function trackFlipRuns(): {
+    track(run: FlipRun): void;
+    cancelAll(): void;
+};
 /**
  * Watch a container and FLIP its children whenever its child list changes.
  *
@@ -66,7 +99,7 @@ export declare function createFlipEngine(deps?: Partial<FlipDeps>): FlipEngine;
  * @param engine - FLIP engine to use.
  * @param options - Timing and scaling.
  * @param observe - MutationObserver factory, injected for tests.
- * @returns Teardown that disconnects the observer.
+ * @returns Teardown that disconnects the observer and cancels any move still playing.
  * @complexity O(n) per mutation batch in the number of children.
  * @overallScore 100
  */

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

@@ -39,6 +39,18 @@ export interface GestureOptions {
     swipeVelocity?: number;
     /** Hold duration in ms before `onLongPress`. Zero disables it. */
     longPressMs?: number;
+    /**
+     * Whether to take pointer capture on `pointerdown`. Default `true`, which is right for every
+     * gesture that *moves* the element (see `onDown`), and wrong for every gesture that does not.
+     *
+     * Capture redirects the whole pointer sequence to this element, and the browser then targets the
+     * resulting `click` at the capturing element rather than the node actually under the cursor. On a
+     * container with interactive children that silently kills all of them: a `swipe-x` on a carousel
+     * shell swallowed every click on its own dots and buttons, because the click was delivered to the
+     * shell. `swipeable` recognises and publishes an attribute — it never moves anything — so it has
+     * nothing to stay under the cursor for and opts out.
+     */
+    capturePointer?: boolean;
 }
 export interface GestureDeps {
     now(): number;