Here’s what a developer building an Origami Text-aware reader needs to implement beyond standard EPUB rendering:
Reading the Origami-specific data
Detect an Origami Text document. Check the manifest in package.opf for a visual-meta.json entry. If present, this is an Origami Text document and the reader can activate enhanced features. If absent, fall back to standard EPUB rendering — every Origami Text document is a valid EPUB, so nothing breaks.
Parse the Visual-Meta. Read visual-meta.json from the package directly rather than parsing it out of the HTML. The standalone file exists precisely so that readers don’t have to scrape the content document. The inline copy in paper.html is a fallback for when someone has extracted the HTML from the package.
High-resolution addressability
Resolve hierarchical anchors. Every addressable element in the document has an id following the hierarchical scheme — 3 for a section heading, 3B for the second element within that section. Your reader should be able to navigate to any anchor by ID, either from an internal link, an external deep link, or a user-entered address.
Expose addresses to the reader. Offer a mode or overlay where the hierarchical addresses become visible alongside the text — in a margin, as a tooltip on hover, or as a toggleable gutter. Readers should be able to see that they are at paragraph 3B the same way they’d see a page number.
Copy with address. When a user selects and copies text, the clipboard payload should include the anchor address of the enclosing element, the selected text, and the document’s bibliographic metadata from the Visual-Meta. This means a paste into a writing tool can automatically generate a citation that points to the specific passage, not just the document.
Accept incoming anchor links. Support a URL scheme or deep link format that includes the document identifier and an anchor — something like origami://[document-id]#3B — so that other documents and tools can link directly to a specific paragraph.
Structured citations
Extract citation data from reference entries. Each bibliography entry in the HTML carries data-bibtex and data-csl-jsonattributes. Your reader should parse these and offer the user actions on them — copy as BibTeX, copy as CSL-JSON, export to a reference manager, or import into the reader’s own library.
Make inline citations interactive. Inline citations are <a> elements linking to the reference section. Beyond the standard jump-to-reference behaviour, an Origami-aware reader can show a popover with the full citation data, offer a one-tap export, or link out to the DOI if one is present in the citation data.
Bulk citation export. The Visual-Meta JSON contains the complete bibliography in structured form. Offer a document-level action to export the entire bibliography as a BibTeX file or CSL-JSON file for import into Zotero, Mendeley, or any reference manager.
Defined Concepts / Glossary
Identify defined terms. Elements with data-concept and data-definition attributes mark terms the author explicitly defined. Your reader should be able to make these visually distinct — a subtle underline, a different colour, or an icon — so the reader knows a definition is available, if that is desired.
Show definitions on interaction. Tap or hover on a defined term to show the author’s definition in a popover. This is distinct from a dictionary lookup — it’s the author’s own definition of the term as used in this document.
Build a glossary view. Collect all defined terms from either the HTML attributes or the Visual-Meta and present them as a browsable glossary panel, each entry linking back to its point of definition in the text.
Spatial layout (for XR-capable readers)
Read spatial views from the Visual-Meta. The JSON contains one or more named layout arrays. Each entry has a refpointing to an element id in the HTML and x, y, z coordinates in metres, right-handed Y-up matching visionOS conventions.
Reconstitute nodes spatially. For each entry in a layout, place a node at the specified coordinates. The node represents the referenced element — it might be a section heading, a glossary term, a citation, or a figure. How the node appears visually (size, shape, typography) is entirely the reader’s decision. The document specifies only position and identity, never appearance.
Support multiple views. If the Visual-Meta contains more than one named layout, let the user switch between them. The author may have provided a default thinking arrangement, a chronological timeline, a citation cluster view, or others.
Allow nodes to be rearranged. The author’s layout is a starting point. A reader should be able to move nodes, and ideally save their own layout as a personal view distinct from the author’s original.
Cross-document connections (future-facing)
Recognise external references. The spatial layout may contain entries whose ref points to an element in a different Origami Text document rather than the current one. These should appear as nodes in the spatial view but be visually distinct — indicating that opening them requires the referenced document.
Resolve cross-document links if the document is available. If the reader has access to the referenced document (in a local library, for instance), opening that node should open the referenced document at the specified anchor. If the document isn’t available, indicate this gracefully rather than failing.
What not to change
Standard EPUB rendering of the HTML and CSS should remain exactly as your reader already handles it. The semantic markup, the nav table of contents, the images — all of this renders through your existing pipeline. The Origami-specific features are additive. A user who never touches the glossary panel, never exports a citation, and never opens a spatial view still gets a clean reading experience identical to any other well-formed EPUB. Every enhanced feature is opt-in from the reader’s perspective.
Graceful handling of partial implementation
Not every reader will implement everything. The features are independent of each other. A reader could support only citation export and addressability without touching spatial layout. A mobile reader might offer glossary popovers and copy-with-address but skip XR features entirely. An XR reader might focus on spatial reconstitution and summon without building a glossary panel. Each feature stands alone because the underlying data — the id attributes, the data- attributes, the Visual-Meta JSON — is always present regardless of which features the reader chooses to surface.