@stage5/lumine 0.2.2 → 0.2.4

package/bin/lumine.js

@@ -33,6 +33,8 @@ const LUMINE_AGENT_INSTRUCTIONS_MARKER =
 const LUMINE_SDK_REFERENCE_MARKER = "<!-- Lumine CLI SDK Reference -->";
 const LUMINE_REFERENCE_INSTRUCTIONS_MARKER =
   "<!-- Lumine CLI Reference Instructions -->";
+const LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER =
+  "<!-- Lumine CLI Main Checkout Instructions -->";
 const BUNDLED_SDK_REFERENCE_URL = new URL(
   "../sdk/BUILD_SDK_INDEX.md",
   import.meta.url,
@@ -70,6 +72,7 @@ Lumine CLI as the source of truth for saving this workspace back to Twinkle.
 - Read ${SDK_REFERENCE_FILE} before adding, removing, or changing any Twinkle.* SDK calls.
 - If build.canWrite is false, do not save changes.
 - If build.canPublish is false or contributionRootBuildId is set, this checkout is a contribution branch. Save only to this branch and do not run lumine launch or lumine save --publish.
+- On a contribution branch, main may have moved since the branch was created. Before starting large edits, run \`lumine update-from-main\` to three-way-merge main into the branch (resolve any <<<<<<< conflict markers it reports, then save). \`lumine pull --main\` gives a read-only checkout of main for comparison (created alongside your workspace, never inside it).
 - Do not edit another local checkout to bypass branch rules.
 
 ## Workflow
@@ -98,6 +101,15 @@ lumine save --summary "Describe the change"
 - 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.
 - For Three.js, use import * as THREE from '/build/vendor/three/0.184.0/three.module.min.js';. Addons (OrbitControls, GLTFLoader, ...) live under /build/vendor/three/0.184.0/addons/, e.g. import { OrbitControls } from '/build/vendor/three/0.184.0/addons/controls/OrbitControls.js';. Builds saved with the older /build/vendor/three/0.160.0/ path keep working.
 - 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.
+
+## Local Testing (Playwright / browser probes)
+
+- Serve the workspace with a tiny local HTTP server and drive it with Playwright. NEVER copy probe/vendor files into the workspace dir — lumine save uploads everything here (and binary files fail validation). Build a sibling probe dir that symlinks the workspace files instead.
+- Vendored imports like /build/vendor/three/0.184.0/... are absolute paths: mirror that directory under your probe dir's root and fetch the files from the LIVE SITE (e.g. https://www.twin-kle.com/build/vendor/three/0.184.0/three.webgpu.min.js). Do NOT use npm/CDN copies — the platform's vendored builds have rewritten import specifiers (npm three.tsl.min.js still imports bare "three/webgpu" and breaks the module graph).
+- The three WebGPU renderer falls back to WebGL2 in headless Chromium automatically. Headless software rendering runs at ~2-5fps, so anything time-based (walking a character, timers) takes ~10-20x longer than real time — loop with generous waits instead of fixed short sleeps, and bump navigation timeouts.
+- To inspect module-scope game state, append debug getters when SERVING main.js (e.g. body += "window.__dbg = () => ({...})") rather than editing workspace files.
+- SDK calls are absent when serving locally; well-written builds optional-chain window.Twinkle and fall back to localStorage. Seed localStorage in the probe to fake saves.
 
 ## Completion Report
 
@@ -119,7 +131,32 @@ the workspace to save.
 - To start from this Build, run lumine fork with the source build id and edit the forked workspace.
 - Do not edit another local checkout to bypass reference read-only semantics.
 `;
+const LUMINE_MAIN_CHECKOUT_INSTRUCTIONS = `${LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER}
+# Lumine Main Checkout (Read-Only)
+
+This directory is a read-only snapshot of a team project's MAIN workspace,
+pulled with \`lumine pull --main\`. Use it to inspect what main currently looks
+like; it is not the workspace to edit or save.
+
+## Source Of Truth
+
+- Read .twinkle/lumine-project.json before using these files.
+- metadata.mainCheckout is true here: do not run lumine save from this directory.
+- Make changes in your contribution-branch workspace (lumine pull <buildId>).
+- Bring main's latest changes into your branch with lumine update-from-main.
+- Do not edit another local checkout to bypass read-only semantics.
+`;
 const AGENT_INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"];
+// Commands allowed to resolve a read-only `pull --main` checkout's build id.
+// Everything else (launch/save/merge/…) mutates and must not run from one.
+const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
+  "pull",
+  "check",
+  "diff",
+  "sdk",
+  "select",
+  "workspace",
+]);
 const COMMANDS = new Set([
   "workspace",
   "login",
@@ -135,6 +172,7 @@ const COMMANDS = new Set([
   "diff",
   "merge",
   "replace-main",
+  "update-from-main",
   "save",
   "push",
   "check",
@@ -215,6 +253,10 @@ async function main() {
     await replaceMainWithBranch(options);
     return;
   }
+  if (options.command === "update-from-main") {
+    await updateBranchFromMain(options);
+    return;
+  }
   if (options.command === "save" || options.command === "push") {
     await save(options);
     return;
@@ -407,12 +449,23 @@ async function selectProject(options) {
 
 async function pull(options) {
   const auth = await resolveAuth(options);
-  const requestedBuildId = await resolveRequiredBuildIdOrSelected(options, auth);
+  const localProject = await findLocalProjectMetadata(
+    path.resolve(options.dir || process.cwd()),
+  );
+  const requestedBuildId = await resolveRequiredBuildIdOrSelected(
+    options,
+    auth,
+    options.pullMain ? { localProject } : {},
+  );
   const selectedBuild = await loadBuildMetadata({
     options,
     auth,
     buildId: requestedBuildId,
   });
+  if (options.pullMain) {
+    await pullMainBuildFiles({ options, auth, build: selectedBuild });
+    return;
+  }
   const build = await resolveEditableWorkspaceBuild({
     options,
     auth,
@@ -423,6 +476,65 @@ async function pull(options) {
   printPullResult(result);
 }
 
+// Sync a contribution branch with its team project's main: the server runs a
+// three-way merge (auto-merging where it can, writing git-style conflict
+// markers where it cannot) and saves the result to the branch. When run inside
+// the branch's workspace, local edits are sent along as the branch's pending
+// state and the merged files are written back to disk.
+async function updateBranchFromMain(options) {
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const localProject = await findLocalProjectMetadata(
+    path.resolve(options.dir || process.cwd()),
+  );
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth, {
+    localProject,
+  });
+  const build = await loadBuildMetadata({ options, auth, buildId });
+  const rootBuildId = Number(build?.contributionRootBuildId || 0);
+  const contributionBuildId = Number(build?.id || 0);
+  if (!rootBuildId || !contributionBuildId) {
+    throw new Error(
+      "update-from-main only applies to contribution branches of a team project. Pull the team project first so your branch workspace exists.",
+    );
+  }
+  let dir = null;
+  let projectFiles = null;
+  if (Number(localProject?.metadata?.buildId || 0) === contributionBuildId) {
+    dir = resolveProjectDirForSave({ options, localProject });
+    projectFiles = await collectProjectFiles(dir);
+  }
+  const result = await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/update-from-main`,
+    authToken: auth.token,
+    body: projectFiles ? { projectFiles } : {},
+    timeoutMs: options.timeoutMs,
+  });
+  const mergedFiles = Array.isArray(result.projectFiles)
+    ? result.projectFiles
+    : [];
+  if (dir && mergedFiles.length > 0) {
+    await writeProjectFiles({ dir, files: mergedFiles });
+    await removeLocalProjectFilesNotIn({ dir, files: mergedFiles });
+    const refreshed = await loadBuildMetadata({
+      options,
+      auth,
+      buildId: contributionBuildId,
+    }).catch(() => null);
+    if (refreshed) {
+      await writeProjectMetadata({
+        dir,
+        options,
+        build: refreshed,
+        manifest: localProject?.metadata?.manifest || null,
+        pulledAt: new Date().toISOString(),
+      });
+    }
+  }
+  printUpdateFromMainResult({ result, build, dir, mergedFiles });
+}
+
 async function reference(options) {
   const auth = await resolveAuth(options);
   const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
@@ -1578,33 +1690,95 @@ async function pullReferenceFiles({ options, auth, buildId }) {
   };
 }
 
-async function writeAgentInstructions({ dir }) {
-  for (const fileName of AGENT_INSTRUCTION_FILES) {
-    const filePath = path.join(dir, fileName);
-    try {
-      const existing = await fs.readFile(filePath, "utf8");
-      if (!existing.includes(LUMINE_AGENT_INSTRUCTIONS_MARKER)) {
-        continue;
-      }
-    } catch (error) {
-      if (error.code !== "ENOENT") throw error;
-    }
-    await fs.writeFile(filePath, LUMINE_AGENT_INSTRUCTIONS, "utf8");
+// Read-only checkout of a team project's MAIN workspace. Collaborators edit on
+// their contribution branch; this exists so branch work can consult what main
+// currently looks like without the pull auto-redirecting to the branch.
+async function pullMainBuildFiles({ options, auth, build }) {
+  const rootBuildId =
+    Number(build?.contributionRootBuildId || 0) || Number(build?.id || 0);
+  if (!rootBuildId) {
+    throw new Error("Could not resolve the team project for --main.");
+  }
+  const result = await loadBuildFiles({
+    options,
+    auth,
+    buildId: rootBuildId,
+    includeContent: true,
+  });
+  const rootBuild = result.build || { id: rootBuildId, title: `Build ${rootBuildId}` };
+  const files = Array.isArray(result.projectFiles) ? result.projectFiles : [];
+  // Never nest a main checkout inside another Lumine workspace (a later save
+  // there would upload it as project files) — default to a sibling instead.
+  // Running from a main checkout of this same build refreshes it in place,
+  // and the refresh prunes files main has deleted (a snapshot must not lie).
+  const enclosing = options.dir
+    ? null
+    : await findLocalProjectMetadata(process.cwd());
+  const enclosingIsThisMain =
+    enclosing?.metadata?.mainCheckout === true &&
+    Number(enclosing.metadata.buildId || 0) === rootBuildId;
+  const dir = path.resolve(
+    options.dir ||
+      (enclosingIsThisMain
+        ? enclosing.rootDir
+        : enclosing
+          ? path.join(path.dirname(enclosing.rootDir), defaultMainCheckoutDir(rootBuild))
+          : defaultMainCheckoutDir(rootBuild)),
+  );
+  await writeProjectFiles({ dir, files });
+  if (files.some((file) => isIndexHtmlPath(String(file.path)))) {
+    await removeLocalProjectFilesNotIn({ dir, files });
   }
+  await writeInstructionFiles({
+    dir,
+    marker: LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER,
+    content: LUMINE_MAIN_CHECKOUT_INSTRUCTIONS,
+  });
+  await writeSdkReference({ dir });
+  await writeMainCheckoutMetadata({
+    dir,
+    options,
+    build: rootBuild,
+    manifest: result.projectManifest || null,
+    pulledAt: new Date().toISOString(),
+  });
+  console.log(`Pulled main for ${formatBuildTitle(rootBuild)} (read-only).`);
+  console.log(`Pulled ${files.length} file${files.length === 1 ? "" : "s"} to ${dir}`);
+  console.log(
+    `Edits belong on your branch: \`lumine pull ${rootBuildId}\`, and \`lumine update-from-main\` brings main's changes into it.`,
+  );
+}
+
+async function writeAgentInstructions({ dir }) {
+  await writeInstructionFiles({
+    dir,
+    marker: LUMINE_AGENT_INSTRUCTIONS_MARKER,
+    content: LUMINE_AGENT_INSTRUCTIONS,
+  });
 }
 
 async function writeReferenceInstructions({ dir }) {
+  await writeInstructionFiles({
+    dir,
+    marker: LUMINE_REFERENCE_INSTRUCTIONS_MARKER,
+    content: LUMINE_REFERENCE_INSTRUCTIONS,
+  });
+}
+
+// Write AGENTS.md/CLAUDE.md, but never clobber a file the user customized:
+// only (re)write when the file is absent or still carries our marker.
+async function writeInstructionFiles({ dir, marker, content }) {
   for (const fileName of AGENT_INSTRUCTION_FILES) {
     const filePath = path.join(dir, fileName);
     try {
       const existing = await fs.readFile(filePath, "utf8");
-      if (!existing.includes(LUMINE_REFERENCE_INSTRUCTIONS_MARKER)) {
+      if (!existing.includes(marker)) {
         continue;
       }
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
     }
-    await fs.writeFile(filePath, LUMINE_REFERENCE_INSTRUCTIONS, "utf8");
+    await fs.writeFile(filePath, content, "utf8");
   }
 }
 
@@ -1659,6 +1833,14 @@ async function collectProjectFilesFromDir({ root, dir, files }) {
     if (entry.isFile() && EXCLUDED_UPLOAD_FILES.has(entry.name)) continue;
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
+      // A nested Lumine checkout (its own .twinkle metadata) is another
+      // project that happens to sit here — never upload it as project files.
+      if (await isNestedLumineCheckout(fullPath)) {
+        console.error(
+          `lumine: skipping nested Lumine checkout ${path.relative(root, fullPath)}/ (not part of this project)`,
+        );
+        continue;
+      }
       await collectProjectFilesFromDir({ root, dir: fullPath, files });
       continue;
     }
@@ -1680,6 +1862,15 @@ async function collectProjectFilesFromDir({ root, dir, files }) {
   }
 }
 
+async function isNestedLumineCheckout(dir) {
+  try {
+    await fs.access(path.join(dir, PROJECT_METADATA_DIR, PROJECT_METADATA_FILE));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function localFilePathToProjectPath({ root, filePath }) {
   const relative = path.relative(root, filePath).replace(/\\/g, "/");
   if (!relative || relative.startsWith("../") || path.isAbsolute(relative)) {
@@ -1763,6 +1954,19 @@ async function writeProjectFiles({ dir, files }) {
   }
 }
 
+// After update-from-main, files that main deleted must also leave the local
+// workspace — otherwise the next save would resurrect them on the branch.
+async function removeLocalProjectFilesNotIn({ dir, files }) {
+  const keep = new Set(files.map((file) => String(file.path)));
+  const localFiles = await collectProjectFiles(dir);
+  for (const file of localFiles) {
+    if (keep.has(file.path)) continue;
+    await fs.unlink(
+      resolveLocalProjectFilePath({ rootDir: dir, projectPath: file.path }),
+    );
+  }
+}
+
 async function writeProjectMetadata({
   dir,
   options,
@@ -1863,6 +2067,50 @@ async function writeReferenceMetadata({
   );
 }
 
+// Metadata for a read-only `pull --main` checkout: canWrite is forced false
+// (the files endpoint reports token scope, not role) and mainCheckout marks it
+// so save can explain where edits belong.
+async function writeMainCheckoutMetadata({
+  dir,
+  options,
+  build,
+  manifest,
+  pulledAt,
+}) {
+  const metadataDir = path.join(dir, PROJECT_METADATA_DIR);
+  await fs.mkdir(metadataDir, { recursive: true });
+  const rootBuildId = Number(build?.id || 0) || null;
+  await fs.writeFile(
+    path.join(metadataDir, PROJECT_METADATA_FILE),
+    JSON.stringify(
+      {
+        schemaVersion: 1,
+        buildId: rootBuildId,
+        readOnly: true,
+        mainCheckout: true,
+        build: {
+          id: rootBuildId,
+          title: build?.title || (rootBuildId ? `Build ${rootBuildId}` : ""),
+          role: build?.role || "collaborator",
+          ownerUsername: build?.ownerUsername || null,
+          contributionStatus: "none",
+          contributionRootBuildId: null,
+          canWrite: false,
+          canPublish: false,
+        },
+        apiUrl: options.apiUrl,
+        siteUrl: options.siteUrl,
+        lumineCli: serializeLumineCliMetadata(options),
+        manifest,
+        pulledAt,
+      },
+      null,
+      2,
+    ),
+    "utf8",
+  );
+}
+
 async function findLocalProjectMetadata(startDir) {
   let current = path.resolve(startDir || process.cwd());
   while (true) {
@@ -1892,6 +2140,13 @@ function resolveProjectDirForSave({ options, localProject }) {
 function assertLocalProjectCanBeSaved(localProject) {
   const metadata = localProject?.metadata;
   if (!metadata) return;
+  if (metadata.mainCheckout === true) {
+    const rootBuildId =
+      Number(metadata.buildId || 0) || Number(metadata.build?.id || 0) || 0;
+    throw new Error(
+      `This is a read-only checkout of main${rootBuildId ? ` for Build ${rootBuildId}` : ""}. Make edits in your branch workspace (\`lumine pull${rootBuildId ? ` ${rootBuildId}` : ""}\`), and run \`lumine update-from-main\` there to bring main's changes into it.`,
+    );
+  }
   if (isReadOnlyReferenceMetadata(metadata)) {
     const sourceBuildId =
       Number(metadata.reference?.sourceBuildId || 0) ||
@@ -2158,6 +2413,40 @@ function printContributionDiff({ result, build }) {
   }
 }
 
+function printUpdateFromMainResult({ result, build, dir, mergedFiles }) {
+  const branchNumber = Number(build?.contributionBranchNumber || 0) || 0;
+  const branchLabel = branchNumber
+    ? `branch ${branchNumber}`
+    : `branch #${build?.id}`;
+  const autoMerged = Array.isArray(result.autoMergedPaths)
+    ? result.autoMergedPaths
+    : [];
+  const conflicts = Array.isArray(result.conflicts) ? result.conflicts : [];
+  console.log(
+    `Updated ${branchLabel} from main (${mergedFiles.length} file${mergedFiles.length === 1 ? "" : "s"}).`,
+  );
+  if (autoMerged.length > 0) {
+    console.log(`Auto-merged: ${autoMerged.join(", ")}`);
+  }
+  if (conflicts.length > 0) {
+    const conflictPaths = conflicts.map((conflict) =>
+      typeof conflict === "string" ? conflict : conflict?.path || "unknown",
+    );
+    console.log(`CONFLICTS (markers written): ${conflictPaths.join(", ")}`);
+    console.log(
+      dir
+        ? "Resolve the <<<<<<< / >>>>>>> markers in the files above, then run `lumine save`."
+        : "Pull the branch, resolve the <<<<<<< / >>>>>>> markers, then run `lumine save`.",
+    );
+  } else if (!dir) {
+    console.log(
+      "The branch was updated on Twinkle. Run `lumine pull` to refresh your local workspace.",
+    );
+  } else {
+    console.log(`Local workspace updated: ${dir}`);
+  }
+}
+
 function printContributionActionResult({
   action,
   result,
@@ -2429,6 +2718,7 @@ function parseArgs(args) {
     "save",
     "noUpdateCheck",
     "allowWrite",
+    "main",
   ]);
 
   for (let i = 0; i < rest.length; i += 1) {
@@ -2507,6 +2797,7 @@ function parseArgs(args) {
       null,
     clientName: String(raw.clientName || "Lumine CLI").slice(0, 120),
     dir: raw.dir ? String(raw.dir) : "",
+    pullMain: parseBoolean(raw.main, false),
     summary: raw.summary ? String(raw.summary) : "",
     publish: parseBoolean(raw.publish, false),
     saveFirst: parseBoolean(raw.save, false),
@@ -2549,6 +2840,22 @@ async function resolveRequiredBuildIdOrSelected(
     (await findLocalProjectMetadata(
       path.resolve(options.dir || process.cwd()),
     ));
+  // A `pull --main` checkout is read-only but still knows its root build id.
+  // Read-only commands run from it (check, diff, a refreshing `pull --main`)
+  // resolve that id instead of bouncing off the reference/fork error — but
+  // mutating commands (launch would PUBLISH main, save, merge, …) stay blocked
+  // with main-checkout-specific guidance.
+  if (resolvedLocalProject?.metadata?.mainCheckout === true) {
+    const mainBuildId =
+      Number(resolvedLocalProject.metadata.buildId || 0) ||
+      Number(resolvedLocalProject.metadata.build?.id || 0);
+    if (!MAIN_CHECKOUT_READONLY_COMMANDS.has(options.command)) {
+      throw new Error(
+        `This is a read-only checkout of main${mainBuildId ? ` for Build ${mainBuildId}` : ""}; \`lumine ${options.command}\` isn't available here. Run it from your branch workspace or the canonical checkout, or pass an explicit Build URL.`,
+      );
+    }
+    if (mainBuildId > 0) return mainBuildId;
+  }
   if (
     resolvedLocalProject?.metadata &&
     isReadOnlyReferenceMetadata(resolvedLocalProject.metadata)
@@ -2767,6 +3074,12 @@ function defaultReferenceDir(build) {
   return `twinkle-reference-${titleSlug || "build"}-${buildId}`;
 }
 
+function defaultMainCheckoutDir(build) {
+  const titleSlug = slugify(build?.title || "");
+  const buildId = Number(build?.id || 0) || "build";
+  return `twinkle-main-${titleSlug || "build"}-${buildId}`;
+}
+
 function slugify(value) {
   return String(value || "")
     .toLowerCase()
@@ -2790,11 +3103,13 @@ function printHelp() {
   lumine explore [search terms]
   lumine select [twinkle-build-url]
   lumine pull [twinkle-build-url]
+  lumine pull [twinkle-build-url] --main
   lumine reference <twinkle-build-url>
   lumine fork <twinkle-build-url>
   lumine diff <twinkle-branch-url>
   lumine merge <twinkle-branch-url>
   lumine replace-main <twinkle-branch-url>
+  lumine update-from-main [twinkle-branch-url]
   lumine save
   lumine check [twinkle-build-url]
   lumine launch [twinkle-build-url]
@@ -2811,6 +3126,8 @@ Examples:
   npx @stage5/lumine@latest fork https://www.twin-kle.com/app/123
   npx @stage5/lumine@latest diff https://www.twin-kle.com/build/884/4
   npx @stage5/lumine@latest merge https://www.twin-kle.com/build/884/4
+  npx @stage5/lumine@latest pull 884 --main
+  npx @stage5/lumine@latest update-from-main
   npx @stage5/lumine@latest pull
   npx @stage5/lumine@latest save
   npx @stage5/lumine@latest save --publish
@@ -2826,6 +3143,7 @@ Options:
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
   --dir <path>          Directory for pulled project files
+  --main                With pull: read-only checkout of the team project's main
   --title <text>        New Build title
   --description <text>  Optional New Build description
   --no-description      Skip the New Build description prompt

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -2,16 +2,17 @@
 
 Version: 1.26.2
 Updated: 2026-06-09
-Generated: 2026-06-11T01:44:12.338Z
+Generated: 2026-06-18T12:26:29.648Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
 - Widgets call SDK methods; the parent proxies to the API.
 - Data API methods require scoped tokens handled by the parent; some namespaces include write methods.
-- Use Twinkle.privateDb as the default private per-user persistence layer for preferences, drafts, settings, and small JSON state.
+- Use Twinkle.privateDb for LOW-frequency durable private per-user state such as preferences, drafts, settings, inventory checkpoints, and saved progress. It is NOT for high-frequency or per-frame/per-tick writes; the server rate-limits writes and returns 429.
+- Match storage to update frequency: privateDb and sharedDb are for LOW-frequency durable state that changes on a user action. NEVER write per-frame/per-tick state to them (camera or cursor position, animation, live movement, presence, autosave every frame/tick). Keep live state in client memory, broadcast realtime/presence via Twinkle.world, and flush only occasional durable snapshots (on an interval or on exit, never per frame). The server enforces per-key write rate limits and returns 429 on excess; never retry-loop a 429.
 - Use Twinkle.userDb only for advanced private SQLite needs such as tables, indexes, many rows, filtered queries, or aggregates.
 - Use Twinkle.leaderboards for public Build scoreboards. Signed-in viewers are ranked by Twinkle username; guests can submit with a display name.
-- Use Twinkle.sharedDb for custom shared multi-user structured data, guestbooks, votes, and append-only run history.
+- Use Twinkle.sharedDb for LOW-frequency durable shared multi-user state such as guestbooks, votes, room settings, submitted records, and append-only run history. It is NOT for high-frequency or per-frame/per-tick writes; keep live/realtime state in Twinkle.world or client memory. The server rate-limits writes and returns 429.
 - Use Twinkle.subjects.search for in-app subject pickers. Twinkle.mount remains an optional host-provided preselection/context shortcut, not a data API.
 - Use Twinkle.aiCards for read-only existing public AI Card words and example texts, including word levels for typing games.
 - Use Twinkle.aiStories for read-only existing AI Story galleries, readers, quizzes, topic chapter indexes, and remix tools.
@@ -567,7 +568,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Returns: { sessionId, session, room, players, snapshot, subscribe(listener), updatePresence(patch), send(actionOrType, data), leave() }
   - Join a realtime Build world room and receive a snapshot plus a session handle for presence updates, actions, and room events.
   - Always available in the build iframe.
-  - World state is ephemeral and heartbeat/TTL based. Use sharedDb/privateDb for durable inventory, XP, quests, ownership, and saved progress.
+  - World state is ephemeral and heartbeat/TTL based. Use sharedDb/privateDb for durable inventory, XP, quests, ownership, and saved progress — but write those LOW-frequency only (on a user action or an occasional snapshot, never per frame/tick); per-frame/live state stays in world presence or client memory. The server rate-limits sharedDb/privateDb writes and returns 429.
   - Events are room-scoped and include serverTime, seq, eventId, schemaVersion, sessionId, player, and room metadata.
   - 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.
@@ -581,7 +582,7 @@ world.updatePresence({ x, y, z, facing });
   - 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.
-  - For durable game state, write through sharedDb/privateDb instead of relying on world presence.
+  - 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 });
 } catch (error) {
@@ -852,7 +853,7 @@ await Twinkle.chat.sendMessage('lobby', 'hello');
 ```
 
 ### Realtime MMO town room
-Use Twinkle.world for live avatar presence and lightweight room actions, recover stale session handles, and keep durable state like inventory and quests in sharedDb/privateDb.
+Use Twinkle.world for live avatar presence and lightweight room actions, recover stale session handles, and keep durable state like inventory and quests in sharedDb/privateDb — written low-frequency (never per frame/tick).
 Keywords: multiplayer, mmo, town, presence, avatars, movement, three.js, realtime
 
 ```js