pinia-plugin-subscription 0.2.0-beta.0 → 0.2.1

package/dist/types/store.d.ts

@@ -1,8 +1,34 @@
 import type { AnyObject } from ".";
 import type { CreateStateSnapshotKeys } from "./plugin";
-import type { PiniaCustomProperties, Store, StoreDefinition } from "pinia";
+import type { Pinia, PiniaCustomProperties, StateTree, Store, StoreDefinition, StoreGeneric } from "pinia";
 import type { Ref } from "vue";
 export type CustomStore<TStore, TState> = Store & TStore & TState & PiniaCustomProperties & StoreDefinition;
+/**
+ * Store definition returned by `defineAStore`/`defineAStoreCtx` when explicit
+ * store/state types are provided, e.g. for stores augmented by plugins with
+ * members not returned by the setup function.
+ *
+ * The call signature exposes `TStore` (actions/getters) and `TState` (state)
+ * with precise typings so IDEs list store members and display action
+ * prototypes. It extends pinia's `StoreDefinition` to stay assignable
+ * wherever a standard store definition is expected.
+ */
+export interface DefineAStoreDefinition<TStore, TState, Id extends string = string> extends StoreDefinition<Id, StrictStateTree<TState>> {
+    /**
+     * Returns a store, creates it if necessary.
+     *
+     * @param pinia - Pinia instance to retrieve the store
+     * @param hot - dev only hot module replacement
+     */
+    (pinia?: Pinia | null, hot?: StoreGeneric): Store<Id, StrictStateTree<TState>> & TStore;
+}
+/**
+ * Maps a state interface to a pinia `StateTree` without intersecting it with
+ * `StateTree` itself, whose `any` index signature would widen every store member to `any`.
+ */
+export type StrictStateTree<TState> = {
+    [K in keyof TState]: TState[K];
+} extends infer S extends StateTree ? S : never;
 export type EmptyExtensions = Record<never, never>;
 export interface DefineAStoreSetupExtensions<TEnhancedStore> {
     /**
@@ -30,7 +56,18 @@ export type RollbackAfterFailureParams = {
 };
 export type StatePropertyValue = StdStatePropertyValue | Ref<StdStatePropertyValue> | StdStatePropertyValue[] | Ref<StdStatePropertyValue[]> | Ref<StdStatePropertyValue>[];
 type StdStatePropertyValue = AnyObject | boolean | null | number | string | undefined;
-export interface StoreOptions {
+/**
+ * Centralized extension point for per-store plugin options.
+ *
+ * Subscriber plugins MUST NOT redeclare pinia's `DefineStoreOptionsBase`:
+ * merging a `storeOptions` property with a different (even compatible) type
+ * raises TS2717 in consumer code. Instead, they augment this interface via
+ * `declare module 'pinia-plugin-subscription/types'`, which merges safely as
+ * long as each plugin declares its own optional keys.
+ */
+export interface StoreOptionsExtensions {
+}
+export interface StoreOptions extends StoreOptionsExtensions {
     [key: string]: StoreOptionsPropertyValue;
     rollbackAfterFailure?: RollbackAfterFailureParams;
 }

package/dist/utils/deep-clone.d.ts

@@ -1 +1,7 @@
+/**
+ * Deeply clones the provided value, handling objects, arrays, maps, and sets. Uses `structuredClone` if available, otherwise falls back to a manual deep clone.
+ * @template T The type of the value to deep clone.
+ * @param value The value to deep clone.
+ * @returns A deep clone of the provided value.
+ */
 export declare function deepClone<T>(value: T): T;

package/dist/utils/store.d.ts

@@ -1,25 +1,94 @@
-import type { DefineStoreOptions, StateTree, Store, StoreDefinition } from "pinia";
+import type { DefineStoreOptions, SetupStoreDefinition, StateTree, Store, StoreDefinition, _GettersTree } from "pinia";
 import type { AnyObject } from "../types";
-import type { DefineAStoreSetupContext, EmptyExtensions, PluginStoreOptions, StoreOptions } from "../types/store";
+import type { DefineAStoreDefinition, DefineAStoreSetupContext, EmptyExtensions, PluginStoreOptions, StoreOptions } from "../types/store";
 export declare const itemState: {
     '@id': undefined;
     id: undefined;
 };
-type DefineAStoreSetup<TEnhancedStore, TExtraExtensions extends Record<string, unknown> = EmptyExtensions> = (ctx: DefineAStoreSetupContext<TEnhancedStore, TExtraExtensions>) => AnyObject;
-export declare function defineAStore<Sto, Sta>(id: string, storeDefinition: Omit<DefineStoreOptions<string, StateTree & Sta, AnyObject, Partial<Sto>>, 'id'> | ((ctx?: DefineAStoreSetupContext<AnyObject>) => AnyObject), options?: StoreOptions): StoreDefinition & Sta & Sto;
-export declare function defineAStoreCtx<Sto, Sta, TExtraExtensions extends Record<string, unknown> = EmptyExtensions>(id: string, storeDefinition: DefineAStoreSetup<Sto & Sta, TExtraExtensions>, options?: StoreOptions): StoreDefinition & Sta & Sto;
-export declare function defineAStoreSetup(id: string, storeDefinition: DefineAStoreSetup<AnyObject>, options: PluginStoreOptions): StoreDefinition<string, Pick<AnyObject, keyof AnyObject>, Pick<AnyObject, keyof AnyObject>, Pick<AnyObject, keyof AnyObject>>;
-export declare function defineAStoreOptionApi(id: string, storeDefinition: AnyObject, options?: PluginStoreOptions): StoreDefinition<string, {}, {}, {}>;
+type DefineAStoreSetup<SS, TExtraExtensions extends Record<string, unknown> = EmptyExtensions> = (ctx: DefineAStoreSetupContext<SS, TExtraExtensions>) => SS;
+/**
+ * Define a store with the setup API. State, getters and actions are inferred
+ * from the setup function return, exactly like pinia's `defineStore`, so
+ * store members are listed by IDEs and action prototypes are preserved.
+ * @template Id The type of the store identifier.
+ * @template SS The type of the setup function return.
+ * @param id The unique identifier for the store.
+ * @param storeDefinition The setup function defining the store.
+ * @param options Optional store options.
+ * @returns The defined store.
+ */
+export declare function defineAStore<Id extends string, SS>(id: Id, storeDefinition: (ctx?: DefineAStoreSetupContext<AnyObject>) => SS, options?: StoreOptions): SetupStoreDefinition<Id, SS>;
+/**
+ * Define a store with the options API, mirroring pinia's `defineStore` inference.
+ * @template Id The type of the store identifier.
+ * @template S The type of the store's state.
+ * @template G The type of the store's getters.
+ * @template A The type of the store's actions.
+ * @param id The unique identifier for the store.
+ * @param storeDefinition The store options definition.
+ * @param options Optional store options.
+ * @returns The defined store.
+ */
+export declare function defineAStore<Id extends string, S extends StateTree = {}, G extends _GettersTree<S> = {}, A = {}>(id: Id, storeDefinition: Omit<DefineStoreOptions<Id, S, G, A>, 'id'>, options?: StoreOptions): StoreDefinition<Id, S, G, A>;
+/**
+ * Define a store with explicit store/state types, e.g. when plugins augment
+ * the store with members not returned by the setup function.
+ * @template Sto The type of the store.
+ * @template Sta The type of the store's state.
+ * @param id The unique identifier for the store.
+ * @param storeDefinition The store definition, either as an options object or a setup function.
+ * @param options Optional store options.
+ * @returns The defined store.
+ */
+export declare function defineAStore<Sto, Sta>(id: string, storeDefinition: Omit<DefineStoreOptions<string, StateTree & Sta, AnyObject, Partial<Sto>>, 'id'> | ((ctx?: DefineAStoreSetupContext<Sto & Sta>) => AnyObject), options?: StoreOptions): DefineAStoreDefinition<Sto, Sta>;
+/**
+ * Define a store with a required, fully typed setup context. State, getters
+ * and actions are inferred from the setup function return.
+ * @template Id The type of the store identifier.
+ * @template SS The type of the setup function return.
+ * @template TExtraExtensions The type of the store's extra extensions.
+ * @param id The unique identifier for the store.
+ * @param storeDefinition The setup function defining the store.
+ * @param options Optional store options.
+ * @returns The defined store with setup context.
+ */
+export declare function defineAStoreCtx<Id extends string, SS, TExtraExtensions extends Record<string, unknown> = EmptyExtensions>(id: Id, storeDefinition: (ctx: DefineAStoreSetupContext<AnyObject, TExtraExtensions>) => SS, options?: StoreOptions): SetupStoreDefinition<Id, SS>;
+/**
+ * Define a store with a setup context and explicit store/state types, e.g.
+ * when plugins augment the store with members not returned by the setup function.
+ * @template Sto The type of the store.
+ * @template Sta The type of the store's state.
+ * @template TExtraExtensions The type of the store's extra extensions.
+ * @param id The unique identifier for the store.
+ * @param storeDefinition The setup function defining the store.
+ * @param options Optional store options.
+ * @returns The defined store with setup context.
+ */
+export declare function defineAStoreCtx<Sto, Sta, TExtraExtensions extends Record<string, unknown> = EmptyExtensions>(id: string, storeDefinition: (ctx: DefineAStoreSetupContext<Sto & Sta, TExtraExtensions>) => AnyObject, options?: StoreOptions): DefineAStoreDefinition<Sto, Sta>;
+export declare function defineAStoreSetup<Id extends string, SS>(id: Id, storeDefinition: DefineAStoreSetup<SS>, options: PluginStoreOptions): SetupStoreDefinition<Id, SS>;
+export declare function defineAStoreOptionApi<Id extends string, S extends StateTree = {}, G extends _GettersTree<S> = {}, A = {}>(id: Id, storeDefinition: Omit<DefineStoreOptions<Id, S, G, A>, 'id'>, options?: PluginStoreOptions): StoreDefinition<Id, S, G, A>;
+/**
+ * Check if a property has a denied first character : ['_', '$'].
+ * @param property The property name to check.
+ * @returns True if the property has a denied first character, false otherwise.
+ */
 export declare function hasDeniedFirstChar(property: string): boolean;
-export declare function getDefineAStoreSetupContext(store: AnyObject): DefineAStoreSetupContext<AnyObject> | undefined;
+/**
+ * Get the setup context associated with a store instance (or pending store id).
+ * @param store The store instance, or an object exposing the store `$id`.
+ * @returns The setup context when the store was defined with `enhancedStore` enabled, undefined otherwise.
+ */
+export declare function getDefineAStoreSetupContext(store: object): DefineAStoreSetupContext<AnyObject> | undefined;
 /**
  * Get the enhanced store from the context.
+ * @template TEnhancedStore The type of the enhanced store.
  * @param ctx The context containing the extensions.
  * @returns The enhanced store casted to the specified types.
  */
 export declare function getEnhancedStore<TEnhancedStore>(ctx: DefineAStoreSetupContext<TEnhancedStore>): TEnhancedStore;
 /**
  * Set the enhanced store in context with deprecated alias support.
+ * @template TEnhancedStore The type of the enhanced store.
  * @param ctx The context containing the extensions.
  * @param store The store to expose as enhancement.
  */

package/docs/authoring-plugins.md

@@ -0,0 +1,408 @@
+# Plugin authoring guide
+
+Guide for **plugin authors** building their own pinia plugin on top of
+`pinia-plugin-subscription`.
+
+If you only want to **use** compatible plugins in an application, read
+[Using compatible plugins](using-plugins.md) instead.
+
+> **Documentation convention:** JavaScript examples come first and are
+> complete and runnable as-is. TypeScript versions follow, adding type
+> annotations and generics. Types are always optional at runtime — they only
+> add autocompletion and compile-time checks.
+
+## Mental model
+
+- A **subscriber** is invoked by the central `PluginSubscription` engine
+  each time pinia registers a store.
+- A subscriber can extend the store, register callbacks (mutation
+  subscriptions, action subscriptions, reset callbacks), and declare an
+  execution policy for SSR.
+- `createPlugin([...subscribers])` aggregates subscribers into a single
+  pinia plugin.
+
+Two authoring styles are available:
+
+1. **Plain object** implementing `PluginSubscriberInterface` — lightweight,
+   no classes.
+2. **`PluginSubscriber` abstract class + `Store` subclass** — recommended
+   for richer plugins: the `Store` subclass wraps the pinia store with
+   helpers (state extension, subscriptions, debug logging).
+
+## Your first subscriber: a plain object
+
+### JavaScript
+
+```js
+export const myStoreSubscriber = {
+  name: 'my-plugin',
+
+  invoke: (context, debug) => {
+    // context contains `store`, `options`, `pinia`
+    console.log('store registered', context.store.$id)
+
+    return true
+  },
+
+  resetStoreCallback: (store) => {
+    console.log('store reset:', store.$id)
+  }
+}
+```
+
+### TypeScript
+
+```ts
+import type { PluginSubscriberInterface } from 'pinia-plugin-subscription'
+
+export const myStoreSubscriber: PluginSubscriberInterface = {
+  name: 'my-plugin',
+
+  invoke: (context, debug) => {
+    console.log('store registered', context.store.$id)
+
+    return true
+  },
+
+  resetStoreCallback: (store) => {
+    console.log('store reset:', store.$id)
+  }
+}
+```
+
+The host app registers subscribers through `createPlugin()`:
+
+```js
+import { createPlugin } from 'pinia-plugin-subscription'
+
+pinia.use(createPlugin([myStoreSubscriber]))
+```
+
+## `PluginSubscriberInterface` reference
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `name` (required) | `string` | Unique plugin name; also used by the debug filter. |
+| `invoke` (required) | `(context: PiniaPluginContext, debug: boolean) => boolean` | Called when a store is registered. Return `false` to skip the store. |
+| `execution` | `PluginExecutionOptions` | Where/when the subscriber runs — see [Execution policy & SSR](#execution-policy--ssr). |
+| `hydrationScheduler` | `(run: () => void) => void` | Custom scheduler used when hydration is deferred. |
+| `hydrate` | `(context, debug) => void \| Promise<void>` | SSR-safe initialization hook; guaranteed to run before `afterHydration`. |
+| `afterHydration` | `(context, debug) => void \| Promise<void>` | Post-hydration lifecycle hook. |
+| `resetStoreCallback` | `(store?: Store) => void` | Custom logic executed when a registered store is reset. |
+| `storeOnActionSubscription` | `{ store, callback }` (getter) | Action subscription forwarded to the returned store's `$onAction`, including after deferred hydration; removed on store disposal. |
+| `storeMutationSubscription` | `{ store, callback }` (getter) | Mutation subscription forwarded to pinia's `$subscribe`. |
+| `subscriptions` | `Record<string, PluginSubscription>` | Plugin-specific subscription functions exposed to other plugins. |
+| `console` | `Console` | Custom console used for debug logging. |
+
+All members except `name` and `invoke` are optional.
+
+## The `PluginSubscriber` abstract class
+
+For class-based plugins, extend `PluginSubscriber<Instance>`. The subscriber
+creates the instance through a factory — conventionally
+`MyPlugin.customizeStore.bind(MyPlugin)`.
+
+### Type parameter (TypeScript only)
+
+| Generic | Constraint | Role |
+| --- | --- | --- |
+| `Instance` | `extends Store` | The `Store` subclass your plugin creates for each registered store. |
+
+The generic parameter is optional — JavaScript code and untyped TypeScript
+plugins can extend the class without it. Providing it types the
+`storeInstance` getter, so overridden hooks (`hydrate()`,
+`afterHydration()`, `pluginCreated`) get full autocompletion and compile-time
+checks when they call your plugin's custom methods.
+
+Constructor:
+
+```ts
+constructor(pluginName: string, createInstance: CreateInstance, pluginConsole?: Console)
+```
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `execution` | public field | Execution policy (see below). |
+| `hydrationScheduler` | public field | Custom scheduler used when hydration is deferred. |
+| `pluginCreated` | protected field | Optional hook called with the pinia store after a successful `invoke`. |
+| `pluginOptions` | getter/setter | Extra options merged into the options passed to your `Store` factory. |
+| `storeInstance` | getter | The `Store` subclass instance created for the current store. |
+| `hydrate()` / `afterHydration()` | methods | Lifecycle stubs to override for SSR-safe initialization. |
+| `invoke()` | method | Implemented for you: creates the instance, wires `subscriptions`, `storeSubscribe` and `onAction`, then calls `pluginCreated`. Returns `false` when the factory creates no instance. |
+
+### JavaScript
+
+```js
+import { PluginSubscriber, Store } from 'pinia-plugin-subscription'
+
+class MyPlugin extends Store {
+  constructor(store, options, debug = false) {
+    super(store, options, debug)
+    this.doSomething()
+  }
+
+  doSomething() {
+    this.debugLog('doSomething', this.store.$id)
+  }
+}
+
+class MyPluginSubscriber extends PluginSubscriber {
+  constructor() {
+    super('my-plugin', (store, options, debug, customConsole) =>
+      new MyPlugin(store, options, debug, customConsole))
+  }
+}
+
+export const myStoreSubscriber = new MyPluginSubscriber()
+```
+
+### TypeScript
+
+```ts
+import { PluginSubscriber, Store } from 'pinia-plugin-subscription'
+
+class MyPlugin extends Store {
+  protected override _className: string = 'MyPlugin'
+  protected static override _requiredKeys?: string[] = ['my-plugin-option']
+
+  constructor(store, options, debug = false) {
+    super(store, options, debug)
+    this.doSomething()
+  }
+
+  doSomething(): void {
+    this.debugLog('doSomething', this.store.$id)
+  }
+}
+
+class MyPluginSubscriber extends PluginSubscriber<MyPlugin> {
+  constructor() {
+    super('my-plugin', MyPlugin.customizeStore.bind(MyPlugin))
+  }
+}
+
+export const myStoreSubscriber = new MyPluginSubscriber()
+```
+
+> **Important contract:** `Store.customizeStore()` only creates an instance
+> when the store defines `storeOptions` **and** every key listed in the
+> static `_requiredKeys` is present in those options. When no instance is
+> created, `invoke()` returns `false` and the store is skipped by your
+> plugin. Declare `_requiredKeys = []` to accept every store that defines
+> `storeOptions`.
+
+## The `Store` base class
+
+`Store` wraps a pinia store (`PiniaStore`) and exposes:
+
+**Properties:** `debug`, `options`, `state`, `store`.
+
+**Methods:**
+
+| Method | Description |
+| --- | --- |
+| `addToState(name, value?)` | Adds a property to the store state; exposed as a `Ref` for setup-style stores. |
+| `addSubscription(pluginName, subscription, options?)` | Registers a plugin-specific subscription function. |
+| `getSubscriptions()` | Returns registered subscriptions (`undefined` when empty). |
+| `getOption(optionName)` | Reads one key from the store's `StoreOptions`. |
+| `getStatePropertyValue(propertyName)` | Reads a state property, unwrapping refs. |
+| `storeSubscribe` (getter/setter) | Factory for pinia's `$subscribe` (`{ store, callback }`). |
+| `onAction` (getter/setter) | Factory for pinia's `$onAction` (`{ store, callback }`). |
+| `static customizeStore(store, options, debug?)` | Recommended factory; guarded by `_requiredKeys` (see above). |
+| `debugLog(message, args)` | Conditional logging, active in debug mode. |
+| `stateHas(property)` / `storeHas(property)` | Safe `hasOwnProperty` checks on state / store. |
+| `getValue(value)` | Unwraps a ref or returns the value as-is. |
+| `isOptionApi()` | Whether the store uses the options API. |
+| `hydrate()` / `afterHydration()` | Lifecycle stubs for SSR-safe initialization. |
+
+## Execution policy & SSR
+
+The source of truth for hydration policy stays on the subscriber itself.
+For example, a client-only plugin declares its execution directly:
+
+### JavaScript
+
+```js
+import { nextTick } from 'vue'
+
+export const persistedStateSubscriber = {
+  name: 'persisted-state',
+  execution: {
+    environment: 'client',
+    hydration: 'defer',
+  },
+  hydrationScheduler: (run) => {
+    nextTick(() => run())
+  },
+  invoke: (context, debug) => {
+    // ...
+    return true
+  }
+}
+```
+
+### TypeScript
+
+```ts
+import { nextTick } from 'vue'
+import type { PluginSubscriberInterface } from 'pinia-plugin-subscription'
+
+export const persistedStateSubscriber: PluginSubscriberInterface = {
+  name: 'persisted-state',
+  execution: {
+    environment: 'client',
+    hydration: 'defer',
+  },
+  hydrationScheduler: (run) => {
+    nextTick(() => run())
+  },
+  invoke: (context, debug) => {
+    // ...
+    return true
+  }
+}
+```
+
+Available execution options (`PluginExecutionOptions`):
+
+- `environment: 'both' | 'client' | 'server'` — controls where the
+  subscriber is allowed to run.
+- `hydration: 'immediate' | 'defer'` — on the client, `defer` schedules
+  execution after hydration.
+- `hydrationScheduler` can be provided either on a subscriber or via
+  `createHydrationPlugin()` to override the execution timing when needed.
+
+The class-based equivalent sets the same policy in the constructor and
+overrides the lifecycle hooks:
+
+```ts
+import { nextTick } from 'vue'
+import { PluginSubscriber } from 'pinia-plugin-subscription'
+
+class ExtendingStoreSubscriber extends PluginSubscriber<StoreExtension> {
+  constructor() {
+    super('extendsPiniaStore', StoreExtension.customizeStore.bind(StoreExtension))
+
+    // Controls when this subscriber may run and whether it should wait
+    // for hydration on the client.
+    this.execution = {
+      environment: 'client',
+      hydration: 'defer',
+    }
+
+    // Optional framework-specific scheduler for deferred execution.
+    this.hydrationScheduler = (run) => {
+      nextTick(() => run())
+    }
+
+    this.pluginCreated = addStore
+  }
+
+  override hydrate() {
+    if (typeof window === 'undefined') {
+      return
+    }
+
+    // Safe browser-only initialization, only called when the policy allows it.
+    return this.storeInstance?.hydrate?.()
+  }
+}
+```
+
+### SSR / Nuxt best practices
+
+`pinia-plugin-subscription` is SSR-safe by design, but the runtime policy
+still needs to match the actual app lifecycle.
+
+Use `hydration: 'defer'` when the subscriber depends on browser-only APIs,
+client-side cookies, `localStorage`, DOM access, or a hydrated app state
+that must exist only after the app is mounted.
+
+Use `runtimeEnvironment: 'server'` (on `createHydrationPlugin()`) or
+`execution.environment: 'server'` when a subscriber is only valid during
+server-side rendering or should not touch browser-only objects:
+
+```js
+pinia.use(createHydrationPlugin([serverOnlySubscriber], {
+  runtimeEnvironment: 'server'
+}))
+```
+
+Avoid browser-only code in stores during build-time SSR. In practice:
+
+- do not access `window`, `document`, `localStorage`, or `matchMedia` at
+  module scope or during store setup when the code may run on the server;
+- keep browser-specific bootstrap in `hydrate()` or `afterHydration()`;
+- prefer environment-aware guards such as `typeof window !== 'undefined'`;
+- avoid network access or hydration reads before the client is ready,
+  unless the code is explicitly intended to run on both environments.
+
+A safe pattern:
+
+```js
+const mySubscriber = {
+  name: 'safe-browser-access',
+  execution: {
+    environment: 'client',
+    hydration: 'defer',
+  },
+  hydrate: (context) => {
+    // safe browser access here, after hydration is allowed
+    const saved = localStorage.getItem('demo')
+    if (saved) {
+      context.store.$patch({ value: JSON.parse(saved) })
+    }
+  },
+  invoke: () => true,
+}
+```
+
+This keeps the server render deterministic and prevents browser-only
+initialization from crashing Nuxt or SSR builds.
+
+## Typing per-store options: `StoreOptionsExtensions` (TypeScript)
+
+This package is the only one allowed to augment pinia's
+`DefineStoreOptionsBase`. A subscriber plugin must **not** redeclare it:
+merging `storeOptions` with a different (even compatible) type raises
+`TS2717` in consumer code.
+
+Instead, per-store plugin options are centralized behind the
+`StoreOptionsExtensions` interface. Augment it through interface merging to
+add your own typed keys:
+
+```ts
+// my-subscriber-plugin/types.d.ts (shipped with your plugin)
+declare module 'pinia-plugin-subscription/types' {
+  interface StoreOptionsExtensions {
+    myPluginOption?: string
+  }
+}
+```
+
+The keys merge into `StoreOptions`, so store authors get type-checking
+directly in the store definition:
+
+```ts
+export const useMyStore = defineAStore('myStore', () => { /* ... */ }, {
+  rollbackAfterFailure: { save: 'all' },  // built-in option
+  myPluginOption: 'value',                // typed via your augmentation
+})
+```
+
+Guidelines:
+
+- Always declare **optional** keys with names specific enough to avoid
+  collisions (prefer `myPluginOption` over `options`).
+- At runtime, merged options are delivered to your subscriber's
+  `invoke(context, debug)` through `context.options.storeOptions` — no
+  extra wiring needed.
+- Never redeclare `DefineStoreOptionsBase` or `PiniaCustomProperties`; only
+  this package owns those augmentations.
+
+## Reference implementation
+
+The demo app ships a complete plugin implementation in
+[`src/demo/extending-pinia-store/`](../src/demo/extending-pinia-store/): a
+`PluginSubscriber` subclass, a `Store` subclass, option typing and SSR
+guards. Run `npm run dev` to explore it live.