@twobirds/microcomponents 0.2.1 → 0.2.3

package/dist/state/observables.d.ts

@@ -1,106 +1,60 @@
 /**
-@module Observables
-
-
-This module provides reactive data binding capabilities using observables,
-enabling automatic DOM updates when underlying data changes.
-
-## Overview
+Reactive data binding via observables — object properties trigger callbacks and update
+DOM placeholders automatically when their values change. Supports primitives, nested objects,
+and deep-change detection with debounced notifications. Most likely you will only need the first
+variant of the examples below
 
-The observable system allows you to make object properties "observable" so that
-registered callbacks are automatically invoked whenever those properties change.
-It's particularly designed for reactive templating and binding data to HTML elements.
-It can also handle simple object properties like strings, boolean and numbers.
-
-## How `observe()` Works
-
-The main function is {@link observe}, which takes an object and makes its properties
-or a specific property observable.
-
-### Simple properties
+@module Observables
 
-javascript
-```js
-let person = { name: "John", count: 0 };
+@example Plugin — chainable instance methods on DC components
+```ts
+import { DC, defineCE, observePlugin } from '@twobirds/microcomponents';
 
-observe( person ); // all properties inside are now observables
+observePlugin(DC);
 
-person.name.subscribe( (name) => {
-  console.log("Name changed:", name);
-});
+class Counter extends DC {
+    data = { clicks: 1 };
 
-person.count.subscribe( (count) => {
-  console.log("Count changed:", count);
-});
+    oneAssets() {
+        this
+        .subscribe('data', (v) => console.log('data →', v))
+        .bind('data', this.target);
+    }
+}
 
-person.name = "Jane";  // > Name changed: Jane
-person.count += 10;    // > Count changed: 10
+defineCE('mc-counter', Counter);
 ```
 
-### Deep Change Detection
-
-This means that if you modify any of the properties inside an observed object -> all callbacks are triggered.
-
-javascript
-```js
-let obj = { data: { name: "John", count: 0 } };
-
-observe( obj, 'data' ); // make the data property observable
-
-obj.data.subscribe( (data) => {
-  console.log("Data changed:", data);
-});
+@example Basic observe + subscribe on a plain object
+```ts
+import { observe } from '@twobirds/microcomponents';
 
-obj.data.name = "Jane"; // > { data: { name: "Jane", count: 0 } }
-obj.data.count += 10;   // > { data: { name: "Jane", count: 10 } }
+const state = observe({ count: 0, label: 'hi' });
+state.count.subscribe((v) => console.log('count is now', v));
+state.count++; // triggers the callback
 ```
 
-### Debounced Notifications
-
-To prevent excessive updates, notifications are debounced briefly:
+@example Deep change detection on a nested property
+```ts
+import { observe } from '@twobirds/microcomponents';
 
-javascript
-```js
-let obj = observe({ value: 1 });
-for (let i = 0; i < 100; i++) {
-  obj.value++; // Only triggers one callback after all changes complete
-}
+const state = observe({ data: { name: 'John', age: 30 } });
+state.data.subscribe((d) => console.log('data changed:', d));
+state.data.name = 'Jane'; // triggers callback with updated object
 ```
 
-## DOM Binding with Placeholders
-
-The observables integrate tightly with placeholder-based templating:
-
-- Elements with `{placeholder}` syntax are scanned for observable data.
-- When observed data changes, matching placeholders in the DOM are updated automatically.
-
-@example
+@example DOM binding — placeholder tokens update live
+```ts
+import { observe } from '@twobirds/microcomponents';
 
-HTML
-```html
-<div class="model {visibility}">
-  Hello {name}! You have {count} messages.
-</div>
+const state = observe({ user: { name: 'Alice', count: 0 } });
+state.user.bind(document.querySelector('.model'));
+// <span>{user.name}</span> updates automatically when state.user.name changes
 ```
 
-Javascript
-```js
-const div = document.querySelector('.model');
-
-const model = observe({
-  data: { name: "Alice", count: 0 },
-  visibility: ''
-});
-
-if (div) {
-  model.data.bind( div );
-}
-
-model.data.count++; // Automatically updates the DOM with new count value
-model.visibility = 'hidden'; // adds the hidden class to the DOM element
-```
 */
 /**
+@hidden
 A callback invoked with the current observable value when notified.
 
 @example
@@ -111,6 +65,7 @@ observable.subscribe(cb);
 */
 export type Callback<T = unknown> = (value: T) => void;
 /**
+@hidden
 Interface representing an observable object that supports subscription, notification, and DOM binding.
 
 Observable objects track registered callbacks and invoke them when their internal state changes.
@@ -132,6 +87,7 @@ export type Observable<T = unknown> = T & {
     callbacks: Array<Function>;
 };
 /**
+@hidden
 Every property of `T` mapped to an observable of its value.
 
 KNOWN LIMIT: the runtime property *setter* accepts a plain value
@@ -161,6 +117,7 @@ export type Observed<T> = {
     [K in keyof T]: Observable<T[K]>;
 };
 /**
+@hidden
 Only `K` of `T` mapped to an observable; other properties keep their type.
 Carries the same write limitation as {@link Observed} for the mapped key.
 
@@ -174,6 +131,7 @@ export type ObservedKey<T, K extends keyof T> = {
     [P in keyof T]: P extends K ? Observable<T[P]> : T[P];
 };
 /**
+@hidden
 The inverse of a hand-declared observable state interface: strips the
 `Observable` wrapper from every property, yielding the plain seed shape.
 `Unobserved<CounterState>` → `{ count: number }`.
@@ -201,6 +159,7 @@ export type Unobserved<S> = {
     } ? V : S[K];
 };
 /**
+@hidden
 Whether a value is already an observable wrapper — `subscribe` is reachable on its prototype chain.
 Used by {@link observe} to skip re-wrapping and to detect the "not yet observed" state on reassignment.
 
@@ -212,65 +171,39 @@ isAlreadyObserved(42);          // false
 ```
 */
 export declare function isAlreadyObserved(value: unknown): boolean;
