SPB Git

Repository Public

EDITOR.md 24.5 KB

# The studio and the editor

What 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).

Parts 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.

# 1. Studio shell

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.

Page Route Component What it does
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
New sheet /admin/sheets/new new-sheet.tsx Creation assistant (§2)
Editor /admin/sheets/<id>/edit editor/Editor.tsx §3 onwards
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
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
Revisions & audit /admin/revisions pages/revisions.tsx Revision history of a sheet with restore (as a new revision), and the audit trail
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

JSON 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).

# 2. Creation assistant

src/components/admin/new-sheet.tsx. Two steps.

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:

  • Propose a plan starts an outline job.
  • Generate without a plan starts a generate job directly.

Other starting points on the same page: a template, or an empty sheet.

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.

While 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.

Without ANTHROPIC_API_KEY, the page says generation is not configured and only templates and empty sheets are available.

# 3. Editor layout

src/components/editor/Editor.tsx. Full-height page with a top bar, the canvas, and panels.

# Top bar

Back 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.

Save 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.

# Desktop (≥ 1024 px)

text
┌────────────┬──────────────────────────────────────┬──────────────────────┐
│ Blocks     │                                      │ Properties │ Claude  │
│ Outline    │             canvas                   │ Quality │ Sources    │
│ (288 px)   │   (the sheet, rendered for real)     │ Sheet     (360 px)   │
└────────────┴──────────────────────────────────────┴──────────────────────┘
  • Left: Blocks (the library) and Outline tabs.
  • Right: Properties, Claude, Quality (with an error/warning count badge), Sources, Sheet.

# Tablet (768–1023 px)

Canvas 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.

# Phone (< 768 px)

The 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.

# 4. Canvas

The 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.

Action How
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.
Add to the selection Shift-, ⌘- or Ctrl-click (also in the outline)
Deselect Click the canvas background, or Escape
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.
Open the diagram editor Double-click a diagram, or the ◇ tool, or the button in its property form
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.
Move ▲ / ▼ in the block toolbar or the outline; ⌥↑ / ⌥↓
Duplicate ⧉ or ⌘D. The copy gets new ids. Refused at 80 blocks.
Lock / unlock 🔓 / 🔒. A locked block cannot be moved or deleted and is never touched by AI edits.
Ask Claude ✦ opens the Claude panel with the block as the selection
Delete ✕, Delete or Backspace

The toolbar appears above a block when exactly one is selected. With several blocks selected the Properties panel offers Duplicate and Delete for the group.

Limits of the canvas as coded:

  • 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.
  • 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.
  • There is no drag-and-drop reordering on the canvas; order is changed with the arrows.

# Document state

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.

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.

For fixed formats the editor measures the rendered frame and reports by how many pixels the content exceeds the page (shown in the Quality panel).

# 5. Block library and outline

Library (LibraryPanel): the 23 block types in five groups.

Group Types
Text heading, paragraph, list, callout, equation, code, references
Structure divider, cards, steps, timeline, comparison, accordion, tabs
Visual legend, diagram, SVG illustration, image
Data table, chart, matrix
Interactive quiz, simulation

Each new block comes with valid starter content in the sheet's language (forms/defaults.ts).

Outline (OutlinePanel): top-level blocks in order with their type, a text excerpt and the locked mark; click to select and scroll, ▲ / ▼ to move.

# 6. Property forms

src/components/editor/forms/. One form per block type (FORMS in BlockForm.tsx; a missing type is a compile error).

How forms behave:

  • A field commits on blur, Enter (single-line), ⌘/Ctrl + Enter (multi-line), or on toggle/select.
  • 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.
  • 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.
  • In code fields, Tab inserts two spaces; Escape then Tab leaves the field.

Common 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.

File Forms Notable features
forms-text.tsx heading, paragraph, list, callout, divider, references, code, equation equation: LaTeX, label, explanation, variables, derivation status
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
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
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

Pasting 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.

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.

# 7. Visual diagram editor

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).

Layout: 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.

# Tools and gestures (Canvas.tsx)

Tool Pointer behaviour
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
Pan (H) Drag to pan. The middle mouse button pans with any tool.
Connect (C) Drag from a node to another node to create an edge
Step pick Entered from the Steps panel: tap nodes and edges to toggle them in the current animation step

Zoom: 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.

Refusals 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.

A 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).

# Panels (panels.tsx)

  • Layers: nodes and edges in paint order; select, reorder (up / down).
  • Properties, depending on the selection:
    • nothing selected — diagram settings (kind, direction, routing, title, caption, text alternative), groups (rename, tone, delete), legend entries;
    • one node — label, sublabel, shape, tone, icon, group, exact position, lock, connect to another node, duplicate, delete;
    • several nodes — align (left, centre, right, top, middle, bottom), distribute (horizontally, vertically), create a group, lock;
    • one edge — label, style, arrow, tone, ports, reverse, delete.
  • 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.

