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
- Offline-first — Core editing, OCR, encrypt, and export must work from vendored
lib/+assets/without third-party CDNs;file://uses embeds where needed. - Documents stay local — Do not add server upload of PDF content without architecture + governance revision and explicit approval.
- No build step required for OWA UI — plain browser JS from
index.html(Windows EXE is a separate packager). - Security by default — Sanitize any HTML restored into the DOM; avoid
eval; be careful withinnerHTML. - Document the “why” — Save-gesture, project trailer, form fill vs design, and offline paths live in docs.
- 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/finallyfor 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/customConfirmwith generic messages. - Log detail with
console.error/console.warnfor 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.cssfor 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
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.