@stage5/lumine 0.2.14 → 0.2.15

package/README.md

@@ -7,6 +7,8 @@ npx @stage5/lumine@latest
 npx @stage5/lumine@latest login
 npx @stage5/lumine@latest new "Daily Reflection App"
 npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Private journal with streaks"
+npx @stage5/lumine@latest rename "My New Build Title"
+npx @stage5/lumine@latest rename "New Title" --target 123
 npx @stage5/lumine@latest projects
 npx @stage5/lumine@latest explore --sort forks
 npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123

package/lib/api.js

@@ -290,12 +290,26 @@ export async function updateBuildThumbnailUrl({
   auth,
   buildId,
   thumbnailUrl,
+}) {
+  return updateBuildMetadata({
+    options,
+    auth,
+    buildId,
+    patch: { thumbnailUrl },
+  });
+}
+
+export async function updateBuildMetadata({
+  options,
+  auth,
+  buildId,
+  patch,
 }) {
   return requestJson({
     method: "PUT",
     url: `${options.apiUrl}/build/${buildId}`,
     authToken: auth.token,
-    body: { thumbnailUrl },
+    body: patch,
     timeoutMs: options.timeoutMs,
   });
 }

package/lib/commands.js

@@ -40,6 +40,7 @@ import {
   replaceMainWithContribution,
   resolveBranchBuild,
   saveProjectFiles,
+  updateBuildMetadata,
 } from "./api.js";
 import { assetsCommand, writeAssetsManifest } from "./assets.js";
 import { thumbnailCommand } from "./thumbnail.js";
@@ -121,6 +122,10 @@ export async function main() {
     await newBuild(options);
     return;
   }
