@hypit/hypit 0.1.4 → 0.1.6

package/packages/studio/locales/en.json

@@ -0,0 +1,197 @@
+{
+  "locale": "en",
+  "name": "English",
+  "direction": "ltr",
+  "messages": {
+    "app.comments": "Comments",
+    "app.language": "Language",
+    "app.studio": "Studio",
+    "app.studio-view": "Studio view",
+    "comments.all": "All",
+    "comments.caught-up": "All caught up",
+    "comments.delete-comment": "Delete comment",
+    "comments.done": "Done",
+    "comments.draw-soon": "Draw — coming later",
+    "comments.edit-comment": "Edit comment",
+    "comments.edit-comment-text": "Edit comment text",
+    "comments.emoji-soon": "Emoji — coming later",
+    "comments.empty": "A note starts here",
+    "comments.empty-hint": "Pause on a frame and describe what you would like to change.",
+    "comments.filter-comments": "Filter comments",
+    "comments.filter-hint": "Switch filters to see the other comments.",
+    "comments.go-to-this-frame": "Go to this frame",
+    "comments.loading-comments": "Loading comments…",
+    "comments.mark-complete": "Mark complete",
+    "comments.no-completed-comments": "No completed comments",
+    "comments.open": "Open",
+    "comments.placeholder": "What would you like to change?",
+    "comments.read-failed": "Could not read comments.",
+    "comments.refresh-comments": "Refresh comments",
+    "comments.reopen-comment": "Reopen comment",
+    "comments.save-failed": "Could not save comment.",
+    "comments.send-comment": "Send comment",
+    "comments.send-shortcut": "Send comment (Enter)",
+    "comments.use-current-frame": "Use current frame",
+    "comments.write-a-comment": "Write a comment",
+    "common.cancel": "Cancel",
+    "common.cancelled": "Cancelled",
+    "common.compile-failed": "Compile failed",
+    "common.completed": "Completed",
+    "common.copied": "Copied",
+    "common.failed": "Failed",
+    "common.invalid-value": "Invalid value",
+    "common.needs-attention": "Needs attention",
+    "common.queued": "Queued",
+    "common.refresh": "Refresh",
+    "common.running": "Running",
+    "common.save": "Save",
+    "common.save-failed": "Save failed",
+    "common.saved": "Saved",
+    "common.saving": "Saving",
+    "common.waiting": "Waiting",
+    "inspector.add-color": "Add color",
+    "inspector.add-item": "Add item",
+    "inspector.anchor.program-end": "Timeline end{detail}",
+    "inspector.anchor.program-start": "Timeline start{detail}",
+    "inspector.anchor.segment-end": "Segment end{detail}",
+    "inspector.anchor.segment-start": "Segment start{detail}",
+    "inspector.anchor.token-end": "Word end{detail}",
+    "inspector.anchor.token-start": "Word start{detail}",
+    "inspector.aspect-ratio": "Aspect ratio",
+    "inspector.author": "Author",
+    "inspector.build": "Build",
+    "inspector.candidates": "Candidates",
+    "inspector.canvas": "Canvas",
+    "inspector.duration": "Duration",
+    "inspector.empty": "No details for this selection",
+    "inspector.end": "End",
+    "inspector.end-anchor": "End semantic anchor",
+    "inspector.frame-rate": "Frame rate",
+    "inspector.frames": "Frames",
+    "inspector.how": "How",
+    "inspector.invalid-fields": "Complete the required fields with valid values to save.",
+    "inspector.item-count": {
+      "one": "{count} item",
+      "other": "{count} items"
+    },
+    "inspector.moment": "Moment",
+    "inspector.moment-anchor": "Moment semantic anchor",
+    "inspector.move-down": "Move down",
+    "inspector.move-up": "Move up",
+    "inspector.project": "Project",
+    "inspector.properties": "Properties",
+    "inspector.remove-item": "Remove item",
+    "inspector.resolution": "Resolution",
+    "inspector.run": "Run",
+    "inspector.semantic-anchors": "Semantic anchors",
+    "inspector.sources": "Sources",
+    "inspector.start": "Start",
+    "inspector.start-anchor": "Start semantic anchor",
+    "inspector.structured-value": "Structured value",
+    "inspector.targets": "Targets",
+    "inspector.timeline": "Timeline",
+    "inspector.timing": "Timing",
+    "inspector.tracks": "Tracks",
+    "inspector.use-color": "Use {color}",
+    "inspector.when": "When",
+    "inspector.where": "Where",
+    "library.all-media": "All media",
+    "library.all-tasks": "All tasks",
+    "library.artifacts": "Artifacts",
+    "library.audio": "Audio",
+    "library.clear-task-filter": "Clear task filter",
+    "library.data": "Data",
+    "library.display-name": "Display name",
+    "library.enter-name": "Enter a name.",
+    "library.finished": "Finished",
+    "library.image": "Image",
+    "library.images": "Images",
+    "library.in-progress": "In progress",
+    "library.loading-media": "Loading media…",
+    "library.loading-more": "Loading more…",
+    "library.loading-tasks": "Loading tasks…",
+    "library.media-categories": "Media categories",
+    "library.media-category": "Media category",
+    "library.media-hint": "Images, videos and audio published as file Outputs appear here, including those from ongoing Builds.",
+    "library.name-failed": "Could not save the name",
+    "library.name-pending": "{name}\nNaming is available when this Build finishes",
+    "library.no-files-in-this-category": "No files in this category",
+    "library.no-media": "No media",
+    "library.no-tasks-here": "No tasks here",
+    "library.no-tasks-in-progress": "No tasks in progress",
+    "library.preview-name": "Preview {name}",
+    "library.preview-unavailable": "Preview unavailable",
+    "library.referenced-source-files": "Referenced source files",
+    "library.refresh-failed": "Refresh failed: {detail}",
+    "library.refresh-failed-retained": "Refresh failed: {detail} · Previous view retained",
+    "library.refresh-interrupted": "Refresh interrupted",
+    "library.refresh-media": "Refresh media",
+    "library.refresh-tasks": "Refresh tasks",
+    "library.refreshing": "Refreshing…",
+    "library.rename-hint": "{name}\nDouble-click or press F2 to rename",
+    "library.return-to-task": "Return to task",
+    "library.source": "Source",
+    "library.studio-library": "Studio library",
+    "library.task-categories": "Task categories",
+    "library.task-return": "{name} · Return to task",
+    "library.tasks": "Tasks",
+    "library.unavailable": "Library unavailable",
+    "library.updated": "Updated {time}",
+    "library.video": "Video",
+    "library.video-loading-preview": "Video · Loading preview",
+    "library.videos": "Videos",
+    "library.view-media": "View media",
+    "library.view-task-media": "View task media",
+    "player.audio-waveform": "Audio waveform",
+    "player.back-5-seconds": "Back 5 seconds",
+    "player.back-to-composition": "Back to composition",
+    "player.composition-time": "Composition time",
+    "player.elements-at-this-point": "Elements at this point",
+    "player.forward-5-seconds": "Forward 5 seconds",
+    "player.frame-loading": "Loading frame…",
+    "player.frame-unavailable": "Frame unavailable",
+    "player.hovered-frame": "Hovered frame",
+    "player.media-failed": "This media could not be opened in the browser.",
+    "player.media-time": "Media time",
+    "player.mute": "Mute",
+    "player.next-frame": "Next frame",
+    "player.pause": "Pause",
+    "player.play": "Play",
+    "player.preview": "Preview",
+    "player.previous-frame": "Previous frame",
+    "player.unmute": "Unmute",
+    "source.changed-outside-studio": "Changed outside Studio",
+    "source.edit-source": "Edit source",
+    "source.keep-lines-unwrapped": "Keep lines unwrapped",
+    "source.read-source": "Read source",
+    "source.save-failed-status": "Save failed ({status})",
+    "source.saving-before-switch": "Saving before switch",
+    "source.svml-source": "SVML source",
+    "source.unsaved": "Unsaved",
+    "source.wrap-lines": "Wrap lines",
+    "tasks.copy-error": "Copy error",
+    "tasks.copy-manually": "Select the text to copy",
+    "tasks.no-runtime": "No Runtime is selected. Saved tasks are available under Finished.",
+    "tasks.progress": "{completed}/{total} steps complete",
+    "tasks.refresh-hint": "Refresh to read the latest task status.",
+    "tasks.saved-only": "Saved project Results · no Runtime selected",
+    "timeline.fit-timeline": "Fit timeline",
+    "timeline.moment-name": "Moment {name}",
+    "timeline.overlapping-timeline-objects": "Overlapping timeline objects",
+    "timeline.resize-timeline-track-labels": "Resize timeline track labels",
+    "timeline.resize-track-labels": "Resize track labels",
+    "timeline.segment-name": "Segment {name}",
+    "timeline.segments": "Segments",
+    "timeline.select": "Select",
+    "timeline.selection-name": "Selection {name}",
+    "timeline.selections-and-moments": "Selections and Moments",
+    "timeline.words": "Words",
+    "timeline.zoom-in": "Zoom in",
+    "timeline.zoom-out": "Zoom out",
+    "inspector.color-picker": "{label} picker",
+    "timeline.segment-count": {
+      "one": "{count} segment",
+      "other": "{count} segments"
+    }
+  }
+}

