@stage5/lumine 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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.23.0
-Updated: 2026-05-24
-Generated: 2026-05-25T00:43:05.370Z
+Version: 1.24.0
+Updated: 2026-05-26
+Generated: 2026-05-26T10:20:06.718Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -21,217 +21,315 @@ Generated: 2026-05-25T00:43:05.370Z
 - Twinkle.ai.chat history entries must use { role, content }; map local message.text fields to content before passing history.
 
 ## Token Scopes
-files:read, user:read, users:read, dailyReflections:read, content:read, sharedDb:read, sharedDb:write, privateDb:read, privateDb:write, files:write, chat:read, chat:write, notifications:read, notifications:write, reminders:read, reminders:write
+files:read, user:read, users:read, dailyReflections:read, content:read, sharedDb:read, sharedDb:write, privateDb:read, privateDb:write, files:write, chat:read, chat:write, notifications:read, notifications:write, notifications:emit, reminders:read, reminders:write
 
 ## Namespaces
 
 ### Twinkle.capabilities
 - async get() | scopes: none
+  - Returns: Capability snapshot
 - async can(actionName) | scopes: none
+  - Returns: boolean
 - async listActions() | scopes: none
+  - Returns: { available, blocked, details }
 - async refresh() | scopes: none
+  - Returns: Capability snapshot
 
 ### Twinkle.viewer
 - async get() | scopes: none
+  - Returns: { id, username, profilePicUrl, isLoggedIn, isOwner, isGuest }
 - async refresh() | scopes: none
+  - Returns: Viewer info
 
 ### Twinkle.preview
 - getLayout() | scopes: none
+  - Returns: { mode, viewport, stage, safeInsets, playfield }
   - Read the host preview layout and derive a fixed-world scale from layout.playfield before sizing a canvas, sprites, or mobile game UI.
   - Example: const WORLD = { width: 360, height: 640 }; const layout = Twinkle.preview.getLayout(); const scale = Math.min(layout.playfield.width / WORLD.width, layout.playfield.height / WORLD.height);
 - reserveInsets({ top, right, bottom, left }) | scopes: none
+  - Returns: { mode, viewport, stage, safeInsets, playfield }
   - Reserve host-aware safe space for HUD bars, touch controls, or other overlays before clamping gameplay.
   - Example: Twinkle.preview.reserveInsets({ top: 72, bottom: 120, left: 0, right: 0 });
 - setPlayfield({ x, y, width, height } | null) | scopes: none
+  - Returns: { playfieldBounds, playerBounds, overflowTop, overflowRight, overflowBottom, overflowLeft, status, reportedAt } | null
   - Declare the actual playable rectangle when the game area is smaller than the raw canvas.
   - Example: Twinkle.preview.setPlayfield({ x: layout.playfield.x, y: layout.playfield.y, width: layout.playfield.width, height: layout.playfield.height });
 - reportGameplayState({ playfieldBounds?, playerBounds? } | null) | scopes: none
+  - Returns: { playfieldBounds, playerBounds, overflowTop, overflowRight, overflowBottom, overflowLeft, status, reportedAt } | null
   - Report live player or avatar bounds so the preview host can detect floor, wall, or out-of-bounds issues.
   - Example: Twinkle.preview.reportGameplayState({ playerBounds: { x: player.x, y: player.y, width: player.width, height: player.height } });
 - getGameplayTelemetry() | scopes: none
+  - Returns: { playfieldBounds, playerBounds, overflowTop, overflowRight, overflowBottom, overflowLeft, status, reportedAt } | null
   - Read the latest preview-side gameplay telemetry snapshot.
 - clearGameplayState() | scopes: none
+  - Returns: { playfieldBounds, playerBounds, overflowTop, overflowRight, overflowBottom, overflowLeft, status, reportedAt } | null
 - clearReservedInsets() | scopes: none
+  - Returns: { mode, viewport, stage, safeInsets, playfield }
 - subscribe(listener, { immediate } = {}) | scopes: none
+  - Returns: unsubscribe()
   - Listen for host layout changes so a fixed-world game scale or canvas surface stays synced after resize, mobile viewport changes, or embedded runtime layout shifts.
   - Example: const unsubscribe = Twinkle.preview.subscribe((layout) => syncGameLayout(layout), { immediate: true });
 
 ### Twinkle.mount
 - async get() | scopes: none
