@zeix/le-truc 0.15.0 → 0.16.0

package/.ai-context.md

@@ -36,12 +36,12 @@ The selector function provides type-safe DOM queries:
 ({ first, all }) => ({
   button?: first('button'),          // HTMLButtonElement | undefined
   input: first('input', 'required'), // HTMLInputElement (throws if missing)
-  items: all('.item'),               // Collection<HTMLElement>
+  items: all('.item'),               // Memo<HTMLElement[]>
   custom?: first<MyElement>('my-el') // Custom typing
 })
 ```
 
-Collections are reactive arrays that emit `add`/`remove` events and track DOM mutations automatically.
+`all()` returns `Memo<E[]>` backed by a lazy `MutationObserver` that tracks DOM mutations automatically.
 
 ### Effect System
 Effects run reactively when dependencies change:
@@ -77,9 +77,10 @@ Effects run reactively when dependencies change:
 - `setStyle(property, reactive)`     - Update inline styles
 
 ### Advanced
-- `pass(props)`                               - Pass properties to child components
-- `dangerouslySetInnerHTML(reactive)`         - Set innerHTML (use carefully)
-- `insertOrRemoveElement(reactive, inserter)` - Dynamic element creation/removal
+- `pass(props)`                               - Pass reactive values to child Le Truc components via Slot signal replacement
+- `dangerouslySetInnerHTML(reactive, opts?)`  - Set innerHTML (use only for trusted sources)
+- `callMethod(name, reactive, args?)`         - Call a method when reactive is truthy
+- `focus(reactive)`                           - Focus element when truthy
 
 ## Parsers
 
@@ -114,23 +115,23 @@ const countSignal = createState(0)
 setText(() => countSignal.get())
 ```
 
-## Collections
+## Element Memos
 
-Read-only reactive element arrays with array-like interface:
+`all()` returns `Memo<E[]>` — a lazily observed collection of elements:
 
 ```typescript
 // Creation
-({ all }) => ({ items: all('.item') })          // In UI query, will be ui.items
-const items = createCollection(parent, '.item') // Elsewhere with arbitrary parent
+({ all }) => ({ items: all('.item') })              // In UI query, will be ui.items
+const items = createElementsMemo(parent, '.item')   // Elsewhere with arbitrary parent
 
 // Access
-items.get()            // Get current elements
-items.length           // Reactive length
-items[0]               // Index access
-items.on('add', fn)    // Listen for additions
-items.on('remove', fn) // Listen for removals
+items.get()            // Get current elements array
+items.get().length     // Current count
+items.get()[0]         // Index access
 ```
 
+The `MutationObserver` backing the memo activates lazily — only when the memo is read from within a reactive effect. This avoids unnecessary observation overhead for memos that aren't actively consumed.
+
 ## Common Patterns
 
 ### Form Components
@@ -222,7 +223,7 @@ export default defineComponent<MyComponentProps, MyComponentUI>(...)
 
 ### Performance
 - Effects automatically optimize re-runs when dependencies don't change
-- Collections efficiently track only actual DOM changes
+- Element memos efficiently track only actual DOM changes via lazy MutationObserver
 - Use `schedule()` for non-critical updates in passive event handlers
 - Proper cleanup prevents memory leaks
 

package/.github/copilot-instructions.md

@@ -32,7 +32,8 @@ Files to consult for examples and authoritative patterns
 - Selector helpers & mutation-observer logic: `src/ui.ts`
 - Parser implementations: `src/parsers/*.ts` (e.g. `json.ts`, `number.ts`, `string.ts`)
 - Effect implementations: `src/effects/*.ts` (exported from root `index.ts`)
-- Signal helpers: `src/signals/*.ts` (collection, sensor)
+- Event-driven sensors: `src/events.ts` (createEventsSensor)
+- Element memos: `createElementsMemo` in `src/ui.ts`
 - Examples demonstrating usage: `examples/*` (start from `basic-hello` and `basic-counter`)
 
 Developer workflows (essential commands)
@@ -45,7 +46,7 @@ Developer workflows (essential commands)
 What to change (and what to avoid)
 - Change: small refactors that preserve exported API in `index.ts` and `.d.ts` files.
 - Change: add or update examples in `examples/` to demonstrate new or changed behavior.
