@hypit/hypit 0.1.4 → 0.1.6

package/packages/store-sqlite/src/store.ts

@@ -35,7 +35,6 @@ import type {
   OperationSnapshot,
   OperationStore,
   OperationUpdate,
-  RuntimeEnvironmentStore,
 } from "@hypit/runtime";
 
 export type SqliteRuntimeStateOptions = {
@@ -224,6 +223,7 @@ function parseExecutionRequest(row: Row, subject: string): BuildExecutionRequest
     `SQLite ${subject} Result location is invalid`);
   return {
     build: row.build_id,
+    ...(typeof row.context_json === "string" ? { context: JSON.parse(row.context_json) as NonNullable<BuildExecutionRequest["context"]> } : {}),
     componentPackages,
     result: result as BuildExecutionRequest["result"],
   };
@@ -263,12 +263,13 @@ class SqlitePendingBuildStore implements PendingBuildStore {
       assert(occupied === undefined, `Build ${request.build} already has Runtime state`);
       this.#database.prepare(`
         INSERT INTO hypit_submissions (
-          build_id, component_packages_json, result_location_json, created_at
-        ) VALUES (?, ?, ?, ?)
+          build_id, component_packages_json, result_location_json, context_json, created_at
+        ) VALUES (?, ?, ?, ?, ?)
       `).run(
         request.build,
         JSON.stringify(request.componentPackages),
         JSON.stringify(request.result),
+        request.context === undefined ? null : JSON.stringify(request.context),
         now,
       );
       return parsePendingBuildSubmission(
@@ -295,7 +296,8 @@ class SqlitePendingBuildStore implements PendingBuildStore {
       if (row === undefined) throw new Error(`Build submission ${request.build} was not prepared`);
       const submission = parsePendingBuildSubmission(row);
       assert(JSON.stringify(submission.componentPackages) === JSON.stringify(request.componentPackages)
-        && JSON.stringify(submission.result) === JSON.stringify(request.result),
+        && JSON.stringify(submission.result) === JSON.stringify(request.result)
+        && JSON.stringify(submission.context) === JSON.stringify(request.context),
       `Build submission ${request.build} does not match its prepared state`);
       this.#database.prepare(`
         INSERT INTO hypit_builds (build_id, definition_json) VALUES (?, ?)
@@ -305,15 +307,16 @@ class SqlitePendingBuildStore implements PendingBuildStore {
       `).run(request.build, Date.now(), JSON.stringify(request.catalog));
       this.#database.prepare(`
         INSERT INTO hypit_executions (
-          build_id, component_packages_json, result_location_json, created_at, wake_at,
+          build_id, component_packages_json, result_location_json, context_json, created_at, wake_at,
           turn_owner, turn_acquired_at, result_writer_owner, result_writer_acquired_at,
           stop_cause, stop_reason,
           decision_outcome, decision_reason, attention_step, attention_error
-        ) VALUES (?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL)
+        ) VALUES (?, ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL)
       `).run(
         request.build,
         JSON.stringify(request.componentPackages),
         JSON.stringify(request.result),
+        request.context === undefined ? null : JSON.stringify(request.context),
         submission.createdAt,
         Date.now(),
       );
@@ -424,6 +427,9 @@ function parseCommandExecution(row: Row): CommandExecutionReceipt {
     command: row.command_id,
     status: row.status,
     ...(event === undefined ? {} : { event }),
+    ...(row.status !== "started" || typeof row.activity_json !== "string" ? {} : {
+      activity: JSON.parse(row.activity_json) as NonNullable<CommandExecutionReceipt["activity"]>,
+    }),
   };
 }
 
@@ -456,7 +462,7 @@ class SqliteCommandExecutionStore implements CommandExecutionStore {
       const current = parseCommandExecution(row);
       if (current.status === "completed") return current;
       this.#database.prepare(`
-        UPDATE hypit_command_executions SET status = 'completed', event_json = ?
+        UPDATE hypit_command_executions SET status = 'completed', event_json = ?, activity_json = NULL
         WHERE build_id = ? AND command_id = ? AND status = 'started'
       `).run(JSON.stringify(event), build, command);
       return parseCommandExecution(this.#database.prepare(`
