refrakt.md

Docs

Runes

Themes

Extend

Project

v0.16.1

Released May 31, 2026 · All releases

Changes

  • file-ref rune + shared preview="drawer" attribute on reference runes (SPEC-078, WORK-298..303).
  • New rune — file-ref. Path-based inline reference to a project file — third member of the Registry family beside xref (one entity) and expand (one entity inlined). Renders as an inline <a> to the file's canonical GitHub URL; optional preview="drawer" hoists a drawer containing the file's snippet plus a "View source on GitHub →" footer link. Sandbox shared with snippet (rejects absolute paths / traversal escapes / out-of-root symlinks).
  • xref preview="drawer" extension. The existing xref rune gains an optional preview="drawer" attribute that hoists a drawer containing the entity's expand-equivalent body. Same hoist mechanism as file-ref — one preview vocabulary across both reference runes. The drawer's chrome footer links to the entity's sourceUrl (or hides silently for URL-less entities). Inline link still resolves via the registry; clicking opens the drawer rather than navigating away.
  • Drawer footer slot + always-visible chrome. The drawer body splits on a top-level --- into two zones — body and footer — same shape {% card %} uses. In dialog mode, the drawer becomes a flex column: header and footer pin via flex: 0 0 auto, body scrolls via flex: 1 1 auto; overflow-y: auto, so a long entity body or file snippet scrolls inside the drawer with the footer staying one tap away.
  • Site config — repoUrl + repoBranch. Two new optional fields on SiteConfig for the canonical repo URL + git ref. file-ref uses them to build {repoUrl}/blob/{repoBranch}/{path}#L{N}-L{M} URLs; falls back to a no-href link with a build warning when repoUrl is absent.
  • Internal mechanism — drawer hoist pipeline. New hoistPreviewDrawers postProcess step collects hoist-drawer sentinels (emitted by file-ref preview="drawer" and xref preview="drawer") and materializes drawers at the page root. Source-specific HoistBuilder registrations keep the drawer pipeline ignorant of file paths / entity ids — reference runes register their own builders. Per-page dedup: multiple references to the same target collapse to one hoisted drawer.
  • SvelteKit plugin — configure lifecycle hook now runs on all plugins in the CSS-analysis pipeline pass (it was only running for the page-rendering virtual modules), so the plan plugin's unconditional scan registers entities for the CSS analyzer too. Also threads repoUrl/repoBranch from SiteConfig through the content loader chain.
  • Fence-level annotations: source, lines, linenumbers, highlight, label (SPEC-062, WORK-304).
  • The Markdoc fence node schema gains five optional attributes that work uniformly on hand-authored fences and snippet-derived ones:
  • source / lines — provenance metadata. Snippet's preprocess now writes these unprefixed names instead of the internal data-snippet-source / data-snippet-lines. The fence transform renders them as data-source / data-lines on the output <pre> and <code>.
  • linenumbers (boolean) — opt into a numbered gutter rendered in pure CSS via counter(). The start number is seeded from data-lines so the gutter reflects the file's real offsets.
  • highlight (range string) — emphasize specific lines without cropping. Shiki-style format ("74-78", "74-78,82,90-92"); file coordinates so it composes naturally with lines=. The highlight transform stamps data-line-status="highlight" on matching span.line rows post-Shiki.
  • label — per-fence tab label hint consumed by codegroup.
  • codegroup: tab labels now fall back through a precedence chain — labels= → per-fence label annotation → derived from source (basename + :lines) → prettified language name. The composition story propagates through fence attributes so codegroup doesn't care whether a panel came from {% snippet %} or a hand-authored fence.
  • diff: the header derives from each panel's source (matching paths collapse to one label; differing paths render as before → after). Each panel's gutter honors its own lines= start, so a diff between two slices of the same file shows real file line numbers per side. The highlight annotation is silently ignored inside diff — the add/remove channel is the primary line-level signal.
  • CSS: diff's [data-line-status] row template grows a third highlight value with a neutral tint (--rf-color-line-highlight) and primary-accent left rail. Snippet and codegroup share the same row primitive for the new highlight state. New tokens: --rf-color-line-highlight, --rf-color-line-highlight-rail, --rf-color-line-number.
  • Internal protocol changes (no user-facing API broken; only CSS targeting the previous internal data-* names needs updating):
  • The internal data-snippet-source / data-snippet-lines attributes emitted by the snippet rune are renamed to data-source / data-lines. These were documented as internal protocol when snippet shipped in v0.16 (SPEC-062).
  • Diff's per-line data-type attribute is renamed to data-line-status to share one CSS row primitive across snippet / codegroup / diff with the three states add | remove | highlight.
  • Diff's <pre> output now wraps its line spans in an inner <div data-name="rows"> (.rf-diff__rows) — mirrors the codeblock's <pre><code> shape so the row tint extends across horizontal scroll. Themes targeting .rf-diff__code > .rf-diff__line directly need to update the selector.