kuinetic 0.1.3 → 0.2.0

package/dist/types/core/host-facts.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The facts that belong to the *element* rather than to any one effect on it.
+ *
+ * Only `reducedMotion` is still a true single-element fact after the plan's D-B.4 reversal: `rm:`
+ * is one author decision (or one folded default) that applies however many `target:` groups the
+ * attribute compiles into, so {@link mergeHostFacts} still folds the strictest declared policy
+ * across every group and writes the merged answer back onto all of them.
+ *
+ * `supportedActivations`/`supportedTimelines`/`channels`/`defaultActivation` are **not** folded
+ * here any more — a `target:` group is a derived host in its own right (each match will get its
+ * own trigger, timeline and events once Phase 2 lands), so pretending its capabilities are the
+ * *document's* capabilities was the bug: `parallax-scale target:video timeline:view` alongside a
+ * `flip-card` host used to intersect the two primitives' `supportedTimelines` down to `[]` and warn
+ * a mismatch that was never really there. `compile.ts`'s `compileTargets` now resolves each of
+ * those per group, from that group's own composed entries, and writes them straight onto that
+ * group's own plan — see this plan's design doc, section D-B.4, for the full reasoning.
+ *
+ * Split out of `compile.ts` when that file reached its own 400-line lint ceiling, the same way
+ * `test/css-composition-invariants.test.ts` was split out of `css-invariants.test.ts`. The seam is
+ * not arbitrary: everything here folds a list of already-computed facts down to one value, and
+ * nothing here knows what an effect, a primitive or a registry is. `resolveDefaultActivation` takes
+ * {@link ActivationClaim}s rather than compiled entries for exactly that reason — the same
+ * structural-input argument `channels.ts` makes for `ChannelClaim`, and it is what keeps the
+ * type-only import of `CompiledPlan` below from becoming a runtime cycle.
+ */
+import type { CompiledPlan } from './compile.js';
+import type { Activation, EffectPhase, ReducedMotionPolicy } from './types.js';
+/** What {@link resolveDefaultActivation} needs to know about one composed effect. */
+export interface ActivationClaim {
+    /** When this effect holds its channels — `compile.ts`'s `phaseOf`, already derived. */
+    phase?: EffectPhase;
+    /** The activation its primitive prefers, or absent when it expresses no preference. */
+    defaultActivation?: Activation;
+}
+/**
+ * Which activation the composed effects prefer, when the author named none.
+ *
+ * An element has exactly one activation binding — `animator.ts`'s `resolveActivation` returns a
+ * single `Activation` and every effect on the element is wired to it — so a comma list whose halves
+ * want different triggers cannot have both. What this decides is which one loses.
+ *
+ * It used to be first-wins: `plan.defaultActivation ??= primitive.defaultActivation`, folded in
+ * authoring order in `buildPlan` and again across every `target:` group's already-folded answer in
+ * `mergeHostFacts` (the D1 model — one document-wide answer written onto every group, since D-B.4
+ * reversed that: each group now calls this function once, over only its own composed entries, and
+ * keeps its own answer). `??=` is the right operator for "a default fills in when nothing is set"
+ * and the wrong one for a *merge*, because there is no sense in which the first name in a comma
+ * list is the authoritative one. The consequence was that composing an entrance with a behaviour
+ * changed **when the entrance itself fired**: `lift` declares `defaultActivation: 'load'`, so
+ * `data-kui="fade-up, lift"` — the pair the whole phase axis was added to allow — bound the element
+ * on `load` and fired the reveal before it was ever scrolled to. `back-in-down, drag` did the same.
+ * Measured across the catalog, 4,545 composing pairs took their activation from the non-entrance
+ * half.
+ *
+ * The rule is that **an entrance names the trigger**, and it is the lesser of two unavoidable harms
+ * rather than a preference. Either choice compromises something:
+ *
+ * - Binding on the behaviour's `load` spends the reveal on a below-the-fold element while nobody is
+ *   looking. The entrance is destroyed outright and cannot be recovered.
+ * - Binding on the entrance's `enter` wires the behaviour up when the element scrolls into view
+ *   instead of at load. It is late, and it still works — nobody drags, hovers or clicks an element
+ *   they cannot see.
+ *
+ * `?? 'enter'` on the found entrance, not its raw declaration: almost no entrance declares an
+ * activation (the catalog's entrances leave it undefined and let `element-config.ts`'s `'enter'`
+ * fall through), so returning `undefined` here would hand the decision straight back to the
+ * first-wins fallback and change nothing at all. Materialising `'enter'` is what makes the
+ * entrance's silence a position. It is materialised *only* when something else declared a value to
+ * beat — a lone `fade-up` still compiles `defaultActivation: undefined`, exactly as before.
+ *
+ * ## No warning, and that was measured rather than assumed
+ *
+ * Silently picking one is what caused this, so a diagnostic is the obvious accompaniment. Two
+ * definitions were tried against the catalog and both are noise, not signal:
+ *
+ * - "the resolved activation is not in some composed primitive's `supportedActivations`" — 6,098
+ *   pairs, including `fade-up, lift`, because `lift` declares `supportedActivations: ['load']`.
+ * - "two entries each declare an activation and the values differ" — 4,882 pairs, again including
+ *   the flagship pairs.
+ *
+ * Disagreement is the *normal* state of this catalog: 120 of 290 names declare `load`, 21 declare
+ * `enter`, 124 declare nothing. A warning that fires on one composing pair in seven trains authors
+ * to ignore the reporter, which costs more than the thing it reports. `on:` remains the spelling
+ * for an author who wants the other answer, and it still wins outright — `animator.ts` only reads
+ * this field when `config.activationAuthored` is false.
+ *
+ * @param claims - Every effect that survived composition, for one `target:` group (`compile.ts`'s
+ *   `compileTargets` calls this once per group, not once over the whole document — see D-B.4).
+ *   Survivors rather than authored segments: an effect the resolver dropped is not going to run, so
+ *   letting it name the trigger would bind the element for a corpse.
+ * @complexity O(n) time in the claim count; O(n) space.
+ * @overallScore 100
+ */
+export declare function resolveDefaultActivation(claims: ActivationClaim[]): Activation | undefined;
+/**
+ * Fold the strictest declared `reducedMotion` across every `target:` group and write the merged
+ * answer back onto every group's plan.
+ *
+ * `rm:` is one author decision (or one folded default among the composed primitives) for the whole
+ * attribute, even when its effects are split across several `target:` groups — `fade-up target:h1
+ * rm:disable, pin target:.x` cannot honour two different reduced-motion policies on one page load
+ * decided from two different subsets of the same author's intent. Every other cross-group fact this
+ * function used to merge (`supportedActivations`/`supportedTimelines`/`channels`/
+ * `defaultActivation`) is decided per group instead now — see this module's own doc comment for why
+ * — so this is the one field left.
+ *
+ * Mutates the plans in place rather than returning a new list: `buildPlan` already built each one,
+ * and threading a copy through here for one field write would cost more than it clarifies.
+ *
+ * @complexity O(g) time in the group count; O(1) space.
+ * @overallScore 100
+ */
+export declare function mergeHostFacts(targets: {
+    plan: CompiledPlan;
+}[]): void;
+/**
+ * Fold an authored `rm:` into the policy the composed primitives declared.
+ *
+ * `rm:` is the one thing an author can say about reduced motion, and it is deliberately a
+ * *one-way ratchet*: it can only make the policy stricter, never weaker.
+ *
+ * The rule is not invented for this key — it is {@link strictestPolicy}'s, applied one more time.
+ * That function already encodes "if any effect must not run, none of the list should", and an
+ * author key that could overrule it would make the whole fold advisory: `parallax` declares
+ * `disable` because parallax is a documented vestibular trigger, not because the library is being
+ * cautious on the author's behalf, and `rm:shorten` on it would hand a visitor who has explicitly
+ * asked their operating system for less motion exactly the motion they asked not to receive. The
+ * useful direction is the other one and it stays open: `rm:disable` on a spinning logo whose
+ * primitive only claims `shorten` is a real request the library previously had no spelling for.
+ *
+ * A weakening attempt warns by name rather than being ignored, because the author wrote a value
+ * and is otherwise owed an explanation for why the page does not behave as they asked.
+ *
+ * @param declared - Strictest policy among the composed primitives.
+ * @param authored - The hoisted `rm:` value, already validated by `parse.ts`.
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function resolvedPolicy(declared: ReducedMotionPolicy, authored: ReducedMotionPolicy | undefined, warnings: string[]): ReducedMotionPolicy;
+/**
+ * Narrow a running capability intersection by one more primitive's support list.
+ *
+ * `undefined` means no primitive has contributed yet; `[]` means the composed primitives share
+ * nothing. Collapsing those two states into "is the array empty?" — which is what the previous
+ * `length ? filter : copy` form did — made an intersection that had legitimately emptied out
+ * repopulate from the next effect: `fade-up, parallax-scale, scroll-progress-ring timeline:view`
+ * emptied on the second effect and came back as `['scroll', 'view']` on the third, so
+ * `style-plan.ts` applied `view()` to `fade-up`, the exact mismatch `supportedTimelines` was
+ * added to prevent. Emptiness is a real answer here and must survive the rest of the list.
+ *
+ * @complexity O(a * b) time in the two list lengths — both are single-digit; O(a) space.
+ * @overallScore 100
+ */
+export declare function intersect<T>(accumulated: T[] | undefined, supported: T[]): T[];
+export declare function strictestPolicy(a: ReducedMotionPolicy, b: ReducedMotionPolicy): ReducedMotionPolicy;

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

