@stage5/lumine 0.3.58 → 0.3.60

package/README.md

@@ -134,6 +134,15 @@ version, records the same save metadata, and marks public builds as having
 unpublished changes. For projects you own, run `lumine launch` to publish the
 saved changes, or `lumine save --publish` to save and publish in one step.
 
+For automation, `lumine save --json` emits one canonical JSON receipt with
+`schemaVersion`, `ok`, the saved artifact metadata, `build`, and `publication`.
+`lumine versions --json` returns the server's version history without prose.
+If `save --publish --json` saves successfully but publication fails, the receipt
+still identifies that saved version, sets `ok: false`, and reports the publication
+error; the command exits nonzero. A contribution branch reports
+`publication.published: false` with `reason: "contribution_requires_owner"`.
+Saving a branch does not publish the owner's app.
+
 Pulled workspaces include `AGENTS.md` and `CLAUDE.md` guides for local coding
 agents, `TWINKLE_BUILD_SDK.md` with the current Build SDK reference, plus
 `.twinkle/lumine-project.json` metadata that tells agents whether the checkout

package/lib/admin.js

@@ -5877,8 +5877,14 @@ function printAdminMonthlyAiCosts(monthlyAiCosts) {
 
 function printAdminDailyAiCosts(dailyAiCosts) {
   console.log(
-    `Application AI-cost ledger for ${dailyAiCosts.day.dayKey} (closed UTC day): ${formatAdminUsd(dailyAiCosts.summary?.estimatedCostUsd)} across ${Number(dailyAiCosts.summary?.requestCount || 0)} request(s).`,
+    `Application AI usage before credits for ${dailyAiCosts.day.dayKey} (closed UTC day): ${formatAdminUsd(dailyAiCosts.summary?.estimatedCostUsd)} across ${Number(dailyAiCosts.summary?.requestCount || 0)} request(s).`,
   );
+  const credit = dailyAiCosts.creditAccounting;
+  if (credit?.status === "estimated" && Number.isFinite(credit.creditUsd) && Number.isFinite(credit.estimatedCashUsd)) {
+    console.log(`Promotional credit: ${formatAdminUsd(credit.creditUsd)}; estimated cash cost: ${formatAdminUsd(credit.estimatedCashUsd)}.`);
+  } else {
+    console.log("Promotional credit and estimated cash cost unavailable; the usage total above is before credits.");
+  }
   for (const row of dailyAiCosts.byProviderModel || []) {
     console.log(
       `  ${row.provider || "unknown"}/${row.model || "unknown"}: ${formatAdminUsd(row.estimatedCostUsd)} · ${Number(row.totalTokens || 0)} token(s) · ${Number(row.requestCount || 0)} request(s).`,

package/lib/agent.js

@@ -116,6 +116,24 @@ export async function agentCommand(options, { saveWorkspace }) {
   let saveResult = null;
   let scopeRepairAttempts = 0;
   let validationRepairAttempts = 0;
+  // The last candidate whose only issues were platform-rule notices. Their
+  // repair is optional: if it breaks the code or fails, this one is saved.
+  let noticesOnlyFiles = null;
+  // The reply written with that candidate: a later repair's reply may
+  // describe fixes that are not in it.
+  let noticesOnlyFinalText = "";
+  async function restoreNoticesOnlyCandidate(fromFiles, reason) {
+    await replaceWorkspaceWithSnapshot({
+      dir: workspace.dir,
+      currentFiles: fromFiles,
+      snapshotFiles: noticesOnlyFiles,
+    });
+    currentFiles = noticesOnlyFiles;
+    finalText = `${noticesOnlyFinalText}\n\nOne small fix is still open: part of this may not work inside Twinkle yet (see the platform rule notices from lumine check).`.trim();
+    console.error(
+      `Lumine: ${reason}; saving the earlier version, which only had platform rule notices.`,
+    );
+  }
 
   console.log(
     `Running ${provider.label} through Lumine's workspace loop (Twinkle AI Energy: 0).`,
@@ -147,20 +165,30 @@ export async function agentCommand(options, { saveWorkspace }) {
               initialFiles: currentFiles,
             })
           : null;
-      const providerResult = await provider.runPass({
-        options,
-        runtime,
-        toolSession,
-        isolationDir,
-        mcp: {
-          cliPath: CLI_PATH,
-          dir: workspace.dir,
-          runtimeFile: artifacts.runtimeFile,
-          traceFile: artifacts.traceFile,
-          buildId: workspace.buildId,
-          baseFilesHash: workspace.baseFilesHash,
-        },
-      });
+      let providerResult;
+      try {
+        providerResult = await provider.runPass({
+          options,
+          runtime,
+          toolSession,
+          isolationDir,
+          mcp: {
+            cliPath: CLI_PATH,
+            dir: workspace.dir,
+            runtimeFile: artifacts.runtimeFile,
+            traceFile: artifacts.traceFile,
+            buildId: workspace.buildId,
+            baseFilesHash: workspace.baseFilesHash,
+          },
+        });
+      } catch (error) {
+        if (!noticesOnlyFiles || runtime.phase !== "validation_repair") throw error;
+        await restoreNoticesOnlyCandidate(
+          await collectAgentProjectFiles(workspace.dir),
+          `the notice repair failed (${error?.message || error})`,
+        );
+        break;
+      }
       finalText = String(providerResult?.finalText || "").trim() || finalText;
       providerRuns.push({
         phase: runtime.phase,
@@ -213,8 +241,19 @@ export async function agentCommand(options, { saveWorkspace }) {
         reason: String(validation.reason || "").slice(0, 1000),
       });
       console.error(`Lumine validation: ${validation.reason}`);
+      if (validation.platformRuleNoticesOnly) {
+        noticesOnlyFiles = candidateFiles;
+        noticesOnlyFinalText = finalText;
+      }
 
       if (validation.kind === "scope") {
+        if (runtime.phase === "validation_repair" && noticesOnlyFiles) {
+          await restoreNoticesOnlyCandidate(
+            candidateFiles,
+            "the notice repair went beyond its scope",
+          );
+          break;
+        }
         if (runtime.phase === "validation_repair") {
           // A validation-repair pass is intentionally allowed only a tiny
           // corrective diff. If it exceeds that scope, retire its local file
@@ -249,6 +288,13 @@ export async function agentCommand(options, { saveWorkspace }) {
         });
         currentFiles = scopeBaseFiles;
       } else {
+        if (validationRepairAttempts >= 2 && noticesOnlyFiles) {
+          await restoreNoticesOnlyCandidate(
+            candidateFiles,
+            "the notice repair did not pass validation",
+          );
+          break;
+        }
         if (validationRepairAttempts >= 2) {
           throw new Error(
             "The external agent could not pass Lumine validation after two repair attempts. Its local candidate remains unsaved for inspection.",

package/lib/commands.js

@@ -1276,7 +1276,7 @@ export async function save(options) {
     lastSavedAt: new Date().toISOString(),
     filesHash: typeof result.filesHash === "string" ? result.filesHash : null,
   });
-  if (!options.quiet) {
+  if (!options.quiet && !options.json) {
     printSaveResult({
       result,
       build,
@@ -1286,14 +1286,31 @@ export async function save(options) {
     });
   }
 
+  const jsonReceipt = (publication = null, ok = true) => {
+    if (options.json && !options.quiet)
+      console.log(JSON.stringify({ ...result, schemaVersion: 1, ok, build, publication }));
+  };
   if (options.publish) {
     if (build?.canPublish === false) {
-      console.log(
+      if (!options.json) console.log(
         "Saved to your branch. The project owner can merge or replace main from Twinkle.",
       );
+      jsonReceipt({ published: false, reason: "contribution_requires_owner" });
+      return result;
+    }
+    let publish;
+    try { publish = await publishBuild({ options, buildId, auth }); }
+    catch (error) {
+      // Saving already succeeded. Preserve its exact receipt even if the
+      // separate publication fails; the command still exits nonzero.
+      jsonReceipt({ published: false, error: String(error?.message || error) }, false);
+      throw error;
+    }
+    if (options.json) {
+      build = publish.build || build;
+      jsonReceipt({ published: true, skipped: Boolean(publish.skipped), build: publish.build || null });
       return result;
     }
-    const publish = await publishBuild({ options, buildId, auth });
     if (publish.skipped) {
       console.log("Publish skipped: already up to date.");
     } else {
@@ -1304,6 +1321,7 @@ export async function save(options) {
     );
     console.log(`App: ${options.siteUrl}/app/${buildId}`);
   }
+  jsonReceipt();
   return result;
 }
 
@@ -1480,6 +1498,20 @@ export function printCheck(result) {
   for (const conflictPath of checks.conflictMarkers?.paths || []) {
     console.log(`  conflict marker: ${conflictPath}`);
   }
+  // Platform-rule notices never fail a check or a launch; they point at code
+  // that will not work inside Twinkle's frame (see Platform Rules in AGENTS.md).
+  const notices = checks.platformRuleNotices?.diagnostics || [];
+  if (notices.length) {
+    console.log(
+      `- platform rule notices: ${checks.platformRuleNotices.count} (do not block)`,
+    );
+    for (const diagnostic of notices) {
+      console.log(
+        `  ${diagnostic.kind} ${diagnostic.filePath}` +
+          `${diagnostic.line ? `:${diagnostic.line}` : ""} ${diagnostic.message}`,
+      );
+    }
+  }
 }
 
 export async function loadTargetBuildMetadata({ options, auth }) {
@@ -1979,7 +2011,8 @@ export async function versionsCommand(options) {
     buildId,
     limit: options.limit,
   });
-  printVersionList({ result });
+  if (options.json) console.log(JSON.stringify(result));
+  else printVersionList({ result });
 }
 
 export function printVersionList({ result }) {
@@ -3196,7 +3229,7 @@ export function printHelp() {
   lumine pull [twinkle-build-url] --main
   lumine pull [twinkle-build-url] --version <n> [--main]
   lumine pull [twinkle-build-url] --published [--main]
-  lumine versions [twinkle-build-url] [--main] [--limit <n>]
+  lumine versions [twinkle-build-url] [--main] [--limit <n>] [--json]
   lumine restore <n> [--main]
   lumine reference <twinkle-build-url>
   lumine fork <twinkle-build-url>
@@ -3204,7 +3237,7 @@ export function printHelp() {
   lumine merge <twinkle-branch-url>
   lumine replace-main <twinkle-branch-url>
   lumine update-from-main [twinkle-branch-url]
-  lumine save
+  lumine save [--summary <text>] [--publish] [--json]
   lumine check [twinkle-build-url]
   lumine launch [twinkle-build-url]
   lumine sdk list

package/lib/constants.js

@@ -1,6 +1,7 @@
 import os from "os";
 import path from "path";
 import { LUMINE_BUILDER_STANCE } from "./builderStance.generated.js";
+import { LUMINE_PLATFORM_RULES } from "./platformRules.generated.js";
 
 export const DEFAULT_API_URL = "https://api.twinkle.network";
 export const DEFAULT_SITE_URL = "https://www.twin-kle.com";
@@ -134,9 +135,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_MOBILE_SELECTION_GUIDANCE = `- Mobile long-press must not select game UI or open the browser's Copy/Look Up/image menu. The SDK protects standard buttons, button-like ARIA controls, and canvases. Mark the entire gameplay wrapper data-twinkle-no-select (including HUD, labels, scores, menus, controls, and empty play space); also apply user-select: none, -webkit-user-select: none, and -webkit-touch-callout: none for local previews. Protecting only one button or the canvas is insufficient.
-- On a played game page (a play-sized canvas, or data-twinkle-game on <html>/<body>) the SDK also blocks text selection, the long-press menu and page pinch-zoom everywhere except inputs, contenteditable and data-twinkle-selectable text. A game that sizes itself with Twinkle.preview should set data-twinkle-game; data-twinkle-document keeps a canvas page (charts, drawing pad) an ordinary page; data-twinkle-allow-zoom keeps pinch-zoom on a game.
-- Keep inputs/contenteditable usable. Mark genuinely copyable story/chat/user-written text data-twinkle-selectable and style it with user-select: text, -webkit-user-select: text, and -webkit-touch-callout: default. Do not blanket-disable selection on document/readers or preventDefault on document-wide touch/pointer events. Test holding controls, the HUD, and empty play space in mobile Safari and Chromium, then verify release/cancel, scrolling, typing, and copying. lumine check only detects a missing no-selection rule; a pass does not prove selector coverage or mobile behavior.`;
+export const LUMINE_MOBILE_SELECTION_GUIDANCE = `- Pages marked data-twinkle-game (or showing a play-sized canvas) block text selection, the long-press menu and page pinch-zoom outside inputs, contenteditable and data-twinkle-selectable text; data-twinkle-allow-zoom keeps pinch-zoom. Do not blanket-disable selection or preventDefault document-wide touch/pointer events on reading pages.
+- After changing game input, check on mobile Safari and Chromium that holding controls, release/cancel, scrolling, typing and copying still work. The long-press part of lumine check only detects a missing no-selection rule; a pass does not prove selector coverage or mobile behavior.`;
 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}
@@ -154,8 +154,12 @@ Use these current source-of-truth rules:
 - Use Twinkle.aiCards.list/search/get for existing public AI Card words, exampleText sentence material, and word levels.
 - 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_MOBILE_SELECTION_GUIDANCE}
+
+## Platform Rules
+
+${LUMINE_PLATFORM_RULES}
+
 ${LUMINE_WORLD_UPDATE_GUIDANCE}
 - Prefer existing documented Twinkle.* methods over guessing names from old code.
 `;
@@ -179,6 +183,14 @@ Lumine CLI as the source of truth for saving this workspace back to Twinkle.
 
 ${LUMINE_BUILDER_STANCE}
 
+## Platform Rules
+
+${LUMINE_PLATFORM_RULES}
+
+\`lumine check\` fails on forms, imports, SDK names, game layout and long-press
+selection, and lists canvas page kind, dialogs and new windows as platform
+rule notices (they do not block); a pass does not prove the other rules.
+
 ## Source Of Truth
 
 - Read .twinkle/lumine-project.json before changing files.
@@ -347,15 +359,12 @@ lumine save --summary "Describe the change"
 
 ## App Constraints
 
-- Use local project files with relative or root-local imports only. Do not add package imports, CDN scripts, external network calls, or app-local /api/* routes.
-- Build apps run in sandboxed iframes without allow-forms. Do not use <form> elements, native form submission, requestSubmit(), or browser form navigation. Build input flows with JavaScript-handled inputs and buttons instead.
+The Platform Rules above come first; these add detail.
+
 ${LUMINE_MOBILE_SELECTION_GUIDANCE}
-- CAUTION: the preview runtime AUTO-DETECTS "game apps" — any <canvas> in the body except a small one on screen (both sides at most 160 CSS px: a visualizer, a sparkle, an icon) switches the app to viewport-app mode: html/body get overflow:hidden !important and body becomes a centering flexbox, so tall document-flow pages clip and stop scrolling. A hidden or not-yet-sized canvas counts too, and a page that sets data-twinkle-game keeps this layout with any canvas. Document-style apps with a larger canvas (a chart, a drawing pad, a background effect) set data-twinkle-document on <html> or <body>, or call Twinkle.preview.subscribe (or getLayout/reserveInsets) early at boot and then pad by layout.safeInsets and scroll within layout.viewport.height.
-- For canvas, WebGL, Three.js, fullscreen, or game builds, use Twinkle.preview for layout. Do not size roots from 100vh, 100vw, 100dvh, 100dvw, window.innerWidth, window.innerHeight, visualViewport, or document viewport dimensions.
 ${LUMINE_THREE_VENDOR_GUIDANCE}
 ${LUMINE_MATH_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/lib/platformRules.generated.js

@@ -0,0 +1,3 @@
+// Generated by twinkle-api/scripts/generate-build-sdk-index.mjs from
+// constants/buildSdkManifest.json (platformRules). Do not edit by hand.
+export const LUMINE_PLATFORM_RULES = "Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.\n\n1. Every page that draws on a <canvas> (2D, WebGL or Three.js) says what kind of page it is on <html>: data-twinkle-game for a game that fills the screen, data-twinkle-document for a normal scrolling page with a drawing pad, chart, visualizer or background effect. Without it, unless the page lays itself out with Twinkle.preview, Twinkle guesses from the canvas, and any canvas larger than 160 px, even one hidden in a tab, locks the page to one screen so it no longer scrolls. Add the attribute together with the first canvas.\n2. Games (data-twinkle-game) size themselves from Twinkle.preview: subscribe with Twinkle.preview.subscribe(listener, { immediate: true }), size canvases and renderers from layout.stage or layout.viewport, and report the play area with Twinkle.preview.setPlayfield(). Never size a game from 100vh/100vw, window.innerWidth/innerHeight or visualViewport, and never draw a fake phone or browser frame unless the creator asks for a device mockup: those fight the host and leave the game blank, cropped or scrolling on phones. Pages marked data-twinkle-document use ordinary CSS layout instead.\n3. alert(), confirm() and prompt() are silently blocked: alert shows nothing, confirm() always returns false (so the action it guards never happens) and prompt() returns null. Use in-page UI instead: a message element, an in-page confirm step, an <input>.\n4. Apps cannot open new windows or tabs: window.open() and target=\"_blank\" links do nothing, and neither does a download link to an uploaded file. Open Twinkle pages with Twinkle.app.openContent(url) from a tap, save files with Twinkle.files.saveAs({ url, fileName }) (or { blob, fileName } for a file the app made), and show other web addresses as plain text.\n5. Do not use <form> elements: native form submission is blocked, so a submit button inside a form does nothing. Handle inputs and buttons in JavaScript.\n6. Code loads only from project files and Twinkle's vendor paths (/build/vendor/...). Package imports, CDN scripts, external network calls and app-local /api/* routes fail at runtime; use the Twinkle SDK for data, AI and storage.\n7. Call only Twinkle.* methods documented in the SDK reference. An invented or guessed method name throws and breaks the feature.\n8. Twinkle.privateDb and Twinkle.sharedDb save on a user action or as an occasional snapshot, never per frame, tick or keystroke: fast repeated writes are refused with 429 and the data is lost. A privateDb value is at most 16 KB. Keep live state in memory, and use Twinkle.world for realtime multiplayer.\n9. Start sound and image generation inside the viewer's tap or click handler. A Web Audio AudioContext stays silent until it is created or resumed in a tap (iPhones always enforce this), and Twinkle.ai.generateImage called from load or a timer fails with USER_ACTIVATION_REQUIRED.\n10. Call setPointerCapture only inside a pointerdown handler with that event's pointerId, wrapped in try/catch, and release only when hasPointerCapture says the element holds it. From click, mouse, timer or synthetic handlers it throws and the control stops working.\n11. Keyboard games call preventDefault for their keys (Space, arrows, WASD) from a window or document keydown listener added with { passive: false }, skipping inputs, textareas, selects and contenteditable, and make the playfield focusable; otherwise those keys scroll or jump the page during play.\n12. On phones a long press on game controls selects text or opens the Copy/Look Up menu unless the whole game area (controls, HUD, menus, empty play space) is marked data-twinkle-no-select and styled user-select: none; -webkit-user-select: none; -webkit-touch-callout: none. A game drawn without a canvas sets data-twinkle-game on <html> too, so Twinkle's phone touch protections apply. Keep inputs and copyable text selectable with data-twinkle-selectable.";

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,24 @@
 # Build SDK Index
 
-Version: 1.68.0
-Updated: 2026-10-16
-Generated: 2026-10-22T07:54:40.033Z
+Version: 1.69.0
+Updated: 2026-10-24
+Generated: 2026-10-24T02:37:05.998Z
+
+## Platform rules
+Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.
+
+1. Every page that draws on a <canvas> (2D, WebGL or Three.js) says what kind of page it is on <html>: data-twinkle-game for a game that fills the screen, data-twinkle-document for a normal scrolling page with a drawing pad, chart, visualizer or background effect. Without it, unless the page lays itself out with Twinkle.preview, Twinkle guesses from the canvas, and any canvas larger than 160 px, even one hidden in a tab, locks the page to one screen so it no longer scrolls. Add the attribute together with the first canvas.
+2. Games (data-twinkle-game) size themselves from Twinkle.preview: subscribe with Twinkle.preview.subscribe(listener, { immediate: true }), size canvases and renderers from layout.stage or layout.viewport, and report the play area with Twinkle.preview.setPlayfield(). Never size a game from 100vh/100vw, window.innerWidth/innerHeight or visualViewport, and never draw a fake phone or browser frame unless the creator asks for a device mockup: those fight the host and leave the game blank, cropped or scrolling on phones. Pages marked data-twinkle-document use ordinary CSS layout instead.
+3. alert(), confirm() and prompt() are silently blocked: alert shows nothing, confirm() always returns false (so the action it guards never happens) and prompt() returns null. Use in-page UI instead: a message element, an in-page confirm step, an <input>.
+4. Apps cannot open new windows or tabs: window.open() and target="_blank" links do nothing, and neither does a download link to an uploaded file. Open Twinkle pages with Twinkle.app.openContent(url) from a tap, save files with Twinkle.files.saveAs({ url, fileName }) (or { blob, fileName } for a file the app made), and show other web addresses as plain text.
+5. Do not use <form> elements: native form submission is blocked, so a submit button inside a form does nothing. Handle inputs and buttons in JavaScript.
+6. Code loads only from project files and Twinkle's vendor paths (/build/vendor/...). Package imports, CDN scripts, external network calls and app-local /api/* routes fail at runtime; use the Twinkle SDK for data, AI and storage.
+7. Call only Twinkle.* methods documented in the SDK reference. An invented or guessed method name throws and breaks the feature.
+8. Twinkle.privateDb and Twinkle.sharedDb save on a user action or as an occasional snapshot, never per frame, tick or keystroke: fast repeated writes are refused with 429 and the data is lost. A privateDb value is at most 16 KB. Keep live state in memory, and use Twinkle.world for realtime multiplayer.
+9. Start sound and image generation inside the viewer's tap or click handler. A Web Audio AudioContext stays silent until it is created or resumed in a tap (iPhones always enforce this), and Twinkle.ai.generateImage called from load or a timer fails with USER_ACTIVATION_REQUIRED.
+10. Call setPointerCapture only inside a pointerdown handler with that event's pointerId, wrapped in try/catch, and release only when hasPointerCapture says the element holds it. From click, mouse, timer or synthetic handlers it throws and the control stops working.
+11. Keyboard games call preventDefault for their keys (Space, arrows, WASD) from a window or document keydown listener added with { passive: false }, skipping inputs, textareas, selects and contenteditable, and make the playfield focusable; otherwise those keys scroll or jump the page during play.
+12. On phones a long press on game controls selects text or opens the Copy/Look Up menu unless the whole game area (controls, HUD, menus, empty play space) is marked data-twinkle-no-select and styled user-select: none; -webkit-user-select: none; -webkit-touch-callout: none. A game drawn without a canvas sets data-twinkle-game on <html> too, so Twinkle's phone touch protections apply. Keep inputs and copyable text selectable with data-twinkle-selectable.
 
 ## Notes
 - Reward is part of completion: a reward-paying run must stay pending until awarded:true and its canonical receipt (or getReceipt status awarded). Do not show final solved/completed status, advance rewarded progress, or discard finished proof before that. Preserve the exact challenge/proof and acknowledged progress in a durable per-viewer outbox; reconcile getReceipt after a lost reply and retry the same challenge, never inventing a payment. Explain explicit practice, already collected, exhausted approved limits, preview and disclosed zero-value retry outcomes. Use the start response as a conservative elapsed-time reference, and test delayed start, network failure, lost claim reply, reload, day/viewer change and duplicate recovery.
@@ -312,7 +328,7 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
   - Download a generated or remote file to the viewer's local device through the parent frame without opening a popup.
   - Local viewer download only; does not upload to Twinkle or consume AI Energy.
   - Use this for generated blobs/data/JSON/bytes or large/remote files that need parent-frame download handling.
-  - For URL downloads, cross-origin URLs must be fetchable by browser CORS or Twinkle's CDN proxy so the parent frame can create a local Blob download.
+  - For URL downloads, the parent frame fetches the file and saves it as a local Blob. Files uploaded to Twinkle (images, audio, PDFs and other files) work as they are; URLs on other sites must allow cross-origin fetches (CORS).
   - Simple visible same-origin images can still use normal browser anchors with href and download.
   - Example: await Twinkle.files.saveAs({ fileName: 'fashion-guide.png', dataUrl: imageUrl, mimeType: 'image/png' });
 - async uploadGenerated({ fileName, url, dataUrl, data, text, json, bytes, blob, file, mimeType } = {}) | scopes: files:write
@@ -902,11 +918,12 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
 
 ### Twinkle.minecraft
 - async getWorlds() | scopes: content:read
-  - Returns: { worlds: [{ id, name, dimension, spawn: { x, z } | null, map: { tileUrlTemplate, minZoom, maxZoom, tilePixels, blocksPerTileAtMaxZoom, renderedAt } | null }], stale }
+  - Returns: { worlds: [{ id, name, dimension, spawn: { x, z } | null, map: { tileUrlTemplate, minZoom, maxZoom, tilePixels, blocksPerTileAtMaxZoom, renderedAt, heightUrlTemplate } | null }], stale }
   - List the server's worlds (world, world1, world2, world_nether, world_the_end) with squaremap tile info for drawing a top-down map.
   - Tiles are 512x512 PNGs over HTTPS from www.twinklemc.site. At maxZoom one pixel is one block; blocksPerTile = blocksPerTileAtMaxZoom * 2 ** (maxZoom - z); tile x/y = floor(block x/z / blocksPerTile). Fill {z}, {x}, {y}. map.renderedAt tells how fresh the tiles are.
   - Limited rollout: apps not enabled yet get 403 with code minecraft_sdk_not_enabled.
   - stale: true means the Minecraft server was briefly unreachable and the data is a recent cached copy.
+  - map.heightUrlTemplate (or null) gives the land's shape on the same tile grid for 3D maps (ground heights; buildings and trees narrower than about 20 blocks are left out, so draw those from getTerrainChunks): a gzipped 'THM1' file, 16-byte little-endian header (magic, uint16 samples per side, uint16 blocks per sample, float64 source time) then samples x samples int16 heights row by row (z, then x); -32768 = no ground. Images and heights are served with CORS, so WebGL can use them.
   - Example: const { worlds } = await Twinkle.minecraft.getWorlds(); const w = worlds.find((x) => x.id === 'world'); const z = w.map.maxZoom; const blocksPerTile = w.map.blocksPerTileAtMaxZoom * 2 ** (w.map.maxZoom - z); const tx = Math.floor(blockX / blocksPerTile), ty = Math.floor(blockZ / blocksPerTile); const url = w.map.tileUrlTemplate.replace('{z}', z).replace('{x}', tx).replace('{y}', ty);
 - async getOnlinePlayers() | scopes: content:read
   - Returns: { players: [{ name, world, x, y, z, isZero }], count, stale }
@@ -1109,10 +1126,18 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Example: const { level } = await Twinkle.minecraft.getPlayArea({ id: 'twinkle-keep' });
 - async getPlayAreaChunks({ id, chunks: [[cx, cz], ...] }) | scopes: content:read
   - Returns: { scenes: [{ cx, cz, scene: { origin: [x,y,z], size: [w,h,d], palette, blocks, light, biomes, count, ... } | null }] }
-  - Up to 9 chunk columns of a play area in the /snap scene format (packed visible blocks with per-face light), cropped to the area's box. Stream the ones around the player.
+  - Up to 24 chunk columns of a play area in the /snap scene format (packed visible blocks with per-face light), cropped to the area's box. Stream the ones around the player.
   - Same scene format as getSnap; only blocks with a visible face inside the area are included. scene is null for a chunk that is not part of the area.
-  - At most 9 chunks per call; reads share the 180-per-minute build read limit, so cache chunks and load the nearest first.
+  - At most 24 chunks per call; reads share the 180-per-minute build read limit, so cache chunks and load the nearest first.
   - Example: const { scenes } = await Twinkle.minecraft.getPlayAreaChunks({ id: level.id, chunks: [[64, 29], [65, 29]] });
+- async getTerrainChunks({ world, chunks: [[cx, cz], ...] }) | scopes: content:read
+  - Returns: { scenes: [{ cx, cz, scene: { origin: [x,y,z], size: [w,h,d], palette, blocks, light, biomes, count, wide? } | null }] }
+  - The visible surface blocks of any chunk columns of a world (up to 24 per call), read from the saved world, in the /snap scene format. For 3D maps: draw real blocks near the camera.
+  - Each column keeps the blocks a camera above the ground can see: the top down to the lowest neighbouring column, through water, glass and leaves to the ground. Caves are left out.
+  - scene is null where the world was never generated. A scene taller than 255 blocks has wide: true (8 bytes per block).
+  - It shows the world as last saved (the server saves every few minutes). Pair it with world.map.heightUrlTemplate for the land farther away.
+  - Reads share the 180-per-minute build read limit: ask for 24 at a time, nearest first, and keep what you loaded.
+  - Example: const { scenes } = await Twinkle.minecraft.getTerrainChunks({ world: 'world', chunks: [[71, 38], [72, 38]] });
 - async createPlayArea({ name, world, box, spawn, id }) | scopes: content:write
   - Returns: { level }
   - Capture a box of a Minecraft world as a new play area (or re-capture an existing id). Runs in the background: poll getPlayArea until status is 'ready'.
@@ -1510,7 +1535,8 @@ world.updatePresence({ x, y, z, facing });
   - Pass null as expectedValue for an absent/null value. Both values are limited to 16 KB. Optional expectedUserId prevents a held operation from crossing an account change.
   - operationId is required: 8–64 letters, digits, underscores or hyphens. Reuse it for retries of the same logical change.
   - On conflict, rebase the intent onto the returned canonical item before comparing again. Do not retry-loop a 429.
-  - A duplicate operation returns the current canonical item without applying again. Ordinary set/remove remain unconditional; use a dedicated key for a compare-and-save workflow.
+  - An applied response confirms the save; use its canonical item as the next expectedValue. JSON storage may normalize floating-point numbers, so byte-for-byte equality with the submitted value is not a valid success check.
+  - A duplicate operation returns the current canonical item without applying again. matchesSubmittedValue is true when that current item equals this operation's submitted value after database normalization, and false if another save has since changed it. A receipt alone does not mean an older snapshot is still current. Ordinary set/remove remain unconditional; use a dedicated key for a compare-and-save workflow.
 
 ### Twinkle.reminders
 - async list({ includeDisabled, limit } = {}) | scopes: reminders:read
@@ -1579,7 +1605,7 @@ world.updatePresence({ x, y, z, facing });
   - For a paid nonogram-picture-v1 receipt, picture { title, category } may also be returned so the app can recover the reveal after a lost response. It contains no solution cells.
   - For collection practice, status:'completed' confirms a saved unpaid completion and includes completion { ruleId, setKey, at }, practice:true and receipt:null. Another challenge for the same personally completed collection set resolves to its existing receipt/completion, never a second payout.
 - await Twinkle.rewards.start({ ruleId, setKey?, levelIndex?, completionToken? }) | scopes: rewards:claim
-  - Returns: { mode: "live", challengeId, questions: [{ prompt, hint?, guide? }], setKey, reward: { xp, coins }, retryReward: { xp, coins }, attempts, maxAttempts, attemptsRemaining, firstTryAvailable, expiresAt }
+  - Returns: { mode: "live", challengeId, readyInSeconds?, questions: [{ prompt, hint?, guide? }], setKey, reward: { xp, coins }, retryReward: { xp, coins }, attempts, maxAttempts, attemptsRemaining, firstTryAvailable, expiresAt }
   - Creates or resumes a server-issued challenge for the signed-in viewer. Render its questions (prompt and optional hint) and collect numeric answers in the same order. One daily challenge per rule/review; repeat starts cannot reset attempts. A challenge stays open until the site's daily reset (UTC midnight, 9:00 AM in Korea) (expiresAt). Resuming after a wrong answer includes each question's guide.
   - Errors: build_reward_not_scheduled when the rule has no questions for today; build_reward_daily_claims_reached when the viewer already earned today’s cap. attemptsRemaining is null for unlimited rules.
   - For a completion rule call start when the activity begins (the moment the stage starts); the challenge's age is what the claim is measured against. In preview mode start also works for the owner (a stateless simulation).
@@ -1587,6 +1613,7 @@ world.updatePresence({ x, y, z, facing });
   - For breadface-v1, breadface-v2 and breadface-v3, pass the zero-based canonical levelIndex. Record [dt, inputBits] from the first physics frame; start returns its server token and maxFrames. For study-record-v1, start returns completion { profile, usesAiEnergy: true }; there is no client-authored proof token. For groove-lab-song-v1, groove-lab-heard-v1, vigil-guest-coplay-v1, minecraft-first-link-v1 and writing-words-v1, start returns completion { profile }; there is no progress step. For groove-lab-listen-v1 and groove-lab-own-listen-v1, call start({ ruleId, completionToken: <published song entry id> }) when that song starts playing; it returns completion { profile, songEntryId, durationSeconds, listenSeconds } and refuses with a plain reason (not published, whose song, too short, already earned for this song today). Starting a different song re-binds the rule's unpaid challenge and restarts its clock. For reading-quiz-v1, call progress({ challengeId, completionToken: <chapter commentId>, record: 'open' }) when the reader opens the chapter (returns readyInSeconds, readingSeconds, alreadyEarned, attemptedToday), then progress({ ..., record: 'quiz' }) once readyInSeconds has passed to get questions [{ question, options[4] }] (never answers). getStatus returns reading { chaptersEarnedToday, readersToday } when the app uses a reading proof. For writing-words-v1, getStatus also returns writing { countedWords, checkingChapters, chapters: [{ commentId, words, countedWords, status: counted|not-counted|checking|duplicate|too-short, english, reason }] } for today. For sliding-block-v1, start deals the board (completion.board, positions, minMoves); render it, record each real slide as [ms, carIndex, newPosition], send moves with progress (frames up to maxFrames per call), then claim with the latest token. For app-check-v1, start returns completion { profile, puzzle }: show that puzzle (a repeat start of the same challenge returns the same one); there is no progress step.
   - For nonogram-picture-v1, start returns completion { profile, completed: false, readyInSeconds, puzzle: { size, rows: number[][], cols: number[][] } }. Render those row and column clues; there is no progress call. Live readyInSeconds is the remaining approved minimum wait, so reopening a puzzle does not restart its clock. The private picture is durably bound to this exact viewer, app, release, rule, challenge and expiry. Reopening returns the same clues even after a refill. New challenges use unseen pictures; build_reward_picture_collection_complete means this size needs a refill. Offer practice/community puzzles while waiting.
   - For collection rules, setKey is required and must be one of the approved permanent keys. Start returns that exact question and persistent attempts. practice:true means no XP/Coins or official rating (daily allowance reached, earlier practice, or viewed archive guide); display that before answering. Merely opening a practice question does not consume its future eligibility, but answering it does. completed:true returns its lesson and completion, without a new challenge or payout. A current eligible daily-rematch puzzle must be opened as the rematch. A challenge still expires at the usual day/release boundary; reopen the same set to resume its saved attempts.
+  - Live completion starts return readyInSeconds, the remaining server-enforced wait for that challenge (including a resumed challenge). Anchor it at response arrival and queue one claim after that time; do not poll claim while too early. Retain the finished proof in a per-viewer outbox and reconcile getReceipt after a lost reply or reload. It is timing metadata, not proof of completion or permission to pay. Older servers may omit it; use the rule minSeconds conservatively. Preview timing and receipts remain separate.
 - await Twinkle.rewards.progress({ challengeId, completionToken?, frames?, record?, requestId? }) | scopes: rewards:claim
   - Returns: { mode: "live" | "preview", completion: { profile, token?, completed, failed?, decision?, message?, maxFrames? }, aiUsagePolicy? }
   - Verify a bounded batch of inputs for an approved server-simulated climb.
@@ -1601,7 +1628,7 @@ world.updatePresence({ x, y, z, facing });
   - Every claim response, wrong or right, returns the questions with their guides unlocked: show the teaching content right after the first answer. Answer keys are never returned.
   - After a wrong answer, the next answer within two seconds, right or wrong, is refused with build_reward_throttled (HTTP 429): it does not count and says nothing about whether it was right. Keep the question open and let the person send it again after the wait; never treat a 429 as a wrong answer or retry-loop it.
   - Optional subject says what the reward was for; it is shown on the public bounty story on Home while the app is public (e.g. "listened to Night Drive"). title is plain text up to 80 characters, path is this app's share-link segment (the one you pass to Twinkle.app.getShareUrl, letters, digits and dashes), imageUrl a Twinkle-hosted image. A malformed subject is refused with build_reward_subject_invalid (HTTP 400); an older server without subjects ignores it. Proof-backed rules that read the item on the server (Groove Lab songs) replace it with the stored title, link, cover and creator.
-  - Completion rules take no answers: claim({ challengeId }) when the activity is finished. build_reward_too_fast (HTTP 409) means fewer than minSeconds passed since start; show nothing and let play continue. In preview mode the receipt carries preview: true and nothing is paid.
+  - Completion rules take no answers: claim({ challengeId }) when the activity is finished. build_reward_too_fast (HTTP 409) means fewer than minSeconds passed since start. Preserve the finished proof, show reward pending, and schedule one retry using the start clock; let unrelated play continue. In preview mode the receipt carries preview: true and nothing is paid.
   - A completionProof rule also requires the signed completionToken from a successful rewards.progress response. The server simulates the registered game physics and must reach the goal. A timer, forged position, client win flag, altered inventory or token from another viewer, challenge or release cannot authorize payment. maxLifetimeClaims is enforced from receipts in the same award transaction; every receipt counts, including one capped by the daily budget (cappedFrom). build_reward_lifetime_claims_reached means all rewards for this rule have been collected; do not retry it.
   - For study-record-v1, the server verifies the settled private review row and its viewer, app, exact release, challenge and day binding. It never trusts the client’s decision, requested award amount or AI answer. Each successful daily study record is claimable once; display only canonical receipt/balances. For groove-lab-song-v1, pass completionToken as the published song's sharedDb entry id; for groove-lab-heard-v1, pass none; for vigil-guest-coplay-v1, pass the guest's world guestId (from world events) or the co-play record id; for minecraft-first-link-v1, pass nothing or the Minecraft UUID to use; for reading-quiz-v1, pass completionToken as the chapter commentId and answers as the three chosen option indexes (all three must be right; a wrong attempt cannot be retried that day); for groove-lab-listen-v1 and groove-lab-own-listen-v1, pass the same song entry id after listenSeconds of foreground playback; for reading-readers-v1, pass nothing; for writing-words-v1, pass nothing (the server counts today's chapters itself and refuses with a plain reason, e.g. "320 of 500 counted words today" or "still being checked"). The server reads the app's own groove-lab-songs, groove-lab-song-parts and groove-lab-listens rows and refuses with build_reward_completion_proof_required and a plain reason when the song or listeners do not qualify.
   - For app-check-v1, pass completionToken as JSON.stringify(record), the record your check reads (at most 64 KB); the server deals the challenge again and runs the approved file's check before paying. A refused record returns { awarded: false, reason, attemptsRemaining } and uses a try; claim only when the app itself sees a finished solve.