assign-gingerly 0.0.38 → 0.0.39

package/README.md

@@ -33,13 +33,9 @@ On top of that, this polyfill package builds on the newly minted Custom Element
 
 2.  [itemscopeRegistry for Itemscope Managers](#itemscoperegistry) to automatically associate a function prototype or class instance with the itemscope attribute of an HTMLElement.
 
-3.  Default Support For Not Replacing one object with another if it is a subclass. [TODO]
+3.  [featuresRegistry for Custom Element Features](#custom-element-features) to support dependency injection of composable feature classes or function prototypes onto custom element prototypes via lazy getters.
 
-4.  Custom Element Features [TODO]
-
-So in our view this package helps fill the void left by not supporting the "is" attribute for built-in elements (but is not a complete solution, just a critical building block).  Mount-observer, mount-observer-script-element, and custom enhancements builds on top of the critical role that assign-gingerly plays.
-
-5.  Iterator upgrade support [TODO] -- limited to ish?
+So in our view this package helps fill the void left by not supporting the "is" attribute for built-in elements (but is not a complete solution, just a critical building block).  Mount-observer and custom enhancements builds on top of the critical role that assign-gingerly plays.
 
 Anyway, let's start out detailing the more innocent features of this package / polyfill.
 
@@ -54,11 +50,11 @@ assign-gingerly adds support for:
 1.  Carefully merging in nested properties.
 2.  Dependency injection based on a mapping protocol.
 
-and 
+The second fundamental utility function is:
 
 ## assignTentatively
 
-assignTentatively provides a far more limited subset of functionality compared to assignGingerly.   The tradeoff is that assignTentatively can do something important assignGingerly cannot do -- be "reversed". This can be quite useful for some scenarios.  Think of how css "turns on" visual effects while conditions are met, then reverts to how things were before the conditions were met when needed without as if nothing happened.  Another example is allowing user edits to be rolled back as they repeatedly hit "ctrl+z".
+assignTentatively provides a far more limited subset of functionality compared to assignGingerly.   The tradeoff is that assignTentatively can do something important assignGingerly cannot do -- be "reversed". This can be quite useful for some scenarios.  Think of how css "turns on" visual effects while conditions are met, then reverts to how things were before the conditions were met when the conditions are no longer met, as if nothing happened.  Another example is allowing user edits to be rolled back as they repeatedly hit "ctrl+z".
 
 ## Example 1 - assignGingerly as a "superset" of Object.assign:
 
@@ -110,7 +106,7 @@ console.log(obj);
 
 When the right hand side of an expression is an object, assignGingerly behavior depends on the context:
 - For **nested paths** (starting with `?.`): recursively merges into nested objects, creating them if needed
-- For **plain keys**: performs simple assignment (like `Object.assign`), unless the target property is readonly or an accessor (see Examples 3a and 3b below)
+- For **plain keys**: performs simple assignment (like `Object.assign`), unless the target property is readonly, an accessor, or the current value's class defines [`static assignTo`](#custom-assignment-with-static-assignto-protocol) (see Examples 3a, 3b, and the assignTo section below)
 
 Of course, just as Object.assign led to object spread notation, assignGingerly could lead to some sort of deep structural JavaScript syntax, but that is outside the scope of this polyfill package.
 
@@ -227,7 +223,7 @@ assignGingerly(config, {
 console.log(config.settings.theme); // 'dark'
 ```
 
-## Example 3b - Class Instances Are Replaced
+## Example 3b - Class Instances Are Normally Replaced
 
 Unlike readonly/accessor properties, class instances on writable properties are **replaced** by simple assignment, just like plain objects. This allows you to swap one object for another without unexpected merging:
 
@@ -257,10 +253,31 @@ console.log(obj.clone === element); // true - replaced, not merged
 
 In real-world use cases, you often need to replace one object with another of a completely different type. For example, replacing a cloned DocumentFragment with the actual web component element. Automatic merging would corrupt the target by mixing properties from incompatible types.
 
+**Exception: classes with `static assignTo`**
+
+If the current value is an instance of a class that defines [`static assignTo`](#custom-assignment-with-static-assignto-protocol), that method is called instead of replacing. This allows classes to opt into custom assignment behavior (e.g., reactive models, validated records, iterable collections with private lists):
+
+```TypeScript
+class TodoList {
+    #items = [];
+    *[Symbol.iterator]() { yield* this.#items; }
+    static assignTo(instance, rhs) {
+        if (Array.isArray(rhs)) instance.#items = [...rhs];
+        else Object.assign(instance, rhs);
+    }
+}
+
+const app = { todos: new TodoList() };
+assignGingerly(app, { todos: ['Buy milk', 'Walk dog'] });
+// TodoList.assignTo is called — replaces internal list, not the instance
+console.log([...app.todos]); // ['Buy milk', 'Walk dog']
+console.log(app.todos instanceof TodoList); // true — instance preserved
+```
+
 **Readonly/accessor properties are still merged:**
 
 The distinction is clear:
-- **Writable data properties**: always replaced (whether holding a plain object or class instance)
+- **Writable data properties**: replaced (unless class defines `static assignTo`)
 - **Readonly data properties** (`writable: false`): merged into
 - **Getter-only accessor properties** (no setter): merged into
 - **Getter+setter accessor properties** (e.g., `style`): setter runs with the value as-is
@@ -3325,6 +3342,232 @@ assignFrom(target, {
 
 For full documentation, see [docs/assignFrom.md](docs/assignFrom.md).
 
+## Custom Assignment with `static assignTo` Protocol
+
+Classes can opt into custom assignment behavior by defining a `static assignTo` method. When `assignGingerly` encounters a property whose current value is an instance of such a class, it delegates the assignment to `assignTo` instead of performing the default merge/replace logic.
+
+```JavaScript
+class ReactiveModel {
+    #data = {};
+    #listeners = [];
+
+    static assignTo(instance, rhs, parent, key) {
+        // Custom merge: trigger reactive notifications
+        for (const [k, v] of Object.entries(rhs)) {
+            instance.#data[k] = v;
+            instance.#listeners.forEach(fn => fn(k, v));
+        }
+    }
+
+    get(prop) { return this.#data[prop]; }
+    onChange(fn) { this.#listeners.push(fn); }
+}
+```
+
+### How it works
+
+When `assignGingerly` is about to assign a value to a property, it checks if the property's current value is an object whose constructor defines `static assignTo`. If so, it calls `assignTo` instead of the default behavior:
+
+```JavaScript
+const obj = { model: new ReactiveModel() };
+
+assignGingerly(obj, { model: { name: 'Alice', age: 30 } });
+// Instead of replacing or merging, calls:
+// ReactiveModel.assignTo(obj.model, { name: 'Alice', age: 30 }, obj, 'model')
+```
+
+### Parameters
+
+```TypeScript
+class MyClass {
+    static assignTo(
+        instance: MyClass,  // The current value (instance of this class)
+        rhs: any,           // The value being assigned (from the RHS of assignGingerly)
+        parent: any,        // The parent object containing the property
+        key: string|symbol  // The property key being assigned to
+    ) { ... }
+}
+```
+
+The `parent` and `key` parameters allow `assignTo` to replace the instance entirely if needed (e.g., for immutable patterns):
+
+```JavaScript
+class ImmutableState {
+    #data;
+    constructor(data) { this.#data = Object.freeze({ ...data }); }
+    
+    static assignTo(instance, rhs, parent, key) {
+        // Replace with a new immutable instance
+        parent[key] = new ImmutableState({ ...instance.#data, ...rhs });
+    }
+}
+```
+
+### Use case: Iterable classes with private lists
+
+A class that is iterable over a private list can use `assignTo` to handle array assignment (replacing the list) vs object assignment (merging properties):
+
+```JavaScript
+class TodoList {
+    #items = [];
+    
+    *[Symbol.iterator]() { yield* this.#items; }
+    
+    static assignTo(instance, rhs) {
+        if (Array.isArray(rhs)) {
+            // Replace the private list
+            instance.#items = [...rhs];
+        } else if (typeof rhs === 'object' && rhs !== null) {
+            // Merge properties normally
+            Object.assign(instance, rhs);
+        }
+    }
+}
+
+const app = { todos: new TodoList() };
+
+// Assign an array — replaces the internal list
+assignGingerly(app, { todos: ['Buy milk', 'Walk dog'] });
+console.log([...app.todos]); // ['Buy milk', 'Walk dog']
+
+// Assign an object — merges properties
+assignGingerly(app, { todos: { title: 'My Todos' } });
+console.log(app.todos.title); // 'My Todos'
+console.log([...app.todos]); // ['Buy milk', 'Walk dog'] (list unchanged)
+```
+
+### Use case: Validation on assignment
+
+```JavaScript
+class TypedRecord {
+    static schema = { name: 'string', age: 'number' };
+    
+    static assignTo(instance, rhs) {
+        for (const [k, v] of Object.entries(rhs)) {
+            const expected = TypedRecord.schema[k];
+            if (expected && typeof v !== expected) {
+                throw new TypeError(`${k} must be ${expected}, got ${typeof v}`);
+            }
+            instance[k] = v;
+        }
+    }
+}
+```
+
+### Private field access
+
+Because `assignTo` is a static method defined in the class body, it has full access to `#private` fields:
+
+```JavaScript
+class SecureStore {
+    #secrets = {};
+    
+    static assignTo(instance, rhs) {
+        // Can read/write private fields
+        for (const [k, v] of Object.entries(rhs)) {
+            instance.#secrets[k] = encrypt(v);
+        }
+    }
+}
+```
+
+### Safety
+
+Only classes that explicitly define their own `assignTo` are affected. The check uses `Object.hasOwn(constructor, 'assignTo')` to prevent accidental inheritance — plain objects, arrays, and classes without `assignTo` use the default assignGingerly behavior.
+
+## Property Forwarding with `installForwarding`
+
+`installForwarding` installs getter/setter pairs on a class prototype that delegate to nested paths on the instance. This is useful for exposing deeply nested properties at the top level of an object — particularly for custom elements that delegate behavior to compositional feature classes.
+
+```JavaScript
+import { installForwarding } from 'assign-gingerly/installForwarding.js';
+```
+
+### Basic usage
+
+```JavaScript
+class ClubMember extends HTMLElement {
+    static propLinks = {
+        'command': '?.behaviors?.commandBehavior?.command',
+        'commandForElement': '?.behaviors?.commandBehavior?.commandForElement'
+    };
+}
+
+installForwarding(ClubMember);
+
+const el = document.createElement('club-member');
+el.command = 'toggle';
+// Equivalent to: assignGingerly(el, { '?.behaviors?.commandBehavior?.command': 'toggle' })
+
+console.log(el.command);
+// Equivalent to: resolveValue('?.behaviors?.commandBehavior?.command', el)
+```
+
+### How it works
+
+1. Reads `static propLinks` from the constructor — a map of top-level property names to `?.`-delimited path strings.
+2. For each entry, installs a getter/setter pair on the prototype:
+   - **Getter**: uses `resolveValue` to walk the path with optional chaining semantics. Returns `undefined` if any segment is nullish.
+   - **Setter**: uses `assignGingerly` to assign the value at the path, creating intermediate objects as needed.
+3. Validates that forwarded property names don't already exist on the prototype (throws if they do).
+
+### With methods and aliases
+
+Because the getter uses `resolveValue` and the setter uses `assignGingerly`, you get full access to `withMethods` and `aka` via the options parameter:
+
+```JavaScript
+class MyComponent extends HTMLElement {
+    static propLinks = {
+        'username': '?.q?.#user-input?.value'
+    };
+}
+
+installForwarding(MyComponent, {
+    withMethods: ['querySelector'],
+    aka: { 'q': 'querySelector' }
+});
+
+// el.username now resolves:
+// el.querySelector('#user-input').value
+```
+
+### Use with Custom Element Features
+
+A common pattern is forwarding top-level properties to feature instances:
+
+```JavaScript
+class CustomButton extends HTMLElement {
+    static supportedFeatures = {
+        commandBehavior: { fallbackSpawn: CommandFeatureImpl }
+    };
+    static propLinks = {
+        'command': '?.commandBehavior?.command',
+        'commandForElement': '?.commandBehavior?.commandForElement'
+    };
+}
+
+customElements.assignFeatures(CustomButton, {
+    commandBehavior: { spawn: CommandFeatureImpl }
+});
+installForwarding(CustomButton);
+
+// Now el.command delegates to el.commandBehavior.command
+// The feature getter triggers lazy instantiation automatically
+```
+
+### Error conditions
+
+| Condition | Error |
+|-----------|-------|
+| Property already exists on prototype | `"already exists on Constructor.prototype"` |
+| Path doesn't start with `?.` | `"path must start with '?.'"` |
+
+### Performance
+
+- Paths are cached after first parse — repeated getter/setter calls don't re-split strings.
+- The getter uses `resolveValue` (a lightweight single-path resolver with caching).
+- The setter uses `assignGingerly` which also benefits from path caching.
+
 ## Itemscope Managers (Chrome 146+)
 
 Itemscope Managers provide a way to manage DOM fragments and their associated data/view models for elements with the `itemscope` attribute. This feature enables frameworks and libraries to manage light children of web components, DOM fragments from looping constructs, and scenarios where custom element wrapping is not feasible.
@@ -3733,3 +3976,646 @@ ItemScope Managers follow these design principles:
 
 This design ensures backward compatibility while providing powerful new capabilities for managing DOM fragments.
 
+
+## Custom Element Features
+
+Custom Element Features provide dependency injection for custom elements (and other objects). A custom element author declares which feature "slots" their class supports, and consumers inject implementations into those slots. Features are lazily instantiated on first property access.
+
+To use features, import the module directly — it is independent of `object-extension.js`:
+
+```JavaScript
+import 'assign-gingerly/assignFeatures.js';
+```
+
+This self-installs `featuresRegistry` and `assignFeatures()` on `CustomElementRegistry.prototype`. It does not require or pull in the enhancement/itemscope registries.
+
+This is useful for:
+
+- **Decomposing large components** into smaller, testable units (e.g., a photo-taking feature, a badge-making feature).
+- **Mocking in tests** — swap real implementations for test doubles without subclassing.
+- **Reusing behaviors** across different custom elements without mixins.
+- **Lazy loading** — feature code isn't executed until the property is actually accessed.
+
+### How it works
+
+1. The custom element declares `static supportedFeatures` — an opt-in map of feature keys and their configuration.
+2. A consumer calls `customElements.assignFeatures(Constructor, injections)` to register implementations.
+3. Lazy getter-only properties are installed on the constructor's prototype.
+4. On first access, the getter spawns the feature instance, validates it (optionally), caches it, and returns it.
+5. Because the property is getter-only (no setter), `assignGingerly` automatically merges into the spawned instance when assigning object values to that property.
+
+### Basic example
+
+```JavaScript
+import 'assign-gingerly/assignFeatures.js';
+
+// 1. Define a feature implementation
+class PhotoTakerImpl {
+    constructor(hostElement) {
+        this.host = hostElement;
+    }
+    takePicture() {
+        return `📸 taken by ${this.host.localName}`;
+    }
+    someProp = 'default';
+}
+
+// 2. Define the custom element with supported feature slots
+class ClubMember extends HTMLElement {
+    static supportedFeatures = {
+        photoTaker: {
+            // Used if no spawn is provided in assignFeatures
+            fallbackSpawn: PhotoTakerImpl,
+            // Optional runtime check on the spawned instance
+            validateShape(instance) {
+                return typeof instance.takePicture === 'function';
+            }
+        }
+    }
+}
+
+// 3. Inject features before define (getters must be on prototype before instances exist)
+customElements.assignFeatures(ClubMember, {
+    photoTaker: {
+        spawn: PhotoTakerImpl
+    }
+});
+
+customElements.define('club-member', ClubMember);
+
+// 4. Use it — lazy instantiation on first access
+const el = document.createElement('club-member');
+console.log(el.photoTaker.takePicture()); // '📸 taken by club-member'
+
+// 5. assignGingerly merges into the feature instance automatically
+el.assignGingerly({
+    photoTaker: { someProp: 'hello' }
+});
+console.log(el.photoTaker.someProp); // 'hello'
+```
+
+### Using fallbackSpawn (no explicit injection needed)
+
+If `fallbackSpawn` is provided in `supportedFeatures`, you can call `assignFeatures` with an empty spawn — or even just `{}` — and the fallback will be used:
+
+```JavaScript
+class ClubMember extends HTMLElement {
+    static supportedFeatures = {
+        photoTaker: {
+            fallbackSpawn: PhotoTakerImpl
+        }
+    }
+}
+
+customElements.define('club-member', ClubMember);
+
+// No spawn provided — will use fallbackSpawn
+customElements.assignFeatures(ClubMember, {
+    photoTaker: {}
+});
+
+const el = document.createElement('club-member');
+console.log(el.photoTaker.takePicture()); // works via fallbackSpawn
+```
+
+### Testing with mocks
+
+```JavaScript
+class PhotoTakerMock {
+    constructor(hostElement) {
+        this.host = hostElement;
+        this.calls = [];
+    }
+    takePicture() {
+        this.calls.push('takePicture');
+        return 'mock click';
+    }
+}
+
+// In test setup:
+customElements.assignFeatures(ClubMember, {
+    photoTaker: { spawn: PhotoTakerMock }
+});
+
+const el = document.createElement('club-member');
+el.photoTaker.takePicture();
+console.log(el.photoTaker.calls); // ['takePicture']
+```
+
+### Multiple features
+
+```JavaScript
+class BadgeMakerImpl {
+    constructor(hostElement) {
+        this.host = hostElement;
+    }
+    makeBadge(name) {
+        return `🎫 ${name}`;
+    }
+}
+
+class ClubMember extends HTMLElement {
+    static supportedFeatures = {
+        photoTaker: { fallbackSpawn: PhotoTakerImpl },
+        badgeMaker: { fallbackSpawn: BadgeMakerImpl }
+    }
+}
+
+customElements.define('club-member', ClubMember);
+
+// Can assign all at once
+customElements.assignFeatures(ClubMember, {
+    photoTaker: { spawn: PhotoTakerImpl },
+    badgeMaker: { spawn: BadgeMakerImpl }
+});
+
+// Or incrementally (different keys each call)
+// customElements.assignFeatures(ClubMember, { photoTaker: { spawn: PhotoTakerImpl } });
+// customElements.assignFeatures(ClubMember, { badgeMaker: { spawn: BadgeMakerImpl } });
+```
+
+### Validation
+
+The `validateShape` callback runs after instantiation. If it returns `false`, an error is thrown:
+
+```JavaScript
+class ClubMember extends HTMLElement {
+    static supportedFeatures = {
+        photoTaker: {
+            fallbackSpawn: PhotoTakerImpl,
+            validateShape(instance) {
+                if (typeof instance.takePicture !== 'function') return false;
+                if (typeof instance.someProp !== 'string') return false;
+                return true;
+            }
+        }
+    }
+}
+```
+
+### Error conditions
+
+`assignFeatures` throws in these cases:
+
+| Condition | Error |
+|-----------|-------|
+| Constructor has no `static supportedFeatures` | `"does not define static supportedFeatures"` |
+| Key not declared in `supportedFeatures` | `"is not declared in Constructor.supportedFeatures"` |
+| Property already exists on prototype | `"already exists on Constructor.prototype"` |
+| Same key assigned twice for same constructor | `"has already been assigned for Constructor"` |
+| No `spawn` provided and no `fallbackSpawn` | `"no spawn implementation found"` (at access time) |
+| `validateShape` returns false | `"failed shape validation"` (at access time) |
+
+### Integration with assignGingerly
+
+Because `assignFeatures` installs **getter-only** properties (no setter), assignGingerly's existing readonly property detection kicks in automatically:
+
+```JavaScript
+// assignGingerly detects photoTaker is getter-only
+// → reads the getter (spawning the instance if needed)
+// → recursively merges the RHS object into the instance
+el.assignGingerly({
+    photoTaker: { someProp: 'updated' }
+});
+```
+
+This means no special handling is needed in assignGingerly for features — it "just works."
+
+### Scoped registry support
+
+The lazy getter uses `(this.customElementRegistry || customElements)` to resolve the features registry. This means:
+
+- On Chrome 146+ (and future browsers with scoped registries), the element's scoped `customElementRegistry` is used.
+- On older browsers, it falls back to the global `customElements`.
+
+### Not limited to custom elements
+
+While designed with custom elements in mind, `assignFeatures` works with any constructor whose instances will have a `customElementRegistry` property (or where the global `customElements` fallback is acceptable). This includes element enhancement classes that set `this.customElementRegistry` from the element they enhance.
+
+### API reference
+
+```TypeScript
+// On CustomElementRegistry.prototype:
+customElements.assignFeatures(
+    ctr: Function,           // The class constructor
+    features: FeatureConfigsMap  // Map of feature keys to FeatureConfig
+): void;
+
+// FeatureConfig — passed to assignFeatures for each feature key:
+interface FeatureConfig {
+    // Synchronous constructor or async function returning one
+    spawn?: 
+        | { new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }
+        | (() => Promise<{ new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }>);
+    
+    // Attribute patterns for parsing element attributes into initVals
+    withAttrs?: AttrPatterns<any>;
+    
+    // Pass-through field for custom configuration (accessible via ctx.injection.customData)
+    customData?: any;
+}
+
+// SupportedFeatureConfig — declared on the class via static supportedFeatures:
+interface SupportedFeatureConfig {
+    fallbackSpawn?: /* same type as FeatureConfig.spawn */;
+    validateShape?: (instance: any) => boolean;
+    lifecycleKeys?: true | { whenFeatureReady?: string };
+    getSharedContext?: (instance: any) => any;
+}
+
+// Context passed to feature constructors:
+interface FeatureSpawnContext {
+    key: string;                        // The feature key (e.g., 'photoTaker')
+    optIn: SupportedFeatureConfig;      // The config from static supportedFeatures
+    injection: FeatureConfig;           // The config from assignFeatures()
+    featuresRegistry: FeaturesRegistry; // The registry reference
+    shared?: any;                       // From getSharedContext (if defined)
+}
+```
+
+### Constructor signature
+
+Feature classes receive three arguments:
+
+```JavaScript
+class MyFeature {
+    constructor(hostElement, ctx, initVals) {
+        // hostElement: the element instance that owns this feature
+        // ctx: { key, optIn, injection, featuresRegistry, shared }
+        // initVals: any pre-set value captured before the feature was spawned (or undefined)
+        if (initVals) {
+            Object.assign(this, initVals);
+        }
+        // Access shared context (e.g., ElementInternals)
+        if (ctx.shared) {
+            this.internals = ctx.shared.internals;
+        }
+        // Access custom data from the FeatureConfig
+        if (ctx.injection.customData) {
+            this.config = ctx.injection.customData;
+        }
+    }
+}
+```
+
+### Pre-upgrade property capture with `captureFeatureInitVals`
+
+When a custom element exists in the DOM before `customElements.define()` is called, properties may be set on it directly (e.g., by a framework or server-rendered HTML hydration). After the element upgrades, these own-properties shadow the prototype getters installed by `assignFeatures`, preventing the lazy spawn mechanism from working.
+
+`captureFeatureInitVals` solves this by capturing and deleting those own-properties in the constructor, storing them so the getter can pass them as `initVals` when the feature is first accessed.
+
+**Usage:**
+
+```JavaScript
+import { captureFeatureInitVals } from 'assign-gingerly/assignFeatures.js';
+
+class ClubMember extends HTMLElement {
+    static supportedFeatures = {
+        photoTaker: { fallbackSpawn: PhotoTakerImpl }
+    }
+
+    constructor() {
+        super();
+        captureFeatureInitVals(this);
+    }
+}
+```
+
+**What it does:**
+
+1. Iterates over the keys in `static supportedFeatures`.
+2. For each key, checks if the instance has an own-property with that name (`Object.hasOwn`).
+3. If found: captures the value, deletes the own-property, and stores the value internally so the getter can retrieve it as `initVals` when the feature is first accessed.
+
+**When to use it:**
+
+- Always include it in the constructor if your element might exist in the DOM before `define()` is called (which is common with server-rendered HTML or lazy-loaded component definitions).
+- It's safe to call even when no own-properties exist — it simply does nothing.
+- It's a one-liner with no performance cost when there are no pre-set properties.
+
+**The full pre-upgrade flow:**
+
+```JavaScript
+// 1. Element exists in DOM before define (unknown element)
+const el = document.createElement('club-member');
+document.body.appendChild(el);
+
+// 2. Framework or hydration sets properties
+el.photoTaker = { someProp: 'hello', count: 42 };
+
+// 3. Later, the component definition loads
+customElements.assignFeatures(ClubMember, {
+    photoTaker: { spawn: PhotoTakerImpl }
+});
+customElements.define('club-member', ClubMember);
+// → constructor runs, captureFeatureInitVals captures el.photoTaker value
+
+// 4. First access spawns with initVals
+console.log(el.photoTaker.someProp); // 'hello'
+console.log(el.photoTaker.count);    // 42
+```
+
+**Important ordering:** Call `assignFeatures` before `customElements.define()`. The getters must be on the prototype before any instances are created or upgraded.
+
+### Async spawn (lazy-loading features)
+
+Feature implementations can be loaded asynchronously. Instead of providing a constructor directly, provide a function that returns a Promise resolving to a constructor:
+
+```JavaScript
+customElements.assignFeatures(ClubMember, {
+    photoTaker: {
+        spawn: () => import('./photo-taker.js').then(m => m.PhotoTakerImpl)
+    }
+});
+```
+
+**How it works:**
+
+1. On first access, the getter detects that `spawn` is an async function (arrow function or `async function`).
+2. It creates a `{}` placeholder object, stores it, and returns it immediately.
+3. In the background, the async function is called and awaited.
+4. When the Promise resolves, the real class is instantiated with the placeholder as `initVals` (so any properties merged into the placeholder are passed to the constructor).
+5. The placeholder is replaced in storage with the real instance.
+6. Subsequent getter accesses return the real instance.
+
+**During the loading window:**
+
+```JavaScript
+const el = document.createElement('club-member');
+
+// First access — returns placeholder {}
+assignGingerly(el, { photoTaker: { someProp: 'hello' } });
+// Merges into the placeholder: { someProp: 'hello' }
+
+// Later, after async resolution:
+console.log(el.photoTaker.someProp); // 'hello' — now on the real instance
+console.log(el.photoTaker instanceof PhotoTakerImpl); // true
+```
+
+**Error handling:**
+
+If the async import fails, the error is stored. The next getter access throws with the original error attached:
+
+```JavaScript
+try {
+    el.photoTaker;
+} catch (e) {
+    console.log(e.message);     // 'assignFeatures: async spawn for "photoTaker" failed: ...'
+    console.log(e.placeholder); // the accumulated placeholder object
+    console.log(e.cause);       // the original import/network error
+}
+```
+
+**Detection heuristic:** A function is treated as an async spawner if it's an `AsyncFunction` or has no `.prototype` (arrow functions). Classes and `function` declarations (which have `.prototype`) are treated as synchronous constructors.
+
+### `whenFeatureReady` lifecycle method
+
+For code that needs to wait for an async feature to be fully instantiated, configure `lifecycleKeys` on the supported feature:
+
+```JavaScript
+class ClubMember extends HTMLElement {
+    static supportedFeatures = {
+        photoTaker: {
+            fallbackSpawn: PhotoTakerImpl,
+            lifecycleKeys: true  // installs 'whenFeatureReady' method
+        }
+    };
+    static featuresConfig = {
+        lifecycleKeys: true
+    }
+}
+
+customElements.assignFeatures(ClubMember, {
+    photoTaker: { spawn: () => import('./photo-taker.js').then(m => m.PhotoTakerImpl) }
+});
+
+const el = document.createElement('club-member');
+
+// Wait for the async feature to be ready
+const photoTaker = await el.whenFeatureReady('photoTaker');
+console.log(photoTaker instanceof PhotoTakerImpl); // true
+```
+
+**Configuration:**
+
+- `lifecycleKeys: true` — installs a method named `'whenFeatureReady'` on the prototype.
+- `lifecycleKeys: { whenFeatureReady: 'awaitFeature' }` — custom method name (in case `whenFeatureReady` conflicts with an existing method).
+
+**Behavior:**
+
+- For **synchronous** features: returns `Promise.resolve(instance)` immediately.
+- For **async** features: returns a Promise that resolves when the async spawn completes and the real instance is stored.
+- The method triggers the getter (starting async resolution if it hasn't started yet).
+
+### Attribute parsing with `withAttrs`
+
+Features can declare attribute patterns to parse element attributes into `initVals`:
+
+```JavaScript
+customElements.assignFeatures(ClubMember, {
+    photoTaker: {
+        spawn: PhotoTakerImpl,
+        withAttrs: {
+            base: 'photo',
+            resolution: '${base}-resolution',
+            format: '${base}-format'
+        }
+    }
+});
+```
+
+```HTML
+<club-member photo-resolution="4k" photo-format="png"></club-member>
+```
+
+This parses into `initVals = { resolution: '4k', format: 'png' }`. By default, non-underscore keys are assumed to be strings with `mapsTo` equal to the key name. The `_key` form is only needed to override defaults (e.g., parse as Number, map to a different property name, use a custom parser):
+
+```JavaScript
+withAttrs: {
+    base: 'photo',
+    resolution: '${base}-resolution',
+    // Override: parse as Number instead of String
+    _resolution: { instanceOf: 'Number', mapsTo: 'resolutionPx' },
+    format: '${base}-format'
+    // No _format needed — defaults to String, mapsTo: 'format'
+}
+```
+
+**Merge priority (lowest to highest):**
+1. Attribute-parsed values (`withAttrs`)
+2. Programmatic `initVals` (from `captureFeatureInitVals` or placeholder accumulation)
+
+Attributes are always unprefixed for features (no `enh-` prefix). The same `parseWithAttrs` function used by enhancements is reused here.
+
+### Shared context with `getSharedContext`
+
+Features often need access to private data from the host element (e.g., `ElementInternals`). The `getSharedContext` callback on `supportedFeatures` provides this:
+
+```JavaScript
+class MyButton extends HTMLElement {
+    #internals;
+    #privateState = { clickCount: 0 };
+
+    static supportedFeatures = {
+        commandBehavior: {
+            fallbackSpawn: CommandFeatureImpl,
+            getSharedContext(instance) {
+                // This callback is in the class scope — it can access #private fields
+                return {
+                    internals: instance.#internals,
+                    state: instance.#privateState
+                };
+            }
+        }
+    }
+
+    constructor() {
+        super();
+        this.#internals = this.attachInternals();
+    }
+}
+
+class CommandFeatureImpl {
+    constructor(host, ctx, initVals) {
+        // ctx.shared contains what getSharedContext returned
+        this.internals = ctx.shared.internals;
+        this.state = ctx.shared.state;
+    }
+}
+```
+
+**Key points:**
+- `getSharedContext` is called at spawn time (both sync and async paths).
+- It's per-feature — different features can receive different slices of private state.
+- It's opt-in — if not defined, `ctx.shared` is `undefined`.
+- Because it's defined in the class body, it has access to `#private` fields of instances of that class.
+
+### Custom data
+
+The `customData` field on `FeatureConfig` is a pass-through for arbitrary configuration:
+
+```JavaScript
+customElements.assignFeatures(ClubMember, {
+    photoTaker: {
+        spawn: PhotoTakerImpl,
+        customData: {
+            maxResolution: '8k',
+            allowedFormats: ['png', 'jpg', 'webp']
+        }
+    }
+});
+
+class PhotoTakerImpl {
+    constructor(host, ctx, initVals) {
+        // Access custom data
+        const { maxResolution, allowedFormats } = ctx.injection.customData;
+    }
+}
+```
+
+### `withAsyncMethods` in assignGingerly
+
+assignGingerly supports async method calls in path expressions via the `withAsyncMethods` option. This is particularly useful with `whenFeatureReady`:
+
+```JavaScript
+import assignGingerly from 'assign-gingerly/assignGingerly.js';
+
+assignGingerly(el, {
+    '?.whenFeatureReady?.photoTaker?.someProp': 'hello'
+}, { withAsyncMethods: ['whenFeatureReady'] });
+// Equivalent to: (await el.whenFeatureReady('photoTaker')).someProp = 'hello'
+```
+
+**How it works:**
+
+- `assignGingerly` remains synchronous — async paths are **fire-and-forget**.
+- When a path segment matches a name in `withAsyncMethods`, the method is called and its return value is awaited before continuing the chain.
+- The async path evaluator (`evaluatePathWithAsyncMethods`) is dynamically imported only when needed, so there's no cost to the synchronous path.
+- `withAsyncMethods` works together with `withMethods` — you can mix sync and async methods in the same path.
+
+```JavaScript
+assignGingerly(el, {
+    '?.whenFeatureReady?.photoTaker?.classList?.add': 'active'
+}, { 
+    withAsyncMethods: ['whenFeatureReady'],
+    withMethods: ['add']
+});
+// (await el.whenFeatureReady('photoTaker')).classList.add('active')
+```
+
+**Note:** Interaction with `@each` and `@eachTime` is not yet supported for async methods.
+
+### Nested features with `PropertyBag`
+
+`PropertyBag` is a base class for creating nested feature containers. It groups related features under a single namespace property, enabling hierarchical composition:
+
+```JavaScript
+import { PropertyBag, assignFeatures } from 'assign-gingerly/assignFeatures.js';
+import { installForwarding } from 'assign-gingerly/installForwarding.js';
+
+// 1. Define a feature container by subclassing PropertyBag
+class ClubMemberBehaviors extends PropertyBag {
+    static supportedFeatures = {
+        commandBehavior: { fallbackSpawn: CommandFeatureImpl },
+        ariaBehavior: { fallbackSpawn: AriaFeatureImpl }
+    }
+}
+
+// 2. Define the custom element with the container as a feature
+class ClubMember extends HTMLElement {
+    static supportedFeatures = {
+        behaviors: { fallbackSpawn: ClubMemberBehaviors }
+    }
+    // Forward nested properties to the top level
+    static propLinks = {
+        'command': '?.behaviors?.commandBehavior?.command',
+        'commandForElement': '?.behaviors?.commandBehavior?.commandForElement'
+    }
+}
+
+// 3. Register features at both levels
+customElements.assignFeatures(ClubMember, {
+    behaviors: { spawn: ClubMemberBehaviors }
+});
+customElements.assignFeatures(ClubMemberBehaviors, {
+    commandBehavior: { spawn: CommandFeatureImpl },
+    ariaBehavior: { spawn: AriaFeatureImpl }
+});
+installForwarding(ClubMember);
+customElements.define('club-member', ClubMember);
+
+// 4. Use it
+const el = document.createElement('club-member');
+el.command = 'toggle';  // forwards to el.behaviors.commandBehavior.command
+el.behaviors.ariaBehavior.setRole('button');  // access nested features directly
+```
+
+**How `PropertyBag` works:**
+
+- Carries `customElementRegistry` from the host element so nested features can resolve their registries.
+- Applies `initVals` via `Object.assign` (supports pre-upgrade property capture).
+- Must be subclassed — direct instantiation throws an error.
+- Subclasses must define `static supportedFeatures` (enforced by `assignFeatures` validation).
+
+**Why subclass instead of using `PropertyBag` directly?**
+
+Each subclass declares its own `static supportedFeatures`, which:
+- Provides opt-in safety (only declared feature keys are allowed).
+- Enables TypeScript type checking on the feature slots.
+- Documents the expected shape of the container.
+
+```JavaScript
+// This throws — PropertyBag has no supportedFeatures
+customElements.assignFeatures(PropertyBag, { anything: {} }); // Error!
+
+// This works — subclass declares what's allowed
+class MyBehaviors extends PropertyBag {
+    static supportedFeatures = { anything: { fallbackSpawn: AnythingImpl } }
+}
+customElements.assignFeatures(MyBehaviors, { anything: { spawn: AnythingImpl } }); // ✓
+```
+
+### Roadmap (future phases)
+
+- **Nested features**: Support `?.path?.notation` keys directly in `assignFeatures` (without requiring `PropertyBag`).
+- **`@each` + async interaction**: Combine async methods with iteration.