✨ feat: replace Show with structural If / Else control flow

.github/workflows/ci.yml

@@ -77,11 +77,13 @@ jobs:
  --component-dir packages/core/components \
  --raw
 
- # A built-in component resolves from the module graph rather than a
- # search path. Only the compiled binary proves it survives `deno compile`.
- # The directory target runs every built-in's colocated document at once.
- - name: Smoke test the built-in components with no search path
- run: ./dist/xmd test packages/core/src/components --raw
+ # A built-in resolves from the module graph rather than a search path.
+ # Only the compiled binary proves it survives `deno compile`. The
+ # directory target discovers every colocated document beneath core's
+ # source at once — the built-in components under `components/`, and the
+ # structural directives, which resolve no file at all.
+ - name: Smoke test the built-ins with no search path
+ run: ./dist/xmd test packages/core/src --raw
 
  # The guide documents this command and its output; running it keeps the
  # value-root contract executable rather than described.

README.md

@@ -123,8 +123,26 @@ executable.md treats the root document like a component:
 - JSX tags with capitalized names become component invocations.
 - `<Content />` acts as a slot for child content.
 - Text segments support `{meta.key}` and `{props.key}` interpolation.
+- `<If condition={...}>`, with an optional `<Else>` block, is a structural directive rather than a component.
 - Markdown is healed at execution boundaries with `remend` so formatting does not bleed across components or executable blocks.
 
