@stage5/lumine 0.1.5 → 0.1.6

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "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.0
+Updated: 2026-05-28
+Generated: 2026-05-28T09:34:12.631Z
 
 ## 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, 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, 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, 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