assign-gingerly 0.0.63 → 0.0.65

package/inferencer/types/assign-gingerly/types.d.ts

@@ -261,6 +261,149 @@ export interface IAssignGingerlyOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * Options for assignTentatively — reversible assignment with change tracking.
+ * 
+ * Supports a subset of assignGingerly's path features (nested paths, +=, =!, -=)
+ * with the addition of reversal tracking.
+ */
+export interface IAssignTentativelyOptions {
+  /**
+   * Object to accumulate reversal entries into.
+   * If omitted, a new object is created internally.
+   * Pass an existing object to accumulate reversals across multiple calls.
+   * 
+   * The reversal object can be passed to assignGingerly to undo all changes:
+   * @example
+   * const reversal = {};
+   * assignTentatively(obj, { name: 'Bob' }, { reversal });
+   * // Later:
+   * assignGingerly(obj, reversal); // restores name to original value
+   */
+  reversal?: Record<string | symbol, any>;
+
+  /**
+   * Alias mappings for property and method names.
+   * Same semantics as IAssignGingerlyOptions.aka — substituted before path evaluation.
+   */
+  aka?: Record<string, string>;
+}
+
+/**
+ * Options for assignFrom / assignFromAsync.
+ */
+export interface AssignFromOptions {
+  /** Source object to resolve RHS path strings against */
+  from: any;
+
+  /** Protocol handlers (sync or async) */
+  protocols?: Record<string, (key: string) => any | Promise<any>>;
+
+  /** Method names to call during path evaluation */
+  withMethods?: string[] | Set<string>;
+
+  /** Alias mappings for path segments */
+  aka?: Record<string, string>;
+
+  /** AbortSignal for cleanup */
+  signal?: AbortSignal;
+
+  /** 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[];
+
+  /**
+   * Pin 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
+   * - Object value: { path: [...], expect?, fallback? } — child index path + auto-ID + optional validation
+   */
+  pin?: Record<string, string | { qry: string } | { path: number[]; expect?: string; fallback?: boolean }>;
+
+  /**
+   * Positional element references for use with `#[varName]` syntax.
+   * Resolves elements by child index path — no IDs assigned, no caching.
+   */
+  at?: Record<string, number[] | { path: number[]; expect?: string; fallback?: boolean }>;
+
+  /**
+   * Handler implementations scoped to this call.
+   * Key: the `do` name referenced in handler configs.
+   * Value: a class constructor, an import path, or a builtIns.* alias string.
+   */
+  handlers?: Record<string, AssignFromHandlerConstructor | string>;
+
+  /**
+   * Inferred assignments — automatically distribute source values to matching
+   * DOM elements based on structural conventions (itemprop, name, etc.).
+   */
+  infer?: {
+    byItemprop?: string[] | true;
+    '|'?: string[] | true;
+    byName?: string[] | true | { props: string[] | true; outside: string };
+    '@'?: string[] | true | { props: string[] | true; outside: string };
+    beVigilant?: boolean;
+  };
+
+  /**
+   * Bulk enhancement application via EMC JSON configs.
+   */
+  enhance?: Array<{ emc: string; matching?: string; parse?: boolean }>;
+
+  /** Registry for enhancement dependency injection (inherited from IAssignGingerlyOptions) */
+  registry?: any;
+
+  [key: string]: any;
+}
+
+/**
+ * Options for synchronous value resolution (getValues / getValue).
+ * Extends IAssignGingerlyOptions with synchronous protocol handlers.
+ */
+export interface GetValuesOptions extends IAssignGingerlyOptions {
+  /**
+   * Internal root object for special $0 references.
+   * This is used by assignFrom to resolve values relative to the target object.
+   */
+  root?: any;
+
+  /**
+   * Synchronous protocol handlers for resolving protocol-prefixed values.
+   * Each handler receives the key portion and MUST return synchronously.
+   * For async protocols, use ResolveValuesOptions / resolveValues instead.
+   * 
+   * @example
+   * protocols: {
+   *     globalThis: (key) => globalThis[key],
+   *     localStorage: (key) => JSON.parse(localStorage.getItem(key) || 'null')
+   * }
+   */
+  protocols?: Record<string, (key: string) => any>;
+}
+
+/**
+ * Options for async value resolution (resolveValues).
+ * Same as GetValuesOptions but protocol handlers may return Promises.
+ */
+export interface ResolveValuesOptions extends IAssignGingerlyOptions {
+  /**
+   * Internal root object for special $0 references.
+   * This is used by assignFrom to resolve values relative to the target object.
+   */
+  root?: any;
+
+  /**
+   * Protocol handlers for resolving protocol-prefixed values (e.g., 'globalThis://key').
+   * Each handler receives the key portion and returns the resolved value (sync or async).
+   */
+  protocols?: Record<string, (key: string) => any | Promise<any>>;
+}
+
 /**
  * Event dispatched when enhancement configs are registered
  */
