assign-gingerly 0.0.22 → 0.0.24

package/README.md

@@ -23,16 +23,24 @@ One can achieve the same functionality with a little more work, and "playing nic
 
 Not only does this polyfill package allow merging data properties onto objects that are expecting them, this polyfill also provides the ability to merge *augmented behavior* onto run-time objects without sub classing all such objects of the same type. This includes the ability to spawn an instance of a class and "merge" it into the API of the original object in an elegant way that is easy to wrap one's brain around, without ever blocking access to the original object or breaking it.
 
+So we are providing a form of the ["Decorator Pattern"](https://en.wikipedia.org/wiki/Decorator_pattern) or perhaps more accurately the [Extension Object Pattern](https://swiftorial.com/swiftlessons/design-patterns/structural-patterns/extension-object-pattern) as tailored for the quirks of the web.  
 
+## Custom Registries
 
-So we are providing a form of the ["Decorator Pattern"](https://en.wikipedia.org/wiki/Decorator_pattern) or perhaps more accurately the [Extension Object Pattern](https://swiftorial.com/swiftlessons/design-patterns/structural-patterns/extension-object-pattern) as tailored for the quirks of the web.  
+On top of that, this polyfill package builds on the newly minted Custom Element Registry, adding additional sub-registries:
+
+1.  [enhancementRegistry](#enhancement-registry-addendum-to-the-custom-element-registry) object on top of the customElementRegistry object associated with all elements, to be able to lazy load object extensions on demand while avoiding namespace conflicts, and, importantly, as a basis for defining custom attributes associated with the enhancements.
 
-## Custom Enhancement Registry
+2.  [itemscopeRegistry for Itemscope Managers](#itemscoperegistry) to automatically associate a function prototype or class instance with the itemscope attribute of an HTMLElement.
 
-On top of that, this polyfill package builds on the newly minted Custom Element Registry, adding an additional EnhancementRegistry object on top of the customElementRegistry object associated with all elements, to be able to manage namespace conflicts, and, importantly, as a basis for defining custom attributes associated with the enhancements.
+3.  Default Support For Not Replacing one object with another if it is a subclass. [TODO]
+
+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?
+
 Anyway, let's start out detailing the more innocent features of this package / polyfill.
 
 The two utility functions are:
@@ -102,7 +110,220 @@ console.log(obj);
 
 When the right hand side of an expression is an object, assignGingerly is recursively applied (passing the third argument in if applicable, which will be discussed 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. 
+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.
+
+## Example 3a - Automatic Readonly Property Detection
+
+assignGingerly automatically detects readonly properties and merges into them instead of attempting to replace them. This makes working with DOM properties like `style` and `dataset` much more ergonomic:
+
+```TypeScript
+// Instead of this verbose syntax:
+const div = document.createElement('div');
+assignGingerly(div, {
+    '?.style?.height': '15px',
+    '?.style?.width': '20px'
+});
+
+// You can now use this cleaner syntax:
+assignGingerly(div, {
+    style: {
+        height: '15px',
+        width: '20px'
+    }
+});
+console.log(div.style.height); // '15px'
+console.log(div.style.width);  // '20px'
+```
+
+**How it works:**
+
+When assignGingerly encounters an object value being assigned to an existing property, it checks if that property is readonly:
+- **Data properties** with `writable: false`
+- **Accessor properties** with a getter but no setter
+
+If the property is readonly and its current value is an object, assignGingerly automatically merges into it recursively.
+
+**Examples of readonly properties:**
+- `HTMLElement.style` - The CSSStyleDeclaration object
+- `HTMLElement.dataset` - The DOMStringMap object  
+- Custom objects with `Object.defineProperty(obj, 'prop', { value: {}, writable: false })`
+- Accessor properties with getter only: `Object.defineProperty(obj, 'prop', { get() { return {}; } })`
+
+**Error handling:**
+
+If you try to merge an object into a readonly property whose current value is a primitive, assignGingerly throws a descriptive error:
+
+```TypeScript
+const obj = {};
+Object.defineProperty(obj, 'readonlyString', {
+    value: 'immutable',
+    writable: false
+});
+
+assignGingerly(obj, {
+    readonlyString: { nested: 'value' }
+});
+// Error: Cannot merge object into readonly primitive property 'readonlyString'
+```
+
+**Additional examples:**
+
+```TypeScript
+// Dataset property
+const div = document.createElement('div');
+assignGingerly(div, {
+    dataset: {
+        userId: '123',
+        userName: 'Alice'
+    }
+});
+console.log(div.dataset.userId);   // '123'
+console.log(div.dataset.userName); // 'Alice'
+
+// Custom readonly property
+const config = {};
+Object.defineProperty(config, 'settings', {
+    value: {},
+    writable: false
+});
+assignGingerly(config, {
+    settings: {
+        theme: 'dark',
+        lang: 'en'
+    }
+});
+console.log(config.settings.theme); // 'dark'
+```
+
+## Example 3b - Automatic Class Instance Preservation
+
+In addition to readonly property detection, assignGingerly automatically preserves class instances when merging. This is particularly useful when working with enhancement instances:
+
+```TypeScript
+import 'assign-gingerly/object-extension.js';
+
+// Define an enhancement class
+class MyEnhancement {
+  constructor(element, ctx, initVals) {
+    this.element = element;
+    this.instanceId = Math.random(); // Track instance identity
+    if (initVals) {
+      Object.assign(this, initVals);
+    }
+  }
+  prop1 = null;
+  prop2 = null;
+}
+
+const element = document.createElement('div');
+element.enh = {
+  myEnh: new MyEnhancement(element, {}, {})
+};
+
+const originalId = element.enh.myEnh.instanceId;
+
+// Clean syntax - no need for ?.myEnh?.prop1 notation
+assignGingerly(element, {
+  enh: {
+    myEnh: {
+      prop1: 'value1',
+      prop2: 'value2'
+    }
+  }
+});
+
+console.log(element.enh.myEnh.instanceId === originalId); // true - instance preserved!
+console.log(element.enh.myEnh.prop1); // 'value1'
+console.log(element.enh.myEnh.prop2); // 'value2'
+```
+
+**How it works:**
+
+When assignGingerly encounters an object value being assigned to an existing property, it checks if the current value is a class instance (not a plain object):
+
+- **Class instances** are detected by checking if their prototype is something other than `Object.prototype` or `null`
+- **Plain objects** `{}` have `Object.prototype` as their prototype
+- **Class instances** have their class's prototype
+
+If the existing value is a class instance, assignGingerly merges into it instead of replacing it.
+
+**What counts as a class instance:**
+- Custom class instances: `new MyClass()`
+- Built-in class instances: `new Date()`, `new Map()`, `new Set()`, etc.
+- Enhancement instances on the `enh` property
+- Any object whose prototype is not `Object.prototype` or `null`
+
+**What doesn't count:**
+- Plain objects: `{}`, `{ a: 1 }`
+- Arrays: `[]`, `[1, 2, 3]` (arrays are replaced, not merged)
+- Primitives: strings, numbers, booleans
+
+**Benefits:**
+
+This feature enables clean, framework-friendly syntax for updating enhancements:
+
+```TypeScript
+// Before: Verbose nested path syntax
+assignGingerly(element, {
+  '?.enh?.mellowYellow?.madAboutFourteen': true
+});
+
+// After: Clean object syntax
+assignGingerly(element, {
+  enh: {
+    mellowYellow: {
+      madAboutFourteen: true
+    }
+  }
+});
+```
+
+**Additional examples:**
+
+```TypeScript
+// Multiple enhancements at once
+assignGingerly(element, {
+  enh: {
+    enhancement1: { prop: 'value1' },
+    enhancement2: { prop: 'value2' }
+  }
+});
+
+// Works with built-in classes too
+const obj = {
+  timestamp: new Date('2024-01-01')
+};
+
+assignGingerly(obj, {
+  timestamp: {
+    customProp: 'metadata'
+  }
+});
+
+console.log(obj.timestamp instanceof Date); // true - Date instance preserved
+console.log(obj.timestamp.customProp);      // 'metadata'
+```
+
+**Combined with readonly detection:**
+
+Both readonly properties and class instances are preserved:
+
+```TypeScript
+const div = document.createElement('div');
+div.enh = {
+  myEnh: new MyEnhancement(div, {}, {})
+};
+
+assignGingerly(div, {
+  style: { height: '100px' },      // Readonly - merged
+  enh: {
+    myEnh: { prop: 'value' }       // Class instance - merged
+  },
+  dataset: { userId: '123' }       // Readonly - merged
+});
+
+// All instances and readonly objects preserved
+```
 
 While we are in the business of passing values of object A into object B, we might as well add some extremely common behavior that allows updating properties of object B based on the current values of object B -- things like incrementing, toggling, and deleting.  Deleting is critical for assignTentatively, but is included with both functions.
 
@@ -167,7 +388,7 @@ For existing values, the toggle is performed using JavaScript's logical NOT oper
 
 ## Example 6 - Deleting properties with -= command
 
-The `-=` command allows you to delete properties from objects:
+The `-=` command allows us to delete properties from objects:
 
 ```TypeScript
 const obj = {
@@ -296,7 +517,7 @@ interface IEnhancementRegistryItem<T = any, TObjToExtend = any> {
     spawn: {new(objToExtend: TObjToExtend, ctx: SpawnContext, initVals: Partial<T>): T}
     symlinks?: {[key: symbol]: keyof T}
     // Optional: for element enhancement access
-    enhKey?: string
+    enhKey?: string | symbol
     // Optional: automatic attribute parsing 
     withAttrs?: AttrPatterns<T>  
 }
@@ -332,7 +553,7 @@ EnhancementRegistry.push([
         },
         spawn: MyEnhancement,
     },{
-       
+       enhKey: 'mellowYellow',
        symlinks: {
            [isMellow]: 'isMellow'
        },
@@ -344,8 +565,13 @@ EnhancementRegistry.push([
 const result = assignGingerly({}, {
     [isHappy]: true,
     [isMellow]: true,
-    '?.style?.height': '40px',
-    '?.enh?.mellowYellow?.madAboutFourteen': true
+    style:{
+      height: '40px',
+    }, 
+    enh: {
+      '?.mellowYellow?.madAboutFourteen': true
+    }
+    
 }, {
     registry: EnhancementRegistry
 });
@@ -462,8 +688,12 @@ console.log(target.set[symbol1].prop2); // 'value2'
 const result = assignGingerly({}, {
     "[Symbol.for('TFWsx0YH5E6eSfhE7zfLxA')]": true,
     "[Symbol.for('BqnnTPWRHkWdVGWcGQoAiw')]": true,
-    '?.style.height': '40px',
-    '?.enh?.mellowYellow?.madAboutFourteen': true
+    style: {
+      height: '40px'
+    }
+    enh: {
+      mellowYellow?.madAboutFourteen': true
+    }
 }, {
     registry: EnhancementRegistry
 });
@@ -511,12 +741,16 @@ The prototype extensions are non-enumerable and won't appear in `Object.keys()`
 
 -->
 
-## Custom Element Registry Integration (Chrome 146+)
+## Enhancement Registry Addendum to the Custom Element Registry
+
+This package polyfill adds an "enhancementRegistry" registry on the CustomElementRegistry prototype.
 
-This package includes support for Chrome's scoped custom element registries, which automatically integrates dependency injection in harmony with scoped custom elements DOM sections or ShadowRoots.
+In this way, we achieve dependency injection in harmony with scoped custom elements DOM registry scopes.
 
 > [!NOTE]
-> Safari/WebKit played a critical role in pushing scoped custom element registries forward, and announced with little fanfare or documentation that [Safari 26 supports it](https://developer.apple.com/documentation/safari-release-notes/safari-26-release-notes).  However, the Playwright test machinery's cross platform Safari test browser doesn't yet support it.
+> Safari/WebKit played a critical role in pushing scoped custom element registries forward, and announced with little fanfare or documentation that [Safari 26 supports it](https://developer.apple.com/documentation/safari-release-notes/safari-26-release-notes).  However, the Playwright test machinery's cross platform Safari test browser doesn't yet support it.  For now, only Chrome 146+ has been tested / vetted for this functionality.
+>
+> For more information about scoped custom element registries, see [Chrome's announcement and guide](https://developer.chrome.com/blog/scoped-registries).
 
 <details>
   <summary>Automatic Registry Population</summary>
@@ -589,7 +823,7 @@ Building on the Custom Element Registry integration, this package provides a pow
 
 ### Basic Usage
 
-The `enh.set` proxy allows you to assign properties to enhancements using a clean, chainable syntax:
+The `enh.set` proxy allows us to assign properties to enhancements using a clean, chainable syntax:
 
 ```TypeScript
 import 'assign-gingerly/object-extension.js';
@@ -680,12 +914,12 @@ class Enhancement<T> {
 
 All parameters are optional for backward compatibility with existing code.
 
-Note that the class need not extend any base class or leverage any mixins.  In fact, ES5 prototype functions can be used, and in both cases are instanted using new ....  Arrow functions cannot be used.
+Note that the class need not extend any base class or leverage any mixins.  In fact, ES5 prototype functions can be used, and in both cases are instantiated using new ....  Arrow functions cannot be used.
 
 <details>
 <summary>Passing Custom Context</summary>
 
-You can pass custom context when calling `enh.get()` or `enh.whenResolved()`:
+You can pass custom context when calling `enh.get()` or `enh.whenResolved()` (discussed in detail below):
 
 ```TypeScript
 // Pass custom context to the spawned instance
@@ -1411,7 +1645,8 @@ console.log(instance.count);  // 42 (parsed from attribute)
 console.log(instance.theme);  // 'dark' (parsed from attribute)
 ```
 
-**Example without enhKey:**
+<details>
+  <summary>Example without enhKey</summary>
 
 ```TypeScript
 // withAttrs works even without enhKey
@@ -1445,16 +1680,21 @@ const instance = element.enh.get(config);
 console.log(instance.value);  // 'test123' (parsed from attribute)
 ```
 
-**How it works:**
+</details>
+
+<details>
+  <summary>How it works</summary>
+
 1. When an enhancement is spawned via `enh.get()`, `enh.set`, or `assignGingerly()`
 2. If the registry item has a `withAttrs` property defined
 3. `parseWithAttrs(element, registryItem.withAttrs)` is automatically called
 4. The parsed attributes are passed to the enhancement constructor as `initVals`
 5. If the registry item also has an `enhKey`, the parsed attributes are merged with any existing values from `element.enh[enhKey]` (existing values take precedence)
 
-**Note**: `withAttrs` works with or without `enhKey`. When there's no `enhKey`, the parsed attributes are passed directly to the constructor. When there is an `enhKey`, they're merged with any pre-existing values on the enh container.
-
+</details>
 
+> ![NOTE]
+> `withAttrs` works with or without `enhKey`. When there's no `enhKey`, the parsed attributes are passed directly to the constructor. When there is an `enhKey`, they're merged with any pre-existing values on the enh container.
 
 ### The `enh-` Prefix for Attribute Isolation
 
@@ -1652,7 +1892,10 @@ interface AttrPatterns<T> {
 interface AttrConfig<T> {
   mapsTo?: keyof T | '.';           // Target property name (or '.' to spread)
   instanceOf?: string | Function;   // Type for default parser
-  parser?: (v: string | null) => any;  // Custom parser function
+  parser?: 
+    | ((v: string | null) => any)   // Inline parser function
+    | string                         // Named parser from globalParserRegistry
+    | [string, string];              // [CustomElementName, StaticMethodName]
 }
 ```
 
@@ -1772,7 +2015,7 @@ The following parsers are pre-registered in `globalParserRegistry`:
 
 **Custom Element Static Method Parsers:**
 
-You can also reference static methods on custom elements using dot notation:
+You can reference static methods on custom elements using tuple syntax `[elementName, methodName]`:
 
 ```TypeScript
 class MyWidget extends HTMLElement {
@@ -1786,29 +2029,47 @@ class MyWidget extends HTMLElement {
 }
 customElements.define('my-widget', MyWidget);
 
-// Reference custom element parsers
+// Reference custom element parsers using tuple syntax
 const config = {
   base: 'data-',
   value: '${base}value',
   _value: {
-    parser: 'my-widget.parseSpecialFormat'  // element-name.methodName
+    parser: ['my-widget', 'parseSpecialFormat']  // [element-name, methodName]
+  },
+  title: '${base}title',
+  _title: {
+    parser: ['my-widget', 'parseWithPrefix']
   }
 };
+
+const result = parseWithAttrs(element, config);
 ```
 
-**Parser Resolution Order:**
+**Parser Resolution:**
 
-When a string parser is specified:
+When a parser is specified, it can be:
 
-1. **Check for dot notation** - If parser contains `.`, try to resolve as `element-name.methodName`
-2. **Try custom element** - Look up element in `customElements` registry and check for static method
-3. **Fall back to global registry** - If custom element not found, check `globalParserRegistry`
-4. **Throw error** - If not found anywhere, throw descriptive error
+1. **Inline function** - `parser: (v) => v.toUpperCase()` - Used directly
+2. **String reference** - `parser: 'timestamp'` - Looks up in `globalParserRegistry`
+3. **Tuple reference** - `parser: ['my-widget', 'parseMethod']` - Looks up static method on custom element constructor
+
+**Error Handling:**
+
+The tuple syntax provides clear error messages:
+
+```TypeScript
+// Element not found
+parser: ['non-existent', 'method']
+// Error: Cannot resolve parser [non-existent, method]: custom element "non-existent" not found
 
-This allows:
-- Element-specific parsers to be scoped to their custom elements
-- Fallback to global registry for shared parsers
-- Dot notation in global registry names (e.g., `'utils.parseDate'`)
+// Method not found
+parser: ['my-widget', 'nonExistent']
+// Error: Cannot resolve parser [my-widget, nonExistent]: static method "nonExistent" not found on custom element "my-widget"
+
+// String not found in registry
+parser: 'unknown'
+// Error: Parser "unknown" not found in globalParserRegistry. If you want to reference a custom element static method, use tuple syntax: ["element-name", "methodName"]
+```
 
 **Example: Organizing Parsers**
 
@@ -1890,7 +2151,7 @@ const result = parseWithAttrs(element, {
 
 ### Default Values with valIfNull
 
-The `valIfNull` property allows you to specify default values when attributes are missing:
+The `valIfNull` property allows us to specify default values when attributes are missing:
 
 ```TypeScript
 // HTML: <div></div>  (no attributes)
@@ -2357,13 +2618,17 @@ buildCSSQuery(config, '  div  ,  span  ,  p  ');
 1. **Mount Observer Integration**: Find elements that need enhancement
    ```TypeScript
    // Match any element with the attributes
-   const query = buildCSSQuery(enhancementConfig);
-   const observer = new MutationObserver(() => {
-     const elements = document.querySelectorAll(query);
-     elements.forEach(el => enhance(el));
+   const matching = buildCSSQuery(enhancementConfig);
+   const observer = new MountObserver({
+      matching,
+      do: (mountedElement) => {
+        enhance(mountedElement);
+      }
    });
    ```
 
+   See [Mount-Observer](https://github.com/bahrus/mount-observer).
+
 2. **Specific Element Types**: Enhance only certain element types
    ```TypeScript
    const query = buildCSSQuery(config, 'template, script');
@@ -2452,6 +2717,414 @@ console.log(result);
 
 -->
 
+## 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.
+
+> [!NOTE]
+> This feature requires Chrome 146+ with scoped custom element registry support. It follows the same browser support requirements as the Enhancement Registry integration.
+>
+> For more information about scoped custom element registries, see [Chrome's announcement and guide](https://developer.chrome.com/blog/scoped-registries).
+
+### Why Itemscope Managers?
+
+The `itemscope` attribute (from the Microdata specification) provides a semantic way to mark elements that represent distinct data items. ItemScope Managers build on this by allowing us to:
+
+- **Manage light children**: Attach behavior to light DOM children of web components without wrapping them in custom elements
+- **Handle template loops**: Manage repeated DOM fragments generated by template systems
+- **Avoid custom element overhead**: Enhance elements where custom element registration isn't appropriate or possible
+- **Separate concerns**: Keep data/view model logic separate from the DOM structure
+
+### Basic Usage
+
+```html
+<div itemscope="user-card">
+  <h2>User Profile</h2>
+  <p itemprop="name"></p>
+  <p itemprop="email"></p>
+</div>
+```
+
+```TypeScript
+import 'assign-gingerly/object-extension.js';
+
+// Define a manager class
+class UserCardManager {
+  element;
+  name = '';
+  email = '';
+  
+  constructor(element, initVals) {
+    this.element = element;
+    if (initVals) {
+      Object.assign(this, initVals);
+      this.render();
+    }
+  }
+  
+  render() {
+    this.element.querySelector('[itemprop="name"]').textContent = this.name;
+    this.element.querySelector('[itemprop="email"]').textContent = this.email;
+  }
+}
+
+// Register the manager
+customElements.itemscopeRegistry.define('user-card', {
+  manager: UserCardManager
+});
+
+// Use assignGingerly with the 'ish' property
+const element = document.querySelector('[itemscope="user-card"]');
+element.assignGingerly({
+  ish: {
+    name: 'Alice',
+    email: 'alice@example.com'
+  }
+});
+
+// Wait for async setup to complete
+await customElements.itemscopeRegistry.whenDefined('user-card');
+
+// Access the manager instance
+console.log(element.ish instanceof UserCardManager); // true
+console.log(element.ish.name); // 'Alice'
+```
+
+### The 'ish' Property
+
+The `ish` property (short for "itemscope host") is the key to ItemScope Managers:
+
+- **Special behavior for HTMLElements**: When you assign an `ish` property to an HTMLElement with an `itemscope` attribute, it triggers manager instantiation
+- **Normal property for other objects**: For non-HTMLElement objects, `ish` is just a regular property with no special behavior
+- **Asynchronous setup**: The manager is instantiated asynchronously, so use `whenDefined()` to wait for completion
+
+```TypeScript
+// HTMLElement with itemscope - special behavior
+const div = document.createElement('div');
+div.setAttribute('itemscope', 'my-manager');
+div.assignGingerly({ ish: { prop: 'value' } });
+// Manager will be instantiated asynchronously
+
+// Plain object - normal property
+const obj = {};
+obj.assignGingerly({ ish: { prop: 'value' } });
+console.log(obj.ish.prop); // 'value' - just a regular property
+```
+
+### ItemscopeRegistry
+
+The `ItemscopeRegistry` class manages manager configurations and extends `EventTarget` to support lazy registration:
+
+```TypeScript
+// Access the global registry
+const registry = customElements.itemscopeRegistry;
+
+// Define a manager
+registry.define('manager-name', {
+  manager: ManagerClass,
+  lifecycleKeys: {
+    dispose: 'cleanup',
+    resolved: 'isReady'
+  }
+});
+
+// Get a manager configuration
+const config = registry.get('manager-name');
+
+// Wait for a manager to be defined and all setups to complete
+await registry.whenDefined('manager-name');
+```
+
+**Methods:**
+
+- `define(name, config)` - Register a manager configuration
+  - Throws `Error: Already registered` if name already exists
+  - Dispatches an event with the manager name when successful
+  
+- `get(name)` - Retrieve a manager configuration
+  - Returns the configuration or `undefined` if not found
+  
+- `whenDefined(name)` - Wait for manager definition and setup completion
+  - Returns a Promise that resolves when:
+    1. The manager is defined (waits for definition if not yet registered)
+    2. All pending `ish` property setups for this manager are complete
+  - This is the recommended way to wait for async manager instantiation
+
+### Manager Configuration
+
+Manager configurations follow this interface:
+
+```TypeScript
+interface ItemscopeManagerConfig<T = any> {
+  manager: {
+    new (element: HTMLElement, initVals?: Partial<T>): T;
+  };
+  lifecycleKeys?: {
+    dispose?: string | symbol;
+    resolved?: string | symbol;
+  };
+}
+```
+
+**Properties:**
+
+- `manager` (required): Constructor function that receives:
+  - `element`: The HTMLElement with the itemscope attribute
+  - `initVals`: Merged values from all queued `ish` assignments
+  
+- `lifecycleKeys` (optional): Lifecycle method names
+  - `dispose`: Method to call when cleaning up
+  - `resolved`: Property/event name for async initialization
+
+### Lazy Registration
+
+Managers can be registered after elements are already using them. The system queues values and instantiates the manager when it's registered:
+
+```TypeScript
+const element = document.createElement('div');
+element.setAttribute('itemscope', 'lazy-manager');
+
+// Assign before manager is registered - values are queued
+element.assignGingerly({ ish: { prop1: 'value1' } });
+element.assignGingerly({ ish: { prop2: 'value2' } });
+
+// Register the manager later
+setTimeout(() => {
+  customElements.itemscopeRegistry.define('lazy-manager', {
+    manager: class LazyManager {
+      constructor(element, initVals) {
+        this.element = element;
+        Object.assign(this, initVals);
+        // initVals contains both prop1 and prop2
+      }
+    }
+  });
+}, 100);
+
+// Wait for registration and setup
+await customElements.itemscopeRegistry.whenDefined('lazy-manager');
+
+console.log(element.ish.prop1); // 'value1'
+console.log(element.ish.prop2); // 'value2'
+```
+
+### Instance Caching
+
+Manager instances are cached per element. Subsequent `ish` assignments merge values into the existing instance:
+
+```TypeScript
+const element = document.createElement('div');
+element.setAttribute('itemscope', 'my-manager');
+
+// First assignment - creates instance
+element.assignGingerly({ ish: { prop1: 'value1' } });
+await customElements.itemscopeRegistry.whenDefined('my-manager');
+
+const firstInstance = element.ish;
+
+// Second assignment - reuses instance
+element.assignGingerly({ ish: { prop2: 'value2' } });
+await customElements.itemscopeRegistry.whenDefined('my-manager');
+
+console.log(element.ish === firstInstance); // true - same instance
+console.log(element.ish.prop1); // 'value1'
+console.log(element.ish.prop2); // 'value2'
+```
+
+### Validation and Error Handling
+
+The system validates `ish` property assignments and throws descriptive errors:
+
+```TypeScript
+// Error: Element must have itemscope attribute
+const div1 = document.createElement('div');
+div1.assignGingerly({ ish: { prop: 'value' } });
+// Throws asynchronously
+
+// Error: itemscope must be non-empty string
+const div2 = document.createElement('div');
+div2.setAttribute('itemscope', '');
+div2.assignGingerly({ ish: { prop: 'value' } });
+// Throws asynchronously
+
+// Error: ish value must be an object
+const div3 = document.createElement('div');
+div3.setAttribute('itemscope', 'my-manager');
+div3.assignGingerly({ ish: 'string' });
+// Throws asynchronously
+```
+
+**Note**: Errors are thrown asynchronously since the `ish` property setup happens in the background. They will appear in the console but won't be catchable with try/catch around the `assignGingerly` call.
+
+### Scoped Registries
+
+ItemScope Managers integrate with scoped custom element registries. Each element can have its own registry:
+
+```TypeScript
+// Create a scoped registry
+const scopedRegistry = new CustomElementRegistry();
+
+// Define a manager in the scoped registry
+scopedRegistry.itemscopeRegistry.define('scoped-manager', {
+  manager: ScopedManager
+});
+
+// Attach the registry to an element
+const element = document.createElement('div');
+element.customElementRegistry = scopedRegistry;
+element.setAttribute('itemscope', 'scoped-manager');
+
+// The element uses its scoped registry
+element.assignGingerly({ ish: { prop: 'value' } });
+await scopedRegistry.itemscopeRegistry.whenDefined('scoped-manager');
+```
+
+If an element doesn't have a `customElementRegistry` property, it falls back to the global `customElements.itemscopeRegistry`.
+
+### Complete Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module">
+    import 'assign-gingerly/object-extension.js';
+    
+    // Define a todo item manager
+    class TodoItemManager {
+      element;
+      text = '';
+      completed = false;
+      
+      constructor(element, initVals) {
+        this.element = element;
+        if (initVals) {
+          Object.assign(this, initVals);
+        }
+        this.render();
+        this.attachListeners();
+      }
+      
+      render() {
+        const checkbox = this.element.querySelector('input[type="checkbox"]');
+        const label = this.element.querySelector('label');
+        
+        if (checkbox) checkbox.checked = this.completed;
+        if (label) label.textContent = this.text;
+      }
+      
+      attachListeners() {
+        const checkbox = this.element.querySelector('input[type="checkbox"]');
+        if (checkbox) {
+          checkbox.addEventListener('change', (e) => {
+            this.completed = e.target.checked;
+            this.render();
+          });
+        }
+      }
+      
+      cleanup() {
+        // Remove event listeners, etc.
+        console.log('Cleaning up todo item');
+      }
+    }
+    
+    // Register the manager
+    customElements.itemscopeRegistry.define('todo-item', {
+      manager: TodoItemManager,
+      lifecycleKeys: {
+        dispose: 'cleanup'
+      }
+    });
+    
+    // Initialize todo items
+    async function initTodos() {
+      const items = document.querySelectorAll('[itemscope="todo-item"]');
+      
+      items.forEach((item, index) => {
+        item.assignGingerly({
+          ish: {
+            text: `Todo item ${index + 1}`,
+            completed: false
+          }
+        });
+      });
+      
+      // Wait for all setups to complete
+      await customElements.itemscopeRegistry.whenDefined('todo-item');
+      
+      console.log('All todo items initialized');
+    }
+    
+    // Run on page load
+    document.addEventListener('DOMContentLoaded', initTodos);
+  </script>
+</head>
+<body>
+  <h1>Todo List</h1>
+  <ul>
+    <li itemscope="todo-item">
+      <input type="checkbox">
+      <label></label>
+    </li>
+    <li itemscope="todo-item">
+      <input type="checkbox">
+      <label></label>
+    </li>
+    <li itemscope="todo-item">
+      <input type="checkbox">
+      <label></label>
+    </li>
+  </ul>
+</body>
+</html>
+```
+
+### Testing with whenDefined
+
+When writing tests for code that uses ItemScope Managers, use `whenDefined()` to wait for async setup:
+
+```TypeScript
+// Test example
+test('should initialize manager with values', async () => {
+  const element = document.createElement('div');
+  element.setAttribute('itemscope', 'test-manager');
+  
+  // Register manager
+  customElements.itemscopeRegistry.define('test-manager', {
+    manager: class TestManager {
+      constructor(element, initVals) {
+        this.element = element;
+        Object.assign(this, initVals);
+      }
+    }
+  });
+  
+  // Assign values
+  element.assignGingerly({ ish: { prop: 'value' } });
+  
+  // Wait for setup to complete
+  await customElements.itemscopeRegistry.whenDefined('test-manager');
+  
+  // Now we can assert
+  expect(element.ish.prop).toBe('value');
+  expect(element.ish.element).toBe(element);
+});
+```
+
+### Design Rationale
+
+ItemScope Managers follow these design principles:
+
+1. **Synchronous API**: `assignGingerly` remains synchronous and returns immediately
+2. **Async setup**: Manager instantiation happens asynchronously in the background
+3. **Explicit waiting**: Use `whenDefined()` when you need to wait for setup completion
+4. **Dual behavior**: The `ish` property has special meaning only for HTMLElements with `itemscope` attributes
+5. **Registry-based**: Follows the same pattern as `EnhancementRegistry` for consistency
+6. **Event-driven**: Uses EventTarget for lazy registration support
+
+This design ensures backward compatibility while providing powerful new capabilities for managing DOM fragments.
+