From b03bb404407ba4d411b21742daecf7041212751e Mon Sep 17 00:00:00 2001
From: Marco Farina <marco.farina@jcmaxwell.it>
Date: Thu, 2 Jul 2026 09:03:36 +0200
Subject: [PATCH 01/11] feat(pyquest): motore trace-based (nucleo movimento)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fase 1 (M1), step 1-4 della spec PyQuest.

- config.py: espone Config.NODE_ID (node_id grezzo) in set_id(), così
  pyquest.py può fare notify() sullo stesso div che bryBridge ascolta.
- bryBridge.ts: RunOptions.onCustom + BryNotifyDetail.type ora string; nel
  switch un ramo default inoltra gli eventi fuori protocollo (D3).
  Retrocompatibile: PyRunner/SQLRunner invariati.
- pyquest.py: modello logico puro (World/Hero), _load_level che riassegna il
  global _world (no contaminazione tra run del modulo cacheato), move/turn,
  sensori is_blocked/on_goal, action_guard + StepLimitError, contatore sensori,
  win spec «reach». Emissione eventi come payload JSON (D4).
- types.ts: tipi normativi della trace (GameEvent/SceneState/LogLine) + schema
  dati LevelDef/WorldDef.
- runLevel.ts: compone il preCode (from pyquest import * + _load_level + shadow
  di input) con JSON compatto spogliato dei campi testuali (D2/D7); riparsa gli
  eventi via onCustom.

Logica del motore validata con CPython (stub di config/py_back_trace):
move/turn/sensori, vittoria reach, no-op post-vittoria, assenza di
contaminazione tra run, step_limit. Bridge Brython/DOM riusa l'infrastruttura
PyRunner esistente.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pv1PzGn4LtwKFku39y15V4
---
 src/components/PyQuest/runLevel.ts |  91 +++++++++++++
 src/components/PyQuest/types.ts    | 120 +++++++++++++++++
 src/theme/PyRunner/bryBridge.ts    |  14 +-
 static/bry-libs/config.py          |   4 +
 static/bry-libs/pyquest.py         | 209 +++++++++++++++++++++++++++++
 5 files changed, 437 insertions(+), 1 deletion(-)
 create mode 100644 src/components/PyQuest/runLevel.ts
 create mode 100644 src/components/PyQuest/types.ts
 create mode 100644 static/bry-libs/pyquest.py

diff --git a/src/components/PyQuest/runLevel.ts b/src/components/PyQuest/runLevel.ts
new file mode 100644
index 0000000..1f128be
--- /dev/null
+++ b/src/components/PyQuest/runLevel.ts
@@ -0,0 +1,91 @@
+/**
+ * Esegue il codice studente contro un livello PyQuest.
+ *
+ * Compone il preCode (D2/D7): `from pyquest import *` + `_load_level(<json>)` +
+ * shadowing di `input`, poi delega a `runPython` (bryBridge). Gli eventi di
+ * gioco arrivano via `onCustom` come `{type:'game_event', payload:'<json>'}`
+ * (D4): qui il payload viene riparsato in un `GameEvent` tipato.
+ *
+ * Il JSON del livello iniettato è **spogliato dei campi testuali**
+ * (title/hints/starterCode/solution): al motore servono solo grid/hero/goal/
+ * enemies/resources/win/maxSteps. Meno quoting, payload più leggero.
+ */
+
+import type { BrythonConfig } from '@site/src/pyBoot';
+import { runPython, type LogKind } from '@site/src/theme/PyRunner/bryBridge';
+import type { GameEvent, LevelDef } from './types';
+
+const MAX_STEPS_DEFAULT = 500;
+
+/** Sottoinsieme del livello che il motore Python consuma davvero. */
+function runtimeLevel(level: LevelDef): Record<string, unknown> {
+  const rt: Record<string, unknown> = {
+    grid: level.grid,
+    hero: level.hero,
+    enemies: level.enemies ?? [],
+    resources: level.resources ?? [],
+    win: level.win,
+    maxSteps: level.maxSteps ?? MAX_STEPS_DEFAULT,
+  };
+  if (level.goal) rt.goal = level.goal;
+  return rt;
+}
+
+function buildPreCode(level: LevelDef): string {
+  const json = JSON.stringify(runtimeLevel(level));
+  return [
+    'from pyquest import *',
+    `_load_level('''${json}''')`,
+    "def input(*a): raise RuntimeError('input() non è disponibile nei livelli: usa i sensori!')",
+  ].join('\n');
+}
+
+export interface RunLevelOptions {
+  code: string;
+  level: LevelDef;
+  codeId: string;
+  libUrl: string;
+  brython?: BrythonConfig;
+  onStart: () => void;
+  onEvent: (ev: GameEvent) => void;
+  onLog: (kind: LogKind, text: string) => void;
+  onDone: (durationMs: number) => void;
+  onError?: (err: Error) => void;
+}
+
+/** Avvia un run. Ritorna una funzione di cleanup (rimuove il listener). */
+export function runLevel(opts: RunLevelOptions): () => void {
+  const {
+    code,
+    level,
+    codeId,
+    libUrl,
+    brython,
+    onStart,
+    onEvent,
+    onLog,
+    onDone,
+    onError,
+  } = opts;
+
+  return runPython(code, {
+    codeId,
+    preCode: buildPreCode(level),
+    libUrl,
+    brython,
+    onStart,
+    onLog,
+    onDone,
+    onError,
+    onCustom: (detail) => {
+      if (detail.type !== 'game_event') return;
+      const payload = detail.payload;
+      if (typeof payload !== 'string') return;
+      try {
+        onEvent(JSON.parse(payload) as GameEvent);
+      } catch {
+        // payload malformato: ignora (non deve mai capitare — lo emettiamo noi)
+      }
+    },
+  });
+}
diff --git a/src/components/PyQuest/types.ts b/src/components/PyQuest/types.ts
new file mode 100644
index 0000000..6173cc7
--- /dev/null
+++ b/src/components/PyQuest/types.ts
@@ -0,0 +1,120 @@
+/**
+ * Tipi di PyQuest: la trace di eventi emessi dal motore Python
+ * (`static/bry-libs/pyquest.py`), lo stato di scena derivato consumato dal
+ * renderer, e i tipi dei dati livello/mondo speculari allo schema world.json.
+ */
+
+export type Facing = 'north' | 'east' | 'south' | 'west';
+
+/** Un evento della trace. Il campo discriminante è `t`. */
+export type GameEvent =
+  | { t: 'move'; x: number; y: number; f: Facing }
+  | { t: 'turn'; f: Facing }
+  | { t: 'bump'; x: number; y: number }
+  | { t: 'attack'; x: number; y: number; hit: boolean }
+  | { t: 'enemy_hit'; id: string; hp: number }
+  | { t: 'defeat'; id: string }
+  | { t: 'enemy_move'; id: string; x: number; y: number }
+  | { t: 'hero_hit'; hp: number; by: string }
+  | { t: 'collect'; id: string; kind: string }
+  | { t: 'win' }
+  | { t: 'death' }
+  | { t: 'step_limit' };
+
+/** Riga di console associata al passo della trace in cui è stata emessa. */
+export interface LogLine {
+  kind: 'stdout' | 'stderr';
+  text: string;
+  atStep: number;
+}
+
+/** Stato di scena a un dato passo: derivato riducendo la trace. */
+export interface SceneState {
+  hero: { x: number; y: number; facing: Facing; hp: number };
+  enemies: Record<
+    string,
+    { kind: string; x: number; y: number; hp: number; alive: boolean }
+  >;
+  resources: Record<
+    string,
+    { kind: string; x: number; y: number; collected: boolean }
+  >;
+  inventory: Record<string, number>;
+  won: boolean;
+  dead: boolean;
+  stepLimit: boolean;
+  /** Transiente: valido solo per lo step corrente (animazioni one-shot). */
+  fx: {
+    kind: 'bump' | 'attack' | 'hero_hit' | 'collect' | 'defeat';
+    at?: { x: number; y: number };
+  } | null;
+}
+
+// --- Schema dati (speculare a static/pyquest/<world>/world.json) -------------
+
+export interface GridDef {
+  legend: Record<string, string>;
+  rows: string[];
+}
+
+export interface HeroDef {
+  x: number;
+  y: number;
+  facing: Facing;
+  hp: number;
+}
+
+export interface PointDef {
+  x: number;
+  y: number;
+}
+
+export type EnemyBehavior = 'static' | 'melee';
+
+export interface EnemyDef {
+  id: string;
+  kind: string;
+  x: number;
+  y: number;
+  hp: number;
+  behavior: EnemyBehavior;
+}
+
+export interface ResourceDef {
+  id: string;
+  kind: string;
+  x: number;
+  y: number;
+}
+
+export type WinCond =
+  | { type: 'reach' }
+  | { type: 'collect'; kind: string; qty: number }
+  | { type: 'defeat'; kind?: string; count?: number };
+
+export interface LevelDef {
+  id: string;
+  title: string;
+  grid: GridDef;
+  hero: HeroDef;
+  goal?: PointDef;
+  enemies?: EnemyDef[];
+  resources?: ResourceDef[];
+  win: WinCond[];
+  starterCode: string;
+  /** Solo per l'autore (calibrazione del `par`); non usato a runtime. */
+  solution?: string;
+  hints: string[];
+  par: number;
+  maxSteps?: number;
+}
+
+export interface WorldDef {
+  schemaVersion: number;
+  id: string;
+  title: string;
+  description: string;
+  character: string;
+  volume: string;
+  levels: LevelDef[];
+}
diff --git a/src/theme/PyRunner/bryBridge.ts b/src/theme/PyRunner/bryBridge.ts
index 50b3e62..3db2976 100644
--- a/src/theme/PyRunner/bryBridge.ts
+++ b/src/theme/PyRunner/bryBridge.ts
@@ -25,10 +25,18 @@ export interface RunOptions {
   onLog: (kind: LogKind, text: string) => void;
   onDone: (durationMs: number) => void;
   onError?: (err: Error) => void;
+  /**
+   * Eventi `bry_notify` con un `type` fuori dal protocollo standard
+   * (start/done/stdout/stderr). PyQuest lo usa per gli eventi `game_event`
+   * emessi da `pyquest.py`; il payload applicativo viaggia in `detail.payload`
+   * come stringa JSON (vedi D4 nella spec).
+   */
+  onCustom?: (detail: { type: string } & Record<string, unknown>) => void;
 }
 
 interface BryNotifyDetail {
-  type: 'start' | 'done' | 'stdout' | 'stderr';
+  // `string` (non un'unione chiusa) per accogliere i type applicativi (PyQuest).
+  type: string;
   output?: string;
   time?: number;
 }
@@ -90,6 +98,7 @@ export function runPython(code: string, opts: RunOptions): () => void {
     onLog,
     onDone,
     onError,
+    onCustom,
   } = opts;
 
   // Difensivo: `codeId` viene interpolato in un sorgente Python che poi
@@ -117,6 +126,9 @@ export function runPython(code: string, opts: RunOptions): () => void {
       case 'stderr':
         if (detail.output) onLog(detail.type, detail.output);
         break;
+      default:
+        onCustom?.(detail as never);
+        break;
     }
   };
 
diff --git a/static/bry-libs/config.py b/static/bry-libs/config.py
index a1e62cd..d73670f 100644
--- a/static/bry-libs/config.py
+++ b/static/bry-libs/config.py
@@ -5,9 +5,13 @@ class Config():
     GRAPHICS_ID = f'id_graphics'
     TURTLE_SVG_CONTAINER = f'id_svg'
     OUTPUT_DIV = f'id_brython_result'
+    # node_id grezzo: serve a PyQuest per fare notify() sullo stesso div che
+    # bryBridge ascolta (py_<node_id>). Gli altri campi sono id DOM derivati.
+    NODE_ID = 'id'
 
     @staticmethod
     def set_id(node_id):
+        Config.NODE_ID = node_id
         Config.BRYTHON_COMMUNICATOR = f'py_{node_id}'
         Config.CANVAS_ID = f'{node_id}_canvas'
         Config.GRAPHICS_ID = f'{node_id}_graphics'
diff --git a/static/bry-libs/pyquest.py b/static/bry-libs/pyquest.py
new file mode 100644
index 0000000..dd33d4a
--- /dev/null
+++ b/static/bry-libs/pyquest.py
@@ -0,0 +1,209 @@
+# pyquest.py — modello logico dei mini-giochi a griglia (PyQuest).
+#
+# Motore trace-based (spec D1): il codice studente viene eseguito davvero, per
+# intero e sincrono, contro questo modello in puro Python. Ogni azione aggiorna
+# il modello ED emette subito un evento `game_event` via notify(); React (lato
+# TS) accumula la trace e la anima dopo. I sensori leggono lo stato corrente del
+# modello (aggiornato durante l'esecuzione vera), quindi i cicli condizionati
+# funzionano.
+#
+# NB (step 6, sys.settrace): decisione ancora da prendere — vedi task PyQuest.
+# Finché non è documentata qui, il residuo `while True: pass` senza chiamate API
+# blocca il main thread come oggi in PyRunner (mitigato da step_count e
+# sensor_count per i loop che *chiamano* qualcosa).
+
+import json
+from config import Config  # type: ignore
+from py_back_trace import notify  # type: ignore
+
+__all__ = [
+    '_load_level',
+    'move', 'turn_left', 'turn_right',
+    'is_blocked', 'on_goal',
+]
+
+# --- Costanti -----------------------------------------------------------------
+
+MAX_STEPS_DEFAULT = 500
+MAX_SENSOR_READS = 100_000
+
+# y cresce verso il basso; facing in north|east|south|west.
+DIRS = {
+    'north': (0, -1),
+    'east': (1, 0),
+    'south': (0, 1),
+    'west': (-1, 0),
+}
+
+_TURN_LEFT = {'north': 'west', 'west': 'south', 'south': 'east', 'east': 'north'}
+_TURN_RIGHT = {'north': 'east', 'east': 'south', 'south': 'west', 'west': 'north'}
+
+
+# --- Eccezioni di fine partita ------------------------------------------------
+
+class StepLimitError(Exception):
+    """Superato il tetto di azioni (o di letture sensore): ciclo non terminante."""
+    pass
+
+
+# --- Modello ------------------------------------------------------------------
+
+class Hero:
+    def __init__(self, x, y, facing, hp):
+        self.x = x
+        self.y = y
+        self.facing = facing
+        self.hp = hp
+        self.inventory = {}
+
+
+class World:
+    def __init__(self, data):
+        grid = data['grid']
+        legend = grid['legend']
+        rows = grid['rows']
+        self.height = len(rows)
+        self.width = len(rows[0]) if rows else 0
+        self.walls = set()
+        for y, row in enumerate(rows):
+            for x, ch in enumerate(row):
+                if legend.get(ch) == 'wall':
+                    self.walls.add((x, y))
+
+        h = data['hero']
+        self.hero = Hero(h['x'], h['y'], h.get('facing', 'east'), h.get('hp', 3))
+
+        g = data.get('goal')
+        self.goal = (g['x'], g['y']) if g else None
+
+        self.win_spec = data.get('win', [])
+        self.max_steps = data.get('maxSteps', MAX_STEPS_DEFAULT)
+
+        self.step_count = 0
+        self.sensor_count = 0
+        self.won = False
+        self.dead = False
+
+    def is_walkable(self, x, y):
+        if x < 0 or y < 0 or x >= self.width or y >= self.height:
+            return False
+        if (x, y) in self.walls:
+            return False
+        return True
+
+    def tick(self):
+        # I nemici si muovono qui (step 13). Nel nucleo movimento è un no-op.
+        pass
+
+
+_world = None  # riassegnato a ogni _load_level → nessuna contaminazione tra run
+
+
+def _load_level(json_str):
+    global _world
+    _world = World(json.loads(json_str))
+
+
+# --- Emissione eventi (D4: payload = stringa JSON) ----------------------------
+
+def _emit(ev):
+    notify(Config.NODE_ID, {'type': 'game_event', 'payload': json.dumps(ev)})
+
+
+# --- Guardie di sicurezza -----------------------------------------------------
+
+def _action_guard():
+    _world.step_count += 1
+    if _world.step_count > _world.max_steps:
+        _emit({'t': 'step_limit'})
+        raise StepLimitError(
+            'Hai superato le %d mosse: forse un ciclo non si ferma mai. '
+            'Controlla la condizione del tuo `while`.' % _world.max_steps
+        )
+
+
+def _sensor_guard():
+    _world.sensor_count += 1
+    if _world.sensor_count > MAX_SENSOR_READS:
+        _emit({'t': 'step_limit'})
+        raise StepLimitError(
+            'Hai interrogato i sensori troppe volte senza agire: '
+            'probabilmente un `while` gira a vuoto. Fai muovere il tuo eroe.'
+        )
+
+
+# --- Ciclo del mondo ----------------------------------------------------------
+
+def _after_action():
+    _world.tick()
+    _check_win()
+
+
+def _cond_met(cond):
+    t = cond.get('type')
+    if t == 'reach':
+        return _world.goal is not None and (_world.hero.x, _world.hero.y) == _world.goal
+    # collect / defeat: implementati allo step 13. Finché non lo sono, la
+    # condizione è considerata NON soddisfatta (mai vittoria fantasma).
+    return False
+
+
+def _check_win():
+    if _world.won:
+        return
+    if not _world.win_spec:
+        return
+    for cond in _world.win_spec:
+        if not _cond_met(cond):
+            return
+    _world.won = True
+    _emit({'t': 'win'})
+
+
+# --- API studente: azioni -----------------------------------------------------
+
+def move():
+    if _world.won:
+        return
+    _action_guard()
+    hero = _world.hero
+    dx, dy = DIRS[hero.facing]
+    nx, ny = hero.x + dx, hero.y + dy
+    if _world.is_walkable(nx, ny):
+        hero.x, hero.y = nx, ny
+        _emit({'t': 'move', 'x': nx, 'y': ny, 'f': hero.facing})
+    else:
+        _emit({'t': 'bump', 'x': nx, 'y': ny})
+    _after_action()
+
+
+def turn_left():
+    if _world.won:
+        return
+    _action_guard()
+    _world.hero.facing = _TURN_LEFT[_world.hero.facing]
+    _emit({'t': 'turn', 'f': _world.hero.facing})
+    _after_action()
+
+
+def turn_right():
+    if _world.won:
+        return
+    _action_guard()
+    _world.hero.facing = _TURN_RIGHT[_world.hero.facing]
+    _emit({'t': 'turn', 'f': _world.hero.facing})
+    _after_action()
+
+
+# --- API studente: sensori (gratuiti, senza tick) -----------------------------
+
+def is_blocked():
+    _sensor_guard()
+    hero = _world.hero
+    dx, dy = DIRS[hero.facing]
+    return not _world.is_walkable(hero.x + dx, hero.y + dy)
+
+
+def on_goal():
+    _sensor_guard()
+    return _world.goal is not None and (_world.hero.x, _world.hero.y) == _world.goal

From 61048796cab723a3ae1f1a0b01de392c39494d47 Mon Sep 17 00:00:00 2001
From: Marco Farina <marco.farina@jcmaxwell.it>
Date: Thu, 2 Jul 2026 09:03:46 +0200
Subject: [PATCH 02/11] feat(pyquest): harness di sviluppo del motore
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fase 1 (M1), step 5 della spec PyQuest.

- index.tsx: prima versione debug del componente PyQuest — editor riusato da
  PyRunner + bottone Esegui + dump grezzo degli eventi e della console. Contatore
  di modulo per il suffisso del codeId (D12), così due istanze sulla stessa
  pagina restano indipendenti. Verrà riscritto allo step 12 (renderer + player).
- pyquest-test.mdx: pagina unlisted /docs/pyquest-test con due harness e la
  checklist di verifica manuale (movimento, indipendenza, errore, vittoria).
- MDXComponents.tsx: registra <PyQuest> tra i componenti MDX globali.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pv1PzGn4LtwKFku39y15V4
---
 docs/pyquest-test.mdx            |  39 +++++
 src/components/PyQuest/index.tsx | 245 +++++++++++++++++++++++++++++++
 src/theme/MDXComponents.tsx      |   2 +
 3 files changed, 286 insertions(+)
 create mode 100644 docs/pyquest-test.mdx
 create mode 100644 src/components/PyQuest/index.tsx

