stimeo-ui 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a78d7192424e66f85cd4fbc901f75f260178f890fbcf040724fd5e518314dda7
-  data.tar.gz: d14ba0559fd6659b4b1edc860c653815bb949439768f26e3540cb758dabee2f7
+  metadata.gz: 8e3f69e3521c7e5d2ffa5e4b948aabbb26dc9bf8429217fa6235c9cdcafb53b1
+  data.tar.gz: d9722417ea447febdc5188eb50812a3725987f65a6920e49f98e852b5f0076ba
 SHA512:
-  metadata.gz: e02be89ae227eec783f0eb7f21c492a00ff75174c5285de3d8cf8418b3a826b6d9fb42d779b63a47845b77679d4b61adcade253746cf39ea83d7c924651f8a8e
-  data.tar.gz: 7661666a77da707d43ad07bf9e7bb4a8b0cb63caea75f2d0d8abf9f43fd6b43421bfe8d24203f814e70042a506177995df72e14487c4c11aa49016129bd44f02
+  metadata.gz: 1fe28608ac28813a4e12b448b438853d19e2acdd948fe2af5d287b615e83439a933023881a72bec2a50d579c384141be0c132310a640540b5d7eaee5554e2f28
+  data.tar.gz: ddb5ffd05af127033055296b6a66e6e71344b89dbcc42f0c88a34bc7e88193cb2c48deb67f4f2250edd19a0bed15957914c5ee90afd137ecce1c11cfc818df5b

data/CHANGELOG.md

@@ -7,6 +7,182 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 While the version is `0.x`, the public API (the `stimeo--*` data attributes) may
 change between releases.
 
