From d026f2b2afc63f9c265aea336ddfe76ecbc113b0 Mon Sep 17 00:00:00 2001
From: bambuska-man <ybva280@gmail.com>
Date: Sun, 30 Aug 2026 11:56:56 +0000
Subject: [PATCH] feat: swap prefill, repeat swap, solver draft, semantic
 tables (#276 #277 #278 #279)

- #279: extend SwapCard with initialChain/initialSrcToken/initialDstToken props
  with graceful fallback; homepage reads ?srcChain/srcToken/amount/dstToken via
  useSearchParams (Suspense-wrapped) and passes them as prefill values
- #276: add Swap again link to my-intents rows building the prefill URL;
  destination address intentionally omitted; pagination UI added
- #277: new useLocalStorageDraft hook (debounced write, 24h TTL, wallet-address
  guard); wired into SolvePageClient to persist address/bond across reloads,
  cleared on success and reset
- #278: convert ExplorePageClient and my-intents intent lists from div stacks
  to native table/thead/tbody/tr/th/td markup with real column headers so
  screen readers announce column context and table navigation mode works

Also fix pre-existing syntax corruptions in explore/page.tsx, solve/page.tsx
and solve/[address]/page.test.tsx (stray JSX fragments and missing closing brace)

Closes #276
Closes #277
Closes #278
Closes #279
---
 src/app/explore/ExplorePageClient.tsx |  75 +++++++++-----
 src/app/explore/page.tsx              |   9 +-
 src/app/my-intents/page.tsx           | 137 +++++++++++++++++++++-----
 src/app/page.tsx                      |  25 ++++-
 src/app/solve/SolvePageClient.tsx     |  45 ++++++++-
 src/app/solve/[address]/page.test.tsx |   2 +-
 src/app/solve/page.tsx                |   7 +-
 src/components/SwapCard.tsx           |  37 ++++++-
 src/hooks/useLocalStorageDraft.ts     | 122 +++++++++++++++++++++++
 9 files changed, 392 insertions(+), 67 deletions(-)
 create mode 100644 src/hooks/useLocalStorageDraft.ts

