Personal Edition Suite (PES) — Master Spec

Round: R56 · Status: PLAN (approved-for-build planning round; product code untouched this round) · Owner standard: zero bugs Scope: Composed Text View (CTV) · Study Bible View (SBV) · Print myGNT (PM) — the #1 ranked product gap and #1 opportunity from download/COMPETITOR-ANALYSIS-BIBLEMAKER-R55.md. Zero-fabrication: every number below is frozen ground truth from the shipped corpus (data/manifest.json, R54-verified) or the real record shape in src/services/mygnt/mygntDecisions.ts. Nothing is invented; open items are marked OPEN. Enhancement loop: this spec is maintained by a scheduled 15-minute QA agent (§13). It edits ONLY this file (by section ID) and keeps the default page in sync.

0. How to read this spec

Normative language (RFC-2119): MUST / MUST NOT / SHOULD / MAY.

Granularity ladder — every requirement lives at exactly one level:

ID scheme: CTV-nn behaviors · SBV-nn · PM-nn · X-nn cross-cutting · E-<view>-nn edge cases · D-nn decisions-still-OPEN. The QA agent references these IDs surgically in §14 changelog entries.

Priority: P0 = block for release · P1 = release quality · P2 = post-release polish.

1. Thesis and the four firsts

Positioning sentence (from R55): "Every Greek NT tool shows you an edition. Bible Maker is the first workbench that lets you build one — decide all 11,644 variant points, record why, and keep a documented, exportable, auditable edition of your own."

PES turns that thesis into three surfaces:

1. CTV — Composed Text View: read YOUR edition as continuous Greek text (not a decision ledger — the resulting text).
2. SBV — Study Bible View: your edition wrapped in your personal apparatus — every note is your unit decision + reasoning.
3. PM — Print myGNT: a printed/PDF critical edition of your own with personal apparatus and a reasons appendix.

The four firsts (unique in the market per R55 census):

2. Ground truth (frozen numbers this spec is built on)

Real reading-value vocabulary (must be honored by every consumer): "Ἰησοῦν" (surface) · "(omit)" · "@order:»3" (word-order move) · "include"|"omit"|"undecided" (passage only).

3. Domain core: the Composed Edition (CE)

3.1 Deterministic resolver

CE(word w, verse v):
  P = passage(v) exists AND passageDecision(P) == "omit"  → render omitted-passage treatment, stop
  u = unitAt(w, v)                       # 0 or 1 unit anchors a word position
  r = decision(u)  if decision(u).attended        # user decided
      else editionDefault(u)             # 9-edition edition-following default (R50)
      else baseFallback(u)               # SRGNT stream value
  apply r:
    substitution  → surface = r
    "(omit)"      → render ghost-dash (L4), text excluded from continuous string
    "@order:»k"   → word placed at rank k in the verse sequence
    no unit       → surface = base stream word

Precedence table (L2, normative):

Invariant: exactly ONE decision record per vuKey — enforced today by id = ${book}:${vuKey} primary key. Two tabs writing concurrently: last-write-wins on updatedAt; CE hash recomputed after each write (see E-CTV-12).

3.2 CE revision & hash (reproducibility — first F-3)

• CE.rev — monotonic integer, +1 on every decision mutation batch (not per keystroke; per commit of the decision dialog).
• CE.hash — sha256(canonical(decisionSet)) where canonical = records sorted by vuKey, fields {vuKey, reading, edition, attended} JSON-serialized, newline-joined, UTF-8. MUST be stable across browser sessions and machines.
• Colophon (§6.5) embeds CE.hash + CE.rev + base default edition + decision counts → a printed edition is byte-reproducible from the ledger.
• Staleness: if Phase-A modelHash ≠ 51d49df3, views MUST show a "pipeline changed — re-derive" banner and MUST NOT silently render (integrity posture inherited from /method).

3.3 Bracketed passages & witness-only verses policy

• The 5 passages: per-passage include|omit|undecided decisions already persist via vuKey "passage:{id}" (5-b layer, shipped). CE renders them per decision; undecided renders the NA28 default treatment (bracketed, grey — current behavior).
• 44 witness-only verses: NEVER in CE main text (they are additions-layer evidence, not edition text). MAY appear in SBV as collapsible "witness-only" cards and MAY appear in PM as an optional appendix toggle X-07.

3.4 What CE is NOT (claims boundary — extends the claims dialog)

