): boolean {
let i = 0;
- if (
- bytes.length >= 3 &&
- bytes[0] === 0xef &&
- bytes[1] === 0xbb &&
- bytes[2] === 0xbf
- ) {
+ // No separate `bytes.length >= 3` clause: an index past the end of `bytes` reads as undefined, which can never equal one of the three real BOM byte values, so the equality checks alone already reject a too-short array.
+ if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
i = 3;
}
- while (i < bytes.length) {
+ // No `i < bytes.length` loop bound, and no separate `b === undefined` early return: bytes[i] reads as undefined once i runs past the end, undefined matches none of the whitespace comparisons below, and `undefined === 0x3c` is false -- so the loop's own final `return b === 0x3c` already answers "false" for an end-of-array read exactly like an explicit early return would, making a separate length or undefined check a redundant restatement of it.
+ for (;;) {
const b = bytes[i];
- if (b === undefined) {
- return false;
- }
if (b === 0x20 || b === 0x09 || b === 0x0a || b === 0x0d) {
i = i + 1;
continue;
}
return b === 0x3c;
}
- return false;
}
diff --git a/packages/epub-codec/src/path.test.ts b/packages/epub-codec/src/path.test.ts
index 59d6d135c..e04062050 100644
--- a/packages/epub-codec/src/path.test.ts
+++ b/packages/epub-codec/src/path.test.ts
@@ -41,4 +41,27 @@ describe("resolvePackagePath", () => {
"https://example.com/x.png",
);
});
+
+ it("recognises a scheme carrying every character class the scheme regex allows (letters, digits, +, ., -)", () => {
+ expect(resolvePackagePath("OEBPS", "epub+zip.v2-1://x")).toBe(
+ "epub+zip.v2-1://x",
+ );
+ });
+
+ it("does not treat a leading digit as a scheme, and resolves it as a relative reference instead", () => {
+ // A URI scheme must start with a letter -- a leading digit makes this a relative segment named "1http", not a scheme.
+ expect(resolvePackagePath("OEBPS", "1http://x")).toBe("OEBPS/1http:/x");
+ });
+
+ it('drops an explicit current-directory (".") segment', () => {
+ expect(resolvePackagePath("OEBPS", "./chapter1.xhtml")).toBe(
+ "OEBPS/chapter1.xhtml",
+ );
+ });
+
+ it("drops an empty segment produced by a doubled slash", () => {
+ expect(resolvePackagePath("OEBPS", "images//cover.png")).toBe(
+ "OEBPS/images/cover.png",
+ );
+ });
});
diff --git a/packages/epub-codec/src/read-cross-document.test.ts b/packages/epub-codec/src/read-cross-document.test.ts
new file mode 100644
index 000000000..2976ba8b5
--- /dev/null
+++ b/packages/epub-codec/src/read-cross-document.test.ts
@@ -0,0 +1,128 @@
+import { describe, expect, it } from "vitest";
+import { readEpubContent } from "./read";
+import { EPUB_MIME_TYPE } from "./format";
+import { zipPackage } from "./zip";
+
+// Regression coverage for buildCrossDocumentAnchorRegistry's own two ordering/self-reference edges (src/read.ts) -- neither is reachable through this package's own hand-authored fixtures (fixtureEpubMultichapterBytes has exactly one referrer per target, and never a document referencing itself by full path instead of a bare fragment), so both need a bespoke, minimal fixture built directly here.
+
+const CONTAINER_XML = `
+
+
+ urn:uuid:fixture-cross-doc
+ en
+
+
+
+
+
+ `;
+
+// The footnote-shaped referrer (epub:type="noteref") comes FIRST in spine order, a plain bookmark-shaped referrer to the SAME target comes SECOND -- the one ordering that actually exercises buildCrossDocumentAnchorRegistry's own "a footnote-shaped referrer always wins" guard: the guard only ever has anything to protect once an entry is ALREADY footnote-classified and a later referrer, read second, would otherwise downgrade it.
+const CHAPTER1_XHTML = `
+
+ Chapter One
+
+ Section 1B
+ A footnote reference1 and an explicit, full-path self-link back to this same document's own heading .
+
+`;
+
+// Also references chapter1's own "sec1b" heading by full path, genuinely cross-document from here -- this is what populates buildCrossDocumentAnchorRegistry's own targetsByHref["OEBPS/chapter1.xhtml"]["sec1b"] entry, the entry chapter1's own resolveHref self-reference guard (targetHref === sourceHref) must refuse to reuse for its OWN, different, same-document reference to the identical heading below.
+const CHAPTER2_XHTML = `
+
+ Chapter Two
+
+ A second, plain (non-noteref, non-class) reference to the same shared target , and a genuine cross-document link back to Chapter One's own Section 1B .
+
+`;
+
+const CHAPTER3_XHTML = `
+
+ Chapter Three
+
+ The shared target, referenced by both earlier chapters.
+
+`;
+
+function fixtureBytes(): Uint8Array {
+ const encoder = new TextEncoder();
+ return zipPackage([
+ ["mimetype", { bytes: encoder.encode(EPUB_MIME_TYPE), stored: true }],
+ ["META-INF/container.xml", { bytes: encoder.encode(CONTAINER_XML) }],
+ ["OEBPS/content.opf", { bytes: encoder.encode(CONTENT_OPF) }],
+ ["OEBPS/chapter1.xhtml", { bytes: encoder.encode(CHAPTER1_XHTML) }],
+ ["OEBPS/chapter2.xhtml", { bytes: encoder.encode(CHAPTER2_XHTML) }],
+ ["OEBPS/chapter3.xhtml", { bytes: encoder.encode(CHAPTER3_XHTML) }],
+ ]);
+}
+
+describe("buildCrossDocumentAnchorRegistry: a footnote-shaped referrer read first is never downgraded by a plain referrer read second", () => {
+ it("keeps the shared target, and the second (plain) referrer's own construct, footnote-classified", () => {
+ const document = readEpubContent(fixtureBytes());
+ expect(document.kind).toBe("wordprocessing");
+ if (document.kind !== "wordprocessing") return;
+
+ const chapter2Paragraph = document.sections[1]?.blocks[0];
+ expect(chapter2Paragraph?.kind).toBe("paragraph");
+ const secondReferrerExtent =
+ chapter2Paragraph?.kind === "paragraph"
+ ? chapter2Paragraph.constructs?.[0]
+ : undefined;
+ // Real code: still footnote (the first referrer's own classification wins). Mutated (guard always overwrites): downgraded to an ordinary internal "link", not an "anchor".
+ expect(secondReferrerExtent?.descriptor).toEqual({
+ kind: "anchor",
+ anchorType: "footnote",
+ name: "OEBPS/chapter3.xhtml#shared",
+ });
+
+ const chapter3Start = document.sections[2]?.blocks.find(
+ (b) => b.kind === "constructStart",
+ );
+ expect(chapter3Start?.kind).toBe("constructStart");
+ expect(
+ chapter3Start?.kind === "constructStart" && chapter3Start.descriptor,
+ ).toEqual({
+ kind: "anchor",
+ anchorType: "footnote",
+ name: "OEBPS/chapter3.xhtml#shared",
+ });
+ });
+});
+
+describe("buildCrossDocumentAnchorRegistry.resolveHref: an explicit full-path self-reference is not treated as cross-document", () => {
+ it("degrades to a plain, unresolved hyperlink rather than an internal link construct pointing at its own document", () => {
+ const document = readEpubContent(fixtureBytes());
+ expect(document.kind).toBe("wordprocessing");
+ if (document.kind !== "wordprocessing") return;
+
+ const chapter1Paragraph = document.sections[0]?.blocks.find(
+ (b) =>
+ b.kind === "paragraph" &&
+ b.runs.some((r) => r.text === "this same document's own heading"),
+ );
+ expect(chapter1Paragraph?.kind).toBe("paragraph");
+ if (chapter1Paragraph?.kind !== "paragraph") return;
+
+ // Real code: resolveHref refuses to treat a same-document target (targetHref === sourceHref) as a cross-document match, so appendAnchor's own target lookup comes back undefined and the href rides ContentRun.hyperlink verbatim, unresolved. Mutated (guard always returns the match): this would instead become an internal link construct naming "sec1b".
+ expect(chapter1Paragraph.runs).toContainEqual({
+ text: "this same document's own heading",
+ hyperlink: "chapter1.xhtml#sec1b",
+ });
+ const internalLinkToOwnHeading = (chapter1Paragraph.constructs ?? []).find(
+ (c) =>
+ c.descriptor.kind === "link" &&
+ c.descriptor.target.kind === "internal" &&
+ c.descriptor.target.anchor === "sec1b",
+ );
+ expect(internalLinkToOwnHeading).toBeUndefined();
+ });
+});
diff --git a/packages/epub-codec/src/read.test.ts b/packages/epub-codec/src/read.test.ts
index b31d0fe50..0e25515a3 100644
--- a/packages/epub-codec/src/read.test.ts
+++ b/packages/epub-codec/src/read.test.ts
@@ -1,10 +1,18 @@
import type { ContentBlock, ContentDocument } from "document-schema.js";
import { describe, expect, it } from "vitest";
+import {
+ EpubEmptySpineError,
+ EpubInvalidContainerError,
+ EpubInvalidMimetypeError,
+ EpubInvalidOpfError,
+} from "./diagnostics";
+import { EPUB_MIME_TYPE } from "./format";
import { readEpub, readEpubContent } from "./read";
import { fixtureEpub2Bytes } from "./test-support/epub2-fixture";
import { fixtureEpub3Bytes } from "./test-support/epub3-fixture";
import { fixtureEpubMultichapterBytes } from "./test-support/epub-multichapter-fixture";
import { fixtureEpub2MultichapterBytes } from "./test-support/epub2-multichapter-fixture";
+import { zipPackage } from "./zip";
function assertWordprocessing(
document: ContentDocument,
@@ -318,3 +326,97 @@ describe("readEpubContent: cross-document footnotes (ExaDev/documents.js#963)",
});
});
});
+
+describe("readEpubContent: the OCF container.xml entry", () => {
+ it("throws EpubInvalidContainerError with a real, non-empty message when the entry is missing entirely", () => {
+ const encoder = new TextEncoder();
+ const bytes = zipPackage([
+ ["mimetype", { bytes: encoder.encode(EPUB_MIME_TYPE), stored: true }],
+ ]);
+ try {
+ readEpubContent(bytes);
+ expect.unreachable("readEpubContent should have thrown");
+ } catch (error) {
+ expect(error).toBeInstanceOf(EpubInvalidContainerError);
+ expect(
+ error instanceof EpubInvalidContainerError ? error.message : undefined,
+ ).toBe("the zip carries no META-INF/container.xml entry");
+ }
+ });
+});
+
+describe("readEpubContent: the OPF rootfile container.xml names", () => {
+ it("throws EpubInvalidOpfError naming the missing rootfile's own path when the zip does not contain it", () => {
+ const encoder = new TextEncoder();
+ const container = `
+ T `;
+ const bytes = zipPackage([
+ ["mimetype", { bytes: encoder.encode(EPUB_MIME_TYPE), stored: true }],
+ ["META-INF/container.xml", { bytes: encoder.encode(container) }],
+ ["OEBPS/content.opf", { bytes: encoder.encode(opf) }],
+ ]);
+ expect(() => readEpubContent(bytes, { sink: () => undefined })).toThrow(
+ EpubEmptySpineError,
+ );
+ });
+});
+
+describe("readEpubContent: a section with no quarantined CSS residue", () => {
+ it("carries no source key at all, rather than an explicit undefined one", () => {
+ const document = readEpubContent(fixtureEpub3Bytes());
+ assertWordprocessing(document);
+ expect("source" in (document.sections[0] ?? {})).toBe(false);
+ });
+});
+
+describe("readEpubContent: the OCF mimetype entry", () => {
+ it("throws EpubInvalidMimetypeError when the mimetype entry is present but carries the wrong content", () => {
+ const encoder = new TextEncoder();
+ const bytes = zipPackage([
+ ["mimetype", { bytes: encoder.encode("text/plain"), stored: true }],
+ ]);
+ expect(() => readEpubContent(bytes)).toThrow(EpubInvalidMimetypeError);
+ });
+
+ it("throws EpubInvalidMimetypeError when the mimetype entry is missing entirely", () => {
+ const encoder = new TextEncoder();
+ const bytes = zipPackage([
+ ["META-INF/container.xml", { bytes: encoder.encode(" navigation document, and a footnote via the structured epub:type="footnote"/"noteref" idiom.
-// A PNG carrying only what src/image/dimensions.ts reads: the signature plus an IHDR chunk declaring 2x2 -- this package's own reader never walks past IHDR, so a real IDAT/IEND is not needed.
+// A PNG carrying only what src/image/dimensions.ts reads: the signature, then just enough of an IHDR chunk to declare 2x2 (width at byte offset 16, height at 20 -- PNG_HEADER_BYTES's own 24 bytes). Deliberately stops there: this package's own reader never looks past offset 24 for a PNG (no chunk-length or bit-depth/colour-type validation, no real IDAT/IEND), so writing bytes beyond it would carry no signal any reader here -- or any test of this fixture -- could ever observe.
function fakePng2x2(): Uint8Array {
- const bytes = new Uint8Array(33);
+ const bytes = new Uint8Array(24);
bytes.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], 0);
- const view = new DataView(bytes.buffer);
- view.setUint32(8, 13);
bytes.set([0x49, 0x48, 0x44, 0x52], 12);
- view.setUint32(16, 2);
- view.setUint32(20, 2);
- bytes.set([8, 6, 0, 0, 0], 24);
+ new DataView(bytes.buffer).setUint32(16, 2);
+ new DataView(bytes.buffer).setUint32(20, 2);
return bytes;
}
diff --git a/packages/epub-codec/src/test-support/fixtures.test.ts b/packages/epub-codec/src/test-support/fixtures.test.ts
new file mode 100644
index 000000000..44c56e80d
--- /dev/null
+++ b/packages/epub-codec/src/test-support/fixtures.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { EPUB_MIME_TYPE } from "../format";
+import { readImageDimensions } from "../image/dimensions";
+import { unzipPackage } from "../zip";
+import { assertMimetypeEntryLayout } from "./zip";
+import { fixtureEpub2Bytes } from "./epub2-fixture";
+import { fixtureEpub2MultichapterBytes } from "./epub2-multichapter-fixture";
+import { fixtureEpubMultichapterBytes } from "./epub-multichapter-fixture";
+import { fixtureEpub3Bytes } from "./epub3-fixture";
+
+// These fixture builders assemble a real zip byte-for-byte, entry path by entry path -- a wrong path or a mimetype entry that isn't genuinely stored uncompressed would still let most reading tests pass, since readEpubContent resolves paths through the OPF manifest rather than by any fixed position. Verified directly here against the fixture's own real byte output, the same way the pipeline-level "OCF-mandated mimetype-first/stored byte layout" test verifies the writer's output.
+describe.each([
+ ["fixtureEpub3Bytes", fixtureEpub3Bytes, ["OEBPS/nav.xhtml"], 6],
+ ["fixtureEpub2Bytes", fixtureEpub2Bytes, ["OEBPS/toc.ncx"], 5],
+ [
+ "fixtureEpubMultichapterBytes",
+ fixtureEpubMultichapterBytes,
+ ["OEBPS/nav.xhtml", "OEBPS/chapter2.xhtml"],
+ 6,
+ ],
+ [
+ "fixtureEpub2MultichapterBytes",
+ fixtureEpub2MultichapterBytes,
+ ["OEBPS/toc.ncx", "OEBPS/chapter2.xhtml"],
+ 6,
+ ],
+] as const)("%s", (_name, buildBytes, expectedPaths, expectedEntryCount) => {
+ it("stores the mimetype entry first and genuinely uncompressed", () => {
+ expect(() => {
+ assertMimetypeEntryLayout(buildBytes(), EPUB_MIME_TYPE);
+ }).not.toThrow();
+ });
+
+ it("zips every entry under its own real, distinct path, with its own real content", () => {
+ const entries = unzipPackage(buildBytes());
+ for (const path of expectedPaths) {
+ const bytes = entries[path];
+ if (bytes === undefined) {
+ throw new Error(`expected a "${path}" entry`);
+ }
+ // Real length, not merely present: fflate silently zips a missing `bytes` value as a genuine, present, zero-length entry rather than throwing.
+ expect(bytes.length).toBeGreaterThan(0);
+ }
+ // Every path is unique: a mutated path colliding with another real entry would silently overwrite it rather than fail outright, so the entry count itself is part of what proves no two declared paths collapsed into one.
+ expect(Object.keys(entries)).toHaveLength(expectedEntryCount);
+ });
+});
+
+describe("fixtureEpub3Bytes", () => {
+ it("builds a cover PNG whose IHDR genuinely declares 2x2 pixels", () => {
+ const entries = unzipPackage(fixtureEpub3Bytes());
+ const coverBytes = entries["OEBPS/images/cover.png"];
+ if (coverBytes === undefined) {
+ throw new Error("expected a cover.png entry");
+ }
+ expect(readImageDimensions(coverBytes)).toEqual({
+ widthPx: 2,
+ heightPx: 2,
+ });
+ });
+});
diff --git a/packages/epub-codec/src/test-support/zip.test.ts b/packages/epub-codec/src/test-support/zip.test.ts
new file mode 100644
index 000000000..6a4336513
--- /dev/null
+++ b/packages/epub-codec/src/test-support/zip.test.ts
@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import {
+ assertMimetypeEntryLayout,
+ definedByte,
+ localFileHeaderNames,
+ readUint16LE,
+ readUint32LE,
+} from "./zip";
+
+describe("definedByte", () => {
+ it("returns the value unchanged when it is a real byte", () => {
+ expect(definedByte(42)).toBe(42);
+ });
+
+ it("throws when the value is undefined", () => {
+ expect(() => definedByte(undefined)).toThrow(
+ "unreachable: expected a byte already known to be defined",
+ );
+ });
+});
+
+// A local file header's own fixed-position fields this module's readers walk: signature (4 bytes), then a run of fields irrelevant to these helpers up to compressed size at +18 (4 bytes), filename length at +26 (2 bytes), extra field length at +28 (2 bytes), the filename itself starting at +30, then the extra field, then the compressed data.
+function buildLocalFileHeader(
+ name: string,
+ options: {
+ readonly extraLength?: number;
+ readonly compressedSize?: number;
+ } = {},
+): number[] {
+ const nameBytes = Array.from(new TextEncoder().encode(name));
+ const extraLength = options.extraLength ?? 0;
+ const compressedSize = options.compressedSize ?? 0;
+ const header: number[] = new Array(30).fill(0);
+ header[0] = 0x50;
+ header[1] = 0x4b;
+ header[2] = 0x03;
+ header[3] = 0x04;
+ header[18] = compressedSize & 0xff;
+ header[19] = (compressedSize >> 8) & 0xff;
+ header[20] = (compressedSize >> 16) & 0xff;
+ header[21] = (compressedSize >> 24) & 0xff;
+ header[26] = nameBytes.length & 0xff;
+ header[27] = (nameBytes.length >> 8) & 0xff;
+ header[28] = extraLength & 0xff;
+ header[29] = (extraLength >> 8) & 0xff;
+ const extraBytes: number[] = new Array(extraLength).fill(0);
+ const compressedBytes: number[] = new Array(compressedSize).fill(0);
+ return [...header, ...nameBytes, ...extraBytes, ...compressedBytes];
+}
+
+function validMimetypeEntryBytes(content: string): Uint8Array {
+ const header: number[] = new Array(30).fill(0);
+ header[0] = 0x50;
+ header[1] = 0x4b;
+ header[2] = 0x03;
+ header[3] = 0x04;
+ header[26] = 8;
+ header[28] = 0;
+ const nameBytes = Array.from(new TextEncoder().encode("mimetype"));
+ const contentBytes = Array.from(new TextEncoder().encode(content));
+ return Uint8Array.from([...header, ...nameBytes, ...contentBytes]);
+}
+
+describe("readUint16LE", () => {
+ it("reads two bytes little-endian", () => {
+ expect(readUint16LE(Uint8Array.from([0x34, 0x12]), 0)).toBe(0x1234);
+ });
+
+ it("reads at a non-zero offset, not adjacent bytes on the wrong side of it", () => {
+ expect(readUint16LE(Uint8Array.from([0xaa, 0x12, 0x34]), 1)).toBe(0x3412);
+ });
+
+ it("throws when zero bytes remain at the offset", () => {
+ expect(() => readUint16LE(Uint8Array.from([]), 0)).toThrow(
+ "truncated zip bytes while reading a uint16 at offset 0",
+ );
+ });
+
+ it("throws when only the first of the two bytes remains", () => {
+ expect(() => readUint16LE(Uint8Array.from([0x12]), 0)).toThrow(
+ "truncated zip bytes while reading a uint16 at offset 0",
+ );
+ });
+});
+
+describe("readUint32LE", () => {
+ it("reads four bytes little-endian", () => {
+ expect(readUint32LE(Uint8Array.from([0x78, 0x56, 0x34, 0x12]), 0)).toBe(
+ 0x12345678,
+ );
+ });
+
+ it("throws when zero of the four bytes remain", () => {
+ expect(() => readUint32LE(Uint8Array.from([]), 0)).toThrow(
+ "truncated zip bytes while reading a uint32 at offset 0",
+ );
+ });
+
+ it("throws when only the first byte remains", () => {
+ expect(() => readUint32LE(Uint8Array.from([1]), 0)).toThrow(
+ "truncated zip bytes while reading a uint32 at offset 0",
+ );
+ });
+
+ it("throws when only the first two bytes remain", () => {
+ expect(() => readUint32LE(Uint8Array.from([1, 2]), 0)).toThrow(
+ "truncated zip bytes while reading a uint32 at offset 0",
+ );
+ });
+
+ it("throws when only the first three bytes remain", () => {
+ expect(() => readUint32LE(Uint8Array.from([1, 2, 3]), 0)).toThrow(
+ "truncated zip bytes while reading a uint32 at offset 0",
+ );
+ });
+});
+
+describe("localFileHeaderNames", () => {
+ it("skips a local file header's own extra field to locate the next entry", () => {
+ const bytes = Uint8Array.from([
+ ...buildLocalFileHeader("a.txt", { extraLength: 4 }),
+ ...buildLocalFileHeader("b.txt"),
+ ]);
+ expect(localFileHeaderNames(bytes)).toEqual(["a.txt", "b.txt"]);
+ });
+
+ it("skips a local file header's own compressed data to locate the next entry", () => {
+ const bytes = Uint8Array.from([
+ ...buildLocalFileHeader("a.txt", { compressedSize: 6 }),
+ ...buildLocalFileHeader("b.txt"),
+ ]);
+ expect(localFileHeaderNames(bytes)).toEqual(["a.txt", "b.txt"]);
+ });
+
+ it("stops cleanly once the byte range ends exactly at the last header's own end, with nothing left to read", () => {
+ const bytes = Uint8Array.from(buildLocalFileHeader("only.txt"));
+ expect(localFileHeaderNames(bytes)).toEqual(["only.txt"]);
+ });
+});
+
+describe("assertMimetypeEntryLayout", () => {
+ const mediaType = "application/epub+zip";
+
+ it("passes for a well-formed stored mimetype entry", () => {
+ expect(() => {
+ assertMimetypeEntryLayout(validMimetypeEntryBytes(mediaType), mediaType);
+ }).not.toThrow();
+ });
+
+ it("throws when the local file header signature is wrong", () => {
+ const bytes = validMimetypeEntryBytes(mediaType);
+ bytes[0] = 0;
+ expect(() => {
+ assertMimetypeEntryLayout(bytes, mediaType);
+ }).toThrow();
+ });
+
+ it("throws when the entry is not stored uncompressed", () => {
+ const bytes = validMimetypeEntryBytes(mediaType);
+ bytes[8] = 8;
+ expect(() => {
+ assertMimetypeEntryLayout(bytes, mediaType);
+ }).toThrow();
+ });
+
+ it("throws when the declared filename length is not exactly 8", () => {
+ const bytes = validMimetypeEntryBytes(mediaType);
+ bytes[26] = 9;
+ expect(() => {
+ assertMimetypeEntryLayout(bytes, mediaType);
+ }).toThrow();
+ });
+
+ it("throws when the declared extra field length is not zero", () => {
+ const bytes = validMimetypeEntryBytes(mediaType);
+ bytes[28] = 1;
+ expect(() => {
+ assertMimetypeEntryLayout(bytes, mediaType);
+ }).toThrow();
+ });
+
+ it("throws when the filename bytes do not spell mimetype", () => {
+ const bytes = validMimetypeEntryBytes(mediaType);
+ bytes[30] = "x".charCodeAt(0);
+ expect(() => {
+ assertMimetypeEntryLayout(bytes, mediaType);
+ }).toThrow();
+ });
+
+ it("throws when the entry content does not match the expected media type", () => {
+ const bytes = validMimetypeEntryBytes(mediaType);
+ expect(() => {
+ assertMimetypeEntryLayout(bytes, "something/else");
+ }).toThrow();
+ });
+});
diff --git a/packages/epub-codec/src/test-support/zip.ts b/packages/epub-codec/src/test-support/zip.ts
index 348979de4..59976d52d 100644
--- a/packages/epub-codec/src/test-support/zip.ts
+++ b/packages/epub-codec/src/test-support/zip.ts
@@ -2,33 +2,40 @@ import { expect } from "vitest";
// Little-endian integer readers over raw zip bytes, shared by every test that walks a zip's physical local-file-header layout rather than trusting a round trip through unzipPackage's Record (which makes no ordering promise of its own to test against). Never imported by src/index.ts and never reaches dist/ -- test-only, mirroring odf.js's and ooxml.js's own identical test-support convention.
+// Narrows a byte the caller already knows is defined by construction (a lower Uint8Array index than one already checked against undefined -- see readUint16LE/readUint32LE, the only two callers). A plain `as number` assertion would say the same thing to the type checker alone; this says it to a reader running the code too, and fails loudly instead of silently coercing to NaN in the impossible case where the premise is ever wrong.
+export function definedByte(value: number | undefined): number {
+ if (value === undefined) {
+ throw new Error("unreachable: expected a byte already known to be defined");
+ }
+ return value;
+}
+
export function readUint16LE(bytes: Uint8Array, offset: number): number {
- const b0 = bytes[offset];
const b1 = bytes[offset + 1];
- if (b0 === undefined || b1 === undefined) {
+ // No separate `bytes[offset] === undefined` check: a Uint8Array holds no gaps, so b1 (the higher index) reads as undefined whenever bytes[offset] would too, and never the other way around -- checking b1 alone already covers every truncation a b0 check would.
+ if (b1 === undefined) {
throw new Error(
`truncated zip bytes while reading a uint16 at offset ${offset}`,
);
}
- return b0 | (b1 << 8);
+ return definedByte(bytes[offset]) | (b1 << 8);
}
export function readUint32LE(bytes: Uint8Array, offset: number): number {
- const b0 = bytes[offset];
- const b1 = bytes[offset + 1];
- const b2 = bytes[offset + 2];
const b3 = bytes[offset + 3];
- if (
- b0 === undefined ||
- b1 === undefined ||
- b2 === undefined ||
- b3 === undefined
- ) {
+ // No separate bytes[offset]/[offset+1]/[offset+2] check: a Uint8Array holds no gaps, so b3 (the highest index) reads as undefined whenever any earlier byte would too, and never the other way around -- checking b3 alone already covers every truncation the other three checks would.
+ if (b3 === undefined) {
throw new Error(
`truncated zip bytes while reading a uint32 at offset ${offset}`,
);
}
- return (b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)) >>> 0;
+ return (
+ (definedByte(bytes[offset]) |
+ (definedByte(bytes[offset + 1]) << 8) |
+ (definedByte(bytes[offset + 2]) << 16) |
+ (b3 << 24)) >>>
+ 0
+ );
}
// Walks local file headers (signature 0x04034b50) from the start of a zip, in physical emission order, returning each entry's declared filename. This is the byte-level ordering guarantee zipPackage's ordered-entries contract exists to provide.
@@ -52,25 +59,18 @@ export function localFileHeaderNames(bytes: Uint8Array): string[] {
/**
* Asserts the exact byte layout EPUB 3.3 section 6.3 pins for a package's first entry: a "mimetype" part, stored uncompressed with a zero-length extra field, containing exactly "application/epub+zip", so a reader can identify the container as an EPUB from fixed byte offsets alone, without parsing the zip central directory first.
*/
+// No per-assertion description string is passed to any expect() call below: vitest's second `expect` argument only ever labels a failure message and is never itself part of the pass/fail decision, so a caller can observe no difference between any two description strings -- the assertions' own values (the signature bytes, 8, 0, "mimetype", mediaType) are what a malformed layout is actually caught by.
export function assertMimetypeEntryLayout(
bytes: Uint8Array,
mediaType: string,
): void {
const decoder = new TextDecoder();
- expect(
- Array.from(bytes.subarray(0, 4)),
- 'local file header signature "PK\\x03\\x04"',
- ).toEqual([0x50, 0x4b, 0x03, 0x04]);
- expect(readUint16LE(bytes, 8), "compression method (0 = stored)").toBe(0);
- expect(readUint16LE(bytes, 26), 'filename length ("mimetype".length)').toBe(
- 8,
- );
- expect(readUint16LE(bytes, 28), "extra field length").toBe(0);
- expect(decoder.decode(bytes.subarray(30, 38)), "filename bytes").toBe(
- "mimetype",
+ expect(Array.from(bytes.subarray(0, 4))).toEqual([0x50, 0x4b, 0x03, 0x04]);
+ expect(readUint16LE(bytes, 8)).toBe(0);
+ expect(readUint16LE(bytes, 26)).toBe(8);
+ expect(readUint16LE(bytes, 28)).toBe(0);
+ expect(decoder.decode(bytes.subarray(30, 38))).toBe("mimetype");
+ expect(decoder.decode(bytes.subarray(38, 38 + mediaType.length))).toBe(
+ mediaType,
);
- expect(
- decoder.decode(bytes.subarray(38, 38 + mediaType.length)),
- "mimetype content bytes",
- ).toBe(mediaType);
}
diff --git a/packages/epub-codec/src/util/base64.test.ts b/packages/epub-codec/src/util/base64.test.ts
index 5ccd869e8..d32b3997a 100644
--- a/packages/epub-codec/src/util/base64.test.ts
+++ b/packages/epub-codec/src/util/base64.test.ts
@@ -28,4 +28,13 @@ describe("bytesToBase64 / base64ToBytes", () => {
it("throws when a padding character appears where a data character is required", () => {
expect(() => base64ToBytes("A===")).toThrow("invalid base64 input");
});
+
+ it("throws when the padding character appears in the very first position", () => {
+ // Distinct from the existing "A===" case: this hits c0 === 255 specifically, not c1.
+ expect(() => base64ToBytes("=AAA")).toThrow("invalid base64 input");
+ });
+
+ it("strips embedded whitespace before decoding, matching the same input with it removed", () => {
+ expect(base64ToBytes("Y W\nJj")).toEqual(base64ToBytes("YWJj"));
+ });
});
diff --git a/packages/epub-codec/src/util/base64.ts b/packages/epub-codec/src/util/base64.ts
index 621d74ed0..1fca8b5e9 100644
--- a/packages/epub-codec/src/util/base64.ts
+++ b/packages/epub-codec/src/util/base64.ts
@@ -29,8 +29,8 @@ export function bytesToBase64(bytes: Uint8Array): string {
export function base64ToBytes(b64: string): Uint8Array {
const clean = b64.replace(/[^A-Za-z0-9+/=]/g, "");
const len = clean.length;
- const out = new Uint8Array(Math.floor((len * 3) / 4));
- let position = 0;
+ // Appended to a plain array and converted once at the end, rather than written into a pre-sized Uint8Array and trimmed with subarray(): the padding in the final quad means the exact decoded length isn't known until every quad has been walked, and a pre-sized buffer only needs to be an upper bound, so its own size is never itself part of what a caller can observe -- any sufficiently large size decodes identically once trimmed.
+ const bytes: number[] = [];
for (let i = 0; i < len; i += 4) {
const c0 = DECODE[clean.charCodeAt(i)] ?? 255;
const c1 = DECODE[clean.charCodeAt(i + 1)] ?? 255;
@@ -39,18 +39,15 @@ export function base64ToBytes(b64: string): Uint8Array {
if (c0 === 255 || c1 === 255) {
throw new Error("invalid base64 input");
}
- out[position] = (c0 << 2) | (c1 >> 4);
- position += 1;
+ bytes.push((c0 << 2) | (c1 >> 4));
if (code2 !== 61) {
const d2 = DECODE[code2] ?? 255;
- out[position] = ((c1 & 0x0f) << 4) | (d2 >> 2);
- position += 1;
+ bytes.push(((c1 & 0x0f) << 4) | (d2 >> 2));
if (code3 !== 61) {
const d3 = DECODE[code3] ?? 255;
- out[position] = ((d2 & 0x03) << 6) | d3;
- position += 1;
+ bytes.push(((d2 & 0x03) << 6) | d3);
}
}
}
- return out.subarray(0, position);
+ return new Uint8Array(bytes);
}
diff --git a/packages/epub-codec/src/write.test.ts b/packages/epub-codec/src/write.test.ts
new file mode 100644
index 000000000..2a883eba5
--- /dev/null
+++ b/packages/epub-codec/src/write.test.ts
@@ -0,0 +1,263 @@
+import type {
+ ContentDocument,
+ ContentSection,
+ DocumentTree,
+} from "document-schema.js";
+import * as documentSchema from "document-schema.js";
+import { describe, expect, it, vi } from "vitest";
+import {
+ EpubUnbalancedConstructMarkersError,
+ EpubUnsupportedDocumentKindError,
+} from "./diagnostics";
+import { readEpub } from "./read";
+import { bytesToBase64 } from "./util/base64";
+import { unzipPackage } from "./zip";
+import { writeEpub, writeEpubContent } from "./write";
+
+const PAGE = { widthPt: 595.28, heightPt: 841.89 };
+const MARGINS = { topPt: 72, rightPt: 72, bottomPt: 72, leftPt: 72 };
+
+function section(blocks: ContentSection["blocks"]): ContentSection {
+ return { pageSize: PAGE, margins: MARGINS, blocks };
+}
+
+function doc(sections: ContentSection[]): ContentDocument {
+ return { kind: "wordprocessing", metadata: {}, sections };
+}
+
+function decode(bytes: Uint8Array): string {
+ return new TextDecoder().decode(bytes);
+}
+
+function writtenOpf(document: ContentDocument): string {
+ const entries = unzipPackage(writeEpubContent(document));
+ const opf = entries["OEBPS/content.opf"];
+ expect(opf).toBeDefined();
+ return decode(opf ?? new Uint8Array());
+}
+
+describe("buildHead: the required element", () => {
+ it("writes a real <title> tag, not an empty one", () => {
+ const entries = unzipPackage(
+ writeEpubContent(
+ doc([section([{ kind: "paragraph", runs: [{ text: "Body." }] }])]),
+ ),
+ );
+ const sectionXml = entries["OEBPS/section1.xhtml"];
+ expect(sectionXml).toBeDefined();
+ expect(decode(sectionXml ?? new Uint8Array())).toContain("<title>");
+ });
+
+ it("carries the real title text inside the <title> element, not an empty one", () => {
+ const entries = unzipPackage(
+ writeEpubContent(
+ doc([
+ {
+ ...section([{ kind: "paragraph", runs: [{ text: "Body." }] }]),
+ },
+ ]),
+ ),
+ );
+ const sectionXml = decode(
+ entries["OEBPS/section1.xhtml"] ?? new Uint8Array(),
+ );
+ const titleMatch = /<title>([^<]*)<\/title>/u.exec(sectionXml);
+ expect(titleMatch?.[1]).toBeTruthy();
+ });
+});
+
+describe("imageExtension/imageMediaType: every ContentImageBlock format maps to its own real extension and media type", () => {
+ it.each([
+ ["png", "png", "image/png"],
+ ["jpeg", "jpg", "image/jpeg"],
+ ["svg", "svg", "image/svg+xml"],
+ ["gif", "gif", "image/gif"],
+ ] as const)(
+ "format %s -> extension .%s, media-type %s",
+ (format, ext, mediaType) => {
+ const document = doc([
+ section([
+ {
+ kind: "image",
+ format,
+ base64: bytesToBase64(new Uint8Array([1, 2, 3])),
+ widthPt: 10,
+ heightPt: 10,
+ },
+ ]),
+ ]);
+ const entries = unzipPackage(writeEpubContent(document));
+ expect(Object.keys(entries)).toContain(`OEBPS/images/img1.${ext}`);
+ const opf = writtenOpf(document);
+ expect(opf).toContain(`href="images/img1.${ext}"`);
+ expect(opf).toContain(`media-type="${mediaType}"`);
+ },
+ );
+});
+
+describe("writeEpubContent: registered-image numbering starts at 1, not 0 or -1", () => {
+ it("names the first registered image img1, not img0 or img-1", () => {
+ const document = doc([
+ section([
+ {
+ kind: "image",
+ format: "png",
+ base64: bytesToBase64(new Uint8Array([1, 2, 3])),
+ widthPt: 10,
+ heightPt: 10,
+ },
+ ]),
+ ]);
+ const entries = unzipPackage(writeEpubContent(document));
+ expect(Object.keys(entries)).toContain("OEBPS/images/img1.png");
+ expect(writtenOpf(document)).toContain('id="img1"');
+ });
+
+ it("numbers a second registered image img2, continuing from the first", () => {
+ const document = doc([
+ section([
+ {
+ kind: "image",
+ format: "png",
+ base64: bytesToBase64(new Uint8Array([1, 2, 3])),
+ widthPt: 10,
+ heightPt: 10,
+ },
+ {
+ kind: "image",
+ format: "png",
+ base64: bytesToBase64(new Uint8Array([4, 5, 6])),
+ widthPt: 10,
+ heightPt: 10,
+ },
+ ]),
+ ]);
+ const entries = unzipPackage(writeEpubContent(document));
+ expect(Object.keys(entries)).toContain("OEBPS/images/img1.png");
+ expect(Object.keys(entries)).toContain("OEBPS/images/img2.png");
+ });
+});
+
+describe("writeEpubContent: the OPF manifest's nav item", () => {
+ it('carries id="nav", href="nav.xhtml", the XHTML media-type, and properties="nav"', () => {
+ const opf = writtenOpf(
+ doc([section([{ kind: "paragraph", runs: [{ text: "x" }] }])]),
+ );
+ expect(opf).toContain('id="nav"');
+ expect(opf).toContain('href="nav.xhtml"');
+ expect(opf).toMatch(/id="nav"[^>]*media-type="application\/xhtml\+xml"/u);
+ expect(opf).toMatch(/id="nav"[^>]*properties="nav"/u);
+ });
+});
+
+describe("writeEpubContent: the OPF manifest's section items", () => {
+ it("carries the XHTML media-type and no properties attribute at all", () => {
+ const opf = writtenOpf(
+ doc([section([{ kind: "paragraph", runs: [{ text: "x" }] }])]),
+ );
+ expect(opf).toMatch(/id="s1"[^>]*media-type="application\/xhtml\+xml"/u);
+ const itemMatch = /<item[^>]*id="s1"[^>]*><\/item>/u.exec(opf);
+ expect(itemMatch?.[0]).toBeDefined();
+ expect(itemMatch?.[0]).not.toContain("properties=");
+ });
+});
+
+describe("writeEpubContent: the OPF manifest's image items", () => {
+ it("carries no properties attribute at all", () => {
+ const document = doc([
+ section([
+ {
+ kind: "image",
+ format: "png",
+ base64: bytesToBase64(new Uint8Array([1, 2, 3])),
+ widthPt: 10,
+ heightPt: 10,
+ },
+ ]),
+ ]);
+ const opf = writtenOpf(document);
+ const itemMatch = /<item[^>]*id="img1"[^>]*><\/item>/u.exec(opf);
+ expect(itemMatch?.[0]).toBeDefined();
+ expect(itemMatch?.[0]).not.toContain("properties=");
+ });
+});
+
+describe("writeEpubContent: the generated dc:identifier", () => {
+ it("is a real, non-empty urn:uuid value, not an empty string", () => {
+ const opf = writtenOpf(
+ doc([section([{ kind: "paragraph", runs: [{ text: "x" }] }])]),
+ );
+ const identifierMatch =
+ /<dc:identifier id="pub-id">([^<]*)<\/dc:identifier>/u.exec(opf);
+ expect(identifierMatch?.[1]).toMatch(/^urn:uuid:[0-9a-f-]{36}$/u);
+ });
+});
+
+describe("writeEpubContent: an unbalanced construct marker", () => {
+ it("wraps decomposeSection's own ConstructMarkerImbalanceError as EpubUnbalancedConstructMarkersError", () => {
+ const document = doc([
+ section([
+ { kind: "constructStart", descriptor: { kind: "division" } },
+ { kind: "paragraph", runs: [{ text: "never closed" }] },
+ // No matching constructEnd.
+ ]),
+ ]);
+ expect(() => writeEpubContent(document)).toThrow(
+ EpubUnbalancedConstructMarkersError,
+ );
+ });
+});
+
+describe("writeEpub: a non-wordprocessing DocumentTree", () => {
+ it("throws EpubUnsupportedDocumentKindError naming the tree's own kind", () => {
+ const tree: DocumentTree = {
+ kind: "spreadsheet",
+ metadata: {},
+ children: [],
+ };
+ try {
+ writeEpub(tree);
+ expect.unreachable("writeEpub should have thrown");
+ } catch (error) {
+ expect(error).toBeInstanceOf(EpubUnsupportedDocumentKindError);
+ expect(
+ error instanceof EpubUnsupportedDocumentKindError
+ ? error.kind
+ : undefined,
+ ).toBe("spreadsheet");
+ }
+ });
+
+ it("checks the tree's own kind before ever calling flattenTree, not after", () => {
+ const flattenTreeSpy = vi.spyOn(documentSchema, "flattenTree");
+ const tree: DocumentTree = {
+ kind: "spreadsheet",
+ metadata: {},
+ children: [],
+ };
+ expect(() => writeEpub(tree)).toThrow(EpubUnsupportedDocumentKindError);
+ expect(flattenTreeSpy).not.toHaveBeenCalled();
+ flattenTreeSpy.mockRestore();
+ });
+});
+
+describe("writeEpub: a wordprocessing DocumentTree", () => {
+ it("does not throw EpubUnsupportedDocumentKindError -- the kind check only ever rejects a non-wordprocessing tree", () => {
+ const tree = documentSchema.assembleTree(
+ doc([section([{ kind: "paragraph", runs: [{ text: "Hello." }] }])]),
+ );
+ expect(() => writeEpub(tree)).not.toThrow(EpubUnsupportedDocumentKindError);
+ });
+});
+
+describe("writeEpubContent: the written nav document's own toc hrefs match the spine order", () => {
+ it("reads back a multi-section EPUB with no NAV_SPINE_ORDER_MISMATCH residue", () => {
+ const document = doc([
+ section([{ kind: "paragraph", runs: [{ text: "Chapter one." }] }]),
+ section([{ kind: "paragraph", runs: [{ text: "Chapter two." }] }]),
+ section([{ kind: "paragraph", runs: [{ text: "Chapter three." }] }]),
+ ]);
+ const tree = readEpub(writeEpubContent(document));
+ expect(tree.source?.nav).toBeUndefined();
+ });
+});
diff --git a/packages/epub-codec/src/write.ts b/packages/epub-codec/src/write.ts
index 19d37e095..db21495d0 100644
--- a/packages/epub-codec/src/write.ts
+++ b/packages/epub-codec/src/write.ts
@@ -33,7 +33,6 @@ import type { XmlElement, XmlNode } from "./xml/node";
import { parseXml } from "./xml/parse";
import { packageFromEntries } from "./package-io/read";
import { serializePackage } from "./package-io/write";
-import type { ZipEntry } from "./zip";
// The public write entry points: writeEpubContent (the primary API -- a flat ContentDocument in, a minimal valid EPUB 3 out) and writeEpub (flattenTree composed on top, for a caller holding a DocumentTree instead -- matching markdown-codec's own dual-level API and readEpub's own tree/flat pairing in src/read.ts). Only EPUB 3 is ever written (ExaDev/documents.js#801's own explicit scope: EPUB 2 is read-only), and only a 'wordprocessing' document -- EPUB has no presentation/spreadsheet/drawing/formula analogue.
@@ -157,8 +156,12 @@ export function writeEpubContent(
const anchorSectionIndex = buildAnchorSectionIndex(document.sections);
- const sectionXhtml: { body: XmlElement; residueXml: string | undefined }[] =
- [];
+ // Carries the source ContentSection alongside its own written body/residue, not just the index: sectionXhtml is built in the same order and from the same array as document.sections, so a later re-lookup by index (document.sections[index]) would always be defined by construction anyway -- storing the reference directly here says so, rather than leaving a caller to re-derive (or defensively re-check) a fact already known at this point.
+ const sectionXhtml: {
+ section: ContentSection;
+ body: XmlElement;
+ residueXml: string | undefined;
+ }[] = [];
document.sections.forEach((section: ContentSection, index) => {
const sourceHref = sectionXhtmlPath(index);
try {
@@ -171,7 +174,7 @@ export function writeEpubContent(
// A same-format (EPUB-to-EPUB) restorable-fidelity re-emission of this package's own CSS residue (src/xhtml/read.ts's own STYLE_RESIDUE quarantine): the raw <link rel="stylesheet">/<style> elements this section's own source XHTML carried, re-parsed and spliced back into the written <head> verbatim, never interpreted -- matching this whole family's residue-channel contract (document-schema.js's own "a same-format writer may re-emit its own residue verbatim").
const residueXml =
section.source?.format === "epub" ? section.source.xml : undefined;
- sectionXhtml.push({ body, residueXml });
+ sectionXhtml.push({ section, body, residueXml });
} catch (error) {
if (error instanceof ConstructMarkerImbalanceError) {
throw new EpubUnbalancedConstructMarkersError(
@@ -220,50 +223,26 @@ export function writeEpubContent(
identifier: `urn:uuid:${crypto.randomUUID()}`,
});
- const entries: [string, ZipEntry][] = [
- [
- OCF_MIMETYPE_PATH,
- {
- bytes: new TextEncoder().encode(EPUB_MIME_TYPE),
- stored: true,
- },
- ],
- [
- OCF_CONTAINER_PATH,
- {
- bytes: new TextEncoder().encode(writeContainerXml(OPF_PATH)),
- },
- ],
- [OPF_PATH, { bytes: new TextEncoder().encode(opfXml) }],
- [
- NAV_PATH,
- {
- bytes: new TextEncoder().encode(writeNav3Document(navEntries)),
- },
- ],
+ // Plain [path, bytes] pairs, not ZipEntry: this array's only consumer is the entryBytes loop directly below, which reads nothing but .bytes -- packageFromEntries/serializePackage (ExaDev/documents.js#963's own Package model) own the actual OCF mimetype-first/stored-uncompressed byte layout now (see serializePackage's own hoist), so a per-entry "stored" flag has no reader left on this path.
+ const entries: [string, Uint8Array<ArrayBuffer>][] = [
+ [OCF_MIMETYPE_PATH, new TextEncoder().encode(EPUB_MIME_TYPE)],
+ [OCF_CONTAINER_PATH, new TextEncoder().encode(writeContainerXml(OPF_PATH))],
+ [OPF_PATH, new TextEncoder().encode(opfXml)],
+ [NAV_PATH, new TextEncoder().encode(writeNav3Document(navEntries))],
];
- sectionXhtml.forEach(({ body, residueXml }, index) => {
- const section = document.sections[index];
- const head = buildHead(
- section === undefined
- ? `Section ${String(index + 1)}`
- : sectionTitle(section, index),
- residueXml,
- );
+ sectionXhtml.forEach(({ section, body, residueXml }, index) => {
+ const head = buildHead(sectionTitle(section, index), residueXml);
const xml = `${XHTML_DOCTYPE}${buildXml([head, body])}</html>`;
- entries.push([
- sectionXhtmlPath(index),
- { bytes: new TextEncoder().encode(xml) },
- ]);
+ entries.push([sectionXhtmlPath(index), new TextEncoder().encode(xml)]);
});
for (const image of registeredImages) {
- entries.push([`${OPF_DIR}/${image.href}`, { bytes: image.bytes }]);
+ entries.push([`${OPF_DIR}/${image.href}`, image.bytes]);
}
// The lossless byte-level Package model (ExaDev/documents.js#963) is this function's own last step, not a separate entry point a caller must reach for themselves: writeEpubContent stays this package's one-shot ContentDocument-in/bytes-out convenience, but internally it now crosses the identical encodePackage boundary a caller reaching for decodePackage/encodePackage directly would. packageFromEntries classifies each entry exactly as parsePackage's own read-side classification would (an XML entry parsed into nodes, a binary entry kept as base64), which serializePackage then re-derives back to these same bytes -- a real round trip through the Package model, not a bypass of it, even though this writer (matching ooxml.js's own buildDocxPackageFromContent precedent: "each writer builds a fresh package rather than touching the decoded one") always builds a brand-new package rather than reusing one read.ts might have decoded.
const entryBytes: Record<string, Uint8Array<ArrayBuffer>> = {};
- for (const [path, entry] of entries) {
- entryBytes[path] = entry.bytes;
+ for (const [path, bytes] of entries) {
+ entryBytes[path] = bytes;
}
return serializePackage(packageFromEntries(entryBytes));
}
diff --git a/packages/epub-codec/src/xhtml/context.test.ts b/packages/epub-codec/src/xhtml/context.test.ts
new file mode 100644
index 000000000..51f74e24e
--- /dev/null
+++ b/packages/epub-codec/src/xhtml/context.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { EpubDiagnosticCodes } from "../diagnostics";
+import type { EpubDiagnostic } from "../diagnostics";
+import { isInertElement, reportInertElementSkip } from "./context";
+import type { XhtmlReadContext } from "./context";
+
+function fakeContext(sink: XhtmlReadContext["sink"]): XhtmlReadContext {
+ return {
+ resolveImage: () => undefined,
+ sink,
+ sourceHref: "OEBPS/chapter1.xhtml",
+ idElements: new Map(),
+ anchorTargets: new Map(),
+ resolveAnchorHref: () => undefined,
+ quoteDepth: 0,
+ };
+}
+
+describe("isInertElement", () => {
+ it("is true for script, template, style, and noscript", () => {
+ expect(isInertElement("script")).toBe(true);
+ expect(isInertElement("template")).toBe(true);
+ expect(isInertElement("style")).toBe(true);
+ expect(isInertElement("noscript")).toBe(true);
+ });
+
+ it("is false for an ordinary content element", () => {
+ expect(isInertElement("p")).toBe(false);
+ });
+});
+
+describe("reportInertElementSkip", () => {
+ it("reports a diagnostic for a skipped noscript element", () => {
+ const diagnostics: EpubDiagnostic[] = [];
+ reportInertElementSkip(
+ "noscript",
+ fakeContext((d) => diagnostics.push(d)),
+ );
+ expect(diagnostics).toHaveLength(1);
+ expect(diagnostics[0]).toMatchObject({
+ code: EpubDiagnosticCodes.NOSCRIPT_CONTENT_SKIPPED,
+ severity: "info",
+ href: "OEBPS/chapter1.xhtml",
+ });
+ expect(diagnostics[0]?.message).toContain("noscript");
+ });
+
+ it("reports nothing for script, template, or style -- only noscript's loss is worth naming", () => {
+ const diagnostics: EpubDiagnostic[] = [];
+ const context = fakeContext((d) => diagnostics.push(d));
+ reportInertElementSkip("script", context);
+ reportInertElementSkip("template", context);
+ reportInertElementSkip("style", context);
+ expect(diagnostics).toEqual([]);
+ });
+});
diff --git a/packages/epub-codec/src/xhtml/footnote.test.ts b/packages/epub-codec/src/xhtml/footnote.test.ts
new file mode 100644
index 000000000..e1f12c436
--- /dev/null
+++ b/packages/epub-codec/src/xhtml/footnote.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+import type { XmlElement } from "../xml/node";
+import {
+ isFootnoteAside,
+ isFootnoteReference,
+ sameDocumentFragment,
+} from "./footnote";
+
+function element(
+ tag: string,
+ attributes: { name: string; value: string }[] = [],
+): XmlElement {
+ return { type: "element", tag, attributes, children: [] };
+}
+
+describe("sameDocumentFragment", () => {
+ it("returns undefined for an undefined href", () => {
+ expect(sameDocumentFragment(undefined)).toBeUndefined();
+ });
+
+ it("returns undefined for an href with no leading '#'", () => {
+ expect(sameDocumentFragment("chapter2.xhtml")).toBeUndefined();
+ });
+
+ it("returns undefined for a cross-document href with a fragment", () => {
+ expect(sameDocumentFragment("chapter2.xhtml#note1")).toBeUndefined();
+ });
+
+ it("returns undefined for a bare '#' with no fragment name", () => {
+ expect(sameDocumentFragment("#")).toBeUndefined();
+ });
+
+ it("returns the single-character fragment name at the length-2 boundary", () => {
+ expect(sameDocumentFragment("#a")).toBe("a");
+ });
+
+ it("returns the fragment name for a real same-document href", () => {
+ expect(sameDocumentFragment("#note1")).toBe("note1");
+ });
+});
+
+describe("isFootnoteReference", () => {
+ it('recognises the structured EPUB 3 epub:type="noteref"', () => {
+ const anchor = element("a", [{ name: "epub:type", value: "noteref" }]);
+ const target = element("aside");
+ expect(isFootnoteReference(anchor, target)).toBe(true);
+ });
+
+ it("recognises noteref among several space-separated epub:type values", () => {
+ const anchor = element("a", [
+ { name: "epub:type", value: "footnote noteref" },
+ ]);
+ const target = element("aside");
+ expect(isFootnoteReference(anchor, target)).toBe(true);
+ });
+
+ it("recognises the EPUB 2 class idiom on the anchor itself", () => {
+ const anchor = element("a", [{ name: "class", value: "footnote" }]);
+ const target = element("aside");
+ expect(isFootnoteReference(anchor, target)).toBe(true);
+ });
+
+ it("recognises the EPUB 2 class idiom on the target when the anchor carries no signal", () => {
+ const anchor = element("a");
+ const target = element("aside", [{ name: "class", value: "noteref" }]);
+ expect(isFootnoteReference(anchor, target)).toBe(true);
+ });
+
+ it("is case-insensitive for the class idiom", () => {
+ const anchor = element("a", [{ name: "class", value: "FootNote" }]);
+ expect(isFootnoteReference(anchor, element("aside"))).toBe(true);
+ });
+
+ it("is false for an ordinary internal link with neither signal", () => {
+ const anchor = element("a", [{ name: "epub:type", value: "bodymatter" }]);
+ const target = element("section");
+ expect(isFootnoteReference(anchor, target)).toBe(false);
+ });
+});
+
+describe("isFootnoteAside", () => {
+ it('recognises epub:type="footnote" on an aside', () => {
+ expect(
+ isFootnoteAside(
+ element("aside", [{ name: "epub:type", value: "footnote" }]),
+ ),
+ ).toBe(true);
+ });
+
+ it('recognises epub:type="rearnote" on an aside', () => {
+ expect(
+ isFootnoteAside(
+ element("aside", [{ name: "epub:type", value: "rearnote" }]),
+ ),
+ ).toBe(true);
+ });
+
+ it("recognises footnote among several space-separated epub:type values, not requiring every value to match", () => {
+ expect(
+ isFootnoteAside(
+ element("aside", [{ name: "epub:type", value: "footnote bodymatter" }]),
+ ),
+ ).toBe(true);
+ });
+
+ it('is false for a non-aside element, even carrying epub:type="footnote"', () => {
+ expect(
+ isFootnoteAside(
+ element("div", [{ name: "epub:type", value: "footnote" }]),
+ ),
+ ).toBe(false);
+ });
+
+ it("is false for an aside with an unrelated epub:type", () => {
+ expect(
+ isFootnoteAside(
+ element("aside", [{ name: "epub:type", value: "bodymatter" }]),
+ ),
+ ).toBe(false);
+ });
+
+ it("is false for an aside with no epub:type at all", () => {
+ expect(isFootnoteAside(element("aside"))).toBe(false);
+ });
+});
diff --git a/packages/epub-codec/src/xhtml/footnote.ts b/packages/epub-codec/src/xhtml/footnote.ts
index e2a15ba20..01144e844 100644
--- a/packages/epub-codec/src/xhtml/footnote.ts
+++ b/packages/epub-codec/src/xhtml/footnote.ts
@@ -7,11 +7,10 @@ import { attrValue } from "../xml/query";
const FOOTNOTE_CLASS_PATTERN = /footnote|noteref/i;
-function epubTypeValues(element: XmlElement): readonly string[] {
+// Whether the element's epub:type attribute contains a token matching the given pattern. Tests the raw attribute value directly rather than splitting on whitespace first: every caller's own pattern (`/noteref/i`, `/footnote|rearnote/i`) is an unanchored substring match with no word-boundary assertion of its own, so pre-splitting into tokens changes nothing a caller could observe -- a match inside one split token is exactly the substring match testing the whole value would also find, and an empty token from splitting never matches any of these patterns either way.
+function hasEpubType(element: XmlElement, pattern: RegExp): boolean {
const value = attrValue(element, "epub:type");
- return value === undefined
- ? []
- : value.split(/\s+/u).filter((v) => v.length > 0);
+ return value !== undefined && pattern.test(value);
}
function hasFootnoteClass(element: XmlElement): boolean {
@@ -34,10 +33,7 @@ export function isFootnoteReference(
anchor: XmlElement,
target: XmlElement,
): boolean {
- const isStructuredNoteref = epubTypeValues(anchor).some((v) =>
- /noteref/i.test(v),
- );
- if (isStructuredNoteref) {
+ if (hasEpubType(anchor, /noteref/i)) {
return true;
}
return hasFootnoteClass(anchor) || hasFootnoteClass(target);
@@ -48,5 +44,5 @@ export function isFootnoteAside(element: XmlElement): boolean {
if (element.tag !== "aside") {
return false;
}
- return epubTypeValues(element).some((v) => /footnote|rearnote/i.test(v));
+ return hasEpubType(element, /footnote|rearnote/i);
}
diff --git a/packages/epub-codec/src/xhtml/inline.test.ts b/packages/epub-codec/src/xhtml/inline.test.ts
new file mode 100644
index 000000000..5ed3400d8
--- /dev/null
+++ b/packages/epub-codec/src/xhtml/inline.test.ts
@@ -0,0 +1,270 @@
+import { describe, expect, it, vi } from "vitest";
+import type { EpubDiagnostic } from "../diagnostics";
+import type { XhtmlReadContext } from "./context";
+import { buildInlineRuns } from "./inline";
+import { readXhtmlBody } from "./read";
+
+const CONTENT_WIDTH_PT = 451.28; // A4 minus 1in margins each side, matching src/read.ts's own default section geometry
+
+function body(inner: string): string {
+ return `<?xml version="1.0" encoding="utf-8"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops"><body>${inner}</body></html>`;
+}
+
+function read(
+ xml: string,
+ sink: (d: EpubDiagnostic) => void = () => undefined,
+) {
+ return readXhtmlBody(xml, {
+ resolveImage: () => undefined,
+ sink,
+ sourceHref: "chapter1.xhtml",
+ contentWidthPt: CONTENT_WIDTH_PT,
+ }).blocks;
+}
+
+describe("styledRun: a plain run carries none of the optional formatting keys", () => {
+ it("produces exactly {text} for a run with no bold/italic/underline/strike/fontFamily/verticalAlign/direction/hyperlink applying", () => {
+ const blocks = read(body("<p>plain text</p>"));
+ expect(blocks).toStrictEqual([
+ { kind: "paragraph", runs: [{ text: "plain text" }] },
+ ]);
+ });
+});
+
+describe("styledRun: each optional key is carried only when its own style applies", () => {
+ it("carries fontFamily for <code>/<kbd>/<samp> (the monospace style), and not otherwise", () => {
+ const blocks = read(
+ body("<p><code>c</code> <kbd>k</kbd> <samp>s</samp></p>"),
+ );
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [
+ { text: "c", fontFamily: "Courier New" },
+ { text: " " },
+ { text: "k", fontFamily: "Courier New" },
+ { text: " " },
+ { text: "s", fontFamily: "Courier New" },
+ ],
+ });
+ });
+
+ it("carries verticalAlign for <sub>/<sup>, and not otherwise", () => {
+ const blocks = read(body("<p>H<sub>2</sub>O<sup>+</sup></p>"));
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [
+ { text: "H" },
+ { text: "2", verticalAlign: "subscript" },
+ { text: "O" },
+ { text: "+", verticalAlign: "superscript" },
+ ],
+ });
+ });
+
+ it('carries direction for a dir="rtl" element, and not otherwise', () => {
+ const blocks = read(body('<p>plain <span dir="rtl">rtl text</span></p>'));
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "plain " }, { text: "rtl text", direction: "rtl" }],
+ });
+ });
+
+ it('carries direction for a dir="ltr" element too, not only "rtl"', () => {
+ const blocks = read(body('<p>plain <span dir="ltr">ltr text</span></p>'));
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "plain " }, { text: "ltr text", direction: "ltr" }],
+ });
+ });
+});
+
+describe("appendElement: each tag alias is matched individually, not only its sibling", () => {
+ it("<b> applies bold, the same as <strong>", () => {
+ const blocks = read(body("<p><b>bold</b></p>"));
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "bold", bold: true }],
+ });
+ });
+
+ it("<i> applies italic, the same as <em>", () => {
+ const blocks = read(body("<p><i>italic</i></p>"));
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "italic", italic: true }],
+ });
+ });
+
+ it("<strike> applies strike, the same as <s>/<del>", () => {
+ const blocks = read(body("<p><strike>gone</strike></p>"));
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "gone", strike: true }],
+ });
+ });
+
+ it("<del> applies strike, the same as <s>/<strike>", () => {
+ const blocks = read(body("<p><del>gone</del></p>"));
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "gone", strike: true }],
+ });
+ });
+});
+
+describe("buildInlineRuns: an empty text-like node produces no run", () => {
+ it("skips an empty CDATA section between two real text nodes, rather than inserting a blank run", () => {
+ const blocks = read(body("<p>before<![CDATA[]]>after</p>"));
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "before" }, { text: "after" }],
+ });
+ });
+});
+
+describe("appendImageFallback: an <img> reached while building a flat run sequence", () => {
+ it("names the real src attribute in its own diagnostic message, not a bare <img>", () => {
+ const sink = vi.fn<(d: EpubDiagnostic) => void>();
+ read(
+ body(
+ '<p><a href="unresolved.xhtml"><img src="pic.png" alt="a pic"/></a></p>',
+ ),
+ sink,
+ );
+ expect(sink).toHaveBeenCalledWith(
+ expect.objectContaining({ code: "epub/image-inline-unsupported" }),
+ );
+ const call = sink.mock.calls.find(
+ ([d]) => d.code === "epub/image-inline-unsupported",
+ );
+ expect(call?.[0].message).toContain('<img src="pic.png">');
+ });
+
+ it("degrades to a run carrying the alt text when alt is present", () => {
+ const blocks = read(
+ body('<p><span><img src="pic.png" alt="a pic"/></span></p>'),
+ );
+ const paragraph = blocks[0];
+ expect(paragraph?.kind).toBe("paragraph");
+ if (paragraph?.kind === "paragraph") {
+ expect(paragraph.runs).toContainEqual({ text: "a pic" });
+ }
+ });
+
+ it("adds no run at all when alt is absent", () => {
+ const blocks = read(
+ body(
+ '<p>before <a href="unresolved.xhtml"><img src="pic.png"/></a> after</p>',
+ ),
+ );
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "before " }, { text: " after" }],
+ });
+ });
+
+ it("adds no run at all when alt is present but empty", () => {
+ const blocks = read(
+ body(
+ '<p>before <a href="unresolved.xhtml"><img src="pic.png" alt=""/></a> after</p>',
+ ),
+ );
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "before " }, { text: " after" }],
+ });
+ });
+});
+
+describe("appendAnchor: an href resolving to no target", () => {
+ it("degrades an empty href (defined, zero-length) to plain nested content with no hyperlink at all", () => {
+ const blocks = read(body('<p><a href="">plain</a></p>'));
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "plain" }],
+ });
+ });
+
+ it("fires no LINK_TARGET_EXTERNAL_ONLY diagnostic for a genuine external URI (a real scheme present)", () => {
+ const sink = vi.fn();
+ read(body('<p><a href="https://example.com">site</a></p>'), sink);
+ expect(sink).not.toHaveBeenCalledWith(
+ expect.objectContaining({ code: "epub/link-target-external-only" }),
+ );
+ });
+
+ it("fires no LINK_TARGET_EXTERNAL_ONLY diagnostic for an unresolved same-document fragment", () => {
+ const sink = vi.fn();
+ const blocks = read(
+ body('<p><a href="#nonexistent-fragment">ghost link</a></p>'),
+ sink,
+ );
+ expect(sink).not.toHaveBeenCalledWith(
+ expect.objectContaining({ code: "epub/link-target-external-only" }),
+ );
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "ghost link", hyperlink: "#nonexistent-fragment" }],
+ });
+ });
+
+ it("fires LINK_TARGET_EXTERNAL_ONLY for a relative href with no scheme at its own start, even when a colon appears later in the string, naming the real href in its own message", () => {
+ const sink = vi.fn<(d: EpubDiagnostic) => void>();
+ read(body('<p><a href="images/note:1.xhtml">later chapter</a></p>'), sink);
+ expect(sink).toHaveBeenCalledWith(
+ expect.objectContaining({ code: "epub/link-target-external-only" }),
+ );
+ const call = sink.mock.calls.find(
+ ([d]) => d.code === "epub/link-target-external-only",
+ );
+ expect(call?.[0].message).toBe(
+ 'href "images/note:1.xhtml" carries no URI scheme and is not a same-document fragment; it is stored verbatim on ContentRun.hyperlink without resolution against the package\'s own manifest',
+ );
+ });
+});
+
+describe("appendAnchor: nested constructs inside a resolved anchor are rebased, not dropped", () => {
+ it("keeps an inner resolved anchor's own construct, shifted by the outer anchor's own already-pushed run count", () => {
+ const idElements = new Map();
+ const targets = new Map([
+ ["outer", { anchorType: "footnote" as const, name: "outer" }],
+ ["inner", { anchorType: "bookmark" as const, name: "inner" }],
+ ]);
+ const context: XhtmlReadContext = {
+ resolveImage: () => undefined,
+ sink: () => undefined,
+ sourceHref: "chapter1.xhtml",
+ idElements,
+ anchorTargets: targets,
+ resolveAnchorHref: (href) => targets.get(href.replace("#", "")),
+ quoteDepth: 0,
+ };
+ const innerAnchor = {
+ type: "element" as const,
+ tag: "a",
+ attributes: [{ name: "href", value: "#inner" }],
+ children: [{ type: "text" as const, value: "Y" }],
+ };
+ const outerAnchor = {
+ type: "element" as const,
+ tag: "a",
+ attributes: [{ name: "href", value: "#outer" }],
+ children: [{ type: "text" as const, value: "X" }, innerAnchor],
+ };
+ const result = buildInlineRuns([outerAnchor], {}, context);
+ expect(result.runs).toEqual([{ text: "X" }, { text: "Y" }]);
+ expect(result.constructs).toContainEqual({
+ descriptor: {
+ kind: "link",
+ target: { kind: "internal", anchor: "inner" },
+ },
+ startRun: 1,
+ endRun: 2,
+ });
+ expect(result.constructs).toContainEqual({
+ descriptor: { kind: "anchor", anchorType: "footnote", name: "outer" },
+ startRun: 0,
+ endRun: 2,
+ });
+ });
+});
diff --git a/packages/epub-codec/src/xhtml/inline.ts b/packages/epub-codec/src/xhtml/inline.ts
index d4f73d9a6..23ba382fe 100644
--- a/packages/epub-codec/src/xhtml/inline.ts
+++ b/packages/epub-codec/src/xhtml/inline.ts
@@ -26,11 +26,8 @@ function mergeStyle(
return { ...outer, ...inner };
}
-function styledRun(
- text: string,
- style: InlineStyle,
- hyperlink?: string,
-): ContentRun {
+// hyperlink is never set here: appendAnchor's own external-href fallback (below) spreads it directly onto each nested run instead, so this constructor never takes it as a parameter -- there is no call site that would ever pass one.
+function styledRun(text: string, style: InlineStyle): ContentRun {
const run: ContentRun = { text };
if (style.bold === true) run.bold = true;
if (style.italic === true) run.italic = true;
@@ -40,7 +37,6 @@ function styledRun(
if (style.verticalAlign !== undefined)
run.verticalAlign = style.verticalAlign;
if (style.direction !== undefined) run.direction = style.direction;
- if (hyperlink !== undefined) run.hyperlink = hyperlink;
return run;
}
@@ -171,8 +167,8 @@ function appendElement(
appendImageFallback(element, styled, context, runs);
return;
}
- case "span":
default:
+ // Covers "span" (no formatting of its own) along with every tag this switch does not name explicitly.
appendNested(element, styled, context, runs, constructs);
}
}
diff --git a/packages/epub-codec/src/xhtml/link-target.test.ts b/packages/epub-codec/src/xhtml/link-target.test.ts
new file mode 100644
index 000000000..d6fd63ffc
--- /dev/null
+++ b/packages/epub-codec/src/xhtml/link-target.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { resolveHrefTarget } from "./link-target";
+
+describe("resolveHrefTarget", () => {
+ it("returns undefined for an empty href", () => {
+ expect(resolveHrefTarget("OEBPS/chapter1.xhtml", "")).toBeUndefined();
+ });
+
+ it("returns undefined for a scheme-carrying (external) href", () => {
+ expect(
+ resolveHrefTarget("OEBPS/chapter1.xhtml", "https://example.com#x"),
+ ).toBeUndefined();
+ });
+
+ it("returns undefined for an href with no fragment at all", () => {
+ expect(
+ resolveHrefTarget("OEBPS/chapter1.xhtml", "chapter2.xhtml"),
+ ).toBeUndefined();
+ });
+
+ it("returns undefined for an href whose fragment is empty (a trailing bare '#')", () => {
+ expect(
+ resolveHrefTarget("OEBPS/chapter1.xhtml", "chapter2.xhtml#"),
+ ).toBeUndefined();
+ });
+
+ it("resolves a same-document fragment against sourceHref itself", () => {
+ expect(resolveHrefTarget("OEBPS/chapter1.xhtml", "#note1")).toEqual({
+ targetHref: "OEBPS/chapter1.xhtml",
+ fragment: "note1",
+ });
+ });
+
+ it("resolves a cross-document fragment against sourceHref's own directory", () => {
+ expect(
+ resolveHrefTarget("OEBPS/chapter1.xhtml", "chapter2.xhtml#note1"),
+ ).toEqual({
+ targetHref: "OEBPS/chapter2.xhtml",
+ fragment: "note1",
+ });
+ });
+
+ it("resolves a hash appearing at index 1, distinguishing 'no hash found' from 'hash found at a small index'", () => {
+ expect(resolveHrefTarget("OEBPS/chapter1.xhtml", "a#frag")).toEqual({
+ targetHref: "OEBPS/a",
+ fragment: "frag",
+ });
+ });
+
+ it("resolves a subdirectory path portion with its own fragment", () => {
+ expect(
+ resolveHrefTarget("OEBPS/chapter1.xhtml", "images/notes.xhtml#n2"),
+ ).toEqual({
+ targetHref: "OEBPS/images/notes.xhtml",
+ fragment: "n2",
+ });
+ });
+});
diff --git a/packages/epub-codec/src/xhtml/link-target.ts b/packages/epub-codec/src/xhtml/link-target.ts
index f7e4f4312..bef09a5cd 100644
--- a/packages/epub-codec/src/xhtml/link-target.ts
+++ b/packages/epub-codec/src/xhtml/link-target.ts
@@ -14,7 +14,8 @@ export function resolveHrefTarget(
sourceHref: string,
href: string,
): HrefTarget | undefined {
- if (href.length === 0 || URI_SCHEME_PATTERN.test(href)) {
+ // No separate `href.length === 0` guard: an empty href can never contain "#", so the hashIndex check immediately below already returns undefined for it -- a length check first would only duplicate that.
+ if (URI_SCHEME_PATTERN.test(href)) {
return undefined;
}
const hashIndex = href.indexOf("#");
diff --git a/packages/epub-codec/src/xhtml/list-id.test.ts b/packages/epub-codec/src/xhtml/list-id.test.ts
index 884c02c5e..400ff7cc8 100644
--- a/packages/epub-codec/src/xhtml/list-id.test.ts
+++ b/packages/epub-codec/src/xhtml/list-id.test.ts
@@ -24,4 +24,17 @@ describe("mintListNumId / parseListNumId", () => {
expect(parseListNumId("list1")).toBeUndefined();
expect(parseListNumId("md1:bullet")).toBeUndefined();
});
+
+ it("mints a bullet list without an 'ordered@' suffix even when a start is given", () => {
+ // A bullet list has no start concept -- the type === "ordered" guard must actually gate this.
+ expect(mintListNumId(4, { type: "bullet", start: 5 })).toBe("epub4:bullet");
+ });
+
+ it("parses an ordered numId with no @start suffix as having no explicit start", () => {
+ expect(parseListNumId("epub1:ordered")).toEqual({ type: "ordered" });
+ });
+
+ it("ignores an @start suffix on a bullet numId -- start only ever applies to ordered", () => {
+ expect(parseListNumId("epub1:bullet@5")).toEqual({ type: "bullet" });
+ });
});
diff --git a/packages/epub-codec/src/xhtml/read.test.ts b/packages/epub-codec/src/xhtml/read.test.ts
index 1ef49f67a..a06837649 100644
--- a/packages/epub-codec/src/xhtml/read.test.ts
+++ b/packages/epub-codec/src/xhtml/read.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it, vi } from "vitest";
import type { EpubDiagnostic } from "../diagnostics";
-import { readXhtmlBody } from "./read";
+import { readXhtmlBody, scanXhtmlAnchors } from "./read";
const CONTENT_WIDTH_PT = 451.28; // A4 minus 1in margins each side, matching src/read.ts's own default section geometry
@@ -195,6 +195,22 @@ describe("hyperlinks", () => {
});
});
+describe("scanXhtmlAnchors", () => {
+ it("finds an id-bearing element at any depth, not just a direct child of <body>", () => {
+ const xml = body('<div><section><p id="deep">text</p></section></div>');
+ const scan = scanXhtmlAnchors(xml);
+ expect(scan.idElements.has("deep")).toBe(true);
+ });
+
+ it("collects only real <a href> elements, never a same-tagged href-less <a> nor an unrelated element that merely carries an href attribute", () => {
+ const xml = body(
+ '<div href="#bogus">not a link</div><a>no href</a><a href="#target">real link</a>',
+ );
+ const scan = scanXhtmlAnchors(xml);
+ expect(scan.anchors).toHaveLength(1);
+ });
+});
+
describe("lists", () => {
it("maps a simple unordered list", () => {
const blocks = read(body("<ul><li>a</li><li>b</li></ul>"));
@@ -255,7 +271,11 @@ describe("lists", () => {
},
]);
expect(sink).toHaveBeenCalledWith(
- expect.objectContaining({ code: "epub/list-content-outside-item" }),
+ expect.objectContaining({
+ code: "epub/list-content-outside-item",
+ message:
+ "content sits directly inside a <ul> rather than inside an <li> (not valid HTML5); recovered as a continuation of the preceding <li>'s own content",
+ }),
);
});
@@ -297,7 +317,11 @@ describe("lists", () => {
},
]);
expect(sink).toHaveBeenCalledWith(
- expect.objectContaining({ code: "epub/list-content-outside-item" }),
+ expect.objectContaining({
+ code: "epub/list-content-outside-item",
+ message:
+ "content sits directly inside a <ul> before its first <li> (not valid HTML5); recovered as ordinary content immediately before the list, inheriting whatever list membership its own enclosing context already carries (none, unless this <ul> is itself nested inside another list's <li>)",
+ }),
);
});
@@ -948,10 +972,23 @@ describe("definition lists", () => {
expect(sink).toHaveBeenCalledWith(
expect.objectContaining({
code: "epub/definition-list-content-outside-entry",
+ message:
+ "content sits directly inside a <dl> (or one of its <div> wrappers) outside any dt/dd (not valid HTML5); recovered as ordinary content -- a non-conformant wrapper's own dt/dd children, if any, lose their distinct term/definition treatment and degrade to plain concatenated text",
}),
);
});
+ it("flushes stray content sitting before a <div> wrapper as its own block, ahead of the div's own dt/dd content", () => {
+ const blocks = read(
+ body("<dl>stray<div><dt>Term</dt><dd>Definition</dd></div></dl>"),
+ );
+ expect(blocks).toEqual([
+ { kind: "paragraph", runs: [{ text: "stray" }] },
+ { kind: "paragraph", runs: [{ text: "Term" }] },
+ { kind: "paragraph", runs: [{ text: "Definition" }], indentLeftPt: 36 },
+ ]);
+ });
+
it("recovers stray text sitting before the very first dt inside a <dl>, with a diagnostic", () => {
const sink = vi.fn();
const blocks = read(body("<dl>stray<dt>Term</dt></dl>"), sink);
@@ -1101,6 +1138,70 @@ describe("tables", () => {
]);
});
+ it("treats a zero or negative colspan as absent, rather than a real span", () => {
+ const table = read(
+ body(
+ '<table><tr><td colspan="0">a</td><td colspan="-1">b</td></tr></table>',
+ ),
+ ).find((b) => b.kind === "table");
+ if (table === undefined) {
+ throw new Error("expected a table block");
+ }
+ for (const cell of table.rows[0]?.cells ?? []) {
+ expect(Object.hasOwn(cell, "colSpan")).toBe(false);
+ }
+ });
+
+ it("honours a cell's own rowspan attribute, distinctly from colspan", () => {
+ const table = read(
+ body('<table><tr><td rowspan="3">tall</td></tr></table>'),
+ ).find((b) => b.kind === "table");
+ if (table === undefined) {
+ throw new Error("expected a table block");
+ }
+ const cell = table.rows[0]?.cells[0];
+ expect(cell?.rowSpan).toBe(3);
+ expect(
+ cell === undefined ? undefined : Object.hasOwn(cell, "colSpan"),
+ ).toBe(false);
+ });
+
+ it("carries neither colSpan nor rowSpan on a cell with no such attribute, rather than an undefined-valued key", () => {
+ const table = read(body("<table><tr><td>plain</td></tr></table>")).find(
+ (b) => b.kind === "table",
+ );
+ if (table === undefined) {
+ throw new Error("expected a table block");
+ }
+ const cell = table.rows[0]?.cells[0];
+ if (cell === undefined) {
+ throw new Error("expected a cell");
+ }
+ expect(Object.hasOwn(cell, "colSpan")).toBe(false);
+ expect(Object.hasOwn(cell, "rowSpan")).toBe(false);
+ });
+
+ it("gives an empty table (no cells at all) the full content width, rather than dividing by a zero column count", () => {
+ const table = read(body("<table></table>")).find((b) => b.kind === "table");
+ if (table === undefined) {
+ throw new Error("expected a table block");
+ }
+ expect(table.rows).toEqual([]);
+ expect(table.columnWidthsPt).toEqual([CONTENT_WIDTH_PT]);
+ });
+
+ it("recovers a stray <ul> sitting directly inside a <table> (not inside any row group) as a genuinely nested list, not as if it were itself a row group", () => {
+ // Only tr/thead/tbody/tfoot are ever treated as row-group-shaped -- a <ul> here must be routed through readContainerChildren's own block-level dispatch (readList, producing a real `list` membership) rather than through collectRowGroupRows, which would instead flatten straight to the <li>'s own bare content with no list membership at all.
+ const blocks = read(
+ body("<table><ul><li>item</li></ul><tr><td>x</td></tr></table>"),
+ );
+ expect(blocks[0]).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "item" }],
+ list: { numId: "epub1:bullet", level: 0, itemId: "item1" },
+ });
+ });
+
it("reads rows nested inside thead/tbody", () => {
const blocks = read(
body(
@@ -1358,7 +1459,11 @@ describe("tables", () => {
columnWidthsPt: [CONTENT_WIDTH_PT],
});
expect(sink).toHaveBeenCalledWith(
- expect.objectContaining({ code: "epub/table-caption-unsupported" }),
+ expect.objectContaining({
+ code: "epub/table-caption-unsupported",
+ message:
+ "<caption> has no document-schema.js table-caption field to carry its own distinct tag; read as an ordinary paragraph immediately before the table",
+ }),
);
});
@@ -1505,6 +1610,32 @@ describe("tables", () => {
columnWidthsPt: [CONTENT_WIDTH_PT / 2, CONTENT_WIDTH_PT / 2],
},
]);
+ expect(sink).toHaveBeenCalledWith(
+ expect.objectContaining({
+ code: "epub/table-row-content-outside-cell",
+ message:
+ "content sits directly inside a <tr> rather than inside a <td>/<th> (not valid HTML5); recovered as its own cell in the row's own column sequence",
+ }),
+ );
+ });
+
+ it("recovers stray text sitting directly inside a <tr> after its last <td> as its own trailing cell, with a diagnostic", () => {
+ const sink = vi.fn();
+ const blocks = read(body("<table><tr><td>x</td>stray</tr></table>"), sink);
+ expect(blocks).toEqual([
+ {
+ kind: "table",
+ rows: [
+ {
+ cells: [
+ { blocks: [{ kind: "paragraph", runs: [{ text: "x" }] }] },
+ { blocks: [{ kind: "paragraph", runs: [{ text: "stray" }] }] },
+ ],
+ },
+ ],
+ columnWidthsPt: [CONTENT_WIDTH_PT / 2, CONTENT_WIDTH_PT / 2],
+ },
+ ]);
expect(sink).toHaveBeenCalledWith(
expect.objectContaining({ code: "epub/table-row-content-outside-cell" }),
);
@@ -1580,6 +1711,47 @@ describe("tables", () => {
);
});
+ it("recovers stray text sitting directly inside a <table> outside any row/caption, with a diagnostic", () => {
+ const sink = vi.fn();
+ const blocks = read(body("<table>stray<tr><td>x</td></tr></table>"), sink);
+ expect(blocks).toEqual([
+ { kind: "paragraph", runs: [{ text: "stray" }] },
+ {
+ kind: "table",
+ rows: [
+ {
+ cells: [{ blocks: [{ kind: "paragraph", runs: [{ text: "x" }] }] }],
+ },
+ ],
+ columnWidthsPt: [CONTENT_WIDTH_PT],
+ },
+ ]);
+ expect(sink).toHaveBeenCalledWith(
+ expect.objectContaining({ code: "epub/table-content-unrecognized" }),
+ );
+ });
+
+ it("recovers a stray <img> sitting directly inside a <colgroup> as its own real image block, not degraded to alt text", () => {
+ // Distinguishes routing a <colgroup>'s own stray content through collectColgroupStrayContent (a flat list of the colgroup's OWN children, so a stray <img> reaches readContainerChildren's block-level dispatch and becomes a real ContentImageBlock) from mistakenly treating the whole <colgroup> element itself as one inline stray node (which would instead degrade the same <img> to alt text via buildInlineRuns' own inline-image fallback).
+ const bytes = fakePng(96, 96);
+ const sink = vi.fn();
+ const { blocks } = readXhtmlBody(
+ body(
+ '<table><colgroup><img src="a.png" alt="colimg"/><col/></colgroup><tr><td>x</td></tr></table>',
+ ),
+ {
+ resolveImage: (href) => (href === "a.png" ? bytes : undefined),
+ sink,
+ sourceHref: "chapter1.xhtml",
+ contentWidthPt: CONTENT_WIDTH_PT,
+ },
+ );
+ expect(blocks[0]).toMatchObject({ kind: "image" });
+ expect(sink).toHaveBeenCalledWith(
+ expect.objectContaining({ code: "epub/table-content-unrecognized" }),
+ );
+ });
+
it("skips a <colgroup>/<script> sitting directly inside a <table>, firing no diagnostic", () => {
const sink = vi.fn();
const blocks = read(
@@ -1607,13 +1779,17 @@ describe("tables", () => {
);
});
- it("skips a <noscript> sitting directly inside a <table>, but reports the drop unlike script", () => {
- const sink = vi.fn();
+ it("skips a <noscript> sitting directly inside a <table>, reporting the drop exactly once, alongside a stray <p> that alone triggers the unrecognized-content diagnostic", () => {
+ // If a <noscript> sitting directly inside a <table> ever fell through this guard un-skipped, it would still eventually be skipped by buildInlineRuns' own universal inert-element safety net once fed through the stray-content recovery path -- so the ONLY observable trace of the guard being bypassed is the drop being reported TWICE (once from each guard) rather than once.
+ const sink = vi.fn<(d: EpubDiagnostic) => void>();
const blocks = read(
- body("<table><noscript>Enable JS</noscript><tr><td>a</td></tr></table>"),
+ body(
+ "<table><noscript>Enable JS</noscript><p>stray</p><tr><td>a</td></tr></table>",
+ ),
sink,
);
expect(blocks).toEqual([
+ { kind: "paragraph", runs: [{ text: "stray" }] },
{
kind: "table",
rows: [
@@ -1624,23 +1800,28 @@ describe("tables", () => {
columnWidthsPt: [CONTENT_WIDTH_PT],
},
]);
- expect(sink).not.toHaveBeenCalledWith(
- expect.objectContaining({ code: "epub/table-content-unrecognized" }),
+ const noscriptCalls = sink.mock.calls.filter(
+ ([diagnostic]) => diagnostic.code === "epub/noscript-content-skipped",
);
- expect(sink).toHaveBeenCalledWith(
- expect.objectContaining({ code: "epub/noscript-content-skipped" }),
+ expect(noscriptCalls).toHaveLength(1);
+ const unrecognizedCalls = sink.mock.calls.filter(
+ ([diagnostic]) => diagnostic.code === "epub/table-content-unrecognized",
);
+ expect(unrecognizedCalls).toHaveLength(1);
});
- it("skips a <noscript> sitting directly inside a <colgroup>, but reports the drop unlike script", () => {
- const sink = vi.fn();
+ it("skips a <noscript> sitting directly inside a <colgroup>, reporting the drop exactly once, alongside a stray <p> that alone triggers the unrecognized-content diagnostic", () => {
+ // A <col/> and a <noscript> together rule out any single mutant that either stops recognising a real <col/> (which would wrongly turn up as unrecognized content) or stops skipping the <noscript> via its own dedicated inert-element guard (which would report the identical drop a SECOND time, once from that guard and once more from buildInlineRuns' own universal inert-element safety net once the un-skipped node is fed through it).
+ const sink = vi.fn<(d: EpubDiagnostic) => void>();
const blocks = read(
body(
- "<table><colgroup><col/><noscript>Enable JS</noscript></colgroup><tr><td>a</td></tr></table>",
+ // <col> carries no legal children of its own -- a stray text node here is a synthetic probe, not real markup, checking that a genuinely recognised <col> is silently skipped WHOLESALE (its own content never even reaches the recovery path at all) rather than merely having its outer tag treated like any other unrecognised stray element.
+ "<table><colgroup><col>faketext</col><noscript>Enable JS</noscript><p>stray</p></colgroup><tr><td>a</td></tr></table>",
),
sink,
);
expect(blocks).toEqual([
+ { kind: "paragraph", runs: [{ text: "stray" }] },
{
kind: "table",
rows: [
@@ -1651,23 +1832,26 @@ describe("tables", () => {
columnWidthsPt: [CONTENT_WIDTH_PT],
},
]);
- expect(sink).not.toHaveBeenCalledWith(
- expect.objectContaining({ code: "epub/table-content-unrecognized" }),
+ const noscriptCalls = sink.mock.calls.filter(
+ ([diagnostic]) => diagnostic.code === "epub/noscript-content-skipped",
);
- expect(sink).toHaveBeenCalledWith(
- expect.objectContaining({ code: "epub/noscript-content-skipped" }),
+ expect(noscriptCalls).toHaveLength(1);
+ const unrecognizedCalls = sink.mock.calls.filter(
+ ([diagnostic]) => diagnostic.code === "epub/table-content-unrecognized",
);
+ expect(unrecognizedCalls).toHaveLength(1);
});
- it("skips a <noscript> sitting directly inside a <tbody>, but reports the drop unlike script", () => {
- const sink = vi.fn();
+ it("skips a <noscript> sitting directly inside a <tbody>, reporting the drop exactly once, alongside a stray <p> that alone triggers the unrecognized-content diagnostic", () => {
+ const sink = vi.fn<(d: EpubDiagnostic) => void>();
const blocks = read(
body(
- "<table><tbody><noscript>Enable JS</noscript><tr><td>a</td></tr></tbody></table>",
+ "<table><tbody><noscript>Enable JS</noscript><p>stray</p><tr><td>a</td></tr></tbody></table>",
),
sink,
);
expect(blocks).toEqual([
+ { kind: "paragraph", runs: [{ text: "stray" }] },
{
kind: "table",
rows: [
@@ -1678,12 +1862,14 @@ describe("tables", () => {
columnWidthsPt: [CONTENT_WIDTH_PT],
},
]);
- expect(sink).not.toHaveBeenCalledWith(
- expect.objectContaining({ code: "epub/table-content-unrecognized" }),
+ const noscriptCalls = sink.mock.calls.filter(
+ ([diagnostic]) => diagnostic.code === "epub/noscript-content-skipped",
);
- expect(sink).toHaveBeenCalledWith(
- expect.objectContaining({ code: "epub/noscript-content-skipped" }),
+ expect(noscriptCalls).toHaveLength(1);
+ const unrecognizedCalls = sink.mock.calls.filter(
+ ([diagnostic]) => diagnostic.code === "epub/table-content-unrecognized",
);
+ expect(unrecognizedCalls).toHaveLength(1);
});
it("reads a second <caption> as its own paragraph too, with an additional duplicate-caption diagnostic, instead of silently discarding it", () => {
@@ -1711,10 +1897,17 @@ describe("tables", () => {
([diagnostic]) => diagnostic.code === "epub/table-duplicate-caption",
);
expect(duplicateCalls).toHaveLength(1);
+ expect(duplicateCalls[0]?.[0]?.message).toBe(
+ "<table> carries more than one <caption> (HTML5 permits at most one); every caption beyond the first is still read as its own ordinary paragraph immediately before the table, rather than being silently discarded",
+ );
const captionUnsupportedCalls = sink.mock.calls.filter(
([diagnostic]) => diagnostic.code === "epub/table-caption-unsupported",
);
expect(captionUnsupportedCalls).toHaveLength(2);
+ // The very first sink call, for the first <caption>, must never be the duplicate-caption diagnostic -- only a second or later caption is a duplicate.
+ expect(sink.mock.calls[0]?.[0]?.code).toBe(
+ "epub/table-caption-unsupported",
+ );
});
});
@@ -1741,6 +1934,22 @@ describe("blockquote", () => {
expect(paragraph).toMatchObject({ indentLeftPt: 72 });
});
+ it("adds a <dd>'s own extra indent to (not in place of) the blockquote's own quote indent", () => {
+ // Distinguishes the two contributions being summed (the correct behaviour) from being subtracted or otherwise combined -- a quote depth of 1 (36pt) plus one dd's own DEFINITION_BODY_INDENT_PT (36pt) must read back as 72pt, not 0pt.
+ const blocks = read(
+ body("<blockquote><dl><dd>text</dd></dl></blockquote>"),
+ );
+ const paragraph = blocks.find((b) => b.kind === "paragraph");
+ expect(paragraph).toMatchObject({ indentLeftPt: 72 });
+ });
+
+ it("degrades to indent-only structure when a heading is nested arbitrarily deep, not only a direct child", () => {
+ const blocks = read(
+ body("<blockquote><div><h2>Heading</h2></div></blockquote>"),
+ );
+ expect(blocks.some((b) => b.kind === "constructStart")).toBe(false);
+ });
+
it("degrades to indent-only structure (no division pair) when a heading is inside", () => {
const blocks = read(body("<blockquote><h2>Heading</h2></blockquote>"));
expect(blocks).toEqual([
@@ -1774,6 +1983,58 @@ describe("pre / code blocks", () => {
]);
});
+ it("carries no codeLanguage key at all when the <code> has no language- class", () => {
+ const blocks = read(body("<pre><code>plain</code></pre>"));
+ expect(Object.hasOwn(blocks[0] as object, "codeLanguage")).toBe(false);
+ });
+
+ it("requires language- to sit at the very start of the class, or right after whitespace, not merely somewhere in it", () => {
+ // "xlanguage-js" has no whitespace (nor the class's own start) immediately before "language-", so this must NOT be read as a language- token the way "language-js" or "foo language-js" would be.
+ const blocks = read(
+ body('<pre><code class="xlanguage-js">code</code></pre>'),
+ );
+ expect(Object.hasOwn(blocks[0] as object, "codeLanguage")).toBe(false);
+ });
+
+ it("produces no runs at all for a genuinely empty <pre>", () => {
+ const blocks = read(body("<pre></pre>"));
+ expect(blocks).toEqual([
+ { kind: "paragraph", runs: [], preformatted: true },
+ ]);
+ });
+
+ it("does not treat an ordinary, non-footnote <a> as a footnote reference, keeping the pre on its flat single-run path", () => {
+ const blocks = read(
+ body('<pre>before<a href="https://example.com">link</a>after</pre>'),
+ );
+ expect(blocks).toEqual([
+ {
+ kind: "paragraph",
+ runs: [{ text: "beforelinkafter", fontFamily: "Courier New" }],
+ preformatted: true,
+ },
+ ]);
+ });
+
+ it("names the <img>'s own src in its degrade diagnostic when one is present", () => {
+ let diagnostic: EpubDiagnostic | undefined;
+ read(body('<pre><img src="pic.png" alt="text"/></pre>'), (d) => {
+ diagnostic = d;
+ });
+ expect(diagnostic?.message).toContain('<img src="pic.png">');
+ });
+
+ it("states the exact generic <img> label and full degrade message when the <img> has no src at all", () => {
+ const sink = vi.fn();
+ read(body('<pre><img alt="text"/></pre>'), sink);
+ expect(sink).toHaveBeenCalledWith(
+ expect.objectContaining({
+ message:
+ "<img> inside a <pre>/<code> block cannot become a real image block (this package reads a <pre> as a single text-content paragraph, so there is no block list to insert an image block into); degraded to its alt text",
+ }),
+ );
+ });
+
it("splices an <img>'s alt text into the extracted text with a diagnostic, instead of vanishing", () => {
const sink = vi.fn();
const blocks = read(
@@ -1895,6 +2156,36 @@ describe("pre / code blocks", () => {
});
});
+ it("never treats a non-<a> wrapper's own href as a footnote reference, even when that same fragment is a real footnote elsewhere", () => {
+ // The wrapping <span> here is not itself a footnote-reference <a>, but happens to carry an href pointing at the same #fn2 fragment a real <a epub:type="noteref"> elsewhere in the document already registers as a footnote target. Only the genuinely nested <a href="#fn1"> should produce a construct; the span's own href must never be mistaken for a second one.
+ const blocks = read(
+ body(
+ '<p>See<a epub:type="noteref" href="#fn1">1</a>. Also<a epub:type="noteref" href="#fn2">2</a>.</p>' +
+ '<pre><span href="#fn2"><a epub:type="noteref" href="#fn1">ref</a></span></pre>' +
+ '<aside epub:type="footnote" id="fn1"><p>Note one.</p></aside>' +
+ '<aside epub:type="footnote" id="fn2"><p>Note two.</p></aside>',
+ ),
+ );
+ const pre = blocks.find(
+ (b) => b.kind === "paragraph" && b.preformatted === true,
+ );
+ if (pre === undefined) {
+ throw new Error("expected a preformatted paragraph block");
+ }
+ expect(pre).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "ref", fontFamily: "Courier New" }],
+ preformatted: true,
+ constructs: [
+ {
+ descriptor: { kind: "anchor", anchorType: "footnote", name: "fn1" },
+ startRun: 0,
+ endRun: 1,
+ },
+ ],
+ });
+ });
+
it("maps a <br> inside a <pre> to a literal newline rather than dropping the line break", () => {
const blocks = read(body("<pre>line1<br/>line2</pre>"));
expect(blocks).toEqual([
@@ -1965,6 +2256,85 @@ describe("pre / code blocks", () => {
],
});
});
+
+ it("splices an <img>'s alt text into the run-splitting readPreRuns path too, when the same <pre> also carries a real footnote reference", () => {
+ const sink = vi.fn();
+ const blocks = read(
+ body(
+ '<pre><img src="a.png" alt="pic"/><a epub:type="noteref" href="#fn1">1</a></pre>' +
+ '<aside epub:type="footnote" id="fn1"><p>Note.</p></aside>',
+ ),
+ sink,
+ );
+ const preParagraph = blocks.find(
+ (b) => b.kind === "paragraph" && b.preformatted === true,
+ );
+ expect(preParagraph).toEqual({
+ kind: "paragraph",
+ runs: [
+ { text: "pic", fontFamily: "Courier New" },
+ { text: "1", fontFamily: "Courier New" },
+ ],
+ preformatted: true,
+ constructs: [
+ {
+ descriptor: { kind: "anchor", anchorType: "footnote", name: "fn1" },
+ startRun: 1,
+ endRun: 2,
+ },
+ ],
+ });
+ expect(sink).toHaveBeenCalledWith(
+ expect.objectContaining({ code: "epub/image-pre-unsupported" }),
+ );
+ });
+
+ it("only wraps the actual <a> footnote reference in a construct, not a same-href-resolving <span> sitting alongside it in the run-splitting readPreRuns path", () => {
+ const blocks = read(
+ body(
+ '<pre>before<span href="#fn1">mid</span><a epub:type="noteref" href="#fn1">1</a>after</pre>' +
+ '<aside epub:type="footnote" id="fn1"><p>Note.</p></aside>',
+ ),
+ );
+ const preParagraph = blocks.find(
+ (b) => b.kind === "paragraph" && b.preformatted === true,
+ );
+ expect(preParagraph).toEqual({
+ kind: "paragraph",
+ runs: [
+ { text: "beforemid", fontFamily: "Courier New" },
+ { text: "1", fontFamily: "Courier New" },
+ { text: "after", fontFamily: "Courier New" },
+ ],
+ preformatted: true,
+ constructs: [
+ {
+ descriptor: { kind: "anchor", anchorType: "footnote", name: "fn1" },
+ startRun: 1,
+ endRun: 2,
+ },
+ ],
+ });
+ });
+
+ it("does not mistake a non-<a> element's own href for a footnote reference, even when that href happens to resolve to a real footnote target elsewhere in the document", () => {
+ // Only a genuine <a> can carry a footnote reference (preFootnoteReferenceName/containsFootnoteReference both gate on node.tag === "a" before ever checking where the href resolves) -- a <span href> pointing at the identical fragment must still take the flat, single-run readPreFlatRuns path, not the run-splitting readPreRuns path a real footnote reference would trigger.
+ const blocks = read(
+ body(
+ '<p><a epub:type="noteref" href="#fn1">1</a></p>' +
+ '<aside epub:type="footnote" id="fn1"><p>Note.</p></aside>' +
+ '<pre>before<span href="#fn1">mid</span>after</pre>',
+ ),
+ );
+ const preParagraph = blocks.find(
+ (b) => b.kind === "paragraph" && b.preformatted === true,
+ );
+ expect(preParagraph).toEqual({
+ kind: "paragraph",
+ runs: [{ text: "beforemidafter", fontFamily: "Courier New" }],
+ preformatted: true,
+ });
+ });
});
describe("hr", () => {
@@ -2016,6 +2386,21 @@ describe("images", () => {
}
});
+ it("carries no altText key at all for a resolved image with an empty alt attribute", () => {
+ const bytes = fakePng(96, 192);
+ const { blocks } = readXhtmlBody(body('<p><img src="a.png" alt=""/></p>'), {
+ resolveImage: (href) => (href === "a.png" ? bytes : undefined),
+ sink: () => undefined,
+ sourceHref: "chapter1.xhtml",
+ contentWidthPt: CONTENT_WIDTH_PT,
+ });
+ const [block] = blocks;
+ if (block === undefined) {
+ throw new Error("expected an image block");
+ }
+ expect(Object.hasOwn(block, "altText")).toBe(false);
+ });
+
it("degrades to alt text with a diagnostic when the manifest has no such part", () => {
const sink = vi.fn();
const blocks = read(
@@ -2026,10 +2411,19 @@ describe("images", () => {
{ kind: "paragraph", runs: [{ text: "fallback text" }] },
]);
expect(sink).toHaveBeenCalledWith(
- expect.objectContaining({ code: "epub/image-unresolved" }),
+ expect.objectContaining({
+ code: "epub/image-unresolved",
+ message:
+ '<img src="missing.png"> names no resolvable manifest part; degraded to its alt text',
+ }),
);
});
+ it("drops an unresolved image with an empty alt attribute entirely, rather than an empty paragraph", () => {
+ const blocks = read(body('<img src="missing.png" alt=""/>'));
+ expect(blocks).toEqual([]);
+ });
+
it("degrades to alt text with a diagnostic for a resolved but unsupported format", () => {
const sink = vi.fn();
const { blocks } = readXhtmlBody(body('<img src="a.gif" alt="a gif"/>'), {
@@ -2040,10 +2434,24 @@ describe("images", () => {
});
expect(blocks).toEqual([{ kind: "paragraph", runs: [{ text: "a gif" }] }]);
expect(sink).toHaveBeenCalledWith(
- expect.objectContaining({ code: "epub/image-format-unsupported" }),
+ expect.objectContaining({
+ code: "epub/image-format-unsupported",
+ message:
+ '<img src="a.gif"> is neither a PNG nor a JPEG (document-schema.js\'s ContentImageBlock supports only those two); degraded to its alt text',
+ }),
);
});
+ it("drops a resolved but unsupported-format image with an empty alt attribute entirely, rather than an empty paragraph", () => {
+ const { blocks } = readXhtmlBody(body('<img src="a.gif" alt=""/>'), {
+ resolveImage: () => new Uint8Array([0x47, 0x49, 0x46, 0x38]),
+ sink: () => undefined,
+ sourceHref: "chapter1.xhtml",
+ contentWidthPt: CONTENT_WIDTH_PT,
+ });
+ expect(blocks).toEqual([]);
+ });
+
it("degrades an <img> nested inside a <span> to its alt text with a diagnostic, instead of vanishing", () => {
const sink = vi.fn();
const blocks = read(
@@ -2235,6 +2643,12 @@ describe("text direction (the dir attribute)", () => {
const blocks = read(body('<p dir="auto">words</p>'));
expect(blocks[0]).toEqual({ kind: "paragraph", runs: [{ text: "words" }] });
});
+
+ it("never sets a direction key at all when nothing in scope ever stated a dir", () => {
+ // toEqual alone would pass even if decorateParagraph always attached a `direction: undefined` property (toEqual ignores undefined-valued keys), so this checks key presence directly.
+ const blocks = read(body("<p>plain</p>"));
+ expect(Object.hasOwn(blocks[0] as object, "direction")).toBe(false);
+ });
});
describe("readContainerChildren's own segment flush", () => {
@@ -2341,6 +2755,33 @@ describe("footnotes: EPUB 3 aside + noteref", () => {
],
});
});
+
+ it("reads a plain, non-footnote <aside> as ordinary content, with no construct wrapper and no diagnostic", () => {
+ const sink = vi.fn();
+ const blocks = read(body("<aside><p>Just a sidebar.</p></aside>"), sink);
+ expect(blocks).toEqual([
+ { kind: "paragraph", runs: [{ text: "Just a sidebar." }] },
+ ]);
+ expect(sink).not.toHaveBeenCalled();
+ });
+
+ it("reads a footnote <aside> with no id as ordinary content, with a diagnostic naming the loss", () => {
+ const sink = vi.fn();
+ const blocks = read(
+ body('<aside epub:type="footnote"><p>Orphan note.</p></aside>'),
+ sink,
+ );
+ expect(blocks).toEqual([
+ { kind: "paragraph", runs: [{ text: "Orphan note." }] },
+ ]);
+ expect(sink).toHaveBeenCalledWith(
+ expect.objectContaining({
+ code: "epub/footnote-target-unresolved",
+ message:
+ "a footnote <aside> carries no id and cannot be referenced; read as ordinary content",
+ }),
+ );
+ });
});
describe("footnotes: EPUB 2 linked-anchor idiom", () => {
diff --git a/packages/epub-codec/src/xhtml/read.ts b/packages/epub-codec/src/xhtml/read.ts
index c91efd77b..b56d6c6cd 100644
--- a/packages/epub-codec/src/xhtml/read.ts
+++ b/packages/epub-codec/src/xhtml/read.ts
@@ -9,7 +9,6 @@ import type {
SourceResidue,
TextDirection,
} from "document-schema.js";
-import { clampHeadingLevel } from "document-schema.js";
import { EpubDiagnosticCodes } from "../diagnostics";
import {
detectImageFormat,
@@ -370,9 +369,7 @@ function readContainerChildren(
const blocks: ContentBlock[] = [];
let segment: XmlNode[] = [];
const flush = (): void => {
- if (segment.length === 0) {
- return;
- }
+ // No separate empty-segment early return is needed here: buildInlineRuns([], ...) is a genuine no-op (its own for loop never executes, so it returns {runs: [], constructs: []} with no side effect), and the whitespace-and-construct check immediately below already drops that empty result exactly like it drops a genuinely whitespace-only segment -- an explicit `if (segment.length === 0) return;` guard ahead of it would only ever short-circuit to a state this check reaches anyway.
const inline = buildInlineRuns(segment, baseStyle, state.context);
segment = [];
// A segment whose only content, once built, is whitespace produces no visible paragraph -- the common real-world case being pretty-printed XHTML's own indentation landing as a bare text node between two block-level siblings (e.g. the newline-plus-indent between <body> and its first real child), which every browser's own block-formatting context already collapses to nothing rather than an empty line. The identical rule also covers a producer's own literal `<p> </p>`/`<p></p>` (used for CSS spacing): both read as "no content here" rather than a bogus empty ContentParagraph, matching this package's own documented choice to drop an empty paragraph entirely on read. The construct check alongside it exists for the identical reason readTable's own caption guard needs one: a segment carrying only a footnote-reference anchor with empty text (`<a epub:type="noteref" href="#fn1"></a>` sitting bare between two block siblings) produces zero text runs but one real RunConstructExtent, and text-emptiness alone would drop that construct along with the whitespace it is vacuously indistinguishable from.
@@ -395,19 +392,25 @@ function readContainerChildren(
blocks.push(...readBlockElement(node, state));
continue;
}
- if (node.type === "element" || isTextLikeNode(node)) {
- segment.push(node);
- }
+ // No element/text-like filter is needed here: buildInlineRuns (called from flush() above) already skips any node that is neither text-like nor an element (a comment, declaration, or processing instruction), so collecting every remaining node into segment unconditionally costs nothing a guard here could meaningfully save.
+ segment.push(node);
}
flush();
return blocks;
}
+// A literal tag->level lookup rather than a /^h([1-6])$/ regex: BLOCK_LEVEL_TAGS is the only source of tags this ever sees (readBlockElementInner calls it once per block-level element), and every member of that fixed set other than h1-h6 itself (p, ul, ol, dl, table, blockquote, pre, hr, figure, figcaption, div, section, article, aside, nav, img) already fails to match a heading tag by construction -- there is no producer-supplied tag this function is ever actually asked to classify that a regex's own anchoring subtleties could get wrong. clampHeadingLevel is unneeded here for the identical reason: every value in this table is already a valid heading depth (document-schema.js's own clamp exists for a source format that can carry a level outside 1-6, which a fixed tag literal can never do).
+const HEADING_TAG_LEVELS: Readonly<Record<string, number>> = {
+ h1: 1,
+ h2: 2,
+ h3: 3,
+ h4: 4,
+ h5: 5,
+ h6: 6,
+};
+
function headingLevelOf(tag: string): number | undefined {
- const match = /^h([1-6])$/u.exec(tag);
- return match?.[1] === undefined
- ? undefined
- : clampHeadingLevel(Number(match[1]));
+ return HEADING_TAG_LEVELS[tag];
}
// Wraps readBlockElementInner's own result in an anchor construct pair (footnote or bookmark) when this element's own id is a recognised anchor target -- src/xhtml/read.ts's own whole-document (and, via ReadXhtmlBodyOptions.extraAnchorTargets, whole-spine, ExaDev/documents.js#963) anchor-target registry, run over every <a> once by readXhtmlBody -- the target-side half of the EPUB 2 linked-anchor idiom and of an ordinary internal link, symmetric with an EPUB 3 <aside epub:type="footnote"> (readAside below), which instead recognises itself directly rather than needing this reverse lookup. An element already handled as such an aside is excluded here to avoid double-wrapping.
@@ -456,9 +459,6 @@ function readBlockElementInner(
}
switch (element.tag) {
- case "p":
- // A <p> containing a direct <img> (some producers/editors wrap every floating image in a paragraph tag rather than a <figure>) cannot become one ContentParagraph -- an image is its own top-level ContentBlock kind, not a run a paragraph can carry inline. readContainerChildren's own phrasing/block split handles this identically to any other container: the text before and after the image becomes its own paragraph (dropped entirely when empty, so a bare `<p><img/></p>` degrades to just the image block), and the image becomes its own block in between, in source order.
- return readContainerChildren(element.children, state);
case "hr": {
const paragraph: ContentParagraph = {
kind: "paragraph",
@@ -478,11 +478,6 @@ function readBlockElementInner(
return readDefinitionList(element, state);
case "table":
return readTable(element, state);
- case "figure":
- return readContainerChildren(element.children, state);
- case "figcaption":
- // <figcaption> is Flow content per the HTML Standard: a <pre>, a nested list, or more than one paragraph is real, conformant markup, not something this reader can flatten to one buildInlineRuns call without losing block shape and fusing sibling paragraphs together with no break between them (ExaDev/documents.js#1023).
- return readContainerChildren(element.children, state);
case "img": {
const block = readImage(element, state);
return block === undefined ? [] : [block];
@@ -490,7 +485,7 @@ function readBlockElementInner(
case "aside":
return readAside(element, state);
default:
- // Every other block-level container (div, section, article, nav that isn't the toc/landmarks/page-list nav src/nav.ts already reads separately, body itself never reaches here) carries no content of its own in document-schema.js's vocabulary -- it is read transparently, descending into its own children at the same nesting level. This is a deliberate, documented simplification: a div's own CSS class/id is residue this package does not interpret (the schema is content, not styling).
+ // Every other block-level container reaches this same transparent passthrough: div, section, article, nav that isn't the toc/landmarks/page-list nav src/nav.ts already reads separately, and body itself never reaches here carry no content of their own in document-schema.js's vocabulary, so each is read transparently, descending into its own children at the same nesting level -- a div's own CSS class/id is residue this package does not interpret (the schema is content, not styling). <p>, <figure>, and <figcaption> deliberately fall to this identical passthrough rather than each getting its own case that would just repeat it: a <p> containing a direct <img> (some producers/editors wrap every floating image in a paragraph tag rather than a <figure>) cannot become one ContentParagraph -- an image is its own top-level ContentBlock kind, not a run a paragraph can carry inline -- and readContainerChildren's own phrasing/block split already handles this identically to any other container (the text before and after the image becomes its own paragraph, dropped entirely when empty, so a bare `<p><img/></p>` degrades to just the image block, with the image becoming its own block in between, in source order); <figure>'s own content is exactly this same image-plus-caption mix; and <figcaption> is Flow content per the HTML Standard, where a <pre>, a nested list, or more than one paragraph is real, conformant markup this generic descent already preserves rather than flattening to one buildInlineRuns call and fusing sibling paragraphs together with no break between them (ExaDev/documents.js#1023).
return readContainerChildren(element.children, state);
}
}
@@ -599,10 +594,8 @@ function readPreRuns(
}
const footnoteName =
node.tag === "a" ? preFootnoteReferenceName(node, context) : undefined;
- if (
- footnoteName === undefined &&
- !containsFootnoteReference([node], context)
- ) {
+ // No separate `footnoteName === undefined &&` guard is needed ahead of this: whenever footnoteName IS defined, node is by construction a footnote-reference <a> (the ternary above requires node.tag === "a" and a resolved name), which is exactly containsFootnoteReference's own first check on this same single-element array -- so footnoteName defined always implies containsFootnoteReference([node]) is true, meaning "footnoteName undefined" is already entailed by "containsFootnoteReference([node]) is false" and adds no information of its own.
+ if (!containsFootnoteReference([node], context)) {
buffer += readPreText(node.children, context);
continue;
}
@@ -734,14 +727,8 @@ function readList(element: XmlElement, state: BuildState): ContentBlock[] {
);
continue;
}
- // The HTML Standard's own content model for <ul>/<ol> is "Zero or more li and script-supporting elements", explicitly naming <script>/<template> as legal direct children alongside <li> -- so those two are ignored entirely here: no stray collection, no LIST_CONTENT_OUTSIDE_ITEM diagnostic, and never routed through readContainerChildren (which has no case for either tag, and readList's own document-content mapping has no use for embedded script/template content regardless). This uses the shared isInertElement predicate (context.ts) rather than a narrower spec-accurate script/template-only check, deliberately extending the identical exemption to <style>/<noscript> too -- neither is actually legal here per the content model above, but both are just as unrepresentable and just as safe to skip silently as the two that are, and a single shared definition is worth more than a spec-perfect distinction no diagnostic here would ever need to draw. reportInertElementSkip still fires its own dedicated diagnostic for <noscript> specifically (the one member of the set whose subtree can be genuine document content) -- this filter only suppresses the unrelated stray-content diagnostic that would otherwise misrepresent a spec-legal position as malformed.
- if (child.type === "element" && isInertElement(child.tag)) {
- reportInertElementSkip(child.tag, state.context);
- continue;
- }
- if (child.type === "element" || isTextLikeNode(child)) {
- strayNodes.push(child);
- }
+ // The HTML Standard's own content model for <ul>/<ol> is "Zero or more li and script-supporting elements", explicitly naming <script>/<template> as legal direct children alongside <li> -- but no separate isInertElement pre-filter is needed here to keep them out of recovered content: buildInlineRuns' own appendElement (called via flushListStrayContent's readContainerChildren below) already carries the identical isInertElement check and skips <script>/<template>/<style>/<noscript> at that point instead, contributing zero runs and zero blocks regardless of which layer catches it. reportInertElementSkip's own dedicated diagnostic for <noscript> specifically (the one member of the set whose subtree can be genuine document content) still fires from that deeper call, at exactly the same single occurrence a pre-filter here would have produced, since a stray collection whose only content resolves to zero blocks never reaches flushListStrayContent's own LIST_CONTENT_OUTSIDE_ITEM diagnostic either way.
+ strayNodes.push(child);
}
blocks.push(
...flushListStrayContent(strayNodes, previousItem, element.tag, state),
@@ -749,16 +736,13 @@ function readList(element: XmlElement, state: BuildState): ContentBlock[] {
return blocks;
}
-// A <ul>/<ol> content model admits only <li> and script-supporting (<script>/<template>) children -- so any *other* content sitting directly inside one is not valid HTML5, most commonly a <ul>/<ol> nested as a sibling rather than wrapped in its own <li> (a shape real-world producers and converters emit even though it is not conformant), but any other stray content (a bare <img>, a run of text) shares the identical malformed shape and the identical most-likely producer intent. Content sitting between or after real <li> siblings is recovered by feeding it through the exact same readContainerChildren dispatch that <li>'s own real children already go through, under that preceding item's own list membership -- so a stray <ul>/<ol> becomes a properly nested list one level deeper sharing the enclosing numId (readBlockElementInner's own "ul"/"ol" case calls back into this function with that membership already on the state, incrementing level exactly as genuine nesting would), a stray <img> becomes its own real image block, and stray text becomes its own paragraph, rather than each needing its own hand-rolled special case. Content sitting BEFORE the very first <li> has no preceding item to attach to, but that is not a reason to drop it: it is recovered through the identical readContainerChildren dispatch, inheriting whatever list membership its own enclosing context already carries (none, unless the <ul>/<ol> it sits directly inside is itself nested inside another list's <li>), and lands in the returned block sequence immediately before the list's own real items -- matching a browser's rendering ORDER for this malformed shape, but not necessarily its nesting DEPTH: when the enclosing <ul>/<ol> is itself nested inside an outer list's own <li>, a browser indents this recovered content at the enclosing (inner) list's own depth, one level deeper than the outer item's own text (inside that inner list's own content box), while this recovery always emits it at that outer item's own depth instead -- a top-level sibling of the enclosing list only in the un-nested case, where the enclosing <ul>/<ol> itself carries no list membership at all. Silently dropping this case (this function's own prior behaviour) lost real content with no diagnostic at all: ExaDev/documents.js#994's own headline repro, `<ul><ul><li>b</li></ul><li>a</li></ul>`, discarded the entire nested list. A stray <script>/<template>/<style>/<noscript> sitting as a DIRECT child of the <ul>/<ol> itself never reaches this function at all -- readList's own loop above filters it out (isInertElement) before it is ever collected as a stray node in the first place. One nested a level or more deeper, though -- e.g. a <script> inside a stray <div> -- still reaches this function's own readContainerChildren call above, which resolves it to zero blocks via src/xhtml/inline.ts's own appendElement guard, the identical narrower claim flushDefinitionListStrayContent's own comment below already states for the <dl> case. Inter-element whitespace, by contrast, DOES reach here: the HTML Standard's own "must be ignored when establishing whether an element's contents match the content model" rule (section 3.2.5 "Content models") governs conformance-checking alone, not deletion of the character data itself, so real whitespace sitting between two stray inline siblings (the single space that keeps two words apart) is still live text that must survive a round trip. What decides whether the diagnostic-and-recovery step below fires is the actual readContainerChildren result, not a speculative text-only probe: a bare block-level construct with no text projection at all (a stray <img>, an <hr>, a table or figure whose only content is an image) still produces a real, non-empty block list and must still be recovered and reported, exactly like the common pretty-printed-list shape of a bare newline-plus-indent text node, which readContainerChildren's own segment-flush already reduces to an empty block list on its own (see its whitespace-only-segment comment) -- so nodes.length === 0 is the only cheap short-circuit worth taking before paying for the real read, whether or not a preceding item exists to attach the result to. The read always runs exactly once, and this function's OWN diagnostic (LIST_CONTENT_OUTSIDE_ITEM) fires only when the recovered block list is non-empty -- but an empty block list does not mean the read underneath it was a no-op: a nested list nested directly in the stray content (e.g. an empty `<ul>` with no `<li>` of its own) still mints a real numId via readList's own eager `mintNumId` call before discovering it has nothing to attach to, and any diagnostic fired by content reached deeper in the recovered subtree (most commonly `epub/image-unresolved`, when a stray `<img>` fails to resolve) still reaches the sink regardless of whether the surrounding recovery is ultimately reported or discarded. Both are harmless in practice -- a numId is an opaque per-list key with no significance beyond uniqueness (src/xhtml/list-id.ts), so a skipped integer costs nothing, and the deeper diagnostic already names its own loss on its own terms -- but they mean the minter and the sink are not, in fact, insulated from a discarded read's side effects the way LIST_CONTENT_OUTSIDE_ITEM's own absence might suggest.
+// A <ul>/<ol> content model admits only <li> and script-supporting (<script>/<template>) children -- so any *other* content sitting directly inside one is not valid HTML5, most commonly a <ul>/<ol> nested as a sibling rather than wrapped in its own <li> (a shape real-world producers and converters emit even though it is not conformant), but any other stray content (a bare <img>, a run of text) shares the identical malformed shape and the identical most-likely producer intent. Content sitting between or after real <li> siblings is recovered by feeding it through the exact same readContainerChildren dispatch that <li>'s own real children already go through, under that preceding item's own list membership -- so a stray <ul>/<ol> becomes a properly nested list one level deeper sharing the enclosing numId (readBlockElementInner's own "ul"/"ol" case calls back into this function with that membership already on the state, incrementing level exactly as genuine nesting would), a stray <img> becomes its own real image block, and stray text becomes its own paragraph, rather than each needing its own hand-rolled special case. Content sitting BEFORE the very first <li> has no preceding item to attach to, but that is not a reason to drop it: it is recovered through the identical readContainerChildren dispatch, inheriting whatever list membership its own enclosing context already carries (none, unless the <ul>/<ol> it sits directly inside is itself nested inside another list's <li>), and lands in the returned block sequence immediately before the list's own real items -- matching a browser's rendering ORDER for this malformed shape, but not necessarily its nesting DEPTH: when the enclosing <ul>/<ol> is itself nested inside an outer list's own <li>, a browser indents this recovered content at the enclosing (inner) list's own depth, one level deeper than the outer item's own text (inside that inner list's own content box), while this recovery always emits it at that outer item's own depth instead -- a top-level sibling of the enclosing list only in the un-nested case, where the enclosing <ul>/<ol> itself carries no list membership at all. Silently dropping this case (this function's own prior behaviour) lost real content with no diagnostic at all: ExaDev/documents.js#994's own headline repro, `<ul><ul><li>b</li></ul><li>a</li></ul>`, discarded the entire nested list. A stray <script>/<template>/<style>/<noscript> sitting as a DIRECT child of the <ul>/<ol> itself is collected into strayNodes exactly like any other stray node -- readList's own loop above has no separate isInertElement pre-filter for it -- but it still contributes zero blocks once it reaches this function's own readContainerChildren call, which resolves it to nothing via src/xhtml/inline.ts's own appendElement guard, the identical mechanism a nested one (e.g. a <script> inside a stray <div>) already goes through, and the identical narrower claim flushDefinitionListStrayContent's own comment below already states for the <dl> case. Inter-element whitespace, by contrast, DOES reach here: the HTML Standard's own "must be ignored when establishing whether an element's contents match the content model" rule (section 3.2.5 "Content models") governs conformance-checking alone, not deletion of the character data itself, so real whitespace sitting between two stray inline siblings (the single space that keeps two words apart) is still live text that must survive a round trip. What decides whether the diagnostic-and-recovery step below fires is the actual readContainerChildren result, not a speculative text-only probe: a bare block-level construct with no text projection at all (a stray <img>, an <hr>, a table or figure whose only content is an image) still produces a real, non-empty block list and must still be recovered and reported, exactly like the common pretty-printed-list shape of a bare newline-plus-indent text node, which readContainerChildren's own segment-flush already reduces to an empty block list on its own (see its whitespace-only-segment comment) -- so there is no separate `nodes.length === 0` short-circuit worth taking here either: readContainerChildren([], ...) is itself already a genuine no-op for the identical reason (an empty for loop, then one flush() call over an empty segment), so calling it unconditionally costs nothing a guard could meaningfully save. The read always runs exactly once, and this function's OWN diagnostic (LIST_CONTENT_OUTSIDE_ITEM) fires only when the recovered block list is non-empty -- but an empty block list does not mean the read underneath it was a no-op: a nested list nested directly in the stray content (e.g. an empty `<ul>` with no `<li>` of its own) still mints a real numId via readList's own eager `mintNumId` call before discovering it has nothing to attach to, and any diagnostic fired by content reached deeper in the recovered subtree (most commonly `epub/image-unresolved`, when a stray `<img>` fails to resolve) still reaches the sink regardless of whether the surrounding recovery is ultimately reported or discarded. Both are harmless in practice -- a numId is an opaque per-list key with no significance beyond uniqueness (src/xhtml/list-id.ts), so a skipped integer costs nothing, and the deeper diagnostic already names its own loss on its own terms -- but they mean the minter and the sink are not, in fact, insulated from a discarded read's side effects the way LIST_CONTENT_OUTSIDE_ITEM's own absence might suggest.
function flushListStrayContent(
nodes: readonly XmlNode[],
previousItem: ListItemContext | undefined,
tag: string,
state: BuildState,
): ContentBlock[] {
- if (nodes.length === 0) {
- return [];
- }
const blocks = readContainerChildren(
nodes,
previousItem === undefined ? state : withListItem(state, previousItem),
@@ -828,26 +812,19 @@ function readDefinitionListEntries(
blocks.push(...readDefinitionListEntries(child.children, state));
continue;
}
- if (child.type === "element" && isInertElement(child.tag)) {
- reportInertElementSkip(child.tag, state.context);
- continue;
- }
- if (child.type === "element" || isTextLikeNode(child)) {
- strayNodes.push(child);
- }
+ // No isInertElement pre-filter is needed here either: flushDefinitionListStrayContent's own readContainerChildren call already carries the identical check (via buildInlineRuns' appendElement), skipping a <script>/<template>/<style>/<noscript> child at that deeper point instead, with reportInertElementSkip's own <noscript> diagnostic still firing from there at exactly the same single occurrence.
+ strayNodes.push(child);
}
flushStray();
return blocks;
}
-// The <dl> twin of flushListStrayContent above: content that is not dt/dd/div (nor an inert element) sitting directly inside a <dl> or one of its <div> wrappers is not valid HTML5, but silently dropping it loses real content with no diagnostic at all -- exactly the defect class ExaDev/documents.js#994 was filed about, reachable here one tag away from the shape that issue's own fix already covers. Recovered through the same readContainerChildren dispatch dt/dd's own real children go through, under the plain `state` (a <dl> entry carries no numId/level membership the way a list item does for stray content to inherit, so there is no withListItem-equivalent to apply here). Reported only when the recovery actually produces content, matching flushListStrayContent's own rule: genuine inter-element whitespace (the common pretty-printed-<dl> shape) and a stray <script>/<template>/<style>/<noscript> collected here (isInertElement's own check above already filters most of these before they are ever collected, but a nested one -- e.g. a <script> inside a stray <section> -- still reaches this function's own readContainerChildren call, which resolves it to zero blocks via src/xhtml/inline.ts's own appendElement guard) both produce an empty recovered block list and fire nothing.
+// The <dl> twin of flushListStrayContent above: content that is not dt/dd/div sitting directly inside a <dl> or one of its <div> wrappers is not valid HTML5, but silently dropping it loses real content with no diagnostic at all -- exactly the defect class ExaDev/documents.js#994 was filed about, reachable here one tag away from the shape that issue's own fix already covers. Recovered through the same readContainerChildren dispatch dt/dd's own real children go through, under the plain `state` (a <dl> entry carries no numId/level membership the way a list item does for stray content to inherit, so there is no withListItem-equivalent to apply here). Reported only when the recovery actually produces content, matching flushListStrayContent's own rule: genuine inter-element whitespace (the common pretty-printed-<dl> shape) and a stray <script>/<template>/<style>/<noscript> collected here -- whether sitting directly in the <dl> or nested a level or more deeper, e.g. inside a stray <section> -- both resolve to zero blocks via src/xhtml/inline.ts's own appendElement guard, so both produce an empty recovered block list and fire nothing.
function flushDefinitionListStrayContent(
nodes: readonly XmlNode[],
state: BuildState,
): ContentBlock[] {
- if (nodes.length === 0) {
- return [];
- }
+ // No separate `nodes.length === 0` short-circuit is needed ahead of this: readContainerChildren([], ...) is itself already a genuine no-op (an empty for loop, then one flush() call over an empty segment producing no blocks), so the block-count check immediately below already returns [] for a genuinely empty `nodes` on its own.
const blocks = readContainerChildren(nodes, state);
if (blocks.length === 0) {
return [];
@@ -875,26 +852,22 @@ function readTable(element: XmlElement, state: BuildState): ContentBlock[] {
continue; // every <caption>, first or duplicate, is handled in full by readTableCaption below regardless of where in source order it sits
}
if (section.type !== "element") {
- if (isTextLikeNode(section)) {
- strayNodes.push(section);
- }
+ // No isTextLikeNode filter is needed here: readContainerChildren's own strayBlocks call below already skips any node that is neither text-like nor an element (a comment, declaration, or processing instruction), so collecting every remaining non-element section into strayNodes unconditionally costs nothing a guard here could meaningfully save.
+ strayNodes.push(section);
continue;
}
if (section.tag === "colgroup") {
- collectColgroupStrayContent(section, strayNodes, state.context);
- continue;
- }
- if (isInertElement(section.tag)) {
- reportInertElementSkip(section.tag, state.context);
+ collectColgroupStrayContent(section, strayNodes);
continue;
}
+ // No isInertElement pre-filter is needed here: an inert <script>/<template>/<style>/<noscript> direct child falls through to the rowContainers===undefined branch below just like any other non-row-group section, and readContainerChildren's own buildInlineRuns call (invoked over strayNodes further down) already carries the identical check, contributing zero runs and firing reportInertElementSkip's own <noscript> diagnostic from that deeper point instead.
const rowContainers =
section.tag === "tr"
? [section]
: section.tag === "thead" ||
section.tag === "tbody" ||
section.tag === "tfoot"
- ? collectRowGroupRows(section, strayNodes, state.context)
+ ? collectRowGroupRows(section, strayNodes)
: undefined;
if (rowContainers === undefined) {
strayNodes.push(section);
@@ -904,9 +877,7 @@ function readTable(element: XmlElement, state: BuildState): ContentBlock[] {
const cells: ContentTableCell[] = [];
let strayCellNodes: XmlNode[] = [];
const flushStrayCell = (): void => {
- if (strayCellNodes.length === 0) {
- return;
- }
+ // No `strayCellNodes.length === 0` short-circuit is needed ahead of this: readContainerChildren([], ...) is itself already a genuine no-op, so the recovered-length check immediately below already returns for a genuinely empty strayCellNodes the same either way.
const recovered = readContainerChildren(strayCellNodes, state);
strayCellNodes = [];
if (recovered.length === 0) {
@@ -944,21 +915,16 @@ function readTable(element: XmlElement, state: BuildState): ContentBlock[] {
});
continue;
}
- if (cellNode.type === "element" && isInertElement(cellNode.tag)) {
- reportInertElementSkip(cellNode.tag, state.context);
- continue;
- }
- if (cellNode.type === "element" || isTextLikeNode(cellNode)) {
- strayCellNodes.push(cellNode);
- }
+ // No isInertElement pre-filter is needed here either: flushStrayCell's own readContainerChildren call already carries the identical check (via buildInlineRuns' appendElement), skipping a <script>/<template>/<style>/<noscript> cellNode at that deeper point instead, with reportInertElementSkip's own <noscript> diagnostic still firing from there at exactly the same single occurrence. No element/text-like filter is needed either, for the identical reason: that same readContainerChildren call already skips any node that is neither text-like nor an element, so collecting every remaining cellNode into strayCellNodes unconditionally costs nothing either guard here could meaningfully save.
+ strayCellNodes.push(cellNode);
}
flushStrayCell();
columnCount = Math.max(columnCount, cells.length);
rows.push({ cells });
}
}
- const strayBlocks =
- strayNodes.length === 0 ? [] : readContainerChildren(strayNodes, state);
+ // No `strayNodes.length === 0` short-circuit is needed ahead of this call: readContainerChildren([], ...) is itself already a genuine no-op, so the length check immediately below already treats a genuinely empty strayNodes the same either way.
+ const strayBlocks = readContainerChildren(strayNodes, state);
if (strayBlocks.length > 0) {
state.context.sink({
code: EpubDiagnosticCodes.TABLE_CONTENT_UNRECOGNIZED,
@@ -989,7 +955,6 @@ function readTable(element: XmlElement, state: BuildState): ContentBlock[] {
function collectRowGroupRows(
section: XmlElement,
strayNodes: XmlNode[],
- context: XhtmlReadContext,
): XmlElement[] {
const trs: XmlElement[] = [];
for (const child of section.children) {
@@ -997,13 +962,8 @@ function collectRowGroupRows(
trs.push(child);
continue;
}
- if (child.type === "element" && isInertElement(child.tag)) {
- reportInertElementSkip(child.tag, context);
- continue;
- }
- if (child.type === "element" || isTextLikeNode(child)) {
- strayNodes.push(child);
- }
+ // No isInertElement pre-filter is needed here: readTable's own strayBlocks call over this same accumulator already carries the identical check (via buildInlineRuns' appendElement), skipping a <script>/<template>/<style>/<noscript> child at that deeper point instead, with reportInertElementSkip's own <noscript> diagnostic still firing from there at exactly the same single occurrence.
+ strayNodes.push(child);
}
return trs;
}
@@ -1012,19 +972,13 @@ function collectRowGroupRows(
function collectColgroupStrayContent(
section: XmlElement,
strayNodes: XmlNode[],
- context: XhtmlReadContext,
): void {
for (const child of section.children) {
if (child.type === "element" && child.tag === "col") {
continue;
}
- if (child.type === "element" && isInertElement(child.tag)) {
- reportInertElementSkip(child.tag, context);
- continue;
- }
- if (child.type === "element" || isTextLikeNode(child)) {
- strayNodes.push(child);
- }
+ // No isInertElement pre-filter is needed here either: readTable's own strayBlocks call over this same accumulator already carries the identical check (via buildInlineRuns' appendElement), skipping a <script>/<template>/<style>/<noscript> child at that deeper point instead, with reportInertElementSkip's own <noscript> diagnostic still firing from there at exactly the same single occurrence.
+ strayNodes.push(child);
}
}
diff --git a/packages/epub-codec/src/xhtml/style-residue.test.ts b/packages/epub-codec/src/xhtml/style-residue.test.ts
index ebd0d0fdf..4f620b060 100644
--- a/packages/epub-codec/src/xhtml/style-residue.test.ts
+++ b/packages/epub-codec/src/xhtml/style-residue.test.ts
@@ -51,4 +51,34 @@ describe("readXhtmlBody: <head> style residue", () => {
});
expect(source).toBeUndefined();
});
+
+ it("does not quarantine a <link> whose rel is not stylesheet, nor an unrelated element that merely carries a rel=stylesheet attribute", () => {
+ // Distinguishes the two-part `node.tag === "link" && attrValue(node, "rel") === "stylesheet"` test from either half alone: a <link> with the wrong rel, and a non-<link> tag that happens to carry rel="stylesheet", must each fail the full conjunction on their own.
+ const { source } = readXhtmlBody(
+ bodyWithHead('<link rel="icon" href="a.ico"/><meta rel="stylesheet"/>'),
+ {
+ resolveImage: () => undefined,
+ sink: () => undefined,
+ sourceHref: "chapter1.xhtml",
+ contentWidthPt: CONTENT_WIDTH_PT,
+ },
+ );
+ expect(source).toBeUndefined();
+ });
+
+ it("states the exact style-residue diagnostic message", () => {
+ const sink = vi.fn();
+ readXhtmlBody(bodyWithHead("<style>p { color: red; }</style>"), {
+ resolveImage: () => undefined,
+ sink,
+ sourceHref: "chapter1.xhtml",
+ contentWidthPt: CONTENT_WIDTH_PT,
+ });
+ expect(sink).toHaveBeenCalledWith(
+ expect.objectContaining({
+ message:
+ "the document's own <head> style declarations (CSS) are quarantined as residue rather than interpreted; the schema is content, not styling",
+ }),
+ );
+ });
});
diff --git a/packages/epub-codec/src/xhtml/write.test.ts b/packages/epub-codec/src/xhtml/write.test.ts
index d275aba9a..30145fe38 100644
--- a/packages/epub-codec/src/xhtml/write.test.ts
+++ b/packages/epub-codec/src/xhtml/write.test.ts
@@ -17,6 +17,16 @@ function write(blocks: ContentBlock[]): string {
return writeWithSink(blocks, () => undefined).xml;
}
+// The raw XmlElement tree, for the handful of tests that need to inspect writer-internal node structure (e.g. whether a spurious empty text node exists between two sibling elements) directly -- a distinction the serialized XML string itself can lose, since an empty text node contributes zero characters to the output either way.
+function writeBody(blocks: ContentBlock[]) {
+ return writeXhtmlBody(blocks, {
+ registerImage: () => "images/img1.png",
+ sink: () => undefined,
+ sourceHref: "chapter1.xhtml",
+ resolveAnchorHref: (name) => `#${name}`,
+ });
+}
+
function writeWithSink(
blocks: ContentBlock[],
sink: (d: EpubDiagnostic) => void,
@@ -172,6 +182,36 @@ describe("writeXhtmlBody", () => {
expect(roundTrip(blocks)).toEqual(blocks);
});
+ it("never groups two adjacent list items that both carry no itemId into a single <li>", () => {
+ const xml = write([
+ {
+ kind: "paragraph",
+ runs: [{ text: "a" }],
+ list: { numId: "epub1:bullet", level: 0 },
+ },
+ {
+ kind: "paragraph",
+ runs: [{ text: "b" }],
+ list: { numId: "epub1:bullet", level: 0 },
+ },
+ ]);
+ const liCount = xml.split("<li>").length - 1;
+ expect(liCount).toBe(2);
+ });
+
+ it("writes and re-reads an ordered list with the default start, carrying no explicit start attribute", () => {
+ const blocks: ContentBlock[] = [
+ {
+ kind: "paragraph",
+ runs: [{ text: "a" }],
+ list: { numId: "epub1:ordered", level: 0, itemId: "item1" },
+ },
+ ];
+ const xml = write(blocks);
+ expect(xml).not.toContain("start=");
+ expect(roundTrip(blocks)).toEqual(blocks);
+ });
+
it("writes and re-reads an ordered list with a non-default start", () => {
const blocks: ContentBlock[] = [
{
@@ -235,6 +275,45 @@ describe("writeXhtmlBody", () => {
]);
});
+ it("writes and re-reads a table cell's own rowspan attribute", () => {
+ const blocks: ContentBlock[] = [
+ {
+ kind: "table",
+ rows: [
+ {
+ cells: [
+ {
+ blocks: [{ kind: "paragraph", runs: [{ text: "tall" }] }],
+ rowSpan: 3,
+ },
+ ],
+ },
+ ],
+ columnWidthsPt: [100],
+ },
+ ];
+ const xml = write(blocks);
+ expect(xml).toContain('rowspan="3"');
+ });
+
+ it("never reports ELEMENT_UNMAPPED for an ordinary table cell carrying only real leaf blocks", () => {
+ const blocks: ContentBlock[] = [
+ {
+ kind: "table",
+ rows: [
+ {
+ cells: [{ blocks: [{ kind: "paragraph", runs: [{ text: "x" }] }] }],
+ },
+ ],
+ columnWidthsPt: [100],
+ },
+ ];
+ const { diagnostics } = writeWithSink(blocks, () => undefined);
+ expect(
+ diagnostics.some((d) => d.code === EpubDiagnosticCodes.ELEMENT_UNMAPPED),
+ ).toBe(false);
+ });
+
// The comment above writeTable's own isTreeBlockLeaf filter used to claim this package's own reader never puts a construct-boundary marker inside a table cell's blocks -- it does, whenever read.ts's own flushStrayCell recovers a stray <blockquote> (or a footnote-target element) sitting directly inside a <tr>: readBlockquote wraps its recovered content in a division construct pair, and that recovered ContentBlock[] becomes the stray cell's own blocks. This exercises that exact path end to end.
it("drops a construct-boundary marker recovered into a stray table cell, with a diagnostic", () => {
const sink = () => undefined;
@@ -277,6 +356,164 @@ describe("writeXhtmlBody", () => {
expect(roundTrip(blocks)).toEqual(blocks);
});
+ it("never treats a paragraph carrying the horizontal-rule styleId but real runs as an <hr>", () => {
+ const xml = write([
+ {
+ kind: "paragraph",
+ runs: [{ text: "not empty" }],
+ styleId: "HorizontalRule",
+ },
+ ]);
+ expect(xml).not.toContain("<hr");
+ expect(xml).toContain("not empty");
+ });
+
+ it("writes a paragraph carrying only codeLanguage (no preformatted flag) as a <pre><code>", () => {
+ const xml = write([
+ {
+ kind: "paragraph",
+ runs: [{ text: "x = 1" }],
+ codeLanguage: "js",
+ },
+ ]);
+ expect(xml).toContain('<pre><code class="language-js">x = 1</code></pre>');
+ });
+
+ it("recognises a foreign producer's own <pre> via the legacy monospace-plus-newline heuristic alone, with neither preformatted nor codeLanguage set", () => {
+ const xml = write([
+ {
+ kind: "paragraph",
+ runs: [
+ { text: "line one\nline two", fontFamily: MONOSPACE_FONT_FAMILY },
+ ],
+ },
+ ]);
+ expect(xml).toContain("<pre>");
+ });
+
+ it("never treats a plain paragraph as preformatted just because it happens to have one monospace run without a newline", () => {
+ const xml = write([
+ {
+ kind: "paragraph",
+ runs: [{ text: "mono", fontFamily: "Courier New" }],
+ },
+ ]);
+ expect(xml).not.toContain("<pre>");
+ expect(xml).toContain("<p>");
+ });
+
+ it("never treats a plain paragraph as preformatted just because it has a newline in a non-monospace run", () => {
+ const xml = write([
+ { kind: "paragraph", runs: [{ text: "line one\nline two" }] },
+ ]);
+ expect(xml).not.toContain("<pre>");
+ });
+
+ it("never treats a plain paragraph as preformatted when the monospace-plus-newline run is not the only run", () => {
+ const xml = write([
+ {
+ kind: "paragraph",
+ runs: [
+ { text: "line one\nline two", fontFamily: "Courier New" },
+ { text: " and more" },
+ ],
+ },
+ ]);
+ expect(xml).not.toContain("<pre>");
+ });
+
+ it("drops a pageBreak block entirely, with no element and no diagnostic", () => {
+ const { xml, diagnostics } = writeWithSink(
+ [{ kind: "pageBreak" }],
+ () => undefined,
+ );
+ expect(xml).toBe(
+ '<?xml version="1.0" encoding="utf-8"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops"><body></body></html>',
+ );
+ expect(diagnostics).toHaveLength(0);
+ });
+
+ it("never inserts a spurious empty text node between two <br/> elements for a run's own consecutive embedded newlines", () => {
+ const body = writeBody([{ kind: "paragraph", runs: [{ text: "a\n\nb" }] }]);
+ const [p] = body.children;
+ if (p?.type !== "element") {
+ throw new Error("expected a <p> element");
+ }
+ expect(
+ p.children.map((c) =>
+ c.type === "element" ? c.tag : c.type === "text" ? c.value : c.type,
+ ),
+ ).toEqual(["a", "br", "br", "b"]);
+ });
+
+ it("writes a wholly empty, unformatted run as exactly one empty text node, never zero and never placeholder text", () => {
+ const body = writeBody([{ kind: "paragraph", runs: [{ text: "" }] }]);
+ const [p] = body.children;
+ if (p?.type !== "element") {
+ throw new Error("expected a <p> element");
+ }
+ expect(p.children).toHaveLength(1);
+ expect(p.children[0]).toEqual({ type: "text", value: "" });
+ });
+
+ it("never emits a text node for an empty-text run inside a <pre>, unlike a non-empty sibling run", () => {
+ const body = writeBody([
+ {
+ kind: "paragraph",
+ preformatted: true,
+ runs: [{ text: "" }, { text: "b" }],
+ },
+ ]);
+ const [pre] = body.children;
+ if (pre?.type !== "element") {
+ throw new Error("expected a <pre> element");
+ }
+ const [code] = pre.children;
+ if (code?.type !== "element") {
+ throw new Error("expected a <code> element");
+ }
+ expect(code.children).toEqual([{ type: "text", value: "b" }]);
+ });
+
+ it("joins a multi-run footnote range's own text verbatim inside a <pre>, with no separator between runs", () => {
+ const xml = write([
+ {
+ kind: "paragraph",
+ preformatted: true,
+ runs: [{ text: "a" }, { text: "b" }],
+ constructs: [
+ {
+ descriptor: { kind: "anchor", anchorType: "footnote", name: "fn1" },
+ startRun: 0,
+ endRun: 2,
+ },
+ ],
+ },
+ ]);
+ expect(xml).toContain('epub:type="noteref" href="#fn1">ab</a>');
+ });
+
+ it("drops an embeddedObject block with the exact ELEMENT_UNMAPPED message naming the loss", () => {
+ const { diagnostics } = writeWithSink(
+ [
+ {
+ kind: "embeddedObject",
+ objectKind: "wordprocessing",
+ frame: { xPt: 0, yPt: 0, widthPt: 100, heightPt: 50 },
+ document: { kind: "wordprocessing", metadata: {}, sections: [] },
+ },
+ ],
+ () => undefined,
+ );
+ expect(diagnostics).toContainEqual(
+ expect.objectContaining({
+ code: EpubDiagnosticCodes.ELEMENT_UNMAPPED,
+ message:
+ "an embedded object has no XHTML representation in this package's writer and was dropped",
+ }),
+ );
+ });
+
it("writes and re-reads a code block with a language", () => {
const blocks: ContentBlock[] = [
{
@@ -507,6 +744,51 @@ describe("writeXhtmlBody", () => {
expect(roundTrip(blocks)).toEqual(blocks);
});
+ it("never reports CONSTRUCT_UNREPRESENTED for a single, cleanly-written point-anchor footnote reference", () => {
+ const blocks: ContentBlock[] = [
+ {
+ kind: "paragraph",
+ runs: [],
+ constructs: [
+ {
+ descriptor: { kind: "anchor", anchorType: "footnote", name: "fn1" },
+ startRun: 0,
+ endRun: 0,
+ },
+ ],
+ },
+ ];
+ const { diagnostics } = writeWithSink(blocks, () => undefined);
+ expect(
+ diagnostics.some(
+ (d) => d.code === EpubDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+ ),
+ ).toBe(false);
+ });
+
+ it("never reports CONSTRUCT_UNREPRESENTED for a single, cleanly-written range footnote reference", () => {
+ const blocks: ContentBlock[] = [
+ {
+ kind: "paragraph",
+ runs: [{ text: "See" }, { text: "1" }],
+ constructs: [
+ {
+ descriptor: { kind: "anchor", anchorType: "footnote", name: "fn1" },
+ startRun: 1,
+ endRun: 2,
+ },
+ ],
+ },
+ ];
+ const { xml, diagnostics } = writeWithSink(blocks, () => undefined);
+ expect(
+ diagnostics.some(
+ (d) => d.code === EpubDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+ ),
+ ).toBe(false);
+ expect(xml).toContain('href="#fn1"');
+ });
+
// The identical writer gap also orphaned a table caption whose only content is a footnote reference: readTableCaption's own construct check (src/xhtml/read.ts) recovers `<caption><a epub:type="noteref" href="#fn1"></a></caption>` as this same runs: [], construct-only shape, read immediately before the table -- the writer's bug was in the shared run-range walk, not anything caption-specific, so this proves the fix holds for that read shape too rather than only the bare-segment one above.
it("writes and re-reads a bare footnote reference construct in a paragraph sitting immediately before a table, matching a caption's own read shape", () => {
const blocks: ContentBlock[] = [
@@ -620,11 +902,13 @@ describe("writeXhtmlBody", () => {
},
];
const { xml, diagnostics } = writeWithSink(blocks, () => undefined);
- expect(
- diagnostics.some(
- (d) => d.code === EpubDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
- ),
- ).toBe(true);
+ const unrepresented = diagnostics.find(
+ (d) => d.code === EpubDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+ );
+ expect(unrepresented?.message).toContain("footnote reference");
+ expect(unrepresented?.message).toContain(
+ "cannot be represented as its own <a> element",
+ );
// No run text is lost: the winning extent (fn1) wraps the first two runs, and the third run -- past fn1's own endRun -- is still written on its own.
expect(xml).toContain('href="#fn1"');
expect(xml).not.toContain('href="#fn2"');
@@ -633,6 +917,85 @@ describe("writeXhtmlBody", () => {
expect(xml).toContain(".");
});
+ it("names an unrepresented internal-link extent as an 'internal link', not a footnote reference, in its CONSTRUCT_UNREPRESENTED message", () => {
+ const blocks: ContentBlock[] = [
+ {
+ kind: "paragraph",
+ runs: [{ text: "See" }, { text: "this" }],
+ constructs: [
+ {
+ descriptor: {
+ kind: "link",
+ target: { kind: "internal", anchor: "bm1" },
+ },
+ startRun: 0,
+ endRun: 2,
+ },
+ {
+ descriptor: {
+ kind: "link",
+ target: { kind: "internal", anchor: "bm2" },
+ },
+ startRun: 0,
+ endRun: 1,
+ },
+ ],
+ },
+ ];
+ const { diagnostics } = writeWithSink(blocks, () => undefined);
+ const unrepresented = diagnostics.find(
+ (d) => d.code === EpubDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+ );
+ expect(unrepresented?.message).toContain("internal link");
+ expect(unrepresented?.message).not.toContain("footnote reference");
+ });
+
+ it("writes a clean internal-link construct extent as its own <a href> targeting the resolved anchor", () => {
+ const xml = write([
+ {
+ kind: "paragraph",
+ runs: [{ text: "See" }, { text: "this" }],
+ constructs: [
+ {
+ descriptor: {
+ kind: "link",
+ target: { kind: "internal", anchor: "bm1" },
+ },
+ startRun: 1,
+ endRun: 2,
+ },
+ ],
+ },
+ ]);
+ expect(xml).toContain('<a href="#bm1">this</a>');
+ });
+
+ it("never treats a run-level link construct with an external target as a representable reference extent", () => {
+ // isReferenceExtent recognises only an internal link target here -- an external one is the run-level ContentRun.hyperlink field's own established territory (ExaDev/document-schema.js#22), so a construct-level extent naming one is neither wrapped in its own <a> nor reported as an unhandled anchor (reportUnhandledAnchorExtents only covers descriptor.kind === "anchor").
+ const { xml, diagnostics } = writeWithSink(
+ [
+ {
+ kind: "paragraph",
+ runs: [{ text: "See" }, { text: "this" }],
+ constructs: [
+ {
+ descriptor: {
+ kind: "link",
+ target: { kind: "external", uri: "https://example.com" },
+ },
+ startRun: 1,
+ endRun: 2,
+ },
+ ],
+ },
+ ],
+ () => undefined,
+ );
+ expect(xml).not.toContain("<a ");
+ expect(xml).toContain("this");
+ expect(diagnostics).toHaveLength(0);
+ });
+
// ExaDev/documents.js#994's round-12 regression, one input shape past the same-startRun collision immediately above: two footnote extents that genuinely CROSS -- fn2's own startRun (1) falls strictly INSIDE fn1's already-winning range (runs 0-2), rather than sharing fn1's exact startRun. Because a winning range extent advances the write walk straight from its own startRun to its own endRun, index 1 is never visited at all, so the previous fix (which only looked for a collision among extents sharing the SAME startRun) never saw fn2 and dropped it with no diagnostic whatsoever -- the exact silent-drop class this whole diagnostic exists to close, just reached via a different input shape. document-schema.js's own RunConstructExtentSchema comment names this precise shape ("two entries may cross freely") as real, representable input.
it("reports CONSTRUCT_UNREPRESENTED and preserves all run text when two footnote extents genuinely cross", () => {
const blocks: ContentBlock[] = [
@@ -694,11 +1057,16 @@ describe("writeXhtmlBody", () => {
},
];
const { xml, diagnostics } = writeWithSink(blocks, () => undefined);
- expect(
- diagnostics.some(
- (d) => d.code === EpubDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
- ),
- ).toBe(true);
+ const unrepresented = diagnostics.find(
+ (d) => d.code === EpubDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+ );
+ // A point anchor's own message names the boundary it marks, distinctly from a range extent's "cannot be represented as its own <a> element" wording.
+ expect(unrepresented?.message).toContain(
+ "marking the boundary before run 1",
+ );
+ expect(unrepresented?.message).toContain(
+ "a point anchor wraps no run text of its own",
+ );
// fn1 wins and wraps every run; fn2's own anchor is not emitted, but no run text is lost -- a point anchor never wraps any of its own.
expect(xml).toContain('href="#fn1"');
expect(xml).not.toContain('href="#fn2"');
@@ -731,6 +1099,77 @@ describe("writeXhtmlBody", () => {
).toBe(true);
});
+ it("restores a bookmark target as an id attribute on its single wrapped element, replacing any id the element already carries", () => {
+ // A nested bookmark: the inner one wraps the paragraph first and stamps its own id onto it; the outer one must overwrite that id with its own name, not leave both id attributes in the array alongside it. The paragraph's own direction gives the wrapped <p> a second, unrelated attribute the filter must leave untouched -- a plain object literal's own duplicate-key-overwrite semantics would otherwise hide a filter that removed nothing at all (an extra "id" entry collapses to the same final serialized attribute either way), so this checks the raw attributes array directly rather than the serialized XML string.
+ const blocks: ContentBlock[] = [
+ {
+ kind: "constructStart",
+ descriptor: { kind: "anchor", anchorType: "bookmark", name: "outer" },
+ },
+ {
+ kind: "constructStart",
+ descriptor: { kind: "anchor", anchorType: "bookmark", name: "inner" },
+ },
+ { kind: "paragraph", direction: "rtl", runs: [{ text: "target" }] },
+ { kind: "constructEnd" },
+ { kind: "constructEnd" },
+ ];
+ const body = writeBody(blocks);
+ const [p] = body.children;
+ if (p?.type !== "element") {
+ throw new Error("expected a <p> element");
+ }
+ expect(p.attributes).toEqual([
+ { name: "dir", value: "rtl" },
+ { name: "id", value: "outer" },
+ ]);
+ });
+
+ it("reports CONSTRUCT_UNREPRESENTED with the exact message when a bookmark wraps more than one written element", () => {
+ const blocks: ContentBlock[] = [
+ {
+ kind: "constructStart",
+ descriptor: { kind: "anchor", anchorType: "bookmark", name: "bm1" },
+ },
+ { kind: "paragraph", runs: [{ text: "one" }] },
+ { kind: "paragraph", runs: [{ text: "two" }] },
+ { kind: "constructEnd" },
+ ];
+ const { xml, diagnostics } = writeWithSink(blocks, () => undefined);
+ expect(xml).toContain("one");
+ expect(xml).toContain("two");
+ expect(xml).not.toContain('id="bm1"');
+ const diagnostic = diagnostics.find(
+ (d) => d.code === EpubDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+ );
+ expect(diagnostic?.message).toBe(
+ "a bookmark target ('bm1') wraps more than one written element (or none); this package's writer only restores an id attribute onto a single wrapped element, so the target's own addressability is dropped",
+ );
+ });
+
+ it.each(["endnote", "comment"] as const)(
+ "reports CONSTRUCT_UNREPRESENTED for a block-scoped '%s' anchor construct group, distinctly from a bookmark, while still writing its content",
+ (anchorType) => {
+ const blocks: ContentBlock[] = [
+ {
+ kind: "constructStart",
+ descriptor: { kind: "anchor", anchorType, name: "x1" },
+ },
+ { kind: "paragraph", runs: [{ text: "body" }] },
+ { kind: "constructEnd" },
+ ];
+ const { xml, diagnostics } = writeWithSink(blocks, () => undefined);
+ expect(xml).toContain("body");
+ expect(xml).not.toContain('id="x1"');
+ const diagnostic = diagnostics.find(
+ (d) => d.code === EpubDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+ );
+ expect(diagnostic?.message).toBe(
+ "a 'anchor' construct has no XHTML spelling in this package's writer; its extent is written, the construct itself is not",
+ );
+ },
+ );
+
// ExaDev/documents.js#1025: a run-level anchor extent whose anchorType is anything but "footnote" (a bookmark or comment range docx documents can and do carry at run scope, e.g. ooxml.js's own runRangeMarkerExtents) has no representable EPUB spelling this reader's own read side understands yet, so it is reported through the diagnostic sink rather than silently dropped with nothing in the output naming it ever happened. The run text it wraps is unaffected either way -- only the anchor's own marker goes unwritten.
it.each(["bookmark", "endnote", "comment"] as const)(
"reports CONSTRUCT_UNREPRESENTED for a run-level '%s' anchor extent, preserving the run text underneath it",
@@ -773,4 +1212,17 @@ describe("writeXhtmlBody", () => {
expect(xml).toContain('src="images/img1.png"');
expect(xml).toContain('alt="alt"');
});
+
+ it("writes an image with no altText as an empty alt attribute, never a placeholder", () => {
+ const xml = write([
+ {
+ kind: "image",
+ format: "png",
+ base64: "aGVsbG8=",
+ widthPt: 72,
+ heightPt: 72,
+ },
+ ]);
+ expect(xml).toContain('alt=""');
+ });
});
diff --git a/packages/epub-codec/src/xhtml/write.ts b/packages/epub-codec/src/xhtml/write.ts
index f694cfcb5..40222dc1b 100644
--- a/packages/epub-codec/src/xhtml/write.ts
+++ b/packages/epub-codec/src/xhtml/write.ts
@@ -77,15 +77,15 @@ function writeSectionChildren(
): XmlNode[] {
const out: XmlNode[] = [];
let index = 0;
- while (index < children.length) {
+ for (;;) {
const child = children[index];
if (child === undefined) {
break;
}
if (isListGroupNode(child)) {
- // Every consecutive run of sibling ListGroupNode entries at this position is one <ul>/<ol> -- decompose emits one list group per item, as flat siblings, never pre-wrapped in a container element (see document-schema.js's own decomposeSectionBlocks/openListGroup).
+ // Every consecutive run of sibling ListGroupNode entries at this position is one <ul>/<ol> -- decompose emits one list group per item, as flat siblings, never pre-wrapped in a container element (see document-schema.js's own decomposeSectionBlocks/openListGroup). No separate `end < children.length` bound is needed ahead of isListGroupNode: past the array's own end, children[end] is undefined, and isListGroupNode(undefined) is already false (its own isRecord guard rejects a non-object outright), so the loop terminates at exactly the same point either way.
let end = index;
- while (end < children.length && isListGroupNode(children[end])) {
+ while (isListGroupNode(children[end])) {
end += 1;
}
const items = children.slice(index, end) as ListGroupNode[];
@@ -99,8 +99,9 @@ function writeSectionChildren(
return out;
}
+// Never called with a ListGroupNode: writeSectionChildren's own loop above always groups a run of one or more sibling ListGroupNode entries and writes them through writeList before this function is reached at all, so its own parameter type excludes that member rather than carrying a dead exhaustiveness branch no test can ever reach.
function writeSectionChild(
- child: SectionChild,
+ child: Exclude<SectionChild, ListGroupNode>,
context: XhtmlWriteContext,
): XmlNode[] {
if (isHeadingGroupNode(child)) {
@@ -109,10 +110,6 @@ function writeSectionChild(
...writeSectionChildren(child.children, context),
];
}
- if (isListGroupNode(child)) {
- // Reached only for a lone list group with no sibling run (writeSectionChildren's own loop always groups runs of one or more before calling this) -- kept for exhaustiveness, never actually hit.
- return [writeList([child], context)];
- }
if (isSectionConstructGroupNode(child)) {
return writeSectionConstructGroup(child, context);
}
@@ -149,7 +146,8 @@ function writeList(
const itemId = items[index]?.node.list.itemId;
let end = index + 1;
if (itemId !== undefined) {
- while (end < items.length && items[end]?.node.list.itemId === itemId) {
+ // No separate `end < items.length` bound is needed ahead of the itemId comparison: past the array's own end, items[end] is undefined, and its own optional-chained `?.node.list.itemId` is therefore undefined too -- which can never equal itemId, since this branch only runs when itemId is itself a real, defined string -- so the loop terminates at exactly the same point either way.
+ while (items[end]?.node.list.itemId === itemId) {
end += 1;
}
}
diff --git a/packages/epub-codec/src/xml/build.test.ts b/packages/epub-codec/src/xml/build.test.ts
new file mode 100644
index 000000000..5abde5e19
--- /dev/null
+++ b/packages/epub-codec/src/xml/build.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { buildXml } from "./build";
+
+describe("buildXml", () => {
+ it("builds a bare text node with no wrapping tag", () => {
+ expect(buildXml([{ type: "text", value: "hello" }])).toBe("hello");
+ });
+
+ it("builds a comment node", () => {
+ expect(buildXml([{ type: "comment", value: "a comment" }])).toBe(
+ "<!--a comment-->",
+ );
+ });
+
+ it("builds a cdata node", () => {
+ expect(buildXml([{ type: "cdata", value: "raw <data>" }])).toBe(
+ "<![CDATA[raw <data>]]>",
+ );
+ });
+
+ it("builds a processing instruction node, keyed by its own target", () => {
+ expect(
+ buildXml([
+ { type: "pi", target: "xml-stylesheet", content: 'href="x.xsl"' },
+ ]),
+ ).toBe("<?xml-stylesheet?>");
+ });
+
+ it("builds an XML declaration carrying its own attributes", () => {
+ expect(
+ buildXml([
+ {
+ type: "declaration",
+ attributes: [
+ { name: "version", value: "1.0" },
+ { name: "encoding", value: "UTF-8" },
+ ],
+ },
+ ]),
+ ).toBe('<?xml version="1.0" encoding="UTF-8"?>');
+ });
+
+ it("builds an element with no attributes, omitting the attribute object entirely", () => {
+ expect(
+ buildXml([
+ {
+ type: "element",
+ tag: "p",
+ attributes: [],
+ children: [{ type: "text", value: "hi" }],
+ },
+ ]),
+ ).toBe("<p>hi</p>");
+ });
+
+ it("builds an element carrying its own attributes", () => {
+ expect(
+ buildXml([
+ {
+ type: "element",
+ tag: "p",
+ attributes: [{ name: "class", value: "note" }],
+ children: [],
+ },
+ ]),
+ ).toBe('<p class="note"></p>');
+ });
+
+ it("builds nested elements in document order", () => {
+ expect(
+ buildXml([
+ {
+ type: "element",
+ tag: "div",
+ attributes: [],
+ children: [
+ {
+ type: "element",
+ tag: "span",
+ attributes: [],
+ children: [{ type: "text", value: "x" }],
+ },
+ ],
+ },
+ ]),
+ ).toBe("<div><span>x</span></div>");
+ });
+});
diff --git a/packages/epub-codec/src/xml/build.ts b/packages/epub-codec/src/xml/build.ts
index 8fe6c692d..03ce37281 100644
--- a/packages/epub-codec/src/xml/build.ts
+++ b/packages/epub-codec/src/xml/build.ts
@@ -13,12 +13,9 @@ const BUILDER = new XMLBuilder({
suppressEmptyNode: false,
});
+// XMLBuilder#build's own type declaration already returns `string` unconditionally (fast-xml-parser's fxp.d.ts: `build(jObj: any): string`), so no runtime check is needed here to narrow it.
export function buildXml(nodes: XmlNode[]): string {
- const out = BUILDER.build(toOrdered(nodes));
- if (typeof out !== "string") {
- throw new Error("XMLBuilder did not return a string");
- }
- return out;
+ return BUILDER.build(toOrdered(nodes));
}
function toOrdered(nodes: XmlNode[]): unknown[] {
@@ -41,19 +38,16 @@ function toOrderedNode(node: XmlNode): Record<string, unknown> {
return { __comment: [{ "#text": node.value }] };
case "cdata":
return { __cdata: [{ "#text": node.value }] };
+ // A pi/declaration node's own value is never read at all by fast-xml-parser's builder in preserveOrder mode -- confirmed empirically against every shape tried (an empty array, one holding a real "#text" entry, undefined, null, a plain object): build([{ "?target": <any of these> }]) always produces the identical "<?target?>", the same quirk this builder's own reader hits on the way in (a plain or attribute-shaped PI's content parses back as "" either way). undefined is therefore used here as the plainest spelling of "this value is never consulted", not a placeholder standing in for children data the builder would otherwise use.
case "pi":
- return { [`?${node.target}`]: [{ "#text": node.content }] };
+ return { [`?${node.target}`]: undefined };
case "declaration":
- return { "?xml": [{ "#text": "" }], ":@": attrsObject(node.attributes) };
- case "element": {
- const obj: Record<string, unknown> = {
+ return { "?xml": undefined, ":@": attrsObject(node.attributes) };
+ case "element":
+ // No emptiness check before setting ":@": XMLBuilder renders an empty attributes object identically to an entirely absent ":@" key (confirmed empirically), so guarding it here would only ever produce output indistinguishable from not guarding it.
+ return {
[node.tag]: toOrdered(node.children),
+ ":@": attrsObject(node.attributes),
};
- const attrs = attrsObject(node.attributes);
- if (Object.keys(attrs).length > 0) {
- obj[":@"] = attrs;
- }
- return obj;
- }
}
}
diff --git a/packages/epub-codec/src/xml/entities.test.ts b/packages/epub-codec/src/xml/entities.test.ts
index 044aa6e82..0b55839cd 100644
--- a/packages/epub-codec/src/xml/entities.test.ts
+++ b/packages/epub-codec/src/xml/entities.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
-import { decodeEntities, encodeEntities } from "./entities";
+import { decodeEntities, decodeTextLikeNode, encodeEntities } from "./entities";
describe("decodeEntities", () => {
it("decodes the five standard XML entities", () => {
@@ -30,6 +30,20 @@ describe("decodeEntities", () => {
});
});
+describe("decodeTextLikeNode", () => {
+ it("decodes entities in a text node", () => {
+ expect(decodeTextLikeNode({ type: "text", value: "A & B" })).toBe(
+ "A & B",
+ );
+ });
+
+ it("leaves a cdata node's value untouched, with no entity decoding applied", () => {
+ expect(decodeTextLikeNode({ type: "cdata", value: "A & B" })).toBe(
+ "A & B",
+ );
+ });
+});
+
describe("encodeEntities", () => {
it("escapes the five standard XML entities, ampersand first", () => {
expect(encodeEntities(`&<>"'`)).toBe("&<>"'");
diff --git a/packages/epub-codec/src/xml/node.test.ts b/packages/epub-codec/src/xml/node.test.ts
new file mode 100644
index 000000000..15ac5da6c
--- /dev/null
+++ b/packages/epub-codec/src/xml/node.test.ts
@@ -0,0 +1,221 @@
+import { describe, expect, it } from "vitest";
+import { isTextLikeNode, isXmlNode } from "./node";
+
+describe("isXmlNode", () => {
+ it("rejects null", () => {
+ expect(isXmlNode(null)).toBe(false);
+ });
+
+ it("rejects an array", () => {
+ expect(isXmlNode([])).toBe(false);
+ });
+
+ it("rejects a non-object primitive", () => {
+ expect(isXmlNode("not a node")).toBe(false);
+ expect(isXmlNode(5)).toBe(false);
+ });
+
+ it("rejects an object with an unrecognised type", () => {
+ expect(isXmlNode({ type: "unknown" })).toBe(false);
+ });
+
+ it("rejects an object with an unrecognised type even when it otherwise has every field an element node would need", () => {
+ expect(
+ isXmlNode({
+ type: "unrecognised",
+ tag: "div",
+ attributes: [],
+ children: [],
+ }),
+ ).toBe(false);
+ });
+
+ it("rejects a value whose typeof is not object even when it carries every property a text node would need", () => {
+ // A function value with `type`/`value` properties bolted on directly, deliberately keeping `typeof fnMasqueradingAsText === "function"` -- Object.assign/spread would either lose that (spreading into a plain object) or bypass type checking on the source, so the properties are set one at a time on a value cast to the shape isXmlNode expects a text node to have.
+ const fnMasqueradingAsText = (() => {}) as unknown as {
+ type: string;
+ value: string;
+ };
+ fnMasqueradingAsText.type = "text";
+ fnMasqueradingAsText.value = "hi";
+ expect(isXmlNode(fnMasqueradingAsText)).toBe(false);
+ });
+
+ it("accepts a text node with a string value", () => {
+ expect(isXmlNode({ type: "text", value: "hello" })).toBe(true);
+ });
+
+ it("rejects a text node whose value is not a string", () => {
+ expect(isXmlNode({ type: "text", value: 5 })).toBe(false);
+ });
+
+ it("accepts a cdata node with a string value", () => {
+ expect(isXmlNode({ type: "cdata", value: "raw" })).toBe(true);
+ });
+
+ it("rejects a cdata node whose value is not a string", () => {
+ expect(isXmlNode({ type: "cdata", value: 5 })).toBe(false);
+ });
+
+ it("accepts a comment node with a string value", () => {
+ expect(isXmlNode({ type: "comment", value: "note" })).toBe(true);
+ });
+
+ it("rejects a comment node whose value is not a string", () => {
+ expect(isXmlNode({ type: "comment", value: 5 })).toBe(false);
+ });
+
+ it("accepts a declaration node whose attributes are all well-formed", () => {
+ expect(
+ isXmlNode({
+ type: "declaration",
+ attributes: [{ name: "version", value: "1.0" }],
+ }),
+ ).toBe(true);
+ });
+
+ it("accepts a declaration node with no attributes at all", () => {
+ expect(isXmlNode({ type: "declaration", attributes: [] })).toBe(true);
+ });
+
+ it("rejects a declaration node whose attributes is not an array", () => {
+ expect(isXmlNode({ type: "declaration", attributes: "not-an-array" })).toBe(
+ false,
+ );
+ });
+
+ it("rejects a declaration node with one malformed attribute among well-formed ones", () => {
+ expect(
+ isXmlNode({
+ type: "declaration",
+ attributes: [{ name: "version", value: "1.0" }, { name: 5 }],
+ }),
+ ).toBe(false);
+ });
+
+ it("accepts a pi node with string target and content", () => {
+ expect(isXmlNode({ type: "pi", target: "t", content: "c" })).toBe(true);
+ });
+
+ it("rejects a pi node whose target is not a string", () => {
+ expect(isXmlNode({ type: "pi", target: 5, content: "c" })).toBe(false);
+ });
+
+ it("rejects a pi node whose content is not a string", () => {
+ expect(isXmlNode({ type: "pi", target: "t", content: 5 })).toBe(false);
+ });
+
+ it("accepts an element node with well-formed attributes and children", () => {
+ expect(
+ isXmlNode({
+ type: "element",
+ tag: "p",
+ attributes: [{ name: "class", value: "note" }],
+ children: [{ type: "text", value: "hi" }],
+ }),
+ ).toBe(true);
+ });
+
+ it("accepts an element node with no attributes and no children", () => {
+ expect(
+ isXmlNode({ type: "element", tag: "br", attributes: [], children: [] }),
+ ).toBe(true);
+ });
+
+ it("rejects an element node whose tag is not a string", () => {
+ expect(
+ isXmlNode({ type: "element", tag: 5, attributes: [], children: [] }),
+ ).toBe(false);
+ });
+
+ it("rejects an element node whose attributes is not an array", () => {
+ expect(
+ isXmlNode({
+ type: "element",
+ tag: "p",
+ attributes: "nope",
+ children: [],
+ }),
+ ).toBe(false);
+ });
+
+ it("rejects an element node with a malformed attribute", () => {
+ expect(
+ isXmlNode({
+ type: "element",
+ tag: "p",
+ attributes: [{ name: 5, value: "x" }],
+ children: [],
+ }),
+ ).toBe(false);
+ });
+
+ it("rejects an element node whose attribute has a well-formed name but a non-string value", () => {
+ expect(
+ isXmlNode({
+ type: "element",
+ tag: "p",
+ attributes: [{ name: "id", value: 5 }],
+ children: [],
+ }),
+ ).toBe(false);
+ });
+
+ it("rejects an element node whose children is not an array", () => {
+ expect(
+ isXmlNode({
+ type: "element",
+ tag: "p",
+ attributes: [],
+ children: "nope",
+ }),
+ ).toBe(false);
+ });
+
+ it("rejects an element node whose children contains a malformed node (recursive check)", () => {
+ expect(
+ isXmlNode({
+ type: "element",
+ tag: "p",
+ attributes: [],
+ children: [{ type: "text", value: 5 }],
+ }),
+ ).toBe(false);
+ });
+
+ it("rejects an element node whose children contains a well-formed sibling followed by a malformed one", () => {
+ expect(
+ isXmlNode({
+ type: "element",
+ tag: "p",
+ attributes: [],
+ children: [{ type: "text", value: "ok" }, { type: "unknown" }],
+ }),
+ ).toBe(false);
+ });
+});
+
+describe("isTextLikeNode", () => {
+ it("is true for a text node", () => {
+ expect(isTextLikeNode({ type: "text", value: "x" })).toBe(true);
+ });
+
+ it("is true for a cdata node", () => {
+ expect(isTextLikeNode({ type: "cdata", value: "x" })).toBe(true);
+ });
+
+ it("is false for a comment node", () => {
+ expect(isTextLikeNode({ type: "comment", value: "x" })).toBe(false);
+ });
+
+ it("is false for an element node", () => {
+ expect(
+ isTextLikeNode({
+ type: "element",
+ tag: "p",
+ attributes: [],
+ children: [],
+ }),
+ ).toBe(false);
+ });
+});
diff --git a/packages/epub-codec/src/xml/parse.test.ts b/packages/epub-codec/src/xml/parse.test.ts
index 58c8d8a16..091857bcd 100644
--- a/packages/epub-codec/src/xml/parse.test.ts
+++ b/packages/epub-codec/src/xml/parse.test.ts
@@ -1,7 +1,13 @@
import { describe, expect, it } from "vitest";
import { buildXml } from "./build";
import { rootElement } from "./query";
-import { parseXml } from "./parse";
+import {
+ parseAttributes,
+ parseNode,
+ parseNodes,
+ parseXml,
+ scalarText,
+} from "./parse";
describe("parseXml", () => {
it("parses a simple element with attributes and text", () => {
@@ -44,6 +50,26 @@ describe("parseXml", () => {
});
});
+ it("parses a comment node", () => {
+ const nodes = parseXml("<!--a comment--><p/>");
+ expect(nodes[0]).toEqual({ type: "comment", value: "a comment" });
+ });
+
+ it("parses a cdata node", () => {
+ const nodes = parseXml("<p><![CDATA[raw <data>]]></p>");
+ const root = rootElement(nodes);
+ expect(root?.children).toEqual([{ type: "cdata", value: "raw <data>" }]);
+ });
+
+ it("parses a processing instruction node, keyed by its own target", () => {
+ const nodes = parseXml('<?xml-stylesheet href="x.xsl"?><p/>');
+ expect(nodes[0]).toEqual({
+ type: "pi",
+ target: "xml-stylesheet",
+ content: "",
+ });
+ });
+
it("parses namespaced tag and attribute names verbatim", () => {
const nodes = parseXml(
'<html xmlns:epub="http://www.idpf.org/2007/ops"><body epub:type="bodymatter"/></html>',
@@ -76,3 +102,86 @@ describe("buildXml", () => {
expect(reparsed?.children).toEqual([]);
});
});
+
+// The functions below validate the shape of fast-xml-parser's own `any`-typed output -- no syntactically valid XML string can drive parseXml itself into most of these branches, since the shape they check is the library's own internal invariant, not something malformed markup can violate. Exercised directly with adversarial `unknown` values instead, exactly like node.ts's own isXmlNode.
+describe("parseNodes", () => {
+ it("rejects a value that is not an array", () => {
+ expect(() => parseNodes("not an array")).toThrow(
+ "fast-xml-parser output was not an ordered array",
+ );
+ });
+});
+
+describe("parseNode", () => {
+ it("rejects a value that is not a plain record", () => {
+ expect(() => parseNode("not a record")).toThrow(
+ "fast-xml-parser node was not an object",
+ );
+ });
+
+ it("rejects null", () => {
+ expect(() => parseNode(null)).toThrow(
+ "fast-xml-parser node was not an object",
+ );
+ });
+
+ it("rejects an array", () => {
+ expect(() => parseNode([])).toThrow(
+ "fast-xml-parser node was not an object",
+ );
+ });
+
+ it("rejects a record with more than one non-:@ key", () => {
+ expect(() => parseNode({ a: [], b: [] })).toThrow(
+ "XML node had multiple tag keys",
+ );
+ });
+
+ it("rejects a record with no tag key at all", () => {
+ expect(() => parseNode({ ":@": {} })).toThrow("XML node had no tag key");
+ });
+
+ it("rejects a #text node whose own text is not a string", () => {
+ expect(() => parseNode({ "#text": 5 })).toThrow(
+ "expected string while parsing XML, got number",
+ );
+ });
+});
+
+describe("parseAttributes", () => {
+ it("returns an empty list for undefined", () => {
+ expect(parseAttributes(undefined)).toEqual([]);
+ });
+
+ it("rejects a value that is not a plain record", () => {
+ expect(() => parseAttributes("not a record")).toThrow(
+ "XML attributes were not an object",
+ );
+ });
+
+ it("rejects a key without the @_ prefix", () => {
+ expect(() => parseAttributes({ id: "x" })).toThrow(
+ "unexpected attribute key without @_ prefix: id",
+ );
+ });
+});
+
+describe("scalarText", () => {
+ it("rejects a value that is not an array", () => {
+ expect(() => scalarText("not an array")).toThrow(
+ "expected a scalar-text wrapper array",
+ );
+ });
+
+ it("rejects an empty array", () => {
+ expect(() => scalarText([])).toThrow(
+ "expected a scalar-text wrapper array",
+ );
+ });
+
+ it("rejects a wrapper whose first element is not a record", () => {
+ expect(() => scalarText(["not a record"])).toThrow(
+ "scalar-text wrapper was not an object",
+ );
+ });
+});
diff --git a/packages/epub-codec/src/xml/parse.ts b/packages/epub-codec/src/xml/parse.ts
index d85a0d42f..fe72419b3 100644
--- a/packages/epub-codec/src/xml/parse.ts
+++ b/packages/epub-codec/src/xml/parse.ts
@@ -34,14 +34,15 @@ function asString(value: unknown): string {
return value;
}
-function parseNodes(raw: unknown): XmlNode[] {
+export function parseNodes(raw: unknown): XmlNode[] {
if (!isUnknownArray(raw)) {
throw new Error("fast-xml-parser output was not an ordered array");
}
return raw.map(parseNode);
}
-function parseNode(raw: unknown): XmlNode {
+// Exported alongside parseAttributes and scalarText below purely so a test can drive each of this module's own runtime shape checks directly with an adversarial `unknown` value: fast-xml-parser's own `.parse()` return type is `any`, so nothing upstream of parseXml can guarantee these shapes at compile time, and no syntactically valid XML string reaches most of these branches through fast-xml-parser's own preserveOrder output (its shape is the library's own internal invariant, not something malformed input can violate) -- these are the same kind of runtime boundary check as node.ts's own isXmlNode, which is exported and unit-tested the identical way.
+export function parseNode(raw: unknown): XmlNode {
if (!isRecord(raw)) {
throw new Error("fast-xml-parser node was not an object");
}
@@ -86,7 +87,7 @@ function parseNode(raw: unknown): XmlNode {
};
}
-function parseAttributes(raw: unknown): Attribute[] {
+export function parseAttributes(raw: unknown): Attribute[] {
if (raw === undefined) {
return [];
}
@@ -104,7 +105,7 @@ function parseAttributes(raw: unknown): Attribute[] {
}
// Comments, CDATA and PIs wrap their text as [{ '#text': string }].
-function scalarText(raw: unknown): string {
+export function scalarText(raw: unknown): string {
if (!isUnknownArray(raw) || raw.length === 0) {
throw new Error("expected a scalar-text wrapper array");
}
diff --git a/packages/epub-codec/src/xml/query.test.ts b/packages/epub-codec/src/xml/query.test.ts
index 2cc39fcba..260b3fd59 100644
--- a/packages/epub-codec/src/xml/query.test.ts
+++ b/packages/epub-codec/src/xml/query.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
import type { XmlNode } from "./node";
-import { decodedTextContent, textContent } from "./query";
+import { decodedTextContent, elementsWithTag, textContent } from "./query";
function text(value: string): XmlNode {
return { type: "text", value };
@@ -31,6 +31,24 @@ describe("textContent", () => {
});
});
+describe("elementsWithTag", () => {
+ it("finds every element with the given tag anywhere in the forest, skipping other tags and non-element nodes", () => {
+ const forest: XmlNode[] = [
+ text("intro"),
+ el("div", [el("p", [text("a")]), el("span", [text("b")])]),
+ el("p", [cdata("c")]),
+ ];
+ expect(elementsWithTag(forest, "p")).toEqual([
+ el("p", [text("a")]),
+ el("p", [cdata("c")]),
+ ]);
+ });
+
+ it("returns an empty array when no element matches", () => {
+ expect(elementsWithTag([el("div", [text("x")])], "p")).toEqual([]);
+ });
+});
+
describe("decodedTextContent", () => {
it("decodes entities in a text-node descendant exactly once", () => {
// A literal source "&" is the two-character entity "&" written out verbatim -- one decode pass restores it to the five-character string "&"; a second pass would over-decode it to a bare "&".