alpha01 filetti: web app, crossword service and tor batch

2026-06-05 16:22:17 +02:00
parent 47d8957e15
commit 9cb8a5aa8f
29 changed files with 8590 additions and 0 deletions
--- a/webapp/README.md
+++ b/webapp/README.md
@@ -0,0 +1,47 @@
+# Webapp iniziale
+
+Questa cartella contiene il primo scheletro della futura UI web in Next.js.
+
+## Obiettivo
+
+Preparare una base chiara da discutere riga per riga, prima ancora di collegarla davvero al backend Python.
+
+## Idee guida
+
+- `app/page.tsx`
+  - redirect iniziale alla lingua di default
+- `app/[locale]/page.tsx`
+  - homepage localizzata
+- `app/[locale]/new/page.tsx`
+  - pagina localizzata di configurazione del cruciverba
+- `app/[locale]/crosswords/[id]/page.tsx`
+  - pagina localizzata di gioco del cruciverba
+- `components/`
+  - pezzi UI riusabili
+- `lib/types.ts`
+  - tipi TypeScript coerenti col contratto JSON
+- `lib/i18n.ts`
+  - dizionari e gestione locale `it/en/es`
+- `lib/mock-crossword.ts`
+  - mock locale della response JSON
+
+## Stato attuale
+
+- il form non chiama ancora il backend reale
+- la pagina di gioco usa un mock locale
+- la struttura però è già pensata per ricevere il JSON del motore
+- il frontend è già predisposto per `it`, `en`, `es`
+
+## Prossimo passo previsto
+
+Sostituire il mock locale con:
+
+- `POST /crosswords/generate`
+- `GET /crosswords/{id}`
+
+e poi introdurre:
+
+- polling dello stato
+- PDF giocatore/soluzione
+- salvataggio partite
+- UI mobile raffinata
--- a/webapp/app/[locale]/crosswords/[id]/page.tsx
+++ b/webapp/app/[locale]/crosswords/[id]/page.tsx
@@ -0,0 +1,42 @@
+import { notFound } from "next/navigation";
+import { CrosswordRuntimePage } from "@/components/crossword-runtime-page";
+import { LanguageSwitcher } from "@/components/language-switcher";
+import { getDictionary, isLocale } from "@/lib/i18n";
+
+type CrosswordPageProps = {
+  params: Promise<{ locale: string; id: string }>;
+};
+
+export default async function CrosswordPage({ params }: CrosswordPageProps) {
+  const { locale, id } = await params;
+  if (!isLocale(locale)) {
+    notFound();
+  }
+
+  const dict = getDictionary(locale);
+
+  return (
+    <main className="shell stack">
+      <section className="card play-header">
+        <div className="hero__topline">
+          <span className="hero__badge">{dict.play.badge}</span>
+          <LanguageSwitcher locale={locale} path={`/crosswords/${id}`} />
+        </div>
+        <h1 className="page-title">Progetto Enigma</h1>
+        <p className="page-subtitle">{dict.play.subtitle}</p>
+      </section>
+
+      <CrosswordRuntimePage
+        id={id}
+        locale={locale}
+        labels={{
+          player: dict.player,
+          clues: dict.clues,
+          play: dict.play,
+          loading: dict.play.loading,
+          errorPrefix: dict.play.errorPrefix,
+        }}
+      />
+    </main>
+  );
+}
--- a/webapp/app/[locale]/crosswords/[id]/solution/page.tsx
+++ b/webapp/app/[locale]/crosswords/[id]/solution/page.tsx
@@ -0,0 +1,42 @@
+import { notFound } from "next/navigation";
+import { CrosswordSolutionRuntimePage } from "@/components/crossword-solution-runtime-page";
+import { LanguageSwitcher } from "@/components/language-switcher";
+import { getDictionary, isLocale } from "@/lib/i18n";
+
+type CrosswordSolutionPageProps = {
+  params: Promise<{ locale: string; id: string }>;
+};
+
+export default async function CrosswordSolutionPage({ params }: CrosswordSolutionPageProps) {
+  const { locale, id } = await params;
+  if (!isLocale(locale)) {
+    notFound();
+  }
+
+  const dict = getDictionary(locale);
+
+  return (
+    <main className="shell stack">
+      <section className="card play-header">
+        <div className="hero__topline">
+          <span className="hero__badge">{dict.solution.badge}</span>
+          <LanguageSwitcher locale={locale} path={`/crosswords/${id}/solution`} />
+        </div>
+        <h1 className="page-title">Progetto Enigma</h1>
+        <p className="page-subtitle">{dict.solution.subtitle}</p>
+      </section>
+
+      <CrosswordSolutionRuntimePage
+        id={id}
+        locale={locale}
+        labels={{
+          player: dict.player,
+          clues: dict.clues,
+          solution: dict.solution,
+          loading: dict.play.loading,
+          errorPrefix: dict.play.errorPrefix,
+        }}
+      />
+    </main>
+  );
+}
--- a/webapp/app/[locale]/new/page.tsx
+++ b/webapp/app/[locale]/new/page.tsx
@@ -0,0 +1,34 @@
+import { notFound } from "next/navigation";
+import { CrosswordConfigForm } from "@/components/crossword-config-form";
+import { LanguageSwitcher } from "@/components/language-switcher";
+import { getDictionary, isLocale } from "@/lib/i18n";
+
+type NewCrosswordPageProps = {
+  params: Promise<{ locale: string }>;
+};
+
+export default async function NewCrosswordPage({ params }: NewCrosswordPageProps) {
+  const { locale } = await params;
+  if (!isLocale(locale)) {
+    notFound();
+  }
+
+  const dict = getDictionary(locale);
+
+  return (
+    <main className="shell stack">
+      <section className="hero">
+        <div className="hero__topline">
+          <span className="hero__badge">{dict.newPage.badge}</span>
+          <LanguageSwitcher locale={locale} path="/new" />
+        </div>
+        <h1 className="page-title">{dict.newPage.title}</h1>
+        <p className="page-subtitle">{dict.newPage.subtitle}</p>
+      </section>
+
+      <section className="card panel">
+        <CrosswordConfigForm locale={locale} dict={dict.form} />
+      </section>
+    </main>
+  );
+}
--- a/webapp/app/[locale]/page.tsx
+++ b/webapp/app/[locale]/page.tsx
@@ -0,0 +1,85 @@
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { CrosswordConfigForm } from "@/components/crossword-config-form";
+import { LanguageSwitcher } from "@/components/language-switcher";
+import { getDictionary, isLocale } from "@/lib/i18n";
+import { getMockCrosswordResponse } from "@/lib/mock-crossword";
+
+type LocalizedHomePageProps = {
+  params: Promise<{ locale: string }>;
+};
+
+export default async function LocalizedHomePage({ params }: LocalizedHomePageProps) {
+  const { locale } = await params;
+  if (!isLocale(locale)) {
+    notFound();
+  }
+
+  const dict = getDictionary(locale);
+  const crossword = getMockCrosswordResponse(locale);
+
+  return (
+    <main className="shell stack">
+      <section className="hero">
+        <div className="hero__topline">
+          <span className="hero__badge">{dict.home.badge}</span>
+          <LanguageSwitcher locale={locale} />
+        </div>
+        <h1>{dict.home.title}</h1>
+        <p>{dict.home.subtitle}</p>
+      </section>
+
+      <section className="home-grid">
+        <div className="card panel">
+          <h2>{dict.home.requestTitle}</h2>
+          <p className="muted">{dict.home.requestText}</p>
+          <CrosswordConfigForm locale={locale} dict={dict.form} />
+        </div>
+
+        <div className="stack">
+          <div className="card panel">
+            <h2>{dict.home.structureTitle}</h2>
+            <div className="chip-row">
+              {dict.home.structureChips.map((chip) => (
+                <span className="chip" key={chip}>
+                  {chip}
+                </span>
+              ))}
+            </div>
+            <p className="muted contract-note">{dict.home.structureText}</p>
+          </div>
+
+          <div className="card panel">
+            <h2>{dict.home.demoTitle}</h2>
+            <div className="kpi-grid">
+              <div className="kpi">
+                <span className="muted">{dict.home.kpis.words}</span>
+                <strong>{crossword.summary.total_words}</strong>
+              </div>
+              <div className="kpi">
+                <span className="muted">{dict.home.kpis.intersections}</span>
+                <strong>{crossword.summary.intersections}</strong>
+              </div>
+              <div className="kpi">
+                <span className="muted">{dict.home.kpis.rows}</span>
+                <strong>{crossword.grid.rows}</strong>
+              </div>
+              <div className="kpi">
+                <span className="muted">{dict.home.kpis.cols}</span>
+                <strong>{crossword.grid.cols}</strong>
+              </div>
+            </div>
+            <div className="actions" style={{ marginTop: 18 }}>
+              <Link className="button" href={`/${locale}/crosswords/demo-transport`}>
+                {dict.home.openDemo}
+              </Link>
+              <Link className="button button--secondary" href={`/${locale}/new`}>
+                {dict.home.openConfig}
+              </Link>
+            </div>
+          </div>
+        </div>
+      </section>
+    </main>
+  );
+}
--- a/webapp/app/api/crosswords/[id]/route.ts
+++ b/webapp/app/api/crosswords/[id]/route.ts
@@ -0,0 +1,18 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { NextResponse } from "next/server";
+
+const RUNTIME_DIR = join(process.cwd(), ".runtime-crosswords");
+
+export async function GET(
+  _request: Request,
+  context: { params: Promise<{ id: string }> },
+) {
+  try {
+    const { id } = await context.params;
+    const source = await readFile(join(RUNTIME_DIR, `${id}.json`), "utf-8");
+    return NextResponse.json(JSON.parse(source));
+  } catch {
+    return NextResponse.json({ status: "not_found" }, { status: 404 });
+  }
+}
--- a/webapp/app/api/crosswords/generate/route.ts
+++ b/webapp/app/api/crosswords/generate/route.ts
@@ -0,0 +1,65 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { NextResponse } from "next/server";
+
+const PYTHON = process.env.PYTHON_EXECUTABLE || "python";
+const PROJECT_ROOT = join(process.cwd(), "..");
+const RUNTIME_DIR = join(process.cwd(), ".runtime-crosswords");
+
+function runPython(requestPayload: unknown): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(PYTHON, ["crossword_service.py"], {
+      cwd: PROJECT_ROOT,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    child.on("error", (error) => {
+      reject(error);
+    });
+
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(stderr || `Python process exited with code ${code}`));
+        return;
+      }
+      resolve(stdout);
+    });
+
+    child.stdin.write(JSON.stringify(requestPayload));
+    child.stdin.end();
+  });
+}
+
+export async function POST(request: Request) {
+  try {
+    const payload = await request.json();
+    const stdout = await runPython(payload);
+    const responsePayload = JSON.parse(stdout);
+
+    await mkdir(RUNTIME_DIR, { recursive: true });
+    const targetPath = join(RUNTIME_DIR, `${responsePayload.crossword_id}.json`);
+    await writeFile(targetPath, JSON.stringify(responsePayload, null, 2), "utf-8");
+
+    return NextResponse.json(responsePayload);
+  } catch (error) {
+    return NextResponse.json(
+      {
+        status: "error",
+        message: error instanceof Error ? error.message : "Unknown error",
+      },
+      { status: 500 },
+    );
+  }
+}
--- a/webapp/app/globals.css
+++ b/webapp/app/globals.css
@@ -0,0 +1,488 @@
+:root {
+  --bg: #f4efe3;
+  --paper: #fffaf1;
+  --ink: #1f2a2a;
+  --muted: #6f776c;
+  --line: #d7cdb8;
+  --accent: #0d6b66;
+  --accent-2: #d97841;
+  --shadow: 0 18px 50px rgba(58, 48, 24, 0.12);
+  --cell: 42px;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  min-height: 100%;
+}
+
+body {
+  margin: 0;
+  min-height: 100%;
+  overflow-x: hidden;
+  background:
+    radial-gradient(circle at top left, rgba(217, 120, 65, 0.16), transparent 28%),
+    radial-gradient(circle at bottom right, rgba(13, 107, 102, 0.14), transparent 24%),
+    linear-gradient(180deg, #f8f4ea 0%, var(--bg) 100%);
+  color: var(--ink);
+  font-family: "IBM Plex Sans", "Segoe UI", sans-serif;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+button,
+input,
+select {
+  font: inherit;
+}
+
+.shell {
+  width: min(1240px, calc(100% - 32px));
+  margin: 0 auto;
+}
+
+.hero {
+  padding: 32px 0 16px;
+}
+
+.hero__topline {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  align-items: center;
+  flex-wrap: wrap;
+}
+
+.hero__badge {
+  display: inline-flex;
+  gap: 8px;
+  align-items: center;
+  padding: 8px 12px;
+  border-radius: 999px;
+  background: rgba(13, 107, 102, 0.09);
+  color: var(--accent);
+  font-size: 13px;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.hero__badge--soft {
+  background: rgba(217, 120, 65, 0.12);
+  color: #8d4d2b;
+}
+
+.hero h1,
+.page-title {
+  margin: 16px 0 10px;
+  font-family: "Space Grotesk", "Segoe UI", sans-serif;
+  font-size: clamp(2.2rem, 4vw, 4.2rem);
+  line-height: 0.95;
+  letter-spacing: -0.05em;
+}
+
+.hero p,
+.page-subtitle {
+  max-width: 760px;
+  margin: 0;
+  color: var(--muted);
+  font-size: 1.04rem;
+  line-height: 1.6;
+}
+
+.card {
+  background: rgba(255, 250, 241, 0.9);
+  border: 1px solid rgba(215, 205, 184, 0.95);
+  border-radius: 24px;
+  box-shadow: var(--shadow);
+  backdrop-filter: blur(12px);
+}
+
+.stack {
+  display: grid;
+  gap: 24px;
+}
+
+.home-grid {
+  display: grid;
+  grid-template-columns: minmax(320px, 420px) minmax(0, 1fr);
+  gap: 24px;
+  padding-bottom: 48px;
+}
+
+.panel {
+  padding: 24px;
+}
+
+.panel h2,
+.panel h3 {
+  margin: 0 0 12px;
+  font-family: "Space Grotesk", "Segoe UI", sans-serif;
+}
+
+.muted {
+  color: var(--muted);
+}
+
+.config-form {
+  display: grid;
+  gap: 16px;
+}
+
+.config-form__grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 14px;
+}
+
+.field {
+  display: grid;
+  gap: 6px;
+}
+
+.field label {
+  font-size: 0.92rem;
+  font-weight: 700;
+}
+
+.field input,
+.field select {
+  width: 100%;
+  padding: 12px 14px;
+  border-radius: 14px;
+  border: 1px solid var(--line);
+  background: #fffdf8;
+}
+
+.form-error {
+  margin: 0;
+  color: #b03030;
+  font-weight: 700;
+}
+
+.actions {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  flex-wrap: wrap;
+}
+
+.button {
+  border: 0;
+  border-radius: 16px;
+  padding: 13px 18px;
+  background: var(--accent);
+  color: white;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.button--secondary {
+  background: #ece2cc;
+  color: var(--ink);
+}
+
+.kpi-grid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 14px;
+}
+
+.kpi-grid--play {
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+}
+
+.kpi {
+  padding: 18px;
+  border-radius: 18px;
+  background: #fffdf8;
+  border: 1px solid var(--line);
+}
+
+.kpi strong {
+  display: block;
+  font-size: 1.7rem;
+  font-family: "Space Grotesk", "Segoe UI", sans-serif;
+}
+
+.play-header,
+.play-overview,
+.play-stage,
+.play-sidebar,
+.solution-topbar {
+  padding: 22px;
+}
+
+.play-overview {
+  display: grid;
+  gap: 18px;
+}
+
+.play-overview__header {
+  display: flex;
+  justify-content: space-between;
+  gap: 18px;
+  align-items: start;
+  flex-wrap: wrap;
+}
+
+.play-overview__header h2,
+.play-stage__header h2 {
+  margin: 10px 0 8px;
+  font-family: "Space Grotesk", "Segoe UI", sans-serif;
+  font-size: 1.45rem;
+}
+
+.play-overview__actions {
+  display: flex;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+
+.play-stage,
+.play-sidebar {
+  display: grid;
+  gap: 16px;
+}
+
+.play-stage__header {
+  display: grid;
+  gap: 6px;
+}
+
+.play-stage__header--tight h2 {
+  margin-top: 0;
+}
+
+.play-sidebar--bottom {
+  padding-bottom: 24px;
+}
+
+.player-shell {
+  display: grid;
+  gap: 16px;
+}
+
+.grid-board-wrap {
+  width: 100%;
+  display: flex;
+  justify-content: center;
+}
+
+.grid-board {
+  display: grid;
+  gap: 2px;
+  padding: 14px;
+  border-radius: 22px;
+  background: #e3d8c1;
+  align-self: start;
+  width: 100%;
+  max-width: 100%;
+  box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.55);
+}
+
+.grid-board--solution {
+  background: #d7d1bf;
+}
+
+.grid-cell {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  min-width: 0;
+  aspect-ratio: 1 / 1;
+  border: 0;
+  padding: 0;
+  background: #fffefb;
+  color: var(--ink);
+  cursor: pointer;
+  text-transform: uppercase;
+  font-weight: 800;
+  font-size: 1.05rem;
+}
+
+.grid-cell--block {
+  background: #273636;
+  cursor: default;
+}
+
+.grid-cell--active {
+  background: #dff2ef;
+}
+
+.grid-cell--filled {
+  color: var(--accent);
+}
+
+.grid-cell--revealed {
+  color: #273636;
+  background: #fff8e9;
+}
+
+.grid-cell__number {
+  position: absolute;
+  top: 3px;
+  left: 4px;
+  font-size: 0.58rem;
+  font-weight: 700;
+  color: var(--muted);
+}
+
+.clue-list {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 18px;
+}
+
+.clue-section h3 {
+  margin: 0 0 10px;
+  font-family: "Space Grotesk", "Segoe UI", sans-serif;
+}
+
+.clue-section__list {
+  margin: 0;
+  padding-left: 0;
+  list-style: none;
+  display: grid;
+  gap: 10px;
+  max-height: 420px;
+  overflow: auto;
+  padding-right: 8px;
+}
+
+.clue-item {
+  color: var(--ink);
+  font-size: 0.97rem;
+  line-height: 1.55;
+  padding-bottom: 8px;
+  border-bottom: 1px solid rgba(215, 205, 184, 0.8);
+}
+
+.chip-row {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.chip {
+  padding: 8px 10px;
+  border-radius: 999px;
+  background: #f0e7d4;
+  color: #5f573f;
+  font-size: 0.86rem;
+}
+
+.lang-switcher {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.lang-switcher__link {
+  padding: 8px 12px;
+  border-radius: 999px;
+  border: 1px solid var(--line);
+  background: rgba(255, 255, 255, 0.66);
+  color: var(--muted);
+  font-size: 0.86rem;
+  font-weight: 700;
+}
+
+.lang-switcher__link--active {
+  background: var(--accent);
+  color: white;
+  border-color: var(--accent);
+}
+
+.contract-note {
+  border-left: 4px solid var(--accent-2);
+  padding-left: 14px;
+}
+
+.solution-topbar {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.answer-key {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 18px;
+}
+
+.answer-key__section h3 {
+  margin: 0 0 12px;
+  font-family: "Space Grotesk", "Segoe UI", sans-serif;
+}
+
+.answer-key__list {
+  margin: 0;
+  padding-left: 0;
+  list-style: none;
+  display: grid;
+  gap: 12px;
+  max-height: 420px;
+  overflow: auto;
+  padding-right: 8px;
+}
+
+.answer-key__item {
+  line-height: 1.55;
+}
+
+.answer-key__heading {
+  display: flex;
+  gap: 8px;
+  align-items: baseline;
+  flex-wrap: wrap;
+  margin-bottom: 4px;
+}
+
+.answer-key__answer {
+  font-family: "Space Grotesk", "Segoe UI", sans-serif;
+  letter-spacing: 0.04em;
+}
+
+@media (max-width: 980px) {
+  .home-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .kpi-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 640px) {
+  :root {
+    --cell: 30px;
+  }
+
+  .shell {
+    width: min(100% - 20px, 1200px);
+  }
+
+  .config-form__grid,
+  .kpi-grid,
+  .kpi-grid--play {
+    grid-template-columns: 1fr;
+  }
+
+  .play-overview__actions,
+  .solution-topbar {
+    justify-content: stretch;
+  }
+
+  .play-overview__actions .button,
+  .solution-topbar .button {
+    width: 100%;
+    text-align: center;
+  }
+}
--- a/webapp/app/layout.tsx
+++ b/webapp/app/layout.tsx
@@ -0,0 +1,19 @@
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Cruciverba Lab",
+  description: "Backoffice e UI iniziale per la generazione di cruciverba interattivi.",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="it">
+      <body>{children}</body>
+    </html>
+  );
+}
--- a/webapp/app/page.tsx
+++ b/webapp/app/page.tsx
@@ -0,0 +1,5 @@
+import { redirect } from "next/navigation";
+
+export default function RootPage() {
+  redirect("/it");
+}
--- a/webapp/components/clue-list.tsx
+++ b/webapp/components/clue-list.tsx
@@ -0,0 +1,37 @@
+import type { CrosswordResponse } from "@/lib/types";
+
+type ClueListProps = {
+  crossword: CrosswordResponse;
+  labels: {
+    across: string;
+    down: string;
+  };
+};
+
+export function ClueList({ crossword, labels }: ClueListProps) {
+  return (
+    <div className="clue-list">
+      <section className="clue-section">
+        <h3>{labels.across}</h3>
+        <ul className="clue-section__list">
+          {crossword.clues.across.map((clue) => (
+            <li className="clue-item" key={clue.entry_id}>
+              <strong>{clue.number}.</strong> {clue.text} <span className="muted">({clue.enumeration})</span>
+            </li>
+          ))}
+        </ul>
+      </section>
+
+      <section className="clue-section">
+        <h3>{labels.down}</h3>
+        <ul className="clue-section__list">
+          {crossword.clues.down.map((clue) => (
+            <li className="clue-item" key={clue.entry_id}>
+              <strong>{clue.number}.</strong> {clue.text} <span className="muted">({clue.enumeration})</span>
+            </li>
+          ))}
+        </ul>
+      </section>
+    </div>
+  );
+}
--- a/webapp/components/crossword-answer-key.tsx
+++ b/webapp/components/crossword-answer-key.tsx
@@ -0,0 +1,50 @@
+import type { CrosswordResponse } from "@/lib/types";
+
+type CrosswordAnswerKeyProps = {
+  crossword: CrosswordResponse;
+  labels: {
+    across: string;
+    down: string;
+    answer: string;
+    clue: string;
+  };
+};
+
+export function CrosswordAnswerKey({ crossword, labels }: CrosswordAnswerKeyProps) {
+  const acrossEntries = crossword.entries.filter((entry) => entry.direction === "across");
+  const downEntries = crossword.entries.filter((entry) => entry.direction === "down");
+
+  function renderEntries(entries: typeof acrossEntries) {
+    return (
+      <ol className="answer-key__list">
+        {entries.map((entry) => (
+          <li className="answer-key__item" key={entry.entry_id}>
+            <div className="answer-key__heading">
+              <strong>{entry.number}.</strong>
+              <span className="muted">{labels.answer}:</span>
+              <span className="answer-key__answer">{entry.answer}</span>
+              <span className="muted">({entry.answer_length})</span>
+            </div>
+            <p>
+              <strong>{labels.clue}:</strong> {entry.clue}
+            </p>
+          </li>
+        ))}
+      </ol>
+    );
+  }
+
+  return (
+    <div className="answer-key">
+      <section className="answer-key__section">
+        <h3>{labels.across}</h3>
+        {renderEntries(acrossEntries)}
+      </section>
+
+      <section className="answer-key__section">
+        <h3>{labels.down}</h3>
+        {renderEntries(downEntries)}
+      </section>
+    </div>
+  );
+}
--- a/webapp/components/crossword-config-form.tsx
+++ b/webapp/components/crossword-config-form.tsx
@@ -0,0 +1,183 @@
+"use client";
+
+import { startTransition, useState } from "react";
+import { useRouter } from "next/navigation";
+import type { Locale } from "@/lib/i18n";
+import type { CrosswordRequest } from "@/lib/types";
+
+const DEFAULTS = {
+  topic: "transport",
+  difficulty: "medium",
+  initialWordCount: 19,
+  themedFillCount: 10,
+  targetEmptyRatio: 0.1667,
+  seed: 2,
+  lexiconFile: "lexicon_it_curated_llm_aggressive.json",
+};
+
+type CrosswordConfigFormProps = {
+  locale: Locale;
+  dict: {
+    topic: string;
+    difficulty: string;
+    initialWords: string;
+    themedFillCount: string;
+    targetEmptyRatio: string;
+    seed: string;
+    lexiconFile: string;
+    submit: string;
+    submitting: string;
+    note: string;
+  };
+};
+
+export function CrosswordConfigForm({ locale, dict }: CrosswordConfigFormProps) {
+  const router = useRouter();
+  const [topic, setTopic] = useState(DEFAULTS.topic);
+  const [difficulty, setDifficulty] = useState(DEFAULTS.difficulty);
+  const [initialWordCount, setInitialWordCount] = useState(DEFAULTS.initialWordCount);
+  const [themedFillCount, setThemedFillCount] = useState(DEFAULTS.themedFillCount);
+  const [targetEmptyRatio, setTargetEmptyRatio] = useState(DEFAULTS.targetEmptyRatio);
+  const [seed, setSeed] = useState(DEFAULTS.seed);
+  const [lexiconFile, setLexiconFile] = useState(DEFAULTS.lexiconFile);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [errorMessage, setErrorMessage] = useState("");
+
+  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setIsSubmitting(true);
+    setErrorMessage("");
+
+    const requestPayload: CrosswordRequest = {
+      schema_version: "1.0",
+      request_id: `req-${Date.now()}`,
+      requested_at: new Date().toISOString(),
+      generator: {
+        topic: topic
+          .split(",")
+          .map((item) => item.trim())
+          .filter(Boolean),
+        difficulty,
+        seed,
+        initial_word_count: initialWordCount,
+        themed_fill_count: themedFillCount,
+        target_empty_ratio: targetEmptyRatio,
+        diffxy: 7,
+        time_limit_seconds: 8,
+        max_candidates_per_word: 12,
+        lexicon_file: lexiconFile,
+        definitions_enabled: true,
+        definition_style: "classic",
+        preferred_output_language: locale,
+      },
+    };
+
+    try {
+      const response = await fetch("/api/crosswords/generate", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(requestPayload),
+      });
+
+      if (!response.ok) {
+        const errorPayload = await response.json().catch(() => ({}));
+        throw new Error(errorPayload.message || "Unable to generate crossword");
+      }
+
+      const generated = await response.json();
+
+      startTransition(() => {
+        router.push(`/${locale}/crosswords/${generated.crossword_id}`);
+      });
+    } catch (error) {
+      setErrorMessage(error instanceof Error ? error.message : "Unexpected error");
+      setIsSubmitting(false);
+    }
+  }
+
+  return (
+    <form className="config-form" onSubmit={handleSubmit}>
+      <div className="config-form__grid">
+        <div className="field">
+          <label htmlFor="topic">{dict.topic}</label>
+          <input id="topic" value={topic} onChange={(event) => setTopic(event.target.value)} />
+        </div>
+
+        <div className="field">
+          <label htmlFor="difficulty">{dict.difficulty}</label>
+          <select
+            id="difficulty"
+            value={difficulty}
+            onChange={(event) => setDifficulty(event.target.value)}
+          >
+            <option value="easy">easy</option>
+            <option value="medium">medium</option>
+            <option value="hard">hard</option>
+            <option value="expert">expert</option>
+          </select>
+        </div>
+
+        <div className="field">
+          <label htmlFor="initialWordCount">{dict.initialWords}</label>
+          <input
+            id="initialWordCount"
+            type="number"
+            value={initialWordCount}
+            onChange={(event) => setInitialWordCount(Number(event.target.value))}
+          />
+        </div>
+
+        <div className="field">
+          <label htmlFor="themedFillCount">{dict.themedFillCount}</label>
+          <input
+            id="themedFillCount"
+            type="number"
+            value={themedFillCount}
+            onChange={(event) => setThemedFillCount(Number(event.target.value))}
+          />
+        </div>
+
+        <div className="field">
+          <label htmlFor="targetEmptyRatio">{dict.targetEmptyRatio}</label>
+          <input
+            id="targetEmptyRatio"
+            type="number"
+            step="0.0001"
+            value={targetEmptyRatio}
+            onChange={(event) => setTargetEmptyRatio(Number(event.target.value))}
+          />
+        </div>
+
+        <div className="field">
+          <label htmlFor="seed">{dict.seed}</label>
+          <input
+            id="seed"
+            type="number"
+            value={seed}
+            onChange={(event) => setSeed(Number(event.target.value))}
+          />
+        </div>
+      </div>
+
+      <div className="field">
+        <label htmlFor="lexiconFile">{dict.lexiconFile}</label>
+        <input
+          id="lexiconFile"
+          value={lexiconFile}
+          onChange={(event) => setLexiconFile(event.target.value)}
+        />
+      </div>
+
+      <div className="actions">
+        <button className="button" type="submit" disabled={isSubmitting}>
+          {isSubmitting ? dict.submitting : dict.submit}
+        </button>
+        <span className="muted">{dict.note}</span>
+      </div>
+
+      {errorMessage ? <p className="form-error">{errorMessage}</p> : null}
+    </form>
+  );
+}
--- a/webapp/components/crossword-player.tsx
+++ b/webapp/components/crossword-player.tsx
@@ -0,0 +1,113 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import type { CrosswordResponse } from "@/lib/types";
+
+type CrosswordPlayerProps = {
+  crossword: CrosswordResponse;
+  labels: {
+    topic: string;
+    difficulty: string;
+    lexicon: string;
+  };
+  readOnly?: boolean;
+  revealSolution?: boolean;
+};
+
+type CellState = Record<string, string>;
+
+function cellKey(row: number, col: number) {
+  return `${row}:${col}`;
+}
+
+export function CrosswordPlayer({
+  crossword,
+  labels,
+  readOnly = false,
+  revealSolution = false,
+}: CrosswordPlayerProps) {
+  const [activeCell, setActiveCell] = useState<string | null>(null);
+  const [letters, setLetters] = useState<CellState>({});
+
+  useEffect(() => {
+    const firstCell = crossword.grid.cells.find((cell) => cell.kind === "letter");
+    if (firstCell) {
+      setActiveCell(cellKey(firstCell.row, firstCell.col));
+    }
+  }, [crossword]);
+
+  function writeLetter(row: number, col: number, value: string) {
+    const normalized = value.slice(-1).toUpperCase();
+    setLetters((current) => ({
+      ...current,
+      [cellKey(row, col)]: normalized,
+    }));
+  }
+
+  return (
+    <div className="player-shell">
+      <div className="chip-row">
+        <span className="chip">{labels.topic}: {crossword.generator.topic.join(", ")}</span>
+        <span className="chip">{labels.difficulty}: {crossword.generator.difficulty}</span>
+        <span className="chip">{labels.lexicon}: {crossword.generator.runtime_lexicon}</span>
+      </div>
+
+      <div className="grid-board-wrap">
+        <div
+          className={`grid-board ${revealSolution ? "grid-board--solution" : ""}`}
+          style={{
+            gridTemplateColumns: `repeat(${crossword.grid.cols}, minmax(0, 1fr))`,
+          }}
+        >
+          {crossword.grid.cells.map((cell) => {
+            const key = cellKey(cell.row, cell.col);
+            if (cell.kind === "block") {
+              return <div className="grid-cell grid-cell--block" key={key} />;
+            }
+
+            const currentValue = revealSolution ? cell.solution ?? "" : letters[key] ?? "";
+            const isActive = activeCell === key;
+            const className = [
+              "grid-cell",
+              isActive && !readOnly ? "grid-cell--active" : "",
+              currentValue ? "grid-cell--filled" : "",
+              revealSolution ? "grid-cell--revealed" : "",
+            ]
+              .filter(Boolean)
+              .join(" ");
+
+            if (readOnly) {
+              return (
+                <div className={className} key={key}>
+                  {cell.number ? <span className="grid-cell__number">{cell.number}</span> : null}
+                  {currentValue}
+                </div>
+              );
+            }
+
+            return (
+              <button
+                aria-label={`Cell ${cell.row + 1}, ${cell.col + 1}`}
+                className={className}
+                key={key}
+                onClick={() => setActiveCell(key)}
+                onKeyDown={(event) => {
+                  if (/^[a-zA-Z]$/.test(event.key)) {
+                    writeLetter(cell.row, cell.col, event.key);
+                  }
+                  if (event.key === "Backspace") {
+                    writeLetter(cell.row, cell.col, "");
+                  }
+                }}
+                type="button"
+              >
+                {cell.number ? <span className="grid-cell__number">{cell.number}</span> : null}
+                {currentValue}
+              </button>
+            );
+          })}
+        </div>
+      </div>
+    </div>
+  );
+}
--- a/webapp/components/crossword-runtime-page.tsx
+++ b/webapp/components/crossword-runtime-page.tsx
@@ -0,0 +1,110 @@
+"use client";
+
+import Link from "next/link";
+import { ClueList } from "@/components/clue-list";
+import { CrosswordPlayer } from "@/components/crossword-player";
+import { useCrosswordData } from "@/components/use-crossword-data";
+import type { Locale } from "@/lib/i18n";
+
+type CrosswordRuntimePageProps = {
+  id: string;
+  locale: Locale;
+  labels: {
+    player: {
+      topic: string;
+      difficulty: string;
+      lexicon: string;
+    };
+    clues: {
+      across: string;
+      down: string;
+    };
+    play: {
+      overviewTitle: string;
+      boardTitle: string;
+      cluesTitle: string;
+      instructions: string;
+      actions: {
+        newCrossword: string;
+        viewSolution: string;
+      };
+      stats: {
+        words: string;
+        intersections: string;
+        filledCells: string;
+        topicWords: string;
+      };
+    };
+    loading: string;
+    errorPrefix: string;
+  };
+};
+
+export function CrosswordRuntimePage({ id, locale, labels }: CrosswordRuntimePageProps) {
+  const { crossword, errorMessage, isLoading } = useCrosswordData(id, locale);
+
+  if (errorMessage) {
+    return <p className="form-error">{labels.errorPrefix}: {errorMessage}</p>;
+  }
+
+  if (isLoading || !crossword) {
+    return <p className="muted">{labels.loading}</p>;
+  }
+
+  return (
+    <section className="stack">
+      <div className="card play-overview">
+        <div className="play-overview__header">
+          <div>
+            <span className="hero__badge hero__badge--soft">{crossword.summary.title}</span>
+            <h2>{labels.play.overviewTitle}</h2>
+            <p className="muted">{labels.play.instructions}</p>
+          </div>
+          <div className="play-overview__actions">
+            <Link className="button" href={`/${locale}/new`}>
+              {labels.play.actions.newCrossword}
+            </Link>
+            <Link className="button button--secondary" href={`/${locale}/crosswords/${id}/solution`}>
+              {labels.play.actions.viewSolution}
+            </Link>
+          </div>
+        </div>
+
+        <div className="kpi-grid kpi-grid--play">
+          <div className="kpi">
+            <span className="muted">{labels.play.stats.words}</span>
+            <strong>{crossword.summary.total_words}</strong>
+          </div>
+          <div className="kpi">
+            <span className="muted">{labels.play.stats.intersections}</span>
+            <strong>{crossword.summary.intersections}</strong>
+          </div>
+          <div className="kpi">
+            <span className="muted">{labels.play.stats.filledCells}</span>
+            <strong>{crossword.diagnostics.filled_cells}</strong>
+          </div>
+          <div className="kpi">
+            <span className="muted">{labels.play.stats.topicWords}</span>
+            <strong>{crossword.diagnostics.topic_words}</strong>
+          </div>
+        </div>
+      </div>
+
+      <div className="card play-stage">
+        <div className="play-stage__header">
+          <h2>{labels.play.boardTitle}</h2>
+          <p className="muted">{crossword.summary.subtitle}</p>
+        </div>
+        <CrosswordPlayer crossword={crossword} labels={labels.player} />
+      </div>
+
+      <section className="card play-sidebar play-sidebar--bottom">
+        <div className="play-stage__header play-stage__header--tight">
+          <h2>{labels.play.cluesTitle}</h2>
+          <p className="muted">{crossword.summary.title}</p>
+        </div>
+        <ClueList crossword={crossword} labels={labels.clues} />
+      </section>
+    </section>
+  );
+}
--- a/webapp/components/crossword-solution-runtime-page.tsx
+++ b/webapp/components/crossword-solution-runtime-page.tsx
@@ -0,0 +1,87 @@
+"use client";
+
+import Link from "next/link";
+import { CrosswordAnswerKey } from "@/components/crossword-answer-key";
+import { CrosswordPlayer } from "@/components/crossword-player";
+import { useCrosswordData } from "@/components/use-crossword-data";
+import type { Locale } from "@/lib/i18n";
+
+type CrosswordSolutionRuntimePageProps = {
+  id: string;
+  locale: Locale;
+  labels: {
+    player: {
+      topic: string;
+      difficulty: string;
+      lexicon: string;
+    };
+    clues: {
+      across: string;
+      down: string;
+    };
+    solution: {
+      solvedGridTitle: string;
+      answersTitle: string;
+      backToGame: string;
+      answer: string;
+      clue: string;
+    };
+    loading: string;
+    errorPrefix: string;
+  };
+};
+
+export function CrosswordSolutionRuntimePage({
+  id,
+  locale,
+  labels,
+}: CrosswordSolutionRuntimePageProps) {
+  const { crossword, errorMessage, isLoading } = useCrosswordData(id, locale);
+
+  if (errorMessage) {
+    return <p className="form-error">{labels.errorPrefix}: {errorMessage}</p>;
+  }
+
+  if (isLoading || !crossword) {
+    return <p className="muted">{labels.loading}</p>;
+  }
+
+  return (
+    <section className="stack">
+      <div className="card solution-topbar">
+        <Link className="button button--secondary" href={`/${locale}/crosswords/${id}`}>
+          {labels.solution.backToGame}
+        </Link>
+      </div>
+
+      <div className="card play-stage">
+        <div className="play-stage__header">
+          <h2>{labels.solution.solvedGridTitle}</h2>
+          <p className="muted">{crossword.summary.title}</p>
+        </div>
+        <CrosswordPlayer
+          crossword={crossword}
+          labels={labels.player}
+          readOnly
+          revealSolution
+        />
+      </div>
+
+      <section className="card play-sidebar play-sidebar--bottom">
+        <div className="play-stage__header play-stage__header--tight">
+          <h2>{labels.solution.answersTitle}</h2>
+          <p className="muted">{crossword.summary.subtitle}</p>
+        </div>
+        <CrosswordAnswerKey
+          crossword={crossword}
+          labels={{
+            across: labels.clues.across,
+            down: labels.clues.down,
+            answer: labels.solution.answer,
+            clue: labels.solution.clue,
+          }}
+        />
+      </section>
+    </section>
+  );
+}
--- a/webapp/components/language-switcher.tsx
+++ b/webapp/components/language-switcher.tsx
@@ -0,0 +1,29 @@
+import Link from "next/link";
+import { LOCALES, type Locale } from "@/lib/i18n";
+
+type LanguageSwitcherProps = {
+  locale: Locale;
+  path?: string;
+};
+
+const LABELS: Record<Locale, string> = {
+  it: "Italiano",
+  en: "English",
+  es: "Espanol",
+};
+
+export function LanguageSwitcher({ locale, path = "" }: LanguageSwitcherProps) {
+  return (
+    <nav aria-label="Language switcher" className="lang-switcher">
+      {LOCALES.map((item) => (
+        <Link
+          className={`lang-switcher__link ${item === locale ? "lang-switcher__link--active" : ""}`}
+          href={`/${item}${path}`}
+          key={item}
+        >
+          {LABELS[item]}
+        </Link>
+      ))}
+    </nav>
+  );
+}
--- a/webapp/components/use-crossword-data.ts
+++ b/webapp/components/use-crossword-data.ts
@@ -0,0 +1,61 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { getMockCrosswordResponse } from "@/lib/mock-crossword";
+import type { Locale } from "@/lib/i18n";
+import type { CrosswordResponse } from "@/lib/types";
+
+type UseCrosswordDataResult = {
+  crossword: CrosswordResponse | null;
+  errorMessage: string;
+  isLoading: boolean;
+};
+
+export function useCrosswordData(id: string, locale: Locale): UseCrosswordDataResult {
+  const [crossword, setCrossword] = useState<CrosswordResponse | null>(
+    id === "demo-transport" ? getMockCrosswordResponse(locale) : null,
+  );
+  const [errorMessage, setErrorMessage] = useState("");
+  const [isLoading, setIsLoading] = useState(id !== "demo-transport");
+
+  useEffect(() => {
+    if (id === "demo-transport") {
+      setIsLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setIsLoading(true);
+    setErrorMessage("");
+
+    fetch(`/api/crosswords/${id}`)
+      .then(async (response) => {
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`);
+        }
+        return response.json();
+      })
+      .then((payload: CrosswordResponse) => {
+        if (!cancelled) {
+          setCrossword(payload);
+          setIsLoading(false);
+        }
+      })
+      .catch((error) => {
+        if (!cancelled) {
+          setErrorMessage(error instanceof Error ? error.message : "Unexpected error");
+          setIsLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [id, locale]);
+
+  return {
+    crossword,
+    errorMessage,
+    isLoading,
+  };
+}
--- a/webapp/lib/i18n.ts
+++ b/webapp/lib/i18n.ts
@@ -0,0 +1,338 @@
+export const LOCALES = ["it", "en", "es"] as const;
+export type Locale = (typeof LOCALES)[number];
+
+export function isLocale(value: string): value is Locale {
+  return LOCALES.includes(value as Locale);
+}
+
+type Dictionary = {
+  home: {
+    badge: string;
+    title: string;
+    subtitle: string;
+    requestTitle: string;
+    requestText: string;
+    structureTitle: string;
+    structureText: string;
+    structureChips: string[];
+    demoTitle: string;
+    openDemo: string;
+    openConfig: string;
+    kpis: {
+      words: string;
+      intersections: string;
+      rows: string;
+      cols: string;
+    };
+  };
+  newPage: {
+    badge: string;
+    title: string;
+    subtitle: string;
+  };
+  form: {
+    topic: string;
+    difficulty: string;
+    initialWords: string;
+    themedFillCount: string;
+    targetEmptyRatio: string;
+    seed: string;
+    lexiconFile: string;
+    submit: string;
+    submitting: string;
+    note: string;
+  };
+  play: {
+    badge: string;
+    subtitle: string;
+    loading: string;
+    errorPrefix: string;
+    overviewTitle: string;
+    boardTitle: string;
+    cluesTitle: string;
+    instructions: string;
+    actions: {
+      newCrossword: string;
+      viewSolution: string;
+    };
+    stats: {
+      words: string;
+      intersections: string;
+      filledCells: string;
+      topicWords: string;
+    };
+  };
+  solution: {
+    badge: string;
+    title: string;
+    subtitle: string;
+    solvedGridTitle: string;
+    answersTitle: string;
+    backToGame: string;
+    answer: string;
+    clue: string;
+  };
+  player: {
+    topic: string;
+    difficulty: string;
+    lexicon: string;
+  };
+  clues: {
+    across: string;
+    down: string;
+  };
+};
+
+const dictionaries: Record<Locale, Dictionary> = {
+  it: {
+    home: {
+      badge: "Alpha 01 Backoffice + Web UI",
+      title: "Cruciverba su richiesta, pronti per essere giocati.",
+      subtitle:
+        "Questa prima interfaccia Next.js separa nettamente il motore Python dal frontend: il sito invia una richiesta JSON, il backend genera il cruciverba e la pagina finale lo rende giocabile in modo interattivo.",
+      requestTitle: "Nuova richiesta",
+      requestText:
+        "Qui l'utente configurerà il cruciverba. Per ora il form prepara già la struttura della richiesta e apre la pagina del gioco reale.",
+      structureTitle: "Perche questa struttura",
+      structureText:
+        "Il frontend non deve conoscere i dettagli dell'algoritmo: riceve solo il JSON finale del cruciverba e lo trasforma in esperienza giocabile, stampabile e riapribile.",
+      structureChips: ["Next.js UI", "Backend JSON", "Motore Python separato", "PDF e mobile-ready"],
+      demoTitle: "Stato demo",
+      openDemo: "Apri demo giocabile",
+      openConfig: "Vai alla configurazione",
+      kpis: {
+        words: "Parole",
+        intersections: "Intersezioni",
+        rows: "Righe",
+        cols: "Colonne",
+      },
+    },
+    newPage: {
+      badge: "Configurazione",
+      title: "Chiedi al motore un nuovo cruciverba.",
+      subtitle:
+        "Questa pagina e il punto naturale da cui il sito invierà al backend la request JSON del contratto che abbiamo definito.",
+    },
+    form: {
+      topic: "Topic",
+      difficulty: "Difficolta",
+      initialWords: "Parole seme",
+      themedFillCount: "Parole filler in tema",
+      targetEmptyRatio: "Rapporto vuoti",
+      seed: "Seed",
+      lexiconFile: "Lessico runtime",
+      submit: "Genera cruciverba",
+      submitting: "Preparazione...",
+      note: "La richiesta ora chiama davvero il motore Python e apre il cruciverba generato.",
+    },
+    play: {
+      badge: "Cruciverba interattivo",
+      subtitle: "Questa pagina carica il JSON reale generato dal motore Python del backoffice.",
+      loading: "Generazione in corso, sto caricando il cruciverba...",
+      errorPrefix: "Errore di caricamento",
+      overviewTitle: "Schema pronto per essere giocato",
+      boardTitle: "Griglia di gioco",
+      cluesTitle: "Definizioni",
+      instructions:
+        "Clicca una casella, poi scrivi da tastiera. Le definizioni restano leggibili nella colonna laterale.",
+      actions: {
+        newCrossword: "Nuovo cruciverba",
+        viewSolution: "Vedi soluzioni",
+      },
+      stats: {
+        words: "Parole",
+        intersections: "Intersezioni",
+        filledCells: "Caselle piene",
+        topicWords: "Parole in tema",
+      },
+    },
+    solution: {
+      badge: "Pagina soluzioni",
+      title: "Controllo finale del cruciverba",
+      subtitle:
+        "Qui trovi la griglia compilata e l'elenco completo delle risposte collegate alle definizioni.",
+      solvedGridTitle: "Griglia risolta",
+      answersTitle: "Elenco soluzioni",
+      backToGame: "Torna al gioco",
+      answer: "Soluzione",
+      clue: "Definizione",
+    },
+    player: {
+      topic: "Topic",
+      difficulty: "Difficolta",
+      lexicon: "Lessico",
+    },
+    clues: {
+      across: "Orizzontali",
+      down: "Verticali",
+    },
+  },
+  en: {
+    home: {
+      badge: "Alpha 01 Backoffice + Web UI",
+      title: "Crosswords on demand, ready to be played.",
+      subtitle:
+        "This first Next.js interface clearly separates the Python engine from the frontend: the site sends a JSON request, the backend generates the crossword, and the final page turns it into an interactive experience.",
+      requestTitle: "New request",
+      requestText:
+        "This is where the user configures the crossword. The form already prepares the request structure and opens the real game page.",
+      structureTitle: "Why this structure",
+      structureText:
+        "The frontend should not know the details of the algorithm: it only receives the final crossword JSON and turns it into a playable, printable and reusable experience.",
+      structureChips: ["Next.js UI", "JSON backend", "Separate Python engine", "PDF and mobile-ready"],
+      demoTitle: "Demo status",
+      openDemo: "Open playable demo",
+      openConfig: "Go to configuration",
+      kpis: {
+        words: "Words",
+        intersections: "Intersections",
+        rows: "Rows",
+        cols: "Columns",
+      },
+    },
+    newPage: {
+      badge: "Configuration",
+      title: "Ask the engine for a new crossword.",
+      subtitle:
+        "This page is the natural place from which the site sends the JSON request defined in our contract to the backend.",
+    },
+    form: {
+      topic: "Topic",
+      difficulty: "Difficulty",
+      initialWords: "Seed words",
+      themedFillCount: "Themed filler words",
+      targetEmptyRatio: "Empty ratio",
+      seed: "Seed",
+      lexiconFile: "Runtime lexicon",
+      submit: "Generate crossword",
+      submitting: "Preparing...",
+      note: "The request now calls the real Python engine and opens the generated crossword.",
+    },
+    play: {
+      badge: "Interactive crossword",
+      subtitle: "This page loads the real JSON generated by the Python backoffice engine.",
+      loading: "Generation in progress, loading crossword...",
+      errorPrefix: "Loading error",
+      overviewTitle: "Crossword ready to be played",
+      boardTitle: "Game grid",
+      cluesTitle: "Clues",
+      instructions: "Click a cell, then type from the keyboard. The clues stay readable in the side panel.",
+      actions: {
+        newCrossword: "New crossword",
+        viewSolution: "View solutions",
+      },
+      stats: {
+        words: "Words",
+        intersections: "Intersections",
+        filledCells: "Filled cells",
+        topicWords: "Theme words",
+      },
+    },
+    solution: {
+      badge: "Solutions page",
+      title: "Final crossword check",
+      subtitle: "Here you can inspect the solved grid and the full list of answers tied to each clue.",
+      solvedGridTitle: "Solved grid",
+      answersTitle: "Answer key",
+      backToGame: "Back to game",
+      answer: "Answer",
+      clue: "Clue",
+    },
+    player: {
+      topic: "Topic",
+      difficulty: "Difficulty",
+      lexicon: "Lexicon",
+    },
+    clues: {
+      across: "Across",
+      down: "Down",
+    },
+  },
+  es: {
+    home: {
+      badge: "Alpha 01 Backoffice + Web UI",
+      title: "Crucigramas a pedido, listos para jugar.",
+      subtitle:
+        "Esta primera interfaz en Next.js separa claramente el motor Python del frontend: el sitio envia una solicitud JSON, el backend genera el crucigrama y la pagina final lo convierte en una experiencia interactiva.",
+      requestTitle: "Nueva solicitud",
+      requestText:
+        "Aqui el usuario configura el crucigrama. El formulario ya prepara la estructura de la solicitud y abre la pagina del juego real.",
+      structureTitle: "Por que esta estructura",
+      structureText:
+        "El frontend no debe conocer los detalles del algoritmo: solo recibe el JSON final del crucigrama y lo transforma en una experiencia jugable, imprimible y reutilizable.",
+      structureChips: ["Next.js UI", "Backend JSON", "Motor Python separado", "PDF y movil listos"],
+      demoTitle: "Estado de la demo",
+      openDemo: "Abrir demo jugable",
+      openConfig: "Ir a configuracion",
+      kpis: {
+        words: "Palabras",
+        intersections: "Intersecciones",
+        rows: "Filas",
+        cols: "Columnas",
+      },
+    },
+    newPage: {
+      badge: "Configuracion",
+      title: "Pide al motor un nuevo crucigrama.",
+      subtitle:
+        "Esta pagina es el punto natural desde el que el sitio enviara al backend la solicitud JSON del contrato que hemos definido.",
+    },
+    form: {
+      topic: "Tema",
+      difficulty: "Dificultad",
+      initialWords: "Palabras semilla",
+      themedFillCount: "Palabras de relleno tematico",
+      targetEmptyRatio: "Proporcion de vacios",
+      seed: "Semilla",
+      lexiconFile: "Lexico activo",
+      submit: "Generar crucigrama",
+      submitting: "Preparando...",
+      note: "La solicitud ahora llama de verdad al motor Python y abre el crucigrama generado.",
+    },
+    play: {
+      badge: "Crucigrama interactivo",
+      subtitle: "Esta pagina carga el JSON real generado por el motor Python del backoffice.",
+      loading: "Generacion en curso, cargando crucigrama...",
+      errorPrefix: "Error de carga",
+      overviewTitle: "Crucigrama listo para jugar",
+      boardTitle: "Cuadricula de juego",
+      cluesTitle: "Definiciones",
+      instructions:
+        "Haz clic en una casilla y escribe desde el teclado. Las definiciones siguen legibles en la columna lateral.",
+      actions: {
+        newCrossword: "Nuevo crucigrama",
+        viewSolution: "Ver soluciones",
+      },
+      stats: {
+        words: "Palabras",
+        intersections: "Intersecciones",
+        filledCells: "Casillas llenas",
+        topicWords: "Palabras tematicas",
+      },
+    },
+    solution: {
+      badge: "Pagina de soluciones",
+      title: "Revision final del crucigrama",
+      subtitle:
+        "Aqui puedes ver la cuadricula completa y la lista de respuestas asociadas a cada definicion.",
+      solvedGridTitle: "Cuadricula resuelta",
+      answersTitle: "Listado de soluciones",
+      backToGame: "Volver al juego",
+      answer: "Solucion",
+      clue: "Definicion",
+    },
+    player: {
+      topic: "Tema",
+      difficulty: "Dificultad",
+      lexicon: "Lexico",
+    },
+    clues: {
+      across: "Horizontales",
+      down: "Verticales",
+    },
+  },
+};
+
+export function getDictionary(locale: Locale): Dictionary {
+  return dictionaries[locale];
+}
--- a/webapp/lib/mock-crossword.ts
+++ b/webapp/lib/mock-crossword.ts
@@ -0,0 +1,276 @@
+import type { Locale } from "@/lib/i18n";
+import type { CrosswordResponse } from "@/lib/types";
+
+function buildCells(solutionRows: string[]) {
+  const cells = [];
+  const numbering = new Map<string, number>([
+    ["0:0", 1],
+    ["0:9", 2],
+    ["2:0", 3],
+    ["4:0", 4],
+    ["4:6", 5],
+    ["6:0", 6],
+  ]);
+
+  for (let row = 0; row < solutionRows.length; row += 1) {
+    for (let col = 0; col < solutionRows[row].length; col += 1) {
+      const char = solutionRows[row][col];
+      if (char === "#") {
+        cells.push({
+          row,
+          col,
+          kind: "block" as const,
+          solution: null,
+          display: null,
+          number: null,
+          across_entry_id: null,
+          down_entry_id: null,
+          is_prefilled: false,
+        });
+        continue;
+      }
+
+      cells.push({
+        row,
+        col,
+        kind: "letter" as const,
+        solution: char,
+        display: "",
+        number: numbering.get(`${row}:${col}`) ?? null,
+        across_entry_id: null,
+        down_entry_id: null,
+        is_prefilled: false,
+      });
+    }
+  }
+
+  return cells;
+}
+
+const solutionRows = [
+  "AMBU#####PI",
+  "L###T#####S",
+  "TRENO#####T",
+  "A###R#####A",
+  "NAVE##MOTO#",
+  "Z###R###O##",
+  "AEROPORTO##",
+  "######R#####",
+];
+
+const titles: Record<Locale, string> = {
+  it: "Cruciverba a tema trasporti",
+  en: "Transport-themed crossword",
+  es: "Crucigrama sobre transportes",
+};
+
+const subtitles: Record<Locale, string> = {
+  it: "Demo iniziale dell'interfaccia web",
+  en: "Initial demo of the web interface",
+  es: "Demo inicial de la interfaz web",
+};
+
+const clueTexts: Record<Locale, string[]> = {
+  it: [
+    "Inizio di un mezzo di soccorso stradale e sanitario.",
+    "Superficie destinata al decollo e all'atterraggio.",
+    "Mezzo di trasporto che corre su rotaie.",
+    "Grande mezzo per viaggiare sul mare.",
+    "Veicolo a due ruote con motore.",
+    "Complesso destinato al traffico degli aerei.",
+  ],
+  en: [
+    "Opening of a road and medical rescue vehicle.",
+    "Surface used for takeoff and landing.",
+    "Means of transport that runs on rails.",
+    "Large vehicle used to travel by sea.",
+    "Two-wheeled motor vehicle.",
+    "Facility dedicated to airplane traffic.",
+  ],
+  es: [
+    "Inicio de un vehículo de socorro vial y sanitario.",
+    "Superficie destinada al despegue y aterrizaje.",
+    "Medio de transporte que circula sobre rieles.",
+    "Gran vehículo para viajar por mar.",
+    "Vehículo de dos ruedas con motor.",
+    "Complejo destinado al tráfico de aviones.",
+  ],
+};
+
+const baseEntries = [
+  {
+    entry_id: "A1",
+    number: 1,
+    direction: "across" as const,
+    answer: "AMBU",
+    answer_length: 4,
+    row: 0,
+    col: 0,
+    cells: [[0, 0], [0, 1], [0, 2], [0, 3]] as [number, number][],
+    clue_source: "demo",
+    topics: ["transport", "health"],
+    pos: "NOUN",
+    is_seed: true,
+    added_by_filler: false,
+    confidence: 0.8,
+  },
+  {
+    entry_id: "A2",
+    number: 2,
+    direction: "across" as const,
+    answer: "PISTA",
+    answer_length: 5,
+    row: 0,
+    col: 9,
+    cells: [[0, 9], [0, 10], [0, 11], [1, 11], [2, 11]] as [number, number][],
+    clue_source: "semantic_definition",
+    topics: ["transport", "aviation"],
+    pos: "NOUN",
+    is_seed: false,
+    added_by_filler: true,
+    confidence: 0.94,
+  },
+  {
+    entry_id: "A3",
+    number: 3,
+    direction: "across" as const,
+    answer: "TRENO",
+    answer_length: 5,
+    row: 2,
+    col: 0,
+    cells: [[2, 0], [2, 1], [2, 2], [2, 3], [2, 4]] as [number, number][],
+    clue_source: "semantic_definition",
+    topics: ["transport"],
+    pos: "NOUN",
+    is_seed: true,
+    added_by_filler: false,
+    confidence: 0.98,
+  },
+  {
+    entry_id: "A4",
+    number: 4,
+    direction: "across" as const,
+    answer: "NAVE",
+    answer_length: 4,
+    row: 4,
+    col: 0,
+    cells: [[4, 0], [4, 1], [4, 2], [4, 3]] as [number, number][],
+    clue_source: "semantic_definition",
+    topics: ["transport", "sea"],
+    pos: "NOUN",
+    is_seed: true,
+    added_by_filler: false,
+    confidence: 0.96,
+  },
+  {
+    entry_id: "A5",
+    number: 5,
+    direction: "across" as const,
+    answer: "MOTO",
+    answer_length: 4,
+    row: 4,
+    col: 6,
+    cells: [[4, 6], [4, 7], [4, 8], [4, 9]] as [number, number][],
+    clue_source: "semantic_definition",
+    topics: ["transport"],
+    pos: "NOUN",
+    is_seed: true,
+    added_by_filler: false,
+    confidence: 0.95,
+  },
+  {
+    entry_id: "A6",
+    number: 6,
+    direction: "across" as const,
+    answer: "AEROPORTO",
+    answer_length: 9,
+    row: 6,
+    col: 0,
+    cells: [[6, 0], [6, 1], [6, 2], [6, 3], [6, 4], [6, 5], [6, 6], [6, 7], [6, 8]] as [number, number][],
+    clue_source: "semantic_definition",
+    topics: ["transport", "aviation"],
+    pos: "NOUN",
+    is_seed: true,
+    added_by_filler: false,
+    confidence: 0.97,
+  },
+];
+
+export function getMockCrosswordResponse(locale: Locale): CrosswordResponse {
+  const texts = clueTexts[locale];
+  const entries = baseEntries.map((entry, index) => ({
+    ...entry,
+    clue: texts[index],
+  }));
+
+  return {
+    schema_version: "1.0",
+    request_id: "req-demo-transport",
+    crossword_id: "demo-transport",
+    generated_at: "2026-04-29T11:30:00+02:00",
+    status: "ok",
+    generator: {
+      topic: ["transport"],
+      difficulty: "medium",
+      seed: 2,
+      runtime_lexicon: "lexicon_it_curated_llm_aggressive.json",
+    },
+    summary: {
+      title: titles[locale],
+      subtitle: subtitles[locale],
+      rows: solutionRows.length,
+      cols: solutionRows[0].length,
+      total_words: 6,
+      intersections: 8,
+    },
+    grid: {
+      rows: solutionRows.length,
+      cols: solutionRows[0].length,
+      cell_size_hint: 42,
+      cells: buildCells(solutionRows),
+    },
+    entries,
+    clues: {
+      across: entries.map((entry) => ({
+        number: entry.number,
+        entry_id: entry.entry_id,
+        text: entry.clue,
+        enumeration: entry.answer_length,
+        topic_match: true,
+        source: entry.clue_source,
+      })),
+      down: [],
+    },
+    solution: {
+      grid_rows: solutionRows,
+      words: ["AMBU", "PISTA", "TRENO", "NAVE", "MOTO", "AEROPORTO"],
+    },
+    diagnostics: {
+      seed_words_requested: 19,
+      seed_words_placed: 19,
+      filler_words_added: 1,
+      filled_cells: 35,
+      empty_cells: 61,
+      empty_ratio: 0.6354,
+      target_empty_ratio: 0.1667,
+      topic_words: 6,
+      off_topic_words: 0,
+      pos_counts: {
+        sostantivi: 6,
+        aggettivi: 0,
+        verbi: 0,
+        avverbi: 0,
+        preposizioni: 0,
+        congiunzioni: 0,
+        altri: 0,
+      },
+      generation_seconds: 11.4,
+    },
+    artifacts: {
+      pdf_player: null,
+      pdf_solution: null,
+      thumbnail: null,
+      html_preview: null,
+    },
+  };
+}
--- a/webapp/lib/types.ts
+++ b/webapp/lib/types.ts
@@ -0,0 +1,115 @@
+export type CrosswordRequest = {
+  schema_version: string;
+  request_id: string;
+  requested_at: string;
+  generator: {
+    topic: string[];
+    difficulty: string;
+    seed: number | null;
+    initial_word_count: number;
+    themed_fill_count: number;
+    target_empty_ratio: number;
+    diffxy: number;
+    time_limit_seconds: number;
+    max_candidates_per_word: number;
+    lexicon_file: string;
+    definitions_enabled: boolean;
+    definition_style: string;
+    preferred_output_language: string;
+  };
+};
+
+export type CrosswordCell = {
+  row: number;
+  col: number;
+  kind: "letter" | "block";
+  solution: string | null;
+  display: string | null;
+  number: number | null;
+  across_entry_id: string | null;
+  down_entry_id: string | null;
+  is_prefilled: boolean;
+};
+
+export type CrosswordClue = {
+  number: number;
+  entry_id: string;
+  text: string;
+  enumeration: number;
+  topic_match: boolean;
+  source: string;
+};
+
+export type CrosswordEntry = {
+  entry_id: string;
+  number: number;
+  direction: "across" | "down";
+  answer: string;
+  answer_length: number;
+  row: number;
+  col: number;
+  cells: [number, number][];
+  clue: string;
+  clue_source: string;
+  topics: string[];
+  pos: string;
+  is_seed: boolean;
+  added_by_filler: boolean;
+  confidence: number;
+};
+
+export type CrosswordResponse = {
+  schema_version: string;
+  request_id: string;
+  crossword_id: string;
+  generated_at: string;
+  status: string;
+  generator: {
+    topic: string[];
+    difficulty: string;
+    seed: number | null;
+    runtime_lexicon: string;
+  };
+  summary: {
+    title: string;
+    subtitle: string;
+    rows: number;
+    cols: number;
+    total_words: number;
+    intersections: number;
+  };
+  grid: {
+    rows: number;
+    cols: number;
+    cell_size_hint: number;
+    cells: CrosswordCell[];
+  };
+  entries: CrosswordEntry[];
+  clues: {
+    across: CrosswordClue[];
+    down: CrosswordClue[];
+  };
+  solution: {
+    grid_rows: string[];
+    words: string[];
+  };
+  diagnostics: {
+    seed_words_requested: number;
+    seed_words_placed: number;
+    filler_words_added: number;
+    filled_cells: number;
+    empty_cells: number;
+    empty_ratio: number;
+    target_empty_ratio: number;
+    topic_words: number;
+    off_topic_words: number;
+    pos_counts: Record<string, number>;
+    generation_seconds: number;
+  };
+  artifacts: {
+    pdf_player: string | null;
+    pdf_solution: string | null;
+    thumbnail: string | null;
+    html_preview: string | null;
+  };
+};
--- a/webapp/next-env.d.ts
+++ b/webapp/next-env.d.ts
@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
--- a/webapp/next.config.ts
+++ b/webapp/next.config.ts
@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+};
+
+export default nextConfig;
--- a/webapp/package-lock.json
+++ b/webapp/package-lock.json
--- a/webapp/package.json
+++ b/webapp/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "cruciverba-webapp",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "next": "^15.2.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.2",
+    "@types/react-dom": "^19.0.2",
+    "eslint": "^9.18.0",
+    "eslint-config-next": "^15.2.0",
+    "typescript": "^5.7.2"
+  }
+}
--- a/webapp/tsconfig.json
+++ b/webapp/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}