feat(learn): interactive Playground feature pages with live embed

components/mdx.tsx

@@ -2,12 +2,14 @@ import defaultMdxComponents from 'fumadocs-ui/mdx';
 import type { MDXComponents } from 'mdx/types';
 import { Mermaid } from '@/components/mermaid';
 import { TryIt } from '@/components/try-it';
+import { TrueCalc } from '@/components/truecalc';
 
 export function getMDXComponents(components?: MDXComponents) {
   return {
     ...defaultMdxComponents,
     Mermaid,
     TryIt,
+    TrueCalc,
     ...components,
   } satisfies MDXComponents;
 }

components/truecalc.tsx

@@ -0,0 +1,35 @@
+const PLAYGROUND_ORIGIN = 'https://try.truecalc.app';
+
+/**
+ * Embeds the live TrueCalc playground as an iframe, seeded with the given
+ * cells so readers can try a feature inline.
+ *
+ * `seed` uses the playground's seed syntax, e.g. `A1=10;A2==A1+1`
+ * (a bare value is a literal; a leading `=` after the cell's `=` is a formula).
+ */
+export function TrueCalc({
+  mode = 'standalone',
+  seed,
+  title = 'TrueCalc interactive playground',
+}: {
+  mode?: string;
+  seed?: string;
+  title?: string;
+}) {
+  const src = seed
+    ? `${PLAYGROUND_ORIGIN}/?seed=${encodeURIComponent(seed)}`
+    : `${PLAYGROUND_ORIGIN}/`;
+
+  return (
+    <div className="not-prose my-4" data-mode={mode}>
+      <iframe
+        src={src}
+        title={title}
+        loading="lazy"
+        allow="clipboard-read; clipboard-write"
+        className="w-full rounded-lg border"
+        style={{ height: 360 }}
+      />
+    </div>
+  );
+}

content/docs/learn/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Learn",
   "root": true,
-  "pages": ["index", "(foundations)", "(workbooks)", "(advanced)", "(platforms)"]
+  "pages": ["index", "(foundations)", "(workbooks)", "(advanced)", "playground", "(platforms)"]
 }

content/docs/learn/playground/clipboard.mdx

@@ -0,0 +1,69 @@
+---
+title: "Copy, cut, and paste"
+description: "Copy adjusts references to the paste target; cut moves a cell verbatim."
+---
+
+## What it does
+
+Select a cell and press **Ctrl+C** to copy or **Ctrl+X** to cut, then select a target and press **Ctrl+V** to paste.
+
+- **Copy + paste** adjusts the formula's relative references by the paste offset — `=A1+B1` copied from **C1** to **C3** becomes `=A3+B3`, while `$`-anchored parts stay put (`=$A$1+B1` → `=$A$1+B3`). The source is left untouched and the clipboard stays loaded, so you can paste it again.
+- **Cut + paste** _moves_ the cell: the formula is written to the destination **verbatim** (no reference adjustment) and the source cell is cleared. The clipboard is consumed after that one paste.
+
+## Try it
+
+<TrueCalc mode="standalone" seed="A1=10;B1=20;C1==A1+B1;A3=5;B3=7" />
+
+## How it works
+
+TrueCalc owns the calc. Copy and cut record the source cell's raw input; paste branches on which one it was. A copy adjusts the input (relative references shift, `$`-anchored references stay fixed) and writes the adjusted text to the target. A cut skips adjustment entirely — it writes the raw text unchanged and clears the source as a single undoable move — because a move should preserve exactly what the formula pointed at. Every result recomputes through the single engine, so the grid matches Google Sheets.
+
+## Verified behavior
+
+_Matches Google Sheets:_ In Google Sheets, copying a formula and pasting it adjusts the formula's relative references by the row/column offset (copying "=A1+B1" from C1 to C3 yields "=A3+B3"), while $-anchored parts stay fixed ("=$A$1+B1" → "=$A$1+B3"); copy leaves the source and the clipboard intact, so it can be pasted again. Cutting and pasting instead MOVES the cell: the formula is written to the destination verbatim (no reference adjustment) and the source is cleared, and the clipboard is consumed after that one paste.
+
+#### Copy a relative formula and paste — references shift by the offset
+
+**Given**
+- **A1** = `10`
+- **B1** = `20`
+- **C1** = `=A1+B1`
+- **A3** = `5`
+- **B3** = `7`
+
+**When** I click **C1**, then press `Control+c`, then click **C3**, then press `Control+v`
+
+**Then**
+- **C3** shows `12`
+- **C1** shows `30`
+- **C3** has formula `=A3+B3`
+- **C1** has formula `=A1+B1`
+
+#### Copy shifts references by both the row and the column offset
+
+**Given**
+- **A1** = `10`
+- **B1** = `20`
+- **C1** = `=A1+B1`
+- **B3** = `7`
+- **C3** = `5`
+
+**When** I click **C1**, then press `Control+c`, then click **D3**, then press `Control+v`
+
+**Then**
+- **D3** shows `12`
+- **D3** has formula `=B3+C3`
+
+#### Cut and paste — the formula moves verbatim and the source is cleared
+
+**Given**
+- **A1** = `10`
+- **B1** = `20`
+- **C1** = `=A1+B1`
+
+**When** I click **C1**, then press `Control+x`, then click **C3**, then press `Control+v`
+
+**Then**
+- **C3** shows `30`
+- **C1** shows `null`
+- **C3** has formula `=A1+B1`

