feat: the site demonstrates order

CHANGELOG.md

@@ -81,6 +81,9 @@ he copy button said "Your settings, as props — only what you changed", and the
 
 ### Added
 
+- **The site demonstrates `order`.** A capability nobody can see is a capability that quietly stops working, so the seam now has a section of its own with two traversals written the way a reader would write them: a **chevron that accelerates** toward its tips, and **rings that expand from a dot the visitor clicks**. Both answer questions the library's own tables cannot: the shape of a traversal can be anything computable per cell, and its origin can be anywhere.
+- **The demo is deliberately separate from the playground.** `order` is a function, so it cannot travel in the copied settings, and a visitor who reproduced the playground's snippet would silently get the preset's motion instead. Its own field, its own code — and the code shown is the traversals file **imported with `?raw`**, so the source a visitor reads is literally the source that is running and cannot drift from it.
+
 - **You can now supply your own traversal.** `order` takes an `OrderFn` and replaces the preset's — which is the seam the layered design always left open, finally reachable from an option instead of only from a custom renderer. Anything you can compute per cell, you can animate:
 
   ```ts

CHANGELOG.zh.md

@@ -60,6 +60,9 @@ Playground、双语文档与 registry 迁到 Cloudflare Pages 上的 Astro + Rea
 
 ### 新增
 
+- **站点演示 `order`。** 没人能看见的能力，就是会悄悄坏掉的能力，所以这个接缝现在有了自己的版块，包含两个按读者会写的方式写的遍历：一个**向尖端加速的箭头**，以及**从访客点击的那个点扩散的圆环**。两者都回答了库自身表格无法回答的问题：遍历的形状可以是任何能按格计算的东西，而它的起点可以在任何位置。
+- **这个演示刻意与 playground 分开。** `order` 是函数，无法随复制的设置一起传递，而照着 playground 的片段重建组件的人会悄悄拿到 preset 的动效。它有自己的场、自己的代码 —— 而展示的代码是用 `?raw` 导入的遍历文件，所以读者读到的源码就是正在运行的源码，两者不可能漂移。
+
 - **现在可以提供你自己的遍历。** `order` 接受一个 `OrderFn`，替换 preset 自带的 —— 这是分层设计一直留着的接缝，终于能从 option 到达，而不再只存在于自定义渲染器里。你能按格计算的任何东西，都能变成动效：
 
   ```ts

apps/site/messages/en.json

@@ -128,5 +128,11 @@
   "ctl_color_swatch": "Pick a colour",
   "color_hex": "HEX",
   "color_rgb": "RGB",
-  "color_hsl": "HSL"
+  "color_hsl": "HSL",
+  "demo_traversal_title": "Your own traversal",
+  "demo_traversal_which": "Which traversal",
+  "demo_traversal_chevron": "Chevron",
+  "demo_traversal_rings": "Rings",
+  "demo_traversal_click": "Click the field to move the centre.",
+  "demo_traversal_lede": "A traversal is one function of lattice position, so anything you can compute per cell you can animate. These two are not presets — they are `order` functions, written here and running below."
 }

apps/site/messages/zh.json

@@ -128,5 +128,11 @@
   "ctl_color_swatch": "选择颜色",
   "color_hex": "HEX",
   "color_rgb": "RGB",
-  "color_hsl": "HSL"
+  "color_hsl": "HSL",
+  "demo_traversal_title": "你自己的遍历",
+  "demo_traversal_which": "选择遍历",
+  "demo_traversal_chevron": "箭头",
+  "demo_traversal_rings": "圆环",
+  "demo_traversal_click": "点击场来移动中心。",
+  "demo_traversal_lede": "遍历就是「格位置」的单一函数，所以你能按格计算的任何东西都能变成动效。下面这两个不是 preset — 它们是 `order` 函数，就在这里写着，并在下面运行。"
 }

apps/site/src/components/Home.astro

@@ -3,6 +3,7 @@ import Base from '../layouts/Base.astro';
 import { InstallCommand } from './InstallCommand';
 import { Playground } from './Playground';
 import { RegistryList } from './RegistryList';
