IKEA assembly, step by step: animated, manual-style 3D guides. Scan any paper manual with Together AI.
TypeScript
Every AI feature runs on the visitor's own Together key
Youssef23e57bde5256
diff --git a/.env.example b/.env.exampleindex d663400..2ff06cb 100644--- a/.env.example+++ b/.env.example@@ -1,9 +1,8 @@-# Together AI key: unlocks any product name, photo lookup, live help, and the-# hands-free voice on lines that have no pre-recorded clip (scanned manuals,-# spoken help answers). Without it those lines are skipped (they stay on-# screen): the device's own voice is never used.-# Scanning a manual (/scan) always uses the visitor's own key instead.-# Re-record the voice clips with `npm run voice`. Get a key at https://api.together.ai+# Together AI key, for development only. The site never spends a key of its own:+# visitors paste theirs into the app, and every AI feature runs on it. Locally,+# pasting bygga-dev-mock-key-000000 into the app uses this key instead (never in+# production). The recording scripts use it too: re-record the voice clips with+# `npm run voice`. Get a key at https://api.together.aiTOGETHER_API_KEY=# Optional: the GitHub repo shown (with its star count) in the nav.diff --git a/README.md b/README.mdindex 42eecde..4dd66b4 100644--- a/README.md+++ b/README.md@@ -13,18 +13,18 @@- A parametric plan generator (`src/lib/plan`) for 7 furniture types and 74 kinds: 1,171 IKEA products (2,180 sizes, UK and US ranges) drawn offline, with typo-tolerant search and article numbers- IKEA's public product listings (`scripts/ikea`): `npm run ikea:fetch` downloads them locally (they are git ignored, see NOTICE), `classify.ts` maps name, type and size to kinds, `npm run ikea:build` writes the catalog rows in `src/data`, and `npm run ikea:check` tests them; every IKEA family name is known, so MARKUS reads as an office chair and never as a typo of MARIUS- Manual scanner (`/scan`, parked for v2 and off unless `NEXT_PUBLIC_SCAN=1`): a vision model reads each page, `gpt-oss-120b` lays out the parts in millimetres, and `src/lib/plan/custom.ts` places every dowel, bolt and screw where parts touch-- Together AI for unknown product names (steered by IKEA's own type, cached for good with `use cache: remote`), photo lookup and the "Stuck?" helper, with model fallback lists in `src/lib/together.ts`-- A hands-free voice on Together AI (Kokoro, `src/lib/voice/tts.ts`): every catalog line is pre-recorded with `npm run voice` (1,476 clips cover all 2,180 guides), the rest are recorded live, product names keep phonetic spellings where they help (`npm run voice:names`), and saying "next" turns the page, even while she is talking: the page listens through an echo-cancelled mic, sends each bit of talk to Whisper on Together (`/api/listen`), and sets her own words aside by when she said them (`hearIntent` in `src/lib/voice/commands.ts`), the same in every browser. `npm run voice:check` replays 283 recorded runs through it+- Together AI on each visitor's own key (`src/components/KeyModal.tsx` asks for it, about a cent a build): unknown product names (steered by IKEA's own type), photo lookup, and a help chat whose answers come with drawings of the exact panel, fitting or step from the guide (`[part B]` tags, `readAnswer` in `src/components/guide/HelpSheet.tsx`), with model fallback lists in `src/lib/together.ts`+- A hands-free voice on Together AI (Kokoro, `src/lib/voice/tts.ts`): every catalog line is pre-recorded with `npm run voice` (1,476 clips cover all 2,180 guides) and reads aloud with no key, the rest are recorded live, product names keep phonetic spellings where they help (`npm run voice:names`), and saying "next" turns the page, even while she is talking: the page listens through an echo-cancelled mic, sends each bit of talk to Whisper on Together (`/api/listen`), and sets her own words aside by when she said them (`hearIntent` in `src/lib/voice/commands.ts`), the same in every browser. `npm run voice:check` replays 283 recorded runs through it- Workshop (`/builds`): every finished build merged into one scene and rendered at true scale next to a person- Share cards drawn by the engine (`scripts/og/render.mjs`, `src/lib/og`), a picture of your finished build to post, an A4 print view, and a service worker so opened guides work with no signal## Cloning & running1. Clone: `git clone https://github.com/Luffixos/bygga.git && cd bygga && npm install`-2. Optional key: `cp .env.example .env.local`, then set `TOGETHER_API_KEY` (the 2,180 offline guides work without it)+2. Optional key: `cp .env.example .env.local`, then set `TOGETHER_API_KEY`, and paste `bygga-dev-mock-key-000000` into the app's key box: under `npm run dev` it stands for your `.env.local` key (the 2,180 offline guides and the read-aloud voice work without one)3. Run: `npm run dev`, open http://localhost:3000 and type `BISSA`4. Jump to a step: http://localhost:3000/build/malm-3-drawers?step=12, print one at `/build/malm-3-drawers/print`, or see finished builds at `/builds`-5. Try the scanner free: run with `NEXT_PUBLIC_SCAN=1`, then on `/scan` paste `bygga-dev-mock-key-000000` as the key and add any photo (only `npm run dev` accepts it)+5. Try the scanner free: run with `NEXT_PUBLIC_SCAN=1`, then on `/scan` paste the same dev key and add any photo (only `npm run dev` accepts it)6. Rebuild the catalog from IKEA's listings (only needed when they change): `npm run ikea:fetch && npm run ikea:build && npm run ikea:check`7. Before pushing: `npm run lint && npm run build`@@ -33,6 +33,7 @@- [x] let people flag a step that doesn't match their box (logged as `[feedback]`)- [x] a print view: the whole guide on A4- [x] cache AI product reads on the server so the second person to ask gets them instantly+- [x] every AI feature on the visitor's own Together key, and help answers with pictures of the part- [x] teach the generator corner sofas, sliding doors, office chairs, day-beds, kitchen and bathroom cabinets- [ ] the last odd shapes `scripts/ikea/skips.ts` lists: three-cornered shelves, corner combinations and PAX widths that don't split into frames- [ ] the voice in more languages@@ -41,6 +42,6 @@## Security-The server's Together key never reaches the browser, every `/api/*` route that spends it answers only the site's own pages and is rate limited per IP, and the pages send a strict Content Security Policy. A visitor's own key (needed for `/scan`) stays in their `localStorage`, travels only in an `x-together-key` header, and is never stored or logged. Scanned guides and build progress live in the browser too, and a shared scan carries the guide inside its link. What the site keeps and sends where is spelled out on [/privacy](https://bygga-eta.vercel.app/privacy).+The site has no Together key of its own in production: every AI call runs on the visitor's key, which stays in their `localStorage`, travels only in an `x-together-key` header, and is never stored or logged. Every `/api/*` route answers only the site's own pages and is rate limited per IP, and the pages send a strict Content Security Policy. Scanned guides and build progress live in the browser too, and a shared scan carries the guide inside its link. What the site keeps and sends where is spelled out on [/privacy](https://bygga-eta.vercel.app/privacy).MIT licensed, see [LICENSE](LICENSE). Bygga is not affiliated with IKEA: IKEA and its product names are trademarks of Inter IKEA Systems B.V., and the license grants no rights in them (see [NOTICE](NOTICE)).diff --git a/src/app/api/guide/route.ts b/src/app/api/guide/route.tsindex a14791b..066961d 100644--- a/src/app/api/guide/route.ts+++ b/src/app/api/guide/route.ts@@ -1,9 +1,8 @@import { PRODUCTS, toSpec } from "@/lib/catalog";import { categoryOf, fold, guessSpec, matchCatalog, searchCatalog } from "@/lib/search";import { parseSpec, SPEC_PROMPT } from "@/lib/spec";-import { draft, type Draft } from "@/lib/draft";import { ikeaType } from "@/lib/ikea";-import { chatText, extractJson, fromApp, hasKey, ipOf, MODELS, rateLimited, TogetherError, userKey } from "@/lib/together";+import { chatText, extractJson, fromApp, ipOf, keyTrouble, MODELS, rateLimited, TogetherError, userKey } from "@/lib/together";import type { ProductSpec } from "@/lib/types";const cache = new Map<string, { spec: ProductSpec; model: string }>();@@ -26,15 +25,17 @@ export async function POST(req: Request) {// IKEA's own word for what this is: steers the draft, and says plainly when it's something we can't drawconst type = await ikeaType(q);if (type && !drawable(type)) return Response.json({ found: false, ikea: type, suggestions: suggestions(), via: "ikea" });- // one spelling per name, so the shared draft cache isn't split by upper and lower case+ // names read the same to the model however they were typedconst said = q.replace(/\s+/g, " ").toUpperCase();const hint = type ? `${said} (IKEA sells this as: ${type})` : said;+ // working out a product we don't know runs on the person's own key; without one, they pick its shapeconst own = userKey(req);- if (hasKey() || own) {+ let trouble: string | null = null;+ if (own) {if (rateLimited(ipOf(req) + ":guide", 12)) return Response.json({ error: "slow down" }, { status: 429 });try {- const d = await draftWith(own, type ? `${key}|${fold(type)}` : key, hint);+ const d = await draft(own, hint);if (d && "found" in d) {return Response.json({ found: false, suggestions: suggestions(d.suggestions), via: "ai" });}@@ -50,13 +51,14 @@ export async function POST(req: Request) {}} catch (e) {const err = e as TogetherError;+ trouble = keyTrouble(err.status);console.error("[guide] together error", err.status, err.message);}}const g = guessSpec(type ? `${q} ${type}` : q);- if (g && categoryOf(type ? `${q} ${type}` : q)) return Response.json({ spec: { ...g, variant: type ?? g.variant }, via: "guess" });- return Response.json({ found: false, ikea: type ?? undefined, suggestions: suggestions(), via: hasKey() || own ? "ai" : "offline" });+ if (g && categoryOf(type ? `${q} ${type}` : q)) return Response.json({ spec: { ...g, variant: type ?? g.variant }, via: "guess", trouble: trouble ?? undefined });+ return Response.json({ found: false, ikea: type ?? undefined, suggestions: suggestions(), via: own ? "ai" : "offline", trouble: trouble ?? undefined });}/** Types the plan generator can draw: lamps, mattresses, textiles, plants and the like it can't. */@@ -65,22 +67,11 @@ function drawable(type: string) {return categoryOf(type) !== null;}-/** The shared, cached draft on the server key; a visitor's own key is never cached under someone else's name. */-async function draftWith(own: string | undefined, key: string, q: string): Promise<Draft | null> {- if (!own && hasKey()) return draft(key, q);- try {- return await draftOwn(own!, q);- } catch (e) {- // a saved key that stopped working gets the shared, cached draft, not a fresh call on the server key- if (e instanceof TogetherError && (e.status === 401 || e.status === 403) && hasKey()) return draft(key, q);- throw e;- }-}+type Draft = { spec: ProductSpec; model: string } | { found: false; suggestions: string[] };-async function draftOwn(own: string, q: string): Promise<Draft | null> {+async function draft(own: string, q: string): Promise<Draft | null> {const { text, model } = await chatText({key: own,- fallback: false,models: MODELS.text,json: true,maxTokens: 1800,diff --git a/src/app/api/help/route.ts b/src/app/api/help/route.tsindex c677d05..e1aca40 100644--- a/src/app/api/help/route.ts+++ b/src/app/api/help/route.ts@@ -1,4 +1,4 @@-import { chat, fromApp, hasKey, ipOf, MODELS, rateLimited, userKey, type Msg } from "@/lib/together";+import { chat, fromApp, ipOf, keyTrouble, MODELS, rateLimited, TogetherError, userKey, type Msg } from "@/lib/together";interface Body {context?: string;@@ -12,16 +12,17 @@ Answer in plain, warm English. At most 3 short sentences, or a short numbered liBe practical and specific to the step they are on. If something could hurt them or damage the furniture, say so first.If a part is missing or broken: tell them to note the number printed on the bag or panel, and that IKEA stores and customer service usually replace small fittings for free.If they send a photo of a part, say which part from the list it most likely is and why (size, shape, head).+They see pictures from their own guide when you add tags: [part B] shows panel B, [fitting 3] shows fitting 3, [step 5] shows the drawing of step 5, using the letters and numbers in the lists below. Add the tags for what your answer is about: the panel or fitting you matched in a photo, the ones you name, the step you point them to, or this step when they ask what to do. At most 3, together on the last line. Never mention the tags or the pictures in words. In your words, call a panel by its letter and name ("panel B, the divider") and a fitting by its name ("the wooden dowels"), never by its number.Never use em dashes or en dashes.`;export async function POST(req: Request) {if (!fromApp(req)) return Response.json({ error: "forbidden" }, { status: 403 });const key = userKey(req);- if (!hasKey() && !key) return Response.json({ error: "ai-off" }, { status: 503 });+ if (!key) return Response.json({ error: "key" }, { status: 401 });if (rateLimited(ipOf(req) + ":help", 20)) return Response.json({ error: "slow down" }, { status: 429 });const b = (await req.json().catch(() => ({}))) as Body;const question = (b.question ?? "").toString().slice(0, 600);- const context = (b.context ?? "").toString().slice(0, 3000);+ const context = (b.context ?? "").toString().slice(0, 7000);const history = (Array.isArray(b.history) ? b.history : []).filter((m) => m && (m.role === "user" || m.role === "assistant")).slice(-6)@@ -75,6 +76,7 @@ export async function POST(req: Request) {return new Response(stream, { headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" } });} catch (e) {console.error("[help]", (e as Error).message);- return Response.json({ error: "failed" }, { status: 502 });+ const trouble = e instanceof TogetherError ? keyTrouble(e.status) : null;+ return Response.json({ error: trouble ?? "failed" }, { status: trouble === "key" ? 401 : trouble === "credits" ? 402 : 502 });}}diff --git a/src/app/api/identify/route.ts b/src/app/api/identify/route.tsindex 7e9b680..10be087 100644--- a/src/app/api/identify/route.ts+++ b/src/app/api/identify/route.ts@@ -1,4 +1,4 @@-import { chatText, extractJson, fromApp, hasKey, ipOf, MODELS, rateLimited, userKey } from "@/lib/together";+import { chatText, extractJson, fromApp, ipOf, keyTrouble, MODELS, rateLimited, TogetherError, userKey } from "@/lib/together";const PROMPT = `This photo shows an IKEA product, its box, its label or its assembly manual cover. Read the product name.Reply with JSON only: {"name": "KALLAX", "variant": "2x4 shelving unit", "confidence": 0.0-1.0}.@@ -7,7 +7,7 @@ The name is the word in capitals (it may contain Å, Ä or Ö). If you can't reaexport async function POST(req: Request) {if (!fromApp(req)) return Response.json({ error: "forbidden" }, { status: 403 });const key = userKey(req);- if (!hasKey() && !key) return Response.json({ error: "ai-off" }, { status: 503 });+ if (!key) return Response.json({ error: "key" }, { status: 401 });if (rateLimited(ipOf(req) + ":identify", 8)) return Response.json({ error: "slow down" }, { status: 429 });const { image } = (await req.json().catch(() => ({}))) as { image?: string };if (typeof image !== "string" || !image.startsWith("data:image/") || image.length > 3_000_000) return Response.json({ error: "bad image" }, { status: 400 });@@ -26,6 +26,7 @@ export async function POST(req: Request) {return Response.json({ name, variant, query: [name, variant].filter(Boolean).join(" ").trim(), confidence: Number(j?.confidence ?? 0) });} catch (e) {console.error("[identify]", (e as Error).message);- return Response.json({ error: "failed" }, { status: 502 });+ const trouble = e instanceof TogetherError ? keyTrouble(e.status) : null;+ return Response.json({ error: trouble ?? "failed" }, { status: trouble === "key" ? 401 : trouble === "credits" ? 402 : 502 });}}diff --git a/src/app/api/key/route.ts b/src/app/api/key/route.tsindex cd549d5..a74eb72 100644--- a/src/app/api/key/route.ts+++ b/src/app/api/key/route.ts@@ -1,13 +1,15 @@-import { fromApp, ipOf, rateLimited, userKey } from "@/lib/together";+import { fromApp, ipOf, isDevKey, rateLimited, userKey } from "@/lib/together";/** Checks that a pasted Together AI key works, without storing it. */export async function POST(req: Request) {// the scanner posts the key alone, with no bodyif (!fromApp(req, false)) return Response.json({ ok: false, reason: "forbidden" }, { status: 403 });- if (rateLimited(ipOf(req) + ":key", 6, 10 * 60_000)) return Response.json({ ok: false, reason: "unavailable" }, { status: 429 });+ if (isDevKey(req)) return Response.json({ ok: true });+ // a string that can't be a key is turned away before it costs a checkconst key = userKey(req);if (!key) return Response.json({ ok: false, reason: "format" });- if (key === "bygga-dev-mock-key-000000" && process.env.NODE_ENV !== "production") return Response.json({ ok: true });+ // too many checks: "busy" is never taken for a working key+ if (rateLimited(ipOf(req) + ":key", 12, 10 * 60_000)) return Response.json({ ok: false, reason: "busy" }, { status: 429 });try {const r = await fetch("https://api.together.xyz/v1/models", { headers: { Authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(8000) });await r.body?.cancel();diff --git a/src/app/api/listen/route.ts b/src/app/api/listen/route.tsindex 2dac68b..29b4499 100644--- a/src/app/api/listen/route.ts+++ b/src/app/api/listen/route.ts@@ -1,4 +1,4 @@-import { fromApp, hasKey, ipOf, rateLimited, userKey } from "@/lib/together";+import { fromApp, ipOf, rateLimited, userKey } from "@/lib/together";import { transcribe } from "@/lib/voice/stt";/** 3 s of 16 kHz 16-bit mono is 96 KB; a little room above that, nothing like a recording. */@@ -11,25 +11,24 @@ const MAX_BYTES = 128 * 1024;*/export async function POST(req: Request) {if (!fromApp(req, false) || !(req.headers.get("content-type") ?? "").startsWith("audio/wav")) return Response.json({ error: "forbidden" }, { status: 403 });- // the person's own key when they've added one; the site's when it's turned away, as for the other routes- const keys = [...new Set([userKey(req), hasKey() ? process.env.TOGETHER_API_KEY!.trim() : undefined].filter((k): k is string => !!k))];- if (!keys.length) return Response.json({ error: "ai-off" }, { status: 503 });+ // listening runs on the person's own key+ const key = userKey(req);+ if (!key) return Response.json({ error: "key" }, { status: 401 });// a busy room sends a piece every second or so; this is well above thatif (rateLimited(ipOf(req) + ":listen", 150)) return Response.json({ error: "slow down" }, { status: 429 });const wav = await req.arrayBuffer().catch(() => null);if (!wav || wav.byteLength < 44 + 3200 || wav.byteLength > MAX_BYTES) return Response.json({ error: "bad audio" }, { status: 400 });const head = new TextDecoder().decode(new Uint8Array(wav, 0, 12));if (!head.startsWith("RIFF") || !head.endsWith("WAVE")) return Response.json({ error: "bad audio" }, { status: 400 });- let err = "";- for (const key of keys) {- try {- const text = await transcribe(wav, key, AbortSignal.timeout(8000));- return Response.json({ text }, { headers: { "Cache-Control": "no-store" } });- } catch (e) {- err = (e as Error).message;- if (!/ 40[123]:/.test(err)) break;- }+ try {+ const text = await transcribe(wav, key, AbortSignal.timeout(8000));+ return Response.json({ text }, { headers: { "Cache-Control": "no-store" } });+ } catch (e) {+ const err = (e as Error).message;+ console.error("[listen]", err);+ // the key turned away, or the account out of credit: the guide says so instead of retrying+ if (/ 40[13]:/.test(err)) return Response.json({ error: "key" }, { status: 401 });+ if (/ 402:/.test(err)) return Response.json({ error: "credits" }, { status: 402 });+ return Response.json({ error: "failed" }, { status: 502 });}- console.error("[listen]", err);- return Response.json({ error: "failed" }, { status: 502 });}diff --git a/src/app/api/scan/route.ts b/src/app/api/scan/route.tsindex 6b911ba..56814c5 100644--- a/src/app/api/scan/route.ts+++ b/src/app/api/scan/route.ts@@ -2,28 +2,26 @@ import { buildPlan } from "@/lib/plan";import { clean, fallbackSpec, parseScan } from "@/lib/scan/parse";import { PAGE_PROMPT, PLAN_PROMPT, planInput, repairInput } from "@/lib/scan/prompts";import { SAMPLE_SCAN } from "@/lib/scan/sample";-import { chatText, extractJson, fromApp, ipOf, MODELS, rateLimited, TogetherError, userKey, type Msg } from "@/lib/together";+import { chatText, extractJson, fromApp, ipOf, isDevKey, MODELS, rateLimited, TogetherError, userKey, type Msg } from "@/lib/together";import type { ProductSpec } from "@/lib/types";import { SCAN_ENABLED } from "@/lib/site";export const maxDuration = 300;-/** Only for trying the scan flow locally without spending credits. Never accepted in production. */-const DEV_MOCK_KEY = "bygga-dev-mock-key-000000";-type Note = { kind?: string; product?: { name?: string; brand?: string; type?: string }; parts?: unknown[]; hardware?: unknown[]; steps?: { n?: number }[] };export async function POST(req: Request) {if (!SCAN_ENABLED) return Response.json({ error: "off" }, { status: 404 });if (!fromApp(req)) return Response.json({ error: "forbidden" }, { status: 403 });- const key = userKey(req);+ // the dev key tries the scan flow locally without spending credits+ const mock = isDevKey(req);+ const key = mock ? "mock" : userKey(req);if (!key) return Response.json({ error: "key" }, { status: 401 });if (rateLimited(ipOf(req) + ":scan", 6, 10 * 60_000)) return Response.json({ error: "busy" }, { status: 429 });const body = (await req.json().catch(() => null)) as { pages?: unknown[]; hint?: unknown } | null;const pages = (body?.pages ?? []).filter((p): p is string => typeof p === "string" && p.startsWith("data:image/") && p.length < 4_000_000).slice(0, 12);if (!pages.length) return Response.json({ error: "pages" }, { status: 400 });const hint = clean(String(body?.hint ?? "")).slice(0, 80);- const mock = key === DEV_MOCK_KEY && process.env.NODE_ENV !== "production";const enc = new TextEncoder();const stream = new ReadableStream({@@ -60,10 +58,8 @@ async function scan(key: string, pages: string[], hint: string, send: (o: objectwhile (next < pages.length) {const i = next++;try {- // scans only ever spend the person's own key, never the server'sconst { text } = await chatText({key,- fallback: false,models: MODELS.read,maxTokens: 2000,temperature: 0,@@ -90,7 +86,7 @@ async function scan(key: string, pages: string[], hint: string, send: (o: object{ role: "user", content: planInput(notes, hint) },];const ask = async () => {- const { text } = await chatText({ key, fallback: false, models: MODELS.plan, json: true, maxTokens: 16000, temperature: 0.2, reasoning: "medium", signal, messages: msgs });+ const { text } = await chatText({ key, models: MODELS.plan, json: true, maxTokens: 16000, temperature: 0.2, reasoning: "medium", signal, messages: msgs });return { text, raw: extractJson(text) };};let { text, raw } = await ask();diff --git a/src/app/api/status/route.ts b/src/app/api/status/route.tsdeleted file mode 100644index 6789fd4..0000000--- a/src/app/api/status/route.ts+++ /dev/null@@ -1,7 +0,0 @@-import { connection } from "next/server";-import { hasKey } from "@/lib/together";--export async function GET() {- await connection();- return Response.json({ ai: hasKey(), voice: hasKey() });-}diff --git a/src/app/api/voice/route.ts b/src/app/api/voice/route.tsindex 89c128d..d8e460f 100644--- a/src/app/api/voice/route.ts+++ b/src/app/api/voice/route.ts@@ -1,27 +1,33 @@import { connection } from "next/server";-import { hasKey, ipOf, rateLimited } from "@/lib/together";+import { ipOf, rateLimited, userKey } from "@/lib/together";import { forTTS, speak } from "@/lib/voice/tts";/*** Records a line live in the same voice as the pre-recorded clips, for text- * that has no clip yet: scanned guides and spoken help answers. Responses are- * cached for good on the CDN too, so each line is only paid for once.+ * that has no clip yet: scanned guides and spoken help answers. It runs on the+ * person's own key. Responses are cached for good on the CDN too, so each line+ * is only paid for once.*/export async function GET(req: Request) {await connection();- if (!hasKey()) return Response.json({ error: "voice-off" }, { status: 404 });+ const key = userKey(req);+ if (!key) return Response.json({ error: "key" }, { status: 401 });// only the app's own pages, which always say so: not other sites or scripts using it as a free voiceif (req.headers.get("sec-fetch-site") !== "same-origin") return Response.json({ error: "forbidden" }, { status: 403 });const text = (new URL(req.url).searchParams.get("t") ?? "").replace(/\s+/g, " ").trim();if (!text || text.length > 400) return Response.json({ error: "bad text" }, { status: 400 });if (rateLimited(ipOf(req) + ":voice", 40)) return Response.json({ error: "slow down" }, { status: 429 });try {- const audio = await speak(forTTS(text), process.env.TOGETHER_API_KEY!.trim());+ const audio = await speak(forTTS(text), key);return new Response(audio, {headers: { "Content-Type": "audio/mpeg", "Cache-Control": "public, max-age=31536000, immutable", "CDN-Cache-Control": "public, max-age=31536000, immutable" },});} catch (e) {- console.error("[voice]", (e as Error).message);+ const err = (e as Error).message;+ console.error("[voice]", err);+ // the key turned away, or the account out of credit, as the other routes say it+ if (/ 40[13]:/.test(err)) return Response.json({ error: "key" }, { status: 401 });+ if (/ 402:/.test(err)) return Response.json({ error: "credits" }, { status: 402 });return Response.json({ error: "failed" }, { status: 502 });}}diff --git a/src/app/guide.css b/src/app/guide.cssindex d080e0b..40b420d 100644--- a/src/app/guide.css+++ b/src/app/guide.css@@ -646,33 +646,74 @@.foot-row .btn.link {font-size: 14.5px;}-.foot-row .btn.link.stuck {- gap: 6px;- text-decoration: none;- font-size: 13px;- color: var(--ink-3);+.step-pane .pane-foot {+ position: relative;}-.foot-row .btn.link.stuck:hover {- color: var(--ink);+.keys-tip {+ position: absolute;+ right: 16px;+ bottom: calc(100% + 10px);+ z-index: 4;+ display: flex;+ align-items: center;+ gap: 14px;+ height: 40px;+ padding: 0 6px 0 14px;+ border-radius: 999px;+ background: var(--ink);+ color: rgba(255, 255, 255, 0.86);+ font-size: 13.5px;+ font-weight: 500;+ white-space: nowrap;+ box-shadow: 0 10px 24px -14px rgba(18, 18, 18, 0.5);}-.kbd-hint {- font-size: 13px;- color: var(--ink-3);- font-weight: 600;+.keys-tip::after {+ content: "";+ position: absolute;+ right: 44px;+ bottom: -5px;+ width: 11px;+ height: 11px;+ border-radius: 2px;+ background: var(--ink);+ transform: rotate(45deg);+}+.keys-tip > span {+ display: inline-flex;+ align-items: center;+ gap: 4px;}-.kbd-hint kbd {+.keys-tip kbd {display: inline-grid;place-items: center;min-width: 22px;height: 22px;padding: 0 5px;- margin-right: 2px;border-radius: 6px;- background: var(--sunk);- box-shadow: inset 0 -1.5px 0 var(--line-2);+ background: rgba(255, 255, 255, 0.14);+ box-shadow: inset 0 -1.5px 0 rgba(255, 255, 255, 0.12);font: inherit;font-size: 12px;- color: var(--ink-2);+ font-weight: 600;+ color: #fff;+}+.keys-tip-x {+ display: grid;+ place-items: center;+ width: 28px;+ height: 28px;+ border: 0;+ border-radius: 999px;+ background: transparent;+ color: rgba(255, 255, 255, 0.7);+ cursor: pointer;+ transition:+ background 0.2s,+ color 0.2s;+}+.keys-tip-x:hover {+ background: rgba(255, 255, 255, 0.14);+ color: #fff;}.callout {@@ -730,6 +771,22 @@background: #fff;box-shadow: inset 0 0 0 1px var(--line);}+.callout-link.plain {+ display: block;+ margin-top: 8px;+ padding: 0;+ border: 0;+ background: none;+ font: inherit;+ font-size: 14px;+ font-weight: 600;+ color: var(--ink);+ text-align: left;+ text-decoration: underline;+ text-decoration-thickness: 1.5px;+ text-underline-offset: 3px;+ cursor: pointer;+}/* ================= stage overlays ================= */@@ -948,6 +1005,30 @@overflow: hidden;text-overflow: ellipsis;}+.listening:has(.listening-fix) {+ padding-right: 5px;+}+.listening-text {+ min-width: 0;+ overflow: hidden;+ text-overflow: ellipsis;+}+.listening-fix {+ flex: 0 0 auto;+ height: 30px;+ padding: 0 12px;+ border: 0;+ border-radius: 999px;+ background: var(--accent);+ color: var(--ink);+ font-size: 13.5px;+ font-weight: 600;+ cursor: pointer;+ transition: transform 0.16s var(--ease);+}+.listening-fix:active {+ transform: scale(0.96);+}.eq {display: inline-flex;align-items: center;@@ -2068,10 +2149,32 @@ input[type="range"] {margin: 22px 0 10px;font-size: 15px;}-.ask-head .muted {+.ask-key {+ display: inline-flex;+ align-items: center;+ gap: 5px;margin-left: auto;+ padding: 5px 10px;+ border: 0;+ border-radius: 999px;+ background: var(--sunk);font-size: 13px;font-weight: 600;+ color: var(--ink-2);+ cursor: pointer;+ transition:+ background 0.2s,+ color 0.2s;+}+.ask-key:hover {+ background: #e8e5de;+ color: var(--ink);+}+.ask-note {+ margin: 10px 2px 0;+ font-size: 13.5px;+ line-height: 1.45;+ color: var(--ink-3);}.ask-suggest {display: flex;@@ -2119,6 +2222,106 @@ input[type="range"] {background: var(--sunk);border-bottom-left-radius: 6px;}+.msg.pics {+ max-width: 100%;+}+.msg.err {+ background: var(--miss-soft);+}+.msg-fix {+ display: inline-flex;+ align-items: center;+ gap: 6px;+ margin-top: 8px;+ padding: 6px 12px;+ border: 0;+ border-radius: 999px;+ background: #fff;+ box-shadow: 0 0 0 1px var(--line-2);+ font-size: 14px;+ font-weight: 600;+ color: var(--ink);+ text-decoration: none;+ cursor: pointer;+}+.msg-fix:hover {+ box-shadow: 0 0 0 1px var(--ink-3);+}+.msg-pics {+ display: grid;+ grid-template-columns: repeat(auto-fill, minmax(112px, 1fr));+ gap: 8px;+ margin: 10px 0 2px;+}+.pic {+ display: flex;+ flex-direction: column;+ min-width: 0;+ margin: 0;+ padding: 6px 6px 8px;+ border: 0;+ border-radius: 14px;+ background: #fff;+ box-shadow: 0 0 0 1px var(--line);+ text-align: left;+ font: inherit;+ color: inherit;+ animation: fadeIn 0.3s var(--ease);+}+.pic-thumb {+ width: 100%;+ border-radius: 10px;+ background: var(--sunk);+}+.pic-art {+ display: grid;+ place-items: center;+ width: 100%;+ aspect-ratio: 260 / 190;+ border-radius: 10px;+ background: var(--sunk);+}+.pic-art svg {+ max-width: 76%;+ max-height: 76%;+}+.pic-cap {+ display: flex;+ flex-direction: column;+ gap: 1px;+ padding: 6px 4px 0;+ line-height: 1.3;+}+.pic-cap b {+ display: flex;+ align-items: center;+ gap: 6px;+ font-size: 13.5px;+ font-weight: 600;+}+.pic-cap > span {+ font-size: 12.5px;+ color: var(--ink-3);+ overflow: hidden;+ display: -webkit-box;+ -webkit-line-clamp: 2;+ -webkit-box-orient: vertical;+}+button.pic {+ cursor: pointer;+ transition:+ box-shadow 0.2s,+ transform 0.16s var(--ease);+}+button.pic:hover:not(:disabled) {+ box-shadow: 0 0 0 1.5px var(--ink);+}+button.pic:active:not(:disabled) {+ transform: scale(0.97);+}+button.pic:disabled {+ cursor: default;+}.typing {font-weight: 500;background: linear-gradient(90deg, var(--ink-3) 0%, var(--ink-3) 40%, var(--ink) 50%, var(--ink-3) 60%, var(--ink-3) 100%);@@ -2380,6 +2583,45 @@ input[type="range"] {.nf-head h1 {margin: 0;}+.nf-ai {+ display: flex;+ align-items: center;+ gap: 12px;+ padding: 12px 10px 12px 18px;+ border-radius: 20px;+ background: var(--accent-soft);+ font-size: 15px;+ line-height: 1.45;+ color: var(--accent-ink);+}+.nf-ai > svg {+ flex: 0 0 auto;+ color: var(--ink);+}+.nf-ai > span {+ flex: 1;+ min-width: 0;+}+.nf-ai b {+ font-weight: 600;+ color: var(--ink);+}+.nf-ai a {+ color: var(--ink);+ font-weight: 600;+ text-underline-offset: 3px;+}+.btn.nf-ai-go {+ flex: 0 0 auto;+ height: 40px;+ padding: 0 18px;+ background: var(--ink);+ color: #fff;+ font-size: 14.5px;+}+.btn.nf-ai-go:hover {+ background: #2a2a2a;+}.kind-grid {display: grid;grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));@@ -2536,6 +2778,16 @@ input[type="range"] {flex-direction: column;text-align: center;}+ .nf-ai {+ flex-wrap: wrap;+ padding: 14px 16px;+ }+ .nf-ai > span {+ flex-basis: calc(100% - 32px);+ }+ .btn.nf-ai-go {+ width: 100%;+ }.kind-grid {grid-template-columns: repeat(2, minmax(0, 1fr));}@@ -2651,7 +2903,7 @@ input[type="range"] {}@media (hover: none), (max-width: 900px) {- .kbd-hint {+ .keys-tip {display: none;}}@@ -2957,3 +3209,360 @@ input[type="range"] {grid-template-rows: none;}}++/* ================= key modal ================= */++.key-back {+ position: fixed;+ inset: 0;+ z-index: 70;+ display: grid;+ place-items: center;+ padding: 16px;+ background: rgba(18, 18, 18, 0.34);+}+.key-modal {+ position: relative;+ width: min(440px, 100%);+ max-height: calc(100dvh - 32px);+ overflow-y: auto;+ overscroll-behavior: contain;+ padding: 20px 24px 20px;+ border-radius: 28px;+ background: #fff;+ box-shadow: var(--shadow-2);+ scrollbar-width: thin;+}+.key-modal:focus {+ outline: none;+}+.key-x {+ position: absolute;+ top: 28px;+ right: 32px;+ z-index: 1;+ display: grid;+ place-items: center;+ width: 34px;+ height: 34px;+ border: 0;+ border-radius: 999px;+ background: #fff;+ color: var(--ink-2);+ cursor: pointer;+ box-shadow: 0 0 0 1px var(--line);+ transition:+ color 0.2s,+ transform 0.16s var(--ease);+}+.key-x:hover {+ color: var(--ink);+}+.key-x:active {+ transform: scale(0.94);+}+.key-hero {+ position: relative;+ display: flex;+ align-items: flex-end;+ justify-content: center;+ height: 124px;+ border-radius: 20px;+ background-color: var(--sunk);+ background-image: radial-gradient(var(--line-2) 1px, transparent 1.2px);+ background-size: 16px 16px;+ background-position: 8px 8px;+ overflow: hidden;+}+.key-hero .figure {+ margin-bottom: -6px;+}+.key-bubble {+ position: absolute;+ top: 18px;+ left: calc(50% + 24px);+ padding: 4px 11px 5px;+ border-radius: 14px 14px 14px 4px;+ background: #fff;+ box-shadow: 0 0 0 2px var(--ink);+ font-size: 14px;+ font-weight: 800;+ white-space: nowrap;+ animation: keyPop 0.5s 0.15s var(--spring) both;+}+.key-tag {+ position: absolute;+ bottom: 18px;+ left: calc(50% - 82px);+ display: grid;+ place-items: center;+ width: 38px;+ height: 38px;+ border-radius: 999px;+ background: var(--accent);+ box-shadow: 0 0 0 2px var(--ink);+ transform: rotate(-14deg);+ animation: keyPop 0.5s 0.3s var(--spring) both;+}+@keyframes keyPop {+ from {+ opacity: 0;+ scale: 0.6;+ }+}+.key-modal h2 {+ margin: 18px 0 4px;+ font-family: var(--display);+ font-size: 26px;+ font-weight: 800;+ line-height: 1.15;+ letter-spacing: -0.02em;+ text-wrap: balance;+}+.key-sub {+ margin: 0;+ font-size: 15.5px;+ color: var(--ink-2);+}+.key-feats {+ display: grid;+ gap: 10px;+ margin: 16px 0 0;+ padding: 0;+ list-style: none;+}+.key-feats li {+ display: flex;+ align-items: center;+ gap: 12px;+ font-size: 15px;+ line-height: 1.4;+ color: var(--ink-2);+}+.key-feats b {+ font-weight: 600;+ color: var(--ink);+}+.key-feat-ico {+ display: grid;+ place-items: center;+ flex: 0 0 auto;+ width: 34px;+ height: 34px;+ border-radius: 999px;+ background: var(--sunk);+ color: var(--ink);+}+.key-cost {+ display: flex;+ align-items: center;+ gap: 14px;+ margin: 18px 0 0;+ padding: 12px 16px 12px 12px;+ border-radius: 18px;+ background: var(--accent-soft);+ color: var(--accent-ink);+ font-size: 14.5px;+ line-height: 1.4;+}+.key-cost b {+ display: block;+ font-weight: 600;+ font-size: 15px;+ color: var(--ink);+}+.key-cost a {+ color: var(--ink);+ font-weight: 600;+ text-underline-offset: 3px;+}+.key-cost.out {+ background: var(--miss-soft);+ color: var(--ink-2);+}+.key-cent {+ flex: 0 0 auto;+ min-width: 56px;+ font-family: var(--display);+ font-size: 30px;+ font-weight: 800;+ line-height: 1;+ letter-spacing: -0.03em;+ text-align: center;+ color: var(--ink);+}+.key-form {+ display: flex;+ gap: 8px;+ margin: 18px 0 0;+}+.key-input {+ flex: 1;+ min-width: 0;+ display: flex;+ align-items: center;+ gap: 10px;+ height: 52px;+ padding: 0 14px;+ border-radius: 14px;+ background: #fff;+ box-shadow: 0 0 0 1px var(--line-2);+ color: var(--ink-3);+ cursor: text;+ transition: box-shadow 0.2s;+}+.key-input:focus-within {+ box-shadow: 0 0 0 2px var(--ink);+}+.key-input input {+ flex: 1;+ min-width: 0;+ border: 0;+ outline: none;+ background: none;+ font-size: 16px;+ color: var(--ink);+}+.key-input input::placeholder {+ color: var(--ink-3);+}+.key-form.bad .key-input {+ box-shadow: 0 0 0 2px var(--miss);+ animation: keyShake 0.36s var(--ease);+}+@keyframes keyShake {+ 25% {+ translate: -5px 0;+ }+ 50% {+ translate: 4px 0;+ }+ 75% {+ translate: -2px 0;+ }+}+.btn.primary.key-save {+ flex: 0 0 auto;+ min-width: 96px;+ height: 52px;+ padding: 0 20px;+ border-radius: 14px;+ gap: 6px;+}+.key-form.saved .btn.primary.key-save {+ background: var(--ok);+ color: #fff;+}+.key-help {+ margin: 10px 2px 0;+ font-size: 14px;+ color: var(--ink-2);+}+.key-help a {+ display: inline-flex;+ align-items: center;+ gap: 4px;+ color: var(--ink);+ font-weight: 600;+ text-decoration: underline;+ text-decoration-thickness: 1.5px;+ text-underline-offset: 3px;+}+.key-help.bad {+ color: var(--miss);+ font-weight: 500;+}+.key-safe {+ display: flex;+ align-items: center;+ gap: 6px;+ margin: 4px 2px 0;+ font-size: 13px;+ color: var(--ink-3);+}+.key-have {+ display: flex;+ align-items: center;+ gap: 12px;+ margin: 18px 0 0;+ padding: 10px 8px 10px 10px;+ border-radius: 14px;+ box-shadow: 0 0 0 1px var(--line-2);+}+.key-have-ico {+ display: grid;+ place-items: center;+ width: 36px;+ height: 36px;+ border-radius: 10px;+ background: var(--accent-soft);+}+.key-have-text {+ flex: 1;+ min-width: 0;+ display: flex;+ flex-direction: column;+ line-height: 1.3;+}+.key-have-text b {+ font-size: 15px;+ font-weight: 600;+}+.key-have-text span {+ font-size: 13.5px;+ color: var(--ink-3);+}+.key-skip {+ display: block;+ margin: 14px auto 0;+ padding: 8px 10px;+ border: 0;+ background: none;+ font-size: 15px;+ font-weight: 600;+ color: var(--ink-2);+ text-decoration: underline;+ text-decoration-thickness: 1.5px;+ text-underline-offset: 4px;+ cursor: pointer;+}+.key-skip:hover {+ color: var(--ink);+}+@media (max-width: 640px) {+ .key-back {+ place-items: end stretch;+ padding: 0;+ }+ .key-modal {+ width: 100%;+ max-height: 94dvh;+ padding: 14px 16px calc(16px + env(safe-area-inset-bottom));+ border-radius: 26px 26px 0 0;+ }+ .key-x {+ top: 22px;+ right: 26px;+ }+ .key-hero {+ height: 104px;+ }+ .key-hero .figure {+ width: 48px;+ height: 80px;+ }+ .key-modal h2 {+ margin-top: 14px;+ font-size: 24px;+ }+ .key-feats {+ margin-top: 12px;+ gap: 8px;+ }+ .key-cost {+ margin-top: 14px;+ }+ .key-form {+ margin-top: 14px;+ }+}diff --git a/src/app/privacy/page.tsx b/src/app/privacy/page.tsxindex ab89674..dbd65fe 100644--- a/src/app/privacy/page.tsx+++ b/src/app/privacy/page.tsx@@ -20,7 +20,7 @@ export default function Privacy() {<h2>On your device</h2><ul><li>Your build progress, which step you are on, and settings like the voice, saved in your browser's local storage.</li>- <li>Your own Together AI key, if you add one. It is sent with your requests so they run on your account, and never stored on our side.</li>+ <li>Your own Together AI key, if you add one. Every AI feature runs on it, so it is sent with those requests and used for them only. It is never stored or logged on our side.</li><li>Guides and voice clips you have opened, kept by the browser so they work offline.</li></ul><p>Clearing this site's data in your browser deletes all of it.</p>@@ -28,7 +28,7 @@ export default function Privacy() {<h2>What reaches our server</h2><ul><li>The product name you search for, to find or draft its guide.</li>- <li>Questions and photos you send from “Stuck?”, and photos of a box label you search with. Photos are resized in your browser first, which also removes location data.</li>+ <li>Questions and photos you send from the help panel, and photos of a box label you search with. Photos are resized in your browser first, which also removes location data.</li><li>The text of a voice line that has no recording yet, to record it.</li><li>While the voice is on, short bits of sound from your mic each time someone talks, so it can hear you say “next”. They are turned into text, and Bygga keeps neither.</li><li>Feedback you send, such as “This step doesn't match my box”, kept in our server logs with the product and step.</li>@@ -38,7 +38,7 @@ export default function Privacy() {<h2>Who else sees it</h2><ul><li>- <b>Together AI</b> (United States) turns searches, questions and photos into answers, records voice lines, and turns what the mic hears into text. See their{" "}+ <b>Together AI</b> (United States) turns searches, questions and photos into answers, records voice lines, and turns what the mic hears into text, all on your own key. See their{" "}<a href="https://www.together.ai/privacy" target="_blank" rel="noreferrer">privacy policy</a>diff --git a/src/components/KeyModal.tsx b/src/components/KeyModal.tsxnew file mode 100644index 0000000..2c393df--- /dev/null+++ b/src/components/KeyModal.tsx@@ -0,0 +1,325 @@+"use client";++import { useEffect, useRef, useState } from "react";+import { createPortal } from "react-dom";+import { motion } from "motion/react";+import { Figure } from "./art/Figure";+import { ICamera, ICheck, IClose, IExternal, IImage, IKey, ILock, IMic, IVolume, IWand } from "./art/Icons";+import { KEY_URL, setUserKey, useUserKey } from "@/lib/userKey";++/** What brought the person here: the modal leads with that. "key" is for checking or changing a saved key. */+export type KeyWhy = "voice" | "ask" | "photo" | "draft" | "key";+/** A key Together turned away, or an account out of credit. */+export type KeyTrouble = "key" | "credits";++const BILLING_URL = "https://api.together.ai/settings/billing";++const FEATURES = {+ next: { icon: IMic, b: "Say “next”", rest: "and it moves on. Your hands stay on the build." },+ ask: { icon: IVolume, b: "Ask when you're stuck,", rest: "out loud or typed, and hear the answer." },+ see: { icon: IImage, b: "See the exact part", rest: "it means, drawn from your guide." },+ photo: { icon: ICamera, b: "Snap the box label", rest: "to find its guide." },+ draft: { icon: IWand, b: "Steps for any product,", rest: "even ones we don't have yet." },+};++const COPY: Record<KeyWhy, { title: (name?: string) => string; bubble: string; features: (keyof typeof FEATURES)[] }> = {+ voice: { title: () => "Go hands-free", bubble: "Next!", features: ["next", "ask", "see"] },+ ask: { title: () => "Ask about any step", bubble: "Which one?", features: ["ask", "see", "next"] },+ photo: { title: () => "Search with a photo", bubble: "Found it", features: ["photo", "ask", "next"] },+ draft: { title: (name) => (name ? `Steps for ${name}` : "Steps for any product"), bubble: "How?", features: ["draft", "next", "ask"] },+ key: { title: () => "Your Together AI key", bubble: "Hi!", features: ["next", "ask", "see"] },+};++/**+ * Asks for the person's own Together AI key, which every AI feature runs on:+ * what it unlocks, what it costs (about a cent a build) and where to get one.+ * Their key stays in this browser.+ */+export default function KeyModal({+ why,+ name,+ trouble,+ skip,+ onSkip,+ onClose,+ onSaved,+ onGesture,+}: {+ why: KeyWhy;+ /** The product, for "draft". */+ name?: string;+ trouble?: KeyTrouble | null;+ /** The quiet way out, e.g. "Just read it aloud", and what it does (closing, unless given). */+ skip?: string;+ onSkip?: () => void;+ /** Closed with no new key. */+ onClose: () => void;+ /** A working key was saved. */+ onSaved?: () => void;+ /** Runs inside the tap on Save, before anything waits: lets the guide start audio, which Safari only allows from a tap. */+ onGesture?: () => void;+}) {+ const key = useUserKey();+ const copy = COPY[why];+ const [editing, setEditing] = useState(!key || trouble === "key");+ const [draft, setDraft] = useState("");+ const [state, setState] = useState<"idle" | "checking" | "bad" | "busy" | "saved">("idle");+ const input = useRef<HTMLInputElement>(null);+ const box = useRef<HTMLDivElement>(null);+ const done = useRef(false);+ // closed while a key was still being checked: it isn't saved, and nothing starts+ const gone = useRef(false);+ const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);+ const close = () => {+ gone.current = true;+ onClose();+ };+ useEffect(() => {+ // set again on mount: React can mount a component twice in development+ gone.current = false;+ return () => {+ gone.current = true;+ clearTimeout(timer.current);+ };+ }, []);++ // keyboards start inside; on phones the field waits for a tap so the keyboard doesn't cover what it's for+ useEffect(() => {+ const back = document.activeElement as HTMLElement | null;+ const fine = matchMedia("(hover: hover) and (pointer: fine)").matches;+ if (fine && input.current) input.current.focus({ preventScroll: true });+ else box.current?.focus({ preventScroll: true });+ return () => back?.focus?.({ preventScroll: true });+ }, []);++ useEffect(() => {+ const onKey = (e: KeyboardEvent) => {+ if (e.key === "Escape") {+ // closes this alone, not the help sheet or guide behind it+ e.preventDefault();+ e.stopImmediatePropagation();+ gone.current = true;+ onClose();+ } else if (e.key === "Tab" && box.current) {+ // focus stays inside while it's open+ const all = [...box.current.querySelectorAll<HTMLElement>("button:not(:disabled), a[href], input")];+ if (!all.length) return;+ const first = all[0],+ last = all[all.length - 1];+ if (e.shiftKey && (document.activeElement === first || document.activeElement === box.current)) {+ e.preventDefault();+ last.focus();+ } else if (!e.shiftKey && document.activeElement === last) {+ e.preventDefault();+ first.focus();+ }+ }+ };+ window.addEventListener("keydown", onKey, true);+ return () => window.removeEventListener("keydown", onKey, true);+ }, [onClose]);++ async function save(value = draft) {+ const k = value.trim();+ if (!k || state === "checking" || done.current) return;+ onGesture?.();+ setState("checking");+ let reason = "";+ try {+ const r = await fetch("/api/key", { method: "POST", headers: { "x-together-key": k } });+ const j = (await r.json()) as { ok: boolean; reason?: string };+ // a check that couldn't run doesn't block the key: it's tried for real on first use+ reason = j.ok || j.reason === "unavailable" ? "" : (j.reason ?? "rejected");+ } catch {+ reason = "";+ }+ if (gone.current) return;+ if (reason) {+ setState(reason === "busy" ? "busy" : "bad");+ input.current?.focus();+ return;+ }+ done.current = true;+ setUserKey(k);+ setState("saved");+ // a beat to see "Saved"; closed in that beat, the key stays saved but nothing else starts+ timer.current = setTimeout(() => !gone.current && (onSaved ?? onClose)(), 650);+ }++ const bad = state === "bad" || state === "busy";+ const help =+ state === "bad"+ ? "Together didn't accept that key. Copy it again from your Together dashboard."+ : state === "busy"+ ? "That's a lot of tries. Wait a few minutes, then paste it again."+ : trouble === "key" && !draft+ ? "Together turned your saved key away. Paste a new one."+ : null;++ // on the body, so nothing it's opened from (a moving search box, a sheet) can clip or shift it+ return createPortal(+ <motion.div className="key-back" initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0, transition: { duration: 0.16 } }} onClick={close}>+ <motion.div+ ref={box}+ tabIndex={-1}+ className="key-modal"+ role="dialog"+ aria-modal="true"+ aria-labelledby="key-title"+ initial={{ opacity: 0, y: 24, scale: 0.98 }}+ animate={{ opacity: 1, y: 0, scale: 1 }}+ exit={{ opacity: 0, y: 12, scale: 0.98, transition: { duration: 0.16 } }}+ transition={{ type: "spring", stiffness: 420, damping: 34 }}+ onClick={(e) => e.stopPropagation()}+ >+ <button className="key-x" onClick={close} aria-label="Close">+ <IClose size={18} />+ </button>++ <div className="key-hero" aria-hidden="true">+ <Figure pose="wave" size={92} />+ <span className="key-bubble">{copy.bubble}</span>+ <span className="key-tag">+ <IKey size={15} />+ </span>+ </div>++ <h2 id="key-title">{copy.title(name)}</h2>+ <p className="key-sub">Bygga's AI runs on your own Together AI key.</p>++ <ul className="key-feats">+ {copy.features.map((f) => {+ const { icon: Icon, b, rest } = FEATURES[f];+ return (+ <li key={f}>+ <span className="key-feat-ico">+ <Icon size={17} />+ </span>+ <span>+ <b>{b}</b> {rest}+ </span>+ </li>+ );+ })}+ </ul>++ {trouble === "credits" ? (+ <div className="key-cost out">+ <span className="key-cent">$0</span>+ <span>+ <b>Your Together credit ran out.</b>+ <a href={BILLING_URL} target="_blank" rel="noreferrer">+ Add credit <IExternal size={12} />+ </a>{" "}+ and it picks up where it left off.+ </span>+ </div>+ ) : (+ <div className="key-cost">+ <span className="key-cent">1¢</span>+ <span>+ <b>About a cent a build.</b> A few cents if the room is busy. $5 of credit lasts 100+ builds.+ </span>+ </div>+ )}++ {!editing && key ? (+ <div className="key-have">+ <span className="key-have-ico">{state === "saved" ? <ICheck size={17} strokeWidth={2.6} /> : <IKey size={17} />}</span>+ <span className="key-have-text">+ <b>Key saved</b>+ <span>Ending in {key.slice(-4)}</span>+ </span>+ <button+ className="link-btn"+ onClick={() => {+ setEditing(true);+ setTimeout(() => input.current?.focus(), 30);+ }}+ >+ Change+ </button>+ <button className="link-btn" onClick={() => setUserKey("")}>+ Remove+ </button>+ </div>+ ) : (+ <form+ className={"key-form" + (bad ? " bad" : "") + (state === "saved" ? " saved" : "")}+ onSubmit={(e) => {+ e.preventDefault();+ save();+ }}+ >+ <label className="key-input">+ <IKey size={17} />+ <input+ ref={input}+ type="password"+ value={draft}+ onChange={(e) => {+ setDraft(e.target.value);+ if (bad) setState("idle");+ }}+ // a pasted key is the whole key: no need to also press Save+ onPaste={(e) => {+ const v = e.clipboardData.getData("text").trim();+ if (v.length < 20) return;+ e.preventDefault();+ setDraft(v);+ save(v);+ }}+ placeholder="Paste your key"+ aria-label="Together AI API key"+ aria-invalid={bad}+ aria-describedby="key-help"+ autoComplete="off"+ autoCapitalize="off"+ spellCheck={false}+ enterKeyHint="done"+ />+ </label>+ <button className="btn primary key-save" type="submit" disabled={!draft.trim() || state === "checking" || state === "saved"}>+ {state === "saved" ? (+ <>+ <ICheck size={17} strokeWidth={2.8} /> Saved+ </>+ ) : state === "checking" ? (+ "Checking"+ ) : (+ "Save"+ )}+ </button>+ </form>+ )}++ <p id="key-help" className={"key-help" + (help ? " bad" : "")} role={help ? "alert" : undefined}>+ {help ?? (+ <>+ No key yet?{" "}+ <a href={KEY_URL} target="_blank" rel="noreferrer">+ Make one at together.ai <IExternal size={12} />+ </a>+ </>+ )}+ </p>+ <p className="key-safe">+ <ILock size={13} /> Stays in this browser. Bygga never stores it.+ </p>++ {skip && (+ <button+ className="key-skip"+ onClick={() => {+ gone.current = true;+ (onSkip ?? onClose)();+ }}+ >+ {skip}+ </button>+ )}+ </motion.div>+ </motion.div>,+ document.body,+ );+}diff --git a/src/components/guide/CoverPanel.tsx b/src/components/guide/CoverPanel.tsxindex bfc938a..2dd2a9d 100644--- a/src/components/guide/CoverPanel.tsx+++ b/src/components/guide/CoverPanel.tsx@@ -18,6 +18,7 @@ export default function CoverPanel({onStart,onResume,onReview,+ onOwnSteps,}: {plan: Plan;via: "catalog" | "ai" | "guess" | "scan";@@ -27,6 +28,8 @@ export default function CoverPanel({onStart: () => void;onResume: () => void;onReview: () => void;+ /** A typical build stands in for this product: a key gets it worked out properly. */+ onOwnSteps?: { text: string; act: () => void };}) {const s = plan.spec;const t = totals(plan);@@ -171,6 +174,11 @@ export default function CoverPanel({? "Built from what Together AI knows about this product. If your box looks different, trust the paper manual.": "We don't know this exact product yet, so this follows a typical build. Keep the paper manual close."}</span>+ {via === "guess" && onOwnSteps && (+ <button className="callout-link plain" onClick={onOwnSteps.act}>+ {onOwnSteps.text}+ </button>+ )}</div></div>)diff --git a/src/components/guide/GuideApp.tsx b/src/components/guide/GuideApp.tsxindex 8c4973f..7f0523d 100644--- a/src/components/guide/GuideApp.tsx+++ b/src/components/guide/GuideApp.tsx@@ -10,7 +10,7 @@ import { buildPlan } from "@/lib/plan";import { stepContents } from "@/lib/plan/contents";import { matchCatalog, specForKind } from "@/lib/search";import { KIND_LABELS, type Kind } from "@/lib/products";-import { BREAK_MS, cacheSpec, cachedSpec, getPref, isBuilt, loadProgress, saveProgress, setPref, type Phase, type Progress } from "@/lib/store";+import { BREAK_MS, cacheSpec, cachedSpec, getPref, isBuilt, loadProgress, saveProgress, setPref, uncacheSpec, type Phase, type Progress } from "@/lib/store";import StageView, { type StageHandle } from "../StageView";import type { StageMode } from "@/engine/stage";import { LogoMark } from "../Logo";@@ -32,7 +32,8 @@ import { mediaSession, voice } from "./voice";import { LINES, builtLine, needsLine, spokenAnswer, stepLines, toolsLine, whereLine } from "@/lib/voice/script";import { hearIntent, type Intent } from "@/lib/voice/commands";import { useMounted } from "@/lib/useMounted";-import { getUserKey, keyHeaders } from "@/lib/userKey";+import { getUserKey, keyHeaders, useUserKey } from "@/lib/userKey";+import KeyModal, { type KeyTrouble, type KeyWhy } from "../KeyModal";import { decodeSpec } from "@/lib/scan/share";import { track } from "@vercel/analytics";import { SCAN_ENABLED } from "@/lib/site";@@ -46,8 +47,10 @@ export default function GuideApp({ slug, query, step, kind }: { slug: string; quconst isScan = slug.startsWith("scan-");const q = query || slug.replace(/-/g, " ");const initial = useMemo(() => (isScan ? null : (catalogSpec(slug) ?? (picked ? { ...specForKind(picked, q.split(" ")[0] || q), slug } : null))), [isScan, slug, picked, q]);+ // asked again after a key was added: a typical build gives way to one worked out for this product+ const [attempt, setAttempt] = useState(0);// a build saved under this name (an AI draft, a picked shape) wins over a near-miss in the catalog- const stored = useMemo(() => (mounted && !initial ? (cachedSpec(slug) ?? loadProgress(slug)?.spec ?? null) : null), [mounted, initial, slug]);+ const stored = useMemo(() => (mounted && !initial ? (cachedSpec(slug) ?? loadProgress(slug)?.spec ?? null) : null), [mounted, initial, slug, attempt]); // eslint-disable-line react-hooks/exhaustive-depsconst match = useMemo(() => (initial || isScan ? null : matchCatalog(q)), [initial, isScan, q]);const local = stored ? null : match;const [imported, setImported] = useState<{ slug: string; spec: ProductSpec | null } | null>(null);@@ -71,8 +74,16 @@ export default function GuideApp({ slug, query, step, kind }: { slug: string; quuseEffect(() => {if (mounted && local?.slug && local.slug !== slug) router.replace(`/build/${local.slug}` + (step ? `?step=${step}` : ""));}, [mounted, local, slug, step, router]);- const [fetched, setFetched] = useState<{ slug: string; spec?: ProductSpec; via?: Via; suggestions?: string[]; ikea?: string; error?: boolean } | null>(null);- const [ai, setAi] = useState(false);+ const [fetched, setFetched] = useState<{ slug: string; spec?: ProductSpec; via?: Via; suggestions?: string[]; ikea?: string; error?: boolean; trouble?: KeyTrouble } | null>(null);+ // every AI feature runs on the person's own key+ const key = useUserKey();+ const ai = !!key;+ const [askKey, setAskKey] = useState<KeyTrouble | "" | null>(null);+ const again = () => {+ uncacheSpec(slug);+ setFetched(null);+ setAttempt((a) => a + 1);+ };const result = fetched?.slug === slug ? fetched : null;const spec = initial ?? cached ?? result?.spec ?? null;const via: Via = initial ? (initial.source === "guess" ? "guess" : "catalog") : cached ? cached.source : (result?.via ?? "ai");@@ -81,14 +92,8 @@ export default function GuideApp({ slug, query, step, kind }: { slug: string; quconst suggestions = result?.suggestions ?? [];useEffect(() => {- fetch("/api/status")- .then((r) => r.json())- .then((j) => {- setAi(!!j.ai || !!getUserKey());- voice.live = !!j.voice;- })- .catch(() => {});- }, []);+ voice.live = !!key;+ }, [key]);// resolve unknown products through the APIuseEffect(() => {@@ -105,15 +110,16 @@ export default function GuideApp({ slug, query, step, kind }: { slug: string; qureturn;}sp.slug = slug;- cacheSpec(slug, sp);- setFetched({ slug, spec: sp, via: j.via });- } else setFetched({ slug, suggestions: j.suggestions ?? [], ikea: j.ikea });+ // a typical build is only a stand-in: not kept, so the next visit (with a key, say) can ask for the real thing+ if (j.via !== "guess") cacheSpec(slug, sp);+ setFetched({ slug, spec: sp, via: j.via, trouble: j.trouble });+ } else setFetched({ slug, suggestions: j.suggestions ?? [], ikea: j.ikea, trouble: j.trouble });}).catch(() => alive && setFetched({ slug, error: true }));return () => {alive = false;};- }, [mounted, initial, cached, local, isScan, slug, q, step, router]);+ }, [mounted, initial, cached, local, isScan, slug, q, step, router, attempt]);const plan = useMemo(() => {if (!spec) return null;@@ -125,6 +131,24 @@ export default function GuideApp({ slug, query, step, kind }: { slug: string; qu}}, [spec]);+ const draftKey = (+ <AnimatePresence>+ {askKey !== null && (+ <KeyModal+ why="draft"+ name={(spec?.name ?? q.split(" ")[0]).toUpperCase()}+ trouble={askKey || null}+ onClose={() => setAskKey(null)}+ onSaved={() => {+ // with a key, ask again: this time AI works the product out+ setAskKey(null);+ again();+ }}+ />+ )}+ </AnimatePresence>+ );+if (status === "scangone")return (<Shell title="Scanned guide">@@ -147,10 +171,38 @@ export default function GuideApp({ slug, query, step, kind }: { slug: string; quif (status === "notfound" || status === "error" || !plan)return (<Shell title={q.toUpperCase()}>- <NotFound query={q} slug={slug} suggestions={suggestions} ikea={result?.ikea} error={status === "error"} />+ <NotFound+ query={q}+ slug={slug}+ suggestions={suggestions}+ ikea={result?.ikea}+ error={status === "error"}+ ai={ai}+ trouble={result?.trouble}+ onAddKey={() => setAskKey(result?.trouble ?? "")}+ onRetry={again}+ />+ {draftKey}</Shell>);- return <Guide key={slug + (picked ?? "")} plan={plan} slug={slug} via={via} ai={ai} startStep={step} />;+ // a typical build, not yet started, can still be swapped for one worked out with the person's key+ const trouble = result?.trouble;+ const ownSteps =+ via === "guess" && !initial && mounted && !loadProgress(slug)+ ? !ai+ ? { text: `Add your Together AI key for ${plan.spec.name}'s own steps`, act: () => setAskKey("") }+ : trouble === "key"+ ? { text: `Together turned your key away. Fix it for ${plan.spec.name}'s own steps`, act: () => setAskKey("key") }+ : trouble === "credits"+ ? { text: "Your Together credit ran out. Top it up, then tap here to try again", act: again }+ : { text: `Try again for ${plan.spec.name}'s own steps`, act: again }+ : undefined;+ return (+ <>+ <Guide key={slug + (picked ?? "")} plan={plan} slug={slug} via={via} ai={ai} startStep={step} onOwnSteps={ownSteps} />+ {draftKey}+ </>+ );}function Shell({ title, children }: { title: string; children: React.ReactNode }) {@@ -169,7 +221,27 @@ function Shell({ title, children }: { title: string; children: React.ReactNode });}-function NotFound({ query, slug, suggestions, ikea, error }: { query: string; slug: string; suggestions: string[]; ikea?: string; error: boolean }) {+function NotFound({+ query,+ slug,+ suggestions,+ ikea,+ error,+ ai,+ trouble,+ onAddKey,+ onRetry,+}: {+ query: string;+ slug: string;+ suggestions: string[];+ ikea?: string;+ error: boolean;+ ai: boolean;+ trouble?: KeyTrouble;+ onAddKey: () => void;+ onRetry: () => void;+}) {const name = query.split(" ")[0].toUpperCase();const what = ikea?.toLowerCase();const kinds = KIND_LABELS;@@ -210,6 +282,33 @@ function NotFound({ query, slug, suggestions, ikea, error }: { query: string; sl)}</div></div>+ {!what && (!ai || trouble) && (+ <div className="nf-ai">+ <ISparkle size={18} />+ <span>+ {trouble === "credits" ? (+ <>+ <b>Your Together credit ran out.</b>{" "}+ <a href="https://api.together.ai/settings/billing" target="_blank" rel="noreferrer">+ Top it up+ </a>{" "}+ and AI can work out {name}'s own steps.+ </>+ ) : trouble === "key" ? (+ <>+ <b>Together turned your key away.</b> Fix it and AI can work out {name}'s own steps.+ </>+ ) : (+ <>+ <b>Want {name}'s own steps?</b> Add your Together AI key and AI works them out, for about a cent.+ </>+ )}+ </span>+ <button className="btn nf-ai-go" onClick={trouble === "credits" ? onRetry : onAddKey}>+ {trouble === "credits" ? "Try again" : trouble ? "Fix it" : "Add key"}+ </button>+ </div>+ )}<div className="kind-grid">{kinds.map((k, i) => (<motion.div key={k.kind} initial={{ opacity: 0, y: 10 }} animate={{ opacity: 1, y: 0 }} transition={{ delay: i * 0.025 }}>@@ -244,7 +343,7 @@ function NotFound({ query, slug, suggestions, ikea, error }: { query: string; sl/* ------------------------------------------------------------------ */-function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; via: Via; ai: boolean; startStep?: number }) {+function Guide({ plan, slug, via, ai, startStep, onOwnSteps }: { plan: Plan; slug: string; via: Via; ai: boolean; startStep?: number; onOwnSteps?: { text: string; act: () => void } }) {const steps = plan.steps;const deep = startStep ? Math.min(startStep, steps.length) - 1 : null;const [phase, setPhase] = useState<Phase>(deep !== null ? "steps" : "cover");@@ -279,7 +378,14 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; vconst clock = useRef({ at: 0, ms: 0, live: false });const stage = useRef<StageHandle | null>(null);const mounted = useMounted();+ const key = useUserKey();const canListen = mounted && ai && micSupported();+ // asking for a key: why, and what to do once there is one+ const [askKey, setAskKey] = useState<{ why: KeyWhy; trouble?: KeyTrouble; then?: "voice" | "tip" } | null>(null);+ // a guide with no recordings (an AI draft) can't be read aloud without a key either+ const [readable, setReadable] = useState(true);+ // bumped after the key modal closes on a key problem (a top-up, say), so listening tries again+ const [listenTry, setListenTry] = useState(0);// restore progress once we are in the browserconst [restored, setRestored] = useState(false);@@ -405,7 +511,7 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; v// keyboarduseEffect(() => {const onKey = (e: KeyboardEvent) => {- if (help || overview) return;+ if (help || overview || askKey) return;const t = e.target as HTMLElement;if (t && (t.tagName === "INPUT" || t.tagName === "TEXTAREA")) return;if (phase !== "steps" || e.metaKey || e.ctrlKey || e.altKey) return;@@ -424,7 +530,7 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; v};window.addEventListener("keydown", onKey);return () => window.removeEventListener("keydown", onKey);- }, [phase, next, back, help, overview]);+ }, [phase, next, back, help, overview, askKey]);// the phone's back gesture steps back through the guide instead of leaving itconst nav = useRef({ phase, back });@@ -454,9 +560,9 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; vconst said = useRef("");const micRef = useRef<Mic>("off");- const live = useRef({ next, back, step, voiceOn });+ const live = useRef({ next, back, step, voiceOn, asking: false });useEffect(() => {- live.current = { next, back, step, voiceOn };+ live.current = { next, back, step, voiceOn, asking: !!askKey };});useEffect(() => voice.subscribe(setSpeaking), []);useEffect(() => () => voice.stop(), []);@@ -467,8 +573,10 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; v// runs inside the tap or key press, so the browser lets it play soundconst startVoice = useCallback(() => {voice.unlock();- if (canListen) primeListening();- track("voice_on", { product: plan.spec.name });+ // read now, not from the render: a key saved a moment ago counts+ const listen = micSupported() && !!getUserKey();+ if (listen) primeListening();+ track("voice_on", { product: plan.spec.name, listen });setVoiceOn(true);setOffer(false);setPref("voice", true);@@ -477,9 +585,19 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; vif (!ok) return;// by now the mic has either started or been refused, so the tip matches what worksconst m = micRef.current;- voice.say([canListen && (m === "on" || m === "asking") ? LINES.sayNext : LINES.tapNext]);+ voice.say([listen && (m === "on" || m === "asking" || m === "off") ? LINES.sayNext : LINES.tapNext]);});- }, [canListen, plan, step]);+ }, [plan, step]);++ // with no key yet, turning the voice on first says what a key adds; once skipped, it just reads for the rest of the visit+ const turnOnVoice = useCallback(() => {+ if (getUserKey() || !micSupported() || skippedKey()) return startVoice();+ // still inside the tap: Safari lets sound start later only if it was unlocked here+ voice.unlock();+ primeListening();+ setAskKey({ why: "voice", then: "voice" });+ voice.readable(stepLines(plan, step)).then(setReadable);+ }, [startVoice, plan, step]);const stopVoice = useCallback((confirm = false) => {setVoiceOn(false);@@ -584,7 +702,10 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; vconst { mic, heard } = useListener(voiceOn && phase === "steps" && canListen,+ `${key}#${listenTry}`,(text, seg) => {+ // nothing acts while the key modal is open+ if (askKey) return null;// what's left of her in the mic is set aside by when she said it; then "next" anywhere moves onconst intent = hearIntent(text, seg, voice.linesBetween(seg.start, seg.end), voice.busy || voice.spokeBetween(seg.start, seg.end));if (!intent) return null;@@ -605,13 +726,15 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; vuseEffect(() => {const onKey = (e: KeyboardEvent) => {const t = e.target as HTMLElement;- if (e.key.toLowerCase() !== "v" || e.metaKey || e.ctrlKey || e.repeat || phase !== "steps" || help || overview || t?.tagName === "INPUT" || t?.tagName === "TEXTAREA") return;+ if (e.key.toLowerCase() !== "v" || e.metaKey || e.ctrlKey || e.repeat || phase !== "steps" || help || overview || askKey || t?.tagName === "INPUT" || t?.tagName === "TEXTAREA") return;+ // the key field opens focused: the "v" mustn't land in it+ e.preventDefault();if (voiceOn) stopVoice();- else startVoice();+ else turnOnVoice();};window.addEventListener("keydown", onKey);return () => window.removeEventListener("keydown", onKey);- }, [phase, help, overview, voiceOn, startVoice, stopVoice]);+ }, [phase, help, overview, askKey, voiceOn, turnOnVoice, stopVoice]);// headphone buttons and the lock screen: next track, previous trackuseEffect(() => {@@ -619,8 +742,8 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; vreturn mediaSession({ title: `Step ${step + 1} of ${steps.length}`, artist: plan.spec.name },{- next: () => live.current.next(),- back: () => live.current.back(),+ next: () => !live.current.asking && live.current.next(),+ back: () => !live.current.asking && live.current.back(),play: () => voice.say(stepLines(plan, live.current.step)),pause: () => voice.stop(),},@@ -680,7 +803,7 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; v{sound ? <ISound /> : <ISoundOff />}</button>{phase === "steps" && (- <button className={"voice-btn" + (voiceOn ? " on" : "")} onClick={() => (voiceOn ? stopVoice() : startVoice())} aria-pressed={voiceOn} aria-label={voiceOn ? "Turn voice off" : "Turn voice on"} data-tip="Voice (V)">+ <button className={"voice-btn" + (voiceOn ? " on" : "")} onClick={() => (voiceOn ? stopVoice() : turnOnVoice())} aria-pressed={voiceOn} aria-label={voiceOn ? "Turn voice off" : "Turn voice on"} data-tip="Voice (V)"><IMic size={18} /><span>{voiceOn ? "Voice on" : "Voice"}</span></button>@@ -788,8 +911,14 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; v<i /><i /></span>- <span>- {heard+ <span className="listening-text">+ {!canListen && mounted && micSupported()+ ? "Reading aloud"+ : mic === "refused"+ ? "Together turned your key away"+ : mic === "credits"+ ? "Your Together credit ran out"+ : heard? `Heard “${heard}”`: mic === "on"? "Say “next” when you're ready"@@ -809,6 +938,17 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; v? "Reading aloud. Tap done to move on": "Turning on the mic"}</span>+ {((!canListen && mounted && micSupported()) || mic === "refused" || mic === "credits") && (+ <button+ className="listening-fix"+ onClick={() => {+ primeListening();+ setAskKey(mic === "refused" ? { why: "key", trouble: "key" } : mic === "credits" ? { why: "key", trouble: "credits" } : { why: "voice", then: "tip" });+ }}+ >+ {mic === "credits" ? "Top up" : mic === "refused" ? "Fix key" : "Turn on “next”"}+ </button>+ )}</div>)}{(via === "ai" || via === "scan") && phase === "cover" && (@@ -846,6 +986,7 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; vgo("tools");}}onReview={() => go("steps", 0)}+ onOwnSteps={onOwnSteps}onResume={() => {if (!resume) return;if (resume.phase === "steps") go("steps", Math.min(resume.step, steps.length - 1));@@ -882,8 +1023,7 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; vonNext={next}onBack={back}onHover={setHl}- onHelp={() => setHelp({})}- offer={!voiceOn && offer && (step === 0 || usedVoice) ? { again: usedVoice, listen: canListen, onStart: startVoice, onDismiss: () => setOffer(false) } : null}+ offer={!voiceOn && offer && (step === 0 || usedVoice) ? { again: usedVoice, listen: canListen || (mounted && micSupported() && !skippedKey()), onStart: turnOnVoice, onDismiss: () => setOffer(false) } : null}/>)}{phase === "done" && <DonePanel plan={plan} slug={slug} finish={finish} onReview={back} />}@@ -907,10 +1047,45 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; vask={help.ask}askId={help.at}onAnswer={voiceOn ? speakAnswer : undefined}+ onAddKey={(why, trouble) => setAskKey({ why, trouble })}+ onShow={setHl}+ onGoto={(i) => {+ setHelp(null);+ if (phase !== "steps" || i !== step) go("steps", i, phase !== "steps" || i > step ? 1 : -1);+ }}onClose={() => setHelp(null)}/>)}</AnimatePresence>+ <AnimatePresence>+ {askKey && (+ <KeyModal+ why={askKey.why}+ trouble={askKey.trouble}+ skip={askKey.then === "voice" && readable ? "Just read it aloud" : undefined}+ onSkip={() => {+ setAskKey(null);+ skipKey();+ startVoice();+ }}+ onClose={() => {+ if (askKey.trouble) setListenTry((n) => n + 1);+ setAskKey(null);+ }}+ onGesture={() => {+ if (!voiceOn) voice.unlock();+ primeListening();+ }}+ onSaved={() => {+ const then = askKey.then;+ setAskKey(null);+ if (then === "voice") startVoice();+ // already reading aloud: now it listens too, and says so when it isn't mid-line+ else if (then === "tip" && !voice.speaking) voice.say([LINES.sayNext]);+ }}+ />+ )}+ </AnimatePresence><AnimatePresence>{overview && (<Overview@@ -931,6 +1106,23 @@ function Guide({ plan, slug, via, ai, startStep }: { plan: Plan; slug: string; vconst PHASES: Phase[] = ["cover", "tools", "parts", "steps", "done"];+/** "Just read it aloud" holds for the rest of the visit, so turning the voice on again doesn't ask again. */+const SKIP = "bygga:key-skip";+function skippedKey() {+ try {+ return sessionStorage.getItem(SKIP) === "1";+ } catch {+ return false;+ }+}+function skipKey() {+ try {+ sessionStorage.setItem(SKIP, "1");+ } catch {+ /* storage blocked */+ }+}+function toggle(s: Set<string>, id: string) {const n = new Set(s);if (n.has(id)) n.delete(id);diff --git a/src/components/guide/HelpSheet.tsx b/src/components/guide/HelpSheet.tsxindex e7b9850..ba1f361 100644--- a/src/components/guide/HelpSheet.tsx+++ b/src/components/guide/HelpSheet.tsx@@ -5,32 +5,88 @@ import { AnimatePresence, motion } from "motion/react";import type { Plan } from "@/lib/types";import { faqFor } from "@/lib/faq";import { stepContents } from "@/lib/plan/contents";-import { ICamera, IChevronDown, IClose, IFlag, ISend, ISparkle } from "../art/Icons";+import { ICamera, IChevronDown, IClose, IExternal, IFlag, IKey, ISend, ISparkle } from "../art/Icons";import { Figure } from "../art/Figure";+import { HwArt } from "../art/Hardware";+import Thumb from "../Thumb";+import type { KeyTrouble, KeyWhy } from "../KeyModal";import { keyHeaders } from "@/lib/userKey";interface Msg {role: "user" | "assistant";content: string;image?: string;+ /** The answer didn't come: the key was turned away, the credit ran out, or the helper couldn't be reached. */+ error?: KeyTrouble | "failed";}+/** A picture from this guide that an answer points at. */+type Show = { kind: "part"; id: string } | { kind: "fit"; id: string } | { kind: "step"; index: number };++/** Fittings are numbered in the order the plan lists them, the same in the context and in the answer's tags. */+const fittingNo = (plan: Plan, id: string) => plan.hardware.findIndex((h) => h.id === id) + 1;+export function helpContext(plan: Plan, index: number) {const s = plan.spec;+ const part = (p: { label: string; name: string }, n: number) => `[part ${p.label}] ${p.name} x${n}`;+ const fit = (h: { id: string; name: string; spec: string }, n: number) => `[fitting ${fittingNo(plan, h.id)}] ${h.name}${h.spec ? " " + h.spec : ""} x${n}`;const lines = [`Product: ${s.name}, ${s.variant} (${s.category}), ${s.size.w} x ${s.size.h} x ${s.size.d} cm.`];if (index >= 0) {const st = plan.steps[index];const c = stepContents(plan, index);- lines.push(`Current step ${index + 1} of ${plan.steps.length}: ${st.title}. ${st.detail ?? ""}`);+ lines.push(`Current step: [step ${index + 1}] of ${plan.steps.length}: ${st.title}. ${st.detail ?? ""}`);if (st.repeat) lines.push(`This step is repeated ${st.repeat} times.`);- if (c.parts.length) lines.push("Parts in this step: " + c.parts.map((p) => `${p.type.label} ${p.type.name} x${p.count}`).join(", "));- if (c.hardware.length) lines.push("Hardware in this step: " + c.hardware.map((h) => `${h.type.name} ${h.type.spec} x${h.count}`).join(", "));+ if (c.parts.length) lines.push("Panels in this step: " + c.parts.map((p) => part(p.type, p.count)).join(", "));+ if (c.hardware.length) lines.push("Fittings in this step: " + c.hardware.map((h) => fit(h.type, h.count)).join(", "));if (st.tools.length) lines.push("Tools: " + st.tools.join(", "));- if (index > 0) lines.push(`Previous step: ${plan.steps[index - 1].title}.`);+ if (index > 0) lines.push(`Previous step: [step ${index}] ${plan.steps[index - 1].title}.`);+ if (index + 1 < plan.steps.length) lines.push(`Next step: [step ${index + 2}] ${plan.steps[index + 1].title}.`);+ }+ lines.push("All panels: " + plan.parts.filter((p) => !p.extra).map((p) => part(p, p.qty)).join(", "));+ lines.push("All fittings: " + plan.hardware.map((h) => fit(h, h.qty) + (h.notIncluded ? " (not included)" : "")).join(", "));+ lines.push("All steps: " + plan.steps.map((x, i) => `[step ${i + 1}] ${x.title}`).join("; "));+ return lines.join("\n").slice(0, 7000);+}++const TAG = /\[(part|panel|fitting|step)\s+([A-Za-z0-9]{1,4})\]/gi;++/** An answer's words with its picture tags taken out, and the pictures they ask for (three at most). */+export function readAnswer(raw: string, plan: Plan, done = true) {+ const shows: Show[] = [];+ const add = (x: Show | null) => {+ if (!x || shows.length >= 3) return;+ if (shows.some((y) => y.kind === x.kind && (y.kind === "step" ? y.index === (x as { index: number }).index : y.id === (x as { id: string }).id))) return;+ shows.push(x);+ };+ const partOf = (ref: string): Show | null => {+ const p = plan.parts.find((p) => !p.extra && p.label.toUpperCase() === ref.toUpperCase());+ return p ? { kind: "part", id: p.id } : null;+ };+ const stepOf = (ref: string): Show | null => {+ const n = Number(ref);+ return Number.isInteger(n) && n >= 1 && n <= plan.steps.length ? { kind: "step", index: n - 1 } : null;+ };+ let tagged = false;+ let text = raw.replace(TAG, (_, kind: string, ref: string) => {+ tagged = true;+ const k = kind.toLowerCase();+ if (k === "part" || k === "panel") add(partOf(ref));+ else if (k === "step") add(stepOf(ref));+ else {+ const h = plan.hardware[Number(ref) - 1];+ add(h ? { kind: "fit", id: h.id } : null);+ }+ return "";+ });+ // a tag still arriving isn't shown half written+ if (!done) text = text.replace(/\[[^\]\n]{0,24}$/, "");+ text = text.replace(/[ \t]+\n/g, "\n").replace(/[ \t]{2,}/g, " ").replace(/\n{3,}/g, "\n\n").replace(/[ \t]+([.,!?])/g, "$1").trim();+ // an answer that names a panel or a step without tagging it still gets its picture+ if (done && !tagged) {+ for (const m of text.matchAll(/\b(?:part|panel)\s+([A-Z])\b/g)) add(partOf(m[1]));+ for (const m of text.matchAll(/\bstep\s+(\d{1,3})\b/gi)) add(stepOf(m[1]));}- lines.push("All panels: " + plan.parts.filter((p) => !p.extra).map((p) => `${p.label} ${p.name} x${p.qty}`).join(", "));- lines.push("All hardware: " + plan.hardware.map((h) => `${h.name} ${h.spec} x${h.qty}${h.notIncluded ? " (not included)" : ""}`).join(", "));- return lines.join("\n");+ return { text, shows };}async function shrink(file: File): Promise<string> {@@ -62,9 +118,13 @@ export default function HelpSheet({ask: asked,askId,onAnswer,+ onAddKey,+ onShow,+ onGoto,}: {plan: Plan;index: number;+ /** A key is saved: asking works. Without one, asking opens the key modal and the question waits for it. */ai: boolean;onClose: () => void;focusMissing?: boolean;@@ -73,6 +133,11 @@ export default function HelpSheet({askId?: number;/** Hears each finished answer, to read it aloud. */onAnswer?: (text: string) => void;+ onAddKey?: (why: KeyWhy, trouble?: KeyTrouble) => void;+ /** Lights up a part or fitting on the drawing behind, while its picture is pointed at. */+ onShow?: (ids: string[] | null) => void;+ /** Goes to a step an answer points at. */+ onGoto?: (index: number) => void;}) {const kind = index >= 0 ? plan.steps[index].kind : "general";const faqs = faqFor(kind);@@ -95,6 +160,18 @@ export default function HelpSheet({return () => window.removeEventListener("keydown", onKey);}, [onClose]);+ // asked before there was a key: it goes as soon as one is saved+ const pending = useRef<{ q: string; image?: string } | null>(null);+ useEffect(() => {+ if (!ai || !pending.current) return;+ const p = pending.current;+ pending.current = null;+ const t = setTimeout(() => ask(p.q, p.image), 0);+ return () => clearTimeout(t);+ // eslint-disable-next-line react-hooks/exhaustive-deps+ }, [ai]);+ useEffect(() => () => onShow?.(null), [onShow]);+// a question asked by voice goes straight in, every time one is askedconst sent = useRef<number | undefined>(undefined);useEffect(() => {@@ -117,10 +194,17 @@ export default function HelpSheet({async function ask(question: string, image?: string, spoken = false) {if ((busy && !spoken) || (!question.trim() && !image)) return;+ if (!ai) {+ pending.current = { q: question, image };+ setQ("");+ onAddKey?.("ask");+ return;+ }ctrl.current?.abort();const c = new AbortController();ctrl.current = c;- const history = msgs.map((m) => ({ role: m.role, content: m.content }));+ // answers that never came aren't part of the conversation+ const history = msgs.filter((m) => !m.error && m.content).map((m) => ({ role: m.role, content: m.content }));const next: Msg[] = [...msgs, { role: "user", content: question || "Which part is this?", image }, { role: "assistant", content: "" }];setMsgs(next);setQ("");@@ -132,6 +216,7 @@ export default function HelpSheet({body: JSON.stringify({ context: helpContext(plan, index), question: question || "Which part is this? Match it to the parts list.", history, image }),signal: c.signal,});+ if (res.status === 401 || res.status === 402) throw new Error(res.status === 401 ? "key" : "credits");if (!res.ok || !res.body) throw new Error(String(res.status));const reader = res.body.getReader();const dec = new TextDecoder();@@ -147,12 +232,23 @@ export default function HelpSheet({});}if (!text.trim()) throw new Error("empty");- if (!c.signal.aborted) onAnswer?.(text);- } catch {+ if (!c.signal.aborted) onAnswer?.(readAnswer(text, plan).text);+ } catch (e) {if (c.signal.aborted) return;+ const why = (e as Error).message;+ const error: Msg["error"] = why === "key" || why === "credits" ? why : "failed";setMsgs((m) => {const c = [...m];- c[c.length - 1] = { role: "assistant", content: "I couldn't reach the helper just now. Try the quick answers above, or ask again in a moment." };+ c[c.length - 1] = {+ role: "assistant",+ error,+ content:+ error === "key"+ ? "Together turned your key away, so I couldn't answer."+ : error === "credits"+ ? "Your Together credit ran out, so I couldn't answer."+ : "I couldn't reach the helper just now. Try the quick answers above, or ask again in a moment.",+ };return c;});} finally {@@ -205,70 +301,134 @@ export default function HelpSheet({</div>{index >= 0 && <Report plan={plan} index={index} />}- {ai && (+ <div className="ask-head">+ <ISparkle size={18} />+ <b>Ask about this step</b>+ <button className="ask-key" onClick={() => onAddKey?.(ai ? "key" : "ask")}>+ <IKey size={13} /> {ai ? "Your key" : "Add your key"}+ </button>+ </div>+ {msgs.length === 0 && (<>- <div className="ask-head">- <ISparkle size={18} />- <b>Ask about this step</b>- <span className="muted">Answers by Together AI</span>- </div>- {msgs.length === 0 && (- <div className="ask-suggest">- {["Which way round does this go?", "Which screw goes where?", "Is it normal to have parts left over?"].map((s) => (- <button key={s} className="chip" onClick={() => ask(s)}>- {s}- </button>- ))}- </div>- )}- <div className="msgs">- {msgs.map((m, i) => (- <motion.div key={i} className={"msg " + m.role} initial={{ opacity: 0, y: 8 }} animate={{ opacity: 1, y: 0 }}>- {/* eslint-disable-next-line @next/next/no-img-element */}- {m.image && <img src={m.image} alt="Your photo" />}- {m.content ? <p>{m.content}</p> : <span className="typing">Thinking</span>}- </motion.div>+ <div className="ask-suggest">+ {["What do I do here?", "Which screw goes where?", "Which way round does this go?"].map((s) => (+ <button key={s} className="chip" onClick={() => ask(s)}>+ {s}+ </button>))}</div>+ <p className="ask-note">{ai ? "Answers come with pictures of the parts. Snap a part to ask which one it is." : "Answers come with pictures of the parts. Runs on your own Together AI key, about a cent a build."}</p></>)}+ <div className="msgs">+ {msgs.map((m, i) => {+ const last = i === msgs.length - 1;+ const a = m.role === "assistant" && !m.error ? readAnswer(m.content, plan, !(busy && last)) : null;+ return (+ <motion.div key={i} className={"msg " + m.role + (m.error ? " err" : "") + (a?.shows.length ? " pics" : "")} initial={{ opacity: 0, y: 8 }} animate={{ opacity: 1, y: 0 }}>+ {/* eslint-disable-next-line @next/next/no-img-element */}+ {m.image && <img src={m.image} alt="Your photo" />}+ {a ? a.text ? <p>{a.text}</p> : busy && last ? <span className="typing">Thinking</span> : null : <p>{m.content}</p>}+ {a && a.shows.length > 0 && <Pictures plan={plan} index={index} shows={a.shows} onShow={onShow} onGoto={onGoto} />}+ {m.error === "key" && (+ <button className="msg-fix" onClick={() => onAddKey?.("key", "key")}>+ <IKey size={14} /> Fix your key+ </button>+ )}+ {m.error === "credits" && (+ <a className="msg-fix" href="https://api.together.ai/settings/billing" target="_blank" rel="noreferrer">+ Add credit <IExternal size={12} />+ </a>+ )}+ </motion.div>+ );+ })}+ </div></div>- {ai && (- <form- className="ask-bar"- onSubmit={(e) => {- e.preventDefault();- ask(q);+ <form+ className="ask-bar"+ onSubmit={(e) => {+ e.preventDefault();+ ask(q);+ }}+ >+ <button type="button" className="btn round small" onClick={() => file.current?.click()} disabled={busy} aria-label="Which part is this? Take a photo" title="Which part is this?">+ <ICamera />+ </button>+ <input ref={inputRef} value={q} onChange={(e) => setQ(e.target.value)} placeholder="Type your question" aria-label="Your question" />+ <button type="submit" className="btn round small primary" disabled={busy || !q.trim()} aria-label="Send">+ <ISend />+ </button>+ <input+ ref={file}+ type="file"+ accept="image/*"+ capture="environment"+ hidden+ onChange={async (e) => {+ const f = e.target.files?.[0];+ e.target.value = "";+ if (!f) return;+ const img = await shrink(f);+ ask("Which part is this?", img);}}- >- <button type="button" className="btn round small" onClick={() => file.current?.click()} disabled={busy} aria-label="Which part is this? Take a photo" title="Which part is this?">- <ICamera />- </button>- <input ref={inputRef} value={q} onChange={(e) => setQ(e.target.value)} placeholder="Type your question" aria-label="Your question" />- <button type="submit" className="btn round small primary" disabled={busy || !q.trim()} aria-label="Send">- <ISend />- </button>- <input- ref={file}- type="file"- accept="image/*"- capture="environment"- hidden- onChange={async (e) => {- const f = e.target.files?.[0];- e.target.value = "";- if (!f) return;- const img = await shrink(f);- ask("Which part is this?", img);- }}- />- </form>- )}+ />+ </form></motion.aside></motion.div>);}+/** What an answer points at, drawn from this guide: the panel, the fitting, the step. */+function Pictures({ plan, index, shows, onShow, onGoto }: { plan: Plan; index: number; shows: Show[]; onShow?: (ids: string[] | null) => void; onGoto?: (index: number) => void }) {+ const id = plan.spec.name + plan.spec.variant;+ return (+ <div className="msg-pics">+ {shows.map((x) => {+ if (x.kind === "step") {+ const st = plan.steps[x.index];+ const here = x.index === index;+ return (+ <button key={"s" + x.index} className="pic step" disabled={here || !onGoto} onClick={() => onGoto?.(x.index)} aria-label={here ? `Step ${x.index + 1}, this step` : `Go to step ${x.index + 1}: ${st.title}`}>+ <Thumb id={id} plan={plan} mode={{ kind: "step", index: x.index }} w={260} h={190} className="pic-thumb" />+ <span className="pic-cap">+ <b>{here ? "This step" : `Step ${x.index + 1}`}</b>+ <span>{st.title}</span>+ </span>+ </button>+ );+ }+ if (x.kind === "part") {+ const p = plan.parts.find((p) => p.id === x.id)!;+ return (+ <figure key={"p" + p.id} className="pic" onMouseEnter={() => onShow?.([p.id])} onMouseLeave={() => onShow?.(null)}>+ <Thumb id={id} plan={plan} mode={{ kind: "part", ref: p.id }} w={260} h={190} className="pic-thumb" />+ <figcaption className="pic-cap">+ <b>+ <span className="letter sm">{p.label}</span> {p.name}+ </b>+ <span>{p.qty} in the box</span>+ </figcaption>+ </figure>+ );+ }+ const h = plan.hardware.find((h) => h.id === x.id)!;+ return (+ <figure key={"h" + h.id} className="pic fit" onMouseEnter={() => onShow?.([h.id])} onMouseLeave={() => onShow?.(null)}>+ <span className="pic-art">+ <HwArt kind={h.kind} len={h.len} dia={h.dia} fit={76} />+ </span>+ <figcaption className="pic-cap">+ <b>{h.notIncluded ? (h.kind === "plug" ? "Wall plug" : "Wall screw") : h.name}</b>+ <span>{h.notIncluded ? "Not in the box" : [h.spec, `${h.qty} in the box`].filter(Boolean).join(", ")}</span>+ </figcaption>+ </figure>+ );+ })}+ </div>+ );+}+/** "This step doesn't match my box": goes to /api/feedback so wrong steps get fixed. */function Report({ plan, index }: { plan: Plan; index: number }) {const [sent, setSent] = useState(false);diff --git a/src/components/guide/StepPanel.tsx b/src/components/guide/StepPanel.tsxindex 8630e62..55b5133 100644--- a/src/components/guide/StepPanel.tsx+++ b/src/components/guide/StepPanel.tsx@@ -1,13 +1,15 @@"use client";-import { motion } from "motion/react";+import { useEffect, useState } from "react";+import { AnimatePresence, motion } from "motion/react";import type { Plan, WarnId } from "@/lib/types";import { stepContents, tipFor } from "@/lib/plan/contents";import { HwArt } from "../art/Hardware";import { ToolArt, TOOL_INFO } from "../art/Tools";-import { IArrowLeft, IArrowRight, ICheck, IClock, IClose, IHelp, IMic, ISparkle, WarnIcon, WARN_TEXT } from "../art/Icons";+import { IArrowLeft, IArrowRight, ICheck, IClock, IClose, IMic, ISparkle, WarnIcon, WARN_TEXT } from "../art/Icons";import { TwoPeople } from "../art/Figure";import Thumb from "../Thumb";+import { getPref, setPref } from "@/lib/store";export function minutesLeft(plan: Plan, index: number) {return plan.steps.slice(index).reduce((s, x) => s + x.minutes, 0);@@ -20,7 +22,6 @@ export default function StepPanel({onNext,onBack,onHover,- onHelp,offer,}: {plan: Plan;@@ -29,7 +30,6 @@ export default function StepPanel({onNext: () => void;onBack: () => void;onHover: (ids: string[] | null) => void;- onHelp: () => void;/** Invite to turn voice on, while it is off. */offer?: { again: boolean; listen: boolean; onStart: () => void; onDismiss: () => void } | null;}) {@@ -190,6 +190,7 @@ export default function StepPanel({</motion.div></div><div className="pane-foot">+ <KeysTip /><button className="btn round" onClick={onBack} aria-label="Previous step" title="Previous (left arrow)"><IArrowLeft /></button>@@ -200,16 +201,56 @@ export default function StepPanel({<span className="done-label">{last ? "Done, finish up" : "Done, next step"}</span><IArrowRight /></button>- <div className="foot-row">- <button className="btn link stuck" onClick={onHelp}>- <IHelp size={16} /> Stuck?- </button>- <span className="kbd-hint" aria-hidden="true">- <kbd>←</kbd>- <kbd>→</kbd> to move, <kbd>R</kbd> to replay- </span>- </div></div></div>);}++/**+ * The keyboard shortcuts, once: a tip over the Done button on a first visit+ * with a keyboard and mouse. Closing it, or using the keys, puts it away for good.+ */+function KeysTip() {+ const [show, setShow] = useState(false);+ useEffect(() => {+ if (getPref("keysTip", false) || !matchMedia("(hover: hover) and (pointer: fine) and (min-width: 901px)").matches) return;+ const t = setTimeout(() => setShow(true), 1200);+ const onKey = (e: KeyboardEvent) => {+ if (e.metaKey || e.ctrlKey || e.altKey || !(e.key === "ArrowLeft" || e.key === "ArrowRight" || e.key.toLowerCase() === "r")) return;+ const t = e.target as HTMLElement;+ if (t?.tagName === "INPUT" || t?.tagName === "TEXTAREA") return;+ setPref("keysTip", true);+ setShow(false);+ };+ window.addEventListener("keydown", onKey);+ return () => {+ clearTimeout(t);+ window.removeEventListener("keydown", onKey);+ };+ }, []);+ return (+ <AnimatePresence>+ {show && (+ <motion.div className="keys-tip" role="note" initial={{ opacity: 0, y: 8, scale: 0.97 }} animate={{ opacity: 1, y: 0, scale: 1 }} exit={{ opacity: 0, y: 4 }} transition={{ type: "spring", stiffness: 460, damping: 32 }}>+ <span>+ <kbd aria-label="Left arrow">←</kbd>+ <kbd aria-label="Right arrow">→</kbd> to move+ </span>+ <span>+ <kbd>R</kbd> to replay+ </span>+ <button+ className="keys-tip-x"+ onClick={() => {+ setPref("keysTip", true);+ setShow(false);+ }}+ aria-label="Got it, hide this tip"+ >+ <IClose size={14} />+ </button>+ </motion.div>+ )}+ </AnimatePresence>+ );+}diff --git a/src/components/guide/hooks.ts b/src/components/guide/hooks.tsindex ac2be0c..ece809e 100644--- a/src/components/guide/hooks.ts+++ b/src/components/guide/hooks.ts@@ -31,7 +31,7 @@ export function useWakeLock(active: boolean) {}, [active]);}-export type Mic = "off" | "asking" | "on" | "paused" | "denied" | "busy" | "nomic" | "unsupported" | "offline";+export type Mic = "off" | "asking" | "on" | "paused" | "denied" | "busy" | "nomic" | "unsupported" | "offline" | "refused" | "credits";type Ctx = typeof AudioContext;const AudioCtx = () => (typeof window === "undefined" ? undefined : (window.AudioContext ?? (window as unknown as { webkitAudioContext?: Ctx }).webkitAudioContext));@@ -64,8 +64,10 @@ export function primeListening() {* piece's times so her own words can be told apart. onHeard returns what it* acted on, to show as "Heard ...", or null. `her` says whether the voice is* playing, so what's left of her in the mic isn't taken for someone talking.+ * It runs on the person's own key: a new key (or a new `key` token, after a+ * top-up) starts it afresh.*/-export function useListener(enabled: boolean, onHeard: (text: string, seg: Segment) => string | null, her: () => boolean) {+export function useListener(enabled: boolean, key: string, onHeard: (text: string, seg: Segment) => string | null, her: () => boolean) {const cb = useRef(onHeard);const herRef = useRef(her);useEffect(() => {@@ -87,6 +89,8 @@ export function useListener(enabled: boolean, onHeard: (text: string, seg: Segmelet tries = 0;let fails = 0;let inflight = 0;+ // a key turned away, or an account out of credit, fails every piece the same way: stop sending+ let dead = false;// a piece that overlaps one already acted on can't act againlet acted = 0;let cut = segmenter();@@ -94,11 +98,18 @@ export function useListener(enabled: boolean, onHeard: (text: string, seg: Segmeconst send = async (seg: Segment) => {// a noisy room: drop a piece rather than queue it behind others- if (inflight >= 3) return;+ if (inflight >= 3 || dead) return;inflight++;try {const r = await fetch("/api/listen", { method: "POST", headers: { "Content-Type": "audio/wav", ...keyHeaders() }, body: toWav(seg.pcm), signal: AbortSignal.timeout(9000) });if (stop) return;+ if (r.status === 401 || r.status === 402) {+ // nothing more will be heard on this key: the mic goes off too, so no recording light stays on for nothing+ dead = true;+ release();+ setMic(r.status === 401 ? "refused" : "credits");+ return;+ }if (!r.ok) throw new Error(String(r.status));const text = String(((await r.json()) as { text?: unknown }).text ?? "");fails = 0;@@ -111,7 +122,7 @@ export function useListener(enabled: boolean, onHeard: (text: string, seg: SegmeclearTimeout(clear);clear = setTimeout(() => setHeard(""), 2400);} catch {- if (!stop && ++fails >= 3) setMic("offline");+ if (!stop && !dead && ++fails >= 3) setMic("offline");} finally {inflight--;}@@ -148,7 +159,7 @@ export function useListener(enabled: boolean, onHeard: (text: string, seg: Segme};const open = async () => {- if (stop || stream || hidden()) return;+ if (stop || dead || stream || hidden()) return;// only say "allow the mic" when the browser is actually askingasking = setTimeout(() => setMic((m) => (m === "on" ? m : "asking")), 500);let s: MediaStream;@@ -205,13 +216,14 @@ export function useListener(enabled: boolean, onHeard: (text: string, seg: Segmetap.connect(sink);nodes = [src, tap, sink];cut = segmenter();+ if (dead) return;if (ctx.state === "running") setMic("on");else {setMic("paused");unwake();wake = () => {unwake();- ctx.resume().then(() => !stop && stream === s && setMic(ctx.state === "running" ? "on" : "paused"), () => {});+ ctx.resume().then(() => !stop && !dead && stream === s && setMic(ctx.state === "running" ? "on" : "paused"), () => {});};document.addEventListener("pointerdown", wake);}@@ -241,7 +253,7 @@ export function useListener(enabled: boolean, onHeard: (text: string, seg: Segmerelease();setMic("off");};- }, [enabled]);+ }, [enabled, key]);if (!enabled) return { mic: "off" as Mic, heard: "" };return { mic: micSupported() ? mic : ("unsupported" as Mic), heard };diff --git a/src/components/guide/voice.ts b/src/components/guide/voice.tsindex 37dd662..396347c 100644--- a/src/components/guide/voice.ts+++ b/src/components/guide/voice.ts@@ -2,11 +2,12 @@import { VOICE_DIR, clipId } from "@/lib/voice/script";import { canon, type Said } from "@/lib/voice/commands";+import { keyHeaders } from "@/lib/userKey";/*** Plays the hands-free voice. Lines with a pre-recorded clip play from* /voice; other lines (scanned guides, spoken answers) are recorded live in- * the same voice when the server allows it. A line that can't be played in+ * the same voice, on the person's own key when they've added one. A line that can't be played in* that voice is skipped (it is on screen anyway): the device's own voice is* never used, so the guide only ever has one voice.*@@ -38,7 +39,7 @@ class Voice {private ended = 0;/** Live lines, fetched whole so they can load ahead and play without gaps. */private fetched = new Map<string, Promise<string | null>>();- /** The server can record lines that have no clip. */+ /** Lines with no clip can be recorded live: there's a key to record them on. */live = false;rate = 1;@@ -79,7 +80,7 @@ class Voice {const t = text.trim();let p = this.fetched.get(t);if (!p) {- p = fetch(`/api/voice?t=${encodeURIComponent(t)}`, { signal: AbortSignal.timeout(10_000) })+ p = fetch(`/api/voice?t=${encodeURIComponent(t)}`, { headers: keyHeaders(), signal: AbortSignal.timeout(10_000) }).then((r) => (r.ok ? r.blob() : null)).then((b) => (b && b.size ? URL.createObjectURL(b) : null)).catch(() => null)@@ -102,6 +103,12 @@ class Voice {return c ? Promise.resolve(c.src) : this.live ? this.liveSrc(text) : Promise.resolve(null);}+ /** Whether any of these lines can be played: a clip, or a key to record it live. */+ async readable(lines: string[]) {+ await this.load();+ return lines.some((l) => this.has(l));+ }+subscribe(fn: Listener) {this.listeners.add(fn);return () => void this.listeners.delete(fn);diff --git a/src/components/home/Search.tsx b/src/components/home/Search.tsxindex 0ad4a87..a1b7547 100644--- a/src/components/home/Search.tsx+++ b/src/components/home/Search.tsx@@ -7,6 +7,7 @@ import { articleNo, articlesReady, loadArticles, searchCatalog, slugify, matchCaimport Drawing from "../Drawing";import { keyHeaders } from "@/lib/userKey";import { IArrowRight, ICamera, ISearch, ISparkle } from "../art/Icons";+import KeyModal, { type KeyTrouble } from "../KeyModal";const EXAMPLES = ["KALLAX", "MALM 3 drawers", "802.758.87", "BILLY bookcase", "LACK side table", "HEMNES chest", "IDÅSEN desk"];@@ -18,6 +19,8 @@ export default function Search({ ai, autoFocus }: { ai: boolean; autoFocus?: booconst [ph, setPh] = useState("");const [reading, setReading] = useState(false);const [msg, setMsg] = useState("");+ // photo search runs on the person's own key: without one, the camera asks for it first+ const [askKey, setAskKey] = useState<KeyTrouble | "" | null>(null);const input = useRef<HTMLInputElement>(null);const file = useRef<HTMLInputElement>(null);@@ -88,6 +91,10 @@ export default function Search({ ai, autoFocus }: { ai: boolean; autoFocus?: booconst img = await shrink(f);const r = await fetch("/api/identify", { method: "POST", headers: { "Content-Type": "application/json", ...keyHeaders() }, body: JSON.stringify({ image: img }) });const j = await r.json();+ if (r.status === 401 || r.status === 402) {+ setAskKey(r.status === 401 ? "key" : "credits");+ return;+ }if (!r.ok) throw new Error(j.error);if (j.name) {setQ(j.query || j.name);@@ -95,7 +102,7 @@ export default function Search({ ai, autoFocus }: { ai: boolean; autoFocus?: boosetTimeout(() => go(j.query || j.name), 650);} else setMsg("Couldn't read a name. Try a closer photo of the label.");} catch {- setMsg(ai ? "Couldn't read that photo. Try again or type the name." : "Photo search needs Together AI on the server.");+ setMsg("Couldn't read that photo. Try again or type the name.");} finally {setReading(false);}@@ -140,7 +147,7 @@ export default function Search({ ai, autoFocus }: { ai: boolean; autoFocus?: booautoFocus={autoFocus}enterKeyHint="go"/>- <button type="button" className={"cam-btn" + (reading ? " busy" : "")} onClick={() => file.current?.click()} aria-label="Search with a photo of the box label" title="Snap the box label">+ <button type="button" className={"cam-btn" + (reading ? " busy" : "")} onClick={() => (ai ? file.current?.click() : setAskKey(""))} aria-label="Search with a photo of the box label" title="Snap the box label"><ICamera size={22} /></button><button type="submit" className="go-btn" aria-label="Find assembly steps">@@ -160,6 +167,19 @@ export default function Search({ ai, autoFocus }: { ai: boolean; autoFocus?: boo/></form><AnimatePresence>{msg && <motion.p className="search-msg" initial={{ opacity: 0, y: -4 }} animate={{ opacity: 1, y: 0 }} exit={{ opacity: 0 }}>{msg}</motion.p>}</AnimatePresence>+ <AnimatePresence>+ {askKey !== null && (+ <KeyModal+ why="photo"+ trouble={askKey || null}+ onClose={() => setAskKey(null)}+ onSaved={() => {+ setAskKey(null);+ setMsg("Key saved. Tap the camera to snap the label.");+ }}+ />+ )}+ </AnimatePresence><AnimatePresence>{open && (<motion.ul className="suggest" role="listbox" initial={{ opacity: 0, y: -6, scale: 0.99 }} animate={{ opacity: 1, y: 0, scale: 1 }} exit={{ opacity: 0, y: -6 }} transition={{ duration: 0.18 }}>diff --git a/src/components/home/Sections.tsx b/src/components/home/Sections.tsxindex 557374d..910fefb 100644--- a/src/components/home/Sections.tsx+++ b/src/components/home/Sections.tsx@@ -9,7 +9,7 @@ import { PRODUCTS, type CatalogEntry } from "@/lib/catalog";import { KIND_ARCH, type Kind } from "@/lib/products";import type { Archetype } from "@/lib/types";import Drawing from "../Drawing";-import { getUserKey } from "@/lib/userKey";+import { useUserKey } from "@/lib/userKey";import { Dots } from "../guide/ui";import { IArrowRight, IClock, IClose, ISearch } from "../art/Icons";@@ -183,13 +183,7 @@ export function Catalog({ limit, search }: { limit?: number; search?: boolean }));}+/** AI features run on the person's own key: they're on once one is saved. */export function useAiStatus() {- const [ai, setAi] = useState(false);- useEffect(() => {- fetch("/api/status")- .then((r) => r.json())- .then((j) => setAi(!!j.ai || !!getUserKey()))- .catch(() => {});- }, []);- return ai;+ return !!useUserKey();}diff --git a/src/lib/draft.ts b/src/lib/draft.tsdeleted file mode 100644index 411acad..0000000--- a/src/lib/draft.ts+++ /dev/null@@ -1,33 +0,0 @@-import "server-only";-import { cacheLife } from "next/cache";-import { parseSpec, SPEC_PROMPT } from "./spec";-import { chatText, extractJson, MODELS } from "./together";-import type { ProductSpec } from "./types";--export type Draft = { spec: ProductSpec; model: string } | { found: false; suggestions: string[] };--/**- * Asks the model what a product name is, on the server key. Shared by every- * server instance and kept for good, so each name is only paid for once and- * the second person to ask gets it instantly. Failures throw and aren't kept.- */-/** `key` is the folded name (and IKEA's type for it), so every spelling of a name shares one entry; `q` is what the model reads. */-export async function draft(key: string, q: string): Promise<Draft | null> {- "use cache: remote";- cacheLife("max");- void key;- const { text, model } = await chatText({- models: MODELS.text,- json: true,- maxTokens: 1800,- temperature: 0.2,- messages: [- { role: "system", content: SPEC_PROMPT },- { role: "user", content: q },- ],- });- const raw = extractJson(text) as { found?: boolean; suggestions?: string[] } | null;- if (raw && raw.found === false) return { found: false, suggestions: (raw.suggestions ?? []).slice(0, 3) };- const spec = parseSpec(raw);- return spec ? { spec, model } : null;-}diff --git a/src/lib/store.ts b/src/lib/store.tsindex 0f3eb69..116cd04 100644--- a/src/lib/store.ts+++ b/src/lib/store.ts@@ -88,6 +88,13 @@ export function cacheSpec(slug: string, spec: ProductSpec) {/* ignore */}}+export function uncacheSpec(slug: string) {+ try {+ localStorage.removeItem(SPEC_KEY + slug);+ } catch {+ /* ignore */+ }+}export function cachedSpec(slug: string): ProductSpec | null {try {const s = localStorage.getItem(SPEC_KEY + slug);diff --git a/src/lib/together.ts b/src/lib/together.tsindex a6fbbf9..df0c1de 100644--- a/src/lib/together.ts+++ b/src/lib/together.ts@@ -17,10 +17,6 @@ function list(env: string | undefined, fallback: string) {return (env?.trim() || fallback).split(",").map((m) => m.trim()).filter(Boolean);}-export function hasKey() {- return !!process.env.TOGETHER_API_KEY?.trim();-}-type Content = string | ({ type: "text"; text: string } | { type: "image_url"; image_url: { url: string } })[];export interface Msg {role: "system" | "user" | "assistant";@@ -35,10 +31,8 @@ interface ChatOpts {temperature?: number;stream?: boolean;signal?: AbortSignal;- /** The person's own key. Falls back to the server key, unless `fallback` is false. */- key?: string;- /** False for calls that must only ever spend the person's own credit. */- fallback?: boolean;+ /** The person's own key: every call runs on it, and there is no other. */+ key: string;reasoning?: "low" | "medium" | "high";}@@ -53,22 +47,8 @@ export class TogetherError extends Error {/** Calls Together's chat completions, falling back through the model list when one is unavailable. */export async function chat(o: ChatOpts): Promise<{ res: Response; model: string }> {- // a visitor's saved key can expire: the server key takes over when it is turned away- const keys = [...new Set([o.key?.trim(), o.fallback === false ? undefined : process.env.TOGETHER_API_KEY?.trim()].filter((k): k is string => !!k))];- if (!keys.length) throw new TogetherError("missing key", 401);- let lastErr: TogetherError | null = null;- for (const key of keys) {- try {- return await chatWith(o, key);- } catch (e) {- lastErr = e as TogetherError;- if (!(e instanceof TogetherError) || (e.status !== 401 && e.status !== 403)) throw e;- }- }- throw lastErr!;-}--async function chatWith(o: ChatOpts, key: string): Promise<{ res: Response; model: string }> {+ const key = o.key?.trim();+ if (!key) throw new TogetherError("missing key", 401);let lastErr: TogetherError | null = null;for (const model of o.models.map((m) => m.trim()).filter(Boolean)) {const reasoning = model.includes("gpt-oss") ? { reasoning_effort: o.reasoning ?? "low" } : {};@@ -150,12 +130,25 @@ export function rateLimited(bucket: string, max = 20, windowMs = 60_000) {return false;}-/** A key the person pasted into the app, sent along with their request. Never stored or logged. */+/** Only for trying the app locally: stands in for the key in .env.local. Never accepted in production. */+export const DEV_KEY = "bygga-dev-mock-key-000000";++export function isDevKey(req: Request) {+ return process.env.NODE_ENV !== "production" && req.headers.get("x-together-key")?.trim() === DEV_KEY;+}++/** The key the person pasted into the app, sent along with each request. Never stored or logged, and the only key any AI call runs on. */export function userKey(req: Request) {+ if (isDevKey(req)) return process.env.TOGETHER_API_KEY?.trim() || undefined;const k = req.headers.get("x-together-key")?.trim() ?? "";return k.length >= 20 && k.length <= 200 && /^[\w.-]+$/.test(k) ? k : undefined;}+/** What a turned-away call tells the person: their key was refused, or their account is out of credit. */+export function keyTrouble(status: number) {+ return status === 401 || status === 403 ? "key" : status === 402 ? "credits" : null;+}+/*** True for requests from this site's own pages. Other sites can't make their visitors'* browsers spend the key: browsers say where a request came from, and a JSON bodydiff --git a/src/lib/userKey.ts b/src/lib/userKey.tsindex 2c318c2..6ad5ae7 100644--- a/src/lib/userKey.ts+++ b/src/lib/userKey.ts@@ -1,6 +1,8 @@"use client";-/** The person's own Together AI key. It lives only in this browser and rides along with AI requests. */+import { useSyncExternalStore } from "react";++/** The person's own Together AI key. It lives only in this browser and rides along with AI requests: every AI feature runs on it. */const K = "bygga:together-key";export function getUserKey(): string {@@ -34,3 +36,11 @@ export function subscribeKey(cb: () => void) {window.removeEventListener("storage", cb);};}++/** The saved key, kept in step across tabs; "" until the page is in the browser. */+export function useUserKey() {+ return useSyncExternalStore(subscribeKey, getUserKey, () => "");+}++/** Where to make a key. */+export const KEY_URL = "https://api.together.ai/settings/api-keys";diff --git a/src/lib/voice/tts.ts b/src/lib/voice/tts.tsindex 88874dd..cd137dd 100644--- a/src/lib/voice/tts.ts+++ b/src/lib/voice/tts.ts@@ -22,7 +22,7 @@ export function forTTS(text: string) {return t;}-/** Renders one line to mp3. The key is the server's, never the visitor's. */+/** Renders one line to mp3: on the person's own key live, on the recording script's key for the clips. */export async function speak(text: string, key: string) {const r = await fetch("https://api.together.ai/v1/audio/speech", {method: "POST",