package/packages/studio/locales/zh-CN.json

@@ -0,0 +1,191 @@
+{
+  "locale": "zh-CN",
+  "name": "简体中文",
+  "direction": "ltr",
+  "messages": {
+    "app.comments": "评论",
+    "app.language": "语言",
+    "app.studio": "工作台",
+    "app.studio-view": "工作区视图",
+    "comments.all": "全部",
+    "comments.caught-up": "评论都已处理",
+    "comments.delete-comment": "删除评论",
+    "comments.done": "已完成",
+    "comments.draw-soon": "批注 · 即将支持",
+    "comments.edit-comment": "编辑评论",
+    "comments.edit-comment-text": "编辑评论内容",
+    "comments.emoji-soon": "表情 · 即将支持",
+    "comments.empty": "留下第一条评论",
+    "comments.empty-hint": "暂停在想调整的画面，说说你的想法。",
+    "comments.filter-comments": "筛选评论",
+    "comments.filter-hint": "切换筛选，查看其他评论。",
+    "comments.go-to-this-frame": "跳转到这一帧",
+    "comments.loading-comments": "加载评论中…",
+    "comments.mark-complete": "标为已完成",
+    "comments.no-completed-comments": "暂无已完成评论",
+    "comments.open": "待处理",
+    "comments.placeholder": "想调整哪里？",
+    "comments.read-failed": "无法读取评论。",
+    "comments.refresh-comments": "刷新评论",
+    "comments.reopen-comment": "标为待处理",
+    "comments.save-failed": "无法保存评论。",
+    "comments.send-comment": "发送评论",
+    "comments.send-shortcut": "发送评论（Enter）",
+    "comments.use-current-frame": "使用当前帧",
+    "comments.write-a-comment": "写评论",
+    "common.cancel": "取消",
+    "common.cancelled": "已取消",
+    "common.compile-failed": "编译失败",
+    "common.completed": "已完成",
+    "common.copied": "已复制",
+    "common.failed": "失败",
+    "common.invalid-value": "无效的值",
+    "common.needs-attention": "需要处理",
+    "common.queued": "排队中",
+    "common.refresh": "刷新",
+    "common.running": "运行中",
+    "common.save": "保存",
+    "common.save-failed": "保存失败",
+    "common.saved": "已保存",
+    "common.saving": "保存中",
+    "common.waiting": "等待中",
+    "inspector.add-color": "添加颜色",
+    "inspector.add-item": "添加条目",
+    "inspector.anchor.program-end": "时间线终点{detail}",
+    "inspector.anchor.program-start": "时间线起点{detail}",
+    "inspector.anchor.segment-end": "段尾{detail}",
+    "inspector.anchor.segment-start": "段头{detail}",
+    "inspector.anchor.token-end": "词尾{detail}",
+    "inspector.anchor.token-start": "词头{detail}",
+    "inspector.aspect-ratio": "画幅比例",
+    "inspector.author": "源文件",
+    "inspector.build": "构建",
+    "inspector.candidates": "候选实现",
+    "inspector.canvas": "画布",
+    "inspector.duration": "时长",
+    "inspector.empty": "当前选中项没有详细信息",
+    "inspector.end": "终点",
+    "inspector.end-anchor": "终点语义锚点",
+    "inspector.frame-rate": "帧率",
+    "inspector.frames": "帧数",
+    "inspector.how": "样式",
+    "inspector.invalid-fields": "请正确填写必填项后保存。",
+    "inspector.item-count": "{count} 项",
+    "inspector.moment": "时刻",
+    "inspector.moment-anchor": "时刻语义锚点",
+    "inspector.move-down": "下移",
+    "inspector.move-up": "上移",
+    "inspector.project": "项目",
+    "inspector.properties": "属性",
+    "inspector.remove-item": "移除条目",
+    "inspector.resolution": "分辨率",
+    "inspector.run": "运行方案",
+    "inspector.semantic-anchors": "语义锚点",
+    "inspector.sources": "引用文件",
+    "inspector.start": "起点",
+    "inspector.start-anchor": "起点语义锚点",
+    "inspector.structured-value": "结构化值",
+    "inspector.targets": "目标产物",
+    "inspector.timeline": "时间线",
+    "inspector.timing": "时间",
+    "inspector.tracks": "轨道",
+    "inspector.use-color": "使用 {color}",
+    "inspector.when": "时间",
+    "inspector.where": "位置",
+    "library.all-media": "全部素材",
+    "library.all-tasks": "全部任务",
+    "library.artifacts": "产物",
+    "library.audio": "音频",
+    "library.clear-task-filter": "清除任务筛选",
+    "library.data": "数据",
+    "library.display-name": "显示名称",
+    "library.enter-name": "请输入名称。",
+    "library.finished": "已结束",
+    "library.image": "图片",
+    "library.images": "图片",
+    "library.in-progress": "进行中",
+    "library.loading-media": "加载素材中…",
+    "library.loading-more": "加载更多…",
+    "library.loading-tasks": "加载任务中…",
+    "library.media-categories": "素材分类",
+    "library.media-category": "素材分类",
+    "library.media-hint": "这里展示已产出的图片、视频和音频，也包括正在构建的任务产物。",
+    "library.name-failed": "无法保存名称",
+    "library.name-pending": "{name}\n构建完成后可以重命名",
+    "library.no-files-in-this-category": "此分类暂无素材",
+    "library.no-media": "暂无素材",
+    "library.no-tasks-here": "暂无任务",
+    "library.no-tasks-in-progress": "没有进行中的任务",
+    "library.preview-name": "预览 {name}",
+    "library.preview-unavailable": "暂时无法预览",
+    "library.referenced-source-files": "引用的源文件",
+    "library.refresh-failed": "刷新失败：{detail}",
+    "library.refresh-failed-retained": "刷新失败：{detail} · 已保留上次视图",
+    "library.refresh-interrupted": "刷新已中断",
+    "library.refresh-media": "刷新素材",
+    "library.refresh-tasks": "刷新任务",
+    "library.refreshing": "刷新中…",
+    "library.rename-hint": "{name}\n双击或按 F2 重命名",
+    "library.return-to-task": "返回任务",
+    "library.source": "源文件",
+    "library.studio-library": "项目资源",
+    "library.task-categories": "任务分类",
+    "library.task-return": "{name} · 返回任务",
+    "library.tasks": "任务",
+    "library.unavailable": "资源暂时不可用",
+    "library.updated": "更新于 {time}",
+    "library.video": "视频",
+    "library.video-loading-preview": "视频 · 加载预览中",
+    "library.videos": "视频",
+    "library.view-media": "查看产物",
+    "library.view-task-media": "查看任务产物",
+    "player.audio-waveform": "音频波形",
+    "player.back-5-seconds": "后退 5 秒",
+    "player.back-to-composition": "返回作品",
+    "player.composition-time": "作品播放进度",
+    "player.elements-at-this-point": "此处的元素",
+    "player.forward-5-seconds": "前进 5 秒",
+    "player.frame-loading": "加载画面中…",
+    "player.frame-unavailable": "画面暂时不可用",
+    "player.hovered-frame": "悬停画面",
+    "player.media-failed": "浏览器无法打开此素材。",
+    "player.media-time": "素材播放进度",
+    "player.mute": "静音",
+    "player.next-frame": "下一帧",
+    "player.pause": "暂停",
+    "player.play": "播放",
+    "player.preview": "预览",
+    "player.previous-frame": "上一帧",
+    "player.unmute": "取消静音",
+    "source.changed-outside-studio": "文件已在外部更改",
+    "source.edit-source": "编辑源文件",
+    "source.keep-lines-unwrapped": "不自动换行",
+    "source.read-source": "查看源文件",
+    "source.save-failed-status": "保存失败（{status}）",
+    "source.saving-before-switch": "切换前保存中",
+    "source.svml-source": "SVML 源文件",
+    "source.unsaved": "未保存",
+    "source.wrap-lines": "自动换行",
+    "tasks.copy-error": "复制错误信息",
+    "tasks.copy-manually": "请选择文字复制",
+    "tasks.no-runtime": "尚未选择运行环境，可在「已结束」中查看保存的任务。",
+    "tasks.progress": "已完成 {completed}/{total} 步",
+    "tasks.refresh-hint": "点击刷新，查看最新任务状态。",
+    "tasks.saved-only": "项目中保存的结果 · 未选择运行环境",
+    "timeline.fit-timeline": "适配时间线",
+    "timeline.moment-name": "时刻 {name}",
+    "timeline.overlapping-timeline-objects": "重叠的时间线对象",
+    "timeline.resize-timeline-track-labels": "调整轨道名称区宽度",
+    "timeline.resize-track-labels": "调整轨道名称区宽度",
+    "timeline.segment-name": "片段 {name}",
+    "timeline.segments": "片段",
+    "timeline.select": "选择",
+    "timeline.selection-name": "区间 {name}",
+    "timeline.selections-and-moments": "区间与时刻",
+    "timeline.words": "词语",
+    "timeline.zoom-in": "放大",
+    "timeline.zoom-out": "缩小",
+    "inspector.color-picker": "{label}取色器",
+    "timeline.segment-count": "{count} 个片段"
+  }
+}

