assign-gingerly 0.0.52 → 0.0.54

package/README.md

@@ -1,4 +1,4 @@
-# assign-gingerly and assign-tentatively
+# assign-gingerly, assign-tentatively, and assign-from
 
 [![Playwright Tests](https://github.com/bahrus/assign-gingerly/actions/workflows/CI.yml/badge.svg?branch=baseline)](https://github.com/bahrus/assign-gingerly/actions/workflows/CI.yml)
 [![NPM version](https://badge.fury.io/js/assign-gingerly.png)](http://badge.fury.io/js/assign-gingerly)
@@ -9,7 +9,7 @@
 
 ## Introduction
 
-This package starts out innocently enough -- it provides two utility functions for carefully merging one object into another.  This is a primitive sorely lacking in the web, and this package is a polyfill for what we (me with a lot of help from AI) would like to see built into the platform.  We make no apologies about adding these features directly to the underlying API's, as it is part of a proposal which is sitting there gathering dust, with no apparent alternatives under consideration.  In particular the reference:
+This package starts out innocently enough -- it provides three utility functions for carefully merging one object into another.  This is a primitive sorely lacking in the web, and this package is a polyfill for what we (me with a lot of help from AI) would like to see built into the platform.  We make no apologies about adding these features directly to the underlying API's, as it is part of a proposal which is sitting there gathering dust, with no apparent alternatives under consideration.  In particular the reference:
 
 ```JavaScript
 import 'assign-gingerly/object-extension.js';
@@ -17,7 +17,7 @@ import 'assign-gingerly/object-extension.js';
 
 has the "side effect" of enhancing the platform API in a way that this proposal can only hope the platform chooses to adopt in the future (or some variation).
 
-One can achieve the same functionality with a little more work, and "playing nicer" with the platform by importing assign-gingerly.js and/or assign-tentatively.js, which has no such side effects.
+One can achieve the same functionality with a little more work, and "playing nicer" with the platform by importing assign-gingerly.js, assign-tentatively.js, and/or assignFrom.js, which has no such side effects.
 
 ## Object Extension Pattern
 
@@ -39,7 +39,7 @@ So in our view this package helps fill the void left by not supporting the "is"
 
 Anyway, let's start out detailing the more innocent features of this package / polyfill.
 
-The two utility functions are:
+The three utility functions are:
 
 ## assignGingerly
 
@@ -56,6 +56,22 @@ The second fundamental utility function is:
 
 assignTentatively provides a far more limited subset of functionality compared to assignGingerly.   The tradeoff is that assignTentatively can do something important assignGingerly cannot do -- be "reversed". This can be quite useful for some scenarios.  Think of how css "turns on" visual effects while conditions are met, then reverts to how things were before the conditions were met when the conditions are no longer met, as if nothing happened.  Another example is allowing user edits to be rolled back as they repeatedly hit "ctrl+z".
 
+The third fundamental utility function is:
+
+## assignFrom
+
+assignFrom builds on assignGingerly by adding a resolution step: RHS values that are `?.`-prefixed path strings are resolved against a source object before assignment.  This enables a declarative, data-driven pattern where a view model (or any source) feeds values into a target through path expressions — replacing imperative property lookups with a single configuration object.
+
+assignFrom adds support for:
+
+1.  Resolving RHS path strings against a source object (`from`).
+2.  Protocol resolution (`globalThis://`, `localStorage://`, custom protocols).
+3.  Handler plugins via the ` =>` operator for custom logic (template instantiation, DOM manipulation, etc.).
+4.  Looped substitution with `where_x_in` / `where_y_in` / `where_z_in` for expanding template patterns into multiple concrete assignments.
+5.  Spread merging via the `"..."` key.
+
+All of assignGingerly's features (nested paths, `withMethods`, `aka`, `@each`, `@eachTime`, registry, etc.) are inherited.
+
 ## Example 1 - assignGingerly as a "superset" of Object.assign:
 
 ```TypeScript
@@ -3425,6 +3441,691 @@ The `"..."` key causes the resolved object to be merged (spread) into the result
 
 **Note:** Both `resolveValues` and `assignFrom` are async (return Promises) to support async protocol handlers (e.g., IndexedDB, fetch). For patterns without protocols, the async overhead is negligible.
 
+## assignFrom Handlers (` =>` operator)
+
+`assignFrom` supports a plugin system via the ` =>` operator. When a LHS key ends with ` =>`, instead of normal assignment, a handler class is invoked to perform custom logic (DOM manipulation, template instantiation, etc.).
+
+### Defining and using a handler
+
+Handlers are provided via the `handlers` option — scoped to each `assignFrom` call:
+
+```JavaScript
+import { assignFrom } from 'assign-gingerly/assignFrom.js';
+
+class MyListHandler {
+    constructor(config) {
+        this.config = config;
+    }
+
+    async assign(lhsTarget, resolvedParams, options) {
+        const { list, template } = resolvedParams;
+        // Custom logic: e.g., clone template for each item in list
+    }
+}
+
+await assignFrom(myElement, {
+    '?.querySelector?.tbody =>': {
+        do: 'my-list',
+        resolve: {
+            list: '?.rankings',
+            template: 'globalThis://myTemplate'
+        }
+    }
+}, {
+    withMethods: ['querySelector'],
+    from: viewModel,
+    protocols: { globalThis: k => globalThis[k] },
+    handlers: {
+        'my-list': MyListHandler,  // class constructor
+    }
+});
+```
+
+Handlers can also be specified as import paths (dynamically loaded on demand):
+
+```JavaScript
+await assignFrom(myElement, {
+    '?.querySelector?.tbody =>': {
+        do: 'my-list',
+        resolve: { list: '?.rankings', template: 'globalThis://myTemplate' }
+    }
+}, {
+    from: viewModel,
+    withMethods: ['querySelector'],
+    protocols: { globalThis: k => globalThis[k] },
+    handlers: {
+        'my-list': './handlers/my-list.js',         // relative path
+        'vendor-chart': 'chart-package/handler.js', // bare specifier (import map)
+    }
+});
+```
+
+Import paths must be local (relative, absolute, or bare specifiers — no cross-domain URLs). The module's default export is checked first; otherwise the first exported class with an `assign` method is used.
+
+Built-in handlers (`builtIns.lazyLoad`, `builtIns.join`, etc.) auto-load without needing to be listed in `handlers`.
+
+**How it works:**
+
+1. Keys ending with ` =>` are separated from normal keys.
+2. Normal keys are processed via `resolveValues` + `assignGingerly` as usual.
+3. For handler keys: the LHS path is evaluated (with `withMethods` support) to get the target.
+4. The `resolve` map is processed through `resolveValues` — paths (`?.`), protocols (`globalThis://`), and literals are all resolved.
+5. The handler class (looked up via `do` in `options.handlers`, then built-in auto-load) is instantiated with the full config, then `assign(target, resolvedParams, options)` is called.
+
+**The `resolve` map supports:**
+- `?.` paths — resolved against `options.from`
+- Protocol strings — resolved via `options.protocols`
+- Plain literals — passed through unchanged
+
+### Built-in handler: `builtIns.lazyLoad`
+
+Conditionally loads (clones) a template into a target element. Uses comment markers to track inserted content and supports show/hide/remove modes. Built-in handlers are auto-loaded on demand — no explicit import is needed.
+
+```JavaScript
+await assignFrom(document.body, {
+    '?.querySelector?..mainView =>': {
+        do: 'builtIns.lazyLoad',
+        resolve: {
+            if: '?.isVisible',
+            instantiate: 'globalThis://myTemplate',
+        }
+    }
+}, { withMethods: ['querySelector'], from: myVM, protocols: { globalThis: k => globalThis[k] } });
+```
+
+**Resolve parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `if` | boolean | Show content when truthy, hide/remove when falsy |
+| `instantiate` | HTMLTemplateElement | The template to clone (typically resolved via globalThis protocol) |
+| `method` | string | `'appendChild'` (default) or `'prepend'` — where to place markers |
+| `forget` | boolean | If true, removes nodes entirely when `if` is false (default: hides with `hidden` attribute) |
+
+**Behavior:**
+
+- **First load (`if` = true, no existing content):** Clones the template, inserts content between `<!--?start name="X"-->` / `<!--?end-->` comment markers.
+- **Show (content exists but hidden):** Removes `hidden` attribute from elements between markers.
+- **Hide (`if` = false, `forget` = false):** Adds `hidden` attribute to elements between markers.
+- **Remove (`if` = false, `forget` = true):** Removes nodes between markers entirely. Markers persist for re-insertion if `if` becomes true again.
+
+This is useful for conditional rendering, routing, and lazy-loading views.
+
+### View Transitions
+
+Both `builtIns.lazyLoad` and `builtIns.lazyLoadSwitch` support animated transitions via the [View Transition API](https://developer.mozilla.org/docs/Web/API/View_Transition_API). Enable with `transitional: true` in the resolve map:
+
+```JavaScript
+await assignFrom(container, {
+    '?.querySelector?..outlet =>': {
+        do: 'builtIns.lazyLoad',
+        resolve: {
+            if: '?.isVisible',
+            instantiate: 'globalThis://myTemplate',
+            transitional: true,
+        }
+    }
+}, { withMethods: ['querySelector'], from: vm, protocols: { globalThis: k => globalThis[k] } });
+```
+
+**How it works:**
+
+1. When `transitional: true`, DOM mutations (show/hide/clone) are wrapped in `document.startViewTransition()`.
+2. Instead of the `hidden` attribute, a CSS class (`.ag-hide` by default) is toggled for visibility.
+3. The actual animation is entirely CSS-driven — you control timing, easing, and effects via your own styles.
+4. If `document.startViewTransition` is unavailable (older browsers), the handler falls back to direct DOM mutation with no animation.
+
+**CSS customization:**
+
+The handler injects a minimal default style (`.ag-hide { display: none }`) once per rootNode. Override it with your own for animated transitions:
+
+```css
+/* Fade + slide transition */
+.ag-hide {
+    opacity: 0;
+    transform: translateY(-10px);
+    transition: opacity 0.5s ease, transform 0.5s ease;
+}
+
+/* View transition keyframes (for cross-fade between old/new states) */
+::view-transition-old(root) {
+    animation: fade-out 0.5s ease;
+}
+::view-transition-new(root) {
+    animation: fade-in 0.5s ease;
+}
+```
+
+**Custom hide class:**
+
+Use the `hideClass` resolve parameter to use a different CSS class name:
+
+```JavaScript
+resolve: {
+    if: '?.isVisible',
+    instantiate: 'globalThis://myTemplate',
+    transitional: true,
+    hideClass: 'my-custom-hide',  // default: 'ag-hide'
+}
+```
+
+**Concurrency handling:**
+
+- Rapid toggling (e.g., clicking a button repeatedly) is handled gracefully.
+- An in-flight transition is cancelled (`skipTransition()`) before starting a new one.
+- Duplicate show/hide requests while one is pending are ignored (re-entry protection).
+
+**Routing example with transitions:**
+
+```JavaScript
+await assignFrom(container, {
+    '?.querySelector?..routerOutlet =>': [
+        { do: 'builtIns.lazyLoadSwitch', resolve: { lhs: '?.route', rhs: 'home', instantiate: 'globalThis://homeView', transitional: true } },
+        { do: 'builtIns.lazyLoadSwitch', resolve: { lhs: '?.route', rhs: 'settings', instantiate: 'globalThis://settingsView', transitional: true } },
+        { do: 'builtIns.lazyLoadSwitch', resolve: { lhs: '?.route', rhs: 'profile', instantiate: 'globalThis://profileView', transitional: true } },
+    ]
+}, { withMethods: ['querySelector'], from: router, protocols: { globalThis: k => globalThis[k] } });
+```
+
+**Shared utility for external consumers (`be-switched`, etc.):**
+
+The transition coordination logic is exported as a reusable utility:
+
+```JavaScript
+import { withTransition, ensureHideStyle } from 'assign-gingerly/transitionHelper.js';
+
+// Inject the hide class style once per rootNode
+ensureHideStyle(myShadowRoot);
+
+// Wrap any DOM mutation with view transition coordination
+withTransition(markerNode, 'show', true, () => {
+    element.classList.remove('ag-hide');
+});
+
+withTransition(markerNode, 'hide', true, () => {
+    element.classList.add('ag-hide');
+});
+```
+
+See the visual demo at `demos/view-transition-demo.html`.
+
+### Multiple Handlers
+
+When the RHS of a ` =>` key is an array, each element is treated as a separate handler config and they are executed sequentially (awaiting each before proceeding to the next). All handlers share the same LHS target.
+
+```JavaScript
+await assignFrom(document.body, {
+    '?.querySelector?..mainView =>': [
+        {
+            do: 'builtIns.lazyLoad',
+            resolve: {
+                if: '?.isVisible',
+                instantiate: 'globalThis://viewTemplate',
+            }
+        },
+        {
+            do: 'applyTheme',
+            resolve: {
+                theme: '?.currentTheme'
+            }
+        }
+    ]
+}, { withMethods: ['querySelector'], from: myVM, protocols: { globalThis: k => globalThis[k] } });
+```
+
+**Behavior:**
+
+- Empty array — silent no-op.
+- Single-element array — identical to passing the object directly.
+- Nested arrays — throws an error (not supported).
+- Mixed `do` values — fully supported, each handler is looked up independently.
+- Error handling — fail-fast. If a handler throws, remaining handlers are skipped.
+
+## Looped Substitution (`where_x_in`, `where_y_in`, `where_z_in`)
+
+`assignFrom` supports expanding template patterns into multiple concrete assignments via variable substitution. Placeholders `${x}`, `${y}`, and `${z}` in pattern keys and string values are replaced with each value from the corresponding option array.
+
+```JavaScript
+const vm = {
+    firstName: 'Monkey',
+    lastName: 'Luffy'
+};
+
+await assignFrom(myForm, {
+    '?.[name="${x}"]': '?.${x}'
+}, {
+    from: vm,
+    withMethods: ['querySelector'],
+    where_x_in: ['firstName', 'lastName']
+});
+
+// Expands to the equivalent of:
+// '?.[name="firstName"]': '?.firstName'   → querySelector('[name="firstName"]').value = 'Monkey'
+// '?.[name="lastName"]':  '?.lastName'    → querySelector('[name="lastName"]').value = 'Luffy'
+```
+
+**How it works:**
+
+1. Before any other processing, `assignFrom` checks for `where_x_in`, `where_y_in`, and `where_z_in` in options.
+2. For each pattern entry whose key or value contains the placeholder (e.g., `${x}`), the entry is expanded — one copy per value in the array.
+3. Substitution applies to both LHS keys and all RHS string values (including nested objects like handler `resolve` maps).
+4. Multiple variables produce a **cartesian product**: x is expanded first, then y, then z. Result count = x.length × y.length × z.length.
+5. Non-string RHS values pass through untouched.
+
+**Cartesian expansion with multiple variables:**
+
+```JavaScript
+await assignFrom(grid, {
+    '?.querySelector?.[data-row="${x}"][data-col="${y}"]?.textContent': '${x}-${y}'
+}, {
+    from: {},
+    withMethods: ['querySelector'],
+    where_x_in: ['1', '2'],
+    where_y_in: ['A', 'B']
+});
+
+// Produces 4 entries (2 × 2):
+// '?.[data-row="1"][data-col="A"]' → '1-A'
+// '?.[data-row="1"][data-col="B"]' → '1-B'
+// '?.[data-row="2"][data-col="A"]' → '2-A'
+// '?.[data-row="2"][data-col="B"]' → '2-B'
+```
+
+**With handler ( =>) keys:**
+
+Substitution applies inside handler `resolve` maps too:
+
+```JavaScript
+await assignFrom(container, {
+    '?.querySelector?..${x}View =>': {
+        do: 'builtIns.lazyLoad',
+        resolve: {
+            if: '?.${x}Visible',
+            instantiate: 'globalThis://${x}Template'
+        }
+    }
+}, {
+    from: vm,
+    withMethods: ['querySelector'],
+    protocols: { globalThis: k => globalThis[k] },
+    where_x_in: ['home', 'settings', 'profile']
+});
+```
+
+**Edge cases:**
+
+- Empty array (`where_x_in: []`) — template entries produce nothing (silent no-op).
+- Missing option — if a pattern contains `${x}` but `where_x_in` is not provided, the literal `${x}` remains in the string.
+- Entries without placeholders — passed through unchanged.
+
+### Built-in handler: `builtIns.join`
+
+Joins a resolved array into a single string. Supports nested sub-arrays with "all-or-nothing" semantics for optional segments. Uses the **return-value protocol** — the handler returns the joined string, which `processHandlerCommands` assigns back to the LHS path.
+
+```JavaScript
+const vm = {
+    lastName: 'Targaryen',
+    firstName: 'Helaena'
+};
+
+await assignFrom(oElement, {
+    '?.textContent =>': {
+        do: 'builtIns.join',
+        resolve: {
+            value: ['?.lastName', ', ', '?.firstName']
+        }
+    }
+}, { from: vm });
+
+// oElement.textContent = 'Targaryen, Helaena'
+```
+
+**How it works:**
+
+1. The `resolve.value` array is resolved by `resolveValues` — `?.` path strings are replaced with actual values from `options.from`.
+2. Top-level `null`/`undefined` values are filtered out.
+3. Nested sub-arrays use **all-or-nothing** semantics: if any element in a sub-array resolves to `null`/`undefined`, the entire sub-array is dropped.
+4. Remaining elements are joined with the separator (default: `''`, empty string).
+5. The joined string is returned and assigned to the LHS path.
+
+**Optional segments with nested arrays:**
+
+```JavaScript
+const vm = {
+    lastName: 'Targaryen',
+    middleName: undefined,  // not present
+    firstName: 'Helaena'
+};
+
+await assignFrom(oElement, {
+    '?.textContent =>': {
+        do: 'builtIns.join',
+        resolve: {
+            value: ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
+        }
+    }
+}, { from: vm });
+
+// middleName is undefined → sub-array [', ', undefined] is dropped entirely
+// oElement.textContent = 'Targaryen, Helaena'
+
+// If middleName were 'D':
+// oElement.textContent = 'Targaryen, D, Helaena'
+```
+
+**Custom separator:**
+
+```JavaScript
+await assignFrom(oElement, {
+    '?.textContent =>': {
+        do: 'builtIns.join',
+        separator: ' | ',
+        resolve: {
+            value: ['?.firstName', '?.lastName']
+        }
+    }
+}, { from: vm });
+
+// oElement.textContent = 'Helaena | Targaryen'
+```
+
+**Return-value protocol:**
+
+When a handler's `assign()` method returns a non-`undefined` value, `processHandlerCommands` assigns it back to the LHS path. This is how `builtIns.join` sets `textContent` — the handler computes the string and returns it. Existing handlers like `builtIns.lazyLoad` return `undefined` (void) and operate by side effects, so they're unaffected.
+
+### Built-in handler: `builtIns.microDataJoin`
+
+Renders a template array as semantic microdata-annotated DOM. Each dynamic value gets an appropriate HTML element based on its JavaScript type, with `itemprop` set to the property name.
+
+```JavaScript
+const vm = {
+    lastName: 'Targaryen',
+    firstName: 'Helaena',
+    birthDT: new Date('July 1, 109'),
+    age: 21,
+    isHappy: false
+};
+
+await assignFrom(oSection, {
+    '?.querySelector?.div =>': {
+        do: 'builtIns.microDataJoin',
+        resolve: {
+            template: [
+                { prop: 'firstName', val: '?.firstName' },
+                ' ',
+                { prop: 'lastName', val: '?.lastName' },
+                ' who was born on ',
+                { prop: 'birthDT', val: '?.birthDT' },
+                ' is ',
+                { prop: 'age', val: '?.age' },
+                ' years old'
+            ]
+        }
+    }
+}, { from: vm, withMethods: ['querySelector'] });
+```
+
+Produces:
+
+```html
+<div itemscope>
+    <!--?start name="microDataJoin"-->
+    <span itemprop="firstName">Helaena</span>
+     
+    <span itemprop="lastName">Targaryen</span>
+     who was born on 
+    <time itemprop="birthDT" datetime="0109-07-01T...">7/1/0109</time>
+     is 
+    <data itemprop="age" value="21">21</data>
+     years old
+    <!--?end-->
+</div>
+```
+
+**Type → element mapping:**
+
+| JS Type | HTML Element | Attributes | textContent |
+|---------|-------------|------------|-------------|
+| `string` | `<span>` | `itemprop` | the value |
+| `number` | `<data>` | `itemprop`, `value` (raw) | locale-formatted |
+| `boolean` | `<data>` | `itemprop`, `value` (true/false) | empty |
+| `Date` | `<time>` | `itemprop`, `datetime` (ISO) | locale-formatted |
+
+**Optional segments (nested arrays):**
+
+Same all-or-nothing semantics as `builtIns.join` — if any `val` in a nested sub-array is null/undefined, the entire sub-array is dropped:
+
+```JavaScript
+resolve: {
+    template: [
+        { prop: 'firstName', val: '?.firstName' },
+        [' ', { prop: 'middleName', val: '?.middleName' }],  // dropped if middleName is undefined
+        ' ',
+        { prop: 'lastName', val: '?.lastName' }
+    ]
+}
+```
+
+**Idempotent updates:**
+
+Uses comment markers (`<!--?start name="microDataJoin"-->` / `<!--?end-->`) to track rendered content. On first call, creates all elements. On subsequent calls, updates existing elements in place (no re-creation) — `textContent`, `value`, and `datetime` attributes are updated without touching the DOM structure.
+
+**Authoring with `md` tag:**
+
+The `md` tagged template literal produces the `{prop, val}` structure from proxy objects — full autocomplete and type safety:
+
+```TypeScript
+import { paths, md } from 'assign-gingerly/paths.js';
+
+interface Person { firstName: string; lastName: string; birthDT: Date; age: number; }
+const $ = paths<Person>();
+
+const template = md`${$.firstName} ${$.lastName} who was born on ${$.birthDT} is ${$.age} years old`;
+// Produces: [{ prop: 'firstName', val: '?.firstName' }, ' ', { prop: 'lastName', val: '?.lastName' }, ...]
+```
+
+For custom property names or per-segment formatting, pass an explicit object:
+
+```TypeScript
+const template = md`${$.firstName} ${{ prop: 'birthDate', val: $.birthDT, format: 'long' }}`;
+```
+
+## Typed Path Authoring with `paths`, `sp`, and `md`
+
+For JSON generated config files generated from TypeScript/`.mts`/`mjs` files during a build or server-side rendering, the `paths` utility provides compile-time autocomplete and type safety for `?.`-prefixed path strings. The `sp` tagged template literal ("split into parts") produces arrays suitable for `builtIns.join`. The `md` tagged template literal produces `{prop, val}` objects suitable for `builtIns.microDataJoin`.
+
+```TypeScript
+import { paths, sp } from 'assign-gingerly/paths.js';
+
+interface Person {
+    firstName?: string;
+    middleName?: string;
+    lastName: string;
+    address: { city: string; zip: string };
+}
+
+const $ = paths<Person>();
+
+// sp produces: ['?.lastName', ', ', '?.firstName']
+// with full autocomplete on $.lastName, $.firstName, etc.
+export default {
+    '?.textContent =>': {
+        do: 'builtIns.join',
+        resolve: {
+            value: sp`${$.lastName}, ${$.firstName}`
+        }
+    }
+};
+```
+
+**How `paths` works:**
+
+- `paths<T>()` creates a deeply-proxied object typed as `T`
+- Every property access returns a deeper proxy (e.g., `$.address.city`)
+- `.path` extracts the `?.`-prefixed string: `$.address.city.path` → `'?.address?.city'`
+- Inside `sp` template literals, `.path` is not needed — proxy objects are auto-detected
+
+**How `sp` works:**
+
+- `sp` (split into parts) is a tagged template literal
+- It interleaves static string segments with interpolated values
+- Path proxy objects are automatically converted to `?.`-prefixed strings
+- Arrays passed as interpolations are preserved as nested arrays (for optional segments)
+
+**Optional segments in `sp`:**
+
+```TypeScript
+const $ = paths<Person>();
+
+// Nested array for all-or-nothing segment:
+const value = sp`${$.lastName}${[', ', $.middleName]}, ${$.firstName}`;
+// ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
+```
+
+**Using `.path` outside of `sp`:**
+
+When you need the path string in a non-`sp` context (object keys, plain arrays, other expressions):
+
+```TypeScript
+const $ = paths<Person>();
+
+$.lastName.path           // '?.lastName'
+$.address.city.path       // '?.address?.city'
+
+// As an object key:
+const pattern = {
+    [$.textContent.path]: '?.firstName'  // '?.textContent': '?.firstName'
+};
+```
+
+**Benefits:**
+
+- Full IDE autocomplete on property names
+- Compile-time errors for typos (e.g., `$.lasName` → TS error)
+- Template literal syntax reads like a natural string template
+- Output is a plain JSON-serializable array
+- No runtime overhead beyond initial proxy creation
+
+**`md` — microdata template tag:**
+
+The `md` tag produces `{prop, val}` objects for `builtIns.microDataJoin`:
+
+```TypeScript
+import { paths, md } from 'assign-gingerly/paths.js';
+
+interface Person { firstName: string; lastName: string; birthDT: Date; age: number; }
+const $ = paths<Person>();
+
+const template = md`${$.firstName} ${$.lastName} born ${$.birthDT}, age ${$.age}`;
+// [{ prop: 'firstName', val: '?.firstName' }, ' ', { prop: 'lastName', val: '?.lastName' }, ' born ', { prop: 'birthDT', val: '?.birthDT' }, ', age ', { prop: 'age', val: '?.age' }]
+```
+
+For custom property names or per-segment config, pass an explicit object:
+
+```TypeScript
+md`${$.firstName} ${{ prop: 'birthDate', val: $.birthDT, format: 'long' }}`
+// [{ prop: 'firstName', val: '?.firstName' }, ' ', { prop: 'birthDate', val: '?.birthDT', format: 'long' }]
+```
+
+**Difference between `sp` and `md`:**
+
+| Tag | Output for proxy interpolation | Use with |
+|-----|-------------------------------|----------|
+| `sp` | `'?.firstName'` (path string) | `builtIns.join` |
+| `md` | `{ prop: 'firstName', val: '?.firstName' }` | `builtIns.microDataJoin` |
+
+Both auto-detect path proxies (no `.path` needed inside template literals) and preserve nested arrays for optional segments.
+
+## Cached Element Resolution with `#[x]` and `withIds`
+
+`assignFrom` supports cached element references via the `#[x]` syntax in LHS keys. This provides near-zero-cost repeated access to DOM elements (~10ns via WeakRef) instead of expensive `querySelector` calls (~3,000-17,000ns for class selectors at scale).
+
+```TypeScript
+import { assignFrom } from 'assign-gingerly/assignFrom.js';
+
+await assignFrom(document.body, {
+    '#[main]?.textContent': '?.greeting',
+    '#[main] =>': {
+        do: 'builtIns.lazyLoad',
+        resolve: { if: '?.showContent', instantiate: 'globalThis://myTemplate' }
+    }
+}, {
+    from: viewModel,
+    withIds: {
+        main: { qry: '.mainView' }  // find by class, auto-assign ID, cache
+    }
+});
+```
+
+**How it works:**
+
+1. On first encounter of `#[main]`, the element is found via `querySelector('.mainView')` against the target.
+2. If the element doesn't have an `id` attribute, one is auto-generated (`_ag0`, `_ag1`, etc.).
+3. A `WeakRef` to the element is cached in a module-level `WeakMap` keyed by rootNode.
+4. On subsequent calls, the cached `WeakRef.deref()` returns the element in ~10ns.
+5. If the WeakRef is collected (element was GC'd), falls back to `getElementById` (~10-100ns).
+
+**Two forms of `withIds` configuration:**
+
+```TypeScript
+withIds: {
+    x: { qry: '.mainView' },    // Object form: querySelector on target, auto-assign ID
+    y: 'existingId',             // String form: element already has an ID, just cache it
+}
+```
+
+**Chaining with `?.` paths:**
+
+`#[x]` anchors the start of the path. Further `?.` segments chain from the resolved element:
+
+```TypeScript
+await assignFrom(document.body, {
+    '#[form]?.querySelector?..username?.value': '?.username',
+    '#[form]?.querySelector?..email?.value': '?.email',
+    '#[header]?.style?.color': '?.themeColor',
+}, {
+    from: viewModel,
+    withMethods: ['querySelector'],
+    withIds: {
+        form: { qry: '.registration-form' },
+        header: 'page-header'
+    }
+});
+```
+
+**With handlers (` =>`):**
+
+```TypeScript
+await assignFrom(container, {
+    '#[outlet] =>': {
+        do: 'builtIns.lazyLoadSwitch',
+        resolve: { lhs: '?.route', rhs: 'home', instantiate: 'globalThis://homeView' }
+    }
+}, {
+    from: router,
+    withIds: { outlet: { qry: '.router-outlet' } },
+    protocols: { globalThis: k => globalThis[k] }
+});
+```
+
+**Performance context (from benchmarks at 5000 elements):**
+
+| Method | Chrome | Firefox | Safari |
+|--------|--------|---------|--------|
+| `querySelector('.class')` | 9,660ns | 6,810ns | 17,770ns |
+| `getElementById(id)` | 100ns | 20ns | 10ns |
+| `Map<id, WeakRef>.deref()` | 12ns | 40ns | 10ns |
+
+The `#[x]` + `withIds` pattern gives you the Map+WeakRef speed tier automatically.
+
+**Key behaviors:**
+
+- **Lazy resolution** — elements are resolved on first encounter, not eagerly at the start.
+- **Auto-ID generation** — IDs are short and predictable (`_ag0`, `_ag1`, ...), unique within the rootNode.
+- **GC-safe** — WeakRef cache doesn't prevent element garbage collection.
+- **Scoped to rootNode** — works correctly inside Shadow DOM (IDs are scoped per shadow root).
+- **`assignFrom` only** — this feature is not available in `assignGingerly` or `assignTentatively`.
+
 ## Custom Assignment with `static assignTo` Protocol
 
 Classes can opt into custom assignment behavior by defining a `static assignTo` method. When `assignGingerly` encounters a property whose current value is an instance of such a class, it delegates the assignment to `assignTo` instead of performing the default merge/replace logic.