diff --git a/src/app/explore/ExplorePageClient.tsx b/src/app/explore/ExplorePageClient.tsx
index 10af3f1..fd6f982 100644
--- a/src/app/explore/ExplorePageClient.tsx
+++ b/src/app/explore/ExplorePageClient.tsx
@@ -132,28 +132,59 @@ export default function ExplorePageClient() {
           </div>
         ) : (
           <>
-            <div className="space-y-2">
-              {paginated.map((item) => (
-                <Link
-                  key={item.id}
-                  href={`/explore/${item.id}`}
-                  className="flex items-center gap-4 p-4 bg-vx-surface/40 rounded-lg border border-vx-line
-                             hover:border-vx-border transition-colors"
-                >
-                  <div className="flex-1 min-w-0">
-                    <div className="text-sm font-medium text-vx-text truncate">
-                      {item.srcAmount} {item.srcToken} → {item.dstToken}
-                    </div>
-                    <div className="text-xs text-vx-muted capitalize">
-                      {item.srcChain} · via {item.solver}
-                    </div>
-                  </div>
-                  <IntentStatusBadge status={item.status} />
-                  <span className="text-xs text-vx-muted num flex-shrink-0 w-16 text-right">
-                    {timeAgo(item.createdAt)}
-                  </span>
-                </Link>
-              ))}
+            {/*
+              Native <table> so screen readers announce column headers, row/column
+              counts, and allow table-navigation mode.
+              Visual layout is preserved via display:block tricks on narrow viewports
+              if needed, but the semantic structure stays table-based.
+            */}
+            <div className="overflow-x-auto rounded-lg border border-vx-line">
+              <table className="w-full border-collapse">
+                <thead>
+                  <tr className="bg-vx-surface/50 border-b border-vx-line">
+                    <th scope="col" className="px-4 py-3 text-left text-xs font-semibold text-vx-muted uppercase tracking-wide">
+                      Swap
+                    </th>
+                    <th scope="col" className="px-4 py-3 text-left text-xs font-semibold text-vx-muted uppercase tracking-wide">
+                      Chain · Solver
+                    </th>
+                    <th scope="col" className="px-4 py-3 text-left text-xs font-semibold text-vx-muted uppercase tracking-wide">
+                      Status
+                    </th>
+                    <th scope="col" className="px-4 py-3 text-right text-xs font-semibold text-vx-muted uppercase tracking-wide">
+                      Age
+                    </th>
+                  </tr>
+                </thead>
+                <tbody className="divide-y divide-vx-line">
+                  {paginated.map((item) => (
+                    <tr
+                      key={item.id}
+                      className="bg-vx-surface/40 hover:bg-vx-surface/60 transition-colors"
+                    >
+                      <td className="px-4 py-4">
+                        <Link
+                          href={`/explore/${item.id}`}
+                          className="block text-sm font-medium text-vx-text truncate max-w-[200px]
+                                     focus:outline-none focus:ring-2 focus:ring-vx-sage focus:ring-offset-2
+                                     focus:ring-offset-vx-ink rounded"
+                        >
+                          {item.srcAmount} {item.srcToken} → {item.dstToken}
+                        </Link>
+                      </td>
+                      <td className="px-4 py-4 text-xs text-vx-muted capitalize whitespace-nowrap">
+                        {item.srcChain} · via {item.solver}
+                      </td>
+                      <td className="px-4 py-4">
+                        <IntentStatusBadge status={item.status} />
+                      </td>
+                      <td className="px-4 py-4 text-xs text-vx-muted num text-right whitespace-nowrap">
+                        {timeAgo(item.createdAt)}
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
             </div>
 
             {pageCount > 1 && (
diff --git a/src/app/explore/page.tsx b/src/app/explore/page.tsx
index b0b1671..6bf6ab8 100644
--- a/src/app/explore/page.tsx
+++ b/src/app/explore/page.tsx
@@ -252,11 +252,6 @@ export default function ExplorePage() {
         )}
       </main>
       <Footer />
-    </div>Merge
-  ),
-  ssr: false,
-});
-
-export default function ExplorePage() {
-  return <ExplorePageClient />;
+    </div>
+  );
 }
diff --git a/src/app/my-intents/page.tsx b/src/app/my-intents/page.tsx
index 41f9c75..ff17c98 100644
--- a/src/app/my-intents/page.tsx
+++ b/src/app/my-intents/page.tsx
@@ -10,11 +10,27 @@ import { useWalletStore } from "@/store/wallet";
 import { useMyLiveIntents } from "@/hooks/useMyLiveIntents";
 import { CHAINS } from "@/lib/marketData";
 import { SkeletonCard } from "@/components/Skeleton";
-import type { IntentStatus } from "@/lib/types";
+import { buildIntentsCsv, downloadCsv } from "@/lib/csv";
+import type { FeedItem, IntentStatus } from "@/lib/types";
 
 const STATUS_OPTIONS: Array<IntentStatus | "all"> = ["all", "pending", "accepted", "filled", "failed"];
 const PAGE_SIZE = 10;
 
+/**
+ * Build a homepage URL that pre-fills SwapCard with an intent's parameters.
+ * Destination address is intentionally NOT carried over (stale/unintended
+ * destination risk — the user must enter it fresh).
+ */
+function swapAgainHref(item: FeedItem): string {
+  const params = new URLSearchParams({
+    srcChain: item.srcChain,
+    srcToken: item.srcToken,
+    amount: item.srcAmount,
+    dstToken: item.dstToken,
+  });
+  return `/?${params.toString()}`;
+}
+
 export default function MyIntentsPage() {
   const address = useWalletStore((s) => s.address);
   const isConnected = useWalletStore((s) => s.isConnected);
@@ -153,27 +169,104 @@ export default function MyIntentsPage() {
                 No intents match your filters.
               </div>
             ) : (
-              <div data-address={address} data-testid="intents-list" className="space-y-2" role="list">
-                {filtered.map((item) => (
-                  <Link
-                    key={item.id}
-                    href={`/explore/${item.id}`}
-                    className="flex flex-col sm:flex-row sm:items-center gap-4 p-4 bg-vx-surface/40 rounded-lg border border-vx-line hover:border-vx-sage/40 active:bg-vx-surface/60 transition-colors"
-                  >
-                    <div className="flex-1 min-w-0">
-                      <div className="text-sm font-medium text-vx-text truncate">
-                        {item.srcAmount} {item.srcToken} → {item.dstToken}
-                      </div>
-                      <div className="text-xs text-vx-muted capitalize">
-                        {item.srcChain} · via {item.solver}
-                      </div>
-                      <IntentStatusBadge status={item.status} />
-                    </div>
-                    <div className="self-start sm:self-center">
-                      <IntentStatusBadge status={item.status} />
-                    </div>
-                  </Link>
-                ))}
+              /*
+                Native <table> so screen readers announce column headers and allow
+                table-navigation mode. Visual design is unchanged — cells use the
+                same spacing and colours as the previous card-stack layout.
+              */
+              <div className="overflow-x-auto rounded-lg border border-vx-line">
+                <table
+                  data-address={address}
+                  data-testid="intents-list"
+                  className="w-full border-collapse"
+                >
+                  <thead>
+                    <tr className="bg-vx-surface/50 border-b border-vx-line">
+                      <th scope="col" className="px-4 py-3 text-left text-xs font-semibold text-vx-muted uppercase tracking-wide">
+                        Swap
+                      </th>
+                      <th scope="col" className="px-4 py-3 text-left text-xs font-semibold text-vx-muted uppercase tracking-wide">
+                        Chain · Solver
+                      </th>
+                      <th scope="col" className="px-4 py-3 text-left text-xs font-semibold text-vx-muted uppercase tracking-wide">
+                        Status
+                      </th>
+                      <th scope="col" className="px-4 py-3 text-right text-xs font-semibold text-vx-muted uppercase tracking-wide">
+                        Actions
+                      </th>
+                    </tr>
+                  </thead>
+                  <tbody className="divide-y divide-vx-line">
+                    {paginated.map((item) => (
+                      <tr
+                        key={item.id}
+                        className="bg-vx-surface/40 hover:bg-vx-surface/60 transition-colors"
+                      >
+                        <td className="px-4 py-4">
+                          <Link
+                            href={`/explore/${item.id}`}
+                            className="block text-sm font-medium text-vx-text truncate max-w-[220px]
+                                       focus:outline-none focus:ring-2 focus:ring-vx-sage focus:ring-offset-2
+                                       focus:ring-offset-vx-ink rounded"
+                          >
+                            {item.srcAmount} {item.srcToken} → {item.dstToken}
+                          </Link>
+                        </td>
+                        <td className="px-4 py-4 text-xs text-vx-muted capitalize whitespace-nowrap">
+                          {item.srcChain} · via {item.solver}
+                        </td>
+                        <td className="px-4 py-4">
+                          <IntentStatusBadge status={item.status} />
+                        </td>
+                        <td className="px-4 py-4 text-right">
+                          {/* Swap again — carries source chain/token/amount + dst token;
+                              destination address is intentionally left blank so the user
+                              must enter a fresh one (never reuse a stale destination). */}
+                          <Link
+                            href={swapAgainHref(item)}
+                            data-testid="swap-again-link"
+                            aria-label={`Swap again: ${item.srcAmount} ${item.srcToken} to ${item.dstToken}`}
+                            className="inline-block px-2.5 py-1 rounded-lg border border-vx-sage/30 text-vx-sage
+                                       text-[11px] font-semibold hover:bg-vx-sage/10 active:bg-vx-sage/20
+                                       transition-colors focus:outline-none focus:ring-2 focus:ring-vx-sage
+                                       focus:ring-offset-2 focus:ring-offset-vx-ink whitespace-nowrap"
+                          >
+                            Swap again
+                          </Link>
+                        </td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            )}
+
+            {/* Pagination */}
+            {pageCount > 1 && (
+              <div className="flex items-center justify-center gap-4 mt-6">
+                <button
+                  type="button"
+                  onClick={() => setPage((p) => Math.max(1, p - 1))}
+                  disabled={page === 1}
+                  className="px-3 py-1.5 text-xs rounded-lg border border-vx-border text-vx-muted
+                             hover:text-vx-text hover:border-vx-sage/30 disabled:opacity-40
+                             disabled:cursor-not-allowed transition-all"
+                >
+                  Previous
+                </button>
+                <span className="text-xs text-vx-muted num">
+                  Page {page} of {pageCount}
+                </span>
+                <button
+                  type="button"
+                  onClick={() => setPage((p) => Math.min(pageCount, p + 1))}
+                  disabled={page === pageCount}
+                  className="px-3 py-1.5 text-xs rounded-lg border border-vx-border text-vx-muted
+                             hover:text-vx-text hover:border-vx-sage/30 disabled:opacity-40
+                             disabled:cursor-not-allowed transition-all"
+                >
+                  Next
+                </button>
               </div>
             )}
           </>
diff --git a/src/app/page.tsx b/src/app/page.tsx
index 1cc4788..7a11ca1 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -1,6 +1,8 @@
 "use client";
 
+import React, { Suspense } from "react";
 import Link from "next/link";
+import { useSearchParams } from "next/navigation";
 import { Nav } from "@/components/Nav";
 import { Footer } from "@/components/Footer";
 import { SwapCard } from "@/components/SwapCard";
@@ -52,6 +54,25 @@ function IntentPipeline() {
   );
 }
 
+// ─── Prefill-aware swap card ───────────────────────────────────────────────────
+// Reads ?srcChain=&srcToken=&amount=&dstToken= from the URL and passes them as
+// initial values. Any missing or invalid param falls back to SwapCard defaults.
+// Wrapped in Suspense because useSearchParams requires it in Next.js 14.
+
+function SwapCardWithPrefill() {
+  const params = useSearchParams();
+  const props: React.ComponentProps<typeof SwapCard> = {};
+  const srcChain = params.get("srcChain");
+  const srcToken = params.get("srcToken");
+  const amount   = params.get("amount");
+  const dstToken = params.get("dstToken");
+  if (srcChain) props.initialChain    = srcChain;
+  if (srcToken) props.initialSrcToken = srcToken;
+  if (amount)   props.initialAmount   = amount;
+  if (dstToken) props.initialDstToken = dstToken;
+  return <SwapCard {...props} />;
+}
+
 // ─── Page ─────────────────────────────────────────────────────────────────────
 
 export default function HomePage() {
@@ -118,7 +139,9 @@ export default function HomePage() {
 
           {/* Right: swap card */}
           <div className="lg:sticky lg:top-24">
-            <SwapCard />
+            <Suspense fallback={<SwapCard />}>
+              <SwapCardWithPrefill />
+            </Suspense>
 
             {/* Supported chains */}
             <div className="mt-5">
diff --git a/src/app/solve/SolvePageClient.tsx b/src/app/solve/SolvePageClient.tsx
index 890745c..174b2a2 100644
--- a/src/app/solve/SolvePageClient.tsx
+++ b/src/app/solve/SolvePageClient.tsx
@@ -1,12 +1,14 @@
 "use client";
 
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { Nav } from "@/components/Nav";
 import { SkeletonCard } from "@/components/Skeleton";
 import { useSolvers } from "@/hooks/useSolvers";
 import { useOpenIntents } from "@/hooks/useOpenIntents";
 import { useAcceptIntent } from "@/hooks/useAcceptIntent";
 import { useSolverRegistration } from "@/hooks/useSolverRegistration";
+import { useLocalStorageDraft } from "@/hooks/useLocalStorageDraft";
+import { useWalletStore } from "@/store/wallet";
 import { timeRemaining } from "@/lib/time";
 import { isValidStellarPublicKey } from "@/lib/stellarAddress";
 import { getMessage } from "@/i18n/messages";
@@ -21,6 +23,12 @@ const usdCompact = (value: number) =>
 
 const MIN_BOND_USD = 50;
 
+/** Shape of the persisted registration draft. */
+type RegistrationDraft = {
+  address: string;
+  bond: string;
+};
+
 const REGISTRATION_LABEL: Record<string, string> = {
   connecting: getMessage("solve.register.states.connecting"),
   building: getMessage("solve.register.states.building"),
@@ -34,11 +42,37 @@ export default function SolvePageClient() {
   const { intents: openIntents, isLoading: intentsLoading, error: intentsError } = useOpenIntents();
   const { accept, acceptingId, error: acceptError } = useAcceptIntent();
 
-  const [address, setAddress] = useState("");
-  const [bond, setBond] = useState("");
+  // Draft persistence — scoped to the currently connected wallet so that
+  // switching wallets never silently restores the wrong address.
+  const connectedAddress = useWalletStore((s) => s.address);
+  const [draft, setDraft, clearDraft] = useLocalStorageDraft<RegistrationDraft>(
+    "vortex:solver-registration-draft",
+    connectedAddress ?? null,
+  );
+
+  const [address, setAddress] = useState(draft?.address ?? "");
+  const [bond, setBond] = useState(draft?.bond ?? "");
+
+  // Sync form fields into the draft whenever they change.
+  const handleAddressChange = (value: string) => {
+    setAddress(value);
+    setDraft({ address: value, bond });
+  };
+  const handleBondChange = (value: string) => {
+    setBond(value);
+    setDraft({ address, bond: value });
+  };
+
   const registration = useSolverRegistration();
   const isRegistering = registration.status in REGISTRATION_LABEL;
 
+  // Clear draft after successful submission.
+  useEffect(() => {
+    if (registration.status === "success") {
+      clearDraft();
+    }
+  }, [registration.status, clearDraft]);
+
   const addressError =
     address && !isValidStellarPublicKey(address)
       ? getMessage("solve.register.validation.invalidAddress")
@@ -55,6 +89,7 @@ export default function SolvePageClient() {
       registration.reset();
       setAddress("");
       setBond("");
+      clearDraft();
       return;
     }
     if (!canRegister) return;
@@ -330,7 +365,7 @@ export default function SolvePageClient() {
                   id="solver-address"
                   type="text"
                   value={address}
-                  onChange={(e) => setAddress(e.target.value.trim())}
+                  onChange={(e) => handleAddressChange(e.target.value.trim())}
                   placeholder={getMessage("solve.register.addressPlaceholder")}
                   aria-invalid={Boolean(addressError)}
                   aria-describedby={addressError ? "solver-address-error" : undefined}
@@ -353,7 +388,7 @@ export default function SolvePageClient() {
                   id="solver-bond"
                   type="number"
                   value={bond}
-                  onChange={(e) => setBond(e.target.value)}
+                  onChange={(e) => handleBondChange(e.target.value)}
                   placeholder={getMessage("solve.register.bondPlaceholder")}
                   aria-invalid={Boolean(bondError)}
                   aria-describedby={bondError ? "solver-bond-error" : undefined}
diff --git a/src/app/solve/[address]/page.test.tsx b/src/app/solve/[address]/page.test.tsx
index 42f7990..c02818b 100644
--- a/src/app/solve/[address]/page.test.tsx
+++ b/src/app/solve/[address]/page.test.tsx
@@ -550,4 +550,4 @@ describe("SolverDetailPage", () => {
     const skeletons = screen.queryAllByTestId("skeleton");
     expect(skeletons.length).toBe(0);
   });
-});
+});});
diff --git a/src/app/solve/page.tsx b/src/app/solve/page.tsx
index 9fc040e..dd0c88b 100644
--- a/src/app/solve/page.tsx
+++ b/src/app/solve/page.tsx
@@ -479,10 +479,5 @@ export default function SolvePage() {
 
       <Footer />
     </div>
-  ),
-  ssr: false,
-});
-
-export default function SolvePage() {
-  return <SolvePageClient />;
+  );
 }
