assign-gingerly 0.0.58 → 0.0.60

package/assignFrom.ts

@@ -1,140 +1,157 @@
 /**
- * Resolve RHS path strings against a source object, then assign the
- * resolved values into a target using assignGingerly.
+ * assignFrom.ts — Synchronous assign-from-source function.
  * 
- * Combines resolveValues + assignGingerly into a single call.
- * Inherits all assignGingerly options (withMethods, aka, signal, etc.).
+ * Resolves RHS path strings synchronously via getValues, then assigns into the target.
+ * Supports looped substitution, #[x] refs, inferredAssignments, and handleSpreads — all sync.
  * 
- * @param target - Object to merge resolved values into
- * @param pattern - Object whose RHS values may contain `?.` path strings
- * @param options - Options including `from` (source object) and any assignGingerly options
- * @returns The target object after merging
+ * For async protocol handlers or awaitable handler execution, use assignFromAsync.
  * 
- * @example
- * const source = { theme: { color: 'red' }, label: 'Hello' };
- * const target = { color: 'blue', text: '' };
- * assignFrom(target, {
- *   color: '?.theme?.color',
- *   text: '?.label'
- * }, { from: source });
- * // target is now { color: 'red', text: 'Hello' }
+ * Handler commands (` =>`) are fire-and-forget (kicked off asynchronously, not awaited).
  */
-import { resolveValues, ResolveValuesOptions } from './resolveValues.js';
+
+import { getValues, getValue } from './getValues.js';
 import assignGingerly, { IAssignGingerlyOptions } from './assignGingerly.js';
+import { resolveIdVariable, parseIdRef } from './resolveIdRef.js';
+import { processInferredAssignments } from './inferredAssignments.js';
 import type { AssignPermissions } from './isAllowedImportPath.js';
 
