@mhmo91/schmancy 0.9.27 → 0.10.1

package/src/rxjs-utils/waitForElements.ts

@@ -8,7 +8,7 @@ import observeOnMutation from './mutation-observer'
  * @example waitForElements(['button', 'input']).subscribe(([button, input]) => button.click())
  * @returns
  */
-export default function waitForElements<T extends Array<T>>(
+export default function waitForElements(
   /**
    * @param selectors The selectors to use to find the elements
    * @type { string[] }

package/src/rxjs-utils/waitForElementsAll.ts

@@ -8,7 +8,7 @@ import observeOnMutation from './mutation-observer'
  * @example waitForElements(['button', 'input']).subscribe(([button, input]) => button.click())
  * @returns
  */
-export default function waitForElementsAll<T extends Array<T>>(
+export default function waitForElementsAll(
   /**
    * @param selectors The selectors to use to find the elements
    * @type { string[] }

package/src/select/select.ts

@@ -1,5 +1,5 @@
 import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom'
-import { $LitElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { color } from '@schmancy/directives'
 import SchmancyInput from '@schmancy/input/input'
 import SchmancyOption from '@schmancy/option/option'
@@ -7,6 +7,7 @@ import { SchmancyTheme } from '@schmancy/theme/theme.interface'
 import { css, html, PropertyValues, TemplateResult } from 'lit'
 import { customElement, property, query, queryAssignedElements, state } from 'lit/decorators.js'
 import { classMap } from 'lit/directives/class-map.js'
+import { ifDefined } from 'lit/directives/if-defined.js'
 import { BehaviorSubject, combineLatest, fromEvent, Subject, takeUntil } from 'rxjs'
 import { tap, withLatestFrom } from 'rxjs/operators'
 
@@ -15,18 +16,7 @@ export type SchmancySelectChangeEvent = CustomEvent<{
 }>
 
 /**
- * Dropdown selector — single or multi-select from a list of `<schmancy-option>` children. Form-associated.
- *
- * @element schmancy-select
- * @summary Material Design dropdown with type-to-filter, keyboard nav, single or multi-select. Options are declared as `<schmancy-option>` children; value / values props sync with selection.
- * @example
- * <schmancy-select name="priority" label="Priority" value="medium">
- *   <schmancy-option value="low">Low</schmancy-option>
- *   <schmancy-option value="medium">Medium</schmancy-option>
- *   <schmancy-option value="high">High</schmancy-option>
- * </schmancy-select>
- * @platform select change - Floating-UI-positioned listbox. Degrades to native `<select>` styled via Tailwind if the tag never registers, though multi-select UX is lost.
- * @fires change - `SchmancySelectChangeEvent` with `{ value }` (single) or `{ value: string[] }` (multi).
+ * Select dropdown component with single and multi-select support.
  *
  * @prop {string} name - Name attribute for form submission
  * @prop {string} label - Label text displayed above the select
@@ -37,7 +27,8 @@ export type SchmancySelectChangeEvent = CustomEvent<{
  * @prop {string[]} values - Selected values (multi-select mode)
  */
 @customElement('schmancy-select')
-export class SchmancySelect extends $LitElement(css`
+export class SchmancySelect extends SchmancyElement {
+	static styles = [css`
 	:host {
 		display: block;
 		position: relative;
@@ -47,7 +38,8 @@ export class SchmancySelect extends $LitElement(css`
 		overflow-y: auto;
 		outline: none;
 	}
-`) {
+`]
+
 	// Form association setup
 	static formAssociated = true
 	private internals?: ElementInternals
@@ -692,7 +684,7 @@ export class SchmancySelect extends $LitElement(css`
 		return html`
 			<div class="relative ${this.disabled ? 'opacity-60 cursor-not-allowed' : ''}">
 				<sch-input
-					.name=${this.name}
+					.name=${this.name ?? ''}
 					tabIndex=${this.disabled ? '-1' : '0'}
 					class="trigger"
 					role="combobox"
@@ -701,7 +693,7 @@ export class SchmancySelect extends $LitElement(css`
 					aria-controls="options"
 					aria-autocomplete="none"
 					aria-required=${this.required}
-					aria-activedescendant=${this._focusedOptionId || undefined}
+					aria-activedescendant=${ifDefined(this._focusedOptionId || undefined)}
 					aria-disabled=${this.disabled}
 					.label=${this.label}
 					.placeholder=${this.placeholder}
@@ -712,7 +704,7 @@ export class SchmancySelect extends $LitElement(css`
 					.error=${showErrors}
 					.validateOn=${this.validateOn}
 					.size=${this.size}
-					readonly
+					.readonly=${true}
 					clickable
 					@click=${(e: MouseEvent) => {
 						// Don't process clicks if disabled

package/src/sheet/hook.ts

@@ -31,7 +31,7 @@ export function on(propName: string, options?: WatchOptions) {
 
 				if (oldValue !== newValue) {
 					if (!options?.waitUntilFirstUpdate || this.hasUpdated) {
-						this[name].call(this, oldValue, newValue)
+						this[name](oldValue, newValue)
 					}
 				}
 			}

package/src/sheet/sheet.ts

@@ -1,4 +1,4 @@
-import { $LitElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { area } from '../area'
 import { html, css } from 'lit'
 import { customElement, property, query } from 'lit/decorators.js'
@@ -7,25 +7,9 @@ import { on } from './hook'
 import { SchmancySheetPosition, sheet } from './sheet.service'
 import { BLACKBIRD_EASING, DURATION_ENTER, DURATION_EXIT, DURATION_BACKDROP, EASE_OUT, EASE_IN } from '../utils/animation'
 
-/**
- * Side-docked or bottom-docked panel — a dialog variant that slides in from an edge. Driven imperatively by the `sheet` service; rarely instantiated directly.
- *
- * @element schmancy-sheet
- * @summary Prefer `sheet.open({ component, position })` over placing this element declaratively — the service handles stacking, focus, close on outside-click, ESC, and router integration.
- * @example
- * import { sheet, SchmancySheetPosition } from '@mhmo91/schmancy'
- * sheet.open({
- *   component: new MyEditorElement(),
- *   position: SchmancySheetPosition.Side,
- *   title: 'Edit item',
- * })
- * @platform dialog close - Positioned-fixed panel with backdrop. Degrades to a `<dialog>` if the tag never registers — loses slide animation, keeps focus trap + dismiss.
- * @attr position - `'side' | 'bottom'`. Which edge the sheet docks to.
- * @attr open - Boolean; sheet is visible when true.
- * @fires close - When the sheet is dismissed (backdrop click, close button, ESC).
- */
 @customElement('schmancy-sheet')
-export default class SchmancySheet extends $LitElement(css`
+export default class SchmancySheet extends SchmancyElement {
+	static styles = [css`
 	:host {
 		position: fixed;
 		inset: 0;
@@ -48,7 +32,8 @@ export default class SchmancySheet extends $LitElement(css`
 	@media (prefers-reduced-motion: reduce) {
 		.content { box-shadow: var(--schmancy-sys-elevation-3); }
 	}
-`) {
+`]
+
 	// uid is inherited from $LitElement mixin - auto-generated or set via attribute
 	@property({ type: Boolean, reflect: true }) open = false
 	@property({ type: String, reflect: true }) position: SchmancySheetPosition = SchmancySheetPosition.Side

package/src/skeleton/skeleton.ts

@@ -1,4 +1,4 @@
-import { TailwindElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { css, html } from 'lit'
 import { customElement, property } from 'lit/decorators.js'
 
@@ -14,7 +14,8 @@ import { customElement, property } from 'lit/decorators.js'
  * @csspart surface - The shimmering surface element.
  */
 @customElement('schmancy-skeleton')
-export class SchmancySkeleton extends TailwindElement(css`
+export class SchmancySkeleton extends SchmancyElement {
+	static styles = [css`
 	:host {
 		display: block;
 		width: var(--_sw, 100%);
@@ -46,7 +47,7 @@ export class SchmancySkeleton extends TailwindElement(css`
 			background: var(--schmancy-sys-color-surface-containerHighest, #e6e6e6);
 		}
 	}
-`) {
+`];
 	@property({ type: String, reflect: true }) shape: 'rect' | 'circle' | 'text' = 'rect'
 	@property({ type: String }) width = ''
 	@property({ type: String }) height = ''

package/src/slider/slide.ts

@@ -1,4 +1,4 @@
-import { $LitElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { css, html } from 'lit'
 import { customElement, property } from 'lit/decorators.js'
 import { cache } from 'lit/directives/cache.js'
@@ -18,7 +18,8 @@ type SlideType = 'image' | 'video' | 'content'
 type ObjectFit = 'cover' | 'contain' | 'fill' | 'scale-down' | 'none'
 
 @customElement('schmancy-slide')
-export class SchmancySlide extends $LitElement(css`
+export class SchmancySlide extends SchmancyElement {
+	static styles = [css`
 	:host {
 		display: block;
 		scroll-snap-align: center; /* If your slider uses scroll-snap */
@@ -30,7 +31,8 @@ export class SchmancySlide extends $LitElement(css`
 		height: auto;
 		object-fit: var(--object-fit, cover);
 	}
-`) {
+`]
+
 	/**
 	 * Determines how this slide should be rendered.
 	 * Defaults to 'content' if not provided.

package/src/slider/slider.ts

@@ -1,11 +1,12 @@
-import { $LitElement } from '@mixins/index'
+import { SchmancyElement } from '@mixins/index'
 import { css, html } from 'lit'
 import { customElement, property, query, state } from 'lit/decorators.js'
 import { fromEvent } from 'rxjs'
 import { throttleTime } from 'rxjs/operators'
 
 @customElement('schmancy-slider')
-export class SchmancySlider extends $LitElement(css`
+export class SchmancySlider extends SchmancyElement {
+	static styles = [css`
 	.slider {
 		/* Lay out slides horizontally, one after another */
 		display: flex;
@@ -30,7 +31,8 @@ export class SchmancySlider extends $LitElement(css`
 		flex: 0 0 100%;
 		box-sizing: border-box;
 	}
-`) {
+`]
+
 	/**
 	 * Currently centered slide index
 	 */

package/src/splash-screen/splash-screen.ts

@@ -1,4 +1,4 @@
-import { $LitElement } from '@mixins/litElement.mixin'
+import { SchmancyElement } from '@mixins/index'
 import { css, html } from 'lit'
 import { customElement, property, state } from 'lit/decorators.js'
 import { styleMap } from 'lit/directives/style-map.js'
@@ -30,7 +30,8 @@ export type SchmancySplashScreenDoneEvent = CustomEvent<void>
  * ```
  */
 @customElement('schmancy-splash-screen')
-export default class SchmancySplashScreen extends $LitElement(css`
+export default class SchmancySplashScreen extends SchmancyElement {
+	static styles = [css`
 	:host {
 		display: block;
 		position: relative;
@@ -56,7 +57,8 @@ export default class SchmancySplashScreen extends $LitElement(css`
 		width: 100%;
 		transition: opacity var(--schmancy-splash-transition, 500ms) ease-in-out;
 	}
-`) {
+`]
+
 	/**
 	 * Minimum duration (ms) the splash layer stays visible. Prevents a flash
 	 * when the app loads faster than expected.

package/src/state/CLAUDE.md

@@ -0,0 +1,161 @@
+# Agent brief — `@mhmo91/schmancy/state`
+
+When you're touching anything in this directory or anything that imports
+from `@mhmo91/schmancy/state`, read this first.
+
+## What this module is
+
+A reactive state primitive for the schmancy library:
+
+- `state(namespace).memory(initial)` / `.local()` / `.session()` / `.idb()`
+  → returns a module-scoped singleton with a TC39 signal, an RxJS
+  Observable, sync getter, microtask-debounced persistence, and a
+  Disposable + (for `idb`) AsyncDisposable lifecycle.
+- `computed(fn)` — re-export of `@lit-labs/signals/computed`.
+- `effect(fn)` — runs `fn` whenever any signal it reads changes;
+  returns a `Disposable` for cleanup.
+- `observe(source)` — legacy property decorator. One-way binds a class
+  field to a state for the host's lifetime. Use only when the value is
+  needed AS a class field (event handlers, derived methods, DevTools).
+- `bindState(host, source)` — `ReactiveController` helper. Same
+  guarantees as `@observe`, no decorator. Use when the host isn't a
+  `$LitElement` subclass.
+- `stateFromObservable(observable, namespace, initial)` — bridges an
+  RxJS source into a `state()`.
+
+The module ships `Signal` (TC39 polyfill) and `StorageBackend` as named
+type exports.
+
+## Default subscription pattern
+
+`$LitElement()` already composes `SignalWatcher` over its mixin chain.
+Every signal read inside `render()` auto-tracks. **The default consumer
+needs zero binding code:**
+
+```ts
+@customElement('cart-view')
+class CartView extends $LitElement() {
+  render() { return html`Items: ${cart.value.items.length}` }
+}
+```
+
+The imported `cart` singleton IS the binding. Only reach for `@observe`
+or `bindState` when you need the value as a class field.
+
+## Scoping (`<schmancy-context provides>`)
+
+The default state is a module-scoped singleton. `<schmancy-context>` is
+the **only** way to scope a state per subtree. Reads and writes inside
+the element auto-resolve to a per-element isolated copy via the
+`@lit/context` request protocol; outside, they read the global.
+
+```ts
+<schmancy-context .provides=${[cart]}>
+  <cart-view></cart-view>   <!-- isolated -->
+</schmancy-context>
+<cart-summary></cart-summary>   <!-- module-scoped global -->
+```
+
+Two infrastructure files own the mechanics:
+
+- `state/active-host.ts` — `_activeHost` Variable + `Promise.then`
+  patch + `resolveActiveHost()` 4-tier fallback (stack →
+  `window.event` → `document.activeElement` → undefined). Hand-rolled
+  TC39 AsyncContext.Variable polyfill (~30 lines). The patch is
+  idempotent and uses `_origThen.call(this, …)` so Promise subclassing
+  / `Symbol.species` are untouched. Decommissions the day a real
+  polyfill or native AsyncContext lands — drop the file, swap the
+  `_activeHost` export.
+- `state/schmancy-context.ts` — the `<schmancy-context>` element. One
+  `ContextProvider` per state in `provides`; all destroyed on
+  disconnect.
+
+`mixins/SchmancyElement.ts` carries the integration points: prototype-
+chain wrap of every concrete subclass at first construction (caches in
+a `WeakSet`), and `addEventListener` / `removeEventListener` overrides
+that wrap host listeners.
+
+Inline arrow handlers in templates (`@click=${() => …}`) are not
+wrapped — they attach to child elements, not the host. They resolve
+via the `window.event.composedPath()` fallback.
+
+## Rules for code in this directory
+
+- **One file by default.** `state/index.ts` holds the factory, types,
+  variant write APIs, persistence-debouncing wrapper, RxJS interop,
+  decorator, and helpers. `persist.ts`, `active-host.ts`, and
+  `schmancy-context.ts` are the only siblings — they own storage
+  adapters / the JSON tunnel, the host tracker / `Promise.then` patch,
+  and the scoping element respectively. Do not split further until a
+  second consumer of an internal helper emerges.
+- **Every read and write on a global instance routes through
+  `resolveContextual`.** Don't add a fast path that bypasses it — the
+  whole point of the scoping primitive is that consumer code is
+  unchanged whether or not a `<schmancy-context>` ancestor exists.
+- **Isolated copies are direct-access.** They serve as resolution
+  targets and must not themselves call `resolveContextual` (would
+  recurse). The `{ isolated: true }` branch in `createInstance`
+  preserves this invariant.
+- **Don't extend the `Promise.prototype.then` patch.** It is the
+  minimum surface needed for await propagation. New schedulers
+  (custom queueMicrotask wrappers, etc.) should be solved by routing
+  through Promise, not by adding more patches.
+- **No tsconfig flip.** Schmancy stays on `experimentalDecorators: true`.
+  Any new decorator in this module is a legacy property/method
+  decorator, same shape as `@property`/`@state`/`@query`.
+- **No `accessor` keyword.** Implied by the line above — but call it
+  out so a reviewer doesn't miss it. The schmancy codebase doesn't use
+  `accessor`; this module follows the same convention.
+- **Brand symbols are plain `Symbol(...)` constants** (`stateBrand`,
+  `namespaceBrand`). They are private to the module and not exported.
+  Do not export them; consumers use the `State<>` type for nominal
+  identity.
+- **Microtask-coalesced writes.** Every persistent backend wraps writes
+  in a per-instance microtask debouncer. Multiple `set`/`update`/
+  `replace` calls in the same task collapse to one `save()`. Do not
+  bypass — write through the variant API.
+- **`signal-polyfill` is the runtime contract.** `@lit-labs/signals` is
+  the canonical import; it re-exports the polyfill plus
+  `SignalWatcher`. Do not import `signal-polyfill` directly.
+
+## Rules for tests
+
+- **Vitest browser mode (Chromium via Playwright).** Real DOM, real
+  IndexedDB, real localStorage. Imported via the schmancy
+  `vitest.config.ts`.
+- **Static namespaces in tests.** The factory's `${string}/${string}`
+  template literal rejects dynamic strings. Use literal namespaces like
+  `'test/foo'` so type inference works without casts.
+- **`using` for test-scoped state.** `using cart = state(...).memory(...)`
+  disposes on scope exit, including failure cases. Use plain `const`
+  for module-scope state in production.
+- **Microtask draining.** Signal-to-Observable emission and write
+  coalescing both use `queueMicrotask`. After `state.set(...)`, call
+  `await settle()` (two microtask drains) before asserting derived
+  state, then `await el.updateComplete` for any host re-render.
+
+## Rules for behaviour changes
+
+- **Public surface is committed.** `value`, `signal`, `$`, `ready`,
+  `loaded`, `defaultValue`, `namespace`, `storage`, `destroy`,
+  `[Symbol.dispose]`, `[Symbol.asyncDispose]` (idb only), variant
+  write methods. Don't rename, don't shape-shift. Add new things;
+  don't change existing ones.
+- **Variant API dispatch is `Kind<T>`-driven.** Don't add separate
+  `mapState()` / `setState()` factories. If a new shape comes up,
+  extend the `Kind<T>` classifier and add a matching variant API
+  interface.
+- **Storage keys are namespace strings.** `state('hannah/cart').local(...)`
+  uses `'hannah/cart'` as the storage key. Don't expose a separate
+  key parameter; the namespace IS the key.
+
+## Pointers
+
+- **State plan and Phase 0 findings:** the original implementation plan
+  lives in `~/.claude/plans/indexed-twirling-stroustrup.md`; spike
+  artifacts and findings are at
+  `packages/schmancy/_scratch/spikes/findings.md` (gitignored).
+- **Skill doc for downstream consumers:**
+  `packages/schmancy/skills/schmancy/state.md`.
+- **Migration cheatsheet** for moving off the v1 `createContext`:
+  `packages/schmancy/src/state/MIGRATION.md`.

package/src/state/MIGRATION.md

@@ -0,0 +1,258 @@
+# Migrating from `createContext` to `state()`
+
+Cheatsheet for moving call sites off the v1 `createContext` /
+`@select` / `createCompoundSelector` / `selectItem` family to
+`@mhmo91/schmancy/state`.
+
+The v1 surface has been deleted from `@mhmo91/schmancy`. There is no
+parallel API; every consumer needs to switch.
+
+## Imports
+
+```ts
+// Before
+import { createContext, select, selectItem, createCompoundSelector } from '@mhmo91/schmancy'
+
+// After
+import { state, computed, observe, bindState, stateFromObservable } from '@mhmo91/schmancy/state'
+```
+
+## Defining a state
+
+| v1 | v2 |
+|---|---|
+| `createContext<T>(initial, 'memory', 'foo')` | `state<T>('feature/foo').memory(initial)` |
+| `createContext<T>(initial, 'session', 'foo')` | `state<T>('feature/foo').session(initial)` |
+| `createContext<T>(initial, 'local', 'foo')` | `state<T>('feature/foo').local(initial)` |
+| `createContext<T>(initial, 'indexeddb', 'foo')` | `state<T>('feature/foo').idb(initial)` |
+
+The string namespace replaces the v1 third-argument storage key. It
+must contain a `/` (compile-time enforced via the
+`${string}/${string}` template literal). Storage is keyed off the
+namespace string.
+
+If your file already declares the initial value in a typed const, drop
+the type arg:
+
+```ts
+const initial: CartState = { items: [], total: 0 }
+const cart = state('hannah/cart').session(initial)   // T inferred from `initial`
+```
+
+## Reading
+
+| v1 | v2 |
+|---|---|
+| `cart.value` | `cart.value` (unchanged) |
+| `cart.$.subscribe(...)` | `cart.$.subscribe(...)` (unchanged) |
+| `cart.ready` (boolean) | `cart.loaded` (boolean) + `await cart.ready` (Promise<void>) |
+
+`cart.ready` is now a Promise that resolves when initial load completes
+(success or fallback). `cart.loaded` is the boolean runtime flag. Use
+whichever fits the call site.
+
+## Writing
+
+| v1 | v2 |
+|---|---|
+| `cart.set({ total: 12 })` | `cart.set({ total: 12 })` (unchanged) |
+| `cart.set({ items: [] }, false)` | `cart.set({ items: [] }, false)` (unchanged) |
+| `cart.replace(next)` | `cart.replace(next)` (unchanged) |
+| `cart.delete('total')` | `cart.delete('total')` (unchanged) |
+| Manual `replace({ ...current, ...patch })` cascade | `cart.update(d => { … })` — immer recipe, single notification |
+
+For `Map<K, V>` shapes:
+
+| v1 | v2 |
+|---|---|
+| `docs.set('id', doc)` | `docs.set('id', doc)` (unchanged — MapAPI dispatch) |
+
+For `Set<U>`:
+
+| v1 | v2 |
+|---|---|
+| Manual `replace(new Set([...current, item]))` | `sel.add('item')` |
+| Manual replace-without-item | `sel.delete('item')` (returns boolean) |
+|  | `sel.toggle('item')` (new) |
+
+For arrays:
+
+| v1 | v2 |
+|---|---|
+| `array.push(...items)` | `array.push(...items)` (unchanged) |
+| Manual `replace(current.filter(...))` | `array.update(d => d.splice(...))` (immer) |
+
+For nullable references and primitives:
+
+| v1 | v2 |
+|---|---|
+| `editing.set({ id: 'x' })` then `editing.set(null)` | Same (ScalarAPI accepts the union directly) |
+
+## Subscribing in a component
+
+The v1 `@select` decorator is gone. Three options in v2, in order of
+preference:
+
+### (1) Default — direct read in render (zero ceremony)
+
+`$LitElement()` composes `SignalWatcher`, so signal reads in `render()`
+auto-track. Just import the state and use it inline:
+
+```ts
+@customElement('cart-view')
+class CartView extends $LitElement() {
+  render() { return html`Items: ${cart.value.items.length}` }
+}
+```
+
+No decorator, no field, no binding code. The imported `cart` singleton
+IS the binding.
+
+### (2) `@observe(source)` — when you need a class field
+
+```ts
+class CartView extends $LitElement() {
+  @observe(cart) cart!: CartState
+
+  onClick() {
+    console.log(this.cart)   // event handler needs `this.cart`
+  }
+
+  render() {
+    return html`Items: ${this.cart.items.length}`
+  }
+}
+```
+
+Reads return the latest value. Caller writes are dropped with a dev
+warning. Same decorator shape as `@property` — works under the existing
+tsconfig.
+
+### (3) `bindState(host, source)` — for hosts that aren't `$LitElement`
+
+```ts
+class CustomHost extends LitElement {
+  cart = bindState(this, cart)
+  render() { return html`Items: ${this.cart.value.items.length}` }
+}
+```
+
+## Compound selectors → `computed`
+
+```ts
+// Before
+const cartItemCount = createCompoundSelector(
+  [cartContext],
+  [cart => cart.items.length],
+  count => count,
+)
+
+// After
+import { computed } from '@mhmo91/schmancy/state'
+const cartItemCount = computed(() => cart.value.items.length)
+```
+
+Cross-state composition just works:
+
+```ts
+const orderTotal = computed(() => cart.value.subtotal + tip.value.amount)
+```
+
+Reading any `state.value` inside `computed(fn)` auto-tracks. No
+explicit dependency array.
+
+## Side effects → `effect`
+
+```ts
+import { effect } from '@mhmo91/schmancy/state'
+
+const stop = effect(() => {
+  document.title = `${cart.value.items.length} items`
+})
+
+// later, when no longer needed:
+stop[Symbol.dispose]()
+```
+
+Eager run + microtask-coalesced re-runs. Returns a `Disposable`.
+
+## Observable bridges
+
+```ts
+// Before
+const userPresence$ = new BehaviorSubject({ online: false, since: 0 })
+// (read with .value, subscribe with .$, no persistence story)
+
+// After
+import { stateFromObservable } from '@mhmo91/schmancy/state'
+
+const userPresence = stateFromObservable(
+  presence$,                    // Observable<PresenceState>
+  'app/presence',
+  { online: false, since: 0 },
+)
+// userPresence has .value, .$, all variant API methods, lifecycle.
+```
+
+## Lifecycle / disposal
+
+```ts
+// Module scope — same as v1
+export const cart = state('hannah/cart').session(initial)
+
+// Test scope — using
+it('cart updates total on add', () => {
+  using cart = state('test/cart').memory(initial)
+  cart.update(d => { d.items.push(item) })
+  expect(cart.value.total).toBe(item.price)
+})  // [Symbol.dispose] runs here, even on assertion failure
+
+// IDB-backed in tests — await using flushes pending writes
+it('persists across reloads', async () => {
+  await using cart = state('test/cart').idb(initial)
+  // ...
+})
+
+// Imperative cleanup (samwa back-compat alias)
+cart.destroy()
+```
+
+## Things that went away
+
+- **`createCompoundSelector`** — use `computed()`.
+- **`@select` and `@selectItem` decorators** — use direct render reads
+  via `$LitElement` (default), `@observe` (field-level), or `bindState`
+  (non-Lit hosts).
+- **`IStore` / `ICollectionStore` / `IArrayStore` interfaces** — no
+  longer needed. The variant write API dispatch is type-level.
+- **`error$` per-store Subject** — errors flow through console + the
+  `StateStorageError` thrown from `save()` for IDB write failures.
+- **Tree-scoped `<state-provider>`** — replaced by
+  `<schmancy-context provides={[…]}>`. Same intent (per-subtree
+  isolation of a state), different API: in v1 the provider was a
+  primitive; in v2 the state surface stays unchanged and the
+  `<schmancy-context>` element is what scopes a subtree. Consumer
+  code (`cart.value`, `cart.set(...)`) is identical inside and
+  outside the element. See `SCOPING.md` for the details.
+
+## Footguns
+
+- **Don't use `using` at module scope.** It disposes on module GC,
+  which is roughly never until the tab closes. Plain `const` for
+  module singletons, `using` for test/function scope only.
+- **Namespaces always contain `/`.** `state('cart')` is a TypeError;
+  use `state('feature/cart')`.
+- **Don't `state.signal.set(...)` directly.** Go through the variant
+  API so write-coalescing and persistence stay coherent.
+- **Inline literals without a typed const narrow T.**
+  `state('app/x').memory({ items: [], total: 0 })` infers
+  `{ items: never[]; total: number }`. Either use a typed const first
+  or pass the type arg: `state<CartState>('app/x').memory({...})`.
+
+## Pointers
+
+- Skill / API reference: `packages/schmancy/skills/schmancy/state.md`
+- Agent brief: `packages/schmancy/src/state/CLAUDE.md`
+- Tree-scoping reference: `packages/schmancy/src/state/SCOPING.md`
+- Original plan: `~/.claude/plans/indexed-twirling-stroustrup.md`
+- Scoping plan: `~/.claude/plans/federated-petting-penguin.md`