[@layout]: ../docs.layout.md

# Paths

A Path is an ordered set of links to activities. Each step keeps its authored
label, linked Source or instance, and progress from the installed Completion reader.

A link to a Block summarizes that Block; a Source link summarizes the Source.

```md
# Practice

1. [First reflection](./reflection.project.md?iid=first) {#first}
2. [Take a break](./break.event.md) {#break}
3. [Reflect again](./reflection.project.md?iid=retry) {#retry}
```

Activate `@pathmx/path` in your project. To compose a Completion reader, use
`createPathPlugin({ completion: completion.reader })` and register its `plugin`
together with the Completion plugin.

## Step details

Use a Source title in frontmatter and let the step component present the heading
and available metadata. It replaces the ordinary Markdown heading at that position.

```md
---
title: Reflection
icon: pencil
---

<x-path-step />

Write one thing you would try differently.
```

When reached from a Path, the header uses that placement's label and effective
Source instance. A direct Source visit shows its own title and metadata. Core
Schedule contributes event times and deadlines; Location contributes physical and
online links. Completion contributes status when configured. These use the
effective instance props of the linked Source.

## Path navigation

Put one navigation component in the shared layout:

```html
<x-path-player />
<x-player-app />
```

The Path component renders a compact island with the current step's completion
indicator, Source icon, title, and available schedule/location metadata. An inset
track has one segment per step: accent segments show completion, a stronger neutral
segment marks the current unfinished step, and remaining segments are muted. Its menu and title area open
the complete outline. The
outline header and close control stay visible as its step list scrolls.
Previous/next controls navigate between steps. Both remain visible, with the
unavailable direction disabled at the beginning or end of the Path. Without valid
Path context, the island is absent; it does not guess a Path from other Sources linking here.

With Player installed, Focus and Slides show a smaller control containing the
Path icon/name and previous/next chevrons in the shared control dock. It omits
progress segments; selecting the Path identity opens the same outline. Step navigation preserves
the chosen mode and each destination's instance. Beat navigation stays within the
current Source; reaching its final Beat does not complete the activity.

The overlay's **Exit Path** link opens the current Source without `path` and
`step`, preserving its instance, other query parameters, and current fragment.
The full row opens a step; location links remain independent targets.

Steps without completion requirements remain navigable and use a quiet content
marker. They do not contribute to completion totals. For explicit acknowledgment,
author a Source or Block `completion` requirement:

```yaml
completion:
  label: Finish this lecture
```

When that acknowledgment is the remaining requirement and the viewer can update
it, Path offers **Complete and continue** (or **Complete step** at the end).
The action uses Completion's existing state and advances only after a confirmed
save and page refresh. A failure leaves the viewer on the current step. Compact
Play keeps this action in the overlay.

## Explicit presentations

```html
<x-path-list source="./practice.path.md" />
<x-path-step path="./practice.path.md" step="retry" />
<x-path-player path="./practice.path.md" step="retry" />
```

`source` and `path` resolve relative to the authoring Source. `step` names the
stable authored identifier within that Path. An explicit player must match the
Source instance being viewed. The list and outline use the same task-row renderer.


## Check authoring

```sh
bun run pmx lint
bun run pmx lint --format json
bun run pmx query path.steps --input '{"path":"/practice.path"}'
```

Lint reports missing or duplicate step IDs, unsupported step tags, missing linked
Sources, nested Path cycles/repeated inclusion, and invalid component references.
For an explicit component, provide both `path` and `step`; an unknown step diagnostic
lists the IDs available in that Path. Select a step inside a nested Path by naming
that nested Path explicitly. `source` and `path` may select an existing instance
with `?iid=…`; use the separate `step` prop rather than a URL fragment.

The `path.steps` query shows the admitted order, stable IDs, targets, and completion.
Use `--as /people/alex.user` to inspect the route through a particular viewer's
access. Querying does not change progress.