@jinntec/fore 3.1.2 → 3.2.1

package/dist/fore-dev.js

@@ -1,4 +1,4 @@
-/* Version: 3.1.2 - May 27, 2026 14:39:35 */
+/* Version: 3.2.1 - June 12, 2026 14:10:39 */
 function t$2(t, s, r, i) {
   const n = {
     op: s,
@@ -20124,7 +20124,7 @@ class Fore {
     return Fore.ACTION_ELEMENTS.includes(elementName);
   }
   static get UI_ELEMENTS() {
-    return new Set(['FX-ALERT', 'FX-CONTROL', 'FX-DIALOG', 'FX-FILENAME', 'FX-MEDIATYPE', 'FX-GROUP', 'FX-HINT', 'FX-ITEMS', 'FX-OUTPUT', 'FX-RANGE', 'FX-REPEAT', 'FX-REPEATITEM', 'FX-REPEAT-ATTRIBUTES', 'FX-SWITCH', 'FX-SECRET', 'FX-SELECT', 'FX-SUBMIT', 'FX-TEXTAREA', 'FX-TRIGGER', 'FX-UPLOAD', 'FX-VAR']);
+    return new Set(['FX-ALERT', 'FX-CONTROL', 'FX-DIALOG', 'FX-FILENAME', 'FX-MEDIATYPE', 'FX-GROUP', 'FX-HINT', 'FX-ITEMS', 'FX-INCLUDE', 'FX-OUTPUT', 'FX-RANGE', 'FX-REPEAT', 'FX-REPEATITEM', 'FX-REPEAT-ATTRIBUTES', 'FX-SWITCH', 'FX-SECRET', 'FX-SELECT', 'FX-SUBMIT', 'FX-TEXTAREA', 'FX-TRIGGER', 'FX-UPLOAD', 'FX-VAR']);
   }
 
   /**
@@ -25479,7 +25479,7 @@ class FxFore extends HTMLElement {
       this._createRepeatsFromAttributes();
       this.inited = true;
     };
-    this.version = 'Version: 3.1.2 - built on May 27, 2026 14:39:35';
+    this.version = 'Version: 3.2.1 - built on June 12, 2026 14:10:39';
 
     /**
      * @type {import('./fx-model.js').FxModel}
@@ -25708,10 +25708,21 @@ class FxFore extends HTMLElement {
     }
     return null;
   }
-  _isReadyTarget(el) {
+  static _isReadyTarget(el) {
     return !!(el && (el.ready === true || el.classList && el.classList.contains('fx-ready') || typeof el.hasAttribute === 'function' && el.hasAttribute('ready')));
   }
 
+  /**
+   * Resolves once `fore` has dispatched its initial `ready` event (or
+   * immediately, if it's already ready).
+   */
+  static waitUntilReady(fore) {
+    if (FxFore._isReadyTarget(fore)) {
+      return Promise.resolve();
+    }
+    return FxFore._waitForEvent(fore, 'ready', FxFore._isReadyTarget);
+  }
+
   /**
    * Collect all init gates derived from attributes.
    *
@@ -25748,7 +25759,7 @@ class FxFore extends HTMLElement {
     }
     return gates;
   }
-  _waitForEvent(target, eventName, isSatisfiedFn = null) {
+  static _waitForEvent(target, eventName, isSatisfiedFn = null) {
     // If a caller provides an explicit satisfaction check, honor it first.
     if (typeof isSatisfiedFn === 'function' && isSatisfiedFn(target)) {
       FxFore._markInitEventSeen(target, eventName);
@@ -25812,19 +25823,19 @@ class FxFore extends HTMLElement {
   }) {
     // Direct targets
     if (targetSpec === 'self') {
-      const satisfied = event === 'ready' ? t => this._isReadyTarget(t) : null;
-      return this._waitForEvent(this, event, satisfied);
+      const satisfied = event === 'ready' ? t => FxFore._isReadyTarget(t) : null;
+      return FxFore._waitForEvent(this, event, satisfied);
     }
     if (targetSpec === 'document') {
-      return this._waitForEvent(document, event);
+      return FxFore._waitForEvent(document, event);
     }
     if (targetSpec === 'window') {
-      return this._waitForEvent(window, event);
+      return FxFore._waitForEvent(window, event);
     }
 
     // Special: closest fx-fore
     if (targetSpec === 'closest') {
-      const recheckFn = event === 'ready' ? () => this._isReadyTarget(this.closest('fx-fore')) : null;
+      const recheckFn = event === 'ready' ? () => FxFore._isReadyTarget(this.closest('fx-fore')) : null;
       const matchesFn = ev => {
         const t = ev.target;
         return t?.tagName === 'FX-FORE' && t.contains(this);
@@ -25834,7 +25845,7 @@ class FxFore extends HTMLElement {
 
     // Selector targets
     const selector = targetSpec;
-    const recheckFn = event === 'ready' ? () => this._isReadyTarget(this._findBySelector(selector)) : null;
+    const recheckFn = event === 'ready' ? () => FxFore._isReadyTarget(this._findBySelector(selector)) : null;
     if (typeof recheckFn === 'function' && recheckFn()) {
       return Promise.resolve();
     }
@@ -26929,7 +26940,7 @@ class FxFore extends HTMLElement {
         bound.evalInContext();
         if (bound.nodeName !== 'FX-REPEAT') {
           // Do not try to get a bind for a nodeSET of a repeat. there are multiple.
-          bound.getModelItem().bind?.evalInContext();
+          bound.getModelItem()?.bind?.evalInContext();
         }
         continue;
       }
@@ -26978,7 +26989,7 @@ class FxFore extends HTMLElement {
         }
       }
       bound.evalInContext();
-      bound.getModelItem().bind?.evalInContext();
+      bound.getModelItem()?.bind?.evalInContext();
       if (!isResolvedBound(bound)) {
         console.warn('create-nodes: could not resolve bound after node creation, skipping', bound);
         continue;
@@ -29635,6 +29646,236 @@ if (!customElements.get('fx-hint')) {
   customElements.define('fx-hint', FxHint);
 }
 
+/**
+ * <fx-include>
+ *
+ * Lazy light-DOM include component.
+ *
+ * Loads markup either from:
+ *   - a direct child <template>
+ *   - an external HTML document via @src
+ *
+ * Default behavior:
+ *   - listens for an event
+ *   - includes content once
+ *   - removes the event listener afterwards
+ *
+ * With @reload:
+ *   - listens repeatedly
+ *   - clears previously included content
+ *   - includes fresh content again
+ *
+ * Attributes:
+ *   event      Event name to listen for. Defaults to "click".
+ *   target     CSS selector for the event target. Defaults to "self".
+ *              Special values: self, document, window.
+ *   src        Optional external HTML source.
+ *   selector   Optional selector inside external HTML.
+ *   replace    Replace <fx-include> with the included content.
+ *   immediate  Include immediately when connected.
+ *   reload     Re-include on every matching event.
+ */
+class FxInclude extends HTMLElement {
+  constructor() {
+    super();
+    this._listener = this._handleEvent.bind(this);
+    this._eventTarget = null;
+    this._loaded = false;
+    this._replaced = false;
+  }
+  connectedCallback() {
+    this.eventName = this.getAttribute('event') || 'click';
+    this.targetSelector = this.getAttribute('target') || 'self';
+    this.src = this.getAttribute('src');
+    this.selector = this.getAttribute('selector');
+    this.replace = this.hasAttribute('replace');
+    this.immediate = this.hasAttribute('immediate');
+    this.reload = this.hasAttribute('reload');
+    if (this.immediate) {
+      this._includeWhenReady();
+      return;
+    }
+    this._bindListener();
+  }
+
+  /**
+   * Includes content immediately, but waits until the closest `fx-fore` has
+   * finished its initial Rebuild/Recalculate/Revalidate/Refresh cycle (i.e. is
+   * "ready"), so the included content can resolve binding context against an
+   * already-initialized ancestor chain.
+   */
+  _includeWhenReady() {
+    const fore = this.closest('fx-fore');
+    if (!fore) {
+      queueMicrotask(() => this.include());
+      return;
+    }
+    FxFore.waitUntilReady(fore).then(() => this.include());
+  }
+  disconnectedCallback() {
+    this._unbindListener();
+  }
+  _bindListener() {
+    const target = this._resolveEventTarget();
+    if (!target) {
+      this._dispatchError(`fx-include: event target not found: '${this.targetSelector}'`);
+      return;
+    }
+    target.addEventListener(this.eventName, this._listener);
+    this._eventTarget = target;
+  }
+  _unbindListener() {
+    if (this._eventTarget && this._listener) {
+      this._eventTarget.removeEventListener(this.eventName, this._listener);
+    }
+    this._eventTarget = null;
+  }
+  _resolveEventTarget() {
+    if (!this.targetSelector || this.targetSelector === 'self') {
+      return this;
+    }
+    if (this.targetSelector === 'document') {
+      return document;
+    }
+    if (this.targetSelector === 'window') {
+      return window;
+    }
+    const fore = this.closest('fx-fore');
+    return fore?.querySelector(this.targetSelector) || document.querySelector(this.targetSelector);
+  }
+  async _handleEvent(event) {
+    await this.include(event);
+  }
+  async include(triggerEvent = null) {
+    if (this._replaced) {
+      return;
+    }
+    if (this._loaded && !this.reload) {
+      return;
+    }
+    const fragment = this.src ? await this._loadExternalFragment() : this._loadTemplateFragment();
+    if (!fragment) {
+      return;
+    }
+    if (this.replace) {
+      await this._replaceSelf(fragment, triggerEvent);
+      return;
+    }
+    this._clearIncludedContent();
+    const wrapper = document.createElement('span');
+    wrapper.setAttribute('data-fx-include-content', '');
+    wrapper.style.display = 'contents';
+    wrapper.appendChild(fragment);
+    this.appendChild(wrapper);
+    this._loaded = true;
+    await this._initializeInsertedContent(wrapper);
+    await Fore.dispatch(this, 'include-done', {
+      src: this.src || null,
+      included: wrapper,
+      replaced: false,
+      triggerEvent
+    });
+    if (!this.reload) {
+      this._unbindListener();
+    }
+  }
+  _loadTemplateFragment() {
+    const template = this.querySelector(':scope > template');
+    if (!template) {
+      this._dispatchError('fx-include: no src and no direct template child found');
+      return null;
+    }
+    return template.content.cloneNode(true);
+  }
+  async _loadExternalFragment() {
+    const html = await Fore.loadHtml(this.src);
+    if (!html) {
+      this._dispatchError(`fx-include: failed to load '${this.src}'`);
+      return null;
+    }
+    const parsed = new DOMParser().parseFromString(html, 'text/html');
+    if (this.selector) {
+      const selected = parsed.querySelector(this.selector);
+      if (!selected) {
+        this._dispatchError(`fx-include: selector '${this.selector}' not found in '${this.src}'`);
+        return null;
+      }
+      const fragment = document.createDocumentFragment();
+      fragment.appendChild(document.importNode(selected, true));
+      return fragment;
+    }
+    const template = parsed.body.querySelector(':scope > template');
+    if (template) {
+      return document.importNode(template.content, true);
+    }
+    const rootElements = Array.from(parsed.body.children);
+    if (rootElements.length === 1) {
+      const fragment = document.createDocumentFragment();
+      fragment.appendChild(document.importNode(rootElements[0], true));
+      return fragment;
+    }
+    const fragment = document.createDocumentFragment();
+    Array.from(parsed.body.childNodes).forEach(node => {
+      fragment.appendChild(document.importNode(node, true));
+    });
+    return fragment;
+  }
+  async _replaceSelf(fragment, triggerEvent) {
+    const parent = this.parentNode;
+    if (!parent) {
+      return;
+    }
+    const wrapper = document.createElement('span');
+    wrapper.setAttribute('data-fx-include-replacement', '');
+    wrapper.style.display = 'contents';
+    wrapper.appendChild(fragment);
+    this._unbindListener();
+    this.replaceWith(wrapper);
+    this._replaced = true;
+    this._loaded = true;
+    await this._initializeInsertedContent(wrapper);
+    await Fore.dispatch(wrapper, 'include-done', {
+      src: this.src || null,
+      included: wrapper,
+      replaced: true,
+      triggerEvent
+    });
+  }
+  _clearIncludedContent() {
+    this.querySelectorAll(':scope > [data-fx-include-content]').forEach(node => {
+      node.remove();
+    });
+  }
+  async _initializeInsertedContent(startElement) {
+    this._initForeUiDescendants(startElement);
+    const fore = startElement.closest('fx-fore');
+    if (fore?.createNodes && typeof fore.initData === 'function') {
+      fore.initData(startElement);
+    }
+    await Fore.refreshChildren(startElement, true);
+  }
+  _initForeUiDescendants(startElement) {
+    Array.from(startElement.children || []).forEach(element => {
+      if (element.nodeName.toUpperCase() === 'FX-FORE') {
+        return;
+      }
+      if (Fore.isUiElement(element.nodeName) && typeof element.init === 'function') {
+        element.init();
+      }
+      this._initForeUiDescendants(element);
+    });
+  }
+  _dispatchError(message) {
+    Fore.dispatch(this, 'error', {
+      level: 'Error',
+      message
+    });
+  }
+}
+if (!customElements.get('fx-include')) {
+  customElements.define('fx-include', FxInclude);
+}
+
 /**
  * todo: review placing of value. should probably work with value attribute and not allow slotted content.
  */
@@ -31153,6 +31394,13 @@ class FxCase extends FxContainer {
         }
         await parentNode.replaceCase(this, replacement);
         target = replacement;
+        // Re-dispatch 'select' on the loaded replacement so its fx-action handlers fire.
+        // The replacement's handlers are registered after async loading; they miss the
+        // initial 'select' that triggered the load.
+        if (parentNode.selectedCase === replacement) {
+          await Fore.dispatch(replacement, 'select', {});
+          return;
+        }
       }
       ownerForm.getModel();
       ownerForm.addToBatchedNotifications(target);

package/dist/fore.js

@@ -1,4 +1,4 @@
-/* Version: 3.1.2 - May 27, 2026 14:39:34 */
+/* Version: 3.2.1 - June 12, 2026 14:10:38 */
 function t$2(t, s, r, i) {
   const n = {
     op: s,
@@ -20121,7 +20121,7 @@ class Fore {
     return Fore.ACTION_ELEMENTS.includes(elementName);
   }
   static get UI_ELEMENTS() {
-    return new Set(['FX-ALERT', 'FX-CONTROL', 'FX-DIALOG', 'FX-FILENAME', 'FX-MEDIATYPE', 'FX-GROUP', 'FX-HINT', 'FX-ITEMS', 'FX-OUTPUT', 'FX-RANGE', 'FX-REPEAT', 'FX-REPEATITEM', 'FX-REPEAT-ATTRIBUTES', 'FX-SWITCH', 'FX-SECRET', 'FX-SELECT', 'FX-SUBMIT', 'FX-TEXTAREA', 'FX-TRIGGER', 'FX-UPLOAD', 'FX-VAR']);
+    return new Set(['FX-ALERT', 'FX-CONTROL', 'FX-DIALOG', 'FX-FILENAME', 'FX-MEDIATYPE', 'FX-GROUP', 'FX-HINT', 'FX-ITEMS', 'FX-INCLUDE', 'FX-OUTPUT', 'FX-RANGE', 'FX-REPEAT', 'FX-REPEATITEM', 'FX-REPEAT-ATTRIBUTES', 'FX-SWITCH', 'FX-SECRET', 'FX-SELECT', 'FX-SUBMIT', 'FX-TEXTAREA', 'FX-TRIGGER', 'FX-UPLOAD', 'FX-VAR']);
   }
 
   /**
@@ -25425,7 +25425,7 @@ class FxFore extends HTMLElement {
       this._createRepeatsFromAttributes();
       this.inited = true;
     };
-    this.version = 'Version: 3.1.2 - built on May 27, 2026 14:39:34';
+    this.version = 'Version: 3.2.1 - built on June 12, 2026 14:10:38';
 
     /**
      * @type {import('./fx-model.js').FxModel}
@@ -25653,10 +25653,21 @@ class FxFore extends HTMLElement {
     }
     return null;
   }
-  _isReadyTarget(el) {
+  static _isReadyTarget(el) {
     return !!(el && (el.ready === true || el.classList && el.classList.contains('fx-ready') || typeof el.hasAttribute === 'function' && el.hasAttribute('ready')));
   }
 
+  /**
+   * Resolves once `fore` has dispatched its initial `ready` event (or
+   * immediately, if it's already ready).
+   */
+  static waitUntilReady(fore) {
+    if (FxFore._isReadyTarget(fore)) {
+      return Promise.resolve();
+    }
+    return FxFore._waitForEvent(fore, 'ready', FxFore._isReadyTarget);
+  }
+
   /**
    * Collect all init gates derived from attributes.
    *
@@ -25692,7 +25703,7 @@ class FxFore extends HTMLElement {
     }
     return gates;
   }
-  _waitForEvent(target, eventName, isSatisfiedFn = null) {
+  static _waitForEvent(target, eventName, isSatisfiedFn = null) {
     // If a caller provides an explicit satisfaction check, honor it first.
     if (typeof isSatisfiedFn === 'function' && isSatisfiedFn(target)) {
       FxFore._markInitEventSeen(target, eventName);
@@ -25756,19 +25767,19 @@ class FxFore extends HTMLElement {
   }) {
     // Direct targets
     if (targetSpec === 'self') {
-      const satisfied = event === 'ready' ? t => this._isReadyTarget(t) : null;
-      return this._waitForEvent(this, event, satisfied);
+      const satisfied = event === 'ready' ? t => FxFore._isReadyTarget(t) : null;
+      return FxFore._waitForEvent(this, event, satisfied);
     }
     if (targetSpec === 'document') {
-      return this._waitForEvent(document, event);
+      return FxFore._waitForEvent(document, event);
     }
     if (targetSpec === 'window') {
-      return this._waitForEvent(window, event);
+      return FxFore._waitForEvent(window, event);
     }
 
     // Special: closest fx-fore
     if (targetSpec === 'closest') {
-      const recheckFn = event === 'ready' ? () => this._isReadyTarget(this.closest('fx-fore')) : null;
+      const recheckFn = event === 'ready' ? () => FxFore._isReadyTarget(this.closest('fx-fore')) : null;
       const matchesFn = ev => {
         const t = ev.target;
         return t?.tagName === 'FX-FORE' && t.contains(this);
@@ -25778,7 +25789,7 @@ class FxFore extends HTMLElement {
 
     // Selector targets
     const selector = targetSpec;
-    const recheckFn = event === 'ready' ? () => this._isReadyTarget(this._findBySelector(selector)) : null;
+    const recheckFn = event === 'ready' ? () => FxFore._isReadyTarget(this._findBySelector(selector)) : null;
     if (typeof recheckFn === 'function' && recheckFn()) {
       return Promise.resolve();
     }
@@ -26859,7 +26870,7 @@ class FxFore extends HTMLElement {
         bound.evalInContext();
         if (bound.nodeName !== 'FX-REPEAT') {
           // Do not try to get a bind for a nodeSET of a repeat. there are multiple.
-          bound.getModelItem().bind?.evalInContext();
+          bound.getModelItem()?.bind?.evalInContext();
         }
         continue;
       }
@@ -26908,7 +26919,7 @@ class FxFore extends HTMLElement {
         }
       }
       bound.evalInContext();
-      bound.getModelItem().bind?.evalInContext();
+      bound.getModelItem()?.bind?.evalInContext();
       if (!isResolvedBound(bound)) {
         continue;
       }
@@ -31053,6 +31064,13 @@ class FxCase extends FxContainer {
         }
         await parentNode.replaceCase(this, replacement);
         target = replacement;
+        // Re-dispatch 'select' on the loaded replacement so its fx-action handlers fire.
+        // The replacement's handlers are registered after async loading; they miss the
+        // initial 'select' that triggered the load.
+        if (parentNode.selectedCase === replacement) {
+          await Fore.dispatch(replacement, 'select', {});
+          return;
+        }
       }
       ownerForm.getModel();
       ownerForm.addToBatchedNotifications(target);

package/index.js

@@ -14,6 +14,7 @@ import './src/ui/fx-control.js';
 import './src/ui/fx-container.js';
 import './src/ui/fx-group.js';
 import './src/ui/fx-hint.js';
+import './src/ui/fx-include.js';
 import './src/ui/fx-output.js';
 import './src/ui/fx-repeat.js';
 import './src/ui/fx-repeat-attributes.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jinntec/fore",
-  "version": "3.1.2",
+  "version": "3.2.1",
   "description": "Fore - declarative user interfaces in plain HTML",
   "module": "./index.js",
   "publishConfig": {

package/src/fore.js

@@ -239,6 +239,7 @@ export class Fore {
       'FX-GROUP',
       'FX-HINT',
       'FX-ITEMS',
+      'FX-INCLUDE',
       'FX-OUTPUT',
       'FX-RANGE',
       'FX-REPEAT',

package/src/fx-fore.js

@@ -387,7 +387,7 @@ export class FxFore extends HTMLElement {
     return null;
   }
 
-  _isReadyTarget(el) {
+  static _isReadyTarget(el) {
     return !!(
       el &&
       (el.ready === true ||
@@ -396,6 +396,17 @@ export class FxFore extends HTMLElement {
     );
   }
 
+  /**
+   * Resolves once `fore` has dispatched its initial `ready` event (or
+   * immediately, if it's already ready).
+   */
+  static waitUntilReady(fore) {
+    if (FxFore._isReadyTarget(fore)) {
+      return Promise.resolve();
+    }
+    return FxFore._waitForEvent(fore, 'ready', FxFore._isReadyTarget);
+  }
+
   /**
    * Collect all init gates derived from attributes.
    *
@@ -433,7 +444,7 @@ export class FxFore extends HTMLElement {
     return gates;
   }
 
-  _waitForEvent(target, eventName, isSatisfiedFn = null) {
+  static _waitForEvent(target, eventName, isSatisfiedFn = null) {
     // If a caller provides an explicit satisfaction check, honor it first.
     if (typeof isSatisfiedFn === 'function' && isSatisfiedFn(target)) {
       FxFore._markInitEventSeen(target, eventName);
@@ -495,20 +506,20 @@ export class FxFore extends HTMLElement {
   _waitForInitGate({ event, targetSpec }) {
     // Direct targets
     if (targetSpec === 'self') {
-      const satisfied = event === 'ready' ? t => this._isReadyTarget(t) : null;
-      return this._waitForEvent(this, event, satisfied);
+      const satisfied = event === 'ready' ? t => FxFore._isReadyTarget(t) : null;
+      return FxFore._waitForEvent(this, event, satisfied);
     }
     if (targetSpec === 'document') {
-      return this._waitForEvent(document, event);
+      return FxFore._waitForEvent(document, event);
     }
     if (targetSpec === 'window') {
-      return this._waitForEvent(window, event);
+      return FxFore._waitForEvent(window, event);
     }
 
     // Special: closest fx-fore
     if (targetSpec === 'closest') {
       const recheckFn =
-        event === 'ready' ? () => this._isReadyTarget(this.closest('fx-fore')) : null;
+        event === 'ready' ? () => FxFore._isReadyTarget(this.closest('fx-fore')) : null;
 
       const matchesFn = ev => {
         const t = ev.target;
@@ -522,7 +533,7 @@ export class FxFore extends HTMLElement {
     const selector = targetSpec;
 
     const recheckFn =
-      event === 'ready' ? () => this._isReadyTarget(this._findBySelector(selector)) : null;
+      event === 'ready' ? () => FxFore._isReadyTarget(this._findBySelector(selector)) : null;
 
     if (typeof recheckFn === 'function' && recheckFn()) {
       return Promise.resolve();
@@ -1819,7 +1830,7 @@ export class FxFore extends HTMLElement {
         bound.evalInContext();
         if (bound.nodeName !== 'FX-REPEAT') {
           // Do not try to get a bind for a nodeSET of a repeat. there are multiple.
-          bound.getModelItem().bind?.evalInContext();
+          bound.getModelItem()?.bind?.evalInContext();
         }
         continue;
       }
@@ -1878,7 +1889,7 @@ export class FxFore extends HTMLElement {
       }
 
       bound.evalInContext();
-      bound.getModelItem().bind?.evalInContext();
+      bound.getModelItem()?.bind?.evalInContext();
 
       if (!isResolvedBound(bound)) {
         console.warn('create-nodes: could not resolve bound after node creation, skipping', bound);

package/src/ui/fx-case.js

@@ -81,6 +81,13 @@ export class FxCase extends FxContainer {
         }
         await parentNode.replaceCase(this, replacement);
         target = replacement;
+        // Re-dispatch 'select' on the loaded replacement so its fx-action handlers fire.
+        // The replacement's handlers are registered after async loading; they miss the
+        // initial 'select' that triggered the load.
+        if (parentNode.selectedCase === replacement) {
+          await Fore.dispatch(replacement, 'select', {});
+          return;
+        }
       }
       const model = ownerForm.getModel();
       ownerForm.addToBatchedNotifications(target);

package/src/ui/fx-include.js

@@ -0,0 +1,296 @@
+import { Fore } from '../fore.js';
+import { FxFore } from '../fx-fore.js';
+
+/**
+ * <fx-include>
+ *
+ * Lazy light-DOM include component.
+ *
+ * Loads markup either from:
+ *   - a direct child <template>
+ *   - an external HTML document via @src
+ *
+ * Default behavior:
+ *   - listens for an event
+ *   - includes content once
+ *   - removes the event listener afterwards
+ *
+ * With @reload:
+ *   - listens repeatedly
+ *   - clears previously included content
+ *   - includes fresh content again
+ *
+ * Attributes:
+ *   event      Event name to listen for. Defaults to "click".
+ *   target     CSS selector for the event target. Defaults to "self".
+ *              Special values: self, document, window.
+ *   src        Optional external HTML source.
+ *   selector   Optional selector inside external HTML.
+ *   replace    Replace <fx-include> with the included content.
+ *   immediate  Include immediately when connected.
+ *   reload     Re-include on every matching event.
+ */
+export class FxInclude extends HTMLElement {
+  constructor() {
+    super();
+
+    this._listener = this._handleEvent.bind(this);
+    this._eventTarget = null;
+    this._loaded = false;
+    this._replaced = false;
+  }
+
+  connectedCallback() {
+    this.eventName = this.getAttribute('event') || 'click';
+    this.targetSelector = this.getAttribute('target') || 'self';
+    this.src = this.getAttribute('src');
+    this.selector = this.getAttribute('selector');
+
+    this.replace = this.hasAttribute('replace');
+    this.immediate = this.hasAttribute('immediate');
+    this.reload = this.hasAttribute('reload');
+
+    if (this.immediate) {
+      this._includeWhenReady();
+      return;
+    }
+
+    this._bindListener();
+  }
+
+  /**
+   * Includes content immediately, but waits until the closest `fx-fore` has
+   * finished its initial Rebuild/Recalculate/Revalidate/Refresh cycle (i.e. is
+   * "ready"), so the included content can resolve binding context against an
+   * already-initialized ancestor chain.
+   */
+  _includeWhenReady() {
+    const fore = this.closest('fx-fore');
+
+    if (!fore) {
+      queueMicrotask(() => this.include());
+      return;
+    }
+
+    FxFore.waitUntilReady(fore).then(() => this.include());
+  }
+
+  disconnectedCallback() {
+    this._unbindListener();
+  }
+
+  _bindListener() {
+    const target = this._resolveEventTarget();
+
+    if (!target) {
+      this._dispatchError(`fx-include: event target not found: '${this.targetSelector}'`);
+      return;
+    }
+
+    target.addEventListener(this.eventName, this._listener);
+    this._eventTarget = target;
+  }
+
+  _unbindListener() {
+    if (this._eventTarget && this._listener) {
+      this._eventTarget.removeEventListener(this.eventName, this._listener);
+    }
+
+    this._eventTarget = null;
+  }
+
+  _resolveEventTarget() {
+    if (!this.targetSelector || this.targetSelector === 'self') {
+      return this;
+    }
+
+    if (this.targetSelector === 'document') {
+      return document;
+    }
+
+    if (this.targetSelector === 'window') {
+      return window;
+    }
+
+    const fore = this.closest('fx-fore');
+
+    return fore?.querySelector(this.targetSelector) || document.querySelector(this.targetSelector);
+  }
+
+  async _handleEvent(event) {
+    await this.include(event);
+  }
+
+  async include(triggerEvent = null) {
+    if (this._replaced) {
+      return;
+    }
+
+    if (this._loaded && !this.reload) {
+      return;
+    }
+
+    const fragment = this.src ? await this._loadExternalFragment() : this._loadTemplateFragment();
+
+    if (!fragment) {
+      return;
+    }
+
+    if (this.replace) {
+      await this._replaceSelf(fragment, triggerEvent);
+      return;
+    }
+
+    this._clearIncludedContent();
+
+    const wrapper = document.createElement('span');
+    wrapper.setAttribute('data-fx-include-content', '');
+    wrapper.style.display = 'contents';
+    wrapper.appendChild(fragment);
+
+    this.appendChild(wrapper);
+
+    this._loaded = true;
+
+    await this._initializeInsertedContent(wrapper);
+
+    await Fore.dispatch(this, 'include-done', {
+      src: this.src || null,
+      included: wrapper,
+      replaced: false,
+      triggerEvent,
+    });
+
+    if (!this.reload) {
+      this._unbindListener();
+    }
+  }
+
+  _loadTemplateFragment() {
+    const template = this.querySelector(':scope > template');
+
+    if (!template) {
+      this._dispatchError('fx-include: no src and no direct template child found');
+      return null;
+    }
+
+    return template.content.cloneNode(true);
+  }
+
+  async _loadExternalFragment() {
+    const html = await Fore.loadHtml(this.src);
+
+    if (!html) {
+      this._dispatchError(`fx-include: failed to load '${this.src}'`);
+      return null;
+    }
+
+    const parsed = new DOMParser().parseFromString(html, 'text/html');
+
+    if (this.selector) {
+      const selected = parsed.querySelector(this.selector);
+
+      if (!selected) {
+        this._dispatchError(`fx-include: selector '${this.selector}' not found in '${this.src}'`);
+        return null;
+      }
+
+      const fragment = document.createDocumentFragment();
+      fragment.appendChild(document.importNode(selected, true));
+      return fragment;
+    }
+
+    const template = parsed.body.querySelector(':scope > template');
+
+    if (template) {
+      return document.importNode(template.content, true);
+    }
+
+    const rootElements = Array.from(parsed.body.children);
+
+    if (rootElements.length === 1) {
+      const fragment = document.createDocumentFragment();
+      fragment.appendChild(document.importNode(rootElements[0], true));
+      return fragment;
+    }
+
+    const fragment = document.createDocumentFragment();
+
+    Array.from(parsed.body.childNodes).forEach(node => {
+      fragment.appendChild(document.importNode(node, true));
+    });
+
+    return fragment;
+  }
+
+  async _replaceSelf(fragment, triggerEvent) {
+    const parent = this.parentNode;
+
+    if (!parent) {
+      return;
+    }
+
+    const wrapper = document.createElement('span');
+    wrapper.setAttribute('data-fx-include-replacement', '');
+    wrapper.style.display = 'contents';
+    wrapper.appendChild(fragment);
+
+    this._unbindListener();
+
+    this.replaceWith(wrapper);
+
+    this._replaced = true;
+    this._loaded = true;
+
+    await this._initializeInsertedContent(wrapper);
+
+    await Fore.dispatch(wrapper, 'include-done', {
+      src: this.src || null,
+      included: wrapper,
+      replaced: true,
+      triggerEvent,
+    });
+  }
+
+  _clearIncludedContent() {
+    this.querySelectorAll(':scope > [data-fx-include-content]').forEach(node => {
+      node.remove();
+    });
+  }
+
+  async _initializeInsertedContent(startElement) {
+    this._initForeUiDescendants(startElement);
+
+    const fore = startElement.closest('fx-fore');
+    if (fore?.createNodes && typeof fore.initData === 'function') {
+      fore.initData(startElement);
+    }
+
+    await Fore.refreshChildren(startElement, true);
+  }
+
+  _initForeUiDescendants(startElement) {
+    Array.from(startElement.children || []).forEach(element => {
+      if (element.nodeName.toUpperCase() === 'FX-FORE') {
+        return;
+      }
+
+      if (Fore.isUiElement(element.nodeName) && typeof element.init === 'function') {
+        element.init();
+      }
+
+      this._initForeUiDescendants(element);
+    });
+  }
+
+  _dispatchError(message) {
+    Fore.dispatch(this, 'error', {
+      level: 'Error',
+      message,
+    });
+  }
+}
+
+if (!customElements.get('fx-include')) {
+  customElements.define('fx-include', FxInclude);
+}