@vibes.diy/prompts 14.3.168 → 14.3.173

package/llms/stripe-subscriptions.md

@@ -28,29 +28,49 @@ one-merchant half.
 
 ## 1. Bring your own Stripe key, turn on the portal, and explain how
 
-The owner sets up Stripe once:
-
-1. Open the Stripe dashboard and sign in (or create a Stripe account). Turn on
-   **Test mode** until the app is working.
-2. Go to Developers, then API keys, and reveal the **Secret key**. Set it on
-   the vibe as `STRIPE_SECRET_KEY` — the vibe's settings page, or
-   `vibes-diy secrets set STRIPE_SECRET_KEY <the key>`.
-3. Go to Settings, then Billing, then **Customer portal**, and save it with
-   **Cancel at end of billing period** on. The app sends members there to
-   cancel or change a card, and the portal does not exist until it is saved
-   once.
-4. To go live, repeat steps 2 and 3 with Test mode off.
+The owner sets up Stripe once. The steps are written for someone who has never
+opened Stripe, so each one is a link to the exact page and uses the words that
+page uses:
+
+1. Open Stripe's **API keys** page in test mode:
+   <https://dashboard.stripe.com/test/apikeys> (sign in, or create a Stripe
+   account when it asks). Under **Standard keys**, press **Reveal test key**
+   beside **Secret key** and copy it. It starts with `sk_test_`.
+2. Open this vibe's **Settings** tab on vibes.diy:
+   `https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings` (that is
+   **My Vibes** → this vibe → **Settings**). Under **Secrets**, enter the key
+   `STRIPE_SECRET_KEY` and paste the value, then save. From a terminal the
+   same thing is `npx vibes-diy secrets set STRIPE_SECRET_KEY --vibe <ownerHandle>/<appSlug>`.
+3. Open Stripe's **Customer portal** settings in test mode:
+   <https://dashboard.stripe.com/test/settings/billing/portal>. Under
+   **Cancellations**, turn on **Cancel subscriptions** and choose **At end of
+   billing period**, then press **Save**. The app sends members there to cancel
+   or change a card, and the portal does not exist until it is saved once.
+4. To go live, take the **live** secret key from
+   <https://dashboard.stripe.com/apikeys> (**Reveal live key**, `sk_live_`),
+   set it the same way, and save the portal once more at
+   <https://dashboard.stripe.com/settings/billing/portal>.
 
 The app carries those steps in its own UI, because the person reading them is
-the person who has to do them.
+the person who has to do them — and it fills in the vibe's real handle and
+slug, which the backend knows as `ctx.appInfo`, so the Settings link and the
+terminal command are copy-ready rather than templates. The Settings tab opens
+in another tab, so the app re-reads `/status` whenever it regains focus or
+becomes visible again: the owner saves the key, comes back, and the card gives
+way to the Join buttons without a reload.
 
-When the key is missing, the app shows the owner the setup steps for a Stripe secret key and the Customer Portal instead of an error.
+When the key is missing, the app shows the owner the setup steps for a Stripe secret key and the Customer Portal instead of an error, and the steps link to Stripe's API keys page, Stripe's Customer portal settings and this vibe's own Settings tab by URL.
 
 The backend answers `{ ok: false, reason: "missing-key" }` when
-`ctx.secrets.STRIPE_SECRET_KEY` is absent, and the client renders the numbered
-steps, naming the Stripe dashboard, `STRIPE_SECRET_KEY` and the Customer Portal
-in so many words. A visitor who is not the owner sees a calmer sentence —
-memberships are not open yet — never the steps. A portal that was never saved
+`ctx.secrets.STRIPE_SECRET_KEY` is absent, and `/status` carries
+`ownerHandle` and `appSlug` so the client can render the numbered steps
+with real links: `https://dashboard.stripe.com/test/apikeys` for the key,
+`https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings` for where
+it goes, `https://dashboard.stripe.com/test/settings/billing/portal` for the
+portal, and `STRIPE_SECRET_KEY` in so many words. "Open the Stripe dashboard"
+and "the Settings page" are not instructions; a person who has never seen
+either would have to search for both. A visitor who is not the owner sees a
+calmer sentence — memberships are not open yet — never the steps. A portal that was never saved
 answers a Stripe error whose message says so; keep that sentence (§ 7) and the
 owner reads step 3 off it.
 
