From 2d3b80487f3de2070448c55b92316ea708665fca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mart=C3=ADn?= <martincastro.10.5@gmail.com>
Date: Mon, 1 Jun 2026 22:26:16 +0200
Subject: [PATCH] feat(spa): form-spec-driven change form + legacy-iframe
 fallback (#659) + 1.9.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The change form is now driven by the rest-api form-spec endpoint
(GET <app>/<model>/<pk>/form-spec/, django-admin-rest-api 1.4.0+ #59)
instead of discovering fields client-side from the model serializer, so
the SPA honours the ModelAdmin layer: request-aware get_form /
get_fieldsets / get_readonly_fields, formfield_overrides, custom Form
classes, and the admin relation widgets — resolved server-side and
mapped through the closed widget.kind enum.

- The original change-form querystring is forwarded, so a get_form that
  swaps the Form on ?variant=… renders the legacy admin's fields.
- A change_form_template / add_form_template override returns
  renderer: "legacy-iframe"; the SPA embeds the legacy admin page in an
  iframe inside the SPA shell (closes part of #624) rather than silently
  dropping the customisation.
- A spec-fetch failure (older backend) degrades gracefully to the
  previous detail-payload-driven form.

Implementation reuses the battle-tested FieldInput/EditForm: a small
adapter maps each FormSpecField onto the existing FieldDescriptor (the
backend reuses the detail serializer for `initial`, so value shapes line
up). New: FormSpecResponse/WidgetKind wire types, client.formSpec(),
useFormSpec hook, adaptFormSpec, LegacyIframe, ChangeForm. i18n strings
for es/fr/pt. 11 new tests (adapter mapping + ChangeForm branches:
iframe, form-spec fields, custom-widget fallback, graceful degradation).

Raises the django-admin-rest-api floor to ^1.4.0 (the endpoint) and the
django-admin-mcp-api floor to >=1.2.0 (the parity tool, #70).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  23 ++++
 README.md                                     |   3 +-
 frontend/apps/web/src/pages/DetailPage.tsx    |  15 +-
 .../web/src/pages/detail/ChangeForm.test.tsx  | 130 ++++++++++++++++++
 .../apps/web/src/pages/detail/ChangeForm.tsx  |  77 +++++++++++
 .../web/src/pages/detail/LegacyIframe.tsx     |  50 +++++++
 .../src/pages/detail/adaptFormSpec.test.ts    |  96 +++++++++++++
 .../web/src/pages/detail/adaptFormSpec.ts     |  86 ++++++++++++
 frontend/packages/api/src/client.ts           |  23 ++++
 frontend/packages/api/src/contract.ts         |  95 +++++++++++++
 .../packages/data/src/form-spec-context.tsx   |  46 +++++++
 frontend/packages/data/src/index.ts           |   9 ++
 frontend/packages/ui/src/i18n/es.json         |   5 +-
 frontend/packages/ui/src/i18n/fr.json         |   5 +-
 frontend/packages/ui/src/i18n/pt.json         |   5 +-
 poetry.lock                                   |  16 +--
 pyproject.toml                                |   9 +-
 17 files changed, 676 insertions(+), 17 deletions(-)
 create mode 100644 frontend/apps/web/src/pages/detail/ChangeForm.test.tsx
 create mode 100644 frontend/apps/web/src/pages/detail/ChangeForm.tsx
 create mode 100644 frontend/apps/web/src/pages/detail/LegacyIframe.tsx
 create mode 100644 frontend/apps/web/src/pages/detail/adaptFormSpec.test.ts
 create mode 100644 frontend/apps/web/src/pages/detail/adaptFormSpec.ts
 create mode 100644 frontend/packages/data/src/form-spec-context.tsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cdcf783..a83fad4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.9.0] — 2026-06-01
+
+### Added
+
+- **Change-form parity via the rest-api form-spec endpoint (#659).** The
+  change form is now driven by `GET <app>/<model>/<pk>/form-spec/`
+  (django-admin-rest-api 1.4.0+, #59) instead of discovering fields
+  client-side from the model serializer. The SPA now honours the
+  **ModelAdmin layer**: request-aware `get_form(request, obj)` /
+  `get_fieldsets(request, obj)` / `get_readonly_fields(request, obj)`,
+  `formfield_overrides`, custom `Form` classes, and the admin relation
+  widgets — resolved server-side and mapped through the closed
+  `widget.kind` enum. The original change-form querystring is forwarded,
+  so a `get_form` that swaps the `Form` on `?variant=…` renders the same
+  fields the legacy `/admin/` does. When the backend can't render the
+  form from JSON (a `change_form_template` override → `renderer:
+  "legacy-iframe"`), the SPA embeds the legacy admin page in an iframe
+  inside the SPA shell instead of silently dropping the customisation
+  (closes part of #624). A spec-fetch failure (older backend) degrades
+  gracefully to the previous detail-payload-driven form. New API client
+  method `formSpec()` + `useFormSpec` hook; the existing `FieldInput`
+  renders the adapted fields unchanged (one control set, no drift).
+
 ### Changed
 
 - **Split DetailPage/ListPage into focused modules (no behavior change)
diff --git a/README.md b/README.md
index ffca9aa..1add217 100644
--- a/README.md
+++ b/README.md
@@ -646,7 +646,8 @@ issues link the work to close each gap.
 
 | Stock-Django hook | SPA behaviour | Tracked |
 |---|---|---|
-| `change_form_template` / `change_list_template` / `add_form_template` / `change_password_template` / `object_history_template` overrides | Silently ignored — the SPA renders entirely from the JSON wire. | [#624](https://github.com/MartinCastroAlvarez/django-admin-react/issues/624) |
+| `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_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 invisible — the SPA picks its own control from the field's `type`. No React-side widget-registration API yet. | [#625](https://github.com/MartinCastroAlvarez/django-admin-react/issues/625) |
 | `raw_id_fields` | Falls back to the autocomplete picker (same as `autocomplete_fields`). Defeats the purpose for FKs with 10M+ rows where autocomplete `get_search_results` is too expensive. | [#626](https://github.com/MartinCastroAlvarez/django-admin-react/issues/626) |
 | `radio_fields = {"status": admin.HORIZONTAL}` | Renders a `<select>` (default choice control) instead of inline radio buttons. | [#626](https://github.com/MartinCastroAlvarez/django-admin-react/issues/626) |
diff --git a/frontend/apps/web/src/pages/DetailPage.tsx b/frontend/apps/web/src/pages/DetailPage.tsx
index fe411d0..a62d9a7 100644
--- a/frontend/apps/web/src/pages/DetailPage.tsx
+++ b/frontend/apps/web/src/pages/DetailPage.tsx
@@ -36,9 +36,9 @@ import { useModelMeta } from '../useModelMeta';
 import { toastMessages, useToast } from '../toast';
 import { followActionRedirect } from '../action-redirect';
 import { carryPreservedFilters, listPathWithPreservedFilters } from '../changelistFilters';
+import { ChangeForm } from './detail/ChangeForm';
 import { CustomViewsMenu } from './detail/CustomViewsMenu';
 import { DeleteButton } from './detail/DeleteButton';
-import { EditForm } from './detail/EditForm';
 import { FieldsetSection } from './detail/FieldsetSection';
 import { InlineSection } from './detail/InlineSection';
 import { ObjectActionButton } from './detail/ObjectActionButton';
@@ -242,8 +242,19 @@ export function DetailPage({
       </header>
 
       {editing ? (
-        <EditForm
+        <ChangeForm
           data={data}
+          appLabel={appLabel}
+          modelName={modelName}
+          pk={pk}
+          // Forward the original change-form querystring so a request-aware
+          // ModelAdmin.get_form (e.g. one branching on ?variant=…) resolves
+          // the matching form (#659). Strip the SPA-only `edit=1` flag.
+          query={(() => {
+            const sp = new URLSearchParams(searchParams);
+            sp.delete('edit');
+            return sp.toString();
+          })()}
           onCancel={() => setEditing(false)}
           onSave={async (payload, action) => {
             // "Save as new" creates a fresh object from the current
diff --git a/frontend/apps/web/src/pages/detail/ChangeForm.test.tsx b/frontend/apps/web/src/pages/detail/ChangeForm.test.tsx
new file mode 100644
index 0000000..77725c2
--- /dev/null
+++ b/frontend/apps/web/src/pages/detail/ChangeForm.test.tsx
@@ -0,0 +1,130 @@
+import '@testing-library/jest-dom/vitest';
+
+import { render, screen } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { DetailResponse, FormSpecPayload } from '@dar/data';
+
+// 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: () => ({}),
+    useFormSpec: () => specState,
+  };
+});
+
+// Import AFTER the mock so ChangeForm picks up the mocked hooks.
+const { ChangeForm } = await import('./ChangeForm');
+
+function detail(): DetailResponse {
+  return {
+    app_label: 'auth',
+    model_name: 'group',
+    pk: 1,
+    label: 'editors',
+    permissions: { view: true, add: true, change: true, delete: true },
+    fieldsets: [{ title: null, fields: [] }],
+    fields: {},
+    inlines: [],
+    save_options: { show_save: true },
+  } as unknown as DetailResponse;
+}
+
+function renderChangeForm() {
+  return render(
+    <ChangeForm
+      data={detail()}
+      appLabel="auth"
+      modelName="group"
+      pk="1"
+      query=""
+      onCancel={() => {}}
+      onSave={async () => {}}
+    />,
+  );
+}
+
+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', () => {
+    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/');
+  });
+
+  it('renders the form-spec fields (request-aware get_form / fieldsets) via EditForm', () => {
+    specState = {
+      data: {
+        renderer: 'form-spec',
+        fieldsets: [{ title: 'Identity', fields: ['name'], classes: ['collapse'] }],
+        fields: {
+          name: {
+            label: 'Name',
+            help_text: '',
+            required: true,
+            readonly: false,
+            type: 'string',
+            widget: { kind: 'text', attrs: { maxlength: 150 } },
+            initial: 'editors',
+            errors: [],
+          },
+        },
+        variant: 'myapp.forms.GroupForm',
+      },
+      loading: false,
+      error: null,
+    };
+    renderChangeForm();
+    const input = screen.getByLabelText('Name', { exact: false }) as HTMLInputElement;
+    expect(input).toBeInTheDocument();
+    expect(input.value).toBe('editors');
+    expect(input).toHaveAttribute('maxlength', '150');
+  });
+
+  it('falls back to a default input + note for an unregistered custom widget', () => {
+    specState = {
+      data: {
+        renderer: 'form-spec',
+        fieldsets: [{ title: null, fields: ['bio'] }],
+        fields: {
+          bio: {
+            label: 'Bio',
+            help_text: '',
+            required: false,
+            readonly: false,
+            type: 'text',
+            widget: { kind: 'custom', attrs: {}, widget_class: 'mypkg.widgets.Markdown' },
+            initial: '',
+            errors: [],
+          },
+        },
+        variant: 'x',
+      },
+      loading: false,
+      error: null,
+    };
+    renderChangeForm();
+    expect(screen.getByText(/is not registered/i)).toBeInTheDocument();
+    expect(screen.getByText('mypkg.widgets.Markdown')).toBeInTheDocument();
+  });
+
+  it('falls back to the detail-driven form when the spec errors (older backend)', () => {
+    specState = { data: null, loading: false, error: new Error('404') };
+    // Should not throw; renders the EditForm shell (a <form> with the Save button).
+    renderChangeForm();
+    expect(screen.getByRole('button', { name: /save/i })).toBeInTheDocument();
+  });
+});
diff --git a/frontend/apps/web/src/pages/detail/ChangeForm.tsx b/frontend/apps/web/src/pages/detail/ChangeForm.tsx
new file mode 100644
index 0000000..051e75f
--- /dev/null
+++ b/frontend/apps/web/src/pages/detail/ChangeForm.tsx
@@ -0,0 +1,77 @@
+// ChangeForm — the form-spec-driven change form (#659).
+//
+// 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"`);
+//   - 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
+//     from the model serializer.
+//
+// If the spec can't be fetched (an older backend without the endpoint, a
+// transient error), we fall back to the detail-payload-driven EditForm so
+// editing still works — graceful degradation, never a broken page.
+
+import {
+  type DetailResponse,
+  useApiClient,
+  useFormSpec,
+} from '@dar/data';
+
+import { RecordSkeleton } from '../../components/RecordSkeleton';
+import { detailFromFormSpec } from './adaptFormSpec';
+import { EditForm, type SaveAction } from './EditForm';
+import { LegacyIframe } from './LegacyIframe';
+
+export interface ChangeFormProps {
+  data: DetailResponse;
+  appLabel: string;
+  modelName: string;
+  pk: string;
+  /** Original change-form querystring (forwarded for request-aware get_form). */
+  query?: string;
+  onCancel: () => void;
+  onSave: (payload: import('@dar/data').UpdatePayload, action: SaveAction) => Promise<void>;
+}
+
+export function ChangeForm({
+  data,
+  appLabel,
+  modelName,
+  pk,
+  query,
+  onCancel,
+  onSave,
+}: ChangeFormProps) {
+  const client = useApiClient();
+  const { data: spec, loading, error } = useFormSpec({
+    client,
+    appLabel,
+    modelName,
+    pk,
+    // `query` is always a string from the caller (URLSearchParams.toString());
+    // default to '' so the optional prop is never assigned `undefined`
+    // (exactOptionalPropertyTypes).
+    query: query ?? '',
+  });
+
+  // First load with nothing cached → skeleton. (Background refresh is off
+  // for the spec, so this only shows on the very first edit-mode entry.)
+  if (loading && !spec) return <RecordSkeleton />;
+
+  // Spec unavailable (older backend / transient error) → fall back to the
+  // detail-driven form so the operator can still edit.
+  if (error && !spec) {
+    return <EditForm data={data} onCancel={onCancel} onSave={onSave} />;
+  }
+  if (!spec) return <EditForm data={data} onCancel={onCancel} onSave={onSave} />;
+
+  if (spec.renderer === 'legacy-iframe') {
+    return <LegacyIframe url={spec.legacy_url} onCancel={onCancel} />;
+  }
+
+  return (
+    <EditForm data={detailFromFormSpec(data, spec)} onCancel={onCancel} onSave={onSave} />
+  );
+}
diff --git a/frontend/apps/web/src/pages/detail/LegacyIframe.tsx b/frontend/apps/web/src/pages/detail/LegacyIframe.tsx
new file mode 100644
index 0000000..308b947
--- /dev/null
+++ b/frontend/apps/web/src/pages/detail/LegacyIframe.tsx
@@ -0,0 +1,50 @@
+// 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.
+
+import { ExternalLink } from 'lucide-react';
+
+import { Button, Card, t } from '@dar/ui';
+
+export interface LegacyIframeProps {
+  url: string;
+  onCancel: () => void;
+}
+
+export function LegacyIframe({ url, onCancel }: LegacyIframeProps) {
+  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">
+            <a
+              href={url}
+              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>
+            <Button type="button" variant="ghost" onClick={onCancel}>
+              {t('Cancel')}
+            </Button>
+          </div>
+        </div>
+        <iframe
+          src={url}
+          title={t('Legacy admin form')}
+          className="h-[70vh] w-full rounded border border-gray-200 bg-white"
+        />
+      </div>
+    </Card>
+  );
+}
diff --git a/frontend/apps/web/src/pages/detail/adaptFormSpec.test.ts b/frontend/apps/web/src/pages/detail/adaptFormSpec.test.ts
new file mode 100644
index 0000000..7fb2586
--- /dev/null
+++ b/frontend/apps/web/src/pages/detail/adaptFormSpec.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+import type { DetailResponse, FormSpecField, FormSpecResponse } from '@dar/data';
+
+import { detailFromFormSpec, formSpecFieldToDescriptor } from './adaptFormSpec';
+
+function fsField(overrides: Partial<FormSpecField> = {}): FormSpecField {
+  return {
+    label: 'Name',
+    help_text: '',
+    required: true,
+    readonly: false,
+    type: 'string',
+    widget: { kind: 'text', attrs: {} },
+    initial: '',
+    errors: [],
+    ...overrides,
+  };
+}
+
+describe('formSpecFieldToDescriptor (#659)', () => {
+  it('maps the closed widget.kind enum onto the existing WidgetHint controls', () => {
+    expect(formSpecFieldToDescriptor(fsField({ widget: { kind: 'password', attrs: {} } })).widget).toBe('password');
+    expect(formSpecFieldToDescriptor(fsField({ widget: { kind: 'radio', attrs: {} } })).widget).toBe('radio');
+    expect(formSpecFieldToDescriptor(fsField({ widget: { kind: 'raw-id', attrs: {} } })).widget).toBe('raw_id');
+    expect(formSpecFieldToDescriptor(fsField({ widget: { kind: 'shuttle', attrs: {} } })).widget).toBe('shuttle_h');
+  });
+
+  it('leaves widget undefined for kinds the FieldType already implies (select/date/autocomplete/…)', () => {
+    expect(formSpecFieldToDescriptor(fsField({ widget: { kind: 'select', attrs: {} } })).widget).toBeUndefined();
+    expect(formSpecFieldToDescriptor(fsField({ widget: { kind: 'date', attrs: {} } })).widget).toBeUndefined();
+    expect(
+      formSpecFieldToDescriptor(fsField({ widget: { kind: 'autocomplete', attrs: {} } })).widget,
+    ).toBeUndefined();
+  });
+
+  it('passes the custom widget_class through so the SPA can dispatch a registered renderer', () => {
+    const d = formSpecFieldToDescriptor(
+      fsField({
+        widget: { kind: 'custom', attrs: {}, widget_class: 'mypkg.widgets.MarkdownEditor' },
+      }),
+    );
+    expect(d.widget).toBe('custom');
+    expect(d.widget_class).toBe('mypkg.widgets.MarkdownEditor');
+  });
+
+  it('carries readonly through and uses `initial` as the descriptor value', () => {
+    const d = formSpecFieldToDescriptor(fsField({ readonly: true, initial: 'editors' }));
+    expect(d.readonly).toBe(true);
+    expect(d.value).toBe('editors');
+  });
+
+  it('derives max_length from widget.attrs.maxlength when not set explicitly', () => {
+    const d = formSpecFieldToDescriptor(fsField({ widget: { kind: 'text', attrs: { maxlength: 150 } } }));
+    expect(d.max_length).toBe(150);
+  });
+
+  it('preserves the FK initial envelope shape ({id,label}) so EditForm derives the pk', () => {
+    const d = formSpecFieldToDescriptor(
+      fsField({ type: 'foreignkey', initial: { id: 7, label: 'Acme' }, to: { app_label: 'a', model_name: 'b' } }),
+    );
+    expect(d.value).toEqual({ id: 7, label: 'Acme' });
+    expect(d.to).toEqual({ app_label: 'a', model_name: 'b' });
+  });
+});
+
+describe('detailFromFormSpec (#659)', () => {
+  it('sources fields + fieldsets from the spec but keeps inlines / save_options / label from the detail', () => {
+    const detail = {
+      app_label: 'auth',
+      model_name: 'group',
+      pk: 1,
+      label: 'editors',
+      permissions: { view: true, add: true, change: true, delete: true },
+      fieldsets: [{ title: null, fields: ['legacy'] }],
+      fields: { legacy: { type: 'string', label: 'Legacy', required: false, readonly: false, help_text: '', value: 'x' } },
+      inlines: [{ name: 'memberships' }],
+      save_options: { show_save: true },
+    } as unknown as DetailResponse;
+    const spec: FormSpecResponse = {
+      renderer: 'form-spec',
+      fieldsets: [{ title: 'Identity', fields: ['name'], classes: ['collapse'] }],
+      fields: { name: fsField() },
+      variant: 'myapp.forms.GroupForm',
+    };
+
+    const merged = detailFromFormSpec(detail, spec);
+    // fields + fieldsets come from the spec…
+    expect(Object.keys(merged.fields)).toEqual(['name']);
+    expect(merged.fieldsets[0]?.classes).toEqual(['collapse']);
+    // …everything else stays from the detail payload.
+    expect(merged.inlines).toEqual([{ name: 'memberships' }]);
+    expect(merged.save_options).toEqual({ show_save: true });
+    expect(merged.label).toBe('editors');
+  });
+});
diff --git a/frontend/apps/web/src/pages/detail/adaptFormSpec.ts b/frontend/apps/web/src/pages/detail/adaptFormSpec.ts
new file mode 100644
index 0000000..e4dcdfd
--- /dev/null
+++ b/frontend/apps/web/src/pages/detail/adaptFormSpec.ts
@@ -0,0 +1,86 @@
+// adaptFormSpec — map a form-spec payload onto the detail-payload shape so
+// the existing EditForm / FieldInput render it unchanged (#659).
+//
+// The form-spec endpoint (rest-api 1.4.0+, #59) is the source of truth for
+// the change/add form: it resolves the ModelAdmin layer (request-aware
+// `get_form` / `get_fieldsets` / `get_readonly_fields`, `formfield_overrides`,
+// custom Form classes) the model serializer can't see. Rather than rebuild
+// every control, we translate each `FormSpecField` into the `FieldDescriptor`
+// the battle-tested FieldInput already renders — the backend reuses the
+// detail serializer for `initial`, so the value shapes line up exactly.
+
+import type {
+  DetailResponse,
+  FieldDescriptor,
+  FormSpecField,
+  FormSpecResponse,
+  WidgetKind,
+  WidgetHint,
+} from '@dar/data';
+
+// The closed `widget.kind` enum → the SPA's existing `WidgetHint` controls.
+// Kinds with no dedicated hint (select, checkbox, date, file, autocomplete,
+// …) return undefined: FieldInput then renders the control implied by
+// `FieldType`, which already covers them (a select for `choice`, an
+// AutocompleteInput for an FK with a `to` target, etc.).
+const KIND_TO_HINT: Partial<Record<WidgetKind, WidgetHint>> = {
+  password: 'password',
+  radio: 'radio',
+  'raw-id': 'raw_id',
+  // form-spec collapses filter_horizontal/vertical to a single `shuttle`
+  // kind; orientation isn't carried, so default to horizontal (the
+  // ShuttleSelect supports both and the difference is purely visual).
+  shuttle: 'shuttle_h',
+  custom: 'custom',
+};
+
+function maxLengthFrom(field: FormSpecField): number | undefined {
+  if (typeof field.max_length === 'number') return field.max_length;
+  const attr = field.widget.attrs['maxlength'];
+  return typeof attr === 'number' ? attr : undefined;
+}
+
+/** Translate one form-spec field into a detail-style FieldDescriptor.
+ *
+ * Optional keys are added only when present — the project's
+ * `exactOptionalPropertyTypes` forbids assigning `undefined` to an
+ * optional prop. */
+export function formSpecFieldToDescriptor(field: FormSpecField): FieldDescriptor {
+  const descriptor: FieldDescriptor = {
+    type: field.type,
+    label: field.label,
+    required: field.required,
+    readonly: field.readonly,
+    help_text: field.help_text,
+    // `initial` reuses the detail serializer's value shape verbatim
+    // (FK {id,label}, M2M [{id,label}], redacted password → null), so
+    // EditForm's `initialValueFor` derives the write value unchanged.
+    value: field.initial,
+  };
+  if (field.choices) descriptor.choices = field.choices;
+  if (field.to) descriptor.to = field.to;
+  const maxLength = maxLengthFrom(field);
+  if (maxLength !== undefined) descriptor.max_length = maxLength;
+  if (field.decimal_places !== undefined) descriptor.decimal_places = field.decimal_places;
+  const hint = KIND_TO_HINT[field.widget.kind];
+  if (hint !== undefined) descriptor.widget = hint;
+  if (field.widget.widget_class !== undefined) descriptor.widget_class = field.widget.widget_class;
+  return descriptor;
+}
+
+/**
+ * Build a DetailResponse-shaped object whose `fields` + `fieldsets` come
+ * from the form spec while inlines / save_options / permissions / label
+ * stay from the live detail payload. Lets the existing EditForm render the
+ * ModelAdmin-resolved form with no other change.
+ */
+export function detailFromFormSpec(
+  detail: DetailResponse,
+  spec: FormSpecResponse,
+): DetailResponse {
+  const fields: Record<string, FieldDescriptor> = {};
+  for (const [name, field] of Object.entries(spec.fields)) {
+    fields[name] = formSpecFieldToDescriptor(field);
+  }
+  return { ...detail, fields, fieldsets: spec.fieldsets };
+}
diff --git a/frontend/packages/api/src/client.ts b/frontend/packages/api/src/client.ts
index a1039bd..3aa46dc 100644
--- a/frontend/packages/api/src/client.ts
+++ b/frontend/packages/api/src/client.ts
@@ -15,6 +15,7 @@ import type {
   DeletePreviewResponse,
   DetailResponse,
   FieldErrorEnvelope,
+  FormSpecPayload,
   HistoryResponse,
   ListResponse,
   LoginResponse,
@@ -259,6 +260,28 @@ export class ApiClient {
     return this.request<AddFormResponse>('GET', `${appLabel}/${modelName}/add/`);
   }
 
+  /**
+   * The ModelAdmin-resolved form spec (rest-api 1.4.0+, #59): request-aware
+   * `get_form` / `get_fieldsets` / `get_readonly_fields` with a closed
+   * `widget.kind` per field, or a `legacy-iframe` pointer. Pass `pk` for
+   * the change form, omit it for the add form. `query` is the original
+   * change-form querystring (forwarded so a request-aware `get_form` that
+   * branches on `?variant=…` resolves the matching form).
+   */
+  formSpec(
+    appLabel: string,
+    modelName: string,
+    pk?: string | number,
+    query?: string,
+  ): Promise<FormSpecPayload> {
+    const base =
+      pk === undefined || pk === null || pk === ''
+        ? `${appLabel}/${modelName}/add/form-spec/`
+        : `${appLabel}/${modelName}/${pk}/form-spec/`;
+    const qs = query ? (query.startsWith('?') ? query : `?${query}`) : '';
+    return this.request<FormSpecPayload>('GET', `${base}${qs}`);
+  }
+
   /** 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 73cb9f9..5e7c966 100644
--- a/frontend/packages/api/src/contract.ts
+++ b/frontend/packages/api/src/contract.ts
@@ -635,6 +635,101 @@ export interface AddFormResponse {
   prepopulated_fields?: Record<string, string[]>;
 }
 
+/**
+ * Closed widget-kind enum from the form-spec endpoint (rest-api 1.4.0+,
+ * `#59`). Derived from each field's *resolved* Django form widget — every
+ * stdlib + admin widget maps to one of these, with `custom` for a widget
+ * whose class lives outside `django.*`. This is *how* to render a field
+ * (the control); `FieldType` is *what* the value is. The SPA maps the
+ * relevant kinds onto its existing `WidgetHint` controls; the rest fall
+ * back to the control implied by `FieldType`.
+ */
+export type WidgetKind =
+  | 'text'
+  | 'textarea'
+  | 'number'
+  | 'email'
+  | 'url'
+  | 'password'
+  | 'hidden'
+  | 'checkbox'
+  | 'checkbox-multiple'
+  | 'select'
+  | 'select-multiple'
+  | 'radio'
+  | 'date'
+  | 'datetime'
+  | 'time'
+  | 'split-datetime'
+  | 'select-date'
+  | 'file'
+  | 'autocomplete'
+  | 'autocomplete-multiple'
+  | 'raw-id'
+  | 'shuttle'
+  | 'custom';
+
+/**
+ * The resolved-widget block on a form-spec field. `kind` is the closed
+ * enum above; `attrs` carries the widget's HTML attrs (so `formfield_overrides`
+ * is visible — a forced `Textarea`'s `{rows: 10}`, a `CharField`'s
+ * `{maxlength: 150}`). `widget_class` (+ `template_name`) is present when
+ * the widget class lives outside `django.*`, so a consumer-registered
+ * renderer (`registerFieldWidget`, #625) can dispatch on it.
+ */
+export interface WidgetBlock {
+  kind: WidgetKind;
+  attrs: Record<string, string | number | boolean>;
+  widget_class?: string;
+  template_name?: string;
+}
+
+/**
+ * One field in a form-spec payload. Same value vocabulary as
+ * `FieldDescriptor` (the backend reuses the detail serializer, so `initial`
+ * has the identical shape `FieldDescriptor.value` does — FK `{id,label}`,
+ * M2M `[{id,label}]`, a redacted password `null`), plus the closed
+ * `widget` block and per-field `errors`.
+ */
+export interface FormSpecField {
+  label: string;
+  help_text: string;
+  required: boolean;
+  readonly: boolean;
+  type: FieldType;
+  widget: WidgetBlock;
+  initial: FieldValue;
+  errors: string[];
+  choices?: FieldChoice[];
+  to?: { app_label: string; model_name: string };
+  max_length?: number;
+  decimal_places?: number;
+}
+
+/**
+ * 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"`).
+ */
+export interface FormSpecResponse {
+  renderer: 'form-spec';
+  fieldsets: FieldsetDescriptor[];
+  fields: Record<string, FormSpecField>;
+  /** Dotted path of the resolved `Form` class — changes when a
+   *  request-aware `get_form` switched form by querystring/user. */
+  variant: string;
+}
+
+/** Escape hatch: embed the legacy admin change/add page in an iframe. */
+export interface LegacyIframeResponse {
+  renderer: 'legacy-iframe';
+  legacy_url: string;
+}
+
+export type FormSpecPayload = FormSpecResponse | LegacyIframeResponse;
+
 /**
  * One object-history entry (Django LogEntry) — `GET <app>/<model>/<pk>/history/`.
  * `action` is `addition` / `change` / `deletion` / `unknown`;
diff --git a/frontend/packages/data/src/form-spec-context.tsx b/frontend/packages/data/src/form-spec-context.tsx
new file mode 100644
index 0000000..0882e37
--- /dev/null
+++ b/frontend/packages/data/src/form-spec-context.tsx
@@ -0,0 +1,46 @@
+// useFormSpec — fetch the ModelAdmin-resolved form spec for the change /
+// add view (rest-api 1.4.0+, #59).
+//
+// Thin wrapper around @dar/api's formSpec call + the shared SWR cache.
+// Page packages MUST consume this hook (never @dar/api directly — see
+// CLAUDE.md §7). The cache key includes the querystring so a request-aware
+// `get_form` swap (`?variant=…`) doesn't read a stale cached spec.
+
+import { useMemo } from 'react';
+
+import type { ApiClient, FormSpecPayload } from '@dar/api';
+
+import { type SwrState, useSwrCache } from './swr-cache';
+
+export interface UseFormSpecParams {
+  client: ApiClient;
+  appLabel: string;
+  modelName: string;
+  /** Omit (or empty) for the add-view form. */
+  pk?: string | number;
+  /** Original change-form querystring, forwarded for request-aware get_form. */
+  query?: string;
+}
+
+export type FormSpecState = SwrState<FormSpecPayload>;
+
+function cacheKeyFor(p: UseFormSpecParams): string {
+  return `dar:formspec:v1:${p.appLabel}|${p.modelName}|${p.pk ?? 'add'}|${p.query ?? ''}`;
+}
+
+export function useFormSpec(params: UseFormSpecParams): FormSpecState {
+  const cacheKey = cacheKeyFor(params);
+  const fetcher = useMemo(
+    () => () =>
+      params.client.formSpec(params.appLabel, params.modelName, params.pk, params.query),
+    [params.client, params.appLabel, params.modelName, params.pk, params.query],
+  );
+  return useSwrCache<FormSpecPayload>({
+    cacheKey,
+    fetcher,
+    deps: [cacheKey],
+    // No background poll: the form spec is read once when the edit form
+    // mounts. Re-validating mid-edit could swap the field set under the
+    // operator. The detail hook keeps the read view live separately.
+  });
+}
diff --git a/frontend/packages/data/src/index.ts b/frontend/packages/data/src/index.ts
index 062ab9d..af2b983 100644
--- a/frontend/packages/data/src/index.ts
+++ b/frontend/packages/data/src/index.ts
@@ -34,6 +34,13 @@ export type {
   FieldsetDescriptor,
   FilterDescriptor,
   FilterOption,
+  FormSpecField,
+  FormSpecPayload,
+  FormSpecResponse,
+  LegacyIframeResponse,
+  WidgetBlock,
+  WidgetHint,
+  WidgetKind,
   HistoryEntry,
   HistoryResponse,
   ForeignKeyValue,
@@ -72,6 +79,8 @@ export type { RecentActionsState } from './recent-actions-context';
 
 export { useDetail } from './detail-context';
 export type { DetailState } from './detail-context';
+export { useFormSpec } from './form-spec-context';
+export type { FormSpecState, UseFormSpecParams } from './form-spec-context';
 
 export {
   createObject,
diff --git a/frontend/packages/ui/src/i18n/es.json b/frontend/packages/ui/src/i18n/es.json
index 41c351a..4d295e8 100644
--- a/frontend/packages/ui/src/i18n/es.json
+++ b/frontend/packages/ui/src/i18n/es.json
@@ -45,5 +45,8 @@
   "Action failed.": "La acción falló.",
   "The action could not be completed.": "No se pudo completar la acción.",
   "Couldn't load the list": "No se pudo cargar la lista",
-  "This page requires JavaScript.": "Esta página requiere JavaScript."
+  "This page requires JavaScript.": "Esta página requiere JavaScript.",
+  "This form is rendered by the legacy admin (custom change_form_template).": "Este formulario lo renderiza el admin clásico (change_form_template personalizado).",
+  "Open in new tab": "Abrir en una pestaña nueva",
+  "Legacy admin form": "Formulario del admin clásico"
 }
diff --git a/frontend/packages/ui/src/i18n/fr.json b/frontend/packages/ui/src/i18n/fr.json
index dfd50ca..3afd83d 100644
--- a/frontend/packages/ui/src/i18n/fr.json
+++ b/frontend/packages/ui/src/i18n/fr.json
@@ -45,5 +45,8 @@
   "Action failed.": "L'action a échoué.",
   "The action could not be completed.": "L'action n'a pas pu être effectuée.",
   "Couldn't load the list": "Impossible de charger la liste",
-  "This page requires JavaScript.": "Cette page nécessite JavaScript."
+  "This page requires JavaScript.": "Cette page nécessite JavaScript.",
+  "This form is rendered by the legacy admin (custom change_form_template).": "Ce formulaire est rendu par l’admin classique (change_form_template personnalisé).",
+  "Open in new tab": "Ouvrir dans un nouvel onglet",
+  "Legacy admin form": "Formulaire de l’admin classique"
 }
diff --git a/frontend/packages/ui/src/i18n/pt.json b/frontend/packages/ui/src/i18n/pt.json
index 97583b8..62fc02f 100644
--- a/frontend/packages/ui/src/i18n/pt.json
+++ b/frontend/packages/ui/src/i18n/pt.json
@@ -45,5 +45,8 @@
   "Action failed.": "A ação falhou.",
   "The action could not be completed.": "A ação não pôde ser concluída.",
   "Couldn't load the list": "Não foi possível carregar a lista",
-  "This page requires JavaScript.": "Esta página requer JavaScript."
+  "This page requires JavaScript.": "Esta página requer JavaScript.",
+  "This form is rendered by the legacy admin (custom change_form_template).": "Este formulário é renderizado pelo admin clássico (change_form_template personalizado).",
+  "Open in new tab": "Abrir em nova aba",
+  "Legacy admin form": "Formulário do admin clássico"
 }
diff --git a/poetry.lock b/poetry.lock
index 1263140..42601a6 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -471,31 +471,31 @@ bcrypt = ["bcrypt"]
 
 [[package]]
 name = "django-admin-mcp-api"
-version = "1.1.0"
+version = "1.2.0"
 description = "MCP (Model Context Protocol) adapter for django-admin-rest-api. A wire-protocol-only layer that lets agents reach the existing REST API — no new functionality, permissions, or validation."
 optional = false
 python-versions = "<4.0,>=3.10"
 groups = ["main"]
 files = [
-    {file = "django_admin_mcp_api-1.1.0-py3-none-any.whl", hash = "sha256:f1db825249e6b1b01d27380f4f5902febba723b6b79829f242c0f7bc9461414b"},
-    {file = "django_admin_mcp_api-1.1.0.tar.gz", hash = "sha256:a84b39400f2960385ef834a9e6087bda475259f2661dfc7680fd8ca337e04016"},
+    {file = "django_admin_mcp_api-1.2.0-py3-none-any.whl", hash = "sha256:2f94b1597c60944c4d9bf75432354c1dfd4a2a66f8ae71da46020974ee88e28e"},
+    {file = "django_admin_mcp_api-1.2.0.tar.gz", hash = "sha256:c2a82b19347ce3e2761411453ff2730a70f0e658124daa2ae504b5ffcbeb4938"},
 ]
 
 [package.dependencies]
 django = ">=4.2,<7.0"
-django-admin-rest-api = ">=1.1.0,<2.0.0"
+django-admin-rest-api = ">=1.4.0,<2.0.0"
 jsonschema = ">=4.0,<5.0"
 
 [[package]]
 name = "django-admin-rest-api"
-version = "1.3.0"
+version = "1.4.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.3.0-py3-none-any.whl", hash = "sha256:fb425b73833e6667f495c6620df903ec0670149ecc14cbe661a14d7af4e2b5b6"},
-    {file = "django_admin_rest_api-1.3.0.tar.gz", hash = "sha256:07f6c08de14d8aeee62685840da2841dc2d803c3cc2c14694cd42d24ea36fb47"},
+    {file = "django_admin_rest_api-1.4.0-py3-none-any.whl", hash = "sha256:66e9ed8536364b82e4eab139471d1115b2740233f31dacbd809e315caddd81fe"},
+    {file = "django_admin_rest_api-1.4.0.tar.gz", hash = "sha256:debead8b5d0effed517e178e3fc5546c444cdd3288fae6f691999253d313f917"},
 ]
 
 [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 = "c2210bc3ebd928924194ed2d653058b0897c26dcff5aa0d5f08373e6038b6910"
+content-hash = "578e1141e6c1cbf842ec8e9b6a8c2ce8ce10f6376bd9b27e50a7a588c1443a1c"
diff --git a/pyproject.toml b/pyproject.toml
index c0a8c1c..6c16cd0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-admin-react"
-version = "1.8.1"
+version = "1.9.0"
 description = "A drop-in React single-page admin for Django, driven entirely by ModelAdmin."
 authors = ["django-admin-react contributors"]
 license = "MIT"
@@ -52,7 +52,10 @@ django = ">=4.2,<7.0"
 # React SPA super-layer over `django-admin-rest-api`. The package's URLs
 # are included by `django_admin_react.urls`, and consumers add
 # `"django_admin_rest_api"` to `INSTALLED_APPS` alongside this package.
-django-admin-rest-api = "^1.3.0"
+# Floor raised to 1.4.0 in v1.9.0 (#659): the change form consumes the
+# `form-spec` endpoint that ships in rest-api 1.4.0 (#59). The SPA degrades
+# gracefully on an older backend, but the documented parity needs 1.4.0+.
+django-admin-rest-api = "^1.4.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.
@@ -61,7 +64,7 @@ django-admin-rest-api = "^1.3.0"
 # so a consumer on Django 4.2 actually gets a Django-4.2-compatible MCP
 # (the 1.0.x line pins ``django>=5.0``, which would refuse to install
 # alongside Django 4.2).
-django-admin-mcp-api = ">=1.1.0,<2.0.0"
+django-admin-mcp-api = ">=1.2.0,<2.0.0"
 
 [tool.poetry.group.dev.dependencies]
 # Dependabot #5: pytest's tmpdir handled symlinks unsafely