@mengine/medeo-tool 1.4.1-alpha.1 → 1.4.1-alpha.3

package/dist/index.mjs

@@ -1,7 +1,141 @@
-import { a as createEntityId, c as collectAffectedPartIds, i as businessState, l as renderPreview, n as EntitySandbox, o as createRelationId, s as isMediaAssetVariantKind, t as EditSandboxSession, u as renderCompactProjection } from "./script-session-AukLN7x7.mjs";
-import { LoroEntityDocument, ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, base64ToBytes, bytesToBase64, compileEntityRows, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, encodeDocVersionMark, ensureEditorFoundation, replayJournal, toVideoDocument } from "@mengine/medeo-client";
+import { a as createEntityId, i as businessState, o as createRelationId, s as isMediaAssetVariantKind, t as EntitySandbox } from "./entity-sandbox-BH-7F5C8.mjs";
+import { LoroEntityDocument, ManualSyncDoc, MengineHttpClient, MengineHttpRequestError, ValidationError, base64ToBytes, bytesToBase64, compileEntityRows, createMirrorVideoDocument, createPlainMemoryAdapter, decodeDocVersionMark, effectiveVideoClipDurationMs, encodeDocVersionMark, ensureEditorFoundation, replayJournal, solveVideoDocument, speedOf, toVideoDocument } from "@mengine/medeo-client";
 import { Worker } from "node:worker_threads";
 import { createHash, randomUUID } from "node:crypto";
+//#region src/document/compact-projection.ts
+const DEFAULT_TEXT_PREVIEW_LENGTH = 24;
+/** Kind tag shown in the first column (`video_clip` → `clip`). */
+function kindTag(kind) {
+	return kind === "video_clip" ? "clip" : kind;
+}
+/** Lane label: `video_clip` tracks display as `main`, otherwise `parts_kind`. */
+function laneLabel(partsKind) {
+	return partsKind === "video_clip" ? "main" : partsKind;
+}
+/** Speed token: absent → `1`; linear → numeric multiplier; anything else → `custom`. */
+function speedToken(speedShift) {
+	if (speedShift == null) return "1";
+	if (speedShift.category === "linear") return String(speedOf(speedShift));
+	return "custom";
+}
+function effectiveDurationMs(part, timelineDurationMs) {
+	if (part.video_clip != null) return effectiveVideoClipDurationMs(part.video_clip);
+	if (part.speech != null) return part.speech.media_duration_ms ?? 0;
+	if (part.caption != null) return part.caption.initial_duration_ms ?? 0;
+	if (part.bgm != null) return timelineDurationMs;
+	return 0;
+}
+function truncateText(text, budget) {
+	if (text.length <= budget) return text;
+	return `${text.slice(0, budget)}…`;
+}
+function anchorToken(timePosition) {
+	if (timePosition.mode === "anchored") return `anchor=${timePosition.anchorPartId}+${timePosition.offsetMs}`;
+	if (timePosition.mode === "absolute") return "anchor=abs";
+	return "anchor=abs";
+}
+function clipAttrs(clip) {
+	const playIn = clip.play_in ?? 0;
+	const playOut = clip.play_out ?? 0;
+	return `media=${clip.origin_media_id ?? ""} trim=${playIn}-${playOut} speed=${speedToken(clip.speed_shift)} vol=${clip.volume ?? 0}`;
+}
+function partAttrs(part, item, textPreviewLength) {
+	if (part.video_clip != null) return clipAttrs(part.video_clip);
+	if (part.speech != null) return `${anchorToken(item.time_position)} dur=${part.speech.media_duration_ms ?? 0}`;
+	if (part.caption != null) {
+		const preview = truncateText(part.caption.text ?? "", textPreviewLength);
+		return `${anchorToken(item.time_position)} text="${preview}"`;
+	}
+	if (part.bgm != null) return `vol=${part.bgm.volume ?? 0}`;
+	return "";
+}
+/**
+* Render a `VideoDocument` as compact text: one header line plus one row per
+* timeline part (optionally filtered by `onlyPartIds`). Deterministic and
+* side-effect free — same document always yields the same string.
+*/
+function renderCompactProjection(document, options) {
+	const onlyPartIds = options?.onlyPartIds;
+	const textPreviewLength = options?.textPreviewLength ?? DEFAULT_TEXT_PREVIEW_LENGTH;
+	const solved = solveVideoDocument(document);
+	const library = document.part_library ?? {};
+	const tracks = document.tracks ?? [];
+	let totalParts = 0;
+	const rows = [];
+	for (const track of tracks) {
+		const partsKind = track.parts_kind;
+		if (partsKind == null) continue;
+		const lane = laneLabel(partsKind);
+		const tag = kindTag(partsKind);
+		for (const item of track.items ?? []) {
+			totalParts += 1;
+			const partId = item.part_id;
+			if (onlyPartIds != null && !onlyPartIds.has(partId)) continue;
+			const part = library[partId];
+			if (part == null) continue;
+			const abs = solved.absByPartId.get(partId) ?? 0;
+			const dur = effectiveDurationMs(part, solved.durationMs);
+			const attrs = partAttrs(part, item, textPreviewLength);
+			rows.push(`${tag} ${partId} ${lane} [${abs},${abs + dur}) ${attrs}`);
+		}
+	}
+	return [`# draft=${document.meta.draft_id ?? ""} v=${document.meta.version ?? 0} duration=${solved.durationMs} parts=${totalParts} shown=${rows.length}`, ...rows].join("\n");
+}
+//#endregion
+//#region src/sandbox/preview.ts
+/**
+* Collect part ids referenced by a journal for compact preview filtering.
+* Walks known id-shaped payload keys (宁多勿少) and unions `generated_ids`.
+*/
+const PART_ID_KEYS = new Set([
+	"clip_id",
+	"clip_ids",
+	"before_clip_id",
+	"after_clip_id",
+	"speech_id",
+	"speech_ids",
+	"speech_part_id",
+	"caption_id",
+	"caption_ids",
+	"bgm_id",
+	"anchor_part_id",
+	"part_id",
+	"body_part_id"
+]);
+/** Extract every part id a journal entry touches (payload refs + minted ids). */
+function collectAffectedPartIds(journal) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const entry of journal) {
+		for (const generated of entry.generated_ids ?? []) if (generated.length > 0) ids.add(generated);
+		collectFromValue(entry.payload, ids);
+	}
+	return ids;
+}
+function collectFromValue(value, ids) {
+	if (value == null) return;
+	if (Array.isArray(value)) {
+		for (const item of value) collectFromValue(item, ids);
+		return;
+	}
+	if (typeof value !== "object") return;
+	for (const [key, child] of Object.entries(value)) {
+		if (PART_ID_KEYS.has(key)) {
+			if (typeof child === "string" && child.length > 0) ids.add(child);
+			else if (Array.isArray(child)) {
+				for (const item of child) if (typeof item === "string" && item.length > 0) ids.add(item);
+			}
+		}
+		collectFromValue(child, ids);
+	}
+}
+/**
+* Render a ChangePlan preview: header + rows for journal-affected parts only.
+* Empty journal → empty `onlyPartIds` (header alone), matching the T2 contract.
+*/
+function renderPreview(document, journal) {
+	return renderCompactProjection(document, { onlyPartIds: journal.length === 0 ? /* @__PURE__ */ new Set() : collectAffectedPartIds(journal) });
+}
+//#endregion
 //#region src/sandbox/node-host.ts
 const DEFAULT_TIMEOUT_MS = 2e3;
 const DEFAULT_MEMORY_MB = 256;
