Improve documentation

Author: o0Zz

CLAUDE.md

@@ -232,16 +232,27 @@ its opener and the magic numbers `Sniff` answers to, and `BookContainers` only s
 which containers are in the build.
 
 Everything downstream reads the two registries, so neither addition edits a third
-file. In particular: the Settings form's context-menu checkboxes and the file-dialog
-filter are both built from `Extensions`, the log's name for a format comes from
-`FormatId.DisplayName`, and `BookFormats.FromExtension` and `BookContainers.Sniff`
-answer from what is registered rather than from a `switch`. **If a change of yours
-needs a list of formats or extensions written out a second time, that is the bug.**
+file. In particular: the Settings form's context-menu checkboxes, the file-dialog
+filter and the About box are all built from `Extensions`, the log's name for a format
+comes from `FormatId.DisplayName`, and `BookFormats.FromExtension` and
+`BookContainers.Sniff` answer from what is registered rather than from a `switch`.
+**If a change of yours needs a list of formats or extensions written out a second
+time, that is the bug.** Nothing outside `BookContainers`' six `Register` lines names
+a container type at all, and there is no `switch` on `ContainerKind` anywhere.
+
+`ExtensionPointTests` is that promise made executable: it adds a container and a
+format from the *test* assembly, registers them, and opens a file end to end through
+`Book.Load` — no Core file edited. It is what fails if the inventory gets hardcoded
+again.
 
 The exceptions, all deliberate:
 
-- **`FormatId` and `ContainerKind`** are enums, so a new one is a line in each plus a
-  line in `DisplayName`.
+- **`ContainerKind`** is an enum, so a new container is also a line there. That, the
+  file, and the `Register` call are the complete list for a container nothing needs
+  to *read as a book*.
+- **A container holds books only once a format claims it.** For a comic archive that
+  is one row in `CbzFormat.Flavours`, plus a `FormatId` and its `DisplayName` line;
+  for anything else, a new `IBookFormat`.
 - **`FormatCapabilities`** must be stated per format — see **Formats**.
 - **`.fb2.zip`** is the one compound extension. `Fb2Format` declares it, the file
   dialog offers it, and `ShellRegistration` drops it, because

README.md

@@ -20,7 +20,7 @@ There are already excellent ebook-management tools, but none quite matched the w
 
 * **Edit files directly from Explorer.** No library import or database required.
 * **Batch-edit an entire collection.** Select multiple files, open a folder, or paste values across dozens of books at once.
-* **Support the formats I actually use.** EPUB, CBZ, CBT, CBR, FB2, MOBI, AZW, and AZW3.
+* **Support the formats I actually use.** EPUB, CBZ, CBT, CBR, CB7, FB2, MOBI, AZW, and AZW3.
 * **Write metadata correctly.** The editor does not just insert values into an OPF or `ComicInfo.xml`; it validates and normalizes the surrounding metadata where possible.
 * **Avoid pretending formats support things they do not.** Fields that cannot be stored safely are disabled instead of being silently discarded or written into undocumented locations.
 
@@ -32,22 +32,22 @@ There are already excellent ebook-management tools, but none quite matched the w
 | CBZ        | ✅    | ✅     | ZIP       | `ComicInfo.xml`      |
 | CBT        | ✅    | ✅     | TAR       | `ComicInfo.xml`      |
 | CBR        | ✅    | ⚙️     | RAR       | `ComicInfo.xml`      |
+| CB7        | ✅    | ⚙️     | 7z        | `ComicInfo.xml`      |
 | FB2        | ✅    | ✅     | Plain XML | `<description>`      |
 | FB2.ZIP    | ✅    | ✅     | ZIP       | `<description>`      |
 | MOBI / PRC | ✅    | ✅     | PalmDB    | EXTH records         |
 | AZW / AZW3 | ✅    | ✅     | PalmDB    | EXTH records         |
 