+export declare function observe<T extends object, K extends keyof T>(target: T, propertyName: K): ObservedKey<T, K>;
+export declare function observe<T extends object>(target: T): Observed<T>;
+export declare function observe<S extends object>(target: Unobserved<S>): S;
 /**
-Makes a target object's properties observable by replacing them with wrapped values.
-
-Wraps each property of `target` that is not already observable (and meets criteria)
-in an observable wrapper. Also sets up deep change detection for objects and
-debounced notifications when the data changes.
+Attaches convenience methods `notify()`, `subscribe()`, and `bind()` to the prototype of a
+microcomponent class so that observable properties can be controlled directly on the instance.
 
-There are two sides to using it — pick per call site:
+All three methods return the component instance, so you can chain them fluently.
 
-**Declarative (typed class fields).** Declare the field as `Observable<T>` up
-front, then let `observe(this, 'field')` install the live wrapper in the
-constructor. The declaration needs the double cast once (`0 as unknown as
-Observable<number>`): the field starts life as a plain value and only becomes
-the wrapper when `observe()` runs. In exchange, every later use is fully typed —
-arithmetic, `subscribe`, `bind` — with no casts anywhere else.
+Call it once at module level before defining any component classes. The plugin is idempotent —
+subsequent calls are no-ops.
 
-**Imperative (wrapping existing data).** Hand any object to `observe()` after
-the fact — no declarations, the return type is inferred: every property comes
-back as `Observable<PropertyType>`.
+@param Class - A constructor function whose prototype chain includes {@link Core.McBase}.
 
-@param target - The object whose properties should be made observable.
-@param propertyName - Optional specific property name to make one property observable instead of all properties.
-@returns The original target object, now with observable properties.
-
-@example Imperative usage — wrap an existing plain object:
-```ts
-const state = observe({ count: 0, label: 'hi' });
-state.count.subscribe((v) => console.log('count is now', v));
-state.count++; // triggers the callback
-```
-
-@example Declarative usage — typed class field with double cast:
+@example
 ```ts
-class Counter {
-    clicks: Observable<number> = 0 as unknown as Observable<number>;
-
-    constructor() {
-        observe(this, 'clicks');
-    }
+class Counter extends DC {
+    data = { clicks: 1 };
 
-    bump() {
-        this.clicks++; // plain arithmetic — the declaration carries the type
+    oneAssets() {
+        this
+        .subscribe('data', (v) => console.log('data →', v))
+        .bind('data', this.target);
     }
 }
 ```
-
-@example Schema-first usage — divergent read/write types via hand-declared interface:
-```ts
-interface CounterState {
-    get count(): Observable<number>;
-    set count(v: number);
-}
-
-const state = observe<CounterState>({ count: 0 }); // seed validated against schema
-state.count.subscribe((v) => console.log(v)); // fully typed
-state.count = 5; // plain assignment — the declared setter type permits it
-```
 */
