SPB Git

Repository Public

EDITOR.md 24.5 KB 328 lines markdown

1# The studio and the editor23What the administrator sees and can do, described from the components. Code: `src/components/admin/` (shell, pages, creation assistant), `src/components/editor/` (editor, panels, block forms, diagram editor).45Parts of the editor were still being edited while this document was written (see the note at the end). The interface is in French or English, following the site's language switch; labels below are the English ones.67## 1. Studio shell89`src/components/admin/shell.tsx`. A sidebar on desktop and a six-item bottom bar on phones: dashboard, new sheet, templates, media & data, revisions & audit, settings. Every studio page sits behind a server-side session check (`src/app/admin/(studio)/layout.tsx`); a recovery-code session is sent to `/admin/setup`.1011| Page | Route | Component | What it does |12|---|---|---|---|13| Dashboard | `/admin` | `pages/dashboard.tsx` | Counts by status, views (7 and 30 days, most viewed), service health tiles (database, Claude API, job queue and worker, storage, antivirus), AI spend against budgets, the sheet list with search and status filter, JSON import |14| New sheet | `/admin/sheets/new` | `new-sheet.tsx` | Creation assistant (§2) |15| Editor | `/admin/sheets/<id>/edit` | `editor/Editor.tsx` | §3 onwards |16| Templates | `/admin/templates` | `pages/templates.tsx` | 12 built-in templates by category with preview in either language, the author's own templates, "use this template", delete own template |17| Media & data | `/admin/assets` | `pages/assets.tsx` | Drag-and-drop upload queue, quota bar, filter by kind, edit alt / credit / licence, view dataset rows, copy id, download, delete |18| Revisions & audit | `/admin/revisions` | `pages/revisions.tsx` | Revision history of a sheet with restore (as a new revision), and the audit trail |19| Settings | `/admin/settings` | `pages/settings.tsx` | Passkeys (add this device, rename, remove), recovery codes, active sessions, Claude (model from the live list, efforts, output cap, budgets, jobs per hour, job time limit), site (view counter), topics |2021JSON import (dashboard): the file is checked with `POST /api/admin/validate` (2 MB at most), the dialog shows its title, block count and language, and the sheet is created as a draft. Image blocks and chart dataset links are removed on import because files do not travel with the JSON (chart points are kept).2223## 2. Creation assistant2425`src/components/admin/new-sheet.tsx`. Two steps.2627**Brief.** A request (8–6 000 characters), language of the sheet, level, kind, length, format and style. Under "Options": audience, constraints, material to read (up to 8 uploaded files: PDF, text, Markdown, CSV, JSON, images) and links to read (one per line, 5 at most, https). Two actions:2829- **Propose a plan** starts an `outline` job.30- **Generate without a plan** starts a `generate` job directly.3132Other starting points on the same page: a template, or an empty sheet.3334**Proposed plan.** The outline is editable: title, summary, objectives, each section's heading and purpose (sections can be removed), the visual plan. Planned block types per section, the references the model is considering (labelled "in your material" or "from memory — to be checked") and its open questions are shown read-only. Warnings appear when the supplied material contains text addressed to an AI. A line gives the cost of the plan and an estimate for the draft. Actions: **Generate the sheet**, **Redo the plan**, **Edit the request**.3536While a job runs, a progress card shows the stage, characters received, the model, the actual cost so far, the attempt number, and a **Cancel** button. When the generation succeeds the browser opens the editor on the new draft. The job lives on the server: closing the page does not stop it.3738Without `ANTHROPIC_API_KEY`, the page says generation is not configured and only templates and empty sheets are available.3940## 3. Editor layout4142`src/components/editor/Editor.tsx`. Full-height page with a top bar, the canvas, and panels.4344### Top bar4546Back to the dashboard · title · status pill, "Unpublished changes" hint and save state · undo · redo · preview width (Desktop / Tablet 820 px / iPhone 390 px; large screens only) · **Save** · **Preview** · **Publish** (or **Publish changes**) · **⋯ More**.4748Save states: Saved, Unsaved changes, Saving…, Invalid document — not saved (with the first schema issues), a version conflict banner with **Reload**, or the server's error message.4950### Desktop (≥ 1024 px)5152```53┌────────────┬──────────────────────────────────────┬──────────────────────┐54│ Blocks     │                                      │ Properties │ Claude  │55│ Outline    │             canvas                   │ Quality │ Sources    │56│ (288 px)   │   (the sheet, rendered for real)     │ Sheet     (360 px)   │57└────────────┴──────────────────────────────────────┴──────────────────────┘58```5960- Left: **Blocks** (the library) and **Outline** tabs.61- Right: **Properties**, **Claude**, **Quality** (with an error/warning count badge), **Sources**, **Sheet**.6263### Tablet (768–1023 px)6465Canvas and the right panel. The left column appears only from 1024 px, so at this width **Blocks** and **Outline** are two extra tabs at the start of the right panel's tab row.6667### Phone (< 768 px)6869The canvas takes the screen. A fixed bar above the home indicator holds **Save / Preview / Publish** (below 640 px, where the top bar hides them) and six tabs: Blocks, Outline, Properties, Claude, Quality, Sheet. A tab opens a bottom drawer (45–82 % of the height) whose header lists all seven panels, Sources included. Adding a block or jumping from the quality report closes the drawer.7071## 4. Canvas7273The canvas renders the sheet with the same `SheetView` as the public site, in `editor` mode, at the chosen preview width or at the format's own width. Each top-level block is wrapped with selection chrome.7475| Action | How |76|---|---|77| Select a block | Click it. Links inside the sheet are inert in the editor. A hidden "Select the … block" button makes each block reachable by keyboard. |78| Add to the selection | Shift-, ⌘- or Ctrl-click (also in the outline) |79| Deselect | Click the canvas background, or Escape |80| Edit text in place | Double-click a heading or paragraph (or the ✎ tool). A text area shows the raw inline syntax. Enter confirms a heading; ⌘/Ctrl + Enter confirms a paragraph; Escape cancels; leaving the field confirms. Not available on a locked block. |81| Open the diagram editor | Double-click a diagram, or the ◇ tool, or the button in its property form |82| Add a block | Pick it in the library: it is inserted after the last selected block, or at the end, selected and scrolled into view. An image block first opens the asset picker; cancelling it adds nothing. |83| Move | ▲ / ▼ in the block toolbar or the outline; ⌥↑ / ⌥↓ |84| Duplicate | ⧉ or ⌘D. The copy gets new ids. Refused at 80 blocks. |85| Lock / unlock | 🔓 / 🔒. A locked block cannot be moved or deleted and is never touched by AI edits. |86| Ask Claude | ✦ opens the Claude panel with the block as the selection |87| Delete | ✕, Delete or Backspace |8889The toolbar appears above a block when exactly one is selected. With several blocks selected the Properties panel offers Duplicate and Delete for the group.9091Limits of the canvas as coded:9293- Selection chrome and the toolbar exist for top-level blocks. A block inside a `tabs` block is edited through the tabs form (it drills into the child), not by clicking it on the canvas.94- Deletion works at any depth (`removeBlocks`): removing a tab group removes its children, a tab never ends up empty (its last block stays), and claims that pointed at a removed block keep their text and lose the link.95- There is no drag-and-drop reordering on the canvas; order is changed with the arrows.9697### Document state9899`src/components/editor/state.ts`. The working copy plus an undo/redo history of whole documents (100 steps). Edits on the same field within 1.2 s coalesce into one step. A document that arrives from the server (after an AI edit, a source check or a revert) becomes a new undoable step.100101**Autosave**: 2.5 s after the last change, and on ⌘S. The document is validated in the browser first; an invalid document is not sent. Saves are serialised (one at a time) and carry the version the editor last saw; a conflict stops autosave. Leaving the page with unsaved changes triggers the browser's confirmation.102103For fixed formats the editor measures the rendered frame and reports by how many pixels the content exceeds the page (shown in the Quality panel).104105## 5. Block library and outline106107**Library** (`LibraryPanel`): the 23 block types in five groups.108109| Group | Types |110|---|---|111| Text | heading, paragraph, list, callout, equation, code, references |112| Structure | divider, cards, steps, timeline, comparison, accordion, tabs |113| Visual | legend, diagram, SVG illustration, image |114| Data | table, chart, matrix |115| Interactive | quiz, simulation |116117Each new block comes with valid starter content in the sheet's language (`forms/defaults.ts`).118119**Outline** (`OutlinePanel`): top-level blocks in order with their type, a text excerpt and the locked mark; click to select and scroll, ▲ / ▼ to move.120121## 6. Property forms122123`src/components/editor/forms/`. One form per block type (`FORMS` in `BlockForm.tsx`; a missing type is a compile error).124125How forms behave:126127- A field commits on blur, Enter (single-line), ⌘/Ctrl + Enter (multi-line), or on toggle/select.128- Every edit goes through `checkBlock`: optional empty values are dropped, simulation sliders are brought back to the ones the kind defines, then the block must pass the schema (and the simulation's own checks). Only a valid block reaches the document.129- An edit that is not valid yet stays in the form with the reason under the field and a "not saved" notice, until it is fixed.130- In code fields, Tab inserts two spaces; Escape then Tab leaves the field.131132Common section, under every form: width on the grid (¼, ⅓, ½, ⅔, full), text alternative (required and highlighted for diagram, chart, matrix, SVG, image and simulation), sources (chips from the sheet's sources, up to 12), locked.133134| File | Forms | Notable features |135|---|---|---|136| `forms-text.tsx` | heading, paragraph, list, callout, divider, references, code, equation | equation: LaTeX, label, explanation, variables, derivation status |137| `forms-lists.tsx` | cards, steps, legend, timeline, accordion, comparison, quiz, table, tabs | table: add / remove / move columns and rows, paste from a spreadsheet; tabs: manage tabs and drill into a child block's own form |138| `forms-data.tsx` | chart, matrix, simulation | chart: data kind with a one-line explanation, axes, series, points grid with paste, build series from an uploaded dataset; matrix: grid with paste; simulation: kind, config and sliders from the registry |139| `forms-visual.tsx` | diagram, SVG, image | diagram: settings, nodes, edges, groups, and the button to the visual editor; SVG: paste markup or choose a file, sanitised by the server, with the list of what was removed; image: pick or upload a picture |140141Pasting tab-, semicolon- or comma-separated cells fills tables, matrices and chart points; rows or columns beyond the schema limits are dropped and the form says how many.142143**Asset picker** (`AssetPicker` in `Editor.tsx`): lists uploaded images, or CSV/JSON files that parsed as a table; uploads a new file in place. Choosing an asset adds an entry to the document's `assets` (once per file) and returns its local id to the form.144145## 7. Visual diagram editor146147`src/components/editor/diagram/`. Opens full screen over the editor. The canvas draws with the reader's own layout engine and SVG component, so what is edited is what is published. Every committed change is validated against the block schema and handed to the editor as one undo step; the diagram editor also keeps its own history (200 steps).148149Layout: toolbar on top; on desktop, layers on the left, canvas in the middle, properties / steps on the right. On phones the canvas is full width, a two-row bottom bar holds the tools, and the panels are bottom drawers.150151### Tools and gestures (`Canvas.tsx`)152153| Tool | Pointer behaviour |154|---|---|155| Select (V) | Click a node or an edge to select it; Shift-click or the multi-select toggle adds; drag a node to move the selected nodes (with a live preview, snapped to the 8 px grid when snap is on); drag on empty space draws a marquee (nodes it touches, edges it contains); drag the handle to the right of a single selected node to draw an edge |156| Pan (H) | Drag to pan. The middle mouse button pans with any tool. |157| Connect (C) | Drag from a node to another node to create an edge |158| Step pick | Entered from the Steps panel: tap nodes and edges to toggle them in the current animation step |159160Zoom: mouse wheel or ⌘/Ctrl + wheel about the pointer, trackpad pinch, two-finger pinch on touch screens, the − / % / + buttons (the percentage resets to actual size), **Fit**. A two-finger trackpad scroll pans. Touch targets are widened to 44 px whatever the zoom.161162Refusals are explained in a message bar: self-loops, duplicate edges, the limits (60 nodes, 120 edges, 12 groups), moving or deleting locked nodes, deleting the last node.163164A node moved by hand gets manual `x`/`y`; nodes without them stay under the layout engine. **Auto-place** clears the manual position of the selected nodes (or of all nodes).165166### Panels (`panels.tsx`)167168- **Layers**: nodes and edges in paint order; select, reorder (up / down).169- **Properties**, depending on the selection:170  - nothing selected — diagram settings (kind, direction, routing, title, caption, text alternative), groups (rename, tone, delete), legend entries;171  - one node — label, sublabel, shape, tone, icon, group, exact position, lock, connect to another node, duplicate, delete;172  - several nodes — align (left, centre, right, top, middle, bottom), distribute (horizontally, vertically), create a group, lock;173  - one edge — label, style, arrow, tone, ports, reverse, delete.174- **Steps**: add, rename, describe, reorder and remove animation steps; preview a step on the canvas; "Pick on the canvas". The first "add" creates two steps because the schema needs at least two; removing down to one removes the animation.175176The layers list and the property panel together are a complete keyboard path: everything the canvas does with a pointer can be done from them.177178## 8. Claude panel179180`ClaudePanel` in `src/components/editor/panels.tsx`. A conversation per sheet.1811821. Type a request (2–4 000 characters); five examples are offered. ⌘/Ctrl + Enter sends.1832. If blocks are selected, a checkbox "Limit to the N selected block(s)" (on by default) sends them as the scope.1843. Pending edits are saved first; the request carries the saved version.1854. A progress card follows the job (with **Cancel**).1865. On success the editor reloads the sheet from the server, the added and changed blocks are outlined for four seconds, and the assistant's summary appears with the revision number and a diff summary (added / changed / removed / moved, metadata, theme, sources).187188Per answer: **Show** highlights the blocks again; **Undo this change** restores the revision that preceded it (as a new revision). An answer without a change says "No change applied". The cost of the last job is shown under the form.189190Only one edit, translation or source check can run on a sheet at a time. Without an API key the panel shows "Claude is not configured on this server".191192What the model can and cannot change is described in [AI_PIPELINE.md](AI_PIPELINE.md).193194## 9. Quality report195196`QualityPanel`; computed by `src/server/quality.ts` on every save, on unsaved changes (debounced 0.9 s) and at publication.197198The panel shows the counts (blocking errors, warnings, notes), statistics (blocks, words, sources checked, unverified claims), the measured overflow for fixed formats, and the list of items. An item attached to a block is a button that selects it and scrolls to it.199200The panel states what the report is: automatic checks of structure, syntax, references and accessibility fields — not a scientific validation.201202| Severity | Checks |203|---|---|204| Error (blocks publication) | no level-1 heading; a citation `[^id]` without a matching source; invalid inline or display LaTeX, invalid variable symbol; missing text alternative on diagram, chart, matrix, SVG, image; chart or matrix of empirical data without a source; non-numeric x on a numeric axis; non-positive value on a log scale; interval that does not contain its value; any simulation problem (unknown kind, option or parameter, value out of bounds, expression that does not parse); a claim marked "sourced" without a source |205| Warning | several level-1 headings; no paragraph among the first four blocks; no objective; no summary; no topic; a link that is not https/mailto; heading over 90 characters; equation without variable definitions; unverified derivation; diagram arrows with neither labels nor legend; node label over 40 characters; more than 24 nodes; non-empirical chart without a caption; table wider than 5 columns; simulation without a text description; no source at all; unverified or unreachable source; sources without a references block; unverified claim |206| Note | example banner on; unconnected diagram node; chart without units; code line over 100 characters; source without DOI or URL; source never cited |207208## 10. Sources panel209210`SourcesPanel`. Each source is a card: number and id, status pill (Unverified, Found, Reviewed, Unreachable), and fields for title, authors, year, type, journal/publisher, DOI and URL. A DOI pasted as a `doi.org` link is reduced to the DOI; an invalid DOI or a non-https URL is refused and the previous value restored.211212- **Add a source** appends an article with a placeholder title (60 at most).213- **Mark as reviewed** sets the status the server never sets by itself.214- Changing the title, DOI or URL of a source that is not "reviewed" resets it to "unverified".215- **Remove** also removes the source from claims and from top-level blocks' source lists.216- **Check the sources** saves, then starts a `verify_sources` job; the per-source verdicts are listed when it finishes and the sheet is reloaded with the new statuses.217218Below the sources, the sheet's claims are listed with a selector for their status (sourced, derived, unverified) and their source ids. Claims cannot be created or reworded here.219220## 11. Sheet panel221222`MetaPanel`. Two parts.223224**Document fields** (part of the document, saved with it, undoable): title, summary, topics and tags (comma-separated), level, kind, learning objectives (one per line), style (theme preset), accent, format, and the "unreviewed example" banner.225226**Publication settings** (not part of the document; saved with their own button): address (slug; if the sheet has been public the old address will redirect), status (Draft, In review, Archived — hidden while published), SEO title and description, canonical URL (https), featured and its order, and whether readers may download the PDF.227228There is no field for the sharing image in this panel; the API accepts `ogAssetId`, and without it the generated Open Graph image is used.229230## 12. Publication, preview and the "More" menu231232**Publish dialog.** States that the current version becomes public at the shown address (the browser's own host followed by `/s/<slug>`) and does not change until the next publication. Lists blocking errors (publication disabled) or open warnings. Requires ticking "I have reviewed this sheet (content, formulas, sources) and authorise its publication." **Publish now** saves, then publishes that exact version; the server re-runs the quality report and refuses on errors or if the version moved. On success a link opens the public page.233234**More menu.**235236| Entry | What it does |237|---|---|238| Private preview link | Creates a 24-hour, non-indexable link to the current draft (saved first), images included; copy or open it; **Revoke links** revokes every link of the sheet |239| Export | §13 |240| Translate | Starts a translation into the other language as a new linked sheet; when a translation exists, offers to open it |241| Save as template | Saves the current sheet as one of the author's templates under a name |242| Revision history | Opens the revisions page |243| View the public page / Unpublish | When published. Unpublishing makes the sheet a draft again; the page, the API, the sitemap and the feeds stop listing it. |244| Delete the sheet | When not published. Soft delete: the sheet leaves the studio, its revisions are kept. |245246## 13. Exports247248The export dialog saves first, then requests an export of the current revision and polls until the file is ready, then offers the download.249250| Format | Scope | Notes |251|---|---|---|252| Vector PDF | whole sheet only (a PDF of one block is refused: `whole_sheet_only`) | fixed formats: one page of the format's size; article: A4 pages with a footer and page numbers |253| PNG | whole sheet | scale 1×, 2× or 4×; refused beyond 16 000 px a side |254| SVG | the selected block | only for diagram, chart, matrix, timeline and SVG illustration; standalone file with colours resolved and fonts embedded |255| Sheet JSON | whole sheet | direct download of the document with sorted keys; uploads are referenced by id and do not travel with the file |256257Interactive blocks are captured in their initial state. There is no whole-sheet SVG. Studio export files are removed after seven days.258259## 14. Keyboard shortcuts260261Collected from the code. ⌘ also means Ctrl.262263### Editor (`Editor.tsx`)264265Inactive while typing in a field (except save), while a dialog is open, and while the diagram editor is open.266267| Keys | Action |268|---|---|269| ⌘S | Save now (works everywhere, including in fields) |270| ⌘Z | Undo |271| ⇧⌘Z or ⌘Y | Redo |272| ⌘D | Duplicate the selected blocks |273| Delete or Backspace | Delete the selected blocks |274| ⌥↑ / ⌥↓ | Move the selected block up / down (single selection) |275| Escape | Clear the selection, leave in-place editing |276277In-place text: Enter confirms a heading; ⌘Enter confirms a paragraph; Escape cancels.278279### Diagram editor (`DiagramEditor.tsx`)280281Inactive while typing in a field.282283| Keys | Action |284|---|---|285| V / H / C | Select / pan / connect tool |286| G | Group the selected nodes, or ungroup them when they share a group |287| Delete or Backspace | Delete the selection |288| ⌘D | Duplicate the selected nodes |289| ⌘A | Select everything |290| ⌘Z, ⇧⌘Z, ⌘Y | Undo, redo |291| Arrows | Nudge the selected nodes by 8 px (Shift: 1 px) |292| + or = / − | Zoom in / out |293| 0 | Fit to the view |294| Escape | Clear the selection, close the shortcut list, leave step picking, close a drawer |295296A keyboard icon in the toolbar shows this list in the editor.297298### Forms and panels299300| Where | Keys | Action |301|---|---|---|302| Single-line field | Enter | Commit |303| Multi-line field | ⌘Enter | Commit |304| Code field | Tab; Escape then Tab | Insert two spaces; leave the field |305| Diagram panel fields | Enter / ⌘Enter; Escape | Commit; restore the committed value |306| Claude request | ⌘Enter | Send |307| Dialogs | Escape | Close (native `<dialog>`) |308309### Reader-facing blocks (also live in the editor)310311| Block | Keys |312|---|---|313| Tabs | ←/↑ and →/↓ change tab; Home / End go to the first / last |314| Diagram (full screen) | Escape leaves full screen |315316## 15. Not offered317318- No offline editing: the service worker never caches pages or API responses, and the studio needs the network.319- No collaborative or multi-user editing. Two tabs on the same sheet are detected by the version check; the second save is refused and the tab must reload.320- No comments, no review workflow beyond the "In review" label.321- No scheduled publication.322- No drag-and-drop block reordering, no canvas selection of blocks nested in tabs.323- No image editing; images are used as uploaded.324325---326327Note on the state of the code: the editor changed several times while this document was written; it was last brought in line after the changes to `Editor.tsx`, `state.ts` and `panels.tsx` (image picker on insert, tablet tabs, deletion at any depth, host taken from the browser). `Editor.tsx` and `panels.tsx` were modified after the first reading and re-checked (layout breakpoints, shortcuts, dialogs); the files in `src/components/editor/forms/` (`BlockForm.tsx`, `forms-data.tsx`, `forms-lists.tsx`, `primitives.tsx`, `strings.ts`) had modification times a few minutes old when section 6 was written. If the interface and this document disagree, the code is right.328
Files main
Menu

Theme