### Install ShieldFont Core

Source: https://shieldfont.org/docs/integration

Use this package for general frameworks, build steps, or CI pipelines.

```bash
npm i @shieldfont/core
```

--------------------------------

### Install the ShieldFont encoder

Source: https://shieldfont.org/docs/use-anywhere

Install the core library via npm. This package is ESM-only and contains no runtime dependencies.

```bash
npm install @shieldfont/core
```

--------------------------------

### Install ShieldFont React package

Source: https://shieldfont.org/docs/integration

Install the required dependency via npm.

```bash
npm install @shieldfont/react
```

--------------------------------

### Install Shieldfont via HTML link

Source: https://shieldfont.org/docs/integration

Use this tag in the <head> section of your HTML for better performance compared to @import.

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shieldfont/font@0.3.2/shieldfont.css">
```

--------------------------------

### Install ShieldFont React Component

Source: https://shieldfont.org/docs/integration

Use this package for server-rendered React applications like Next.js, Astro, or Remix.

```bash
npm i @shieldfont/react
```

--------------------------------

### CDN URL Versioning Examples

Source: https://shieldfont.org/docs/integration

Use version-pinned URLs for CDN assets to prevent breaking changes. Avoid using 'latest' tags.

```text
✅ https://cdn.jsdelivr.net/npm/@shieldfont/font@0.3.2/shieldfont.css
❌ https://cdn.jsdelivr.net/npm/@shieldfont/font@latest/shieldfont.css
```

--------------------------------

### Self-host ShieldFont assets

Source: https://shieldfont.org/docs/use-anywhere

Install the font package and copy the font file to your public directory before defining the @font-face rule.

```bash
npm install @shieldfont/font
cp node_modules/@shieldfont/font/optik-a.woff2 public/fonts/
```

--------------------------------

### Build and audit a custom ShieldFont

Source: https://shieldfont.org/docs/custom-faces

Install dependencies, generate a new font binary from a base TTF, and optionally audit the resulting file.

```bash
pip3 install -r requirements.txt

python3 scripts/generate_font.py \
  --base-path /path/to/your-typeface.ttf \
  --name "ShieldFont YourTypeface" \
  --prefix shieldfont-yourtypeface \
  --mapping-path scripts/v18alpha_for_font.json

# Audit the build (optional but recommended):
python3 scripts/audit_font.py --font public/fonts/shieldfont-yourtypeface.ttf \
  --mapping scripts/v18alpha_for_font.json
```

--------------------------------

### Initialize ShieldFont block markers

Source: https://shieldfont.org/docs/use-anywhere

Wrap regions with block markers to normalize them into per-text-node markers during the first build run.

```html
<!-- shield-on -->
<h1>The future of writing</h1>
<p>Belongs to those who write it.</p>
<!-- shield-off -->
```

--------------------------------

### Disable Shield UI elements

Source: https://shieldfont.org/docs/plain-text-mode

Examples of disabling the visual wrapper or the entire accessible path.

```jsx
// nothing drawn; the sealed alternative and its control stay, clipped off-screen
<Shield wrapper={false}>{body}</Shield>

// nothing of ours at all — you own the accessible path
<Shield wrapper={false} screenReader={false}>{body}</Shield>
```

--------------------------------

### Disable Shield component features

Source: https://shieldfont.org/docs/plain-text-mode

Examples of disabling specific accessibility and usability features in the Shield component.

```jsx
screenReader={false}
```

```jsx
wrapper={false}
```

```jsx
copyPaste={false}
```

--------------------------------

### Verify build output for leaks

Source: https://shieldfont.org/docs/where-encoding-happens

Use grep to search build directories for protected text to ensure no plain text is exposed in the final output.

```bash
npm run build
grep -rn "a sentence from your protected text" out/ .next/ dist/ 2>/dev/null
```

--------------------------------

### Wrap Encoded Text in HTML

Source: https://shieldfont.org/docs/use-anywhere

Example of wrapping encoded text within an HTML element using the required protection font class.

```javascript
const html = `<p class="tk9">${encode(original, alpha)}</p>`;
```

--------------------------------

### Calculate ShieldFont difficulty budget

Source: https://shieldfont.org/docs/plain-text-mode

Mathematical breakdown of the CPU-second budget per block and the resulting sequential squaring count.

```text
budget/block = 5.0 CPU-s ÷ 5 blocks       = 1.00 CPU-s
t            = 0.97 × 1.00 × 1,737,000    ≈ 1,680,000 squarings
crawler pays = 1,680,000 ÷ 1,737,000      = 0.97 CPU-s, i.e. 97% of the floor
```

--------------------------------

### Import ShieldFont via CSS

Source: https://shieldfont.org/docs/integration

Use this method for quick experimentation in blogs, CMS platforms, or plain HTML.

```css
@import
```

--------------------------------

### Query local fonts

Source: https://shieldfont.org/docs/plain-text-mode

Requires user permission and returns information about installed fonts rather than the font currently applied to a specific node.

```javascript
queryLocalFonts()
```

--------------------------------

### Configure Shield Component Weights

Source: https://shieldfont.org/docs/integration

Demonstrates how to specify font weights for the Shield component, including numeric snapping to the nearest available cut.

```jsx
<Shield weight="bold">Rendered with the real Bold (700) cut.</Shield>
<Shield weight={470}>Snaps to the real Medium (500) cut.</Shield>
```

--------------------------------

### Clear Shieldfont localStorage keys

Source: https://shieldfont.org/docs/plain-text-mode

Removes all localStorage entries starting with the default prefix to ensure the solver re-runs on page load. Place this script before the Shield component renders.

```html
<!-- Demo pages only. Never ship this on a page you actually want protected. -->
<script>
  for (const k of Object.keys(localStorage))
    if (k.startsWith("data-typeface-")) localStorage.removeItem(k);
