homebridge-plugin-utils 1.35.0 → 2.0.0

package/dist/clock.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The injectable wall-clock contract: the platform time primitives time-dependent code reads. A consumer holds a `Clock` rather than calling `Date.now()` /
+ * `node:timers/promises` `setTimeout` directly, so a test can substitute a controllable double (`TestClock`) and drive time deterministically while production behavior
+ * stays unchanged through {@link systemClock}.
+ *
+ * @see systemClock
+ *
+ * @category Utilities
+ */
+export interface Clock {
+    /**
+     * Resolve after `ms` milliseconds, or reject if `init.signal` aborts first. The production {@link systemClock} implements this as `node:timers/promises` `setTimeout`,
+     * so an abort rejects with that primitive's `AbortError` (`name` `"AbortError"`, `code` `"ABORT_ERR"`) rather than the signal's reason.
+     *
+     * @param ms   - The delay, in milliseconds.
+     * @param init - Optional init options. `signal` cancels the delay - resolving the wait early with a rejection - when it aborts.
+     *
+     * @returns A promise that resolves after the delay, or rejects with an `AbortError` if the signal aborts first.
+     */
+    delay(ms: number, init?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Return the current time as epoch milliseconds. The production {@link systemClock} implements this as `Date.now()`.
+     *
+     * @returns The current time in epoch milliseconds.
+     */
+    now(): number;
+}
+/**
+ * The behavior-neutral production {@link Clock}: `now()` IS `Date.now()` and `delay()` IS `node:timers/promises` `setTimeout`. A consumer that routes its time reads
+ * through this clock instead of calling those primitives directly cannot observe any behavior change - it is the same two calls, one indirection removed at test time.
+ *
+ * @see Clock
+ *
+ * @category Utilities
+ */
+export declare const systemClock: Clock;
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.js

@@ -0,0 +1,34 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * clock.ts: An injectable wall-clock seam - the current time and an abortable delay - so time-dependent code can be driven deterministically under test.
+ */
+/**
+ * An injectable wall-clock time seam.
+ *
+ * Time-dependent code reads the platform time primitives it needs: the current epoch time (`Date.now()`) and a delay that can be cancelled (`node:timers/promises`
+ * `setTimeout`). Calling those directly bakes real wall-clock time into the code, so a test cannot exercise a pacing or timeout path without multi-second real waits, and
+ * `node:test`'s mock timers do not patch the `node:timers/promises` primitives. Holding a {@link Clock} instead - the abstraction over those primitives - inverts the
+ * dependency: production wires {@link systemClock}, whose `now()` IS `Date.now()` and whose `delay()` IS `node:timers/promises` `setTimeout`, so routing through the seam
+ * is behavior-neutral; a test wires a `TestClock` (see `clock-double.ts`) that advances virtual time explicitly, so the consumer's time-dependent path runs
+ * deterministically and instantly.
+ *
+ * This module imports `node:timers/promises` and is therefore Node-only (not browser-safe), like `util.ts`. A browser-targeted consumer cannot resolve that import.
+ *
+ * @module
+ */
+import { setTimeout as delay } from "node:timers/promises";
+/**
+ * The behavior-neutral production {@link Clock}: `now()` IS `Date.now()` and `delay()` IS `node:timers/promises` `setTimeout`. A consumer that routes its time reads
+ * through this clock instead of calling those primitives directly cannot observe any behavior change - it is the same two calls, one indirection removed at test time.
+ *
+ * @see Clock
+ *
+ * @category Utilities
+ */
+export const systemClock = {
+    // `setTimeout(ms, value, options)` from `node:timers/promises`: pass `undefined` for the resolution value and forward `init` as the options so the caller's signal
+    // cancels the wait. `setTimeout(ms, undefined, opts)` resolves to `Promise<undefined>`, which is assignable to the `Promise<void>` the contract declares.
+    delay: (ms, init) => delay(ms, undefined, init),
+    now: () => Date.now()
+};
+//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAgC3D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAU;IAEhC,mKAAmK;IACnK,0JAA0J;IAC1J,KAAK,EAAE,CAAC,EAAU,EAAE,IAA+B,EAAiB,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC;IACjG,GAAG,EAAE,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;CAC9B,CAAC"}

package/dist/eslint-plugin/config.d.mts

@@ -0,0 +1,193 @@
+export default config;
+/**
+ * Build a ready-to-use ESLint flat config array. Consumers call this function and export default the result.
+ *
+ * Every option is optional and defaults to an empty array, mirrored by the destructuring defaults in the signature below. The JSDoc marks them optional with the
+ * bracket form so the emitted declaration types each property as optional, matching how consumers actually call this - passing only the subset they need.
+ *
+ * @param {object} [options] - Configuration options.
+ * @param {string[]} [options.ts] - Glob patterns for TypeScript files (strict + stylistic type-checked rules).
+ * @param {string[]} [options.js] - Glob patterns for JavaScript files (disable-type-checked rules).
+ * @param {string[]} [options.ui] - Glob patterns for browser UI files (adds browser globals).
+ * @param {string[]} [options.allowDefaultProject] - Globs passed to parserOptions.projectService.allowDefaultProject.
+ * @param {string[]} [options.ignores] - Global ignore patterns (in addition to the hardcoded "dist" ignore on the common block).
+ * @param {object[]} [options.extraConfigs] - Additional flat config objects appended to the output.
+ * @returns {object[]} A flat config array suitable for `export default` in eslint.config.mjs. Block ordering is significant - do not reorder.
+ */
+export function config({ allowDefaultProject, extraConfigs, ignores, js, ts: tsFiles, ui }?: {
+    ts?: string[] | undefined;
+    js?: string[] | undefined;
+    ui?: string[] | undefined;
+    allowDefaultProject?: string[] | undefined;
+    ignores?: string[] | undefined;
+    extraConfigs?: any[] | undefined;
+}): object[];
+/**
+ * Rule preset applied to every linted file regardless of language. Disables the base ESLint rules that are redundant once TypeScript's own compiler
+ * and syntax already catch the same errors, mirroring the `typescript-eslint` compatibility overlay it spreads in; the enabled ESLint-recommended
+ * baseline itself comes from the separate `eslintJs.configs.recommended` block pushed in {@link config}. Layers on top of that the full `@hjdhjd/*`
+ * rule set, the `@stylistic/*` whitespace and formatting rules, and the project's opinionated `sort-imports` / `sort-keys` / `quotes` / `eqeqeq` /
+ * `curly` constraints.
+ *
+ * Spread into the `rules:` slot of the all-files block of a flat config.
+ */
+export const commonRules: {
+    "@hjdhjd/blank-line-after-open-brace": string;
+    "@hjdhjd/comment-style": string;
+    "@hjdhjd/enforce-node-protocol": string;
+    "@hjdhjd/paren-comparisons-in-logical": string;
+    "@hjdhjd/split-type-imports": string;
+    "@stylistic/array-bracket-spacing": (string | {
+        arraysInArrays: boolean;
+        objectsInArrays: boolean;
+        singleValue: boolean;
+    })[];
+    "@stylistic/block-spacing": string;
+    "@stylistic/brace-style": (string | {
+        allowSingleLine: boolean;
+    })[];
+    "@stylistic/comma-dangle": string;
+    "@stylistic/eol-last": string[];
+    "@stylistic/generator-star-spacing": string;
+    "@stylistic/implicit-arrow-linebreak": string;
+    "@stylistic/indent": (string | number | {
+        SwitchCase: number;
+    })[];
+    "@stylistic/keyword-spacing": (string | {
+        overrides: {
+            for: {
+                after: boolean;
+            };
+            if: {
+                after: boolean;
+            };
+            switch: {
+                after: boolean;
+            };
+            while: {
+                after: boolean;
+            };
+        };
+    })[];
+    "@stylistic/linebreak-style": string[];
+    "@stylistic/lines-between-class-members": (string | {
+        exceptAfterSingleLine: boolean;
+    })[];
+    "@stylistic/max-len": (string | number)[];
+    "@stylistic/no-tabs": string;
+    "@stylistic/no-trailing-spaces": string;
+    "@stylistic/operator-linebreak": (string | {
+        overrides: {
+            ":": string;
+            "?": string;
+        };
+    })[];
+    "@stylistic/padding-line-between-statements": (string | {
+        blankLine: string;
+        next: string[];
+        prev: string;
+    } | {
+        blankLine: string;
+        next: string;
+        prev: string[];
+    } | {
+        blankLine: string;
+        next: string[];
+        prev: string[];
+    } | {
+        blankLine: string;
+        next: string;
+        prev: string;
+    })[];
+    "@stylistic/semi": string[];
+    "@stylistic/space-before-function-paren": (string | {
+        anonymous: string;
+        asyncArrow: string;
+        catch: string;
+        named: string;
+    })[];
+    "@stylistic/space-in-parens": string;
+    "@stylistic/space-infix-ops": string;
+    "@stylistic/space-unary-ops": string;
+    "@typescript-eslint/dot-notation": (string | {
+        allowIndexSignaturePropertyAccess: boolean;
+    })[];
+    "@typescript-eslint/no-this-alias": string;
+    camelcase: string;
+    curly: string[];
+    "dot-notation": string;
+    eqeqeq: string;
+    "logical-assignment-operators": (string | {
+        enforceForIfStatements: boolean;
+    })[];
+    "no-await-in-loop": string;
+    "no-console": string;
+    "no-restricted-syntax": string[];
+    "prefer-arrow-callback": string;
+    "prefer-const": string;
+    quotes: (string | {
+        allowTemplateLiterals: boolean;
+        avoidEscape: boolean;
+    })[];
+    "sort-imports": string;
+    "sort-keys": string;
+    "sort-vars": string;
+};
+/**
+ * Browser-environment globals typically present in Homebridge webUI files - `window`, `document`, `fetch`, the Homebridge configuration API entry
+ * point, and a few timer functions. Each is declared as `"readonly"` so `no-undef` accepts references without permitting reassignment.
+ *
+ * Pass into the `languageOptions.globals` slot of a flat config block scoped to UI files.
+ */
+export const globalsUi: {
+    [k: string]: string;
+};
+/**
+ * Rule preset for JavaScript source files. Starts from `typescript-eslint`'s `disableTypeChecked` set (so type-aware rules don't fire on plain JS), then
+ * re-enables `no-unused-vars` with the underscore-prefix ignore pattern. The `require-await` rule is left disabled here for the same reason the TypeScript
+ * preset omits its pair - see the omission paragraph in the {@link tsRules} JSDoc.
+ *
+ * Spread into the `rules:` slot of a flat config block scoped to `.js` / `.mjs` files.
+ */
+export const jsRules: {
+    "@typescript-eslint/no-floating-promises": string;
+    "no-unused-vars": (string | {
+        argsIgnorePattern: string;
+        caughtErrors: string;
+        caughtErrorsIgnorePattern: string;
+        varsIgnorePattern: string;
+    })[];
+};
+/**
+ * The ESLint plugin namespace map used by the composed configuration: `@hjdhjd` (this package's rules), `@stylistic` (the official stylistic-rules
+ * plugin), and `@typescript-eslint`. Drop this object into the `plugins` slot of a flat config block to register every plugin namespace this preset
+ * composes at once.
+ *
+ * The type annotation is deliberately loose since consumers that read the named `plugins` export do their own narrowing before touching rule entries.
+ * It's annotated explicitly so the emitted type stays portable - the raw inference picks up typescript-eslint's exported `CompatiblePlugin` shape,
+ * and the `tsconfig.eslint-plugin.json` declaration-only build (TS2742) refuses to serialize it into the `.d.ts` without citing a deep module path.
+ *
+ * @type {Record<string, { meta?: { name: string; version?: string }; rules?: Record<string, unknown> }>}
+ */
+export const plugins: Record<string, {
+    meta?: {
+        name: string;
+        version?: string;
+    };
+    rules?: Record<string, unknown>;
+}>;
+/**
+ * Rule preset for TypeScript source files. Builds on `typescript-eslint`'s strict and stylistic type-checked configs, then layers project-specific
+ * overrides: type-aware lint rules (`await-thenable`, `no-floating-promises`, `prefer-nullish-coalescing`, etc.) at warn level, explicit return-type and
+ * module-boundary requirements, and `@stylistic/member-delimiter-style`. Disables the JavaScript-recommended versions of rules that have TypeScript-aware
+ * equivalents to avoid double-flagging.
+ *
+ * Deliberately omits `@typescript-eslint/promise-function-async` and forces `@typescript-eslint/require-await` (and the base `require-await`) off. The pair
+ * encodes a tight coupling between Promise return types and the `async` keyword that predates the Disposable protocol: `[Symbol.asyncDispose]()` must be declared
+ * `async ...(): Promise<void>` to satisfy `await using` even when the body is synchronous, and identity-preserving Promise pass-throughs (e.g., `markHandled` in
+ * `src/util.ts`) cannot be marked `async` without wrapping the return in a fresh chain and breaking reference equality. Encoding the stance at the preset level
+ * rather than scattering per-site `eslint-disable` directives is the SSOT.
+ *
+ * Spread into the `rules:` slot of a flat config block scoped to `.ts` files.
+ */
+export const tsRules: any;

package/dist/eslint-plugin/index.d.mts

@@ -0,0 +1,2 @@
+export { default as plugin } from "./plugin.mjs";
+export { commonRules, config, globalsUi, jsRules, plugins, tsRules, default } from "./config.mjs";

package/dist/eslint-plugin/plugin.d.mts

@@ -0,0 +1,87 @@
+export default plugin;
+declare namespace plugin {
+    namespace meta {
+        let name: string;
+        let version: string;
+    }
+    let rules: {
+        "blank-line-after-open-brace": {
+            create(context: any): {
+                BlockStatement(node: any): void;
+                ClassBody(node: any): void;
+                ObjectExpression(node: any): void;
+                TSInterfaceBody(node: any): void;
+                TSTypeAliasDeclaration(node: any): void;
+            };
+            meta: {
+                docs: {
+                    description: string;
+                    recommended: boolean;
+                };
+                fixable: string;
+                schema: never[];
+                type: string;
+            };
+        };
+        "comment-style": {
+            create(context: any): {
+                Program(): void;
+            };
+            meta: {
+                docs: {
+                    description: string;
+                    recommended: boolean;
+                };
+                fixable: string;
+                schema: never[];
+                type: string;
+            };
+        };
+        "enforce-node-protocol": {
+            create(context: any): {
+                ExportAllDeclaration(node: any): void;
+                ExportNamedDeclaration(node: any): void;
+                ImportDeclaration(node: any): void;
+                ImportExpression(node: any): void;
+            };
+            meta: {
+                docs: {
+                    description: string;
+                    recommended: boolean;
+                };
+                fixable: string;
+                schema: never[];
+                type: string;
+            };
+        };
+        "paren-comparisons-in-logical": {
+            create(context: any): {
+                LogicalExpression(node: any): void;
+            };
+            meta: {
+                docs: {
+                    description: string;
+                    recommended: boolean;
+                };
+                fixable: string;
+                schema: never[];
+                type: string;
+            };
+        };
+        "split-type-imports": {
+            create(context: any): {
+                ExportNamedDeclaration(node: any): void;
+                ImportDeclaration(node: any): void;
+            };
+            meta: {
+                docs: {
+                    description: string;
+                    recommended: boolean;
+                };
+                fixable: string;
+                schema: never[];
+                type: string;
+            };
+        };
+    };
+}

package/dist/eslint-plugin/rules/blank-line-after-open-brace.d.mts

@@ -0,0 +1,19 @@
+export default ruleBlankAfterOpenBrace;
+declare namespace ruleBlankAfterOpenBrace {
+    function create(context: any): {
+        BlockStatement(node: any): void;
+        ClassBody(node: any): void;
+        ObjectExpression(node: any): void;
+        TSInterfaceBody(node: any): void;
+        TSTypeAliasDeclaration(node: any): void;
+    };
+    namespace meta {
+        namespace docs {
+            let description: string;
+            let recommended: boolean;
+        }
+        let fixable: string;
+        let schema: never[];
+        let type: string;
+    }
+}

package/dist/eslint-plugin/rules/comment-style.d.mts

@@ -0,0 +1,15 @@
+export default ruleCommentStyle;
+declare namespace ruleCommentStyle {
+    function create(context: any): {
+        Program(): void;
+    };
+    namespace meta {
+        namespace docs {
+            let description: string;
+            let recommended: boolean;
+        }
+        let fixable: string;
+        let schema: never[];
+        let type: string;
+    }
+}

package/dist/eslint-plugin/rules/enforce-node-protocol.d.mts

@@ -0,0 +1,18 @@
+export default ruleEnforceNodeProtocol;
+declare namespace ruleEnforceNodeProtocol {
+    function create(context: any): {
+        ExportAllDeclaration(node: any): void;
+        ExportNamedDeclaration(node: any): void;
+        ImportDeclaration(node: any): void;
+        ImportExpression(node: any): void;
+    };
+    namespace meta {
+        namespace docs {
+            let description: string;
+            let recommended: boolean;
+        }
+        let fixable: string;
+        let schema: never[];
+        let type: string;
+    }
+}

package/dist/eslint-plugin/rules/paren-comparisons-in-logical.d.mts

@@ -0,0 +1,15 @@
+export default ruleParenComparisonsInLogical;
+declare namespace ruleParenComparisonsInLogical {
+    function create(context: any): {
+        LogicalExpression(node: any): void;
+    };
+    namespace meta {
+        namespace docs {
+            let description: string;
+            let recommended: boolean;
+        }
+        let fixable: string;
+        let schema: never[];
+        let type: string;
+    }
+}

package/dist/eslint-plugin/rules/split-type-imports.d.mts

@@ -0,0 +1,16 @@
+export default ruleSplitTypeImports;
+declare namespace ruleSplitTypeImports {
+    function create(context: any): {
+        ExportNamedDeclaration(node: any): void;
+        ImportDeclaration(node: any): void;
+    };
+    namespace meta {
+        namespace docs {
+            let description: string;
+            let recommended: boolean;
+        }
+        let fixable: string;
+        let schema: never[];
+        let type: string;
+    }
+}

package/dist/featureOptions-docs.d.ts

@@ -0,0 +1,96 @@
+/**
+ * A shared documentation renderer for the {@link featureOptions!FeatureOptions | FeatureOptions} catalog.
+ *
+ * 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
+ * elegant renderer so the documentation becomes a pure projection of the live catalog.
+ *
+ * The module exports two pure string functions:
+ *
+ *   - {@link renderFeatureOptionsReference} - the projection itself. It derives every key via {@link expandOption}, decides value-ness via {@link isValueOption}, and
+ *     builds the catalog index once via {@link buildCatalogIndex}; it never re-derives any of those. Plugin-private scope prose is supplied through two optional render
+ *     hooks that mirror the webUI's field-blind `validOption` / `validOptionCategory` predicate seam, lifted from *filter* (boolean) to *describe* (string). No
+ *     plugin-specific field name appears anywhere in this file.
+ *
+ *   - {@link spliceMarkedRegion} - the in-place splice that replaces the region between {@link FEATURE_OPTIONS_DOC_BEGIN} / {@link FEATURE_OPTIONS_DOC_END} in an
+ *     existing doc with freshly rendered content, leaving each plugin's hand-written header and intro untouched.
+ *
+ * Both functions are pure and isomorphic: no `node:` imports, no `fs`, no `process`. The only I/O - reading the doc and writing it back - is two lines of
+ * `node:fs/promises` in each plugin's build-script shim, which is inherently a tooling concern. This module is therefore browser-safe and trivially testable, but it
+ * is a tooling concern and is deliberately NOT mirrored into `dist/ui/` by the build pipeline.
+ *
+ * @module
+ */
+import type { FeatureCategoryEntry, FeatureOptionEntry } from "./featureOptions.ts";
+/**
+ * The opening marker of the auto-generated region in a plugin's `docs/FeatureOptions.md`. {@link spliceMarkedRegion} replaces everything strictly between this marker
+ * and {@link FEATURE_OPTIONS_DOC_END}, preserving both markers and the hand-written prose around them. The text doubles as an in-document warning to maintainers not to
+ * edit the region by hand.
+ *
+ * @category Feature Options
+ */
+export declare const FEATURE_OPTIONS_DOC_BEGIN = "<!-- FEATURE OPTIONS:BEGIN - Auto-generated by homebridge-plugin-utils. Do not edit this region by hand. -->";
+/**
+ * The closing marker of the auto-generated region. See {@link FEATURE_OPTIONS_DOC_BEGIN}.
+ *
+ * @category Feature Options
+ */
+export declare const FEATURE_OPTIONS_DOC_END = "<!-- FEATURE OPTIONS:END -->";
+/**
+ * Render a feature-options catalog into the markdown reference fragment a plugin embeds in its `docs/FeatureOptions.md`. The output is a category index (one bullet per
+ * category, deep-linking to its detail section), an optional one-line legend explaining the `.<value>` notation, and then one detail section per category, each carrying
+ * an optional device-scope line and a flat table of option rows. The legend is emitted only when the catalog has at least one value option, since a toggle-only catalog
+ * never renders the `.<value>` placeholder the legend describes.
+ *
+ * The renderer owns all base-shaped scaffolding - the index, headings, per-row deep-link anchors, the key cell with its value/toggle placeholder, the default cell, the
+ * description cell, and the column math - purely from the base {@link FeatureOptionEntry} / {@link FeatureCategoryEntry} fields. The two optional hooks own *only* the
+ * plugin-private scope prose: `describeCategoryScope` contributes the device-scope sentence under a category heading, and `describeOptionScope` contributes a suffix
+ * appended to an option's description cell. A hook returning `undefined` omits its contribution cleanly - never an "undefined" literal, never a stray blank line.
+ *
+ * The catalog index is built once via {@link buildCatalogIndex}; value-ness is decided via {@link isValueOption}; the canonical dotted key is derived via
+ * {@link expandOption}. None of those is re-derived here - the renderer is a projection of the same single source of truth the rest of the module owns.
+ *
+ * @typeParam TOptionMeta   - The concrete type of an option entry's opaque `meta` annotation, reconstituted at this boundary so `describeOptionScope` sees it typed.
+ * @typeParam TCategoryMeta - The concrete type of a category entry's opaque `meta` annotation, reconstituted so `describeCategoryScope` sees it typed.
+ * @param input
+ * @param input.categories            - The catalog's category list, in the order the index and detail sections should follow.
+ * @param input.describeCategoryScope - Optional. Returns the device-scope sentence emitted under a category's heading, or `undefined` to omit it. The hook owns the full
+ *                                      sentence including any leading or trailing text.
+ * @param input.describeOptionScope   - Optional. Returns a suffix appended to an option's description cell, or `undefined` to omit it. The hook owns its full text
+ *                                      including any leading separator.
+ * @param input.options               - The catalog's options map keyed by category name.
+ *
+ * @returns The rendered markdown fragment.
+ */
+export declare function renderFeatureOptionsReference<TOptionMeta = unknown, TCategoryMeta = unknown>(input: {
+    categories: readonly FeatureCategoryEntry<TCategoryMeta>[];
+    describeCategoryScope?: (category: FeatureCategoryEntry<TCategoryMeta>) => string | undefined;
+    describeOptionScope?: (option: FeatureOptionEntry<TOptionMeta>, category: FeatureCategoryEntry<TCategoryMeta>) => string | undefined;
+    options: Readonly<Record<string, readonly FeatureOptionEntry<TOptionMeta>[]>>;
+}): string;
+/**
+ * Replace the region strictly between {@link FEATURE_OPTIONS_DOC_BEGIN} and {@link FEATURE_OPTIONS_DOC_END} in `source` with `content`, leaving both markers and all
+ * surrounding prose untouched. This is the pure half of the in-place splice each plugin's build-script shim performs; the shim supplies the trivial `readFile` /
+ * `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
+ * 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.
+ * @param content           - The fragment to insert between the markers, typically the output of {@link renderFeatureOptionsReference}.
+ * @param markers
+ * @param markers.beginMarker - The opening marker to search for. Defaults to {@link FEATURE_OPTIONS_DOC_BEGIN}.
+ * @param markers.endMarker   - The closing marker to search for. Defaults to {@link FEATURE_OPTIONS_DOC_END}.
+ *
+ * @returns `source` with the marked region's contents replaced by `content`.
+ *
+ * @throws `Error` naming the offending marker when either marker is absent, when the closing marker precedes the opening marker, or when the document is ambiguous - a
+ *         second begin marker after the first, or a second end marker - since the marked region would not be uniquely identified.
+ */
+export declare function spliceMarkedRegion(source: string, content: string, { beginMarker, endMarker }?: {
+    beginMarker?: string;
+    endMarker?: string;
+}): string;
+//# sourceMappingURL=featureOptions-docs.d.ts.map