Reference · SemText · Document & structure

`<sem-reader>`

SemText element

It is page furniture, not content — a document without it loses nothing a machine would read. Readers get focus mode, type size, colour scheme, print, and audience controls in one place.

Reading tools for a long document: an outline, a progress bar, and controls for text size and theme. It is page furniture, not content — a document without it loses nothing a machine would read. Readers get focus mode, type size, colour scheme, print, and audience controls in one place. optional. Comma flags, in any order, one of `outline`, `progress`, `focus`, `type`, `color`, `print`, `audience` — unknown flags, including the theme flag reserved for R/W3, are ignored. Controls render in the **canonical order** above, not in attribute order.

optional. Deepest heading level in the generated outline, `2`–`6`; The outline always starts at `h2` — `h1` is the document title.

per the global attribute catalog (conventions.md §2)

Children

<nav>Child (optional): an authored `<nav aria-label="Contents">`. When present it is the outline, **used verbatim** — no ids are assigned, no list is generated, nothing inside it is rewritten. This is the JS-off table of contents.

Example

sem-reader.html

source

              
              <sem-reader controls="outline,progress,focus,type,color,print,audience" outline-depth="3"></sem-reader>
            

render

Live render boots with JavaScript — the authored source is alongside.

variant: in a document

The reader in its habitat: first child of the root wrapper, all seven controls. The outline derives from the document's h2–h3 headings (one link per heading, `aria-current="location"` on the topmost one in view); the progress bar fills with the document scroll; focus, type and colour write session attributes on `<html>`, persisted per control via localStorage — fail-open. This page's pane is not a long document, so the full chrome is honest only in a real document (see the site's demo build).

variant: in a document

sem-reader-in-document.html

source

              
              <sem-enhanced-document>
            
                <sem-reader controls="outline,progress,focus,type,color,print,audience" outline-depth="3"></sem-reader>
            
                <h1>Token rotation runbook</h1>
            
                <h2>Before you start</h2>
            
                <p>Port-forward to the admin bucket and confirm replica lag is zero.</p>
            
                <h2>Run the rotation</h2>
            
                <h3>Dry run</h3>
            
                <p>Print the next grant and check the audience list, apply nothing.</p>
            
                <h3>Apply</h3>
            
                <p>Rotate the pair, then verify the new hash validates a live session.</p>
            
                <h2>After</h2>
            
                <p>Revoke the old grant and close the change ticket.</p>
            
              </sem-enhanced-document>

render

Live render boots with JavaScript — the authored source is alongside.

variant: authored contents nav

An authored `<nav aria-label="Contents">` IS the outline: used verbatim — no ids are minted, no list is generated, nothing inside is rewritten. This is the JS-off table of contents; with the bundle, the toggle still opens it and an outline link closes the panel again.

variant: authored contents nav

sem-reader-authored-nav.html

source

              
              <sem-reader controls="outline,progress">
            
                <nav aria-label="Contents">
            
                  <ol>
            
                    <li><a href="#before">Before you start</a></li>
            
                    <li>
            
                      <a href="#apply">Run the rotation</a>
            
                      <ol>
            
                        <li><a href="#dry">Dry run</a></li>
            
                        <li><a href="#apply-step">Apply</a></li>
            
                      </ol>
            
                    </li>
            
                    <li><a href="#after">After</a></li>
            
                  </ol>
            
                </nav>
            
              </sem-reader>

render

Live render boots with JavaScript — the authored source is alongside.

variant: outline only, depth 2

`outline-depth="2"` caps the outline at h2: the h3 headings still render in the document but stay out of the contents. `controls="outline"` drops the progress bar and every preference control — only the Contents toggle renders.

variant: outline only, depth 2

sem-reader-outline-depth-2.html

source

              
              <sem-enhanced-document>
            
                <sem-reader controls="outline" outline-depth="2"></sem-reader>
            
                <h1>Token rotation runbook</h1>
            
                <h2>Before you start</h2>
            
                <p>Port-forward to the admin bucket.</p>
            
                <h3>Replica lag</h3>
            
                <p>Confirm zero lag before touching the grants.</p>
            
                <h2>Run the rotation</h2>
            
                <p>Rotate the pair and verify a live session.</p>
            
              </sem-enhanced-document>

render

Live render boots with JavaScript — the authored source is alongside.

variant: audience control

The audience select renders only when the document declares profiles: it lists every `sem-profile` (label, else id) under a leading `Everyone`, and the choice writes the shareable `sem-audience` hash parameter — the audience handler applies it on `hashchange`; the reader never hides anything itself. No declared profiles, no control.

variant: audience control

sem-reader-audience-control.html

source

              
              <sem-audiences>
            
                <sem-profile id="reader" label="Reader"></sem-profile>
            
                <sem-profile id="operator" label="Operator" implies="reader"></sem-profile>
            
              </sem-audiences>
            
              <sem-reader controls="outline,audience"></sem-reader>

render

Live render boots with JavaScript — the authored source is alongside.

Source: spec/schema/sem-reader.md