@stage5/lumine 0.2.51 → 0.2.52

package/lib/constants.js

@@ -115,6 +115,8 @@ export const BUNDLED_SDK_REFERENCE_URL = new URL(
   import.meta.url,
 );
 export const PACKAGE_METADATA_URL = new URL("../package.json", import.meta.url);
+export const LUMINE_WORLD_UPDATE_GUIDANCE = `- For Twinkle.world realtime presence, keep render/input loops local. Queue an update only when relevant state changes, replace any queued snapshot with the newest one, and flush on a fixed 5-15 updates-per-second schedule with at most one updatePresence request in flight. Never call or await updatePresence every animation frame, resend unchanged snapshots, overlap requests, or build a backlog.
+- Send Twinkle.world actions only when the discrete action happens; do not poll or automatically retry them. On WORLD_EVENT_RATE_LIMITED or another recoverable non-session-ended error, drop that attempted presence/action update without an immediate retry and keep the session. Reconnect with backoff only after session.ended or Twinkle.world.isSessionEndedError(error).`;
 export const SDK_REFERENCE_FALLBACK = `${LUMINE_SDK_REFERENCE_MARKER}
 # Twinkle Build SDK Reference
 
@@ -131,6 +133,7 @@ Use these current source-of-truth rules:
 - Use Twinkle.aiStories.list/search/get for existing AI Story passage text, story media, and questions.
 - Use Twinkle.ai.chat with history entries shaped as { role, content }, not { text }. Live web search is enabled by default; pass webSearch: false to disable it for the app.
 - Use Twinkle.preview for canvas, WebGL, Three.js, fullscreen, and game layout.
+${LUMINE_WORLD_UPDATE_GUIDANCE}
 - Prefer existing documented Twinkle.* methods over guessing names from old code.
 `;
 export const LUMINE_THREE_VENDOR_GUIDANCE = `- For Three.js, use the first-party core module: import * as THREE from '${BUILD_VENDOR_THREE_MODULE_IMPORT}';
@@ -285,6 +288,7 @@ lumine save --summary "Describe the change"
 ${LUMINE_THREE_VENDOR_GUIDANCE}
 - Do not invent or guess Twinkle.* SDK method names. Use ${SDK_REFERENCE_FILE} as the local SDK reference and prefer Twinkle.capabilities checks for gated features.
 - Match storage to update frequency. Twinkle.privateDb and Twinkle.sharedDb are for LOW-frequency durable state only — things that change on a user action (settings, inventory checkpoints, completed quests, saved progress; comments, votes, room settings, submitted records). NEVER write high-frequency or per-frame/per-tick state to them (camera or cursor position, animation state, live movement, presence, autosave every frame/tick). Keep live state in client memory, broadcast realtime/presence via Twinkle.world, and for durable per-user state flush an occasional snapshot on an interval or on exit (never per frame) — e.g. the viewer/user DB or a single latest-snapshot key. The server rate-limits these writes per key and returns 429 on excess; never retry-loop a 429.
+${LUMINE_WORLD_UPDATE_GUIDANCE}
 
 ## Local Testing (Playwright / browser probes)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.51",
+  "version": "0.2.52",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.37.0
-Updated: 2026-08-25
-Generated: 2026-08-25T02:01:15.207Z
+Version: 1.37.2
+Updated: 2026-08-26
+Generated: 2026-08-26T15:17:11.027Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -341,7 +341,7 @@ renderBattery(policy?.energyPercent, policy?.energySegmentsRemaining);
   - Use this for in-app AI replies instead of creating or fetching app-local endpoints such as /api/chat.
   - Example: const chatHistory = conversation.slice(-12).map((entry) => ({ role: entry.role === 'assistant' ? 'assistant' : 'user', content: entry.text }));
 const result = await Twinkle.ai.chat({ message, history: chatHistory, systemPrompt: 'You are a cheerful pirate helper who answers in one sentence.', onText: (text, meta) => renderReply(text), onStatus: (status) => setThinking(status === 'thinking') });
-- async generateObject({ prompt, expectedStructure, thinkingMode, mode, model, instructions, systemPrompt, webSearch, requestId, onText, onStatus } = {}) | scopes: none
+- async generateObject({ prompt, expectedStructure, thinkingMode, mode, model, instructions, systemPrompt, webSearch, requestId, onText, onStatus, onReasoning } = {}) | scopes: none
   - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, requestedModel, webSearch, aiUsagePolicy }
   - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic, with optional live output/status callbacks and web search.
   - Signed-in viewers only.
@@ -353,13 +353,14 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - thinkingMode medium uses Grok 4.6 with medium reasoning and consumes normal AI Energy.
   - thinkingMode high without model uses GPT-5.6 Sol with high reasoning and consumes high AI Energy. Explicit model: 'gpt-5.6-sol' selects Sol with xhigh reasoning at the same High AI Energy tier.
   - claude-opus-5 uses Anthropic adaptive High thinking. claude-fable-5 uses Anthropic xhigh thinking and normally consumes more AI Energy for comparable token use. Both debit confirmed provider usage at the High tier.
-  - Pass onStatus and/or onText to stream progress from the same structured generation. onStatus receives high-level phases such as thinking, searching_web, responding, validating, and completed.
+  - Pass onStatus, onReasoning, and/or onText to stream progress from the same structured generation. onStatus receives high-level phases such as thinking, searching_web, responding, validating, and completed.
+  - onReasoning receives accumulated provider-supplied, app-visible reasoning summaries plus { done, delta, requestId, status }. A provider retry may replace the accumulated summary; treat each callback's first argument as the current source of truth. This callback never exposes hidden/private model chain-of-thought.
   - onText receives accumulated structured-output text plus { done, delta, requestId, status }. Partial output is intentionally incomplete and may include provider formatting; parse only when done is true, when the callback receives the canonical object serialized as JSON, and use the resolved object as the source of truth.
-  - Streaming exposes app-visible structured output and high-level phases, not private model chain-of-thought. Put a user-facing field such as producerNotes in expectedStructure when the app should display model-authored commentary from the same generation.
+  - Put a user-facing field such as producerNotes in expectedStructure when commentary must be part of the validated final object rather than transient reasoning progress.
   - When AI Energy is empty, every automatic or named model choice rejects before new provider work; there is no free fallback mode.
   - Live web search is enabled by default in Medium and High modes. Pass webSearch: false to disable it for the app. Low/Lite Mode remains tool-free; explicitly forcing webSearch: true in Low Mode returns an error.
-  - The server validates the final shape; automatic OpenAI/xAI routes can retry malformed output, while explicit Anthropic routes use native JSON Schema output. App code should still validate business-specific enum values.
-  - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'high', model: 'claude-opus-5', prompt: 'Plan the next section from: ' + currentState, expectedStructure: { producerNotes: 'string', action: 'string', confidence: 0 }, onStatus: (phase) => showPhase(phase), onText: (partialJson, meta) => showStructuredProgress(partialJson, meta) });
+  - The server validates the final shape; automatic OpenAI/xAI routes can retry malformed output, while explicit Anthropic routes use native JSON Schema output and retry one malformed or shape-invalid result. App code should still validate business-specific enum values.
+  - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'high', model: 'claude-opus-5', prompt: 'Plan the next section from: ' + currentState, expectedStructure: { producerNotes: 'string', action: 'string', confidence: 0 }, onStatus: (phase) => showPhase(phase), onReasoning: (summary, meta) => showReasoningProgress(summary, meta), onText: (partialJson, meta) => showStructuredProgress(partialJson, meta) });
 - onChatStatus(listener) | scopes: none
   - Returns: unsubscribe function
   - Listen to shared runtime AI chat stream events.
@@ -742,7 +743,8 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Signed-in player identity comes from the canonical Twinkle user record; player.profilePicUrl is only used for guests and is returned only when it is a valid absolute HTTPS URL.
   - Subscribe to session.ended and catch updatePresence/send errors. Stop using stale handles and reconnect only when Twinkle.world.isSessionEndedError(error) is true; for other Twinkle.world.isRecoverableSessionError(error) cases, drop the transient presence/action and keep the handle.
   - Use updatePresence for live avatar snapshots and send for lightweight actions such as emotes, interactions, and chat bubbles.
-  - Throttle movement updates in app code, usually 5-15 updates per second. Do not call updatePresence from every animation frame.
+  - Treat the render/input loop as local-only. Queue presence only after relevant fields change, replace any queued snapshot with the newest one, and flush on a fixed 5-15 updates-per-second schedule with at most one updatePresence request in flight. Never call or await updatePresence every animation frame, resend unchanged snapshots, overlap requests, or build a backlog.
+  - Send discrete actions only when they happen; do not poll or automatically retry them. The parent limits updatePresence and send together to protect the website connection. WORLD_EVENT_RATE_LIMITED is recoverable: drop that attempted update without an immediate retry and keep the current session.
   - Rooms are addressed by worldKey, roomKey, and instanceId so the contract can later move to sharded or dedicated game backends.
   - Example: const world = await Twinkle.world.join({ roomKey: 'town-square', presence: { x: 0, y: 0, z: 0, facing: 'south' }, player: { name: avatarName } });
 world.subscribe((event) => updateRemotePlayers(event.players));
@@ -750,8 +752,8 @@ world.updatePresence({ x, y, z, facing });
 - isRecoverableSessionError(error) | scopes: none
   - Returns: boolean
   - Return true when a world request error is expected to be handled by app code instead of crashing.
-  - Recoverable session errors include ended, missing, socket-disconnected, socket-not-ready, room-missing, preview-updating, and timed-out world session requests.
-  - Only session-ended errors prove that the current handle should be discarded. Timed-out or preview-updating presence requests can be dropped without reconnecting.
+  - Recoverable session errors include ended, missing, socket-disconnected, socket-not-ready, room-missing, rate-limited, preview-updating, and timed-out world session requests.
+  - Only session-ended errors prove that the current handle should be discarded. WORLD_EVENT_RATE_LIMITED, timed-out, or preview-updating presence/action requests must be dropped without reconnecting and without an immediate retry.
   - For durable game state, write through sharedDb/privateDb instead of relying on world presence — but LOW-frequency only (on a user action or an occasional snapshot, never per frame/tick).
   - Example: try {
   await world.updatePresence({ x, y, z, facing });
@@ -1028,59 +1030,104 @@ Keywords: multiplayer, mmo, town, presence, avatars, movement, three.js, realtim
 
 ```js
 let world = null;