+  - Returns: { type: 'subject', id: number } | null
 - async refresh() | scopes: none
+  - Returns: { type: 'subject', id: number } | null
 
 ### Twinkle.notifications
 - getLaunchTarget() | scopes: none
+  - Returns: { notificationId, buildId, eventKey, eventLabel, target, payload? } | null
   - Read the current notification launch target, if the app was opened from a Build notification.
 - onLaunchTarget(listener, { immediate } = {}) | scopes: none
+  - Returns: unsubscribe()
   - Listen for notification launch targets while the Build app is already open.
   - Example: const off = Twinkle.notifications.onLaunchTarget((launchTarget) => focusEntry(launchTarget?.target?.focus?.entryId));
+- async getSubscription(channelKey, { targetKey }) | scopes: notifications:read
+  - Returns: { subscription }
+  - Read whether the current viewer is subscribed to an app-defined notification channel target.
+  - Example: const { subscription } = await Twinkle.notifications.getSubscription('room.message', { targetKey: 'room:lobby' });
+- async subscribe(channelKey, { targetKey, launchTarget }) | scopes: notifications:write
+  - Returns: { subscription }
+  - Subscribe the current viewer to an app-defined notification channel target.
+  - Example: await Twinkle.notifications.subscribe('room.message', { targetKey: 'room:lobby', launchTarget: { view: 'room', roomId: 'lobby' } });
+- async unsubscribe(channelKey, { targetKey }) | scopes: notifications:write
+  - Returns: { subscription: null }
+  - Unsubscribe the current viewer from an app-defined notification channel target.
+  - Example: await Twinkle.notifications.unsubscribe('room.message', { targetKey: 'room:lobby' });
+- async notifySubscribers(channelKey, { targetKey, eventKey, label, summary, launchTarget, payload }) | scopes: notifications:emit
+  - Returns: { sent }
+  - Notify viewers who opted into an app-defined channel target, without requiring a sharedDb write.
+  - Example: await Twinkle.notifications.notifySubscribers('room.message', { targetKey: 'room:lobby', eventKey: 'room.message.created', label: 'Room messages', summary: 'posted in Lobby', launchTarget: { view: 'room', roomId: 'lobby', messageId } });
 - async getSubjectUpdateSubscription(subjectId) | scopes: notifications:read
+  - Returns: { subscription }
   - Read whether the current viewer is subscribed to Build notifications for updates to a subject.
   - Example: const { subscription } = await Twinkle.notifications.getSubjectUpdateSubscription(subjectId);
 - async subscribeToSubjectUpdates(subjectId, { target } = {}) | scopes: notifications:write
+  - Returns: { subscription }
   - Subscribe the current viewer to notifications when the original subject author adds a new page or update.
   - Example: await Twinkle.notifications.subscribeToSubjectUpdates(subjectId, { target: { view: 'book', subjectId } });
 - async unsubscribeFromSubjectUpdates(subjectId) | scopes: notifications:write
+  - Returns: { subscription: null }
   - Unsubscribe the current viewer from Build notifications for a subject's new pages or updates.
 
 ### Twinkle.chess
 - async bestMove({ fen, depth?, skillLevel?, maxTimeMs?, timeoutMs? }) | scopes: none
+  - Returns: { success, move, bestMove, from, to, promotion, evaluation, depth, mate, error, engine }
   - Ask the parent-hosted Stockfish engine for the best move from a FEN position.
   - Example: const result = await Twinkle.chess.bestMove({ fen: game.fen(), skillLevel: 8, maxTimeMs: 1000 });
 if (result.success) game.move({ from: result.from, to: result.to, promotion: result.promotion || undefined });
 - async evaluate({ fen, depth?, skillLevel?, maxTimeMs?, timeoutMs? }) | scopes: none
+  - Returns: { success, move, bestMove, from, to, promotion, evaluation, depth, mate, error, engine }
   - Analyze a FEN position and return Stockfish's current best move plus centipawn or mate evaluation.
   - Example: const analysis = await Twinkle.chess.evaluate({ fen: game.fen(), depth: 12 });
 console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
 
 ### Twinkle.files
 - async saveAs({ fileName, url, dataUrl, data, text, json, bytes, blob, file, mimeType } = {}) | scopes: none
+  - Returns: { success, fileName, size?, mimeType?, method }
   - Download a generated or remote file to the viewer's local device through the parent frame without opening a popup.
   - 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