• CE is NOT the autograph, NOT NA28-equivalent, NOT exhaustive (only 11,644 of all conceivable points), NOT a theological authority. Printed colophon MUST carry the abridged MAY/MUST-NOT block (§6.5). D-02 CLOSED: claims dialog copy is normative for the colophon, single source in one TS constant shared by dialog and print stylesheet generation.

4. F1 — Composed Text View (CTV)

4.1 User story

As the editor of my own Greek NT, I open Mark and read continuous text that already reflects my 1,207 decisions — not a grid, not a ledger. Words I changed feel like my words; I can tap any word to see what I decided and why. I can flip to compare against NA28 in one keystroke.

4.2 Wireframes

Desktop ≥1280 (M1 paragraph mode):

┌────────────────────────────────────────────────────────────────────────────┐
│ ◀ Mark ▸ ch.1        [M1|M2|M3|M4]  vs:NA28▾   ◉ 1,207/11,644   ⎙ Print    │  header 56px
├──────────┬─────────────────────────────────────────────────────┬──────────┤
│ density  │  1 Ἀρχὴ τοῦ εὐαγγελίου Ἰησοῦ Χριστοῦ [υἱοῦ θεοῦ].   │ word     │
│ ribbon   │  2 καθὼς γέγραπται ἐν τοῖς προφήταις·               │ popover  │
│ (verse   │    …              (text pane, max 62ch measure)      │ (on tap) │
│  heat    │  8 … κηρύσσων βάπτισμα μετανοίας …                   │          │
│  strip)  │  ────────────────────────────────────────────────    │ lexicon  │
│ 44px     │  ‸ markers row: ◉3 ◉8 ◉12 … jump-to-unit            │ TBESG/LSJ│
├──────────┴─────────────────────────────────────────────────────┴──────────┤
│ status bar: CE rev 412 · hash c3f9… · base SRGNT · 96% covered · ⎙         │
└────────────────────────────────────────────────────────────────────────────┘

Mobile ≤390: header collapses to [☰][Mark 1][◉12%][⎙]; ribbon hidden (dots row instead); popover becomes bottom sheet (max-h-[70dvh], overflow-y-auto).

4.3 Reading modes

Mode is per-book sticky (localStorage pes.ctv.mode.{book}); switching book keeps mode.

4.4 Visual grammar of marks (normative — same grammar in print, F-4)

4.5 Word popover anatomy (tap any word)

┌──────────────────────────────────────┐
│ λόγος  ·  G3056 · noun, masc sg nom  │  TBESG gloss (9,362 entries)
│ LSJ: (senses 1–3, collapsed)         │  LSJ/TFLSJ 9,361 — expandable
├──────────────────────────────────────┤
│ UNIT u#4812 · substitution           │  if word anchors a unit
│ base: λόγος   default(NA28): λόγος   │
│ YOURS: ἔργον  ● decided 12 Jan 2026  │  or "default in effect — decide?"
│ reason: "Byz A C D read ἔργον;       │
│          ὁ λόγος is editorial smooth"│
│ [Edit decision] [Witnesses (14)]     │  deep-links back to Bible Maker
├──────────────────────────────────────┤
│ (word not in any unit → lexicon only)│
└──────────────────────────────────────┘

4.6 State machine (view level)

        ┌─────────┐  select book/ch   ┌─────────┐  shards ready  ┌────────┐
boot ──▶│ LOADING │──────────────────▶│ READY   │───────────────▶│ READING│
        └─────────┘                   └─────────┘                └───┬────┘
             │ stale modelHash            │ 0 decisions               │ tap word
             ▼                            ▼                           ▼
        ┌─────────┐                   ┌──────────┐              ┌──────────┐
        │ BLOCKED │                   │ EMPTY-CE │──decide─────▶│ POPOVER  │
        │ banner  │                   │ banner   │              └────┬─────┘
        └─────────┘                   └──────────┘                   │ edit
                                          ▲                          ▼
                     CE.rev++ / hash recompute ← decision saved ──┘ (all views re-derive)

Transitions: LOADING→READY only when chapter shard + decisions slice both resolve; any fetch failure → ERROR state with retry (no infinite spinner — zero-bug rule).

4.7 Completeness meter

coverage = decided / 11,649 where decided = records with attended:true (units + 5 passages, counting passage:"undecided" as NOT decided). Header shows book-scope meter; status bar shows global. Per-book breakdown table lives on SBV settings sheet. Meter MUST be aria-live="polite" (X-09).

4.8 Behavior register

4.9 Edge cases

5. F2 — Study Bible View (SBV)

5.1 User story