@@ -538,15 +681,140 @@ export interface LazyLoadConfig extends HandlerConfig {
         if: string;
         /** Template element to clone (resolved via protocol or path) */
         instantiate: string;
-        /** Insert method: 'appendChild' (default) or 'prepend' */
+        /** Insert method: 'appendChild' (default), 'prepend', or 'after' (sibling after target) */
         method?: string;
         /** If true, removes nodes when hiding instead of adding hidden attribute */
         forget?: boolean | string;
+        /** Enable view transitions */
+        transitional?: boolean | string;
+        /** CSS class for hiding (default: 'ag-hide', only used when transitional: true) */
+        hideClass?: string;
+        /** Custom CSS for the hide class (default: 'display: none') */
+        hideCss?: string;
         /** Optional async callback invoked after cloning, resolved from the VM */
         onInstantiated?: string;
+        /** Override auto-derived marker name */
+        markerName?: string;
+        /** Set inert attribute on hidden elements */
+        toggleInert?: boolean | string;
+        /** Set disabled property on hidden form elements */
+        toggleDisabled?: boolean | string;
     };
 }
 
+/**
+ * Resolved parameters received by LazyLoadHandler.assign() after resolveValues processing.
+ */
+export interface LazyLoadResolvedParams {
+    /** Condition — resolved to actual truthy/falsy value */
+    if: any;
+    /** Template element — resolved to HTMLTemplateElement or DocumentFragment */
+    instantiate: HTMLTemplateElement | DocumentFragment;
+    /** Insertion method (default: 'appendChild') */
+    method?: 'appendChild' | 'prepend' | 'after';
+    /** Remove nodes on hide instead of using hidden attribute */
+    forget?: boolean;
+    /** Enable view transitions */
+    transitional?: boolean;
+    /** CSS class for hiding (default: 'ag-hide', only used when transitional: true) */
+    hideClass?: string;
+    /** Custom CSS for the hide class (default: 'display: none') */
+    hideCss?: string;
+    /** Callback after clone+insert */
+    onInstantiated?: (ctx: LazyLoadInstantiatedContext) => void | Promise<void>;
+    /** Override auto-derived marker name */
+    markerName?: string;
+    /** Set inert attribute on hidden elements (removes from a11y tree + interaction) */
+    toggleInert?: boolean;
+    /** Set disabled property on hidden form elements */
+    toggleDisabled?: boolean;
+    /** Name of a pre-existing marker pair whose content should be removed on first activation.
+     *  Used for SSR placeholder content (e.g., "Loading..." text) that disappears once real content loads. */
+    placeholder?: string;
+    /** Assignment config applied to cloned content before insertion.
+     *  Same shape as manageTemplateList's fromEachItem: { assignToFragment, withOptions } or { configs: [...] } */
+    assign?: {
+        assignToFragment?: Record<string, any>;
+        withOptions?: Record<string, any>;
+        configs?: Array<{ assignToFragment?: Record<string, any>; withOptions?: Record<string, any> }>;
+    };
+}
+
+/**
+ * Configuration for the builtIns.lazyLoadSwitch handler.
+ */
+export interface LazyLoadSwitchConfig extends HandlerConfig {
+    do: 'builtIns.lazyLoadSwitch';
+    resolve: {
+        /** Left-hand side of comparison (resolved from VM) */
+        lhs: string;
+        /** Comparison operator (default: '===') */
+        op?: '===' | '!==' | '==' | '!=' | '<' | '>' | '<=' | '>=';
+        /** Right-hand side of comparison (resolved from VM or literal) */
+        rhs: string;
+        /** Template element to clone (resolved via protocol or path) */
+        instantiate: string;
+        /** Insert method: 'appendChild' (default), 'prepend', or 'after' */
+        method?: string;
+        /** If true, removes nodes when hiding instead of adding hidden attribute */
+        forget?: boolean | string;
+        /** Enable view transitions */
+        transitional?: boolean | string;
+        /** CSS class for hiding (default: 'ag-hide', only used when transitional: true) */
+        hideClass?: string;
+        /** Custom CSS for the hide class (default: 'display: none') */
+        hideCss?: string;
+        /** Optional async callback invoked after cloning, resolved from the VM */
+        onInstantiated?: string;
+    };
+}
+
+/**
+ * Resolved parameters received by LazyLoadSwitchHandler.assign() after resolveValues processing.
+ */
+export interface LazyLoadSwitchResolvedParams extends Omit<LazyLoadResolvedParams, 'if'> {
+    /** Left-hand side — resolved to actual value */
+    lhs: any;
+    /** Comparison operator (default: '===') */
+    op?: '===' | '!==' | '==' | '!=' | '<' | '>' | '<=' | '>=';
+    /** Right-hand side — resolved to actual value */
+    rhs: any;
+}
+
+export interface FromEachItemConfig {
+    assignToFragment?: Record<string, any>;
+    withOptions?: AssignFromOptions;
+    resolve?: {
+      key?: string;
+    }
+}
+
+export interface ManageTemplateListConfig extends HandlerConfig {
+    do: 'builtIns.manageTemplateList';
+    resolve: ManageTemplateListResolvedParams;
+    fromEachItem: FromEachItemConfig;
+}
+
+/**
+ * Resolved parameters received by ManageTemplateListHandler.assign().
+ */
+export interface ManageTemplateListResolvedParams {
+    /** The iterable to loop over (resolved from VM) */
+    forEach: Iterable<any>;
+    /** Template element to clone per item */
+    instantiate: HTMLTemplateElement | DocumentFragment;
+    /** Insertion method (default: 'appendChild') */
+    method?: 'appendChild' | 'prepend' | 'after';
+    /** Remove nodes on hide instead of using hidden attribute */
+    forget?: boolean;
+    /** Override auto-derived marker name */
+    markerName?: string;
+    /** Wait for async rendering before DOM commit */
+    waitForSettled?: boolean | { idleMs?: number; timeout?: number };
+    /** Yield to browser every N items to prevent jank (default: undefined = no yielding) */
+    yieldEvery?: number;
+}
+
 /**
  * Context passed to onInstantiated callbacks after template cloning.
  */

