@mekuru/protocol 0.1.3 → 0.1.4

package/README.jp.md

@@ -1,3 +1,13 @@
 # @mekuru/protocol
 
-コンパイラ出力とサーバー状態を共有するTypeScript型です。実行時依存はありません。cliとviewerがこの通信契約を参照します。
+コンパイラ出力とサーバー状態を共有するTypeScript型です。実行時依存はありません。compilerパッケージとviewerがこの通信契約を参照します。
+
+`TimelineCompilation` は整数フレーム区間、有理数 `FrameRate`、台本ID、反復情報を表します。プレビューの同期には `PreviewEvent` の `snapshot`・`status`・`patch` を使います。
+
+単発・常駐プレビューの文字は内容・配置・スタイルを持つ `TextOp` で、viewer が HTML/CSS で描画します。`fontSrc` と `fontRevision` はプロジェクト内のフォントを識別します。画像・動画・音声もリビジョンを持ちます。動画書き出しには従来の Rust 組版・パス描画を使います。コンパイラと埋め込み viewer は同時に更新してください。
+
+ワーカー要求は `knownResources` の列挙から `baseVersion` の受理通知へ変わりました。応答は `previewVersion` と `update`（snapshot・patch・null）、Rust の差分生成時間 `stats.diffMs` を持ちます。`previewVersion: null` はコンパイル失敗、成功してシーンが同じなら受理済みの版を維持し更新を送りません。ワーカーは受理済みシーンと候補1件を保持し、破棄した応答を差分の基準にしません。再起動・不明な基準では snapshot を返します。以前の全体シーン応答を置き換えるためコンパイラと外部ツール を同時更新してください。ブラウザの `PreviewEvent` と単発の `Compilation` は維持します。
+
+ネイティブの `--serve` は同一プロセス内でコンパイルし、`PreviewEvent` を直接 WebSocket 配信します。ビューアはコンパイラへ埋め込んで同時に配布します。JSON Lines のワーカー型は外部ツール・計測用です。
+
+`/api/ws` の WebSocket で、1メッセージにつき1件の `PreviewEvent` JSON テキストを送ります。基準バージョンが合わない場合、viewer は `PreviewCommand` の `{"type":"resync"}` を送り、同じ接続で snapshot を再取得します。切断・再同期のタイムアウト時は再接続します。旧 `/api/events` SSE エンドポイントは廃止し、コンパイラと埋め込みビューアを同時更新してください。

package/README.md

@@ -2,4 +2,16 @@
 
 Preview transport types.
 
-Shared TypeScript types for compiler output and server state. This package has no runtime dependencies. CLI and viewer both depend on this contract.
+Shared TypeScript types for compiler output and server state. This package has no runtime dependencies. The browser viewer and authoring adapters depend on this contract; the native server implements it in Rust.
+
+`Compilation` describes the standalone `--emit-preview` output. `WorkerRequest` and `WorkerCompilation` describe the resident compiler's JSON Lines exchange. Shared elements reference ordered SHA-256 drawing IDs, one per original `ViewOp`; preview keys identify elements independently of their drawing content and sequential compiler IDs.
+
+`PreviewEvent` is sent as one JSON text message per WebSocket message at `/api/ws`: `snapshot` supplies the current scene and resources, `status` supplies only server state, and `patch` supplies a base/next version, keyed collection edits, ordering and resource changes. The viewer sends `PreviewCommand` (`{"type":"resync"}`) to request a snapshot on the same connection if a patch's base version does not match. A lost connection or three-second resync timeout reconnects the viewer. The old `/api/events` SSE endpoint is removed. The viewer is embedded in the compiler, so they ship together.
+
+`TimelineCompilation` exposes integer frame intervals, rational `FrameRate`, source IDs, and compact repeat chains. Preview synchronization uses the `snapshot`, `status`, and `patch` variants of `PreviewEvent`.
+
+Text is a `TextOp` (content, layout and style) in both standalone and worker previews. The viewer renders it as HTML/CSS. `fontSrc` and `fontRevision` identify project fonts; images and media carry their own revision. Export still uses Rust text shaping and path rendering.
+
+Worker requests now acknowledge `baseVersion` instead of listing `knownResources`. Responses carry `previewVersion` and `update` (snapshot, patch, or null), with `stats.diffMs` measuring Rust diff generation. `previewVersion: null` means compilation failure; a successful unchanged scene keeps the acknowledged version and sends no update. The worker retains an acknowledged scene plus one candidate, so discarded responses never become a patch base. Restarting or receiving an unknown base forces a snapshot. This replaces the previous full-scene worker response; update tool clients together with the compiler. Browser `PreviewEvent` and standalone `Compilation` are unchanged.
+
+The native `--serve` path calls the compiler in process and sends `PreviewEvent` directly over WebSocket. JSON Lines worker types remain for external tools and benchmarks.

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "@mekuru/protocol",
-  "version": "0.1.3",
+  "version": "0.1.4",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kanade-k-1228/mekuru.git",
+    "directory": "pkgs/protocol"
+  },
+  "homepage": "https://github.com/kanade-k-1228/mekuru/blob/main/pkgs/protocol/README.md",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/index.ts

@@ -8,6 +8,7 @@ export interface Compilation {
   preview: PreviewDto | null;
   diagnostics: Diagnostic[];
 }
