Add the offline HERESY API Calculator and GitHub Pages deployment

.github/workflows/pages.yml

@@ -0,0 +1,41 @@
+name: deploy-pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "web/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload static calculator
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: web
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test.yml

@@ -24,14 +24,14 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.13"
 
-      - name: Validate Time Machine
+      - name: Validate Time Machine and offline calculator
         run: |
           python -m compileall -q heresy.py tests
           python -m unittest discover -s tests -v
@@ -40,3 +40,9 @@ jobs:
           python heresy.py --left 17 --right -3 --style udp --json >/dev/null
           python heresy.py --list-styles >/dev/null
           python heresy.py --old-school-defense >/dev/null
+          node --check web/heresy-core.js
+          node --check web/app.js
+          node --check tests/web_smoke.js
+          node --check tests/app_dom_smoke.js
+          node tests/web_smoke.js
+          node tests/app_dom_smoke.js

README.md

@@ -6,11 +6,62 @@ HERESY-API asks a deeply irresponsible question:
 
 **What if modern API ceremony had to justify itself in a museum beside punch cards, magnetic tape, raw TCP frames, UDP datagrams, batch files, CORBA, SOAP, JSON, GraphQL, and agent tool schemas?**
 
-The answer is the **API Time Machine**.
+The answer now comes in two forms: the Python **API Time Machine** and the browser-based **HERESY API Calculator**.
+
+## HERESY API Calculator
+
+The calculator is a plain HTML/CSS/JavaScript static app under [`web/`](web/).
+
+Open it locally with no server at all:
+
+```text
+web/index.html
+```
+
+Or use the GitHub Pages deployment after PR #3 lands:
+
+```text
+https://qsolkcb.github.io/HERESY-API/
+```
+
+GitHub Pages is only the display case. The exact same files work directly from local disk.
+
+### Calculator contract
+
+- no framework
+- no backend
+- no package install
+- no external API
+- no network dependency
+- no API key required, because Dave would lose it
+- signed 32-bit integer operands
+- add, subtract, multiply, and divide
+- exact fractional display for non-integral division
+- all eleven Time Machine interface styles
+- fake wire representation for the selected era
+- useful bytes, payload bytes, approximate tokens, ceremony bytes, and Ceremony Ratio
+- protocol-specific punchline
+- what the abstraction actually buys
+- honest engineering caveat
+- synthetic 401 authentication tragedy for modern modes
+
+Example conceptual output:
+
+```text
+Mathematics: 4
+Useful intent: ADD 2 2
+Useful bytes: 7
+Interface: Agent Tool Call
+API key status: FOUND IN .env.old.backup.final2
+Authentication status: 401
+Recommended remediation: rewind tape
+```
+
+The app uses only relative local assets. If the internet disappears, it retains enough functionality to continue insulting APIs.
 
 ## API Time Machine
 
-The default experiment remains magnificently difficult:
+The canonical command-line experiment remains magnificently difficult:
 
 ```text
 ADD 2 2
@@ -58,7 +109,7 @@ Produce machine-readable metadata about our joke about machine-readable metadata
 python3 heresy.py --left 10 --right -7 --style graphql --json
 ```
 
-The operands are intentionally restricted to signed 32-bit integers so the binary TCP/UDP exhibits remain deterministic and structurally comparable.
+The Python Time Machine operands are restricted to signed 32-bit integers so the binary TCP/UDP exhibits remain deterministic and structurally comparable.
 
 ## Current timeline
 
@@ -70,31 +121,31 @@ The operands are intentionally restricted to signed 32-bit integers so the binar
 | UDP-style Datagram | 1970s-1980s | The packet can simply leave. No architecture review calendar invite required. |
 | FTP / Batch File | 1970s-1990s | Real-time, if tomorrow morning counts as a latency target. |
 | RPC-ish Invocation | 1980s-1990s | The network is local until packet loss files an objection. |
