homebridge-plugin-utils 2.0.0 → 2.1.0

package/dist/docChrome.js

@@ -0,0 +1,361 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * docChrome.ts: Pure, isomorphic renderers that project a per-plugin documentation-chrome manifest into the masthead, navigation index, dashboard badges, and project
+ * list that every family plugin repeats by hand across its README, its docs, and its webUI.
+ */
+/**
+ * The opening marker of the auto-generated masthead region. See {@link renderMasthead}. The text doubles as an in-document warning not to edit the region by hand.
+ *
+ * @category Doc Chrome
+ */
+export const MASTHEAD_BEGIN = "<!-- MASTHEAD:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
+/**
+ * The closing marker of the auto-generated masthead region. See {@link MASTHEAD_BEGIN}.
+ *
+ * @category Doc Chrome
+ */
+export const MASTHEAD_END = "<!-- MASTHEAD:END -->";
+/**
+ * The opening marker of the auto-generated documentation-index region, used in the README's documentation section, each content doc's footer, and the webUI's Support
+ * tab. See {@link renderDocIndex}.
+ *
+ * @category Doc Chrome
+ */
+export const DOCUMENTATION_BEGIN = "<!-- DOCUMENTATION:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
+/**
+ * The closing marker of the auto-generated documentation-index region. See {@link DOCUMENTATION_BEGIN}.
+ *
+ * @category Doc Chrome
+ */
+export const DOCUMENTATION_END = "<!-- DOCUMENTATION:END -->";
+/**
+ * The opening marker of the auto-generated development-dashboard badge region (README only). See {@link renderDevBadges}.
+ *
+ * @category Doc Chrome
+ */
+export const DEV_BADGES_BEGIN = "<!-- DEV BADGES:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
+/**
+ * The closing marker of the auto-generated development-dashboard badge region. See {@link DEV_BADGES_BEGIN}.
+ *
+ * @category Doc Chrome
+ */
+export const DEV_BADGES_END = "<!-- DEV BADGES:END -->";
+/**
+ * The opening marker of the auto-generated project-list region (webUI only). See {@link renderProjects}.
+ *
+ * @category Doc Chrome
+ */
+export const PROJECTS_BEGIN = "<!-- PROJECTS:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
+/**
+ * The closing marker of the auto-generated project-list region. See {@link PROJECTS_BEGIN}.
+ *
+ * @category Doc Chrome
+ */
+export const PROJECTS_END = "<!-- PROJECTS:END -->";
+// Escape text destined for an HTML text node. We neutralize "&", "<", and ">" so a blurb containing any of them renders as literal text rather than being parsed as
+// markup. "&" is replaced first so the entities we introduce are not themselves re-escaped. This applies only to the webUI (HTML) surface; the markdown surfaces embed
+// author-owned prose verbatim, matching the hand-authored source the renderer reproduces.
+function escapeHtmlText(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+// Escape a value destined for a double-quoted HTML attribute (an href). It builds on the text-node escaping - the shared single source of truth for the "&"/"<"/">"
+// entities - and adds the double quote that would otherwise terminate the attribute early. The quote substitution runs after the text escaping, so the "&" it introduces
+// is not itself re-escaped.
+function escapeHtmlAttr(value) {
+    return escapeHtmlText(value).replaceAll("\"", "&quot;");
+}
+// The absolute GitHub blob base for a repository, the prefix every non-local navigation href is built on.
+function blobBaseUrl(repo) {
+    return "https://github.com/" + repo.owner + "/" + repo.name + "/blob/" + repo.branch;
+}
+// Render a single badge as a linked markdown image, the shape both the masthead and the dashboard badges share.
+function renderBadge(badge) {
+    return "[![" + badge.alt + "](" + badge.image + ")](" + badge.link + ")";
+}
+// Derive the href for a documentation entry on a given surface. On the README itself a `readme-anchor` entry is an in-page anchor; viewed from anywhere else it must
+// resolve to the README's absolute blob URL. A `doc` entry is always an absolute blob URL to its file, identical on every surface - which is what collapses the
+// per-surface href drift the hand-maintained lists suffer from.
+function docEntryHref(entry, repo, local) {
+    if (entry.kind === "readme-anchor") {
+        return local ? ("#" + entry.anchor) : (blobBaseUrl(repo) + "/README.md#" + entry.anchor);
+    }
+    return blobBaseUrl(repo) + "/" + entry.file;
+}
+/**
+ * Render the masthead - the centered logo, the H1 title, the ordered badge row, and the H2 tagline - as the markdown/HTML block a plugin embeds at the top of its README
+ * and every content doc. The block is identical across those surfaces, so a single manifest drives all of them and the hand-copied mastheads collapse to one.
+ *
+ * @param manifest - The documentation-chrome manifest.
+ *
+ * @returns The rendered masthead block.
+ *
+ * @category Doc Chrome
+ */
+export function renderMasthead(manifest) {
+    const { badges, logo, tagline, title } = manifest.masthead;
+    // Assemble the block line by line: the centering wrapper, the linked logo image, the title, one linked badge image per badge, and the tagline. A pushed empty string
+    // is a blank line, keeping the vertical rhythm explicit rather than threading "\n\n" through concatenations.
+    const lines = [
+        "<SPAN ALIGN=\"CENTER\" STYLE=\"text-align:center\">",
+        "<DIV ALIGN=\"CENTER\" STYLE=\"text-align:center\">",
+        "",
+        "[![" + logo.alt + "](" + logo.src + ")](" + logo.href + ")",
+        "",
+        "# " + title,
+        "",
+        ...badges.map(renderBadge),
+        "",
+        "## " + tagline,
+        "</DIV>",
+        "</SPAN>"
+    ];
+    return lines.join("\n");
+}
+/**
+ * Render the development-dashboard badges - the README-only badge row (license, build status, dependencies, and the like) that sits apart from the masthead. Returns an
+ * empty string when the manifest declares no dashboard badges.
+ *
+ * @param manifest - The documentation-chrome manifest.
+ *
+ * @returns The rendered badge rows, one badge per line.
+ *
+ * @category Doc Chrome
+ */
+export function renderDevBadges(manifest) {
+    return (manifest.devBadges ?? []).map(renderBadge).join("\n");
+}
+/**
+ * Render the documentation index for a surface. On the markdown surfaces (`"readme"`, `"doc-footer"`) the output is one bullet per section with a nested bullet per
+ * entry; on `"webui"` it is one `<h5>` heading and `<ul>` per section. Href derivation follows the surface: in-README anchors on `"readme"`, absolute blob URLs
+ * elsewhere. A `"doc-footer"` render omits the current document (via `currentFile`) and drops any section left empty by that omission, so a doc's own footer never links
+ * back to itself.
+ *
+ * @param input
+ * @param input.currentFile - The doc file being rendered into, relative to the plugin root. Only consulted for the `"doc-footer"` surface, to omit the self-link.
+ * @param input.manifest    - The documentation-chrome manifest.
+ * @param input.surface     - The surface to render for.
+ *
+ * @returns The rendered documentation index.
+ *
+ * @category Doc Chrome
+ */
+export function renderDocIndex({ currentFile, manifest, surface }) {
+    if (surface === "webui") {
+        // The webUI surface renders HTML and never omits a self-link (it is not itself a doc). Each entry links to an absolute blob URL.
+        const sections = manifest.nav.map((section) => {
+            const items = section.entries.map((entry) => {
+                return "  <li><a target=\"_blank\" href=\"" + escapeHtmlAttr(docEntryHref(entry, manifest.repo, false)) + "\">" + escapeHtmlText(entry.title) + "</a>: " +
+                    escapeHtmlText(entry.blurb) + "</li>";
+            });
+            return "<h5>" + escapeHtmlText(section.title) + "</h5>\n<ul dir=\"auto\">\n" + items.join("\n") + "\n</ul>";
+        });
+        return sections.join("\n\n");
+    }
+    // The markdown surfaces. `"readme"` uses in-page anchors for anchor entries; `"doc-footer"` uses absolute URLs and omits the current doc.
+    const local = surface === "readme";
+    const omitFile = (surface === "doc-footer") ? currentFile : undefined;
+    const sections = [];
+    for (const section of manifest.nav) {
+        const bullets = section.entries
+            .filter((entry) => !((entry.kind === "doc") && (entry.file === omitFile)))
+            .map((entry) => "  * [" + entry.title + "](" + docEntryHref(entry, manifest.repo, local) + "): " + entry.blurb);
+        // Drop a section that the self-omission emptied, so a footer never renders a heading with no entries beneath it.
+        if (bullets.length === 0) {
+            continue;
+        }
+        sections.push(["* " + section.title, ...bullets].join("\n"));
+    }
+    return sections.join("\n\n");
+}
+/**
+ * Render the webUI project list - the "other projects" links - as an HTML `<ul>`. The CLI resolves the manifest's project source (inline, local file, or remote URL) to
+ * this array before calling; the renderer never performs I/O. Entries are rendered in alphabetical order by title, so the list reads predictably no matter what order the
+ * source - often a shared, remotely-fetched file every plugin points at - happens to hold. Each entry's link text is `{title}: {blurb}`.
+ *
+ * @param projects - The resolved project entries. Their order is not significant; the renderer sorts them by title.
+ *
+ * @returns The rendered project list.
+ *
+ * @category Doc Chrome
+ */
+export function renderProjects(projects) {
+    // Sort a copy by lowercased title so the output is alphabetical and consistent regardless of the source order, without disturbing the caller's array. We compare
+    // lowercased titles directly rather than through localeCompare so the ordering is identical on every build machine, independent of the host's locale.
+    const ordered = projects.toSorted((left, right) => {
+        const leftTitle = left.title.toLowerCase();
+        const rightTitle = right.title.toLowerCase();
+        if (leftTitle < rightTitle) {
+            return -1;
+        }
+        if (leftTitle > rightTitle) {
+            return 1;
+        }
+        return 0;
+    });
+    const items = ordered.map((project) => {
+        return "  <li><a target=\"_blank\" href=\"" + escapeHtmlAttr(project.href) + "\">" + escapeHtmlText(project.title) + ": " +
+            escapeHtmlText(project.blurb) + "</a></li>";
+    });
+    return "<ul dir=\"auto\">\n" + items.join("\n") + "\n</ul>";
+}
+// Throw a uniformly framed validation error naming the manifest source and the offending path, mirroring the diagnostics the catalog validation in the CLI produces.
+function fail(source, detail) {
+    throw new Error("Doc-chrome manifest " + source + " " + detail + ".");
+}
+// Assert that a value is a non-empty string at a named path, else fail with a framed diagnostic.
+function assertString(value, path, source) {
+    if ((typeof value !== "string") || (value.length === 0)) {
+        fail(source, "field `" + path + "` must be a non-empty string");
+    }
+}
+// Validate a badge's shape. Shared by the masthead badges and the optional dashboard badges.
+function assertBadge(value, path, source) {
+    if ((typeof value !== "object") || (value === null)) {
+        fail(source, "field `" + path + "` must be an object");
+    }
+    const badge = value;
+    assertString(badge.alt, path + ".alt", source);
+    assertString(badge.image, path + ".image", source);
+    assertString(badge.link, path + ".link", source);
+}
+// Validate one documentation entry. The `kind` tag selects which additional field is required.
+function assertDocEntry(value, path, source) {
+    if ((typeof value !== "object") || (value === null)) {
+        fail(source, "field `" + path + "` must be an object");
+    }
+    const entry = value;
+    assertString(entry.title, path + ".title", source);
+    assertString(entry.blurb, path + ".blurb", source);
+    switch (entry.kind) {
+        case "doc": {
+            assertString(entry.file, path + ".file", source);
+            if ((entry.masthead !== undefined) && (typeof entry.masthead !== "boolean")) {
+                fail(source, "field `" + path + ".masthead` must be a boolean when present");
+            }
+            return;
+        }
+        case "readme-anchor": {
+            assertString(entry.anchor, path + ".anchor", source);
+            return;
+        }
+        default: {
+            fail(source, "field `" + path + ".kind` must be \"doc\" or \"readme-anchor\"");
+        }
+    }
+}
+/**
+ * Validate a loaded value and return it typed as a well-formed {@link DocChromeManifest}, failing fast with a framed diagnostic that names the manifest source and the
+ * offending field rather than surfacing an opaque error deep inside a renderer or a bare `resolve()` type error in the CLI. Validates every field the renderer or the
+ * CLI consumes - `masthead`, `nav`, `repo`, and the optional `devBadges` and `surfaces`. The project source is validated separately at resolution time, since it may be
+ * a remote reference rather than inline data.
+ *
+ * @param value  - The loaded manifest value, untrusted until validated.
+ * @param source - The manifest's path or module specifier, for diagnostics.
+ *
+ * @returns The same value, now typed as a validated {@link DocChromeManifest}.
+ *
+ * @category Doc Chrome
+ */
+export function parseDocChromeManifest(value, source) {
+    if ((typeof value !== "object") || (value === null)) {
+        fail(source, "must export a manifest object");
+    }
+    const manifest = value;
+    // The masthead and its nested logo and badge row.
+    if ((typeof manifest.masthead !== "object") || (manifest.masthead === null)) {
+        fail(source, "field `masthead` must be an object");
+    }
+    const masthead = manifest.masthead;
+    assertString(masthead.title, "masthead.title", source);
+    assertString(masthead.tagline, "masthead.tagline", source);
+    if ((typeof masthead.logo !== "object") || (masthead.logo === null)) {
+        fail(source, "field `masthead.logo` must be an object");
+    }
+    const logo = masthead.logo;
+    assertString(logo.alt, "masthead.logo.alt", source);
+    assertString(logo.href, "masthead.logo.href", source);
+    assertString(logo.src, "masthead.logo.src", source);
+    if (!Array.isArray(masthead.badges)) {
+        fail(source, "field `masthead.badges` must be an array");
+    }
+    for (const [index, badge] of masthead.badges.entries()) {
+        assertBadge(badge, "masthead.badges[" + String(index) + "]", source);
+    }
+    // The repository coordinates.
+    if ((typeof manifest.repo !== "object") || (manifest.repo === null)) {
+        fail(source, "field `repo` must be an object");
+    }
+    const repo = manifest.repo;
+    assertString(repo.branch, "repo.branch", source);
+    assertString(repo.name, "repo.name", source);
+    assertString(repo.owner, "repo.owner", source);
+    // The navigation sections and their entries.
+    if (!Array.isArray(manifest.nav)) {
+        fail(source, "field `nav` must be an array");
+    }
+    for (const [sectionIndex, section] of manifest.nav.entries()) {
+        if ((typeof section !== "object") || (section === null)) {
+            fail(source, "field `nav[" + String(sectionIndex) + "]` must be an object");
+        }
+        const navSection = section;
+        assertString(navSection.title, "nav[" + String(sectionIndex) + "].title", source);
+        if (!Array.isArray(navSection.entries)) {
+            fail(source, "field `nav[" + String(sectionIndex) + "].entries` must be an array");
+        }
+        for (const [entryIndex, entry] of navSection.entries.entries()) {
+            assertDocEntry(entry, "nav[" + String(sectionIndex) + "].entries[" + String(entryIndex) + "]", source);
+        }
+    }
+    // The optional dashboard badges.
+    if (manifest.devBadges !== undefined) {
+        if (!Array.isArray(manifest.devBadges)) {
+            fail(source, "field `devBadges` must be an array when present");
+        }
+        for (const [index, badge] of manifest.devBadges.entries()) {
+            assertBadge(badge, "devBadges[" + String(index) + "]", source);
+        }
+    }
+    // The optional per-surface path overrides. These are consumed by the CLI's `resolve()` calls, so validating them here keeps the framed-diagnostic guarantee whole for
+    // a JSON-authored manifest that could otherwise smuggle a non-string path past the type system.
+    if (manifest.surfaces !== undefined) {
+        if ((typeof manifest.surfaces !== "object") || (manifest.surfaces === null)) {
+            fail(source, "field `surfaces` must be an object when present");
+        }
+        const surfaces = manifest.surfaces;
+        if ((surfaces.readme !== undefined) && ((typeof surfaces.readme !== "string") || (surfaces.readme.length === 0))) {
+            fail(source, "field `surfaces.readme` must be a non-empty string when present");
+        }
+        if ((surfaces.webui !== undefined) && ((typeof surfaces.webui !== "string") || (surfaces.webui.length === 0))) {
+            fail(source, "field `surfaces.webui` must be a non-empty string when present");
+        }
+    }
+    return value;
+}
+/**
+ * Validate a resolved project source and return it typed as an array of {@link ProjectEntry}. The CLI calls this after resolving the manifest's project source - which
+ * may be inline data, a local file, or a remote URL - so a malformed external list fails fast with a framed diagnostic naming the source rather than rendering broken
+ * markup.
+ *
+ * @param value  - The resolved project value, untrusted until validated.
+ * @param source - The project source (a path or URL) for diagnostics.
+ *
+ * @returns The same value, now typed as a validated array of {@link ProjectEntry}.
+ *
+ * @category Doc Chrome
+ */
+export function parseProjectEntries(value, source) {
+    if (!Array.isArray(value)) {
+        fail(source, "project source must resolve to an array of project entries");
+    }
+    for (const [index, entry] of value.entries()) {
+        if ((typeof entry !== "object") || (entry === null)) {
+            fail(source, "project entry [" + String(index) + "] must be an object");
+        }
+        const project = entry;
+        assertString(project.blurb, "project entry [" + String(index) + "].blurb", source);
+        assertString(project.href, "project entry [" + String(index) + "].href", source);
+        assertString(project.title, "project entry [" + String(index) + "].title", source);
+    }
+    return value;
+}
+//# sourceMappingURL=docChrome.js.map

package/dist/docChrome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docChrome.js","sourceRoot":"","sources":["../src/docChrome.ts"],"names":[],"mappings":"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"}

package/dist/featureOptions-docs.d.ts

@@ -3,7 +3,7 @@
  *
  * Every plugin in the family used to ship a near-duplicate `*-gendocs.ts` script that walked its feature-options catalog and printed a markdown category index plus
  * per-category option tables, then pasted the result into its `docs/FeatureOptions.md` by hand. ~95% of each script was identical, and each hand-rolled the dotted-key
- * construction and the value-vs-toggle discrimination that this library already owns as single-source-of-truth helpers. This module collapses all of that into one
+ * construction and the value-vs-toggle distinction that this library already owns as single-source-of-truth helpers. This module collapses all of that into one
  * elegant renderer so the documentation becomes a pure projection of the live catalog.
  *
  * The module exports two pure string functions:
@@ -75,7 +75,7 @@ export declare function renderFeatureOptionsReference<TOptionMeta = unknown, TCa
  * `writeFile` around it.
  *
  * The replacement inserts a newline before and after `content`, so a marker pair on its own lines stays on its own lines and the rendered fragment is cleanly framed.
- * The operation is idempotent: splicing the same `content` into an already-spliced document reproduces it byte-for-byte. Each marker may be overridden through the
+ * The operation is repeatable: splicing the same `content` into an already-spliced document reproduces it byte-for-byte. Each marker may be overridden through the
  * options object for documents that use a different convention, though the defaults match what every plugin in the family embeds.
  *
  * @param source            - The full document text.

package/dist/featureOptions-docs.js

@@ -149,7 +149,7 @@ export function renderFeatureOptionsReference(input) {
  * `writeFile` around it.
  *
  * The replacement inserts a newline before and after `content`, so a marker pair on its own lines stays on its own lines and the rendered fragment is cleanly framed.
- * The operation is idempotent: splicing the same `content` into an already-spliced document reproduces it byte-for-byte. Each marker may be overridden through the
+ * The operation is repeatable: splicing the same `content` into an already-spliced document reproduces it byte-for-byte. Each marker may be overridden through the
  * options object for documents that use a different convention, though the defaults match what every plugin in the family embeds.
  *
  * @param source            - The full document text.

package/dist/featureOptions.d.ts

@@ -26,7 +26,7 @@ import type { HomebridgePluginLogging, Nullable } from "./util.ts";
  * available for bespoke needs that the registry does not cover.
  *
  * The set targets the unit categories that recur across plugin catalogs: bitrate (in either of the two common storage conventions), data size, percentages, and
- * durations. Extend the union when a new shared format becomes load-bearing across multiple plugins. Resist adding a formatter speculatively - the function escape
+ * durations. Extend the union when a new format is genuinely shared across multiple plugins. Resist adding a formatter speculatively - the function escape
  * hatch already covers one-off needs, and an unused formatter is dead surface that downstream plugins still see in their IDE autocomplete.
  *
  * @category Feature Options
@@ -43,7 +43,7 @@ export type FeatureOptionFormatter = "bps" | "bytes" | "kbps" | "ms" | "percent"
  * @property meta            - Optional. An opaque, plugin-private annotation channel the core never interprets. HBPU's types deliberately cannot see inside `TMeta`;
  *                             the value is carried verbatim through the catalog and forwarded to the documentation renderer's closures (the only surface that knows its
  *                             concrete shape). This mirrors the OpenAPI `x-*` extension discipline, made type-safe: a plugin parameterizes the entry with its own
- *                             annotation type, the core treats it as `unknown`, and the round-trip stays structurally invariant rather than a naming convention.
+ *                             annotation type, the core treats it as `unknown`, and the round-trip stays structurally unchanged rather than a naming convention.
  * @property name            - Name of the feature option (used in option strings).
  * @property render          - Optional. Maps the raw stored value of a value-centric option to a display string. Either a {@link FeatureOptionFormatter} string naming
  *                             a built-in formatter (preferred when the format already exists in the registry, since this keeps the enclosing catalog JSON-serializable
@@ -105,7 +105,7 @@ export interface ResolvedOptionEntry {
  * Immutable derived index over the catalog inputs ({@link FeatureCategoryEntry}[] + the options map). Every field except `categories` / `options` is derived from
  * those two; the index bundles them with their derivations so a single value carries everything any caller needs to make catalog-level decisions in O(1).
  *
- * The index is built once per catalog at {@link buildCatalogIndex}; it is invariant across configured-options mutations, so a consumer that holds a stable
+ * The index is built once per catalog at {@link buildCatalogIndex}; it is unchanged across configured-options mutations, so a consumer that holds a stable
  * reference can rely on its query results until the catalog itself changes. The {@link FeatureOptions} class holds one internally; consumers driving reducers
  * directly hold it as state and reuse it across every dispatch that does not touch the catalog.
  *
@@ -188,7 +188,7 @@ export declare function expandOption(category: FeatureCategoryEntry | string, op
  * name on a `render` declaration does not resolve, surfacing the misconfiguration at load time rather than silently degrading the log-emission path.
  *
  * The index is the catalog-side input to every other pure helper in this module. Build it once per catalog; reuse it across every configured-options mutation
- * because the catalog is invariant across those mutations. Categories without an entry in the options map are skipped silently (a plugin defines a category for
+ * because the catalog is unchanged across those mutations. Categories without an entry in the options map are skipped silently (a plugin defines a category for
  * future expansion before any option has migrated into it).
  *
  * @param categories - The raw category list.
@@ -557,7 +557,7 @@ export declare class FeatureOptions {
      *
      * Callers express intent ("forget any configuration for option X at scope Y") and the model owns the entry-format end-to-end. The match is value-aware: for
      * value-centric options it covers both the bare scoped entry and any entry carrying a single trailing value segment, so a subsequent {@link setOption} cleanly
-     * replaces whatever was there. No-op when no entry addresses the target scope, so callers can treat this as an idempotent reset.
+     * replaces whatever was there. No-op when no entry addresses the target scope, so callers can treat this as a repeatable reset.
      *
      * @param args - The addressing intent: option key and optional scope id. See {@link ClearOptionArgs}.
      *

package/dist/featureOptions.js

@@ -136,7 +136,7 @@ function entryAddressesScope({ catalog, rawEntry, target }) {
  * name on a `render` declaration does not resolve, surfacing the misconfiguration at load time rather than silently degrading the log-emission path.
  *
  * The index is the catalog-side input to every other pure helper in this module. Build it once per catalog; reuse it across every configured-options mutation
- * because the catalog is invariant across those mutations. Categories without an entry in the options map are skipped silently (a plugin defines a category for
+ * because the catalog is unchanged across those mutations. Categories without an entry in the options map are skipped silently (a plugin defines a category for
  * future expansion before any option has migrated into it).
  *
  * @param categories - The raw category list.
@@ -681,7 +681,7 @@ export class FeatureOptions {
      *
      * Callers express intent ("forget any configuration for option X at scope Y") and the model owns the entry-format end-to-end. The match is value-aware: for
      * value-centric options it covers both the bare scoped entry and any entry carrying a single trailing value segment, so a subsequent {@link setOption} cleanly
-     * replaces whatever was there. No-op when no entry addresses the target scope, so callers can treat this as an idempotent reset.
+     * replaces whatever was there. No-op when no entry addresses the target scope, so callers can treat this as a repeatable reset.
      *
      * @param args - The addressing intent: option key and optional scope id. See {@link ClearOptionArgs}.
      *
@@ -700,7 +700,7 @@ export class FeatureOptions {
             return;
         }
         this.#configuredOptions = next;
-        // Only the index depends on the configured-options array; the catalog-derived state is invariant across config mutations and need not be touched here.
+        // Only the index depends on the configured-options array; the catalog-derived state is unchanged across config mutations and need not be touched here.
         this.#configIndex = buildConfigIndex(this.#catalog, this.#configuredOptions);
     }
     /**
@@ -725,7 +725,7 @@ export class FeatureOptions {
      */
     setOption(args) {
         this.#configuredOptions = applySetOption({ args, catalog: this.#catalog, configuredOptions: this.#configuredOptions });
-        // Only the index depends on the configured-options array; the catalog-derived state is invariant across config mutations and need not be touched here.
+        // Only the index depends on the configured-options array; the catalog-derived state is unchanged across config mutations and need not be touched here.
         this.#configIndex = buildConfigIndex(this.#catalog, this.#configuredOptions);
     }
     /**
@@ -791,7 +791,7 @@ export class FeatureOptions {
      * @returns Returns the current list of available feature option categories.
      */
     get categories() {
-        // The catalog stores the categories as readonly to encode the immutability invariant the pure functional core relies on. The public getter returns the
+        // The catalog stores the categories as readonly to encode the immutability guarantee the pure functional core relies on. The public getter returns the
         // historical mutable type for backward compatibility - the array is the same identity the caller passed at construction (or via the setter), so consumers
         // mutating it would be mutating the catalog regardless of the return type. The readonly annotation is the discipline, not a runtime enforcement.
         return this.#catalog.categories;
@@ -823,7 +823,7 @@ export class FeatureOptions {
      */
     set configuredOptions(options) {
         this.#configuredOptions = options ?? [];
-        // The catalog-derived state is invariant across config mutations; only the lookup index needs rebuilding.
+        // The catalog-derived state is unchanged across config mutations; only the lookup index needs rebuilding.
         this.#configIndex = buildConfigIndex(this.#catalog, this.#configuredOptions);
     }
     /**

package/dist/ffmpeg/exec.d.ts

@@ -98,7 +98,7 @@ export declare class FfmpegExec extends FfmpegProcess {
      * path does not normally produce a stream error, so an aborted run yields whatever bytes happened to arrive before the kill landed - which may be all of them, some
      * of them, or none of them.
      *
-     * This promise is the data channel only. To discriminate "the child wrote nothing" from "the run was aborted before the child could write anything," consult
+     * This promise is the data channel only. To distinguish "the child wrote nothing" from "the run was aborted before the child could write anything," consult
      * {@link FfmpegExec.exited} (`exitCode` / `exitSignal`) and {@link FfmpegProcess.signal} (`signal.reason`). Those are the single source of truth for process
      * disposition; an empty buffer carries no disposition meaning on its own.
      */
@@ -117,7 +117,7 @@ export declare class FfmpegExec extends FfmpegProcess {
      * Await the process to completion and return the bundled result.
      *
      * Resolves once both the stdout collector and the base class's `exited` promise settle. Rejects with the same reason `exited` would reject with (today, only when
-     * the child never spawned - e.g., ENOENT). On any normal exit, including non-zero exit codes, this method resolves; callers discriminate outcomes by inspecting
+     * the child never spawned - e.g., ENOENT). On any normal exit, including non-zero exit codes, this method resolves; callers distinguish outcomes by inspecting
      * `exitCode` and `exitSignal` in the result, or the derived `hasError` getter on the instance.
      *
      * @returns A promise resolving to an {@link ExecResult} bundling stdout, exit code, exit signal, and the accumulated stderr log.

package/dist/ffmpeg/exec.js

@@ -47,7 +47,7 @@ export class FfmpegExec extends FfmpegProcess {
      * path does not normally produce a stream error, so an aborted run yields whatever bytes happened to arrive before the kill landed - which may be all of them, some
      * of them, or none of them.
      *
-     * This promise is the data channel only. To discriminate "the child wrote nothing" from "the run was aborted before the child could write anything," consult
+     * This promise is the data channel only. To distinguish "the child wrote nothing" from "the run was aborted before the child could write anything," consult
      * {@link FfmpegExec.exited} (`exitCode` / `exitSignal`) and {@link FfmpegProcess.signal} (`signal.reason`). Those are the single source of truth for process
      * disposition; an empty buffer carries no disposition meaning on its own.
      */
@@ -88,7 +88,7 @@ export class FfmpegExec extends FfmpegProcess {
      * Await the process to completion and return the bundled result.
      *
      * Resolves once both the stdout collector and the base class's `exited` promise settle. Rejects with the same reason `exited` would reject with (today, only when
-     * the child never spawned - e.g., ENOENT). On any normal exit, including non-zero exit codes, this method resolves; callers discriminate outcomes by inspecting
+     * the child never spawned - e.g., ENOENT). On any normal exit, including non-zero exit codes, this method resolves; callers distinguish outcomes by inspecting
      * `exitCode` and `exitSignal` in the result, or the derived `hasError` getter on the instance.
      *
      * @returns A promise resolving to an {@link ExecResult} bundling stdout, exit code, exit signal, and the accumulated stderr log.

package/dist/ffmpeg/mp4-assembler.d.ts

@@ -14,6 +14,28 @@ export interface Mp4SegmentAssemblerInit {
     segmentTimeout?: number;
     signal?: AbortSignal;
 }
+/**
+ * The kind of a segment yielded by {@link Mp4SegmentAssembler.stream}. `"init"` is the one-shot initialization segment; `"media"` is a continuous media fragment. A
+ * consumer that paces or forwards every item uniformly can read {@link Mp4Segment.bytes} without branching; a consumer that must treat the init segment specially
+ * branches on this field.
+ *
+ * @category FFmpeg
+ */
+export type Mp4SegmentKind = "init" | "media";
+/**
+ * A single fMP4 segment yielded by {@link Mp4SegmentAssembler.stream}, tagged with its kind so a consumer can tell the one-shot initialization segment apart from the
+ * media fragments that follow it without relying on positional ordering.
+ *
+ * @property bytes  - The complete segment bytes: for `"init"`, the concatenated initialization boxes (typically `ftyp` + `moov`); for `"media"`, a concatenated
+ *                    `moof` + `mdat` pair.
+ * @property kind   - `"init"` for the single leading initialization segment, `"media"` for each subsequent media fragment.
+ *
+ * @category FFmpeg
+ */
+export interface Mp4Segment {
+    bytes: Buffer;
+    kind: Mp4SegmentKind;
+}
 /**
  * AsyncDisposable fMP4 segment assembler that converts a Readable byte source into an init segment promise and a media-segment async generator.
  *
@@ -88,7 +110,7 @@ export declare class Mp4SegmentAssembler implements AsyncDisposable {
     get aborted(): boolean;
     /**
      * `true` when the abort reason indicates a timeout. Matches both the canonical `HbpuAbortError("timeout")` emitted by the inter-segment watchdog and the platform
-     * `TimeoutError` emitted by `AbortSignal.timeout()`. The discrimination lives in {@link isTimeoutReason} so this getter stays a one-line delegation and every
+     * `TimeoutError` emitted by `AbortSignal.timeout()`. The branching lives in {@link isTimeoutReason} so this getter stays a one-line delegation and every
      * resource class in the library shares one definition of "timeout."
      */
     get isTimedOut(): boolean;
@@ -105,9 +127,9 @@ export declare class Mp4SegmentAssembler implements AsyncDisposable {
      * ends, the assembler aborts, or the optional caller signal aborts; in every case the queue is drained before the generator returns, so a consumer never loses a
      * segment that was already assembled before teardown.
      *
-     * **Single-consumer only.** The internal parked-waiter slot is single-writer; calling `segments()` concurrently with another consumer on the same assembler is
-     * unsupported and will hang one of the consumers when the producer's wake-up resolves only the later parker. If fan-out is needed, tee at the consumer side by
-     * replicating each yielded Buffer into per-consumer queues external to the assembler.
+     * **Single-consumer only.** The internal parked-waiter slot is single-writer; calling `segments()` concurrently with another consumer on the same assembler - including
+     * the {@link Mp4SegmentAssembler.stream} view, which drives this generator internally - is unsupported and will hang one of the consumers when the producer's wake-up
+     * resolves only the later parker. If fan-out is needed, tee at the consumer side by replicating each yielded Buffer into per-consumer queues external to the assembler.
      *
      * @param init - Optional init options. `signal` composes with the assembler's own signal - aborting it terminates only this generator call, not the assembler.
      *
@@ -116,5 +138,24 @@ export declare class Mp4SegmentAssembler implements AsyncDisposable {
     segments(init?: {
         signal?: AbortSignal;
     }): AsyncGenerator<Buffer>;
+    /**
+     * Async generator yielding the whole segment stream as a kind-tagged sequence: exactly one {@link Mp4Segment} of kind `"init"` carrying the initialization bytes,
+     * followed by one of kind `"media"` per completed media fragment. This is a third view over the same single-pass pipeline, composed from {@link initSegment} and
+     * {@link segments} - it lets a consumer forward the init segment and the media segments through a single loop without tracking which item is which by position.
+     *
+     * Terminates cleanly on the same conditions as {@link segments}: the source ends, the assembler aborts, or the optional caller signal aborts; queued media drains
+     * before the generator returns, so no assembled segment is lost. If the assembler is aborted before the initialization segment arrives, the generator returns without
+     * yielding anything.
+     *
+     * **Single-consumer only.** `stream()` drives {@link segments} internally, so it shares the one parked-waiter slot. Use `stream()` OR the {@link initSegment} /
+     * {@link segments} pair on a single assembler, never both concurrently - mixing them competes for the same drain and hangs one consumer.
+     *
+     * @param init - Optional init options. `signal` composes with the assembler's own signal - aborting it terminates only this generator call, not the assembler.
+     *
+     * @returns An async generator yielding one `"init"` segment followed by `"media"` segments in stream order.
+     */
+    stream(init?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<Mp4Segment>;
 }
 //# sourceMappingURL=mp4-assembler.d.ts.map