+let worldConnection = null;
 let reconnectTimer = 0;
+let reconnectDelayMs = 1000;
+let latestPresence = { x: 0, y: 0, z: 0, facing: 'south', animation: 'idle' };
+let latestPresenceKey = JSON.stringify(latestPresence);
+let queuedPresence = null;
+let presenceInFlight = false;
 
 async function connectWorld() {
   if (world) return world;
-  world = await Twinkle.world.join({
-    worldKey: 'town',
-    roomKey: 'square',
-    presence: { x: 0, y: 0, z: 0, facing: 'south', animation: 'idle' },
+  if (worldConnection) return worldConnection;
+  const presenceAtJoin = latestPresence;
+  const presenceKeyAtJoin = latestPresenceKey;
+  worldConnection = Twinkle.world.join({
+    worldKey: 'town', roomKey: 'square', presence: presenceAtJoin,
     player: { name: avatarName }
   });
+  try {
+    const session = await worldConnection;
+    world = session;
+    reconnectDelayMs = 1000;
+    session.subscribe((event) => {
+      renderPlayers(event.players);
+      if (event.type === 'session.ended') handleWorldDrop(session);
+      if (event.type === 'action.received' && event.action?.type === 'emote') {
+        showEmote(event.sessionId, event.action.data.emote);
+      }
+    });
+    if (latestPresenceKey !== presenceKeyAtJoin) queuedPresence = latestPresence;
+    return session;
+  } finally {
+    worldConnection = null;
+  }
+}
 
-  world.subscribe((event) => {
-    renderPlayers(event.players);
-    if (event.type === 'session.ended') {
-      handleWorldDrop();
-    }
-    if (event.type === 'action.received' && event.action?.type === 'emote') {
-      showEmote(event.sessionId, event.action.data.emote);
-    }
-  });
-  return world;
+function handleWorldConnectError(error) {
+  if (Twinkle.world.isRecoverableSessionError(error)) {
+    scheduleReconnect();
+  } else {
+    console.error('World connection failed', error);
+  }
+}
+
+function scheduleReconnect() {
+  if (reconnectTimer || world || worldConnection) return;
+  const delay = reconnectDelayMs;
+  reconnectDelayMs = Math.min(30000, reconnectDelayMs * 2);
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = 0;
+    connectWorld().catch(handleWorldConnectError);
+  }, delay);
 }
 