-export declare function observe<T extends object, K extends keyof T>(target: T, propertyName: K): ObservedKey<T, K>;
-export declare function observe<T extends object>(target: T): Observed<T>;
-export declare function observe<S extends object>(target: Unobserved<S>): S;
+export declare function observePlugin(Class: any): void;
+declare module '../core/MC' {
+    interface McBase<TTarget extends object = object> {
+        notify(propName: string): this;
+        subscribe(propName: string, callback: Function): this;
+        bind(propName: string, target: HTMLElement | ShadowRoot): this;
+    }
+}
 //# sourceMappingURL=observables.d.ts.map

package/dist/state/observables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observables.d.ts","sourceRoot":"","sources":["../../src/state/observables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqGE;AAiBF;;;;;;;;EAQE;AACF,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAEvD;;;;;;;;;;;;EAYE;AACF,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG;IACzC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAChD,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAClD,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,gBAAgB,GAAG,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IACzE,cAAc;IACd,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;CAC3B,CAAC;AAwNF;;;;;;;;;;;;;;;;;;;;;;;;;EAyBE;AACF,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAE/D;;;;;;;;;EASE;AACF,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI;KAC9C,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;EAqBE;AACF,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;KAC1B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,GAAG,OAAO,CAAA;KAAE,GACpF,CAAC,GACD,CAAC,CAAC,CAAC,CAAC;CACP,CAAC;AAKF;;;;;;;;;;EAUE;AACF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyDE;AAEF,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAC1D,MAAM,EAAE,CAAC,EACT,YAAY,EAAE,CAAC,GACb,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACrB,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAClE,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC"}
+{"version":3,"file":"observables.d.ts","sourceRoot":"","sources":["../../src/state/observables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsDE;AAkBF;;;;;;;;;EASE;AACF,MAAM,MAAM,QAAQ,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAEvD;;;;;;;;;;;;;EAaE;AACF,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG;IACzC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAChD,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAClD,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,gBAAgB,GAAG,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IACzE,cAAc;IACd,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;CAC3B,CAAC;AAyNF;;;;;;;;;;;;;;;;;;;;;;;;;;EA0BE;AACF,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAE/D;;;;;;;;;;EAUE;AACF,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI;KAC9C,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;EAsBE;AACF,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI;KAC1B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,GAAG,OAAO,CAAA;KAAE,GACpF,CAAC,GACD,CAAC,CAAC,CAAC,CAAC;CACP,CAAC;AAKF;;;;;;;;;;;EAWE;AACF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMzD;AAED,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAC1D,MAAM,EAAE,CAAC,EACT,YAAY,EAAE,CAAC,GACb,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACrB,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAClE,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAyIpE;;;;;;;;;;;;;;;;;;;;;;;EAuBE;AACF,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,QAoEvC;AAED,OAAO,QAAQ,YAAY,CAAC;IACxB,UAAiB,MAAM,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;QACnD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;QACtD,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,CAAC;KAClE;CACJ"}

package/dist/state/observables.js

@@ -1,109 +1,63 @@
 /**
-@module Observables
-
-
-This module provides reactive data binding capabilities using observables,
-enabling automatic DOM updates when underlying data changes.
-
-## Overview
-
-The observable system allows you to make object properties "observable" so that
-registered callbacks are automatically invoked whenever those properties change.
-It's particularly designed for reactive templating and binding data to HTML elements.
-It can also handle simple object properties like strings, boolean and numbers.
+Reactive data binding via observables — object properties trigger callbacks and update
+DOM placeholders automatically when their values change. Supports primitives, nested objects,
+and deep-change detection with debounced notifications. Most likely you will only need the first
+variant of the examples below
 
-## How `observe()` Works
-
-The main function is {@link observe}, which takes an object and makes its properties
-or a specific property observable.
-
-### Simple properties
+@module Observables
 
-javascript
-```js
-let person = { name: "John", count: 0 };
+@example Plugin — chainable instance methods on DC components
+```ts
+import { DC, defineCE, observePlugin } from '@twobirds/microcomponents';
 
-observe( person ); // all properties inside are now observables
+observePlugin(DC);
 
-person.name.subscribe( (name) => {
-  console.log("Name changed:", name);
-});
+class Counter extends DC {
+    data = { clicks: 1 };
 
-person.count.subscribe( (count) => {
-  console.log("Count changed:", count);
-});
+    oneAssets() {
+        this
+        .subscribe('data', (v) => console.log('data →', v))
+        .bind('data', this.target);
+    }
+}
 
-person.name = "Jane";  // > Name changed: Jane
-person.count += 10;    // > Count changed: 10
+defineCE('mc-counter', Counter);
 ```
 
-### Deep Change Detection
-
-This means that if you modify any of the properties inside an observed object -> all callbacks are triggered.
-
-javascript
-```js
-let obj = { data: { name: "John", count: 0 } };
-
-observe( obj, 'data' ); // make the data property observable
-
-obj.data.subscribe( (data) => {
-  console.log("Data changed:", data);
-});
+@example Basic observe + subscribe on a plain object
+```ts
+import { observe } from '@twobirds/microcomponents';
 
-obj.data.name = "Jane"; // > { data: { name: "Jane", count: 0 } }
-obj.data.count += 10;   // > { data: { name: "Jane", count: 10 } }
+const state = observe({ count: 0, label: 'hi' });
+state.count.subscribe((v) => console.log('count is now', v));
+state.count++; // triggers the callback
 ```
 
-### Debounced Notifications
-
-To prevent excessive updates, notifications are debounced briefly:
+@example Deep change detection on a nested property
+```ts
+import { observe } from '@twobirds/microcomponents';
 
-javascript
-```js
-let obj = observe({ value: 1 });
-for (let i = 0; i < 100; i++) {
-  obj.value++; // Only triggers one callback after all changes complete
-}
+const state = observe({ data: { name: 'John', age: 30 } });
+state.data.subscribe((d) => console.log('data changed:', d));
+state.data.name = 'Jane'; // triggers callback with updated object
 ```
 
-## DOM Binding with Placeholders
-
-The observables integrate tightly with placeholder-based templating:
-
-- Elements with `{placeholder}` syntax are scanned for observable data.
-- When observed data changes, matching placeholders in the DOM are updated automatically.
-
-@example
+@example DOM binding — placeholder tokens update live
+```ts
+import { observe } from '@twobirds/microcomponents';
 
-HTML
-```html
-<div class="model {visibility}">
-  Hello {name}! You have {count} messages.
-</div>
+const state = observe({ user: { name: 'Alice', count: 0 } });
+state.user.bind(document.querySelector('.model'));
+// <span>{user.name}</span> updates automatically when state.user.name changes
 ```
 
-Javascript
-```js
-const div = document.querySelector('.model');
-
-const model = observe({
-  data: { name: "Alice", count: 0 },
-  visibility: ''
-});
-
-if (div) {
-  model.data.bind( div );
-}
-
-model.data.count++; // Automatically updates the DOM with new count value
-model.visibility = 'hidden'; // adds the hidden class to the DOM element
-```
 */
 import { flattenObject, deepEqual, copyGettersSetters, isBrowser } from '../utils/helpers.js';
 import { makePlaceholders } from './placeholders.js';
 import { trigger } from '../utils/events.js';
 /**
+@hidden
 Determines if a value is an observable object.
 
 @param value - The value to check.
@@ -115,6 +69,7 @@ function isObservableObject(value) {
 // repository for observable class wrappers
 const classRepo = {};
 /**
+@hidden
 Creates a new observable wrapper class for the given value's constructor.
 
 Returns a subclass of the original constructor that implements the Observable interface,
@@ -301,6 +256,7 @@ function getConstructor(val) {
     return classRepo[key] || makeObservable(val);
 }
 /**
+@hidden
 Whether a value is already an observable wrapper — `subscribe` is reachable on its prototype chain.
 Used by {@link observe} to skip re-wrapping and to detect the "not yet observed" state on reassignment.
 
@@ -316,6 +272,65 @@ export function isAlreadyObserved(value) {
         value !== null &&
         'subscribe' in value);
 }
+/**
+@hidden
+Makes a target object's properties observable by replacing them with wrapped values.
+
+Wraps each property of `target` that is not already observable (and meets criteria)
+in an observable wrapper. Also sets up deep change detection for objects and
+debounced notifications when the data changes.
+
+There are two sides to using it — pick per call site:
+
+**Declarative (typed class fields).** Declare the field as `Observable<T>` up
+front, then let `observe(this, 'field')` install the live wrapper in the
+constructor. The declaration needs the double cast once (`0 as unknown as
+Observable<number>`): the field starts life as a plain value and only becomes
+the wrapper when `observe()` runs. In exchange, every later use is fully typed —
+arithmetic, `subscribe`, `bind` — with no casts anywhere else.
+
+**Imperative (wrapping existing data).** Hand any object to `observe()` after
+the fact — no declarations, the return type is inferred: every property comes
+back as `Observable<PropertyType>`.
+
+@param target - The object whose properties should be made observable.
+@param propertyName - Optional specific property name to make one property observable instead of all properties.
+@returns The original target object, now with observable properties.
+
+@example Imperative usage — wrap an existing plain object:
+```ts
+const state = observe({ count: 0, label: 'hi' });
+state.count.subscribe((v) => console.log('count is now', v));
+state.count++; // triggers the callback
+```
+
+@example Declarative usage — typed class field with double cast:
+```ts
+class Counter {
+    clicks: Observable<number> = 0 as unknown as Observable<number>;
+
+    constructor() {
+        observe(this, 'clicks');
+    }
+
+    bump() {
+        this.clicks++; // plain arithmetic — the declaration carries the type
+    }
+}
+```
+
+@example Schema-first usage — divergent read/write types via hand-declared interface:
+```ts
+interface CounterState {
+    get count(): Observable<number>;
+    set count(v: number);
+}
+
+const state = observe<CounterState>({ count: 0 }); // seed validated against schema
+state.count.subscribe((v) => console.log(v)); // fully typed
+state.count = 5; // plain assignment — the declared setter type permits it
+```
+*/
 export function observe(target, propertyName) {
     const source = target;
     const keys = propertyName ? [propertyName] : [...Object.getOwnPropertyNames(target)];
@@ -380,3 +395,90 @@ export function observe(target, propertyName) {
     });
     return target;
 }
