@praxisjs/store 1.2.3 → 1.3.0

package/dist/decorators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAI9B,qGAAqG;AACrG,qBAAa,aAAc,YAAW,YAAY;IAChD,WAAW,UAAS;CACrB;AAED,wBAAgB,QAAQ,KAEpB,aAAa,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,aAAa,EACtD,UAAU,qBAAqB,KAC9B,IAAI,CAGR;AAED,wBAAgB,KAAK,CAAC,CAAC,SAAS,aAAa,EAAE,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,CAKzE;AAED,wBAAgB,KAAK,CAAC,gBAAgB,EAAE,UAAU,OAAO,GAYtC,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,0BAA0B,CAAC,GAAG,CAAC,KAAK,IAAI,CACvF"}
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQrD,qGAAqG;AACrG,qBAAa,aAAc,YAAW,YAAY;IAChD,WAAW,UAAS;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,IAElD,aAAa,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,aAAa,EACtD,UAAU,qBAAqB,KAC9B,IAAI,CAMR;AAED,wBAAgB,KAAK,CAAC,CAAC,SAAS,aAAa,EAAE,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,CAUzE;AAED,wBAAgB,KAAK,CAAC,gBAAgB,EAAE,UAAU,OAAO,GAYtC,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,0BAA0B,CAAC,GAAG,CAAC,KAAK,IAAI,CACvF"}

package/dist/decorators.js

@@ -1,19 +1,29 @@
 import { createFieldDecorator, } from "@praxisjs/decorators";
+import { applyPluginsToStore } from "./apply-plugins.js";
+import { getGlobalPlugins } from "./plugin-registry.js";
 const storeRegistry = new Map();
+const storePluginsMap = new WeakMap();
 /** Base class for store classes. Extend this to enable `@State` and `@DeepState` on store fields. */
 export class ReactiveStore {
     constructor() {
         this._stateDirty = false;
     }
 }
