@hypit/hypit 0.1.3 → 0.1.5

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

@@ -0,0 +1,117 @@
+# Companion-owned Inspector fields
+
+The Inspector asks three questions. **Where** describes spatial placement and organization;
+**When** describes scheduling, playback and changes over time; **How** describes appearance,
+content and sound. These are navigation domains, not restrictions on component behavior.
+
+| Domain | Useful pages and sections |
+| --- | --- |
+| Where | Position, size, anchor, fitting/cropping, padding, clipping, stacking, layout |
+| When | Placement in time, playback/cycling, source trim, entrance, sustained motion, exit, transitions, fades |
+| How | Text/content, typography, fill/stroke, image adjustments, shadows, effect character, audio levels |
+
+Each Companion supplies page and section IDs and labels in declaration order. These examples are
+a shared vocabulary, not a registry of permitted pages. A new component can name a useful grouping
+without a Studio change. Put a field where its authoring decision belongs: motion duration is When,
+its color is How, and the object's frame is Where. One field has one owner and one location.
+
+## Controls describe the editing task
+
+`bindings` exposes actual author endpoints; `inspector` chooses which to show. A resolved field is
+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 |
+| --- | --- |
+| `text` | Text, identifiers, or a meaningful expression. `multiline: true` provides a textarea. |
+| `number` | A scalar with optional limits, stepping, display scaling, or an authored suffix. |
+| `boolean` | A two-state switch. |
+| `select` | A finite choice, including presets, font families or numeric weights. |
+| `color` | Hex text and a native color picker; optional `swatches` offers package-chosen colors. |
+| `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 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.
+
+## Separate author values from display values
+
+The DTO retains the authored `value`. A numeric presentation describes the small, reversible
+conversion into the editor. The server applies the inverse, validates the **authored** value against
+its public schema, and uses the author language's serializer. Source ranges and existing transactions
+still own the write. Failed validation or recompilation does not publish a partial edit.
+
+```ts
+// Authored as "78%" or "240px": edit only the magnitude, keep the existing unit.
+{ binding: "frame.width", label: "Width", domain: "where",
+  section: { id: "size", label: "Size" }, control: "number",
+  number: { suffixes: ["%", "px"], step: 1 } }
+
+// Authored as 0.78: display 78 %, write 0.42 when the author enters 42.
+{ binding: "appearance.opacity", label: "Opacity", domain: "how",
+  section: { id: "image", label: "Image" }, control: "number", unit: "%",
+  number: { scale: 100, minimum: 0, maximum: 100, step: 1 } }
+```
+
+`unit` is a label, not an instruction to append text. `suffixes` explicitly declares a string-valued
+number and retains whichever admitted suffix the current source uses. It does not convert `%` into
+pixels or seconds into frames. `scale` is positive; displayed value = authored magnitude × scale.
+Limits and step in `number` refer to displayed values. A number schema's limits and integer setting
+also inform the input when no presentation override is provided. Empty input is not silently zero.
+
+SVML strings escape attribute delimiters and entity characters. SVS values use `formatSvsValue`.
+Neither the UI nor a Companion writes source text through an arbitrary callback. Timeline temporal
+gestures are separate from Inspector field conversion; see the temporal author forms for their
+semantic-anchor and local-offset editing behavior.
+
+## Choices retain their actual value
+
+Existing string options are shorthand for identical value and label. Rich options can supply a
+different label, description and one small visual hint:
+
+```ts
+options: [
+  { value: "brand-serif", label: "Brand Serif", description: "Project headline face",
+    preview: { kind: "font", family: "Project Serif", sample: "Aa 字幕" } },
+  { value: "brand-sans", label: "Brand Sans" },
+]
+```
+
+A color hint uses `{ kind: "color", color: "#FF584A" }`. Values may be strings, numbers or booleans;
+the selected value, not its display label, is validated and written. Preview hints contain data only.
+Options remain named keyboard-operable choices. Font hints use a family available to the Studio
+document; declaring a hint does not install or load a font or change the composition's font bytes.
+
+The optional `@hypit/fonts-open/studio` helper owns its catalog labels and descriptions. Caption,
+Typography and Ranking Companions use it to reach a Style's referenced font and edit its `family`
+attribute. It appears for an actual writable family attribute; a `media:Font` file has no such
+attribute. The family still has to supply the authored weight and style. A local font keeps its exact
+file binding. Changing a shared font changes every consumer; this is visible Source reuse.
+
+Nested `referenced` declarations follow explicit author references, such as Style → Font → family.
+They neither scan for candidates nor replace whole-value references with strings. Project components
+can declare their own option values and binding paths through the same ABI.
+
+## Implementation owners
+
+- `studio-adapter` owns the data-only declarations and snapshot types.
+- Component Companions own grouping, choices, units and references to writable author facts.
+- Studio resolves endpoints, renders controls, converts display values and commits source edits.
+- SVML/SVS and the component's ordinary compilation remain the authority for valid authored work.
+
+The UI follows native numeric input behavior and named listbox options; reference material:
+[MDN numeric inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/number),
+[WAI listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).

package/packages/studio/README.md

@@ -14,11 +14,55 @@ When `--runtime` is omitted, Studio reads the resolved project's `.hypit/runtime
 selection made by `hypit runtime use`. It does not search parent projects for a
 Profile. `--workspace` explicitly selects the project boundary; `--package-root`
 overrides the author package resolution root when those locations intentionally differ.