-| CORBA / IDL Theatre | 1990s | The addition has been referred to the Object Request Broker. |
+| CORBA / IDL Theatre | 1990s | The arithmetic has been referred to the Object Request Broker. |
 | SOAP-ish XML | late 1990s-2000s | The integer has entered the XML cathedral and acquired a namespace. |
 | REST-ish HTTP + JSON | modern web | Human-readable bureaucracy. Dave has lost the API key again. |
 | GraphQL-ish HTTP | modern web | Ask precisely for what you need after introducing yourself to the syntax tree. |
 | Agent Tool Call | current AI stack | Tiny arithmetic escorted by a schema and several responsible adults. |
 
 ## Ceremony Ratio
 
-For any Time Machine request:
+For any exhibit:
 
 ```text
 Ceremony Ratio = application payload bytes / useful semantic intent bytes
 ```
 
-For the canonical `ADD 2 2`, useful intent is seven ASCII bytes.
+For canonical `ADD 2 2`, useful intent is seven ASCII bytes.
 
-The approximate token meter remains deliberately crude:
+The approximate token meter is deliberately crude:
 
 ```text
 estimated tokens = ceil(application payload bytes / 4)
 ```
 
 It is a joke-meter, not a tokenizer, benchmark, protocol-efficiency paper, or invoice predictor.
 
-Network headers, TLS, Ethernet, filesystem overhead, physical-media overhead, server implementation cost, latency, reliability, maintenance, observability, governance, and all the other things capable of ruining a simple chart are intentionally outside this metric.
+Network headers outside the represented application payload, TLS, Ethernet, filesystem overhead, physical-media overhead, server implementation cost, latency, reliability, maintenance, observability, governance, and all the other things capable of ruining a simple chart are intentionally outside this metric.
 
 ## The Heresies
 
@@ -107,6 +158,7 @@ Network headers, TLS, Ethernet, filesystem overhead, physical-media overhead, se
 7. **An old mechanism can be unsuitable for modern production and still make a devastating comparison at a deliberately tiny scale.**
 8. **An API key stored safely is apparently indistinguishable from an API key lost forever.**
 9. **If an abstraction adds bytes, the Time Machine is allowed to ask what those bytes purchased.**
+10. **A calculator that needs the cloud to add two integers has volunteered as an exhibit.**
 
 ## Why the heretics occasionally have a point
 
@@ -138,7 +190,7 @@ For **MOVE THIS FILE OVER THERE**, a durable file can be wonderfully literal: in
 
 The CORBA stop is deliberately **GIOP-ish theatre**, not a byte-accurate packet capture. IDL is normally a build-time interface contract and is not resent on every call.
 
-That caveat is part of the joke's constitution: HERESY-API may exaggerate bureaucracy, but it does not get to falsify where the bureaucracy lives.
+HERESY-API may exaggerate bureaucracy, but it does not get to falsify where the bureaucracy lives.
 
 ## Modern authentication ceremony
 
@@ -171,25 +223,22 @@ For the technically annoying version of the joke:
 python3 heresy.py --old-school-defense
 ```
 
-This prints the narrow cases for TCP, UDP, and batch files together with the bill each one leaves on the table.
-
 ## Project sequence
 
 See [`ROADMAP.md`](ROADMAP.md).
 
 - **PR #1 — Protocol Museum:** foundation, curatorial rules, metrics, and first exhibits.
 - **PR #2 — API Time Machine:** dynamic operands, full historical timeline, filtering, detailed dossiers, engineering value/caveats, UDP, CORBA, and persistent API-key tragedy.
-- **PR #3 — HERESY API CALCULATOR:** offline-first plain HTML/CSS/JavaScript calculator distributed through GitHub Pages, with no backend and therefore no API key for Dave to lose.
-
-GitHub Pages will be the display case, not a runtime dependency.
+- **PR #3 — HERESY API Calculator:** offline-first HTML/CSS/JavaScript calculator, with GitHub Pages as a static distribution surface only.
 
 ## Run the tests
 
 ```bash
 python3 -m unittest discover -s tests -v