+  - Returns: { assets: [{ id, buildId, fileName, originalFileName, mimeType, sizeBytes, filePath, url, thumbUrl, fileType, uploadedByUserId, createdAt }], failed?: [{ fileName, message }], canceled }
   - Upload an app-generated file to Twinkle-hosted cloud storage without opening a picker, then store the returned asset refs in sharedDb/privateDb/userDb.
   - Example: const { assets } = await Twinkle.files.uploadGenerated({ fileName: 'fashion-guide.png', dataUrl: generatedImageUrl, mimeType: 'image/png' });
 - async pickAndUpload({ accept, multiple } = {}) | scopes: files:write
+  - Returns: { assets: [{ id, buildId, fileName, originalFileName, mimeType, sizeBytes, filePath, url, thumbUrl, fileType, uploadedByUserId, createdAt }], failed?: [{ fileName, message }], canceled }
   - Pick supported local files and upload them to Twinkle-hosted cloud storage, then store the returned asset refs in sharedDb/privateDb/userDb.
   - Example: const { assets, canceled } = await Twinkle.files.pickAndUpload({ accept: 'image/*,.pdf', multiple: true });
 - async list({ cursor, limit } = {}) | scopes: files:read
+  - Returns: { assets: [{ id, buildId, fileName, originalFileName, mimeType, sizeBytes, filePath, url, thumbUrl, fileType, uploadedByUserId, createdAt }], nextCursor, usage: { totalBytes, fileCount, maxRuntimeFileStorageBytes, remainingBytes } | null }
   - List the current viewer's uploaded runtime files for this build.
   - Example: const { assets, usage } = await Twinkle.files.list({ limit: 20 });
 - async delete(assetId) | scopes: files:write
+  - Returns: { success, deletedAssetId, usage: { totalBytes, fileCount, maxRuntimeFileStorageBytes, remainingBytes } | null }
   - Delete one of the current viewer's uploaded runtime files and free up Twinkle.files quota.
   - Example: await Twinkle.files.delete(assetId);
 
 ### Twinkle.ai
 - async listPrompts() | scopes: none
+  - Returns: Array<{ id, title, description }>
 - async chat({ promptId, message, history, systemPrompt, requestId, onText, onStatus } = {}) | scopes: none
+  - Returns: { text, response, model, aiUsagePolicy }
   - Generate text with the default Lumine text model, optionally streaming text updates through onText.
   - Example: const chatHistory = conversation.slice(-12).map((entry) => ({ role: entry.role === 'assistant' ? 'assistant' : 'user', content: entry.text }));
 const result = await Twinkle.ai.chat({ message, history: chatHistory, systemPrompt: 'You are a cheerful pirate helper who answers in one sentence.', onText: (text, meta) => renderReply(text), onStatus: (status) => setThinking(status === 'thinking') });
 - async generateObject({ prompt, expectedStructure, thinkingMode, mode, instructions, systemPrompt } = {}) | scopes: none
+  - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, aiUsagePolicy }
   - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic.
   - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'medium', prompt: 'Classify the player intent from: ' + playerText, expectedStructure: { action: 'string', targetCharacter: 'string', confidence: 0, shouldAskFollowUp: false } });
 - onChatStatus(listener) | scopes: none
+  - Returns: unsubscribe function
   - Listen to shared runtime AI chat stream events.
 - async generateImage({ prompt, referenceImageB64, previousResponseId, previousImageId, engine, quality, requestId, onStatus, timeoutMs } = {}) | scopes: none
+  - Returns: { success, imageUrl, responseId, imageId, engine, quality, aiUsagePolicy } or { success: false, error, reason, code, aiUsagePolicy }
   - Generate or edit an image from a prompt and optional base64/data-URL reference image.
   - Example: const result = await Twinkle.ai.generateImage({ prompt: 'Create a fashion guide portrait for this face with flattering colors and outfit ideas', referenceImageB64, quality: 'high', onStatus: (status) => console.log(status.stage) });
 - onImageGenerationStatus(listener) | scopes: none
+  - Returns: unsubscribe function
   - Subscribe to real-time image generation status events forwarded into the build iframe.
   - Example: const unsubscribe = Twinkle.ai.onImageGenerationStatus((status) => console.log(status.stage));
 
 ### Twinkle.characters
 - async chat({ character, thinkingMode, message, history, roomContext, scene, systemPrompt, instructions, includeWebsiteContext, requestId, onText, onStatus } = {}) | scopes: none