package/packages/studio/package.json

@@ -12,34 +12,35 @@
     "@hypit/build-result": "workspace:*",
     "@hypit/caption-fine-studio": "workspace:*",
     "@hypit/cli": "workspace:*",
+    "@hypit/comment-sticker-studio": "workspace:*",
     "@hypit/compiler-node": "workspace:*",
     "@hypit/component-kit": "workspace:*",
     "@hypit/composition": "workspace:*",
-    "@hypit/comment-sticker-studio": "workspace:*",
     "@hypit/core": "workspace:*",
-    "@hypit/driver-node": "workspace:*",
     "@hypit/deck-track-studio": "workspace:*",
+    "@hypit/driver-node": "workspace:*",
     "@hypit/elaborator": "workspace:*",
     "@hypit/film-studio": "workspace:*",
     "@hypit/hyperframes": "workspace:*",
     "@hypit/markup": "workspace:*",
     "@hypit/media-track-studio": "workspace:*",
-    "@hypit/narrative": "workspace:*",
     "@hypit/package-loader-node": "workspace:*",
+    "@hypit/performance-studio": "workspace:*",
+    "@hypit/sound-studio": "workspace:*",
     "@hypit/program-space": "workspace:*",
+    "@hypit/project-context-node": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/ranking-studio": "workspace:*",
     "@hypit/run": "workspace:*",
     "@hypit/runtime": "workspace:*",
     "@hypit/runtime-host-node": "workspace:*",
