@panyam/tsappkit 0.2.0 → 0.6.0

package/dist/index.d.mts

@@ -760,6 +760,47 @@ declare class MobileBottomDrawer extends BaseComponent implements LCMComponent {
     getContentContainer(): HTMLElement;
 }
 
+/**
+ * When an island mounts: its `load` in the page spec (goapplib's
+ * page.Island.Load), read and waited for. Every strategy mounts once; an
+ * island isn't unmounted when its media query stops matching.
+ */
+/** A parsed `load`. An empty or missing one is eager. */
+type LoadStrategy = {
+    kind: "eager";
+} | {
+    kind: "idle";
+} | {
+    kind: "visible";
+} | {
+    kind: "media";
+    query: string;
+};
+/**
+ * The strategy `load` names, or null when it isn't one of the forms Go's
+ * Validate accepts (`eager`, `idle`, `visible`, `media:<query>`), compared
+ * exactly.
+ */
+declare function parseLoad(load: string | undefined): LoadStrategy | null;
+/**
+ * The browser APIs scheduleMount waits on, so tests can stand them in.
+ * `requestIdleCallback` is optional because Safari doesn't have it.
+ */
+interface LoadEnv {
+    requestIdleCallback?: (cb: () => void) => unknown;
+    setTimeout: (cb: () => void, ms?: number) => unknown;
+    IntersectionObserver: typeof IntersectionObserver;
+    matchMedia: (query: string) => MediaQueryList;
+}
+/**
+ * Calls `mount` once, when `strategy` says the island in `el` should mount:
+ * at once for eager; when the browser is idle (or on the next task, without
+ * requestIdleCallback) for idle; the first time any of `el` enters the
+ * viewport for visible; and at once if the query matches, or else on the
+ * first change that makes it match, for media.
+ */
+declare function scheduleMount(strategy: LoadStrategy, el: Element, mount: () => void, env?: LoadEnv): void;
+
 /**
  * The page spec: which islands a page mounts, where, and with what config.
  * The server writes it into the page as JSON (goapplib's page.Spec, through
@@ -775,6 +816,12 @@ interface IslandSpec {
     presentation?: string;
     /** Handed to the factory as is. Always an object. */
     config: Record<string, unknown>;