+  - Returns: { text, response, character, aiUsername, thinkingMode, requestedThinkingMode, includeWebsiteContext, model, provider, aiUsagePolicy }
   - Talk to Zero or Ciel from a Build app, either as a final-response call or streaming RPG-style dialogue text with onText/onStatus.
   - Example: const dialogueHistory = recentTurns.slice(-16).map((entry) => ({ role: entry.role === 'assistant' ? 'assistant' : 'user', content: entry.text, speaker: entry.speaker }));
 const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode: thinkHard ? 'high' : 'medium', message: playerText, history: dialogueHistory, roomContext, scene: { location: 'classroom', nearbyCharacters: ['zero', 'ciel'] }, includeWebsiteContext: false, onText: (text) => renderDialogue(text) });
 - onChatStatus(listener) | scopes: none
+  - Returns: unsubscribe function
   - Listen to shared Zero/Ciel runtime chat stream events.
 
 ### Twinkle.userDb
 - async query(sql, params) | scopes: none
+  - Returns: { rows, rowCount, truncated }
   - Run a SELECT against advanced private per-user SQLite. Use Twinkle.privateDb instead for simple preferences, drafts, settings, or small JSON state.
 - async exec(sql, params) | scopes: none
+  - Returns: { changes, lastInsertRowid }
   - Run a write or schema statement against advanced private per-user SQLite.
 
 ### Twinkle.subjects
 - async getMySubjects({ limit, cursor } = {}) | scopes: content:read
+  - Returns: { subjects: [{ id, title, description, filePath, fileName, fileSize, thumbUrl, timeStamp, rootType, rootId, rewardLevel }], cursor? }
 - async search({ query, limit, cursor } = {}) | scopes: content:read
+  - Returns: { subjects: [{ id, contentType, contentId, title, description, filePath, fileName, fileSize, thumbUrl, timeStamp, userId, username, profilePicUrl, rootType, rootId, rewardLevel, numComments }], cursor?, pagination: { limit, hasMore, nextCursor }, filters: { query } }
   - Search Twinkle subjects by text for subject picker UIs, book apps, scrapbooks, and galleries.
   - Example: const { subjects } = await Twinkle.subjects.search({ query: searchText, limit: 12 });
 - async getSubject(subjectId) | scopes: content:read
+  - Returns: { subject: { id, title, description, filePath, fileName, fileSize, thumbUrl, secretAnswer, secretAttachment, timeStamp, userId, username, profilePicUrl, rootType, rootId, rewardLevel } }
 - async getSubjectComments(subjectId, { limit, cursor } = {}) | scopes: content:read
+  - Returns: { comments: [{ id, content, filePath, fileName, fileSize, thumbUrl, timeStamp }], cursor? }
 
 ### 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.
   - 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.
   - 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.
   - Example: const { story } = await Twinkle.aiStories.get(storyId);
 
 ### Twinkle.grammarbles
 - async listQuestions({ level, limit, cursor } = {}) | scopes: content:read
+  - Returns: { questions: [{ id, level, rating, question, choices, answerIndex, correctChoice, correctChoiceKey, isChecked, explanation }], cursor?, pagination: { level, limit, hasMore, nextCursor } }
   - Read public Grammarbles questions and answers by level with rating/id cursor pagination.
   - Example: const page = await Twinkle.grammarbles.listQuestions({ level: 3, limit: 100 }); const question = page.questions[Math.floor(Math.random() * page.questions.length)];
 - async getMyQuestionHistory({ level, limit, cursor } = {}) | scopes: content:read
+  - Returns: { attempts: [{ id, questionId, level, grade, gradeRank, isCorrect, attemptNumber, timeStamp }], cursor?, pagination: { level, limit, hasMore, nextCursor } }
   - Read the signed-in viewer's real Grammarbles attempt rows for trainer filtering.
   - Example: const history = await Twinkle.grammarbles.getMyQuestionHistory({ level: selectedLevel, limit: 500 }); const answeredIds = new Set(history.attempts.map((attempt) => attempt.questionId));
 
 ### Twinkle.subjectComments
 - async list(subjectId, { limit, cursor, sortBy, includeReplies, author, authorUserId, replyScope } = {}) | scopes: content:read