diff --git a/docs/pyquest-test.mdx b/docs/pyquest-test.mdx
new file mode 100644
index 0000000..7c4f46c
--- /dev/null
+++ b/docs/pyquest-test.mdx
@@ -0,0 +1,39 @@
+---
+unlisted: true
+title: PyQuest — pagina di test
+description: Harness di verifica del motore PyQuest (trace-based, mini-giochi a griglia)
+---
+
+# PyQuest — sandbox di test del motore
+
+Pagina temporanea per validare il **motore** di PyQuest (fase 1). Non è linkata
+dalla sidebar (`unlisted: true`): la raggiungi solo via URL `/docs/pyquest-test`.
+Qui il componente è in versione **harness**: editor + bottone Esegui + dump grezzo
+degli eventi emessi dal motore Python. Renderer e player arrivano nella fase 2.
+
+Il livello di default è una griglia 5×5 con Byte in `(1, 1)` rivolto a est e un
+muro a due celle di distanza.
+
+## 1. Movimento base
+
+Digita `for _ in range(3): move()` e premi Esegui: attesi `move`, `move`, `bump`
+(la terza mossa sbatte contro il muro).
+
+<PyQuest />
+
+## 2. Verifica indipendenza tra istanze
+
+Due harness sullo stesso livello sulla stessa pagina: devono avere `codeId`
+diversi e trace indipendenti (esegui l'uno, l'altro resta fermo).
+
+<PyQuest />
+
+## Note per la verifica (checklist step 5)
+
+- **a)** `for _ in range(3): move()` → `move, move, bump`.
+- **b)** un errore a riga 2 (es. `move()` poi `boom`) → eventi fino a riga 1
+  **più** un traceback su stderr che indica **riga 2**.
+- **c)** due Esegui consecutivi producono trace identiche (nessuna
+  contaminazione tra run del modulo `pyquest` cacheato).
+- Prova anche `while not on_goal(): move()` e la vittoria (`win`) quando Byte
+  raggiunge `(3, 3)` — serve girare e muoversi (`turn_right()` + `move()`).
diff --git a/src/components/PyQuest/index.tsx b/src/components/PyQuest/index.tsx
new file mode 100644
index 0000000..3fcadba
--- /dev/null
+++ b/src/components/PyQuest/index.tsx
@@ -0,0 +1,245 @@
+/**
+ * PyQuest — mini-giochi a griglia con Python (spec: PyQuest).
+ *
+ * ⚠️ VERSIONE HARNESS (step 5). Questa è la prima versione "debug" del
+ * componente: editor riusato da PyRunner + bottone Esegui + dump grezzo degli
+ * eventi ricevuti dal motore. Niente renderer, niente player: quelli arrivano
+ * nella fase 2 (step 10-12), quando questo file verrà riscritto (step 12).
+ * Serve solo a validare il motore trace-based end-to-end.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import BrowserOnly from '@docusaurus/BrowserOnly';
+import { usePluginData } from '@docusaurus/useGlobalData';
+import { Editor, type EditorHandle } from '@site/src/theme/PyRunner/Editor';
+import { ensureBrython, type BrythonConfig } from '@site/src/pyBoot';
+import { runLevel } from './runLevel';
+import type { GameEvent, LevelDef, LogLine } from './types';
+
+export interface PyQuestProps {
+  /** Id del mondo nei global data del plugin `pyquest` (fase 2, step 7). */
+  world?: string;
+  /** Id del livello dentro il mondo. */
+  level?: string;
+  /** Livello passato inline (editor/test): bypassa la lookup su world/level. */
+  levelData?: LevelDef;
+  /** Titolo mostrato sopra l'editor. */
+  title?: string;
+}
+
+interface PyRunnerGlobalData {
+  libUrl: string;
+  brython?: BrythonConfig;
+}
+
+type RunStatus = 'idle' | 'running' | 'done' | 'error';
+
+// Livello di fallback per l'harness: griglia 5×5, muro a 2 celle davanti a Byte
+// così `for _ in range(3): move()` produce move, move, bump.
+const DEFAULT_LEVEL: LevelDef = {
+  id: 'harness',
+  title: 'Harness 5×5',
+  grid: {
+    legend: { '#': 'wall', '.': 'floor' },
+    rows: ['#####', '#...#', '#...#', '#...#', '#####'],
+  },
+  hero: { x: 1, y: 1, facing: 'east', hp: 3 },
+  goal: { x: 3, y: 3 },
+  win: [{ type: 'reach' }],
+  starterCode:
+    '# Muovi Byte. Prova a cambiare il codice ed esegui.\nfor _ in range(3):\n    move()\n',
+  hints: [],
+  par: 6,
+};
+
+// Contatore di modulo per il suffisso del codeId (D12): due istanze dello stesso
+// livello sulla stessa pagina devono restare indipendenti.
+let idCounter = 0;
+
+function makeCodeId(seed: string, n: number): string {
+  let hash = 5381;
+  for (let i = 0; i < seed.length; i++) {
+    hash = (hash * 33) ^ seed.charCodeAt(i);
+  }
+  // Deve soddisfare la guardia /^pyr_[a-z0-9]+$/ di bryBridge (niente separatori).
+  return `pyr_${(hash >>> 0).toString(36)}${n.toString(36)}`;
+}
+
+function PyQuestInner(props: PyQuestProps) {
+  const data = usePluginData('pyrunner') as PyRunnerGlobalData | undefined;
+  const libUrl = data?.libUrl ?? '';
+  const brython = data?.brython;
+
+  const level = props.levelData ?? DEFAULT_LEVEL;
+  const seed =
+    props.world && props.level
+      ? `${props.world}/${props.level}`
+      : JSON.stringify(level);
+
+  const instanceN = useRef<number>(-1);
+  if (instanceN.current < 0) instanceN.current = idCounter++;
+  const codeId = useMemo(() => makeCodeId(seed, instanceN.current), [seed]);
+
+  const [events, setEvents] = useState<GameEvent[]>([]);
+  const [logs, setLogs] = useState<LogLine[]>([]);
+  const [status, setStatus] = useState<RunStatus>('idle');
+
+  const editorRef = useRef<EditorHandle | null>(null);
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const cleanupRef = useRef<(() => void) | null>(null);
+
+  // Precarica Brython quando l'harness entra nel viewport (pattern PyRunner).
+  useEffect(() => {
+    const el = rootRef.current;
+    const preload = () => {
+      ensureBrython(libUrl, brython).catch(() => {
+        /* l'errore riemerge al primo run via onError */
+      });
+    };
+    if (!el || typeof IntersectionObserver === 'undefined') {
+      preload();
+      return;
+    }
+    const io = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((e) => e.isIntersecting)) {
+          io.disconnect();
+          preload();
+        }
+      },
+      { rootMargin: '200px' },
+    );
+    io.observe(el);
+    return () => io.disconnect();
+  }, [libUrl, brython]);
+
+  useEffect(() => () => cleanupRef.current?.(), []);
+
+  const handleRun = useCallback(() => {
+    const code = editorRef.current?.getCode() ?? level.starterCode;
+    setStatus('running');
+    setEvents([]);
+    setLogs([]);
+    const collected: GameEvent[] = [];
+    cleanupRef.current?.();
+    cleanupRef.current = runLevel({
+      code,
+      level,
+      codeId,
+      libUrl,
+      brython,
+      onStart: () => {
+        collected.length = 0;
+        setEvents([]);
+        setLogs([]);
+      },
+      onEvent: (ev) => {
+        collected.push(ev);
+        setEvents([...collected]);
+      },
+      onLog: (kind, text) => {
+        setLogs((prev) => [...prev, { kind, text, atStep: collected.length }]);
+        if (kind === 'stderr') setStatus('error');
+      },
+      onDone: () => setStatus((s) => (s === 'error' ? s : 'done')),
+      onError: (err) => {
+        setStatus('error');
+        setLogs((prev) => [
+          ...prev,
+          {
+            kind: 'stderr',
+            text: `[PyQuest] ${err.message}\n`,
+            atStep: collected.length,
+          },
+        ]);
+      },
+    });
+  }, [level, codeId, libUrl, brython]);
+
+  if (!libUrl) {
+    return (
+      <div style={{ padding: 12, border: '1px solid var(--at-border)' }}>
+        PyQuest (harness): plugin <code>pyrunner</code> non registrato — libUrl
+        mancante.
+      </div>
+    );
+  }
+
+  const boxStyle: React.CSSProperties = {
+    border: '1px solid var(--at-border)',
+    borderRadius: 'var(--radius-m, 10px)',
+    padding: 8,
+    margin: '8px 0',
+    background: 'var(--at-bg-subtle)',
+    fontFamily: '"Monaspace Neon", ui-monospace, monospace',
+    fontSize: '0.85rem',
+    whiteSpace: 'pre-wrap',
+    maxHeight: 240,
+    overflow: 'auto',
+  };
+
+  return (
+    <div ref={rootRef} data-pagefind-ignore style={{ margin: '1.5rem 0' }}>
+      <div style={{ marginBottom: 6, fontWeight: 600 }}>
+        {props.title ?? level.title}{' '}
+        <span style={{ opacity: 0.6, fontWeight: 400 }}>
+          — harness ({status})
+        </span>
+      </div>
+      <div
+        style={{
+          border: '1px solid var(--at-border)',
+          borderRadius: 'var(--radius-m, 10px)',
+          overflow: 'hidden',
+        }}
+      >
+        <Editor
+          ref={editorRef}
+          initialCode={level.starterCode}
+          showLineNumbers
+          onRun={handleRun}
+        />
+      </div>
+      <button
+        type="button"
+        onClick={handleRun}
+        disabled={status === 'running'}
+        style={{
+          marginTop: 8,
+          padding: '6px 14px',
+          borderRadius: 'var(--radius-s, 6px)',
+          border: '1px solid var(--at-border)',
+          background: 'var(--at-accent)',
+          color: '#fff',
+          cursor: status === 'running' ? 'default' : 'pointer',
+        }}
+      >
+        Esegui
+      </button>
+      <div style={{ marginTop: 8, fontWeight: 600, fontSize: '0.8rem' }}>
+        Eventi ({events.length})
+      </div>
+      <div style={boxStyle}>
+        {events.map((ev, i) => `${i}: ${JSON.stringify(ev)}`).join('\n') || '—'}
+      </div>
+      {logs.length > 0 && (
+        <>
+          <div style={{ marginTop: 8, fontWeight: 600, fontSize: '0.8rem' }}>
+            Console
+          </div>
+          <div style={boxStyle}>
+            {logs.map((l) => `[${l.kind}@${l.atStep}] ${l.text}`).join('')}
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+
+export default function PyQuest(props: PyQuestProps) {
+  return (
+    <BrowserOnly fallback={<div>PyQuest…</div>}>
+      {() => <PyQuestInner {...props} />}
+    </BrowserOnly>
+  );
+}
diff --git a/src/theme/MDXComponents.tsx b/src/theme/MDXComponents.tsx
index f6efe9d..dcdded5 100644
--- a/src/theme/MDXComponents.tsx
+++ b/src/theme/MDXComponents.tsx
@@ -16,6 +16,7 @@ import Quiz, {
 import PyRunner from '@site/src/theme/PyRunner';
 import SQLRunner from '@site/src/theme/SQLRunner';
 import Algorithm from '@site/src/components/Algorithm';
+import PyQuest from '@site/src/components/PyQuest';
 import ExerciseLink from '@site/src/components/ExerciseLink';
 import Exercise, { LessonMeta, Solution } from '@site/src/components/Exercise';
 import AssignedExercises from '@site/src/components/AssignedExercises';
@@ -34,6 +35,7 @@ export default {
   PyRunner,
   SQLRunner,
   Algorithm,
+  PyQuest,
   ExerciseLink,
   Exercise,
   LessonMeta,

From fa913b01338299ce534047fa376290f998ec85f4 Mon Sep 17 00:00:00 2001
From: Marco Farina <marco.farina@jcmaxwell.it>
Date: Thu, 2 Jul 2026 15:43:36 +0200
Subject: [PATCH 03/11] =?UTF-8?q?feat(pyquest):=20chiuso=20spike=20sys.set?=
 =?UTF-8?q?trace=20=E2=80=94=20guardia=20non=20attivata?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Test nel browser (Brython 3.12): settrace emette line events solo nei
frame di funzione; il codice a livello modulo/exec (dove gira il codice
studente) non genera line events, frame.f_trace è inefficace e il raise
dal tracer non è contenibile in modo affidabile. Decisione documentata
in testa a pyquest.py: rischio residuo `while True: pass` accettato,
come oggi in PyRunner. Pagina spike temporanea eliminata.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V9dpQX4sKY6tJkTetJz3ho
---
 static/bry-libs/pyquest.py | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/static/bry-libs/pyquest.py b/static/bry-libs/pyquest.py
index dd33d4a..d4860ff 100644
--- a/static/bry-libs/pyquest.py
+++ b/static/bry-libs/pyquest.py
@@ -7,10 +7,21 @@
 # modello (aggiornato durante l'esecuzione vera), quindi i cicli condizionati
 # funzionano.
 #
-# NB (step 6, sys.settrace): decisione ancora da prendere — vedi task PyQuest.
-# Finché non è documentata qui, il residuo `while True: pass` senza chiamate API
-# blocca il main thread come oggi in PyRunner (mitigato da step_count e
-# sensor_count per i loop che *chiamano* qualcosa).
+# Decisione step 6 (spike sys.settrace, 2026-07-02): guardia NON attivata,
+# rischio residuo ACCETTATO. Misure in Brython 3.12 nel browser:
+#   - settrace con eventi 'line' funziona SOLO nei frame di funzione
+#     (400 005 eventi su un loop 200k in funzione; overhead ~20-27x, ~2-6 us/evento);
+#   - il codice a livello modulo — cioè il codice studente, exec-utato da
+#     brython_runner — NON genera line events (1 solo evento su loop da 300k
+#     iterazioni top-level), quindi la guardia non vedrebbe proprio il caso
+#     canonico `while True: pass`;
+#   - frame.f_trace sul frame corrente è accettato ma inefficace (0 eventi);
+#   - il raise dal tracer nei frame di funzione ha semantica rotta:
+#     sys.settrace(None) chiamato dentro il tracer non disattiva il tracing e
+#     l'eccezione riesplode durante le righe dell'handler, scavalcando l'except.
+# Quindi: `while True: pass` senza chiamate API blocca il main thread come oggi
+# in PyRunner; i loop che chiamano qualcosa sono mitigati da step_count e
+# sensor_count qui sotto.
 
 import json
 from config import Config  # type: ignore

From 7f785344f0903861b7f50568595d503737926933 Mon Sep 17 00:00:00 2001
From: Marco Farina <marco.farina@jcmaxwell.it>
Date: Thu, 2 Jul 2026 16:02:03 +0200
Subject: [PATCH 04/11] =?UTF-8?q?fix(pyquest):=20guardia=20azioni=20prima?=
 =?UTF-8?q?=20del=20check=20won=20=E2=80=94=20niente=20hang=20post-vittori?=
 =?UTF-8?q?a?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review fase 1: a mondo congelato (dopo win) move/turn_* ritornavano prima di
_action_guard(), quindi 'while True: move()' dopo la vittoria ciclava su no-op
senza far avanzare nessun contatore, bloccando il main thread. Ora la guardia
scatta sempre: le azioni post-win restano no-op ma costano un passo e il loop
muore con StepLimitError (trace: win seguito da step_limit).

Minore: makeCodeId con hash base36 a larghezza fissa (padStart 7) per rendere
impossibile la collisione teorica della concatenazione hash+contatore.

Verificato con test CPython (19/19, stub config/py_back_trace) e live nel
browser: scenari a/b/c dello step 5, loop post-win che termina con messaggio
didattico, indipendenza tra istanze, smoke PyRunner senza regressioni.
typecheck/lint/build verdi.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V9dpQX4sKY6tJkTetJz3ho
---
 src/components/PyQuest/index.tsx |  5 ++++-
 static/bry-libs/pyquest.py       | 10 +++++++---
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/src/components/PyQuest/index.tsx b/src/components/PyQuest/index.tsx
index 3fcadba..6f320e2 100644
--- a/src/components/PyQuest/index.tsx
+++ b/src/components/PyQuest/index.tsx
@@ -62,7 +62,10 @@ function makeCodeId(seed: string, n: number): string {
     hash = (hash * 33) ^ seed.charCodeAt(i);
   }
   // Deve soddisfare la guardia /^pyr_[a-z0-9]+$/ di bryBridge (niente separatori).
-  return `pyr_${(hash >>> 0).toString(36)}${n.toString(36)}`;
+  // Hash a larghezza fissa (7 = max cifre base36 di un uint32): senza padding la
+  // concatenazione hash+contatore potrebbe collidere tra istanze diverse.
+  const h = (hash >>> 0).toString(36).padStart(7, '0');
+  return `pyr_${h}${n.toString(36)}`;
 }
 
 function PyQuestInner(props: PyQuestProps) {
diff --git a/static/bry-libs/pyquest.py b/static/bry-libs/pyquest.py
index d4860ff..6b68516 100644
--- a/static/bry-libs/pyquest.py
+++ b/static/bry-libs/pyquest.py
@@ -174,9 +174,13 @@ def _check_win():
 # --- API studente: azioni -----------------------------------------------------
 
 def move():
+    # La guardia scatta PRIMA del check `won`: a mondo congelato le azioni
+    # restano no-op ma costano comunque un passo, altrimenti un
+    # `while True: move()` dopo la vittoria ciclerebbe per sempre senza che
+    # nessun contatore avanzi (main thread bloccato).
+    _action_guard()
     if _world.won:
         return
-    _action_guard()
     hero = _world.hero
     dx, dy = DIRS[hero.facing]
     nx, ny = hero.x + dx, hero.y + dy
@@ -189,18 +193,18 @@ def move():
 
 
 def turn_left():
+    _action_guard()
     if _world.won:
         return
-    _action_guard()
     _world.hero.facing = _TURN_LEFT[_world.hero.facing]
     _emit({'t': 'turn', 'f': _world.hero.facing})
     _after_action()
 
 
 def turn_right():
+    _action_guard()
     if _world.won:
         return
-    _action_guard()
     _world.hero.facing = _TURN_RIGHT[_world.hero.facing]
     _emit({'t': 'turn', 'f': _world.hero.facing})
     _after_action()

From 02ec74aea628db3f1f11b80ea64e55d080a3f8eb Mon Sep 17 00:00:00 2001
From: Marco Farina <marco.farina@jcmaxwell.it>
Date: Fri, 3 Jul 2026 01:42:15 +0200
Subject: [PATCH 05/11] feat(pyquest): renderer+player, dati mondo e
 orchestrazione (fase 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Plugin Docusaurus `pyquest` che carica e valida a build-time i mondi in
static/pyquest/<world>/world.json (schema versionato, guardia quoting
sui campi iniettati nel motore Python). GameScene renderizza la griglia
e i personaggi, GamePlayer anima la trace step-by-step, applyEvent.ts
deriva lo stato del mondo da ogni evento. PyQuest/index.tsx orchestra
editor, esecuzione (runLevel) e animazione con la macchina a stati
idle → executing → animating → finished, esito won > failed > error.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V9dpQX4sKY6tJkTetJz3ho
---
 docs/pyquest-test.mdx                        |  70 ++--
 docusaurus.config.ts                         |   1 +
 plugins/pyquest/index.js                     | 287 +++++++++++++++
 src/components/PyQuest/GamePlayer.module.css | 133 +++++++
 src/components/PyQuest/GamePlayer.tsx        | 256 ++++++++++++++
 src/components/PyQuest/GameScene.module.css  | 349 ++++++++++++++++++
 src/components/PyQuest/GameScene.tsx         | 238 +++++++++++++
 src/components/PyQuest/PyQuest.module.css    |  87 +++++
 src/components/PyQuest/applyEvent.ts         | 115 ++++++
 src/components/PyQuest/characters.tsx        | 177 ++++++++++
 src/components/PyQuest/index.tsx             | 351 ++++++++++++-------
 src/components/PyQuest/runLevel.ts           |   2 +-
 src/components/PyQuest/useWorldData.ts       |  16 +
 static/pyquest/mondo-01/world.json           |  51 +++
 14 files changed, 1980 insertions(+), 153 deletions(-)
 create mode 100644 plugins/pyquest/index.js
 create mode 100644 src/components/PyQuest/GamePlayer.module.css
 create mode 100644 src/components/PyQuest/GamePlayer.tsx
 create mode 100644 src/components/PyQuest/GameScene.module.css
 create mode 100644 src/components/PyQuest/GameScene.tsx
 create mode 100644 src/components/PyQuest/PyQuest.module.css
 create mode 100644 src/components/PyQuest/applyEvent.ts
 create mode 100644 src/components/PyQuest/characters.tsx
 create mode 100644 src/components/PyQuest/useWorldData.ts
 create mode 100644 static/pyquest/mondo-01/world.json

diff --git a/docs/pyquest-test.mdx b/docs/pyquest-test.mdx
index 7c4f46c..1a9fa9d 100644
--- a/docs/pyquest-test.mdx
+++ b/docs/pyquest-test.mdx
@@ -1,39 +1,61 @@
 ---
 unlisted: true
 title: PyQuest — pagina di test
-description: Harness di verifica del motore PyQuest (trace-based, mini-giochi a griglia)
+description: Harness di verifica del motore + renderer PyQuest (mini-giochi a griglia)
 ---
 
-# PyQuest — sandbox di test del motore
+# PyQuest — sandbox di test
 
-Pagina temporanea per validare il **motore** di PyQuest (fase 1). Non è linkata
-dalla sidebar (`unlisted: true`): la raggiungi solo via URL `/docs/pyquest-test`.
-Qui il componente è in versione **harness**: editor + bottone Esegui + dump grezzo
-degli eventi emessi dal motore Python. Renderer e player arrivano nella fase 2.
+Pagina temporanea per validare **motore + renderer + player** di PyQuest (fasi
+1–2). Non è linkata dalla sidebar (`unlisted: true`): la raggiungi solo via URL
+`/docs/pyquest-test`. Il componente è ora giocabile end-to-end: editor + Esegui +
+board animata passo per passo.
 
-Il livello di default è una griglia 5×5 con Byte in `(1, 1)` rivolto a est e un
-muro a due celle di distanza.
+## 1. Livello dal plugin dati (world/level)
 
-## 1. Movimento base
+Livello `muoviti` del mondo `mondo-01` (livelli provvisori di collaudo),
+risolto dai global data del plugin `pyquest`. Il codice iniziale porta Byte
+sulla bandiera: premi Esegui e guarda l'animazione.
 
-Digita `for _ in range(3): move()` e premi Esegui: attesi `move`, `move`, `bump`
-(la terza mossa sbatte contro il muro).
+<PyQuest world="mondo-01" level="muoviti" />
 
-<PyQuest />
+## 2. Navigazione con i sensori
 
-## 2. Verifica indipendenza tra istanze
+Livello `attorno-al-muro`: c'è un blocco centrale da aggirare, più una gemma e un
+fantasma come scenografia (combat e raccolta arrivano nella fase 3). Prova a far
+arrivare Byte in basso a destra con un ciclo `while not on_goal()`.
 
-Due harness sullo stesso livello sulla stessa pagina: devono avere `codeId`
-diversi e trace indipendenti (esegui l'uno, l'altro resta fermo).
+<PyQuest world="mondo-01" level="attorno-al-muro" />
 
-<PyQuest />
+## 3. Indipendenza tra istanze
 
-## Note per la verifica (checklist step 5)
+Due istanze dello stesso livello sulla stessa pagina: devono avere trace e player
+indipendenti (esegui l'una, l'altra resta ferma).
 
-- **a)** `for _ in range(3): move()` → `move, move, bump`.
-- **b)** un errore a riga 2 (es. `move()` poi `boom`) → eventi fino a riga 1
-  **più** un traceback su stderr che indica **riga 2**.
-- **c)** due Esegui consecutivi producono trace identiche (nessuna
-  contaminazione tra run del modulo `pyquest` cacheato).
-- Prova anche `while not on_goal(): move()` e la vittoria (`win`) quando Byte
-  raggiunge `(3, 3)` — serve girare e muoversi (`turn_right()` + `move()`).
+<PyQuest world="mondo-01" level="muoviti" />
+
+## 4. Id ignoto
+
+Un `level` inesistente non deve ripiegare su un livello di riserva: atteso un
+pannello d'errore esplicito.
+
+<PyQuest world="mondo-01" level="non-esiste" />
+
+## Note per la verifica (checklist step 10-12)
+
+- **a)** Esegui il livello 1: attesi `move, move, turn, move, move`, poi
+  autoplay da passo 0 e — a fine animazione — il pannello di vittoria con il
+  flavor text di Byte.
+- **b)** Un errore nel codice (es. `boom` a riga 2) → trace parziale animata,
+  poi pannello «C'è un errore nel codice» col traceback (riga giusta).
+- **c)** `while True: move()` → pannello step limit nel tono di Byte; il
+  traceback resta in console.
+- **d)** Slider di seek, play/pausa, passo avanti/indietro, reset; le 4
+  velocità (0,5× 1× 2× 4×) scalano anche la durata delle transizioni.
+- **e)** `print()` interleaved compaiono in console solo quando l'animazione
+  raggiunge il passo in cui sono stati emessi.
+- **f)** Il livello 2 disegna gemma e fantasma fermi; Byte li attraversa
+  (niente combat/raccolta finché non arriva la fase 3). Sbattere più volte
+  contro il blocco centrale senza vincere → flavor «bump ripetuto».
+- **g)** Dark mode: board, sprite e pannelli esito leggibili in entrambi i
+  temi; la griglia scala col contenitore (`--pq-cell`).
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 5985ed5..05404a5 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -127,6 +127,7 @@ export default async function createConfig(): Promise<Config> {
 
     plugins: [
       './plugins/pyrunner/index.js',
+      './plugins/pyquest/index.js',
       './plugins/exercise-graph/index.js',
       './plugins/copy-page-md/index.js',
       [
diff --git a/plugins/pyquest/index.js b/plugins/pyquest/index.js
new file mode 100644
index 0000000..8adbcf8
--- /dev/null
+++ b/plugins/pyquest/index.js
@@ -0,0 +1,287 @@
+const path = require('path');
+const fs = require('fs');
+
+const PLUGIN_NAME = 'pyquest';
+
+const DEFAULT_OPTIONS = {
+  // I mondi vivono in static/pyquest/<world>/world.json (uno per cartella).
+  worldsDir: 'pyquest',
+};
+
+// I facing validi (specular a DIRS in static/bry-libs/pyquest.py).
+const FACINGS = ['north', 'east', 'south', 'west'];
+const ENEMY_BEHAVIORS = ['static', 'melee'];
+const WIN_TYPES = ['reach', 'collect', 'defeat'];
+// Versioni di schema che questo plugin sa leggere (spec D8).
+const KNOWN_SCHEMA_VERSIONS = [1];
+
+// --- Validazione build-time ---------------------------------------------------
+//
+// Fallire il build (throw) su dati malformati è coerente con `onBrokenLinks:
+// 'throw'`: meglio un mondo rotto che ferma la CI di un livello che esplode nel
+// browser dello studente.
+
+class WorldError extends Error {}
+
+/**
+ * Guardia quoting (spec step 7): i campi stringa che finiscono nel modello a
+ * runtime vengono iniettati in Python dentro una stringa triple-quoted
+ * (`'''<json>'''` in runLevel.ts). Un apice, una virgoletta o un backslash in
+ * quei campi potrebbero rompere quella stringa o iniettare codice. Li vietiamo
+ * a monte: sono identificatori corti d'autore (facing, kind, id, legenda,
+ * righe mappa), non prosa — nessuna ragione legittima per avere `'"\`.
+ */
+function assertSafeString(value, where) {
+  if (typeof value !== 'string') {
+    throw new WorldError(`${where}: atteso una stringa, trovato ${typeof value}.`);
+  }
+  if (/['"\\]/.test(value)) {
+    throw new WorldError(
+      `${where}: la stringa "${value}" contiene un carattere vietato (' " \\). ` +
+        'Questi campi vengono iniettati nel motore Python: usa solo identificatori semplici.',
+    );
+  }
+  // Niente caratteri di controllo (newline compresi): romperebbero il JSON su
+  // una riga o la stringa Python.
+  if (/[\x00-\x1f]/.test(value)) {  // eslint-disable-line no-control-regex
+    throw new WorldError(`${where}: la stringa contiene caratteri di controllo non ammessi.`);
+  }
+}
+
+function assertInt(value, where) {
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    throw new WorldError(`${where}: atteso un intero, trovato ${JSON.stringify(value)}.`);
+  }
+}
+
+function assertPoint(pt, where) {
+  if (!pt || typeof pt !== 'object') {
+    throw new WorldError(`${where}: atteso un punto {x, y}.`);
+  }
+  assertInt(pt.x, `${where}.x`);
+  assertInt(pt.y, `${where}.y`);
+}
+
+/**
+ * Geometria della griglia già validata: dimensioni + celle muro, per i check
+ * di posizione (entità dentro i bordi e mai su una cella `wall`).
+ */
+function gridGeometry(grid) {
+  const walls = new Set();
+  grid.rows.forEach((row, y) => {
+    Array.from(row).forEach((ch, x) => {
+      if (grid.legend[ch] === 'wall') walls.add(`${x},${y}`);
+    });
+  });
+  return { width: grid.rows[0].length, height: grid.rows.length, walls };
+}
+
+function assertOnFloor(pt, geo, where) {
+  if (pt.x < 0 || pt.y < 0 || pt.x >= geo.width || pt.y >= geo.height) {
+    throw new WorldError(
+      `${where}: (${pt.x}, ${pt.y}) è fuori dalla griglia ${geo.width}×${geo.height}.`,
+    );
+  }
+  if (geo.walls.has(`${pt.x},${pt.y}`)) {
+    throw new WorldError(`${where}: (${pt.x}, ${pt.y}) è su una cella muro.`);
+  }
+}
+
+function validateGrid(grid, where) {
+  if (!grid || typeof grid !== 'object') {
+    throw new WorldError(`${where}: manca la griglia.`);
+  }
+  const { legend, rows } = grid;
+  if (!legend || typeof legend !== 'object') {
+    throw new WorldError(`${where}.legend: attesa una mappa carattere→ruolo.`);
+  }
+  for (const [ch, role] of Object.entries(legend)) {
+    assertSafeString(ch, `${where}.legend (chiave)`);
+    assertSafeString(role, `${where}.legend['${ch}']`);
+  }
+  if (!Array.isArray(rows) || rows.length === 0) {
+    throw new WorldError(`${where}.rows: atteso un array non vuoto di righe.`);
+  }
+  const width = rows[0].length;
+  rows.forEach((row, i) => {
+    assertSafeString(row, `${where}.rows[${i}]`);
+    if (row.length !== width) {
+      throw new WorldError(
+        `${where}.rows[${i}]: larghezza ${row.length} ≠ ${width} (griglia non rettangolare).`,
+      );
+    }
+    for (const ch of row) {
+      if (!(ch in legend)) {
+        throw new WorldError(
+          `${where}.rows[${i}]: il carattere "${ch}" non è nella legenda.`,
+        );
+      }
+    }
+  });
+}
+
+function validateLevel(level, where) {
+  if (!level || typeof level !== 'object') {
+    throw new WorldError(`${where}: livello non valido.`);
+  }
+  assertSafeString(level.id, `${where}.id`);
+  if (typeof level.title !== 'string' || !level.title) {
+    throw new WorldError(`${where}.title: titolo mancante.`);
+  }
+
+  validateGrid(level.grid, `${where}.grid`);
+  const geo = gridGeometry(level.grid);
+
+  const { hero } = level;
+  assertPoint(hero, `${where}.hero`);
+  assertOnFloor(hero, geo, `${where}.hero`);
+  if (hero.facing !== undefined && !FACINGS.includes(hero.facing)) {
+    throw new WorldError(`${where}.hero.facing: "${hero.facing}" non è un facing valido.`);
+  }
+  if (hero.hp !== undefined) assertInt(hero.hp, `${where}.hero.hp`);
+
+  if (level.goal !== undefined) {
+    assertPoint(level.goal, `${where}.goal`);
+    assertOnFloor(level.goal, geo, `${where}.goal`);
+  }
+
+  const ids = new Set();
+  for (const [i, e] of (level.enemies ?? []).entries()) {
+    const w = `${where}.enemies[${i}]`;
+    assertSafeString(e.id, `${w}.id`);
+    if (ids.has(e.id)) throw new WorldError(`${w}.id: "${e.id}" duplicato.`);
+    ids.add(e.id);
+    assertSafeString(e.kind, `${w}.kind`);
+    assertPoint(e, w);
+    assertOnFloor(e, geo, w);
+    assertInt(e.hp, `${w}.hp`);
+    if (!ENEMY_BEHAVIORS.includes(e.behavior)) {
+      throw new WorldError(`${w}.behavior: "${e.behavior}" non valido (static|melee).`);
+    }
+  }
+  for (const [i, r] of (level.resources ?? []).entries()) {
+    const w = `${where}.resources[${i}]`;
+    assertSafeString(r.id, `${w}.id`);
+    if (ids.has(r.id)) throw new WorldError(`${w}.id: "${r.id}" duplicato.`);
+    ids.add(r.id);
+    assertSafeString(r.kind, `${w}.kind`);
+    assertPoint(r, w);
+    assertOnFloor(r, geo, w);
+  }
+
+  if (!Array.isArray(level.win) || level.win.length === 0) {
+    throw new WorldError(`${where}.win: attesa almeno una condizione di vittoria.`);
+  }
+  for (const [i, cond] of level.win.entries()) {
+    const w = `${where}.win[${i}]`;
+    if (!cond || !WIN_TYPES.includes(cond.type)) {
+      throw new WorldError(`${w}.type: atteso uno di ${WIN_TYPES.join('|')}.`);
+    }
+    if (cond.type === 'reach' && level.goal === undefined) {
+      throw new WorldError(`${w}: vittoria "reach" ma il livello non ha un goal.`);
+    }
+    if (cond.type === 'collect') {
+      assertSafeString(cond.kind, `${w}.kind`);
+      assertInt(cond.qty, `${w}.qty`);
+    }
+    if (cond.type === 'defeat') {
+      if (cond.kind !== undefined) assertSafeString(cond.kind, `${w}.kind`);
+      if (cond.count !== undefined) assertInt(cond.count, `${w}.count`);
+    }
+  }
+
+  if (typeof level.starterCode !== 'string') {
+    throw new WorldError(`${where}.starterCode: codice iniziale mancante.`);
+  }
+  if (
+    !Array.isArray(level.hints) ||
+    level.hints.length < 1 ||
+    level.hints.length > 3 ||
+    level.hints.some((h) => typeof h !== 'string' || !h)
+  ) {
+    throw new WorldError(`${where}.hints: attesi da 1 a 3 suggerimenti (stringhe non vuote).`);
+  }
+  if (level.maxSteps !== undefined) assertInt(level.maxSteps, `${where}.maxSteps`);
+  assertInt(level.par, `${where}.par`);
+  if (level.par < 1) {
+    throw new WorldError(`${where}.par: atteso ≥ 1, trovato ${level.par}.`);
+  }
+}
+
+function validateWorld(world, file) {
+  if (!world || typeof world !== 'object') {
+    throw new WorldError(`${file}: JSON del mondo non valido.`);
+  }
+  if (!KNOWN_SCHEMA_VERSIONS.includes(world.schemaVersion)) {
+    throw new WorldError(
+      `${file} → schemaVersion: ${JSON.stringify(world.schemaVersion)} non riconosciuta ` +
+        `(note: ${KNOWN_SCHEMA_VERSIONS.join(', ')}).`,
+    );
+  }
+  assertSafeString(world.id, `${file} → id`);
+  if (!Array.isArray(world.levels) || world.levels.length === 0) {
+    throw new WorldError(`${file}: il mondo non ha livelli.`);
+  }
+  const levelIds = new Set();
+  world.levels.forEach((lvl, i) => {
+    validateLevel(lvl, `${file} → levels[${i}] (${lvl && lvl.id})`);
+    if (levelIds.has(lvl.id)) {
+      throw new WorldError(`${file}: id livello "${lvl.id}" duplicato.`);
+    }
+    levelIds.add(lvl.id);
+  });
+}
+
+function loadWorlds(worldsAbsDir) {
+  const worlds = {};
+  if (!fs.existsSync(worldsAbsDir)) {
+    console.warn(
+      `[pyquest] Directory mondi non trovata: ${worldsAbsDir} — nessun mondo caricato.`,
+    );
+    return worlds;
+  }
+  for (const entry of fs.readdirSync(worldsAbsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const file = path.join(worldsAbsDir, entry.name, 'world.json');
+    if (!fs.existsSync(file)) continue;
+    let world;
+    try {
+      world = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    } catch (err) {
+      throw new WorldError(`${file}: JSON illeggibile — ${err.message}`);
+    }
+    validateWorld(world, file);
+    if (world.id in worlds) {
+      throw new WorldError(`[pyquest] id mondo "${world.id}" duplicato (${file}).`);
+    }
+    worlds[world.id] = world;
+  }
+  return worlds;
+}
+
+module.exports = function pyquestPlugin(context, pluginOptions = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...pluginOptions };
+  const staticRoot =
+    (context.siteConfig.staticDirectories &&
+      context.siteConfig.staticDirectories[0]) ||
+    'static';
+  const worldsAbsDir = path.join(context.siteDir, staticRoot, opts.worldsDir);
+
+  return {
+    name: PLUGIN_NAME,
+
+    async loadContent() {
+      return { worlds: loadWorlds(worldsAbsDir) };
+    },
+
+    async contentLoaded({ content, actions }) {
+      actions.setGlobalData({ worlds: content.worlds });
+    },
+
+    getPathsToWatch() {
+      return [path.join(worldsAbsDir, '**/world.json')];
+    },
+  };
+};
+
+module.exports.PLUGIN_NAME = PLUGIN_NAME;
diff --git a/src/components/PyQuest/GamePlayer.module.css b/src/components/PyQuest/GamePlayer.module.css
new file mode 100644
index 0000000..324f95d
--- /dev/null
+++ b/src/components/PyQuest/GamePlayer.module.css
@@ -0,0 +1,133 @@
+/* GamePlayer — board + slider di seek + barra dei comandi + console. */
+
+.player {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+/* --- Slider di seek ------------------------------------------------------ */
+
+.scrub {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.scrubInput {
+  flex: 1;
+  min-width: 0;
+  accent-color: var(--at-accent, #0270ad);
+  cursor: pointer;
+}
+
+.scrubInput:disabled {
+  cursor: default;
+  opacity: 0.4;
+}
+
+.counter {
+  font-family: var(--font-mono, ui-monospace, monospace);
+  font-size: 0.8rem;
+  opacity: 0.7;
+  min-width: 4.5em;
+  text-align: right;
+}
+
+/* --- Transport ----------------------------------------------------------- */
+
+.controls {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-wrap: wrap;
+}
+
+.btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 34px;
+  height: 34px;
+  border-radius: var(--radius-xs, 6px);
+  border: 1px solid var(--at-border, rgba(0, 0, 0, 0.08));
+  background: var(--at-bg-panel, rgba(255, 255, 255, 0.7));
+  color: inherit;
+  cursor: pointer;
+  transition:
+    background var(--dur-fast, 150ms) var(--ease-out),
+    transform var(--dur-fast, 150ms) var(--ease-out);
+}
+
+.btn:hover:not(:disabled) {
+  background: var(--at-bg-chip, rgba(0, 0, 0, 0.04));
+}
+
+.btn:active:not(:disabled) {
+  transform: scale(0.98);
+}
+
+.btn:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+.playBtn {
+  color: #fff;
+  background: var(--at-accent, #0270ad);
+  border-color: transparent;
+}
+
+.playBtn:hover:not(:disabled) {
+  background: var(--at-accent-soft, #0369a1);
+}
+
+.speed {
+  display: inline-flex;
+  margin-left: auto;
+  border: 1px solid var(--at-border, rgba(0, 0, 0, 0.08));
+  border-radius: var(--radius-pill, 999px);
+  overflow: hidden;
+}
+
+.speedBtn {
+  border: none;
+  background: transparent;
+  color: inherit;
+  font-size: 0.75rem;
+  padding: 5px 10px;
+  cursor: pointer;
+  transition: background var(--dur-fast, 150ms) var(--ease-out);
+}
+
+.speedBtn:hover {
+  background: var(--at-bg-chip, rgba(0, 0, 0, 0.04));
+}
+
+.speedActive {
+  background: var(--at-accent, #0270ad);
+  color: #fff;
+}
+
+.speedActive:hover {
+  background: var(--at-accent, #0270ad);
+}
+
+/* --- Console sincronizzata (print/traceback per atStep) ------------------- */
+
+.console {
+  margin: 0;
+  padding: 10px 12px;
+  border-radius: var(--radius-sm, 10px);
+  background: var(--at-bg-subtle, rgba(0, 0, 0, 0.025));
+  border: 1px solid var(--at-border, rgba(0, 0, 0, 0.08));
+  font-family: var(--font-mono, ui-monospace, monospace);
+  font-size: 0.8rem;
+  white-space: pre-wrap;
+  max-height: 200px;
+  overflow: auto;
+}
+
+.stderr {
+  color: var(--ifm-color-danger, #d6336c);
+}
diff --git a/src/components/PyQuest/GamePlayer.tsx b/src/components/PyQuest/GamePlayer.tsx
new file mode 100644
index 0000000..87c2a38
--- /dev/null
+++ b/src/components/PyQuest/GamePlayer.tsx
@@ -0,0 +1,256 @@
+/**
+ * GamePlayer — transport della trace PyQuest (riferimento diretto:
+ * src/components/Algorithm/Player.tsx, reducer e azioni identici).
+ *
+ * Riceve la trace completa di eventi (il motore è sincrono: arriva in ms) e
+ * deriva la scena al passo corrente con slice + reduce. Differenza voluta da
+ * Algorithm: al termine del run parte l'autoplay da passo 0 (lo studente ha
+ * premuto Esegui: vuole vedere il film) — il genitore lo segnala incrementando
+ * `playKey`.
+ *
+ * La durata delle transizioni della scena è iniettata come `--pq-dur`
+ * (DUR_MS[speedIdx]); la console mostra solo le righe di log con
+ * `atStep <= passo corrente` (sincronizzazione print/traceback ↔ animazione).
+ */
+
+import {
+  useEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  type CSSProperties,
+} from 'react';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import {
+  faPlay,
+  faPause,
+  faForwardStep,
+  faBackwardStep,
+  faRotateLeft,
+} from '@fortawesome/free-solid-svg-icons';
+import clsx from 'clsx';
+import GameScene from './GameScene';
+import { applyGameEvent, initScene } from './applyEvent';
+import type { GameEvent, LevelDef, LogLine } from './types';
+import styles from './GamePlayer.module.css';
+
+const SPEEDS = [0.5, 1, 2, 4];
+const TICK_MS = [700, 400, 220, 120];
+const DUR_MS = [520, 320, 180, 100];
+const DEFAULT_SPEED_IDX = 1;
+
+interface PlayerState {
+  stepIndex: number;
+  playing: boolean;
+  speedIdx: number;
+}
+
+type Action =
+  | { type: 'FWD' }
+  | { type: 'BACK' }
+  | { type: 'RESET' }
+  | { type: 'TOGGLE_PLAY' }
+  | { type: 'STOP' }
+  | { type: 'SEEK'; to: number }
+  | { type: 'SET_SPEED'; idx: number };
+
+export interface GamePlayerProps {
+  level: LevelDef;
+  character: string;
+  events: GameEvent[];
+  logs: LogLine[];
+  /** Incrementato dal genitore a ogni run: riparte da passo 0 in autoplay. */
+  playKey: number;
+  /** Notifica il passo corrente (il genitore vi deriva la fine animazione). */
+  onStepChange?: (step: number, total: number) => void;
+}
+
+export default function GamePlayer({
+  level,
+  character,
+  events,
+  logs,
+  playKey,
+  onStepChange,
+}: GamePlayerProps) {
+  const total = events.length;
+
+  const [state, dispatch] = useReducer(
+    (s: PlayerState, action: Action): PlayerState => {
+      switch (action.type) {
+        case 'FWD': {
+          const ni = Math.min(s.stepIndex + 1, total);
+          return {
+            ...s,
+            stepIndex: ni,
+            playing: ni >= total ? false : s.playing,
+          };
+        }
+        case 'BACK':
+          return {
+            ...s,
+            stepIndex: Math.max(s.stepIndex - 1, 0),
+            playing: false,
+          };
+        case 'RESET':
+          return { ...s, stepIndex: 0, playing: false };
+        case 'TOGGLE_PLAY':
+          if (s.stepIndex >= total)
+            return { ...s, stepIndex: 0, playing: true };
+          return { ...s, playing: !s.playing };
+        case 'STOP':
+          return { ...s, playing: false };
+        case 'SEEK':
+          return { ...s, stepIndex: action.to, playing: false };
+        case 'SET_SPEED':
+          return { ...s, speedIdx: action.idx };
+        default:
+          return s;
+      }
+    },
+    { stepIndex: 0, playing: false, speedIdx: DEFAULT_SPEED_IDX },
+  );
+
+  // Nuovo run: autoplay dal passo 0 (velocità conservata).
+  const firstRender = useRef(true);
+  useEffect(() => {
+    if (firstRender.current) {
+      firstRender.current = false;
+      return;
+    }
+    dispatch({ type: 'RESET' });
+    dispatch({ type: 'TOGGLE_PLAY' });
+  }, [playKey]);
+
+  // Autoplay.
+  useEffect(() => {
+    if (!state.playing) return undefined;
+    const id = setTimeout(
+      () => dispatch({ type: 'FWD' }),
+      TICK_MS[state.speedIdx],
+    );
+    return () => clearTimeout(id);
+  }, [state.playing, state.stepIndex, state.speedIdx]);
+
+  // Trace nuova più corta del cursore (run rieseguito): clamp in render.
+  const stepIndex = Math.min(state.stepIndex, total);
+
+  const scene = useMemo(
+    () => events.slice(0, stepIndex).reduce(applyGameEvent, initScene(level)),
+    [events, stepIndex, level],
+  );
+
+  useEffect(() => {
+    onStepChange?.(stepIndex, total);
+  }, [stepIndex, total, onStepChange]);
+
+  const atStart = stepIndex === 0;
+  const atEnd = stepIndex >= total;
+  const visibleLogs = logs.filter((l) => l.atStep <= stepIndex);
+
+  const durStyle = {
+    '--pq-dur': `${DUR_MS[state.speedIdx]}ms`,
+  } as CSSProperties;
+
+  return (
+    <div className={styles.player} style={durStyle}>
+      <GameScene
+        level={level}
+        character={character}
+        scene={scene}
+        fxKey={stepIndex}
+      />
+
+      <div className={styles.scrub}>
+        <input
+          className={styles.scrubInput}
+          type="range"
+          min={0}
+          max={total}
+          value={stepIndex}
+          disabled={total === 0}
+          aria-label="Posizione nella sequenza"
+          onChange={(e) =>
+            dispatch({ type: 'SEEK', to: Number(e.target.value) })
+          }
+        />
+        <span className={styles.counter}>
+          {stepIndex} / {total}
+        </span>
+      </div>
+
+      <div className={styles.controls}>
+        <button
+          type="button"
+          className={styles.btn}
+          onClick={() => dispatch({ type: 'RESET' })}
+          disabled={atStart}
+          aria-label="Torna all’inizio"
+          title="Torna all’inizio"
+        >
+          <FontAwesomeIcon icon={faRotateLeft} />
+        </button>
+        <button
+          type="button"
+          className={styles.btn}
+          onClick={() => dispatch({ type: 'BACK' })}
+          disabled={atStart}
+          aria-label="Passo indietro"
+          title="Passo indietro"
+        >
+          <FontAwesomeIcon icon={faBackwardStep} />
+        </button>
+        <button
+          type="button"
+          className={clsx(styles.btn, styles.playBtn)}
+          onClick={() => dispatch({ type: 'TOGGLE_PLAY' })}
+          disabled={total === 0}
+          aria-label={state.playing ? 'Pausa' : 'Riproduci'}
+          title={state.playing ? 'Pausa' : 'Riproduci'}
+        >
+          <FontAwesomeIcon icon={state.playing ? faPause : faPlay} />
+        </button>
+        <button
+          type="button"
+          className={styles.btn}
+          onClick={() => dispatch({ type: 'FWD' })}
+          disabled={atEnd}
+          aria-label="Passo avanti"
+          title="Passo avanti"
+        >
+          <FontAwesomeIcon icon={faForwardStep} />
+        </button>
+
+        <div className={styles.speed} role="group" aria-label="Velocità">
+          {SPEEDS.map((sp, i) => (
+            <button
+              key={sp}
+              type="button"
+              className={clsx(
+                styles.speedBtn,
+                i === state.speedIdx && styles.speedActive,
+              )}
+              onClick={() => dispatch({ type: 'SET_SPEED', idx: i })}
+              aria-pressed={i === state.speedIdx}
+            >
+              {String(sp).replace('.', ',')}×
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {visibleLogs.length > 0 && (
+        <pre className={styles.console} aria-live="polite">
+          {visibleLogs.map((l, i) => (
+            <span
+              key={i}
+              className={l.kind === 'stderr' ? styles.stderr : undefined}
+            >
+              {l.text}
+            </span>
+          ))}
+        </pre>
+      )}
+    </div>
+  );
+}
diff --git a/src/components/PyQuest/GameScene.module.css b/src/components/PyQuest/GameScene.module.css
new file mode 100644
index 0000000..94a9278
--- /dev/null
+++ b/src/components/PyQuest/GameScene.module.css
@@ -0,0 +1,349 @@
+/* GameScene — board a griglia + entità posizionate per trasformazione.
+   Le entità animano il movimento via transition su `transform`; la durata è
+   `--pq-dur`, iniettata dal GamePlayer in base alla velocità scelta. Gli
+   effetti one-shot (fx) sono keyframes rimontate a ogni passo (key cangiante).
+   `--pq-cell` è calcolata dal renderer (ResizeObserver): min(48px, larghezza
+   contenitore / colonne). */
+
+.scene {
+  /* Tema di scena (light). Override dark in fondo, con selettore
+     html[data-theme='dark'] per evitare il gotcha oklch/P3 su display wide. */
+  --pq-board-bg: #e9edf2;
+  --pq-floor: #f5f7fa;
+  --pq-wall: #40495b;
+  --pq-grid-line: rgba(0, 0, 0, 0.06);
+  --pq-hero: var(--at-accent, #0270ad);
+  --pq-hero-track: #3d4759;
+  --pq-hero-panel: rgba(255, 255, 255, 0.35);
+  --pq-hero-led-ring: #ffffff;
+  --pq-hero-led: #22b8cf;
+  --pq-monty: #2f9e44;
+  --pq-monty-hat: #8d6e3f;
+  --pq-monty-eye: #1a1a1a;
+  --pq-enemy: #d6336c;
+  --pq-resource: #f08c00;
+  --pq-goal: #2f9e44;
+
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  align-items: flex-start;
+  width: 100%;
+}
+
+.board {
+  position: relative;
+  width: calc(var(--pq-cols) * var(--pq-cell));
+  height: calc(var(--pq-rows) * var(--pq-cell));
+  max-width: 100%;
+  background: var(--pq-board-bg);
+  border-radius: var(--radius-sm, 10px);
+  border: 1px solid var(--at-border, rgba(0, 0, 0, 0.08));
+  box-shadow: var(--shadow-card);
+  overflow: hidden;
+}
+
+/* Base comune a celle ed entità: box grande una cella, posizionato per
+   trasformazione tramite le custom property --pq-x/--pq-y. */
+.floor,
+.wall,
+.goal,
+.resource,
+.enemy,
+.hero,
+.fx {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--pq-cell);
+  height: var(--pq-cell);
+  transform: translate(
+    calc(var(--pq-x) * var(--pq-cell)),
+    calc(var(--pq-y) * var(--pq-cell))
+  );
+}
+
+/* --- Celle -------------------------------------------------------------- */
+
+.floor,
+.wall {
+  padding: 1px;
+  background-clip: content-box;
+  box-shadow: inset 0 0 0 1px var(--pq-grid-line);
+}
+
+.floor {
+  background-color: var(--pq-floor);
+}
+
+.wall {
+  background-color: var(--pq-wall);
+}
+
+/* --- Entità ------------------------------------------------------------- */
+
+.goal,
+.resource,
+.enemy,
+.hero {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: calc(var(--pq-cell) * 0.5);
+  pointer-events: none;
+}
+
+.goal {
+  color: var(--pq-goal);
+  font-size: calc(var(--pq-cell) * 0.42);
+  opacity: 0.85;
+}
+
+.resource {
+  animation: pq-float 2.4s var(--ease-smooth, ease-in-out) infinite;
+  filter: drop-shadow(0 1px 1px rgba(0, 0, 0, 0.25));
+  transition:
+    opacity var(--pq-dur, 320ms) var(--ease-out),
+    scale var(--pq-dur, 320ms) var(--ease-out);
+}
+
+/* Raccolta: resta montata (identità DOM stabile), svanisce e basta. */
+.collected {
+  opacity: 0;
+  scale: 0.3;
+  animation: none;
+}
+
+.enemy {
+  filter: drop-shadow(0 1px 1px rgba(0, 0, 0, 0.25));
+  transition:
+    transform var(--pq-dur, 320ms) var(--ease-smooth),
+    opacity var(--pq-dur, 320ms) var(--ease-out),
+    scale var(--pq-dur, 320ms) var(--ease-out);
+}
+
+/* Sconfitto: resta montato, dissolvenza. */
+.dead {
+  opacity: 0;
+  scale: 0.4;
+}
+
+/* Pips HP del nemico (un puntino per PV). */
+.enemyPips {
+  position: absolute;
+  top: 3px;
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  gap: 2px;
+}
+
+.pip {
+  width: 4px;
+  height: 4px;
+  border-radius: var(--radius-circle, 50%);
+  background: var(--pq-enemy);
+  box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.65);
+}
+
+/* L'eroe anima lo spostamento tra celle. */
+.hero {
+  transition: transform var(--pq-dur, 320ms) var(--ease-smooth);
+  z-index: 2;
+  filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.3));
+}
+
+/* Wrapper degli effetti one-shot sull'eroe: rimontato (key cangiante) a ogni
+   fx, così la keyframe riparte anche su bump consecutivi. */
+.heroFxWrap {
+  display: block;
+  width: 100%;
+  height: 100%;
+  padding: 12%;
+}
+
+/* Lo sprite ruota col facing (disegnato rivolto a nord). */
+.sprite {
+  display: block;
+  width: 100%;
+  height: 100%;
+  transition: transform var(--pq-dur, 320ms) var(--ease-smooth);
+}
+
+/* --- Effetti one-shot --------------------------------------------------- */
+
+.fx {
+  z-index: 3;
+  pointer-events: none;
+}
+
+.fx_attack::after,
+.fx_defeat::after,
+.fx_collect::after {
+  content: '';
+  position: absolute;
+  inset: 15%;
+  border-radius: var(--radius-circle, 50%);
+}
+
+.fx_attack::after {
+  border: 2px solid var(--pq-enemy);
+  animation: pq-ring var(--pq-dur, 320ms) var(--ease-out) forwards;
+}
+
+.fx_collect::after {
+  background: radial-gradient(circle, var(--pq-resource) 0%, transparent 70%);
+  animation: pq-pop var(--pq-dur, 320ms) var(--ease-spring) forwards;
+}
+
+.fx_defeat::after {
+  border: 2px solid var(--pq-enemy);
+  animation: pq-pop var(--pq-dur, 320ms) var(--ease-out) forwards;
+}
+
+/* Effetti applicati direttamente sull'eroe. */
+.bump {
+  animation: pq-shake var(--pq-dur, 320ms) var(--ease-out);
+}
+
+.heroHit {
+  animation: pq-flash var(--pq-dur, 320ms) var(--ease-out);
+}
+
+@keyframes pq-float {
+  0%,
+  100% {
+    margin-top: 0;
+  }
+  50% {
+    margin-top: -3px;
+  }
+}
+
+@keyframes pq-shake {
+  0%,
+  100% {
+    translate: 0;
+  }
+  25% {
+    translate: -4px 0;
+  }
+  75% {
+    translate: 4px 0;
+  }
+}
+
+@keyframes pq-flash {
+  0%,
+  100% {
+    filter: none;
+  }
+  50% {
+    filter: drop-shadow(0 0 6px var(--pq-enemy)) brightness(1.4);
+  }
+}
+
+@keyframes pq-ring {
+  from {
+    transform: scale(0.4);
+    opacity: 0.9;
+  }
+  to {
+    transform: scale(1.3);
+    opacity: 0;
+  }
+}
+
+@keyframes pq-pop {
+  from {
+    transform: scale(0.2);
+    opacity: 0.9;
+  }
+  to {
+    transform: scale(1.2);
+    opacity: 0;
+  }
+}
+
+/* --- HUD ---------------------------------------------------------------- */
+
+.hud {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+  min-height: 1.6rem;
+}
+
+.hp {
+  display: inline-flex;
+  gap: 3px;
+  color: #e03131;
+}
+
+.hpPip {
+  font-size: 0.95rem;
+}
+
+.inventory {
+  display: inline-flex;
+  gap: 6px;
+}
+
+.invChip {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 0.8rem;
+  padding: 2px 8px;
+  border-radius: var(--radius-pill, 999px);
+  background: var(--at-bg-chip, rgba(0, 0, 0, 0.04));
+  color: var(--pq-resource);
+}
+
+.badge {
+  font-size: 0.82rem;
+  font-weight: 700;
+  padding: 3px 10px;
+  border-radius: var(--radius-pill, 999px);
+}
+
+.badgeWin {
+  color: #fff;
+  background: var(--pq-goal);
+}
+
+.badgeFail {
+  color: #fff;
+  background: var(--pq-enemy);
+}
+
+/* --- Dark: override del tema di scena (html[data-theme] contro gotcha P3) - */
+
+:global(html[data-theme='dark']) .scene {
+  --pq-board-bg: #14161c;
+  --pq-floor: #1e2230;
+  --pq-wall: #2b3245;
+  --pq-grid-line: rgba(255, 255, 255, 0.05);
+  --pq-hero: var(--at-accent, #38bdf8);
+  --pq-hero-track: #566178;
+  --pq-hero-panel: rgba(0, 0, 0, 0.25);
+  --pq-hero-led-ring: #10131a;
+  --pq-hero-led: #3bc9db;
+  --pq-monty: #51cf66;
+  --pq-monty-hat: #a98953;
+  --pq-monty-eye: #10131a;
+  --pq-enemy: #f06595;
+  --pq-resource: #ffc078;
+  --pq-goal: #51cf66;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hero,
+  .enemy,
+  .resource,
+  .sprite {
+    transition: none;
+    animation: none;
+  }
+}
diff --git a/src/components/PyQuest/GameScene.tsx b/src/components/PyQuest/GameScene.tsx
new file mode 100644
index 0000000..2e6dbab
--- /dev/null
+++ b/src/components/PyQuest/GameScene.tsx
@@ -0,0 +1,238 @@
+/**
+ * GameScene — renderer DOM+CSS di uno stato di scena PyQuest (spec D5).
+ *
+ * Puro e derivato: riceve un `SceneState` (già ridotto dalla trace da
+ * applyEvent) e lo disegna. Nessuna logica di gioco, nessun timer: le
+ * animazioni sono transizioni CSS sulle posizioni (durata `--pq-dur`, iniettata
+ * dal player in base alla velocità) più effetti one-shot legati a `scene.fx`.
+ *
+ * Identità DOM stabile: nemici morti e risorse raccolte NON vengono smontati —
+ * restano nel DOM con le classi `dead`/`collected` (dissolvenza CSS), così le
+ * transizioni e lo scrubbing all'indietro funzionano senza remount.
+ *
+ * `fxKey` cambia a ogni passo del player: è la `key` degli elementi effetto,
+ * così due fx consecutivi dello stesso tipo rimontano il nodo e la keyframe
+ * riparte.
+ */
+
+import { useEffect, useRef, useState } from 'react';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import clsx from 'clsx';
+import type { CSSProperties } from 'react';
+import {
+  characterDef,
+  enemyVisual,
+  resourceVisual,
+  GOAL_ICON,
+  HP_ICON,
+} from './characters';
+import type { Facing, LevelDef, SceneState } from './types';
+import styles from './GameScene.module.css';
+
+/** Lato massimo di una cella (px); sotto, la griglia scala col contenitore. */
+const MAX_CELL_PX = 48;
+
+// Gradi di rotazione dello sprite per facing (disegnato rivolto a nord).
+const FACING_DEG: Record<Facing, number> = {
+  north: 0,
+  east: 90,
+  south: 180,
+  west: 270,
+};
+
+interface CellStyle extends CSSProperties {
+  '--pq-x'?: number;
+  '--pq-y'?: number;
+}
+
+function cellVars(x: number, y: number): CellStyle {
+  return { '--pq-x': x, '--pq-y': y };
+}
+
+export interface GameSceneProps {
+  level: LevelDef;
+  character: string;
+  scene: SceneState;
+  /** Cambia a ogni passo: fa ripartire le animazioni one-shot. */
+  fxKey: number;
+}
+
+export default function GameScene({
+  level,
+  character,
+  scene,
+  fxKey,
+}: GameSceneProps) {
+  const rows = level.grid.rows;
+  const height = rows.length;
+  const width = rows.length > 0 ? rows[0].length : 0;
+  const legend = level.grid.legend;
+  const char = characterDef(character);
+
+  // --pq-cell = min(48px, larghezza contenitore / colonne) via ResizeObserver.
+  const wrapRef = useRef<HTMLDivElement | null>(null);
+  const [cellPx, setCellPx] = useState(MAX_CELL_PX);
+  useEffect(() => {
+    const el = wrapRef.current;
+    if (!el || typeof ResizeObserver === 'undefined') return undefined;
+    const ro = new ResizeObserver((entries) => {
+      const w = entries[0]?.contentRect.width ?? 0;
+      if (w > 0 && width > 0) {
+        setCellPx(Math.min(MAX_CELL_PX, Math.floor(w / width)));
+      }
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [width]);
+
+  const boardStyle = {
+    '--pq-cols': width,
+    '--pq-rows': height,
+    '--pq-cell': `${cellPx}px`,
+  } as CSSProperties as CellStyle;
+
+  const heroFx =
+    scene.fx?.kind === 'bump' || scene.fx?.kind === 'hero_hit'
+      ? scene.fx.kind
+      : null;
+
+  return (
+    <div ref={wrapRef} className={styles.scene}>
+      <div
+        className={styles.board}
+        style={boardStyle}
+        role="img"
+        aria-label={`Griglia ${width}×${height}, ${char.name} in (${scene.hero.x}, ${scene.hero.y})`}
+      >
+        {/* Griglia di celle (pavimento/muro). */}
+        {rows.map((row, y) =>
+          Array.from(row).map((ch, x) => {
+            const wall = legend[ch] === 'wall';
+            return (
+              <div
+                key={`${x},${y}`}
+                className={wall ? styles.wall : styles.floor}
+                style={cellVars(x, y)}
+              />
+            );
+          }),
+        )}
+
+        {/* Goal (sotto le entità: l'eroe ci sale sopra). */}
+        {level.goal && (
+          <div
+            className={styles.goal}
+            style={cellVars(level.goal.x, level.goal.y)}
+          >
+            <FontAwesomeIcon icon={GOAL_ICON} />
+          </div>
+        )}
+
+        {/* Risorse: sempre montate; da raccolte restano con la classe
+            `collected` (dissolvenza), mai smontate. */}
+        {Object.entries(scene.resources).map(([id, r]) => {
+          const v = resourceVisual(r.kind);
+          return (
+            <div
+              key={id}
+              className={clsx(styles.resource, r.collected && styles.collected)}
+              style={{ ...cellVars(r.x, r.y), color: v.color }}
+              aria-label={r.collected ? undefined : v.label}
+              aria-hidden={r.collected || undefined}
+            >
+              <FontAwesomeIcon icon={v.icon} />
+            </div>
+          );
+        })}
+
+        {/* Nemici: sempre montati; da morti restano con la classe `dead`. */}
+        {Object.entries(scene.enemies).map(([id, e]) => {
+          const v = enemyVisual(e.kind);
+          return (
+            <div
+              key={id}
+              className={clsx(styles.enemy, !e.alive && styles.dead)}
+              style={{ ...cellVars(e.x, e.y), color: v.color }}
+              aria-label={e.alive ? `${v.label}, ${e.hp} PV` : undefined}
+              aria-hidden={!e.alive || undefined}
+            >
+              <FontAwesomeIcon icon={v.icon} />
+              {e.alive && e.hp > 0 && (
+                <span className={styles.enemyPips} aria-hidden="true">
+                  {Array.from({ length: e.hp }).map((_, i) => (
+                    <span key={i} className={styles.pip} />
+                  ))}
+                </span>
+              )}
+            </div>
+          );
+        })}
+
+        {/* Eroe: il div esterno anima la posizione (transition su transform),
+            il wrapper interno porta gli effetti one-shot (key cangiante),
+            lo sprite interno ruota col facing. */}
+        <div
+          className={styles.hero}
+          style={cellVars(scene.hero.x, scene.hero.y)}
+        >
+          <span
+            key={heroFx ? `fx-${fxKey}` : 'idle'}
+            className={clsx(
+              styles.heroFxWrap,
+              heroFx === 'bump' && styles.bump,
+              heroFx === 'hero_hit' && styles.heroHit,
+            )}
+          >
+            <span
+              className={styles.sprite}
+              style={{
+                transform: `rotate(${FACING_DEG[scene.hero.facing]}deg)`,
+              }}
+            >
+              {char.sprite}
+            </span>
+          </span>
+        </div>
+
+        {/* Effetto one-shot posizionale (attacco/raccolta/sconfitta). */}
+        {scene.fx && scene.fx.at && !heroFx && (
+          <div
+            key={`fx-${fxKey}`}
+            className={clsx(styles.fx, styles[`fx_${scene.fx.kind}`])}
+            style={cellVars(scene.fx.at.x, scene.fx.at.y)}
+          />
+        )}
+      </div>
+
+      {/* HUD di scena: PV, inventario, esito (precedenza won > failed). */}
+      <div className={styles.hud}>
+        <div className={styles.hp} aria-label={`${scene.hero.hp} punti vita`}>
+          {Array.from({ length: Math.max(scene.hero.hp, 0) }).map((_, i) => (
+            <FontAwesomeIcon key={i} icon={HP_ICON} className={styles.hpPip} />
+          ))}
+        </div>
+        <div className={styles.inventory}>
+          {Object.entries(scene.inventory).map(([kind, n]) => {
+            const v = resourceVisual(kind);
+            return (
+              <span key={kind} className={styles.invChip}>
+                <FontAwesomeIcon icon={v.icon} /> {n}
+              </span>
+            );
+          })}
+        </div>
+        {scene.won ? (
+          <span className={clsx(styles.badge, styles.badgeWin)}>Vittoria!</span>
+        ) : scene.dead ? (
+          <span className={clsx(styles.badge, styles.badgeFail)}>
+            {char.name} è caduto
+          </span>
+        ) : scene.stepLimit ? (
+          <span className={clsx(styles.badge, styles.badgeFail)}>
+            Troppe mosse
+          </span>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/PyQuest/PyQuest.module.css b/src/components/PyQuest/PyQuest.module.css
new file mode 100644
index 0000000..99a3e62
--- /dev/null
+++ b/src/components/PyQuest/PyQuest.module.css
@@ -0,0 +1,87 @@
+/* PyQuest — layout del componente giocabile: scena a sinistra, editor a destra
+   (impilati su schermi stretti). L'editor riusa toolbar e stili di PyRunner;
+   qui vivono solo il layout e i pannelli di esito (flavor text, D13).
+   Niente bordo-sinistra colorato: gli esiti si distinguono per sfondo. */
+
+.root {
+  margin: 1.5rem 0;
+}
+
+.layout {
+  display: grid;
+  grid-template-columns: minmax(0, auto) minmax(280px, 1fr);
+  gap: 20px;
+  align-items: start;
+}
+
+@media (max-width: 820px) {
+  .layout {
+    grid-template-columns: 1fr;
+  }
+}
+
+.stage {
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.editorCol {
+  min-width: 0;
+}
+
+/* --- Pannelli di esito ---------------------------------------------------- */
+
+.panel {
+  padding: 12px 14px;
+  border-radius: var(--radius-sm, 10px);
+  border: 1px solid var(--at-border, rgba(0, 0, 0, 0.08));
+  font-size: 0.92rem;
+  line-height: 1.5;
+}
+
+.panelWin {
+  background: color-mix(in srgb, #2f9e44 12%, transparent);
+  border-color: color-mix(in srgb, #2f9e44 35%, transparent);
+}
+
+.panelFail {
+  background: color-mix(in srgb, #d6336c 10%, transparent);
+  border-color: color-mix(in srgb, #d6336c 30%, transparent);
+}
+
+.panelError {
+  background: color-mix(in srgb, #d6336c 6%, transparent);
+  border-color: color-mix(in srgb, #d6336c 25%, transparent);
+}
+
+.panelNeutral {
+  background: var(--at-bg-subtle, rgba(0, 0, 0, 0.025));
+}
+
+.panelTitle {
+  margin: 0 0 6px;
+  font-weight: 700;
+}
+
+.traceback {
+  margin: 0;
+  padding: 8px 10px;
+  border-radius: var(--radius-xs, 6px);
+  background: var(--at-bg-subtle, rgba(0, 0, 0, 0.04));
+  font-family: var(--font-mono, ui-monospace, monospace);
+  font-size: 0.78rem;
+  white-space: pre-wrap;
+  max-height: 180px;
+  overflow: auto;
+}
+
+/* --- Errori di configurazione (props/plugin) ------------------------------ */
+
+.error {
+  margin: 1.5rem 0;
+  padding: 12px;
+  border: 1px solid var(--at-border, rgba(0, 0, 0, 0.08));
+  border-radius: var(--radius-sm, 10px);
+}
diff --git a/src/components/PyQuest/applyEvent.ts b/src/components/PyQuest/applyEvent.ts
new file mode 100644
index 0000000..be7db87
--- /dev/null
+++ b/src/components/PyQuest/applyEvent.ts
@@ -0,0 +1,115 @@
+/**
+ * Riduttore di scena PyQuest (pattern Algorithm/applyStep.ts).
+ *
+ * Il motore Python emette una trace di `GameEvent` (via `runLevel`); la scena a
+ * un dato passo è derivata: `events.slice(0, step).reduce(applyGameEvent,
+ * initScene(level))`. Riduttore puro → seek, step-back e replay gratis.
+ *
+ * Il campo `fx` è **transiente**: descrive un'animazione one-shot (bump, colpo,
+ * raccolta…) valida solo per il passo che l'ha generata. Ogni `applyGameEvent`
+ * lo azzera e lo re-imposta solo se l'evento corrente lo richiede.
+ */
+
+import type { GameEvent, LevelDef, SceneState } from './types';
+
+/** Stato di scena al passo 0: derivato dal livello, prima di ogni evento. */
+export function initScene(level: LevelDef): SceneState {
+  const enemies: SceneState['enemies'] = {};
+  for (const e of level.enemies ?? []) {
+    enemies[e.id] = { kind: e.kind, x: e.x, y: e.y, hp: e.hp, alive: true };
+  }
+  const resources: SceneState['resources'] = {};
+  for (const r of level.resources ?? []) {
+    resources[r.id] = { kind: r.kind, x: r.x, y: r.y, collected: false };
+  }
+  return {
+    hero: {
+      x: level.hero.x,
+      y: level.hero.y,
+      facing: level.hero.facing,
+      hp: level.hero.hp,
+    },
+    enemies,
+    resources,
+    inventory: {},
+    won: false,
+    dead: false,
+    stepLimit: false,
+    fx: null,
+  };
+}
+
+/** Applica un evento a uno stato, restituendo un nuovo stato (immutabile). */
+export function applyGameEvent(prev: SceneState, ev: GameEvent): SceneState {
+  // Clona in superficie: `fx` riparte sempre da null (transiente).
+  const s: SceneState = {
+    ...prev,
+    hero: { ...prev.hero },
+    enemies: { ...prev.enemies },
+    resources: { ...prev.resources },
+    inventory: { ...prev.inventory },
+    fx: null,
+  };
+
+  switch (ev.t) {
+    case 'move':
+      s.hero.x = ev.x;
+      s.hero.y = ev.y;
+      s.hero.facing = ev.f;
+      break;
+    case 'turn':
+      s.hero.facing = ev.f;
+      break;
+    case 'bump':
+      s.fx = { kind: 'bump', at: { x: ev.x, y: ev.y } };
+      break;
+    case 'attack':
+      s.fx = { kind: 'attack', at: { x: ev.x, y: ev.y } };
+      break;
+    case 'enemy_hit': {
+      const e = s.enemies[ev.id];
+      if (e) s.enemies[ev.id] = { ...e, hp: ev.hp };
+      break;
+    }
+    case 'defeat': {
+      const e = s.enemies[ev.id];
+      if (e) {
+        s.enemies[ev.id] = { ...e, hp: 0, alive: false };
+        s.fx = { kind: 'defeat', at: { x: e.x, y: e.y } };
+      }
+      break;
+    }
+    case 'enemy_move': {
+      const e = s.enemies[ev.id];
+      if (e) s.enemies[ev.id] = { ...e, x: ev.x, y: ev.y };
+      break;
+    }
+    case 'hero_hit':
+      s.hero.hp = ev.hp;
+      s.fx = { kind: 'hero_hit', at: { x: s.hero.x, y: s.hero.y } };
+      break;
+    case 'collect': {
+      const r = s.resources[ev.id];
+      if (r) s.resources[ev.id] = { ...r, collected: true };
+      s.inventory[ev.kind] = (s.inventory[ev.kind] ?? 0) + 1;
+      s.fx = { kind: 'collect', at: { x: s.hero.x, y: s.hero.y } };
+      break;
+    }
+    case 'win':
+      s.won = true;
+      break;
+    case 'death':
+      s.dead = true;
+      break;
+    case 'step_limit':
+      s.stepLimit = true;
+      break;
+    default: {
+      // Exhaustive check: se GameEvent cresce, il compilatore segnala qui.
+      const _exhaustive: never = ev;
+      return _exhaustive;
+    }
+  }
+
+  return s;
+}
diff --git a/src/components/PyQuest/characters.tsx b/src/components/PyQuest/characters.tsx
new file mode 100644
index 0000000..25aaae2
--- /dev/null
+++ b/src/components/PyQuest/characters.tsx
@@ -0,0 +1,177 @@
+/**
+ * Registry data-driven dei personaggi PyQuest (spec D13).
+ *
+ * Ogni personaggio ha uno sprite SVG inline (colori via CSS var → dark mode
+ * gratis, definite in GameScene.module.css) e i flavor text di esito nel suo
+ * registro. Lo sprite è disegnato in vista dall'alto rivolto a nord: il
+ * renderer lo orienta nelle 4 direzioni con una rotate.
+ *
+ * V1 implementa Byte completo; `monty` è la predisposizione dati per il volume
+ * futuro (sprite placeholder, la struttura è quella definitiva).
+ */
+
+import type { ReactElement } from 'react';
+import type { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import {
+  faGhost,
+  faSkull,
+  faDragon,
+  faSpider,
+  faBug,
+  faGem,
+  faKey,
+  faCoins,
+  faStar,
+  faHeart,
+  faFlagCheckered,
+} from '@fortawesome/free-solid-svg-icons';
+
+export interface CharacterDef {
+  /** Nome proprio, usato nei pannelli di esito. */
+  name: string;
+  /** Sprite SVG inline, vista dall'alto, rivolto a nord (il renderer ruota). */
+  sprite: ReactElement;
+  /** Flavor text di esito, nel registro del personaggio (sarcasmo ≈3/5). */
+  flavor: {
+    win: string;
+    death: string;
+    stepLimit: (maxSteps: number) => string;
+    /** Bump ripetuto: il codice è terminato ma l'eroe ha sbattuto più volte. */
+    bump: string;
+  };
+}
+
+/* Byte, il droide esploratore: corpo circolare con cingoli laterali e un
+   occhio-LED al «muso» che rende leggibile il facing anche ruotato. Sprite
+   provvisorio «da validare» (l'asset definitivo può sostituirlo qui). */
+const byteSprite = (
+  <svg viewBox="0 0 48 48" width="100%" height="100%" aria-hidden="true">
+    {/* cingoli */}
+    <rect
+      x="4"
+      y="12"
+      width="7"
+      height="26"
+      rx="3.5"
+      fill="var(--pq-hero-track)"
+    />
+    <rect
+      x="37"
+      y="12"
+      width="7"
+      height="26"
+      rx="3.5"
+      fill="var(--pq-hero-track)"
+    />
+    {/* corpo */}
+    <circle cx="24" cy="25" r="14" fill="var(--pq-hero)" />
+    {/* muso: indica la direzione di marcia */}
+    <path d="M17 15 L24 4 L31 15 Z" fill="var(--pq-hero)" />
+    {/* occhio-LED */}
+    <circle cx="24" cy="14" r="5" fill="var(--pq-hero-led-ring)" />
+    <circle cx="24" cy="14" r="2.6" fill="var(--pq-hero-led)" />
+    {/* pannello dorsale */}
+    <rect
+      x="18"
+      y="24"
+      width="12"
+      height="8"
+      rx="2"
+      fill="var(--pq-hero-panel)"
+    />
+  </svg>
+);
+
+/* Monty, il pitone col cappello (volume futuro): placeholder minimale, la
+   entry esiste solo perché la struttura dati deve esserci già in v1. */
+const montySprite = (
+  <svg viewBox="0 0 48 48" width="100%" height="100%" aria-hidden="true">
+    <circle cx="24" cy="26" r="13" fill="var(--pq-monty)" />
+    {/* tesa e calotta del cappello da esploratore */}
+    <ellipse cx="24" cy="14" rx="13" ry="4" fill="var(--pq-monty-hat)" />
+    <path d="M16 14 Q24 2 32 14 Z" fill="var(--pq-monty-hat)" />
+    <circle cx="19" cy="24" r="2" fill="var(--pq-monty-eye)" />
+    <circle cx="29" cy="24" r="2" fill="var(--pq-monty-eye)" />
+  </svg>
+);
+
+export const CHARACTERS: Record<string, CharacterDef> = {
+  byte: {
+    name: 'Byte',
+    sprite: byteSprite,
+    flavor: {
+      win: 'Obiettivo raggiunto. I miei circuiti esultano — in binario, ovviamente.',
+      death:
+        'Integrità dello scafo: 0%. Nel mio report scriverò «atterraggio molto ravvicinato su un nemico». Riavviami e riproviamo.',
+      stepLimit: (maxSteps) =>
+        `${maxSteps + 1} mosse e nessuna uscita: o il labirinto è infinito, o quel \`while\` non si ferma mai. Scommetto sul \`while\`.`,
+      bump: 'Hai sbattuto contro un muro. Di nuovo. Aggiorno il mio report assicurativo.',
+    },
+  },
+  monty: {
+    name: 'Monty',
+    sprite: montySprite,
+    flavor: {
+      win: 'Missione compiuta. Niente applausi, grazie: mi cadrebbe il cappello.',
+      death: 'Sono svenuto nel modo più dignitoso possibile. Riproviamo.',
+      stepLimit: (maxSteps) =>
+        `${maxSteps} mosse senza arrivare da nessuna parte. Persino io mi sono annoiato, e sono un rettile.`,
+      bump: 'Quel muro era lì anche il turno scorso. E anche quello prima.',
+    },
+  },
+};
+
+const CHARACTER_FALLBACK = CHARACTERS.byte;
+
+export function characterDef(id: string): CharacterDef {
+  return CHARACTERS[id] ?? CHARACTER_FALLBACK;
+}
+
+// --- Nemici e risorse (icone Font Awesome, colori via CSS var) -----------------
+
+export interface Visual {
+  icon: IconDefinition;
+  /** Colore CSS (token del tema di scena). */
+  color: string;
+  /** Etichetta accessibile. */
+  label: string;
+}
+
+const ENEMIES: Record<string, Visual> = {
+  bug: { icon: faBug, color: 'var(--pq-enemy)', label: 'bug' },
+  ghost: { icon: faGhost, color: 'var(--pq-enemy)', label: 'fantasma' },
+  dragon: { icon: faDragon, color: 'var(--pq-enemy)', label: 'drago' },
+  spider: { icon: faSpider, color: 'var(--pq-enemy)', label: 'ragno' },
+};
+
+const ENEMY_FALLBACK: Visual = {
+  icon: faSkull,
+  color: 'var(--pq-enemy)',
+  label: 'nemico',
+};
+
+export function enemyVisual(kind: string): Visual {
+  return ENEMIES[kind] ?? ENEMY_FALLBACK;
+}
+
+const RESOURCES: Record<string, Visual> = {
+  gem: { icon: faGem, color: 'var(--pq-resource)', label: 'gemma' },
+  key: { icon: faKey, color: 'var(--pq-resource)', label: 'chiave' },
+  coin: { icon: faCoins, color: 'var(--pq-resource)', label: 'moneta' },
+  heart: { icon: faHeart, color: 'var(--pq-resource)', label: 'cuore' },
+};
+
+const RESOURCE_FALLBACK: Visual = {
+  icon: faStar,
+  color: 'var(--pq-resource)',
+  label: 'risorsa',
+};
+
+export function resourceVisual(kind: string): Visual {
+  return RESOURCES[kind] ?? RESOURCE_FALLBACK;
+}
+
+// --- Icone di scena non-personaggio -------------------------------------------
+
+export const GOAL_ICON = faFlagCheckered;
+export const HP_ICON = faHeart;
diff --git a/src/components/PyQuest/index.tsx b/src/components/PyQuest/index.tsx
index 6f320e2..45aea47 100644
--- a/src/components/PyQuest/index.tsx
+++ b/src/components/PyQuest/index.tsx
@@ -1,29 +1,47 @@
 /**
- * PyQuest — mini-giochi a griglia con Python (spec: PyQuest).
+ * PyQuest — mini-giochi a griglia con Python (spec step 12).
  *
- * ⚠️ VERSIONE HARNESS (step 5). Questa è la prima versione "debug" del
- * componente: editor riusato da PyRunner + bottone Esegui + dump grezzo degli
- * eventi ricevuti dal motore. Niente renderer, niente player: quelli arrivano
- * nella fase 2 (step 10-12), quando questo file verrà riscritto (step 12).
- * Serve solo a validare il motore trace-based end-to-end.
+ * Orchestrazione: editor + Toolbar (riusati da PyRunner) → `runLevel` esegue il
+ * codice studente contro il motore trace-based (`static/bry-libs/pyquest.py`),
+ * gli eventi si accumulano in un ref, e a fine esecuzione `GamePlayer` anima la
+ * trace su `GameScene`.
+ *
+ * Macchina a stati: `idle → executing (invisibile, ms) → animating → finished`.
+ * L'esito è calcolato dalla trace con precedenza **won > failed > error**
+ * (emendamento D7): dopo la vittoria la trace può contenere anche `step_limit`
+ * e uno stderr — lo studente ha comunque vinto, il traceback resta in console.
+ *
+ * Risoluzione del livello: `levelData` inline (editor/test) ha la precedenza;
+ * altrimenti `world`+`level` fanno lookup nei global data del plugin `pyquest`.
+ * Id ignoti = pannello d'errore, mai un livello di ripiego silenzioso.
  */
 
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import BrowserOnly from '@docusaurus/BrowserOnly';
 import { usePluginData } from '@docusaurus/useGlobalData';
+import clsx from 'clsx';
 import { Editor, type EditorHandle } from '@site/src/theme/PyRunner/Editor';
+import { Toolbar } from '@site/src/theme/PyRunner/Toolbar';
+import type { RunStatus } from '@site/src/theme/PyRunner/types';
 import { ensureBrython, type BrythonConfig } from '@site/src/pyBoot';
-import { runLevel } from './runLevel';
+import pyStyles from '@site/src/theme/PyRunner/styles.module.css';
+import { runLevel, MAX_STEPS_DEFAULT } from './runLevel';
+import { useWorldData } from './useWorldData';
+import { characterDef } from './characters';
+import GamePlayer from './GamePlayer';
 import type { GameEvent, LevelDef, LogLine } from './types';
+import styles from './PyQuest.module.css';
 
 export interface PyQuestProps {
-  /** Id del mondo nei global data del plugin `pyquest` (fase 2, step 7). */
+  /** Id del mondo nei global data del plugin `pyquest`. */
   world?: string;
   /** Id del livello dentro il mondo. */
   level?: string;
   /** Livello passato inline (editor/test): bypassa la lookup su world/level. */
   levelData?: LevelDef;
-  /** Titolo mostrato sopra l'editor. */
+  /** Personaggio (override): normalmente ereditato dal mondo. */
+  character?: string;
+  /** Titolo mostrato nella toolbar (override del titolo del livello). */
   title?: string;
 }
 
@@ -32,25 +50,9 @@ interface PyRunnerGlobalData {
   brython?: BrythonConfig;
 }
 
-type RunStatus = 'idle' | 'running' | 'done' | 'error';
-
-// Livello di fallback per l'harness: griglia 5×5, muro a 2 celle davanti a Byte
-// così `for _ in range(3): move()` produce move, move, bump.
-const DEFAULT_LEVEL: LevelDef = {
-  id: 'harness',
-  title: 'Harness 5×5',
-  grid: {
-    legend: { '#': 'wall', '.': 'floor' },
-    rows: ['#####', '#...#', '#...#', '#...#', '#####'],
-  },
-  hero: { x: 1, y: 1, facing: 'east', hp: 3 },
-  goal: { x: 3, y: 3 },
-  win: [{ type: 'reach' }],
-  starterCode:
-    '# Muovi Byte. Prova a cambiare il codice ed esegui.\nfor _ in range(3):\n    move()\n',
-  hints: [],
-  par: 6,
-};
+type Phase = 'idle' | 'executing' | 'animating' | 'finished';
+/** `null` = il codice è terminato senza vittoria, sconfitta né errore. */
+type Outcome = 'won' | 'failed' | 'error' | null;
 
 // Contatore di modulo per il suffisso del codeId (D12): due istanze dello stesso
 // livello sulla stessa pagina devono restare indipendenti.
@@ -68,30 +70,51 @@ function makeCodeId(seed: string, n: number): string {
   return `pyr_${h}${n.toString(36)}`;
 }
 
+function ErrorBox({ children }: { children: React.ReactNode }) {
+  return <div className={styles.error}>{children}</div>;
+}
+
 function PyQuestInner(props: PyQuestProps) {
-  const data = usePluginData('pyrunner') as PyRunnerGlobalData | undefined;
-  const libUrl = data?.libUrl ?? '';
-  const brython = data?.brython;
+  const pyrunner = usePluginData('pyrunner') as PyRunnerGlobalData | undefined;
+  const worlds = useWorldData();
+  const libUrl = pyrunner?.libUrl ?? '';
+  const brython = pyrunner?.brython;
+
+  // Risoluzione livello + personaggio (prima degli hook condizionali: i render
+  // d'errore stanno in fondo, dopo tutti gli hook).
+  const world = props.world ? worlds[props.world] : undefined;
+  const level: LevelDef | undefined =
+    props.levelData ??
+    (world && props.level
+      ? world.levels.find((l) => l.id === props.level)
+      : undefined);
+  const character = props.character ?? world?.character ?? 'byte';
+  const char = characterDef(character);
+  const starterCode = level?.starterCode ?? '';
 
-  const level = props.levelData ?? DEFAULT_LEVEL;
   const seed =
     props.world && props.level
       ? `${props.world}/${props.level}`
-      : JSON.stringify(level);
-
+      : JSON.stringify(level ?? props);
   const instanceN = useRef<number>(-1);
   if (instanceN.current < 0) instanceN.current = idCounter++;
-  const codeId = useMemo(() => makeCodeId(seed, instanceN.current), [seed]);
+  const codeId = makeCodeId(seed, instanceN.current);
 
+  const [phase, setPhase] = useState<Phase>('idle');
+  const [outcome, setOutcome] = useState<Outcome>(null);
   const [events, setEvents] = useState<GameEvent[]>([]);
   const [logs, setLogs] = useState<LogLine[]>([]);
-  const [status, setStatus] = useState<RunStatus>('idle');
+  const [playKey, setPlayKey] = useState(0);
+  const [hasEdits, setHasEdits] = useState(false);
+  const [currentCode, setCurrentCode] = useState(starterCode);
 
   const editorRef = useRef<EditorHandle | null>(null);
   const rootRef = useRef<HTMLDivElement | null>(null);
   const cleanupRef = useRef<(() => void) | null>(null);
+  const eventsRef = useRef<GameEvent[]>([]);
+  const logsRef = useRef<LogLine[]>([]);
 
-  // Precarica Brython quando l'harness entra nel viewport (pattern PyRunner).
+  // Precarica Brython quando il componente entra nel viewport (pattern PyRunner).
   useEffect(() => {
     const el = rootRef.current;
     const preload = () => {
@@ -118,12 +141,37 @@ function PyQuestInner(props: PyQuestProps) {
 
   useEffect(() => () => cleanupRef.current?.(), []);
 
+  const finishRun = useCallback(() => {
+    const trace = eventsRef.current;
+    const hasWin = trace.some((e) => e.t === 'win');
+    const hasDeath = trace.some((e) => e.t === 'death');
+    const hasLimit = trace.some((e) => e.t === 'step_limit');
+    const hasStderr = logsRef.current.some((l) => l.kind === 'stderr');
+    // Precedenza esplicita (emendamento D7): won > failed > error.
+    setOutcome(
+      hasWin
+        ? 'won'
+        : hasDeath || hasLimit
+          ? 'failed'
+          : hasStderr
+            ? 'error'
+            : null,
+    );
+    setEvents([...trace]);
+    setLogs([...logsRef.current]);
+    setPhase('animating');
+    setPlayKey((k) => k + 1);
+  }, []);
+
   const handleRun = useCallback(() => {
-    const code = editorRef.current?.getCode() ?? level.starterCode;
-    setStatus('running');
+    if (!level) return;
+    const code = editorRef.current?.getCode() ?? starterCode;
+    setPhase('executing');
+    setOutcome(null);
     setEvents([]);
     setLogs([]);
-    const collected: GameEvent[] = [];
+    eventsRef.current = [];
+    logsRef.current = [];
     cleanupRef.current?.();
     cleanupRef.current = runLevel({
       code,
@@ -132,116 +180,163 @@ function PyQuestInner(props: PyQuestProps) {
       libUrl,
       brython,
       onStart: () => {
-        collected.length = 0;
-        setEvents([]);
-        setLogs([]);
+        eventsRef.current = [];
+        logsRef.current = [];
       },
       onEvent: (ev) => {
-        collected.push(ev);
-        setEvents([...collected]);
+        eventsRef.current.push(ev);
       },
       onLog: (kind, text) => {
-        setLogs((prev) => [...prev, { kind, text, atStep: collected.length }]);
-        if (kind === 'stderr') setStatus('error');
+        logsRef.current.push({ kind, text, atStep: eventsRef.current.length });
       },
-      onDone: () => setStatus((s) => (s === 'error' ? s : 'done')),
+      onDone: finishRun,
       onError: (err) => {
-        setStatus('error');
-        setLogs((prev) => [
-          ...prev,
-          {
-            kind: 'stderr',
-            text: `[PyQuest] ${err.message}\n`,
-            atStep: collected.length,
-          },
-        ]);
+        logsRef.current.push({
+          kind: 'stderr',
+          text: `[PyQuest] ${err.message}\n`,
+          atStep: eventsRef.current.length,
+        });
+        finishRun();
       },
     });
-  }, [level, codeId, libUrl, brython]);
+  }, [level, starterCode, codeId, libUrl, brython, finishRun]);
+
+  const handleReset = useCallback(() => {
+    editorRef.current?.setCode(starterCode);
+    setCurrentCode(starterCode);
+    setHasEdits(false);
+  }, [starterCode]);
+
+  const handleChange = useCallback(
+    (next: string) => {
+      setCurrentCode(next);
+      setHasEdits(next !== starterCode);
+    },
+    [starterCode],
+  );
+
+  // Fine animazione: il player è arrivato in fondo alla trace.
+  const handleStepChange = useCallback((step: number, total: number) => {
+    if (step >= total) {
+      setPhase((p) => (p === 'animating' ? 'finished' : p));
+    }
+  }, []);
 
   if (!libUrl) {
     return (
-      <div style={{ padding: 12, border: '1px solid var(--at-border)' }}>
-        PyQuest (harness): plugin <code>pyrunner</code> non registrato — libUrl
-        mancante.
-      </div>
+      <ErrorBox>
+        PyQuest: plugin <code>pyrunner</code> non registrato — libUrl mancante.
+      </ErrorBox>
     );
   }
+  if (!level) {
+    if (props.world && !world) {
+      return (
+        <ErrorBox>
+          PyQuest: mondo <code>{props.world}</code> non trovato nei dati del
+          plugin.
+        </ErrorBox>
+      );
+    }
+    if (world && props.level) {
+      return (
+        <ErrorBox>
+          PyQuest: livello <code>{props.level}</code> non trovato nel mondo{' '}
+          <code>{props.world}</code>.
+        </ErrorBox>
+      );
+    }
+    return (
+      <ErrorBox>
+        PyQuest: specifica <code>world</code> + <code>level</code> oppure{' '}
+        <code>levelData</code>.
+      </ErrorBox>
+    );
+  }
+
+  const toolbarStatus: RunStatus =
+    phase === 'executing'
+      ? 'running'
+      : phase === 'idle'
+        ? 'idle'
+        : outcome === 'error'
+          ? 'error'
+          : 'done';
 
-  const boxStyle: React.CSSProperties = {
-    border: '1px solid var(--at-border)',
-    borderRadius: 'var(--radius-m, 10px)',
-    padding: 8,
-    margin: '8px 0',
-    background: 'var(--at-bg-subtle)',
-    fontFamily: '"Monaspace Neon", ui-monospace, monospace',
-    fontSize: '0.85rem',
-    whiteSpace: 'pre-wrap',
-    maxHeight: 240,
-    overflow: 'auto',
-  };
+  const maxSteps = level.maxSteps ?? MAX_STEPS_DEFAULT;
+  const hasDeath = events.some((e) => e.t === 'death');
+  const bumpCount = events.filter((e) => e.t === 'bump').length;
+  const stderrText = logs
+    .filter((l) => l.kind === 'stderr')
+    .map((l) => l.text)
+    .join('');
 
   return (
-    <div ref={rootRef} data-pagefind-ignore style={{ margin: '1.5rem 0' }}>
-      <div style={{ marginBottom: 6, fontWeight: 600 }}>
-        {props.title ?? level.title}{' '}
-        <span style={{ opacity: 0.6, fontWeight: 400 }}>
-          — harness ({status})
-        </span>
-      </div>
-      <div
-        style={{
-          border: '1px solid var(--at-border)',
-          borderRadius: 'var(--radius-m, 10px)',
-          overflow: 'hidden',
-        }}
-      >
-        <Editor
-          ref={editorRef}
-          initialCode={level.starterCode}
-          showLineNumbers
-          onRun={handleRun}
-        />
-      </div>
-      <button
-        type="button"
-        onClick={handleRun}
-        disabled={status === 'running'}
-        style={{
-          marginTop: 8,
-          padding: '6px 14px',
-          borderRadius: 'var(--radius-s, 6px)',
-          border: '1px solid var(--at-border)',
-          background: 'var(--at-accent)',
-          color: '#fff',
-          cursor: status === 'running' ? 'default' : 'pointer',
-        }}
-      >
-        Esegui
-      </button>
-      <div style={{ marginTop: 8, fontWeight: 600, fontSize: '0.8rem' }}>
-        Eventi ({events.length})
-      </div>
-      <div style={boxStyle}>
-        {events.map((ev, i) => `${i}: ${JSON.stringify(ev)}`).join('\n') || '—'}
-      </div>
-      {logs.length > 0 && (
-        <>
-          <div style={{ marginTop: 8, fontWeight: 600, fontSize: '0.8rem' }}>
-            Console
-          </div>
-          <div style={boxStyle}>
-            {logs.map((l) => `[${l.kind}@${l.atStep}] ${l.text}`).join('')}
+    <div ref={rootRef} data-pagefind-ignore className={styles.root}>
+      <div className={styles.layout}>
+        <div className={styles.stage}>
+          <GamePlayer
+            level={level}
+            character={character}
+            events={events}
+            logs={logs}
+            playKey={playKey}
+            onStepChange={handleStepChange}
+          />
+
+          {/* Pannelli di esito con il flavor text del personaggio (D13). */}
+          {phase === 'finished' && outcome === 'won' && (
+            <div className={clsx(styles.panel, styles.panelWin)}>
+              <strong>{char.name}:</strong> {char.flavor.win}
+            </div>
+          )}
+          {phase === 'finished' && outcome === 'failed' && (
+            <div className={clsx(styles.panel, styles.panelFail)}>
+              <strong>{char.name}:</strong>{' '}
+              {hasDeath ? char.flavor.death : char.flavor.stepLimit(maxSteps)}
+            </div>
+          )}
+          {phase === 'finished' && outcome === 'error' && (
+            <div className={clsx(styles.panel, styles.panelError)}>
+              <p className={styles.panelTitle}>C’è un errore nel codice</p>
+              <pre className={styles.traceback}>{stderrText}</pre>
+            </div>
+          )}
+          {phase === 'finished' && outcome === null && bumpCount >= 2 && (
+            <div className={clsx(styles.panel, styles.panelNeutral)}>
+              <strong>{char.name}:</strong> {char.flavor.bump}
+            </div>
+          )}
+        </div>
+
+        <div className={clsx(pyStyles.runner, 'notranslate', styles.editorCol)}>
+          <Toolbar
+            title={props.title ?? level.title}
+            status={toolbarStatus}
+            hasEdits={hasEdits}
+            code={currentCode}
+            onRun={handleRun}
+            onReset={handleReset}
+          />
+          <div className={pyStyles.editorWrap}>
+            <Editor
+              ref={editorRef}
+              initialCode={starterCode}
+              showLineNumbers
+              onChange={handleChange}
+              onRun={handleRun}
+              ariaLabel="Editor di codice Python del livello"
+            />
           </div>
-        </>
-      )}
+        </div>
+      </div>
     </div>
   );
 }
 
 export default function PyQuest(props: PyQuestProps) {
   return (
-    <BrowserOnly fallback={<div>PyQuest…</div>}>
+    <BrowserOnly fallback={<div className={styles.root}>PyQuest…</div>}>
       {() => <PyQuestInner {...props} />}
     </BrowserOnly>
   );
diff --git a/src/components/PyQuest/runLevel.ts b/src/components/PyQuest/runLevel.ts
index 1f128be..f0776d3 100644
--- a/src/components/PyQuest/runLevel.ts
+++ b/src/components/PyQuest/runLevel.ts
@@ -15,7 +15,7 @@ import type { BrythonConfig } from '@site/src/pyBoot';
 import { runPython, type LogKind } from '@site/src/theme/PyRunner/bryBridge';
 import type { GameEvent, LevelDef } from './types';
 
-const MAX_STEPS_DEFAULT = 500;
+export const MAX_STEPS_DEFAULT = 500;
 
 /** Sottoinsieme del livello che il motore Python consuma davvero. */
 function runtimeLevel(level: LevelDef): Record<string, unknown> {
diff --git a/src/components/PyQuest/useWorldData.ts b/src/components/PyQuest/useWorldData.ts
new file mode 100644
index 0000000..7ae4399
--- /dev/null
+++ b/src/components/PyQuest/useWorldData.ts
@@ -0,0 +1,16 @@
+/**
+ * Hook sui global data del plugin `pyquest` (spec step 12): i mondi validati a
+ * build time da plugins/pyquest/index.js.
+ */
+
+import { usePluginData } from '@docusaurus/useGlobalData';
+import type { WorldDef } from './types';
+
+interface PyQuestGlobalData {
+  worlds: Record<string, WorldDef>;
+}
+
+export function useWorldData(): Record<string, WorldDef> {
+  const data = usePluginData('pyquest') as PyQuestGlobalData | undefined;
+  return data?.worlds ?? {};
+}
diff --git a/static/pyquest/mondo-01/world.json b/static/pyquest/mondo-01/world.json
new file mode 100644
index 0000000..95003dd
--- /dev/null
+++ b/static/pyquest/mondo-01/world.json
@@ -0,0 +1,51 @@
+{
+  "schemaVersion": 1,
+  "id": "mondo-01",
+  "title": "Mondo di collaudo",
+  "description": "Livelli provvisori di collaudo (fase 2): saranno sostituiti dal mondo pilota definitivo allo step 18.",
+  "character": "byte",
+  "volume": "programmatore",
+  "levels": [
+    {
+      "id": "muoviti",
+      "title": "Fai muovere Byte",
+      "grid": {
+        "legend": { "#": "wall", ".": "floor" },
+        "rows": ["#####", "#...#", "#...#", "#...#", "#####"]
+      },
+      "hero": { "x": 1, "y": 1, "facing": "east", "hp": 3 },
+      "goal": { "x": 3, "y": 3 },
+      "win": [{ "type": "reach" }],
+      "starterCode": "# Porta Byte sulla bandiera in (3, 3).\nmove()\nmove()\nturn_right()\nmove()\nmove()\n",
+      "solution": "move()\nmove()\nturn_right()\nmove()\nmove()\n",
+      "hints": [
+        "Byte guarda a est: due move() lo portano al muro di destra.",
+        "Con turn_right() gira verso sud, poi altri due move() lo mettono sul goal."
+      ],
+      "par": 5
+    },
+    {
+      "id": "attorno-al-muro",
+      "title": "Aggira l'ostacolo",
+      "grid": {
+        "legend": { "#": "wall", ".": "floor" },
+        "rows": ["#######", "#.....#", "#.###.#", "#.#.#.#", "#.###.#", "#.....#", "#######"]
+      },
+      "hero": { "x": 1, "y": 1, "facing": "south", "hp": 3 },
+      "goal": { "x": 5, "y": 5 },
+      "win": [{ "type": "reach" }],
+      "starterCode": "# Aggira il blocco centrale e raggiungi la bandiera in basso a destra.\nwhile not on_goal():\n    if is_blocked():\n        turn_left()\n    move()\n",
+      "hints": [
+        "Usa i sensori: is_blocked() ti dice se hai un muro davanti.",
+        "Un ciclo while not on_goal() ripete finché non sei arrivato."
+      ],
+      "par": 12,
+      "enemies": [
+        { "id": "e1", "kind": "ghost", "x": 1, "y": 5, "hp": 2, "behavior": "static" }
+      ],
+      "resources": [
+        { "id": "g1", "kind": "gem", "x": 5, "y": 1 }
+      ]
+    }
+  ]
+}

From 29f345417e19694fa44b4413b982403d4683f53b Mon Sep 17 00:00:00 2001
From: Marco Farina <marco.farina@jcmaxwell.it>
Date: Fri, 3 Jul 2026 02:13:33 +0200
Subject: [PATCH 06/11] feat(pyquest): combat, risorse, hint, progressione e
 stelle (fase 3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 13 — motore completo (static/bry-libs/pyquest.py):
- classi Enemy/Resource; tick nemici deterministico (zero RNG): static
  attacca se adiacente, melee attacca o fa un passo greedy verso l'eroe
  (asse col delta maggiore, a parità x, poi l'altro asse, altrimenti
  fermo; niente sovrapposizioni tra nemici o con l'eroe);
- attack()/collect(); sensori enemy_ahead/on_resource/health/inventory;
  move() e is_blocked() ora trattano il nemico come blocco (bump);
- GameOverError (sollevata dopo l'evento death → la precedenza esito
  won>failed>error mostra la UI di sconfitta, non il pannello errore);
- win collect (inventory>=qty) e defeat (tutti i target, o count; guard
  len>0 anti-vittoria-fantasma);
- guardia _action_guard PRIMA del check won anche in attack/collect
  (emendamento D7).

Step 15 — HintPanel.tsx (reveal progressivo, stato in memoria) + slot
"Spiegamelo facile" cablato in index.tsx (buildExplainText +
copyToClipboard riusati da PyRunner).

Step 16 — useProgress.ts (chiave versionata pdb:pyquest:progress, parse
difensivo con reset, sync same-tab via CustomEvent + storage cross-tab
sul pattern di usePref; recordWin minimizza bestSteps, isUnlocked
calcolato; countActions = move/turn/bump/attack/collect fino al win;
starsFor D11) + pannello vittoria con stelle e "nuovo record" + striscia
"Completato · record N" persistente + stili in PyQuest.module.css.

Step 14 (scena combat) era già coperto dalla fase 2 (applyEvent +
GameScene gestivano già gli eventi combat/collect, HUD PV/inventario e
fx): nessuna modifica, solo verifica.

Dati: livello di collaudo "duello" (bug melee + gemma, win defeat+collect,
par 7) in mondo-01/world.json; tolto il fantasma decorativo dal livello 2.
Harness docs/pyquest-test.mdx aggiornato (sezione combat + note h/i/j).

Verifica: motore validato sotto CPython (trace del duello deterministica
su 3 run, win a 7 azioni; morte -> death+GameOverError; while True su
livello senza nemici -> step_limit; reach win). typecheck+lint+build
verdi. Verifica visiva nel browser (Chrome): combat, raccolta, stelle,
persistenza del record al reload, hint progressivi, dark mode.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V9dpQX4sKY6tJkTetJz3ho
---
 docs/pyquest-test.mdx                     |  35 +++-
 src/components/PyQuest/HintPanel.tsx      |  48 ++++++
 src/components/PyQuest/PyQuest.module.css | 108 +++++++++++++
 src/components/PyQuest/index.tsx          |  79 ++++++++-
 src/components/PyQuest/useProgress.ts     | 169 +++++++++++++++++++
 static/bry-libs/pyquest.py                | 189 +++++++++++++++++++++-
 static/pyquest/mondo-01/world.json        |  30 +++-
 7 files changed, 637 insertions(+), 21 deletions(-)
 create mode 100644 src/components/PyQuest/HintPanel.tsx
 create mode 100644 src/components/PyQuest/useProgress.ts

diff --git a/docs/pyquest-test.mdx b/docs/pyquest-test.mdx
index 1a9fa9d..dc3cf3e 100644
--- a/docs/pyquest-test.mdx
+++ b/docs/pyquest-test.mdx
@@ -21,12 +21,22 @@ sulla bandiera: premi Esegui e guarda l'animazione.
 
 ## 2. Navigazione con i sensori
 
-Livello `attorno-al-muro`: c'è un blocco centrale da aggirare, più una gemma e un
-fantasma come scenografia (combat e raccolta arrivano nella fase 3). Prova a far
-arrivare Byte in basso a destra con un ciclo `while not on_goal()`.
+Livello `attorno-al-muro`: c'è un blocco centrale da aggirare (più una gemma come
+scenografia). Prova a far arrivare Byte in basso a destra con un ciclo
+`while not on_goal()`.
 
 <PyQuest world="mondo-01" level="attorno-al-muro" />
 
+## 2-bis. Combat, raccolta, hint e stelle (fase 3)
+
+Livello `duello`: un bug **melee** ti viene incontro. Colpiscilo con `attack()`
+(ha 2 PV), poi raccogli la gemma con `collect()`. La vittoria richiede *sia*
+sconfiggere il bug *sia* raccogliere la gemma (`win` multipla). Alla vittoria
+compaiono le stelle (da `par`); i suggerimenti si rivelano a scaglioni sotto
+l'editor; «Spiegamelo facile» copia il prompt negli appunti.
+
+<PyQuest world="mondo-01" level="duello" />
+
 ## 3. Indipendenza tra istanze
 
 Due istanze dello stesso livello sulla stessa pagina: devono avere trace e player
@@ -54,8 +64,17 @@ pannello d'errore esplicito.
   velocità (0,5× 1× 2× 4×) scalano anche la durata delle transizioni.
 - **e)** `print()` interleaved compaiono in console solo quando l'animazione
   raggiunge il passo in cui sono stati emessi.
-- **f)** Il livello 2 disegna gemma e fantasma fermi; Byte li attraversa
-  (niente combat/raccolta finché non arriva la fase 3). Sbattere più volte
-  contro il blocco centrale senza vincere → flavor «bump ripetuto».
-- **g)** Dark mode: board, sprite e pannelli esito leggibili in entrambi i
-  temi; la griglia scala col contenitore (`--pq-cell`).
+- **f)** Sbattere più volte contro il blocco centrale del livello 2 senza
+  vincere → flavor «bump ripetuto».
+- **g)** Dark mode: board, sprite, stelle e pannelli esito leggibili in entrambi
+  i temi; la griglia scala col contenitore (`--pq-cell`).
+- **h)** Livello `duello` (fase 3): il bug melee si avvicina a ogni azione; due
+  `attack()` lo sconfiggono; `collect()` raccoglie la gemma; con la soluzione la
+  vittoria arriva a `par` azioni → 3 stelle. La trace è **identica** su run
+  ripetuti. Ricaricando la pagina, il livello risulta «Completato · record N».
+- **i)** Morte dell'eroe (es. resta fermo accanto a un nemico che lo colpisce
+  fino a 0 PV): UI di sconfitta (non pannello errore); traceback breve in
+  console. `while True: move()` → step limit nel tono di Byte.
+- **j)** Suggerimenti: si rivelano uno alla volta (1/3 → 2/3 → 3/3) e non
+  persistono al reload. «Spiegamelo facile» copia un prompt con codice + titolo
+  del livello.
diff --git a/src/components/PyQuest/HintPanel.tsx b/src/components/PyQuest/HintPanel.tsx
new file mode 100644
index 0000000..441408d
--- /dev/null
+++ b/src/components/PyQuest/HintPanel.tsx
@@ -0,0 +1,48 @@
+/**
+ * HintPanel — suggerimenti progressivi di un livello PyQuest (spec step 15).
+ *
+ * Rivela gli hint uno alla volta (concettuale → direzionale → quasi-soluzione).
+ * Lo stato è **in memoria** (non persistito): riaprendo la pagina si riparte da
+ * zero suggerimenti, così lo studente prova prima con la testa.
+ */
+
+import { useState } from 'react';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import { faLightbulb } from '@fortawesome/free-solid-svg-icons';
+import styles from './PyQuest.module.css';
+
+export interface HintPanelProps {
+  hints: string[];
+}
+
+export default function HintPanel({ hints }: HintPanelProps) {
+  const [revealed, setRevealed] = useState(0);
+  if (hints.length === 0) return null;
+
+  const allRevealed = revealed >= hints.length;
+
+  return (
+    <div className={styles.hints}>
+      {revealed > 0 && (
+        <ol className={styles.hintList}>
+          {hints.slice(0, revealed).map((hint, i) => (
+            <li key={i}>{hint}</li>
+          ))}
+        </ol>
+      )}
+      {!allRevealed && (
+        <button
+          type="button"
+          className={styles.hintBtn}
+          onClick={() => setRevealed((r) => r + 1)}
+        >
+          <FontAwesomeIcon icon={faLightbulb} />
+          <span>
+            {revealed === 0 ? 'Suggerimento' : 'Un altro aiuto'} ({revealed + 1}
+            /{hints.length})
+          </span>
+        </button>
+      )}
+    </div>
+  );
+}
diff --git a/src/components/PyQuest/PyQuest.module.css b/src/components/PyQuest/PyQuest.module.css
index 99a3e62..e11decc 100644
--- a/src/components/PyQuest/PyQuest.module.css
+++ b/src/components/PyQuest/PyQuest.module.css
@@ -77,6 +77,114 @@
   overflow: auto;
 }
 
+.winHead {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-bottom: 6px;
+}
+
+.winSteps {
+  font-size: 0.86rem;
+  opacity: 0.85;
+}
+
+.record {
+  color: #2f9e44;
+  font-weight: 700;
+}
+
+.winFlavor {
+  margin: 0;
+}
+
+/* --- Stelle (spec D11) ---------------------------------------------------- */
+
+.stars {
+  display: inline-flex;
+  gap: 3px;
+  font-size: 1rem;
+  line-height: 1;
+}
+
+.star {
+  color: var(--at-border, rgba(0, 0, 0, 0.18));
+}
+
+.starOn {
+  color: #f0a92b;
+}
+
+html[data-theme='dark'] .star {
+  color: rgba(255, 255, 255, 0.22);
+}
+
+html[data-theme='dark'] .starOn {
+  color: #ffca4b;
+}
+
+/* --- Striscia «completato» (record persistito) --------------------------- */
+
+.completed {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 12px;
+  border-radius: var(--radius-sm, 10px);
+  background: color-mix(in srgb, #2f9e44 10%, transparent);
+  border: 1px solid color-mix(in srgb, #2f9e44 28%, transparent);
+  font-size: 0.86rem;
+  font-weight: 600;
+}
+
+/* --- Suggerimenti progressivi (step 15) ---------------------------------- */
+
+.hints {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  margin-top: 4px;
+}
+
+.hintList {
+  margin: 0;
+  padding-left: 1.2rem;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  font-size: 0.9rem;
+  line-height: 1.5;
+}
+
+.hintBtn {
+  align-self: flex-start;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 7px 14px;
+  border-radius: var(--radius-pill, 999px);
+  border: 1px solid var(--at-border, rgba(0, 0, 0, 0.12));
+  background: var(--at-bg-subtle, rgba(0, 0, 0, 0.03));
+  color: inherit;
+  font: inherit;
+  font-size: 0.88rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition:
+    background var(--dur-fast, 140ms) var(--ease-smooth, ease),
+    border-color var(--dur-fast, 140ms) var(--ease-smooth, ease),
+    transform var(--dur-fast, 140ms) var(--ease-smooth, ease);
+}
+
+.hintBtn:hover {
+  background: color-mix(in srgb, #f0a92b 14%, transparent);
+  border-color: color-mix(in srgb, #f0a92b 45%, transparent);
+}
+
+.hintBtn:active {
+  transform: scale(0.98);
+}
+
 /* --- Errori di configurazione (props/plugin) ------------------------------ */
 
 .error {
diff --git a/src/components/PyQuest/index.tsx b/src/components/PyQuest/index.tsx
index 45aea47..47fc63c 100644
--- a/src/components/PyQuest/index.tsx
+++ b/src/components/PyQuest/index.tsx
@@ -19,16 +19,26 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import BrowserOnly from '@docusaurus/BrowserOnly';
 import { usePluginData } from '@docusaurus/useGlobalData';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import { faStar } from '@fortawesome/free-solid-svg-icons';
+import { faStar as faStarOutline } from '@fortawesome/free-regular-svg-icons';
 import clsx from 'clsx';
 import { Editor, type EditorHandle } from '@site/src/theme/PyRunner/Editor';
 import { Toolbar } from '@site/src/theme/PyRunner/Toolbar';
 import type { RunStatus } from '@site/src/theme/PyRunner/types';
+import { copyToClipboard } from '@site/src/theme/PyRunner/clipboard';
+import {
+  buildExplainText,
+  DEFAULT_EXPLAIN_PROMPT,
+} from '@site/src/theme/PyRunner/share';
 import { ensureBrython, type BrythonConfig } from '@site/src/pyBoot';
 import pyStyles from '@site/src/theme/PyRunner/styles.module.css';
 import { runLevel, MAX_STEPS_DEFAULT } from './runLevel';
 import { useWorldData } from './useWorldData';
+import { useProgress, countActions, starsFor } from './useProgress';
 import { characterDef } from './characters';
 import GamePlayer from './GamePlayer';
+import HintPanel from './HintPanel';
 import type { GameEvent, LevelDef, LogLine } from './types';
 import styles from './PyQuest.module.css';
 
@@ -74,9 +84,25 @@ function ErrorBox({ children }: { children: React.ReactNode }) {
   return <div className={styles.error}>{children}</div>;
 }
 
+/** Riga di 3 stelle, piene fino a `n` (spec D11). */
+function Stars({ n }: { n: number }) {
+  return (
+    <span className={styles.stars} aria-label={`${n} stelle su 3`}>
+      {[1, 2, 3].map((i) => (
+        <FontAwesomeIcon
+          key={i}
+          icon={i <= n ? faStar : faStarOutline}
+          className={clsx(styles.star, i <= n && styles.starOn)}
+        />
+      ))}
+    </span>
+  );
+}
+
 function PyQuestInner(props: PyQuestProps) {
   const pyrunner = usePluginData('pyrunner') as PyRunnerGlobalData | undefined;
   const worlds = useWorldData();
+  const { getLevel, recordWin } = useProgress();
   const libUrl = pyrunner?.libUrl ?? '';
   const brython = pyrunner?.brython;
 
@@ -92,6 +118,11 @@ function PyQuestInner(props: PyQuestProps) {
   const char = characterDef(character);
   const starterCode = level?.starterCode ?? '';
 
+  // Progresso salvato: solo per livelli identificati da world+level (non per i
+  // livelli inline dell'editor, che non hanno un id persistibile).
+  const savedProgress =
+    props.world && props.level ? getLevel(props.world, props.level) : undefined;
+
   const seed =
     props.world && props.level
       ? `${props.world}/${props.level}`
@@ -157,11 +188,25 @@ function PyQuestInner(props: PyQuestProps) {
             ? 'error'
             : null,
     );
+    // Vittoria: salva completamento e record (solo per livelli identificabili).
+    if (hasWin && props.world && props.level) {
+      recordWin(props.world, props.level, countActions(trace));
+    }
     setEvents([...trace]);
     setLogs([...logsRef.current]);
     setPhase('animating');
     setPlayKey((k) => k + 1);
-  }, []);
+  }, [recordWin, props.world, props.level]);
+
+  const handleExplain = useCallback(() => {
+    if (!level) return;
+    const code = editorRef.current?.getCode() ?? starterCode;
+    const contextTitle = `Livello PyQuest «${level.title}»`;
+    const text = buildExplainText(DEFAULT_EXPLAIN_PROMPT, code, contextTitle);
+    copyToClipboard(text).catch(() => {
+      /* clipboard non disponibile: nessun feedback, il codice resta nell'editor */
+    });
+  }, [level, starterCode]);
 
   const handleRun = useCallback(() => {
     if (!level) return;
@@ -271,10 +316,26 @@ function PyQuestInner(props: PyQuestProps) {
     .map((l) => l.text)
     .join('');
 
+  // Azioni e stelle di QUESTA esecuzione (il pannello vittoria le mostra);
+  // `savedProgress` porta invece il record persistito, visibile anche a freddo.
+  const runSteps = countActions(events);
+  const runStars = starsFor(runSteps, level.par);
+  const isRecord =
+    outcome === 'won' &&
+    (savedProgress === undefined || runSteps <= savedProgress.bestSteps);
+
   return (
     <div ref={rootRef} data-pagefind-ignore className={styles.root}>
       <div className={styles.layout}>
         <div className={styles.stage}>
+          {/* Record persistito: visibile anche a freddo (verifica reload). */}
+          {savedProgress?.done && (
+            <div className={styles.completed}>
+              <Stars n={starsFor(savedProgress.bestSteps, level.par)} />
+              <span>Completato · record {savedProgress.bestSteps} azioni</span>
+            </div>
+          )}
+
           <GamePlayer
             level={level}
             character={character}
@@ -287,7 +348,18 @@ function PyQuestInner(props: PyQuestProps) {
           {/* Pannelli di esito con il flavor text del personaggio (D13). */}
           {phase === 'finished' && outcome === 'won' && (
             <div className={clsx(styles.panel, styles.panelWin)}>
-              <strong>{char.name}:</strong> {char.flavor.win}
+              <div className={styles.winHead}>
+                <Stars n={runStars} />
+                <span className={styles.winSteps}>
+                  {runSteps} azioni · par {level.par}
+                  {isRecord && (
+                    <b className={styles.record}> · nuovo record!</b>
+                  )}
+                </span>
+              </div>
+              <p className={styles.winFlavor}>
+                <strong>{char.name}:</strong> {char.flavor.win}
+              </p>
             </div>
           )}
           {phase === 'finished' && outcome === 'failed' && (
@@ -317,6 +389,8 @@ function PyQuestInner(props: PyQuestProps) {
             code={currentCode}
             onRun={handleRun}
             onReset={handleReset}
+            showExplain
+            onExplain={handleExplain}
           />
           <div className={pyStyles.editorWrap}>
             <Editor
@@ -328,6 +402,7 @@ function PyQuestInner(props: PyQuestProps) {
               ariaLabel="Editor di codice Python del livello"
             />
           </div>
+          <HintPanel hints={level.hints} />
         </div>
       </div>
     </div>
diff --git a/src/components/PyQuest/useProgress.ts b/src/components/PyQuest/useProgress.ts
new file mode 100644
index 0000000..7ae6f33
--- /dev/null
+++ b/src/components/PyQuest/useProgress.ts
@@ -0,0 +1,169 @@
+/**
+ * Progressione di PyQuest (spec D10): completamenti e record per livello,
+ * persistiti in localStorage sotto un'unica chiave versionata.
+ *
+ * - Chiave `pdb:pyquest:progress` (convenzione `pdb:` = stato di dominio).
+ * - Lo **sblocco non è salvato**: un livello è giocabile se è il primo o se il
+ *   precedente nell'array del mondo è `done` (`isUnlocked`). Inserire un livello
+ *   in mezzo ri-blocca solo ciò che segue; rimuoverne uno lascia chiavi orfane
+ *   innocue.
+ * - Parse difensivo: JSON corrotto o `version` ignota → reset silenzioso.
+ * - Sincronizzazione same-tab via `CustomEvent` (l'evento `storage` non scatta
+ *   nella tab che scrive) + `storage` cross-tab (pattern `Algorithm/usePref`).
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+import type { GameEvent, WorldDef } from './types';
+
+const KEY = 'pdb:pyquest:progress';
+const EVENT = 'pdb-pyquest-progress';
+const VERSION = 1;
+
+export interface LevelProgress {
+  done: boolean;
+  bestSteps: number;
+}
+
+interface ProgressShape {
+  version: number;
+  worlds: Record<string, { levels: Record<string, LevelProgress> }>;
+}
+
+const EMPTY: ProgressShape = { version: VERSION, worlds: {} };
+
+function readProgress(): ProgressShape {
+  if (typeof window === 'undefined') return EMPTY;
+  try {
+    const raw = window.localStorage.getItem(KEY);
+    if (!raw) return EMPTY;
+    const parsed = JSON.parse(raw);
+    if (
+      !parsed ||
+      parsed.version !== VERSION ||
+      typeof parsed.worlds !== 'object'
+    ) {
+      return EMPTY; // corrotto o versione ignota → reset
+    }
+    return parsed as ProgressShape;
+  } catch {
+    return EMPTY;
+  }
+}
+
+function writeProgress(next: ProgressShape) {
+  try {
+    window.localStorage.setItem(KEY, JSON.stringify(next));
+  } catch {
+    /* storage non disponibile: la sessione resta valida in memoria */
+  }
+  window.dispatchEvent(new CustomEvent(EVENT));
+}
+
+export interface UseProgress {
+  /** Progresso salvato di un livello (undefined se mai completato). */
+  getLevel(worldId: string, levelId: string): LevelProgress | undefined;
+  /** Registra una vittoria: marca `done` e minimizza `bestSteps`. */
+  recordWin(worldId: string, levelId: string, steps: number): void;
+  /** Sblocco calcolato: primo livello o precedente `done` (spec D10). */
+  isUnlocked(world: WorldDef, levelId: string): boolean;
+}
+
+export function useProgress(): UseProgress {
+  const [progress, setProgress] = useState<ProgressShape>(EMPTY);
+
+  // Dopo l'hydration leggo il valore reale (sul server era EMPTY). È una lettura
+  // di sincronizzazione con un sistema esterno (localStorage), non uno stato
+  // derivato: il set al mount è voluto e SSR-safe (parte da EMPTY, poi allinea).
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setProgress(readProgress());
+  }, []);
+
+  // Allineamento con gli altri blocchi (same-tab) e con le altre tab (storage).
+  useEffect(() => {
+    const onLocal = () => setProgress(readProgress());
+    const onStorage = (e: StorageEvent) => {
+      if (e.key === KEY) setProgress(readProgress());
+    };
+    window.addEventListener(EVENT, onLocal);
+    window.addEventListener('storage', onStorage);
+    return () => {
+      window.removeEventListener(EVENT, onLocal);
+      window.removeEventListener('storage', onStorage);
+    };
+  }, []);
+
+  const getLevel = useCallback(
+    (worldId: string, levelId: string): LevelProgress | undefined =>
+      progress.worlds[worldId]?.levels[levelId],
+    [progress],
+  );
+
+  const recordWin = useCallback(
+    (worldId: string, levelId: string, steps: number) => {
+      // Rileggo dallo storage prima di scrivere: evita di sovrascrivere
+      // aggiornamenti fatti da un altro blocco tra un render e l'altro.
+      const current = readProgress();
+      const world = current.worlds[worldId] ?? { levels: {} };
+      const prev = world.levels[levelId];
+      const bestSteps = prev ? Math.min(prev.bestSteps, steps) : steps;
+      const next: ProgressShape = {
+        ...current,
+        worlds: {
+          ...current.worlds,
+          [worldId]: {
+            ...world,
+            levels: {
+              ...world.levels,
+              [levelId]: { done: true, bestSteps },
+            },
+          },
+        },
+      };
+      writeProgress(next);
+      setProgress(next); // aggiorna subito questo blocco; l'evento fa gli altri
+    },
+    [],
+  );
+
+  const isUnlocked = useCallback(
+    (world: WorldDef, levelId: string): boolean => {
+      const idx = world.levels.findIndex((l) => l.id === levelId);
+      if (idx <= 0) return true; // primo livello (o id ignoto): sempre aperto
+      const prevId = world.levels[idx - 1].id;
+      return Boolean(progress.worlds[world.id]?.levels[prevId]?.done);
+    },
+    [progress],
+  );
+
+  return { getLevel, recordWin, isUnlocked };
+}
+
+// --- Calcolo azioni e stelle --------------------------------------------------
+
+/**
+ * Eventi che contano come «azione» dello studente (spec step 16): gli eventi
+ * derivati dal mondo (`enemy_*`, `hero_hit`, `defeat`, `win`, `death`,
+ * `step_limit`) non contano.
+ */
+const ACTION_TYPES: ReadonlyArray<GameEvent['t']> = [
+  'move',
+  'turn',
+  'bump',
+  'attack',
+  'collect',
+];
+
+/** Numero di azioni fino al `win` incluso (o su tutta la trace se non c'è). */
+export function countActions(events: GameEvent[]): number {
+  const winIdx = events.findIndex((e) => e.t === 'win');
+  const upto = winIdx >= 0 ? events.slice(0, winIdx) : events;
+  return upto.reduce((n, e) => n + (ACTION_TYPES.includes(e.t) ? 1 : 0), 0);
+}
+
+/** Stelle da `par` (spec D11): ≤ par → 3; ≤ ⌈par·1,5⌉ → 2; completato → 1. */
+export function starsFor(steps: number, par: number): 1 | 2 | 3 {
+  if (steps <= par) return 3;
+  if (steps <= Math.ceil(par * 1.5)) return 2;
+  return 1;
+}
diff --git a/static/bry-libs/pyquest.py b/static/bry-libs/pyquest.py
index 6b68516..39682d7 100644
--- a/static/bry-libs/pyquest.py
+++ b/static/bry-libs/pyquest.py
@@ -29,8 +29,9 @@
 
 __all__ = [
     '_load_level',
-    'move', 'turn_left', 'turn_right',
-    'is_blocked', 'on_goal',
+    'move', 'turn_left', 'turn_right', 'attack', 'collect',
+    'is_blocked', 'enemy_ahead', 'on_goal', 'on_resource',
+    'health', 'inventory',
 ]
 
 # --- Costanti -----------------------------------------------------------------
@@ -57,6 +58,20 @@ class StepLimitError(Exception):
     pass
 
 
+class GameOverError(Exception):
+    """L'eroe è morto: aborta i cicli in corso su un eroe ormai fuori gioco.
+
+    L'evento `death` è già in trace quando questa viene sollevata, quindi lato
+    React la sconfitta si mostra come UI dedicata (non come pannello d'errore):
+    la precedenza degli esiti è won > failed > error.
+    """
+    pass
+
+
+def _sign(d):
+    return (d > 0) - (d < 0)
+
+
 # --- Modello ------------------------------------------------------------------
 
 class Hero:
@@ -68,6 +83,26 @@ def __init__(self, x, y, facing, hp):
         self.inventory = {}
 
 
+class Enemy:
+    def __init__(self, data):
+        self.id = data['id']
+        self.kind = data['kind']
+        self.x = data['x']
+        self.y = data['y']
+        self.hp = data['hp']
+        self.behavior = data.get('behavior', 'static')
+        self.alive = True
+
+
+class Resource:
+    def __init__(self, data):
+        self.id = data['id']
+        self.kind = data['kind']
+        self.x = data['x']
+        self.y = data['y']
+        self.collected = False
+
+
 class World:
     def __init__(self, data):
         grid = data['grid']
@@ -87,6 +122,9 @@ def __init__(self, data):
         g = data.get('goal')
         self.goal = (g['x'], g['y']) if g else None
 
+        self.enemies = [Enemy(e) for e in data.get('enemies', [])]
+        self.resources = [Resource(r) for r in data.get('resources', [])]
+
         self.win_spec = data.get('win', [])
         self.max_steps = data.get('maxSteps', MAX_STEPS_DEFAULT)
 
@@ -102,9 +140,70 @@ def is_walkable(self, x, y):
             return False
         return True
 
+    def enemy_at(self, x, y):
+        """Nemico VIVO nella cella (x, y), oppure None."""
+        for e in self.enemies:
+            if e.alive and (e.x, e.y) == (x, y):
+                return e
+        return None
+
+    def resource_at(self, x, y):
+        """Risorsa NON raccolta nella cella (x, y), oppure None."""
+        for r in self.resources:
+            if not r.collected and (r.x, r.y) == (x, y):
+                return r
+        return None
+
+    def _enemy_can_enter(self, x, y):
+        # Un nemico non entra in muri/bordi, sulla cella dell'eroe (là attacca)
+        # né sopra un altro nemico vivo (niente sovrapposizioni).
+        if not self.is_walkable(x, y):
+            return False
+        if (x, y) == (self.hero.x, self.hero.y):
+            return False
+        return self.enemy_at(x, y) is None
+
+    def _hero_take_hit(self, by_id):
+        self.hero.hp -= 1
+        _emit({'t': 'hero_hit', 'hp': self.hero.hp, 'by': by_id})
+        if self.hero.hp <= 0:
+            self.dead = True
+            _emit({'t': 'death'})
+            raise GameOverError(
+                'Il tuo eroe è caduto. Ripensa la strategia: attacca prima di '
+                'finire circondato, oppure evita i nemici.'
+            )
+
+    def _enemy_step(self, e):
+        # Un passo «greedy» verso l'eroe: prima l'asse col delta maggiore (a
+        # parità l'asse x), poi l'altro asse; se entrambi sono bloccati, fermo.
+        dx = self.hero.x - e.x
+        dy = self.hero.y - e.y
+        if abs(dx) >= abs(dy):
+            candidates = ((_sign(dx), 0), (0, _sign(dy)))
+        else:
+            candidates = ((0, _sign(dy)), (_sign(dx), 0))
+        for sx, sy in candidates:
+            if sx == 0 and sy == 0:
+                continue
+            nx, ny = e.x + sx, e.y + sy
+            if self._enemy_can_enter(nx, ny):
+                e.x, e.y = nx, ny
+                _emit({'t': 'enemy_move', 'id': e.id, 'x': nx, 'y': ny})
+                return
+
     def tick(self):
-        # I nemici si muovono qui (step 13). Nel nucleo movimento è un no-op.
-        pass
+        # Turno dei nemici dopo ogni azione: ordine di lista, deterministico,
+        # zero RNG. `static` attacca solo se adiacente; `melee` attacca se
+        # adiacente, altrimenti fa un passo verso l'eroe.
+        for e in self.enemies:
+            if not e.alive:
+                continue
+            adjacent = abs(e.x - self.hero.x) + abs(e.y - self.hero.y) == 1
+            if adjacent:
+                self._hero_take_hit(e.id)
+            elif e.behavior == 'melee':
+                self._enemy_step(e)
 
 
 _world = None  # riassegnato a ogni _load_level → nessuna contaminazione tra run
@@ -154,8 +253,20 @@ def _cond_met(cond):
     t = cond.get('type')
     if t == 'reach':
         return _world.goal is not None and (_world.hero.x, _world.hero.y) == _world.goal
-    # collect / defeat: implementati allo step 13. Finché non lo sono, la
-    # condizione è considerata NON soddisfatta (mai vittoria fantasma).
+    if t == 'collect':
+        kind = cond.get('kind')
+        qty = cond.get('qty', 1)
+        return _world.hero.inventory.get(kind, 0) >= qty
+    if t == 'defeat':
+        kind = cond.get('kind')
+        count = cond.get('count')
+        targets = [e for e in _world.enemies if kind is None or e.kind == kind]
+        defeated = sum(1 for e in targets if not e.alive)
+        if count is not None:
+            return defeated >= count
+        # «tutti i nemici (di quel kind)»: il guard len>0 evita la vittoria
+        # fantasma se, per errore d'autore, non ci sono nemici da sconfiggere.
+        return len(targets) > 0 and defeated == len(targets)
     return False
 
 
@@ -184,7 +295,8 @@ def move():
     hero = _world.hero
     dx, dy = DIRS[hero.facing]
     nx, ny = hero.x + dx, hero.y + dy
-    if _world.is_walkable(nx, ny):
+    # Muro/bordo o nemico davanti: no-op + bump (mai eccezione, spec D7).
+    if _world.is_walkable(nx, ny) and _world.enemy_at(nx, ny) is None:
         hero.x, hero.y = nx, ny
         _emit({'t': 'move', 'x': nx, 'y': ny, 'f': hero.facing})
     else:
@@ -210,15 +322,76 @@ def turn_right():
     _after_action()
 
 
+def attack():
+    _action_guard()
+    if _world.won:
+        return
+    hero = _world.hero
+    dx, dy = DIRS[hero.facing]
+    tx, ty = hero.x + dx, hero.y + dy
+    target = _world.enemy_at(tx, ty)
+    if target is not None:
+        target.hp -= 1
+        _emit({'t': 'attack', 'x': tx, 'y': ty, 'hit': True})
+        _emit({'t': 'enemy_hit', 'id': target.id, 'hp': target.hp})
+        if target.hp <= 0:
+            target.alive = False
+            _emit({'t': 'defeat', 'id': target.id})
+    else:
+        _emit({'t': 'attack', 'x': tx, 'y': ty, 'hit': False})
+    _after_action()
+
+
+def collect():
+    _action_guard()
+    if _world.won:
+        return
+    hero = _world.hero
+    res = _world.resource_at(hero.x, hero.y)
+    if res is not None:
+        res.collected = True
+        hero.inventory[res.kind] = hero.inventory.get(res.kind, 0) + 1
+        _emit({'t': 'collect', 'id': res.id, 'kind': res.kind})
+    else:
+        _emit({'t': 'bump', 'x': hero.x, 'y': hero.y})
+    _after_action()
+
+
 # --- API studente: sensori (gratuiti, senza tick) -----------------------------
 
 def is_blocked():
     _sensor_guard()
     hero = _world.hero
     dx, dy = DIRS[hero.facing]
-    return not _world.is_walkable(hero.x + dx, hero.y + dy)
+    nx, ny = hero.x + dx, hero.y + dy
+    return not _world.is_walkable(nx, ny) or _world.enemy_at(nx, ny) is not None
+
+
+def enemy_ahead():
+    _sensor_guard()
+    hero = _world.hero
+    dx, dy = DIRS[hero.facing]
+    return _world.enemy_at(hero.x + dx, hero.y + dy) is not None
 
 
 def on_goal():
     _sensor_guard()
     return _world.goal is not None and (_world.hero.x, _world.hero.y) == _world.goal
+
+
+def on_resource():
+    _sensor_guard()
+    return _world.resource_at(_world.hero.x, _world.hero.y) is not None
+
+
+def health():
+    _sensor_guard()
+    return _world.hero.hp
+
+
+def inventory(kind=None):
+    _sensor_guard()
+    inv = _world.hero.inventory
+    if kind is None:
+        return sum(inv.values())
+    return inv.get(kind, 0)
diff --git a/static/pyquest/mondo-01/world.json b/static/pyquest/mondo-01/world.json
index 95003dd..b5e8e32 100644
--- a/static/pyquest/mondo-01/world.json
+++ b/static/pyquest/mondo-01/world.json
@@ -40,12 +40,36 @@
         "Un ciclo while not on_goal() ripete finché non sei arrivato."
       ],
       "par": 12,
-      "enemies": [
-        { "id": "e1", "kind": "ghost", "x": 1, "y": 5, "hp": 2, "behavior": "static" }
-      ],
       "resources": [
         { "id": "g1", "kind": "gem", "x": 5, "y": 1 }
       ]
+    },
+    {
+      "id": "duello",
+      "title": "Duello con un bug",
+      "grid": {
+        "legend": { "#": "wall", ".": "floor" },
+        "rows": ["########", "#......#", "#......#", "########"]
+      },
+      "hero": { "x": 1, "y": 1, "facing": "east", "hp": 5 },
+      "enemies": [
+        { "id": "b1", "kind": "bug", "x": 6, "y": 1, "hp": 2, "behavior": "melee" }
+      ],
+      "resources": [
+        { "id": "g1", "kind": "gem", "x": 3, "y": 2 }
+      ],
+      "win": [
+        { "type": "defeat" },
+        { "type": "collect", "kind": "gem", "qty": 1 }
+      ],
+      "starterCode": "# Il bug ti viene incontro: colpiscilo con attack(), poi raccogli la gemma.\nmove()\nmove()\nattack()\nattack()\nturn_right()\nmove()\ncollect()\n",
+      "solution": "move()\nmove()\nattack()\nattack()\nturn_right()\nmove()\ncollect()\n",
+      "hints": [
+        "Il bug è di tipo melee: ti si avvicina di un passo a ogni tua azione. Non serve rincorrerlo.",
+        "attack() colpisce la cella davanti a te: falla mentre il bug è lì davanti. Servono due colpi (ha 2 PV).",
+        "Sconfitto il bug, girati verso la gemma con turn_right(), avvicinati e usa collect()."
+      ],
+      "par": 7
     }
   ]
 }

From 902cee78f6fdfc79fecebfa779d8ecd920fed3b4 Mon Sep 17 00:00:00 2001
From: Marco Farina <marco.farina@jcmaxwell.it>
Date: Fri, 3 Jul 2026 10:23:49 +0200
Subject: [PATCH 07/11] fix(pyquest): record onesto, niente spoiler d'esito,
 reset player in render (review fase 3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review del codice della fase 3. Motore validato sotto CPython (19 check
verdi: determinismo del duello, morte, step limit post-win, guard
sensori, defeat count/kind, nessuna vittoria fantasma né sovrapposizioni
melee): nessun bug lato Python. Correzioni tutte lato UI:

- «nuovo record!» compariva a ogni pareggio: recordWin scrive il best
  PRIMA del render del pannello vittoria, quindi il confronto col best
  salvato era sempre vero eguagliando il proprio record. Ora recordWin
  decide (e restituisce) se il run è un record — prima vittoria o
  miglioramento stretto — e index.tsx lo tiene in uno stato catturato
  al momento della vittoria.
- La striscia «Completato · record N» compariva all'inizio
  dell'animazione della prima vittoria (recordWin scatta in finishRun),
  rivelando l'esito in anticipo: durante l'animazione ora è visibile
  solo se il livello era già completato all'avvio del run.
- GamePlayer: al re-run il pannello di esito restava visibile per tutto
  il replay — l'effect su playKey resettava il cursore DOPO che l'effect
  di onStepChange aveva notificato il cursore stantio del run precedente
  (già a fine trace) con la trace nuova, e il genitore chiudeva subito
  l'animazione. Reset spostato in render (pattern «adjust state during
  render»).
- Plurali al valore 1: «1 stella su 3» (aria-label) e «1 azione».
- HintPanel con key={level.id}: i suggerimenti rivelati ripartono da
  zero al cambio livello (anteprima live dell'editor, fase 4).

Verifica: typecheck+lint+build verdi. Verifica visiva nel browser sul
livello duello: prima vittoria con «nuovo record!» e striscia solo a
fine animazione; pareggio senza «nuovo record!» né pannello anticipato;
striscia e record persistenti al reload; console senza warning.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V9dpQX4sKY6tJkTetJz3ho
---
 src/components/PyQuest/GamePlayer.tsx | 19 ++++++------
 src/components/PyQuest/index.tsx      | 44 +++++++++++++++++++++------
 src/components/PyQuest/useProgress.ts | 13 ++++++--
 3 files changed, 54 insertions(+), 22 deletions(-)

diff --git a/src/components/PyQuest/GamePlayer.tsx b/src/components/PyQuest/GamePlayer.tsx
index 87c2a38..416fd63 100644
--- a/src/components/PyQuest/GamePlayer.tsx
+++ b/src/components/PyQuest/GamePlayer.tsx
@@ -17,7 +17,7 @@ import {
   useEffect,
   useMemo,
   useReducer,
-  useRef,
+  useState,
   type CSSProperties,
 } from 'react';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
@@ -111,16 +111,17 @@ export default function GamePlayer({
     { stepIndex: 0, playing: false, speedIdx: DEFAULT_SPEED_IDX },
   );
 
-  // Nuovo run: autoplay dal passo 0 (velocità conservata).
-  const firstRender = useRef(true);
-  useEffect(() => {
-    if (firstRender.current) {
-      firstRender.current = false;
-      return;
-    }
+  // Nuovo run: autoplay dal passo 0 (velocità conservata). Il reset avviene IN
+  // RENDER (pattern «adjust state during render»), non in un effect: con
+  // l'effect, al re-run il cursore stantio del run precedente (già a fine
+  // trace) veniva notificato via onStepChange prima del reset e il genitore
+  // chiudeva subito l'animazione (pannello esito visibile per tutto il replay).
+  const [prevPlayKey, setPrevPlayKey] = useState(playKey);
+  if (prevPlayKey !== playKey) {
+    setPrevPlayKey(playKey);
     dispatch({ type: 'RESET' });
     dispatch({ type: 'TOGGLE_PLAY' });
-  }, [playKey]);
+  }
 
   // Autoplay.
   useEffect(() => {
diff --git a/src/components/PyQuest/index.tsx b/src/components/PyQuest/index.tsx
index 47fc63c..ae26bc5 100644
--- a/src/components/PyQuest/index.tsx
+++ b/src/components/PyQuest/index.tsx
@@ -84,10 +84,18 @@ function ErrorBox({ children }: { children: React.ReactNode }) {
   return <div className={styles.error}>{children}</div>;
 }
 
+/** «1 azione» / «N azioni». */
+function azioni(n: number): string {
+  return n === 1 ? 'azione' : 'azioni';
+}
+
 /** Riga di 3 stelle, piene fino a `n` (spec D11). */
 function Stars({ n }: { n: number }) {
   return (
-    <span className={styles.stars} aria-label={`${n} stelle su 3`}>
+    <span
+      className={styles.stars}
+      aria-label={n === 1 ? '1 stella su 3' : `${n} stelle su 3`}
+    >
       {[1, 2, 3].map((i) => (
         <FontAwesomeIcon
           key={i}
@@ -138,12 +146,19 @@ function PyQuestInner(props: PyQuestProps) {
   const [playKey, setPlayKey] = useState(0);
   const [hasEdits, setHasEdits] = useState(false);
   const [currentCode, setCurrentCode] = useState(starterCode);
+  // Nuovo record di QUESTO run: deciso da recordWin PRIMA di scrivere il best
+  // (dopo la scrittura un pareggio sarebbe indistinguibile da un record).
+  const [isRecord, setIsRecord] = useState(false);
 
   const editorRef = useRef<EditorHandle | null>(null);
   const rootRef = useRef<HTMLDivElement | null>(null);
   const cleanupRef = useRef<(() => void) | null>(null);
   const eventsRef = useRef<GameEvent[]>([]);
   const logsRef = useRef<LogLine[]>([]);
+  // Il livello era già completato all'avvio del run? Serve a non far comparire
+  // la striscia «Completato» durante l'animazione della prima vittoria (recordWin
+  // scatta a inizio animazione: la striscia rivelerebbe l'esito in anticipo).
+  const wasDoneBeforeRunRef = useRef(false);
 
   // Precarica Brython quando il componente entra nel viewport (pattern PyRunner).
   useEffect(() => {
@@ -190,7 +205,7 @@ function PyQuestInner(props: PyQuestProps) {
     );
     // Vittoria: salva completamento e record (solo per livelli identificabili).
     if (hasWin && props.world && props.level) {
-      recordWin(props.world, props.level, countActions(trace));
+      setIsRecord(recordWin(props.world, props.level, countActions(trace)));
     }
     setEvents([...trace]);
     setLogs([...logsRef.current]);
@@ -211,8 +226,10 @@ function PyQuestInner(props: PyQuestProps) {
   const handleRun = useCallback(() => {
     if (!level) return;
     const code = editorRef.current?.getCode() ?? starterCode;
+    wasDoneBeforeRunRef.current = savedProgress?.done === true;
     setPhase('executing');
     setOutcome(null);
+    setIsRecord(false);
     setEvents([]);
     setLogs([]);
     eventsRef.current = [];
@@ -244,7 +261,7 @@ function PyQuestInner(props: PyQuestProps) {
         finishRun();
       },
     });
-  }, [level, starterCode, codeId, libUrl, brython, finishRun]);
+  }, [level, starterCode, codeId, libUrl, brython, finishRun, savedProgress]);
 
   const handleReset = useCallback(() => {
     editorRef.current?.setCode(starterCode);
@@ -320,19 +337,24 @@ function PyQuestInner(props: PyQuestProps) {
   // `savedProgress` porta invece il record persistito, visibile anche a freddo.
   const runSteps = countActions(events);
   const runStars = starsFor(runSteps, level.par);
-  const isRecord =
-    outcome === 'won' &&
-    (savedProgress === undefined || runSteps <= savedProgress.bestSteps);
+  // La striscia «Completato» non deve anticipare l'esito durante l'animazione
+  // della vittoria che l'ha appena sbloccata (recordWin scrive a inizio replay).
+  const showCompleted =
+    savedProgress?.done === true &&
+    (phase === 'idle' || phase === 'finished' || wasDoneBeforeRunRef.current);
 
   return (
     <div ref={rootRef} data-pagefind-ignore className={styles.root}>
       <div className={styles.layout}>
         <div className={styles.stage}>
           {/* Record persistito: visibile anche a freddo (verifica reload). */}
-          {savedProgress?.done && (
+          {showCompleted && savedProgress && (
             <div className={styles.completed}>
               <Stars n={starsFor(savedProgress.bestSteps, level.par)} />
-              <span>Completato · record {savedProgress.bestSteps} azioni</span>
+              <span>
+                Completato · record {savedProgress.bestSteps}{' '}
+                {azioni(savedProgress.bestSteps)}
+              </span>
             </div>
           )}
 
@@ -351,7 +373,7 @@ function PyQuestInner(props: PyQuestProps) {
               <div className={styles.winHead}>
                 <Stars n={runStars} />
                 <span className={styles.winSteps}>
-                  {runSteps} azioni · par {level.par}
+                  {runSteps} {azioni(runSteps)} · par {level.par}
                   {isRecord && (
                     <b className={styles.record}> · nuovo record!</b>
                   )}
@@ -402,7 +424,9 @@ function PyQuestInner(props: PyQuestProps) {
               ariaLabel="Editor di codice Python del livello"
             />
           </div>
-          <HintPanel hints={level.hints} />
+          {/* key: al cambio livello (anteprima live dell'editor) i suggerimenti
+              rivelati ripartono da zero. */}
+          <HintPanel key={level.id} hints={level.hints} />
         </div>
       </div>
     </div>
diff --git a/src/components/PyQuest/useProgress.ts b/src/components/PyQuest/useProgress.ts
index 7ae6f33..d1afcc3 100644
--- a/src/components/PyQuest/useProgress.ts
+++ b/src/components/PyQuest/useProgress.ts
@@ -62,8 +62,13 @@ function writeProgress(next: ProgressShape) {
 export interface UseProgress {
   /** Progresso salvato di un livello (undefined se mai completato). */
   getLevel(worldId: string, levelId: string): LevelProgress | undefined;
-  /** Registra una vittoria: marca `done` e minimizza `bestSteps`. */
-  recordWin(worldId: string, levelId: string, steps: number): void;
+  /**
+   * Registra una vittoria: marca `done` e minimizza `bestSteps`. Ritorna true
+   * se è un nuovo record (prima vittoria o miglioramento **stretto** del best):
+   * va deciso qui, prima della scrittura — dopo, il best salvato coincide col
+   * run e un pareggio sarebbe indistinguibile da un record.
+   */
+  recordWin(worldId: string, levelId: string, steps: number): boolean;
   /** Sblocco calcolato: primo livello o precedente `done` (spec D10). */
   isUnlocked(world: WorldDef, levelId: string): boolean;
 }
@@ -100,12 +105,13 @@ export function useProgress(): UseProgress {
   );
 
   const recordWin = useCallback(
-    (worldId: string, levelId: string, steps: number) => {
+    (worldId: string, levelId: string, steps: number): boolean => {
       // Rileggo dallo storage prima di scrivere: evita di sovrascrivere
       // aggiornamenti fatti da un altro blocco tra un render e l'altro.
       const current = readProgress();
       const world = current.worlds[worldId] ?? { levels: {} };
       const prev = world.levels[levelId];
+      const isRecord = prev === undefined || steps < prev.bestSteps;
       const bestSteps = prev ? Math.min(prev.bestSteps, steps) : steps;
       const next: ProgressShape = {
         ...current,
@@ -122,6 +128,7 @@ export function useProgress(): UseProgress {
       };
       writeProgress(next);
       setProgress(next); // aggiorna subito questo blocco; l'evento fa gli altri
+      return isRecord;
     },
     [],
   );

From 3b50c4af238b4a8ab7aa9e8ed9b73e552879d26a Mon Sep 17 00:00:00 2001
From: Marco Farina <marco.farina@jcmaxwell.it>
Date: Fri, 3 Jul 2026 22:18:17 +0200
Subject: [PATCH 08/11] =?UTF-8?q?feat(pyquest):=20editor=20livelli=20?=
 =?UTF-8?q?=E2=80=94=20paint,=20resize,=20form,=20anteprima=20live,=20expo?=
 =?UTF-8?q?rt/import=20(fase=204)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Nuova pagina interna /level-editor (noindex, non in navbar): disegna un livello
con palette+paint click&drag, ridimensiona la griglia, compila i metadati
(vittoria, nemici, risorse, hint, codice iniziale), lo vede girare
nell'anteprima live <PyQuest levelData={draft} /> e ne esporta/importa il JSON
da incollare in static/pyquest/<mondo>/world.json. Validazione client che
ricalca le regole del plugin build-time. Esporta FACING_DEG da GameScene e
ENEMY_KINDS/RESOURCE_KINDS da characters perché l'editor li riusa nei menu;
index.tsx ora resetta lo stato di gioco quando cambia l'identità del livello
o dello starterCode a runtime, per l'anteprima live dell'editor.

Verificato nel browser (build pulita, paint/resize/validazione, esecuzione
codice nell'anteprima con combat, round-trip export→import esatto, nessun
errore console).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V9dpQX4sKY6tJkTetJz3ho
---
 src/components/PyQuest/GameScene.tsx  |    3 +-
 src/components/PyQuest/characters.tsx |    6 +
 src/components/PyQuest/index.tsx      |   28 +
 src/pages/level-editor.module.css     |  364 +++++++
 src/pages/level-editor.tsx            | 1287 +++++++++++++++++++++++++
 5 files changed, 1687 insertions(+), 1 deletion(-)
 create mode 100644 src/pages/level-editor.module.css
 create mode 100644 src/pages/level-editor.tsx

diff --git a/src/components/PyQuest/GameScene.tsx b/src/components/PyQuest/GameScene.tsx
index 2e6dbab..d980a84 100644
--- a/src/components/PyQuest/GameScene.tsx
+++ b/src/components/PyQuest/GameScene.tsx
@@ -33,7 +33,8 @@ import styles from './GameScene.module.css';
 const MAX_CELL_PX = 48;
 
 // Gradi di rotazione dello sprite per facing (disegnato rivolto a nord).
-const FACING_DEG: Record<Facing, number> = {
+// Esportato: anche l'editor livelli orienta l'eroe con la stessa tabella.
+export const FACING_DEG: Record<Facing, number> = {
   north: 0,
   east: 90,
   south: 180,
diff --git a/src/components/PyQuest/characters.tsx b/src/components/PyQuest/characters.tsx
index 25aaae2..caf742b 100644
--- a/src/components/PyQuest/characters.tsx
+++ b/src/components/PyQuest/characters.tsx
@@ -144,6 +144,9 @@ const ENEMIES: Record<string, Visual> = {
   spider: { icon: faSpider, color: 'var(--pq-enemy)', label: 'ragno' },
 };
 
+/** Kind con uno sprite dedicato (l'editor livelli li offre nei menu). */
+export const ENEMY_KINDS = Object.keys(ENEMIES);
+
 const ENEMY_FALLBACK: Visual = {
   icon: faSkull,
   color: 'var(--pq-enemy)',
@@ -161,6 +164,9 @@ const RESOURCES: Record<string, Visual> = {
   heart: { icon: faHeart, color: 'var(--pq-resource)', label: 'cuore' },
 };
 
+/** Kind con uno sprite dedicato (l'editor livelli li offre nei menu). */
+export const RESOURCE_KINDS = Object.keys(RESOURCES);
+
 const RESOURCE_FALLBACK: Visual = {
   icon: faStar,
   color: 'var(--pq-resource)',
diff --git a/src/components/PyQuest/index.tsx b/src/components/PyQuest/index.tsx
index ae26bc5..e9979b8 100644
--- a/src/components/PyQuest/index.tsx
+++ b/src/components/PyQuest/index.tsx
@@ -187,6 +187,34 @@ function PyQuestInner(props: PyQuestProps) {
 
   useEffect(() => () => cleanupRef.current?.(), []);
 
+  // Cambio di livello a runtime (anteprima live dell'editor livelli): la trace
+  // del run precedente non descrive più il livello — annulla l'eventuale run e
+  // torna a idle. Per i livelli da world data l'identità è stabile: non scatta.
+  const levelRef = useRef(level);
+  useEffect(() => {
+    if (levelRef.current === level) return;
+    levelRef.current = level;
+    cleanupRef.current?.();
+    cleanupRef.current = null;
+    eventsRef.current = [];
+    logsRef.current = [];
+    setPhase('idle');
+    setOutcome(null);
+    setIsRecord(false);
+    setEvents([]);
+    setLogs([]);
+  }, [level]);
+
+  // Anche starterCode può cambiare a runtime (form dell'editor livelli):
+  // l'Editor monta initialCode una sola volta, quindi va allineato a mano —
+  // ma solo finché non ci sono modifiche manuali da preservare.
+  useEffect(() => {
+    if (!hasEdits) {
+      editorRef.current?.setCode(starterCode);
+      setCurrentCode(starterCode);
+    }
+  }, [starterCode, hasEdits]);
+
   const finishRun = useCallback(() => {
     const trace = eventsRef.current;
     const hasWin = trace.some((e) => e.t === 'win');
diff --git a/src/pages/level-editor.module.css b/src/pages/level-editor.module.css
new file mode 100644
index 0000000..690d1ed
--- /dev/null
+++ b/src/pages/level-editor.module.css
@@ -0,0 +1,364 @@
+/* Editor livelli PyQuest (step 17). Strumento d'autore desktop-first. */
+
+.page {
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 2rem 1.5rem 4rem;
+}
+
+.header {
+  margin-bottom: 1.5rem;
+}
+.header h1 {
+  margin-bottom: 0.35rem;
+}
+.header p {
+  color: var(--ifm-color-emphasis-700);
+  max-width: 60ch;
+  margin: 0;
+}
+.headerIcon {
+  color: var(--ifm-color-primary);
+}
+
+.loading {
+  padding: 3rem;
+  text-align: center;
+  color: var(--ifm-color-emphasis-600);
+}
+
+/* Layout a due colonne (canvas | form). */
+.editor {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  gap: 1.25rem;
+  align-items: start;
+}
+@media (max-width: 996px) {
+  .editor {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
+.canvasCol,
+.formCol {
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+  min-width: 0;
+}
+
+.panel {
+  background: var(
+    --ifm-card-background-color,
+    var(--ifm-background-surface-color)
+  );
+  border: 1px solid var(--ifm-color-emphasis-200);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-card);
+  padding: 1rem 1.1rem;
+}
+
+.panelTitle {
+  font-size: 1rem;
+  margin: 0 0 0.6rem;
+}
+.panelHead {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  margin-bottom: 0.6rem;
+}
+.panelHead .panelTitle {
+  margin: 0;
+}
+
+.hint {
+  font-size: 0.82rem;
+  color: var(--ifm-color-emphasis-600);
+  margin: 0 0 0.75rem;
+  line-height: 1.4;
+}
+.hint code {
+  font-size: 0.78rem;
+}
+
+/* Palette + resize. */
+.paletteRow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 0.75rem;
+  margin-bottom: 0.5rem;
+}
+.palette {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.4rem;
+}
+.paletteBtn {
+  border: 1px solid var(--ifm-color-emphasis-300);
+  background: var(--ifm-background-color);
+  color: var(--ifm-font-color-base);
+  border-radius: var(--radius-sm);
+  padding: 0.35rem 0.7rem;
+  font-size: 0.85rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition:
+    background var(--dur-fast) var(--ease-out),
+    border-color var(--dur-fast) var(--ease-out),
+    transform var(--dur-fast) var(--ease-out);
+}
+.paletteBtn:hover {
+  border-color: var(--ifm-color-primary);
+}
+.paletteBtn:active {
+  transform: scale(0.98);
+}
+.paletteActive {
+  background: var(--ifm-color-primary);
+  border-color: var(--ifm-color-primary);
+  color: #fff;
+}
+
+.sizeCtrl {
+  display: flex;
+  gap: 0.75rem;
+}
+.sizeCtrl label {
+  display: flex;
+  flex-direction: column;
+  font-size: 0.72rem;
+  font-weight: 600;
+  color: var(--ifm-color-emphasis-600);
+  gap: 0.2rem;
+}
+.sizeCtrl input {
+  width: 4rem;
+}
+
+/* Griglia editabile. Cella a lato fisso (strumento desktop-first): niente
+   percentuali circolari con `width: fit-content`. */
+.board {
+  --ed-cell: 40px;
+  display: grid;
+  grid-template-columns: repeat(var(--ed-cols), var(--ed-cell));
+  grid-template-rows: repeat(var(--ed-rows), var(--ed-cell));
+  gap: 2px;
+  padding: 6px;
+  background: var(--ed-board-bg);
+  border-radius: var(--radius-sm);
+  width: fit-content;
+  max-width: 100%;
+  overflow: auto;
+  user-select: none;
+  touch-action: none;
+}
+
+/* Le celle riempiono la griglia in auto-placement (ordine row-major nel tsx);
+   quadrate come in GameScene, niente radius fuori scala token. */
+.cell {
+  width: var(--ed-cell);
+  height: var(--ed-cell);
+  padding: 0;
+  border: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  position: relative;
+  font-size: calc(var(--ed-cell) * 0.5);
+  transition: box-shadow var(--dur-fast) var(--ease-out);
+}
+.cell:hover {
+  box-shadow: inset 0 0 0 2px var(--ifm-color-primary);
+}
+.cellFloor {
+  background: var(--ed-floor);
+}
+.cellWall {
+  background: var(--ed-wall);
+}
+
+.mark {
+  pointer-events: none;
+  line-height: 1;
+}
+.markHero {
+  color: var(--ed-hero);
+  display: inline-flex;
+}
+.markGoal {
+  color: var(--ed-goal);
+  position: absolute;
+  inset: 0;
+  margin: auto;
+  opacity: 0.85;
+}
+.markEnemy {
+  color: var(--ed-enemy);
+  position: absolute;
+  right: 2px;
+  bottom: 2px;
+  font-size: calc(var(--ed-cell) * 0.42);
+}
+.markResource {
+  color: var(--ed-resource);
+  position: absolute;
+  left: 2px;
+  top: 2px;
+  font-size: calc(var(--ed-cell) * 0.42);
+}
+
+/* Colori griglia (allineati a GameScene, override dark dedicato). */
+.board {
+  --ed-board-bg: #e9edf2;
+  --ed-floor: #f5f7fa;
+  --ed-wall: #40495b;
+  --ed-hero: var(--ifm-color-primary);
+  --ed-goal: #2f9e44;
+  --ed-enemy: #d6336c;
+  --ed-resource: #f08c00;
+}
+html[data-theme='dark'] .board {
+  --ed-board-bg: #14161c;
+  --ed-floor: #1e2230;
+  --ed-wall: #2b3245;
+  --ed-goal: #51cf66;
+  --ed-enemy: #f06595;
+  --ed-resource: #ffc078;
+}
+
+/* Errori di validazione. */
+.errors {
+  margin: 0 0 0.9rem;
+  padding: 0.6rem 0.9rem 0.6rem 1.5rem;
+  border-radius: var(--radius-sm);
+  background: color-mix(in srgb, var(--ifm-color-danger) 12%, transparent);
+  color: var(--ifm-color-danger-darker);
+  font-size: 0.85rem;
+}
+.errors li {
+  margin: 0.15rem 0;
+}
+html[data-theme='dark'] .errors {
+  color: var(--ifm-color-danger-lightest);
+}
+
+/* Form metadati. */
+.fieldGrid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0.75rem;
+}
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  font-size: 0.78rem;
+  font-weight: 600;
+  color: var(--ifm-color-emphasis-700);
+}
+.field input,
+.field select {
+  font-weight: 400;
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.5rem;
+}
+.rowId {
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.78rem;
+  color: var(--ifm-color-emphasis-600);
+  min-width: 5.5rem;
+}
+.grow {
+  flex: 1;
+}
+.numSmall {
+  width: 4.5rem;
+}
+
+/* Input comuni. */
+.editor input[type='text'],
+.editor input[type='number'],
+.editor select,
+.editor textarea {
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--radius-xs);
+  background: var(--ifm-background-color);
+  color: var(--ifm-font-color-base);
+  padding: 0.35rem 0.5rem;
+  font-size: 0.85rem;
+  font-family: inherit;
+}
+.editor input:focus,
+.editor select:focus,
+.editor textarea:focus {
+  outline: 2px solid var(--ifm-color-primary);
+  outline-offset: -1px;
+  border-color: transparent;
+}
+
+.code {
+  width: 100%;
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.8rem;
+  line-height: 1.45;
+  resize: vertical;
+  margin-bottom: 0.75rem;
+}
+
+/* Bottoni azione. */
+.addBtn {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  background: var(--ifm-background-color);
+  color: var(--ifm-font-color-base);
+  border-radius: var(--radius-sm);
+  padding: 0.3rem 0.65rem;
+  font-size: 0.8rem;
+  font-weight: 600;
+  cursor: pointer;
+  white-space: nowrap;
+  transition:
+    border-color var(--dur-fast) var(--ease-out),
+    transform var(--dur-fast) var(--ease-out);
+}
+.addBtn:hover {
+  border-color: var(--ifm-color-primary);
+}
+.addBtn:active {
+  transform: scale(0.98);
+}
+
+.iconBtn {
+  border: 1px solid transparent;
+  background: transparent;
+  color: var(--ifm-color-emphasis-600);
+  border-radius: var(--radius-xs);
+  padding: 0.3rem 0.45rem;
+  cursor: pointer;
+  transition:
+    color var(--dur-fast) var(--ease-out),
+    background var(--dur-fast) var(--ease-out);
+}
+.iconBtn:hover {
+  color: var(--ifm-color-danger);
+  background: color-mix(in srgb, var(--ifm-color-danger) 12%, transparent);
+}
+
+.importError {
+  color: var(--ifm-color-danger);
+  font-size: 0.82rem;
+  margin: 0 0 0.5rem;
+}
diff --git a/src/pages/level-editor.tsx b/src/pages/level-editor.tsx
new file mode 100644
index 0000000..2ecf207
--- /dev/null
+++ b/src/pages/level-editor.tsx
@@ -0,0 +1,1287 @@
+/**
+ * Editor di livelli PyQuest (spec step 17) — `/level-editor`.
+ *
+ * Strumento interno d'autore, non linkato in navbar e `noindex`: disegna un
+ * livello (palette + paint click&drag, resize griglia, form metadati), lo vede
+ * girare nell'anteprima live `<PyQuest levelData={draft} />`, e ne esporta il
+ * JSON da incollare in `static/pyquest/<mondo>/world.json`.
+ *
+ * Il modello interno (`Draft`) è comodo per l'editing (muri come array di bool,
+ * eroe/goal/entità come oggetti); `draftToLevel` lo proietta sullo schema
+ * `LevelDef` (speculare al world.json) e `levelToDraft` fa il verso inverso in
+ * import. La validazione ricalca le regole del plugin build-time
+ * (`plugins/pyquest/index.js`) così l'anteprima segnala in anticipo ciò che
+ * romperebbe la build.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import Head from '@docusaurus/Head';
+import BrowserOnly from '@docusaurus/BrowserOnly';
+import Layout from '@theme/Layout';
+import Heading from '@theme/Heading';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import {
+  faPenRuler,
+  faPlus,
+  faTrash,
+  faCopy,
+  faFileImport,
+  faRobot,
+} from '@fortawesome/free-solid-svg-icons';
+import clsx from 'clsx';
+import type { CSSProperties } from 'react';
+import PyQuest from '@site/src/components/PyQuest';
+import {
+  ENEMY_KINDS,
+  RESOURCE_KINDS,
+  enemyVisual,
+  resourceVisual,
+  GOAL_ICON,
+} from '@site/src/components/PyQuest/characters';
+import { FACING_DEG } from '@site/src/components/PyQuest/GameScene';
+import { copyToClipboard } from '@site/src/theme/PyRunner/clipboard';
+import type {
+  EnemyBehavior,
+  EnemyDef,
+  Facing,
+  LevelDef,
+  ResourceDef,
+  WinCond,
+} from '@site/src/components/PyQuest/types';
+import styles from './level-editor.module.css';
+
+// --- Costanti d'autore --------------------------------------------------------
+
+type Tool = 'wall' | 'floor' | 'hero' | 'goal' | 'enemy' | 'resource';
+
+const FACINGS: Facing[] = ['north', 'east', 'south', 'west'];
+const FACING_LABEL: Record<Facing, string> = {
+  north: 'nord',
+  east: 'est',
+  south: 'sud',
+  west: 'ovest',
+};
+const BEHAVIORS: EnemyBehavior[] = ['static', 'melee'];
+const WIN_TYPES: WinCond['type'][] = ['reach', 'collect', 'defeat'];
+
+const MIN_SIZE = 3;
+const MAX_SIZE = 15;
+const DEFAULT_SIZE = 7;
+/** Tetto sui punti vita: la scena renderizza un'icona per PV (cuori/pip). */
+const MAX_HP = 99;
+
+const PALETTE: { tool: Tool; label: string }[] = [
+  { tool: 'wall', label: 'Muro' },
+  { tool: 'floor', label: 'Pavimento' },
+  { tool: 'hero', label: 'Eroe' },
+  { tool: 'goal', label: 'Bandiera' },
+  { tool: 'enemy', label: 'Nemico' },
+  { tool: 'resource', label: 'Risorsa' },
+];
+
+// --- Modello di editing -------------------------------------------------------
+
+interface Draft {
+  id: string;
+  title: string;
+  width: number;
+  height: number;
+  /** Muri: `walls[y * width + x]`. */
+  walls: boolean[];
+  hero: { x: number; y: number; facing: Facing; hp: number };
+  goal: { x: number; y: number } | null;
+  enemies: EnemyDef[];
+  resources: ResourceDef[];
+  win: WinCond[];
+  hints: string[];
+  par: number;
+  maxSteps: number | null;
+  starterCode: string;
+  solution: string;
+}
+
+/** Stanza vuota bordata di muri, eroe in alto a sinistra, bandiera in fondo. */
+function emptyDraft(width: number, height: number): Draft {
+  const walls: boolean[] = [];
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const border = x === 0 || y === 0 || x === width - 1 || y === height - 1;
+      walls.push(border);
+    }
+  }
+  return {
+    id: 'nuovo-livello',
+    title: 'Nuovo livello',
+    width,
+    height,
+    walls,
+    hero: { x: 1, y: 1, facing: 'east', hp: 3 },
+    goal: { x: width - 2, y: height - 2 },
+    enemies: [],
+    resources: [],
+    win: [{ type: 'reach' }],
+    hints: ['Primo suggerimento.'],
+    par: 1,
+    maxSteps: null,
+    starterCode: '# Scrivi qui il codice iniziale che vede lo studente.\n',
+    solution: '',
+  };
+}
+
+function allIds(d: Draft): Set<string> {
+  return new Set([
+    ...d.enemies.map((e) => e.id),
+    ...d.resources.map((r) => r.id),
+  ]);
+}
+
+/** Primo `prefix + n` (n ≥ 1) non ancora usato. */
+function freeId(prefix: string, used: Set<string>): string {
+  let n = 1;
+  while (used.has(`${prefix}${n}`)) n++;
+  return `${prefix}${n}`;
+}
+
+/** Copia di `arr` con l'elemento in posizione `i` sostituito da `next`. */
+function replaceAt<T>(arr: T[], i: number, next: T): T[] {
+  return arr.map((x, j) => (j === i ? next : x));
+}
+
+/** Copia di `arr` senza l'elemento in posizione `i`. */
+function removeAt<T>(arr: T[], i: number): T[] {
+  return arr.filter((_, j) => j !== i);
+}
+
+// --- Proiezioni Draft ↔ LevelDef ---------------------------------------------
+
+function draftToLevel(d: Draft): LevelDef {
+  const rows: string[] = [];
+  for (let y = 0; y < d.height; y++) {
+    let row = '';
+    for (let x = 0; x < d.width; x++) {
+      row += d.walls[y * d.width + x] ? '#' : '.';
+    }
+    rows.push(row);
+  }
+  const level: LevelDef = {
+    id: d.id,
+    title: d.title,
+    grid: { legend: { '#': 'wall', '.': 'floor' }, rows },
+    hero: d.hero,
+    win: d.win,
+    starterCode: d.starterCode,
+    hints: d.hints,
+    par: d.par,
+  };
+  if (d.goal) level.goal = d.goal;
+  if (d.enemies.length) level.enemies = d.enemies;
+  if (d.resources.length) level.resources = d.resources;
+  if (d.solution.trim()) level.solution = d.solution;
+  if (d.maxSteps != null) level.maxSteps = d.maxSteps;
+  return level;
+}
+
+/**
+ * Import: proietta un `LevelDef` (già filtrato da `handleImport`) sul modello.
+ * I campi stringa e numerici vengono coercitivamente normalizzati: un JSON
+ * scritto a mano può avere tipi sbagliati o campi mancanti, e un draft con
+ * `undefined` dove i form si aspettano un valore renderebbe gli input
+ * uncontrolled (o farebbe crashare la pagina) invece di mostrare un errore
+ * di validazione. I fallback sono valori invalidi apposta ('' e 0/-1): la
+ * validazione li segnala, senza riparare il livello di nascosto.
+ */
+function str(v: unknown): string {
+  return typeof v === 'string' ? v : '';
+}
+
+function num(v: unknown, fallback: number): number {
+  return typeof v === 'number' ? v : fallback;
+}
+
+function levelToDraft(level: LevelDef): Draft {
+  const rows = level.grid.rows;
+  const height = rows.length;
+  const width = rows[0].length;
+  const wallChars = new Set(
+    Object.entries(level.grid.legend)
+      .filter(([, role]) => role === 'wall')
+      .map(([ch]) => ch),
+  );
+  const walls: boolean[] = [];
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      walls.push(wallChars.has(rows[y][x]));
+    }
+  }
+  return {
+    id: str(level.id),
+    title: str(level.title),
+    width,
+    height,
+    walls,
+    hero: {
+      x: num(level.hero.x, -1),
+      y: num(level.hero.y, -1),
+      facing: FACINGS.includes(level.hero.facing) ? level.hero.facing : 'east',
+      hp: num(level.hero.hp ?? 3, 0),
+    },
+    goal: level.goal ?? null,
+    enemies: (Array.isArray(level.enemies) ? level.enemies : []).map((e) => ({
+      ...e,
+      id: str(e.id),
+      kind: str(e.kind),
+      x: num(e.x, -1),
+      y: num(e.y, -1),
+      hp: num(e.hp, 0),
+    })),
+    resources: (Array.isArray(level.resources) ? level.resources : []).map(
+      (r) => ({
+        ...r,
+        id: str(r.id),
+        kind: str(r.kind),
+        x: num(r.x, -1),
+        y: num(r.y, -1),
+      }),
+    ),
+    win: level.win.map((c) =>
+      c.type === 'collect'
+        ? { ...c, kind: str(c.kind), qty: num(c.qty, 0) }
+        : c.type === 'defeat'
+          ? {
+              ...c,
+              kind: c.kind === undefined ? undefined : str(c.kind),
+              count: c.count === undefined ? undefined : num(c.count, 0),
+            }
+          : c,
+    ),
+    hints: level.hints,
+    par: num(level.par, 0),
+    maxSteps: level.maxSteps == null ? null : num(level.maxSteps, 0),
+    starterCode: str(level.starterCode),
+    solution: str(level.solution),
+  };
+}
+
+// --- Validazione (ricalca plugins/pyquest/index.js) ---------------------------
+
+const FORBIDDEN = /['"\\]/;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f]/;
+
+function safeId(v: unknown): boolean {
+  return (
+    typeof v === 'string' &&
+    v.length > 0 &&
+    !FORBIDDEN.test(v) &&
+    !CONTROL.test(v)
+  );
+}
+
+/** Intero ≥ min: gli input `type="number"` lasciano passare anche i decimali. */
+function intAtLeast(v: unknown, min: number): boolean {
+  return typeof v === 'number' && Number.isInteger(v) && v >= min;
+}
+
+/** Punti vita sensati: intero in [1, MAX_HP] (la scena disegna un'icona a PV). */
+function validHp(v: unknown): boolean {
+  return intAtLeast(v, 1) && (v as number) <= MAX_HP;
+}
+
+/** Elenco di problemi che romperebbero l'import in world.json (vuoto = ok). */
+function validateDraft(d: Draft): string[] {
+  const errs: string[] = [];
+  // Cella valida per un'entità: dentro la griglia e non su un muro (il plugin
+  // fa lo stesso check con assertOnFloor). Raggiungibile via import: il paint
+  // non permette di creare queste configurazioni.
+  const onFloor = (x: number, y: number) =>
+    Number.isInteger(x) &&
+    Number.isInteger(y) &&
+    x >= 0 &&
+    y >= 0 &&
+    x < d.width &&
+    y < d.height &&
+    !d.walls[y * d.width + x];
+
+  if (!safeId(d.id)) {
+    errs.push(
+      'L’id deve essere non vuoto e senza apici, virgolette o backslash.',
+    );
+  }
+  if (!d.title.trim()) errs.push('Il titolo è obbligatorio.');
+
+  if (!onFloor(d.hero.x, d.hero.y)) {
+    errs.push('L’eroe è fuori dalla griglia o su una cella muro.');
+  }
+  if (!validHp(d.hero.hp)) {
+    errs.push(
+      `I punti vita dell’eroe devono essere un intero tra 1 e ${MAX_HP}.`,
+    );
+  }
+
+  if (d.goal && !onFloor(d.goal.x, d.goal.y)) {
+    errs.push('La bandiera è fuori dalla griglia o su una cella muro.');
+  }
+
+  if (d.win.length === 0) {
+    errs.push('Serve almeno una condizione di vittoria.');
+  }
+  for (const cond of d.win) {
+    if (cond.type === 'reach' && !d.goal) {
+      errs.push('Vittoria «raggiungi» ma il livello non ha una bandiera.');
+    }
+    if (cond.type === 'collect') {
+      if (!safeId(cond.kind))
+        errs.push('Vittoria «raccogli»: tipo risorsa non valido.');
+      if (!intAtLeast(cond.qty, 1)) {
+        errs.push(
+          'Vittoria «raccogli»: la quantità deve essere un intero ≥ 1.',
+        );
+      }
+    }
+    if (cond.type === 'defeat') {
+      if (cond.kind !== undefined && !safeId(cond.kind)) {
+        errs.push('Vittoria «sconfiggi»: tipo nemico non valido.');
+      }
+      if (cond.count !== undefined && !intAtLeast(cond.count, 1)) {
+        errs.push(
+          'Vittoria «sconfiggi»: il conteggio deve essere un intero ≥ 1.',
+        );
+      }
+    }
+  }
+
+  const ids = new Set<string>();
+  for (const e of d.enemies) {
+    if (!safeId(e.id) || ids.has(e.id))
+      errs.push(`Nemico con id non valido o duplicato: «${e.id}».`);
+    ids.add(e.id);
+    if (!safeId(e.kind)) errs.push(`Nemico «${e.id}»: tipo non valido.`);
+    if (!onFloor(e.x, e.y))
+      errs.push(`Nemico «${e.id}»: fuori dalla griglia o su una cella muro.`);
+    if (!validHp(e.hp))
+      errs.push(
+        `Nemico «${e.id}»: i punti vita devono essere un intero tra 1 e ${MAX_HP}.`,
+      );
+    if (!BEHAVIORS.includes(e.behavior))
+      errs.push(`Nemico «${e.id}»: comportamento non valido (static|melee).`);
+  }
+  for (const r of d.resources) {
+    if (!safeId(r.id) || ids.has(r.id))
+      errs.push(`Risorsa con id non valido o duplicato: «${r.id}».`);
+    ids.add(r.id);
+    if (!safeId(r.kind)) errs.push(`Risorsa «${r.id}»: tipo non valido.`);
+    if (!onFloor(r.x, r.y))
+      errs.push(`Risorsa «${r.id}»: fuori dalla griglia o su una cella muro.`);
+  }
+
+  if (
+    d.hints.length < 1 ||
+    d.hints.length > 3 ||
+    d.hints.some((h) => typeof h !== 'string' || !h.trim())
+  ) {
+    errs.push('Servono da uno a tre suggerimenti, tutti non vuoti.');
+  }
+  if (!intAtLeast(d.par, 1)) {
+    errs.push('Il par deve essere un intero ≥ 1.');
+  }
+  if (d.maxSteps != null && !intAtLeast(d.maxSteps, 1)) {
+    errs.push('maxSteps deve essere un intero ≥ 1.');
+  }
+  return errs;
+}
+
+// --- Griglia editabile --------------------------------------------------------
+
+interface GridStyle extends CSSProperties {
+  '--ed-cols'?: number;
+  '--ed-rows'?: number;
+}
+
+function EditableGrid({
+  draft,
+  tool,
+  paint,
+}: {
+  draft: Draft;
+  tool: Tool;
+  paint: (x: number, y: number) => void;
+}) {
+  const painting = useRef(false);
+
+  useEffect(() => {
+    const up = () => {
+      painting.current = false;
+    };
+    window.addEventListener('mouseup', up);
+    return () => window.removeEventListener('mouseup', up);
+  }, []);
+
+  const enemyAt = (x: number, y: number) =>
+    draft.enemies.find((e) => e.x === x && e.y === y);
+  const resourceAt = (x: number, y: number) =>
+    draft.resources.find((r) => r.x === x && r.y === y);
+
+  const boardStyle: GridStyle = {
+    '--ed-cols': draft.width,
+    '--ed-rows': draft.height,
+  };
+
+  // Celle in ordine row-major: l'auto-placement della griglia CSS le posiziona
+  // da solo (niente coordinate inline per cella; l'ordine è load-bearing).
+  const cells = [];
+  for (let y = 0; y < draft.height; y++) {
+    for (let x = 0; x < draft.width; x++) {
+      const wall = draft.walls[y * draft.width + x];
+      const isHero = draft.hero.x === x && draft.hero.y === y;
+      const isGoal = draft.goal?.x === x && draft.goal?.y === y;
+      const enemy = enemyAt(x, y);
+      const resource = resourceAt(x, y);
+      cells.push(
+        <button
+          type="button"
+          key={`${x},${y}`}
+          className={clsx(
+            styles.cell,
+            wall ? styles.cellWall : styles.cellFloor,
+          )}
+          title={`(${x}, ${y})`}
+          aria-label={`Cella ${x}, ${y}`}
+          onMouseDown={(e) => {
+            e.preventDefault();
+            painting.current = true;
+            paint(x, y);
+          }}
+          onMouseEnter={(e) => {
+            // e.buttons: se il tasto è stato rilasciato fuori dalla finestra
+            // il mouseup su window non arriva mai — non fidarsi del solo ref.
+            if (
+              painting.current &&
+              (e.buttons & 1) === 1 &&
+              (tool === 'wall' || tool === 'floor')
+            ) {
+              paint(x, y);
+            }
+          }}
+        >
+          {isGoal && (
+            <FontAwesomeIcon
+              icon={GOAL_ICON}
+              className={clsx(styles.mark, styles.markGoal)}
+            />
+          )}
+          {resource && (
+            <FontAwesomeIcon
+              icon={resourceVisual(resource.kind).icon}
+              className={clsx(styles.mark, styles.markResource)}
+            />
+          )}
+          {enemy && (
+            <FontAwesomeIcon
+              icon={enemyVisual(enemy.kind).icon}
+              className={clsx(styles.mark, styles.markEnemy)}
+            />
+          )}
+          {isHero && (
+            <span
+              className={clsx(styles.mark, styles.markHero)}
+              style={{
+                transform: `rotate(${FACING_DEG[draft.hero.facing]}deg)`,
+              }}
+            >
+              <FontAwesomeIcon icon={faRobot} />
+            </span>
+          )}
+        </button>,
+      );
+    }
+  }
+
+  return (
+    <div className={styles.board} style={boardStyle}>
+      {cells}
+    </div>
+  );
+}
+
+// --- Editor completo (client-only) -------------------------------------------
+
+function LevelEditorInner() {
+  const [draft, setDraft] = useState<Draft>(() =>
+    emptyDraft(DEFAULT_SIZE, DEFAULT_SIZE),
+  );
+  const [tool, setTool] = useState<Tool>('wall');
+  // Testo grezzo degli input dimensione: applicare il resize (con clamp) a ogni
+  // keystroke distruggerebbe la griglia digitando — «12» passa per «1», e il
+  // campo svuotato varrebbe 0 → troncamento a MIN_SIZE con perdita di muri ed
+  // entità. Il resize scatta solo quando il testo è un intero nel range.
+  const [sizeText, setSizeText] = useState({
+    width: String(DEFAULT_SIZE),
+    height: String(DEFAULT_SIZE),
+  });
+  const [importText, setImportText] = useState('');
+  const [importError, setImportError] = useState<string | null>(null);
+  const [copied, setCopied] = useState(false);
+
+  const level = useMemo(() => draftToLevel(draft), [draft]);
+  const errors = useMemo(() => validateDraft(draft), [draft]);
+  const exportJson = useMemo(() => JSON.stringify(level, null, 2), [level]);
+
+  const paint = useCallback(
+    (x: number, y: number) => {
+      setDraft((d) => {
+        const i = y * d.width + x;
+        const isWall = d.walls[i];
+        switch (tool) {
+          case 'wall': {
+            if (d.hero.x === x && d.hero.y === y) return d; // niente muro sull’eroe
+            const hasGoal = d.goal !== null && d.goal.x === x && d.goal.y === y;
+            const hasEntity =
+              d.enemies.some((e) => e.x === x && e.y === y) ||
+              d.resources.some((r) => r.x === x && r.y === y);
+            // Già muro e niente da spazzare via: no-op (il trascinamento su
+            // muri esistenti non deve rifare draft → anteprima a ogni cella).
+            if (isWall && !hasGoal && !hasEntity) return d;
+            const walls = [...d.walls];
+            walls[i] = true;
+            return {
+              ...d,
+              walls,
+              goal: hasGoal ? null : d.goal,
+              enemies: d.enemies.filter((e) => !(e.x === x && e.y === y)),
+              resources: d.resources.filter((r) => !(r.x === x && r.y === y)),
+            };
+          }
+          case 'floor': {
+            if (!isWall) return d;
+            const walls = [...d.walls];
+            walls[i] = false;
+            return { ...d, walls };
+          }
+          case 'hero': {
+            if (isWall) return d;
+            return { ...d, hero: { ...d.hero, x, y } };
+          }
+          case 'goal': {
+            if (isWall) return d;
+            if (d.goal && d.goal.x === x && d.goal.y === y)
+              return { ...d, goal: null };
+            return { ...d, goal: { x, y } };
+          }
+          case 'enemy': {
+            if (isWall || (d.hero.x === x && d.hero.y === y)) return d;
+            const existing = d.enemies.find((e) => e.x === x && e.y === y);
+            if (existing)
+              return { ...d, enemies: d.enemies.filter((e) => e !== existing) };
+            const id = freeId('e', allIds(d));
+            return {
+              ...d,
+              enemies: [
+                ...d.enemies,
+                { id, kind: 'bug', x, y, hp: 2, behavior: 'melee' },
+              ],
+            };
+          }
+          case 'resource': {
+            if (isWall || (d.hero.x === x && d.hero.y === y)) return d;
+            const existing = d.resources.find((r) => r.x === x && r.y === y);
+            if (existing)
+              return {
+                ...d,
+                resources: d.resources.filter((r) => r !== existing),
+              };
+            const id = freeId('r', allIds(d));
+            return {
+              ...d,
+              resources: [...d.resources, { id, kind: 'gem', x, y }],
+            };
+          }
+          default:
+            return d;
+        }
+      });
+    },
+    [tool],
+  );
+
+  const resize = useCallback((dim: 'width' | 'height', raw: string) => {
+    setSizeText((s) => ({ ...s, [dim]: raw }));
+    const size = Number(raw);
+    if (!Number.isInteger(size) || size < MIN_SIZE || size > MAX_SIZE) return;
+    setDraft((d) => {
+      const width = dim === 'width' ? size : d.width;
+      const height = dim === 'height' ? size : d.height;
+      const walls: boolean[] = [];
+      for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+          walls.push(
+            x < d.width && y < d.height ? d.walls[y * d.width + x] : false,
+          );
+        }
+      }
+      const inB = (p: { x: number; y: number }) => p.x < width && p.y < height;
+      const hero = inB(d.hero)
+        ? d.hero
+        : {
+            ...d.hero,
+            x: Math.min(d.hero.x, width - 1),
+            y: Math.min(d.hero.y, height - 1),
+          };
+      return {
+        ...d,
+        width,
+        height,
+        walls,
+        hero,
+        goal: d.goal && inB(d.goal) ? d.goal : null,
+        enemies: d.enemies.filter(inB),
+        resources: d.resources.filter(inB),
+      };
+    });
+  }, []);
+
+  const patch = useCallback((p: Partial<Draft>) => {
+    setDraft((d) => ({ ...d, ...p }));
+  }, []);
+
+  const handleImport = useCallback(() => {
+    setImportError(null);
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(importText);
+    } catch {
+      setImportError('JSON non valido.');
+      return;
+    }
+    const lvl = parsed as LevelDef;
+    if (
+      !lvl ||
+      typeof lvl !== 'object' ||
+      !lvl.grid ||
+      !Array.isArray(lvl.grid.rows) ||
+      lvl.grid.rows.length === 0 ||
+      lvl.grid.rows.some((row) => typeof row !== 'string') ||
+      !lvl.hero ||
+      !Array.isArray(lvl.win) ||
+      !Array.isArray(lvl.hints)
+    ) {
+      setImportError(
+        'Non sembra un livello PyQuest (mancano grid/hero/win/hints).',
+      );
+      return;
+    }
+    // Il plugin rifiuta le griglie non rettangolari; qui il modello a walls[]
+    // le «riparerebbe» in silenzio (righe corte → pavimento, righe lunghe
+    // troncate), riscrivendo la geometria — meglio rifiutare anche noi.
+    if (lvl.grid.rows.some((row) => row.length !== lvl.grid.rows[0].length)) {
+      setImportError(
+        'Griglia non rettangolare: tutte le righe devono avere la stessa lunghezza.',
+      );
+      return;
+    }
+    // Il form può rendere solo i tipi che conosce: win e hints malformati
+    // farebbero crashare il render, meglio rifiutarli con un messaggio.
+    if (
+      lvl.win.some(
+        (c) =>
+          !c ||
+          typeof c !== 'object' ||
+          !(WIN_TYPES as string[]).includes(c.type),
+      )
+    ) {
+      setImportError(
+        'Condizioni di vittoria non riconosciute (attesi reach/collect/defeat).',
+      );
+      return;
+    }
+    if (lvl.hints.some((h) => typeof h !== 'string')) {
+      setImportError('I suggerimenti devono essere stringhe.');
+      return;
+    }
+    if (
+      [
+        ...(Array.isArray(lvl.enemies) ? lvl.enemies : []),
+        ...(Array.isArray(lvl.resources) ? lvl.resources : []),
+      ].some((e) => !e || typeof e !== 'object')
+    ) {
+      setImportError('Nemici o risorse malformati (attesi oggetti).');
+      return;
+    }
+    try {
+      const next = levelToDraft(lvl);
+      setDraft(next);
+      setSizeText({ width: String(next.width), height: String(next.height) });
+      setImportText('');
+    } catch {
+      setImportError('Livello illeggibile: controlla la struttura.');
+    }
+  }, [importText]);
+
+  const handleCopy = useCallback(() => {
+    copyToClipboard(exportJson)
+      .then(() => {
+        setCopied(true);
+        window.setTimeout(() => setCopied(false), 1500);
+      })
+      .catch(() => setCopied(false));
+  }, [exportJson]);
+
+  return (
+    <div className={styles.editor}>
+      {/* Colonna sinistra: disegno + anteprima */}
+      <div className={styles.canvasCol}>
+        <section className={styles.panel}>
+          <div className={styles.paletteRow}>
+            <div className={styles.palette} role="group" aria-label="Strumenti">
+              {PALETTE.map((p) => (
+                <button
+                  key={p.tool}
+                  type="button"
+                  className={clsx(
+                    styles.paletteBtn,
+                    tool === p.tool && styles.paletteActive,
+                  )}
+                  aria-pressed={tool === p.tool}
+                  onClick={() => setTool(p.tool)}
+                >
+                  {p.label}
+                </button>
+              ))}
+            </div>
+            <div className={styles.sizeCtrl}>
+              <label>
+                Larghezza
+                <input
+                  type="number"
+                  min={MIN_SIZE}
+                  max={MAX_SIZE}
+                  value={sizeText.width}
+                  onChange={(e) => resize('width', e.target.value)}
+                  onBlur={() =>
+                    setSizeText({
+                      width: String(draft.width),
+                      height: String(draft.height),
+                    })
+                  }
+                />
+              </label>
+              <label>
+                Altezza
+                <input
+                  type="number"
+                  min={MIN_SIZE}
+                  max={MAX_SIZE}
+                  value={sizeText.height}
+                  onChange={(e) => resize('height', e.target.value)}
+                  onBlur={() =>
+                    setSizeText({
+                      width: String(draft.width),
+                      height: String(draft.height),
+                    })
+                  }
+                />
+              </label>
+            </div>
+          </div>
+          <p className={styles.hint}>
+            Seleziona uno strumento e disegna sulla griglia (muro e pavimento
+            supportano il trascinamento). Con «Nemico» o «Risorsa» clicca una
+            cella occupata per rimuoverla; con «Bandiera» clicca la bandiera per
+            toglierla.
+          </p>
+          <EditableGrid draft={draft} tool={tool} paint={paint} />
+        </section>
+
+        <section className={styles.panel}>
+          <Heading as="h2" className={styles.panelTitle}>
+            Anteprima
+          </Heading>
+          {errors.length > 0 && (
+            <ul className={styles.errors}>
+              {errors.map((e) => (
+                <li key={e}>{e}</li>
+              ))}
+            </ul>
+          )}
+          {/* Anteprima solo su draft valido: un livello che la validazione
+              rifiuta salterebbe le guardie che il plugin garantisce a build
+              time (quoting delle stringhe iniettate in Python, geometria).
+              PyQuest assorbe live i cambi di levelData e starterCode. */}
+          {errors.length === 0 ? (
+            <PyQuest levelData={level} character="byte" />
+          ) : (
+            <p className={styles.hint}>
+              Correggi gli errori qui sopra per vedere l’anteprima.
+            </p>
+          )}
+        </section>
+      </div>
+
+      {/* Colonna destra: metadati + import/export */}
+      <div className={styles.formCol}>
+        <section className={styles.panel}>
+          <Heading as="h2" className={styles.panelTitle}>
+            Metadati
+          </Heading>
+          <div className={styles.fieldGrid}>
+            <label className={styles.field}>
+              <span>Id (kebab-case, univoco nel mondo)</span>
+              <input
+                type="text"
+                value={draft.id}
+                onChange={(e) => patch({ id: e.target.value })}
+              />
+            </label>
+            <label className={styles.field}>
+              <span>Titolo</span>
+              <input
+                type="text"
+                value={draft.title}
+                onChange={(e) => patch({ title: e.target.value })}
+              />
+            </label>
+            <label className={styles.field}>
+              <span>Eroe — orientamento</span>
+              <select
+                value={draft.hero.facing}
+                onChange={(e) =>
+                  patch({
+                    hero: { ...draft.hero, facing: e.target.value as Facing },
+                  })
+                }
+              >
+                {FACINGS.map((f) => (
+                  <option key={f} value={f}>
+                    {FACING_LABEL[f]}
+                  </option>
+                ))}
+              </select>
+            </label>
+            <label className={styles.field}>
+              <span>Eroe — punti vita</span>
+              <input
+                type="number"
+                min={1}
+                max={MAX_HP}
+                value={draft.hero.hp}
+                onChange={(e) =>
+                  patch({
+                    hero: {
+                      ...draft.hero,
+                      hp: Math.min(MAX_HP, Number(e.target.value) || 1),
+                    },
+                  })
+                }
+              />
+            </label>
+            <label className={styles.field}>
+              <span>Par (azioni ottimali)</span>
+              <input
+                type="number"
+                min={1}
+                value={draft.par}
+                onChange={(e) => patch({ par: Number(e.target.value) || 1 })}
+              />
+            </label>
+            <label className={styles.field}>
+              <span>maxSteps (opzionale)</span>
+              <input
+                type="number"
+                min={1}
+                value={draft.maxSteps ?? ''}
+                placeholder="default 500"
+                onChange={(e) =>
+                  patch({
+                    maxSteps: e.target.value ? Number(e.target.value) : null,
+                  })
+                }
+              />
+            </label>
+          </div>
+        </section>
+
+        <section className={styles.panel}>
+          <div className={styles.panelHead}>
+            <Heading as="h2" className={styles.panelTitle}>
+              Vittoria
+            </Heading>
+            <button
+              type="button"
+              className={styles.addBtn}
+              onClick={() => patch({ win: [...draft.win, { type: 'reach' }] })}
+            >
+              <FontAwesomeIcon icon={faPlus} /> Condizione
+            </button>
+          </div>
+          {draft.win.map((cond, i) => (
+            <div key={i} className={styles.row}>
+              <select
+                value={cond.type}
+                onChange={(e) => {
+                  const type = e.target.value as WinCond['type'];
+                  const next: WinCond =
+                    type === 'reach'
+                      ? { type: 'reach' }
+                      : type === 'collect'
+                        ? { type: 'collect', kind: 'gem', qty: 1 }
+                        : { type: 'defeat' };
+                  patch({ win: replaceAt(draft.win, i, next) });
+                }}
+              >
+                {WIN_TYPES.map((t) => (
+                  <option key={t} value={t}>
+                    {t === 'reach'
+                      ? 'raggiungi bandiera'
+                      : t === 'collect'
+                        ? 'raccogli'
+                        : 'sconfiggi'}
+                  </option>
+                ))}
+              </select>
+              {cond.type === 'collect' && (
+                <>
+                  <select
+                    value={cond.kind}
+                    onChange={(e) =>
+                      patch({
+                        win: replaceAt(draft.win, i, {
+                          ...cond,
+                          kind: e.target.value,
+                        }),
+                      })
+                    }
+                  >
+                    {RESOURCE_KINDS.map((k) => (
+                      <option key={k} value={k}>
+                        {k}
+                      </option>
+                    ))}
+                  </select>
+                  <input
+                    type="number"
+                    min={1}
+                    value={cond.qty}
+                    className={styles.numSmall}
+                    onChange={(e) =>
+                      patch({
+                        win: replaceAt(draft.win, i, {
+                          ...cond,
+                          qty: Number(e.target.value) || 1,
+                        }),
+                      })
+                    }
+                  />
+                </>
+              )}
+              {cond.type === 'defeat' && (
+                <>
+                  <select
+                    value={cond.kind ?? ''}
+                    onChange={(e) =>
+                      patch({
+                        win: replaceAt(draft.win, i, {
+                          ...cond,
+                          kind: e.target.value || undefined,
+                        }),
+                      })
+                    }
+                  >
+                    <option value="">qualsiasi tipo</option>
+                    {ENEMY_KINDS.map((k) => (
+                      <option key={k} value={k}>
+                        {k}
+                      </option>
+                    ))}
+                  </select>
+                  <input
+                    type="number"
+                    min={1}
+                    value={cond.count ?? ''}
+                    placeholder="tutti"
+                    className={styles.numSmall}
+                    onChange={(e) =>
+                      patch({
+                        win: replaceAt(draft.win, i, {
+                          ...cond,
+                          count: e.target.value
+                            ? Number(e.target.value)
+                            : undefined,
+                        }),
+                      })
+                    }
+                  />
+                </>
+              )}
+              <button
+                type="button"
+                className={styles.iconBtn}
+                aria-label="Rimuovi condizione"
+                onClick={() => patch({ win: removeAt(draft.win, i) })}
+              >
+                <FontAwesomeIcon icon={faTrash} />
+              </button>
+            </div>
+          ))}
+        </section>
+
+        {draft.enemies.length > 0 && (
+          <section className={styles.panel}>
+            <Heading as="h2" className={styles.panelTitle}>
+              Nemici
+            </Heading>
+            {draft.enemies.map((e, i) => (
+              <div key={e.id} className={styles.row}>
+                <span className={styles.rowId}>
+                  {e.id} ({e.x},{e.y})
+                </span>
+                <select
+                  value={e.kind}
+                  onChange={(ev) =>
+                    patch({
+                      enemies: replaceAt(draft.enemies, i, {
+                        ...e,
+                        kind: ev.target.value,
+                      }),
+                    })
+                  }
+                >
+                  {ENEMY_KINDS.map((k) => (
+                    <option key={k} value={k}>
+                      {k}
+                    </option>
+                  ))}
+                </select>
+                <input
+                  type="number"
+                  min={1}
+                  max={MAX_HP}
+                  value={e.hp}
+                  className={styles.numSmall}
+                  aria-label="Punti vita nemico"
+                  onChange={(ev) =>
+                    patch({
+                      enemies: replaceAt(draft.enemies, i, {
+                        ...e,
+                        hp: Math.min(MAX_HP, Number(ev.target.value) || 1),
+                      }),
+                    })
+                  }
+                />
+                <select
+                  value={e.behavior}
+                  onChange={(ev) =>
+                    patch({
+                      enemies: replaceAt(draft.enemies, i, {
+                        ...e,
+                        behavior: ev.target.value as EnemyBehavior,
+                      }),
+                    })
+                  }
+                >
+                  {BEHAVIORS.map((b) => (
+                    <option key={b} value={b}>
+                      {b}
+                    </option>
+                  ))}
+                </select>
+                <button
+                  type="button"
+                  className={styles.iconBtn}
+                  aria-label="Rimuovi nemico"
+                  onClick={() => patch({ enemies: removeAt(draft.enemies, i) })}
+                >
+                  <FontAwesomeIcon icon={faTrash} />
+                </button>
+              </div>
+            ))}
+          </section>
+        )}
+
+        {draft.resources.length > 0 && (
+          <section className={styles.panel}>
+            <Heading as="h2" className={styles.panelTitle}>
+              Risorse
+            </Heading>
+            {draft.resources.map((r, i) => (
+              <div key={r.id} className={styles.row}>
+                <span className={styles.rowId}>
+                  {r.id} ({r.x},{r.y})
+                </span>
+                <select
+                  value={r.kind}
+                  onChange={(ev) =>
+                    patch({
+                      resources: replaceAt(draft.resources, i, {
+                        ...r,
+                        kind: ev.target.value,
+                      }),
+                    })
+                  }
+                >
+                  {RESOURCE_KINDS.map((k) => (
+                    <option key={k} value={k}>
+                      {k}
+                    </option>
+                  ))}
+                </select>
+                <button
+                  type="button"
+                  className={styles.iconBtn}
+                  aria-label="Rimuovi risorsa"
+                  onClick={() =>
+                    patch({ resources: removeAt(draft.resources, i) })
+                  }
+                >
+                  <FontAwesomeIcon icon={faTrash} />
+                </button>
+              </div>
+            ))}
+          </section>
+        )}
+
+        <section className={styles.panel}>
+          <div className={styles.panelHead}>
+            <Heading as="h2" className={styles.panelTitle}>
+              Suggerimenti (1–3)
+            </Heading>
+            {draft.hints.length < 3 && (
+              <button
+                type="button"
+                className={styles.addBtn}
+                onClick={() => patch({ hints: [...draft.hints, ''] })}
+              >
+                <FontAwesomeIcon icon={faPlus} /> Suggerimento
+              </button>
+            )}
+          </div>
+          {draft.hints.map((h, i) => (
+            <div key={i} className={styles.row}>
+              <input
+                type="text"
+                className={styles.grow}
+                value={h}
+                aria-label={`Suggerimento ${i + 1}`}
+                onChange={(e) =>
+                  patch({ hints: replaceAt(draft.hints, i, e.target.value) })
+                }
+              />
+              {draft.hints.length > 1 && (
+                <button
+                  type="button"
+                  className={styles.iconBtn}
+                  aria-label="Rimuovi suggerimento"
+                  onClick={() => patch({ hints: removeAt(draft.hints, i) })}
+                >
+                  <FontAwesomeIcon icon={faTrash} />
+                </button>
+              )}
+            </div>
+          ))}
+        </section>
+
+        <section className={styles.panel}>
+          <Heading as="h2" className={styles.panelTitle}>
+            Codice iniziale
+          </Heading>
+          <textarea
+            className={styles.code}
+            rows={6}
+            value={draft.starterCode}
+            spellCheck={false}
+            onChange={(e) => patch({ starterCode: e.target.value })}
+          />
+          <Heading as="h2" className={styles.panelTitle}>
+            Soluzione (opzionale, per calibrare il par)
+          </Heading>
+          <textarea
+            className={styles.code}
+            rows={6}
+            value={draft.solution}
+            spellCheck={false}
+            onChange={(e) => patch({ solution: e.target.value })}
+          />
+        </section>
+
+        <section className={styles.panel}>
+          <div className={styles.panelHead}>
+            <Heading as="h2" className={styles.panelTitle}>
+              Esporta JSON
+            </Heading>
+            <button
+              type="button"
+              className={styles.addBtn}
+              onClick={handleCopy}
+            >
+              <FontAwesomeIcon icon={faCopy} /> {copied ? 'Copiato!' : 'Copia'}
+            </button>
+          </div>
+          <p className={styles.hint}>
+            Incolla questo oggetto in <code>levels</code> dentro
+            <code> static/pyquest/&lt;mondo&gt;/world.json</code>.
+          </p>
+          <textarea
+            className={styles.code}
+            rows={10}
+            value={exportJson}
+            readOnly
+            spellCheck={false}
+            aria-label="JSON esportato"
+          />
+
+          <div className={styles.panelHead}>
+            <Heading as="h2" className={styles.panelTitle}>
+              Importa JSON
+            </Heading>
+            <button
+              type="button"
+              className={styles.addBtn}
+              onClick={handleImport}
+            >
+              <FontAwesomeIcon icon={faFileImport} /> Importa
+            </button>
+          </div>
+          {importError && <p className={styles.importError}>{importError}</p>}
+          <textarea
+            className={styles.code}
+            rows={6}
+            value={importText}
+            spellCheck={false}
+            placeholder="Incolla qui il JSON di un livello per ricaricarlo nell’editor…"
+            aria-label="JSON da importare"
+            onChange={(e) => setImportText(e.target.value)}
+          />
+        </section>
+      </div>
+    </div>
+  );
+}
+
+export default function LevelEditorPage(): JSX.Element {
+  return (
+    <Layout
+      title="Editor livelli PyQuest"
+      description="Strumento d’autore per disegnare i livelli di PyQuest."
+    >
+      <Head>
+        <meta name="robots" content="noindex, nofollow" />
+      </Head>
+      <main className={styles.page}>
+        <div className={styles.header}>
+          <Heading as="h1">
+            <FontAwesomeIcon icon={faPenRuler} className={styles.headerIcon} />{' '}
+            Editor livelli PyQuest
+          </Heading>
+          <p>
+            Strumento interno d’autore. Disegna la mappa, riempi i metadati,
+            provala nell’anteprima e incolla il JSON in un{' '}
+            <code>world.json</code>.
+          </p>
+        </div>
+        <BrowserOnly
+          fallback={<div className={styles.loading}>Caricamento…</div>}
+        >
+          {() => <LevelEditorInner />}
+        </BrowserOnly>
+      </main>
+    </Layout>
+  );
+}

From ae05eb8fddb6a9b6b3c94f1de65ec26bba51dce2 Mon Sep 17 00:00:00 2001
From: Marco Farina <marco.farina@jcmaxwell.it>
Date: Mon, 6 Jul 2026 18:10:46 +0200
Subject: [PATCH 09/11] feat(pyquest): galleria /pyquest con progressione e
 livello successivo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Aggiunge la pagina galleria (src/pages/pyquest/) con lucchetti sui livelli
non ancora sbloccati e stelle per livello, più /pyquest/gioca che dopo la
vittoria propone la navigazione al livello successivo tramite la nuova prop
onWin di PyQuest (callback a fine animazione, dopo il salvataggio del
progresso).

Rinomina e ribilancia i livelli del mondo pilota mondo-01 (nomi definitivi,
nuovo livello sul for/range, ordine gemma-poi-bug nel duello) e allinea la
pagina di collaudo pyquest-test.mdx alle nuove soluzioni/hint. Aggiunge la
voce di navbar «PyQuest». Rimuove game.py/grid.py (libreria canvas non più
usata) e i relativi riferimenti in brython_runner.py.
---
 docs/pyquest-test.mdx               |  62 ++++---
 docusaurus.config.ts                |   5 +
 src/components/PyQuest/index.tsx    |  14 ++
 src/pages/legale/privacy-policy.mdx |   4 +-
 src/pages/pyquest/gioca.module.css  | 151 ++++++++++++++++
 src/pages/pyquest/gioca.tsx         | 149 ++++++++++++++++
 src/pages/pyquest/index.tsx         | 190 ++++++++++++++++++++
 src/pages/pyquest/styles.module.css | 242 +++++++++++++++++++++++++
 static/bry-libs/brython_runner.py   |   3 -
 static/bry-libs/game.py             |  84 ---------
 static/bry-libs/grid.py             | 265 ----------------------------
 static/pyquest/mondo-01/world.json  | 110 ++++++++----
 12 files changed, 860 insertions(+), 419 deletions(-)
 create mode 100644 src/pages/pyquest/gioca.module.css
 create mode 100644 src/pages/pyquest/gioca.tsx
 create mode 100644 src/pages/pyquest/index.tsx
 create mode 100644 src/pages/pyquest/styles.module.css
 delete mode 100644 static/bry-libs/game.py
 delete mode 100644 static/bry-libs/grid.py

diff --git a/docs/pyquest-test.mdx b/docs/pyquest-test.mdx
index dc3cf3e..144c174 100644
--- a/docs/pyquest-test.mdx
+++ b/docs/pyquest-test.mdx
@@ -6,43 +6,44 @@ description: Harness di verifica del motore + renderer PyQuest (mini-giochi a gr
 
 # PyQuest — sandbox di test
 
-Pagina temporanea per validare **motore + renderer + player** di PyQuest (fasi
-1–2). Non è linkata dalla sidebar (`unlisted: true`): la raggiungi solo via URL
-`/docs/pyquest-test`. Il componente è ora giocabile end-to-end: editor + Esegui +
-board animata passo per passo.
+Pagina temporanea per validare **motore + renderer + player** di PyQuest. Non è
+linkata dalla sidebar (`unlisted: true`): la raggiungi solo via URL
+`/docs/pyquest-test`. Il componente è giocabile end-to-end: editor + Esegui +
+board animata passo per passo. I livelli qui sono quelli del mondo pilota
+`mondo-01`; la galleria vera vive su `/pyquest`.
 
 ## 1. Livello dal plugin dati (world/level)
 
-Livello `muoviti` del mondo `mondo-01` (livelli provvisori di collaudo),
-risolto dai global data del plugin `pyquest`. Il codice iniziale porta Byte
-sulla bandiera: premi Esegui e guarda l'animazione.
+Livello `primo-passo` del mondo `mondo-01`, risolto dai global data del plugin
+`pyquest`. Il codice iniziale manda Byte dritto contro il muro di destra: aggiungi
+`turn_right()` e due `move()` per raggiungere la bandiera.
 
-<PyQuest world="mondo-01" level="muoviti" />
+<PyQuest world="mondo-01" level="primo-passo" />
 
 ## 2. Navigazione con i sensori
 
-Livello `attorno-al-muro`: c'è un blocco centrale da aggirare (più una gemma come
-scenografia). Prova a far arrivare Byte in basso a destra con un ciclo
-`while not on_goal()`.
+Livello `svolta-al-buio`: un corridoio a L. Fai arrivare Byte sulla bandiera con
+un ciclo `while not on_goal()` che gira quando `is_blocked()`.
 
-<PyQuest world="mondo-01" level="attorno-al-muro" />
+<PyQuest world="mondo-01" level="svolta-al-buio" />
 
-## 2-bis. Combat, raccolta, hint e stelle (fase 3)
+## 2-bis. Combat, raccolta, hint e stelle
 
-Livello `duello`: un bug **melee** ti viene incontro. Colpiscilo con `attack()`
-(ha 2 PV), poi raccogli la gemma con `collect()`. La vittoria richiede *sia*
-sconfiggere il bug *sia* raccogliere la gemma (`win` multipla). Alla vittoria
-compaiono le stelle (da `par`); i suggerimenti si rivelano a scaglioni sotto
-l'editor; «Spiegamelo facile» copia il prompt negli appunti.
+Livello `il-tesoro-e-la-guardia`: un bug **melee** ti viene incontro. Raccogli
+prima la gemma con `collect()`, poi colpiscilo con `attack()` (ha 2 PV). La
+vittoria richiede *sia* raccogliere la gemma *sia* sconfiggere il bug (`win`
+multipla). Alla vittoria compaiono le stelle (da `par`); i suggerimenti si
+rivelano a scaglioni sotto l'editor; «Spiegamelo facile» copia il prompt negli
+appunti.
 
-<PyQuest world="mondo-01" level="duello" />
+<PyQuest world="mondo-01" level="il-tesoro-e-la-guardia" />
 
 ## 3. Indipendenza tra istanze
 
 Due istanze dello stesso livello sulla stessa pagina: devono avere trace e player
 indipendenti (esegui l'una, l'altra resta ferma).
 
-<PyQuest world="mondo-01" level="muoviti" />
+<PyQuest world="mondo-01" level="primo-passo" />
 
 ## 4. Id ignoto
 
@@ -51,11 +52,11 @@ pannello d'errore esplicito.
 
 <PyQuest world="mondo-01" level="non-esiste" />
 
-## Note per la verifica (checklist step 10-12)
+## Note per la verifica (checklist finale)
 
-- **a)** Esegui il livello 1: attesi `move, move, turn, move, move`, poi
-  autoplay da passo 0 e — a fine animazione — il pannello di vittoria con il
-  flavor text di Byte.
+- **a)** Livello 1 (`primo-passo`): scrivi la soluzione `move, move, move,
+  turn_right, move, move` → autoplay da passo 0 e, a fine animazione, il pannello
+  di vittoria col flavor text di Byte e 3 stelle (6 azioni, par 6).
 - **b)** Un errore nel codice (es. `boom` a riga 2) → trace parziale animata,
   poi pannello «C'è un errore nel codice» col traceback (riga giusta).
 - **c)** `while True: move()` → pannello step limit nel tono di Byte; il
@@ -64,17 +65,20 @@ pannello d'errore esplicito.
   velocità (0,5× 1× 2× 4×) scalano anche la durata delle transizioni.
 - **e)** `print()` interleaved compaiono in console solo quando l'animazione
   raggiunge il passo in cui sono stati emessi.
-- **f)** Sbattere più volte contro il blocco centrale del livello 2 senza
-  vincere → flavor «bump ripetuto».
+- **f)** Livello 1: scrivi cinque `move()` di fila → Byte arriva al muro e ci
+  sbatte due volte senza vincere → flavor «bump ripetuto».
 - **g)** Dark mode: board, sprite, stelle e pannelli esito leggibili in entrambi
   i temi; la griglia scala col contenitore (`--pq-cell`).
-- **h)** Livello `duello` (fase 3): il bug melee si avvicina a ogni azione; due
-  `attack()` lo sconfiggono; `collect()` raccoglie la gemma; con la soluzione la
+- **h)** Livello `il-tesoro-e-la-guardia`: il bug melee si avvicina a ogni
+  azione; con la soluzione (`move, move, collect, move, attack, attack`) la
   vittoria arriva a `par` azioni → 3 stelle. La trace è **identica** su run
   ripetuti. Ricaricando la pagina, il livello risulta «Completato · record N».
 - **i)** Morte dell'eroe (es. resta fermo accanto a un nemico che lo colpisce
   fino a 0 PV): UI di sconfitta (non pannello errore); traceback breve in
-  console. `while True: move()` → step limit nel tono di Byte.
+  console.
 - **j)** Suggerimenti: si rivelano uno alla volta (1/3 → 2/3 → 3/3) e non
   persistono al reload. «Spiegamelo facile» copia un prompt con codice + titolo
   del livello.
+- **k)** Galleria `/pyquest`: lucchetti che si aprono al completamento, stelle
+  per livello, e da `/pyquest/gioca` la navigazione «Livello successivo» dopo la
+  vittoria.
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 05404a5..6bb467e 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -256,6 +256,11 @@ export default async function createConfig(): Promise<Config> {
               },
             ],
           },
+          {
+            to: '/pyquest',
+            label: 'PyQuest',
+            position: 'left',
+          },
           /*        {
                     to: '/blog',
                     label: 'Blog',
diff --git a/src/components/PyQuest/index.tsx b/src/components/PyQuest/index.tsx
index e9979b8..f16cea2 100644
--- a/src/components/PyQuest/index.tsx
+++ b/src/components/PyQuest/index.tsx
@@ -53,6 +53,12 @@ export interface PyQuestProps {
   character?: string;
   /** Titolo mostrato nella toolbar (override del titolo del livello). */
   title?: string;
+  /**
+   * Notifica una vittoria a fine animazione (la galleria vi aggancia la
+   * navigazione al livello successivo). Il progresso è già stato salvato quando
+   * scatta. Passa una callback stabile (useCallback) per evitare rifiri.
+   */
+  onWin?: (result: { steps: number; stars: number; isRecord: boolean }) => void;
 }
 
 interface PyRunnerGlobalData {
@@ -312,6 +318,14 @@ function PyQuestInner(props: PyQuestProps) {
     }
   }, []);
 
+  // Vittoria conclusa: segnala al genitore (la galleria sblocca il «prossimo»).
+  const { onWin } = props;
+  useEffect(() => {
+    if (phase !== 'finished' || outcome !== 'won' || !level || !onWin) return;
+    const steps = countActions(events);
+    onWin({ steps, stars: starsFor(steps, level.par), isRecord });
+  }, [phase, outcome, level, events, isRecord, onWin]);
+
   if (!libUrl) {
     return (
       <ErrorBox>
diff --git a/src/pages/legale/privacy-policy.mdx b/src/pages/legale/privacy-policy.mdx
index 5c4496c..50d5f77 100644
--- a/src/pages/legale/privacy-policy.mdx
+++ b/src/pages/legale/privacy-policy.mdx
@@ -112,9 +112,7 @@ Le richieste possono essere inviate all'indirizzo [marco@rainbowbits.cloud](mail
 
 La presente informativa potrà essere aggiornata; le eventuali modifiche saranno pubblicate su questa pagina con indicazione della data di ultimo aggiornamento.
 
-<GeekSignoff icon="ring">
-  Tienilo segreto. Tienilo al sicuro.
-</GeekSignoff>
+<GeekSignoff icon="ring">Tienilo segreto. Tienilo al sicuro.</GeekSignoff>
 
 ---
 
diff --git a/src/pages/pyquest/gioca.module.css b/src/pages/pyquest/gioca.module.css
new file mode 100644
index 0000000..fe63fd2
--- /dev/null
+++ b/src/pages/pyquest/gioca.module.css
@@ -0,0 +1,151 @@
+/* Pagina di gioco PyQuest (/pyquest/gioca): topbar con breadcrumb + titolo,
+   la scena giocabile centrata, e la barra di vittoria con «livello successivo».
+   Token globali; niente bordo-sinistra colorato. */
+
+.page {
+  min-height: calc(100vh - var(--ifm-navbar-height));
+  background: var(--at-bg-base, var(--ifm-background-color));
+}
+
+.game {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 1rem 1rem 3rem;
+}
+
+/* --- Topbar --------------------------------------------------------------- */
+
+.topbar {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  flex-wrap: wrap;
+  padding: 0.5rem 0 1rem;
+  border-bottom: 1px solid var(--at-border, rgba(0, 0, 0, 0.08));
+  margin-bottom: 1.25rem;
+}
+
+.crumb {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 12px;
+  border-radius: var(--radius-pill, 999px);
+  border: 1px solid var(--at-border, rgba(0, 0, 0, 0.12));
+  color: inherit;
+  font-size: 0.86rem;
+  font-weight: 600;
+  text-decoration: none;
+  transition:
+    background var(--dur-fast, 140ms) var(--ease-smooth, ease),
+    border-color var(--dur-fast, 140ms) var(--ease-smooth, ease);
+}
+
+.crumb:hover {
+  text-decoration: none;
+  background: var(--at-bg-subtle, rgba(0, 0, 0, 0.04));
+  border-color: color-mix(in srgb, var(--ifm-color-primary) 35%, transparent);
+}
+
+.topbarTitle {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.worldName {
+  font-size: 0.8rem;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  opacity: 0.65;
+  font-weight: 700;
+}
+
+.levelName {
+  font-size: 1.1rem;
+  font-weight: 600;
+}
+
+/* --- Scena ---------------------------------------------------------------- */
+
+.stage {
+  min-width: 0;
+}
+
+/* --- Barra di vittoria ---------------------------------------------------- */
+
+.winBar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: 1rem;
+  margin-top: 1rem;
+  padding: 14px 18px;
+  border-radius: var(--radius-md, 14px);
+  background: color-mix(in srgb, #2f9e44 12%, transparent);
+  border: 1px solid color-mix(in srgb, #2f9e44 32%, transparent);
+}
+
+.winMsg {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  font-weight: 600;
+}
+
+.nextBtn {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 9px 18px;
+  border-radius: var(--radius-pill, 999px);
+  border: 1px solid transparent;
+  background: var(--ifm-color-primary);
+  color: #fff;
+  font: inherit;
+  font-weight: 700;
+  cursor: pointer;
+  text-decoration: none;
+  transition:
+    filter var(--dur-fast, 140ms) var(--ease-smooth, ease),
+    transform var(--dur-fast, 140ms) var(--ease-smooth, ease);
+}
+
+.nextBtn:hover {
+  text-decoration: none;
+  color: #fff;
+  filter: brightness(1.08);
+}
+
+.nextBtn:active {
+  transform: scale(0.98);
+}
+
+/* --- Non trovato ---------------------------------------------------------- */
+
+.notFound {
+  max-width: 560px;
+  margin: 3rem auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+.backBtn {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  margin-top: 1rem;
+  padding: 9px 18px;
+  border-radius: var(--radius-pill, 999px);
+  background: var(--ifm-color-primary);
+  color: #fff;
+  font-weight: 700;
+  text-decoration: none;
+}
+
+.backBtn:hover {
+  text-decoration: none;
+  color: #fff;
+  filter: brightness(1.08);
+}
diff --git a/src/pages/pyquest/gioca.tsx b/src/pages/pyquest/gioca.tsx
new file mode 100644
index 0000000..e50ea32
--- /dev/null
+++ b/src/pages/pyquest/gioca.tsx
@@ -0,0 +1,149 @@
+/**
+ * Pagina di gioco PyQuest (spec step 19) — `/pyquest/gioca?world=…&level=…`.
+ *
+ * Legge mondo e livello dalla query (via `useLocation`, così reagisce alla
+ * navigazione SPA) e li valida contro i global data del plugin: un id ignoto
+ * mostra un messaggio e il link alla galleria, mai un livello di ripiego. Alla
+ * vittoria (`onWin` di PyQuest, che a quel punto ha già salvato il progresso e
+ * quindi sbloccato il seguito) compare la navigazione al livello successivo.
+ */
+
+import { useCallback, useState } from 'react';
+import Layout from '@theme/Layout';
+import Heading from '@theme/Heading';
+import Link from '@docusaurus/Link';
+import { useHistory, useLocation } from '@docusaurus/router';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import {
+  faArrowLeft,
+  faArrowRight,
+  faTrophy,
+} from '@fortawesome/free-solid-svg-icons';
+import PyQuest from '@site/src/components/PyQuest';
+import { useWorldData } from '@site/src/components/PyQuest/useWorldData';
+import styles from './gioca.module.css';
+
+function GiocaInner() {
+  const location = useLocation();
+  const history = useHistory();
+  const worlds = useWorldData();
+
+  const params = new URLSearchParams(location.search);
+  const worldId = params.get('world') ?? '';
+  const levelId = params.get('level') ?? '';
+
+  const world = worlds[worldId];
+  const idx = world ? world.levels.findIndex((l) => l.id === levelId) : -1;
+  const level = idx >= 0 ? world.levels[idx] : undefined;
+  const next =
+    world && idx >= 0 && idx < world.levels.length - 1
+      ? world.levels[idx + 1]
+      : undefined;
+
+  const [justWon, setJustWon] = useState(false);
+  // Nuovo livello (anche via «successivo»): nascondi la barra di vittoria. Reset
+  // in render (pattern «adjust state during render»), non in un effect.
+  const levelKey = `${worldId}/${levelId}`;
+  const [prevKey, setPrevKey] = useState(levelKey);
+  if (prevKey !== levelKey) {
+    setPrevKey(levelKey);
+    setJustWon(false);
+  }
+
+  const handleWin = useCallback(() => setJustWon(true), []);
+
+  const goTo = useCallback(
+    (nextLevelId: string) => {
+      history.push(
+        `/pyquest/gioca?world=${encodeURIComponent(
+          worldId,
+        )}&level=${encodeURIComponent(nextLevelId)}`,
+      );
+    },
+    [history, worldId],
+  );
+
+  if (!world || !level) {
+    return (
+      <div className={styles.notFound}>
+        <Heading as="h1">Livello non trovato</Heading>
+        <p>
+          {worldId
+            ? `Non esiste il livello «${levelId}» nel mondo «${worldId}».`
+            : 'Manca il mondo o il livello nell’indirizzo.'}
+        </p>
+        <Link className={styles.backBtn} to="/pyquest">
+          <FontAwesomeIcon icon={faArrowLeft} /> Vai alla galleria
+        </Link>
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.game}>
+      <div className={styles.topbar}>
+        <Link className={styles.crumb} to="/pyquest">
+          <FontAwesomeIcon icon={faArrowLeft} /> Tutti i livelli
+        </Link>
+        <div className={styles.topbarTitle}>
+          <span className={styles.worldName}>{world.title}</span>
+          <span className={styles.levelName}>
+            {idx + 1}/{world.levels.length} · {level.title}
+          </span>
+        </div>
+      </div>
+
+      <div className={styles.stage}>
+        {/* key: cambiando livello il componente riparte pulito (editor, trace). */}
+        <PyQuest
+          key={`${worldId}/${levelId}`}
+          world={worldId}
+          level={levelId}
+          onWin={handleWin}
+        />
+
+        {justWon && (
+          <div className={styles.winBar} role="status">
+            {next ? (
+              <>
+                <span className={styles.winMsg}>
+                  <FontAwesomeIcon icon={faTrophy} /> Livello superato!
+                </span>
+                <button
+                  type="button"
+                  className={styles.nextBtn}
+                  onClick={() => goTo(next.id)}
+                >
+                  Livello successivo <FontAwesomeIcon icon={faArrowRight} />
+                </button>
+              </>
+            ) : (
+              <>
+                <span className={styles.winMsg}>
+                  <FontAwesomeIcon icon={faTrophy} /> Mondo completato — Byte ti
+                  ringrazia in binario.
+                </span>
+                <Link className={styles.nextBtn} to="/pyquest">
+                  Torna alla galleria
+                </Link>
+              </>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default function PyQuestPlay(): JSX.Element {
+  return (
+    <Layout
+      title="PyQuest — gioca"
+      description="Gioca un livello di PyQuest: scrivi Python e guarda Byte eseguirlo sulla griglia."
+    >
+      <main className={styles.page}>
+        <GiocaInner />
+      </main>
+    </Layout>
+  );
+}
diff --git a/src/pages/pyquest/index.tsx b/src/pages/pyquest/index.tsx
new file mode 100644
index 0000000..9875ec6
--- /dev/null
+++ b/src/pages/pyquest/index.tsx
@@ -0,0 +1,190 @@
+/**
+ * Galleria PyQuest (spec step 19) — `/pyquest`.
+ *
+ * Elenca i mondi validati a build time dal plugin `pyquest` e, per ciascuno, i
+ * livelli con lucchetti (sblocco calcolato da `useProgress`, spec D10), stelle
+ * guadagnate (spec D11) e link alla pagina di gioco full-height `/pyquest/gioca`.
+ *
+ * Nessun `BrowserOnly`: `useProgress` parte da EMPTY sia sul server sia al primo
+ * render client (allinea lo storage in un effect), quindi l'hydration combacia e
+ * i lucchetti «si aprono» subito dopo. Le card e gli sprite sono SSR-safe.
+ */
+
+import Layout from '@theme/Layout';
+import Heading from '@theme/Heading';
+import Link from '@docusaurus/Link';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import {
+  faStar,
+  faLock,
+  faPlay,
+  faFlagCheckered,
+} from '@fortawesome/free-solid-svg-icons';
+import { faStar as faStarOutline } from '@fortawesome/free-regular-svg-icons';
+import clsx from 'clsx';
+import { useWorldData } from '@site/src/components/PyQuest/useWorldData';
+import {
+  useProgress,
+  starsFor,
+} from '@site/src/components/PyQuest/useProgress';
+import { characterDef } from '@site/src/components/PyQuest/characters';
+import type { LevelDef, WorldDef } from '@site/src/components/PyQuest/types';
+import styles from './styles.module.css';
+
+/** Riga di 3 stelle, piene fino a `n` (spec D11); `n = 0` = tutte vuote. */
+function Stars({ n }: { n: number }) {
+  return (
+    <span
+      className={styles.stars}
+      aria-label={n === 0 ? 'nessuna stella' : `${n} stelle su 3`}
+    >
+      {[1, 2, 3].map((i) => (
+        <FontAwesomeIcon
+          key={i}
+          icon={i <= n ? faStar : faStarOutline}
+          className={clsx(styles.star, i <= n && styles.starOn)}
+        />
+      ))}
+    </span>
+  );
+}
+
+function LevelRow({
+  world,
+  level,
+  index,
+}: {
+  world: WorldDef;
+  level: LevelDef;
+  index: number;
+}) {
+  const { getLevel, isUnlocked } = useProgress();
+  const saved = getLevel(world.id, level.id);
+  const unlocked = isUnlocked(world, level.id);
+  const stars = saved?.done ? starsFor(saved.bestSteps, level.par) : 0;
+
+  const meta = (
+    <>
+      <span className={styles.levelNum} aria-hidden="true">
+        {index + 1}
+      </span>
+      <span className={styles.levelBody}>
+        <span className={styles.levelTitle}>{level.title}</span>
+        <span className={styles.levelSub}>
+          {saved?.done
+            ? `Completato · record ${saved.bestSteps} · par ${level.par}`
+            : unlocked
+              ? `Da giocare · par ${level.par}`
+              : 'Completa il livello precedente per sbloccarlo'}
+        </span>
+      </span>
+    </>
+  );
+
+  if (!unlocked) {
+    return (
+      <div
+        className={clsx(styles.level, styles.levelLocked)}
+        aria-disabled="true"
+      >
+        {meta}
+        <FontAwesomeIcon icon={faLock} className={styles.levelIcon} />
+      </div>
+    );
+  }
+
+  return (
+    <Link
+      className={clsx(styles.level, saved?.done && styles.levelDone)}
+      to={`/pyquest/gioca?world=${encodeURIComponent(
+        world.id,
+      )}&level=${encodeURIComponent(level.id)}`}
+    >
+      {meta}
+      {saved?.done ? (
+        <Stars n={stars} />
+      ) : (
+        <FontAwesomeIcon icon={faPlay} className={styles.levelIcon} />
+      )}
+    </Link>
+  );
+}
+
+function WorldCard({ world }: { world: WorldDef }) {
+  const { getLevel } = useProgress();
+  const char = characterDef(world.character);
+  const done = world.levels.filter(
+    (l) => getLevel(world.id, l.id)?.done,
+  ).length;
+  const total = world.levels.length;
+
+  return (
+    <section className={styles.card}>
+      <header className={styles.cardHead}>
+        <div className={styles.avatar} aria-hidden="true">
+          {char.sprite}
+        </div>
+        <div className={styles.cardHeadText}>
+          <Heading as="h2" className={styles.cardTitle}>
+            {world.title}
+          </Heading>
+          <p className={styles.cardDesc}>{world.description}</p>
+          <div className={styles.progress}>
+            <FontAwesomeIcon icon={faFlagCheckered} aria-hidden="true" />
+            <span>
+              {done} / {total} completati
+            </span>
+            <span className={styles.progressChar}>· con {char.name}</span>
+          </div>
+        </div>
+      </header>
+
+      <ol className={styles.levels}>
+        {world.levels.map((level, i) => (
+          <li key={level.id}>
+            <LevelRow world={world} level={level} index={i} />
+          </li>
+        ))}
+      </ol>
+    </section>
+  );
+}
+
+export default function PyQuestGallery(): JSX.Element {
+  const worlds = useWorldData();
+  const list = Object.values(worlds);
+
+  return (
+    <Layout
+      title="PyQuest"
+      description="Impara Python facendo muovere Byte il droide su una griglia: mini-missioni con codice vero, eseguito nel browser."
+    >
+      <main className={styles.page}>
+        <div className={styles.header}>
+          <Heading as="h1" className={styles.h1}>
+            PyQuest
+          </Heading>
+          <p className={styles.lead}>
+            Scrivi Python vero e guarda Byte il droide eseguirlo — esattamente
+            come lo hai scritto. Ogni missione ti insegna un pezzo del
+            linguaggio: muoverti, ripetere, decidere e cavartela quando le cose
+            si mettono male. Completa un livello per sbloccare il prossimo.
+          </p>
+        </div>
+
+        {list.length === 0 ? (
+          <p className={styles.empty}>
+            Nessun mondo disponibile: controlla che <code>static/pyquest/</code>{' '}
+            contenga almeno un <code>world.json</code>.
+          </p>
+        ) : (
+          <div className={styles.grid}>
+            {list.map((world) => (
+              <WorldCard key={world.id} world={world} />
+            ))}
+          </div>
+        )}
+      </main>
+    </Layout>
+  );
+}
diff --git a/src/pages/pyquest/styles.module.css b/src/pages/pyquest/styles.module.css
new file mode 100644
index 0000000..4e9e25e
--- /dev/null
+++ b/src/pages/pyquest/styles.module.css
@@ -0,0 +1,242 @@
+/* Galleria PyQuest (/pyquest): card mondo con avatar del personaggio, progresso
+   e lista livelli con lucchetti/stelle. Token globali (--radius-*, --dur-*,
+   --ease-*); niente bordo-sinistra colorato. */
+
+.page {
+  max-width: 900px;
+  margin: 0 auto;
+  padding: 2.5rem 1rem 4rem;
+}
+
+.header {
+  margin-bottom: 2rem;
+}
+
+.h1 {
+  font-size: clamp(2rem, 5vw, 3rem);
+  margin-bottom: 0.75rem;
+}
+
+.lead {
+  font-size: 1.05rem;
+  line-height: 1.6;
+  max-width: 62ch;
+  opacity: 0.9;
+}
+
+.empty {
+  padding: 1.25rem;
+  border-radius: var(--radius-sm, 10px);
+  background: var(--at-bg-subtle, rgba(0, 0, 0, 0.03));
+}
+
+.grid {
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+/* --- Card mondo ----------------------------------------------------------- */
+
+.card {
+  border: 1px solid var(--at-border, rgba(0, 0, 0, 0.08));
+  border-radius: var(--radius-lg, 18px);
+  padding: 1.5rem;
+  background: var(
+    --ifm-card-background-color,
+    var(--ifm-background-surface-color)
+  );
+  box-shadow: var(--shadow-sm, 0 1px 3px rgba(0, 0, 0, 0.06));
+}
+
+.cardHead {
+  display: flex;
+  gap: 1.25rem;
+  align-items: flex-start;
+  margin-bottom: 1.25rem;
+}
+
+.avatar {
+  flex: none;
+  width: 72px;
+  height: 72px;
+  display: grid;
+  place-items: center;
+  padding: 8px;
+  border-radius: var(--radius-md, 14px);
+  background: var(--at-bg-subtle, rgba(0, 0, 0, 0.04));
+  /* Vars dello sprite (specular a GameScene.module.css): senza queste lo sprite
+     userebbe i fallback e non seguirebbe il tema. */
+  --pq-hero: var(--at-accent, #0270ad);
+  --pq-hero-track: #3d4759;
+  --pq-hero-panel: rgba(255, 255, 255, 0.35);
+  --pq-hero-led-ring: #ffffff;
+  --pq-hero-led: #22b8cf;
+  --pq-monty: #2f9e44;
+  --pq-monty-hat: #8d6e3f;
+  --pq-monty-eye: #1a1a1a;
+}
+
+:global(html[data-theme='dark']) .avatar {
+  --pq-hero: var(--at-accent, #38bdf8);
+  --pq-hero-track: #566178;
+  --pq-hero-panel: rgba(0, 0, 0, 0.25);
+  --pq-hero-led-ring: #10131a;
+  --pq-hero-led: #3bc9db;
+  --pq-monty: #51cf66;
+  --pq-monty-hat: #a98953;
+  --pq-monty-eye: #10131a;
+}
+
+.avatar svg {
+  width: 100%;
+  height: 100%;
+}
+
+.cardHeadText {
+  min-width: 0;
+}
+
+.cardTitle {
+  margin: 0 0 0.4rem;
+  font-size: 1.5rem;
+}
+
+.cardDesc {
+  margin: 0 0 0.75rem;
+  line-height: 1.55;
+  opacity: 0.88;
+}
+
+.progress {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 0.88rem;
+  font-weight: 600;
+}
+
+.progressChar {
+  font-weight: 400;
+  opacity: 0.75;
+}
+
+/* --- Lista livelli -------------------------------------------------------- */
+
+.levels {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.level {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  padding: 12px 14px;
+  border-radius: var(--radius-sm, 10px);
+  border: 1px solid var(--at-border, rgba(0, 0, 0, 0.08));
+  background: var(--at-bg-subtle, rgba(0, 0, 0, 0.02));
+  color: inherit;
+  text-decoration: none;
+  transition:
+    background var(--dur-fast, 140ms) var(--ease-smooth, ease),
+    border-color var(--dur-fast, 140ms) var(--ease-smooth, ease),
+    transform var(--dur-fast, 140ms) var(--ease-smooth, ease);
+}
+
+a.level:hover {
+  text-decoration: none;
+  background: color-mix(in srgb, var(--ifm-color-primary) 8%, transparent);
+  border-color: color-mix(in srgb, var(--ifm-color-primary) 35%, transparent);
+  transform: translateY(-1px);
+}
+
+a.level:active {
+  transform: scale(0.99);
+}
+
+.levelDone {
+  background: color-mix(in srgb, #2f9e44 8%, transparent);
+  border-color: color-mix(in srgb, #2f9e44 28%, transparent);
+}
+
+.levelLocked {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.levelNum {
+  flex: none;
+  width: 30px;
+  height: 30px;
+  display: grid;
+  place-items: center;
+  border-radius: var(--radius-circle, 50%);
+  background: color-mix(in srgb, var(--ifm-color-primary) 14%, transparent);
+  color: var(--ifm-color-primary);
+  font-weight: 700;
+  font-size: 0.9rem;
+}
+
+.levelLocked .levelNum {
+  background: var(--at-border, rgba(0, 0, 0, 0.1));
+  color: inherit;
+}
+
+.levelBody {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+  flex: 1;
+}
+
+.levelTitle {
+  font-weight: 600;
+}
+
+.levelSub {
+  font-size: 0.82rem;
+  opacity: 0.75;
+}
+
+.levelIcon {
+  flex: none;
+  opacity: 0.6;
+}
+
+/* --- Stelle (spec D11) ---------------------------------------------------- */
+
+.stars {
+  display: inline-flex;
+  gap: 3px;
+  font-size: 0.95rem;
+  line-height: 1;
+}
+
+.star {
+  color: var(--at-border, rgba(0, 0, 0, 0.18));
+}
+
+.starOn {
+  color: #f0a92b;
+}
+
+:global(html[data-theme='dark']) .star {
+  color: rgba(255, 255, 255, 0.22);
+}
+
+:global(html[data-theme='dark']) .starOn {
+  color: #ffca4b;
+}
+
+@media (max-width: 600px) {
+  .cardHead {
+    flex-direction: column;
+    gap: 1rem;
+  }
+}
diff --git a/static/bry-libs/brython_runner.py b/static/bry-libs/brython_runner.py
index 2d94aae..07964fe 100644
--- a/static/bry-libs/brython_runner.py
+++ b/static/bry-libs/brython_runner.py
@@ -9,9 +9,6 @@
 log_line_number_shift = 0
 
 TURTLE_IMPORTS = re.compile(r'(^from turtle import)|(^import turtle)|(^from turtle3d import)|(^import turtle3d)', re.M)
-GRID_IMPORTS = re.compile(r'(^from grid import)|(^import grid)', re.M)
-GRAPHICS_OUTPUT = re.compile(r'^(SETUP_)?GRAPHICS_OUTPUT\s*=\s*(True|1)', re.M)
-CANVAS_OUTPUT = re.compile(r'^(SETUP_)?CANVAS_OUTPUT\s*=\s*(True|1)', re.M)
 TURTLE_TEMPLATE = '''from browser import document
 import turtle
 turtle.restart()
diff --git a/static/bry-libs/game.py b/static/bry-libs/game.py
deleted file mode 100644
index ef8ab19..0000000
--- a/static/bry-libs/game.py
+++ /dev/null
@@ -1,84 +0,0 @@
-
-from browser import timer, document # type: ignore
-from config import Config           # type: ignore
-
-import time
-class Game():
-    stop_request = False
-    anim_id = None
-    timeout_id = None
-    init_time = None
-    sleep_requested: bool = False
-
-    @staticmethod
-    def reset():
-        Game.stop_request = False
-        Game.anim_id = None
-        Game.timeout_id = None
-        Game.init_time = None
-        Game.sleep_requested = False
-
-    @staticmethod
-    def sleep(ms):
-        pass
-
-    @staticmethod
-    def stop():
-        Game.stop_request = True
-        timer.clear_timeout(Game.timeout_id)
-        timer.cancel_animation_frame(Game.timeout_id)
-
-    @staticmethod
-    def is_running():
-        return not Game.stop_request and document[Config.BRYTHON_COMMUNICATOR].attrs.get('data--start-time') == Game.init_time # type: ignore
-
-def sleep(ms):
-    Game.sleep(ms)
-
-def stop():
-    Game.stop()
-
-def gameloop(func):
-    '''
-    Wrapper function for brython
-
-    ## Example
-    ```py
-    from game import gameloop, sleep, stop
-
-    @gameloop
-    def run(dt):
-        print('Time', dt)
-        if dt > 2000: # stop the game loop after 2000 ms 
-            stop()
-        sleep(100) # sleeps 100 ms
-
-    
-    run()
-    ```
-    '''
-    Game.reset()
-    t0 = time.now() # type: ignore
-    Game.init_time = document[Config.BRYTHON_COMMUNICATOR].attrs.get('data--start-time')
-        
-    def animation_frame():
-        Game.anim_id = timer.request_animation_frame(lambda t: wrap(t))
-
-    def sleep(ms):
-        Game.sleep_requested = True
-        if Game.is_running():
-            Game.timeout_id = timer.set_timeout(animation_frame, ms)
-
-    Game.sleep = sleep
-    
-    def wrap(*args, **kwargs):
-        Game.sleep_requested = False
-        if func.__code__.co_argcount > 0:
-            result = func(time.now() - t0) # type: ignore
-        else:
-            result = func()
-
-        if not Game.sleep_requested and not Game.stop_request:
-            animation_frame()
-        return Game
-    return wrap
\ No newline at end of file
diff --git a/static/bry-libs/grid.py b/static/bry-libs/grid.py
deleted file mode 100644
index 078fe04..0000000
--- a/static/bry-libs/grid.py
+++ /dev/null
@@ -1,265 +0,0 @@
-from browser import document # type: ignore
-from config import Config # type: ignore
-
-class Rectangle():
-    col: int
-    row: int
-    ctx = None
-    grid = None
-    init_draw = False
-    def __init__(self, grid, col: int, row: int, color: str = ''):
-        self.col = col
-        self.row = row
-        self.grid = grid
-        self.init_draw = False
-        try:
-            canvas = document[Config.CANVAS_ID]
-            self.ctx = canvas.getContext('2d')
-        except Exception:
-            # Niente canvas in pagina: la griglia resta solo "logica".
-            pass
-        self._color = color
-        
-    def get(self, offset_x: int, offset_y: int):
-        y = (self.row + offset_y) % len(self.grid) # type: ignore
-        x = (self.col + offset_x) % len(self.grid[y]) # type: ignore
-        return self.grid[y][x] # type: ignore
-
-    @property
-    def color(self):
-        return self._color or 'rgba(0,0,0,0)'
-
-    @color.setter
-    def color(self, color: str):
-        if color == '':
-            color = 'rgba(0,0,0,0)'
-
-        if self._color == color and self.init_draw:
-            return
-        self._color = color
-        self.init_draw = True
-        self.draw()
-
-    def draw(self):
-        scale = self.grid.scale # type: ignore
-        x = self.col * scale
-        y = self.row * scale
-        try:
-            self.ctx.clearRect(x, y, scale, scale) # type: ignore
-            self.ctx.lineWidth = 0 # type: ignore
-            self.ctx.fillStyle = self.color # type: ignore
-            self.ctx.fillRect(x, y, scale, scale) # type: ignore
-        except Exception:
-            # ctx assente (niente canvas): il draw è un no-op.
-            pass
-
-    def copy(self, grid):
-        return Rectangle(grid, self.col, self.row, self.color)
-
-    def __repr__(self):
-        return self.color
-
-class RectLine():
-    line: list = []
-    n = 0
-    max = 0
-    def __init__(self, grid, row, cols: int | list, color: str = ''):
-        self.grid = grid
-        if type(cols) == list:
-            self.line = cols # type: ignore
-        else:
-            self.line = [Rectangle(grid, col, row, color) for col in range(cols)] # type: ignore
-        self.max = len(self.line) # type: ignore
-    
-    def __getitem__(self, key):
-        return self.line[key]
-
-    def __setitem__(self, key, value):
-        self.line[key].color = value
-
-    def __repr__(self):
-        return ', '.join([f'{r.color}' for r in self.line])
-
-    def __iter__(self):
-        self.n = 0
-        return self
-
-    def __next__(self):
-        if self.n < self.max:
-            result = self[self.n]
-            self.n += 1
-            return result
-        else:
-            raise StopIteration
-    
-    def __len__(self):
-        return self.max
-
-    def draw(self):
-        for rect in self.line:
-            rect.draw()
-    
-    def copy(self, grid):
-        return RectLine(grid, self.line[0].row, [l.copy(grid) for l in self.line]) # type: ignore
-
-class Grid():
-    lines = []
-    n = 0
-    max = 0
-    CANVAS_ID = ''
-    WIDTH = 500
-    HEIGHT = 500
-    scale = 10
-    record_gif = False
-    frames = {}
-
-    def __init__(self, rows: int, cols: int, color: str = '', scale: int = -1):
-        if scale < 0:
-            if rows > 0 and cols > 0:
-                scale = min(Grid.WIDTH // cols, Grid.HEIGHT // rows)
-            else:
-                scale = 10
-        self.scale = scale
-        self.lines = [RectLine(self, row, cols, color) for row in range(rows)]
-        self.max = rows
-    
-    @staticmethod
-    def setup(width: int, height: int, record_gif: bool = False):
-        Grid.HEIGHT = height
-        Grid.WIDTH = width
-        Grid.record_gif = record_gif
-        Grid.frames = {}
-        canvas = document[Config.CANVAS_ID]
-        parent = canvas.parent
-        parent.replaceChildren()
-    
-        canv = document.createElement('canvas')
-        canv.style.display = 'block'
-        canv.id = Config.CANVAS_ID;
-        canv.attrs['height'] = height
-        canv.attrs['width'] = width
-        canv.style.width = f'{width}px'
-        canv.style.height = f'{height}px'
-        parent.appendChild(canv)
-
-    @staticmethod
-    def from_text(bin_text: str, colors={'s': 'black', '1': 'black', 'x': 'black', 'bg': ''}):
-        lines = bin_text.lower().splitlines()
-        if 'bg' not in colors:
-            colors['bg'] = ''
-        while len(lines) > 0 and len(lines[0]) == 0:
-            lines.pop(0)
-        size_y = len(lines)
-        if size_y < 1:
-            raise Exception('Grid must have at least one non empty line')
-        size_x = max(map(lambda x: len(x), lines))
-
-        scale = min(Grid.WIDTH // size_x, Grid.HEIGHT // size_y)
-        grid = Grid(0, 0, colors['bg'], scale)
-        raw_grid = []
-        for line in lines:
-            raw_line = []
-            for x in range(size_x):
-                if x < len(line):
-                    raw_line.append(Rectangle(grid, x, len(raw_grid), colors.get(line[x], colors['bg'])))
-                else:
-                    raw_line.append(Rectangle(grid, x, len(raw_grid), colors['bg']))
-            raw_grid.append(RectLine(grid, len(raw_grid), raw_line))
-        grid.set_lines(raw_grid)
-        grid.draw()
-        return grid
-        
-
-    def set_lines(self, lines):
-        self.lines = lines
-        self.max = len(lines)
-
-        
-    def to_list(self):
-        return [[c.color for c in l.line] for l in self.lines]
-
-    @property
-    def color_grid(self):
-        return self.to_list()
-
-    @property
-    def grid(self):
-        return self.to_list()
-
-    @property
-    def size(self):
-        return (self.dim_y, self.dim_x)
-
-    @property
-    def dim_x(self):
-        if self.max < 1:
-            return 0
-        return len(self[0])
-
-    @property
-    def dim_y(self):
-        return len(self.lines)
-
-    @staticmethod
-    def clear_canvas():
-        try:
-            canvas = document[Config.CANVAS_ID]
-            ctx = canvas.getContext('2d')
-            ctx.clearRect(0, 0, Grid.WIDTH, Grid.HEIGHT) # type: ignore
-        except Exception:
-            # Niente canvas in pagina: nulla da pulire.
-            pass
-
-
-    def draw(self):
-        for line in self.lines:
-            line.draw()
-
-    @staticmethod
-    def gif_add():
-        if Grid.record_gif:
-            canvas = document[Config.CANVAS_ID]
-            frameName = 'frame_' + str(len(Grid.frames)).rjust(3, '0')
-            Grid.frames[frameName] = canvas.toDataURL('image/png');
-
-
-
-    def fill(self, color: str = ''):
-        for line in self.lines:
-            for cell in line:
-                cell.color = color
-
-    def copy(self):
-        cp = Grid(0, 0)
-        lines = [l.copy(cp) for l in self.lines]
-        cp.set_lines(lines)
-        return cp
-
-
-    def __getitem__(self, key):
-        return self.lines[key]
-
-    def __setitem__(self, key, value):
-        self.lines[key] = value
-        
-    def __repr__(self):
-        rep = ''
-        for line in self.lines:
-            rep += f'{line}'
-            rep += '\n'
-        return rep
-    
-    def __iter__(self):
-        self.n = 0
-        return self
-
-    def __next__(self):
-        if self.n < self.max:
-            result = self[self.n]
-            self.n += 1
-            return result
-        else:
-            raise StopIteration
-
-    def __len__(self):
-        return self.max
\ No newline at end of file
diff --git a/static/pyquest/mondo-01/world.json b/static/pyquest/mondo-01/world.json
index b5e8e32..d88da97 100644
--- a/static/pyquest/mondo-01/world.json
+++ b/static/pyquest/mondo-01/world.json
@@ -1,75 +1,115 @@
 {
   "schemaVersion": 1,
   "id": "mondo-01",
-  "title": "Mondo di collaudo",
-  "description": "Livelli provvisori di collaudo (fase 2): saranno sostituiti dal mondo pilota definitivo allo step 18.",
+  "title": "I primi passi di Byte",
+  "description": "Cinque missioni per insegnare a Byte il droide a muoversi, ripetere, decidere e — quando serve — menare le mani. Una alla volta: ogni livello sblocca il successivo.",
   "character": "byte",
   "volume": "programmatore",
   "levels": [
     {
-      "id": "muoviti",
-      "title": "Fai muovere Byte",
+      "id": "primo-passo",
+      "title": "Il primo passo",
       "grid": {
         "legend": { "#": "wall", ".": "floor" },
-        "rows": ["#####", "#...#", "#...#", "#...#", "#####"]
+        "rows": ["######", "#....#", "####.#", "####.#", "######"]
       },
       "hero": { "x": 1, "y": 1, "facing": "east", "hp": 3 },
-      "goal": { "x": 3, "y": 3 },
+      "goal": { "x": 4, "y": 3 },
       "win": [{ "type": "reach" }],
-      "starterCode": "# Porta Byte sulla bandiera in (3, 3).\nmove()\nmove()\nturn_right()\nmove()\nmove()\n",
-      "solution": "move()\nmove()\nturn_right()\nmove()\nmove()\n",
+      "starterCode": "# Byte deve raggiungere la bandiera.\n# Guarda gia verso est: portalo fino al muro di destra.\nmove()\nmove()\nmove()\nmove()\n",
+      "solution": "move()\nmove()\nmove()\nturn_right()\nmove()\nmove()\n",
       "hints": [
-        "Byte guarda a est: due move() lo portano al muro di destra.",
-        "Con turn_right() gira verso sud, poi altri due move() lo mettono sul goal."
+        "Byte esegue le istruzioni una dopo l’altra, esattamente come le scrivi: nessuna magia, nessuna scorciatoia.",
+        "Tre move() lo portano contro il muro di destra. Da lì deve piegare verso il basso.",
+        "Con turn_right() Byte gira verso sud senza spostarsi; poi altri due move() lo mettono sulla bandiera."
       ],
-      "par": 5
+      "par": 6
     },
     {
-      "id": "attorno-al-muro",
-      "title": "Aggira l'ostacolo",
+      "id": "il-lungo-corridoio",
+      "title": "Il lungo corridoio",
       "grid": {
         "legend": { "#": "wall", ".": "floor" },
-        "rows": ["#######", "#.....#", "#.###.#", "#.#.#.#", "#.###.#", "#.....#", "#######"]
+        "rows": ["##########", "#........#", "##########"]
       },
-      "hero": { "x": 1, "y": 1, "facing": "south", "hp": 3 },
-      "goal": { "x": 5, "y": 5 },
+      "hero": { "x": 1, "y": 1, "facing": "east", "hp": 3 },
+      "goal": { "x": 8, "y": 1 },
       "win": [{ "type": "reach" }],
-      "starterCode": "# Aggira il blocco centrale e raggiungi la bandiera in basso a destra.\nwhile not on_goal():\n    if is_blocked():\n        turn_left()\n    move()\n",
+      "starterCode": "# Il corridoio e lungo e scrivere move() a mano e da robot.\n# Completa il ciclo: quante ripetizioni servono davvero?\nfor _ in range(3):\n    move()\n",
+      "solution": "for _ in range(7):\n    move()\n",
       "hints": [
-        "Usa i sensori: is_blocked() ti dice se hai un muro davanti.",
-        "Un ciclo while not on_goal() ripete finché non sei arrivato."
+        "Un ciclo for ripete lo stesso blocco quante volte gli dici: range(n) significa «fallo n volte».",
+        "Conta le celle tra Byte e la bandiera: da (1, 1) a (8, 1) ci sono sette passi.",
+        "range(3) si ferma a metà strada. Alza il numero finché Byte non tocca la bandiera."
       ],
-      "par": 12,
-      "resources": [
-        { "id": "g1", "kind": "gem", "x": 5, "y": 1 }
-      ]
+      "par": 7
     },
     {
-      "id": "duello",
+      "id": "svolta-al-buio",
+      "title": "Svolta al buio",
+      "grid": {
+        "legend": { "#": "wall", ".": "floor" },
+        "rows": ["#######", "#.....#", "#####.#", "#####.#", "#######"]
+      },
+      "hero": { "x": 1, "y": 1, "facing": "east", "hp": 3 },
+      "goal": { "x": 5, "y": 3 },
+      "win": [{ "type": "reach" }],
+      "starterCode": "# Byte non sa dove finisce il muro: deve sentirlo con i sensori.\n# on_goal() e True quando e sulla bandiera; is_blocked() e True\n# se ha un muro proprio davanti.\nwhile not on_goal():\n    move()\n",
+      "solution": "while not on_goal():\n    if is_blocked():\n        turn_right()\n    move()\n",
+      "hints": [
+        "Il ciclo while ripete finché la condizione resta vera: qui, «finché non sei sulla bandiera».",
+        "Se Byte sbatte all’infinito è perché continua ad andare dritto contro il muro. Prima di ogni passo, chiedigli se è bloccato.",
+        "Dentro il while: se is_blocked() allora turn_right(), poi in ogni caso move(). Così gira solo quando serve."
+      ],
+      "par": 7
+    },
+    {
+      "id": "duello-col-bug",
       "title": "Duello con un bug",
       "grid": {
         "legend": { "#": "wall", ".": "floor" },
-        "rows": ["########", "#......#", "#......#", "########"]
+        "rows": ["########", "#......#", "########"]
+      },
+      "hero": { "x": 1, "y": 1, "facing": "east", "hp": 4 },
+      "enemies": [
+        { "id": "b1", "kind": "bug", "x": 5, "y": 1, "hp": 2, "behavior": "static" }
+      ],
+      "win": [{ "type": "defeat" }],
+      "starterCode": "# Un bug ostinato blocca il corridoio: non si muove, ma se resti\n# accanto a lui morde. Avvicinati e colpiscilo con attack().\n# Ha 2 punti vita: un colpo solo non basta.\nmove()\nmove()\nmove()\nattack()\n",
+      "solution": "move()\nmove()\nmove()\nattack()\nattack()\n",
+      "hints": [
+        "attack() colpisce solo la cella subito davanti a Byte: devi essere a un passo dal bug, non a due.",
+        "Il bug ha 2 punti vita, quindi servono due attack() di fila. Ogni turno che passi accanto a lui perdi un punto vita: non gironzolare.",
+        "Tre move() ti portano a (4, 1), proprio davanti al bug. Poi due attack() lo mettono ko."
+      ],
+      "par": 5
+    },
+    {
+      "id": "il-tesoro-e-la-guardia",
+      "title": "Il tesoro e la sua guardia",
+      "grid": {
+        "legend": { "#": "wall", ".": "floor" },
+        "rows": ["##########", "#........#", "##########"]
       },
       "hero": { "x": 1, "y": 1, "facing": "east", "hp": 5 },
       "enemies": [
-        { "id": "b1", "kind": "bug", "x": 6, "y": 1, "hp": 2, "behavior": "melee" }
+        { "id": "b1", "kind": "bug", "x": 8, "y": 1, "hp": 2, "behavior": "melee" }
       ],
       "resources": [
-        { "id": "g1", "kind": "gem", "x": 3, "y": 2 }
+        { "id": "g1", "kind": "gem", "x": 3, "y": 1 }
       ],
       "win": [
-        { "type": "defeat" },
-        { "type": "collect", "kind": "gem", "qty": 1 }
+        { "type": "collect", "kind": "gem", "qty": 1 },
+        { "type": "defeat" }
       ],
-      "starterCode": "# Il bug ti viene incontro: colpiscilo con attack(), poi raccogli la gemma.\nmove()\nmove()\nattack()\nattack()\nturn_right()\nmove()\ncollect()\n",
-      "solution": "move()\nmove()\nattack()\nattack()\nturn_right()\nmove()\ncollect()\n",
+      "starterCode": "# Due obiettivi in uno: raccogli la gemma E sconfiggi il bug.\n# Questo bug e di tipo melee: ti viene incontro da solo, quindi\n# non serve rincorrerlo. Raccogli prima, combatti dopo.\nmove()\nmove()\ncollect()\n",
+      "solution": "move()\nmove()\ncollect()\nmove()\nattack()\nattack()\n",
       "hints": [
-        "Il bug è di tipo melee: ti si avvicina di un passo a ogni tua azione. Non serve rincorrerlo.",
-        "attack() colpisce la cella davanti a te: falla mentre il bug è lì davanti. Servono due colpi (ha 2 PV).",
-        "Sconfitto il bug, girati verso la gemma con turn_right(), avvicinati e usa collect()."
+        "collect() raccoglie la risorsa solo se Byte è fermo sopra di essa: portalo sulla gemma, poi raccogli.",
+        "Il bug melee si avvicina di una cella a ogni tua azione. Mentre raccogli la gemma, lui è già in viaggio verso di te.",
+        "Presa la gemma in (3, 1), continua verso destra: il bug ti raggiunge a metà corridoio. Due attack() lo fermano e la missione è completa."
       ],
-      "par": 7
+      "par": 6
     }
   ]
 }

From 1a0cada31595c6866b4e2d4405bdcedb81428611 Mon Sep 17 00:00:00 2001
From: Marco Farina <marco.farina@jcmaxwell.it>
Date: Wed, 29 Jul 2026 12:03:54 +0200
Subject: [PATCH 10/11] =?UTF-8?q?fix(pyquest):=20accettazione=20finale=20f?=
 =?UTF-8?q?ase=205=20=E2=80=94=20sei=20correzioni=20dalla=20checklist=20ma?=
 =?UTF-8?q?nuale?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Trovate provando il mondo pilota end-to-end nel browser (light + dark, desktop
e viewport stretto) e ricontrollando le solution con un harness CPython.

- «Livello successivo» usava `history.push` su un path assoluto, che non
  antepone il baseUrl come fa <Link>: portava alla 404. Ora il path passa da
  useBaseUrl.
- In dark mode muro (#2b3245) e pavimento (#1e2230) stavano a 1,3:1 di
  contrasto e la mappa era di fatto illeggibile. Nuova coppia a ~3:1, muro
  chiaro su pavimento scuro (l'inverso del tema light).
- Il pannello d'errore ripeteva per intero il traceback già mostrato nella
  console del player: ora ne tiene solo l'ultima riga (tipo + messaggio) e
  rimanda alla console per il dettaglio con la riga esatta.
- Commenti degli starterCode senza accenti nel world.json («gia», «e» per «è»).
- Target del transport a 34px: su puntatore coarse salgono a 44px.
- I global data del plugin includevano `solution` di ogni livello, che finisce
  nel bundle main.js servito a ogni pagina del sito e non viene mai letta dal
  client. Ora viene spogliata. Il world.json statico resta accessibile: non è
  una protezione, è peso in meno e la risposta non arriva insieme al livello.

Aggiunte /docs/pyquest-test e /level-editor all'indice /test.

Verificato: le 5 solution vincono in esattamente `par` azioni (6/7/7/5/6) e
nessuno starterCode vince per sbaglio; vittoria con stelle e record, morte,
step limit, precedenza won > failed > error, errore runtime con trace parziale
animata, print interleaved, seek e step-back, hint progressivi, sblocco
sequenziale e persistenza dopo reload, due istanze indipendenti sulla stessa
pagina, roundtrip dell'editor identico all'originale. typecheck, lint e build
verdi.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015uYRFDbz7dZiMnZ9GeUXWj
---
 plugins/pyquest/index.js                     | 21 +++++++++++++++++++-
 src/components/PyQuest/GamePlayer.module.css | 18 +++++++++++++++++
 src/components/PyQuest/GameScene.module.css  | 10 +++++++---
 src/components/PyQuest/PyQuest.module.css    |  6 ++++++
 src/components/PyQuest/index.tsx             | 15 +++++++++++++-
 src/pages/pyquest/gioca.tsx                  |  8 ++++++--
 src/pages/test.mdx                           |  5 +++++
 static/pyquest/mondo-01/world.json           |  8 ++++----
 8 files changed, 80 insertions(+), 11 deletions(-)

diff --git a/plugins/pyquest/index.js b/plugins/pyquest/index.js
index 8adbcf8..9b0b007 100644
--- a/plugins/pyquest/index.js
+++ b/plugins/pyquest/index.js
@@ -259,6 +259,21 @@ function loadWorlds(worldsAbsDir) {
   return worlds;
 }
 
+/**
+ * I global data di Docusaurus finiscono nel bundle principale, servito a ogni
+ * pagina del sito. `solution` serve solo all'autore (calibrare il par, provare
+ * il livello nell'editor): il client non la legge mai, quindi la togliamo —
+ * meno peso su ogni pagina e la risposta non arriva in faccia allo studente
+ * insieme al livello. Resta nel world.json su disco, che è servito come file
+ * statico: chi la cerca la trova, non è una protezione.
+ */
+function stripAuthorFields(world) {
+  return {
+    ...world,
+    levels: world.levels.map(({ solution: _solution, ...level }) => level),
+  };
+}
+
 module.exports = function pyquestPlugin(context, pluginOptions = {}) {
   const opts = { ...DEFAULT_OPTIONS, ...pluginOptions };
   const staticRoot =
@@ -275,7 +290,11 @@ module.exports = function pyquestPlugin(context, pluginOptions = {}) {
     },
 
     async contentLoaded({ content, actions }) {
-      actions.setGlobalData({ worlds: content.worlds });
+      const worlds = {};
+      for (const [id, world] of Object.entries(content.worlds)) {
+        worlds[id] = stripAuthorFields(world);
+      }
+      actions.setGlobalData({ worlds });
     },
 
     getPathsToWatch() {
diff --git a/src/components/PyQuest/GamePlayer.module.css b/src/components/PyQuest/GamePlayer.module.css
index 324f95d..c3f9279 100644
--- a/src/components/PyQuest/GamePlayer.module.css
+++ b/src/components/PyQuest/GamePlayer.module.css
@@ -113,6 +113,24 @@
   background: var(--at-accent, #0270ad);
 }
 
+/* Su touch i target del transport salgono a 44px (il dito non ha la precisione
+   del mouse); il desktop resta compatto come nel player di Algorithm. */
+@media (pointer: coarse) {
+  .btn {
+    width: 44px;
+    height: 44px;
+  }
+
+  .speedBtn {
+    min-height: 44px;
+    padding: 5px 14px;
+  }
+
+  .scrubInput {
+    height: 32px;
+  }
+}
+
 /* --- Console sincronizzata (print/traceback per atStep) ------------------- */
 
 .console {
diff --git a/src/components/PyQuest/GameScene.module.css b/src/components/PyQuest/GameScene.module.css
index 94a9278..23f2fba 100644
--- a/src/components/PyQuest/GameScene.module.css
+++ b/src/components/PyQuest/GameScene.module.css
@@ -322,9 +322,13 @@
 
 :global(html[data-theme='dark']) .scene {
   --pq-board-bg: #14161c;
-  --pq-floor: #1e2230;
-  --pq-wall: #2b3245;
-  --pq-grid-line: rgba(255, 255, 255, 0.05);
+  /* Muro e pavimento devono restare distinguibili a colpo d'occhio: il primo
+     tentativo (#1e2230 su #2b3245) stava a 1,3:1 e la mappa spariva. Qui il
+     rapporto è ~3:1, con il muro chiaro sul pavimento scuro — l'inverso del
+     tema light, dove il muro è il colore pieno. */
+  --pq-floor: #151926;
+  --pq-wall: #59637f;
+  --pq-grid-line: rgba(255, 255, 255, 0.07);
   --pq-hero: var(--at-accent, #38bdf8);
   --pq-hero-track: #566178;
   --pq-hero-panel: rgba(0, 0, 0, 0.25);
diff --git a/src/components/PyQuest/PyQuest.module.css b/src/components/PyQuest/PyQuest.module.css
index e11decc..43ec9a2 100644
--- a/src/components/PyQuest/PyQuest.module.css
+++ b/src/components/PyQuest/PyQuest.module.css
@@ -77,6 +77,12 @@
   overflow: auto;
 }
 
+.panelHint {
+  margin: 6px 0 0;
+  font-size: 0.82rem;
+  opacity: 0.75;
+}
+
 .winHead {
   display: flex;
   align-items: center;
diff --git a/src/components/PyQuest/index.tsx b/src/components/PyQuest/index.tsx
index f16cea2..9b8d395 100644
--- a/src/components/PyQuest/index.tsx
+++ b/src/components/PyQuest/index.tsx
@@ -374,6 +374,15 @@ function PyQuestInner(props: PyQuestProps) {
     .filter((l) => l.kind === 'stderr')
     .map((l) => l.text)
     .join('');
+  // Il traceback completo è già nella console del player: il pannello ne mostra
+  // solo l'ultima riga — tipo di errore e messaggio, cioè la parte che dice allo
+  // studente cosa correggere.
+  const errorSummary =
+    stderrText
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .pop() ?? '';
 
   // Azioni e stelle di QUESTA esecuzione (il pannello vittoria le mostra);
   // `savedProgress` porta invece il record persistito, visibile anche a freddo.
@@ -435,7 +444,11 @@ function PyQuestInner(props: PyQuestProps) {
           {phase === 'finished' && outcome === 'error' && (
             <div className={clsx(styles.panel, styles.panelError)}>
               <p className={styles.panelTitle}>C’è un errore nel codice</p>
-              <pre className={styles.traceback}>{stderrText}</pre>
+              <pre className={styles.traceback}>{errorSummary}</pre>
+              <p className={styles.panelHint}>
+                Il traceback completo, con la riga esatta, è qui sopra nella
+                console.
+              </p>
             </div>
           )}
           {phase === 'finished' && outcome === null && bumpCount >= 2 && (
diff --git a/src/pages/pyquest/gioca.tsx b/src/pages/pyquest/gioca.tsx
index e50ea32..e8a0436 100644
--- a/src/pages/pyquest/gioca.tsx
+++ b/src/pages/pyquest/gioca.tsx
@@ -13,6 +13,7 @@ import Layout from '@theme/Layout';
 import Heading from '@theme/Heading';
 import Link from '@docusaurus/Link';
 import { useHistory, useLocation } from '@docusaurus/router';
+import useBaseUrl from '@docusaurus/useBaseUrl';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import {
   faArrowLeft,
@@ -52,15 +53,18 @@ function GiocaInner() {
 
   const handleWin = useCallback(() => setJustWon(true), []);
 
+  // `history.push` è il router grezzo: non antepone il baseUrl (a differenza di
+  // <Link>), quindi il path va risolto a mano o si finisce sulla 404.
+  const playPath = useBaseUrl('/pyquest/gioca');
   const goTo = useCallback(
     (nextLevelId: string) => {
       history.push(
-        `/pyquest/gioca?world=${encodeURIComponent(
+        `${playPath}?world=${encodeURIComponent(
           worldId,
         )}&level=${encodeURIComponent(nextLevelId)}`,
       );
     },
-    [history, worldId],
+    [history, playPath, worldId],
   );
 
   if (!world || !level) {
diff --git a/src/pages/test.mdx b/src/pages/test.mdx
index 5ae2d22..ced994e 100644
--- a/src/pages/test.mdx
+++ b/src/pages/test.mdx
@@ -18,4 +18,9 @@ questa pagina di raccolta è a sua volta `noindex`.
 - [PyRunner — sandbox di test](/docs/pyrunner-test)
 - [SQLRunner — sandbox di test](/docs/sqlrunner-test)
 - [Algorithm — sandbox di test](/docs/algorithm-test)
+- [PyQuest — sandbox di test](/docs/pyquest-test)
 - [Callouts — demo visivo](/docs/callouts-demo)
+
+Strumenti d'autore, pubblici ma non linkati né indicizzati:
+
+- [Editor livelli PyQuest](/level-editor)
diff --git a/static/pyquest/mondo-01/world.json b/static/pyquest/mondo-01/world.json
index d88da97..6392763 100644
--- a/static/pyquest/mondo-01/world.json
+++ b/static/pyquest/mondo-01/world.json
@@ -16,7 +16,7 @@
       "hero": { "x": 1, "y": 1, "facing": "east", "hp": 3 },
       "goal": { "x": 4, "y": 3 },
       "win": [{ "type": "reach" }],
-      "starterCode": "# Byte deve raggiungere la bandiera.\n# Guarda gia verso est: portalo fino al muro di destra.\nmove()\nmove()\nmove()\nmove()\n",
+      "starterCode": "# Byte deve raggiungere la bandiera.\n# Guarda già verso est: portalo fino al muro di destra.\nmove()\nmove()\nmove()\nmove()\n",
       "solution": "move()\nmove()\nmove()\nturn_right()\nmove()\nmove()\n",
       "hints": [
         "Byte esegue le istruzioni una dopo l’altra, esattamente come le scrivi: nessuna magia, nessuna scorciatoia.",
@@ -35,7 +35,7 @@
       "hero": { "x": 1, "y": 1, "facing": "east", "hp": 3 },
       "goal": { "x": 8, "y": 1 },
       "win": [{ "type": "reach" }],
-      "starterCode": "# Il corridoio e lungo e scrivere move() a mano e da robot.\n# Completa il ciclo: quante ripetizioni servono davvero?\nfor _ in range(3):\n    move()\n",
+      "starterCode": "# Il corridoio è lungo, e scrivere move() a mano è da robot.\n# Completa il ciclo: quante ripetizioni servono?\nfor _ in range(3):\n    move()\n",
       "solution": "for _ in range(7):\n    move()\n",
       "hints": [
         "Un ciclo for ripete lo stesso blocco quante volte gli dici: range(n) significa «fallo n volte».",
@@ -54,7 +54,7 @@
       "hero": { "x": 1, "y": 1, "facing": "east", "hp": 3 },
       "goal": { "x": 5, "y": 3 },
       "win": [{ "type": "reach" }],
-      "starterCode": "# Byte non sa dove finisce il muro: deve sentirlo con i sensori.\n# on_goal() e True quando e sulla bandiera; is_blocked() e True\n# se ha un muro proprio davanti.\nwhile not on_goal():\n    move()\n",
+      "starterCode": "# Byte non sa dove finisce il muro: deve sentirlo con i sensori.\n# on_goal() è True quando è sulla bandiera; is_blocked() è True\n# se ha un muro proprio davanti.\nwhile not on_goal():\n    move()\n",
       "solution": "while not on_goal():\n    if is_blocked():\n        turn_right()\n    move()\n",
       "hints": [
         "Il ciclo while ripete finché la condizione resta vera: qui, «finché non sei sulla bandiera».",
@@ -102,7 +102,7 @@
         { "type": "collect", "kind": "gem", "qty": 1 },
         { "type": "defeat" }
       ],
-      "starterCode": "# Due obiettivi in uno: raccogli la gemma E sconfiggi il bug.\n# Questo bug e di tipo melee: ti viene incontro da solo, quindi\n# non serve rincorrerlo. Raccogli prima, combatti dopo.\nmove()\nmove()\ncollect()\n",
+      "starterCode": "# Due obiettivi in uno: raccogli la gemma E sconfiggi il bug.\n# Questo bug è di tipo melee: ti viene incontro da solo, quindi\n# non serve rincorrerlo. Raccogli prima, combatti dopo.\nmove()\nmove()\ncollect()\n",
       "solution": "move()\nmove()\ncollect()\nmove()\nattack()\nattack()\n",
       "hints": [
         "collect() raccoglie la risorsa solo se Byte è fermo sopra di essa: portalo sulla gemma, poi raccogli.",

From c18352f0833d8c44e68e79c060447ff4637901af Mon Sep 17 00:00:00 2001
From: Marco Farina <marco.farina@jcmaxwell.it>
Date: Wed, 29 Jul 2026 12:04:00 +0200
Subject: [PATCH 11/11] chore: bump version a 0.14.0 (PyQuest)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015uYRFDbz7dZiMnZ9GeUXWj
---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 87107fb..e3132f5 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "python-doesnt-byte",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",