@thomas-siegfried/tapout 0.0.2 → 0.0.3

package/README.md

@@ -4,6 +4,8 @@ A modern ESM reactivity and templating library, spiritually inspired by [Knockou
 
 Tapout provides dependency-tracked observables, computed values, declarative DOM bindings, a component system, and TC39 Stage 3 decorators — all in a lightweight, explicit architecture built on TypeScript.
 
+For detailed TypeScript decorator setup and compatibility notes, see [`decorator-config.md`](./decorator-config.md).
+
 ## Table of Contents
 
 - [Installation](#installation)

package/decorator-config.md

@@ -0,0 +1,220 @@
+# Vite Decorator Setup Guide
+
+Four tested configurations for using decorators with Vite 7/8 and tapout.
+
+---
+
+## Option A: Babel + TC39 Stage 3 Decorators
+
+Uses the `accessor` keyword. Babel transpiles TC39 decorators into `_applyDecs` helper calls.
+
+### Install
+
+```bash
+npm install -D vite-plugin-babel @babel/plugin-proposal-decorators @babel/plugin-transform-typescript
+```
+
+### `vite.config.ts`
+
+```typescript
+import { defineConfig } from 'vite';
+import babel from 'vite-plugin-babel';
+
+export default defineConfig({
+  resolve: {
+    preserveSymlinks: true,       // only needed for npm link scenarios
+  },
+  oxc: false as any,              // disable Vite 8's default Oxc transpiler
+  plugins: [
+    babel({
+      filter: /\.[jt]sx?$/,       // must include .ts/.tsx — default only handles .js/.jsx
+      babelConfig: {
+        plugins: [
+          ['@babel/plugin-proposal-decorators', { version: '2023-11' }],
+          ['@babel/plugin-transform-typescript', { allowDeclareFields: true }],
+        ],
+      },
+    }),
+  ],
+});
+```
+
+### `tsconfig.json`
+
+Do **not** add `experimentalDecorators`. Keep `useDefineForClassFields: true` (the default).
+
+### Source syntax
+
+```typescript
+@reactive accessor currentRoute: string = 'dashboard';
+@reactiveArray accessor items: Item[] = [];
+@computed get fullName(): string { return ... }
+```
+
+---
+
+## Option B: Babel + Experimental (Legacy) Decorators
+
+No `accessor` keyword. Babel transpiles legacy decorators. Requires `@babel/plugin-transform-class-properties` with `loose: true` to prevent Babel from creating own data properties that shadow the decorator's getter/setter.
+
+### Install
+
+```bash
+npm install -D vite-plugin-babel @babel/plugin-proposal-decorators @babel/plugin-transform-class-properties @babel/plugin-transform-typescript
+```
+
+### `vite.config.ts`
+
+```typescript
+import { defineConfig } from 'vite';
+import babel from 'vite-plugin-babel';
+
+export default defineConfig({
+  resolve: {
+    preserveSymlinks: true,
+  },
+  oxc: false as any,
+  plugins: [
+    babel({
+      filter: /\.[jt]sx?$/,
+      babelConfig: {
+        plugins: [
+          ['@babel/plugin-proposal-decorators', { version: 'legacy' }],
+          ['@babel/plugin-transform-class-properties', { loose: true }],
+          ['@babel/plugin-transform-typescript', { allowDeclareFields: true }],
+        ],
+      },
+    }),
+  ],
+});
+```
+
+### `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false
+  }
+}
+```
+
+### Source syntax
+
+```typescript
+@reactive currentRoute: string = 'dashboard';
+@reactiveArray items: Item[] = [];
+@computed get fullName(): string { return ... }
+```
+
+### Babel-specific note
+
+Babel passes a `descriptor` with an `initializer` property to legacy field decorators — this is a Babel convention, not a standard. tapout handles this to prevent Babel's class property transform from shadowing the decorator's getter/setter with a plain data property.
+
+---
+
+## Option C: Oxc (Vite 8 built-in) + Experimental (Legacy) Decorators
+
+No Babel needed — Vite 8's built-in Oxc transpiler handles legacy decorators natively. Zero extra dependencies.
+
+### Install
+
+No additional packages needed beyond Vite itself.
+
+### `vite.config.ts`
+
+```typescript
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  resolve: {
+    preserveSymlinks: true,
+  },
+  oxc: {
+    decorator: {
+      legacy: true,
+    },
+  },
+});
+```
+
+### `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false
+  }
+}
+```
+
+### Source syntax
+
+Same as Option B (no `accessor` keyword).
+
+---
+
+## Option D: esbuild (Vite 7 built-in) + Experimental (Legacy) Decorators
+
+No Babel or Oxc needed — Vite 7's built-in esbuild transpiler handles legacy decorators natively by reading `tsconfig.json`. Zero extra dependencies.
+
+### Install
+
+No additional packages needed beyond Vite itself.
+
+```bash
+npm install -D vite@~7.3.1
+```
+
+### `vite.config.ts`
+
+No `vite.config.ts` is required. esbuild reads `experimentalDecorators` and `useDefineForClassFields` directly from `tsconfig.json` — no explicit esbuild config needed.
+
+### `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false
+  }
+}
+```
+
+`erasableSyntaxOnly` (added in TypeScript 5.9) must **not** be enabled — it rejects decorator syntax as non-erasable.
+
+### Source syntax
+
+Same as Option B (no `accessor` keyword).
+
+### esbuild-specific notes
+
+- esbuild does **not** support `emitDecoratorMetadata`. tapout does not use `reflect-metadata`, so this is a non-issue.
+- esbuild does **not** pass a `descriptor` with an `initializer` to legacy field decorators (unlike Babel). tapout's legacy path handles both cases — with and without the Babel-style `initializer`.
+
+---
+
+## Quick Reference
+
+| | Option A | Option B | Option C | Option D |
+|---|---|---|---|---|
+| Vite version | 8 | 8 | 8 | 7 |
+| Spec | TC39 Stage 3 | Experimental/Legacy | Experimental/Legacy | Experimental/Legacy |
+| Transpiler | Babel | Babel | Oxc (built-in) | esbuild (built-in) |
+| Extra deps | 2 packages | 3 packages | None | None |
+| `accessor` keyword | Yes | No | No | No |
+| `experimentalDecorators` | No | Yes | Yes | Yes |
+| `useDefineForClassFields` | `true` | `false` | `false` | `false` |
+| `emitDecoratorMetadata` | N/A | Supported | Supported | Not supported |
+
+## Common Gotchas
+
+- **`oxc: false as any`** — required for Options A/B to disable Vite 8's default Oxc transpiler so Babel takes over. The `as any` is needed because Vite 8's types don't expose this option.
+- **`filter: /\.[jt]sx?$/`** — critical for Babel options. Without it, `.ts` files bypass Babel and hit the default transpiler.
+- **`preserveSymlinks: true`** (Vite 8) / **`resolve.dedupe`** (Vite 7) — only needed when using `npm link` for local package development.
+- **Plugin order matters** — decorators must come before class-properties, which must come before TypeScript transform (Options A/B only).
+- **Vite caches pre-bundled deps** — after changing a linked package, delete `node_modules/.vite` and restart the dev server.
+- **`erasableSyntaxOnly: true`** — if present in `tsconfig.json`, must be removed when enabling `experimentalDecorators`. TypeScript 5.9 introduced this flag to enforce type-only syntax, but decorator emit is runtime code.
+- **esbuild reads tsconfig automatically** (Option D) — no `vite.config.ts` is needed at all. esbuild picks up `experimentalDecorators` and `useDefineForClassFields` from the project's `tsconfig.json`.

package/dist/wireParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wireParams.d.ts","sourceRoot":"","sources":["../src/wireParams.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAMtD,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;CACxC;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,IAAI,GACb,gBAAgB,CA+BlB"}
+{"version":3,"file":"wireParams.d.ts","sourceRoot":"","sources":["../src/wireParams.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAkBtD,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;CACxC;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,IAAI,GACb,gBAAgB,CAuClB"}

package/dist/wireParams.js

@@ -4,14 +4,27 @@ import { isSubscribable } from './subscribable.js';
 import { getObservable, replaceObservable } from './decorators.js';
 import { addDisposeCallback } from './domNodeDisposal.js';
 const SKIP_KEYS = new Set(['$raw']);
+function getWritableChildTarget(instance, key) {
+    const decorated = getObservable(instance, key);
+    if (decorated instanceof Observable)
+        return decorated;
+    if (decorated instanceof Computed && decorated.hasWriteFunction)
+        return decorated;
+    const directValue = instance[key];
+    if (directValue instanceof Observable)
+        return directValue;
+    if (directValue instanceof Computed && directValue.hasWriteFunction)
+        return directValue;
+    return undefined;
+}
 export function wireParams(instance, params, element) {
     const subscriptions = [];
     for (const key of Object.keys(params)) {
         if (SKIP_KEYS.has(key))
             continue;
         const paramValue = params[key];
-        const childObs = getObservable(instance, key);
-        const childIsReactive = childObs !== undefined && isSubscribable(childObs);
+        const childTarget = getWritableChildTarget(instance, key);
+        const childIsReactive = childTarget !== undefined && isSubscribable(childTarget);
         if (paramValue instanceof Observable) {
             if (childIsReactive) {
                 replaceObservable(instance, key, paramValue);
@@ -21,9 +34,19 @@ export function wireParams(instance, params, element) {
             }
         }
         else if (paramValue instanceof Computed) {
-            instance[key] = paramValue.get();
+            if (childTarget) {
+                childTarget.set(paramValue.get());
+            }
+            else {
+                instance[key] = paramValue.get();
+            }
             const sub = paramValue.subscribe((newValue) => {
-                instance[key] = newValue;
+                if (childTarget) {
+                    childTarget.set(newValue);
+                }
+                else {
+                    instance[key] = newValue;
+                }
             });
             subscriptions.push(sub);
             if (element) {

package/dist/wireParams.js.map

@@ -1 +1 @@
-{"version":3,"file":"wireParams.js","sourceRoot":"","sources":["../src/wireParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAMpC,MAAM,UAAU,UAAU,CACxB,QAAgB,EAChB,MAA+B,EAC/B,OAAc;IAEd,MAAM,aAAa,GAA4B,EAAE,CAAC;IAElD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAEjC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC9C,MAAM,eAAe,GAAG,QAAQ,KAAK,SAAS,IAAI,cAAc,CAAC,QAAQ,CAAC,CAAC;QAE3E,IAAI,UAAU,YAAY,UAAU,EAAE,CAAC;YACrC,IAAI,eAAe,EAAE,CAAC;gBACpB,iBAAiB,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;YAC/C,CAAC;iBAAM,CAAC;gBACL,QAAoC,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC;YAChE,CAAC;QACH,CAAC;aAAM,IAAI,UAAU,YAAY,QAAQ,EAAE,CAAC;YACzC,QAAoC,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC;YAC9D,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,QAAiB,EAAE,EAAE;gBACpD,QAAoC,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;YACxD,CAAC,CAAC,CAAC;YACH,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxB,IAAI,OAAO,EAAE,CAAC;gBACZ,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;aAAM,CAAC;YACL,QAAoC,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC;QAC1D,CAAC;IACH,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"wireParams.js","sourceRoot":"","sources":["../src/wireParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAEpC,SAAS,sBAAsB,CAAC,QAAgB,EAAE,GAAW;IAC3D,MAAM,SAAS,GAAG,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC/C,IAAI,SAAS,YAAY,UAAU;QAAE,OAAO,SAAS,CAAC;IACtD,IAAI,SAAS,YAAY,QAAQ,IAAI,SAAS,CAAC,gBAAgB;QAAE,OAAO,SAAS,CAAC;IAElF,MAAM,WAAW,GAAI,QAAoC,CAAC,GAAG,CAAC,CAAC;IAC/D,IAAI,WAAW,YAAY,UAAU;QAAE,OAAO,WAAW,CAAC;IAC1D,IAAI,WAAW,YAAY,QAAQ,IAAI,WAAW,CAAC,gBAAgB;QAAE,OAAO,WAAW,CAAC;IAExF,OAAO,SAAS,CAAC;AACnB,CAAC;AAMD,MAAM,UAAU,UAAU,CACxB,QAAgB,EAChB,MAA+B,EAC/B,OAAc;IAEd,MAAM,aAAa,GAA4B,EAAE,CAAC;IAElD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAEjC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,WAAW,GAAG,sBAAsB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC1D,MAAM,eAAe,GAAG,WAAW,KAAK,SAAS,IAAI,cAAc,CAAC,WAAW,CAAC,CAAC;QAEjF,IAAI,UAAU,YAAY,UAAU,EAAE,CAAC;YACrC,IAAI,eAAe,EAAE,CAAC;gBACpB,iBAAiB,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC;YAC/C,CAAC;iBAAM,CAAC;gBACL,QAAoC,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC;YAChE,CAAC;QACH,CAAC;aAAM,IAAI,UAAU,YAAY,QAAQ,EAAE,CAAC;YAC1C,IAAI,WAAW,EAAE,CAAC;gBAChB,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC;YACpC,CAAC;iBAAM,CAAC;gBACL,QAAoC,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC;YAChE,CAAC;YACD,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,QAAiB,EAAE,EAAE;gBACrD,IAAI,WAAW,EAAE,CAAC;oBAChB,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBAC5B,CAAC;qBAAM,CAAC;oBACL,QAAoC,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;gBACxD,CAAC;YACH,CAAC,CAAC,CAAC;YACH,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxB,IAAI,OAAO,EAAE,CAAC;gBACZ,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;aAAM,CAAC;YACL,QAAoC,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC;QAC1D,CAAC;IACH,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,CAAC;AAC3B,CAAC"}

package/llms.txt

@@ -0,0 +1,360 @@
+# Tapout
+
+> Tapout is a modern ESM reactivity and templating library, spiritually inspired by KnockoutJS. Same philosophy, modern implementation.
+
+## Guidance
+
+- Prefer `@reactive accessor` over `new Observable()` for class properties
+- Prefer `@reactiveArray accessor` over `new ObservableArray()` for array properties
+- Prefer `@computed` over `new Computed()` for derived values in classes
+- Prefer `@component` decorator over `components.register()` for component registration
+- Use `tapout/core` when you only need reactivity (no DOM)
+- Use `tapout` when you need DOM bindings, templates, and components
+- Always dispose subscriptions and effects when no longer needed
+- Use `DisposableGroup` for centralized cleanup
+- Use `PureComputed` (or `@computed`, which uses it) for intermittent UI values
+
+## Installation
+
+```bash
+npm install tapout
+```
+
+ESM-only. Two entry points:
+
+```typescript
+import { Observable, applyBindings } from 'tapout';       // full library
+import { Observable, Computed } from 'tapout/core';        // reactivity only, no DOM
+```
+
+## Quick Start (Preferred Style)
+
+```typescript
+import { reactive, computed, component, applyBindings } from 'tapout';
+
+@component('greeting-card', `
+  <p>First: <input data-bind="textInput: firstName" /></p>
+  <p>Last: <input data-bind="textInput: lastName" /></p>
+  <h2 data-bind="text: fullName"></h2>
+`)
+class GreetingCard {
+  @reactive accessor firstName = 'Jane';
+  @reactive accessor lastName = 'Doe';
+
+  @computed get fullName() {
+    return `${this.firstName} ${this.lastName}`;
+  }
+}
+
+applyBindings({}, document.body);
+```
+
+```html
+<greeting-card></greeting-card>
+```
+
+## Core Reactivity
+
+### Observable
+
+Mutable reactive value. Reading inside a computed or effect tracks the dependency.
+
+```typescript
+const count = new Observable(0);
+count.get();    // read (tracks dependency)
+count.peek();   // read without tracking
+count.set(5);   // write, notifies subscribers
+```
+
+Decorator equivalent (preferred in classes):
+
+```typescript
+class MyClass {
+  @reactive accessor count = 0;
+}
+// Reading: this.count (tracks), Writing: this.count = 5 (notifies)
+```
+
+Pass extender options: `@reactive({ deferred: true }) accessor query = '';`
+
+### ObservableArray
+
+Observable wrapping an array with mutation methods: `push`, `pop`, `shift`, `unshift`, `splice`, `sort`, `reverse`, `remove`, `removeAll`, `replace`.
+
+```typescript
+const items = new ObservableArray(['a', 'b']);
+items.push('c');
+items.remove('a');
+```
+
+Decorator equivalent (preferred in classes):
+
+```typescript
+class MyClass {
+  @reactiveArray accessor items: string[] = [];
+}
+```
+
+Subscribe to fine-grained diffs:
+
+```typescript
+items.subscribe(changes => { /* status, value, index */ }, 'arrayChange');
+```
+
+### Computed
+
+Derived value, re-evaluates when dependencies change.
+
+```typescript
+const area = new Computed(() => width.get() * height.get());
+```
+
+Writable computed:
+
+```typescript
+const full = new Computed({
+  read: () => `${first.get()} ${last.get()}`,
+  write: (v: string) => { [first, last] = v.split(' ').map(s => s); },
+});
+```
+
+Decorator equivalent (preferred in classes):
+
+```typescript
+class MyClass {
+  @reactive accessor first = 'John';
+  @reactive accessor last = 'Doe';
+
+  @computed get full() { return `${this.first} ${this.last}`; }
+  set full(v: string) { [this.first, this.last] = v.split(' '); }
+}
+```
+
+### PureComputed
+
+Memory-optimized computed that sleeps when it has no subscribers. `@computed` uses this internally.
+
+```typescript
+const label = new PureComputed(() => `Count: ${count.get()}`);
+```
+
+### Effects
+
+```typescript
+// Runs immediately, then on each dependency change
+const handle = effect(() => name.get(), val => console.log(val));
+
+// Runs only on subsequent changes (not immediately)
+const handle = observe(() => name.get(), val => console.log(val));
+
+handle.dispose(); // stop
+```
+
+### Subscriptions
+
+```typescript
+const sub = count.subscribe(value => console.log(value));
+sub.dispose();
+```
+
+Event channels: `'change'` (default), `'beforeChange'`, `'spectate'`, `'dirty'`, `'awake'`, `'asleep'`, `'arrayChange'`.
+
+### Events
+
+Stateless hot signals with owner/consumer separation:
+
+```typescript
+class MyService {
+  private _onSave = new Event<SaveEvent>();
+  readonly onSave = this._onSave.subscribable;
+
+  save(id: number) { this._onSave.emit(new SaveEvent(id, true)); }
+}
+```
+
+Type-filtered: `event.subscribable.on(SaveEvent).subscribe(...)`.
+Aggregate: `AggregateEvent` rolls up multiple event sources via `pipe()`.
+
+### DisposableGroup
+
+Centralized cleanup for subscriptions and event subscriptions:
+
+```typescript
+private _subs = new DisposableGroup();
+// this._subs.add(someSubscription);
+// this._subs.dispose(); // cleans up all at once
+```
+
+## Extenders
+
+```typescript
+obs.extend({ rateLimit: { timeout: 300, method: 'notifyWhenChangesStop' } });
+obs.extend({ rateLimit: 200 });      // throttle
+obs.extend({ notify: 'always' });    // always notify
+obs.extend({ deferred: true });      // microtask batching
+```
+
+## Decorators (Preferred API)
+
+| Decorator | Target | Backing |
+|---|---|---|
+| `@reactive` | `accessor` property | `Observable` |
+| `@reactiveArray` | `accessor` property | `ObservableArray` |
+| `@computed` | getter, getter+setter, method | `PureComputed` / writable `Computed` |
+| `@component(tag, template)` | class | registers component |
+
+Access underlying observable: `getObservable(instance, 'propName')`.
+Replace underlying observable: `replaceObservable(instance, 'propName', newObs)`.
+
+## Components
+
+### Registration (decorator preferred)
+
+```typescript
+@component('user-card', '<div><span data-bind="text: name"></span></div>')
+class UserCard {
+  @reactive accessor name = '';
+}
+```
+
+Or with options:
+
+```typescript
+@component({ tag: 'user-card', template: '...', synchronous: true })
+class UserCard { ... }
+```
+
+Manual registration (use decorator instead when possible):
+
+```typescript
+components.register('user-card', { template: '...', viewModel: UserCard });
+```
+
+### Usage
+
+```html
+<user-card params="name: userName"></user-card>
+```
+
+### Params and Wiring
+
+- Plain values assigned directly
+- Computed params create one-way subscription
+- `$`-prefixed observable params enable two-way binding
+
+```html
+<user-card params="name: $sharedName"></user-card>
+```
+
+### Lifecycle
+
+```typescript
+onInit()                        // after creation and param wiring
+onDescendantsComplete(node)     // after DOM is ready
+dispose()                       // on cleanup
+```
+
+### Slots
+
+```html
+<!-- Component template -->
+<div data-bind="slot: 'header'">Default</div>
+<div data-bind="slot: ''">Default body</div>
+
+<!-- Usage -->
+<my-card>
+  <h2 slot="header">Custom Title</h2>
+  <p>Body content</p>
+</my-card>
+```
+
+## Binding System
+
+Apply bindings: `applyBindings(vm, rootElement)`.
+
+### Context
+
+`$data`, `$root`, `$parent`, `$parents`, `$index`, `$component`, `$parentContext`, `$rawData`, `$componentTemplateNodes`.
+
+Inspect: `contextFor(element)`, `dataFor(element)`.
+
+### Built-in Bindings
+
+**Display:** `text`, `html`, `visible`, `hidden`.
+**Attributes:** `attr: { href: url }`, `css: { active: isActive }`, `class: className`, `style: { color: c }`.
+**Form state:** `enable`, `disable`, `uniqueName`.
+**Events:** `event: { mouseover: fn }`, `click`, `submit`, `enter`. Return `true` for default behavior. Use `clickBubble: false` to stop bubbling.
+**Two-way:** `value`, `textInput`, `checked`, `checkedValue`, `hasFocus`, `selectedOptions`, `options`.
+**Control flow:** `if`, `ifnot`, `with`, `using`, `let`, `foreach`, `template`.
+**Dialog:** `modal`.
+
+### Virtual Elements
+
+```html
+<!-- tap if: showSection -->
+  <p>Content</p>
+<!-- /tap -->
+
+<!-- tap foreach: items -->
+  <span data-bind="text: $data"></span>
+<!-- /tap -->
+```
+
+### Interpolation Markup
+
+Enable with `enableInterpolationMarkup()`:
+
+```html
+<span>Hello, {{ name }}!</span>
+<div>{{{ richHtml }}}</div>
+{{# if isLoggedIn }}<p>Welcome!</p>{{/ if }}
+```
+
+### Attribute Interpolation
+
+Enable with `enableAttributeInterpolationMarkup()`:
+
+```html
+<a href="{{ baseUrl }}/profile/{{ userId }}">Profile</a>
+```
+
+### Namespaced Bindings
+
+Enable with `enableNamespacedBindings()`:
+
+```html
+<a data-bind="attr.href: url, css.active: isActive">Link</a>
+```
+
+### Filters
+
+Enable with `enableTextFilter('text')`:
+
+```html
+<span data-bind="text: name | uppercase"></span>
+<span data-bind="text: bio | default:'None'"></span>
+```
+
+Built-in: `uppercase`, `lowercase`, `default`, `json`. Custom: `filters['myFilter'] = (val, ...args) => result`.
+
+## Utilities
+
+- `toJS(obj)` — deep-unwrap observables to plain JS
+- `toJSON(obj)` — JSON string of unwrapped object
+- `when(() => condition, callback)` — one-shot reactive wait (or returns Promise if no callback)
+- `unwrapObservable(val)` — recursively unwrap
+- `cleanNode(el)`, `removeNode(el)`, `addDisposeCallback(el, fn)` — DOM cleanup
+
+## Configuration
+
+```typescript
+import { options } from 'tapout';
+options.deferUpdates = true;                    // global microtask batching
+options.onError = (err) => { ... };             // global error handler
+options.viewModelFactory = (ctor) => new ctor(); // DI hook
+options.customElementDisplayContents = true;     // display: contents on custom elements
+```
+
+## Type Guards
+
+`isObservable(v)`, `isObservableArray(v)`, `isComputed(v)`, `isPureComputed(v)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thomas-siegfried/tapout",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,7 +30,9 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "llms.txt",
+    "decorator-config.md"
   ],
   "scripts": {
     "build": "tsc",

package/src/wireParams.ts

@@ -7,6 +7,18 @@ import { addDisposeCallback } from './domNodeDisposal.js';
 
 const SKIP_KEYS = new Set(['$raw']);
 
+function getWritableChildTarget(instance: object, key: string): Observable<unknown> | Computed<unknown> | undefined {
+  const decorated = getObservable(instance, key);
+  if (decorated instanceof Observable) return decorated;
+  if (decorated instanceof Computed && decorated.hasWriteFunction) return decorated;
+
+  const directValue = (instance as Record<string, unknown>)[key];
+  if (directValue instanceof Observable) return directValue;
+  if (directValue instanceof Computed && directValue.hasWriteFunction) return directValue;
+
+  return undefined;
+}
+
 export interface WireParamsResult {
   subscriptions: Subscription<unknown>[];
 }
@@ -22,8 +34,8 @@ export function wireParams(
     if (SKIP_KEYS.has(key)) continue;
 
     const paramValue = params[key];
-    const childObs = getObservable(instance, key);
-    const childIsReactive = childObs !== undefined && isSubscribable(childObs);
+    const childTarget = getWritableChildTarget(instance, key);
+    const childIsReactive = childTarget !== undefined && isSubscribable(childTarget);
 
     if (paramValue instanceof Observable) {
       if (childIsReactive) {
@@ -32,9 +44,17 @@ export function wireParams(
         (instance as Record<string, unknown>)[key] = paramValue.get();
       }
     } else if (paramValue instanceof Computed) {
-      (instance as Record<string, unknown>)[key] = paramValue.get();
+      if (childTarget) {
+        childTarget.set(paramValue.get());
+      } else {
+        (instance as Record<string, unknown>)[key] = paramValue.get();
+      }
       const sub = paramValue.subscribe((newValue: unknown) => {
-        (instance as Record<string, unknown>)[key] = newValue;
+        if (childTarget) {
+          childTarget.set(newValue);
+        } else {
+          (instance as Record<string, unknown>)[key] = newValue;
+        }
       });
       subscriptions.push(sub);
       if (element) {