Snippet rune

Acceptance Criteria

Authoring + sandbox

• {% snippet path="..." /%} reads the file from project root and renders it as a syntax-highlighted code block
• Paths are resolved relative to the directory containing refrakt.config.json
• Absolute paths (/etc/passwd) are rejected with a build error
• Traversal paths (../../foo) escaping project root are rejected with a build error
• Symlinks pointing outside project root are rejected with a build error
• Missing files produce a build error naming the resolved path and the referencing source location
• Directory paths are rejected with a build error
• lines="10-25" extracts lines 10–25 inclusive
• lines="10-" extracts from line 10 to end of file
• lines="-20" extracts from line 1 to line 20
• lines="10" extracts just line 10
• Out-of-range end clamps to file length with a build warning
• Out-of-range start (entirely past EOF) is a build error
• Inverted range ("25-10") is a build error
• Malformed range string is a build error with the input echoed
• Language is inferred from file extension via the shared lang-map module from WORK-254
• lang= overrides inferred language
• {% snippet path=$file.path /%} works end-to-end (project-root frame matches the sandbox)

Standalone rendering

• title= renders as a caption in .rf-snippet__title on the standalone figure wrapper
• data-source-path is set on the standalone figure wrapper to the resolved path (relative to project root)
• data-lines is set on the standalone figure wrapper when lines= is used
• CSS in Lumina (packages/lumina/styles/runes/snippet.css) covers .rf-snippet* selectors

Composition (pre-resolve)

• PluginPipelineHooks gains a preprocess hook that runs per page on the parsed Markdoc AST before the schema-driven transform
• packages/content/src/site.ts runs registered preprocess hooks in plugin order between Markdoc.parse(...) and Markdoc.transform(...)
• Core's pipeline contributions (corePipelineHooks / createCorePipelineHooks) register a preprocess hook that walks the AST, finds every {% snippet %} tag node, resolves it (read file, slice lines=, infer language), and replaces it with a fence node carrying content, language, and data-snippet-source / data-snippet-title / data-snippet-lines attributes as appropriate
• By transform time, no {% snippet %} tags remain in the AST — only fence nodes (some "snippet-derived" distinguishable by data-snippet-* attributes)
• {% snippet %} inside {% codegroup %} renders as a tab containing the file's content; tab label uses title= or the inferred prettified language; no <figure> wrapper applied
• {% snippet %} inside {% diff %} (two snippets — before / after) renders as a diff with hunks computed from the two files' contents; no <figure> wrapper applied
• Mixed children — {% snippet %} and triple-backtick fences in the same {% codegroup %} or {% diff %} — work uniformly
• {% snippet %} at document level renders inside the <figure class="rf-snippet"> wrapper with optional <figcaption> from title=
• The post-transform wrap step suppresses the figure wrapper when the <pre data-snippet-source> is descended from a known fence-consuming container output (data-rune="code-group", data-rune="diff")
• The snippet rune schema's transform function is unreachable in normal operation; if it ever runs (e.g., core's preprocess hook not wired through), it throws a clear error pointing the user at the registration site
• Tests cover composition cases with real file fixtures: snippet at document level, two snippets in codegroup, two snippets in diff, mixed snippet + fence in codegroup
• Authoring docs cover the rune, sandbox rules, line range syntax, language inference table, and the composition cases

Site documentation (dogfooded)

• New rune-catalog page at site/content/runes/snippet.md following the established rune-doc pattern (frontmatter title + description, intro paragraph, sectioned examples with {% preview source=true %} blocks)
• Page is linked from site/content/runes/_layout.md in the "Code & Data" section of the sidebar nav (next to codegroup, compare, diff)
• Page includes a live example loading a real file from refrakt's own content/source tree — at minimum, one {% snippet %} block that resolves an actual file in the repo (a small, stable example like a token CSS snippet or a docs-plugin source file). The reader sees the actual file content rendered through the rune.
• Page includes a view-source-of-itself example: {% snippet path=$file.path lang="md" title="This page's source" /%} at the bottom of the doc, demonstrating the canonical view-source pattern recursively against the page itself.
• Page includes composition examples: {% codegroup %} with two {% snippet %} children, and {% diff %} with two {% snippet %} children, both loading real files from the repo. Reader sees the composition work end-to-end.
• Page documents the line-range syntax with a live example that slices a file (e.g., lines="1-10" on a meaningfully larger file).
• Page documents the language-inference table and the lang= override with a live example.
• Page documents the sandbox rules (project-root anchor, traversal rejection, symlink rejection) as a reference table; doesn't need to demonstrate failures live.