useGuideStore.getState().replayStep()}>
โป
@@ -172,7 +268,11 @@ function Step({
))}
{copy.warn && {copy.warn}
}
{page === "make" &&
+
+ )}
{copy.note && (
{ui.noteBy}
@@ -196,40 +296,97 @@ function Chapter({
guide,
chapter: { id, label, copy },
lang,
+ late,
}: {
page: GuidePageId;
/** The guide's name ("Play"), for the "Stuck here?" issues. */
guide: string;
chapter: PageChapter;
lang: GuideLang;
+ late: boolean;
}) {
const chapter = `${guide} ยท ${copy.num} ${label}`;
return (
-
-
- {copy.num}
-
- {copy.title}
- {copy.lede}
+
+
+
+
+ {copy.lede}
+
{copy.steps.map((step, i) => (
-
);
}
+// The chapter rail. Its marker is one pill that travels to the chapter the
+// reader is in (measured off that chapter's item, so it fits any label in
+// either language), and the line along the marker's foot fills as the
+// chapter's steps go by: nothing under the chapter's title, then a share a
+// step, full on the last. On top of the rail, over the tip of that line,
+// stands the resident (ui/resident/RailResident): it runs along as the
+// reader goes on. It is play โ hidden from assistive technology, outside the
+// rail's box โ and the rail is what it was without it.
function ChapterRail({ chapters }: { chapters: PageChapter[] }) {
const scene = useGuideStore((s) => s.scene);
+ const step = useGuideStore((s) => s.step);
+ const cardIn = useGuideStore((s) => s.cardIn);
+ const nav = useRef(null);
+ const marker = useRef(null);
+ const index = chapters.findIndex((c) => c.id === scene);
+ const total = index < 0 ? 0 : chapters[index].copy.steps.length;
+ const fill = total ? Math.min(1, (cardIn ? step + 1 : step) / total) : 0;
+
+ useLayoutEffect(() => {
+ const el = nav.current;
+ const m = marker.current;
+ if (!el || !m) return;
+ let frame = 0;
+ const place = (travel: boolean) => {
+ const item = index < 0 ? null : el.querySelectorAll("a")[index];
+ if (!item || item.offsetWidth === 0) {
+ m.dataset.on = "0";
+ return;
+ }
+ // Its first place, and a place after being away, is taken, not travelled to.
+ const still = !travel || m.dataset.on !== "1";
+ if (still) m.dataset.still = "1";
+ m.style.setProperty("--x", `${item.offsetLeft}px`);
+ m.style.setProperty("--w", `${item.offsetWidth}px`);
+ m.dataset.on = "1";
+ el.dataset.marked = "1";
+ if (still) {
+ cancelAnimationFrame(frame);
+ frame = requestAnimationFrame(() => {
+ frame = requestAnimationFrame(() => delete m.dataset.still);
+ });
+ }
+ };
+ place(true);
+ // The items' widths change with the window and with their fonts.
+ const ro = new ResizeObserver(() => place(false));
+ ro.observe(el);
+ return () => {
+ ro.disconnect();
+ cancelAnimationFrame(frame);
+ };
+ }, [index]);
+
return (
-
+
+
+
{copy.num}
{label}
))}
+
);
}
@@ -241,18 +398,42 @@ export default function GuideExperience({ lang, page = "play" }: { lang: GuideLa
const root = useRef(null);
const deskFits = useDeskFits();
- // The stage plays this page's script, from its top: set before the canvas
- // draws a frame, and before the tracker below says where the reader is.
- // Coming from another page the board is the same one (store.ts getSim);
- // the Director puts it in this page's state on its first frame.
- useLayoutEffect(() => {
- useGuideStore.getState().enterPage(page);
- }, [page]);
+ // Reached from another page of the guide, at its top: the cards' extras
+ // come in after the words (ui/Later). Decided once, as the page mounts โ
+ // the store still names the page the reader came from. A page being taken
+ // up from the server's markup, the same guide in its other language (the
+ // reader lands mid-page) and a page reached through the history are whole
+ // from the start.
+ const hydrating = useSyncExternalStore(
+ noSubscription,
+ () => false,
+ () => true,
+ );
+ const [late] = useState(() => {
+ if (hydrating) return false;
+ const s = useGuideStore.getState();
+ return s.entered && s.page !== page && !arrivedByHistory();
+ });
+ // โฆand the blocks below the first screen are laid out after them, each in
+ // its turn (they are marked [data-wait] as they mount; this takes the mark
+ // off, a block at a time, after the extras above have had theirs).
+ useEffect(() => arrived(), []);
+ useEffect(() => {
+ if (!late) return;
+ const waiting = Array.from(root.current?.querySelectorAll("[data-wait]") ?? []);
+ const forget = waiting.map((el) => whenQuiet(() => el.removeAttribute("data-wait")));
+ return () => forget.forEach((f) => f());
+ }, [late]);
+ // The stage plays this page's script, from its top: said before the browser
+ // paints the page, and before the tracker below says where the reader is.
+ // The board is the same one on every page (store.ts getSim); the Director
+ // puts it in this page's state on its next frame. The document says the
+ // page's language meanwhile (darkDocument.ts).
+ useGuidePage(page, lang);
useScrollTracker(root);
-
- // The document goes dark while the guide is open, and says its language (darkDocument.ts).
- useDarkDocument();
- useDocumentLang(lang);
+ useReveal(root);
+ useStepKeys(root);
+ usePanelTint(root);
// Sanity: the copy and the script must agree on how many steps each
// chapter has, in both languages (pages.test.ts holds the same line).
@@ -263,21 +444,8 @@ export default function GuideExperience({ lang, page = "play" }: { lang: GuideLa
return (
- {page === "make" ? (
- // The room only: the desk comes after the story, so the keyboard
- // reaches the cards first (each card's cue line can jump into it).
-
- ) : (
-
- )}
-
+ {/* The first visit's cover; Make has no stage to wait for. */}
+ {page !== "make" &&
}
{copy.langSwitch.label}
-
+
-
+
+ {page === "make" && (
+
+
+ )}
{opening.kicker}
- {opening.title}
+
+
{opening.lede}
{chapters.map((c) => (
@@ -312,10 +488,10 @@ export default function GuideExperience({ lang, page = "play" }: { lang: GuideLa
{opening.back && (
-
โ
{opening.back.label}
-
+
)}
@@ -326,14 +502,18 @@ export default function GuideExperience({ lang, page = "play" }: { lang: GuideLa
{chapters.map((c) => (
-
-
- {next.title}
- {next.lede}
- {next.groups.map((g) => {
+
+
+
+
+ {next.lede}
+
+ {next.groups.map((g, gi) => {
const items = (
{g.items.map((s) => (
@@ -342,24 +522,26 @@ export default function GuideExperience({ lang, page = "play" }: { lang: GuideLa
);
return (
-
+
{g.label}
{g.to ? (
// A guide that exists: the whole group is the way there.
-
+
{items}
โ
-
+
) : (
items
)}
);
})}
-
{next.until}
-
+
+ {next.until}
+
+
-
+
+
diff --git a/web/src/components/guide/GuideHub.tsx b/web/src/components/guide/GuideHub.tsx
index f6f63028..a6ba2a95 100644
--- a/web/src/components/guide/GuideHub.tsx
+++ b/web/src/components/guide/GuideHub.tsx
@@ -1,34 +1,56 @@
"use client";
-import dynamic from "next/dynamic";
import Link from "next/link";
-import { Fragment, useLayoutEffect, useRef, useState, type RefObject } from "react";
+import { Fragment, useEffect, useLayoutEffect, useRef, useState, type RefObject } from "react";
import styles from "./Guide.module.css";
import hub from "./Hub.module.css";
import { COPY } from "./copy";
import { HUB_COPY } from "./copy/hub";
-import { GUIDE_ORDER, PAGES, pagePath } from "./pages";
+import { GUIDE_ORDER, PAGES } from "./pages";
import { hereFor, reportUrl } from "./report";
import { legacyGuideTarget } from "./legacy";
-import { useDarkDocument, useDocumentLang } from "./darkDocument";
-import type { GuideLang, GuidePageId } from "./store";
+import { useGuideStore, type GuideLang, type GuidePageId } from "./store";
+import GuideLink from "./world/GuideLink";
+import { useGuidePage } from "./world/usePage";
+import Preloader from "./ui/Preloader";
+import Words from "./ui/Words";
+import { usePanelTint } from "./ui/panelTint";
+import HubResident from "./ui/resident/HubResident";
// /guide: the hub. One glance, three ways in: Build (soldering one from bare
// parts), Play (it's built), Make (it plays; now their own patterns) โ side
// by side in that order, each a number, a name and the one line a reader
// recognises themselves in. What a guide covers is its own opening's to say;
// here its chapter names only surface under the guide being pointed at. The
-// 3D device stands alone above them, the page's one image (HubStage, loaded
-// after the page, so the words never wait for it), and it answers the guide
-// being pointed at.
+// 3D device stands alone above them, the page's one image, and it answers
+// the guide being pointed at.
+//
+// The device is not this page's: the stage is mounted above the pages, once
+// for the whole guide (world/GuideWorld โ loaded after the page, so the
+// words never wait for it), and the hub is one of the pages that play on it.
+// This page tells the stage three things, all through the store: that the
+// hub is on screen (useGuidePage), where its choices start (setHubTop โ the
+// device is framed above them, world/framing.ts), and which guide the reader
+// is pointing at (setPreview). The answers are the stage's (world/HubAnswers,
+// stage/Explode): Build โ the device comes apart; Play โ K1 turns and the
+// pattern follows; Make โ the pattern is made again and again. Choosing a
+// guide (GuideLink) holds its answer while the words leave, and the guide's
+// opening takes it from there: the parts settle, the camera pushes in, the
+// device stands back for the desk.
+//
+// On the rule over the three guides stands the resident (ui/resident): a
+// figure a few LED cells tall that walks to the guide being pointed at, and
+// can be walked with โ and โ โ the guide it stands over is then the chosen
+// one (`walked`: the same state as pointing at it, kept here so the column
+// can show it), and Enter goes in. It is play, and nothing depends on it:
+// the three links, their order for Tab, and what a click does are as they
+// were. The mouse takes the choice back by moving.
//
// /guide used to be the Play guide. Its old anchors (#flash, #knobs-3, โฆ)
// are sent on to /guide/play (legacy.ts): on a page load by the root
// layout's script, before the hub is parsed; here when the hub is reached
// without one, before it paints.
-const HubStage = dynamic(() => import("./HubStage"), { ssr: false });
-
function useLegacyAnchors() {
useLayoutEffect(() => {
const d = document.documentElement;
@@ -52,14 +74,14 @@ function useLegacyAnchors() {
}, []);
}
-// Where the choices start, from the top of the page: the stage is a box round
-// what is above them (Hub.module.css .stageBox reads --hub-top).
-function useChoicesTop(page: RefObject
, choices: RefObject) {
+// Where the choices start, from the top of the page: the stage frames the
+// device in what is above them, and fades its floor out behind them
+// (store.hubTop โ world/framing.ts hubFraming, Guide.module.css --hub-top).
+function useChoicesTop(choices: RefObject) {
useLayoutEffect(() => {
- const root = page.current;
const el = choices.current;
- if (!root || !el) return;
- const measure = () => root.style.setProperty("--hub-top", `${Math.round(el.getBoundingClientRect().top + window.scrollY)}px`);
+ if (!el) return;
+ const measure = () => useGuideStore.getState().setHubTop(Math.round(el.getBoundingClientRect().top + window.scrollY));
measure();
// The choices grow and shrink with the window's width and with their fonts.
const ro = new ResizeObserver(measure);
@@ -69,32 +91,38 @@ function useChoicesTop(page: RefObject, choices: RefObject(null);
- const page = useRef(null);
+ const root = useRef(null);
const choices = useRef(null);
+ // The guide chosen by walking the resident to it (ui/resident/HubResident), or null.
+ const [walked, setWalked] = useState(null);
useLegacyAnchors();
- useDarkDocument();
- useDocumentLang(lang);
- useChoicesTop(page, choices);
-
- const leave = (id: GuidePageId) => setGuide((g) => (g === id ? null : g));
+ useGuidePage("hub", lang);
+ useChoicesTop(choices);
+ // The page's accent follows the colour on the panel (ui/panelTint.ts).
+ usePanelTint(root);
+ // Nothing is pointed at once the hub is gone (the store outlives it; a guide's own arrival clears it too).
+ useEffect(() => () => useGuideStore.setState({ preview: null }), []);
return (
-
-
-
+
+ {/* The first visit's cover, while the stage loads (ui/Preloader). */}
+
- {/* data-scene / data-step: what the stage frames the device against (GuideCanvas freeArea; Hub.module.css .frame). */}
-
-
+
{words.kicker} {words.title}
-
+ {
+ if (walked === null || e.pointerType !== "mouse") return;
+ setWalked(null);
+ const under = (e.target as Element).closest?.("[data-guide]")?.dataset.guide as GuidePageId | undefined;
+ useGuideStore.getState().setPreview(under ?? null);
+ }}
+ >
{GUIDE_ORDER.map((id, i) => {
const text = PAGES[id].text(lang);
const inside = `hub-${id}-inside`;
return (
-
- {
- if (e.pointerType === "mouse") setGuide(id);
+ if (e.pointerType === "mouse") point(id);
+ }}
+ onPointerLeave={() => pointAway(id)}
+ onFocus={() => {
+ // The focus is a pointing of its own: it takes over from the walk.
+ setWalked(null);
+ point(id);
}}
- onPointerLeave={() => leave(id)}
- onFocus={() => setGuide(id)}
- onBlur={() => leave(id)}
+ onBlur={() => pointAway(id)}
>
{String(i + 1).padStart(2, "0")}
- {text.name}
+
+
โ
{words.guides[id].situation}
-
+
{/* What is inside, for the guide being pointed at. A name never breaks in two: the line turns after its dot. */}
{text.chapters.map((c, n) => (
diff --git a/web/src/components/guide/Hub.module.css b/web/src/components/guide/Hub.module.css
index 6a93753c..acdb5045 100644
--- a/web/src/components/guide/Hub.module.css
+++ b/web/src/components/guide/Hub.module.css
@@ -1,46 +1,15 @@
/* The hub (/guide, GuideHub): the guide's dark room with the device alone in
the middle of it, and under it three ways in โ a number, a name, one line
โ side by side in the order a reader goes through them. The page's own
- words are in Guide.module.css (.page, .stage, .top, .report); the choices
- and the hub's stage are here. */
+ words are in Guide.module.css (.page, .top, .report), and so is the stage,
+ which is the whole guide's (.stage, .hubGlow, .canvasBox: the device above
+ the choices, its floor fading out behind them); the choices are here. */
.page {
/* The guides' names: the page's large type. */
--hub-name: clamp(52px, 6vw, 96px);
/* The side margin the choices keep. */
--hub-side: 6vw;
- /* Where the choices start, from the top of the page (GuideHub measures it). */
- --hub-top: 66vh;
-}
-
-/* โโ the stage โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ */
-
-/* The stage is a box round the part of the screen above the choices, so the
- device stands in the middle of that and not of the whole screen. The
- camera (GuideCanvas) shows the device 0.6 of its canvas's height, centred
- 16px below the canvas's middle (it keeps 64px free at the top and 32px at
- the bottom); a box this tall, this far up, stands the device from 72px
- under the top of the screen to 56px above the choices. The box's foot
- runs on behind the choices and fades out there, so the floor has no edge. */
-.stageBox {
- --box-top: calc(99px - var(--hub-top) / 3);
- --fade: calc(var(--hub-top) - var(--box-top));
- position: absolute;
- left: 0;
- right: 0;
- top: var(--box-top);
- height: calc(var(--hub-top) * 1.667 - 213px);
- -webkit-mask-image: linear-gradient(#000 min(100% - 64px, var(--fade) - 36px), transparent min(100%, var(--fade) + 52px));
- mask-image: linear-gradient(#000 min(100% - 64px, var(--fade) - 36px), transparent min(100%, var(--fade) + 52px));
-}
-.glow {
- position: absolute;
- inset: 0;
- pointer-events: none;
- background:
- radial-gradient(30% 44% at 50% calc(var(--hub-top) / 2 + 8px), rgba(255, 106, 61, 0.07), transparent 70%),
- radial-gradient(64% 62% at 50% calc(var(--hub-top) / 2), rgba(90, 110, 160, 0.06), transparent 70%),
- radial-gradient(120% 120% at 50% 50%, transparent 55%, rgba(0, 0, 0, 0.55) 100%);
}
/* โโ the choices โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ */
@@ -60,21 +29,32 @@
align-items: end;
pointer-events: auto;
}
-/* What the stage frames the device against (GuideCanvas freeArea, by
- [data-step]): its top is where the choices start, which is what a narrow
- screen's stage reads, and its left edge is the screen's right, which is
- what a wide one's reads โ nothing stands beside the device. */
-.frame {
- position: absolute;
- top: 0;
- left: calc(100% + var(--hub-side));
- width: 0;
- height: 0;
+/* The hub arrives the way a poster is set: the sentence, then each guide in
+ turn, left to right โ its rule drawn, its number, its name up from behind
+ a mask (Guide.module.css .wordsNow), its line. Once, as the page comes in;
+ under the first visit's cover it waits for the cover to lift. */
+@keyframes hubLine {
+ from {
+ opacity: 0;
+ transform: translate3d(0, 14px, 0);
+ }
+}
+@keyframes hubDraw {
+ from {
+ transform: scaleX(0);
+ }
+}
+.title,
+.inner .report {
+ animation: hubLine 0.9s var(--g-out) backwards;
+}
+.inner .report {
+ animation-delay: 620ms;
}
-
/* The page's one sentence, small: the names are the large type. */
.title {
- margin: 0 0 18px;
+ /* Room under it for the resident (ui/resident), who stands on the rule below: 18 px of figure, 8 of air. */
+ margin: 0 0 26px;
font-size: 17px;
line-height: 1.4;
font-weight: 500;
@@ -93,7 +73,7 @@
.inner .report {
grid-column: 2;
grid-row: 1;
- margin: 0 0 20px;
+ margin: 0 0 28px;
}
.guides {
@@ -106,9 +86,39 @@
list-style: none;
}
.guide {
+ /* Its place in the row: what arrives in it waits its turn. */
+ --at: calc(120ms + var(--c, 0) * 110ms);
position: relative;
- border-top: 1px solid var(--g-hair-2);
- transition: border-color 0.25s;
+}
+.guide:nth-child(2) {
+ --c: 1;
+}
+.guide:nth-child(3) {
+ --c: 2;
+}
+/* Its rule: a hairline, drawn as the page arrives; and over it, when the
+ guide is pointed at, a line of the panel's light drawn the same way. */
+.guide::before,
+.guide::after {
+ content: "";
+ position: absolute;
+ top: 0;
+ left: 0;
+ right: 0;
+ height: 1px;
+ transform-origin: 0 50%;
+ pointer-events: none;
+}
+.guide::before {
+ background: var(--g-hair-2);
+ animation: hubDraw 1.2s var(--g-io) backwards;
+ animation-delay: calc(var(--at) - 120ms);
+}
+.guide::after {
+ background: var(--g-led);
+ box-shadow: 0 0 14px rgb(var(--g-led-rgb) / 0.7);
+ transform: scaleX(0);
+ transition: transform 0.7s var(--g-out);
}
/* The way in: the whole column, its foot included (::after lies over all of it). */
.go {
@@ -122,7 +132,7 @@
padding: 16px 0 10px;
color: var(--g-ink);
text-decoration: none;
- transition: opacity 0.25s;
+ transition: opacity 0.35s ease;
}
.go::after {
content: "";
@@ -149,6 +159,9 @@
font-variant-numeric: tabular-nums;
letter-spacing: 0.06em;
color: var(--g-led);
+ animation: hubLine 0.9s var(--g-out) backwards;
+ animation-delay: var(--at);
+ transition: color 0.3s;
}
.arrow {
grid-area: arrow;
@@ -156,10 +169,11 @@
line-height: 1;
color: var(--g-led);
opacity: 0;
- transform: translateX(-10px);
+ transform: translate3d(-14px, 0, 0);
transition:
- opacity 0.25s,
- transform 0.25s;
+ opacity 0.3s ease,
+ transform 0.6s var(--g-out),
+ color 0.3s;
}
.name {
grid-area: name;
@@ -172,6 +186,10 @@
.page:lang(ko) .name {
letter-spacing: -0.035em;
}
+.name {
+ /* The name's own turn (Guide.module.css .wordsNow reads --at). */
+ --at: calc(160ms + var(--c, 0) * 110ms);
+}
.situation {
grid-area: situation;
margin-top: 12px;
@@ -179,6 +197,8 @@
font-size: 16px;
line-height: 1.4;
color: var(--g-ink-2);
+ animation: hubLine 0.9s var(--g-out) backwards;
+ animation-delay: calc(var(--at) + 260ms);
}
/* What is inside, only for the guide being pointed at. It is the column's
foot and always there, so showing it moves nothing; the foot is as tall as
@@ -193,8 +213,11 @@
letter-spacing: 0.02em;
color: var(--g-ink-3);
opacity: 0;
+ transform: translate3d(0, 6px, 0);
pointer-events: none;
- transition: opacity 0.25s;
+ transition:
+ opacity 0.3s ease,
+ transform 0.6s var(--g-out);
}
/* A chapter's name, with the dot after it: the line turns between names, never inside one. */
.chapter {
@@ -203,11 +226,12 @@
/* Pointed at, with the keyboard or the mouse: its line lights, its arrow
and what is inside it show, and the other two step back. */
-.guide:has(.go:focus-visible) {
- border-top-color: var(--g-led);
+.guide:has(.go:focus-visible)::after {
+ transform: none;
}
.go:focus-visible ~ .inside {
opacity: 1;
+ transform: none;
}
.go:focus-visible .arrow {
opacity: 1;
@@ -216,21 +240,40 @@
.guides:has(.go:focus-visible) .go:not(:focus-visible) {
opacity: 0.42;
}
+/* (Not while a guide is chosen by walking the resident to it โ below: the
+ mouse may be resting on another, and it points again when it moves.) */
@media (hover: hover) {
- .guide:has(.go:hover) {
- border-top-color: var(--g-led);
+ .guides:not([data-walk]) .guide:has(.go:hover)::after {
+ transform: none;
}
- .go:hover ~ .inside {
+ .guides:not([data-walk]) .go:hover ~ .inside {
opacity: 1;
+ transform: none;
}
- .go:hover .arrow {
+ .guides:not([data-walk]) .go:hover .arrow {
opacity: 1;
transform: none;
}
- .guides:has(.go:hover) .go:not(:hover) {
+ .guides:not([data-walk]):has(.go:hover) .go:not(:hover) {
opacity: 0.42;
}
}
+/* Chosen by walking the resident to it with โ and โ (GuideHub `walked`,
+ ui/resident/HubResident): the same as being pointed at. */
+.guides[data-walk] .guide[data-here]::after {
+ transform: none;
+}
+.guides[data-walk] .guide[data-here] .inside {
+ opacity: 1;
+ transform: none;
+}
+.guides[data-walk] .guide[data-here] .arrow {
+ opacity: 1;
+ transform: none;
+}
+.guides[data-walk] .guide:not([data-here]) .go {
+ opacity: 0.42;
+}
/* A short window: the names give way before the page scrolls. */
@media (min-width: 900px) and (max-height: 820px) {
@@ -244,24 +287,11 @@
/* โโ narrow screens โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ */
-/* Under 900px the stage is the whole screen, and its camera keeps the device
- above the choices (HubStage: the stage's narrow framing). */
+/* Under 900px the camera keeps the device above the choices (world/framing.ts hubFraming). */
@media (max-width: 899px) {
.page {
--hub-side: 20px;
}
- .stageBox {
- inset: 0;
- height: auto;
- -webkit-mask-image: none;
- mask-image: none;
- }
- .glow {
- background:
- radial-gradient(70% 34% at 50% 28%, rgba(255, 106, 61, 0.07), transparent 70%),
- radial-gradient(120% 50% at 50% 28%, rgba(90, 110, 160, 0.06), transparent 70%),
- radial-gradient(140% 120% at 50% 50%, transparent 55%, rgba(0, 0, 0, 0.55) 100%);
- }
/* On a short phone the choices scroll up under the top bar; it keeps a dark ground to stay legible. */
.top {
background: linear-gradient(rgba(10, 9, 8, 0.94) 55%, rgba(10, 9, 8, 0));
@@ -272,6 +302,19 @@
padding-top: 38vh;
padding-bottom: 18px;
}
+ /* The floor ends above the choices here too. Wide, the canvas is masked
+ (Guide.module.css [data-foot]); here the room's dark rises behind the
+ words instead โ no mask for a phone to draw the stage through. Without
+ it the kicker, set in the panel's colour, stood on the floor's
+ reflection of that same colour. */
+ .inner::before {
+ content: "";
+ position: absolute;
+ z-index: -1;
+ inset: -48px calc(-1 * var(--hub-side)) -18px;
+ pointer-events: none;
+ background: linear-gradient(rgba(10, 9, 8, 0), rgba(10, 9, 8, 0.6) 30px, rgba(10, 9, 8, 0.9) 48px, var(--g-ground) 84px);
+ }
/* Nothing hovers on a phone: each way in shows it is one. */
.arrow {
color: var(--g-ink-3);
@@ -372,13 +415,21 @@
}
@media (prefers-reduced-motion: reduce) {
- .guide,
+ .guide::after,
.go,
.arrow,
.inside {
transition: none;
}
- .arrow {
+ .arrow,
+ .inside {
transform: none;
}
+ .title,
+ .inner .report,
+ .guide::before,
+ .num,
+ .situation {
+ animation: none;
+ }
}
diff --git a/web/src/components/guide/HubStage.tsx b/web/src/components/guide/HubStage.tsx
deleted file mode 100644
index 421349c0..00000000
--- a/web/src/components/guide/HubStage.tsx
+++ /dev/null
@@ -1,101 +0,0 @@
-"use client";
-
-import { useEffect, useLayoutEffect } from "react";
-import GuideCanvas from "./stage/GuideCanvas";
-import hub from "./Hub.module.css";
-import { knobIsTurned, turnBackClick, turnBackNow, turnOn } from "./hubKnob";
-import { getSim, useGuideStore, type GuidePageId } from "./store";
-
-// The hub's stage: the same 3D device the guides use, playing the hub's
-// script (scenes.ts HUB_SCENES โ Play's opening, turning slowly beside the
-// choices). Loaded on its own, after the page (GuideHub), so the hub's
-// words never wait for the board, the simulator or three.js.
-//
-// The hub has no scroll story, so nothing here tracks the scroll: the stage
-// stays on the opening. Its canvas is a box round the part of the screen
-// above the choices (Hub.module.css .stageBox), and the camera fits the
-// device into that (GuideCanvas freeArea reads the hub's [data-scene]).
-//
-// The device answers the guide the reader is pointing at (mouse or keyboard),
-// with what that guide is about: Build โ the panel is dark, it has not had
-// its first light yet; Play โ K1 turns and Origin's colour follows; Make โ
-// someone's own pattern is on the panel. Pointing away powers it back on,
-// turns K1 back to where it was and puts Origin back. The script only sets
-// the board on a step change, and the hub never changes step, so the board
-// stays as it is put here. Nothing answers under reduced motion.
-//
-// The board is the same one in every guide (store.ts getSim), so the hub
-// hands it on as it found it: Play's words call Origin red, and a hue left
-// turned here would open that guide in another colour (hubKnob.ts keeps the
-// count and turns it back).
-
-/** The pattern the panel shows for Make: a community one from the Basics pack, a picture where Origin is tiles. */
-const MAKE_PATTERN = "midsummer_sea";
-/** Play: one click of K1 (Origin's hue, which wraps) this often, in ms. */
-const PLAY_CLICK_MS = 120;
-/** Pointing away from Play: K1 turns back a click this often, in ms. */
-const BACK_CLICK_MS = 16;
-/** Build and Make: how often the board is put back in its answer while pointed at, in ms. */
-const HOLD_MS = 300;
-
-export default function HubStage({ guide }: { guide: GuidePageId | null }) {
- useLayoutEffect(() => {
- const store = useGuideStore.getState();
- store.enterPage("hub");
- const onResize = () => useGuideStore.getState().setNarrow(window.innerWidth < 900);
- onResize();
- window.addEventListener("resize", onResize);
- return () => window.removeEventListener("resize", onResize);
- }, []);
-
- useEffect(() => {
- const sim = getSim();
- if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
- turnBackNow(sim);
- return;
- }
- if (!guide) {
- // Pointing away from Play: the knob turns back and the colour comes
- // home with it, a click at a time.
- if (!knobIsTurned()) return;
- const timer = window.setInterval(() => {
- if (turnBackClick(sim)) window.clearInterval(timer);
- }, BACK_CLICK_MS);
- return () => window.clearInterval(timer);
- }
- if (guide !== "play") turnBackNow(sim);
- const answer =
- guide === "build"
- ? () => sim.setMode("off")
- : guide === "play"
- ? () => turnOn(sim)
- : () => {
- sim.setPack("basics");
- sim.showPattern(MAKE_PATTERN);
- };
- answer();
- // Play's is a turning knob. The other two are a state, said again now and
- // then: the stage sets the board once when it first draws, which can come
- // after a guide is already being pointed at.
- const timer = window.setInterval(answer, guide === "play" ? PLAY_CLICK_MS : HOLD_MS);
- return () => {
- window.clearInterval(timer);
- // Power on fades the frame up (deviceSim render).
- if (guide === "build") sim.setMode("run");
- if (guide === "make") {
- sim.showPattern("origin");
- sim.setPack("origin");
- }
- };
- }, [guide]);
-
- // Leaving the hub โ into a guide, most often Play, with K1 still turned.
- // After the effect above, whose own leaving puts the board back on Origin.
- useEffect(() => () => turnBackNow(getSim()), []);
-
- return (
-
-
- );
-}
diff --git a/web/src/components/guide/LabShots.module.css b/web/src/components/guide/LabShots.module.css
index 50727310..1aec4323 100644
--- a/web/src/components/guide/LabShots.module.css
+++ b/web/src/components/guide/LabShots.module.css
@@ -80,8 +80,8 @@
border-radius: 7px;
pointer-events: none;
box-shadow:
- 0 0 0 3px rgba(255, 106, 61, 0.2),
- 0 0 16px rgba(255, 106, 61, 0.32);
+ 0 0 0 3px rgb(var(--g-led-rgb, 255 106 61) / 0.2),
+ 0 0 16px rgb(var(--g-led-rgb, 255 106 61) / 0.32);
animation:
ringIn 0.42s cubic-bezier(0.2, 0.7, 0.2, 1) 0.22s both,
ringBreathe 1.9s ease-in-out 0.7s infinite;
@@ -100,13 +100,13 @@
0%,
100% {
box-shadow:
- 0 0 0 3px rgba(255, 106, 61, 0.2),
- 0 0 16px rgba(255, 106, 61, 0.32);
+ 0 0 0 3px rgb(var(--g-led-rgb, 255 106 61) / 0.2),
+ 0 0 16px rgb(var(--g-led-rgb, 255 106 61) / 0.32);
}
50% {
box-shadow:
- 0 0 0 6px rgba(255, 106, 61, 0.08),
- 0 0 24px rgba(255, 106, 61, 0.45);
+ 0 0 0 6px rgb(var(--g-led-rgb, 255 106 61) / 0.08),
+ 0 0 24px rgb(var(--g-led-rgb, 255 106 61) / 0.45);
}
}
@@ -144,7 +144,7 @@
inset: -6px -3px;
}
.dot[data-done="1"] {
- border-color: rgba(255, 106, 61, 0.35);
+ border-color: rgb(var(--g-led-rgb, 255 106 61) / 0.35);
color: var(--g-ink-2, rgba(239, 233, 221, 0.78));
}
.dot[data-on="1"] {
@@ -174,6 +174,7 @@
margin-top: 10px;
}
.text {
+ text-wrap: pretty;
grid-area: 1 / 1;
margin: 0;
font-size: 13px;
diff --git a/web/src/components/guide/build/Build.module.css b/web/src/components/guide/build/Build.module.css
index c948951b..86304d3c 100644
--- a/web/src/components/guide/build/Build.module.css
+++ b/web/src/components/guide/build/Build.module.css
@@ -68,6 +68,22 @@
.bomRow {
border-bottom: 1px solid var(--g-hair);
}
+/* The line and its part on the stage point at each other
+ (stage/build/touchState.ts): under the mouse here its part lifts on the
+ bench, and with the mouse on the part there, its line is lit here. */
+.bomRow .bomPart,
+.bomRow .bomRef {
+ transition: color 0.18s ease;
+}
+.bomRow[data-lit="1"] .bomPart,
+.bomRow[data-lit="1"] .bomRef {
+ color: var(--g-led);
+}
+@media (hover: hover) {
+ .bomRow:hover .bomRef {
+ color: var(--g-led);
+ }
+}
.bomHead {
display: grid;
grid-template-columns: 42px minmax(0, 1fr) auto 12px;
@@ -189,7 +205,7 @@ summary.bomHead:hover .bomChev,
font-size: 12.5px;
}
.linkFirst {
- border-color: rgba(255, 106, 61, 0.6);
+ border-color: rgb(var(--g-led-rgb, 255 106 61) / 0.6);
background: var(--g-led-wash);
}
.bomNote {
@@ -220,7 +236,7 @@ summary.bomHead:hover .bomChev,
background 0.2s;
}
.checks li[data-done="1"] {
- border-color: rgba(255, 106, 61, 0.45);
+ border-color: rgb(var(--g-led-rgb, 255 106 61) / 0.45);
background: var(--g-led-wash);
}
.checks label {
diff --git a/web/src/components/guide/build/BuildCards.tsx b/web/src/components/guide/build/BuildCards.tsx
index a0dc02ff..c70b2082 100644
--- a/web/src/components/guide/build/BuildCards.tsx
+++ b/web/src/components/guide/build/BuildCards.tsx
@@ -1,7 +1,7 @@
"use client";
import Link from "next/link";
-import { useSyncExternalStore } from "react";
+import { useEffect, useSyncExternalStore, type FocusEvent, type PointerEvent } from "react";
import guide from "../Guide.module.css";
import styles from "./Build.module.css";
import { BUILD_COPY, type BuildLink } from "../copy/build";
@@ -9,6 +9,7 @@ import type { GuideLang } from "../store";
import { BOM_URL, PANEL_PART, bomKey, dashed, times, type BomRow } from "./bom";
import { useBom } from "./BomContext";
import { CHECK_CARDS, LINK_CARDS, type BuildCard, type CheckCard, type LinkCard } from "./cards";
+import { cardTouch, nameParts, stageTouch, subscribeTouch, touchFromCard } from "../stage/build/touchState";
// The cards inside the Build guide's steps (a step's `extra`, "build:",
// copy/build.ts): the parts list โ the BOM file itself, read when the page
@@ -131,6 +132,40 @@ function Checklist({ id, items }: { id: string; items: { label: string; aside?:
// One line is not folded away: the LED panel. It is bought by its listing,
// and it is the part that goes wrong โ so its line carries the listing
// BUILD_GUIDE ยง1 recommends and the way to docs/panel-compatibility.md.
+//
+// The list and the stage point at each other (stage/build/touchState.ts): a
+// line under the mouse, or with the keyboard on it, lifts and lights its part
+// on the bench; a part under the mouse on the stage lights its line here.
+// Nothing else about a line changes โ it opens and reads as it did.
+
+/** What a line's part is called beside it on the stage: its reference and its name, as the line has them. */
+function stageName(r: BomRow, name: string): string {
+ return r.ref === "-" ? name : `${dashed(r.ref.replace(" (sockets)", ""))} ยท ${name}`;
+}
+
+/** The line's side of the pointing: what to put on its . */
+function usePartTouch(key: string) {
+ const lit = useSyncExternalStore(
+ subscribeTouch,
+ () => stageTouch() === key,
+ () => false,
+ );
+ const away = () => {
+ if (cardTouch() === key) touchFromCard(null);
+ };
+ return {
+ "data-lit": lit ? "1" : undefined,
+ onPointerEnter: (e: PointerEvent) => {
+ if (e.pointerType === "mouse") touchFromCard(key);
+ },
+ onPointerLeave: away,
+ onFocus: () => touchFromCard(key),
+ onBlur: (e: FocusEvent) => {
+ // (Not while the keyboard only moves on inside the same line.)
+ if (!e.currentTarget.contains(e.relatedTarget as Node | null)) away();
+ },
+ };
+}
function BomLine({ row: r, lang }: { row: BomRow; lang: GuideLang }) {
const words = BUILD_COPY[lang].cards.bom;
@@ -140,6 +175,7 @@ function BomLine({ row: r, lang }: { row: BomRow; lang: GuideLang }) {
// What to order it by: the part number, where it has one.
const mpn = r.mpn && r.mpn !== "-" && r.mpn !== "generic" ? r.mpn : null;
const more = words.more[key];
+ const touch = usePartTouch(key);
const head = (
<>
ร{dashed(r.qty)}
@@ -155,7 +191,7 @@ function BomLine({ row: r, lang }: { row: BomRow; lang: GuideLang }) {
if (isPanel) {
const { listing, other, note } = words.panel;
return (
-
+
{head}
@@ -177,14 +213,14 @@ function BomLine({ row: r, lang }: { row: BomRow; lang: GuideLang }) {
if (!mpn && !more) {
return (
-
+
{head}
);
}
return (
-
+
{head}
@@ -223,6 +259,13 @@ function BomList({ category, lang }: { category: BomRow["category"]; lang: Guide
const words = BUILD_COPY[lang].cards.bom;
const rows = useBom()?.filter((r) => r.category === category);
const links = [{ label: words.source, href: BOM_URL }, words.guide];
+ // What the stage calls these parts when one is under the hand: the line's own words.
+ useEffect(() => {
+ if (!rows) return;
+ nameParts(Object.fromEntries(rows.map((r) => [bomKey(r), stageName(r, words.names?.[bomKey(r)] ?? r.part)])));
+ });
+ // Gone with the card: the stage is pointed at nothing from here.
+ useEffect(() => () => touchFromCard(null), []);
if (!rows) {
return (
diff --git a/web/src/components/guide/desk/Desk.module.css b/web/src/components/guide/desk/Desk.module.css
index 5606bd62..69e1e36b 100644
--- a/web/src/components/guide/desk/Desk.module.css
+++ b/web/src/components/guide/desk/Desk.module.css
@@ -16,14 +16,27 @@
--d-ink-3: rgba(239, 233, 221, 0.46);
--d-hair: rgba(239, 233, 221, 0.1);
--d-hair-2: rgba(239, 233, 221, 0.18);
- --d-led: #ff6a3d;
+ --d-led: var(--g-led, #ff6a3d);
--d-chrome: #1b1a18;
--d-chrome-2: #131210;
- --d-field: #0f0e0d;
+ --d-field: #0d0c0b;
/* The Lab's own ground, so its window is the Lab's colour before it paints. */
--d-lab: #f4efe6;
- --d-shadow: 0 26px 70px rgba(0, 0, 0, 0.55), 0 2px 10px rgba(0, 0, 0, 0.4);
- --d-ease: cubic-bezier(0.2, 0.7, 0.2, 1);
+ /* A window stands off the desk: a tight dark line where it meets it, the
+ shade it throws close by, and the wide soft one under it. One light,
+ from above. */
+ --d-shadow:
+ 0 0 0 1px rgba(0, 0, 0, 0.5),
+ 0 2px 4px rgba(0, 0, 0, 0.35),
+ 0 14px 28px -8px rgba(0, 0, 0, 0.5),
+ 0 44px 90px -24px rgba(0, 0, 0, 0.7);
+ /* The one in front stands higher. */
+ --d-shadow-fore:
+ 0 0 0 1px rgba(0, 0, 0, 0.55),
+ 0 3px 6px rgba(0, 0, 0, 0.4),
+ 0 22px 44px -10px rgba(0, 0, 0, 0.6),
+ 0 70px 120px -30px rgba(0, 0, 0, 0.8);
+ --d-ease: cubic-bezier(0.16, 1, 0.3, 1);
position: fixed;
z-index: 1;
@@ -31,6 +44,20 @@
top: 72px;
bottom: 20px;
right: calc(var(--desk-col, 380px) + 56px);
+ /* The desk comes up as the device stands back (the stage is the whole
+ guide's and stays; its fade on this page is Guide.module.css's). */
+ animation: deskUp 1s var(--d-ease) backwards;
+}
+@keyframes deskUp {
+ from {
+ opacity: 0;
+ transform: translate3d(0, 34px, 0) scale(0.98);
+ }
+}
+@media (prefers-reduced-motion: reduce) {
+ .desk {
+ animation: none;
+ }
}
/* โโ a window โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ */
@@ -46,17 +73,32 @@
background: var(--d-chrome);
box-shadow: var(--d-shadow);
transition:
- transform 0.62s var(--d-ease),
+ transform 0.85s var(--d-ease),
opacity 0.45s ease,
border-color 0.3s,
+ box-shadow 0.7s ease,
visibility 0s linear 0s;
}
+/* The light from above catches the frame's top edge. */
+.win::after {
+ content: "";
+ position: absolute;
+ inset: 0;
+ z-index: 6;
+ border-radius: inherit;
+ box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.07);
+ pointer-events: none;
+}
+.win[data-role="fore"],
+.win[data-role="solo"] {
+ box-shadow: var(--d-shadow-fore);
+}
.win[data-role="away"] {
opacity: 0;
visibility: hidden;
pointer-events: none;
transition:
- transform 0.62s var(--d-ease),
+ transform 0.85s var(--d-ease),
opacity 0.4s ease,
border-color 0.3s,
visibility 0s linear 0.45s;
@@ -64,35 +106,36 @@
.win[data-win="ai"] {
inset: auto 18px 18px auto;
border-color: rgba(239, 233, 221, 0.24);
- box-shadow:
- 0 30px 80px rgba(0, 0, 0, 0.6),
- 0 2px 10px rgba(0, 0, 0, 0.45);
+ box-shadow: var(--d-shadow-fore);
}
.win[data-win="ai"][data-role="away"] {
transform: translate3d(0, 18px, 0) scale(0.97);
}
+/* The chrome is the quietest thing on the desk: it says "a browser window"
+ and then gets out of the way of what is in it. */
.bar {
display: flex;
flex: none;
align-items: center;
gap: 10px;
- height: 36px;
- padding: 0 10px 0 12px;
- border-bottom: 1px solid rgba(0, 0, 0, 0.5);
- background: var(--d-chrome-2);
+ height: 34px;
+ padding: 0 10px 0 13px;
+ border-bottom: 1px solid rgba(0, 0, 0, 0.55);
+ background: linear-gradient(#181715, var(--d-chrome-2));
font-family: var(--pf-sans, system-ui, sans-serif);
}
.lights {
display: flex;
flex: none;
- gap: 5px;
+ gap: 6px;
}
.lights i {
- width: 9px;
- height: 9px;
+ width: 8px;
+ height: 8px;
border-radius: 50%;
- background: rgba(239, 233, 221, 0.16);
+ background: rgba(239, 233, 221, 0.11);
+ box-shadow: inset 0 0 0 0.5px rgba(239, 233, 221, 0.1);
}
.tab {
display: flex;
@@ -102,15 +145,21 @@
min-width: 0;
max-width: 220px;
font-size: 11.5px;
+ letter-spacing: 0.005em;
+ color: var(--d-ink-3);
+ transition: color 0.4s;
+}
+/* The window being worked in says so in its title, not its frame. */
+.win:not([data-dim="1"]) .tab {
color: var(--d-ink-2);
}
.favicon {
flex: none;
- width: 7px;
- height: 7px;
+ width: 6px;
+ height: 6px;
border-radius: 50%;
- background: #ff5c2e;
- box-shadow: 0 0 5px rgba(255, 92, 46, 0.7);
+ background: var(--d-led);
+ opacity: 0.85;
}
.tabTitle {
overflow: hidden;
@@ -123,14 +172,15 @@
align-items: center;
gap: 7px;
min-width: 0;
- height: 23px;
+ height: 22px;
padding: 0 11px;
border-radius: 999px;
background: var(--d-field);
+ box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.5);
font-family: var(--pf-mono, ui-monospace, monospace);
- font-size: 11px;
+ font-size: 10.5px;
letter-spacing: 0.01em;
- color: var(--d-ink);
+ color: var(--d-ink-2);
}
.lock {
flex: none;
@@ -152,11 +202,11 @@
.badge {
flex: none;
padding: 2px 8px;
- border: 1px solid rgba(255, 106, 61, 0.5);
+ border: 1px solid rgb(var(--g-led-rgb, 255 106 61) / 0.4);
border-radius: 999px;
font-family: var(--pf-mono, ui-monospace, monospace);
- font-size: 10px;
- letter-spacing: 0.06em;
+ font-size: 9.5px;
+ letter-spacing: 0.08em;
color: var(--d-led);
white-space: nowrap;
}
@@ -169,8 +219,7 @@
background: var(--d-chrome);
}
-/* Over a window in the back (or all of them, at rest): dimmed, and a click
- brings it forward. */
+/* Over a window in the back: dimmed, and a click brings it forward. */
.cover {
position: absolute;
inset: 0;
@@ -180,8 +229,8 @@
pointer-events: none;
cursor: pointer;
transition:
- opacity 0.45s ease,
- background 0.25s;
+ opacity 0.6s ease,
+ background 0.3s;
}
.win[data-dim="1"] .cover {
opacity: 1;
@@ -190,9 +239,6 @@
.win[data-dim="1"] .cover:hover {
background: rgba(10, 9, 8, 0.42);
}
-.desk[data-rest="1"] .win[data-dim="1"] .cover {
- background: rgba(10, 9, 8, 0.5);
-}
/* A practice window's content. */
.appRoot {
@@ -253,7 +299,7 @@
gap: 10px;
margin: 0;
padding: 10px 12px;
- border: 1px solid rgba(255, 106, 61, 0.55);
+ border: 1px solid rgb(var(--g-led-rgb, 255 106 61) / 0.55);
border-radius: 10px;
background: rgba(20, 18, 16, 0.94);
font-size: 12.5px;
@@ -320,11 +366,17 @@
top: -2.2px;
overflow: visible;
transform-origin: 3px 2.2px;
- filter: drop-shadow(0 3px 5px rgba(0, 0, 0, 0.55));
- transition: transform 0.14s ease;
+ /* It floats over the windows: a close shade and a wider one under it. */
+ filter: drop-shadow(0 1px 1px rgba(0, 0, 0, 0.6)) drop-shadow(0 6px 9px rgba(0, 0, 0, 0.45));
+ transition:
+ transform 0.34s cubic-bezier(0.3, 1.5, 0.5, 1),
+ filter 0.2s ease;
}
+/* A press: down onto the glass at once (its shade closes up), and back with a little spring. */
.cursor[data-press="1"] svg {
- transform: scale(0.82);
+ transform: scale(0.84);
+ filter: drop-shadow(0 0 1px rgba(0, 0, 0, 0.7)) drop-shadow(0 2px 3px rgba(0, 0, 0, 0.5));
+ transition-duration: 0.07s;
}
.cursor[data-mode="scroll"] svg {
animation: bob 0.5s ease-in-out infinite alternate;
@@ -376,10 +428,10 @@
}
.halo {
border: 1.5px solid var(--d-led);
- border-radius: 8px;
+ border-radius: 9px;
box-shadow:
- 0 0 0 3px rgba(255, 106, 61, 0.16),
- 0 0 22px rgba(255, 106, 61, 0.35);
+ 0 0 0 3px rgb(var(--g-led-rgb, 255 106 61) / 0.16),
+ 0 0 22px rgb(var(--g-led-rgb, 255 106 61) / 0.35);
opacity: 0;
transition: opacity 0.3s ease;
}
@@ -394,24 +446,47 @@
/* Wide enough for the longest one-line hints ("Your turn: roll the wheel
over a card" left its last word on a line of its own at 260). */
max-width: 300px;
- padding: 7px 11px 7px 10px;
- border: 1px solid rgba(255, 106, 61, 0.5);
- border-radius: 10px;
- background: rgba(16, 14, 12, 0.95);
- box-shadow: 0 10px 28px rgba(0, 0, 0, 0.45);
+ padding: 7px 12px 7px 11px;
+ border: 1px solid rgba(239, 233, 221, 0.16);
+ border-radius: 11px;
+ /* The pointer's own voice: dark glass, a line of the accent down its near
+ edge (the same line the cue in the card has), lit from above. */
+ background:
+ linear-gradient(var(--d-led), var(--d-led)) 0 50% / 2px calc(100% - 12px) no-repeat,
+ rgba(18, 16, 14, 0.94);
+ box-shadow:
+ inset 0 1px 0 rgba(255, 255, 255, 0.07),
+ 0 0 0 1px rgba(0, 0, 0, 0.5),
+ 0 4px 8px rgba(0, 0, 0, 0.35),
+ 0 18px 36px -10px rgba(0, 0, 0, 0.6);
font: 500 12.5px/1.35 var(--pf-sans, system-ui, sans-serif);
+ letter-spacing: 0.005em;
color: var(--d-ink);
opacity: 0;
- transition: opacity 0.25s ease;
+ /* It comes up from the pointer and settles (its place is the script's transform; this is on top of it). */
+ scale: 0.94;
+ translate: 0 5px;
+ transition:
+ opacity 0.2s ease,
+ scale 0.2s ease,
+ translate 0.2s ease;
}
.pointerLayer[data-shown="1"] .bubble[data-on="1"] {
opacity: 1;
+ scale: 1;
+ translate: 0 0;
+ transition:
+ opacity 0.3s ease,
+ scale 0.5s cubic-bezier(0.3, 1.36, 0.5, 1),
+ translate 0.5s var(--d-ease);
}
.chip {
flex: none;
- padding: 1px 6px;
- border: 1px solid rgba(239, 233, 221, 0.35);
+ padding: 1px 6px 0;
+ border: 1px solid rgba(239, 233, 221, 0.28);
+ border-bottom-width: 2px;
border-radius: 5px;
+ background: rgba(239, 233, 221, 0.05);
font-family: var(--pf-mono, ui-monospace, monospace);
font-size: 10.5px;
letter-spacing: 0.04em;
@@ -446,13 +521,13 @@
0%,
100% {
box-shadow:
- 0 0 0 3px rgba(255, 106, 61, 0.14),
- 0 0 16px rgba(255, 106, 61, 0.25);
+ 0 0 0 3px rgb(var(--g-led-rgb, 255 106 61) / 0.14),
+ 0 0 16px rgb(var(--g-led-rgb, 255 106 61) / 0.25);
}
50% {
box-shadow:
- 0 0 0 5px rgba(255, 106, 61, 0.22),
- 0 0 28px rgba(255, 106, 61, 0.45);
+ 0 0 0 5px rgb(var(--g-led-rgb, 255 106 61) / 0.22),
+ 0 0 28px rgb(var(--g-led-rgb, 255 106 61) / 0.45);
}
}
@keyframes bob {
@@ -477,10 +552,13 @@
align-items: center;
gap: 8px 10px;
margin: 14px 0 2px;
- padding: 9px 10px 9px 12px;
+ padding: 9px 10px 9px 13px;
border: 1px solid var(--g-hair-2, rgba(239, 233, 221, 0.18));
border-radius: 12px;
- background: rgba(255, 106, 61, 0.06);
+ /* The same accent line as the pointer's bubble: the two are one voice. */
+ background:
+ linear-gradient(var(--g-led, #ff6a3d), var(--g-led, #ff6a3d)) 0 50% / 2px calc(100% - 16px) no-repeat,
+ rgb(var(--g-led-rgb, 255 106 61) / 0.06);
}
@media (min-width: 1340px) and (min-height: 640px), (min-width: 1280px) and (min-height: 660px), (min-width: 1180px) and (min-height: 700px) {
.cue {
@@ -534,7 +612,7 @@
.cueAgain:focus-visible {
border-color: var(--g-led, #ff6a3d);
color: var(--g-ink, #efe9dd);
- background: rgba(255, 106, 61, 0.1);
+ background: rgb(var(--g-led-rgb, 255 106 61) / 0.1);
}
.cueAgain:focus-visible,
.cueJump:focus-visible {
@@ -552,7 +630,7 @@
padding: 6px 11px;
border: 1px solid var(--g-led, #ff6a3d);
border-radius: 999px;
- background: var(--g-led-wash, rgba(255, 106, 61, 0.1));
+ background: var(--g-led-wash, rgb(var(--g-led-rgb, 255 106 61) / 0.1));
color: var(--g-ink, #efe9dd);
font: 500 12px/1 var(--pf-sans, system-ui, sans-serif);
cursor: pointer;
@@ -584,8 +662,12 @@
.cursor,
.cursor svg,
.halo,
- .bubble {
+ .bubble,
+ .pointerLayer[data-shown="1"] .bubble[data-on="1"],
+ .tab {
transition: none;
+ scale: 1;
+ translate: 0 0;
}
.cursor[data-mode="scroll"] svg,
.cursor[data-mode="type"]::after,
diff --git a/web/src/components/guide/desk/DeskStage.tsx b/web/src/components/guide/desk/DeskStage.tsx
index 790de971..1cbd26d3 100644
--- a/web/src/components/guide/desk/DeskStage.tsx
+++ b/web/src/components/guide/desk/DeskStage.tsx
@@ -42,7 +42,12 @@ const LAB_W = 1024;
const LAB_H = 680;
/** What the keyboard can land on in a practice window. */
const FOCUSABLE = 'button:not([disabled]), a[href], input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
-/** Two big windows on the desk: the one behind peeks out this far above and left of the one in front. */
+/**
+ * Two big windows on the desk: the one behind shows this much above the one
+ * in front โ its title bar, whole: its name, its address, whose it is. (It
+ * used to show to the left as well, and what showed there was a strip of the
+ * Lab's panel cut through its labels: "Pat", "Pre", "60".)
+ */
const CASCADE = 30;
type Role = "solo" | "fore" | "back" | "away";
@@ -337,14 +342,16 @@ function roles(l: Layout): Record
{
function bigStyle(role: Role, size: { w: number; h: number } | null, i: number): CSSProperties {
const w = size?.w ?? 1000;
const h = size?.h ?? 700;
- const s = Math.min((w - CASCADE) / w, (h - CASCADE) / h);
+ void w;
+ const s = (h - CASCADE) / h;
switch (role) {
case "solo":
return { transform: "none", transformOrigin: "50% 50%", zIndex: 3 };
+ // One over the other, the same width: the one in front lower, the one behind higher.
case "fore":
- return { transform: `scale(${s.toFixed(4)})`, transformOrigin: "100% 100%", zIndex: 3 };
+ return { transform: `scale(${s.toFixed(4)})`, transformOrigin: "50% 100%", zIndex: 3 };
case "back":
- return { transform: `scale(${s.toFixed(4)})`, transformOrigin: "0 0", zIndex: 2 };
+ return { transform: `scale(${s.toFixed(4)})`, transformOrigin: "50% 0", zIndex: 2 };
case "away":
return { transform: `translate3d(${i ? 24 : -24}px, 22px, 0) scale(0.97)`, transformOrigin: "50% 50%", zIndex: 1 };
}
@@ -372,9 +379,10 @@ export default function DeskStage({ lang }: { lang: GuideLang }) {
ai: DESK_APPS.ai.chrome.address?.path ?? "",
});
// The Lab's frame is made the first time the Lab is on the desk for real
- // (not at rest behind the opening), then kept for the rest of the visit.
+ // (not behind the opening, where it is a picture of itself), then kept for
+ // the rest of the visit.
const [labMounted, setLabMounted] = useState(false);
- const wantLab = layout.shown.has("lab") && !layout.rest;
+ const wantLab = layout.shown.has("lab") && (!layout.rest || layout.top === "lab");
if (wantLab && !labMounted) setLabMounted(true);
const labReady = useRef(false);
@@ -497,7 +505,11 @@ export default function DeskStage({ lang }: { lang: GuideLang }) {
const aiH = Math.round(Math.max(300, Math.min(520, (size?.h ?? 700) * layout.aiHeight)));
const aiRole: Role = aiShown ? "solo" : "away";
- const dimBig = (w: BigWin) => r[w] === "back" || (layout.rest && r[w] !== "away") || (layout.front === "ai" && r[w] !== "away");
+ // A window behind another is dimmed, and one under the AI's. At rest (the
+ // opening, the end) nothing is pointed at yet, and the window in front is
+ // as bright as it will be: the page used to open on two dimmed windows,
+ // which read as a desk that was switched off.
+ const dimBig = (w: BigWin) => r[w] === "back" || (layout.front === "ai" && r[w] !== "away");
const appProps = (win: "community" | "ai") => ({
lang,
shown: layout.shown.has(win),
@@ -517,6 +529,8 @@ export default function DeskStage({ lang }: { lang: GuideLang }) {
= STILL_BUDGET_MS) break;
}
- return new ImageData(new Uint8ClampedArray(rt.data), rt.width, rt.height);
+ if (m.steps < STILL_STEPS) return undefined;
+ making = null;
+ return new ImageData(new Uint8ClampedArray(m.rt.data), m.rt.width, m.rt.height);
}
function tick(now: number) {
@@ -177,12 +200,14 @@ function tick(now: number) {
if (img) paint(s, img);
else s.failed = true;
} else if (!stillMade) {
- // One new still per frame: a page of them never holds the page up.
+ // One still at a time, a little of it a frame: a page of them never holds the page up.
stillMade = true;
- const img = renderStill(s);
- stills.set(k, img);
- if (img) paint(s, img);
- else s.failed = true;
+ const img = renderStill(s, k);
+ if (img !== undefined) {
+ stills.set(k, img);
+ if (img) paint(s, img);
+ else s.failed = true;
+ }
} else {
more = true;
}
diff --git a/web/src/components/guide/hubKnob.ts b/web/src/components/guide/hubKnob.ts
index 443bfac8..09c46bc9 100644
--- a/web/src/components/guide/hubKnob.ts
+++ b/web/src/components/guide/hubKnob.ts
@@ -2,7 +2,7 @@ import type { DeviceSim } from "@/lib/guide/deviceSim";
import { ENCODER_CLICKS_PER_TURN, TURNS_PER_FULL_RANGE } from "@/lib/pattern/controls";
import { useGuideStore } from "./store";
-// The hub's Play answer (HubStage): K1 turns while Play is pointed at, and
+// The hub's Play answer (world/HubAnswers): K1 turns while Play is pointed at, and
// Origin's colour follows. The board is the same one in every guide
// (store.ts getSim), so the hub hands it on as it found it: Play's words call
// Origin red, and a hue left turned here opened that guide in another colour.
diff --git a/web/src/components/guide/pages.ts b/web/src/components/guide/pages.ts
index 93890fe3..70d2eec3 100644
--- a/web/src/components/guide/pages.ts
+++ b/web/src/components/guide/pages.ts
@@ -115,3 +115,30 @@ export const PAGES: Record
= {
export function pagePath(page: GuideScreen, lang: GuideLang): string {
return page === "hub" ? HUB_PATH[lang] : PAGES[page].path[lang];
}
+
+/**
+ * The page of the guide an address is, and its language โ the other way
+ * round from pagePath โ or null for an address that is not the guide's. The
+ * world (world/GuideWorld) reads the address for what it can know before a
+ * page has mounted: which room to light on the server's first paint.
+ */
+export function screenAt(pathname: string): { page: GuideScreen; lang: GuideLang } | null {
+ const path = pathname.replace(/\/+$/, "") || "/";
+ for (const lang of ["en", "ko"] as const) {
+ if (HUB_PATH[lang] === path) return { page: "hub", lang };
+ for (const page of GUIDE_ORDER) if (PAGES[page].path[lang] === path) return { page, lang };
+ }
+ return null;
+}
+
+/**
+ * Where the reader is on a guide, as an anchor: "#flash-3" for a step whose
+ * card is on screen, "#flash" for a chapter's title, "#next" for the end, and
+ * nothing at the opening. A link to the same guide in the other language
+ * carries it (world/GuideLink), so switching language keeps the place.
+ */
+export function placeAnchor(scene: string, step: number, cardIn: boolean): string {
+ if (scene === "opening") return "";
+ if (scene === "next") return "#next";
+ return cardIn ? `#${scene}-${step + 1}` : `#${scene}`;
+}
diff --git a/web/src/components/guide/scenes.ts b/web/src/components/guide/scenes.ts
index 2b685166..9b49a547 100644
--- a/web/src/components/guide/scenes.ts
+++ b/web/src/components/guide/scenes.ts
@@ -24,7 +24,9 @@ import type { BuildViewName } from "./stage/build/views";
// on the desk (DeskStep), not what a device does. Every guide opens on a
// scene called "opening" and ends on one called "next"; which guide's is
// meant is the store's `page`. The hub (/guide, GuideHub) has the stage too,
-// playing HUB_SCENES: Play's opening, and nothing after it.
+// playing HUB_SCENES: Play's opening, and nothing after it โ what it shows
+// besides, while a guide is pointed at, is not script (world/HubAnswers,
+// stage/Explode).
export type ViewName =
| "hero"
@@ -336,8 +338,11 @@ export const MAKE_SCENES: SceneDef[] = [
// beside the three guides. The hub has no scroll story, so this is all it plays.
const HUB_SCENES: SceneDef[] = [SCENES[0]];
-// The scripts the 3D stage plays, by page. Make has the desk instead; were
-// the stage ever mounted there, it would play Play's.
+// The scripts the 3D stage plays, by page. The stage is one for the whole
+// guide and stays up between pages (world/GuideWorld). Make has the desk
+// instead: there the device stands far back, faded and at rest, and what it
+// holds meanwhile is Play's opening โ the device whole and lit, which is how
+// it comes back.
const STAGE_SCENES: Record = { build: BUILD_SCENES, play: SCENES, make: SCENES, hub: HUB_SCENES };
const PAGE_SCENES: Record[]> = { build: BUILD_SCENES, play: SCENES, make: MAKE_SCENES, hub: HUB_SCENES };
diff --git a/web/src/components/guide/stage/Device.tsx b/web/src/components/guide/stage/Device.tsx
index 548d6279..fca85e1a 100644
--- a/web/src/components/guide/stage/Device.tsx
+++ b/web/src/components/guide/stage/Device.tsx
@@ -11,8 +11,12 @@ import * as THREE from "three";
import { patternVert } from "@/components/3d/patterns/common";
import { PATTERN_DETENTS_PER_TURN } from "@/lib/pattern/harness";
import { FIRMWARE, PANEL_H, PANEL_W } from "@/lib/guide/panelScreens";
+import { ledPanelMaterial, ledPanelTexture } from "./look/ledPanel";
+import { knobMaterial, plaMaterial, tunePcbMaterials } from "./look/materials";
+import { readPanelGlow } from "./look/panelGlow";
import { getSim, useGuideStore } from "../store";
import { stepOf } from "../scenes";
+import { knobIsTurned } from "../hubKnob";
import {
DRACO_URL,
modelToWorld,
@@ -38,6 +42,8 @@ import {
sliderPose,
} from "./parts";
import KitFx from "./KitFx";
+import { kitPress } from "./hand";
+import { kitState } from "../timing";
import { devkitMaterials } from "./kitMaterials";
import { forgetPillSize, NO_POINTER, placeTag } from "./tags";
import { VIEWS } from "./views";
@@ -51,29 +57,6 @@ import { VIEWS } from "./views";
// The landing model's GLB is shared with the landing page's HeroScene through
// drei's cache, so this works on clones and never touches a cached scene.
-const ledFragment = `
-uniform sampler2D uTex;
-uniform float uPower;
-varying vec2 vUv;
-void main() {
- vec2 rotatedUV = vec2(vUv.y, 1.0 - vUv.x);
- vec2 gridUV = rotatedUV * vec2(128.0, 64.0);
- vec2 localUV = fract(gridUV);
- vec2 pxUV = (floor(gridUV) + 0.5) / vec2(128.0, 64.0);
- vec3 col = texture2D(uTex, pxUV).rgb;
- float d = length(localUV - 0.5);
- float dotMask = smoothstep(0.46, 0.34, d);
- float fw = fwidth(vUv.x) * 128.0;
- float lod = smoothstep(0.0, 0.29, fw);
- float alpha = mix(dotMask, 1.0, lod);
- float luma = dot(col, vec3(0.299, 0.587, 0.114));
- col *= luma > 0.75 ? 2.35 : 0.9;
- float unlit = 0.018;
- col = mix(vec3(unlit), col, step(0.01, length(col)));
- gl_FragColor = vec4(col * alpha * uPower + vec3(unlit) * (1.0 - uPower), 1.0);
-}
-`;
-
// A ring drawn on a plane: `uFill` of the circle as a bright arc (a hold on
// its way to a long-press) over a faint full ring (the knob in focus).
const ringFragment = `
@@ -131,6 +114,8 @@ const KNOB_HIT_R = 1.45;
const DIAL_IN = 0.98;
const DIAL_OUT = 1.16;
const DIAL_DOT = 0.17;
+/** The focus / hold ring's outer edge round a knob's top (the ring's plane is 4.2 across, its band out to 0.98 of that). */
+const FOCUS_RING_R = 2.06;
/** Just proud of the case's front face (1.5635), under the knob skirts (1.6437). */
const DIAL_Z = KNOB_BASE_Z - 0.06;
/** How long a knob keeps its readout after it last moved, ms. */
@@ -162,9 +147,13 @@ function seatingStep(page: string, scene: string, step: number) {
return page === "build" && scene === "firmware" && step === 1;
}
-// Warm white PLA, and the knobs' matte black.
-const caseMaterial = () => new THREE.MeshStandardMaterial({ color: "#eceae4", roughness: 0.55, metalness: 0 });
-const knobMaterial = () => new THREE.MeshStandardMaterial({ color: "#161616", roughness: 0.82, metalness: 0 });
+// Warm white PLA and the knobs' black (look/materials.ts): printed, with a
+// print's layers on the walls. The case lay on its face on the plate and the
+// knobs stood on their skirts, so in the device both are layered along z.
+const caseMaterial = () => plaMaterial();
+
+/** How fast the panel dies when its power is cut: the time to fall to a third, seconds. A supply's capacitors, not a fade โ but not a cut frame either. */
+const POWER_OFF_S = 0.11;
export default function Device() {
const [ledGltf, caseGltf, pcbGltf, kitGltf] = useGLTF([MODEL_URL, CASE_URL, PCB_URL, DEVKIT_URL], DRACO_URL);
@@ -214,6 +203,21 @@ export default function Device() {
m.castShadow = true;
m.receiveShadow = true;
});
+ // The board's parts as what they are made of (the file gives most of
+ // them glTF's default, a fully rough metal): look/materials.ts.
+ tunePcbMaterials(pcb);
+ // The encoders' simplified metal reads as a mirror under the stage's
+ // light (it was made to sit inside the case), and blooms: brushed steel
+ // instead, wherever they are out in the open โ the hub's device taken
+ // apart (Explode), and the Build guide (BuildStage sets the same).
+ pcb.traverse((o) => {
+ const mat = (o as THREE.Mesh).material as THREE.MeshStandardMaterial | undefined;
+ if (mat && !Array.isArray(mat) && mat.name === "encoder_metal") {
+ mat.color.set("#8d9096");
+ mat.metalness = 0.7;
+ mat.roughness = 0.6;
+ }
+ });
return root;
}, [ledGltf, caseGltf, pcbGltf]);
@@ -245,22 +249,10 @@ export default function Device() {
};
}, [scene, kit]);
- const texture = useMemo(() => {
- const data = new Uint8Array(PANEL_W * PANEL_H * 4);
- const t = new THREE.DataTexture(data, PANEL_W, PANEL_H, THREE.RGBAFormat);
- t.needsUpdate = true;
- return t;
- }, []);
-
- const ledMat = useMemo(
- () =>
- new THREE.ShaderMaterial({
- uniforms: { uTex: { value: texture }, uPower: { value: 0 } },
- vertexShader: patternVert,
- fragmentShader: ledFragment,
- }),
- [texture],
- );
+ // The panel's face (look/ledPanel.ts): the frame as a texture, and the
+ // shader that makes LEDs of it.
+ const texture = useMemo(() => ledPanelTexture(), []);
+ const ledMat = useMemo(() => ledPanelMaterial(texture), [texture]);
const parts = useMemo(() => {
const p: Parts = { devkit: kit, led: null, knobs: [null, null, null, null], slider: null, all: [] };
@@ -319,6 +311,8 @@ export default function Device() {
toneMapped: false,
});
const mesh = new THREE.Mesh(new THREE.PlaneGeometry(4.2, 4.2), mat);
+ // By name: a ring goes where its knob goes when the device comes apart (Explode).
+ mesh.name = "knob_ring";
return mesh;
}),
[],
@@ -373,6 +367,8 @@ export default function Device() {
}, [dials, scene]);
const hovered = useRef(-1);
+ /** The DevKit button under the pointer, while it can be pressed. */
+ const overButton = useRef(null);
// โโ knobs under the pointer โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
const drag = useRef<{
@@ -411,6 +407,7 @@ export default function Device() {
}
};
const onUp = () => {
+ kitPress.boot = kitPress.rst = false;
const d = drag.current;
if (!d) return;
if (!d.turned) sim.release(d.knob);
@@ -419,6 +416,7 @@ export default function Device() {
};
// A gesture the browser took over (a scroll, say) was never a click.
const onCancel = () => {
+ kitPress.boot = kitPress.rst = false;
const d = drag.current;
if (!d) return;
sim.cancel(d.knob);
@@ -445,7 +443,29 @@ export default function Device() {
};
}, []);
+ // The DevKit's BOOT and RST, on the step that is about them ("Hold BOOT,
+ // tap RST": scenes.ts bootSeq) and with the DevKit held up: a real hand
+ // could press them there, so the reader's can (hand.ts kitPress). Only the
+ // nearest thing under the pointer counts โ never a button through the cable.
+ const buttonUnder = (e: ThreeEvent): "boot" | "rst" | null => {
+ if (!kit.boot && !kit.rst) return null;
+ let which: "boot" | "rst" | null = null;
+ for (let o: THREE.Object3D | null = e.object; o; o = o.parent) {
+ if (o === kit.boot) which = "boot";
+ else if (o === kit.rst) which = "rst";
+ }
+ if (!which || e.intersections[0]?.object !== e.object) return null;
+ const { scene: sceneId, step, page } = useGuideStore.getState();
+ return page === "play" && kitState.presented && stepOf(sceneId, step).bootSeq ? which : null;
+ };
+
const onPointerDown = (e: ThreeEvent) => {
+ const button = buttonUnder(e);
+ if (button) {
+ e.stopPropagation();
+ kitPress[button] = true;
+ return;
+ }
const knob = knobUnder(e.object);
const knobMesh = knob < 0 ? null : parts.knobs[knob];
if (!knobMesh) return;
@@ -472,12 +492,18 @@ export default function Device() {
};
const onPointerOver = (e: ThreeEvent) => {
+ if (buttonUnder(e)) {
+ overButton.current = e.object;
+ if (!drag.current) document.body.style.cursor = "pointer";
+ return;
+ }
const knob = knobUnder(e.object);
if (knob < 0) return;
hovered.current = knob;
if (!drag.current) document.body.style.cursor = "grab";
};
const onPointerOut = (e: ThreeEvent) => {
+ if (overButton.current === e.object) overButton.current = null;
if (knobUnder(e.object) === hovered.current) hovered.current = -1;
if (!drag.current) document.body.style.cursor = "";
};
@@ -485,7 +511,8 @@ export default function Device() {
// โโ the frame โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
// back: sliderPose's travel (0 shut, SLIDER_OFF off its rails, 1 laid
// down); esp: devkitPose's travel (0 seated, 1 presented).
- const shown = useRef({ turns: [0, 0, 0, 0], press: [0, 0, 0, 0], power: 0, back: 0, esp: 0 });
+ // power: the panel's, as shown (it dies away when cut); held: a lit frame is still on it.
+ const shown = useRef({ turns: [0, 0, 0, 0], press: [0, 0, 0, 0], power: 0, held: false, tick: 0, back: 0, esp: 0 });
const tmp = useMemo(() => ({ pos: new THREE.Vector3(), quat: new THREE.Quaternion() }), []);
const labelRefs = useRef<(HTMLDivElement | null)[]>([]);
const readout = useRef({
@@ -507,6 +534,8 @@ export default function Device() {
const size = useThree((st) => st.size);
// The knobs' top centres, world units (the stage's model group: geometry.ts).
const knobTops = useMemo(() => [0, 1, 2, 3].map((i) => modelToWorld(knobWorldCenter(i, "model"))), []);
+ // โฆand their dials' centres on the case's face, a knob's height below: a pill stands clear of both (tags.ts).
+ const dialAt = useMemo(() => [0, 1, 2, 3].map((i) => ({ at: modelToWorld(knobWorldCenter(i, "model").setZ(DIAL_Z)), radius: DIAL_OUT * MODEL_SCALE })), []);
useFrame((state, rawDt) => {
// A tab coming back from the background hands over one long frame; don't
@@ -523,11 +552,17 @@ export default function Device() {
// A couple of frames' grace, for the board being put in the step's state.
{
const ro = readout.current;
- const key = `${sceneId}.${step}`;
+ // The page is part of it: the stage carries on from one page to the
+ // next, and both open on "opening", 0.
+ const key = `${page}.${sceneId}.${step}`;
if (ro.key !== key) {
ro.key = key;
ro.settle = 2;
}
+ // Nor is the hub's Play answer turning K1 back a knob "just moved": it
+ // finishes in Play's opening (world/HubAnswers), and its readout came up
+ // beside K1 there as if the reader had turned it.
+ if (page !== "hub" && knobIsTurned()) ro.settle = 2;
if (ro.settle > 0) {
ro.settle--;
for (let i = 0; i < 4; i++) {
@@ -539,16 +574,36 @@ export default function Device() {
}
// Panel: copy the simulated frame in, bottom row first for GL.
- const src = sim.frame;
+ //
+ // When the power goes the simulator's frame is black at once. The panel
+ // is not: what it was showing dies away over a tenth of a second, as the
+ // supply's capacitors empty. So the last lit frame is held on the panel
+ // while its power falls, and only then is it cleared. (Coming on is the
+ // firmware's own fade, in the frame itself.)
const dst = texture.image.data as Uint8Array;
- const row = PANEL_W * 4;
- for (let y = 0; y < PANEL_H; y++) {
- dst.set(src.subarray(y * row, (y + 1) * row), (PANEL_H - 1 - y) * row);
+ const sh0 = shown.current;
+ const on = snap.mode !== "off";
+ if (on) {
+ const src = sim.frame;
+ const row = PANEL_W * 4;
+ for (let y = 0; y < PANEL_H; y++) {
+ dst.set(src.subarray(y * row, (y + 1) * row), (PANEL_H - 1 - y) * row);
+ }
+ texture.needsUpdate = true;
+ sh0.power += (1 - sh0.power) * Math.min(1, dt * 9);
+ sh0.held = true;
+ } else if (sh0.held) {
+ sh0.power *= Math.exp(-dt / POWER_OFF_S);
+ if (sh0.power < 0.004) {
+ sh0.power = 0;
+ sh0.held = false;
+ dst.fill(0);
+ texture.needsUpdate = true;
+ }
}
- texture.needsUpdate = true;
- const powerTarget = snap.mode === "off" ? 0 : 1;
- shown.current.power += (powerTarget - shown.current.power) * Math.min(1, dt * 6);
- ledMat.uniforms.uPower.value = shown.current.power;
+ ledMat.uniforms.uPower.value = sh0.power;
+ // What the panel is giving off, for the lights and the floor (look/panelGlow.ts): every other frame is plenty.
+ if ((sh0.tick = (sh0.tick + 1) & 1) === 0) readPanelGlow(dst, sh0.power, dt * 2);
// Knobs: rotation about their own axis follows the detents, a press
// pushes the cap in along it.
@@ -647,11 +702,23 @@ export default function Device() {
}
}
// Beside its knob at a fixed gap in screen pixels, whatever the
- // zoom: K1/K3 to the right, over the case's margin. Left of K2/K4 is
- // the panel's edge, where the screens print their headings and
- // SELECT its bar, so K2's goes above and K4's below.
+ // zoom, and outside its dial โ the band the orange dot rides โ and
+ // its focus ring while that is lit: K1/K3 to the right, over the
+ // case's margin. Left of K2/K4 is the panel's edge, where the
+ // screens print their headings and SELECT its bar, so K2's goes
+ // above and K4's below, and a readout there grows to the right, away
+ // from the panel. Where there is no room to the right for a readout
+ // (a phone), K1's goes above K2's row and K3's below K4's.
const side = i === 0 || i === 2 ? "right" : i === 1 ? "up" : "down";
- if (on) placeTag(label, state.camera, size, knobTops[i], KNOB_R * MODEL_SCALE, side, 7);
+ if (on) {
+ const reach = (KNOB_R + (FOCUS_RING_R - KNOB_R) * Math.min(1, ring.uniforms.uFocus.value * 1.5)) * MODEL_SCALE;
+ placeTag(label, state.camera, size, knobTops[i], reach, side, 6, undefined, 0, {
+ also: dialAt[i],
+ growRight: true,
+ alt: i === 0 ? "up" : i === 2 ? "down" : undefined,
+ altRow: 1,
+ });
+ }
}
});
diff --git a/web/src/components/guide/stage/Explode.tsx b/web/src/components/guide/stage/Explode.tsx
new file mode 100644
index 00000000..34dd3a93
--- /dev/null
+++ b/web/src/components/guide/stage/Explode.tsx
@@ -0,0 +1,149 @@
+"use client";
+
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { smoothDamp, type Damp } from "./damp";
+import { EXPLODE_WHOLE, explodeState, explodeWanted, partOffset } from "./explodeParts";
+import { KNOB_MESH_TO_LOGICAL } from "./geometry";
+import { PCB_PLACEMENT } from "./parts";
+import { OPENING_GONE, OPENING_UNSEEN } from "./build/beats";
+import { useGuideStore } from "../store";
+import { buildClock } from "../timing";
+
+// The device coming apart and going back together (explodeParts.ts has what moves
+// where; this puts it on the device's objects).
+//
+// Mounted straight after (null);
+ const st = useRef<{ e: number; vel: Damp }>({ e: 0, vel: { v: 0 } });
+ const o = useMemo(() => new THREE.Vector3(), []);
+
+ // Gone with the canvas: nothing is apart.
+ useEffect(
+ () => () => {
+ explodeState.amount = 0;
+ },
+ [],
+ );
+
+ useFrame((_, rawDt) => {
+ const s = st.current;
+ const want = explodeWanted() ? 1 : 0;
+ if (want === 0 && s.e === 0) return;
+ const dt = Math.min(rawDt, 1 / 20);
+ const { page, scene } = useGuideStore.getState();
+ const t = buildClock.t;
+ let e: number;
+ if (t >= OPENING_GONE) {
+ // The build is under way and the opening's device is not on stage: whole,
+ // or โ on the way back up to the opening, while it still cannot be seen โ apart again.
+ e = want && t < OPENING_UNSEEN ? 1 : 0;
+ s.vel.v = 0;
+ } else if (!want && page === "build" && t >= 0) {
+ // Scrolled into the build: the opening's device goes where it hangs.
+ e = s.e;
+ s.vel.v = 0;
+ } else {
+ const hurry = page !== "hub" && scene !== "opening";
+ e = smoothDamp(s.e, want, s.vel, want ? OUT_S : hurry ? HURRY_S : HOME_S, dt);
+ if (want === 0 && e < EXPLODE_WHOLE) {
+ e = 0;
+ s.vel.v = 0;
+ } else if (want === 1 && e > 1 - EXPLODE_WHOLE) e = 1;
+ }
+ const r = (rig.current ??= find(world));
+ if (!r) {
+ // The device has not loaded yet: nothing has moved.
+ s.e = 0;
+ s.vel.v = 0;
+ return;
+ }
+ s.e = e;
+ explodeState.amount = e;
+
+ // Added to where Device has just put them.
+ partOffset("knobs", e, o);
+ for (const k of r.knobs) k.position.z += o.z;
+ for (const ring of r.rings) ring.position.z += o.z;
+ r.devkit.position.add(partOffset("devkit", e, o));
+ r.slider.position.add(partOffset("slider", e, o));
+ // Placed from home.
+ for (const p of r.placed) p.node.position.copy(p.home).add(partOffset(p.part, e, o));
+ });
+
+ return null;
+}
diff --git a/web/src/components/guide/stage/Fx.tsx b/web/src/components/guide/stage/Fx.tsx
index cfc673e5..5bd6c1c7 100644
--- a/web/src/components/guide/stage/Fx.tsx
+++ b/web/src/components/guide/stage/Fx.tsx
@@ -11,6 +11,7 @@ import { PANEL_H, PANEL_W } from "@/lib/guide/panelScreens";
import { getSim, useGuideStore } from "../store";
import { stepOf } from "../scenes";
import { LED_CENTER_WORLD, modelToWorld } from "./geometry";
+import { stageAccent } from "./look/accent";
import { DEVKIT_SEAT } from "./parts";
// World-space effects around the whole device, one draw call each:
@@ -29,6 +30,13 @@ import { DEVKIT_SEAT } from "./parts";
// All three add light and nothing else: see `lightOnly`. Each hides itself
// entirely while faded out, and prefers-reduced-motion slows the stream to a
// drift, stands the arcs still and turns the ripple into a plain glow.
+//
+// The stream and the Wi-Fi are the page's signs, so they are drawn in the
+// page's accent (look/accent.ts) โ the panel's colour, as the card's lit edge
+// is โ and flat: a full colour and no more, under what the bloom takes, the
+// same arcs as the DevKit's in chapter one. And they stop short of the copy
+// card: the canvas is behind the page, the card is glass, and coloured
+// pixels ran under its text.
// The LED face, measured off the model (world units): 1.6 ร 3.2, portrait,
// so the landscape 128 ร 64 panel stands 64 LEDs across and 128 down.
@@ -78,27 +86,52 @@ function seeded(seed: number) {
}
const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
-/** Screen x (NDC) of a world point, given a view-projection matrix's elements. */
-const ndcX = (vp: ArrayLike, x: number, y: number, z: number) =>
- (vp[0] * x + vp[4] * y + vp[8] * z + vp[12]) / (vp[3] * x + vp[7] * y + vp[11] * z + vp[15]);
const smooth = (e0: number, e1: number, x: number) => {
const t = Math.min(1, Math.max(0, (x - e0) / (e1 - e0)));
return t * t * (3 - 2 * t);
};
+/** The copy card on screen, px of the canvas (x right, y down); `on` false when there is none to keep clear of. */
+type CardRect = { on: boolean; l: number; t: number; r: number; b: number };
+/** How far outside the card the drawn light is all there, px: nearer than that it fades, and it is gone a little before the card's edge. */
+const CARD_CLEAR = 64;
+const CARD_GONE = 10;
+
+/**
+ * 0 at the card (and for CARD_GONE px round it) โฆ 1 well clear of it, for a
+ * world point; `vp` is the view-projection matrix's elements, `hw`/`hh` half
+ * the canvas's size in px.
+ */
+function clearOfCard(card: CardRect, vp: ArrayLike, hw: number, hh: number, x: number, y: number, z: number) {
+ if (!card.on) return 1;
+ const w = vp[3] * x + vp[7] * y + vp[11] * z + vp[15];
+ if (w <= 1e-5) return 1;
+ const sx = ((vp[0] * x + vp[4] * y + vp[8] * z + vp[12]) / w + 1) * hw;
+ const sy = (1 - (vp[1] * x + vp[5] * y + vp[9] * z + vp[13]) / w) * hh;
+ const dx = Math.max(card.l - sx, sx - card.r, 0);
+ const dy = Math.max(card.t - sy, sy - card.b, 0);
+ return smooth(CARD_GONE, CARD_CLEAR, Math.hypot(dx, dy));
+}
+
// โโ stream โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-// The Basics palette: LED oranges and reds, cyans, and two whites.
-const PALETTE = ["#ff6a3d", "#ff3b2f", "#ffab40", "#38d6ff", "#fff1de", "#e6f6ff", "#ff8a4c"].map((h) => new THREE.Color(h));
-// Two colours per ribbon, top ribbon first, warm and cool taking turns.
+// The stream's colours: the accent, the accent paled half-way to white, and
+// two whites โ made each frame from the page's accent (look/accent.ts), so a
+// packet in flight turns with the page.
+const WHITES = ["#fff1de", "#e6f6ff"].map((h) => new THREE.Color(h));
+/** [accent, pale accent, warm white, cool white] */
+const PALETTE = [new THREE.Color(), new THREE.Color(), WHITES[0], WHITES[1]];
+// Two colours per ribbon, top ribbon first.
const RIBBON_COLOURS: [number, number][] = [
- [0, 2],
- [3, 5],
- [1, 0],
- [4, 2],
- [3, 5],
- [6, 1],
+ [0, 1],
+ [1, 3],
+ [0, 0],
+ [2, 1],
+ [1, 3],
+ [0, 1],
];
+/** A full colour and no more: what the bloom takes starts above this (look/StagePost). */
+const STREAM_PEAK = 1.02;
const RIBBONS = RIBBON_COLOURS.length;
const PACKETS = 12; // per ribbon
@@ -170,7 +203,8 @@ function buildStream() {
phase: new Float32Array(P),
jit: new Float32Array(P * 3),
cycle: new Int32Array(P).fill(-1 << 30),
- rgb: new Float32Array(P * 3),
+ /** Which of the palette's colours the packet is. */
+ colour: new Uint8Array(P),
};
for (let r = 0; r < RIBBONS; r++) {
for (let p = 0; p < PACKETS; p++) {
@@ -233,7 +267,6 @@ void main() {
float wedge = smoothstep(0.95, 0.55, abs(ang)) * step(0.0, p.y);
float arcs = 0.0;
- float haze = 0.0;
for (int i = 0; i < 4; i++) {
float fi = float(i);
float ph = fract(uTime * 0.34 + fi * 0.25);
@@ -245,22 +278,22 @@ void main() {
float d = abs(r - R);
float w = 0.011 + 0.009 * ph;
arcs += (1.0 - smoothstep(w * 0.35, w, d)) * life;
- haze += exp(-d * d / 0.005) * life;
}
- float lit = (arcs + haze * 0.14) * wedge;
- float core = exp(-r * r / 0.0009) * 0.9 + exp(-r * r / 0.025) * 0.1;
- vec3 col = uColor * (lit * 2.3 + core * 2.2);
+ // Flat: a line of the accent at its own strength, no halo, and never more
+ // than a full colour โ over that it blooms, and these arcs glowed red here
+ // while the DevKit's, in chapter one, were plain.
+ float lit = arcs * wedge;
+ float core = exp(-r * r / 0.0009);
+ vec3 col = uColor * min(lit * 1.25 + core, 1.0);
// The pulse: a packet of square pixels, like the stream's, hopping along.
float pul = 0.0;
for (int k = 0; k < ${PULSES * PULSE_PTS}; k++) {
vec3 a = uPts[k];
vec2 dd = abs(vWorld - a.xy);
- float sq = max(dd.x, dd.y);
- float d2 = dot(dd, dd);
- pul += a.z * ((1.0 - smoothstep(0.014, 0.019, sq)) + 0.22 * exp(-d2 / 0.0025));
+ pul += a.z * (1.0 - smoothstep(0.014, 0.019, max(dd.x, dd.y)));
}
- col += mix(uColor, uHot, 0.4) * pul * uPulse * 2.2;
+ col += uHot * min(pul * 1.6, 1.0) * uPulse;
// The path itself, a row of small dim pixels.
float path = 0.0;
@@ -271,7 +304,7 @@ void main() {
}
col += uColor * path * uPulse;
- gl_FragColor = vec4(col * uFade, 0.0);
+ gl_FragColor = vec4(min(col, vec3(1.0)) * uFade, 0.0);
}
`;
@@ -409,6 +442,8 @@ export default function Fx() {
flashT: 10,
});
const tmp = useMemo(() => ({ v: new THREE.Vector3(), vp: new THREE.Matrix4() }), []);
+ // The step's card, measured now and then while something is drawn that must keep clear of it.
+ const card = useRef({ on: false, l: 0, t: 0, r: 0, b: 0, age: 0, key: "" });
useFrame((state, rawDt) => {
const dt = Math.min(rawDt, 0.1);
@@ -421,8 +456,45 @@ export default function Fx() {
o.narrow += ((narrow ? 1 : 0) - o.narrow) * Math.min(1, dt * 3);
const cam = state.camera;
const vp = tmp.vp.multiplyMatrices(cam.projectionMatrix, cam.matrixWorldInverse).elements;
- const edge = cardLeftNdc(state.size.width);
- const wideCard = 1 - o.narrow;
+ const hw = state.size.width / 2;
+ const hh = state.size.height / 2;
+
+ // The page's accent: the arcs and their path in it, the pulse a shade
+ // paler, the stream in both and white.
+ const accent = stageAccent();
+ PALETTE[0].copy(accent);
+ PALETTE[1].copy(accent).lerp(WHITES[0], 0.5);
+ wifi.mat.uniforms.uColor.value.copy(accent);
+ wifi.mat.uniforms.uHot.value.copy(accent).lerp(WHITES[0], 0.4);
+
+ // Where the step's card is (its block's one child โ GuideCanvas's
+ // freeArea reads it the same way). Measured every few frames, and at once
+ // on a new step: the page scrolls over the stage, and the card with it.
+ const cd = card.current;
+ if (s.stream || s.wifi === "device" || o.stream > 0.003 || o.wifi > 0.003) {
+ const key = scene + "." + step;
+ if (key !== cd.key || ++cd.age > 5) {
+ cd.key = key;
+ cd.age = 0;
+ const art = document.querySelector('[data-scene="' + scene + '"] [data-step="' + step + '"]');
+ const el = art && art.children.length === 1 ? (art.firstElementChild as HTMLElement) : art;
+ const box = el?.getBoundingClientRect();
+ const cv = state.gl.domElement.getBoundingClientRect();
+ if (box && box.width > 0 && cv.width > 0) {
+ const kx = state.size.width / cv.width;
+ const ky = state.size.height / cv.height;
+ cd.on = true;
+ cd.l = (box.left - cv.left) * kx;
+ cd.r = (box.right - cv.left) * kx;
+ cd.t = (box.top - cv.top) * ky;
+ cd.b = (box.bottom - cv.top) * ky;
+ } else {
+ cd.on = false;
+ }
+ }
+ } else {
+ cd.key = "";
+ }
// โโ install complete: read the board's pack for a few frames after each
// step edge (the Director applies the step's pack in the same frame,
@@ -499,11 +571,9 @@ export default function Fx() {
// A new packet: a colour.
pkt.cycle[pi] = cycle;
const pair = RIBBON_COLOURS[r];
- const c = PALETTE[hash(pi + 31, cycle) < 0.68 ? pair[0] : pair[1]];
- pkt.rgb[pi * 3] = c.r;
- pkt.rgb[pi * 3 + 1] = c.g;
- pkt.rgb[pi * 3 + 2] = c.b;
+ pkt.colour[pi] = hash(pi + 31, cycle) < 0.68 ? pair[0] : pair[1];
}
+ const colour = PALETTE[pkt.colour[pi]];
// Packets past the density hide โ whole packets, never half of one.
const dens = Math.min(1, Math.max(0, o.density * PACKETS - p));
// Stretch the cycle so the packet's last pixel finishes too.
@@ -530,10 +600,9 @@ export default function Fx() {
x = b0 * (sx + jx) + b1 * (ax + jx * 0.7) + b2 * (bx + jx * 0.3) + b3 * ex;
y = b0 * (sy + jy) + b1 * (ay + jy * 0.7) + b2 * (by + jy * 0.3) + b3 * ey;
z = b0 * (sz + jz) + b1 * (az + jz * 0.7) + b2 * (bz + jz * 0.3) + b3 * ez;
- // A dim glow while still behind the card, brightest mid-air,
- // fading as it goes in.
- const behind = smooth(edge - 0.05, edge + 0.03, ndcX(vp, x, y, z)) * wideCard;
- bright = smooth(0.02, 0.18, f) * (1 - behind * 0.82) * (1 - q * 0.075) * 2.1 * (1 - smooth(0.82, 1, f));
+ // Out from the card's edge โ nothing under the card itself โ
+ // brightest mid-air, fading as it goes in.
+ bright = smooth(0.02, 0.18, f) * clearOfCard(cd, vp, hw, hh, x, y, z) * (1 - q * 0.075) * STREAM_PEAK * (1 - smooth(0.82, 1, f));
size = lerp(0.034, 0.022, q / (PER - 1));
bright *= fade * dens;
}
@@ -556,9 +625,9 @@ export default function Fx() {
m[i16 + 13] = y;
m[i16 + 14] = z;
m[i16 + 15] = 1;
- cArr[idx * 3] = pkt.rgb[pi * 3] * bright;
- cArr[idx * 3 + 1] = pkt.rgb[pi * 3 + 1] * bright;
- cArr[idx * 3 + 2] = pkt.rgb[pi * 3 + 2] * bright;
+ cArr[idx * 3] = colour.r * bright;
+ cArr[idx * 3 + 1] = colour.g * bright;
+ cArr[idx * 3 + 2] = colour.b * bright;
}
}
}
@@ -596,9 +665,8 @@ export default function Fx() {
const ia = 1 - a;
pt.x = ia * ia * WIFI_ORIGIN.x + 2 * ia * a * PULSE_CTRL.x + a * a * PULSE_END.x;
pt.y = ia * ia * WIFI_ORIGIN.y + 2 * ia * a * PULSE_CTRL.y + a * a * PULSE_END.y;
- // Out of the arcs, over to the card, gone at its edge.
- const gone = smooth(edge - 0.07, edge + 0.01, ndcX(vp, pt.x, pt.y, 0)) * wideCard;
- pt.z = smooth(0.04, 0.16, a) * (1 - smooth(0.9, 1, a)) * (1 - gone) * (1 - (j / PULSE_PTS) * 0.8);
+ // Out of the arcs, over to the card, gone before its edge.
+ pt.z = smooth(0.04, 0.16, a) * (1 - smooth(0.9, 1, a)) * clearOfCard(cd, vp, hw, hh, pt.x, pt.y, 0) * (1 - (j / PULSE_PTS) * 0.8);
}
}
// The path: dim dots from just out of the arcs to the card's edge.
@@ -608,8 +676,7 @@ export default function Fx() {
const pt = wifi.path[j];
pt.x = ia * ia * WIFI_ORIGIN.x + 2 * ia * a * PULSE_CTRL.x + a * a * PULSE_END.x;
pt.y = ia * ia * WIFI_ORIGIN.y + 2 * ia * a * PULSE_CTRL.y + a * a * PULSE_END.y;
- const gone = smooth(edge - 0.05, edge + 0.01, ndcX(vp, pt.x, pt.y, 0)) * wideCard;
- pt.z = 0.22 * smooth(0.1, 0.22, a) * (1 - gone);
+ pt.z = 0.22 * smooth(0.1, 0.22, a) * clearOfCard(cd, vp, hw, hh, pt.x, pt.y, 0);
}
}
}
diff --git a/web/src/components/guide/stage/GuideCanvas.tsx b/web/src/components/guide/stage/GuideCanvas.tsx
index 171c0f52..7ddb8c9f 100644
--- a/web/src/components/guide/stage/GuideCanvas.tsx
+++ b/web/src/components/guide/stage/GuideCanvas.tsx
@@ -6,29 +6,44 @@
import { Canvas, useFrame, useThree } from "@react-three/fiber";
import { Environment, Lightformer } from "@react-three/drei";
-import { EffectComposer, Bloom, N8AO, ToneMapping, Vignette } from "@react-three/postprocessing";
-import { ToneMappingMode } from "postprocessing";
import { lazy, Suspense, useEffect, useMemo, useRef, useState } from "react";
import * as THREE from "three";
import Device from "./Device";
+import Explode from "./Explode";
import Fx from "./Fx";
-import { LED_CENTER_WORLD, MODEL_OFFSET, MODEL_SCALE } from "./geometry";
+import StageHand from "./StageHand";
+import { smoothDamp, type Damp } from "./damp";
+import { explodeWanted } from "./explodeParts";
+import { MODEL_OFFSET, MODEL_SCALE } from "./geometry";
+import { hand } from "./hand";
+import { HUB_VIEWS } from "./hubViews";
+import { stageFocus } from "./look/focus";
+import { settingsFor, useTier } from "./look/quality";
+import { PanelAir, PanelLights, StageFloor } from "./look/StageLight";
+import StagePost from "./look/StagePost";
import { VIEWS } from "./views";
import { getSim, useGuideStore } from "../store";
import { stepOf, type DemoAction } from "../scenes";
import { buildClock, kitState } from "../timing";
import { beatIndex } from "./build/beats";
-
-// The stage: one canvas behind the whole page. It never scrolls; the page
-// scrolls over it and the Director below turns the scroll position into
-// what the device does and where the camera stands.
+import { awayFraming, hubFraming, type Framing, type Free } from "../world/framing";
+
+// The stage: one canvas behind the whole guide. It is mounted once, above
+// the pages (world/GuideWorld, from app/guide/layout.tsx), and stays up while
+// the reader goes between the hub, Build and Play, in either language: the
+// board, the camera and the loaded models carry over, and what changes from
+// page to page โ the script (store.page), the framing (world/framing.ts) โ
+// is eased into. It never scrolls; the page scrolls over it and the Director
+// below turns the scroll position into what the device does and where the
+// camera stands. On Make, which has a desk instead, the device stands far
+// back, the canvas fades (Guide.module.css) and the frame loop rests.
// The Build guide's bench, plates and assembly (build/BuildStage): loaded
// only on that page, after the device, which it takes over and adds to.
const BuildStage = lazy(() => import("./build/BuildStage"));
function Director() {
- const last = useRef({ scene: "", step: -1, clock: 0, fired: new Set() });
+ const last = useRef({ page: "", scene: "", step: -1, clock: 0, fired: new Set() });
useFrame((_, dt) => {
const sim = getSim();
@@ -36,7 +51,10 @@ function Director() {
const s = stepOf(scene, step);
const d = last.current;
- if (d.scene !== scene || d.step !== step) {
+ // Another page's opening is another step, though both are "opening", 0:
+ // the board is put in the new page's state (the hub's is lit, Build's dark).
+ if (d.page !== page || d.scene !== scene || d.step !== step) {
+ d.page = page;
d.scene = scene;
d.step = step;
d.clock = 0;
@@ -99,18 +117,17 @@ function Director() {
// what must be on screen (views.ts), and the rig finds the distance at which
// that fits the part of the screen the copy leaves free โ left of the card
// on a wide screen, above it on a narrow one โ at this screen's aspect.
+//
+// And it leans toward the reader's hand: a few degrees round its subject to
+// the side the mouse is on (hand.ts), so the device is a thing standing in
+// front of you and not a film of one. It goes round what it is looking at,
+// so nothing leaves the frame; it is eased in and out, never switched; and
+// it is level again while the reader has a knob, for a finger, and for a
+// reader who asked for less motion.
-type Damp = { v: number };
-
-function smoothDamp(current: number, target: number, vel: Damp, smoothTime: number, dt: number) {
- const omega = 2 / Math.max(0.0001, smoothTime);
- const x = omega * dt;
- const exp = 1 / (1 + x + 0.48 * x * x + 0.235 * x * x * x);
- const change = current - target;
- const temp = (vel.v + omega * change) * dt;
- vel.v = (vel.v - omega * temp) * exp;
- return target + (change + temp) * exp;
-}
+/** How far round its subject the camera leans with the mouse at the window's edge: the tangents of 3.2ยฐ across and 2ยฐ up. */
+const LEAN_X = 0.056;
+const LEAN_Y = 0.035;
function wrapAngle(a: number) {
return Math.atan2(Math.sin(a), Math.cos(a));
@@ -119,9 +136,6 @@ function wrapAngle(a: number) {
// The device's box in world units; the camera keeps a margin from it.
const DEVICE_BOX = new THREE.Box3(new THREE.Vector3(-1.3, -1.7, -0.3), new THREE.Vector3(1.3, 1.75, 0.45));
-/** The free part of the screen, in CSS px. */
-type Free = { l: number; r: number; t: number; b: number };
-
// Where the step's card is when the reader is on that step (its block
// centred; the opening at the top of the page), and so what it leaves free.
function freeArea(scene: string, step: number, w: number, h: number, narrow: boolean, tallCards: boolean): Free {
@@ -205,7 +219,7 @@ type RigState = {
ox: Damp;
oy: Damp;
offset: { x: number; y: number };
- free: Free;
+ framing: Framing;
freeKey: string;
freeAge: number;
};
@@ -225,11 +239,12 @@ function CameraRig({ reducedMotion }: { reducedMotion: boolean }) {
ox: { v: 0 },
oy: { v: 0 },
offset: { x: 0, y: 0 },
- free: { l: 0, r: 1, t: 0, b: 1 },
+ framing: { free: { l: 0, r: 1, t: 0, b: 1 }, scale: 1 },
freeKey: "",
freeAge: 0,
});
- const pointer = useRef({ x: 0, y: 0, sx: 0, sy: 0 });
+ // The lean: where it is, eased, and how much of it there is (0 while the reader has the knobs).
+ const pointer = useRef({ sx: 0, sy: 0, w: 0 });
const tmp = useMemo(
() => ({
d: new THREE.Vector3(),
@@ -241,19 +256,13 @@ function CameraRig({ reducedMotion }: { reducedMotion: boolean }) {
[],
);
- useEffect(() => {
- const onMove = (e: PointerEvent) => {
- pointer.current.x = (e.clientX / window.innerWidth) * 2 - 1;
- pointer.current.y = (e.clientY / window.innerHeight) * 2 - 1;
- };
- window.addEventListener("pointermove", onMove);
- return () => window.removeEventListener("pointermove", onMove);
- }, []);
-
useFrame((state, rawDt) => {
const dt = Math.min(rawDt, 1 / 20);
- const { scene, step, narrow, handsOn, page } = useGuideStore.getState();
+ const { scene, step, narrow, handsOn, page, lang, hubTop } = useGuideStore.getState();
const s = stepOf(scene, step);
+ // The hub, with Build pointed at: the device is coming apart (Explode),
+ // and the camera goes round to where its layers show.
+ const apart = explodeWanted();
// A DevKit view before the DevKit is out from behind the case (scrolling
// back up into chapter one, say) would stare at empty air while the back
// cover comes off; it watches from behind, as the chapter's first step
@@ -267,33 +276,41 @@ function CameraRig({ reducedMotion }: { reducedMotion: boolean }) {
// A Build step with two places to look at on a narrow screen (scenes.ts
// narrowLate): its second view from that far through its beat.
const late = narrow && s.narrowLate && s.build !== undefined && buildClock.t - beatIndex(s.build) >= s.narrowLate.from ? s.narrowLate.view : null;
- const view = VIEWS[(devkitView && !kitState.out) || reassembling ? "back" : (late ?? ((narrow && s.narrowView) || s.view))];
+ const view = apart ? HUB_VIEWS.exploded : VIEWS[(devkitView && !kitState.out) || reassembling ? "back" : (late ?? ((narrow && s.narrowView) || s.view))];
const c = st.current;
const cam = camera as THREE.PerspectiveCamera;
const w = size.width;
const h = size.height;
- // What the copy leaves free: measured when the step or the screen
- // changes, and now and then in case the card grew (fonts, images).
- const key = `${scene}.${step}.${w}x${h}.${narrow ? 1 : 0}`;
+ // What the page leaves free (world/framing.ts): measured when the page,
+ // the step or the screen changes, and now and then in case the card grew
+ // (fonts, images). The hub's is above its choices; Make has no device,
+ // and it stands far back there.
+ const key = `${page}.${lang}.${scene}.${step}.${w}x${h}.${narrow ? 1 : 0}.${hubTop}`;
if (key !== c.freeKey || ++c.freeAge > 45) {
- c.free = freeArea(scene, step, w, h, narrow, page === "build");
+ c.framing =
+ page === "hub"
+ ? hubFraming(w, h, hubTop, narrow)
+ : page === "make"
+ ? awayFraming(w, h)
+ : { free: freeArea(scene, step, w, h, narrow, page === "build"), scale: 1 };
c.freeKey = key;
c.freeAge = 0;
}
- const free = c.free;
+ const { free, scale } = c.framing;
// Where this step wants the camera, in spherical terms around its target.
let wantAz = Math.atan2(view.dir.x, view.dir.z);
const wantEl = Math.asin(THREE.MathUtils.clamp(view.dir.y, -1, 1));
- if (s.spin && !reducedMotion) wantAz += Math.sin(state.clock.elapsedTime * s.spin) * 0.5;
+ // Taken apart, it sways a little; whole, it turns.
+ if (s.spin && !reducedMotion) wantAz += Math.sin(state.clock.elapsedTime * s.spin) * (apart ? 0.1 : 0.5);
const cosWantEl = Math.cos(wantEl);
tmp.d.set(Math.sin(wantAz) * cosWantEl, Math.sin(wantEl), Math.cos(wantAz) * cosWantEl);
// Back off along that line until the view's frame fits the free area.
const tanHalf = Math.tan(THREE.MathUtils.degToRad(cam.fov / 2));
const hx = ((free.r - free.l) / w) * view.fill;
const hy = ((free.b - free.t) / h) * view.fill;
- const wantR = Math.max(view.minR, fitDistance(view.target, tmp.d, view.frame, tanHalf, w / h, hx, hy, tmp.fit));
+ const wantR = Math.max(view.minR * scale, fitDistance(view.target, tmp.d, view.frame, tanHalf, w / h, hx, hy, tmp.fit));
if (!c.init) {
// Arrive from a little further out and round, once, on load.
@@ -326,15 +343,19 @@ function CameraRig({ reducedMotion }: { reducedMotion: boolean }) {
const cosEl = Math.cos(c.el);
tmp.p.set(Math.sin(c.az) * cosEl, Math.sin(c.el), Math.cos(c.az) * cosEl).multiplyScalar(c.r).add(c.target);
- // A little parallax from the pointer, smoothed; none while on the knobs.
- const par = reducedMotion || handsOn ? 0 : 0.12 * (c.r / 8);
+ // The lean toward the hand (see the top of this section): round the
+ // target, by the mouse's place in the window โ level with the mouse gone
+ // from the window, and eased out to nothing while the reader has a knob
+ // (a turn is a circle drawn round the knob's place on screen).
const pt = pointer.current;
- pt.sx += (pt.x - pt.sx) * Math.min(1, dt * 2);
- pt.sy += (pt.y - pt.sy) * Math.min(1, dt * 2);
+ const follow = Math.min(1, dt * 2.4);
+ pt.sx += ((hand.here ? hand.x : 0) - pt.sx) * follow;
+ pt.sy += ((hand.here ? hand.y : 0) - pt.sy) * follow;
+ pt.w += ((reducedMotion || handsOn ? 0 : 1) - pt.w) * Math.min(1, dt * 5);
tmp.d.subVectors(c.target, tmp.p).normalize();
tmp.right.crossVectors(tmp.d, camera.up).normalize();
tmp.up.crossVectors(tmp.right, tmp.d).normalize();
- tmp.p.addScaledVector(tmp.right, pt.sx * par).addScaledVector(tmp.up, -pt.sy * par * 0.6);
+ tmp.p.addScaledVector(tmp.right, pt.sx * pt.w * c.r * LEAN_X).addScaledVector(tmp.up, -pt.sy * pt.w * c.r * LEAN_Y);
// Never inside the device, whatever the springs are doing.
const m = 0.35;
@@ -349,6 +370,9 @@ function CameraRig({ reducedMotion }: { reducedMotion: boolean }) {
camera.position.copy(tmp.p);
camera.lookAt(c.target);
+ // What the lens is on, for the depth of field (look/StagePost).
+ stageFocus.target.copy(c.target);
+ stageFocus.r = c.r;
// Composition: the copy takes the right side on a wide screen and the
// bottom on a narrow one, so the target moves to the middle of what it
@@ -397,97 +421,85 @@ function Warmup() {
return null;
}
-// โโ light from the panel โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+// โโ light โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
//
-// An LED panel is a light. A point light just in front of it takes the
-// average colour of what the board is showing, so the knobs, the case edge
-// and the floor catch the pattern's colour the way they do in a dark room.
+// The room has two kinds of light. The studio's: a soft key from above right
+// with a wide soft shadow, three rims and fills neutral enough that the white
+// case stays white, and a set of light panels for anything glossy or metal to
+// reflect (below). And the device's own: the LED panel is a light, and the
+// colours of the pattern on it reach the knobs, the bench, the floor and the
+// dark round it โ look/StageLight.tsx (PanelLights, StageFloor, PanelAir),
+// fed by what the panel is showing (look/panelGlow.ts).
//
-// It has no shadow, so it lights whatever faces it, through anything. On the
-// Build guide the panel's back stands open to a camera behind it (check-4,
-// before the back goes on), and the ribs and band there glowed with the
-// pattern's colour โ a panel shining through itself. So on that page the
-// light goes out as the camera comes round behind the panel's plane; the
-// floor's spill, which it is for, is in front and not in those shots.
-
-function PanelLight() {
- const light = useRef(null);
- const color = useMemo(() => new THREE.Color(), []);
- const n = useRef(0);
- useFrame((state) => {
- const l = light.current;
- if (!l || n.current++ % 3) return;
- // 1 in front of the panel, 0 behind it (world z: its faces are at ยฑ0.1).
- const front = useGuideStore.getState().page === "build" ? THREE.MathUtils.clamp((state.camera.position.z + 0.3) / 0.6, 0, 1) : 1;
- const f = getSim().frame;
- let r = 0;
- let g = 0;
- let b = 0;
- // Every 8th pixel is plenty for an average.
- for (let i = 0; i < f.length; i += 32) {
- r += f[i];
- g += f[i + 1];
- b += f[i + 2];
- }
- const count = f.length / 32;
- r /= count * 255;
- g /= count * 255;
- b /= count * 255;
- const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
- const peak = Math.max(r, g, b);
- if (peak > 0.0001) color.setRGB(r / peak, g / peak, b / peak);
- l.color.lerp(color, 0.25);
- l.intensity += (Math.min(4, lum * 9) * front - l.intensity) * 0.2;
- });
+// The panel's lights have no shadow, so they light whatever faces them,
+// through anything. On the Build guide the panel's back stands open to a
+// camera behind it (check-4, before the back goes on), and the ribs and band
+// there glowed with the pattern's colour โ a panel shining through itself.
+// So on that page they go out as the camera comes round behind the panel's
+// plane; what they are for is in front and not in those shots.
+
+/** The key light. Its shadow map follows the quality tier: the old map is let go when the size changes. */
+function KeyLight({ shadows, mapSize }: { shadows: boolean; mapSize: number }) {
+ const light = useRef(null);
+ const made = useRef(mapSize);
+ useEffect(() => {
+ const s = light.current?.shadow;
+ if (!s || made.current === mapSize) return;
+ made.current = mapSize;
+ // Both of VSM's targets: three makes them again, at the new size, on the next frame.
+ s.map?.dispose();
+ s.map = null;
+ s.mapPass?.dispose();
+ s.mapPass = null;
+ }, [mapSize]);
return (
-
-
- );
-}
-
-// ?gdebug=nobloom,noshadow,noenv,noao โ for bisecting what a GPU objects to.
+// ?gdebug=nobloom,noshadow,noenv,noao,nodof โ for bisecting what a GPU objects to. (?gq=0|1|2 pins the quality tier: look/quality.ts.)
function debugFlags(): Set {
if (typeof window === "undefined") return new Set();
return new Set((new URLSearchParams(window.location.search).get("gdebug") ?? "").split(",").filter(Boolean));
}
+/** Make has the desk: how long the device takes to leave before the frame loop rests, ms (the canvas's fade is Guide.module.css's). */
+const REST_AFTER_MS = 1400;
+
export default function GuideCanvas() {
const flags = debugFlags();
const narrow = useGuideStore((s) => s.narrow);
- const page = useGuideStore((s) => s.page);
+ // The Build guide's stage: on with its guide, and off it until it has run
+ // the build to the whole device and handed it back (store.buildLive).
+ const building = useGuideStore((s) => s.page === "build" || s.buildLive);
+ // Make: the device has left. Once it has, nothing is drawn until it comes back.
+ const away = useGuideStore((s) => s.page === "make");
+ const [rested, setRested] = useState(false);
+ useEffect(() => {
+ if (!away) return;
+ const timer = window.setTimeout(() => setRested(true), REST_AFTER_MS);
+ return () => {
+ window.clearTimeout(timer);
+ setRested(false);
+ };
+ }, [away]);
const [reducedMotion, setReducedMotion] = useState(false);
useEffect(() => {
const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
@@ -496,62 +508,59 @@ export default function GuideCanvas() {
mq.addEventListener("change", set);
return () => mq.removeEventListener("change", set);
}, []);
- const ao = !narrow && !flags.has("noao");
+ // How much this machine draws (look/quality.ts): measured, and stepped down if its frames run long.
+ const quality = settingsFor(useTier(), narrow);
+ const shadows = !flags.has("noshadow");
return (
+
)}
-
+ {/* Straight after the device: each frame it adds to where the device
+ has put its parts (the hub's answer to Build). */}
+
@@ -560,24 +569,11 @@ export default function GuideCanvas() {
-
- ) : (
-
-
- ))}
+ {/* The reader's mouse on the stage: the light it carries, and the hub's panel under it. After the rig, whose camera it reads. */}
+
);
}
diff --git a/web/src/components/guide/stage/KitFx.tsx b/web/src/components/guide/stage/KitFx.tsx
index b34cf36a..3f66ed8e 100644
--- a/web/src/components/guide/stage/KitFx.tsx
+++ b/web/src/components/guide/stage/KitFx.tsx
@@ -12,6 +12,8 @@ import { getSim, useGuideStore } from "../store";
import { stepOf } from "../scenes";
import { bootPhase, kitState, RST_PULSE, rstPulseDown } from "../timing";
import { MODEL_OFFSET, MODEL_SCALE } from "./geometry";
+import { kitPress } from "./hand";
+import { stageAccent } from "./look/accent";
import { DEVKIT_PRESENT, DEVKIT_SEAT, KIT, M_TO_MODEL } from "./parts";
import { NO_POINTER, pillSize, placeTag, screenY, type TagSide } from "./tags";
@@ -231,7 +233,10 @@ export default function KitFx({ boot, rst }: Props) {
const waves = useMemo(
() =>
[0, 1, 2].map(() => {
- const mat = new THREE.MeshBasicMaterial({ color: LED, transparent: true, opacity: 0, toneMapped: false, depthWrite: false, side: THREE.DoubleSide });
+ // They write depth: they are thin, nothing is behind them to hide, and
+ // the stage's soft focus (look/StagePost) needs to know they are here
+ // at the antenna and not out with the background.
+ const mat = new THREE.MeshBasicMaterial({ color: LED, transparent: true, opacity: 0, toneMapped: false, side: THREE.DoubleSide });
const arc = Math.PI * 0.5;
const m = new THREE.Mesh(new THREE.TorusGeometry(0.0055, 0.0004, 6, 40, arc), mat);
m.rotation.z = Math.PI / 2 - arc / 2;
@@ -388,6 +393,11 @@ export default function KitFx({ boot, rst }: Props) {
rstDown = rstPulseDown(rstSince - 500 + RST_PULSE.down);
}
const rstIdle = rstNow ? 0.3 + 0.15 * Math.sin(t * 3) : 0.25;
+ // โฆand under the reader's own finger, on that step (Device.tsx, hand.ts kitPress): the same press.
+ if (s.bootSeq) {
+ bootDown ||= kitPress.boot;
+ rstDown ||= kitPress.rst;
+ }
if (!presented) {
bootDown = false;
rstDown = false;
@@ -406,10 +416,13 @@ export default function KitFx({ boot, rst }: Props) {
// The DevKit's own light, up while it is held up in front.
light.intensity += ((presented ? KIT_LIGHT : 0) - light.intensity) * Math.min(1, dt * 3);
+ // The Wi-Fi's arcs are the page's sign, as the device's own are (Fx.tsx): in the page's accent.
+ const accent = stageAccent();
waves.forEach((w, i) => {
const phase = (((t * 0.7 + i / 3) % 1) + 1) % 1;
w.scale.setScalar(1 + phase * 1.9);
const mat = w.material as THREE.MeshBasicMaterial;
+ mat.color.copy(accent);
const target = s.wifi === "esp" ? (1 - phase) * 0.9 * here : 0;
mat.opacity += (target - mat.opacity) * Math.min(1, dt * (s.wifi === "esp" ? 6 : 10));
w.visible = mat.opacity > 0.01;
diff --git a/web/src/components/guide/stage/StageHand.tsx b/web/src/components/guide/stage/StageHand.tsx
new file mode 100644
index 00000000..a8f0c698
--- /dev/null
+++ b/web/src/components/guide/stage/StageHand.tsx
@@ -0,0 +1,181 @@
+"use client";
+
+/* eslint-disable react-hooks/immutability --
+ A light is an imperative three.js object driven from the frame loop; that
+ is its API and it never feeds back into React. */
+
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { getSim, useGuideStore } from "../store";
+import { handSteer } from "../world/hubHand";
+import { touchSpot } from "./build/touchState";
+import { LED_CENTER_WORLD } from "./geometry";
+import { hand, handGone } from "./hand";
+import { stageFocus } from "./look/focus";
+
+// The stage answers the hand.
+//
+// The guide's stage played like a film: everything on it moved by the script
+// and nothing by the reader, short of taking a knob. This is the reader's
+// mouse on it (hand.ts), and the two things it carries here:
+//
+// a light a torch in the hand: a narrow, soft-edged beam from beside the
+// eye to where the pointer is, so it rakes over what it passes โ
+// the print's layers, the knobs' flanks, the board's mask, the
+// bench. It has no fall-off with distance, on purpose. It used to
+// be a small bulb held in the air just in front of the subject,
+// and on the hub, where the view swings round the device, the
+// case's near corner and the knobs came through that spot: the
+// closer they swung, the harder they were lit, brightest with
+// the device on the diagonal. A beam gives every surface the
+// same light however the device is turned. It is weak beside the
+// key light and it cannot touch the panel (whose face is its own
+// light, not a lit surface): it adds a highlight, it does not
+// relight the room. On the Build guide it goes to the part the
+// parts list is pointing at (build/touchState.ts touchSpot).
+// the hub the pointer on the panel steers the pattern a little, as two
+// knobs would (world/hubHand.ts: the arithmetic, and giving the
+// board back).
+//
+// The camera's lean toward the pointer is the rig's (GuideCanvas CameraRig),
+// and the Build guide's parts are BuildStage's (build/touch.ts); both read
+// the same hand.
+//
+// None of it is there for a finger (a touch is a scroll or a knob), for a
+// reader who asked for less motion, or on Make, where the stage rests. The
+// pointer is read on pointer events only; a frame does a ray, a plane and
+// two eases.
+//
+// The light is always in the scene, at nothing when it is not wanted: a light
+// coming or going changes every lit shader on the stage (GuideCanvas, on the
+// panel's lights).
+
+/** The floor (look/StageLight.tsx), and how near it the light may come. */
+const FLOOR_Y = -1.66;
+const FLOOR_CLEAR = 0.32;
+/**
+ * What the beam gives a surface that faces it, against the key light's 2.4,
+ * by page. What it lands on decides how much it takes to be seen: the Build
+ * guide's bench and board are dark, and a weak beam vanishes on them; the hub
+ * and Play are mostly the white case, already near the top of the picture's
+ * range, where the same strength would bleach it.
+ */
+const GIVES: Record = { hub: 0.8, play: 0.9, build: 1.9 };
+/** How many times that for the part the parts list points at: there the light is all the pointing there is. */
+const SPOT = 1.35;
+/** The beam's half-angle, radians: about a sixth of the picture's height across, whatever the view. */
+const BEAM = 0.085;
+/** Where the torch is held, beside and above the eye, as a share of the distance to the subject: enough to rake. */
+const HELD = { right: 0.26, up: 0.18 };
+/** The panel's lit face: its plane and half-sizes, world units (look/StageLight.tsx FACE). */
+const PANEL = { z: 0.15, hw: 0.8, hh: 1.6 };
+
+export default function StageHand({ reducedMotion }: { reducedMotion: boolean }) {
+ const gl = useThree((s) => s.gl);
+ const light = useRef(null);
+ // What the beam is pointed at; the light itself stays by the eye.
+ const aim = useMemo(() => new THREE.Object3D(), []);
+ const lit = useRef(0);
+ const at = useMemo(() => ({ u: 0, v: 0 }), []);
+ const tmp = useMemo(
+ () => ({ dir: new THREE.Vector3(), view: new THREE.Vector3(), to: new THREE.Vector3(), want: new THREE.Vector3(), right: new THREE.Vector3(), up: new THREE.Vector3() }),
+ [],
+ );
+
+ // Where the mouse is (hand.ts). A finger is never the hand.
+ useEffect(() => {
+ const canvas = gl.domElement;
+ const onMove = (e: PointerEvent) => {
+ if (e.pointerType !== "mouse") return;
+ hand.px = e.clientX;
+ hand.py = e.clientY;
+ hand.x = (e.clientX / window.innerWidth) * 2 - 1;
+ hand.y = (e.clientY / window.innerHeight) * 2 - 1;
+ hand.here = true;
+ hand.onStage = e.target === canvas;
+ hand.moves++;
+ };
+ const onDown = (e: PointerEvent) => {
+ if (e.pointerType !== "mouse") handGone();
+ };
+ const onHide = () => {
+ if (document.hidden) handGone();
+ };
+ const root = document.documentElement;
+ window.addEventListener("pointermove", onMove, { passive: true });
+ window.addEventListener("pointerdown", onDown, { passive: true });
+ window.addEventListener("blur", handGone);
+ root.addEventListener("pointerleave", handGone);
+ document.addEventListener("visibilitychange", onHide);
+ return () => {
+ window.removeEventListener("pointermove", onMove);
+ window.removeEventListener("pointerdown", onDown);
+ window.removeEventListener("blur", handGone);
+ root.removeEventListener("pointerleave", handGone);
+ document.removeEventListener("visibilitychange", onHide);
+ handGone();
+ };
+ }, [gl]);
+
+ useFrame((state, rawDt) => {
+ const dt = Math.min(rawDt, 0.1);
+ const { page, leaving } = useGuideStore.getState();
+ const cam = state.camera;
+ const l = light.current;
+ const over = hand.here && hand.onStage && !reducedMotion;
+ // The card's part, on the Build guide: the light is there, wherever the pointer is.
+ const spot = touchSpot.on && page === "build" && !reducedMotion;
+ const wanted = (over || spot) && !leaving && page !== "make";
+
+ let onPanel = false;
+ if (wanted || (over && page === "hub")) {
+ cam.updateMatrixWorld();
+ const { dir, view, to, want } = tmp;
+ // The line from the eye through the pointer.
+ dir.set(hand.x, -hand.y, 0.5).unproject(cam).sub(cam.position).normalize();
+
+ if (l && wanted) {
+ cam.getWorldDirection(view);
+ if (spot) want.set(touchSpot.x, touchSpot.y, touchSpot.z);
+ else {
+ // Where the pointer's line meets the plane the camera is on โ and
+ // never under the floor, which that plane goes through in a view
+ // from above.
+ let d = view.dot(to.subVectors(stageFocus.target, cam.position)) / Math.max(0.2, dir.dot(view));
+ if (dir.y < -1e-3) d = Math.min(d, (FLOOR_Y + FLOOR_CLEAR - cam.position.y) / dir.y);
+ want.copy(cam.position).addScaledVector(dir, Math.max(0.3, d));
+ }
+ // The beam trails the pointer a little; lit from nothing, it is simply there.
+ if (lit.current < 0.004) aim.position.copy(want);
+ else aim.position.lerp(want, 1 - Math.exp(-dt * 16));
+ // The torch: beside and a little above the eye, so the beam rakes.
+ const r = Math.max(1, stageFocus.r);
+ tmp.right.setFromMatrixColumn(cam.matrixWorld, 0);
+ tmp.up.setFromMatrixColumn(cam.matrixWorld, 1);
+ l.position.copy(cam.position).addScaledVector(tmp.right, r * HELD.right).addScaledVector(tmp.up, r * HELD.up);
+ // (The card's part is lit harder: there the light is all the pointing there is.)
+ lit.current += ((GIVES[page] ?? 0.8) * (spot ? SPOT : 1) - lit.current) * (1 - Math.exp(-dt * 9));
+ }
+
+ // The hub: where on the panel the pointer is, from in front of it.
+ if (over && page === "hub" && cam.position.z > PANEL.z && dir.z < -1e-3) {
+ const s = (PANEL.z - cam.position.z) / dir.z;
+ at.u = (cam.position.x + dir.x * s - LED_CENTER_WORLD.x) / PANEL.hw;
+ at.v = (cam.position.y + dir.y * s - LED_CENTER_WORLD.y) / PANEL.hh;
+ onPanel = Math.abs(at.u) <= 1 && Math.abs(at.v) <= 1;
+ }
+ }
+ if (!wanted) lit.current += (0 - lit.current) * (1 - Math.exp(-dt * 6));
+ if (l) l.intensity = lit.current < 0.002 ? 0 : lit.current;
+
+ if (page === "hub") handSteer(getSim(), onPanel ? at : null, dt * 1000);
+ });
+
+ return (
+ <>
+ = {
J3: [S2 + 0.12, S2 + 0.26],
J4: [S2 + 0.2, S2 + 0.34],
C11: [S3 + 0.04, S3 + 0.34],
- SW1: [S4 + 0.38, S4 + 0.5],
- SW2: [S4 + 0.42, S4 + 0.54],
- SW3: [S4 + 0.46, S4 + 0.58],
- SW4: [S4 + 0.5, S4 + 0.62],
+ SW1: [S4 + 0.31, S4 + 0.43],
+ SW2: [S4 + 0.345, S4 + 0.465],
+ SW3: [S4 + 0.38, S4 + 0.5],
+ SW4: [S4 + 0.415, S4 + 0.535],
};
/**
* The board turns over (B side up) and back for each round of joints. The
@@ -176,8 +244,8 @@ const FLIPS: [number, number][] = [
[S2 + 0.91, S2 + 0.99],
[S3 + 0.4, S3 + 0.49],
[S3 + 0.88, S3 + 0.97],
- [S4 + 0.29, S4 + 0.36],
- [S4 + 0.64, S4 + 0.71],
+ [S4 + 0.22, S4 + 0.29],
+ [S4 + 0.55, S4 + 0.62],
[S4 + 0.9, S4 + 0.98],
[C1 + 0.04, C1 + 0.2],
];
@@ -186,7 +254,7 @@ const ROUNDS: { refs: string[]; from: number; to: number }[] = [
{ refs: ["U1"], from: S1 + 0.6, to: S1 + 0.88 },
{ refs: ["J1", "J3", "J4"], from: S2 + 0.52, to: S2 + 0.88 },
{ refs: ["C11"], from: S3 + 0.55, to: S3 + 0.8 },
- { refs: ["SW1", "SW2", "SW3", "SW4"], from: S4 + 0.73, to: S4 + 0.87 },
+ { refs: ["SW1", "SW2", "SW3", "SW4"], from: S4 + 0.64, to: S4 + 0.87 },
];
/** When the soldered board is carried from the bench to behind its bay (case-3): after the lead is through the hole. */
@@ -200,12 +268,95 @@ const BOARD_OVER: [number, number] = [C3 + 0.4, C3 + 0.7];
*/
const OVER_TOP = [52, 60, -9] as const;
+/** From here on the device is whole again: the last knob is on (check-5), the bench long gone. */
+const WHOLE_AGAIN = at("next");
+
+/** Further than this (beats) from where the stage must be when the guide is opened or left, it cuts there instead of running through. */
+const CUT_FAR = 2;
+/** How long after asking for a cut the canvas is out, ms (Guide.module.css [data-cut]: 0.14 s). */
+const CUT_DARK_MS = 170;
+
+/** Before it takes the device over, the stage builds its shaders only while the camera is slower than this, world units a second (the opening's own sway is a quarter of it). */
+const WARM_STILL = 1.2;
+
/** The print's layer, model units (0.2 mm). */
const LAYER = 0.02;
+/** How many pieces of the bead behind the nozzle are drawn, and how long each is (a share of the tour). */
+const BEAD = 20;
+const BEAD_STEP = 0.009;
+
+type TourStop = { x: number; z: number; at: number; part: number };
+/** Where on a plate's tour (BuildStage kit.plates) the nozzle is, `along` of the way round (0โฆ1): writes x, z; returns which part's wall it is laying there, โ1 while it crosses to the next part. */
+function tourAt(tour: TourStop[], length: number, along: number, out: THREE.Vector3) {
+ const d = along * length;
+ let i = 1;
+ while (i < tour.length - 1 && tour[i].at < d) i++;
+ const a = tour[i - 1];
+ const b = tour[i];
+ const f = b.at > a.at ? (d - a.at) / (b.at - a.at) : 0;
+ out.set(a.x + (b.x - a.x) * f, 0, a.z + (b.z - a.z) * f);
+ return b.part;
+}
+
+/**
+ * When each part lands on the mat (gather-1): in the order they are
+ * soldered, one kind after another with a breath between the kinds โ the
+ * socket rows, the three connectors, the capacitor, the four encoders (each
+ * with its washer and nut a moment behind it) โ and the DevKit last, apart.
+ */
+const ARRIVE_BOARD = G1 + 0.24;
+const ARRIVE: Record = {
+ "U1_socket_pins1-22": G1 + 0.4,
+ "U1_socket_pins23-44": G1 + 0.43,
+ J1: G1 + 0.49,
+ J3: G1 + 0.52,
+ J4: G1 + 0.55,
+ C11: G1 + 0.61,
+ SW1: G1 + 0.67,
+ SW2: G1 + 0.7,
+ SW3: G1 + 0.73,
+ SW4: G1 + 0.76,
+};
+const ARRIVE_DEVKIT = G1 + 0.84;
+/** When what came besides the board's parts lands (gather-2): the panel, its ribbon and power lead, the screws, the USB cable, the power bank. */
+const ARRIVE2 = { panel: G2 + 0.16, ribbon: G2 + 0.25, power: G2 + 0.29, screws: G2 + 0.42, usb: G2 + 0.52, bank: G2 + 0.56, named: G2 + 0.76 };
+/** Pads no further apart than this (mm) are a row of pins: 2.54 mm, with a little to spare. */
+const ROW_PITCH = 3;
+
+/**
+ * A part's pads in the order the iron makes them. A header's or a socket's
+ * (rows of pins): down one row and back up the next, so the tip is drawn
+ * along a row and crosses once โ in pin order, a 2 ร 8 header's pins
+ * alternate between its rows, and the tip stitched back and forth sixteen
+ * times. Anything else: round the part by the nearest pad not yet made.
+ */
+function ironOrder(ref: string): { ref: string; p: (typeof PADS)[string][number] }[] {
+ const pads = PADS[ref].map((p) => ({ ref, p }));
+ if (pads.length >= 8) {
+ // Rows run down the board (z): pads within a millimetre across are one row.
+ const rows: (typeof pads)[] = [];
+ for (const pad of [...pads].sort((a, b) => a.p[0] - b.p[0])) {
+ const row = rows[rows.length - 1];
+ if (row && pad.p[0] - row[row.length - 1].p[0] < 0.001) row.push(pad);
+ else rows.push([pad]);
+ }
+ return rows.flatMap((row, n) => row.sort((a, b) => (n % 2 ? b.p[1] - a.p[1] : a.p[1] - b.p[1])));
+ }
+ const out = [pads[0]];
+ const left = pads.slice(1);
+ while (left.length) {
+ const from = out[out.length - 1].p;
+ let best = 0;
+ left.forEach((pad, i) => {
+ if (Math.hypot(pad.p[0] - from[0], pad.p[1] - from[1]) < Math.hypot(left[best].p[0] - from[0], left[best].p[1] - from[1])) best = i;
+ });
+ out.push(left.splice(best, 1)[0]);
+ }
+ return out;
+}
-/** How far apart (timeline) the parts land on the mat. */
-const ARRIVE0 = G1 + 0.3;
-const ARRIVE_STEP = 0.036;
+/** A board turned over in its holder: it leans back a few degrees, goes over, and is a few degrees past before it is level. */
+const turnOver = (x: number) => swing(x, 0.022, 0.018);
// โโ small maths โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
@@ -221,6 +372,10 @@ const qy = (a: number) => new THREE.Quaternion().setFromAxisAngle(V(0, 1, 0), a)
const KIT_PRESENTED: Pose = { p: DEVKIT_PRESENT.position, q: DEVKIT_PRESENT.quaternion };
/** Turned over about the board's long axis (z). */
const TURNED = new THREE.Quaternion().setFromAxisAngle(V(0, 0, 1), Math.PI);
+/** Upside down about x: a joint on the board's plain side. */
+const FLIPPED = qx(Math.PI);
+/** The way the iron is held: its tip on the joint, its handle up and toward the reader's right. */
+const IRON_AXIS = V(0.5, 1, 0.62).normalize();
function bezier(p0: THREE.Vector3, p1: THREE.Vector3, p2: THREE.Vector3, p3: THREE.Vector3, u: number, out: THREE.Vector3) {
const v = 1 - u;
@@ -232,26 +387,56 @@ function bezier(p0: THREE.Vector3, p1: THREE.Vector3, p2: THREE.Vector3, p3: THR
.addScaledVector(p3, u * u * u);
}
-/** Between two poses, lifted on an arc. */
-function arcPose(a: Pose, b: Pose, u: number, lift: number, out: Pose) {
- out.p.lerpVectors(a.p, b.p, u);
- out.p.y += lift * 4 * u * (1 - u);
- out.q.slerpQuaternions(a.q, b.q, smooth(u * 1.15 - 0.05));
+// A part carried from one place to another is picked up, taken across and put
+// down โ not slid along a parabola. `x` is how far through the move the
+// timeline is, straight (0โฆ1): the part comes up off where it lay before it
+// goes anywhere (its way across starts slowly, its rise at once), is turned
+// while it is in the air, and is over its place and level before it comes
+// down onto it. `lift` is how high it is carried.
+const carryUp = (x: number) => smooth(x / 0.36) * (1 - smooth((x - 0.6) / 0.4));
+const carryTurn = (x: number) => glide((x - 0.12) / 0.66);
+
+/** Between two poses, carried. */
+function carry(a: Pose, b: Pose, x: number, lift: number, out: Pose) {
+ const c = clamp01(x);
+ out.p.lerpVectors(a.p, b.p, glide(c));
+ out.p.y += lift * carryUp(c);
+ out.q.slerpQuaternions(a.q, b.q, carryTurn(c));
return out;
}
const tmpR = { ca: V(), cb: V(), c: V() };
-/** Between two rigid placements of a part whose centre (unplaced) is `c`: the centre travels, lifted on an arc; the turn is about it. */
-function arcRigid(c: THREE.Vector3, a: Rigid, b: Rigid, u: number, lift: number, out: Rigid) {
+/** Between two rigid placements of a part whose centre (unplaced) is `c`: the centre is carried; the turn is about it. */
+function carryRigid(c: THREE.Vector3, a: Rigid, b: Rigid, x: number, lift: number, out: Rigid) {
+ const u = clamp01(x);
tmpR.ca.copy(c).applyQuaternion(a.q).add(a.T);
tmpR.cb.copy(c).applyQuaternion(b.q).add(b.T);
- tmpR.c.lerpVectors(tmpR.ca, tmpR.cb, u);
- tmpR.c.y += lift * 4 * u * (1 - u);
- out.q.slerpQuaternions(a.q, b.q, smooth(u * 1.2 - 0.1));
+ tmpR.c.lerpVectors(tmpR.ca, tmpR.cb, glide(u));
+ tmpR.c.y += lift * carryUp(u);
+ out.q.slerpQuaternions(a.q, b.q, carryTurn(u));
out.T.copy(c).applyQuaternion(out.q).negate().add(tmpR.c);
return out;
}
+/** Between two poses through the air, on a low arc: for a part brought up to the reader, where there is nothing to put it down on. `u` is already eased. */
+function arc(a: Pose, b: Pose, u: number, lift: number, out: Pose) {
+ out.p.lerpVectors(a.p, b.p, u);
+ out.p.y += lift * Math.sin(Math.PI * clamp01(u));
+ out.q.slerpQuaternions(a.q, b.q, glide(u * 1.15 - 0.05));
+ return out;
+}
+
+const tmpTilt = { axis: V(), q: new THREE.Quaternion() };
+/**
+ * The lean a part has while it comes down, and the rock as it finds its feet:
+ * a turn of `angle` about a level axis โ a different one for each part
+ * (`i`), the same one every time.
+ */
+function tilt(i: number, angle: number) {
+ const a = scatter(i, 3) * Math.PI;
+ return tmpTilt.q.setFromAxisAngle(tmpTilt.axis.set(Math.cos(a), 0, Math.sin(a)), angle);
+}
+
/** A rigid placement that puts a part's centre `c` at `p`, turned by `q`. */
function placeCentre(c: THREE.Vector3, p: THREE.Vector3, q: THREE.Quaternion): Rigid {
return { q: q.clone(), T: c.clone().applyQuaternion(q).negate().add(p) };
@@ -262,11 +447,18 @@ function setRigid(o: THREE.Object3D, r: Rigid) {
o.position.copy(r.T);
}
-/** A part dropping onto the mat: how far through, as (height factor, scale). */
-function drop(t: number, t0: number, dur = 0.07) {
+/**
+ * A part arriving on the mat, `dur` of a beat from `t0`: let go a little
+ * above it, it comes down under its own weight, rebounds once (twice, the
+ * second barely) and is still. `fall` is its height as a share of the drop
+ * (1 โ 0, never below: it lands ON the mat), `scale` its size (it comes out
+ * of nothing, full size before it touches), `lean` what is left of the angle
+ * it comes down at (1 โ 0, a rock the other way after it touches). `heavy`
+ * things โ the panel, the power bank โ are let down instead: no rebound.
+ */
+function drop(t: number, t0: number, dur = 0.1, heavy = false) {
const u = clamp01((t - t0) / dur);
- // Down onto the mat and no lower (the landing ease runs past its end: without the floor, a part sank into the mat).
- return { fall: Math.max(0, 1 - settle(u)), scale: 0.35 + 0.65 * smooth(u * 1.6), on: t >= t0 };
+ return { fall: heavy ? setDown(u) : land(u), scale: grow(u), lean: heavy ? 1 - reach(u) : rock(u), on: t >= t0, u };
}
// โโ materials โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
@@ -338,6 +530,22 @@ const TAGS: { key: TagKey; text: TagText; side: TagSide; r: number }[] = [
{ key: "gBank", text: { en: "power bank", ko: "๋ณด์กฐ๋ฐฐํฐ๋ฆฌ" }, side: "up", r: 0 },
];
+// The parts under the hand (touch.ts) go by their line in the parts list
+// (build/bom.ts bomKey). These are the lines the stage names itself at some
+// point of the build, and with which of its tags: while one of them is up,
+// the hand does not put a second name beside it.
+const NAMED_BY: Partial> = {
+ "U1 (sockets)": ["u1"],
+ J1: ["j1"],
+ J3: ["j3"],
+ J4: ["j4"],
+ C11: ["c11"],
+ "LED matrix panel": ["gPanel"],
+ "M4 screw": ["gScrews"],
+ "USB cable (sacrificial)": ["gUsb"],
+ "USB power bank": ["gBank"],
+};
+
// โโ board-local feature points (pcb-v39.glb frame, metres) โโโโโโโโโโโโโโโโโ
const SW_CENTRES = ["SW1", "SW2", "SW3", "SW4"].map((ref) => {
@@ -355,12 +563,50 @@ const PLUS5_J3 = V(0.019752, 0.0017, 0.048993);
const USB_MARK = V(-0.00005, 0.0017, 0.053515);
const U1_MID = V(0, 0.009, 0.0255);
+// โโ the kit, made once โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+//
+// Everything the build adds to the stage is a pure function of the models
+// and is drawn on one canvas for the whole visit (world/GuideWorld), so it is
+// made once and kept here, outside the component: this stage comes and goes
+// with its guide, and making the kit again on every visit left the last
+// one's two hundred buffers, its vertex arrays and its textures on the GPU โ
+// React never disposes what is handed to it as a , and the canvas
+// that used to take them with it now outlives the page. A kit made for
+// another canvas (the guide was left altogether, and come back to) or other
+// models is let go before the next is made.
+
+type KitParts = { group: THREE.Object3D; joints: THREE.Object3D; ghost: THREE.Object3D };
+let kept: { key: unknown[]; kit: KitParts } | null = null;
+
+function disposeKit(kit: KitParts) {
+ const all = new Set<{ dispose: () => void }>();
+ for (const root of [kit.group, kit.joints, kit.ghost]) {
+ root.traverse((o) => {
+ const m = o as THREE.Mesh;
+ if (m.geometry) all.add(m.geometry);
+ for (const mat of Array.isArray(m.material) ? m.material : m.material ? [m.material] : []) {
+ all.add(mat);
+ for (const v of Object.values(mat)) if (v && (v as THREE.Texture).isTexture) all.add(v as THREE.Texture);
+ }
+ });
+ }
+ all.forEach((x) => x.dispose());
+}
+
+function keepKit(key: unknown[], make: () => T): T {
+ if (kept && kept.key.length === key.length && kept.key.every((k, i) => k === key[i])) return kept.kit as T;
+ if (kept) disposeKit(kept.kit);
+ const kit = make();
+ kept = { key, kit };
+ return kit;
+}
+
export default function BuildStage() {
const [splitGltf, platesGltf, caseGltf, ledGltf, pcbGltf] = useGLTF([SPLIT_URL, PLATES_URL, CASE_URL, MODEL_URL, PCB_URL], DRACO_URL);
const { scene: world, gl, camera, size } = useThree();
// โโ everything the build adds โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- const kit = useMemo(() => {
+ const kit = useMemo(() => keepKit([gl, splitGltf, platesGltf, caseGltf, ledGltf, pcbGltf], () => {
const group = new THREE.Group();
group.name = "build_stage";
const add = (o: T, parent: THREE.Object3D = group, shadow = true): T => {
@@ -374,12 +620,14 @@ export default function BuildStage() {
parent.add(o);
return o;
};
- const white = () => std("#eceae4", 0.55, 0, { transparent: true });
- const metal = std("#c3c6cc", 0.32, 0.85);
+ // What the stage's things are made of is look/materials.ts' โ the same
+ // printed PLA, turned steel and solder the Device has.
+ const white = () => plaMaterial({ extra: { transparent: true } });
+ const metal = screwMaterial();
// The encoders' washers and nuts: the brushed finish their bodies have
// (find(), below). Polished, the eight of them lying flat on the mat
// mirrored the key light straight into the bloom โ four white lamps.
- const brushed = std("#8d9096", 0.6, 0.7);
+ const brushed = steelMaterial();
const darkMetal = std("#5d6168", 0.4, 0.8);
// The bench mat, under everything that arrives.
@@ -413,9 +661,9 @@ export default function BuildStage() {
// board under it carries its parts and lettering as a texture.
const frameMat = std("#17171a", 0.46, 0, { transparent: true });
const headerMat = std("#1d1d20", 0.5, 0, { transparent: true });
- const pinMat = std("#c9a44a", 0.35, 0.85, { transparent: true });
+ const pinMat = goldMaterial({ transparent: true });
const canMat = std("#7f8389", 0.45, 0.6, { transparent: true });
- const brassMat = std("#8f7440", 0.55, 0.55, { transparent: true });
+ const brassMat = brassMaterial({ transparent: true });
const powerMat = std("#e6e1d6", 0.6, 0, { transparent: true });
const lSrc = ledGltf.scene.getObjectByName("l") as THREE.Mesh | undefined;
if (lSrc) {
@@ -439,9 +687,11 @@ export default function BuildStage() {
// Fasteners.
const screws = add(new THREE.InstancedMesh(props.screwGeometry(), metal, SCREW_HOLES.length));
+ // The cross in each head: what shows a screw turning.
+ const screwSlots = add(new THREE.InstancedMesh(props.screwRecessGeometry(), std("#17181b", 0.7, 0.4), SCREW_HOLES.length), group, false);
const washers = add(new THREE.InstancedMesh(props.washerGeometry(), brushed, 4));
const nuts = add(new THREE.InstancedMesh(props.nutGeometry(), brushed, 4));
- for (const m of [screws, washers, nuts]) {
+ for (const m of [screws, screwSlots, washers, nuts]) {
m.frustumCulled = false;
m.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
}
@@ -475,16 +725,19 @@ export default function BuildStage() {
// it sits in the case, so the group is at the origin when it is seated.
const idcMat = std("#b9b9b4", 0.62);
const ribbon = add(new THREE.Group());
- {
- const rz = (mouthZ: number) => mouthZ + props.IDC_PLUG.into - (props.IDC_PLUG.d - 0.12);
- const rg = props.foldedRibbon(J1_MOUTH.x, J1_MOUTH.y, rz(J1_MOUTH.z) - 0.045, PANEL_IN.x, PANEL_IN.y, rz(PANEL_IN.z) - 0.045);
- add(new THREE.Mesh(rg.cable, std("#b8b7b2", 0.7, 0, { side: THREE.DoubleSide })), ribbon);
- add(new THREE.Mesh(rg.stripe, std("#b3231d", 0.7, 0, { side: THREE.DoubleSide })), ribbon);
- const p0 = add(new THREE.Mesh(props.idcPlug("y"), idcMat), ribbon);
- p0.position.set(J1_MOUTH.x, J1_MOUTH.y, J1_MOUTH.z + props.IDC_PLUG.into);
- const p1 = add(new THREE.Mesh(props.idcPlug("x"), idcMat), ribbon);
- p1.position.set(PANEL_IN.x, PANEL_IN.y, PANEL_IN.z + props.IDC_PLUG.into);
+ const rz = (mouthZ: number) => mouthZ + props.IDC_PLUG.into - (props.IDC_PLUG.d - 0.12);
+ const ribbonFlex = props.foldedRibbon(J1_MOUTH.x, J1_MOUTH.y, rz(J1_MOUTH.z) - 0.045, PANEL_IN.x, PANEL_IN.y, rz(PANEL_IN.z) - 0.045);
+ for (const m of [new THREE.Mesh(ribbonFlex.cable, std("#b8b7b2", 0.7, 0, { side: THREE.DoubleSide })), new THREE.Mesh(ribbonFlex.stripe, std("#b3231d", 0.7, 0, { side: THREE.DoubleSide }))]) {
+ // It bends (the frame loop moves its strips): never culled by where it was built.
+ m.frustumCulled = false;
+ add(m, ribbon);
}
+ // Its two plugs, on its ends wherever they are: J1's, then IN's.
+ const ribbonPlugs = [
+ { mesh: add(new THREE.Mesh(props.idcPlug("y"), idcMat), ribbon), home: V(J1_MOUTH.x, J1_MOUTH.y, J1_MOUTH.z + props.IDC_PLUG.into) },
+ { mesh: add(new THREE.Mesh(props.idcPlug("x"), idcMat), ribbon), home: V(PANEL_IN.x, PANEL_IN.y, PANEL_IN.z + props.IDC_PLUG.into) },
+ ];
+ for (const rp of ribbonPlugs) rp.mesh.position.copy(rp.home);
// The panel's power lead: its plug on the panel's header, a red and a black wire to J3.
const powerPlug = add(new THREE.Mesh(props.vhPlug(), std("#e9e5da", 0.6)));
const powerPaths = [new Path(7), new Path(7)];
@@ -502,35 +755,63 @@ export default function BuildStage() {
pc2.position.set(0.22, 0, 0.16);
coils.power.position.copy(POWER_COIL);
- // Tools: the iron and its glint.
+ // A soft round glow for a point of heat: the print's nozzles.
+ const glowMap = props.glowTexture();
+ // Tools: the iron โ a plated tip, the heater's steel barrel, a rubber
+ // handle with its guard. Nothing glows where its tip touches: that was a
+ // flat disc of light lying on the board, a sprite and seen to be one.
+ // What says the tip is on a pad is the joint that grows under it.
const ig = props.iron();
const iron = add(new THREE.Group());
- add(new THREE.Mesh(ig.metal, std("#b5b9c0", 0.28, 0.9)), iron);
- add(new THREE.Mesh(ig.grip, std("#25272b", 0.75)), iron);
- const glint = new THREE.Sprite(
- new THREE.SpriteMaterial({ map: props.glowTexture(), color: new THREE.Color(2.4, 2.1, 1.7), transparent: true, depthWrite: false, toneMapped: false, blending: THREE.AdditiveBlending }),
- );
- group.add(glint);
+ add(new THREE.Mesh(ig.tip, metal), iron);
+ add(new THREE.Mesh(ig.barrel, brushed), iron);
+ add(new THREE.Mesh(ig.grip, std("#232528", 0.82)), iron);
// Solder joints: a small fillet at every through-hole pad (pads.ts),
// children of the board once it is found.
- const jointList: { pos: THREE.Vector3; up: boolean; r: number; at: number; ref: string }[] = [];
- for (const round of ROUNDS) {
- const pads = round.refs.flatMap((ref) => PADS[ref].map((p) => ({ ref, p })));
- pads.forEach(({ ref, p }, i) => {
+ type Joint = { pos: THREE.Vector3; up: boolean; r: number; at: number; ref: string; life: number; hold: number; hop: number };
+ const jointList: Joint[] = [];
+ const rounds = ROUNDS.map((round) => {
+ const secs = beatSeconds(Math.floor(round.from));
+ const pads = round.refs.flatMap((ref) => ironOrder(ref));
+ // The time from one joint to the next is the time on the pad plus the
+ // way to the next: quick along a row of pins, longer across the board.
+ const gaps = pads.map(({ p }, i) => (i ? Math.min(40, Math.hypot(p[0] - pads[i - 1].p[0], p[1] - pads[i - 1].p[1]) * 1000) : 0));
+ // A pin down a row is one beat of it; a move across the board is a
+ // short touch and then the way over, which is given its time โ the
+ // iron is carried, not thrown.
+ const dab = 0.6;
+ const way = (mm: number) => (mm <= ROW_PITCH ? 1 + mm * 0.2 : dab + mm * 0.45);
+ const cost: number[] = [];
+ gaps.forEach((mm, i) => cost.push(i ? cost[i - 1] + way(mm) : 0));
+ const total = Math.max(1e-6, cost[cost.length - 1]);
+ const list = pads.map(({ ref, p }, i) => {
const up = ref.startsWith("SW"); // encoders: joints on the F side
- jointList.push({
+ const j: Joint = {
ref,
up,
pos: V(p[0], up ? 0.0016 : 0, p[1]),
r: Math.min(0.0011, p[2] / 2 + 0.0001),
- at: round.from + ((round.to - round.from) * i) / Math.max(1, pads.length - 1),
- });
+ at: round.from + ((round.to - round.from) * cost[i]) / total,
+ // Half a second from bead to cold fillet, whatever the beat's length.
+ life: 0.5 / secs,
+ // On the pad before it for this share of the way here; lifted this
+ // high (model units) on the way. Down a row of pins (a pitch
+ // apart) it does neither: the tip is drawn along the row.
+ hold: gaps[i] <= ROW_PITCH ? 0 : dab / way(gaps[i]),
+ hop: gaps[i] <= ROW_PITCH ? 0 : Math.min(1.1, 0.03 + gaps[i] * 0.035),
+ };
+ jointList.push(j);
+ return j;
});
- }
+ return { from: round.from, to: round.to, secs, list };
+ });
const jointGeo = new THREE.ConeGeometry(1, 1, 14, 1, true);
jointGeo.translate(0, 0.5, 0);
- const joints = new THREE.InstancedMesh(jointGeo, std("#d9dce1", 0.22, 0.95), jointList.length);
+ const joints = new THREE.InstancedMesh(jointGeo, solderMaterial(), jointList.length);
+ // Each joint's own heat (look/materials.ts solderMaterial): 1 as it is made, 0 once it has set.
+ const jointHeat = new THREE.InstancedBufferAttribute(new Float32Array(jointList.length), 1).setUsage(THREE.DynamicDrawUsage);
+ jointGeo.setAttribute("aHeat", jointHeat);
joints.frustumCulled = false;
joints.castShadow = false;
joints.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
@@ -546,12 +827,41 @@ export default function BuildStage() {
// The print plates, the parts on them (plates.glb), a layer line each.
const plateMat = std("#45474d", 0.72, 0.15, { transparent: true });
+ // What they stand on. The floor of the room is black, and four dark
+ // plates on it were four squares hanging in the dark, in another and
+ // flatter world than the bench before them: a mat like the bench's, and
+ // on it the shade each plate keeps round its foot (drawn, not cast: the
+ // key light's shadow map is fitted to the device and does not reach the
+ // far plates).
+ const plateGround = add(new THREE.Group(), group, false);
+ plateGround.position.set(PLATES_GROUND.x, 0, PLATES_GROUND.z);
+ const plateGroundMat = std("#232b29", 0.96, 0, { transparent: true, opacity: 0 });
+ const groundSlab = add(new THREE.Mesh(props.mat(PLATES_GROUND.w, PLATES_GROUND.d), plateGroundMat), plateGround, false);
+ groundSlab.position.y = -0.05;
+ // One shade for each plate, and with its plate (the knobs' comes for the second print).
+ const plateShadeMat = new THREE.MeshBasicMaterial({
+ color: "#000000",
+ alphaMap: props.plateShade(PLATE_SHADE),
+ transparent: true,
+ opacity: 0,
+ depthWrite: false,
+ polygonOffset: true,
+ polygonOffsetFactor: -2,
+ polygonOffsetUnits: -8,
+ });
+ const plateShadeGeo = new THREE.PlaneGeometry(PLATE_SIZE + PLATE_SHADE * 2, PLATE_SIZE + PLATE_SHADE * 2);
+ plateShadeGeo.rotateX(-Math.PI / 2);
const clip = [1, 2, 3, 4].map(() => new THREE.Plane(V(0, -1, 0), 1e4));
const plates = [1, 2, 3, 4].map((p) => {
const g = add(new THREE.Group());
g.position.copy(plateCorner(p));
const slab = add(new THREE.Mesh(props.plate(), plateMat), g, false);
- const partMat = std(p === 4 ? "#161616" : "#eceae4", p === 4 ? 0.82 : 0.55, 0, { clippingPlanes: [clip[p - 1]], clipShadows: true });
+ // Its shade on the mat, just above the mat's top (the plate's corner is PLATE_TOP up).
+ const shade = new THREE.Mesh(plateShadeGeo, plateShadeMat);
+ shade.position.set(PLATE_SIZE / 2, -0.008 - plateCorner(p).y, -PLATE_SIZE / 2);
+ g.add(shade);
+ // Printed lying on the plate: its layers stack along the plate's up.
+ const partMat = plaMaterial({ axis: "y", ...(p === 4 ? { color: LOOK.plaBlack, roughness: 0.74 } : {}), extra: { clippingPlanes: [clip[p - 1]], clipShadows: true } });
// The layer being laid: where the cut opens a part, its inside is drawn
// in one flat tone โ a solid section, not the inside of a hollow shell.
// Drawn a little toward the camera in depth: a part's underside lies
@@ -578,7 +888,45 @@ export default function BuildStage() {
new THREE.LineBasicMaterial({ color: new THREE.Color("#ff8a4d").multiplyScalar(2.2), transparent: true, opacity: 0, toneMapped: false, depthWrite: false }),
);
g.add(line);
- return { group: g, slab, parts, cuts, line };
+ // The nozzle: a point of heat going round each part's outer wall at the
+ // layer being laid, with the bead it has just put down cooling behind
+ // it โ something laying the part, where the layer line only says how
+ // high it has got. One closed tour of the plate's parts: round each
+ // one's outline (props.ts footprint), and across to the next.
+ const tour: TourStop[] = [];
+ let length = 0;
+ // `part` is which part's wall the way TO this stop lays; โ1 for the way across to a part.
+ const stop = (x: number, z: number, part: number) => {
+ const last = tour[tour.length - 1];
+ if (last) length += Math.hypot(x - last.x, z - last.z);
+ tour.push({ x, z, at: length, part });
+ };
+ parts.forEach((part, n) => {
+ const outline = props.footprint(part.geometry);
+ outline.forEach(([x, z], i) => stop(x, z, i > 0 ? n : -1));
+ stop(outline[0][0], outline[0][1], n);
+ });
+ if (tour.length) stop(tour[0].x, tour[0].z, -1);
+ const nozzle = new THREE.Sprite(
+ new THREE.SpriteMaterial({ map: glowMap, color: new THREE.Color(2.6, 1.7, 0.9), transparent: true, opacity: 0, depthWrite: false, toneMapped: false, blending: THREE.AdditiveBlending }),
+ );
+ nozzle.scale.setScalar(0.7);
+ g.add(nozzle);
+ // In pieces, so that it stops where the nozzle lifted to cross to the next part.
+ const bead = new THREE.LineSegments(
+ new THREE.BufferGeometry().setAttribute("position", new THREE.BufferAttribute(new Float32Array(BEAD * 6), 3).setUsage(THREE.DynamicDrawUsage)),
+ new THREE.LineBasicMaterial({ vertexColors: true, transparent: true, depthWrite: false, toneMapped: false, blending: THREE.AdditiveBlending }),
+ );
+ const fade = new Float32Array(BEAD * 6);
+ for (let i = 0; i < BEAD * 2; i++) {
+ // Piece i runs from sample i to sample i + 1: hottest at the nozzle.
+ const k = Math.pow(1 - (Math.floor(i / 2) + (i % 2)) / BEAD, 1.6);
+ fade.set([2.2 * k, 1.1 * k, 0.4 * k], i * 3);
+ }
+ bead.geometry.setAttribute("color", new THREE.BufferAttribute(fade, 3));
+ bead.frustumCulled = false;
+ g.add(bead);
+ return { group: g, slab, parts, cuts, line, tour, length, nozzle, bead };
});
// The 256 mm print's halves where they sit in the case (case-split.glb).
@@ -593,15 +941,36 @@ export default function BuildStage() {
const slider = add(new THREE.Mesh(sliderSrc ? sliderSrc.geometry : new THREE.BufferGeometry(), white()));
// Bonding: tape across the seams, and a glow along them while they cure.
+ //
+ // The frame's seam (y 17.07) is only where the frame is: at that height
+ // its front is two openings โ the panel's and the power-bank tray's โ so
+ // the seam runs across the tray's back wall and down the case's two
+ // sides, and that is where the tape and the glow are. (They used to lie
+ // straight across the front: a line of light and two strips of tape in
+ // the air of the panel's opening.)
const tapeMat = std("#3b78d0", 0.9, 0, { transparent: true });
- const frameTape = [-8, 0, 8].map((x) => {
+ const SEAM_Y = 17.07;
+ const trayBack = TRAY.z0 + 0.02;
+ const side = 12.41;
+ const frameTape = [
+ { x: 6.3, z: trayBack, turn: 0 },
+ { x: 9.9, z: trayBack, turn: 0 },
+ { x: side, z: -0.2, turn: Math.PI / 2 },
+ ].map(({ x, z, turn }) => {
const m = add(new THREE.Mesh(props.tapeStrip(2.4), tapeMat), group, false);
- m.position.set(x, 17.07, FRONT_Z + 0.02);
+ m.position.set(x, SEAM_Y, z);
+ m.rotation.y = turn;
return m;
});
const seamMat = new THREE.MeshBasicMaterial({ color: new THREE.Color("#ff8a4d").multiplyScalar(2), transparent: true, opacity: 0, toneMapped: false, depthWrite: false });
- const frameSeam = add(new THREE.Mesh(new THREE.BoxGeometry(24.4, 0.06, 0.03), seamMat), group, false);
- frameSeam.position.set(-0.18, 17.07, FRONT_Z + 0.02);
+ const frameSeam = add(new THREE.Group(), group, false);
+ const seamAt = (w: number, d: number, x: number, z: number) => {
+ const m = add(new THREE.Mesh(new THREE.BoxGeometry(w, 0.06, d), seamMat), frameSeam, false);
+ m.position.set(x, SEAM_Y, z);
+ };
+ seamAt(TRAY.x1 - TRAY.x0, 0.03, (TRAY.x0 + TRAY.x1) / 2, trayBack);
+ seamAt(0.03, 3.4, side, -0.17);
+ seamAt(0.03, 3.4, -12.61, -0.17);
const backSeamGroup = add(new THREE.Group(), group, false);
const backSeam = add(new THREE.Mesh(new THREE.BoxGeometry(15.8, 0.06, 0.03), seamMat), backSeamGroup, false);
backSeam.position.set(-4.21, 17.03, -1.93);
@@ -616,6 +985,7 @@ export default function BuildStage() {
new THREE.BufferGeometry().setFromPoints([V(), V()]),
new THREE.LineDashedMaterial({ color: new THREE.Color("#ff6a3d").multiplyScalar(1.6), dashSize: 0.18, gapSize: 0.12, transparent: true, opacity: 0, toneMapped: false, depthWrite: false }),
);
+ dash.geometry.setAttribute("lineDistance", new THREE.BufferAttribute(new Float32Array(2), 1).setUsage(THREE.DynamicDrawUsage));
group.add(dash);
return {
@@ -625,6 +995,7 @@ export default function BuildStage() {
panel,
backGroup,
screws,
+ screwSlots,
washers,
nuts,
bank,
@@ -635,17 +1006,23 @@ export default function BuildStage() {
j4Paths,
j4Wires,
ribbon,
+ ribbonFlex,
+ ribbonPlugs,
powerPlug,
powerPaths,
powerWires,
coils,
iron,
- glint,
jointList,
+ rounds,
joints,
+ jointHeat,
ghost,
ghostMat,
plates,
+ plateGround,
+ plateGroundMat,
+ plateShadeMat,
clip,
split,
slider,
@@ -656,8 +1033,10 @@ export default function BuildStage() {
seamMat,
tapeMat,
dash,
+ // Its shaders have all been built and drawn once (warmStep): a kit that is kept does not do it again.
+ warm: { done: false },
};
- }, [splitGltf, platesGltf, caseGltf, ledGltf, pcbGltf]);
+ }), [gl, splitGltf, platesGltf, caseGltf, ledGltf, pcbGltf]);
// Centres of the case parts (unplaced), for turning them about themselves.
const centres = useMemo(() => {
@@ -715,6 +1094,17 @@ export default function BuildStage() {
};
}, [centres]);
+ // The parts under the hand (touch.ts; set up further down, with the tags).
+ const touch = useMemo(() => makeTouch(), []);
+ const touchFrame = useMemo(
+ () => ({
+ t: 0,
+ on: false,
+ occluders: [] as { mesh: THREE.Object3D; key?: string }[],
+ }),
+ [],
+ );
+
// โโ Device's objects, found once they are in the scene โโโโโโโโโโโโโโโโโโโ
type DeviceRig = {
root: THREE.Object3D;
@@ -782,15 +1172,28 @@ export default function BuildStage() {
root.add(node);
node.scale.setScalar(PCB_PLACEMENT.scale);
}
+ // Device's case and knobs fade here (with the opening; while they wait
+ // beside the case). The flag alone is not enough: three keeps the shader
+ // it built for an opaque material โ which writes alpha 1 whatever the
+ // opacity says โ until the material says it has changed, and the case
+ // never faded at all: it stood solid for the length of the fade and was
+ // then switched off. The see-through variant is the one the stage's own
+ // printed parts use (white(), in the kit), built and drawn in the
+ // warm-up, so this costs a look-up, not a compile.
+ const seeThrough = (mat: THREE.Material) => {
+ if (mat.transparent) return;
+ mat.transparent = true;
+ mat.needsUpdate = true;
+ };
const fade: THREE.Material[] = [];
for (const m of [body, backPlate, topLid]) {
const mat = m.material as THREE.MeshStandardMaterial;
- mat.transparent = true;
+ seeThrough(mat);
fade.push(mat);
}
const knobMats = knobs.map((k) => {
const mat = k.material as THREE.MeshStandardMaterial;
- mat.transparent = true;
+ seeThrough(mat);
return mat;
});
// The encoders' simplified metal reads as a mirror under the bench
@@ -819,7 +1222,8 @@ export default function BuildStage() {
deviceSlider,
notch: root.getObjectByName("notch_floor") ?? null,
knobs,
- knobHome: knobs.map((k) => (k.userData.buildHome ??= { p: k.position.clone(), q: k.quaternion.clone() }) as { p: THREE.Vector3; q: THREE.Quaternion }),
+ // (Device's own home for it โ userData.home โ not where it is now: the device may be standing apart, its knobs out in front.)
+ knobHome: knobs.map((k) => (k.userData.buildHome ??= { p: ((k.userData.home as THREE.Vector3 | undefined) ?? k.position).clone(), q: k.quaternion.clone() }) as { p: THREE.Vector3; q: THREE.Quaternion }),
led,
kit: kitPivot,
dials,
@@ -835,6 +1239,9 @@ export default function BuildStage() {
() => () => {
const d = dev.current;
dev.current = null;
+ // Nothing is left lifted or named by the hand.
+ touch.release();
+ touch.set([]);
if (!d) return;
for (const name of PART_ORDER) {
const p = d.parts[name];
@@ -862,35 +1269,44 @@ export default function BuildStage() {
d.kit.scale.setScalar(100);
d.dials.forEach((g) => g.scale.setScalar(1));
},
- [kit],
+ [kit, touch],
);
// Clipping for the print, on this canvas only (the build page's).
useEffect(() => {
const prev = gl.localClippingEnabled;
gl.localClippingEnabled = true;
+ // A context the GPU took away and gave back has none of the kit's shaders: they are built again before the next takeover.
+ const canvas = gl.domElement;
+ const restored = () => {
+ kit.warm.done = false;
+ };
+ canvas.addEventListener("webglcontextrestored", restored);
return () => {
gl.localClippingEnabled = prev;
+ canvas.removeEventListener("webglcontextrestored", restored);
};
- }, [gl]);
+ }, [gl, kit]);
// The timeline is not running once this is gone (timing.ts buildClock).
useEffect(
() => () => {
buildClock.t = -1;
+ buildFocus.on = false;
+ settleIn(null, 0);
},
[],
);
// โโ tags: DOM pills beside what they name โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
const tagEls = useRef>>({});
+ // The page's language: the stage outlives a page, so it is read from the store, not from the DOM round the canvas.
+ const lang: TagLang = useGuideStore((st) => st.lang);
useEffect(() => {
const host = gl.domElement.parentElement;
if (!host) return;
const layer = document.createElement("div");
layer.style.cssText = "position:absolute;inset:0;pointer-events:none;overflow:hidden;z-index:20";
- // The page's language (GuideExperience puts it on the guide's root).
- const lang: TagLang = host.closest("[lang]")?.getAttribute("lang") === "ko" ? "ko" : "en";
for (const t of TAGS) {
const wrap = document.createElement("div");
wrap.style.cssText = "position:absolute;left:0;top:0;will-change:transform";
@@ -904,15 +1320,146 @@ export default function BuildStage() {
tagEls.current[t.key] = { wrap, pill };
}
host.appendChild(layer);
+ // โฆand the one the hand brings up, for the part under it (touch.ts).
+ touch.mount(layer);
return () => {
+ touch.unmount();
layer.remove();
tagEls.current = {};
};
- }, [gl]);
+ }, [gl, lang, touch]);
+
+ // โโ shaders before it takes over โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+ //
+ // three builds a material's shader the first time it draws it, and this
+ // stage brings some forty materials with it. Drawn for the first time all
+ // at once โ the frame it takes the device over, and the warm-up draw after
+ // it โ that was two frames of a quarter of a second each. So before it
+ // starts: first every material is compiled in the background, where the
+ // browser can (compileAsync, parallel shader compile โ nothing waits on
+ // it); then each piece the build adds is drawn once on its own, off
+ // screen, one piece a frame, for what compiling alone misses (the clipping
+ // planes' variant of a shader, the shadow pass's) โ a few slow frames
+ // instead of two frozen ones. Returns true once all of it has been drawn.
+ const warm = useRef<{ i: number; target: THREE.WebGLRenderTarget | null; compiled: "no" | "busy" | "yes"; cam: THREE.Vector3; seen: boolean }>({
+ i: 0,
+ target: null,
+ compiled: "no",
+ // Where the camera was last frame, for how fast it is moving (the gate at the top of the frame loop).
+ cam: new THREE.Vector3(),
+ seen: false,
+ });
+ const warmUnits = useMemo(() => {
+ // The print plates bring the clipped shaders โ a part's, its cut's, and
+ // the shadow pass's for both โ and one plate drawn whole was the one long
+ // frame left: its pieces go one at a time, ahead of the plates themselves.
+ const plate = kit.plates[0];
+ const platePieces: THREE.Object3D[] = [plate.slab, plate.parts[0], plate.cuts[0], plate.line].filter(Boolean);
+ return [...platePieces, ...kit.group.children, kit.joints, kit.ghost];
+ }, [kit]);
+ useEffect(
+ () => () => {
+ warm.current.target?.dispose();
+ warm.current.target = null;
+ },
+ [],
+ );
+ const warmStep = (renderer: THREE.WebGLRenderer, scene: THREE.Scene, cam: THREE.Camera): boolean => {
+ if (kit.warm.done) return true;
+ const w = warm.current;
+ if (w.compiled !== "yes") {
+ if (w.compiled === "no") {
+ w.compiled = "busy";
+ const done = () => {
+ w.compiled = "yes";
+ };
+ // For the buffer the frame is really drawn into (the effects
+ // composer's: its linear colour space is part of the shader), and
+ // with the loose pieces in the tree for the moment it is walked.
+ const loosePieces = warmUnits.filter((u) => !u.parent);
+ for (const u of loosePieces) kit.group.add(u);
+ w.target ??= new THREE.WebGLRenderTarget(1, 1, { type: THREE.HalfFloatType });
+ const before = renderer.getRenderTarget();
+ const planes = renderer.clippingPlanes;
+ try {
+ renderer.setRenderTarget(w.target);
+ const jobs: Promise[] = [renderer.compileAsync(kit.group, cam, scene)];
+ // The print's parts are cut by a clipping plane, and a cut material
+ // is a shader of its own โ which compile() does not make: it builds
+ // for as many planes as the renderer last drew with, and that is
+ // none. So that one was built where it could not be put off, on
+ // the piece's first draw: the one long frame (130โ270 ms) left in
+ // the whole way from the hub into Build. Here the renderer is left
+ // counting one plane โ an empty scene, drawn with one that cuts
+ // nothing โ and the cut materials are compiled again, for that
+ // count, in the background with the rest.
+ renderer.clippingPlanes = [UNCUT];
+ renderer.render(NOTHING, cam);
+ const plate = kit.plates[0];
+ for (const cut of [plate.parts[0], plate.cuts[0], kit.plates[3].parts[0]]) if (cut) jobs.push(renderer.compileAsync(cut, cam, scene));
+ Promise.all(jobs).then(done, done);
+ } catch {
+ done();
+ } finally {
+ renderer.clippingPlanes = planes;
+ renderer.setRenderTarget(before);
+ for (const u of loosePieces) kit.group.remove(u);
+ }
+ }
+ return false;
+ }
+ const unit = warmUnits[w.i];
+ if (!unit) {
+ w.target?.dispose();
+ w.target = null;
+ kit.warm.done = true;
+ return true;
+ }
+ w.i++;
+ // The solder joints and the wrong-side encoder hang on the board once it is found; until then they are loose.
+ const loose = !unit.parent;
+ if (loose) kit.group.add(unit);
+ // Only this piece, wherever in the build's tree it hangs: everything
+ // off, then the piece and the way down to it on.
+ const saved: [THREE.Object3D, boolean, boolean][] = [];
+ kit.group.traverse((o) => {
+ saved.push([o, o.visible, o.frustumCulled]);
+ o.visible = false;
+ });
+ unit.traverse((o) => {
+ o.visible = true;
+ o.frustumCulled = false;
+ });
+ for (let up = unit.parent; up && up !== kit.group; up = up.parent) up.visible = true;
+ kit.group.visible = true;
+ w.target ??= new THREE.WebGLRenderTarget(1, 1, { type: THREE.HalfFloatType });
+ const prev = renderer.getRenderTarget();
+ const t0 = performance.now();
+ try {
+ renderer.setRenderTarget(w.target);
+ renderer.render(scene, cam);
+ if (process.env.NODE_ENV !== "production") {
+ // For measuring (scratchpad craft/world/hitch.py): what each piece's first draw cost.
+ const log = ((window as unknown as { __pfWarm?: { piece: number; kind: string; ms: number }[] }).__pfWarm ??= []);
+ log.push({ piece: w.i - 1, kind: unit.type + (unit.name ? ":" + unit.name : ""), ms: Math.round(performance.now() - t0) });
+ }
+ } catch {
+ // Nothing lost: the shader builds on first use instead.
+ } finally {
+ renderer.setRenderTarget(prev);
+ for (const [o, vis, culled] of saved) {
+ o.visible = vis;
+ o.frustumCulled = culled;
+ }
+ kit.group.visible = false;
+ if (loose) kit.group.remove(unit);
+ }
+ return false;
+ };
// Frames since mount, for the one-off warm-up draw below.
const warmed = useRef(0);
- const clock = useRef({ beat: -1, start: 0, t: -1, mounted: 0, replay: useGuideStore.getState().replay, heldOff: false });
+ const clock = useRef({ beat: -1, start: 0, since: 0, t: -1, mounted: 0, replay: useGuideStore.getState().replay, heldOff: false, cutAt: 0, shown: NaN });
const tmp = useMemo(
() => ({
a: pose(),
@@ -930,16 +1477,121 @@ export default function BuildStage() {
m: new THREE.Matrix4(),
s: V(1, 1, 1),
world: V(),
+ open: V(),
+ plugShown: V(1e9, 0, 0),
tags: new Map(),
jacket: V(),
}),
[],
);
+ // โโ the parts under the hand (touch.ts) โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+ //
+ // Which of the stage's objects is which line of the parts list, and how
+ // each comes out of its seat. Laid over the build once it has the device's
+ // objects; the frame loop's last act is to hand it the frame.
+ const touchParts = (d: DeviceRig): TouchPart[] => {
+ const board = (key: TouchKey, name: PartName): TouchPart => {
+ const part = d.parts[name];
+ const q = new THREE.Quaternion();
+ // Out of its holes: off the face it sits on (the encoders', the plain one), wherever the board is โ or, in the row, would be.
+ const out = name.startsWith("SW") ? -1 : 1;
+ return { key, object: part.node, full: PCB_PLACEMENT.scale, axis: (v) => v.set(0, out, 0).applyQuaternion(q.copy(part.hq).invert().premultiply(part.node.quaternion)) };
+ };
+ // The screws, lying in their row on the mat (the frame loop's `bench` pose): one box for the dozen.
+ const row = new THREE.Box3(V(SCREW_BENCH_X0 - 0.45, MAT_TOP, SCREW_BENCH_Z - 0.9), V(SCREW_BENCH_X0 + (SCREW_HOLES.length - 1) * SCREW_BENCH_DX + 0.45, MAT_TOP + 0.8, SCREW_BENCH_Z + 0.9));
+ return [
+ { key: "U1", object: d.kit, body: d.kit.children[0], full: 100 },
+ board("U1 (sockets)", "U1_socket_pins1-22"),
+ board("U1 (sockets)", "U1_socket_pins23-44"),
+ board("SW1-SW4", "SW1"),
+ board("SW1-SW4", "SW2"),
+ board("SW1-SW4", "SW3"),
+ board("SW1-SW4", "SW4"),
+ board("J1", "J1"),
+ board("J3", "J3"),
+ board("J4", "J4"),
+ board("C11", "C11"),
+ { key: "LED matrix panel", object: kit.panel.group },
+ { key: "M4 screw", object: kit.screws, box: row, owned: [kit.screwSlots] },
+ { key: "USB cable (sacrificial)", object: kit.coils.usb },
+ { key: "USB power bank", object: kit.bank },
+ ];
+ };
+ // On the mat, and not yet picked up for its step (the frame loop's own landmarks).
+ const touchLive = (key: string) => {
+ const t = touchFrame.t;
+ switch (key) {
+ case "U1":
+ return t >= ARRIVE_DEVKIT && t < F1;
+ case "LED matrix panel":
+ return t >= ARRIVE2.panel && t < C1;
+ case "M4 screw":
+ return t >= ARRIVE2.screws + 0.22 && t < C2 + 0.1;
+ case "USB cable (sacrificial)":
+ return t >= ARRIVE2.usb && t < C3;
+ case "USB power bank":
+ return t >= ARRIVE2.bank && t < F3;
+ default:
+ return true;
+ }
+ };
+ const touchNamed = (key: string) => NAMED_BY[key as TouchKey]?.some((k) => tmp.tags.has(k)) ?? false;
+ // What can stand between the eye and a part: the case and its covers, the panel, the bare board.
+ const touchOccluders = (d: DeviceRig) => {
+ const list: { mesh: THREE.Object3D; key?: string }[] = [d.body, d.backPlate, d.topLid, d.deviceSlider, d.led, kit.slider, ...Object.values(kit.split)].map((mesh) => ({ mesh }));
+ kit.panel.group.traverse((o) => {
+ if ((o as THREE.Mesh).isMesh) list.push({ mesh: o, key: "LED matrix panel" });
+ });
+ d.pcb.traverse((o) => {
+ if ((o as THREE.Mesh).isMesh && o !== kit.joints && o.parent !== kit.ghost) list.push({ mesh: o });
+ });
+ return list;
+ };
+
useFrame((state, rawDt) => {
- if (!dev.current) dev.current = find();
+ const onPage = useGuideStore.getState().page === "build";
+ if (!dev.current) {
+ // Nothing of the build is on stage until it takes the device over.
+ kit.group.visible = false;
+ if (!onPage) {
+ // Standby on the hub: the shaders, while the device hangs apart and
+ // still. Anywhere else it has no business โ off the guide before it
+ // ever drew, with nothing to hand back.
+ if (useGuideStore.getState().page !== "hub") useGuideStore.getState().setBuildLive(false);
+ else if (explodeState.amount === 1) warmStep(state.gl, state.scene, state.camera);
+ return;
+ }
+ // On the guide: the device is taken over as it stands, apart or whole.
+ // First what is left of the shaders โ unless the reader is already
+ // scrolling into the guide, then it starts at once โ and those only
+ // while the stage is still: the parts neither on their way out nor in,
+ // the camera arrived (a slow frame in the middle of its move from the
+ // hub is the stutter this is here to keep off the screen).
+ if (useGuideStore.getState().scene === "opening") {
+ const w = warm.current;
+ const speed = w.seen ? state.camera.position.distanceTo(w.cam) / Math.max(rawDt, 1e-3) : Infinity;
+ w.cam.copy(state.camera.position);
+ w.seen = true;
+ const still = speed < WARM_STILL && (explodeState.amount === 0 || explodeState.amount === 1);
+ if (!kit.warm.done && !still) return;
+ if (!warmStep(state.gl, state.scene, state.camera)) return;
+ }
+ dev.current = find();
+ if (dev.current) {
+ touch.set(touchParts(dev.current));
+ touchFrame.occluders = touchOccluders(dev.current);
+ }
+ }
const d = dev.current;
if (!d) return;
+ kit.group.visible = true;
+ // Where Device has its own back cover and the DevKit this frame (it ran
+ // just before this; the cover's place is overwritten further down).
+ const deviceWhole =
+ d.deviceSlider.position.lengthSq() < 1e-8 &&
+ Math.abs(d.deviceSlider.quaternion.w) > 0.99999 &&
+ d.kit.position.distanceToSquared(DEVKIT_SEAT.position) < 1e-6;
if (warmed.current < 3 && ++warmed.current === 2) {
// Draw everything the build adds once, off screen, before it is
// needed: compiling alone misses the clipping planes' variant of a
@@ -982,17 +1634,26 @@ export default function BuildStage() {
const now = performance.now();
const c = clock.current;
if (!c.mounted) c.mounted = now;
+ // The guide has been left: to the nearer end at which the device is whole.
+ if (!onPage) B = c.t >= WHOLE_AGAIN / 2 ? BEATS.length - 1 : 0;
if (B !== c.beat) {
// Forward, a step plays its own motion; back, it shows how it ends.
c.start = c.beat >= 0 && B < c.beat ? now - beatSeconds(B) * 1000 : now;
c.beat = B;
+ c.since = now;
}
// A step plays for its card. A chapter's first step is the current one
// from the chapter's title on, a screen and more before its card: until
// the card is on screen (store.ts cardIn) the beat waits at its start โ
// the build as the last chapter left it โ and plays when the reader gets
// there. Scrolling back up to the title winds it back, to play again.
- if (!cardIn) c.start = now;
+ //
+ // One thing does not wait for a card: the opening's device. It goes as
+ // the opening is left โ the first sixth of gather-1, the case fading and
+ // the mat coming up โ under the first chapter's title, while the camera
+ // comes down to the bench. Held for the card, it hung in the top of the
+ // bench's frame for as long as the title took to pass.
+ if (!cardIn && onPage) c.start = now - (B === beatIndex("gather-1") ? Math.min(now - c.since, (OPENING_GONE - G1) * beatSeconds(B) * 1000) : 0);
// "Replay" on the card: this step's motion again, from its start.
if (replay !== c.replay) {
c.replay = replay;
@@ -1000,9 +1661,29 @@ export default function BuildStage() {
c.t = B;
}
const reduced = typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
- const target = B + Math.min(0.999, (now - c.start) / 1000 / beatSeconds(B));
- if (c.t < 0 || now - c.mounted < 700) c.t = target;
- else if (reduced) c.t = B + (cardIn ? beatStill(B) : 0);
+ // On the guide, the step's own motion; off it, the end the build is being run to.
+ const target = onPage ? B + Math.min(0.999, (now - c.start) / 1000 / beatSeconds(B)) : B === 0 ? 0 : B + 0.999;
+ // It takes over a whole device: until told otherwise, the build stands at its opening.
+ if (c.t < 0) c.t = Math.min(target, 0.5);
+ const arriving = now - c.mounted < 700;
+ const far = (arriving || !onPage) && Math.abs(target - c.t) > CUT_FAR;
+ if (!far) c.cutAt = 0;
+ if (far) {
+ // Too much of the build lies between what is on stage and where it
+ // must be โ the guide opened on a step in its middle (a link, Back,
+ // Forward), or left from one โ to run through in view: a cut, made in
+ // the dark. The world dips the canvas (store.requestCut โ
+ // Guide.module.css [data-cut]); the timeline jumps once it is out.
+ if (!c.cutAt) {
+ c.cutAt = now;
+ useGuideStore.getState().requestCut();
+ }
+ if (now - c.cutAt >= CUT_DARK_MS) {
+ c.t = target;
+ c.cutAt = 0;
+ }
+ } else if (arriving && onPage) c.t = target;
+ else if (reduced) c.t = onPage ? B + (cardIn ? beatStill(B) : 0) : target;
else {
const dlt = target - c.t;
// Its own pace forward within the beat; quick from another beat, and
@@ -1021,53 +1702,95 @@ export default function BuildStage() {
w.__pfBuild ??= { kit, dev: d, THREE };
}
const t = c.t;
+ // The timeline has not moved since the last frame โ a step holding its
+ // end, which is most of the time a reader spends on it: the cables, each
+ // a tube rebuilt from a curve, are as they were, and are left alone.
+ const tStill = t === c.shown;
+ c.shown = t;
// For the camera and the scripted demos (timing.ts).
buildClock.t = t;
+ // The camera is still coming in while the step's motion plays, and is in
+ // its frame as it ends (views.ts settleIn) โ on the guide, on this step,
+ // and not for a reader who has asked for less motion.
+ {
+ const late = narrow && s.narrowLate && t - B >= s.narrowLate.from ? s.narrowLate.view : null;
+ const viewName = late ?? ((narrow && s.narrowView) || s.view);
+ const through = Math.floor(t) === B ? t - B : t > B ? 1 : 0;
+ settleIn(onPage && !reduced ? viewName : null, 1 - glide(through / 0.9), Math.min(1, beatSeconds(B) / 4), through);
+ }
+ // Left, the build at an end, and Device's own parts home: this frame
+ // draws the whole device, and is the last (see the end of the frame).
+ const handBack = !onPage && (t < G1 || t >= WHOLE_AGAIN) && deviceWhole;
const finished = t < G1; // the opening: the device as it will end up
+ // What this frame is about, for whoever wants to know (focus.ts): set by the parts below that are.
+ buildFocus.on = false;
const caseFade = finished ? 1 : 1 - span(t, G1, G1 + 0.16);
+ // The opening's device may be standing apart (stage/Explode: the hub's
+ // answer to Build, kept through Build's opening): how far, 0 whole โฆ 1,
+ // and each part's way out by it. Everything this stage places at its
+ // opening it places by this, until that device has faded (OPENING_GONE).
+ const apart = t < OPENING_GONE ? explodeState.amount : 0;
+ const open = (part: ExplodePart) => partOffset(part, apart, tmp.open) as THREE.Vector3;
+ // Apart, the board and the DevKit are out in the open, and cannot simply
+ // stop being there when the bench comes up (whole, they are inside the
+ // case and nobody sees them go): they are drawn in to nothing where they
+ // hang, as the case fades round them.
+ const going = apart > 0 && !finished;
+ const gone = going ? 1 - span(t, G1, G1 + 0.15, ease) : 1;
+ // What is inside the closed case and is not Device's โ the screws, the
+ // nuts, the cables, the power bank: the hub's device has none of them,
+ // so apart they are not drawn. The case is shut again before the amount
+ // is back at 0, so they are never seen to come or go.
+ const shut = !(finished && apart > 0);
// โโ the board โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
const bp = tmp.board;
let boardScale = 1;
let boardOn = true;
if (t < G1) {
- bp.p.copy(BOARD_IN_CASE.p);
+ bp.p.copy(BOARD_IN_CASE.p).add(open("board"));
bp.q.copy(BOARD_IN_CASE.q);
- } else if (t < G1 + 0.12) {
- boardOn = false;
+ } else if (t < ARRIVE_BOARD) {
+ if (going && gone > 0.002) {
+ bp.p.copy(BOARD_IN_CASE.p).add(open("board"));
+ bp.q.copy(BOARD_IN_CASE.q);
+ boardScale = gone;
+ } else boardOn = false;
} else if (t < P1) {
- const dr = drop(t, G1 + 0.12, 0.09);
+ const dr = drop(t, ARRIVE_BOARD, 0.13);
bp.p.copy(BOARD_FLAT.p).setY(BOARD_FLAT.p.y + dr.fall * 4);
- bp.q.copy(BOARD_FLAT.q);
+ bp.q.copy(tilt(40, 0.1 * dr.lean)).multiply(BOARD_FLAT.q);
boardScale = dr.scale;
} else if (t < S1) {
// Up off the mat, over once โ the PATTERNFLOW face, the plain face โ
// and held up to be read (print-1); off to the side while the case
// prints (print-2 on).
- if (t < P1 + 0.3) arcPose(BOARD_FLAT, BOARD_LIFT, span(t, P1, P1 + 0.3), 0.5, bp);
+ if (t < P1 + 0.3) carry(BOARD_FLAT, BOARD_LIFT, span(t, P1, P1 + 0.3, clamp01), 0.5, bp);
else if (t < P2) {
+ // Once over about its long axis: a lean back, round, a hair past and level.
bp.p.copy(BOARD_LIFT.p);
- bp.q.copy(BOARD_LIFT.q).multiply(tmp.q.setFromAxisAngle(V(0, 0, 1), Math.PI * 2 * span(t, P1 + 0.3, P1 + 0.8, smooth)));
- } else arcPose(BOARD_LIFT, BOARD_PARK, span(t, P2, P2 + 0.14), 2, bp);
+ bp.q.copy(BOARD_LIFT.q).multiply(tmp.q.setFromAxisAngle(V(0, 0, 1), Math.PI * 2 * span(t, P1 + 0.34, P1 + 0.86, (x) => swing(x, 0.012, 0.012))));
+ } else carry(BOARD_LIFT, BOARD_PARK, span(t, P2, P2 + 0.16, clamp01), 2, bp);
} else if (t < C3) {
- if (t < S1 + 0.22) arcPose(BOARD_PARK, BOARD_WORK, span(t, S1, S1 + 0.22), 4, bp);
+ if (t < S1 + 0.22) carry(BOARD_PARK, BOARD_WORK, span(t, S1 + 0.03, S1 + 0.22, clamp01), 4, bp);
else bp.p.copy(BOARD_WORK.p);
let flip = 0;
FLIPS.forEach(([a, b], i) => {
- flip += (i % 2 ? -1 : 1) * span(t, a, b);
+ flip += (i % 2 ? -1 : 1) * span(t, a, b, turnOver);
});
if (t >= S1 + 0.22) bp.q.copy(tmp.q.setFromAxisAngle(V(0, 0, 1), Math.PI * flip)).multiply(BOARD_WORK.q);
} else if (t < C4) {
// Round the case's right side to behind its bay, turning to face the
// back โ once the lead is through the case's cable hole and waiting
// there (BUILD_GUIDE ยง7.3: the cable goes through first).
- const u = span(t, BOARD_OVER[0], BOARD_OVER[1], smooth);
- bezier(BOARD_WORK.p, V(16, 10, 30), V(27, 22, -12), BOARD_HOVER.p, u, bp.p);
- bp.q.slerpQuaternions(BOARD_WORK.q, BOARD_HOVER.q, smooth((u - 0.12) / 0.7));
+ const u = span(t, BOARD_OVER[0], BOARD_OVER[1], glide);
+ bezier(BOARD_WORK.p, tmp.v.set(16, 10, 30), tmp.v2.set(27, 22, -12), BOARD_HOVER.p, u, bp.p);
+ bp.q.slerpQuaternions(BOARD_WORK.q, BOARD_HOVER.q, glide((u - 0.12) / 0.7));
} else {
- // Straight in, the encoder shafts through the front face.
- const u = span(t, C4, C4 + 0.55, smooth);
+ // Straight in: up to the bay, the four shafts found in their holes, and
+ // pushed home through the front face.
+ const u = span(t, C4 + 0.14, C4 + 0.7, (x) => press(x, 0.8));
bp.p.lerpVectors(BOARD_HOVER.p, BOARD_IN_CASE.p, u);
bp.q.copy(BOARD_IN_CASE.q);
}
@@ -1110,28 +1833,38 @@ export default function BuildStage() {
return out;
};
const [i0, i1] = INSERT[name];
- const arrive = ARRIVE0 + k * ARRIVE_STEP;
let scale = 1;
let on = true;
if (t < G1) onBoard(tmp.a);
- else if (t < i0) {
- const dr = drop(t, arrive);
+ else if (going && boardOn) {
+ // Still on the board, as the opening has it, and going with it: drawn in toward the board's middle.
+ onBoard(tmp.a);
+ tmp.a.p.sub(boardPose.p).multiplyScalar(gone).add(boardPose.p);
+ scale = gone;
+ } else if (t < i0) {
+ const dr = drop(t, ARRIVE[name]);
on = dr.on;
row(tmp.a);
tmp.a.p.y += dr.fall * 3;
+ tmp.a.q.premultiply(tilt(k, 0.26 * dr.lean));
scale = dr.scale;
} else if (t < i1) {
- const u = span(t, i0, i1, clamp01);
+ // Picked out of the row and carried to just over its holes; then its
+ // pins found in them, and pushed down until its body is on the board.
+ const x = span(t, i0, i1, clamp01);
+ const over = 0.62;
row(tmp.b);
- if (u < 0.68) {
+ if (x < over) {
onBoard(tmp.c, 0.022);
- if (name === "C11") tmp.c.q.premultiply(tmp.q.setFromAxisAngle(V(0, 1, 0).applyQuaternion(boardPose.q), Math.PI * 2 * smooth(u / 0.68)));
- arcPose(tmp.b, tmp.c, smooth(u / 0.68), 3.5, tmp.a);
+ carry(tmp.b, tmp.c, x / over, 2.6, tmp.a);
+ // The capacitor is turned once round on its way โ its stripe and its
+ // long lead go by โ on top of the carry: as a pose for the carry to
+ // turn toward, a turn past half-way came back the short way, in one frame.
+ if (name === "C11") tmp.a.q.premultiply(tmp.q.setFromAxisAngle(tmp.v.set(0, 1, 0).applyQuaternion(boardPose.q), Math.PI * 2 * glide(x / over)));
} else {
onBoard(tmp.b, 0.022);
onBoard(tmp.c);
- const v = smooth((u - 0.68) / 0.32);
- tmp.a.p.lerpVectors(tmp.b.p, tmp.c.p, v);
+ tmp.a.p.lerpVectors(tmp.b.p, tmp.c.p, press((x - over) / (1 - over), 0.72));
tmp.a.q.copy(tmp.c.q);
}
} else onBoard(tmp.a);
@@ -1142,78 +1875,99 @@ export default function BuildStage() {
});
// โโ solder joints and the iron โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+ //
+ // The iron comes in along its own length to the round's first pad, and
+ // works through them: on a pad for a moment, over to the next โ a short
+ // slide along a row of pins, a real lift across the board โ and away
+ // again the way it came once the last is made. A joint starts when the
+ // iron reaches its pad: a bead of molten solder, which then wets โ it
+ // draws in to the pad and climbs the pin into a fillet โ and cools: liquid
+ // and mirror-bright under the tip, frosting over a joint or two behind
+ // the iron (look/materials.ts solderMaterial: its heat is in its
+ // surface, not in a glow).
let ironTip: THREE.Vector3 | null = null;
- let lastPop = -1;
{
const m = tmp.m;
+ const heat = kit.jointHeat.array as Float32Array;
kit.jointList.forEach((j, i) => {
- const pop = finished ? 1 : span(t, j.at, j.at + 0.012, smooth);
- if (!finished && t >= j.at && (lastPop < 0 || j.at > kit.jointList[lastPop].at)) lastPop = i;
- const r = j.r * pop;
- tmp.q.copy(j.up ? IDENTITY : qx(Math.PI));
- m.compose(j.pos, tmp.q, tmp.s.set(r, pop * 0.0011, r));
+ const age = finished ? 2 : (t - j.at) / j.life;
+ if (age <= 0) {
+ m.compose(j.pos, IDENTITY, tmp.s.setScalar(0));
+ kit.joints.setMatrixAt(i, m);
+ heat[i] = 0;
+ return;
+ }
+ const melt = ease(age / 0.22);
+ const wet = glide((age - 0.18) / 0.42);
+ const r = j.r * (1.5 * melt - 0.5 * wet);
+ const h = 0.0011 * (0.4 * melt + 0.6 * wet);
+ tmp.q.copy(j.up ? IDENTITY : FLIPPED);
+ m.compose(j.pos, tmp.q, tmp.s.set(r, h, r));
kit.joints.setMatrixAt(i, m);
+ heat[i] = 1 - glide((age - 0.1) / 0.9);
});
kit.joints.instanceMatrix.needsUpdate = true;
+ kit.jointHeat.needsUpdate = true;
kit.joints.visible = boardOn;
- // The iron walks the round of joints being made.
- for (const round of ROUNDS) {
- if (t < round.from - 0.035 || t > round.to + 0.035) continue;
- const list = kit.jointList.filter((j) => round.refs.includes(j.ref));
- const g = clamp01((t - round.from) / (round.to - round.from)) * (list.length - 1);
- const i = Math.min(list.length - 2, Math.floor(g));
- const f = g - i;
- const a = list[Math.max(0, i)];
+ for (const round of kit.rounds) {
+ const lead = 0.36 / round.secs;
+ const dwell = 0.12 / round.secs;
+ if (t < round.from - lead || t > round.to + dwell + lead) continue;
+ const list = round.list;
+ let i = 0;
+ while (i < list.length - 2 && t >= list[i + 1].at) i++;
+ const a = list[i];
const b = list[Math.min(list.length - 1, i + 1)];
- tmp.v.lerpVectors(a.pos, b.pos, smooth(f));
+ const f = clamp01((t - a.at) / Math.max(1e-6, b.at - a.at));
+ // On the pad for `hold` of the way to the next one, then over to it; along a row, straight on.
+ const go = b.hop === 0 ? f : glide((f - b.hold) / (1 - b.hold));
+ tmp.v.lerpVectors(a.pos, b.pos, go);
tmp.v.y = a.up ? 0.0028 : -0.0012;
ironTip = d.pcb.localToWorld(tmp.v2.copy(tmp.v));
kit.group.worldToLocal(ironTip);
- // Away between joints, in and out at either end.
- const away = Math.sin(Math.PI * f) * 0.12 + (1 - span(t, round.from - 0.035, round.from)) * 4 + span(t, round.to, round.to + 0.035) * 4;
- ironTip.addScaledVector(tmp.v3.set(0.5, 1, 0.62).normalize(), away);
+ // Lifted between pads by how far apart they are; in before the first, out after the last.
+ const hop = Math.sin(Math.PI * go) * b.hop;
+ const coming = 1 - span(t, round.from - lead, round.from, reach);
+ const leaving = span(t, round.to + dwell, round.to + dwell + lead, fall);
+ ironTip.addScaledVector(IRON_AXIS, hop + (coming + leaving) * 4.4);
}
}
kit.iron.visible = !!ironTip;
if (ironTip) {
kit.iron.position.copy(ironTip);
- kit.iron.quaternion.setFromUnitVectors(Y, tmp.v3.set(0.5, 1, 0.62).normalize());
- }
- {
- const j = lastPop >= 0 ? kit.jointList[lastPop] : null;
- const age = j ? t - j.at : 1;
- const glow = j && ironTip ? Math.max(0, 1 - age / 0.025) : 0;
- kit.glint.visible = glow > 0.01;
- if (j && glow > 0.01) {
- kit.glint.position.copy(d.pcb.localToWorld(tmp.v.copy(j.pos)));
- kit.group.worldToLocal(kit.glint.position);
- kit.glint.scale.setScalar(0.9 * glow + 0.2);
- (kit.glint.material as THREE.SpriteMaterial).opacity = glow;
- }
+ kit.iron.quaternion.setFromUnitVectors(Y, IRON_AXIS);
+ buildFocus.on = true;
+ buildFocus.size = 0.06;
+ buildFocus.world.copy(ironTip).multiplyScalar(MODEL_SCALE).add(MODEL_OFFSET);
}
// The encoder that went in from the wrong side (solder-4).
{
- const u = span(t, S4 + 0.02, S4 + 0.17);
- const fade = 1 - span(t, S4 + 0.19, S4 + 0.27);
- const on = t > S4 && t < S4 + 0.27;
+ const u = span(t, S4 + 0.02, S4 + 0.11, clamp01);
+ const fade = 1 - span(t, S4 + 0.15, S4 + 0.2);
+ const on = t > S4 && t < S4 + 0.2;
kit.ghost.visible = on;
kit.ghostMat.opacity = 0.5 * fade * Math.min(1, u * 4);
// Mirrored onto the F side, coming down onto SW1's place.
const c0 = SW_CENTRES[0];
- kit.ghost.position.set(0, 0.0016 + 0.028 * (1 - u), 0);
+ // It comes down onto the printed side, is refused โ a shake of the head โ and goes back up as it fades.
+ kit.ghost.position.set(0.0014 * shake((t - (S4 + 0.11)) / 0.05), 0.0016 + 0.028 * (1 - reach(u)) + 0.012 * (1 - fade), 0);
kit.ghost.scale.set(1, -1, 1);
void c0;
}
// โโ the holder โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
{
- const up = span(t, S1, S1 + 0.1) * (1 - span(t, BOARD_OVER[1], BOARD_OVER[1] + 0.1));
+ const up = span(t, S1, S1 + 0.1, ease) * (1 - span(t, BOARD_OVER[1], BOARD_OVER[1] + 0.1));
+ // The jaws stand open until the board is between them, close on its two
+ // short edges, and let go of it just before it is carried off.
+ const grip = span(t, S1 + 0.2, S1 + 0.26, ease) * (1 - span(t, BOARD_OVER[0] - 0.05, BOARD_OVER[0] - 0.01, ease));
kit.holder.group.visible = up > 0.001;
kit.holder.posts.forEach((p) => p.scale.set(1, 2.75 * up + 0.001, 1));
- kit.holder.jaws.forEach((j) => {
+ kit.holder.jaws.forEach((j, i) => {
j.visible = up > 0.98;
j.position.y = BOARD_WORK.p.y + 0.075;
+ j.position.z = HOLDER_Z[i] + (i === 0 ? -1 : 1) * (0.12 + 0.6 * (1 - grip));
});
}
@@ -1223,21 +1977,28 @@ export default function BuildStage() {
if (t < G1) {
// Device has it on its pins inside the closed case; back from the
// bench, it is not shown on its way there.
+ // (Apart, its pins are where Explode has put them: that far behind the board's sockets.)
+ kp.visible = true;
+ kp.scale.setScalar(kp.position.distanceToSquared(tmp.v.copy(DEVKIT_SEAT.position).add(open("devkit"))) < 1e-4 ? 100 : 1e-4);
+ } else if (going) {
+ // Hanging apart behind the board: it goes as the board does.
kp.visible = true;
- kp.scale.setScalar(kp.position.distanceToSquared(DEVKIT_SEAT.position) < 1e-4 ? 100 : 1e-4);
+ kp.position.copy(DEVKIT_SEAT.position).add(open("devkit"));
+ kp.quaternion.copy(DEVKIT_SEAT.quaternion);
+ kp.scale.setScalar(Math.max(1e-4, 100 * gone));
} else if (t < F1 + 0.45) {
// Not on the mat yet: shrunk away rather than hidden โ KitFx keeps a
// light on it, and a light going out changes every lit shader in the
// scene (a frozen frame while they all rebuild).
- const dr = drop(t, G1 + 0.68, 0.09);
+ const dr = drop(t, ARRIVE_DEVKIT, 0.13);
kp.visible = true;
if (t < F1) {
kp.position.copy(DEVKIT_BENCH.p).setY(DEVKIT_BENCH.p.y + dr.fall * 3);
- kp.quaternion.copy(DEVKIT_BENCH.q);
- kp.scale.setScalar(dr.on ? 100 * dr.scale : 1e-4);
+ kp.quaternion.copy(tilt(20, 0.16 * dr.lean)).multiply(DEVKIT_BENCH.q);
+ kp.scale.setScalar(dr.on ? Math.max(1e-4, 100 * dr.scale) : 1e-4);
} else {
// Up from the mat into the reader's hands (Device and KitFx take it from there).
- arcPose(DEVKIT_BENCH, KIT_PRESENTED, span(t, F1, F1 + 0.42), 6, tmp.a);
+ arc(DEVKIT_BENCH, KIT_PRESENTED, span(t, F1 + 0.02, F1 + 0.42, glide), 3, tmp.a);
const w = 1 - span(t, F1 + 0.36, F1 + 0.45);
// Blend into wherever Device has it, so handing over never jumps.
kp.position.lerp(tmp.a.p, w);
@@ -1251,7 +2012,24 @@ export default function BuildStage() {
}
// โโ the case โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- const swapAt = P4 + 0.62;
+ // When the bonded halves become the one-piece body (the same shape in the same place: nothing shows).
+ const swapAt = P4 + 0.72;
+ // The printed parts that wait for the end of the build โ the back, the
+ // two covers, the knobs โ lie beside the case from the moment they are
+ // bonded. They are put away with the bench (the mat goes at firmware-1)
+ // and are back as each is wanted: lying there through first light they
+ // were white slabs cut by the frame's left edge and running under the
+ // card, at the one moment the stage should hold nothing but the device
+ // and its light. (Device does the same with its own back cover, set down
+ // for Play's first chapter.)
+ const away = 1 - span(t, F1 + 0.55, F1 + 0.95);
+ const spare = {
+ back: t < K4 ? away : span(t, K4, K4 + 0.05),
+ // (The cover lies at the edge of check-4's frame: it is back as it is picked up, not before.)
+ slider: t < K4 + 0.66 ? away : span(t, K4 + 0.66, K4 + 0.74),
+ // The lid and the knobs: for the last step.
+ late: t < K5 ? away : span(t, K5, K5 + 0.08),
+ };
{
// Device's body: the finished device, then gone until the halves are bonded.
d.body.visible = finished ? true : t < G1 + 0.17 || t >= swapAt;
@@ -1262,69 +2040,90 @@ export default function BuildStage() {
// The back panel: bonded at rest, then hooked in and swung shut (check-4).
const bpMesh = d.backPlate;
+ bpMesh.castShadow = t < swapAt || spare.back > 0.5;
if (t < G1 + 0.17) {
bpMesh.visible = true;
setRigid(bpMesh, places.home);
+ bpMesh.position.add(open("backPlate"));
} else if (t < swapAt) bpMesh.visible = false;
else {
- bpMesh.visible = true;
+ // Lying beside the case until it is wanted โ and put away with the bench in between (`spare`, above).
+ (bpMesh.material as THREE.MeshStandardMaterial).opacity = spare.back;
+ bpMesh.visible = spare.back > 0.01;
if (t < K4) setRigid(bpMesh, places.backRest);
- else if (t < K4 + 0.32) setRigid(bpMesh, arcRigid(centres.back_plate, places.backRest, places.hingeAway, span(t, K4 + 0.1, K4 + 0.32), 6, tmp.r));
+ else if (t < K4 + 0.32) setRigid(bpMesh, carryRigid(centres.back_plate, places.backRest, places.hingeAway, span(t, K4 + 0.06, K4 + 0.32, clamp01), 6, tmp.r));
else if (t < K4 + 0.44) {
+ // Its outer edge brought up to the case's and hooked in.
tmp.r.q.copy(places.hingeOpen.q);
- tmp.r.T.lerpVectors(places.hingeAway.T, places.hingeOpen.T, span(t, K4 + 0.32, K4 + 0.43));
+ tmp.r.T.lerpVectors(places.hingeAway.T, places.hingeOpen.T, span(t, K4 + 0.32, K4 + 0.43, reach));
setRigid(bpMesh, tmp.r);
- }
- else {
- // Shut, and no further: an ease that overshoots swung the panel on through the ribbon.
- const u = span(t, K4 + 0.44, K4 + 0.62, smooth);
- const a = BACK_OPEN_ANGLE * (1 - u);
+ } else {
+ // Swung shut: it comes to rest on its catch, a couple of degrees
+ // open, and is pressed home โ the click. Shut and no further: an
+ // ease that overshoots swung the panel on through the ribbon.
+ const a = BACK_OPEN_ANGLE * latch(span(t, K4 + 0.45, K4 + 0.67, clamp01));
tmp.r.q.setFromAxisAngle(Y, a);
tmp.r.T.copy(BACK_HINGE).sub(tmp.v.copy(BACK_HINGE).applyQuaternion(tmp.r.q));
setRigid(bpMesh, tmp.r);
}
+ if (t >= K4 + 0.06 && t < K4 + 0.68) {
+ buildFocus.on = true;
+ buildFocus.size = 2.4;
+ buildFocus.world.copy(centres.back_plate).applyQuaternion(bpMesh.quaternion).add(bpMesh.position).multiplyScalar(MODEL_SCALE).add(MODEL_OFFSET);
+ }
}
- if (d.notch) d.notch.visible = finished || t >= K4 + 0.58;
+ if (d.notch) d.notch.visible = finished || t >= K4 + 0.655;
// The PCB cover (the stage's copy). Printed on plate 3 (the plate's own
// mesh shows it until print-4), it stays on its plate until it is
// lifted off: from P4 this one is there, in the same place.
const sl = kit.slider;
const slMat = sl.material as THREE.MeshStandardMaterial;
- slMat.opacity = t < G1 + 0.17 ? caseFade : 1;
+ slMat.opacity = t < G1 + 0.17 ? caseFade : spare.slider;
+ sl.castShadow = t < G1 + 0.17 || spare.slider > 0.5;
if (t < G1 + 0.17) {
sl.visible = true;
setRigid(sl, places.home);
+ sl.position.add(open("slider"));
} else if (t < P4) sl.visible = false;
else {
- sl.visible = true;
- if (t < P4 + 0.55) setRigid(sl, arcRigid(centres.back_slider, places.plate.back_slider, places.sliderRest, span(t, P4 + 0.3, P4 + 0.55), 10, tmp.r));
- else if (t < K4 + 0.65) setRigid(sl, places.sliderRest);
- else if (t < K4 + 0.85) setRigid(sl, arcRigid(centres.back_slider, places.sliderRest, places.sliderOut, span(t, K4 + 0.65, K4 + 0.85), 6, tmp.r));
+ sl.visible = spare.slider > 0.01;
+ if (t < P4 + 0.56) setRigid(sl, carryRigid(centres.back_slider, places.plate.back_slider, places.sliderRest, span(t, P4 + 0.3, P4 + 0.56, clamp01), 10, tmp.r));
+ else if (t < K4 + 0.68) setRigid(sl, places.sliderRest);
+ else if (t < K4 + 0.86) setRigid(sl, carryRigid(centres.back_slider, places.sliderRest, places.sliderOut, span(t, K4 + 0.68, K4 + 0.86, clamp01), 6, tmp.r));
else {
+ // Along its rails: freely until the catch, then pushed over it.
tmp.r.q.identity();
- tmp.r.T.set(SLIDER_OUT_X * (1 - span(t, K4 + 0.86, K4 + 0.98)), 0, 0);
+ tmp.r.T.set(SLIDER_OUT_X * (1 - span(t, K4 + 0.865, K4 + 0.99, (x) => press(x, 0.9))), 0, 0);
setRigid(sl, tmp.r);
}
+ if (t >= K4 + 0.68 && t < K5) {
+ buildFocus.on = true;
+ buildFocus.size = 1.2;
+ buildFocus.world.copy(centres.back_slider).applyQuaternion(sl.quaternion).add(sl.position).multiplyScalar(MODEL_SCALE).add(MODEL_OFFSET);
+ }
}
// The lid over the power-bank tray: printed, laid down beside the
// case with the other covers, and slid in from the case's side at the
// end (check-5).
const lid = d.topLid;
+ lid.castShadow = t < P4 || spare.late > 0.5;
if (t < G1 + 0.17) {
lid.visible = true;
setRigid(lid, places.home);
+ lid.position.add(open("lid"));
} else if (t < P4) lid.visible = false;
else {
- lid.visible = true;
- if (t < P4 + 0.62) setRigid(lid, arcRigid(centres.top_lid, places.plate.top_lid, places.lidRest, span(t, P4 + 0.4, P4 + 0.62), 9, tmp.r));
+ (lid.material as THREE.MeshStandardMaterial).opacity = spare.late;
+ lid.visible = spare.late > 0.01;
+ if (t < P4 + 0.62) setRigid(lid, carryRigid(centres.top_lid, places.plate.top_lid, places.lidRest, span(t, P4 + 0.38, P4 + 0.62, clamp01), 9, tmp.r));
else if (t < K5) setRigid(lid, places.lidRest);
- else if (t < K5 + 0.32) setRigid(lid, arcRigid(centres.top_lid, places.lidRest, places.lidApproach, span(t, K5 + 0.18, K5 + 0.32), 5, tmp.r));
+ else if (t < K5 + 0.32) setRigid(lid, carryRigid(centres.top_lid, places.lidRest, places.lidApproach, span(t, K5 + 0.12, K5 + 0.32, clamp01), 5, tmp.r));
else {
- // Along its rails, in from the case's side.
+ // Along its rails, in from the case's side: freely, then pushed the last of the way.
tmp.r.q.identity();
- tmp.r.T.set(LID_CLEAR * (1 - span(t, K5 + 0.32, K5 + 0.5)), 0, 0);
+ tmp.r.T.set(LID_CLEAR * (1 - span(t, K5 + 0.33, K5 + 0.5, (x) => press(x, 0.92))), 0, 0);
setRigid(lid, tmp.r);
}
}
@@ -1335,6 +2134,9 @@ export default function BuildStage() {
const platesOn = t >= P2 && t < P4 + 0.92;
const plateFade = span(t, P2, P2 + 0.05) * (1 - span(t, P4 + 0.72, P4 + 0.92));
(kit.plates[0].slab.material as THREE.MeshStandardMaterial).opacity = plateFade;
+ kit.plateGround.visible = platesOn;
+ kit.plateGroundMat.opacity = plateFade;
+ kit.plateShadeMat.opacity = 0.6 * plateFade;
kit.plates.forEach((pl, i) => {
const p = i + 1;
pl.group.visible = platesOn && (p < 4 || t >= P3);
@@ -1358,6 +2160,34 @@ export default function BuildStage() {
pl.line.position.y = h;
(pl.line.material as THREE.LineBasicMaterial).opacity = printing ? 0.9 : 0;
pl.slab.visible = true;
+ // The nozzle, round the plate's parts about once a second.
+ const laying = printing && pl.length > 0;
+ pl.nozzle.visible = laying;
+ pl.bead.visible = laying;
+ if (laying) {
+ const secs = beatSeconds(Math.floor(from)) * (to - from);
+ const laps = Math.max(1, Math.round(secs / 1.15));
+ const along = (((u * laps) % 1) + 1) % 1;
+ let part = tourAt(pl.tour, pl.length, along, tmp.v);
+ pl.nozzle.position.set(tmp.v.x, h + 0.05, tmp.v.z);
+ // In at the start of the print and out at its end; dim on the way across to the next part.
+ const on = span(u, 0, 0.03, clamp01) * (1 - span(u, 0.97, 1, clamp01));
+ (pl.nozzle.material as THREE.SpriteMaterial).opacity = on * (part >= 0 ? 1 : 0.2);
+ const pos = pl.bead.geometry.getAttribute("position") as THREE.BufferAttribute;
+ for (let k = 0; k < BEAD; k++) {
+ // The bead behind it: no further back than the print's start, and
+ // only where both ends of a piece are on the same part's wall.
+ const back = Math.min((k + 1) * BEAD_STEP, u * laps);
+ const next = tourAt(pl.tour, pl.length, (((along - back) % 1) + 1) % 1, tmp.v2);
+ const laid = part >= 0 && next === part;
+ pos.setXYZ(k * 2, tmp.v.x, h + 0.012, tmp.v.z);
+ pos.setXYZ(k * 2 + 1, laid ? tmp.v2.x : tmp.v.x, h + 0.012, laid ? tmp.v2.z : tmp.v.z);
+ tmp.v.copy(tmp.v2);
+ part = next;
+ }
+ pos.needsUpdate = true;
+ (pl.bead.material as THREE.LineBasicMaterial).opacity = on;
+ }
});
// The halves: off their plates, turned to stand as they will, closed up.
@@ -1365,45 +2195,55 @@ export default function BuildStage() {
const sp = kit.split;
for (const n of ["frame_bottom", "frame_top", "back_bottom", "back_top"]) sp[n].visible = bonding;
if (bonding) {
- const uF = span(t, P4, P4 + 0.3, clamp01);
- setRigid(sp.frame_bottom, arcRigid(centres.frame_bottom, places.plate.frame_bottom, places.home, uF, 12, tmp.r));
- if (t < P4 + 0.3) setRigid(sp.frame_top, arcRigid(centres.frame_top, places.plate.frame_top, places.frameTopApart, uF, 14, tmp.r));
+ // Each half is lifted off its plate, turned to stand as it will,
+ // and set down โ the lower one first, the upper one held over it โ
+ // then the two are pressed together: up to the seam, a breath while
+ // the edges line up, and closed.
+ setRigid(sp.frame_bottom, carryRigid(centres.frame_bottom, places.plate.frame_bottom, places.home, span(t, P4, P4 + 0.28, clamp01), 12, tmp.r));
+ if (t < P4 + 0.31) setRigid(sp.frame_top, carryRigid(centres.frame_top, places.plate.frame_top, places.frameTopApart, span(t, P4 + 0.04, P4 + 0.31, clamp01), 14, tmp.r));
else {
tmp.r.q.identity();
- tmp.r.T.set(0, 3.2 * (1 - span(t, P4 + 0.3, P4 + 0.44)), 0);
+ tmp.r.T.set(0, 3.2 * (1 - span(t, P4 + 0.32, P4 + 0.46, (x) => press(x, 0.86))), 0);
setRigid(sp.frame_top, tmp.r);
}
- const uB = span(t, P4 + 0.04, P4 + 0.32, clamp01);
- setRigid(sp.back_bottom, arcRigid(centres.back_bottom, places.plate.back_bottom, places.backRest, uB, 10, tmp.r));
- if (t < P4 + 0.32) setRigid(sp.back_top, arcRigid(centres.back_top, places.plate.back_top, places.backTopApart, uB, 10, tmp.r));
+ setRigid(sp.back_bottom, carryRigid(centres.back_bottom, places.plate.back_bottom, places.backRest, span(t, P4 + 0.05, P4 + 0.31, clamp01), 10, tmp.r));
+ if (t < P4 + 0.34) setRigid(sp.back_top, carryRigid(centres.back_top, places.plate.back_top, places.backTopApart, span(t, P4 + 0.08, P4 + 0.34, clamp01), 10, tmp.r));
else {
tmp.r.q.copy(places.backRest.q);
- tmp.r.T.lerpVectors(places.backTopApart.T, places.backRest.T, span(t, P4 + 0.32, P4 + 0.46));
+ tmp.r.T.lerpVectors(places.backTopApart.T, places.backRest.T, span(t, P4 + 0.35, P4 + 0.48, (x) => press(x, 0.86)));
setRigid(sp.back_top, tmp.r);
}
}
// Tape and a glow along each seam while it cures.
- const tape = t >= P4 + 0.47 && t < swapAt;
+ // A strip at a time, laid across the seam from its middle and smoothed
+ // down to both ends; and peeled off again, the same way, once it has cured.
+ const tape = t >= P4 + 0.48 && t < swapAt;
+ const peel = (i: number) => 1 - span(t, swapAt - 0.09 + i * 0.015, swapAt - 0.05 + i * 0.015, ease);
kit.frameTape.forEach((m, i) => {
- m.visible = tape && t >= P4 + 0.47 + i * 0.03;
+ const on = span(t, P4 + 0.48 + i * 0.025, P4 + 0.51 + i * 0.025, ease) * peel(i);
+ m.visible = tape && on > 0;
+ m.scale.set(1, Math.max(0.02, on), 1);
});
setRigid(kit.backSeamGroup, places.backRest);
kit.backTape.forEach((m, i) => {
- m.visible = tape && t >= P4 + 0.48 + i * 0.03;
+ const on = span(t, P4 + 0.5 + i * 0.025, P4 + 0.53 + i * 0.025, ease) * peel(i);
+ m.visible = tape && on > 0;
+ m.scale.set(1, Math.max(0.02, on), 1);
});
- const pulse = t >= P4 + 0.44 && t < swapAt ? (0.5 + 0.5 * Math.sin(state.clock.elapsedTime * 7)) * (1 - span(t, swapAt - 0.06, swapAt)) : 0;
+ const pulse = t >= P4 + 0.46 && t < swapAt ? (0.5 + 0.5 * Math.sin(state.clock.elapsedTime * 7)) * (1 - span(t, swapAt - 0.14, swapAt - 0.08)) : 0;
kit.seamMat.opacity = pulse;
kit.frameSeam.visible = pulse > 0.01;
- kit.backSeamGroup.visible = t >= P4 + 0.44 && t < swapAt;
+ kit.backSeamGroup.visible = t >= P4 + 0.48 && t < swapAt;
}
// โโ the knobs โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
d.knobs.forEach((k, i) => {
const home = d.knobHome[i];
const mat = d.knobMats[i] as THREE.MeshStandardMaterial;
- mat.opacity = t < G1 + 0.17 ? caseFade : 1;
const onAt = K5 + 0.52 + i * 0.09;
const doneAt = onAt + 0.2;
+ // With the case at the opening; put away with the bench while they wait on the floor (`spare`).
+ mat.opacity = t < G1 + 0.17 ? caseFade : t < doneAt ? spare.late : 1;
if (finished || t >= doneAt) {
// Device's: home, turning and pressing as the encoder does.
if (!d.released[i]) {
@@ -1418,10 +2258,11 @@ export default function BuildStage() {
d.released[i] = false;
let shown = true;
if (t < G1 + 0.17) {
- // Fading with the case.
+ // Fading with the case, where the opening has it.
k.position.copy(home.p);
+ k.position.z += open("knobs").z;
k.quaternion.copy(home.q);
- } else if (t < P4) shown = false;
+ } else if (t < P4 || spare.late < 0.01) shown = false;
else {
const plateP = tmp.a;
plateCorner(4, plateP.p).add(V(KNOB_PLATE_XZ[i][0], 2, KNOB_PLATE_XZ[i][1]));
@@ -1432,27 +2273,37 @@ export default function BuildStage() {
if (t < P4 + 0.5) {
k.position.copy(plateP.p);
k.quaternion.copy(plateP.q);
- } else if (t < P4 + 0.8) {
- arcPose(plateP, rest, span(t, P4 + 0.5 + i * 0.04, P4 + 0.68 + i * 0.04), 8, tmp.c);
+ } else if (t < P4 + 0.84) {
+ carry(plateP, rest, span(t, P4 + 0.5 + i * 0.045, P4 + 0.7 + i * 0.045, clamp01), 8, tmp.c);
k.position.copy(tmp.c.p);
k.quaternion.copy(tmp.c.q);
} else if (t < onAt) {
k.position.copy(rest.p);
k.quaternion.copy(rest.q);
} else {
- // Over to the front of its shaft, then pressed on.
+ // Up to the front of its shaft; turned until its flat finds the
+ // shaft's; pushed on โ it goes on tight, most of the way and then
+ // home โ and the encoder gives under the last of the push.
const above = tmp.c;
- above.p.copy(home.p).add(V(0, 0, 2.4));
+ above.p.copy(home.p);
+ above.p.z += 2.4;
above.q.copy(home.q);
- if (t < onAt + 0.13) {
- arcPose(rest, above, span(t, onAt, onAt + 0.13), 6, tmp.a);
+ // It arrives turned a little off, and is turned true as it goes on.
+ const off = (i % 2 ? -0.7 : 0.7) * span(t, onAt + 0.03, onAt + 0.12, glide) * (1 - span(t, onAt + 0.12, onAt + 0.16, glide));
+ if (t < onAt + 0.12) {
+ arc(rest, above, span(t, onAt, onAt + 0.12, glide), 2.2, tmp.a);
k.position.copy(tmp.a.p);
k.quaternion.copy(tmp.a.q);
} else {
- k.position.lerpVectors(above.p, home.p, span(t, onAt + 0.13, onAt + 0.2));
- k.position.z -= KNOB_PRESS * Math.sin(Math.PI * span(t, onAt + 0.17, onAt + 0.2, clamp01));
+ const x = span(t, onAt + 0.12, onAt + 0.2, clamp01);
+ k.position.lerpVectors(above.p, home.p, press(x, 0.66));
+ k.position.z -= KNOB_PRESS * Math.sin(Math.PI * clamp01((x - 0.74) / 0.26));
k.quaternion.copy(home.q);
}
+ k.quaternion.multiply(tmp.q.setFromAxisAngle(tmp.v.set(0, 0, 1), off));
+ buildFocus.on = true;
+ buildFocus.size = 0.3;
+ buildFocus.world.copy(k.position).multiplyScalar(MODEL_SCALE).add(MODEL_OFFSET);
}
}
k.visible = shown;
@@ -1470,42 +2321,51 @@ export default function BuildStage() {
const ledOn = finished || t >= C2;
d.led.visible = ledOn;
if (kit.panel.slab) kit.panel.slab.visible = !ledOn;
- const arrive = G2 + 0.05;
+ const arrive = ARRIVE2.panel;
let on = true;
let scale = 1;
let alpha = 1;
if (t < G1 + 0.17) {
- pg.position.copy(PANEL_CENTRE);
+ pg.position.copy(PANEL_CENTRE).add(open("panel"));
pg.quaternion.identity();
alpha = caseFade;
} else if (t < C1) {
- const dr = drop(t, arrive, 0.1);
+ // The heaviest thing on the bench: let down, not dropped.
+ const dr = drop(t, arrive, 0.2, true);
on = dr.on;
pg.position.copy(PANEL_BENCH.p).setY(PANEL_BENCH.p.y + dr.fall * 3);
- pg.quaternion.copy(PANEL_BENCH.q);
+ pg.quaternion.copy(tilt(31, 0.07 * dr.lean)).multiply(PANEL_BENCH.q);
scale = dr.scale;
} else if (t < C1 + 0.5) {
// Up off the mat and stood up in FRONT of the frame, its back to the
// frame, IN end up: the panel only goes in from the front (the
// frame's ledge and its twelve tabs are behind it).
- const u = span(t, C1 + 0.12, C1 + 0.5, smooth);
- const front = tmp.v.copy(PANEL_CENTRE).add(V(0, 0, PANEL_FRONT_GAP));
- bezier(PANEL_BENCH.p, V(PANEL_BENCH.p.x, 15, PANEL_BENCH.p.z), V(-9, 21, 21), front, u, pg.position);
- pg.quaternion.slerpQuaternions(PANEL_BENCH.q, IDENTITY, smooth((u - 0.08) / 0.8));
+ const u = span(t, C1 + 0.1, C1 + 0.5, glide);
+ const front = tmp.v.copy(PANEL_CENTRE);
+ front.z += PANEL_FRONT_GAP;
+ bezier(PANEL_BENCH.p, tmp.v2.set(PANEL_BENCH.p.x, 15, PANEL_BENCH.p.z), tmp.v3.set(-9, 21, 21), front, u, pg.position);
+ pg.quaternion.slerpQuaternions(PANEL_BENCH.q, IDENTITY, glide((u - 0.08) / 0.8));
} else {
- // In along โz, slowly, its bottom edge first and the top pressed home
- // after it โ the fit has almost no clearance โ until its rim is on
- // the ledge and the tabs.
- const u = span(t, C1 + 0.54, C1 + 0.96, clamp01);
- const tilt = 0.06 * smooth(u / 0.3) * (1 - smooth((u - 0.62) / 0.38));
- pg.quaternion.setFromAxisAngle(tmp.v.set(1, 0, 0), tilt);
+ // In along โz, its bottom edge first: up to the frame quickly, then
+ // slowly โ the fit has almost no clearance, and it is worked in, one
+ // side a hair ahead of the other โ until the bottom of its rim is on
+ // the ledge; then the top is pressed home after it, in two pushes,
+ // until the rim is on the ledge and the tabs all round.
+ const x = span(t, C1 + 0.52, C1 + 0.97, clamp01);
+ const gap = PANEL_FRONT_GAP * (1 - 0.87 * reach(x / 0.34) - 0.09 * span(x, 0.34, 0.58, clamp01) - 0.04 * span(x, 0.58, 0.68, ease));
+ const lean = 0.075 * glide(x / 0.3) * (1 - 0.6 * span(x, 0.68, 0.78, reach) - 0.4 * span(x, 0.86, 0.96, reach));
+ const work = 0.011 * Math.sin((x - 0.34) * 46) * span(x, 0.34, 0.4, clamp01) * (1 - span(x, 0.56, 0.68, clamp01));
+ pg.quaternion.setFromAxisAngle(tmp.v.set(1, 0, 0), lean).multiply(tmp.q.setFromAxisAngle(Y, work));
// About its bottom back edge, which travels straight in.
const edge = tmp.v2.set(0, -16, -0.85);
- pg.position
- .copy(PANEL_CENTRE)
- .add(edge)
- .add(tmp.v3.set(0, 0, PANEL_FRONT_GAP * (1 - smooth(u / 0.72))))
- .sub(edge.applyQuaternion(pg.quaternion));
+ pg.position.copy(PANEL_CENTRE).add(edge);
+ pg.position.z += gap;
+ pg.position.sub(edge.applyQuaternion(pg.quaternion));
+ }
+ if (t >= C1 + 0.1 && t < C2) {
+ buildFocus.on = true;
+ buildFocus.size = 3;
+ buildFocus.world.copy(pg.position).multiplyScalar(MODEL_SCALE).add(MODEL_OFFSET);
}
pg.visible = on;
pg.scale.setScalar(scale);
@@ -1521,75 +2381,115 @@ export default function BuildStage() {
seated.p.set(hx, hy, TAB_BACK_Z + 1.0);
seated.q.copy(lying);
let scale = 1;
- const s0 = k < 6 ? C2 + 0.14 + k * 0.07 : C2 + 0.56 + (k - 6) * 0.035;
+ // The first one alone, with the camera close on it (views.ts): what
+ // is done. Then five more to the corners and middles โ the six that
+ // hold the panel โ and the other six quickly.
+ const s0 = k === 0 ? C2 + 0.12 : k < 6 ? C2 + 0.38 + (k - 1) * 0.06 : C2 + 0.63 + (k - 6) * 0.023;
const bench = tmp.b;
bench.p.set(SCREW_BENCH_X0 + k * SCREW_BENCH_DX, MAT_TOP + 0.36, SCREW_BENCH_Z);
bench.q.copy(lying);
let p: Pose = seated;
if (finished) p = seated;
else if (t < s0) {
- const dr = drop(t, G2 + 0.3 + k * 0.012, 0.06);
+ // A handful let fall along the row: one after another, each rocking still.
+ const dr = drop(t, ARRIVE2.screws + k * 0.014, 0.08);
scale = dr.on ? dr.scale : 0;
bench.p.y += dr.fall * 2.5;
+ bench.q.premultiply(tilt(70 + k, 0.3 * dr.lean));
p = bench;
} else if (t < s0 + 0.16) {
// Over the top of the case and down behind it to its tab: high and
// far enough back that it is past the case before it comes down
// (a lower arc took the screws for the low tabs through the panel).
- const u = span(t, s0, s0 + 0.16, smooth);
- const hover = tmp.v.set(hx, hy, TAB_BACK_Z - 3.2);
+ const u = span(t, s0, s0 + 0.16, glide);
+ // (Its tip, 3.2 behind where it ends up: where the drive below takes it from.)
+ const hover = tmp.v.set(hx, hy, TAB_BACK_Z + 1.0 - 3.2);
bezier(bench.p, tmp.v2.set(bench.p.x, OVER_TOP[0], bench.p.z / 2), tmp.v3.set(hx, OVER_TOP[1], OVER_TOP[2]), hover, u, tmp.c.p);
tmp.c.q.copy(lying);
p = tmp.c;
} else {
- // Driven in: 1.2 units along +z, turning.
- const u = span(t, s0 + 0.16, s0 + 0.24, smooth);
- tmp.c.p.set(hx, hy, TAB_BACK_Z + 1.0 - (1 - u) * 3.2 + (u < 0.4 ? 0 : 0));
- tmp.c.q.copy(lying).multiply(tmp.q.setFromAxisAngle(Y, -u * Math.PI * 8));
+ // In through its slot until the thread meets the panel's insert,
+ // then driven: it goes in as far as it turns, a turn for every
+ // sixth of a unit, slower as the head comes down on the tab โ
+ // clockwise, seen from behind.
+ const x = span(t, s0 + 0.16, s0 + 0.25, clamp01);
+ const near = reach(x / 0.36);
+ const driven = 1 - Math.pow(1 - clamp01((x - 0.3) / 0.7), 2.4);
+ tmp.c.p.set(hx, hy, TAB_BACK_Z + 1.0 - 3.2 + 2.45 * near + 0.75 * driven);
+ tmp.c.q.copy(lying).multiply(tmp.q.setFromAxisAngle(Y, -driven * Math.PI * 9));
p = tmp.c;
+ if (x < 1) {
+ buildFocus.on = true;
+ buildFocus.size = 0.12;
+ buildFocus.world.copy(tmp.c.p).multiplyScalar(MODEL_SCALE).add(MODEL_OFFSET);
+ }
}
- if (!finished && t >= G1 && t < G2 + 0.3) scale = 0;
+ if (!finished && t >= G1 && t < ARRIVE2.screws) scale = 0;
+ if (!shut) scale = 0;
m.compose(p.p, p.q, tmp.s.setScalar(scale));
kit.screws.setMatrixAt(k, m);
+ kit.screwSlots.setMatrixAt(k, m);
});
kit.screws.instanceMatrix.needsUpdate = true;
+ kit.screwSlots.instanceMatrix.needsUpdate = true;
}
// โโ washers and nuts on the encoder bushings โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+ //
+ // One encoder at a time, top to bottom: its washer is brought up from the
+ // mat, slipped over the shaft and rings down flat against the case; the
+ // nut comes after it, is started on the thread and run down โ it turns as
+ // far as it travels โ until it is snug.
{
const m = tmp.m;
const upZ = qx(Math.PI / 2);
for (let k = 0; k < 4; k++) {
- const ax = boardToModel(tmp.v.copy(SW_CENTRES[k]), BOARD_IN_CASE, V());
+ const ax = boardToModel(tmp.v.copy(SW_CENTRES[k]), BOARD_IN_CASE, tmp.v5);
const sx = ROW[`SW${k + 1}`];
- const arrive = ARRIVE0 + (6 + k) * ARRIVE_STEP + 0.02;
- const s0 = C5 + 0.2 + k * 0.18;
+ const s0 = C5 + 0.22 + k * 0.17;
for (const which of [0, 1] as const) {
const seatZ = which === 0 ? FRONT_Z : FRONT_Z + 0.05;
- const restP = V(sx + (which ? 0.15 : 0), MAT_TOP, which ? NUT_ROW_Z - 1.3 : NUT_ROW_Z);
- const lift0 = s0 + which * 0.04;
+ const restP = tmp.b.p.set(sx + (which ? 0.15 : 0), MAT_TOP, which ? NUT_ROW_Z - 1.3 : NUT_ROW_Z);
+ tmp.b.q.identity();
+ const lift0 = s0 + which * 0.045;
let scale = 1;
if (finished) {
tmp.a.p.set(ax.x, ax.y, seatZ);
tmp.a.q.copy(upZ);
+ if (!shut) scale = 0;
} else if (t < lift0) {
- const dr = drop(t, arrive, 0.06);
+ const dr = drop(t, ARRIVE[`SW${k + 1}` as PartName] + 0.03 + which * 0.02, 0.09);
scale = dr.on ? dr.scale : 0;
tmp.a.p.copy(restP).setY(restP.y + dr.fall * 2.5);
- tmp.a.q.identity();
+ tmp.a.q.copy(tilt(50 + k * 2 + which, 0.3 * dr.lean));
} else if (t < lift0 + 0.1) {
- tmp.b.p.copy(restP);
- tmp.b.q.identity();
+ // Up from the mat to in front of its shaft, turned to face it.
tmp.c.p.set(ax.x, ax.y, seatZ + 3);
tmp.c.q.copy(upZ);
- arcPose(tmp.b, tmp.c, span(t, lift0, lift0 + 0.1, clamp01), 10, tmp.a);
+ arc(tmp.b, tmp.c, span(t, lift0, lift0 + 0.1, glide), 2.4, tmp.a);
+ } else if (which === 0) {
+ // The washer: over the shaft and down it, and it rings flat against the case.
+ const u = span(t, lift0 + 0.1, lift0 + 0.15, reach);
+ const ring = sway((t - (lift0 + 0.145)) / 0.05, 1.5, 2.2);
+ const lean = 0.16 * Math.abs(ring);
+ tmp.a.p.set(ax.x, ax.y, seatZ + 3 * (1 - u) + 0.53 * Math.sin(lean));
+ tmp.a.q.copy(upZ).multiply(tmp.q.setFromAxisAngle(tmp.v.set(Math.cos(k * 1.7 + ring * 3), 0, Math.sin(k * 1.7 + ring * 3)), lean));
} else {
- const u = span(t, lift0 + 0.1, lift0 + 0.16, smooth);
- tmp.a.p.set(ax.x, ax.y, seatZ + 3 * (1 - u));
- tmp.a.q.copy(upZ).multiply(tmp.q.setFromAxisAngle(Y, which ? -u * Math.PI * 6 : 0));
+ // The nut: up to the end of the thread, then on โ a turn for every
+ // 0.2 of the way, slower as it tightens.
+ const near = span(t, lift0 + 0.1, lift0 + 0.135, reach);
+ const on = span(t, lift0 + 0.135, lift0 + 0.21, (x) => 1 - Math.pow(1 - clamp01(x), 2.2));
+ tmp.a.p.set(ax.x, ax.y, seatZ + 0.7 + 2.3 * (1 - near) - 0.7 * on);
+ tmp.a.q.copy(upZ).multiply(tmp.q.setFromAxisAngle(Y, -on * Math.PI * 7));
}
m.compose(tmp.a.p, tmp.a.q, tmp.s.setScalar(scale));
(which ? kit.nuts : kit.washers).setMatrixAt(k, m);
+ // The one in hand is what the step is about.
+ if (!finished && t >= lift0 && t < lift0 + 0.21) {
+ buildFocus.on = true;
+ buildFocus.size = 0.12;
+ buildFocus.world.copy(tmp.a.p).multiplyScalar(MODEL_SCALE).add(MODEL_OFFSET);
+ }
}
}
kit.washers.instanceMatrix.needsUpdate = true;
@@ -1597,7 +2497,8 @@ export default function BuildStage() {
}
// โโ the power bank, the plug, the J4 lead โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- const plugIn = finished || t >= F3 + 0.76;
+ // The plug starts into the bank's port at PLUG_GO and is home โ power on โ at PLUG_HOME.
+ const plugIn = finished || t >= PLUG_HOME;
{
// The panel lights only once the bank is plugged in (firmware-3): a
// lit step reached while the timeline is still short of that โ it runs
@@ -1622,24 +2523,30 @@ export default function BuildStage() {
const b = kit.bank;
let on = true;
let scale = 1;
- if (finished || t >= F3 + 0.7) {
+ if (finished || t >= F3 + 0.63) {
b.position.copy(BANK_IN.p);
b.quaternion.identity();
} else if (t < F3) {
- const dr = drop(t, G2 + 0.4, 0.08);
+ const dr = drop(t, ARRIVE2.bank, 0.18, true);
on = dr.on;
scale = dr.scale;
b.position.copy(BANK_BENCH.p).setY(BANK_BENCH.p.y + dr.fall * 3);
- b.quaternion.copy(BANK_BENCH.q);
+ b.quaternion.copy(tilt(33, 0.1 * dr.lean)).multiply(BANK_BENCH.q);
} else if (t < F3 + 0.44) {
- arcPose(BANK_BENCH, BANK_FRONT, span(t, F3 + 0.2, F3 + 0.42), 6, tmp.a);
+ carry(BANK_BENCH, BANK_FRONT, span(t, F3 + 0.14, F3 + 0.43, clamp01), 5, tmp.a);
b.position.copy(tmp.a.p);
b.quaternion.copy(tmp.a.q);
} else {
- b.position.lerpVectors(BANK_FRONT.p, BANK_IN.p, span(t, F3 + 0.46, F3 + 0.7, smooth));
+ // Slid into its tray: it has weight โ drawn back a little, then pushed, and up against the tray's back without a knock.
+ b.position.lerpVectors(BANK_FRONT.p, BANK_IN.p, span(t, F3 + 0.44, F3 + 0.63, (x) => windUp(x, 0.035)));
b.quaternion.identity();
}
- b.visible = on;
+ if (t >= F3 + 0.14 && t < F3 + 0.64) {
+ buildFocus.on = true;
+ buildFocus.size = 1.2;
+ buildFocus.world.copy(b.position).multiplyScalar(MODEL_SCALE).add(MODEL_OFFSET);
+ }
+ b.visible = on && shut;
b.scale.setScalar(scale);
kit.bankLed.visible = plugIn && sim.snapshot().mode !== "off";
@@ -1648,23 +2555,29 @@ export default function BuildStage() {
// (check-3) it follows the panel: out while it is off.
const plugPos = tmp.v4;
const above = (p: THREE.Vector3, h: number) => plugPos.copy(p).setY(p.y + h);
- if (plugIn) {
+ if (finished || t >= PLUG_GO) {
+ // Down into the port: its mouth found, then pushed in until it stops.
const track = plugTrack.current;
const out = !finished && t >= K1 && sim.snapshot().mode === "off" ? 1 : 0;
track.out += (out - track.out) * Math.min(1, dt * 8);
- above(PORT_IN, finished ? 0 : Math.max(1.1 * track.out, 1.4 * (1 - span(t, F3 + 0.76, F3 + 0.84))));
+ above(PORT_IN, finished ? 0 : Math.max(1.1 * track.out, 1.4 * (1 - span(t, PLUG_GO, PLUG_HOME, (x) => press(x, 0.55)))));
+ if (!finished && t < PLUG_HOME + 0.04) {
+ buildFocus.on = true;
+ buildFocus.size = 0.2;
+ buildFocus.world.copy(plugPos).multiplyScalar(MODEL_SCALE).add(MODEL_OFFSET);
+ }
} else if (t < F3) plugPos.copy(PLUG_LOOSE);
- else plugPos.lerpVectors(PLUG_LOOSE, tmp.v2.copy(PORT_IN).setY(PORT_IN.y + 1.4), span(t, F3 + 0.22, F3 + 0.42, smooth));
+ else plugPos.lerpVectors(PLUG_LOOSE, tmp.v2.copy(PORT_IN).setY(PORT_IN.y + 1.4), span(t, F3 + 0.2, F3 + 0.42, glide));
// The cable as it came: a coil on the mat, its USB-A plug lying at
// the coil's end, mouth toward the reader โ a bare coil did not read
// as a USB cable. At case-3 it is the lead, its plug in the tray.
- const coilDrop = drop(t, G2 + 0.36, 0.07);
+ const coilDrop = drop(t, ARRIVE2.usb, 0.09);
const cableOn = finished || t >= C3 + 0.05;
if (cableOn) {
kit.plug.position.copy(plugPos);
kit.plug.quaternion.identity();
kit.plug.scale.setScalar(1);
- kit.plug.visible = true;
+ kit.plug.visible = shut;
} else {
kit.plug.position.copy(USB_PLUG_BENCH).setY(USB_PLUG_BENCH.y + coilDrop.fall * 2);
kit.plug.quaternion.copy(PLUG_FLAT);
@@ -1689,15 +2602,28 @@ export default function BuildStage() {
const entryMid = tmp.v2.copy(J4_ENTRY[0]).add(J4_ENTRY[1]).multiplyScalar(0.5);
const onBoard = boardToModel(tmp.v3.copy(entryMid).setZ(entryMid.z + 0.0022), boardPose, tmp.jacket);
// 0 while the end is free, 1 once it is in J4.
- const held = finished ? 1 : span(t, C3 + 0.72, C3 + 0.84, smooth);
+ const held = finished ? 1 : span(t, C3 + 0.72, C3 + 0.86, glide);
+ // A lead pushed up through a hole comes out swinging, and is still by
+ // the time the board is brought to it; and once it is in J4 the slack
+ // behind the board swings once and hangs.
+ const whip = finished ? 0 : 0.42 * sway((t - (C3 + 0.26)) / 0.16, 1.6, 1.5) * (1 - held);
+ const hang = finished ? 0 : 0.3 * sway((t - (C3 + 0.85)) / 0.12, 1.2, 2);
// Out and round J4's side on its way under it, not through its body.
const jacketEnd = onBoard.lerpVectors(LEAD_FREE, onBoard, held).addScaledVector(LEAD_ROUND, Math.sin(Math.PI * held));
- const inCase = finished || t >= C4 + 0.55 ? 1 : t >= C4 ? span(t, C4, C4 + 0.55, smooth) : 0;
+ jacketEnd.x += whip;
+ jacketEnd.z += whip * 0.4;
+ // The slack goes back down the hole as the board goes in: with it, not ahead of it.
+ const inCase = finished || t >= C4 + 0.7 ? 1 : t >= C4 ? span(t, C4 + 0.14, C4 + 0.7, (x) => press(x, 0.8)) : 0;
pts[5].lerpVectors(BAY_OUT, BAY_IN, inCase);
pts[6].lerpVectors(tmp.v.lerpVectors(LEAD_FREE_MID, SAG, held), tmp.v2.lerpVectors(pts[5], jacketEnd, 0.45), inCase);
+ pts[6].x += whip * 0.45 + hang;
+ pts[6].z += hang * 0.6;
pts[7].lerpVectors(pts[6], jacketEnd, 0.7);
pts[8].copy(jacketEnd);
- kit.usbPath.touch();
+ // (Its plug end also follows the power cycle at check-3, eased on the frame clock.)
+ const usbStill = tStill && plugPos.distanceToSquared(tmp.plugShown) < 1e-10;
+ tmp.plugShown.copy(plugPos);
+ if (!usbStill) kit.usbPath.touch();
// Up the tray first (behind the case, out of this step's view), then
// out of the hole at a pace that can be watched: the hole's share of
// the lead's length, by its chords.
@@ -1709,21 +2635,25 @@ export default function BuildStage() {
}
const holeAt = toHole / Math.max(1e-6, whole);
const grow = finished ? 1 : holeAt * span(t, C3 + 0.06, C3 + 0.2, clamp01) + (1 - holeAt) * span(t, C3 + 0.2, C3 + 0.38, smooth);
- if (cableOn && grow > 0) kit.usb.update(kit.usbPath, grow);
- kit.usb.mesh.visible = cableOn && grow > 0;
+ if (cableOn && grow > 0 && !usbStill) kit.usb.update(kit.usbPath, grow);
+ kit.usb.mesh.visible = cableOn && grow > 0 && shut;
// Red to +5V, black to GND: fanned out of the jacket while they wait, then into J4's entries.
const wireGrow = finished ? 1 : span(t, C3 + 0.37, C3 + 0.42, clamp01);
+ // The two wires spring apart as they come out of the jacket.
+ const spread = finished ? 1 : span(t, C3 + 0.38, C3 + 0.5, (x) => past(x, 0.18));
[1, 0].forEach((pad, w) => {
const path = kit.j4Paths[w];
- const fan = w === 0 ? -0.22 : 0.22;
+ const fan = (w === 0 ? -0.22 : 0.22) * spread;
path.points[0].copy(jacketEnd);
boardToModel(tmp.v.copy(J4_ENTRY[pad]).setZ(J4_ENTRY[pad].z + 0.0012), boardPose, path.points[1]);
boardToModel(tmp.v.copy(J4_ENTRY[pad]).setZ(J4_ENTRY[pad].z - 0.0025), boardPose, path.points[2]);
path.points[1].lerpVectors(tmp.v.copy(LEAD_FREE).add(tmp.v2.set(fan * 0.5, 0.12, -0.45)), path.points[1], held);
path.points[2].lerpVectors(tmp.v.copy(LEAD_FREE).add(tmp.v2.set(fan, 0.3, -0.85)), path.points[2], held);
- path.touch();
- if (cableOn && wireGrow > 0) kit.j4Wires[w].update(path, wireGrow);
- kit.j4Wires[w].mesh.visible = cableOn && wireGrow > 0;
+ if (!tStill) {
+ path.touch();
+ if (cableOn && wireGrow > 0) kit.j4Wires[w].update(path, wireGrow);
+ }
+ kit.j4Wires[w].mesh.visible = cableOn && wireGrow > 0 && shut;
});
// The coil it came as, on the mat.
kit.coils.usb.visible = !finished && coilDrop.on && t < C3 + 0.08;
@@ -1742,26 +2672,49 @@ export default function BuildStage() {
const rc = tmp.v;
let rs = 1;
let rOn = true;
- if (finished || t >= W1 + 0.74) {
+ // How far out of its seat each end and the fold are held, and how far it hangs (props.ts foldedRibbon).
+ let endJ1 = 0;
+ let fold = 0;
+ let endIn = 0;
+ const sag = tmp.v5.set(0, 0, 0);
+ if (finished || t >= W1 + 0.88) {
rq.identity();
rc.copy(RIBBON_CENTRE);
- } else if (t < W1 + 0.16) {
- const dr = drop(t, G2 + 0.12, 0.07);
+ } else if (t < W1 + 0.1) {
+ const dr = drop(t, ARRIVE2.ribbon, 0.1);
rOn = t >= G1 && dr.on;
rs = dr.scale;
- rq.copy(RIBBON_BENCH.q);
+ rq.copy(tilt(32, 0.14 * dr.lean)).multiply(RIBBON_BENCH.q);
rc.copy(RIBBON_BENCH.p).setY(RIBBON_BENCH.p.y + dr.fall * 2.5);
- } else if (t < W1 + 0.56) {
- // Quick over the top of the case, where the camera is not looking, and slow down behind it, where it is.
- const u = 1 - Math.pow(1 - span(t, W1 + 0.16, W1 + 0.56, clamp01), 2.4);
- const hover = tmp.v2.copy(RIBBON_CENTRE).setZ(RIBBON_CENTRE.z - RIBBON_HOVER);
- bezier(RIBBON_BENCH.p, tmp.v3.set(RIBBON_BENCH.p.x, 44, 28), tmp.v4.set(RIBBON_CENTRE.x, 50, -8), hover, u, rc);
- rq.slerpQuaternions(RIBBON_BENCH.q, IDENTITY, smooth((u - 0.1) / 0.7));
} else {
- rq.identity();
- rc.copy(RIBBON_CENTRE).setZ(RIBBON_CENTRE.z - RIBBON_HOVER * (1 - span(t, W1 + 0.6, W1 + 0.74, smooth)));
+ // Picked up by its fold โ its two runs hang from it, the long one
+ // most โ and carried over the top of the case: quick where the
+ // camera is not looking, slow down behind it, where it is. There it
+ // is held just off its seat, and goes on one end at a time: J1's
+ // plug pressed home, the run laid flat after it, then IN's plug.
+ const x = span(t, W1 + 0.1, W1 + 0.54, clamp01);
+ const u = 1 - Math.pow(1 - smooth(x), 1.7);
+ bezier(RIBBON_BENCH.p, tmp.v2.set(RIBBON_BENCH.p.x, 44, 28), tmp.v3.set(RIBBON_CENTRE.x, 50, -8), RIBBON_CENTRE, u, rc);
+ const turned = glide((u - 0.1) / 0.7);
+ rq.slerpQuaternions(RIBBON_BENCH.q, IDENTITY, turned);
+ // Off its seat by the hover, once it is turned to face it (lying on the mat that way is down, into it).
+ const off = RIBBON_HOVER * turned;
+ endJ1 = off * (1 - span(t, W1 + 0.58, W1 + 0.69, (y) => press(y, 0.72)));
+ fold = off * (1 - span(t, W1 + 0.63, W1 + 0.8, glide));
+ endIn = off * (1 - span(t, W1 + 0.74, W1 + 0.87, (y) => press(y, 0.72)));
+ // It hangs while it is in the air, swings a little as it is brought to a stop, and is taken up as its ends are held.
+ const hang = 0.85 * span(t, W1 + 0.1, W1 + 0.18, glide) * (1 - span(t, W1 + 0.5, W1 + 0.62, glide)) + 0.3 * sway((t - (W1 + 0.5)) / 0.1, 1.2, 2) * (1 - span(t, W1 + 0.58, W1 + 0.66, clamp01));
+ // Down, in the ribbon's own frame.
+ sag.set(0, -hang, 0).applyQuaternion(tmp.q.copy(rq).invert());
+ if (t >= W1 + 0.56) {
+ buildFocus.on = true;
+ buildFocus.size = 0.3;
+ buildFocus.world.copy(t < W1 + 0.71 ? J1_MOUTH : PANEL_IN).multiplyScalar(MODEL_SCALE).add(MODEL_OFFSET);
+ }
}
- rb.visible = rOn;
+ kit.ribbonFlex.bend(endJ1, fold, endIn, sag);
+ kit.ribbonPlugs.forEach((rp, i) => rp.mesh.position.copy(rp.home).add(kit.ribbonFlex.ends[i]));
+ rb.visible = rOn && shut;
rb.quaternion.copy(rq);
rb.scale.setScalar(rs);
// Turned and scaled about its own middle.
@@ -1772,26 +2725,27 @@ export default function BuildStage() {
// the notch's low end and down the bay's side into J3 from above.
const seat = tmp.v2.set(PANEL_POWER.x, PANEL_POWER.y, PANEL_PCB_Z - 0.3);
const pp = kit.powerPlug;
- const pc = drop(t, G2 + 0.15, 0.07);
+ const pc = drop(t, ARRIVE2.power, 0.09);
// On the mat it lies in its coil, mating face up.
const plugBench = tmp.v5.set(POWER_COIL.x, POWER_COIL.y + 0.9, POWER_COIL.z);
pp.scale.setScalar(1);
- if (finished || t >= W2 + 0.24) {
+ if (finished || t >= W2 + 0.26) {
pp.position.copy(seat);
pp.quaternion.identity();
- pp.visible = true;
+ pp.visible = shut;
} else if (t < W2 + 0.02) {
pp.visible = t >= G1 && pc.on;
pp.position.copy(plugBench).setY(MAT_TOP + 0.9 * pc.scale + pc.fall * 2.5);
pp.quaternion.copy(qx(-Math.PI / 2));
pp.scale.setScalar(pc.scale);
} else if (t < W2 + 0.18) {
- const u = span(t, W2 + 0.02, W2 + 0.18, smooth);
+ const u = span(t, W2 + 0.02, W2 + 0.18, glide);
bezier(plugBench, tmp.v3.set(POWER_COIL.x, OVER_TOP[0], POWER_COIL.z / 2), tmp.v4.set(seat.x, OVER_TOP[1], OVER_TOP[2]), tmp.v.copy(seat).setZ(seat.z - 2.4), u, pp.position);
- pp.quaternion.slerpQuaternions(qx(-Math.PI / 2), IDENTITY, smooth((u - 0.1) / 0.7));
+ pp.quaternion.slerpQuaternions(qx(-Math.PI / 2), IDENTITY, glide((u - 0.1) / 0.7));
pp.visible = true;
} else {
- pp.position.copy(seat).setZ(seat.z - 2.4 * (1 - span(t, W2 + 0.18, W2 + 0.24, smooth)));
+ // Onto its header: found, then pushed until its latch is over.
+ pp.position.copy(seat).setZ(seat.z - 2.4 * (1 - span(t, W2 + 0.18, W2 + 0.26, (y) => press(y, 0.7))));
pp.quaternion.identity();
pp.visible = true;
}
@@ -1836,9 +2790,11 @@ export default function BuildStage() {
laid.z = carried + (z - carried) * lower;
}
}
- kit.powerPaths[w].touch();
- if (pwrOn) kit.powerWires[w].update(kit.powerPaths[w], tail);
- kit.powerWires[w].mesh.visible = pwrOn && tail > 0;
+ if (!tStill) {
+ kit.powerPaths[w].touch();
+ if (pwrOn) kit.powerWires[w].update(kit.powerPaths[w], tail);
+ }
+ kit.powerWires[w].mesh.visible = pwrOn && tail > 0 && shut;
});
kit.coils.power.visible = !finished && pc.on && t < W2 + 0.1;
kit.coils.power.scale.setScalar(pc.scale * (1 - span(t, W2 + 0.02, W2 + 0.1)) + 0.001);
@@ -1853,7 +2809,13 @@ export default function BuildStage() {
pos.setXYZ(0, j3Plus.x, j3Plus.y, j3Plus.z - 0.9);
pos.setXYZ(1, j4Plus.x, j4Plus.y, j4Plus.z - 0.9);
pos.needsUpdate = true;
- kit.dash.computeLineDistances();
+ // The dashes' distances along it, written in place. (computeLineDistances
+ // makes a new attribute every call, and three a new buffer for each one
+ // it draws โ one a frame for as long as the line was on screen, and one
+ // more on every visit, none of them ever let go.)
+ const along = kit.dash.geometry.getAttribute("lineDistance") as THREE.BufferAttribute;
+ along.setX(1, Math.hypot(j4Plus.x - j3Plus.x, j4Plus.y - j3Plus.y, j4Plus.z - j3Plus.z));
+ along.needsUpdate = true;
const lm = kit.dash.material as THREE.LineDashedMaterial;
lm.opacity += ((plusOn ? 1 : 0) - lm.opacity) * Math.min(1, dt * 6);
kit.dash.visible = lm.opacity > 0.01;
@@ -1872,7 +2834,7 @@ export default function BuildStage() {
return local(V((pr.min.x + pr.max.x) / 2, pr.max.y, (pr.min.z + pr.max.z) / 2));
};
// What came off the board (gather-2), named until the bench is left for the board.
- if (t >= G2 + 0.5 && t < at("gather-4")) {
+ if (t >= ARRIVE2.named && t < at("gather-4")) {
// Above the panel's far edge, so the pill covers nothing on its back.
tags.set("gPanel", V(PANEL_BENCH.p.x, PANEL_BENCH.p.y + 0.9, PANEL_BENCH.p.z - 8));
// On a narrow screen the screws lie at the stage's bottom edge, under the card: no tag there.
@@ -1895,9 +2857,9 @@ export default function BuildStage() {
tags.set("c11p", local(V(PADS.C11[0][0], 0.0017, PADS.C11[0][1] + 0.006)));
tags.set("c11m", local(V(PADS.C11[1][0], 0.0017, PADS.C11[1][1] + 0.006)));
}
- if (t >= S4 + 0.07 && t < S4 + 0.26) tags.set("wrong", local(V(SW_CENTRES[0].x, 0.03, SW_CENTRES[0].z)));
+ if (t >= S4 + 0.06 && t < S4 + 0.19) tags.set("wrong", local(V(SW_CENTRES[0].x, 0.03, SW_CENTRES[0].z)));
// Which side is which, while the joints are made and where the step holds.
- if (t >= S4 + 0.72 && t < S4 + 0.89) tags.set("swPins", local(V(0, 0.004, SW_CENTRES[0].z - 0.004)));
+ if (t >= S4 + 0.63 && t < S4 + 0.89) tags.set("swPins", local(V(0, 0.004, SW_CENTRES[0].z - 0.004)));
if (t >= S4 + 0.985 && t < C1) tags.set("swBodies", local(V(0, -0.027, (SW_CENTRES[0].z + SW_CENTRES[2].z) / 2)));
// The panel's IN header, wherever the panel is: while it is stood up and seated (case-1), and for the ribbon (wire-1).
if ((t >= C1 + 0.26 && t < C2) || (t >= W1 && t < W2)) tags.set("in", V().copy(PANEL_IN).sub(PANEL_CENTRE).applyQuaternion(kit.panel.group.quaternion).add(kit.panel.group.position));
@@ -1922,6 +2884,8 @@ export default function BuildStage() {
const facing = toCam.dot(tmp.v2.set(0, 1, 0).applyQuaternion(boardPose.q));
if (facing > 0.45) tags.set("usb", mark);
}
+ // The guide has been left: the build is being run to an end, and nothing in it is named on the way.
+ if (!onPage) tags.clear();
const els = tagEls.current;
for (const def of TAGS) {
const el = els[def.key];
@@ -1944,6 +2908,35 @@ export default function BuildStage() {
placeTag(el.pill, state.camera, size, wp, def.r, def.side, 7);
}
}
+
+ // โโ the parts under the hand โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+ //
+ // Last, over everything the timeline has placed (touch.ts): the part
+ // under the pointer, or the one the parts list points at, lifts a hair
+ // and is named. Only what is out in the open at this point of the build:
+ // the board's parts wherever they are, the rest while they lie on the mat.
+ {
+ const tf = touchFrame;
+ tf.t = t;
+ tf.on = onPage && !finished && !going && t < WHOLE_AGAIN;
+ touch.frame({
+ camera: state.camera,
+ size,
+ dt,
+ on: tf.on,
+ reduced,
+ // The two steps with the parts list on their card (scenes/build.ts: gather-1, gather-2).
+ card: s.build === "gather-1" || s.build === "gather-2",
+ occluders: tf.occluders,
+ hold: handHold(stageFocus.r),
+ live: touchLive,
+ named: touchNamed,
+ });
+ }
+
+ // Off the stage, once the guide has been left and the device stands whole
+ // (the cleanup above gives Device its objects back as they are now).
+ if (handBack) useGuideStore.getState().setBuildLive(false);
});
return (
@@ -1956,6 +2949,8 @@ export default function BuildStage() {
// The power bank: in its tray (the tray's inside, layout.ts TRAY, with the
// bank's 1.5-unit thickness against the tray's back), and stood in front of
// it. Its USB-A port is in its top end, 7.2 above its centre.
+const PLUG_GO = F3 + 0.65;
+const PLUG_HOME = F3 + 0.76;
const BANK_IN: Pose = { p: V(8.0, 7.62, -0.78), q: new THREE.Quaternion() };
const BANK_FRONT: Pose = { p: V(8.0, 7.4, 6.6), q: new THREE.Quaternion() };
const PORT_IN = V(8.0, 14.82, -0.78);
@@ -1989,6 +2984,15 @@ const PLUG_FLAT = qx(-Math.PI / 2);
const POWER_CARRY_Z = -2.7;
const POWER_RISE = [0, 0, 0, 0, 0.3, 1.2, 1.2] as const;
+/** For building the cut materials' shaders ahead of their first draw (warmStep): nothing to draw, and a plane that cuts none of it. */
+const NOTHING = new THREE.Scene();
+const UNCUT = new THREE.Plane(new THREE.Vector3(0, -1, 0), 1e6);
+
+/** The mat the four print plates stand on: its middle (the plates' own, layout.ts) and its size, a few centimetres more than the plates all round. */
+const PLATES_GROUND = { x: 0, z: -48, w: 66, d: 64 } as const;
+/** How far out from a plate's edge its shade on that mat reaches. */
+const PLATE_SHADE = 3.2;
+
// How far the plug is out of the bank, shown (check-3's power cycle eases it).
const plugTrack = { current: { out: 0 } };
diff --git a/web/src/components/guide/stage/build/beats.ts b/web/src/components/guide/stage/build/beats.ts
index 9a3cf9c3..f127a440 100644
--- a/web/src/components/guide/stage/build/beats.ts
+++ b/web/src/components/guide/stage/build/beats.ts
@@ -10,15 +10,19 @@
// step's own motion once at its own pace and holds its end.
//
// The ids are the storyboard's step ids. `seconds` is how long the beat's
-// own motion takes at its own pace. There is no solder-5 and no wire-3: the
+// own motion takes at its own pace. A beat whose step has the camera come a
+// long way โ from the bench to behind the case, from behind it to the front โ
+// keeps what it is about out of its first second and a bit: the camera is
+// still arriving then (its springs take about that long), and the reader
+// would see the end of something that had already happened. There is no solder-5 and no wire-3: the
// build has no multimeter checks, so solder-4 is followed by case-1 and
// wire-2 by firmware-1. Every beat but "opening" and "next" is one step of
// the script, and the script uses every one (build.test.ts).
export const BEATS = [
["opening", 1],
- ["gather-1", 4.5],
- ["gather-2", 3.2],
+ ["gather-1", 5],
+ ["gather-2", 4],
["gather-3", 1],
["gather-4", 1.6],
["print-1", 3.4],
@@ -30,11 +34,11 @@ export const BEATS = [
["solder-3", 4.6],
["solder-4", 8.8],
["case-1", 5],
- ["case-2", 5.6],
+ ["case-2", 6.6],
["case-3", 6.4],
- ["case-4", 3],
- ["case-5", 5.2],
- ["wire-1", 4.4],
+ ["case-4", 3.6],
+ ["case-5", 6],
+ ["wire-1", 5],
["wire-2", 5],
["firmware-1", 2.2],
// The DevKit's travel round the case and onto its pins is Device's (it is
@@ -64,6 +68,21 @@ export function at(id: BuildBeat, phase = 0): number {
return (INDEX.get(id) ?? 0) + phase;
}
+/**
+ * The opening's device is gone by here: it goes over the first sixth of
+ * gather-1, as the bench comes up (BuildStage). Until then it may be standing
+ * apart โ the hub's answer to Build, kept through Build's opening
+ * (stage/Explode) โ and from here on nothing of it is on stage.
+ */
+export const OPENING_GONE = at("gather-1", 0.17);
+/**
+ * Up to here nothing that comes apart is on stage at all (the case is not
+ * printed yet, the panel not in it): scrolling back up to the opening, the
+ * device is put apart again while it cannot be seen, and fades back in as it
+ * was left.
+ */
+export const OPENING_UNSEEN = at("print-1");
+
export function beatSeconds(i: number): number {
return BEATS[Math.max(0, Math.min(BEATS.length - 1, i))][1];
}
diff --git a/web/src/components/guide/stage/build/build.test.ts b/web/src/components/guide/stage/build/build.test.ts
index c83ba14f..113dfb00 100644
--- a/web/src/components/guide/stage/build/build.test.ts
+++ b/web/src/components/guide/stage/build/build.test.ts
@@ -5,9 +5,14 @@ import { BEATS, beatIndex, beatSeconds, beatStill, clamp01, span } from "./beats
import { BUILD_STEPS } from "./script";
import { PADS, PAD_COUNT } from "./pads";
import { BOARD_WORK, CABLE_HOLE, PANEL_CENTRE, PANEL_IN, PANEL_OUT, PANEL_POWER, SCREW_HOLES } from "./layout";
-import { BUILD_VIEWS } from "./views";
+import { BUILD_VIEWS, settleIn } from "./views";
+import { ease, fall, glide, grow, land, latch, past, press, reach, rock, setDown, swing, windUp } from "./motion";
+import { footprint, foldedRibbon } from "./props";
+import * as THREE from "three";
import { VIEWS } from "../views";
import { BUILD_SCENES } from "../../scenes/build";
+import { BOM_FILE, bomKey, parseBom } from "../../build/bom";
+import { TOUCH_KEYS } from "./touchState";
// The build stage's contract with the Build guide's script (scenes/build.ts):
// every beat has a ready step that names itself and a view the camera knows,
@@ -137,6 +142,99 @@ describe("build stage", () => {
expect(stage).not.toMatch(/\bprobes?\b|\bmeter\b|multimeter/i);
});
+ it("moves every part from its start to exactly its end, whatever the timeline does outside the move", () => {
+ // span() clamps only through its ease (above): each of these must hold its
+ // ends for any input, or a part keeps going after its move is over.
+ const rising = { glide, reach, ease, fall, press, past, swing, windUp, grow };
+ for (const [name, f] of Object.entries(rising)) {
+ expect(f(0), name).toBeCloseTo(0, 6);
+ expect(f(1), name).toBeCloseTo(1, 6);
+ expect(f(-3), name).toBeCloseTo(0, 6);
+ expect(f(7), name).toBeCloseTo(1, 6);
+ }
+ const falling = { land, setDown, latch };
+ for (const [name, f] of Object.entries(falling)) {
+ expect(f(0), name).toBeCloseTo(1, 6);
+ expect(f(1), name).toBeCloseTo(0, 6);
+ expect(f(-3), name).toBeCloseTo(1, 6);
+ expect(f(7), name).toBeCloseTo(0, 6);
+ }
+ expect(rock(0)).toBeCloseTo(1, 6);
+ expect(rock(1)).toBeCloseTo(0, 6);
+ });
+
+ it("never pushes a part that seats against another past its seat, or under the mat", () => {
+ // A press ends against the part behind it; a part that lands, lands ON
+ // the mat; a cover shuts and no further (it swung on through the ribbon).
+ let last = 0;
+ for (let i = 0; i <= 400; i++) {
+ const x = i / 400;
+ const p = press(x);
+ expect(p).toBeLessThanOrEqual(1 + 1e-9);
+ expect(p).toBeGreaterThanOrEqual(last - 1e-9);
+ last = p;
+ expect(land(x)).toBeGreaterThanOrEqual(0);
+ expect(setDown(x)).toBeGreaterThanOrEqual(0);
+ expect(latch(x)).toBeGreaterThanOrEqual(0);
+ expect(latch(x)).toBeLessThanOrEqual(1);
+ // The ones that do go past their end go a little, and come back.
+ expect(past(x)).toBeLessThan(1.05);
+ expect(swing(x)).toBeLessThan(1.04);
+ expect(swing(x)).toBeGreaterThan(-0.04);
+ }
+ });
+
+ it("bends the ribbon and puts it back exactly as it is fitted", () => {
+ const r = foldedRibbon(5.6, 24.2, -1, -3.85, 28.5, -0.6);
+ const rest = Array.from(r.cable.getAttribute("position").array);
+ r.bend(3.2, 3.2, 3.2, new THREE.Vector3(0, -0.9, 0));
+ const bent = Array.from(r.cable.getAttribute("position").array);
+ expect(bent).not.toEqual(rest);
+ // Held out by the same amount everywhere, no part of it is left behind.
+ expect(Math.max(...bent.filter((_, i) => i % 3 === 2).map((z, i) => z - rest[i * 3 + 2]))).toBeCloseTo(-3.2, 5);
+ // Its ends carry the plugs: J1's end hangs the whole sag, IN's (the short run) less.
+ expect(r.ends[0].y).toBeCloseTo(-0.9, 6);
+ expect(r.ends[1].y).toBeGreaterThan(-0.9);
+ expect(r.ends[0].z).toBeCloseTo(-3.2, 6);
+ r.bend(0, 0, 0);
+ expect(Array.from(r.cable.getAttribute("position").array)).toEqual(rest);
+ expect(r.ends[0].length()).toBe(0);
+ });
+
+ it("finds a printed part's outline on its plate", () => {
+ const box = new THREE.BoxGeometry(4, 1, 2);
+ box.translate(10, 0.5, -6);
+ const outline = footprint(box, 16, 0);
+ for (const [x, z] of outline) {
+ expect(Math.abs(Math.abs(x - 10) - 2) < 1e-6 || Math.abs(Math.abs(z + 6) - 1) < 1e-6).toBe(true);
+ }
+ });
+
+ it("leaves every view as authored once the camera has settled in", () => {
+ const before = Object.fromEntries(Object.entries(BUILD_VIEWS).map(([k, v]) => [k, { dir: v.dir.clone(), fill: v.fill }]));
+ settleIn("boardF", 1);
+ expect(BUILD_VIEWS.boardF.fill).toBeLessThan(before.boardF.fill);
+ expect(BUILD_VIEWS.boardF.dir.angleTo(before.boardF.dir)).toBeGreaterThan(0.01);
+ // The step's end, and another step's view: both put it back.
+ settleIn("boardF", 0);
+ expect(BUILD_VIEWS.boardF.dir.angleTo(before.boardF.dir)).toBeLessThan(1e-9);
+ settleIn("boardF", 1);
+ settleIn("caseBack", 0.5);
+ expect(BUILD_VIEWS.boardF.dir.angleTo(before.boardF.dir)).toBeLessThan(1e-9);
+ expect(BUILD_VIEWS.boardF.fill).toBe(before.boardF.fill);
+ settleIn(null, 0);
+ for (const [k, v] of Object.entries(BUILD_VIEWS)) {
+ expect(v.dir.angleTo(before[k].dir), k).toBeLessThan(1e-9);
+ expect(v.fill, k).toBe(before[k].fill);
+ }
+ // The views that look through a gap never turn (case-3, above): only in.
+ for (const k of ["leadBack", "leadHole", "leadJ4", "terminalsBack"] as const) {
+ settleIn(k, 1);
+ expect(BUILD_VIEWS[k].dir.angleTo(before[k].dir), k).toBeLessThan(1e-9);
+ }
+ settleIn(null, 0);
+ });
+
it("solders every through-hole pad of the v3.9 board, and screws the panel at twelve slots", () => {
const counts = Object.fromEntries(Object.entries(PADS).map(([k, v]) => [k, v.length]));
expect(counts).toEqual({ U1: 44, J1: 16, J3: 2, J4: 2, C11: 2, SW1: 7, SW2: 7, SW3: 7, SW4: 7 });
@@ -144,3 +242,12 @@ describe("build stage", () => {
expect(SCREW_HOLES).toHaveLength(12);
});
});
+
+// The parts under the hand (touch.ts) go by their line in the parts list.
+describe("the parts that can be touched", () => {
+ it("are the BOM's lines, every one and no other", () => {
+ const csv = readFileSync(path.resolve(__dirname, "../../../../../..", BOM_FILE), "utf8");
+ const lines = parseBom(csv).map(bomKey);
+ expect([...TOUCH_KEYS].sort()).toEqual([...lines].sort());
+ });
+});
diff --git a/web/src/components/guide/stage/build/focus.ts b/web/src/components/guide/stage/build/focus.ts
new file mode 100644
index 00000000..3779b4b1
--- /dev/null
+++ b/web/src/components/guide/stage/build/focus.ts
@@ -0,0 +1,15 @@
+import * as THREE from "three";
+
+/**
+ * What the build's current step is about, as a point on the stage: the joint
+ * under the iron, the screw being driven, the plug going in. World units (the
+ * camera's), written by BuildStage every frame it runs; `on` is false when
+ * the build is not on stage or the step has no one subject (the whole bench,
+ * the finished device) โ then the camera's own target is the thing to look at.
+ * `size` is roughly how big the subject is, world units (a joint 0.02, the
+ * panel 3).
+ *
+ * For anything that wants to know where the eye should be: depth of field, a
+ * light, a vignette. Nothing on the build stage reads it back.
+ */
+export const buildFocus = { on: false, world: new THREE.Vector3(), size: 1 };
diff --git a/web/src/components/guide/stage/build/motion.ts b/web/src/components/guide/stage/build/motion.ts
new file mode 100644
index 00000000..ac2c7052
--- /dev/null
+++ b/web/src/components/guide/stage/build/motion.ts
@@ -0,0 +1,161 @@
+import { clamp01 } from "./beats";
+
+// How things move on the build stage. Every curve here takes how far through
+// a move the timeline is (0โฆ1, clamped โ beats.ts span() relies on that) and
+// says how far the part has got; nothing keeps state, so a step reached any
+// way, forward or back, is the same picture.
+//
+// The names say what the part is doing, not the maths:
+//
+// glide leaves gently, arrives gently โ a part carried through the air
+// reach quick off the mark, a long slow arrival โ a hand bringing
+// something up to where it must be lined up
+// windUp leans back a little before it goes โ a part picked up
+// past a hair beyond its place and back โ only where there is air
+// behind the place (a turn in a holder, a part held in the hand)
+// press in until it meets the fit, a breath, then pushed home with a
+// click โ never past the end: there is a part behind it
+// land height above the mat for a part let go just over it: down,
+// one small rebound, a smaller one, still
+// setDown height for a heavy part lowered onto the mat: no bounce
+// latch a cover swinging shut: onto the catch, a breath, pressed home
+//
+// The amounts are sized in millimetres on the part, not as a share of the
+// travel: a rebound is a couple of millimetres whether the part fell thirty
+// or three hundred.
+
+/** Cubic ease in and out. */
+export const glide = (x: number) => {
+ const c = clamp01(x);
+ return c < 0.5 ? 4 * c * c * c : 1 - Math.pow(-2 * c + 2, 3) / 2;
+};
+
+/** Quintic ease out: quick away, a long arrival. */
+export const reach = (x: number) => 1 - Math.pow(1 - clamp01(x), 5);
+
+/** Cubic ease out. */
+export const ease = (x: number) => 1 - Math.pow(1 - clamp01(x), 3);
+
+/** Cubic ease in: slow away, quick at the end (something let go). */
+export const fall = (x: number) => {
+ const c = clamp01(x);
+ return c * c * c;
+};
+
+/**
+ * Leans back by `back` (a share of the travel) before it goes, then glides.
+ * Ends exactly on 1.
+ */
+export function windUp(x: number, back = 0.045) {
+ const c = clamp01(x);
+ const go = glide((c - 0.12) / 0.88);
+ // The lean is over by a quarter of the way, and is gone once the part is travelling.
+ const lean = Math.sin(Math.PI * clamp01(c / 0.26));
+ return go - back * lean * (1 - go);
+}
+
+/**
+ * A hair past its place and back (`over` of the travel, at about four fifths
+ * of the way). For a turn, or a part held in the air: never for one that
+ * seats against another.
+ */
+export function past(x: number, over = 0.03) {
+ const c = clamp01(x);
+ // Glides to its place by 0.78; the excursion is one soft lobe after it.
+ const go = glide(c / 0.78);
+ const s = clamp01((c - 0.6) / 0.4);
+ return go + over * Math.sin(Math.PI * s) * (1 - s) * 1.72;
+}
+
+/** Leans back, goes, arrives a hair past and settles: a board turned over in its holder. */
+export function swing(x: number, back = 0.03, over = 0.025) {
+ const c = clamp01(x);
+ const go = glide((c - 0.1) / 0.72);
+ const lean = Math.sin(Math.PI * clamp01(c / 0.24));
+ const s = clamp01((c - 0.62) / 0.38);
+ return go - back * lean * (1 - go) + over * Math.sin(Math.PI * s) * (1 - s) * 1.72;
+}
+
+/**
+ * Pushed in against a fit: `meet` of the way freely, a breath there, then the
+ * rest in one short push that stops dead (the click). Never past 1.
+ */
+export function press(x: number, meet = 0.8) {
+ const c = clamp01(x);
+ if (c < 0.56) return meet * reach(c / 0.56) * 0.985;
+ // The breath: it creeps, it does not stop โ a part held against a fit is never quite still.
+ if (c < 0.72) return meet * (0.985 + 0.015 * ((c - 0.56) / 0.16));
+ // Home: it gives, faster and faster, and stops dead on its seat.
+ const u = clamp01((c - 0.72) / 0.2);
+ return meet + (1 - meet) * u * u;
+}
+
+/**
+ * Height above the mat, as a share of the drop, for a part let go: down under
+ * its own weight, a rebound of `bounce` (a share of the drop) and a second a
+ * quarter of that, then still. 1 โ 0, never below.
+ */
+export function land(x: number, bounce = 0.08) {
+ const c = clamp01(x);
+ const hit = 0.56;
+ if (c < hit) {
+ const u = c / hit;
+ return 1 - u * u;
+ }
+ // Never a hair under the mat, not even by a rounding error.
+ const hop = (u: number) => Math.max(0, 4 * u * (1 - u));
+ if (c < 0.84) return bounce * hop((c - hit) / (0.84 - hit));
+ return bounce * 0.24 * hop((c - 0.84) / 0.16);
+}
+
+/** Height for a heavy part lowered onto the mat: let down, slower and slower, no rebound. 1 โ 0. */
+export const setDown = (x: number) => 1 - reach(x);
+
+/**
+ * How far over a part still leans as it lands (1 โ 0, with a rock the other
+ * way and back after it touches): multiply a small angle by it.
+ */
+export function rock(x: number) {
+ const c = clamp01(x);
+ const hit = 0.56;
+ if (c < hit) return 1 - glide(c / hit);
+ const s = (c - hit) / (1 - hit);
+ return -0.32 * Math.sin(Math.PI * 2 * s) * (1 - s) * (1 - s);
+}
+
+/** How big a part is as it arrives: from nothing, full size before it touches. */
+export const grow = (x: number) => ease(clamp01(x) / 0.5);
+
+/**
+ * A cover swinging shut on a hinge, as the angle still open (1 โ 0): it
+ * swings to, comes to rest on its catch (`catchAt` still open), and is
+ * pressed home. Never below 0: there is a case behind it.
+ */
+export function latch(x: number, catchAt = 0.035) {
+ const c = clamp01(x);
+ if (c < 0.66) {
+ const u = c / 0.66;
+ // Falls shut faster and faster, then the catch takes it.
+ return catchAt + (1 - catchAt) * (1 - glide(u));
+ }
+ if (c < 0.8) return catchAt;
+ return catchAt * (1 - reach((c - 0.8) / 0.14));
+}
+
+/** A damped swing about rest, for something hanging that was just let go or brought to a stop: `s` is time since, in swings. 0 before. */
+export function sway(s: number, swings = 2.5, decay = 3) {
+ if (s <= 0) return 0;
+ return Math.sin(Math.PI * 2 * s * swings) * Math.exp(-decay * s * swings);
+}
+
+/** A shake of the head โ three quick turns, dying away โ over 0โฆ1; 0 outside. */
+export function shake(x: number) {
+ if (x <= 0 || x >= 1) return 0;
+ return Math.sin(Math.PI * 6 * x) * (1 - x);
+}
+
+/** A small fixed scatter for index `i` (โ1โฆ1): the same every time, so the build is the same build. */
+export function scatter(i: number, salt = 0) {
+ const s = Math.sin((i + 1) * 12.9898 + salt * 78.233) * 43758.5453;
+ return (s - Math.floor(s)) * 2 - 1;
+}
diff --git a/web/src/components/guide/stage/build/props.ts b/web/src/components/guide/stage/build/props.ts
index defd249c..97d383f8 100644
--- a/web/src/components/guide/stage/build/props.ts
+++ b/web/src/components/guide/stage/build/props.ts
@@ -20,6 +20,21 @@ export function screwGeometry() {
return g;
}
+/**
+ * The cross in the screw's head (the same frame as screwGeometry): two shallow
+ * bars across the top of the dome, drawn dark. A lathed head is the same from
+ * every side โ without this a screw being driven does not show that it turns.
+ */
+export function screwRecessGeometry() {
+ const bar = (turn: number) => {
+ const g = new THREE.BoxGeometry(0.4, 0.03, 0.075);
+ g.rotateY(turn);
+ g.translate(0, 1.278, 0);
+ return g;
+ };
+ return mergeGeometries([bar(0), bar(Math.PI / 2)]);
+}
+
/** The encoder's washer, axis +y, sitting on y 0. */
export function washerGeometry() {
return new THREE.LatheGeometry([v2(0.37, 0), v2(0.53, 0), v2(0.53, 0.05), v2(0.37, 0.05), v2(0.37, 0)], 28);
@@ -351,77 +366,91 @@ export function idcPlug(along: "x" | "y") {
* `y0`; the upright run from the fold to y `y1`, rising to z `z1` at IN's
* plug. 16 wires at 1.27 mm: 20.3 mm wide; wire 1's red stripe is the flat
* run's top edge, which the fold turns to the upright run's โx edge.
+ *
+ * It is a cable, and is handled like one: each run is cut into strips along
+ * its length, and `bend` moves them โ how far out of its seat each end and
+ * the fold between them are held (toward โz, model units), and how far the
+ * runs hang from the fold under their own weight (`sag`, in the ribbon's own
+ * frame). bend(0, 0, 0) is the ribbon as fitted. The ends carry the plugs:
+ * `ends` is where each one is, as an offset from its fitted place.
*/
export function foldedRibbon(x0: number, y0: number, z0: number, inX: number, y1: number, z1: number) {
const w = 2.03;
const t = 0.09;
const hw = w / 2;
- const pos: number[] = [];
- const idx: number[] = [];
- /** A flat quad strip aโbโcโd (counter-clockwise seen from โz), given thickness toward +z. */
- const slab = (pts: [number, number, number][], into: { pos: number[]; idx: number[] }) => {
- const base = into.pos.length / 3;
- for (const [x, y, z] of pts) into.pos.push(x, y, z);
- for (const [x, y, z] of pts) into.pos.push(x, y, z + t);
- const n = pts.length;
- // back face (toward โz), front face, and the edges
- for (let i = 1; i < n - 1; i++) into.idx.push(base, base + i + 1, base + i, base + n, base + n + i, base + n + i + 1);
+ const s = 0.13; // the stripe's width
+ const FLAT = 14; // strips along the flat run
+ const UP = 8; // and along the upright one
+ type Strip = { pos: number[]; w1: number[]; w2: number[] };
+ const soft = (x: number) => x * x * (3 - 2 * x);
+ /** A run between two edges (each a start and an end point), in `n` strips, `t` thick toward +z; `weight` says which end's it is. */
+ const run = (a0: number[], a1: number[], b0: number[], b1: number[], n: number, which: 1 | 2, into: Strip) => {
+ const at = (p0: number[], p1: number[], f: number, dz: number) => [p0[0] + (p1[0] - p0[0]) * f, p0[1] + (p1[1] - p0[1]) * f, p0[2] + (p1[2] - p0[2]) * f + dz];
+ const quad = (p: number[][], f: number[]) => {
+ // Two triangles, the weight of each corner beside it.
+ for (const k of [0, 1, 2, 0, 2, 3]) {
+ into.pos.push(...p[k]);
+ // Flat run: 1 at J1's end (f 0), 0 at the fold. Upright: 0 at the fold (f 0), 1 at IN's end.
+ const wt = which === 1 ? 1 - soft(f[k]) : soft(f[k]);
+ into.w1.push(which === 1 ? wt : 0);
+ into.w2.push(which === 2 ? wt : 0);
+ }
+ };
for (let i = 0; i < n; i++) {
- const j = (i + 1) % n;
- into.idx.push(base + i, base + j, base + n + j, base + i, base + n + j, base + n + i);
+ const f0 = i / n;
+ const f1 = (i + 1) / n;
+ // back (toward โz), front, and the two long edges
+ quad([at(a0, a1, f0, 0), at(b0, b1, f0, 0), at(b0, b1, f1, 0), at(a0, a1, f1, 0)], [f0, f0, f1, f1]);
+ quad([at(a0, a1, f0, t), at(a0, a1, f1, t), at(b0, b1, f1, t), at(b0, b1, f0, t)], [f0, f1, f1, f0]);
+ quad([at(a0, a1, f0, 0), at(a0, a1, f1, 0), at(a0, a1, f1, t), at(a0, a1, f0, t)], [f0, f1, f1, f0]);
+ quad([at(b0, b1, f0, 0), at(b0, b1, f0, t), at(b0, b1, f1, t), at(b0, b1, f1, 0)], [f0, f0, f1, f1]);
}
};
- const grey = { pos, idx };
- const red = { pos: [] as number[], idx: [] as number[] };
- const s = 0.13; // the stripe's width
+ const grey: Strip = { pos: [], w1: [], w2: [] };
+ const red: Strip = { pos: [], w1: [], w2: [] };
// The flat run: from J1's plug to the fold line (inX + hw, y0 โ hw) โ (inX โ hw, y0 + hw).
- slab(
- [
- [x0, y0 - hw, z0],
- [inX + hw, y0 - hw, z0],
- [inX - hw + s, y0 + hw - s, z0],
- [x0, y0 + hw - s, z0],
- ],
- grey,
- );
- slab(
- [
- [x0, y0 + hw - s, z0],
- [inX - hw + s, y0 + hw - s, z0],
- [inX - hw, y0 + hw, z0],
- [x0, y0 + hw, z0],
- ],
- red,
- );
+ run([x0, y0 - hw, z0], [inX + hw, y0 - hw, z0], [x0, y0 + hw - s, z0], [inX - hw + s, y0 + hw - s, z0], FLAT, 1, grey);
+ run([x0, y0 + hw - s, z0], [inX - hw + s, y0 + hw - s, z0], [x0, y0 + hw, z0], [inX - hw, y0 + hw, z0], FLAT, 1, red);
// The upright run, lying on the flat one at the fold (behind it: toward โz).
const zf = z0 - t;
- slab(
- [
- [inX - hw + s, y0 + hw - s, zf],
- [inX + hw, y0 - hw, zf],
- [inX + hw, y1, z1],
- [inX - hw + s, y1, z1],
- ],
- grey,
- );
- slab(
- [
- [inX - hw, y0 + hw, zf],
- [inX - hw + s, y0 + hw - s, zf],
- [inX - hw + s, y1, z1],
- [inX - hw, y1, z1],
- ],
- red,
- );
- const make = (d: { pos: number[]; idx: number[] }) => {
+ run([inX - hw + s, y0 + hw - s, zf], [inX - hw + s, y1, z1], [inX + hw, y0 - hw, zf], [inX + hw, y1, z1], UP, 2, grey);
+ run([inX - hw, y0 + hw, zf], [inX - hw, y1, z1], [inX - hw + s, y0 + hw - s, zf], [inX - hw + s, y1, z1], UP, 2, red);
+ const make = (d: Strip) => {
const g = new THREE.BufferGeometry();
- g.setAttribute("position", new THREE.Float32BufferAttribute(d.pos, 3));
- g.setIndex(d.idx);
- const flat = g.toNonIndexed();
- flat.computeVertexNormals();
- return flat;
+ g.setAttribute("position", new THREE.BufferAttribute(new Float32Array(d.pos), 3).setUsage(THREE.DynamicDrawUsage));
+ g.computeVertexNormals();
+ return { geometry: g, rest: new Float32Array(d.pos), w1: new Float32Array(d.w1), w2: new Float32Array(d.w2) };
+ };
+ const parts = [make(grey), make(red)];
+ const ends = [new THREE.Vector3(), new THREE.Vector3()];
+ let bent = false;
+ /** How far the upright run hangs for a given hang of the flat one: it is a third as long. */
+ const SHORT = 0.3;
+ const bend = (e1: number, fold: number, e2: number, sag?: THREE.Vector3) => {
+ const sx = sag?.x ?? 0;
+ const sy = sag?.y ?? 0;
+ const sz = sag?.z ?? 0;
+ const still = e1 === 0 && fold === 0 && e2 === 0 && sx === 0 && sy === 0 && sz === 0;
+ ends[0].set(sx, sy, sz - e1);
+ ends[1].set(sx * SHORT, sy * SHORT, sz * SHORT - e2);
+ if (still && !bent) return;
+ bent = !still;
+ for (const p of parts) {
+ const pos = p.geometry.getAttribute("position") as THREE.BufferAttribute;
+ const arr = pos.array as Float32Array;
+ for (let i = 0, k = 0; k < p.w1.length; i += 3, k++) {
+ const a = p.w1[k];
+ const b = p.w2[k];
+ const hang = a + b * SHORT;
+ arr[i] = p.rest[i] + sx * hang;
+ arr[i + 1] = p.rest[i + 1] + sy * hang;
+ arr[i + 2] = p.rest[i + 2] + sz * hang - (fold + (e1 - fold) * a + (e2 - fold) * b);
+ }
+ pos.needsUpdate = true;
+ p.geometry.computeVertexNormals();
+ }
};
- return { cable: make(grey), stripe: make(red) };
+ return { cable: parts[0].geometry, stripe: parts[1].geometry, bend, ends };
}
/** The panel's power lead's plug (VH, 4-way housing), in its own frame: mating face at z 0, the wires leaving its back at z โ0.9. */
@@ -450,15 +479,19 @@ export function usbPlug() {
return { shell, boot };
}
-/** A soldering iron: tip at the origin, the iron running up +y. */
+/**
+ * A soldering iron: tip at the origin, the iron running up +y. Three turned
+ * parts, each a lathe profile (radius, height): the plated tip, a cone a
+ * hair blunt on its shank; the heater's steel barrel, with the collar that
+ * holds the tip and the nut that holds the barrel; and the handle โ a guard
+ * ahead of the fingers, a waist for them, a rounded end.
+ */
export function iron() {
- const tip = new THREE.CylinderGeometry(0.03, 0.12, 0.9, 12);
- tip.translate(0, 0.45, 0);
- const barrel = new THREE.CylinderGeometry(0.2, 0.2, 2.6, 16);
- barrel.translate(0, 0.9 + 1.3, 0);
- const grip = new THREE.CylinderGeometry(0.42, 0.36, 4.6, 20);
- grip.translate(0, 3.5 + 2.3, 0);
- return { metal: mergeGeometries([tip, barrel]), grip };
+ const lathe = (profile: [number, number][], segments: number) => new THREE.LatheGeometry(profile.map(([r, y]) => new THREE.Vector2(r, y)), segments);
+ const tip = lathe([[0, 0], [0.026, 0.014], [0.082, 0.62], [0.082, 0.96]], 20);
+ const barrel = lathe([[0.082, 0.96], [0.15, 0.96], [0.15, 1.14], [0.112, 1.16], [0.112, 2.96], [0.2, 2.98], [0.2, 3.32], [0.12, 3.34]], 24);
+ const grip = lathe([[0.12, 3.34], [0.3, 3.34], [0.37, 3.46], [0.37, 3.62], [0.27, 3.9], [0.245, 5.2], [0.3, 6.5], [0.3, 7.7], [0.24, 7.96], [0, 8.02]], 28);
+ return { tip, barrel, grip };
}
/** The PCB holder: two posts with jaws, gripping the board's short edges. */
@@ -485,6 +518,76 @@ export function plate() {
return g;
}
+/**
+ * The shade a print plate keeps round its foot, as an alpha map for a square
+ * of ground `margin` wider than the plate all round: close and dark under
+ * the plate's edge, gone a few centimetres out.
+ */
+export function plateShade(margin: number) {
+ const c = document.createElement("canvas");
+ c.width = c.height = 128;
+ const ctx = c.getContext("2d");
+ if (ctx) {
+ ctx.fillStyle = "#000";
+ ctx.fillRect(0, 0, 128, 128);
+ const px = 128 / (PLATE_SIZE + margin * 2);
+ // Twice: a wide soft one, and a tight one where the plate meets the mat.
+ for (const [blur, a] of [
+ [margin * px * 0.8, 0.5],
+ [margin * px * 0.28, 0.8],
+ ]) {
+ ctx.shadowColor = `rgba(255,255,255,${a})`;
+ ctx.shadowBlur = blur;
+ ctx.fillStyle = "#fff";
+ ctx.fillRect(margin * px, margin * px, PLATE_SIZE * px, PLATE_SIZE * px);
+ }
+ }
+ return new THREE.CanvasTexture(c);
+}
+
+/**
+ * The outline of a part as it lies on its print plate, seen from above: the
+ * outermost point of it in each of `n` directions (plate x, z), drawn in a
+ * little โ where the nozzle lays the part's outer wall, near enough.
+ */
+export function footprint(g: THREE.BufferGeometry, n = 28, inset = 0.06): [number, number][] {
+ const pos = g.getAttribute("position");
+ const far = new Float32Array(n).fill(-Infinity);
+ const out: [number, number][] = Array.from({ length: n }, () => [0, 0]);
+ const cos = Array.from({ length: n }, (_, k) => Math.cos((k / n) * Math.PI * 2));
+ const sin = Array.from({ length: n }, (_, k) => Math.sin((k / n) * Math.PI * 2));
+ let cx = 0;
+ let cz = 0;
+ // Every third vertex is plenty for an outline.
+ const step = pos.count > 3000 ? 3 : 1;
+ let count = 0;
+ for (let i = 0; i < pos.count; i += step) {
+ const x = pos.getX(i);
+ const z = pos.getZ(i);
+ cx += x;
+ cz += z;
+ count++;
+ for (let k = 0; k < n; k++) {
+ const d = x * cos[k] + z * sin[k];
+ if (d > far[k]) {
+ far[k] = d;
+ out[k][0] = x;
+ out[k][1] = z;
+ }
+ }
+ }
+ cx /= Math.max(1, count);
+ cz /= Math.max(1, count);
+ for (const p of out) {
+ const dx = cx - p[0];
+ const dz = cz - p[1];
+ const l = Math.hypot(dx, dz) || 1;
+ p[0] += (dx / l) * inset;
+ p[1] += (dz / l) * inset;
+ }
+ return out;
+}
+
/** A coil of cable lying on the mat (a few loose turns). */
export function coil(radius: number, tube: number, turns: number) {
const parts: THREE.BufferGeometry[] = [];
@@ -502,7 +605,7 @@ export function tapeStrip(length: number) {
return new THREE.BoxGeometry(0.9, length, 0.02);
}
-/** A soft round glow for sprites (a solder joint's glint). */
+/** A soft round glow for sprites (a print's nozzle). */
export function glowTexture() {
const c = document.createElement("canvas");
c.width = c.height = 64;
diff --git a/web/src/components/guide/stage/build/script.ts b/web/src/components/guide/stage/build/script.ts
index 3492f20f..83a4ca61 100644
--- a/web/src/components/guide/stage/build/script.ts
+++ b/web/src/components/guide/stage/build/script.ts
@@ -72,18 +72,20 @@ export const BUILD_STEPS: Record = {
// brought over โ J4 on it.
"case-3": { build: "case-3", view: "leadBack", narrowView: "leadHole", narrowLate: { from: 0.52, view: "leadJ4" }, ...dark, esp: 1 },
"case-4": { build: "case-4", view: "caseBackClose", ...dark, esp: 1 },
- "case-5": { build: "case-5", view: "knobs", ...dark, esp: 1 },
+ "case-5": { build: "case-5", view: "shafts", ...dark, esp: 1 },
"wire-1": { build: "wire-1", view: "wireBack", ...dark, esp: 1 },
// On a phone, close on the two terminals: the polarity is the step.
"wire-2": { build: "wire-2", view: "wireBack", narrowView: "terminalsBack", ...dark, esp: 1 },
// Flashing is Play's 01 Flash: the DevKit held up, the cable in its left port.
"firmware-1": { build: "firmware-1", view: "esp", ...dark, esp: 1, cable: 1, flashing: true, espTags: ["usb"] },
"firmware-2": { build: "firmware-2", view: "back", ...dark, esp: 0 },
- "firmware-3": { build: "firmware-3", view: "front", ...lit, esp: 0 },
+ // Opens on the tray (views.ts powerOn) and comes round to the front as the panel lights.
+ "firmware-3": { build: "firmware-3", view: "powerOn", ...lit, esp: 0 },
"check-1": { build: "check-1", view: "knobs", ...lit, esp: 0, labels: true, demo: turnAndClick, period: 5600 },
"check-2": { build: "check-2", view: "screenKnobs", ...lit, esp: 0, labels: true, demo: longPresses, period: 17800 },
"check-3": { build: "check-3", view: "front", ...lit, esp: 0, demo: [{ at: 700, mode: "off" }, { at: 2300, mode: "run" }], period: 5200 },
- "check-4": { build: "check-4", view: "caseBack", ...lit, esp: 0 },
- "check-5": { build: "check-5", view: "front", ...lit, esp: 0 },
+ // From behind, round to the knob side and low: along the back's face as it shuts (views.ts backShut).
+ "check-4": { build: "check-4", view: "backShut", ...lit, esp: 0 },
+ "check-5": { build: "check-5", view: "finish", ...lit, esp: 0 },
next: { build: "next", view: "hero", spin: 0.18, ...lit, esp: 0 },
};
diff --git a/web/src/components/guide/stage/build/touch.ts b/web/src/components/guide/stage/build/touch.ts
new file mode 100644
index 00000000..e15152d9
--- /dev/null
+++ b/web/src/components/guide/stage/build/touch.ts
@@ -0,0 +1,332 @@
+import * as THREE from "three";
+import { hand } from "../hand";
+import { forgetPillSize, placeTag } from "../tags";
+import { cardTouch, partLabel, touchFromStage, touchSpot, type TouchKey } from "./touchState";
+
+// The Build guide's parts under the hand.
+//
+// A mouse over a part on the bench or the board lifts it a hair โ along the
+// way it comes out of its seat: up off the mat, out of its holes โ and names
+// it, as the parts list does (reference and part, in the page's language),
+// and lights its line in the list; a line of the list pointed at does the
+// same from the other side, and the hand's light goes to the part
+// (touchState.ts is what the card and the stage share).
+//
+// It is laid over the build, not part of it. BuildStage puts every part where
+// the timeline has it each frame and then calls `frame` here, which adds the
+// hair to what it finds and remembers what it wrote โ so there is nothing to
+// undo: the next frame starts from the build's own place again. A part the
+// build is carrying is the build's: one that has moved since the last frame
+// is not lifted, not named and not found under the pointer, and neither is
+// one that is not on stage, not yet full size, or behind the case.
+//
+// What is under the pointer is looked for once a pointer move, and no more
+// than every 60 ms: the line through the pointer against each part's box in
+// its own frame โ a dozen boxes โ and only when one is hit, against the
+// meshes that could be standing in front of it (the case, the board).
+// Nothing is looked for under a finger, and nothing lifts for a reader who
+// asked for less motion (the name still comes).
+
+/** How far a part lifts, as it looks on screen, px โ and the least and most of it, in its own units of length (10 mm). */
+const HAIR_PX = 8;
+const HAIR_MIN = 0.1;
+const HAIR_MAX = 0.9;
+/** A part must have lain still this long before it answers, s (a part dropped on the mat rocks a moment). */
+const STILL_S = 0.25;
+/** The pointer is looked under at most this often, ms. */
+const PICK_MS = 60;
+/** โฆand a part that is held is looked at again this often, ms. */
+const HELD_MS = 250;
+/** Moved this far since the last frame (squared, its own units): it is being carried. */
+const MOVED_SQ = 1e-8;
+
+export type TouchPart = {
+ /** Its line's key in the BOM (build/bom.ts bomKey). */
+ key: TouchKey;
+ object: THREE.Object3D;
+ /** What its box is measured from, if not all of `object` (the DevKit's group also holds its cable). */
+ body?: THREE.Object3D;
+ /** Its box in its own frame, if it cannot be measured (the screws are instances). */
+ box?: THREE.Box3;
+ /** The way it lifts, in the frame it is placed in: up off the mat by default. */
+ axis?: (out: THREE.Vector3) => THREE.Vector3;
+ /** Its scale when it is whole (a part still arriving is smaller). */
+ full?: number;
+ /** The stage never writes its place (an InstancedMesh, moved by its instances): this does, outright โ and these with it. */
+ owned?: THREE.Object3D[];
+};
+
+type Item = TouchPart & {
+ box: THREE.Box3;
+ centre: THREE.Vector3;
+ radius: number;
+ base: THREE.Vector3;
+ written: THREE.Vector3;
+ seen: boolean;
+ still: number;
+ lift: number;
+};
+
+export type TouchFrame = {
+ camera: THREE.Camera;
+ size: { width: number; height: number };
+ dt: number;
+ /** The guide is on screen and the build is showing its own parts. */
+ on: boolean;
+ /** No lift: the reader asked for less motion. */
+ reduced: boolean;
+ /** The parts list is on this step: what it points at counts (a line left focused does not follow the reader down the page). */
+ card: boolean;
+ /** This line's part is out in the open at this point of the build. */
+ live: (key: string) => boolean;
+ /** The build is naming this part itself just now (its own tag is up): no second name. */
+ named: (key: string) => boolean;
+ /** What may stand in front of a part: meshes, each with the key of the part it belongs to, if any. */
+ occluders: { mesh: THREE.Object3D; key?: string }[];
+ /** How far in front of the part the hand's light is held, world units. */
+ hold: number;
+};
+
+/** A subtree's box in `frame`'s own coordinates. */
+function boxIn(frame: THREE.Object3D, root: THREE.Object3D): THREE.Box3 {
+ const box = new THREE.Box3();
+ const rel = new THREE.Matrix4();
+ root.traverse((o) => {
+ const m = o as THREE.Mesh;
+ if (!m.isMesh || !m.geometry) return;
+ if (!m.geometry.boundingBox) m.geometry.computeBoundingBox();
+ rel.identity();
+ for (let n: THREE.Object3D | null = m; n && n !== frame; n = n.parent) {
+ n.updateMatrix();
+ rel.premultiply(n.matrix);
+ }
+ box.union(m.geometry.boundingBox!.clone().applyMatrix4(rel));
+ });
+ return box;
+}
+
+function shown(o: THREE.Object3D): boolean {
+ for (let n: THREE.Object3D | null = o; n; n = n.parent) if (!n.visible) return false;
+ return true;
+}
+
+const UP = new THREE.Vector3(0, 1, 0);
+
+export function makeTouch() {
+ let items: Item[] = [];
+ let hovered: Item | null = null;
+ let pill: HTMLDivElement | null = null;
+ let wrap: HTMLDivElement | null = null;
+ let shownLabel = "";
+ const picked = { moves: -1, at: 0 };
+ const ray = new THREE.Ray();
+ const local = new THREE.Ray();
+ const caster = new THREE.Raycaster();
+ const inv = new THREE.Matrix4();
+ const v = new THREE.Vector3();
+ const v2 = new THREE.Vector3();
+ const axis = new THREE.Vector3();
+ const anchor = new THREE.Vector3();
+ const hits: THREE.Intersection[] = [];
+ /** The parts being named this frame. */
+ const naming: Item[] = [];
+
+ const ready = (it: Item, f: TouchFrame) =>
+ f.on && it.still >= STILL_S && f.live(it.key) && shown(it.object) && it.object.scale.x >= (it.full ?? 1) * 0.98;
+
+ /** The part under the pointer, if there is one and nothing stands in front of it. */
+ function pick(f: TouchFrame): Item | null {
+ if (!hand.here || !hand.onStage) return null;
+ v.set(hand.x, -hand.y, 0.5).unproject(f.camera);
+ ray.origin.copy(f.camera.position);
+ ray.direction.copy(v).sub(ray.origin).normalize();
+ let best: Item | null = null;
+ let near = Infinity;
+ for (const it of items) {
+ if (!ready(it, f)) continue;
+ inv.copy(it.object.matrixWorld).invert();
+ local.copy(ray).applyMatrix4(inv);
+ if (!local.intersectBox(it.box, v)) continue;
+ const d = v.applyMatrix4(it.object.matrixWorld).distanceTo(ray.origin);
+ if (d < near) {
+ near = d;
+ best = it;
+ }
+ }
+ if (!best) return null;
+ caster.ray.copy(ray);
+ caster.near = 0;
+ caster.far = near - 0.01;
+ for (const o of f.occluders) {
+ if (o.key === best.key || !shown(o.mesh)) continue;
+ const mat = (o.mesh as THREE.Mesh).material as THREE.Material | undefined;
+ if (mat && mat.transparent && mat.opacity < 0.5) continue;
+ hits.length = 0;
+ caster.intersectObject(o.mesh, false, hits);
+ if (hits.length) return null;
+ }
+ return best;
+ }
+
+ return {
+ /** The pill that names a part, in the stage's own layer of tags. */
+ mount(host: HTMLElement) {
+ wrap = document.createElement("div");
+ wrap.style.cssText = "position:absolute;left:0;top:0;will-change:transform;pointer-events:none;z-index:21";
+ pill = document.createElement("div");
+ pill.className = "guide-knob-tag";
+ pill.dataset.on = "0";
+ pill.style.transform = "translate(-50%, -50%)";
+ wrap.appendChild(pill);
+ host.appendChild(wrap);
+ shownLabel = "";
+ },
+ unmount() {
+ wrap?.remove();
+ wrap = pill = null;
+ },
+ /** The parts that can be touched (BuildStage, once it has the device's objects). */
+ set(parts: TouchPart[]) {
+ items = parts.map((p) => {
+ const box = p.box ?? boxIn(p.object, p.body ?? p.object);
+ return {
+ ...p,
+ box,
+ centre: box.getCenter(new THREE.Vector3()),
+ radius: box.getSize(new THREE.Vector3()).length() / 2,
+ base: new THREE.Vector3(),
+ written: new THREE.Vector3(),
+ seen: false,
+ still: 0,
+ lift: 0,
+ };
+ });
+ hovered = null;
+ },
+ /** Everything as the build has it: nothing lifted, nothing named. */
+ release() {
+ for (const it of items) {
+ if (it.owned) {
+ it.object.position.set(0, 0, 0);
+ for (const w of it.owned) w.position.set(0, 0, 0);
+ } else if (it.seen && it.object.position.equals(it.written)) it.object.position.copy(it.base);
+ it.written.copy(it.object.position);
+ it.lift = 0;
+ it.seen = false;
+ }
+ hovered = null;
+ touchFromStage(null);
+ touchSpot.on = false;
+ if (pill) pill.dataset.on = "0";
+ },
+ /** After the build has placed its parts for this frame. */
+ frame(f: TouchFrame) {
+ if (!items.length) return;
+ // Where the build has each part, and whether it has moved it.
+ for (const it of items) {
+ const p = it.object.position;
+ if (it.owned) {
+ it.still += f.dt;
+ continue;
+ }
+ // Not placed again this frame, it is still where this put it: back to the build's own place first.
+ if (it.seen && p.equals(it.written)) p.copy(it.base);
+ const moved = it.seen ? p.distanceToSquared(it.base) : Infinity;
+ it.base.copy(p);
+ it.seen = true;
+ it.still = moved > MOVED_SQ ? 0 : it.still + f.dt;
+ }
+
+ // Under the pointer: once a move, and not too often.
+ const now = performance.now();
+ // (And now and then while a part is held: the page scrolls and the camera moves under a pointer that does not.)
+ if ((hand.moves !== picked.moves && now - picked.at >= PICK_MS) || (hovered && now - picked.at >= HELD_MS)) {
+ picked.moves = hand.moves;
+ picked.at = now;
+ hovered = pick(f);
+ }
+ if (hovered && !ready(hovered, f)) hovered = null;
+ const stageKey = hovered?.key ?? null;
+ touchFromStage(stageKey);
+ const cardKey = f.card ? cardTouch() : null;
+
+ // The hair.
+ naming.length = 0;
+ for (const it of items) {
+ // Under the pointer, that part alone; from the card, every part of its line.
+ const active = (it === hovered || it.key === cardKey) && ready(it, f);
+ const want = active && !f.reduced ? 1 : 0;
+ if (it.still === 0) it.lift = 0;
+ else {
+ it.lift += (want - it.lift) * (1 - Math.exp(-f.dt * 14));
+ if (want === 0 && it.lift < 0.004) it.lift = 0;
+ }
+ const o = it.object;
+ if (it.lift > 0 || it.owned) {
+ // As far as reads as a hair at this distance.
+ const dist = v.setFromMatrixPosition(o.matrixWorld).distanceTo(f.camera.position);
+ const cam = f.camera as THREE.PerspectiveCamera;
+ const perPx = (2 * dist * Math.tan(THREE.MathUtils.degToRad(cam.fov / 2))) / f.size.height;
+ const unit = v2.setFromMatrixScale(o.parent ? o.parent.matrixWorld : o.matrixWorld).x || 1;
+ const hair = THREE.MathUtils.clamp((HAIR_PX * perPx) / unit, HAIR_MIN, HAIR_MAX) * it.lift;
+ (it.axis ? it.axis(axis) : axis.copy(UP)).multiplyScalar(hair);
+ if (it.owned) {
+ o.position.copy(axis);
+ for (const w of it.owned) w.position.copy(axis);
+ } else o.position.copy(it.base).add(axis);
+ }
+ if (!it.owned) it.written.copy(o.position);
+ // What is named: the one under the pointer; from the card, all of its line together.
+ if (active && (stageKey ? it === hovered : true)) naming.push(it);
+ }
+
+ // The name, and where the hand's light goes for the card's part.
+ touchSpot.on = false;
+ const named = naming.length ? naming[0].key : null;
+ const count = naming.length;
+ let reach = 0;
+ if (named) {
+ anchor.set(0, 0, 0);
+ for (const it of naming) {
+ it.object.updateWorldMatrix(true, false);
+ anchor.add(v.copy(it.centre).applyMatrix4(it.object.matrixWorld));
+ }
+ anchor.multiplyScalar(1 / count);
+ for (const it of naming) {
+ const r = it.radius * v2.setFromMatrixScale(it.object.matrixWorld).x * 0.7;
+ reach = Math.max(reach, v.copy(it.centre).applyMatrix4(it.object.matrixWorld).distanceTo(anchor) * 0.5 + r);
+ }
+ if (named !== stageKey) {
+ // Between the part and the eye, and a little above: it rakes, as in the hand.
+ v.copy(f.camera.position).sub(anchor).normalize();
+ touchSpot.x = anchor.x + v.x * f.hold;
+ touchSpot.y = anchor.y + v.y * f.hold + f.hold * 0.35;
+ touchSpot.z = anchor.z + v.z * f.hold;
+ touchSpot.on = true;
+ }
+ }
+ if (!pill || !wrap) return;
+ const show = named !== null && count > 0 && !f.named(named);
+ if (show) {
+ const label = partLabel(named!);
+ if (label !== shownLabel) {
+ shownLabel = label;
+ pill.textContent = label;
+ forgetPillSize(pill);
+ }
+ v.copy(anchor).project(f.camera);
+ if (v.z > 1) pill.dataset.on = "0";
+ else {
+ const x = (v.x * 0.5 + 0.5) * f.size.width;
+ const y = (-v.y * 0.5 + 0.5) * f.size.height;
+ wrap.style.transform = `translate3d(${x.toFixed(1)}px, ${y.toFixed(1)}px, 0)`;
+ pill.dataset.on = "1";
+ // A line of several parts (the four encoders) is named over the lot.
+ placeTag(pill, f.camera, f.size, anchor, reach, "up", 8);
+ }
+ } else if (pill.dataset.on !== "0") pill.dataset.on = "0";
+ },
+ };
+}
+
+export type Touch = ReturnType;
diff --git a/web/src/components/guide/stage/build/touchState.ts b/web/src/components/guide/stage/build/touchState.ts
new file mode 100644
index 00000000..d31b8094
--- /dev/null
+++ b/web/src/components/guide/stage/build/touchState.ts
@@ -0,0 +1,83 @@
+// The Build guide's parts can be touched: a mouse over a part on the bench or
+// the board lifts it a hair and names it, and lights its line in the parts
+// list; a line of the list pointed at lifts and lights its part on the stage.
+// This is what the two sides share โ the card (build/BuildCards.tsx, the
+// page's code) and the stage (stage/build/touch.ts, the canvas's) โ kept free
+// of three.js so the card does not pull the stage in.
+//
+// A part goes by its line's key in the BOM (build/bom.ts bomKey: the board's
+// reference, "SW1-SW4", or the part's name where it has none).
+
+/**
+ * The lines that have a part on the stage: every line of the BOM
+ * (stage/build/build.test.ts keeps the two in step โ a line added to the
+ * file, or renamed, shows up there and not as a part that silently stopped
+ * answering).
+ */
+export const TOUCH_KEYS = [
+ "U1",
+ "U1 (sockets)",
+ "SW1-SW4",
+ "J1",
+ "J3",
+ "J4",
+ "C11",
+ "LED matrix panel",
+ "M4 screw",
+ "USB cable (sacrificial)",
+ "USB power bank",
+] as const;
+export type TouchKey = (typeof TOUCH_KEYS)[number];
+
+type Listener = () => void;
+
+const listeners = new Set();
+const labels = new Map();
+let fromStage: string | null = null;
+let fromCard: string | null = null;
+
+/** Where the hand's light goes for the part the card points at (world units); `on` while there is one on stage. */
+export const touchSpot = { on: false, x: 0, y: 0, z: 0 };
+
+function changed() {
+ listeners.forEach((l) => l());
+}
+
+export function subscribeTouch(l: Listener) {
+ listeners.add(l);
+ return () => {
+ listeners.delete(l);
+ };
+}
+
+/** The card: what its lines are called on the stage, in the page's language ("J4 ยท Screw terminal"). */
+export function nameParts(names: Record) {
+ for (const [key, label] of Object.entries(names)) labels.set(key, label);
+}
+
+export function partLabel(key: string): string {
+ return labels.get(key) ?? key;
+}
+
+/** The part under the pointer on the stage, or null. */
+export function touchFromStage(key: string | null) {
+ if (fromStage === key) return;
+ fromStage = key;
+ changed();
+}
+
+/** The line pointed at in the card (mouse or keyboard), or null. */
+export function touchFromCard(key: string | null) {
+ if (fromCard === key) return;
+ fromCard = key;
+ if (!key) touchSpot.on = false;
+ changed();
+}
+
+export function stageTouch(): string | null {
+ return fromStage;
+}
+
+export function cardTouch(): string | null {
+ return fromCard;
+}
diff --git a/web/src/components/guide/stage/build/views.ts b/web/src/components/guide/stage/build/views.ts
index 0ccb67e7..c2c49e90 100644
--- a/web/src/components/guide/stage/build/views.ts
+++ b/web/src/components/guide/stage/build/views.ts
@@ -41,8 +41,10 @@ export const BUILD_VIEWS = {
boardLift: look([0, 6.4, 29], [0.2, 0.55, 1], box([-4, 0.8, 25.4], [4, 12, 32.6]), 0.8),
// The four plates printing, from in front and high up.
plates: look([0, 4, -46], [0, 1.15, 0.85], box([-28.6, 0, -71.4], [28.6, 17.6, -19.6]), 0.95),
- // The knob plate, closer.
- platesKnobs: look([15.4, 0.6, -32.6], [0.25, 0.95, 0.75], box([2.4, 0, -45.4], [28.4, 2.2, -19.8]), 0.85),
+ // The four knobs on their plate, close: they are 20 mm across on a 256 mm
+ // plate, black on dark โ framed on the whole plate they were four dots.
+ // The near half of the plate, with its edge in shot for bearings.
+ platesKnobs: look([17.2, 0.8, -34.4], [0.3, 0.8, 0.75], box([12.2, 0, -40.4], [22.2, 2.4, -28.4]), 0.86),
// The halves coming off their plates and closing up: the frame stands at the
// origin, the back panel lies left of it.
bond: look([-6, 9, 0], [0.42, 0.42, 1], box([-36, 0, -10], [12.6, 32.6, 22]), 0.94, 2),
@@ -68,6 +70,13 @@ export const BUILD_VIEWS = {
screwsBack: look([-1.2, 16.3, -0.6], [0.34, 0.3, -1], box([-12.6, 0.4, -3.6], [9.4, 32.4, 0.4]), 0.96, 1.6),
// The whole case from behind (looking +z), a little from the knob side and above.
caseBack: look([-0.4, 16, -1], [0.3, 0.42, -1], box([-12.6, 0, -9], [12.4, 32.6, 1.6]), 0.94, 2),
+ // Closing the back (check-4): from behind, well round to the knob side and
+ // low. Square on and from above (caseBack) the shut back was a blank slab
+ // under flat light โ nothing of the edge that hooks in, of the cover on its
+ // rails or of the print. From here the back is seen along its face: the
+ // panel swings shut toward the camera, the cover slides in along the near
+ // edge, and the light rakes across both.
+ backShut: look([-0.6, 15.6, -1.6], [0.74, 0.17, -1], box([-12.6, 0, -9], [12.4, 32.6, 1.6]), 0.94, 2),
// The board bay from behind and the knob side, with room for the board
// hovering 7 units behind it (case-3, case-4) and the cable coming out.
caseBackClose: look([7.4, 22.4, -3.6], [0.75, 0.42, -1], box([2.6, 16.6, -8.2], [12.6, 32.4, 1.2]), 0.94, 1.2),
@@ -97,8 +106,147 @@ export const BUILD_VIEWS = {
// narrow screen (wire-2), where wireBack leaves the two terminals a
// thumb's width apart and their four tags on top of each other.
terminalsBack: look([8.05, 20.9, -0.6], [0.22, 0.34, -1], box([4.3, 18.8, -1.8], [11.9, 23.4, 0.7]), 0.94, 1),
+ // The four encoder shafts through the case's front face, close, from the
+ // knob side and a little above: a washer and a nut on each (case-5), with
+ // room in front for the one being brought up. Play's "knobs" view is for
+ // four knobs and a screen behind them; a washer is a third of a knob across.
+ shafts: look([8.0, 28.0, 2.4], [0.62, 0.3, 1], box([5.0, 25.2, 1.5], [11.2, 31.2, 5.2]), 0.9, 0.9),
// The front tray, its lid slid out to the right, from the front and the right.
trayFront: look([8.6, 9, 3], [0.62, 0.32, 1], box([2.8, 0, -1.6], [21, 20.4, 7.6]), 0.92, 1.2),
+ // The whole device from the front and the knob side, a little above
+ // (check-5): the lid comes in along its rails from that side, toward the
+ // camera's left, and each knob is seen going ONTO its shaft โ from square
+ // in front a knob pushed on is a disc that appears. Close to where the
+ // guide's last view (Play's "hero") stands, so the end is a short move.
+ finish: look([0.4, 16.2, 0.8], [0.52, 0.2, 1], box([-12.4, 0, -2], [13.2, 32.6, 4.2]), 0.92, 2),
+ // The whole device from the front, as the panel comes on (firmware-3):
+ // Play's "front" view (views.ts โ the same target, direction, distance and
+ // frame, in world units). It is a view of its own because the step does
+ // not start there: it opens on the tray, from the front and the knob side
+ // (below), where the bank going in and the plug going into it can be seen
+ // โ from square in front, a bank sliding 7 units straight away from the
+ // camera is a bank standing still โ and comes round to the front as the
+ // plug goes home and the panel lights.
+ powerOn: {
+ target: new THREE.Vector3(0.2, 0, 0),
+ dir: new THREE.Vector3(0.4, 0.3, 11.8).normalize(),
+ minR: new THREE.Vector3(0.4, 0.3, 11.8).length(),
+ frame: [-1.23, 1.23].flatMap((x) => [-1.63, 1.58].flatMap((y) => [-0.2, 0.37].map((z) => new THREE.Vector3(x, y, z)))),
+ fill: 0.92,
+ },
} satisfies Record;
export type BuildViewName = keyof typeof BUILD_VIEWS;
+
+// โโ the camera's move within a step โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+//
+// A view above is where the camera ends up: the frame the step holds on. It
+// does not arrive there and stop dead. While the step's own motion plays the
+// camera is still coming in โ from a few degrees round and a few per cent
+// further out โ so that it settles into the authored frame as the motion
+// ends. The rig (GuideCanvas) follows whatever the view says on its springs;
+// BuildStage calls settleIn every frame with how far through the beat it is.
+//
+// `turn` is how far round (radians, about the vertical) the camera starts,
+// `push` how much further out (a share of the frame). The views that look
+// through a gap at one particular thing do not turn: from a few degrees off
+// they look through it at something else (build.test.ts, case-3).
+
+// A step whose subject is small in the frame it must end on opens close on
+// it โ `open`: another target and frame, held until `until` of the way
+// through the beat, and left for the authored ones by `by` โ so the reader
+// sees what is being done before seeing it done twelve times.
+
+type Open = { target: THREE.Vector3; frame: THREE.Vector3[]; minR: number; dir?: THREE.Vector3; until: number; by: number };
+type Move = { turn: number; push: number; open?: Open };
+const MOVE: Move = { turn: 0.06, push: 0.05 };
+const MOVES: Partial> = {
+ bench: { turn: 0.04, push: 0.04 },
+ benchWide: { turn: 0.03, push: 0.03 },
+ plates: { turn: 0.05, push: 0.05 },
+ boardF: { turn: -0.05, push: 0.05 },
+ boardParts: { turn: 0.04, push: 0.04 },
+ boardC11: { turn: -0.07, push: 0.05 },
+ boardSW: { turn: 0.05, push: 0.04 },
+ panelIn: { turn: -0.07, push: 0.05 },
+ // The first screw into its tab (the bottom corner on the panel's outer
+ // side), with room for the screw waiting 3 units behind it; then back, for
+ // the other eleven.
+ screwsBack: {
+ turn: 0.06,
+ push: 0.04,
+ open: { target: w(-10.6, 4.4, -1.2), frame: box([-12.6, 0.6, -4.4], [-7, 8.6, 0.4]), minR: 0.9, until: 0.38, by: 0.56 },
+ },
+ shafts: { turn: -0.06, push: 0.05 },
+ finish: { turn: 0.07, push: 0.04 },
+ // The tray, the bank standing in front of it and going in, the plug above
+ // its port; then round to the front for the panel.
+ powerOn: {
+ turn: 0,
+ push: 0,
+ open: { target: w(8.4, 9.6, 2.4), dir: new THREE.Vector3(0.7, 0.34, 1).normalize(), frame: box([3.6, 0, -1.6], [13, 19.4, 8]), minR: 1.2, until: 0.68, by: 0.9 },
+ },
+ caseBack: { turn: -0.07, push: 0.05 },
+ backShut: { turn: -0.08, push: 0.05 },
+ caseBackClose: { turn: 0.05, push: 0.05 },
+ leadBack: { turn: 0, push: 0.05 },
+ leadHole: { turn: 0, push: 0.04 },
+ leadJ4: { turn: 0, push: 0.04 },
+ wireBack: { turn: -0.05, push: 0.05 },
+ terminalsBack: { turn: 0, push: 0.04 },
+};
+const REST = new Map();
+const UP = new THREE.Vector3(0, 1, 0);
+const TURNED = new THREE.Vector3();
+let moving: BuildViewName | null = null;
+
+function rest(name: BuildViewName) {
+ const r = REST.get(name);
+ if (!r) return;
+ const view = BUILD_VIEWS[name] as View;
+ view.dir.copy(r.dir);
+ view.fill = r.fill;
+ view.target.copy(r.target);
+ view.frame.forEach((q, i) => q.copy(r.frame[i]));
+ view.minR = r.minR;
+}
+
+/**
+ * Put view `name` where the camera should be `left` of the way from its
+ * authored frame (1 at the start of a step's motion, 0 once it has ended);
+ * `weight` scales the whole move (a one-second beat has no room for it);
+ * `phase` is how far through its beat the step is (0โฆ1), for a view that
+ * opens close. Any other view is put back as authored. With no name, all of
+ * them are.
+ */
+export function settleIn(name: string | null | undefined, left: number, weight = 1, phase = 1) {
+ if (moving && moving !== name) {
+ rest(moving);
+ moving = null;
+ }
+ if (!name || !(name in BUILD_VIEWS)) return;
+ const key = name as BuildViewName;
+ const view = BUILD_VIEWS[key] as View;
+ let r = REST.get(key);
+ if (!r) {
+ r = { dir: view.dir.clone(), fill: view.fill, target: view.target.clone(), frame: view.frame.map((q) => q.clone()), minR: view.minR };
+ REST.set(key, r);
+ }
+ const m = MOVES[key] ?? MOVE;
+ const k = Math.min(1, Math.max(0, left)) * weight;
+ view.dir.copy(r.dir).applyAxisAngle(UP, m.turn * k);
+ view.fill = r.fill * (1 - m.push * k);
+ TURNED.copy(view.dir);
+ if (m.open && m.open.frame.length === r.frame.length) {
+ const x = Math.min(1, Math.max(0, (phase - m.open.until) / (m.open.by - m.open.until)));
+ // 1 close on the subject, 0 the authored frame; eased both ways.
+ const close = weight > 0 ? 1 - (x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2) : 0;
+ view.target.lerpVectors(r.target, m.open.target, close);
+ view.frame.forEach((q, i) => q.lerpVectors(r.frame[i], m.open!.frame[i], close));
+ view.minR = r.minR + (m.open.minR - r.minR) * close;
+ // The direction goes round the short way, on the sphere: a straight line
+ // between two directions dips toward the target on the way.
+ if (m.open.dir) view.dir.copy(TURNED).lerp(m.open.dir, close).normalize();
+ }
+ moving = key;
+}
diff --git a/web/src/components/guide/stage/damp.ts b/web/src/components/guide/stage/damp.ts
new file mode 100644
index 00000000..2867dd02
--- /dev/null
+++ b/web/src/components/guide/stage/damp.ts
@@ -0,0 +1,20 @@
+// A critically damped spring, for anything on the stage that follows a
+// target: the camera (GuideCanvas), the device coming apart (Explode). It
+// never overshoots, and it starts and stops without a corner whatever the
+// target does meanwhile โ the target can move while it is on its way.
+
+export type Damp = { v: number };
+
+/**
+ * One step of `current` toward `target`. `vel` carries the velocity between
+ * frames; `smoothTime` is roughly how long most of the way takes, seconds.
+ */
+export function smoothDamp(current: number, target: number, vel: Damp, smoothTime: number, dt: number) {
+ const omega = 2 / Math.max(0.0001, smoothTime);
+ const x = omega * dt;
+ const exp = 1 / (1 + x + 0.48 * x * x + 0.235 * x * x * x);
+ const change = current - target;
+ const temp = (vel.v + omega * change) * dt;
+ vel.v = (vel.v - omega * temp) * exp;
+ return target + (change + temp) * exp;
+}
diff --git a/web/src/components/guide/stage/explodeParts.ts b/web/src/components/guide/stage/explodeParts.ts
new file mode 100644
index 00000000..14515355
--- /dev/null
+++ b/web/src/components/guide/stage/explodeParts.ts
@@ -0,0 +1,116 @@
+import { useGuideStore } from "../store";
+import { buildClock } from "../timing";
+import { OPENING_GONE } from "./build/beats";
+
+// The device, taken apart in the air: the hub's answer to "Build" (GuideHub
+// โ store.preview โ stage/Explode.tsx), and how the Build guide opens. One
+// amount, 0 whole โฆ 1 apart, and
+// each part's place is a function of it โ along the axis that part really
+// goes on or comes off by (BUILD_GUIDE.md ยง6โยง9, stage/build/BuildStage):
+//
+// knobs pressed onto the encoder shafts from the front +z
+// panel into the frame from the front +z
+// lid slides over the power-bank tray from the case's side +x (and a little forward, clear of the face)
+// body stays: everything else is told from it
+// board in from behind, its encoder shafts through the face โz
+// devkit onto its sockets on the back of the board โz
+// backPlate hooked on and shut over the back โz
+// slider the cover on the back plate, along its rails +x, with the plate
+//
+// The numbers are model units (10 mm). The parts leave in order โ the
+// outside first โ and come home in the reverse order, each on its own slice
+// of the amount (`from`โฆ`to`), eased; nothing travels at a constant speed.
+//
+// This file is the arithmetic, kept free of three.js so it can be tested;
+// Explode.tsx applies it to the device's objects.
+
+export type ExplodePart = "knobs" | "panel" | "lid" | "board" | "devkit" | "backPlate" | "slider";
+
+export type ExplodeSpec = {
+ /** Where the part is when the device is fully apart, from its place in the device. */
+ offset: readonly [number, number, number];
+ /** The slice of the amount this part travels over. */
+ from: number;
+ to: number;
+};
+
+export const EXPLODE: Record = {
+ // The knobs come less far than the panel: seen from the knob side they
+ // then stand in front of the white face they came off, not of the dark panel.
+ knobs: { offset: [0, 0, 4.2], from: 0, to: 0.72 },
+ slider: { offset: [5.4, 0, -15.5], from: 0, to: 0.8 },
+ backPlate: { offset: [0, 0, -15.5], from: 0.04, to: 0.84 },
+ panel: { offset: [0, 0, 6.4], from: 0.1, to: 0.88 },
+ lid: { offset: [7.2, 0, 2.2], from: 0.14, to: 0.9 },
+ devkit: { offset: [0, 0, -11.2], from: 0.16, to: 0.94 },
+ board: { offset: [0, 0, -6.8], from: 0.22, to: 1 },
+};
+
+export const EXPLODE_PARTS = Object.keys(EXPLODE) as ExplodePart[];
+
+/**
+ * Below this the device is whole: the amount snaps to 0 and every part is
+ * exactly home (and above 1 โ this, to 1). At this amount the parts that
+ * lead are a few hundredths of a millimetre out, so the snap cannot be seen;
+ * a spring left to itself would take another second to get there.
+ */
+export const EXPLODE_WHOLE = 0.02;
+
+const clamp01 = (x: number) => Math.min(1, Math.max(0, x));
+/** Starts and ends at rest, with no corner in between. */
+const ease = (x: number) => {
+ const c = clamp01(x);
+ return c * c * c * (c * (c * 6 - 15) + 10);
+};
+
+/** How far along its own way a part is, 0โฆ1, for an amount. */
+export function partAmount(part: ExplodePart, amount: number): number {
+ const { from, to } = EXPLODE[part];
+ return ease((amount - from) / (to - from));
+}
+
+/** A part's displacement for an amount, written into `out` (x, y, z). */
+export function partOffset(part: ExplodePart, amount: number, out: { x: number; y: number; z: number }) {
+ const a = partAmount(part, amount);
+ const o = EXPLODE[part].offset;
+ // (+ 0: a part that goes backward is at 0 when home, not โ0.)
+ out.x = o[0] * a + 0;
+ out.y = o[1] * a + 0;
+ out.z = o[2] * a + 0;
+ return out;
+}
+
+/**
+ * Where the stage is with it. Explode.tsx writes `amount` every frame;
+ * anything may read it (the Build stage draws its opening apart by it, and
+ * hands the device back only at 0; the light and the page may follow it).
+ */
+export const explodeState = { amount: 0 };
+
+let calm: MediaQueryList | null = null;
+function reducedMotion(): boolean {
+ if (typeof window === "undefined" || !window.matchMedia) return false;
+ calm ??= window.matchMedia("(prefers-reduced-motion: reduce)");
+ return calm.matches;
+}
+
+/**
+ * Should the device be apart right now? On the hub, while Build is the guide
+ * pointed at (or chosen: store.leaveFor keeps it pointed at until the guide
+ * arrives) โ and on through Build's own opening: choosing Build does not put
+ * back together what pointing at it took apart. The parts hang there beside
+ * the title until the reader scrolls into the build, and go as the bench
+ * comes up (BuildStage; Explode holds them apart while they do).
+ *
+ * Not under reduced motion โ nothing on the hub answers there, and Build
+ * opens on the whole device โ and on the hub not while the Build stage is
+ * still showing the build (it is winding it back after its guide was left:
+ * timing.ts buildClock; at its opening it draws the device apart as well as
+ * whole).
+ */
+export function explodeWanted(): boolean {
+ const { page, preview, scene } = useGuideStore.getState();
+ if (reducedMotion()) return false;
+ if (page === "hub") return preview === "build" && buildClock.t < OPENING_GONE;
+ return page === "build" && scene === "opening";
+}
diff --git a/web/src/components/guide/stage/hand.ts b/web/src/components/guide/stage/hand.ts
new file mode 100644
index 00000000..f13dcdb8
--- /dev/null
+++ b/web/src/components/guide/stage/hand.ts
@@ -0,0 +1,49 @@
+// The reader's hand on the stage: where the mouse is, for whatever answers it
+// โ the camera's lean (GuideCanvas CameraRig), the light it carries
+// (StageHand.tsx), the hub's panel (world/hubHand.ts), the Build guide's parts
+// (build/touch.ts).
+//
+// Plain numbers, written on pointer events only (StageHand.tsx has the listeners)
+// and read from the frame loops, which do their own easing. A mouse, never a
+// finger: a touch is a scroll or a knob, there is no hover on a phone, and
+// nothing here may move under a thumb. Kept free of three.js so the page's
+// own code can read it.
+
+export const hand = {
+ /** Across the window, โ1 left โฆ 1 right, and โ1 top โฆ 1 bottom. */
+ x: 0,
+ y: 0,
+ /** The same place in CSS px. */
+ px: 0,
+ py: 0,
+ /** A mouse is in the window. */
+ here: false,
+ /** โฆand on the stage itself: nothing of the page is under it. */
+ onStage: false,
+ /** Counts the moves: whoever looks for what is under the pointer looks once a move. */
+ moves: 0,
+};
+
+/** The mouse has gone (left the window, the tab hid) or a finger took over. */
+export function handGone() {
+ hand.here = false;
+ hand.onStage = false;
+ hand.moves++;
+}
+
+/**
+ * How far in front of its subject the hand's light is held, world units, for
+ * a camera `r` away from what it is on: close enough that it grazes, and pools.
+ */
+export function handHold(r: number): number {
+ return Math.min(0.9, Math.max(0.2, r * 0.07));
+}
+
+/**
+ * The DevKit's two buttons under the reader's own finger (Device.tsx takes
+ * the press, KitFx.tsx shows it): BOOT and RST go down for as long as the
+ * pointer holds them, exactly as the script presses them โ the same travel,
+ * the same ring, the same tag โ and only on the step whose subject they are.
+ * Nothing else happens, as nothing else would: the board is out of the case.
+ */
+export const kitPress = { boot: false, rst: false };
diff --git a/web/src/components/guide/stage/hubViews.ts b/web/src/components/guide/stage/hubViews.ts
new file mode 100644
index 00000000..71c1eb9b
--- /dev/null
+++ b/web/src/components/guide/stage/hubViews.ts
@@ -0,0 +1,37 @@
+import * as THREE from "three";
+import { MODEL_OFFSET, MODEL_SCALE } from "./geometry";
+import { EXPLODE } from "./explodeParts";
+import type { View } from "./views";
+
+// The hub's own camera views (GuideCanvas CameraRig), in views.ts's terms.
+// The hub plays Play's opening โ the device turning slowly โ and these are
+// for what it shows besides, while a guide is pointed at. The Build guide
+// opens on the same view of the same device (explodeParts.ts explodeWanted),
+// in the room its title leaves.
+
+const w = (x: number, y: number, z: number) => new THREE.Vector3(x, y, z).multiplyScalar(MODEL_SCALE).add(MODEL_OFFSET);
+
+// The device taken apart (explodeParts.ts): its parts are strung out along z, the
+// knobs in front and the back plate behind, with the two sliding covers out
+// to the right. Seen from the knob side and a little above, well round from
+// the front: from the front the layers hide one another, from the side they
+// are edges.
+//
+// The frame goes a little below the floor (FOOT). The parts nearest the
+// camera โ the lid over the power-bank tray, out to the right and forward โ
+// hang lowest on screen, and fitted to the device's own height the lid's
+// corner came down to within a line of the hub's "Start where you are.":
+// the picture had no air at its foot.
+const front = Math.max(3.65 + EXPLODE.knobs.offset[2], 1.5 + EXPLODE.panel.offset[2]);
+const back = -1.95 + EXPLODE.backPlate.offset[2];
+const right = 12.3 + Math.max(EXPLODE.lid.offset[0], EXPLODE.slider.offset[0]);
+const FOOT = -3.4;
+const exploded: View = {
+ target: w(0.6, 16.3, (front + back) / 2),
+ dir: new THREE.Vector3(0.86, 0.3, 0.72).normalize(),
+ minR: 13.2,
+ frame: [-12.5, right].flatMap((x) => [FOOT, 32.6].flatMap((y) => [back, front].map((z) => w(x, y, z)))),
+ fill: 0.9,
+};
+
+export const HUB_VIEWS = { exploded } satisfies Record;
diff --git a/web/src/components/guide/stage/look/StageLight.tsx b/web/src/components/guide/stage/look/StageLight.tsx
new file mode 100644
index 00000000..f494e952
--- /dev/null
+++ b/web/src/components/guide/stage/look/StageLight.tsx
@@ -0,0 +1,326 @@
+"use client";
+
+/* eslint-disable react-hooks/immutability --
+ Lights and materials are imperative three.js objects driven from the frame
+ loop; that is their API and it never feeds back into React. */
+
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { useGuideStore } from "../../store";
+import { LED_CENTER_WORLD } from "../geometry";
+import { LED_GAIN, ledPanelTexture } from "./ledPanel";
+import { GLOW_BANDS, panelGlow } from "./panelGlow";
+import { grainTexture } from "./textures";
+
+// The LED panel as a light.
+//
+// The panel is the brightest thing in the room and the only coloured one, and
+// what it shows changes all the time; the room has to answer it. Three things
+// do, all fed by what the panel is showing right now (panelGlow.ts, and the
+// panel's own texture):
+//
+// PanelLights three small lights standing just off the panel's face, one
+// per third of its height, each the colour of its third. They
+// stand close to the face, so the case's front โ which the
+// panel is flush with, and cannot light โ takes them only at a
+// graze, while what stands proud of it or faces it does: the
+// knobs' flanks, the bench, a part held in front.
+// StageFloor the floor mirrors the panel: a rough, dark, slightly glossy
+// surface, so the mirror image is a soft smear drawn out
+// toward the eye, in the pattern's own colours, strongest at a
+// graze. And where the device stands on it, the dark gathers.
+// PanelAir the veil a bright thing has round it in a dark room, to the
+// eye and to a lens: the panel's colour, faint, reaching out
+// past its edges into the dark.
+//
+// None of them has a shadow (see GuideCanvas: on the Build guide the lights
+// go out as the camera comes round behind the panel, or its open back would
+// glow), and all three are always there โ at nothing when the panel is dark
+// โ so no shader is rebuilt when it lights.
+
+/** The panel's lit face, world units: its left, foot, right and top edges, and its plane. */
+const FACE = { x0: LED_CENTER_WORLD.x - 0.8, y0: LED_CENTER_WORLD.y - 1.6, x1: LED_CENTER_WORLD.x + 0.8, y1: LED_CENTER_WORLD.y + 1.6, z: 0.15 };
+/** How far off the face the lights stand. */
+const LIGHT_OFF = 0.16;
+/** Candela of a band at full white, before the knee. */
+const LIGHT_GAIN = 6;
+/** The floor (GuideCanvas has always had it here). */
+const FLOOR_Y = -1.66;
+/** The case's footprint on the floor: centre x, z and half-sizes. */
+const FOOT = new THREE.Vector4(0, 0.085, 1.24, 0.29);
+
+/** 1 with the camera in front of the panel, 0 behind it โ on the Build guide, where the panel's back stands open. */
+function frontOf(camera: THREE.Camera) {
+ if (useGuideStore.getState().page !== "build") return 1;
+ return THREE.MathUtils.clamp((camera.position.z + 0.3) / 0.6, 0, 1);
+}
+
+export function PanelLights() {
+ const lights = useRef<(THREE.PointLight | null)[]>([]);
+ useFrame((state) => {
+ const front = frontOf(state.camera);
+ for (let k = 0; k < GLOW_BANDS; k++) {
+ const l = lights.current[k];
+ if (!l) continue;
+ const c = panelGlow.bands[k];
+ const peak = Math.max(c.r, c.g, c.b);
+ if (peak > 1e-4) l.color.setRGB(c.r / peak, c.g / peak, c.b / peak);
+ // A knee: a third of the panel in full white is not five times a pattern's worth of light on the case.
+ l.intensity = ((LIGHT_GAIN * peak) / (1 + 2.2 * peak)) * front;
+ }
+ });
+ const h = (FACE.y1 - FACE.y0) / GLOW_BANDS;
+ return (
+ <>
+ {Array.from({ length: GLOW_BANDS }, (_, k) => (
+ {
+ lights.current[k] = l;
+ }}
+ position={[(FACE.x0 + FACE.x1) / 2, FACE.y0 + h * (k + 0.5), FACE.z + LIGHT_OFF]}
+ intensity={0}
+ distance={5.5}
+ decay={2}
+ />
+ ))}
+
+ );
+}
+
+// โโ the air โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+
+const airVert = /* glsl */ `
+varying vec2 vP;
+void main() {
+ vP = position.xy;
+ gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`;
+
+const airFrag = /* glsl */ `
+uniform vec3 uBands[${GLOW_BANDS}];
+uniform vec2 uHalf;
+uniform float uFade;
+varying vec2 vP;
+void main() {
+ // How far outside the face, in world units (0 on it).
+ vec2 q = abs(vP) - uHalf;
+ float d = length(max(q, 0.0));
+ // The colour of the nearest height: the thirds, run together.
+ float t = clamp(vP.y / (2.0 * uHalf.y) + 0.5, 0.0, 1.0) * ${GLOW_BANDS.toFixed(1)} - 0.5;
+ vec3 col = mix(uBands[0], uBands[1], smoothstep(0.0, 1.0, t));
+ col = mix(col, uBands[2], smoothstep(1.0, 2.0, t));
+ // Close in, a tight glow; further out, a long faint one.
+ float veil = 0.65 * exp(-d * d / 0.02) + 0.35 * exp(-d / 0.4);
+ // Over the face itself, less: its blacks are what make it read as LEDs.
+ veil *= mix(0.18, 1.0, smoothstep(-0.03, 0.05, max(q.x, q.y)));
+ gl_FragColor = vec4(col * veil * uFade, 0.0);
+}
+`;
+
+export function PanelAir() {
+ const mat = useMemo(() => {
+ const m = new THREE.ShaderMaterial({
+ uniforms: {
+ uBands: { value: panelGlow.bands },
+ uHalf: { value: new THREE.Vector2((FACE.x1 - FACE.x0) / 2, (FACE.y1 - FACE.y0) / 2) },
+ uFade: { value: 0 },
+ },
+ vertexShader: airVert,
+ fragmentShader: airFrag,
+ transparent: true,
+ depthWrite: false,
+ depthTest: false,
+ toneMapped: false,
+ // Adds light and leaves alpha alone: the canvas is transparent over the page (Fx.tsx lightOnly).
+ blending: THREE.CustomBlending,
+ blendEquation: THREE.AddEquation,
+ blendSrc: THREE.OneFactor,
+ blendDst: THREE.OneFactor,
+ blendEquationAlpha: THREE.AddEquation,
+ blendSrcAlpha: THREE.ZeroFactor,
+ blendDstAlpha: THREE.OneFactor,
+ });
+ return m;
+ }, []);
+ useEffect(() => () => mat.dispose(), [mat]);
+ const mesh = useRef(null);
+ useFrame((state) => {
+ // From the front only: square on it is strongest, and it is gone by the time the panel is edge on.
+ const cam = state.camera.position;
+ const dz = cam.z - FACE.z;
+ const dist = Math.hypot(cam.x - LED_CENTER_WORLD.x, cam.y - LED_CENTER_WORLD.y, dz);
+ const facing = THREE.MathUtils.clamp(dz / Math.max(dist, 1e-3), 0, 1);
+ const fade = 0.15 * LED_GAIN * Math.min(1, facing * 1.6) * frontOf(state.camera);
+ mat.uniforms.uFade.value = fade;
+ if (mesh.current) mesh.current.visible = fade > 0.002 && panelGlow.power > 0.002;
+ });
+ return (
+
+
+ );
+}
+
+// โโ the floor โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+//
+// Something for the device to stand on, fading into the dark well before its
+// edges. It is nearly black, so what it shows of the panel is not a spill of
+// colour on it (a black thing has no colour to give back) but the panel's
+// reflection: rough, so blurred โ more the further the light has travelled โ
+// and drawn out toward the eye, as a wet road draws out a lamp; Fresnel, so
+// it is strong at a graze and almost nothing from above.
+
+export function StageFloor() {
+ const scene = useThree((s) => s.scene);
+ const alpha = useMemo(() => {
+ const c = document.createElement("canvas");
+ c.width = c.height = 256;
+ const ctx = c.getContext("2d");
+ if (ctx) {
+ const g = ctx.createRadialGradient(128, 128, 0, 128, 128, 128);
+ g.addColorStop(0, "#ffffff");
+ g.addColorStop(0.45, "#8a8a8a");
+ g.addColorStop(1, "#000000");
+ ctx.fillStyle = g;
+ ctx.fillRect(0, 0, 256, 256);
+ }
+ return new THREE.CanvasTexture(c);
+ }, []);
+
+ const { mat, uniforms } = useMemo(() => {
+ const uniforms = {
+ uPanel: { value: ledPanelTexture() as THREE.Texture },
+ uPanelRect: { value: new THREE.Vector4(FACE.x0, FACE.y0, FACE.x1, FACE.y1) },
+ uPanelZ: { value: FACE.z },
+ // The panel's power ร its gain, and how much of the device stands on the floor (0 โฆ 1).
+ uPanelPower: { value: 0 },
+ uContact: { value: 0 },
+ uFoot: { value: FOOT },
+ // The case's front face: its centre x, y and half-sizes.
+ uCase: { value: new THREE.Vector4(0, -0.025, 1.23, 1.605) },
+ uTooth: { value: grainTexture() as THREE.Texture },
+ };
+ const mat = new THREE.MeshStandardMaterial({ color: "#141210", roughness: 0.92, metalness: 0, transparent: true, alphaMap: alpha });
+ mat.onBeforeCompile = (shader) => {
+ Object.assign(shader.uniforms, uniforms);
+ shader.vertexShader = shader.vertexShader
+ .replace("#include ", "#include \nvarying vec3 vFloorW;")
+ .replace("#include ", "#include \nvFloorW = (modelMatrix * vec4(transformed, 1.0)).xyz;");
+ shader.fragmentShader = shader.fragmentShader
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+varying vec3 vFloorW;
+uniform sampler2D uPanel;
+uniform vec4 uPanelRect;
+uniform float uPanelZ;
+uniform float uPanelPower;
+uniform float uContact;
+uniform vec4 uFoot;
+uniform vec4 uCase;
+uniform sampler2D uTooth;
+
+// The device as the floor sees it at p, looking along view (from the eye):
+// the panel's light, and round it the pale of the case's face.
+vec3 floorMirror(vec3 p, vec3 view) {
+ // Only in front of the device, and not out where the floor has faded away.
+ if (p.z < uPanelZ || p.z > uPanelZ + 5.0 || abs(p.x) > 3.4) return vec3(0.0);
+ vec2 toEye = -normalize(view.xz + vec2(1e-5));
+ vec3 sum = vec3(0.0);
+ float wsum = 0.0;
+ float lastUp = -1.0;
+ // A rough floor is many small mirrors, each leaning a little along the line
+ // to the eye. Seen at a graze it is the ones leaning toward the eye that
+ // show, and those look higher up the device: the smear a lamp leaves on a
+ // wet road โ drawn out toward the eye, and hardly spread sideways at all.
+ // Six of them, fewer the further they lean; each is read through a
+ // footprint as long as the gap to the next (the sampler's anisotropic
+ // filter does the smearing), so the six never show as six.
+ for (int i = 0; i < 6; i++) {
+ float f = float(i);
+ float lean = -0.06 + f * (0.045 + f * 0.0094);
+ float w = exp(-f * 0.3) * (i == 0 ? 0.6 : 1.0);
+ wsum += w;
+ vec3 r = reflect(view, normalize(vec3(toEye.x * lean, 1.0, toEye.y * lean)));
+ if (r.z > -1e-3) continue;
+ float t = (uPanelZ - p.z) / r.z;
+ if (t <= 0.0) continue;
+ vec3 hit = p + r * t;
+ float across = (hit.x - uPanelRect.x) / (uPanelRect.z - uPanelRect.x);
+ float up = (hit.y - uPanelRect.y) / (uPanelRect.w - uPanelRect.y);
+ float along = lastUp < 0.0 ? 0.06 : clamp(abs(up - lastUp), 0.03, 0.4);
+ lastUp = up;
+ // Sideways it blurs with how far the light came, and the panel's edges are soft by as much.
+ float side = 0.012 + 0.035 * t;
+ float inPanel = smoothstep(-side, side, min(across, 1.0 - across)) * smoothstep(-along * 0.5, along * 0.5, min(up, 1.0 - up));
+ vec3 light = textureGrad(uPanel, vec2(clamp(up, 0.0, 1.0), 1.0 - clamp(across, 0.0, 1.0)), vec2(along, 0.0), vec2(0.0, side)).rgb * (inPanel * uPanelPower);
+ // The case's face round the panel: white PLA under the key light.
+ vec2 c = (hit.xy - uCase.xy) / uCase.zw;
+ float inCase = smoothstep(-side, side, 1.0 - abs(c.x)) * smoothstep(-along * 0.5, along * 0.5, 1.0 - abs(c.y));
+ light += vec3(0.5, 0.485, 0.46) * (inCase * (1.0 - inPanel) * uContact);
+ sum += light * (w / (1.0 + 0.35 * t));
+ }
+ return sum / max(wsum, 1e-3);
+}`,
+ )
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+// Where the case stands: the light cannot get under it, and little gets near.
+vec2 footQ = abs(vFloorW.xz - uFoot.xy) - uFoot.zw;
+float footD = max(length(max(footQ, 0.0)) + min(max(footQ.x, footQ.y), 0.0), 0.0);
+float contact = 1.0 - uContact * (0.6 * exp(-footD / 0.06) + 0.32 * exp(-footD / 0.42));
+diffuseColor.rgb *= contact;`,
+ )
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+if (uPanelPower + uContact > 0.001) {
+ vec3 floorView = normalize(vFloorW - cameraPosition);
+ float fres = 0.04 + 0.96 * pow(1.0 - clamp(-floorView.y, 0.0, 1.0), 5.0);
+ // No floor is evenly smooth: the mirror is a little stronger here and weaker there.
+ float floorTooth = 0.7 + 0.6 * texture2D(uTooth, vFloorW.xz * 0.9).b;
+ totalEmissiveRadiance += floorMirror(vFloorW, floorView) * (fres * 1.1 * floorTooth) * mix(1.0, contact, 0.6);
+}`,
+ );
+ };
+ mat.customProgramCacheKey = () => "look-floor-1";
+ return { mat, uniforms };
+ }, [alpha]);
+
+ useEffect(
+ () => () => {
+ mat.dispose();
+ alpha.dispose();
+ },
+ [mat, alpha],
+ );
+
+ const body = useRef(null);
+ const contact = useRef(0);
+ useFrame((state, dt) => {
+ uniforms.uPanelPower.value = panelGlow.power * LED_GAIN * frontOf(state.camera);
+ // The case's shade on the floor is there while the case is: on the Build
+ // guide it is printed, bonded and brought in part-way through, and until
+ // then (its body hidden, faded, or somewhere else) the floor is bare.
+ const b = (body.current ??= (scene.getObjectByName("body") as THREE.Mesh | undefined) ?? null);
+ let want = 0;
+ if (b && b.visible && b.parent) {
+ const home = b.userData.home as THREE.Vector3 | undefined;
+ const moved = home ? b.position.distanceToSquared(home) : b.position.lengthSq();
+ const m = b.material as THREE.MeshStandardMaterial;
+ if (moved < 1e-4 && Math.abs(b.quaternion.w) > 0.9999) want = m.transparent ? m.opacity : 1;
+ }
+ contact.current += (want - contact.current) * Math.min(1, dt * 6);
+ uniforms.uContact.value = contact.current;
+ });
+
+ return (
+
+
+ );
+}
diff --git a/web/src/components/guide/stage/look/StagePost.tsx b/web/src/components/guide/stage/look/StagePost.tsx
new file mode 100644
index 00000000..3f76a3b0
--- /dev/null
+++ b/web/src/components/guide/stage/look/StagePost.tsx
@@ -0,0 +1,281 @@
+"use client";
+
+/* eslint-disable react-hooks/immutability --
+ The effects are imperative postprocessing objects driven from the frame
+ loop; that is their API and it never feeds back into React. */
+
+import { useFrame } from "@react-three/fiber";
+import { EffectComposer, N8AO, ToneMapping, Vignette } from "@react-three/postprocessing";
+import { BlendFunction, BloomEffect, Effect, EffectAttribute, FXAAEffect, ToneMappingMode } from "postprocessing";
+import { memo, useEffect, useMemo, type JSX } from "react";
+import * as THREE from "three";
+import { useGuideStore } from "../../store";
+import { stageLoad } from "../../ui/stageLoad";
+import { buildFocus } from "../build/focus";
+import { stageFocus } from "./focus";
+import { measureFrame, settingsFor, useTier } from "./quality";
+
+// What the lens and the film do to the frame, in order:
+//
+// occlusion where surfaces meet, the room's light does not reach (N8AO)
+// focus a shallow depth of field on what the step is about; the rest
+// of the stage falls a little soft, more the closer the camera is
+// bloom only what is brighter than white glows: LEDs past their knee,
+// the live rings. The white case, however well lit, stays under
+// the threshold โ it used to bloom the screen white. "Brighter
+// than white" is judged by luminance for what is white and by
+// its strongest channel for what is coloured (see the glow,
+// below): a blue LED at full power is as much a light as a
+// white one.
+// tone curve ACES
+// grade a film's: shadows a touch cool, highlights a touch warm, a
+// gentle shoulder and toe, a little more colour
+// vignette
+//
+// edges at the lowest tier, where there is no multisampling, an edge
+// filter over the finished picture โ in a pass of its own
+//
+// Which of these a machine gets is its tier (quality.ts), measured from its
+// own frame times. The composer is rebuilt only when the tier changes.
+
+// โโ the grade โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+
+const gradeFrag = /* glsl */ `
+void mainImage(const in vec4 inputColor, const in vec2 uv, out vec4 outputColor) {
+ // The frame here is display-linear; the eye's scale is what a grade works on.
+ vec3 c = pow(max(inputColor.rgb, 0.0), vec3(1.0 / 2.2));
+ float l = dot(c, vec3(0.2126, 0.7152, 0.0722));
+ // Split tone: nothing is added to black (the canvas is transparent there), the tint is a gain.
+ c *= mix(vec3(0.97, 0.995, 1.04), vec3(1.012, 1.0, 0.985), smoothstep(0.08, 0.75, l));
+ // A film's curve: a toe and a shoulder round the same mid grey.
+ c = mix(c, c * c * (3.0 - 2.0 * c), 0.16);
+ // A little more colour in the mid-tones, none added to what is already full.
+ float sat = 1.0 + 0.06 * (1.0 - smoothstep(0.55, 1.0, max(c.r, max(c.g, c.b)) - min(c.r, min(c.g, c.b))));
+ c = mix(vec3(dot(c, vec3(0.2126, 0.7152, 0.0722))), c, sat);
+ outputColor = vec4(pow(max(c, 0.0), vec3(2.2)), inputColor.a);
+}
+`;
+
+class GradeEffect extends Effect {
+ constructor() {
+ super("GradeEffect", gradeFrag, { blendFunction: BlendFunction.NORMAL });
+ }
+}
+
+function Grade() {
+ const effect = useMemo(() => new GradeEffect(), []);
+ useEffect(() => () => effect.dispose(), [effect]);
+ return
+ {effects}
+
+
+ );
+});
diff --git a/web/src/components/guide/stage/look/accent.ts b/web/src/components/guide/stage/look/accent.ts
new file mode 100644
index 00000000..0621009b
--- /dev/null
+++ b/web/src/components/guide/stage/look/accent.ts
@@ -0,0 +1,28 @@
+import * as THREE from "three";
+import { accentNow } from "../../ui/panelTint";
+
+// The page's accent, for what the stage draws in it.
+//
+// The page takes its accent from the panel (ui/panelTint.ts): the dot on the
+// card being read, the chapter rail, a link's underline are the colour of the
+// pattern playing. The stage's drawn light โ the Wi-Fi's arcs, the stream of
+// a deck arriving โ used to stay the LED orange it was written in, and with
+// the panel on a blue pattern the screen had two accents: a blue page, and
+// orange arcs running into it. They are the page's signs, not the device's,
+// so they take the page's colour: the very one it has now, eased and fenced
+// as the page's is, not a second reading of the panel that could differ.
+//
+// What stays orange is what answers to the device itself: the dots on the
+// knobs' dials and the tags beside them (Guide.module.css --g-led-fixed).
+
+const ORANGE = new THREE.Color("#ff6a3d");
+const now = new THREE.Color().copy(ORANGE);
+
+/** The accent as light (the renderer's linear colour). The same object every call: copy it to keep it. */
+export function stageAccent(): THREE.Color {
+ const [r, g, b] = accentNow();
+ // Whatever the page's loop is doing, the stage is never handed a colour that is not one.
+ if (Number.isFinite(r + g + b)) now.setRGB(r / 255, g / 255, b / 255, THREE.SRGBColorSpace);
+ else now.copy(ORANGE);
+ return now;
+}
diff --git a/web/src/components/guide/stage/look/dominant.ts b/web/src/components/guide/stage/look/dominant.ts
new file mode 100644
index 00000000..84a6c821
--- /dev/null
+++ b/web/src/components/guide/stage/look/dominant.ts
@@ -0,0 +1,110 @@
+// The dominant colour of what the panel shows. (No three.js here: the page's
+// own bundle reads a frame with this before the stage has loaded.)
+//
+// It used to be a mean โ every coloured LED's colour, weighed by how coloured
+// and how bright it was. A mean of one colour is that colour; a mean of two
+// is neither. Blue squares with an orange slider over them gave the page a
+// salmon pink that was nowhere on the panel, and as the squares and the
+// slider traded places the page hopped between pink, lilac and sky.
+//
+// So the hues are counted instead: a histogram of 24 bins round the wheel,
+// each LED adding its weight (how coloured ร how bright) to its hue's bin,
+// and the colour that is handed on is the one in the fullest bin โ a colour
+// that is on the panel. Two things keep it from flickering between two bins
+// that are nearly as full: a bin's count includes half of each neighbour's
+// (a hue that falls on a bin's edge is not split in two), and the bin that
+// was the fullest last time stays the answer until another beats it by a
+// quarter.
+
+export const HUE_BINS = 24;
+/** Another hue takes over when its bin is this many times as full as the one held. */
+const TAKE_OVER = 1.25;
+
+export type HueHistogram = {
+ w: Float32Array;
+ r: Float32Array;
+ g: Float32Array;
+ b: Float32Array;
+ /** The bin held from the last read (โ1: none yet). */
+ held: number;
+};
+
+export function hueHistogram(): HueHistogram {
+ return { w: new Float32Array(HUE_BINS), r: new Float32Array(HUE_BINS), g: new Float32Array(HUE_BINS), b: new Float32Array(HUE_BINS), held: -1 };
+}
+
+export function clearHues(h: HueHistogram) {
+ h.w.fill(0);
+ h.r.fill(0);
+ h.g.fill(0);
+ h.b.fill(0);
+}
+
+/**
+ * Count one LED: `r`, `g`, `b` on any one scale (0โฆ1 or 0โฆ255, light or
+ * bytes โ the answer comes back on the same), `w` its weight. Returns nothing;
+ * a grey LED (no hue) is not counted.
+ */
+export function addHue(h: HueHistogram, r: number, g: number, b: number, w: number) {
+ const max = r > g ? (r > b ? r : b) : g > b ? g : b;
+ const min = r < g ? (r < b ? r : b) : g < b ? g : b;
+ const d = max - min;
+ if (d <= 0 || w <= 0) return;
+ // The hue, in sixths of the wheel: 0 red, 2 green, 4 blue.
+ let six = max === r ? (g - b) / d : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+ if (six < 0) six += 6;
+ const bin = Math.min(HUE_BINS - 1, Math.floor((six / 6) * HUE_BINS));
+ h.w[bin] += w;
+ h.r[bin] += r * w;
+ h.g[bin] += g * w;
+ h.b[bin] += b * w;
+}
+
+function score(h: HueHistogram, i: number) {
+ return h.w[i] + 0.5 * (h.w[(i + HUE_BINS - 1) % HUE_BINS] + h.w[(i + 1) % HUE_BINS]);
+}
+
+/**
+ * The dominant colour of what was counted, written to `out` at full value
+ * (its largest channel 1), and how much of all the colour counted is that
+ * hue, 0โฆ1 (a rainbow: about an eighth; one colour: 1). Returns 0, and
+ * leaves `out`, when nothing with a hue was counted.
+ */
+export function dominantHue(h: HueHistogram, out: { r: number; g: number; b: number }): number {
+ let best = -1;
+ let bestScore = 0;
+ let total = 0;
+ for (let i = 0; i < HUE_BINS; i++) {
+ total += h.w[i];
+ const s = score(h, i);
+ if (s > bestScore) {
+ bestScore = s;
+ best = i;
+ }
+ }
+ if (best < 0 || total <= 0) {
+ h.held = -1;
+ return 0;
+ }
+ // The hue held stays, unless another is clearly ahead of it now.
+ if (h.held >= 0 && h.held !== best && score(h, h.held) * TAKE_OVER >= bestScore) best = h.held;
+ h.held = best;
+ const a = (best + HUE_BINS - 1) % HUE_BINS;
+ const c = (best + 1) % HUE_BINS;
+ // The colour of that bin, with what little of it fell just over either edge.
+ const r = h.r[best] + 0.5 * (h.r[a] + h.r[c]);
+ const g = h.g[best] + 0.5 * (h.g[a] + h.g[c]);
+ const b = h.b[best] + 0.5 * (h.b[a] + h.b[c]);
+ const peak = Math.max(r, g, b);
+ if (peak <= 0) return 0;
+ out.r = r / peak;
+ out.g = g / peak;
+ out.b = b / peak;
+ return Math.min(1, (h.w[best] + h.w[a] + h.w[c]) / total);
+}
+
+/** How much a pattern has one colour to follow, from the dominant hue's share of it: a rainbow has none. */
+export function oneColour(share: number): number {
+ const t = Math.min(1, Math.max(0, (share - 0.16) / (0.4 - 0.16)));
+ return t * t * (3 - 2 * t);
+}
diff --git a/web/src/components/guide/stage/look/focus.ts b/web/src/components/guide/stage/look/focus.ts
new file mode 100644
index 00000000..647a56ad
--- /dev/null
+++ b/web/src/components/guide/stage/look/focus.ts
@@ -0,0 +1,7 @@
+import * as THREE from "three";
+
+// Where the camera is looking and from how far, for the depth of field
+// (StagePost.tsx). The camera rig (GuideCanvas) writes it every frame: the
+// point its springs have the camera aimed at, and the distance to it.
+
+export const stageFocus = { target: new THREE.Vector3(), r: 10 };
diff --git a/web/src/components/guide/stage/look/ledPanel.ts b/web/src/components/guide/stage/look/ledPanel.ts
new file mode 100644
index 00000000..2c89242b
--- /dev/null
+++ b/web/src/components/guide/stage/look/ledPanel.ts
@@ -0,0 +1,144 @@
+import * as THREE from "three";
+import { PANEL_H, PANEL_W } from "@/lib/guide/panelScreens";
+
+// The LED panel's face.
+//
+// From where the whole device is seen it is an image: 128 ร 64 LEDs are a
+// pixel or two each and the eye โ and the texture filter โ blend them. As the
+// camera comes close they come apart into what they are: a grid of small
+// emitters, each a lit window in a black package, bright in the middle and
+// falling off toward its edge, with black between them.
+//
+// The change-over is by how many screen pixels an LED covers, and it is made
+// so that it cannot shimmer: an emitter is only drawn as a dot while its soft
+// profile is a good pixel wide or more (a narrower dot would beat against the
+// pixel grid as the camera moves โ moirรฉ), and below that the face is the
+// filtered image, which the mipmaps keep still at any distance.
+//
+// The frame is the firmware's: sRGB bytes, the values a pattern was drawn
+// with. The texture decodes them to light (SRGBColorSpace), so a mid grey is
+// a fifth of full power, as it is on the real panel after the driver's gamma,
+// and the room light, the bloom and the tone curve all work on light.
+//
+// The mesh ("l" of the landing model) is the whole panel, not only its face:
+// its rim, sides and back are the moulded black frame, and they are drawn as
+// that โ dark plastic under the key light โ instead of with the pattern
+// smeared over them, which showed when the device comes apart.
+
+/** LEDs across and up, as the panel stands in the device (portrait). */
+const ACROSS = PANEL_H;
+const UP = PANEL_W;
+
+/** How bright a full-power LED is, in the stage's light (the white case under the key is about 1). */
+export const LED_GAIN = 1.5;
+
+const vertex = /* glsl */ `
+varying vec2 vUv;
+varying vec3 vObjN;
+varying vec3 vViewN;
+varying vec3 vViewPos;
+void main() {
+ vUv = uv;
+ vObjN = normal;
+ vec4 mv = modelViewMatrix * vec4(position, 1.0);
+ vViewPos = mv.xyz;
+ vViewN = normalMatrix * normal;
+ gl_Position = projectionMatrix * mv;
+}
+`;
+
+const fragment = /* glsl */ `
+uniform sampler2D uTex;
+uniform float uPower;
+uniform float uGain;
+varying vec2 vUv;
+varying vec3 vObjN;
+varying vec3 vViewN;
+varying vec3 vViewPos;
+
+const vec2 GRID = vec2(${ACROSS.toFixed(1)}, ${UP.toFixed(1)});
+
+void main() {
+ vec3 n = normalize(vViewN);
+ vec3 v = normalize(-vViewPos);
+ // The room's key light (GuideCanvas: from above right, in front), for what little a black surface shows of it.
+ vec3 key = normalize((viewMatrix * vec4(0.41, 0.58, 0.7, 0.0)).xyz);
+ float diff = max(dot(n, key), 0.0);
+
+ // Not the face: the moulded frame.
+ if (vObjN.y > -0.5) {
+ float spec = pow(max(dot(n, normalize(key + v)), 0.0), 28.0);
+ float rim = pow(1.0 - max(dot(n, v), 0.0), 3.0);
+ gl_FragColor = vec4(vec3(0.012) + vec3(0.045) * diff + vec3(0.05) * spec + vec3(0.016) * rim, 1.0);
+ return;
+ }
+
+ vec2 g = vUv * GRID;
+ vec2 gw = fwidth(g);
+ // LEDs per screen pixel, along the worse of the two directions.
+ float fw = max(gw.x, gw.y);
+
+ // The frame's x runs up the device, its y across.
+ vec2 smoothUv = vec2(vUv.y, 1.0 - vUv.x);
+ vec2 cell = (floor(g) + 0.5) / GRID;
+ vec2 cellUv = vec2(cell.y, 1.0 - cell.x);
+ // Up close each LED is one value; once LEDs are smaller than about two
+ // pixels the filter takes over. The mip level follows the true footprint
+ // either way (the snapped coordinate has no gradient of its own).
+ float far = smoothstep(0.4, 1.0, fw);
+ vec3 col = textureGrad(uTex, mix(cellUv, smoothUv, far), dFdx(smoothUv), dFdy(smoothUv)).rgb;
+ // What the lit LEDs put into their surround: the lens, the mask, the eye.
+ vec3 haze = textureLod(uTex, smoothUv, 3.0).rgb;
+
+ // An emitter: a soft round window in its cell.
+ vec2 c = fract(g) - 0.5;
+ float d2 = dot(c, c);
+ float dots = 1.0 - smoothstep(0.07, 0.24, fw);
+ float lens = exp(-d2 / 0.085);
+ float shape = mix(1.0, lens * 2.1, dots);
+
+ // Whites run hot (they are three LEDs at once, and they bloom); a single
+ // colour stays under the bloom's knee and keeps its hue through the tone curve.
+ // (Judged on the eye's scale: a light grey is already most of the way to white.)
+ float luma = pow(dot(col, vec3(0.2126, 0.7152, 0.0722)), 0.4545);
+ vec3 emit = col * uGain * (1.0 + 0.95 * smoothstep(0.55, 0.95, luma));
+ // LEDs are brightest square on, and lose a little to the side.
+ float lobe = 0.4 + 0.6 * pow(max(dot(n, v), 0.0), 0.6);
+
+ // Unlit: the black mask, and โ up close โ each package's dark window catching the room.
+ vec3 body = vec3(0.007) + vec3(0.012) * diff + vec3(0.008) * lens * dots;
+
+ gl_FragColor = vec4(body + (emit * shape + haze * uGain * 0.07) * lobe * uPower, 1.0);
+}
+`;
+
+let shared: THREE.DataTexture | null = null;
+
+/**
+ * The texture the Device writes the shown frame into each frame (bottom row
+ * first, as GL has it). One for the guide: the panel's face reads it, and so
+ * does the floor, which mirrors the panel (StageLight.tsx). Its u runs up
+ * the device and its v from the knob side to the left edge โ a point of the
+ * face at (across, up), both 0 โฆ 1, is at (up, 1 โ across).
+ */
+export function ledPanelTexture(): THREE.DataTexture {
+ if (shared) return shared;
+ const t = new THREE.DataTexture(new Uint8Array(PANEL_W * PANEL_H * 4), PANEL_W, PANEL_H, THREE.RGBAFormat);
+ t.colorSpace = THREE.SRGBColorSpace;
+ t.magFilter = THREE.LinearFilter;
+ t.minFilter = THREE.LinearMipmapLinearFilter;
+ t.generateMipmaps = true;
+ // For the face at a slant, and for the floor, which reads it through long thin footprints.
+ t.anisotropy = 8;
+ t.needsUpdate = true;
+ shared = t;
+ return t;
+}
+
+export function ledPanelMaterial(texture: THREE.Texture): THREE.ShaderMaterial {
+ return new THREE.ShaderMaterial({
+ uniforms: { uTex: { value: texture }, uPower: { value: 0 }, uGain: { value: LED_GAIN } },
+ vertexShader: vertex,
+ fragmentShader: fragment,
+ });
+}
diff --git a/web/src/components/guide/stage/look/materials.ts b/web/src/components/guide/stage/look/materials.ts
new file mode 100644
index 00000000..9bca502a
--- /dev/null
+++ b/web/src/components/guide/stage/look/materials.ts
@@ -0,0 +1,492 @@
+import * as THREE from "three";
+import { grainTexture, LAYER_TILE, layerTexture, turnedTexture } from "./textures";
+
+// What the stage's things are made of. One place for it, so the device on
+// the hub, in Play and on the Build guide's bench is the same object under
+// the same light: the Device uses these, and the Build stage's own parts
+// (its print plates, the halves of the case, its screws and nuts, its solder)
+// are meant to as well.
+//
+// Every one is a MeshStandardMaterial with a little added to its shader, so
+// it takes whatever a standard material takes โ `transparent`, `opacity`,
+// `clippingPlanes`, `side` โ through `extra`, fades and clips as before, and
+// costs one or two texture reads more than the plain material it replaces.
+// The detail is in mipmapped textures (textures.ts), so it resolves up close
+// and is simply gone from a distance, without shimmer in between.
+//
+// Sizes are in the mesh's own units. The device and the build's parts are in
+// model units, 10 mm each (geometry.ts): a 0.2 mm layer is 0.02.
+
+type Extra = Partial;
+export type Axis = "x" | "y" | "z";
+
+const AXES: Record = {
+ // [the axis, and the two directions of a face across it]
+ x: [new THREE.Vector3(1, 0, 0), new THREE.Vector3(0, 1, 0), new THREE.Vector3(0, 0, 1)],
+ y: [new THREE.Vector3(0, 1, 0), new THREE.Vector3(0, 0, 1), new THREE.Vector3(1, 0, 0)],
+ z: [new THREE.Vector3(0, 0, 1), new THREE.Vector3(1, 0, 0), new THREE.Vector3(0, 1, 0)],
+};
+
+/** The stage's colours for what is printed and what is metal. */
+export const LOOK = {
+ /** Warm white PLA: the case. */
+ pla: "#eceae4",
+ /** Black PLA: the knobs. */
+ plaBlack: "#151515",
+ /** Zinc-plated steel: the M4 screws. */
+ screw: "#c6c9ce",
+ /** Brushed steel: the encoders' bushings, washers and nuts. */
+ steel: "#8d9096",
+ /** Gold-flashed contacts: header pins, socket springs. */
+ gold: "#d9b56a",
+ /** Brass: threaded inserts. */
+ brass: "#a8853f",
+ /** Tin: HASL pads, solder. */
+ tin: "#dfe0dc",
+} as const;
+
+/**
+ * three's Material.clone() copies a material's properties but not what was
+ * put on its shader (onBeforeCompile is the instance's own), so a clone of
+ * one of these would be a plain material. The Device clones every material
+ * it is handed; so each of these knows how to make itself again.
+ */
+function cloneable(m: THREE.MeshStandardMaterial, again: () => THREE.MeshStandardMaterial): THREE.MeshStandardMaterial {
+ m.clone = function (this: THREE.MeshStandardMaterial) {
+ const c = again();
+ const own = c.userData;
+ THREE.MeshStandardMaterial.prototype.copy.call(c, this);
+ // copy() replaces userData with a JSON copy: put the new material's own (its live uniforms) back.
+ c.userData = own;
+ return c;
+ } as THREE.MeshStandardMaterial["clone"];
+ return m;
+}
+
+const VERT_COMMON = /* glsl */ `#include
+uniform vec3 uLkAxis;
+uniform vec3 uLkU;
+uniform vec3 uLkV;
+varying vec3 vLkPos;
+varying vec3 vLkN;
+varying vec3 vLkAxisV;
+varying vec3 vLkUV;
+varying vec3 vLkVV;`;
+
+// The object's own directions in view space (normalMatrix is a rotation over
+// a uniform scale for everything on the stage; the fragment normalises).
+const VERT_BEGIN = /* glsl */ `#include
+vLkPos = position;
+vLkN = normal;
+mat3 lkM = normalMatrix;
+#ifdef USE_INSTANCING
+lkM = lkM * mat3(instanceMatrix);
+#endif
+vLkAxisV = lkM * uLkAxis;`;
+
+// โโ printed PLA โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+
+export type PlaOptions = {
+ color?: THREE.ColorRepresentation;
+ roughness?: number;
+ /** The print axis in the mesh's own frame: its layers stack along it. The case, as it sits in the device, was printed lying on its face: z. On a print plate: y. */
+ axis?: Axis;
+ /** Layer height, mesh units (0.02 = 0.2 mm in model units). */
+ layer?: number;
+ /** 0 โฆ 1: how much of the print shows (1). */
+ strength?: number;
+ extra?: Extra;
+};
+
+/**
+ * Printed PLA. Its walls carry the layers โ each a rounded bead, so a wall's
+ * highlight is drawn out across them, with the faint banding of a real print
+ * โ and the faces across the print axis carry the fine tooth of the plate it
+ * lay on. All of it is finer than a pixel from where the whole device is
+ * seen, and is filtered away there; it shows as the camera comes close.
+ */
+export function plaMaterial(o: PlaOptions = {}): THREE.MeshStandardMaterial {
+ const [axis, u, v] = AXES[o.axis ?? "z"];
+ const layer = o.layer ?? 0.02;
+ const strength = o.strength ?? 1;
+ const m = new THREE.MeshStandardMaterial({ color: o.color ?? LOOK.pla, roughness: o.roughness ?? 0.56, metalness: 0, ...o.extra });
+ const uniforms = {
+ uLkAxis: { value: axis },
+ uLkU: { value: u },
+ uLkV: { value: v },
+ uLkLayers: { value: layerTexture() },
+ uLkGrain: { value: grainTexture() },
+ // 1 / a tile of layers; 1 / a tile of grain (about 12 mm in model units); the two strengths.
+ uLkScale: { value: new THREE.Vector4(1 / (LAYER_TILE * layer), 1 / (layer * 64), strength, strength) },
+ };
+ m.onBeforeCompile = (shader) => {
+ Object.assign(shader.uniforms, uniforms);
+ shader.vertexShader = shader.vertexShader
+ .replace("#include ", VERT_COMMON)
+ .replace("#include ", `${VERT_BEGIN}\nvLkUV = lkM * uLkU;\nvLkVV = lkM * uLkV;`);
+ shader.fragmentShader = shader.fragmentShader
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+uniform vec3 uLkAxis;
+uniform vec3 uLkU;
+uniform vec3 uLkV;
+uniform vec4 uLkScale;
+uniform sampler2D uLkLayers;
+uniform sampler2D uLkGrain;
+varying vec3 vLkPos;
+varying vec3 vLkN;
+varying vec3 vLkAxisV;
+varying vec3 vLkUV;
+varying vec3 vLkVV;`,
+ )
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+// A wall (its normal across the print axis) or a face (along it).
+float lkWall = smoothstep(0.3, 0.8, 1.0 - abs(dot(normalize(vLkN), uLkAxis)));
+float lkFace = 1.0 - lkWall;
+vec4 lkL = texture2D(uLkLayers, vec2(dot(vLkPos, uLkAxis) * uLkScale.x, 0.5)) - 0.5;
+vec4 lkG = texture2D(uLkGrain, vec2(dot(vLkPos, uLkU), dot(vLkPos, uLkV)) * uLkScale.y) - 0.5;
+diffuseColor.rgb *= 1.0 + lkL.b * 0.075 * lkWall * uLkScale.z;`,
+ )
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+roughnessFactor = clamp(roughnessFactor + (lkL.g * 0.3 + 0.05) * lkWall * uLkScale.z + (lkG.b * 0.2 - 0.03) * lkFace * uLkScale.w, 0.06, 1.0);`,
+ )
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+normal = normalize(normal
+ + normalize(vLkAxisV) * (lkL.r * 0.55 * lkWall * uLkScale.z)
+ + (normalize(vLkUV) * lkG.r + normalize(vLkVV) * lkG.g) * (0.42 * lkFace * uLkScale.w));`,
+ );
+ };
+ m.customProgramCacheKey = () => "look-pla-1";
+ return cloneable(m, () => plaMaterial(o));
+}
+
+/** The knobs: black PLA, printed standing on their skirts (their axis is the print's). */
+export function knobMaterial(extra?: Extra): THREE.MeshStandardMaterial {
+ return plaMaterial({ color: LOOK.plaBlack, roughness: 0.74, axis: "z", extra });
+}
+
+// โโ metal โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+
+export type MetalOptions = {
+ color?: THREE.ColorRepresentation;
+ roughness?: number;
+ metalness?: number;
+ /** The axis the part was turned about, in the mesh's own frame: the marks run round it on its end faces and round its sides. */
+ axis?: Axis;
+ /** The spacing of the broad marks, mesh units (0.05 = half a millimetre in model units). */
+ pitch?: number;
+ /** 0 โฆ 1: how strongly the marks show (1). */
+ strength?: number;
+ extra?: Extra;
+};
+
+/**
+ * Turned metal: a lathe's fine concentric marks on the end faces (a screw's
+ * head, a washer) and round the sides, as a slope and a roughness. Enough to
+ * draw a highlight out into the arc turned parts have, and no more.
+ */
+export function turnedMetal(o: MetalOptions = {}): THREE.MeshStandardMaterial {
+ const [axis] = AXES[o.axis ?? "y"];
+ const m = new THREE.MeshStandardMaterial({ color: o.color ?? LOOK.steel, roughness: o.roughness ?? 0.42, metalness: o.metalness ?? 0.9, ...o.extra });
+ const uniforms = {
+ uLkAxis: { value: axis },
+ uLkU: { value: axis },
+ uLkV: { value: axis },
+ uLkTurned: { value: turnedTexture() },
+ uLkScale: { value: new THREE.Vector4(1 / ((o.pitch ?? 0.05) * 16), 0, o.strength ?? 1, 0) },
+ };
+ m.onBeforeCompile = (shader) => {
+ Object.assign(shader.uniforms, uniforms);
+ shader.vertexShader = shader.vertexShader.replace("#include ", VERT_COMMON).replace(
+ "#include ",
+ /* glsl */ `${VERT_BEGIN}
+vec3 lkRad = position - uLkAxis * dot(position, uLkAxis);
+vLkUV = lkM * (lkRad / max(length(lkRad), 1e-5));
+vLkVV = vLkUV;`,
+ );
+ shader.fragmentShader = shader.fragmentShader
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+uniform vec3 uLkAxis;
+uniform vec4 uLkScale;
+uniform sampler2D uLkTurned;
+varying vec3 vLkPos;
+varying vec3 vLkN;
+varying vec3 vLkAxisV;
+varying vec3 vLkUV;`,
+ )
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+// An end face (marks run round the axis, read along the radius) or the side (read along the axis).
+float lkEnd = smoothstep(0.5, 0.9, abs(dot(normalize(vLkN), uLkAxis)));
+float lkAlong = dot(vLkPos, uLkAxis);
+vec4 lkT = texture2D(uLkTurned, vec2(mix(lkAlong, length(vLkPos - uLkAxis * lkAlong), lkEnd) * uLkScale.x, 0.5)) - 0.5;
+roughnessFactor = clamp(roughnessFactor + lkT.g * 0.26 * uLkScale.z, 0.06, 1.0);`,
+ )
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+normal = normalize(normal + normalize(mix(vLkAxisV, vLkUV, lkEnd) + vec3(1e-5)) * (lkT.r * 0.55 * uLkScale.z));`,
+ );
+ };
+ m.customProgramCacheKey = () => "look-turned-1";
+ return cloneable(m, () => turnedMetal(o));
+}
+
+/** Zinc-plated steel: an M4 screw (props.ts' screw stands on +y). Bright, but a satin bright โ nothing here is a mirror, mirrors bloom. */
+export function screwMaterial(extra?: Extra) {
+ return turnedMetal({ color: LOOK.screw, roughness: 0.34, metalness: 0.9, axis: "y", extra });
+}
+
+/** Brushed steel: the encoders' washers and nuts (on +y), anything turned and left satin. */
+export function steelMaterial(extra?: Extra) {
+ return turnedMetal({ color: LOOK.steel, roughness: 0.52, metalness: 0.8, axis: "y", extra });
+}
+
+/** Gold-flashed contacts: header pins, the sockets' springs. */
+export function goldMaterial(extra?: Extra) {
+ return new THREE.MeshStandardMaterial({ color: LOOK.gold, roughness: 0.34, metalness: 1, ...extra });
+}
+
+/** Brass: the panel's threaded inserts. */
+export function brassMaterial(extra?: Extra) {
+ return new THREE.MeshStandardMaterial({ color: LOOK.brass, roughness: 0.46, metalness: 0.9, ...extra });
+}
+
+// โโ solder โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+
+/**
+ * Solder, with its heat. Cold it is tin: bright, a little frosted. Hot
+ * (`heat` 1) it is liquid โ a mirror, which is how molten solder shows its
+ * heat: it does not glow (at 250 ยฐC nothing does), it goes bright and clean
+ * and frosts over as it sets. A trace of warmth is left in it, no brighter
+ * than the board round it; lit like a lamp, a row of fresh joints read as a
+ * string of LEDs. The heat is `material.userData.heat.value` for the whole material
+ * (setSolderHeat), or per instance: give the InstancedMesh's geometry an
+ * `aHeat` InstancedBufferAttribute (one float each, 0 โฆ 1) and each joint
+ * cools on its own. Without the attribute it reads 0.
+ */
+export function solderMaterial(extra?: Extra): THREE.MeshStandardMaterial {
+ const m = new THREE.MeshStandardMaterial({ color: LOOK.tin, roughness: 0.34, metalness: 1, ...extra });
+ const heat = { value: 0 };
+ m.userData.heat = heat;
+ m.onBeforeCompile = (shader) => {
+ shader.uniforms.uLkHeat = heat;
+ shader.vertexShader = shader.vertexShader
+ .replace("#include ", "#include \nattribute float aHeat;\nvarying float vLkHeat;")
+ .replace("#include ", "#include \nvLkHeat = aHeat;");
+ shader.fragmentShader = shader.fragmentShader
+ .replace("#include ", "#include \nuniform float uLkHeat;\nvarying float vLkHeat;")
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+float lkHeat = clamp(max(uLkHeat, vLkHeat), 0.0, 1.0);
+roughnessFactor = mix(roughnessFactor, 0.045, lkHeat);`,
+ )
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+totalEmissiveRadiance += vec3(1.0, 0.36, 0.08) * (lkHeat * lkHeat * 0.15);`,
+ );
+ };
+ m.customProgramCacheKey = () => "look-solder-2";
+ return cloneable(m, () => {
+ const c = solderMaterial();
+ setSolderHeat(c, heat.value);
+ return c;
+ });
+}
+
+/** The whole material's heat, 0 cold โฆ 1 molten. */
+export function setSolderHeat(m: THREE.Material, heat: number) {
+ const u = m.userData.heat as { value: number } | undefined;
+ if (u) u.value = heat;
+}
+
+// โโ the board โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+
+type Tune = { color?: string; roughness: number; metalness: number; env?: number };
+
+// pcb-v39.glb's materials, by the names KiCad's export and the footprints'
+// models give them. Most arrive as glTF's defaults โ metal, fully rough โ
+// which renders a blue capacitor sleeve and a black header as dull metal.
+//
+// Nothing on the board is a mirror. The capacitor's top and the terminals'
+// screws were bright enough metal to hand the studio's strip lights straight
+// back, over the bloom's threshold: loose parts on the bench looked lit from
+// inside. They are satin now โ stamped aluminium and plated steel are โ and
+// take less of the studio.
+const PCB_TUNE: Record = {
+ // The pads are HASL โ tin, not gold: bright, satin.
+ pad_hasl: { color: LOOK.tin, roughness: 0.3, metalness: 1 },
+ silkscreen: { color: "#f3f3ee", roughness: 0.86, metalness: 0 },
+ // C11: its aluminium top, its sleeve (a shrink film), its leads, its base.
+ mat_0: { roughness: 0.6, metalness: 1, env: 0.55 },
+ mat_1: { roughness: 0.45, metalness: 0, env: 0.8 },
+ mat_2: { roughness: 0.5, metalness: 1, env: 0.7 },
+ mat_3: { roughness: 0.6, metalness: 0 },
+ // The box header's and the pin sockets' black housings, and their gold contacts.
+ mat_8: { roughness: 0.52, metalness: 0 },
+ mat_6: { roughness: 0.52, metalness: 0 },
+ mat_9: { color: LOOK.gold, roughness: 0.32, metalness: 1 },
+ mat_7: { color: LOOK.gold, roughness: 0.32, metalness: 1 },
+ // The screw terminals: blue housings (a moulded matt), plated screws and clamps.
+ terminal_blue: { roughness: 0.62, metalness: 0, env: 0.7 },
+ mat_5: { roughness: 0.58, metalness: 1, env: 0.55 },
+ encoder_base: { roughness: 0.62, metalness: 0 },
+};
+
+// โโ the solder mask โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+//
+// The board's own material was one flat green: no sheen, nothing under it. A
+// real board is a lacquer over copper and laminate. The lacquer is a clear
+// coat โ it takes a hard, narrow highlight over a satin body โ and it is
+// paler where there is copper under it and darker where there is not, with a
+// small step at the copper's edge that catches a raking light. On this board
+// both sides are poured (a ground plane each), so what shows is the plane,
+// and every trace drawn in it by the dark line of its clearance.
+//
+// The copper is the board's own: F.Cu and B.Cu plotted from
+// hardware/pcb/kicad/patternflow.kicad_pcb with kicad-cli (pcb export svg,
+// board area only), rasterised, and packed into one image โ red is the front
+// layer, green the back (public/guide/look/pcb-v39-copper.webp). It is laid
+// on by position: the board mesh is in metres, 62 ร 116.26 mm about its
+// centre in x and z, 1.51 thick, its front face up (+y).
+
+/** The board's size in its mesh's own units (metres): x across, z along. */
+const BOARD = { w: 0.062, h: 0.11626 };
+const COPPER_URL = "/guide/look/pcb-v39-copper.webp";
+
+let copper: { tex: { value: THREE.Texture }; on: { value: number } } | null = null;
+
+/** The copper image, fetched once, the first time a board is tuned. Until it is here the board is all plane (as most of it is). */
+function copperUniforms() {
+ if (copper) return copper;
+ const blank = new THREE.DataTexture(new Uint8Array([255, 255, 0, 255]), 1, 1, THREE.RGBAFormat);
+ blank.needsUpdate = true;
+ const c = (copper = { tex: { value: blank as THREE.Texture }, on: { value: 0 } });
+ if (typeof window !== "undefined") {
+ new THREE.TextureLoader().load(
+ COPPER_URL,
+ (t) => {
+ t.colorSpace = THREE.NoColorSpace;
+ t.minFilter = THREE.LinearMipmapLinearFilter;
+ t.magFilter = THREE.LinearFilter;
+ t.generateMipmaps = true;
+ t.anisotropy = 8;
+ t.needsUpdate = true;
+ c.tex.value = t;
+ c.on.value = 1;
+ blank.dispose();
+ },
+ undefined,
+ // Without it the board is a plain lacquered green: still a board.
+ () => undefined,
+ );
+ }
+ return c;
+}
+
+/** The solder mask, in place of the board's flat green: the same name, so a second tuning finds it done. */
+function maskMaterial(from: THREE.MeshStandardMaterial): THREE.MeshPhysicalMaterial {
+ const m = new THREE.MeshPhysicalMaterial({
+ // The mask over bare laminate; over copper it is paler (below).
+ color: "#0d5626",
+ roughness: 0.5,
+ metalness: 0,
+ // A clear coat, not a mirror: at a graze the whole studio would be in it, and the board went white.
+ clearcoat: 0.5,
+ clearcoatRoughness: 0.28,
+ specularIntensity: 0.6,
+ envMapIntensity: 0.6,
+ side: from.side,
+ transparent: from.transparent,
+ opacity: from.opacity,
+ });
+ m.name = from.name;
+ const u = copperUniforms();
+ m.onBeforeCompile = (shader) => {
+ shader.uniforms.uLkCopper = u.tex;
+ shader.uniforms.uLkCopperOn = u.on;
+ shader.vertexShader = shader.vertexShader
+ .replace("#include ", "#include \nvarying vec3 vLkPos;\nvarying vec3 vLkN;\nvarying vec3 vLkXV;\nvarying vec3 vLkZV;")
+ .replace("#include ", "#include \nvLkPos = position;\nvLkN = normal;\nvLkXV = normalMatrix * vec3(1.0, 0.0, 0.0);\nvLkZV = normalMatrix * vec3(0.0, 0.0, 1.0);");
+ shader.fragmentShader = shader.fragmentShader
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+uniform sampler2D uLkCopper;
+uniform float uLkCopperOn;
+varying vec3 vLkPos;
+varying vec3 vLkN;
+varying vec3 vLkXV;
+varying vec3 vLkZV;
+// How much copper is under the mask at a point of the board, on the face being looked at.
+float lkCopper(vec2 uv, float front) {
+ vec2 c = texture2D(uLkCopper, uv).rg;
+ return mix(c.g, c.r, front);
+}`,
+ )
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+// The image's top row is the board's far end (โz); a texture is loaded bottom row first.
+vec2 lkUv = vec2(vLkPos.x / ${BOARD.w} + 0.5, 0.5 - vLkPos.z / ${BOARD.h});
+float lkFront = step(0.0, vLkN.y);
+// Not on the board's cut edge: that is bare laminate.
+float lkFace = smoothstep(0.5, 0.9, abs(vLkN.y));
+float lkCu = lkCopper(lkUv, lkFront);
+diffuseColor.rgb *= 1.0 + 0.36 * lkCu * lkFace;`,
+ )
+ .replace(
+ "#include ",
+ /* glsl */ `#include
+// The copper's edge under the lacquer: a step of a few hundredths of a millimetre, enough to catch a raking light.
+vec2 lkStep = vec2(0.6 / 1024.0, 0.6 / 1920.0);
+float lkDx = lkCopper(lkUv + vec2(lkStep.x, 0.0), lkFront) - lkCopper(lkUv - vec2(lkStep.x, 0.0), lkFront);
+float lkDz = lkCopper(lkUv - vec2(0.0, lkStep.y), lkFront) - lkCopper(lkUv + vec2(0.0, lkStep.y), lkFront);
+normal = normalize(normal - (normalize(vLkXV) * lkDx + normalize(vLkZV) * lkDz) * (0.22 * lkFace * uLkCopperOn));`,
+ );
+ };
+ m.customProgramCacheKey = () => "look-mask-1";
+ return m;
+}
+
+/**
+ * Sets the board's materials (pcb-v39.glb, and its parts wherever they have
+ * been hung) to what the parts are made of. Safe to call again: it sets
+ * values, and the one material it replaces (the board's own, by the solder
+ * mask) it replaces once โ so a material faded or made transparent elsewhere
+ * stays as it was.
+ */
+export function tunePcbMaterials(root: THREE.Object3D) {
+ root.traverse((o) => {
+ const mesh = o as THREE.Mesh;
+ if (!mesh.isMesh) return;
+ // The board itself: its flat green is replaced, once, by the mask.
+ const own = mesh.material as THREE.MeshStandardMaterial;
+ if (!Array.isArray(own) && own.name === "pcb_green" && !(own as THREE.MeshPhysicalMaterial).isMeshPhysicalMaterial) {
+ mesh.material = maskMaterial(own);
+ own.dispose();
+ return;
+ }
+ for (const mat of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
+ const std = mat as THREE.MeshStandardMaterial;
+ const tune = PCB_TUNE[std.name];
+ if (!tune || !std.isMeshStandardMaterial) continue;
+ if (tune.color) std.color.set(tune.color);
+ std.roughness = tune.roughness;
+ std.metalness = tune.metalness;
+ if (tune.env) std.envMapIntensity = tune.env;
+ }
+ });
+}
diff --git a/web/src/components/guide/stage/look/panelGlow.ts b/web/src/components/guide/stage/look/panelGlow.ts
new file mode 100644
index 00000000..6eed9503
--- /dev/null
+++ b/web/src/components/guide/stage/look/panelGlow.ts
@@ -0,0 +1,123 @@
+import * as THREE from "three";
+import { PANEL_H, PANEL_W } from "@/lib/guide/panelScreens";
+import { addHue, clearHues, dominantHue, hueHistogram, oneColour } from "./dominant";
+
+// The light the LED panel is giving off, read from the frame it is showing.
+//
+// The Device samples the frame it has just put on the panel (what is *shown*:
+// the simulator's frame, held and faded when the power goes) and writes the
+// result here every other frame; the stage's lights, the floor and the air
+// round the panel read it. Anything else may too โ it is plain data, read it
+// from a frame loop or subscribe.
+//
+// The panel stands portrait: the frame's x runs up the device (x 0 at the
+// foot, 127 at the top), its y across (y 0 at the left edge, 63 by the
+// knobs). `bands` are along the device's height, foot first.
+
+/** How many bands the panel's height is read in. */
+export const GLOW_BANDS = 3;
+
+export type PanelGlow = {
+ /** The whole panel's mean light, linear RGB, power applied: black when it is dark. */
+ mean: THREE.Color;
+ /** The same per band up the device's height: [foot, middle, top]. */
+ bands: THREE.Color[];
+ /** What colour the light is: the pattern's dominant colour (look/dominant.ts โ one that is on the panel, not an average of several) at full value, linear RGB, eased. Meaningless while `colour` is 0. */
+ hue: THREE.Color;
+ /** 0 โฆ 1: how much the panel has a colour to follow (0: dark, white and grey only, or every hue at once), eased. */
+ colour: number;
+ /** 0 โฆ 1: how lit the panel is (its mean luminance, linear), eased. */
+ lit: number;
+ /** 0 โฆ 1: the panel's power as shown (it fades when the power is cut). */
+ power: number;
+};
+
+export const panelGlow: PanelGlow = {
+ mean: new THREE.Color(0, 0, 0),
+ bands: Array.from({ length: GLOW_BANDS }, () => new THREE.Color(0, 0, 0)),
+ hue: new THREE.Color(1, 0.14, 0.05),
+ colour: 0,
+ lit: 0,
+ power: 0,
+};
+
+// sRGB byte โ linear light.
+const LIN = new Float32Array(256);
+for (let i = 0; i < 256; i++) {
+ const v = i / 255;
+ LIN[i] = v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+
+const STEP = 4; // every 4th LED each way: 32 ร 16 samples
+const acc = new Float32Array(GLOW_BANDS * 3);
+const count = new Uint16Array(GLOW_BANDS);
+const hues = hueHistogram();
+const lead = { r: 0, g: 0, b: 0 };
+
+/**
+ * Read a frame (PANEL_W ร PANEL_H RGBA bytes, any row order) at `power`
+ * (0 โฆ 1) and ease the signal toward it; `dt` is the time since the last
+ * read, seconds.
+ */
+export function readPanelGlow(frame: ArrayLike, power: number, dt: number) {
+ acc.fill(0);
+ count.fill(0);
+ clearHues(hues);
+ let weight = 0;
+ let n = 0;
+ for (let y = STEP >> 1; y < PANEL_H; y += STEP) {
+ const row = y * PANEL_W * 4;
+ for (let x = STEP >> 1; x < PANEL_W; x += STEP) {
+ const i = row + x * 4;
+ const r = LIN[frame[i]];
+ const g = LIN[frame[i + 1]];
+ const b = LIN[frame[i + 2]];
+ const band = Math.min(GLOW_BANDS - 1, Math.floor((x * GLOW_BANDS) / PANEL_W)) * 3;
+ acc[band] += r;
+ acc[band + 1] += g;
+ acc[band + 2] += b;
+ count[band / 3]++;
+ const max = r > g ? (r > b ? r : b) : g > b ? g : b;
+ const min = r < g ? (r < b ? r : b) : g < b ? g : b;
+ // Coloured and bright counts; a dim wash of colour counts little.
+ const w = (max - min) * max;
+ addHue(hues, r, g, b, w);
+ weight += w;
+ n++;
+ }
+ }
+ const g = panelGlow;
+ // The light itself follows at once (it is light); a short ease only takes the edge off a pattern that flickers.
+ const quick = 1 - Math.exp(-dt / 0.06);
+ let mr = 0;
+ let mg = 0;
+ let mb = 0;
+ for (let k = 0; k < GLOW_BANDS; k++) {
+ const c = Math.max(1, count[k]);
+ const r = (acc[k * 3] / c) * power;
+ const gg = (acc[k * 3 + 1] / c) * power;
+ const b = (acc[k * 3 + 2] / c) * power;
+ const band = g.bands[k];
+ band.r += (r - band.r) * quick;
+ band.g += (gg - band.g) * quick;
+ band.b += (b - band.b) * quick;
+ mr += band.r;
+ mg += band.g;
+ mb += band.b;
+ }
+ g.mean.setRGB(mr / GLOW_BANDS, mg / GLOW_BANDS, mb / GLOW_BANDS);
+ g.power = power;
+ // What colour it is, and how much: slower, so a hue turns rather than jumps.
+ const slow = 1 - Math.exp(-dt / 0.3);
+ const lum = 0.2126 * g.mean.r + 0.7152 * g.mean.g + 0.0722 * g.mean.b;
+ g.lit += (Math.min(1, lum / 0.04) - g.lit) * slow;
+ // The dominant hue's colour, and how much of the pattern's colour it is.
+ const share = weight > 1e-5 ? dominantHue(hues, lead) : 0;
+ const colour = n ? Math.min(1, weight / n / 0.03) * Math.min(1, power * 4) * oneColour(share) : 0;
+ g.colour += (colour - g.colour) * slow;
+ if (share > 0) {
+ g.hue.r += (lead.r - g.hue.r) * slow;
+ g.hue.g += (lead.g - g.hue.g) * slow;
+ g.hue.b += (lead.b - g.hue.b) * slow;
+ }
+}
diff --git a/web/src/components/guide/stage/look/quality.ts b/web/src/components/guide/stage/look/quality.ts
new file mode 100644
index 00000000..4ee56579
--- /dev/null
+++ b/web/src/components/guide/stage/look/quality.ts
@@ -0,0 +1,192 @@
+import { useSyncExternalStore } from "react";
+
+// How much the stage draws, decided by how long its frames really take.
+//
+// Three tiers. Every machine starts on the first (a phone-sized screen starts
+// with a phone's settings of it); a machine whose frames run long is stepped
+// down โ the expensive parts first, the ones least missed โ and never back up
+// in the same visit, so the picture does not flip between two looks. The step
+// is remembered for the tab's session, so the next page of the guide starts
+// where this one settled.
+//
+// 0 everything: depth of field, ambient occlusion, multisampling, the
+// screen's full pixel ratio (up to 2)
+// 1 no depth of field, a pixel ratio of 1.5 at most, lighter occlusion
+// 2 no occlusion, no multisampling (an edge filter instead), one canvas
+// pixel per CSS pixel, a smaller shadow map
+//
+// (A phone's three are its own โ settingsFor.)
+//
+// The bloom, the tone curve, the panel's own light and the materials stay at
+// every tier: they are what the stage looks like, and cost little.
+//
+// ?gq=0|1|2 pins a tier (and stops the measuring), for looking at each.
+
+export type Tier = 0 | 1 | 2;
+
+const KEY = "pf-guide-tier";
+
+function pinned(): Tier | null {
+ if (typeof window === "undefined") return null;
+ const q = new URLSearchParams(window.location.search).get("gq");
+ return q === "0" || q === "1" || q === "2" ? (Number(q) as Tier) : null;
+}
+
+function initial(): Tier {
+ const pin = pinned();
+ if (pin !== null) return pin;
+ try {
+ const s = window.sessionStorage.getItem(KEY);
+ if (s === "1" || s === "2") return Number(s) as Tier;
+ } catch {
+ // No storage (private mode): measure again.
+ }
+ return 0;
+}
+
+let tier: Tier | null = null;
+const listeners = new Set<() => void>();
+
+export function getTier(): Tier {
+ if (typeof window === "undefined") return 0;
+ return (tier ??= initial());
+}
+
+function setTier(next: Tier) {
+ if (next === getTier()) return;
+ tier = next;
+ try {
+ window.sessionStorage.setItem(KEY, String(next));
+ } catch {
+ // Not remembered, then.
+ }
+ listeners.forEach((l) => l());
+}
+
+// In development, step it by hand from the console: __pfSetTier(1).
+if (typeof window !== "undefined" && process.env.NODE_ENV !== "production") {
+ (window as unknown as { __pfSetTier?: (t: Tier) => void }).__pfSetTier = setTier;
+}
+
+function subscribe(l: () => void) {
+ listeners.add(l);
+ return () => {
+ listeners.delete(l);
+ };
+}
+
+/** The tier, for a component: re-renders when the stage is stepped down. */
+export function useTier(): Tier {
+ return useSyncExternalStore(subscribe, getTier, () => 0);
+}
+
+export type Settings = {
+ /** The most canvas pixels per CSS pixel. */
+ dpr: number;
+ /** MSAA samples of the frame the effects are drawn from (0: none). */
+ msaa: number;
+ /** A cheap edge filter after the fact, where there is no multisampling and the pixels are big enough to show it. */
+ fxaa: boolean;
+ /** Ambient occlusion: off, or its quality. */
+ ao: false | "performance" | "medium";
+ /** Depth of field. */
+ dof: boolean;
+ /** The key light's shadow map, pixels a side. */
+ shadow: number;
+};
+
+/**
+ * What a tier draws. A narrow screen (a phone) has no occlusion and no depth
+ * of field: its pixels are small and its GPU is not. It does have its edges
+ * smoothed at every tier โ it used to have nothing at the two it lands on,
+ * drawn at 1.5 canvas pixels to a 3ร screen's 3, and the seam along the
+ * case's foot came out as a row of dashes. Multisampling at the first (two
+ * samples: a phone's tiled GPU resolves them almost for nothing) and an edge
+ * filter after it; never both โ the filter is a pass of its own, and under
+ * multisampling a second pass is the resolve that fails (StagePost).
+ */
+export function settingsFor(t: Tier, narrow: boolean): Settings {
+ if (narrow) {
+ if (t === 0) return { dpr: 2, msaa: 2, fxaa: false, ao: false, dof: false, shadow: 2048 };
+ if (t === 1) return { dpr: 1.5, msaa: 0, fxaa: true, ao: false, dof: false, shadow: 1024 };
+ return { dpr: 1, msaa: 0, fxaa: true, ao: false, dof: false, shadow: 1024 };
+ }
+ if (t === 0) return { dpr: 2, msaa: 4, fxaa: false, ao: "medium", dof: true, shadow: 2048 };
+ if (t === 1) return { dpr: 1.5, msaa: 4, fxaa: false, ao: "performance", dof: false, shadow: 2048 };
+ return { dpr: 1, msaa: 0, fxaa: true, ao: false, dof: false, shadow: 1024 };
+}
+
+// โโ the measuring โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+//
+// The median of a window of frames: a median, because one long frame (a
+// shader built, a model parsed) says nothing about the machine. Two windows
+// in a row over the limit and the stage steps down; then it waits for the new
+// settings to take before it measures again.
+//
+// The windows are lengths of time, not counts of frames. Counted in frames
+// (120 of them, twice) the wait was four seconds at 60 a second and most of
+// a minute at 12 โ the slower the machine, the longer it was left struggling,
+// and one slower than four frames a second was never stepped down at all,
+// because its frames were thrown away as "the tab was away".
+
+/** A window, ms, and the fewest frames one must hold to be judged. */
+const WINDOW_MS = 1200;
+const MIN_FRAMES = 8;
+/** Slower than this is not smooth: 45 frames a second. */
+const LIMIT_MS = 22;
+/** This slow, and the top tier's next step would not be enough: straight to the last. */
+const FAR_MS = 40;
+/** After a step: the composer is rebuilt and the canvas resized. Not measured for this long, ms. */
+const REST_MS = 900;
+/** A gap this long is the tab coming back, not a frame, ms. */
+const AWAY_MS = 2000;
+
+const samples: number[] = [];
+let span = 0;
+let strikes = 0;
+let restUntil = 0;
+let last = 0;
+
+/** For the look of it in development: the last window's median, ms. */
+export const qualityProbe = { median: 0, tier: 0 as Tier };
+
+/**
+ * Call once a frame with the frame's time, ms. `settled` is false while the
+ * stage is doing something that is slow for its own reasons โ loading, a
+ * page changing, the Build stage warming its shaders โ and those frames are
+ * not counted.
+ */
+export function measureFrame(ms: number, settled: boolean) {
+ if (pinned() !== null) return;
+ const now = performance.now();
+ // A tab that was away, or the first frame: start over. (A long frame is a
+ // slow machine's frame unless the gap says the tab was not being drawn.)
+ if (!settled || document.hidden || now - last > AWAY_MS || last === 0) {
+ last = now;
+ samples.length = 0;
+ span = 0;
+ return;
+ }
+ last = now;
+ if (now < restUntil) return;
+ samples.push(ms);
+ span += ms;
+ if (span < WINDOW_MS || samples.length < MIN_FRAMES) return;
+ samples.sort((a, b) => a - b);
+ const median = samples[samples.length >> 1];
+ samples.length = 0;
+ span = 0;
+ qualityProbe.median = median;
+ qualityProbe.tier = getTier();
+ if (median <= LIMIT_MS) {
+ strikes = 0;
+ return;
+ }
+ if (++strikes < 2) return;
+ strikes = 0;
+ const t = getTier();
+ if (t < 2) {
+ setTier(median > FAR_MS ? 2 : ((t + 1) as Tier));
+ restUntil = now + REST_MS;
+ }
+}
diff --git a/web/src/components/guide/stage/look/textures.ts b/web/src/components/guide/stage/look/textures.ts
new file mode 100644
index 00000000..e0819896
--- /dev/null
+++ b/web/src/components/guide/stage/look/textures.ts
@@ -0,0 +1,148 @@
+import * as THREE from "three";
+
+// The stage's surface detail, made here rather than downloaded: three small
+// tiling textures, each built once and shared by every material that uses it.
+// They carry what a surface does to light at the scale of a tenth of a
+// millimetre โ a print's layers, the pebble of a textured build plate, the
+// grooves a lathe leaves โ as a slope, a roughness and a shade, and they are
+// mipmapped: from further away than the detail can be resolved the filter
+// averages it to nothing, so nothing shimmers when the camera moves. A
+// procedural line in the shader would alias exactly where these fade.
+
+function seeded(seed: number) {
+ let s = seed >>> 0;
+ return () => {
+ s = (s + 0x6d2b79f5) >>> 0;
+ let t = s;
+ t = Math.imul(t ^ (t >>> 15), t | 1);
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+ };
+}
+
+const byte = (v: number) => Math.max(0, Math.min(255, Math.round(127.5 + 127.5 * v)));
+
+function finish(t: THREE.DataTexture, wrapT: THREE.Wrapping) {
+ t.wrapS = THREE.RepeatWrapping;
+ t.wrapT = wrapT;
+ t.magFilter = THREE.LinearFilter;
+ t.minFilter = THREE.LinearMipmapLinearFilter;
+ t.generateMipmaps = true;
+ t.anisotropy = 8;
+ t.colorSpace = THREE.NoColorSpace;
+ t.needsUpdate = true;
+ return t;
+}
+
+/** Layers in one tile of the layer texture, and texels across a layer. */
+export const LAYER_TILE = 128;
+const LAYER_TEXELS = 8;
+
+let layers: THREE.DataTexture | null = null;
+
+/**
+ * A printed wall, read across its layers: one tile is LAYER_TILE layers.
+ * R the surface's slope along the print axis (each layer is a rounded
+ * bead: it leans one way coming out of a groove and the other going in)
+ * G roughness (the grooves are duller; no two layers went down alike)
+ * B shade (the grooves hold a little shadow; bands a few layers wide โ
+ * the faint striping every print has)
+ * 0.5 is "no change" in each.
+ */
+export function layerTexture(): THREE.DataTexture {
+ if (layers) return layers;
+ const rand = seeded(20260931);
+ const w = LAYER_TILE * LAYER_TEXELS;
+ const data = new Uint8Array(w * 4);
+ // Per layer: its own small difference, and a slow drift over several layers (periodic, so the tile repeats without a seam).
+ const own = Array.from({ length: LAYER_TILE }, () => rand() * 2 - 1);
+ const knots = Array.from({ length: 16 }, () => rand() * 2 - 1);
+ const drift = (i: number) => {
+ const x = (i / LAYER_TILE) * knots.length;
+ const a = Math.floor(x) % knots.length;
+ const b = (a + 1) % knots.length;
+ const f = x - Math.floor(x);
+ const s = f * f * (3 - 2 * f);
+ return knots[a] + (knots[b] - knots[a]) * s;
+ };
+ for (let i = 0; i < LAYER_TILE; i++) {
+ const d = drift(i);
+ const dNext = drift(i + 1);
+ for (let k = 0; k < LAYER_TEXELS; k++) {
+ const s = ((k + 0.5) / LAYER_TEXELS) * 2 - 1; // โ1 โฆ 1 across the bead
+ const groove = Math.abs(s) ** 3;
+ const o = (i * LAYER_TEXELS + k) * 4;
+ // The bead's own slope, and the lean of a band that stands a hair proud of the next.
+ data[o] = byte(s * 0.85 + (dNext - d) * 0.15);
+ data[o + 1] = byte(groove * 0.55 - 0.14 + own[i] * 0.22 + d * 0.3);
+ data[o + 2] = byte(-groove * 0.6 + 0.15 + own[i] * 0.3 + d * 0.35);
+ data[o + 3] = 255;
+ }
+ }
+ layers = finish(new THREE.DataTexture(data, w, 1, THREE.RGBAFormat), THREE.ClampToEdgeWrapping);
+ return layers;
+}
+
+let grain: THREE.DataTexture | null = null;
+
+/**
+ * The face a print lay on: the fine pebble of a textured PEI plate, and much
+ * the same tooth for any moulded matt plastic. RG is the slope in the two
+ * directions of the face, B roughness; 0.5 is "no change".
+ */
+export function grainTexture(): THREE.DataTexture {
+ if (grain) return grain;
+ const n = 128;
+ const rand = seeded(7_190_423);
+ let h = new Float32Array(n * n);
+ for (let i = 0; i < h.length; i++) h[i] = rand() * 2 - 1;
+ // Two wrapped box blurs: pebbles a few texels across.
+ for (let pass = 0; pass < 2; pass++) {
+ const out = new Float32Array(n * n);
+ for (let y = 0; y < n; y++) {
+ for (let x = 0; x < n; x++) {
+ let sum = 0;
+ for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) sum += h[((y + dy + n) % n) * n + ((x + dx + n) % n)];
+ out[y * n + x] = sum / 9;
+ }
+ }
+ h = out;
+ }
+ const data = new Uint8Array(n * n * 4);
+ for (let y = 0; y < n; y++) {
+ for (let x = 0; x < n; x++) {
+ const at = (xx: number, yy: number) => h[((yy + n) % n) * n + ((xx + n) % n)];
+ const o = (y * n + x) * 4;
+ data[o] = byte((at(x + 1, y) - at(x - 1, y)) * 3.2);
+ data[o + 1] = byte((at(x, y + 1) - at(x, y - 1)) * 3.2);
+ data[o + 2] = byte(at(x, y) * 2.4);
+ data[o + 3] = 255;
+ }
+ }
+ grain = finish(new THREE.DataTexture(data, n, n, THREE.RGBAFormat), THREE.RepeatWrapping);
+ return grain;
+}
+
+let turned: THREE.DataTexture | null = null;
+
+/**
+ * Turned or brushed metal, read across the tool's marks: R the slope across
+ * them, G roughness; 0.5 is "no change". Fine marks over a few broader ones.
+ */
+export function turnedTexture(): THREE.DataTexture {
+ if (turned) return turned;
+ const w = 512;
+ const rand = seeded(55_210_917);
+ const data = new Uint8Array(w * 4);
+ const broad = Array.from({ length: 32 }, () => rand() * 2 - 1);
+ for (let i = 0; i < w; i++) {
+ const b = broad[Math.floor((i / w) * broad.length)];
+ const o = i * 4;
+ data[o] = byte((rand() * 2 - 1) * 0.75 + b * 0.25);
+ data[o + 1] = byte((rand() * 2 - 1) * 0.5 + b * 0.4);
+ data[o + 2] = 128;
+ data[o + 3] = 255;
+ }
+ turned = finish(new THREE.DataTexture(data, w, 1, THREE.RGBAFormat), THREE.ClampToEdgeWrapping);
+ return turned;
+}
diff --git a/web/src/components/guide/stage/tags.ts b/web/src/components/guide/stage/tags.ts
index 0f108465..a8ce3f06 100644
--- a/web/src/components/guide/stage/tags.ts
+++ b/web/src/components/guide/stage/tags.ts
@@ -48,6 +48,32 @@ export function pillSize(el: HTMLElement) {
return s;
}
+/** What a knob's pill needs that a port's does not. */
+export type TagOpts = {
+ /**
+ * A second thing the pill must stand clear of on its side: a knob's dial,
+ * which is on the case's face while the pill is anchored on the knob's top
+ * โ seen at an angle the two are a knob's height apart on screen, and a
+ * pill placed by the top alone sat on the dial.
+ */
+ also?: { at: THREE.Vector3; radius: number };
+ /**
+ * A pill above or below starts at its thing's left edge and grows to the
+ * right as its text does (one no wider than the thing stays centred): left
+ * of the knobs is the panel, and a readout centred on K4 lay over it.
+ */
+ growRight?: boolean;
+ /**
+ * Where a left/right pill goes instead when there is no room for it on its
+ * side (a readout beside K1 on a phone), and how many rows out โ a row is a
+ * pill's height โ so it clears the pill that is already above or below.
+ */
+ alt?: "up" | "down";
+ altRow?: number;
+};
+
+const c = new THREE.Vector3();
+
/**
* Place a pill beside a world point.
* @param at the centre of what it names (world), where its is anchored
@@ -67,6 +93,7 @@ export function placeTag(
gap = 7,
clear?: THREE.Vector3,
nudgeY = 0,
+ opts?: TagOpts,
) {
const hw = size.width / 2;
const hh = size.height / 2;
@@ -74,26 +101,52 @@ export function placeTag(
right.setFromMatrixColumn(camera.matrixWorld, 0);
b.copy(at).addScaledVector(right, radius).project(camera);
const rpx = Math.hypot((b.x - a.x) * hw, (b.y - a.y) * hh);
- let near = rpx + gap;
- if (clear) {
- b.copy(clear).project(camera);
- const d = side === "left" || side === "right" ? Math.abs(b.x - a.x) * hw : Math.abs(b.y - a.y) * hh;
- near = Math.max(near, d + gap);
+ // How far the thing reaches from the anchor on each side, px: its own radius, and the second thing's where there is one.
+ let extL = rpx;
+ let extR = rpx;
+ let extU = rpx;
+ let extD = rpx;
+ if (opts?.also) {
+ b.copy(opts.also.at).project(camera);
+ const dx = (b.x - a.x) * hw;
+ const dy = -(b.y - a.y) * hh;
+ c.copy(opts.also.at).addScaledVector(right, opts.also.radius).project(camera);
+ const r2 = Math.hypot((c.x - b.x) * hw, (c.y - b.y) * hh);
+ extL = Math.max(extL, r2 - dx);
+ extR = Math.max(extR, r2 + dx);
+ extU = Math.max(extU, r2 - dy);
+ extD = Math.max(extD, r2 + dy);
}
const { w, h } = pillSize(el);
// Where the point is on screen: the pill is centred on it before the translate.
const cx = (a.x * 0.5 + 0.5) * size.width;
const cy = (-a.y * 0.5 + 0.5) * size.height;
// A pill beside a knob near the edge of a narrow screen ran off it (K3's on
- // a phone): it stays on its side, pushed back onto the screen โ over the
- // edge of its knob rather than over the panel on the other side.
- const place = side;
+ // a phone). A pill with somewhere else to go (opts.alt) goes there; one
+ // without stays on its side, pushed back onto the screen.
+ let place: TagSide = side;
+ let row = 0;
+ if (opts?.alt && w > 0) {
+ const fits = side === "right" ? cx + extR + gap + w + EDGE <= size.width : side === "left" ? cx - extL - gap - w - EDGE >= 0 : true;
+ if (!fits) {
+ place = opts.alt;
+ row = opts.altRow ?? 0;
+ }
+ }
+ let near = (place === "right" ? extR : place === "left" ? extL : place === "up" ? extU : extD) + gap;
+ if (clear) {
+ b.copy(clear).project(camera);
+ const d = place === "left" || place === "right" ? Math.abs(b.x - a.x) * hw : Math.abs(b.y - a.y) * hh;
+ near = Math.max(near, d + gap);
+ }
let tx = 0;
let ty = 0;
if (place === "right") tx = near + w / 2;
else if (place === "left") tx = -(near + w / 2);
- else if (place === "up") ty = -(near + h / 2);
- else ty = near + h / 2;
+ else {
+ ty = (near + h / 2 + row * (h + 4)) * (place === "up" ? -1 : 1);
+ if (opts?.growRight && w > extL + extR) tx = w / 2 - extL;
+ }
ty += nudgeY;
if (w > 0 && size.width > w + 2 * EDGE) {
tx = Math.min(Math.max(tx, EDGE + w / 2 - cx), size.width - EDGE - w / 2 - cx);
diff --git a/web/src/components/guide/store.ts b/web/src/components/guide/store.ts
index f00d737a..35e7318d 100644
--- a/web/src/components/guide/store.ts
+++ b/web/src/components/guide/store.ts
@@ -1,11 +1,19 @@
import { create } from "zustand";
import { DeviceSim } from "@/lib/guide/deviceSim";
+import { buildClock } from "./timing";
// The guide's shared state. Scroll position is written here many times a
// second, so nothing that renders React should subscribe to `progress`: the
// 3D stage reads it with getState() inside its frame loop, and the page's own
// motion reads the --p custom property the scroll tracker sets on each scene.
// Components subscribe to `scene` and `step`, which only change at edges.
+//
+// The guide is one world (world/GuideWorld, mounted by app/guide/layout.tsx):
+// the stage stays up while the reader goes between the hub and the guides, in
+// either language. A page says it is the one on screen with enterPage (a
+// page does it through world/usePage.ts), and everything the stage does
+// between two pages โ the hub's answers, the device coming apart, the build
+// winding back, the camera's move โ is read from here.
export type GuideLang = "en" | "ko";
@@ -28,6 +36,38 @@ type GuideState = {
* guides and the hub (stepOf), the desk's on the make guide (deskStepOf).
*/
page: GuideScreen;
+ /** The language of the page on screen (the stage's own words follow it: the Build stage's tags). */
+ lang: GuideLang;
+ /** A page has said which one it is: false until the first enterPage (the stage waits for it). */
+ entered: boolean;
+ /**
+ * The hub: the guide the reader is pointing at, with the mouse or the
+ * keyboard. The device answers it (world/HubAnswers, stage/Explode, the
+ * camera). Null everywhere else, and on the hub when nothing is pointed at.
+ */
+ preview: GuidePageId | null;
+ /**
+ * A way out of this page has been chosen (world/GuideLink) and the next
+ * page has not arrived yet: the words go, the stage holds what it is
+ * showing โ on the hub, the chosen guide's answer. Null otherwise.
+ */
+ leaving: GuideScreen | null;
+ /** The hub: where its choices start, px from the top of the screen (GuideHub measures it); 0 until measured. */
+ hubTop: number;
+ /**
+ * The Build stage is on the canvas. True from the moment the Build guide
+ * is entered; leaving the guide, the stage stays until it has run the build
+ * to the whole device (BuildStage), and takes itself off here. The hub
+ * also turns it on, in standby, once the reader lingers on Build
+ * (world/HubAnswers): it readies itself there and shows nothing.
+ */
+ buildLive: boolean;
+ /**
+ * Counts the cuts asked for: moments the stage must jump โ too far to
+ * play โ and does it with the canvas dipped to dark (requestCut; the world
+ * shows it, Guide.module.css [data-cut]).
+ */
+ cut: number;
/** The scene whose band contains the middle of the viewport. */
scene: string;
/** 0..1 through that scene. */
@@ -57,8 +97,21 @@ type GuideState = {
flasher: { set: string; index: number; at: number } | null;
/** The DevKit is held up in front of the reader (KitFx), so a card about it can start. */
kitPresented: boolean;
- /** A guide page has mounted: its script, from its top (the scroll tracker takes over at once). */
- enterPage: (page: GuideScreen) => void;
+ /**
+ * A page of the guide has mounted. Another page: its script, from its top
+ * (the scroll tracker takes over at once). The same page again โ the other
+ * language, most often โ keeps the step the stage is on: the new page is
+ * scrolled to it (GuideLink), and nothing on stage starts over.
+ */
+ enterPage: (page: GuideScreen, lang?: GuideLang) => void;
+ /** The hub: the guide pointed at, or null. Ignored once a way out has been chosen. */
+ setPreview: (guide: GuidePageId | null) => void;
+ /** A way out has been chosen (GuideLink). On the hub, a guide chosen is a guide pointed at. */
+ leaveFor: (page: GuideScreen | null) => void;
+ setHubTop: (px: number) => void;
+ setBuildLive: (on: boolean) => void;
+ /** The stage is about to jump: dip the canvas for it. The jump itself waits ~170 ms, until the canvas is out. */
+ requestCut: () => void;
setScroll: (scene: string, progress: number, step: number, cardIn?: boolean) => void;
replayStep: () => void;
setHandsOn: (on: boolean) => void;
@@ -69,6 +122,13 @@ type GuideState = {
export const useGuideStore = create((set, get) => ({
page: "play",
+ lang: "en",
+ entered: false,
+ preview: null,
+ leaving: null,
+ hubTop: 0,
+ buildLive: false,
+ cut: 0,
scene: "opening",
progress: 0,
step: 0,
@@ -78,10 +138,49 @@ export const useGuideStore = create((set, get) => ({
narrow: false,
flasher: null,
kitPresented: false,
- enterPage: (page) => {
- if (get().page === page && get().scene === "opening" && get().step === 0) return;
- set({ page, scene: "opening", progress: 0, step: 0, cardIn: true, handsOn: false, flasher: null });
+ enterPage: (page, lang) => {
+ const s = get();
+ const next = lang ?? s.lang;
+ if (s.entered && s.page === page) {
+ // The same page, mounted again: the stage carries on where it is.
+ if (s.lang !== next || s.leaving !== null) set({ lang: next, leaving: null });
+ return;
+ }
+ set({
+ page,
+ lang: next,
+ entered: true,
+ preview: null,
+ leaving: null,
+ // The Build stage: on with its guide; off it, kept only while it is
+ // still showing something (timing.ts buildClock: โ1 until it has drawn).
+ buildLive: page === "build" || (s.buildLive && buildClock.t >= 0),
+ scene: "opening",
+ progress: 0,
+ step: 0,
+ cardIn: true,
+ handsOn: false,
+ flasher: null,
+ });
},
+ setPreview: (preview) => {
+ const s = get();
+ if (s.leaving !== null || s.page !== "hub" || s.preview === preview) return;
+ set({ preview });
+ },
+ leaveFor: (leaving) => {
+ const s = get();
+ if (s.leaving === leaving) return;
+ // The guide chosen on the hub is the one the device answers, pointed at or not (a tap, a key).
+ set(leaving !== null && leaving !== "hub" && s.page === "hub" ? { leaving, preview: leaving } : { leaving });
+ },
+ setHubTop: (hubTop) => {
+ if (get().hubTop !== hubTop) set({ hubTop });
+ },
+ setBuildLive: (buildLive) => {
+ if (get().buildLive !== buildLive) set({ buildLive });
+ },
+ requestCut: () => set({ cut: get().cut + 1 }),
setScroll: (scene, progress, step, cardIn = true) => {
const s = get();
if (s.scene !== scene || s.step !== step) {
@@ -93,7 +192,9 @@ export const useGuideStore = create((set, get) => ({
},
replayStep: () => set({ replay: get().replay + 1 }),
setHandsOn: (handsOn) => set({ handsOn }),
- setNarrow: (narrow) => set({ narrow }),
+ setNarrow: (narrow) => {
+ if (get().narrow !== narrow) set({ narrow });
+ },
setFlasher: (f) => {
const cur = get().flasher;
if (!f) {
@@ -107,9 +208,9 @@ export const useGuideStore = create((set, get) => ({
},
}));
-// One simulated board per page. Module scope rather than state because it is
-// an imperative object ticked from the render loop, and the DOM control pad
-// and the 3D knobs must reach the same one.
+// One simulated board for the whole guide. Module scope rather than state
+// because it is an imperative object ticked from the render loop, and the DOM
+// control pad and the 3D knobs must reach the same one.
let sim: DeviceSim | null = null;
export function getSim(): DeviceSim {
if (!sim) sim = new DeviceSim();
diff --git a/web/src/components/guide/ui/Later.tsx b/web/src/components/guide/ui/Later.tsx
new file mode 100644
index 00000000..7ae5fb9f
--- /dev/null
+++ b/web/src/components/guide/ui/Later.tsx
@@ -0,0 +1,155 @@
+"use client";
+
+import { startTransition, useEffect, useRef, useState, type ReactNode } from "react";
+
+// A guide entered from another page of the guide: its words first, the rest
+// of the page a moment after.
+//
+// Going from the hub into a guide, the whole story is mounted in one go โ
+// every chapter, every card โ and laid out in one go, in the middle of the
+// camera's move: one long frame (a twelfth of a second on a fast machine, a
+// second on a slow one) on a stage that is meant never to stop. More than
+// half of it was the browser laying out cards that are five and ten screens
+// further down; the rest was React making what those cards hold besides their
+// words โ the flasher's screens, the consoles, the parts lists, the deck.
+//
+// So on such an arrival โ and only then โ the page comes in in two parts:
+//
+// - What a card holds besides its words is mounted after the page ().
+// - Every block below the first screen is marked [data-wait]: the browser
+// skips the layout of what is inside it until it is near the screen or
+// its turn comes (Guide.module.css: content-visibility; a block keeps its
+// height meanwhile โ its min-height is its usual one).
+//
+// Both are then done in the quiet after the move, one at a time and in the
+// page's order, each a small piece of work between two frames
+// (`whenQuiet`), until the page is exactly the page it always was: nothing
+// stays skipped, nothing is measured from an estimate. A block that comes
+// near the screen first is done there and then; and everything still waiting
+// is done at once the moment the reader presses a key or the mouse โ a
+// chapter's link, โ to the next stop: where those lead depends on every card
+// above having its real height.
+//
+// A page that is loaded (its markup comes whole from the server), reached
+// with Back or Forward (the browser puts the scroll back where it was), or
+// swapped for its other language (the reader lands mid-page) is mounted whole,
+// as it always was.
+
+/** The first job waits this long after it was asked for: the words' arrival and the busiest part of the stage's move, ms. */
+const START_MS = 650;
+/** Near enough to the screen to be needed now: a screen's height either way. */
+const NEAR = "100% 0px";
+
+const jobs: (() => void)[] = [];
+let pumping = 0;
+let listening = false;
+
+function idle(fn: () => void) {
+ if (typeof window.requestIdleCallback === "function") window.requestIdleCallback(fn, { timeout: 250 });
+ else window.setTimeout(fn, 60);
+}
+
+function pump() {
+ pumping = 0;
+ const job = jobs.shift();
+ if (!job) return;
+ job();
+ if (jobs.length) pumping = window.setTimeout(() => idle(pump), 24);
+}
+
+/** Everything that is waiting, now: the reader is about to go somewhere. */
+function flush() {
+ if (!jobs.length) return;
+ window.clearTimeout(pumping);
+ pumping = 0;
+ for (const job of jobs.splice(0)) job();
+}
+
+/**
+ * Do this in the quiet after the page has arrived, in its turn (or at once,
+ * with everything else waiting, when the reader acts). Returns its undoing:
+ * the job is forgotten.
+ */
+export function whenQuiet(job: () => void): () => void {
+ jobs.push(job);
+ if (!listening) {
+ listening = true;
+ window.addEventListener("pointerdown", flush, true);
+ window.addEventListener("keydown", flush, true);
+ }
+ if (!pumping) pumping = window.setTimeout(() => idle(pump), START_MS);
+ return () => {
+ const i = jobs.indexOf(job);
+ if (i >= 0) jobs.splice(i, 1);
+ };
+}
+
+// A page reached with Back or Forward is never mounted late (see above): the
+// browser puts the scroll back as the page mounts, and it must be the whole
+// page it does that on. What is remembered is the kind of the last move, not
+// when it was โ the page can mount seconds after the button was pressed (its
+// data being fetched), and a window of time let it through as a new arrival:
+// it came back a hundred pixels off, on a card that was not the one on.
+// A move through the history says so (popstate); a link followed is a new
+// visit again; and the page that arrives takes the mark with it.
+let byHistory = false;
+if (typeof window !== "undefined") {
+ window.addEventListener("popstate", () => {
+ byHistory = true;
+ });
+ document.addEventListener(
+ "click",
+ (e) => {
+ const el = e.target as Element | null;
+ if (el && typeof el.closest === "function" && el.closest("a[href]")) byHistory = false;
+ },
+ true,
+ );
+}
+/** The page being mounted now was reached through the history. */
+export function arrivedByHistory() {
+ return byHistory;
+}
+/** A page has arrived: the next one is judged afresh. (From an effect, not as it renders.) */
+export function arrived() {
+ byHistory = false;
+}
+
+/** `late`: this page's extras come in after it (GuideExperience decides, once, as it mounts). */
+export default function Later({ late, children }: { late: boolean; children: ReactNode }) {
+ const [on, setOn] = useState(!late);
+ const mark = useRef(null);
+
+ useEffect(() => {
+ if (on) return;
+ let done = false;
+ // In its turn: a small render the stage's frames go on through.
+ const forget = whenQuiet(() => {
+ if (done) return;
+ done = true;
+ startTransition(() => setOn(true));
+ });
+ // Or as its card comes near the screen, whichever is first.
+ const el = mark.current;
+ const io =
+ el && typeof IntersectionObserver !== "undefined"
+ ? new IntersectionObserver(
+ (entries) => {
+ if (done || !entries.some((e) => e.isIntersecting)) return;
+ done = true;
+ setOn(true);
+ },
+ { rootMargin: NEAR },
+ )
+ : null;
+ if (el) io?.observe(el);
+ return () => {
+ io?.disconnect();
+ forget();
+ };
+ }, [on]);
+
+ // (Its place in the card is kept: the card's lines are counted, Guide.module.css.)
+ if (!on) return (null);
+ const canvas = useRef(null);
+ /** This is the page that took the visit's one cover (an effect run twice in development is still the same page). */
+ const mine = useRef(false);
+
+ useLayoutEffect(() => {
+ if (handled && !mine.current) return;
+ handled = true;
+ mine.current = true;
+ const el = cover.current;
+ const cv = canvas.current;
+ let seen = false;
+ try {
+ seen = window.localStorage.getItem(SEEN_KEY) === SEEN;
+ } catch {
+ /* no storage: it is a first visit every time */
+ }
+ if (!el || !cv || seen || el.getAttribute("data-off") === "skip" || stageLoad.get().ready || stageLoad.get().failed) {
+ setShow(false);
+ return;
+ }
+ // The canvas stays out under the counter until the count is done (Guide.module.css).
+ const world = el.closest("[data-guide-world]");
+ world?.setAttribute("data-cover", "1");
+ const ctx = cv.getContext("2d");
+ const still = reducedMotion();
+ const pitch = el.clientWidth < 520 ? 6 : 7;
+ const dpr = Math.min(2, window.devicePixelRatio || 1);
+ cv.width = COLS * pitch * dpr;
+ cv.height = ROWS * pitch * dpr;
+ el.style.setProperty("--pitch", `${pitch}px`);
+ const grid = new Float32Array(COLS * ROWS);
+
+ // Counted from when the page was asked for (performance.now() is from the
+ // navigation's start); a page reached inside the guide starts from here.
+ const t0 = performance.now() < 5000 ? 0 : performance.now();
+ let raf = 0;
+ let timer = 0;
+ let last = performance.now();
+ let value = 0;
+ let shown = 0;
+ let fullAt = 0;
+ let lifted = false;
+
+ const draw = (count: number, dark: number, roll = false) => {
+ if (!ctx) return;
+ countMatrix(count, grid, roll && !still);
+ const [r, g, b] = accentNow();
+ ctx.clearRect(0, 0, cv.width, cv.height);
+ const cell = pitch * dpr;
+ const led = (pitch - 2) * dpr;
+ const core = Math.max(1, led * 0.44);
+ for (let y = dark; y < ROWS; y++) {
+ for (let x = 0; x < COLS; x++) {
+ const level = grid[y * COLS + x];
+ if (!level) continue;
+ const px = x * cell + dpr;
+ const py = y * cell + dpr;
+ ctx.fillStyle = `rgba(${r},${g},${b},${level})`;
+ ctx.fillRect(px, py, led, led);
+ // An emitter is brightest in its middle.
+ ctx.fillStyle = `rgba(255,244,232,${0.55 * level})`;
+ ctx.fillRect(px + (led - core) / 2, py + (led - core) / 2, core, core);
+ }
+ }
+ };
+
+ const lift = () => {
+ if (lifted) return;
+ lifted = true;
+ setOff(true);
+ world?.removeAttribute("data-cover");
+ try {
+ if (stageLoad.get().ready) window.localStorage.setItem(SEEN_KEY, SEEN);
+ } catch {
+ /* no storage */
+ }
+ timer = window.setTimeout(() => setShow(false), LIFT_MS);
+ };
+
+ const loop = (t: number) => {
+ raf = requestAnimationFrame(loop);
+ const dt = Math.min(100, t - last);
+ last = t;
+ const s = stageLoad.get();
+ // No stage is coming: there is nothing to count.
+ if (s.failed) {
+ cancelAnimationFrame(raf);
+ raf = 0;
+ ctx?.clearRect(0, 0, cv.width, cv.height);
+ lift();
+ return;
+ }
+ const late = t - t0 > GIVE_UP_MS;
+ // What has really arrived: the stage's chunk (until it has, a slow creep
+ // that never gets there), then the models, then the device on screen.
+ const target = s.ready || late ? 1 : s.staged ? 0.3 + 0.66 * s.frac : 0.3 * (1 - Math.exp(-(t - t0) / 1600));
+ value += (target - value) * (1 - Math.exp(-dt / 240));
+ // Ready: the count runs out the rest at a pace, however far it had to go.
+ if (target === 1) value = Math.min(1, value + dt / 900);
+ if (value > 0.9995) value = 1;
+ const whole = Math.floor(value * 100 + 1e-6);
+ // While things are still arriving the figures change at once, as an LED
+ // counter's do: the page is at its busiest then (scripts being read,
+ // models unpacked), frames go missing, and a figure caught half-way
+ // through a roll and held there for half a second reads as a fault.
+ // Once the stage is ready the frames are smooth โ that is what ready
+ // means โ and the count runs out the rest rolling, a row of LEDs at a
+ // time, like a counter coming up to its number.
+ //
+ // And it never stalls: what arrives comes in lumps (a 1.6 MB model is
+ // nothing, then everything), and a number that sits on 019 for a second
+ // and then leaps to 052 looks frozen, then broken. So the figure shown
+ // runs after the real one at a pace with a floor and a ceiling โ a
+ // slow creep while nothing is reported, a run when a lot is โ and only
+ // the last ten wait for the stage itself.
+ const rolling = s.ready && !late;
+ const behind = whole - shown;
+ const pace = late
+ ? RUN * 3
+ : rolling
+ ? Math.min(RUN, Math.max(behind * 7, 22))
+ : behind > 0
+ ? Math.min(RUN, Math.max(behind * 5, CREEP))
+ : shown < CREEP_TO
+ ? CREEP
+ : 0;
+ // (Never back: the creep may have got ahead of what was reported.)
+ shown = Math.max(shown, Math.min(rolling || late ? whole : Math.max(whole, CREEP_TO), shown + (pace * dt) / 1000));
+ // (Not rolling, the figures are whole: an LED is on or off.)
+ if (shown < 100) {
+ draw(rolling ? shown : Math.floor(shown + 1e-6), 0, rolling);
+ return;
+ }
+ if (!fullAt) fullAt = t;
+ const since = t - fullAt - HOLD_MS;
+ if (since < 0) {
+ draw(100, 0);
+ return;
+ }
+ // Out, a row at a time from the top, as the cover lifts.
+ lift();
+ const dark = still ? ROWS : Math.min(ROWS, Math.floor((since / WIPE_MS) * ROWS));
+ draw(100, dark);
+ if (dark >= ROWS) {
+ cancelAnimationFrame(raf);
+ raf = 0;
+ }
+ };
+ raf = requestAnimationFrame(loop);
+ return () => {
+ if (raf) cancelAnimationFrame(raf);
+ window.clearTimeout(timer);
+ world?.removeAttribute("data-cover");
+ };
+ }, []);
+
+ if (!show) return null;
+ return (
+ 0 ? ({ "--hub-top": `${hubTop}px` } as React.CSSProperties) : undefined}
+ suppressHydrationWarning
+ >
+
+
+ {hydrating && }
+
("[data-guide-world]");
+ world?.setAttribute("data-stage", "loading");
+ stageLoad.set({ staged: true });
+
+ const t0 = performance.now();
+ let raf = 0;
+ let last = t0;
+ let most = 0;
+ let mountedAt = 0;
+ let smooth = 0;
+ const done = () => {
+ raf = 0;
+ stageLoad.set({ frac: 1, ready: true });
+ world?.removeAttribute("data-stage");
+ };
+ const loop = (t: number) => {
+ const dt = t - last;
+ last = t;
+ const p = useProgress.getState();
+ // The total grows as models name their parts: the share never goes back.
+ most = Math.max(most, p.total);
+ if (most > 0) stageLoad.set({ frac: Math.max(stageLoad.get().frac, Math.min(1, p.loaded / most)) });
+ if (!mountedAt && world?.querySelector(".guide-knob-tag")) mountedAt = t;
+ if (mountedAt) {
+ smooth = dt < SMOOTH_MS ? smooth + 1 : 0;
+ if (smooth >= SMOOTH_FRAMES || t - mountedAt > SETTLE_MAX_MS) return done();
+ }
+ if (t - t0 > GIVE_UP_MS) return done();
+ raf = requestAnimationFrame(loop);
+ };
+ raf = requestAnimationFrame(loop);
+ return () => {
+ // The stage is taken down with the guide: the next visit's starts over.
+ if (raf) cancelAnimationFrame(raf);
+ world?.removeAttribute("data-stage");
+ stageLoad.set({ staged: false, frac: 0, ready: false });
+ };
+ }, []);
+
+ useEffect(() => {
+ const copy = () => {
+ panelSignal.rgb[0] = toByte(panelGlow.hue.r);
+ panelSignal.rgb[1] = toByte(panelGlow.hue.g);
+ panelSignal.rgb[2] = toByte(panelGlow.hue.b);
+ panelSignal.colour = panelGlow.colour;
+ panelSignal.lit = panelGlow.lit;
+ panelSignal.live = true;
+ };
+ copy();
+ const timer = window.setInterval(copy, SIGNAL_MS);
+ return () => {
+ window.clearInterval(timer);
+ panelSignal.live = false;
+ };
+ }, []);
+
+ return null;
+}
diff --git a/web/src/components/guide/ui/Words.tsx b/web/src/components/guide/ui/Words.tsx
new file mode 100644
index 00000000..56461c32
--- /dev/null
+++ b/web/src/components/guide/ui/Words.tsx
@@ -0,0 +1,30 @@
+import type { CSSProperties } from "react";
+import styles from "../Guide.module.css";
+
+// A title, word by word: each word stands in a mask of its own and rises into
+// it, one after another along the line (Guide.module.css "words behind
+// masks"). The words are still the title's text โ a real space between each,
+// nothing hidden from a screen reader, a copy or a search โ and they wrap
+// where the plain title would: the masks are clips, not boxes.
+//
+// Who starts it is the block's business: `.wordsNow` on the title for one on
+// a page's first screen (it plays on arrival), or a [data-reveal] block that
+// is marked the first time the reader reaches it (ui/useReveal).
+
+/** `from`: the first word's place in the line of things arriving (its delay is from ร 55 ms). */
+export default function Words({ text, from = 0 }: { text: string; from?: number }) {
+ const words = text.split(/\s+/).filter(Boolean);
+ return (
+ <>
+ {words.map((word, i) => (
+ // The space is outside the mask, so the line breaks between words as it always did.
+
+
+ {word}
+
+ {i < words.length - 1 ? " " : null}
+
+ ))}
+
+ );
+}
diff --git a/web/src/components/guide/ui/panelSignal.ts b/web/src/components/guide/ui/panelSignal.ts
new file mode 100644
index 00000000..2ea5adb4
--- /dev/null
+++ b/web/src/components/guide/ui/panelSignal.ts
@@ -0,0 +1,25 @@
+// What the panel is showing, for the page โ the stage's own signal
+// (stage/look/panelGlow.ts) handed across without three.js coming with it.
+//
+// panelGlow lives in the stage's chunk and is made of three's colours; the
+// page's bundle must not pull three in (the words never wait for it). So the
+// stage copies what the page needs into this plain object a few times a
+// second (ui/StageLoadReport, mounted with the canvas), and the page's tint
+// (ui/panelTint.ts) reads it here. It is what the panel *shows*: dark while
+// the device is apart on the hub or the power is held on the Build guide,
+// fading when the power is cut โ which the simulator's frame alone does not
+// say. Until the stage is up (`live` false) the tint reads the simulator's
+// frame itself.
+
+export type PanelSignal = {
+ /** The stage is up and writing this. */
+ live: boolean;
+ /** What colour the panel's light is, sRGB 0..255 (meaningless while `colour` is 0). */
+ rgb: [number, number, number];
+ /** 0..1: how much colour the panel carries (0: dark, or white and grey only). */
+ colour: number;
+ /** 0..1: how lit the panel is at all. */
+ lit: number;
+};
+
+export const panelSignal: PanelSignal = { live: false, rgb: [0, 0, 0], colour: 0, lit: 0 };
diff --git a/web/src/components/guide/ui/panelTint.ts b/web/src/components/guide/ui/panelTint.ts
new file mode 100644
index 00000000..6bf1bf2d
--- /dev/null
+++ b/web/src/components/guide/ui/panelTint.ts
@@ -0,0 +1,421 @@
+"use client";
+
+import { useEffect, type RefObject } from "react";
+import styles from "../Guide.module.css";
+import { addHue, clearHues, dominantHue, hueHistogram, oneColour } from "../stage/look/dominant";
+import { getSim, useGuideStore } from "../store";
+import { panelSignal } from "./panelSignal";
+
+// The page answers the instrument.
+//
+// The LED panel is the only light in the guide's room, and the page is in
+// that room: its accent โ the kicker's dot, the numerals, the lit edge of the
+// card being read, the chapter rail's marker, a link's underline โ takes the
+// colour of the pattern playing on the panel. Turn K1 on Origin and the page
+// turns with it.
+//
+// One thing is written (Guide.module.css .world has its default):
+//
+// --g-led-rgb: "255 106 61" the accent, as three numbers
+// --g-lit: 0..1 how lit the panel is at all
+//
+// and the sheet makes the rest from them (--g-led, --g-led-wash, every glow;
+// the light on a card's edge is as strong as the panel is lit: with the
+// power off, on the Build guide, the edge is only a marker).
+// The colour is eased here and written only when it has moved far enough to
+// see, and only on what is on screen (see "the loop", below), so a pattern
+// that holds its colour costs the page nothing and one that does not costs
+// it little.
+//
+// What it may become is fenced in (accentFor): the hue is the panel's, the
+// lightness stays in a band where it reads on the room's dark as text and
+// takes the dark ink of a button on top of it, and the chroma is held under
+// what the hue can carry without shouting. A white or grey pattern has no hue
+// to give: the accent pales toward the LED orange it started from. A dark
+// panel โ off, asleep, the Build guide before the power goes in โ gives the
+// orange back, and so does Make, where the device has left the room.
+//
+// The knob tags on the stage do not follow: they answer to the orange dots on
+// the knobs' rings, which are the device's own and stay orange
+// (Guide.module.css --g-led-fixed).
+
+export type Rgb = [number, number, number];
+
+/** The LED orange the guide starts from, and comes back to when the panel is dark. */
+export const LED_ORANGE: Rgb = [255, 106, 61];
+
+// โโ OKLab โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+
+function toLinear(c: number) {
+ const v = c / 255;
+ return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+function fromLinear(v: number) {
+ const c = v <= 0.0031308 ? v * 12.92 : 1.055 * Math.pow(v, 1 / 2.4) - 0.055;
+ return Math.round(Math.max(0, Math.min(1, c)) * 255);
+}
+function linearToOklab(r: number, g: number, b: number): Rgb {
+ const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+ const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+ const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+ return [
+ 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+ 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+ 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+ ];
+}
+function oklabToLinear(L: number, a: number, b: number): Rgb {
+ const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+ const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+ const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+ return [
+ 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+ -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+ -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+ ];
+}
+function inGamut([r, g, b]: Rgb) {
+ const e = 0.0005;
+ return r >= -e && r <= 1 + e && g >= -e && g <= 1 + e && b >= -e && b <= 1 + e;
+}
+/** The most chroma sRGB holds at this lightness and hue. */
+function maxChroma(L: number, h: number) {
+ let lo = 0;
+ let hi = 0.4;
+ for (let i = 0; i < 14; i++) {
+ const mid = (lo + hi) / 2;
+ if (inGamut(oklabToLinear(L, mid * Math.cos(h), mid * Math.sin(h)))) lo = mid;
+ else hi = mid;
+ }
+ return lo;
+}
+
+const ORANGE_LAB = linearToOklab(toLinear(LED_ORANGE[0]), toLinear(LED_ORANGE[1]), toLinear(LED_ORANGE[2]));
+const ORANGE_HUE = Math.atan2(ORANGE_LAB[2], ORANGE_LAB[1]);
+const ORANGE_CHROMA = Math.hypot(ORANGE_LAB[1], ORANGE_LAB[2]);
+
+/** Relative luminance (WCAG) of an sRGB colour. */
+export function luminance([r, g, b]: Rgb) {
+ return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+/** WCAG contrast between two sRGB colours. */
+export function contrast(a: Rgb, b: Rgb) {
+ const la = luminance(a);
+ const lb = luminance(b);
+ return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+// โโ the panel's colour โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+
+/** What the panel is giving off: its colour as linear-light sums, and how much of it is lit. */
+export type PanelLight = {
+ /** The dominant colour, sRGB 0..255 โ what colour the light is. */
+ rgb: Rgb;
+ /** 0..1: how much the panel has a colour to follow (0: black, white and grey only, or every hue at once). */
+ colour: number;
+ /** 0..1: how lit the panel is at all. */
+ lit: number;
+};
+
+/**
+ * The dominant colour of a panel frame (128ร64 RGBA, deviceSim.frame). Pixels
+ * are weighed by how coloured they are, so on a pattern of white with a red
+ * heart the answer is the red: white is what every pattern has, the colour is
+ * what this one is. And it is the fullest hue, not the mean of them all
+ * (stage/look/dominant.ts): blue squares under an orange slider are blue,
+ * not the pink between.
+ *
+ * Once the stage is up the page reads the stage's own signal instead
+ * (ui/panelSignal.ts, from stage/look/panelGlow.ts โ the same weighing, of
+ * what the panel is *showing*: dark while the device is apart or its power is
+ * held, fading when it is cut). This is for the moments before that, and for
+ * the tests.
+ */
+export function readPanel(frame: Uint8ClampedArray, out: PanelLight = { rgb: [0, 0, 0], colour: 0, lit: 0 }, hues = hueHistogram()): PanelLight {
+ clearHues(hues);
+ let weight = 0;
+ let light = 0;
+ let n = 0;
+ // Every 13th pixel: about 630 of the 8192, and no two rows start alike.
+ for (let i = 0; i < frame.length; i += 52) {
+ const pr = frame[i];
+ const pg = frame[i + 1];
+ const pb = frame[i + 2];
+ const max = pr > pg ? (pr > pb ? pr : pb) : pg > pb ? pg : pb;
+ const min = pr < pg ? (pr < pb ? pr : pb) : pg < pb ? pg : pb;
+ // Coloured and bright counts; a dim wash of colour counts little.
+ const w = ((max - min) / 255) * (max / 255);
+ addHue(hues, pr, pg, pb, w);
+ weight += w;
+ light += max;
+ n++;
+ }
+ const share = weight > 0.0001 ? dominantHue(hues, LEAD) : 0;
+ if (share > 0) {
+ out.rgb[0] = LEAD.r * 255;
+ out.rgb[1] = LEAD.g * 255;
+ out.rgb[2] = LEAD.b * 255;
+ } else {
+ out.rgb[0] = out.rgb[1] = out.rgb[2] = 0;
+ }
+ // A twentieth of the panel in full colour is already "a coloured pattern" โ if it is one colour.
+ out.colour = Math.min(1, weight / n / 0.05) * oneColour(share);
+ out.lit = Math.min(1, light / n / 255 / 0.04);
+ return out;
+}
+
+const LEAD = { r: 0, g: 0, b: 0 };
+
+/** Hue distance, 0..ฯ. */
+function hueGap(a: number, b: number) {
+ return Math.abs(Math.atan2(Math.sin(a - b), Math.cos(a - b)));
+}
+
+/**
+ * The page's accent for a panel light, as OKLab. Always readable: lightness
+ * 0.72โ0.78 (โฅ 4.5:1 on the room's dark, and under the buttons' dark ink),
+ * chroma no more than the hue carries quietly. No colour to follow: the LED
+ * orange, paler the whiter the panel is.
+ */
+export function accentLab(panel: PanelLight): Rgb {
+ const follow = panel.lit * panel.colour;
+ // A lit panel with no colour in it (white, grey): a pale orange.
+ const pale = panel.lit * (1 - panel.colour);
+ let hue = ORANGE_HUE;
+ if (follow > 0.001) {
+ const lab = linearToOklab(toLinear(panel.rgb[0]), toLinear(panel.rgb[1]), toLinear(panel.rgb[2]));
+ const h = Math.atan2(lab[2], lab[1]);
+ // The short way round from the orange to the panel's hue.
+ hue = ORANGE_HUE + Math.atan2(Math.sin(h - ORANGE_HUE), Math.cos(h - ORANGE_HUE)) * Math.min(1, follow * 1.6);
+ }
+ // Warm hues keep the orange's own strength; the cool ones are held lower
+ // (a full green or blue beside cream type shouts) and set a little lighter
+ // (blue is dark for its lightness).
+ //
+ // Yellow and lime are the other way about: they are only themselves when
+ // they are light. Held in the same band as the rest a yellow panel gave a
+ // khaki page and a green one an olive โ the two hues that are brightest on
+ // the panel came out the muddiest on the page. So between about 85ยฐ and
+ // 150ยฐ the band rises with the hue (up to 0.88) and takes more of the
+ // chroma the hue has there. Lighter only helps the reading: more contrast
+ // on the dark, and more under the dark ink.
+ const warm = 1 - Math.min(1, hueGap(hue, ORANGE_HUE) / 1.1);
+ const bright = brightHue(hue);
+ const base = COOL_L + (ORANGE_LAB[0] - COOL_L) * warm;
+ const L = base + (BRIGHT_L - base) * bright;
+ const cool = Math.min(maxChroma(L, hue) * 0.92, COOL_CHROMA + (BRIGHT_CHROMA - COOL_CHROMA) * bright);
+ const cap = cool + (ORANGE_CHROMA - cool) * warm * (1 - bright);
+ const chroma = cap * (1 - 0.55 * pale);
+ return [L + (PALE_L - L) * pale * 0.6, chroma * Math.cos(hue), chroma * Math.sin(hue)];
+}
+/** A cool accent's lightness (the orange's own is 0.71) and the most chroma it is given. */
+const COOL_L = 0.775;
+const COOL_CHROMA = 0.118;
+/** Yellow's and lime's: lighter, and with more of their own colour. */
+const BRIGHT_L = 0.88;
+const BRIGHT_CHROMA = 0.168;
+/** 0..1: how much a hue (OKLab angle, radians) is one of the light ones โ all of it from 97ยฐ to 135ยฐ, none below 72ยฐ or above 162ยฐ. */
+function brightHue(h: number) {
+ const deg = ((h * 180) / Math.PI + 360) % 360;
+ const up = Math.min(1, Math.max(0, (deg - 72) / 25));
+ const down = Math.min(1, Math.max(0, (162 - deg) / 27));
+ const t = Math.min(up, down);
+ return t * t * (3 - 2 * t);
+}
+/** A white panel's accent is lighter as well as paler. */
+const PALE_L = 0.8;
+
+/** OKLab โ sRGB 0..255, chroma pulled in until it fits. */
+export function labToRgb([L, a, b]: Rgb): Rgb {
+ let lin = oklabToLinear(L, a, b);
+ if (!inGamut(lin)) {
+ let lo = 0;
+ let hi = 1;
+ for (let i = 0; i < 12; i++) {
+ const mid = (lo + hi) / 2;
+ if (inGamut(oklabToLinear(L, a * mid, b * mid))) lo = mid;
+ else hi = mid;
+ }
+ lin = oklabToLinear(L, a * lo, b * lo);
+ }
+ return [fromLinear(lin[0]), fromLinear(lin[1]), fromLinear(lin[2])];
+}
+
+/** The page's accent for a panel frame, sRGB โ the whole of the mapping, for the tests. */
+export function accentFor(frame: Uint8ClampedArray): Rgb {
+ return labToRgb(accentLab(readPanel(frame)));
+}
+
+// โโ the loop โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+//
+// Where it is written matters more than how often. A custom property set on
+// the world would make the browser work out the style of every element of
+// the page again, each time (7โ9 ms on a guide's page: a dropped frame, a
+// few times a second, for as long as a pattern keeps changing colour). So
+// the colour is written only where it can be seen: the stage's glow, the top
+// bar, and the page's blocks that are on screen or about to be โ the card
+// being read, a chapter's title โ a hundred elements or so. A block that
+// comes onto the screen is given the colour as it does.
+
+/** How fast the page's colour follows the panel's: the time to cover 63% of the way, seconds. */
+const FOLLOW_S = 0.45;
+/**
+ * And no faster than this, in OKLab per second, however far it has to go:
+ * about 70ยฐ of hue a second at the accent's chroma. A knob turned a detent is
+ * well inside it; a pattern swapped for one of another colour is a turn of
+ * the page's colour over a second, not a jump.
+ */
+const MAX_SPEED = 0.2;
+/** The panel is read this often, ms. */
+const READ_MS = 110;
+/** The page is written no more often than this, ms. */
+const WRITE_MS = 48;
+/** A step smaller than this in every channel is not written (0..255). */
+const WRITE_STEP = 2;
+/** A block this far off the screen (a share of its height) is already kept in colour. */
+const NEAR = "30% 0px";
+
+let users = 0;
+let raf = 0;
+let lastRead = 0;
+let lastWrite = 0;
+let lastTick = 0;
+const panel: PanelLight = { rgb: [0, 0, 0], colour: 0, lit: 0 };
+const panelHues = hueHistogram();
+const NONE: PanelLight = { rgb: [0, 0, 0], colour: 0, lit: 0 };
+let want: Rgb = accentLab(NONE);
+let now: Rgb = [...want];
+let written: Rgb = [...LED_ORANGE];
+/** How lit the panel is, wanted / eased / as written (0..1). */
+let wantLit = 0;
+let nowLit = 0;
+let writtenLit = -1;
+/** What is in colour now: the stage, the top bar, the blocks on screen. */
+const lit = new Set();
+
+function reducedMotion() {
+ return window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+}
+
+function paint(el: HTMLElement) {
+ if (written[0] === LED_ORANGE[0] && written[1] === LED_ORANGE[1] && written[2] === LED_ORANGE[2]) el.style.removeProperty("--g-led-rgb");
+ else el.style.setProperty("--g-led-rgb", `${written[0]} ${written[1]} ${written[2]}`);
+ if (writtenLit <= 0) el.style.removeProperty("--g-lit");
+ else el.style.setProperty("--g-lit", writtenLit.toFixed(2));
+}
+
+function tick(t: number) {
+ raf = requestAnimationFrame(tick);
+ // Never negative: a frame's time is taken when the frame begins, and the
+ // loop can be started (lastTick = now) by a page mounted a moment after
+ // that. A negative step made the limit below divide by a distance of zero,
+ // and the accent was "NaN NaN NaN" from then on โ on Make, most visits:
+ // every lit thing on the page fell back to the ink's cream.
+ const dt = Math.max(0, Math.min(0.25, (t - lastTick) / 1000));
+ lastTick = t;
+ if (t - lastRead >= READ_MS) {
+ lastRead = t;
+ const s = useGuideStore.getState();
+ // The device has left the room on Make, and has not arrived before a page says so.
+ const here = s.entered && s.page !== "make" && s.leaving !== "make";
+ const light = !here ? NONE : panelSignal.live ? panelSignal : readPanel(getSim().frame, panel, panelHues);
+ // While the pattern list is open (K4 held: the board's "select" screen)
+ // the panel shows a pattern a moment and then the next, each its own
+ // colour. The page does not chase them: it keeps the colour it had, and
+ // takes the chosen pattern's when the list closes.
+ const browsing = here && getSim().snapshot().mode === "select";
+ if (!browsing) want = accentLab(light);
+ // On Make the light is the desk's windows, and they are always on.
+ wantLit = here ? light.lit : s.entered ? 1 : 0;
+ }
+ const still = reducedMotion();
+ const k = still ? 1 : 1 - Math.exp(-dt / FOLLOW_S);
+ const d0 = (want[0] - now[0]) * k;
+ const d1 = (want[1] - now[1]) * k;
+ const d2 = (want[2] - now[2]) * k;
+ const far = Math.hypot(d0, d1, d2);
+ const cap = still || far <= MAX_SPEED * dt || far === 0 ? 1 : (MAX_SPEED * dt) / far;
+ now[0] += d0 * cap;
+ now[1] += d1 * cap;
+ now[2] += d2 * cap;
+ nowLit += (wantLit - nowLit) * k;
+ if (t - lastWrite < WRITE_MS) return;
+ const rgb = labToRgb(now);
+ // In steps of a twentieth, and all the way to each end.
+ const level = Math.abs(wantLit - nowLit) < 0.03 ? wantLit : Math.round(nowLit * 20) / 20;
+ if (level === writtenLit && Math.abs(rgb[0] - written[0]) < WRITE_STEP && Math.abs(rgb[1] - written[1]) < WRITE_STEP && Math.abs(rgb[2] - written[2]) < WRITE_STEP) return;
+ lastWrite = t;
+ written = rgb;
+ writtenLit = level;
+ lit.forEach(paint);
+}
+
+/** The accent as it is on the page now, sRGB (the preloader's lit pixels are this colour). */
+export function accentNow(): Rgb {
+ return written;
+}
+
+/**
+ * The page follows the panel while a page of the guide is mounted: `root` is
+ * the page (GuideHub's, GuideExperience's). One loop and one colour for the
+ * whole guide: it carries on across a move between two pages (the next page
+ * takes it over before the last lets go), so the colour never starts over.
+ */
+export function usePanelTint(root: RefObject) {
+ useEffect(() => {
+ const page = root.current;
+ if (!page) return;
+ if (users++ === 0) {
+ lastTick = performance.now();
+ raf = requestAnimationFrame(tick);
+ }
+ const mine: HTMLElement[] = [];
+ const add = (el: HTMLElement | null | undefined) => {
+ if (!el) return;
+ mine.push(el);
+ lit.add(el);
+ paint(el);
+ };
+ // Always in colour: the room's glow behind the device, and the top bar.
+ const stage = page.closest("[data-guide-world]")?.querySelector(`.${styles.stage}`);
+ add(stage);
+ add(page.querySelector("header"));
+ // The page's blocks, as they come near the screen.
+ const blocks = Array.from(page.querySelectorAll('main [data-leaves=""]'));
+ let io: IntersectionObserver | null = null;
+ if (typeof IntersectionObserver === "undefined") blocks.forEach(add);
+ else {
+ io = new IntersectionObserver(
+ (entries) => {
+ for (const e of entries) {
+ const el = e.target as HTMLElement;
+ if (e.isIntersecting) {
+ lit.add(el);
+ paint(el);
+ } else lit.delete(el);
+ }
+ },
+ { rootMargin: NEAR },
+ );
+ blocks.forEach((b) => io?.observe(b));
+ }
+ return () => {
+ io?.disconnect();
+ blocks.forEach((b) => lit.delete(b));
+ mine.forEach((el) => el !== stage && lit.delete(el));
+ // Let the next page take the loop first (a move between pages unmounts, then mounts).
+ window.setTimeout(() => {
+ if (--users > 0) return;
+ cancelAnimationFrame(raf);
+ raf = 0;
+ // Out of the guide: the next visit starts from the orange.
+ now = [...accentLab(NONE)];
+ written = [...LED_ORANGE];
+ wantLit = nowLit = 0;
+ writtenLit = -1;
+ lit.forEach(paint);
+ lit.clear();
+ }, 400);
+ };
+ }, [root]);
+}
diff --git a/web/src/components/guide/ui/resident/HubResident.tsx b/web/src/components/guide/ui/resident/HubResident.tsx
new file mode 100644
index 00000000..edc3b3c1
--- /dev/null
+++ b/web/src/components/guide/ui/resident/HubResident.tsx
@@ -0,0 +1,202 @@
+"use client";
+
+import { useEffect, useRef, type RefObject } from "react";
+import { GUIDE_ORDER } from "../../pages";
+import { useGuideStore, type GuidePageId } from "../../store";
+import { busy } from "../useStepKeys";
+import type { ResidentSetup } from "./engine";
+import { ROWS } from "./sprite";
+import { Figure, useResident, useWide } from "./useResident";
+
+// The resident on the hub. It stands on the rule over the three guides โ
+// at first at the rule's start, under the page's own name โ and it goes
+// where the reader points:
+//
+// ยท the mouse or the Tab key on a guide (store.preview, as before): it
+// walks to that guide, hopping the gaps between the three rules;
+// ยท โ and โ (or D and A): it walks a guide on or a guide back, and the
+// guide it stands over is the chosen one โ the same state as pointing at
+// it, so the device answers (the hub marks the column [data-here]);
+// โ from the first guide takes it home and nothing is chosen;
+// ยท Enter or Space: into the chosen guide (the guide's own link is
+// followed, so the page leaves the way it always does); Escape: nothing
+// chosen.
+//
+// It takes nothing from anyone. No focus: Tab walks the three links as it
+// always did, and while one of them has the focus the arrows move the focus
+// along them instead. Enter and Space are left alone unless a guide has been
+// chosen with the arrows and nothing has the focus. The mouse takes the
+// choice back by moving (GuideHub). Under 900 px there is no resident, and
+// no keys.
+
+/** 3 px a cell: 21 ร 18 px, beside names 96 px tall. */
+const SCALE = 3;
+const SETUP: ResidentSetup = { scale: SCALE, hop: 8, sitAfter: 7000 };
+/** What it keeps between itself and the page's words, px. */
+const CLEAR = 16;
+
+type Props = {
+ /** The hub's choices (.inner): the block it lives in, and measures. */
+ within: RefObject;
+ /** The guide chosen by walking to it, or null. */
+ chosen: GuidePageId | null;
+ onChoose: (guide: GuidePageId | null) => void;
+};
+
+function OnHub({ within, chosen, onChoose }: Props) {
+ const { el, path, engine } = useResident(SETUP);
+ /** Where it stands for: home, then each guide (its left edge, in the block). */
+ const stops = useRef([]);
+ /** Where it is, or is going: โ1 home, else the guide's place in the row. */
+ const pos = useRef(-1);
+ const chosenNow = useRef(chosen);
+ useEffect(() => {
+ chosenNow.current = chosen;
+ }, [chosen]);
+
+ // Its line, and its places on it.
+ useEffect(() => {
+ const box = within.current;
+ const r = engine.current;
+ if (!box || !r) return;
+ const measure = () => {
+ const cols = Array.from(box.querySelectorAll("[data-guide]"));
+ if (!cols.length || cols[0].offsetWidth === 0) return;
+ const b = box.getBoundingClientRect();
+ const rects = cols.map((c) => {
+ const q = c.getBoundingClientRect();
+ return { left: q.left - b.left, right: q.right - b.left, top: q.top - b.top };
+ });
+ // The words on the line above the rule: the page's sentence at its left end, the report at its right.
+ let wordsEnd = -Infinity;
+ const title = box.querySelector("h1");
+ if (title) {
+ const range = document.createRange();
+ range.selectNodeContents(title);
+ wordsEnd = range.getBoundingClientRect().right - b.left;
+ }
+ const report = box.querySelector("[data-report]");
+ const reportStart = report ? report.getBoundingClientRect().left - b.left : Infinity;
+ const w = r.width;
+ const next = [rects[0].left];
+ for (const c of rects) {
+ // Over the middle of its guide; clear of the words where the column has room for that.
+ let s = (c.left + c.right) / 2 - w / 2;
+ if (s < wordsEnd + CLEAR && wordsEnd + CLEAR + w <= c.right - 8) s = wordsEnd + CLEAR;
+ if (s + w > reportStart - CLEAR && reportStart - CLEAR - w >= Math.max(c.left + 8, wordsEnd + CLEAR)) s = reportStart - CLEAR - w;
+ next.push(s);
+ }
+ stops.current = next;
+ // The three rules are three: it hops from one to the next.
+ const gaps: number[] = [];
+ let half = 0;
+ for (let i = 0; i + 1 < rects.length; i++) {
+ gaps.push((rects[i].right + rects[i + 1].left) / 2);
+ half = Math.max(half, (rects[i + 1].left - rects[i].right) / 2 + 12);
+ }
+ r.setGaps(gaps, half);
+ // Feet on the rule.
+ r.setGround(b.left, rects[0].top - ROWS * SCALE);
+ r.put(next[pos.current + 1]);
+ };
+ measure();
+ const ro = new ResizeObserver(measure);
+ ro.observe(box);
+ window.addEventListener("resize", measure);
+ return () => {
+ ro.disconnect();
+ window.removeEventListener("resize", measure);
+ };
+ }, [within, engine]);
+
+ // The guide pointed at โ by the mouse, the Tab key, or the arrows below: it goes there. Entering one: a hop.
+ useEffect(
+ () =>
+ useGuideStore.subscribe((s, was) => {
+ const r = engine.current;
+ if (!r || s.page !== "hub") return;
+ if (s.preview !== was.preview) {
+ if (s.preview) {
+ pos.current = GUIDE_ORDER.indexOf(s.preview);
+ r.walkTo(stops.current[pos.current + 1]);
+ }
+ // It does not sit down on a choice.
+ r.setRestful(s.preview === null);
+ }
+ if (s.leaving !== was.leaving && s.leaving && s.leaving !== "hub") r.hop();
+ }),
+ [engine],
+ );
+
+ // The keys.
+ useEffect(() => {
+ /** Choose a guide, or none. None hands the pointing back to the mouse: true if it is resting on a guide. */
+ const choose = (guide: GuidePageId | null): boolean => {
+ const s = useGuideStore.getState();
+ const was = chosenNow.current;
+ chosenNow.current = guide;
+ onChoose(guide);
+ if (guide) {
+ s.setPreview(guide);
+ return false;
+ }
+ const under = within.current?.querySelector("[data-guide]:hover")?.dataset.guide as GuidePageId | undefined;
+ if (under) s.setPreview(under);
+ else if (was && s.preview === was) s.setPreview(null);
+ return Boolean(under);
+ };
+ const onKey = (e: KeyboardEvent) => {
+ if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) return;
+ if (busy(e.target) || useGuideStore.getState().leaving !== null) return;
+ const box = within.current;
+ const r = engine.current;
+ if (!box || !r || !r.isPlaced) return;
+ const k = e.key;
+ const dir = k === "ArrowRight" || k === "d" || k === "D" ? 1 : k === "ArrowLeft" || k === "a" || k === "A" ? -1 : 0;
+ const active = document.activeElement as HTMLElement | null;
+ if (dir) {
+ // A guide's link has the focus: the arrows move the focus along the three, and the resident follows it.
+ const links = Array.from(box.querySelectorAll("[data-guide] > a"));
+ const at = active ? links.indexOf(active as HTMLAnchorElement) : -1;
+ if (at >= 0) {
+ e.preventDefault();
+ links[at + dir]?.focus();
+ return;
+ }
+ const to = Math.max(-1, Math.min(GUIDE_ORDER.length - 1, pos.current + dir));
+ e.preventDefault();
+ if (to < 0) {
+ // Home: nothing is chosen (unless the mouse is on a guide: then that one is, and it goes there).
+ if (choose(null)) return;
+ pos.current = -1;
+ r.walkTo(stops.current[0]);
+ return;
+ }
+ // (At the row's end, with the guide it stands over not chosen yet: chosen now.)
+ pos.current = to;
+ choose(GUIDE_ORDER[to]);
+ r.walkTo(stops.current[to + 1]);
+ return;
+ }
+ const guide = chosenNow.current;
+ if (!guide) return;
+ if (k === "Escape") {
+ choose(null);
+ return;
+ }
+ // Enter and Space belong to whatever has the focus; with nothing focused, they go in.
+ if ((k === "Enter" || k === " ") && (!active || active === document.body)) {
+ e.preventDefault();
+ box.querySelector(`[data-guide="${guide}"] > a`)?.click();
+ }
+ };
+ window.addEventListener("keydown", onKey);
+ return () => window.removeEventListener("keydown", onKey);
+ }, [within, engine, onChoose]);
+
+ return ;
+ /** The chapter the reader is in, โ1 on the opening and the end. */
+ index: number;
+ /** How far through that chapter, 0..1 (the marker's fill). */
+ fill: number;
+ /** The guide's end is on screen. */
+ end: boolean;
+};
+
+type Place = Pick;
+
+/** Its place on the rail for where the reader is (its left edge, in the rail), or null while the rail is not laid out. */
+function where(rail: HTMLElement, r: Resident, { index, fill, end }: Place): number | null {
+ const items = rail.querySelectorAll("a");
+ if (!items.length || items[0].offsetWidth === 0) return null;
+ const item = index >= 0 ? items[index] : end ? items[items.length - 1] : items[0];
+ if (!item) return null;
+ const f = index >= 0 ? fill : end ? 1 : 0;
+ // A chapter's item ends where the next begins: over the join, a hop.
+ const joins: number[] = [];
+ for (let i = 0; i + 1 < items.length; i++) joins.push((items[i].offsetLeft + items[i].offsetWidth + items[i + 1].offsetLeft) / 2);
+ r.setGaps(joins, 9);
+ r.setGround(rail.getBoundingClientRect().left);
+ const x = item.offsetLeft + INSET + f * (item.offsetWidth - 2 * INSET) - r.width / 2;
+ // The rail's ends are round: it keeps to the flat of its top.
+ return Math.min(rail.offsetWidth - ROUND - r.width, Math.max(ROUND, x));
+}
+
+function OnRail({ nav, index, fill, end }: Props) {
+ const { el, path, engine } = useResident(SETUP);
+ const at = useRef({ index, fill, end });
+
+ // The reader has moved on: it goes there.
+ useEffect(() => {
+ at.current = { index, fill, end };
+ const rail = nav.current;
+ const r = engine.current;
+ if (!rail || !r) return;
+ const x = where(rail, r, at.current);
+ if (x !== null) r.walkTo(x);
+ }, [nav, engine, index, fill, end]);
+
+ // The items' widths change with the window and with their fonts: it is put where it belongs, not walked.
+ useEffect(() => {
+ const rail = nav.current;
+ if (!rail) return;
+ const ro = new ResizeObserver(() => {
+ const r = engine.current;
+ const x = r && where(rail, r, at.current);
+ if (r && x !== null && x !== undefined) r.put(x);
+ });
+ ro.observe(rail);
+ return () => ro.disconnect();
+ }, [nav, engine]);
+
+ return {
+ const lit = new Set();
+ for (const m of d.matchAll(/M(\d+) (\d+)h(\d+)v1h-\d+z/g)) {
+ for (let i = 0; i < Number(m[3]); i++) lit.add(`${Number(m[1]) + i},${m[2]}`);
+ }
+ return lit;
+}
+
+describe("the resident's frames", () => {
+ it("every pose with every eyes is a figure inside its 7 ร 6 cells", () => {
+ for (const pose of POSES) {
+ for (const eyes of EYES) {
+ const lit = cells(framePath(pose, eyes));
+ expect(lit.size).toBeGreaterThan(20);
+ for (const c of lit) {
+ const [x, y] = c.split(",").map(Number);
+ expect(x).toBeLessThan(COLS);
+ expect(y).toBeLessThan(ROWS);
+ }
+ }
+ }
+ });
+
+ it("has two eyes, a cell each, that close in a blink and move in a glance", () => {
+ const open = cells(framePath("stand", "mid"));
+ const shut = cells(framePath("stand", "shut"));
+ expect(shut.size - open.size).toBe(2);
+ const left = cells(framePath("stand", "left"));
+ const right = cells(framePath("stand", "right"));
+ expect(left.size).toBe(open.size);
+ expect(right.size).toBe(open.size);
+ expect([...left].sort()).not.toEqual([...right].sort());
+ });
+
+ it("stands on the bottom row in every pose (its feet are on the line)", () => {
+ for (const pose of POSES) {
+ const lit = cells(framePath(pose, "mid"));
+ expect([...lit].some((c) => c.endsWith(`,${ROWS - 1}`))).toBe(true);
+ }
+ });
+});
+
+describe("the resident's engine", () => {
+ const make = () => {
+ const el = document.createElement("span");
+ const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+ return { el, path, r: new Resident(el, path as SVGPathElement, { scale: 3, hop: 8, sitAfter: 0 }) };
+ };
+
+ it("is not shown until it has been put somewhere, and is then on whole pixels", () => {
+ const { el, r } = make();
+ expect(el.dataset.on).toBeUndefined();
+ r.still = true;
+ r.place(123.6);
+ expect(el.dataset.on).toBe("1");
+ expect(el.style.transform).toBe("translate3d(124px,0px,0)");
+ r.destroy();
+ });
+
+ it("under reduced motion goes straight to its place, and neither hops nor glances", () => {
+ const { el, path, r } = make();
+ r.still = true;
+ r.place(10);
+ const frame = path.getAttribute("d");
+ r.walkTo(400);
+ expect(el.style.transform).toBe("translate3d(400px,0px,0)");
+ r.hop();
+ r.glance(1);
+ expect(el.style.transform).toBe("translate3d(400px,0px,0)");
+ expect(path.getAttribute("d")).toBe(frame);
+ r.destroy();
+ });
+
+ it("knows where its middle is on the screen (for the glance)", () => {
+ const { r } = make();
+ r.still = true;
+ r.setGround(100);
+ r.place(50);
+ expect(r.centre).toBe(100 + 50 + r.width / 2);
+ r.destroy();
+ });
+});
diff --git a/web/src/components/guide/ui/resident/sprite.ts b/web/src/components/guide/ui/resident/sprite.ts
new file mode 100644
index 00000000..b6fd67ce
--- /dev/null
+++ b/web/src/components/guide/ui/resident/sprite.ts
@@ -0,0 +1,61 @@
+// The resident: a small figure that lives in the guide, drawn the way the
+// panel draws โ square lit cells, seven across and six up. A round body, two
+// eyes that are two dark cells, two feet. Nothing is downloaded: a frame is a
+// pose (five of them) with a row of eyes set into it (four), a few rows of
+// text each, and it is turned into one SVG path the first time it is shown.
+//
+// Why this one. Three were drawn at the sizes it is seen at (14 px on a
+// guide's chapter rail, 21 px on the hub): a 5-cell-wide person, a square
+// "LED with legs", and this. The person's head is three cells โ no room for
+// eyes, and at 14 px it is a twig. The square read as a robot, and its eyes
+// closed up at 2 px a cell. This one keeps two eyes at both sizes, and its
+// head is seven cells wide, so the eyes have somewhere to go: one cell left
+// or right is a glance.
+
+export const COLS = 7;
+export const ROWS = 6;
+
+export type Pose = "stand" | "stepA" | "stepB" | "hop" | "sit";
+export type Eyes = "mid" | "left" | "right" | "shut";
+
+const EYES: Record = {
+ mid: "##.#.##",
+ left: "#.#.###",
+ right: "###.#.#",
+ shut: "#######",
+};
+
+// "E" is the row the eyes go in.
+const BODY = ["..###..", ".#####.", "E", "#######", ".#####."];
+const POSES: Record = {
+ stand: [...BODY, ".##.##."],
+ // Walking: one foot down, then the other.
+ stepA: [...BODY, ".##...."],
+ stepB: [...BODY, "....##."],
+ // In the air: feet out.
+ hop: [...BODY, "#.....#"],
+ // Sat down: a row lower, feet tucked under.
+ sit: [".......", "..###..", ".#####.", "E", "#######", "#######"],
+};
+
+const made = new Map();
+
+/** A frame as an SVG path, a unit a cell (runs of lit cells along a row are one box). */
+export function framePath(pose: Pose, eyes: Eyes): string {
+ const key = `${pose}:${eyes}`;
+ const had = made.get(key);
+ if (had !== undefined) return had;
+ let d = "";
+ POSES[pose].forEach((line, y) => {
+ const row = line === "E" ? EYES[eyes] : line;
+ for (let x = 0; x < COLS; x++) {
+ if (row[x] !== "#") continue;
+ let end = x;
+ while (end + 1 < COLS && row[end + 1] === "#") end++;
+ d += `M${x} ${y}h${end - x + 1}v1h${x - end - 1}z`;
+ x = end;
+ }
+ });
+ made.set(key, d);
+ return d;
+}
diff --git a/web/src/components/guide/ui/resident/useResident.tsx b/web/src/components/guide/ui/resident/useResident.tsx
new file mode 100644
index 00000000..b74ba32e
--- /dev/null
+++ b/web/src/components/guide/ui/resident/useResident.tsx
@@ -0,0 +1,93 @@
+"use client";
+
+import { useEffect, useRef, useSyncExternalStore, type CSSProperties, type RefObject } from "react";
+import css from "./Resident.module.css";
+import { Resident, type ResidentSetup } from "./engine";
+import { COLS, ROWS, framePath } from "./sprite";
+
+// The figure's element and its engine, for whoever gives it a line to stand
+// on (HubResident, RailResident). The engine is made when the figure mounts;
+// the one thing wired here is its glance โ which side of it the mouse is on,
+// worked out on the pointer's own events and nowhere else.
+
+/** A window wide enough for it: under 900 px (a phone) there is no resident at all. */
+export function useWide(): boolean {
+ return useSyncExternalStore(
+ (changed) => {
+ const mq = window.matchMedia("(min-width: 900px)");
+ mq.addEventListener("change", changed);
+ return () => mq.removeEventListener("change", changed);
+ },
+ () => window.matchMedia("(min-width: 900px)").matches,
+ // Not in the server's markup: it is put in by the browser that has room for it.
+ () => false,
+ );
+}
+
+export function useResident(setup: ResidentSetup) {
+ const el = useRef(null);
+ const path = useRef(null);
+ const engine = useRef(null);
+
+ useEffect(() => {
+ if (!el.current || !path.current) return;
+ const r = new Resident(el.current, path.current, setup);
+ engine.current = r;
+ const calm = window.matchMedia("(prefers-reduced-motion: reduce)");
+ const onCalm = () => {
+ r.still = calm.matches;
+ };
+ onCalm();
+ calm.addEventListener("change", onCalm);
+ // A glance: toward the pointer, once it is clearly to one side.
+ let side: -1 | 0 | 1 = 0;
+ const onMove = (e: PointerEvent) => {
+ if (e.pointerType !== "mouse" || !r.isPlaced) return;
+ const dx = e.clientX - r.centre;
+ const next = dx > 26 ? 1 : dx < -26 ? -1 : 0;
+ if (next !== side) {
+ side = next;
+ r.glance(next);
+ }
+ };
+ window.addEventListener("pointermove", onMove, { passive: true });
+ return () => {
+ window.removeEventListener("pointermove", onMove);
+ calm.removeEventListener("change", onCalm);
+ r.destroy();
+ engine.current = null;
+ };
+ }, [setup]);
+
+ return { el, path, engine };
+}
+
+/** The figure. Hidden from assistive technology and out of the tab order; a click on it is a hop. */
+export function Figure({
+ el,
+ path,
+ engine,
+ scale,
+ place,
+}: {
+ el: RefObject;
+ path: RefObject;
+ engine: RefObject;
+ scale: number;
+ place: "hub" | "rail";
+}) {
+ return (
+ engine.current?.hop()}
+ >
+
+
+
+ );
+}
diff --git a/web/src/components/guide/ui/stageLoad.ts b/web/src/components/guide/ui/stageLoad.ts
new file mode 100644
index 00000000..20c5c2e8
--- /dev/null
+++ b/web/src/components/guide/ui/stageLoad.ts
@@ -0,0 +1,38 @@
+// How far the 3D stage is from being on the page โ between the stage's own
+// chunk, which knows (ui/StageLoadReport, loaded with three.js), and the
+// page's preloader, which shows it (ui/Preloader, in the page's bundle and so
+// there from the first paint). Nothing here pulls three.js into the page.
+
+export type StageLoad = {
+ /** The stage's chunk has arrived and its canvas is mounting. */
+ staged: boolean;
+ /** The models: 0..1 of what the loader has been asked for. */
+ frac: number;
+ /** The device has been drawn and the frames run smooth: the stage can be shown. */
+ ready: boolean;
+ /** There will be no stage: this browser cannot draw it (no WebGL). */
+ failed: boolean;
+};
+
+const state: StageLoad = { staged: false, frac: 0, ready: false, failed: false };
+const subs = new Set<() => void>();
+
+export const stageLoad = {
+ get: (): Readonly => state,
+ set(patch: Partial) {
+ let changed = false;
+ for (const key of Object.keys(patch) as (keyof StageLoad)[]) {
+ if (state[key] !== patch[key]) {
+ (state[key] as StageLoad[typeof key]) = patch[key] as StageLoad[typeof key];
+ changed = true;
+ }
+ }
+ if (changed) subs.forEach((fn) => fn());
+ },
+ subscribe(fn: () => void) {
+ subs.add(fn);
+ return () => {
+ subs.delete(fn);
+ };
+ },
+};
diff --git a/web/src/components/guide/ui/ui.test.ts b/web/src/components/guide/ui/ui.test.ts
new file mode 100644
index 00000000..5de503f4
--- /dev/null
+++ b/web/src/components/guide/ui/ui.test.ts
@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest";
+import { PANEL_H, PANEL_W } from "@/lib/guide/panelScreens";
+import { accentFor, accentLab, contrast, labToRgb, LED_ORANGE, readPanel, type Rgb } from "./panelTint";
+import { COLS, countMatrix, ROWS } from "./Preloader";
+
+// The page's accent follows the panel (ui/panelTint.ts). Whatever the panel
+// shows, the accent has to stay something the page can be read in: it is the
+// colour of small type on the room's dark, and the ground of a button whose
+// label is dark ink.
+
+const GROUND: Rgb = [10, 9, 8];
+const CARD: Rgb = [20, 18, 16];
+const INK_ON_LED: Rgb = [21, 10, 6];
+
+function frameOf(paint: (x: number, y: number) => Rgb): Uint8ClampedArray {
+ const f = new Uint8ClampedArray(PANEL_W * PANEL_H * 4);
+ for (let y = 0; y < PANEL_H; y++) {
+ for (let x = 0; x < PANEL_W; x++) {
+ const [r, g, b] = paint(x, y);
+ const i = (y * PANEL_W + x) * 4;
+ f[i] = r;
+ f[i + 1] = g;
+ f[i + 2] = b;
+ f[i + 3] = 255;
+ }
+ }
+ return f;
+}
+
+/** Hue of an sRGB colour, degrees (HSV's: enough to say "it is a blue"). */
+function hue([r, g, b]: Rgb) {
+ const max = Math.max(r, g, b);
+ const min = Math.min(r, g, b);
+ if (max === min) return 0;
+ const d = max - min;
+ const h = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+ return (h * 60 + 360) % 360;
+}
+
+const PATTERNS: Record = {
+ dark: frameOf(() => [0, 0, 0]),
+ "the reddest": frameOf(() => [255, 0, 0]),
+ "the bluest": frameOf(() => [0, 0, 255]),
+ "the greenest": frameOf(() => [0, 255, 0]),
+ white: frameOf(() => [255, 255, 255]),
+ "dim grey": frameOf(() => [40, 40, 40]),
+ magenta: frameOf(() => [255, 0, 255]),
+ cyan: frameOf(() => [0, 255, 255]),
+ yellow: frameOf(() => [255, 255, 0]),
+ // Origin, more or less: mostly black, white blocks, a red heart.
+ "white with a red heart": frameOf((x, y) => (x > 50 && x < 70 && y > 22 && y < 42 ? [255, 30, 20] : (x >> 3) % 2 && (y >> 3) % 2 ? [255, 255, 255] : [0, 0, 0])),
+ // Every hue at once: nothing to follow.
+ rainbow: frameOf((x) => {
+ const h = (x / PANEL_W) * 6;
+ const f = h % 1;
+ const s = Math.floor(h);
+ const up = Math.round(f * 255);
+ const down = 255 - up;
+ return ([[255, up, 0], [down, 255, 0], [0, 255, up], [0, down, 255], [up, 0, 255], [255, 0, down]] as Rgb[])[s % 6];
+ }),
+};
+
+describe("the page's accent, from the panel", () => {
+ it("is the LED orange when the panel is dark", () => {
+ expect(accentFor(PATTERNS.dark)).toEqual(LED_ORANGE);
+ });
+
+ it.each(Object.keys(PATTERNS))("reads on the dark, and under dark ink: %s", (name) => {
+ const accent = accentFor(PATTERNS[name]);
+ // Small type in the accent on the room's ground and on a card.
+ expect(contrast(accent, GROUND)).toBeGreaterThanOrEqual(4.5);
+ expect(contrast(accent, CARD)).toBeGreaterThanOrEqual(4.5);
+ // A button's dark label on the accent.
+ expect(contrast(INK_ON_LED, accent)).toBeGreaterThanOrEqual(4.5);
+ // Never white-hot, never a neon: no channel pinned at both ends.
+ const [r, g, b] = accent;
+ expect(Math.max(r, g, b) - Math.min(r, g, b)).toBeLessThan(205);
+ });
+
+ it("takes the panel's hue", () => {
+ const blue = hue(accentFor(PATTERNS["the bluest"]));
+ expect(blue).toBeGreaterThan(200);
+ expect(blue).toBeLessThan(270);
+ const green = hue(accentFor(PATTERNS["the greenest"]));
+ expect(green).toBeGreaterThan(90);
+ expect(green).toBeLessThan(160);
+ const red = hue(accentFor(PATTERNS["the reddest"]));
+ expect(red < 25 || red > 340).toBe(true);
+ });
+
+ it("finds the colour in a pattern that is mostly white", () => {
+ const light = readPanel(PATTERNS["white with a red heart"]);
+ expect(light.rgb[0]).toBeGreaterThan(200);
+ expect(light.rgb[1]).toBeLessThan(80);
+ const accent = hue(accentFor(PATTERNS["white with a red heart"]));
+ expect(accent < 30 || accent > 340).toBe(true);
+ });
+
+ it("pales toward the orange for a white panel, and keeps its warmth", () => {
+ const white = accentFor(PATTERNS.white);
+ const h = hue(white);
+ expect(h).toBeGreaterThan(5);
+ expect(h).toBeLessThan(45);
+ // Paler than the orange itself.
+ const spread = (c: Rgb) => Math.max(...c) - Math.min(...c);
+ expect(spread(white)).toBeLessThan(spread(LED_ORANGE));
+ });
+
+ it("is in gamut whatever is asked of it", () => {
+ for (const name of Object.keys(PATTERNS)) {
+ const rgb = labToRgb(accentLab(readPanel(PATTERNS[name])));
+ for (const c of rgb) {
+ expect(c).toBeGreaterThanOrEqual(0);
+ expect(c).toBeLessThanOrEqual(255);
+ }
+ }
+ });
+});
+
+// The preloader's counter (ui/Preloader.tsx): the firmware's 5ร7 figures, on
+// a matrix of LEDs.
+
+function lit(grid: Float32Array) {
+ let n = 0;
+ for (const v of grid) if (v > 0) n++;
+ return n;
+}
+
+describe("the preloader's counter", () => {
+ const grid = new Float32Array(COLS * ROWS);
+
+ it("draws 000 with its leading zeros faint", () => {
+ countMatrix(0, grid);
+ const levels = new Set(Array.from(grid).filter((v) => v > 0).map((v) => Number(v.toFixed(2))));
+ expect(levels).toEqual(new Set([0.2, 1]));
+ // The units' zero is full, the two in front are not.
+ expect(grid.filter((v) => v === 1).length * 2).toBe(grid.filter((v) => v > 0 && v < 1).length);
+ });
+
+ it("draws 100 with nothing faint", () => {
+ countMatrix(100, grid);
+ expect(Array.from(grid).every((v) => v === 0 || v === 1)).toBe(true);
+ expect(lit(grid)).toBeGreaterThan(100);
+ });
+
+ it("keeps every figure inside its window while it rolls", () => {
+ let outside = 0;
+ for (let v = 0; v <= 100; v += 0.37) {
+ countMatrix(v, grid);
+ for (let y = 0; y < ROWS; y++) {
+ for (let x = 0; x < COLS; x++) {
+ if (grid[y * COLS + x] && (y < 3 || y >= ROWS - 3 || x < 3 || x >= COLS - 3)) outside++;
+ }
+ }
+ }
+ expect(outside).toBe(0);
+ });
+
+ it("does not roll when asked not to", () => {
+ const a = new Float32Array(COLS * ROWS);
+ const b = new Float32Array(COLS * ROWS);
+ countMatrix(41.6, a, false);
+ countMatrix(41, b, false);
+ expect(Array.from(a)).toEqual(Array.from(b));
+ });
+});
diff --git a/web/src/components/guide/ui/useReveal.ts b/web/src/components/guide/ui/useReveal.ts
new file mode 100644
index 00000000..2d7c3321
--- /dev/null
+++ b/web/src/components/guide/ui/useReveal.ts
@@ -0,0 +1,51 @@
+"use client";
+
+import { useEffect, type RefObject } from "react";
+
+// What arrives when the reader reaches it โ a chapter's number, its title's
+// words, the end's โ arrives once. A block marked [data-reveal] gets
+// [data-in] the first time it comes onto the screen and keeps it: scrolling
+// away and back, or back and forth across its edge, plays nothing again.
+//
+// A block that is already above the screen when the page opens (a link to a
+// step further down, the other language at the same place) is marked
+// "still": it is there, with no arriving, when the reader scrolls up to it.
+//
+// What is watched is the block's [data-reveal-at] (its title) when it has
+// one, not the block: a chapter's head is most of a screen tall, and its
+// words are not at its top.
+
+export function useReveal(root: RefObject) {
+ useEffect(() => {
+ const el = root.current;
+ if (!el) return;
+ const blocks = Array.from(el.querySelectorAll("[data-reveal]"));
+ if (typeof IntersectionObserver === "undefined") {
+ blocks.forEach((b) => b.setAttribute("data-in", "still"));
+ return;
+ }
+ const io = new IntersectionObserver(
+ (entries) => {
+ for (const entry of entries) {
+ const block = (entry.target as HTMLElement).closest("[data-reveal]");
+ if (!block) continue;
+ if (entry.isIntersecting) {
+ block.setAttribute("data-in", "1");
+ io.unobserve(entry.target);
+ } else if (entry.boundingClientRect.bottom < 0) {
+ // Passed before it was ever seen.
+ block.setAttribute("data-in", "still");
+ io.unobserve(entry.target);
+ }
+ }
+ },
+ // A little inside the bottom of the screen, so it starts where it can be seen starting.
+ { rootMargin: "0px 0px -12% 0px" },
+ );
+ for (const block of blocks) {
+ if (block.hasAttribute("data-in")) continue;
+ io.observe(block.querySelector("[data-reveal-at]") ?? block);
+ }
+ return () => io.disconnect();
+ }, [root]);
+}
diff --git a/web/src/components/guide/ui/useStepKeys.ts b/web/src/components/guide/ui/useStepKeys.ts
new file mode 100644
index 00000000..aca601da
--- /dev/null
+++ b/web/src/components/guide/ui/useStepKeys.ts
@@ -0,0 +1,72 @@
+"use client";
+
+import { useEffect, type RefObject } from "react";
+
+// The guide by keyboard: โ or J to the next stop, โ or K to the one before.
+// A stop is what the scroll would stop on: the opening, each chapter's title,
+// each step's card, the end. The page is scrolled there โ the same thing a
+// wheel does, so the stage follows as it always does โ and nothing takes the
+// focus: Tab still walks the links from where it was.
+//
+// The keys are left alone while they are someone else's: typing in a field
+// or the Lab's editor, a window on Make's desk (its patterns scroll and its
+// deck is rearranged with the arrows), the device's console, a held modifier.
+
+/** Where the keyboard is busy with something of its own. */
+export function busy(target: EventTarget | null): boolean {
+ const el = target as HTMLElement | null;
+ if (!el || typeof el.closest !== "function") return false;
+ if (el.isContentEditable) return true;
+ return Boolean(el.closest("input, textarea, select, iframe, [contenteditable], [role='slider'], [role='tablist'], [data-win], [data-keys-own]"));
+}
+
+function reducedMotion() {
+ return window.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+}
+
+/** The page's stops, top to bottom, as scroll positions. */
+function stops(root: HTMLElement): number[] {
+ const vh = window.innerHeight;
+ const max = Math.max(0, document.documentElement.scrollHeight - vh);
+ const out: number[] = [0];
+ const centre = (el: Element) => {
+ const r = el.getBoundingClientRect();
+ return Math.round(Math.min(max, Math.max(0, window.scrollY + r.top + r.height / 2 - vh / 2)));
+ };
+ root.querySelectorAll("[data-scene]").forEach((scene) => {
+ const id = scene.dataset.scene;
+ if (id === "opening") return;
+ if (id === "next") {
+ out.push(centre(scene));
+ return;
+ }
+ const head = scene.querySelector("header");
+ if (head) out.push(centre(head));
+ scene.querySelectorAll("[data-step]").forEach((step) => out.push(centre(step)));
+ });
+ // In order, and no two on top of each other (a short page's last stops all clamp to its end).
+ return out.sort((a, b) => a - b).filter((y, i, all) => i === 0 || y - all[i - 1] > 8);
+}
+
+export function useStepKeys(root: RefObject) {
+ useEffect(() => {
+ const onKey = (e: KeyboardEvent) => {
+ if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) return;
+ const dir = e.key === "ArrowRight" || e.key === "j" || e.key === "J" ? 1 : e.key === "ArrowLeft" || e.key === "k" || e.key === "K" ? -1 : 0;
+ if (!dir || busy(e.target) || busy(document.activeElement)) return;
+ // A window lifted off the page (the console, a practice dialog) holds the page still.
+ if (document.querySelector("[role='dialog']")) return;
+ const el = root.current;
+ if (!el) return;
+ const all = stops(el);
+ const y = window.scrollY;
+ // From between two stops, the next one in that direction; from on one, the one after.
+ const next = dir > 0 ? all.find((s) => s > y + 8) : [...all].reverse().find((s) => s < y - 8);
+ if (next === undefined) return;
+ e.preventDefault();
+ window.scrollTo({ top: next, behavior: reducedMotion() ? "auto" : "smooth" });
+ };
+ window.addEventListener("keydown", onKey);
+ return () => window.removeEventListener("keydown", onKey);
+ }, [root]);
+}
diff --git a/web/src/components/guide/world/GuideLink.tsx b/web/src/components/guide/world/GuideLink.tsx
new file mode 100644
index 00000000..a41d5be6
--- /dev/null
+++ b/web/src/components/guide/world/GuideLink.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import type { ComponentProps } from "react";
+import { pagePath, placeAnchor } from "../pages";
+import { useGuideStore, type GuideLang, type GuideScreen } from "../store";
+
+// A way from one page of the guide to another: the hub's three choices, a
+// guide's way back to the hub, the way on at its end, the language switch.
+//
+// It is a real link (its address is right for a new tab, a copied link, a
+// reader without scripts). Followed in place, the page does not just swap:
+// the words leave first (store.leaveFor โ Guide.module.css fades the story
+// on .world[data-leaving], and the stage holds what it is showing: on the
+// hub, the chosen guide's answer), and then the next page comes in over a
+// stage that never went away and plays its way there.
+//
+// `keepPlace` is for the same guide in the other language: the address
+// carries the step the reader is on, so they land where they were and the
+// stage carries on with what it was doing.
+
+/** How long the words take to leave before the next page is asked for, ms (the fade is Guide.module.css's). */
+export const LEAVE_MS = 200;
+
+let pending = 0;
+
+function reducedMotion() {
+ return typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+}
+
+type Props = Omit, "href"> & {
+ to: GuideScreen;
+ lang: GuideLang;
+ /** Land on the step the reader is on now (the language switch). */
+ keepPlace?: boolean;
+};
+
+export default function GuideLink({ to, lang, keepPlace, onNavigate, ...rest }: Props) {
+ const router = useRouter();
+ const href = pagePath(to, lang);
+ return (
+
+//
the room's glow ยท the canvas (world/WorldStage) ยท grain
+// {children} the page: GuideHub or GuideExperience
+//
+// What is here and what is the page's:
+// - A page says it is on screen with useGuidePage (world/usePage.ts โ
+// store.enterPage). The stage plays that page's script from then on.
+// - The stage reads everything else from the store: the hub's pointed-at
+// guide (store.preview), a way out being taken (store.leaving, from
+// world/GuideLink).
+// - The room's light and the canvas's mask are CSS on [data-screen], which
+// is read off the address, so the server's first paint already has them.
+// - Make has a desk instead of the device: the canvas stays mounted but
+// fades and rests (Guide.module.css, GuideCanvas). A reader who arrives
+// on Make never loads the stage at all until they go to a page with it.
+
+// three.js, the models and the simulated board: after the page's words.
+const WorldStage = dynamic(() => import("./WorldStage"), { ssr: false });
+
+// A browser that cannot give the stage a WebGL 2 context (turned off, an old
+// machine, a blocked GPU) gets the guide without it: the words, the cards and
+// the pictures are all there. Asked once, before the stage's chunk is; the
+// stage used to be loaded regardless, throw as it made its renderer, and
+// leave the page waiting on a canvas that would never draw.
+let webgl: boolean | null = null;
+function hasWebGL(): boolean {
+ if (webgl !== null) return webgl;
+ try {
+ // (A 1ร1 canvas nobody holds: its context goes with it.)
+ const probe = document.createElement("canvas");
+ probe.width = probe.height = 1;
+ webgl = !!probe.getContext("webgl2");
+ } catch {
+ webgl = false;
+ }
+ return webgl;
+}
+
+/**
+ * The stage is the guide's picture, not the guide. If it throws as it is
+ * made or drawn โ the context refused after all, a model that did not arrive
+ * โ it is taken off and the page stays whole: the words, the cards and the
+ * figures never depended on it. (Uncaught, the error went up to the site's
+ * error screen and took the page with it.) Whoever waits for the stage is
+ * told, as where there is no WebGL at all.
+ */
+class StageGuard extends Component<{ children: ReactNode }, { failed: boolean }> {
+ state = { failed: false };
+ static getDerivedStateFromError() {
+ return { failed: true };
+ }
+ componentDidCatch() {
+ stageLoad.set({ failed: true });
+ }
+ render() {
+ return this.state.failed ? null : this.props.children;
+ }
+}
+
+/** How long the hub's floor fade stays on the canvas after the hub is left: its ease down off the screen (Guide.module.css), ms. */
+const FOOT_LINGER_MS = 1000;
+/** A cut (store.requestCut): how long the canvas stays out before it comes back, ms. Its fade out is 0.14 s; the stage jumps at 0.17 s. */
+const CUT_MS = 300;
+/** A page that was asked for and never came (offline, a failed load): the words come back after this, ms. */
+const LEAVE_GIVE_UP_MS = 6000;
+
+export default function GuideWorld({ children }: { children: ReactNode }) {
+ const screen = screenAt(usePathname() ?? "")?.page ?? null;
+ // An address under /guide that is no page of the guide (the site's own
+ // "not found"): no stage, no dark room โ the site's page as it is.
+ if (!screen) return <>{children};
+ return
{children} ;
+}
+
+function World({ screen, children }: { screen: GuideScreen; children: ReactNode }) {
+ const page = useGuideStore((s) => s.page);
+ const entered = useGuideStore((s) => s.entered);
+ const leaving = useGuideStore((s) => s.leaving);
+ const hubTop = useGuideStore((s) => s.hubTop);
+
+ // The stage loads the first time a page with the device is on screen, and stays.
+ const [staged, setStaged] = useState(false);
+ if (!staged && entered && page !== "make" && hasWebGL()) setStaged(true);
+ // No stage is coming: whoever waits for it (the first visit's counter) is told.
+ useEffect(() => {
+ if (entered && page !== "make" && !hasWebGL()) stageLoad.set({ failed: true });
+ }, [entered, page]);
+
+ // The hub's floor fade: on with the hub, and until its ease away has run.
+ const [foot, setFoot] = useState(screen === "hub");
+ if (screen === "hub" && !foot) setFoot(true);
+ useEffect(() => {
+ if (screen === "hub" || !foot) return;
+ const timer = window.setTimeout(() => setFoot(false), FOOT_LINGER_MS);
+ return () => window.clearTimeout(timer);
+ }, [screen, foot]);
+
+ // A cut: the canvas dips to dark while the stage jumps, and comes back.
+ const cut = useGuideStore((s) => s.cut);
+ const [cutShown, setCutShown] = useState(cut);
+ useEffect(() => {
+ if (cut === cutShown) return;
+ const timer = window.setTimeout(() => setCutShown(cut), CUT_MS);
+ return () => window.clearTimeout(timer);
+ }, [cut, cutShown]);
+
+ // The document goes dark while the guide is open (darkDocument.ts).
+ useDarkDocument();
+
+ // Narrow screen: the stage sits above the text instead of beside it.
+ useEffect(() => {
+ const onResize = () => useGuideStore.getState().setNarrow(window.innerWidth < 900);
+ onResize();
+ window.addEventListener("resize", onResize);
+ return () => window.removeEventListener("resize", onResize);
+ }, []);
+
+ // The words left for a page that never arrived: back they come.
+ useEffect(() => {
+ if (!leaving) return;
+ const timer = window.setTimeout(() => useGuideStore.getState().leaveFor(null), LEAVE_GIVE_UP_MS);
+ return () => window.clearTimeout(timer);
+ }, [leaving]);
+
+ // Out of the guide altogether: the next visit starts from nothing.
+ useEffect(
+ () => () => {
+ useGuideStore.setState({ entered: false, preview: null, leaving: null, buildLive: false });
+ },
+ [],
+ );
+
+ return (
+
+
0 ? ({ "--hub-top": `${hubTop}px` } as CSSProperties) : undefined}>
+
+
+
+ {staged && (
+
+
+ )}
+
+
+
+ {children}
+
+ );
+}
diff --git a/web/src/components/guide/world/HubAnswers.tsx b/web/src/components/guide/world/HubAnswers.tsx
new file mode 100644
index 00000000..e32c72c0
--- /dev/null
+++ b/web/src/components/guide/world/HubAnswers.tsx
@@ -0,0 +1,122 @@
+"use client";
+
+import { useEffect } from "react";
+import { knobIsTurned, turnBackClick, turnBackNow, turnOn } from "../hubKnob";
+import { getSim, useGuideStore } from "../store";
+import { handBackNow } from "./hubHand";
+import { DRAW_MS, makeNext, makeRestore } from "./hubMake";
+
+// The hub's answers. On the hub the device answers the guide the reader is
+// pointing at (mouse or keyboard โ store.preview, from GuideHub), with what
+// that guide is about:
+//
+// Build the device comes apart: case, panel, board, DevKit, back, knobs,
+// each along the way it goes on (stage/Explode โ the stage's, not
+// the board's: a device in pieces is dark, and KitFx keeps it so)
+// Play K1 turns and Origin's colour follows (hubKnob.ts)
+// Make the pattern on the panel is made again and again (hubMake.ts)
+//
+// Pointing away puts it all back, as calmly as it came: the parts settle,
+// K1 turns back a click at a time, Origin is drawn back. Nothing answers
+// under reduced motion.
+//
+// And with nothing pointed at, the panel answers the hand itself: a mouse
+// over it steers Origin a little (hubHand.ts, from stage/StageHand.tsx). That is
+// given back here, at once, the moment anything else takes the board โ so
+// each answer starts from the board as the hub found it.
+//
+// This lives with the stage (world/WorldStage), not with the hub's page: the
+// board is the same one in every guide, and choosing a guide must not cut an
+// answer off. Going into Play, K1 finishes turning back there โ Play's words
+// call Origin red โ and going anywhere else it is back before the next
+// page's first frame, because that page may turn the panel off (Build opens
+// dark), and a knob only turns a pattern that is running.
+
+/** Play: one click of K1 (Origin's hue, which wraps) this often, in ms. */
+const PLAY_CLICK_MS = 120;
+/** Pointing away from Play: K1 turns back a click this often, in ms. */
+const BACK_CLICK_MS = 16;
+/** Build: pointed at for this long, its stage is readied on the canvas, in ms (the parts are apart and nearly still by then). */
+const BUILD_STANDBY_MS = 700;
+/** Make: a pattern holds this long once it is drawn, in ms. */
+const MAKE_HOLD_MS = 1150;
+
+function reducedMotion() {
+ return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+export default function HubAnswers() {
+ const page = useGuideStore((s) => s.page);
+ const guide = useGuideStore((s) => (s.page === "hub" ? s.preview : null));
+
+ // Off the hub to anywhere but Play: K1 home at once, inside the store's own
+ // update โ before the stage draws the next page's first frame.
+ useEffect(
+ () =>
+ useGuideStore.subscribe((s, prev) => {
+ // What the hand turned (hubHand.ts): back before a guide's answer
+ // begins, before the knobs are the reader's, before another page.
+ if (s.page !== prev.page || (s.preview && s.preview !== prev.preview) || (s.leaving && s.leaving !== prev.leaving) || (s.handsOn && !prev.handsOn)) {
+ handBackNow(getSim());
+ }
+ if (s.page === prev.page || prev.page !== "hub" || s.page === "play") return;
+ // Origin first: a knob turns the pattern that is running, and it is Origin's hue that is owed.
+ makeRestore(getSim());
+ turnBackNow(getSim());
+ }),
+ [],
+ );
+
+ useEffect(() => {
+ const sim = getSim();
+ if (reducedMotion()) {
+ turnBackNow(sim);
+ return;
+ }
+ if (guide === "play") {
+ turnOn(sim);
+ const timer = window.setInterval(() => turnOn(sim), PLAY_CLICK_MS);
+ return () => window.clearInterval(timer);
+ }
+ if (guide === "make") {
+ // K1 stays where Play left it for now: it is Origin's knob, and turns back once Origin is.
+ makeNext(sim);
+ const timer = window.setInterval(() => makeNext(sim), DRAW_MS + MAKE_HOLD_MS);
+ return () => {
+ window.clearInterval(timer);
+ makeRestore(sim);
+ };
+ }
+ // Build is pointed at: its stage and models start loading now (GuideCanvas
+ // loads the same module), and if the reader lingers the Build stage is
+ // put on the canvas in standby, where it gets its shaders built while the
+ // device hangs apart โ so choosing Build flows straight into the guide,
+ // which opens on the device as it hangs here (BuildStage, stage/Explode).
+ // It stays there, doing nothing, until the hub is left.
+ if (guide === "build") {
+ void import("../stage/build/BuildStage");
+ const timer = window.setTimeout(() => useGuideStore.getState().setBuildLive(true), BUILD_STANDBY_MS);
+ return () => window.clearTimeout(timer);
+ }
+ // Nothing pointed at, or Build (the stage's): the knob turns back and the
+ // colour comes home with it, a click at a time โ here, and in Play.
+ if (!knobIsTurned()) return;
+ if (page !== "hub" && page !== "play") return;
+ const timer = window.setInterval(() => {
+ if (turnBackClick(sim)) window.clearInterval(timer);
+ }, BACK_CLICK_MS);
+ return () => window.clearInterval(timer);
+ }, [guide, page]);
+
+ // The world is left (out of the guide altogether): the board as it was found.
+ useEffect(
+ () => () => {
+ handBackNow(getSim());
+ makeRestore(getSim());
+ turnBackNow(getSim());
+ },
+ [],
+ );
+
+ return null;
+}
diff --git a/web/src/components/guide/world/WorldStage.tsx b/web/src/components/guide/world/WorldStage.tsx
new file mode 100644
index 00000000..afa52575
--- /dev/null
+++ b/web/src/components/guide/world/WorldStage.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import GuideCanvas from "../stage/GuideCanvas";
+import StageLoadReport from "../ui/StageLoadReport";
+import HubAnswers from "./HubAnswers";
+
+// The 3D stage and what plays on it between the pages, as one piece to load:
+// three.js, the models and the simulated board come in here, after the page's
+// words (GuideWorld loads this on its own, the first time a page with a
+// device is on screen). Everything in it lives as long as the reader stays in
+// the guide.
+//
+// StageLoadReport says how far the stage is from being on the page (the
+// preloader shows it, ui/Preloader) and keeps the canvas out until the device
+// has been drawn.
+
+export default function WorldStage() {
+ return (
+ <>
+
+
+
+
+ );
+}
diff --git a/web/src/components/guide/world/framing.ts b/web/src/components/guide/world/framing.ts
new file mode 100644
index 00000000..9fe728a7
--- /dev/null
+++ b/web/src/components/guide/world/framing.ts
@@ -0,0 +1,60 @@
+// How the stage frames the device on a page: the part of the screen it may
+// take, and how far back the camera stands. The stage is one canvas over the
+// whole window for every page of the guide (world/GuideWorld); what differs
+// from page to page is this, and the camera (GuideCanvas CameraRig) eases
+// from one framing to the next.
+//
+// a guide the card's left on a wide screen, above it on a narrow one โ
+// measured off the page by the rig (GuideCanvas freeArea), scale 1
+// the hub above the three choices (hubFraming)
+// Make no device: it stands far back while the desk is up (AWAY_SCALE)
+//
+// Pure arithmetic, so it can be tested without a canvas.
+
+/** The free part of the screen, in CSS px. */
+export type Free = { l: number; r: number; t: number; b: number };
+
+export type Framing = {
+ free: Free;
+ /**
+ * How much further back than a view's own distance the camera stands
+ * (views.ts minR): 1 on a guide. The fit to `free` is unaffected โ this
+ * only moves the closest the camera comes.
+ */
+ scale: number;
+};
+
+/** Until the hub has measured where its choices start (store.hubTop): Hub.module.css's --hub-top default, 66vh. */
+const HUB_TOP_DEFAULT = 0.66;
+
+/**
+ * The hub. The device stands alone in the room above the choices, which
+ * start `hubTop` px down the screen.
+ *
+ * On a wide screen the hub's stage used to be a canvas of its own, a box
+ * round that room โ `99 โ hubTop/3` px from the top, `hubTop ร 1.667 โ 213`
+ * tall โ and the device stood in it at the view's own distance: from 72 px
+ * under the top of the screen to 56 px above the choices. The canvas is the
+ * whole window now, so the same picture is asked for in the window's terms:
+ * the box as the free area (less the 64 px and 32 px the stage keeps clear
+ * at its top and bottom), and the camera further back by the window's height
+ * over the box's.
+ *
+ * On a narrow screen the stage was always the whole screen: the device keeps
+ * what the choices leave above them, and never less than 36% of the height.
+ */
+export function hubFraming(w: number, h: number, hubTop: number, narrow: boolean): Framing {
+ const top = hubTop > 0 ? hubTop : h * HUB_TOP_DEFAULT;
+ if (narrow) return { free: { l: 12, r: w - 12, t: 56, b: Math.min(h - 12, Math.max(h * 0.36, top - 14)) }, scale: 1 };
+ const boxTop = 99 - top / 3;
+ const boxH = Math.max(240, top * 1.667 - 213);
+ return { free: { l: 24, r: w - 24, t: boxTop + 64, b: boxTop + boxH - 32 }, scale: h / boxH };
+}
+
+/** Make: how many times its own distance the device stands back while the desk has the screen. */
+export const AWAY_SCALE = 2.6;
+
+/** Make: the device, far back in the middle of the room behind the desk. */
+export function awayFraming(w: number, h: number): Framing {
+ return { free: { l: 24, r: w - 24, t: 64, b: h - 32 }, scale: AWAY_SCALE };
+}
diff --git a/web/src/components/guide/world/hubHand.test.ts b/web/src/components/guide/world/hubHand.test.ts
new file mode 100644
index 00000000..84662341
--- /dev/null
+++ b/web/src/components/guide/world/hubHand.test.ts
@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { DeviceSim } from "@/lib/guide/deviceSim";
+import { knobIsTurned, turnBackNow, turnOn } from "../hubKnob";
+import { useGuideStore } from "../store";
+import { handBackNow, handIsOn, handSteer } from "./hubHand";
+import { makeNext, makeRestore } from "./hubMake";
+
+// The hub's panel answers the hand: a mouse over it turns K1 and K2 a few
+// clicks. The board is the one every guide shares, so whatever comes next โ
+// the pointer leaves, a guide is pointed at, the knobs are taken, the page is
+// left โ it must be back as the hub found it, and the three answers must
+// find it so.
+
+const FRAME = 1 / 60;
+const MS = 1000 * FRAME;
+
+/** The pointer held at one place on the panel for `frames` frames (null: off the panel). */
+function hold(sim: DeviceSim, at: { u: number; v: number } | null, frames: number) {
+ for (let i = 0; i < frames; i++) {
+ handSteer(sim, at, MS);
+ sim.tick(FRAME);
+ }
+}
+
+describe("the hub's panel under the hand", () => {
+ let sim: DeviceSim;
+ beforeEach(() => {
+ useGuideStore.setState({ page: "hub", preview: null, leaving: null, handsOn: false });
+ sim = new DeviceSim();
+ sim.tick(FRAME);
+ });
+ // The count is kept with the board, outside any one hub: no test leaves it owing.
+ afterEach(() => {
+ useGuideStore.setState({ handsOn: false });
+ handBackNow(sim);
+ makeRestore(sim);
+ turnBackNow(sim);
+ });
+
+ it("does nothing with the pointer off the panel", () => {
+ hold(sim, null, 30);
+ expect(handIsOn()).toBe(false);
+ expect(sim.snapshot().turns).toEqual([0, 0, 0, 0]);
+ });
+
+ it("turns K1 across the panel and K2 up it, a click at a time, and no further than its reach", () => {
+ hold(sim, { u: 1, v: 1 }, 3);
+ const early = sim.snapshot().turns;
+ expect(early[0]).toBeGreaterThan(0);
+ expect(early[0]).toBeLessThanOrEqual(2);
+ hold(sim, { u: 1, v: 1 }, 120);
+ const t = sim.snapshot().turns;
+ expect(t[0]).toBe(9);
+ expect(t[1]).toBe(7);
+ expect(t[2]).toBe(0);
+ expect(t[3]).toBe(0);
+ expect(sim.knobReadout(0).value).toBeCloseTo(9 / 48, 6);
+ hold(sim, { u: -1, v: -1 }, 200);
+ expect(sim.snapshot().turns.slice(0, 2)).toEqual([-9, -7]);
+ });
+
+ it.each([
+ [1, 1],
+ [-1, 0.4],
+ [0.3, -1],
+ [-0.62, -0.77],
+ ])("is back exactly where it began once the pointer leaves the panel (%f, %f)", (u, v) => {
+ const speed = sim.knobReadout(1).value;
+ hold(sim, { u, v }, 90);
+ expect(handIsOn()).toBe(true);
+ hold(sim, null, 90);
+ expect(handIsOn()).toBe(false);
+ expect(sim.snapshot().turns).toEqual([0, 0, 0, 0]);
+ expect(sim.knobReadout(0).value).toBe(0);
+ expect(sim.knobReadout(1).value).toBeCloseTo(speed, 9);
+ });
+
+ it("is back at once when a guide is pointed at, and Play's answer starts from Origin's own start", () => {
+ hold(sim, { u: 0.8, v: -0.5 }, 90);
+ handBackNow(sim);
+ expect(handIsOn()).toBe(false);
+ expect(sim.knobReadout(0).value).toBe(0);
+ useGuideStore.setState({ preview: "play" });
+ // The hand does not steer while a guide has the board.
+ hold(sim, { u: 1, v: 1 }, 30);
+ expect(handIsOn()).toBe(false);
+ for (let i = 0; i < 12; i++) {
+ turnOn(sim);
+ sim.tick(FRAME);
+ }
+ useGuideStore.setState({ preview: null });
+ // โฆnor while K1 is still on its way back from Play's answer.
+ hold(sim, { u: 1, v: 1 }, 5);
+ expect(handIsOn()).toBe(false);
+ turnBackNow(sim);
+ expect(knobIsTurned()).toBe(false);
+ expect(sim.knobReadout(0).value).toBe(0);
+ });
+
+ it("leaves Make's pattern alone", () => {
+ makeNext(sim);
+ sim.tick(FRAME);
+ const before = sim.snapshot().turns;
+ hold(sim, { u: 1, v: 1 }, 60);
+ expect(handIsOn()).toBe(false);
+ expect(sim.snapshot().turns).toEqual(before);
+ });
+
+ it("gives the board back before the reader's own turn, and keeps out of it afterwards", () => {
+ hold(sim, { u: 1, v: 0 }, 90);
+ // The reader takes K3: Device presses it and says so (store.handsOn); HubAnswers calls handBackNow.
+ sim.press(2);
+ useGuideStore.setState({ handsOn: true });
+ handBackNow(sim);
+ sim.tick(FRAME);
+ expect(handIsOn()).toBe(false);
+ expect(sim.snapshot().down[2]).toBe(true);
+ expect(sim.knobReadout(0).value).toBeCloseTo(0, 9);
+ hold(sim, { u: -1, v: 1 }, 60);
+ expect(handIsOn()).toBe(false);
+ sim.release(2);
+ });
+
+ it("does not steer off the hub", () => {
+ useGuideStore.setState({ page: "play" });
+ hold(sim, { u: 1, v: 1 }, 60);
+ expect(handIsOn()).toBe(false);
+ });
+});
diff --git a/web/src/components/guide/world/hubHand.ts b/web/src/components/guide/world/hubHand.ts
new file mode 100644
index 00000000..c13fb062
--- /dev/null
+++ b/web/src/components/guide/world/hubHand.ts
@@ -0,0 +1,122 @@
+import type { DeviceSim } from "@/lib/guide/deviceSim";
+import { knobIsTurned } from "../hubKnob";
+import { useGuideStore } from "../store";
+import { makeIsDrawing, makeIsShown } from "./hubMake";
+
+// The hub is a poster, and the panel on it answers the hand: a mouse over the
+// panel steers Origin a little, as two knobs would โ across the panel is K1
+// (the hue), up it is K2 (the speed) โ and K1 and K2 are seen to turn for it.
+// The panel's middle is where the board was found; the further from it, the
+// further the knobs are turned, a click at a time. Off the panel they turn
+// back the same way. And because the page's accent is the panel's colour
+// (ui/panelTint.ts), the whole hub leans with the hand.
+//
+// The board is the same one in every guide (store.ts getSim), so what the
+// hand turned is counted here and given back, exactly as the Play answer's
+// K1 is (hubKnob.ts) โ and at once, before anything else takes the board:
+// a guide pointed at or chosen, the knobs taken in hand, the page left
+// (world/HubAnswers calls handBackNow from the store's own update). It does
+// nothing while any of that is going on, so the three answers play on a
+// board that is as the hub found it.
+//
+// stage/StageHand.tsx calls handSteer every frame with where the pointer is on
+// the panel; the arithmetic is here, free of three.js, so it can be tested.
+
+/** The knobs the hand turns: K1 across the panel, K2 up it. */
+const KNOBS = [0, 1] as const;
+/** Clicks at the panel's edge: a fifth of the hue's wheel either way; the speed from a crawl to nearly twice. */
+const REACH = [9, 7] as const;
+/** A click of each knob at most this often on the way out, and on the way home, ms. */
+const OUT_MS = 34;
+const HOME_MS = 20;
+
+/** The clicks the hand has turned and not yet turned back, per knob. */
+const applied = [0, 0];
+const since = [0, 0];
+/** K1 was at Origin's own start when the hand began (the Play answer asks the same: hubKnob.ts). */
+let fromStart = false;
+
+const turned = () => applied[0] !== 0 || applied[1] !== 0;
+
+/** The hand has the pattern turned from where the hub found it. */
+export function handIsOn(): boolean {
+ return turned();
+}
+
+/** The board is the hub's to steer: Origin running, nothing pointed at, nobody on the knobs. */
+function free(sim: DeviceSim): boolean {
+ const s = useGuideStore.getState();
+ if (s.page !== "hub" || s.preview !== null || s.leaving !== null || s.handsOn) return false;
+ // The Play answer's K1 is still on its way home, or Make's pattern is on the panel.
+ if (knobIsTurned() || makeIsShown() || makeIsDrawing()) return false;
+ const snap = sim.snapshot();
+ return snap.mode === "run" && snap.pack === "origin";
+}
+
+/**
+ * Home. Sums of clicks leave the hue a hair off (hubKnob.ts land), so from
+ * Origin's own start it ends as the device would: a click of K1. Not once
+ * the reader has the knobs โ a press of K1 is theirs then.
+ */
+function land(sim: DeviceSim) {
+ applied[0] = applied[1] = 0;
+ since[0] = since[1] = 0;
+ if (fromStart && !useGuideStore.getState().handsOn) {
+ sim.press(0);
+ sim.release(0);
+ }
+}
+
+/**
+ * A frame of the hand: `at` is the pointer on the panel โ u across it, โ1 at
+ * its left edge โฆ 1 at its right; v up it, โ1 at its foot โฆ 1 at its top โ
+ * or null when the pointer is anywhere else. One click a knob at a time.
+ */
+export function handSteer(sim: DeviceSim, at: { u: number; v: number } | null, dtMs: number) {
+ if (!at && !turned()) return;
+ const ok = free(sim);
+ if (!ok && !turned()) return;
+ // A knob only turns a pattern that is running: the way home waits for it.
+ if (!ok && sim.snapshot().mode !== "run") return;
+ for (let i = 0; i < 2; i++) {
+ const reach = REACH[i];
+ const want = ok && at ? Math.max(-reach, Math.min(reach, Math.round((i === 0 ? at.u : at.v) * reach))) : 0;
+ if (want === applied[i]) {
+ since[i] = 0;
+ continue;
+ }
+ since[i] += dtMs;
+ if (since[i] < (want === 0 ? HOME_MS : OUT_MS)) continue;
+ since[i] = 0;
+ if (!turned()) {
+ const k1 = sim.knobReadout(0);
+ fromStart = k1.value === k1.min;
+ }
+ const step = Math.sign(want - applied[i]);
+ sim.turn(KNOBS[i], step);
+ applied[i] += step;
+ if (!turned()) land(sim);
+ }
+}
+
+/**
+ * Everything the hand turned, back at once: before the board is anyone
+ * else's. With `frame`, the turn reaches the pattern here and now โ whatever
+ * the board is told next (a page that opens dark).
+ */
+export function handBackNow(sim: DeviceSim, frame = true) {
+ if (!turned()) return;
+ const handsOn = useGuideStore.getState().handsOn;
+ if (sim.snapshot().mode !== "run") {
+ // A screen the reader opened: the knobs are that screen's now, and the count is let go.
+ if (handsOn) {
+ applied[0] = applied[1] = 0;
+ return;
+ }
+ sim.setMode("run");
+ }
+ for (let i = 0; i < 2; i++) if (applied[i]) sim.turn(KNOBS[i], -applied[i]);
+ land(sim);
+ // (Not on top of the reader's own press: the next frame takes both.)
+ if (frame && !handsOn) sim.tick(0);
+}
diff --git a/web/src/components/guide/world/hubMake.ts b/web/src/components/guide/world/hubMake.ts
new file mode 100644
index 00000000..bc85da85
--- /dev/null
+++ b/web/src/components/guide/world/hubMake.ts
@@ -0,0 +1,104 @@
+import type { DeviceSim } from "@/lib/guide/deviceSim";
+import { PANEL_H, PANEL_W } from "@/lib/guide/panelScreens";
+
+// The hub's Make answer (HubAnswers): while Make is pointed at, the pattern on
+// the panel is made again and again โ someone's own pattern drawn in over the
+// last, a row at a time from the top, then the next โ and when the reader
+// points away Origin is drawn back the same way. The patterns are community
+// ones from the Basics pack, pictures where Origin is tiles.
+//
+// The drawing-in is the page's, not the firmware's: a board switches pattern
+// at once. It is done over the simulator's frame (deviceSim setFrameFilter),
+// and only while a redraw is running.
+//
+// The board is the same one in every guide (store.ts getSim), so what this
+// changes โ the pack, the pattern โ it puts back: makeRestore. Origin's own
+// knob values are the board's to keep (it remembers them per pattern), so the
+// hue the reader left Origin on is the hue it comes back with.
+
+/** What the panel is remade into, in turn. */
+export const MAKE_PATTERNS = ["midsummer_sea", "chromatic_vortex", "lissajous_weave", "firefly_hollow"] as const;
+
+/** How long a pattern takes to be drawn in, and Origin to be drawn back, ms. */
+export const DRAW_MS = 640;
+export const RESTORE_MS = 460;
+
+/** The colour of the row being drawn: the guide's LED orange, bright. */
+const HEAD = [255, 150, 96] as const;
+
+type Redraw = { old: Uint8ClampedArray; at: number; ms: number };
+
+let redraw: Redraw | null = null;
+/** The panel is showing a pattern this answer put there. */
+let made = false;
+let next = 0;
+
+/** The clock the redraw runs on; tests set it. */
+export const makeClock = { now: (): number => performance.now() };
+
+const ease = (x: number) => {
+ const c = Math.min(1, Math.max(0, x));
+ return c * c * (3 - 2 * c);
+};
+
+/**
+ * Over the frame: what has not been drawn yet is still the old picture, and
+ * the row being drawn is lit. The panel stands on its end โ the frame's x
+ * runs up the device, its last column the top row (panelScreens.ts) โ so the
+ * drawing goes down the frame's x.
+ */
+function filter(frame: Uint8ClampedArray) {
+ const r = redraw;
+ if (!r) return;
+ const u = (makeClock.now() - r.at) / r.ms;
+ if (u >= 1) {
+ redraw = null;
+ return;
+ }
+ // Columns from `edge` up are the new pattern; below it, the old one.
+ const edge = Math.round(PANEL_W * (1 - ease(u)));
+ for (let y = 0; y < PANEL_H; y++) {
+ const row = y * PANEL_W * 4;
+ frame.set(r.old.subarray(row, row + edge * 4), row);
+ if (edge > 0 && edge < PANEL_W) {
+ const i = row + edge * 4;
+ frame[i] = HEAD[0];
+ frame[i + 1] = HEAD[1];
+ frame[i + 2] = HEAD[2];
+ }
+ }
+}
+
+function begin(sim: DeviceSim, ms: number) {
+ redraw = { old: sim.frame.slice(), at: makeClock.now(), ms };
+ sim.setFrameFilter(filter);
+}
+
+/** The panel is showing one of the answer's patterns, or still drawing Origin back. */
+export function makeIsShown(): boolean {
+ return made;
+}
+
+/** A redraw is on its way down the panel. */
+export function makeIsDrawing(): boolean {
+ return redraw !== null && makeClock.now() - redraw.at < redraw.ms;
+}
+
+/** The answer: the next pattern, drawn in over what is there. */
+export function makeNext(sim: DeviceSim) {
+ begin(sim, DRAW_MS);
+ sim.setPack("basics");
+ sim.showPattern(MAKE_PATTERNS[next % MAKE_PATTERNS.length]);
+ next++;
+ made = true;
+}
+
+/** Pointing away: Origin drawn back, and the board's pack as it was. Nothing to do if the answer never showed. */
+export function makeRestore(sim: DeviceSim) {
+ if (!made) return;
+ made = false;
+ next = 0;
+ begin(sim, RESTORE_MS);
+ sim.showPattern("origin");
+ sim.setPack("origin");
+}
diff --git a/web/src/components/guide/world/usePage.ts b/web/src/components/guide/world/usePage.ts
new file mode 100644
index 00000000..7df3a573
--- /dev/null
+++ b/web/src/components/guide/world/usePage.ts
@@ -0,0 +1,23 @@
+"use client";
+
+import { useLayoutEffect } from "react";
+import { useDocumentLang } from "../darkDocument";
+import { useGuideStore, type GuideLang, type GuideScreen } from "../store";
+
+/**
+ * How a page of the guide says it is the one on screen. Every page under
+ * /guide calls this once, from its root component: the hub (GuideHub) and
+ * the three guides (GuideExperience).
+ *
+ * The stage is not the page's: it is mounted above the pages and stays up
+ * between them (world/GuideWorld). This tells it whose script to play and in
+ * which language (store.enterPage) โ before the browser paints the page, so
+ * the stage never plays the last page's script under the new page's words โ
+ * and tells the document its language.
+ */
+export function useGuidePage(page: GuideScreen, lang: GuideLang) {
+ useLayoutEffect(() => {
+ useGuideStore.getState().enterPage(page, lang);
+ }, [page, lang]);
+ useDocumentLang(lang);
+}
diff --git a/web/src/components/guide/world/world.test.tsx b/web/src/components/guide/world/world.test.tsx
new file mode 100644
index 00000000..b7631246
--- /dev/null
+++ b/web/src/components/guide/world/world.test.tsx
@@ -0,0 +1,550 @@
+import { act, render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { DeviceSim } from "@/lib/guide/deviceSim";
+import { PANEL_H, PANEL_W } from "@/lib/guide/panelScreens";
+import { knobIsTurned, turnBackNow, turnOn } from "../hubKnob";
+import { GUIDE_ORDER, pagePath, placeAnchor, screenAt } from "../pages";
+import { at, OPENING_GONE, OPENING_UNSEEN } from "../stage/build/beats";
+import { EXPLODE, EXPLODE_PARTS, explodeWanted, partAmount, partOffset } from "../stage/explodeParts";
+import { getSim, useGuideStore, type GuideScreen } from "../store";
+import { buildClock } from "../timing";
+import { AWAY_SCALE, awayFraming, hubFraming } from "./framing";
+import HubAnswers from "./HubAnswers";
+import { DRAW_MS, MAKE_PATTERNS, RESTORE_MS, makeClock, makeIsDrawing, makeIsShown, makeNext, makeRestore } from "./hubMake";
+
+// The guide is one world: one stage under the hub and the three guides. These
+// are the rules that hold it together between two pages โ which page the
+// stage is playing, what the hub's answers do to the board and how they are
+// put back, how the device is framed on each page, and how it comes apart.
+
+const FRAME = 1 / 60;
+const SCREENS: GuideScreen[] = ["hub", ...GUIDE_ORDER];
+
+function freshStore() {
+ buildClock.t = -1;
+ useGuideStore.setState({
+ page: "play",
+ lang: "en",
+ entered: false,
+ preview: null,
+ leaving: null,
+ hubTop: 0,
+ buildLive: false,
+ cut: 0,
+ scene: "opening",
+ progress: 0,
+ step: 0,
+ cardIn: true,
+ handsOn: false,
+ flasher: null,
+ });
+}
+
+describe("which page the stage plays", () => {
+ beforeEach(freshStore);
+
+ it("waits for a page to say which one it is", () => {
+ expect(useGuideStore.getState().entered).toBe(false);
+ useGuideStore.getState().enterPage("hub", "ko");
+ expect(useGuideStore.getState()).toMatchObject({ entered: true, page: "hub", lang: "ko", scene: "opening", step: 0 });
+ });
+
+ it("starts another page's script from its top", () => {
+ const s = useGuideStore.getState();
+ s.enterPage("play", "en");
+ s.setScroll("knobs", 0.4, 3);
+ s.setHandsOn(true);
+ s.enterPage("build", "en");
+ expect(useGuideStore.getState()).toMatchObject({ page: "build", scene: "opening", step: 0, handsOn: false });
+ });
+
+ it("carries on where it is when the same page comes back in the other language", () => {
+ const s = useGuideStore.getState();
+ s.enterPage("play", "en");
+ s.setScroll("knobs", 0.4, 3);
+ s.leaveFor("play");
+ s.enterPage("play", "ko");
+ expect(useGuideStore.getState()).toMatchObject({ page: "play", lang: "ko", scene: "knobs", step: 3, leaving: null });
+ });
+
+ it("answers a guide only on the hub, and holds the chosen one's answer until the guide arrives", () => {
+ const s = useGuideStore.getState();
+ s.enterPage("play", "en");
+ s.setPreview("build");
+ expect(useGuideStore.getState().preview).toBeNull();
+
+ s.enterPage("hub", "en");
+ s.setPreview("play");
+ expect(useGuideStore.getState().preview).toBe("play");
+ // Chosen with a tap or a key, nothing pointed at: the choice is the answer.
+ s.setPreview(null);
+ s.leaveFor("build");
+ expect(useGuideStore.getState()).toMatchObject({ leaving: "build", preview: "build" });
+ // The pointer leaving the link on its way out changes nothing now.
+ s.setPreview(null);
+ s.setPreview("make");
+ expect(useGuideStore.getState().preview).toBe("build");
+ // The guide arrives: nothing is pointed at, nothing is being left.
+ s.enterPage("build", "en");
+ expect(useGuideStore.getState()).toMatchObject({ page: "build", preview: null, leaving: null });
+ });
+
+ it("keeps the hub's answer as it is for the hub's own language switch, and gives the words back if no page comes", () => {
+ const s = useGuideStore.getState();
+ s.enterPage("hub", "en");
+ s.setPreview("make");
+ s.leaveFor("hub");
+ expect(useGuideStore.getState()).toMatchObject({ leaving: "hub", preview: "make" });
+ s.leaveFor(null);
+ expect(useGuideStore.getState().leaving).toBeNull();
+ });
+
+ it("keeps the Build stage on after its guide is left only while it is still showing the build", () => {
+ const s = useGuideStore.getState();
+ s.enterPage("build", "en");
+ expect(useGuideStore.getState().buildLive).toBe(true);
+ // Left before the stage ever drew: nothing to run back.
+ s.enterPage("hub", "en");
+ expect(useGuideStore.getState().buildLive).toBe(false);
+
+ s.enterPage("build", "en");
+ buildClock.t = 11.4;
+ s.enterPage("hub", "en");
+ expect(useGuideStore.getState().buildLive).toBe(true);
+ // It takes itself off once the device is whole.
+ s.setBuildLive(false);
+ expect(useGuideStore.getState().buildLive).toBe(false);
+ buildClock.t = -1;
+ });
+
+ it("counts the cuts it is asked for", () => {
+ const before = useGuideStore.getState().cut;
+ useGuideStore.getState().requestCut();
+ useGuideStore.getState().requestCut();
+ expect(useGuideStore.getState().cut).toBe(before + 2);
+ });
+});
+
+describe("the guide's addresses", () => {
+ it("reads every page back off its address, in both languages", () => {
+ for (const page of SCREENS) {
+ for (const lang of ["en", "ko"] as const) {
+ expect(screenAt(pagePath(page, lang))).toEqual({ page, lang });
+ expect(screenAt(pagePath(page, lang) + "/")).toEqual({ page, lang });
+ }
+ }
+ });
+
+ it("knows what is not the guide", () => {
+ expect(screenAt("/")).toBeNull();
+ expect(screenAt("/guide/flash")).toBeNull();
+ expect(screenAt("/pattern-lab")).toBeNull();
+ });
+
+ it("says where the reader is as an anchor the other language's page has too", () => {
+ expect(placeAnchor("opening", 0, true)).toBe("");
+ expect(placeAnchor("flash", 2, true)).toBe("#flash-3");
+ // A chapter's title, its first card not on screen yet.
+ expect(placeAnchor("knobs", 0, false)).toBe("#knobs");
+ expect(placeAnchor("next", 0, true)).toBe("#next");
+ });
+});
+
+describe("how the device is framed", () => {
+ it("stands it above the hub's choices, where the hub's own canvas used to", () => {
+ // The old canvas was a box 99 โ top/3 from the top and top ร 1.667 โ 213
+ // tall, and kept 64 px free above and 32 px below.
+ const { free, scale } = hubFraming(1440, 900, 600, false);
+ const boxTop = 99 - 600 / 3;
+ const boxH = 600 * 1.667 - 213;
+ expect(free).toEqual({ l: 24, r: 1416, t: boxTop + 64, b: boxTop + boxH - 32 });
+ // The same size on screen: the camera further back by the window's height over the box's.
+ expect(scale).toBeCloseTo(900 / boxH, 9);
+ // Its middle is halfway down to the choices, a touch lower.
+ expect((free.t + free.b) / 2).toBeCloseTo(600 / 2 + 8.5, 0);
+ expect((free.l + free.r) / 2).toBe(720);
+ });
+
+ it("keeps it above the choices on a phone, and never in less than 36% of the height", () => {
+ expect(hubFraming(390, 844, 430, true)).toEqual({ free: { l: 12, r: 378, t: 56, b: 416 }, scale: 1 });
+ // Choices that start very high (a short phone on its side): the floor of 36%.
+ expect(hubFraming(700, 360, 60, true).free.b).toBeCloseTo(360 * 0.36, 9);
+ });
+
+ it("frames it somewhere sensible before the hub has been measured", () => {
+ const { free, scale } = hubFraming(1440, 900, 0, false);
+ expect(free.b).toBeGreaterThan(free.t + 200);
+ expect(scale).toBeGreaterThan(1);
+ expect(scale).toBeLessThan(1.6);
+ });
+
+ it("stands it well back for Make, in the middle of the room", () => {
+ const { free, scale } = awayFraming(1440, 900);
+ expect(scale).toBe(AWAY_SCALE);
+ expect(scale).toBeGreaterThan(2);
+ expect((free.l + free.r) / 2).toBe(720);
+ });
+});
+
+describe("the device coming apart", () => {
+ beforeEach(freshStore);
+
+ it("is whole at 0 and fully apart at 1, every part", () => {
+ const o = { x: 0, y: 0, z: 0 };
+ for (const part of EXPLODE_PARTS) {
+ expect(partAmount(part, 0)).toBe(0);
+ expect(partAmount(part, 1)).toBe(1);
+ expect(partOffset(part, 0, o)).toEqual({ x: 0, y: 0, z: 0 });
+ const [x, y, z] = EXPLODE[part].offset;
+ expect(partOffset(part, 1, o)).toEqual({ x, y, z });
+ }
+ });
+
+ it("moves each part one way only, never back on itself", () => {
+ for (const part of EXPLODE_PARTS) {
+ let last = 0;
+ for (let i = 0; i <= 100; i++) {
+ const a = partAmount(part, i / 100);
+ expect(a).toBeGreaterThanOrEqual(last);
+ expect(a).toBeLessThanOrEqual(1);
+ last = a;
+ }
+ }
+ });
+
+ it("takes each part along the way it goes on", () => {
+ const at = (part: (typeof EXPLODE_PARTS)[number]) => EXPLODE[part].offset;
+ // From the front: the knobs onto their shafts, the panel into the frame.
+ for (const part of ["knobs", "panel"] as const) {
+ expect(at(part)[0]).toBe(0);
+ expect(at(part)[1]).toBe(0);
+ expect(at(part)[2]).toBeGreaterThan(0);
+ }
+ // From behind, in the order they go in: the board, the DevKit onto it, the back over both.
+ for (const part of ["board", "devkit", "backPlate"] as const) {
+ expect(at(part)[0]).toBe(0);
+ expect(at(part)[1]).toBe(0);
+ expect(at(part)[2]).toBeLessThan(0);
+ }
+ expect(at("devkit")[2]).toBeLessThan(at("board")[2]);
+ expect(at("backPlate")[2]).toBeLessThan(at("devkit")[2]);
+ // The two covers slide, out of the case's knob side; the back cover goes with the back.
+ expect(at("slider")[0]).toBeGreaterThan(0);
+ expect(at("lid")[0]).toBeGreaterThan(0);
+ expect(at("slider")[2]).toBe(at("backPlate")[2]);
+ // Nothing leaves the bench's height.
+ for (const part of EXPLODE_PARTS) expect(at(part)[1]).toBe(0);
+ });
+
+ it("opens from the outside in, and closes from the inside out", () => {
+ // Early on the way out the covers and knobs lead and the board has not started.
+ expect(partAmount("knobs", 0.2)).toBeGreaterThan(0);
+ expect(partAmount("slider", 0.2)).toBeGreaterThan(0);
+ expect(partAmount("board", 0.2)).toBe(0);
+ // Near home again, the board is seated while the back cover is still off โ
+ // which is what keeps the panel dark until the device is whole (KitFx).
+ expect(partAmount("board", 0.1)).toBe(0);
+ expect(partAmount("slider", 0.1)).toBeGreaterThan(0);
+ });
+
+ it("is asked for by the hub with Build pointed at, and not while the Build stage is still showing the build", () => {
+ const s = useGuideStore.getState();
+ s.enterPage("hub", "en");
+ expect(explodeWanted()).toBe(false);
+ s.setPreview("play");
+ expect(explodeWanted()).toBe(false);
+ s.setPreview("build");
+ expect(explodeWanted()).toBe(true);
+ // The Build stage is still winding the build back on this canvas.
+ buildClock.t = 3.2;
+ expect(explodeWanted()).toBe(false);
+ // Back at its opening it draws the device apart as well as whole.
+ buildClock.t = 0.4;
+ expect(explodeWanted()).toBe(true);
+ buildClock.t = -1;
+ });
+
+ it("stays apart when Build is chosen, through the guide's opening, until the reader scrolls into the build", () => {
+ // Pointing at Build took the device apart; choosing it must not put it
+ // back together (it did: Build opened on a whole, dark device).
+ const s = useGuideStore.getState();
+ s.enterPage("hub", "en");
+ s.setPreview("build");
+ s.leaveFor("build");
+ expect(explodeWanted()).toBe(true);
+ s.enterPage("build", "en");
+ expect(explodeWanted()).toBe(true);
+ // The Build stage taking the device over changes nothing.
+ buildClock.t = 0.5;
+ expect(explodeWanted()).toBe(true);
+ // Into the first chapter: the camera is the bench's (the parts go where they hang: Explode).
+ s.setScroll("gather", 0, 0);
+ expect(explodeWanted()).toBe(false);
+ // Back up at the top, and at the top of Build opened cold.
+ s.setScroll("opening", 0, 0);
+ expect(explodeWanted()).toBe(true);
+ buildClock.t = -1;
+ expect(explodeWanted()).toBe(true);
+ // The other guides open on a whole device.
+ s.enterPage("play", "en");
+ expect(explodeWanted()).toBe(false);
+ });
+
+ it("keeps the opening's device on the first sixth of the build's first beat only", () => {
+ expect(OPENING_GONE).toBeGreaterThan(at("gather-1"));
+ expect(OPENING_GONE).toBeLessThan(at("gather-1", 0.24));
+ // Put apart again, unseen, only while nothing that comes apart is on stage.
+ expect(OPENING_UNSEEN).toBeGreaterThan(OPENING_GONE);
+ expect(OPENING_UNSEEN).toBeLessThanOrEqual(at("print-4"));
+ });
+});
+
+/** The share of the frame's columns (down the device, from its top) that match `other` exactly. */
+function sameColumns(a: Uint8ClampedArray, b: Uint8ClampedArray): boolean[] {
+ const out: boolean[] = [];
+ for (let x = 0; x < PANEL_W; x++) {
+ let same = true;
+ for (let y = 0; y < PANEL_H && same; y++) {
+ const i = (y * PANEL_W + x) * 4;
+ same = a[i] === b[i] && a[i + 1] === b[i + 1] && a[i + 2] === b[i + 2];
+ }
+ out.push(same);
+ }
+ return out;
+}
+
+describe("the hub's Make answer", () => {
+ let sim: DeviceSim;
+ let now = 0;
+ beforeEach(() => {
+ freshStore();
+ now = 1000;
+ makeClock.now = () => now;
+ sim = new DeviceSim();
+ sim.tick(FRAME);
+ });
+ afterEach(() => {
+ makeRestore(sim);
+ turnBackNow(sim);
+ makeClock.now = () => performance.now();
+ });
+
+ it("has every one of its patterns on a board with the Basics pack", () => {
+ sim.setPack("basics");
+ for (const slug of MAKE_PATTERNS) {
+ sim.showPattern(slug);
+ expect(sim.consoleState().patternSlug, slug).toBe(slug);
+ }
+ });
+
+ it("shows someone's pattern, then the next, and puts Origin and its pack back", () => {
+ expect(makeIsShown()).toBe(false);
+ makeNext(sim);
+ expect(makeIsShown()).toBe(true);
+ expect(sim.consoleState().patternSlug).toBe(MAKE_PATTERNS[0]);
+ expect(sim.snapshot().pack).toBe("basics");
+ makeNext(sim);
+ expect(sim.consoleState().patternSlug).toBe(MAKE_PATTERNS[1]);
+
+ makeRestore(sim);
+ expect(makeIsShown()).toBe(false);
+ expect(sim.consoleState().patternSlug).toBe("origin");
+ expect(sim.snapshot().pack).toBe("origin");
+ // And starts from its first pattern the next time.
+ makeNext(sim);
+ expect(sim.consoleState().patternSlug).toBe(MAKE_PATTERNS[0]);
+ });
+
+ it("does nothing to a board it never changed", () => {
+ sim.setPack("basics");
+ sim.showPattern("wave_saw");
+ makeRestore(sim);
+ expect(sim.consoleState().patternSlug).toBe("wave_saw");
+ expect(sim.snapshot().pack).toBe("basics");
+ });
+
+ it("draws the new pattern in from the top of the device, over the old one", () => {
+ const origin = sim.frame.slice();
+ makeNext(sim);
+ // Halfway through: the top half of the device (the frame's last columns) is new, the rest still Origin.
+ now += DRAW_MS / 2;
+ sim.tick(0);
+ expect(makeIsDrawing()).toBe(true);
+ const mid = sameColumns(sim.frame, origin);
+ expect(mid.slice(0, PANEL_W / 2 - 2).every(Boolean)).toBe(true);
+ expect(mid.slice(PANEL_W / 2 + 2).some((same) => !same)).toBe(true);
+ // Done: nothing of Origin is left on the panel.
+ now += DRAW_MS;
+ sim.tick(0);
+ expect(makeIsDrawing()).toBe(false);
+ const done = sim.frame.slice();
+ sim.tick(0);
+ expect(sameColumns(sim.frame, done).every(Boolean)).toBe(true);
+ expect(sameColumns(done, origin).every(Boolean)).toBe(false);
+ });
+
+ it("never draws over a panel that is off", () => {
+ makeNext(sim);
+ sim.setMode("off");
+ now += DRAW_MS / 2;
+ sim.tick(FRAME);
+ for (let i = 0; i < sim.frame.length; i += 4) expect(sim.frame[i] + sim.frame[i + 1] + sim.frame[i + 2]).toBe(0);
+ });
+
+ it("leaves Origin's hue where it was", () => {
+ sim.turn(0, 7);
+ sim.tick(FRAME);
+ const hue = sim.knobReadout(0).value;
+ makeNext(sim);
+ now += DRAW_MS * 2;
+ sim.tick(FRAME);
+ makeRestore(sim);
+ now += RESTORE_MS * 2;
+ sim.tick(FRAME);
+ expect(sim.knobReadout(0).value).toBe(hue);
+ });
+});
+
+describe("the hub's answers, between pages", () => {
+ const sim = getSim();
+ beforeEach(() => {
+ // Not requestAnimationFrame: the test setup pins its own.
+ vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "performance", "Date"] });
+ Object.defineProperty(window, "matchMedia", {
+ configurable: true,
+ value: (query: string) => ({ matches: false, media: query, addEventListener() {}, removeEventListener() {} }),
+ });
+ freshStore();
+ sim.setPack("origin");
+ sim.setMode("run");
+ sim.tick(FRAME);
+ });
+ afterEach(() => {
+ makeRestore(sim);
+ turnBackNow(sim);
+ vi.useRealTimers();
+ });
+
+ /** Timers and the board's frames, as on the stage. */
+ function run(ms: number) {
+ for (let t = 0; t < ms; t += 16) {
+ act(() => {
+ vi.advanceTimersByTime(16);
+ });
+ sim.tick(FRAME);
+ }
+ }
+
+ it("turns K1 while Play is pointed at, and turns it back when the reader points away", () => {
+ render(
);
+ act(() => useGuideStore.getState().enterPage("hub", "en"));
+ act(() => useGuideStore.getState().setPreview("play"));
+ run(1000);
+ expect(knobIsTurned()).toBe(true);
+ expect(sim.knobReadout(0).value).toBeGreaterThan(0);
+ act(() => useGuideStore.getState().setPreview(null));
+ run(800);
+ expect(knobIsTurned()).toBe(false);
+ expect(sim.knobReadout(0).value).toBe(0);
+ });
+
+ it("finishes turning K1 back in Play, a click at a time, when Play is chosen", () => {
+ render(
);
+ act(() => useGuideStore.getState().enterPage("hub", "en"));
+ act(() => useGuideStore.getState().setPreview("play"));
+ run(1000);
+ const turnedTo = sim.knobReadout(0).value;
+ act(() => useGuideStore.getState().leaveFor("play"));
+ act(() => useGuideStore.getState().enterPage("play", "en"));
+ // Not at once: the colour comes home in Play's opening.
+ expect(sim.knobReadout(0).value).toBe(turnedTo);
+ run(800);
+ expect(knobIsTurned()).toBe(false);
+ expect(sim.knobReadout(0).value).toBe(0);
+ });
+
+ it("has K1 home before Build's first frame, which is dark", () => {
+ render(
);
+ act(() => useGuideStore.getState().enterPage("hub", "en"));
+ act(() => useGuideStore.getState().setPreview("play"));
+ run(1000);
+ expect(knobIsTurned()).toBe(true);
+ // Straight from Play's answer into Build, no frame in between: inside the store's own update.
+ act(() => {
+ useGuideStore.getState().leaveFor("build");
+ useGuideStore.getState().enterPage("build", "en");
+ expect(knobIsTurned()).toBe(false);
+ expect(sim.knobReadout(0).value).toBe(0);
+ });
+ });
+
+ it("puts Origin back, with its own hue, when the hub is left with Make's pattern on the panel", () => {
+ render(
);
+ act(() => useGuideStore.getState().enterPage("hub", "en"));
+ // K1 turned by Play's answer, then straight on to Make before it has turned back.
+ act(() => useGuideStore.getState().setPreview("play"));
+ run(600);
+ act(() => useGuideStore.getState().setPreview("make"));
+ run(2500);
+ expect(makeIsShown()).toBe(true);
+ expect(sim.snapshot().pack).toBe("basics");
+ act(() => useGuideStore.getState().leaveFor("make"));
+ act(() => useGuideStore.getState().enterPage("make", "en"));
+ expect(makeIsShown()).toBe(false);
+ expect(sim.consoleState().patternSlug).toBe("origin");
+ expect(sim.snapshot().pack).toBe("origin");
+ expect(knobIsTurned()).toBe(false);
+ expect(sim.knobReadout(0).value).toBe(0);
+ });
+
+ it("readies the Build stage once the reader lingers on Build, and keeps it only for Build", () => {
+ render(
);
+ act(() => useGuideStore.getState().enterPage("hub", "en"));
+ // A pointer passing over Build on its way elsewhere readies nothing.
+ act(() => useGuideStore.getState().setPreview("build"));
+ run(300);
+ act(() => useGuideStore.getState().setPreview(null));
+ run(1000);
+ expect(useGuideStore.getState().buildLive).toBe(false);
+ // Lingering does; it stays in standby while the hub is up.
+ act(() => useGuideStore.getState().setPreview("build"));
+ run(1000);
+ expect(useGuideStore.getState().buildLive).toBe(true);
+ act(() => useGuideStore.getState().setPreview(null));
+ run(300);
+ expect(useGuideStore.getState().buildLive).toBe(true);
+ // Chosen: it is the guide's stage now.
+ act(() => useGuideStore.getState().enterPage("build", "en"));
+ expect(useGuideStore.getState().buildLive).toBe(true);
+ // Had the reader gone to Play instead, it is taken off: it never drew anything.
+ act(() => useGuideStore.getState().enterPage("hub", "en"));
+ act(() => useGuideStore.getState().setBuildLive(true));
+ act(() => useGuideStore.getState().enterPage("play", "en"));
+ expect(useGuideStore.getState().buildLive).toBe(false);
+ });
+
+ it("answers nothing under reduced motion", () => {
+ Object.defineProperty(window, "matchMedia", {
+ configurable: true,
+ value: (query: string) => ({ matches: true, media: query, addEventListener() {}, removeEventListener() {} }),
+ });
+ render(
);
+ act(() => useGuideStore.getState().enterPage("hub", "en"));
+ act(() => useGuideStore.getState().setPreview("play"));
+ run(600);
+ expect(knobIsTurned()).toBe(false);
+ act(() => useGuideStore.getState().setPreview("make"));
+ run(600);
+ expect(makeIsShown()).toBe(false);
+ expect(explodeWanted()).toBe(false);
+ });
+
+ // turnOn is the answer's one click; used here so the import is the same one the component makes.
+ it("counts only its own clicks", () => {
+ turnOn(sim);
+ sim.tick(FRAME);
+ expect(knobIsTurned()).toBe(true);
+ turnBackNow(sim);
+ expect(sim.knobReadout(0).value).toBe(0);
+ });
+});
diff --git a/web/src/components/sections/BuildPanel.tsx b/web/src/components/sections/BuildPanel.tsx
index 2fca08b3..fa4471a0 100644
--- a/web/src/components/sections/BuildPanel.tsx
+++ b/web/src/components/sections/BuildPanel.tsx
@@ -1,4 +1,5 @@
import { useEffect, useRef, useState } from 'react';
+import Link from 'next/link';
import { useAppStore, SectionType } from '@/store/useAppStore';
import { SectionContent } from '@/lib/content';
import { captureEvent } from '@/lib/posthogEvents';
@@ -244,30 +245,41 @@ export default function BuildPanel({ content, isActive }: BuildPanelProps) {
Start here
-
captureEvent('build_guide_opened', {
- guide: 'v3.0.0',
+ guide: 'interactive',
surface: 'build_panel',
})}
>
- Build Guide v3.0.0 โ
+ The build guide, in 3D โ
- PLA case, hand-soldered PCB, browser flash. Start to finish in one document.
+ Parts, soldering, case, wiring, first light. Every step on a Patternflow you can turn.
-
+
{/* Name on the left, destination on the right โ the guide card above
is the only solid in this panel, so these stay hairline rows. */}
diff --git a/web/src/components/sections/InsideGlobe/Globe.tsx b/web/src/components/sections/InsideGlobe/Globe.tsx
index f4d5e468..b31da29c 100644
--- a/web/src/components/sections/InsideGlobe/Globe.tsx
+++ b/web/src/components/sections/InsideGlobe/Globe.tsx
@@ -1,9 +1,10 @@
'use client';
-import { useMemo, useRef, useState } from 'react';
-import { Canvas, useFrame } from '@react-three/fiber';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { RefObject } from 'react';
+import { Canvas, useFrame, useThree } from '@react-three/fiber';
import type { ThreeEvent } from '@react-three/fiber';
-import type { Group, InstancedMesh, Mesh } from 'three';
+import type { Group, InstancedMesh, LineSegments, Mesh, MeshBasicMaterial } from 'three';
import {
BufferGeometry,
CanvasTexture,
@@ -14,6 +15,9 @@ import {
} from 'three';
import type { Build } from './builds';
import { builds, latLngToVec3, originOf } from './builds';
+import type { BuildGroup } from './groups';
+import type { FanObstacle } from './groups';
+import { angularDistance, fanAngle, fanChordPx, fanLean, fanRadiusPx, groupBuilds } from './groups';
import landData from './land.json';
const COLORS = {
@@ -21,7 +25,7 @@ const COLORS = {
land: '#ffffff', // pure-white filled continents
outline: '#141414', // bold black coastlines
pin: '#E8552E', // build markers (LED orange)
- activePin: '#141414', // selected marker
+ activePin: '#141414', // the selected marker
web: '#E8552E', // links between builds
};
@@ -203,19 +207,6 @@ function seededRandom(seed: number): () => number {
};
}
-// Angular distance between two lat/lng points (radians), for nearest-neighbour ranking.
-function angularDistance(a: { lat: number; lng: number }, b: { lat: number; lng: number }): number {
- const toRad = Math.PI / 180;
- const lat1 = a.lat * toRad;
- const lat2 = b.lat * toRad;
- const dLat = (b.lat - a.lat) * toRad;
- const dLng = (b.lng - a.lng) * toRad;
- const h =
- Math.sin(dLat / 2) ** 2 +
- Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
- return 2 * Math.atan2(Math.sqrt(h), Math.sqrt(1 - h));
-}
-
// Every link, sampled once as a polyline of ARC_SAMPLES + 1 points. Both the
// drawn line and the dots travelling along it read from the same samples, so a
// dot can never drift off the line it is supposed to be running on. Pure maths
@@ -397,81 +388,537 @@ export interface GlobeProps {
onSelectBuild?: (buildId: string | null) => void;
}
+// --- Pins --------------------------------------------------------------------
+
+// The invisible sphere a pin is hovered and clicked by, in pin radii.
+const HIT_SCALE = 3.6;
+const HOVER_SCALE = 1.3;
+const SELECTED_SCALE = 1.45;
+// How fast a pin settles into a new size, and a group into open or closed
+// (1/seconds). Quick, but with a tail: the pin arrives rather than snaps.
+const PIN_EASE = 16;
+const FAN_EASE = 13;
+
+// A ring pin's own axis before it is turned to face out of the globe.
+const PIN_UP = new Vector3(0, 0, 1);
+
+// Frame-rate independent easing: the share of the remaining distance to cover
+// in a frame of `delta` seconds.
+const easeShare = (rate: number, delta: number) => 1 - Math.exp(-rate * delta);
+
+const smoothstep = (value: number, from: number, to: number) => {
+ const t = Math.min(1, Math.max(0, (value - from) / (to - from)));
+ return t * t * (3 - 2 * t);
+};
+
+// A dot means a Patternflow exists there; a collaboration is an open ring,
+// something that grew out of one; a sale is a diamond, a unit that went out
+// rather than one that was built there. Reads at a glance without a second
+// colour, and survives colour-blindness.
+function PinShape({ kind }: { kind: Build['kind'] }) {
+ if (kind === 'collaboration') {
+ return (null);
+ const eased = useRef({ scale: 1 });
+
+ useFrame((_, delta) => {
+ const body = bodyRef.current;
+ if (!body) return;
+ const now = eased.current;
+ const scale = selected ? SELECTED_SCALE : hovered ? HOVER_SCALE : 1;
+ if (now.scale === scale) return;
+
+ now.scale += (scale - now.scale) * easeShare(PIN_EASE, delta);
+ if (Math.abs(scale - now.scale) < 0.004) now.scale = scale;
+ body.scale.setScalar(now.scale);
+ });
+
+ return (
+
+
+ );
+}
+
+const setCursor = (cursor: string) => {
+ document.body.style.cursor = cursor;
+};
+
+// The pins of an open fan, in canvas pixels: where each one is and how far
+// from it a pointer still counts. They stand in front of whatever else is on
+// the map there, so every other pin asks this before it takes a pointer event
+// - R3F hands events to the nearest hit sphere first, and a neighbour's big
+// hit sphere would otherwise swallow a fanned-out pin sitting over it.
+type FanClaim = { id: string; count: number; xy: Float32Array; hitPx: number };
+
+type PinEvent = ThreeEvent | ThreeEvent;
+
+function fanClaims(claim: FanClaim | null, event: PinEvent): boolean {
+ if (!claim) return false;
+ const { offsetX, offsetY } = event.nativeEvent;
+ for (let i = 0; i < claim.count; i += 1) {
+ if (Math.hypot(offsetX - claim.xy[i * 2], offsetY - claim.xy[i * 2 + 1]) <= claim.hitPx) return true;
+ }
+ return false;
+}
+
+// Hover is a mouse thing. A finger's "hover" arrives with the tap and is
+// taken away with it, which would open a group and shut it in one touch.
+const isMouse = (event: ThreeEvent) => event.nativeEvent.pointerType === 'mouse';
+
function BuildPin({
build,
isSelected,
+ isHovered,
+ fanRef,
+ onHover,
onSelect,
}: {
build: Build;
isSelected: boolean;
+ isHovered: boolean;
+ fanRef: RefObject;
+ onHover: (buildId: string, over: boolean) => void;
onSelect: (buildId: string | null) => void;
}) {
- const meshRef = useRef(null);
- const [hovered, setHovered] = useState(false);
- const position = latLngToVec3(build.location.lat, build.location.lng, PIN_LAYER_RADIUS);
-
- // A collaboration is drawn as an open ring rather than a filled dot: a dot
- // means a Patternflow exists there, a ring means something grew out of one.
- // Reads at a glance without a second colour, and survives colour-blindness.
- // The ring is flat against the surface, so lay its axis along the normal.
+ const { lat, lng } = build.location;
+ const position = useMemo(() => latLngToVec3(lat, lng, PIN_LAYER_RADIUS), [lat, lng]);
+ // A ring is flat against the surface, so lay its axis along the normal.
const quaternion = useMemo(
() => new Quaternion().setFromUnitVectors(PIN_UP, new Vector3(...position).normalize()),
- // eslint-disable-next-line react-hooks/exhaustive-deps
- [position[0], position[1], position[2]],
+ [position],
);
- useFrame(() => {
- if (!meshRef.current) return;
- // No idle pulse! Constant base scale of 1.0, grows to 1.3x on hover, and 1.45x when selected.
- const targetScale = isSelected ? 1.45 : hovered ? 1.3 : 1.0;
- meshRef.current.scale.setScalar(targetScale);
- });
+ // Over and move both: a pointer that came in under an open fan was not
+ // ours to take then, and has to be picked up once it moves off the fan.
+ const over = (event: ThreeEvent) => {
+ if (fanClaims(fanRef.current, event)) return;
+ event.stopPropagation();
+ setCursor('pointer');
+ if (isMouse(event)) onHover(build.id, true);
+ };
return (
{/* Large invisible hit-box for both easy hover and click (3.6x sensitivity) */}
event.stopPropagation()}
- onPointerOver={(event) => {
- event.stopPropagation();
- setHovered(true);
- document.body.style.cursor = 'pointer';
+ onPointerDown={(event) => {
+ if (!fanClaims(fanRef.current, event)) event.stopPropagation();
}}
+ onPointerOver={over}
+ onPointerMove={over}
onPointerOut={() => {
- setHovered(false);
- document.body.style.cursor = '';
+ setCursor('');
+ onHover(build.id, false);
}}
onClick={(event) => {
+ if (fanClaims(fanRef.current, event)) return;
event.stopPropagation();
- if (isSelected) {
- onSelect(null);
- } else {
- onSelect(build.id);
- }
+ onSelect(isSelected ? null : build.id);
}}
>
-
{/* Small, precise visible pin */}
-
- {build.kind === 'collaboration' ? (
-
+
);
}
-// A ring pin's own axis before it is turned to face out of the globe.
-const PIN_UP = new Vector3(0, 0, 1);
+// --- Groups ------------------------------------------------------------------
+//
+// Builds too close to tell apart are drawn as ONE pin that says how many it
+// holds: a dot with a ring around it for each build after the first, so two
+// is a dot in a ring and three a dot in two. On demand it opens into a fan -
+// each build its own pin on an arc above the shared point, tied by a hairline
+// to where it truly is. Nothing is moved to make room: a build keeps its
+// coordinates, and the hairline says the pin is standing off them.
+// (The grouping rule and the fan's proportions are in groups.ts.)
+
+// At rest: the dot is a little smaller than a lone pin, so the whole mark
+// stays compact enough not to run into a neighbour (the UK and France are
+// under four pin radii apart).
+const GROUP_DOT = 0.72;
+const GROUP_RING_FIRST = 1.28; // radius of the first ring, in pin radii
+const GROUP_RING_REACH = 1.9; // ...and of the outermost, when there are several
+const GROUP_RING_STEP = 0.56; // between rings, while that reach allows it
+const GROUP_RING_TUBE = 0.12;
+// Where a build truly is, marked while its pin stands off on the fan.
+const ORIGIN_DOT = 0.3;
+
+function ringRadii(count: number): number[] {
+ const rings = count - 1;
+ if (rings <= 0) return [];
+ const step = rings === 1
+ ? 0
+ : Math.min(GROUP_RING_STEP, (GROUP_RING_REACH - GROUP_RING_FIRST) / (rings - 1));
+ return Array.from({ length: rings }, (_, index) => PIN_RADIUS * (GROUP_RING_FIRST + step * index));
+}
+
+// What the scene knows about the pointer, in canvas pixels. Kept by plain DOM
+// listeners rather than read off R3F's raycasts: an open fan has to know the
+// pointer has left it even when it has left for empty sky.
+type PointerState = { x: number; y: number; inside: boolean; mouse: boolean };
+
+// Another pin on the map, as the fan of an open group has to see it: where it
+// is on the globe and how big its mark is, in world units.
+type Neighbour = { id: string; at: Vector3; radius: number };
+
+// Scratch objects for the per-frame fan layout (one globe on screen).
+const _anchor = new Vector3();
+const _normal = new Vector3();
+const _toCamera = new Vector3();
+const _slot = new Vector3();
+const _inverse = new Quaternion();
+const _obstaclePool: FanObstacle[] = [];
+const _obstacles: FanObstacle[] = [];
+
+function distanceToSegment(px: number, py: number, ax: number, ay: number, bx: number, by: number) {
+ const dx = bx - ax;
+ const dy = by - ay;
+ const lengthSq = dx * dx + dy * dy;
+ const t = lengthSq === 0 ? 0 : Math.min(1, Math.max(0, ((px - ax) * dx + (py - ay) * dy) / lengthSq));
+ return Math.hypot(px - (ax + dx * t), py - (ay + dy * t));
+}
+
+function GroupPin({
+ group,
+ open,
+ watchPointer,
+ selectedBuildId,
+ hoveredId,
+ worldRef,
+ pointer,
+ neighbours,
+ fanRef,
+ reducedMotion,
+ onOpen,
+ onLeave,
+ onHover,
+ onSelect,
+}: {
+ group: BuildGroup;
+ // Open by hover, by a tap, or because one of its builds is the selected one.
+ open: boolean;
+ // Opened by hovering: it shuts again when the pointer leaves the fan.
+ watchPointer: boolean;
+ selectedBuildId: string | null;
+ hoveredId: string | null;
+ worldRef: RefObject;
+ pointer: RefObject;
+ // Every pin on the map, this group's own included.
+ neighbours: Neighbour[];
+ fanRef: RefObject;
+ reducedMotion: boolean;
+ onOpen: (group: BuildGroup, sticky: boolean) => void;
+ onLeave: (group: BuildGroup) => void;
+ onHover: (buildId: string, over: boolean) => void;
+ onSelect: (buildId: string | null) => void;
+}) {
+ const { members, center } = group;
+ const count = members.length;
+
+ const anchor = useMemo(
+ () => new Vector3(...latLngToVec3(center.lat, center.lng, PIN_LAYER_RADIUS)),
+ [center],
+ );
+ const normal = useMemo(() => anchor.clone().normalize(), [anchor]);
+ const surface = useMemo(() => new Quaternion().setFromUnitVectors(PIN_UP, normal), [normal]);
+ // Where each build truly is. The fan leaves from here and returns to here.
+ const homes = useMemo(
+ () => members.map(({ location }) => new Vector3(...latLngToVec3(location.lat, location.lng, PIN_LAYER_RADIUS))),
+ [members],
+ );
+ const rings = useMemo(() => ringRadii(count), [count]);
+ const hairlines = useMemo(() => {
+ const geometry = new BufferGeometry();
+ geometry.setAttribute('position', new Float32BufferAttribute(new Float32Array(count * 6), 3));
+ return geometry;
+ }, [count]);
+
+ const amount = useRef(0); // 0 closed โฆ 1 fanned out
+ // How far the fan is tipped over to keep clear of its neighbours: where it
+ // is heading, and where it has got to.
+ const lean = useRef({ target: 0, now: 0 });
+ const claim = useRef({ id: group.id, count, xy: new Float32Array(count * 2), hitPx: 0 });
+ const restRef = useRef(null);
+ const lineRef = useRef(null);
+ const memberRefs = useRef<(Group | null)[]>([]);
+ const memberHitRefs = useRef<(Mesh | null)[]>([]);
+ const originRefs = useRef<(Mesh | null)[]>([]);
+
+ useFrame((state, delta) => {
+ const world = worldRef.current;
+ const rest = restRef.current;
+ const line = lineRef.current;
+ if (!world || !rest || !line) return;
+
+ // A fan only stands on a point that faces the viewer. As the point nears
+ // the edge of the globe the fan folds back into the one pin, so it can
+ // never end up drawn across the far side.
+ _anchor.copy(anchor).applyQuaternion(world.quaternion);
+ _toCamera.copy(state.camera.position).sub(_anchor).normalize();
+ const facing = _normal.copy(normal).applyQuaternion(world.quaternion).dot(_toCamera);
+ const target = open ? smoothstep(facing, 0.02, 0.2) : 0;
+
+ const before = amount.current;
+ if (before === 0 && target === 0) {
+ // Shut, and staying shut.
+ if (fanRef.current === claim.current) fanRef.current = null;
+ return;
+ }
+ let now = reducedMotion ? target : before + (target - before) * easeShare(FAN_EASE, delta);
+ if (Math.abs(target - now) < 0.003) now = target;
+ amount.current = now;
+
+ // Everything about the fan is measured in pixels and turned back into
+ // world units at the depth of the shared point - so it is the same size
+ // on screen whether the globe is far away or dollied in on a selection.
+ // The camera sits on +z looking at the origin (GlobeScene), so the screen
+ // is the world's xy plane and "towards the viewer" is +z.
+ const pxPerUnit =
+ state.size.height / 2 / ((state.camera.position.z - _anchor.z) * TAN_HALF_VFOV);
+ const pinPx = PIN_RADIUS * pxPerUnit;
+ const radiusPx = fanRadiusPx(count, pinPx);
+ const hitPx = fanChordPx(pinPx) / 2;
+ const radius = radiusPx / pxPerUnit;
+ _inverse.copy(world.quaternion).invert();
+ const ax = state.size.width / 2 + _anchor.x * pxPerUnit;
+ const ay = state.size.height / 2 - _anchor.y * pxPerUnit;
+
+ // Tip the fan over if standing straight up would put a pin on a
+ // neighbour. Only the pins near enough to be in the way are looked at.
+ _obstacles.length = 0;
+ const reach = radiusPx + pinPx * 3;
+ for (const neighbour of neighbours) {
+ if (neighbour.id === group.id) continue;
+ _slot.copy(neighbour.at).applyQuaternion(world.quaternion);
+ const x = (_slot.x - _anchor.x) * pxPerUnit;
+ const y = (_slot.y - _anchor.y) * pxPerUnit;
+ const r = neighbour.radius * pxPerUnit;
+ if (_slot.z < 0 || Math.hypot(x, y) > reach + r) continue;
+ const index = _obstacles.length;
+ const obstacle = _obstaclePool[index] ?? (_obstaclePool[index] = { x: 0, y: 0, r: 0 });
+ obstacle.x = x;
+ obstacle.y = y;
+ obstacle.r = r;
+ _obstacles.push(obstacle);
+ }
+ const tip = lean.current;
+ tip.target = fanLean(count, radiusPx, pinPx, _obstacles, tip.target);
+ // A fan that is only now opening starts out already leaning the right way.
+ tip.now = before === 0 || reducedMotion
+ ? tip.target
+ : tip.now + (tip.target - tip.now) * easeShare(FAN_EASE, delta);
+
+ const positions = line.geometry.attributes.position;
+ const taken = claim.current;
+ for (let i = 0; i < count; i += 1) {
+ const member = memberRefs.current[i];
+ if (!member) continue;
+ const angle = fanAngle(count, i, tip.now);
+ const cos = Math.cos(angle);
+ const sin = Math.sin(angle);
+ taken.xy[i * 2] = ax + cos * radiusPx;
+ taken.xy[i * 2 + 1] = ay - sin * radiusPx;
+ _slot.set(cos * radius, sin * radius, 0).add(_anchor).applyQuaternion(_inverse);
+ member.position.lerpVectors(homes[i], _slot, now);
+ // Upright to the viewer, whichever way the globe is turned.
+ member.quaternion.copy(_inverse);
+ member.scale.setScalar(0.35 + 0.65 * now);
+ member.visible = now > 0;
+ positions.setXYZ(i * 2, homes[i].x, homes[i].y, homes[i].z);
+ positions.setXYZ(i * 2 + 1, member.position.x, member.position.y, member.position.z);
+
+ memberHitRefs.current[i]?.scale.setScalar(hitPx / pxPerUnit / (0.35 + 0.65 * now));
+ originRefs.current[i]?.scale.setScalar(now);
+ }
+ positions.needsUpdate = true;
+ line.visible = now > 0;
+ (line.material as MeshBasicMaterial).opacity = 0.9 * now;
+
+ // The rings draw in to the middle as the pins leave it.
+ rest.scale.setScalar(1 - now);
+ rest.visible = now < 1;
+
+ // Once the pins are most of the way out, they are what a pointer there
+ // means (see FanClaim).
+ taken.hitPx = hitPx;
+ if (open && now > 0.5) fanRef.current = taken;
+ else if (fanRef.current === taken) fanRef.current = null;
+
+ if (!open || !watchPointer) return;
+ // Opened by hovering: stay open while the pointer is on the shared point
+ // or anywhere along a hairline or its pin, and close once it is not.
+ const at = pointer.current;
+ let near = false;
+ if (at.inside) {
+ near = Math.hypot(at.x - ax, at.y - ay) <= pinPx * HIT_SCALE + 3;
+ for (let i = 0; i < count && !near; i += 1) {
+ near = distanceToSegment(at.x, at.y, ax, ay, taken.xy[i * 2], taken.xy[i * 2 + 1]) <= hitPx + 3;
+ }
+ }
+ if (!near) onLeave(group);
+ });
+
+ // A group that leaves the map (the filter changed) takes its claim with it.
+ useEffect(() => {
+ const taken = claim.current;
+ return () => {
+ if (fanRef.current === taken) fanRef.current = null;
+ };
+ }, [fanRef]);
+
+ // Over and move both, as for a lone pin: the pointer may arrive under the
+ // fan of another group and only later be this pin's to take.
+ const over = (event: ThreeEvent) => {
+ if (fanClaims(fanRef.current, event)) return;
+ event.stopPropagation();
+ setCursor('pointer');
+ const world = worldRef.current;
+ // Not through the globe: a group on the far side is opened by a click,
+ // which also brings it round.
+ const towards = world
+ ? _normal.copy(normal).applyQuaternion(world.quaternion).dot(event.ray.direction)
+ : 0;
+ if (isMouse(event) && towards < -0.05) onOpen(group, false);
+ };
+
+ return (
+ <>
+ {/* The one pin, flat against the surface: a dot and its rings. */}
+
+ {
+ if (!fanClaims(fanRef.current, event)) event.stopPropagation();
+ }}
+ onPointerOver={over}
+ onPointerMove={over}
+ onPointerOut={() => setCursor('')}
+ onClick={(event) => {
+ if (fanClaims(fanRef.current, event)) return;
+ event.stopPropagation();
+ onOpen(group, true);
+ }}
+ >
+
+
+
+
+ {rings.map((radius) => (
+
+
+ ))}
+
+
+
+ {/* Where each build truly is, and the hairline out to its pin. */}
+ {members.map((build, index) => (
+ {
+ originRefs.current[index] = node;
+ }}
+ position={homes[index]}
+ scale={0}
+ renderOrder={11}
+ >
+
+ ))}
+
+
+
+ {/* The builds themselves, each a pin like any other once fanned out. */}
+ {members.map((build, index) => {
+ const isSelected = selectedBuildId === build.id;
+ return (
+ {
+ memberRefs.current[index] = node;
+ }}
+ position={homes[index]}
+ visible={false}
+ >
+ {open && (
+ {
+ memberHitRefs.current[index] = node;
+ }}
+ scale={PIN_RADIUS}
+ onPointerDown={(event) => event.stopPropagation()}
+ onPointerOver={(event) => {
+ event.stopPropagation();
+ if (isMouse(event)) onHover(build.id, true);
+ }}
+ onPointerMove={(event) => {
+ event.stopPropagation();
+ setCursor('pointer');
+ }}
+ onPointerOut={() => {
+ setCursor('');
+ onHover(build.id, false);
+ }}
+ onClick={(event) => {
+ event.stopPropagation();
+ onSelect(isSelected ? null : build.id);
+ }}
+ >
+
+ )}
+
+ );
+ })}
+
+ );
+}
const AXIS_Y = new Vector3(0, 1, 0);
const AXIS_X = new Vector3(1, 0, 0);
@@ -483,6 +930,12 @@ const FIT_RADIUS = 1.35; // globe radius including markers
const FIT_FRACTION = 0.7; // share of the limiting dimension to occupy
const FOCUS_DOLLY = 0.62; // zoom-in factor when a build is selected
const DRAG_SPEED = 0.006; // radians per pixel of drag
+const DRIFT_SPEED = 0.18; // radians per second, idle
+
+// The globe leans a degree or two towards the pointer - enough to feel that
+// it has noticed, not enough to move a pin out from under it. Mouse only, and
+// not at all for anyone who has asked for less motion.
+const LEAN = 0.03; // radians, at the edge of the frame
// The globe is a turntable, not a trackball: yaw spins around the world's
// vertical axis and pitch tilts towards the viewer, and there is no third axis
@@ -497,6 +950,7 @@ const MAX_PITCH = 1.31;
// Reusable scratch objects (module-scoped โ a single globe instance).
const _yawQ = new Quaternion();
const _pitchQ = new Quaternion();
+const _leanQ = new Quaternion();
const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
@@ -512,39 +966,163 @@ function headingTo(lat: number, lng: number): { yaw: number; pitch: number } {
return { yaw: Math.atan2(-x, z), pitch: Math.atan2(y, Math.hypot(x, z)) };
}
-function GlobeScene({ entries = builds, selectedBuildId, onSelectBuild }: GlobeProps) {
+// Which group is open without one of its builds being selected: `sticky` when
+// it was tapped or clicked open (it stays until something else is picked),
+// not sticky when the pointer is merely resting on it.
+// `during` is the build that was selected when it was opened (or null): a
+// group opened by hand stays open only for as long as the selection it was
+// opened under stands, so picking another build closes it without an effect.
+type OpenGroup = { id: string; sticky: boolean; during: string | null };
+
+interface SceneProps extends GlobeProps {
+ openGroup: OpenGroup | null;
+ onOpenGroup: (next: OpenGroup | null) => void;
+}
+
+function GlobeScene({
+ entries = builds,
+ selectedBuildId,
+ onSelectBuild,
+ openGroup,
+ onOpenGroup,
+}: SceneProps) {
const web = useMemo(() => webArcs(entries), [entries]);
const collaborations = useMemo(() => collaborationArcs(entries), [entries]);
+ const groups = useMemo(() => groupBuilds(entries), [entries]);
+ // Every pin as an open fan has to see it: where, and how big its mark is.
+ const neighbours = useMemo(
+ () => groups.map(({ id, members, center }) => {
+ const kind = members[0].kind;
+ const reach = members.length > 1
+ ? (ringRadii(members.length).at(-1) ?? 0) / PIN_RADIUS + GROUP_RING_TUBE
+ : kind === 'collaboration' ? 1.77 : kind === 'sold' ? 1.45 : 1;
+ return {
+ id,
+ at: new Vector3(...latLngToVec3(center.lat, center.lng, PIN_LAYER_RADIUS)),
+ radius: PIN_RADIUS * reach,
+ };
+ }),
+ [groups],
+ );
+ const reducedMotion = useMemo(
+ () => window.matchMedia('(prefers-reduced-motion: reduce)').matches,
+ [],
+ );
+ const canvas = useThree((state) => state.gl.domElement);
+
+ const [hoverId, setHoverId] = useState(null);
const worldRef = useRef(null);
const yaw = useRef(0);
const pitch = useRef(INITIAL_PITCH);
+ const drift = useRef(DRIFT_SPEED);
+ const lean = useRef({ x: 0, y: 0 });
+ // Where a group that was tapped open is being brought round to.
+ const focus = useRef<{ yaw: number; pitch: number } | null>(null);
const dragging = useRef(false);
const moved = useRef(0);
const distRef = useRef(5);
+ const pointer = useRef({ x: 0, y: 0, inside: false, mouse: false });
+ const fanRef = useRef(null);
+
+ useEffect(() => {
+ const track = (event: PointerEvent) => {
+ const at = pointer.current;
+ at.x = event.offsetX;
+ at.y = event.offsetY;
+ at.inside = true;
+ at.mouse = event.pointerType === 'mouse';
+ };
+ const leave = () => {
+ pointer.current.inside = false;
+ };
+ canvas.addEventListener('pointermove', track);
+ canvas.addEventListener('pointerdown', track);
+ canvas.addEventListener('pointerleave', leave);
+ canvas.addEventListener('pointercancel', leave);
+ return () => {
+ canvas.removeEventListener('pointermove', track);
+ canvas.removeEventListener('pointerdown', track);
+ canvas.removeEventListener('pointerleave', leave);
+ canvas.removeEventListener('pointercancel', leave);
+ };
+ }, [canvas]);
const selected = selectedBuildId
? entries.find((build) => build.id === selectedBuildId) ?? null
: null;
+ // A selected build holds its own group open - picked from the list or
+ // arrived at by URL, the fan shows which of the builds there it is.
+ const selectedGroup = selected
+ ? groups.find((group) => group.members.length > 1 && group.members.includes(selected)) ?? null
+ : null;
+ // A group opened by hand, with or without a build selected: from a selected
+ // build the pointer can open another group and pick from it in one go. (It
+ // used to be ignored while a build was selected, so the rings would not open.)
+ const heldOpen = openGroup && openGroup.during === (selectedBuildId ?? null)
+ ? groups.find((group) => group.id === openGroup.id) ?? null
+ : null;
+ const isOpen = (id: string) => id === selectedGroup?.id || id === heldOpen?.id;
+ // A hover only counts while the pin it was on is still there to be left:
+ // a pin of a fan that has since closed never reports the pointer leaving,
+ // and the globe would hold still for it for good.
+ const hoveredId = groups.some(({ id, members }) =>
+ (members.length === 1 || isOpen(id)) && members.some((build) => build.id === hoverId))
+ ? hoverId
+ : null;
useFrame((state, delta) => {
const world = worldRef.current;
if (!world) return;
+ if (!heldOpen) focus.current = null;
+ // The globe holds still under a pointer that is on a pin, and while a
+ // group stands open: a fan that slid away as you reached for it would be
+ // no use. It picks its drift back up gradually, the way it would if it
+ // had weight.
+ const held = !!selected || !!heldOpen || !!hoveredId || dragging.current;
+ drift.current += ((held ? 0 : DRIFT_SPEED) - drift.current) * easeShare(held ? 9 : 2.5, delta);
+
if (selected) {
// Ease the picked location around to face the camera.
const target = headingTo(selected.location.lat, selected.location.lng);
yaw.current += wrapAngle(target.yaw - yaw.current) * 0.08;
pitch.current += (target.pitch - pitch.current) * 0.08;
+ } else if (focus.current) {
+ const dYaw = wrapAngle(focus.current.yaw - yaw.current);
+ const dPitch = clamp(focus.current.pitch, -MAX_PITCH, MAX_PITCH) - pitch.current;
+ yaw.current += dYaw * 0.08;
+ pitch.current += dPitch * 0.08;
+ if (Math.abs(dYaw) + Math.abs(dPitch) < 0.002) focus.current = null;
} else if (!dragging.current) {
// Idle drift, carrying on around whatever axis the globe was left
// tilted on โ the way a desk globe keeps turning after a nudge.
- yaw.current += delta * 0.18;
+ yaw.current += delta * drift.current;
}
- // Yaw runs first so it spins the globe about its own (tilted) axis.
- _pitchQ.setFromAxisAngle(AXIS_X, pitch.current);
+ // The lean towards the pointer. It rests at zero whenever a build is
+ // selected, so the selected place still lands dead centre.
+ const at = pointer.current;
+ const leaning = at.inside && at.mouse && !selected && !reducedMotion;
+ const leanX = leaning ? (at.x / state.size.width) * 2 - 1 : 0;
+ const leanY = leaning ? (at.y / state.size.height) * 2 - 1 : 0;
+ const share = easeShare(4, delta);
+ lean.current.x += (clamp(leanX, -1, 1) * LEAN - lean.current.x) * share;
+ lean.current.y += (clamp(leanY, -1, 1) * LEAN - lean.current.y) * share;
+
+ // Yaw runs first so it spins the globe about its own (tilted) axis; the
+ // lean is laid over the top, about the screen's own axes.
+ _pitchQ.setFromAxisAngle(AXIS_X, pitch.current + lean.current.y);
_yawQ.setFromAxisAngle(AXIS_Y, yaw.current);
- world.quaternion.copy(_pitchQ).multiply(_yawQ);
+ _leanQ.setFromAxisAngle(AXIS_Y, lean.current.x);
+ world.quaternion.copy(_leanQ).multiply(_pitchQ).multiply(_yawQ);
+
+ // A group left open that has since been dragged round the back is shut.
+ if (heldOpen && !focus.current) {
+ _normal
+ .set(...latLngToVec3(heldOpen.center.lat, heldOpen.center.lng, 1))
+ .applyQuaternion(world.quaternion);
+ if (_normal.z < 0) onOpenGroup(null);
+ }
// Responsive distance so the globe fills ~70% of the smaller dimension.
const aspect = state.size.width / Math.max(1, state.size.height);
@@ -559,10 +1137,19 @@ function GlobeScene({ entries = builds, selectedBuildId, onSelectBuild }: GlobeP
// Drag to rotate (disabled while a build is focused). A near-still press is
// treated as a click on empty globe and clears the current selection.
const startDrag = (event: ThreeEvent) => {
- if (selected) return;
+ if (selected) {
+ // No turning while a build is in focus. A press on the bare globe lets
+ // the selection go; a press on another pin never gets here (the pin
+ // takes it), so one click goes from build to build.
+ event.stopPropagation();
+ onOpenGroup(null);
+ onSelectBuild?.(null);
+ return;
+ }
event.stopPropagation();
dragging.current = true;
moved.current = 0;
+ focus.current = null;
const onMove = (move: PointerEvent) => {
const dx = move.movementX || 0;
@@ -577,12 +1164,39 @@ function GlobeScene({ entries = builds, selectedBuildId, onSelectBuild }: GlobeP
window.removeEventListener('pointermove', onMove);
window.removeEventListener('pointerup', onUp);
dragging.current = false;
- if (moved.current < 6) onSelectBuild?.(null);
+ if (moved.current < 6) {
+ onOpenGroup(null);
+ onSelectBuild?.(null);
+ }
};
window.addEventListener('pointermove', onMove);
window.addEventListener('pointerup', onUp);
};
+ const hover = (buildId: string, over: boolean) => {
+ setHoverId((current) => (over ? buildId : current === buildId ? null : current));
+ };
+ const select = (buildId: string | null) => {
+ setHoverId(null);
+ onSelectBuild?.(buildId);
+ };
+ const open = (group: BuildGroup, sticky: boolean) => {
+ if (dragging.current) return;
+ if (sticky) {
+ // A tap brings the group round to the middle, where there is room for
+ // its fan - and where a group tapped through the far side can open.
+ // Not while a build is selected: the view stays on that build until
+ // another is picked.
+ if (!selected) focus.current = headingTo(group.center.lat, group.center.lng);
+ } else if (heldOpen?.id === group.id) {
+ return; // already open; a hover never loosens a tapped-open group
+ }
+ onOpenGroup({ id: group.id, sticky, during: selectedBuildId ?? null });
+ };
+ const leave = (group: BuildGroup) => {
+ if (openGroup?.id === group.id && !openGroup.sticky) onOpenGroup(null);
+ };
+
return (
onSelectBuild?.(buildId)}
- />
- ))}
+ {groups.map((group) => {
+ if (group.members.length === 1) {
+ const build = group.members[0];
+ return (
+
@@ -611,6 +1252,19 @@ function GlobeScene({ entries = builds, selectedBuildId, onSelectBuild }: GlobeP
}
export default function Globe(props: GlobeProps) {
+ // Held out here, beside the canvas, because a click that misses everything
+ // in the scene is reported to the canvas and has to close the group too.
+ const [openGroup, setOpenGroup] = useState(null);
+ // A selection made anywhere - a pin, the list, the address bar - takes over
+ // from a group that was merely standing open, so it does not spring back
+ // open when that selection is cleared.
+ const selectedBuildId = props.selectedBuildId ?? null;
+ const [selectionSeen, setSelectionSeen] = useState(selectedBuildId);
+ if (selectionSeen !== selectedBuildId) {
+ setSelectionSeen(selectedBuildId);
+ if (selectedBuildId) setOpenGroup(null);
+ }
+
return (
props.onSelectBuild?.(null)}
+ onPointerMissed={() => {
+ setOpenGroup(null);
+ props.onSelectBuild?.(null);
+ }}
>
-
);
}
diff --git a/web/src/components/sections/InsideGlobe/GlobeViewer.module.css b/web/src/components/sections/InsideGlobe/GlobeViewer.module.css
index f97baa8f..9b098931 100644
--- a/web/src/components/sections/InsideGlobe/GlobeViewer.module.css
+++ b/web/src/components/sections/InsideGlobe/GlobeViewer.module.css
@@ -37,10 +37,15 @@
opacity: 0;
transition: opacity 0.3s ease;
}
+/* Open, it still lets the pointer through to the globe: another pin can be
+ picked straight from a selected one, and a click on bare globe or beside it
+ lets the selection go (Globe.tsx). Only its own controls take the pointer. */
.overlayOpen {
opacity: 1;
+}
+.overlayOpen .thumbs,
+.overlayOpen .links {
pointer-events: auto;
- cursor: pointer;
}
/* Top-center prompt, matching the product preview's hint style. */
diff --git a/web/src/components/sections/InsideGlobe/GlobeViewer.tsx b/web/src/components/sections/InsideGlobe/GlobeViewer.tsx
index 1512b6f2..a3ff4a7d 100644
--- a/web/src/components/sections/InsideGlobe/GlobeViewer.tsx
+++ b/web/src/components/sections/InsideGlobe/GlobeViewer.tsx
@@ -94,9 +94,6 @@ export default function GlobeViewer() {
{
- if (selected) select(null);
- }}
>
{selected && (
<>
diff --git a/web/src/components/sections/InsideGlobe/builds.ts b/web/src/components/sections/InsideGlobe/builds.ts
index 57d5e21e..73e173e7 100644
--- a/web/src/components/sections/InsideGlobe/builds.ts
+++ b/web/src/components/sections/InsideGlobe/builds.ts
@@ -342,6 +342,20 @@ export function originOf(build: Build): Build | undefined {
return origin && origin.id !== build.id ? origin : undefined;
}
+// The country a pin is in, read off the end of its label ("Leeds, UK" โ the
+// United Kingdom). Labels are written for people, so the one country that is
+// spelled two ways is folded here rather than by rewording somebody's pin.
+const COUNTRY_ALIASES: Record
= { UK: 'United Kingdom' };
+
+export function countryOf(build: Build): string {
+ const name = build.location.label.split(',').pop()!.trim();
+ return COUNTRY_ALIASES[name] ?? name;
+}
+
+export function countCountries(entries: Build[]): number {
+ return new Set(entries.map(countryOf)).size;
+}
+
const MONTHS = [
'January', 'February', 'March', 'April', 'May', 'June',
'July', 'August', 'September', 'October', 'November', 'December',
diff --git a/web/src/components/sections/InsideGlobe/groups.test.ts b/web/src/components/sections/InsideGlobe/groups.test.ts
new file mode 100644
index 00000000..eb3431df
--- /dev/null
+++ b/web/src/components/sections/InsideGlobe/groups.test.ts
@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'vitest';
+import { builds, countCountries, countryOf, type Build } from './builds';
+import {
+ angularDistance, fanAngles, fanChordPx, fanLean, fanRadiusPx, groupBuilds, GROUP_ANGLE_DEG,
+} from './groups';
+
+const DEG = Math.PI / 180;
+
+function at(id: string, lat: number, lng: number): Build {
+ return {
+ id,
+ slug: id,
+ kind: 'build',
+ title: id,
+ category: 'builds',
+ location: { lat, lng, label: id },
+ maker: id,
+ date: '2026-01',
+ description: '',
+ };
+}
+
+const idsOf = (groups: ReturnType) => groups.map((group) => group.members.map((build) => build.id));
+
+describe('grouping builds that sit too close to tell apart', () => {
+ it('puts every entry in exactly one group and moves none of them', () => {
+ const before = JSON.stringify(builds);
+ const groups = groupBuilds(builds);
+ const seen = groups.flatMap((group) => group.members.map((build) => build.id)).sort();
+ expect(seen).toEqual(builds.map((build) => build.id).sort());
+ expect(JSON.stringify(builds)).toBe(before);
+ for (const group of groups) {
+ for (const member of group.members) expect(builds).toContain(member);
+ }
+ });
+
+ it('groups two builds on the very same coordinates', () => {
+ const groups = groupBuilds([at('a', 54, -2), at('b', 54, -2), at('far', 10, 100)]);
+ expect(idsOf(groups)).toEqual([['a', 'b'], ['far']]);
+ expect(groups[0].center.lat).toBeCloseTo(54, 6);
+ expect(groups[0].center.lng).toBeCloseTo(-2, 6);
+ });
+
+ it('groups by distance, not by which side of the limit a longitude number falls', () => {
+ // 2.9 degrees apart along the equator, and the same across the date line.
+ expect(idsOf(groupBuilds([at('a', 0, 10), at('b', 0, 12.9)]))).toEqual([['a', 'b']]);
+ expect(idsOf(groupBuilds([at('a', 0, 10), at('b', 0, 13.1)]))).toEqual([['a'], ['b']]);
+ const acrossDateLine = groupBuilds([at('east', 0, 179), at('west', 0, -179)]);
+ expect(idsOf(acrossDateLine)).toEqual([['east', 'west']]);
+ expect(Math.abs(acrossDateLine[0].center.lng)).toBeCloseTo(180, 6);
+ // Near a pole a degree of longitude is next to nothing.
+ expect(idsOf(groupBuilds([at('a', 89, 0), at('b', 89, 90)]))).toEqual([['a', 'b']]);
+ });
+
+ it('does not chain a line of builds into one pin', () => {
+ // Each 2 degrees from the next: neighbours are close, the ends are not.
+ const row = [at('a', 0, 0), at('b', 0, 2), at('c', 0, 4), at('d', 0, 6)];
+ const groups = groupBuilds(row);
+ for (const group of groups) {
+ for (const p of group.members) {
+ for (const q of group.members) {
+ expect(angularDistance(p.location, q.location)).toBeLessThanOrEqual(GROUP_ANGLE_DEG * DEG + 1e-9);
+ }
+ }
+ }
+ expect(idsOf(groups)).toEqual([['a', 'b'], ['c', 'd']]);
+ });
+
+ it('orders a group west to east, and keeps the given order on one spot', () => {
+ const groups = groupBuilds([at('east', 50, 1), at('first', 50, 0), at('west', 50, -1), at('second', 50, 0)]);
+ expect(idsOf(groups)).toEqual([['west', 'first', 'second', 'east']]);
+ });
+
+ it('does not depend on the order the entries arrive in', () => {
+ const forwards = groupBuilds(builds);
+ const backwards = groupBuilds([...builds].reverse());
+ expect(backwards.map((group) => group.id).sort()).toEqual(forwards.map((group) => group.id).sort());
+ });
+
+ it('reads the real map: the UK is three, France two, northern California three', () => {
+ const multi = idsOf(groupBuilds(builds))
+ .filter((ids) => ids.length > 1)
+ .map((ids) => [...ids].sort());
+ expect(multi).toHaveLength(3);
+ expect(multi).toContainEqual(['uk-nath', 'uk-saladman', 'uk-slowrush']);
+ expect(multi).toContainEqual(['france-day', 'paris-v1']);
+ expect(multi).toContainEqual(['california-lopez', 'sf-swartz', 'usa-jon']);
+ });
+
+ it('follows the filter: a group is only the entries on show', () => {
+ const builtOnly = builds.filter((build) => build.category === 'builds');
+ const multi = idsOf(groupBuilds(builtOnly)).filter((ids) => ids.length > 1).map((ids) => [...ids].sort());
+ // France loses its project and California its sale.
+ expect(multi).toContainEqual(['uk-nath', 'uk-saladman', 'uk-slowrush']);
+ expect(multi).toContainEqual(['california-lopez', 'usa-jon']);
+ expect(multi).toHaveLength(2);
+ });
+});
+
+describe('the count beside the list', () => {
+ it('reads a country off the end of a label, and folds the UK into one', () => {
+ expect(countryOf(at('a', 0, 0))).toBe('a');
+ const named = (label: string) => countryOf({ ...at('x', 0, 0), location: { lat: 0, lng: 0, label } });
+ expect(named('Leeds, UK')).toBe('United Kingdom');
+ expect(named('United Kingdom')).toBe('United Kingdom');
+ expect(named('San Francisco, USA')).toBe('USA');
+ expect(countCountries(builds)).toBe(9);
+ });
+});
+
+describe('the fan a group opens into', () => {
+ it('stands above the shared point, first member leftmost, symmetric about straight up', () => {
+ for (const count of [2, 3, 4, 7]) {
+ const angles = fanAngles(count);
+ expect(angles).toHaveLength(count);
+ for (let i = 0; i < count; i += 1) {
+ expect(Math.sin(angles[i])).toBeGreaterThan(0); // never below level
+ expect(angles[i] + angles[count - 1 - i]).toBeCloseTo(Math.PI); // mirror pairs
+ if (i > 0) expect(angles[i]).toBeLessThan(angles[i - 1]); // left to right
+ }
+ }
+ });
+
+ it('keeps neighbouring pins apart on screen however small the pins are drawn', () => {
+ for (const count of [2, 3, 5, 8]) {
+ for (const pinPx of [2, 4.5, 8, 15, 30]) {
+ const radius = fanRadiusPx(count, pinPx);
+ const angles = fanAngles(count);
+ const gap = Math.hypot(
+ radius * (Math.cos(angles[0]) - Math.cos(angles[1])),
+ radius * (Math.sin(angles[0]) - Math.sin(angles[1])),
+ );
+ expect(gap).toBeCloseTo(fanChordPx(pinPx), 6);
+ expect(gap).toBeGreaterThan(29.999); // a fingertip apart
+ expect(gap).toBeGreaterThan(2 * pinPx); // and never overlapping
+ }
+ }
+ });
+
+ it('stands straight up when nothing is in the way', () => {
+ expect(fanLean(3, 32, 8, [])).toBe(0);
+ // A neighbour below the shared point is not in the way of a fan above it.
+ expect(fanLean(3, 32, 8, [{ x: 10, y: -30, r: 10 }])).toBe(0);
+ // ...and a lean it no longer needs is given up.
+ expect(fanLean(2, 32, 8, [{ x: 10, y: -30, r: 10 }], 0.5)).toBe(0);
+ });
+
+ it('tips away from a neighbour a pin would land on, and never below level', () => {
+ const pinPx = 8;
+ for (const count of [2, 3]) {
+ const radius = fanRadiusPx(count, pinPx);
+ // A neighbour sitting exactly where the leftmost pin would go.
+ const [left] = fanAngles(count);
+ const neighbour = { x: Math.cos(left) * radius, y: Math.sin(left) * radius, r: 12 };
+ const lean = fanLean(count, radius, pinPx, [neighbour]);
+ expect(lean).toBeGreaterThan(0); // to the right, away from it
+ for (const angle of fanAngles(count, lean)) {
+ expect(Math.sin(angle)).toBeGreaterThan(0);
+ const gap = Math.hypot(Math.cos(angle) * radius - neighbour.x, Math.sin(angle) * radius - neighbour.y);
+ // Two pins have the room to get clear altogether. Three span too much
+ // of the arc for that, and go as far as staying above level allows.
+ if (count === 2) expect(gap).toBeGreaterThan(pinPx + neighbour.r);
+ else expect(lean).toBeCloseTo((88 - 56) * DEG);
+ }
+ // Mirrored, it tips the other way by the same amount.
+ expect(fanLean(count, radius, pinPx, [{ ...neighbour, x: -neighbour.x }])).toBeCloseTo(-lean);
+ }
+ });
+
+ it('does not rock: a slight overlap is not worth tipping further for', () => {
+ const radius = fanRadiusPx(2, 8);
+ const [left] = fanAngles(2);
+ // Two pixels short of clear: 8 * 1.45 + 10 + 3 = 24.6 needed, 22.6 given.
+ const graze = { x: Math.cos(left) * radius - 22.6, y: Math.sin(left) * radius, r: 10 };
+ expect(fanLean(2, radius, 8, [graze], 0)).toBe(0);
+ });
+});
diff --git a/web/src/components/sections/InsideGlobe/groups.ts b/web/src/components/sections/InsideGlobe/groups.ts
new file mode 100644
index 00000000..29577358
--- /dev/null
+++ b/web/src/components/sections/InsideGlobe/groups.ts
@@ -0,0 +1,230 @@
+import type { Build } from './builds';
+import { latLngToVec3 } from './builds';
+
+// Which pins are too close together to be told apart, and how a set of them
+// opens up. Pure maths over the entries - no three.js, no DOM - so the rules
+// can be tested without a globe.
+//
+// Why this exists: a build whose city is not known sits on its country's
+// centre (see `location` in builds.ts), so two builds in one country can have
+// the very same coordinates, and no amount of zooming separates them. The
+// answer is not to nudge a coordinate - that would claim a place nobody gave
+// us - but to draw the set as one pin that says how many it holds, and to fan
+// it out on demand.
+
+type LatLng = { lat: number; lng: number };
+
+const TO_RAD = Math.PI / 180;
+
+// Angular distance between two lat/lng points, in radians (haversine).
+export function angularDistance(a: LatLng, b: LatLng): number {
+ const lat1 = a.lat * TO_RAD;
+ const lat2 = b.lat * TO_RAD;
+ const dLat = (b.lat - a.lat) * TO_RAD;
+ const dLng = (b.lng - a.lng) * TO_RAD;
+ const h =
+ Math.sin(dLat / 2) ** 2 +
+ Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
+ return 2 * Math.atan2(Math.sqrt(h), Math.sqrt(1 - h));
+}
+
+// A pin is about 3.2 degrees across on the globe (PIN_RADIUS in Globe.tsx), so
+// two builds nearer than this overlap by more than a sliver and read as one
+// blob. Angular, not on-screen: the pins are world-sized, so what overlaps at
+// rest overlaps just the same after the dolly-in.
+export const GROUP_ANGLE_DEG = 3;
+
+export type BuildGroup = {
+ // Stable for a given membership, so React keeps a group's pin mounted while
+ // unrelated entries come and go.
+ id: string;
+ // West to east, which is the order the fan lays them out in, left to right.
+ // Builds on the very same spot keep the order they were given in.
+ members: Build[];
+ // The mean direction of the members: where the group's one pin is drawn.
+ // No member is moved - each keeps its own `location`.
+ center: LatLng;
+};
+
+function meanDirection(members: Build[]): LatLng {
+ let x = 0;
+ let y = 0;
+ let z = 0;
+ for (const { location } of members) {
+ const v = latLngToVec3(location.lat, location.lng, 1);
+ x += v[0];
+ y += v[1];
+ z += v[2];
+ }
+ const length = Math.hypot(x, y, z) || 1;
+ // The inverse of latLngToVec3.
+ const lat = 90 - Math.acos(Math.min(1, Math.max(-1, y / length))) / TO_RAD;
+ const lng = wrapDegrees(Math.atan2(z, -x) / TO_RAD - 180);
+ return { lat, lng };
+}
+
+// Into (-180, 180].
+function wrapDegrees(deg: number): number {
+ const wrapped = ((deg % 360) + 360) % 360;
+ return wrapped > 180 ? wrapped - 360 : wrapped;
+}
+
+// Every entry lands in exactly one group; an entry with no close neighbour is
+// a group of one. Complete linkage: two sets merge only while EVERY pair
+// across them is within the limit, closest sets first. Single linkage would
+// let a chain of builds each a little further along the coast swallow a whole
+// country into one pin; this keeps a group no wider than one pin's reach.
+export function groupBuilds(entries: Build[], maxAngleDeg = GROUP_ANGLE_DEG): BuildGroup[] {
+ const limit = maxAngleDeg * TO_RAD + 1e-9;
+ const dist: number[][] = entries.map((a) =>
+ entries.map((b) => angularDistance(a.location, b.location)),
+ );
+
+ // Clusters as lists of indices into `entries`, kept in first-member order.
+ const clusters: number[][] = entries.map((_, index) => [index]);
+ for (;;) {
+ let best: { a: number; b: number; link: number } | null = null;
+ for (let a = 0; a < clusters.length; a += 1) {
+ for (let b = a + 1; b < clusters.length; b += 1) {
+ let link = 0;
+ for (const i of clusters[a]) {
+ for (const j of clusters[b]) link = Math.max(link, dist[i][j]);
+ }
+ if (link <= limit && (!best || link < best.link)) best = { a, b, link };
+ }
+ }
+ if (!best) break;
+ clusters[best.a] = [...clusters[best.a], ...clusters[best.b]].sort((p, q) => p - q);
+ clusters.splice(best.b, 1);
+ }
+
+ return clusters.map((indices) => {
+ const inOrder = indices.map((index) => entries[index]);
+ const center = meanDirection(inOrder);
+ const members = inOrder
+ .map((build, order) => ({ build, order, east: wrapDegrees(build.location.lng - center.lng) }))
+ .sort((p, q) => p.east - q.east || p.order - q.order)
+ .map(({ build }) => build);
+ return {
+ // Sorted, so the id does not depend on the order the entries came in.
+ id: inOrder.map((build) => build.id).sort().join('+'),
+ members,
+ center,
+ };
+ });
+}
+
+// --- The fan ---------------------------------------------------------------
+//
+// An open group is a hand fan standing on the shared point: its builds on an
+// arc above it, west to east. Upwards and never a full circle, because the
+// selected build's name is printed just below the pin (GlobeViewer), and on a
+// phone a finger covers whatever is under the tap.
+
+const FAN_STEP_MAX = 56 * TO_RAD; // between neighbours, when there is room
+const FAN_SPREAD_MAX = 160 * TO_RAD; // the whole arc never dips below level
+// Neighbouring pins sit at least this far apart, centre to centre: far enough
+// that their hit areas do not swallow each other under a fingertip.
+const FAN_MIN_CHORD_PX = 30;
+// ...and never closer than this many pin radii, so they stay apart once the
+// dolly-in has made the pins themselves bigger.
+const FAN_MIN_CHORD_PINS = 2.9;
+
+function fanStep(count: number): number {
+ return count < 2 ? 0 : Math.min(FAN_STEP_MAX, FAN_SPREAD_MAX / (count - 1));
+}
+
+// The direction of one member from the shared point, as an angle on screen
+// (radians, anticlockwise from "right"), first member leftmost. `lean` tips
+// the whole fan over to the right (see fanLean).
+export function fanAngle(count: number, index: number, lean = 0): number {
+ return Math.PI / 2 - lean + ((count - 1) / 2 - index) * fanStep(count);
+}
+
+export function fanAngles(count: number, lean = 0): number[] {
+ return Array.from({ length: count }, (_, index) => fanAngle(count, index, lean));
+}
+
+// Centre-to-centre distance between neighbouring pins of the fan, in pixels.
+export function fanChordPx(pinRadiusPx: number): number {
+ return Math.max(FAN_MIN_CHORD_PX, FAN_MIN_CHORD_PINS * pinRadiusPx);
+}
+
+// How far from the shared point the pins sit, in pixels. Sized on screen and
+// not as an angle on the globe: an angle that separates the pins after the
+// dolly-in would collapse them into each other when the globe is far away.
+export function fanRadiusPx(count: number, pinRadiusPx: number): number {
+ const step = fanStep(count);
+ if (step === 0) return 0;
+ return fanChordPx(pinRadiusPx) / (2 * Math.sin(step / 2));
+}
+
+// Something else on the map the fan should not land on: its centre in pixels
+// from the shared point (x right, y up) and its radius.
+export type FanObstacle = { x: number; y: number; r: number };
+
+const FAN_LEAN_STEPS = 6; // candidates each side of upright
+const FAN_LEVEL = 88 * TO_RAD; // no pin of a leaning fan dips below this
+const FAN_CLEARANCE_PX = 3;
+// A pin of the fan may be the selected one, drawn this much bigger.
+const FAN_PIN_REACH = 1.45;
+// How much better (pxยฒ of overlap) tipping further must be before the fan
+// does it: without this it would rock between two near-equal leans as the
+// globe turns under it.
+const FAN_LEAN_STICK = 9;
+
+function fanOverlap(
+ count: number, radiusPx: number, pinRadiusPx: number, lean: number, obstacles: FanObstacle[],
+): number {
+ let cost = 0;
+ for (let index = 0; index < count; index += 1) {
+ const angle = fanAngle(count, index, lean);
+ const x = Math.cos(angle) * radiusPx;
+ const y = Math.sin(angle) * radiusPx;
+ for (const obstacle of obstacles) {
+ const need = pinRadiusPx * FAN_PIN_REACH + obstacle.r + FAN_CLEARANCE_PX;
+ const short = need - Math.hypot(x - obstacle.x, y - obstacle.y);
+ if (short > 0) cost += short * short;
+ }
+ }
+ return cost;
+}
+
+// How far to tip the fan over (radians, positive to the right) so its pins do
+// not land on a neighbouring pin. The UK and France are the case in point:
+// France's fan, standing straight up, would put a pin exactly on the UK.
+// Upright unless something is in the way; never so far that a pin dips below
+// level; and slow to tip further than `current`, the lean it already has.
+export function fanLean(
+ count: number,
+ radiusPx: number,
+ pinRadiusPx: number,
+ obstacles: FanObstacle[],
+ current = 0,
+): number {
+ const limit = Math.max(0, FAN_LEVEL - ((count - 1) / 2) * fanStep(count));
+ if (limit === 0 || obstacles.length === 0) return 0;
+
+ let best = 0;
+ let bestCost = fanOverlap(count, radiusPx, pinRadiusPx, 0, obstacles);
+ // Outwards from upright, right before left, so the least lean that clears
+ // the neighbours wins and the answer never depends on float noise.
+ for (let step = 1; step <= FAN_LEAN_STEPS && bestCost > 0; step += 1) {
+ for (const side of [1, -1]) {
+ const lean = (side * step * limit) / FAN_LEAN_STEPS;
+ const cost = fanOverlap(count, radiusPx, pinRadiusPx, lean, obstacles);
+ if (cost < bestCost - 1e-9) {
+ best = lean;
+ bestCost = cost;
+ }
+ }
+ }
+ // Sticky only towards upright: a fan stays less tipped than it might be
+ // while the overlap that costs is slight, and comes back up the moment the
+ // way is clear - it never keeps a lean it no longer needs.
+ if (current !== best && Math.abs(current) < Math.abs(best)) {
+ const currentCost = fanOverlap(count, radiusPx, pinRadiusPx, current, obstacles);
+ if (currentCost <= bestCost + FAN_LEAN_STICK) return current;
+ }
+ return best;
+}
diff --git a/web/src/components/sections/InsidePanel.tsx b/web/src/components/sections/InsidePanel.tsx
index 1c30a9dd..28a6c4d0 100644
--- a/web/src/components/sections/InsidePanel.tsx
+++ b/web/src/components/sections/InsidePanel.tsx
@@ -4,7 +4,7 @@ import Link from 'next/link';
import { SectionContent } from '@/lib/content';
import BuildCard from './InsideGlobe/BuildCard';
import BuildIndex from './InsideGlobe/BuildIndex';
-import { BUILD_FILTERS, builds } from './InsideGlobe/builds';
+import { BUILD_FILTERS, builds, countCountries } from './InsideGlobe/builds';
import { useBuildSelection } from './InsideGlobe/useBuildSelection';
import styles from './InsidePanel.module.css';
@@ -41,6 +41,9 @@ const JOIN = [
},
];
+// How far the map reaches, said once and quietly beside the entry count.
+const COUNTRIES = countCountries(builds);
+
export default function InsidePanel({ content }: InsidePanelProps) {
const { filter, visibleBuilds } = useBuildSelection();
const label = BUILD_FILTERS.find((entry) => entry.value === filter)?.label;
@@ -77,7 +80,9 @@ export default function InsidePanel({ content }: InsidePanelProps) {
{filter === 'all' ? 'Around the world' : label}
- {filter === 'all' ? `${builds.length} entries` : `${visibleBuilds.length} of ${builds.length} entries`}
+ {filter === 'all'
+ ? `${builds.length} entries ยท ${COUNTRIES} countries`
+ : `${visibleBuilds.length} of ${builds.length} entries`}