Files
paper-doc/frontend/scripts/check-image.mjs
T
govin 1531263bd2 frontend: let a figure be sized by its height as well as its width
A writer with a tall panel does not want to shrink it from the left edge: what
they know is "this one is too tall". The format had a width and nothing else, so
the only way to make a figure shorter was to guess a percentage and check the
page — and the previous commit's answer, "type 638px", asked them to do the
arithmetic themselves.

So `{height=300px}` joins `{width=…}`, in the same attribute block, and the
editor grows a second box beside the first. Both are typeable as well as
pre-set, both write through the reader's own parse function, and the hint beside
them says what the picture will measure on the page.

Three rules, and the point of all three is that a figure cannot be stretched:

* **a width is exact, a height is a cap.** A width has a reference — the column,
  or a length the writer chose — while nothing measures a height against
  anything, and enlarging a picture past its own pixels only makes it soft. In
  the flow of a sentence a height is always a downscale, which comes to the same
  thing as exact.
* **given one, the other follows from the picture's own shape** — `max-height`
  for a height, `width` for a width — so the height is never written by hand.
* **given both, they are a box to fit inside**, not a box to fill. Two numbers
  that need not have the picture's proportions can only mean "no bigger than",
  and the check asserts the drawn rectangle still matches the file's ratio.

Whichever box is left empty keeps the other's setting, so a size can be set in
two steps, and clearing either goes back to the natural size.

`check-image.mjs`: 26 checks to 36. Two of the new ones found real bugs while
being written. The first: with both a width and a height in one `{…}` block,
neither side parsed — the patterns were anchored to the whole block, so a figure
with two numbers silently printed at its natural size. The attribute block is now
split into declarations first. The second was mine: returning "contain" for a
height-only figure left a 1276×2000 box around a small picture, which the caption
then sat under. A height is a cap, and a cap needs no contain.

The MCP tool takes the same two arguments, so a model can write either number,
and a percentage height is refused with the reason it cannot work: a sentence is
flowed text, so there is nothing for it to be a percentage of and the browser
ignores it. v8 is deployed and DSH has verified both numbers round-tripping.
2026-09-24 13:18:52 +08:00

