@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,711 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+import '../../menu/index.js';
+/**
+ * @summary Plays a video, with controls this library draws rather than the
+ * browser's.
+ *
+ * @description
+ * **The picture is a real `<video>`.** Decoding, buffering, captions, Picture
+ * in Picture, AirPlay and the codecs a device happens to have are all the
+ * platform's, and none of them can be had from anything else. What is replaced
+ * is the control bar, which is the one part of a video element that cannot be
+ * styled and looks different in every browser.
+ *
+ * **Every control is a real control.** The scrubber and the volume are
+ * `<input type="range">`, so a reader gets arrow keys, Home and End, the
+ * platform's own touch target and its screen reader announcement without this
+ * element implementing any of it. Drawing a div and listening for pointer moves
+ * is how a media player ends up unusable from a keyboard.
+ *
+ * **Native controls are the fallback, not the default.** Where a consumer sets
+ * `controls`, the browser's bar is used and this one is not drawn: two sets of
+ * controls over one video is worse than either alone, and a consumer who asked
+ * for the native bar has a reason.
+ *
+ * The keys are the ones every player uses: Space and `k` to play or pause, the
+ * arrows to seek and to change the volume, `m` to mute, `f` for fullscreen.
+ * They are bound on this element rather than on the document, because a video
+ * is not a palette: keys belong to it only while a reader is on it.
+ *
+ * **And none of them where `controls` is set.** The browser's own bar owns
+ * those keys, and two handlers on one press is a video that seeks twice or
+ * plays and immediately pauses. The focus stop goes with them, since the native
+ * controls bring their own.
+ *
+ * **`<source>` and `<track>` are copied into the video, not slotted into it.**
+ * A media element runs its resource selection over its own child *nodes*, and a
+ * slot is one node: the sources and the caption tracks a consumer wrote were
+ * assigned into the flattened tree and the video never saw any of them. It had
+ * no text tracks, no current source and a `readyState` of zero, so a video
+ * given sources this way did not merely lack captions, it did not play.
+ *
+ * They are copied rather than moved, because the consumer's light DOM is theirs
+ * and a framework that re-renders it would find its children gone. The copies
+ * are rebuilt whenever the slot changes and the video is asked to load again,
+ * which is what makes a `<track>` added later take effect.
+ *
+ * **The lock screen and a headset's buttons work, and one player owns them.**
+ * There is one `navigator.mediaSession` per page, so the rule is stated rather
+ * than left to render order: whichever player was started last owns it, which
+ * is what a reader means by "this one" when they press play on their
+ * headphones. The title comes from `label` and the artwork from `poster`.
+ *
+ * **`remote` sends the picture somewhere else.** The Remote Playback API is
+ * what Safari implements for AirPlay and Chrome for Cast, so one control covers
+ * both and the platform supplies the device list. It is offered only once
+ * something has answered `watchAvailability`: a button that opens an empty list
+ * is worse than no button, and a consumer who wants none can set
+ * `disableremoteplayback` on this element.
+ *
+ * The properties below are written by this component and read by whoever draws
+ * it. A consumer sets none of them: they carry a number this element computed
+ * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
+ * without measuring anything itself.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category media
+ * @aliases Player, Media, Movie
+ * @documentation https://helix.fusion.dev/components/video
+ *
+ * @slot - `<source>` and `<track>` elements, which are copied into the video.
+ * @slot back - Top left over the frame, for a way out of a set.
+ * @slot controls - Added to the control bar, before fullscreen.
+ * @slot poster - Shown over the video until it starts.
+ *
+ * @event {Event} ended - Relayed for the same reason.
+ * @event {HelixNextEvent} helix-next - Fired when the reader asks for the next item.
+ * @event {HelixPreviousEvent} helix-previous - Fired when they ask for the previous one.
+ * @event {Event} pause - Relayed for the same reason.
+ * @event {Event} play - Relayed, because it does not cross a shadow boundary.
+ *
+ * @csspart back - The region top left, for a way out of a set.
+ * @csspart captions - Subtitles on and off.
+ * @csspart captions-menu - The language menu, where there is more than one.
+ * @csspart captions-menu-back - The control that returns from a submenu.
+ * @csspart captions-menu-back-mark - The glyph on the back control of a submenu.
+ * @csspart captions-menu-empty - Shown when there are no items to show.
+ * @csspart captions-menu-header - The bar above a submenu, holding the way back and its name.
+ * @csspart captions-menu-loading - Shown while the items are still on their way.
+ * @csspart captions-menu-surface - The floating panel the menu is drawn on.
+ * @csspart captions-menu-title - The name of the submenu that is showing.
+ * @csspart controls - The bar along the bottom.
+ * @csspart cue - The caption on screen now, drawn by this element.
+ * @csspart download - Saves the file, where it was asked for.
+ * @csspart entry - One row in a menu this player opens.
+ * @csspart entry-item - The row, which is an `<a>` where `href` is set.
+ * @csspart entry-mark - The trailing mark: a tick when checked, a caret when it opens.
+ * @csspart entry-start - The leading column, which is a slot and is always there.
+ * @csspart failure - What is said when the source will not play.
+ * @csspart forward - The control that goes on ten seconds.
+ * @csspart fullscreen - The whole screen, and back.
+ * @csspart icon - A glyph this component draws.
+ * @csspart loading - What is said while the picture waits for more of itself.
+ * @csspart loading-mark - The part of that which spins.
+ * @csspart more - The button that opens it.
+ * @csspart mute - Sound on and off.
+ * @csspart next - Asks for the next item, where it was asked for.
+ * @csspart overflow - The menu holding the controls kept off the bar.
+ * @csspart overflow-back - The control that returns from a submenu.
+ * @csspart overflow-back-mark - The glyph on the back control of a submenu.
+ * @csspart overflow-empty - Shown when there are no items to show.
+ * @csspart overflow-header - The bar above a submenu, holding the way back and its name.
+ * @csspart overflow-loading - Shown while the items are still on their way.
+ * @csspart overflow-surface - The floating panel the menu is drawn on.
+ * @csspart overflow-title - The name of the submenu that is showing.
+ * @csspart pip - Picture in picture, where it was asked for and exists.
+ * @csspart play - Play and pause.
+ * @csspart poster - What covers it before it plays.
+ * @csspart previous - Asks for the previous one.
+ * @csspart remote - Play on another device, where one is available.
+ * @csspart rewind - The control that goes back ten seconds.
+ * @csspart scrubber - Where it is, and where to go.
+ * @csspart sound - The speaker and its level, which are one control.
+ * @csspart speed - Playback speed, where it was asked for.
+ * @csspart stage - The box holding the picture and its controls, and the focus
+ * target the keys are bound to.
+ * @csspart start - The mark over the picture before anything has played.
+ * @csspart time - The position and the duration.
+ * @csspart video - The video itself.
+ * @csspart volume - How loud.
+ *
+ * @cssproperty --video-intrinsic-ratio - The media's own aspect ratio, once it is known. `--video-aspect-ratio` overrides it.
+ * @cssproperty --video-level - The current volume, 0 to 1.
+ * @cssproperty --video-progress - How far playback has reached, as a fraction of the duration.
+ */
+export declare class HelixHeadlessVideo extends HelixElement {
+    /**
+     * Where the video is, for the common case of one file.
+     */
+    src: string;
+    /**
+     * A still shown before it plays, which the platform draws itself.
+     */
+    poster: string;
+    /**
+     * Accessible name, since a video is not described by its filename.
+     */
+    label: string;
+    /**
+     * Whether it starts again at the end.
+     */
+    loop: boolean;
+    /**
+     * Whether it *starts* silent, which is what an autoplaying video must do.
+     *
+     * **Renamed from `muted`, because that is what it always was.** The platform
+     * splits these two: the `muted` content attribute reflects to `defaultMuted`,
+     * and the `muted` property is live state a reader's click moves without
+     * touching the attribute. This element declared one property called `muted`,
+     * bound it to the attribute, and tracked the live state privately as
+     * `silent`, so `<helix-video>.muted` answered what the author wrote rather
+     * than whether there was sound. A name matching the platform's while meaning
+     * something else is worse than a name the platform does not have, and
+     * `check:platform-fidelity` could not see it: it compares names.
+     */
+    defaultMuted: boolean;
+    /**
+     * Whether it plays where it sits rather than taking over the screen.
+     */
+    playsInline: boolean;
+    /**
+     * Whether the browser draws the controls instead of this element.
+     *
+     * A fallback rather than a default. Two bars over one video is worse than
+     * either alone, so this one is not drawn at all when it is set.
+     */
+    controls: boolean;
+    /**
+     * How much to fetch before anything is asked for.
+     */
+    preload: 'auto' | 'metadata' | 'none';
+    /**
+     * Whether it starts on its own, which a browser only allows while silent.
+     *
+     * Forwarded rather than acted on. Whether an unprompted play is permitted is
+     * the browser's policy and not this element's, and `play()` already swallows
+     * the refusal: what follows a refused autoplay is a paused player showing its
+     * start control, which is the correct thing to be looking at.
+     */
+    autoplay: boolean;
+    /**
+     * How the media is fetched across origins, which decides whether a track can
+     * be read.
+     */
+    crossOrigin: 'anonymous' | 'use-credentials' | null;
+    /**
+     * Whether the browser may offer picture in picture.
+     */
+    disablePictureInPicture: boolean;
+    /**
+     * Whether the browser may offer playback on a remote device.
+     */
+    disableRemotePlayback: boolean;
+    /**
+     * Controls beyond the ones every player has, named in the order they appear.
+     *
+     * A list rather than a property apiece. A bar is a row with a budget, and a
+     * boolean per feature invites a consumer to switch all of them on: naming
+     * them makes the row a decision, and makes the order theirs. Anything
+     * unrecognised is skipped rather than throwing, since the list is markup and
+     * a typo should cost a control, not a page.
+     *
+     * `pip` is offered only where the platform has it, checked rather than
+     * assumed: it is absent on iPhone and behind a flag in Firefox, and a button
+     * that cannot work is worse than one that is not there.
+     *
+     * The names are `speed`, `pip`, `remote` and `download`.
+     *
+     * **`download` is named and never assumed.** Offering the file is a decision
+     * about the content rather than about the player, and plenty of consumers
+     * decline it deliberately. It is also the one control whose success is not
+     * ours to promise: the attribute is ignored cross-origin, so a file served
+     * from somewhere else opens rather than saves, which is the browser's rule
+     * and not something a player can work around.
+     */
+    extraControls: string;
+    /**
+     * Controls that go behind one button instead of onto the bar, named the same
+     * way.
+     *
+     * **Named rather than measured, and the reason is that a width cannot answer
+     * this.** A media query asks about the window, and the bar's problem is its
+     * own width: a video in a 320px sidebar on a desktop is cramped and a
+     * full-bleed hero on a phone is not. A container query asks the right
+     * question and still cannot answer it, because how many controls there are is
+     * the consumer's, so the threshold is not a width but a width per control,
+     * which is a guess. And a control that moves between the bar and a hidden
+     * menu as the layout shifts is a control the reader has to find twice.
+     *
+     * So the consumer says where the fold is, which they can, having already
+     * named the controls in order. A name in both lists is drawn once, on the
+     * bar: two of the same control is worse than either placement.
+     */
+    overflowControls: string;
+    /**
+     * The big mark over the picture before anything has played, or `none`.
+     *
+     * **On unless it is turned off, because a stopped video has nothing else.**
+     * Measured on the bar as it was: the play glyph is 16 by 16 in a 24 by 24
+     * target, which is 0.12% of a 528 by 396 picture and 0.33% at 320. What a
+     * reader meets first is a still frame with some chrome along the bottom, and
+     * nothing in it says "press to watch".
+     *
+     * `none` is for the cases where that is wrong rather than right: a muted loop
+     * behind a hero, a grid of eight thumbnails, anything where the video is
+     * decoration rather than something to start.
+     *
+     * **Only before the first play.** A video paused halfway already has its bar
+     * up, because a paused video never idles, so the small control is visible and
+     * the reader has just used it. Covering the picture they stopped to look at
+     * would be the opposite of helpful.
+     *
+     * A value rather than a boolean, so the resting state is the attribute's
+     * absence: a boolean defaulting to on would have to be spelled as its own
+     * negation.
+     */
+    startControl?: 'none';
+    /**
+     * Whether the file this points at is ours to hand over.
+     *
+     * `blob:` and `data:` named rather than compared, because the rule `download`
+     * actually follows is same-origin *or one of those two*: a clip a consumer
+     * generated in the page has no origin to match and is theirs to save by
+     * definition. Comparing origins alone called both foreign, so the one case
+     * where a download certainly works was the one case it was not offered.
+     */
+    private get localFile();
+    /**
+     * The speeds offered, slowest first, as multipliers of normal.
+     */
+    speeds: string;
+    /**
+     * How long the bar waits after the pointer stops before it goes, in ms.
+     *
+     * It used to leave the moment the pointer did, which is not how a player
+     * behaves: a reader moving across the picture to reach a control watched it
+     * vanish under them. Zero turns the wait off and the bar goes immediately;
+     * a large number keeps it up for as long as anyone is likely to look.
+     *
+     * The wait is only ever about *idling*. A video that is paused keeps its bar
+     * regardless, because a reader who stopped it is deciding what to do next.
+     */
+    idleDelay: number;
+    /**
+     * What the play control is called while it would start the video.
+     */
+    playLabel: string;
+    /**
+     * And while it would stop it.
+     */
+    pauseLabel: string;
+    /**
+     * What a reader is told while the picture is waiting for more of itself.
+     */
+    loadingLabel: string;
+    /**
+     * And what they are told when it will not play at all.
+     */
+    errorLabel: string;
+    /**
+     * Whether playback has stopped to wait for data.
+     *
+     * **Only ever after somebody asked for playback**, which is what `waiting`
+     * means: the element wanted the next frame and did not have it. Before that,
+     * a video that has loaded nothing is a poster with a play control over it,
+     * which looks deliberate and is. A spinner there would say something is
+     * happening when nothing is, on every video on the page.
+     *
+     * The case this covers is the one that looks like a bug: a picture frozen
+     * mid-play, the scrubber stopped, and nothing on screen saying why.
+     */
+    private buffering;
+    /**
+     * Whether the source failed, which is the other thing a frozen frame can
+     * mean.
+     */
+    private failed;
+    private playing;
+    private position;
+    private knownDuration;
+    private loudness;
+    private silent;
+    private full;
+    private captioned;
+    /**
+     * Which caption track is showing, or `-1` for none.
+     *
+     * `@state`, because it is read off the video rather than declared: a consumer
+     * asking for a language would be naming a track that may not have loaded, and
+     * `default` on the `<track>` is the platform's own way to say it.
+     */
+    private captionIndex;
+    /**
+     * How many caption tracks there are, which decides which control is drawn.
+     *
+     * A count and not a boolean, and that is the whole reason it changed. Tracks
+     * resolve after the element renders, so this is what schedules the update
+     * that draws the control at all; as a boolean it went false to true when the
+     * first one arrived and then never moved again, so a second track landing
+     * left the toggle in place and the language menu was unreachable on exactly
+     * the videos it exists for.
+     */
+    private captionCount;
+    /**
+     * The cue on screen now, as nodes, or nothing between cues.
+     *
+     * Nodes rather than a string, because `VTTCue.text` is the cue's *source*:
+     * WebVTT carries markup, and a caption file in the wild is full of it. `<v
+     * Hildy>` names who is speaking, `<b>` and `<i>` and `<u>` mark emphasis, and
+     * `<c.loud>` classes a line. Rendered as text every one of those arrives on
+     * screen as visible angle brackets.
+     *
+     * `getCueAsHTML` is the platform parsing its own format, so nothing here has
+     * to know the grammar and no cue text is ever treated as HTML: what comes
+     * back is a fragment the browser built, not a string anybody interpolated.
+     */
+    private cue;
+    private rate;
+    /**
+     * Whether the reader has been still long enough for the bar to go.
+     */
+    private idle;
+    private idleTimer?;
+    /**
+     * Whether anything on the network offers to play this.
+     */
+    private remoteAvailable;
+    /**
+     * Whether it is playing somewhere else right now.
+     */
+    private remoteConnected;
+    /** Cancels the availability watch, since it outlives a single render. */
+    private remoteWatch;
+    /** Whether this platform can do a named control at all. */
+    private offers;
+    /** The extras asked for, in order, and only the ones this platform can do. */
+    private get extras();
+    /**
+     * The controls asked for behind the overflow button, in order.
+     *
+     * A name in both lists is on the bar and not here. Drawing it twice is worse
+     * than either placement, and the bar is the one a reader can see.
+     */
+    private get overflow();
+    /**
+     * The sources and caption tracks to copy into the video, as the consumer
+     * wrote them.
+     */
+    private media;
+    /**
+     * The media's own state, under the platform's own names.
+     *
+     * **This element already knew every one of these and kept them private.** It
+     * tracks `currentTime` as `position`, `duration` as `knownDuration`, `volume`
+     * as `loudness`, `paused` as `playing` and `playbackRate` as `rate`, paints
+     * them, and published none of them, so a consumer asking where the video had
+     * reached had nowhere to ask: the `<video>` is inside this shadow root and
+     * `querySelector` does not cross it. 295 is that finding across the library
+     * and this is its clearest case.
+     *
+     * **Read from the element, with the mirror as the fallback.** The element is
+     * the truth and the mirror is a render cache that a media event refreshes, so
+     * reading the mirror alone would answer with whatever the last `timeupdate`
+     * said rather than with where the video is now. The fallback is what answers
+     * on the server and before the first render, where there is no element and
+     * the mirror holds what markup asked for.
+     *
+     * **Accessors rather than reactive properties**, because none of these is a
+     * setting: they are the media's state, and a `@property` would give each one
+     * an attribute that a consumer could write and the element would then have to
+     * disagree with. Where the platform makes one writable this writes it
+     * through, and where the platform does not neither does this.
+     */
+    get currentSrc(): string;
+    /**
+     * Where playback has reached, in seconds.
+     *
+     * Writing seeks, through the same clamp `seek` uses, because a `currentTime`
+     * past the end is the one write the platform answers with an exception.
+     */
+    get currentTime(): number;
+    set currentTime(seconds: number);
+    /** The rate playback returns to, which `defaultPlaybackRate` names natively. */
+    get defaultPlaybackRate(): number;
+    set defaultPlaybackRate(rate: number);
+    /** How long the media runs, in seconds, and `NaN` until that is known. */
+    get duration(): number;
+    /** Whether playback has run off the end. */
+    get ended(): boolean;
+    /** Whether playback is stopped, which is the resting state and not an error. */
+    get paused(): boolean;
+    /** How fast it plays, where 1 is the recorded speed. */
+    get playbackRate(): number;
+    set playbackRate(rate: number);
+    /** Whether pitch is held steady when the rate changes. */
+    get preservesPitch(): boolean;
+    set preservesPitch(preserve: boolean);
+    /** Whether it is currently moving to a new position. */
+    get seeking(): boolean;
+    /** The media's own height in pixels, and zero until the metadata has loaded. */
+    get videoHeight(): number;
+    /** The media's own width in pixels, and zero until the metadata has loaded. */
+    get videoWidth(): number;
+    /**
+     * Whether there is sound, now, which a reader's click moves.
+     *
+     * The live half of the pair above. Writing mutes or unmutes the media itself
+     * rather than the attribute, which is what the platform does and what the
+     * mute control here has always done directly.
+     */
+    get muted(): boolean;
+    set muted(quiet: boolean);
+    /** How loud it plays, 0 to 1. */
+    get volume(): number;
+    set volume(level: number);
+    private get video();
+    /**
+     * Starts playing, where the platform allows it.
+     *
+     * The rejection is swallowed on purpose: a browser refuses `play()` when
+     * nothing the reader did asked for it, and that is a policy answer rather than
+     * a fault. What follows a refused play is a paused player showing its start
+     * control, which is the correct thing to be looking at.
+     */
+    play(): void;
+    /** Stops, leaving the frame up. */
+    pause(): void;
+    /** Toggles playback, which is what every key and the button both come to. */
+    toggle(): void;
+    /** Moves to a point in seconds, clamped to what exists. */
+    seek(seconds: number): void;
+    /**
+     * The scrubber's new position, and the reason these two are named at all.
+     *
+     * **The stop is the first line.** `input` is composed by specification, so a
+     * range inside this shadow root sends its own straight past the host to
+     * whoever is listening on it, and this component declares no `input`: a
+     * consumer binding one received the scrubber's and the volume rail's under a
+     * name Video never promised, carrying a seconds count or a level between zero
+     * and one rather than anything about the element.
+     *
+     * Found by sweeping every family that renders a native control, which is what
+     * 308 said and not what it was read as: the first two passes both took "form
+     * control" as the population and a media component with two rails in its
+     * chrome is neither a form control nor exempt from the mechanism. See 308.
+     */
+    private takeScrub;
+    /** The volume rail's new level, stopped for the reason `takeScrub` carries. */
+    private takeVolume;
+    /**
+     * Rebuilds the copies from whatever the consumer has slotted.
+     *
+     * The attribute list is explicit rather than a blind copy of every attribute:
+     * these are two elements with a known and small surface, and copying anything
+     * a consumer happened to put on one would carry their framework's own markers
+     * into a shadow root that has no use for them.
+     */
+    private readonly handleMedia;
+    private readonly handleLoaded;
+    private readonly handleTime;
+    /**
+     * Relayed, because none of these cross a shadow boundary on their own.
+     *
+     * The video is inside this element's shadow root, so a consumer listening on
+     * the element they wrote hears nothing at all without this. Input relays
+     * `change` for the same reason.
+     */
+    private readonly handleWaiting;
+    private readonly handleReady;
+    private readonly handleError;
+    private readonly handleState;
+    /**
+     * Takes the page's media session, and tells the platform what is playing.
+     *
+     * On play rather than on render, which is the ownership rule: a page with two
+     * players gives the session to whichever one the reader started, so a
+     * headset's buttons land on what they are listening to rather than on
+     * whichever came first in the markup.
+     *
+     * The handlers are what make a headset's play, pause and skip work at all.
+     * Without them a platform falls back to guessing which element was meant,
+     * which is right often enough to hide the fault and wrong exactly when there
+     * are two.
+     */
+    private claimSession;
+    private readonly handleVolume;
+    /**
+     * Draws the active cue ourselves, so it can be put where we want it.
+     *
+     * The browser renders cues inside the video's own box and there is no
+     * standard way to inset that box: a caption lands under the control bar and
+     * stays there. `::cue` styles the text and not the region, and the property
+     * that moves the region is a `-webkit-` internal that two of the three
+     * engines do not have.
+     *
+     * So the track is set to `hidden` rather than `showing`, which is the mode
+     * that keeps the cues coming without drawing them, and what it reports is
+     * rendered into a part of our own. That also makes captions styleable, which
+     * `::cue` only half allows.
+     */
+    private readonly handleCue;
+    /**
+     * Moves by a fixed length, clamped by `seek`.
+     *
+     * Separate from the arrow keys, which move by 5 and by 10 with Shift. Those
+     * are a scrub; this is the gesture for "I missed that", and a reader who
+     * presses it twice expects twenty seconds rather than an accelerating jump.
+     */
+    private skipBy;
+    /**
+     * The tracks a reader could choose between, in the order they were written.
+     *
+     * Filtered by kind, because `textTracks` also carries `chapters`, `metadata`
+     * and `descriptions`, and a menu offering "Chapters" as a subtitle language
+     * would be offering something that draws no words. Read off the video rather
+     * than off the slot: a `<track>` added later is in one and not the other, and
+     * the video is the one that has resolved them.
+     */
+    private get captionTracks();
+    /**
+     * Shows one track and disables every other, or shows none at `-1`.
+     *
+     * Every other, rather than only the one that was on. Two tracks in `hidden`
+     * both fire `cuechange`, so the rendered cue becomes whichever fired last and
+     * a reader who switched language gets the two interleaved. Measured as two
+     * subtitles alternating line by line.
+     *
+     * `hidden`, never `showing`. Hidden is the mode where a track still fires
+     * `cuechange` and still fills `activeCues`, and the browser draws nothing,
+     * which is exactly what is wanted when something else is doing the drawing.
+     */
+    private showCaption;
+    /** Turns captions on or off, which is what the button means with one track. */
+    private toggleCaptions;
+    /**
+     * Says the reader asked for another item, and does nothing else.
+     *
+     * There is nothing else it could do. A `<video>` plays one resource, so what
+     * comes before or after it is a fact this element does not hold: a playlist
+     * has it, or the consumer does. Announcing is the whole of the contribution,
+     * and the event bubbles so a wrapper hears it.
+     *
+     * The same call answers the button, the row in the overflow menu, and the
+     * skip keys on a headset, which is why the media session's handlers point
+     * here rather than at anything of their own.
+     */
+    private skip;
+    /** Steps through the speeds offered, which is what one button can do. */
+    private cycleSpeed;
+    /**
+     * Starts watching for something to play this on, and stops on the way out.
+     *
+     * The Remote Playback API is the standard one, and it is what Safari
+     * implements for AirPlay and Chrome for Cast: one call covers both, where the
+     * older `webkitShowPlaybackTargetPicker` covers only the first. Firefox has
+     * neither, and `remote` simply being absent is what turns the control off
+     * there.
+     *
+     * `watchAvailability` returns an id that has to be canceled, or the callback
+     * outlives the element that owns it.
+     */
+    private watchRemote;
+    /** Opens the platform's own device picker. It has no list of its own. */
+    private promptRemote;
+    private togglePip;
+    /**
+     * Into fullscreen and back, and quiet about being refused.
+     *
+     * `requestFullscreen` rejects rather than returning false, and the two
+     * refusals a consumer will actually meet are a Permissions Policy that does
+     * not grant `fullscreen` to the frame the player is in, and a call without
+     * user activation. Both are `TypeError: Permissions check failed`, which is
+     * the same message for two different causes.
+     *
+     * It was `void`ed, so a refusal became an unhandled rejection: the button did
+     * nothing and said nothing, and the console entry it left named neither the
+     * element nor the reason. Caught here, the state stays honest because
+     * `aria-pressed` follows `fullscreenchange` rather than this call, so a
+     * refused request leaves a button that correctly reports "not fullscreen".
+     */
+    private toggleFullscreen;
+    /**
+     * Restarts the wait, on anything that counts as the reader being here.
+     *
+     * Pointer movement and focus both count, and both have to: a reader using the
+     * keyboard never moves a pointer, and a bar that only answered the mouse
+     * would leave them nothing to look at.
+     */
+    private readonly stir;
+    private readonly handleFullscreenChange;
+    /**
+     * The keys every player uses, bound to this element rather than the document.
+     *
+     * A video is not a command palette: its keys belong to it while a reader is
+     * on it, and a page with two videos on it would otherwise have both answering
+     * the same press.
+     *
+     * Nothing is taken while focus is in a range. The scrubber and the volume are
+     * real inputs and the arrows are already theirs, so intercepting would mean
+     * seeking twice for one press.
+     */
+    private readonly handleKeydown;
+    /** The track currently being listened to, so the next one can take it off. */
+    private cued;
+    private readonly handleRemoteState;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    /**
+     * Mirrors playback onto the host as `data-playing`.
+     *
+     * Because CSS cannot ask. `paused` is a property of a `<video>` and never an
+     * attribute, so `video:not([paused])` matches every video that has ever
+     * existed: the first version of the rule that hides the bar used exactly that
+     * and hid it always, including on a paused video, which is the one state it
+     * was written to keep it in.
+     *
+     * **A `data-` attribute is right here because of when it is written.** A fact
+     * that can be true on the first update mirrors to a custom state instead, or
+     * a consumer's server sends markup the element then grows an attribute on and
+     * React reports a mismatch it will not patch up. Nothing plays until somebody
+     * presses play, so this one is written long past hydration and there is
+     * nothing for it to disagree with. `data-closed` on `Toast.Item` and
+     * `data-closed` on `Toast.Item` is the same case; `:state(open)` and
+     * `:state(checked)` are the other one, and were `data-` attributes until
+     * 27 Aug 2026.
+     */
+    protected updated(changed: PropertyValues): void;
+    /**
+     * One named control, as a button on the bar.
+     *
+     * A method rather than four branches inlined, because the same four names are
+     * asked for twice now, once for the bar and once for the menu behind it, and
+     * two lists that have to stay in step is how a control ends up offered in one
+     * place and not the other.
+     */
+    protected renderExtra(one: string): TemplateResult;
+    /**
+     * A toggle for one track, a menu for several, and nothing for none.
+     *
+     * No menu at one, because a menu of a single language plus "Off" is a
+     * two-state control wearing a popover, and the button already says which
+     * state it is in through `aria-pressed`. The moment there are two the button
+     * cannot say which one is on, so it stops being a button.
+     *
+     * The label comes off the track: `label` where the markup gave one, and
+     * `srclang` where it did not, because a `<track>` with neither is a track
+     * nobody can choose between and that is the markup's fault to fix, not this
+     * component's to paper over with "Track 2".
+     */
+    protected renderCaptions(): TemplateResult | typeof nothing;
+    protected renderOverflowItem(one: string): TemplateResult;
+    protected renderBar(): TemplateResult;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-video': HelixHeadlessVideo;
+    }
+}