@@ -1,9 +1,13 @@
-export { createActivationBinder } from './activation.js';
-export type { ActivationBinder, ActivationBinderOptions } from './activation.js';
+export { createActivationBinder, resolveActivationSpec } from './activation.js';
+export type { ActivationBinder, ActivationBinderOptions, ActivationRequest, ActivationSpec, ActivationTrigger, } from './activation.js';
 export { Animator, createAnimator, ATTR } from './animator.js';
 export type { AnimatorOptions } from './animator.js';
 export { detect } from './capabilities.js';
 export type { Capabilities } from './capabilities.js';
+export { control } from './control.js';
+export type { ControlHandle } from './control.js';
+export { KUI_EVENT } from './control.js';
+export type { LifecycleDetail, LifecycleEvent, LifecycleEventType, LifecycleReason, } from './control.js';
 export { play, resolveTargets, toAttributeValue } from './play.js';
 export type { PlaybackHandle, PlayOptions, Target } from './play.js';
 export { Registry } from './registry.js';
@@ -11,4 +15,4 @@ export type { ResolvedEffect } from './registry.js';
 export { collectingReporter, consoleReporter, silentReporter } from './reporter.js';
 export type { CollectingReporter, Reporter } from './reporter.js';
 export { CHANNEL, inertInstance } from './types.js';
