Align CSS injection contract and improve release tooling

.github/workflows/release.yml

@@ -45,10 +45,11 @@ jobs:
       - name: Use Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: 'npm'
-          registry-url: 'https://registry.npmjs.org'
-          always-auth: true
+
+      - name: Update npm
+        run: npm install -g npm@latest
 
       - name: Install dependencies
         run: npm ci
@@ -63,8 +64,6 @@ jobs:
           DEBUG: release-it:*,@release-it/*
           HUSKY: 0
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           VERSION_ARG=""
           if [ -n "${{ inputs.version }}" ]; then
@@ -94,4 +93,3 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
         env:
           HUSKY: 0
-

.gitignore

@@ -16,3 +16,4 @@ stats.html
 .tool-versions
 .cache
 *-stats.txt
+.npmrc

.husky/pre-commit

@@ -1,7 +1,5 @@
 #!/usr/bin/env sh
 
-# Husky pre-commit hook: format and run related tests on staged files
+# Husky pre-commit hook: format and lint staged files
 
-npm run lint:fix:aggressive || exit 1;
-npm run test || exit 1;
-npm run format || exit 1;
+npx --no -- lint-staged

.husky/pre-push

@@ -4,4 +4,3 @@
 
 npm run typecheck || exit 1
 npm run test:ci || exit 1
-npm run build || exit 1

.release-it.cjs

@@ -107,7 +107,71 @@ const types = new Map([
 const normalizeRepoUrl = url => url.replace(/^git\+/, "").replace(/\.git$/, "");
 const repoUrl = pkg?.repository?.url ? normalizeRepoUrl(pkg.repository.url) : null;
 
-module.exports = () => {
+const breakingChangePattern = /\bBREAKING(?: |-)?CHANGE\b/i;
+
+function hasBreakingChange(commit) {
+    if (commit.breaking) {
+        return true;
+    }
+
+    const type = String(commit.type || "").trim();
+
+    if (type.endsWith("!")) {
+        return true;
+    }
+
+    if (typeof commit.header === "string" && /^\w+(?:\([^)]+\))?!:/.test(commit.header)) {
+        return true;
+    }
+
+    if (
+        commit.notes?.some(note =>
+            [note.title, note.text].some(value => typeof value === "string" && breakingChangePattern.test(value))
+        )
+    ) {
+        return true;
+    }
+
+    return typeof commit.footer === "string" && breakingChangePattern.test(commit.footer);
+}
+
+function whatBump(commits, currentVersion = pkg.version) {
+    let isBreaking = false;
+    let isMinor = false;
+    let isPatch = false;
+
+    for (const commit of commits) {
+        if (hasBreakingChange(commit)) {
+            isBreaking = true;
+        }
+
+        const type = String(commit.type || "")
+            .trim()
+            .toLowerCase()
+            .replace(/!+$/, "");
+
+        if (["feat", "revert"].includes(type)) {
+            isMinor = true;
+        }
+
+        if (["fix", "perf", "refactor", "ci"].includes(type)) {
+            isPatch = true;
+        }
+    }
+
+    if (isBreaking) {
+        const currentMajor = Number.parseInt(String(currentVersion).replace(/^v/i, "").split(".")[0], 10);
+
+        return {level: Number.isNaN(currentMajor) || currentMajor >= 1 ? 0 : 1};
+    }
+
+    if (isMinor) return {level: 1};
+    if (isPatch) return {level: 2};
+
+    return null;
+}
+
+const createReleaseConfig = () => {
     const contributors = getContributors();
 
     return {
@@ -139,8 +203,11 @@ module.exports = () => {
 
         npm: {
             publish: true,
+            skipChecks: true,
+            provenance: true,
+            access: "public",
+            registry: "https://registry.npmjs.org/",
             versionArgs: ["--no-git-tag-version"],
-            publishArgs: ["--provenance", "--access", "public"],
         },
 
         plugins: {
@@ -165,37 +232,7 @@ module.exports = () => {
                     contributors,
                 },
 
-                recommendedBumpOpts: {
-                    preset: "conventionalcommits",
-                    whatBump: commits => {
-                        let isMajor = false;
-                        let isMinor = false;
-                        let isPatch = false;
-
-                        for (const commit of commits) {
-                            if (commit.notes?.some(n => /BREAKING CHANGE/i.test(n.title || n.text || ""))) {
-                                isMajor = true;
-                                break;
-                            }
-
-                            const type = (commit.type || "").toLowerCase();
-
-                            if (type === "feat") {
-                                isMinor = true;
-                            }
-
-                            if (["fix", "perf", "refactor", "ci"].includes(type)) {
-                                isPatch = true;
-                            }
-                        }
-
-                        if (isMajor) return {level: 0};
-                        if (isMinor) return {level: 1};
-                        if (isPatch) return {level: 2};
-
-                        return null;
-                    },
-                },
+                whatBump,
                 writerOpts: {
                     headerPartial:
                         "## 🚀 Release {{#if name}}`{{name}}` {{else}}{{#if @root.pkg}}`{{@root.pkg.name}}` {{/if}}{{/if}}v{{version}} ({{date}})\n\n",
@@ -254,3 +291,5 @@ module.exports = () => {
         },
     };
 };
+
+module.exports = Object.assign(createReleaseConfig, {whatBump});

CONTRIBUTING.md

@@ -5,7 +5,7 @@
 
 # Contributing to @addon-core/inject-css
 
-This document outlines the process for contributing, reporting issues, and submitting patches. By participating, you agree to abide by the project’s [Code of Conduct](CODE_OF_CONDUCT.md).
+This package provides one typed CSS insertion and removal contract across Manifest V2 and Manifest V3. Contributions should preserve that boundary, keep unsupported capabilities explicit, and include verification for every affected adapter. By participating, you agree to abide by the project’s [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Table of Contents
 
@@ -70,17 +70,32 @@ The following scripts are available and should be used during development:
 
 - `npm run build` — build the project with tsup
 - `npm run build:watch` — build in watch mode
+- `npm run dev` — build in watch mode
 - `npm run format` — format code with Biome
 - `npm run format:check` — check formatting only
 - `npm run lint` — lint code with Biome
 - `npm run lint:fix` — attempt to automatically fix lint issues
 - `npm run lint:fix:aggressive` — fix lint issues using unsafe rules
+- `npm run lint:fix:unsafe` — fix lint issues using unsafe rules
 - `npm run typecheck` — run TypeScript type checks
-- `npm run test` — run tests with Jest
+- `npm run test:types` — type-check public API contract fixtures
+- `npm run test` — type-check fixtures, build the package, and run Jest
 - `npm run test:ci` — run tests in CI with coverage
 - `npm run release` — trigger release via release-it
 
-Note: Husky hooks are configured. On commit, your message is validated with commitlint; on pre-commit, linting/formatting/tests are run.
+Note: Husky hooks are configured. Commit messages are validated with commitlint, pre-commit runs `lint-staged`, and pre-push runs the full type/test/build path.
+
+## Contract Guidelines
+
+- Every operation has one explicit `target`.
+- `allFrames`, `frameIds`, and `documentIds` remain mutually exclusive.
+- Unsupported targets and options fail explicitly; they are never removed silently or replaced with a broader target.
+- `insert()`, `file()`, `remove()`, and `removeFile()` remain strict `Promise<void>` operations because native CSS APIs expose no portable per-frame result.
+- File order is part of the CSS cascade contract and must be preserved.
+- Omitted options preserve native defaults.
+- Explicit `undefined` values passed to `options()` reset the corresponding option.
+- Removal must preserve the caller's exact source, target, and origin; the package does not track prior insertions.
+- Frame enumeration, document discovery, and application-specific result aggregation remain outside this package.
 
 ## Pull Request Workflow
 
@@ -98,7 +113,7 @@ Note: Husky hooks are configured. On commit, your message is validated with comm
    npm run test
    ```
 4. Commit changes using [Conventional Commits](https://www.conventionalcommits.org/).
-5. Push to your fork and open a Pull Request against the `main` branch.
+5. Push to your fork and open a Pull Request against the `develop` branch.
 6. Provide a clear title and description, referencing related issues (e.g., `Closes #123`).
 
 ## Code Style & Quality