feat(spa): in-shell html-fragment rendering for custom change_form_template, drop iframe (#679)

Replace the legacy-iframe escape hatch with the server-rendered html-fragment
renderer (rest-api 1.7.0+, #75). A custom change_form_template / change_view
admin now renders INSIDE the SPA shell — no iframe, so no X-Frame-Options /
SameSite / cross-origin cookie failure mode ever again.

ChangeForm: renderer "html-fragment" -> new HtmlFragment component injects the
content HTML into the SPA shell (breadcrumb / sidebar / title / toolbar stay
React-rendered). Because dangerouslySetInnerHTML leaves parsed <script>
elements inert, HtmlFragment clones each injected <script> into a fresh element
and re-inserts it so it executes (required for the dual-listbox JS). The
injected <form>'s submit is wired to ApiClient.submitChangeFragment, which
POSTs the FormData to the round-trip route with credentials + X-CSRFToken from
the fragment. On response: another html-fragment re-injects in place
(validation errors, no SPA route change); { renderer: "redirect", to } triggers
an SPA navigate(to) (never window.location); messages[] surface as toasts via
the shared toastMessages adapter. The backend HTML is trusted (the integrator's
own admin template behind the same auth) and injected verbatim — the trust
boundary is documented in HtmlFragment.tsx.

Removed the iframe path entirely: LegacyIframe(.test), legacy-url(.test) and
the #673 framing-refusal workaround. contract.ts drops LegacyIframeResponse /
"legacy-iframe" and adds HtmlFragmentResponse + RedirectResponse (+ the
ChangePostPayload union + FragmentMessage); @dar/data re-exports updated.

No regression for ModelAdmins using only documented hooks (form / fieldsets /
formfield_overrides / get_form) — those keep rendering via the JSON field-map
path.

Bump django-admin-rest-api dep to ^1.7.0; version 1.11.2 -> 1.12.0; CHANGELOG
[1.12.0] section; README "Embedding the legacy admin in an iframe" section
rewritten as "Custom change_form_template admins — rendered in-shell".

Closes #679

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: martin-castro-laminr-ai

CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.12.0] — 2026-06-02
+
+### Added
+- **Custom `change_form_template` admins now render INSIDE the SPA shell via a
+  server-rendered html-fragment — no iframe (#679).** The form-spec endpoint
+  (rest-api 1.7.0+, #75) renders a custom-template admin server-side, strips
+  the admin chrome, and returns `{renderer: "html-fragment", html, csrf_token,
+  submit_url, method, messages}`. The SPA injects that HTML into the content
+  area while the breadcrumb / sidebar / title / toolbar stay React-rendered.
+  Inline `<script>` / `<style>` the integrator's template emits **execute /
+  apply after injection**: `dangerouslySetInnerHTML` leaves parsed `<script>`
+  elements inert, so the new `HtmlFragment` component clones each into a fresh
+  `<script>` and re-inserts it (the dual-listbox JS only runs because of this).
+  The injected `<form>` POSTs via `fetch(…, {credentials: "include", headers:
+  {"X-CSRFToken": …}})` to the round-trip route; a returned `html-fragment`
+  re-injects in place (validation errors, no SPA route change), a
+  `{renderer: "redirect", to}` triggers an SPA `navigate(to)` (never a
+  `window.location` reload), and any Django `messages` surface as toasts.
+  The backend HTML is **trusted** — it is the integrator's own admin template,
+  rendered behind the same auth as `/admin/` over the same-origin API — so the
+  custom JS/CSS is injected verbatim, deliberately not sanitised (see the
+  `HtmlFragment.tsx` trust-boundary note). ModelAdmins that use only documented
+  hooks (`form` / `fieldsets` / `formfield_overrides` / `get_form`) are
+  unaffected — they keep rendering via the JSON field-map path. The
+  `examples/jobs` `?run_custom=1` dual-listbox fixture exercises the full path
+  (form-spec → POST → validation re-render → redirect) end-to-end against the
+  example backend.
+
+### Removed
+- **The `legacy-iframe` renderer and its iframe fallback are gone (#679).**
+  No iframe element is ever rendered for a custom-template form again. This
+  drops `LegacyIframe` (and the #673 "detect framing refusal → open-in-new-tab"
+  workaround) and the `safeLegacyUrl` same-origin validation that only guarded
+  the iframe `src`. Custom-template admins now render in-shell via the
+  html-fragment renderer above — no `X-Frame-Options`, `SameSite=None; Secure`,
+  or cross-origin cookie bridge required. The contract type drops
+  `LegacyIframeResponse` / `renderer: "legacy-iframe"` and adds
+  `HtmlFragmentResponse` (`renderer: "html-fragment"`) + `RedirectResponse`
+  (`renderer: "redirect"`).
+
+### Changed
+- **`django-admin-rest-api` floor raised to `^1.7.0` (#679).** 1.7.0 ships the
+  html-fragment form-spec renderer (`renderer: "html-fragment"`) plus the POST
+  round-trip route the in-shell custom form submits to. The SPA still degrades
+  gracefully to the JSON form-spec / detail-driven form on an older backend.
+
 ## [1.11.2] — 2026-06-02
 
 ### Fixed

README.md

@@ -651,7 +651,7 @@ issues link the work to close each gap.
 
 | Stock-Django hook | SPA behaviour | Tracked |
 |---|---|---|
-| `change_form_template` / `add_form_template` overrides | **Embedded in an iframe** (since 1.9.0, #659): the change/add form-spec endpoint returns a `legacy-iframe` pointer and the SPA embeds the legacy admin page inside the SPA shell (breadcrumb / sidebar / toolbar stay SPA-rendered). Port the form to documented ModelAdmin hooks at your own pace. | [#624](https://github.com/MartinCastroAlvarez/django-admin-react/issues/624) |
+| `change_form_template` / `add_form_template` overrides | **Rendered server-side as an html-fragment, in-shell** (since 1.12.0, #679): the change/add form-spec endpoint renders the custom template server-side, strips the admin chrome, and returns `{renderer: "html-fragment", html, …}`; the SPA injects it into the content area while the breadcrumb / sidebar / title / toolbar stay React-rendered. The injected form's inline `<script>` / `<style>` run, its submit round-trips through the API (validation re-render / redirect / `messages` toasts), and **no iframe is used** — so no `X-Frame-Options` / `SameSite` configuration is required. Port the form to documented ModelAdmin hooks at your own pace. | [#624](https://github.com/MartinCastroAlvarez/django-admin-react/issues/624) |
 | `change_list_template` / `change_password_template` / `object_history_template` overrides | Silently ignored — those surfaces render entirely from the JSON wire. | [#624](https://github.com/MartinCastroAlvarez/django-admin-react/issues/624) |
 | `formfield_overrides = {Field: {"widget": CustomWidget}}` | Custom widget rendered via the React widget-registration API (`registerFieldWidget`, #625) when the consumer registers a renderer for the widget class; otherwise falls back to the default control + an operator-visible "not registered" note. | [#625](https://github.com/MartinCastroAlvarez/django-admin-react/issues/625) |
 | `empty_value_display` | **Hard-coded to `—`.** A per-`ModelAdmin` / per-field `empty_value_display` override is **not** surfaced — the SPA renders the literal em-dash for every empty value, regardless of the consumer's chosen placeholder. | [#629](https://github.com/MartinCastroAlvarez/django-admin-react/issues/629) |
@@ -667,56 +667,43 @@ typical workaround is to keep that model on the legacy
 [experience-toggle strip](#experience-toggle-strip-optional) — the
 SPA + legacy admin happily coexist.
 
-#### Embedding the legacy admin in an iframe — required backend headers
-
-When a `ModelAdmin` overrides `change_form_template` / `add_form_template`,
-the SPA embeds the legacy admin page in an `<iframe>` (the row above). For
-the browser to actually render that frame, the **legacy admin responses must
-allow being framed by the SPA's origin** — otherwise the embed is refused and
-the SPA shows a "Embedding refused by the legacy admin — open in new tab"
-fallback (never a broken-image icon, #673).
-
-Most projects mount `django.middleware.clickjacking.XFrameOptionsMiddleware`,
-which by default sets `X-Frame-Options: DENY` on **every** response and blocks
-the iframe. Configure the legacy responses as follows:
-
-**Same origin (SPA and legacy admin under one host — the common case):**
-
-```python
-# settings.py
-X_FRAME_OPTIONS = "SAMEORIGIN"   # was the implicit "DENY"
-# …or drop XFrameOptionsMiddleware entirely if you don't need clickjacking
-# protection on the legacy surface.
-```
-
-`SAMEORIGIN` lets the same-origin SPA frame the legacy page while still
-blocking cross-site framing.
-
-**Cross-origin (SPA and legacy admin on different origins):**
-
-```python
-# On the legacy admin responses (e.g. via a middleware or
-# django-csp), allow ONLY the SPA origin to frame them:
-#   Content-Security-Policy: frame-ancestors https://admin.example.com
-#
-# And, because the iframe is a cross-site context, the legacy session
-# cookie must be sent in it:
-# settings.py
-SESSION_COOKIE_SAMESITE = "None"   # send the cookie in the cross-site frame
-SESSION_COOKIE_SECURE = True       # required whenever SameSite=None
+#### Custom `change_form_template` admins — rendered in-shell (no iframe)
+
+When a `ModelAdmin` overrides `change_form_template` / `add_form_template`
+(or a `change_view` override renders a non-standard template — e.g. a
+`?run_custom=1` branch), the JSON form-spec can't reproduce the form. Since
+1.12.0 (#679) the form-spec endpoint (rest-api 1.7.0+) renders the admin's
+real view **server-side**, strips the admin chrome, and returns the content
+HTML for the SPA to inject inside its own shell:
+
+```json
+{
+  "renderer": "html-fragment",
+  "html": "<form …>…</form>",
+  "csrf_token": "…",
+  "submit_url": "/admin/<app>/<model>/<pk>/change/?<qs>",
+  "method": "POST",
+  "messages": [{ "level": "success", "text": "…" }]
+}
 ```
 
-Without these, the framed legacy page either refuses to load (`frame-ancestors`
-block) or loads unauthenticated (cookie dropped) and bounces through a login
-redirect the browser then refuses to display. The
-[`examples/jobs`](examples/jobs) `JobAdmin` (the `?run_custom=1` variant)
-exercises this path end-to-end against the example backend.
-
-> The SPA detects a refused frame client-side (a `loading → loaded → refused`
-> state machine: a ~4s window with no iframe `load` event ⇒ refused) and
-> renders the fallback. A future server-side `legacy_iframeable` flag computed
-> from the response middleware chain (cross-repo, rest-api) could switch to the
-> "open in new tab only" UI immediately — tracked as a follow-up.
+The SPA injects `html` into the content area (breadcrumb / sidebar / title /
+toolbar stay React-rendered), **re-executes** the template's inline
+`<script>` (so custom-widget JS / dual-listbox handlers / drag-and-drop run),
+and wires the injected `<form>` to POST back through the API round-trip route
+(`credentials: "include"` + `X-CSRFToken`). On the response: another
+`html-fragment` re-injects in place (validation errors), a
+`{renderer: "redirect", to}` triggers an SPA `navigate(to)`, and any Django
+`messages` surface as toasts.
+
+This needs **no iframe**, so there is nothing to configure: no
+`X-Frame-Options`, no `Content-Security-Policy: frame-ancestors`, no
+`SESSION_COOKIE_SAMESITE = "None"` cross-origin cookie bridge. The fragment is
+same-origin and trusted (it is your own admin template, rendered behind the
+same auth as `/admin/`), so its custom JS/CSS is injected verbatim. The
+[`examples/jobs`](examples/jobs) `JobAdmin` (the `?run_custom=1` dual-listbox
+variant) exercises the full path — form-spec → POST → validation re-render →
+redirect — end-to-end against the example backend.
 
 ---
 

frontend/apps/web/src/legacy-url.test.ts

@@ -1,18 +1,21 @@
 import '@testing-library/jest-dom/vitest';
 
 import { render, screen } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { DetailResponse, FormSpecPayload } from '@dar/data';
 
+import { ToastProvider } from '../../toast';
+
 // Mocked SWR state the mocked useFormSpec returns, set per test.
 let specState: { data: FormSpecPayload | null; loading: boolean; error: Error | null };
 
 vi.mock('@dar/data', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@dar/data')>();
   return {
     ...actual,
-    useApiClient: () => ({}),
+    useApiClient: () => ({ submitChangeFragment: vi.fn() }),
     useFormSpec: () => specState,
   };
 });
@@ -36,58 +39,46 @@ function detail(): DetailResponse {
 
 function renderChangeForm() {
   return render(
-    <ChangeForm
-      data={detail()}
-      appLabel="auth"
-      modelName="group"
-      pk="1"
-      query=""
-      onCancel={() => {}}
-      onSave={async () => {}}
-    />,
+    <MemoryRouter>
+      <ToastProvider>
+        <ChangeForm
+          data={detail()}
+          appLabel="auth"
+          modelName="group"
+          pk="1"
+          query=""
+          onCancel={() => {}}
+          onSave={async () => {}}
+        />
+      </ToastProvider>
+    </MemoryRouter>,
   );
 }
 
 beforeEach(() => {
   specState = { data: null, loading: false, error: null };
 });
 
-describe('ChangeForm (#659)', () => {
-  it('embeds the legacy admin in an iframe when the backend returns legacy-iframe', () => {
+describe('ChangeForm (#659, #679)', () => {
+  it('injects the server-rendered html-fragment in-shell (no iframe) (#679)', () => {
     specState = {
-      data: { renderer: 'legacy-iframe', legacy_url: '/admin/auth/group/1/change/' },
-      loading: false,
-      error: null,
-    };
-    renderChangeForm();
-    const iframe = screen.getByTitle('Legacy admin form') as HTMLIFrameElement;
-    expect(iframe).toBeInTheDocument();
-    expect(iframe.src).toContain('/admin/auth/group/1/change/');
-    // #665: the iframe is sandboxed with an explicit allowlist (no
-    // allow-top-navigation / allow-popups / allow-modals).
-    expect(iframe.getAttribute('sandbox')).toBe('allow-forms allow-scripts allow-same-origin');
-  });
-
-  it('rejects a javascript: legacy_url and renders an inert error card (no iframe) (#665)', () => {
-    specState = {
-      data: { renderer: 'legacy-iframe', legacy_url: 'javascript:fetch("/admin/")' },
-      loading: false,
-      error: null,
-    };
-    renderChangeForm();
-    expect(screen.queryByTitle('Legacy admin form')).not.toBeInTheDocument();
-    expect(screen.getByText(/can’t be displayed/i)).toBeInTheDocument();
-  });
-
-  it('rejects an off-origin legacy_url and renders the error card (#665)', () => {
-    specState = {
-      data: { renderer: 'legacy-iframe', legacy_url: 'https://attacker.example/admin/' },
+      data: {
+        renderer: 'html-fragment',
+        html: '<form id="run-custom-form"><button type="submit">Queue</button></form>',
+        csrf_token: 'tok',
+        submit_url: '/admin/auth/group/1/change/',
+        method: 'POST',
+        messages: [],
+      },
       loading: false,
       error: null,
     };
     renderChangeForm();
-    expect(screen.queryByTitle('Legacy admin form')).not.toBeInTheDocument();
-    expect(screen.getByText(/can’t be displayed/i)).toBeInTheDocument();
+    // No iframe is ever rendered for a custom-template form.
+    expect(document.querySelector('iframe')).toBeNull();
+    // The fragment's own <form> is injected inside the SPA shell.
+    expect(document.querySelector('#run-custom-form')).toBeInTheDocument();
+    expect(screen.getByTestId('html-fragment-host')).toBeInTheDocument();
   });
 
   it('renders the form-spec fields (request-aware get_form / fieldsets) via EditForm', () => {