-export function Storable() {
+export function Storable(options = {}) {
     return function (constructor, _context) {
         storeRegistry.set(constructor, null);
+        if (options.plugins?.length) {
+            storePluginsMap.set(constructor, options.plugins);
+        }
     };
 }
 export function store(StoreClass) {
     if (!storeRegistry.has(StoreClass) || storeRegistry.get(StoreClass) === null) {
-        storeRegistry.set(StoreClass, new StoreClass());
+        const instance = new StoreClass();
+        const perStore = storePluginsMap.get(StoreClass) ?? [];
+        const plugins = [...getGlobalPlugins(), ...perStore];
+        const wrapped = applyPluginsToStore(instance, StoreClass.name, plugins);
+        storeRegistry.set(StoreClass, wrapped);
     }
     return storeRegistry.get(StoreClass);
 }

package/dist/decorators.js.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,GAGrB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,aAAa,GAAG,IAAI,GAAG,EAAgD,CAAC;AAE9E,qGAAqG;AACrG,MAAM,OAAO,aAAa;IAA1B;QACE,gBAAW,GAAG,KAAK,CAAC;IACtB,CAAC;CAAA;AAED,MAAM,UAAU,QAAQ;IACtB,OAAO,UACL,WAAsD,EACtD,QAA+B;QAE/B,aAAa,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,KAAK,CAA0B,UAAuB;IACpE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;QAC7E,aAAa,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,UAAU,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,aAAa,CAAC,GAAG,CAAC,UAAU,CAAM,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,gBAAmC;IACvD,OAAO,oBAAoB,CAAC;QAC1B,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,aAAa;YAClC,OAAO;gBACL,UAAU,EAAE;oBACV,GAAG;wBACD,OAAO,KAAK,CAAC,gBAA2C,CAAC,CAAC;oBAC5D,CAAC;iBACF;aACF,CAAC;QACJ,CAAC;QACH,8DAA8D;KAC7D,CAAqF,CAAC;AACzF,CAAC"}
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,GAGrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAIxD,MAAM,aAAa,GAAG,IAAI,GAAG,EAAgD,CAAC;AAC9E,MAAM,eAAe,GAAG,IAAI,OAAO,EAGhC,CAAC;AAEJ,qGAAqG;AACrG,MAAM,OAAO,aAAa;IAA1B;QACE,gBAAW,GAAG,KAAK,CAAC;IACtB,CAAC;CAAA;AAMD,MAAM,UAAU,QAAQ,CAAC,UAA2B,EAAE;IACpD,OAAO,UACL,WAAsD,EACtD,QAA+B;QAE/B,aAAa,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACrC,IAAI,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;YAC5B,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QACpD,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,KAAK,CAA0B,UAAuB;IACpE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;QAC7E,MAAM,QAAQ,GAAG,IAAI,UAAU,EAAE,CAAC;QAClC,MAAM,QAAQ,GACZ,eAAe,CAAC,GAAG,CAAC,UAAuD,CAAC,IAAI,EAAE,CAAC;QACrF,MAAM,OAAO,GAAG,CAAC,GAAG,gBAAgB,EAAE,EAAE,GAAG,QAAQ,CAAC,CAAC;QACrD,MAAM,OAAO,GAAG,mBAAmB,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxE,aAAa,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,aAAa,CAAC,GAAG,CAAC,UAAU,CAAM,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,gBAAmC;IACvD,OAAO,oBAAoB,CAAC;QAC1B,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,aAAa;YAClC,OAAO;gBACL,UAAU,EAAE;oBACV,GAAG;wBACD,OAAO,KAAK,CAAC,gBAA2C,CAAC,CAAC;oBAC5D,CAAC;iBACF;aACF,CAAC;QACJ,CAAC;QACH,8DAA8D;KAC7D,CAAqF,CAAC;AACzF,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,5 @@
-export { Storable, Store, store, ReactiveStore } from "./decorators";
+export { Storable, Store, store, ReactiveStore } from "./decorators.js";
+export type { StorableOptions } from "./decorators.js";
+export { useStorePlugin, clearPlugins } from "./plugin-registry.js";
+export type { StorePlugin, StoreMutation, StoreActionContext, StoreActionResult, StoreInitContext, } from "./plugin-types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACxE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpE,YAAY,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
-export { Storable, Store, store, ReactiveStore } from "./decorators";
+export { Storable, Store, store, ReactiveStore } from "./decorators.js";
+export { useStorePlugin, clearPlugins } from "./plugin-registry.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAExE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/plugin-registry.d.ts

@@ -0,0 +1,5 @@
+import type { StorePlugin } from "./plugin-types.js";
+export declare function useStorePlugin(plugin: StorePlugin): void;
+export declare function getGlobalPlugins(): StorePlugin[];
+export declare function clearPlugins(): void;
+//# sourceMappingURL=plugin-registry.d.ts.map

package/dist/plugin-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../src/plugin-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAExD;AAED,wBAAgB,gBAAgB,IAAI,WAAW,EAAE,CAEhD;AAED,wBAAgB,YAAY,IAAI,IAAI,CAEnC"}

package/dist/plugin-registry.js

@@ -0,0 +1,11 @@
+const globalRegistry = [];
+export function useStorePlugin(plugin) {
+    globalRegistry.push(plugin);
+}
+export function getGlobalPlugins() {
+    return globalRegistry.slice();
+}
+export function clearPlugins() {
+    globalRegistry.length = 0;
+}
+//# sourceMappingURL=plugin-registry.js.map

package/dist/plugin-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-registry.js","sourceRoot":"","sources":["../src/plugin-registry.ts"],"names":[],"mappings":"AAEA,MAAM,cAAc,GAAkB,EAAE,CAAC;AAEzC,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,CAAC,KAAK,EAAE,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5B,CAAC"}

package/dist/plugin-types.d.ts

@@ -0,0 +1,28 @@
+export interface StoreMutation {
+    key: string;
+    value: unknown;
+    prevValue: unknown;
+    storeName: string;
+}
+export interface StoreActionContext {
+    name: string;
+    args: unknown[];
+    storeName: string;
+}
+export interface StoreActionResult extends StoreActionContext {
+    result: unknown;
+    error?: unknown;
+}
+export interface StoreInitContext {
+    store: Record<string, unknown>;
+    storeName: string;
+    extend(props: Record<string, unknown>): void;
+}
+export interface StorePlugin {
+    name: string;
+    onInit?(context: StoreInitContext): void;
+    onMutation?(mutation: StoreMutation): void;
+    onAction?(context: StoreActionContext): void;
+    onActionDone?(result: StoreActionResult): void;
+}
+//# sourceMappingURL=plugin-types.d.ts.map

package/dist/plugin-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-types.d.ts","sourceRoot":"","sources":["../src/plugin-types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,UAAU,CAAC,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC7C,YAAY,CAAC,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAChD"}

package/dist/plugin-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin-types.js.map

package/dist/plugin-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-types.js","sourceRoot":"","sources":["../src/plugin-types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisjs/store",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -14,8 +14,8 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@praxisjs/core": "1.7.0",
-    "@praxisjs/decorators": "1.2.0"
+    "@praxisjs/core": "1.8.0",
+    "@praxisjs/decorators": "1.3.0"
   },
   "scripts": {
     "build": "tsc",

package/src/__tests__/plugins.test.ts

@@ -0,0 +1,445 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+import { clearPlugins, useStorePlugin } from "../plugin-registry";
+import { createStore } from "../create-store";
+import { Storable, store, ReactiveStore } from "../decorators";
+import type { StorePlugin, StoreMutation, StoreActionResult } from "../plugin-types";
+
+// Isolate global plugins between tests
+beforeEach(() => clearPlugins());
+
+// ── createStore — per-store plugins ──────────────────────────────────────────
+
+describe("createStore — per-store plugins (options.plugins)", () => {
+  it("onInit receives storeName and store reference", () => {
+    const ctx: { storeName?: string; store?: unknown } = {};
+    const plugin: StorePlugin = {
+      name: "p",
+      onInit(context) { ctx.storeName = context.storeName; ctx.store = context.store; },
+    };
+
+    createStore({ count: 0 }, { name: "counter", plugins: [plugin] });
+    expect(ctx.storeName).toBe("counter");
+    expect(ctx.store).toBeDefined();
+  });
+
+  it("storeName defaults to 'anonymous' when not provided", () => {
+    let received = "";
+    createStore({ count: 0 }, { plugins: [{ name: "p", onInit({ storeName }) { received = storeName; } }] });
+    expect(received).toBe("anonymous");
+  });
+
+  it("onMutation fires when a signal is set", () => {
+    const mutations: StoreMutation[] = [];
+    const s = createStore({ count: 0 }, {
+      name: "counter",
+      plugins: [{ name: "p", onMutation(m) { mutations.push(m); } }],
+    })();
+
+    (s as unknown as { count: number }).count = 5;
+
+    expect(mutations).toHaveLength(1);
+    expect(mutations[0]).toMatchObject({ key: "count", value: 5, prevValue: 0, storeName: "counter" });
+  });
+
+  it("onMutation fires per key when $patch is called", () => {
+    const keys: string[] = [];
+    const s = createStore({ a: 1, b: 2 }, {
+      name: "s",
+      plugins: [{ name: "p", onMutation({ key }) { keys.push(key); } }],
+    })();
+
+    (s as unknown as { $patch: (p: Record<string, unknown>) => void }).$patch({ a: 10, b: 20 });
+    expect(keys).toContain("a");
+    expect(keys).toContain("b");
+  });
+
+  it("onMutation does NOT fire for $reset", () => {
+    const mutations: string[] = [];
+    const s = createStore({ count: 0 }, {
+      plugins: [{ name: "p", onMutation({ key }) { mutations.push(key); } }],
+    })();
+
+    (s as unknown as { count: number }).count = 99;
+    mutations.length = 0;
+    (s as unknown as { $reset: () => void }).$reset();
+    expect(mutations).toHaveLength(0);
+  });
+
+  it("onAction fires before the method; onActionDone fires after", () => {
+    const log: string[] = [];
+    const s = createStore({
+      count: 0,
+      increment() { log.push("run"); (this as unknown as { count: number }).count++; },
+    }, {
+      name: "s",
+      plugins: [{
+        name: "p",
+        onAction({ name }) { log.push(`before:${name}`); },
+        onActionDone({ name, result }) { log.push(`done:${name}:${String(result)}`); },
+      }],
+    })();
+
+    (s as unknown as { increment: () => void }).increment();
+    expect(log).toEqual(["before:increment", "run", "done:increment:undefined"]);
+  });
+
+  it("onActionDone resolves with value for async actions", async () => {
+    const results: StoreActionResult[] = [];
+    const s = createStore(
+      { async fetch() { return 42; } },
+      { plugins: [{ name: "p", onActionDone(r) { results.push(r); } }] },
+    )();
+
+    await (s as unknown as { fetch: () => Promise<number> }).fetch();
+    expect(results[0].result).toBe(42);
+    expect(results[0].error).toBeUndefined();
+  });
+
+  it("onActionDone receives error when async action rejects", async () => {
+    const results: StoreActionResult[] = [];
+    const boom = new Error("boom");
+    const s = createStore(
+      { async fail() { throw boom; } },
+      { plugins: [{ name: "p", onActionDone(r) { results.push(r); } }] },
+    )();
+
+    await expect((s as unknown as { fail: () => Promise<void> }).fail()).rejects.toThrow("boom");
+    expect(results[0].error).toBe(boom);
+    expect(results[0].result).toBeUndefined();
+  });
+
+  it("onInit extend() adds properties to the store", () => {
+    const s = createStore({ count: 0 }, {
+      plugins: [{
+        name: "p",
+        onInit({ extend }) { extend({ $version: "2.0" }); },
+      }],
+    })();
+
+    expect((s as unknown as { $version: string }).$version).toBe("2.0");
+  });
+
+  it("extended functions are bound to the store proxy", () => {
+    let capturedStore: unknown;
+    const s = createStore({ count: 0 }, {
+      plugins: [{
+        name: "p",
+        onInit({ extend }) {
+          extend({ $self(this: unknown) { capturedStore = this; } });
+        },
+      }],
+    })();
+
+    (s as unknown as { $self: () => void }).$self();
+    expect(capturedStore).toBe(s);
+  });
+
+  it("multiple per-store plugins run in order", () => {
+    const log: string[] = [];
+    const s = createStore({ x: 0 }, {
+      plugins: [
+        { name: "a", onMutation() { log.push("a"); } },
+        { name: "b", onMutation() { log.push("b"); } },
+      ],
+    })();
+
+    (s as unknown as { x: number }).x = 1;
+    expect(log).toEqual(["a", "b"]);
+  });
+
+  it("$subscribe, $reset, $patch, $state are NOT tracked as actions", () => {
+    const actions: string[] = [];
+    const s = createStore({ count: 0 }, {
+      plugins: [{ name: "p", onAction({ name }) { actions.push(name); } }],
+    })();
+
+    (s as unknown as { $state: () => unknown }).$state();
+    (s as unknown as { $patch: (p: Record<string, unknown>) => void }).$patch({ count: 1 });
+    (s as unknown as { $reset: () => void }).$reset();
+    expect(actions).toHaveLength(0);
+  });
+
+  it("no plugins — store behaves identically to baseline", () => {
+    const s = createStore({ count: 0, increment() { (this as unknown as { count: number }).count++; } })();
+    (s as unknown as { increment: () => void }).increment();
+    expect(s.count).toBe(1);
+  });
+});
+
+// ── createStore — global plugins ─────────────────────────────────────────────
+
+describe("createStore — global plugins (useStorePlugin)", () => {
+  it("global plugin fires for any store created after registration", () => {
+    const storenames: string[] = [];
+    useStorePlugin({ name: "g", onInit({ storeName }) { storenames.push(storeName); } });
+
+    createStore({ x: 0 }, { name: "alpha" });
+    createStore({ y: 0 }, { name: "beta" });
+    expect(storenames).toEqual(["alpha", "beta"]);
+  });
+
+  it("global + per-store plugins both fire: global first", () => {
+    const log: string[] = [];
+    useStorePlugin({ name: "global", onMutation() { log.push("global"); } });
+
+    const s = createStore({ x: 0 }, {
+      plugins: [{ name: "local", onMutation() { log.push("local"); } }],
+    })();
+
+    (s as unknown as { x: number }).x = 1;
+    expect(log).toEqual(["global", "local"]);
+  });
+
+  it("plugin registered after createStore does NOT receive events", () => {
+    const mutations: number[] = [];
+    const s = createStore({ x: 0 }, { name: "s" })();
+    useStorePlugin({ name: "late", onMutation() { mutations.push(1); } });
+
+    (s as unknown as { x: number }).x = 5;
+    expect(mutations).toHaveLength(0);
+  });
+});
+
+// ── class-based stores — per-store plugins ────────────────────────────────────
+
+describe("@Storable({ plugins }) — per-store plugins", () => {
+  it("onInit receives the class name as storeName", () => {
+    let received = "";
+    class SessionStore extends ReactiveStore { token = ""; }
+    Storable({ plugins: [{ name: "p", onInit({ storeName }) { received = storeName; } }] })(
+      SessionStore, {} as ClassDecoratorContext,
+    );
+    store(SessionStore);
+    expect(received).toBe("SessionStore");
+  });
+
+  it("onMutation fires when a property is set on the singleton", () => {
+    const mutations: StoreMutation[] = [];
+    class FlagsStore extends ReactiveStore { enabled = false; }
+    Storable({ plugins: [{ name: "p", onMutation(m) { mutations.push(m); } }] })(
+      FlagsStore, {} as ClassDecoratorContext,
+    );
+
+    const s = store(FlagsStore);
+    s.enabled = true;
+
+    const m = mutations.find((x) => x.key === "enabled");
+    expect(m?.value).toBe(true);
+    expect(m?.prevValue).toBe(false);
+    expect(m?.storeName).toBe("FlagsStore");
+  });
+
+  it("onAction and onActionDone fire for store methods", () => {
+    const log: string[] = [];
+    class CounterStore2 extends ReactiveStore {
+      count = 0;
+      increment() { this.count++; }
+    }
+    Storable({
+      plugins: [{
+        name: "p",
+        onAction({ name }) { log.push(`before:${name}`); },
+        onActionDone({ name }) { log.push(`done:${name}`); },
+      }],
+    })(CounterStore2, {} as ClassDecoratorContext);
+
+    store(CounterStore2).increment();
+    expect(log).toContain("before:increment");
+    expect(log).toContain("done:increment");
+  });
+
+  it("onInit extend() — non-function value is returned directly", () => {
+    class TagStore extends ReactiveStore {}
+    Storable({ plugins: [{ name: "p", onInit({ extend }) { extend({ $tag: "ok" }); } }] })(
+      TagStore, {} as ClassDecoratorContext,
+    );
+
+    expect((store(TagStore) as unknown as { $tag: string }).$tag).toBe("ok");
+  });
+
+  it("onInit extend() — function value is bound to the proxy", () => {
+    let capturedThis: unknown;
+    class SelfStore extends ReactiveStore {}
+    Storable({
+      plugins: [{
+        name: "p",
+        onInit({ extend }) {
+          extend({ $self(this: unknown) { capturedThis = this; } });
+        },
+      }],
+    })(SelfStore, {} as ClassDecoratorContext);
+
+    const s = store(SelfStore);
+    (s as unknown as { $self(): void }).$self();
+    expect(capturedThis).toBe(s);
+  });
+
+  it("onMutation does NOT fire when Reflect.set returns false (non-writable property)", () => {
+    const mutations: string[] = [];
+    class ReadonlyStore extends ReactiveStore {
+      get fixed() { return 42; }
+    }
+    Storable({ plugins: [{ name: "p", onMutation({ key }) { mutations.push(key); } }] })(
+      ReadonlyStore, {} as ClassDecoratorContext,
+    );
+
+    const s = store(ReadonlyStore);
+    // `fixed` has no setter — Reflect.set returns false, onMutation must NOT fire
+    Reflect.set(s as object, "fixed", 99);
+    expect(mutations).not.toContain("fixed");
+  });
+
+  it("$-prefixed methods are NOT tracked as actions", () => {
+    const actions: string[] = [];
+    class OpStore extends ReactiveStore {
+      value = 0;
+      $internal() { this.value = 1; }
+    }
+    Storable({ plugins: [{ name: "p", onAction({ name }) { actions.push(name); } }] })(
+      OpStore, {} as ClassDecoratorContext,
+    );
+    store(OpStore).$internal();
+    expect(actions).not.toContain("$internal");
+  });
+
+  it("onActionDone fires with resolved value for async methods (lines 30-35 in apply-plugins)", async () => {
+    const results: StoreActionResult[] = [];
+    class AsyncStore extends ReactiveStore {
+      async fetch() { return 99; }
+    }
+    Storable({ plugins: [{ name: "p", onActionDone(r) { results.push(r); } }] })(
+      AsyncStore, {} as ClassDecoratorContext,
+    );
+
+    await store(AsyncStore).fetch();
+    expect(results[0].result).toBe(99);
+    expect(results[0].error).toBeUndefined();
+  });
+
+  it("onActionDone fires with error when async method rejects (lines 36-39 in apply-plugins)", async () => {
+    const results: StoreActionResult[] = [];
+    const boom = new Error("async-fail");
+    class FailStore extends ReactiveStore {
+      async fail() { throw boom; }
+    }
+    Storable({ plugins: [{ name: "p", onActionDone(r) { results.push(r); } }] })(
+      FailStore, {} as ClassDecoratorContext,
+    );
+
+    await expect(store(FailStore).fail()).rejects.toThrow("async-fail");
+    expect(results[0].error).toBe(boom);
+    expect(results[0].result).toBeUndefined();
+  });
+
+  it("setting a symbol key on the proxy is a no-op and returns true (lines 53-54 in apply-plugins)", () => {
+    class SymStore extends ReactiveStore { value = 0; }
+    Storable({ plugins: [{ name: "p", onMutation() { /* intentionally empty */ } }] })(
+      SymStore, {} as ClassDecoratorContext,
+    );
+
+    const s = store(SymStore);
+    const sym = Symbol("test");
+    expect(() => {
+      (s as unknown as Record<symbol, unknown>)[sym] = "ignored";
+    }).not.toThrow();
+    expect((s as unknown as Record<symbol, unknown>)[sym]).toBe("ignored");
+  });
+
+  it("no plugins — class-based store works identically to baseline", () => {
+    class BareStore extends ReactiveStore { value = 7; }
+    Storable()(BareStore, {} as ClassDecoratorContext);
+    const s = store(BareStore);
+    s.value = 42;
+    expect(s.value).toBe(42);
+  });
+});
+
+// ── class-based stores — global plugins ───────────────────────────────────────
+
+describe("class-based store — global plugins", () => {
+  it("global plugin fires for class-based stores", () => {
+    const names: string[] = [];
+    useStorePlugin({ name: "g", onInit({ storeName }) { names.push(storeName); } });
+
+    class GlobalTestStore extends ReactiveStore {}
+    Storable()(GlobalTestStore, {} as ClassDecoratorContext);
+    store(GlobalTestStore);
+
+    expect(names).toContain("GlobalTestStore");
+  });
+
+  it("global + per-store plugins both fire: global first", () => {
+    const log: string[] = [];
+    useStorePlugin({ name: "global", onMutation() { log.push("global"); } });
+
+    class MixStore extends ReactiveStore { x = 0; }
+    Storable({ plugins: [{ name: "local", onMutation() { log.push("local"); } }] })(
+      MixStore, {} as ClassDecoratorContext,
+    );
+
+    store(MixStore).x = 1;
+    expect(log).toEqual(["global", "local"]);
+  });
+});
+
+// ── real-world plugin patterns ────────────────────────────────────────────────
+
+describe("built-in plugin patterns", () => {
+  it("logger plugin: records mutations and action calls", () => {
+    const log: string[] = [];
+    const logger: StorePlugin = {
+      name: "logger",
+      onMutation({ storeName, key, value }) {
+        log.push(`[${storeName}] ${key} = ${JSON.stringify(value)}`);
+      },
+      onAction({ storeName, name }) {
+        log.push(`[${storeName}] ${name}()`);
+      },
+    };
+
+    const s = createStore({
+      count: 0,
+      increment() { (this as unknown as { count: number }).count++; },
+    }, { name: "counter", plugins: [logger] })();
+
+    (s as unknown as { increment: () => void }).increment();
+    expect(log).toContain("[counter] increment()");
+    expect(log).toContain('[counter] count = 1');
+  });
+
+  it("persistence plugin: restores state onInit and saves onMutation", () => {
+    const storage: Record<string, unknown> = { count: 99 };
+    let savedCount: unknown;
+
+    const persistPlugin: StorePlugin = {
+      name: "persist",
+      onInit({ store: s, storeName }) {
+        if (storeName === "counter" && typeof storage.count === "number") {
+          (s as { count: number }).count = storage.count as number;
+        }
+      },
+      onMutation({ key, value }) {
+        if (key === "count") savedCount = value;
+      },
+    };
+
+    const s = createStore({ count: 0 }, { name: "counter", plugins: [persistPlugin] })();
+    expect((s as unknown as { count: number }).count).toBe(99);
+
+    (s as unknown as { count: number }).count = 55;
+    expect(savedCount).toBe(55);
+  });
+
+  it("spy plugin: action wrapping does not break return values", () => {
+    const spy = vi.fn();
+    const s = createStore(
+      { double(n: unknown) { return (n as number) * 2; } },
+      { plugins: [{ name: "spy", onActionDone({ name, result }) { spy(name, result); } }] },
+    )();
+
+    const result = (s as unknown as { double: (n: number) => number }).double(5);
+    expect(result).toBe(10);
+    expect(spy).toHaveBeenCalledWith("double", 10);
+  });
+});