+import { TraversalDemo } from './TraversalDemo';
 import LocaleSwitch from './LocaleSwitch.astro';
 import { m } from '../paraglide/messages.js';
 import { localizeHref, locales } from '../paraglide/runtime.js';
@@ -51,6 +52,12 @@ const path = Astro.url.pathname;
       <Playground client:load />
     </section>
 
+    <section class="traversal-section">
+      <h2>{m.demo_traversal_title()}</h2>
+      <p class="lede">{m.demo_traversal_lede()}</p>
+      <TraversalDemo client:visible />
+    </section>
+
     <section id={m.nav_components()}>
       <h2>{m.components_heading()}</h2>
       <p class="fine">{m.components_note()}</p>

apps/site/src/components/TraversalDemo.tsx

@@ -0,0 +1,125 @@
+import { useMemo, useState } from "react";
+import { Matrix } from "./Matrix.js";
+import { m } from "../i18n.js";
+import { chevron, nearestCell, ringsFrom } from "../traversals.js";
+// The source of the traversals file, at build time. Shown beside the field so the code a
+// visitor reads IS the code that is running — a hand-kept copy of a function is a copy that
+// lies the first time anyone edits one of them.
+import traversalSource from "../traversals.ts?raw";
+
+// The file, from the first export onward. The header comment explains WHY these exist, which
+// is for us; a visitor's first question is what to copy, and scrolling past five paragraphs
+// of rationale to reach it is the wrong first impression of a code sample.
+const COPYABLE = traversalSource.slice(traversalSource.indexOf("export"));
+
+const N = 9;
+
+/**
+ * The `order` seam, on the page.
+ *
+ * A capability the page cannot demonstrate is a capability that quietly stops working, and
+ * this one has a specific hazard: `order` is a FUNCTION, so it cannot go in the copied
+ * snippet. A visitor who reproduced the settings from the copy button would get the preset's
+ * motion and no indication why. So this demo is deliberately separate from the playground —
+ * its own field, its own settings, its own copy button that copies the CODE — and the code is
+ * right there to paste.
+ *
+ * Two traversals, because they answer two different questions:
+ *
+ *   chevron   the SHAPE of the traversal can be anything you can compute per cell, including
+ *             an easing along its own axis — which is what "accelerating" actually is.
+ *   rings     the ORIGIN can be anywhere, which the library's concentric preset pins to the
+ *             middle. Click the field to move it.
+ */
+export function TraversalDemo() {
+  const [variant, setVariant] = useState<"chevron" | "rings">("chevron");
+  const [origin, setOrigin] = useState({ col: 4, row: 4 });
+
+  // rebuilt whenever the origin moves, and the field below is keyed on it so the engine
+  // re-ranks rather than remounting — the same path a real caller takes
+  const order = useMemo(
+    () => (variant === "chevron" ? chevron : ringsFrom(origin)),
+    [variant, origin],
+  );
+
+  return (
+    <div className="traversal-demo">
+      <div className="traversal-demo-head">
+        <div className="traversal-choices" role="group" aria-label={m.demo_traversal_which()}>
+          <button
+            type="button"
+            className={variant === "chevron" ? "is-on" : undefined}
+            aria-pressed={variant === "chevron"}
+            onClick={() => setVariant("chevron")}
+          >
+            {m.demo_traversal_chevron()}
+          </button>
+          <button
+            type="button"
+            className={variant === "rings" ? "is-on" : undefined}
+            aria-pressed={variant === "rings"}
+            onClick={() => setVariant("rings")}
+          >
+            {m.demo_traversal_rings()}
+          </button>
+        </div>
+        {variant === "rings" && <p className="traversal-hint">{m.demo_traversal_click()}</p>}
+      </div>
+
+      <div className="traversal-demo-body">
+        <div
+          className="traversal-field"
+          onClick={(e) => {
+            if (variant !== "rings") return;
+            const box = e.currentTarget.getBoundingClientRect();
+            // the field is drawn from its centre outward, in the engine's own px geometry
+            const pitch = box.width / N;
+            setOrigin(
+              nearestCell(
+                {
+                  x: e.clientX - box.left - box.width / 2,
+                  y: e.clientY - box.top - box.height / 2,
+                },
+                { x: pitch, y: pitch },
+                N,
+                N,
+              ),
+            );
+          }}
+        >
+          <Matrix
+            cols={N}
+            rows={N}
+            size={260}
+            silhouette="square"
+            dot="circle"
+            dotSize={0.8}
+            gapX={0.12}
+            gapY={0.12}
+            preset={variant === "chevron" ? "morph" : "ripple"}
+            renderer="css"
+            order={order}
+          />
+          {variant === "rings" && (
+            <span
+              className="traversal-origin"
+              style={{
+                left: `${(origin.col / (N - 1)) * 100}%`,
+                top: `${(origin.row / (N - 1)) * 100}%`,
+              }}
+              aria-hidden="true"
+            />
+          )}
+        </div>
+
+        <div className="traversal-code">
+          {/* No caption here: the section's lede already says what these are, and a second
+              copy of the same sentence one inch away is the thing people stop reading. */}
+          <pre>
+            <code>{COPYABLE}</code>
+          </pre>
+        </div>
+      </div>
+    </div>
+  );
+}