-**⚙️ CBR reads on its own; saving one needs WinRAR installed.**.
-So EBookMetaEditor reads CBR files out of the box, and to save one it uses the `Rar.exe` that comes with WinRAR:
-it looks for your WinRAR installation in the registry, then for `rar.exe` on your `PATH`.
+**⚙️ CBR and CB7 read on their own; saving one needs the matching archiver installed.**
+EBookMetaEditor reads both out of the box. Writing them needs a compressor it is not allowed to ship, so to save a CBR it runs the `Rar.exe` that comes with WinRAR, and to save a CB7 the `7z.exe` that comes with 7-Zip. It looks for the installation in the registry, then for the program on your `PATH`. If neither turns up, the save is refused and your file is left exactly as it was — nothing is half-written, and no other format is affected.
 
-**Not supported:** CB7, PDF, KFX, AZW4, LIT, PDB, RB, DjVu, and audiobooks.
+**Not supported:** PDF, KFX, AZW4, LIT, PDB, RB, DjVu, and audiobooks.
 
 ## Editable metadata
 
 Not every format can store the same metadata. EBookMetaEditor disables fields that a particular file cannot preserve rather than accepting a value that would later be lost.
 
-| Field                    | EPUB         | CBZ / CBT / CBR | FB2       | MOBI / AZW3  |
+| Field                    | EPUB         | CBZ / CBT / CBR / CB7 | FB2       | MOBI / AZW3  |
 | ------------------------ | ------------ | ------------ | ------------ | ------------ |
 | Title                    | read + write | read + write | read + write | read + write |
 | Sort title               | read + write | —            | —            | —            |
@@ -59,7 +59,6 @@ Not every format can store the same metadata. EBookMetaEditor disables fields th
 | Description              | read + write | read + write | read + write | read + write |
 | Publisher                | read + write | read + write | read + write | read + write |
 | Publication date         | read + write | read + write | read + write | read + write |
-| Modification date        | read + write | —            | —            | —            |
 | Language                 | read + write | read + write | read + write | read + write |
 | Subjects / tags          | read + write | read + write | read + write | read + write |
 | Identifiers (ISBN, etc.) | read + write | —            | read         | read         |
@@ -107,9 +106,9 @@ Unmodified files are not rewritten — they are not even opened for writing. Eve
 
 Each row reports its own result, so one bad file does not stop the rest of the batch. For example:
 
-* A `.cbz` that is actually a 7z archive is reported as unsupported, by name.
-* A `.cbz` that is actually a RAR opens as a CBR, and the mismatch is still reported.
-* A CBR row reads and edits like any other; on save it either goes through the `Rar.exe` found on the machine or reports that the save failed.
+* A `.cbz` that is actually a RAR opens as a CBR, and one that is actually a 7z opens as a CB7. Either way the mismatch is still reported.
+* A `.cbz` that is actually a PDF is reported as unsupported, by name.
+* A CBR or CB7 row reads and edits like any other; on save it either goes through the archiver found on the machine or reports that the save failed.
 * A DRM-protected AZW is reported as non-editable.
 * A file that fails to save fails independently without aborting the remaining files.
 

src/EBookMeta.Core/IBookFormat.cs

@@ -1,4 +1,4 @@
-using EBookMeta.Model;
+using EBookMeta.Model;
 
 namespace EBookMeta;
 
@@ -76,12 +76,15 @@ public enum FormatId
     Cbz,
 
     /// <summary>
-    /// Comic archive, RAR. <c>ComicInfo.xml</c>, read but never written — see
-    /// <c>RarContainer</c>.
+    /// Comic archive, RAR. <c>ComicInfo.xml</c>, written only where the machine has
+    /// an archiver — see <c>RarContainer</c>.
     /// </summary>
     Cbr,
 
-    /// <summary>Comic archive, 7z.</summary>
+    /// <summary>
+    /// Comic archive, 7z. <c>ComicInfo.xml</c>, written only where the machine has
+    /// an archiver — see <c>SevenZipContainer</c>.
+    /// </summary>
     Cb7,
 
     /// <summary>Comic archive, TAR.</summary>

src/EBookMeta.Core/IContainer.cs

@@ -63,10 +63,10 @@ public enum ContainerKind
     /// <summary>ZIP.</summary>
     Zip,
 
-    /// <summary>RAR, versions 4 and 5. Readable; never rebuilt.</summary>
+    /// <summary>RAR, versions 4 and 5. Rebuilt only through an archiver on the machine.</summary>
     Rar,
 
