assign-gingerly 0.0.57 → 0.0.59

package/README.md

@@ -58,15 +58,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.
 
@@ -3382,14 +3396,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 +3419,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 +3439,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 +3453,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 +3553,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 +3566,10 @@ class MyListHandler {
     }
 }
 
-await assignFrom(myElement, {
+await assignFromAsync(myElement, {
     '?.querySelector?.tbody =>': {
         do: 'my-list',
-        resolve: {
+        get: {
             list: '?.rankings',
             template: 'globalThis://myTemplate'
         }
@@ -3484,10 +3587,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,
@@ -3507,25 +3610,42 @@ Built-in handlers (`builtIns.lazyLoad`, `builtIns.join`, etc.) auto-load without
 **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 +3653,7 @@ await assignFrom(document.body, {
 }, { withMethods: ['querySelector'], from: myVM, protocols: { globalThis: k => globalThis[k] } });
 ```
 
-**Resolve parameters:**
+**Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -3556,10 +3676,10 @@ This is useful for conditional rendering, routing, and lazy-loading views.
 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 +3718,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 +3738,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 +3774,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 +3801,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 +3811,10 @@ const vm = {
     firstName: 'Helaena'
 };
 
-await assignFrom(oElement, {
+assignFrom(oElement, {
     '?.textContent =>': {
         do: 'builtIns.join',
-        resolve: {
+        get: {
             value: ['?.lastName', ', ', '?.firstName']
         }
     }
@@ -3782,7 +3825,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 +3840,10 @@ const vm = {
     firstName: 'Helaena'
 };
 
-await assignFrom(oElement, {
+assignFrom(oElement, {
     '?.textContent =>': {
         do: 'builtIns.join',
-        resolve: {
+        get: {
             value: ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
         }
     }
@@ -3816,11 +3859,11 @@ await assignFrom(oElement, {
 **Custom separator:**
 
 ```JavaScript
-await assignFrom(oElement, {
+assignFrom(oElement, {
     '?.textContent =>': {
         do: 'builtIns.join',
         separator: ' | ',
-        resolve: {
+        get: {
             value: ['?.firstName', '?.lastName']
         }
     }
@@ -3846,10 +3889,10 @@ const vm = {
     isHappy: false
 };
 
-await assignFrom(oSection, {
+assignFrom(oSection, {
     '?.querySelector?.div =>': {
         do: 'builtIns.microDataJoin',
-        resolve: {
+        get: {
             template: [
                 { prop: 'firstName', val: '?.firstName' },
                 ' ',
@@ -3896,7 +3939,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 +3973,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'], inferredAssignments: 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 +4063,7 @@ const $ = paths<Person>();
 export default {
     '?.textContent =>': {
         do: 'builtIns.join',
-        resolve: {
+        get: {
             value: sp`${$.lastName}, ${$.firstName}`
         }
     }
@@ -4041,13 +4153,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,
@@ -4079,7 +4191,7 @@ withIds: {
 `#[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 +4208,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,
@@ -4137,7 +4249,7 @@ const vm = {
     user: { role: 'admin', avatar: '/img/alice.png' }
 };
 
-await assignFrom(outerDiv, {}, {
+assignFrom(outerDiv, {}, {
     from: vm,
     inferredAssignments: {
         byItemprop: ['name', 'email', 'user']
@@ -4170,9 +4282,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]' },