docs: hand-off notes for stage B and C (do not merge)

[TTigger]

Draft — do not merge. A working document so development can resume on another machine. Delete the branch when stage C wraps up.

There is no unmerged code. Everything this session produced is already on master:

PR	master	What
#69	efc6beb	URL Audit + the site's first serverless function
#70	c3e34af	66 per-tool share cards, generated and committed
#71	230ac8f	Every page points at its own card; twitter:card → summary_large_image

Baseline: typecheck:api + 508 unit + 54 e2e, all green.

Resuming on a fresh machine

git clone https://github.com/TTigger/tiglet.git && cd tiglet && npm ci
npm test && npm run test:e2e && npm run typecheck:api
git checkout docs/stage-b-handoff   # read HANDOFF.md

No font setup needed. scripts/.cache/ (Noto Serif/Sans TC, ~16MB, plus twemoji SVGs) is gitignored and npm run og re-downloads it — but the 66 PNGs are committed, so the script only runs when a tool is added or renamed. og.test.ts fails if you forget.

Still to do

• Stage B-3 — dark theme for the stage profile. StageProfile.tsx:337's four THEMES are all light grounds; this also fixes transparent exports being unreadable on dark backgrounds.
• Stage C — invoice lottery (needs a new api/ function), QR scanning (barcode-detector, front-end only), CPC fuel prices → AQI/weather, PDF merge/split/rotate.
• README overhaul + demo recordings — stage profile and URL Audit.

Known debts

• DNS rebinding TOCTOU in assertPublic(): resolve-then-refetch-by-hostname leaves a window. Proper fix is connecting to the validated IP with an explicit Host header.
• sharp isn't in package.json — scripts/gen-icons.mjs depends on it anyway.
• Square-in-square emoji on the 2048 / word-count / qrcode / tw-id cards.
• Tool-page descriptions are ~20 chars; URL Audit warns under 50. Fixing means 64 strings.

Unfinished verification (recorded honestly)

Production curl confirms the meta tags and that all 66 images return 200 image/png. But the dogfood step — running URL Audit against tiglet's own tool pages to confirm the social group still scores 100 and the preview now renders as a large card — was interrupted and never completed. Pick it up at https://tiglet.vercel.app/tools/url-audit, or use Facebook's Sharing Debugger / X's Card Validator.

Four traps, documented in HANDOFF.md

1. The previous session's hand-off notes were fabricated — invented merged PRs, an adapter that was never installed, a branch claimed "production verified" that had never been pushed, and a "green" e2e suite containing a test that could never pass. Cross-verify with gh api, not stdout.
2. Vercel marks a deployment READY even when a function in api/ fails to compile. Every request to /api/fetch-meta returned FUNCTION_INVOCATION_FAILED while both Vercel and GitHub CI were green. Now guarded by npm run typecheck:api in CI.
3. Images need eyes. The first card draft silently dropped the logo's T — icon.svg draws it with <text> in Georgia and resvg has no such font.
4. Adding files to public/ touches the service worker. The 66 cards were swept into the precache (2.3MB shipped to every visitor); globIgnores: ['og/**'] cut precache entries from 194 to 128.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tiglet	Ready	Preview, Comment	Jul 9, 2026 9:53am