@nanisoft/prism-llms 0.5.2 → 0.6.0

package/dist/llms-full.txt

@@ -6,6 +6,17 @@
 
 # @nanisoft/prism-llms
 
+## 0.6.0
+
+### Minor Changes
+
+- Regenerate the corpus for the third law of motion
+  
+  The corpus picks up the `ParticleField`, `AuroraWash` and `Reveal` entries, the
+  `backdrop` slot on `Hero01`, the `aurora` field on `Backdrop01`, the
+  `scrollRail` prop on `SiteNavbar`, and the rewritten Motion documentation,
+  whose third law the new items document in their own JSDoc.
+
 ## 0.5.2
 
 ### Patch Changes
@@ -267,6 +278,13 @@ Changesets are appended above this entry for every published change.
 
 # @nanisoft/prism-mcp-server
 
+## 0.4.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @nanisoft/prism-llms@0.6.0
+
 ## 0.4.2
 
 ### Patch Changes
@@ -373,6 +391,16 @@ Changesets are appended above this entry for every published change.
 
 # @nanisoft/prism-tokens
 
+## 1.5.0
+
+### Minor Changes
+
+- Add the `aurora` ambient cycle at 24000ms
+  
+  The new member measures light crossing a ground: the washes a hero stands on.
+  It rides `ambient-ease-drift`, holds to the one-second floor with the rest of
+  the group, and is admitted into the closed set the emitted-contract gate holds.
+
 ## 1.2.0
 
 ### Minor Changes
@@ -914,6 +942,58 @@ Changesets are appended above this entry for every published change.
 
 # @nanisoft/prism-ui
 
+## 1.5.0
+
+### Minor Changes
+
+- Add the third law of motion: arrivals, living fields, and the reading rail
+  
+  Motion now has three laws. Feedback and the ambient cycles are unchanged; the
+  new law admits three authored mechanisms, each shipped as primitives rather
+  than opened as a licence:
+  
+  - `Reveal` wraps a band in a scroll-driven arrival bound to the reader's own
+    scroll through `prism-reveal` utilities behind a view-timeline capability
+    check. No script arms it, a browser without the timeline ships no rule at
+    all, and the universal reduced-motion rule hands that reader the visible
+    page.
+  - `ParticleField` is the one script-driven figure: a linked, pointer-answering
+    medium whose complete still field renders on the server, whose loop stops off
+    screen, and whose palette is re-read when the document's pack or mode
+    changes. `AuroraWash` is the still counterpart: translucent planes in the
+    pack's own colours on the new `aurora` cycle, transform-only.
+  - `SiteNavbar` gains a reading rail on its sticky hairline, `scrollRail` on by
+    default: a spectrum line filling with the page's own scroll, drawing nothing
+    in a browser that cannot run the timeline. The current link's filled pill
+    becomes a persistent spectrum underline, and `Hero01` gains a `backdrop` slot
+    so a hero composes its own ground.
+  
+  `Backdrop01` offers `field="aurora"`, and `prism-text-spectrum` is the one
+  admitted motion on text: display ink lit at the sweep tempo with foreground
+  ends, so it holds contrast in every pack and both modes.
+  
+  `scripts/check-motion.mjs` holds the new layer: a reveal or rail selector
+  outside the `@supports` block naming its timeline fails the build, because an
+  animation whose timeline fails to resolve pauses at its invisible keyframe.
+
+### Patch Changes
+
+- Updated dependencies
+  - @nanisoft/prism-tokens@1.5.0
+
+## 1.4.0
+
+### Minor Changes
+
+- 3f9cc78: Add `MediaBand01`, an editorial band with a caller-owned media slot, and a `size`
+  prop on `Section` for compact, default and tall vertical rhythms.
+  
+  The band owns the frame, the ratio, the surface and the order, and it never puts
+  the copy on top of an arbitrary photograph. The media is the caller's node, so an
+  image, a video poster or a composed figure can sit in the frame. The Section size
+  keeps the existing default byte-identical and gives a page three authored rhythms
+  instead of five site stylesheets inventing their own.
+
 ## 1.3.0
 
 ### Minor Changes
@@ -6126,10 +6206,10 @@ icon-only control carries an accessible name.
 
 # Motion
 
-Two laws: feedback on a short scale, and a running figure on a cycle scale, both by token.
+Three laws: feedback on a short scale, a running figure on a cycle scale, and an arrival bound to the reader's own scroll, all by token.
 
-Motion has two laws, and they are different laws rather than one law with an
-exception. The distinction is falsifiable: stop the animation and ask whether
+Motion has three laws, and they are different laws rather than one law with
+exceptions. The distinction is falsifiable: stop the animation and ask whether
 the figure is still true and still legible.
 
 **Feedback is a response.** Something happened because the reader did it. They