The layers list and the property panel together are a complete keyboard path: everything the canvas does with a pointer can be done from them.

# 8. Claude panel

ClaudePanel in src/components/editor/panels.tsx. A conversation per sheet.

  1. Type a request (2–4 000 characters); five examples are offered. ⌘/Ctrl + Enter sends.
  2. If blocks are selected, a checkbox "Limit to the N selected block(s)" (on by default) sends them as the scope.
  3. Pending edits are saved first; the request carries the saved version.
  4. A progress card follows the job (with Cancel).
  5. 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).

Per 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.

Only 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".

What the model can and cannot change is described in AI_PIPELINE.md.

# 9. Quality report

QualityPanel; computed by src/server/quality.ts on every save, on unsaved changes (debounced 0.9 s) and at publication.

The 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.

The panel states what the report is: automatic checks of structure, syntax, references and accessibility fields — not a scientific validation.

Severity Checks
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
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
Note example banner on; unconnected diagram node; chart without units; code line over 100 characters; source without DOI or URL; source never cited

# 10. Sources panel

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.

  • Add a source appends an article with a placeholder title (60 at most).
  • Mark as reviewed sets the status the server never sets by itself.
  • Changing the title, DOI or URL of a source that is not "reviewed" resets it to "unverified".
  • Remove also removes the source from claims and from top-level blocks' source lists.
  • 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.

Below 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.

# 11. Sheet panel

MetaPanel. Two parts.

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.

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.

There is no field for the sharing image in this panel; the API accepts ogAssetId, and without it the generated Open Graph image is used.

# 12. Publication, preview and the "More" menu

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.

More menu.

Entry What it does
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
Export §13
Translate Starts a translation into the other language as a new linked sheet; when a translation exists, offers to open it
Save as template Saves the current sheet as one of the author's templates under a name
Revision history Opens the revisions page
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.
Delete the sheet When not published. Soft delete: the sheet leaves the studio, its revisions are kept.

# 13. Exports

The export dialog saves first, then requests an export of the current revision and polls until the file is ready, then offers the download.

Format Scope Notes
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
PNG whole sheet scale 1×, 2× or 4×; refused beyond 16 000 px a side
SVG the selected block only for diagram, chart, matrix, timeline and SVG illustration; standalone file with colours resolved and fonts embedded
Sheet JSON whole sheet direct download of the document with sorted keys; uploads are referenced by id and do not travel with the file

Interactive blocks are captured in their initial state. There is no whole-sheet SVG. Studio export files are removed after seven days.

# 14. Keyboard shortcuts

Collected from the code. ⌘ also means Ctrl.

# Editor (Editor.tsx)

Inactive while typing in a field (except save), while a dialog is open, and while the diagram editor is open.

Keys Action
⌘S Save now (works everywhere, including in fields)
⌘Z Undo
⇧⌘Z or ⌘Y Redo
⌘D Duplicate the selected blocks
Delete or Backspace Delete the selected blocks
⌥↑ / ⌥↓ Move the selected block up / down (single selection)
Escape Clear the selection, leave in-place editing

In-place text: Enter confirms a heading; ⌘Enter confirms a paragraph; Escape cancels.

# Diagram editor (DiagramEditor.tsx)

Inactive while typing in a field.

Keys Action
V / H / C Select / pan / connect tool
G Group the selected nodes, or ungroup them when they share a group
Delete or Backspace Delete the selection
⌘D Duplicate the selected nodes
⌘A Select everything
⌘Z, ⇧⌘Z, ⌘Y Undo, redo
Arrows Nudge the selected nodes by 8 px (Shift: 1 px)
+ or = / − Zoom in / out
0 Fit to the view
Escape Clear the selection, close the shortcut list, leave step picking, close a drawer

A keyboard icon in the toolbar shows this list in the editor.

# Forms and panels

Where Keys Action
Single-line field Enter Commit
Multi-line field ⌘Enter Commit
Code field Tab; Escape then Tab Insert two spaces; leave the field
Diagram panel fields Enter / ⌘Enter; Escape Commit; restore the committed value
Claude request ⌘Enter Send
Dialogs Escape Close (native <dialog>)

# Reader-facing blocks (also live in the editor)

Block Keys
Tabs ←/↑ and →/↓ change tab; Home / End go to the first / last
Diagram (full screen) Escape leaves full screen

# 15. Not offered

  • No offline editing: the service worker never caches pages or API responses, and the studio needs the network.
  • 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.
  • No comments, no review workflow beyond the "In review" label.
  • No scheduled publication.
  • No drag-and-drop block reordering, no canvas selection of blocks nested in tabs.
  • No image editing; images are used as uploaded.

Note 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.

Files main
Menu

Theme