# Paged Book Bundle Contract v1
Status: normativ og stabil. Denne fil er den selvstændige kontrakt for at bygge
en ny bundle. Ordene **SKAL**, **MÅ IKKE**, **BØR** og **KAN** er normative.
Manifestets maskinlæsbare kontrakt er
[`schemas/book-viewer.bundle.v1.schema.json`](../schemas/book-viewer.bundle.v1.schema.json).
En bundle er en passiv, selvbærende bogrevision. Den kan valideres som en mappe
og uploades som et gzip-komprimeret tar-arkiv. Runtime-, adgangs-, bruger- og
annotationsdata hører aldrig til i bundlen.
## Hurtigste sikre vej for mennesker og agenter
Fra repository-roden:
```sh
bun run bundle init --out ./my-book --id my-book --title "Min bog"
# Erstat det genererede indhold, og behold kontraktmarkørerne.
bun run bundle validate ./my-book --expected-book-id my-book --json
bun run bundle pack ./my-book --out ./my-book.tar.gz --expected-book-id my-book --json
bun run bundle validate ./my-book.tar.gz --expected-book-id my-book --json
```
`init` skaber den minimale gyldige fixture. `pack` validerer først og skaber et
deterministisk arkiv; samme filindhold giver byte-identisk output. Brug denne
kommando frem for en generel tar-kommando.
## Kanoniske layouts
Den minimale bundle findes i [`example/minimal-book`](../example/minimal-book):
```text
my-book/
├── book-viewer.json
└── book.html
```
Den komplette integrationsfixture findes i [`example/book`](../example/book):
```text
book/
├── book-viewer.json
├── book.html
└── navigation.xhtml
```
Den komplette fixture viser alle manifestfelter, hierarkisk navigation, flere
sider og flere ankertyper. `book-viewer.json` SKAL ligge direkte i roden.
Assetmapper til CSS, billeder og fonts er valgfrie.
## Manifestet `book-viewer.json`
Et nyt v1-manifest SKAL være UTF-8 JSON, matche JSON Schemaet og må ikke have
ukendte felter:
```json
{
"schemaVersion": 1,
"book": {
"id": "my-book",
"title": "Min bog",
"subtitle": "Første korrektur",
"mark": "MB",
"language": "da",
"document": "book.html",
"navigation": "navigation.xhtml",
"buildId": "2026-07-15T10:00:00Z"
}
}
```
| Felt | Krav |
| --- | --- |
| `schemaVersion` | Påkrævet og præcis tallet `1`. |
| `book.id` | Påkrævet, stabilt og 1–96 tegn. Regex: `^[a-z0-9][a-z0-9_-]{0,95}$`. Ved upload SKAL det matche katalogbogens id. |
| `book.title` | Påkrævet, ikke-tom tekst, højst 200 tegn. |
| `book.document` | Påkrævet relativ POSIX-sti til bogens `.html`- eller `.xhtml`-dokument, højst 240 tegn. |
| `book.subtitle` | Valgfri, ikke-tom tekst, højst 300 tegn. |
| `book.mark` | Valgfri, ikke-tom tekst, højst 16 tegn. |
| `book.language` | Valgfri, ikke-tom tekst, 2–35 tegn; BØR være et BCP 47-sprog-tag. |
| `book.navigation` | Valgfri relativ POSIX-sti til en `.xhtml`-navigation. |
| `book.buildId` | Valgfri stabil build-identitet, højst 200 tegn. |
En bundle-sti SKAL være relativ, bruge `/`, have ikke-tomme segmenter og må
ikke indeholde `.`- eller `..`-segmenter, `?`, `#`, backslash, NUL, drevbogstav eller
absolut rod.
## Bogdokumentet
`book.document` SKAL være et passivt, færdigpagineret HTML-dokument. Det SKAL:
1. indeholde mindst én `.pagedjs_pages`-container og én `.pagedjs_page`;
2. sætte `data-paged-complete="true"` på `` eller
`data-pre-paginated="true"` på ``;
3. indeholde mindst én unik `data-book-anchor`;
4. give hvert element med `data-annotation-text` sit eget unikke
`data-book-anchor`.
Minimal struktur:
```html
Min bog
```
`data-book-anchor` er en permanent indholdsidentitet og BØR ikke indeholde et
sidetal. Sidetal og `data-book-page-label` er kun hints. En ændret udgave BØR
genbruge ankeret, når det semantisk er samme passage. Uklare matches bliver
`anchorState: orphaned`; klienter må ikke gætte. Den fulde
genforankringskontrakt står i
[`manifest-and-anchors.md`](manifest-and-anchors.md).
Hvis `book.navigation` er angivet, SKAL dokumentet opfylde
[`navigation.md`](navigation.md), og hvert lokalt link SKAL pege på et
eksisterende stabilt mål i bogdokumentet.
## Passive filer og referencer
Bundlen SKAL fungere uden netværk og uden værtens filsystem. `src`, `href`,
`poster`, CSS `url()` og CSS `@import` SKAL pege på eksisterende regulære filer
inde i bundlen. Fragmenter og passive, indlejrede rasterbilleder som
`data:image/avif`, `bmp`, `gif`, `jpeg`, `png` eller `webp` er tilladt; øvrige
`data:`-URL'er er forbudt. Eksterne schemes, protocol-relative URL'er
og stier ud af roden er forbudt. Strikte bundles må ikke bruge `srcset`, fordi
hver kandidat ellers udgør sin egen referencekanal.
Følgende er forbudt:
- symbolske links, hardlinks, devices, sockets og andre specialfiler;
- aktiv markup: blandt andet `script`, forms, frames, portals, `object`, `embed`,
`base`, event-attributter, namespacede aktive elementer, `javascript:` og
refresh-meta;
- aktiv SVG: blandt andet `script`, `foreignObject`, animation og
event-attributter;
- aktiv CSS: `expression()`, `behavior`, `-moz-binding` og `image-set()`;
- inline `