+/**
+Attaches convenience methods `notify()`, `subscribe()`, and `bind()` to the prototype of a
+microcomponent class so that observable properties can be controlled directly on the instance.
+
+All three methods return the component instance, so you can chain them fluently.
+
+Call it once at module level before defining any component classes. The plugin is idempotent —
+subsequent calls are no-ops.
+
+@param Class - A constructor function whose prototype chain includes {@link Core.McBase}.
+
+@example
+```ts
+class Counter extends DC {
+    data = { clicks: 1 };
+
+    oneAssets() {
+        this
+        .subscribe('data', (v) => console.log('data →', v))
+        .bind('data', this.target);
+    }
+}
+```
+*/
+export function observePlugin(Class) {
+    const McBaseProto = Object.getPrototypeOf(Class.prototype);
+    function makePropObservable(obj, propName) {
+        const obs = obj[propName];
+        if (!isAlreadyObserved(obs)) {
+            observe(obj, propName);
+        }
+    }
+    if (!Object.hasOwn(McBaseProto, 'notify')) {
+        Object.assign(McBaseProto, {
+            /**
+* Manually trigger a notification on an observable property.
+* Ensures the property is observed first if it hasn't been yet.
+* @param propName - The name of the observable property to notify.
+* @returns This instance for chaining.
+
+@example
+```ts
+this.notify('count');
+```
+            */
+            notify: function (propName) {
+                makePropObservable(this, propName);
+                this[propName].notify();
+                return this; // chainable
+            },
+            /**
+* Subscribe a callback to changes on an observable property.
+* Ensures the property is observed first if it hasn't been yet.
+* @param propName - The name of the observable property.
+* @param callback - Function invoked with the new value on every change.
+* @returns This instance for chaining.
+
+@example
+```ts
+this.subscribe('count', (v) => console.log('count →', v));
+```
+            */
+            subscribe: function (propName, callback) {
+                makePropObservable(this, propName);
+                this[propName].subscribe(callback);
+                return this; // chainable
+            },
+            /**
+* Bind an observable property to a DOM target so that `{placeholder}` tokens are updated live.
+* Ensures the property is observed first if it hasn't been yet.
+* @param propName - The name of the observable property.
+* @param target - HTMLElement, ShadowRoot, or DocumentFragment containing placeholders.
+* @returns This instance for chaining.
+
+@example
+```ts
+this.bind('data', this.target);
+```
+            */
+            bind: function (propName, target) {
+                makePropObservable(this, propName);
+                this[propName].bind(target);
+                return this; // chainable
+            },
+        });
+    }
+}

