microtags 0.0.1 → 0.0.5

package/README.md

@@ -1,6 +1,6 @@
 # microtags
 
-![tests](https://github.com/nichoth/microtags/actions/workflows/nodejs.yml/badge.svg)
+[![tests](https://img.shields.io/github/actions/workflow/status/nichoth/microtags/nodejs.yml?style=flat-square)](https://github.com/nichoth/microtags/actions/workflows/nodejs.yml)
 [![types](https://img.shields.io/npm/types/microtags?style=flat-square)](README.md)
 [![module](https://img.shields.io/badge/module-ESM%2FCJS-blue?style=flat-square)](README.md)
 [![semantic versioning](https://img.shields.io/badge/semver-2.0.0-blue?logo=semver&style=flat-square)](https://semver.org/)
@@ -9,9 +9,11 @@
 [![gzip size](https://img.shields.io/bundlephobia/minzip/microtags?style=flat-square)](https://bundlephobia.com/package/microtags)
 [![license](https://img.shields.io/badge/license-Big_Time-blue?style=flat-square)](LICENSE)
 
-Web component helper with reactive props, automatic cleanup,
-and no Shadow DOM. Reactive via
-[alien-signals](https://github.com/stackblitz/alien-signals).
+Web component helper with reactive props, automatic cleanup, and no
+[Shadow DOM](https://gomakethings.com/the-shadow-dom-is-an-antipattern/).
+Reactive via [alien-signals](https://github.com/stackblitz/alien-signals).
+
+**Size**: 3.41 kB with all dependencies, minified and brotlied
 
 Inspired by [nanotags](https://nanotags.psdcoder.dev/). Reactive props use
 **alien-signals** instead of nanostores atoms.
@@ -21,30 +23,85 @@ Inspired by [nanotags](https://nanotags.psdcoder.dev/). Reactive props use
 <!-- toc -->
 
 - [Install](#install)
+  * [Import map](#import-map)
+  * [Pre-bundled](#pre-bundled)
 - [Example](#example)
+  * [Client-side validation](#client-side-validation)
 - [Serverside Example](#serverside-example)
+  * [`.TAG`](#tag)
+  * [`.refs`](#refs)
 - [API](#api)
   * [Props](#props)
-  * [define](#define)
-  * [withProps](#withprops)
-  * [withRefs](#withrefs)
-  * [withContexts](#withcontexts)
-  * [setup and ctx](#setup-and-ctx)
-- [Subpaths](#subpaths)
-  * [microtags/context](#microtagscontext)
-  * [microtags/render](#microtagsrender)
+    + [`withProps`](#withprops)
+  * [Refs](#refs)
+    + [`withRefs`](#withrefs)
+    + [Element types](#element-types)
+  * [`define`](#define)
+  * [`withContexts`](#withcontexts)
+  * [`setup` and `ctx`](#setup-and-ctx)
+    + [peek and untracked](#peek-and-untracked)
+- [Templates](#templates)
+- [Subpath Exports](#subpath-exports)
+  * [`microtags/context`](#microtagscontext)
+  * [`microtags/render`](#microtagsrender)
+    + [`renderList`](#renderlist)
+    + [`render`](#render)
+    + [Templates](#templates-1)
 - [Divergence from nanotags](#divergence-from-nanotags)
 
 <!-- tocstop -->
 
 </details>
 
+----------------------------------------------------------------------
 ## Install
+----------------------------------------------------------------------
 
 ```sh
 npm i -S microtags
 ```
 
+### Import map
+
+No build step needed. Resolve `microtags` with an
+[import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap)
+and `esm.sh`.
+
+
+```html
+<script type="importmap">
+{
+    "imports": {
+        "microtags": "https://esm.sh/microtags"
+    }
+}
+</script>
+
+<script type="module">
+    import { define } from 'microtags'
+</script>
+```
+
+Subpaths follow the same URL pattern: `microtags/context`, `microtags/render`.
+
+### Pre-bundled
+
+For raw-file CDNs (jsDelivr, unpkg) or local files, where dependencies are
+not resolved for you, use the pre-bundled `microtags/min` build. It is a
+single self-contained file with `alien-signals` inlined, so no other
+mappings are needed:
+
+```html
+<script type="importmap">
+{
+    "imports": {
+        "microtags": "https://cdn.jsdelivr.net/npm/microtags/dist/index.min.js"
+    }
+}
+</script>
+```
+
+
 ----------------------------------------------------------------------
 ## Example
 ----------------------------------------------------------------------
@@ -54,13 +111,13 @@ to do client-side-rendered components, that is possible. You would update the
 DOM inside `.setup`.
 
 Since the full HTML exists already, defining your components in the
-client-side JS is about "hydrating" the page only (adding behavior).
+client-side JS is about "hydrating" the page (adding behavior).
 
 ---
 
 `withProps`, `withRefs`, and `withContexts` are optional and can appear in
-any order. setup ends the chain: it calls `customElements.define` under the hood
-and returns a typed constructor.
+any order. `.setup` ends the chain: it calls `customElements.define` under the
+hood and returns a typed constructor.
 
 ```ts
 import { define } from 'microtags'
@@ -117,36 +174,130 @@ export const myCounter = define('my-counter')
 </my-counter>
 ```
 
+### Client-side validation
+
+See [example/subscribe-form.ts](./example/subscribe-form.ts).
+
+There are two separate things people call "validation", and `microtags`
+handles them in different places:
+
+1. **Prop validation** checks the attributes passed *into* a component.
+   Pass a [Standard Schema](https://standardschema.dev) (Zod, Valibot,
+   ArkType) to [`p.schema`](#withprops); it coerces the attribute value
+   and falls back to `undefined` when the value doesn't match.
+2. **Form input validation** checks live user input in a form, for example a
+   value that changes on every keystroke and needs to report *why* it is invalid.
+   There is no dedicated API for this. Validate the schema directly
+   inside `.setup()` and hold the result in a signal:
+
+The example below is the second kind -- form input (client-side) validation.
+
+```ts
+import { signal, startBatch, endBatch } from 'alien-signals'
+import { z } from 'zod'
+import { define } from 'microtags'
+
+const Email = z.email('Please enter a valid email address.')
+
+define('subscribe-form')
+    .withRefs(r => ({
+        form: r.one('form'),
+        input: r.one('input'),
+        submit: r.one('button'),
+        error: r.one('.error'),
+        status: r.one('.status'),
+    }))
+    .setup(ctx => {
+        const value = signal('')
+        const touched = signal(false)
+
+        // capture the live value (two-way; clears the field on reset)
+        ctx.bind(value, ctx.refs.input)
+        // only reveal errors after the first blur
+        ctx.on(ctx.refs.input, 'blur', () => touched(true))
+
+        ctx.effect(() => {
+            const result = Email.safeParse(value())
+            const message = result.success ?
+                '' :
+                result.error.issues[0].message
+            const showError = touched() && !result.success
+
+            ctx.refs.submit.disabled = !result.success
+            ctx.refs.input.setAttribute('aria-invalid', String(showError))
+            ctx.refs.error.textContent = showError ? message : ''
+        })
+
+        ctx.on(ctx.refs.form, 'submit', ev => {
+            ev.preventDefault()
+            if (!Email.safeParse(value()).success) return
+            ctx.refs.status.textContent = 'Thanks for subscribing!'
+            startBatch()
+            value('')
+            touched(false)
+            endBatch()
+        })
+    })
+```
+
+The error stays hidden until the field is blurred once, then updates live;
+the submit button is gated on validity. See `example/subscribe-form.ts`
+for the full working component.
+
 
 ----------------------------------------------------------------------
 ## Serverside Example
 ----------------------------------------------------------------------
 
+### `.TAG`
+
 Each tag name that you pass to `define` is exposed as a property `.TAG`
 on the return value. It is possible to import your web components in Node,
 even though Node does not have browser APIs.
 
+### `.refs`
+
+All refs are defined per-component, and the ref names are exposed at `.refs`,
+so you can import your web components on the server and read the ref names
+as strings.
+
 ```ts
-import { myCounter, countBtn, copyBtn } from './index.js'
+import { MyCounter, CountBtn, CopyBtn } from './index.js'
 
 // this runs in Node
 
 export function render ():string {
-    return `
-    <div>
-        <${myCounter.TAG} start="5">
-            <div data-ref="display" role="status" class="count"></div>
+    return `<div>
+        <${MyCounter.TAG} start="${START}">
+            <div data-ref="${MyCounter.refs.display}"
+                role="status"
+                class="count"
+            >${START}</div>
 
             <div class="controls">
-                <${countBtn.TAG} data-ref="dec" label="-" aria-label="Decrement">
-                </${countBtn.TAG}>
-                <${copyBtn.TAG} data-ref="copy"></${copyBtn.TAG}>
-                <${countBtn.TAG} data-ref="inc" label="+" aria-label="Increment">
-                </${countBtn.TAG}>
+                <${CountBtn.TAG}
+                    class="dec"
+                    data-ref="${MyCounter.refs.dec}"
+                    aria-label="Decrement"
+                >
+                    <button>-</button>
+                </${CountBtn.TAG}>
+
+                <${CopyBtn.TAG}
+                    class="copy"
+                    data-ref="${MyCounter.refs.copy}"
+                ></${CopyBtn.TAG}>
+
+                <${CountBtn.TAG}
+                    class="inc"
+                    data-ref="${MyCounter.refs.inc}"
+                    aria-label="Increment"
+                >
+                    <button>+</button>
+                </${CountBtn.TAG}>
             </div>
-        </${myCounter.TAG}>
-    </div>
-    `
+        </${MyCounter.TAG}>
+    </div>`
 }
 ```
 
@@ -156,7 +307,7 @@ export function render ():string {
 
 ### Props
 
-Declare reactive attributes via withProps. Each prop becomes:
+Declare reactive attributes via `withProps`. Each prop becomes:
 
 * An observed HTML attribute (auto-synced via `attributeChangedCallback`)
 * A signal at `ctx.props.propName`
@@ -170,27 +321,17 @@ Declare reactive attributes via withProps. Each prop becomes:
 | `p.boolean()` | `"true"` / `""` &rarr; `true`, `"false"` &rarr; `false` | `false` |
 | `p.oneOf(opts)` | Picklist enum, throws on invalid | throws |
 
-### define
-
-```ts
-import { define } from 'microtags'
 
-define(tagName: string): ComponentBuilder
-```
-
-Returns a fluent builder. Call `.setup()` to register the custom element.
-All builder methods are chainable and fully type-inferred.
-
-### withProps
+#### `withProps`
 
 ```ts
 .withProps(p => ({
-    count:   p.number(),        // attribute -> number  (NaN when absent)
-    label:   p.string(),        // attribute -> string  ('' when absent)
-    active:  p.boolean(),       // attribute -> boolean (true if present)
-    data:    p.json<MyType>(),  // attribute -> JSON.parse or undefined
-    schema:  p.schema(zodSchema),  // Standard Schema (Zod, Valibot, ArkType …)
-    value:   p.prop(0),         // property-only, not observed as an attribute
+    count:   p.number(),           // attribute -> number  (NaN when absent)
+    label:   p.string(),           // attribute -> string  ('' when absent)
+    active:  p.boolean(),          // attribute -> boolean (true if present)
+    data:    p.json<MyType>(),     // attribute -> JSON.parse or undefined
+    schema:  p.schema(zodSchema),  // Standard Schema (Zod, Valibot, ArkType)
+    value:   p.prop(0),            // property-only, not an observed attribute
 }))
 ```
 
@@ -201,18 +342,30 @@ ctx.props.count()      // read
 ctx.props.count(42)    // write
 ```
 
-### withRefs
+
+### Refs
+
+The `data-ref` attribute is a fallback. It's used when you don't pass a
+selector to `r.one()`. If you pass explicit CSS selectors to `withRefs`,
+e.g. `{ copy: r.one('button') }`, then the HTML does not require a `data-ref`
+attribute.
+
+#### `withRefs`
+
+Call `r.one()` / `r.all()` with no argument to match `[data-ref="<key>"]`,
+where `key` is the key name you pass in, or pass a CSS selector to query by
+it instead. Queries are resolved relative to the host element, during
+[the `connectedCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks).
+
 
 ```ts
 .withRefs(r => ({
-    button: r.one(),   // resolves [data-ref="button"] — throws if missing
-    items:  r.all(),   // resolves all [data-ref="items"] — empty array if none
+    button: r.one(),   // resolves [data-ref="button"] (throws if missing)
+    items:  r.all(),   // resolves all [data-ref="items"] (empty array if none)
 }))
 ```
 
-Call `r.one()` / `r.all()` with no argument to match `[data-ref="<key>"]`,
-or pass a CSS selector to query by it instead — resolved relative to the
-host element:
+If there are no `data-ref` attribtues in the HTML, use CSS query selectors.
 
 ```ts
 .withRefs(r => ({
@@ -221,7 +374,9 @@ host element:
 }))
 ```
 
-Refs are resolved from within the element during `connectedCallback`.
+See [#refs in serverside-rendering](#refs). Each component created with
+`micortags` exposes a `.refs` property that is an object map
+of ref names, eg `MyComponent.refs.copyButton`.
 
 #### Element types
 
@@ -255,35 +410,84 @@ Non-HTML refs (SVG / MathML) are out of scope: the type parameter is
 constrained to `HTMLElement`, so cast at the use site if you need one
 (e.g. `ctx.refs.icon as unknown as SVGSVGElement`).
 
-### withContexts
+
+### `define`
+
+```ts
+import { define } from 'microtags'
+
+define(tagName:string):ComponentBuilder
+```
+
+Returns a fluent builder. Call `.setup()` to register the custom element.
+All builder methods are chainable and fully type-inferred.
+
+### `withContexts`
+
+Context is for the case where a parent component defines some state, e.g. a
+`theme`, and the top-level (application) knows nothing about the theme. But the
+top level application does determine what children the parent renders
+(it passes in children), and the children need to know the theme.
+
+In that case, there is no way for the "parent" component to pass the theme to
+the children, and the root level (application) doesn't know what the theme is.
+
+Context gives us a "pull" based way to model this. The context-provider
+publishes the value, and any descendants opt in (or pull values) with
+`withContexts`, and the unknown-consumer and late-arrival problems are handled. 
+
+>
+> [!IMPORTANT]  
+> Context is only relevant on the client-side.
+> Context gives you nothing for first paint or the no-JS case.
+>
+
 
 ```ts
-import { createContext } from 'microtags/context'
+import { define } from 'microtags'
+import { createContext, provide } from 'microtags/context'
 
 const ThemeToken = createContext<string>()
 
-define('my-child')
+// Parent: owns the theme and publishes it to its descendants. It does
+// not reference the children below. The application composes those in.
+define('theme-provider')
+    .setup(ctx => {
+        ctx.onCleanup(provide(ctx.host, ThemeToken, 'dark'))
+    })
+
+// Child: opts in to the theme and reads whichever provider it is
+// composed into. It never receives the value as a prop.
+define('themed-card')
     .withContexts(() => ({
         theme: ThemeToken,
     }))
     .setup(ctx => {
         ctx.effect(() => {
-            console.log('theme is', ctx.contexts.theme)
+            ctx.host.dataset.theme = ctx.contexts.theme
         })
     })
 ```
 
+```html
+<!-- The application writes this markup. It nests <themed-card> inside
+     <theme-provider> but never sets the theme itself. -->
+<theme-provider>
+    <themed-card>Card content</themed-card>
+</theme-provider>
+```
+
 `setup()` is deferred until all required contexts resolve. See
-[microtags/context](#microtagscontext) for the provider API.
+[`microtags/context`](#microtagscontext) for the provider API.
 
-### setup and ctx
+### `setup` and `ctx`
 
 ```ts
 .setup(ctx => {
-    // ctx.host       — the HTMLElement itself
-    // ctx.props      — callable signals for each declared prop
-    // ctx.refs       — resolved DOM refs
-    // ctx.contexts   — consumed context values (reactive)
+    // ctx.host       the HTMLElement itself
+    // ctx.props      callable signals for each declared prop
+    // ctx.refs       resolved DOM refs
+    // ctx.contexts   consumed context values (reactive)
 
     // Run a tracked effect; auto-disposed on disconnect.
     ctx.effect(() => {
@@ -323,46 +527,265 @@ ctx.effect(() => {
 })
 ```
 
-## Subpaths
+## Templates
+
+[`render` and `renderList`](#microtagsrender) both take a `<template>`
+element as their second argument. A
+[`<template>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/template)
+is a native HTML element that holds markup the browser parses but does not
+render. Its contents are inert. Nothing inside paints, scripts do not run,
+images and other resources do not load, and the nodes stay out of the
+document until you clone them.
+
+See [./example/ssr.ts, line 89](./example/ssr.ts#L89).
+
+You write the markup for an item inside the template, and the
+reconciler stamps out a copy per item by cloning `template.content`. The
+template's first element child is the unit that gets cloned, so give each
+template a single root element.
+
+```html
+<item-list>
+    <ul></ul>
+    <template>
+        <li>
+            <span class="name"></span>
+            <span class="count"></span>
+        </li>
+    </template>
+</item-list>
+```
+
+The component resolves the list and the template as refs, then calls
+`renderList` from inside an effect so the list re-renders whenever the
+data signal changes.
+
+```ts
+import { define } from 'microtags'
+import { signal } from 'alien-signals'
+import { renderList } from 'microtags/render'
+
+type Item = { id:string; name:string; count:number }
+
+define('item-list')
+    .withRefs(r => ({
+        list: r.one('ul'),
+        row: r.one('template'),  // typed as HTMLTemplateElement
+    }))
+    .setup(ctx => {
+        const items = signal<Item[]>([
+            { id: 'a', name: 'Alice', count: 1 },
+            { id: 'b', name: 'Bob', count: 2 },
+        ])
+
+        // Re-runs on every items() change; only changed rows are touched.
+        ctx.effect(() => {
+            renderList(ctx.refs.list, ctx.refs.row, {
+                data: items(),
+                key: item => item.id,
+                update: (el, item) => {
+                    el.querySelector('.name')!.textContent = item.name
+                    el.querySelector('.count')!.textContent =
+                        String(item.count)
+                },
+            })
+        })
+    })
+```
+
+Because the template lives in your HTML instead of a JavaScript string, each
+render clones real DOM nodes rather than re-parsing HTML, and the `update`
+callback function mutates the DOM through properties like `textContent`.
+Nothing concatenates strings into markup, so there is no string-injection
+XSS vector.
+
+## Subpath Exports
+
+### `microtags/context`
 
-### microtags/context
+Cross-component context backed by alien-signals. A provider shares a value
+with everything nested inside it; a consumer reads the value from its nearest
+provider ancestor and reacts when it changes.
 
-Cross-component context backed by alien-signals.
+`provide` seeds a signal the first time it runs and updates that same signal
+on later calls, so re-providing inside an effect pushes changes to consumers.
 
 ```ts
-import { createContext, provide, resolveContextSignal } from 'microtags/context'
+import { define } from 'microtags'
+import { signal } from 'alien-signals'
+import { createContext, provide } from 'microtags/context'
 
 const ThemeToken = createContext<string>()
 
-// In a provider component's setup():
-const cleanup = provide(ctx.host, ThemeToken, 'dark')
-ctx.onCleanup(cleanup)
+// Provider: owns the theme and shares it with its descendants.
+define('theme-provider')
+    .withRefs(r => ({
+        toggle: r.one('button'),
+    }))
+    .setup(ctx => {
+        const theme = signal('light')
+
+        // Share with descendants; remove the entry on disconnect.
+        ctx.onCleanup(provide(ctx.host, ThemeToken, theme()))
 
-// In a consumer component via withContexts:
-ctx.contexts.theme   // 'dark' (reactive — re-runs effects when value changes)
+        // Re-provide on change. provide() updates the existing signal,
+        // so consumers that read this value re-run.
+        ctx.effect(() => provide(ctx.host, ThemeToken, theme()))
+
+        ctx.on(ctx.refs.toggle, 'click', () => {
+            theme(theme() === 'light' ? 'dark' : 'light')
+        })
+    })
+
+// Consumer: reads the nearest provider's theme, reactively.
+define('themed-card')
+    .withContexts(() => ({
+        theme: ThemeToken,
+    }))
+    .setup(ctx => {
+        // Reading ctx.contexts.theme inside an effect subscribes to it,
+        // so this re-runs whenever the provider toggles the value.
+        ctx.effect(() => {
+            ctx.host.dataset.theme = ctx.contexts.theme
+        })
+    })
+```
+
+```html
+<theme-provider>
+    <button>Toggle theme</button>
+    <themed-card>Card A</themed-card>
+    <themed-card>Card B</themed-card>
+</theme-provider>
 ```
 
-### microtags/render
+Both cards resolve to the same nearest `<theme-provider>`, so one click
+updates both. `resolveContextSignal(element, token)` is the low-level lookup
+those reads use under the hood; reach for it only when you need the provider
+signal imperatively.
+
+---
+
+### `microtags/render`
+
+A keyed reconciler for rendering lists and single items from a
+`<template>`, with no virtual DOM and no diffing library.
 
-DOM diffing helpers for rendering lists and single items without a virtual DOM.
+Microtags' state is reactive. When a signal changes, you want the DOM to follow.
+A way to do that for a list is to rebuild the markup on every change,
+e.g. `container.innerHTML = items.map(toHTML).join('')`.
+
+But rebuilding the markup on every change
+**throws away and recreates every node on every update**, losing any DOM
+state, like focus, text selection, scroll position, and the internal state of
+elements like `<video>`, `<details>`, and `<iframe>`. It also re-parses HTML on
+every pass, which creates a vector for string-concatenation XSS.
+
+**This library exports a `renderList` and a `render` function**.
+They diff against the live DOM. See
+[example/render-demo.ts](./example/render-demo.ts) for a working example.
+
+#### `renderList`
+
+Each item is matched to an existing element by its `key` attribute, so nodes
+are reused across renders rather than being recreated. Nodes whose keys
+disappear from the data are removed, surviving nodes are moved into place
+with the fewest DOM operations, and your `update` callback runs only for
+items whose value actually changed (compared by identity). Focus state and other
+DOM state survives a re-render, and changing one row touches only that row.
 
 ```ts
-import { render, renderList } from 'microtags/render'
+function renderList<T, E extends Element = Element> (
+    container:Element,
+    template:HTMLTemplateElement,
+    options:{
+        data:readonly T[];
+        key:(item:T, index:number) => string|number;
+        update:(el:E, item:T) => void;
+    }
+):void
+```
 
-// Render a single item into a container from a <template>.
-render(container, template, {
-    data: item,
-    update: (el, item) => { el.querySelector('span')!.textContent = item.name },
+##### `renderList` Example
+
+The markup is the list container plus a `<template>` for one row:
+
+```html
+<ul></ul>
+<template>
+    <li>
+        <span class="name"></span>
+    </li>
+</template>
+```
+
+Call `renderList` from inside an effect so it re-runs whenever the data
+signal changes:
+
+```ts
+ctx.effect(() => {
+    renderList(ctx.refs.list, ctx.refs.row, {
+        data: items(),
+        key: item => item.id,
+        update: (el, item) => {
+            el.querySelector('.name')!.textContent = item.name
+        },
+    })
 })
+```
+
+#### `render`
+
+`render` is the same machinery for a single item. It keys on the template, so
+repeated calls update the same element in place instead of replacing it.
+
+```ts
+function render<T, E extends Element = Element> (
+    container:Element,
+    template:HTMLTemplateElement,
+    options?:{
+        data?:T;
+        update?:(el:E, item:T) => void;
+    }
+):void
+```
+
+##### `render` Example
+
+The markup is a container plus a single-item `<template>`:
 
-// Render a keyed list with minimal DOM mutations.
-renderList(container, template, {
-    data: items,
-    key: item => item.id,
-    update: (el, item) => { /* update el from item */ },
+```html
+<div class="item"></div>
+<template>
+    <div>
+        <span></span>
+    </div>
+</template>
+```
+
+```ts
+import { render } from 'microtags/render'
+
+// Render a single item into the container from the <template>.
+render(container, template, {
+    data: item,
+    update: (el, item) => {
+        el.querySelector('span')!.textContent = item.name
+    },
 })
 ```
 
+For a runnable version, see `example/render-demo.ts`. It keeps an editable
+`<input>` in every row and a single item panel rendered with `render`, then
+re-renders on a timer and reorders on demand to show that focus, caret, and
+typed text survive: keyed nodes are reused and at most moved, never rebuilt.
+
+#### Templates
+
+
+
+---
+
 ## Divergence from nanotags
 
 | nanotags (nanostores) | microtags (alien-signals) |
@@ -373,8 +796,4 @@ renderList(container, template, {
 | `ctx.props.$count` (store) | `ctx.props.count` (callable signal) |
 
 Props declared with `withProps` are native alien-signals callable signals.
-There is no `$` prefix convention — all prop names are plain identifiers.
-
-```
-/ed3d-plan-and-execute:execute-implementation-plan /Users/nick/code/microtags/docs/implementation-plans/2026-06-27-two-way-bind-design/ /Users/nick/code/microtags/
-```
+There is no `$` prefix convention; all prop names are plain identifiers.