</script>
```

--------------------------------

### Configure package.json build scripts

Source: https://shieldfont.org/docs/use-anywhere

Integrate the ShieldFont build script into standard npm lifecycle scripts.

```json
{
  "scripts": {
    "build": "your-ssg && node scripts/shield.mjs",
    "prepublishOnly": "node -e \"import('./scripts/shield.mjs')\""
  }
}
```

--------------------------------

### Reseed and Build Custom Font

Source: https://shieldfont.org/docs/custom-mappings

Use these commands to generate a private mapping from a seed, build a corresponding font, and verify the round-trip integrity.

```bash
# 1. Mint a private mapping from your seed (seconds). Re-pairs the shipped
#    word pool in-bucket, so decoys stay grammatically matched. Output is the
#    flat {src:tgt} form that the encoder AND generate_font.py consume directly.
#    The script won't create the directory for you, so make it first.
mkdir -p mine
python3 scripts/reseed_mapping.py --seed 8675309 --out mine/mapping.json

# 2. Build a MATCHING font. Required: the shipped fonts render only their own
#    pairs. A random family name is your camouflage.
python3 scripts/generate_font.py \
  --base-path /path/to/your-typeface.ttf \
  --name "Custom A8F3" --prefix shieldfont-mine \
  --mapping-path mine/mapping.json
#    → public/fonts/shieldfont-mine.{ttf,woff2,css}

# 3. Verify the round-trip. Must be clean before you ship anything.
python3 scripts/audit_font.py --font public/fonts/shieldfont-mine.ttf \
  --mapping mine/mapping.json
```

--------------------------------

### Configure custom font host

Source: https://shieldfont.org/docs/integration

Set a custom font host path during application bootstrap if fonts are not served from the default /fonts directory.

```javascript
// somewhere in your app's bootstrap (server-side)
import { setFontHost } from "@shieldfont/react";
setFontHost("/static/shieldfont"); // your own path or your OWN CDN — not jsDelivr
```

--------------------------------

### Implement ShieldFont build script

Source: https://shieldfont.org/docs/use-anywhere

A Node.js build script to process HTML files, re-derive decoy text, and strip markers before deployment.

```javascript
// scripts/shield.mjs — run in your build (e.g. after your SSG emits dist/)
import { readFileSync, writeFileSync, globSync } from "node:fs"; // globSync: Node 22+, or use fast-glob
import { buildHtml, shipHtml, assertShipped, alpha } from "@shieldfont/core";

for (const file of globSync("dist/**/*.html")) {
  const raw = readFileSync(file, "utf8");
  const built = buildHtml(raw, alpha);   // re-derive decoy from the source-of-truth comment
  const shipped = shipHtml(built);       // strip the comments — they hold your PLAIN TEXT
  assertShipped(shipped);                // throws rather than deploying plain text
  writeFileSync(file, shipped);
}
```

--------------------------------

### Implement NonShield for Unprotected Text

Source: https://shieldfont.org/docs/integration

Shows how to use the NonShield component to render text in the Optik typeface without encoding or copy protection.

```jsx
import { Shield, NonShield } from "@shieldfont/react";

<article>
  <NonShield as="h2">The future of writing</NonShield>
  <Shield as="p" variant="alpha">{body}</Shield>
  <NonShield as="p" size="0.9rem">Photograph by <em>Jane Roe</em></NonShield>