package/dist/state/placeholders.d.ts

@@ -1,4 +1,5 @@
 /**
+@hidden
 DOM placeholder binding: `{name}` templates in attributes and text nodes,
 kept up to date from observable data.
 

package/dist/state/placeholders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"placeholders.d.ts","sourceRoot":"","sources":["../../src/state/placeholders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;EASE;AAEF,OAAO,EAAE,EAAE,EAAE,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAoD5D;;;;;;EAME;AACF,cAAM,YAAa,SAAQ,EAAE;;IAE5B,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAwD;IACjG,UAAU,CAAC,EAAE,MAAM,CAAM;IAEzB;;;;;;;;MAQE;gBACU,MAAM,EAAE,WAAW;IAkF/B;;;;;;;MAOE;IACF,MAAM,CAAC,EAAE,EAAE,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAOzD;AAmBD;;;;;;;EAOE;AACF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,gBAAgB,GAAG,UAAU,GAAG,IAAI,CAK3F;AAED;;;;EAIE;AACF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,WAAW,EAAE;IAAE,aAAa,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC"}
+{"version":3,"file":"placeholders.d.ts","sourceRoot":"","sources":["../../src/state/placeholders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;EAUE;AAEF,OAAO,EAAE,EAAE,EAAE,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAoD5D;;;;;;EAME;AACF,cAAM,YAAa,SAAQ,EAAE;;IAE5B,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAwD;IACjG,UAAU,CAAC,EAAE,MAAM,CAAM;IAEzB;;;;;;;;MAQE;gBACU,MAAM,EAAE,WAAW;IAkF/B;;;;;;;MAOE;IACF,MAAM,CAAC,EAAE,EAAE,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAOzD;AAmBD;;;;;;;EAOE;AACF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,gBAAgB,GAAG,UAAU,GAAG,IAAI,CAK3F;AAED;;;;EAIE;AACF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,WAAW,EAAE;IAAE,aAAa,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC"}

package/dist/state/placeholders.js

@@ -1,4 +1,5 @@
 /**
+@hidden
 DOM placeholder binding: `{name}` templates in attributes and text nodes,
 kept up to date from observable data.
 

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+/**
+Types module — pure type layer for the microcomponent system.
+
+@module Types
+*/
+export type { McBubbleController, BubbleDirection, BubbleDirections, McDetail, McEventHandler, McEvent, McPayloadOf, McController, McNativeEventHandlers, McHost, McHostOf, McEntriesOf, McMerged, McRemoved, } from './mcTypes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;EAIE;AACF,YAAY,EACX,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,OAAO,EACP,WAAW,EACX,YAAY,EACZ,qBAAqB,EACrB,MAAM,EACN,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,SAAS,GACT,MAAM,cAAc,CAAC"}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/types/mcTypes.d.ts

@@ -1,10 +1,10 @@
 /**
-@module Type layer
 
 Pure type layer of the microcomponent system.
 
 RULE: types only — no runtime exports, no imports. It sits at the bottom of the
 dependency graph so every other module can import from it without cycles.
+@module Types
 */
 /** The bubble control handle passed to event handlers; `BubbleController` in events.ts implements it. */
 export interface McBubbleController {
@@ -66,7 +66,7 @@ export type McPayloadOf<EM, K extends string, D = unknown> = K extends keyof EM
 declare global {
     /**
     App-wide map of registry key names to component types. Augment it next to a
-    component definition and keyed lookups (`isMcDOM(el, 'cart')`, `closest('cart')`,
+    component definition and keyed lookups (`isMcHost(el, 'cart')`, `closest('cart')`,
     `ancestors` / `children` / `descendants`) type themselves from it.
 
     Presence is checked at runtime; the key → type mapping is a convention. Where
@@ -81,7 +81,7 @@ declare global {
     }
 
     const el = document.querySelector('form');
-    if (el && isMcDOM(el, 'cart')) {
+    if (el && isMcHost(el, 'cart')) {
         el._mc.cart.addItem(item); // Cart
     }
     ```