astro-knots
Mode

← All ship notes

fullstack-vc

v0.3.0 — Reading surfaces: a table of contents, syntax-highlighted code, image carousels, and the first steps off Astro DB

Two weeks spent making long-form content actually readable — a reading-position ToC on every guide, code blocks that read in the house palette, carousels for screenshot sequences — and one layout bug, found by measurement after three wrong guesses, that had been bleeding every page off the right edge the entire time.

Why Care?

v0.2.0 filled Recipes with content. This release is about whether that content is any good to read.

Long-form pieces here run to five sections and a dozen sub-headings, carry code you're meant to paste, and increasingly carry screenshots that only mean something in sequence. All three were being rendered as an undifferentiated column of text. This release gives each of them a real surface — and fixes a layout bug that had been quietly undermining all of them at narrow widths since long before any of this content existed.

What's New?

A table of contents on every guide. Persistent left rail on wide screens; a floating hamburger at laptop widths; on mobile, a top bar whose label names the heading you're currently reading. Selecting a heading jumps and collapses. It tracks your position in all three states, works with JavaScript disabled, and measures your site header at runtime rather than guessing at an offset.

Code blocks are syntax-highlighted for the first time, themed from the house palette rather than a stock Shiki theme, with a copy button on every block.

:::image-carousel — a new LFM directive for screenshot sequences, in four variants (filmstrip, stepper, peek, contact-sheet). Every variant works without JavaScript; scroll-snap does the work and the script only adds the live step readout and arrow keys.

Two new Recipes:

  • Orientation: Agent-Native Browsers — the third body for an agent, why the shape fits venture, and a flagship recipe for pulling a portfolio company's entire email history out as filed PDFs.

  • Orientation: Which Open Model for Which Job — coding, ETL, data analysis, on-brand imagery and speech-to-text across three months of open-weight releases.

Seven agentic browsers and MCP Market added to the tool registry.

The bug that was there the whole time

Every page on this site bled off the right edge at narrow widths. It reads as "responsive text wrapping stopped working," which sends you into the wrong file — three fixes were attempted and all three were wrong, because the symptom looks content-shaped so you keep fixing content.

Driving headless Chrome and printing the ancestor chain settled it in one pass: <main> was 637px inside a 500px viewport, while html, body and the flex wrapper were all correctly 500px and nothing inside <main> exceeded its content box. <main> was sizing itself.

BaseThemeLayout wraps the slot in a flex column, and callers pass mx-auto to centre the column. An auto cross-axis margin on a flex item cancels align-items: stretch, so <main> fell back to fit-content and grew to its max-content width. The class is correct; the flex context silently changes what it means.

One class fixed it. The transferable part — measure the cascade, don't reason about it — is written up with the full probe script as an astro-knots blueprint.

Under the Hood

  • @lossless-group/lfm 0.3.0 → 0.4.1. This is what made the ToC possible: remarkHeadingIds attaches an ordered outline at tree.data.headings. The site had been three minors behind and computing its own heading slugs — precisely the drift that plugin exists to end. Anchor churn on adoption: zero of 53 headings, verified before the renderer was touched.

  • First steps off Astro DB. Astro is deprecating it, and Astro 7 already broke astro db execute once. Stack writes now go to Turso directly over @libsql/client, with no @astrojs/db in the path. A four-phase retirement plan for the remaining 41 files is specced in context-v/issues/.

  • Frontmatter tolerance. The changelog collection now accepts every date spelling — legacy date and the editorial keys — so a tree-wide normalization sweep can no longer fail the build. Renderers resolve through one fallback chain.

  • Tables scroll inside their own frame instead of clipping. .ak-table-wrap had been emitted by the renderer since forever and never styled.

  • Seven identities reconciled in the participant roster, and the stack tooling revived after Astro 7 broke it.

Versioning

0.2.0 → 0.3.0 — a feature release. New reading surfaces (ToC, syntax highlighting, carousels), two new Recipes, and a dependency minor bump. No breaking changes for readers; the anchor-slug algorithm changed but moved zero published anchors.

The tracked migration risk from v0.2.0 is now being acted on rather than watched: @astrojs/db's deprecation has a written retirement plan and its first phase has shipped.