package/inferencer/types/mount-observer/types.d.ts

@@ -1,6 +1,6 @@
 // Core types for MountObserver v2 - Polyfill Supported Scenario I
 
-import {EnhancementConfigBase, EnhKey, AttrPatterns} from '../assign-gingerly/types';
+import {EnhancementConfigBase, EnhKey, AttrPatterns, AssignFromOptions} from '../assign-gingerly/types';
 
 export type Constructor = new (...args: any[]) => any;
 
@@ -189,6 +189,14 @@ export interface MountConfig<TKeys extends string = string, TCustomData = unknow
      */
     stageOnMount?: Record<string, any>;
     
+    /**
+     * Options passed to assign-gingerly for assignOnMount, assignOnDismount, and stageOnMount.
+     * Enables features like method calls (withMethods), aliases (aka), async methods, and signal-based cleanup.
+     * Shared across all assign operations on this observer.
+     * @example { withMethods: ['setAttribute', 'removeAttribute'], aka: { '$': 'querySelector' } }
+     */
+    assignOptions?: Record<string, any>;
+
     /**
      * When true, enables detailed event dispatching for debugging and monitoring.
      * Provides granular lifecycle events for observation.
@@ -342,7 +350,7 @@ export interface IMountObserver extends EventTarget {
     observe(observedNode: Node): Promise<void>;
     disconnect(): void;
     disconnectedSignal: AbortSignal;
-    assignGingerly(config: Record<string, any> | undefined): Promise<void>;
+    assign(config: Record<string, any> | undefined, options?: Record<string, any>): Promise<void>;
     getNotifier(element: Element): EventTarget;
     readonly options: MountObserverOptions;
 }

package/inferencer/types/roundabout/types.d.ts

@@ -190,7 +190,7 @@ export interface RoundaboutOptions<TProps = unknown, TActions = TProps, ETProps
      * Options passed to every internal assignGingerly call.
      * See IAssignGingerlyOptions in assign-gingerly for details.
      */