As the editor, I study Mark 1 with my edition open beside MY apparatus: every note is numbered exactly as it will print, each carrying my chosen reading, my witnesses, my reasoning, and my confidence. I filter to "only my deviations" to rehearse my defense of the text.

5.2 Wireframes

Desktop three-pane:

┌──────────────┬───────────────────────────────┬───────────────────────────┐
│ TEXT (CTV M2)│ APPARATUS (verse-scoped)      │ REASONS                   │
│              │ Mrk 1:2 · 3 units             │ note b card:              │
│ 1 Ἀρχὴ…[a]   │ a  ἐν τοῖς προφήταις — add    │ ┌───────────────────────┐ │
│ 2 …[b][c]    │    ἐν Ἠσαΐᾳ (NA28) vs TR Ἠσαΐᾳ│ │ b · substitution      │ │
│ 3 …          │ b  τοῖς προφήταις ⋯ variants  │ │ chosen: Ἠσαΐᾳ         │ │
│              │ c  …                          │ │ wits: TR, Byz, A C …  │ │
│ (sync scroll │ (unit rows, R35 dash+panel    │ │ reason: …             │ │
│  to focused  │  anatomy reused verbatim)     │ │ confidence ●●○ revise │ │
│  verse)      │ [only-mine ▾][type ▾][kind ▾] │ │ ⚠ anti-fallacy #4:    │ │
│              │                               │ │ "don't count mss,     │ │
│              │                               │ │  weigh them" reminder │ │
│              │                               │ └───────────────────────┘ │
└──────────────┴───────────────────────────────┴───────────────────────────┘
Mobile: tabs [Text|Apparatus|Reasons]; note tap on Text → Apparatus tab scrolled to unit.

5.3 Personal apparatus note grammar

A NOTE = the print-facing projection of one unit decision:

note := marker + unit-ref + kind + chosen-reading + [against-default] + [witnesses] + [reason ≤280ch] + [confidence]

• marker: a, b, c … z, aa, bb … per verse, ordered by unit index within the verse (deterministic; NEVER alphabetical-by-content).
• kind: substitution · addition · omission · word-order (from unit type + reading value).
• Verse header line: Mrk 1:2 · 3 units · 2 decided · witnesses cited: 14.

5.4 Note-numbering parity contract (first F-2 — NORMATIVE)

1. SBV marker sequence for verse v == PM footnote marker sequence for verse v == marker order in the reasons appendix (§6.6), all derived from ONE function numberNotes(v) in shared lib.
2. Test gate: for every verse with units, the three renderings produce identical marker arrays (property test over all 4,720 verses; gate runs in QA script, MUST PASS before any PES release).

5.5 Filters & study presets

• Filter axes: only-my-deviations · kind (sub/add/omit/order) · decided-vs-default · confidence · has-reason.
• Preset = named combination persisted in D1 (pesPresets), max 24 presets; sharing a preset exports JSON (X-06).

5.6 Reason cards & anti-fallacy hooks

• Reason card fields: chosen reading, base default, witness citation list (from 42,482-pair table), reasoning text, confidence (none/low/med/high), timestamp.
• The 12-item anti-fallacy catalogue (shipped) surfaces contextually: e.g. a decision citing >6 witnesses with no internal-consistency note shows the relevant catalogue reminder — NEVER blocks, only reminds (guarded-inference posture).

5.7 Behavior register

5.8 Edge cases

6. F3 — Print myGNT (PM)

6.1 User story

As the editor, I press ⎙ and receive a typeset critical edition of MY text: continuous Greek with superscript markers, my apparatus as footnotes, my reasons as an appendix, and a colophon that hashes the whole thing — a real book of my own scholarship.

6.2 Product kinds

6.3 Page geometry & typography

6.4 Footnote engine (normative)

6.5 Colophon (every kind except K2)

Fields (fixed order): edition name (E-CTV-11 rules) · editor · date (ISO) · base-default declaration · CE rev + hash (§3.2) · Phase-A model hash · counts (decided/defaults per kind: sub/add/omit/order/passages) · license lines: "Greek base stream and apparatus data © contributors, CC BY; TBESG/LSJ gloss data per PROVENANCE §3; no restricted text served (qa15 L3)" · abridged MAY/MUST-NOT claims block (D-02) · /method URL citation.

6.6 Reasons appendix (K4)

Table per book: verse · marker · kind · chosen · against(default) · witnesses (n) · reason (wrapped) · confidence. Row keep-together; a reason >280ch splits at sentence with "(cont.)" — never mid-word.

6.7 Render path

