chesspal 0.3.0 → 0.3.2

package/dist/page/guide/en.md

@@ -1,9 +1,11 @@
 # Chesspal: the guide
 
-With **Chesspal** you play chess against an **AI**, on a real board in your browser, and learn with it. This guide is for players: you do not need to know how to program.
+With **Chesspal** you play chess against an **AI**, on a real board, and learn with it. This guide is for players: you do not need to know how to program.
 
 ## How it works
 
+![The page with the board and the AI's chat window, joined by a thread](how-it-works)
+
 | Who | What they do |
 |---|---|
 | **You** | You move on the board and talk with the AI. |
@@ -14,53 +16,65 @@ There are two windows: this **page**, with the board, and the AI's **chat**, in
 
 No chess engine plays for the AI: every move and every judgment is its own. Chesspal checks that each move is legal and tells the AI what is on the board: the pieces attacked and defended, the pins, the opening's name.
 
-## Quick start
-
-1. Install **Node.js** from [nodejs.org](https://nodejs.org), the recommended (LTS) version, and an AI with your own subscription: **Claude Code** or **Codex**.
-2. Open a terminal, the window where you type commands (on Windows, Command Prompt: press Start, type `cmd`, press Enter; on macOS, Terminal), and type `npm install -g chesspal`, then `chesspal`: this page opens. The first time it offers an icon on your desktop, to open it with a double click.
-3. Press **Claude Code** or **Codex**: the AI's chat opens in a window of its own. Keep it open while you play.
-4. Press **New game**, choose your colour, the clock and the AI's level, and press **Start**.
-
-## If you are lost
-
-- **The AI does not answer**: look at its window. If it is asking you something, answer there; if you closed it, press **Claude Code** or **Codex** again.
-- **The page does not open**: double-click Chesspal's icon, or open it as in the [Quick start](#quick-start).
-- **Your games** are in a folder on your computer: **Who's playing?**, from your picture at the top right, shows where, and **Open the folder** opens it.
+### Getting started
 
-## The AI's chat
-
-- The page opens the AI's **chat** with its buttons, in a window of its own: there the AI thinks and writes. Beside the buttons you choose its model (the version of the AI) and how much it reasons: the more it reasons, the slower it plays.
-- You talk with the AI in the box under its name, a few words with each move: it reads them with your move. You can also write to it in its window.
-- A **move written** in the chat counts too: `e4`, `Nf3`, with the English letters of the pieces (K Q R B N), or in words.
-- At each **new game**, the chat the page opened starts again clean by itself, once the AI has stopped thinking: a long chat makes the AI slower.
+1. Click the **AI's name**, at the top left, and choose its chat among those on your computer: **Claude Code** or **Codex**. It opens in a window of its own: keep it open while you play.
+2. Press **New game**, choose your colour, the clock and the AI's level, and press **Start**.
+3. Move: the AI answers on the board, and with a few words under its name.
 
 ## The game
 
+![The board with the dots of the legal moves and a piece moving](game)
+
 - **Move** by dragging a piece, or by clicking the piece and then its square. The dots show the legal moves; when a move is not allowed, the page says why.
 - **The clock**, if you chose one, starts with **Start**. The AI has its own and knows how much time it has left.
 - **Offer a draw** on your turn, once each side has moved; **Resign** ends the game.
-- **The helps**: with "The AI teaches as you play", in the settings, the **Helps** card shows the pieces in danger, the pins and the pawns, and the AI, as your coach, gives you an idea. The AI draws coloured arrows on the board: the **?** beside the moves explains every mark.
 - **Flip** turns the board round; **PGN** saves the moves in the file every chess site reads, to open on Lichess or Chess.com.
 
+## Talking with the AI
+
+![The box to write in under the AI's name, and its answer](talk)
+
+- You talk with the AI in the **box under its name**, a few words with each move: it reads them with your move. You can also write to it in its window.
+- A **move written** in the chat counts too: `e4`, `Nf3`, with the English letters of the pieces (K Q R B N), or in words.
+- **The AI's name** opens the choice of its chat: Claude Code or Codex, the model (which AI: some are faster, others stronger) and how much it reasons. The more it reasons, the slower it plays. If you change them, the chat starts afresh in the same window: the AI forgets what you talked about, and the game stays as it is.
+- At each **new game**, the chat the page opened starts afresh by itself, once the AI has stopped thinking: a long chat makes the AI slower.
+
+## Helps and marks
+
+![Coloured arrows and badges on the board, beside the helps' card](helps)
+
+- With **"The AI teaches as you play"**, in the settings, the **Helps** card shows the pieces in danger, the pins and the pawns, and the AI, as your coach, gives you an idea.
+- The AI draws **coloured arrows** on the board: the **?** beside the moves explains every mark.
+- In the review, a **badge** on a move gives the AI's judgment: a great move, an inaccuracy, a blunder.
+
 ## Review and analysis
 
-- When the game is over, press **Analyse the game**: the AI goes over it and puts its judgments and notes on the moves. Read them by stepping through the moves with the arrows.
+![The bar that steps through the moves, and the judgments on the moves](analysis)
+
+- When the game is over, press **Analyse the game**: the AI goes over it and puts its judgments and notes on the moves. Read them by stepping through the moves with the arrows at the foot of the column, or by clicking a move.
 - **Analyses**, in the header, opens your analyses, and loads a game played elsewhere: paste its PGN, or choose a .pgn file.
 - Ask the AI about the game in the box under its name.
 - **Annotated PGN** saves the game with its comments.
 
 ## Players and profile
 
-- **Who's playing?**: your picture at the top right chooses a player or adds one. Each has their own games and settings.
-- **Your profile**: a click on your picture beside the board, or the pencil in **Who's playing?**, changes your picture, your name, how you play, your names on Lichess and Chess.com and your FIDE rating.
+![Your picture at the top right and the Who's playing? window](players)
+
+- **Who's playing?**: your picture at the top right, or your name beside the board, opens the list of the players: there you choose one or add one. Each has their own games and settings.
+- **Your profile**: in **Who's playing?**, the pencil beside your name changes your picture, your name, how you play, your names on Lichess and Chess.com and your FIDE rating.
 - **Your rating**: from your names there, Chesspal reads your public rating, the one of your rapid games if you play them, and tells the AI. No passwords: anyone can see that rating on the site. Without a name there, the AI knows how you play from **How do you play?**
 - **Your FIDE rating**, if you play tournaments, you type yourself: no site gives it to Chesspal. The AI reads it beside the site's, each on its own.
 - If you load a game played on Lichess or Chess.com, Chesspal knows which colour you played.
 
 ## Questions and problems
 
-- **The AI is slow**: it really thinks over each move. Choose a faster model, or less reasoning, beside the chat's buttons.
+- **The AI does not answer, and its clock runs**: look at its window, which may have gone behind the others: find it in the bar at the bottom. If it is asking you something, answer there; if you closed it, click the AI's name and open another.
+- **The AI is slow**: it really thinks over each move. From its name, choose a faster model, or less reasoning.
+- **A piece does not move**: it is not your turn, or the move is not allowed; the page says why.
+- **Closed the page?** Open it again from Chesspal's icon, on the desktop or in the menu: the game you left halfway is still there.
+- **Your games** are in a folder on your computer: **Who's playing?**, from your picture at the top right, shows where, and **Open the folder** opens it. For a backup copy it, with the chat and the page closed.
+- **A new version of Chesspal**: an arrow at the top tells you, and installs it between games.
 - **What it costs**: Chesspal is free; the AI uses your own subscription, and you pay nothing more.
 - **Can the AI play an illegal move?** No: Chesspal checks every move. Its judgments are its own, though, and an AI can be wrong, like a person.
-- **A backup**: copy the folder of your games, with the chat and the page closed.
 - **Something does not work?** Tell us on [GitHub](https://github.com/stefanocaronia/chesspal/issues): what you did, what you expected, what happened. GitHub is the site where Chesspal is made: you write there with a free account, and anyone can read it.

package/dist/page/guide/guide.css

@@ -1,11 +1,19 @@
-/* The guide: a tall dialog, an index of chips, each part folding under its title, and the foot with who made Chesspal and the credits (Zoe) */
+/* The guide: a wide dialog, the index of its pages beside the page shown, and at the dialog's foot, on every page, the arrows to the one before and after
+   (Zoe) */
 
 .dialog:has(> .guide) {
+    width: min(900px, calc(100vw - 32px));
     height: calc(100vh - 48px);
     max-height: 90vh;
 }
 
+/* As tall as the dialog under its title, so that a short page keeps its arrows at the foot */
 .guide {
+    display: grid;
+    grid-template-columns: 200px minmax(0, 1fr);
+    gap: 28px;
+    align-items: start;
+    min-height: calc(100% - 60px);
     font-size: 14px;
     line-height: 1.55;
 }
@@ -36,76 +44,69 @@
     font-size: 13px;
 }
 
-/* A heading a chip or a link brings into sight stays under the dialog's own title */
+/* A heading a link brings into sight stays under the dialog's own title */
 .guide [id] {
     scroll-margin-top: 64px;
 }
 
+/* The index: the pages' titles, the one shown marked by a bar at its start; it stays in sight while the page scrolls */
 .guide-index {
+    position: sticky;
+    top: 60px;
     display: flex;
-    flex-wrap: wrap;
-    gap: 8px;
-    margin: 4px 0 14px;
+    flex-direction: column;
+    gap: 2px;
+    margin-top: 4px;
 }
 
 .guide-chip {
     min-height: 32px;
-    padding: 5px 12px;
-    border: 1px solid var(--line);
-    border-radius: 999px;
-    background: var(--card);
-    color: var(--ink);
+    padding: 6px 12px;
+    border: 0;
+    border-radius: 0 8px 8px 0;
+    background: none;
+    color: var(--soft);
     font: inherit;
-    font-size: 13px;
+    font-size: 13.5px;
+    text-align: start;
+    cursor: pointer;
 }
 
 .guide-chip:hover {
-    border-color: var(--accent);
-    color: var(--accent);
+    color: var(--ink);
 }
 
-/* A part: its title, a chevron that turns when it opens */
-.guide-part {
-    border-top: 1px solid var(--line);
+.guide-chip[aria-current="page"] {
+    background: var(--quote);
+    box-shadow: inset 3px 0 0 var(--accent);
+    color: var(--ink);
+    font-weight: 600;
 }
 
-.guide-part summary {
+.guide-page {
     display: flex;
-    align-items: center;
-    gap: 8px;
-    padding: 10px 0;
-    cursor: pointer;
-    list-style: none;
-}
-
-.guide-part summary::-webkit-details-marker {
-    display: none;
+    flex-direction: column;
+    align-self: stretch;
 }
 
-.guide-part summary::before,
-.credits summary::before {
-    content: "";
-    width: 7px;
-    height: 7px;
-    border-right: 1.7px solid var(--soft);
-    border-bottom: 1.7px solid var(--soft);
-    transform: rotate(-45deg);
-    transition: transform 0.15s;
+/* The page's text grows to push the arrows to the foot */
+.guide-text {
+    flex: 1 0 auto;
+    margin-bottom: 22px;
 }
 
-.guide-part[open] summary::before,
-.credits[open] summary::before {
-    transform: rotate(45deg);
-}
-
-.guide-part h3 {
-    margin: 0;
-    font-size: 16px;
+/* The page's title takes the focus when the page turns, for a screen reader: no ring, since no key brought it there */
+.guide-page h3 {
+    margin: 4px 0 12px;
+    font-size: 19px;
     font-weight: 600;
+    outline: none;
 }
 
-.guide-part[open] {
-    padding-bottom: 6px;
+.guide-page h4 {
+    margin: 16px 0 6px;
+    font-size: 15px;
+    font-weight: 600;
 }
 
 .guide-table {
@@ -125,68 +126,99 @@
     vertical-align: top;
 }
 
-/* The foot: who made Chesspal, where it lives, the heart that supports it; the credits folded under it */
-.guide-foot {
-    display: grid;
-    gap: 6px;
-    margin-top: 18px;
-    padding-top: 14px;
+/* The arrows to the page before and after, each with its title: at the foot of a short page, and at the dialog's foot over a long one */
+.guide-turn {
+    position: sticky;
+    bottom: 0;
+    display: flex;
+    gap: 12px;
+    padding: 14px 0 4px;
     border-top: 1px solid var(--line);
-    color: var(--soft);
-    font-size: 12.5px;
-    text-align: center;
-}
-
-.guide-foot p {
-    margin: 0;
+    background: var(--card);
 }
 
-.foot-own {
-    display: flex;
-    flex-wrap: wrap;
+.guide-turn button {
+    display: inline-flex;
     align-items: center;
-    justify-content: center;
-    gap: 6px 14px;
+    gap: 6px;
+    min-height: 36px;
+    padding: 6px 12px;
+    border: 1px solid var(--line);
+    border-radius: 8px;
+    background: var(--card);
+    color: var(--ink);
+    font: inherit;
+    font-size: 13.5px;
+    cursor: pointer;
 }
 
-.guide .foot-own a {
-    display: inline-flex;
-    align-items: center;
-    gap: 5px;
-    color: inherit;
-    text-decoration: none;
+.guide-turn button:hover {
+    border-color: var(--accent);
+    color: var(--accent);
 }
 
-.guide .foot-own a:hover,
-.guide .foot-own a:focus-visible {
-    color: var(--ink);
+.guide-turn .next {
+    margin-inline-start: auto;
 }
 
-.foot-own .icon {
+.guide-turn .icon {
     width: 16px;
     height: 16px;
-}
+    fill: none;
+    stroke: currentColor;
+    stroke-width: 2;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+}
+
+/* On a narrow screen the index is one row of chips over the page, scrolled sideways, its end fading where more follow; the arrows share the page's
+   width at its foot, each title by its arrow */
+@media (max-width: 640px) {
+    .guide {
+        grid-template-columns: minmax(0, 1fr);
+        grid-template-rows: auto 1fr;
+        gap: 14px;
+    }
 
-.foot-support .icon {
-    color: var(--low-time);
-}
+    .guide-index {
+        position: static;
+        flex-direction: row;
+        gap: 6px;
+        overflow-x: auto;
+        scrollbar-width: none;
+        mask-image: linear-gradient(to right, #000 calc(100% - 24px), transparent);
+    }
 
-.credits summary {
-    display: inline-flex;
-    align-items: center;
-    gap: 6px;
-    cursor: pointer;
-    list-style: none;
-}
+    .guide-index::-webkit-scrollbar {
+        display: none;
+    }
 
-.credits summary::-webkit-details-marker {
-    display: none;
-}
+    .guide-chip {
+        flex: none;
+        border: 1px solid var(--line);
+        border-radius: 999px;
+        font-size: 13px;
+        white-space: nowrap;
+    }
 
-.credits ul {
-    margin: 8px auto 0;
-    max-width: 60ch;
-    text-align: start;
+    .guide-chip[aria-current="page"] {
+        box-shadow: none;
+        border-color: var(--accent);
+    }
+
+    .guide-turn {
+        position: static;
+    }
+
+    .guide-turn button {
+        flex: 1 1 0;
+        min-width: 0;
+    }
+
+    .guide-turn .next {
+        justify-content: flex-end;
+        text-align: end;
+    }
 }
 
 @media (max-width: 600px) {

package/dist/page/guide/guide.js

@@ -1,41 +1,63 @@
-import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
-// The guide, from the book in the header: how to play, in the page's language (guide/<code>.md), an index of chips, its parts folding, the first two
-// open, and its foot; its anchors are the English guide's, so that a link finds its heading in both languages.
-import { useEffect, useMemo, useState } from "preact/hooks";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "preact/jsx-runtime";
+// The guide, from the book in the header: how to play, in the page's language (guide/<code>.md), a page at a time, chosen in its index or with the arrows at
+// its foot, the credits the last; its anchors are the English guide's, so that a link finds its heading in both languages.
+import { useEffect, useMemo, useRef, useState } from "preact/hooks";
 import { Dialog } from "../dialogs/dialog.js";
 import { anchorOf, markdownBlocks } from "./blocks.js";
-import { GuideFoot } from "./foot.js";
-import { Blocks, Inline } from "./markdown.js";
+import { GuideCredits } from "./credits.js";
+import { Blocks } from "./markdown.js";
 /** The guide in its dialog. */
 export function GuideDialog({ open, onClose, text }) {
     return (_jsx(Dialog, { open: open, title: text.guide.title, onClose: onClose, text: text, children: _jsx(Guide, { text: text }) }));
 }
 function Guide({ text }) {
+    const words = text.guide;
     const guide = useGuide(text.language);
-    const [open, setOpen] = useState(() => new Set([0, 1]));
+    const { lead, pages, anchors } = useMemo(() => guidePages(guide.own, guide.english), [guide]);
+    const [shown, setShown] = useState(0);
+    // The heading to bring into sight once its page is drawn: "" for the page's top.
     const [sought, setSought] = useState();
-    const { lead, parts, anchors } = useMemo(() => guideParts(guide.own, guide.english), [guide]);
-    const toggle = (index, event) => {
-        event.preventDefault();
-        setOpen((before) => new Set(before.has(index) ? [...before].filter((one) => one !== index) : [...before, index]));
+    const top = useRef(null);
+    const title = useRef(null);
+    const titles = [...pages.map((page) => page.heading.text), words.credits];
+    const page = pages[shown];
+    const show = (index, id = "") => {
+        setShown(index);
+        setSought(id);
     };
-    // A chip of the index, or a link to a heading, opens its part and brings the heading into sight.
-    const go = (id) => {
-        const index = parts.findIndex((part) => [part.heading, ...part.blocks].some((block) => anchors.get(block) === id));
+    // A link to a heading shows its page, and the heading in it.
+    const go = (anchor) => {
+        const id = idOf(anchor);
+        const index = pages.findIndex((one) => [one.heading, ...one.blocks].some((block) => anchors.get(block) === id));
         if (index >= 0) {
-            setOpen((before) => new Set([...before, index]));
-            setSought(id);
+            show(index, id);
         }
     };
-    const goToAnchor = (anchor) => go(idOf(anchor));
+    // A page turned: its chip in sight in the index, the focus on its title, which a screen reader says, and its top or the heading sought in sight.
     useEffect(() => {
         if (sought === undefined) {
             return;
         }
         setSought(undefined);
-        document.getElementById(sought)?.scrollIntoView({ block: "start", behavior: matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth" });
+        top.current?.querySelector(".guide-chip[aria-current]")?.scrollIntoView({ inline: "center", block: "nearest" });
+        title.current?.focus({ preventScroll: true });
+        const heading = sought === "" ? null : document.getElementById(sought);
+        if (heading === null) {
+            top.current?.closest("dialog")?.scrollTo({ top: 0 });
+        }
+        else {
+            heading.scrollIntoView({ block: "start" });
+        }
     }, [sought]);
-    return (_jsxs("div", { class: "guide", children: [_jsx(Blocks, { blocks: lead, anchors: anchors, go: goToAnchor }), _jsx("nav", { class: "guide-index", "aria-label": text.guide.contents, children: parts.map((part) => (_jsx("button", { type: "button", class: "guide-chip", onClick: () => go(anchors.get(part.heading) ?? ""), children: _jsx(Inline, { text: part.heading.text, go: goToAnchor }) }, part.heading.text))) }), parts.map((part, index) => (_jsxs("details", { id: anchors.get(part.heading), class: "guide-part", open: open.has(index), children: [_jsx("summary", { onClick: (event) => toggle(index, event), children: _jsx("h3", { children: part.heading.text }) }), _jsx(Blocks, { blocks: part.blocks, anchors: anchors, go: goToAnchor })] }, part.heading.text))), _jsx(GuideFoot, { text: text })] }));
+    if (pages.length === 0) {
+        return _jsx("div", { class: "guide", ref: top });
+    }
+    return (_jsxs("div", { class: "guide", ref: top, children: [_jsx("nav", { class: "guide-index", "aria-label": words.contents, children: titles.map((title, index) => (_jsx("button", { type: "button", class: "guide-chip", "aria-current": index === shown ? "page" : undefined, onClick: () => show(index), children: title }, title))) }), _jsxs("article", { class: "guide-page", children: [_jsxs("div", { class: "guide-text", children: [_jsx("h3", { id: page === undefined ? undefined : anchors.get(page.heading), ref: title, tabIndex: -1, children: titles[shown] }), page === undefined ? _jsx(GuideCredits, { text: text }) : (_jsxs(_Fragment, { children: [shown === 0 ? _jsx(Blocks, { blocks: lead, anchors: anchors, go: go }) : null, _jsx(Blocks, { blocks: page.blocks, anchors: anchors, go: go })] }))] }), _jsxs("div", { class: "guide-turn", children: [shown === 0 ? null : _jsx(TurnButton, { back: true, title: titles[shown - 1] ?? "", label: words.previous, onTurn: () => show(shown - 1) }), shown === titles.length - 1 ? null : _jsx(TurnButton, { title: titles[shown + 1] ?? "", label: words.next, onTurn: () => show(shown + 1) })] })] })] }));
+}
+/** An arrow at a page's foot, with the title of the page it shows. */
+function TurnButton({ back = false, title, label, onTurn }) {
+    const arrow = (_jsx("svg", { class: "icon", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { d: back ? "M14.5 6L8.5 12L14.5 18" : "M9.5 6L15.5 12L9.5 18" }) }));
+    return (_jsxs("button", { type: "button", class: back ? "back" : "next", "aria-label": `${label}: ${title}`, onClick: onTurn, children: [back ? arrow : null, title, back ? null : arrow] }));
 }
 /** The guide in a language, and in English for its anchors; empty until they are read. */
 function useGuide(language) {
@@ -63,8 +85,8 @@ function guideIn(language) {
         return "";
     });
 }
-/** The guide's lead, the lines before its first part, its title aside; its parts; and each heading's anchor, the English one at its place. */
-function guideParts(own, english) {
+/** The guide's lead, the lines before its first page, its title aside; its pages; and each heading's anchor, the English one at its place. */
+function guidePages(own, english) {
     const blocks = markdownBlocks(own);
     const headings = blocks.filter((block) => block.kind === "heading");
     const englishHeadings = markdownBlocks(english).filter((block) => block.kind === "heading");
@@ -72,16 +94,16 @@ function guideParts(own, english) {
     const anchors = new Map(headings.map((heading, index) => [heading, idOf(anchorOf((sameShape ? englishHeadings[index] : heading)?.text ?? heading.text))]));
     const first = blocks.findIndex((block) => block.kind === "heading" && block.level === 2);
     const lead = (first < 0 ? blocks : blocks.slice(0, first)).filter((block) => !(block.kind === "heading" && block.level === 1));
-    const parts = [];
+    const pages = [];
     for (const block of first < 0 ? [] : blocks.slice(first)) {
         if (block.kind === "heading" && block.level === 2) {
-            parts.push({ heading: block, blocks: [] });
+            pages.push({ heading: block, blocks: [] });
         }
         else {
-            parts.at(-1)?.blocks.push(block);
+            pages.at(-1)?.blocks.push(block);
         }
     }
-    return { lead, parts, anchors };
+    return { lead, pages, anchors };
 }
 // A heading's id on the page, apart from the page's own.
 function idOf(anchor) {

package/dist/page/guide/it.md

@@ -1,9 +1,11 @@
 # Chesspal: la guida
 
-Con **Chesspal** giochi a scacchi contro un'**AI**, su una scacchiera vera nel browser, e impari con lei. Questa guida è per chi gioca: non serve saper programmare.
+Con **Chesspal** giochi a scacchi contro un'**AI**, su una scacchiera vera, e impari con lei. Questa guida è per chi gioca: non serve saper programmare.
 
 ## Come funziona
 
+![La pagina con la scacchiera e la finestra della chat dell'AI, unite da un filo](how-it-works)
+
 | Chi | Cosa fa |
 |---|---|
 | **Tu** | Muovi sulla scacchiera e parli con l'AI. |
@@ -14,53 +16,65 @@ Le finestre sono due: questa **pagina**, con la scacchiera, e la **chat** dell'A
 
 Nessun motore di scacchi gioca al posto dell'AI: ogni mossa e ogni giudizio sono suoi. Chesspal controlla che ogni mossa sia legale e dice all'AI cosa c'è sulla scacchiera: i pezzi attaccati e difesi, le inchiodature, il nome dell'apertura.
 
-## Avvio rapido
-
-1. Installa **Node.js** da [nodejs.org](https://nodejs.org), la versione consigliata (LTS), e un'AI col tuo abbonamento: **Claude Code** o **Codex**.
-2. Apri un terminale, la finestra dove si scrivono i comandi (su Windows il Prompt dei comandi: tasto Start, scrivi `cmd`, Invio; su macOS il Terminale), e scrivi `npm install -g chesspal`, poi `chesspal`: si apre questa pagina. La prima volta ti propone un'icona sul desktop, per aprirla con un doppio clic.
-3. Premi **Claude Code** o **Codex**: la chat dell'AI si apre in una finestra sua. Tienila aperta mentre giochi.
-4. Premi **Nuova partita**, scegli il colore, l'orologio e il livello dell'AI, e premi **Inizia**.
-
-## Se ti sei perso
-
-- **L'AI non risponde**: guarda la sua finestra. Se ti sta chiedendo qualcosa, rispondi lì; se l'hai chiusa, premi di nuovo **Claude Code** o **Codex**.
-- **La pagina non si apre**: fai doppio clic sull'icona di Chesspal, o aprila come nell'[Avvio rapido](#quick-start).
-- **Le tue partite** stanno in una cartella sul tuo computer: **Chi gioca?**, dalla tua immagine in alto a destra, dice dove, e **Apri la cartella** la apre.
+### Per cominciare
 
-## La chat dell'AI
-
-- La pagina apre la **chat** dell'AI coi suoi pulsanti, in una finestra a parte: lì l'AI pensa e scrive. Accanto ai pulsanti scegli il modello (la versione dell'AI) e quanto ragiona: più ragiona, più gioca lenta.
-- Parli con l'AI nella casella sotto il suo nome, qualche parola a ogni mossa: le legge con la tua mossa. Puoi scriverle anche nella sua finestra.
-- Anche una **mossa scritta** nella chat vale: `e4`, `Nf3`, con le lettere inglesi dei pezzi (K Q R B N), o a parole.
-- A ogni **nuova partita** la chat aperta dalla pagina riparte pulita da sola, se l'AI ha finito di pensare: una chat lunga rende l'AI più lenta.
+1. Clicca il **nome dell'AI**, in alto a sinistra, e scegli la chat fra quelle che hai sul computer: **Claude Code** o **Codex**. Si apre in una finestra sua: tienila aperta mentre giochi.
+2. Premi **Nuova partita**, scegli il colore, l'orologio e il livello dell'AI, e premi **Inizia**.
+3. Muovi: l'AI risponde sulla scacchiera, e con qualche parola sotto il suo nome.
 
 ## La partita
 
+![La scacchiera coi pallini delle mosse legali e un pezzo che si sposta](game)
+
 - **Muovi** trascinando un pezzo, o cliccando il pezzo e poi la sua casa. I pallini segnano le mosse legali; quando una mossa è vietata, la pagina dice perché.
 - **L'orologio**, se ne hai scelto uno, parte con **Inizia**. Anche l'AI ha il suo, e sa quanto tempo le resta.
 - **Proponi patta** nel tuo turno, dopo una mossa a testa; **Abbandona** chiude la partita.
-- **Gli aiuti**: con «L'AI ti insegna mentre giochi», nelle impostazioni, la scheda **Aiuti** mostra i pezzi in pericolo, le inchiodature e i pedoni, e l'AI, da allenatore, ti dà un'idea. L'AI disegna frecce colorate sulla scacchiera: il **?** accanto alle mosse spiega ogni segno.
 - **Gira** volta la scacchiera; **PGN** salva le mosse nel file che leggono tutti i siti di scacchi, da aprire su Lichess o Chess.com.
 
+## Parlare con l'AI
+
+![La casella per scrivere sotto il nome dell'AI, e la sua risposta](talk)
+
+- Parli con l'AI nella **casella sotto il suo nome**, qualche parola a ogni mossa: le legge con la tua mossa. Puoi scriverle anche nella sua finestra.
+- Anche una **mossa scritta** nella chat vale: `e4`, `Nf3`, con le lettere inglesi dei pezzi (K Q R B N), o a parole.
+- **Il nome dell'AI** apre la scelta della chat: Claude Code o Codex, il modello (quale AI: alcune sono più veloci, altre più forti) e quanto ragiona. Più ragiona, più gioca lenta. Se cambi, la chat riparte da capo nella stessa finestra: l'AI dimentica la chiacchierata di prima, la partita resta com'è.
+- A ogni **nuova partita** la chat aperta dalla pagina riparte da capo da sola, se l'AI ha finito di pensare: una chat lunga rende l'AI più lenta.
+
+## Gli aiuti e i segni
+
+![Frecce colorate e bollini sulla scacchiera, accanto alla scheda degli aiuti](helps)
+
+- Con **«L'AI ti insegna mentre giochi»**, nelle impostazioni, la scheda **Aiuti** mostra i pezzi in pericolo, le inchiodature e i pedoni, e l'AI, da allenatore, ti dà un'idea.
+- L'AI disegna **frecce colorate** sulla scacchiera: il **?** accanto alle mosse spiega ogni segno.
+- Nel ripasso, un **bollino** su una mossa dice il giudizio dell'AI: un'ottima mossa, un'imprecisione, un errore grave.
+
 ## Il ripasso e l'analisi
 
-- A partita finita premi **Analizza la partita**: l'AI la ripassa e mette sulle mosse i suoi giudizi e le sue note. Le leggi scorrendo le mosse con le frecce.
+![La barra per scorrere le mosse e i giudizi sulle mosse](analysis)
+
+- A partita finita premi **Analizza la partita**: l'AI la ripassa e mette sulle mosse i suoi giudizi e le sue note. Le leggi scorrendo le mosse con le frecce in fondo alla colonna, o cliccando una mossa.
 - **Analisi**, nell'intestazione, apre le tue analisi e carica una partita giocata altrove: incolla il suo PGN, o scegli un file .pgn.
 - Chiedi all'AI della partita nella casella sotto il suo nome.
 - **PGN annotato** salva la partita coi commenti.
 
 ## I giocatori e il profilo
 
-- **Chi gioca?**: la tua immagine in alto a destra sceglie un giocatore o ne aggiunge uno. Ognuno ha le sue partite e le sue impostazioni.
-- **Il tuo profilo**: un clic sulla tua immagine accanto alla scacchiera, o la matita in **Chi gioca?**, cambia la tua immagine, il nome, come giochi, i tuoi nomi su Lichess e Chess.com e il tuo punteggio FIDE.
+![La tua immagine in alto a destra e la finestra Chi gioca?](players)
+
+- **Chi gioca?**: la tua immagine in alto a destra, o il tuo nome accanto alla scacchiera, apre l'elenco dei giocatori: lì ne scegli uno o ne aggiungi uno. Ognuno ha le sue partite e le sue impostazioni.
+- **Il tuo profilo**: in **Chi gioca?**, la matita accanto al tuo nome cambia la tua immagine, il nome, come giochi, i tuoi nomi su Lichess e Chess.com e il tuo punteggio FIDE.
 - **Il tuo punteggio**: dai tuoi nomi lì, Chesspal legge il tuo punteggio pubblico, quello delle partite rapide se le giochi, e lo dice all'AI. Niente password: quel punteggio lo vede chiunque sul sito. Senza un nome lì, l'AI sa come giochi da **Come giochi?**
 - **Il punteggio FIDE**, se giochi tornei, lo scrivi tu: nessun sito lo dà a Chesspal. L'AI lo legge accanto a quello del sito, ognuno per sé.
 - Se carichi una partita giocata su Lichess o Chess.com, Chesspal sa da che colore giocavi tu.
 
 ## Domande e problemi
 
-- **L'AI è lenta**: ogni mossa la pensa davvero. Scegli un modello più veloce, o meno ragionamento, accanto ai pulsanti della chat.
+- **L'AI non risponde, e il suo orologio corre**: guarda la sua finestra, che può essere finita dietro le altre: cercala nella barra in basso. Se ti sta chiedendo qualcosa, rispondi lì; se l'hai chiusa, clicca il nome dell'AI e aprine un'altra.
+- **L'AI è lenta**: ogni mossa la pensa davvero. Dal suo nome scegli un modello più veloce, o meno ragionamento.
+- **Un pezzo non si muove**: non è il tuo turno, o la mossa è vietata; la pagina dice perché.
+- **Hai chiuso la pagina?** Riaprila dall'icona di Chesspal, sul desktop o nel menu: la partita lasciata a metà è ancora lì.
+- **Le tue partite** stanno in una cartella sul tuo computer: **Chi gioca?**, dalla tua immagine in alto a destra, dice dove, e **Apri la cartella** la apre. Per tenerne una copia di sicurezza, copia la cartella, con la chat e la pagina chiuse.
+- **Una versione nuova di Chesspal**: una freccia in alto te lo dice e la installa, fra una partita e l'altra.
 - **Quanto costa**: Chesspal è gratis; l'AI usa il tuo abbonamento, e non paghi niente in più.
 - **L'AI può fare una mossa illegale?** No: Chesspal controlla ogni mossa. I suoi giudizi però sono suoi, e un'AI può sbagliare, come una persona.
-- **Un backup**: copia la cartella delle tue partite, con la chat e la pagina chiuse.
 - **Qualcosa non va?** Raccontacelo su [GitHub](https://github.com/stefanocaronia/chesspal/issues): cosa hai fatto, cosa ti aspettavi, cosa è successo. GitHub è il sito dove si fa Chesspal: ci scrivi con un account gratuito, e chiunque può leggere.

package/dist/page/guide/markdown.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "preact/jsx-runtime";
+import { drawings } from "./drawings/drawings.js";
 /** Blocks drawn as the page's elements: headings one level under the part's, each with the anchor given by its place among them; a link to an anchor calls go. */
 export function Blocks({ blocks, anchors, go }) {
     return _jsx(_Fragment, { children: blocks.map((block, index) => _jsx(BlockView, { block: block, anchors: anchors, go: go }, index)) });
@@ -47,6 +48,10 @@ function BlockView({ block, anchors, go }) {
             return (_jsx("blockquote", { children: _jsx(Blocks, { blocks: block.blocks, anchors: anchors, go: go }) }));
         case "code":
             return _jsx("pre", { children: _jsx("code", { children: block.text }) });
+        case "drawing": {
+            const Drawing = drawings[block.name];
+            return Drawing === undefined ? null : (_jsx("figure", { class: "guide-drawing", role: "img", "aria-label": block.alt, children: _jsx(Drawing, {}) }));
+        }
         case "rule":
             return null;
     }