-    assignGingerlyOptions?: import('../assign-gingerly/types.js').IAssignGingerlyOptions,
+    assignOptions?: import('../assign-gingerly/types.js').IAssignGingerlyOptions,
 
     /**
      * Protocol handlers for resolving protocol-prefixed values in initialPropVals.

package/inferencer/types/three-peat/types.d.ts

@@ -0,0 +1,18 @@
+import { ElementEnhancementGateway, SpawnContext, FromEachItemConfig } from "../assign-gingerly/types";
+
+export interface EndUserProps{
+    /**
+     * Property of host to pull list from.
+     * If not provided, the host itself is 
+     * assumed to be iterable.
+     */
+    listProp?: string,
+    
+    /**
+     * Specify id of peer element to pull list from.
+     */
+    src?: string;
+    each: FromEachItemConfig,
+    target: string,
+    updateOn: string,
+}

package/object-extension.js

@@ -432,7 +432,7 @@ Object.defineProperty(Object.prototype, 'assignGingerly', {
 Object.defineProperty(Object.prototype, 'assignTentatively', {
     value: function (source, options) {
         const reversal = options?.reversal ?? {};
-        assignTentatively(this, source, { reversal });
+        assignTentatively(this, source, { ...options, reversal });
         return reversal;
     },
     writable: true,

package/object-extension.ts

@@ -1,5 +1,6 @@
 import assignGingerly, { EnhancementRegistry, ItemscopeRegistry, IAssignGingerlyOptions, getInstanceMap, INSTANCE_MAP_GUID } from './assignGingerly.js';
 import assignTentatively from './assignTentatively.js';
+import type { IAssignTentativelyOptions } from './types/assign-gingerly/types.js';
 import { EnhancementConfig, SpawnContext } from './types/assign-gingerly/types.js';
 import { parseWithAttrs } from './parseWithAttrs.js';
 
@@ -77,7 +78,7 @@ declare global {
      */
     assignTentatively(
       source: Record<string | symbol, any>,
-      options?: { reversal?: Record<string | symbol, any> }
+      options?: IAssignTentativelyOptions
     ): Record<string | symbol, any>;
   }
 }
@@ -576,10 +577,10 @@ Object.defineProperty(Object.prototype, 'assignTentatively', {
   value: function <T extends object>(
     this: T,
     source: Record<string | symbol, any>,
-    options?: { reversal?: Record<string | symbol, any> }
+    options?: IAssignTentativelyOptions
   ): Record<string | symbol, any> {
     const reversal = options?.reversal ?? {};
-    assignTentatively(this, source, { reversal });
+    assignTentatively(this, source, { ...options, reversal });
     return reversal;
   },
   writable: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.63",
+  "version": "0.0.65",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -169,6 +169,14 @@
     "./evaluatePathWithAsyncMethods.js": {
       "default": "./evaluatePathWithAsyncMethods.js",
       "types": "./evaluatePathWithAsyncMethods.ts"
+    },
+    "./handlers/nudge.js": {
+      "default": "./handlers/nudge.js",
+      "types": "./handlers/nudge.ts"
+    },
+    "./handlers/arr.js": {
+      "default": "./handlers/arr.js",
+      "types": "./handlers/arr.ts"
     }
   },
   "main": "index.js",

package/paths.ts

@@ -287,7 +287,7 @@ export function doAssign(...pairs: Record<string, any>[]): { assign: Record<stri
  * const merges = [
  *     ...forEachKeyIn<Person>(['firstName', 'lastName'], (key, $) => ({
  *         ifKeyIn: [key],
- *         assignOptions: { withIds: { [key]: { qry: `[name="${key}"]` } } },
+ *         assignOptions: { pin: { [key]: { qry: `[name="${key}"]` } } },
  *         ...doAssign(set($['#' + key]).to($[key]))
  *     })),
  * ];

package/{withIdsCorrector.js → pinCorrector.js}

@@ -1,5 +1,5 @@
 /**
- * withIdsCorrector.ts — Dev-time diagnostic for stale withIds coordinates.
+ * pinCorrector.ts — Dev-time diagnostic for stale pin coordinates.
  *
  * Dynamically imported only on mismatch — zero cost in production or when coordinates are correct.
  * Computes and logs the correct child index path for a given selector.
@@ -24,24 +24,24 @@ function computeChildPath(root, target) {
     return current === root ? path : null;
 }
 /**
- * Log a correction suggestion for a mismatched withIds config.
+ * Log a correction suggestion for a mismatched pin config.
  */
 export function logConfigCorrection(target, varName, config) {
     if (!config.expect)
         return;
     const correctEl = target.querySelector?.(config.expect);
     if (!correctEl) {
-        console.warn(`withIds["${varName}"]: path [${config.path}] did not match "${config.expect}" ` +
+        console.warn(`pin["${varName}"]: path [${config.path}] did not match "${config.expect}" ` +
             `and querySelector also found no match. Check that the selector is correct.`);
         return;
     }
     const correctPath = computeChildPath(target, correctEl);
     if (correctPath) {
-        console.warn(`withIds["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
+        console.warn(`pin["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
             `Suggested correction: [${correctPath.join(', ')}]`);
     }
     else {
-        console.warn(`withIds["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
+        console.warn(`pin["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
             `Could not compute a child index path (element may not be a descendant of target).`);
     }
 }

package/{withIdsCorrector.ts → pinCorrector.ts}

@@ -1,5 +1,5 @@
 /**
- * withIdsCorrector.ts — Dev-time diagnostic for stale withIds coordinates.
+ * pinCorrector.ts — Dev-time diagnostic for stale pin coordinates.
  * 
  * Dynamically imported only on mismatch — zero cost in production or when coordinates are correct.
  * Computes and logs the correct child index path for a given selector.
@@ -26,7 +26,7 @@ function computeChildPath(root: Element, target: Element): number[] | null {
 }
 
 /**
- * Log a correction suggestion for a mismatched withIds config.
+ * Log a correction suggestion for a mismatched pin config.
  */
 export function logConfigCorrection(
     target: any,
@@ -38,7 +38,7 @@ export function logConfigCorrection(
     const correctEl = target.querySelector?.(config.expect);
     if (!correctEl) {
         console.warn(
-            `withIds["${varName}"]: path [${config.path}] did not match "${config.expect}" ` +
+            `pin["${varName}"]: path [${config.path}] did not match "${config.expect}" ` +
             `and querySelector also found no match. Check that the selector is correct.`
         );
         return;
@@ -47,12 +47,12 @@ export function logConfigCorrection(
     const correctPath = computeChildPath(target, correctEl);
     if (correctPath) {
         console.warn(
-            `withIds["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
+            `pin["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
             `Suggested correction: [${correctPath.join(', ')}]`
         );
     } else {
         console.warn(
-            `withIds["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
+            `pin["${varName}"]: path [${config.path}] did not match "${config.expect}". ` +
             `Could not compute a child index path (element may not be a descendant of target).`
         );
     }

package/processHandlerCommands.js

@@ -194,7 +194,8 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
                 resolvedParams = getValues(config.get, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
-                    protocols: options.protocols
+                    protocols: options.protocols,
+                    root: target
                 });
             }
             // Resolve 'resolve' map asynchronously (yields to microtask queue)
@@ -202,7 +203,8 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
                 const asyncResolved = await resolveValues(config.resolve, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
-                    protocols: options.protocols
+                    protocols: options.protocols,
+                    root: target
                 });
                 Object.assign(resolvedParams, asyncResolved);
             }

package/processHandlerCommands.ts

@@ -220,7 +220,8 @@ export async function processHandlerCommands(
                 resolvedParams = getValues(config.get, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
-                    protocols: options.protocols
+                    protocols: options.protocols,
+                    root: target
                 });
             }
             // Resolve 'resolve' map asynchronously (yields to microtask queue)
@@ -228,7 +229,8 @@ export async function processHandlerCommands(
                 const asyncResolved = await resolveValues(config.resolve, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
-                    protocols: options.protocols
+                    protocols: options.protocols,
+                    root: target
                 });
                 Object.assign(resolvedParams, asyncResolved);
             }

package/resolveIdRef.js

@@ -1,7 +1,7 @@
 /**
  * resolveIdRef.ts — Cached element resolution via #[x] syntax.
  *
- * Dynamically imported by assignFrom when `withIds` is provided or `#[x]` patterns are detected.
+ * Dynamically imported by assignFrom when `pin` is provided or `#[x]` patterns are detected.
  * Provides lazy, WeakRef-cached element lookups keyed by variable name.
  *
  * First access: runs the query against the target, auto-assigns an ID if needed, caches via WeakRef.
@@ -37,11 +37,11 @@ function generateUniqueId(rootNode) {
  *
  * @param varName - The variable name (e.g., 'x' from '#[x]')
  * @param target - The target element to query against
- * @param withIds - The withIds configuration map
+ * @param pin - The pin configuration map
  * @returns The resolved element, or undefined if not found
  */
-export function resolveIdVariable(varName, target, withIds) {
-    const config = withIds[varName];
+export function resolveIdVariable(varName, target, pin) {
+    const config = pin[varName];
     if (config === undefined)
         return undefined;
     // For 'at' option path-based configs (array or { path }), resolve directly from target — no ID, no caching
@@ -56,10 +56,10 @@ export function resolveIdVariable(varName, target, withIds) {
         return current instanceof Element ? current : undefined;
     }
     if (typeof config === 'object' && 'path' in config && !('qry' in config)) {
-        // Determine if this is from 'at' (no ID assignment) or 'withIds' with path (assigns ID + caches)
-        // When called from 'at', we skip ID/caching. When from 'withIds', we assign ID and cache.
+        // Determine if this is from 'at' (no ID assignment) or 'pin' with path (assigns ID + caches)
+        // When called from 'at', we skip ID/caching. When from 'pin', we assign ID and cache.
         // Distinguish by presence in the options — caller passes the merged map.
-        // For now: { path } without 'noId' → assign ID + cache (withIds behavior)
+        // For now: { path } without 'noId' → assign ID + cache (pin behavior)
         const rootNode = target.getRootNode?.() ?? target;
         let current = target;
         for (const idx of config.path) {
@@ -78,7 +78,7 @@ export function resolveIdVariable(varName, target, withIds) {
                 // Fire-and-forget: log correction suggestion
                 const capturedConfig = config;
                 const capturedVarName = varName;
-                import('./withIdsCorrector.js').then(module => {
+                import('./pinCorrector.js').then(module => {
                     module.logConfigCorrection(target, capturedVarName, capturedConfig);
                 }).catch(() => { });
             }

package/resolveIdRef.ts

@@ -1,7 +1,7 @@
 /**
  * resolveIdRef.ts — Cached element resolution via #[x] syntax.
  * 
- * Dynamically imported by assignFrom when `withIds` is provided or `#[x]` patterns are detected.
+ * Dynamically imported by assignFrom when `pin` is provided or `#[x]` patterns are detected.
  * Provides lazy, WeakRef-cached element lookups keyed by variable name.
  * 
  * First access: runs the query against the target, auto-assigns an ID if needed, caches via WeakRef.
@@ -9,7 +9,7 @@
  */
 
 /**
- * Configuration for a withIds entry.
+ * Configuration for a pin entry.
  */
 export type WithIdConfig = string | { qry: string } | number[] | { path: number[]; expect?: string; fallback?: boolean };
 
@@ -46,15 +46,15 @@ function generateUniqueId(rootNode: any): string {
  * 
  * @param varName - The variable name (e.g., 'x' from '#[x]')
  * @param target - The target element to query against
- * @param withIds - The withIds configuration map
+ * @param pin - The pin configuration map
  * @returns The resolved element, or undefined if not found
  */
 export function resolveIdVariable(
     varName: string,
     target: any,
-    withIds: Record<string, WithIdConfig>
+    pin: Record<string, WithIdConfig>
 ): Element | undefined {
-    const config = withIds[varName];
+    const config = pin[varName];
     if (config === undefined) return undefined;
 
     // For 'at' option path-based configs (array or { path }), resolve directly from target — no ID, no caching
@@ -69,10 +69,10 @@ export function resolveIdVariable(
     }
 
     if (typeof config === 'object' && 'path' in config && !('qry' in config)) {
-        // Determine if this is from 'at' (no ID assignment) or 'withIds' with path (assigns ID + caches)
-        // When called from 'at', we skip ID/caching. When from 'withIds', we assign ID and cache.
+        // Determine if this is from 'at' (no ID assignment) or 'pin' with path (assigns ID + caches)
+        // When called from 'at', we skip ID/caching. When from 'pin', we assign ID and cache.
         // Distinguish by presence in the options — caller passes the merged map.
-        // For now: { path } without 'noId' → assign ID + cache (withIds behavior)
+        // For now: { path } without 'noId' → assign ID + cache (pin behavior)
         const rootNode = target.getRootNode?.() ?? target;
         let current: any = target;
         for (const idx of config.path) {
@@ -91,7 +91,7 @@ export function resolveIdVariable(
                 // Fire-and-forget: log correction suggestion
                 const capturedConfig = config;
                 const capturedVarName = varName;
-                import('./withIdsCorrector.js').then(module => {
+                import('./pinCorrector.js').then(module => {
                     module.logConfigCorrection(target, capturedVarName, capturedConfig);
                 }).catch(() => {});
             }