fix: report the document reference map from slot state

onChange was emitted at the end of each upload, which had two problems:

- it read `slots` from a closure captured before the await, so a slot
  finishing could emit a map missing another slot's reference
- it never fired when a pending scan later resolved, so the parent stayed
  on "scan_pending" after the scan had finished

The map is now derived from slot state and reported via an effect keyed on
its content, so progress ticks don't emit and scan transitions do.

Also guards the deliberately un-awaited scan poll against an unhandled
rejection.

Author: Fury03

__tests__/documents/DocumentUpload.test.jsx

@@ -423,9 +423,12 @@ describe("replace and remove", () => {
       `/api/educators/applications/documents/${SIGNED_TARGET.documentId}`
     );
 
-    // The referenced object now points at the new document.
-    const latest = onChange.mock.calls.at(-1)[0];
-    expect(latest[ID].documentId).toBe("doc_second");
+    // The referenced object now points at the new document. Waited for rather
+    // than read once: the filename renders as soon as validation starts, which
+    // is before the replacement upload has finalised.
+    await waitFor(() =>
+      expect(onChange.mock.calls.at(-1)[0][ID].documentId).toBe("doc_second")
+    );
   });
 
   it("remove deletes the document and clears the slot", async () => {
@@ -462,6 +465,109 @@ describe("replace and remove", () => {
 
 // ---------------------------------------------------------------------------
 
+describe("onChange reports the full reference map", () => {
+  const CERT = DOCUMENT_TYPES.TEACHING_CERTIFICATE;
+
+  const TWO_SLOTS = [
+    { ...SINGLE_SLOT[0] },
+    {
+      type: CERT,
+      label: "Teaching certificate",
+      description: "Ijazah or teaching licence.",
+      required: true,
+      allowCamera: false,
+    },
+  ];
+
+  /** Give each slot its own documentId so the map can be told apart. */
+  function mockPerSlot() {
+    axiosInstance.post.mockImplementation((url, body) => {
+      if (url.endsWith("/upload-url")) {
+        return Promise.resolve({
+          data: { ...SIGNED_TARGET, documentId: `doc_${body.documentType}` },
+        });
+      }
+      if (url.endsWith("/complete")) {
+        const documentId = url.split("/documents/")[1].split("/complete")[0];
+        return Promise.resolve({
+          data: {
+            documentId,
+            documentType: body.documentType,
+            status: "accepted",
+          },
+        });
+      }
+      return Promise.resolve({ data: {} });
+    });
+    axios.request.mockResolvedValue({ data: {}, status: 200 });
+  }
+
+  function dropInto(type, name) {
+    fireEvent.drop(screen.getByTestId(`dropzone-${type}`), {
+      dataTransfer: {
+        files: [makeFile(PDF_MAGIC, { name, type: "application/pdf" })],
+      },
+    });
+  }
+
+  it("keeps earlier slots when a later slot finishes", async () => {
+    mockPerSlot();
+    const onChange = vi.fn();
+
+    render(
+      <DocumentUpload
+        slots={TWO_SLOTS}
+        uploadOptions={{ pollIntervalMs: 5, maxPollAttempts: 5 }}
+        onChange={onChange}
+      />
+    );
+
+    dropInto(ID, "passport.pdf");
+    await waitFor(() =>
+      expect(screen.getByTestId(`document-slot-${ID}`)).toHaveAttribute(
+        "data-state",
+        "accepted"
+      )
+    );
+
+    dropInto(CERT, "ijazah.pdf");
+    await waitFor(() =>
+      expect(screen.getByTestId(`document-slot-${CERT}`)).toHaveAttribute(
+        "data-state",
+        "accepted"
+      )
+    );
+
+    // The second slot completing must not drop the first slot's reference.
+    const latest = onChange.mock.calls.at(-1)[0];
+    expect(Object.keys(latest).sort()).toEqual([CERT, ID].sort());
+    expect(latest[ID].documentId).toBe(`doc_${ID}`);
+    expect(latest[CERT].documentId).toBe(`doc_${CERT}`);
+  });
+
+  it("reports the status change when a pending scan resolves", async () => {
+    mockHappyPath({ finalStatus: "scan_pending", pollStatus: "accepted" });
+    const onChange = vi.fn();
+    renderUpload({ onChange });
+
+    dropInto(ID, "passport.pdf");
+
+    await waitFor(
+      () =>
+        expect(screen.getByTestId("slot-status")).toHaveAttribute(
+          "data-state",
+          "accepted"
+        ),
+      { timeout: 3000 }
+    );
+
+    // The parent must see the resolved status, not the stale scan_pending one.
+    expect(onChange.mock.calls.at(-1)[0][ID].status).toBe("accepted");
+  });
+});
+
+// ---------------------------------------------------------------------------
+
 describe("no public asset URL is ever produced or stored", () => {
   it("never surfaces a cloudinary or other public URL, and stores only an id", async () => {
     mockHappyPath({ finalStatus: "accepted" });
@@ -483,13 +589,17 @@ describe("no public asset URL is ever produced or stored", () => {
     );
 
     // The stored reference carries an opaque id and a status — no URL field.
-    const reference = onChange.mock.calls.at(-1)[0][ID];
-    expect(reference).toEqual(
-      expect.objectContaining({
-        documentId: "doc_abc123",
-        status: "accepted",
-      })
+    // Waited for: the reference map is reported from an effect, which flushes
+    // a tick after the slot's DOM state settles.
+    await waitFor(() =>
+      expect(onChange.mock.calls.at(-1)?.[0]?.[ID]).toEqual(
+        expect.objectContaining({
+          documentId: "doc_abc123",
+          status: "accepted",
+        })
+      )
     );
+    const reference = onChange.mock.calls.at(-1)[0][ID];
     expect(JSON.stringify(reference)).not.toMatch(/https?:\/\//);
     expect(reference.secure_url).toBeUndefined();
     expect(reference.url).toBeUndefined();

components/organisms/educator-onboarding/DocumentUpload.jsx

@@ -18,7 +18,14 @@
  * - No component in this tree ever receives or renders a public asset URL.
  */
 
-import { useCallback, useId, useRef, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import {
   AlertCircle,
   Camera,
@@ -373,35 +380,49 @@ export default function DocumentUpload({
     useDocumentUpload(uploadOptions);
 
   const handleSelectFile = useCallback(
-    async (documentType, file) => {
+    (documentType, file) => {
       const existing = slots[documentType]?.reference?.documentId;
       const run = existing ? replaceDocument : uploadDocument;
-
-      const result = await run(documentType, file);
-
-      if (result?.ok && onChange) {
-        onChange({
-          ...collectReferences(slots),
-          [documentType]: result.reference,
-        });
-      }
-      return result;
+      return run(documentType, file);
     },
-    [onChange, replaceDocument, slots, uploadDocument]
+    [replaceDocument, slots, uploadDocument]
   );
 
   const handleRemove = useCallback(
-    async (documentType) => {
-      const result = await removeDocument(documentType);
-      if (result?.ok && onChange) {
-        const next = collectReferences(slots);
-        delete next[documentType];
-        onChange(next);
-      }
-    },
-    [onChange, removeDocument, slots]
+    (documentType) => removeDocument(documentType),
+    [removeDocument]
   );
 
+  // ── Report the reference map upward ──────────────────────────────────────
+  // Derived from slot state rather than emitted at the end of each upload.
+  // Emitting per-upload read `slots` from a closure captured before the await,
+  // and never fired at all when a pending scan later resolved — so the parent
+  // could hold a reference map that was missing a slot, or stuck on
+  // "scan_pending" after the scan had finished.
+  const references = useMemo(() => collectReferences(slots), [slots]);
+
+  // Compare by content: slot state also changes on every progress tick, and
+  // those must not be reported as reference changes.
+  const referencesKey = JSON.stringify(references);
+
+  // Held in a ref so a parent passing an inline arrow doesn't re-fire this.
+  const onChangeRef = useRef(onChange);
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  }, [onChange]);
+
+  const hasReportedRef = useRef(false);
+  useEffect(() => {
+    // Skip the initial empty map so mounting doesn't look like a change.
+    if (!hasReportedRef.current) {
+      hasReportedRef.current = true;
+      if (referencesKey === "{}") return;
+    }
+    onChangeRef.current?.(references);
+    // `references` is recreated per render; `referencesKey` is the real trigger.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [referencesKey]);
+
   const requiredTypes = definitions
     .filter((d) => d.required)
     .map((d) => d.type);

hooks/useDocumentUpload.js

@@ -266,7 +266,10 @@ export function useDocumentUpload(options = {}) {
         });
 
         if (!isTerminalStatus(reference.status)) {
-          pollScanStatus(documentType, reference.documentId);
+          // Deliberately not awaited — the upload is done and the caller
+          // shouldn't block on the scan. Errors are swallowed inside the poll
+          // loop; the catch here only guards against an unhandled rejection.
+          pollScanStatus(documentType, reference.documentId).catch(() => {});
         }
 
         return { ok: true, reference };