1. v1 (this suite): browser print — dedicated print route renders print-DOM; @media print hides app chrome; user "Save as PDF". Zero new server deps; deterministic via embedded fonts.
2. v2 (explicitly DEFERRED, not in P0–P5): server-side PDF (typst/puppeteer on Workers is out of scope; will be its own round).

6.8 Keep-together decision table

6.9 Behavior register

6.10 Edge cases

7. Cross-cutting

8. Data contracts

// CE manifest (derived; produced by resolver, consumed by CTV/SBV/PM)
{
  "ceRev": 412,
  "ceHash": "c3f9…64",            // §3.2 canonical hash
  "baseDefault": "SRGNT",
  "modelHash": "51d49df3",        // staleness guard (X-08)
  "counts": { "decided": 1207, "defaults": 10437, "passagesDecided": 3, "passagesUndecided": 2 },
  "perKind": { "substitution": 511, "add_omit": 566, "wordOrder": 130 }
}

// resolution record (per rendered unit; internal)
{ "vuKey": "Mrk.1.2:4", "kind": "add_omit", "chosen": "Ἠσαΐᾳ", "source": "decision|default|fallback", "note": 2 }

// print spec (input to print route)
{ "kind": "K1", "book": "mrk", "duplex": false, "pageSize": "A4", "bodySize": "M",
  "includeWitnessOnlyAppendix": false, "ceRev": 412, "ceHash": "c3f9…64" }

// note record (parity function output)
{ "verse": "Mrk.1.2", "marker": "b", "unitIndex": 4, "kind": "substitution",
  "chosen": "Ἠσαΐᾳ", "againstDefault": "ἐν Ἠσαΐᾳ", "witnesses": ["TR","Byz","A","C"],
  "reason": "…≤280…", "confidence": "med" }

9. End-to-end flows

FLOW A — decide → everywhere
  Bible Maker grid ──save──▶ MygntDecision(D1) ──▶ CE.rev++ / hash
        │                                        │
        ▼                                        ▼
  CTV text re-render (shard slice)         SBV notes renumber (verse-local, E-SBV-10)
                                                 │
                                                 ▼
                                     PM preview invalidated (hash changed)

FLOW B — print session
  ⎙ on CTV/SBV ──▶ print route (kind, book, options) ──▶ resolver → numberNotes() parity
      → paginate → preview (pages + count) ──▶ window.print() ──▶ PDF/paper + colophon hash

FLOW C — share
  Export CE ledger JSON ──▶ (other device) import validate §8 ──▶ same CE.hash ⇒ same book

10. Test matrix & QA gates

• Matrix: {CTV, SBV, PM} × modes × {en,id} × {1440, 768, 390} × {light,dark} × CE states {empty, minimal, mixed, full-book} × kinds K1–K4.
• Property gates: parity test §5.4 over 4,720 verses; page-break audit PM-21; i18n key parity X-01; contrast X-02.
• Round gates (every code round): lint clean · tsc delta 0 vs 106 baseline · Phase-A --check PASS (X-08) · qa18 197/197 · browser pass 1440+390 zero console errors · ERRATUM stays at zero NEW findings (zero-bug standard).

11. Rollout

12. Risks

13. Continuous enhancement loop (scheduled QA agent, every 15 min)

Axes (each run must name the axis it served): robustness (new edge cases / tightening) · advancement (one-of-a-kind mechanisms) · effectiveness (does each behavior serve the editor's goal) · efficiency (steps, latency, tokens of effort) · uniqueness (moat deepening vs R55 census).

Rules: R1 Iron Rule git fetch && git reset --hard origin/main first · R2 edit ONLY download/PERSONAL-EDITION-SUITE-SPEC-R56.md (by section/ID) — product code untouched except page-sync fixes · R3 add a §14 changelog line per run (date · axis · IDs touched · delta) · R4 surgical edits, never wholesale rewrites · R5 commit ONLY on substantive delta (max 1 commit/run) + CANARY + tar; otherwise no-op report · R6 report EN/ID · R7 zero-bug standard applies to the spec page itself (lint + render check).

14. Spec changelog

15. Sources (repo pointers)

data/manifest.json · src/services/mygnt/mygntDecisions.ts · src/lib/na-brackets.ts · src/islands/views/BibleMakerView.tsx · scripts/qa12-external-review-scope.ts · scripts/qa13-phase-a-reconciliation.ts · ERRATUM.md · download/COMPETITOR-ANALYSIS-BIBLEMAKER-R55.md · src/pages/method.astro.