-export type { Activation, Channel, Cleanup, EffectInstance, EffectParams, ParamSpec, ParameterSchema, PerfClass, PrepareContext, Preset, Primitive, ReducedMotionPolicy, Timeline, } from './types.js';
+export type { Activation, Channel, Cleanup, EffectInstance, EffectParams, EffectVariant, InstanceControl, NamedActivation, ParamSpec, ParameterSchema, PerfClass, PlaybackState, PrepareContext, Preset, Primitive, ReducedMotionPolicy, Timeline, } from './types.js';

package/dist/types/core/owned-styles.d.ts

@@ -20,6 +20,19 @@ export interface StyleLedger {
     restore(): void;
     /** Properties currently owned. Diagnostics and leak assertions. */
     owned(): string[];
+    /**
+     * The value this ledger will restore `property` to — whatever was there immediately before its
+     * first `set()` or `claim()` — or `undefined` if this ledger has never captured that property.
+     *
+     * `restore()` can put a value back, but until now nothing could ask what it remembered without
+     * writing it: a caller that needs the *value itself* mid-effect (a "resting state" to fall back
+     * to when its own live input settles at a neutral point, say) had to keep a private snapshot of
+     * its own, taken at its own moment, which is exactly the two-sources-of-truth bug this ledger
+     * exists to prevent everywhere else. `undefined` here means only "never captured" — a property
+     * that *was* captured but held no value beforehand reads back as `''`, matching what a live
+     * `getPropertyValue` call would have returned for it at that same instant.
+     */
+    peek(property: string): string | undefined;
 }
 /**
  * Create a ledger over one element's inline style.
@@ -36,9 +49,123 @@ export interface AttributeLedger {
 }
 /**
  * The same discipline for attributes, so a library-stamped attribute never clobbers an authored
- * one permanently.
+ * one permanently. The concrete ledger also exposes `remove`, which records the original value
+ * before clearing a boolean attribute such as a slideshow slide's `inert`.
  *
  * @complexity O(1) per write; O(n) to restore.
  * @overallScore 100
  */
