stimeo-ui 0.14.0 → 0.16.0

package/dist/controllers/lazy_frame_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/declared_value.ts","../../src/utils/intersection_watcher.ts","../../src/controllers/lazy_frame_controller.ts"],"names":[],"mappings":"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","file":"lazy_frame_controller.js","sourcesContent":["/**\n * Readers for the String Values whose text can only be checked by handing it to\n * a parser: a CSS selector, a regular-expression source, a JSON object.\n *\n * Stimulus reads each of them as an ordinary string, so the controller connects\n * and the flaw surfaces later, inside the first handler that consumes the value\n * (a `SyntaxError` from `new RegExp`, a `DOMException` from the selector engine),\n * where it takes the whole handler down on every event. Parsing here, once, in\n * the `<name>ValueChanged` callback keeps the failure local to the declaration:\n * an unreadable value falls back to its default, the element stays alive, and\n * the hot path only ever receives a value that parsed.\n *\n * Which default a broken declaration falls back to is the caller's contract, so\n * every reader takes (or returns) the fallback rather than choosing one.\n */\n\n/**\n * The result of `parse(raw)`, or `fallback` when `parse` throws.\n *\n * Any exception counts as \"does not parse\": the parsers these Values feed\n * (`RegExp`, `JSON.parse`, the selector engine) all report a malformed input by\n * throwing, and none of them throws for another reason.\n */\nexport function parseDeclared<T>(raw: string, parse: (raw: string) => T, fallback: T): T {\n  try {\n    return parse(raw);\n  } catch {\n    return fallback;\n  }\n}\n\n/** What {@link validSelector} needs of the element it probes with. */\nexport interface SelectorProbe {\n  matches(selector: string): boolean;\n}\n\n/**\n * `raw` when it is a non-empty selector the DOM accepts, otherwise `fallback`.\n *\n * `element.matches` is the probe: the engine parses the selector and throws for\n * one it cannot read. Whether the selector actually matches `element` plays no\n * part, so a selector aimed at another element still passes.\n *\n * The parameter names the one method the probe uses rather than `Element`, so\n * this module carries no DOM type and the readers below stay importable from\n * the Node-side Inspector, which checks the same declarations statically.\n */\nexport function validSelector(element: SelectorProbe, raw: string, fallback: string): string {\n  if (raw.length === 0) return fallback;\n  return parseDeclared(\n    raw,\n    (selector) => {\n      element.matches(selector);\n      return selector;\n    },\n    fallback,\n  );\n}\n\n/** How `compileRegExp` wraps a source before compiling it. */\nexport type RegExpAnchor = \"none\" | \"exact\";\n\n/**\n * `source` compiled as a `RegExp`, or `null` when it does not compile.\n *\n * `\"exact\"` wraps the source as `^(?:source)$`, so the whole input has to match\n * and an alternation inside the source cannot escape the anchors. The source is\n * compiled on its own first, because an unbalanced source can be made to parse\n * by the wrapper's own parentheses — `0)|(1` becomes `^(?:0)|(1)$` — which would\n * accept a declaration that is not a regular expression and leave half of it\n * outside the anchors. The default that replaces a broken source is the\n * caller's, so `null` is returned rather than a fallback pattern.\n */\nexport function compileRegExp(source: string, anchor: RegExpAnchor = \"none\"): RegExp | null {\n  return parseDeclared(\n    source,\n    (text) => {\n      const bare = new RegExp(text);\n      return anchor === \"exact\" ? new RegExp(`^(?:${text})$`) : bare;\n    },\n    null,\n  );\n}\n\n/**\n * The JSON object `raw` declares, or `null` when the text does not parse or\n * parses to something other than a plain object (`null`, an array, a scalar).\n * Values are returned as parsed; narrowing them is the caller's contract.\n */\nexport function parseJsonObject(raw: string): Record<string, unknown> | null {\n  const parsed = parseDeclared<unknown>(raw, (text) => JSON.parse(text), null);\n  if (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) return null;\n  return parsed as Record<string, unknown>;\n}\n","/**\n * Shared `IntersectionObserver` plumbing for Stimeo's scroll-triggered\n * controllers (`intersection`, `scrollspy`, `sticky-observer`, `lazy-frame`).\n *\n * It centralizes the `IntersectionObserver` support guard, root resolution from\n * a selector (degrading to the viewport rather than failing), observer\n * creation/teardown, the **active guard** (the browser may\n * flush a final queued callback batch right after `disconnect()`, and a\n * detached controller must not mutate possibly-cached DOM), and the\n * unobserve→observe **re-arm** that re-delivers the current state even when the\n * target never leaves the viewport.\n *\n * Like `RovingTabindex` and `FocusTrap`, this is a policy-free internal\n * util: what an intersection *means* (a spied link, a stuck header, a lazy\n * load) stays in each controller. The public `stimeo--intersection` controller\n * is its thin declarative face.\n */\n\nimport { parseDeclared } from \"./declared_value\";\n\n/**\n * Whether `entry`'s target sits entirely before the root's **start (top)** edge —\n * the \"scrolled past the top\" half of a non-intersecting entry, as opposed to\n * \"not reached yet\" below the root.\n *\n * A target with no layout box (`display: none`, a `hidden` ancestor, a collapsed\n * `<details>`) is reported with an **empty rect**, whose `bottom` of `0` would\n * otherwise satisfy `bottom <= rootTop` for a viewport root and read as \"passed\"\n * even though the target was never scrolled anywhere. An empty rect carries no\n * position at all, so it is deliberately never \"before the edge\"; what a caller\n * publishes for that case is its own policy (both consumers treat it as the\n * neutral \"not passed\"/\"not stuck\", and the real rect that arrives once the\n * target is laid out re-establishes the true state).\n */\nexport function isBeforeRootStart(entry: IntersectionObserverEntry): boolean {\n  const rect = entry.boundingClientRect;\n  if (rect.width === 0 && rect.height === 0) return false;\n  // rootBounds is null for a cross-origin/removed root; fall back to the\n  // viewport origin.\n  const rootTop = entry.rootBounds?.top ?? 0;\n  return rect.bottom <= rootTop;\n}\n\n/**\n * Resolves an observation root from a selector. Every reading of \"no root\" ends\n * at the same place — absent, matching nothing, or not parsing at all (a typo in\n * a data attribute) — so the observation falls back to the viewport instead of\n * leaving the caller inert with no state hooks published at all.\n */\nfunction queryRoot(selector: string | undefined): Element | null {\n  if (!selector) return null;\n  return parseDeclared(selector, (raw) => document.querySelector(raw), null);\n}\n\nexport interface IntersectionWatchOptions {\n  /**\n   * The observation root. Pass an element (or `null` for the viewport) when\n   * the caller already resolved it; omit to resolve from `rootSelector`.\n   */\n  root?: Element | null;\n  /**\n   * Selector for the observation root; empty/omitted = viewport. A selector\n   * that matches nothing or does not parse also means the viewport.\n   */\n  rootSelector?: string;\n  rootMargin?: string;\n  threshold?: number | number[];\n}\n\nexport class IntersectionWatcher {\n  readonly #onEntries: (entries: IntersectionObserverEntry[]) => void;\n  #observer: IntersectionObserver | null = null;\n  #active = false;\n  #usingPlatformDefaults = false;\n\n  constructor(onEntries: (entries: IntersectionObserverEntry[]) => void) {\n    this.#onEntries = onEntries;\n  }\n\n  /** Whether an observer is live (started, `IntersectionObserver` supported). */\n  get active(): boolean {\n    return this.#active;\n  }\n\n  /** Whether the live observer discarded configured options after construction failed. */\n  get usingPlatformDefaults(): boolean {\n    return this.#usingPlatformDefaults;\n  }\n\n  /**\n   * (Re)creates the observer and observes `targets`. Returns `false` — leaving\n   * the watcher inert — without `IntersectionObserver` support (very old\n   * browsers; the caller's no-JS fallback stays in charge) or with no targets.\n   * If initial construction with the configured options fails, the watcher\n   * warns and retries once with the same root and platform defaults. A\n   * `rootSelector` that does not parse resolves to the viewport (see\n   * {@link IntersectionWatchOptions.rootSelector}), so a typo never fails the\n   * call.\n   *\n   * @throws The fallback constructor error if both construction attempts fail,\n   *   or whatever the platform throws from `observe()`. The exception is passed\n   *   through unchanged, but the watcher rolls back first: every target observed\n   *   so far is released and `active` stays `false`, so a caller that retries\n   *   starts from a clean slate.\n   */\n  start(targets: Element | readonly Element[], options: IntersectionWatchOptions = {}): boolean {\n    this.stop();\n    if (typeof IntersectionObserver === \"undefined\") return false;\n    const list = Array.isArray(targets) ? (targets as readonly Element[]) : [targets as Element];\n    if (list.length === 0) return false;\n\n    const root = \"root\" in options ? (options.root ?? null) : queryRoot(options.rootSelector);\n\n    let observer: IntersectionObserver | null = null;\n    try {\n      const onEntries = (entries: IntersectionObserverEntry[]): void => {\n        // Identity matters across an immediate restart: the old observer can\n        // flush a queued batch after the new observer has made `active` true.\n        if (this.#active && this.#observer === observer) this.#onEntries(entries);\n      };\n      try {\n        observer = new IntersectionObserver(onEntries, {\n          root,\n          rootMargin: options.rootMargin,\n          threshold: options.threshold,\n        });\n      } catch (error) {\n        console.warn(\n          \"Stimeo UI: IntersectionObserver could not be constructed with the configured options; retrying with platform defaults.\",\n          error,\n        );\n        observer = new IntersectionObserver(onEntries, { root });\n        this.#usingPlatformDefaults = true;\n      }\n      for (const target of list) observer.observe(target);\n      this.#observer = observer;\n      this.#active = true;\n      return true;\n    } catch (error) {\n      // A constructor or partial observe failure must not leave earlier targets\n      // observed or report an active watcher. Preserve the platform exception.\n      observer?.disconnect();\n      this.#observer = null;\n      this.#active = false;\n      this.#usingPlatformDefaults = false;\n      throw error;\n    }\n  }\n\n  /**\n   * Re-delivers `target`'s CURRENT intersection state: `IntersectionObserver`\n   * only reports *changes*, but `observe()` always reports the present state,\n   * so unobserve→observe turns \"still intersecting\" into a fresh callback.\n   *\n   * @throws Whatever `unobserve()`/`observe()` throws. The watcher is stopped\n   *   first, so it never stays live with a half-rearmed target.\n   */\n  rearm(target: Element): void {\n    if (!this.#observer) return;\n    try {\n      this.#observer.unobserve(target);\n      this.#observer.observe(target);\n    } catch (error) {\n      this.stop();\n      throw error;\n    }\n  }\n\n  /** Severs the observer; late queued callbacks become no-ops via the guard. */\n  stop(): void {\n    this.#active = false;\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#usingPlatformDefaults = false;\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { IntersectionWatcher } from \"../utils/intersection_watcher\";\n\n/**\n * Headless **lazy frame**: defers a `<turbo-frame>`'s load until it nears the viewport\n * (or focus reaches it), to keep the initial render light. Turbo's own `loading=\"lazy\"`\n * observes with no margin, so the frame loads only once it is already in view; this\n * drives an explicit `IntersectionObserver` with a configurable `rootMargin`, plus a focus fallback so keyboard /\n * assistive-tech users trigger the load too (no APG pattern).\n *\n * Markup contract (identifier: `stimeo--lazy-frame`):\n *   <turbo-frame id=\"comments\" data-controller=\"stimeo--lazy-frame\"\n *     data-stimeo--lazy-frame-url-value=\"/posts/1/comments\"\n *     data-stimeo--lazy-frame-root-margin-value=\"200px\">Loading…</turbo-frame>\n *\n * The URL is *held* in the `url` value (not on `src`) so Turbo does not load it eagerly;\n * when the frame intersects (within `rootMargin`) or focus enters it, the controller\n * writes `url` to `src` — **writing `src` is what starts the fetch** — marks\n * `data-lazy-loaded`, and emits `load`. Focus is the fallback for the *first* load only;\n * once the frame has loaded, its listener is released and further focus moves inside the\n * frame change nothing.\n *\n * With `once` (default) the controller then stops observing. With `once` off it keeps\n * watching and re-fetches on a **re-entry** — the frame has to be seen inside the\n * observed area, leave it, and come back. Where a connection first finds the frame is the\n * baseline rather than a movement, so a focus-started load and a cache restore each begin\n * the visit wherever the frame sits — in view or out of it — and re-fetch nothing until it\n * leaves and returns. A re-entry serves the held `url`: when it still matches `src`, the\n * host's own `reload()` refetches it; when it has moved on, writing the new `url` to `src`\n * is the fetch.\n *\n * `load` dispatches `{ url }` — always the URL the fetch actually started for.\n *\n * @remarks\n * Behavior only — the load itself and the frame's content are Turbo's / the server's job,\n * and the loading UI (skeleton / `aria-busy`) belongs to `stimeo--frame-loading`. The trigger\n * is idempotent (`data-lazy-loaded` guards a double load and is the truth source on a\n * Turbo cache restore: a restored frame is observed again only while `once` is off, which\n * is the mode that asked to keep re-fetching). An empty `url` arms nothing and is never\n * written to `src`. The `IntersectionObserver` and focus listener are released once loaded\n * (when `once`) and on `disconnect()` (Turbo navigation included).\n */\nexport class LazyFrameController extends Controller<HTMLElement> {\n  static override values = {\n    url: { type: String, default: \"\" },\n    rootMargin: { type: String, default: \"0px\" },\n    once: { type: Boolean, default: true },\n  };\n  static events = [\"load\"] as const;\n\n  declare urlValue: string;\n  declare rootMarginValue: string;\n  declare onceValue: boolean;\n\n  /** Shared IO plumbing (support guard, active guard, teardown). */\n  readonly #watcher = new IntersectionWatcher((entries) => this.#onIntersect(entries));\n  #connected = false;\n  #loaded = false;\n  /**\n   * Whether the observer last saw the frame inside the observed area — `null`\n   * until it has reported. A re-entry needs a frame that was seen inside and\n   * then left, so an unknown position is never a departure.\n   */\n  #inside: boolean | null = null;\n\n  /**\n   * Focus reaching the frame starts the FIRST load before it intersects (keyboard / AT).\n   * `#load` releases this listener, so focus never reaches an already-loaded frame.\n   */\n  readonly #onFocus = (): void => this.#load();\n\n  /**\n   * Follows the held URL at runtime: one that arrives arms the frame, one that is\n   * taken away disarms it, so an empty `url` holds no triggers either way.\n   *\n   * Stimulus runs value callbacks before `connect()`, so the connected guard keeps\n   * arming in one place. A frame that already loaded keeps its held URL for the next\n   * re-entry instead of fetching on the spot.\n   */\n  urlValueChanged(): void {\n    if (!this.#connected || this.#loaded) return;\n    if (this.urlValue) this.#arm();\n    else this.#stopObserving();\n  }\n\n  /** Rebuilds the observer when the early-load margin changes at runtime. */\n  rootMarginValueChanged(): void {\n    if (this.#connected && this.#watcher.active) this.#observe();\n  }\n\n  override connect(): void {\n    // `data-lazy-loaded` is the truth source across a cache restore, and `once`\n    // decides whether a restored frame still has anything to watch for.\n    this.#loaded = this.element.hasAttribute(\"data-lazy-loaded\");\n    this.#inside = null;\n    this.#connected = true;\n    if (this.#loaded && this.onceValue) return;\n    this.#arm();\n  }\n\n  override disconnect(): void {\n    this.#connected = false;\n    this.#stopObserving();\n  }\n\n  /** Attaches the triggers that still have a job to do. */\n  #arm(): void {\n    if (!this.urlValue) return;\n    if (!this.#loaded) this.element.addEventListener(\"focusin\", this.#onFocus);\n    this.#observe();\n  }\n\n  #observe(): void {\n    this.#watcher.start(this.element, { rootMargin: this.rootMarginValue });\n  }\n\n  #onIntersect(entries: IntersectionObserverEntry[]): void {\n    for (const entry of entries) {\n      if (entry.isIntersecting) {\n        const returning = this.#inside === false;\n        this.#inside = true;\n        this.#enter(returning);\n      } else if (this.#inside) {\n        // An observer reports where the frame is before it reports any movement,\n        // so only a frame already seen inside can be leaving.\n        this.#inside = false;\n      }\n    }\n  }\n\n  /** Applies an intersecting entry: the first one loads, a return re-fetches. */\n  #enter(returning: boolean): void {\n    if (!this.#loaded) {\n      this.#load();\n      return;\n    }\n    if (this.onceValue || !returning) return;\n    this.#reload();\n  }\n\n  /** Starts the load by writing the held URL to `src`. */\n  #load(): void {\n    if (!this.urlValue) return;\n    this.#loaded = true;\n    this.element.setAttribute(\"src\", this.urlValue);\n    this.element.setAttribute(\"data-lazy-loaded\", \"true\");\n    this.dispatch(\"load\", { detail: { url: this.urlValue } });\n    // The focus fallback exists to start the first load; it has nothing left to do.\n    this.element.removeEventListener(\"focusin\", this.#onFocus);\n    if (this.onceValue) this.#watcher.stop();\n  }\n\n  /** Re-entry while `once` is off: fetch the held URL again. */\n  #reload(): void {\n    const src = this.element.getAttribute(\"src\");\n    if (this.urlValue && this.urlValue !== src) {\n      // The held URL moved on. Writing it to `src` is the fetch, the same start\n      // the first load uses, so it works on any host.\n      this.element.setAttribute(\"src\", this.urlValue);\n      this.dispatch(\"load\", { detail: { url: this.urlValue } });\n      return;\n    }\n    const frame = this.element as HTMLElement & { reload?: () => void };\n    // Refetching the URL already on `src` needs the host's own `reload()`. On a\n    // non-`<turbo-frame>` host there is none, and firing `load` would announce a\n    // fetch that never started.\n    if (typeof frame.reload !== \"function\") return;\n    frame.reload();\n    this.dispatch(\"load\", { detail: { url: src ?? \"\" } });\n  }\n\n  #stopObserving(): void {\n    this.#watcher.stop();\n    this.element.removeEventListener(\"focusin\", this.#onFocus);\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/declared_value.ts","../../src/utils/intersection_watcher.ts","../../src/controllers/lazy_frame_controller.ts"],"names":[],"mappings":"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","file":"lazy_frame_controller.js","sourcesContent":["/**\n * Readers for the String Values whose text can only be checked by handing it to\n * a parser: a CSS selector, a regular-expression source, a JSON object.\n *\n * Stimulus reads each of them as an ordinary string, so the controller connects\n * and the flaw surfaces later, inside the first handler that consumes the value\n * (a `SyntaxError` from `new RegExp`, a `DOMException` from the selector engine),\n * where it takes the whole handler down on every event. Parsing here, once, in\n * the `<name>ValueChanged` callback keeps the failure local to the declaration:\n * an unreadable value falls back to its default, the element stays alive, and\n * the hot path only ever receives a value that parsed.\n *\n * Which default a broken declaration falls back to is the caller's contract, so\n * every reader takes (or returns) the fallback rather than choosing one.\n */\n\n/**\n * The result of `parse(raw)`, or `fallback` when `parse` throws.\n *\n * Any exception counts as \"does not parse\": the parsers these Values feed\n * (`RegExp`, `JSON.parse`, the selector engine) all report a malformed input by\n * throwing, and none of them throws for another reason.\n */\nexport function parseDeclared<T>(raw: string, parse: (raw: string) => T, fallback: T): T {\n  try {\n    return parse(raw);\n  } catch {\n    return fallback;\n  }\n}\n\n/** What {@link validSelector} needs of the element it probes with. */\nexport interface SelectorProbe {\n  matches(selector: string): boolean;\n}\n\n/**\n * `raw` when it is a non-empty selector the DOM accepts, otherwise `fallback`.\n *\n * `element.matches` is the probe: the engine parses the selector and throws for\n * one it cannot read. Whether the selector actually matches `element` plays no\n * part, so a selector aimed at another element still passes.\n *\n * The parameter names the one method the probe uses rather than `Element`, so\n * this module carries no DOM type and the readers below stay importable from\n * the Node-side Inspector, which checks the same declarations statically.\n */\nexport function validSelector(element: SelectorProbe, raw: string, fallback: string): string {\n  if (raw.length === 0) return fallback;\n  return parseDeclared(\n    raw,\n    (selector) => {\n      element.matches(selector);\n      return selector;\n    },\n    fallback,\n  );\n}\n\n/** How `compileRegExp` wraps a source before compiling it. */\nexport type RegExpAnchor = \"none\" | \"exact\";\n\n/**\n * `source` compiled as a `RegExp`, or `null` when it does not compile.\n *\n * `\"exact\"` wraps the source as `^(?:source)$`, so the whole input has to match\n * and an alternation inside the source cannot escape the anchors. The source is\n * compiled on its own first, because an unbalanced source can be made to parse\n * by the wrapper's own parentheses — `0)|(1` becomes `^(?:0)|(1)$` — which would\n * accept a declaration that is not a regular expression and leave half of it\n * outside the anchors. The default that replaces a broken source is the\n * caller's, so `null` is returned rather than a fallback pattern.\n */\nexport function compileRegExp(source: string, anchor: RegExpAnchor = \"none\"): RegExp | null {\n  return parseDeclared(\n    source,\n    (text) => {\n      const bare = new RegExp(text);\n      return anchor === \"exact\" ? new RegExp(`^(?:${text})$`) : bare;\n    },\n    null,\n  );\n}\n\n/**\n * The JSON object `raw` declares, or `null` when the text does not parse or\n * parses to something other than a plain object (`null`, an array, a scalar).\n * Values are returned as parsed; narrowing them is the caller's contract.\n */\nexport function parseJsonObject(raw: string): Record<string, unknown> | null {\n  const parsed = parseDeclared<unknown>(raw, (text) => JSON.parse(text), null);\n  if (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) return null;\n  return parsed as Record<string, unknown>;\n}\n","/**\n * Shared `IntersectionObserver` plumbing for Stimeo's scroll-triggered\n * controllers (`intersection`, `scrollspy`, `sticky-observer`, `lazy-frame`).\n *\n * It centralizes the `IntersectionObserver` support guard, root resolution from\n * a selector (degrading to the viewport rather than failing), observer\n * creation/teardown, the **active guard** (the browser may\n * flush a final queued callback batch right after `disconnect()`, and a\n * detached controller must not mutate possibly-cached DOM), and the\n * unobserve→observe **re-arm** that re-delivers the current state even when the\n * target never leaves the viewport.\n *\n * Like `RovingTabindex` and `FocusTrap`, this is a policy-free internal\n * util: what an intersection *means* (a spied link, a stuck header, a lazy\n * load) stays in each controller. The public `stimeo--intersection` controller\n * is its thin declarative face.\n */\n\nimport { parseDeclared } from \"./declared_value\";\n\n/**\n * Whether `entry`'s target sits entirely before the root's **start (top)** edge —\n * the \"scrolled past the top\" half of a non-intersecting entry, as opposed to\n * \"not reached yet\" below the root.\n *\n * A target with no layout box (`display: none`, a `hidden` ancestor, a collapsed\n * `<details>`) is reported with an **empty rect**, whose `bottom` of `0` would\n * otherwise satisfy `bottom <= rootTop` for a viewport root and read as \"passed\"\n * even though the target was never scrolled anywhere. An empty rect carries no\n * position at all, so it is deliberately never \"before the edge\"; what a caller\n * publishes for that case is its own policy (both consumers treat it as the\n * neutral \"not passed\"/\"not stuck\", and the real rect that arrives once the\n * target is laid out re-establishes the true state).\n */\nexport function isBeforeRootStart(entry: IntersectionObserverEntry): boolean {\n  const rect = entry.boundingClientRect;\n  if (rect.width === 0 && rect.height === 0) return false;\n  // rootBounds is null for a cross-origin/removed root; fall back to the\n  // viewport origin.\n  const rootTop = entry.rootBounds?.top ?? 0;\n  return rect.bottom <= rootTop;\n}\n\n/**\n * Resolves an observation root from a selector. Every reading of \"no root\" ends\n * at the same place — absent, matching nothing, or not parsing at all (a typo in\n * a data attribute) — so the observation falls back to the viewport instead of\n * leaving the caller inert with no state hooks published at all.\n */\nfunction queryRoot(selector: string | undefined): Element | null {\n  if (!selector) return null;\n  return parseDeclared(selector, (raw) => document.querySelector(raw), null);\n}\n\nexport interface IntersectionWatchOptions {\n  /**\n   * The observation root. Pass an element (or `null` for the viewport) when\n   * the caller already resolved it; omit to resolve from `rootSelector`.\n   */\n  root?: Element | null;\n  /**\n   * Selector for the observation root; empty/omitted = viewport. A selector\n   * that matches nothing or does not parse also means the viewport.\n   */\n  rootSelector?: string;\n  rootMargin?: string;\n  threshold?: number | number[];\n}\n\nexport class IntersectionWatcher {\n  readonly #onEntries: (entries: IntersectionObserverEntry[]) => void;\n  #observer: IntersectionObserver | null = null;\n  #active = false;\n  #usingPlatformDefaults = false;\n\n  constructor(onEntries: (entries: IntersectionObserverEntry[]) => void) {\n    this.#onEntries = onEntries;\n  }\n\n  /** Whether an observer is live (started, `IntersectionObserver` supported). */\n  get active(): boolean {\n    return this.#active;\n  }\n\n  /** Whether the live observer discarded configured options after construction failed. */\n  get usingPlatformDefaults(): boolean {\n    return this.#usingPlatformDefaults;\n  }\n\n  /**\n   * (Re)creates the observer and observes `targets`. Returns `false` — leaving\n   * the watcher inert — without `IntersectionObserver` support (very old\n   * browsers; the caller's no-JS fallback stays in charge) or with no targets.\n   * If initial construction with the configured options fails, the watcher\n   * warns and retries once with the same root and platform defaults. A\n   * `rootSelector` that does not parse resolves to the viewport (see\n   * {@link IntersectionWatchOptions.rootSelector}), so a typo never fails the\n   * call.\n   *\n   * @throws The fallback constructor error if both construction attempts fail,\n   *   or whatever the platform throws from `observe()`. The exception is passed\n   *   through unchanged, but the watcher rolls back first: every target observed\n   *   so far is released and `active` stays `false`, so a caller that retries\n   *   starts from a clean slate.\n   */\n  start(targets: Element | readonly Element[], options: IntersectionWatchOptions = {}): boolean {\n    this.stop();\n    if (typeof IntersectionObserver === \"undefined\") return false;\n    const list = Array.isArray(targets) ? (targets as readonly Element[]) : [targets as Element];\n    if (list.length === 0) return false;\n\n    const root = \"root\" in options ? (options.root ?? null) : queryRoot(options.rootSelector);\n\n    let observer: IntersectionObserver | null = null;\n    try {\n      const onEntries = (entries: IntersectionObserverEntry[]): void => {\n        // Identity matters across an immediate restart: the old observer can\n        // flush a queued batch after the new observer has made `active` true.\n        if (this.#active && this.#observer === observer) this.#onEntries(entries);\n      };\n      try {\n        observer = new IntersectionObserver(onEntries, {\n          root,\n          rootMargin: options.rootMargin,\n          threshold: options.threshold,\n        });\n      } catch (error) {\n        console.warn(\n          \"Stimeo UI: IntersectionObserver could not be constructed with the configured options; retrying with platform defaults.\",\n          error,\n        );\n        observer = new IntersectionObserver(onEntries, { root });\n        this.#usingPlatformDefaults = true;\n      }\n      for (const target of list) observer.observe(target);\n      this.#observer = observer;\n      this.#active = true;\n      return true;\n    } catch (error) {\n      // A constructor or partial observe failure must not leave earlier targets\n      // observed or report an active watcher. Preserve the platform exception.\n      observer?.disconnect();\n      this.#observer = null;\n      this.#active = false;\n      this.#usingPlatformDefaults = false;\n      throw error;\n    }\n  }\n\n  /**\n   * Re-delivers `target`'s CURRENT intersection state: `IntersectionObserver`\n   * only reports *changes*, but `observe()` always reports the present state,\n   * so unobserve→observe turns \"still intersecting\" into a fresh callback.\n   *\n   * @throws Whatever `unobserve()`/`observe()` throws. The watcher is stopped\n   *   first, so it never stays live with a half-rearmed target.\n   */\n  rearm(target: Element): void {\n    if (!this.#observer) return;\n    try {\n      this.#observer.unobserve(target);\n      this.#observer.observe(target);\n    } catch (error) {\n      this.stop();\n      throw error;\n    }\n  }\n\n  /** Severs the observer; late queued callbacks become no-ops via the guard. */\n  stop(): void {\n    this.#active = false;\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#usingPlatformDefaults = false;\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { IntersectionWatcher } from \"../utils/intersection_watcher\";\n\n/**\n * Headless **lazy frame**: defers a `<turbo-frame>`'s load until it nears the viewport\n * (or focus reaches it), to keep the initial render light. Turbo's own `loading=\"lazy\"`\n * observes with no margin, so the frame loads only once it is already in view; this\n * drives an explicit `IntersectionObserver` with a configurable `rootMargin`, plus a focus fallback so keyboard /\n * assistive-tech users trigger the load too (no APG pattern).\n *\n * Markup contract (identifier: `stimeo--lazy-frame`):\n *   <turbo-frame id=\"comments\" data-controller=\"stimeo--lazy-frame\"\n *     data-stimeo--lazy-frame-url-value=\"/posts/1/comments\"\n *     data-stimeo--lazy-frame-root-margin-value=\"200px\">Loading…</turbo-frame>\n *\n * The URL is *held* in the `url` value (not on `src`) so Turbo does not load it eagerly;\n * when the frame intersects (within `rootMargin`) or focus enters it, the controller\n * writes `url` to `src` — **writing `src` is what starts the fetch** — marks\n * `data-lazy-loaded`, and emits `load`. Focus is the fallback for the *first* load only;\n * once the frame has loaded, its listener is released and further focus moves inside the\n * frame change nothing.\n *\n * With `once` (default) the controller then stops observing. With `once` off it keeps\n * watching and re-fetches on a **re-entry** — the frame has to be seen inside the\n * observed area, leave it, and come back. Where a connection first finds the frame is the\n * baseline rather than a movement, so a focus-started load and a cache restore each begin\n * the visit wherever the frame sits — in view or out of it — and re-fetch nothing until it\n * leaves and returns. A re-entry serves the held `url`: when it still matches `src`, the\n * host's own `reload()` refetches it; when it has moved on, writing the new `url` to `src`\n * is the fetch.\n *\n * `load` dispatches `{ url }` — always the URL the fetch actually started for.\n *\n * @remarks\n * Behavior only — the load itself and the frame's content are Turbo's / the server's job,\n * and the loading UI (skeleton / `aria-busy`) belongs to `stimeo--frame-loading`. The trigger\n * is idempotent (`data-lazy-loaded` guards a double load and is the truth source on a\n * Turbo cache restore: a restored frame is observed again only while `once` is off, which\n * is the mode that asked to keep re-fetching). An empty `url` arms nothing and is never\n * written to `src`. The `IntersectionObserver` and focus listener are released once loaded\n * (when `once`) and on `disconnect()` (Turbo navigation included).\n */\nexport class LazyFrameController extends Controller<HTMLElement> {\n  static override values = {\n    url: { type: String, default: \"\" },\n    rootMargin: { type: String, default: \"0px\" },\n    once: { type: Boolean, default: true },\n  };\n  static events = [\"load\"] as const;\n\n  declare urlValue: string;\n  declare rootMarginValue: string;\n  declare onceValue: boolean;\n\n  /** Shared IO plumbing (support guard, active guard, teardown). */\n  readonly #watcher = new IntersectionWatcher((entries) => this.#onIntersect(entries));\n  #connected = false;\n  #loaded = false;\n  /**\n   * Whether the observer last saw the frame inside the observed area — `null`\n   * until it has reported. A re-entry needs a frame that was seen inside and\n   * then left, so an unknown position is never a departure.\n   */\n  #inside: boolean | null = null;\n\n  /**\n   * Focus reaching the frame starts the FIRST load before it intersects (keyboard / AT).\n   * `#load` releases this listener, so focus never reaches an already-loaded frame.\n   */\n  readonly #onFocus = (): void => this.#load();\n\n  /**\n   * Follows the held URL at runtime: one that arrives arms the frame, one that is\n   * taken away disarms it, so an empty `url` holds no triggers either way.\n   *\n   * Stimulus runs value callbacks before `connect()`, so the connected guard keeps\n   * arming in one place. A frame that already loaded keeps its held URL for the next\n   * re-entry instead of fetching on the spot.\n   */\n  urlValueChanged(): void {\n    if (!this.#connected || this.#loaded) return;\n    if (this.urlValue) this.#arm();\n    else this.#stopObserving();\n  }\n\n  /** Rebuilds the observer when the early-load margin changes at runtime. */\n  rootMarginValueChanged(): void {\n    if (this.#connected && this.#watcher.active) this.#observe();\n  }\n\n  override connect(): void {\n    // `data-lazy-loaded` is the truth source across a cache restore, and `once`\n    // decides whether a restored frame still has anything to watch for.\n    this.#loaded = this.element.hasAttribute(\"data-lazy-loaded\");\n    this.#inside = null;\n    this.#connected = true;\n    if (this.#loaded && this.onceValue) return;\n    this.#arm();\n  }\n\n  override disconnect(): void {\n    this.#connected = false;\n    this.#stopObserving();\n  }\n\n  /** Attaches the triggers that still have a job to do. */\n  #arm(): void {\n    if (!this.urlValue) return;\n    if (!this.#loaded) this.element.addEventListener(\"focusin\", this.#onFocus);\n    this.#observe();\n  }\n\n  #observe(): void {\n    this.#watcher.start(this.element, { rootMargin: this.rootMarginValue });\n  }\n\n  #onIntersect(entries: IntersectionObserverEntry[]): void {\n    for (const entry of entries) {\n      if (entry.isIntersecting) {\n        const returning = this.#inside === false;\n        this.#inside = true;\n        this.#enter(returning);\n      } else if (this.#inside) {\n        // An observer reports where the frame is before it reports any movement,\n        // so only a frame already seen inside can be leaving.\n        this.#inside = false;\n      }\n    }\n  }\n\n  /** Applies an intersecting entry: the first one loads, a return re-fetches. */\n  #enter(returning: boolean): void {\n    if (!this.#loaded) {\n      this.#load();\n      return;\n    }\n    if (this.onceValue || !returning) return;\n    this.#reload();\n  }\n\n  /**\n   * Starts the load by writing the held URL to `src`.\n   *\n   * @stimeoRuntimeOnly `url` is the address this one load fetches and `once` decides whether it\n   *   stops the watcher.\n   */\n  #load(): void {\n    if (!this.urlValue) return;\n    this.#loaded = true;\n    this.element.setAttribute(\"src\", this.urlValue);\n    this.element.setAttribute(\"data-lazy-loaded\", \"true\");\n    this.dispatch(\"load\", { detail: { url: this.urlValue } });\n    // The focus fallback exists to start the first load; it has nothing left to do.\n    this.element.removeEventListener(\"focusin\", this.#onFocus);\n    if (this.onceValue) this.#watcher.stop();\n  }\n\n  /**\n   * Re-entry while `once` is off: fetch the held URL again.\n   *\n   * @stimeoRuntimeOnly `url` is the address this one re-entry reloads.\n   */\n  #reload(): void {\n    const src = this.element.getAttribute(\"src\");\n    if (this.urlValue && this.urlValue !== src) {\n      // The held URL moved on. Writing it to `src` is the fetch, the same start\n      // the first load uses, so it works on any host.\n      this.element.setAttribute(\"src\", this.urlValue);\n      this.dispatch(\"load\", { detail: { url: this.urlValue } });\n      return;\n    }\n    const frame = this.element as HTMLElement & { reload?: () => void };\n    // Refetching the URL already on `src` needs the host's own `reload()`. On a\n    // non-`<turbo-frame>` host there is none, and firing `load` would announce a\n    // fetch that never started.\n    if (typeof frame.reload !== \"function\") return;\n    frame.reload();\n    this.dispatch(\"load\", { detail: { url: src ?? \"\" } });\n  }\n\n  #stopObserving(): void {\n    this.#watcher.stop();\n    this.element.removeEventListener(\"focusin\", this.#onFocus);\n  }\n}\n"]}

