@addon-core/inject-css 0.3.1 → 0.4.0

package/README.md

@@ -1,125 +1,277 @@
 # @addon-core/inject-css
 
-[![npm version](https://img.shields.io/npm/v/%40addon-core%2Finject-css.svg?logo=npm)](https://www.npmjs.com/package/@addon-core/inject-css)
-[![npm downloads](https://img.shields.io/npm/dm/%40addon-core%2Finject-css.svg)](https://www.npmjs.com/package/@addon-core/inject-css)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
-[![CI](https://github.com/addon-stack/inject-css/actions/workflows/ci.yml/badge.svg)](https://github.com/addon-stack/inject-css/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/%40addon-core%2Finject-css.svg?logo=npm&style=for-the-badge)](https://www.npmjs.com/package/@addon-core/inject-css)
+[![npm downloads](https://img.shields.io/npm/dm/%40addon-core%2Finject-css.svg?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@addon-core/inject-css)
+[![CI](https://img.shields.io/github/actions/workflow/status/addon-stack/inject-css/ci.yml?style=for-the-badge)](https://github.com/addon-stack/inject-css/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE.md)
 
-A lightweight, TypeScript-ready library for injecting CSS into browser extension pages.
-Automatically detects Chrome Extension Manifest V2 and V3 and delegates to the appropriate API via [@addon-core/browser](https://github.com/addon-stack/browser). 
+Insert and remove CSS code or extension stylesheets in browser tabs with one typed API for Manifest V2 and Manifest V3.
 
-## Table of Contents
+`@addon-core/inject-css` selects the correct native adapter, validates the target before delivery, and keeps unsupported browser behavior explicit.
 
-- [Installation](#installation)
-- [Usage](#usage)
-    - [Injecting CSS Code](#injecting-css-code)
-    - [Injecting CSS Files](#injecting-css-files)
-    - [Updating Options](#updating-options)
-- [API](#api)
-- [Options](#options)
-- [Examples](#examples)
-- [License](#license)
+- One target model for the top frame, all frames, selected frames, or selected documents
+- Runtime validation that matches the TypeScript contract
+- Ordered stylesheet injection
+- Matching stylesheet removal where the browser exposes a native removal API
+- Stable package errors for invalid, unsupported, failed, and timed-out operations
+- No silent selector fallback and no extra frame-enumeration permissions
 
-## Installation
-
-### npm:
+## Install
 
 ```bash
 npm install @addon-core/inject-css
 ```
 
-### pnpm:
-
 ```bash
 pnpm add @addon-core/inject-css
 ```
 
-### yarn:
+Your extension still needs the native permissions required for CSS injection, including `scripting` in MV3 and appropriate host or `activeTab` access. The package does not modify the manifest.
 
-```bash
-yarn add @addon-core/inject-css
+## Quick start
+
+```ts
+import injectCss from "@addon-core/inject-css";
+
+const injector = injectCss({
+  target: {tabId: 123},
+});
+
+await injector.insert("body { background: #f5f5f5; }");
+
+// The source, target, and origin match the insertion.
+await injector.remove("body { background: #f5f5f5; }");
 ```
 
+The package detects the current manifest version automatically. Insertion uses `tabs.insertCSS` in MV2 and `scripting.insertCSS` in MV3; removal uses the matching native removal API when available.
+
+## Choose what to target
+
+Every injector has exactly one target. Selectors are mutually exclusive in TypeScript and validated again at runtime.
 
-## Usage
+| Need | Target |
+| --- | --- |
+| Main frame | `{tabId: 123}` |
+| Every injectable frame | `{tabId: 123, allFrames: true}` |
+| One frame | `{tabId: 123, frameIds: [7]}` |
+| Selected frames | `{tabId: 123, frameIds: [0, 7, 12]}` |
+| Selected documents | `{tabId: 123, documentIds: ["document-a", "document-b"]}` |
 
 ```ts
-import injectCss, {InjectCssOptions} from "@addon-core/inject-css";
+const topFrame = injectCss({
+  target: {tabId: 123},
+});
+
+const selectedFrames = injectCss({
+  target: {tabId: 123, frameIds: [0, 7]},
+});
+
+const allFrames = injectCss({
+  target: {tabId: 123, allFrames: true},
+});
+```
+
+`allFrames` accepts only the literal `true`. Omitting a selector means the top frame; there is no `allFrames: false` mode.
 
-// Initialize an injector with a target tab ID
-const injector = injectCss({tabId: 123});
+`documentIds` require an MV3 runtime with native document targeting. An unsupported target throws `UnsupportedInjectCssTargetError`; the package never drops `documentIds` or falls back to a broader target.
 
-// Inject raw CSS code into the page
-await injector.insert("body { background-color: #f0f0f0; }");
+`allFrames` remains one native browser operation. The package does not enumerate frames or promise an exhaustive frame snapshot.
 
-// Inject one or more CSS files (paths relative to extension)
-await injector.file("styles/main.css");
-await injector.file(["styles/reset.css", "styles/theme.css"]);
+## Insert CSS code
 
-// Update options dynamically and reuse the injector
-injector.options({frameId: true, origin: "USER"});
-await injector.insert("p { color: red; }");
+```ts
+await injector.insert(`
+  html {
+    color-scheme: dark;
+  }
+
+  body {
+    background: #111;
+    color: #eee;
+  }
+`);
 ```
 
-### Injecting CSS Code
+The CSS source must be a non-empty string.
 
-Use the `insert(css: string)` method to inject raw CSS code.
+## Insert CSS files
 
-### Injecting CSS Files
+```ts
+await injector.file("styles/content.css");
 
-Use the `file(files: string | string[])` method to inject CSS file(s).
+await injector.file([
+  "styles/reset.css",
+  "styles/theme.css",
+]);
+```
 
-### Updating Options
+File lists must be non-empty and every path must be a non-empty string. Files are injected in the provided order. In MV2, one file completes for the requested target before the next file starts, preserving CSS cascade order.
 
-Use the `options(opts: Partial<InjectCssOptions>)` method to merge or override options on an existing injector instance.
+## Remove CSS
 
-## API
+Remove CSS code with `remove()` and extension stylesheets with `removeFile()`:
 
-### `injectCss(options: InjectCssOptions): InjectCssContract`
+```ts
+await injector.remove("body { background: #f5f5f5; }");
 
-Creates a new CSS injector instance. Detects the manifest version (V2 or V3) via `@addon-core/browser` and delegates to the appropriate implementation.
+await injector.removeFile("styles/content.css");
 
-#### `InjectCssContract`
+await injector.removeFile([
+  "styles/reset.css",
+  "styles/theme.css",
+]);
+```
 
-- `insert(css: string): Promise<void>` — Inject raw CSS code.
-- `file(files: string | string[]): Promise<void>` — Inject one or more CSS files.
-- `options(opts: Partial<InjectCssOptions>): this` — Update injector options.
+Removal uses the injector's current target and origin. The CSS source, file list, target, and origin must match the values used for insertion. Removing a stylesheet that is not present is a native no-op.
 
-## Options
+MV3 uses `scripting.removeCSS`. MV2 uses `tabs.removeCSS` only when the current browser exposes it; otherwise removal rejects with `UnsupportedInjectCssOperationError`. This capability is checked when removal is requested, so insertion remains available in MV2 browsers without `tabs.removeCSS`.
 
-The injector accepts the following options (passed to `injectCss(options)` and/or `injector.options(opts)`):
+MV2 removes multiple files sequentially in the provided order, matching its insertion behavior. `runAt` affects insertion only because the MV2 removal API has no corresponding field.
 
-| Option          | Type                                                  | Description                                                                                  |
-| --------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| tabId           | number                                                | Required. Target browser tab ID.                                                             |
-| frameId         | boolean \| number \| number[]                         | Optional. Select frames to inject into: `true` for all frames; number or array for specific. |
-| matchAboutBlank | boolean                                               | Optional. (V2 only) Include `about:blank` and similar subframes. Defaults to `true`.         |
-| runAt           | 'document_start' \| 'document_end' \| 'document_idle' | Optional. (V2 only) Injection timing, matches Chrome's `runAt` in `insertCSS`.               |
-| documentId      | string \| string[]                                    | Optional. (V3 only) Document IDs for scripting targets.                                      |
-| origin          | 'AUTHOR' \| 'USER'                                    | Optional. CSS origin matching Chrome's API (`cssOrigin` in V2, `origin` in V3).              |
+## Reuse an injector
 
-## Examples
+Replace the complete target with `target()`:
 
 ```ts
-import injectCss from "@addon-core/inject-css";
+injector
+  .target({tabId: 123, frameIds: [7]})
+  .target({tabId: 123, allFrames: true});
+```
+
+The second call replaces the previous selector instead of merging with it. A validation failure leaves the existing target unchanged.
+
+Update only execution options with `options()`:
+
+```ts
+injector.options({
+  origin: "USER",
+  timeoutMs: 8_000,
+});
+```
+
+`options()` never accepts or changes a target. Passing an explicit `undefined` resets that option instead of retaining its previous value:
 
-// Initialize with a mix of options
+```ts
+injector.options({
+  origin: undefined,
+  timeoutMs: undefined,
+});
+```
+
+The next operation then uses the native origin default and the package's default timeout.
+
+## Execution options
+
+The portable baseline is to omit adapter-specific options:
+
+```ts
 const injector = injectCss({
-    tabId: 123,
-    frameId: [1, 2], // (V2 & V3)
-    runAt: "document_end", // (V2 only)
-    documentId: "main-doc-id", // (V3 only)
-    origin: "AUTHOR", // 'AUTHOR' or 'USER'
+  target: {tabId: 123},
+  origin: "AUTHOR",
+  timeoutMs: 5_000,
 });
+```
+
+| Option | MV2 | MV3 |
+| --- | --- | --- |
+| `origin` | Mapped to `author` or `user` | Passed as `AUTHOR` or `USER` |
+| `timeoutMs` | Supported; default `4_000` ms | Supported; default `4_000` ms |
+| `matchAboutBlank` | Passed only when explicitly set | Rejected; no native equivalent |
+| `runAt` | Passed to `tabs.insertCSS` | Rejected; no native equivalent |
+
+When `matchAboutBlank` is omitted, the package preserves the native default instead of forcing it to `true`.
+
+Explicit unsupported options throw `UnsupportedInjectCssOptionError`. They are never ignored silently.
+
+## Handle failures
+
+```ts
+import {InjectCssBaseError} from "@addon-core/inject-css";
+
+try {
+  await injector.file("styles/content.css");
+} catch (error) {
+  if (error instanceof InjectCssBaseError) {
+    console.error(error.code, error.message, error.cause);
+  } else {
+    throw error;
+  }
+}
+```
+
+Every rejected package operation exposes an error derived from `InjectCssBaseError` with a stable `code`. Delivery and timeout errors also retain the request target and expose `operation` as `"insert"` or `"remove"`. For explicit MV2 frame targets, a delivery error may contain an `InjectCssFrameDeliveryError` cause with code `ERR_INJECT_CSS_FRAME_DELIVERY`, the failed `tabId`, `frameId`, operation, and native cause. Prefer `code` when errors may cross realms or multiple copies of the dependency may exist.
 
-// Inject raw CSS code
-await injector.insert("body { background-color: #fafafa; }");
+Known validation and adapter incompatibilities fail before delivery. Browser capabilities discovered only by a native call are normalized after that call.
 
-// Inject one or more CSS files
-await injector.file(["styles/reset.css", "styles/theme.css"]);
+### What `Promise<void>` means
+
+Native CSS injection and removal APIs do not provide a portable per-frame result. `insert()`, `file()`, `remove()`, and `removeFile()` therefore resolve with no value.
+
+A resolved promise means the native operation completed. It does not prove that CSS was inserted or removed in every requested frame. A rejected multi-target operation is not transactional: some targets or earlier files may already have completed the requested change.
+
+In MV2, a timeout stops the package from starting later files in a sequential insertion or removal batch. In MV3, the complete file list is handed to the browser in one native call before a timeout can occur. In either adapter, a timeout cannot cancel a native browser operation that is already in progress.
+
+## API reference
+
+The factory is available as both a default and named export:
+
+```ts
+import injectCss from "@addon-core/inject-css";
+import {injectCss} from "@addon-core/inject-css";
 ```
 
+```ts
+interface InjectCssContract {
+  insert(css: string): Promise<void>;
+  file(files: string | NonEmptyReadonlyArray<string>): Promise<void>;
+  remove(css: string): Promise<void>;
+  removeFile(files: string | NonEmptyReadonlyArray<string>): Promise<void>;
+  target(target: InjectCssTarget): this;
+  options(options: InjectCssExecutionOptionsPatch): this;
+}
+```
+
+Runtime exports:
+
+```text
+injectCss
+InjectCssBaseError
+InjectCssDeliveryError
+InjectCssFrameDeliveryError
+InjectCssTimeoutError
+InvalidInjectCssCodeError
+InvalidInjectCssFilesError
+InvalidInjectCssOptionsError
+InvalidInjectCssTargetError
+UnsupportedInjectCssOptionError
+UnsupportedInjectCssOperationError
+UnsupportedInjectCssTargetError
+```
+
+Core type exports:
+
+```text
+InjectCssContract
+InjectCssOptions
+InjectCssExecutionOptions
+InjectCssExecutionOptionsPatch
+InjectCssOperation
+InjectCssOrigin
+InjectCssTarget
+InjectCssTopFrameTarget
+InjectCssAllFramesTarget
+InjectCssFramesTarget
+InjectCssDocumentsTarget
+InjectCssErrorCode
+NonEmptyReadonlyArray
+```
+
+## Design boundaries
+
+The package focuses on portable programmatic CSS insertion and removal. It does not enumerate frames, discover document IDs, track which stylesheets were inserted, aggregate application-specific per-frame results, or claim atomic delivery across targets.
+
+Callers remain responsible for retaining the exact source, target, and origin needed for later removal.
 
 ## License
 
-MIT © Addon Stack
+[MIT](LICENSE.md)