When broken text and missing images appear in the same book, changing the encoding, filenames, and asset folders in one attempt is tempting. It is also a poor diagnostic method: even a successful export cannot reveal which change repaired the fault or whether one repair introduced another. A safer way to create a Kindle EPUB is to examine text and images independently, then join the two accepted results at one named package.
This walkthrough uses a 34-character Shift_JIS fixture and a synthetic three-chapter book with a cover. The text test proves a separately named UTF-8 readback. The image test follows four uses from XHTML references through the OPF manifest to files inside the ZIP. A pass on one side never stands in for a pass on the other.
Write two acceptance cards before repairing anything
Create one card for text and another for images. The text input is synthetic-source-shiftjis.txt; its expected result is a separately named file that reopens as UTF-8 with LF line endings, contains 34 characters, and decodes to the same string. The image inputs are three chapter files, three body-image uses, and one cover use. Their expected result is four XHTML references, four image resources in the manifest, four alt values, and zero unresolved files.
Do not make “EPUB export succeeded” the acceptance rule. A completion message can coexist with incorrect decoded text or an src that points nowhere. Record the starting filenames and digests. During a text repair, freeze all accepted image inputs. During an image repair, freeze the accepted UTF-8 manuscript.
These two cards also determine recovery. A changed character sends the work back to the encoding conversion. A missing path sends it back to the reference chain. Neither failure invites a broad rewrite of the other side.
Recover the 34-character string under a new name
The retained source measured 59 bytes. It was identified as Shift_JIS, decoded to 34 characters, and used LF line endings. Its SHA-256 was e770d422597d8473c36ae4b93273b994b11c471b1bff5605e6155f894ac51686. Preserve that byte sequence; saving a wrongly decoded display over the source may destroy the information needed for another interpretation.
The conversion was written to synthetic-restored-utf8.txt, not over the source. Reopening the result returned UTF-8, LF, and 34 characters. Its decoded text equaled the source text, and its SHA-256 was 96c6c6c2ad77c5a47dbafcedbb21a045a9c2356e9640b18fdddca1546c107b33.
Character count alone is insufficient. Two strings may have equal length while differing in a name, punctuation mark, or composed character. Acceptance therefore combines decoded equality, encoding, line ending, count, and preservation of the original digest. If any field differs, reject the working copy, return to the preserved source, and repeat conversion to another new name. Do not edit the prose during that retry, because doing so would give a difference two possible causes.
Trace all four image uses into the ZIP
The image specimen contained chapter-1.md through chapter-3.md plus cover.png. After export, the three chapter uses appeared in p001.xhtml, p002.xhtml, and p003.xhtml, pointing to ../Images/p001.png, p002.png, and p003.png. The cover document pointed to ../Images/cover.png.
Opening the package as a ZIP showed four image resources in the manifest: the cover and p001.png through p003.png. The XHTML contained four image references and four alt values. Resolving every relative path found zero missing resources. The result must be described as four packaged uses, not four different source photographs; the synthetic fixture reused copied test pixels. What matters here is that each output reference has a registered, present target.
For a broken path, compare the XHTML src, manifest href, and ZIP entry name in that order. Case, extension, and directory differences are separate failure points. Correct only the failed reference while leaving the accepted UTF-8 file untouched. Then rescan all four paths, because repairing one entry does not prove that the other three remained intact.
Bind both receipts to one exported file
The inspected output was studio-408-260903.100000.epub. Its SHA-256 was a5a0cbbbf8c70e01da5086e8a412cb8c498b3f466008c7515dddaf2a79101f33, and the ZIP contained 16 entries. Rune’s bounded local inspection returned valid=true with no listed issues.
The handoff record links that exact EPUB digest to the accepted UTF-8 digest and the four image paths. If the text receipt describes one manuscript revision while the image receipt describes another export, the book has not passed. Similar filenames are not enough; the digest identifies the candidate that was actually reopened.
Close the local test only when all of these statements are true for that candidate: the restored text is UTF-8/LF with 34 characters and equal decoded content; the package contains four references, four image resources, four alt values, and no missing target; and the local structural result is valid. The rules are conjunctive, not alternatives.
Roll back only the side that failed
If text fails while images pass, freeze the image files and all four paths, then repeat only the named conversion. If an image path fails while text passes, freeze the accepted 34-character UTF-8 file, then repair only the src, manifest record, or packaged filename responsible for the break. Changing both sides again would erase the diagnostic benefit.
Suppose only p002.png is missing. There is no reason to replace the cover or the other chapter assets. Keep the rejected EPUB, produce the repair under a new filename, and compare the two ZIP inventories. The expected difference is limited to the broken path. An unexplained change elsewhere keeps the candidate blocked.
Recovery still ends with a complete reopen. A zero exit code from the correcting command is not the final receipt. Recheck decoded text and all four asset routes from the new EPUB so that a local repair cannot silently invalidate the other accepted side.
Keep retailer and reader claims outside the local pass
The retained evidence establishes conversion and readback of a synthetic string, packaging and resolution of synthetic images, and a local structural check. It did not upload the book to KDP, obtain retailer acceptance, or measure rendering in a Kindle device or third-party reader. It also does not prove that a displayed image has an appropriate size, or that the underlying artwork has the required rights.
For production, send the same EPUB digest that passed locally into the retailer preview and the chosen devices. Record glyph appearance, page behavior, image proportions, and margins on a separate card. Keep copyright and licensing review separate from technical presence in the ZIP.
Rune Studio’s current public scope is available on the official product site, while general package structure belongs to the W3C EPUB 3.3 specification. Distinguishing product documentation, industry structure, and this measured fixture prevents a local result from becoming an unsupported publishing guarantee.
