A browser preview can look correct while the downloaded PDF breaks a word across pages, changes a glyph, or exports an older edit. For a handwriting worksheet, those are functional bugs: the spacing and character shapes are the product.
This is an implementation case study from my project, 漢字ドリル (Kanji Drill), a Japanese handwriting worksheet generator. This article was drafted by an AI agent from the project's implementation; the concrete design choices below come from its layout, preview, export and storage code.
1. Give both renderers the same document
The app first turns a draft into a layout document. Each page contains positioned cells, text baselines and optional vector paths. The document also records its revision and the font version used to build it.
The screen renders that model as SVG with a 210 × 297 viewBox. The PDF renderer consumes the same page objects and converts millimetres to points using 72 / 25.4. It does not ask the browser to wrap the text again.
This makes a 20 mm writing cell a physical measurement. Resizing the preview changes its screen scale, not the PDF geometry. With 12 mm margins on each side of A4, the available width is 186 mm: nine complete 20 mm cells fit, while a tenth does not.
The useful separation is between deciding where content belongs and drawing it. Once pagination is part of the shared model, a renderer should not invent another line break.
2. Define what must stay together
A single-character exercise and a name exercise have different pagination rules.
For individual characters, a row is a useful unit. For a name or word, the indivisible unit is one complete repetition, which may occupy several rows. At 24 mm per cell, seven characters fit across the 186 mm content width. A 20-character sequence therefore needs three rows for each complete repetition.
If the remaining page space cannot hold those three rows, move the entire repetition to the next page. Otherwise the learner gets the beginning of a name on one sheet and its ending on another.
That rule belongs in the layout builder. It should not depend on which PDF viewer or browser happens to print the document.
3. Treat old output as a different version
Font loading and PDF generation are asynchronous. Editing can continue while either operation is running.
The draft carries a revision number that changes with edits. The preview is eligible for export only when its revision matches the current draft and validation succeeds. During an update, the previous preview may remain visible, but it is marked as previous output and cannot be downloaded as though it were current.
The PDF export also checks whether its revision is still current while processing pages and around the final save. A stale export is discarded. Merely disabling the download button after it is clicked would not handle an edit made during generation.
Japanese input adds another boundary: do not validate half-finished IME composition as final text. The preview hook waits until composition finishes and the text settles before rebuilding.
4. A font family name is not enough
The regular preview draws glyph outlines from the actual font asset, and PDF export embeds that asset. This avoids relying on a fallback font that looks acceptable on screen but has a different shape or width in the file.
This implementation embeds the full Klee One font rather than a subset because its export path encountered missing composite glyphs with subsetting. That is a project-specific tradeoff, not a claim that all Japanese fonts require full embedding. The cost is a larger font payload; the benefit is preserving the checked glyph mapping.
Font checks should inspect the final asset. The project's tests check real glyphs for the 1,026 grade-listed kanji and inspect the embedded font stream in a generated PDF. Those checks complement visual review; they cannot establish whether a worksheet is pedagogically appropriate.
5. Make persistence a separate decision
A reusable layout does not necessarily need reusable personal text. Saving settings defaults to excluding the practice text, title and instruction. Including those fields is an explicit choice.
Storage errors are surfaced without disabling worksheet generation. Restored content is validated again against the current settings and font. Local storage is useful for repeat work, but it is neither cross-device sync nor permanent backup.
The same boundary applies to export names: the filename uses a timestamp instead of a learner's name. Keeping PDF creation local also does not mean the whole website makes no network requests; static assets and visit analytics are separate concerns.
A small regression checklist
- Change the text while export is running: the old file must not be offered as the current result.
- Use a multirow sequence near a page boundary: one repetition must remain intact.
- Resize the preview: physical PDF cell sizes must stay constant.
- Restore an old template: validate it against current rules.
- Deny local storage: generation must still work.
- Compare the downloaded PDF with the preview using the same input and font asset.
For a concrete example, the Kanji Drill worksheet editor exposes the cell size, tracing and preview controls discussed here. Start with 山川日月, then change one setting at a time. The interface is in Japanese.
The design question I would carry to another document tool is simple: which layer owns geometry, and how do you prove that every output belongs to the user's current edit?
Top comments (0)