@blac/core 2.0.20 → 2.0.21

package/README.md

@@ -52,7 +52,6 @@ class UserCardCubit extends Cubit<UserCardState, { userId: string }> {
   init(args: { userId: string }) {
     // Called by framework once, synchronously at creation, before first snapshot
     this.userId = args.userId;
-    void this.loadUser(args.userId);
   }
 
   // Optional: control how args map to identity (default = structural hash)
@@ -60,6 +59,8 @@ class UserCardCubit extends Cubit<UserCardState, { userId: string }> {
 }
 ```
 
+`init` is for synchronous state seeding, not side effects. Kick off a fetch, subscription, or timer from `onActivate(signal)` instead — it only fires once something actually owns the instance and hands you an `AbortSignal` for cleanup. See the [`@blac/react` README](../blac-react/README.md#activation-onactivate--ondeactivate) for the full lifecycle.
+
 **Key mechanics:**
 
 - **Different args ⇒ different instance** (structural hash by default, or `static key` if declared).
@@ -124,7 +125,7 @@ class CanvasRendererCubit extends Cubit<
 
 ### StateContainer
 
-Abstract base class. Use this when you want `emit`/`update` to be protected (not callable from outside).
+Abstract base class for managing state outside the bloc/cubit pattern. Mutation is protected: the class owns its transitions and callers go through the methods it exposes.
 
 ```ts
 import { StateContainer } from '@blac/core';
@@ -144,9 +145,11 @@ class AuthContainer extends StateContainer<{ token: string | null }> {
 }
 ```
 
-**Public API:** `state`, `subscribe(listener)`, `dispose()`, `$blac` (`$blac.name`, `$blac.id`, `$blac.debug`, `$blac.createdAt`, `$blac.disposed`, `$blac.dependencies`, `$blac.hydration`)
+**Public API:** `state`, `subscribe(interest, cb)`, `dispose()`, `$blac` (`$blac.name`, `$blac.id`, `$blac.debug`, `$blac.createdAt`, `$blac.disposed`, `$blac.dependencies`, `$blac.hydration`)
+
+**Protected:** `emit(state)`, `patch(partial)`, `update(fn)` — state mutation is restricted to the class itself, as in the example above. Use `Cubit` when a caller needs to drive state from outside.
 
-**Protected API:** `emit(state)`, `update(fn)`, `init(args)` (optional), `onDepsChanged(next, prev)` (optional), `onSystemEvent(event, handler)`, `depend(BlocClass, instanceKey?)`
+**Protected API:** `init(args)` (optional), `onDepsChanged(next, prev)` (optional), `onSystemEvent(event, handler)`, `depend(Type, defaultArgs?)` (returns a `DepHandle`, not an instance)
 
 ## Registry
 
@@ -196,34 +199,25 @@ const stop = watch(CounterCubit, (counter) => {
 });
 
 // Watch a specific named instance
-const stop2 = watch(instance(CounterCubit, 'counter-1'), (c) => {
+const stop2 = watch(instance(CounterCubit, { id: 'counter-1' }), (c) => {
   console.log(c.state.count);
 });
 ```
 
-## Tracked
-
-Run a function and capture which blocs/state it accessed.
-
-```ts
-import { tracked } from '@blac/core';
-
-const { result, dependencies } = tracked(() => {
-  const user = ensure(UserCubit);
-  return user.state.name;
-});
-```
+State tracking (which blocs/state a function accesses) is automatic — see
+[Tracked](https://blac-docs.pages.dev/core/tracked) for details.
 
 ## Plugins
 
 ```ts
-import { getPluginManager, type BlacPlugin } from '@blac/core';
+import { getPluginManager } from '@blac/core/plugins';
+import { type BlacPlugin } from '@blac/core';
 
 const myPlugin: BlacPlugin = {
   name: 'my-plugin',
   version: '1.0.0',
-  onStateChanged(instance, previousState, currentState) {
-    console.log(instance.constructor.name, previousState, '→', currentState);
+  onStateChange(ctx, prev, next, paths) {
+    console.log(ctx.container?.$blac.name, prev, '→', next);
   },
 };
 
@@ -232,15 +226,11 @@ getPluginManager().install(myPlugin, { environment: 'development' });
 
 ## Subpath Exports
 
-| Export                | Contents                                               |
-| --------------------- | ------------------------------------------------------ |
-| `@blac/core`          | All core classes, registry, decorators, watch, tracked |
-| `@blac/core/watch`    | `watch`, `instance`, `tracked`                         |
-| `@blac/core/tracking` | Dependency tracking internals for framework adapters   |
-| `@blac/core/plugins`  | Plugin system types and utilities                      |
-| `@blac/core/debug`    | Registry introspection helpers                         |
-| `@blac/core/testing`  | Test utilities                                         |
-| `@blac/core/types`    | Type-only exports                                      |
+| Export               | Contents                                      |
+| -------------------- | --------------------------------------------- |
+| `@blac/core`         | All core classes, registry, decorators, watch |
+| `@blac/core/plugins` | Plugin system types and utilities             |
+| `@blac/core/testing` | Test utilities                                |
 
 ## License