docs: add TSDoc across public APIs and auto-publish TypeDoc site

[kelsos]

Summary

Two related changes landing together:

1. TSDoc coverage on every exported function, type, and singleton in the library (109 blocks across 30 files, all 13 namespaces).
2. TypeDoc site auto-published to GitHub Pages on every merge to main.

What consumers get

• Hover tooltips in VS Code / JetBrains for every public API — descriptions, realistic domain examples, and edge-case notes.
• Emitted .d.ts files carry the TSDoc forward, so downstream tooling (language servers, api-extractor, typedoc consumers) sees the same comments.
• Searchable API reference site at https://kelsos.net/plainfp/ (inherits the user-level Pages custom domain on kelsos.github.io). Refreshes automatically on each merge.

TSDoc style choices

• Imperative mood ("Transform the value…" not "Transforms…"). No "this function".
• @example blocks only on user-facing functions; trivial type guards and obvious aliases get one-liner descriptions.
• No @param / @returns that just restate the TS signature.
• On overloaded functions the block sits on the first overload only; implementation signatures and internal helpers (isFn, sleep, run closures) are left undocumented.
• Realistic domain values in examples (users, orders, payments) — no foo/bar/baz.

Edge cases explicitly documented

• chunk → RangeError on fractional/zero/negative sizes
• minBy/maxBy → Option<T>, none on empty input
• find/findIndex → return Option (replacing native undefined / -1)
• fromZod → throws a wrapped error on async schemas; points at fromZodAsync
• allWithConcurrency → swallows factory rejections (use fromPromise to preserve)
• Records.get / getOr → own properties only, prototype chain is skipped
• unique / uniqueBy → SameValueZero semantics (NaN=NaN, +0=-0)
• tag → data cannot hijack _tag; Tagged<Tag, Data> omits _tag from Data

TypeDoc wiring

• pnpm docs / pnpm docs:watch scripts
• typedoc.json pins entry points (every subpath export), excludes private/internal, validates links
• docs.yml workflow: build + deploy via actions/configure-pages + actions/upload-pages-artifact + actions/deploy-pages (SHA-pinned, tokenless OIDC, concurrency-guarded)
• .gitignore excludes packages/*/docs/api/; vite.config.ts fmt+lint ignore the same path

Dist size impact

plainfp grows from 114 KB → 180 KB unminified. This is the cost of shipping TSDoc inline with the .d.ts files. Minified + gzipped size is roughly proportional. For a docs-heavy library this is worth it — consumers who care about raw size can use a bundler that strips comments at build.

No runtime code changed

Purely comments + config + new tooling wiring. All 177 tests still pass, typecheck clean, attw clean, publint clean.

Test plan

• All required status checks pass
• docs.yml deploys successfully on merge to main (first run establishes the Pages site)
• https://kelsos.net/plainfp/ loads the API reference after merge
• Hover tooltips in an IDE on plainfp imports show the TSDoc content (can verify locally: pnpm build && cd packages/plainfp/dist && ls *.d.ts)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.41%. Comparing base (ea43477) to head (377d35d).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main       #5   +/-   ##
=======================================
  Coverage   86.41%   86.41%           
=======================================
  Files          20       20           
  Lines         346      346           
  Branches       71       71           
=======================================
  Hits          299      299           
  Misses         19       19           
  Partials       28       28           

Flag	Coverage Δ
unittests	86.41% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/plainfp/src/arrays/aggregate.ts	85.00% <ø> (ø)
packages/plainfp/src/arrays/group.ts	100.00% <ø> (ø)
packages/plainfp/src/arrays/search.ts	94.11% <ø> (ø)
packages/plainfp/src/arrays/transform.ts	100.00% <ø> (ø)
packages/plainfp/src/arrays/unique.ts	100.00% <ø> (ø)
packages/plainfp/src/option/constructors.ts	100.00% <ø> (ø)
packages/plainfp/src/option/transform.ts	66.66% <ø> (ø)
packages/plainfp/src/option/unwrap.ts	83.33% <ø> (ø)
packages/plainfp/src/pipe.ts	100.00% <ø> (ø)
packages/plainfp/src/records/access.ts	100.00% <ø> (ø)
... and 10 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[codspeed-hq]

Merging this PR will not alter performance

✅ 20 untouched benchmarks

---

_{Comparing docs/tsdoc-coverage (377d35d) with main (ea43477)}