# CCS PDF Editor — Development Standards

| Field | Value |
|-------|--------|
| **Version** | 1.5.40 |
| **Owner** | CCS Information Technology |
| **Approved by** | CCS Information Technology |
| **Last updated** | 2026-08-15 |
| **Review frequency** | Annual (or after significant process/tooling change) |
| **Next review** | 2027-08-05 |

Standards for anyone changing application code, assets, or docs. Goal: keep deploys boring, offline-first intact, and reviews short. Process/compliance: [GOVERNANCE.md](GOVERNANCE.md).

---

## 1. Principles

1. **Offline-first** — Core editing, OCR, encrypt, and export must work from **vendored** `lib/` + `assets/` without third-party CDNs; `file://` uses embeds where needed.  
2. **Documents stay local** — Do not add server upload of PDF content without architecture + governance revision and explicit approval.  
3. **No build step required** for OWA UI — plain browser JS from `index.html` (Windows EXE is a separate packager).  
4. **Security by default** — Sanitize any HTML restored into the DOM; avoid `eval`; be careful with `innerHTML`.  
5. **Document the “why”** — Save-gesture, project trailer, form fill vs design, and offline paths live in docs.  
6. **CCS ownership** — App code remains under [LICENSE](../LICENSE); third parties under [NOTICE](../NOTICE).

---

## 2. Repository layout

| Path | Purpose |
|------|---------|
| `index.html` | Shell, script tags, modals markup |
| `js/core/` | State, history, project-state / seal, project-audit, crypto, import/export, host-bridge |
| `js/engine/` | PDF render, AnnotationLayer helpers (`native-forms.js`), thumbnails |
| `js/overlays/` | Editable objects + form design/fill |
| `js/interaction/` | Input + file import |
| `js/features/` | OCR, print, signature + form attestation |
| `js/ui/` | Modals, toolbars, hotkeys, header density |
| `lib/` | Third-party engines + offline embeds (do not “clean up” without NOTICE) |
| `assets/` | Self-hosted fonts |
| `docs/` | Compliance & training |
| `scripts/` | `build-release.ps1`, `build-windows.ps1` |
| `deploy_windows/` | WebView2 shell + `tools\` helpers |
| `manifest.json`, `sw.js` | PWA hooks |

Do **not** commit secrets, live PHI sample documents, or node_modules unless the team deliberately adopts a broader build toolchain.

---

## 3. JavaScript conventions

### Style

- Prefer readable vanilla JS consistent with existing modules.  
- Features hang off `window.*` for simple multi-file loading (current pattern).  
- Prefer early returns; keep export paths resilient (`try/finally` for DOM restore).  
- Use `const`/`let`; avoid introducing a framework without a project decision.

### Module boundaries (logical)

| Concern | Home |
|---------|------|
| Save destination (Tauri / picker / download) | `js/core/io.js` — `acquireSaveDestination` / `writeSaveDestination` |
| Flatten export | `exportPdf` in `io.js` |
| Project export | `exportProject` in `io.js` |
| Render page | `js/engine/renderer.js` |
| OCR worker config | `js/features/ocr.js` — **local paths only** |

### Errors

- User-facing: `customAlert` / `customConfirm` with generic messages.  
- Log detail with `console.error` / `console.warn` for IT debugging.  
- Never empty-catch security or save failures without fallback or user message.

### Save / user activation

Long async work (`html2canvas`, multi-page loops, `setTimeout` yields) **clears** Chromium transient activation.

**Rule:** Call `acquireSaveDestination()` (or equivalent) **before** long export work. Do not call `showSaveFilePicker` only at the end of export.

---

## 4. Front-end / CSS

- Prefer existing classes in `style.css` for modals and overlays.  
- Keep UI handles (resize, rotate, drag) excluded from export capture.  
- Inverse zoom CSS variables already exist for handle sizing — preserve behavior when changing zoom.

---

## 5. Security standards

| Area | Rule |
|------|------|
| HTML from files / projects | Run through `sanitizeHTML` (or stricter) before `innerHTML` |
| External images | Prefer user-selected local files; blob → controlled use |
| New network calls | **Forbidden for document content** without governance change; asset loads same-origin only |
| CDN | Do not point production OCR/pdf.js at public CDNs |
| Dependencies | Vendor into `lib/`; update NOTICE; smoke-test offline |
| Service worker | Must not cache user PDF contents from arbitrary URLs; asset-focused only |
| Secrets | None in repo |

---

## 6. Privacy & test data

- Prefer **synthetic** PDFs in tickets, screenshots, and shared labs.  
- If a production-like PHI PDF is required for a bug, minimize pages, restrict access, and destroy copies after fix per CCS policy.  
- Do not commit sample charts with real client names.

---

## 7. Release checklist

Before promoting a build to production (OWA and/or Windows pack):

| # | Check |
|---|--------|
| 1 | Open multi-page PDF; zoom (default 100%); text layer selectable |
| 2 | Editor: add text, rectangle, **circle/ellipse**, line, image; rotate a shape (toolbar stays upright); undo/redo |
| 3 | Open a **fillable** PDF → **Editor + Pointer** can type/check/select fields |
| 4 | Form workspace: place text field + dropdown; Options modal works; fill in Editor+Pointer |
| 5 | Save Project → re-open → annotations **and** form fields restore; trailer `audit[]` present when edits were made; optional smoke: `scripts\extract-ccspdf-audit.ps1 -Path … -FullSchema` → Integrity OK |
| 6 | Save PDF from **Form** mode → annotations full opacity; fields fillable in Edge/Adobe |
| 7 | Save PDF **with password** → unlock in Edge/Adobe; fields still fillable |
| 8 | Open **password-protected** PDF → centered unlock dialog; cancel aborts cleanly |
| 9 | OCR on a scan page (HTTPS and, if shipping offline pack, `file://`) |
| 10 | Print dialog opens; annotations not faded |
| 11 | Firefox: name modal + download; Chromium: native save **before** long wait |
| 12 | Workspace: F → Form+Pointer; E in Form → Editor+Pointer; E in Editor → Edit/Stamp |
| 13 | Header usable at ~1280 CSS px (labels may collapse; tool select readable) |
| 14 | No unexpected third-party host calls in DevTools Network |
| 15 | Windows pack (if used): EXE opens; `tools\Create Desktop Shortcut.bat`; Register File Types |
| 16 | Edit `VERSION`, then `scripts\sync-version.ps1` (stamps headers / `config.js` / zip names and runs `render-docs.ps1`; does **not** overwrite `marketing/index.html` story, only the footer version) |
| 17 | Ticket / change record references the deploy |

---

## 8. Documentation maintenance

| Change | Update |
|--------|--------|
| New library | [NOTICE](../NOTICE) |
| New data leaving the browser | Update ARCHITECTURE, GOVERNANCE, and SYSTEM-PROFILE; obtain approval before production |
| New user-facing feature | USER-GUIDE + USER-TRAINING as needed |
| Host URL / owner change | SYSTEM-PROFILE |
| Release version | Edit [VERSION](../VERSION), then run `scripts/sync-version.ps1` (stamps `config.js`, README, doc headers, SYSTEM-PROFILE, [CHANGELOG-1.5.25.md](CHANGELOG-1.5.25.md), Windows zip names; regenerates HTML) |

---

## 9. Related

- [ARCHITECTURE.md](ARCHITECTURE.md)  
- [GOVERNANCE.md](GOVERNANCE.md)  
- [README.md](../README.md)  