+## [0.7.0] - 2026-08-16
+
+Minor release reworking the form stack, separator, and scroll-area, with
+announcements moving onto the shared `stimeo--announcer`. The Inspector manifest
+moves to schema v12, so `stimeo check` can report on views that passed under
+0.6.0.
+
+### Removed
+
+- **Breaking** — direct-upload: the `status` target and the `announce` /
+  `doneLabel` / `errorLabel` Values. Use `announceDoneText` /
+  `announceErrorText` with `{name}` instead of `%{name}`.
+- **Breaking** — persist: the unversioned draft format. Drafts written by earlier
+  releases are discarded, not migrated.
+
+### Added
+
+- separator `min` / `max` / `value`; submit-once `finish` / `cancel` and
+  `idle` / `busy` targets; dirty-form `acceptRestore`; character-counter
+  `announceText`; form-field `setError(message, { focus })`; persist `error`;
+  `reconcile` on character-counter and conditional-fields.
+- form-validation: localized constraint wording through
+  `data-stimeo--form-validation-message[-<constraint>]`, a declarative
+  `disallow="whitespace"`, and controls attached with `form="id"`.
+- Inspector: schema v12 (`requiredActions`, `actionCompletion`) with the
+  `missing-required-action`, `missing-action-completion`, and
+  `missing-announcer` diagnostics.
+
+### Changed
+
+- **Breaking** — announcing components need a `stimeo--announcer` on the page
+  plus the wording: character-counter `announceText`, direct-upload
+  `announceDoneText` / `announceErrorText`, submit-once `announceText` /
+  `announceReadyText`. Drop `role="alert"` from form-field's `error` target and
+  `aria-live` from character-counter's `output`.
+- **Breaking** — separator: the Values are the only runtime input, so move
+  `role`, `tabindex`, and the orientation / range ARIA into `orientation`,
+  `focusable`, `min`, `max`, `step`, and `value`. A `focusable` separator also
+  needs `keydown->stimeo--separator#onKeydown` on itself and an accessible name.
+- **Breaking** — submit-once: sessions are per form, and `preventDefault()` no
+  longer ends one — wire `finish` or `cancel`, or set a `timeout`. `start` /
+  `end` carry `{ form, submitter, … }`.
+- **Breaking** — direct-upload: `done` fires only on success, and a row that
+  reached `error` stays there.
+- **Breaking** — dirty-form: a successful submit re-baselines to what Turbo
+  submitted, so later edits stay dirty, and one native confirmation covers every
+  dirty form per navigation. With persist, add
+  `data-action="stimeo--persist:restore->stimeo--dirty-form#acceptRestore"`.
+- **Breaking** — character-counter: `change` fires only when a committed edit
+  changes the length. form-field: `validate` fires only for `setError` /
+  `clearError`.
+- persist: `exclude` defaults to Rails' `authenticity_token` / `_method` /
+  `utf8`; `password` is always excluded regardless of the list.
+
+### Fixed
+
+- Attribute and style leases are released by the subscriber that owns the
+  lifecycle, so a cached page no longer retains detached elements.
+- localStorage access goes through one guarded helper, so persist, sidebar, and
+  theme keep working when the browser denies storage.
+
+## [0.6.0] - 2026-08-15
+
+Minor release that separates reconciled state from user edits: `change` now
+means the user committed a value, and a controller that re-derives its own state
+reports `reconcile` instead. Several markup contracts tightened, and authored
+prose — remove-button names, announcements — moved out of the library. The
+Inspector manifest stays on schema v11, but **`stimeo check` can report errors on
+views that passed under 0.5.0**, so run it before deploying.
+
+### Upgrade notes
+
+- Listening to `change` to observe controller-driven repair? Subscribe to
+  `reconcile` too: carousel, checkbox, color-picker, multi-select, number-input,
+  radio-group, rating, tags-input, time-picker. Neither fires on connect.
+- rating: delete `max` and every `data-rating-value`. The DOM order of the
+  `symbol` targets is the scale.
+- aspect-ratio: delete the `content` target.
+- toggle-group, radio-group: items must be `<button type="button">` or a
+  non-interactive host with `role="button"` / `role="radio"`. Others are left
+  untouched at runtime.
+- tags-input, multi-select: delete the `status` target, put a
+  `stimeo--announcer` on the page, and set `announceText` /
+  `announceRemovedText`. In the chip template add `label` and `remove` targets
+  and author the remove button's `aria-label` (`{label}` / `{value}` expand).
+  Drop `data-*-slot="label"` and tags-input's `removeTag` action.
+- date-range-picker: declare unavailable days with `disabled-dates`; an
+  `aria-disabled` you write on a cell is overwritten on the next paint.
+- time-picker: AM/PM is a `role="spinbutton"` segment, not an `aria-pressed`
+  toggle. `seconds` only decides whether the composed value carries seconds.
+- List values are read as JSON strings — idle's `events`, password-strength's
+  `levels`, persist's `exclude`, date-range-picker's `disabled-dates`. The
+  markup is unchanged; the manifest reports `String` where it reported `Array`.
+
+### Removed
+
+- **Breaking** — rating: `max` and `data-rating-value`. aspect-ratio: the
+  `content` target. tags-input, multi-select: the `status` target, tags-input's
+  `removeTag` action, and the English `Remove {value}` label the library wrote
+  onto generated remove buttons.
+
+### Added
+
+- A `reconcile` event, carrying the same `detail` as that component's `change`,
+  on carousel, checkbox, color-picker, multi-select, number-input, radio-group,
+  rating, tags-input, and time-picker.
+- checkbox: a group works without a `parent`; the root still reports
+  `all` / `partial` / `none`.
+- rating: `Delete` and `Backspace` clear the rating when `clearable`.
+- date-range-picker: `disabled-dates`, a `monthchange` event,
+  `Shift+PageUp` / `Shift+PageDown` for stepping a year, and month labels
+  formatted from `documentElement.lang`.
+- multi-select: a `fields` target holding one hidden input per selected value,
+  with `name` and `form`, plus `announceText` / `announceRemovedText`.
+  tags-input: `label` and `remove` targets and the same two announce values.
+- avatar: an `empty` state beside `loading`, `loaded`, and `error`.
+- Inspector: `invalid-host` for radio-group and toggle-group items;
+  chip-template parts required *inside* the template; `aria-label` on remove
+  buttons and the group role on toggle groups; at most one checkbox `parent`
+  and one checked radio; a positive integer time-picker `step`. An empty
+  attribute value no longer satisfies a requirement that asks only for the
+  attribute's presence.
+
+### Changed
+
+- **Breaking** — `change` is reserved for user-committed values. DOM
+  normalization, target churn, morphs, and runtime value changes report
+  `reconcile`, and a repair that leaves the committed state unchanged reports
+  nothing.
+- **Breaking** — radio-group, time-picker: the hidden `field` fires a native
+  `change` only for user edits, so a server-rendered repaint cannot drive an
+  `auto-submit` companion into a resubmit loop.
+- **Breaking** — multi-select: `max` is enforced at all times, not only on the
+  click path; surplus options normalize to `aria-selected="false"`.
+- **Breaking** — avatar: a present `src` value wins over an authored `src`, and
+  an empty one means "no image". Remove the attribute to hand the element's own
+  `src` back.
+- **Breaking** — checkbox: a parent toggle sets each child's `checked` without
+  synthesizing a native `change` per child; the root reports one event.
+- toggle-group, radio-group, tags-input, multi-select: interaction is delegated
+  from the container, so items added at runtime work without per-item
+  `data-action`. Existing per-item actions stay compatible.
+- toggle-group, radio-group: `aria-disabled` items stay reachable by arrow keys
+  with activation suppressed; natively disabled and `hidden` items are skipped.
+- number-input, rating, scroll-area, time-picker: ARIA and `tabindex` the
+  controller writes are treated as loans and handed back to their authored
+  values, without overwriting a change you made in the meantime.
+- date-range-picker: a preset that only partly overlaps `min` / `max` is
+  narrowed to the selectable span instead of committing an unavailable endpoint.
+- multi-select, tags-input: `Backspace` in an empty input removes the last chip
+  and keeps focus in the input.
+- time-picker: a unit that wraps past noon or midnight carries AM/PM with it,
+  and one operation reports one `change` with the final value.
+
+### Fixed
+
+- avatar, carousel, checkbox, radio-group, rating, roving, toggle-group: targets
+  added, removed, or morphed at runtime settle on one state — a single tab stop,
+  a single checked or pressed item, and focus on a surviving item.
+- date-range-picker: an unavailable day cannot become a committed endpoint
+  through a preset, a preview, or Enter/Space; a reversed stored range is
+  normalized on connect; a pending selection is rewound before Turbo caches the
+  page.
+- number-input: commits compare numbers rather than the displayed text, and IME
+  composition never commits a value.
+- time-picker: with `wrap` disabled, 11 and 12 no longer step into each other,
+  and an unfinished direct-entry buffer is discarded when focus leaves.
+- multi-select, tags-input: a chip is built only when the template can produce a
+  complete one, only the `remove` target inside a chip acts on it, and a
+  replaced `tags` container is re-wired.
+- file-dropzone, scroll-area: a replaced `list` / `viewport` keeps its state and
+  takes over the listeners; the old element stops responding.
+- idle, password-strength, persist, date-range-picker: a malformed list value
+  falls back to its default instead of stopping the controller from connecting
+  and leaving the whole element inert.
+
 ## [0.5.0] - 2026-08-13
 
 ### Changed