+Startup prints the project, Run, Profile and whether the Profile came from the command argument or
+the project's selection file. Relative command-line paths start at the invoking directory;
+`--workspace` selects the project without rebasing `--run` or `--runtime`.
 The upper-left library is intentionally not a filesystem browser:
 
 - Source is the exact Run + Author closure and writes back only the selected file;
-- Tasks combine finished project Results with read-only active `BuildView` and Operation information;
-- Artifacts are public files exposed by project Build Results.
+- Tasks show one card per Build, with All, In progress and Finished filters. Active progress comes from
+  the selected Runtime's read-only control interface; completed, failed and cancelled Builds come
+  from the project's Result Repository. Saving a Result and an issue requiring attention remain
+  visible, with the source Run and available progress or failure reason.
+- Artifacts show top-level file Outputs whose declared MIME type is image, video or audio,
+  including files already published by ongoing Builds. Composite Outputs retain their structure:
+  the library does not extract their embedded resources. Forwarded file Outputs resolve to their
+  owner; references to the same owner file share one card and retain their origins. Highlighted
+  Outputs sort first, without excluding other media.
+
+Source, Tasks and Artifacts use the shared `ui/sidebar-panel.ts` layout and navigation buttons. Each view
+owns its toolbar content, data and actions; the shared shell owns geometry and navigation styling.
+
+Views load on entry; returning to Tasks preserves its loaded list and selection. Explicit Refresh reads the latest state. There is no library polling.
+Refresh replaces the current snapshot; scrolling to the end loads more finished Results. Failed
+refreshes preserve the last view and show the error. Artifacts show project media through an icon sidebar: All media, Videos, Images and Audio.
+The header names the category and offers Refresh. Selecting a Task adds its name beside the category in the existing header, establishing a session-local task context without shifting the list; its arrow opens that Build's media. The context remains across tab changes. Click its name to return to the selected Task, or clear it to browse project media. Task selection does not write Source, Result or Runtime state. Selected tasks expand the complete error text with a copy action. Source details are available on each media card. A media category is sent to the server, which
+walks Result metadata pages until it collects a useful batch of matching files or reaches the end.
+This keeps Build storage unchanged while avoiding empty category pages. The browser appends
+older matches on scroll; Refresh reads the latest results for the current category.
+
+Media cards use fixed-size square cells, contain the file at its own aspect ratio, and show up to two
+wrapped name lines below. Selection colors the thumbnail area and name separately, without an
+outer card border. Resizing the
+sidebar distributes spare width between columns, then adds a column when another fixed-size
+card fits. Card size stays unchanged. Video thumbnails decode a frame in the browser; audio waveforms are also
+browser presentation, not additional Result files. Thumbnails load as their cells enter view.
+The CLI carries the author's component name from compilation provenance into the Result's
+optional Output `displayName`. The public Output identifier stays intact for references;
+Outputs without a display name show that identifier unchanged. Double-click a name or press F2
+to edit it in full; Enter or blur saves, Escape cancels. Failed saves retain the text and show the
+reason. A completed, failed or cancelled Build's name is written through Result Repository
+`updatePresentation` to that exact Output's `displayName`. Ongoing Builds become editable when
+they finish, following the existing Result presentation-edit boundary. Renaming never changes
+Output identity, referenced media files or other Builds' names for the same file.
+
+The composition has a frame-snapped progress slider and current/total time.
+Clicking a card opens the file in the central preview and pauses the composition. Images need
+no transport; video and audio share the play/mute controls and a seconds-based scrubber above
+the playback bar. The previous/next buttons skip five seconds for media, and step one frame
+for the composition. Back to composition restores the existing composition playhead. Selecting
+or seeking in the composition timeline also returns to it. Opening media changes no Source,
+Run, or Candidate selection.
 
 No project manifest, Studio database, output-directory scan or inferred campaign
 folder structure is involved. With no selected Runtime, finished Result tasks and
@@ -28,11 +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.
+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
@@ -43,20 +154,37 @@ 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
 inverse remain read-only. Seeing an entity does not promise every drag gesture.
+
+A direct `during={selection}` move advances both endpoints by the same number of semantic
+stops (distinct frame positions), so its duration may change. `at/for` moves its event and
+offers a trailing duration trim; `until/for` offers the corresponding leading trim.
+An Instant reference expression edits only its offset; a bare reference has an implicit zero offset.
+`start/end` trims edit the corresponding expression; moving the window shifts both by the same
+frame delta. Edited clock values and offsets are written in frames at the current ProgramSpace rate.
+The semantic marker Inspector exposes exact anchor identities and, where a
+declared handle supports it, offers choices among coincident anchors.
+See [temporal author forms](../temporal-markup/EDITING.md) for the complete behavior.
+
 Tasks and Artifacts are inspection surfaces; selecting an Artifact does not write a
 Run Candidate. Use `build-record`/`satisfy` in the Run for explicit Output reuse.
 
 ## Component presentation
 
+[Inspector fields](INSPECTOR.md) describes Where/When/How grouping, numeric unit conversion,
+rich choices, fonts, color suggestions and exact Source writeback.
+
 Studio is an application boundary. Core and domain computation do not import it or
 register UI metadata. The installed Distribution explicitly selects one independent
 Studio Companion per supported official domain. Packages actually selected by the
@@ -76,13 +204,12 @@ 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.
-Studio owns session-wide behavior and chrome: Companion assembly, collision rules,
+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
 companion cannot ship arbitrary DOM or CSS into the application.
@@ -123,3 +250,11 @@ 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.