@nanisoft/prism-llms 0.5.2 → 0.6.0

package/dist/md/components/reveal.md

@@ -0,0 +1,113 @@
+# 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.

package/dist/md/foundation/motion.md

@@ -1,9 +1,9 @@
 # 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
@@ -13,29 +13,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.
+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.
 
-The cycle scale is separate because the two measure different things by a factor
+**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.
+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.
+Three rules bound the ambient layer, 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.
+- **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
@@ -50,8 +67,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" />
 

package/dist/prism-skill.md

@@ -43,8 +43,8 @@ The read-only MCP endpoint is `https://prism.nanisoft.com/mcp`. It exposes nine
 
 ## This corpus
 
-Generated from the catalogue and the authored pages: 132
-Components, 126 Blocks, 18 Pages and 3
+Generated from the catalogue and the authored pages: 135
+Components, 127 Blocks, 18 Pages and 3
 live surfaces, plus the Overview, Foundation, Content, Patterns and Changelogs
 pages. The Changelogs pages are each
 published package's own changelog, byte for byte; `get_changelog` returns one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanisoft/prism-llms",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "type": "module",
   "description": "Prism's agent-facing corpus: llms.txt, the Markdown mirror, prism-skill.md and the PrismDocsStore projection. One build-fresh dist/ serves npm, the site and the MCP server.",
   "license": "MIT",
@@ -38,8 +38,8 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
     "vitest": "^3.2.4",
-    "@nanisoft/prism-tokens": "1.2.0",
-    "@nanisoft/prism-ui": "1.3.0"
+    "@nanisoft/prism-tokens": "1.5.0",
+    "@nanisoft/prism-ui": "1.5.0"
   },
   "scripts": {
     "build": "node scripts/build.mjs",