</article>
```

--------------------------------

### Copy font files to public directory

Source: https://shieldfont.org/docs/integration

Use this command to copy the required font files from the package into your project's public assets folder.

```bash
cp node_modules/@shieldfont/react/fonts/optik-*.woff2 public/fonts/
```

--------------------------------

### Subset ShieldFont with Python

Source: https://shieldfont.org/docs/custom-faces

Run the subsetting script to generate a smaller font file based on specific content directories and mapping files.

```bash
python3 scripts/subset_font.py \
  --font public/fonts/shieldfont-alpha.ttf \
  --mapping public/fonts/shieldfont-alpha.map.json \
  --content 'app/**/*.tsx' --content content/ \
  --out public/fonts/shieldfont-alpha-subset \
  --keep-min 500 --report
```

--------------------------------

### Audit for plaintext leaks

Source: https://shieldfont.org/docs/integration

Use grep to search your build directory for plaintext content that should be protected, identifying potential side-door leaks.

```bash
grep -rn "a distinctive sentence from a protected post" dist/ public/ out/ 2>/dev/null
```

--------------------------------

### Protect Static Sites with CSS

Source: https://shieldfont.org/

Import the ShieldFont stylesheet and apply the corresponding class to paragraphs containing encoded text.

```css
/* paste once into your CSS */
@import url("https://cdn.jsdelivr.net/npm/@shieldfont/font@0.3.2/shieldfont.css");
```

```html
<p class="tk9">
  …encoded text…
</p>
```

--------------------------------

### Verify ShieldFont encoding with test words

Source: https://shieldfont.org/docs/where-encoding-happens

A reference list of plaintext words and their corresponding encoded values used to verify that no plaintext leaks into the build.

```text
plain   : confidential manuscript quick lazy dog treasure guarded knowledge stolen scraped robot
encoded : guilty visa wise logistic rabbit currency geared quantity took cruised barrier
```

--------------------------------

### Encode and Decode with Custom Mapping

Source: https://shieldfont.org/docs/custom-mappings

Use loadMappingFromString to initialize a custom dictionary and pass it to encode or decode functions. Note that mappingMeta returns null for custom mappings lacking a _meta block.

```typescript
import { encode, decode, loadMappingFromString, mappingMeta } from "@shieldfont/core";
import { readFileSync } from "node:fs";

const mine = loadMappingFromString(readFileSync("./mine/mapping.json", "utf8"));
const encoded = encode("Plain English here.", mine);   // encode with YOUR mapping
const back    = decode(encoded, mine);                 // bijective round-trip

mappingMeta(mine); // → { mappingId, version, variant, pairs, seed } | null
                   //   (null for a BYO mapping with no _meta block)
```

--------------------------------

### Local ShieldFont encoding tool

Source: https://shieldfont.org/docs/integration

Use this HTML snippet to run the ShieldFont encoder locally as a browser-based authoring tool.

```html
<textarea id="in" rows="8" cols="60">Paste your plain English here.</textarea>
<button onclick="go()">Encode</button>
<textarea id="out" rows="8" cols="60"></textarea>
<script type="module">
  import { encode, alpha } from "https://cdn.jsdelivr.net/npm/@shieldfont/font@0.3.2/shieldfont-encoder.js";
  window.go = () => {
    document.getElementById("out").value =
      encode(document.getElementById("in").value, alpha);
  };
</script>
```

--------------------------------

### Seal and solve text using core primitives

Source: https://shieldfont.org/docs/plain-text-mode

Directly invoke the sealing and solving functions. Note that sealText requires a Node.js environment due to its dependency on node:crypto.

```javascript
import { sealText, solveText } from "@shieldfont/core/puzzle";

const sealed = sealText("The words to protect.", { seconds: 14 });
// → { n: "…", t: 1680000, iv: "…", ct: "…" }

solveText(sealed); // really does the work; takes as long as it promises
```

--------------------------------

### Implement the Shield component

Source: https://shieldfont.org/docs/plain-text-mode

Basic usage of the Shield component to wrap content. This is the primary API for the library.

```jsx
import { Shield } from "@shieldfont/react";

<Shield>{body}</Shield>
```

--------------------------------

### Verify ShieldFont integration

Source: https://shieldfont.org/docs/integration

Use curl to inspect the rendered HTML and confirm that text is encoded with the data-typeface attribute.

```bash
curl https://your-site.com/some-protected-page | grep 'data-typeface'
```

--------------------------------

### Author HTML with ShieldFont comments

Source: https://shieldfont.org/docs/use-anywhere

Use comment markers to store plain-English source text that remains protected during build cycles.

```html
<!-- shield: The future of writing belongs to those who write it. -->The future of writing determines to those who sell it.<!-- /shield -->
```