@@ -345,7 +365,8 @@ export async function fetch(request, ctx) {
   const me = ctx.userInfo?.userHandle;
 
   if (url.pathname === "/status" && request.method === "GET") {
-    return json({ ok: true, configured: Boolean(ctx.secrets.STRIPE_SECRET_KEY), owner: me === ctx.appInfo.ownerHandle, graceDays: GRACE_DAYS });
+    // ownerHandle + appSlug let the setup card link this vibe's own Settings tab.
+    return json({ ok: true, configured: Boolean(ctx.secrets.STRIPE_SECRET_KEY), owner: me === ctx.appInfo.ownerHandle, graceDays: GRACE_DAYS, ownerHandle: ctx.appInfo.ownerHandle, appSlug: ctx.appInfo.appSlug });
   }
 
   if (!me) return json({ ok: false, reason: "sign-in" }, 401);
@@ -508,11 +529,34 @@ import { useFireproof } from "use-fireproof";
 import { apiFetch, useViewer } from "use-vibes";
 import { Badge, Button, Heading, Stack, Text } from "@vibes.diy/pouf";
 
-const SETUP_STEPS = [
-  "Open the Stripe dashboard, turn on Test mode, and reveal the Secret key under Developers → API keys.",
-  "Set it on this vibe as STRIPE_SECRET_KEY: the Settings page, or `vibes-diy secrets set STRIPE_SECRET_KEY`.",
-  "Under Settings → Billing → Customer portal, save the portal with Cancel at end of billing period on.",
-];
+// The owner's setup card: every step is a link to the exact page, in that page's own words.
+function SetupSteps({ status }) {
+  const vibe = `${status.ownerHandle}/${status.appSlug}`;
+  const settingsUrl = `https://vibes.diy/vibes/mine/${vibe}/settings`;
+  return (
+    <ol>
+      <li>
+        Open Stripe's <a href="https://dashboard.stripe.com/test/apikeys" target="_blank" rel="noreferrer">API keys page (test mode)</a>,
+        use your Stripe account (the page offers to create one), and under <b>Standard keys</b> press <b>Reveal test key</b> beside <b>Secret key</b>.
+        Copy it; it starts with <code>sk_test_</code>.
+      </li>
+      <li>
+        Open <a href={settingsUrl} target="_blank" rel="noreferrer">this vibe's Settings tab</a> (My Vibes → this vibe → Settings).
+        Under <b>Secrets</b>, enter the key <code>STRIPE_SECRET_KEY</code>, paste the value, and save.
+        From a terminal instead: <code>npx vibes-diy secrets set STRIPE_SECRET_KEY --vibe {vibe}</code>.
+      </li>
+      <li>
+        Open Stripe's <a href="https://dashboard.stripe.com/test/settings/billing/portal" target="_blank" rel="noreferrer">Customer portal settings</a>:
+        under <b>Cancellations</b> turn on <b>Cancel subscriptions</b>, choose <b>At end of billing period</b>, and press <b>Save</b>.
+        Members use that page to cancel or change a card.
+      </li>
+      <li>
+        Come back here: the Join buttons work as soon as the key is saved. In test mode the card 4242 4242 4242 4242 pays.
+        To go live, do the same with the <a href="https://dashboard.stripe.com/apikeys" target="_blank" rel="noreferrer">live key</a> and the live portal.
+      </li>
+    </ol>
+  );
+}
 
 export default function App() {
   const { viewer, requestLogin } = useViewer();
@@ -523,8 +567,15 @@ export default function App() {
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState(null);
 
+  // Read status on mount, and again whenever the app comes back into view: the owner sets the key
+  // in another tab and returns, and the setup card has to give way to the buttons without a reload.
   useEffect(() => {
-    apiFetch("/status").then((r) => r.json()).then(setStatus).catch(() => setStatus({ configured: false, owner: false }));
+    const load = () => apiFetch("/status").then((r) => r.json()).then(setStatus).catch(() => setStatus({ configured: false, owner: false }));
+    load();
+    const onVisible = () => { if (document.visibilityState === "visible") load(); };
+    document.addEventListener("visibilitychange", onVisible);
+    window.addEventListener("focus", load);
+    return () => { document.removeEventListener("visibilitychange", onVisible); window.removeEventListener("focus", load); };
   }, []);
 
   // Back from Stripe: the fragment arrives just after first render and on hashchange, so read both.
@@ -570,7 +621,7 @@ export default function App() {
       <Stack>
         <Heading>Set up memberships</Heading>
         <Text>Three steps in Stripe, once, and the Join buttons go live for everyone.</Text>
-        <ol>{SETUP_STEPS.map((s) => <li key={s}>{s}</li>)}</ol>
+        <SetupSteps status={status} />
       </Stack>
     );
   }

package/llms/stripe.md

@@ -38,26 +38,45 @@ does not build — say so plainly and build the one-merchant half.
 
 ## 1. Bring your own Stripe key, and explain how
 
-The owner gets a key from Stripe, once:
-
-1. Open the Stripe dashboard and sign in (or create a Stripe account).
-2. Turn on **Test mode** (the toggle at the top) until the app is working.
-3. Go to Developers, then API keys, and reveal the **Secret key** (`sk_test_…`
-   in test mode, `sk_live_…` later).
-4. Set it on the vibe as `STRIPE_SECRET_KEY` — the vibe's settings page, or
-   `vibes-diy secrets set STRIPE_SECRET_KEY <the key>`.
-5. To go live, repeat step 3 with Test mode off and set the live key the same way.
+The owner gets a key from Stripe, once. The steps are written for someone
+who has never opened Stripe, so each one is a link to the exact page and uses
+the words that page uses:
+
+1. Open Stripe's **API keys** page in test mode:
+   <https://dashboard.stripe.com/test/apikeys> (sign in, or create a Stripe
+   account when it asks). Under **Standard keys**, press **Reveal test key**
+   beside **Secret key** and copy it. It starts with `sk_test_`.
+2. Open this vibe's **Settings** tab on vibes.diy:
+   `https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings` (that is
+   **My Vibes** → this vibe → **Settings**). Under **Secrets**, enter the key
+   `STRIPE_SECRET_KEY` and paste the value, then save. From a terminal the
+   same thing is `npx vibes-diy secrets set STRIPE_SECRET_KEY --vibe <ownerHandle>/<appSlug>`.
+3. Come back to the app. The Pay buttons work the moment the key is saved; no
+   redeploy. In test mode the card `4242 4242 4242 4242` with any future date
+   pays.
+4. To go live, take the **live** secret key from
+   <https://dashboard.stripe.com/apikeys> (**Reveal live key**, `sk_live_`)
+   and set it the same way; setting an existing key replaces it.
 
 The app carries those steps in its own UI, because the person reading them is
-the person who has to do them.
+the person who has to do them — and it fills in the vibe's real handle and
+slug, which the backend knows as `ctx.appInfo`, so the Settings link and the
+terminal command are copy-ready rather than templates. The Settings tab opens
+in another tab, so the app re-reads `/status` whenever it regains focus or
+becomes visible again: the owner saves the key, comes back, and the card gives
+way to the Pay buttons without a reload.
 
-When the key is missing, the app shows the owner the setup steps for a Stripe secret key instead of an error.
+When the key is missing, the app shows the owner the setup steps for a Stripe secret key instead of an error, and the steps link to Stripe's API keys page and to this vibe's own Settings tab by URL.
 
 The backend answers `{ ok: false, reason: "missing-key" }` when
-`ctx.secrets.STRIPE_SECRET_KEY` is absent, and the client renders the numbered
-steps, naming the Stripe dashboard and `STRIPE_SECRET_KEY` in so many words so
-the owner knows where to go and what to call it. A visitor who is not the owner
-sees a calmer sentence — payments are not set up yet — never the steps.
+`ctx.secrets.STRIPE_SECRET_KEY` is absent, and `/status` carries
+`ownerHandle` and `appSlug` so the client can render the numbered steps
+with real links: `https://dashboard.stripe.com/test/apikeys` for the key,
+`https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings` for where
+it goes, and `STRIPE_SECRET_KEY` in so many words. "Open the Stripe
+dashboard" and "the Settings page" are not instructions; a person who has
+never seen either would have to search for both. A visitor who is not the
+owner sees a calmer sentence — payments are not set up yet — never the steps.
 
 Only the owner can set or rotate a secret, and handlers see the current value on
 every invocation — so the pay button starts working the moment the key lands,
@@ -292,7 +311,8 @@ export async function fetch(request, ctx) {
   // Is Stripe set up? The owner gets the steps; everyone else gets a sentence.
   if (url.pathname === "/status" && request.method === "GET") {
     const owner = ctx.userInfo?.userHandle === ctx.appInfo.ownerHandle;
-    return json({ ok: true, configured: Boolean(ctx.secrets.STRIPE_SECRET_KEY), owner });
+    // ownerHandle + appSlug let the setup card link this vibe's own Settings tab.
+    return json({ ok: true, configured: Boolean(ctx.secrets.STRIPE_SECRET_KEY), owner, ownerHandle: ctx.appInfo.ownerHandle, appSlug: ctx.appInfo.appSlug });
   }
 
   // Start a purchase: the order first, then a Checkout Session for exactly that order.
@@ -406,21 +426,46 @@ import { useFireproof } from "use-fireproof";
 import { apiFetch, useVibe } from "use-vibes";
 import { Badge, Button, Heading, Stack, Text } from "@vibes.diy/pouf";
 
-const SETUP_STEPS = [
-  "Open the Stripe dashboard and turn on Test mode.",
-  "Go to Developers → API keys and reveal the Secret key (sk_test_…).",
-  "Set it on this vibe as STRIPE_SECRET_KEY: the Settings page, or `vibes-diy secrets set STRIPE_SECRET_KEY`.",
-];
+// The owner's setup card: every step is a link to the exact page, in that page's own words.
+function SetupSteps({ status }) {
+  const vibe = `${status.ownerHandle}/${status.appSlug}`;
+  const settingsUrl = `https://vibes.diy/vibes/mine/${vibe}/settings`;
+  return (
+    <ol>
+      <li>
+        Open Stripe's <a href="https://dashboard.stripe.com/test/apikeys" target="_blank" rel="noreferrer">API keys page (test mode)</a>,
+        use your Stripe account (the page offers to create one), and under <b>Standard keys</b> press <b>Reveal test key</b> beside <b>Secret key</b>.
+        Copy it; it starts with <code>sk_test_</code>.
+      </li>
+      <li>
+        Open <a href={settingsUrl} target="_blank" rel="noreferrer">this vibe's Settings tab</a> (My Vibes → this vibe → Settings).
+        Under <b>Secrets</b>, enter the key <code>STRIPE_SECRET_KEY</code>, paste the value, and save.
+        From a terminal instead: <code>npx vibes-diy secrets set STRIPE_SECRET_KEY --vibe {vibe}</code>.
+      </li>
+      <li>
+        Come back here: the Pay buttons work as soon as the key is saved. In test mode the card 4242 4242 4242 4242 pays.
+        To go live, do the same with the <a href="https://dashboard.stripe.com/apikeys" target="_blank" rel="noreferrer">live key</a>.
+      </li>
+    </ol>
+  );
+}
 
 export default function App() {
   const { me } = useVibe("orders");
   const { useLiveQuery } = useFireproof("orders");
   const { docs: orders } = useLiveQuery("type", { key: "order" });
-  const [status, setStatus] = useState(null); // { configured, owner } from the backend
+  const [status, setStatus] = useState(null); // { configured, owner, ownerHandle, appSlug } from the backend
   const [error, setError] = useState(null);
 
+  // Read status on mount, and again whenever the app comes back into view: the owner sets the key
+  // in another tab and returns, and the setup card has to give way to the buttons without a reload.
   useEffect(() => {
-    apiFetch("/status").then((r) => r.json()).then(setStatus).catch(() => setStatus({ configured: false, owner: false }));
+    const load = () => apiFetch("/status").then((r) => r.json()).then(setStatus).catch(() => setStatus({ configured: false, owner: false }));
+    load();
+    const onVisible = () => { if (document.visibilityState === "visible") load(); };
+    document.addEventListener("visibilitychange", onVisible);
+    window.addEventListener("focus", load);
+    return () => { document.removeEventListener("visibilitychange", onVisible); window.removeEventListener("focus", load); };
   }, []);
 
   // Back from Stripe: ask the backend to read the session and settle the order.
@@ -467,7 +512,7 @@ export default function App() {
       <Stack>
         <Heading>Set up payments</Heading>
         <Text>Add your Stripe secret key once and the Pay buttons go live for everyone.</Text>
-        <ol>{SETUP_STEPS.map((s) => <li key={s}>{s}</li>)}</ol>
+        <SetupSteps status={status} />
       </Stack>
     );
   }

package/llms/three-js.md

@@ -95,6 +95,10 @@ title, settings, scores, sharing and every other panel live behind **one** menu
 top-right corner (`IconButton`, never the bottom-right, which the platform owns) that toggles an
 overlay — see the Sky Glider example below. The game stays in view the moment the overlay closes.
 
+The lens follows the screen: pass the camera to `useWorldControls` and it widens on a phone held upright.
+An overview camera that orbits the scene keeps its own distance: scale the radius by
+`0.36 / (tan(fov / 2) · aspect)`, clamped to 1–2.2×, so the whole scene stays in frame upright.
+
 When the person asks for a smaller view — a model on a product page, a scene inside a card, a
 viewer beside a form — give the viewport a box instead and keep the page around it:
 
@@ -115,61 +119,14 @@ Size the renderer from the box (`mount.clientWidth`, `mount.clientHeight`) and w
 
 ## Touch controls on a phone
 
-On a phone, every drag across the canvas and every press of an on-screen
-button is a touch the browser would otherwise claim for itself: it selects
-the nearest text, pops the copy / look-up callout, scrolls the page, or zooms.
-Hand those touches to the scene:
-
-- Put `select-none touch-none` on the mount `<div>` / `<canvas>` **and** on the
-  container that holds the HUD, labels and on-screen controls — a long press
-  on a joystick selects the label next to it if only the canvas is covered.
-- Drive input with Pointer Events (`pointerdown` / `pointermove` / `pointerup`
-  / `pointercancel`): one path for mouse, pen and finger. `touch-none` is what
-  lets the move events keep flowing during a drag.
-- A button someone **holds** (thrust, fire, accelerate, a D-pad arrow) tracks
-  its own pressed state from the pointer events, captures the pointer so a
-  finger sliding off still releases cleanly, and cancels the long-press menu:
-
-```jsx
-import { IconButton } from "@vibes.diy/pouf";
-
-function HoldButton({ icon, label, onChange }) {
-  const set = (on) => (e) => {
-    e.preventDefault();
-    if (on) e.currentTarget.setPointerCapture(e.pointerId);
-    onChange(on);
-  };
-  return (
-    <IconButton
-      icon={icon}
-      label={label}
-      size="lg"
-      variant="solid"
-      onPointerDown={set(true)}
-      onPointerUp={set(false)}
-      onPointerCancel={set(false)}
-      onContextMenu={(e) => e.preventDefault()}
-    />
-  );
-}
-
-// The wrapper carries select-none touch-none, and its buttons inherit both —
-// the whole control area belongs to the finger:
-<div className="relative h-dvh w-full select-none touch-none">
-  <div ref={mountRef} className="absolute inset-0" />
-  <div className="absolute bottom-6 left-6 flex gap-3">
-    <HoldButton icon="◀" label="Steer left" onChange={(on) => (input.current.left = on)} />
-    <HoldButton icon="▶" label="Steer right" onChange={(on) => (input.current.right = on)} />
-  </div>
-</div>
-```
-
-Read the held state (`input.current`) inside the animation loop, so a press
-moves the scene every frame it's down. `OrbitControls` already speaks pointer
-events; it still needs `touch-none` on its element to receive the drag.
+On a phone, every drag across the canvas is a touch the browser would otherwise claim for itself:
+it selects the nearest text, pops the copy / look-up callout, scrolls the page, or zooms. Hand
+those touches to the scene with `select-none touch-none` on the mount `<div>` / `<canvas>` **and**
+on the container that holds the HUD and labels. `OrbitControls` already speaks pointer events and
+receives the drag once its element is `touch-none`.
 
-For a game's control scheme — swipes that fire mid-move, a ghost stick under the thumb,
-hold-to-boost, pull-and-release — load the `touch-games` skill beside this one.
+- A world you move through — walked, explored, flown around — calls `useWorldControls` from `use-vibes`, taught in the `touch-games` skill (Walk + look): left thumb walks, right thumb looks, tap acts, and a click-to-play overlay carries the desktop.
+- A flyer or a car that charges forward calls for hold + steer from the `touch-games` skill: thumb down is the throttle and its offset steers.
 
 ## Core Setup
 
@@ -1300,11 +1257,14 @@ Structure your component in this order:
 import React, { useState, useEffect, useRef, useCallback } from "react";
 import { useFireproof } from "use-fireproof";
 import * as THREE from "three";
+import { useWorldControls } from "use-vibes";
 import { Card, Heading, IconButton, Stack, Text } from "@vibes.diy/pouf";
 
 export default function SkyGlider() {
   const { database, useLiveQuery } = useFireproof("skyGliderScores");
+  const rootRef = useRef(null);
   const canvasRef = useRef(null);
+  const [camera] = useState(() => new THREE.PerspectiveCamera(60, 1, 0.1, 1000));
   const gameStateRef = useRef({
     scene: null,
     camera: null,
@@ -1317,7 +1277,7 @@ export default function SkyGlider() {
     lastSmokeTime: 0,
     score: 0,
     gameRunning: false,
-    keys: {},
+    stick: { x: 0, y: 0 },
     velocity: { x: 0, y: 0, z: 0 },
     heading: 0,
     forwardSpeed: 0,
@@ -1327,6 +1287,18 @@ export default function SkyGlider() {
 
   const [currentScore, setCurrentScore] = useState(0);
   const [menuOpen, setMenuOpen] = useState(false);
+
+  // The left thumb (or WASD) steers through useWorldControls, a flick up thrusts, and the hook
+  // keeps the lens fitted to the screen because it holds the camera.
+  const { keys, tick } = useWorldControls(rootRef, {
+    mode: "player",
+    flying: true,
+    camera,
+    onMove: (x, y) => Object.assign(gameStateRef.current.stick, { x, y }),
+    onFlick: (dir) => dir === "up" && (gameStateRef.current.forwardSpeed = 0.3),
+  });
+  gameStateRef.current.tick = tick;
+  gameStateRef.current.held = keys;
   const { docs: scoreData } = useLiveQuery("type", { key: "score" }) || {
     docs: [],
   };
@@ -1465,7 +1437,6 @@ export default function SkyGlider() {
     scene.background = new THREE.Color(0x70d6ff);
     scene.fog = new THREE.Fog(0x70d6ff, 50, 300);
 
-    const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
     camera.position.set(0, 10, 20);
 
     const renderer = new THREE.WebGLRenderer({
@@ -1538,15 +1509,19 @@ export default function SkyGlider() {
       roll: 0,
     };
 
-    const gameLoop = () => {
+    // dt is the real frame time in seconds, clamped so a backgrounded tab resumes gently.
+    let last = performance.now();
+    const gameLoop = (now) => {
       if (gameStateRef.current.gameRunning) {
-        updateGame();
+        const dt = Math.min((now - last) / 1000, 0.1);
+        last = now;
+        updateGame(dt);
         requestAnimationFrame(gameLoop);
       }
     };
     gameStateRef.current.gameRunning = true;
-    gameLoop();
-  }, [createTexturedCoin]);
+    requestAnimationFrame(gameLoop);
+  }, [createTexturedCoin, camera]);
 
   const checkCoinCollisions = useCallback(() => {
     const state = gameStateRef.current;
@@ -1573,36 +1548,23 @@ export default function SkyGlider() {
     });
   }, [createGlowEffect]);
 
-  const handleKeyDown = useCallback((event) => {
-    if (event.code === "Space") event.preventDefault();
-    gameStateRef.current.keys[event.code] = true;
-  }, []);
-
-  const handleKeyUp = useCallback((event) => {
-    if (event.code === "Space") event.preventDefault();
-    gameStateRef.current.keys[event.code] = false;
-  }, []);
-
   const handleResize = useCallback(() => {
     const state = gameStateRef.current;
-    if (!state.camera || !state.renderer) return;
-    state.camera.aspect = window.innerWidth / window.innerHeight;
-    state.camera.updateProjectionMatrix();
+    if (!state.renderer) return;
     state.renderer.setSize(window.innerWidth, window.innerHeight);
   }, []);
 
-  const updateGame = useCallback(() => {
+  const updateGame = useCallback((dt) => {
     const state = gameStateRef.current;
     if (!state.gameRunning || !state.glider) return;
 
-    const { keys, glider } = state;
+    const { stick, held, glider } = state;
+    state.tick(dt);
 
-    // Controls
-    if (keys["ArrowLeft"] || keys["KeyA"]) state.heading += 0.03;
-    if (keys["ArrowRight"] || keys["KeyD"]) state.heading -= 0.03;
-    if (keys["ArrowUp"] || keys["KeyW"]) state.pitch += 0.01;
-    if (keys["ArrowDown"] || keys["KeyS"]) state.pitch -= 0.01;
-    if (keys["Space"]) state.forwardSpeed = Math.min(0.3, state.forwardSpeed + 0.005);
+    // Controls: the stick (thumb or WASD) banks and pitches; Space thrusts
+    state.heading -= stick.x * 0.03;
+    state.pitch -= stick.y * 0.01; // forward on the stick (y < 0) climbs
+    if (held.has("Space")) state.forwardSpeed = Math.min(0.3, state.forwardSpeed + 0.005);
 
     // Physics
     state.forwardSpeed = Math.max(0.05, state.forwardSpeed * 0.995);
@@ -1672,12 +1634,8 @@ export default function SkyGlider() {
 
   useEffect(() => {
     initThreeJS();
-    window.addEventListener("keydown", handleKeyDown);
-    window.addEventListener("keyup", handleKeyUp);
     window.addEventListener("resize", handleResize);
     return () => {
-      window.removeEventListener("keydown", handleKeyDown);
-      window.removeEventListener("keyup", handleKeyUp);
       window.removeEventListener("resize", handleResize);
       const state = gameStateRef.current;
       state.gameRunning = false;
@@ -1696,12 +1654,15 @@ export default function SkyGlider() {
       }
       if (state.renderer) state.renderer.dispose();
     };
-  }, [initThreeJS, handleKeyDown, handleKeyUp, handleResize]);
+  }, [initThreeJS, handleResize]);
 
   return (
     // Full screen by default: the game is the whole view. The score stays as a quiet HUD; the title,
     // the controls legend and the high scores live behind ONE menu button, so nothing covers play.
-    <div className="relative h-dvh w-full overflow-hidden bg-background text-foreground font-sans select-none touch-none">
+    <div
+      ref={rootRef}
+      className="relative h-dvh w-full overflow-hidden bg-background text-foreground font-sans select-none touch-none"
+    >
       <canvas ref={canvasRef} className="absolute inset-0 select-none touch-none" />
       <div className="absolute top-3 left-3 pointer-events-none">
         <Text num>Score: {currentScore}</Text>
@@ -1715,7 +1676,7 @@ export default function SkyGlider() {
             <Stack gap={2}>
               <Heading level={2}>Sky Glider</Heading>
               <Text size="sm" muted>
-                WASD/Arrows: Fly, Space: Thrust
+                Left thumb or WASD: steer · flick up or Space: thrust
               </Text>
               {scoreData
                 .sort((a, b) => b.value - a.value)

package/llms/touch-games.js

@@ -5,9 +5,11 @@ export const touchGamesConfig = {
         "physics, p5, worlds or pouf-game for every game, 3D scene you move through, or canvas toy: the play area " +
         "is the controller (select-none touch-none surface, Pointer Events with pointer capture), swipes that fire " +
         "mid-move with chaining, tap vs swipe on one surface, a floating ghost stick under the thumb, hold-to-boost " +
-        "with drag steering, pull-back-and-release aiming, gesture trails and feedback, keyboard twins for desktop. " +
+        "with drag steering, pull-back-and-release aiming, gesture trails and feedback, keyboard twins for desktop, " +
+        "and walk + look for a 3D world through the useWorldControls hook from use-vibes (left thumb walks, right thumb " +
+        "looks, flick up to jump, desktop pointer lock and WASD). " +
         "game, mobile game, touch controls, swipe, joystick, runner, racer, flyer, shooter, snake, slingshot, " +
-        "platformer, arcade, one thumb",
+        "platformer, arcade, one thumb, first-person, walk around, explore",
     cues: [
         "swipe",
         "touch controls",
@@ -36,6 +38,10 @@ export const touchGamesConfig = {
         "catapult",
         "flappy",
         "snake game",
+        "first-person",
+        "first person",
+        "walk around",
+        "explore",
     ],
 };
 //# sourceMappingURL=touch-games.js.map

package/llms/touch-games.js.map

@@ -1 +1 @@
-{"version":3,"file":"touch-games.js","sourceRoot":"","sources":["../../jsr/llms/touch-games.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,gBAAgB,GAAc;IACzC,IAAI,EAAE,aAAa;IACnB,KAAK,EAAE,aAAa;IACpB,WAAW,EACT,qGAAqG;QACrG,2GAA2G;QAC3G,4GAA4G;QAC5G,6GAA6G;QAC7G,6GAA6G;QAC7G,uGAAuG;QACvG,+BAA+B;IAKjC,IAAI,EAAE;QACJ,OAAO;QACP,gBAAgB;QAChB,aAAa;QACb,YAAY;QACZ,YAAY;QACZ,aAAa;QACb,cAAc;QACd,aAAa;QACb,UAAU;QACV,QAAQ;QACR,OAAO;QACP,QAAQ;QACR,OAAO;QACP,SAAS;QACT,YAAY;QACZ,gBAAgB;QAChB,SAAS;QACT,aAAa;QACb,aAAa;QACb,OAAO;QACP,SAAS;QACT,WAAW;QACX,SAAS;QACT,WAAW;QACX,UAAU;QACV,QAAQ;QACR,YAAY;KACb;CACF,CAAC"}
+{"version":3,"file":"touch-games.js","sourceRoot":"","sources":["../../jsr/llms/touch-games.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,gBAAgB,GAAc;IACzC,IAAI,EAAE,aAAa;IACnB,KAAK,EAAE,aAAa;IACpB,WAAW,EACT,qGAAqG;QACrG,2GAA2G;QAC3G,4GAA4G;QAC5G,6GAA6G;QAC7G,6GAA6G;QAC7G,iHAAiH;QACjH,2DAA2D;QAC3D,uGAAuG;QACvG,mEAAmE;IAKrE,IAAI,EAAE;QACJ,OAAO;QACP,gBAAgB;QAChB,aAAa;QACb,YAAY;QACZ,YAAY;QACZ,aAAa;QACb,cAAc;QACd,aAAa;QACb,UAAU;QACV,QAAQ;QACR,OAAO;QACP,QAAQ;QACR,OAAO;QACP,SAAS;QACT,YAAY;QACZ,gBAAgB;QAChB,SAAS;QACT,aAAa;QACb,aAAa;QACb,OAAO;QACP,SAAS;QACT,WAAW;QACX,SAAS;QACT,WAAW;QACX,UAAU;QACV,QAAQ;QACR,YAAY;QACZ,cAAc;QACd,cAAc;QACd,aAAa;QACb,SAAS;KACV;CACF,CAAC"}

package/llms/touch-games.md

@@ -18,6 +18,7 @@ Three things make that true, and each has one home:
    steers the game while nearby text stays put — no selection highlight, no copy callout, no
    page scroll, no pinch zoom, no pull-to-refresh.
 2. **One input path for every pointer.** Input runs on Pointer Events with `setPointerCapture` on one tracked `pointerId`, so mouse, pen and finger share one path.
+   A 3D world you walk through gets that path from `useWorldControls` (see Walk + look below).
 3. **The game says what it understood.** A short fading trail under the finger, plus an arrow,
    ghost stick or aim line, so the player sees which gesture the game read.
 
@@ -30,6 +31,7 @@ Three things make that true, and each has one home:
 | Flies or drives forward: a glider, a ship, a car | **Hold + steer** — thumb down = throttle, offset = steer | canyon flyer |
 | Aims then commits: a launcher, golf, pool, basketball | **Pull back + release** | slingshot |
 | Moves in steps AND has one action | **Flick + tap** on the same surface | snake with a dash |
+| Walks or flies through a 3D world: a block world, a garden, a ruin to explore | **Walk + look** — `useWorldControls` | first-person explorer |
 
 A desktop visitor gets the same game: the mouse drives the same pointer path, and arrow keys /
 WASD / Space call the same action functions the gestures call.
@@ -159,6 +161,211 @@ the start point (~24px) cancels, and the ring says so. The thumb usually starts
 third, so put the ground at about two-thirds of the screen height and leave room below it to
 pull. Preview only part of the arc (about 0.85s of flight) so aiming stays a skill.
 
+## Walk + look: move through a 3D world
+
+A 3D world you walk, fly or look around in gets its controls from `useWorldControls` (from `use-vibes`), on phone and desktop alike. Hand it the root element and what each act means; the hook owns the gestures, keeps the root `touch-none`, and sizes the lens when you pass it the camera.
+
+Left half walks: a floating stick appears under the thumb. Right half looks: drag to turn, and a finger held near the screen's edge keeps turning.
+
+Tap acts on what is under the finger; press and hold is the second action; a quick upward flick on the look side jumps.
+
+- **The jump is judged as the finger lifts**, and the flick's up/down look is held back, so the
+  camera stays level through every jump.
+- **`mode: "player"`** walks, looks and flicks; **`mode: "free"`** orbits a camera that zooms
+  with a pinch or the mouse wheel (`onPinch(factor)`, under 1 zooms in). With `flying: true`, a
+  flick down (`onFlick("down")`) sinks.
+- **The callbacks speak screen sense.** `onMove(x, y)` is the walk vector with forward at `y < 0`;
+  `onLook(dx, dy)` and `onTurn(yaw, pitch)` arrive in radians, applied the same way; `onTap`,
+  `onHold` and `onAim` carry client coordinates.
+- **Call `tick(dt)` once per frame** from the animation loop; the edge turn, the hold timer and
+  the finger trail advance on that clock, and `keys` holds every key code down right now.
+- **The lens follows the screen.** Pass the `THREE.PerspectiveCamera` as `camera` and the hook
+  keeps its aspect current and widens the view on a phone held upright.
+- **HUD controls live inside the root.** A press on a button, input or link there is that
+  control's own and never a world tap; mark any other piece that keeps its own touches (a slider,
+  a chip row) with `data-world-controls-ignore`.
+
+A 🎥 button outside the menu cycles the views; on a phone the world opens in a free-cam overview that frames the whole scene. The views are **Free cam → First person → Shoulder view**; a desktop visitor opens in first person.
+The overview's distance is the app's: scale the orbit radius by
+`0.36 / (tan(fov / 2) · aspect)`, clamped to 1–2.2×, each frame, so a phone held upright still
+frames the whole scene.
+
+The one-line hint follows the current view.
+
+The ☰ menu holds everything else, in this order: the views by name, fullscreen, how to play,
+who else is here and what they did lately (players and activity), then invite a friend and all
+worlds.
+
+**The desktop twin is the same world.** In the player views a click-to-play overlay calls
+`requestLock()`, so the mouse looks under pointer lock; WASD or the arrows walk and Space jumps.
+`locked` reports the lock, so the overlay comes back when the player presses Esc, and `isTouch`
+keeps the overlay off phones. While locked, a click under the crosshair is the tap and a
+right-click is the hold (`onTap` / `onHold` at the screen centre). Free cam needs no lock: drag
+orbits, a click is `onTap`, a right-click is `onHold`, and the wheel zooms.
+
+### `App.jsx`
+```jsx
+import React from "react";
+import * as THREE from "three";
+import { useWorldControls } from "use-vibes";
+import { Button, Card, Heading, IconButton, Stack, Text } from "@vibes.diy/pouf";
+
+const VIEWS = ["Free cam", "First person", "Shoulder view"];
+const HINT = {
+  "Free cam": "drag to look around · pinch to zoom · 🎥 to step in",
+  "First person": "left thumb walks · right thumb looks · flick up to jump",
+  "Shoulder view": "tap a hedge to bloom it · hold to trim it back",
+};
+const stop = (e) => e.stopPropagation();
+
+export default function App() {
+  const rootRef = React.useRef(null);
+  const canvasRef = React.useRef(null);
+  const [camera] = React.useState(() => new THREE.PerspectiveCamera(70, 1, 0.1, 500));
+  const [view, setView] = React.useState(() => (matchMedia("(pointer: coarse)").matches ? "Free cam" : "First person"));
+  const [menuOpen, setMenuOpen] = React.useState(false);
+  const me = React.useRef({ pos: new THREE.Vector3(0, 0, 12), yaw: 0, pitch: 0, move: [0, 0], vy: 0, zoom: 34 });
+  const world = React.useRef({ hedges: [] });
+
+  const turn = (yaw, pitch) => {
+    me.current.yaw += yaw;
+    me.current.pitch = Math.max(-1.5, Math.min(1.5, me.current.pitch + pitch));
+  };
+  const look = (dx, dy) => turn(-dx, -dy); // radians, screen sense: a drag right turns right
+  const hedgeAt = (x, y) => {
+    const r = rootRef.current.getBoundingClientRect(); // taps arrive in client coordinates
+    const ray = new THREE.Raycaster();
+    ray.setFromCamera(new THREE.Vector2(((x - r.left) / r.width) * 2 - 1, 1 - ((y - r.top) / r.height) * 2), camera);
+    return ray.intersectObjects(world.current.hedges)[0]?.object;
+  };
+  const { isTouch, locked, requestLock, tick } = useWorldControls(rootRef, {
+    mode: view === "Free cam" ? "free" : "player",
+    camera,
+    onMove: (x, y) => (me.current.move = [x, y]),
+    onLook: look,
+    onTurn: look,
+    onPinch: (factor) => (me.current.zoom = Math.max(8, Math.min(60, me.current.zoom * factor))),
+    onTap: (x, y) => hedgeAt(x, y)?.material.color.set(0xff6fb1),
+    onHold: (x, y) => hedgeAt(x, y)?.material.color.set(0x2f7a3a),
+    onFlick: (dir) => dir === "up" && me.current.pos.y === 0 && (me.current.vy = 7),
+  });
+  const live = React.useRef({});
+  live.current = { tick, view };
+
+  React.useEffect(() => {
+    const root = rootRef.current;
+    const renderer = new THREE.WebGLRenderer({ canvas: canvasRef.current, antialias: true });
+    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+    const size = new ResizeObserver(() => renderer.setSize(root.clientWidth, root.clientHeight, false));
+    size.observe(root);
+    const scene = new THREE.Scene();
+    scene.background = new THREE.Color(0x9fe3ff);
+    scene.add(new THREE.HemisphereLight(0xffffff, 0x3b5d2a, 1.4));
+    const groundGeo = new THREE.PlaneGeometry(60, 60);
+    const ground = new THREE.Mesh(groundGeo, new THREE.MeshLambertMaterial({ color: 0x6fcf5b }));
+    ground.rotation.x = -Math.PI / 2;
+    scene.add(ground);
+    const hedgeGeo = new THREE.BoxGeometry(5, 2, 1);
+    for (let i = 0; i < 10; i++) {
+      const hedge = new THREE.Mesh(hedgeGeo, new THREE.MeshLambertMaterial({ color: 0x2f7a3a }));
+      hedge.position.set(Math.cos(i * 0.63) * 18, 1, Math.sin(i * 0.63) * 18);
+      hedge.lookAt(0, 1, 0);
+      scene.add(hedge);
+      world.current.hedges.push(hedge);
+    }
+
+    let raf = 0;
+    let last = performance.now();
+    const frame = (now) => {
+      const dt = Math.min((now - last) / 1000, 1 / 30);
+      last = now;
+      live.current.tick(dt);
+      const m = me.current;
+      const fwd = new THREE.Vector3(-Math.sin(m.yaw), 0, -Math.cos(m.yaw));
+      const side = new THREE.Vector3(-fwd.z, 0, fwd.x);
+      m.pos.addScaledVector(fwd, -m.move[1] * 5 * dt).addScaledVector(side, m.move[0] * 5 * dt); // forward is y < 0
+      m.vy -= 20 * dt;
+      m.pos.y = Math.max(0, m.pos.y + m.vy * dt);
+      if (m.pos.y === 0) m.vy = 0;
+      if (live.current.view === "Free cam") {
+        // Back the overview off on a narrow screen so the whole garden stays in frame.
+        const fit = Math.min(2.2, Math.max(1, 0.36 / (Math.tan((camera.fov * Math.PI) / 360) * camera.aspect)));
+        const d = m.zoom * fit;
+        camera.position.set(m.pos.x + Math.sin(m.yaw) * d, d * 0.7, m.pos.z + Math.cos(m.yaw) * d);
+        camera.lookAt(m.pos);
+      } else {
+        camera.position.copy(m.pos).y += 1.6;
+        if (live.current.view === "Shoulder view") camera.position.addScaledVector(fwd, -4).y += 1;
+        camera.rotation.set(m.pitch, m.yaw, 0, "YXZ");
+      }
+      renderer.render(scene, camera);
+      raf = requestAnimationFrame(frame);
+    };
+    raf = requestAnimationFrame(frame);
+
+    return () => {
+      cancelAnimationFrame(raf);
+      size.disconnect();
+      world.current.hedges.forEach((hedge) => hedge.material.dispose());
+      world.current.hedges = [];
+      hedgeGeo.dispose();
+      groundGeo.dispose();
+      ground.material.dispose();
+      renderer.dispose();
+    };
+  }, [camera]);
+
+  const cycle = () => setView(VIEWS[(VIEWS.indexOf(view) + 1) % VIEWS.length]);
+  return (
+    <div ref={rootRef} className="relative h-dvh w-full overflow-hidden bg-background text-foreground select-none touch-none">
+      <canvas ref={canvasRef} className="absolute inset-0 block w-full h-full select-none touch-none" />
+      <div className="absolute top-3 left-3 pointer-events-none">
+        <Text size="sm">{HINT[view]}</Text>
+      </div>
+      <div className="absolute top-3 right-3 flex gap-2" onPointerDown={stop}>
+        <IconButton icon="🎥" label={`View: ${view}`} onClick={cycle} />
+        <IconButton icon="☰" label={menuOpen ? "Hide menu" : "Show menu"} onClick={() => setMenuOpen(!menuOpen)} />
+      </div>
+      {menuOpen && (
+        <div className="absolute top-16 right-3 w-72" onPointerDown={stop}>
+          <Card>
+            <Stack gap={2}>
+              <Heading level={2}>Hedge Garden</Heading>
+              {VIEWS.map((v) => (
+                <Button key={v} variant={v === view ? "solid" : "quiet"} onClick={() => setView(v)}>
+                  {v}
+                </Button>
+              ))}
+              <Text size="sm" muted>
+                Left thumb walks, right thumb looks. Tap a hedge to bloom it, hold to trim it, flick up to jump.
+              </Text>
+            </Stack>
+          </Card>
+        </div>
+      )}
+      {!isTouch && !locked && view !== "Free cam" && (
+        <div className="absolute inset-0 z-20 flex items-center justify-center bg-background/80" onPointerDown={stop}>
+          <Card>
+            <Stack gap={3}>
+              <Heading level={2}>Hedge Garden</Heading>
+              <Button size="lg" onClick={requestLock}>
+                Click to play
+              </Button>
+              <Text size="sm" muted>
+                WASD walk · mouse look · Space jump · click bloom · Esc frees the mouse
+              </Text>
+            </Stack>
+          </Card>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+Grow it by changing what the acts mean: `voxel` makes the tap build and the hold break, a ruin
+makes the tap open a door. The gesture numbers live in the hook; pass `tune` to adjust them.
+
 ## Teach the gesture once, then get out of the way
 
 - **A ghost thumb on first run.** Before the first touch, a translucent thumb with a short motion

package/llms/voxel.js

@@ -5,7 +5,7 @@ export const voxelConfig = {
         "Build a Minecraft-style first-person voxel sandbox with Three.js: chunked block world, " +
         "procedural terrain (noise heightmaps, biomes, caves, ore veins, trees), place/break with a " +
         "DDA voxel raycast, an AABB player controller with gravity, jump, sprint, auto step-up and " +
-        "un-stick, pointer-lock look with a click-to-play overlay and touch drag, endless chunk " +
+        "un-stick, thumb walk/look and desktop pointer lock through useWorldControls with a click-to-play overlay, endless chunk " +
         "streaming, a shared voxel palette with material-colored controls, a day/night cycle, " +
         "ambient mobs, and live multiplayer block edits with temporary player presence over Fireproof. " +
         "Covers the survival layer (table-driven crafting tiers, tools with durability, smelting, " +

package/llms/voxel.js.map

@@ -1 +1 @@
-{"version":3,"file":"voxel.js","sourceRoot":"","sources":["../../jsr/llms/voxel.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,WAAW,GAAc;IACpC,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,OAAO;IACd,WAAW,EACT,wGAAwG;QACtG,yFAAyF;QAC3F,6FAA6F;QAC7F,4FAA4F;QAC5F,yFAAyF;QACzF,uFAAuF;QACvF,gGAAgG;QAChG,2FAA2F;QAC3F,yFAAyF;QACzF,6CAA6C;QAC7C,2FAA2F;QAC3F,+JAA+J;IACjK,IAAI,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,CAAC;IAC/E,YAAY,EAAE,OAAO;IACrB,UAAU,EAAE,OAAO;IACnB,UAAU,EAAE,WAAW;CACxB,CAAC"}
+{"version":3,"file":"voxel.js","sourceRoot":"","sources":["../../jsr/llms/voxel.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,WAAW,GAAc;IACpC,IAAI,EAAE,OAAO;IACb,KAAK,EAAE,OAAO;IACd,WAAW,EACT,wGAAwG;QACtG,yFAAyF;QAC3F,6FAA6F;QAC7F,4FAA4F;QAC5F,0HAA0H;QAC1H,uFAAuF;QACvF,gGAAgG;QAChG,2FAA2F;QAC3F,yFAAyF;QACzF,6CAA6C;QAC7C,2FAA2F;QAC3F,+JAA+J;IACjK,IAAI,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,CAAC;IAC/E,YAAY,EAAE,OAAO;IACrB,UAAU,EAAE,OAAO;IACnB,UAAU,EAAE,WAAW;CACxB,CAAC"}

package/llms/voxel.md

@@ -190,9 +190,7 @@ luminance and contrast ratio ([normal text: at least 4.5:1](https://www.w3.org/W
 and erase take `ink`; recompute for additional or customized colors. A simple
 brightness threshold can choose white on wood, water, or lava even when dark
 text is more readable. Keep labels/icons and `aria-pressed` or `aria-checked`:
-the accent reinforces the selected mode rather than being its only signal. On
-touch, keep movement/look separate from Place/Break/Jump controls, and clear
-held input on pointer cancellation or lost capture.
+the accent reinforces the selected mode rather than being its only signal.
 
 ## Rendering: instance the EXPOSED blocks (this is the whole performance game)
 
@@ -404,52 +402,36 @@ handlers. Clear held keys on blur, pointer-lock loss, pause, and tab hiding so
 movement stops even when the matching keyup never arrives. Remove listeners
 when the engine unmounts.
 
-### Looking: pointer lock with a click-to-play overlay (+ touch drag)
+### Moving and looking: `useWorldControls`
 
-Pointer lock is the number-one confusion in browser voxel games: players click
-and nothing happens, or they don't know the mouse controls the camera at all.
-**Always** show an explicit "Click to play" overlay with the control legend,
-and only request lock from that click:
-
-```jsx
-{worldReady && !isTouch && !locked && (
-  <div className="absolute inset-0 z-20 flex flex-col items-center justify-center bg-background/80 backdrop-blur-sm">
-    <Card>
-      <Stack gap={3}>
-        <Heading level={2}>Voxel World</Heading>
-        <Button type="button" size="lg" onClick={() => engineRef.current?.requestLock()}>
-          Click to play
-        </Button>
-        {/* WASD move · Mouse look · Shift sprint · Space jump · Left-click break · Right-click place · F fly · 1–9 blocks */}
-        <Text size="sm" muted>Press Esc to release the mouse</Text>
-      </Stack>
-    </Card>
-  </div>
-)}
-```
+Controls come from `useWorldControls`; voxel adds what the acts mean: a tap builds on the targeted block, a hold breaks it, the block chip and hotbar pick the material, G toggles flying, and a flick down sinks while flying.
 
-Drive the overlay off the real lock state so it reappears when the player hits
-Esc:
+The hook, its usage example and its desktop twin live in the `touch-games` skill (Walk + look);
+load it beside this one. In a block world the hook's callbacks become:
 
-```js
-React.useEffect(() => {
-  const onLock = () => setLocked(!!document.pointerLockElement);
-  document.addEventListener("pointerlockchange", onLock);
-  return () => document.removeEventListener("pointerlockchange", onLock);
-}, []);
-```
+- `onTap(x, y)` builds and `onHold(x, y)` breaks, through the DDA raycast below — from that point
+  (client coordinates) on a phone, from screen centre under the crosshair while the mouse is locked.
+- `onAim(x, y)` moves the block highlight under a resting finger, and `onAim(null, null)` clears it.
+- `onFlick("up")` jumps. G toggles `flying: true`; while flying, `onFlick("down")` sinks.
+- `onLook(dx, dy)` and `onTurn(yaw, pitch)` turn the player, in radians. Clamp pitch to ±1.5 rad.
+- `camera` is the player's `THREE.PerspectiveCamera`, so the lens widens on a phone held upright.
 
-In the engine, read `movementX/Y` when `document.pointerLockElement === canvas`
-(clamp per-event deltas — browsers spike them on lock acquire), and fall back to
-**drag-to-look on touch** so phones work without pointer lock. Clamp pitch to
-±1.5 rad. Provide on-screen move/jump/place/break buttons for touch.
+Pointer lock is the number-one confusion in browser voxel games: players click
+and nothing happens, or they don't know the mouse controls the camera at all.
+**Always** show an explicit "Click to play" overlay with the control legend,
+and only request lock from that click: its button calls the hook's `requestLock()`, and the hook's
+`locked` brings the overlay back when the player presses Esc. The overlay JSX is in `touch-games`;
+the voxel legend reads "WASD move · Mouse look · Shift sprint · Space jump · Click build ·
+Right-click break · G fly · 1–9 blocks".
 
 ### View switcher: see your own character
 
 Include a view switcher between first-person and third-person so players can see their own avatar.
-Provide a labeled HUD button that works on touch and a keyboard shortcut
-(e.g. `V`, shown in the control legend); toggle once per press, ignoring key
-repeat. Render a simple blocky local-player avatar in third-person, following
+The 🎥 camera button outside the menu cycles **Free cam → First person → Shoulder view**, and a
+keyboard shortcut (e.g. `V`, shown in the control legend) does the same; toggle once per press,
+ignoring key repeat. On a phone the world opens in Free cam, an overview that frames the island;
+back its radius off on a narrow screen as `touch-games` shows.
+Render a simple blocky local-player avatar in third-person, following
 the player's position and heading, and hide it in first-person so it does not
 cover the camera. Keep the same player physics and position when switching:
 offset the third-person camera behind the player and shorten that offset when
@@ -473,15 +455,15 @@ when needed. Remove the fullscreen listener on unmount.
 ### Full screen, with one menu button
 
 The world fills the screen (the `CanvasStage` above is `absolute inset-0` inside a
-`relative h-dvh w-full` root). Keep the crosshair, the hotbar and the touch controls on screen;
+`relative h-dvh w-full` root). Keep the crosshair, the block chip (the material in hand; a tap
+opens the palette), the hotbar (1–9 and 0 on a keyboard), undo and the 🎥 camera button on screen;
 put the title, settings, crafting recipes, the world-reset control and the player list behind
 **one** top-right menu button (`IconButton`) that toggles an overlay. The bottom-right corner
 belongs to the platform. A smaller boxed world is only for when the person asks for one.
 
-### No text selection, and bind touch as well as mouse
+### No text selection on the game surface
 
-The phone control schemes themselves (swipes, a ghost stick under the thumb, hold-to-move)
-live in the `touch-games` skill; load it beside this one.
+The phone controls themselves come from `useWorldControls`, taught in the `touch-games` skill.
 
 Two things separate "works on my laptop" from "works", and both are easy to
 forget because the desktop build hides them:
@@ -490,8 +472,7 @@ forget because the desktop build hides them:
   otherwise highlights the HUD text, fires iOS's selection callout, or scrolls
   the page under the player. Put `select-none touch-none` (Tailwind for
   `user-select: none` + `touch-action: none`) on the `<canvas>` **and** its
-  container, cover the WebKit-only bits, and `preventDefault()` on every
-  `mousedown` / `touchstart` you handle so a drag can never *begin* a selection:
+  container, and cover the WebKit-only bits:
 
   ```css
   #world, #world * {
@@ -501,31 +482,8 @@ forget because the desktop build hides them:
   }
   ```
 
-- **Every mouse binding needs a touch twin, or the game is dead on a phone.**
-  Add `touchstart` / `touchmove` / `touchend` next to your mouse handlers, and —
-  this is the part that bites — register them with `{ passive: false }`, or the
-  browser treats the listener as passive and your `preventDefault()` is ignored
-  (scroll/zoom win). A drag looks; a tap mines/places (raycast from the touch
-  point, or from screen-center under the crosshair). On-screen move/jump buttons
-  stand in for the keyboard.
-
-  ```js
-  const opts = { passive: false }; // REQUIRED — a passive listener CANNOT preventDefault
-  // ALWAYS read `changedTouches[0]`, never `touches[0]`: at touchend/touchcancel
-  // `touches` is EMPTY (the finger lifted), so `touches[0]` is undefined and you
-  // lose the final tap coordinate. A TouchEvent also has no mouse `movementX`, so
-  // compute look deltas yourself from the last point rather than reusing the
-  // pointer-lock path. Handle touchcancel too (a call/notification interrupts).
-  let lx = 0, ly = 0;
-  const pt = (e) => e.changedTouches[0];
-  canvas.addEventListener("touchstart", (e) => { e.preventDefault(); const t = pt(e); lx = t.clientX; ly = t.clientY; onDown(t); }, opts);
-  canvas.addEventListener("touchmove",  (e) => { e.preventDefault(); const t = pt(e); onLook(t.clientX - lx, t.clientY - ly); lx = t.clientX; ly = t.clientY; }, opts);
-  canvas.addEventListener("touchend",   (e) => { e.preventDefault(); onUp(pt(e)); }, opts);   // pt(e) = the finger that lifted; a tap here = mine/place
-  canvas.addEventListener("touchcancel",(e) => { e.preventDefault(); onCancel(); }, opts);     // gesture interrupted — reset drag state
-  // Pointer Events (pointerdown/move/up + pointercancel) unify mouse + touch in
-  // one path and give you `movementX` under lock — often cleaner — but you STILL
-  // need `touch-action: none` above or the browser eats the drag.
-  ```
+- **Every act reaches a phone through the hook.** The tap, the hold, the stick and the look drag
+  arrive as `useWorldControls` callbacks, so one handler serves the mouse and the finger alike.
 
 ### Block targeting: a DDA voxel raycast, not `Raycaster`
 
@@ -542,8 +500,10 @@ function castTarget() {
 }
 ```
 
-Left-click breaks the targeted block; right-click (`contextmenu`, prevent
-default) places `selected` on the entered face. **Guard placement** so a player
+On a desktop, a click under the crosshair is the tap and a right-click is the hold: the hook
+reports both at screen centre while the mouse is locked (and cancels the context menu), so
+`onTap` places `selected` on the entered face and `onHold` breaks the targeted block, the same
+handlers a phone uses. **Guard placement** so a player
 can never place a block inside their own AABB. Show a wireframe highlight box on
 the current target each frame, and spawn a quick burst of small colored cubes
 when a block breaks — cheap, and it makes mining feel real.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "14.3.168",
+  "version": "14.3.173",
   "type": "module",
   "main": "./index.js",
   "exports": {
@@ -39,10 +39,10 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/api-types": "14.3.168",
-    "@vibes.diy/call-ai-v2": "14.3.168",
-    "@vibes.diy/identity": "14.3.168",
-    "@vibes.diy/use-vibes-types": "14.3.168",
+    "@vibes.diy/api-types": "14.3.173",
+    "@vibes.diy/call-ai-v2": "14.3.173",
+    "@vibes.diy/identity": "14.3.173",
+    "@vibes.diy/use-vibes-types": "14.3.173",
     "arktype": "~2.2.6",
     "json-schema-faker": "~0.6.3"
   },