-- Avoid: breaking changes to public exports without updating `index.ts` / `index.dev.ts` and re-building (`bun run build:dev`).
+- Avoid: breaking changes to public exports without updating `index.ts` and re-building (`bun run build`).
 - Avoid: changing the custom element registration pattern (i.e., calling `customElements.define`) in a way that prevents `getHelpers` dependency detection.
 
 PR guidance / descriptions

package/.github/workflows/ci-cd.yml

@@ -0,0 +1,101 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [main, develop]
+    tags: ['v*']
+  pull_request:
+    branches: [main, develop]
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Build
+        run: bun run build
+
+      - name: Install Playwright browsers
+        run: bunx playwright install --with-deps
+
+      - name: Run tests
+        run: bun run test
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' && github.event.action == 'published'
+    permissions:
+      contents: read
+      id-token: write # Required for npm provenance
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build package
+        run: bun run build
+
+      - name: Setup Node.js for npm
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Verify package version matches tag
+        run: |
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          TAG_VERSION=${GITHUB_REF#refs/tags/v}
+          if [ "$PACKAGE_VERSION" != "$TAG_VERSION" ]; then
+            echo "Package version ($PACKAGE_VERSION) doesn't match tag version ($TAG_VERSION)"
+            exit 1
+          fi
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create deployment status
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.repos.createDeploymentStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              deployment_id: context.payload.deployment?.id || 0,
+              state: 'success',
+              environment: 'npm',
+              target_url: 'https://www.npmjs.com/package/@zeix/le-truc'
+            });

package/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (leave empty to use package.json version)'
+        required: false
+        type: string
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # Required for npm provenance
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build package
+        run: bun run build
+
+      - name: Setup Node.js for npm
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Update version (if specified)
+        if: github.event.inputs.version != ''
+        run: npm version ${{ github.event.inputs.version }} --no-git-tag-version
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub release (if manual dispatch)
+        if: github.event_name == 'workflow_dispatch'
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: v${{ steps.version.outputs.version || fromJson(steps.package.outputs.json).version }}
+          release_name: Release v${{ steps.version.outputs.version || fromJson(steps.package.outputs.json).version }}
+          draft: false
+          prerelease: false

package/.github/workflows/release.yml

@@ -0,0 +1,98 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_type:
+        description: 'Version bump type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+        default: 'patch'
+      prerelease:
+        description: 'Create prerelease'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run tests and build
+        run: bun run build
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        id: version
+        run: |
+          if [ "${{ github.event.inputs.prerelease }}" = "true" ]; then
+            NEW_VERSION=$(npm version pre${{ github.event.inputs.version_type }} --preid=beta --no-git-tag-version)
+          else
+            NEW_VERSION=$(npm version ${{ github.event.inputs.version_type }} --no-git-tag-version)
+          fi
+          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          echo "version_number=${NEW_VERSION#v}" >> $GITHUB_OUTPUT
+
+      - name: Update changelog
+        run: |
+          echo "## ${{ steps.version.outputs.new_version }} - $(date +%Y-%m-%d)" >> CHANGELOG_NEW.md
+          echo "" >> CHANGELOG_NEW.md
+          echo "- Version bump: ${{ github.event.inputs.version_type }}" >> CHANGELOG_NEW.md
+          echo "" >> CHANGELOG_NEW.md
+          if [ -f CHANGELOG.md ]; then
+            cat CHANGELOG.md >> CHANGELOG_NEW.md
+          fi
+          mv CHANGELOG_NEW.md CHANGELOG.md
+
+      - name: Commit changes
+        run: |
+          git add package.json CHANGELOG.md
+          git commit -m "chore: bump version to ${{ steps.version.outputs.new_version }}"
+          git tag ${{ steps.version.outputs.new_version }}
+          git push origin main
+          git push origin ${{ steps.version.outputs.new_version }}
+
+      - name: Create GitHub Release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ steps.version.outputs.new_version }}
+          release_name: Release ${{ steps.version.outputs.new_version }}
+          draft: false
+          prerelease: ${{ github.event.inputs.prerelease }}
+          body: |
+            ## Changes in ${{ steps.version.outputs.new_version }}
+
+            This release was created automatically via GitHub Actions.
+
+            **Version bump:** ${{ github.event.inputs.version_type }}
+            **Prerelease:** ${{ github.event.inputs.prerelease }}
+
+            View the full changelog at [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md)