-    /// <summary>7z.</summary>
+    /// <summary>7z. Rebuilt only through an archiver on the machine.</summary>
     SevenZip,
 
     /// <summary>TAR.</summary>
@@ -212,7 +212,7 @@ public sealed record ContainerEntry
     /// <summary>
     /// Whether an entry name is absolute, or walks out of the archive with <c>..</c>.
     /// Hard invariant 4, and the one predicate for it, so the read path and
-    /// <c>RarContainer.Stage</c> cannot disagree about what "escapes" means.
+    /// <c>ExternalArchiver.Stage</c> cannot disagree about what "escapes" means.
     /// </summary>
     public static bool EscapesArchive(string? name)
     {

src/EBookMeta.Core/README.md

@@ -5,6 +5,146 @@ broken, and writing it back without disturbing anything else. Zero UI dependenci
 — that is enforced by the `GuardCoreHasNoUiDependencies` target in the csproj, not
 by review.
 
+## How it fits together
+
+Two axes, deliberately the same shape. A **container** knows how to get bytes out of a
+file and how to write a new one; a **format** knows what the metadata document inside
+those bytes means. Neither has heard of the other, and `Book` is the only thing
+holding one of each.
+
+```
+                     ┌──────────────────────────┐
+                     │ Book                     │
+                     │                          │
+                     │ Load(path)      Save()   │
+                     └─────────────┬────────────┘
+                                   │  asks both registries and names
+                                   │  no implementation of either
+                 ┌─────────────────┴─────────────────┐
+                 │                                   │
+   seam 1 · the metadata document       seam 2 · the bytes it sits in
+                 │                                   │
+   ┌─────────────▼────────────┐        ┌─────────────▼────────────┐
+   │ BookFormats              │        │ BookContainers           │
+   │                          │        │                          │
+   │ Register  For            │        │ Register  For            │
+   │ TryOpen  FromExtension   │        │ Open     Sniff           │
+   └─────────────┬────────────┘        └─────────────┬────────────┘
+                 │  the registry of                  │
+   ┌─────────────▼────────────┐        ┌─────────────▼────────────┐
+   │ IBookFormat              │        │ IContainer               │
+   │                          │        │                          │
+   │ Id   Extensions          │        │ Entries  (order kept)    │
+   │ Capabilities             │        │ IsWritable               │
+   │ TryOpen(BookSource)      │        │ OpenRead(entry)          │
+   │ Read(container)          │        │ Rebuild(pending, path)   │
+   │ Write(container, path)   │        │                          │
+   ├──────────────────────────┤        ├──────────────────────────┤
+   │ EpubFormat   .epub       │        │ ZipContainer      ZIP    │
+   │ CbzFormat    .cbz .cbt   │        │ TarContainer      TAR    │
+   │              .cbr .cb7   │        │ RarContainer      RAR *  │
+   │ Fb2Format    .fb2        │        │ SevenZipContainer 7z  *  │
+   │              .fb2.zip    │        │ PalmDbContainer   PalmDB │
+   │ MobiFormat   .mobi .prc  │        │ RawContainer      none   │
+   │              .azw .azw3  │        └─────────────┬────────────┘
+   └──────────────────────────┘                      │  * cannot compress itself
+                                       ┌─────────────▼────────────┐
+                                       │ ExternalArchiver         │
+                                       │                          │
+                                       │ finds and runs the       │
+                                       │ rar.exe / 7z.exe that    │
+                                       │ is on the machine        │
+                                       └──────────────────────────┘
+```
+
+Most of the design falls out of that picture:
+
+- **The two axes are independent.** `ZipContainer` has never heard of EPUB and
+  `EpubFormat` never opens a file. That is why CBZ, CBT, CBR and CB7 are one format
+  class living in four containers, and why adding a container is a file and a
+  `Register` line.
+- **The registries are the only way across.** Nothing above them ever says
+  `new ZipContainer()` — `Book` asks for a `ContainerKind` and gets an `IContainer`.
+- **There is no second path.** `BatchSession` is a list of `Book`s; saving a row of
+  the grid calls `Book.Save`, the same one the single-file window calls. Five hundred
+  files are five hundred independent saves, not a batch write.
+
+### Opening a file
+
+```
+Book.Load("comic.cbz")
+ │
+ ├─▶ BookFormats.TryOpen(path)
+ │    │
+ │    ├─▶ BookSource.Open(path)            the file is opened once; 8 KB is read
+ │    │    └─▶ BookContainers.Sniff(head)
+ │    │         "PK\x03\x04" at offset 0  ─▶  ContainerKind.Zip
+ │    │
+ │    ├─▶ offer that one BookSource to every registered format
+ │    │         EpubFormat  ─▶ null        no mimetype entry
+ │    │         CbzFormat   ─▶ Strong      holds ComicInfo.xml
+ │    │         Fb2Format   ─▶ null        no .fb2 entry
+ │    │         MobiFormat  ─▶ null        not a PalmDB
+ │    │    the strongest MatchConfidence wins, never registration order
+ │    │
+ │    └─▶ source.Container ─▶ BookContainers.Open(path, Zip) ─▶ ZipContainer
+ │             opened on first use and handed to the winner still open
+ │
+ ├─▶ CheckEntryNames(container)            GEN-E003 for a name that escapes
+ │
+ └─▶ CbzFormat.Read(container)
+      └─▶ container.OpenRead("ComicInfo.xml")  ─▶  BookMetadata
+```
+
+**Almost nothing runs here**, which is most of why a cold launch stays under 400 ms.
+A read parses the metadata document and stops: no entry is decompressed to decide what
+a file is, and no page is touched.
+
+### Saving a file
+
+```
+Book.Save()
+ │
+ └─▶ AtomicFileWriter.Write(path, …)      the only sanctioned way a file is replaced
+      │
+      ├ 1  BookContainers.Open(path, Zip)
+      │      reopened inside the callback, so the read handle is shut before the
+      │      swap pulls the file out from under it
+      │
+      ├ 2  CbzFormat.Write(container, metadata, "comic.cbz.tmp")
+      │      │   every correction happens here, never on open:
+      │      │     CBZ-W010  no ComicInfo.xml    ─▶ one is created
+      │      │     CBZ-E011  it sits in a folder ─▶ moved to the root
+      │      │     CBZ-E020  PageCount is wrong  ─▶ recounted from the images
+      │      │
+      │      └─▶ container.Rebuild(PendingEntry[], "comic.cbz.tmp")
+      │             the metadata document is replaced; every other entry is
+      │             copied through byte for byte
+      │
+      └ 3  File.Replace(comic.cbz.tmp ─▶ comic.cbz, backup comic.cbz.bak)
+```
+
+`Read` parses and stops; **`Write` is where every repair lives**. A repair therefore
+cannot reach the disk unless the user saves, which is what makes "the file on disk is
+what you last saved" true by construction rather than by care.
+
+### When the container cannot compress itself
+
+```
+RarContainer.Rebuild(entries, "comic.cbr.tmp")        SevenZipContainer is identical
+ │
+ ├─ no archiver on this machine
+ │    └─▶ CBR-F002 / CB7-F002 — refused, and the user's file is left untouched
+ │
+ └─▶ ExternalArchiver
+      ├─ Stage()  writes every entry under comic.cbr.tmp.stage\
+      │             the one place in Core that extracts to disk, and therefore
+      │             where ".." and duplicate names are refused outright
+      ├─ writes __entries.lst — UTF-16, one relative name per line
+      └─ runs rar.exe / 7z.exe  ─▶  comic.cbr.tmp
+            every way that can fail becomes the same BookIoException
+```
+
 ## Read these six files, in this order
 
 | # | File | Why |
@@ -40,6 +180,11 @@ compress itself — RAR, 7z — supplies an `ExternalArchiver` with the name of
 program to find, the registry keys that record where it installed, and its command
 line, and gets the staging, the list file and the one failure answer for free.
 
+In full, and this is the whole list: the file, a `ContainerKind` member, the
+`Register` line. Nothing else in Core names a container, and nothing switches on
+`ContainerKind` — `ExtensionPointTests` proves it by adding a container and a format
+from the test assembly and opening a file through both.
+
 **A comic archive is smaller still.** `CbzFormat.Flavours` pairs a `FormatId` with a
 `ContainerKind` and an extension; a new row plus the container is the whole change,
 and `BookFormats` does not need editing.