docs(website): rebrand homepage around 'any binary' + raw .md endpoint - #36
Merged
Conversation
Re-applies #32, which merged as an empty commit (squash-merge bug — the merge commit had the right message but recorded no file changes, so the old `viewBox=220` SVG stayed on main). Two fixes to /flow.svg: - Cropping: viewBox was 720x220 but content (the patch label + the diagonal arrow) sat at y=226, clipped on every render. Widened to 720x260 and moved labels into bounds. - Dark mode invisibility: SVG is embedded via <img>, which sandboxes it from host-page CSS variables. `currentColor` defaults to black, invisible against the dark theme background. Switch to explicit `prefers-color-scheme` media query inside the SVG with light/dark hex tokens.
Reposition the binpitch landing page from CLI-only to 'any binary' — Electron apps, CLIs, agents, game updaters. Lead with a measured download comparison instead of an abstract '90% savings' claim. Hero graph: getsentry/cli 0.38.0 to 0.39.0 (sentry-linux-x64) shows a 31.83 MB full gzipped binary versus a 2.58 MB binpatch patch (8.1% ratio, 92% saved). Numbers come from a new bench/sentry-cli-bench.mjs reproducible script that downloads the real upstream artifacts, applies the published TRDIFF10 patch through applyPatchChainInMemory, and verifies the SHA-256 of the reconstructed binary. The script is linked from the homepage so anyone can re-run it. 'When to reach for binpatch' is now a Tabs component with four positioning angles (Self-updating CLI / Electron-Tauri / Agent-daemon / Game-native) instead of a single CardGrid. 'What you save' stays a CardGrid but with measured numbers instead of percentages. Each page now exposes its raw markdown source at /<slug>.md via a Starlight Footer override and an Astro API endpoint. The link is base-path aware so PR previews keep working. Useful for LLM scraping, copy-as-markdown, and humans who prefer the raw source. Also includes light edits to architecture.md, faq.md, contributing.md, and README.md dropping CLI-only framing.
Move size-comparison.svg to sit immediately below the hero (it was still preceded by a paragraph explaining the numbers). Caption below the chart now just names the data source (getsentry/cli release history) — no more link to the benchmark script or callout for applyPatchChainInMemory. Drop bench/sentry-cli-bench.mjs and the bench/ directory entirely. The chart stands on its own with a measured-data caption; the runnable script was a digression for the homepage audience. Clean up .gitignore entries that were tracking bench fixtures. CHANGELOG.md entry updated to match.
Contributor
|
Markdown image syntax `![]()` renders the URL verbatim in the HTML, so the previous `/size-comparison.svg` references resolved to the top-level `https://binpatch.p.byk.im/size-comparison.svg` even on PR previews — the SVG wasn't found under `/_preview/pr-N/` and the page showed a broken image. Switch both image references in index.mdx to inline JSX <img> tags that prepend `import.meta.env.BASE_URL` (with a trailing-slash trim to avoid double slashes). The MarkdownLink footer link already uses the same pattern, so the two are consistent now. Verified: PR-preview build emits `/_preview/pr-36/size-comparison.svg` and `/_preview/pr-36/flow.svg`. Production build emits the bare `/size-comparison.svg` and `/flow.svg` as before. Link check still passes.
Simplify size-comparison.svg: - Drop the huge 'MEASURED ON' / 'getsentry/cli' headers at the top. The chart now leads with the bars themselves, then the 'getsentry/cli · 8 release pairs' range section below the horizontal divider. - Drop the '96% SAVED PER UPDATE' pill — the bars speak for themselves. - Drop everything below the horizontal line (per-pair bar chart). The range strip with min/median/max ticks already conveys the variance. - Switch bars from solid fills to diagonal SVG <pattern> hatches. Full bar is light ink hatching; patch bar is accent-orange hatching. Hatch colors adapt to dark mode via prefers-color-scheme media query on the pattern's stroke/fill classes. Simplify index.mdx: - Drop the 'Measured on 8 adjacent ...' paragraph below the chart. - Swap 'The catch' (deltas need two halves) and 'What you save' (CardGrid) sections — savings first, then the architectural context.
Drop the range strip (line + min/median/max ticks) and the footer caption from the chart. The chart is now just two hatched bars with their labels, the horizontal divider, and the 'getsentry/cli · 8 release pairs' header + subtitle below. Variance info (min 0.9% / median 4.0% / max 8.1%) is still mentioned in the subtitle and the alt text, so the data is preserved in accessible form without the visual noise.
Replace the hand-drawn flow.svg with a fenced Mermaid code block in the homepage. The diagram itself is now text in the Markdown, easier to edit and review in PRs. Mermaid infrastructure (mirrors the loreai blueprint at BYK/loreai PR #1528): - New integrations/mermaid-renderer.mjs that uses astro:config:setup to inject a bundled Mermaid renderer on every page (docs AND any future pages). Renderer walks pre[data-language=mermaid] blocks (Expressive Code wrapping of a fenced mermaid block) and replaces each with the rendered SVG. - New mermaid@11.16.0 dep in website/package.json. - astro.config.mjs wires the renderer into the integrations array. - Old flow.svg and the JSX img reference removed. Section reordering (per request): When to reach for binpatch sits between What you save (CardGrid) and The catch (deltas need two halves). The flow chart is in its usual slot, just inside the How an update flows heading. Note: builds use npm ci (CI uses Pages workflow with npm). The pnpm overrides in package.json were unchanged from previous commits; the existing package-lock.json carries vite@8.x which astro@7.1.4 needs for its build.environments.prerender config.
Wire up the mermaid-renderer integration: - astro.config.mjs imports and registers the integration - package.json declares mermaid at 11.16.0 as a dep - package-lock.json carries the lockfile entry Swap the JSX img reference to flow.svg for a fenced mermaid block in the "How an update flows" section of index.mdx. Section reordering: "When to reach for binpatch" now sits between "What you save" and "The catch: deltas need two halves". Delete website/public/flow.svg (no longer referenced).
npm install --save dropped the vite^7.3.5 pnpm override while rewriting package.json. Restore it so pnpm users on this branch don't get auto-bumped to vite 8.x, which is what astro@7.1.4 needs (the lockfile already pins it via npm ci).
…nd-v3 # Conflicts: # website/public/flow.svg
…page Landing page refinements per feedback: - Drop TRDIFF10 references from the landing page. The previous copy mentioned TRDIFF10 three times (description, Electron Tabs item, mermaid node label). Keep the technical term in architecture.md and github-action.md where readers care about the wire format; the landing page is about the why, not the how. - Remove the duplicate "The catch" + "How an update flows" sections. The earlier section ordering work accidentally left both copies in place; collapse to one "The catch" section that links out to the github-action page for the flow diagram. - Drop "Skip it when" from the "When to reach for binpatch" Tabs. Negation framing was muddying the section — the tabs already enumerate positive cases. - Drop the "CI minutes" Card. The card claimed bsdiff runs "well below free-tier limits" — but adding patch generation is a real CI cost that doesn't fit the savings framing. Keep the three cards that are unambiguously true (Bandwidth, Wall time, User patience) so "What you save" stays honest. Move the mermaid flow diagram from the landing page to the GitHub Action page (it lives in the new "How an update flows" section just before "What it does"). The diagram shows the end-to-end CI-build to verified-binary flow that the Action implements, so the github-action.md page is a more honest home for it.
Tighten the Self-updating CLI tab and remove the "unpacked app" line from the Electron/Tauri tab: - Lump Node SEA and Fossilize into one bullet. Both are "embed a Node runtime (or V8 snapshot) with your app's prepended scripts" techniques; the two-bullet split read as overlap. - Rename "yao-pkg / @yao-pkg/pkg" to just "pkg". The fork name is detail for the GitHub page; the link itself goes to the canonical yao-pkg site. - Reword pkg description to match their home page copy: "Ship your Node.js project as one self-contained binary. No runtime install, no npm, just run." was the closest match to their own pitch. - Drop the "If your unpacked app is 80-200 MB" line from Electron/Tauri. Adds a footnote without changing the pitch. Add brand icons next to each tool name (simpleicons CDN, 20px, inline). Bun, Deno, Node.js, and pkg each get a colored icon. The icons render in the user's light/dark mode naturally via the recognizable brand colors.
BYK
force-pushed
the
docs/any-binary-rebrand-v3
branch
from
July 30, 2026 21:05
2545447 to
1fd5ef0
Compare
…al benchmarks, OG image Mixed-bag docs + tooling commit, each item independent: - Node 22.5 → 22.15.0 across all three surfaces (package.json engines, website installation page, contributing page). The 22.5 minimum was wrong: node:zlib's zstd support was actually added in v22.15.0 (April 2025), not v22.5. v22.15.0 is the first release that ships createZstdDecompress and zstdDecompressSync, which bspatch.ts uses extensively. Verified by Node v22.zlib docs "Added in: v22.15.0" and the V22 CHANGELOG (PR #52100, "add zstd support"). - FAQ "production-ready" copy: "for years" → "for months". The new CLI is recent — was confusingly overstating the track record. - FAQ "how is the project released": link to https://craft.sentry.dev before the existing .craft.yml reference. - FAQ: drop the bench/sentry-cli-bench.mjs reference. The script was removed in an earlier commit; the link was a 404 waiting to happen. - Contributing security disclosures: drop the security@withlore.ai email. Promotes the GitHub private security advisory as the only channel. The loreai address was a leftover from when the project lived at withlore.ai. - Architecture page: replace architecture-flow.svg with a Mermaid block. The SVG embedded through an <img> tag can't see page currentColor, so dark-mode rendering made the ink invisible (the same bug that felled the original flow.svg). Mermaid inherits host CSS variables so the diagram adapts to the active theme. Delete the now-unused SVG. - Apply page performance: replace the placebo benchmark numbers (883ms / 221ms / WRONG) with measurements from this machine (Intel Core i5-6500T, Node v24.16.0, 100 MB narrow-gap diff, 5×5 reps, 3 warm-up): 280ms / 145ms / 128ms. The doc also claimed the BigUint64Array SWAR was wrong (carry across byte lanes) — that claim is wrong. The 0x7f mask strips each byte's high bit before the add, so the masked add carries within each byte only. Verified exhaustively across 1.7M+ random pairs and worst-case carry patterns. The corrected doc explains why the trick is correct per byte lane, and notes we ship the 4-byte variant anyway (BigUint64 is ~14% faster but the BigInt allocations hurt generality on some embedded runtimes). - Social media previews: new integrations/social-assets.ts that generates a 1200×630 OG image at build time, content-hashed filename for cache-busting. astro.config.mjs calls generateAssetsEagerly() at config-load so the Starlight head array can reference the same hashed URL. Layout: logo top-left, headline "Patch only what moved", tagline "Up to 96% smaller updates for any binary.", CTA "binpatch.p.byk.im" in brand teal. Colors from the logo's dark variant. Adapted from the loreai integrations/favicon-assets.ts pattern. - .gitignore: ignore website/src/generated/ (manifest sidecar) and website/public/og-image-*.png (regenerated on every build).
The architecture page had the same placebo benchmark numbers as the apply page (220ms / 883ms / "WRONG") that I corrected on the apply page in the previous commit. Replace with the real numbers from the local benchmark (145ms / 280ms / 1.9× speedup). The "carry propagates across byte lanes" claim about BigUint64 was also wrong in the same way — the 0x7f mask preserves per-byte carry bounds at any lane width — but the conservative conclusion (ship the 4-byte variant for portability) is still correct. The architecture page now links to the apply page's performance section for the full benchmark table.
2 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reposition the binpatch landing page from CLI-only to "any binary" — Electron apps, CLIs, agents, game updaters. Lead with a measured download comparison instead of an abstract "90% savings" claim.
What changed
Homepage (
website/src/content/docs/index.mdx)Raw markdown endpoint (
website/src/pages/[...slug].md.ts)Each page now exposes its raw markdown source at
/<slug>.mdvia an Astro API endpoint. Useful for:"View as Markdown" link (
website/src/components/{MarkdownLink,Footer}.astro)Starlight Footer override adds a "View as Markdown" link next to the (would-be) EditLink. Link is base-path aware so PR previews keep working.
Light edits
architecture.md,faq.md,contributing.md,README.md— drop CLI-only framing.CHANGELOG.md— Unreleased entry.Verified
pnpm run buildclean (both default andDOCS_BASE_PATH=/_preview/pr-<n>/)hyperlink --sources src/content/docs dist-> 0 broken links across 1002 links from 123 filesnpm run typecheck+npm run testgreen (57 tests pass).mdendpoints return raw source withContent-Type: text/markdown/,/installation/, and/wire-contract/Preview
PR preview will deploy to
https://binpatch.p.byk.im/_preview/pr-<n>/once CI runs. Try:/_preview/pr-<n>/— homepage with the chart directly under the hero/_preview/pr-<n>/installation.md— raw markdown of any page/_preview/pr-<n>/size-comparison.svg— the chart