content/docs/learn/playground/edit.mdx

@@ -0,0 +1,64 @@
+---
+title: "Edit a cell"
+description: "Type into a cell to set a literal or a formula; the formula is stored and its computed value is shown."
+---
+
+## What it does
+
+Select a cell and start typing (or press **Enter**/**F2** to open the in-cell editor) to set its contents. A bare value — `42`, `hello` — is stored as a literal. A leading `=` makes it a **formula**: TrueCalc stores the formula text and shows the computed result. Press **Enter** to commit and move down, or **Escape** to cancel.
+
+## Try it
+
+<TrueCalc mode="standalone" seed="A1=10" />
+
+## How it works
+
+When you commit an edit, TrueCalc stores exactly what you typed. If it starts with `=` it is kept as the cell's formula and recomputed whenever a cell it depends on changes; otherwise it is stored as a literal. The same engine both keeps the formula text and computes the shown result, so editing behaves like Google Sheets.
+
+## Verified behavior
+
+_Matches Google Sheets:_ In Google Sheets, typing a bare number into a cell stores that literal and displays it. Typing a leading "=" makes the entry a formula: the cell stores the formula text and displays its computed result (e.g. with A1=10, entering "=A1*2" shows 20 while the formula bar still reads "=A1*2"). Typing into a non-empty cell replaces its prior contents — a literal overwrites a formula and vice-versa — and pressing Enter commits and moves the selection down.
+
+#### Typing a literal number displays that number
+
+**Given**
+
+
+**When** I type `42` into **A1**
+
+**Then**
+- **A1** shows `42`
+
+#### Typing a formula shows the computed value and stores the formula
+
+**Given**
+- **A1** = `10`
+
+**When** I type `=A1*2` into **A2**
+
+**Then**
+- **A2** shows `20`
+- **A2** has formula `=A1*2`
+
+#### Typing into a non-empty cell replaces its prior contents
+
+**Given**
+- **A1** = `10`
+- **A2** = `=A1*2`
+
+**When** I type `7` into **A2**
+
+**Then**
+- **A2** shows `7`
+
+#### A committed formula stores its text while displaying its result
+
+**Given**
+- **A1** = `10`
+- **B1** = `3`
+
+**When** I type `=A1*B1` into **C1**
+
+**Then**
+- **C1** shows `30`
+- **C1** has formula `=A1*B1`

content/docs/learn/playground/fill.mdx

@@ -0,0 +1,36 @@
+---
+title: "Fill a formula across cells"
+description: "Drag to extend a formula; references adjust automatically."
+---
+
+## What it does
+
+Drag the fill handle at the bottom-right of a selection (or press **Ctrl+D** to fill down, **Ctrl+R** to fill right) to extend a formula. Relative references shift automatically, and TrueCalc recomputes every filled cell.
+
+## Try it
+
+<TrueCalc mode="standalone" seed="A1=10;A2==A1+1" />
+
+## How it works
+
+TrueCalc owns the calc. Filling adjusts the formula **text** — relative references shift, `$`-anchored ones stay fixed — and recomputes through the single engine. There is no second engine to reconcile, which is exactly why fill behaves like Google Sheets here.
+
+## Verified behavior
+
+_Matches Google Sheets:_ In Google Sheets, filling "=A1+1" down from A2 yields "=A2+1", "=A3+1", "=A4+1" — relative references shift by row, producing a column of values.
+
+#### Filling a formula down adjusts relative references
+
+**Given**
+- **A1** = `10`
+- **A2** = `=A1+1`
+
+**When** I fill from **A2** to **A5**
+
+**Then**
+- **A3** shows `12`
+- **A4** shows `13`
+- **A5** shows `14`
+- **A3** has formula `=A2+1`
+- **A4** has formula `=A3+1`
+- **A5** has formula `=A4+1`

content/docs/learn/playground/format-bold.mdx

@@ -0,0 +1,40 @@
+---
+title: "Bold a cell"
+description: "Ctrl+B (or the toolbar Bold button) toggles bold on the selection."
+---
+
+## What it does
+
+Select cells and press **Ctrl+B** — or click the **Bold (B)** button in the toolbar — to toggle bold. Bold is **presentation**, separate from the cell's value: bolding `=A1+B1` styles the number without touching the formula. It undoes and redoes like any other edit.
+
+## Try it
+
+<TrueCalc mode="standalone" seed="A1=hello" />
+
+## How it works
+
+Bold is stored alongside the cell's value and rides the same undo/redo history, but it never reaches the calc engine — TrueCalc still owns the value; formatting is pure presentation. It is the foundation for the rest of the formatting toolbar (italic, font, color, borders, alignment, merge…), which add more attributes along the same edit and render path.
+
+## Verified behavior
+
+_Matches Google Sheets:_ In Google Sheets, Ctrl+B toggles bold on the selected cells. Bold is a presentation attribute independent of the cell's value or formula, and it undoes/redoes like any edit. Toggling again removes it.
+
+#### Ctrl+B bolds the selected cell
+
+**Given**
+- **A1** = `hello`
+
+**When** I click **A1**, then press `Control+b`
+
+**Then**
+- **A1** is bold
+
+#### Ctrl+B a second time removes bold
+
+**Given**
+- **A1** = `hello`
+
+**When** I click **A1**, then press `Control+b`, then press `Control+b`
+
+**Then**
+- **A1** is bold=false

content/docs/learn/playground/index.mdx

@@ -0,0 +1,19 @@
+---
+title: Playground features
+description: Try TrueCalc's interactive spreadsheet — editing cells, filling formulas, copy and paste, undo/redo, and formatting — live in the browser.
+---
+
+The **playground** is a full interactive spreadsheet running on TrueCalc. Each
+page in this section explains one editing feature, then lets you try it live in
+an embedded grid — no install, no sign-up.
+
+- **[Edit a cell](/learn/playground/edit)** — type a value or a formula.
+- **[Fill a formula across cells](/learn/playground/fill)** — extend a formula; references adjust.
+- **[Copy, cut, and paste](/learn/playground/clipboard)** — move and duplicate cells.
+- **[Undo and redo edits](/learn/playground/undo)** — step backward and forward.
+- **[Bold a cell](/learn/playground/format-bold)** — toggle presentation formatting.
+
+Every grid you see below is the live playground, seeded with a starting layout
+so you can reproduce the described behavior yourself.
+
+<TrueCalc mode="standalone" seed="A1=10;B1=5;C1==A1*B1" />

content/docs/learn/playground/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Playground",
+  "pages": ["index", "edit", "fill", "clipboard", "undo", "format-bold"]
+}

content/docs/learn/playground/undo.mdx

@@ -0,0 +1,41 @@
+---
+title: "Undo and redo edits"
+description: "Ctrl+Z reverts the last change; Ctrl+Y (or Ctrl+Shift+Z) re-applies it."
+---
+
+## What it does
+
+Every edit — typing a value, filling, pasting, clearing — is one undoable step. Press **Ctrl+Z** to revert the last step and **Ctrl+Y** (or **Ctrl+Shift+Z**) to re-apply it. A fresh edit after undoing clears the redo history, exactly like Google Sheets.
+
+## Try it
+
+<TrueCalc mode="standalone" seed="A1=10" />
+
+## How it works
+
+Each edit records how to reverse it and how to re-apply it, so undo and redo simply replay the recorded step and recompute the affected cells through TrueCalc. Undo and redo act on whole edits rather than individual keystrokes, and a fresh edit after undoing discards the redo history.
+
+## Verified behavior
+
+_Matches Google Sheets:_ In Google Sheets, Ctrl+Z undoes the last edit — restoring the cell's prior contents — and Ctrl+Y (or Ctrl+Shift+Z) redoes it. Undo/redo apply to whole edits, not keystrokes, and a new edit clears the redo stack.
+
+#### Ctrl+Z reverts an edit
+
+**Given**
+- **A1** = `10`
+
+**When** I type `=A1*2` into **A2**, then press `Control+z`
+
+**Then**
+- **A2** shows `null`
+
+#### Ctrl+Y re-applies an undone edit
+
+**Given**
+- **A1** = `10`
+
+**When** I type `=A1*2` into **A2**, then press `Control+z`, then press `Control+y`
+
+**Then**
+- **A2** shows `20`
+- **A2** has formula `=A1*2`