mobx-mantle 0.3.6 → 0.6.1

package/README.md

@@ -1,6 +1,6 @@
 # MobX Mantle
 
-A lightweight library for building React components with a class-based API and MobX reactivity built in. Get full access to the React ecosystem, with better access to vanilla JS libraries, and simpler overall DX for both.
+A lightweight library for building React components with a familiar class-based API and MobX reactivity built in. Get full access to the React ecosystem, with better access to vanilla JS libraries, and simpler overall DX for both.
 
 ## Why
 
@@ -14,23 +14,45 @@ The goal is to give React developers a way to build components using patterns co
 npm install mobx-mantle
 ```
 
-Requires React 17+, MobX 6+, and mobx-react-lite 3+.
+Requires React 18+ and MobX 6+. (No other dependencies — Mantle ships its own observer implementation.)
+
+## Take it for a spin
+
+Want to try Mantle before adding it to a project? Clone the repo and run the
+playground — a live Vite app with example components you can edit and watch
+update instantly:
+
+```bash
+git clone https://github.com/craigthings/mobx-mantle
+cd mobx-mantle
+npm install
+npm run dev
+```
+
+Open the URL Vite prints (usually http://localhost:5173).
+
+- The playground lives in [`playground/`](playground/); `main.tsx` renders the
+  demos (`Greeting`, `Todo`, and a `Counter` you can wire in).
+- The demos import Mantle straight from `src/`, so editing **either a demo or the
+  library source** hot-reloads in the browser — a fast loop for poking at how it
+  works.
+- To change something: edit any file in `playground/`, or drop your own
+  component into `App` in `playground/main.tsx`. It runs in React StrictMode, so
+  you'll see the mount/remount behavior too.
+
+Curious how it works under the hood? See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ## Basic Example
 
 ```tsx
-import { View, createView } from 'mobx-mantle';
+import { Component, createComponent } from 'mobx-mantle';
 
 interface CounterProps {
   initial: number;
 }
 