diff --git a/src/components/SwapCard.tsx b/src/components/SwapCard.tsx
index 3524333..9685d70 100644
--- a/src/components/SwapCard.tsx
+++ b/src/components/SwapCard.tsx
@@ -24,20 +24,51 @@ const SUBMISSION_LABEL_KEY: Record<string, MessageKey> = {
 
 export type SwapCardProps = {
   initialAmount?: string;
+  /** Pre-select the source chain (must be a valid CHAINS id; falls back to "ethereum"). */
+  initialChain?: string;
+  /** Pre-select the source token symbol on the given chain (falls back to that chain's first token). */
+  initialSrcToken?: string;
+  /** Pre-select the destination token symbol (must be in DST_TOKENS; falls back to the first). */
+  initialDstToken?: string;
   previewQuote?: Quote;
   onPreviewSubmit?: (request: QuoteRequest) => void;
 };
 
+/** Resolve a chain id from an untrusted string, falling back to "ethereum". */
+function resolveChain(raw: string | undefined): string {
+  if (!raw) return "ethereum";
+  const found = CHAINS.find(c => c.id === raw);
+  return found ? found.id : "ethereum";
+}
+
+/** Resolve a src token for a given chain, falling back to the chain's first token. */
+function resolveSrcToken(chainId: string, symbol: string | undefined) {
+  const tokens = SRC_TOKENS[chainId] ?? SRC_TOKENS["ethereum"] ?? [];
+  const first = tokens[0] ?? SRC_TOKENS["ethereum"]![0]!;
+  if (!symbol) return first;
+  return tokens.find(t => t.symbol === symbol) ?? first;
+}
+
+/** Resolve a dst token, falling back to the first available. */
+function resolveDstToken(symbol: string | undefined) {
+  if (!symbol) return DST_TOKENS[0];
+  return DST_TOKENS.find(t => t.symbol === symbol) ?? DST_TOKENS[0];
+}
+
 export function SwapCard({
   initialAmount = "",
+  initialChain,
+  initialSrcToken,
+  initialDstToken,
   previewQuote,
   onPreviewSubmit,
 }: SwapCardProps = {}) {
   const { t } = useTranslation();
 
-  const [srcChain, setSrcChain] = useState("ethereum");
-  const [srcToken, setSrcToken] = useState(SRC_TOKENS["ethereum"][0]);
-  const [dstToken, setDstToken] = useState(DST_TOKENS[0]);
+  const resolvedChain = resolveChain(initialChain);
+  const [srcChain, setSrcChain] = useState(resolvedChain);
+  const [srcToken, setSrcToken] = useState(() => resolveSrcToken(resolvedChain, initialSrcToken));
+  const [dstToken, setDstToken] = useState(() => resolveDstToken(initialDstToken));
   const [srcAmount, setSrcAmount] = useState(initialAmount);
   const [showChainPicker, setShowChainPicker] = useState(false);
   const [showTokenPicker, setShowTokenPicker] = useState(false);
diff --git a/src/hooks/useLocalStorageDraft.ts b/src/hooks/useLocalStorageDraft.ts
new file mode 100644
index 0000000..cb762e1
--- /dev/null
+++ b/src/hooks/useLocalStorageDraft.ts
@@ -0,0 +1,122 @@
+/**
+ * useLocalStorageDraft
+ *
+ * Provides debounced persistence of an arbitrary draft value to localStorage,
+ * with TTL-based expiry and a wallet-address guard so stale drafts from a
+ * different wallet are never silently restored.
+ *
+ * Usage:
+ *   const [draft, setDraft, clearDraft] = useLocalStorageDraft<MyDraft>(
+ *     "solver-registration",
+ *     connectedWalletAddress ?? null,
+ *   );
+ *
+ * Behaviour:
+ * - Reads on mount; returns null when the key is absent, the TTL has elapsed,
+ *   or the stored wallet address doesn't match the current one.
+ * - Writes are debounced (default 500 ms) to avoid thrashing localStorage on
+ *   every keystroke.
+ * - `clearDraft()` removes the entry immediately (no debounce).
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+const DEFAULT_DEBOUNCE_MS = 500;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+type StoredEntry<T> = {
+  value: T;
+  savedAt: number;
+  walletAddress: string | null;
+};
+
+function readEntry<T>(key: string): StoredEntry<T> | null {
+  try {
+    const raw = localStorage.getItem(key);
+    if (!raw) return null;
+    return JSON.parse(raw) as StoredEntry<T>;
+  } catch {
+    return null;
+  }
+}
+
+function writeEntry<T>(key: string, value: T, walletAddress: string | null): void {
+  try {
+    const entry: StoredEntry<T> = { value, savedAt: Date.now(), walletAddress };
+    localStorage.setItem(key, JSON.stringify(entry));
+  } catch {
+    // Silently ignore quota errors — draft persistence is best-effort.
+  }
+}
+
+function removeEntry(key: string): void {
+  try {
+    localStorage.removeItem(key);
+  } catch {
+    // ignore
+  }
+}
+
+export function useLocalStorageDraft<T>(
+  key: string,
+  walletAddress: string | null,
+  options?: { debounceMs?: number; ttlMs?: number },
+): [T | null, (value: T) => void, () => void] {
+  const debounceMs = options?.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
+
+  // Read on mount — return null for absent, expired, or wrong-wallet entries.
+  const [draft, setDraftState] = useState<T | null>(() => {
+    if (typeof window === "undefined") return null;
+    const entry = readEntry<T>(key);
+    if (!entry) return null;
+    if (Date.now() - entry.savedAt > ttlMs) {
+      removeEntry(key);
+      return null;
+    }
+    if (entry.walletAddress !== walletAddress) {
+      removeEntry(key);
+      return null;
+    }
+    return entry.value;
+  });
+
+  // Keep a stable ref to the latest wallet address so the debounced write
+  // always uses the current value (avoids stale closure issues).
+  const walletRef = useRef(walletAddress);
+  useEffect(() => {
+    walletRef.current = walletAddress;
+  }, [walletAddress]);
+
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const setDraft = useCallback(
+    (value: T) => {
+      setDraftState(value);
+      if (timerRef.current !== null) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => {
+        writeEntry(key, value, walletRef.current);
+        timerRef.current = null;
+      }, debounceMs);
+    },
+    [key, debounceMs],
+  );
+
+  const clearDraft = useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    setDraftState(null);
+    removeEntry(key);
+  }, [key]);
+
+  // Clean up any pending debounced write on unmount.
+  useEffect(() => {
+    return () => {
+      if (timerRef.current !== null) clearTimeout(timerRef.current);
+    };
+  }, []);
+
+  return [draft, setDraft, clearDraft];
+}