feat(faucet): add devnet faucet web app for test tokens

[sadiq1971]

Summary

New packages/faucet workspace — a public web faucet for the devnet test tokens (DEMO, PROMPT, USDCX), implementing the approved design from #96 against the middleware faucet API specced in ChainSafe/canton-middleware#350 (assumed available under /api/v2/faucet/*).

Closes #96

What's included

Faucet app (packages/faucet) — mirrors the dapp's stack and structure (Vite + React 19 + TS, CSS modules, same design tokens, SPDX headers, cn()/component conventions):

• lib/faucet.ts — typed client for the four faucet endpoints (tokens, drip, status, drips/recent), snake_case→camelCase mapping, response-shape guards, and typed errors (NotRegisteredError / CooldownActiveError / FaucetDrainedError)
• pages/FaucetPage.tsx — the single drip flow: token selector (config-driven from the API, nothing hardcoded), recipient address with validation + paste helper, drip button with per-token cooldown countdown (restored from the status endpoint when an address is re-entered), success receipts (offer-specific copy for USDCX: "accept it from Offers in the dapp"), and a live recent-drips feed (30s refresh)
• Distinct UI states for 404 (address not registered → register-in-dapp hint), 429 (cooldown → countdown), 503 (reserves drained)
• Responsive down to mobile (token grid restacks, like the dapp's breakpoints)

Monorepo wiring: workspace + root scripts (dev:faucet, build:faucet, test:faucet, lint/format coverage), eslint react-hooks rules, release-please component (faucet-v*), Docker image (unprivileged nginx + runtime env injection, same pattern as the dapp) with a faucet-docker.yml workflow.

Side effects on existing packages:

• packages/dapp/Dockerfile now copies the faucet manifest (required for npm ci once the workspace exists)
• react-dom aligned to react 19.2.7 in dapp + faucet — React 19 throws at runtime on exact-version mismatch, which the fresh workspace install surfaced

Verification

Driven end-to-end with Playwright against a mock of the middleware faucet API: 14/14 checks pass — initial load (tokens + feed from API), address validation, direct drip receipt with tx id, USDCX offer receipt, countdown start/restore via status endpoint, 404/503 error states, mobile layout, no console errors. npm run build, lint, format:check, test all green.

Notes / follow-ups

• Drip amounts and cooldowns render from GET /api/v2/faucet/tokens, so final values are a middleware config concern.
• Captcha (captcha_token) intentionally not wired yet — pending provider decision in canton-middleware#350.
• Address validation is format-only (0x + 40 hex); no checksum validation to avoid pulling ethers into the bundle for one call.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a new @chainsafe/canton-faucet package, which is a React-based public web faucet for devnet test tokens, complete with Docker configuration, Nginx setup, and integration into the monorepo workspace. The review feedback suggests several robustness improvements, including adding defensive checks for API responses to prevent potential null-pointer exceptions, verifying the existence of navigator.clipboard to avoid crashes in non-secure HTTP environments, and handling non-positive values in the cooldown formatting utility.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Add a defensive check to ensure data is not null or undefined before accessing data.items. If the API returns a null response, accessing data.items will throw a TypeError.

Suggested change

	const data = await get<{ items: unknown[] }>(baseUrl, "/api/v2/faucet/tokens");
	if (!Array.isArray(data.items)) throw new Error("Unexpected faucet tokens response shape");
	const data = await get<{ items: unknown[] }>(baseUrl, "/api/v2/faucet/tokens");
	if (!data || !Array.isArray(data.items)) throw new Error("Unexpected faucet tokens response shape");

[gemini-code-assist]

Add a defensive check to ensure data is not null or undefined before accessing data.items to prevent potential runtime TypeErrors if the API returns a null response.

Suggested change

	const data = await get<{ items: unknown[] }>(
	baseUrl,
	`/api/v2/faucet/status?address=${encodeURIComponent(address)}`,
	);
	if (!Array.isArray(data.items)) throw new Error("Unexpected faucet status response shape");
	const data = await get<{ items: unknown[] }>(
	baseUrl,
	`/api/v2/faucet/status?address=${encodeURIComponent(address)}`,
	);
	if (!data || !Array.isArray(data.items)) throw new Error("Unexpected faucet status response shape");

[gemini-code-assist]

Add a defensive check to ensure data is not null or undefined before accessing data.items to prevent potential runtime TypeErrors if the API returns a null response.

Suggested change

	const data = await get<{ items: unknown[] }>(
	baseUrl,
	`/api/v2/faucet/drips/recent?limit=${limit}`,
	);
	if (!Array.isArray(data.items)) throw new Error("Unexpected recent drips response shape");
	const data = await get<{ items: unknown[] }>(
	baseUrl,
	`/api/v2/faucet/drips/recent?limit=${limit}`,
	);
	if (!data || !Array.isArray(data.items)) throw new Error("Unexpected recent drips response shape");

[gemini-code-assist]

Add a defensive check to ensure data is not null or undefined before accessing its properties (data.kind, data.amount, data.token) to prevent potential runtime TypeErrors if the API returns a null response.

Suggested change

	const data = JSON.parse(text) as Record<string, unknown>;
	if (!isDripKind(data.kind) || typeof data.amount !== "string" || typeof data.token !== "string") {
	throw new Error("Unexpected drip response shape");
	}
	const data = JSON.parse(text) as Record<string, unknown>;
	if (!data || !isDripKind(data.kind) || typeof data.amount !== "string" || typeof data.token !== "string") {
	throw new Error("Unexpected drip response shape");
	}

[gemini-code-assist]

Check if navigator.clipboard is defined before calling readText(). In non-secure contexts (HTTP) or certain browsers, navigator.clipboard may be undefined, which would cause a runtime TypeError when attempting to access readText.

  async function handlePaste() {
    try {
      if (navigator.clipboard) {
        const text = await navigator.clipboard.readText();
        if (text) setAddress(text.trim());
      }
    } catch {
      // Clipboard access denied — user can paste manually.
    }
  }

[gemini-code-assist]

Handle cases where seconds is less than or equal to 0 (e.g., if a token has no cooldown configured) to avoid displaying confusing labels like 0 days or 0 minutes.

Suggested change

	export function formatCooldownNoun(seconds: number): string {
	if (seconds % 86400 === 0) {
	export function formatCooldownNoun(seconds: number): string {
	if (seconds <= 0) return "no cooldown";
	if (seconds % 86400 === 0) {