ZDDC/bootstrap/README.md

Deployment bootstrap

ZDDC tools (archive, transmittal, classifier, mdedit, landing) are single-file HTML bundles. The bootstrap pattern lets you install once on a deployment and update by editing a few lines, without re-uploading multi-megabyte HTML files.

The two-level model

A typical zddc-server deployment looks like this:

<ZDDC_ROOT>/
  index.html                # landing tool (or bootstrap)
  archive.html              # archive tool (or bootstrap; site-wide channel switch lives here)
  transmittal.html
  classifier.html
  mdedit.html
  <project-A>/
    archive.html            # level-1 bootstrap → fetches ../archive.html
    transmittal.html
    classifier.html
    mdedit.html
    <project files…>
  <project-B>/
    archive.html            # level-1 bootstrap (or pinned to a specific version)
    …

• Level-1 stubs at <project>/<tool>.html always fetch the same-origin ../<tool>.html. They never touch zddc.varasys.io. Install them once; they don't need to change.
• At deployment root (<ZDDC_ROOT>/<tool>.html), put either:
  • the actual built tool HTML — fully self-contained install, no external dependencies; or
  • a level-2 bootstrap — fetches a specific channel or pinned version from https://zddc.varasys.io/releases/<tool>_<channel|v…>.html.

The site administrator switches the whole site to a channel by replacing the file at <ZDDC_ROOT>/<tool>.html with the matching level-2 stub from track-<channel>.zip. A single project can override one tool by editing just <project-X>/<tool>.html (replace the relative upstream URL with an absolute zddc.varasys.io URL).

Why two levels

The level-1 stubs let projects share a single source of truth for "which build of the archive tool runs here." Switching channels is one file change at the root; pinning a single project is one file change in that directory.

document.write() chains across both levels: level-1 fetches and writes, the new document's level-2 script runs and writes again, the third write is the actual tool. Origin stays at the deployment domain throughout, so File System Access API, crypto.subtle, and localStorage all work and preferences stay scoped to the deployment.

Pinning options

There are two ways to choose a version: edit the stub for a permanent pin, or pass a ?v= URL parameter for a per-request override.

1. Permanent pin (edit the stub)

Each stub has one fallback/upstream constant. Edit it once and the choice sticks for everyone using that file.

URL	Behavior
https://zddc.varasys.io/releases/<tool>_latest.html	current stable; auto-updates within stable
https://zddc.varasys.io/releases/<tool>_beta.html	latest beta build (mutable)
https://zddc.varasys.io/releases/<tool>_alpha.html	latest alpha build (mutable)
https://zddc.varasys.io/releases/<tool>_v1.2.3.html	pinned to exact stable version

2. Per-request ?v= parameter

Both stub levels honor a ?v= URL parameter. The parameter survives the document.write() chain, so it flows through level-1 → level-2 → upstream automatically.

URL parameter	Behavior
?v=0.0.4 (or ?v=v0.0.4)	tries <tool>_v0.0.4.html locally, then upstream
?v=alpha	switches to alpha channel
?v=beta	switches to beta channel
?v=latest	latest stable
(omitted)	the default baked into the stub

When level-1 has ?v=…, it tries ../<tool>_<suffix>.html first (useful when the admin has staged specific versions locally) and falls back to ../<tool>.html if 404 — which then forwards the parameter via level-2 if one is installed. So the same URL works whether the version is staged locally, served by a level-2 stub, or both.

Stable releases are immutable. Alpha and beta channel files are overwritten in place each time their channel is rebuilt; expect them to change without notice. The build label rendered on the tool page tells you what you are running (date + commit SHA for alpha/beta, version number for stable).

Auditing what's installed

Every stub contains a fallback (level-1) or upstream (level-2) constant. To see what each tool / project on the deployment points at:

grep -rn "fallback\|upstream" <ZDDC_ROOT>

CORS prerequisite (level-2 only)

A level-2 fetch is cross-origin (deployment → zddc.varasys.io). The upstream must serve Access-Control-Allow-Origin: * (or a list including your deployment origin) on the released HTML files. Verify with:

curl -I https://zddc.varasys.io/releases/archive_latest.html | grep -i access-control

Level-1 fetches are same-origin so no CORS is involved.

Templates

level1.html.tmpl and level2.html.tmpl are the source of truth. The project's top-level build.sh substitutes {{TOOL}}, {{TOOL_TITLE}}, and {{CHANNEL}} to produce the per-tool stubs that ship in install.zip and track-<channel>.zip.