@@ -35,8 +169,7 @@ function runEditScript(options) {
 				script: options.script,
 				inputs: options.inputs,
 				entityState: options.entityState,
-				idLabel: options.idLabel,
-				entityOnly: options.entityOnly
+				idLabel: options.idLabel
 			},
 			execArgv: resolveRegisterUrl.pathname.endsWith(".ts") ? [
 				"--experimental-transform-types",
@@ -81,6 +214,26 @@ function runEditScript(options) {
 				armTimeout();
 				return;
 			}
+			if (message.t === "entity-asset") {
+				(async () => {
+					try {
+						if (!options.loadEntityAsset) throw new Error("Entity Asset loader is unavailable");
+						const result = await options.loadEntityAsset(message.entity);
+						if (!settled) worker.postMessage({
+							t: "entity-asset-result",
+							requestId: message.requestId,
+							result
+						});
+					} catch (error) {
+						if (!settled) worker.postMessage({
+							t: "entity-asset-result",
+							requestId: message.requestId,
+							error: error instanceof Error ? error.message : String(error)
+						});
+					}
+				})();
+				return;
+			}
 			if (message.t === "entry") {
 				ops.push(message.entry);
 				return;
@@ -604,12 +757,10 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  sampling: 'native';",
 	"  coordinateSpace: JsonValue;",
 	"}",
-	"/** Business editing surface. Infrastructure Assets are assembled by the host. */",
+	"/** Business editing surface. Reads are assembled snapshots; writes preserve native operation intent. */",
 	"export interface BusinessEntityFacade {",
 	"  list(): SandboxEntity[];",
 	"  get(entityId: string): SandboxEntity | null;",
-	"  readCaptionContent(entityId: string): ComposedScriptContent;",
-	"  readPhoneticScriptContent(entityId: string): ComposedPhoneticContent;",
 	"  create(",
 	"    input: Exclude<",
 	"      CreateEntityInput,",
@@ -618,66 +769,18 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"      }",
 	"    >,",
 	"  ): string;",
-	"  update(input: UpdateEntityInput): void;",
+	"  update(input: EntityUpdateInput): void;",
 	"  declareFields(input: UpdateEntityInput): void;",
 	"  delete(input: DeleteEntityInput): void;",
 	"}",
-	"/** Physical Asset bindings are maintained outside the sandbox. */",
+	"/** Endpoint order is retained; each relation kind defines its endpoint semantics. */",
 	"export interface BusinessRelationFacade {",
 	"  list(): SandboxRelation[];",
 	"  of(entityId: string, relationKind?: KnownRelationKind): SandboxRelation[];",
-	"  link(",
-	"    input: Exclude<",
-	"      LinkRelationInput,",
-	"      {",
-	"        relation_kind: 'physical-asset';",
-	"      }",
-	"    >,",
-	"  ): string;",
-	"  linkGenerated(input: LinkGeneratedRelationInput): string;",
-	"  linkClipAnchor(input: LinkClipAnchorRelationInput): string;",
-	"  linkPhoneticScriptRender(input: LinkPhoneticScriptRenderRelationInput): string;",
-	"  linkAudioScriptSource(input: LinkAudioScriptSourceRelationInput): string;",
+	"  link(input: LinkRelationInput): string;",
+	"  update(input: RelationUpdateInput): void;",
 	"  unlink(input: UnlinkRelationInput): void;",
 	"}",
-	"export interface CaptionFontDescriptor {",
-	"  readonly system: 'font-library';",
-	"  readonly key: string;",
-	"}",
-	"/**",
-	" * One ordered entry of the Caption's segment selection. `segmentId` quotes the",
-	" * composed AudioScript's own stable segment identity — a local id quoted by the",
-	" * variant, never a peer Entity reference. Text itself is never copied here;",
-	" * complete Caption content is assembled through its direct baseEntityIds.",
-	" * The optional `textRange` narrows one Segment to an intra-Segment sub-span",
-	" * (intra-segment re-segmentation); without it the whole Segment text is selected.",
-	" */",
-	"export type CaptionSegmentSelection = JsonObject & {",
-	"  readonly segmentId: string;",
-	"  readonly textRange?: CaptionTextRange;",
-	"};",
-	"export interface CaptionStyleFields {",
-	"  readonly font?: CaptionFontDescriptor;",
-	"  readonly fontSize?: number;",
-	"  readonly fontColor?: string;",
-	"  readonly fontWeight?: number;",
-	"  readonly entranceAnimation?: string;",
-	"  readonly entranceAnimationDurationMs?: number;",
-	"  readonly strokeColor?: string;",
-	"  readonly strokeWidth?: number;",
-	"  readonly positionX?: number;",
-	"  readonly positionY?: number;",
-	"}",
-	"/**",
-	" * Half-open `[start, end)` position window inside one Segment's text, counted",
-	" * in Unicode code points (not UTF-16 code units), so a boundary never splits a",
-	" * surrogate pair. Positions are non-negative safe integers with `start < end`;",
-	" * `end` must not exceed the Segment's code-point length.",
-	" */",
-	"export interface CaptionTextRange extends JsonObject {",
-	"  readonly start: number;",
-	"  readonly end: number;",
-	"}",
 	"export type CaptionTextSelection = JsonObject & {",
 	"  segmentId: string;",
 	"  /** Half-open Unicode code-point range within the selected source segment. */",
@@ -686,31 +789,6 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"    end: number;",
 	"  };",
 	"};",
-	"export type ClipEntityId = EntityId;",
-	"export type ClipPlacement =",
-	"  | {",
-	"      readonly kind: 'sequential';",
-	"      readonly order: number;",
-	"    }",
-	"  | {",
-	"      readonly kind: 'absolute';",
-	"      readonly targetRange: SequenceRange<number>;",
-	"    }",
-	"  | {",
-	"      readonly kind: 'anchored';",
-	"      readonly hostClipEntityId: string;",
-	"      readonly anchorOffset: number;",
-	"    };",
-	"export interface ComposedPhoneticContent extends ComposedScriptContent {",
-	"  phonemeScript?: string;",
-	"  prosody?: JsonObject;",
-	"}",
-	"/** Read result only: base text is assembled from the real AudioScript row. */",
-	"export interface ComposedScriptContent {",
-	"  audio_script_entity_id: string;",
-	"  text: string;",
-	"  segments: ScriptTextSegment[];",
-	"}",
 	"export type CreateEntityInput = {",
 	"  [K in KnownEntityKind]: {",
 	"    entity_id?: string;",
@@ -718,31 +796,14 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"    payload: StoredEntityPayload<K>;",
 	"  };",
 	"}[KnownEntityKind];",
-	"export interface DeleteBgmInput {",
-	"  readonly timelineEntityId: string;",
-	"}",
-	"export interface DeleteClipInput {",
-	"  readonly clipEntityId: string;",
-	"}",
-	"export interface DeleteClipTreeInput {",
-	"  readonly clipEntityIds: readonly string[];",
-	"  readonly onAnchored: 'cascade' | 'detach';",
-	"}",
 	"export interface DeleteEntityInput {",
 	"  entity_id: string;",
 	"}",
-	"export interface DeleteVoiceoverInput {",
-	"  readonly voiceoverClipEntityIds: readonly string[];",
+	"/** Immutable resource content resolved by the host for a document Entity. */",
+	"export interface EntityAssetContent {",
+	"  assetId: string;",
+	"  content: JsonValue;",
 	"}",
-	"export type EmptyRelationKind =",
-	"  | 'timeline-track'",
-	"  | 'track-clip'",
-	"  | 'clip-marker'",
-	"  | 'marker-content'",
-	"  | 'axvideo-marker'",
-	"  | 'marker-timeline'",
-	"  | 'audio-script-marker';",
-	"export type EntityId = string;",
 	"export interface EntityPayloadByKind {",
 	"  axvideo: BoundedDerivedSequencePayload;",
 	"  timeline: JsonObject;",
@@ -751,10 +812,10 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"    role?: string;",
 	"  };",
 	"  clip: JsonObject;",
-	"  video: BoundedNativeSequencePayload;",
-	"  audio: BoundedNativeSequencePayload;",
-	"  voice: BoundedNativeSequencePayload;",
-	"  image: UnboundedConstantSequencePayload;",
+	"  video: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  audio: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  voice: BoundedNativeSequencePayload & MediaAssetPayload;",
+	"  image: UnboundedConstantSequencePayload & MediaAssetPayload;",
 	"  'sequence-marker': JsonObject & {",
 	"    sourceRange: {",
 	"      start: number;",
@@ -795,51 +856,62 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"    baseEntityIds: string[];",
 	"    selections: CaptionTextSelection[];",
 	"    style?: JsonObject;",
+	"    segmentRanges?: {",
+	"      segmentId: string;",
+	"      startMs: number;",
+	"      endMs: number;",
+	"    }[];",
 	"  };",
 	"}",
-	"export interface EntityStoreSnapshot {",
-	"  /** Causal compiler baseline; required for publishing edits. */",
-	"  loroSnapshot?: string;",
-	"  revision: number;",
-	"  /** Current AudioScript version attached to the project; initialized projects always attach a script, possibly empty. */",
-	"  audioScriptEntityId: string | null;",
-	"  entities: SandboxEntity[];",
-	"  relations: SandboxRelation[];",
-	"}",
-	"export interface InsertCaptionClipInput {",
-	"  readonly timelineEntityId: string;",
-	"  /** Existing generation identity for newly materialized Caption content, distinct from its Clip. */",
-	"  readonly captionEntityId?: string;",
-	"  /** Stable placed caption identity, distinct from the Caption content identity. */",
-	"  readonly captionClipEntityId?: string;",
-	"  /** Existing bases composed by this variant; includes an AudioScript text owner. */",
-	"  readonly baseEntityIds: readonly string[];",
-	"  /** Ordered selection of the AudioScript segments this Caption displays. */",
-	"  readonly selections: readonly CaptionSegmentSelection[];",
-	"  /** Intrinsic cue length of the Caption entity itself; display comes from the placement. */",
-	"  readonly durationMs: number;",
-	"  readonly style?: CaptionStyleFields;",
-	"  readonly placement: ClipPlacement;",
-	"}",
-	"export interface InsertClipInput {",
-	"  readonly trackEntityId: string;",
-	"  /** Existing Sequence media Entity id. Asset ids and URLs are not content ids. */",
-	"  readonly contentEntityId: string;",
-	"  readonly sourceRange: SequenceRange<number>;",
-	"  readonly duration: SequenceDuration<number>;",
-	"  readonly targetRange?: SequenceRange<number>;",
-	"  readonly clipPayload?: JsonObject;",
+	"/** Tokens have no script-authored data; only the creating session can validate them. */",
+	"export interface EntitySandboxCheckpoint {",
+	"  readonly __checkpoint: unique symbol;",
 	"}",
-	"export interface InsertPlacedClipInput {",
-	"  readonly trackEntityId: string;",
-	"  readonly contentEntityId: string;",
-	"  readonly sourceRange: SequenceRange<number>;",
-	"  readonly duration: SequenceDuration<number>;",
-	"  readonly placement: ClipPlacement;",
-	"  readonly clipPayload?: JsonObject;",
-	"  /** Stable caller-owned placement identity, when one already exists outside the graph. */",
-	"  readonly clipEntityId?: string;",
+	"export interface EntityUpdateInput {",
+	"  entity_id: string;",
+	"  changes: FieldChange[];",
 	"}",
+	"export type FieldChange =",
+	"  | {",
+	"      op: 'set';",
+	"      path: FieldPath;",
+	"      value: JsonValue;",
+	"    }",
+	"  | {",
+	"      op: 'unset';",
+	"      path: FieldPath;",
+	"    }",
+	"  | {",
+	"      op: 'text.splice';",
+	"      path: FieldPath;",
+	"      index: number;",
+	"      deleteCount: number;",
+	"      text: string;",
+	"    }",
+	"  | {",
+	"      op: 'list.insert';",
+	"      path: FieldPath;",
+	"      value: JsonValue;",
+	"      beforeElementId: string | null;",
+	"    }",
+	"  | {",
+	"      op: 'list.move';",
+	"      path: FieldPath;",
+	"      elementId: string;",
+	"      beforeElementId: string | null;",
+	"    }",
+	"  | {",
+	"      op: 'list.remove';",
+	"      path: FieldPath;",
+	"      elementId: string;",
+	"    };",
+	"/** List members are addressed by identity, never a transient array offset. */",
+	"export type FieldPath = readonly (",
+	"  | string",
+	"  | {",
+	"      elementId: string;",
+	"    }",
+	")[];",
 	"export interface JsonObject {",
 	"  [key: string]: JsonValue;",
 	"}",
@@ -872,93 +944,25 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  | 'phonetic-script-render'",
 	"  | 'audio-script-source'",
 	"  | 'audio-script-marker';",
-	"export interface LinearClipSpeed {",
-	"  readonly kind: 'linear';",
-	"  readonly rate: number;",
-	"  readonly mode?: string;",
-	"}",
-	"/** `audio-script-source(script, source)`; the script was transcribed from the source media. */",
-	"export interface LinkAudioScriptSourceRelationInput {",
-	"  relation_id?: string;",
-	"  script_entity_id: string;",
-	"  source_entity_id: string;",
-	"  trace?: JsonObject;",
-	"}",
-	"export interface LinkClipAnchorRelationInput {",
-	"  relation_id?: string;",
-	"  child_clip_entity_id: string;",
-	"  host_clip_entity_id: string;",
-	"  trace?: JsonObject;",
-	"}",
-	"export interface LinkGeneratedRelationInput {",
-	"  relation_id?: string;",
-	"  output_entity_id: string;",
-	"  input_entity_id: string;",
-	"  trace?: JsonObject;",
-	"}",
-	"export interface LinkPhoneticScriptRenderRelationInput {",
-	"  relation_id?: string;",
-	"  output_entity_id: string;",
-	"  phonetic_script_entity_id: string;",
-	"  trace?: JsonObject;",
-	"}",
 	"interface LinkRelationBase {",
 	"  relation_id?: string;",
 	"  endpoint_0_entity_id: string;",
 	"  endpoint_1_entity_id: string;",
 	"  trace?: JsonObject;",
 	"}",
-	"export type LinkRelationInput =",
-	"  | (LinkRelationBase & {",
-	"      relation_kind: EmptyRelationKind;",
-	"      metadata?: {",
-	"        [key: string]: never;",
-	"      };",
-	"    })",
-	"  | (LinkRelationBase & {",
-	"      relation_kind: 'physical-asset';",
-	"      metadata?: JsonObject;",
-	"    })",
-	"  | (LinkRelationBase & {",
-	"      relation_kind: 'caption-alignment';",
-	"      metadata: JsonObject & {",
-	"        alignment: JsonValue;",
-	"      };",
-	"    });",
-	"export interface MoveClipInput {",
-	"  readonly clipEntityId: string;",
-	"  readonly trackEntityId: string;",
-	"}",
-	"export interface MoveClipsToStartsInput {",
-	"  readonly moves: readonly {",
-	"    readonly clipEntityId: string;",
-	"    readonly newStartMs: number;",
-	"  }[];",
-	"  /** Absolute-time drags preserve every voiceover's current visible landing. */",
-	"  readonly onAnchored: 'keepAbsolute';",
-	"}",
-	"export interface MoveSequentialClipsInput {",
-	"  readonly clipEntityIds: readonly string[];",
-	"  readonly anchor: SequentialClipAnchor;",
-	"  readonly onAnchored: 'follow' | 'keepAbsolute';",
-	"}",
-	"export interface MoveVoiceoverInput {",
-	"  readonly voiceoverClipEntityId: string;",
-	"  /** Absolute requested timeline start; MEngine resolves and persists the host relation. */",
-	"  readonly newStartMs: number;",
-	"}",
-	"export interface PatchCaptionStyleInput {",
-	"  readonly timelineEntityId: string;",
-	"  readonly style: CaptionStyleFields;",
+	"export interface LinkRelationInput extends LinkRelationBase {",
+	"  relation_kind: KnownRelationKind;",
+	"  metadata?: JsonObject;",
 	"}",
-	"export interface ReplaceClipContentInput {",
-	"  readonly clipEntityId: string;",
-	"  /** Existing Sequence media Entity id. Asset ids and URLs are not content ids. */",
-	"  readonly contentEntityId: string;",
-	"  readonly sourceRange: SequenceRange<number>;",
-	"  readonly duration: SequenceDuration<number>;",
-	"  readonly targetRange?: SequenceRange<number>;",
-	"  readonly timeRemapping?: JsonValue;",
+	"export type MediaAssetPayload = JsonObject & {",
+	"  external: {",
+	"    system: 'memota' | 'memota-speech';",
+	"    key: string;",
+	"  };",
+	"};",
+	"export interface RelationUpdateInput {",
+	"  relation_id: string;",
+	"  changes: FieldChange[];",
 	"}",
 	"export interface SandboxEntity<K extends KnownEntityKind = KnownEntityKind> {",
 	"  entity_id: string;",
@@ -978,54 +982,14 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"  text: string;",
 	"  language?: string;",
 	"};",
-	"export type SequenceDuration<Span = unknown> =",
-	"  | {",
-	"      readonly mode: 'from-source';",
-	"    }",
-	"  | {",
-	"      readonly mode: 'fixed';",
-	"      readonly value: Span;",
-	"    };",
-	"export interface SequenceRange<Point = unknown> {",
-	"  readonly start: Point;",
-	"  readonly end: Point;",
-	"}",
-	"export type SequentialClipAnchor =",
-	"  | {",
-	"      readonly position: 'before' | 'after';",
-	"      readonly clipEntityId: string;",
-	"    }",
-	"  | {",
-	"      readonly position: 'trackStart';",
-	"    };",
-	"export interface SetCaptionVisibilityInput {",
-	"  readonly timelineEntityId: string;",
-	"  readonly hidden: boolean;",
-	"}",
-	"export interface SetClipPlacementInput {",
-	"  readonly clipEntityId: string;",
-	"  readonly placement: ClipPlacement;",
-	"}",
-	"export interface SetClipSpeedInput {",
-	"  readonly clipEntityId: string;",
-	"  readonly timeRemapping: LinearClipSpeed | null;",
-	"}",
-	"export interface SetClipVolumeInput {",
-	"  readonly clipEntityId: string;",
-	"  /** Playback gain in decibels. */",
-	"  readonly volume: number;",
-	"}",
 	"/** Stored own fields; a variant may obtain required content fields from its declared bases. */",
 	"export type StoredEntityPayload<K extends KnownEntityKind> =",
 	"  | EntityPayloadByKind[K]",
+	"  | (K extends 'caption' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never)",
 	"  | (JsonObject &",
 	"      Partial<EntityPayloadByKind[K]> & {",
 	"        baseEntityIds: string[];",
 	"      });",
-	"export interface TrimClipInput {",
-	"  readonly clipEntityId: string;",
-	"  readonly sourceRange: SequenceRange<number>;",
-	"}",
 	"export interface UnboundedConstantSequencePayload extends JsonObject {",
 	"  extent: {",
 	"    kind: 'unbounded';",
@@ -1037,93 +1001,60 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"export interface UnlinkRelationInput {",
 	"  relation_id: string;",
 	"}",
-	"export interface UpdateClipInput {",
-	"  readonly clipEntityId: string;",
-	"  /** Complete replacement for the Clip-owned payload. */",
-	"  readonly payload: JsonObject;",
-	"}",
-	"export interface UpdateClipMarkerInput {",
-	"  readonly clipEntityId: string;",
-	"  readonly sourceRange?: SequenceRange<number>;",
-	"  /** Passing `undefined` explicitly removes the optional target range. */",
-	"  readonly targetRange?: SequenceRange<number> | undefined;",
-	"  readonly duration?: SequenceDuration<number>;",
-	"  /** Passing `undefined` explicitly removes the optional remapping value. */",
-	"  readonly timeRemapping?: JsonValue | undefined;",
-	"}",
 	"/** Patch supplied fields on the assembled entity; omitted fields remain unchanged. */",
 	"export interface UpdateEntityInput {",
 	"  entity_id: string;",
 	"  payload: JsonObject;",
 	"}",
-	"/** Timeline writes accept existing media Entity ids, never Memota asset ids or URLs. */",
-	"export interface EditApi {",
-	"  insertClip(input: InsertClipInput): ClipEntityId;",
-	"  insertPlacedClip(input: InsertPlacedClipInput): ClipEntityId;",
-	"  updateClipMarker(input: UpdateClipMarkerInput): void;",
-	"  setClipPlacement(input: SetClipPlacementInput): void;",
-	"  moveSequentialClips(input: MoveSequentialClipsInput): void;",
-	"  moveClip(input: MoveClipInput): void;",
-	"  replaceClipContent(input: ReplaceClipContentInput): void;",
-	"  setClipVolume(input: SetClipVolumeInput): void;",
-	"  setClipSpeed(input: SetClipSpeedInput): void;",
-	"  trimClip(input: TrimClipInput): void;",
-	"  deleteClip(input: DeleteClipInput): void;",
-	"  deleteClipTree(input: DeleteClipTreeInput): void;",
-	"  updateClip(input: UpdateClipInput): void;",
-	"  moveVoiceover(input: MoveVoiceoverInput): void;",
-	"  moveClipsToStarts(input: MoveClipsToStartsInput): void;",
-	"  deleteVoiceover(input: DeleteVoiceoverInput): void;",
-	"  deleteBgm(input: DeleteBgmInput): void;",
-	"  setCaptionVisibility(input: SetCaptionVisibilityInput): void;",
-	"  patchCaptionStyle(input: PatchCaptionStyleInput): void;",
-	"  insertCaptionClip(input: InsertCaptionClipInput): ClipEntityId;",
-	"}",
-	"export interface TimelineApi {",
-	"  snapshot(): EntityStoreSnapshot & {",
-	"    audioScriptEntityId: string;",
-	"  };",
-	"}",
-	"export interface SandboxCheckpoint {",
-	"  readonly index: number;",
-	"}",
-	"export declare const edit: EditApi;",
-	"export declare const timeline: TimelineApi;",
 	"export declare const entities: BusinessEntityFacade;",
 	"export declare const relations: BusinessRelationFacade;",
-	"export declare function checkpoint(): SandboxCheckpoint;",
-	"export declare function rollbackTo(cp: SandboxCheckpoint): void;",
+	"/** Resolve this Entity's attached resource through the host; await before using an uninitialized Caption. */",
+	"export declare function rgetAssetFromEntity(entityId: string): Promise<EntityAssetContent>;",
+	"export declare function checkpoint(): EntitySandboxCheckpoint;",
+	"export declare function rollbackTo(cp: EntitySandboxCheckpoint): void;",
 	"export declare const inputs: Readonly<Record<string, unknown>>;",
+	"export declare const console: {",
+	"  log(...values: unknown[]): void;",
+	"  info(...values: unknown[]): void;",
+	"  warn(...values: unknown[]): void;",
+	"  error(...values: unknown[]): void;",
+	"};",
 	""
 ].join("\n");
 //#endregion
 //#region src/prompt.ts
 const MEDEO_TOOL_DESCRIPTION = `
-Edit the authoritative Medeo Entity/Relation graph through a deterministic, side-effect-free JavaScript sandbox. Timeline objects and edit targets are Entities, not Memota assets or legacy parts.
+Edit the authoritative Medeo Entity/Relation graph in an isolated JavaScript sandbox.
 
 Operations:
-- snapshot: read the current Entity/Relation view, project attachments and causal Loro baseline. Reading does not initialize or mutate domain data.
-- run-edit-script: inspect timeline.snapshot(), entities.*, and relations.*; edit.* operates existing Entity ids and creates the required Clip/SequenceMarker structural graph. The sandbox has no network, storage or generation access. Use assembled entity fields; the host manages resource storage and generation provenance. A successful run returns preview, logs, base revision and plan_id.
-- commit-plan: publish the native Loro update compiled against the plan’s causal baseline. Concurrent independent edits merge through Loro. The timeline and AudioScript panel read the merged entity state. A failed transport is unconfirmed; retry the same plan_id so operation identities are preserved.
+- snapshot: read assembled entities, relations, project attachments and the current document version. Reading never initializes or changes the document.
+- run-edit-script: use entities and relations to inspect and edit the causal working view. rgetAssetFromEntity(entityId) delegates an attached-resource read to the host. The script has no network, generation or storage access. A successful run returns preview, logs and plan_id.
+- commit-plan: publish the original native Loro operations compiled against the plan's causal baseline. Independent concurrent edits merge; failed transport is unconfirmed, so retry the same plan_id to preserve operation identity.
 
-Default flow: snapshot → run-edit-script with auto_commit=false → inspect preview → commit-plan. Use auto_commit=true only for low-risk edits when the host does not need user confirmation. Concurrent edits do not require replaying the script against a newer snapshot. If a domain conflict is reported, inspect the merged state and resolve it explicitly; never replace the complete document to force the edit through.
-
-Generation tools return Asset references, not domain Entity ids. An Asset id may be passed as an entity resource field: external: { system: "memota", key: assetId }. Create or update the domain Entity using entities.*, then place its Entity id with edit.insertClip. Asset ids are not Entity ids, baseEntityIds or Relation endpoints. The sandbox exposes no Asset creation, lookup, reading or storage API; the host resolves resource references. Each placement has its own Clip and SequenceMarker. Generation lineage is host-synced; relations.of(entityId) is endpoint-agnostic.
+Default flow: snapshot → run-edit-script with auto_commit=false → inspect preview → commit-plan. Use auto_commit=true for low-risk edits that need no host confirmation. A domain conflict requires inspecting and explicitly resolving the merged state; never overwrite the document or silently replay an old plan on a new snapshot.
 `.trim();
 const MEDEO_TOOL_EXECUTION_RULES = `
-The host supplies the current document. Do not ask for, invent, or pass a document id.
-timeline.snapshot() returns the Entity/Relation graph with its revision, not a legacy VideoDraft. Inspect Timeline, Track, Clip, SequenceMarker and their relations to plan edits.
-Inspect existing Image/Video/Audio/Voice Entities and their factual extents before placing them. For an uploaded or generated resource, create its media Entity with the returned Asset id in external.key and the factual media extent. The host resolves its physical resource. Replace a Clip's content using another content Entity id. Never fabricate a duration.
-Caption composes AudioScript text. Its optional external field may carry the Caption Asset id; the host resolves that resource. A Caption created from AudioScript may have no physical resource. Read and edit assembled fields through entities; do not create Asset entities or physical-asset Relations.
-The editor projection supports the existing four Track roles: video_clip (Image/Video), speech (Voice), caption (Caption), and bgm (Audio), one of each. Clip.volume is decibels (-60 to 20, 0 = original). Marker.sourceRange is the selected source interval; Marker.duration is effective display/playback duration. Coordinates and duration are whole milliseconds for this reader, not a global DSL restriction. Placement is exactly one of Clip.order, Marker.targetRange, or clip-anchor(child,host) plus Marker.anchorOffset. Use the native move/delete/voiceover helpers so placement and cascade decisions are in the same entity plan. Reading the graph never rebinds anchors or invents empty clips. Linear timeRemapping is {kind:'linear',rate:2,mode:'constant'} and agrees with rounded source span divided by rate. Image remains unbounded/constant; an explicit linear rate scales its display window, not an invented media extent. Nonlinear speed and multiple visual overlay tracks are unsupported.
-Entities own fields; ordinary Relations express associations; variants directly hold baseEntityIds and assemble the referenced entities. These foundations are fixed: implementation must follow them, never redefine them. Any entity may compose multiple bases. Equal field names from multiple bases (even equal values) are errors, even when the variant declares that field itself. After validating all base fields are unambiguous, explicitly declared own fields may override base fields without mutating the bases. Base ordering never resolves conflicts. AudioScript owns segmented text. Caption and PhoneticScript persist baseEntityIds including their AudioScript, plus their own fields; no composition Relation exists. Create the real bases before reading or committing a variant. Inside the DSL sandbox, entities.get/list expose complete assembled fields. Consumers read fields without inspecting base IDs or merging bases. entities.update patches supplied fields and routes inherited fields to their declaring entity; omitted fields remain unchanged. entities.declareFields explicitly declares own overrides and is distinct from an ordinary field edit. Persistence keeps owned fields only. entities.readCaptionContent(id) and entities.readPhoneticScriptContent(id) return assembled text. Missing/cyclic bases and field conflicts fail before persistence.
-Use edit.insertCaptionClip with baseEntityIds and selections, plus captionEntityId when generation returned a Caption identity; each voiceover caption also supplies baseEntityIds. A selection names segmentId and may use a half-open Unicode code-point textRange to split a segment for the screen without rewriting AudioScript. Generate Voice from an existing PhoneticScript, then use phoneticScriptEntityId in the voiceover helper or relations.linkPhoneticScriptRender({output_entity_id,phonetic_script_entity_id}) for its render relation. Caption and Voice have their own Clips; display anchoring is explicit and independent of composition/alignment.
-Move or stretch only the Clip's display Marker; preserve Caption intrinsic Sequence, AudioScript text and its annotation Markers. AudioScript cannot enter a Clip and has no intrinsic time. audio-script-source links its ASR source Audio/Video/Voice; audio-script-marker attaches annotation Markers with directly assigned segmentRanges:{segmentId,startMs,endMs} in whole milliseconds. Annotation Markers have no Clip/AXVideo/content/Timeline relations and never refer to other Markers for time. BGM keeps factual source duration with durationPolicy:'timeline'. Never introduce a speech entity kind.
-Create only the known entity kinds. Project creation initializes one current Timeline, four Tracks and an attached AudioScript with segments:[]. Read the current AudioScript ID from timeline.snapshot(); the panel displays this attachment and preserves its segments. Normal edits operate this script, not an unrelated newly created script.
-Immutable updates apply to every entity: editing an owned field creates a new content version ID; changing only a variant's base ID preserves the variant ID. Editing a base through a variant updates the owner, and the compiler advances the affected base links and project attachment. A variant-owned edit creates a new variant version and retains its unchanged bases. Do not manually clone entities or duplicate inherited fields to implement versioning. Versions preserve native text and list editing identities so independent concurrent edits survive. Missing facts, unsupported layouts and composition conflicts are explicit errors; there is no legacy migration or whole-state overwrite path.
-Use only the globals and methods declared by the following TypeScript interface. Values not declared here are unavailable.
+The host supplies the current document. Do not invent or request a document id. The sandbox exposes only the API below: entity operations, relation operations, entity-bound resource reading and checkpoints. All business edits are expressed using entity fields and relation kinds.
+
+Entity reads return assembled snapshots. Mutating returned objects has no persistence effect. Create declares own fields. Update requires a nonempty changes array and atomically applies its ordered operations to assembled fields, routing each to its declaring owner. DeclareFields explicitly establishes own fields or an override; it is not the normal way to edit inherited content. Deletion requires explicitly handling incident relations, variant references and protected project attachments; it never deletes external resources or cascades business entities.
+
+FieldChange paths start at payload for an entity, and at metadata or trace for a relation. Use strings for fields and {elementId:'...'} for list members, never numeric indices. Segment identity is segmentId; reference identity is the referenced id. set writes scalars or schema-declared atomic values, including complete sourceRange, targetRange, extent, duration, timeRemapping, textRange and external. It cannot replace collaborative text, lists or maps. Edit text with text.splice (Unicode code-point index and deleteCount), and segments/selections with list.insert, list.move or list.remove. beforeElementId:null means append; moving before itself, duplicate identity or an absent anchor is an error. Unset removes optional fields only. Map fields are edited through leaf paths; initialize a new own map via declareFields. baseEntityIds is unordered composition membership: insert/remove are supported, moving bases cannot resolve field conflicts. Independent fields and list-item text edits retain native Loro identities.
+
+Entities own data. Relations associate two existing entities; endpoint_0 and endpoint_1 retain their declared positions. Each relation kind defines direction and meaning; neither relation listing order nor endpoint storage order implies a global business order. Relations.update changes metadata/trace fields only; kind/endpoints require explicit unlink plus link with a new identity. Generated relations use generated(output,input). Ordinary associations do not implement composition.
+
+Variants directly hold baseEntityIds. Assembly validates every base before applying explicit own overrides: two bases supplying the same field are an error even if values match or the variant declares that field. Missing/cyclic bases fail. Consumers operate assembled fields without copying inherited content or resolving owners themselves. An owned-field edit creates a new immutable entity version. Base changes automatically advance variant base references and project attachments without versioning an unchanged variant. A variant-owned change versions the variant and retains unchanged bases. Do not manually clone entities for versioning. Use the current plan's ids throughout that execution; refresh after commit.
+
+Generation tools return resource references. An asset id may be passed in an entity's external:{system:'memota',key:assetId}; it is never an entity id, baseEntityId or relation endpoint. Physical resources are host infrastructure. The sandbox has no direct resource lookup/CRUD by asset id. rgetAssetFromEntity takes only an existing business entity id and returns {assetId,content} for its attached resource. For output_caption, create a Caption with payload:{external:{system:'memota',key:assetId}}, then await rgetAssetFromEntity(captionId). The host initializes Caption intrinsic timing and its composed project AudioScript text in the same causal plan; read the editable fields with entities.get afterwards. Repeated reads preserve edited text and return the original immutable resource content. Unawaited initialization is completed before validation; failure prevents publication. Resource-free Caption composition from AudioScript is also valid.
+
+Project initialization creates one current Timeline, the four standard Tracks and one attached AudioScript with segments:[]. Locate these with entities.list, and edit the attached script. AudioScript owns independent multi-segment text. Caption and PhoneticScript compose it through baseEntityIds. Caption owns selections ({segmentId,textRange?}), intrinsic timing and style; selection textRange is a half-open code-point range and can split display text without rewriting the script. PhoneticScript owns pronunciation/prosody; Voice is generated from it and related by phonetic-script-render(voice,phoneticScript). Speech and caption occupy separate Clips. Subtitles normally accompany sound; use source media or generate Voice from PhoneticScript when the request requires narration. Do not fabricate a sound resource.
+
+AudioScript has no intrinsic time and cannot be Clip content. ASR input Audio/Video/Voice associates via audio-script-source(script,source). Its external annotation SequenceMarker associates via audio-script-marker(script,marker) and receives assigned segmentRanges, not references to another marker. Caption intrinsic timing and its Clip's display SequenceMarker are distinct. Move/stretch display by editing only the placement marker.
+
+To place content, create a Clip and a SequenceMarker, then link track-clip(track,clip), clip-marker(clip,marker) and marker-content(marker,content). Existing track membership uses timeline-track(timeline,track). The editor has one track of each role: video_clip for Image/Video, speech for Voice, caption for Caption, bgm for Audio. Inspect factual media extents; never invent duration. Each placement is exactly one of Clip.order (sequential), Marker.targetRange (absolute) or clip-anchor(childClip,hostClip) plus Marker.anchorOffset. Marker.sourceRange selects source, duration describes playback/display. Whole milliseconds are required by this editor projection. Clip.volume is decibels (-60..20, 0 original). Image is unbounded/constant. Linear timeRemapping is {kind:'linear',rate:2,mode:'constant'}, with duration matching the rounded source span/rate. BGM can use durationPolicy:'timeline'. Nonlinear speed and multiple overlay tracks are unsupported. Caption visibility is the caption Track's hidden field. Caption style is its style map. Handle structural links explicitly when moving/deleting; there is no implicit cascade.
+
+checkpoint returns an opaque token valid only in this execution. rollbackTo restores that point and invalidates later checkpoints. Returned read snapshots and inputs are not writable document authorities. Use only the declarations below.
 `.trim();
-/** Render the complete MEngine-owned context injected before one model call. */
+/** MEngine owns API disclosure; Harness only supplies the changing document context. */
 function renderMedeoModelContext(input) {
 	const updated = input.updatedSincePreviousModelCall == null ? "unknown (first model call)" : String(input.updatedSincePreviousModelCall);
 	return `
@@ -1131,11 +1062,11 @@ ${MEDEO_TOOL_DESCRIPTION}
 
 ${MEDEO_TOOL_EXECUTION_RULES}
 
-Current MEngine document state (sampled dynamically immediately before this model call):
+Current MEngine document state (sampled immediately before this model call):
 - document_version: ${JSON.stringify(input.documentVersion)}
 - updated_since_previous_model_call: ${updated}
 
-When updated_since_previous_model_call is true, the document changed after the previous model call. The change may have come from this tool or another editor, so take a fresh snapshot before planning further edits.
+When updated_since_previous_model_call is true, take a fresh snapshot before planning further edits.
 
 Sandbox TypeScript interface:
 \`\`\`ts
@@ -1724,10 +1655,10 @@ function createMedeoTool(options) {
 				document,
 				baseVersion,
 				entityState,
-				entityOnly: true,
+				loadEntityAsset: options.loadEntityAsset ? (entity) => options.loadEntityAsset(input.doc_id, entity) : void 0,
 				script: input.script,
 				...input.inputs !== void 0 ? { inputs: input.inputs } : {},
-				timeoutMs: input.timeout_ms ?? options.sandbox?.timeoutMs,
+				timeoutMs: input.timeout_ms ?? options.sandbox?.timeoutMs ?? 3e4,
 				memoryLimitMb: input.memory_limit_mb ?? options.sandbox?.memoryLimitMb
 			});
 			if (!result.ok) return {
@@ -1987,6 +1918,6 @@ function stableId(prefix, ...parts) {
 	return `${prefix}_${createHash("sha256").update(JSON.stringify(parts)).digest("hex")}`;
 }
 //#endregion
-export { EditSandboxSession, MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, collectAffectedPartIds, commitPlan, createMedeoTool, materializeResources, renderCompactProjection, renderPreview, runEditScript };
+export { MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, collectAffectedPartIds, commitPlan, createMedeoTool, materializeResources, renderCompactProjection, renderPreview, runEditScript };
 
 //# sourceMappingURL=index.mjs.map