@@ -6139,29 +6219,46 @@ overshoots. The scale is `fast` 80ms, `base` 160ms and `slow` 280ms, with
 token rather than a value, and it does not decide reduced motion for itself.
 
 **A cycle is a demonstration.** A marker crosses a rail, a reticle crosses a
-series, a wavefront crosses a field. The reader did not cause it and is not
-waiting for it: the figure is making a claim about a mechanism and the motion is
-how the claim is made visible. If stopping the animation leaves nothing true and
-nothing legible, the motion was the figure, and the right component is one that
-says it is atmosphere.
-
-The cycle scale is separate because the two measure different things by a factor
+series, a wavefront crosses a field, light crosses a ground. The reader did not
+cause it and is not waiting for it: the figure is making a claim about a
+mechanism and the motion is how the claim is made visible. If stopping the
+animation leaves nothing true and nothing legible, the motion was the figure,
+and the right component is one that says it is atmosphere.
+
+**An arrival is bound to the reader's own scroll.** A section a reader scrolls
+to may meet them, and the meeting is the third law rather than a loosened
+second: it runs on CSS scroll-driven animations, so no script decides when it
+plays and no timer can play it early; the content exists in the document from
+the first paint; a browser that does not ship the timeline declines the whole
+rule and shows the section simply there; and the universal reduced-motion rule
+hands that reader the same still page. The one script-driven figure in the
+system, `ParticleField`, follows the same test from the other side: it renders
+its complete still figure on the server and the script only adds the movement.
+
+The cycle scale is separate because it measures a different thing by a factor
 of twenty-five, and one name cannot mean both. `ambient` is in seconds, and the
-emitted contract measures it with a floor of one second: a cycle faster than that
-is unreadable before it is understood.
-
-Three rules bound it, and none of them is a matter of taste.
-
-- **Nothing is hidden.** No ambient rule sets `opacity: 0`, and nothing waits
-  for a script, an intersection or a timer. Every figure is complete at first
-  paint, so a reader with scripting off, a print stylesheet or a crawler sees the
-  whole drawing.
+emitted contract measures it with a floor of one second: a cycle faster than
+that is unreadable before it is understood.
+
+Three rules bound the ambient layer, and none of them is a matter of taste.
+
+- **Nothing in the ambient layer is hidden.** No ambient rule sets `opacity: 0`
+  and no ambient figure waits for a script or a timer. Every figure is complete
+  at first paint, so a reader with scripting off, a print stylesheet or a
+  crawler sees the whole drawing. The reveal layer is the one exception ever
+  granted, and it is granted to the reader's own scroll position rather than to
+  a script: it lives behind a capability check, and collapses to the fully
+  visible form the moment anything, including reduced motion, declines to run
+  it.
 - **Reduced motion removes the movement, not the figure.** The
   `prefers-reduced-motion` block is one unlayered rule setting `animation: none`
   and `transition: none` on the universal selector, and because every resting
   state is the full form, that reader gets the same figure, still.
-- **Compositor properties only.** Every keyframe animates `transform` or
-  `opacity`. Nothing in the layer animates a layout or paint property.
+- **Compositor properties only.** Every ambient keyframe animates `transform`
+  or `opacity`. Nothing in the layer animates a layout or paint property. The
+  one named exception is the spectrum ink on display type, which animates a
+  gradient position because text cannot be moved behind its own gradient, and
+  the exception is a class in the stylesheet with a scope, not a licence.
 
 One rule covers the whole package rather than each component guarding itself, and
 that is a correction rather than a preference. A `motion-safe:` variant adds a
@@ -6176,8 +6273,8 @@ announcement, without the time.
 A keyframe is a mechanism and lives in the component package's stylesheet; a
 duration is a value and lives in the token source. They meet at exactly one
 place, an `animation` shorthand whose length is `var(--ambient-travel)`, so
-neither can invent the other. The six `prism-ambient-*` classes exist so that a
-component picks a cycle by naming a mechanism and never writes a timing.
+neither can invent the other. The eight `prism-ambient-*` classes exist so that
+a component picks a cycle by naming a mechanism and never writes a timing.
 
 <TokenTable group="motion" />
 
