assign-gingerly 0.0.85 → 0.0.86

package/DX/emojis.js

@@ -7,7 +7,7 @@
  * import { builtInEmoji } from 'assign-gingerly/builtInEmoji.js';
  *
  * assignFrom(target, {
- *     '?.el =>': { do: '🔗', get: { value: ['?.first', ' ', '?.last'] } }
+ *     '?.el =>': { do: '🏷️', get: { template: [...] } }
  * }, { from: vm, handlers: builtInEmoji });
  */
 /**
@@ -17,14 +17,16 @@
  * |-------|---------|
  * | 📦 | builtIns.lazyLoad |
  * | 🎚️ | builtIns.lazyLoadSwitch |
- * | 🔗 | builtIns.join |
  * | 🏷️ | builtIns.microDataJoin |
  * | 📋 | builtIns.manageTemplateList |
+ *
+ * `join` is no longer a `do:` handler — it moved to the synchronous ` =&` operator
+ * (see syncOps/join.ts) and isn't looked up through options.handlers, so it has no
+ * emoji alias here.
  */
 export const builtInEmoji = {
     '📦': 'builtIns.lazyLoad',
     '🎚️': 'builtIns.lazyLoadSwitch',
-    '🔗': 'builtIns.join',
     '🏷️': 'builtIns.microDataJoin',
     '📋': 'builtIns.manageTemplateList',
     '📊': 'builtIns.rangeSelector',

package/DX/emojis.ts

@@ -7,7 +7,7 @@
  * import { builtInEmoji } from 'assign-gingerly/builtInEmoji.js';
  * 
  * assignFrom(target, {
- *     '?.el =>': { do: '🔗', get: { value: ['?.first', ' ', '?.last'] } }
+ *     '?.el =>': { do: '🏷️', get: { template: [...] } }
  * }, { from: vm, handlers: builtInEmoji });
  */
 
@@ -18,14 +18,16 @@
  * |-------|---------|
  * | 📦 | builtIns.lazyLoad |
  * | 🎚️ | builtIns.lazyLoadSwitch |
- * | 🔗 | builtIns.join |
  * | 🏷️ | builtIns.microDataJoin |
  * | 📋 | builtIns.manageTemplateList |
+ *
+ * `join` is no longer a `do:` handler — it moved to the synchronous ` =&` operator
+ * (see syncOps/join.ts) and isn't looked up through options.handlers, so it has no
+ * emoji alias here.
  */
 export const builtInEmoji= {
     '📦': 'builtIns.lazyLoad',
     '🎚️': 'builtIns.lazyLoadSwitch',
-    '🔗': 'builtIns.join',
     '🏷️': 'builtIns.microDataJoin',
     '📋': 'builtIns.manageTemplateList',
     '📊': 'builtIns.rangeSelector',

package/DX/paths.js

@@ -15,7 +15,7 @@
  *
  * const $ = paths<Person>();
  *
- * // Use sp (split into parts) to create arrays for builtIns.join:
+ * // Use sp (split into parts) to create arrays for the ' =&' join op:
  * const value = sp`${$.lastName}, ${$.firstName}`;
  * // ['?.lastName', ', ', '?.firstName']
  *
@@ -321,7 +321,7 @@ export function forEachKeyIn(keys, factory, options) {
  * string representation — no `.Path` call needed inside sp template literals.
  *
  * Arrays passed as interpolations are preserved as nested arrays (for
- * all-or-nothing optional segments in builtIns.join).
+ * all-or-nothing optional segments in the ' =&' join op).
  *
  * @example
  * const $ = paths<Person>();

package/DX/paths.ts

@@ -15,12 +15,12 @@
  * 
  * const $ = paths<Person>();
  * 
- * // Use sp (split into parts) to create arrays for builtIns.join:
+ * // Use sp (split into parts) to create arrays for the ' =&' join op:
  * const value = sp`${$.lastName}, ${$.firstName}`;
  * // ['?.lastName', ', ', '?.firstName']
  * 
- * // Use .Path for raw string contexts (object keys, plain arrays):
- * const key = $.textContent.Path;  // '?.textContent'
+ * // Use .Path for raw string contexts (object keys, plain arrays):
+ * const key = $.textContent.Path;  // '?.textContent'
  */
 
 /**
@@ -102,25 +102,25 @@ export interface PathsOptions {
 /**
  * Create a proxy for id-ref paths (#[varName]).
  * After the initial #[varName], further property access chains with ?. from the resolved element.
- * .Path returns the #[varName] prefix (optionally with further ?. path).
+ * .Path returns the #[varName] prefix (optionally with further ?. path).
  */
 function createIdRefProxy(idRef: string, options?: PathsOptions): any {
     function handler() {}
     Object.defineProperty(handler, PATH_SYMBOL, { value: idRef });
     return new Proxy(handler, {
         get(_, prop: string | symbol) {
-            if (prop === 'Path' || prop === PATH_SYMBOL) {
-                return idRef;
-            }
+            if (prop === 'Path' || prop === PATH_SYMBOL) {
+                return idRef;
+            }
             if (typeof prop === 'symbol') return undefined;
 
             const reservedToken = getReservedToken(prop);
             if (reservedToken === 'Each') {
                 return createIdRefProxy(appendPathSegment(idRef, '@each'), options);
             }
-            if (reservedToken && reservedToken !== 'Path') {
-                return createIdRefProxy(appendCommandSuffix(idRef, reservedToken), options);
-            }
+            if (reservedToken && reservedToken !== 'Path') {
+                return createIdRefProxy(appendCommandSuffix(idRef, reservedToken), options);
+            }
 
             // Chain further path segments after the id ref
             const chained = appendPathSegment(idRef, String(prop));
@@ -162,16 +162,16 @@ function createPathProxy(prefix: string, options?: PathsOptions): any {
 
     return new Proxy(handler, {
         get(_, prop: string | symbol) {
-            if (prop === 'Path' || prop === PATH_SYMBOL) {
-                return serializePath(prefix);
-            }
+            if (prop === 'Path' || prop === PATH_SYMBOL) {
+                return serializePath(prefix);
+            }
             // Ignore symbol access (Symbol.iterator, Symbol.toPrimitive, etc.)
             if (typeof prop === 'symbol') return undefined;
 
             const reservedToken = getReservedToken(String(prop));
-            if (reservedToken === 'Path') {
-                return serializePath(prefix);
-            }
+            if (reservedToken === 'Path') {
+                return serializePath(prefix);
+            }
             if (reservedToken === 'Each') {
                 return createPathProxy(appendPathSegment(prefix, '@each'), options);
             }
@@ -231,14 +231,14 @@ function createPathProxy(prefix: string, options?: PathsOptions): any {
  * 
  * @example
  * const $ = paths<Person>();
- * $.lastName.Path          // '?.lastName'
- * $.address.city.Path      // '?.address?.city'
+ * $.lastName.Path          // '?.lastName'
+ * $.address.city.Path      // '?.address?.city'
  * 
  * // With aka (reverse alias applied):
  * const $ = paths<MyEl>({ aka: { q: 'querySelector' } });
- * $.querySelector('.user').textContent.Path  // '?.q?..user?.textContent'
+ * $.querySelector('.user').textContent.Path  // '?.q?..user?.textContent'
  * 
- * // Inside sp template literals, .Path is not needed:
+ * // Inside sp template literals, .Path is not needed:
  * sp`${$.lastName}, ${$.firstName}`  // ['?.lastName', ', ', '?.firstName']
  */
 export function paths<T>(options?: PathsOptions): PathProxy<T> {
@@ -246,7 +246,7 @@ export function paths<T>(options?: PathsOptions): PathProxy<T> {
 }
 
 /**
- * Create an assignment pair: { [lhs.Path]: rhs.Path }.
+ * Create an assignment pair: { [lhs.Path]: rhs.Path }.
  * Used to express "set this target to this source value" in a spreadable form.
  * 
  * @example
@@ -373,10 +373,10 @@ export function forEachKeyIn<T>(
  * Interleaves static string segments with interpolated values.
  * 
  * Path proxy objects are auto-detected and converted to their `?.`-prefixed
- * string representation — no `.Path` call needed inside sp template literals.
+ * string representation — no `.Path` call needed inside sp template literals.
  * 
  * Arrays passed as interpolations are preserved as nested arrays (for
- * all-or-nothing optional segments in builtIns.join).
+ * all-or-nothing optional segments in the ' =&' join op).
  * 
  * @example
  * const $ = paths<Person>();

package/README.md

@@ -851,7 +851,8 @@ While we are in the business of passing values of object A into object B, we mig
 | ` -=` | 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', ... }` |
+| ` =>` | Handler | Invoke a handler plugin (assignFrom only) | `'?.el =>': { do: 'builtIns.lazyLoad', ... }` |
+| ` =&` | Sync op | Compute a value synchronously and assign it back (assignFrom only) — no dynamic import, no await, ever | `'?.text =&': { join: ['?.first', ' ', '?.last'] }` |
 
 All operators use a space before the suffix to distinguish them from property names. They compose with `?.` nested paths and `withMethods`.
 
@@ -2691,16 +2692,18 @@ await assignFromAsync(myElement, {
 
 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`.
+Built-in handlers (`builtIns.lazyLoad`, `builtIns.microDataJoin`, etc.) auto-load without needing to be listed in `handlers`.
+
+> `join` isn't in this list — it's a synchronous [` =&` op](#sync-op-join) now, not an async `do:` handler, so it's never dynamically imported and never awaited.
 
 **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' }
+// { '📦': 'builtIns.lazyLoad', '🎚️': 'builtIns.lazyLoadSwitch', '🏷️': 'builtIns.microDataJoin', '📋': 'builtIns.manageTemplateList' }
 
 assignFrom(target, {
-    '?.textContent =>': { do: '🔗', get: { value: ['?.first', ' ', '?.last'] } }
+    '?.el =>': { do: '🏷️', get: { template: [...] } }
 }, { from: vm, handlers: builtInEmoji });
 
 // Or define your own:
@@ -2960,9 +2963,15 @@ await assignFromAsync(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.
 
-### Built-in handler: `builtIns.join`
+**Return-value protocol:**
+
+When a handler's `assign()` method returns a non-`undefined` value, `processHandlerCommands` assigns it back to the LHS path. Handlers like `builtIns.lazyLoad` return `undefined` (void) and operate by side effects instead.
+
+### Sync op: 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.
+` =&` is a separate operator from ` =>`, for computed values that have nothing to await — no dynamic import, no handler class, no microtask hop, ever. The RHS names exactly one op from a small built-in registry (`syncOps/registry.ts`); sibling keys are that op's own config. `join` is the first (and so far only) op in the registry.
+
+`join` resolves an array of `?.` paths and literals, then joins it into a single string. It supports nested sub-arrays with "all-or-nothing" semantics for optional segments.
 
 ```JavaScript
 const vm = {
@@ -2971,11 +2980,8 @@ const vm = {
 };
 
 assignFrom(oElement, {
-    '?.textContent =>': {
-        do: 'builtIns.join',
-        get: {
-            value: ['?.lastName', ', ', '?.firstName']
-        }
+    '?.textContent =&': {
+        join: ['?.lastName', ', ', '?.firstName']
     }
 }, { from: vm });
 
@@ -2984,11 +2990,11 @@ assignFrom(oElement, {
 
 **How it works:**
 
-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.
+1. The whole config object (`{ join: [...], separator: '...' }`) is resolved in one pass by `getValues` — `?.` path strings anywhere inside it, including nested inside the `join` array, are replaced with actual values from `options.from`.
+2. Top-level `null`/`undefined` values in the resolved array 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.
+4. Remaining elements are joined with `separator` (default: `''`, empty string).
+5. The joined string is assigned straight to the LHS path — every sync op always produces a value to assign; there's no opt-in return-value protocol to it like ` =>` has.
 
 **Optional segments with nested arrays:**
 
@@ -3000,11 +3006,8 @@ const vm = {
 };
 
 assignFrom(oElement, {
-    '?.textContent =>': {
-        do: 'builtIns.join',
-        get: {
-            value: ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
-        }
+    '?.textContent =&': {
+        join: ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
     }
 }, { from: vm });
 
@@ -3019,21 +3022,16 @@ assignFrom(oElement, {
 
 ```JavaScript
 assignFrom(oElement, {
-    '?.textContent =>': {
-        do: 'builtIns.join',
-        get: {
-            value: ['?.firstName', '?.lastName'],
-            separator: ' | '
-        }
+    '?.textContent =&': {
+        join: ['?.firstName', '?.lastName'],
+        separator: ' | '
     }
 }, { 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.
+**On `options.protocols`:** `getValues` runs synchronously and calls protocol handlers without awaiting them. `options.protocols` is typed to allow an async handler (`(key: string) => any | Promise<any>`), because ` =>`'s `resolve:` path can use one — but ` =&` has no await to catch a Promise coming back from one. If a resolved value under ` =&` turns out to be a thenable, assignFrom throws immediately rather than silently assigning `"[object Promise]"`. Use ` =>` with `resolve:` for handler configs that need an async protocol.
 
 ### Built-in handler: `builtIns.microDataJoin`
 
@@ -3095,7 +3093,7 @@ Produces:
 
 **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:
+Same all-or-nothing semantics as the [`join` sync op](#sync-op-join) — if any `val` in a nested sub-array is null/undefined, the entire sub-array is dropped:
 
 ```JavaScript
 get: {
@@ -3239,7 +3237,7 @@ assignFrom(element, {
 
 ## 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`.
+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 the [`join` sync op](#sync-op-join). The `md` tagged template literal produces `{prop, val}` objects suitable for `builtIns.microDataJoin`.
 
 ```TypeScript
 import { paths, sp } from 'assign-gingerly/DX/paths.js';
@@ -3256,11 +3254,8 @@ const $ = paths<Person>();
 // sp produces: ['?.lastName', ', ', '?.firstName']
 // with full autocomplete on $.lastName, $.firstName, etc.
 export default {
-    '?.textContent =>': {
-        do: 'builtIns.join',
-        get: {
-            value: sp`${$.lastName}, ${$.firstName}`
-        }
+    '?.textContent =&': {
+        join: sp`${$.lastName}, ${$.firstName}`
     }
 };
 ```
@@ -3268,9 +3263,9 @@ export default {
 **How `paths` works:**
 
 - `paths<T>()` creates a deeply-proxied object typed as `T`
-- Every property access returns a deeper proxy (e.g., `$.address.city`)
+- Every property access returns a deeper proxy (e.g., `$.address.city`)
 - Capitalized reserved tokens like `.Each` and `.EqNot` normalize into command syntax
-- `.Path` extracts the `?.`-prefixed string: `$.address.city.Path` → `'?.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:**
@@ -3339,7 +3334,7 @@ md`${$.firstName} ${{ prop: 'birthDate', val: $.birthDT, format: 'long' }}`
 
 | Tag | Output for proxy interpolation | Use with |
 |-----|-------------------------------|----------|
-| `sp` | `'?.firstName'` (path string) | `builtIns.join` |
+| `sp` | `'?.firstName'` (path string) | the `join` sync op |
 | `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.

package/assignFrom.js

@@ -7,11 +7,14 @@
  * For async protocol handlers or awaitable handler execution, use assignFromAsync.
  *
  * Handler commands (` =>`) are fire-and-forget (kicked off asynchronously, not awaited).
+ * Sync-op commands (` =&`) are always fully synchronous — see SYNC_OPS.
  */
 import { getValues, getValue } from './resolve/getValues.js';
 import assignGingerly from './assignGingerly.js';
 import { resolveIdVariable, parseIdRef } from './resolve/resolveIdRef.js';
 import { processInferredAssignments } from './inferredAssignments.js';
+import { resolveLhsPath } from './utils/resolveLhsPath.js';
+import { SYNC_OPS } from './syncOps/registry.js';
 /**
  * Supported substitution variables and their option keys.
  */
@@ -40,6 +43,48 @@ export function parseTernaryCommand(key) {
         return null;
     return key.substring(0, key.length - 3); // Remove ' ?=' suffix
 }
+/**
+ * Check if a key ends with the sync-op operator ' =&'.
+ */
+export function isSyncOpCommand(key) {
+    return key.endsWith(' =&');
+}
+/**
+ * Parse a =& sync-op command and extract the LHS path.
+ */
+export function parseSyncOpCommand(key) {
+    if (!isSyncOpCommand(key))
+        return null;
+    return key.substring(0, key.length - 3); // Remove ' =&' suffix
+}
+/**
+ * Throws if a resolved sync-op value (or anything nested inside it) is a thenable.
+ *
+ * getValues is synchronous by contract, but `options.protocols` handlers are
+ * typed to allow returning a Promise. A sync op has no await to catch that —
+ * left unchecked it would silently stringify as "[object Promise]" — so this
+ * turns it into a clear error instead.
+ */
+function assertNoThenable(value, opName, key) {
+    if (value == null)
+        return;
+    if (typeof value.then === 'function') {
+        throw new Error(`assignFrom: sync op '${opName}' (key "${key}") received an async value — ` +
+            `a protocol in options.protocols returned a Promise, which ' =&' cannot await. ` +
+            `Use ' =>' with 'resolve:' instead for async values.`);
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertNoThenable(item, opName, key);
+    }
+    else if (typeof value === 'object') {
+        const proto = Object.getPrototypeOf(value);
+        if (proto === Object.prototype || proto === null) {
+            for (const item of Object.values(value))
+                assertNoThenable(item, opName, key);
+        }
+    }
+}
 /**
  * Resolve a single value — if it's a `?.` path string, resolve against source.
  * If it's a protocol string, resolve via protocol. Otherwise pass through as literal.
@@ -343,6 +388,7 @@ export function categorizeKeys(expandedPattern) {
     const idRefNormalKeys = [];
     const idRefHandlerKeys = [];
     const ternaryKeys = [];
+    const syncOpKeys = [];
     for (const key of Object.keys(expandedPattern)) {
         if (isHandlerCommand(key)) {
             if (key.startsWith('#[')) {
@@ -355,6 +401,9 @@ export function categorizeKeys(expandedPattern) {
         else if (isTernaryCommand(key)) {
             ternaryKeys.push(key);
         }
+        else if (isSyncOpCommand(key)) {
+            syncOpKeys.push(key);
+        }
         else if (key.startsWith('#[')) {
             idRefNormalKeys.push(key);
         }
@@ -362,7 +411,7 @@ export function categorizeKeys(expandedPattern) {
             normalPattern[key] = expandedPattern[key];
         }
     }
-    return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys };
+    return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys };
 }
 /**
  * Merge pin and at into a single lookup map for resolveIdVariable.
@@ -420,7 +469,7 @@ export function assignFrom(target, pattern, options, permissionProcessor) {
     // Expand looped substitution variables
     const expandedPattern = expandSubstitutions(pattern, options);
     // Categorize keys
-    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys } = categorizeKeys(expandedPattern);
+    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys } = categorizeKeys(expandedPattern);
     const resolveOptions = { ...options, root: target, permissionProcessor };
     // Process ?= ternary keys (sync)
     if (ternaryKeys.length > 0) {
@@ -441,6 +490,33 @@ export function assignFrom(target, pattern, options, permissionProcessor) {
             assignGingerly(target, ternaryResolved, options, permissionProcessor);
         }
     }
+    // Process =& sync-op keys (sync — always, no dynamic import, no await, ever)
+    if (syncOpKeys.length > 0) {
+        for (const key of syncOpKeys) {
+            const lhsPath = parseSyncOpCommand(key);
+            if (lhsPath === null)
+                continue;
+            const config = expandedPattern[key];
+            if (!config || typeof config !== 'object' || Array.isArray(config)) {
+                throw new Error(`assignFrom: sync-op command "${key}" requires a config object naming exactly one op`);
+            }
+            const opName = Object.keys(config).find(k => k in SYNC_OPS);
+            if (!opName) {
+                throw new Error(`assignFrom: sync-op command "${key}" does not name a known op (${Object.keys(SYNC_OPS).join(', ')})`);
+            }
+            const resolvedConfig = getValues(config, options.from, resolveOptions);
+            assertNoThenable(resolvedConfig, opName, key);
+            const { [opName]: args, ...extra } = resolvedConfig;
+            const result = SYNC_OPS[opName](args, extra);
+            if (result === undefined)
+                continue;
+            const { lhsParent, lhsKey } = resolveLhsPath(target, lhsPath, options);
+            if (lhsParent != null && lhsKey != null
+                && !permissionProcessor?.redirectRestrictedProp(lhsParent, lhsKey, result)) {
+                lhsParent[lhsKey] = result;
+            }
+        }
+    }
     // Process normal keys via getValues (sync) + assignGingerly
     if (Object.keys(normalPattern).length > 0) {
         // Resolve #[x] references on RHS values before getValues

package/assignFrom.ts

@@ -7,12 +7,15 @@
  * For async protocol handlers or awaitable handler execution, use assignFromAsync.
  * 
  * Handler commands (` =>`) are fire-and-forget (kicked off asynchronously, not awaited).
+ * Sync-op commands (` =&`) are always fully synchronous — see SYNC_OPS.
  */
 
 import { getValues, getValue } from './resolve/getValues.js';
 import assignGingerly from './assignGingerly.js';
 import { resolveIdVariable, parseIdRef } from './resolve/resolveIdRef.js';
 import { processInferredAssignments } from './inferredAssignments.js';
+import { resolveLhsPath } from './utils/resolveLhsPath.js';
+import { SYNC_OPS } from './syncOps/registry.js';
 import type { PermissionProcessor, AssignFromOptions, AssignFromHandler, AssignFromHandlerConstructor } from './types/assign-gingerly/types.js';
 
 // Re-export types for consumers
@@ -49,6 +52,48 @@ export function parseTernaryCommand(key: string): string | null {
     return key.substring(0, key.length - 3); // Remove ' ?=' suffix
 }
 
+/**
+ * Check if a key ends with the sync-op operator ' =&'.
+ */
+export function isSyncOpCommand(key: string): boolean {
+    return key.endsWith(' =&');
+}
+
+/**
+ * Parse a =& sync-op command and extract the LHS path.
+ */
+export function parseSyncOpCommand(key: string): string | null {
+    if (!isSyncOpCommand(key)) return null;
+    return key.substring(0, key.length - 3); // Remove ' =&' suffix
+}
+
+/**
+ * Throws if a resolved sync-op value (or anything nested inside it) is a thenable.
+ *
+ * getValues is synchronous by contract, but `options.protocols` handlers are
+ * typed to allow returning a Promise. A sync op has no await to catch that —
+ * left unchecked it would silently stringify as "[object Promise]" — so this
+ * turns it into a clear error instead.
+ */
+function assertNoThenable(value: any, opName: string, key: string): void {
+    if (value == null) return;
+    if (typeof value.then === 'function') {
+        throw new Error(
+            `assignFrom: sync op '${opName}' (key "${key}") received an async value — ` +
+            `a protocol in options.protocols returned a Promise, which ' =&' cannot await. ` +
+            `Use ' =>' with 'resolve:' instead for async values.`
+        );
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) assertNoThenable(item, opName, key);
+    } else if (typeof value === 'object') {
+        const proto = Object.getPrototypeOf(value);
+        if (proto === Object.prototype || proto === null) {
+            for (const item of Object.values(value)) assertNoThenable(item, opName, key);
+        }
+    }
+}
+
 /**
  * Resolve a single value — if it's a `?.` path string, resolve against source.
  * If it's a protocol string, resolve via protocol. Otherwise pass through as literal.
@@ -354,6 +399,7 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
   const idRefNormalKeys: string[] = [];
   const idRefHandlerKeys: string[] = [];
   const ternaryKeys: string[] = [];
+  const syncOpKeys: string[] = [];
 
   for (const key of Object.keys(expandedPattern)) {
     if (isHandlerCommand(key)) {
@@ -364,6 +410,8 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
       }
     } else if (isTernaryCommand(key)) {
       ternaryKeys.push(key);
+    } else if (isSyncOpCommand(key)) {
+      syncOpKeys.push(key);
     } else if (key.startsWith('#[')) {
       idRefNormalKeys.push(key);
     } else {
@@ -371,7 +419,7 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
     }
   }
 
-  return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys };
+  return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys };
 }
 
 /**
@@ -447,7 +495,7 @@ export function assignFrom(
   const expandedPattern = expandSubstitutions(pattern, options);
 
   // Categorize keys
-  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys } = categorizeKeys(expandedPattern);
+  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys } = categorizeKeys(expandedPattern);
 
   const resolveOptions = { ...options, root: target, permissionProcessor } as any;
 
@@ -469,6 +517,36 @@ export function assignFrom(
     }
   }
 
+  // Process =& sync-op keys (sync — always, no dynamic import, no await, ever)
+  if (syncOpKeys.length > 0) {
+    for (const key of syncOpKeys) {
+      const lhsPath = parseSyncOpCommand(key);
+      if (lhsPath === null) continue;
+      const config = expandedPattern[key];
+      if (!config || typeof config !== 'object' || Array.isArray(config)) {
+        throw new Error(`assignFrom: sync-op command "${key}" requires a config object naming exactly one op`);
+      }
+
+      const opName = Object.keys(config).find(k => k in SYNC_OPS);
+      if (!opName) {
+        throw new Error(`assignFrom: sync-op command "${key}" does not name a known op (${Object.keys(SYNC_OPS).join(', ')})`);
+      }
+
+      const resolvedConfig = getValues(config, options.from, resolveOptions);
+      assertNoThenable(resolvedConfig, opName, key);
+
+      const { [opName]: args, ...extra } = resolvedConfig;
+      const result = SYNC_OPS[opName](args, extra);
+      if (result === undefined) continue;
+
+      const { lhsParent, lhsKey } = resolveLhsPath(target, lhsPath, options);
+      if (lhsParent != null && lhsKey != null
+          && !permissionProcessor?.redirectRestrictedProp(lhsParent, lhsKey, result)) {
+        lhsParent[lhsKey] = result;
+      }
+    }
+  }
+
   // Process normal keys via getValues (sync) + assignGingerly
   if (Object.keys(normalPattern).length > 0) {
     // Resolve #[x] references on RHS values before getValues

package/inferencer/types/NewCustomElementFeature.md

@@ -224,7 +224,7 @@ Create `.vscode/settings.json`:
 }
 ```
 
-## Step 8: Set Up .kiro Directory
+## Step 8: Set Up .kiro Directory Only if kiro is implementing.
 
 Create `.kiro/steering/project-context.md` to reference the shared types documentation:
 
@@ -350,6 +350,8 @@ customElements.assignFeatures(MyElement, {
 
 The parsed attributes (`{ myProp: 'hello', count: 42 }`) are passed as `initVals` to the constructor.
 
+See [withAttrs](https://github.com/bahrus/assign-gingerly/blob/baseline/docs/withAttrs.md) for an in-depth discussion of all the various configuration options.
+
 ### Async Spawn (Lazy Loading)
 
 Feature implementations can be loaded asynchronously:

package/inferencer/types/NewHTMLFirstCustomElement.md

@@ -451,6 +451,8 @@ const raConfig = {
 };
 ```
 
+[Please fully digest all the attribute parsing tha assign-gingerly provides before configuring the attributes.](https://github.com/bahrus/assign-gingerly/blob/baseline/docs/withAttrs.md) 
+
 
 ## Step 8