@mengine/medeo-tool 1.4.1-alpha.5 → 2.0.1-alpha.5

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { C as UpdateEntityInput, S as UnlinkRelationInput, _ as LinkRelationInput, a as DeleteEntityInput, b as SandboxEntity, c as EntitySandboxCheckpoint, d as JsonObject, f as JsonPrimitive, g as LinkGeneratedRelationInput, h as KnownRelationKind, i as CreateEntityInput, l as EntityStoreSnapshot, m as KnownEntityKind, n as BusinessEntityFacade, o as EntityCommand, p as JsonValue, r as BusinessRelationFacade, s as EntityPlanState, t as AuthorableRelationKind, u as EntityUpdateInput, v as RelationUpdateInput, x as SandboxRelation, y as ResourceEntityKind } from "./entity-contract-DlmUSouB.mjs";
+import { C as UpdateEntityInput, S as UnlinkRelationInput, _ as LinkRelationInput, a as DeleteEntityInput, b as SandboxEntity, c as EntitySandboxCheckpoint, d as JsonObject, f as JsonPrimitive, g as LinkGeneratedRelationInput, h as KnownRelationKind, i as CreateEntityInput, l as EntityStoreSnapshot, m as KnownEntityKind, n as BusinessEntityFacade, o as EntityCommand, p as JsonValue, r as BusinessRelationFacade, s as EntityPlanState, t as AuthorableRelationKind, u as EntityUpdateInput, v as RelationUpdateInput, x as SandboxRelation, y as ResourceEntityKind } from "./entity-contract-G4HxwNXl.mjs";
 import { JournalEntry, ManualSyncDoc, MediaAssetFact, PartIdFactory, SemanticOpName, VideoDocument, VideoDraft } from "@mengine/medeo-client";
 
 //#region src/document/compact-projection.d.ts
@@ -40,6 +40,8 @@ interface EntityAssetContent {
 }
 /** Host-only I/O. The sandbox supplies an Entity, never an arbitrary Asset query. */
 type EntityAssetLoader = (docId: string, entity: SandboxEntity) => Promise<EntityAssetContent>;
+/** Program-only initial resource creation; never exposed as a sandbox API. */
+type EntityAssetWriter = (docId: string, entity: SandboxEntity, content: JsonValue) => Promise<EntityAssetContent>;
 //#endregion
 //#region src/entity/entity-sandbox.d.ts
 type DomainIdFactory = (prefix: 'entity' | 'relation') => string;
