avo 4.0.0.beta.45 → 4.0.0.beta.46

data/app/assets/stylesheets/application.css

@@ -1,6 +1,11 @@
 /* @layer base, components, utilities; */
 @import "tailwindcss";
 
+@source not "*/tmp/cache";
+@source not "*/tmp/pids";
+@source not "*/tmp/screenshots";
+@source not "*/tmp/storage";
+
 /* TODO: Figure out a way to add those dynamically */
 /* Find a long term solution for this. */
 /* Basically this is a hack to make sure that we dont have specificity issues with the packages stylesheets. */
@@ -87,6 +92,23 @@
 @custom-variant resource-edit-view (&:where(.resource-edit-view *));
 @custom-variant resource-new-view (&:where(.resource-new-view *));
 
+/* Field wrappers use the same stacked layout below md, when the whole page
+   forces stacked fields, and when an individual field is explicitly stacked.
+   The component styles live in field-wrapper.css under `@variant field-stacked`. */
+@custom-variant field-stacked {
+  @media (width < 48rem) {
+    @slot;
+  }
+
+  &:is(.all-fields-stacked .field-wrapper, .field-wrapper.field-wrapper--stacked) {
+    @slot;
+  }
+
+  :is(.all-fields-stacked .field-wrapper, .field-wrapper.field-wrapper--stacked) & {
+    @slot;
+  }
+}
+
 /* Used to determine if the filters buttons is displayed. */
 @custom-variant index-missing-resources (&:where(.index-missing-resources *));
 
@@ -160,6 +182,7 @@
   @import "./css/components/discreet_information.css";
   @import "./css/components/header_menu.css";
   @import "./css/components/hotkey.css";
+  @import "./css/components/manual_frame.css";
   @import "./css/components/modal.css";
   @import "./css/components/filters.css";
   @import "./css/css-animations.css";

data/app/assets/stylesheets/css/components/field-wrapper.css

@@ -85,24 +85,25 @@
 }
 
 /* Stacked modifier */
