@braccato/core 0.1.6 → 1.0.0

package/dist/README.md

@@ -0,0 +1,298 @@
+# @braccato/core
+
+A custom element that renders synchronized lyrics and lights each syllable up as it is sung. No
+runtime dependencies, only a types-only one on `@braccato/types`. The lines go into light DOM rather
+than a shadow root, so the CSS already on your page reaches them.
+
+Extracted from the [Better Lyrics](https://better-lyrics.boidu.dev) rendering engine, which is still
+where it runs.
+
+## Install
+
+```bash
+npm i @braccato/core
+```
+
+## Usage
+
+```html
+<audio id="player" src="song.mp3" controls></audio>
+<braccato-lyrics source="#player"></braccato-lyrics>
+
+<script type="module">
+  import "@braccato/core/element";
+  import "@braccato/core/styles/variables.css";
+  import "@braccato/core/styles/lyrics.css";
+  import "@braccato/core/styles/instrumental.css";
+
+  document.querySelector("braccato-lyrics").lyrics = [
+    { startTimeMs: 0, durationMs: 4200, words: "The first line" },
+    { startTimeMs: 4200, durationMs: 3800, words: "The second" },
+  ];
+</script>
+```
+
+`source` takes a CSS selector or a media element. It is resolved when the element connects, so put
+the `<audio>` before the tag, or write the property from script. Without a source, drive the view
+yourself by writing `currentTime` and `playing`.
+
+Two things catch everybody once. The element has no `display` of its own:
+
+```css
+braccato-lyrics {
+  display: block;
+}
+```
+
+And autoscroll writes `scrollTop` on the nearest ancestor that scrolls, falling through to the
+document when nothing does. If the element is not inside its own scroller, say which one it is:
+
+```js
+view.host = { getScrollElement: () => yourFrame };
+```
+
+## Lyrics
+
+The array is the whole input, and nothing in this package produces one.
+[`@braccato/parsers`](https://www.npmjs.com/package/@braccato/parsers) reads TTML, LRC, SRT, QRC and
+plain text, and picks between them by looking at the file.
+
+```js
+import { detectParser } from "@braccato/parsers";
+
+const text = await fetch("song.ttml").then(response => response.text());
+view.lyrics = detectParser(text).parse(text, player.duration * 1000);
+```
+
+A `Lyric` is `{ startTimeMs, durationMs, words }`, with an optional `parts` array of the same three
+fields for syllable or word timing, and optional `translation`, `romanization` and
+`timedRomanization` beside them.
+
+## Properties
+
+Every one of these may be written before the element is in a document. The renderer is built when it
+connects, and everything it was handed by then is applied at once.
+
+| Property        | Attribute      | Type                                | Default  | Description                                                                                                                              |
+| --------------- | -------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `lyrics`        |                | `Lyric[] \| null`                   | `null`   | The song. Null means it was never given one, and an empty array clears the view, so there is a way to say both.                            |
+| `lyricsOptions` |                | `{ loaderVisible?, noLyrics? }`     | `{}`     | How the lines are built. `noLyrics` marks a message as a placeholder rather than a song, which keeps passive scrolling from drifting it.   |
+| `source`        | `source`       | `string \| HTMLMediaElement \| null` | `null`  | A selector or the media element itself. See Following a media element.                                                                     |
+| `mediaElement`  |                | `HTMLMediaElement \| null` (get)    | `null`   | What `source` resolved to. Null while disconnected, and null for a selector that missed.                                                   |
+| `currentTime`   | `current-time` | `number`                            | `0`      | Playback position in **seconds**. Writing it renders the view again, so whoever holds the clock drives the lyrics by writing this.        |
+| `playing`       | `playing`      | `boolean`                           | `false`  | A paused view animates differently from a playing one.                                                                                     |
+| `tickOptions`   |                | `ElementTickOptions`                | `{}`     | The rest of a tick: four offsets taken off the clock before it is matched, whether passive scrolling is on, and when the clock was sampled. |
+| `theme`         | `theme`        | `string`                            | `""`     | A compiled stylesheet. See Theming.                                                                                                        |
+| `host`          |                | `Partial<LyricsRendererHost>`       | `{}`     | Overrides for what the renderer asks of its surroundings. Every member has a default. Writing it while connected rebuilds the view.        |
+| `renderer`      |                | `LyricsRenderer \| null` (get)      | `null`   | The renderer underneath, for the day the tag runs out. A different one after every reconnection.                                            |
+| `status`        |                | `ElementStatus` (get)               | `"idle"` | `idle`, `rendering`, `theme-conflict` or `no-browsing-context`.                                                                            |
+
+`tickOptions` and `lyricsOptions` are stored on write and read by the next tick or the next build, so
+writing options and the clock on the same frame renders once.
+
+## Attributes
+
+An attribute writes its property, and a property never writes back. Reflecting `current-time` would
+put the playback clock into the DOM sixty times a second, and one attribute reflecting while the rest
+do not is worse than none of them doing it.
+
+| Attribute      | Writes        | Notes                                                                                              |
+| -------------- | ------------- | -------------------------------------------------------------------------------------------------- |
+| `source`       | `source`      | The selector form only. Another selector moves the binding, and removing it unbinds.                |
+| `theme`        | `theme`       | A whole stylesheet in an attribute value. It works, but nobody would ship a theme this way.          |
+| `current-time` | `currentTime` | Seconds. A value that does not parse as a number is ignored rather than read as zero.               |
+| `playing`      | `playing`     | An ordinary boolean attribute: its presence is what counts, so `playing="false"` is playing.         |
+
+## Events
+
+All four bubble and are composed, so an element you put inside your own shadow root still reaches
+your listener.
+
+| Event                    | Detail                    | When                                                                            |
+| ------------------------ | ------------------------- | --------------------------------------------------------------------------------- |
+| `braccato:lyrics-loaded` | `{ lineCount, syncType }` | Lyrics were applied, including an empty array. A theme change that rebuilds the lines reports itself the same way. |
+| `braccato:line-click`    | `{ timeS }`               | A line was clicked. The seek has already reached the bound media element by the time you hear about it.            |
+| `braccato:scroll-state`  | `{ userScrolling }`       | Autoscroll stopped following the song, or started again.                                                           |
+| `braccato:error`         | `{ phase, error }`        | Connecting, resolving a source, or applying lyrics or a theme went wrong. `phase` is `connect`, `conflict`, `source`, `lyrics` or `theme`. |
+
+Errors are dispatched a microtask after they happen rather than where they happen, which is what
+makes them receivable at all: `connectedCallback` runs before any listener a page could have added.
+A listener added later than that still misses them, so `status` answers the same question and needs
+no listener. Nothing thrown by a tick lands here, because sixty error events a second would bury the
+one that mattered.
+
+There is no `braccato:word-click`. The renderer tells its host `seek(timeS)` and nothing else, so the
+element cannot tell a word seek from a line seek without re-deriving the click branch off the DOM.
+The DOM is light and the class names are published, so listen for `click` on the element and read
+`.blyrics--word` yourself.
+
+## Theming
+
+A theme is a stylesheet. Write CSS against the class names below and the module stays out of it. What
+it does read is the `blyrics-*` lines inside the comments, which is how a theme changes behaviour
+without a second configuration format.
+
+```js
+view.theme = `
+  /* blyrics-target-scroll-pos-ratio = 0.5; */
+  /* blyrics-long-word-threshold = 900; */
+
+  .blyrics-container {
+    --blyrics-font-size: 3.5rem;
+    --blyrics-lyric-active-color: white;
+    --blyrics-lyric-inactive-color: rgb(255 255 255 / 0.25);
+  }
+`;
+```
+
+Settings are read from comments only. Everything else is CSS the browser is going to read, and a
+stylesheet must not be able to configure the module by accident. An empty theme puts every setting
+back to its default. The stylesheet itself goes into the document head under the
+`blyrics-custom-style` id.
+
+There is no `longWordThreshold`, `lineSyncedDelay` or `disableRichsync` property. Those are theme
+settings (`blyrics-long-word-threshold`, `blyrics-line-synced-animation-delay`,
+`blyrics-disable-richsync`), read from the stylesheet you already hand over. A theme that set one
+while a property said otherwise would leave the module with two answers and no rule for picking.
+
+`parseThemeConfig` is published on `@braccato/core/themeSettings` for reading the settings out of a
+stylesheet somewhere no renderer is running.
+
+### Custom properties
+
+The ones a theme reaches for first. `variables.css` declares the rest.
+
+```css
+.blyrics-container {
+  --blyrics-font-family: system-ui, sans-serif;
+  --blyrics-font-size: 3rem;
+  --blyrics-line-height: 1.333;
+  --blyrics-padding: 2rem;
+  --blyrics-lyric-active-color: white;
+  --blyrics-lyric-inactive-color: rgb(255 255 255 / 0.3);
+  --blyrics-glow-color: rgb(255 255 255 / 0.5);
+}
+```
+
+`--blyrics-font-size` is what everything else is sized off, including the instrumental dots.
+`--blyrics-padding` is the vertical room around each line, and the one to reach for before
+`line-height`. Every word is given the glow, so a theme that wants it to mean something selects on
+`data-long-word`, which the module sets on any part held past `blyrics-long-word-threshold`.
+
+### Class names
+
+These are published API rather than implementation. Renaming one costs a migration rather than a
+refactor. Import them from `@braccato/core/constants` instead of typing them out.
+
+| Constant                  | Class                       | What it is                                                |
+| ------------------------- | --------------------------- | ----------------------------------------------------------- |
+| `LYRICS_CLASS`            | `blyrics-container`         | The view. One per renderer.                                  |
+| `LINE_CLASS`              | `blyrics--line`             | One line, carrying its own `dir="auto"`.                     |
+| `CURRENT_LYRICS_CLASS`    | `blyrics--active`           | The line the song is on right now.                           |
+| `WORD_CLASS`              | `blyrics--word`             | One word, and the unit the sweep animates.                   |
+| `BACKGROUND_LYRIC_CLASS`  | `blyrics-background-lyric`  | A background vocal, sung over the line it answers.           |
+| `USER_SCROLLING_CLASS`    | `blyrics-user-scrolling`    | Set while a reader has scrolled away and autoscroll waits.   |
+| `TRANSLATED_LYRICS_CLASS` | `blyrics--translated`       | A translation hung off a line that was already built.        |
+| `CUSTOM_THEME_STYLE_ID`   | `blyrics-custom-style`      | The id of the `<style>` the theme lands in.                  |
+
+## Stylesheets
+
+Three sheets ship with the package, and loading them is yours, the way any package's CSS is. Leave
+them out and you get lines that are in the document and unstyled, rather than lines that are missing.
+
+| File                                     | What it carries                                                                                                        |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `@braccato/core/styles/variables.css`    | Every `--blyrics-*` default. It goes first, because the other two read from it.                                           |
+| `@braccato/core/styles/lyrics.css`       | The container, the lines, the words and the sweep, plus two `@property` registrations the word animation interpolates through. |
+| `@braccato/core/styles/instrumental.css` | The waveform that fills a bar nobody sings over, and the animation that walks it.                                          |
+
+One thing they do not do for you. The module measures the room the first and last lines need to reach
+the view's target scroll position and writes it on the root as `--blyrics-padding-top` and
+`--blyrics-padding-bottom`, but `lyrics.css` only spends the bottom one. Supply the top rule:
+
+```css
+.blyrics-container {
+  padding-top: var(--blyrics-padding-top, 2rem);
+}
+```
+
+## Light DOM, not shadow DOM
+
+The element builds into itself. That is what lets a stylesheet at document level select the lines,
+and what lets the package's own `@property` registrations apply to them, which they would not inside
+a shadow root. The theme is adopted into the element's document rather than encapsulated, and the
+package's stylesheets are yours to load for the same reason.
+
+## Entry points
+
+`@braccato/core` is the facade and registers nothing. `createLyricsRenderer(options)` returns one
+`LyricsRenderer`: give it lyrics, tick it, and it owns the DOM it builds and every re-measurement
+that DOM needs. `resetPlaybackClock`, `resumeAllAutoscroll`, `injectRomanization` and
+`injectTranslation` are published beside it, for what one instance cannot answer for on its own.
+
+`@braccato/core/element` registers `<braccato-lyrics>`, and `<better-lyrics>` beside it, on import.
+Registration is a side effect, which is why it is entered separately.
+
+Four leaves import nothing at all, so taking one does not pull the engine into your bundle with it:
+
+- `@braccato/core/constants` for the class names and element ids above
+- `@braccato/core/text` for script detection: `testRtl`, `containsNonLatin`, `detectNonLatinLanguage`
+- `@braccato/core/themeSettings` for `parseThemeConfig`
+- `@braccato/core/util` for pure helpers such as `clamp` and `toMs`
+
+Two notes on the element entry point. A browser extension's isolated world has no custom element
+registry, so `window.customElements` is null there and importing this file throws where it registers.
+An extension that wants the tag has to run in the page's own world; one that stays isolated calls
+`createLyricsRenderer` directly. And registration is silent about a name already taken, so two copies
+of this package on one page means the first to load takes both names and `instanceof` against the
+second copy's class is false for every element on the page. Load one copy.
+
+## Following a media element
+
+While a `source` is bound, the element drives itself. It reads `currentTime` and `paused` off the
+media element on a `requestAnimationFrame` loop that runs only while the song plays, and a click on a
+lyric line sets `currentTime` back on it. So `currentTime` and `playing` become outputs: a write to
+either is dropped and the getter keeps reporting what the binding last read. Dropped rather than
+reported, because a consumer who bound a source and left their own frame loop running would otherwise
+be told about it sixty times a second. Unbind and the clock goes back to whoever asked for it.
+
+A reading the media element has not refreshed yet is carried forward at the playback rate it was
+taken at, capped at 100ms of frame time. That cap is what covers a stall: the view runs at most 100ms
+past the last real reading and then waits with it. What it costs is a step backwards when the clock
+moves again, scaled by the rate. 100ms at 1x, 400ms at 4x.
+
+`play`, `pause`, `seeking`, `seeked` and `ratechange` are listened to. The frame loop covers the rest
+by asking the media element whether its clock is still going rather than trusting that something said
+so. One gap is worth knowing: `emptied` while already paused leaves no loop running to notice, so
+swapping `audio.src` between songs without playing goes on reporting the old position until the next
+`play`.
+
+## One renderer per document
+
+Two renderers in one document write over each other, so the module supports one. It is a constraint
+rather than a setting, and it is stated rather than enforced: none of the points where two of them
+collide is a crash.
+
+Two things are written per document and belong to whichever renderer wrote them last: the theme's
+`<style>` element, and the scroll padding on the root. Two more are per bundle, because a settings
+registry and the playback clock both live at module scope: one theme means one set of values for
+every view in that bundle, and whichever view ticked last is the one whose clock the others replay.
+
+None of that is a limit on how many elements you may have. Two views handed the **same** theme share
+only the settings both of them asked for, and the renderer adopts an existing theme element rather
+than adding a rival under the same id. The line is drawn at the disagreement: when an element applies
+a theme another element in its document was not given, both dispatch `braccato:error` with
+`phase: "conflict"` and both read `status === "theme-conflict"`. Neither stops rendering, because a
+blank view with a reason is worse than a themed one with a warning.
+
+## Docs and demo
+
+Full documentation is at [braccato.boidu.dev](https://braccato.boidu.dev).
+
+The demo page lives at [`demo/`](https://github.com/better-lyrics/braccato/tree/master/demo) in the
+repository and runs against the emitted package, with a control for most of what is above. Clone the
+repository and run `pnpm -C demo dev`, then open `http://localhost:5173/`.
+
+## Licence
+
+MIT. See `LICENSE`.

package/dist/constants.d.ts

@@ -0,0 +1,25 @@
+export declare const LYRICS_WRAPPER_ID: "blyrics-wrapper";
+export declare const LYRICS_CLASS: "blyrics-container";
+export declare const LINE_CLASS: "blyrics--line";
+export declare const WORD_CLASS: "blyrics--word";
+export declare const FOOTER_CLASS: "blyrics-footer";
+export declare const CURRENT_LYRICS_CLASS: "blyrics--active";
+export declare const ANIMATING_CLASS: "blyrics--animating";
+export declare const PAUSED_CLASS: "blyrics--paused";
+export declare const ZERO_DURATION_ANIMATION_CLASS: "blyrics-zero-dur-animate";
+export declare const USER_SCROLLING_CLASS: "blyrics-user-scrolling";
+export declare const BACKGROUND_LYRIC_CLASS: "blyrics-background-lyric";
+export declare const EXPLICIT_WORD_CLASS: "blyrics-explicit";
+export declare const RTL_CLASS: "blyrics-rtl";
+export declare const TRANSLATED_LYRICS_CLASS: "blyrics--translated";
+export declare const ROMANIZED_LYRICS_CLASS: "blyrics--romanized";
+export declare const CONTENT_LINE_CLASS: "blyrics-content-line";
+export declare const LINE_MAIN_CLASS: "blyrics-line-main";
+export declare const BACKGROUND_LINE_CLASS: "blyrics-background-line";
+export declare const WORD_GROUP_CLASS: "blyrics-word-group";
+export declare const LONG_WORD_GROUP_CLASS: "blyrics-word-group-long";
+export declare const WORD_HIGHLIGHT_CLASS: "blyrics-word-highlight";
+export declare const LINE_SYNCED_WORD_CLASS: "blyrics-line-synced-word";
+export declare const BIDI_RUN_CLASS: "blyrics-bidi-run";
+export declare const BIDI_SENSITIVE_CLASS: "blyrics-bidi-sensitive";
+export declare const CUSTOM_THEME_STYLE_ID: "blyrics-custom-style";

package/dist/constants.js

@@ -0,0 +1,42 @@
+// These names are a public contract: marketplace themes select on them and set properties through
+// them, so renaming one is a breaking change for every published theme, not a refactor.
+// -- Structure --------------------------------------------
+export const LYRICS_WRAPPER_ID = "blyrics-wrapper";
+export const LYRICS_CLASS = "blyrics-container";
+export const LINE_CLASS = "blyrics--line";
+export const WORD_CLASS = "blyrics--word";
+export const FOOTER_CLASS = "blyrics-footer";
+// -- Playback state --------------------------------------------
+export const CURRENT_LYRICS_CLASS = "blyrics--active";
+export const ANIMATING_CLASS = "blyrics--animating";
+export const PAUSED_CLASS = "blyrics--paused";
+export const ZERO_DURATION_ANIMATION_CLASS = "blyrics-zero-dur-animate";
+export const USER_SCROLLING_CLASS = "blyrics-user-scrolling";
+// -- Line and word variants --------------------------------------------
+export const BACKGROUND_LYRIC_CLASS = "blyrics-background-lyric";
+export const EXPLICIT_WORD_CLASS = "blyrics-explicit";
+export const RTL_CLASS = "blyrics-rtl";
+export const TRANSLATED_LYRICS_CLASS = "blyrics--translated";
+export const ROMANIZED_LYRICS_CLASS = "blyrics--romanized";
+// -- Line internals --------------------------------------------
+export const CONTENT_LINE_CLASS = "blyrics-content-line";
+export const LINE_MAIN_CLASS = "blyrics-line-main";
+export const BACKGROUND_LINE_CLASS = "blyrics-background-line";
+export const WORD_GROUP_CLASS = "blyrics-word-group";
+export const LONG_WORD_GROUP_CLASS = "blyrics-word-group-long";
+export const WORD_HIGHLIGHT_CLASS = "blyrics-word-highlight";
+export const LINE_SYNCED_WORD_CLASS = "blyrics-line-synced-word";
+export const BIDI_RUN_CLASS = "blyrics-bidi-run";
+export const BIDI_SENSITIVE_CLASS = "blyrics-bidi-sensitive";
+// -- Theme --------------------------------------------
+// The element a theme handed to `setTheme` is applied through, one per document a renderer builds
+// in. Named rather than anonymous because a consumer with a second document to style has to be able
+// to find the first one: this extension's floating window mirrors the side panel's by id.
+//
+// One renderer per document owns it. Two renderers in one document render against one theme
+// whatever they are given, because the settings registry is module scope, so this is a constraint
+// stated rather than a configuration supported. A renderer that finds the id already in its
+// document writes into that element rather than adding a rival, so the id stays unique and a
+// consumer reading it by id gets the sheet in force, and `destroy` takes the element away only if
+// this renderer is what put it there.
+export const CUSTOM_THEME_STYLE_ID = "blyrics-custom-style";

package/dist/element.d.ts

@@ -0,0 +1,155 @@
+import type { Lyric, LyricsRenderer, LyricsRendererHost, LyricSyncType, TickOptions } from "./types.js";
+import type { SetLyricsOptions } from "./view.js";
+/**
+ * What a tick carries beyond the clock. `isPlaying` is not among them: `playing` is the property
+ * that says so, and one question with two answers has no rule for choosing between them.
+ *
+ * @public
+ */
+export type ElementTickOptions = Omit<TickOptions, "isPlaying">;
+/**
+ * How the lines are built, beyond the lines themselves. The mount is not among them: the element is
+ * the mount.
+ *
+ * @public
+ */
+export type ElementLyricsOptions = Partial<SetLyricsOptions>;
+/** @public */
+export type ElementErrorPhase = "connect" | "conflict" | "lyrics" | "source" | "theme";
+/** @public */
+export interface ElementErrorDetail {
+    /** What the element was doing. Nothing thrown by a tick is reported here: see the README. */
+    phase: ElementErrorPhase;
+    error: Error;
+}
+/**
+ * What the element is doing, and why it is not doing what it was asked. Every `braccato:error` is
+ * dispatched a microtask after the fact so that a listener added straight after the element was
+ * inserted still hears it; this is the answer for a consumer that added one later than that, or
+ * never.
+ *
+ * @public
+ */
+export type ElementStatus = "idle" | "rendering" | "theme-conflict" | "no-browsing-context";
+/** @public */
+export interface LyricsLoadedDetail {
+    lineCount: number;
+    syncType: LyricSyncType;
+}
+/** @public */
+export interface LineClickDetail {
+    /** Where the click asked the player to go, in seconds. */
+    timeS: number;
+}
+/** @public */
+export interface ScrollStateDetail {
+    /** Whether the user has scrolled away, so autoscroll is waiting rather than following the song. */
+    userScrolling: boolean;
+}
+/**
+ * Mounts a lyrics view into itself. The renderer is built when the element is connected and
+ * destroyed when it is disconnected, so an element that is moved around the page rebuilds rather
+ * than going quiet, and every property may be written before either has happened.
+ *
+ * `dir` is not among the properties, and that is the point: `HTMLElement` already reflects it, the
+ * lines this module builds carry `dir="auto"` and resolve their own direction from their text, and a
+ * property here would be a second opinion about a question the platform has already answered.
+ */
+export declare class BraccatoLyricsElement extends HTMLElement {
+    #private;
+    static readonly observedAttributes: string[];
+    /**
+     * The song. An empty array clears the view, so a consumer between songs has a way to say so.
+     */
+    get lyrics(): Lyric[] | null;
+    set lyrics(lyrics: Lyric[] | null);
+    /**
+     * How the lines are built, beyond the lines themselves: whether a loader is still covering the
+     * view, and whether these lyrics are a "not found" placeholder rather than a song. The second one
+     * is what keeps passive scrolling off a one line message it would otherwise drift for the length
+     * of the song.
+     *
+     * Read by the next build rather than causing one, so a consumer writes it beside `lyrics` rather
+     * than instead of it, and writing both renders once.
+     */
+    get lyricsOptions(): ElementLyricsOptions;
+    set lyricsOptions(options: ElementLyricsOptions);
+    /**
+     * The media element the lyrics follow, as a CSS selector resolved in this element's own document
+     * or as the element itself. Setting it binds and null unbinds, and while it is bound the element
+     * reads the clock rather than being told it: `currentTime` and `playing` become what it reports.
+     *
+     * Bound only while connected, the way the renderer is built only while connected, and a selector
+     * is resolved again every time it is written and every time the element connects.
+     */
+    get source(): HTMLMediaElement | string | null;
+    set source(source: HTMLMediaElement | string | null);
+    /**
+     * The media element `source` resolved to. Null whenever nothing is being followed, which is the
+     * answer for a selector that matched nothing and for an element that is not connected.
+     */
+    get mediaElement(): HTMLMediaElement | null;
+    /**
+     * Playback position in seconds, not milliseconds: the module ticks in seconds, and converting here
+     * would leave the element and the renderer underneath it disagreeing about what a number means.
+     * Writing it renders the view again, so whoever owns the clock drives the lyrics by writing this.
+     *
+     * While a media element is bound it is the one that owns the clock, so a write is dropped and this
+     * keeps reporting what the binding last read. Dropped rather than reported: a consumer who left
+     * their own frame loop running would otherwise be told about it sixty times a second.
+     */
+    get currentTime(): number;
+    set currentTime(currentTimeS: number);
+    /** An output rather than an input while a media element is bound, exactly as `currentTime` is. */
+    get playing(): boolean;
+    set playing(playing: boolean);
+    /**
+     * The rest of a tick: the user offsets the clock is matched against, whether passive scrolling is
+     * switched on for unsynced lyrics, and the timestamp of the player snapshot the clock came from.
+     *
+     * That last one matters beyond this element. The playback clock the module compares a tick
+     * against is module scope, so an element sharing a realm with another view has to be given the
+     * same snapshot timestamps that view is, or every tick reads as a jump away from the other one.
+     *
+     * Read by the next tick rather than causing one, so a consumer that writes these and the clock on
+     * the same frame renders the view once rather than twice.
+     */
+    get tickOptions(): ElementTickOptions;
+    set tickOptions(options: ElementTickOptions);
+    /**
+     * A compiled stylesheet. Its `blyrics-*` comments configure the module and the sheet itself goes
+     * into this element's document. An empty one puts every setting back to its default, and is
+     * applied like any other: the settings are module scope, so an element that applied nothing would
+     * render against whatever the last theme in that bundle left behind. What that costs is that
+     * connecting an element nobody gave a theme empties the theme element already in its document.
+     */
+    get theme(): string;
+    set theme(css: string);
+    /**
+     * Overrides for anything the renderer asks of its surroundings. Every member has a default, so a
+     * consumer with nothing to say leaves this alone. Writing it while connected rebuilds the view:
+     * the renderer is handed its host once, when it is created.
+     */
+    get host(): Partial<LyricsRendererHost>;
+    set host(overrides: Partial<LyricsRendererHost>);
+    /**
+     * The renderer underneath, for a consumer who outgrows the element. Null while disconnected, and a
+     * different one after every reconnection.
+     */
+    get renderer(): LyricsRenderer | null;
+    /**
+     * What the element is doing, asked rather than listened for. `theme-conflict` is the one that says
+     * the view is on the screen but not necessarily the way it was asked for: the theme settings are
+     * module scope, so a document with two elements holding different themes renders both against
+     * whichever was applied last.
+     *
+     * A `source` that named nothing to follow is deliberately not one of these. The element is still
+     * rendering, and a status saying otherwise would trade one true answer for another. What a
+     * consumer who was not listening for the error reads instead is `mediaElement`, which is null
+     * while `source` still holds the selector it could not resolve.
+     */
+    get status(): ElementStatus;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}