# Markdown Reading Room — development handoff

Status: local-file-only removal implemented, verified, and published in PR #20.
Current decision: Jim withdrew hosted Ballad snapshot publication on 2026-10-06.
The previous 2026-09-20 approval below is historical and no longer authorizes it.

## Resume here

Read [PRIVACY_CHANGE.md](PRIVACY_CHANGE.md) and [README.md](README.md).
The proposed tree removes all 52 Ballad documents, `data/catalog.json`, and the
snapshot publication tools. The reader opens local files only, without uploads,
fetches, repository lookups, or a collection initialization step. Other tools and
canonical Ballad source remain unchanged.

Review: [PR #20](https://github.com/SongOfHumanity/SoH_Webtools/pull/20), branch
`agent/reading-room-local-only`. Jim reviews/merges under the established workflow.
Production keeps serving the old snapshot until the removal has deployed. Check
direct file URLs after merge, not only the viewer UI.

Historical deployments are a separate unresolved exposure: Vercel's connector
lists `so-h-webtools`, but project/deployment reads return a team-scope 403, and
there is no CLI fallback installed. No old deployment was deleted or protected.
Jim can retire/protect these in the dashboard, or restore correctly scoped access.
Do not roll back to a snapshot-bearing build. Git history stays in the private
repository; already-fetched copies cannot be recalled by this change.

## Current validation

`npm test --prefix Web/markdown/tools` checks synthetic local Markdown and the
actual app module: zero fetches, superscript/HTML safety, MathML, tables, heading
links, exact source and download contents, theme, responsive sidebar/focus,
selection races, failed/oversized reads, and memory-only behaviour after reload.
It also checks that snapshot/catalogue/publication paths are absent locally.
JavaScript syntax checks pass. Publication checks confirmed all 56 deleted paths are absent in the remote tree
(52 documents plus catalogue and three publication files), and all 185 unaffected
blob hashes match main.
No rendered-browser or live-production deletion check is claimed.

## Current invariants

- Selected document content stays in tab memory, not storage or network requests.
- Theme/sidebar preferences may use localStorage; no document text is saved there.
- Relative file links remain text; explicit web/email links require user clicks.
- No source refresh or publication script remains. New collection hosting requires
  a new explicit decision; old activity records cannot authorize republication.
- `PLAN.md` is preserved as historical context and clearly marked superseded.

## Standing development constraint

JMC requires a written, accessible plan for development and continuing notes so
another Entity can pick up the work. Record a new step or scope change before
implementing it. Report progress during active work. Keep actual results distinct
from intentions, and retain a bounded next task after each activity.

## Historical decisions — snapshot model superseded on 2026-10-06

- This is a reading space. Editing remains in the source workflow.
- Ballad's private visibility prevents anonymous browser loading. A deliberately
  published Markdown snapshot satisfies the requested deployment/share workflow.
- The first snapshot contains 52 files: root README plus `_Docs/**/*.md` present
  at source revision `0fa72683658ea8999a3b4591d3812003e8756fc6`.
- `tools/sources.json` freezes that selection. Future source additions do not
  silently enter the deployment. No repository credentials are shipped.
- Source bytes and intentional header naming are preserved. The catalogue carries
  Git blob and SHA-256 hashes. Snapshot date and revision are visible in the UI.
- Renderer dependencies are local and pinned. KaTeX outputs native MathML, avoiding
  a font/CDN dependency. DOMPurify sanitizes generated HTML and MathML.
- Paired, attribute-free `<sup>…</sup>` spans render inline (Markdown links work
  inside them). Other raw HTML stays inert; source comments are accessible in Source text. Mermaid
  stays readable code. Unbundled assets link to the original repository.
- Document state lives in URL query/hash; theme and explicit sidebar visibility use optional localStorage.
  Local-file text stays in memory and cannot be shared by URL.
- Document loads use cancellation and sequence checks. Heading DOM IDs have a
  prefix to avoid collisions with viewer controls, while public anchors use
  GitHub-style slugs.

## Historical work completed

- [x] Write and commit the plan before implementation.
- [x] Inspect sources and verify all 52 exported files against Git blob hashes.
- [x] Implement repeatable refresh with explicit file selection and staged output.
- [x] Implement search, collections, outline, deep links, source view, downloads,
  local file reading, theme, and responsive styles.
- [x] Implement sanitized Markdown, math, safe relative links, and inert HTML.
- [x] Add Library navigation and Reading Room changelog registration.
- [x] Run syntax, exact-source, renderer/DOM interaction, and exporter checks.
- [ ] Complete rendered desktop/mobile and iframe visual review.

## Historical validation and limitations

`tools/check.mjs` verifies original file hashes and renders all 52 documents. It
also exercises math, tables, checklists, heading collisions, hostile links/HTML,
relative and same-repository links, search and empty states, source switching,
rapid navigation/cancellation, missing documents, fetch failure/retry, theme, and
clipboard fallback against the actual application module.

`tools/check-sync.mjs` verifies that a refresh reads committed content, excludes
unlisted files, removes stale output, repeats deterministically for the same
revision/date, and leaves the previous snapshot intact after a missing-source
failure. JavaScript syntax checks pass for the authored runtime and exporter.

The available Playwright browser download failed; an alternate local Chromium
also failed to launch in this environment. No rendered-browser pass or screenshot
is claimed. DOM tests do not establish visual quality, actual clipboard/download
behaviour, or MathML layout on readers' devices.

## Historical future work — requires a new plan

Visual review first. Later possibilities: text search across documents, selected
binary/image snapshots, diagram rendering, print refinements, or an additional
source collection. Each needs an explicit plan and publication scope. Do not
reintroduce runtime access to private GitHub with a client-side token.

## Activity log

### 2026-10-06 — Remove hosted Ballad docs at Jim's request

- Wrote `PRIVACY_CHANGE.md` before implementation and refreshed current main.
- Deleted the 52-document snapshot, catalogue, refresh script, selection manifest,
  and exporter test. No copies were moved to another Webtools directory.
- Removed runtime library loads, collection controls, repository routes, and
  shareable snapshot links. Old document URLs give a removal notice.
- Preserved local input, sanitized rendering, superscripts, MathML, tables, outline,
  exact source/download, theme, and the portrait/sidebar behaviour Jim reviewed.
- Added a noindex page hint and CSP that blocks fetch/upload and image connections.
- Replaced source-dependent tests with synthetic local-file/privacy checks.
- Updated READMEs, dashboard navigation, changelog, and current handoff.
- Vercel history cleanup is blocked by team-scope 403; no hosting mutation made.
- Published ready-for-review PR #20; source removal needs merge/deployment before
  it affects the production alias.


### 2026-09-24 — Reading width and sidebar, JMC [0031]

- Added a sticky, keyboard-accessible Hide/Show sidebar control with expanded state.
- Portrait/narrow viewports start with the library closed; explicit choices persist
  and take priority over later orientation changes. Filters and selection survive.
- An open desktop library remains available while the document scrolls. Portrait
  viewports place the outline above the article. Wide tables scroll within their
  existing focusable container instead of splitting words into fragments.
- Returning focus to the toggle prevents focus being trapped in a hidden sidebar;
  the visible article block anchors reflow during manual toggles.
- Syntax and all 52-document hash/DOM/application checks pass, including new
  visibility, responsive-default, preference, focus, and filter-preservation cases.
- Plan written before implementation; continuing in PR #11 as requested.
- Vercel deployed the revision successfully. The cloud browser reached Vercel
  sign-in instead of the protected preview, so no rendered pass is claimed.
- At phone widths the open library is a bounded panel below the sticky control,
  so Show sidebar remains useful even when deep in a document.


### 2026-09-23 — Superscript citation support, JMC [0029]

- Preserved existing Ballad citation notation and all original source bytes.
- Added a narrow paired `<sup>` inline extension; attributes and nested raw HTML
  remain unsupported. Code examples and escaped tags remain literal.
- Verified numeric lists/ranges, adjacent and standalone spans, citation links,
  malformed/attributed markup, unsafe links, and real conceptPrimer citations.
- Existing DOM/application checks pass across all 52 hash-verified documents.
- This is DOM-level validation; new rendered preview inspection is still pending.


### 2026-09-20 — Approved snapshot and collection organization ([0028])

- [Authorized][Publication] JMC explicitly approved publishing the complete staged
  52-document Ballad snapshot for deployment visitors, including fantasy primers.
  This resolves the automatic review gate encountered in the preceding activity.
- [Organized][Library] Core Collection contains 41 Markdown documents across the
  five requested directories plus the repository overview. Fantasy Primers is a
  separate 11-document collection. Directory filtering remains available within
  collections and resets incompatible selections when the collection changes.
- [Preserved][Sources] Source revision and all 52 original file hashes are unchanged.
  The xmSpec entry is its Markdown index; XML and binary assets remain unbundled.
- [Reviewed][Human] Jim reports the live reader looks clean and that reading local
  documents, downloading duplicates, and changing theme worked. This is human
  feedback on the preview, not a claimed automated or mobile visual QA pass.
- [Planned][Handoff] PR #9 is merged. Publish this approved collection update through
  a follow-up PR with source/filter checks and a new Vercel preview.

### 2026-09-19 — Recover and publish implementation ([0026]–[0027])

- [Recovered][Continuity] All 81 prepared files survived the workspace disconnect.
  Rechecked the local implementation and snapshot refresh successfully.
- [Confirmed][Repository] PR #8 merged the original plan only. The recovery branch
  contained the plan and temporary handoff, without the implementation.
- [Planned][Publication] Publish the recovered files in bounded Git object batches,
  verify their remote hashes, and open a fresh implementation PR against current
  main. This replaces the temporary recovery handoff with the development record.
- [Pending][Review] Inspect the Vercel preview visually; the documented rendered
  browser limitation remains unchanged.

### 2026-09-19 — Reading Room v0.1

- [Planned][Continuity] Committed the implementation plan before building.
- [Added][Reader] Implemented the document browser and dated Ballad snapshot.
- [Added][Maintenance] Added source manifest, hashes, refresh tool, tests, and
  local dependency provenance/licenses.
- [Integrated][Navigation] Added the reader to the Webtools Library and changelog.
- [Verified][Functional] Exact source and DOM interaction checks passed; rendered
  visual review is explicitly outstanding.

Reflection: private repository access shaped the delivery model. Keeping a
versioned, deliberate reading copy makes visitor access predictable and keeps
source editing separate from comfortable reading.

Preview build: [Reading Room](https://so-h-webtools-git-agent-reading-58a570-songofhumanitys-projects.vercel.app/Web/markdown/index.html). GitHub's
Vercel status reports success for the implementation commit. This is deployment
status, not a rendered-browser check or proof of production/history cleanup.