@fusion.dev/helix 0.0.0-dev

package/dist/aura/root/aura-root.d.ts

@@ -0,0 +1,447 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import type { CSSResultGroup, TemplateResult } from 'lit';
+/**
+ * @summary A lit, drifting background, drawn from the token layer.
+ *
+ * @description
+ * One fragment shader over a full-screen triangle, with the palette read from
+ * the tokens rather than given as colors. That is the whole reason this belongs
+ * in a design system instead of in a page: a background written with hex values
+ * is an asset that has to be re-cut when the brand moves, and one written
+ * against `--helix-color-primary` is a consequence of it.
+ *
+ * **Every shape ramps through four token stops**, and the token layer inverts
+ * each of them: the page's own background, `primary-subtle`, `primary`, and
+ * then a peak. The peak is the foreground on a dark page and `primary-active`
+ * on a light one, because mixing a saturated hue toward near-black takes the
+ * chroma out of exactly the pixels carrying the most of it. Which way the page
+ * runs is not asked of the mode, which is a private token: it is read off the
+ * ground's own luminance, which the shader already has.
+ *
+ * **No dependency, and no scene graph.** The geometry is three vertices derived
+ * from `gl_VertexID`, so there is no attribute, no buffer and no upload. The
+ * common implementations of this reach for a 3D library to draw one quad, which
+ * is a camera and a material system for four vertices that never move.
+ *
+ * **It stops when nobody is looking**, off screen and in a background tab, and
+ * `prefers-reduced-motion` gets one still frame rather than an empty box: the
+ * composition is the point and the drift is a garnish.
+ *
+ * **A layer over an interactive aura has to let the pointer through.** The
+ * element is hit-testable only when `interactive` is set, because a background
+ * that swallows clicks is worse than one that does nothing, but a scrim or an
+ * overlay a consumer paints on top will absorb the move before it arrives. Any
+ * decorative layer above this wants `pointer-events: none`. It has already
+ * caught this repository's own bench once.
+ *
+ * **The fallback needs no detection.** Where WebGL is refused the canvas never
+ * paints and is transparent, and the host carries a gradient of the same tokens
+ * underneath. Nothing has to ask whether it worked.
+ *
+ * Presentation only, so there is no headless tier: the split exists to keep
+ * behavior separate from styling, and there is no structure or semantics here
+ * to separate. Decorative, so the host is hidden from assistive technology and
+ * takes no pointer events.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category media
+ * @aliases Backdrop, Background, Atmosphere, Gradient
+ * @documentation https://helix.fusion.dev/components/aura
+ *
+ * @csspart canvas - The surface the shader draws into.
+ */
+export declare class HelixAura extends HelixElement {
+    static styles: CSSResultGroup;
+    /**
+     * Which form the light takes. Absent is `braid`.
+     *
+     * Reflected because the fallback gradient selects on it, and given no default
+     * for the same reason every axis here has none: a default on a reflected
+     * property writes the attribute onto every host anybody renders.
+     *
+     * **`variant` and not `shape`, which it was until 26 Aug 2026.** `shape` is
+     * an axis about geometry, `circle` against `square`, `arc` against `ring`,
+     * and it is registered as one now. Aurora, braid and caustics are not
+     * geometries; they are eleven names for a look, which is what `variant` is
+     * for by the rule the registry already states. Renamed rather than
+     * grandfathered because nothing is published yet: there is no `helix-v` tag,
+     * so this costs an edit today and a deprecation later. See 236.
+     */
+    variant?: 'aurora' | 'braid' | 'caustics' | 'flow' | 'fracture' | 'lattice' | 'particles' | 'rays' | 'streaks' | 'threads' | 'waves';
+    /**
+     * How far the settings wander on their own, `0` still and `1` restless.
+     *
+     * **One property rather than a range on each of the five.** A range per axis
+     * is five more things to author and four more chances to write a pair that
+     * fights another; the reason to want any of it is the same reason in every
+     * case, which is that a fixed field is legibly a loop. So this is an amount,
+     * and each axis is given its own span and its own period.
+     *
+     * The periods are irrational multiples of each other, so no two axes come
+     * back into phase and the field has no cycle a reader can count. That is the
+     * difference between a background that breathes and one that is obviously on
+     * a timer.
+     */
+    drift: number;
+    /**
+     * What the pointer does, where the shape's own answer is not wanted.
+     *
+     * Absent is `native`, which is each shape answering in the terms it is made
+     * of: braid leans, rays are occluded, threads pinch, particles scatter. The
+     * named options are generic, and are a deliberate step down in meaning. A
+     * response made of the same material as the shape says something about that
+     * shape; a lamp following the cursor says the same nothing on all nine.
+     *
+     * They exist because a consumer may want the quieter, more conventional
+     * answer, and because `none` is a real requirement. Not because any of them
+     * is the better default.
+     */
+    interaction?: 'light' | 'none' | 'ripple' | 'shadow';
+    /**
+     * How far the pointer reaches into the field, `0` upward.
+     *
+     * Multiplied into the presence the pointer already fades in and out with, so
+     * it scales the whole response rather than any one part of it, whichever
+     * interaction is in play.
+     */
+    reach: number;
+    /**
+     * Whether the pointer shifts and lifts the field.
+     *
+     * Reflected because the stylesheet selects on it: a background is not
+     * hit-testable at rest, or it would swallow clicks meant for what is over it,
+     * and an element that is not hit-testable never receives the `pointermove`
+     * this listens for. Asking for the pointer is asking for the hit test.
+     */
+    interactive: boolean;
+    /**
+     * How soft the falloff is, `0` tight and `1` diffuse.
+     */
+    bloom: number;
+    /**
+     * Overall brightness, as a multiplier on the field.
+     */
+    gain: number;
+    /**
+     * Feature size, as a multiplier on the sampled coordinates.
+     */
+    scale: number;
+    /**
+     * How fast it drifts, as a multiplier on time.
+     */
+    speed: number;
+    /**
+     * The field's rotation, in degrees.
+     */
+    tilt: number;
+    /**
+     * Where the axis crosses the top edge, as a fraction of the width.
+     *
+     * **An angle does not say what a consumer means, and this does.** The axis
+     * runs `x = y * tan(tilt)`, so the same `tilt` puts the exit somewhere else
+     * the moment the box changes shape. Measured on the landing page hero, which
+     * was tuned to 23 degrees against a box two screens tall: at a 1152 pixel
+     * window that lands the exit at 979, between the navigation and the actions,
+     * and at a 720 pixel window it lands at 611, a third of the way further left.
+     * Nothing is wrong with either number and neither is what anybody asked for.
+     *
+     * Given as a fraction rather than a length so it survives the same change:
+     * `0` is the left edge, `0.5` the middle and `1` the right edge, at every
+     * size. Absent leaves `tilt` in charge, so an angle is still sayable where
+     * the angle really is the point, which is what an aura in a square tile
+     * wants.
+     *
+     * **The fraction is measured across the whole width, and for a while it was
+     * not.** The first expression corrected for the aspect once in the wrong
+     * direction and never subtracted the center, so the value read as an offset
+     * from the middle that also moved with the box: on a 1440 by 1800 hero `0.5`
+     * put the axis at 81.3% of the width and `0` was the only value that reached
+     * the middle. The contract above is now solved against what the shader draws
+     * rather than asserted beside it.
+     *
+     * Derived from the box the resize observer already keeps, so it costs no
+     * layout read per frame, and the drift is applied to the result rather than
+     * to the angle behind it: the field still wanders, around a bearing that
+     * holds the exit where it was put.
+     */
+    terminus?: number;
+    /**
+     * How much the members of a population differ from one another, `0` a set
+     * that is uniform and `1` the resting amount. Clamped to that range: these
+     * are interpolations, so a larger number extrapolates rather than
+     * exaggerating, and a streak whose length has passed through zero is drawn
+     * as a bar across the whole frame.
+     *
+     * Read by the shapes made of many similar things, whether those are counted
+     * or continuous: `streaks`, whose lanes draw a speed, a length, a width, a
+     * spacing and a weight apiece; `particles`, whose motes draw a size, a
+     * brightness and a wander; and `rays` and `aurora`, whose fan, bundles and
+     * folds widen or even out. `braid`, `waves` and `flow` have a
+     * single subject and nothing to vary, and `threads` is even on purpose, so on
+     * those four this is inert.
+     */
+    variance: number;
+    /** Repaints when the palette moves, which no re-render would do on its own. */
+    private readonly tokens;
+    /**
+     * The four ramp stops, resolved.
+     *
+     * **Cached, because reading them is not free and they do not move.** Each
+     * read sets a style, calls `getComputedStyle`, fills a pixel and reads it
+     * back: a style recalc and a canvas readback apiece. Doing that inside
+     * `paint` meant four of each on every frame, forever, to fetch values that
+     * change only when the color mode does. The controller already says when
+     * that happens, so this is filled from there and from the first paint.
+     */
+    private palette;
+    private canvas;
+    private gl;
+    private program;
+    private uniforms;
+    /** The pending context release, or `0`. Canceled by a reconnection. */
+    private release;
+    /** What every context is asked for, here rather than at two call sites. */
+    private static readonly CONTEXT;
+    private frame;
+    private elapsed;
+    private last;
+    private width;
+    private height;
+    /**
+     * Where the pointer has been, as flat triples of x, y and age.
+     *
+     * A ring rather than a queue: the oldest slot is overwritten, so nothing is
+     * allocated and the cost is the same on the first second and the thousandth.
+     */
+    private readonly trail;
+    private trailNext;
+    /**
+     * The same marks, oldest first, which is what the shader is given.
+     *
+     * The ring's own order is not time order, and the wake is drawn as a polyline
+     * through consecutive entries: a segment across the wrap joined the newest
+     * mark to the oldest and drew a bright bar clean through the middle of the
+     * field. Unrolled once per frame, which is eight copies.
+     */
+    private readonly ordered;
+    /**
+     * The live end of the stroke, outside the ring.
+     *
+     * **In the ring it destroyed a mark every time it committed.** The head was
+     * the slot at `trailNext`, so advancing wrote over whatever was oldest, and
+     * the tail of the stroke lost a point instantly rather than fading. Held
+     * apart, committing appends where the head already is: the polyline goes from
+     * ending at P to ending at P, P, which is the same shape, and nothing jumps.
+     */
+    private readonly head;
+    /** Where the pointer is, and where the field has got to. The gap is weight. */
+    private readonly target;
+    private readonly eased;
+    private motion;
+    private visible;
+    /**
+     * The element's box, cached.
+     *
+     * **Read per event, this was the ragged half.** `getBoundingClientRect` forces
+     * a synchronous layout, and a pointer emits events far faster than the
+     * display refreshes: a 1000Hz mouse flushed layout a thousand times a second
+     * to compute a number that only changes when the page reflows. Refreshed from
+     * the resize observer and from scroll, both of which are exactly when it can
+     * go stale, and never from the handler that reads it.
+     */
+    private box;
+    /** Watches the element's own size, so no frame has to ask for it. */
+    private sized;
+    /**
+     * Whether the field has drawn its opening frame yet.
+     *
+     * **The box changes shape while a page is arriving, and this shader is scaled
+     * by the box.** `p.y` spans [-1, 1] over the element's height, so a feature's
+     * size in pixels is proportional to how tall the box happens to be when the
+     * frame is drawn. A page that upgrades its custom elements, loads its fonts
+     * and settles its images passes through several heights on the way to its
+     * final one, and painting each of them draws the same field at several
+     * scales: it opens coarse and tightens, which reads as the background zooming
+     * out on load rather than as a background.
+     *
+     * Refusing the degenerate 0 by 0 box fixed the worst of it, a 2 by 2 drawing
+     * buffer smeared over the page, and left the ordinary case: a first real box
+     * that is simply not the last one.
+     *
+     * So the opening frame waits for the box to stop moving. Nothing paints until
+     * a measurement has stood unchanged for one animation frame, which is the
+     * cheapest definition of settled that is not a guess, and the host's own
+     * gradient covers the wait. After that a resize repaints immediately, because
+     * by then a change is the window moving rather than the page arriving.
+     */
+    private opened;
+    /** The pending opening frame, canceled and rescheduled by each new box. */
+    private opening;
+    /**
+     * When to stop waiting and draw anyway.
+     *
+     * A page that resizes the field every frame forever would otherwise never get
+     * an opening frame at all. Half a second is far longer than a load takes to
+     * settle and far shorter than a reader waits before deciding the background is
+     * simply a gradient.
+     */
+    private openBy;
+    protected render(): TemplateResult;
+    protected firstUpdated(): void;
+    private start;
+    /**
+     * The context and the program, from whatever canvas can still give one.
+     *
+     * **A canvas whose context was force-lost never yields a working one again**,
+     * and the release below used to assume the opposite: `getContext` hands back
+     * the very same dead object, which reports `isContextLost()` and answers
+     * `null` to every `getShaderParameter`. So `link` failed, `start` returned
+     * before installing a single observer, and the element sat connected and
+     * permanently blind, holding whatever buffer it last painted. Measured on the
+     * landing page, where one remove-and-reinsert was enough: the frozen frame
+     * was the 2x2 the first `measure` took before layout, stretched across two
+     * screens as a gray smear that reads as a broken gradient rather than as a
+     * dead component. The only sound in the console was `getShaderInfoLog`
+     * answering `null`, twice per element.
+     *
+     * A spent canvas is therefore replaced rather than re-asked. `restoreContext`
+     * is the other way and is not reachable from here: it needs the `webglcontextlost`
+     * event default-prevented and the extension held from before the loss, and it
+     * restores asynchronously, so `start` would have to become a state machine to
+     * use it. A fresh canvas is synchronous and cannot half-succeed.
+     */
+    private build;
+    connectedCallback(): void;
+    protected updated(): void;
+    disconnectedCallback(): void;
+    /**
+     * Gives the context back, once nothing has claimed the element again.
+     *
+     * **The context is not released by dropping the reference.** A browser caps
+     * live WebGL contexts at about sixteen and drops the oldest when a
+     * seventeenth is asked for, so a page that mounts and unmounts auras kills
+     * the ones still on screen: the symptom is an aura elsewhere going blank,
+     * which looks like a fault in that element and is this one. The context
+     * belongs to the canvas, and the canvas is held by the shadow root until the
+     * element is collected, which is a moment nothing here controls and which is
+     * far too late for a cap of sixteen. `WEBGL_lose_context` is the only way.
+     *
+     * **It spends the canvas**, which is what `build` is written around: the
+     * canvas can never serve a context again and a returning element takes a
+     * fresh one.
+     */
+    private readonly drop;
+    /**
+     * Resolves the ramp. Called when the palette moves, not when a frame draws.
+     *
+     * Light pages peak on a deep brand blue and dark ones on the foreground, and
+     * the ground is what says which: mixing a saturated hue toward near-black
+     * takes the chroma out of exactly the pixels carrying the most of it. Read
+     * from the ground's own luminance rather than asked of the color mode, which
+     * is a private token this tier may not reach for.
+     */
+    private readPalette;
+    private link;
+    /**
+     * Re-reads the box and resizes the drawing buffer to match.
+     *
+     * **Called from the observer, never from the frame.** `clientWidth` is a
+     * layout read, and doing it in `tick` meant a forced synchronous layout on
+     * every single frame to learn a number that changes when the box changes and
+     * at no other time. A `ResizeObserver` is told when that is.
+     *
+     * Returns whether the drawing buffer was resized, which is the same question
+     * as whether it was cleared, and so whether the caller owes it a frame.
+     */
+    private measure;
+    private paint;
+    /**
+     * The opening frame, one animation frame after the box last changed.
+     *
+     * Each new measurement cancels the pending frame and books another, so a run
+     * of resizes collapses to a single paint at the end of it rather than one per
+     * step. `openBy` stops that from being unbounded.
+     */
+    private open;
+    /** One frame, now, for a change that has to show while the loop is stopped. */
+    private paintOnce;
+    /**
+     * The shortest gap between two painted frames, for a field nobody points at.
+     *
+     * **A drifting field does not need the display's rate and a pointer does.**
+     * `tick` advances on `(now - this.last) / 1000`, so motion is wall-clock: at
+     * half the frames the field moves the same distance in the same time, sampled
+     * more coarsely. `delta` is already clamped at 0.05, which is a floor of 20
+     * frames a second, and 30 sits inside that with room. A cap at 15 would land
+     * on the clamp and the field would genuinely drag, which is the failure that
+     * would be misdiagnosed as choppiness.
+     *
+     * **`interactive` is the exception and it is the whole exception.** The
+     * element eases `presence` toward the pointer on a 50ms rise constant, so at
+     * 33ms a frame the entire response is one or two samples and the follow reads
+     * as a lag rather than a lightness. Every field on the landing page leaves
+     * `interactive` unset; the only one that sets it is the lab on
+     * `/helix/aura`, where it is a toggle a reader chose. So the cap applies where
+     * nothing is being followed and lifts where something is.
+     *
+     * **Measured before it was capped, because the cost had changed.** 252 was
+     * filed against one field on the first two screens. It is three now, one per
+     * transparent run of the page, and with the frame limiter off they drew 2,654
+     * times in three seconds against 1,276 for one: the work scales with the count
+     * because each instance draws once per callback. Capping the two that nobody
+     * points at is most of that back.
+     */
+    private static readonly CAPPED;
+    private readonly tick;
+    private play;
+    private stop;
+    /**
+     * The angle actually drawn, which is `terminus` resolved against the box.
+     *
+     * A getter rather than a stored value because the box changes and this has no
+     * business knowing when: it is read once per frame from numbers already
+     * there.
+     *
+     * The solve is `tiltFor` in `aura-axis.ts` rather than an expression here,
+     * and that is the fix for how this went wrong twice. Both times the
+     * arithmetic sat inside this getter next to a sentence describing different
+     * arithmetic, and nothing in the repository could tell they disagreed. It is
+     * callable now, and `aura-root.dom.spec.ts` runs it against a model of the
+     * shader in both directions. See 155.
+     */
+    private get bearing();
+    private drifted;
+    /** Ages the wake, and drops a fresh mark where the pointer has moved far. */
+    private age;
+    private readonly handlePointer;
+    /**
+     * Keeps the head of the wake on the cursor, and commits it as it travels.
+     *
+     * **The head used to be a committed mark, and that was both faults at once.**
+     * Marks are spaced by distance so eight slots cover a gesture rather than the
+     * last few milliseconds of one, but committing was also the only time the
+     * stroke grew: its leading end therefore sat up to a full gate behind the
+     * pointer, and caught up in jumps of exactly that size. Latent, and jagged,
+     * for one reason.
+     *
+     * So the slot at `trailNext` is provisional. It is rewritten every frame to
+     * wherever the field has actually eased to, which is where the cursor looks
+     * like it is, so the stroke always reaches the pointer. Crossing the gate does
+     * not move the head, it just stops the previous position from being
+     * overwritten, and a new provisional head starts from there. The wake grows
+     * continuously and is still only ever eight points.
+     *
+     * Measured against `eased` rather than `target`, or the stroke would reach a
+     * place the field has not arrived at yet and lead its own parallax.
+     */
+    private advanceWake;
+    private readonly handleLeave;
+    private readonly handleVisibility;
+    private readonly handleScroll;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-aura': HelixAura;
+    }
+}