From ee26fdb20bcb7e88ae128c5e992b6ddf06b729ef Mon Sep 17 00:00:00 2001
From: tannevaled <tannevaled@users.noreply.github.com>
Date: Thu, 22 Oct 2026 19:49:04 +0200
Subject: [PATCH] Playground: the file panel (themes, kinds, data files, media,
 .zip)

The Playground page describes the project panel of
go-slides/go-slides.github.io#32: files in the slides command's layout,
New theme / New kind / New data file, media in media/ instead of data:
URIs, Download and Open project (.zip or folder) and its bounds, Share
with a project, and how media reach the sandboxed preview.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 content/en/playground.md | 53 +++++++++++++++++++++++++++++++++-------
 1 file changed, 44 insertions(+), 9 deletions(-)

diff --git a/content/en/playground.md b/content/en/playground.md
index 48dd3b2..0b46c7b 100644
--- a/content/en/playground.md
+++ b/content/en/playground.md
@@ -35,15 +35,41 @@ right. Nothing is sent to a server: not the deck, not a share link.
 - **Examples**: a welcome deck, templates that generate slides, slide kinds,
   an HCL front matter, themes and spot directives, and math, images and
   backgrounds (`![bg]`, a split `![bg left:40%]`, filters).
-- **Images**: drop or paste an image file (PNG, JPEG, GIF, WebP or SVG, up
-  to 256 KiB) into the editor and it goes into the deck as a `data:` URI. It
-  travels with the deck and nothing is uploaded. `https:` images work too,
-  but the browser fetches them from their server, which then sees your
-  address. The preview sends no referrer.
+- **Files**: the panel left of the editor is the deck's project, laid out
+  the way the [command]({{< relref "cli" >}}) and the
+  [VS Code extension]({{< relref "vscode" >}}) read it: `deck.md`,
+  `slides.yaml`, `themes/`, `kinds/`, `media/`.
+  - Click a file to edit it. The editor colours it by its language
+    (Markdown, YAML, HCL, JSON, CSS) and marks its problems.
+  - Right-click (or Shift+F10) for New File, New Folder, Rename (F2),
+    Delete (asks first) and New theme / New kind. Drag a file onto a folder
+    to move it. The keyboard follows the WAI-ARIA tree pattern, type-ahead
+    included.
+  - **Project ▸ New theme** makes `themes/my-gaia.css` (or from default,
+    uncover): `@import` of the built-in theme and the rules you add. It
+    joins the Theme list. **New kind** and **New data file** start from
+    templates too. Each is listed in `slides.yaml`, so `slides build deck.md`
+    finds it.
+  - **Project ▸ Download project (.zip)** saves it all. Unzipped,
+    `slides build deck.md` builds it. **Open project** takes a `.zip` or a
+    folder back. An archive that leaves its folder (`..`, absolute paths),
+    holds more than 256 files or 8 MiB in a file, or inflates more than 100
+    times is refused.
+  - Everything is kept in this browser with the draft. A project holds up
+    to 64 MiB, and the line under the files says how much is used.
+- **Media**: drop or paste an image, a video or a sound on the editor and it
+  goes into `media/`, and the deck names it: `![](media/photo.png)`. Drop
+  files on a folder of the panel to put them there. The deck stays small and
+  readable, and nothing is uploaded. The preview's sandbox loads them
+  without being opened up (the page hands it the bytes). **Save as ▸ HTML
+  page** puts them in the page. `https:` images work too, but the browser
+  fetches them from their server, which then sees your address. The
+  preview sends no referrer.
 - **Highlighting** of the front matter's keys at any depth, in YAML (also
   in `{a: 1}` mappings) and in HCL.
-- **Theme** picker: default, gaia, uncover, and the themes the deck defines
-  (`/* @theme name */` in a `<style>`). It writes `theme:` into the front
+- **Theme** picker: default, gaia, uncover, the project's themes
+  (`themes/*.css`) and the themes the deck defines (`/* @theme name */` in a
+  `<style>`). It writes `theme:` into the front
   matter, YAML or HCL, so a shared link keeps it, and it follows the front
   matter when you edit it.
 - The preview **keeps its place** as you type: only the slides that
@@ -51,8 +77,8 @@ right. Nothing is sent to a server: not the deck, not a share link.
   same slide.
 - **Share link**: the deck travels in the link itself (in its `#` part,
   compressed), so opening the link opens the deck. Links carry up to
-  64 KiB compressed, so a deck with images is shared as a download
-  instead.
+  64 KiB compressed, and the deck only: when the project holds more
+  (themes, kinds, media), Share says so and offers the `.zip`.
 - **Save as**:
   - the HTML page, the same as `slides deck.md` writes;
   - a **PDF** (vector, its text selectable, with the outline);
@@ -75,6 +101,10 @@ right. Nothing is sent to a server: not the deck, not a share link.
     back.
   - **Draft ▸ Forget my drafts** erases everything stored.
 
+The PDF, PowerPoint and OpenDocument exports render the deck alone for now,
+without the project's themes, kinds and media: for those, download the
+project and use the command.
+
 Images as files (slides `--images`) are not made in the browser: use the
 [command]({{< relref "cli" >}}) or the
 [VS Code extension]({{< relref "vscode" >}}).
@@ -94,6 +124,11 @@ iframes cannot share storage, so the playground relays the slide number
 between them in messages. No frame that runs the deck gets the
 playground's origin.
 
+The project's media reach the sandboxed frames as bytes in a message, and
+each frame makes its own `blob:` URLs of them, in its own origin. A `blob:`
+URL made by the playground does not load there, and the frames' policy
+gains only `blob:` for media and fonts.
+
 ## Size and speed
 
 The module is 8.8 MiB as GitHub Pages serves it (gzip; Pages does not