assign-gingerly 0.0.57 → 0.0.59

package/assignFrom.ts

@@ -1,140 +1,44 @@
 /**
- * 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';
 
 /**
- * Interface for assignFrom handler classes.
- * Handlers are invoked when a LHS key ends with ' =>'.
+ * Supported substitution variables and their option keys.
  */
-export interface AssignFromHandler {
-    assign(lhsTarget: any, resolvedParams: Record<string, any>, options: AssignFromOptions): Promise<void> | void;
-}
-
-export interface AssignFromHandlerConstructor {
-    new (config: any): AssignFromHandler;
-}
+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 ' =>'.
  */
-function isHandlerCommand(key: string): boolean {
+export function isHandlerCommand(key: string): boolean {
     return key.endsWith(' =>');
 }
 
-/**
- * Supported substitution variables and their option keys.
- */
-const SUBSTITUTION_VARS = [
-  { placeholder: '${x}', optionKey: 'where_x_in' },
-  { placeholder: '${y}', optionKey: 'where_y_in' },
-  { placeholder: '${z}', optionKey: 'where_z_in' },
-] as const;
-
 /**
  * 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 +61,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 +69,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 +83,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 +97,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 +105,6 @@ function expandSubstitutions(
           expanded.push([newKey, newValue]);
         }
       } else {
-        // No placeholder in this entry — pass through
         expanded.push([key, value]);
       }
     }
@@ -218,14 +116,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,16 +134,32 @@ 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[] = [];
@@ -268,131 +179,133 @@ export async function assignFrom(
     }
   }
 
-  // Process normal keys via resolveValues + assignGingerly
+  return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys };
+}
+
+/**
+ * Process #[x] normal keys synchronously.
+ */
+function processIdRefNormalKeys(
+  idRefNormalKeys: string[],
+  expandedPattern: Record<string, any>,
+  target: any,
+  options: AssignFromOptions
+): void {
+  if (!options.withIds) return;
+
+  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) {
+      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 } = categorizeKeys(expandedPattern);
+
+  // Process normal keys via getValues (sync) + assignGingerly
   if (Object.keys(normalPattern).length > 0) {
-    const resolved = await resolveValues(normalPattern, options.from, {
+    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
+  // Process #[x] handler keys — fire-and-forget (async)
   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);
-    }
+    import('./processHandlerCommands.js').then(({ processHandlerCommands }) => {
+      for (const key of idRefHandlerKeys) {
+        const parsed = parseIdRef(key);
+        if (!parsed) continue;
+        const el = resolveIdVariable(parsed.varName, target, options.withIds!);
+        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
+  // Process inferred assignments (sync)
   if (options.inferredAssignments) {
-    const { processInferredAssignments } = await import('./inferredAssignments.js');
-    await processInferredAssignments(target, options.from, options.inferredAssignments);
+    processInferredAssignments(target, options.from, options.inferredAssignments);
 
-    // Set up MutationObserver for new matching elements if beVigilant
+    // beVigilant — fire-and-forget (async)
     if (options.inferredAssignments.beVigilant) {
       if (!options.signal) {
         throw new Error('assignFrom: inferredAssignments.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.inferredAssignments!, 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;

package/assignFromAsync.js

@@ -0,0 +1,118 @@
+/**
+ * Resolve RHS path strings against a source object, then assign the
+ * resolved values into a target using assignGingerly.
+ *
+ * Combines resolveValues + assignGingerly into a single call.
+ * Inherits all assignGingerly options (withMethods, aka, signal, etc.).
+ *
+ * @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
+ *
+ * @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' }
+ */
+import { resolveValues } from './resolveValues.js';
+import assignGingerly from './assignGingerly.js';
+import { expandSubstitutions, categorizeKeys, handleSpreads } from './assignFrom.js';
+// Module cache for processHandlerCommands — avoids await on dynamic import after first call
+let _processHandlerCommands;
+export async function assignFromAsync(target, pattern, options, permissions) {
+    // First: expand looped substitution variables (${x}, ${y}, ${z})
+    const expandedPattern = expandSubstitutions(pattern, options);
+    // Categorize keys
+    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys } = categorizeKeys(expandedPattern);
+    // Process normal keys via resolveValues + assignGingerly
+    if (Object.keys(normalPattern).length > 0) {
+        const resolved = await resolveValues(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 handler commands ( =>) — cached after first load to avoid await overhead
+    if (handlerKeys.length > 0) {
+        _processHandlerCommands ??= (await import('./processHandlerCommands.js')).processHandlerCommands;
+        await _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');
+        _processHandlerCommands ??= (await import('./processHandlerCommands.js')).processHandlerCommands;
+        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 = {
+                [syntheticKey]: expandedPattern[key]
+            };
+            await _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);
+        // Set up MutationObserver for new matching elements if beVigilant
+        if (options.inferredAssignments.beVigilant) {
+            if (!options.signal) {
+                throw new Error('assignFrom: inferredAssignments.beVigilant requires options.signal (AbortSignal) for cleanup');
+            }
+            const { setupVigilantObserver } = await import('./beVigilant.js');
+            setupVigilantObserver(target, options.from, options.inferredAssignments, options.signal);
+        }
+    }
+    // Process bulk enhancements — dynamically imported only when option is present
+    if (options.enhance && options.enhance.length > 0) {
+        const { enhanceAll } = await import('./enhanceAll.js');
+        await enhanceAll(target, options.enhance, permissions);
+    }
+    return target;
+}