-.all-fields-stacked .field-wrapper,
-.field-wrapper.field-wrapper--stacked {
-  @apply md:flex-col md:items-start gap-y-2 py-3;
+.field-wrapper {
+  @variant field-stacked {
+    @apply flex-col items-start gap-y-2 py-3;
 
-  .field-wrapper__label {
-    @apply md:w-full min-h-0 pt-0;
-  }
+    .field-wrapper__label {
+      @apply w-full min-h-0 pt-0;
+    }
 
-  .field-wrapper__label-help {
-    @apply pb-0;
-  }
+    .field-wrapper__label-help {
+      @apply pb-0;
+    }
 
-  .field-wrapper__content {
-    @apply pt-0 px-4 w-full;
-  }
+    .field-wrapper__content {
+      @apply pt-0 px-4 w-full;
+    }
 
-  .field-wrapper__content-wrapper {
-    @apply w-full;
+    .field-wrapper__content-wrapper {
+      @apply w-full;
+    }
   }
 }
 

data/app/assets/stylesheets/css/components/manual_frame.css

@@ -0,0 +1,38 @@
+.manual-frame {
+  @apply relative overflow-hidden rounded-lg border border-secondary px-4 py-3;
+}
+
+.manual-frame__overlay {
+  @apply absolute inset-0 z-10 flex items-center justify-center bg-primary/80 backdrop-blur-sm;
+}
+
+.manual-frame__loading {
+  @apply inline-flex items-center gap-2 rounded-lg border border-secondary bg-primary px-3 py-2 text-sm font-medium text-content shadow-panel;
+}
+
+.manual-frame__loading-icon {
+  @apply size-4 animate-spin text-content-secondary;
+}
+
+/* --- Error / Retry state -------------------------------------------------- */
+
+.manual-frame__error-row {
+  @apply flex items-center justify-between gap-3;
+}
+
+.manual-frame__error-message {
+  @apply inline-flex min-w-0 items-center gap-2 truncate text-sm text-content-secondary;
+}
+
+.manual-frame__error-icon {
+  @apply size-4 shrink-0 text-danger-content;
+}
+
+/* Dev-only "open this frame" note. */
+.manual-frame__error-note {
+  @apply mt-2 text-xs text-content-secondary;
+}
+
+.manual-frame__error-link {
+  @apply font-medium underline underline-offset-2;
+}

data/app/assets/stylesheets/css/components/modal.css

@@ -17,7 +17,7 @@
   /* size-full + m-0 + border-0/p-0/bg-transparent reset the popover UA chrome
      (fit-content sizing, auto margins, border, padding, background) so the
      element stays a transparent, full-viewport flex container that centers the card. */
-  @apply fixed inset-0 size-full m-0 border-0 p-0 bg-transparent justify-center items-center;
+  @apply fixed inset-0 size-full m-0 border-0 p-0 bg-transparent justify-center items-center overflow-hidden;
 
   /* Enter/leave transition duration, shared by the card and the backdrop.
      Keep in sync with TRANSITION_MS in base_modal_controller.js. */
@@ -59,16 +59,20 @@
 }
 
 .modal__card-container {
-  @apply flex flex-col items-center justify-center relative shrink-0 w-full;
+  @apply flex flex-col items-center justify-center relative min-h-0 size-full;
 }
 
 .modal__card {
-  @apply relative w-full shrink-0 flex flex-col;
+  @apply relative w-full shrink-0 flex flex-col min-h-0 overflow-hidden;
 
   /* Never exceed the viewport — keeps a tall (e.g. :auto height) modal fully
      on screen so its body can scroll instead of being clipped by the centered
-     overlay. */
+     overlay. The width clamp does the same horizontally: the size classes set a
+     preferred width (e.g. w-xl), but on a narrow phone screen it caps to the
+     viewport instead of overflowing and being clipped on both sides. The gutter
+     is tight on mobile to reclaim width and opens up to 2rem from sm up. */
   max-height: calc(100dvh - 2rem);
+  max-width: calc(100dvw - 1rem);
 
   box-shadow: var(--shadow-modal);
 
@@ -82,6 +86,14 @@
     transform var(--modal-transition-duration) ease-out;
 }
 
+/* Open the gutter back up from sm up, where the extra breathing room reads
+   better and the clamp rarely engages anyway. */
+@media (min-width: 640px) {
+  .modal__card {
+    max-width: calc(100dvw - 2rem);
+  }
+}
+
 .modal:popover-open .modal__card {
   opacity: 1;
   transform: scale(1);
@@ -126,19 +138,19 @@
    its wrapper fill the (capped) modal height and shrink, so the body's
    overflow-auto kicks in while the header and footer stay pinned. */
 .modal__card > .card {
-  @apply w-full flex-1 min-h-0;
+  @apply w-full flex-1 min-h-0 overflow-hidden;
 }
 
 .modal__card > .card > .card__wrapper {
-  @apply w-full flex flex-col flex-1 min-h-0;
+  @apply w-full flex flex-col flex-1 min-h-0 overflow-hidden;
 }
 
 .modal__card .card__header {
-  @apply py-3 px-4;
+  @apply py-3 px-4 shrink-0;
 }
 
 .modal__card > .card > .card__wrapper > .card__body {
-  @apply flex flex-col flex-1 gap-4 items-start pt-0 px-0 min-h-64;
+  @apply block flex-1 pt-0 px-0 min-h-0 overflow-auto border-0 rounded-none bg-transparent;
 }
 
 .modal__title {
@@ -158,7 +170,7 @@
 }
 
 .modal__body-content {
-  @apply size-full;
+  @apply w-full min-h-48 rounded-card-wrapper border border-tertiary bg-primary;
 }
 
 /* Belongs-to "Create new" embeds an edit form in the modal. Drop the nested
@@ -169,7 +181,7 @@
 }
 
 .modal__controls {
-  @apply flex items-center justify-between gap-2 py-2 px-3 w-full;
+  @apply flex items-center justify-between gap-2 py-2 px-3 w-full shrink-0;
 }
 
 /* When the controls hold only buttons, nudge the horizontal padding in so the

data/app/components/avo/fields/has_many_field/show_component.html.erb

@@ -1,3 +1,7 @@
-<%= turbo_frame_tag @field.turbo_frame, src: @field.frame_url, loading: turbo_frame_loading, target: :_top, class: "block" do %>
-  <%= render(Avo::LoadingComponent.new(title: @field.plural_name)) %>
+<% if @field.manual? && @field.view.display? && !helpers.manual_frame_remembered?(@field.frame_url, @field.auto_load_for) %>
+  <%= render Avo::ManualFrameComponent.new(@field.turbo_frame, deferred_url: @field.frame_url, title: @field.plural_name, description: @field.description(loading_type: :manual), auto_load_for: @field.auto_load_for, cookie_name: helpers.manual_frame_cookie_name(@field.frame_url)) %>
+<% else %>
+  <%= turbo_frame_tag @field.turbo_frame, src: @field.frame_url, loading: (@field.lazy_loading_mode? ? "lazy" : turbo_frame_loading), target: :_top, class: "block" do %>
+    <%= render(Avo::LoadingComponent.new(title: @field.plural_name)) %>
+  <% end %>
 <% end %>

data/app/components/avo/fields/has_one_field/show_component.html.erb

@@ -1,31 +1,35 @@
 <% if @field.value %>
-  <%= turbo_frame_tag @field.turbo_frame, src: @field.frame_url, loading: turbo_frame_loading, target: "_top", class: "block" do %>
-    <%= render(Avo::LoadingComponent.new(title: @field.name)) %>
+  <% if @field.manual? && @field.view.display? && !helpers.manual_frame_remembered?(@field.frame_url, @field.auto_load_for) %>
+    <%= render Avo::ManualFrameComponent.new(@field.turbo_frame, deferred_url: @field.frame_url, title: @field.name, description: @field.description(loading_type: :manual), auto_load_for: @field.auto_load_for, cookie_name: helpers.manual_frame_cookie_name(@field.frame_url)) %>
+  <% else %>
+    <%= turbo_frame_tag @field.turbo_frame, src: @field.frame_url, loading: (@field.lazy_loading_mode? ? "lazy" : turbo_frame_loading), target: "_top", class: "block" do %>
+      <%= render(Avo::LoadingComponent.new(title: @field.name)) %>
+    <% end %>
   <% end %>
 <% else %>
   <%= render ui.panel(title: @field.name) do |panel| %>
     <% panel.with_controls do %>
       <% if can_attach? %>
         <%= a_link attach_path,
-          icon: 'tabler/outline/link',
+          icon: "tabler/outline/link",
           color: :primary,
           style: :text,
           data: {
             turbo_frame: Avo::MODAL_FRAME_ID,
             target: :attach
           } do %>
-          <%= t('avo.attach_item', item: @field.name.humanize(capitalize: false)) %>
+          <%= t("avo.attach_item", item: @field.name.humanize(capitalize: false)) %>
         <% end %>
       <% end %>
 
       <% if can_see_the_create_button? %>
         <%= a_link create_path,
-          icon: 'tabler/outline/plus',
-          'data-target': 'create',
-          'data-turbo-frame': '_top',
+          icon: "tabler/outline/plus",
+          "data-target": "create",
+          "data-turbo-frame": "_top",
           style: :primary,
           color: :accent do %>
-          <%= t('avo.create_new_item', item: @field.name.humanize(capitalize: false) ) %>
+          <%= t("avo.create_new_item", item: @field.name.humanize(capitalize: false)) %>
         <% end %>
       <% end %>
     <% end %>

data/app/components/avo/manual_frame_component.html.erb

@@ -0,0 +1,60 @@
+<%# Manual (on-demand) Turbo Frame: no `src`; the Load button supplies it on click. %>
+<%= turbo_frame_tag @frame_id,
+      target: :_top,
+      class: "block",
+      data: {
+        manual_frame: true,
+        controller: "manual-frame",
+        manual_frame_url_value: @deferred_url,
+        manual_frame_auto_load_for_value: @auto_load_for,
+        manual_frame_cookie_name_value: @cookie_name
+      } do %>
+  <%# Placeholder state. %>
+  <div class="<%= class_names("manual-frame", @classes) %>" data-manual-frame-target="placeholder">
+    <%= render ui.panel_header(title: label, description: @description) do |header| %>
+      <% header.with_controls do %>
+        <%= a_button color: :primary,
+                     icon: "tabler/outline/ripple-down",
+                     aria: {label: load_label},
+                     data: {action: "manual-frame#load"} do %>
+          <%= load_label %>
+        <% end %>
+      <% end %>
+    <% end %>
+
+    <div
+      class="manual-frame__overlay"
+      data-manual-frame-target="loading"
+      aria-live="polite"
+      hidden>
+      <div class="manual-frame__loading">
+        <%= svg "tabler/outline/refresh", class: "manual-frame__loading-icon" %>
+        <span><%= t("avo.loading") %></span>
+      </div>
+    </div>
+  </div>
+
+  <%# Error/Retry state: a quiet inline message (danger-colored icon + muted %>
+  <%# copy), a low-key Retry, and a dev-only link to the failing URL. %>
+  <div
+    class="manual-frame"
+    data-manual-frame-target="error"
+    aria-live="polite"
+    hidden>
+    <div class="manual-frame__error-row">
+      <span class="manual-frame__error-message">
+        <%= svg "tabler/outline/alert-circle", class: "manual-frame__error-icon" %>
+        <%= t("avo.failed_to_load_item", item: label) %>
+      </span>
+
+      <%= a_button color: :gray,
+                   icon: "tabler/outline/refresh",
+                   aria: {label: retry_label},
+                   data: {action: "manual-frame#retry"} do %>
+        <%= t("avo.retry") %>
+      <% end %>
+    </div>
+
+    <%= dev_details_note %>
+  </div>
+<% end %>

data/app/components/avo/manual_frame_component.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Renders a `<turbo-frame>` with NO `src` that defers loading until the user
+# clicks the "Load" button. Used by manual (`loading: :manual`) tabs and
+# associations on Show pages.
+#
+# The frame carries the deferred URL in `data-manual-frame-url-value` for the
+# `manual-frame` Stimulus controller, which sets the frame `src` on click and
+# renders an inline error + Retry on failure. It is marked `data-manual-frame`
+# as an identifying hook.
+#
+# States (single component, three states):
+# - placeholder: title + a "Load <title>" button
+# - loading: `Avo::LoadingComponent` spinner while the request is in flight
+# - error: inline message + Retry
+class Avo::ManualFrameComponent < Avo::BaseComponent
+  # @param frame_id [String] the `<turbo-frame>` id (positional)
+  # @param deferred_url [String] the URL the controller loads on click
+  # @param title [String] label source; callers pass an already display-ready
+  #   name (a field's `plural_name`/`name` or a tab title), used verbatim
+  # @param description [String, nil] the field/tab description, shown beside the
+  #   title when present (already resolved by the caller)
+  # @param auto_load_for [Integer, nil] seconds the browser should remember an
+  #   opened frame and auto-load it on return (sliding window). `nil` disables
+  #   the memory — the frame stays a click-to-load placeholder every visit.
+  # @param cookie_name [String, nil] the cookie the Stimulus controller writes on
+  #   a successful load so the server can render this frame without the Load
+  #   button on the next visit. Paired with `auto_load_for`; both come from the
+  #   `manual_frame_*` application helpers. `nil` when there's no memory window.
+  # @param classes [String, nil] extra CSS classes for the placeholder container
+  prop :frame_id, kind: :positional
+  prop :deferred_url
+  prop :title
+  prop :description
+  prop :auto_load_for
+  prop :cookie_name
+  prop :classes
+
+  # The display label. Callers already hand us presentation-ready, translated
+  # text (field name / tab title), so we use it as-is. Never `humanize`, which
+  # would mangle custom or translated names ("Order Items" -> "Order items").
+  def label
+    @title.to_s
+  end
+
+  # "Load <title>", interpolated so the full phrase is translatable, matching
+  # the codebase's `attach_item`/`create_new_item` convention.
+  def load_label
+    t("avo.load_item", item: label)
+  end
+
+  # The Retry button's aria-label: "Retry <title>" (the visible copy is just
+  # "Retry"; the aria-label scopes it to this frame for screen readers).
+  def retry_label
+    t("avo.retry_item", item: label)
+  end
+
+  # In development only, a link straight to the deferred URL so a developer can
+  # open the failing frame on its own and read the real error / stack trace
+  # (the inline error state otherwise swallows the response). Mirrors the
+  # dev-only link in `avo/home/failed_to_load.html.erb`. Returns nil elsewhere.
+  def dev_details_note
+    return unless Rails.env.development? && @deferred_url.present?
+
+    helpers.tag.p(class: "manual-frame__error-note") do
+      helpers.safe_join([
+        "Follow ",
+        helpers.link_to("this link", @deferred_url, target: "_blank", rel: "noopener", class: "manual-frame__error-link"),
+        " for more details about the issue and how to fix it."
+      ])
+    end
+  end
+end

data/app/components/avo/tab_group_component.html.erb

@@ -28,7 +28,20 @@
         <% end %>
 
         <% if !tab.is_empty? %>
-          <% if tab.lazy_load && view.display? %>
+          <% if tab.manual? && view.display? %>
+            <% if !is_not_loaded?(tab) %>
+              <%= turbo_frame_tag tab.turbo_frame_id(parent: group), target: :_top, class: "block" do %>
+                <%= render Avo::TabContentComponent.new tab:, resource:, index:, form:, view: %>
+              <% end %>
+            <% elsif helpers.manual_frame_remembered?(manual_frame_url(tab), tab.auto_load_for) %>
+              <%# Remembered: render a real (lazy) frame so it loads with no Load button. %>
+              <%= turbo_frame_tag tab.turbo_frame_id(parent: group), **frame_args(tab) do %>
+                <%= render Avo::LoadingComponent.new(title: tab.title) %>
+              <% end %>
+            <% else %>
+              <%= render Avo::ManualFrameComponent.new(tab.turbo_frame_id(parent: group), deferred_url: manual_frame_url(tab), title: tab.title, description: tab.description, auto_load_for: tab.auto_load_for, cookie_name: helpers.manual_frame_cookie_name(manual_frame_url(tab))) %>
+            <% end %>
+          <% elsif (tab.lazy_load || tab.lazy_loading_mode?) && view.display? %>
             <%= turbo_frame_tag tab.turbo_frame_id(parent: group), **frame_args(tab) do %>
               <% if is_not_loaded?(tab) %>
                 <%= render Avo::LoadingComponent.new(title: tab.title) %>

data/app/components/avo/tab_group_component.rb

@@ -27,18 +27,26 @@ class Avo::TabGroupComponent < Avo::BaseComponent
 
     if is_not_loaded?(tab)
       args[:loading] = :lazy
-      args[:src] = helpers.resource_path(
-        resource: resource,
-        record: resource.record,
-        keep_query_params: true,
-        active_tab_title: tab.title,
-        tab_turbo_frame: tab.turbo_frame_id(parent: group)
-      )
+      args[:src] = manual_frame_url(tab)
     end
 
     args
   end
 
+  # The deferred load URL for a tab's turbo frame. Mirrors the `src` the lazy
+  # branch builds in `frame_args`, so a manual tab's Load button fetches the
+  # exact same proven URL — carrying `tab_turbo_frame` so `is_not_loaded?` is
+  # false on the framed re-render and the real `TabContentComponent` renders.
+  def manual_frame_url(tab)
+    helpers.resource_path(
+      resource: resource,
+      record: resource.record,
+      keep_query_params: true,
+      active_tab_title: tab.title,
+      tab_turbo_frame: tab.turbo_frame_id(parent: group)
+    )
+  end
+
   def is_not_loaded?(tab)
     params[:tab_turbo_frame] != tab.turbo_frame_id(parent: group)
   end

data/app/helpers/avo/application_helper.rb

@@ -5,6 +5,35 @@ module Avo
 
     def ui = Avo::UIInstance
 
+    # The cookie name that remembers an opened manual frame. Derived from the
+    # frame's deferred URL (which already encodes resource + record + frame), so
+    # the memory is scoped per record + association/tab. Hashed to keep the name
+    # short and cookie-safe. The `manual-frame` Stimulus controller writes this
+    # same name client-side on a successful load (see manual_frame_controller.js).
+    def manual_frame_cookie_name(url)
+      "amf_#{Digest::MD5.hexdigest(url.to_s)}"
+    end
+
+    # Whether this manual frame was opened recently enough to skip the placeholder
+    # and render a real auto-loading `<turbo-frame src>` (so the Load button never
+    # appears). Presence-based: the cookie carries `max-age`, so the browser drops
+    # it when the window lapses — a present cookie means "still remembered".
+    #
+    # Sliding: every render that finds it remembered refreshes the cookie, so the
+    # window keeps moving forward as long as the user keeps coming back.
+    #
+    # Returns false (and touches nothing) for plain `loading: :manual` frames,
+    # which carry no `auto_load_for` window.
+    def manual_frame_remembered?(url, auto_load_for)
+      return false if auto_load_for.blank?
+
+      name = manual_frame_cookie_name(url)
+      return false if request.cookies[name].blank?
+
+      cookies[name] = {value: "1", path: "/", max_age: auto_load_for.to_i, same_site: :lax}
+      true
+    end
+
     # Active Storage URL helpers raise UrlGenerationError when a blob's filename
     # is blank (the route requires a :filename segment). Use a synthetic filename
     # so attach mode and other callers still get a routable URL; return nil only

data/app/javascript/application.js

@@ -102,6 +102,12 @@ document.addEventListener('turbo:frame-load', () => {
 })
 
 document.addEventListener('turbo:before-fetch-response', async (e) => {
+  // Manual frames handle their own deferred-load failures inline and call
+  // `stopImmediatePropagation()` (see manual_frame_controller.js), so this
+  // global handler never sees them. We intentionally do NOT skip on the
+  // `data-manual-frame` attribute: once a manual frame has loaded, a later
+  // navigation inside its content that 500s should still fall through to the
+  // /failed_to_load page like any other frame.
   if (e.detail.fetchResponse.response.status === 500) {
     const { id, src } = e.target
     // Don't try to redirect to failed to load if this is already a redirection to failed to load and crashed somewhere.

data/app/javascript/js/controllers/manual_frame_controller.js

@@ -0,0 +1,160 @@
+import { Controller } from '@hotwired/stimulus'
+import { toggleHidden } from '../helpers/toggle_hidden'
+
+// Drives a manual (on-demand) Turbo Frame: the frame renders with NO `src`,
+// and clicking the Load button sets `src` from `data-manual-frame-url-value`
+// so the deferred content is fetched only on demand.
+//
+// The controller is attached to the `<turbo-frame>` element itself, so
+// `this.element` is the frame.
+//
+// We deliberately do NOT set `loading="lazy"`, so neither Turbo's lazy
+// auto-fetch nor the #886 strip handler touches this frame.
+//
+// Auto-load memory: when the frame is configured with a window
+// (`auto_load_for`), a successful load writes a short-lived cookie. The SERVER
+// reads that cookie on the next render and emits a real `<turbo-frame src>`
+// (no placeholder, no button) — so the controller never has to "auto-click".
+// All this controller does is write/refresh the cookie when the user opens the
+// frame; the decision to skip the button lives entirely on the server.
+export default class extends Controller {
+  static targets = ['placeholder', 'loading', 'error']
+
+  static values = {
+    url: String,
+    // The cookie name the server reads to decide whether to skip the Load
+    // button on the next visit. Empty when the frame has no memory window.
+    cookieName: String,
+    // Seconds the memory cookie should live (its max-age). 0 (the Stimulus
+    // default when the attribute is absent) = no memory.
+    autoLoadFor: Number,
+  }
+
+  connect() {
+    this.pending = false
+    this.awaitingFrameLoad = false
+    this.onRequestError = this.handleRequestError.bind(this)
+    this.onBeforeFetchResponse = this.handleBeforeFetchResponse.bind(this)
+    this.onFrameLoad = this.handleFrameLoad.bind(this)
+
+    this.element.addEventListener('turbo:fetch-request-error', this.onRequestError)
+    this.element.addEventListener('turbo:before-fetch-response', this.onBeforeFetchResponse)
+    this.element.addEventListener('turbo:frame-load', this.onFrameLoad)
+  }
+
+  disconnect() {
+    this.element.removeEventListener('turbo:fetch-request-error', this.onRequestError)
+    this.element.removeEventListener('turbo:before-fetch-response', this.onBeforeFetchResponse)
+    this.element.removeEventListener('turbo:frame-load', this.onFrameLoad)
+  }
+
+  // Click handler for the Load button.
+  load() {
+    if (this.pending) return // ignore repeat clicks while a request is in flight
+
+    this.pending = true
+    this.awaitingFrameLoad = false
+    this.showLoading()
+
+    // Setting `src` triggers Turbo to fetch and swap in the deferred content.
+    // On Retry the `src` is already this URL (a failed load leaves it in place),
+    // and re-setting an attribute to its current value is a no-op, so reload()
+    // to force a fresh fetch in that case.
+    if (this.element.getAttribute('src') === this.urlValue) {
+      this.element.reload()
+    } else {
+      this.element.src = this.urlValue
+    }
+  }
+
+  // Click handler for the Retry button: drop the error state and re-issue.
+  retry() {
+    this.load()
+  }
+
+  showLoading() {
+    this.setHidden(this.placeholderTarget, false)
+    this.setHidden(this.loadingTarget, false)
+    this.setHidden(this.errorTarget, true)
+  }
+
+  showError() {
+    this.setHidden(this.placeholderTarget, true)
+    this.setHidden(this.loadingTarget, true)
+    this.setHidden(this.errorTarget, false)
+  }
+
+  setHidden(element, hidden) {
+    if (!element) return
+    if (element.hasAttribute('hidden') === hidden) return
+
+    toggleHidden(element)
+  }
+
+  // --- Lifecycle ------------------------------------------------------------
+
+  // Our deferred load succeeded and Turbo swapped the real content in. Move
+  // focus into the frame so keyboard / screen-reader users aren't dropped to
+  // <body> when the Load button is removed from the DOM (R9).
+  handleFrameLoad() {
+    if (!this.awaitingFrameLoad) return // not our load (or a later navigation inside content)
+
+    this.awaitingFrameLoad = false
+
+    // Remember the open frame (and slide the window forward) — only on success,
+    // so a failed load never sets the memory.
+    this.rememberOpen()
+
+    this.element.setAttribute('tabindex', '-1')
+    this.element.focus({ preventScroll: true })
+  }
+
+  // Network failure / timeout (no HTTP response at all).
+  handleRequestError(event) {
+    if (!this.pending) return // a later in-frame navigation, let Turbo handle it
+
+    this.pending = false
+    event.stopImmediatePropagation()
+    this.showError()
+  }
+
+  // A response arrived; our deferred load is resolved either way. If it's not OK
+  // (status >= 400), stop Turbo from rendering the error body into the frame,
+  // stop the global `application.js` handler from hijacking it, and show our
+  // inline error instead.
+  handleBeforeFetchResponse(event) {
+    if (!this.pending) return // after our load resolves, later navigations are Turbo's
+
+    const response = event.detail?.fetchResponse?.response
+    if (!response) return
+
+    this.pending = false
+
+    if (response.ok) {
+      // Success: handleFrameLoad finishes the sequence (focus + memory) once
+      // Turbo renders the frame. `pending` is cleared HERE (not there) so that
+      // if `turbo:frame-load` never fires (e.g. the response is missing the
+      // matching frame), later in-frame navigations are never mistaken for the
+      // deferred load and still reach the global failure handler.
+      this.awaitingFrameLoad = true
+
+      return
+    }
+
+    event.preventDefault()
+    event.stopImmediatePropagation()
+    this.showError()
+  }
+
+  // --- Auto-load memory -----------------------------------------------------
+
+  // Write/refresh the cookie that tells the server "this frame is open, render
+  // it without the Load button next time." `max-age` gives it a sliding TTL —
+  // the browser drops it when the window lapses, and each successful load
+  // rewrites it with a fresh window. No-ops when the frame has no memory window.
+  rememberOpen() {
+    if (!this.cookieNameValue || this.autoLoadForValue <= 0) return
+
+    document.cookie = `${this.cookieNameValue}=1; path=/; max-age=${this.autoLoadForValue}; samesite=lax`
+  }
+}