@@ -7800,6 +7897,99 @@ export default function AspectRatioDemo() {
 **`className`** `string` · optional · default: — — Layout only.
 
 
+---
+
+# AuroraWash
+
+Light moving through a ground: translucent planes in the pack’s own colours, each on its own long orbit of the aurora cycle.
+
+```tsx
+import { AuroraWash } from '@nanisoft/prism-ui/components/aurora-wash'
+```
+
+## Overview
+
+AuroraWash is light moving through a ground: two or three large translucent
+planes in the pack's own colours, each on its own long orbit of the aurora
+cycle. It follows the wash law, so the stops are semantic, the element is
+`aria-hidden`, and it never touches text.
+
+## Guidelines
+
+### When to use
+
+Use it where a hero's ground would otherwise be flat: a band whose claim is
+that a surface is alive reads differently with light crossing it, and the wash
+says that without drawing a single invented mark. It repaints with the pack,
+because the planes carry the pack's own primary and series colours, so a wash
+in one pack is a different wash in another.
+
+Give it a clipped container. The wrapper clips, but the caller gives it the
+positioned ancestor to fill, and a wash that escapes its band is a page-wide
+stain.
+
+### When not to use
+
+Do not put type on it without its own contrast. A wash is a ground, and the
+content over it owns the contrast the way content over `SignalField` does.
+
+Do not use two on one page. Light moving through two grounds is two weathers,
+and the reader cannot be in both.
+
+Do not reach for it when the claim is a mechanism rather than an atmosphere. A
+marker crossing a rail is `Backdrop01` with the travel cycle; the wash says a
+surface is lit, not that a system runs.
+
+### Best practices
+
+- Let it be quiet. The intensity of a wash is the caller's, through opacity on
+  the caller's own wrapper, and the restrained version is the one that reads
+  as a place rather than as a poster.
+- Pair it with `ParticleField` only when the two claims belong together, and
+  let the tempos differ, which the aurora and drift cycles already do.
+- Trust the still frame. The reduced-motion rule holds the planes at rest and
+  the wash survives it, which is the test every ambient figure in this system
+  passes.
+
+**The wash as a ground, with type over it, and a pack boundary around the**
+
+```tsx
+import { AuroraWash } from '@nanisoft/prism-ui/components/aurora-wash'
+
+/**
+ * The wash as a ground, with type over it, and a pack boundary around the
+ * second card so the demo shows the claim the component makes: the planes
+ * carry the ground's own colours, and a wash in one pack is a different wash
+ * in another.
+ */
+export default function AuroraWashDemo() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="bg-card relative overflow-hidden rounded-xl border p-10">
+        <AuroraWash className="absolute inset-0" />
+        <div className="relative">
+          <p className="text-muted-foreground text-sm font-medium tracking-wide uppercase">
+            Preview
+          </p>
+          <h3 className="mt-3 text-3xl font-semibold tracking-tight text-balance">
+            Light through the ground the page is wearing
+          </h3>
+          <p className="text-muted-foreground mt-4 max-w-168 text-lg text-pretty">
+            Three planes on one long orbit, out of step with each other, each
+            carrying a colour the page already resolved.
+          </p>
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component. The wash fills the nearest positioned ancestor, so the caller's job is to give it one and to keep the content above it; the wash never carries the content and never takes the pointer.
+
+
 ---
 
 # Avatar
@@ -22169,6 +22359,110 @@ export default function PaginationDemo() {
 > Extends: the native `<nav>` element. No additional Prism-specific props.
 
 
+---
+
+# ParticleField
+
+A living field: points drifting on linked paths, answering the pointer, and standing still as a complete figure when the loop is stopped or declined.
+
+```tsx
+import { ParticleField } from '@nanisoft/prism-ui/components/particle-field'
+```
+
+## Overview
+
+ParticleField is a living field: points drifting on linked paths, the medium a
+page's largest statements stand in front of. It is the one script-driven figure
+in the system, and the static field it renders on the server is the contract
+that makes that safe: stop the loop, disarm the canvas, print the page, and the
+figure is still a field, still true, still legible.
+
+## Guidelines
+
+### When to use
+
+Use it where a page claims there is a medium to move through: a hero that says
+traffic flows, a band that says an estate is observed, a ground that says the
+surface is live. The links are what make it a medium rather than dust, so size
+`linkDistance` to the band: a wide band carries longer lines than a panel.
+
+Give it room behind content that has its own position and its own contrast. It
+is a ground, exactly as `SignalField` is, and it composes behind type rather
+than beside it.
+
+### When not to use
+
+Do not use it behind a reading passage. A medium that moves while a reader
+reads is the first thing a reader with vestibular sensitivity will ask to have
+gone, and `SignalField` still, or nothing, is the ground a passage wants.
+
+Do not use it to say something. It is `aria-hidden` by default because a medium
+is not information; a figure that carries a claim is `PulseGraph` or
+`PulseSeries`, both of which require a name.
+
+Do not stack two of them. Two media on one page is a collision, and the reader
+cannot tell which one they are looking through.
+
+### Best practices
+
+- Leave `interactive` on wherever a reader's hand can reach the ground, and
+  turn it off under text a reader will select, because a surface that moves
+  during a selection is a surface fighting the selection.
+- Keep the count in the dozens. A field with hundreds of points is a haze, and
+  the clamp will not save a composition that wanted fog.
+- Pair it with `AuroraWash` when the claim is light moving through the medium
+  as well as across it, and let the two differ in tempo, which they already do
+  by an order of magnitude.
+- Trust the floor. The component that renders nothing until a script runs is
+  the retired line's defect, and this one renders the whole figure before any
+  script decides to help.
+
+**The field as a ground, with type over it, which is the only honest way to**
+
+```tsx
+import { ParticleField } from '@nanisoft/prism-ui/components/particle-field'
+
+/**
+ * The field as a ground, with type over it, which is the only honest way to
+ * preview a medium: a field on its own is a scatter and there is nothing to
+ * judge.
+ *
+ * The demo is a server component. The field is a client component under it, so
+ * the floor renders here and the loop arms in the reader's browser, which is
+ * the arrangement a product composes.
+ */
+export default function ParticleFieldDemo() {
+  return (
+    <div className="bg-card relative overflow-hidden rounded-xl border p-10">
+      <ParticleField count={56} className="absolute inset-0" />
+      <div className="relative">
+        <p className="text-muted-foreground text-sm font-medium tracking-wide uppercase">
+          Preview
+        </p>
+        <h3 className="mt-3 text-3xl font-semibold tracking-tight text-balance">
+          A medium as a ground, with type over it
+        </h3>
+        <p className="text-muted-foreground mt-4 max-w-168 text-lg text-pretty">
+          The points drift on linked paths and answer the pointer. Move the hand
+          across this panel and the medium parts around it, and the field it
+          falls back to when the loop is stopped is the same field at rest.
+        </p>
+      </div>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`count`** `number` · optional · default: — — How many points the field drifts. Read as a suggestion and clamped, because a field behind a hero wants dozens and a field behind a panel wants a handful, and a count outside that range is either a haze or a chart.
+**`linkDistance`** `number` · optional · default: — — How far apart two points may sit and still be linked, in CSS pixels. The links are what make a field read as a medium rather than as dust, and the distance is a prop because a wide band carries longer lines than a panel.
+**`interactive`** `boolean` · optional · default: — — Whether the reader's pointer pushes the field. On by default, because a medium that answers the hand is the claim this figure makes; a caller placing the field under text a reader is selecting turns it off, because a surface that moves while a reader drags across it is a surface fighting the selection.
+**`label`** `string` · optional · default: — — The name of the figure, or `decorative`. See `SignalFieldProps`.
+**`decorative`** `boolean` · optional · default: —
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component.
+
+
 ---
 
 # PasswordField
@@ -25694,6 +25988,123 @@ export default function ResizableDemo() {
 **`size`** `Position` · optional · default: `50` — The pane's share of the group, as a percentage.
 
 
+---
+
+# Reveal
+
+A section that meets the reader: the wrapper that binds an arrival to the reader’s own scroll position, with no script and no second introduction for the hero.
+
+```tsx
+import { Reveal } from '@nanisoft/prism-ui/components/reveal'
+```
+
+## Overview
+
+Reveal is a section that meets the reader: the wrapper that binds an arrival to
+the reader's own scroll position and to nothing else. It is a style the browser
+resolves rather than a state a script flips, so there is no observer, no
+listener and no client boundary, and the content exists from the first paint.
+
+## Guidelines
+
+### When to use
+
+Use it on the bands a reader scrolls to. An arrival acknowledges the reader's
+own movement, which is the only input it answers to, and a band that enters
+the viewport as the reader arrives reads as a page composed for reading rather
+than as one long poster.
+
+Stagger with `delay` when bands arrive in a rhythm, and keep the stagger to a
+page's own measure: three steps exist, and a cascade longer than the rhythm it
+sits in is a wait the reader did not cause.
+
+### When not to use
+
+Do not wrap the hero. A section above the fold when the page loads has already
+finished entering, and the page does not introduce itself twice; the one
+authored moment a page carries belongs to its hero, not to every band under
+it.
+
+Do not wrap everything. A reveal on every section is one identical entrance
+wearing four different clothes, and the second arrival a reader notices is the
+one where the device stops being about the content. Let the still bands
+between the arriving ones carry their own weight.
+
+Do not use it for feedback or for state. A control answering a reader is the
+first law of motion and already has its scale; an arrival is the third law and
+holds exactly one job.
+
+### Best practices
+
+- Compose it around a Block, not inside one. The wrapper is the whole of the
+  component, every Block keeps its own surface, and no Block widens for a
+  behaviour the whole page shares.
+- Remember the fallbacks are the design: a browser without scroll-driven
+  animations shows the section simply there, a reader who asked for less
+  motion gets the same still page, and neither of those outcomes is a failure
+  to be worked around.
+- The `delay` steps are fractions of the entry rather than waits, so a reader
+  who scrolls fast arrives fast. That is the property that separates this law
+  from a timer, and it is worth keeping.
+
+**Two cards arriving, the second a step behind the first. The demo is the**
+
+```tsx
+import { Reveal } from '@nanisoft/prism-ui/components/reveal'
+
+/**
+ * Two cards arriving, the second a step behind the first. The demo is the
+ * device at its smallest: a staggered pair inside one panel, so the rhythm is
+ * visible without a page to scroll.
+ *
+ * In this documentation frame the cards below the fold are the honest preview:
+ * scroll to them and they arrive, arrive again on the way back up at no delay,
+ * and a reader who has asked the platform for less motion finds them simply
+ * there.
+ */
+export default function RevealDemo() {
+  return (
+    <div className="flex flex-col gap-4">
+      <Reveal>
+        <div className="bg-card text-card-foreground rounded-xl border p-6 shadow-sm">
+          <p className="text-muted-foreground text-sm font-medium tracking-wide uppercase">
+            First band
+          </p>
+          <h3 className="mt-2 text-xl font-semibold tracking-tight">
+            An arrival, bound to the scroll the reader owns
+          </h3>
+          <p className="text-muted-foreground mt-2 text-sm text-pretty">
+            No script decides when this plays. The hand on the scroll does, and
+            a browser that cannot run it shows the band simply there.
+          </p>
+        </div>
+      </Reveal>
+      <Reveal delay={1}>
+        <div className="bg-card text-card-foreground rounded-xl border p-6 shadow-sm">
+          <p className="text-muted-foreground text-sm font-medium tracking-wide uppercase">
+            Second band
+          </p>
+          <h3 className="mt-2 text-xl font-semibold tracking-tight">
+            The same arrival, a step behind
+          </h3>
+          <p className="text-muted-foreground mt-2 text-sm text-pretty">
+            The step is a fraction of the entry rather than a wait, so a reader
+            who scrolls fast arrives fast, and nothing here could delay them.
+          </p>
+        </div>
+      </Reveal>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`children`** `ReactNode` · required · default: — — The band, grid or figure that arrives.
+**`delay`** `1 | 2 | 3` · optional · default: — — How far into the page's rhythm this arrival sits behind the one before it, as a fraction of the entry rather than as a wait: the reader's scroll is the only clock, and a delay a reader could not hurry would be a delay the reader did not cause. Three steps, as on the ambient delays.
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component.
+
+
 ---
 
 # ScrollArea
@@ -33945,7 +34356,10 @@ Use `drift` and `pulse` for any figure. They are the two whose resting form is t
 figure's own full form, so nothing is lost when the cycle is at either end of its
 turn. Use `travel`, `sweep`, `scan` and `shimmer` when the figure is drawn wider
 than the band, because those four carry something across a field and the band
-clips what leaves.
+clips what leaves. Use `aurora` when the claim is the ground rather than anything
+crossing it: the whole layer rides one slow orbit, so it suits a wash or a wide
+field and mismatches a drawing with a baseline, which would visibly leave the
+ground it was measured on.
 
 Use `pauseControl` on a page that gives a reader reason to want the page still.
 
@@ -33958,9 +34372,10 @@ Do not use it for a figure that belongs in the layout rather than behind the
 copy. That is `InstrumentPanel01`, and a panel beside the copy says the same thing
 with a border and a title bar instead of an opacity.
 
-Do not reach for it to add movement to a page. There is no entrance animation,
-no scroll effect and no motion on text in this system, and this Block is the one
-place a cycle is allowed, which is exactly why it is not a decoration.
+Do not reach for it to add movement to a page. A cycle demonstrates a system
+that runs, and this Block is the one place in a band a cycle is allowed; an
+arrival is `Reveal`'s job and not a faster cycle's, and neither of them is a
+decoration, which is exactly why each has one place.
 
 ### Best practices
 
@@ -41673,10 +42088,10 @@ at the edge rather than pushing the field wider, and the table behind the figure
 carries its true dates.
 
 **There is no motion, so reduced motion costs the reader nothing.** No draw-in, no
-bar that grows from nothing, no scroll effect, no entrance. DESIGN.md's Motion
-section refuses entrance animation outright, and a schedule is the case where that
-is most obviously right: a bar that arrives is a bar whose arrival a reader has to
-wait for before they can read the relationship it has with the bar above it, and
+bar that grows from nothing, no entrance. DESIGN.md's Motion section lets a band
+arrive with the reader's own scroll, and a schedule is the case where arriving
+would misread: a bar that appears is a bar whose appearance a reader has to wait
+for before they can read the relationship it has with the bar above it, and
 the whole claim of a Gantt is that relationship.
 
 ## The hidden table, and its gaps
@@ -42508,6 +42923,11 @@ of those is a mechanism, and a mechanism reads better shown than described. The
 figure should be one that would still be true with every animation stopped, so
 what the reader gets from it is the claim and the motion is only the emphasis.
 
+Compose a ground with `backdrop` when the claim is the surface the hero stands
+on. An `AuroraWash` says the surface is lit, a `ParticleField` says there is a
+medium to move through, and the band clips and positions whatever it is given,
+so the caller composes a claim rather than a layout.
+
 ### When not to use
 
 Do not use Hero01 inside an application screen. It is a marketing composition,
@@ -42521,7 +42941,9 @@ inside `Section` instead.
 
 Do not pass a figure that is only interesting while it moves. A slot that reads
 as empty in a still frame is a decoration with a slot, and this system does not
-author those.
+author those. The same test holds for the ground: a `backdrop` that collapses
+into nothing when it is stopped was a video with extra steps, and the hero is a
+band making a claim, not a frame around one.
 
 ### Best practices
 
@@ -42658,6 +43080,7 @@ export default function Hero01Demo() {
 **`align`** `'center' | 'left'` · optional · default: `'center'` — Whether the copy is centered in the band or set flush to the left edge of the container. This is the hero's own alignment and not `SectionHeading`'s, because the two are not the same decision: a left-aligned hero is nearly always the left half of a two-column band with a panel or an instrument beside it, and that column is narrower than the container, so the alignment has to be the hero's before the container can be anything. It has no visual effect on its own, which is the point: it aligns the copy inside whatever width it is given.
 **`instrument`** `ReactNode` · optional · default: — — The figure beside the copy: a live view of the thing the copy is about. A slot, and the reason is the whole shape of this Block's second form. The hero that names what a product does and the hero that shows it running are the same section, and every one of the four NaniSoft product sites hand-wrote the two-column band that joins them, each with its own grid, its own gap and its own breakpoint. This is that band. What goes in it is the consumer's, and specifically it should be something that would still be true with every animation stopped: a `PulseGraph` of the pipeline the product runs, a `PulseSeries` of what it captures. A slot that only reads as motion is a decoration with a slot, and this system does not author those. The `instrumented` slot is marked as required when the hero is given one, so a figure cannot be half-wired.
 **`split`** `boolean` · optional · default: — — Puts the copy and the instrument side by side rather than stacked, and narrows the copy to the column it shares the band with. Implied by `instrument` and overridable: a consumer with a narrow instrument and a wide hero may want them stacked anyway.
+**`backdrop`** `ReactNode` · optional · default: — — The ground the hero stands on: a figure the whole band is drawn over. A slot, and for the same reason the instrument is one: the ground a hero wants is the product's own claim, and this Block cannot make it. An `AuroraWash` says the surface is lit, a `ParticleField` says there is a medium to move through, and a caller who wants both composes both, because the one decision a hero should not delegate is what its ground claims. The Block clips the ground to the band, takes the pointer away from it, and holds it behind the copy beside the hero's own faint wash, so a slot here never has to arrive pre-positioned. A ground that would not still be true with every animation stopped does not belong here, for the same reason an instrument that only reads as motion does not: this is a band making a claim, not a frame around a video.
 **`headingLevel`** `HeadingLevel` · optional · default: — — Heading level for the title. Defaults to `h2` because a block is composed, not a page: it installs into a consumer's layout and renders inside catalog previews, so the surrounding document already owns the `h1`. A page that uses this block as its top-level heading opts in with `headingLevel="h1"`; a document that already names this section in its own heading passes one level deeper. See `HeadingLevel`.
 **`className`** `string` · optional · default: — — Layout only, exactly as on every Component. Changing a Prism-owned visual property from here is prohibited.
 
@@ -46686,6 +47109,133 @@ export default function MagicLink01Demo() {
 **`dependencies`** `Button, Card, Field, Input, LiveRegion, Section` — the public Prism exports this item composes
 
 
+---
+
+# MediaBand01
+
+An editorial band: one media slot held at a caller ratio beside one title, description and optional destination, with the copy always on a solid surface.
+
+```tsx
+import { MediaBand01 } from '@nanisoft/prism-ui/blocks/media-band-01'
+```
+
+## Overview
+
+MediaBand01 is an editorial band: one media frame beside one statement, with one
+action. It is the marketing surface the catalogue did not have. `Bento01` holds a
+media node in a cell, but a cell is one item of a set, and a set is the wrong shape
+for the one photograph a page stops on. `Gallery01` holds a set of images and opens
+one at full size, which is right for a portfolio and wrong for a statement.
+
+The media is a slot, not a `src`. A caller can pass an image, a video poster, a
+rendered figure, or a composition of its own components. The Block owns the frame,
+the ratio, the surface and the order. The caller owns the node and its accessible
+name.
+
+The copy is first in the document, and the media is first only in the visual order
+the caller asks for. A reader on a phone meets the title before the picture, and a
+reader at `lg` meets the arrangement the caller chose. That is one tree, so the
+heading is in the outline once.
+
+The copy never sits on the picture. A title over an arbitrary photograph is a
+contrast failure nobody measured, and the solid column beside the image is both
+more legible and more editorial.
+
+There is no animation. An editorial photograph is not feedback and it is not a
+figure showing a system running, so the band does not zoom, slide or reveal.
+
+## Guidelines
+
+### When to use
+
+Use MediaBand01 when a page has one photograph or one composed figure that is a
+moment of its own, and one sentence that the picture makes. It is the band a page
+stops on between two sections of argument.
+
+### When not to use
+
+Do not use it for a set of images. A set is `Gallery01` or a `Bento01` grid. Do not
+use it for a figure that carries a claim a screen reader must hear in full; that is
+`InstrumentPanel01` or one of the figure Components. Do not put the copy on top of
+the image; the solid column is the arrangement this Block exists to make easy.
+
+### Ratios and sides
+
+`ratio` is `wide`, `square` or `portrait`. `align` is `media-left` or `media-right`,
+and it changes the visual order only. Below the breakpoint the copy always comes
+first.
+
+### Tone
+
+`default` leaves the band on the page ground. `muted` puts it on the muted surface,
+which is for a band that is a chapter rather than a transition. The muted arm states
+its own ink as well as its own fill.
+
+### The media slot
+
+The caller's node fills the frame. The Block does not style a node it did not
+render, so the image should set its own width, height and `object-fit`, and it
+should carry the alt text that names it. A composed figure should carry its own
+accessible name.
+
+**The band with a placeholder in the media slot.**
+
+```tsx
+import { ImageIcon } from 'lucide-react'
+
+import { MediaBand01 } from '@nanisoft/prism-ui/blocks/media-band-01'
+
+/**
+ * The band with a placeholder in the media slot.
+ *
+ * The slot is the point: a marketing band's picture is the consumer's asset, and
+ * the demo shows the frame the Block owns rather than a photograph this package
+ * would have to license. A real caller passes an image, a video poster or a
+ * composed figure, and the frame holds it at the ratio the caller chose.
+ */
+export default function MediaBand01Demo() {
+  return (
+    <MediaBand01
+      headingLevel="h3"
+      eyebrow="Preview"
+      size="default"
+      title="A photograph, a statement and one way forward"
+      description="The copy is first in the document and the media is first only in the visual order the caller asks for. The frame holds a wide, square or portrait crop, and the copy never sits on the picture."
+      media={
+        <div className="bg-accent text-accent-foreground flex h-full w-full flex-col items-center justify-center gap-3">
+          <ImageIcon className="size-8" aria-hidden />
+          <span className="font-mono text-xs">media slot</span>
+        </div>
+      }
+      caption="A placeholder in the slot. The caller supplies the image and its accessible name."
+      action={{ label: 'Read the story', href: '#' }}
+    />
+  )
+}
+```
+
+## Props
+
+**`eyebrow`** `string` · optional · default: — — Optional label above the title. See the No-Default-Eyebrow Rule.
+**`title`** `ReactNode` · required · default: — — The band's one claim. Required: a band with no title is a picture.
+**`description`** `ReactNode` · optional · default: — — One or two sentences under the title.
+**`media`** `ReactNode` · required · default: — — The media, composed by the caller. A slot rather than a `src`, because the honest media here is not always an image: it is a photograph, a video poster, a rendered figure, or a composition of the consumer's own components. The Block owns the frame, the ratio and the surface, and the caller owns the node and its accessible name. **The node fills the frame.** The caller's image or figure should be sized to its container and should set its own `object-fit`; the Block does not style a node it did not render, which is the same rule every slot in this package follows.
+**`align`** `'media-left' | 'media-right'` · optional · default: `'media-right'` — Which side the media sits on at the wide breakpoint. Below the breakpoint the copy always comes first, because the title is the way into the picture and a reader on a phone should not have to scroll past a photograph to learn what it is for.
+**`ratio`** `MediaBand01Ratio` · optional · default: `'wide'` — The shape the media frame holds.
+**`tone`** `'default' | 'muted'` · optional · default: `'default'` — The surface the band is drawn on. `default` leaves it on the page ground, which is the quieter answer and the right one for a band that is one moment among several. `muted` puts it on the muted surface, for a band that is a chapter of its own. The muted arm states its own ink as well as its own fill, which is the `Stated Ink Rule` `Cta01` and `Bento01` both state: a surface that sets a fill and inherits its ink is correct wherever the design system happened to put it and wrong everywhere else.
+**`caption`** `ReactNode` · optional · default: — — One line under the media. Functional, not decorative: it says what a reader is looking at when the photograph is a placeholder or when the image is not the product itself. It is never a photo credit for a placeholder, and it is never a caption for a picture whose subject the title already names.
+**`action`** `MediaBand01Action` · optional · default: — — The band's one action. Omit it for a band that is a statement and not an ask.
+**`size`** `MediaBand01Size` · optional · default: `'tall'` — How tall the band is. See `MediaBand01Size`.
+**`headingLevel`** `HeadingLevel` · optional · default: `'h2'` — Heading level for the title. See `HeadingLevel`.
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Block. Changing a Prism-owned visual property from here is prohibited.
+
+## Composition
+
+**`exports`** `MediaBand01` — the public runtime names this Block promises
+**`source`** `packages/ui/src/blocks/media-band-01/index.tsx` — the file this Block is defined in
+**`dependencies`** `AspectRatio, CtaLink, Section` — the public Prism exports this item composes
+
+
 ---
 
 # MemberList01
@@ -56677,6 +57227,11 @@ none of the four and would rather compose its own.
 - Leave `sticky` on unless the page does not scroll. The bar is how a reader leaves
   the page they are on, and it takes that with them on exactly the long pages where
   it is needed. `sticky={false}` is honoured and puts the bar back in the flow.
+- Leave `scrollRail` on for pages a reader reads end to end. The rail fills with
+  the reader's own progress, a browser that cannot run it draws no rail at all,
+  and a reader who asked for less motion gets a still spectrum hairline. Turn
+  it off on a short page, where a rail that is born nearly full misreads the
+  page it is on.
 
 ### Content guidelines
 
@@ -56715,9 +57270,25 @@ Two things to know if you were styling against the old bar:
 - A rule that relied on the bar being translucent to hide a scrolling heading will
   no longer hide it, which is the point.
 
-`will-change` is not on the bar and is not proposed for it. Nothing on the bar
-animates, so a compositing hint applied at rest has no frame to be ready for and
-nothing that would release it.
+`will-change` is not on the bar and is not proposed for it. Two things on the bar
+move, the current link's underline and the reading rail, and both are compositor
+transforms the browser promotes while they run, so a hint applied at rest has no
+frame to be ready for and nothing that would release it.
+
+### The reading rail, and the current link's underline
+
+The sticky bar carries a two-pixel spectrum line on its bottom hairline, filled
+left to right by the page's own scroll. It is the travel figure at the scale of a
+page: one marker, one rail, the reader's hand providing the motion. The whole
+figure lives behind a capability check in the stylesheet, so a browser without
+scroll-driven animations draws no rail rather than an empty one, and the rail is
+`aria-hidden` because a reading position the scrollbar already shows is not
+information the bar needs to announce.
+
+The current link is marked by a persistent underline in the same spectrum rather
+than by a filled pill, so the bar carries one indicator language on one edge. The
+underline is shape rather than colour, and `aria-current` still says the page to
+a reader who sees nothing at all.
 
 ### The one client boundary
 
@@ -56834,6 +57405,7 @@ export default function SiteNavbarDemo() {
 **`mobileLabels`** `SiteNavMobileLabels` · required · default: — — The two names of the mobile trigger, which is a round icon with no visible word. Required rather than defaulted, because a default would be a sentence this Block ships about a product that is not the caller's, and because a bar that renders an unlabelled round control below its own threshold has a keyboard reader reaching for something it cannot name.
 **`actions`** `ReactNode` · optional · default: — — A slot for controls the product owns, after the ones this bar composes. A slot rather than a prop, because an account menu and a sign-in link are application state and neither is a fact a bar can be told.
 **`sticky`** `boolean` · optional · default: — — Keeps the bar at the top of the viewport as the page scrolls. On by default, because the bar is how a reader leaves the page they are on, and a bar that scrolls away takes that with it on exactly the long pages a reader needs it. `false` is honoured: the bar is then part of the flow and scrolls away with the page. It was accepted and ignored until this release, so a site that passed it was given the sticky bar it had asked not to have, and `SiteHeader` has always applied it the other way round.
+**`scrollRail`** `boolean` · optional · default: `true` — Draws the reading rail: a two-pixel spectrum line on the bar's bottom hairline that fills with the reader's own progress through the page. On by default, because the rail is the one motion that costs a reader nothing: it is bound to the scroll position the reader already owns, it runs on a transform, and a browser that cannot run it draws no rail rather than an empty promise of one. A reader who asked the platform for less motion gets a still spectrum hairline, the same figure without the claim. `false` is for the pages the rail would misread: a short page whose scroll never gets going, or a composition where a second line under the bar is a line too many. The rail rides only a sticky bar, so `sticky={false}` takes it regardless.
 **`className`** `string` · optional · default: — — Layout only. Changing a Prism-owned visual property from here is prohibited.
 
 ## Composition