assign-gingerly 0.0.58 → 0.0.60

package/README.md

@@ -19,6 +19,21 @@ has the "side effect" of enhancing the platform API in a way that this proposal
 
 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.
 
+For `assignFrom` method chaining on objects, separate extension modules are available — import only what you need:
+
+```JavaScript
+import 'assign-gingerly/assignFrom-extension.js';       // adds obj.assignFrom() — sync
+import 'assign-gingerly/assignFromAsync-extension.js';  // adds obj.assignFromAsync() — async
+```
+
+This enables fluent patterns like:
+
+```JavaScript
+oElement
+    .assignFrom({ '?.textContent': '?.greeting' }, { from: vm1 })
+    .assignFrom({ '?.style Y=': { width: '?.w' } }, { from: vm2 });
+```
+
 ## Object Extension Pattern
 
 Not only does this polyfill package allow merging data properties onto objects that are expecting them, this polyfill also provides the ability to merge *augmented behavior* onto run-time objects without sub classing all such objects of the same type. This includes the ability to spawn an instance of a class and "merge" it into the API of the original object in an elegant way that is easy to wrap one's brain around, without ever blocking access to the original object or breaking it.
@@ -58,15 +73,29 @@ assignTentatively provides a far more limited subset of functionality compared t
 
 The third fundamental utility function is:
 
-## assignFrom
+## assignFrom (and assignFromAsync)
+
+`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 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` is synchronous** — it resolves paths, expands substitutions, handles spreads, processes `#[x]` refs, and runs inferred assignments all without yielding to the event loop. Handler commands (` =>`), `beVigilant`, and `enhance` are fire-and-forget (kicked off asynchronously in the background).
+
+**`assignFromAsync`** is the awaitable variant for when you need to:
+- Use async protocol handlers (e.g., `fetch`-based resolution)
+- `await` handler completion before proceeding
+- Wait for `enhance` (EMC JSON imports) to finish
+
+```TypeScript
+import { assignFrom } from 'assign-gingerly/assignFrom.js';           // sync (default)
+import { assignFromAsync } from 'assign-gingerly/assignFromAsync.js';  // async when needed
+```
+
+For most use cases — including `manageTemplateList`, reactive merge cycles, and DOM binding — the sync `assignFrom` is the right choice. It delivers near-vanilla-JS performance by avoiding microtask overhead.
 
 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.).
+2.  Protocol resolution (`globalThis://`, `localStorage://`, custom sync protocols).
+3.  Handler plugins via the ` =>` operator for custom logic (fire-and-forget in sync mode, awaitable in async mode).
 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.
 
