Export template source from be30143a326d5d7d7b0cbabea5bc5ac0301ef5b9:examples/local-first/packages/gutenberg-runtime

2000-01-01 00:00:00 +00:00
commit da97d4b35c
13 changed files with 624 additions and 0 deletions
@@ -0,0 +1,48 @@
+# Project Gutenberg source for Reader
+
+Updated September 30, 2026. The catalog is an ordinary Camino entity with
+`search` and `readBook` remote operations. It has an independent Studio
+presentation and an embeddable `GutenbergPicker`. Reader's document-author
+adapter imports the chosen excerpt through the existing durable publication
+connection; completion navigates the bookshelf to the new document. Manual
+text authoring keeps its own independent state.
+
+## Catalog and downloads
+
+`flake.nix` pins Gutenberg's compressed machine-readable CSV by SHA-256.
+The build parses text editions and bundles the index into the service. Fuzzy
+search over titles/authors reads that index without contacting Gutenberg.
+Update the CSV hash deliberately and repin workspace resources when refreshing
+it. A changed upstream catalog cannot silently change an existing build.
+
+Book text is requested when a user opens a result, from the
+[listed generated-files mirror](https://www.gutenberg.org/dirs/MIRRORS.ALL)
+`gutenberg.pglaf.org`, following the
+[robot access policy](https://www.gutenberg.org/policy/robot_access.html).
+The downloader reads only far enough to collect about 1,000 words, ending at
+the next complete paragraph, then cancels the remaining response body. Gutenberg
+header/footer markers are removed. Short books end at EOF. Exceptionally long
+paragraphs are bounded at 56,000 characters, preferring a word boundary and
+preserving Unicode surrogate pairs.
+
+`readBook({ebook})` returns `{book, url, text, words}` in one response. The picker
+shows a preview and an **Import excerpt** button; the standalone catalog offers
+**Copy excerpt**. There is no paragraph pagination or selection step.
+
+Downloads are serialized, start at least two seconds apart, and coalesce requests
+for the same book. The process caches eight excerpts, bounded by 32 MiB. The UI
+also keeps eight excerpts while mounted, so going back to a book needs no new
+remote call. The first request still needs the mirror to respond. Downloads have
+a 20-second timeout and 12 MiB maximum; missing editions and failures can be
+retried. Search never downloads books.
+
+## Verification
+
+```sh
+node --test examples/local-first/packages/gutenberg-runtime/test/catalog.test.mjs
+nix run .#camino-presentation-qualification
+```
+
+Unit tests cover paragraph/Unicode boundaries, truncated streams, stopping and
+cancelling a download, coalescing, caching, serialization and retries. Browser
+checks search the actual pinned index and stub only the external book response.