509 lines
20 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Does an inserted picture actually show?
*
* pnpm check:image # API on :8000 and the web app on :5173
* PAPER_WEB=http://… pnpm check:image
*
* This is the check `backend/scripts/smoke_images.py` cannot make. That one
* proves the endpoints store and return the bytes; this one proves the page
* *draws* them: that the `<img>` really decoded (`naturalWidth`), that a figure
* took a line of its own and is centred on the column, that `{width=50%}` came
* out at half the column, that the 图注 is printed under the picture rather than
* beside it, that an image inside a sentence stayed in that line, and that the
* editor's 「插入图片」 button ends with the picture in the paper after saving.
*
* It creates a throwaway paper for the run and deletes it afterwards, so it can
* be pointed at a database that holds real work.
*
* It needs Playwright, which is deliberately not a dependency of the app:
*
* pnpm add -D playwright && npx playwright install chromium
*
* An install that lives elsewhere can be pointed at instead, which is how this
* was verified on the machine that runs the paper:
*
* PLAYWRIGHT_MODULE=/path/to/node_modules/playwright/index.mjs pnpm check:image
*/
import { deflateSync } from 'node:zlib'
const WEB = process.env.PAPER_WEB ?? 'http://127.0.0.1:5173'
const API = process.env.PAPER_API ?? 'http://127.0.0.1:8000/api'
let chromium
try {
;({ chromium } = await import(process.env.PLAYWRIGHT_MODULE ?? 'playwright'))
} catch {
console.error(
'playwright is not installed. Either install it:\n' +
' pnpm add -D playwright && npx playwright install chromium\n' +
'or point at an existing install with PLAYWRIGHT_MODULE=…/playwright/index.mjs',
)
process.exit(2)
}
// --- a real PNG, built here so the script carries its own fixture ------------
const CRC_TABLE = Array.from({ length: 256 }, (_, index) => {
let value = index
for (let bit = 0; bit < 8; bit += 1) {
value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1
}
return value >>> 0
})
function crc32(buffer) {
let crc = 0xffffffff
for (const byte of buffer) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8)
return (crc ^ 0xffffffff) >>> 0
}
function chunk(tag, payload) {
const body = Buffer.concat([Buffer.from(tag, 'ascii'), payload])
const length = Buffer.alloc(4)
length.writeUInt32BE(payload.length)
const crc = Buffer.alloc(4)
crc.writeUInt32BE(crc32(body))
return Buffer.concat([length, body, crc])
}
/** A gradient, so two fixtures differ and the size is honest. */
function makePng(width = 480, height = 300) {
const raw = Buffer.alloc(height * (1 + width * 3))
let offset = 0
for (let y = 0; y < height; y += 1) {
raw[offset] = 0 // filter: none
offset += 1
for (let x = 0; x < width; x += 1) {
raw[offset] = Math.round((x * 255) / Math.max(width - 1, 1))
raw[offset + 1] = Math.round((y * 255) / Math.max(height - 1, 1))
raw[offset + 2] = 128
offset += 3
}
}
const header = Buffer.alloc(13)
header.writeUInt32BE(width, 0)
header.writeUInt32BE(height, 4)
header[8] = 8 // bit depth
header[9] = 2 // truecolour
return Buffer.concat([
Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
chunk('IHDR', header),
chunk('IDAT', deflateSync(raw, { level: 9 })),
chunk('IEND', Buffer.alloc(0)),
])
}
// --- the API, spoken with fetch ---------------------------------------------
async function api(method, path, body) {
const response = await fetch(`${API}${path}`, {
method,
headers: { 'Content-Type': 'application/json' },
body: body ? JSON.stringify(body) : undefined,
})
if (!response.ok && response.status !== 204) {
throw new Error(`${method} ${path} -> ${response.status}: ${await response.text()}`)
}
return response.status === 204 ? null : response.json()
}
const results = []
function check(label, ok, detail = '') {
results.push([label, ok])
console.log(`${ok ? ' ok ' : ' FAIL'}${label}${ok ? '' : ` — ${detail}`}`)
}
const png = makePng()
const uploadResponse = await fetch(`${API}/images`, {
method: 'POST',
body: (() => {
const form = new FormData()
form.append('file', new Blob([png], { type: 'image/png' }), '试验装置.png')
return form
})(),
})
if (!uploadResponse.ok) {
throw new Error(`upload -> ${uploadResponse.status}: ${await uploadResponse.text()}`)
}
const image = await uploadResponse.json()
console.log(`uploaded ${image.url} (${image.size} bytes)`)
const browser = await chromium.launch()
let paperId = null
try {
const context = await browser.newContext({ viewport: { width: 1600, height: 950 } })
const page = await context.newPage()
const template = (await api('GET', '/templates?page_size=1')).items[0]
paperId = (await api('POST', '/papers', { title: '插图浏览器测试', template_id: template.id })).id
const outline = await api('GET', `/templates/${template.id}`)
const sort = outline.placements[0].sort
// One paragraph with an image inside a sentence, and one figure half the
// column wide. Written through the API so the *rendering* is what is checked.
await api('PUT', `/papers/${paperId}/paragraphs/${sort}`, {
sentences: [
{ content: `试验装置如 ![行内示意图](${image.url}) 所示,量测点布置在试件中部。` },
{ content: `![试验装置示意图](${image.url}){width=50%}`, line_break_before: true },
],
})
await page.goto(`${WEB}/papers/${paperId}`, { waitUntil: 'networkidle' })
await page.waitForSelector('.paragraph-body')
// `naturalWidth` is the proof it decoded; give the decode a moment.
await page.waitForTimeout(800)
const geometry = await page.evaluate(() => {
const body = document.querySelector('.paragraph-body')
const bodyBox = body.getBoundingClientRect()
const figure = document.querySelector('.sentence--figure')
const figureImage = figure.querySelector('img')
const figureBox = figureImage.getBoundingClientRect()
const caption = figure.querySelector('.figure-caption')
const inline = [...document.querySelectorAll('.sentence img')].find(
(node) => !node.closest('.sentence--figure'),
)
const inlineBox = inline.getBoundingClientRect()
return {
bodyWidth: Math.round(bodyBox.width),
bodyCenter: Math.round(bodyBox.left + bodyBox.width / 2),
figure: {
src: figureImage.getAttribute('src'),
natural: [figureImage.naturalWidth, figureImage.naturalHeight],
width: Math.round(figureBox.width),
height: Math.round(figureBox.height),
// What the markup asked the browser for. The height is expected to be
// empty: only a width is ever written, which is what makes a figure
// impossible to deform.
styleHeight: figureImage.style.height || '',
center: Math.round(figureBox.left + figureBox.width / 2),
caption: caption.textContent.trim(),
gapBelowImage: Math.round(caption.getBoundingClientRect().top - figureBox.bottom),
siblings: figure.closest('.paragraph-line').querySelectorAll('.sentence').length,
},
inline: {
width: Math.round(inlineBox.width),
height: Math.round(inlineBox.height),
inFigure: Boolean(inline.closest('.sentence--figure')),
lineHasText: inline.closest('.paragraph-line').textContent.includes('量测点'),
},
}
})
const { figure, inline } = geometry
check('the picture decoded', figure.natural[0] === 480, JSON.stringify(figure.natural))
check('it is served from our own path', figure.src.startsWith('/api/images/'), figure.src)
check(
'{width=50%} is half the column',
Math.abs(figure.width - geometry.bodyWidth * 0.5) <= 2,
`${figure.width} vs ${geometry.bodyWidth * 0.5}`,
)
check(
'the figure is centred on the column',
Math.abs(figure.center - geometry.bodyCenter) <= 2,
`${figure.center} vs ${geometry.bodyCenter}`,
)
// The size is a *width* and nothing else: the height is whatever keeps the
// picture's own shape, so a figure cannot be stretched. Both halves of that
// are checked — the shape the browser drew, and that nothing asked for a
// height in the first place.
check(
'a sized figure keeps its own shape',
Math.abs((figure.width / figure.height) / (figure.natural[0] / figure.natural[1]) - 1) < 0.01,
`${figure.width}×${figure.height} vs natural ${figure.natural.join('×')}`,
)
check(
'and no height is ever written into the sentence',
figure.styleHeight === '',
`style.height = ${JSON.stringify(figure.styleHeight)}`,
)
check('the 图注 is the text in the brackets', figure.caption === '试验装置示意图', figure.caption)
check('…and it is printed under the picture', figure.gapBelowImage > 0, `${figure.gapBelowImage}`)
check('the figure owns its line', figure.siblings === 1, `${figure.siblings} sentences`)
check(
'an image inside a sentence stays inline',
!inline.inFigure && inline.lineHasText,
JSON.stringify(inline),
)
check(
'the inline image keeps its aspect ratio',
Math.abs(inline.width / inline.height - 480 / 300) < 0.02,
`${inline.width}x${inline.height}`,
)
await page.locator('.sentence--figure img').click()
await page.waitForTimeout(400)
check(
'clicking opens the picture at full size',
await page.evaluate(() => Boolean(document.querySelector('.el-image-viewer__wrapper'))),
)
await page.keyboard.press('Escape')
await page.waitForTimeout(400)
// --- the editor's own 「插入图片」 -----------------------------------------
// Scoped to a paragraph header: 「编辑信息」 in the toolbar also contains 编辑.
await page.locator('.paragraph-actions button:has-text("编辑")').first().click()
await page.waitForSelector('.editor .rows', { timeout: 15000 })
await page.locator('.editor input[type=file]').setInputFiles({
name: '第二张图.png',
mimeType: 'image/png',
buffer: png,
})
// Wait for the *new* thumbnail: the dialog already shows the two the API
// wrote, so waiting for any `.row-image img` would return immediately.
await page.waitForFunction(
() =>
[...document.querySelectorAll('.row-image figcaption')].some(
(node) => node.textContent.trim() === '第二张图',
),
{ timeout: 20000 },
)
check(
'the editor shows the uploaded picture',
(await page.locator('.row-image img').count()) === 3,
`${await page.locator('.row-image img').count()} thumbnails`,
)
check(
'the row caption comes from the filename',
(await page.locator('.row-image figcaption', { hasText: '第二张图' }).first().textContent()).trim() ===
'第二张图',
)
await page.getByRole('button', { name: '保存段落' }).click()
await page.waitForSelector('.el-dialog', { state: 'detached', timeout: 15000 })
await page.waitForTimeout(800)
const saved = await page.evaluate(() => {
const figures = [...document.querySelectorAll('.sentence--figure')]
return {
count: figures.length,
captions: figures.map((node) => node.querySelector('.figure-caption').textContent.trim()),
decoded: figures.map((node) => node.querySelector('img').naturalWidth),
}
})
check('the inserted figure is in the paper', saved.count === 2, JSON.stringify(saved))
check('and it is the one that was uploaded', saved.captions.includes('第二张图'), saved.captions.join())
check('both pictures decoded', saved.decoded.every((width) => width === 480), saved.decoded.join())
// --- the figure's size, set from the editor ------------------------------
//
// Figures come out of the plotting tool at whatever size they were made —
// one paper's are 1441, 2400 and 4169 pixels wide — and every one of them can
// be wider than the column, so with no size they all print at the full column
// and a near-square panel fills a page. This control is the answer to that,
// and what has to hold is that what it writes is what the reader prints.
await page.locator('.paragraph-actions button:has-text("编辑")').first().click()
await page.waitForSelector('.editor .rows', { timeout: 15000 })
await page.waitForSelector('.width-select')
// The hint divides the column by the picture's own size, so it needs the
// thumbnail to have decoded first.
await page.waitForFunction(
() => document.querySelector('.size-hint')?.textContent?.includes('原图'),
{ timeout: 15000 },
)
// What each select is showing: Element Plus prints the chosen label in its
// own element, not as the value of the input the writer types into.
const boxes = await page.evaluate(() => {
const rows = [...document.querySelectorAll('.row')]
const withSize = rows.filter((row) => row.querySelector('.width-select'))
return {
rows: rows.length,
withSize: withSize.length,
// Two boxes per figure — a width and a height, in that order.
values: withSize.map((row) =>
[...row.querySelectorAll('.width-select')].map(
(node) =>
(node.querySelector('.el-select__selected-item')?.textContent ?? '').trim() ||
(node.querySelector('.el-select__placeholder')?.textContent ?? '').trim(),
),
),
}
})
check(
'a size is offered on the figure rows and nowhere else',
boxes.withSize === 2 && boxes.rows === 3,
JSON.stringify(boxes),
)
check(
'each figure row has a width box and a height box',
boxes.values.every((pair) => pair.length === 2),
JSON.stringify(boxes.values),
)
check(
'and the width box shows the size that row is set to',
boxes.values[0][0] === '50%' && boxes.values[1][0] !== '50%',
JSON.stringify(boxes.values),
)
const hint = async () =>
(await page.locator('.size-hint').first().innerText()).replace(/\s+/g, ' ')
check(
'the hint says what it will measure on the page',
/显示 638×399/.test(await hint()),
await hint(),
)
// Typing a value that is not one of the presets is the point of the control:
// the size a panel wants is what it measures, not a round number.
await page.locator('.width-select input').first().fill('30%')
await page.keyboard.press('Enter')
await page.waitForTimeout(400)
check('typing 30% converts immediately', /显示 383×239/.test(await hint()), await hint())
await page.getByRole('button', { name: '保存段落' }).click()
await page.waitForSelector('.el-dialog', { state: 'detached', timeout: 15000 })
await page.waitForTimeout(700)
const stored = await api('GET', `/papers/${paperId}/paragraphs/${sort}`)
const sized = stored.paragraph.sentences.find((sentence) =>
sentence.content.includes('试验装置示意图'),
)
check('what was typed is what is stored', sized?.content.endsWith('{width=30%}'), sized?.content)
const shrunk = await page.evaluate(() => {
const body = document.querySelector('.paragraph-body')
const column = Math.round(body.getBoundingClientRect().width)
const figure = [...document.querySelectorAll('.sentence--figure')].find(
(node) => node.querySelector('.figure-caption')?.textContent.trim() === '试验装置示意图',
)
const box = figure.querySelector('img').getBoundingClientRect()
return { column, width: Math.round(box.width), height: Math.round(box.height) }
})
check(
'and the paper prints it at that size',
Math.abs(shrunk.width - shrunk.column * 0.3) <= 2,
`${shrunk.width} vs ${shrunk.column * 0.3}`,
)
// Taking the size off again: 原尺寸, which is what the placeholder promises.
await page.locator('.paragraph-actions button:has-text("编辑")').first().click()
await page.waitForSelector('.width-select', { timeout: 15000 })
await page.waitForFunction(
() => document.querySelector('.size-hint')?.textContent?.includes('原图'),
{ timeout: 15000 },
)
await page.locator('.width-select').first().hover()
await page.locator('.width-select .el-select__clear').first().click({ force: true })
await page.waitForTimeout(300)
check('clearing it goes back to the natural size', /显示 480×300/.test(await hint()), await hint())
// A size the reader cannot read is refused rather than stored: a figure that
// quietly prints at its natural size is the bug this control exists to fix.
await page.locator('.width-select input').first().fill('宽一点')
await page.keyboard.press('Enter')
await page.waitForTimeout(400)
check(
'a size that is not one is refused',
await page.evaluate(() => Boolean(document.querySelector('.el-message--warning'))),
)
check('and the sentence keeps the size it had', /显示 480×300/.test(await hint()), await hint())
await page.getByRole('button', { name: '取消' }).click()
await page.waitForSelector('.el-dialog', { state: 'detached', timeout: 15000 })
// --- a height, which is what a writer asks for when the width is fine -----
//
// Not every figure needs resizing from the left edge: a tall panel is made
// short by its *height*, and its width has to follow or the picture deforms.
// Written through the API so what is checked is the reader's rule, not the
// editor's; the 480×300 fixture makes the arithmetic checkable by hand.
const shapeOf = async (attributes) => {
await api('PUT', `/papers/${paperId}/paragraphs/${sort}`, {
sentences: [{ content: `![尺寸试验](${image.url})${attributes}`, line_break_before: true }],
})
await page.reload({ waitUntil: 'networkidle' })
await page.waitForSelector('.sentence--figure img')
await page.waitForFunction(
() => document.querySelector('.sentence--figure img')?.complete,
{ timeout: 15000 },
)
return page.evaluate(() => {
const body = document.querySelector('.paragraph-body')
const img = document.querySelector('.sentence--figure img')
const box = img.getBoundingClientRect()
return {
column: Math.round(body.getBoundingClientRect().width),
width: Math.round(box.width),
height: Math.round(box.height),
ratio: box.width / box.height,
natural: img.naturalWidth / img.naturalHeight,
style: img.getAttribute('style') ?? '',
}
})
}
const onlyHeight = await shapeOf('{height=200px}')
check(
'只填高度时,高度就是填的那个数',
Math.abs(onlyHeight.height - 200) <= 1,
JSON.stringify(onlyHeight),
)
check(
'只填高度时,宽度按原比例跟着算(480×300 → 320×200)',
Math.abs(onlyHeight.width - 320) <= 2,
JSON.stringify(onlyHeight),
)
check(
'只填高度时,图还是原来的形状',
Math.abs(onlyHeight.ratio / onlyHeight.natural - 1) < 0.01,
JSON.stringify(onlyHeight),
)
const both = await shapeOf('{width=400px height=100px}')
check(
'宽高都填时,图放进这个框里(400×100 的框 → 160×100)',
Math.abs(both.width - 160) <= 2 && Math.abs(both.height - 100) <= 1,
JSON.stringify(both),
)
check(
'宽高都填时也没有被拉变形',
Math.abs(both.ratio / both.natural - 1) < 0.01,
JSON.stringify(both),
)
const huge = await shapeOf('{height=2000px}')
check(
'高度是个上限:不会把图放大,也不会把它推出栏外',
huge.width === 480 && huge.height === 300,
JSON.stringify(huge),
)
// …and the same thing typed into the editor's 高 box.
await page.locator('.paragraph-actions button:has-text("编辑")').first().click()
await page.waitForSelector('.width-select', { timeout: 15000 })
await page.waitForFunction(
() => document.querySelector('.size-hint')?.textContent?.includes('原图'),
{ timeout: 15000 },
)
check(
'编辑器里宽、高各有一个框',
(await page.locator('.width-select').count()) === 2,
`${await page.locator('.width-select').count()} boxes`,
)
await page.locator('.width-select').nth(1).locator('input').fill('250')
await page.keyboard.press('Enter')
await page.waitForTimeout(400)
check('填高度后立刻换算(250 → 400×250)', /显示 400×250/.test(await hint()), await hint())
await page.getByRole('button', { name: '保存段落' }).click()
await page.waitForSelector('.el-dialog', { state: 'detached', timeout: 15000 })
await page.waitForTimeout(700)
const savedHeight = await api('GET', `/papers/${paperId}/paragraphs/${sort}`)
check(
'存下来的也是高度',
savedHeight.paragraph.sentences[0].content.endsWith('{height=250px}'),
savedHeight.paragraph.sentences[0].content,
)
} finally {
await browser.close()
if (paperId) {
await api('DELETE', `/papers/${paperId}`).catch((error) => console.error('cleanup:', error.message))
}
}
const failed = results.filter(([, ok]) => !ok)
console.log(`\n${results.length - failed.length}/${results.length} checks passed`)
process.exit(failed.length ? 1 : 0)