-function handleWorldDrop() {
+function handleWorldDrop(session = world) {
+  if (session && world && world !== session) return;
   world = null;
-  if (!reconnectTimer) {
-    reconnectTimer = setTimeout(() => {
-      reconnectTimer = 0;
-      connectWorld().catch(handleWorldDrop);
-    }, 1000);
-  }
+  queuedPresence = null;
+  scheduleReconnect();
+}
+
+function queuePresence(next) {
+  const key = JSON.stringify(next);
+  if (key === latestPresenceKey) return;
+  latestPresenceKey = key;
+  latestPresence = next;
+  if (world) queuedPresence = next; // Coalesce to the newest unsent snapshot.
 }
 
-async function syncPresence() {
+async function flushPresence() {
+  if (presenceInFlight || !queuedPresence || !world) return;
+  const session = world;
+  const next = queuedPresence;
+  queuedPresence = null;
+  presenceInFlight = true;
   try {
-    const session = await connectWorld();
-    // Throttle this in the game loop, for example 5-15 times per second.
-    await session.updatePresence({ x: player.x, y: player.y, z: player.z, facing });
+    await session.updatePresence(next);
   } catch (error) {
     if (Twinkle.world.isSessionEndedError(error)) {
-      handleWorldDrop();
-      return;
+      handleWorldDrop(session);
+    } else if (!Twinkle.world.isRecoverableSessionError(error)) {
+      console.error('World update failed', error);
     }
-    if (Twinkle.world.isRecoverableSessionError(error)) {
-      // Drop this transient presence update and keep the current handle.
-      return;
-    }
-    throw error;
+    // Recoverable errors drop this transient snapshot without an immediate retry.
+  } finally {
+    presenceInFlight = false;
   }
 }
 
-await connectWorld();
-await syncPresence();
+// The render/input loop only queues changed local state.
+function onPlayerStateChanged() {
+  queuePresence({
+    x: player.x, y: player.y, z: player.z,
+    facing, animation: player.animation
+  });
+}
+
+connectWorld().catch(handleWorldConnectError);
+setInterval(() => { void flushPresence(); }, 100); // Fixed 10 Hz cap.
 ```
 
 ### Play chess against the computer