phase-5: declarations, from generated numbers to a PDF you file yourself

Formulario 120 and 515 assembly, the review screen, approval, the PDF, and the guided checklist that walks the user through presenting it in Marangatu. Approval is a promise about what the user actually saw: the numbers are recomputed on the way in, and if the documents moved since the declaration was generated the answer is a 409 with the fresh figures stored as a draft, not a silent approval of numbers nobody read. An approved declaration is never regenerated or invalidated. Editing, confirming, rejecting or reclassifying a document flips any ready declaration covering its period back to draft, which is what the dashboard reads to stop offering it for review. The PDF is rendered once and cached against the declaration, so two downloads are byte for byte the same document; every write that changes the numbers clears the cache. Approval pre-renders it, and the route renders on demand, so a failed job costs a wait rather than a missing file. It stays Spanish in both locales, like the form it mirrors, and carries a BORRADOR watermark until it is approved. The seeded declarations are computed through the same code path the product uses, so their figures agree with the documents behind them. Three defects the screenshots caught: the floating scan button swallowed the tap meant for Aprobar on a phone, the summary breakdown reused labels meant for other screens, and five tab labels collided at 390px. Tests that can avoid depending on a fresh seed now do; the ones that cannot say so in the assertion rather than timing out. db:reset warns that the API has to be stopped first, having learned that the hard way. 293 vitest tests, 59 Playwright tests, rules coverage still 100%, typecheck and lint clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-04 05:50:29 +00:00
parent 5dc284c5f2
commit 6620650e9e
33 changed files with 2522 additions and 23 deletions
@@ -0,0 +1,248 @@
+'use client';
+
+import { isApiError, type DeclarationDto } from '@impuestos/contracts';
+import { formatDateLong, formatGs, formatGsAmount, type Locale } from '@impuestos/i18n';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useRef, useState } from 'react';
+import { FormPreview } from '@/components/form-preview';
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+import { Skeleton } from '@/components/ui/skeleton';
+import { useT } from '@/i18n/t';
+import { api } from '@/lib/api';
+import { FilingChecklist } from './filing-checklist';
+
+/**
+ * Flow D2 and D3. The human summary first, the official layout underneath, and one
+ * primary action. Nothing here files anything: the checklist that follows approval is how
+ * the user presents it themselves.
+ */
+export function DeclarationDetail({ id, locale }: { id: string; locale: string }) {
+  const t = useT();
+  const queryClient = useQueryClient();
+  const confirmDialog = useRef<HTMLDialogElement>(null);
+  const [staleWarning, setStaleWarning] = useState<string | null>(null);
+
+  const declaration = useQuery({
+    queryKey: ['declarations', id],
+    queryFn: ({ signal }) => api.getDeclaration(id, signal),
+    retry: (count, error) => !isApiError(error) && count < 1,
+  });
+
+  const approve = useMutation({
+    mutationFn: () => api.approveDeclaration(id),
+    onSuccess: async () => {
+      setStaleWarning(null);
+      confirmDialog.current?.close();
+      await queryClient.invalidateQueries({ queryKey: ['declarations'] });
+      await queryClient.invalidateQueries({ queryKey: ['dashboard'] });
+    },
+    onError: (error) => {
+      confirmDialog.current?.close();
+      // A 409 means the documents moved: the numbers on screen are stale, not wrong.
+      setStaleWarning(isApiError(error) ? error.message : t('common.error.generic'));
+      void queryClient.invalidateQueries({ queryKey: ['declarations', id] });
+    },
+  });
+
+  if (declaration.isPending) {
+    return (
+      <Card className="my-4">
+        <Skeleton name="declaration-summary" />
+      </Card>
+    );
+  }
+
+  if (declaration.isError || !declaration.data) {
+    const missing = isApiError(declaration.error) && declaration.error.code === 'not_found';
+    return (
+      <Card className="my-4 space-y-3">
+        <p role="alert" className="text-sm">
+          {missing ? t('error.not_found') : t('common.error.generic')}
+        </p>
+        {!missing ? (
+          <Button type="button" onClick={() => void declaration.refetch()}>
+            {t('common.retry')}
+          </Button>
+        ) : null}
+      </Card>
+    );
+  }
+
+  const data = declaration.data;
+  const approved = data.status === 'approved';
+  // Spanish in every locale, like the form it names (COPY.md multi-language policy).
+  const officialTitle = `Formulario ${data.formCode}`;
+
+  return (
+    <div className="space-y-4 py-4 pb-28">
+      <div>
+        <h1 className="text-2xl font-semibold tracking-tight">{officialTitle}</h1>
+        <p className="tnum text-sm text-[var(--text-muted)]">{data.period}</p>
+      </div>
+
+      {staleWarning ? (
+        <Card className="border-attention">
+          <p role="alert" className="text-sm text-attention text-pretty">
+            {staleWarning}
+          </p>
+        </Card>
+      ) : null}
+
+      <Card className="space-y-3">
+        <h2 className="font-semibold tracking-tight">{t('decl.summary.title')}</h2>
+        <p className="text-lg text-pretty">{humanSummary(data, t)}</p>
+        <Breakdown declaration={data} />
+      </Card>
+
+      <FormPreview
+        formCode={data.formCode}
+        period={data.period}
+        values={data.values}
+        draft={!approved}
+        labels={{
+          title: t('decl.preview.title'),
+          spanishNote: t('decl.preview.spanishNote'),
+          casilla: t('decl.preview.casilla'),
+          concept: t('decl.preview.concept'),
+          amount: t('decl.amount'),
+          draftMark: t('decl.preview.draftMark'),
+        }}
+      />
+
+      {approved ? (
+        <FilingChecklist declaration={data} locale={locale as Locale} />
+      ) : (
+        <>
+          {/* Sticky footer: the primary action stays reachable however long the form is. */}
+          <div className="fixed inset-x-0 bottom-16 z-10 border-t bg-[var(--surface-raised)] px-5 py-3">
+            <div className="mx-auto flex max-w-2xl gap-2">
+              <a
+                href={api.declarationPdfUrl(data.id)}
+                download
+                className="flex h-11 flex-1 items-center justify-center rounded-full border text-sm font-medium"
+              >
+                {t('decl.downloadPdf')}
+              </a>
+              <Button
+                type="button"
+                className="flex-1"
+                onClick={() => confirmDialog.current?.showModal()}
+              >
+                {t('decl.approve')}
+              </Button>
+            </div>
+          </div>
+
+          <dialog
+            ref={confirmDialog}
+            aria-label={t('decl.approve.confirmTitle')}
+            className="m-auto w-[min(28rem,calc(100vw-2rem))] rounded-2xl border bg-[var(--surface-raised)] p-6 text-[var(--text)] backdrop:bg-black/40"
+          >
+            <div className="space-y-4">
+              <h2 className="text-lg font-semibold tracking-tight">
+                {t('decl.approve.confirmTitle')}
+              </h2>
+              <p className="text-sm text-[var(--text-muted)] text-pretty">
+                {t('decl.approve.confirmBody', {
+                  form: data.formCode,
+                  period: data.period,
+                  amount: formatGsAmount(payable(data)),
+                })}
+              </p>
+              <div className="flex justify-end gap-2">
+                <Button
+                  type="button"
+                  variant="ghost"
+                  onClick={() => confirmDialog.current?.close()}
+                >
+                  {t('common.cancel')}
+                </Button>
+                <Button type="button" disabled={approve.isPending} onClick={() => approve.mutate()}>
+                  {approve.isPending ? t('common.saving') : t('decl.approve')}
+                </Button>
+              </div>
+            </div>
+          </dialog>
+        </>
+      )}
+
+      {approved && data.approvedAt ? (
+        <p className="text-center text-xs text-[var(--text-muted)]">
+          {t('decl.approvedAt', { date: formatDateLong(locale as Locale, data.approvedAt.slice(0, 10)) })}
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+type Translate = ReturnType<typeof useT>;
+
+/** FLOWS.md D2: the sentence comes before the form, always. */
+function humanSummary(declaration: DeclarationDto, t: Translate): string {
+  const summary = declaration.summary;
+
+  if (declaration.formCode === '120') {
+    const aPagar = Number(summary['aPagar'] ?? 0);
+    const result =
+      aPagar > 0
+        ? t('decl.f120.toPay', { amount: formatGsAmount(aPagar) })
+        : t('decl.f120.inFavor', { amount: formatGsAmount(Number(summary['saldoAFavor'] ?? 0)) });
+
+    return t('decl.f120.summary', {
+      sales: formatGsAmount(Number(summary['sales'] ?? 0)),
+      purchases: formatGsAmount(Number(summary['purchases'] ?? 0)),
+      result,
+    });
+  }
+
+  return t('decl.f515.summary', {
+    income: formatGsAmount(Number(summary['grossIncome'] ?? 0)),
+    deductions: formatGsAmount(Number(summary['totalDeductions'] ?? 0)),
+    tax: formatGsAmount(Number(summary['tax'] ?? 0)),
+  });
+}
+
+function Breakdown({ declaration }: { declaration: DeclarationDto }) {
+  const t = useT();
+  const summary = declaration.summary;
+
+  const rows: [string, number][] =
+    declaration.formCode === '120'
+      ? [
+          [t('decl.breakdown.debito'), Number(summary['debito'] ?? 0)],
+          [t('decl.breakdown.credito'), Number(summary['credito'] ?? 0)],
+          [t('decl.breakdown.saldoAnterior'), Number(summary['saldoAnterior'] ?? 0)],
+        ]
+      : [
+          [t('profile.income'), Number(summary['grossIncome'] ?? 0)],
+          [t('docs.detail.deductible'), Number(summary['totalDeductions'] ?? 0)],
+          [t('decl.f515.netIncome'), Number(summary['netIncome'] ?? 0)],
+        ];
+
+  const capExcess = Number(summary['capExcess'] ?? 0);
+
+  return (
+    <dl className="space-y-2 text-sm">
+      {rows.map(([label, amount]) => (
+        <div key={label} className="flex items-baseline justify-between gap-4">
+          <dt className="text-[var(--text-muted)]">{label}</dt>
+          <dd className="tnum font-medium">{formatGs(amount)}</dd>
+        </div>
+      ))}
+
+      {capExcess > 0 ? (
+        <p className="pt-2 text-[var(--text-muted)] text-pretty">
+          {t('decl.f515.capNote', { amount: formatGsAmount(capExcess) })}
+        </p>
+      ) : null}
+    </dl>
+  );
+}
+
+function payable(declaration: DeclarationDto): number {
+  const summary = declaration.summary;
+  return declaration.formCode === '120'
+    ? Number(summary['aPagar'] ?? 0) || Number(summary['saldoAFavor'] ?? 0)
+    : Number(summary['tax'] ?? 0);
+}
@@ -0,0 +1,140 @@
+'use client';
+
+import type { DeclarationDto } from '@impuestos/contracts';
+import { formatDateLong, formatGs, type Locale } from '@impuestos/i18n';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { Check, Copy } from 'lucide-react';
+import { useState } from 'react';
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+import { useT } from '@/i18n/t';
+import { api } from '@/lib/api';
+
+/**
+ * Flow D3. The platform never files anything: it lays out the steps and puts every value
+ * one tap from the clipboard, so transcribing into Marangatu is mechanical rather than
+ * error prone. Marking it filed is the user telling us, not us finding out.
+ */
+export function FilingChecklist({
+  declaration,
+  locale,
+}: {
+  declaration: DeclarationDto;
+  locale: Locale;
+}) {
+  const t = useT();
+  const queryClient = useQueryClient();
+  const [copied, setCopied] = useState<string | null>(null);
+
+  const markFiled = useMutation({
+    mutationFn: () => api.markDeclarationFiled(declaration.id),
+    onSuccess: async () => {
+      await queryClient.invalidateQueries({ queryKey: ['declarations'] });
+      await queryClient.invalidateQueries({ queryKey: ['deadlines'] });
+      await queryClient.invalidateQueries({ queryKey: ['dashboard'] });
+    },
+  });
+
+  const filed = declaration.filedMarkedAt !== null;
+
+  async function copy(casilla: string, amount: number): Promise<void> {
+    // The bare digits, which is what the Marangatu field takes.
+    await navigator.clipboard?.writeText(String(amount));
+    setCopied(casilla);
+    setTimeout(() => setCopied((current) => (current === casilla ? null : current)), 2000);
+  }
+
+  if (filed) {
+    return (
+      <Card className="space-y-2">
+        {/* A short celebration belongs here (FLOWS.md D3); the motion pass is phase 7. */}
+        <h2 className="text-xl font-semibold tracking-tight text-positive">
+          {t('decl.filed.title')}
+        </h2>
+        <p className="text-sm text-[var(--text-muted)] text-pretty">{t('decl.filed.body')}</p>
+        {declaration.filedMarkedAt ? (
+          <p className="text-xs text-[var(--text-muted)]">
+            {t('decl.filedAt', {
+              date: formatDateLong(locale, declaration.filedMarkedAt.slice(0, 10)),
+            })}
+          </p>
+        ) : null}
+      </Card>
+    );
+  }
+
+  return (
+    <Card className="space-y-5">
+      <div className="space-y-1">
+        <h2 className="font-semibold tracking-tight">{t('decl.checklist.title')}</h2>
+        <p className="text-sm text-[var(--text-muted)] text-pretty">{t('decl.checklist.intro')}</p>
+      </div>
+
+      <ol className="list-inside list-decimal space-y-2 text-sm">
+        <li>{t('decl.checklist.step1')}</li>
+        <li>{t('decl.checklist.step2', { form: declaration.formCode, period: declaration.period })}</li>
+        <li>{t('decl.checklist.step3')}</li>
+        <li>{t('decl.checklist.step4')}</li>
+      </ol>
+
+      <ul className="divide-y border-y">
+        {declaration.values.map((value) => (
+          <li key={value.casilla} className="flex items-center justify-between gap-3 py-2.5">
+            <span className="min-w-0">
+              <span className="block truncate text-sm">{value.label}</span>
+              <span className="font-mono text-xs text-[var(--text-muted)]">{value.casilla}</span>
+            </span>
+            <span className="flex shrink-0 items-center gap-2">
+              <span className="tnum text-sm font-medium">{formatGs(value.amount)}</span>
+              <button
+                type="button"
+                aria-label={t('decl.checklist.copyValue')}
+                onClick={() => void copy(value.casilla, value.amount)}
+                className="rounded-full border p-2 hover:bg-accent-50 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent-600"
+              >
+                {copied === value.casilla ? (
+                  <Check aria-hidden className="size-4 text-positive" />
+                ) : (
+                  <Copy aria-hidden className="size-4" />
+                )}
+              </button>
+            </span>
+          </li>
+        ))}
+      </ul>
+
+      {copied ? (
+        <p role="status" className="text-sm text-positive">
+          {t('decl.checklist.copied')}
+        </p>
+      ) : null}
+
+      <div className="space-y-2">
+        <a
+          href={api.declarationPdfUrl(declaration.id)}
+          download
+          className="flex h-11 items-center justify-center rounded-full border text-sm font-medium"
+        >
+          {t('decl.downloadPdf')}
+        </a>
+
+        {markFiled.isError ? (
+          <p role="alert" className="text-sm text-overdue">
+            {t('common.error.generic')}
+          </p>
+        ) : null}
+
+        <Button
+          type="button"
+          size="lg"
+          block
+          disabled={markFiled.isPending}
+          onClick={() => markFiled.mutate()}
+        >
+          {markFiled.isPending ? t('common.saving') : t('decl.checklist.done')}
+        </Button>
+        <p className="text-center text-xs text-[var(--text-muted)]">{t('decl.notFiledYet')}</p>
+      </div>
+    </Card>
+  );
+}
@@ -0,0 +1,12 @@
+import { setRequestLocale } from 'next-intl/server';
+import { DeclarationDetail } from './declaration-detail';
+
+export default async function DeclarationPage({
+  params,
+}: {
+  params: Promise<{ locale: string; id: string }>;
+}) {
+  const { locale, id } = await params;
+  setRequestLocale(locale);
+  return <DeclarationDetail id={id} locale={locale} />;
+}
@@ -0,0 +1,160 @@
+'use client';
+
+import type { DeclarationDto } from '@impuestos/contracts';
+import { formatGs, formatMonthName, type Locale } from '@impuestos/i18n';
+import { addMonths, formatPeriod } from '@impuestos/rules';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { FileCheck } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+import { EmptyState } from '@/components/ui/empty-state';
+import { Skeleton } from '@/components/ui/skeleton';
+import { Link, useRouter } from '@/i18n/navigation';
+import { useT } from '@/i18n/t';
+import { api } from '@/lib/api';
+import { cn } from '@/lib/utils';
+
+/** Flow D1: grouped by year, newest first, with a way to prepare the open period. */
+export function DeclarationsScreen({ locale }: { locale: string }) {
+  const t = useT();
+  const router = useRouter();
+  const queryClient = useQueryClient();
+
+  const declarations = useQuery({
+    queryKey: ['declarations'],
+    queryFn: ({ signal }) => api.listDeclarations(undefined, signal),
+  });
+
+  // The month just closed is the one there is a complete picture for.
+  const now = new Date();
+  const openPeriod = addMonths(formatPeriod(now.getUTCFullYear(), now.getUTCMonth() + 1), -1);
+  const alreadyPrepared = declarations.data?.items.some(
+    (item) => item.formCode === '120' && item.period === openPeriod,
+  );
+
+  const generate = useMutation({
+    mutationFn: () => api.generateDeclaration({ formCode: '120', period: openPeriod }),
+    onSuccess: async (declaration) => {
+      await queryClient.invalidateQueries({ queryKey: ['declarations'] });
+      router.push(`/declaraciones/${declaration.id}`);
+    },
+  });
+
+  const byYear = groupByYear(declarations.data?.items ?? []);
+
+  return (
+    <div className="space-y-4 py-4">
+      <h1 className="text-2xl font-semibold tracking-tight">{t('decl.title')}</h1>
+
+      {!alreadyPrepared ? (
+        <Card className="space-y-3">
+          <p className="font-medium">
+            {t('decl.generate', { form: '120', period: formatMonthName(locale as Locale, openPeriod) })}
+          </p>
+          {generate.isError ? (
+            <p role="alert" className="text-sm text-overdue">
+              {t('common.error.generic')}
+            </p>
+          ) : null}
+          <Button type="button" block disabled={generate.isPending} onClick={() => generate.mutate()}>
+            {generate.isPending ? t('decl.generating') : t('decl.generate', {
+              form: '120',
+              period: formatMonthName(locale as Locale, openPeriod),
+            })}
+          </Button>
+        </Card>
+      ) : null}
+
+      {declarations.isPending ? (
+        <Card>
+          <Skeleton name="declaration-summary" />
+        </Card>
+      ) : null}
+
+      {declarations.isError ? (
+        <Card className="space-y-3">
+          <p role="alert" className="text-sm">
+            {t('common.error.generic')}
+          </p>
+          <Button type="button" onClick={() => void declarations.refetch()}>
+            {t('common.retry')}
+          </Button>
+        </Card>
+      ) : null}
+
+      {declarations.data && declarations.data.items.length === 0 ? (
+        <Card>
+          <EmptyState
+            icon={<FileCheck aria-hidden className="size-8" />}
+            title={t('decl.empty')}
+            body={t('decl.emptyBody')}
+          />
+        </Card>
+      ) : null}
+
+      {byYear.map(([year, items]) => (
+        <section key={year} className="space-y-2">
+          <h2 className="tnum text-sm font-medium text-[var(--text-muted)]">{year}</h2>
+          <Card className="divide-y p-0">
+            <ul>
+              {items.map((declaration) => (
+                <li key={declaration.id} className="px-6">
+                  <Link
+                    href={`/declaraciones/${declaration.id}`}
+                    className="flex items-center justify-between gap-4 py-4"
+                  >
+                    <span className="min-w-0">
+                      <span className="flex items-center gap-2">
+                        <span className="tnum rounded-full bg-accent-50 px-2 py-0.5 text-xs font-medium text-accent-700">
+                          {declaration.formCode}
+                        </span>
+                        <span className="tnum text-sm">{declaration.period}</span>
+                      </span>
+                      <StatusChip declaration={declaration} />
+                    </span>
+                    <span className="tnum shrink-0 font-medium">{headline(declaration)}</span>
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          </Card>
+        </section>
+      ))}
+    </div>
+  );
+}
+
+function StatusChip({ declaration }: { declaration: DeclarationDto }) {
+  const t = useT();
+  return (
+    <span
+      className={cn(
+        'mt-1.5 inline-flex rounded-full px-2.5 py-0.5 text-xs font-medium',
+        declaration.status === 'approved' && 'bg-positive-soft text-positive',
+        declaration.status === 'ready' && 'bg-attention-soft text-attention',
+        declaration.status === 'draft' && 'bg-[var(--surface)] text-[var(--text-muted)]',
+      )}
+    >
+      {t(`decl.status.${declaration.status}` as const)}
+    </span>
+  );
+}
+
+/** The one number that matters on a row: what it costs, or what it saves. */
+function headline(declaration: DeclarationDto): string {
+  const summary = declaration.summary;
+  const amount =
+    declaration.formCode === '120'
+      ? Number(summary['aPagar'] ?? 0) || Number(summary['saldoAFavor'] ?? 0)
+      : Number(summary['tax'] ?? 0);
+  return formatGs(amount);
+}
+
+function groupByYear(items: DeclarationDto[]): [string, DeclarationDto[]][] {
+  const groups = new Map<string, DeclarationDto[]>();
+  for (const item of items) {
+    const year = item.period.slice(0, 4);
+    groups.set(year, [...(groups.get(year) ?? []), item]);
+  }
+  return [...groups.entries()].sort((a, b) => b[0].localeCompare(a[0]));
+}
@@ -0,0 +1,12 @@
+import { setRequestLocale } from 'next-intl/server';
+import { DeclarationsScreen } from './declarations-screen';
+
+export default async function DeclarationsPage({
+  params,
+}: {
+  params: Promise<{ locale: string }>;
+}) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+  return <DeclarationsScreen locale={locale} />;
+}
@@ -1,15 +1,20 @@
 'use client';

-import { FileText, Home, Inbox, Plus, CalendarClock } from 'lucide-react';
+import { CalendarClock, FileCheck, FileText, Home, Inbox, Plus } from 'lucide-react';
 import type { ComponentType } from 'react';
 import { Link, usePathname } from '@/i18n/navigation';
 import { useT } from '@/i18n/t';
 import { cn } from '@/lib/utils';

-const TABS: { href: string; key: 'inicio' | 'bandeja' | 'comprobantes' | 'vencimientos'; Icon: ComponentType<{ className?: string }> }[] = [
+const TABS: {
+  href: string;
+  key: 'inicio' | 'bandeja' | 'comprobantes' | 'declaraciones' | 'vencimientos';
+  Icon: ComponentType<{ className?: string }>;
+}[] = [
  { href: '/inicio', key: 'inicio', Icon: Home },
  { href: '/bandeja', key: 'bandeja', Icon: Inbox },
  { href: '/comprobantes', key: 'comprobantes', Icon: FileText },
+  { href: '/declaraciones', key: 'declaraciones', Icon: FileCheck },
  { href: '/vencimientos', key: 'vencimientos', Icon: CalendarClock },
 ];

@@ -22,26 +27,37 @@ export function AppShell() {
  const t = useT();
  const pathname = usePathname();

+  /**
+   * The scan button belongs on the screens you arrive at, not on a detail screen that
+   * already has its own primary action. On a phone the two overlap, and a floating button
+   * that swallows the tap meant for "Aprobar" is worse than no floating button.
+   */
+  const onDetailScreen = TABS.some(
+    ({ href }) => pathname !== href && pathname.startsWith(`${href}/`),
+  );
+
  return (
    <>
-      <Link
-        href="/escanear"
-        aria-label={t('scan.fab')}
-        className={cn(
-          'fixed right-5 bottom-24 z-20 flex items-center gap-2 rounded-full bg-accent-600 px-5 py-3.5',
-          'font-medium text-white shadow-lg transition-colors hover:bg-accent-700',
-          'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent-600',
-        )}
-      >
-        <Plus aria-hidden className="size-5" />
-        {t('scan.fab')}
-      </Link>
+      {!onDetailScreen ? (
+        <Link
+          href="/escanear"
+          aria-label={t('scan.fab')}
+          className={cn(
+            'fixed right-5 bottom-24 z-20 flex items-center gap-2 rounded-full bg-accent-600 px-5 py-3.5',
+            'font-medium text-white shadow-lg transition-colors hover:bg-accent-700',
+            'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent-600',
+          )}
+        >
+          <Plus aria-hidden className="size-5" />
+          {t('scan.fab')}
+        </Link>
+      ) : null}

      <nav
        aria-label={t('common.appName')}
        className="fixed inset-x-0 bottom-0 z-10 border-t bg-[var(--surface-raised)]"
      >
-        <ul className="mx-auto flex max-w-2xl">
+        <ul className="mx-auto flex max-w-2xl px-1">
          {TABS.map(({ href, key, Icon }) => {
            const active = pathname === href || pathname.startsWith(`${href}/`);
            return (
@@ -50,12 +66,15 @@ export function AppShell() {
                  href={href}
                  aria-current={active ? 'page' : undefined}
                  className={cn(
-                    'flex flex-col items-center gap-1 py-2.5 text-xs transition-colors',
+                    'flex flex-col items-center gap-1 px-0.5 py-2.5 transition-colors',
                    active ? 'text-accent-700' : 'text-[var(--text-muted)]',
                  )}
                >
                  <Icon aria-hidden className="size-5" />
-                  {t(`nav.${key}` as const)}
+                  {/* Five tabs on a 390px screen: the label has to give, not overlap. */}
+                  <span className="w-full truncate text-center text-[10px] leading-tight">
+                    {t(`nav.${key}` as const)}
+                  </span>
                </Link>
              </li>
            );
@@ -0,0 +1,83 @@
+import type { FormValueDto } from '@impuestos/contracts';
+import { formatGs } from '@impuestos/i18n';
+import { cn } from '@/lib/utils';
+
+/**
+ * The declaration laid out the way the official form is, casilla by casilla, so the
+ * numbers can be transcribed straight across into Marangatu.
+ *
+ * The labels are Spanish in every locale, deliberately: this mirrors the DNIT form, and a
+ * form whose labels have been translated is harder to copy from, not easier
+ * (COPY.md multi-language policy). The caption around it says so in the reader's language.
+ */
+export function FormPreview({
+  formCode,
+  period,
+  values,
+  draft,
+  labels,
+}: {
+  formCode: string;
+  period: string;
+  values: FormValueDto[];
+  draft: boolean;
+  labels: { title: string; spanishNote: string; casilla: string; concept: string; amount: string; draftMark: string };
+}) {
+  // The official designation, Spanish in every locale: COPY.md keeps "Formulario 120"
+  // and "515" as-is in English, and this block mirrors the DNIT form.
+  const officialTitle = `Formulario ${formCode}`;
+
+  return (
+    <div className="space-y-2">
+      <div className="flex flex-wrap items-baseline justify-between gap-2">
+        <h2 className="font-semibold tracking-tight">{labels.title}</h2>
+        <span className="text-xs text-[var(--text-muted)]">{labels.spanishNote}</span>
+      </div>
+
+      <div className="relative overflow-hidden rounded-2xl border bg-[var(--surface-raised)]">
+        {draft ? (
+          <span
+            aria-hidden
+            className="pointer-events-none absolute inset-0 flex items-center justify-center text-5xl font-bold tracking-widest text-overdue/10 -rotate-12"
+          >
+            {labels.draftMark}
+          </span>
+        ) : null}
+
+        <div className="border-b px-5 py-4">
+          <p className="font-semibold tracking-tight">{officialTitle}</p>
+          <p className="tnum text-sm text-[var(--text-muted)]">{period}</p>
+        </div>
+
+        <table className="w-full text-sm">
+          <thead>
+            <tr className="border-b text-left text-xs text-[var(--text-muted)]">
+              <th scope="col" className="px-5 py-2 font-medium">
+                {labels.casilla}
+              </th>
+              <th scope="col" className="py-2 font-medium">
+                {labels.concept}
+              </th>
+              <th scope="col" className="px-5 py-2 text-right font-medium">
+                {labels.amount}
+              </th>
+            </tr>
+          </thead>
+          <tbody>
+            {values.map((value) => (
+              <tr key={value.casilla} className="border-b last:border-0">
+                <td className="px-5 py-2.5 font-mono text-xs text-[var(--text-muted)]">
+                  {value.casilla}
+                </td>
+                <td className="py-2.5">{value.label}</td>
+                <td className={cn('tnum px-5 py-2.5 text-right font-medium')}>
+                  {formatGs(value.amount)}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}