+  if (options.command === "rename") {
+    await renameBuild(options);
+    return;
+  }
   if (options.command === "projects") {
     await projects(options);
     return;
@@ -221,6 +226,58 @@ export async function newBuild(options) {
   printNewBuildResult({ createResult, pullResult: result });
 }
 
+export async function renameBuild(options) {
+  const title = String(options.title || "").trim();
+  if (!title) {
+    throw new Error(
+      'Pass a title: `lumine rename "My New Build Title"` or `lumine rename --title "My New Build Title"`.',
+    );
+  }
+  const auth = await ensureAuth(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 currentBuild = await loadBuildMetadata({ options, auth, buildId });
+  if (currentBuild.canWrite === false) {
+    throw new Error(`You cannot rename Build #${buildId}.`);
+  }
+  if (Number(currentBuild.contributionRootBuildId || 0) > 0) {
+    throw new Error(
+      "Contribution branches use the original Build title and cannot be renamed.",
+    );
+  }
+  const result = await updateBuildMetadata({
+    options,
+    auth,
+    buildId,
+    patch: { title },
+  });
+  if (result?.success !== true || !result?.build) {
+    throw new Error(result?.error || "Failed to rename the Build.");
+  }
+  const updatedBuild = { ...currentBuild, ...result.build };
+  await saveSelectedBuild({ options, auth, build: updatedBuild });
+  if (
+    localProject?.rootDir &&
+    Number(localProject.metadata?.buildId || 0) === buildId
+  ) {
+    await writeProjectMetadata({
+      dir: localProject.rootDir,
+      options,
+      build: updatedBuild,
+      manifest: localProject.metadata.manifest || null,
+      pulledAt: localProject.metadata.pulledAt || null,
+      lastSavedAt: localProject.metadata.lastSavedAt || null,
+      filesHash: localProject.metadata.filesHash || null,
+    });
+  }
+  console.log(`Renamed Build #${buildId} to "${updatedBuild.title}".`);
+}
+
 export async function workspace(options) {
   const auth = await ensureAuth(options);
   const selectedBuild = options.target
@@ -1693,10 +1750,16 @@ export function parseArgs(args) {
     quality: raw.quality ? String(raw.quality) : "",
     assetName: raw.name ? String(raw.name) : "",
     out: raw.out ? String(raw.out) : "",
-    target: raw.url || raw.target || positional[0] || "",
+    target:
+      raw.url ||
+      raw.target ||
+      (command === "rename" ? "" : positional[0] || ""),
     title:
       String(
-        raw.title || (command === "new" ? positional.join(" ") : ""),
+        raw.title ||
+          (command === "new" || command === "rename"
+            ? positional.join(" ")
+            : ""),
       ).trim() || "",
     description: Object.prototype.hasOwnProperty.call(raw, "description")
       ? String(raw.description || "").trim()
@@ -1916,6 +1979,7 @@ export function printHelp() {
   lumine whoami
   lumine logout
   lumine new [title]
+  lumine rename [title] [--target <twinkle-build-url-or-id>]
   lumine projects
   lumine explore [search terms]
   lumine select [twinkle-build-url]
@@ -1949,6 +2013,8 @@ Examples:
   npx @stage5/lumine@latest
   npx @stage5/lumine@latest login
   npx @stage5/lumine@latest new "Daily Reflection App"
+  npx @stage5/lumine@latest rename "My New Build Title"
+  npx @stage5/lumine@latest rename "New Title" --target 123
   npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Private journal with streaks"
   npx @stage5/lumine@latest explore --sort forks
   npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
@@ -1983,9 +2049,10 @@ Options:
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
   --dir <path>          Directory for pulled project files
+  --target <build>      Explicit Build URL or ID for rename (positionals are title-only)
   --main                With pull/versions/restore: target the team project's main
   --version <n>         With pull: read-only checkout of previous save v<n>
-  --title <text>        New Build title
+  --title <text>        Build title for new/rename
   --description <text>  Optional New Build description
   --no-description      Skip the New Build description prompt
   --summary <text>      Save summary

package/lib/constants.js

@@ -324,6 +324,7 @@ export const COMMANDS = new Set([
   "logout",
   "whoami",
   "new",
+  "rename",
   "projects",
   "explore",
   "select",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "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.26.3
-Updated: 2026-07-10
-Generated: 2026-07-10T05:52:15.007Z
+Version: 1.27.0
+Updated: 2026-07-21
+Generated: 2026-07-23T05:57:27.486Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -25,7 +25,7 @@ Generated: 2026-07-10T05:52:15.007Z
 - Build app tab mute is enforced by the host runtime automatically for standard media elements and Web Audio connections to AudioContext.destination. Apps with custom audio engines can also observe Twinkle.onAudioMuteChange and check Twinkle.isAudioMuted.
 
 ## 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, notifications:emit, reminders:read, reminders:write
+files:read, user:read, users:read, dailyReflections:read, content:read, content:write, 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
 
@@ -80,6 +80,14 @@ files:read, user:read, users:read, dailyReflections:read, content:read, sharedDb
   - The parent validates that the target is still a Build preview URL before navigating.
   - External URLs are rejected and do not receive the Build bridge nonce.
   - Example: await Twinkle.app.navigate('./arena.html');
+- async openContent(target) | scopes: none
+  - Returns: { success, url }
+  - Open a recognized Twinkle content page in the parent app from a viewer click or tap.
+  - Call this directly from a user click or tap handler; calls without an active user action are rejected.
+  - The trusted parent displays the canonical destination and requires viewer confirmation before navigating.
+  - Only recognized Twinkle content URLs are accepted. The parent preserves its current signed-in origin when opening the content.
+  - Use navigate() for routes inside the current Build and openContent() for Twinkle subjects, comments, apps, profiles, and other content pages.
+  - Example: await Twinkle.app.openContent('https://www.twin-kle.com/subjects/432');
 
 ### Twinkle.preview
 - getLayout() | scopes: none
@@ -310,6 +318,9 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Generate or edit an image from a prompt and optional base64/data-URL reference image.
   - Signed-in viewers only.
   - Each successful image generation consumes AI Energy from the signed-in viewer.
+  - Call generateImage directly from an explicit viewer action such as a button click. Calls from page load, timers, background work, or programmatic retries are rejected.
+  - Twinkle shows a host-owned confirmation for every generation. One approval authorizes exactly one request.
+  - Only one image generation may be active at a time. Do not queue or automatically retry cancellation, ai_image_generation_in_progress, USER_ACTIVATION_REQUIRED, or 429 errors.
   - Default engine is openai and default quality is high.
   - The SDK timeout defaults to 390000ms for image generation because high-quality image runs can exceed normal request timing.
   - Pass onStatus to receive real-time stages from the backend: prompt_ready, in_progress, generating, partial_image, completed, and error.
@@ -382,6 +393,19 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Returns: { comments: [{ id, content, filePath, fileName, fileSize, thumbUrl, timeStamp }], cursor? }
   - Returns only the current viewer's own comments on the given subject.
   - Supports cursor-based pagination. Pass cursor from previous response to load more.
+- async getWriteStatus({ subjectId, commentId } = {}) | scopes: content:read
+  - Returns: { writeStatus: { serverNow, subjectCreate, commentCreate, subjectEdit, commentEdit } }
+  - Each operation slice is { cooldownSeconds, availableAt, retryAfterSeconds }.
+  - serverNow is unix seconds so progress bars ignore client clock skew.
+  - Pass subjectId/commentId to include per-target edit cooldowns.
+- async create({ title, description }) | scopes: content:write
+  - Returns: { subject, writeStatus }
+  - Creates a normal site subject (title + description only in v1).
+  - Site-wide durable cooldown: 600s between creates. 429 includes writeStatus.
+- async edit({ subjectId, title, description }) | scopes: content:write
+  - Returns: { subject, writeStatus }
+  - Own subjects only (userId === uploader). Never uses moderator edit rights.
+  - Per-subject edit cooldown: 10s.
 
 ### Twinkle.aiCards
 - async list({ limit, cursor, level, minLevel, maxLevel, quality, userId, hasImage, hasExample } = {}) | scopes: content:read
@@ -468,6 +492,13 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - For subject-poster books that include poster replies, use author: subjectPoster, includeReplies: true, and replyScope: ownThread so the poster's replies to other people do not become pages.
   - Supports cursor-based pagination. Pass cursor from the previous response to load more.
   - 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 });
+- async create({ subjectId, content }) | scopes: content:write
+  - Returns: { comment, writeStatus }
+  - Adds a top-level subject comment (book page). Own subject only.
+  - Site-wide durable cooldown: 20s between comment creates. 429 includes writeStatus.
+- async edit({ commentId, content }) | scopes: content:write
+  - Returns: { comment, writeStatus }
+  - Own comments only. Per-comment edit cooldown: 10s.
 
 ### Twinkle.profileComments
 - async getProfileComments({ profileUserId, limit, offset, sortBy, includeReplies, range, since, until } = {}) | scopes: content:read
@@ -540,7 +571,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Update a viewer-owned shared row, optionally notifying safe recipients from the canonical write.
   - Updates an entry. Only the entry creator or the build owner can update.
   - data must be a JSON object, max 10 KB.
-  - notify may include eventKey, label, summary, recipients, and target. Supported recipients include { kind: 'sharedDbEntryAuthor', entryId }.
+  - notify may include eventKey, label, summary, recipients, and target. Supported recipients include { kind: 'sharedDbEntryAuthor', entryId } and { kind: 'subjectAuthor', subjectId } (subject must be referenced by this build via a subject-linked sharedDb entry).
 - async deleteEntry(entryId) | scopes: sharedDb:write
   - Returns: { success: true }
   - Deletes an entry. Only the entry creator or the build owner can delete.