+node tests/web_smoke.js
 ```
 
-No runtime dependencies are required.
+No runtime dependencies are required by the project itself.
 
 ## Important lack of seriousness
 

ROADMAP.md

@@ -10,9 +10,9 @@ Established the dependency-free museum, canonical `ADD 2 2` experiment, Ceremony
 
 ## PR #2 — API TIME MACHINE
 
-**Status:** implemented by PR #2.
+**Status:** implemented and merged.
 
-Turn the protocol museum into a dynamic historical comparison engine for the same tiny semantic intent.
+Turned the protocol museum into a dynamic historical comparison engine for the same tiny semantic intent.
 
 ### Delivered contract
 
@@ -34,77 +34,50 @@ Turn the protocol museum into a dynamic historical comparison engine for the sam
 - detailed curatorial dossier view
 - deterministic JSON output
 
-Every exhibit reports:
-
-- useful semantic intent
-- useful bytes
-- application payload bytes
-- ceremony bytes relative to useful intent
-- deliberately crude approximate token count
-- Ceremony Ratio
-- protocol-specific punchline
-- what the extra ceremony buys
-- honest engineering caveat
-- authentication status where applicable
-
-### Running gag
-
-Modern authenticated modes retain the API-key lifecycle:
-
-```text
-provision -> store safely -> forget where -> search .env variants -> find somewhere unsafe -> rotate -> 401 -> consider magnetic tape
-```
+Every exhibit reports useful semantics, payload metrics, approximate token ceremony, Ceremony Ratio, a punchline, the value purchased by the abstraction, an engineering caveat, and authentication status where applicable.
 
 ## PR #3 — HERESY API CALCULATOR
 
-**Status:** next.
+**Status:** implemented by PR #3.
 
-Build an offline-first HTML/CSS/JavaScript joke calculator and publish the same static app through GitHub Pages.
+Build an offline-first HTML/CSS/JavaScript joke calculator and publish the exact same static app through GitHub Pages.
 
-### Hard requirements
+### Delivered contract
 
-- plain HTML, CSS, and JavaScript
+- plain HTML, CSS, and JavaScript under `web/`
 - no runtime framework
 - no backend
-- no external API dependency
-- no API key required, because Dave would lose it
-- works when opened directly from local disk
-- works when served through GitHub Pages
-- deterministic calculations
+- no package installation
+- no external API or network dependency
+- no API key required to run the calculator, because Dave would lose it
+- opens directly from `web/index.html` on local disk
+- deploys the same `web/` directory through GitHub Pages
+- deterministic signed-int32 operands
+- four basic operations: add, subtract, multiply, and divide
+- exact fractional display for non-integral division results
+- all eleven API Time Machine interface styles
+- fake wire representation for the selected style
+- useful bytes, payload bytes, approximate tokens, ceremony bytes, and Ceremony Ratio
+- protocol-specific punchline, engineering value, and caveat
+- synthetic lost-key / 401 gag for REST, GraphQL, and agent-tool modes
 - responsive desktop/mobile layout
+- executable JavaScript core regressions plus offline/static CI checks
 
-### Joke interaction
-
-The user enters a tiny arithmetic operation, for example `2 + 2`, then selects an unnecessarily elaborate interface style.
-
-The calculator shows:
-
-1. the actual mathematical answer
-2. the useful semantic request
-3. the fake wire representation for the chosen era/style
-4. payload bytes
-5. approximate token ceremony
-6. Ceremony Ratio
-7. an era-specific punchline
-8. a modern-authentication failure gag where appropriate
+### Running gag
 
-Example outcome:
+Modern authenticated modes retain the lifecycle:
 
 ```text
-Mathematics: 4
-Useful intent: ADD 2 2
-Useful bytes: 7
-Enterprise ceremony: 487
-API key status: FOUND IN .env.old.backup.final2
-Authentication status: 401
-Recommended remediation: rewind tape
+provision -> store safely -> forget where -> search .env variants -> find somewhere unsafe -> rotate -> 401 -> consider magnetic tape
 ```
 
-### GitHub Pages
+The calculator itself needs no credential. The fake modern API exhibits are the only things irresponsible enough to entrust Dave with one.
+
+### GitHub Pages invariant
 
-The Pages deployment should publish exactly the static offline-capable application. GitHub Pages is a distribution surface, not a runtime dependency.
+GitHub Pages publishes exactly `web/` as a static artifact. It is a distribution surface, not a runtime dependency.
 
-If the internet disappears after loading the repository, the calculator should still be able to insult APIs locally.
+If the internet disappears, opening `web/index.html` locally must still provide the same arithmetic, protocol payloads, metrics, and jokes.
 
 ## Later gallery wings