package/.zed/settings.json

@@ -0,0 +1,3 @@
+{
+	"project_name": "Le Truc",
+}

package/ARCHITECTURE.md

@@ -0,0 +1,272 @@
+# Architecture
+
+Le Truc is a reactive custom elements library. This document describes how the pieces in `src/` fit together.
+
+## File Map
+
+```
+src/
+  component.ts        The heart: defineComponent() and the Truc class
+  effects.ts          Effect orchestration: runEffects, updateElement
+  ui.ts               DOM queries (first/all), dependency resolution, selector type inference
+  parsers.ts          Parser/Reader type system and composition
+  events.ts           Event-driven sensor factory (createEventsSensor)
+  context.ts          Context protocol (provide/request) for dependency injection
+  scheduler.ts        rAF-based task deduplication
+  errors.ts           Domain-specific error classes
+  internal.ts         Internal signal map (getSignals) — shared by component.ts and pass.ts
+  util.ts             Logging, element introspection, property validation
+
+  effects/
+    attribute.ts      setAttribute, toggleAttribute
+    class.ts          toggleClass
+    event.ts          on() — event listener effect
+    html.ts           dangerouslySetInnerHTML
+    pass.ts           pass() — inter-component reactive property binding
+    property.ts       setProperty, show
+    style.ts          setStyle
+    text.ts           setText
+
+  parsers/
+    boolean.ts        asBoolean
+    json.ts           asJSON
+    number.ts         asInteger, asNumber
+    string.ts         asString, asEnum
+```
+
+## Dependency Graph
+
+Arrows mean "imports from". The graph flows bottom-up from leaf utilities to `component.ts`.
+
+```
+util.ts ─────────────────────────────────────────────┐
+errors.ts ──────── util.ts                           │
+scheduler.ts ──── (leaf, no internal imports)        │
+parsers.ts ─────── ui.ts (types only)                │
+parsers/* ──────── parsers.ts, ui.ts (types)         │
+                                                     │
+internal.ts ────── (leaf, signal storage)            │
+ui.ts ──────────── errors.ts, util.ts                │
+                                                     │
+effects.ts ─────── component.ts (types), errors.ts,  │
+                   ui.ts, util.ts                    │
+                                                     │
+effects/* ──────── component.ts (types), effects.ts  │
+                   + scheduler.ts, util.ts, etc.     │
+                                                     │
+events.ts ──────── component.ts (types), parsers.ts, │
+                   scheduler.ts, ui.ts               │
+                                                     │
+context.ts ─────── component.ts (types), parsers.ts, │
+                   ui.ts                             │
+                                                     │
+component.ts ───── effects.ts, errors.ts, parsers.ts,│
+                   ui.ts, util.ts                    │
+```
+
+The single external dependency is `@zeix/cause-effect`, which provides the reactive primitives: `createState`, `createComputed`, `createEffect`, `createMemo`, `createSensor`, `Signal`, `Memo`, `Sensor`, `batch`, and various type guards.
+
+## The Component Lifecycle
+
+`defineComponent(name, props, select, setup)` is the main entry point. It creates a class `Truc extends HTMLElement`, registers it via `customElements.define()`, and returns the class.
+
+### connectedCallback — initialization
+
+```
+connectedCallback()
+  │
+  ├─ 1. getHelpers(this)  →  [{ first, all }, resolveDependencies]
+  │     Determines query root (shadowRoot ?? this).
+  │     Tracks custom element dependencies found during queries.
+  │
+  ├─ 2. ui = { ...select({ first, all }), host: this }
+  │     User-provided select function queries DOM elements.
+  │     Object is frozen — immutable after creation.
+  │
+  ├─ 3. Initialize signals for each property:
+  │     ├─ Parser (≥2 args)?  →  parser(ui, this.getAttribute(key))
+  │     ├─ Function (1 arg)?  →  reader(ui)  or  methodProducer(ui)
+  │     └─ Otherwise          →  use value directly (static or Signal)
+  │     Each result is passed to #setAccessor(key, value).
+  │
+  └─ 4. resolveDependencies(() => {
+           this.#cleanup = runEffects(ui, setup(ui))
+         })
+         Waits for child custom elements to be defined (50ms timeout),
+         then runs the setup function and activates effects.
+```
+
+### #setAccessor — signal creation
+
+Takes a key and a value and creates the appropriate signal:
+
+- Already a `Signal` → use directly
+- A function → `createComputed(fn)` (read-only)
+- Anything else → `createState(value)` (read-write)
+
+For mutable signals, the value is wrapped in a `createSlot(signal)` — a Slot from `@zeix/cause-effect` that acts as an indirection layer. The Slot's `get`/`set` are used as the property descriptor on the component instance, which is what makes `host.count` reactive. Reading calls `signal.get()` inside effects, registering the dependency automatically.
+
+The Slot enables signal swapping: if `#setAccessor` is called again for an existing key (e.g., via `attributeChangedCallback`), it calls `slot.replace(newSignal)` instead of redefining the property. This is also the mechanism used by `pass()` to inject parent signals into a child component.
+
+### attributeChangedCallback — attribute sync
+
+Only fires for properties whose initializer `isParser` (function with ≥2 parameters). These are collected into `static observedAttributes` at class creation time.
+
+When an attribute changes: parse the new value through the parser, then assign it to the component property (which triggers `signal.set()`). Computed (read-only) signals are skipped.
+
+### disconnectedCallback — cleanup
+
+Calls the cleanup function returned by `runEffects()`, which tears down all effects and event listeners.
+
+## The Effect System
+
+### Three layers
+
+1. **`runEffects(ui, effects)`** — top-level orchestrator. Iterates the keys of the effects record. For each key, checks whether `ui[key]` is a `Memo` (from `all()`) or a single `Element` (from `first()`), and delegates accordingly.
+
+2. **`runElementsEffects(host, elements, effects)`** — handles dynamic collections. Creates a `createEffect()` that watches `Memo<E[]>`, computes added/removed elements by diffing against currently attached cleanups, and attaches/detaches per-element effects.
+
+3. **`runElementEffects(host, target, effects)`** — runs one or many effect functions against a single target element, collecting their cleanup functions.
+
+### updateElement — the shared abstraction
+
+Every built-in effect (`setAttribute`, `toggleClass`, `setText`, `setProperty`, `setStyle`, `toggleAttribute`, `dangerouslySetInnerHTML`, `callMethod`, `focus`, `show`) follows the same pattern via `updateElement(reactive, updater)`:
+
+```
+updateElement(reactive, { op, name, read, update, delete? })
+  │
+  ├─ Captures fallback = read(target)     ← current DOM value
+  │
+  └─ createEffect(() => {
+       value = resolveReactive(reactive)   ← auto-tracks signal deps
+       if value === RESET   → use fallback
+       if value === null    → delete(target) if available, else use fallback
+       if value !== current → update(target, value)
+     })
+```
+
+The `Reactive<T>` type is a union of three forms:
+- `keyof P` — a string property name on the host (reads `host[name]`)
+- `Signal<T>` — a signal (calls `.get()`)
+- `(target: E) => T` — a reader function
+
+`resolveReactive()` handles all three and returns the concrete value. Because it calls `.get()` inside a `createEffect`, signal dependencies are automatically tracked.
+
+### The RESET sentinel
+
+`RESET` is a `Symbol('RESET')` typed as `any`. When a reactive resolves to `RESET` (e.g., the reader function threw an error), the effect restores the original DOM value captured at setup time.
+
+### Built-in effects at a glance
+
+| Effect | Op | What it does |
+|---|---|---|
+| `setAttribute(name, reactive?)` | `a` | Sets an attribute with URL safety validation |
+| `toggleAttribute(name, reactive?)` | `a` | Boolean attribute: present when truthy |
+| `toggleClass(token, reactive?)` | `c` | Adds/removes a CSS class |
+| `setText(reactive)` | `t` | Replaces non-comment child nodes with a text node |
+| `setProperty(key, reactive?)` | `p` | Sets a DOM property directly |
+| `show(reactive)` | `p` | Controls `el.hidden` |
+| `setStyle(prop, reactive?)` | `s` | Sets/removes an inline style |
+| `dangerouslySetInnerHTML(reactive, opts?)` | `h` | Sets innerHTML, optionally in a shadow root |
+
+All default their `reactive` parameter to the effect name (e.g., `setAttribute('href')` reads `host.href`).
+
+### on() — event listener effect
+
+`on(type, handler, options?)` is different from `updateElement`-based effects. It directly attaches an event listener to the target element. The handler receives the event and may return a partial property update object like `{ count: host.count + 1 }`. If it does, the updates are applied to the host in a `batch()`. For passive events (scroll, resize, touch, wheel), execution is deferred via `schedule()`.
+
+### pass() — inter-component binding
+
+`pass(props)` replaces the backing signal of a child Le Truc component's Slot properties. It uses `getSignals(target)` to access the child's internal signal map, then for each passed prop calls `slot.replace(signal)` with a new signal derived from the parent's reactive value. This creates a live reactive binding between parent and child without the child needing to know about the parent. No cleanup/restore is needed: when the parent unmounts, the child is torn down as well.
+
+## The UI Query System
+
+`getHelpers(host)` returns `[{ first, all }, resolveDependencies]`.
+
+### first(selector, required?)
+
+Calls `root.querySelector()`. If the matched element is an undefined custom element, its tag name is added to the dependency set. Returns the element or `undefined` (throws `MissingElementError` if `required` is provided and element is missing).
+
+### all(selector, required?)
+
+Returns a `Memo<E[]>` created by `createElementsMemo()`. This sets up a `MutationObserver` (lazily, via the `watched` option on `createMemo`) that watches for `childList`, `subtree`, and relevant attribute changes. The memo always contains the current matching elements; added/removed diffs are derived downstream where needed (for example in `runElementsEffects`).
+
+The `MutationObserver` config is smart about which attributes to watch: `extractAttributes(selector)` parses the CSS selector to find attribute names implied by `.class`, `#id`, and `[attr]` patterns.
+
+### Dependency resolution
+
+During `first()` and `all()` calls, any matched custom element that isn't yet defined (matches `:not(:defined)`) is collected. `resolveDependencies(callback)` then awaits `customElements.whenDefined()` for all of them with a 50ms timeout. On timeout, it logs a `DependencyTimeoutError` but still runs the callback — effects proceed even if dependencies aren't ready.
+
+### Compile-time selector type inference
+
+The file contains a type-level CSS selector parser that infers the correct `HTMLElement` subtype from selector strings at compile time. `first('button')` returns `HTMLButtonElement`, `first('input[type="text"]')` returns `HTMLInputElement`, `first('.foo')` returns `HTMLElement`. This works through template literal types that split combinators, extract tag names, and look them up in `HTMLElementTagNameMap` / `SVGElementTagNameMap` / `MathMLElementTagNameMap`.
+
+## The Parser System
+
+Parsers transform HTML attribute strings into typed JavaScript values. The key design choice: **a Parser is a function with ≥2 parameters** (`(ui, value, old?) => T`), while a **Reader is any function with 1 parameter** (`(ui) => T`). This distinction is checked at runtime via `value.length >= 2` in `isParser()`.
+
+Parsers serve dual duty:
+1. As property initializers — `{ config: asJSON({ theme: 'light' }) }` — called during `connectedCallback` with the attribute's initial value
+2. As attribute watchers — automatically added to `observedAttributes` and called in `attributeChangedCallback`
+
+The `read(reader, fallback)` function composes a `LooseReader` (which may return `string | null | undefined`) with a parser/fallback into a clean `Reader<T>`. This is useful for reading DOM state and parsing it: `read(ui => ui.input.value, asInteger())`.
+
+## Event-Driven Sensors
+
+`createEventsSensor(init, key, events)` returns a Reader that creates a `Sensor<T>` — a signal driven by DOM events. It uses event delegation: all listeners are attached to the host, and when an event fires, the sensor finds the matching target element via `Node.contains()`.
+
+This is more declarative than `on()`: instead of imperatively updating host properties, the sensor produces a single reactive value from multiple event types. Use case: combining `input`, `change`, `focus`, `blur` into a single state value.
+
+The sensor is created via `createSensor(set => ...)` from `@zeix/cause-effect`, which manages the lifecycle (activate when read, deactivate when unwatched).
+
+## The Context Protocol
+
+Implements the [W3C Community Protocol for Context](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md) for dependency injection between components.
+
+### Provider side
+
+`provideContexts(['theme', 'user'])` returns a function `(host) => Cleanup` that adds a `context-request` event listener. When a matching request arrives, it stops propagation and provides a getter `() => host[context]` to the callback.
+
+This is used as a `MethodProducer` — a property initializer that returns `void` and exists only for its side effects (setting up the listener).
+
+### Consumer side
+
+`requestContext('theme', 'light')` returns a `Reader<Memo<T>>` used as a property initializer. During `connectedCallback`, it dispatches a `ContextRequestEvent` that bubbles up the DOM. If an ancestor provider intercepts it, the consumer receives a getter and wraps it in a `createMemo()`, creating a live reactive binding. If no provider responds, it falls back to the provided default value.
+
+## The Scheduler
+
+`schedule(element, task)` deduplicates high-frequency DOM updates using `requestAnimationFrame`. A `WeakMap<Element, () => void>` stores the latest task per element. If the same element schedules multiple tasks before the next frame, only the last one runs. This is used by `on()` for passive events and by `dangerouslySetInnerHTML`.
+
+## Security
+
+`setAttribute()` includes security validation:
+- Blocks `on*` event handler attributes (prevents XSS via attribute injection)
+- Validates URLs against an allowlist of safe protocols (`http:`, `https:`, `ftp:`, `mailto:`, `tel:`) — blocks `javascript:`, `data:`, etc.
+
+---
+
+## Open Questions
+
+### Parser/Reader distinction via `function.length`
+
+The distinction between Parser (≥2 params) and Reader (1 param) is detected at runtime via `value.length >= 2`. This is fragile — default parameters, rest parameters, and destructuring all affect `function.length` in non-obvious ways. A function `(ui, value = '') => ...` has `length === 1` and would be misclassified as a Reader. This is a potential source of subtle bugs. Would a branded type, a wrapper function, or a static property be a more robust marker?
+
+### MethodProducer is invisible in the type system
+
+`MethodProducer<P, U>` is defined as `(ui) => void`, but `isReaderOrMethodProducer` just checks `isFunction`. There's no way to distinguish a `Reader` from a `MethodProducer` at runtime — the only difference is that a MethodProducer returns `void` and relies on side effects (like `provideContexts`). Since `#setAccessor` is only called when the result is non-null, this works by convention, but the flow is non-obvious: the MethodProducer's return value (`undefined`) causes `#setAccessor` to be silently skipped, which is the desired behavior but isn't explicitly documented in the code.
+
+### Dependency timeout of 50ms
+
+`DEPENDENCY_TIMEOUT` is hardcoded at 50ms. This seems very short — on slower devices or with lazy-loaded component definitions, this could fire frequently. The error is logged but effects still run, so it's non-fatal, but it could cause effects to run against not-yet-upgraded elements. Is this timeout well-calibrated? Should it be configurable?
+
+### `resolveDependencies` uses Promise.race with error swallowing
+
+The dependency resolution catches all errors and runs the callback anyway. The `.catch(() => { callback() })` pattern means even unexpected errors (not just timeouts) are silently swallowed. The `DependencyTimeoutError` is constructed and passed to `reject`, but the actual logging happens... nowhere visible. The error is created inside a `new Promise((_, reject) => { reject(new DependencyTimeoutError(...)) })`, which rejects the race, but the `.catch` just calls `callback()` without logging the error.
+
+### `createEventsSensor` captures `targets` once
+
+In `createEventsSensor`, the `targets` array is computed once at sensor creation time from the current state of the `Memo`. If the collection changes later (elements added/removed), the sensor won't pick up new targets. For `Memo`-based collections that are specifically designed to be dynamic, this seems like a gap.
+
+### `dangerouslySetInnerHTML` script handling
+
+The script re-execution logic clones scripts by copying only `textContent` and `type`. This drops `src`, `async`, `defer`, `crossorigin`, `integrity`, `nomodule`, and other attributes. External scripts (`<script src="...">`) will silently become empty inline scripts. Is this intentional (security boundary) or an oversight?