+/** Compilation status; it never contains drawing data. */
 export interface StateDto {
   path: string;
   version: number;
@@ -15,9 +16,65 @@ export interface StateDto {
   status: "building" | "ready" | "error";
   error: string | null;
   diagnostics: Diagnostic[];
-  preview: PreviewDto | null;
 }
 
+export type Keyed<T> = T & { key: string };
+export interface SharedPreviewDto extends Omit<PreviewDto, "elements" | "timeline"> {
+  version: number;
+  elements: SharedElement[];
+  timeline: { nodes: Keyed<TimelineNode>[]; clips: Keyed<TimelineClip>[] };
+}
+export interface SharedElement extends Omit<SceneElement, "ops" | "chunks"> {
+  key: string;
+  drawings: string[];
+}
+export type Resources = Record<string, DrawOp[]>;
+export interface WorkerRequest {
+  version: number;
+  xml: string;
+  /** Last scene accepted by the CLI, never an intermediate discarded result. */
+  baseVersion: number | null;
+}
+export interface WorkerCompilation {
+  version: number;
+  /** null on compilation failure; unchanged scenes retain the acknowledged version. */
+  previewVersion: number | null;
+  diagnostics: Diagnostic[];
+  update: PreviewUpdate | null;
+  stats: { drawHits: number; drawMisses: number; compileMs: number; diffMs: number };
+}
+export type PreviewUpdate = Omit<SnapshotEvent, "state"> | Omit<PatchEvent, "state">;
+export interface CollectionPatch<T> {
+  upsert: T[];
+  remove: string[];
+  order?: string[];
+}
+export interface SnapshotEvent {
+  type: "snapshot";
+  state: StateDto;
+  preview: SharedPreviewDto | null;
+  resources: Resources;
+}
+export interface StatusEvent {
+  type: "status";
+  state: StateDto;
+}
+export interface PatchEvent {
+  type: "patch";
+  state: StateDto;
+  baseVersion: number;
+  version: number;
+  scene: Pick<PreviewDto, "width" | "height" | "fps" | "duration">;
+  elements: CollectionPatch<SharedElement>;
+  nodes: CollectionPatch<Keyed<TimelineNode>>;
+  clips: CollectionPatch<Keyed<TimelineClip>>;
+  resources: Resources;
+  removedResources: string[];
+}
+export type PreviewEvent = SnapshotEvent | StatusEvent | PatchEvent;
+/** Browser-to-server JSON message over /api/ws. */
+export type PreviewCommand = { type: "resync" };
+
 export interface PreviewDto {
   width: number;
   height: number;
@@ -28,20 +85,41 @@ export interface PreviewDto {
 }
 export type Bounds = [number, number, number, number];
 export type Fade = [start: number, end: number, fadeIn: number, fadeOut: number, level: number];
+export interface TextOp {
+  kind: "text";
+  text: string;
+  x: number;
+  y: number;
+  width: number | null;
+  font: string;
+  fontSrc: string | null;
+  fontRevision: string | null;
+  size: number;
+  color: string;
+  bold: boolean;
+  align: "left" | "center" | "right";
+  lineHeight: number;
+  stroke: string | null;
+  strokeWidth: number;
+  transform: [number, number, number, number, number, number] | null;
+}
 export type DrawOp =
+  | TextOp
   | {
       kind: "path";
       d: string;
       color: string;
       stroke: { width: number; lineCap: "butt" | "round" | "square"; lineJoin: "miter" | "round" | "bevel"; dash: number[] } | null;
     }
-  | { kind: "image"; src: string; bounds: Bounds; transform: [number, number, number, number, number, number] | null };
+  | { kind: "image"; src: string; revision?: string; bounds: Bounds; transform: [number, number, number, number, number, number] | null };
 export interface MediaMap {
   from: number;
   end: number;
   segments: [outStart: number, outEnd: number, srcStart: number, rate: number][];
 }
 export interface SceneElement {
+  key?: string;
+  chunks?: { id: string; ops: DrawOp[] }[];
   id: number;
   kind: "view" | "video" | "audio";
   start: number;
@@ -50,12 +128,13 @@ export interface SceneElement {
   fades: Fade[];
   ops: DrawOp[];
   bounds: Bounds | null;
-  media: { src: string; gain: number; map: MediaMap } | null;
+  media: { src: string; revision?: string; gain: number; map: MediaMap } | null;
   repeat: [from: number, period: number, until: number][];
   hidden: [start: number, end: number][];
 }
 
 export interface TimelineNode {
+  key?: string;
   id: number;
   parent: number | null;
   depth: number;
@@ -71,6 +150,7 @@ export interface TimelineNode {
 export type ClipLane = "speech" | "visual" | "video" | "audio";
 
 export interface TimelineClip {
+  key?: string;
   tag: string;
   lane: ClipLane;
   line: number;
@@ -85,3 +165,29 @@ export interface TimelineDto {
   nodes: TimelineNode[];
   clips: TimelineClip[];
 }
+
+export interface FrameRate {
+  num: number;
+  den: number;
+}
+export interface FrameInterval {
+  startFrame: number;
+  endFrame: number;
+}
+export interface TimelineEntry extends FrameInterval {
+  id: string;
+  parent: string | null;
+  sourceId: string | null;
+  kind: "seq" | "par" | "repeat" | "view" | "video" | "audio";
+  repeat: { fromFrame: number; periodFrames: number; untilFrame: number }[];
+}
+export interface ResolvedTimeline {
+  fps: FrameRate;
+  frames: number;
+  estimated: boolean;
+  entries: TimelineEntry[];
+}
+export interface TimelineCompilation {
+  timeline: ResolvedTimeline | null;
+  diagnostics: Diagnostic[];
+}