@@ -740,7 +769,20 @@ assignGingerly(div, {
 - Testing is done in mount-observer package (no tests in assign-gingerly)
 - Single @eachTime per path (nested @eachTime not currently supported)
 
-While we are in the business of passing values of object A into object B, we might as well add some extremely common behavior that allows updating properties of object B based on the current values of object B -- things like incrementing, toggling, and deleting.  Deleting is critical for assignTentatively, but is included with both functions.
+## Common Operation Support
+
+While we are in the business of passing values of object A into object B, we might as well add some extremely common behavior that allows updating properties of object B based on the current values of object B -- things like incrementing, toggling, deleting, and merging into sub-objects.  Deleting is critical for assignTentatively, but is included with both functions.
+
+| Operator | Name | Description | Example |
+|----------|------|-------------|---------|
+| ` +=` | Increment | Add to numeric value, concatenate strings, append to arrays | `'count +=': 5` |
+| ` =!` | Toggle | Negate a boolean (or any value via `!`) | `'visible =!': '.'` |
+| ` -=` | Delete | Remove properties from an object | `'?.data -=': 'key'` |
+| ` Y=` | Merge | Recursively `assignGingerly` into a sub-object | `'style Y=': { width: '100px' }` |
+| ` ?=` | Ternary | Conditional assignment (assignFrom only) — [details](docs/ternary-assignment.md) | `'?.text ?=': ['?.cond', 'yes', 'no']` |
+| ` =>` | Handler | Invoke a handler plugin (assignFrom only) | `'?.el =>': { do: 'builtIns.join', ... }` |
+
+All operators use a space before the suffix to distinguish them from property names. They compose with `?.` nested paths and `withMethods`.
 
 ## Example 4 - Incrementing values with += command
 
@@ -886,7 +928,101 @@ console.log(obj);
 
 
 
-## Example 7 - Reversible assignments with assignTentatively
+## Example 7 - Merging into sub-objects with Y= command
+
+The `Y=` command recursively merges an object into an existing sub-object — like a nested `assignGingerly` call, declared inline:
+
+```TypeScript
+const element = {
+    style: { color: 'blue', display: 'block' },
+    dataset: { userId: '1' }
+};
+
+assignGingerly(element, {
+    'style Y=': {
+        width: '100px',
+        height: '50px'
+    },
+    'dataset Y=': {
+        role: 'admin'
+    }
+});
+
+console.log(element.style);
+// { color: 'blue', display: 'block', width: '100px', height: '50px' }
+
+console.log(element.dataset);
+// { userId: '1', role: 'admin' }
+```
+
+This is equivalent to the more verbose path-per-property approach:
+
+```TypeScript
+assignGingerly(element, {
+    '?.style?.width': '100px',
+    '?.style?.height': '50px',
+    '?.dataset?.role': 'admin'
+});
+```
+
+**With `?.` nested paths:**
+
+```TypeScript
+const app = { config: { database: { host: 'localhost', port: 5432 } } };
+
+assignGingerly(app, {
+    '?.config?.database Y=': {
+        port: 3306,
+        ssl: true
+    }
+});
+// app.config.database = { host: 'localhost', port: 3306, ssl: true }
+```
+
+**Nested `Y=` (recursive composition):**
+
+`Y=` composes — the merged object can itself contain `Y=` keys:
+
+```TypeScript
+const app = {
+    config: {
+        database: { host: 'localhost', port: 5432 },
+        appName: 'OldApp'
+    }
+};
+
+assignGingerly(app, {
+    'config Y=': {
+        'database Y=': {
+            port: 3306,
+            ssl: true
+        },
+        appName: 'NewApp'
+    }
+});
+// config.database = { host: 'localhost', port: 3306, ssl: true }
+// config.appName = 'NewApp'
+```
+
+**Mixing with other operators:**
+
+```TypeScript
+assignGingerly(obj, {
+    'style Y=': { width: '100px' },      // merge into sub-object
+    '?.style?.opacity': '1',              // direct path assignment
+    'counter +=': 1,                      // increment
+    textContent: 'Hello'                  // plain assignment
+});
+```
+
+**Behavior notes:**
+- If the target property doesn't exist or isn't an object, the command is a silent no-op
+- Arrays in the RHS replace the target property (not concatenated) — consistent with normal `assignGingerly` behavior
+- Works with `withMethods` for DOM path evaluation (e.g., `'?.querySelector?..panel?.style Y='`)
+- The name `Y=` evokes a merge sign (Y) — two paths converging into one — combined with `=` to signal an assignment operator
+
+
+## Example 8 - Reversible assignments with assignTentatively
 
 The `assignTentatively` function works like `assignGingerly` but with a powerful addition: **reversibility**. It tracks changes and generates a reversal object that can undo all modifications:
 
@@ -1176,7 +1312,7 @@ obj
 console.log(obj); // { a: 1, b: { c: 2 }, d: 3 }
 ```
 
-**Note**: The `assignTentatively` method on Object.prototype is simply an alias for `assignGingerly` and does **not** provide the reversibility features of the standalone `assignTentatively` function described in Example 7. For reversible assignments, use the standalone function from `assign-gingerly/assignTentatively`.
+**Note**: The `assignTentatively` method on Object.prototype is simply an alias for `assignGingerly` and does **not** provide the reversibility features of the standalone `assignTentatively` function described in Example 8. For reversible assignments, use the standalone function from `assign-gingerly/assignTentatively`.
 
 The prototype extensions are non-enumerable and won't appear in `Object.keys()` or `for...in` loops.
 
@@ -1410,7 +1546,7 @@ interface EnhancementConfig<T, TObj = Element> {
 
 The `withAttrs` property enables automatic attribute parsing when the enhancement is spawned. See the [Parsing Attributes with parseWithAttrs](#parsing-attributes-with-parsewithattrs) section for details.
 
-It also tips off extending polyfills / libraries, in particular mount-observer, to be on te lookout for the attributes specified by withAttrs.  But *assign-gingerly, by itself, performs **no** DOM observing to automatically spawn the class instance*.  It expects consumers of the polyfill to programmatically attach such behavior/enhancements, and/or rely on alternative, higher level packages to be vigilant for enhancement opportunities. 
+It also tips off extending polyfills / libraries, in particular mount-observer, to be on the lookout for the attributes specified by withAttrs.  But *assign-gingerly, by itself, performs **no** DOM observing to automatically spawn the class instance*.  It expects consumers of the polyfill to programmatically attach such behavior/enhancements, and/or rely on alternative, higher level packages to be vigilant for enhancement opportunities. 
 
 The `canSpawn` static method allows enhancement classes to conditionally block spawning based on the target object. See the [Conditional Spawning with canSpawn](#conditional-spawning-with-canspawn) section for details.
 
@@ -3382,14 +3518,14 @@ assignFrom(target, {
 
 For full documentation, see [docs/assignFrom.md](docs/assignFrom.md).
 
-## Protocol Resolution in `resolveValues` and `assignFrom`
+## Protocol Resolution in `getValues` and `assignFrom`
 
-`resolveValues` (and by extension `assignFrom`) supports resolving values from external sources via protocol-prefixed strings. This enables declarative references to `globalThis`, `localStorage`, `sessionStorage`, or custom stores.
+`getValues` (and by extension `assignFrom`) supports resolving values from external sources via protocol-prefixed strings. This enables declarative references to `globalThis`, `localStorage`, `sessionStorage`, or custom stores.
 
 ```JavaScript
-import { resolveValues } from 'assign-gingerly/resolveValues.js';
+import { getValues } from 'assign-gingerly/getValues.js';
 
-const result = await resolveValues({
+const result = getValues({
     baseURL: 'globalThis://myAppConfig?.apiBaseUrl',
     authToken: 'localStorage://auth?.token',
     label: '?.title'  // normal path resolution still works
@@ -3405,7 +3541,7 @@ const result = await resolveValues({
 
 1. If a value contains `://` and the part before it matches a key in `protocols`, it's treated as a protocol reference.
 2. The protocol handler is called with the key portion (between `://` and the first `?.`, or end of string).
-3. If a `?.` path follows the key, it's resolved against the handler's result using `resolveValue`.
+3. If a `?.` path follows the key, it's resolved against the handler's result using `getValue`.
 4. If the protocol isn't found in the map, the value passes through unchanged (no error).
 
 **Path after protocol key:**
@@ -3425,7 +3561,7 @@ const result = await resolveValues({
 ```JavaScript
 import { assignFrom } from 'assign-gingerly/assignFrom.js';
 
-await assignFrom(myForm, {
+assignFrom(myForm, {
     "...": "globalThis://qmywdO1vr0SwyuIe4fvzxQ",
     path: "api/v2/:operation/:expression",
     headers: {
@@ -3439,7 +3575,96 @@ await assignFrom(myForm, {
 
 The `"..."` key causes the resolved object to be merged (spread) into the result before passing to `assignGingerly`, rather than being assigned to a property named `"..."`.
 
-**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.
+**Async protocol handlers:**
+
+For protocol handlers that return Promises (e.g., `fetch`, IndexedDB), use `resolveValues` (async) or `assignFromAsync`:
+
+```JavaScript
+import { resolveValues } from 'assign-gingerly/resolveValues.js';
+import { assignFromAsync } from 'assign-gingerly/assignFromAsync.js';
+
+// resolveValues is the async variant of getValues
+const result = await resolveValues(pattern, source, {
+    protocols: { api: async (key) => (await fetch(`/api/${key}`)).json() }
+});
+```
+
+## 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'
+};
+
+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
+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 assignFromAsync(container, {
+    '?.querySelector?..${x}View =>': {
+        do: 'builtIns.lazyLoad',
+        get: {
+            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.
 
 ## assignFrom Handlers (` =>` operator)
 
@@ -3450,7 +3675,7 @@ The `"..."` key causes the resolved object to be merged (spread) into the result
 Handlers are provided via the `handlers` option — scoped to each `assignFrom` call:
 
 ```JavaScript
-import { assignFrom } from 'assign-gingerly/assignFrom.js';
+import { assignFromAsync } from 'assign-gingerly/assignFromAsync.js';
 
 class MyListHandler {
     constructor(config) {
@@ -3463,10 +3688,10 @@ class MyListHandler {
     }
 }
 
-await assignFrom(myElement, {
+await assignFromAsync(myElement, {
     '?.querySelector?.tbody =>': {
         do: 'my-list',
-        resolve: {
+        get: {
             list: '?.rankings',
             template: 'globalThis://myTemplate'
         }
@@ -3484,10 +3709,10 @@ await assignFrom(myElement, {
 Handlers can also be specified as import paths (dynamically loaded on demand):
 
 ```JavaScript
-await assignFrom(myElement, {
+await assignFromAsync(myElement, {
     '?.querySelector?.tbody =>': {
         do: 'my-list',
-        resolve: { list: '?.rankings', template: 'globalThis://myTemplate' }
+        get: { list: '?.rankings', template: 'globalThis://myTemplate' }
     }
 }, {
     from: viewModel,
@@ -3504,28 +3729,62 @@ Import paths must be local (relative, absolute, or bare specifiers — no cross-
 
 Built-in handlers (`builtIns.lazyLoad`, `builtIns.join`, etc.) auto-load without needing to be listed in `handlers`.
 
+**Handler aliases:** The `handlers` option also accepts built-in names as values, allowing you to define short aliases (including emoji) for concise configs:
+
+```JavaScript
+import { builtInEmoji } from 'assign-gingerly/builtInEmoji.js';
+// { '📦': 'builtIns.lazyLoad', '🎚️': 'builtIns.lazyLoadSwitch', '🔗': 'builtIns.join', '🏷️': 'builtIns.microDataJoin', '📋': 'builtIns.manageTemplateList' }
+
+assignFrom(target, {
+    '?.textContent =>': { do: '🔗', get: { value: ['?.first', ' ', '?.last'] } }
+}, { from: vm, handlers: builtInEmoji });
+
+// Or define your own:
+assignFrom(target, pattern, {
+    from: vm,
+    handlers: { 'sw': 'builtIns.lazyLoadSwitch', 'list': 'builtIns.manageTemplateList' }
+});
+```
+
 **How it works:**
 
 1. Keys ending with ` =>` are separated from normal keys.
-2. Normal keys are processed via `resolveValues` + `assignGingerly` as usual.
+2. Normal keys are processed via `getValues` + `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.
+4. The `get` map (if present) is processed synchronously via `getValues` — no thread yield.
+5. The `resolve` map (if present) is processed asynchronously via `resolveValues` — yields to the microtask queue. Results are merged with `get` results.
+6. 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:**
+**The `get` and `resolve` maps support:**
 - `?.` paths — resolved against `options.from`
 - Protocol strings — resolved via `options.protocols`
 - Plain literals — passed through unchanged
 
+Use `get` for performance-sensitive handlers (synchronous, no yield). Use `resolve` when you need async protocol handlers (e.g., `fetch`). Both can coexist — `get` runs first, `resolve` merges on top:
+
+```JavaScript
+'?.querySelector?.tbody =>': {
+    do: 'builtIns.manageTemplateList',
+    get: {
+        forEach: '?.rankings',
+        instantiate: 'globalThis://country-ranking',
+    },
+    resolve: {
+        // Only for genuinely async protocols
+        remoteConfig: 'api://settings'
+    }
+}
+```
+
 ### 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, {
+await assignFromAsync(document.body, {
     '?.querySelector?..mainView =>': {
         do: 'builtIns.lazyLoad',
-        resolve: {
+        get: {
             if: '?.isVisible',
             instantiate: 'globalThis://myTemplate',
         }
@@ -3533,7 +3792,7 @@ await assignFrom(document.body, {
 }, { withMethods: ['querySelector'], from: myVM, protocols: { globalThis: k => globalThis[k] } });
 ```
 
-**Resolve parameters:**
+**Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -3541,25 +3800,81 @@ await assignFrom(document.body, {
 | `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) |
+| `placeholder` | string | Name of a pre-existing marker pair whose content is removed on first activation |
+| `assign` | object | Assignment config applied to cloned content before insertion (see below) |
 
 **Behavior:**
 
-- **First load (`if` = true, no existing content):** Clones the template, inserts content between `<!--?start name="X"-->` / `<!--?end-->` comment markers.
+- **First load (`if` = true, no existing content):** Clones the template, inserts content between `<!--?start name="X"-->` / `<!--?end-->` comment markers. If `placeholder` is specified, its content is removed first.
 - **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.
 
+**Placeholder content (SSR/streaming):**
+
+Use `placeholder` to remove pre-rendered "loading" content when real content first activates. The server streams placeholder content inside named markers; once JS runs and the condition is met, the placeholder is cleared and the template is cloned in its place:
+
+```html
+<div class="mainView">
+    <!--?start name="loading"-->
+    <div class="skeleton">Loading...</div>
+    <!--?end-->
+</div>
+```
+
+```JavaScript
+await assignFromAsync(container, {
+    '?.querySelector?..mainView =>': {
+        do: 'builtIns.lazyLoad',
+        get: {
+            if: '?.isReady',
+            instantiate: 'globalThis://mainTemplate',
+            placeholder: 'loading',
+        }
+    }
+}, { withMethods: ['querySelector'], from: vm, protocols: { globalThis: k => globalThis[k] } });
+```
+
+The placeholder is removed only on first activation (one-shot). If `if` later becomes false and then true again, the template is re-shown from its own markers — the placeholder does not reappear.
+
+**Assigning values to cloned content (`assign`):**
+
+Use `assign` to populate the cloned template's elements before they are inserted into the DOM. This uses the same pattern as `manageTemplateList`'s `fromEachItem`:
+
+```JavaScript
+await assignFromAsync(container, {
+    '?.querySelector?..panel =>': {
+        do: 'builtIns.lazyLoad',
+        get: {
+            if: '?.showPanel',
+            instantiate: 'globalThis://panelTemplate',
+            assign: {
+                assignToFragment: {
+                    '#[title]?.textContent': '?.panelTitle',
+                    '#[body]?.textContent': '?.panelContent'
+                },
+                withOptions: {
+                    at: { title: [0], body: [1] }
+                }
+            }
+        }
+    }
+}, { from: vm, withMethods: ['querySelector'], protocols: { globalThis: k => globalThis[k] } });
+```
+
+The `assign.assignToFragment` paths resolve against `options.from` (the same source that drives the `if` condition). For multi-element templates, use `assign.configs` (same zip semantics as `manageTemplateList`).
+
 ### 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, {
+await assignFromAsync(container, {
     '?.querySelector?..outlet =>': {
         do: 'builtIns.lazyLoad',
-        resolve: {
+        get: {
             if: '?.isVisible',
             instantiate: 'globalThis://myTemplate',
             transitional: true,
@@ -3598,10 +3913,10 @@ The handler injects a minimal default style (`.ag-hide { display: none }`) once
 
 **Custom hide class:**
 
-Use the `hideClass` resolve parameter to use a different CSS class name:
+Use the `hideClass` parameter to use a different CSS class name:
 
 ```JavaScript
-resolve: {
+get: {
     if: '?.isVisible',
     instantiate: 'globalThis://myTemplate',
     transitional: true,
@@ -3618,11 +3933,11 @@ resolve: {
 **Routing example with transitions:**
 
 ```JavaScript
-await assignFrom(container, {
+await assignFromAsync(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 } },
+        { do: 'builtIns.lazyLoadSwitch', get: { lhs: '?.route', rhs: 'home', instantiate: 'globalThis://homeView', transitional: true } },
+        { do: 'builtIns.lazyLoadSwitch', get: { lhs: '?.route', rhs: 'settings', instantiate: 'globalThis://settingsView', transitional: true } },
+        { do: 'builtIns.lazyLoadSwitch', get: { lhs: '?.route', rhs: 'profile', instantiate: 'globalThis://profileView', transitional: true } },
     ]
 }, { withMethods: ['querySelector'], from: router, protocols: { globalThis: k => globalThis[k] } });
 ```
@@ -3654,18 +3969,18 @@ See the visual demo at `demos/view-transition-demo.html`.
 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, {
+await assignFromAsync(document.body, {
     '?.querySelector?..mainView =>': [
         {
             do: 'builtIns.lazyLoad',
-            resolve: {
+            get: {
                 if: '?.isVisible',
                 instantiate: 'globalThis://viewTemplate',
             }
         },
         {
             do: 'applyTheme',
-            resolve: {
+            get: {
                 theme: '?.currentTheme'
             }
         }
@@ -3681,83 +3996,6 @@ await assignFrom(document.body, {
 - 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.
@@ -3768,10 +4006,10 @@ const vm = {
     firstName: 'Helaena'
 };
 
-await assignFrom(oElement, {
+assignFrom(oElement, {
     '?.textContent =>': {
         do: 'builtIns.join',
-        resolve: {
+        get: {
             value: ['?.lastName', ', ', '?.firstName']
         }
     }
@@ -3782,7 +4020,7 @@ await assignFrom(oElement, {
 
 **How it works:**
 
-1. The `resolve.value` array is resolved by `resolveValues` — `?.` path strings are replaced with actual values from `options.from`.
+1. The `get.value` array is resolved by `getValues` — `?.` 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).
@@ -3797,10 +4035,10 @@ const vm = {
     firstName: 'Helaena'
 };
 
-await assignFrom(oElement, {
+assignFrom(oElement, {
     '?.textContent =>': {
         do: 'builtIns.join',
-        resolve: {
+        get: {
             value: ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
         }
     }
@@ -3816,11 +4054,11 @@ await assignFrom(oElement, {
 **Custom separator:**
 
 ```JavaScript
-await assignFrom(oElement, {
+assignFrom(oElement, {
     '?.textContent =>': {
         do: 'builtIns.join',
         separator: ' | ',
-        resolve: {
+        get: {
             value: ['?.firstName', '?.lastName']
         }
     }
@@ -3846,10 +4084,10 @@ const vm = {
     isHappy: false
 };
 
-await assignFrom(oSection, {
+assignFrom(oSection, {
     '?.querySelector?.div =>': {
         do: 'builtIns.microDataJoin',
-        resolve: {
+        get: {
             template: [
                 { prop: 'firstName', val: '?.firstName' },
                 ' ',
@@ -3896,7 +4134,7 @@ Produces:
 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: {
+get: {
     template: [
         { prop: 'firstName', val: '?.firstName' },
         [' ', { prop: 'middleName', val: '?.middleName' }],  // dropped if middleName is undefined
@@ -3930,6 +4168,75 @@ For custom property names or per-segment formatting, pass an explicit object:
 const template = md`${$.firstName} ${{ prop: 'birthDate', val: $.birthDT, format: 'long' }}`;
 ```
 
+### Built-in handler: `builtIns.manageTemplateList`
+
+Clones a template once per item in an iterable, with keyed reconciliation for efficient updates. Each clone receives its item's data via `assignFrom`, and optionally shared data from the parent source.
+
+```JavaScript
+assignFrom(document.body, {
+    '?.querySelector?.tbody =>': {
+        do: 'builtIns.manageTemplateList',
+        get: {
+            forEach: '?.rankings',
+            instantiate: 'globalThis://country-ranking',
+        },
+        fromEachItem: {
+            assignToFragment: { '?.querySelector?.tr?.ish': '?.' },
+            withOptions: { withMethods: ['querySelector'], infer: true },
+            get: { key: '?.rank' }
+        }
+    }
+}, {
+    from: olympics2024Summary,
+    withMethods: ['querySelector'],
+    protocols: { globalThis: k => globalThis[k] }
+});
+```
+
+**How it works:**
+
+1. Resolves `forEach` (iterable) and `instantiate` (template) from the `resolve` block
+2. Clones the template once per item, buffering all clones into a `DocumentFragment`
+3. For each clone, calls `assignFrom(clone, assignToFragment, { from: item, ...withOptions })` — distributing the item's data
+4. Inserts the fragment between comment markers in one DOM operation
+5. On subsequent calls, reconciles by `key` — adds new items, removes missing ones, updates existing clones in place
+
+**Keyed reconciliation:**
+
+The `key` field (in `fromEachItem.get`) identifies each item for stable identity across updates:
+- New key → clone + append
+- Key removed → hide (or remove if `forget: true`)
+- Key still present → update clone in place (no re-cloning)
+
+Without `key`, positional matching is used (item[i] → clone[i]).
+
+**Shared parent data (`fromSource`):**
+
+Pass data from the outer VM into each clone (e.g., aggregate totals):
+
+```JavaScript
+fromSource: {
+    assignToFragment: {
+        '?.querySelector?.[part~="totalMedalCount"]?.textContent': '?.totalMedalCount'
+    },
+    withOptions: { withMethods: ['querySelector'] }
+}
+```
+
+**Wait for async rendering (`waitForSettled`):**
+
+Optionally wait for async operations inside the fragment to complete before committing to the live DOM:
+
+```JavaScript
+get: {
+    forEach: '?.rankings',
+    instantiate: 'globalThis://country-ranking',
+    waitForSettled: true,  // or { idleMs: 50, timeout: 2000 }
+}
+```
+
+For full details, see [docs/manage-template-list.md](docs/manage-template-list.md).
+
 ## 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`.
@@ -3951,7 +4258,7 @@ const $ = paths<Person>();
 export default {
     '?.textContent =>': {
         do: 'builtIns.join',
-        resolve: {
+        get: {
             value: sp`${$.lastName}, ${$.firstName}`
         }
     }
@@ -4041,13 +4348,13 @@ Both auto-detect path proxies (no `.path` needed inside template literals) and p
 `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';
+import { assignFromAsync } from 'assign-gingerly/assignFromAsync.js';
 
-await assignFrom(document.body, {
+await assignFromAsync(document.body, {
     '#[main]?.textContent': '?.greeting',
     '#[main] =>': {
         do: 'builtIns.lazyLoad',
-        resolve: { if: '?.showContent', instantiate: 'globalThis://myTemplate' }
+        get: { if: '?.showContent', instantiate: 'globalThis://myTemplate' }
     }
 }, {
     from: viewModel,
@@ -4065,21 +4372,65 @@ await assignFrom(document.body, {
 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:**
+**`withIds` — stable references with auto-assigned IDs:**
+
+All forms assign a unique ID to the resolved element (if it doesn't have one). This makes the reference resilient to future DOM mutations — once an element has an ID, it can be found regardless of structural changes.
+
+```TypeScript
+withIds: {
+    x: { qry: '.mainView' },    // querySelector on target, auto-assign ID
+    y: 'existingId',             // element already has an ID, cache via WeakRef
+    z: { path: [0, 1], expect: 'input', fallback: true },  // child index path + auto-ID + validation
+}
+```
+
+| Form | First access | Subsequent | Use case |
+|------|-------------|------------|----------|
+| `'existingId'` | getElementById (~10-100ns) | WeakRef cache (~10ns) | Singleton elements with known IDs |
+| `{ qry: '.x' }` | querySelector (~3,000ns) | — (re-queries each call) | Target-relative elements, stable against mutations |
+| `{ path: [0, 1] }` | children[i] (~2-4ns) | — (re-traverses each call) | Fast + stable (ID protects against future DOM changes) |
+
+**`at` — lightweight positional references (no IDs, no DOM pollution):**
+
+For repeated elements (e.g., per-row in `manageTemplateList`) where you control the template structure and don't want to assign 2,000 IDs to the DOM:
+
+```TypeScript
+at: {
+    a: [0],                                              // target.children[0]
+    b: [1],                                              // target.children[1]
+    c: { path: [0, 2], expect: '.info', fallback: true } // with validation
+}
+```
+
+`at` resolves by child index every call — no IDs assigned, no WeakRef cache, no DOM attributes added. ~2-4ns per index step. Use when:
+- The template structure is stable (you own it)
+- You want a clean DOM (no auto-generated `id` attributes)
+- You're rendering many items (1,000 rows × 2 refs = 2,000 fewer DOM attributes)
+
+Both `withIds` and `at` use the same `#[x]` syntax on LHS and RHS keys.
+
+**Validated paths with `expect` and `fallback`:**
+
+Both `withIds` and `at` support the `{ path, expect, fallback }` form for dev-time validation:
 
 ```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
+    nameInput: { path: [1], expect: 'input' },              // warn if [1] isn't an <input>
+    label:     { path: [0], expect: 'label', fallback: true } // warn + recover via querySelector
 }
 ```
 
+- `expect` — a CSS selector checked via `element.matches()` (~50-200ns). If the element at `path` doesn't match, a console warning is logged with the correct coordinates.
+- `fallback: true` — on mismatch, automatically recovers by falling back to `querySelector(expect)`. The corrected element is cached for subsequent access.
+- The correction diagnostic is loaded lazily (fire-and-forget dynamic import) — zero payload in the happy path.
+- Strip `expect`/`fallback` in production builds for maximum performance (or leave them — the overhead is a single `matches()` call).
+
 **Chaining with `?.` paths:**
 
 `#[x]` anchors the start of the path. Further `?.` segments chain from the resolved element:
 
 ```TypeScript
-await assignFrom(document.body, {
+assignFrom(document.body, {
     '#[form]?.querySelector?..username?.value': '?.username',
     '#[form]?.querySelector?..email?.value': '?.email',
     '#[header]?.style?.color': '?.themeColor',
@@ -4096,10 +4447,10 @@ await assignFrom(document.body, {
 **With handlers (` =>`):**
 
 ```TypeScript
-await assignFrom(container, {
+await assignFromAsync(container, {
     '#[outlet] =>': {
         do: 'builtIns.lazyLoadSwitch',
-        resolve: { lhs: '?.route', rhs: 'home', instantiate: 'globalThis://homeView' }
+        get: { lhs: '?.route', rhs: 'home', instantiate: 'globalThis://homeView' }
     }
 }, {
     from: router,
@@ -4118,6 +4469,24 @@ await assignFrom(container, {
 
 The `#[x]` + `withIds` pattern gives you the Map+WeakRef speed tier automatically.
 
+**RHS references (`#[x]` on the value side):**
+
+`#[x]` can also appear on the RHS (value side) to read properties from a cached element. Bare `#[x]` resolves to the element's ID string; append `?.` paths to access other properties:
+
+```TypeScript
+assignFrom(form, {
+    '?.querySelector?.label?.htmlFor': '#[nameInput]',           // → the input's ID string
+    '?.querySelector?.label?.title': '#[nameInput]?.type',       // → 'text', 'email', etc.
+    '?.headerText': '#[info]?.dataset?.user',                    // → nested property access
+}, {
+    from: {},
+    withIds: { nameInput: { qry: 'input' }, info: { qry: '.info' } },
+    withMethods: ['querySelector']
+});
+```
+
+This is useful for accessibility patterns (setting `label[for]` to an auto-generated input ID) and cross-referencing elements declaratively.
+
 **Key behaviors:**
 
 - **Lazy resolution** — elements are resolved on first encounter, not eagerly at the start.
@@ -4137,9 +4506,9 @@ const vm = {
     user: { role: 'admin', avatar: '/img/alice.png' }
 };
 
-await assignFrom(outerDiv, {}, {
+assignFrom(outerDiv, {}, {
     from: vm,
-    inferredAssignments: {
+    infer: {
         byItemprop: ['name', 'email', 'user']
     }
 });
@@ -4160,7 +4529,7 @@ For each key in `byItemprop`, this finds `[itemprop="${key}"]` elements within t
 **Pass `true` to infer all source keys:**
 
 ```TypeScript
-inferredAssignments: { byItemprop: true }
+infer: { byItemprop: true }
 ```
 
 For full details, see [docs/inferred-assignments.md](docs/inferred-assignments.md).
@@ -4170,9 +4539,9 @@ For full details, see [docs/inferred-assignments.md](docs/inferred-assignments.m
 Apply enhancements in bulk to matching elements using EMC (Element Mount Configuration) JSON files that enhancement packages already publish. No manual registration step needed — enhancements are auto-loaded and registered on demand.
 
 ```TypeScript
-import { assignFrom } from 'assign-gingerly/assignFrom.js';
+import { assignFromAsync } from 'assign-gingerly/assignFromAsync.js';
 
-await assignFrom(shadowRoot, { /* normal assignments */ }, {
+await assignFromAsync(shadowRoot, { /* normal assignments */ }, {
     from: vm,
     enhance: [
         { emc: 'be-bound/emc.json', matching: '[name]' },
@@ -5800,4 +6169,4 @@ Any web server that serves static files with server-side includes will do but...
 7. > git submodule update --init --recursive
 8. > npm install
 9. > npm run serve
-10. Open http://localhost:8000/demo/ in a modern browser
+10. Open http://localhost:8000/demo/ in a modern browser