docs: Astro Starlight documentation site - #233
Conversation
Adds packages/docs, a Starlight site covering the library, and turns the two examples into in-page playgrounds. The playgrounds have no backend. scripts/build-playgrounds.mjs bundles each example's own Worker into the page alongside its own client and routes the client's fetch of the RPC path into the Worker's fetch handler, so the batching and round-trip counts the demos report are real while the site stays static. Source panes are read from the repo at build time, so a renamed file or a missing #region fails the build rather than rendering an empty tab.
Syncs the site with the two changes merged from main. URL joins the by-value type lists on What Can Be Passed, the API reference and the validation guide's coverage paragraph, and the protocol reference gains the ["url", href] expression. The validation guide gains a Schema evolution section for #227: which cross-version changes a validator accepts, and the distinction that matters once extra arguments are allowed -- they are dropped before the method runs, so an implementation still cannot read an argument no validator checked, while extra object properties are forwarded unvalidated. Also collapses the empty title bar Expressive Code leaves above terminal code blocks, and adds a wrangler config that serves dist/ from a Worker's asset store.
|
commit: |
|
This demo code is correct and well-designed — the pipelining example genuinely demonstrates the feature. The There's one subtle interaction worth noting: in the playground shim (build-playgrounds.mjs:159), I've reviewed the substantive code paths: the build-time bundler, the example Worker/API/server, the demo client, the Astro component, and the doc accuracy against the actual library. This PR is a documentation site plus example scaffolding. No changes touch
The documentation I spot-checked (security guide, api cheat sheet) matches the actual library behavior and signatures. The code is defensive and well-commented. LGTM |
Replaces the nautical theme and the logo with a dark-first palette: a near-black with a blue undertone, a deep saturated blue as the structural colour, and an electric azure for anything interactive. Cloudflare orange appears in three places and nowhere else -- the hero pulses, the primary call to action, and the current sidebar page -- because a fourth use is the point at which it stops meaning anything. Light mode is a second scheme rather than an inversion, and the chrome stays near-black in both. The landing page now runs a 3D network in WebGL. It is raw WebGL2 with no dependency: the page claims the library is under 10 kB with nothing behind it, and shipping a 3D framework to draw points and lines would undercut that in the first paint. The animation is the argument rather than decoration -- each pulse leaves a node, crosses several hops and returns along the same path, which is what pipelining actually buys you. Everything degrades to a designed state: the CSS gradient with no JavaScript or no WebGL2, a single still frame under prefers-reduced-motion, and a parked loop off-screen or on a hidden tab. GPU objects live in one struct that is rebuilt on webglcontextrestored, so a driver reset or a wake from sleep does not leave a dead rectangle. Additive blending cannot darken a pale page, so light mode composites the same geometry normally, as ink. Also fixes a horizontal overflow the new landing page exposed: cards holding a code block would not shrink below the widest unwrapped line, so the whole document scrolled sideways below about 1140px. And drops the explicit `sharp` dependency, which existed only to optimise the raster logo.
1 participant
A Starlight docs site under
packages/docs, and the twoexamples/turned into playgrounds embedded in their own pages.The playgrounds have no backend. Each example's real Worker is bundled into the page next to its real client, and the client's
fetchof the RPC path is routed into the Worker'sfetchhandler, so the batching and round-trip counts the demos report are genuine while the site stays static and deployable anywhere.Draft: the preview deploy currently sits behind an account-wide Cloudflare Access policy, so there is no public URL to link yet.