SPB Git

Repository Public

EDITOR-NODES.md 13.2 KB 122 lines markdown

1# Editor nodes — SP Note Next Generation (web)23Contract: `SPEC.md` §2. The stored format is the ProseMirror JSON; attrs below are exactly those of the SPEC (defaults in4`src/lib/editor/next-nodes.ts`). Every new block is a **leaf atom** (no `content`) that carries the usual block `id`; binary data is5an attachment referenced by id (`/api/files/<id>`). Schema: `src/components/editor/extensions/next-nodes.tsx`; views:6`src/components/editor/nodes/*`. Slash menu, ⌘K ("Insert …"), Markdown paste, drag handle and block menu know all of them.78## 0. Safety (read first)910- `enableContentCheck` is on. A document that fails the schema check **opens read-only** ("Read-only — this page holds newer content")11  and is **never autosaved**: the editor emits nothing while locked and the page's sync engine reads the copy received from the server.12  When the document could be built completely the banner offers "Edit anyway…" behind a confirmation; when it could not (what is on13  screen is partial) there is no override. `Editor` prop `onLock(lock | null)`.14- **Unknown content round-trips verbatim** (`src/lib/editor/unknown.ts`):15  unknown node type → `unknownBlock` / `unknownInline` atom (attr `raw`, neutral card "Unsupported block"); unknown mark, or known mark16  with unknown attrs → `unknownMark` (text stays editable, dotted underline); unknown attrs on a known node → reserved attr `xattrs`.17  Boxing happens before the JSON reaches ProseMirror, unboxing in everything the editor emits. `unknownBlock`, `unknownInline`,18  `unknownMark` and `xattrs` never reach the server. **Always use `getEditorDoc(editor)` / `setEditorDoc(editor, doc)`** instead of19  `editor.getJSON()` / `commands.setContent()`.20- A failed *insert* (pasted or generated content that does not fit) shows a toast and changes nothing; it does not lock the page.2122## 1. New nodes2324| Node | Attrs | Behaviour on the web | Limits |25|---|---|---|---|26| `mermaid` | `code`, `preview`, `previewHash` | `mermaid` 12 loaded on demand (block near the viewport), `securityLevel: "strict"`, SVG text labels. On-screen render 450 ms after the last change. Stored render: **PNG at 2×** (max side 4096 px) of the light theme uploaded as an attachment, `previewHash` = sha256 hex of `code`; uploaded only when the code is valid, stable for 2.5 s **and the source field is not focused**. A syntax error keeps the last valid render and uploads nothing. | If rasterising fails the SVG itself is uploaded (SPEC allows SVG or PNG). Offline: hash stays stale (natives show the source + notice); "Save the render now" retries. |27| `drawing` | `ink`, `preview`, `pk`, `width`, `height`, `background` | Ink editor in a sheet: pointer events with pressure, pen / marker / highlighter / eraser (stroke eraser), 8 colours, 3 widths, undo / redo, clear. Save uploads `spn-ink-1` JSON (`application/json`) + PNG preview and sets `pk: null`. Re-editing loads the ink file. | Canvas 1200×800 units. A drawing with a preview but no readable ink cannot be edited (never overwritten). Unknown ink keys are preserved. |28| `chart` | `kind`, `title`, `columns`, `rows`, `x`, `y`, `source` | Own SVG renderer (bar, line, area, pie, scatter), responsive, legend + `<title>` on marks, `role="img"`. Editable data grid (cells, rows, columns, x/y mapping, paste a table). | `source` (live database data) is **not resolved in this wave**: the snapshot is rendered with a note; `source` is never modified. Grid shows 100 rows at a time. 8 series colours then repeat. |29| `queryView` | `source`, `databaseId`, `viewId`, `filter`, `layout`, `limit`, `title` | Config UI + `POST /api/query` `{source, databaseId?, viewId?, filter, limit}`; list / table / board (grouped by status). Refetched on window focus (30 s stale time). | **Feature-detected**: 404/405/501 → "Live views are not available on this server yet", config kept. Row shape is normalised tolerantly (`src/lib/editor/query.ts`) until `docs/next/API-NEXT.md` fixes it. For `source: "backlinks"` the current page id is sent as top-level `pageId`. Limit 1–200. |30| `citation` (inline) | `refId`, `locator`, `label` | Chip `(Author Year, locator)`; popover to pick a reference (fuzzy search of the library) and edit the locator. `label` is cached as "Author Year". | Read-only editors link to `/research?ref=<id>`. A citation without `refId` is shown dashed. |31| `bibliography` | `style`, `title` | APA list of the references cited in the page, computed from the document; resolved with `GET /api/research/references?ids=` (a server that ignores `ids` returns the library, filtered client-side). | Only `apa` is rendered. Deleted references are listed as not found. |32| `pdf` | `attachmentId`, `name`, `page`, `annotations` | pdf.js 6 loaded when the block scrolls into view; one page at a time (canvas + text layer), fit / zoom, page navigation (`page` = reading position, debounced). Select text → Highlight (4 colours) or Add note → annotation `{id, page, kind, color, rects (0..1, origin top-left), text, note, createdAt}`; list under the page, jump, edit note, delete. | Worker and data files are served from `/vendor/pdfjs` (copied by `scripts/copy-vendor.mjs` before dev/build). `kind: "ink"` annotations from other clients are drawn and preserved, not editable. Password-protected / corrupt files show an error state. |33| `blockRef` | `pageId`, `blockId`, `mode` | Picker (search a page → choose a block). `embed`: the source block rendered read-only by the editor itself, refreshed on focus (15 s stale time); `link`: one-line link. "Jump to the source" → `/p/<pageId>#block-<blockId>`. | Missing target → "Reference not found — Référence introuvable". Nested references are embedded 2 levels deep, then shown as links. |34| `runCode` | `language`, `code`, `output` | Runs **only on the Run button** (or ⌘/Ctrl+Enter in the code field). Sandbox: hidden `<iframe sandbox="allow-scripts">` (opaque origin) built from `srcdoc` with CSP `default-src 'none'; script-src 'nonce-…' 'unsafe-eval'; worker-src blob:; base-uri 'none'; form-action 'none'`; the code runs in a blob Worker inside the frame, so an endless loop cannot freeze the app. Console output, returned value and errors are captured into `output = {text, error, ms, at}`. | JavaScript only (other languages are stored and displayed). Timeout 5 s, output 20 000 characters. No network, no DOM, no storage, no cookies. |35| `audio` | `attachmentId`, `duration`, `title`, `recordedAt`, `transcript`, `transcriptStatus`, `transcriptEngine`, `summary` | Recorder (MediaRecorder: mp4/m4a preferred, else webm/opus) with level meter → upload → node; or upload a file. Player: play/pause, scrubber, rate, waveform (decoded lazily, ≤ 25 MB), transcript lines `[m:ss] text` that seek. "Transcribe" → `POST /api/audio/<id>/transcribe`. `summary` is displayed in an AI-labelled box, never generated here. | **Feature-detected** transcription (404/405/501 → "not available on this server yet"). Seeking long files needs `Range` on `/api/files` (backend). |36| `canvasLink` | `pageId` | Card that opens the canvas page; picker of existing canvases (`type: "canvas"` in the tree) or "New canvas". | **Feature-detected**: a server that refuses `type: "canvas"` shows "Canvases are not available on this server yet". |3738## 2. Extended nodes3940- `taskItem`: optional `due` (ISO date), `priority` (`low|medium|high`), `taskId`. Chips at the end of the item (due date — red when41  overdue and unchecked — priority, a "linked" mark when `taskId` is set); click a chip or use the context bar to edit. The web editor42  never writes `taskId` (the link to the `tasks` table is the backend's).43- `listItem` / `taskItem` now receive a block `id` (client `BLOCK_ID_TYPES`; the server list is `ID_TYPES` in `src/lib/editor/text.ts`).44- `aiBlock`: optional `sources` (`[{pageId, blockId, title}]`, rendered as numbered chips linking to the block) and `action` (shown in the "AI · action" tag).45- `callout.kind`: + `decision`, `question`, `hypothesis` (labelled, own tint; kind switcher in the context bar; `/decision`, `/question`, `/hypothesis`).4647## 3. Editor chrome4849- **Context bar** (desktop, Morphing Editor): tools for the block under the cursor — table (rows, columns, header, merge/split, delete),50  code (language, copy), callout (kind), image (size presets, alt text), task (due, priority).51- **Drag handle**: drag to move any block; `+` adds a block below (opens "/"); click the grip for the block menu (turn into, duplicate,52  copy link to block, move up/down, delete). New blocks are not HTML-draggable themselves (it would break text selection and drawing inside them).53- **Images**: resize handles left/right on desktop (stores `width`), presets in the context bar.54- **Markdown paste**: plain text that is clearly Markdown becomes blocks (⌘⇧V pastes as plain text).55- **Semantic zoom**: "Zoom out to the outline" (level 2: headings + first block of each section; read-only; click a heading to return).56  Level 1 (AI synopsis) needs `GET /api/pages/<id>/zoom` — later wave.5758## 4. Markdown (client) — `src/lib/editor/markdown-client.ts`5960`docToMarkdown(doc)` expands the new nodes to the forms of SPEC §2, then calls the shared `toMarkdown`. `markdownToDoc(md)` reads back61the forms that identify their node:6263| Node | Export | Import |64|---|---|---|65| mermaid | ```` ```mermaid ```` fence | yes |66| runCode | fence with its language + ```` ```output ```` fence | only when followed by an `output` fence (else a plain code block) |67| chart | title line + Markdown table | no (stays a table) |68| drawing | `![Dessin](/api/files/<preview>)` or `[Dessin]` | preview only (`ink: null`) |69| pdf | `[PDF: name](/api/files/<id>)` + `> p.<page> — <text> — <note>` lines | yes (annotations without rects) |70| audio | `[Audio: title](/api/files/<id>)` + `[mm:ss] text` lines | yes |71| queryView | `[Vue: title]` | title only |72| blockRef | `[[<pageId>#<blockId>]]` | yes (also by the file importer: a uuid target is never read as a wiki link by title) |73| citation | `[@<label or refId>, locator]` | yes (label + locator, or a reference uuid) |74| bibliography | `## <title>` | no (a heading) |75| canvasLink | `[Canvas](/p/<pageId>)` | yes |7677Server-side text / Markdown / HTML export of these nodes is owned by the backend workstream (`src/lib/editor/text.ts`, `src/lib/export/*`).787980## Integration pass (2026-11-19) — viewing a page never writes8182Opening a note must not create a save (a version, a new `rev`, a `page.edited` event) when the user edited nothing. Two node views83used to write on view and no longer do:8485- **`chart` with a `source`** — the data snapshot (`columns`, `rows`) is written into the node only (1) on a click on **Refresh**,86  or (2) together with a real user edit of the document (outside the undo history in both cases). Until then the live table is what87  is drawn; the stored snapshot is what native clients and offline readers draw, and may be older than the database.88- **`mermaid`** — the stored render (`preview`, `previewHash`) is uploaded and written only (1) after the user changed the source in89  this view, (2) on **Save the render now**, or (3) together with a real user edit elsewhere in the document. A diagram written by a90  native client (no `preview`) therefore shows « Render not saved yet » on the web until one of the three happens; natives keep91  showing the source with their notice meanwhile.9293File import (`POST /api/import`, Markdown): the forms of the table above are read by the same parser as a paste. Two were pre-empted94by the importer and are fixed: `[[<page uuid>#<block>]]` (was treated as a wiki link by title → plain text) and95`![Dessin](/api/files/<id>)` (was imported as an image). A file with YAML front matter (SP Note's own export) no longer has a first96paragraph of the form `Word: text` swallowed as a Notion-style property. Test: `tests/unit/next-int-import.test.ts`,97`tests/e2e/next-integration.spec.ts`.9899100## Ink: one width law for every platform (lead decision, integration pass)101102`src/lib/editor/ink.ts` (drawing block **and** canvas ink — same module) now uses the law of the Swift core, so a drawing has the same103thickness on every device:104105| tool | drawn width at pressure `p` (0…1) |106|---|---|107| pen | `width × (0.35 + 0.65 · p)` — the nominal `width` at `p = 1`, 35 % of it at `p = 0` (it was `width × (0.35 + 1.3 · p)`, nominal at 0.5) |108| marker | `width`, constant (it was `width × (0.85 + 0.3 · p)`) |109| highlighter | `width`, constant; an opaque colour is drawn at alpha **0.40** (it was 0.35); new strokes are written `#rrggbb66` |110111A point without pressure (`[x, y]`) counts as `p = 1` (it was 0.5). Input without a force sensor — mouse, finger — is **written with112`p = 1`** (it was 0.5); only a stylus (`pointerType: "pen"`) writes its real pressure. Drawings saved before this change keep their113stored pressures: a mouse stroke stored at 0.5 is now drawn at 67.5 % of its nominal width.114115Shared numeric fixture, asserted by `tests/unit/next-web-ink.test.ts` and meant for the Swift tests — `tests/fixtures/ink/width-law.json`:116117| stroke | points (pressure) | drawn widths | bounds `[minX, minY, maxX, maxY]` |118|---|---|---|---|119| pen, width 4 | 0 · 0.25 · 0.5 · 0.75 · 1 · *(none)* | 1.4 · 2.05 · 2.7 · 3.35 · 4 · 4 | 8, 8, 62, 12 |120| marker, width 6 | 0.2 · 0.9 · *(none)* | 6 · 6 · 6 | 7, 47, 113, 53 |121| highlighter, width 20, `#ffd60aff` | 0.1 · *(none)* | 20 · 20 (alpha 0.40) | 0, 90, 210, 110 |122
Files main
Menu

Theme