CCS PDF Editor · Docs

# 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.

## 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; third parties under 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
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, then run `scripts/sync-version.ps1` (stamps `config.js`, README, doc headers, SYSTEM-PROFILE, CHANGELOG-1.5.25.md, Windows zip names; regenerates HTML)

## 9. Related

- ARCHITECTURE.md
- GOVERNANCE.md
- README.md

Rendered for the browser from repository markdown. Edit the `.md` sources, then re-run `powershell -File docs/marketing/render-docs.ps1` from the repo root.