# Deploying to Hugging Face

This repo deploys [SimpleDocReview](https://github.com/eputnam77/SimpleDocReview)
to a Hugging Face **Static** Space as a browser-only demo. It holds no
application logic of its own — only the build tooling, the Space card, a vendored
copy of upstream in `app/`, the browser-side API in `overlay/`, and the generated
site at the repository root.

## Why static

Per Hugging Face's own docs, [Static Spaces][static-docs] are free for everyone —
"served directly without running on compute, so unlike Gradio and Docker Spaces,
creating them never requires a paid plan."

Upstream is a good fit in one respect and a poor fit in another, and both matter:

- **Good fit:** the front end is plain HTML, CSS, and JavaScript with no build
  step, no framework, and no bundler. It is served byte-for-byte as upstream
  wrote it.
- **Poor fit:** upstream is a *server*. `app.py` owns the review logic and the
  storage. A Static Space cannot run it, so the API is reimplemented in the
  browser and the storage becomes IndexedDB.

That second point is the whole design constraint of this repository, and it is
why the Space is a demo. See [What the demo cannot be](#what-the-demo-cannot-be).

[static-docs]: https://huggingface.co/docs/hub/spaces-sdks-static

## The everyday workflow

After you change something in `C:\dev\SimpleDocReview` and commit it there:

```powershell
cd C:\dev\sdr-streamlit
.\scripts\deploy.ps1
```

That syncs `app/`, builds the site into the repository root, commits with the
upstream commit in the message, and pushes to `hf`. Because a Static Space serves
files directly, the update is live as soon as the push lands.

To see what would change without committing:

```powershell
.\scripts\deploy.ps1 -DryRun
```

Individual steps, when you want them:

```powershell
.\scripts\sync-upstream.ps1          # refresh app/ from the local upstream checkout
.\scripts\build-static.ps1           # build the site into the repository root
node tests\parity\run-parity.mjs     # diff the browser API against the real app.py
node tests\browser\run-browser-check.mjs   # drive the built site in headless Chromium
python -m http.server 8000           # preview at http://localhost:8000
```

### Useful flags

| Flag | Effect |
| --- | --- |
| `-Message "feat: ..."` | Custom commit message |
| `-AlsoPushOrigin` | Also push to the GitHub mirror of this repo |
| `-UpstreamPath D:\other\checkout` | Sync from a different checkout |
| `-AllowDirty` | Deploy from an uncommitted upstream working tree |
| `-SkipSync` | Build and deploy `app/` as it stands, no re-mirror |
| `-SkipBuild` | Commit and push the existing site, no rebuild |
| `-SkipTests` | Skip the parity and browser checks (they run by default) |
| `-DryRun` | Show the plan, change nothing |

By default a dirty upstream working tree is an **error**, because `UPSTREAM.json`
would otherwise record a commit that does not describe what actually shipped.
Commit upstream first, or opt in with `-AllowDirty`.

## First-time setup

1. Create the Space at https://huggingface.co/new-space — choose the **Static**
   SDK and the **Blank** template. Name it `SimpleDocReview`.

2. Add it as a remote:

   ```powershell
   git remote add hf https://huggingface.co/spaces/Hoctar77/SimpleDocReview
   ```

3. Authenticate. Use a Hugging Face access token with **write** scope from
   https://huggingface.co/settings/tokens as the password when git prompts, or
   store it once:

   ```powershell
   git config credential.helper manager
   ```

4. Build and push:

   ```powershell
   .\scripts\deploy.ps1 -AlsoPushOrigin
   ```

   A blank Space starts with its own initial commit, so the first push may be
   rejected as non-fast-forward. Reconcile once:

   ```powershell
   git pull --rebase hf main
   git push hf main
   ```

## How the build works

```
app/        clean upstream mirror        (generated by sync-upstream.ps1)
overlay/    the browser-side API         (hand-maintained)
   |
   v  copy + insert two <script> tags into index.html
.build/out/
   |
   v  copied to the repository root
index.html, static/, sdr-api-core.js, sdr-api-shim.js   (committed; HF serves these)
```

There is no compiler and no package manager. `build-static.ps1` copies
`app/static/index.html` to the site root, copies the rest of `app/static/` to
`/static/`, copies the two overlay scripts, and inserts their `<script>` tags
immediately before upstream's `app.js` tag.

The repository root is the web root, which is why the site lives there rather
than in a subdirectory — `index.html` asks for `/static/styles.css` by absolute
path.

Everything the build emits is recorded in `.space-build-manifest` and deleted
before the next copy, so nothing stale accumulates. The cleanup refuses to touch
a protected list (`README.md`, `app/`, `scripts/`, …) even if the manifest
somehow named one.

### Why the script tags are inserted rather than committed

The overlay has to load before `app.js`, which fires its first three requests as
soon as it is parsed. The alternative — keeping a modified `index.html` in
`overlay/` — would mean a second copy of an upstream file that silently rots
every time upstream edits its markup. Inserting a tag is a *transform* of
upstream's HTML, so there is nothing to drift.

`build-static.ps1` fails loudly if it cannot find upstream's `app.js` tag, rather
than shipping a page where the overlay never loads.

## The browser-side API

`overlay/sdr-api-core.js` is a port of `app.py`: every route, the rubric
analyzer, the DOCX text extractor, the status recalculation, the notification
queue, and the record migrations. `overlay/sdr-api-shim.js` supplies what a
browser has and Python does not — IndexedDB, an `XMLHttpRequest` interceptor, and
a click handler for the Download button.

Three things in that split are worth knowing:

- **Requests are intercepted at `XMLHttpRequest`,** not `fetch`, because that is
  what upstream's `app.js` uses. The interceptor is a `Proxy` over a real
  `XMLHttpRequest`, so anything the shim does not simulate still reaches the
  genuine object. `fetch` is covered too, defensively, in case upstream migrates.
- **Download is a click interception, not a request interception.** Upstream
  navigates: `window.location.href = "/api/documents/<id>/download"`. A page
  cannot cancel that assignment, so the click is caught in the capture phase
  before upstream's own handler runs, and the file is handed over as a blob URL.
  The shim tracks which document is on screen from the API traffic, because the
  click event does not carry the id.
- **DOCX extraction has no dependency.** `app.py` uses `zipfile`; the port reads
  the ZIP central directory itself and inflates with `DecompressionStream`,
  which every current browser has. ZIP64 is rejected rather than guessed at.

### Keeping the port honest

A port that silently diverges from the server it mirrors is worse than no port,
so three things guard it.

**A hash guard.** `overlay/ported-from.json` records the SHA-256 of `app.py` and
`static/app.js` as of the last time the port was reviewed.
`build-static.ps1` refuses to build when either changes:

```
Upstream changed in files the overlay reimplements: app.py
```

Read the upstream diff, carry any behavior change into `sdr-api-core.js`, re-run
the tests, then acknowledge it:

```powershell
.\scripts\build-static.ps1 -AcceptUpstreamChanges
```

This is deliberately annoying. An upstream change to a rubric rule or a status
transition will not reach the Space on its own, and nothing else in a
copy-and-inject build would notice.

**A parity test.** `tests/parity/` replays a 67-request workflow through the real
`app.py` — imported from `app/`, behind a real HTTP server, with its clock and
`uuid4` replaced by counters — and through the JavaScript port in Node, then
diffs every response, the final record store, and the list of stored uploads.
Making the clock sequential means the port has to *call* it the same number of
times in the same order, so a missing timestamp is a failure rather than a value
nobody compares.

One divergence is accepted and printed on every run: `mimetypes.guess_type`
returns `application/octet-stream` for `.docx` on a Windows machine with no
Office mapping, where the port always sends the real OOXML type.

**A browser test.** `tests/browser/` serves the repository root, opens it in
headless Chromium via the DevTools protocol, and runs upload → review → assign →
approve → download → reload through the real UI. That covers what the parity test
cannot: the inserted script tags, the XHR interception, IndexedDB persistence
across a reload, and the download click.

## What the demo cannot be

Storage is the constraint, and it is not fixable inside a Static Space:

- **Records are per-browser.** IndexedDB is scoped to one origin in one browser
  profile. A reviewer opening the same URL sees an empty workspace, so a real
  multi-person approval round cannot happen here.
- **Records are disposable.** Clearing site data deletes them, with no export
  other than downloading the original files one at a time.
- **Records may not persist at all.** The Space renders in an iframe on
  huggingface.co, and a browser that partitions or blocks storage for embedded
  third parties leaves the shim with an in-memory store for the length of the
  visit. It says so in the notice when that happens.

The Space says all of this in three places: the Space card, a badge next to the
title that does not go away, and a dismissible notice on first load. Keep them
accurate. Someone who mistakes this for a service and runs a real approval round
through it loses the record with no warning, and that is the one failure mode
this deployment can actually cause.

If you need the Space to be the real thing, it needs to run `app.py`, which
means the Docker SDK on a paid plan — and even then, a Space's filesystem is
ephemeral, so `data/reviews.json` and `uploads/` would need a persistent volume
or an external store. The `Dockerfile` here runs upstream unmodified for local
use and as that starting point; the Space does not use it.

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| Space shows a directory listing or 404 | `app_file: index.html` must be in the front matter and `index.html` must exist at the repo root. Re-run `build-static.ps1`. |
| The page loads but stays empty, console shows 404s for `/api/...` | The overlay did not load. Confirm both `<script>` tags are in the deployed `index.html`, before `app.js`. |
| `sdr-api-core.js did not load` in the console | The tags are in the wrong order. `sdr-api-core.js` must come first. |
| Build fails: "Upstream changed in files the overlay reimplements" | Working as intended. Review the upstream diff, update the overlay, then `-AcceptUpstreamChanges`. |
| Build fails: "Could not find upstream's app.js script tag" | Upstream changed its markup. Update the anchor in `build-static.ps1`. |
| Parity test fails after an upstream change | The port no longer matches `app.py`. The diff output names the exact field. |
| Browser test cannot find a browser | Set `BROWSER` to a `chrome.exe` or `msedge.exe` path. |
| Documents vanish between visits | Expected on a demo. See [What the demo cannot be](#what-the-demo-cannot-be). |
| Uploading a DOCX fails with "appears to be invalid" | The port rejects ZIP64 archives and unsupported compression methods. Re-save the file from Word. |
| Push rejected, non-fast-forward | The Space has commits this repo lacks: `git pull --rebase hf main`. |
| `robocopy` exit code 8 or higher | A real copy failure — a file was locked. Close anything watching `app/` or `.build/` and re-run. |