-export declare function createAttributeLedger(el: Element): AttributeLedger;
+export declare function createAttributeLedger(el: Element): AttributeLedger & {
+    remove(name: string): void;
+};
+/**
+ * One owner's claim on the shared per-element ledgers.
+ *
+ * Deliberately not "the registry" — there is exactly one registry, module-wide, and a claim is a
+ * handle onto it. Two claims over one element see one capture and two refcounts.
+ */
+export interface StyleClaim {
+    /**
+     * This element's shared ledger, claimed for this owner.
+     *
+     * The object handed back is this claim's own view of it: `set`/`claim`/`owned`/`peek` read and
+     * write the shared ledger, and `restore()` means *"this owner is done"* rather than *"unwind the
+     * element now"*. That distinction is what lets a caller holding only a `StyleLedger` — every
+     * primitive, via `PrepareContext.style` — participate in the refcount without knowing it exists.
+     */
+    style(el: Element): StyleLedger;
+    /** Drop this owner's claim on `el`, restoring it when no other owner holds it. */
+    release(el: Element): void;
+    /** Elements this claim currently holds, in the order it first asked for them. A snapshot. */
+    elements(): Element[];
+}
+/**
+ * Open one owner's claim on the shared inline-style ledgers.
+ *
+ * **Writing is claiming; reading is not.** A handle outlives its own `restore()` — a primitive is
+ * handed `PrepareContext.style` once at prepare and keeps it for the element's whole life, a
+ * controller cancels and re-activates, a `LedgerSet` is restored and the element is entered again
+ * — so a handle that closed over one entry would, after release, write straight into a ledger the
+ * registry had already deleted and restored. The value landed on the element, the claim was empty,
+ * and nothing anywhere would ever put it back. So `set` and `claim` rejoin. `owned` and `peek`
+ * deliberately do not: asking what this owner will restore must not make it an owner, and a
+ * released handle honestly answers "nothing".
+ *
+ * @returns A claim that hands out ref-counted handles and releases them one element at a time.
+ * @complexity O(1) per lookup and per release; O(p) in properties written, on the last release.
+ * @overallScore 100
+ */
+export declare function createStyleClaim(): StyleClaim;
+/**
+ * One owner's claim on the shared per-element *attribute* ledgers.
+ *
+ * The same model and the same reason. `animator.ts`'s `installMatch` stamps `data-kui-fx` and
+ * `data-kui-rm` onto every element a group's `target:` resolves to, and under `scope:page` two
+ * authored hosts can resolve to the same element — at which point the second `LedgerSet` captured
+ * the first one's stamp as the author's attribute and put *that* back on teardown.
+ */
+export interface AttributeClaim {
+    /** This element's shared attribute ledger, claimed for this owner. */
+    attributes(el: Element): AttributeLedger;
+    /** Drop this owner's claim on `el`, restoring it when no other owner holds it. */
+    release(el: Element): void;
+    /** Elements this claim currently holds, in the order it first asked for them. A snapshot. */
+    elements(): Element[];
+}
+/**
+ * Open one owner's claim on the shared attribute ledgers.
+ *
+ * @complexity O(1) per lookup and per release; O(n) in attributes written, on the last release.
+ * @overallScore 100
+ */
+export declare function createAttributeClaim(): AttributeClaim;
+/**
+ * Every element one authored `data-kui` wrote to, and the ledgers that unwind them.
+ *
+ * The host owns the lifecycle — one `InstanceState`, one gate, one event stream — but the *writes*
+ * do not all land on the host. `target:` names elements the effect animates instead of the element
+ * the attribute sits on, and each of those needs its own pair of ledgers: `createStyleLedger`
+ * closes over one element's `style` object and one snapshot of whether that element had a `style`
+ * attribute to begin with, so it cannot be shared and cannot be reconstructed later.
+ *
+ * A set rather than an array of pairs because the same element is reached repeatedly — once per
+ * effect in a composed attribute, once more by the stagger pass — and a second ledger over an
+ * element the first has already written to would snapshot *this library's* values as the author's
+ * own and restore to them. Memoising per element is what makes "what was there before" mean before
+ * this instance existed, rather than before this particular call.
+ *
+ * Both kinds go one level further out than that, through {@link createStyleClaim} and
+ * {@link createAttributeClaim}: memoising *within* one set is not enough once two sets reach the
+ * same element — two authored hosts whose `target:` lands on one node, a stagger group and the
+ * child's own state, a core effect and an advanced controller. The set is one owner of a shared,
+ * ref-counted capture, so `restore()` here means "this host is finished with the element", and the
+ * element is unwound by whichever owner is last.
+ */
+export interface LedgerSet {
+    /** This element's inline-style ledger, created on first ask. */
+    style(el: Element): StyleLedger;
+    /** This element's attribute ledger, created on first ask. */
+    attributes(el: Element): AttributeLedger;
+    /** Unwind every element this set ever handed out a ledger for. Host last — see below. */
+    restore(): void;
+}
+/**
+ * Open a ledger set over one authored host.
+ *
+ * **Restore is host-last, and that ordering is load-bearing.** The host carries `data-kui-state`,
+ * which is the cloak layer's per-element release key: `html[data-kui-cloak] [data-kui][data-kui-reveal]:not([data-kui-state])`
+ * holds a subtree at `opacity: 0`, and the attribute's presence is what lets go. Restoring the host
+ * first removes that key while the elements underneath still carry library styles, reopening the
+ * cloak over a half-unwound subtree. Doing it last means the page is already back to the author's
+ * markup at the instant it becomes visible again.
+ *
+ * Style before attributes within each element, matching the order `release()` has always used: a
+ * primitive's teardown may write styles, and the attributes are what CSS keys on to decide whether
+ * those styles mean anything.
+ *
+ * @param host - The authored element. Always present in the set, always restored last.
+ * @returns A set that hands out memoised ledgers and unwinds all of them together.
+ * @complexity O(1) per lookup; O(n) space and O(n) time to restore, in elements written to.
+ * @overallScore 100
+ */
+export declare function createLedgerSet(host: Element): LedgerSet;

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

