assign-gingerly 0.0.67 → 0.0.68

package/{emojis.js → DX/emojis.js}

@@ -33,7 +33,8 @@ export const akaMethods = {
     '🔍': 'querySelector',
     '🧺': 'querySelectorAll',
     '+': 'add',
-    '🧬': 'cloneNode'
+    '🧬': 'cloneNode',
+    '🔤': 'textContent',
 };
 export const aka = {
     '©️': 'content?.cloneNode?.true',

package/{emojis.ts → DX/emojis.ts}

@@ -35,7 +35,8 @@ export const akaMethods: Record<string, string> = {
     '🔍': 'querySelector',
     '🧺': 'querySelectorAll',
     '+': 'add',
-    '🧬': 'cloneNode'
+    '🧬': 'cloneNode',
+    '🔤': 'textContent',
 };
 
 export const aka: Record<string, string> = {

package/inferencer/AGENTS.md

@@ -0,0 +1,10 @@
+# Inferencer Submodule Isolation
+
+The `inferencer/` folder is a git submodule that must remain self-contained and independently publishable.
+
+## Rules
+
+- **No imports from outside the folder.** Code in `inferencer/` must NOT import from any file in the parent project (no `../assignGingerly.js`, no `../paths.js`, etc.).
+- **No references to assign-gingerly internals.** The inferencer module must work as a standalone package with zero dependencies on assign-gingerly runtime code.
+- **Types only exception:** Type-only imports from `../types/` are acceptable IF they are also published as part of the inferencer package's own type declarations. Prefer duplicating small type definitions over creating a dependency.
+- **Test exceptions:** Test files within `inferencer/` MAY reference the parent project for integration testing, but runtime source files must not.

package/inferencer/types/EnhancementConversionInstructions.md

@@ -1383,6 +1383,27 @@ const selectorMatch = prop.match(/^\[(.+?)\](?:\?\.(.+))?$/);
 3. **Wrong parser in HTML** - HTML references `parse-pattern-statements` but emc.mjs uses `parse-grouped-capture-statements`
 4. **Period vs chained accessor** - Using `.` instead of `?.` for selector properties
 5. **Forgetting to rebuild** - After changing emc.mjs or emoji.mjs, always run `npm run build`
+6. **Hydrate fires before all attributes are read** - Attribute props are assigned one at a time during initialization; use the `initialized` flag pattern (see below) when an action must wait for all of them
+
+### Blocking an Action Until All Attributes Are Read
+
+When converting an enhancement whose `hydrate` (or other action) depends on multiple attribute-derived props, it's often predictable that nothing should happen until all relevant attributes have been read. Gating on the props alone doesn't work:
+
+- `ifKeyIn` alone means **at least one** of the listed props is defined, so the action can fire after the first attribute is read with the rest still `undefined`.
+- With `ifKeyIn` and `ifAllOf` combined, roundabout only runs the action when the *changed* property is in `ifKeyIn` — a prop listed only in `ifAllOf` never triggers it.
+
+The proven fix (from three-peat): add `initialized?: boolean` to `AllProps`, set `self.initialized = true` in `init` immediately after `await roundabout(...)`, and gate the action on it in both lists:
+
+```javascript
+actions: {
+    hydrate: {
+        ifKeyIn: ['src', 'listProp', 'initialized'],
+        ifAllOf: ['enhancedElement', 'initialized']
+    }
+}
+```
+
+`initialized` flips only after `roundabout()` returns (all attribute reads complete), and including it in `ifKeyIn` makes its change the trigger. Keep the attribute props in `ifKeyIn` too, so later attribute changes still re-trigger the action. See `NewEnhancementInstructions.md` ("Blocking an Action Until All Attributes Are Read") for the full step-by-step recipe.
 
 ### Debugging Tips
 

package/inferencer/types/NewEnhancementInstructions.md

@@ -681,6 +681,52 @@ import { findAdjacentElement } from 'be-hive/findAdjacentElement.js';
 import { findAdjacentElement } from 'trans-render/lib/findAdjacentElement.js';
 ```
 
+### Blocking an Action Until All Attributes Are Read
+
+**Use this pattern only when it's predictable that an action (typically `hydrate`) must not run until all relevant attributes have been read.** Attribute-derived props are assigned one at a time during `roundabout()`'s initial pass, so gating on the props themselves isn't enough:
+
+- `ifKeyIn` alone means **at least one** of the listed props is defined — the action fires as soon as the first attribute is read, while later ones are still `undefined`.
+- When `ifKeyIn` is combined with `ifAllOf`, the action only executes when the property that *changed* is in `ifKeyIn` (`shouldExecute = conditionsMet && changedIsInKeyIn` in roundabout). A prop listed only in `ifAllOf` can never trigger the action.
+
+The proven solution (from three-peat) is an `initialized` flag set after `roundabout()` returns:
+
+**1. Add `initialized` to `AllProps` in `types/<name>/types.d.ts`:**
+
+```typescript
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element & ElementEnhancementGateway;
+    resolved?: boolean;
+    initialized?: boolean;
+}
+```
+
+**2. Set it at the end of `init`, after the `await roundabout(...)`:**
+
+```javascript
+async init(self, enhancedElement, ctx, initVals){
+    // ...build raOptions...
+    await (await import('roundabout-lib/roundabout.js')).roundabout(raOptions);
+    self.initialized = true;  // all attribute reads are done at this point
+}
+```
+
+**3. Gate the action on `initialized` in `emc.mjs` — in *both* lists:**
+
+```javascript
+actions: {
+    hydrate: {
+        ifKeyIn: ['src', 'listProp', 'initialized'],
+        ifAllOf: ['enhancedElement', 'initialized']
+    }
+}
+```
+
+- `initialized` is the last prop to change, and it only flips after every attribute has been read, so it is the reliable trigger.
+- It must be in `ifKeyIn`, not just `ifAllOf` — otherwise its change event doesn't satisfy `changedIsInKeyIn` and the action never fires (the other props were already assigned during the initial pass and never change again).
+- Keeping the attribute props (`src`, `listProp`) in `ifKeyIn` preserves re-hydration when those attributes change later at runtime.
+
+Reference implementation: three-peat (`emc.mjs`, `three-peat.js`, `types/three-peat/types.d.ts`).
+
 ### Debugging Tips
 
 1. **Check the generated JSON** — Run `node emc.mjs` and verify all sections (especially `customData`) are present
@@ -702,4 +748,4 @@ Don't try to implement all features at once.
 
 ---
 
-*Last updated: June 2026*
+*Last updated: July 2026*

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

@@ -10,9 +10,49 @@ export interface EndUserProps{
     
     /**
      * Specify id of peer element to pull list from.
+     * If not provided, the host is found by searching upwards
+     * for an itemscope-managed element, falling back to the
+     * shadow root host.
      */
     src?: string;
-    each: FromEachItemConfig,
-    target: string,
-    updateOn: string,
-}
+
+    /**
+     * Specifies how each item's values are distributed into the
+     * cloned document fragment.  Parsed from JSON.
+     * If not provided, each item's properties are inferred into
+     * the clone's [itemprop] descendants.
+     */
+    each?: FromEachItemConfig,
+
+    /**
+     * id of an element (within the same root node) into which the
+     * repeating cloned fragments should be placed.
+     * If not provided, the fragments are appended to the children
+     * of the adorned element (or, if the adorned element is a
+     * template, to the template's parent element).
+     */
+    target?: string,
+
+    /**
+     * Name of the event the host dispatches when the list has changed.
+     * If not provided, but listProp is, the host is assumed to have
+     * a propagator (one is created if it doesn't exist), which is
+     * listened to for an event named after listProp.
+     */
+    updateOn?: string,
+}
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element & ElementEnhancementGateway;
+    resolved?: boolean;
+    initialized?: boolean;
+}
+
+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>;
+    hydrate(self: AP): ProPAP;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -163,9 +163,9 @@
       "default": "./assignFromAsync-extension.js",
       "types": "./assignFromAsync-extension.ts"
     },
-    "./emojis.js": {
-      "default": "./emojis.js",
-      "types": "./emojis.ts"
+    "./DX/emojis.js": {
+      "default": "./DX/emojis.js",
+      "types": "./DX/emojis.ts"
     },
     "./assignFeatures.js": {
       "default": "./assignFeatures.js",