-class Counter extends View<CounterProps> {
-  count = 0;
-
-  onCreate() {
-    this.count = this.props.initial;
-  }
+class Counter extends Component<CounterProps> {
+  count = this.props.initial;
 
   increment() {
     this.count++;
@@ -45,10 +67,10 @@ class Counter extends View<CounterProps> {
   }
 }
 
-export default createView(Counter);
+export default createComponent(Counter);
 ```
 
-**Everything is reactive by default.** All properties become observable, getters become computed, and methods become auto-bound actions. No annotations needed.
+**Everything is reactive by default.** All properties become observable, getters become computed, and methods become auto-bound. A method called inside a render, computed, or reaction keeps its observable reads tracked; elsewhere its synchronous mutations are batched as an action. No annotations needed.
 
 > Want explicit control? See [Decorators](#decorators) below to opt into manual annotations.
 
@@ -80,7 +102,7 @@ toggle(id: number) {    // automatically bound to this
 **React to changes explicitly:**
 ```tsx
 onMount() {
-  return reaction(
+  this.watch(
     () => this.props.filter,
     (filter) => this.applyFilter(filter)
   );
@@ -91,40 +113,74 @@ onMount() {
 
 | Method | When |
 |--------|------|
-| `onCreate()` | Instance created, props available |
+| `onCreate()` | Instance created, props available, before first render. Derive initial state here (synchronous only). |
 | `onLayoutMount()` | DOM ready, before paint. Return a cleanup function (optional). |
-| `onMount()` | Component mounted, after paint. Return a cleanup function (optional). |
+| `onMount()` | Component mounted, after paint. The default home for watchers, effects, and resource acquisition. Return a cleanup function (optional). |
 | `onUpdate()` | After every render (via `useEffect`). |
 | `onUnmount()` | Component unmounting. Called after cleanups (optional). |
 | `render()` | On mount and updates. Return JSX. |
 
+**The rule of thumb:** everything goes in `onMount()`; derive initial state in `onCreate()`. In development, React StrictMode may clean up and re-run `onLayoutMount`/`onMount` while retaining the same component model and DOM refs. Pre-mount `watch`/`effect` declarations are automatically re-created during that effect replay. Plain `addCleanup` registrations are not; Mantle warns if one is registered before mount. This is different from a real removal (`{show && <Thing />}`, a changed `key`, navigation), which discards the model and constructs a new one if it is rendered again.
+
+**Resource ownership:** acquire and release an external resource through the same mechanism. If `onLayoutMount`/`onMount` creates an observer, listener, or timer, return its cleanup from that same method. If a callback ref acquires the resource, the callback must release it when React passes `null`. Do not acquire in a ref callback and disconnect from a mount cleanup: StrictMode can replay the cleanup without replaying the ref callback.
+
+### Initial State From Props
+
+`this.props` is available during class field initialization. Use this for simple initial state derived from props:
+
+```tsx
+class Editor extends Component<{ defaultValue: string }> {
+  value = this.props.defaultValue;
+}
+```
+
+Use `onCreate()` for more complex conditional setup needed before the first render:
+
+```tsx
+class Editor extends Component<{ defaultValue?: string; mode: 'plain' | 'rich' }> {
+  value = '';
+
+  onCreate() {
+    if (this.props.mode === 'rich') {
+      this.value = normalizeRichText(this.props.defaultValue ?? '');
+    } else {
+      this.value = this.props.defaultValue ?? '';
+    }
+  }
+}
+```
+
+Most components should not define a constructor. If you do, call `super(props)` before accessing `this.props`.
+
 ### Watching State
 
-Use `this.watch` to react to state changes. Watchers are automatically disposed on unmount.
+Use `this.watch` to react to state changes. Declare watchers in `onMount()` — they're automatically disposed on unmount, and `onMount` re-runs if the component remounts, so the contract is React-native and StrictMode-safe.
+
+Coming from Vue or Svelte, you may reach for `onCreate()` instead — that works too: watchers declared there are automatically re-created on remount. The only behavioral difference is timing: `onCreate` watchers come alive when the component commits, just before the first paint. `fireImmediately` and `effect`'s initial pass run at that point — after the first render, before the user sees anything. (Registrations are recorded during construction but not started, so renders React throws away — Suspense, interrupted transitions — never leak watchers. It also means the first render cannot depend on state a watcher or effect sets; for deriving state, prefer a computed getter.)
 
 ```tsx
 this.watch(
-  () => expr,           // reactive expression (getter)
-  (value, prev) => {},  // callback when expression result changes
-  options?              // optional: { delay, fireImmediately }
-)
+  () => this.query,                       // expression to track
+  (query, prev) => this.search(query),    // runs when result changes
+  { delay: 300, fireImmediately: true }   // wait 300ms before running + run on setup
+);
 ```
 
 **Options:**
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `delay` | `number` | — | Debounce the callback by N milliseconds |
+| `delay` | `number` | — | Wait N ms after a change before running once; changes in between are batched (MobX `reaction` delay, not a debounce — use `withDebounce` for that) |
 | `fireImmediately` | `boolean` | `false` | Run callback immediately with current value |
 
 **Basic example:**
 
 ```tsx
-class SearchView extends View<Props> {
+class Search extends Component<Props> {
   query = '';
   results: string[] = [];
 
-  onCreate() {
+  onMount() {
     this.watch(
       () => this.query,
       async (query) => {
@@ -138,20 +194,12 @@ class SearchView extends View<Props> {
 }
 ```
 
-**Multiple watchers:**
-
-```tsx
-onCreate() {
-  this.watch(() => this.props.filter, (filter) => this.applyFilter(filter));
-  this.watch(() => this.props.sort, (sort) => this.applySort(sort));
-  this.watch(() => this.props.page, (page) => this.fetchPage(page));
-}
-```
+Call `this.watch` as many times as you need — each watcher is tracked and disposed independently.
 
-**Early disposal:**
+**Early disposal** (works the same for `effect`):
 
 ```tsx
-onCreate() {
+onMount() {
   const stop = this.watch(() => this.props.token, (token) => {
     this.authenticate(token);
     stop(); // only needed once
@@ -159,47 +207,94 @@ onCreate() {
 }
 ```
 
-### Props Reactivity
+`this.watch` wraps MobX's `reaction` with automatic lifecycle disposal and remount-safe re-creation. For advanced MobX patterns (`when`, custom schedulers), use MobX directly and return a dispose function from `onMount`.
 
-`this.props` is reactive: your component re-renders when accessed props change.
+### Effects
 
-**Option 1: `this.watch`** — the recommended way to react to state changes:
+Use `this.effect` to run a side effect that auto-tracks dependencies. It runs immediately and re-runs whenever any accessed observable changes.
 
 ```tsx
-onCreate() {
-  this.watch(
-    () => this.props.filter,
-    (filter) => this.applyFilter(filter)
-  );
+this.effect(() => {
+  document.title = `${this.count} items`;   // auto-tracks this.count
+  return () => { /* cleanup */ };            // optional, runs before each re-run
+}, { delay: 100 });                          // optional delay: batches changes within 100ms
+```
+
+**When to use which:**
+
+| Method | Best for |
+|--------|----------|
+| `effect(fn)` | Simple sync: DOM updates, logging, derived side effects |
+| `watch(expr, fn)` | Complex side effects with explicit triggers: API calls, debounced actions |
+
+`effect` auto-tracks all accessed state, which can lead to unexpected re-runs in complex scenarios. For side effects where you want explicit control over what triggers re-runs, prefer `watch`.
+
+**Example:**
+
+```tsx
+class Counter extends Component<Props> {
+  count = 0;
+
+  onMount() {
+    // Runs immediately, re-runs when this.count changes
+    this.effect(() => {
+      const handler = () => console.log('clicked at count:', this.count);
+      window.addEventListener('click', handler);
+
+      // Cleanup runs before each re-run and on unmount
+      return () => window.removeEventListener('click', handler);
+    });
+  }
 }
 ```
 
-Watchers are automatically disposed on unmount. No cleanup needed.
+Early disposal works the same as `watch` — the returned `stop()` function tears the effect down early.
+
+### Cleanup
 
-**Option 2: `reaction`** — for advanced MobX patterns (autorun, when, custom schedulers):
+Use `this.addCleanup` to register any cleanup function that should run automatically on unmount. This is useful for subscriptions, event listeners, timers, observers, and third-party libraries.
 
 ```tsx
 onMount() {
-  return reaction(
-    () => this.props.filter,
-    (filter) => this.applyFilter(filter)
-  );
+  this.addCleanup(store.subscribe(this.handleChange));
+
+  window.addEventListener('resize', this.handleResize);
+  this.addCleanup(() => window.removeEventListener('resize', this.handleResize));
+
+  const id = setInterval(this.tick, 1000);
+  this.addCleanup(() => clearInterval(id));
 }
 ```
 
-**Option 3: `onUpdate`** — imperative hook after each render (requires manual dirty-checking):
+`addCleanup` returns a function you can call for early cleanup. `watch()` and `effect()` use the same automatic cleanup behavior internally.
+
+> **Note:** `addCleanup` registrations are one-shot — unlike `watch`/`effect`, they are not re-created if the component remounts. Acquire resources in `onMount()` (which re-runs on remount), or use `this.effect()` when setup must happen at creation — its setup/teardown pair is remount-safe. Mantle warns in development if `addCleanup` is called before mount.
+
+### Props Reactivity
+
+`this.props` is reactive: your component re-renders when accessed props change.
+
+**Option 1: `this.watch`** — the recommended way to react to state changes:
 
 ```tsx
-onUpdate() {
-  if (this.props.filter !== this.lastFilter) {
-    this.lastFilter = this.props.filter;
-    this.applyFilter(this.props.filter);
-  }
+onMount() {
+  this.watch(
+    () => this.props.filter,
+    (filter) => this.applyFilter(filter)
+  );
 }
 ```
 
+Watchers are automatically disposed on unmount and re-created on remount. No cleanup needed.
+
+**Option 2: raw MobX** — for advanced patterns (`autorun`, `when`, custom schedulers), call MobX directly in `onMount` and return the disposer.
+
+**Option 3: `onUpdate`** — imperative hook after each render; requires manual dirty-checking against the previous value.
+
 Or access props directly in `render()` and MobX handles re-renders when they change.
 
+> **Performance note:** a prop change costs exactly one render when `render()` reads props directly. A computed getter *over props* read in `render()` can add one extra render before paint — what's painted is always correct. If a hot component renders twice per prop change, that's the first thing to check.
+
 ## Patterns
 
 ### Combined (default)
@@ -207,7 +302,7 @@ Or access props directly in `render()` and MobX handles re-renders when they cha
 State, logic, and template in one class:
 
 ```tsx
-class Todo extends View<Props> {
+class Todo extends Component<Props> {
   todos: TodoItem[] = [];
   input = '';
 
@@ -231,7 +326,7 @@ class Todo extends View<Props> {
   }
 }
 
-export default createView(Todo);
+export default createComponent(Todo);
 ```
 
 ### Separated
@@ -239,7 +334,7 @@ export default createView(Todo);
 ViewModel and template separate:
 
 ```tsx
-import { ViewModel, createView } from 'mobx-mantle';
+import { ViewModel, createComponent } from 'mobx-mantle';
 
 class Todo extends ViewModel<Props> {
   todos: TodoItem[] = [];
@@ -255,7 +350,7 @@ class Todo extends ViewModel<Props> {
   }
 }
 
-export default createView(Todo, (vm) => (
+export default createComponent(Todo, (vm) => (
   <div>
     <input value={vm.input} onChange={vm.setInput} />
     <button onClick={vm.add}>Add</button>
@@ -264,14 +359,179 @@ export default createView(Todo, (vm) => (
 ));
 ```
 
+## Services
+
+Configure your application's resolver once, then declare services as fields:
+
+```tsx
+import { Component, configure, createComponent, inject } from 'mobx-mantle';
+import { container } from 'tsyringe';
+
+configure({ resolveService: token => container.resolve(token) });
+
+class ReportsComponent extends Component {
+  preferences = inject(PreferencesService);
+  reporting = inject(ReportingAgencyService);
+
+  render() {
+    return <div>{this.reporting.title}</div>;
+  }
+}
+
+const Reports = createComponent(ReportsComponent);
+root.render(<Reports />);
+```
+
+Class tokens infer the service type. For an interface, create a token with
+`createServiceToken<MyService>('MyService')` and register it with your resolver.
+Mantle works with any compatible resolver; tsyringe is optional.
+
+### Choosing between `inject()` and `this.inject()`
+
+Use `inject()` when setting up your component or behavior, either in a field
+declaration or in `onCreate`. Usually, you can get the service once and use that
+field whenever you need it:
+
+```ts
+preferences = inject(PreferencesService);
+
+onClick() {
+  this.preferences.save();
+}
+```
+
+If you need to get a service later, such as when a button is clicked or after an
+`await`, use `this.inject()` instead:
+
+```ts
+onClick() {
+  const reporting = this.inject(ReportingAgencyService);
+  reporting.open();
+}
+```
+
+`this.inject()` also works during setup. Both versions are available to Components
+and Behaviors, including nested behaviors and those used through `useBehavior()`.
+
+### How services are shared
+
+Your resolver decides whether to create a service or return an existing one.
+Mantle asks it each time you call either version of `inject()`, and returns the
+object it gives back. Caching and cleanup are also up to your resolver.
+
+Mantle keeps service fields out of its automatic MobX setup. The service's own
+observable state still works normally. If you use decorators, leave the service
+field undecorated. An injected service that is itself a Behavior won't be mounted
+or unmounted by Mantle. Services must be objects or functions. To provide a simple
+setting such as a string or number, put it in an object.
+
+Set up `configure({ resolveService })` before creating components. If one part of
+your app needs different services, wrap it in a `ServiceProvider resolve={resolve}`.
+Components inside that provider use its resolver instead of the default.
+
+Each component or behavior remembers the resolver it started with. Changing the
+configuration or provider won't switch existing instances over. Recreate them to
+use the new resolver. If a provider can't supply a service, Mantle reports the
+error rather than trying the application default.
+
+You can keep using your existing tsyringe container and its service registrations.
+Mantle's field injection doesn't need extra decorator metadata from the compiler.
+Your tsyringe services still need whatever decorator and metadata setup they
+already use.
+
+### Creating a model outside React
+
+If you're creating a model or behavior yourself with `new`, use
+`withInjectionScope()` to make the resolver available to imported `inject()`:
+
+```ts
+const model = withInjectionScope(resolve, () => new ReportsComponent());
+```
+
+Pass `undefined` for `resolve` to use the default from `configure()`. This creates
+the model but doesn't render it or run its mount lifecycle. Keep the setup inside
+the callback synchronous. For code that runs after an `await`, use `this.inject()`.
+
+If your model only uses `this.inject()`, you can use `new` directly with the
+configured default, without `withInjectionScope()`.
+
+## Testing
+
+Use `mobx-mantle/testing` to replace services or an entire model. Create a fresh
+scope per test and register substitutes before rendering.
+
+### Real model, fake services
+
+```tsx
+import { createTestScope } from 'mobx-mantle/testing';
+
+const scope = createTestScope();
+scope.service(ReportingAgencyService, fakeReportingService);
+scope.service(PreferencesService, fakePreferencesService);
+
+render(<scope.Provider><Reports /></scope.Provider>);
+```
+
+If a service hasn't been registered, you'll get an error, even if you've configured an application resolver.
+To reuse existing container mocks, supply a fallback:
+
+```ts
+const scope = createTestScope({
+  resolve: token => container.resolve(token),
+});
+```
+
+Test-local registrations take precedence. A shared render helper can apply the
+Provider internally so individual tests need no JSX setup.
+
+### Only the view
+
+To test how a view looks and responds without running the model behind it, give
+it some test values and functions instead.
+
+If your view is written separately from the model, the test uses that view. If
+the JSX lives in the model's `render()` method, you'll need to provide JSX for the
+test, as shown below. That tests the JSX you provide, not the original `render()`
+method. To test the original method, keep the real model and mock its services
+instead.
+
+```tsx
+const scope = createTestScope();
+scope.model(ReportsComponent, () => ({
+  reporting: fakeReportingService,
+}), {
+  template: model => <div>{model.reporting.title}</div>,
+});
+
+render(<scope.Provider><Reports /></scope.Provider>);
+```
+
+### Substitution rules
+
+- The state factory runs for each instance and may be retried by React. Return
+  fresh mutable state unless sharing is intentional.
+- Fields are observable by reference. Supplied objects retain their identity and
+  existing observability; nested plain objects are not made observable. Use
+  `runInAction` when changing a mounted substitute's fields.
+- Supply data and callbacks, not lifecycle methods, getters, framework members
+  or an original model instance. Missing members stay `undefined`.
+- `findParent(Model)` and `isModel(instance, Model)` recognize substitutes;
+  `instanceof Model` does not. Props, rendering, forwarded DOM refs and cleanup
+  retain their normal framework behavior.
+- Providers snapshot registrations at mount. Remount to apply later registrations.
+
+`ModelProvider` exposes the underlying substitution mechanism for custom test
+helpers. The testing package does not bundle a test runner or DI container.
+
 ## Decorators
 
-For teams that prefer explicit annotations over auto-observable, Mantle provides its own decorators. These are lightweight metadata collectors. No `accessor` keyword required.
+Use Mantle's decorators when you prefer to choose which fields are reactive.
+Methods remain automatically bound, and `this.props` is always reactive.
 
 ```tsx
-import { View, createView, observable, action, computed } from 'mobx-mantle';
+import { Component, createComponent, observable, action, computed } from 'mobx-mantle';
 
-class Todo extends View<Props> {
+class Todo extends Component<Props> {
   @observable todos: TodoItem[] = [];
   @observable input = '';
 
@@ -289,49 +549,66 @@ class Todo extends View<Props> {
   }
 }
 
-export default createView(Todo);
+export default createComponent(Todo);
 ```
 
-**Key differences from auto-observable mode:**
-- Only decorated fields are reactive (undecorated fields are inert)
-- Methods are still auto-bound for stable `this` references
+### Compiler setup
+
+Choose one decorator mode for your project:
+
+- **TypeScript legacy:** set `experimentalDecorators: true`. Mantle needs no
+  metadata polyfill. Tsyringe services may still require `reflect-metadata` and
+  `emitDecoratorMetadata`.
+- **TC39:** omit that flag, include `ESNext.Decorators` or `ESNext` in `lib`, and
+  load a `Symbol.metadata` polyfill before decorated modules.
 
 ### Available Decorators
 
 | Decorator | Purpose |
 |-----------|---------|
 | `@observable` | Deep observable field |
+| `@observable.deep` | Explicit deep observable field |
 | `@observable.ref` | Reference-only observation |
 | `@observable.shallow` | Shallow observation (add/remove only) |
 | `@observable.struct` | Structural equality comparison |
-| `@action` | Action method (auto-bound) |
-| `@computed` | Computed getter (optional; getters are computed by default) |
+| `@action` | Action method (auto-bound) or arrow-function field |
+| `@computed` | Computed getter |
+
+### Supported members and inheritance
+
+- Decorate public instance fields, prototype methods and getters in Components
+  and Behaviors. Undecorated fields remain nonreactive.
+- Use ordinary fields with `@observable`, without `accessor`. Static/private
+  members, parameter decorators and TC39 auto-accessors are not supported by
+  Mantle's decorators.
+- Overrides of annotated methods/getters retain their annotation. Repeating it
+  is allowed; changing it is rejected. Do not redeclare inherited observable fields.
+- Use one decorator family per model hierarchy. Do not mix Mantle and raw MobX
+  annotations on the same instance.
 
-### MobX Decorators (Legacy)
+### MobX decorators
 
-If you prefer using MobX's own decorators (requires `accessor` keyword for TC39):
+You can instead use MobX's own decorators with auto-observable disabled. MobX's
+TC39 observable fields require `accessor`:
 
 ```tsx
 import { observable, action } from 'mobx';
-import { configure } from 'mobx-mantle';
+import { Component, configure, createComponent } from 'mobx-mantle';
 
-// Disable auto-observable globally
 configure({ autoObservable: false });
 
-class Todo extends View<Props> {
-  @observable accessor todos: TodoItem[] = [];  // note: accessor required
+class Todo extends Component<Props> {
+  @observable accessor todos: TodoItem[] = [];
   @action add() { /* ... */ }
 }
 
-export default createView(Todo);
-```
-
-Note: `this.props` is always reactive regardless of decorator mode.
-
+export default createComponent(Todo);
+```
+
 ## Refs
 
 ```tsx
-class FormView extends View<Props> {
+class Form extends Component<Props> {
   inputRef = this.ref<HTMLInputElement>();
 
   onMount() {
@@ -349,13 +626,13 @@ class FormView extends View<Props> {
 Expose a DOM element to parent components via `this.forwardRef`:
 
 ```tsx
-class FancyInput extends View<InputProps> {
+class FancyInput extends Component<InputProps> {
   render() {
     return <input ref={this.forwardRef} className="fancy-input" />;
   }
 }
 
-export default createView(FancyInput);
+export default createComponent(FancyInput);
 
 // Parent can now get a ref to the underlying input:
 function Parent() {
@@ -370,48 +647,12 @@ function Parent() {
 }
 ```
 
-## Reactions
-
-```tsx
-class SearchView extends View<Props> {
-  query = '';
-  results: string[] = [];
-
-  onMount() {
-    const dispose = reaction(
-      () => this.query,
-      async (query) => {
-        if (query.length > 2) {
-          this.results = await searchApi(query);
-        }
-      },
-      { delay: 300 }
-    );
-
-    return dispose;
-  }
-
-  setQuery(e: React.ChangeEvent<HTMLInputElement>) {
-    this.query = e.target.value;
-  }
-
-  render() {
-    return (
-      <div>
-        <input value={this.query} onChange={this.setQuery} />
-        <ul>{this.results.map(r => <li key={r}>{r}</li>)}</ul>
-      </div>
-    );
-  }
-}
-```
-
 ## React Hooks
 
 Hooks work inside `render()`:
 
 ```tsx
-class DataView extends View<{ id: string }> {
+class DataView extends Component<{ id: string }> {
   render() {
     const navigate = useNavigate();
     const { data, isLoading } = useQuery({
@@ -435,7 +676,7 @@ class DataView extends View<{ id: string }> {
 Imperative libraries become straightforward:
 
 ```tsx
-class ChartView extends View<{ data: number[] }> {
+class Chart extends Component<{ data: number[] }> {
   containerRef = this.ref<HTMLDivElement>();
   chart: Chart | null = null;
 
@@ -444,15 +685,12 @@ class ChartView extends View<{ data: number[] }> {
       data: this.props.data,
     });
 
-    const dispose = reaction(
+    this.watch(
       () => this.props.data,
       (data) => this.chart?.update(data)
     );
 
-    return () => {
-      dispose();
-      this.chart?.destroy();
-    };
+    return () => this.chart?.destroy();
   }
 
   render() {
@@ -483,9 +721,183 @@ function ChartView({ data }) {
 
 Split effects, multiple refs, dependency tracking: all unnecessary with Mantle.
 
+## Side by Side
+
+Each example shows the same component in Mantle and React hooks. As components grow, hooks require an increasingly complex web of dependency arrays, memoized callbacks, and mirrored refs that you have to maintain by hand — miss one and you get a silent bug. These comparisons show how Mantle helps to significantly sidesteps that overhead.
+
+### Copy to Clipboard
+
+A small component with async logic, a reset timer, and cleanup. The kind of thing every project has:
+
+```tsx
+class CopyButton extends Component<{ text: string; label?: string }> {
+  copied = false;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  async copy() {
+    await navigator.clipboard.writeText(this.props.text);
+    this.copied = true;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => (this.copied = false), 2000);
+  }
+
+  onUnmount() {
+    if (this.timer) clearTimeout(this.timer);
+  }
+
+  render() {
+    return (
+      <button onClick={this.copy}>
+        {this.copied ? 'Copied!' : (this.props.label ?? 'Copy')}
+      </button>
+    );
+  }
+}
+```
+
+Compare to hooks:
+
+```tsx
+function CopyButton({ text, label }: { text: string; label?: string }) {
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const copy = useCallback(async () => {
+    await navigator.clipboard.writeText(text);
+    setCopied(true);
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => setCopied(false), 2000);
+  }, [text]); // forget `text` here and you copy stale values
+
+  useEffect(() => {
+    return () => { if (timerRef.current) clearTimeout(timerRef.current); };
+  }, []);
+
+  return (
+    <button onClick={copy}>
+      {copied ? 'Copied!' : (label ?? 'Copy')}
+    </button>
+  );
+}
+```
+
+The hooks version needs `useState`, `useRef`, `useCallback` with a dependency array, and a separate `useEffect` for cleanup. Miss `text` in the dependency array and you get a stale closure bug. In Mantle, `this.props.text` is always current.
+
+### Inline List Editor
+
+A component with multiple interaction modes — adding, editing, keyboard shortcuts, and paste handling:
+
+```tsx
+class ListEditor extends Component<{ items: string[]; onChange: (items: string[]) => void }> {
+  newItem = '';
+  editingIndex: number | null = null;
+  editValue = '';
+
+  add() {
+    if (!this.newItem.trim()) return;
+    this.props.onChange([...this.props.items, this.newItem.trim()]);
+    this.newItem = '';
+  }
+
+  remove(index: number) {
+    this.props.onChange(this.props.items.filter((_, i) => i !== index));
+  }
+
+  startEdit(index: number) {
+    this.editingIndex = index;
+    this.editValue = this.props.items[index];
+  }
+
+  saveEdit() {
+    if (this.editingIndex === null) return;
+    const updated = [...this.props.items];
+    updated[this.editingIndex] = this.editValue.trim();
+    this.props.onChange(updated);
+    this.editingIndex = null;
+  }
+
+  cancelEdit() {
+    this.editingIndex = null;
+  }
+
+  handleKeyDown(e: React.KeyboardEvent) {
+    if (e.key === 'Enter') this.add();
+  }
+
+  handleEditKeyDown(e: React.KeyboardEvent) {
+    if (e.key === 'Enter') this.saveEdit();
+    if (e.key === 'Escape') this.cancelEdit();
+  }
+
+  handlePaste(e: React.ClipboardEvent) {
+    const lines = e.clipboardData.getData('text').split(/\n/).map(l => l.trim()).filter(Boolean);
+    if (lines.length <= 1) return;
+    e.preventDefault();
+    this.props.onChange([...this.props.items, ...lines]);
+  }
+
+  render() { /* ... */ }
+}
+```
+
+Compare to hooks:
+
+```tsx
+function ListEditor({ items, onChange }: { items: string[]; onChange: (items: string[]) => void }) {
+  const [newItem, setNewItem] = useState('');
+  const [editingIndex, setEditingIndex] = useState<number | null>(null);
+  const [editValue, setEditValue] = useState('');
+
+  const add = useCallback(() => {
+    if (!newItem.trim()) return;
+    onChange([...items, newItem.trim()]);
+    setNewItem('');
+  }, [newItem, items, onChange]);
+
+  const remove = useCallback((index: number) => {
+    onChange(items.filter((_, i) => i !== index));
+  }, [items, onChange]);
+
+  const startEdit = useCallback((index: number) => {
+    setEditingIndex(index);
+    setEditValue(items[index]);
+  }, [items]);
+
+  const saveEdit = useCallback(() => {
+    if (editingIndex === null) return;
+    const updated = [...items];
+    updated[editingIndex] = editValue.trim();
+    onChange(updated);
+    setEditingIndex(null);
+  }, [editingIndex, editValue, items, onChange]);
+
+  const cancelEdit = useCallback(() => setEditingIndex(null), []);
+
+  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
+    if (e.key === 'Enter') add();
+  }, [add]);
+
+  const handleEditKeyDown = useCallback((e: React.KeyboardEvent) => {
+    if (e.key === 'Enter') saveEdit();
+    if (e.key === 'Escape') cancelEdit();
+  }, [saveEdit, cancelEdit]);
+
+  const handlePaste = useCallback((e: React.ClipboardEvent) => {
+    const lines = e.clipboardData.getData('text').split(/\n/).map(l => l.trim()).filter(Boolean);
+    if (lines.length <= 1) return;
+    e.preventDefault();
+    onChange([...items, ...lines]);
+  }, [items, onChange]);
+
+  return /* ... */;
+}
+```
+
+3 `useState`, 7 `useCallback` with dependency chains where each callback depends on others. `handleKeyDown` depends on `add`, which depends on `newItem`, `items`, and `onChange`. Miss one and you get stale state. The Mantle version is just methods calling `this` — no dependency graph to maintain.
+
 ## Error Handling
 
-Render errors propagate to React error boundaries as usual. Lifecycle errors (`onLayoutMount`, `onMount`, `onUpdate`, `onUnmount`, `watch`) in both Views and Behaviors are caught and routed through a configurable handler.
+Render errors propagate to React error boundaries as usual. Lifecycle errors (`onLayoutMount`, `onMount`, `onUpdate`, `onUnmount`, `watch`) in both Components and Behaviors are caught and routed through a configurable handler.
 
 By default, errors are logged to `console.error`. Configure a global handler to integrate with your error reporting:
 
@@ -495,7 +907,7 @@ import { configure } from 'mobx-mantle';
 configure({
   onError: (error, context) => {
     // context.phase: 'onLayoutMount' | 'onMount' | 'onUpdate' | 'onUnmount' | 'watch'
-    // context.name: class name of the View or Behavior
+    // context.name: class name of the Component or Behavior
     // context.isBehavior: true if the error came from a Behavior
     Sentry.captureException(error, {
       tags: { phase: context.phase, component: context.name },
@@ -504,13 +916,36 @@ configure({
 });
 ```
 
-Behavior errors are isolated. A failing Behavior won't prevent sibling Behaviors or the parent View from mounting.
+Behavior errors are isolated. A failing Behavior won't prevent sibling Behaviors or the parent Component from mounting.
+
+## MobX Action Enforcement
+
+Mantle preserves the host application's MobX action policy by default (`manageMobxActions: false`). Importing or constructing a Mantle model does not change it. MobX can still warn about changes made outside actions during development. These warnings don't stop your code.
+
+Synchronous model methods and lifecycle callbacks batch their writes as actions. Render helpers retain tracked reads. Watch callbacks are reaction actions; effect bodies stay tracked and should wrap their writes explicitly. An async method leaves its action when it reaches an `await`:
+
+```tsx
+import { runInAction } from 'mobx';
+async load() {
+  const result = await fetchReports();
+  runInAction(() => { this.reports = result; });
+}
+```
+
+The built-in behaviors handle their own async/timer writes. To deliberately keep the permissive pre-0.6 behavior, configure it **before the first component or behavior is created**, including module-level behavior construction:
+
+```tsx
+import { configure } from 'mobx-mantle';
+configure({ manageMobxActions: true });
+```
+
+This opt-in sets `enforceActions: 'never'` globally for that MobX instance. Providers cannot scope this policy. Setting the default to false does not undo configuration another library has already applied.
 
-## Behaviors (Experimental)
+## Behaviors
 
-> ⚠️ **Experimental:** The Behaviors API is still evolving and may change in future releases.
+Behaviors are a supported feature for reusable React/MobX state and logic. The core API covers creation, nesting, lifecycle cleanup, reactive arguments, and hosting through Components or `useBehavior()`. MobX Mantle remains pre-1.0; supported means this is an API intended for normal application use and ongoing maintenance, not a promise that no future release can change it.
 
-Behaviors are reusable pieces of state and logic that can be shared across views. Define them as classes, wrap with `createBehavior()`, and use the resulting factory function in your Views.
+Behaviors are reusable pieces of state and logic that can be shared across components. Define them as classes, wrap with `createBehavior()`, and use the resulting factory function in your Components.
 
 ### Defining a Behavior
 
@@ -548,14 +983,27 @@ The naming convention:
 - **Class**: PascalCase (`WindowSizeBehavior`)
 - **Factory**: camelCase with `with` prefix (`withWindowSize`)
 
+Behavior methods have the same tracking-aware binding as Component methods. A
+read helper called from a render or computed remains inside that derivation:
+
+```tsx
+class BreakpointBehavior extends Behavior {
+  width = 0;
+  below(px: number) { return this.width < px; }
+}
+```
+
+`this.size.below(640)` therefore subscribes its caller to `width`; passing a
+mutating method as an event handler still keeps it bound and batches its writes.
+
 ### Using Behaviors
 
-Call the factory function (no `new` keyword) in your View. The `with` prefix signals that the View manages this behavior's lifecycle:
+Call the factory function (no `new` keyword) in your Component. The `with` prefix signals that the Component manages this behavior's lifecycle:
 
 ```tsx
 import { withWindowSize } from './withWindowSize';
 
-class Responsive extends View<Props> {
+class Responsive extends Component<Props> {
   windowSize = withWindowSize(768);
 
   render() {
@@ -568,12 +1016,12 @@ class Responsive extends View<Props> {
   }
 }
 
-export default createView(Responsive);
+export default createComponent(Responsive);
 ```
 
 ### Watching in Behaviors
 
-Behaviors can use `this.watch` just like Views:
+Behaviors can use `this.watch` just like Components:
 
 ```tsx
 class FetchBehavior extends Behavior {
@@ -583,6 +1031,9 @@ class FetchBehavior extends Behavior {
 
   onCreate(url: string) {
     this.url = url;
+  }
+
+  onMount() {
     this.watch(() => this.url, () => this.fetchData(), { fireImmediately: true });
   }
 
@@ -632,11 +1083,11 @@ export const withFetch = createBehavior(FetchBehavior);
 ```
 
 ```tsx
-import { View, createView } from 'mobx-mantle';
+import { Component, createComponent } from 'mobx-mantle';
 import { withFetch } from './FetchBehavior';
 import { withWindowSize } from './WindowSizeBehavior';
 
-class Dashboard extends View<Props> {
+class Dashboard extends Component<Props> {
   users = withFetch('/api/users', 10000);
   posts = withFetch('/api/posts');
   windowSize = withWindowSize(768);
@@ -651,25 +1102,271 @@ class Dashboard extends View<Props> {
   }
 }
 
-export default createView(Dashboard);
+export default createComponent(Dashboard);
+```
 
 ### Behavior Lifecycle
 
-Behaviors support the same lifecycle methods as Views:
+Behaviors support the same lifecycle methods as Components:
 
 | Method | When |
 |--------|------|
 | `onCreate(...args)` | Called during construction with the factory arguments |
-| `onLayoutMount()` | Called when parent View layout mounts (before paint). Return cleanup (optional). |
-| `onMount()` | Called when parent View mounts (after paint). Return cleanup (optional). |
-| `onUnmount()` | Called when parent View unmounts, after cleanups (optional). |
+| `onLayoutMount()` | Called when parent Component layout mounts (before paint). Return cleanup (optional). |
+| `onMount()` | Called when parent Component mounts (after paint). Return cleanup (optional). |
+| `onUnmount()` | Called when parent Component unmounts, after cleanups (optional). |
+
+React StrictMode replays the mount lifecycle with the same model and refs in
+development. Pair setup and teardown in the same lifecycle method so the
+second setup always reacquires what the first cleanup released. A real removal
+from the React tree destroys the model; rendering it later creates a new one.
+
+### Reactive Arguments
+
+A behavior's setup runs once, so a plain argument is a snapshot — frozen at construction. To pass a *live* value, pass a getter:
+
+```tsx
+class Dashboard extends Component<Props> {
+  frozen = withFetch('/api/users');            // frozen at construction
+  live   = withFetch(() => this.props.url);    // refetches when the prop changes
+}
+```
+
+**Consumer rule of thumb:** not sure which to pass? Pass the arrow — it's never wrong, only occasionally redundant. Reserve plain values for things you intend to freeze. (Parameters that don't accept getters are typed plain, so TypeScript tells you when the question even exists.)
+
+**Observable objects need none of this.** Reactivity lives in property reads, so an observable *object* (a store, another behavior) passes by reference and stays fully live — `withSync(this.settingsStore)` needs no arrow. The getter is only for primitives and computed expressions, which leave the reactive graph the moment they're evaluated. One footgun: the reference is captured once, so it survives *mutation* (`store.theme = 'dark'` ✅) but not *reassignment* of the field that held it (`this.settingsStore = newStore` ❌ — the behavior still holds the old object). If you reassign, pass a getter.
+
+**Authoring a behavior with live arguments:** `this.sync()` is an optional convenience shortcut for using `this.effect()` to keep a field synchronized with an input. It handles field initialization and one-way mirroring for you; use `effect()` directly when you need custom synchronization logic. Using `effect()`:
+
+```tsx
+class SearchBehavior extends Behavior {
+  query = '';
+
+  onCreate(getQuery: () => string) {
+    this.effect(() => {
+      this.query = getQuery();
+    });
+  }
+}
+```
+
+Using the `sync()` shortcut:
+
+```tsx
+class SearchBehavior extends Behavior {
+  query = '';
+
+  onCreate(getQuery: () => string) {
+    this.query = this.sync(getQuery);
+  }
+}
+```
+
+Both keep `query` following the getter. The effect first runs at mount;
+`sync()` also initializes the field after `onCreate()` completes, before the
+first render, then keeps it updated from mount onward.
+
+Type the input `MaybeGetter<T>` to accept either a fixed value or a live getter:
+
+```tsx
+import { Behavior, createBehavior, type MaybeGetter } from 'mobx-mantle';
+
+class FetchBehavior extends Behavior {
+  url = '';
 
+  onCreate(url: MaybeGetter<string>) {
+    this.url = this.sync(url);   // one-way mirror: argument → field
+    this.watch(() => this.url, (u) => this.fetchData(u), { fireImmediately: true });
+  }
+
+  refresh() {
+    this.fetchData(this.url);    // plain read — always current
+  }
+}
+export const withFetch = createBehavior(FetchBehavior);
+```
+
+A plain value just sits in the field; a getter drives a hidden effect that keeps the field updated (alive from mount, like `watch`/`effect`, StrictMode-safe). The sync is **one-way** — don't write to the field from outside; the next source change would overwrite it, and Mantle warns in development if you do.
+
+When passing a getter, assign `this.sync()` to a behavior field during initialization. The field receives its initial value after `onCreate()` completes. Use `toValue(argument)` if you need the input value immediately inside `onCreate()`.
+
+Two lighter alternatives when a mirror field is more than you need:
+
+- `this.watch(source, cb)` — a `MaybeGetter` is a valid watch source directly (a plain value dev-warns unless `fireImmediately`, since a constant watch can never fire).
+- `toValue(arg)` — unwrap in place: returns `arg()` if it's a getter, `arg` otherwise. For one-off reads and `effect` bodies, where calling the getter doubles as dependency tracking.
+
+This is the same convention Vue (`MaybeRefOrGetter` + `toValue`) and Solid (`MaybeAccessor` + `access`) converged on. One caveat: an argument that is legitimately a function (a callback, not a getter) can't also be a `MaybeGetter` — the two are indistinguishable at runtime, so choose per parameter which ones are reactive.
+
+#### Config-Object Behaviors
+
+Positional arguments are fine for one or two parameters. When a behavior takes more — or its signature will grow — take a single config object typed `MaybeGetter<Options>`. One arrow at the call site makes the whole bag live, and callbacks inside are safe (they're read, never called):
+
+```tsx
+interface SearchOptions {
+  query: string;
+  limit?: number;
+  onResult?: (items: string[]) => void;
+}
+
+class SearchBehavior extends Behavior {
+  opts!: SearchOptions;
+
+  onCreate(opts: MaybeGetter<SearchOptions>) {
+    this.opts = this.sync(opts);   // same one line as any other live argument
+    this.watch(() => this.opts.query, (q) => this.run(q));
+  }
+}
+export const withSearch = createBehavior(SearchBehavior);
+```
+
+```tsx
+class Page extends Component<Props> {
+  search = withSearch(() => ({ query: this.query, limit: 20 }));  // live bag — one arrow
+  fixed  = withSearch({ query: 'docs' });                          // deliberately frozen
+}
+```
+
+The bag object is re-created when its sources change, but watchers on individual keys (`() => this.opts.query`) still fire only when that key's value actually changes — MobX's value comparison absorbs the churn.
+
+### Nesting Behaviors
+
+Behaviors compose recursively: a behavior declared as a field of another behavior (or assigned in its `onCreate`) receives the full lifecycle relay. Children mount before their parent's `onMount` — so a parent can rely on live children — and tear down after their parent's `onUnmount`, in reverse order.
+
+```tsx
+class AutosaveBehavior extends Behavior {
+  saver = withAsync((url, data) => postJson(url, data)); // child: request state machine
+  timer!: IntervalBehavior;
+
+  onCreate(url: MaybeGetter<string>, data: () => unknown, interval = 5000) {
+    this.timer = withInterval(() => this.save(), interval); // child: scheduling
+  }
+
+  save() { /* diff + this.saver.run(...) */ }
+}
+export const withAutosave = createBehavior(AutosaveBehavior);
+```
+
+Two rules, both consistent with how Components collect behaviors:
+
+- **Underscore-prefixed fields are invisible** to collection — `_helper = withThing()` is not relayed.
+- **Late assignment isn't collected.** Components collect behaviors at construction; a behavior assigned to a Component field later (conditionally, lazily, or in the Component's `onCreate`) silently never mounts. Mantle warns in development when it finds one. (Inside a *behavior*, `onCreate` assignment is fine — behaviors scan after `onCreate` runs.)
+
+### Behaviors in Plain Function Components
+
+You don't have to adopt Mantle components to use behaviors. `useBehavior()` hosts any behavior inside an ordinary function component, with the same lifecycle relay (StrictMode-safe, watchers alive from commit, full teardown on unmount). Wrap the component in `observer()` so renders track the behavior's observables:
+
+```tsx
+import { useBehavior, observer } from 'mobx-mantle';
+import { withWindowSize } from 'mobx-mantle/behaviors';
+
+const Toolbar = observer(() => {
+  const size = useBehavior(() => withWindowSize());
+  return <div>{size.width} × {size.height}</div>;
+});
+```
+
+The factory runs once per mount lifetime. Because of that, getter arguments close over the first render — getters reading observables stay live, but getters reading the function component's own props go stale. Pass observable sources instead.
+
+This inverts the adoption story: logic written as a behavior runs in both worlds, and Mantle Components are simply the nicer host.
+
+### Built-in Behaviors
+
+`mobx-mantle/behaviors` ships a standard library of small behaviors, all with `MaybeGetter` arguments:
+
+`withEventListener`, `withInterval`, `withTimeout`, `withAsync`, `withFetch`, `withLocalStorage`, `withElementSize`, `withWindowSize`, `withMediaQuery`, `withDebounce`, `withThrottle`, `withDocumentTitle`, `withPageVisibility`, `withAutosave`.
+
+Several are themselves compositions — `withFetch` nests `withAsync`; `withWindowSize`, `withLocalStorage`, and `withPageVisibility` nest `withEventListener`; `withAutosave` nests `withInterval` + `withAsync` — the same nesting available to your own behaviors.
+
+```tsx
+import { withFetch, withMediaQuery } from 'mobx-mantle/behaviors';
+
+class Dashboard extends Component<Props> {
+  users = withFetch<User[]>(() => `/api/users?team=${this.props.teamId}`);
+  compact = withMediaQuery('(max-width: 768px)');
+
+  render() {
+    if (this.users.loading) return <Spinner />;
+    return <UserList users={this.users.data} compact={this.compact.matches} />;
+  }
+}
+```
+
+Element measurement uses the same ref objects as Components and owns its
+`ResizeObserver` through the layout lifecycle, including StrictMode replay.
+It reports the element's layout-space border box, so CSS transforms on the
+element or an ancestor do not change component
+breakpoints:
+
+```tsx
+import { withElementSize } from 'mobx-mantle/behaviors';
+
+class ResponsivePanel extends Component {
+  root = this.ref<HTMLDivElement>();
+  size = withElementSize(this.root);
+
+  get compact() {
+    return this.size.width !== null && this.size.width < 640;
+  }
+
+  render() {
+    return <div ref={this.root}>{this.compact ? <Compact /> : <Wide />}</div>;
+  }
+}
+```
+
+### What Behaviors Are Not For
+
+- **Behaviors cannot call hooks.** `useContext`, `useQuery`, and friends are render-scoped; behaviors live outside the render cycle. The blessed pattern: read the hook in `render()` and pass the value where it's needed.
+- **Division of labor:** behaviors own vanilla-JS integration, MobX-native logic, and cheaply-testable state machines; hooks own React-ecosystem bindings; `render()` is where the two meet.
+
+## Shared Stores
+
+A store that several windows must agree on — a theme, a navigation preference, anything a
+design tool's hosted frames or a second tab should follow — is shared once, at the entry point:
+
+```ts
+import { shareStores } from 'mobx-mantle';
+import { themeStore } from './themeStore';
+import { navPreferences } from './navPreferences';
+
+shareStores({ themeStore, navPreferences });
+```
+
+Every window that imports that module wires the same stores. Each window keeps its own
+instance; values are mirrored, identity is not shared, and nothing goes through a server or a
+parent document. The mechanics are the web's own answer for two windows, packaged: the store's
+observable fields are restored from `localStorage` at startup, published through a reaction to
+`localStorage` and a `BroadcastChannel`, and incoming changes from the channel or the `storage`
+event are applied inside an action. Echo loops are bounded because a window publishes only when
+its serialized state changed and applies only what differs from it.
+
+`shared(store, key, options)` shares one store under an explicit key; `options.fields` limits
+the shared fields (default: the store's own observable data fields, not getters or methods) and
+`options.persist: false` skips storage. `unshare(store)` stops the sync.
+
+**The one authoring rule: effects derive from state.** A change that arrives from another window
+sets fields directly, so anything the store does to the world — writing custom properties onto
+`document.documentElement`, updating a title — must be a `reaction`, an `autorun`, or a
+component's `watch`/`effect`, never a call inside a setter:
+
+```ts
+class ThemeStore {
+  theme = 'light';
+  constructor() {
+    makeAutoObservable(this);
+    autorun(() => document.documentElement.dataset.theme = this.theme); // repaints on any window's change
+  }
+  setTheme(theme: string) {
+    this.theme = theme; // no apply() here
+  }
+}
+```
 
 ## API
 
 ### `configure(config)`
 
-Set global defaults for all views. Settings can still be overridden per-view in `createView` options.
+Set global defaults for all components. Settings can still be overridden per-component in `createComponent` options.
 
 ```tsx
 import { configure } from 'mobx-mantle';
@@ -680,25 +1377,52 @@ configure({ autoObservable: false });
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `autoObservable` | `true` | Whether to automatically make View instances observable |
+| `autoObservable` | `true` | Whether to automatically make Component instances observable |
+| `cacheAnnotations` | `true` | Cache per-class annotation data (getters, methods) so repeated instantiations skip the prototype walk. Turn off only if class prototypes are mutated between instantiations. |
 | `onError` | `console.error` | Global error handler for lifecycle errors (see [Error Handling](#error-handling)) |
+| `manageMobxActions` | `false` | Preserve the host policy. Set true before first construction to opt into globally permissive actions (see [MobX Action Enforcement](#mobx-action-enforcement)). |
 
-### `View<P>` / `ViewModel<P>`
+### `Component<P>` / `ViewModel<P>`
 
-Base class for view components. `ViewModel` is an alias for `View`. Use it when separating the ViewModel from the template for semantic clarity.
+Base class for components. `ViewModel` is an alias for `Component`. Use it when separating the ViewModel from the template for semantic clarity.
 
 | Property/Method | Description |
 |-----------------|-------------|
-| `props` | Current props (reactive) |
+| `props` | Current props (reactive, available in field initializers) |
 | `forwardRef` | Ref passed from parent component (for ref forwarding) |
-| `onCreate()` | Called when instance created |
+| `getParent()` | Immediate ancestor in the live Mantle view tree, or `undefined` at the root |
+| `findParent(Type)` | Nearest parent matching a Mantle component/model class |
+| `getParents()` | Readonly array of all parents, ordered from the immediate parent toward the root |
+| `getRoot()` | Highest Mantle ancestor, or the current instance when already at the root |
+| `onCreate()` | Called when instance is created, before first render |
 | `onLayoutMount()` | Called before paint, return cleanup (optional) |
 | `onMount()` | Called after paint, return cleanup (optional) |
 | `onUpdate()` | Called after every render |
 | `onUnmount()` | Called on unmount, after cleanups (optional) |
 | `render()` | Return JSX (optional if using template) |
 | `ref<T>()` | Create a ref for DOM elements |
-| `watch(expr, callback, options?)` | Watch reactive expression, auto-disposed on unmount |
+| `addCleanup(fn)` | Register cleanup to run automatically on unmount |
+| `watch(source, callback, options?)` | Watch a reactive expression (or a `MaybeGetter` directly), auto-disposed on unmount, re-created on remount |
+| `effect(fn, options?)` | Run auto-tracked side effect, auto-disposed on unmount, re-created on remount |
+
+Ancestry follows the logical Mantle view tree. Plain React wrappers and fragments
+are transparent, portals preserve their logical ancestry, and no DOM wrapper is
+added. The API works the same way when `ViewModel` uses an external template:
+
+```tsx
+class FormModel extends ViewModel {}
+
+class FieldModel extends ViewModel {
+  form = this.findParent(FormModel)
+}
+
+const Field = createComponent(FieldModel, (field) => <input />)
+const Form = createComponent(FormModel, (form) => <Field />)
+```
+
+Ancestry is available in field initializers and `onCreate()`. It is runtime-only,
+non-observable, and not serialized. A model constructed manually with `new`
+outside `createComponent()` has no automatic parent.
 
 ### `Behavior`
 
@@ -709,8 +1433,11 @@ Base class for behaviors. Extend it and wrap with `createBehavior()`.
 | `onCreate(...args)` | Called during construction with constructor args |
 | `onLayoutMount()` | Called before paint, return cleanup (optional) |
 | `onMount()` | Called after paint, return cleanup (optional) |
-| `onUnmount()` | Called when parent View unmounts |
-| `watch(expr, callback, options?)` | Watch reactive expression, auto-disposed on unmount |
+| `onUnmount()` | Called when parent Component unmounts |
+| `addCleanup(fn)` | Register cleanup to run automatically on unmount |
+| `watch(source, callback, options?)` | Watch a reactive expression (or a `MaybeGetter` argument directly), auto-disposed on unmount, re-created on remount |
+| `effect(fn, options?)` | Run auto-tracked side effect, auto-disposed on unmount, re-created on remount |
+| `sync(arg)` | Normalize a `MaybeGetter` argument into an ordinary field that stays current (one-way, see [Reactive Arguments](#reactive-arguments)) |
 
 ### `createBehavior(Class)`
 
@@ -726,25 +1453,41 @@ export const withMyBehavior = createBehavior(MyBehavior);
 // Usage: withMyBehavior('hello')
 ```
 
-### `createView(ViewClass, templateOrOptions?)`
+### `createComponent(ComponentClass, templateOrOptions?)`
 
-Function that creates a React component from a View class.
+Function that creates a React component from a Component class.
 
 ```tsx
 // Basic (auto-observable)
-createView(MyView)
+createComponent(MyComponent)
 
 // With template
-createView(MyView, (vm) => <div>{vm.value}</div>)
+createComponent(MyComponent, (vm) => <div>{vm.value}</div>)
 
 // With options
-createView(MyView, { autoObservable: false })
+createComponent(MyComponent, { autoObservable: false })
 ```
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `autoObservable` | `true` | Make all fields observable. Set to `false` when using decorators. |
 
+### `useBehavior(factory)`
+
+Host a behavior in a plain React function component (see [Behaviors in Plain Function Components](#behaviors-in-plain-function-components)). The factory runs once per mount lifetime; the returned instance is observable — pair with `observer()`.
+
+```tsx
+const size = useBehavior(() => withWindowSize());
+```
+
+### `observer(fc)`
+
+Minimal observer wrapper for function components — re-renders when any observable read during render changes. Ships with Mantle (no `mobx-react-lite` needed); intended for components using `useBehavior()` or reading MobX stores directly.
+
+### `toValue(value)` / `MaybeGetter<T>`
+
+The value-or-getter convention for reactive behavior arguments (see [Reactive Arguments](#reactive-arguments)). `toValue(v)` returns `v()` if `v` is a function, otherwise `v`. Behavior authors normalizing an argument into a self-updating field use `this.sync()` instead (documented in the same section).
+
 ## Who This Is For
 
 - Teams using MobX for state management