+    /**
+     * When it mounts: `eager` (also when absent), `idle`, `visible` or
+     * `media:<query>` (see parseLoad). IslandPage waits for it; mountIslands
+     * does when given a `defer`.
+     */
+    load?: string;
 }
 interface PageSpec {
     /** The arrangement of slots, for state kept per layout. */
@@ -804,22 +851,65 @@ declare function readSpec<Ext extends object>(text: string | null | undefined, e
  * the app says they are; `bus` is the page's event bus.
  */
 type IslandFactory<Ctx, El, C, B> = (el: El, island: IslandSpec, ctx: Ctx, bus: B) => C;
-/** The islands an entry can mount, by name. An entry bundles only what its registry names. */
-type Registry<Ctx, El, C, B> = Record<string, IslandFactory<Ctx, El, C, B>>;
+declare const LAZY: unique symbol;
+/** A registry entry whose factory is loaded when the island mounts. Made by lazy. */
+interface LazyIsland<Ctx, El, C, B> {
+    readonly [LAZY]: () => Promise<IslandFactory<Ctx, El, C, B> | {
+        default: IslandFactory<Ctx, El, C, B>;
+    }>;
+}
+/**
+ * A registry entry that loads its island's module only when the island
+ * mounts: `hero: lazy(() => import("./islands/hero"))`. With esbuild's
+ * --splitting each such module is its own chunk, so a page downloads only the
+ * islands its spec names, each when its `load` says. `load` resolves to the
+ * factory or to a module whose default export is the factory.
+ *
+ * A lazy island always mounts late, even an eager one, since its chunk
+ * arrives after the page has started; goapplib's page.Assets writes
+ * modulepreload links for the eager ones so that wait is short.
+ */
+declare function lazy<Ctx, El, C, B>(load: () => Promise<IslandFactory<Ctx, El, C, B> | {
+    default: IslandFactory<Ctx, El, C, B>;
+}>): LazyIsland<Ctx, El, C, B>;
+/**
+ * The islands an entry can mount, by name: a factory, bundled with the entry,
+ * or a lazy entry, loaded as its own chunk when the island mounts.
+ */
+type Registry<Ctx, El, C, B> = Record<string, IslandFactory<Ctx, El, C, B> | LazyIsland<Ctx, El, C, B>>;
+/** How mountIslands handles islands that shouldn't mount at once. */
+interface MountOptions<El, C> {
+    /**
+     * Gets each island whose `load` isn't eager, with the slot it will mount
+     * in; call `mount` when it's time (IslandPage passes scheduleMount). An
+     * island with a `load` parseLoad doesn't know is logged and mounted at once
+     * instead, so it still shows up.
+     */
+    defer?: (island: IslandSpec, el: El, mount: () => void) => void;
+    /** Gets what the factory built for each island mounted later: through `defer`, or from a lazy entry. */
+    onLateMount?: (component: C, island: IslandSpec) => void;
+}
 /**
  * Mounts every island in `spec` into the element `findSlot` gives for its
- * slot, and returns what the factories built, in spec order. `context` builds
- * the page's shared services; it's called once, before the first island
- * mounts, and not at all on a page with nothing to mount, so a page without
- * islands doesn't start what they'd share. An island the registry doesn't
- * know, a slot that isn't on the page, or a factory that throws is reported
- * through `log` and skipped, so one bad entry doesn't take the rest of the
- * page down with it.
+ * slot, and returns what the factories built at once, in spec order. With
+ * `options.defer`, an island whose `load` isn't eager is handed to it instead
+ * and reported through `options.onLateMount` when it mounts; without it,
+ * every island mounts now whatever its `load` says. A lazy entry is loaded
+ * when its island would mount and is reported through `onLateMount` too, so
+ * it's never in the returned list.
+ *
+ * `context` builds the page's shared services; it's called once, before the
+ * first island mounts (eager or late), and not at all on a page with nothing
+ * to mount, so a page without islands doesn't start what they'd share. An
+ * island the registry doesn't know, a slot that isn't on the page, or a
+ * factory that throws (now or later), or a lazy entry that fails to load, is
+ * reported through `log` and skipped,
+ * so one bad entry doesn't take the rest of the page down with it.
  *
  * Plain types throughout (no DOM), so it runs under node in tests and on a
  * bare page without BasePage.
  */
-declare function mountIslands<Ctx, El, C, B>(spec: PageSpec, registry: Registry<Ctx, El, C, B>, findSlot: (slot: string) => El | null, context: () => Ctx, bus: B, log: (message: string) => void): C[];
+declare function mountIslands<Ctx, El, C, B>(spec: PageSpec, registry: Registry<Ctx, El, C, B>, findSlot: (slot: string) => El | null, context: () => Ctx, bus: B, log: (message: string) => void, options?: MountOptions<El, C>): C[];
 
 /**
  * A page whose islands come from the page spec. A subclass says which
@@ -832,6 +922,13 @@ declare function mountIslands<Ctx, El, C, B>(spec: PageSpec, registry: Registry<
  * fields in `readExtension`, and they arrive typed as `Ext` on the spec
  * `makeContext` gets.
  *
+ * Each island mounts when its `load` says (`eager`, `idle`, `visible`,
+ * `media:<query>`; see scheduleMount), and a `lazy` registry entry loads its
+ * chunk then. One that mounts later, a lazy eager one included, goes through
+ * its own LifecycleController, so it still gets performLocalInit,
+ * setupDependencies and activate. A deferred island mustn't be something
+ * another island or the page needs at startup: nothing waits for it.
+ *
  * A page with no readable `#page-spec` mounts nothing and warns. Subclasses
  * that override initializeSpecificComponents call super and add to what it
  * returns.
@@ -845,6 +942,11 @@ declare abstract class IslandPage<Ctx, Ext extends object = {}> extends BasePage
      */
     protected readExtension(raw: Record<string, unknown>): Ext;
     protected initializeSpecificComponents(): LCMComponent[];
+    /**
+     * Waits for `strategy` and then calls `mount`. Defaults to scheduleMount
+     * against the window; a subclass or test can replace how the waiting is done.
+     */
+    protected scheduleLoad(strategy: LoadStrategy, el: HTMLElement, mount: () => void): void;
 }
 
 /**
@@ -950,4 +1052,4 @@ declare class KeyboardShortcutManager {
     getCurrentArgs(): string;
 }
 
-export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, LifecycleController, type LifecycleEventType, LifecycleEventTypes, MobileBottomDrawer, Modal, type PageSpec, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, mountIslands, readSpec, shouldIgnoreShortcut };
+export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, type LazyIsland, LifecycleController, type LifecycleEventType, LifecycleEventTypes, type LoadEnv, type LoadStrategy, MobileBottomDrawer, Modal, type MountOptions, type PageSpec, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, lazy, mountIslands, parseLoad, readSpec, scheduleMount, shouldIgnoreShortcut };

package/dist/index.d.ts

@@ -760,6 +760,47 @@ declare class MobileBottomDrawer extends BaseComponent implements LCMComponent {
     getContentContainer(): HTMLElement;
 }
 
+/**
+ * When an island mounts: its `load` in the page spec (goapplib's
+ * page.Island.Load), read and waited for. Every strategy mounts once; an
+ * island isn't unmounted when its media query stops matching.
+ */
+/** A parsed `load`. An empty or missing one is eager. */
+type LoadStrategy = {
+    kind: "eager";
+} | {
+    kind: "idle";
+} | {
+    kind: "visible";
+} | {
+    kind: "media";
+    query: string;
+};
+/**
+ * The strategy `load` names, or null when it isn't one of the forms Go's
+ * Validate accepts (`eager`, `idle`, `visible`, `media:<query>`), compared
+ * exactly.
+ */
+declare function parseLoad(load: string | undefined): LoadStrategy | null;
+/**
+ * The browser APIs scheduleMount waits on, so tests can stand them in.
+ * `requestIdleCallback` is optional because Safari doesn't have it.
+ */
+interface LoadEnv {
+    requestIdleCallback?: (cb: () => void) => unknown;
+    setTimeout: (cb: () => void, ms?: number) => unknown;
+    IntersectionObserver: typeof IntersectionObserver;
+    matchMedia: (query: string) => MediaQueryList;
+}
+/**
+ * Calls `mount` once, when `strategy` says the island in `el` should mount:
+ * at once for eager; when the browser is idle (or on the next task, without
+ * requestIdleCallback) for idle; the first time any of `el` enters the
+ * viewport for visible; and at once if the query matches, or else on the
+ * first change that makes it match, for media.
+ */
+declare function scheduleMount(strategy: LoadStrategy, el: Element, mount: () => void, env?: LoadEnv): void;
+
 /**
  * The page spec: which islands a page mounts, where, and with what config.
  * The server writes it into the page as JSON (goapplib's page.Spec, through
@@ -775,6 +816,12 @@ interface IslandSpec {
     presentation?: string;
     /** Handed to the factory as is. Always an object. */
     config: Record<string, unknown>;
+    /**
+     * When it mounts: `eager` (also when absent), `idle`, `visible` or
+     * `media:<query>` (see parseLoad). IslandPage waits for it; mountIslands
+     * does when given a `defer`.
+     */
+    load?: string;
 }
 interface PageSpec {
     /** The arrangement of slots, for state kept per layout. */
@@ -804,22 +851,65 @@ declare function readSpec<Ext extends object>(text: string | null | undefined, e
  * the app says they are; `bus` is the page's event bus.
  */
 type IslandFactory<Ctx, El, C, B> = (el: El, island: IslandSpec, ctx: Ctx, bus: B) => C;
-/** The islands an entry can mount, by name. An entry bundles only what its registry names. */
-type Registry<Ctx, El, C, B> = Record<string, IslandFactory<Ctx, El, C, B>>;
+declare const LAZY: unique symbol;
+/** A registry entry whose factory is loaded when the island mounts. Made by lazy. */
+interface LazyIsland<Ctx, El, C, B> {
+    readonly [LAZY]: () => Promise<IslandFactory<Ctx, El, C, B> | {
+        default: IslandFactory<Ctx, El, C, B>;
+    }>;
+}
+/**
+ * A registry entry that loads its island's module only when the island
+ * mounts: `hero: lazy(() => import("./islands/hero"))`. With esbuild's
+ * --splitting each such module is its own chunk, so a page downloads only the
+ * islands its spec names, each when its `load` says. `load` resolves to the
+ * factory or to a module whose default export is the factory.
+ *
+ * A lazy island always mounts late, even an eager one, since its chunk
+ * arrives after the page has started; goapplib's page.Assets writes
+ * modulepreload links for the eager ones so that wait is short.
+ */
+declare function lazy<Ctx, El, C, B>(load: () => Promise<IslandFactory<Ctx, El, C, B> | {
+    default: IslandFactory<Ctx, El, C, B>;
+}>): LazyIsland<Ctx, El, C, B>;
+/**
+ * The islands an entry can mount, by name: a factory, bundled with the entry,
+ * or a lazy entry, loaded as its own chunk when the island mounts.
+ */
+type Registry<Ctx, El, C, B> = Record<string, IslandFactory<Ctx, El, C, B> | LazyIsland<Ctx, El, C, B>>;
+/** How mountIslands handles islands that shouldn't mount at once. */
+interface MountOptions<El, C> {
+    /**
+     * Gets each island whose `load` isn't eager, with the slot it will mount
+     * in; call `mount` when it's time (IslandPage passes scheduleMount). An
+     * island with a `load` parseLoad doesn't know is logged and mounted at once
+     * instead, so it still shows up.
+     */
+    defer?: (island: IslandSpec, el: El, mount: () => void) => void;
+    /** Gets what the factory built for each island mounted later: through `defer`, or from a lazy entry. */
+    onLateMount?: (component: C, island: IslandSpec) => void;
+}
 /**
  * Mounts every island in `spec` into the element `findSlot` gives for its
- * slot, and returns what the factories built, in spec order. `context` builds
- * the page's shared services; it's called once, before the first island
- * mounts, and not at all on a page with nothing to mount, so a page without
- * islands doesn't start what they'd share. An island the registry doesn't
- * know, a slot that isn't on the page, or a factory that throws is reported
- * through `log` and skipped, so one bad entry doesn't take the rest of the
- * page down with it.
+ * slot, and returns what the factories built at once, in spec order. With
+ * `options.defer`, an island whose `load` isn't eager is handed to it instead
+ * and reported through `options.onLateMount` when it mounts; without it,
+ * every island mounts now whatever its `load` says. A lazy entry is loaded
+ * when its island would mount and is reported through `onLateMount` too, so
+ * it's never in the returned list.
+ *
+ * `context` builds the page's shared services; it's called once, before the
+ * first island mounts (eager or late), and not at all on a page with nothing
+ * to mount, so a page without islands doesn't start what they'd share. An
+ * island the registry doesn't know, a slot that isn't on the page, or a
+ * factory that throws (now or later), or a lazy entry that fails to load, is
+ * reported through `log` and skipped,
+ * so one bad entry doesn't take the rest of the page down with it.
  *
  * Plain types throughout (no DOM), so it runs under node in tests and on a
  * bare page without BasePage.
  */
-declare function mountIslands<Ctx, El, C, B>(spec: PageSpec, registry: Registry<Ctx, El, C, B>, findSlot: (slot: string) => El | null, context: () => Ctx, bus: B, log: (message: string) => void): C[];
+declare function mountIslands<Ctx, El, C, B>(spec: PageSpec, registry: Registry<Ctx, El, C, B>, findSlot: (slot: string) => El | null, context: () => Ctx, bus: B, log: (message: string) => void, options?: MountOptions<El, C>): C[];
 
 /**
  * A page whose islands come from the page spec. A subclass says which
@@ -832,6 +922,13 @@ declare function mountIslands<Ctx, El, C, B>(spec: PageSpec, registry: Registry<
  * fields in `readExtension`, and they arrive typed as `Ext` on the spec
  * `makeContext` gets.
  *
+ * Each island mounts when its `load` says (`eager`, `idle`, `visible`,
+ * `media:<query>`; see scheduleMount), and a `lazy` registry entry loads its
+ * chunk then. One that mounts later, a lazy eager one included, goes through
+ * its own LifecycleController, so it still gets performLocalInit,
+ * setupDependencies and activate. A deferred island mustn't be something
+ * another island or the page needs at startup: nothing waits for it.
+ *
  * A page with no readable `#page-spec` mounts nothing and warns. Subclasses
  * that override initializeSpecificComponents call super and add to what it
  * returns.
@@ -845,6 +942,11 @@ declare abstract class IslandPage<Ctx, Ext extends object = {}> extends BasePage
      */
     protected readExtension(raw: Record<string, unknown>): Ext;
     protected initializeSpecificComponents(): LCMComponent[];
+    /**
+     * Waits for `strategy` and then calls `mount`. Defaults to scheduleMount
+     * against the window; a subclass or test can replace how the waiting is done.
+     */
+    protected scheduleLoad(strategy: LoadStrategy, el: HTMLElement, mount: () => void): void;
 }
 
 /**
@@ -950,4 +1052,4 @@ declare class KeyboardShortcutManager {
     getCurrentArgs(): string;
 }
 
-export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, LifecycleController, type LifecycleEventType, LifecycleEventTypes, MobileBottomDrawer, Modal, type PageSpec, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, mountIslands, readSpec, shouldIgnoreShortcut };
+export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, type LazyIsland, LifecycleController, type LifecycleEventType, LifecycleEventTypes, type LoadEnv, type LoadStrategy, MobileBottomDrawer, Modal, type MountOptions, type PageSpec, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, lazy, mountIslands, parseLoad, readSpec, scheduleMount, shouldIgnoreShortcut };

package/dist/index.js

@@ -257,9 +257,9 @@ var BaseComponent = class {
   /**
    * Log messages with component identification
    */
-  log(message, data = null) {
+  log(message2, data = null) {
     if (this.debugMode) {
-      console.log(`[${this.componentId}] ${message}`, data);
+      console.log(`[${this.componentId}] ${message2}`, data);
     }
   }
   /**
@@ -437,16 +437,16 @@ var LifecycleController = class {
   /**
    * Log message if debug logging is enabled
    */
-  log(message, ...args) {
+  log(message2, ...args) {
     if (this.config.enableDebugLogging) {
-      console.log(`[LifecycleController] ${message}`, ...args);
+      console.log(`[LifecycleController] ${message2}`, ...args);
     }
   }
   /**
    * Log error message
    */
-  logError(message, error) {
-    console.error(`[LifecycleController] ${message}`, error);
+  logError(message2, error) {
+    console.error(`[LifecycleController] ${message2}`, error);
   }
   /**
    * Get current status of all components
@@ -845,7 +845,7 @@ var _ToastManager = class _ToastManager {
    * @param type Toast type for styling
    * @param duration Duration in ms (default: 4000)
    */
-  showToast(title, message, type = "info", duration = 4e3) {
+  showToast(title, message2, type = "info", duration = 4e3) {
     if (!this.container || !this.template) return "";
     const id = `toast-${Date.now()}-${this.counter++}`;
     const toast = this.template.cloneNode(true);
@@ -854,7 +854,7 @@ var _ToastManager = class _ToastManager {
     const titleElement = toast.querySelector(".toast-title");
     const messageElement = toast.querySelector(".toast-message");
     if (titleElement) titleElement.textContent = title;
-    if (messageElement) messageElement.textContent = message;
+    if (messageElement) messageElement.textContent = message2;
     const iconContainer = toast.querySelector(".flex-shrink-0");
     if (iconContainer) {
       iconContainer.innerHTML = "";
@@ -959,7 +959,7 @@ var SplashScreen = class {
   /**
    * Update the splash screen message (if it hasn't been dismissed yet)
    */
-  static updateMessage(title, message) {
+  static updateMessage(title, message2) {
     if (this.dismissed) {
       return;
     }
@@ -973,10 +973,10 @@ var SplashScreen = class {
         titleEl.textContent = title;
       }
     }
-    if (message) {
+    if (message2) {
       const messageEl = splash.querySelector("[data-splash-message]");
       if (messageEl) {
-        messageEl.textContent = message;
+        messageEl.textContent = message2;
       }
     }
   }
@@ -1091,8 +1091,8 @@ var BasePage = class extends BaseComponent {
   /**
    * Show a toast notification
    */
-  showToast(title, message, type = "info", duration) {
-    this.toastManager?.showToast(title, message, type, duration);
+  showToast(title, message2, type = "info", duration) {
+    this.toastManager?.showToast(title, message2, type, duration);
   }
   /**
    * Show a modal dialog
@@ -1373,13 +1373,68 @@ var MobileBottomDrawer = class extends BaseComponent {
   }
 };
 
+// src/page/load.ts
+function parseLoad(load) {
+  switch (load ?? "") {
+    case "":
+    case "eager":
+      return { kind: "eager" };
+    case "idle":
+      return { kind: "idle" };
+    case "visible":
+      return { kind: "visible" };
+  }
+  const query = load.startsWith("media:") ? load.slice("media:".length) : "";
+  return query.trim() ? { kind: "media", query } : null;
+}
+function scheduleMount(strategy, el, mount, env = window) {
+  switch (strategy.kind) {
+    case "eager":
+      mount();
+      return;
+    case "idle":
+      if (env.requestIdleCallback) env.requestIdleCallback(mount);
+      else env.setTimeout(mount, 1);
+      return;
+    case "visible": {
+      let done = false;
+      const observer = new env.IntersectionObserver((entries) => {
+        if (done || !entries.some((e) => e.isIntersecting)) return;
+        done = true;
+        observer.disconnect();
+        mount();
+      });
+      observer.observe(el);
+      return;
+    }
+    case "media": {
+      const mq = env.matchMedia(strategy.query);
+      if (mq.matches) {
+        mount();
+        return;
+      }
+      const onChange = (e) => {
+        if (!e.matches) return;
+        mq.removeEventListener("change", onChange);
+        mount();
+      };
+      mq.addEventListener("change", onChange);
+      return;
+    }
+  }
+}
+
 // src/page/mount.ts
-function mountIslands(spec, registry, findSlot, context, bus, log) {
+var LAZY = /* @__PURE__ */ Symbol("lazy island");
+function lazy(load) {
+  return { [LAZY]: load };
+}
+function mountIslands(spec, registry, findSlot, context, bus, log, options = {}) {
   const out = [];
   let ctx;
   for (const island of spec.islands) {
-    const factory = Object.prototype.hasOwnProperty.call(registry, island.name) ? registry[island.name] : void 0;
-    if (!factory) {
+    const entry = Object.prototype.hasOwnProperty.call(registry, island.name) ? registry[island.name] : void 0;
+    if (!entry) {
       log(`page spec: no island called "${island.name}" in this page's registry`);
       continue;
     }
@@ -1388,15 +1443,53 @@ function mountIslands(spec, registry, findSlot, context, bus, log) {
       log(`page spec: island "${island.name}" wants slot "${island.slot}", which isn't on the page`);
       continue;
     }
-    try {
-      ctx ?? (ctx = context());
-      out.push(factory(el, island, ctx, bus));
-    } catch (err) {
-      log(`page spec: island "${island.name}" failed to mount: ${err instanceof Error ? err.message : String(err)}`);
+    const build = (factory) => {
+      try {
+        ctx ?? (ctx = context());
+        return factory(el, island, ctx, bus);
+      } catch (err) {
+        log(`page spec: island "${island.name}" failed to mount: ${message(err)}`);
+        return void 0;
+      }
+    };
+    const mountLate = () => {
+      const late = (factory) => {
+        const c2 = build(factory);
+        if (c2 !== void 0) options.onLateMount?.(c2, island);
+      };
+      if (typeof entry === "function") {
+        late(entry);
+        return;
+      }
+      new Promise((resolve) => resolve(entry[LAZY]())).then(
+        (m) => {
+          const factory = typeof m === "function" ? m : m?.default;
+          if (typeof factory === "function") late(factory);
+          else log(`page spec: island "${island.name}" loaded, but its module has no factory (a default export or the function itself)`);
+        },
+        (err) => log(`page spec: island "${island.name}" failed to load: ${message(err)}`)
+      );
+    };
+    const strategy = parseLoad(island.load);
+    if (strategy === null) {
+      log(`page spec: island "${island.name}" has load "${island.load}", which isn't eager, idle, visible or media:<query>; mounting it now`);
+    }
+    if (options.defer && strategy !== null && strategy.kind !== "eager") {
+      options.defer(island, el, mountLate);
+      continue;
     }
+    if (typeof entry !== "function") {
+      mountLate();
+      continue;
+    }
+    const c = build(entry);
+    if (c !== void 0) out.push(c);
   }
   return out;
 }
+function message(err) {
+  return err instanceof Error ? err.message : String(err);
+}
 
 // src/page/spec.ts
 var SPEC_ELEMENT_ID = "page-spec";
@@ -1417,7 +1510,8 @@ function readSpec(text, extend) {
       name: is.name,
       slot: is.slot,
       ...typeof is.presentation === "string" && { presentation: is.presentation },
-      config: isObject(is.config) ? is.config : {}
+      config: isObject(is.config) ? is.config : {},
+      ...typeof is.load === "string" && { load: is.load }
     });
   }
   const spec = { layout: raw.layout, islands };
@@ -1455,9 +1549,22 @@ var IslandPage = class extends BasePage {
       (slot) => document.querySelector(`[data-slot="${slot}"]`),
       () => this.makeContext(spec),
       this.eventBus,
-      (message) => console.warn(message)
+      (message2) => console.warn(message2),
+      {
+        defer: (island, el, mount) => this.scheduleLoad(parseLoad(island.load) ?? { kind: "eager" }, el, mount),
+        onLateMount: (component, island) => {
+          new LifecycleController(this.eventBus, LifecycleController.DefaultConfig).initializeFromRoot(component).catch((err) => console.warn(`page spec: island "${island.name}" failed to start: ${err instanceof Error ? err.message : String(err)}`));
+        }
+      }
     );
   }
+  /**
+   * Waits for `strategy` and then calls `mount`. Defaults to scheduleMount
+   * against the window; a subclass or test can replace how the waiting is done.
+   */
+  scheduleLoad(strategy, el, mount) {
+    scheduleMount(strategy, el, mount);
+  }
 };
 
 // src/DOMUtils.ts
@@ -1820,8 +1927,11 @@ exports.ThemeManager = ThemeManager;
 exports.ToastManager = ToastManager;
 exports.hasModifierKeys = hasModifierKeys;
 exports.isInInputContext = isInInputContext;
+exports.lazy = lazy;
 exports.mountIslands = mountIslands;
+exports.parseLoad = parseLoad;
 exports.readSpec = readSpec;
+exports.scheduleMount = scheduleMount;
 exports.shouldIgnoreShortcut = shouldIgnoreShortcut;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map