Stabilize offscreen lifecycle, add workspace mode and tighten locale contracts

.gitignore

@@ -2,6 +2,8 @@
 .env
 .env.*
 .idea
+.codex
+.claude
 .output
 addon
 *.log

package.json

@@ -4,6 +4,7 @@
   "version": "0.5.7",
   "description": "Addon Bone - Cross-browser web extension framework with shared code base",
   "homepage": "https://addonbone.com",
+  "author": "Anjey Tsibylskij (https://github.com/atldays)",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -27,10 +28,6 @@
     "opera",
     "safari"
   ],
-  "author": "Addon Stack <addonbonedev@gmail.com>",
-  "contributors": [
-    "Anjey Tsibylskij (https://github.com/atldays)"
-  ],
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -104,7 +101,7 @@
     "prepare": "husky",
     "preinstall": "npm run check:node-version",
     "prepublishOnly": "npm run build",
-    "build": "cross-env NODE_OPTIONS=--max-old-space-size=15046 tsup && node ./scripts/copy-dts.js",
+    "build": "tsup && tsc -p tsconfig.build.json && node ./scripts/copy-dts.js && tsc-alias -p tsconfig.build.json -f -fe .js",
     "format": "prettier --write .",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "check:node-version": "node ./scripts/check-node-version.js",
@@ -123,9 +120,9 @@
     "release:preview": "release-it --no-github.release --no-npm.publish --no-git.tag --ci"
   },
   "dependencies": {
-    "@addon-core/browser": "^0.2.1",
+    "@addon-core/browser": "^0.6.0",
     "@addon-core/inject-script": "^0.3.1",
-    "@addon-core/storage": "^0.4.0",
+    "@addon-core/storage": "^0.6.0",
     "@rsdoctor/rspack-plugin": "^1.5.1",
     "@rspack/cli": "^1.7.5",
     "@rspack/core": "^1.7.5",
@@ -141,7 +138,7 @@
     "html-rspack-tags-plugin": "^0.0.3",
     "js-yaml": "^4.1.1",
     "json-stringify-deterministic": "^1.0.12",
-    "lodash": "4.17.23",
+    "lodash": "4.18.1",
     "mini-css-extract-plugin": "^2.9.2",
     "nanoid": "^5.1.4",
     "pluralize": "^8.0.0",
@@ -157,7 +154,6 @@
     "zod": "^3.24.2"
   },
   "devDependencies": {
-    "glob": "^13.0.1",
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@microsoft/api-extractor": "^7.53.1",
@@ -181,14 +177,16 @@
     "esbuild-fix-imports-plugin": "^1.0.22",
     "esbuild-plugin-raw": "^0.3.0",
     "fs-extra": "^11.3.0",
+    "glob": "^13.0.1",
     "globby": "^14.1.0",
     "husky": "^9.1.7",
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.0.0",
     "jest-webextension-mock": "^4.0.0",
     "prettier": "^3.6.2",
     "release-it": "^19.2.3",
-    "ts-node": "^1.7.1",
+    "ts-node": "10.9.2",
+    "tsc-alias": "^1.8.17",
     "tsup": "^8.5.0",
     "tsx": "^4.19.2",
     "uglify-js": "^3.19.3",

src/cli/builders/locale/LocaleBuilder.test.ts

@@ -0,0 +1,115 @@
+import LocaleBuilder from "./LocaleBuilder";
+
+import {Language, LocaleCustomKeyForLanguage, LocaleValuesSeparator} from "@typing/locale";
+import {Browser} from "@typing/browser";
+
+const makeValidator = () => ({
+    isValid: jest.fn(),
+    validate: jest.fn(),
+});
+
+describe("LocaleBuilder", () => {
+    test("returns the builder language", () => {
+        expect(new LocaleBuilder(Browser.Chrome, Language.French).lang()).toBe(Language.French);
+    });
+
+    test("flattens nested data, stringifies values and injects the language marker", () => {
+        const builder = new LocaleBuilder(Browser.Chrome, Language.English).merge({
+            app: {
+                name: "My App",
+                version: 2,
+                items: ["one", 2],
+            },
+        });
+
+        expect(Object.fromEntries(builder.get())).toEqual({
+            "app.name": "My App",
+            "app.version": "2",
+            "app.items": ["one", "2"].join(LocaleValuesSeparator),
+            [LocaleCustomKeyForLanguage]: Language.English,
+        });
+    });
+
+    test("lets later merged data override earlier values and clears cached items", () => {
+        const builder = new LocaleBuilder(Browser.Chrome, Language.English).merge({
+            title: "Before",
+        });
+
+        const first = builder.get();
+
+        builder.merge({
+            title: "After",
+        });
+
+        const second = builder.get();
+
+        expect(second).not.toBe(first);
+        expect(second.get("title")).toBe("After");
+    });
+
+    test("returns locale keys from converted items", () => {
+        const builder = new LocaleBuilder(Browser.Chrome, Language.English).merge({
+            app: {
+                name: "My App",
+            },
+        });
+
+        expect(builder.keys()).toEqual(new Set(["app.name", LocaleCustomKeyForLanguage]));
+    });
+
+    test("normalizes substitution names in locale structure", () => {
+        const builder = new LocaleBuilder(Browser.Chrome, Language.English).merge({
+            greeting: "Hello {{ name }} {{name}} {{ count }}",
+            cars: ["{{count}} car", "{{count}} cars"],
+        });
+
+        expect(builder.structure().greeting.substitutions).toEqual(["count", "name"]);
+        expect(builder.structure().cars).toEqual({
+            plural: true,
+            substitutions: ["count"],
+        });
+    });
+
+    test("builds browser messages and validates before output", () => {
+        const validator = makeValidator();
+        const builder = new LocaleBuilder(Browser.Chrome, Language.English).setValidator(validator).merge({
+            app: {
+                name: "My App",
+            },
+        });
+
+        expect(builder.build()).toEqual({
+            app_name: {
+                message: "My App",
+            },
+            [LocaleCustomKeyForLanguage]: {
+                message: Language.English,
+            },
+        });
+
+        expect(validator.validate).toHaveBeenCalledWith(builder);
+    });
+
+    test("throws validation errors when validator is not set", () => {
+        const builder = new LocaleBuilder(Browser.Chrome, Language.English);
+
+        expect(() => builder.validate()).toThrow("Locale for chrome:en - Validator is not set");
+        expect(builder.isValid()).toBe(false);
+    });
+
+    test("reports validation status from configured validator", () => {
+        const passingValidator = makeValidator();
+        const failingValidator = makeValidator();
+
+        failingValidator.validate.mockImplementation(() => {
+            throw new Error("Invalid locale");
+        });
+
+        const passing = new LocaleBuilder(Browser.Chrome, Language.English).setValidator(passingValidator);
+        const failing = new LocaleBuilder(Browser.Chrome, Language.English).setValidator(failingValidator);
+
+        expect(passing.validate()).toBe(passing);
+        expect(passing.isValid()).toBe(true);
+        expect(failing.isValid()).toBe(false);
+    });
+});

src/cli/builders/locale/LocaleBuilder.ts

@@ -84,7 +84,7 @@ export default class LocaleBuilder implements LocaleBuilderContract {
                 substitutions.push(match[1].trim());
             }
 
-            return substitutions;
+            return _.uniq(substitutions.filter(Boolean)).sort();
         };
 
         return this.get()