@@ -458,6 +634,8 @@ Initial public alpha: 101 behavior-only, accessible Stimulus controllers driven
 by `data-*` attributes, shipping no CSS. Published to npm (with provenance) and
 RubyGems.
 
+[0.7.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.7.0
+[0.6.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.6.0
 [0.5.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.5.0
 [0.4.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.4.0
 [0.3.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.3.0

data/dist/controllers/alert_dialog_controller.js

@@ -115,8 +115,81 @@ var EscapeLayer = class _EscapeLayer {
   }
 };
 
+// src/utils/focus_candidate.ts
+function inheritsFieldsetDisabled(control) {
+  let fieldset = control.closest("fieldset[disabled]");
+  while (fieldset) {
+    const legend = Array.from(fieldset.children).find((child) => child.tagName === "LEGEND");
+    if (!legend?.contains(control)) return true;
+    fieldset = fieldset.parentElement?.closest("fieldset[disabled]") ?? null;
+  }
+  return false;
+}
+function canTakeFocus(element) {
+  if (element.closest("[hidden], [inert]")) return false;
+  if (element instanceof HTMLInputElement && element.type === "hidden") return false;
+  if (!("disabled" in element)) return true;
+  if (element.disabled) return false;
+  return !inheritsFieldsetDisabled(element);
+}
+var TAB_STOP_CANDIDATE_SELECTOR = [
+  "a[href]",
+  "area[href]",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "summary",
+  "iframe",
+  "audio[controls]",
+  "video[controls]",
+  "[tabindex]",
+  "[contenteditable]"
+].join(",");
+function isRenderedForFocus(element) {
+  const check = element.checkVisibility;
+  return typeof check === "function" ? check.call(element, { visibilityProperty: true }) : true;
+}
+function authoredTabindex(element) {
+  const value = element.getAttribute("tabindex");
+  if (value === null || !/^[+-]?\d+$/.test(value.trim())) return null;
+  return Number(value);
+}
+function hasNativeTabStop(element) {
+  if (element instanceof HTMLAnchorElement || element instanceof HTMLAreaElement) {
+    return element.hasAttribute("href");
+  }
+  if (element instanceof HTMLButtonElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement) {
+    return true;
+  }
+  if (element instanceof HTMLInputElement) return element.type !== "hidden";
+  if (element instanceof HTMLIFrameElement) return true;
+  if (element.tagName === "AUDIO" || element.tagName === "VIDEO") {
+    return element.hasAttribute("controls");
+  }
+  if (element instanceof HTMLElement && element.tagName === "SUMMARY") {
+    const details = element.parentElement;
+    return details instanceof HTMLDetailsElement && Array.from(details.children).find((child) => child.tagName === "SUMMARY") === element;
+  }
+  return false;
+}
+function hasEditableTabStop(element) {
+  const value = element.getAttribute("contenteditable")?.toLowerCase();
+  return value === "" || value === "true" || value === "plaintext-only";
+}
+function isTabStop(element) {
+  if (!canTakeFocus(element) || !isRenderedForFocus(element)) return false;
+  const tabindex = authoredTabindex(element);
+  if (tabindex !== null) return tabindex >= 0;
+  return hasNativeTabStop(element) || hasEditableTabStop(element);
+}
+function tabStopsWithin(root) {
+  return Array.from(root.querySelectorAll(TAB_STOP_CANDIDATE_SELECTOR)).filter(
+    isTabStop
+  );
+}
+
 // src/utils/focus_trap.ts
-var FOCUSABLE = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 var FocusTrap = class {
   /** The element focused before activation, restored on deactivation. */
   #previouslyFocused = null;
@@ -278,9 +351,7 @@ var FocusTrap = class {
   }
   /** Collects the container's currently focusable descendants in DOM order. */
   #focusableElements() {
-    return Array.from(this.#getContainer().querySelectorAll(FOCUSABLE)).filter(
-      (el) => !el.hidden
-    );
+    return tabStopsWithin(this.#getContainer());
   }
 };
 

data/dist/controllers/aspect_ratio_controller.js

@@ -1,33 +1,41 @@
 import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/aspect_ratio_controller.ts
+var DEFAULT_RATIO = "1 / 1";
+var RATIO_PROPERTY = "--stimeo--aspect-ratio";
+var CSS_NUMBER_PATTERN = /^[+-]?(?:\d+|\d*\.\d+)(?:[eE][+-]?\d+)?$/;
 var AspectRatioController = class extends Controller {
-  static targets = ["content"];
   static values = {
     ratio: { type: String, default: "1/1" }
   };
   /** Applies the ratio on connect and whenever the value changes. */
   ratioValueChanged() {
-    this.element.style.setProperty("--stimeo--aspect-ratio", this.#normalizeRatio(this.ratioValue));
+    this.element.style.setProperty(RATIO_PROPERTY, this.#normalizeRatio(this.ratioValue));
   }
   /**
    * Normalizes a ratio string to a valid CSS `<ratio>`:
-   * - `"16/9"` / `"16 / 9"` → `"16 / 9"` (both parts must be positive numbers)
-   * - `"1.5"` → `"1.5"` (a bare positive number)
+   * - `"16/9"` / `"16 / 9"` → `"16 / 9"` (both parts must be positive CSS numbers)
+   * - `"1.5"` → `"1.5"` (a bare positive CSS number)
    * - anything else → `"1 / 1"` (the default), so the custom property is always valid.
    */
   #normalizeRatio(raw) {
     const value = raw.trim();
     if (value.includes("/")) {
-      const [w, h] = value.split("/").map((part) => Number.parseFloat(part.trim()));
-      if (this.#isPositive(w) && this.#isPositive(h)) return `${w} / ${h}`;
-      return "1 / 1";
+      const parts = value.split("/");
+      if (parts.length !== 2) return DEFAULT_RATIO;
+      const width = this.#parsePositiveNumber(parts[0] ?? "");
+      const height = this.#parsePositiveNumber(parts[1] ?? "");
+      return width !== void 0 && height !== void 0 ? `${width} / ${height}` : DEFAULT_RATIO;
     }
-    const single = Number.parseFloat(value);
-    return this.#isPositive(single) ? String(single) : "1 / 1";
+    const single = this.#parsePositiveNumber(value);
+    return single === void 0 ? DEFAULT_RATIO : String(single);
   }
-  #isPositive(value) {
-    return value !== void 0 && Number.isFinite(value) && value > 0;
+  /** Parses one complete CSS `<number>` token and rejects units or trailing syntax. */
+  #parsePositiveNumber(raw) {
+    const token = raw.trim();
+    if (!CSS_NUMBER_PATTERN.test(token)) return void 0;
+    const value = Number(token);
+    return Number.isFinite(value) && value > 0 ? value : void 0;
   }
 };
 

data/dist/controllers/avatar_controller.js

@@ -1,63 +1,260 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/avatar_controller.ts
+
+// src/utils/attribute_lease.ts
+var AttributeLease = class {
+  #attribute;
+  #records = /* @__PURE__ */ new Map();
+  /** @param attribute - The attribute whose temporary values this lease owns. */
+  constructor(attribute) {
+    this.#attribute = attribute;
+  }
+  /** Writes or removes the leased attribute while preserving its authored value. */
+  write(element, value) {
+    const existing = this.#records.get(element);
+    if (existing) {
+      existing.written = value;
+    } else {
+      this.#records.set(element, {
+        original: element.getAttribute(this.#attribute),
+        written: value
+      });
+    }
+    this.#reflect(element, value);
+  }
+  /** Returns one lease without overwriting a value subsequently authored by a consumer. */
+  return(element) {
+    const record = this.#records.get(element);
+    if (!record) return;
+    this.#records.delete(element);
+    const stillOwned = element.getAttribute(this.#attribute) === record.written;
+    if (stillOwned) this.#reflect(element, record.original);
+  }
+  /** Reflects only a real value transition, avoiding self-triggered mutation work. */
+  #reflect(element, value) {
+    if (element.getAttribute(this.#attribute) === value) return;
+    if (value === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, value);
+  }
+  /** Returns every outstanding lease using the same ownership check as {@link return}. */
+  returnAll() {
+    for (const element of Array.from(this.#records.keys())) this.return(element);
+  }
+};
+
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/controllers/avatar_controller.ts
 var AvatarController = class extends Controller {
   static targets = ["image", "fallback"];
-  static values = {
-    src: { type: String, default: "" }
-  };
+  static values = { src: String };
   static actions = ["onError", "onLoad"];
   static events = ["error"];
+  /** Collapses one morph's Value, target, and direct-attribute signals into one pass. */
+  #reconcile = new MicrotaskCoalescer(() => this.#render());
+  /** Preserves directly-authored source and visibility while targets are controlled. */
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #src = new AttributeLease("src");
+  #imageHidden = new AttributeLease("hidden");
+  #fallbackHidden = new AttributeLease("hidden");
+  /** True only while target departure means ownership was actually relinquished. */
+  #connected = false;
+  /** Watches the non-Value render input used by the direct `<img src>` form. */
+  #srcObserver = new MutationObserver((records) => {
+    if (records.some((record) => this.hasImageTarget && record.target === this.imageTarget)) {
+      this.#reconcile.schedule();
+    }
+  });
+  /** Starts retained-DOM observation and silently derives the current phase. */
   connect() {
-    if (!this.hasImageTarget) {
-      this.#showFallback();
-      return;
+    this.#connected = true;
+    this.#reconcile.activate();
+    this.#beforeCache.activate();
+    this.#srcObserver.observe(this.element, {
+      attributes: true,
+      attributeFilter: ["src"],
+      subtree: true
+    });
+    this.#render();
+  }
+  /** Cancels asynchronous work while retaining the last materialized visual state. */
+  disconnect() {
+    this.#connected = false;
+    this.#reconcile.cancel();
+    this.#beforeCache.deactivate();
+    this.#srcObserver.disconnect();
+  }
+  /** Repaints when application code or a Turbo morph changes the source Value. */
+  srcValueChanged() {
+    this.#reconcile.schedule();
+  }
+  /** Applies the current source and phase to an image inserted or replaced at runtime. */
+  imageTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Returns attributes borrowed from an image that leaves this live avatar. */
+  imageTargetDisconnected(image) {
+    if (this.#connected) {
+      this.#src.return(image);
+      this.#imageHidden.return(image);
     }
-    if (this.srcValue) {
-      this.imageTarget.src = this.srcValue;
+    this.#reconcile.schedule();
+  }
+  /** Applies the current phase to a fallback inserted or replaced at runtime. */
+  fallbackTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Returns authored visibility when a fallback leaves this live avatar. */
+  fallbackTargetDisconnected(fallback) {
+    if (this.#connected) this.#fallbackHidden.return(fallback);
+    this.#reconcile.schedule();
+  }
+  /** Reveals the current image after its native `load` event. */
+  onLoad(event) {
+    const image = this.#eventImage(event);
+    if (!image) return;
+    if (!image.getAttribute("src")) {
+      this.#render();
+      return;
     }
-    const src = this.imageTarget.getAttribute("src");
+    this.#reflect("loaded");
+  }
+  /**
+   * Reveals the fallback after the current image's native `error` event.
+   *
+   * Dispatches `stimeo--avatar:error` with `{ src: string }`, where `src` is
+   * the attempted attribute value. Empty/stale/detached image events are ignored.
+   */
+  onError(event) {
+    const image = this.#eventImage(event);
+    if (!image) return;
+    const src = image.getAttribute("src");
     if (!src) {
-      this.#showFallback();
+      this.#render();
       return;
     }
-    if (this.imageTarget.complete && this.imageTarget.naturalWidth > 0) {
-      this.#showImage();
+    this.#reflect("error");
+    this.dispatch("error", { detail: { src } });
+  }
+  /**
+   * Materializes the phase from the final source/target DOM after one mutation batch.
+   *
+   * Cached success and failure are state reconstruction, not new load events, so
+   * this pass never dispatches the public `error` event.
+   *
+   * @stimeoRenderRoot
+   */
+  #render() {
+    if (!this.hasImageTarget) {
+      this.#reflect("empty");
+      return;
+    }
+    const image = this.imageTarget;
+    const src = this.#applySource(image);
+    if (!src) {
+      this.#reflect("empty");
       return;
     }
-    if (this.imageTarget.complete && this.imageTarget.naturalWidth === 0 && src) {
-      this.onError();
+    if (!image.complete) {
+      this.#reflect("loading");
       return;
     }
-    this.#enterLoading();
+    this.#reflect(image.naturalWidth > 0 ? "loaded" : "error");
   }
-  /** Reveals the image once it has loaded successfully. */
-  onLoad() {
-    this.#showImage();
+  /** Applies Value precedence and returns the effective raw `src` attribute. */
+  #applySource(image) {
+    if (!this.element.hasAttribute("data-stimeo--avatar-src-value")) {
+      this.#src.return(image);
+      return image.getAttribute("src");
+    }
+    const desired = this.srcValue.length > 0 ? this.srcValue : null;
+    if (image.getAttribute("src") !== desired) this.#src.write(image, desired);
+    return desired;
   }
-  /** Swaps to the fallback when the image fails and emits `error`. */
-  onError() {
-    const src = this.hasImageTarget ? this.imageTarget.getAttribute("src") ?? "" : "";
-    this.#showFallback();
-    this.dispatch("error", { detail: { src } });
+  /** Accepts an action only from the singular image target currently controlled. */
+  #eventImage(event) {
+    const candidate = event.currentTarget;
+    if (!(candidate instanceof HTMLImageElement)) return null;
+    if (!this.hasImageTarget || candidate !== this.imageTarget) return null;
+    return candidate;
+  }
+  /** Writes the visibility pair and public root state as one controller-owned output. */
+  #reflect(state) {
+    const showImage = state === "loading" || state === "loaded";
+    if (this.hasImageTarget) {
+      this.#imageHidden.write(this.imageTarget, showImage ? null : "");
+    }
+    if (this.hasFallbackTarget) {
+      this.#fallbackHidden.write(this.fallbackTarget, showImage ? "" : null);
+    }
+    this.element.setAttribute("data-state", state);
   }
-  /** Loading phase: keep the image visible (per markup) while it fetches. */
-  #enterLoading() {
-    if (this.hasImageTarget) this.imageTarget.hidden = false;
-    if (this.hasFallbackTarget) this.fallbackTarget.hidden = true;
-    this.element.setAttribute("data-state", "loading");
-  }
-  /** Loaded phase: image visible, fallback hidden. */
-  #showImage() {
-    if (this.hasImageTarget) this.imageTarget.hidden = false;
-    if (this.hasFallbackTarget) this.fallbackTarget.hidden = true;
-    this.element.setAttribute("data-state", "loaded");
-  }
-  /** Error / no-src phase: fallback visible, image hidden. */
-  #showFallback() {
-    if (this.hasImageTarget) this.imageTarget.hidden = true;
-    if (this.hasFallbackTarget) this.fallbackTarget.hidden = false;
-    this.element.setAttribute("data-state", "error");
+  /** Returns borrowed image and fallback semantics before Turbo snapshots the page. */
+  #rewindForCache() {
+    this.#src.returnAll();
+    this.#imageHidden.returnAll();
+    this.#fallbackHidden.returnAll();
   }
 };