apps/site/src/rawprobe.ts

@@ -0,0 +1,2 @@
+import src from "./traversals.ts?raw";
+export const hasRaw = typeof src === "string" && src.includes("chevron");

apps/site/src/styles/site.css

@@ -167,6 +167,115 @@ h3 {
   cursor: pointer;
 }
 
+/* The `order` seam. Separate from the playground on purpose: `order` is a FUNCTION, so it
+   cannot travel in the copied settings, and a visitor who reproduced the playground's
+   snippet would silently get the preset's motion instead. Its own field, its own code. */
+.traversal-demo {
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: var(--card);
+  padding: 16px;
+}
+
+.traversal-demo-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 14px;
+}
+
+.traversal-choices {
+  display: flex;
+  gap: 2px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 2px;
+}
+
+.traversal-choices button {
+  font: inherit;
+  font-size: 13px;
+  border: 0;
+  background: transparent;
+  color: var(--muted);
+  border-radius: 6px;
+  padding: 5px 12px;
+  cursor: pointer;
+}
+
+.traversal-choices button.is-on {
+  background: var(--accent);
+  color: #fff;
+}
+
+.traversal-hint {
+  margin: 0;
+  font-size: 12px;
+  color: var(--muted);
+}
+
+.traversal-demo-body {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  gap: 20px;
+  align-items: start;
+}
+
+.traversal-field {
+  position: relative;
+  line-height: 0;
+  /* the origin marker sits ON a cell, so a cell at the very corner would have half of it
+     clipped by the field's own edge — which is exactly where a visitor clicks first */
+  padding: 6px;
+}
+
+/* only the rings variant is interactive, and saying so with a pointer is cheaper than
+   disabling it: the chevron has no origin to click */
+.traversal-field[role="button"],
+.traversal-field:has(.traversal-origin) {
+  cursor: crosshair;
+}
+
+/* where the rings currently expand from — the one thing the demo is about, so it is drawn
+   rather than described */
+.traversal-origin {
+  position: absolute;
+  width: 7px;
+  height: 7px;
+  margin: -3.5px 0 0 -3.5px;
+  border-radius: 999px;
+  background: var(--accent);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 25%, transparent);
+  pointer-events: none;
+  /* over the dots, which are drawn in `currentColor` at the page's ink */
+  z-index: 1;
+}
+
+.traversal-code p {
+  margin: 0 0 8px;
+  font-size: 12px;
+  color: var(--muted);
+}
+
+.traversal-code pre {
+  margin: 0;
+  padding: 12px 14px;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: var(--bg);
+  font-size: 11px;
+  line-height: 1.6;
+  max-height: 320px;
+  overflow: auto;
+}
+
+@media (max-width: 860px) {
+  .traversal-demo-body {
+    grid-template-columns: 1fr;
+  }
+}
+
 /* The dot colour. Full width like the copy button, and in the sticky pane beside the
    field, because a colour you have to look away from to check is not a colour you are
    choosing. */

apps/site/src/traversals.ts