+## Control flow
+
+`<If>` expands one branch and only one. `condition` must be a boolean — there is no truthy or falsy coercion — and the branch that is not selected never expands, so nothing in it imports a component, runs a block, or creates a binding.
+
+```md
+<If condition={hasFailures}>
+## Test failures
+
+<FailureReport />
+<Else>
+All checks passed.
+</Else>
+</If>
+```
+
+`<Else>` is optional and, when present, is the final substantive child of its `<If>`. See the [control-flow guide](https://executable.md/docs/control-flow) for nesting and binding examples.
+
 ## Executable code blocks
 
 The first word in a fence info string is the language. The remaining words form a modifier chain. Standard renderers only read the first word, so the modifiers stay invisible everywhere else.

packages/core/src/If.test.md

@@ -0,0 +1,96 @@
+# If
+
+`<If>` chooses one branch of a document and expands only that branch. It is a
+directive the expansion engine handles itself, so there is no `If.md` to import
+and nothing to install before using it.
+
+A true condition renders the content it guards.
+
+<Test name="A true condition renders its children">
+<Capture as="rendered"><If condition={true}>selected</If></Capture>
+<AssertEquals actual={rendered} expected={"selected"} />
+</Test>
+
+A false condition with nothing else to say renders nothing at all — not an
+empty region, not a placeholder.
+
+<Test name="A false condition without Else renders nothing">
+<Capture as="empty"><If condition={false}>hidden</If></Capture>
+<AssertEquals actual={empty} expected={""} />
+</Test>
+
+`<Else>` supplies the alternative. Whichever branch the condition selects, the
+other one contributes nothing to the output.
+
+<Test name="A false condition selects the Else branch">
+<Capture as="otherwise"><If condition={false}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={otherwise} expected={"otherwise"} />
+</Test>
+
+<Test name="A true condition selects the leading branch">
+<Capture as="then"><If condition={true}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={then} expected={"then"} />
+</Test>
+
+The condition is an ordinary expression, so it reads whatever the document has
+already bound. Here `<Parse>` turns a JSON answer into a value, and `<If>`
+branches on one of its fields.
+
+<Test name="The condition reads a binding the document already made">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="verdict">
+{ "passed": true }
+</Parse>
+<Capture as="report"><If condition={verdict.passed}>approved<Else>needs revision</Else></If></Capture>
+<AssertEquals actual={report} expected={"approved"} />
+</Test>
+
+<Test name="The condition may compute a boolean from that binding">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="failing">
+{ "passed": false }
+</Parse>
+<Capture as="failingReport"><If condition={!failing.passed}>needs revision<Else>approved</Else></If></Capture>
+<AssertEquals actual={failingReport} expected={"needs revision"} />
+</Test>
+
+The selected branch is spliced in where the directive was written, so content
+around it keeps its order.
+
+<Test name="Content around the selected branch keeps its order">
+<Capture as="ordered">before|<If condition={true}>mid<Else>alt</Else></If>|after</Capture>
+<AssertEquals actual={ordered} expected={"before|mid|after"} />
+</Test>
+
+`<If>` opens no scope of its own. A binding the selected branch creates behaves
+like one written inline, so it is still readable after `</If>`.
+
+<Test name="A capture from the selected branch survives the block">
+<If condition={true}><Capture as="picked">chosen</Capture></If>
+<AssertEquals actual={picked} expected={"chosen"} />
+</Test>
+
+The branch that is not selected never expands, so it binds nothing. A reference
+to a name it would have created stays unresolved, exactly as a reference to a
+name no one ever wrote.
+
+<Test name="The unselected branch creates no binding">
+<If condition={false}><Capture as="skipped">never</Capture><Else>alternative</Else></If>
+<Capture as="probe">[{skipped}]</Capture>
+<AssertEquals actual={probe} expected={"[{skipped}]"} />
+</Test>
+
+Conditionals nest, and each one selects on its own.
+
+<Test name="Nested conditionals select independently">
+<Capture as="nested"><If condition={true}>outer:<If condition={false}>inner<Else>alt</Else></If>:end<Else>skipped</Else></If></Capture>
+<AssertEquals actual={nested} expected={"outer:alt:end"} />
+</Test>
+
+"Never expands" is stronger than "renders nothing". An assertion placed in the
+unselected branch would fail this document if it ran — the test passes only
+because that branch is never reached.
+
+<Test name="The unselected branch never runs">
+<If condition={true}>selected<Else>
+<AssertEquals actual={"the unselected branch ran"} expected={"it must never run"} />
+</Else></If>
+</Test>

.github/workflows/ci.yml

@@ -77,11 +77,13 @@ jobs:
  --component-dir packages/core/components \
  --raw
 
- # A built-in component resolves from the module graph rather than a
- # search path. Only the compiled binary proves it survives `deno compile`.
- # The directory target runs every built-in's colocated document at once.
- - name: Smoke test the built-in components with no search path
- run: ./dist/xmd test packages/core/src/components --raw
+ # A built-in resolves from the module graph rather than a search path.
+ # Only the compiled binary proves it survives `deno compile`. The
+ # directory target discovers every colocated document beneath core's
+ # source at once — the built-in components under `components/`, and the
+ # structural directives, which resolve no file at all.
+ - name: Smoke test the built-ins with no search path
+ run: ./dist/xmd test packages/core/src --raw
 
  # The guide documents this command and its output; running it keeps the
  # value-root contract executable rather than described.

README.md

@@ -123,8 +123,26 @@ executable.md treats the root document like a component:
 - JSX tags with capitalized names become component invocations.
 - `<Content />` acts as a slot for child content.
 - Text segments support `{meta.key}` and `{props.key}` interpolation.
+- `<If condition={...}>`, with an optional `<Else>` block, is a structural directive rather than a component.
 - Markdown is healed at execution boundaries with `remend` so formatting does not bleed across components or executable blocks.
 
+## Control flow
+
+`<If>` expands one branch and only one. `condition` must be a boolean — there is no truthy or falsy coercion — and the branch that is not selected never expands, so nothing in it imports a component, runs a block, or creates a binding.
+
+```md
+<If condition={hasFailures}>
+## Test failures
+
+<FailureReport />
+<Else>
+All checks passed.
+</Else>
+</If>
+```
+
+`<Else>` is optional and, when present, is the final substantive child of its `<If>`. See the [control-flow guide](https://executable.md/docs/control-flow) for nesting and binding examples.
+
 ## Executable code blocks
 
 The first word in a fence info string is the language. The remaining words form a modifier chain. Standard renderers only read the first word, so the modifiers stay invisible everywhere else.

packages/core/src/If.test.md

@@ -0,0 +1,96 @@
+# If
+
+`<If>` chooses one branch of a document and expands only that branch. It is a
+directive the expansion engine handles itself, so there is no `If.md` to import
+and nothing to install before using it.
+
+A true condition renders the content it guards.
+
+<Test name="A true condition renders its children">
+<Capture as="rendered"><If condition={true}>selected</If></Capture>
+<AssertEquals actual={rendered} expected={"selected"} />
+</Test>
+
+A false condition with nothing else to say renders nothing at all — not an
+empty region, not a placeholder.
+
+<Test name="A false condition without Else renders nothing">
+<Capture as="empty"><If condition={false}>hidden</If></Capture>
+<AssertEquals actual={empty} expected={""} />
+</Test>
+
+`<Else>` supplies the alternative. Whichever branch the condition selects, the
+other one contributes nothing to the output.
+
+<Test name="A false condition selects the Else branch">
+<Capture as="otherwise"><If condition={false}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={otherwise} expected={"otherwise"} />
+</Test>
+
+<Test name="A true condition selects the leading branch">
+<Capture as="then"><If condition={true}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={then} expected={"then"} />
+</Test>
+
+The condition is an ordinary expression, so it reads whatever the document has
+already bound. Here `<Parse>` turns a JSON answer into a value, and `<If>`
+branches on one of its fields.
+
+<Test name="The condition reads a binding the document already made">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="verdict">
+{ "passed": true }
+</Parse>
+<Capture as="report"><If condition={verdict.passed}>approved<Else>needs revision</Else></If></Capture>
+<AssertEquals actual={report} expected={"approved"} />
+</Test>
+
+<Test name="The condition may compute a boolean from that binding">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="failing">
+{ "passed": false }
+</Parse>
+<Capture as="failingReport"><If condition={!failing.passed}>needs revision<Else>approved</Else></If></Capture>
+<AssertEquals actual={failingReport} expected={"needs revision"} />
+</Test>
+
+The selected branch is spliced in where the directive was written, so content
+around it keeps its order.
+
+<Test name="Content around the selected branch keeps its order">
+<Capture as="ordered">before|<If condition={true}>mid<Else>alt</Else></If>|after</Capture>
+<AssertEquals actual={ordered} expected={"before|mid|after"} />
+</Test>
+
+`<If>` opens no scope of its own. A binding the selected branch creates behaves
+like one written inline, so it is still readable after `</If>`.
+
+<Test name="A capture from the selected branch survives the block">
+<If condition={true}><Capture as="picked">chosen</Capture></If>
+<AssertEquals actual={picked} expected={"chosen"} />
+</Test>
+
+The branch that is not selected never expands, so it binds nothing. A reference
+to a name it would have created stays unresolved, exactly as a reference to a
+name no one ever wrote.
+
+<Test name="The unselected branch creates no binding">
+<If condition={false}><Capture as="skipped">never</Capture><Else>alternative</Else></If>
+<Capture as="probe">[{skipped}]</Capture>
+<AssertEquals actual={probe} expected={"[{skipped}]"} />
+</Test>
+
+Conditionals nest, and each one selects on its own.
+
+<Test name="Nested conditionals select independently">
+<Capture as="nested"><If condition={true}>outer:<If condition={false}>inner<Else>alt</Else></If>:end<Else>skipped</Else></If></Capture>
+<AssertEquals actual={nested} expected={"outer:alt:end"} />
+</Test>
+
+"Never expands" is stronger than "renders nothing". An assertion placed in the
+unselected branch would fail this document if it ran — the test passes only
+because that branch is never reached.
+
+<Test name="The unselected branch never runs">
+<If condition={true}>selected<Else>
+<AssertEquals actual={"the unselected branch ran"} expected={"it must never run"} />
+</Else></If>
+</Test>

.github/workflows/ci.yml

@@ -77,11 +77,13 @@ jobs:
  --component-dir packages/core/components \
  --raw
 
- # A built-in component resolves from the module graph rather than a
- # search path. Only the compiled binary proves it survives `deno compile`.
- # The directory target runs every built-in's colocated document at once.
- - name: Smoke test the built-in components with no search path
- run: ./dist/xmd test packages/core/src/components --raw
+ # A built-in resolves from the module graph rather than a search path.
+ # Only the compiled binary proves it survives `deno compile`. The
+ # directory target discovers every colocated document beneath core's
+ # source at once — the built-in components under `components/`, and the
+ # structural directives, which resolve no file at all.
+ - name: Smoke test the built-ins with no search path
+ run: ./dist/xmd test packages/core/src --raw
 
  # The guide documents this command and its output; running it keeps the
  # value-root contract executable rather than described.

README.md

@@ -123,8 +123,26 @@ executable.md treats the root document like a component:
 - JSX tags with capitalized names become component invocations.
 - `<Content />` acts as a slot for child content.
 - Text segments support `{meta.key}` and `{props.key}` interpolation.
+- `<If condition={...}>`, with an optional `<Else>` block, is a structural directive rather than a component.
 - Markdown is healed at execution boundaries with `remend` so formatting does not bleed across components or executable blocks.
 
+## Control flow
+
+`<If>` expands one branch and only one. `condition` must be a boolean — there is no truthy or falsy coercion — and the branch that is not selected never expands, so nothing in it imports a component, runs a block, or creates a binding.
+
+```md
+<If condition={hasFailures}>
+## Test failures
+
+<FailureReport />
+<Else>
+All checks passed.
+</Else>
+</If>
+```
+
+`<Else>` is optional and, when present, is the final substantive child of its `<If>`. See the [control-flow guide](https://executable.md/docs/control-flow) for nesting and binding examples.
+
 ## Executable code blocks
 
 The first word in a fence info string is the language. The remaining words form a modifier chain. Standard renderers only read the first word, so the modifiers stay invisible everywhere else.

packages/core/src/If.test.md

@@ -0,0 +1,96 @@
+# If
+
+`<If>` chooses one branch of a document and expands only that branch. It is a
+directive the expansion engine handles itself, so there is no `If.md` to import
+and nothing to install before using it.
+
+A true condition renders the content it guards.
+
+<Test name="A true condition renders its children">
+<Capture as="rendered"><If condition={true}>selected</If></Capture>
+<AssertEquals actual={rendered} expected={"selected"} />
+</Test>
+
+A false condition with nothing else to say renders nothing at all — not an
+empty region, not a placeholder.
+
+<Test name="A false condition without Else renders nothing">
+<Capture as="empty"><If condition={false}>hidden</If></Capture>
+<AssertEquals actual={empty} expected={""} />
+</Test>
+
+`<Else>` supplies the alternative. Whichever branch the condition selects, the
+other one contributes nothing to the output.
+
+<Test name="A false condition selects the Else branch">
+<Capture as="otherwise"><If condition={false}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={otherwise} expected={"otherwise"} />
+</Test>
+
+<Test name="A true condition selects the leading branch">
+<Capture as="then"><If condition={true}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={then} expected={"then"} />
+</Test>
+
+The condition is an ordinary expression, so it reads whatever the document has
+already bound. Here `<Parse>` turns a JSON answer into a value, and `<If>`
+branches on one of its fields.
+
+<Test name="The condition reads a binding the document already made">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="verdict">
+{ "passed": true }
+</Parse>
+<Capture as="report"><If condition={verdict.passed}>approved<Else>needs revision</Else></If></Capture>
+<AssertEquals actual={report} expected={"approved"} />
+</Test>
+
+<Test name="The condition may compute a boolean from that binding">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="failing">
+{ "passed": false }
+</Parse>
+<Capture as="failingReport"><If condition={!failing.passed}>needs revision<Else>approved</Else></If></Capture>
+<AssertEquals actual={failingReport} expected={"needs revision"} />
+</Test>
+
+The selected branch is spliced in where the directive was written, so content
+around it keeps its order.
+
+<Test name="Content around the selected branch keeps its order">
+<Capture as="ordered">before|<If condition={true}>mid<Else>alt</Else></If>|after</Capture>
+<AssertEquals actual={ordered} expected={"before|mid|after"} />
+</Test>
+
+`<If>` opens no scope of its own. A binding the selected branch creates behaves
+like one written inline, so it is still readable after `</If>`.
+
+<Test name="A capture from the selected branch survives the block">
+<If condition={true}><Capture as="picked">chosen</Capture></If>
+<AssertEquals actual={picked} expected={"chosen"} />
+</Test>
+
+The branch that is not selected never expands, so it binds nothing. A reference
+to a name it would have created stays unresolved, exactly as a reference to a
+name no one ever wrote.
+
+<Test name="The unselected branch creates no binding">
+<If condition={false}><Capture as="skipped">never</Capture><Else>alternative</Else></If>
+<Capture as="probe">[{skipped}]</Capture>
+<AssertEquals actual={probe} expected={"[{skipped}]"} />
+</Test>
+
+Conditionals nest, and each one selects on its own.
+
+<Test name="Nested conditionals select independently">
+<Capture as="nested"><If condition={true}>outer:<If condition={false}>inner<Else>alt</Else></If>:end<Else>skipped</Else></If></Capture>
+<AssertEquals actual={nested} expected={"outer:alt:end"} />
+</Test>
+
+"Never expands" is stronger than "renders nothing". An assertion placed in the
+unselected branch would fail this document if it ran — the test passes only
+because that branch is never reached.
+
+<Test name="The unselected branch never runs">
+<If condition={true}>selected<Else>
+<AssertEquals actual={"the unselected branch ran"} expected={"it must never run"} />
+</Else></If>
+</Test>

.github/workflows/ci.yml

@@ -77,11 +77,13 @@ jobs:
  --component-dir packages/core/components \
  --raw
 
- # A built-in component resolves from the module graph rather than a
- # search path. Only the compiled binary proves it survives `deno compile`.
- # The directory target runs every built-in's colocated document at once.
- - name: Smoke test the built-in components with no search path
- run: ./dist/xmd test packages/core/src/components --raw
+ # A built-in resolves from the module graph rather than a search path.
+ # Only the compiled binary proves it survives `deno compile`. The
+ # directory target discovers every colocated document beneath core's
+ # source at once — the built-in components under `components/`, and the
+ # structural directives, which resolve no file at all.
+ - name: Smoke test the built-ins with no search path
+ run: ./dist/xmd test packages/core/src --raw
 
  # The guide documents this command and its output; running it keeps the
  # value-root contract executable rather than described.

README.md

@@ -123,8 +123,26 @@ executable.md treats the root document like a component:
 - JSX tags with capitalized names become component invocations.
 - `<Content />` acts as a slot for child content.
 - Text segments support `{meta.key}` and `{props.key}` interpolation.
+- `<If condition={...}>`, with an optional `<Else>` block, is a structural directive rather than a component.
 - Markdown is healed at execution boundaries with `remend` so formatting does not bleed across components or executable blocks.
 
+## Control flow
+
+`<If>` expands one branch and only one. `condition` must be a boolean — there is no truthy or falsy coercion — and the branch that is not selected never expands, so nothing in it imports a component, runs a block, or creates a binding.
+
+```md
+<If condition={hasFailures}>
+## Test failures
+
+<FailureReport />
+<Else>
+All checks passed.
+</Else>
+</If>
+```
+
+`<Else>` is optional and, when present, is the final substantive child of its `<If>`. See the [control-flow guide](https://executable.md/docs/control-flow) for nesting and binding examples.
+
 ## Executable code blocks
 
 The first word in a fence info string is the language. The remaining words form a modifier chain. Standard renderers only read the first word, so the modifiers stay invisible everywhere else.

packages/core/src/If.test.md

@@ -0,0 +1,96 @@
+# If
+
+`<If>` chooses one branch of a document and expands only that branch. It is a
+directive the expansion engine handles itself, so there is no `If.md` to import
+and nothing to install before using it.
+
+A true condition renders the content it guards.
+
+<Test name="A true condition renders its children">
+<Capture as="rendered"><If condition={true}>selected</If></Capture>
+<AssertEquals actual={rendered} expected={"selected"} />
+</Test>
+
+A false condition with nothing else to say renders nothing at all — not an
+empty region, not a placeholder.
+
+<Test name="A false condition without Else renders nothing">
+<Capture as="empty"><If condition={false}>hidden</If></Capture>
+<AssertEquals actual={empty} expected={""} />
+</Test>
+
+`<Else>` supplies the alternative. Whichever branch the condition selects, the
+other one contributes nothing to the output.
+
+<Test name="A false condition selects the Else branch">
+<Capture as="otherwise"><If condition={false}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={otherwise} expected={"otherwise"} />
+</Test>
+
+<Test name="A true condition selects the leading branch">
+<Capture as="then"><If condition={true}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={then} expected={"then"} />
+</Test>
+
+The condition is an ordinary expression, so it reads whatever the document has
+already bound. Here `<Parse>` turns a JSON answer into a value, and `<If>`
+branches on one of its fields.
+
+<Test name="The condition reads a binding the document already made">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="verdict">
+{ "passed": true }
+</Parse>
+<Capture as="report"><If condition={verdict.passed}>approved<Else>needs revision</Else></If></Capture>
+<AssertEquals actual={report} expected={"approved"} />
+</Test>
+
+<Test name="The condition may compute a boolean from that binding">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="failing">
+{ "passed": false }
+</Parse>
+<Capture as="failingReport"><If condition={!failing.passed}>needs revision<Else>approved</Else></If></Capture>
+<AssertEquals actual={failingReport} expected={"needs revision"} />
+</Test>
+
+The selected branch is spliced in where the directive was written, so content
+around it keeps its order.
+
+<Test name="Content around the selected branch keeps its order">
+<Capture as="ordered">before|<If condition={true}>mid<Else>alt</Else></If>|after</Capture>
+<AssertEquals actual={ordered} expected={"before|mid|after"} />
+</Test>
+
+`<If>` opens no scope of its own. A binding the selected branch creates behaves
+like one written inline, so it is still readable after `</If>`.
+
+<Test name="A capture from the selected branch survives the block">
+<If condition={true}><Capture as="picked">chosen</Capture></If>
+<AssertEquals actual={picked} expected={"chosen"} />
+</Test>
+
+The branch that is not selected never expands, so it binds nothing. A reference
+to a name it would have created stays unresolved, exactly as a reference to a
+name no one ever wrote.
+
+<Test name="The unselected branch creates no binding">
+<If condition={false}><Capture as="skipped">never</Capture><Else>alternative</Else></If>
+<Capture as="probe">[{skipped}]</Capture>
+<AssertEquals actual={probe} expected={"[{skipped}]"} />
+</Test>
+
+Conditionals nest, and each one selects on its own.
+
+<Test name="Nested conditionals select independently">
+<Capture as="nested"><If condition={true}>outer:<If condition={false}>inner<Else>alt</Else></If>:end<Else>skipped</Else></If></Capture>
+<AssertEquals actual={nested} expected={"outer:alt:end"} />
+</Test>
+
+"Never expands" is stronger than "renders nothing". An assertion placed in the
+unselected branch would fail this document if it ran — the test passes only
+because that branch is never reached.
+
+<Test name="The unselected branch never runs">
+<If condition={true}>selected<Else>
+<AssertEquals actual={"the unselected branch ran"} expected={"it must never run"} />
+</Else></If>
+</Test>

.github/workflows/ci.yml

@@ -77,11 +77,13 @@ jobs:
  --component-dir packages/core/components \
  --raw
 
- # A built-in component resolves from the module graph rather than a
- # search path. Only the compiled binary proves it survives `deno compile`.
- # The directory target runs every built-in's colocated document at once.
- - name: Smoke test the built-in components with no search path
- run: ./dist/xmd test packages/core/src/components --raw
+ # A built-in resolves from the module graph rather than a search path.
+ # Only the compiled binary proves it survives `deno compile`. The
+ # directory target discovers every colocated document beneath core's
+ # source at once — the built-in components under `components/`, and the
+ # structural directives, which resolve no file at all.
+ - name: Smoke test the built-ins with no search path
+ run: ./dist/xmd test packages/core/src --raw
 
  # The guide documents this command and its output; running it keeps the
  # value-root contract executable rather than described.

README.md

@@ -123,8 +123,26 @@ executable.md treats the root document like a component:
 - JSX tags with capitalized names become component invocations.
 - `<Content />` acts as a slot for child content.
 - Text segments support `{meta.key}` and `{props.key}` interpolation.
+- `<If condition={...}>`, with an optional `<Else>` block, is a structural directive rather than a component.
 - Markdown is healed at execution boundaries with `remend` so formatting does not bleed across components or executable blocks.
 
+## Control flow
+
+`<If>` expands one branch and only one. `condition` must be a boolean — there is no truthy or falsy coercion — and the branch that is not selected never expands, so nothing in it imports a component, runs a block, or creates a binding.
+
+```md
+<If condition={hasFailures}>
+## Test failures
+
+<FailureReport />
+<Else>
+All checks passed.
+</Else>
+</If>
+```
+
+`<Else>` is optional and, when present, is the final substantive child of its `<If>`. See the [control-flow guide](https://executable.md/docs/control-flow) for nesting and binding examples.
+
 ## Executable code blocks
 
 The first word in a fence info string is the language. The remaining words form a modifier chain. Standard renderers only read the first word, so the modifiers stay invisible everywhere else.

packages/core/src/If.test.md

@@ -0,0 +1,96 @@
+# If
+
+`<If>` chooses one branch of a document and expands only that branch. It is a
+directive the expansion engine handles itself, so there is no `If.md` to import
+and nothing to install before using it.
+
+A true condition renders the content it guards.
+
+<Test name="A true condition renders its children">
+<Capture as="rendered"><If condition={true}>selected</If></Capture>
+<AssertEquals actual={rendered} expected={"selected"} />
+</Test>
+
+A false condition with nothing else to say renders nothing at all — not an
+empty region, not a placeholder.
+
+<Test name="A false condition without Else renders nothing">
+<Capture as="empty"><If condition={false}>hidden</If></Capture>
+<AssertEquals actual={empty} expected={""} />
+</Test>
+
+`<Else>` supplies the alternative. Whichever branch the condition selects, the
+other one contributes nothing to the output.
+
+<Test name="A false condition selects the Else branch">
+<Capture as="otherwise"><If condition={false}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={otherwise} expected={"otherwise"} />
+</Test>
+
+<Test name="A true condition selects the leading branch">
+<Capture as="then"><If condition={true}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={then} expected={"then"} />
+</Test>
+
+The condition is an ordinary expression, so it reads whatever the document has
+already bound. Here `<Parse>` turns a JSON answer into a value, and `<If>`
+branches on one of its fields.
+
+<Test name="The condition reads a binding the document already made">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="verdict">
+{ "passed": true }
+</Parse>
+<Capture as="report"><If condition={verdict.passed}>approved<Else>needs revision</Else></If></Capture>
+<AssertEquals actual={report} expected={"approved"} />
+</Test>
+
+<Test name="The condition may compute a boolean from that binding">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="failing">
+{ "passed": false }
+</Parse>
+<Capture as="failingReport"><If condition={!failing.passed}>needs revision<Else>approved</Else></If></Capture>
+<AssertEquals actual={failingReport} expected={"needs revision"} />
+</Test>
+
+The selected branch is spliced in where the directive was written, so content
+around it keeps its order.
+
+<Test name="Content around the selected branch keeps its order">
+<Capture as="ordered">before|<If condition={true}>mid<Else>alt</Else></If>|after</Capture>
+<AssertEquals actual={ordered} expected={"before|mid|after"} />
+</Test>
+
+`<If>` opens no scope of its own. A binding the selected branch creates behaves
+like one written inline, so it is still readable after `</If>`.
+
+<Test name="A capture from the selected branch survives the block">
+<If condition={true}><Capture as="picked">chosen</Capture></If>
+<AssertEquals actual={picked} expected={"chosen"} />
+</Test>
+
+The branch that is not selected never expands, so it binds nothing. A reference
+to a name it would have created stays unresolved, exactly as a reference to a
+name no one ever wrote.
+
+<Test name="The unselected branch creates no binding">
+<If condition={false}><Capture as="skipped">never</Capture><Else>alternative</Else></If>
+<Capture as="probe">[{skipped}]</Capture>
+<AssertEquals actual={probe} expected={"[{skipped}]"} />
+</Test>
+
+Conditionals nest, and each one selects on its own.
+
+<Test name="Nested conditionals select independently">
+<Capture as="nested"><If condition={true}>outer:<If condition={false}>inner<Else>alt</Else></If>:end<Else>skipped</Else></If></Capture>
+<AssertEquals actual={nested} expected={"outer:alt:end"} />
+</Test>
+
+"Never expands" is stronger than "renders nothing". An assertion placed in the
+unselected branch would fail this document if it ran — the test passes only
+because that branch is never reached.
+
+<Test name="The unselected branch never runs">
+<If condition={true}>selected<Else>
+<AssertEquals actual={"the unselected branch ran"} expected={"it must never run"} />
+</Else></If>
+</Test>

.github/workflows/ci.yml

@@ -77,11 +77,13 @@ jobs:
  --component-dir packages/core/components \
  --raw
 
- # A built-in component resolves from the module graph rather than a
- # search path. Only the compiled binary proves it survives `deno compile`.
- # The directory target runs every built-in's colocated document at once.
- - name: Smoke test the built-in components with no search path
- run: ./dist/xmd test packages/core/src/components --raw
+ # A built-in resolves from the module graph rather than a search path.
+ # Only the compiled binary proves it survives `deno compile`. The
+ # directory target discovers every colocated document beneath core's
+ # source at once — the built-in components under `components/`, and the
+ # structural directives, which resolve no file at all.
+ - name: Smoke test the built-ins with no search path
+ run: ./dist/xmd test packages/core/src --raw
 
  # The guide documents this command and its output; running it keeps the
  # value-root contract executable rather than described.

README.md

@@ -123,8 +123,26 @@ executable.md treats the root document like a component:
 - JSX tags with capitalized names become component invocations.
 - `<Content />` acts as a slot for child content.
 - Text segments support `{meta.key}` and `{props.key}` interpolation.
+- `<If condition={...}>`, with an optional `<Else>` block, is a structural directive rather than a component.
 - Markdown is healed at execution boundaries with `remend` so formatting does not bleed across components or executable blocks.
 
+## Control flow
+
+`<If>` expands one branch and only one. `condition` must be a boolean — there is no truthy or falsy coercion — and the branch that is not selected never expands, so nothing in it imports a component, runs a block, or creates a binding.
+
+```md
+<If condition={hasFailures}>
+## Test failures
+
+<FailureReport />
+<Else>
+All checks passed.
+</Else>
+</If>
+```
+
+`<Else>` is optional and, when present, is the final substantive child of its `<If>`. See the [control-flow guide](https://executable.md/docs/control-flow) for nesting and binding examples.
+
 ## Executable code blocks
 
 The first word in a fence info string is the language. The remaining words form a modifier chain. Standard renderers only read the first word, so the modifiers stay invisible everywhere else.

packages/core/src/If.test.md

@@ -0,0 +1,96 @@
+# If
+
+`<If>` chooses one branch of a document and expands only that branch. It is a
+directive the expansion engine handles itself, so there is no `If.md` to import
+and nothing to install before using it.
+
+A true condition renders the content it guards.
+
+<Test name="A true condition renders its children">
+<Capture as="rendered"><If condition={true}>selected</If></Capture>
+<AssertEquals actual={rendered} expected={"selected"} />
+</Test>
+
+A false condition with nothing else to say renders nothing at all — not an
+empty region, not a placeholder.
+
+<Test name="A false condition without Else renders nothing">
+<Capture as="empty"><If condition={false}>hidden</If></Capture>
+<AssertEquals actual={empty} expected={""} />
+</Test>
+
+`<Else>` supplies the alternative. Whichever branch the condition selects, the
+other one contributes nothing to the output.
+
+<Test name="A false condition selects the Else branch">
+<Capture as="otherwise"><If condition={false}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={otherwise} expected={"otherwise"} />
+</Test>
+
+<Test name="A true condition selects the leading branch">
+<Capture as="then"><If condition={true}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={then} expected={"then"} />
+</Test>
+
+The condition is an ordinary expression, so it reads whatever the document has
+already bound. Here `<Parse>` turns a JSON answer into a value, and `<If>`
+branches on one of its fields.
+
+<Test name="The condition reads a binding the document already made">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="verdict">
+{ "passed": true }
+</Parse>
+<Capture as="report"><If condition={verdict.passed}>approved<Else>needs revision</Else></If></Capture>
+<AssertEquals actual={report} expected={"approved"} />
+</Test>
+
+<Test name="The condition may compute a boolean from that binding">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="failing">
+{ "passed": false }
+</Parse>
+<Capture as="failingReport"><If condition={!failing.passed}>needs revision<Else>approved</Else></If></Capture>
+<AssertEquals actual={failingReport} expected={"needs revision"} />
+</Test>
+
+The selected branch is spliced in where the directive was written, so content
+around it keeps its order.
+
+<Test name="Content around the selected branch keeps its order">
+<Capture as="ordered">before|<If condition={true}>mid<Else>alt</Else></If>|after</Capture>
+<AssertEquals actual={ordered} expected={"before|mid|after"} />
+</Test>
+
+`<If>` opens no scope of its own. A binding the selected branch creates behaves
+like one written inline, so it is still readable after `</If>`.
+
+<Test name="A capture from the selected branch survives the block">
+<If condition={true}><Capture as="picked">chosen</Capture></If>
+<AssertEquals actual={picked} expected={"chosen"} />
+</Test>
+
+The branch that is not selected never expands, so it binds nothing. A reference
+to a name it would have created stays unresolved, exactly as a reference to a
+name no one ever wrote.
+
+<Test name="The unselected branch creates no binding">
+<If condition={false}><Capture as="skipped">never</Capture><Else>alternative</Else></If>
+<Capture as="probe">[{skipped}]</Capture>
+<AssertEquals actual={probe} expected={"[{skipped}]"} />
+</Test>
+
+Conditionals nest, and each one selects on its own.
+
+<Test name="Nested conditionals select independently">
+<Capture as="nested"><If condition={true}>outer:<If condition={false}>inner<Else>alt</Else></If>:end<Else>skipped</Else></If></Capture>
+<AssertEquals actual={nested} expected={"outer:alt:end"} />
+</Test>
+
+"Never expands" is stronger than "renders nothing". An assertion placed in the
+unselected branch would fail this document if it ran — the test passes only
+because that branch is never reached.
+
+<Test name="The unselected branch never runs">
+<If condition={true}>selected<Else>
+<AssertEquals actual={"the unselected branch ran"} expected={"it must never run"} />
+</Else></If>
+</Test>

.github/workflows/ci.yml

@@ -77,11 +77,13 @@ jobs:
  --component-dir packages/core/components \
  --raw
 
- # A built-in component resolves from the module graph rather than a
- # search path. Only the compiled binary proves it survives `deno compile`.
- # The directory target runs every built-in's colocated document at once.
- - name: Smoke test the built-in components with no search path
- run: ./dist/xmd test packages/core/src/components --raw
+ # A built-in resolves from the module graph rather than a search path.
+ # Only the compiled binary proves it survives `deno compile`. The
+ # directory target discovers every colocated document beneath core's
+ # source at once — the built-in components under `components/`, and the
+ # structural directives, which resolve no file at all.
+ - name: Smoke test the built-ins with no search path
+ run: ./dist/xmd test packages/core/src --raw
 
  # The guide documents this command and its output; running it keeps the
  # value-root contract executable rather than described.

README.md

@@ -123,8 +123,26 @@ executable.md treats the root document like a component:
 - JSX tags with capitalized names become component invocations.
 - `<Content />` acts as a slot for child content.
 - Text segments support `{meta.key}` and `{props.key}` interpolation.
+- `<If condition={...}>`, with an optional `<Else>` block, is a structural directive rather than a component.
 - Markdown is healed at execution boundaries with `remend` so formatting does not bleed across components or executable blocks.
 
+## Control flow
+
+`<If>` expands one branch and only one. `condition` must be a boolean — there is no truthy or falsy coercion — and the branch that is not selected never expands, so nothing in it imports a component, runs a block, or creates a binding.
+
+```md
+<If condition={hasFailures}>
+## Test failures
+
+<FailureReport />
+<Else>
+All checks passed.
+</Else>
+</If>
+```
+
+`<Else>` is optional and, when present, is the final substantive child of its `<If>`. See the [control-flow guide](https://executable.md/docs/control-flow) for nesting and binding examples.
+
 ## Executable code blocks
 
 The first word in a fence info string is the language. The remaining words form a modifier chain. Standard renderers only read the first word, so the modifiers stay invisible everywhere else.

packages/core/src/If.test.md

@@ -0,0 +1,96 @@
+# If
+
+`<If>` chooses one branch of a document and expands only that branch. It is a
+directive the expansion engine handles itself, so there is no `If.md` to import
+and nothing to install before using it.
+
+A true condition renders the content it guards.
+
+<Test name="A true condition renders its children">
+<Capture as="rendered"><If condition={true}>selected</If></Capture>
+<AssertEquals actual={rendered} expected={"selected"} />
+</Test>
+
+A false condition with nothing else to say renders nothing at all — not an
+empty region, not a placeholder.
+
+<Test name="A false condition without Else renders nothing">
+<Capture as="empty"><If condition={false}>hidden</If></Capture>
+<AssertEquals actual={empty} expected={""} />
+</Test>
+
+`<Else>` supplies the alternative. Whichever branch the condition selects, the
+other one contributes nothing to the output.
+
+<Test name="A false condition selects the Else branch">
+<Capture as="otherwise"><If condition={false}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={otherwise} expected={"otherwise"} />
+</Test>
+
+<Test name="A true condition selects the leading branch">
+<Capture as="then"><If condition={true}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={then} expected={"then"} />
+</Test>
+
+The condition is an ordinary expression, so it reads whatever the document has
+already bound. Here `<Parse>` turns a JSON answer into a value, and `<If>`
+branches on one of its fields.
+
+<Test name="The condition reads a binding the document already made">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="verdict">
+{ "passed": true }
+</Parse>
+<Capture as="report"><If condition={verdict.passed}>approved<Else>needs revision</Else></If></Capture>
+<AssertEquals actual={report} expected={"approved"} />
+</Test>
+
+<Test name="The condition may compute a boolean from that binding">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="failing">
+{ "passed": false }
+</Parse>
+<Capture as="failingReport"><If condition={!failing.passed}>needs revision<Else>approved</Else></If></Capture>
+<AssertEquals actual={failingReport} expected={"needs revision"} />
+</Test>
+
+The selected branch is spliced in where the directive was written, so content
+around it keeps its order.
+
+<Test name="Content around the selected branch keeps its order">
+<Capture as="ordered">before|<If condition={true}>mid<Else>alt</Else></If>|after</Capture>
+<AssertEquals actual={ordered} expected={"before|mid|after"} />
+</Test>
+
+`<If>` opens no scope of its own. A binding the selected branch creates behaves
+like one written inline, so it is still readable after `</If>`.
+
+<Test name="A capture from the selected branch survives the block">
+<If condition={true}><Capture as="picked">chosen</Capture></If>
+<AssertEquals actual={picked} expected={"chosen"} />
+</Test>
+
+The branch that is not selected never expands, so it binds nothing. A reference
+to a name it would have created stays unresolved, exactly as a reference to a
+name no one ever wrote.
+
+<Test name="The unselected branch creates no binding">
+<If condition={false}><Capture as="skipped">never</Capture><Else>alternative</Else></If>
+<Capture as="probe">[{skipped}]</Capture>
+<AssertEquals actual={probe} expected={"[{skipped}]"} />
+</Test>
+
+Conditionals nest, and each one selects on its own.
+
+<Test name="Nested conditionals select independently">
+<Capture as="nested"><If condition={true}>outer:<If condition={false}>inner<Else>alt</Else></If>:end<Else>skipped</Else></If></Capture>
+<AssertEquals actual={nested} expected={"outer:alt:end"} />
+</Test>
+
+"Never expands" is stronger than "renders nothing". An assertion placed in the
+unselected branch would fail this document if it ran — the test passes only
+because that branch is never reached.
+
+<Test name="The unselected branch never runs">
+<If condition={true}>selected<Else>
+<AssertEquals actual={"the unselected branch ran"} expected={"it must never run"} />
+</Else></If>
+</Test>

.github/workflows/ci.yml

@@ -77,11 +77,13 @@ jobs:
  --component-dir packages/core/components \
  --raw
 
- # A built-in component resolves from the module graph rather than a
- # search path. Only the compiled binary proves it survives `deno compile`.
- # The directory target runs every built-in's colocated document at once.
- - name: Smoke test the built-in components with no search path
- run: ./dist/xmd test packages/core/src/components --raw
+ # A built-in resolves from the module graph rather than a search path.
+ # Only the compiled binary proves it survives `deno compile`. The
+ # directory target discovers every colocated document beneath core's
+ # source at once — the built-in components under `components/`, and the
+ # structural directives, which resolve no file at all.
+ - name: Smoke test the built-ins with no search path
+ run: ./dist/xmd test packages/core/src --raw
 
  # The guide documents this command and its output; running it keeps the
  # value-root contract executable rather than described.

README.md

@@ -123,8 +123,26 @@ executable.md treats the root document like a component:
 - JSX tags with capitalized names become component invocations.
 - `<Content />` acts as a slot for child content.
 - Text segments support `{meta.key}` and `{props.key}` interpolation.
+- `<If condition={...}>`, with an optional `<Else>` block, is a structural directive rather than a component.
 - Markdown is healed at execution boundaries with `remend` so formatting does not bleed across components or executable blocks.
 
+## Control flow
+
+`<If>` expands one branch and only one. `condition` must be a boolean — there is no truthy or falsy coercion — and the branch that is not selected never expands, so nothing in it imports a component, runs a block, or creates a binding.
+
+```md
+<If condition={hasFailures}>
+## Test failures
+
+<FailureReport />
+<Else>
+All checks passed.
+</Else>
+</If>
+```
+
+`<Else>` is optional and, when present, is the final substantive child of its `<If>`. See the [control-flow guide](https://executable.md/docs/control-flow) for nesting and binding examples.
+
 ## Executable code blocks
 
 The first word in a fence info string is the language. The remaining words form a modifier chain. Standard renderers only read the first word, so the modifiers stay invisible everywhere else.

packages/core/src/If.test.md

@@ -0,0 +1,96 @@
+# If
+
+`<If>` chooses one branch of a document and expands only that branch. It is a
+directive the expansion engine handles itself, so there is no `If.md` to import
+and nothing to install before using it.
+
+A true condition renders the content it guards.
+
+<Test name="A true condition renders its children">
+<Capture as="rendered"><If condition={true}>selected</If></Capture>
+<AssertEquals actual={rendered} expected={"selected"} />
+</Test>
+
+A false condition with nothing else to say renders nothing at all — not an
+empty region, not a placeholder.
+
+<Test name="A false condition without Else renders nothing">
+<Capture as="empty"><If condition={false}>hidden</If></Capture>
+<AssertEquals actual={empty} expected={""} />
+</Test>
+
+`<Else>` supplies the alternative. Whichever branch the condition selects, the
+other one contributes nothing to the output.
+
+<Test name="A false condition selects the Else branch">
+<Capture as="otherwise"><If condition={false}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={otherwise} expected={"otherwise"} />
+</Test>
+
+<Test name="A true condition selects the leading branch">
+<Capture as="then"><If condition={true}>then<Else>otherwise</Else></If></Capture>
+<AssertEquals actual={then} expected={"then"} />
+</Test>
+
+The condition is an ordinary expression, so it reads whatever the document has
+already bound. Here `<Parse>` turns a JSON answer into a value, and `<If>`
+branches on one of its fields.
+
+<Test name="The condition reads a binding the document already made">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="verdict">
+{ "passed": true }
+</Parse>
+<Capture as="report"><If condition={verdict.passed}>approved<Else>needs revision</Else></If></Capture>
+<AssertEquals actual={report} expected={"approved"} />
+</Test>
+
+<Test name="The condition may compute a boolean from that binding">
+<Parse schema={{ type: "object", properties: { passed: { type: "boolean" } }, required: ["passed"] }} as="failing">
+{ "passed": false }
+</Parse>
+<Capture as="failingReport"><If condition={!failing.passed}>needs revision<Else>approved</Else></If></Capture>
+<AssertEquals actual={failingReport} expected={"needs revision"} />
+</Test>
+
+The selected branch is spliced in where the directive was written, so content
+around it keeps its order.
+
+<Test name="Content around the selected branch keeps its order">
+<Capture as="ordered">before|<If condition={true}>mid<Else>alt</Else></If>|after</Capture>
+<AssertEquals actual={ordered} expected={"before|mid|after"} />
+</Test>
+
+`<If>` opens no scope of its own. A binding the selected branch creates behaves
+like one written inline, so it is still readable after `</If>`.
+
+<Test name="A capture from the selected branch survives the block">
+<If condition={true}><Capture as="picked">chosen</Capture></If>
+<AssertEquals actual={picked} expected={"chosen"} />
+</Test>
+
+The branch that is not selected never expands, so it binds nothing. A reference
+to a name it would have created stays unresolved, exactly as a reference to a
+name no one ever wrote.
+
+<Test name="The unselected branch creates no binding">
+<If condition={false}><Capture as="skipped">never</Capture><Else>alternative</Else></If>
+<Capture as="probe">[{skipped}]</Capture>
+<AssertEquals actual={probe} expected={"[{skipped}]"} />
+</Test>
+
+Conditionals nest, and each one selects on its own.
+
+<Test name="Nested conditionals select independently">
+<Capture as="nested"><If condition={true}>outer:<If condition={false}>inner<Else>alt</Else></If>:end<Else>skipped</Else></If></Capture>
+<AssertEquals actual={nested} expected={"outer:alt:end"} />
+</Test>
+
+"Never expands" is stronger than "renders nothing". An assertion placed in the
+unselected branch would fail this document if it ran — the test passes only
+because that branch is never reached.
+
+<Test name="The unselected branch never runs">
+<If condition={true}>selected<Else>
+<AssertEquals actual={"the unselected branch ran"} expected={"it must never run"} />
+</Else></If>
+</Test>