+  - Returns: { comments: [{ id, content, filePath, fileName, fileSize, thumbUrl, timeStamp, userId, username, profilePicUrl, commentId, replyId }], cursor?, pagination: { limit, hasMore, nextCursor }, filters: { subjectId, sortBy, includeReplies, author, replyScope, authorUserId } }
   - Read a subject's comment stream with stable keyset pagination, oldest/newest ordering, author filters, and optional same-author reply scoping.
   - Example: const { subjects } = await Twinkle.subjects.search({ query: searchText, limit: 12 }); const subjectId = pickedSubject.id; const page = await Twinkle.subjectComments.list(subjectId, { sortBy: 'oldest', author: 'subjectPoster', includeReplies: true, replyScope: 'ownThread', limit: 50 });
 
 ### Twinkle.profileComments
 - async getProfileComments({ profileUserId, limit, offset, sortBy, includeReplies, range, since, until } = {}) | scopes: content:read
+  - Returns: { comments: [{ id, content, filePath, fileName, fileSize, thumbUrl, timeStamp, userId, username, profilePicUrl, likes, replies, commentId, replyId }], pagination: { limit, offset, hasMore, nextOffset }, filters: { profileUserId, sortBy, includeReplies, since, until } }
 - async getProfileCommentIds({ profileUserId, limit, offset, sortBy, includeReplies, range, since, until } = {}) | scopes: content:read
+  - Returns: { ids: number[], pagination: { limit, offset, hasMore, nextOffset }, filters: { profileUserId, sortBy, includeReplies, since, until } }
 - async getCommentsByIds(idsOrOpts) | scopes: content:read
+  - Returns: { comments: [{ id, content, filePath, fileName, fileSize, thumbUrl, timeStamp, userId, username, profilePicUrl, commentId, replyId }] }
 - async getProfileCommentCounts(idsOrOpts) | scopes: content:read
+  - Returns: { countsById: { [commentId]: { likes, replies } } }
 
 ### Twinkle.leaderboards
 - async get({ boardKey = 'default', limit, cursor } = {}) | scopes: none
+  - Returns: { entries: [{ rank, id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt }], scores, cursor, hasMore, personalBest: { id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt } | null }
   - Read score-sorted personal-best leaderboard rows for this Build app.
 - async submit({ boardKey = 'default', score, displayName, meta } = {}) | scopes: none
+  - Returns: { entry: { id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt } | null, personalBest: { id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt } | null, improved, previousScore }
   - Submit a score to a public Build leaderboard using server-owned viewer identity.
 
 ### Twinkle.sharedDb
 - async getTopics() | scopes: sharedDb:read
+  - Returns: { topics: [{ id, name, createdBy, createdAt }] }
 - async createTopic(name) | scopes: sharedDb:write
+  - Returns: { topic: { id, name, createdBy, createdAt } }
 - async getEntries(topicName, { limit, pageSize, cursor, order, sort, direction } = {}) | scopes: sharedDb:read
+  - Returns: { entries: [{ id, topicId, userId, username, profilePicUrl, data, createdAt, updatedAt }], cursor?, hasMore }
   - Read shared topic rows with cursor pagination.
 - async loadMoreEntries(topicName, { limit, pageSize, cursor, order, sort, direction } = {}) | scopes: sharedDb:read
+  - Returns: { entries: [{ id, topicId, userId, username, profilePicUrl, data, createdAt, updatedAt }], cursor?, hasMore }
   - Fetch the next sharedDb page.
 - async addEntry(topicName, data, { notify } = {}) | scopes: sharedDb:write
+  - Returns: { entry: { id, topicId, userId, username, profilePicUrl, data, createdAt, updatedAt } }
   - Append a shared JSON row, optionally creating a Twinkle notification from the canonical write.
 - async updateEntry(entryId, data, { notify } = {}) | scopes: sharedDb:write
+  - Returns: { entry: { id, topicId, userId, username, profilePicUrl, data, createdAt, updatedAt } }
   - Update a viewer-owned shared row, optionally notifying safe recipients from the canonical write.
 - async deleteEntry(entryId) | scopes: sharedDb:write
+  - Returns: { success: true }
 
 ### Twinkle.chat
 - async listRooms() | scopes: chat:read
+  - Returns: { rooms: [{ id, buildId, key, name, createdByUserId, createdAt, updatedAt }] }
 - async createRoom({ roomKey, name }) | scopes: chat:write