@@ -0,0 +1,82 @@
+import type { OrderFn } from "@botharness/botui-core";
+
+/**
+ * Two traversals the library does not ship, written the way a reader would write them.
+ *
+ * These exist to demonstrate the `order` seam on the page rather than only in a README: a
+ * capability nobody can see is a capability that quietly stops working. Both are ordinary
+ * `OrderFn`s — a function of lattice position returning `0…1`, where `0` leads.
+ *
+ * The source of this file is shown verbatim beside the field, imported with `?raw`, so the
+ * code a visitor reads cannot drift from the code that is running. A hand-maintained copy
+ * of a function is a copy that lies the first time someone edits one of them.
+ */
+
+/**
+ * A CHEVRON that accelerates toward its tips.
+ *
+ * "Accelerating" is not a property of the traversal's SHAPE but of how the value is
+ * distributed along it: squaring compresses the early differences and stretches the late
+ * ones, so successive dots along each arm start closer together in phase near the tip. A
+ * linear chevron is a chevron; an eased one is a chevron that moves like it is going
+ * somewhere.
+ *
+ * The value mixes distance from the spine with progress along the field, which is what
+ * makes it fold rather than simply translate.
+ */
+export const chevron: OrderFn = (col, row, cols, rows) => {
+  const mid = (rows - 1) / 2;
+  // 0 at the spine, 1 at the outer tips. `|| 1` because a single row has no mid to divide by
+  const arm = Math.abs(row - mid) / (mid || 1);
+  const along = col / (cols - 1 || 1);
+  const v = arm * 0.6 + along * 0.4;
+  // ease-in
+  return v * v;
+};
+
+/**
+ * RINGS expanding from a dot the visitor chooses.
+ *
+ * Chebyshev distance — `max(|dc|, |dr|)` — rather than Euclidean, and that choice is the
+ * whole character: on an integer lattice the Chebyshev radius takes only a handful of
+ * distinct values, so every dot on a ring shares one phase and the field reads as discrete
+ * bands. Euclidean would give nearly every dot its own value and turn the same traversal
+ * into a smooth travelling wave. The concentric `ring` preset is this function with the
+ * origin pinned to the middle; here the origin is a parameter, which is the request the
+ * library's own table could not express.
+ *
+ * Normalised by the largest distance the lattice can hold, so the outermost dot leads at 1
+ * whatever the grid size — otherwise a 9×9 and a 3×3 would animate at different rates for
+ * the same nominal shape.
+ */
+export function ringsFrom(origin: { col: number; row: number }): OrderFn {
+  return (col, row, cols, rows) => {
+    const d = Math.max(Math.abs(col - origin.col), Math.abs(row - origin.row));
+    // The furthest cell in the lattice FROM THE ORIGIN, which is whichever corner is
+    // diagonally opposite it. Normalising by a fixed denominator — `cols`, or
+    // `max(cols, rows)` — is the tempting one-liner and it is wrong twice over: it makes
+    // the outermost dot's value depend on the GRID SIZE rather than on the origin, so a
+    // 9×9 and a 3×3 animate at different rates for the same nominal shape, and it leaves
+    // the last ring short of 1, so the wave never quite arrives.
+    const far = Math.max(origin.col, cols - 1 - origin.col, origin.row, rows - 1 - origin.row);
+    return far > 0 ? Math.min(1, d / far) : 0;
+  };
+}
+
+/** the cell nearest a click, so a visitor can pick the origin with a pointer */
+export function nearestCell(
+  at: { x: number; y: number },
+  pitch: { x: number; y: number },
+  cols: number,
+  rows: number,
+): { col: number; row: number } {
+  // the field is centred, so a click at (0,0) in field space is the top-left cell
+  const cx = (cols - 1) / 2;
+  const cy = (rows - 1) / 2;
+  const col = Math.round(cx + (at.x / pitch.x) * cx);
+  const row = Math.round(cy + (at.y / pitch.y) * cy);
+  return {
+    col: Math.min(cols - 1, Math.max(0, col)),
+    row: Math.min(rows - 1, Math.max(0, row)),
+  };
+}