Fragments — Reusable Content Fragments

Fragments are reusable content files stored in instructions/. They eliminate duplication across instruction documents: a piece of information that is true in multiple contexts (the compiler layout, the test commands, the TagProcessor interface) lives in exactly one file and is inlined at compile time wherever it is needed.

Each fragment file carries structured frontmatter — id, type: fragment, tags — in addition to the standard title and description fields.

How to embed a fragment

Use a self-closing include tag anywhere in an .mdoc instruction file:

Every compiler change must pass all three checks before it is considered done. Run them in order — each builds on the previous.

### Step 1 — Type check and unit tests

```bash
# From starspec/
pnpm --filter @starspec/compiler build    # TypeScript compile — zero errors required
pnpm test                                 # agent-pass, public-pass, instructions-pass tests

All tests must pass. Do not proceed if any test fails.

Step 2 — End-to-end compile

# From starspec/
pnpm compile

Builds the compiler then runs it against content/. Inspect at least one generated file for the affected type:

Agent bundle: dist/bundles/{type}/{id}.toon — verify the new or changed field is present and correct
Public page: src/content/docs/{type}/{id}.md — verify the rendered section looks right
Aggregate page (if applicable): src/content/docs/{aggregate-name}.md

Step 3 — Regression check

# From starspec/
pnpm build

Confirm:

src/summary.json reports zero validation issues (or only pre-existing ones known before your change)
The Starlight site builds without errors

Step 4 — Automated E2E Gallery Verification

For changes affecting the Component Gallery or Screenshot Export, run the automated E2E agent. (These tests use the *.e2e.ts naming convention and are excluded from standard unit tests).

# From starspec/
pnpm test:e2e

This agent verifies:

All download buttons have deterministic IDs
Every component variant in the gallery can be successfully captured
Grouped component tabs are correctly handled
Both “Chrome” and “Clean” export modes function as expected

For interactive debugging of visual regressions:

pnpm test:e2e:ui

Do’s and Don’ts

Do:

Run all steps in order — each builds on the previous
Inspect at least one generated file for the affected type after end-to-end compile
Run the E2E agent when changes affect the Component Gallery or Screenshot Export

Don’t:

Skip a step or proceed if any test fails
Treat a passing TypeScript compile as sufficient without running end-to-end compile and site build

Definition of Done

TypeScript compile and unit tests pass
End-to-end compile produces correct output
Starlight site builds without errors

The `source` path is relative to `instructions/` and omits the `.mdoc` extension. At compile time, the instructions pass replaces the directive with the body of the referenced fragment file. Both the JSON bundle and the rendered Starlight page receive the fully-resolved content — there is no runtime indirection.

### The `frontmatter` attribute

| Value | Behaviour |
|---|---|
| `frontmatter=false` (default) | Frontmatter is stripped; only the body is inlined |
| `frontmatter=true` | The raw `---` frontmatter block is prepended to the inlined body |

Use `frontmatter=true` when the consuming context is an agent bundle and you need the fragment's `id`, `type`, or `tags` metadata alongside its prose. Do **not** use `frontmatter=true` in files that feed the public Starlight site — the injected `---` block is not valid inside an already-frontmatted MDX page.

Fragments can be placed inline within prose or under a section heading:

```markdoc
## Verification

Every compiler change must pass all three checks before it is considered done. Run them in order — each builds on the previous.

### Step 1 — Type check and unit tests

```bash
# From starspec/
pnpm --filter @starspec/compiler build    # TypeScript compile — zero errors required
pnpm test                                 # agent-pass, public-pass, instructions-pass tests