+  - Returns: { room: { id, buildId, key, name, createdByUserId, createdAt, updatedAt } }
 - async listMessages(roomKey, { cursor, limit } = {}) | scopes: chat:read
+  - Returns: { messages: [{ id, roomId, roomKey, userId, username, profilePicUrl, role, status, text, metadata, clientMessageId, createdAt, updatedAt }], cursor? }
 - async sendMessage(roomKey, textOrOptions, options) | scopes: chat:write
+  - Returns: { message: { id, buildId, roomId, roomKey, userId, username, profilePicUrl, role, status, text, metadata, clientMessageId, createdAt, updatedAt }, room: { id, buildId, key, name, createdByUserId, createdAt, updatedAt }, created }
 - async deleteMessage(messageId) | scopes: chat:write
+  - Returns: { success: true, messageId }
 - subscribe(roomKey, listener) | scopes: chat:read
+  - Returns: unsubscribe function
 
 ### Twinkle.world
 - async join({ worldKey = 'default', roomKey = 'main', instanceId = 'main', presence, player } = {}) | scopes: none
+  - 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.
   - Example: const world = await Twinkle.world.join({ roomKey: 'town-square', presence: { x: 0, y: 0, z: 0, facing: 'south' }, player: { name: avatarName } });
 world.subscribe((event) => updateRemotePlayers(event.players));
 world.updatePresence({ x, y, z, facing });
 - leaveAll() | scopes: none
+  - Returns: void
   - Leave every active world session in the current iframe.
 
 ### Twinkle.users
 - async getUser(userId) | scopes: user:read
+  - Returns: { id, username, profilePicUrl, realName } | null
 - async getUsers({ search, userIds, cursor, limit } = {}) | scopes: users:read
+  - Returns: { users: [{ id, username, profilePicUrl, realName }], cursor? }
 
 ### Twinkle.reflections
 - async getDailyReflections({ userIds, cursor, lastId, limit } = {}) | scopes: dailyReflections:read
+  - Returns: { reflections: [{ id, userId, response, questionId, submittedAt, sharedAt, username, profilePicUrl, question }], cursor? }
 - async getDailyReflectionsByUser(userId, { cursor, lastId, limit } = {}) | scopes: dailyReflections:read
+  - Returns: { reflections: [{ id, userId, response, questionId, submittedAt, sharedAt, username, profilePicUrl, question }], cursor? }
 
 ### Twinkle.privateDb
 - async get(key) | scopes: privateDb:read
+  - Returns: { item: { id, key, value, updatedAt } | null }
   - Read one key from the default private per-user JSON store.
 - async list({ prefix, limit, cursor } = {}) | scopes: privateDb:read
+  - Returns: { items: [{ id, key, value, updatedAt }], cursor? }
   - List keys from the default private per-user JSON store.
 - async set(key, value) | scopes: privateDb:write
+  - Returns: { item: { id, key, value, updatedAt } }
   - Upsert one JSON-serializable value in the default private per-user store.
 - async remove(key) | scopes: privateDb:write
+  - Returns: { success: true, deleted: boolean }
   - Delete one key from the default private per-user JSON store.
 
 ### Twinkle.reminders
 - async list({ includeDisabled, limit } = {}) | scopes: reminders:read
+  - Returns: { reminders: [{ id, buildId, userId, title, body, targetPath, payload, isEnabled, schedule, lastTriggeredAt, createdAt, updatedAt }] }
 - async create({ title, body, targetPath, payload, schedule, isEnabled }) | scopes: reminders:write
+  - Returns: { reminder: { id, buildId, userId, title, body, targetPath, payload, isEnabled, schedule, lastTriggeredAt, createdAt, updatedAt } | null }
 - async update(reminderId, patch) | scopes: reminders:write
+  - Returns: { reminder: { id, buildId, userId, title, body, targetPath, payload, isEnabled, schedule, lastTriggeredAt, createdAt, updatedAt } | null }
 - async remove(reminderId) | scopes: reminders:write
+  - Returns: { success: true, deleted: boolean }
 - async getDue({ now, autoAcknowledge, limit } = {}) | scopes: reminders:read
+  - Returns: { now, reminders: [{ id, buildId, userId, title, body, targetPath, payload, isEnabled, schedule, lastTriggeredAt, createdAt, updatedAt }] }
 
 ## Examples