@@ -88,6 +90,7 @@ interface ConsoleShim {
  */
 interface RunEditScriptOptions {
   loadEntityAsset?: (entity: SandboxEntity) => Promise<EntityAssetContent>;
+  writeEntityAsset?: (entity: SandboxEntity, content: EntityAssetContent['content']) => Promise<EntityAssetContent>;
   document: VideoDocument;
   baseVersion: string;
   script: string;
@@ -395,6 +398,8 @@ interface CreateMedeoToolOptions {
   /** Assemble optional Caption artifacts by immutable entity ID; never exposed to scripts. */
   loadCaptionAssets?: CaptionAssetsLoader;
   loadEntityAsset?: EntityAssetLoader;
+  /** Program-side persistence for immutable AudioScript resources. */
+  writeEntityAsset?: EntityAssetWriter;
   fetchImpl?: typeof fetch;
   /** @deprecated ManualSyncDoc has no SSE or reconnect loop. */
   sseReconnectDelayMs?: number;
@@ -567,5 +572,5 @@ declare function materializeResources(options: EntityHttpClientOptions & {
   loadGenerationFacts?: GenerationFactsLoader;
 }, resources: readonly GeneratedResource[]): Promise<readonly string[]>;
 //#endregion
-export { type AssetGenerationFact, type AuthorableRelationKind, type BusinessEntityFacade, type BusinessRelationFacade, type CaptionAssetAssemblyOutcome, type CaptionAssetFact, type CaptionAssetsLoader, type ChangePlan, type CommitPlan, type CommitPlanOptions, type CommitPlanResult, type CompactProjectionOptions, type ConsoleShim, type CreateEntityInput, type CreateMedeoToolOptions, type DeleteEntityInput, type EditSandboxSessionOptions, type EditScriptResult, type EntityAssetContent, type EntityAssetLoader, type EntityCommand, type EntityCommitResult, type EntityPlanState, type EntitySandboxCheckpoint, type EntityStoreSnapshot, type EntityUpdateInput, type GeneratedResource, type GenerationFactsLoader, type GenerationSyncOutcome, type JsonObject, type JsonPrimitive, type JsonValue, type KnownEntityKind, type KnownRelationKind, type LinkGeneratedRelationInput, type LinkRelationInput, MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, type MedeoCommitResult, type MedeoInitialDraft, type MedeoModelContext, type MedeoModelContextInput, type MedeoTool, type MedeoToolInput, type MedeoToolOp, type MedeoToolResult, type RelationUpdateInput, type ResourceEntityKind, type RunEditScriptOptions, type SandboxEntity, type SandboxRelation, type UnlinkRelationInput, type UpdateEntityInput, collectAffectedPartIds, commitPlan, createMedeoTool, materializeResources, renderCompactProjection, renderPreview, runEditScript };
+export { type AssetGenerationFact, type AuthorableRelationKind, type BusinessEntityFacade, type BusinessRelationFacade, type CaptionAssetAssemblyOutcome, type CaptionAssetFact, type CaptionAssetsLoader, type ChangePlan, type CommitPlan, type CommitPlanOptions, type CommitPlanResult, type CompactProjectionOptions, type ConsoleShim, type CreateEntityInput, type CreateMedeoToolOptions, type DeleteEntityInput, type EditSandboxSessionOptions, type EditScriptResult, type EntityAssetContent, type EntityAssetLoader, type EntityAssetWriter, type EntityCommand, type EntityCommitResult, type EntityPlanState, type EntitySandboxCheckpoint, type EntityStoreSnapshot, type EntityUpdateInput, type GeneratedResource, type GenerationFactsLoader, type GenerationSyncOutcome, type JsonObject, type JsonPrimitive, type JsonValue, type KnownEntityKind, type KnownRelationKind, type LinkGeneratedRelationInput, type LinkRelationInput, MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, type MedeoCommitResult, type MedeoInitialDraft, type MedeoModelContext, type MedeoModelContextInput, type MedeoTool, type MedeoToolInput, type MedeoToolOp, type MedeoToolResult, type RelationUpdateInput, type ResourceEntityKind, type RunEditScriptOptions, type SandboxEntity, type SandboxRelation, type UnlinkRelationInput, type UpdateEntityInput, collectAffectedPartIds, commitPlan, createMedeoTool, materializeResources, renderCompactProjection, renderPreview, runEditScript };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { c as isMediaAssetVariantKind, i as businessState, o as createEntityId, s as createRelationId, t as EntitySandbox } from "./entity-sandbox-TaUVT3on.mjs";
+import { c as isMediaAssetVariantKind, i as businessState, o as createEntityId, s as createRelationId, t as EntitySandbox } from "./entity-sandbox-DSFbfybl.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";
@@ -214,11 +214,14 @@ function runEditScript(options) {
 				armTimeout();
 				return;
 			}
-			if (message.t === "entity-asset") {
+			if (message.t === "entity-asset" || message.t === "write-entity-asset") {
 				(async () => {
 					try {
-						if (!options.loadEntityAsset) throw new Error("Entity Asset loader is unavailable");
-						const result = await options.loadEntityAsset(message.entity);
+						const result = message.t === "write-entity-asset" ? await (options.writeEntityAsset ?? (() => {
+							throw new Error("Entity Asset writer is unavailable");
+						}))(message.entity, message.content) : await (options.loadEntityAsset ?? (() => {
+							throw new Error("Entity Asset loader is unavailable");
+						}))(message.entity);
 						if (!settled) worker.postMessage({
 							t: "entity-asset-result",
 							requestId: message.requestId,
@@ -985,7 +988,7 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"/** 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)",
+	"  | (K extends 'caption' | 'voice' ? JsonObject & Pick<MediaAssetPayload, 'external'> : never)",
 	"  | (JsonObject &",
 	"      Partial<EntityPayloadByKind[K]> & {",
 	"        baseEntityIds: string[];",
@@ -1008,7 +1011,7 @@ const ENTITY_EDIT_SANDBOX_API_DTS = [
 	"}",
 	"export declare const entities: BusinessEntityFacade;",
 	"export declare const relations: BusinessRelationFacade;",
-	"/** Resolve this Entity's attached resource through the host; await before using an uninitialized Caption. */",
+	"/** Resolve this Entity's attached resource through the host; await before using an uninitialized Caption or Voice. */",
 	"export declare function rgetAssetFromEntity(entityId: string): Promise<EntityAssetContent>;",
 	"export declare function checkpoint(): EntitySandboxCheckpoint;",
 	"export declare function rollbackTo(cp: EntitySandboxCheckpoint): void;",
@@ -1048,7 +1051,9 @@ Generation tools return resource references. An asset id may be passed in an ent
 
 Project initialization creates one current Timeline, the four standard Tracks and one attached AudioScript with segments:[]. A project may contain multiple independent complete AudioScripts (for example a generated script and an uploaded video transcript). The project AudioScript attachment selects only the panel view; it is not a singleton or membership constraint. Locate scripts with entities.list and choose the appropriate source. AudioScript owns independent multi-segment text; each can have multiple Caption variants. Caption and PhoneticScript compose it through baseEntityIds. Caption owns exactly one selection object ({segmentId,textRange?}), never an array or the legacy selections field. It selects one script segment or a contiguous substring, and owns only that selection's intrinsic timing and style; segmentId is a stable script-local identity, not an entity reference or transient array index; 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.
+For Speech resources, create a Voice with external:{system:'memota-speech',key:speechId}, then await rgetAssetFromEntity(voiceId) before linking its placement. The host supplies full extent and optional voice-library identity, and assembles physical storage facts internally. Read the visible fields through entities.get; never invent them or use a Speech ID as a Memota media ID. TTS Voice still requires its real PhoneticScript relation; resource loading does not invent script content.
+
+Direct AudioScript creation saves its segments as a resource before publication. Its assembled segments remain readable and editable; committed text changes preserve native Loro operations and save a new immutable resource, automatically advancing the external reference. AudioScripts initialized through Caption resources keep inline segments without an additional script resource. Do not manage these resources yourself. 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.
 
@@ -1656,6 +1661,7 @@ function createMedeoTool(options) {
 				baseVersion,
 				entityState,
 				loadEntityAsset: options.loadEntityAsset ? (entity) => options.loadEntityAsset(input.doc_id, entity) : void 0,
+				writeEntityAsset: options.writeEntityAsset ? (entity, content) => options.writeEntityAsset(input.doc_id, entity, content) : void 0,
 				script: input.script,
 				...input.inputs !== void 0 ? { inputs: input.inputs } : {},
 				timeoutMs: input.timeout_ms ?? options.sandbox?.timeoutMs ?? 3e4,