package/dist/controllers/listbox_controller.d.ts

@@ -28,9 +28,12 @@ import { Controller } from '@hotwired/stimulus';
  * (Select-Only Combobox) form. Focus stays on the trigger; the active option is
  * tracked with `aria-activedescendant` rather than by moving DOM focus. For a
  * text-filtered popup use {@link ComboboxController | Combobox}; for multiple
- * selection use Multi-Select.
+ * selection use {@link MultiSelectController | Multi-Select}.
  *
- * `change` dispatches `{ value: string, option: HTMLElement }`.
+ * `change` dispatches `{ value: string, option: HTMLElement }` when the user
+ * selects. `reconcile` dispatches `{ value: string, option: HTMLElement | null }`
+ * — the shape of `change`, with `option: null` and `value: ""` once nothing is
+ * selected — when the page moves the selection instead.
  *
  * @remarks
  * Behavior only. Static placement is the consumer's CSS; dynamic placement is
@@ -50,14 +53,34 @@ import { Controller } from '@hotwired/stimulus';
  *   Making the field a validatable mirror (`<input type="text" hidden required>`
  *   instead of `type="hidden"`) lets `stimeo--form-validation` enforce native
  *   constraints on the committed value with no extra JavaScript.
+ * - With nothing selected the trigger value shows `placeholder` when it is set,
+ *   else the text it held before the controller first wrote into it; it keeps no
+ *   text of an option that is not selected. A value the page rewrote, or added an
+ *   element to, after the controller wrote into it is the page's instead, and stays
+ *   exactly as the page left it until the next selection.
+ * - A selection the page moves — the selected option removed or dropped from the
+ *   targets, a morph or a script writing an option's `aria-selected` or the
+ *   selected option's `data-value`, a selected option that arrives ahead of the
+ *   selection — updates the label and the field silently and dispatches
+ *   `stimeo--listbox:reconcile`: once per batch, and only when the selected
+ *   option or its value differs from the selection last settled (on connect, by
+ *   the user, or by the previous `reconcile`). Connecting reports nothing. While
+ *   connected a `MutationObserver` watches the options' `aria-selected` and
+ *   `data-value`; `disconnect()` releases it.
  * - `Enter`/`Space` select and close; `Escape` and outside click / `Tab` close;
  *   closing via select/Escape returns focus to the trigger.
  */
 declare class ListboxController extends Controller<HTMLElement> {
     #private;
     static targets: string[];
+    static values: {
+        placeholder: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
     static actions: readonly ["close", "onTriggerKeydown", "open", "select", "toggle"];
-    static events: readonly ["change"];
+    static events: readonly ["change", "reconcile"];
     readonly triggerTarget: HTMLElement;
     readonly valueTarget: HTMLElement;
     readonly listTarget: HTMLElement;
@@ -67,16 +90,35 @@ declare class ListboxController extends Controller<HTMLElement> {
     readonly hasValueTarget: boolean;
     readonly hasListTarget: boolean;
     readonly hasFieldTarget: boolean;
-    /** Establishes the ARIA baseline, starts closed, and listens for outside clicks. */
+    placeholderValue: string;
+    /**
+     * Establishes the ARIA baseline, settles the selection without reporting it,
+     * starts closed, and listens for outside clicks.
+     */
     connect(): void;
     /**
-     * Establishes an inactive baseline for a late option, re-resolves active
-     * identity, and re-applies the selection baseline.
+     * Establishes an inactive baseline for a late option, then re-applies the
+     * selection baseline and re-resolves active identity once the batch is in.
      */
     optionTargetConnected(option: HTMLElement): void;
-    /** Removes controller-owned active state and reconciles the surviving targets. */
+    /**
+     * Removes controller-owned active state, then settles the selection and the
+     * active option among the surviving targets once the batch is in.
+     */
     optionTargetDisconnected(option: HTMLElement): void;
-    /** Removes the document listener and clears the typeahead timer. */
+    /** Fills a form field inserted or replaced at runtime with the current selection. */
+    fieldTargetConnected(): void;
+    /** Writes the current selection into a trigger value inserted or replaced at runtime. */
+    valueTargetConnected(): void;
+    /**
+     * Re-renders the empty-selection label when application code (or a Turbo morph)
+     * changes `placeholder` at runtime.
+     */
+    placeholderValueChanged(): void;
+    /**
+     * Releases the outside-click listener and the option observer, drops a queued
+     * pass, and clears the typeahead timer.
+     */
     disconnect(): void;
     /**
      * Toggles the list on a real mouse click. Keyboard activation of the

package/dist/controllers/listbox_controller.js

@@ -8,6 +8,16 @@ function isReservedArrowChord(event, allow = []) {
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
 
+// src/utils/field_mirror.ts
+function writeField(field, value) {
+  if (field.value === value) return false;
+  field.value = value;
+  return true;
+}
+function commitField(target) {
+  target.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
 // src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
@@ -165,45 +175,79 @@ function findTypeaheadMatch(items, from, query, label = (item) => typeaheadLabel
 }
 
 // src/controllers/listbox_controller.ts
+var OBSERVED_ATTRIBUTES = ["aria-selected", "data-value"];
+function setAttributeIfChanged(element, name, value) {
+  if (element.getAttribute(name) !== value) element.setAttribute(name, value);
+}
 var ListboxController = class extends Controller {
   static targets = ["trigger", "value", "list", "option", "field"];
+  static values = {
+    placeholder: { type: String, default: "" }
+  };
   static actions = ["close", "onTriggerKeydown", "open", "select", "toggle"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   /** Stable ID of the active option; DOM targets are resolved afresh before use. */
   #activeId = null;
   /** Target ID order captured while an option is active, used only for removal fallback. */
   #activeOrder = [];
-  #connected = false;
-  /** Collapses one mutation batch of target callbacks into a single pass. */
-  #reconcile = new MicrotaskCoalescer(() => this.#reconcileActive());
+  /**
+   * Collapses the target callbacks, Value changes and observed option writes of
+   * one DOM mutation into a single pass; refused before `connect()` and after
+   * `disconnect()`.
+   */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());
+  /** Watches the option attributes a page can rewrite in place; set while connected. */
+  #observer = null;
+  /** The selection last settled: on connect, by the user, or by a reported pass. */
+  #settled = { option: null, value: "" };
   /** Accumulated typeahead query and its idle-reset timer. */
   #typeahead = new Typeahead();
-  /** Establishes the ARIA baseline, starts closed, and listens for outside clicks. */
+  /**
+   * Establishes the ARIA baseline, settles the selection without reporting it,
+   * starts closed, and listens for outside clicks.
+   */
   connect() {
     this.#normalizeSelection();
     this.close();
     document.addEventListener("click", this.#onOutsideClick, true);
-    this.#connected = true;
+    this.#settled = this.#selection();
     this.#reconcile.activate();
+    this.#observeOptions();
   }
   /**
-   * Establishes an inactive baseline for a late option, re-resolves active
-   * identity, and re-applies the selection baseline.
+   * Establishes an inactive baseline for a late option, then re-applies the
+   * selection baseline and re-resolves active identity once the batch is in.
    */
   optionTargetConnected(option) {
     option.removeAttribute("data-active");
-    if (!this.#connected) return;
-    this.#normalizeSelection();
-    this.#queueOptionReconciliation();
+    this.#reconcile.schedule();
   }
-  /** Removes controller-owned active state and reconciles the surviving targets. */
+  /**
+   * Removes controller-owned active state, then settles the selection and the
+   * active option among the surviving targets once the batch is in.
+   */
   optionTargetDisconnected(option) {
     option.removeAttribute("data-active");
-    if (this.#connected) this.#queueOptionReconciliation();
+    this.#reconcile.schedule();
+  }
+  /** Fills a form field inserted or replaced at runtime with the current selection. */
+  fieldTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Writes the current selection into a trigger value inserted or replaced at runtime. */
+  valueTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /**
+   * Re-renders the empty-selection label when application code (or a Turbo morph)
+   * changes `placeholder` at runtime.
+   */
+  placeholderValueChanged() {
+    this.#reconcile.schedule();
   }
   /**
    * Brings the authored DOM to the shape the APG requires, and derives the state
-   * that follows from the initial selection.
+   * that follows from the selection.
    *
    * Three things happen, and only these three — which option is chosen is the
    * author's, and is never changed:
@@ -212,27 +256,59 @@ var ListboxController = class extends Controller {
    *    selectable" in ARIA, so a forgotten attribute hides a selectable option
    *    from assistive technology.
    * 2. At most one stays `true`. The first in DOM order wins, since that is the
-   *    only deterministic reading of "which one did the author mean".
-   * 3. The trigger label and the hidden field are derived from that selection.
-   *    Without this the widget announces a choice it does not submit: the popup
-   *    says "Banana", the trigger still says "Choose…", and the form posts "".
+   *    only deterministic reading of "which one did the author mean"; an option
+   *    the page inserts ahead of the selection, already selected, takes it over.
+   * 3. The trigger label and the hidden field are derived from that selection,
+   *    an empty one included. Without this the widget announces a choice it does
+   *    not submit: the popup says "Banana", the trigger still says "Choose…", and
+   *    the form posts "".
    *
-   * No `change` fires — nothing changed, this is the initial state being told
-   * properly. The scan is the `option` target set: a `role="option"` without the
-   * target is outside the contract and is neither counted nor written.
+   * Nothing is reported here: `connect()` describes the initial state, and a
+   * page-driven pass reports a moved selection itself. The scan is the `option`
+   * target set: a `role="option"` without the target is outside the contract and
+   * is neither counted nor written.
    */
   #normalizeSelection() {
-    const options = this.optionTargets;
-    const selected = options.find((option) => option.getAttribute("aria-selected") === "true");
-    for (const option of options) {
-      option.setAttribute("aria-selected", option === selected ? "true" : "false");
-    }
-    if (selected) this.#applySelection(selected);
+    const selected = this.optionTargets.find(
+      (option) => option.getAttribute("aria-selected") === "true"
+    );
+    this.#applySelection(selected);
+  }
+  /**
+   * The pass the page's changes run: the selection is normalized and mirrored,
+   * the active option re-resolved, then a selection that moved is reported. The
+   * report comes last, so options a subscriber rewrites are the next pass's to
+   * settle.
+   */
+  #reconcileOptions() {
+    this.#normalizeSelection();
+    this.#reconcileActive();
+    this.#reportMove();
   }
-  /** Removes the document listener and clears the typeahead timer. */
+  /**
+   * Reports the selection as `reconcile` when its option or value differs from the
+   * selection last settled. The settled selection is replaced before dispatching,
+   * so a move a subscriber makes is measured against what it was told.
+   */
+  #reportMove() {
+    const { option, value } = this.#selection();
+    if (option === this.#settled.option && value === this.#settled.value) return;
+    this.#settled = { option, value };
+    this.dispatch("reconcile", { detail: { value, option } });
+  }
+  /** The selected option target, if any, and the value its field submits. */
+  #selection() {
+    const option = this.optionTargets.find((candidate) => candidate.getAttribute("aria-selected") === "true") ?? null;
+    return { option, value: option ? this.#optionValue(option) : "" };
+  }
+  /**
+   * Releases the outside-click listener and the option observer, drops a queued
+   * pass, and clears the typeahead timer.
+   */
   disconnect() {
-    this.#connected = false;
     this.#reconcile.cancel();
+    this.#observer?.disconnect();
+    this.#observer = null;
     document.removeEventListener("click", this.#onOutsideClick, true);
     this.#typeahead.reset();
   }
@@ -354,27 +430,113 @@ var ListboxController = class extends Controller {
   /** Applies selection: `aria-selected`, trigger label, hidden field, `change`. */
   #selectOption(option) {
     const { value, fieldChanged } = this.#applySelection(option);
-    if (fieldChanged) {
-      this.fieldTarget.dispatchEvent(new Event("change", { bubbles: true }));
-    }
+    this.#settled = { option, value };
+    if (fieldChanged) commitField(this.fieldTarget);
     this.dispatch("change", { detail: { value, option } });
   }
   /**
-   * Writes `option` into `aria-selected`, the trigger label and the hidden field.
-   * Emits nothing — {@link #normalizeSelection} reuses this at connect, where the
-   * state is being described rather than changed.
+   * Writes `option` — or, when it is `undefined`, no selection — into
+   * `aria-selected`, the trigger label and the hidden field. Emits nothing: the
+   * user's commit and a page-driven pass each report it their own way, and
+   * `connect()` only describes the state it finds.
    */
   #applySelection(option) {
     for (const candidate of this.optionTargets) {
-      candidate.setAttribute("aria-selected", candidate === option ? "true" : "false");
+      setAttributeIfChanged(candidate, "aria-selected", candidate === option ? "true" : "false");
     }
-    const label = (option.textContent ?? "").trim();
-    const value = option.dataset.value ?? label;
-    if (this.hasValueTarget) this.valueTarget.textContent = label;
-    const fieldChanged = this.hasFieldTarget && this.fieldTarget.value !== value;
-    if (fieldChanged) this.fieldTarget.value = value;
+    this.#dropOwnRecords();
+    const value = option ? this.#optionValue(option) : "";
+    this.#renderLabel(option);
+    const fieldChanged = this.hasFieldTarget && writeField(this.fieldTarget, value);
     return { value, fieldChanged };
   }
+  /**
+   * Keeps the trigger value on the selection: the selected option's text, or, with
+   * nothing selected, `placeholder` when it is set, else the text the value held
+   * before this controller first wrote into it.
+   *
+   * The value is this controller's only while it holds the text last written into
+   * it and nothing else — the `owns-label` marker carries that text — and the text
+   * it held before is kept in the `original-label` marker. A value the page
+   * rewrote or added an element to after that — the marker is still there but no
+   * longer matches — is the page's: with nothing selected it is left exactly as it
+   * is, `placeholder` or not, and the next selection remembers its text before
+   * replacing it. A value with no marker at all — the author's, or one a morph put
+   * back without the markers — is taken over the same way by `placeholder` or by a
+   * selection. A value that only ever showed a selection has no text of its own to
+   * return to, so it is emptied rather than left naming an option that is not
+   * selected.
+   *
+   * @stimeoRenderRoot
+   */
+  #renderLabel(option) {
+    if (!this.hasValueTarget) return;
+    const label = this.valueTarget;
+    const ownsLabel = `data-${this.identifier}-owns-label`;
+    const originalLabel = `data-${this.identifier}-original-label`;
+    const owned = label.getAttribute(ownsLabel) === label.textContent && label.childElementCount === 0;
+    if (option === void 0 && !owned && label.hasAttribute(ownsLabel)) return;
+    const text = option ? this.#optionLabel(option) : this.placeholderValue || null;
+    if (text === null) {
+      if (!owned) return;
+      label.textContent = label.getAttribute(originalLabel) ?? "";
+      label.removeAttribute(ownsLabel);
+      label.removeAttribute(originalLabel);
+      return;
+    }
+    if (!owned) {
+      const current = (label.textContent ?? "").trim();
+      if (option === void 0 || current !== text) {
+        setAttributeIfChanged(label, originalLabel, current);
+      }
+    }
+    if (label.textContent !== text) label.textContent = text;
+    setAttributeIfChanged(label, ownsLabel, text);
+  }
+  /** An option's visible label: its own text, trimmed. */
+  #optionLabel(option) {
+    return (option.textContent ?? "").trim();
+  }
+  /** The value an option submits: its `data-value`, else its label. */
+  #optionValue(option) {
+    return option.dataset.value ?? this.#optionLabel(option);
+  }
+  /**
+   * Watches the options' `aria-selected` and `data-value`. The listbox's own writes
+   * to them are dropped from the queue as they happen, so each record the callback
+   * receives is the page's, and only a record on one of the listbox's own options
+   * schedules a pass.
+   */
+  #observeOptions() {
+    const observer = new MutationObserver((records) => {
+      if (this.#concernsOptions(records)) this.#reconcile.schedule();
+    });
+    observer.observe(this.element, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: OBSERVED_ATTRIBUTES
+    });
+    this.#observer = observer;
+  }
+  /**
+   * Whether any record is about one of this listbox's own options. A widget nested
+   * inside it writes the same attributes on its own elements, and those are no
+   * reason to reconcile the listbox.
+   */
+  #concernsOptions(records) {
+    const options = new Set(this.optionTargets);
+    return records.some((record) => options.has(record.target));
+  }
+  /**
+   * Drops the records the listbox's own writes just queued, so the observer never
+   * takes them for the page's. A page write queued just before goes with them and
+   * owes nothing: every such write leaves every option's `aria-selected` at the
+   * value the selection gives it, and the selection is then read back from the DOM,
+   * so it already holds what the page wrote.
+   */
+  #dropOwnRecords() {
+    this.#observer?.takeRecords();
+  }
   /**
    * Marks the option at `index` active via `data-active` and the trigger's
    * `aria-activedescendant`. Pass `-1` to clear it (the attribute is removed, not
@@ -444,10 +606,6 @@ var ListboxController = class extends Controller {
     }
     return -1;
   }
-  /** Coalesces all target callbacks from one MutationObserver batch. */
-  #queueOptionReconciliation() {
-    this.#reconcile.schedule();
-  }
   /**
    * Advances the typeahead query and activates the next matching option.
    *