From 3aeaacd87d92bbad4372fd6b61d7cdba4505217c Mon Sep 17 00:00:00 2001
From: Martin Castro Laminrs <mcastro@laminr.ai>
Date: Tue, 2 Jun 2026 18:33:59 +0200
Subject: [PATCH 1/2] test(examples): exercise html-fragment path in jobs
 custom-form fixture (#679)

The examples/jobs JobAdmin already ships the custom-template Path B
(?run_custom=1 dual-listbox change_view + run_custom.html + the
run_with_custom_steps action). Update its docstrings/comments from the old
legacy-iframe contract to the server-rendered html-fragment contract
(rest-api 1.7.0+, #75), and add JobHtmlFragmentApiTests covering the SPA's
actual API path end-to-end against the example backend:

  - GET .../form-spec/?run_custom=1 -> renderer "html-fragment" (dual-listbox
    markup + inline <script> + csrf_token + submit_url preserved);
  - POST .../change/?run_custom=1 with no selection -> re-rendered
    html-fragment carrying the error message (PRG-to-self);
  - POST with a selection -> renderer "redirect", target mapped onto the SPA
    prefix, success message carried for toasting.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 examples/jobs/admin.py                        | 20 +++--
 .../templates/admin/jobs/job/run_custom.html  |  8 +-
 examples/jobs/tests/test_admin.py             | 78 ++++++++++++++++++-
 3 files changed, 95 insertions(+), 11 deletions(-)

diff --git a/examples/jobs/admin.py b/examples/jobs/admin.py
index f49039d..312b594 100644
--- a/examples/jobs/admin.py
+++ b/examples/jobs/admin.py
@@ -1,21 +1,27 @@
-"""``JobAdmin`` — the custom-form fixture that proves the legacy-iframe escape.
+"""``JobAdmin`` — the custom-form fixture that exercises the html-fragment path.
 
 This admin uses *only* documented Django ``ModelAdmin`` hooks — no
 django-admin-react / -rest-api / -mcp-specific API. The point: if this runs
-on the React admin at ``/admin-react/`` with at most a single-view iframe
-fallback, then any legacy ``/admin/`` ModelAdmin does too.
+inside the React admin shell at ``/admin2/`` with the server-rendered
+html-fragment renderer, then any legacy ``/admin/`` ModelAdmin does too.
 
 Two rendering paths:
 
-* **Path A** — ``/admin-react/jobs/job/<pk>/change/`` (no query). The stock
+* **Path A** — ``/admin2/jobs/job/<pk>/change/`` (no query). The stock
   change form, fully describable by the form-spec contract.
   ``formfield_for_dbfield`` swaps ``metadata`` to a large textarea, which
   the SPA renders natively from ``widget.kind == "textarea"``.
 * **Path B** — ``?run_custom=1``. ``change_view`` returns a hand-rolled
   dual-listbox template (not a ModelForm, not fieldsets). The form-spec
-  resolver detects the custom render and returns
-  ``{renderer: "legacy-iframe", legacy_url: …}``; the SPA embeds the legacy
-  page in an iframe inside its own chrome.
+  resolver (rest-api 1.7.0+, #75) detects the custom render, renders it
+  SERVER-SIDE, strips the admin chrome, and returns
+  ``{renderer: "html-fragment", html, csrf_token, submit_url, method,
+  messages}``. The SPA injects that HTML inside its own shell — breadcrumb /
+  sidebar / title / toolbar stay React-rendered, no iframe (#679). The
+  injected ``<form>`` POSTs back through the round-trip route, which
+  re-renders on a validation error (``messages.error`` + redirect-to-self) or
+  returns ``{renderer: "redirect", to}`` on success — surfaced as a SPA
+  ``navigate()`` plus toasts.
 """
 
 from __future__ import annotations
diff --git a/examples/jobs/templates/admin/jobs/job/run_custom.html b/examples/jobs/templates/admin/jobs/job/run_custom.html
index 35c1bfa..ce57556 100644
--- a/examples/jobs/templates/admin/jobs/job/run_custom.html
+++ b/examples/jobs/templates/admin/jobs/job/run_custom.html
@@ -4,8 +4,12 @@
 
 This is a *pure custom template* with a custom POST contract: no ModelForm,
 no fieldsets, no model fields. The form-spec resolver detects this (the
-overridden change_view renders a non-standard template) and tells the React
-SPA to embed THIS legacy page in an iframe. The contract that must hold:
+overridden change_view renders a non-standard template), renders it
+server-side, strips the admin chrome, and hands the SPA the content-block
+HTML — including the inline <script>/<style> below — to inject INSIDE its own
+shell (no iframe, #679). The inline JS must survive into the SPA and run after
+injection (the SPA re-executes injected <script> elements). The contract that
+must hold:
 
   request.POST.getlist("selected_steps")  ← ordered, in DOM order of the
                                              right-hand column.
diff --git a/examples/jobs/tests/test_admin.py b/examples/jobs/tests/test_admin.py
index f00eb7d..c6981b5 100644
--- a/examples/jobs/tests/test_admin.py
+++ b/examples/jobs/tests/test_admin.py
@@ -1,8 +1,8 @@
 """Backend tests for the Job custom-form fixture.
 
 Exercises the legacy ``/admin/`` side of the contract — the side the React
-SPA embeds in an iframe for Path B. Pure Django ``TestCase`` + test client;
-no browser / e2e.
+SPA renders server-side as an html-fragment for Path B (#679). Pure Django
+``TestCase`` + test client; no browser / e2e.
 """
 
 from django.contrib import admin
@@ -66,3 +66,77 @@ def test_path_b_post_empty_is_rejected(self) -> None:
         # Redirects back to the same custom view with an error message.
         self.assertEqual(resp.status_code, 302)
         self.assertIn("run_custom=1", resp["Location"])
+
+
+class JobHtmlFragmentApiTests(TestCase):
+    """End-to-end exercise of the SPA's html-fragment path (#679) against the
+    example backend's REST API — the side the React SPA actually consumes.
+
+    The SPA fetches ``GET …/form-spec/?run_custom=1`` (→ ``html-fragment``)
+    and POSTs the injected form back to ``POST …/<pk>/change/?run_custom=1``
+    (→ another ``html-fragment`` on a validation error, or a ``redirect`` on
+    success, with Django ``messages`` surfaced for SPA toasts). Pure Django
+    ``TestCase`` + test client; no browser / e2e.
+    """
+
+    @classmethod
+    def setUpTestData(cls) -> None:
+        cls.user = get_user_model().objects.create_superuser(
+            username="root",
+            email="root@example.com",
+            password="x",  # noqa: S106
+        )
+        cls.job = Job.objects.create(name="nightly", status="idle")
+
+    def setUp(self) -> None:
+        self.client.force_login(self.user)
+
+    def _form_spec_url(self) -> str:
+        return f"/admin-react/api/v1/jobs/job/{self.job.pk}/form-spec/?run_custom=1"
+
+    def _change_post_url(self) -> str:
+        return f"/admin-react/api/v1/jobs/job/{self.job.pk}/change/?run_custom=1"
+
+    def test_form_spec_returns_html_fragment(self) -> None:
+        """The custom-template view resolves to a server-rendered html-fragment
+        (not the JSON form-spec, never an iframe)."""
+        resp = self.client.get(self._form_spec_url())
+        self.assertEqual(resp.status_code, 200)
+        payload = resp.json()
+        self.assertEqual(payload["renderer"], "html-fragment")
+        # The dual-listbox markup + the inline JS survive into the fragment.
+        self.assertIn('data-step="fetch"', payload["html"])
+        self.assertIn("<script>", payload["html"])
+        # The form wiring the SPA needs is present.
+        self.assertTrue(payload["csrf_token"])
+        self.assertEqual(payload["method"], "POST")
+        self.assertIn("run_custom=1", payload["submit_url"])
+
+    def test_post_empty_re_renders_fragment_with_error(self) -> None:
+        """An empty selection re-renders the fragment (the PRG-to-self idiom)
+        and carries the error message for the SPA to toast."""
+        resp = self.client.post(self._change_post_url(), data={})
+        self.assertEqual(resp.status_code, 200)
+        payload = resp.json()
+        self.assertEqual(payload["renderer"], "html-fragment")
+        self.assertTrue(
+            any(m["level"] == "error" for m in payload["messages"]),
+            payload["messages"],
+        )
+
+    def test_post_selection_redirects_to_spa(self) -> None:
+        """A valid selection redirects; the target is mapped onto the SPA prefix
+        and the success message is carried for the SPA to toast."""
+        resp = self.client.post(
+            self._change_post_url(),
+            data={"selected_steps": ["validate", "fetch"]},
+        )
+        self.assertEqual(resp.status_code, 200)
+        payload = resp.json()
+        self.assertEqual(payload["renderer"], "redirect")
+        # Mapped onto the SPA prefix (not the legacy /admin/ mount).
+        self.assertNotIn("/admin/", payload["to"])
+        self.assertTrue(
+            any("validate → fetch" in m["text"] for m in payload["messages"]),
+            payload["messages"],
+        )

From 59b176b5e201e950467e218684ff0fefebeded54 Mon Sep 17 00:00:00 2001
From: Martin Castro Laminrs <mcastro@laminr.ai>
Date: Tue, 2 Jun 2026 18:34:19 +0200
Subject: [PATCH 2/2] feat(spa): in-shell html-fragment rendering for custom
 change_form_template, drop iframe (#679)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 CHANGELOG.md                                  |  46 +++++
 README.md                                     |  85 ++++-----
 frontend/apps/web/src/legacy-url.test.ts      |  37 ----
 frontend/apps/web/src/legacy-url.ts           |  53 ------
 .../web/src/pages/detail/ChangeForm.test.tsx  |  73 ++++----
 .../apps/web/src/pages/detail/ChangeForm.tsx  |  24 ++-
 .../src/pages/detail/HtmlFragment.test.tsx    | 139 ++++++++++++++
 .../web/src/pages/detail/HtmlFragment.tsx     | 172 ++++++++++++++++++
 .../src/pages/detail/LegacyIframe.test.tsx    |  77 --------
 .../web/src/pages/detail/LegacyIframe.tsx     | 156 ----------------
 frontend/packages/api/src/client.ts           |  63 +++++++
 frontend/packages/api/src/contract.ts         |  63 ++++++-
 frontend/packages/data/src/index.ts           |   5 +-
 poetry.lock                                   |   8 +-
 pyproject.toml                                |  10 +-
 15 files changed, 578 insertions(+), 433 deletions(-)
 delete mode 100644 frontend/apps/web/src/legacy-url.test.ts
 delete mode 100644 frontend/apps/web/src/legacy-url.ts
 create mode 100644 frontend/apps/web/src/pages/detail/HtmlFragment.test.tsx
 create mode 100644 frontend/apps/web/src/pages/detail/HtmlFragment.tsx
 delete mode 100644 frontend/apps/web/src/pages/detail/LegacyIframe.test.tsx
 delete mode 100644 frontend/apps/web/src/pages/detail/LegacyIframe.tsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f69c790..5ffa5f9 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/README.md b/README.md
index a68e5d7..c52d96e 100644
--- a/README.md
+++ b/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.
 
 ---
 
diff --git a/frontend/apps/web/src/legacy-url.test.ts b/frontend/apps/web/src/legacy-url.test.ts
deleted file mode 100644
index 460203b..0000000
--- a/frontend/apps/web/src/legacy-url.test.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { safeLegacyUrl } from './legacy-url';
-
-const ORIGIN = 'https://admin.example.com';
-
-describe('safeLegacyUrl (#665)', () => {
-  it('accepts a same-origin relative legacy-admin path and returns an absolute same-origin URL', () => {
-    expect(safeLegacyUrl({ url: '/admin/auth/group/1/change/', currentOrigin: ORIGIN })).toBe(
-      'https://admin.example.com/admin/auth/group/1/change/',
-    );
-  });
-
-  it('accepts an absolute same-origin http(s) URL', () => {
-    expect(
-      safeLegacyUrl({ url: 'https://admin.example.com/admin/x/', currentOrigin: ORIGIN }),
-    ).toBe('https://admin.example.com/admin/x/');
-  });
-
-  it('rejects a javascript: URL (anchor-click code execution)', () => {
-    expect(safeLegacyUrl({ url: "javascript:alert(1)", currentOrigin: ORIGIN })).toBeNull();
-  });
-
-  it('rejects data: and blob: schemes', () => {
-    expect(safeLegacyUrl({ url: 'data:text/html,<h1>x', currentOrigin: ORIGIN })).toBeNull();
-    expect(safeLegacyUrl({ url: 'blob:https://admin.example.com/abc', currentOrigin: ORIGIN })).toBeNull();
-  });
-
-  it('rejects an off-origin http(s) URL (phishing surface inside admin chrome)', () => {
-    expect(safeLegacyUrl({ url: 'https://attacker.example/', currentOrigin: ORIGIN })).toBeNull();
-    expect(safeLegacyUrl({ url: '//attacker.example/x', currentOrigin: ORIGIN })).toBeNull();
-  });
-
-  it('rejects an unparseable URL', () => {
-    expect(safeLegacyUrl({ url: 'http://[::bad', currentOrigin: ORIGIN })).toBeNull();
-  });
-});
diff --git a/frontend/apps/web/src/legacy-url.ts b/frontend/apps/web/src/legacy-url.ts
deleted file mode 100644
index dd5ee41..0000000
--- a/frontend/apps/web/src/legacy-url.ts
+++ /dev/null
@@ -1,53 +0,0 @@
-// Legacy-iframe URL validation (#665).
-//
-// The form-spec endpoint can return `{renderer: "legacy-iframe", legacy_url}`
-// to embed the legacy admin change/add page inside the SPA shell (#659). That
-// URL flows into both an `<iframe src>` and an `<a href target=_blank>`, so it
-// reaches two navigational sinks. The SPA *should* be able to trust the API,
-// but every other navigational sink in this codebase validates before using a
-// server-supplied URL (`action-redirect.ts` parses + origin/mount-checks the
-// action redirect; `views.py` percent-encodes `next`). This is the one
-// server-emitted URL that previously reached `src`/`href` unchecked — a
-// compromised, buggy, or request-influenced backend could emit a
-// `javascript:` URL (executes from the anchor on click) or an off-origin
-// `http://attacker/` URL (renders attacker content inside the authenticated
-// admin chrome — a high-fidelity phishing surface). We close that with the
-// same parse-and-validate discipline used elsewhere.
-//
-// The legacy admin lives on the SAME origin as the SPA (under its own admin
-// prefix, NOT the SPA mount), so the rule is: parse against the current
-// origin, require an `http:`/`https:` scheme, and require the parsed origin to
-// equal the current origin. Anything else (a non-http(s) scheme like
-// `javascript:`/`data:`/`blob:`, or a cross-origin target) is rejected and the
-// caller renders an inert error card instead of framing/linking it.
-
-export interface ValidateLegacyUrlArgs {
-  url: string;
-  /** Current page origin. Defaults to `window.location.origin`; the test
-   *  injects a known value (jsdom's origin is fixed). */
-  currentOrigin?: string;
-}
-
-/**
- * Return a safe, same-origin http(s) URL string, or `null` when the URL is
- * unparseable, uses a non-http(s) scheme, or points off-origin.
- *
- * Returning the *re-serialised* parsed URL (not the raw input) means the value
- * handed to `src`/`href` is exactly what passed validation — no room for a
- * parser-differential between the check and the sink.
- */
-export function safeLegacyUrl(args: ValidateLegacyUrlArgs): string | null {
-  const origin = args.currentOrigin ?? window.location.origin;
-  let parsed: URL;
-  try {
-    parsed = new URL(args.url, origin);
-  } catch {
-    return null;
-  }
-  // Reject `javascript:` / `data:` / `blob:` / `mailto:` etc. outright — only
-  // real navigable web schemes are allowed in an iframe/anchor here.
-  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
-  // The legacy admin is same-origin; an off-origin target is never legitimate.
-  if (parsed.origin !== origin) return null;
-  return parsed.href;
-}
diff --git a/frontend/apps/web/src/pages/detail/ChangeForm.test.tsx b/frontend/apps/web/src/pages/detail/ChangeForm.test.tsx
index a01e849..2cee90a 100644
--- a/frontend/apps/web/src/pages/detail/ChangeForm.test.tsx
+++ b/frontend/apps/web/src/pages/detail/ChangeForm.test.tsx
@@ -1,10 +1,13 @@
 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 };
 
@@ -12,7 +15,7 @@ vi.mock('@dar/data', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@dar/data')>();
   return {
     ...actual,
-    useApiClient: () => ({}),
+    useApiClient: () => ({ submitChangeFragment: vi.fn() }),
     useFormSpec: () => specState,
   };
 });
@@ -36,15 +39,19 @@ 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>,
   );
 }
 
@@ -52,42 +59,26 @@ 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', () => {
diff --git a/frontend/apps/web/src/pages/detail/ChangeForm.tsx b/frontend/apps/web/src/pages/detail/ChangeForm.tsx
index 051e75f..05d18db 100644
--- a/frontend/apps/web/src/pages/detail/ChangeForm.tsx
+++ b/frontend/apps/web/src/pages/detail/ChangeForm.tsx
@@ -1,9 +1,10 @@
-// ChangeForm — the form-spec-driven change form (#659).
+// ChangeForm — the form-spec-driven change form (#659, #679).
 //
 // On edit, fetch the ModelAdmin-resolved form spec (rest-api 1.4.0+, #59)
 // and render:
-//   - the legacy admin in an iframe, when the admin overrides
-//     `change_form_template` (`renderer: "legacy-iframe"`);
+//   - a server-rendered html-fragment INSIDE the SPA shell, when the admin
+//     overrides `change_form_template` (`renderer: "html-fragment"`,
+//     rest-api 1.7.0+, #679) — no iframe;
 //   - otherwise the existing EditForm, with its fields + fieldsets sourced
 //     from the spec (request-aware get_form / fieldsets / readonly, the
 //     closed widget.kind enum) instead of being discovered client-side
@@ -22,7 +23,7 @@ import {
 import { RecordSkeleton } from '../../components/RecordSkeleton';
 import { detailFromFormSpec } from './adaptFormSpec';
 import { EditForm, type SaveAction } from './EditForm';
-import { LegacyIframe } from './LegacyIframe';
+import { HtmlFragment } from './HtmlFragment';
 
 export interface ChangeFormProps {
   data: DetailResponse;
@@ -67,8 +68,19 @@ export function ChangeForm({
   }
   if (!spec) return <EditForm data={data} onCancel={onCancel} onSave={onSave} />;
 
-  if (spec.renderer === 'legacy-iframe') {
-    return <LegacyIframe url={spec.legacy_url} onCancel={onCancel} />;
+  if (spec.renderer === 'html-fragment') {
+    // Custom `change_form_template` (#679): inject the server-rendered form
+    // in-shell. `onCancel` is unused here — the fragment owns its own
+    // submit/cancel affordances and redirects via SPA navigate.
+    return (
+      <HtmlFragment
+        fragment={spec}
+        appLabel={appLabel}
+        modelName={modelName}
+        pk={pk}
+        query={query ?? ''}
+      />
+    );
   }
 
   return (
diff --git a/frontend/apps/web/src/pages/detail/HtmlFragment.test.tsx b/frontend/apps/web/src/pages/detail/HtmlFragment.test.tsx
new file mode 100644
index 0000000..2920d1d
--- /dev/null
+++ b/frontend/apps/web/src/pages/detail/HtmlFragment.test.tsx
@@ -0,0 +1,139 @@
+// @vitest-environment-options { "runScripts": "dangerously" }
+//
+// The script-execution assertion needs jsdom to actually run injected
+// `<script>` elements (the default jsdom config leaves them inert). Real
+// browsers always run a freshly-created+inserted script — that's exactly the
+// re-execution path HtmlFragment relies on for the dual-listbox JS (#679).
+import '@testing-library/jest-dom/vitest';
+
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { ChangePostPayload, HtmlFragmentResponse } from '@dar/data';
+
+import { ToastProvider } from '../../toast';
+
+// The SPA navigate the redirect path must call (NOT window.location).
+const navigateMock = vi.fn();
+vi.mock('react-router-dom', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('react-router-dom')>();
+  return { ...actual, useNavigate: () => navigateMock };
+});
+
+// The mocked API client; `submitChangeFragment` is set per test.
+const submitMock = vi.fn<(args: unknown) => Promise<ChangePostPayload>>();
+vi.mock('@dar/data', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@dar/data')>();
+  return { ...actual, useApiClient: () => ({ submitChangeFragment: submitMock }) };
+});
+
+const { HtmlFragment } = await import('./HtmlFragment');
+
+function fragment(overrides: Partial<HtmlFragmentResponse> = {}): HtmlFragmentResponse {
+  return {
+    renderer: 'html-fragment',
+    html:
+      '<form id="run-custom-form">' +
+      '<input type="hidden" name="selected_steps" value="fetch" />' +
+      '<button type="submit">Queue</button>' +
+      '</form>' +
+      // Inline <script> that mutates the DOM — must execute after injection.
+      // (We assert via the DOM mutation, not a window global: jsdom runs the
+      // script against its own internal window, which differs from the test's
+      // `window` reference, but DOM writes are observable either way — and the
+      // DOM is exactly what the dual-listbox JS manipulates.)
+      '<script>var f = document.getElementById("run-custom-form");' +
+      'f.setAttribute("data-script-ran", String(' +
+      '(parseInt(f.getAttribute("data-script-ran") || "0", 10) || 0) + 1));</script>',
+    csrf_token: 'csrf-123',
+    submit_url: '/admin/jobs/job/1/change/?run_custom=1',
+    method: 'POST',
+    messages: [],
+    ...overrides,
+  };
+}
+
+function renderFragment(frag: HtmlFragmentResponse) {
+  return render(
+    <MemoryRouter>
+      <ToastProvider>
+        <HtmlFragment
+          fragment={frag}
+          appLabel="jobs"
+          modelName="job"
+          pk="1"
+          query="run_custom=1"
+        />
+      </ToastProvider>
+    </MemoryRouter>,
+  );
+}
+
+beforeEach(() => {
+  navigateMock.mockReset();
+  submitMock.mockReset();
+});
+
+describe('HtmlFragment (#679)', () => {
+  it('injects the fragment in-shell and EXECUTES inline <script> (no iframe)', () => {
+    renderFragment(fragment());
+    expect(document.querySelector('iframe')).toBeNull();
+    const form = document.querySelector('#run-custom-form');
+    expect(form).toBeInTheDocument();
+    // The dual-listbox JS path: a naive dangerouslySetInnerHTML would NOT run
+    // this; the re-execution step makes it run exactly once (the count is "1",
+    // not "11" / "2" — proof it executed exactly once, not zero or twice).
+    expect(form).toHaveAttribute('data-script-ran', '1');
+  });
+
+  it('round-trips a POST through a validation error (re-inject) then a redirect (navigate)', async () => {
+    // First submit → another html-fragment (validation error) → re-inject;
+    // second submit → redirect → SPA navigate.
+    submitMock
+      .mockResolvedValueOnce(
+        fragment({
+          html: '<form id="run-custom-form"><span class="err">Pick at least one step.</span>' +
+            '<button type="submit">Queue</button></form>',
+          messages: [{ level: 'error', text: 'Pick at least one step.' }],
+        }),
+      )
+      .mockResolvedValueOnce({
+        renderer: 'redirect',
+        to: '/admin2/jobs/job/1/change/',
+        messages: [{ level: 'success', text: 'Queued fetch' }],
+      } satisfies ChangePostPayload);
+
+    renderFragment(fragment());
+
+    // First submit → validation re-inject, no navigation.
+    fireEvent.submit(document.querySelector('#run-custom-form') as HTMLFormElement);
+    await waitFor(() => expect(submitMock).toHaveBeenCalledTimes(1));
+    // POSTs FormData + the fragment's CSRF token to the round-trip route.
+    expect(submitMock.mock.calls[0]?.[0]).toMatchObject({
+      appLabel: 'jobs',
+      modelName: 'job',
+      pk: '1',
+      query: 'run_custom=1',
+      csrfToken: 'csrf-123',
+      method: 'POST',
+    });
+    expect(submitMock.mock.calls[0]?.[0]).toHaveProperty('body');
+    // The re-injected fragment shows the validation error inside the host
+    // (the same text is also toasted, so scope to the fragment host).
+    const host = screen.getByTestId('html-fragment-host');
+    await waitFor(() =>
+      expect(within(host).getByText('Pick at least one step.')).toBeInTheDocument(),
+    );
+    expect(navigateMock).not.toHaveBeenCalled();
+
+    // Second submit (on the re-injected form) → redirect → SPA navigate.
+    fireEvent.submit(document.querySelector('#run-custom-form') as HTMLFormElement);
+    await waitFor(() => expect(navigateMock).toHaveBeenCalledWith('/admin2/jobs/job/1/change/'));
+  });
+
+  it('toasts the fragment messages on initial load', () => {
+    renderFragment(fragment({ messages: [{ level: 'success', text: 'Queued fetch → validate' }] }));
+    expect(screen.getByText('Queued fetch → validate')).toBeInTheDocument();
+  });
+});
diff --git a/frontend/apps/web/src/pages/detail/HtmlFragment.tsx b/frontend/apps/web/src/pages/detail/HtmlFragment.tsx
new file mode 100644
index 0000000..cfbc2e8
--- /dev/null
+++ b/frontend/apps/web/src/pages/detail/HtmlFragment.tsx
@@ -0,0 +1,172 @@
+// HtmlFragment — render a server-rendered custom change form INSIDE the SPA
+// shell (#679). Replaces the old legacy-iframe escape hatch entirely.
+//
+// When a ModelAdmin overrides `change_form_template` (or renders a custom
+// template from a `change_view` branch like `?run_custom=1`), the JSON
+// form-spec can't reproduce the form, so the backend (rest-api 1.7.0+, #75)
+// renders the admin's real view server-side, strips the admin chrome, and
+// returns `{renderer: "html-fragment", html, csrf_token, submit_url, method,
+// messages}`. We inject `html` into the content area while the breadcrumb,
+// sidebar, title, and toolbar stay React-rendered — no iframe, so no
+// `X-Frame-Options` / `SameSite` failure mode ever again.
+//
+// TRUST BOUNDARY (#679): `html` is TRUSTED. It is the integrator's own admin
+// template, rendered by their backend behind the same auth as `/admin/`, and
+// delivered over the same authenticated, same-origin API as every other
+// payload. We DELIBERATELY do not sanitise it: the custom form's inline
+// `<script>` (dual-listbox handlers, drag-and-drop, embedded widgets) and
+// `<style>` are part of the form contract and MUST run. This is the same
+// trust the integrator already places in their legacy admin. The fragment is
+// never cross-origin and never attacker-controlled in a correctly-deployed
+// admin; the threat model is identical to the legacy `/admin/` page itself.
+//
+// Because React's `dangerouslySetInnerHTML` does NOT execute `<script>`
+// elements parsed from a string (the HTML spec disables scripts inserted via
+// innerHTML), we parse the fragment, mount the non-script markup, then clone
+// each `<script>` into a fresh element and append it so the browser executes
+// it — the dual-listbox JS only works because of this re-execution step.
+
+import { useCallback, useEffect, useRef } from 'react';
+import { useNavigate } from 'react-router-dom';
+
+import { type ChangePostPayload, type HtmlFragmentResponse, useApiClient } from '@dar/data';
+import { Card } from '@dar/ui';
+
+import { toastMessages, useToast } from '../../toast';
+
+export interface HtmlFragmentProps {
+  fragment: HtmlFragmentResponse;
+  appLabel: string;
+  modelName: string;
+  pk: string;
+  /** Original change-form querystring (e.g. `run_custom=1`), forwarded so the
+   *  request-aware `change_view` resolves the same branch on POST. */
+  query?: string;
+}
+
+/**
+ * Re-execute `<script>` elements within an injected fragment.
+ *
+ * `dangerouslySetInnerHTML` / `innerHTML` parse `<script>` tags into inert
+ * elements — the HTML parser flags scripts inserted that way as
+ * "already started", so they never run. To make the integrator's inline JS
+ * run, we walk the injected scripts, build a fresh `<script>` for each
+ * (copying attributes + text), and swap it in. A newly *created* and
+ * *inserted* script element executes per the DOM spec.
+ */
+function executeScripts(container: HTMLElement): void {
+  const scripts = Array.from(container.querySelectorAll('script'));
+  for (const old of scripts) {
+    const replacement = document.createElement('script');
+    for (const attr of Array.from(old.attributes)) {
+      replacement.setAttribute(attr.name, attr.value);
+    }
+    replacement.text = old.textContent ?? '';
+    old.replaceWith(replacement);
+  }
+}
+
+export function HtmlFragment({ fragment, appLabel, modelName, pk, query }: HtmlFragmentProps) {
+  const client = useApiClient();
+  const navigate = useNavigate();
+  const toast = useToast();
+
+  const hostRef = useRef<HTMLDivElement | null>(null);
+  // The fragment currently injected. Held in a ref (not state) so the submit
+  // handler always reads the live fragment after a validation re-inject
+  // without re-binding the form listener.
+  const fragmentRef = useRef<HtmlFragmentResponse>(fragment);
+  // Toast the messages from each payload exactly once (success on first load,
+  // errors on a validation round-trip). Tracks the last-toasted reference.
+  const toastedRef = useRef<HtmlFragmentResponse['messages'] | null>(null);
+
+  // Inject markup + (re-)wire the form. Factored out so a validation-error
+  // round-trip can re-inject without a full SPA route change (#679).
+  const inject = useCallback(
+    (frag: HtmlFragmentResponse) => {
+      const host = hostRef.current;
+      if (!host) return;
+      fragmentRef.current = frag;
+      // Replace the previous fragment wholesale.
+      host.innerHTML = frag.html;
+      // Make inline <script> run (innerHTML-parsed scripts are inert).
+      executeScripts(host);
+
+      // Surface this payload's Django messages as toasts, once.
+      if (frag.messages.length > 0 && toastedRef.current !== frag.messages) {
+        toastedRef.current = frag.messages;
+        toastMessages(
+          toast,
+          frag.messages.map((m) => ({ level: m.level, message: m.text })),
+        );
+      }
+    },
+    [toast],
+  );
+
+  // Submit handler for the injected <form>. Captured-phase listener on the
+  // host so it sees the submit before the browser performs a native
+  // navigation, which we prevent.
+  const onSubmit = useCallback(
+    (event: SubmitEvent) => {
+      const form = event.target;
+      if (!(form instanceof HTMLFormElement)) return;
+      event.preventDefault();
+      const frag = fragmentRef.current;
+      const body = new FormData(form);
+      void (async () => {
+        let result: ChangePostPayload;
+        try {
+          result = await client.submitChangeFragment({
+            appLabel,
+            modelName,
+            pk,
+            query: query ?? '',
+            body,
+            csrfToken: frag.csrf_token,
+            method: frag.method,
+          });
+        } catch {
+          toast.error('Could not submit the form. Please try again.');
+          return;
+        }
+        if (result.renderer === 'redirect') {
+          // Toast first (the redirect tears down this component), then SPA
+          // navigate — never a window.location reload.
+          if (result.messages.length > 0) {
+            toastMessages(
+              toast,
+              result.messages.map((m) => ({ level: m.level, message: m.text })),
+            );
+          }
+          navigate(result.to);
+          return;
+        }
+        // Another html-fragment → validation errors / self-redirect re-render.
+        // Re-inject in place, preserving the SPA route.
+        inject(result);
+      })();
+    },
+    [client, appLabel, modelName, pk, query, navigate, toast, inject],
+  );
+
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return undefined;
+    inject(fragment);
+    host.addEventListener('submit', onSubmit, true);
+    return () => {
+      host.removeEventListener('submit', onSubmit, true);
+    };
+    // `inject` / `onSubmit` are stable across renders (their deps are stable);
+    // re-run only when the initial fragment changes (a new edit-mode entry).
+  }, [fragment, inject, onSubmit]);
+
+  return (
+    <Card>
+      {/* The server-rendered custom form, injected in-shell. `data-testid`
+          lets the snapshot/interaction test locate the host. */}
+      <div ref={hostRef} data-testid="html-fragment-host" />
+    </Card>
+  );
+}
diff --git a/frontend/apps/web/src/pages/detail/LegacyIframe.test.tsx b/frontend/apps/web/src/pages/detail/LegacyIframe.test.tsx
deleted file mode 100644
index f88b163..0000000
--- a/frontend/apps/web/src/pages/detail/LegacyIframe.test.tsx
+++ /dev/null
@@ -1,77 +0,0 @@
-import '@testing-library/jest-dom/vitest';
-
-import { act, render, screen } from '@testing-library/react';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { LegacyIframe } from './LegacyIframe';
-
-const SAME_ORIGIN = '/admin/jobs/job/1/change/?run_custom=1';
-
-beforeEach(() => {
-  vi.useFakeTimers();
-});
-
-afterEach(() => {
-  vi.runOnlyPendingTimers();
-  vi.useRealTimers();
-});
-
-describe('LegacyIframe refusal detection (#673)', () => {
-  it('points the iframe src at the same URL as the Open-in-new-tab link', () => {
-    render(<LegacyIframe url={SAME_ORIGIN} onCancel={() => {}} refuseAfterMs={4000} />);
-    const iframe = screen.getByTitle('Legacy admin form') as HTMLIFrameElement;
-    const link = screen.getByRole('link', { name: /open in new tab/i }) as HTMLAnchorElement;
-    expect(iframe.src).toBe(link.href);
-    expect(iframe.src).toContain('/admin/jobs/job/1/change/');
-  });
-
-  it('keeps the iframe when onLoad fires before the timeout (loaded)', () => {
-    render(<LegacyIframe url={SAME_ORIGIN} onCancel={() => {}} refuseAfterMs={4000} />);
-    const iframe = screen.getByTitle('Legacy admin form');
-    act(() => {
-      iframe.dispatchEvent(new Event('load'));
-    });
-    // Advancing past the refusal window must NOT flip a successfully loaded
-    // frame to the fallback.
-    act(() => {
-      vi.advanceTimersByTime(5000);
-    });
-    expect(screen.getByTitle('Legacy admin form')).toBeInTheDocument();
-    expect(screen.queryByText(/embedding refused/i)).not.toBeInTheDocument();
-  });
-
-  it('renders the refused fallback (no broken-image iframe) when onLoad never fires', () => {
-    render(<LegacyIframe url={SAME_ORIGIN} onCancel={() => {}} refuseAfterMs={4000} />);
-    expect(screen.getByTitle('Legacy admin form')).toBeInTheDocument();
-
-    // No `load` event ever arrives (X-Frame-Options: DENY). After the
-    // timeout the SPA concludes the frame was refused.
-    act(() => {
-      vi.advanceTimersByTime(4000);
-    });
-
-    // The broken-image iframe is gone; a clear fallback takes its place.
-    expect(screen.queryByTitle('Legacy admin form')).not.toBeInTheDocument();
-    expect(screen.getByText(/embedding refused by the legacy admin/i)).toBeInTheDocument();
-    // Open-in-new-tab (the proven-working top-level navigation) is offered.
-    const link = screen.getByRole('link', { name: /open in new tab/i }) as HTMLAnchorElement;
-    expect(link.href).toContain('/admin/jobs/job/1/change/');
-  });
-
-  it('does not flip to refused before the timeout elapses', () => {
-    render(<LegacyIframe url={SAME_ORIGIN} onCancel={() => {}} refuseAfterMs={4000} />);
-    act(() => {
-      vi.advanceTimersByTime(3999);
-    });
-    expect(screen.getByTitle('Legacy admin form')).toBeInTheDocument();
-    expect(screen.queryByText(/embedding refused/i)).not.toBeInTheDocument();
-  });
-
-  it('still rejects an off-origin URL with the inert error card (no iframe, no timer)', () => {
-    render(
-      <LegacyIframe url="https://attacker.example/admin/" onCancel={() => {}} refuseAfterMs={4000} />,
-    );
-    expect(screen.queryByTitle('Legacy admin form')).not.toBeInTheDocument();
-    expect(screen.getByText(/can’t be displayed/i)).toBeInTheDocument();
-  });
-});
diff --git a/frontend/apps/web/src/pages/detail/LegacyIframe.tsx b/frontend/apps/web/src/pages/detail/LegacyIframe.tsx
deleted file mode 100644
index f6cf8dc..0000000
--- a/frontend/apps/web/src/pages/detail/LegacyIframe.tsx
+++ /dev/null
@@ -1,156 +0,0 @@
-// LegacyIframe — embed the legacy admin change/add page inside the SPA
-// shell (#659 escape hatch).
-//
-// When a ModelAdmin overrides `change_form_template` / `add_form_template`,
-// the form can't be faithfully rendered from the JSON form spec, so the
-// backend returns `{renderer: "legacy-iframe", legacy_url}`. The breadcrumb,
-// sidebar, and toolbar stay SPA-rendered; only the form body is the legacy
-// page. Integrators can port the custom form to documented ModelAdmin hooks
-// at their own pace without blocking SPA adoption.
-//
-// Load-failure detection (#673): most projects mount
-// `django.middleware.clickjacking.XFrameOptionsMiddleware`, which sets
-// `X-Frame-Options: DENY` on EVERY response — including the legacy admin
-// page. The browser then refuses to render the framed document and paints
-// its broken-image glyph (document-with-X), with NO reliable `error` event
-// on the `<iframe>`. We detect the refusal with a `loading | loaded |
-// refused` state machine: `onLoad` flips us to `loaded`; a ~4s timeout that
-// fires while still `loading` (no onLoad ever arrived) flips us to
-// `refused`, and we swap the iframe for a clear fallback ("Embedding refused
-// — open in new tab") instead of leaving the browser's broken-image icon on
-// screen. See README › "Embedding the legacy admin" for the backend headers
-// (`X-Frame-Options: SAMEORIGIN`, cross-origin `frame-ancestors`, cookies).
-
-import { useEffect, useRef, useState } from 'react';
-import { ExternalLink } from 'lucide-react';
-
-import { Button, Card, t } from '@dar/ui';
-
-import { safeLegacyUrl } from '../../legacy-url';
-
-export interface LegacyIframeProps {
-  url: string;
-  onCancel: () => void;
-  /** Milliseconds to wait for the iframe's `load` event before concluding
-   *  the legacy admin refused to be framed. Exposed for tests; defaults to
-   *  the 4s the issue prescribes. */
-  refuseAfterMs?: number;
-}
-
-type FrameStatus = 'loading' | 'loaded' | 'refused';
-
-export function LegacyIframe({ url, onCancel, refuseAfterMs = 4000 }: LegacyIframeProps) {
-  // Validate the server-supplied `legacy_url` before it reaches the iframe
-  // `src` / anchor `href` (#665): same-origin + http(s) only. A
-  // `javascript:` / `data:` URL or an off-origin target is rejected and we
-  // render an inert error card instead — never frame/link an unvalidated URL.
-  const safe = safeLegacyUrl({ url });
-
-  const [status, setStatus] = useState<FrameStatus>('loading');
-  // Hold the timer id across renders so the cleanup can clear it.
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  // Arm the refusal timeout once we have a framable URL. If `onLoad` never
-  // fires (X-Frame-Options: DENY / frame-ancestors block), the timeout marks
-  // the frame `refused`; if it already loaded, the timeout is a no-op.
-  useEffect(() => {
-    if (safe === null) return;
-    timerRef.current = setTimeout(() => {
-      setStatus((prev) => (prev === 'loading' ? 'refused' : prev));
-    }, refuseAfterMs);
-    return () => {
-      if (timerRef.current !== null) clearTimeout(timerRef.current);
-    };
-    // `safe` re-derives from `url`; re-arm if the target changes.
-  }, [safe, refuseAfterMs]);
-
-  if (safe === null) {
-    return (
-      <Card>
-        <div className="space-y-3">
-          <p className="text-sm text-red-700">
-            {t('This form can’t be displayed: its address is invalid or points off-site.')}
-          </p>
-          <Button type="button" variant="ghost" onClick={onCancel}>
-            {t('Cancel')}
-          </Button>
-        </div>
-      </Card>
-    );
-  }
-
-  const openInNewTab = (
-    <a
-      href={safe}
-      target="_blank"
-      rel="noopener noreferrer"
-      className="inline-flex items-center gap-1.5 rounded-md border border-gray-300 bg-white px-3 py-1.5 text-sm font-medium text-gray-700 hover:bg-gray-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500"
-    >
-      <ExternalLink className="h-4 w-4" aria-hidden /> {t('Open in new tab')}
-    </a>
-  );
-
-  // The legacy admin refused to be framed — render an explicit fallback with
-  // the same Open-in-new-tab affordance, NEVER the browser's broken-image
-  // glyph (#673). The "Open in new tab" link is the proven-working escape
-  // hatch (a top-level navigation isn't subject to X-Frame-Options).
-  if (status === 'refused') {
-    return (
-      <Card>
-        <div className="space-y-3">
-          <p className="text-sm text-gray-700">
-            {t(
-              'Embedding refused by the legacy admin — open in new tab. (The legacy backend' +
-                ' sent X-Frame-Options / frame-ancestors that block framing; see the' +
-                ' integration guide for the headers to allow it.)',
-            )}
-          </p>
-          <div className="flex flex-wrap items-center gap-2">
-            {openInNewTab}
-            <Button type="button" variant="ghost" onClick={onCancel}>
-              {t('Cancel')}
-            </Button>
-          </div>
-        </div>
-      </Card>
-    );
-  }
-
-  return (
-    <Card>
-      <div className="space-y-3">
-        <div className="flex flex-wrap items-center justify-between gap-2">
-          <p className="text-xs text-gray-500">
-            {t('This form is rendered by the legacy admin (custom change_form_template).')}
-          </p>
-          <div className="flex shrink-0 items-center gap-2">
-            {openInNewTab}
-            <Button type="button" variant="ghost" onClick={onCancel}>
-              {t('Cancel')}
-            </Button>
-          </div>
-        </div>
-        <iframe
-          src={safe}
-          title={t('Legacy admin form')}
-          // Refusal detection (#673): a successful frame fires `load`; we mark
-          // it `loaded` and the refusal timer becomes a no-op. (We don't try
-          // to read `contentDocument` — the sandbox makes a same-origin page
-          // opaque, and a thrown SecurityError would be indistinguishable from
-          // success — the `load` event firing at all is the signal.)
-          onLoad={() => {
-            if (timerRef.current !== null) clearTimeout(timerRef.current);
-            setStatus('loaded');
-          }}
-          // Defence-in-depth (#665): the legacy admin needs forms + scripts +
-          // same-origin cookies to function, but this explicit allowlist drops
-          // the unsafe-by-default capabilities — `allow-top-navigation`,
-          // `allow-popups`, `allow-modals` — so a framed page can't break out
-          // of the admin chrome even if `legacy_url` were ever subverted.
-          sandbox="allow-forms allow-scripts allow-same-origin"
-          className="h-[70vh] w-full rounded border border-gray-200 bg-white"
-        />
-      </div>
-    </Card>
-  );
-}
diff --git a/frontend/packages/api/src/client.ts b/frontend/packages/api/src/client.ts
index 3aa46dc..2008063 100644
--- a/frontend/packages/api/src/client.ts
+++ b/frontend/packages/api/src/client.ts
@@ -10,6 +10,7 @@ import type {
   AddFormResponse,
   BulkUpdateEntry,
   BulkUpdateResponse,
+  ChangePostPayload,
   CreatePayload,
   CreateResponse,
   DeletePreviewResponse,
@@ -282,6 +283,68 @@ export class ApiClient {
     return this.request<FormSpecPayload>('GET', `${base}${qs}`);
   }
 
+  /**
+   * Submit a server-rendered html-fragment change form (#679). The SPA POSTs
+   * the injected `<form>`'s FormData back to the REST round-trip route
+   * `POST <app>/<model>/<pk>/change/?<qs>`, which re-runs the legacy
+   * `change_view` server-side and returns either another `html-fragment`
+   * (validation errors / self-redirect re-render) or a `redirect`.
+   *
+   * `query` is the original change-form querystring (e.g. `run_custom=1`) so
+   * the request-aware `change_view` resolves the same branch. The FormData is
+   * sent as-is (multipart) — the browser sets `Content-Type` with the
+   * boundary — with `credentials: "include"` and the `X-CSRFToken` header set
+   * from the fragment's `csrf_token` (the backend's CSRF middleware honours
+   * the header; no `@csrf_exempt`). Bypasses the JSON `request()` helper
+   * because the body is FormData, not JSON.
+   */
+  async submitChangeFragment(args: {
+    appLabel: string;
+    modelName: string;
+    pk: string | number;
+    query?: string;
+    body: FormData;
+    csrfToken: string;
+    method?: string;
+  }): Promise<ChangePostPayload> {
+    const qs = args.query ? (args.query.startsWith('?') ? args.query : `?${args.query}`) : '';
+    const path = `${args.appLabel}/${args.modelName}/${args.pk}/change/${qs}`;
+    const response = await this.fetchImpl(this.url(path), {
+      method: args.method ?? 'POST',
+      credentials: 'include',
+      headers: {
+        Accept: 'application/json',
+        // The fragment carries its own CSRF token; send it in the header the
+        // Django CSRF middleware checks (don't set Content-Type — the browser
+        // adds the multipart boundary for FormData).
+        'X-CSRFToken': args.csrfToken,
+      },
+      body: args.body,
+    });
+
+    const text = await response.text();
+    let parsed: unknown = null;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        // Fall through with parsed === null.
+      }
+    }
+    if (!response.ok) {
+      const envelope = (parsed ?? null) as FieldErrorEnvelope | null;
+      if (this.isSessionAuthFailure(response.status, envelope)) {
+        this.onAuthFailure?.();
+      }
+      throw new ApiError(
+        response.status,
+        envelope,
+        envelope?.error?.message ?? `HTTP ${response.status}`,
+      );
+    }
+    return parsed as ChangePostPayload;
+  }
+
   /** Object-history timeline (GET <app>/<model>/<pk>/history/) — #244. */
   history(
     appLabel: string,
diff --git a/frontend/packages/api/src/contract.ts b/frontend/packages/api/src/contract.ts
index b6a41b1..2315997 100644
--- a/frontend/packages/api/src/contract.ts
+++ b/frontend/packages/api/src/contract.ts
@@ -745,8 +745,9 @@ export interface FormSpecField {
  * Response of `GET /api/v1/<app>/<model>/<pk>/form-spec/` (or
  * `…/add/form-spec/`) — the ModelAdmin-resolved form (rest-api 1.4.0+,
  * #59). Either the JSON form spec (`renderer: "form-spec"`) or, when the
- * admin overrides `change_form_template` / `add_form_template`, a pointer
- * to embed the legacy admin page in an iframe (`renderer: "legacy-iframe"`).
+ * admin overrides `change_form_template` / `add_form_template`, a
+ * server-rendered html-fragment the SPA injects in-shell
+ * (`renderer: "html-fragment"`, rest-api 1.7.0+, #679).
  */
 export interface FormSpecResponse {
   renderer: 'form-spec';
@@ -766,13 +767,61 @@ export interface FormSpecResponse {
   prepopulated_fields?: Record<string, string[]>;
 }
 
-/** Escape hatch: embed the legacy admin change/add page in an iframe. */
-export interface LegacyIframeResponse {
-  renderer: 'legacy-iframe';
-  legacy_url: string;
+/**
+ * One Django `messages` entry surfaced from a server-rendered html-fragment
+ * round-trip (#679). `level` is Django's level tag (`success` / `error` /
+ * `warning` / `info` / `debug`); `text` is the rendered message. The SPA
+ * toasts these via the shared `toastMessages` adapter.
+ */
+export interface FragmentMessage {
+  level: string;
+  text: string;
+}
+
+/**
+ * Escape hatch for a custom `change_form_template` / `add_form_template`
+ * admin (rest-api 1.7.0+, #679). The backend renders the admin's real
+ * change/add view SERVER-SIDE, strips the admin chrome, and returns the
+ * content-block HTML for the SPA to inject inside its own shell — no iframe,
+ * so no `X-Frame-Options` / `SameSite` failure mode.
+ *
+ * `html` is TRUSTED: it is the integrator's own admin template, rendered by
+ * their backend behind the same auth as `/admin/`, and is injected verbatim
+ * (inline `<script>` / `<style>` execute — that's the contract; see
+ * `HtmlFragment.tsx` for the trust boundary). `submit_url` + `method` +
+ * `csrf_token` wire the injected `<form>`; `messages` are toasted.
+ */
+export interface HtmlFragmentResponse {
+  renderer: 'html-fragment';
+  html: string;
+  csrf_token: string;
+  submit_url: string;
+  method: string;
+  messages: FragmentMessage[];
+}
+
+/**
+ * The POST round-trip (`POST <app>/<model>/<pk>/change/?<qs>`, #679) returns
+ * this when the legacy `change_view` redirects on success. `to` is the legacy
+ * target already mapped onto the SPA prefix by the backend (e.g.
+ * `/admin2/jobs/job/1/change/`); the SPA `navigate(to)`s it (never a full
+ * `window.location` reload). `messages` are toasted.
+ */
+export interface RedirectResponse {
+  renderer: 'redirect';
+  to: string;
+  messages: FragmentMessage[];
 }
 
-export type FormSpecPayload = FormSpecResponse | LegacyIframeResponse;
+/** GET `…/form-spec/` resolves to one of these (#679: no more `legacy-iframe`). */
+export type FormSpecPayload = FormSpecResponse | HtmlFragmentResponse;
+
+/**
+ * POST `…/<pk>/change/` (the html-fragment round-trip, #679) resolves to
+ * another html-fragment (validation errors / self-redirect re-render) or a
+ * redirect (success).
+ */
+export type ChangePostPayload = HtmlFragmentResponse | RedirectResponse;
 
 /**
  * One object-history entry (Django LogEntry) — `GET <app>/<model>/<pk>/history/`.
diff --git a/frontend/packages/data/src/index.ts b/frontend/packages/data/src/index.ts
index af2b983..0c58901 100644
--- a/frontend/packages/data/src/index.ts
+++ b/frontend/packages/data/src/index.ts
@@ -37,7 +37,10 @@ export type {
   FormSpecField,
   FormSpecPayload,
   FormSpecResponse,
-  LegacyIframeResponse,
+  HtmlFragmentResponse,
+  RedirectResponse,
+  ChangePostPayload,
+  FragmentMessage,
   WidgetBlock,
   WidgetHint,
   WidgetKind,
diff --git a/poetry.lock b/poetry.lock
index 40bbb36..1f3516c 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -488,14 +488,14 @@ jsonschema = ">=4.0,<5.0"
 
 [[package]]
 name = "django-admin-rest-api"
-version = "1.6.0"
+version = "1.7.0"
 description = "A JSON REST API for the Django admin — same permissions, same ModelAdmin, no new features. Powers django-admin-react and django-admin-mcp."
 optional = false
 python-versions = "<4.0,>=3.10"
 groups = ["main"]
 files = [
-    {file = "django_admin_rest_api-1.6.0-py3-none-any.whl", hash = "sha256:18cf550223ab19e44610235e43b6052bc8afa0cfa384e7c67b4039ff5f304021"},
-    {file = "django_admin_rest_api-1.6.0.tar.gz", hash = "sha256:6f8e79d42f343edddd2663eab43364e449391b8b86df1e82e4c5682a5dc58a4e"},
+    {file = "django_admin_rest_api-1.7.0-py3-none-any.whl", hash = "sha256:a82730af5c750d6031c21f0d9c26557c023040d33db285480ce2781d58b5e6f6"},
+    {file = "django_admin_rest_api-1.7.0.tar.gz", hash = "sha256:a854b498bc9bec32edffa9ffa6c7da7ec902188ef2e8050867e5901688b7dfe8"},
 ]
 
 [package.dependencies]
@@ -1900,4 +1900,4 @@ zstd = ["backports-zstd (>=1.0.0) ; python_version < \"3.14\""]
 [metadata]
 lock-version = "2.1"
 python-versions = "^3.10"
-content-hash = "754f98cf4853954ac4d142f7430c9ad0b3469cd1c2f2701c9f22f47c1b346cb0"
+content-hash = "1e492debbef3834f9cb768aa24a1f98181f301169ac6f6b0f908636da580c1b3"
diff --git a/pyproject.toml b/pyproject.toml
index ca4418c..95d5e80 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-admin-react"
-version = "1.11.2"
+version = "1.12.0"
 description = "A drop-in React single-page admin for Django, driven entirely by ModelAdmin."
 authors = ["django-admin-react contributors"]
 license = "MIT"
@@ -61,7 +61,13 @@ django = ">=4.2,<7.0"
 # Raised to 1.6.0 in v1.11.0 (#664): the form-spec wire now emits
 # `prepopulated_fields` and autocomplete hints, which the SPA's widget-kind
 # rendering consumes (slugify-on-keystroke + autocomplete widget).
-django-admin-rest-api = "^1.6.0"
+# Raised to 1.7.0 in v1.12.0 (#679): the form-spec endpoint now renders a
+# custom `change_form_template` admin SERVER-SIDE and returns
+# `renderer: "html-fragment"` (html / csrf_token / submit_url / method /
+# messages) plus a POST round-trip route (another html-fragment for
+# validation errors, or `{renderer: "redirect", to}`); the SPA injects the
+# fragment in-shell. The `legacy-iframe` renderer is gone (no more iframe).
+django-admin-rest-api = "^1.7.0"
 # `django-admin-mcp-api` — MCP-protocol adapter over the same REST API
 # so agents reach the SAME `ModelAdmin`-driven surface. Wire-protocol-only
 # layer; adds NO new functionality, permissions, or validation.