@@ -471,54 +477,18 @@ class SqliteCommandExecutionStore implements CommandExecutionStore {
     `).all(build) as Row[]).map(parseCommandExecution);
   }
 
-  async removeBuild(build: string): Promise<void> {
-    this.#database.prepare("DELETE FROM hypit_command_executions WHERE build_id = ?").run(build);
-  }
-}
-
-class SqliteRuntimeEnvironmentStore implements RuntimeEnvironmentStore {
-  readonly #database: DatabaseSync;
-
-  constructor(database: DatabaseSync) {
-    this.#database = database;
-  }
-
-  async use(config: string): Promise<void> {
-    assert(config.length > 0, "Runtime environment configuration is empty");
-    transaction(this.#database, () => {
-      const active = this.#database.prepare(
-        `SELECT
-          (SELECT COUNT(*) FROM hypit_submissions)
-          + (SELECT COUNT(*) FROM hypit_executions) AS count`,
-      ).get() as Row;
-      assert(typeof active.count === "number", "SQLite active Runtime work count is invalid");
-      const row = this.#database.prepare(
-        "SELECT config_json FROM hypit_runtime_environment WHERE singleton = 1",
-      ).get() as Row | undefined;
-      if (active.count > 0) {
-        assert(typeof row?.config_json === "string",
-          "Active Runtime work has no recorded environment; use its original Profile or resolve it explicitly");
-        assert(row.config_json === config,
-          "Runtime Profile differs from the environment pinned by active Builds");
-        return;
-      }
-      this.#database.prepare(`
-        INSERT INTO hypit_runtime_environment (singleton, config_json) VALUES (1, ?)
-        ON CONFLICT(singleton) DO UPDATE SET config_json = excluded.config_json
-      `).run(config);
-    });
+  async reportProgress(build: string, command: string, activity: NonNullable<CommandExecutionReceipt["activity"]>): Promise<void> {
+    this.#database.prepare(`
+      UPDATE hypit_command_executions SET activity_json = ?
+      WHERE build_id = ? AND command_id = ? AND status = 'started'
+    `).run(JSON.stringify(activity), build, command);
   }
 
-  async assert(config: string): Promise<void> {
-    const row = this.#database.prepare(
-      "SELECT config_json FROM hypit_runtime_environment WHERE singleton = 1",
-    ).get() as Row | undefined;
-    assert(typeof row?.config_json === "string" && row.config_json === config,
-      "Runtime Profile no longer matches this Worker's active environment");
+  async removeBuild(build: string): Promise<void> {
+    this.#database.prepare("DELETE FROM hypit_command_executions WHERE build_id = ?").run(build);
   }
 }
 
-
 function parseExecutionSnapshot(row: Row): BuildExecutionSnapshot {
   assert(typeof row.created_at === "number", "SQLite Execution creation time is invalid");
   assert(row.wake_at === null || typeof row.wake_at === "number", "SQLite Execution wake time is invalid");
@@ -538,6 +508,7 @@ function parseExecutionSnapshot(row: Row): BuildExecutionSnapshot {
   return {
     ...parseExecutionRequest(row, "Execution"),
     createdAt: row.created_at,
+    ...(typeof row.started_at === "number" ? { startedAt: row.started_at } : {}),
     ...(typeof row.wake_at === "number" ? { wakeAt: row.wake_at } : {}),
     ...(typeof row.operation_wait_json === "string" ? { operationWait: JSON.parse(row.operation_wait_json) as string[] } : {}),
     ...(typeof row.turn_owner === "string" ? {
@@ -582,12 +553,12 @@ class SqliteBuildExecutionStore implements BuildExecutionStore {
     nonNegativeInteger(now, "Execution creation time");
     this.#database.prepare(`
       INSERT INTO hypit_executions (
-        build_id, component_packages_json, result_location_json, created_at, wake_at,
+        build_id, component_packages_json, result_location_json, context_json, created_at, wake_at,
         turn_owner, turn_acquired_at, result_writer_owner, result_writer_acquired_at,
         stop_cause, stop_reason,
         decision_outcome, decision_reason, attention_step, attention_error
-      ) VALUES (?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL)
-    `).run(request.build, JSON.stringify(request.componentPackages), JSON.stringify(request.result), now, now);
+      ) VALUES (?, ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL)
+    `).run(request.build, JSON.stringify(request.componentPackages), JSON.stringify(request.result), request.context === undefined ? null : JSON.stringify(request.context), now, now);
     return {
       ...copy(request),
       createdAt: now,
@@ -608,19 +579,20 @@ class SqliteBuildExecutionStore implements BuildExecutionStore {
     return rows.map(parseExecutionSnapshot);
   }
 
-  async claim(owner: string, now = Date.now()): Promise<BuildExecutionSnapshot | undefined> {
+  async claim(owner: string, now = Date.now(), build?: string): Promise<BuildExecutionSnapshot | undefined> {
     assert(owner.trim().length > 0, "Execution turn owner is empty");
     nonNegativeInteger(now, "Execution claim time");
     return transaction(this.#database, () => {
       const row = this.#database.prepare(`
         SELECT execution.build_id FROM hypit_executions AS execution
         WHERE decision_outcome IS NULL AND turn_owner IS NULL AND wake_at <= ?
+          AND (? IS NULL OR execution.build_id = ?)
         ORDER BY EXISTS (
           SELECT 1 FROM hypit_capacity AS capacity
           WHERE capacity.build_id = execution.build_id
         ) DESC, wake_at ASC, created_at ASC, execution.build_id ASC
         LIMIT 1
-      `).get(now) as Row | undefined;
+      `).get(now, build ?? null, build ?? null) as Row | undefined;
       if (row === undefined) return undefined;
       assert(typeof row.build_id === "string", "SQLite ready Execution has no Build id");
       const updated = this.#database.prepare(`
@@ -635,6 +607,45 @@ class SqliteBuildExecutionStore implements BuildExecutionStore {
     });
   }
 
+  async listUnstarted(): Promise<readonly string[]> {
+    return (this.#database.prepare(`SELECT build_id FROM hypit_executions
+      WHERE decision_outcome IS NULL AND started_at IS NULL ORDER BY created_at, build_id`).all() as Row[])
+      .map((row) => row.build_id as string);
+  }
+
+  async listReady(now = Date.now()): Promise<readonly string[]> {
+    return (this.#database.prepare(`SELECT build_id FROM hypit_executions
+      WHERE decision_outcome IS NULL AND turn_owner IS NULL AND wake_at <= ?
+      ORDER BY wake_at, created_at, build_id`).all(now) as Row[]).map((row) => row.build_id as string);
+  }
+
+  async start(build: string, now = Date.now()): Promise<BuildExecutionSnapshot> {
+    nonNegativeInteger(now, "Execution start time");
+    const updated = this.#database.prepare(`
+      UPDATE hypit_executions SET started_at = ?
+      WHERE build_id = ? AND started_at IS NULL AND decision_outcome IS NULL
+    `).run(now, build);
+    assert(updated.changes === 1, `Execution ${build} has already started or ended`);
+    return (await this.read(build))!;
+  }
+
+  async interrupt(build: string, reason: string): Promise<BuildExecutionSnapshot> {
+    return transaction(this.#database, () => {
+      const row = this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row | undefined;
+      assert(row !== undefined, `Execution ${build} does not exist`);
+      const current = parseExecutionSnapshot(row);
+      if (current.decision !== undefined) return current;
+      this.#release(build);
+      this.#database.prepare(`
+        UPDATE hypit_executions SET decision_outcome = ?, decision_reason = ?,
+          turn_owner = NULL, turn_acquired_at = NULL,
+          result_writer_owner = NULL, result_writer_acquired_at = NULL
+        WHERE build_id = ?
+      `).run(current.stop?.cause === "user-cancelled" ? "cancelled" : "failed", current.stop?.reason ?? reason, build);
+      return parseExecutionSnapshot(this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row);
+    });
+  }
+
   async releaseTurn(build: string, owner: string, wakeAt: number | undefined, operationWait?: readonly string[]): Promise<BuildExecutionSnapshot> {
     if (wakeAt !== undefined) nonNegativeInteger(wakeAt, "Execution wakeAt");
     return transaction(this.#database, () => {
@@ -902,28 +913,6 @@ class SqliteBuildExecutionStore implements BuildExecutionStore {
     transaction(this.#database, () => this.#release(build));
   }
 
-  async reclaimTurns(now = Date.now()): Promise<readonly string[]> {
-    nonNegativeInteger(now, "Execution turn reclaim time");
-    return transaction(this.#database, () => {
-      const rows = this.#database.prepare(
-        "SELECT build_id FROM hypit_executions WHERE turn_owner IS NOT NULL AND decision_outcome IS NULL",
-      ).all() as Row[];
-      const builds = rows.map((row) => {
-        assert(typeof row.build_id === "string", "SQLite owned Execution has no Build id");
-        return row.build_id;
-      });
-      for (const row of rows) {
-        assert(typeof row.build_id === "string", "SQLite active Execution is invalid");
-        this.#database.prepare(`
-          UPDATE hypit_executions
-          SET turn_owner = NULL, turn_acquired_at = NULL, wake_at = ?
-          WHERE build_id = ? AND decision_outcome IS NULL
-        `).run(now, row.build_id);
-      }
-      return builds;
-    });
-  }
-
   async listCapacity(): Promise<readonly CapacityReservation[]> {
     return (this.#database.prepare(
       "SELECT * FROM hypit_capacity ORDER BY created_at ASC, build_id ASC, command_id ASC",
@@ -961,7 +950,6 @@ export class SqliteRuntimeState {
   readonly commandExecutions: CommandExecutionStore;
   readonly execution: BuildExecutionStore;
   readonly catalog: BuildCatalog;
-  readonly environment: RuntimeEnvironmentStore;
   readonly submissions: PendingBuildStore;
   readonly #database: DatabaseSync;
 
@@ -1007,6 +995,7 @@ export class SqliteRuntimeState {
         command_id TEXT NOT NULL,
         status TEXT NOT NULL CHECK (status IN ('started', 'completed')),
         event_json TEXT,
+        activity_json TEXT,
         PRIMARY KEY (build_id, command_id)
       ) STRICT;
       CREATE TABLE IF NOT EXISTS hypit_build_catalog (
@@ -1018,13 +1007,16 @@ export class SqliteRuntimeState {
         build_id TEXT PRIMARY KEY,
         component_packages_json TEXT NOT NULL,
         result_location_json TEXT NOT NULL,
+        context_json TEXT,
         created_at INTEGER NOT NULL
       ) STRICT;
       CREATE TABLE IF NOT EXISTS hypit_executions (
         build_id TEXT PRIMARY KEY,
         component_packages_json TEXT NOT NULL,
         result_location_json TEXT NOT NULL,
+        context_json TEXT,
         created_at INTEGER NOT NULL,
+        started_at INTEGER,
         wake_at INTEGER,
         operation_wait_json TEXT,
         turn_owner TEXT,
@@ -1062,17 +1054,26 @@ export class SqliteRuntimeState {
         resource_id TEXT PRIMARY KEY, limit_units INTEGER NOT NULL, period_ms INTEGER NOT NULL,
         tokens REAL NOT NULL, updated_at INTEGER NOT NULL
       ) STRICT;
-      CREATE TABLE IF NOT EXISTS hypit_runtime_environment (
-        singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
-        config_json TEXT NOT NULL
-      ) STRICT;
     `);
+    if (!options.readOnly) transaction(database, () => {
+      for (const table of ["hypit_submissions", "hypit_executions"]) {
+        const columns = database.prepare(`PRAGMA table_info(${table})`).all() as Row[];
+        if (!columns.some((column) => column.name === "context_json")) database.exec(`ALTER TABLE ${table} ADD COLUMN context_json TEXT`);
+        if (table === "hypit_executions" && !columns.some((column) => column.name === "started_at")) database.exec("ALTER TABLE hypit_executions ADD COLUMN started_at INTEGER");
+      }
+    });
+    // Add the nullable live-activity column without touching any accepted facts or Results.
+    if (!options.readOnly) transaction(database, () => {
+      if (!(database.prepare("PRAGMA table_info(hypit_command_executions)").all() as Row[])
+        .some((column) => column.name === "activity_json")) {
+        database.exec("ALTER TABLE hypit_command_executions ADD COLUMN activity_json TEXT");
+      }
+    });
     this.builds = new SqliteBuildStore(database);
     this.operations = new SqliteOperationStore(database);
     this.commandExecutions = new SqliteCommandExecutionStore(database);
     this.execution = new SqliteBuildExecutionStore(database);
     this.catalog = new SqliteBuildCatalog(database);
-    this.environment = new SqliteRuntimeEnvironmentStore(database);
     this.submissions = new SqlitePendingBuildStore(database);
   }
 

package/packages/studio/INSPECTOR.md

@@ -18,7 +18,20 @@ its color is How, and the object's frame is Where. One field has one owner and o
 ## Controls describe the editing task
 
 `bindings` exposes actual author endpoints; `inspector` chooses which to show. A resolved field is
-shown only when its binding is writable. The finite controls are independent of the three domains:
+shown when selected by the Companion, including read-only bindings. The interface orders available
+domains as Where, When, How. Read-only values and editable controls share the same sections.
+
+A projected entity may supply a few computed `inspector` facts without binding them to Source:
+
+```ts
+inspector: [{ id: "range", label: "Range", domain: "when",
+  section: { id: "placement", label: "Placement" }, value: "15–105", unit: "f" }]
+```
+
+The resolved DTO carries an `edit: { language, source }` only for writable author fields.
+The UI uses plain selectable text otherwise; the server requires that endpoint for writes.
+Choose facts that explain the selected object or its controls. Component headers organize lanes;
+the selected entities own their details. The finite controls are independent of the three domains:
 
 | Control | Use |
 | --- | --- |
@@ -30,7 +43,7 @@ shown only when its binding is writable. The finite controls are independent of
 | `list` | An ordered value described by an array schema, such as a palette or repeated settings. |
 | `record` | Named values described by an object schema, such as one shadow's parameters. |
 
-Lists and records retain Apply/Reset drafts. Their schema owns value shape. There is no separate
+Lists and records save complete, valid values when editing ends. Incomplete edits show a completion hint; their schema owns value shape. There is no separate
 palette database, font control protocol, generic CSS editor, or component-supplied DOM renderer.
 Use text for an expression whose parts cannot meaningfully be edited as one number.
 

package/packages/studio/LOCALIZATION.md

@@ -0,0 +1,98 @@
+# Localizing Studio
+
+Studio owns its interface messages; a language pack supplies their wording. The
+English catalog in [locales/en.json](locales/en.json) is the complete list of
+message IDs. [Simplified Chinese](locales/zh-CN.json) uses exactly the same format
+as any additional language. A pack is JSON data, not executable code.
+
+## Add a language
+
+Copy `locales/en.json`, change `locale` (a BCP 47 tag such as `ja` or `pt-BR`),
+`name` (the language's native name), and translate the message values. Keep the
+message IDs. `direction` is `ltr` or `rtl` and controls translated text; it does
+not reverse the physical video timeline or canvas coordinates.
+
+A small, valid starting point is:
+
+```json
+{
+  "locale": "ja",
+  "name": "日本語",
+  "direction": "ltr",
+  "messages": {
+    "app.studio": "スタジオ",
+    "app.comments": "コメント",
+    "app.language": "言語"
+  }
+}
+```
+
+Missing messages use English, so a partial translation is useful immediately.
+Text is displayed as text, never interpreted as HTML. Preserve named variables
+such as `{name}` and `{count}`; their order may change to suit the language.
+Messages with `{count}` can be strings or plural forms:
+
+```json
+{ "one": "{count} item", "other": "{count} items" }
+```
+
+Use the language's `Intl.PluralRules` categories (`zero`, `one`, `two`, `few`,
+`many`, `other`); `other` is required. Numbers and interface dates use the chosen
+locale. Choose natural full sentences instead of assembling translated fragments.
+
+Check and load your file:
+
+```sh
+hypit studio --check-locale ./ja.json
+hypit studio --run ./render.svrun --locale-pack ./ja.json
+```
+
+The check lists missing translations and unknown IDs and reports malformed
+messages or renamed variables. It does not open a Run or require a Runtime.
+Relative file paths start at the command's working directory; prefix them with
+`./` or `../`. Repeat `--locale-pack` to load multiple languages. Packs are read
+at server startup; restart Studio after editing a pack. An explicitly loaded
+pack with an existing locale replaces that locale's pack, with English fallback
+for any omitted messages.
+
+## Share a language pack
+
+A local file is sufficient. For reuse, publish it through an ordinary package
+under your own scope; there is no Hypit language registry or separate approval
+step. Export the JSON file in the package's `package.json`, for example:
+
+```json
+{
+  "name": "@your-scope/studio-ja",
+  "version": "1.0.0",
+  "files": ["ja.json"],
+  "exports": { "./locale.json": "./ja.json" }
+}
+```
+
+Install it using the project's package manager, then load it explicitly:
+
+```sh
+hypit studio --run ./render.svrun --locale-pack @your-scope/studio-ja/locale.json
+```
+
+Package exports resolve from the project, or `--package-root` when specified.
+Studio reads the resolved JSON without importing package code. It neither scans
+for language packs nor installs missing packages.
+
+## Interface behavior and ownership
+
+The globe menu to the left of **Studio / Comments** lists loaded languages by
+their native names. The first visit follows the browser's language preferences;
+subsequent visits retain the choice saved in that browser. Switching updates
+marked labels in place, preserving the playhead, selection and comment draft.
+
+Only Studio-owned interface text belongs in this catalog. Component names,
+Companion-supplied labels, Source code, user comments and raw service diagnostics
+retain their original text. Language packs do not change the Companion ABI,
+Core, compilation, or rendering. A component remains the owner of its labels.
+
+When adding Studio UI, give each message a stable ID in the English catalog and
+use the helpers in `src/ui/i18n.ts` for text and attributes. Do not use English
+wording as IDs, inspect DOM text to guess what needs translation, or put language
+branches into components. Keep interpolation values separate from message text.

package/packages/studio/README.md

@@ -72,14 +72,78 @@ transient processing require the selected Runtime.
 
 ## Opening and editing a session
 
+The CLI prints the actual session URL and its direct `#comments` URL after the server chooses a port.
+Open the latter to review the current composition before export. Browser playback creates no export
+Build or encoded video; an export remains a separate Run execution when the user wants the file.
+
+The top-right **Studio / Comments** tabs change the layout around the same composition player.
+Comments gives the picture the available height with a notes column on the right. Click the picture
+to play or pause; the wider progress control seeks, with a hovered-frame preview that leaves the
+main playhead alone. The hover picture uses one lazy, muted instance of the current preview document,
+released when leaving Comments. It needs no Build or thumbnail files.
+
+Studio retains picture selection and its right-click menu for overlapping Companion entities.
+Comments uses viewing controls without selecting objects. Switching views preserves the composition
+time and Studio's selection; comments themselves only refer to a time and the user's words.
+
+### Comments are project files
+
+Studio saves comments in `<workspace>/FEEDBACK.json`, creating it on the first saved comment.
+This path is Studio's project-file convention, rooted in the resolved workspace; it is independent
+of the Runtime, Result repository and Agent implementation.
+Each comment records its reviewed Run relative to that workspace, so the file can hold notes for
+several Runs while the UI shows the current Run. Times are seconds, including fractional seconds:
+
+```json
+{
+  "comments": [
+    {
+      "id": "caption-size",
+      "run": "runs/main.svrun",
+      "at": 12.5,
+      "text": "Make this caption larger.",
+      "resolved": false
+    }
+  ]
+}
+```
+
+`id`, `run`, `at` and `text` are required. `resolved` defaults to false; setting it to true marks
+the comment complete, and false reopens it. Deleting removes the entry. Following a note seeks to
+its saved time; a changed composition can show something different at that time.
+
+Focusing the comment composer pauses the picture and captures the current frame. The time chip
+captures a new time. The draft keeps its time while the user writes. Click a saved timestamp to
+revisit it. Comments can be edited, completed, reopened and deleted from the UI or by editing the file.
+The list is ordered by timestamp. Its `#1`, `#2` labels follow submission order within the current
+Run (the file's array order) and appear beside the completion control. Changing a timestamp or
+filtering Open/Done preserves those numbers; deleting a note closes its gap in the numbering.
+The stored `id` remains the stable identity. Clicking a note's text or time seeks
+to its frame. The composer has an icon-only send control; emoji and drawing buttons are inactive placeholders.
+Clicking outside the selected note clears its highlight without discarding an edit. Enter sends a
+new note or saves an edited one; Shift+Enter or Alt+Enter inserts a line break. IME confirmation stays
+with the text input rather than submitting the comment.
+
+File changes refresh comments through filesystem events, without polling or recompiling the video.
+Studio reads the file afresh for each edit, preserves unrelated notes and project-added fields, and
+rejects an edit to a comment that has changed since it was displayed. An invalid manually edited
+file remains intact and its error is shown. Unsent text stays in the browser. Agent notification is
+a separate, planned connection; **Send comment** currently saves the note only.
+
+### Composition editing
+
 The selected targets must reach one Film and its resolved time source. Studio rejects several
-distinct Films in one view; use separate Runs/sessions for those. A SemanticTrack supplies the
-Script lane and performance timing, including wordless Segments with media spans. A declared
-ProgramSpace supplies authored animation time without a Script lane. Both show their component
-tracks and use the same rendering and parameter-editing machinery. When the snapshot contains
-a semantic timeline, its lane and label stay pinned directly below the time ruler while
-component tracks scroll. Its presence follows the resolved semantic timeline, including
-wordless content, rather than a component name or the presence of spoken words.
+distinct Films in one view; use separate Runs/sessions for those. A Timeline supplies the
+placed material and semantic timing, including wordless Segments. The ruler always shows program
+time. When placed Segments are present, its left Timeline header spans the time ticks and the
+Segment, Word and Selection/Moment bands. Empty Word or marker bands are omitted based on the
+whole work, not the visible window or playhead. With no Segments, only the ordinary time ruler remains.
+The complete ruler area stays pinned while component tracks scroll.
+
+Semantic objects retain declaration-order drawing within each band. Their fine borders distinguish
+adjacent and overlapping intervals without inventing time gaps. Selection raises an object above
+its peers; playback highlighting changes color without changing that order. Right-click an overlap
+to choose a covered object. These are editor presentation rules, independent of Film paint order.
 
 Open the URL printed by Vite. Studio requests port 5179 by default, accepts `--port`,
 and Vite can choose another available port when it is occupied. Reuse that process
@@ -90,11 +154,14 @@ package code or imports that introduce new packages. Browser refresh does not re
 server-side package modules.
 
 The Source pane can edit the selected `.svml`, `.svs` or `.svrun` file. The Inspector
-shows project facts when no entity is selected and only declared writable fields for
+shows project facts when no entity is selected and declared facts and author fields for
 the selected entity. A reference can resolve to a shared Frame or Recipe, so one edit
-may affect several consumers. Structured fields use Apply/Reset for their local draft.
+may affect several consumers. Structured fields save together when editing ends and the value is complete; missing required values stay in the editor with a completion hint.
 Check save status; source conflicts reject stale edits rather than overwrite newer files.
 
+The Timeline owns the editor's complete range; displayed objects do not extend it. Take placement
+and complete extent are reference information in Studio.
+
 Timeline gestures use explicit temporal authority. Moving a shared Selection or
 Moment edits Script and moves its consumers after recompilation. A parameter-based
 handle edits its exact authored parameter. Fixed or derived values with no supported
@@ -137,12 +204,11 @@ at runtime. Ship the Companion's compiled JavaScript with its component package.
 The companion owns what its Track means: matching, required same-Surface values,
 entities, lane range, finite chrome, title and ordered text/material layers,
 source bindings, Inspector fields and executed temporal lineage. Inspector fields
-select real writable bindings and organize them under the Studio-owned
-`Where / How / When` domains, optional companion-owned pages and sections. A
+select real bindings or package-owned facts and organize them under the Studio-owned
+`Where / When / How` domains, optional companion-owned pages and sections. A
 source binding is never shown merely because Studio can reach it. Material layers carry a
-Resource id or Surface identity, never a Studio HTTP URL. Studio always owns
-time formatting and transport resolution, so chrome and material cannot hide a
-title or its time.
+Resource id or Surface identity, never a Studio HTTP URL. Studio owns time formatting and transport resolution. Compact chrome shows one primary label;
+computed time remains available in its tooltip rather than competing with that label.
 Studio owns session-wide behavior and chrome: Companion assembly, single-row overlap display,
 fallback defaults, selection treatment, playback, zoom,
 scrolling, the finite Inspector control set and source mutation transport. A
@@ -184,3 +250,24 @@ semantics.
 
 Read [`@hypit/studio-adapter`](../studio-adapter/README.md) for the Companion ABI,
 project activation example, value projection and Inspector declarations.
+
+## Composition audio preview
+
+The preview consumes generic AudioClips: source sampling, fixed gain, program-sample gain envelopes,
+audibility regions and target-relative fades. Web Audio gain nodes schedule the independent factors
+on the same clock, including silence and amplification above unity. Visual video elements stay muted;
+the Film's selected AudioTracks own composition sound. Seeking is silent. This path is independent of
+which component emitted a clip.
+
+### Interface language
+
+The globe menu to the left of **Studio / Comments** selects a language. English
+and Simplified Chinese are included; additional JSON language packs can be loaded
+with `--locale-pack`, from local files or installed package exports. The first
+visit follows browser preferences, and later visits remember the user's choice.
+Switching preserves the playhead, selection and comment draft.
+
+[Localizing Studio](LOCALIZATION.md) explains the message catalog, plural forms,
+translation checks and language-pack distribution. Only Studio-owned interface
+text is translated; Companion labels, project content and raw diagnostics retain
+their original text. The Companion ABI is unchanged.