-    "@hypit/script-studio": "workspace:*",
     "@hypit/screen-overlay-studio": "workspace:*",
+    "@hypit/script-studio": "workspace:*",
     "@hypit/speech": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/studio-adapter": "workspace:*",
     "@hypit/svs": "workspace:*",
     "@hypit/temporal": "workspace:*",
-    "@hypit/studio-adapter": "workspace:*",
-    "@hypit/speech-track-studio": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/typography-track-studio": "workspace:*",
     "@hypit/validation": "workspace:*",
     "@hypit/video-cli": "workspace:*",

package/packages/studio/src/companion-assembly.ts

@@ -34,6 +34,7 @@ export async function loadStudioCompanionRegistry(input: {
     {
       films: contributions.flatMap((item) => item.films),
       scripts: contributions.flatMap((item) => item.scripts),
+      parameters: contributions.flatMap((item) => item.parameters),
     },
   );
 }

package/packages/studio/src/domain.ts

@@ -33,7 +33,7 @@ export type StudioDomain = {
 
 /**
  * Assemble Studio from the same recursive package selection as the official CLI.
- * The application owns this video-domain view; packages never register Studio metadata.
+ * The application assembles the video-domain view; selected packages contribute Studio Companions through host facets.
  */
 export async function loadStudioDomain(input: {
   readonly run: string;

package/packages/studio/src/fallback-companions.ts

@@ -1,7 +1,7 @@
 import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-adapter";
 import { artifactPreview, previewLayer, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
 import { compositionTypes } from "@hypit/composition";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 
 type TerminalVisualTrack = {
   readonly presents?: readonly {
@@ -79,8 +79,8 @@ function projectTerminalAudio(context: StudioTrackCompanionContext): readonly St
 /** Cross-domain terminal protocols understood even when no Companion is installed. */
 export const fallbackStudioTrackCompanions: readonly StudioTrackCompanion[] = [
   {
-    id: "@hypit/studio#semantic-track", role: "semantic-track", output: { type: semanticTrackTypes.track },
-    family: "semantic", tone: "teal", label: "Semantic", icon: "brand",
+    id: "@hypit/studio#timeline", role: "timeline", output: { type: timelineTypes.track },
+    family: "semantic", tone: "teal", label: "Timeline", icon: "brand",
     lane: { heightPx: 45 },
   },
   {

package/packages/studio/src/feedback-server.ts

@@ -0,0 +1,51 @@
+import { watch } from "node:fs";
+import { relative } from "node:path";
+import type { Plugin } from "vite";
+import { createFeedbackStore, FeedbackConflict } from "./feedback-store.js";
+import { readFeedbackMutation } from "./feedback.js";
+import type { FeedbackDocument, FeedbackView } from "./feedback.js";
+
+/** Review storage is separate from compilation, Results and Agent delivery. */
+export function studioFeedbackPlugin(workspaceRoot: string, runPath: string): Plugin {
+  const store = createFeedbackStore(workspaceRoot);
+  const run = relative(workspaceRoot, runPath).replaceAll("\\", "/");
+  const view = (document: FeedbackDocument): FeedbackView => ({
+    file: "FEEDBACK.json", run, comments: document.comments.filter((comment) => comment.run === run),
+  });
+  return {
+    name: "hypit-studio-feedback",
+    configureServer(server) {
+      const watcher = watch(workspaceRoot, (_event, filename) => {
+        if (filename === null || filename.toString() === "FEEDBACK.json") {
+          server.ws.send({ type: "custom", event: "studio:feedback-changed", data: {} });
+        }
+      });
+      server.httpServer?.once("close", () => watcher.close());
+      server.middlewares.use((request, response, next) => {
+        if (new URL(request.url ?? "/", "http://studio.hypit.local").pathname !== "/__studio/feedback") return next();
+        response.setHeader("content-type", "application/json; charset=utf-8");
+        response.setHeader("cache-control", "no-store");
+        void (async () => {
+          try {
+            if (request.method === "GET") {
+              response.end(JSON.stringify(view(await store.read())));
+              return;
+            }
+            if (request.method !== "POST") { response.statusCode = 405; response.end(); return; }
+            const chunks: Buffer[] = [];
+            for await (const chunk of request) chunks.push(Buffer.from(chunk));
+            const mutation = readFeedbackMutation(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            const comment = mutation.type === "delete" ? mutation.before : mutation.comment;
+            if (comment.run !== run) throw new Error("The comment belongs to another Run.");
+            const result = view(await store.mutate(mutation));
+            response.end(JSON.stringify(result));
+            server.ws.send({ type: "custom", event: "studio:feedback-changed", data: {} });
+          } catch (error) {
+            response.statusCode = error instanceof FeedbackConflict ? 409 : 400;
+            response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+          }
+        })();
+      });
+    },
+  };
+}

package/packages/studio/src/feedback-store.ts

@@ -0,0 +1,66 @@
+import { isDeepStrictEqual } from "node:util";
+import { randomUUID } from "node:crypto";
+import { readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readFeedbackDocument } from "./feedback.js";
+import type { FeedbackDocument, FeedbackMutation } from "./feedback.js";
+
+export class FeedbackConflict extends Error {}
+
+/** The file is authoritative; every operation reads it afresh and edits one note. */
+export function createFeedbackStore(workspaceRoot: string) {
+  const path = join(workspaceRoot, "FEEDBACK.json");
+  let pending: Promise<unknown> = Promise.resolve();
+  const readText = async (): Promise<string | undefined> => {
+    try { return await readFile(path, "utf8"); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw error;
+    }
+  };
+  const decode = (text: string | undefined): FeedbackDocument => text === undefined
+    ? { comments: [] } : readFeedbackDocument(JSON.parse(text));
+
+  const apply = async (mutation: FeedbackMutation): Promise<FeedbackDocument> => {
+    const previous = await readText();
+    const document = decode(previous);
+    const comments = [...document.comments];
+    if (mutation.type === "add") {
+      if (comments.some((comment) => comment.id === mutation.comment.id)) throw new FeedbackConflict("This comment already exists.");
+      comments.push(mutation.comment);
+    } else {
+      const index = comments.findIndex((comment) => comment.id === mutation.before.id);
+      if (index < 0 || !isDeepStrictEqual(comments[index], mutation.before)) {
+        throw new FeedbackConflict("This comment changed outside this view. Your unsaved text is kept in the editor; reopen the comment to edit its latest version.");
+      }
+      if (mutation.type === "delete") comments.splice(index, 1);
+      else {
+        if (mutation.comment.id !== mutation.before.id || mutation.comment.run !== mutation.before.run) {
+          throw new Error("Editing a comment preserves its id and Run.");
+        }
+        comments[index] = mutation.comment;
+      }
+    }
+    const next = { ...document, comments };
+    const temporary = join(workspaceRoot, `.FEEDBACK.${randomUUID()}.tmp`);
+    try {
+      await writeFile(temporary, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+      if (await readText() !== previous) throw new FeedbackConflict("FEEDBACK.json changed while saving. Your draft is kept; please try again.");
+      await rename(temporary, path);
+    } finally {
+      await unlink(temporary).catch((error: NodeJS.ErrnoException) => { if (error.code !== "ENOENT") throw error; });
+    }
+    return next;
+  };
+
+  return {
+    path,
+    read: async (): Promise<FeedbackDocument> => decode(await readText()),
+    mutate(mutation: FeedbackMutation): Promise<FeedbackDocument> {
+      // Serialize browser submissions, without keeping a second copy of the document.
+      const result = pending.then(() => apply(mutation));
+      pending = result.catch(() => undefined);
+      return result;
+    },
+  };
+}

package/packages/studio/src/feedback.ts

@@ -0,0 +1,60 @@
+/** Project-owned review notes. Times are seconds in the reviewed Run. */
+export type FeedbackComment = {
+  readonly id: string;
+  readonly run: string;
+  readonly at: number;
+  readonly text: string;
+  readonly resolved?: boolean;
+};
+
+export type FeedbackDocument = { readonly comments: readonly FeedbackComment[] };
+export type FeedbackView = FeedbackDocument & { readonly file: string; readonly run: string };
+export type FeedbackMutation =
+  | { readonly type: "add"; readonly comment: FeedbackComment }
+  | { readonly type: "replace"; readonly before: FeedbackComment; readonly comment: FeedbackComment }
+  | { readonly type: "delete"; readonly before: FeedbackComment };
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonempty(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function time(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+export function readFeedbackComment(value: unknown): FeedbackComment {
+  if (!record(value) || !nonempty(value.id) || !nonempty(value.run) || !nonempty(value.text) || !time(value.at)) {
+    throw new Error("Each comment needs an id, run, non-empty text and a non-negative time in seconds.");
+  }
+  if (value.resolved !== undefined && typeof value.resolved !== "boolean") throw new Error("Comment resolved must be true or false.");
+  // Preserve any project-added fields when Studio edits this document.
+  return value as FeedbackComment;
+}
+
+export function readFeedbackDocument(value: unknown): FeedbackDocument {
+  if (!record(value) || !Array.isArray(value.comments)) throw new Error("FEEDBACK.json needs a comments array.");
+  const ids = new Set<string>();
+  for (const entry of value.comments) {
+    const comment = readFeedbackComment(entry);
+    if (ids.has(comment.id)) throw new Error(`Duplicate comment id: ${comment.id}`);
+    ids.add(comment.id);
+  }
+  return value as FeedbackDocument;
+}
+
+export function readFeedbackMutation(value: unknown): FeedbackMutation {
+  if (!record(value)) throw new Error("Expected a comment operation.");
+  if (value.type === "add") return { type: "add", comment: readFeedbackComment(value.comment) };
+  if (value.type === "delete") return { type: "delete", before: readFeedbackComment(value.before) };
+  if (value.type === "replace") return { type: "replace", before: readFeedbackComment(value.before), comment: readFeedbackComment(value.comment) };
+  throw new Error("Unknown comment operation.");
+}
+
+export function feedbackClock(seconds: number): string {
+  const ticks = Math.round(seconds * 100);
+  return `${String(Math.floor(ticks / 6000)).padStart(2, "0")}:${String(Math.floor(ticks / 100) % 60).padStart(2, "0")}.${String(ticks % 100).padStart(2, "0")}`;
+}