assign-gingerly 0.0.95 → 0.0.97

package/README.md

@@ -82,7 +82,7 @@ The third fundamental utility function is:
 **`assignFrom` is synchronous** — it resolves paths, expands substitutions, handles spreads, processes `#[x]` refs, and runs inferred assignments all without yielding to the event loop. Handler commands (` =>`), `beVigilant`, and `enhance` are fire-and-forget (kicked off asynchronously in the background).
 
 **`assignFromAsync`** is the awaitable variant for when you need to:
-- Use async protocol handlers (e.g., `fetch`-based resolution)
+- Use async protocol handlers (e.g., `fetch`-based resolution — protocols are introduced just below, and covered in full in [Protocol Resolution](#protocol-resolution-in-getvalues-and-assignfrom) later in this doc)
 - `await` handler completion before proceeding
 - Wait for `enhance` (EMC JSON imports) to finish
 
@@ -97,7 +97,7 @@ assignFrom adds support for:
 
 1.  Resolving RHS path strings against a source object (`from`).
 2.  Target-relative root references via `$0` so paths can resolve from the first argument passed to `assignFrom`/`assignFromAsync` (the target object) instead of the `from` object.
-3.  Protocol resolution (`globalThis://`, `localStorage://`, custom sync protocols).
+3.  Protocol resolution (`globalThis://`, `localStorage://`, custom sync protocols) — don't worry if this is unfamiliar yet, it's explained in full in [Protocol Resolution in `getValues` and `assignFrom`](#protocol-resolution-in-getvalues-and-assignfrom) later in this doc.
 4.  Handler plugins via the ` =>` operator for custom logic (fire-and-forget in sync mode, awaitable in async mode).
 5.  Looped substitution with `where_x_in` / `where_y_in` / `where_z_in` for expanding template patterns into multiple concrete assignments.
 6.  Dynamic substitutions via the `substitutions` option for injecting runtime string values into path segments. See [docs/substitutions.md](docs/substitutions.md).
@@ -1594,7 +1594,83 @@ When you access `element.enh.set.enhKey.property`, the proxy:
    - If a non-matching object already exists at `element.enh[enhKey]`, it's passed as `initVals`
    - Stores the spawned instance at `element.enh[enhKey]`
 3. **Reuses existing instances**: If the enhancement already exists and is the correct type, it reuses it
-4. **Falls back to plain objects**: If no registry item is found, creates a plain object at `element.enh[enhKey]`
+4. **Falls back to plain objects, and waits for registration**: If no registry item is found yet, creates a plain object at `element.enh[enhKey]` and calls `registry.whenDefined(enhKey)` to spawn the real instance automatically once the registry item eventually arrives — see [Setting Properties Before the Registry Item Exists](#setting-properties-before-the-registry-item-exists) below
+
+</details>
+
+### Setting Properties Before the Registry Item Exists
+
+Code doesn't always run in the order you'd like — a module might set
+properties on an enhancement before whatever registers that enhancement's
+config has had a chance to run. `enh.set` handles this automatically, the
+same way `element.enh.set.enhKey.property = value` does when the registry
+item is already there:
+
+```TypeScript
+import 'assign-gingerly/object-extension.js';
+
+const myElement = document.createElement('div');
+
+// Nothing has called `registry.push(...)` for 'myEnh' yet.
+myElement.enh.set.myEnh.myProp = 'hello';        // plain placeholder, collected as pending initVals
+myElement.enh.myEnh.anotherProp = 'world';        // direct property access works too, same placeholder
+
+console.log(myElement.enh.myEnh instanceof MyEnhancement); // false -- still a plain object
+
+// ...later, whenever the registry item shows up...
+const registry = myElement.customElementRegistry.enhancementRegistry;
+registry.push({ spawn: MyEnhancement, enhKey: 'myEnh' });
+
+// The spawn happens automatically once `whenDefined` resolves -- no need to
+// touch `myElement.enh.myEnh` again yourself.
+await registry.whenDefined('myEnh');
+console.log(myElement.enh.myEnh instanceof MyEnhancement); // true
+console.log(myElement.enh.myEnh.myProp);                   // 'hello' -- both properties
+console.log(myElement.enh.myEnh.anotherProp);               // 'world' -- survived as initVals
+```
+
+<details>
+<summary>How it works</summary>
+
+1. The first `enh.set.enhKey.property = value` assignment for an
+   unregistered `enhKey` creates a plain object at `element.enh[enhKey]` (as
+   always) and, in addition, calls
+   `registry.whenDefined(enhKey).then(() => element.enh.get(enhKey))`.
+2. Because that call only happens inside the `if (self[prop] === undefined)`
+   branch, it fires exactly once per element/`enhKey` pair — further property
+   assignments before registration just add to the same placeholder object,
+   they don't queue additional spawn attempts.
+3. `registry.whenDefined(enhKey)` resolves once a matching `enhKey` is
+   `push`ed into the registry (see below).
+4. Once it resolves, `enh.get(enhKey)` runs — the same method used everywhere
+   else in this library. It finds the plain placeholder already sitting at
+   `element.enh[enhKey]`, treats it as `initVals` (this is the same
+   "non-matching object passed as `initVals`" behavior described in step 2 of
+   [How It Works](#basic-usage) above — nothing new here), constructs the real
+   instance, and overwrites the placeholder with it.
+
+**`EnhancementRegistry.whenDefined(enhKey)`** — mirrors
+[`customElements.whenDefined(name)`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined):
+
+- If `enhKey` is already registered, resolves once any of its pending
+  [Custom Element Features](#custom-element-features) setup has settled (see
+  `features` on `EnhancementConfig`).
+- If `enhKey` isn't registered yet, first waits for a future `registry.push(...)`
+  call whose config (a single item, or an array) includes a matching `enhKey`,
+  then does the same features-setup wait.
+- **If `enhKey` is never registered, this promise never resolves** — same
+  tradeoff `customElements.whenDefined` makes. Don't `await` it unconditionally
+  in code paths where registration isn't guaranteed to eventually happen.
+
+**Limitations while waiting:**
+- The placeholder is a plain object — no reactivity, no defaults, no
+  validation. Reading a property other than the ones you've explicitly set
+  (e.g. checking `resolved`) just returns `undefined`, since nothing has
+  spawned yet.
+- `mountCtx` still isn't available through this path (same restriction as
+  `enh.set` generally — see the note in
+  [Passing Custom Context](#constructor-signature) above); the eventual
+  `enh.get(enhKey)` call is made with no `mountCtx`.
 
 </details>
 

package/assignGingerly.js

@@ -63,10 +63,27 @@ export class EnhancementRegistry extends EventTarget {
         }
     }
     /**
-     * Wait for all pending setups for a given enhancement key to complete.
+     * Resolves once `enhKey` is defined -- i.e. registered via `push` -- and
+     * ready (any pending `features` setup for it has settled). Mirrors
+     * `customElements.whenDefined(name)`: if the key isn't registered yet, waits
+     * for a future `push` that registers it; if it's never registered, this
+     * never resolves (same tradeoff as the platform method).
      * @param enhKey - Enhancement key to wait for
      */
     async whenDefined(enhKey) {
+        if (!this.findByEnhKey(enhKey)) {
+            await new Promise((resolve) => {
+                const handler = (event) => {
+                    const config = event.config;
+                    const items = Array.isArray(config) ? config : [config];
+                    if (items.some(item => item.enhKey === enhKey)) {
+                        this.removeEventListener(EnhancementRegisteredEvent.eventName, handler);
+                        resolve();
+                    }
+                };
+                this.addEventListener(EnhancementRegisteredEvent.eventName, handler);
+            });
+        }
         const pending = this.#pendingSetups.get(enhKey);
         if (pending && pending.length > 0) {
             await Promise.all(pending);

package/assignGingerly.ts

@@ -106,10 +106,27 @@ export class EnhancementRegistry extends EventTarget {
   }
 
   /**
-   * Wait for all pending setups for a given enhancement key to complete.
+   * Resolves once `enhKey` is defined -- i.e. registered via `push` -- and
+   * ready (any pending `features` setup for it has settled). Mirrors
+   * `customElements.whenDefined(name)`: if the key isn't registered yet, waits
+   * for a future `push` that registers it; if it's never registered, this
+   * never resolves (same tradeoff as the platform method).
    * @param enhKey - Enhancement key to wait for
    */
   async whenDefined(enhKey: EnhKey): Promise<void> {
+    if (!this.findByEnhKey(enhKey)) {
+      await new Promise<void>((resolve) => {
+        const handler = (event: Event) => {
+          const config = (event as EnhancementRegisteredEvent).config;
+          const items = Array.isArray(config) ? config : [config];
+          if (items.some(item => item.enhKey === enhKey)) {
+            this.removeEventListener(EnhancementRegisteredEvent.eventName, handler);
+            resolve();
+          }
+        };
+        this.addEventListener(EnhancementRegisteredEvent.eventName, handler);
+      });
+    }
     const pending = this.#pendingSetups.get(enhKey);
     if (pending && pending.length > 0) {
       await Promise.all(pending);

package/index.js

@@ -8,6 +8,7 @@ export { buildCSSQuery } from './buildCSSQuery.js';
 export { resolveTemplate } from './resolve/resolveTemplate.js';
 export { getHost } from './getHost.js';
 export { resolveValues, resolveValue } from './resolve/resolveValues.js';
+export { getValues, getValue, hasProtocol, parseProtocolRef, isPlainObject } from './resolve/getValues.js';
 export { assignFromAsync } from './assignFromAsync.js';
 export { assignFrom } from './assignFrom.js';
 export { assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions } from './assignFeatures.js';

package/index.ts

@@ -8,6 +8,7 @@ export {buildCSSQuery} from './buildCSSQuery.js';
 export {resolveTemplate} from './resolve/resolveTemplate.js';
 export {getHost} from './getHost.js';
 export {resolveValues, resolveValue} from './resolve/resolveValues.js';
+export {getValues, getValue, hasProtocol, parseProtocolRef, isPlainObject} from './resolve/getValues.js';
 export {assignFromAsync} from './assignFromAsync.js';
 export {assignFrom} from './assignFrom.js';
 export {assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions} from './assignFeatures.js';

package/inferencer/types/EnhancementConversionInstructions.md

@@ -107,7 +107,7 @@ Update the package.json to use the modern architecture's dependencies and build
      "nested-regex-groups": "*"
    }
    ```
-   - Drop the legacy dependencies (`be-enhanced`, `trans-render`, etc.). Keep a legacy dependency **only** if a converted action still imports from it and the modern stack has no replacement (e.g. `trans-render/XV/set.js` for the Uniform Storage Path protocol) — note any such carry-over in your conversion notes.
+   - Drop the legacy dependencies (`be-enhanced`, `trans-render`, etc.). There is a modern replacement for most legacy utilities — e.g. Uniform Storage Path writes move from `trans-render/XV/set.js` to [`fifteenth`](https://github.com/bahrus/fifteenth) (`fifteenth/set.js`, see Step 9). Keep a legacy dependency **only** if a converted action still imports from it and no replacement exists — and note any such carry-over in your conversion notes.
    - `mount-observer` is listed as a direct dependency so it lands at the root `node_modules/` level, accessible via the import map. `nested-regex-groups` is optional but recommended if your enhancement needs custom attribute parsing (Step 7a).
    - The exact version strings do not matter here — the next step replaces them all with the latest published versions.
 
@@ -969,6 +969,14 @@ export interface Actions{
 7. **Update utility imports**:
    - Replace `trans-render/lib/findAdjacentElement.js` with `be-hive/findAdjacentElement.js`
    - The be-hive package provides common utilities that were previously in trans-render
+   - **Uniform Storage Path (USL) writes** — if a legacy action wrote values to `indexedDB://…`, `localStorage://…`, etc. via `trans-render/XV/set.js`, use [`fifteenth`](https://github.com/bahrus/fifteenth) instead:
+     ```javascript
+     const { set } = await import('fifteenth/set.js');
+     await set('indexedDB://myDB/myStore/myKey', value);   // same (usl, val, ctx?) signature as XV/set
+     ```
+     - Add `"fifteenth"` to `dependencies` and a `"fifteenth/": "/node_modules/fifteenth/"` entry to the import map.
+     - `fifteenth` imports `parseProtocolRef` from `assign-gingerly@0.0.96`+. `roundabout-lib` / `mount-observer` may still pin an older `assign-gingerly` exactly, and the flat import map can only serve one copy — so also add `"assign-gingerly": "<the version fifteenth needs>"` to `dependencies` to hoist a single root copy. Verify the be-hive/mount-observer/roundabout read path still works against that version.
+     - **Behavior change to note in your conversion notes:** `fifteenth`'s `set` broadcasts `window.postMessage([usp])` (or `[usp, usl]` when the USL has a `?.` accessor chain) — a plain `Array` of path strings, *not* the `Set` (protocol + store-root + full-path) that `trans-render/XV` posted. Update any `message` listeners accordingly.
 
 **CRITICAL - Avoid Compact/Action Conflicts:**
 

package/inferencer/types/ImportantEnhancementAddendum.md

@@ -0,0 +1,46 @@
+# Clarify Programmatic Way to Add Enhancements
+
+When we define an enhancement, it is easiest to demonstrate what it does and how it works by providing simple HTML examples with the attributes used to trigger the enhancement.
+
+These examples are skewed towards an important use case -- progressive enhancement of server rendered content.
+
+However, currently, only a small fraction of web development centers around that paradigm.  Rather, it tends to revolve around client-side rendering, using a framework.
+
+In such a context, putting so much emphasis on the attribute way of hooking things up is problematic.  
+
+1.  Such frameworks are clumsy when it comes to setting attributes.
+2.  The amount of object stringifying and parsing is inefficient.
+
+So we should make an effort to showcase how to integrate with these enhancements efficiently and ergonomically in such settings.  Basically programmatically without the use of attributes.
+
+I think we should showcase two ways to do so.
+
+So for example, currently the README.md for be-persistent shows the example:
+
+```html
+<input be-persistent="of value@input via sessionStorage://{autoGenId}.">
+```
+
+We should also show:
+
+## Imperative Enhancement Attachment:
+
+```JS
+import {emc} from 'be-persistent/emc.json' with {type: 'json'};
+import {BePersistent} from 'be-persistent/be-persistent.js';
+emc.spawn = BePersistent;
+const persistenceEnhancement = oInput.enh.get(emc);
+persistenceEnhancement.store = 
+    {
+        localProp: 'value', //default
+        localEvent: 'input', //default
+        usl: 'sessionStorage://{autoGenId}'
+    };
+```
+
+## Declarative Enhancement Attachment:
+
+```JS
+import 'be-persistent/.js';
+
+```

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

@@ -72,6 +72,8 @@ export interface EnhancementConfig<T = any, Obj = Element> extends EnhancementCo
    * Calls assignFeatures(spawn, features) automatically on registration.
    */
   features?: FeatureConfigsMap;
+
+  customData?: any;
     
 }
 
@@ -406,7 +408,7 @@ export interface AssignFromOptions {
   from: any;
 
   /** Protocol handlers (sync or async) */
-  protocols?: Record<string, (key: string) => any | Promise<any>>;
+  protocols?: ProtocolHandlers;
 
   /** Method names to call during path evaluation (append `|` to a path segment for a zero-argument call) */
   withMethods?: string[] | Set<string>;
@@ -480,6 +482,37 @@ export interface AssignFromOptions {
   [key: string]: any;
 }
 
+/**
+ * A protocol handler resolves the key portion of a protocol-prefixed value
+ * (the text between `://` and the first `?.`) to a value. May be sync or async.
+ */
+export type ProtocolHandler = (key: string) => any | Promise<any>;
+
+/**
+ * A synchronous-only protocol handler, as accepted by getValues / getValue /
+ * assignFrom. For handlers that may return a Promise, use ProtocolHandler.
+ */
+export type SyncProtocolHandler = (key: string) => any;
+
+/** Map of protocol name (the text before `://`) to a handler (sync or async). */
+export type ProtocolHandlers = Record<string, ProtocolHandler>;
+
+/** Map of protocol name to a synchronous handler. */
+export type SyncProtocolHandlers = Record<string, SyncProtocolHandler>;
+
+/**
+ * The outer grammar of a protocol-prefixed value string,
+ * `‹protocol›://‹key›?.‹path›`, as produced by `parseProtocolRef`.
+ */
+export interface ParsedProtocolRef {
+    /** Text before `://`; `''` when the value contains no `://`. */
+    protocol: string;
+    /** Text between `://` and the first `?.` (or the end of the string). */
+    key: string;
+    /** Text from the first `?.` onward (always starts with `?.`), or `null`. */
+    path: string | null;
+}
+
 /**
  * Options for synchronous value resolution (getValues / getValue).
  * Extends IAssignGingerlyOptions with synchronous protocol handlers.
@@ -507,7 +540,7 @@ export interface GetValuesOptions extends IAssignGingerlyOptions {
    *     localStorage: (key) => JSON.parse(localStorage.getItem(key) || 'null')
    * }
    */
-  protocols?: Record<string, (key: string) => any>;
+  protocols?: SyncProtocolHandlers;
 }
 
 /**
@@ -530,7 +563,7 @@ export interface ResolveValuesOptions extends IAssignGingerlyOptions {
    * 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>>;
+  protocols?: ProtocolHandlers;
 }
 
 /**

package/inferencer/types/be-literate/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Uniform Storage Path string (e.g. "indexedDB://myDB/myFiles/{file.name}").
- * Inlined here (was imported from trans-render/XV/types) to keep this file standalone.
+ * Consumed by `fifteenth`'s `set`. Kept as a local alias so this file stays standalone.
  */
 export type USL = string;
 

package/inferencer/types/be-persistent/types.d.ts

@@ -0,0 +1,81 @@
+import { ElementEnhancementGateway, SpawnContext } from "../assign-gingerly/types";
+import { StatementsResult } from "../nested-regex-groups/types";
+
+/**
+ * The programmatic shape of `store`: a bare USL string (shorthand for
+ * `{usl}`, i.e. `localProp`/`localEvent` take their defaults), a single
+ * {@link PersistenceRule}, or an array of them (one binder per entry).
+ * This is the property JS callers set directly — e.g.
+ * `persistenceEnhancement.store = 'sessionStorage://{autoGenId}'` — without
+ * ever going through attribute parsing.
+ */
+export type PersistenceRuleConfig = string | PersistenceRule | PersistenceRule[];
+
+export interface EndUserProps {
+    /**
+     * What to persist and where. Accepts a USL string, a single
+     * {@link PersistenceRule}, or an array of rules — see
+     * {@link PersistenceRuleConfig}. This is the property `hydrate` reads and
+     * the one programmatic (attribute-free) callers should assign.
+     */
+    store?: PersistenceRuleConfig;
+    /**
+     * Opt-in flag set by the boolean `be-persistent-nudge` / `💾-nudge`
+     * attribute.  When present, `hydrate` waits for every rule to finish its
+     * initial storage reconciliation and then calls `assign-gingerly`'s
+     * `nudge` on the enhanced element — decrementing its `disabled` counter so
+     * an element that was disabled only to block edits before its persisted
+     * value loaded becomes interactive.
+     */
+    nudge?: boolean;
+}
+
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element & ElementEnhancementGateway;
+    resolved?: boolean;
+    /**
+     * Flipped to `true` at the end of `init`, once `roundabout` has finished
+     * assigning every attribute-derived prop.  `hydrate` is gated on it so it
+     * never runs against a half-populated view model.
+     */
+    initialized?: boolean;
+    /**
+     * Raw parse result of the base attribute (`be-persistent` / `💾`), via the
+     * `parse-grouped-capture-statements` built-in parser. Exists **only** to be
+     * transferred into `store` by `onPersistenceRulesChange` — nothing else
+     * reads it. Programmatic callers should assign `store` directly instead of
+     * this property.
+     */
+    persistenceRules?: StatementsResult<PersistenceRule>;
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+export interface Actions {
+    init(self: AP, enhancedElement: Element & ElementEnhancementGateway, ctx: SpawnContext, initVals: PAP): Promise<void>;
+    /**
+     * Compact-invoked (`when_persistenceRules_changes_call_onPersistenceRulesChange`),
+     * not an action — normalizes `persistenceRules.statements` into `store`.
+     */
+    onPersistenceRulesChange(self: AP): PAP;
+    hydrate(self: AP): ProPAP;
+}
+
+export interface PersistenceRule {
+    /** Element property to read/write (e.g. `value`, `checked`, `innerHTML`). Defaults to `value`. */
+    localProp?: string;
+    /** DOM event that triggers a save. Defaults to `input`. */
+    localEvent?: string;
+    /**
+     * Uniform Storage Locator describing where the value lives, e.g.
+     * `sessionStorage://{autoGenId}`, `indexedDB://myDB/myStore/{autoGenId}`,
+     * `cookie://{autoGenId}`, `locationHash://{autoGenId}`.
+     * `{autoGenId}` is expanded at runtime to a location-independent DOM path.
+     * Defaults to `sessionStorage://{autoGenId}`.
+     */
+    usl?: string;
+}

package/inferencer/types/gist-in/types.d.ts

@@ -0,0 +1,59 @@
+import { ElementEnhancementGateway, SpawnContext } from "../assign-gingerly/types";
+
+export interface EndUserProps {
+    /**
+     * Where to fetch the replacement content from — either a literal URL
+     * (typically a `gist.githubusercontent.com/.../raw/.../<file>` URL) or a
+     * `fifteenth` `gist://` USL (`gist://<owner>/<id>/raw[/<sha>]/<file>`,
+     * or an alias/`=<id>` form once `configureGist()` has registered the
+     * `gist` protocol).
+     */
+    url: string;
+    /** The `<?marker name="…">` this template's content replaces. */
+    markerName: string;
+    /**
+     * CSS selector naming the parent(s) of the marker(s), so the search
+     * doesn't have to `TreeWalker` the whole subtree. Optional.
+     */
+    forHint: string | undefined;
+    /**
+     * Show a link to edit the gist on GitHub right after the template.
+     * Also triggered page-wide by `?gist-in-show-edit-link=true` in the URL.
+     */
+    showEditLink: boolean;
+    /**
+     * Custom Sanitizer configuration (JSON object, e.g.
+     * `{"elements":["option","optgroup"]}`), same shape as pipe-in's
+     * `[base]-sanitizer`. The platform's *default* sanitizer strips elements
+     * like `<option>` entirely — this is the escape hatch for patching them.
+     * Gated the same way pipe-in gates it: only honored when `url` is a
+     * same-origin path, an import-map-resolved bare specifier, or a
+     * `gist://` USL (whose real destination is always the fixed
+     * `gist.githubusercontent.com` host, not attacker-steerable).
+     */
+    sanitizer: object | undefined;
+    /**
+     * `'setHTML'` (default, sanitized) or `'setHTMLUnsafe'` (no sanitizing at
+     * all) — named after, and selecting between, the two real underlying
+     * methods, the same way pipe-in's `[base]-method` selects one of its own
+     * `streamHTML`/`streamHTMLUnsafe`/etc. `'setHTMLUnsafe'` is gated the same
+     * as a custom `sanitizer` (see above). Never runs embedded `<script>`s
+     * either way — `setHTML`/`setHTMLUnsafe` parse, they don't execute
+     * (verified; same as plain `innerHTML`).
+     */
+    method: 'setHTML' | 'setHTMLUnsafe';
+}
+
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element & ElementEnhancementGateway;
+    resolved: boolean;
+}
+
+export type AP = AllProps;
+export type PAP = Partial<AP>;
+export type ProPAP = Promise<PAP>;
+
+export interface Actions {
+    init(self: AP, enhancedElement: Element, ctx: SpawnContext, initVals: PAP): Promise<void>;
+    hydrate(self: AP): ProPAP;
+}

package/object-extension.js

@@ -317,6 +317,16 @@ class ElementEnhancementContainer {
                     // No registry item found - create plain object if needed
                     if (self[prop] === undefined) {
                         self[prop] = {};
+                        // Declarative-out-of-sequence: `prop`'s enhancement config hasn't
+                        // been registered yet. Once it is, hand the plain object we just
+                        // created off to `get()` as pending initVals and let it spawn
+                        // normally -- `get()` already treats a non-instance value sitting
+                        // in this slot as initVals to merge in (see the `existingInitVals`
+                        // check above). If `prop` is never registered, this never
+                        // resolves (same tradeoff as `customElements.whenDefined`).
+                        const laterRegistry = registry
+                            ?? (typeof customElements !== 'undefined' ? customElements.enhancementRegistry : undefined);
+                        laterRegistry?.whenDefined(prop).then(() => self.get(prop));
                     }
                     return self[prop];
                 }

package/object-extension.ts

@@ -443,8 +443,19 @@ class ElementEnhancementContainer {
           // No registry item found - create plain object if needed
           if (self[prop] === undefined) {
             self[prop] = {};
+
+            // Declarative-out-of-sequence: `prop`'s enhancement config hasn't
+            // been registered yet. Once it is, hand the plain object we just
+            // created off to `get()` as pending initVals and let it spawn
+            // normally -- `get()` already treats a non-instance value sitting
+            // in this slot as initVals to merge in (see the `existingInitVals`
+            // check above). If `prop` is never registered, this never
+            // resolves (same tradeoff as `customElements.whenDefined`).
+            const laterRegistry = registry
+              ?? (typeof customElements !== 'undefined' ? (customElements as any).enhancementRegistry : undefined);
+            laterRegistry?.whenDefined(prop).then(() => self.get(prop));
           }
-          
+
           return self[prop];
         }
       }) as any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.95",
+  "version": "0.0.97",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -228,7 +228,7 @@
     "chrome": "npx playwright cr http://localhost:8000"
   },
   "devDependencies": {
-    "@playwright/test": "1.62.1",
-    "spa-ssi": "0.0.27"
+    "@playwright/test": "1.63.0",
+    "spa-ssi": "0.0.28"
   }
 }

package/resolve/getValues.js

@@ -183,11 +183,47 @@ function navigatePath(source, parts, withMethods, permissionProcessor) {
     return current;
 }
 /**
- * Checks if a string value looks like a protocol reference.
+ * Whether a string carries a protocol prefix (contains `://`).
+ *
+ * Exported as the single source of truth for the outer USL grammar, so
+ * downstream packages (and resolveValues) don't re-implement the check.
  */
-function hasProtocol(value) {
+export function hasProtocol(value) {
     return value.includes('://');
 }
+/**
+ * Split a protocol-prefixed value string into its outer-grammar parts:
+ * `‹protocol›://‹key›?.‹path›`.
+ *
+ * - `protocol` is the text before `://` (`''` when there is no `://`).
+ * - `key` is the text between `://` and the first `?.` (or end of string).
+ * - `path` is the `?.`-onward remainder (starting with `?.`), or `null`.
+ *
+ * Pure string parsing — no handler lookup, no resolution. Shared by the sync
+ * (`getProtocolValue`) and async (`resolveProtocolValue`) resolvers.
+ */
+export function parseProtocolRef(value) {
+    const protoEnd = value.indexOf('://');
+    if (protoEnd === -1)
+        return { protocol: '', key: value, path: null };
+    const protocol = value.substring(0, protoEnd);
+    const rest = value.substring(protoEnd + 3);
+    const pathStart = rest.indexOf('?.');
+    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
+    const path = pathStart === -1 ? null : rest.substring(pathStart);
+    return { protocol, key, path };
+}
+/**
+ * Whether a value is a plain object (prototype is `Object.prototype` or `null`),
+ * as opposed to an array, a class instance, or a primitive. Used to decide
+ * whether a nested value should be recursed into as a pattern.
+ */
+export function isPlainObject(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
 /**
  * Detect a leading run of `!` characters used as a boolean coercion / negation
  * marker (`!` = negate, `!!` = coerce to boolean, `!!!` = negate, …). Returns the
@@ -266,15 +302,10 @@ function resolveStringValue(value, source, aliasMap, withMethods, protocols, opt
  * Resolve a protocol-prefixed value synchronously.
  */
 function getProtocolValue(value, protocols, options) {
-    const protoEnd = value.indexOf('://');
-    const protocol = value.substring(0, protoEnd);
+    const { protocol, key, path } = parseProtocolRef(value);
     const handler = protocols[protocol];
     if (!handler)
         return value; // not a recognized protocol
-    const rest = value.substring(protoEnd + 3);
-    const pathStart = rest.indexOf('?.');
-    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
-    const path = pathStart === -1 ? null : rest.substring(pathStart);
     const resolved = handler(key);
     if (path) {
         return getValue(path, resolved, options);
@@ -295,13 +326,7 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options, substi
             result.push(getArray(item, source, aliasMap, withMethods, protocols, options, substitutionMap));
         }
         else if (item && typeof item === 'object') {
-            const proto = Object.getPrototypeOf(item);
-            if (proto === Object.prototype || proto === null) {
-                result.push(getValues(item, source, options));
-            }
-            else {
-                result.push(item);
-            }
+            result.push(isPlainObject(item) ? getValues(item, source, options) : item);
         }
         else {
             result.push(item);
@@ -334,13 +359,7 @@ export function getValues(pattern, source, options) {
             result[key] = getArray(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
         }
         else if (typeof value === 'object' && value !== null) {
-            const proto = Object.getPrototypeOf(value);
-            if (proto === Object.prototype || proto === null) {
-                result[key] = getValues(value, source, options);
-            }
-            else {
-                result[key] = value;
-            }
+            result[key] = isPlainObject(value) ? getValues(value, source, options) : value;
         }
         else {
             result[key] = value;

package/resolve/getValues.ts

@@ -17,7 +17,7 @@
  * }, source, { withMethods: ['querySelector'], aka: { q: 'querySelector' } });
  */
 
-import type { GetValuesOptions, PermissionProcessor } from '../types/assign-gingerly/types.js';
+import type { GetValuesOptions, ParsedProtocolRef, PermissionProcessor, SyncProtocolHandlers } from '../types/assign-gingerly/types.js';
 
 export function normalizeAliasOptions(options?: {
     aka?: Record<string, string>;
@@ -221,12 +221,48 @@ function navigatePath(
 }
 
 /**
- * Checks if a string value looks like a protocol reference.
+ * Whether a string carries a protocol prefix (contains `://`).
+ *
+ * Exported as the single source of truth for the outer USL grammar, so
+ * downstream packages (and resolveValues) don't re-implement the check.
  */
-function hasProtocol(value: string): boolean {
+export function hasProtocol(value: string): boolean {
     return value.includes('://');
 }
 
+/**
+ * Split a protocol-prefixed value string into its outer-grammar parts:
+ * `‹protocol›://‹key›?.‹path›`.
+ *
+ * - `protocol` is the text before `://` (`''` when there is no `://`).
+ * - `key` is the text between `://` and the first `?.` (or end of string).
+ * - `path` is the `?.`-onward remainder (starting with `?.`), or `null`.
+ *
+ * Pure string parsing — no handler lookup, no resolution. Shared by the sync
+ * (`getProtocolValue`) and async (`resolveProtocolValue`) resolvers.
+ */
+export function parseProtocolRef(value: string): ParsedProtocolRef {
+    const protoEnd = value.indexOf('://');
+    if (protoEnd === -1) return { protocol: '', key: value, path: null };
+    const protocol = value.substring(0, protoEnd);
+    const rest = value.substring(protoEnd + 3);
+    const pathStart = rest.indexOf('?.');
+    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
+    const path = pathStart === -1 ? null : rest.substring(pathStart);
+    return { protocol, key, path };
+}
+
+/**
+ * Whether a value is a plain object (prototype is `Object.prototype` or `null`),
+ * as opposed to an array, a class instance, or a primitive. Used to decide
+ * whether a nested value should be recursed into as a pattern.
+ */
+export function isPlainObject(value: any): boolean {
+    if (!value || typeof value !== 'object') return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
 /**
  * Detect a leading run of `!` characters used as a boolean coercion / negation
  * marker (`!` = negate, `!!` = coerce to boolean, `!!!` = negate, …). Returns the
@@ -249,7 +285,7 @@ function parseNegationMarker(value: string): { count: number; rest: string } | n
  */
 function looksLikeReference(
     value: string,
-    protocols: Record<string, (key: string) => any> | undefined
+    protocols: SyncProtocolHandlers | undefined
 ): boolean {
     return value.startsWith('?.')
         || value.startsWith('$0')
@@ -265,7 +301,7 @@ function resolveReferenceString(
     source: any,
     aliasMap: Map<string, string>,
     withMethods: Set<string> | undefined,
-    protocols: Record<string, (key: string) => any> | undefined,
+    protocols: SyncProtocolHandlers | undefined,
     options: GetValuesOptions | undefined,
     substitutionMap: Map<string, string> | undefined
 ): any {
@@ -298,7 +334,7 @@ function resolveStringValue(
     source: any,
     aliasMap: Map<string, string>,
     withMethods: Set<string> | undefined,
-    protocols: Record<string, (key: string) => any> | undefined,
+    protocols: SyncProtocolHandlers | undefined,
     options: GetValuesOptions | undefined,
     substitutionMap: Map<string, string> | undefined
 ): any {
@@ -325,21 +361,14 @@ function resolveStringValue(
  */
 function getProtocolValue(
     value: string,
-    protocols: Record<string, (key: string) => any>,
+    protocols: SyncProtocolHandlers,
     options?: GetValuesOptions
 ): any {
-    const protoEnd = value.indexOf('://');
-    const protocol = value.substring(0, protoEnd);
+    const { protocol, key, path } = parseProtocolRef(value);
 
     const handler = protocols[protocol];
     if (!handler) return value; // not a recognized protocol
 
-    const rest = value.substring(protoEnd + 3);
-
-    const pathStart = rest.indexOf('?.');
-    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
-    const path = pathStart === -1 ? null : rest.substring(pathStart);
-
     const resolved = handler(key);
 
     if (path) {
@@ -357,7 +386,7 @@ function getArray(
     source: any,
     aliasMap: Map<string, string>,
     withMethods: Set<string> | undefined,
-    protocols: Record<string, (key: string) => any> | undefined,
+    protocols: SyncProtocolHandlers | undefined,
     options?: GetValuesOptions,
     substitutionMap?: Map<string, string>
 ): any[] {
@@ -368,12 +397,7 @@ function getArray(
         } else if (Array.isArray(item)) {
             result.push(getArray(item, source, aliasMap, withMethods, protocols, options, substitutionMap));
         } else if (item && typeof item === 'object') {
-            const proto = Object.getPrototypeOf(item);
-            if (proto === Object.prototype || proto === null) {
-                result.push(getValues(item, source, options));
-            } else {
-                result.push(item);
-            }
+            result.push(isPlainObject(item) ? getValues(item, source, options) : item);
         } else {
             result.push(item);
         }
@@ -410,12 +434,7 @@ export function getValues(
         } else if (Array.isArray(value)) {
             result[key] = getArray(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
         } else if (typeof value === 'object' && value !== null) {
-            const proto = Object.getPrototypeOf(value);
-            if (proto === Object.prototype || proto === null) {
-                result[key] = getValues(value, source, options);
-            } else {
-                result[key] = value;
-            }
+            result[key] = isPlainObject(value) ? getValues(value, source, options) : value;
         } else {
             result[key] = value;
         }

package/resolve/resolveValues.js

@@ -4,30 +4,24 @@
  * Thin async wrapper around getValues that adds support for async protocol handlers.
  * For synchronous-only use cases, import getValues/getValue directly for better performance.
  *
+ * The outer-grammar primitives (`hasProtocol`, `parseProtocolRef`, `isPlainObject`)
+ * live in getValues.js and are re-exported here for convenience.
+ *
  * Re-exports ResolveValuesOptions for backward compatibility.
  */
-import { getValue, getValues } from './getValues.js';
+import { getValue, getValues, hasProtocol, isPlainObject, parseProtocolRef } from './getValues.js';
 // Re-export getValue as resolveValue for backward compatibility
 export { getValue as resolveValue };
-/**
- * Checks if a string value looks like a protocol reference.
- */
-function hasProtocol(value) {
-    return value.includes('://');
-}
+// Re-export the shared outer-grammar primitives (defined in getValues.js)
+export { hasProtocol, parseProtocolRef, isPlainObject };
 /**
  * Resolves a protocol-prefixed value asynchronously.
  */
 async function resolveProtocolValue(value, protocols, options) {
-    const protoEnd = value.indexOf('://');
-    const protocol = value.substring(0, protoEnd);
+    const { protocol, key, path } = parseProtocolRef(value);
     const handler = protocols[protocol];
     if (!handler)
         return value;
-    const rest = value.substring(protoEnd + 3);
-    const pathStart = rest.indexOf('?.');
-    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
-    const path = pathStart === -1 ? null : rest.substring(pathStart);
     const resolved = await handler(key);
     if (path) {
         return getValue(path, resolved, options);
@@ -52,8 +46,7 @@ async function resolveArray(arr, source, protocols, options) {
             result.push(await resolveArray(item, source, protocols, options));
         }
         else if (item && typeof item === 'object') {
-            const proto = Object.getPrototypeOf(item);
-            if (proto === Object.prototype || proto === null) {
+            if (isPlainObject(item)) {
                 result.push(options?.protocols ? await resolveValues(item, source, options) : getValues(item, source, options));
             }
             else {
@@ -93,8 +86,7 @@ export async function resolveValues(pattern, source, options) {
             result[key] = await resolveArray(value, source, protocols, options);
         }
         else if (typeof value === 'object' && value !== null) {
-            const proto = Object.getPrototypeOf(value);
-            if (proto === Object.prototype || proto === null) {
+            if (isPlainObject(value)) {
                 result[key] = options?.protocols ? await resolveValues(value, source, options) : getValues(value, source, options);
             }
             else {

package/resolve/resolveValues.ts

@@ -1,126 +1,116 @@
-/**
- * resolveValues.ts — Async value resolution for path strings.
- * 
- * Thin async wrapper around getValues that adds support for async protocol handlers.
- * For synchronous-only use cases, import getValues/getValue directly for better performance.
- * 
- * Re-exports ResolveValuesOptions for backward compatibility.
- */
-
-import { getValue, getValues } from './getValues.js';
-import type { ResolveValuesOptions } from '../types/assign-gingerly/types.js';
-
-export type { ResolveValuesOptions };
-
-// Re-export getValue as resolveValue for backward compatibility
-export { getValue as resolveValue };
-
-/**
- * Checks if a string value looks like a protocol reference.
- */
-function hasProtocol(value: string): boolean {
-    return value.includes('://');
-}
-
-
-/**
- * Resolves a protocol-prefixed value asynchronously.
- */
-async function resolveProtocolValue(
-    value: string,
-    protocols: Record<string, (key: string) => any | Promise<any>>,
-    options?: ResolveValuesOptions
-): Promise<any> {
-    const protoEnd = value.indexOf('://');
-    const protocol = value.substring(0, protoEnd);
-
-    const handler = protocols[protocol];
-    if (!handler) return value;
-
-    const rest = value.substring(protoEnd + 3);
-    const pathStart = rest.indexOf('?.');
-    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
-    const path = pathStart === -1 ? null : rest.substring(pathStart);
-
-    const resolved = await handler(key);
-
-    if (path) {
-        return getValue(path, resolved, options);
-    }
-    return resolved;
-}
-
-/**
- * Resolve path strings and protocol references within an array (async).
- */
-async function resolveArray(
-    arr: any[],
-    source: any,
-    protocols: Record<string, (key: string) => any | Promise<any>> | undefined,
-    options?: ResolveValuesOptions
-): Promise<any[]> {
-    const result: any[] = [];
-    for (const item of arr) {
-        if (typeof item === 'string') {
-            if (protocols && hasProtocol(item)) {
-                result.push(await resolveProtocolValue(item, protocols, options));
-            } else {
-                result.push(getValue(item, source, options));
-            }
-        } else if (Array.isArray(item)) {
-            result.push(await resolveArray(item, source, protocols, options));
-        } else if (item && typeof item === 'object') {
-            const proto = Object.getPrototypeOf(item);
-            if (proto === Object.prototype || proto === null) {
-                result.push(options?.protocols ? await resolveValues(item, source, options) : getValues(item, source, options));
-            } else {
-                result.push(item);
-            }
-        } else {
-            result.push(item);
-        }
-    }
-    return result;
-}
-
-/**
- * Async resolve RHS path strings in a pattern object against a source object.
- * 
- * Supports async protocol handlers (e.g., fetch, IndexedDB).
- * For synchronous-only patterns, use `getValues` from 'assign-gingerly/getValues.js' instead.
- * 
- * @param pattern - Object whose RHS values may contain `?.` path strings
- * @param source - Object to resolve paths against
- * @param options - Optional withMethods, aka, and protocol handlers
- * @returns New object with path strings replaced by resolved values
- */
-export async function resolveValues(
-    pattern: Record<string, any>,
-    source: any,
-    options?: ResolveValuesOptions
-): Promise<Record<string, any>> {
-    const protocols = options?.protocols;
-
-    const result: Record<string, any> = {};
-    for (const [key, value] of Object.entries(pattern)) {
-        if (typeof value === 'string') {
-            if (protocols && hasProtocol(value)) {
-                result[key] = await resolveProtocolValue(value, protocols, options);
-            } else {
-                result[key] = getValue(value, source, options);
-            }
-        } else if (Array.isArray(value)) {
-            result[key] = await resolveArray(value, source, protocols, options);
-        } else if (typeof value === 'object' && value !== null) {
-            const proto = Object.getPrototypeOf(value);
-            if (proto === Object.prototype || proto === null) {
-                result[key] = options?.protocols ? await resolveValues(value, source, options) : getValues(value, source, options);
-            } else {
-                result[key] = value;
-            }
-        } else {
-            result[key] = value;
-        }
-    }
-    return result;
-}
+/**
+ * resolveValues.ts — Async value resolution for path strings.
+ *
+ * Thin async wrapper around getValues that adds support for async protocol handlers.
+ * For synchronous-only use cases, import getValues/getValue directly for better performance.
+ *
+ * The outer-grammar primitives (`hasProtocol`, `parseProtocolRef`, `isPlainObject`)
+ * live in getValues.js and are re-exported here for convenience.
+ *
+ * Re-exports ResolveValuesOptions for backward compatibility.
+ */
+
+import { getValue, getValues, hasProtocol, isPlainObject, parseProtocolRef } from './getValues.js';
+import type { ProtocolHandlers, ResolveValuesOptions } from '../types/assign-gingerly/types.js';
+
+export type { ResolveValuesOptions };
+
+// Re-export getValue as resolveValue for backward compatibility
+export { getValue as resolveValue };
+
+// Re-export the shared outer-grammar primitives (defined in getValues.js)
+export { hasProtocol, parseProtocolRef, isPlainObject };
+
+/**
+ * Resolves a protocol-prefixed value asynchronously.
+ */
+async function resolveProtocolValue(
+    value: string,
+    protocols: ProtocolHandlers,
+    options?: ResolveValuesOptions
+): Promise<any> {
+    const { protocol, key, path } = parseProtocolRef(value);
+
+    const handler = protocols[protocol];
+    if (!handler) return value;
+
+    const resolved = await handler(key);
+
+    if (path) {
+        return getValue(path, resolved, options);
+    }
+    return resolved;
+}
+
+/**
+ * Resolve path strings and protocol references within an array (async).
+ */
+async function resolveArray(
+    arr: any[],
+    source: any,
+    protocols: ProtocolHandlers | undefined,
+    options?: ResolveValuesOptions
+): Promise<any[]> {
+    const result: any[] = [];
+    for (const item of arr) {
+        if (typeof item === 'string') {
+            if (protocols && hasProtocol(item)) {
+                result.push(await resolveProtocolValue(item, protocols, options));
+            } else {
+                result.push(getValue(item, source, options));
+            }
+        } else if (Array.isArray(item)) {
+            result.push(await resolveArray(item, source, protocols, options));
+        } else if (item && typeof item === 'object') {
+            if (isPlainObject(item)) {
+                result.push(options?.protocols ? await resolveValues(item, source, options) : getValues(item, source, options));
+            } else {
+                result.push(item);
+            }
+        } else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+
+/**
+ * Async resolve RHS path strings in a pattern object against a source object.
+ *
+ * Supports async protocol handlers (e.g., fetch, IndexedDB).
+ * For synchronous-only patterns, use `getValues` from 'assign-gingerly/getValues.js' instead.
+ *
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param source - Object to resolve paths against
+ * @param options - Optional withMethods, aka, and protocol handlers
+ * @returns New object with path strings replaced by resolved values
+ */
+export async function resolveValues(
+    pattern: Record<string, any>,
+    source: any,
+    options?: ResolveValuesOptions
+): Promise<Record<string, any>> {
+    const protocols = options?.protocols;
+
+    const result: Record<string, any> = {};
+    for (const [key, value] of Object.entries(pattern)) {
+        if (typeof value === 'string') {
+            if (protocols && hasProtocol(value)) {
+                result[key] = await resolveProtocolValue(value, protocols, options);
+            } else {
+                result[key] = getValue(value, source, options);
+            }
+        } else if (Array.isArray(value)) {
+            result[key] = await resolveArray(value, source, protocols, options);
+        } else if (typeof value === 'object' && value !== null) {
+            if (isPlainObject(value)) {
+                result[key] = options?.protocols ? await resolveValues(value, source, options) : getValues(value, source, options);
+            } else {
+                result[key] = value;
+            }
+        } else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

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

@@ -72,6 +72,8 @@ export interface EnhancementConfig<T = any, Obj = Element> extends EnhancementCo
    * Calls assignFeatures(spawn, features) automatically on registration.
    */
   features?: FeatureConfigsMap;
+
+  customData?: any;
     
 }
 
@@ -406,7 +408,7 @@ export interface AssignFromOptions {
   from: any;
 
   /** Protocol handlers (sync or async) */
-  protocols?: Record<string, (key: string) => any | Promise<any>>;
+  protocols?: ProtocolHandlers;
 
   /** Method names to call during path evaluation (append `|` to a path segment for a zero-argument call) */
   withMethods?: string[] | Set<string>;
@@ -480,6 +482,37 @@ export interface AssignFromOptions {
   [key: string]: any;
 }
 
+/**
+ * A protocol handler resolves the key portion of a protocol-prefixed value
+ * (the text between `://` and the first `?.`) to a value. May be sync or async.
+ */
+export type ProtocolHandler = (key: string) => any | Promise<any>;
+
+/**
+ * A synchronous-only protocol handler, as accepted by getValues / getValue /
+ * assignFrom. For handlers that may return a Promise, use ProtocolHandler.
+ */
+export type SyncProtocolHandler = (key: string) => any;
+
+/** Map of protocol name (the text before `://`) to a handler (sync or async). */
+export type ProtocolHandlers = Record<string, ProtocolHandler>;
+
+/** Map of protocol name to a synchronous handler. */
+export type SyncProtocolHandlers = Record<string, SyncProtocolHandler>;
+
+/**
+ * The outer grammar of a protocol-prefixed value string,
+ * `‹protocol›://‹key›?.‹path›`, as produced by `parseProtocolRef`.
+ */
+export interface ParsedProtocolRef {
+    /** Text before `://`; `''` when the value contains no `://`. */
+    protocol: string;
+    /** Text between `://` and the first `?.` (or the end of the string). */
+    key: string;
+    /** Text from the first `?.` onward (always starts with `?.`), or `null`. */
+    path: string | null;
+}
+
 /**
  * Options for synchronous value resolution (getValues / getValue).
  * Extends IAssignGingerlyOptions with synchronous protocol handlers.
@@ -507,7 +540,7 @@ export interface GetValuesOptions extends IAssignGingerlyOptions {
    *     localStorage: (key) => JSON.parse(localStorage.getItem(key) || 'null')
    * }
    */
-  protocols?: Record<string, (key: string) => any>;
+  protocols?: SyncProtocolHandlers;
 }
 
 /**
@@ -530,7 +563,7 @@ export interface ResolveValuesOptions extends IAssignGingerlyOptions {
    * 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>>;
+  protocols?: ProtocolHandlers;
 }
 
 /**