src/cli/builders/locale/LocaleStructureValidator.test.ts

@@ -0,0 +1,117 @@
+import LocaleBuilder from "./LocaleBuilder";
+import LocaleStructureValidator from "./LocaleStructureValidator";
+
+import {Language, LocaleBuilders, LocaleData} from "@typing/locale";
+import {Browser} from "@typing/browser";
+
+const makeBuilder = (lang: Language, data: LocaleData): LocaleBuilder => {
+    return new LocaleBuilder(Browser.Chrome, lang).merge(data);
+};
+
+const makeBuilders = (items: Array<[Language, LocaleData]>): LocaleBuilders => {
+    return new Map(items.map(([lang, data]) => [lang, makeBuilder(lang, data)]));
+};
+
+describe("LocaleStructureValidator", () => {
+    let consoleWarnSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+        consoleWarnSpy = jest.spyOn(console, "warn").mockImplementation();
+    });
+
+    afterEach(() => {
+        consoleWarnSpy.mockRestore();
+    });
+
+    test("allows non-default locales to omit default locale keys", () => {
+        const builders = makeBuilders([
+            [
+                Language.English,
+                {
+                    app: {
+                        name: "My App",
+                        greeting: "Hello {{name}}",
+                    },
+                },
+            ],
+            [
+                Language.French,
+                {
+                    app: {
+                        name: "Mon App",
+                    },
+                },
+            ],
+        ]);
+
+        const validator = new LocaleStructureValidator(Language.English);
+
+        expect(validator.validate(builders)).toBe(validator);
+        expect(validator.isValid(builders)).toBe(true);
+    });
+
+    test("rejects missing default locale", () => {
+        const builders = makeBuilders([
+            [
+                Language.French,
+                {
+                    app: {
+                        name: "Mon App",
+                    },
+                },
+            ],
+        ]);
+
+        expect(() => new LocaleStructureValidator(Language.English).validate(builders)).toThrow(
+            'Default locale "en" not found in available translations. Available languages: fr'
+        );
+    });
+
+    test("warns about keys outside the default locale contract", () => {
+        const builders = makeBuilders([
+            [Language.English, {app: {name: "My App"}}],
+            [Language.French, {app: {name: "Mon App", extra: "Extra"}}],
+        ]);
+
+        const validator = new LocaleStructureValidator(Language.English);
+
+        expect(validator.validate(builders)).toBe(validator);
+        expect(consoleWarnSpy).toHaveBeenCalledWith(
+            'Locale "fr" contains unknown key "app.extra" not found in default locale "en"'
+        );
+        expect(validator.isValid(builders)).toBe(true);
+    });
+
+    test("rejects substitution mismatch against the default locale contract", () => {
+        const builders = makeBuilders([
+            [Language.English, {app: {greeting: "Hello {{ name }}"}}],
+            [Language.French, {app: {greeting: "Bonjour {{firstName}}"}}],
+        ]);
+
+        const validator = new LocaleStructureValidator(Language.English);
+
+        expect(() => validator.validate(builders)).toThrow(
+            'Locale "fr" key "app.greeting" substitutions [firstName] must match default locale "en" substitutions [name]'
+        );
+        expect(validator.isValid(builders)).toBe(false);
+    });
+
+    test("rejects plural mismatch against the default locale contract", () => {
+        const builders = makeBuilders([
+            [Language.English, {app: {cars: ["car", "cars"]}}],
+            [Language.French, {app: {cars: "voiture"}}],
+        ]);
+
+        expect(() => new LocaleStructureValidator(Language.English).validate(builders)).toThrow(
+            'Locale "fr" key "app.cars" must be plural like default locale "en"'
+        );
+    });
+
+    test("allows empty builder collection", () => {
+        const builders: LocaleBuilders = new Map();
+        const validator = new LocaleStructureValidator(Language.English);
+
+        expect(validator.validate(builders)).toBe(validator);
+        expect(validator.isValid(builders)).toBe(true);
+    });
+});