@vibes.diy/prompts 14.3.0 → 14.3.1

package/llms/voxel.js

@@ -5,7 +5,8 @@ export const voxelConfig = {
         "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 " +
-        "streaming, a day/night cycle, ambient mobs, and live multiplayer block edits over Fireproof. " +
+        "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, " +
         "armor, mob combat, hunger, dimensions, per-player inventory, world reset) and the flat " +
         "multi-file project split for bigger games. " +

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,yFAAyF;QACzF,6FAA6F;QAC7F,4FAA4F;QAC5F,yFAAyF;QACzF,+FAA+F;QAC/F,2FAA2F;QAC3F,yFAAyF;QACzF,6CAA6C;QAC7C,2FAA2F;QAC3F,yFAAyF;IAC3F,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,yFAAyF;QACzF,6FAA6F;QAC7F,4FAA4F;QAC5F,yFAAyF;QACzF,uFAAuF;QACvF,gGAAgG;QAChG,2FAA2F;QAC3F,yFAAyF;QACzF,6CAA6C;QAC7C,2FAA2F;QAC3F,yFAAyF;IAC3F,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

@@ -13,7 +13,11 @@ veins, endless chunk streaming, day/night, live multiplayer edits, ambient
 wildlife — and its bigger successor **Blockcraft World**, which adds the full
 survival layer: crafting tiers, tool durability, smelting, armor, mob combat,
 hunger, creative mode, nether/end dimensions, per-player inventory, and a
-shared world reset. Every pattern below is pulled from them.
+shared world reset. **Blocktopia** contributes material-colored controls,
+compact procedural island settings, and sparse per-cell edits; **Block Craft**
+contributes exposed-face chunk meshes and survival feedback. Adapt the useful
+patterns to the persistence contracts below: whole-world autosaves and durable
+movement heartbeats are expensive examples to improve, rather than defaults.
 
 ## Project shape: an engine in a React shell, split across a few flat files
 
@@ -43,9 +47,10 @@ access.js        the access function (see multiplayer section)
 Multi-file rules — each one is load-bearing, breaking any of them breaks the
 deployed app:
 
-- **All files flat at the root.** The CLI push / codegen path reads top-level
-  files only — a subdirectory (`components/…`) is silently not uploaded and
-  every import of it dangles.
+- **All files flat at the root** is a simple default for this example.
+  Nested `components/` and `lib/` modules also work in the CLI and codegen.
+  **Relative imports resolve to uploaded files** at their exact paths; keep
+  the special App, access, backend, and seed entry files at the root.
 - **Relative imports include the extension**: `./core.js`, `./ui.jsx` — the
   client serves files by exact path, so an extensionless `./core` 404s in the
   browser.
@@ -114,17 +119,83 @@ const state = {
 };
 ```
 
-Keep block types as a table of face colors so one material set covers the world:
+Keep block types as a table of face colors so one material set covers the world.
+Use the shared palette below for matching materials, with darker side faces:
 
 ```js
 const BLOCK_TYPES = {
-  grass: { top: 0x5fbf3f, side: 0x7a5230 }, dirt: { top: 0x7a5230, side: 0x6b4626 },
-  stone: { top: 0x8a8a8a, side: 0x7a7a7a }, sand: { top: 0xe0d29a, side: 0xd6c78a },
-  water: { top: 0x3f6fbf, side: 0x3f6fbf }, wood: { top: 0x9a6b3f, side: 0x6b4626 },
+  grass: { top: 0x6fcf5b, side: 0x8a5a3b }, dirt: { top: 0x8a5a3b, side: 0x6b4626 },
+  stone: { top: 0x9b9b9b, side: 0x7a7a7a }, sand: { top: 0xf2dc9b, side: 0xd6c78a },
+  water: { top: 0x2f8fe0, side: 0x2f8fe0 }, wood: { top: 0xb5793a, side: 0x6b4626 },
   leaves:{ top: 0x3f8f2f, side: 0x3f8f2f }, /* ...ores, planks, snow, etc. */
 };
 ```
 
+## Voxel palette: the block in hand colors the controls
+
+Use the Blocktopia voxel palette in every voxel app. Keep the game-specific
+colors in one named table, shared by material swatches and HUD controls. Add
+game-specific materials to that table; preserve these colors for matching
+materials. The surrounding app retains its supplied theme's surfaces and text.
+
+```js
+export const VOXEL_PALETTE = {
+  grass: "#6fcf5b", dirt: "#8a5a3b", stone: "#9b9b9b",
+  wood: "#b5793a", glass: "#9fe3ff", candy: "#ff6fb1",
+  neon: "#39ff9e", water: "#2f8fe0", lava: "#ff5a2f",
+  erase: "#ff4d6d", ink: "#1a1325", light: "#ffffff",
+};
+
+function luminance(hex) {
+  const linear = [1, 3, 5].map((i) => {
+    const c = parseInt(hex.slice(i, i + 2), 16) / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return linear[0] * 0.2126 + linear[1] * 0.7152 + linear[2] * 0.0722;
+}
+export function readableInk(background) {
+  const bg = luminance(background);
+  const ratio = (color) => (Math.max(bg, luminance(color)) + 0.05) /
+    (Math.min(bg, luminance(color)) + 0.05);
+  return ratio(VOXEL_PALETTE.ink) >= ratio(VOXEL_PALETTE.light)
+    ? VOXEL_PALETTE.ink : VOXEL_PALETTE.light;
+}
+```
+
+The selected material supplies the active accent; erase mode supplies `erase`.
+Apply it consistently to active view/gravity buttons, action buttons, the
+stage border, selected hotbar ring, and keycap accents. Keep unselected panels
+on theme surfaces (`bg-background/85`, `bg-card`, `text-foreground`) so the
+controls stay readable over sky, water, caves, and bright terrain. Scope the
+variables to the game container, including its HUD and fullscreen subtree:
+
+```jsx
+const accent = eraseMode ? VOXEL_PALETTE.erase : selectedMaterial.color;
+const controlStyle = {
+  backgroundColor: "var(--voxel-accent)",
+  color: "var(--voxel-accent-fg)",
+};
+return <section style={{
+  "--voxel-accent": accent,
+  "--voxel-accent-fg": readableInk(accent),
+  "--voxel-accent-soft": `${accent}33`, // palette colors are six-digit hex
+}}>
+  {/* canvas and HUD share this scope */}
+  <button style={controlStyle} onClick={cycleView}>Switch view</button>
+</section>;
+```
+
+Choose the higher-contrast foreground from `ink` and `light` using sRGB relative
+luminance and contrast ratio ([normal text: at least 4.5:1](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)). For the palette above,
+`dirt` takes white and the other materials and erase take `ink`; recompute for
+additional or customized colors. Apply the same foreground selection to
+hotbar number labels too. A simple brightness threshold can choose white on
+wood, water, or lava even when dark text is more readable. Keep labels/icons,
+`aria-pressed` or `aria-checked`, a visible focus ring, and a two-tone selection
+outline: 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.
+
 ## Rendering: mesh only the EXPOSED blocks (this is the whole performance game)
 
 The single most important rule: **do not create a `THREE.Mesh` per stored
@@ -151,6 +222,14 @@ Raycasting and collision must read `state.blocks` (the full model), never the
 meshes — otherwise you can't hit or collide with a face that isn't currently
 meshed.
 
+For larger worlds, use Block Craft's **exposed-face chunk batching**: append
+only visible faces into a `BufferGeometry` per material per chunk, sharing
+materials across chunks. An edit dirties its chunk and any neighboring chunk
+whose boundary face changes; rebuild only those chunks and dispose their old
+geometries. Keep transparent faces in a separate material pass with deliberate
+occlusion rules. The small-world shared-cube example above remains a simpler
+starting point.
+
 ## Procedural terrain: deterministic noise, layered
 
 Terrain must be a **pure function of world coordinates** so chunks generate
@@ -200,6 +279,19 @@ function loadChunk(cx, cz) {
 }
 ```
 
+### Described islands: save the recipe, regenerate the terrain
+
+For a world described in a sentence, use Blocktopia's approach: ask `callAI`
+for structured generator settings, normalize them, then persist that compact
+recipe with a fixed seed and generator version. Bound map dimensions, heights,
+densities, array lengths, and supported tree/animal kinds before generating.
+Keep a usable flat-world option and preserve the description if generation
+fails. Generate the voxel field locally from the saved recipe on every client;
+save only player overrides. Keep seeded randomness and traversal deterministic,
+and retain the matching generator for existing worlds when generation changes.
+Ambient animals, flowers, clouds, and particles stay capped and local unless
+their shared gameplay state actually needs persistence.
+
 ## Endless streaming: one chunk per frame
 
 Each frame, figure out which chunks should be resident around the player
@@ -258,6 +350,20 @@ toggle** (e.g. `F`) that swaps gravity for direct vertical thrust — great for
 building. Add **sprint** (hold `Shift` while moving forward → higher speed, and
 nudge the camera FOV up a few degrees for a sense of speed).
 
+### Keyboard: game actions keep the page still
+
+During active play, prevent the browser defaults for every key bound to a game action.
+Use `KeyboardEvent.code` for the binding map (`Space`, `ArrowUp`, `KeyW`,
+etc.), and call `event.preventDefault()` in the handled keyboard events so
+Space jumps and arrow keys move without scrolling the page. Apply this only
+while the game has focus or its canvas owns pointer lock, with gameplay active;
+leave typing in chat, inputs, and contenteditable fields, normal button
+activation, and browser shortcuts available outside that input path. CSS
+`touch-action: none` handles touch gestures; keyboard defaults need their own
+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)
 
 Pointer lock is the number-one confusion in browser voxel games: players click
@@ -299,6 +405,32 @@ In the engine, read `movementX/Y` when `document.pointerLockElement === canvas`
 **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.
 
+### 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 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
+terrain blocks the view. Preserve aiming and the player's block-interaction
+reach as the camera moves. Keep the button reachable when pointer lock is
+released, and let the shortcut switch views during locked play.
+
+### Optional fullscreen: keep the HUD with the world
+
+Offer an optional fullscreen button for a larger play area; the Vibes iframe allows fullscreen.
+When included, call `requestFullscreen()` directly from the button's user
+gesture on the game container that includes both the canvas and HUD. Check
+`document.fullscreenEnabled` and method availability, and handle a rejected
+request by keeping play usable in the embedded view. Derive the Enter/Exit
+fullscreen label from `document.fullscreenElement` on `fullscreenchange`, use
+`document.exitFullscreen()` to exit, and resize the renderer and camera aspect
+to the container on entry and exit. Keep fullscreen and pointer lock as
+separate controls; reacquire pointer lock through the click-to-play overlay
+when needed. Remove the fullscreen listener on unmount.
+
 ### No text selection, and bind touch as well as mouse
 
 Two things separate "works on my laptop" from "works", and both are easy to
@@ -368,6 +500,109 @@ when a block breaks — cheap, and it makes mining feel real.
 
 ## Multiplayer: live block edits over Fireproof
 
+### Keep saved edits separate from temporary movement
+
+`useDocument.merge(updates)` updates a local draft and broadcasts its **full
+merged snapshot** to authorized connected peers when it has an `_id`.
+It is a shallow merge, not a durable field-patch API; `save()` persists through
+`database.put()`. The app-facing database has no `database.merge()` method.
+
+Use small, separate documents for different lifetimes:
+
+- **World recipe and membership:** persist the seed, generator settings,
+  version, and world membership once, then only when deliberately changed.
+- **Placed/mined cells:** persist one small override per world and coordinate.
+  Include `worldId` in both the ID and indexed fields when an app has several
+  worlds. Keep a `removed: true` override for mined procedural terrain so it
+  stays gone after reload. Use the consistency model below for concurrent edits.
+- **Inventory, health, and resume checkpoints:** persist per world and player,
+  with change detection and an explicit commit/checkpoint cadence. Commit
+  important collected items when the action completes; a player-pose heartbeat
+  should carry only pose. `save()` still creates a durable write. To commit in
+  the same callback as a draft update, pass the complete next snapshot to
+  `save(snapshot)`; a bare `save()` can read the previous render's draft.
+  A nested object replaces that entire field rather than merging individual
+  coordinates.
+- **Live pose/aim:** use a dedicated presence draft and `merge()` without
+  `save()`. Keep the movement cadence bounded and heartbeat while stationary.
+  Temporary overlays expire after about 12 seconds without updates or when the
+  peer disconnects; they are not a durable resume position or offline edit log.
+- **Activity feed:** use a bounded/coalesced recent-action summary unless a
+  durable audit trail is required. Showing only eight results does not bound
+  storage when every block placement appends a new activity document.
+
+Blocktopia's per-coordinate writes already avoid saving an entire world for
+each block. The useful `merge()` substitution is its recurring **presence**
+write. Block Craft's whole-world snapshot every two seconds combines edits,
+inventory, vitals, and pose; split those lifetimes before adopting its survival
+systems. Fewer durable commits and smaller documents reduce persistence work;
+measure wire bytes and delivery latency separately before claiming faster sync.
+
+For a world whose membership is already established, mount this component
+with `key={worldId + ":" + handle}`. Its hook stays at component scope and
+starts a new draft when the player changes worlds. `poseRef` is the engine's
+latest `{ x, y, z, theta }` snapshot; animation updates that ref without React
+state or database writes:
+
+```jsx
+function PlayerPresence({ worldId, handle, poseRef, useDocument }) {
+  const { merge } = useDocument({
+    _id: `presence:${worldId}:${handle}`, type: "presence",
+    worldId, userHandle: handle,
+  });
+  React.useEffect(() => {
+    let previous = "";
+    let lastSent = 0;
+    const timer = setInterval(() => {
+      const p = poseRef.current;
+      if (!p) return;
+      const pose = { x: p.x, y: p.y, z: p.z, theta: p.theta };
+      const stamp = JSON.stringify(pose);
+      const now = Date.now();
+      if (stamp === previous && now - lastSent < 5000) return;
+      merge({ ...pose, at: now });
+      previous = stamp;
+      lastSent = now;
+    }, 350);
+    return () => clearInterval(timer);
+  }, [merge, poseRef]);
+  return null;
+}
+```
+
+Peers can receive this never-saved row through a live query on `worldId`;
+the temporary overlay supplies the index fields. The access function must
+validate the sender's identity, bind `_id` to its world/player, validate finite
+pose coordinates, and require world membership before returning the existing
+world channel. Persist the world/invitation that grants that membership first:
+a presence broadcast does not create grants. Use this matching branch in the
+multi-world access function (the single-world example later uses different IDs
+and `authorHandle`):
+
+```js
+if (doc.type === "presence") {
+  if (!user || doc.userHandle !== user.userHandle) throw { forbidden: "not you" };
+  if (typeof doc.worldId !== "string" || !doc.worldId) throw { forbidden: "world required" };
+  if (doc._id !== `presence:${doc.worldId}:${user.userHandle}`) throw { forbidden: "presence ID" };
+  if (![doc.x, doc.y, doc.z, doc.theta, doc.at].every(Number.isFinite)) throw { forbidden: "invalid pose" };
+  const channel = `world:${doc.worldId}`;
+  ctx.requireAccess(channel);
+  return { channels: [channel] };
+}
+```
+
+A hidden or disconnected tab may miss its heartbeat, so peers expire it rather
+than treating it as saved state. Use receiver arrival time for update freshness.
+Rely on disconnect/expiry for departure:
+an unmount-time `merge()` can be canceled before broadcast. This example uses
+one presence ID per handle; independent same-handle tabs need a session suffix
+and access rules that validate that ID. During migration from saved presence,
+admit old durable rows only if their timestamps are plausibly fresh; their
+first query arrival or reappearance after overlay expiry is not a heartbeat.
+Alternatively, use a distinct ephemeral namespace with matching access rules.
+
+### Choose the durable edit conflict model
+
 **Know exactly what the substrate gives you before you design for it.** A live
 query returns the **full, latest-per-document result set**, deliveries are
 **unordered** (notifications can be delayed; overlapping re-queries can resolve
@@ -406,6 +641,11 @@ so **there is no free lunch here.** Pick a model with eyes open:
 
 ### Model A: one doc per coordinate
 
+The durable examples below use a single shared world. For a world picker,
+carry `worldId` through document IDs, queries, reset watermarks, accumulator
+lifecycles, and access checks together; use one channel per world. Keep a reset
+in one world from invalidating edits or inventories in another.
+
 Give the doc a **deterministic `_id` of `block:<key>`** so every edit at a
 coordinate updates the same doc — the database stays one-doc-per-cell instead of
 replaying every historical value. A break writes a `removed: true` tombstone at
@@ -739,7 +979,7 @@ tables once in `core.js` and every system (mining, crafting, combat, UI) reads
 them — adding content then means adding rows, not code:
 
 ```js
-export const BLOCKS = [ { id: "grass", name: "Grass", top: 0x5fbf3f, side: 0x7a5230, drops: "dirt" }, /* … */ ]
+export const BLOCKS = [ { id: "grass", name: "Grass", top: 0x6fcf5b, side: 0x8a5a3b, drops: "dirt" }, /* … */ ]
 export const ITEMS = { plank: { name: "Plank" }, stick: { name: "Stick" }, ironIngot: { name: "Iron Ingot" }, /* … */ }
 export const RECIPES = [
   { id: "planks", out: { plank: 4 }, needs: { wood: 1 } },
@@ -772,10 +1012,11 @@ The systems that ride those tables:
 - **World depth** — keep a real vertical range (e.g. bedrock at `y = -128`)
   so caves and ores have somewhere to live.
 
-Persist the survival state as typed docs (see access function below): one
-`inventory` doc per player (`inv:<handle>`), and a `worldReset` singleton the
-owner writes — clients ignore voxel edits older than its timestamp, which
-resets the shared world without deleting anything.
+Persist the survival state as typed docs (see the single-world access function
+above): one `inventory` doc per player (`inv:<handle>`), and a `worldReset`
+singleton the owner writes — clients ignore voxel edits older than its
+timestamp. For several worlds, scope these IDs and queries by world as well
+(`inv:<worldId>:<handle>`), and update the access checks to enforce that scope.
 
 ## Ambient life & atmosphere (cheap, high-impact)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "14.3.0",
+  "version": "14.3.1",
   "type": "module",
   "main": "./index.js",
   "exports": {
@@ -37,9 +37,9 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/call-ai-v2": "14.3.0",
-    "@vibes.diy/identity": "14.3.0",
-    "@vibes.diy/use-vibes-types": "14.3.0",
+    "@vibes.diy/call-ai-v2": "14.3.1",
+    "@vibes.diy/identity": "14.3.1",
+    "@vibes.diy/use-vibes-types": "14.3.1",
     "arktype": "~2.2.3",
     "json-schema-faker": "~0.6.3"
   },