@@ -15,6 +15,54 @@ export interface ValidationResult {
  * @overallScore 100
  */
 export declare function validate(raw: string, spec: ParamSpec): ValidationResult;
+/**
+ * Expand decimal notation lexically, optionally shifting the decimal point.
+ *
+ * Lexical rather than arithmetic on purpose. `Number('1.1') / 100` is `0.011000000000000001` — a
+ * binary floating-point artefact that would be written verbatim into a custom property and shown
+ * to anyone inspecting the element, making a correct value look broken. Shifting the digits
+ * instead is exact for every input, and it neither rounds a tiny scale to zero nor rounds a large
+ * integer to its nearest double.
+ *
+ * The length cap matches the core value budget and bounds the allocation even for `1e999999999`,
+ * which would otherwise ask for a gigabyte of zeroes. An unrepresentable result returns
+ * `undefined` and leaves the caller holding the original input for ordinary validation to reject.
+ *
+ * Lives in the core because two callers need the same answer: this module's `'number|percentage'`
+ * normalisation, and `effects/tween/properties.ts`'s `withImpliedUnit`, which has accepted
+ * `opacity:50%` on the tween since before the union type existed. Two copies would be two places
+ * for `50%` to stop meaning `0.5`.
+ *
+ * @param raw - A candidate number in CSS's spelling, including `+` and exponent forms.
+ * @param shift - Decimal places to move the point by; `-2` divides by one hundred.
+ * @returns The plain decimal spelling, or `undefined` when the input is not a number or the
+ *   result would exceed the value budget.
+ * @complexity O(n) time and space in the digit count, bounded by the cap.
+ * @overallScore 100
+ */
+export declare function decimalNumber(raw: string, shift?: number): string | undefined;
+/**
+ * The escape screen on its own, for a value that has no type to be validated against.
+ *
+ * Every authored value normally reaches `style.setProperty` through {@link validate}, which runs
+ * this screen and then a type match. One value cannot take the second half: `data-kui-stagger`'s
+ * step (and its `cascade:` spelling inside `data-kui`) has always been passed through verbatim so
+ * that `var(--speed)` and `calc(90ms * 2)` work, and narrowing it to a `<time>` literal now would
+ * break every group written against that promise. That left it as the one authored string in the
+ * library with no screen at all — and `data-kui` is explicitly not assumed to be site-owner text
+ * (see the module doc above; a CMS field or a comment can reach it).
+ *
+ * So the half that costs the expression forms nothing is available separately. It is deliberately
+ * *not* a type check: anything shaped like a length, a time, a `calc()` or a `var()` passes, and
+ * only the characters and functions that can escape a declaration or reach the network are
+ * refused.
+ *
+ * @param value - Author-supplied text bound for a custom property.
+ * @returns Whether it is safe to write as-is.
+ * @complexity O(n) time in value length; O(1) space.
+ * @overallScore 100
+ */
+export declare function isSafeCssValue(value: string): boolean;
 /**
  * Whether an authored value stays on the page's own origin wherever a `src`-shaped `text`
  * parameter is actually turned into a network request.

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

@@ -1,4 +1,4 @@
-import type { ParsedValue } from './types.js';
+import type { Activation, ParsedValue } from './types.js';
 /**
  * Split on a delimiter, ignoring delimiters nested inside parentheses or quotes.
  *
@@ -11,6 +11,25 @@ import type { ParsedValue } from './types.js';
  * @overallScore 100
  */
 export declare function splitTopLevel(input: string, delimiter: ',' | ' ', warnings?: string[]): string[];
+/** The parsed longhand activation and its optional foreign event source. */
+export interface ParsedActivationAttribute {
+    activation?: Activation;
+    from?: string;
+    warnings: string[];
+}
+/**
+ * Parse the `data-kui-on` grammar: an activation followed by optional `key:value` refinements.
+ *
+ * `from:` deliberately lives only in this longhand grammar. It cannot be a general `data-kui`
+ * hoist because `from:` remains a per-effect parameter on existing primitives such as `count-up`.
+ * Quoting keeps a selector containing whitespace in one token, e.g.
+ * `submit from:"#signup form"`.
+ *
+ * @param input - Raw `data-kui-on` attribute value.
+ * @returns The activation/source pair, or no pair when any token is malformed.
+ * @complexity O(n) time in input length; O(n) space for tokenisation.
+ */
+export declare function parseActivationAttribute(input: string | null): ParsedActivationAttribute;
 /**
  * Parse a `data-kui` attribute value.
  *
@@ -20,3 +39,11 @@ export declare function splitTopLevel(input: string, delimiter: ',' | ' ', warni
  * @overallScore 100
  */
 export declare function parse(input: string): ParsedValue;
+/**
+ * Write a hoisted value once. A second, differing value across segments is an authoring mistake;
+ * first one wins so behaviour stays deterministic.
+ *
+ * @complexity O(1) time, O(1) space.
+ * @overallScore 100
+ */
+export declare function assignOnce<K extends 'activation' | 'timeline' | 'threshold' | 'actions' | 'cascade' | 'spread' | 'order' | 'cols' | 'along' | 'rm' | 'func'>(result: ParsedValue, key: K, value: ParsedValue[K], label: string): void;

package/dist/types/core/register-into.d.ts

@@ -0,0 +1,29 @@
+/**
+ * How the showcase module is handed a registry.
+ *
+ * A near-copy of `registerInto`/`asRegistry`/`hasRegistrarShape` from `src/3d/register.ts`
+ * (itself a copy of `src/advanced/base.ts:519-568`) — deliberately copied rather than imported.
+ * `src/showcase/` ships in core today but is designed to split into its own `<script>` bundle and
+ * subpath later (see `.claude/showcase-run/showcase-plan.md`'s "Exact steps to split"), and importing a
+ * sibling tier's helper would mean the split could not happen without also shipping whichever tier
+ * that helper lived in. This file is the third copy of the same nine lines; the two originals stay
+ * the reference implementation, and if the shape gate's rule ever changes, all three move together.
+ * `test/showcase-seam.test.ts` covers this copy the same way `test/3d-register-gate.test.ts` mirrors
+ * `src/advanced/__tests__/register-gate.test.ts`, so a drift shows up as a failing test rather than
+ * a browser bug.
+ */
+import type { Preset, Primitive } from './types.js';
+import type { Registry } from './registry.js';
+import type { Animator } from './animator.js';
+/**
+ * Register one module's primitives and presets onto a `Registry`, an `Animator`, or anything
+ * carrying either shape.
+ *
+ * @param target - The registry, the animator, or a host exposing one as `.registry`.
+ * @param primitives - One primitive or a list of them.
+ * @param presets - One preset or a list of them.
+ * @param name - Spelled into the thrown message, so it names the function the consumer called.
+ * @returns `target`, so callers can chain.
+ * @complexity O(n) in primitives plus presets.
+ */
+export declare function registerInto(target: unknown, primitives: Primitive | Primitive[], presets: Preset | Preset[], name?: string): Registry | Animator;

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

@@ -6,9 +6,16 @@ export interface ResolvedEffect {
 /**
  * Name → primitive alias table.
  *
- * The catalog's ~237 names come from 29 primitives; 48 of them are one primitive with different
- * parameter defaults. Presets are therefore data rows, not code, and adding a name in a later
- * release costs a table entry. See docs/catalog.md.
+ * The catalog's 302 names come from 159 primitives; 143 of the names are aliases — the
+ * same primitive with different parameter defaults. Presets are therefore data rows, not
+ * code, and adding a name in a later release costs a table entry. See docs/catalog.md.
+ *
+ * Those two numbers are derived, never incremented by hand: `createRegistry().names().length`,
+ * and the count of distinct `resolve(name).primitive.id` across them. Do not add to a
+ * remembered total — the figures above were stale by 31 names and 21 primitives when last
+ * checked, because someone did. Note they count *primitives*, which is not the same thing as
+ * the "primitive families" docs/catalog.md tallies; that grouping is curatorial and has no
+ * registry equivalent.
  */
 export declare class Registry {
     private primitives;

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

@@ -0,0 +1,91 @@
+import type { EffectSpec, Renderer, Timeline } from './types.js';
+export type PlaybackKey = 'repeat' | 'yoyo';
+/**
+ * Whether a `key:value` key is one this module owns, so `parse.ts` can dispatch with one lookup
+ * rather than a growing `||` chain against its own complexity ceiling.
+ *
+ * @complexity O(1) time and space.
+ * @overallScore 100
+ */
+export declare function isPlaybackKey(key: string): key is PlaybackKey;
+/** Where a playback token came from, so the diagnostics can quote it back. */
+export interface PlaybackContext {
+    segment: string;
+    warn: (message: string) => void;
+}
+/**
+ * Validate and lift one `repeat:`/`yoyo:` token onto the spec being built.
+ *
+ * Validated here, at parse time, for the reason `rm:` is: both are closed value sets with no
+ * expression forms, so there is nothing a later stage could know that this one does not, and the
+ * author is owed the diagnostic next to every other grammar diagnostic. The *timeline*-dependent
+ * refusals are the opposite case and live in {@link resolvePlayback}, which runs where the
+ * element's timeline and renderer are known.
+ *
+ * Every rejection is a warning plus no value, never a warning plus a half-applied one — the same
+ * fail-open `applyGate` uses. A mistyped count leaves the effect playing exactly once, which is
+ * what it did before the author added the key.
+ *
+ * @complexity O(n) time in the value's length; O(1) space.
+ * @overallScore 100
+ */
+export declare function applyPlayback(spec: EffectSpec, key: PlaybackKey, value: string, context: PlaybackContext): void;
+/** What {@link resolvePlayback} needs to know about one compiled segment. */
+export interface PlaybackInput {
+    /** Preset name. Only ever used in warnings, which have to name what the author wrote. */
+    name: string;
+    renderer: Renderer;
+    /** Whether the preset's from-state is one the visitor must not see. See `Preset.cloak`. */
+    cloak?: boolean;
+    timeline: Timeline;
+    repeat?: string;
+    yoyo?: boolean;
+}
+/** The playback settings that survived, plus anything the author needs told. */
+export interface PlaybackResolution {
+    repeat?: string;
+    yoyo?: boolean;
+    warnings: string[];
+}
+/**
+ * Decide what an authored `repeat:`/`yoyo:` actually compiles to, given the renderer and timeline.
+ *
+ * Refusals here **drop the modifier and keep the effect**, which is the same fail-open
+ * `refuseContainerGate` uses one function away in `compile.ts`: the effect still runs, it simply
+ * runs the way it would have without the key, and the author is told by name. It is the right
+ * direction for this feature specifically because the failure mode of *keeping* an impossible
+ * repeat is not "nothing happens" but a visibly broken element — see the progress-timeline case.
+ *
+ * @complexity O(1) time; O(1) space beyond the returned warnings.
+ * @overallScore 100
+ */
+export declare function resolvePlayback(input: PlaybackInput): PlaybackResolution;
+/**
+ * The finite number of plays a validated `repeat:` asks for.
+ *
+ * @returns The count, or `undefined` for `infinite` and for an unwritten `repeat:` — the two cases
+ *   where no caller may do arithmetic with it.
+ * @complexity O(n) time in the value's length; O(1) space.
+ * @overallScore 100
+ */
+export declare function repeatCount(repeat: string | undefined): number | undefined;
+/** Whether a validated `repeat:` asks for a loop with no end. */
+export declare function isInfiniteRepeat(repeat: string | undefined): boolean;
+/** The value a track's `animation-direction` takes. `normal` is the CSS initial value. */
+export declare function directionValue(yoyo: boolean | undefined): string;
+/**
+ * A CSS time expression scaled from one iteration to the whole playback.
+ *
+ * Used by both consumers of a repeat that has to do arithmetic — the `at:` sequencer's "after the
+ * previous one ends", and the pin scrub head in `declarations.ts` — so the two cannot disagree
+ * about how long a repeated effect takes.
+ *
+ * Returns `duration` untouched for an unwritten or single repeat, which is what makes every
+ * attribute written before this parameter existed compile byte-for-byte identically. Never called
+ * with `infinite`: both callers refuse that case by name first, because `calc(600ms * infinite)`
+ * is not an expression and a browser drops the whole declaration rather than reporting it.
+ *
+ * @complexity O(n) time in the expression's length; O(1) space.
+ * @overallScore 100
+ */
+export declare function playbackExpression(duration: string, repeat: string | undefined): string;