frontend: insert a figure into a sentence, and print it as one

The editor gains 「插入图片」: it uploads the file and appends the sentence that
shows it, and a file dropped anywhere in the dialog does the same. Each row then
prints the picture it holds, not only the path to it — checking that the right
curve landed in the right paragraph is the whole reason to look at the editor.

Reading it back, one rule decides the layout: a sentence holding nothing but an
image is a figure — its own line, centred, the text in the brackets printed
underneath as its 图注 — while an image inside a run of text stays on the line,
height capped so a pasted screenshot cannot stretch a line of prose. The size is
optional, in pandoc's `{width=70%}` form, and is validated to digits plus one
unit before it becomes a CSS length.

`utils/math.ts` becomes `utils/rich.ts`, because it now reads two families of
markup rather than one: the formulas it always parsed, and the images a sentence
keeps as Markdown. A figure is deliberately not built inside the `v-html` string
the rest of a sentence is: `PaperParagraph` prints it as a real `<img>`, so it
can carry the writer's size and open at full resolution when clicked — an
experiment figure on a page is often too small to check a curve against.
This commit is contained in:
2026-09-23 13:31:31 +08:00
parent 6f37120dc4
commit 0e0fde8f02
5 changed files with 556 additions and 55 deletions
+93 -8
View File
@@ -358,6 +358,68 @@ sentences printed correctly by accident (the full stop hides the missing space),
so nothing looked wrong until the first English paper, whose sentences would
have run together.
### An image is an object, and the sentence keeps only its address
Not everything in a paper is text, and the parts that are not do not get a table.
The bytes of a 插图 live in **MinIO** (k3s, S3 protocol) and the sentence keeps
the address, as Markdown:
```
试验装置如 ![行内示意图](/api/images/2026/09/9f8c1a4b7e2d0c33.png) 所示。
![试验装置示意图](/api/images/2026/09/9f8c1a4b7e2d0c33.png){width=70%}
```
A table was the obvious alternative — `paper_image` with a `sort`, a caption and
a paragraph position — and it is wrong here, for the reason the sentence model
already gives: a paragraph is *reassembled from sentences ordered by one number*,
and a second table holding its own `sort` beside that one gives a paragraph two
orderings that eventually disagree. Keeping the picture inside `content` means a
figure moves between paragraphs by being cut and pasted, survives a template
switch with the sentence it belongs to, and needs no new endpoint to write. The
same argument that made citations a table (a citation carries data of its own,
and is queried in both directions) is what keeps images out of one.
Three properties of the storage are deliberate:
- **The key is the digest of the picture.** `2026/09/9f8c1a4b7e2d0c33.png` is
derived from the bytes, so uploading the same screenshot twice — from two
paragraphs, or by accident — stores one object, and the address can never come
to mean a different picture than the one it was written for. That is what makes
the year-long `immutable` cache header safe to hand out.
- **The format is sniffed, never trusted.** The declared content type and the
filename are the uploader's claims; the magic bytes are the fact. PNG, JPEG,
GIF and WebP are accepted — and **SVG is not**, because an uploaded SVG served
from this origin is stored XSS, while the page already renders text the writer
controls. The served content type comes from a whitelist on our side, with
`X-Content-Type-Options: nosniff`.
- **The key space is also the access rule.** `GET /api/images/{key}` serves keys
of the shape this application writes and nothing else, so the read route cannot
become a browser for the rest of the bucket, whatever else is in it.
Images are served through the API rather than from a public bucket URL so that a
sentence never embeds a host name: the same paper is read from the LAN in
development and from the public address later, and a hard-coded origin would
break on the other. It also means the bucket stays private. The response streams
the object out of MinIO rather than reading it into memory, and releases the
connection when the reader stops.
Two rules decide how a picture prints, and both follow from "a sentence is a
line":
| What the sentence holds | How it prints |
|---|---|
| nothing but `![图注](地址)` | a **figure**: its own line, centred, the brackets' text as 图注 underneath |
| an image inside a run of text | **inline**, on the line with the words, height capped at `12em` |
The size is optional and comes from pandoc's attribute form — `{width=70%}`,
`{width=400px}` — and is validated to digits plus one unit before it becomes a
CSS length, so no second declaration can be smuggled through it.
Configuration is three variables (`MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`,
`MINIO_SECRET_KEY`, plus `MINIO_BUCKET`). Left empty, the paper still writes and
reads: only the image routes answer `503`, saying which variables are missing.
The bucket is created on the first upload if it is not there.
### Citations are a table, not a column
One sentence may quote several references, so
@@ -465,6 +527,8 @@ All routes are mounted under `/api`. Interactive docs at `/docs`.
| `PUT` | `/papers/{id}/paragraphs/{sort}` | full replacement; optional `target_sort` moves it |
| `POST` | `/papers/{id}/sentences` | append one sentence |
| `PATCH` `DELETE` | `/papers/{id}/sentences/{id}` | edit or remove one sentence |
| `POST` | `/images` | `multipart/form-data`, one `file` field; answers `key`, `url`, ready-to-paste `markdown`, `content_type`, `size`, `sha256` |
| `GET` | `/images/{key}` | streams the picture; only keys this app wrote, cached `immutable` for a year |
Conventions worth knowing:
@@ -510,6 +574,12 @@ Conventions worth knowing:
rail's labels compose with the toolbar's.
- A DOI is stored without its ``https://doi.org/`` prefix, so the column holds
one spelling whichever way it was pasted.
- An uploaded image is refused with `415` when its bytes are not PNG/JPEG/GIF/
WebP (SVG included), `413` when it is over `MAX_IMAGE_BYTES` (20 MiB) and `400`
when it is empty. A key that has no object, or one this application did not
write, is `404`.
- An image URL is relative (`/api/images/…`) and same-origin on purpose: the
client prints it as it stands, and the paper does not name a host.
## MCP server
@@ -693,15 +763,16 @@ are not lists (the paper document) keep scrolling normally.
A formula is stored exactly as the writer typed it — `$\ell$`, `$$ … \tag{1} $$`
— because that is the form that can be edited; an equation image cannot be
changed by one character. Typesetting happens when the paper is read, in
`src/utils/math.ts`, which splits a sentence into text and formulas, hands the
formulas to KaTeX and escapes everything else.
changed by one character. The same is true of a picture: the sentence keeps the
Markdown that points at it. Typesetting happens when the paper is read, in
`src/utils/rich.ts`, which splits a sentence into text, formulas and images,
hands the formulas to KaTeX and escapes everything else.
Four delimiters are recognised, because a writer's habit decides which they use:
`$$…$$` and `\[…\]` for display, `$…$` and `\(…\)` for inline. An unmatched
`$` is left alone rather than swallowing the rest of the paragraph.
Three rules are worth knowing when reading the renderer:
Four rules are worth knowing when reading the renderer:
- **A display formula is a block.** It takes its own line whether or not the
sentence asked for a break, because that is what "display" means.
@@ -723,6 +794,14 @@ Three rules are worth knowing when reading the renderer:
through `v-html`, and KaTeX runs with `trust` off, so a sentence cannot inject
markup.
An image is the one thing the renderer does *not* build inside that HTML string.
A figure is printed by `PaperParagraph` as a real `<img>` — so it can carry the
writer's size and be opened at full resolution by a click — and `figureOf()`
decides whether a sentence is a figure: it is one when the sentence holds nothing
but a picture and whitespace. The reader's click is handled once, on the
paragraph body, because inline pictures arrive through `v-html`, where no
listener can be bound to them from a template.
### The paper view
`PapersView` is the library; `papers/PaperDetailView` is the writing surface.
@@ -780,11 +859,12 @@ in correctly.
paper-doc/
├── backend/ # FastAPI application
│ ├── app/
│ │ ├── api/routes/ # route handlers (health, papers, references,
│ │ ├── api/routes/ # route handlers (health, images, papers, references,
│ │ │ # reference_tags, templates, template_title)
│ │ ├── citation_styles/ # how a reference prints: springer.py, and the
│ │ │ # registry that names the styles
│ │ ├── core/ # settings and configuration
│ │ ├── core/ # settings, and the object store (MinIO) the
│ │ │ # images a paper embeds are kept in
│ │ ├── crud/ # data-access helpers
│ │ ├── db/ # engine, session, declarative base
│ │ ├── mcp/ # MCP server: tools, specs, transports, self-check
@@ -795,6 +875,7 @@ paper-doc/
│ ├── scripts/smoke_papers.py # end-to-end check of the writing loop
│ ├── scripts/smoke_references.py # end-to-end check of the reference library
│ │ # and its tags
│ ├── scripts/smoke_images.py # end-to-end check of upload, serve and refusal
│ ├── scripts/check_citation_styles.py # the formatter, one entry per type
│ │ # (no server, no database)
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
@@ -811,7 +892,8 @@ paper-doc/
│ │ ├── stores/ # pinia stores (UI prefs persisted, the paper and
│ │ │ # tag lists not)
│ │ ├── styles/ # global reset and the shell viewport contract
│ │ ├── utils/ # formatting helpers
│ │ ├── utils/ # formatting helpers, and rich.ts — the reader for
│ │ │ # a sentence's LaTeX and its images
│ │ └── views/ # route-level components (papers/, references/,
│ │ # templates/)
│ ├── package.json
@@ -832,6 +914,8 @@ paper-doc/
- Python 3.10+ with `venv`
- Node.js 18+ with `pnpm`
- Network access to the TiDB instance (local development uses the NodePort)
- *Optional:* a MinIO (or any S3-compatible) endpoint, for the images a paper
embeds. Without one, everything still works except uploading pictures.
**Backend**
@@ -839,7 +923,8 @@ paper-doc/
cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # then fill in the database credentials
cp .env.example .env # then fill in the database credentials, and the
# MINIO_* ones if the paper is to hold images
uvicorn app.main:app --reload --port 8000
```