@stage5/lumine 0.1.5 → 0.1.7

package/bin/lumine.js

@@ -50,6 +50,8 @@ Use these current source-of-truth rules:
 - Use Twinkle.privateDb for simple private per-user preferences, drafts, settings, and small JSON state.
 - Use Twinkle.userDb only for advanced private SQLite tables, indexes, many rows, filtered queries, or aggregates.
 - Use Twinkle.sharedDb for shared multi-user JSON data.
+- 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 }.
 - Use Twinkle.preview for canvas, WebGL, Three.js, fullscreen, and game layout.
 - Prefer existing documented Twinkle.* methods over guessing names from old code.
@@ -123,6 +125,9 @@ const COMMANDS = new Set([
   "pull",
   "reference",
   "fork",
+  "diff",
+  "merge",
+  "replace-main",
   "save",
   "push",
   "check",
@@ -186,6 +191,18 @@ async function main() {
     await fork(options);
     return;
   }
+  if (options.command === "diff") {
+    await diff(options);
+    return;
+  }
+  if (options.command === "merge") {
+    await mergeBranch(options);
+    return;
+  }
+  if (options.command === "replace-main") {
+    await replaceMainWithBranch(options);
+    return;
+  }
   if (options.command === "save" || options.command === "push") {
     await save(options);
     return;
@@ -300,11 +317,7 @@ async function whoami(options) {
 async function workspace(options) {
   const auth = await ensureAuth(options);
   const selectedBuild = options.target
-    ? await loadBuildMetadata({
-        options,
-        auth,
-        buildId: resolveRequiredBuildId(options.target),
-      })
+    ? await loadTargetBuildMetadata({ options, auth })
     : await chooseProject({
         builds: await listBuilds({ options, auth }),
       });
@@ -335,11 +348,7 @@ async function explore(options) {
 async function selectProject(options) {
   const auth = await resolveAuth(options);
   const selectedBuild = options.target
-    ? await loadBuildMetadata({
-        options,
-        auth,
-        buildId: resolveRequiredBuildId(options.target),
-      })
+    ? await loadTargetBuildMetadata({ options, auth })
     : await chooseProject({
         builds: await listBuilds({ options, auth }),
       });
@@ -374,7 +383,7 @@ async function pull(options) {
 
 async function reference(options) {
   const auth = await resolveAuth(options);
-  const buildId = resolveRequiredBuildId(options.target);
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
   const result = await pullReferenceFiles({ options, auth, buildId });
   printReferenceResult(result);
 }
@@ -382,7 +391,7 @@ async function reference(options) {
 async function fork(options) {
   const auth = await resolveAuth(options);
   await assertAuthScope({ options, auth, scope: "build:write" });
-  const buildId = resolveRequiredBuildId(options.target);
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
   const forkResult = await forkBuild({ options, auth, buildId });
   const forkedBuildId = Number(forkResult.build?.id || 0);
   if (!forkedBuildId) {
@@ -397,6 +406,60 @@ async function fork(options) {
   printForkResult({ forkResult, pullResult: result });
 }
 
+async function diff(options) {
+  const auth = await resolveAuth(options);
+  const build = await loadTargetBuildMetadata({ options, auth });
+  const { rootBuildId, contributionBuildId } =
+    resolveContributionActionBuildIds(build);
+  const result = await loadContributionDiff({
+    options,
+    auth,
+    rootBuildId,
+    contributionBuildId,
+  });
+  printContributionDiff({ result, build });
+}
+
+async function mergeBranch(options) {
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const build = await loadTargetBuildMetadata({ options, auth });
+  const { rootBuildId, contributionBuildId } =
+    resolveContributionActionBuildIds(build);
+  const result = await mergeContributionIntoMain({
+    options,
+    auth,
+    rootBuildId,
+    contributionBuildId,
+  });
+  printContributionActionResult({
+    action: "Merged",
+    result,
+    rootBuildId,
+    contributionBuildId,
+  });
+}
+
+async function replaceMainWithBranch(options) {
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const build = await loadTargetBuildMetadata({ options, auth });
+  const { rootBuildId, contributionBuildId } =
+    resolveContributionActionBuildIds(build);
+  const result = await replaceMainWithContribution({
+    options,
+    auth,
+    rootBuildId,
+    contributionBuildId,
+  });
+  printContributionActionResult({
+    action: "Replaced main with",
+    result,
+    rootBuildId,
+    contributionBuildId,
+  });
+}
+
 async function save(options) {
   const auth = await resolveAuth(options);
   await assertAuthScope({ options, auth, scope: "build:write" });
@@ -413,6 +476,11 @@ async function save(options) {
     buildId,
     localProject,
   });
+  if (build?.canWrite === false) {
+    throw new Error(
+      "This checkout is read-only for the current CLI login. Pull or diff it for review, then merge or replace main from the project owner workflow.",
+    );
+  }
   buildId = Number(build?.id || buildId);
   const dir = resolveProjectDirForSave({ options, localProject });
   const files = await collectProjectFiles(dir);
@@ -564,6 +632,11 @@ async function publishBuild({ options, buildId, auth }) {
 function printCheck(result) {
   const checks = result.checks || {};
   console.log(`Launch check: ${result.ok ? "ok" : "fail"}`);
+  if (checks.canonicalBuild) {
+    console.log(
+      `- canonical build: ${checks.canonicalBuild.ok ? "ok" : "fail"}`,
+    );
+  }
   console.log(
     `- project files: ${checks.projectFiles?.ok ? "ok" : "fail"} ` +
       `files=${checks.projectFiles?.fileCount ?? 0}`,
@@ -643,6 +716,11 @@ async function loadBuildMetadata({ options, auth, buildId }) {
   return result.build;
 }
 
+async function loadTargetBuildMetadata({ options, auth }) {
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
+  return await loadBuildMetadata({ options, auth, buildId });
+}
+
 async function loadOpenSourceBuildFiles({
   options,
   auth,
@@ -668,6 +746,24 @@ async function loadBuildFiles({ options, auth, buildId, includeContent }) {
   });
 }
 
+async function resolveBranchBuild({
+  options,
+  auth,
+  rootBuildId,
+  branchNumber,
+}) {
+  const result = await requestJson({
+    url: `${options.apiUrl}/cli/build/${rootBuildId}/branches/${branchNumber}`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+  const branchBuildId = Number(result.build?.id || 0);
+  if (!branchBuildId) {
+    throw new Error(`Branch ${branchNumber} for Build ${rootBuildId} could not be loaded.`);
+  }
+  return result.build;
+}
+
 async function forkBuild({ options, auth, buildId }) {
   return await requestJson({
     method: "POST",
@@ -692,6 +788,49 @@ async function saveProjectFiles({ options, auth, buildId, files, summary }) {
   });
 }
 
+async function loadContributionDiff({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  return await requestJson({
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+async function mergeContributionIntoMain({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/merge`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+async function replaceMainWithContribution({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/replace-main`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 async function resolveBuildForSave({ options, auth, buildId, localProject }) {
   const localBuild = localProject?.metadata?.build;
   const localBuildId =
@@ -1224,6 +1363,11 @@ function assertLocalProjectCanBeSaved(localProject) {
       `This is a read-only Lumine reference${sourceBuildId ? ` for Build ${sourceBuildId}` : ""}. Run \`lumine fork${sourceBuildId ? ` ${sourceBuildId}` : ""}\` to create an editable workspace.`,
     );
   }
+  if (metadata.build?.canWrite === false) {
+    throw new Error(
+      "This Lumine checkout is read-only for the current CLI login. Pull or diff it for review; project-owner branch edits must go through merge or replace-main.",
+    );
+  }
 }
 
 function isReadOnlyReferenceMetadata(metadata) {
@@ -1342,6 +1486,17 @@ function isContributionBranch(build) {
   );
 }
 
+function resolveContributionActionBuildIds(build) {
+  const contributionBuildId = Number(build?.id || 0);
+  const rootBuildId = Number(build?.contributionRootBuildId || 0);
+  if (!contributionBuildId || !rootBuildId || !isContributionBranch(build)) {
+    throw new Error(
+      "Pass a branch URL such as https://www.twin-kle.com/build/884/4, or run this from a pulled branch workspace.",
+    );
+  }
+  return { rootBuildId, contributionBuildId };
+}
+
 function printPullResult(result) {
   const build = result.build || {};
   const entryPath = result.manifest?.entryPath || "unknown";
@@ -1354,6 +1509,12 @@ function printPullResult(result) {
   console.log(`Next: cd ${shellQuote(result.dir)}`);
   if (build.canWrite === false) {
     console.log("This checkout is read-only for the current CLI login.");
+    if (isContributionBranch(build)) {
+      console.log("Review changes: lumine diff");
+      if (build.role === "project_owner") {
+        console.log("Owner actions: lumine merge, or lumine replace-main");
+      }
+    }
     return;
   }
   console.log('Codex: codex "Read AGENTS.md, then make the requested change."');
@@ -1424,6 +1585,57 @@ function printSaveResult({ result, build, dir, files }) {
   }
 }
 
+function printContributionDiff({ result, build }) {
+  const summary = result.diff?.summary || {};
+  const files = Array.isArray(result.diff?.changedFiles)
+    ? result.diff.changedFiles
+    : [];
+  const branchNumber = Number(build.contributionBranchNumber || 0) || 0;
+  const branchLabel = branchNumber ? `branch ${branchNumber}` : `branch #${build.id}`;
+  console.log(`Diff for ${branchLabel}:`);
+  console.log(
+    `- total=${summary.total ?? files.length} added=${summary.added ?? 0} ` +
+      `updated=${summary.updated ?? 0} deleted=${summary.deleted ?? 0}`,
+  );
+  if (result.rootDrifted) {
+    console.log("- main changed after this branch was created");
+  }
+  if (!files.length) {
+    console.log("No file changes.");
+    return;
+  }
+  for (const file of files) {
+    const mergeStatus = file.mergeStatus ? ` (${file.mergeStatus})` : "";
+    console.log(`- ${file.status || "changed"} ${file.path}${mergeStatus}`);
+  }
+}
+
+function printContributionActionResult({
+  action,
+  result,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  if (!result?.success) {
+    console.log(result?.error || "Branch action did not complete.");
+    process.exitCode = 1;
+    return;
+  }
+  const projectFiles = Array.isArray(result.projectFiles)
+    ? result.projectFiles
+    : [];
+  console.log(`${action} branch #${contributionBuildId} for Build #${rootBuildId}.`);
+  if (projectFiles.length > 0) {
+    console.log(
+      `Main now has ${projectFiles.length} project file${projectFiles.length === 1 ? "" : "s"}.`,
+    );
+  }
+  if (result.mergeConflictsWritten || result.conflicts?.length > 0) {
+    console.log("Merge wrote conflict markers. Resolve them in the Build workspace.");
+  }
+  console.log(`Main workspace: ${rootBuildId}`);
+}
+
 async function resolveAuth(options) {
   if (options.authToken) {
     return { token: options.authToken };
@@ -1743,8 +1955,14 @@ async function resolveRequiredBuildIdOrSelected(
   auth,
   { localProject = null } = {},
 ) {
-  const buildId = resolveBuildId(options.target);
-  if (buildId > 0) return buildId;
+  const targetReference = resolveBuildReference(options.target);
+  if (targetReference.buildId > 0) {
+    return await resolveBuildReferenceBuildId({
+      options,
+      auth,
+      reference: targetReference,
+    });
+  }
   const resolvedLocalProject =
     localProject ||
     (await findLocalProjectMetadata(
@@ -1773,7 +1991,7 @@ async function resolveRequiredBuildIdOrSelected(
 }
 
 function resolveRequiredBuildId(value) {
-  const buildId = resolveBuildId(value);
+  const buildId = resolveBuildReference(value).buildId;
   if (buildId > 0) return buildId;
   throw new Error(
     "Pass a Twinkle build URL, app URL, preview URL, or build id.",
@@ -1781,40 +1999,74 @@ function resolveRequiredBuildId(value) {
 }
 
 function resolveBuildId(value) {
+  return resolveBuildReference(value).buildId;
+}
+
+async function resolveBuildReferenceBuildId({ options, auth, reference }) {
+  if (reference.branchNumber > 0) {
+    const build = await resolveBranchBuild({
+      options,
+      auth,
+      rootBuildId: reference.buildId,
+      branchNumber: reference.branchNumber,
+    });
+    return Number(build.id || 0);
+  }
+  return Number(reference.buildId || 0);
+}
+
+function resolveBuildReference(value) {
   const rawValue = String(value || "").trim();
   const directId = Number(rawValue);
-  if (Number.isFinite(directId) && directId > 0) return directId;
-  if (!rawValue) return 0;
+  if (Number.isFinite(directId) && directId > 0) {
+    return { buildId: directId, branchNumber: 0 };
+  }
+  if (!rawValue) return { buildId: 0, branchNumber: 0 };
 
   try {
     const parsedUrl = new URL(rawValue);
     const host = parsedUrl.hostname.toLowerCase();
     const previewHost = host.match(/^b-(\d+)\.preview\.lumine\.app$/);
-    if (previewHost) return Number(previewHost[1]) || 0;
+    if (previewHost) {
+      return { buildId: Number(previewHost[1]) || 0, branchNumber: 0 };
+    }
 
     const parts = parsedUrl.pathname.split("/").filter(Boolean);
     const appIndex = parts.indexOf("app");
-    if (appIndex >= 0) return Number(parts[appIndex + 1]) || 0;
+    if (appIndex >= 0) {
+      return { buildId: Number(parts[appIndex + 1]) || 0, branchNumber: 0 };
+    }
 
     const buildIndex = parts.indexOf("build");
     if (buildIndex >= 0) {
       if (parts[buildIndex + 1] === "preview") {
         const nestedBuildIndex = parts.indexOf("build", buildIndex + 2);
-        return Number(parts[nestedBuildIndex + 1]) || 0;
+        return {
+          buildId: Number(parts[nestedBuildIndex + 1]) || 0,
+          branchNumber: 0,
+        };
       }
-      return Number(parts[buildIndex + 1]) || 0;
+      return {
+        buildId: Number(parts[buildIndex + 1]) || 0,
+        branchNumber: Number(parts[buildIndex + 2]) || 0,
+      };
     }
 
-    return (
-      Number(parsedUrl.searchParams.get("buildId")) ||
-      Number(parsedUrl.searchParams.get("build")) ||
-      0
-    );
+    return {
+      buildId:
+        Number(parsedUrl.searchParams.get("buildId")) ||
+        Number(parsedUrl.searchParams.get("build")) ||
+        0,
+      branchNumber: 0,
+    };
   } catch {
     const match = rawValue.match(
-      /(?:^|\/)(?:app|build)\/(?:preview\/build\/)?(\d+)(?:\/|$)/,
+      /(?:^|\/)(?:app|build)\/(?:preview\/build\/)?(\d+)(?:\/(\d+))?(?:\/|$)/,
     );
-    return Number(match?.[1] || 0) || 0;
+    return {
+      buildId: Number(match?.[1] || 0) || 0,
+      branchNumber: Number(match?.[2] || 0) || 0,
+    };
   }
 }
 
@@ -1924,6 +2176,9 @@ function printHelp() {
   lumine pull [twinkle-build-url]
   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 save
   lumine check [twinkle-build-url]
   lumine launch [twinkle-build-url]
@@ -1934,6 +2189,8 @@ Examples:
   npx @stage5/lumine@latest explore --sort forks
   npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
   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
   npx @stage5/lumine@latest save
   npx @stage5/lumine@latest save --publish

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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.24.0
-Updated: 2026-05-26
-Generated: 2026-05-26T10:20:06.718Z
+Version: 1.25.1
+Updated: 2026-05-28
+Generated: 2026-05-28T10:24:18.784Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -13,6 +13,7 @@ Generated: 2026-05-26T10:20:06.718Z
 - 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.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, and remix tools.
 - Use Twinkle.grammarbles for public Grammarbles question-bank trainer apps and optional signed-in viewer attempt-history filtering.
 - Use Twinkle.chess for chess engine play and analysis; app code still owns chess rules, legal moves, board state, and UI.
@@ -200,18 +201,32 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
 - async getSubjectComments(subjectId, { limit, cursor } = {}) | scopes: content:read
   - Returns: { comments: [{ id, content, filePath, fileName, fileSize, thumbUrl, timeStamp }], cursor? }
 
+### Twinkle.aiCards
+- async list({ limit, cursor, level, minLevel, maxLevel, quality, userId, hasImage, hasExample } = {}) | scopes: content:read
+  - Returns: { cards: [{ id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, isMysteryCard, isImageGenerating, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
+  - List existing public AI Cards newest first, including each card word, example sentence text, word level, and quality.
+  - Example: const { cards } = await Twinkle.aiCards.list({ level: 2, hasExample: true, limit: 20 });
+- async search({ query, limit, cursor, level, minLevel, maxLevel, quality, userId, hasImage, hasExample } = {}) | scopes: content:read
+  - Returns: { cards: [{ id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, isMysteryCard, isImageGenerating, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
+  - Search existing public AI Cards by word, with optional level and quality filters.
+  - Example: const { cards } = await Twinkle.aiCards.search({ query: searchText, minLevel: 1, maxLevel: 3, hasExample: true, limit: 12 });
+- async get(cardId) | scopes: content:read
+  - Returns: { card: { id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, isMysteryCard, isImageGenerating, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction } }
+  - Fetch one existing public AI Card by id, including word, example text, and level metadata.
+  - Example: const { card } = await Twinkle.aiCards.get(cardId);
+
 ### Twinkle.aiStories
 - async list({ limit, cursor, difficulty, type, isListening, userId, hasImage, hasQuestions } = {}) | scopes: content:read
   - Returns: { stories: [{ id, contentType, contentId, topic, topicKey, type, story, explanation, difficulty, isListening, imagePath, imageUrl, audioPath, audioUrl, questions, questionsBy, hasImage, hasQuestions, userId, username, profilePicUrl, timeStamp }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
-  - List completed existing user-generated AI Stories newest first for galleries, quiz apps, readers, and image/story collections.
+  - List completed existing user-generated AI Stories newest first for galleries, quiz apps, readers, passage typing, and image/story collections.
   - Example: const { stories } = await Twinkle.aiStories.list({ hasImage: true, hasQuestions: true, limit: 12 });
 - async search({ query, limit, cursor, difficulty, type, isListening, userId, hasImage, hasQuestions } = {}) | scopes: content:read
   - Returns: { stories: [{ id, contentType, contentId, topic, topicKey, type, story, explanation, difficulty, isListening, imagePath, imageUrl, audioPath, audioUrl, questions, questionsBy, hasImage, hasQuestions, userId, username, profilePicUrl, timeStamp }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
-  - Search completed existing user-generated AI Stories by topic or story text for galleries, quizzes, and readers.
+  - Search completed existing user-generated AI Stories by topic or story text for galleries, quizzes, readers, and passage typing games.
   - Example: const { stories } = await Twinkle.aiStories.search({ query: searchText, hasQuestions: true, limit: 12 });
 - async get(storyId) | scopes: content:read
   - Returns: { story: { id, contentType, contentId, topic, topicKey, type, story, explanation, difficulty, isListening, imagePath, imageUrl, audioPath, audioUrl, questions, questionsBy, hasImage, hasQuestions, userId, username, profilePicUrl, timeStamp } }
-  - Fetch one completed existing AI Story by id, including story text, media URLs, and normalized questions when available.
+  - Fetch one completed existing AI Story by id, including story text for passage typing, media URLs, and normalized questions when available.
   - Example: const { story } = await Twinkle.aiStories.get(storyId);
 
 ### Twinkle.grammarbles
@@ -302,8 +317,10 @@ world.updatePresence({ x, y, z, facing });
 ### Twinkle.reflections
 - async getDailyReflections({ userIds, cursor, lastId, limit } = {}) | scopes: dailyReflections:read
   - Returns: { reflections: [{ id, userId, response, questionId, submittedAt, sharedAt, username, profilePicUrl, question }], cursor? }
+  - Read only currently public Daily Reflection shares. response is the exact text the author chose to share publicly, never an unshared raw/private answer.
 - async getDailyReflectionsByUser(userId, { cursor, lastId, limit } = {}) | scopes: dailyReflections:read
   - Returns: { reflections: [{ id, userId, response, questionId, submittedAt, sharedAt, username, profilePicUrl, question }], cursor? }
+  - Read one user's currently public Daily Reflection shares. response is the exact text the author chose to share publicly, never an unshared raw/private answer.
 
 ### Twinkle.privateDb
 - async get(key) | scopes: privateDb:read
@@ -385,6 +402,37 @@ const { comments, pagination } = await Twinkle.subjectComments.list(subjectId, {
 console.log('Title:', subject.title, 'Pages:', comments.length, 'hasMore:', pagination?.hasMore);
 ```
 
+### Typing game content from AI Cards and AI Stories
+Use AI Card words for word mode, AI Card exampleText for sentence mode, and AI Story story text for passage mode. Keep leaderboards separate per mode.
+Keywords: typing, ai cards, ai stories, words, sentences, passages, leaderboard
+
+```js
+const wordPage = await Twinkle.aiCards.list({ level: 1, hasExample: true, limit: 20 });
+const wordTargets = wordPage.cards.map((card) => ({
+  text: card.word,
+  level: card.level,
+  sourceId: card.id
+}));
+const sentenceTargets = wordPage.cards.map((card) => ({
+  text: card.exampleText,
+  level: card.level,
+  sourceId: card.id
+}));
+
+const passagePage = await Twinkle.aiStories.list({ difficulty: 2, limit: 10 });
+const passageTargets = passagePage.stories.map((story) => ({
+  text: story.story,
+  level: story.difficulty,
+  sourceId: story.id
+}));
+
+await Twinkle.leaderboards.submit({
+  boardKey: 'arcade-typing-words',
+  score: finalScore,
+  meta: { mode: 'words', level }
+});
+```
+
 ### Search AI Stories for a quiz app
 Use existing user-generated AI Stories as source material for visual galleries, readers, and question-based games.
 Keywords: ai stories, story, quiz, questions, image, gallery