-export interface AssignFromOptions extends IAssignGingerlyOptions, ResolveValuesOptions {
-  /** Source object to resolve RHS path strings against */
-  from: any;
-
-  /** Loop variable bindings — expand pattern entries containing ${x} */
-  where_x_in?: string[];
-  /** Loop variable bindings — expand pattern entries containing ${y} */
-  where_y_in?: string[];
-  /** Loop variable bindings — expand pattern entries containing ${z} */
-  where_z_in?: string[];
-
-  /**
-   * Cached element references by variable name.
-   * Used with `#[varName]` syntax in LHS keys for fast repeated element access.
-   * 
-   * - String value: existing element ID (uses getElementById)
-   * - Object value: { qry: 'selector' } — finds element via querySelector on target, auto-assigns an ID
-   * 
-   * Elements are cached via WeakRef with getElementById fallback on cache miss.
-   */
-  withIds?: Record<string, string | { qry: string }>;
-
-  /**
-   * Handler implementations scoped to this call.
-   * Key: the `do` name referenced in handler configs.
-   * Value: a class constructor, or an import path to dynamically load one.
-   * 
-   * Import paths must be local (relative, absolute, or bare specifier — no cross-domain URLs).
-   * The module's default export is checked first; otherwise the first exported class
-   * with an `assign` method on its prototype is used.
-   * 
-   * Built-in handlers (builtIns.*) auto-load without needing to be listed here.
-   * 
-   * @example
-   * handlers: {
-   *     'my-list': MyListHandler,                    // class constructor
-   *     'my-chart': './handlers/chart.js',           // dynamic import path
-   *     'vendor-widget': 'some-package/handler.js',  // bare specifier (import map)
-   * }
-   */
-  handlers?: Record<string, AssignFromHandlerConstructor | string>;
-
-  /**
-   * Inferred assignments — automatically distribute source values to matching
-   * DOM elements based on structural conventions (itemprop, name, etc.).
-   * 
-   * Uses the inferencer submodule to determine the correct property for each
-   * matched element (textContent, value, checked, dateTime, ish, etc.).
-   * 
-   * @example
-   * inferredAssignments: {
-   *     byItemprop: ['user', 'name', 'email'],  // or true for all source keys
-   *     beVigilant: true,  // watch for new matching elements (requires signal)
-   * }
-   */
-  inferredAssignments?: {
-    byItemprop?: string[] | true;
-    /** Watch for new matching elements via MutationObserver. Requires options.signal for cleanup. */
-    beVigilant?: boolean;
-  };
-
-  /**
-   * Bulk enhancement application via EMC JSON configs.
-   * Finds matching elements and spawns enhancements on them.
-   * 
-   * Each entry specifies an EMC JSON path and optionally overrides the matching selector.
-   * Enhancements are auto-registered if not already present in the enhancement registry.
-   * 
-   * No scope perimeter is applied — use mount-observer for reactive/scoped enhancement.
-   * 
-   * @example
-   * enhance: [
-   *     { emc: 'be-bound/emc.json', matching: '[name]' },
-   *     { emc: 'be-observant/emc.json', matching: '[itemprop]' },
-   * ]
-   */
-  enhance?: Array<{ emc: string; matching?: string; parse?: boolean }>;
+// Re-export types and interfaces for consumers
+export type { AssignFromOptions, AssignFromHandler, AssignFromHandlerConstructor } from './assignFromAsync.js';
+import type { AssignFromOptions } from './assignFromAsync.js';
+
+/**
+ * Supported substitution variables and their option keys.
+ */
+export const SUBSTITUTION_VARS = [
+  { placeholder: '${x}', optionKey: 'where_x_in' },
+  { placeholder: '${y}', optionKey: 'where_y_in' },
+  { placeholder: '${z}', optionKey: 'where_z_in' },
+] as const;
+
+/**
+ * Check if a key ends with the handler operator ' =>'.
+ */
+export function isHandlerCommand(key: string): boolean {
+    return key.endsWith(' =>');
 }
 
 /**
- * Interface for assignFrom handler classes.
- * Handlers are invoked when a LHS key ends with ' =>'.
+ * Check if a key ends with the ternary operator ' ?='.
  */
-export interface AssignFromHandler {
-    assign(lhsTarget: any, resolvedParams: Record<string, any>, options: AssignFromOptions): Promise<void> | void;
+export function isTernaryCommand(key: string): boolean {
+    return key.endsWith(' ?=');
 }
 
-export interface AssignFromHandlerConstructor {
-    new (config: any): AssignFromHandler;
+/**
+ * Parse a ?= ternary command and extract the LHS path.
+ */
+export function parseTernaryCommand(key: string): string | null {
+    if (!isTernaryCommand(key)) return null;
+    return key.substring(0, key.length - 3); // Remove ' ?=' suffix
 }
 
 /**
- * Check if a key ends with the handler operator ' =>'.
+ * 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.
  */
-function isHandlerCommand(key: string): boolean {
-    return key.endsWith(' =>');
+function resolveTernaryValue(value: any, source: any, options: AssignFromOptions): any {
+    if (typeof value === 'string' && value.startsWith('?.')) {
+        return getValue(value, source, {
+            withMethods: options.withMethods,
+            aka: options.aka,
+            protocols: options.protocols
+        });
+    }
+    if (typeof value === 'string' && value.includes('://') && options.protocols) {
+        // Check if it matches a known protocol
+        const protoEnd = value.indexOf('://');
+        const protocol = value.substring(0, protoEnd);
+        if (options.protocols[protocol]) {
+            return getValue(value, source, {
+                withMethods: options.withMethods,
+                aka: options.aka,
+                protocols: options.protocols
+            });
+        }
+    }
+    return value;
 }
 
 /**
- * Supported substitution variables and their option keys.
+ * Evaluate a ?= ternary expression.
+ * 
+ * Supported forms:
+ * - [ifTruthy, thenResult]                         — guard (skip if falsy)
+ * - [ifTruthy, thenResult, elseResult]             — ternary
+ * - [ifTrue, trueResult, falseResult, neither]     — three-state (true/false/nullish)
+ * - [[lhs, rhs], ifEqual, ifNotEqual?]             — equality comparison
+ * - [[lhs, rhs], ifEqual]                          — equality guard
+ * 
+ * Returns undefined to signal "skip assignment" (guard forms when condition not met).
  */
-const SUBSTITUTION_VARS = [
-  { placeholder: '${x}', optionKey: 'where_x_in' },
-  { placeholder: '${y}', optionKey: 'where_y_in' },
-  { placeholder: '${z}', optionKey: 'where_z_in' },
-] as const;
+const TERNARY_SKIP = Symbol('ternary-skip');
+
+function evaluateTernary(arr: any[], source: any, options: AssignFromOptions): any {
+    const condition = arr[0];
+
+    if (Array.isArray(condition)) {
+        // Comparison mode: [[lhs, rhs], ...] or [[lhs, op, rhs], ...]
+        const lhs = resolveTernaryValue(condition[0], source, options);
+        if (condition.length === 2) {
+            // Equality: [[lhs, rhs], result, elseResult?]
+            const rhs = resolveTernaryValue(condition[1], source, options);
+            if (lhs === rhs) {
+                return resolveTernaryValue(arr[1], source, options);
+            } else {
+                return arr.length > 2 ? resolveTernaryValue(arr[2], source, options) : TERNARY_SKIP;
+            }
+        } else {
+            // Operator: [[lhs, op, rhs], result, elseResult?]
+            const op = condition[1] as string;
+            const rhs = resolveTernaryValue(condition[2], source, options);
+            const satisfied = compareWithOp(lhs, op, rhs);
+            if (satisfied) {
+                return resolveTernaryValue(arr[1], source, options);
+            } else {
+                return arr.length > 2 ? resolveTernaryValue(arr[2], source, options) : TERNARY_SKIP;
+            }
+        }
+    } else {
+        // Truthiness mode
+        const resolved = resolveTernaryValue(condition, source, options);
+        if (arr.length === 4) {
+            // [ifTrue, trueResult, falseResult, neitherResult]
+            if (resolved == null) return resolveTernaryValue(arr[3], source, options);
+            return resolved ? resolveTernaryValue(arr[1], source, options) : resolveTernaryValue(arr[2], source, options);
+        } else if (arr.length === 3) {
+            // [ifTruthy, thenResult, elseResult]
+            return resolved ? resolveTernaryValue(arr[1], source, options) : resolveTernaryValue(arr[2], source, options);
+        } else {
+            // [ifTruthy, thenResult] — guard, skip if falsy
+            return resolved ? resolveTernaryValue(arr[1], source, options) : TERNARY_SKIP;
+        }
+    }
+}
+
+/**
+ * Compare two values with a given operator.
+ */
+function compareWithOp(lhs: any, op: string, rhs: any): boolean {
+    switch (op) {
+        case '===': return lhs === rhs;
+        case '!==': return lhs !== rhs;
+        case '>': return lhs > rhs;
+        case '>=': return lhs >= rhs;
+        case '<': return lhs < rhs;
+        case '<=': return lhs <= rhs;
+        default: return lhs === rhs; // fallback to equality
+    }
+}
 
 /**
  * Recursively substitute a placeholder in all string values of an object.
- * Returns a new object (shallow clone at each level) with substitutions applied.
  */
-function substituteInValue(value: any, placeholder: string, replacement: string): any {
+export function substituteInValue(value: any, placeholder: string, replacement: string): any {
   if (typeof value === 'string') {
     return value.includes(placeholder) ? value.replaceAll(placeholder, replacement) : value;
   }
@@ -157,7 +174,7 @@ function substituteInValue(value: any, placeholder: string, replacement: string)
 /**
  * Check if a pattern entry (key + value) contains a given placeholder.
  */
-function entryContainsPlaceholder(key: string, value: any, placeholder: string): boolean {
+export function entryContainsPlaceholder(key: string, value: any, placeholder: string): boolean {
   if (key.includes(placeholder)) return true;
   return valueContainsPlaceholder(value, placeholder);
 }
@@ -165,7 +182,7 @@ function entryContainsPlaceholder(key: string, value: any, placeholder: string):
 /**
  * Check if a value (string, object, or array) contains a placeholder.
  */
-function valueContainsPlaceholder(value: any, placeholder: string): boolean {
+export function valueContainsPlaceholder(value: any, placeholder: string): boolean {
   if (typeof value === 'string') return value.includes(placeholder);
   if (Array.isArray(value)) return value.some(item => valueContainsPlaceholder(item, placeholder));
   if (value && typeof value === 'object') {
@@ -179,12 +196,8 @@ function valueContainsPlaceholder(value: any, placeholder: string): boolean {
 
 /**
  * Expand looped substitution variables in a pattern.
- * Applies cartesian expansion: x values are expanded first, then y, then z.
- * Each variable multiplies the entries — result count = x.length × y.length × z.length.
- *
- * Returns the expanded pattern (or the original if no substitutions apply).
  */
-function expandSubstitutions(
+export function expandSubstitutions(
   pattern: Record<string, any>,
   options: AssignFromOptions
 ): Record<string, any> {
@@ -197,7 +210,6 @@ function expandSubstitutions(
     const expanded: [string, any][] = [];
     for (const [key, value] of entries) {
       if (entryContainsPlaceholder(key, value, placeholder)) {
-        // Expand this entry for each value in the variable array
         for (const replacement of values) {
           const newKey = key.includes(placeholder)
             ? key.replaceAll(placeholder, replacement)
@@ -206,7 +218,6 @@ function expandSubstitutions(
           expanded.push([newKey, newValue]);
         }
       } else {
-        // No placeholder in this entry — pass through
         expanded.push([key, value]);
       }
     }
@@ -218,14 +229,11 @@ function expandSubstitutions(
 
 /**
  * Convert entries to an object, merging duplicate handler (` =>`) keys into arrays.
- * For normal (non-handler) keys, later entries overwrite earlier ones (standard object behavior).
- * For handler keys, duplicate entries are combined into an array (Multiple Handlers pattern).
  */
-function mergeHandlerDuplicates(entries: [string, any][]): Record<string, any> {
+export function mergeHandlerDuplicates(entries: [string, any][]): Record<string, any> {
   const result: Record<string, any> = {};
   for (const [key, value] of entries) {
     if (key.endsWith(' =>') && key in result) {
-      // Duplicate handler key — merge into array
       const existing = result[key];
       if (Array.isArray(existing)) {
         existing.push(value);
@@ -239,20 +247,37 @@ function mergeHandlerDuplicates(entries: [string, any][]): Record<string, any> {
   return result;
 }
 
-export async function assignFrom(
-  target: any,
-  pattern: Record<string, any>,
-  options: AssignFromOptions,
-  permissions?: AssignPermissions
-): Promise<any> {
-  // First: expand looped substitution variables (${x}, ${y}, ${z})
-  const expandedPattern = expandSubstitutions(pattern, options);
+/**
+ * Recursively walk an object and handle "..." spread keys.
+ */
+export function handleSpreads(obj: Record<string, any>): Record<string, any> {
+  for (const [key, value] of Object.entries(obj)) {
+    if (key !== '...' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      const proto = Object.getPrototypeOf(value);
+      if (proto === Object.prototype || proto === null) {
+        obj[key] = handleSpreads(value);
+      }
+    }
+  }
+  if ('...' in obj) {
+    const spreadValue = obj['...'];
+    delete obj['...'];
+    if (spreadValue && typeof spreadValue === 'object') {
+      Object.assign(obj, spreadValue);
+    }
+  }
+  return obj;
+}
 
-  // Separate handler commands ( =>), #[x] keys, and normal keys
+/**
+ * Categorize pattern keys into handler keys, #[x] keys, and normal keys.
+ */
+export function categorizeKeys(expandedPattern: Record<string, any>) {
   const handlerKeys: string[] = [];
   const normalPattern: Record<string, any> = {};
   const idRefNormalKeys: string[] = [];
   const idRefHandlerKeys: string[] = [];
+  const ternaryKeys: string[] = [];
 
   for (const key of Object.keys(expandedPattern)) {
     if (isHandlerCommand(key)) {
@@ -261,6 +286,8 @@ export async function assignFrom(
       } else {
         handlerKeys.push(key);
       }
+    } else if (isTernaryCommand(key)) {
+      ternaryKeys.push(key);
     } else if (key.startsWith('#[')) {
       idRefNormalKeys.push(key);
     } else {
@@ -268,131 +295,190 @@ export async function assignFrom(
     }
   }
 
-  // Process normal keys via resolveValues + assignGingerly
+  return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys };
+}
+
+/**
+ * Merge withIds and at into a single lookup map for resolveIdVariable.
+ */
+function getEffectiveIds(options: AssignFromOptions): Record<string, any> | undefined {
+  if (!options.withIds && !options.at) return undefined;
+  if (options.withIds && !options.at) return options.withIds;
+  if (!options.withIds && options.at) return options.at;
+  return { ...options.withIds, ...options.at };
+}
+
+/**
+ * Process #[x] normal keys synchronously.
+ */
+function processIdRefNormalKeys(
+  idRefNormalKeys: string[],
+  expandedPattern: Record<string, any>,
+  target: any,
+  options: AssignFromOptions
+): void {
+  const ids = getEffectiveIds(options);
+  if (!ids) return;
+
+  for (const key of idRefNormalKeys) {
+    const parsed = parseIdRef(key);
+    if (!parsed) continue;
+
+    const el = resolveIdVariable(parsed.varName, target, ids);
+    if (!el) continue;
+
+    const value = expandedPattern[key];
+    if (parsed.remainingPath) {
+      const resolvedValue = getValues(
+        { __v: value }, options.from,
+        { withMethods: options.withMethods, aka: options.aka, protocols: options.protocols }
+      );
+      assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options);
+    } else {
+      const resolvedValue = getValues(
+        typeof value === 'object' && value !== null ? value : { __v: value },
+        options.from,
+        { withMethods: options.withMethods, aka: options.aka, protocols: options.protocols }
+      );
+      if (!('__v' in resolvedValue)) {
+        assignGingerly(el, resolvedValue, options);
+      }
+    }
+  }
+}
+
+/**
+ * Synchronous assignFrom — resolves values, assigns to target, all without awaiting.
+ * 
+ * Handler commands (` =>`), beVigilant, and enhance are fire-and-forget (async, non-blocking).
+ * For awaitable handler execution, use assignFromAsync.
+ * 
+ * @param target - Object to merge resolved values into
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param options - Options including `from` (source object)
+ * @param permissions - Optional security permissions
+ * @returns The target object after merging
+ */
+export function assignFrom(
+  target: any,
+  pattern: Record<string, any>,
+  options: AssignFromOptions,
+  permissions?: AssignPermissions
+): any {
+  // Expand looped substitution variables
+  const expandedPattern = expandSubstitutions(pattern, options);
+
+  // Categorize keys
+  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys } = categorizeKeys(expandedPattern);
+
+  // Process ?= ternary keys (sync)
+  if (ternaryKeys.length > 0) {
+    const ternaryResolved: Record<string, any> = {};
+    for (const key of ternaryKeys) {
+      const lhsPath = parseTernaryCommand(key);
+      if (!lhsPath) continue;
+      const arr = expandedPattern[key];
+      if (!Array.isArray(arr) || arr.length < 2) continue;
+      const result = evaluateTernary(arr, options.from, options);
+      if (result !== TERNARY_SKIP) {
+        ternaryResolved[lhsPath] = result;
+      }
+    }
+    if (Object.keys(ternaryResolved).length > 0) {
+      assignGingerly(target, ternaryResolved, options);
+    }
+  }
+
+  // Process normal keys via getValues (sync) + assignGingerly
   if (Object.keys(normalPattern).length > 0) {
-    const resolved = await resolveValues(normalPattern, options.from, {
+    // Resolve #[x] references on RHS values before getValues
+    if (options.withIds || options.at) {
+      const ids = getEffectiveIds(options)!;
+      for (const key of Object.keys(normalPattern)) {
+        const value = normalPattern[key];
+        if (typeof value === 'string' && value.startsWith('#[')) {
+          const closeIdx = value.indexOf(']');
+          if (closeIdx !== -1) {
+            const varName = value.substring(2, closeIdx);
+            const el = resolveIdVariable(varName, target, ids);
+            if (el) {
+              const remainingPath = value.substring(closeIdx + 1);
+              if (remainingPath) {
+                normalPattern[key] = getValue(remainingPath, el, {
+                  withMethods: options.withMethods,
+                  aka: options.aka,
+                  protocols: options.protocols
+                });
+              } else {
+                normalPattern[key] = el.id; // bare #[x] → ID string
+              }
+            }
+          }
+        }
+      }
+    }
+
+    const resolved = getValues(normalPattern, options.from, {
       withMethods: options.withMethods,
       aka: options.aka,
       protocols: options.protocols
     });
 
-    // Recursively handle "..." spread keys at all nesting levels
     handleSpreads(resolved);
-
     assignGingerly(target, resolved, options);
   }
 
-  // Process #[x] normal keys — resolve element, then apply remaining path + value
-  if (idRefNormalKeys.length > 0 && options.withIds) {
-    const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
-    for (const key of idRefNormalKeys) {
-      const parsed = parseIdRef(key);
-      if (!parsed) continue;
-
-      const el = resolveIdVariable(parsed.varName, target, options.withIds);
-      if (!el) continue;
-
-      const value = expandedPattern[key];
-      if (parsed.remainingPath) {
-        // Resolve the RHS value
-        const resolvedValue = await resolveValues(
-          { __v: value }, options.from,
-          { withMethods: options.withMethods, aka: options.aka, protocols: options.protocols }
-        );
-        // Apply remaining path on the resolved element
-        assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options);
-      } else {
-        // No remaining path — resolve and assign directly to the element
-        const resolvedValue = await resolveValues(
-          typeof value === 'object' && value !== null ? value : { __v: value },
-          options.from,
-          { withMethods: options.withMethods, aka: options.aka, protocols: options.protocols }
-        );
-        if ('__v' in resolvedValue) {
-          // Single value — can't assign to element root without a path
-        } else {
-          assignGingerly(el, resolvedValue, options);
-        }
-      }
-    }
+  // Process #[x] normal keys (sync)
+  if (idRefNormalKeys.length > 0) {
+    processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, options);
   }
 
-  // Process handler commands ( =>) — dynamically imported only when needed
+  // Process handler commands — fire-and-forget (async)
   if (handlerKeys.length > 0) {
-    const { processHandlerCommands } = await import('./processHandlerCommands.js');
-    await processHandlerCommands(target, handlerKeys, expandedPattern, options, permissions);
+    import('./processHandlerCommands.js').then(({ processHandlerCommands }) => {
+      processHandlerCommands(target, handlerKeys, expandedPattern, options, permissions);
+    });
   }
 
-  // Process #[x] handler keys — resolve element, then pass to handler processing
-  if (idRefHandlerKeys.length > 0 && options.withIds) {
-    const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
-    const { processHandlerCommands } = await import('./processHandlerCommands.js');
-
-    for (const key of idRefHandlerKeys) {
-      const parsed = parseIdRef(key);
-      if (!parsed) continue;
-
-      const el = resolveIdVariable(parsed.varName, target, options.withIds);
-      if (!el) continue;
-
-      // Build a synthetic key for processHandlerCommands:
-      // The resolved element becomes the target, remaining path is the LHS
-      const syntheticKey = parsed.remainingPath
-        ? `${parsed.remainingPath} =>`
-        : ' =>';
-
-      const syntheticPattern: Record<string, any> = {
-        [syntheticKey]: expandedPattern[key]
-      };
-
-      await processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissions);
-    }
+  // Process #[x] handler keys — fire-and-forget (async)
+  if (idRefHandlerKeys.length > 0 && (options.withIds || options.at)) {
+    const ids = getEffectiveIds(options)!;
+    import('./processHandlerCommands.js').then(({ processHandlerCommands }) => {
+      for (const key of idRefHandlerKeys) {
+        const parsed = parseIdRef(key);
+        if (!parsed) continue;
+        const el = resolveIdVariable(parsed.varName, target, ids);
+        if (!el) continue;
+        const syntheticKey = parsed.remainingPath ? `${parsed.remainingPath} =>` : ' =>';
+        const syntheticPattern = { [syntheticKey]: expandedPattern[key] };
+        processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissions);
+      }
+    });
   }
 
-  // Process inferred assignments — dynamically imported only when option is present
-  if (options.inferredAssignments) {
-    const { processInferredAssignments } = await import('./inferredAssignments.js');
-    await processInferredAssignments(target, options.from, options.inferredAssignments);
+  // Process inferred assignments (sync)
+  if (options.infer) {
+    processInferredAssignments(target, options.from, options.infer);
 
-    // Set up MutationObserver for new matching elements if beVigilant
-    if (options.inferredAssignments.beVigilant) {
+    // beVigilant — fire-and-forget (async)
+    if (options.infer.beVigilant) {
       if (!options.signal) {
-        throw new Error('assignFrom: inferredAssignments.beVigilant requires options.signal (AbortSignal) for cleanup');
+        throw new Error('assignFrom: infer.beVigilant requires options.signal (AbortSignal) for cleanup');
       }
-      const { setupVigilantObserver } = await import('./beVigilant.js');
-      setupVigilantObserver(target, options.from, options.inferredAssignments, options.signal);
+      import('./beVigilant.js').then(({ setupVigilantObserver }) => {
+        setupVigilantObserver(target, options.from, options.infer!, options.signal!);
+      });
     }
   }
 
-  // Process bulk enhancements — dynamically imported only when option is present
+  // Process bulk enhancements — fire-and-forget (async)
   if (options.enhance && options.enhance.length > 0) {
-    const { enhanceAll } = await import('./enhanceAll.js');
-    await enhanceAll(target, options.enhance, permissions);
+    import('./enhanceAll.js').then(({ enhanceAll }) => {
+      enhanceAll(target, options.enhance!, permissions);
+    });
   }
 
   return target;
 }
 
-/**
- * Recursively walk an object and handle "..." spread keys.
- * When a "..." key is found, its value (which should be an object after protocol resolution)
- * is spread into the parent, replacing the "..." entry.
- */
-function handleSpreads(obj: Record<string, any>): Record<string, any> {
-  for (const [key, value] of Object.entries(obj)) {
-    if (key !== '...' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
-      const proto = Object.getPrototypeOf(value);
-      if (proto === Object.prototype || proto === null) {
-        obj[key] = handleSpreads(value);
-      }
-    }
-  }
-  if ('...' in obj) {
-    const spreadValue = obj['...'];
-    delete obj['...'];
-    if (spreadValue && typeof spreadValue === 'object') {
-      Object.assign(obj, spreadValue);
-    }
-  }
-  return obj;
-}
+export default assignFrom;