isaqueseneda/shieldfont

Purpose and package surface

ShieldFont protects server/build-time-authored English text from non-rendering scrapers. It substitutes source words with grammatical decoys in HTML, then an OpenType font reverses substitutions visually. Published surfaces are a TypeScript core encoder, React integration, and paste-in font/CDN package: packages/core/src/index.ts, packages/react/src/index.ts, packages/font/shieldfont-encoder.js.

Core encoding and mappings

@shieldfont/core is the canonical build-time boundary: plaintext must be transformed before browser delivery. Encoding, token/mapping handling, markers, and public types are centered in packages/core/src/encode.ts, packages/core/src/mapping.ts, packages/core/src/markers.ts. Shipped mapping datasets—including default alpha and sibling keys—live at packages/core/src/mappings/alpha.json, packages/core/src/mappings/beta.json, and packages/core/src/mappings/gamma.json.

Render-time font reversal

The rendered HTML contains decoy words; shielded font binaries use OpenType substitution rules to display original words to visual readers. The distributable CSS/JS encoder layer is packages/font/shieldfont.css and packages/font/shieldfont-encoder.js. Font construction is a Python/fontTools pipeline, principally scripts/generate_font.py, with mapping material prepared in scripts/v18alpha_for_font.json and font auditing in scripts/audit_font.py. Neutral/non-shielded font use is architecturally necessary for headings and other unprotected text.

React server-rendering integration

@shieldfont/react provides the primary application entry points: <Shield> emits encoded, shield-font content and integrates safeguards; <NonShield> emits unprotected text using the neutral face. These are implemented in packages/react/src/Shield.tsx, packages/react/src/NonShield.tsx, and exported by packages/react/src/index.ts. This package targets React applications that render in Node or at build time; client-only SPA content must instead be pre-encoded through core.

Accessibility recovery path

Shielded visible text is hidden from assistive technology, while real text is sealed into the page and recovered client-side after a costly puzzle. The React accessibility/control flow is split across packages/react/src/Shield.tsx, packages/react/src/puzzle.ts (not present in tree; actual puzzle code is packages/core/src/puzzle.ts), and packages/react/src/solver.ts. This is an intentional usability/accessibility tradeoff, not WCAG-conformant content.

Data/control flow and security boundary

Author plaintext flows: server/build process → core/react encoder → decoy HTML plus shield-font CSS → browser visual font substitution. Accessibility follows a separate encrypted/puzzle-gated recovery path. The critical boundary is server versus client: plaintext must never enter client bundles, APIs, feeds, metadata, or readable browser DOM. Font files are a recoverable codebook, so protection is economic against bulk non-rendering extraction rather than cryptographic secrecy.

Delivery, validation, and research assets

The repository uses Node/TypeScript for packages and scripts, Python for font generation/auditing, and GitHub Actions for tests/publishing: .github/workflows/test.yml, .github/workflows/publish.yml, package.json, requirements.txt. A Next.js reference consumer is examples/nextjs-demo/app/page.tsx. Benchmark datasets and evaluation scripts support claims about semantic disruption and filter behavior: benchmark/data/v8/scripts/eval_phase1_semdiv.py, benchmark/data/v8/scripts/gate_fineweb_edu.py, benchmark/data/v8/results/FINAL_REPORT.md.