@morshoto/framekit 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (156) hide show
  1. package/dist-package/adapters/final-cut/typescript/src/analyzers.d.ts +58 -0
  2. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +52 -13
  3. package/dist-package/adapters/final-cut/typescript/src/assets.d.ts +24 -0
  4. package/dist-package/adapters/final-cut/typescript/src/background-export.d.ts +98 -0
  5. package/dist-package/adapters/final-cut/typescript/src/background-materialization.d.ts +47 -0
  6. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery-guard.d.ts +32 -0
  7. package/dist-package/adapters/final-cut/typescript/src/canonical-recovery.d.ts +22 -0
  8. package/dist-package/adapters/final-cut/typescript/src/canonical-verification.d.ts +11 -0
  9. package/dist-package/adapters/final-cut/typescript/src/canonical.d.ts +184 -0
  10. package/dist-package/adapters/final-cut/typescript/src/canonical.js +33 -1
  11. package/dist-package/adapters/final-cut/typescript/src/connection.d.ts +103 -0
  12. package/dist-package/adapters/final-cut/typescript/src/disposable-native.d.ts +90 -0
  13. package/dist-package/adapters/final-cut/typescript/src/documents.d.ts +3 -0
  14. package/dist-package/adapters/final-cut/typescript/src/documents.js +3 -0
  15. package/dist-package/adapters/final-cut/typescript/src/experimental.d.ts +8 -0
  16. package/dist-package/adapters/final-cut/typescript/src/export.d.ts +125 -0
  17. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.d.ts +54 -0
  18. package/dist-package/adapters/final-cut/typescript/src/fcpxml.d.ts +75 -0
  19. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +6 -1
  20. package/dist-package/adapters/final-cut/typescript/src/index.d.ts +22 -0
  21. package/dist-package/adapters/final-cut/typescript/src/library-inspection.d.ts +101 -0
  22. package/dist-package/adapters/final-cut/typescript/src/live.d.ts +101 -0
  23. package/dist-package/adapters/final-cut/typescript/src/live.js +8 -0
  24. package/dist-package/adapters/final-cut/typescript/src/media.d.ts +12 -0
  25. package/dist-package/adapters/final-cut/typescript/src/native-operation.d.ts +6 -0
  26. package/dist-package/adapters/final-cut/typescript/src/native-recovery-inspection.d.ts +77 -0
  27. package/dist-package/adapters/final-cut/typescript/src/native-session.d.ts +130 -0
  28. package/dist-package/adapters/final-cut/typescript/src/native.d.ts +828 -0
  29. package/dist-package/adapters/final-cut/typescript/src/native.js +274 -107
  30. package/dist-package/adapters/final-cut/typescript/src/pasteboard-snapshot.d.ts +114 -0
  31. package/dist-package/adapters/final-cut/typescript/src/publish-readback.d.ts +26 -0
  32. package/dist-package/adapters/final-cut/typescript/src/publish-readback.js +18 -2
  33. package/dist-package/adapters/final-cut/typescript/src/publisher.d.ts +215 -0
  34. package/dist-package/adapters/final-cut/typescript/src/session.d.ts +43 -0
  35. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.d.ts +51 -0
  36. package/dist-package/adapters/final-cut/typescript/src/sqlite-experiment.d.ts +156 -0
  37. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.d.ts +134 -0
  38. package/dist-package/adapters/final-cut/typescript/src/sqlite-materialization.d.ts +110 -0
  39. package/dist-package/adapters/final-cut/typescript/src/sqlite-wal-observation.d.ts +132 -0
  40. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.d.ts +61 -0
  41. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +28 -4
  42. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.d.ts +54 -0
  43. package/dist-package/adapters/headless/typescript/src/audio-output.d.ts +3 -0
  44. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.d.ts +11 -0
  45. package/dist-package/adapters/headless/typescript/src/ffmpeg-media-probe.js +26 -2
  46. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.d.ts +25 -0
  47. package/dist-package/adapters/headless/typescript/src/ffmpeg-renderer.js +5 -0
  48. package/dist-package/adapters/headless/typescript/src/ffmpeg-verifier.d.ts +15 -0
  49. package/dist-package/adapters/headless/typescript/src/index.d.ts +3 -0
  50. package/dist-package/apps/cli/src/dev-doctor.d.ts +25 -0
  51. package/dist-package/apps/cli/src/headless-projects.d.ts +3 -0
  52. package/dist-package/apps/cli/src/main.d.ts +10 -0
  53. package/dist-package/apps/mcp-server/runtime/ffmpeg-audio-backend.py +129 -0
  54. package/dist-package/apps/mcp-server/runtime/whisper-speech-backend.py +92 -2
  55. package/dist-package/apps/mcp-server/src/build-alignment.d.ts +10 -0
  56. package/dist-package/apps/mcp-server/src/build-identity.d.ts +7 -0
  57. package/dist-package/apps/mcp-server/src/build-identity.json +2 -2
  58. package/dist-package/apps/mcp-server/src/canonical-native-snapshot.d.ts +8 -0
  59. package/dist-package/apps/mcp-server/src/final-cut-runtime-config.d.ts +5 -0
  60. package/dist-package/apps/mcp-server/src/headless-project-snapshot.d.ts +3 -0
  61. package/dist-package/apps/mcp-server/src/headless-sessions.d.ts +89 -0
  62. package/dist-package/apps/mcp-server/src/main.d.ts +1 -0
  63. package/dist-package/apps/mcp-server/src/materialization-jobs.d.ts +204 -0
  64. package/dist-package/apps/mcp-server/src/readback-policy.d.ts +18 -0
  65. package/dist-package/apps/mcp-server/src/routing.d.ts +90 -0
  66. package/dist-package/apps/mcp-server/src/server.d.ts +75 -0
  67. package/dist-package/apps/mcp-server/src/server.js +77 -7
  68. package/dist-package/apps/mcp-server/src/tools/skills/catalog.d.ts +19 -0
  69. package/dist-package/apps/mcp-server/src/tools/skills/metadata.d.ts +37 -0
  70. package/dist-package/apps/mcp-server/src/tools/skills/register.d.ts +11 -0
  71. package/dist-package/apps/mcp-server/src/version.d.ts +4 -0
  72. package/dist-package/packages/headless-application/src/external-edit.d.ts +30 -0
  73. package/dist-package/packages/headless-application/src/external-edit.js +72 -0
  74. package/dist-package/packages/headless-application/src/headless-projects.d.ts +233 -0
  75. package/dist-package/packages/headless-application/src/headless-projects.js +1 -1
  76. package/dist-package/packages/headless-application/src/index.d.ts +2 -0
  77. package/dist-package/packages/headless-application/src/index.js +1 -0
  78. package/dist-package/packages/runtime/src/application/duration-policy-service.d.ts +4 -0
  79. package/dist-package/packages/runtime/src/application/local-media.d.ts +46 -0
  80. package/dist-package/packages/runtime/src/application/media-analysis-service.d.ts +40 -0
  81. package/dist-package/packages/runtime/src/application/media-analysis-service.js +105 -15
  82. package/dist-package/packages/runtime/src/application/project-service.d.ts +35 -0
  83. package/dist-package/packages/runtime/src/application/project-store.d.ts +56 -0
  84. package/dist-package/packages/runtime/src/application/project-transactions.d.ts +51 -0
  85. package/dist-package/packages/runtime/src/application/runtime-options.d.ts +15 -0
  86. package/dist-package/packages/runtime/src/application/semantic-media-index-store.d.ts +28 -0
  87. package/dist-package/packages/runtime/src/application/transaction-store.d.ts +10 -0
  88. package/dist-package/packages/runtime/src/audio/analysis.d.ts +3 -0
  89. package/dist-package/packages/runtime/src/audio/analysis.js +95 -0
  90. package/dist-package/packages/runtime/src/audio/dialogue-normalization.d.ts +47 -0
  91. package/dist-package/packages/runtime/src/audio/noise-reduction.d.ts +34 -0
  92. package/dist-package/packages/runtime/src/capabilities.d.ts +45 -0
  93. package/dist-package/packages/runtime/src/color-correction.d.ts +33 -0
  94. package/dist-package/packages/runtime/src/context/context-engine.d.ts +28 -0
  95. package/dist-package/packages/runtime/src/context/context-service.d.ts +20 -0
  96. package/dist-package/packages/runtime/src/context/project-catalog.d.ts +12 -0
  97. package/dist-package/packages/runtime/src/context/revision.d.ts +2 -0
  98. package/dist-package/packages/runtime/src/domain/capabilities.d.ts +170 -0
  99. package/dist-package/packages/runtime/src/domain/context.d.ts +179 -0
  100. package/dist-package/packages/runtime/src/domain/diff.d.ts +104 -0
  101. package/dist-package/packages/runtime/src/domain/duration.d.ts +63 -0
  102. package/dist-package/packages/runtime/src/domain/editing.d.ts +227 -0
  103. package/dist-package/packages/runtime/src/domain/incremental-sync.d.ts +67 -0
  104. package/dist-package/packages/runtime/src/domain/index.d.ts +14 -0
  105. package/dist-package/packages/runtime/src/domain/media.d.ts +406 -0
  106. package/dist-package/packages/runtime/src/domain/ports.d.ts +62 -0
  107. package/dist-package/packages/runtime/src/domain/primitives.d.ts +21 -0
  108. package/dist-package/packages/runtime/src/domain/project.d.ts +119 -0
  109. package/dist-package/packages/runtime/src/domain/rough-cut.d.ts +27 -0
  110. package/dist-package/packages/runtime/src/domain/skills.d.ts +145 -0
  111. package/dist-package/packages/runtime/src/domain/timeline-target.d.ts +57 -0
  112. package/dist-package/packages/runtime/src/domain/timeline-target.js +19 -1
  113. package/dist-package/packages/runtime/src/domain/types.d.ts +5 -0
  114. package/dist-package/packages/runtime/src/domain/verification.d.ts +92 -0
  115. package/dist-package/packages/runtime/src/editing/dialogue-normalization-service.d.ts +18 -0
  116. package/dist-package/packages/runtime/src/editing/duration-policy.d.ts +3 -0
  117. package/dist-package/packages/runtime/src/editing/edit-service.d.ts +44 -0
  118. package/dist-package/packages/runtime/src/editing/filler-removal-service.d.ts +23 -0
  119. package/dist-package/packages/runtime/src/editing/intent.d.ts +97 -0
  120. package/dist-package/packages/runtime/src/editing/music-service.d.ts +9 -0
  121. package/dist-package/packages/runtime/src/index.d.ts +32 -0
  122. package/dist-package/packages/runtime/src/index.js +1 -0
  123. package/dist-package/packages/runtime/src/planning/rough-cut.d.ts +3 -0
  124. package/dist-package/packages/runtime/src/render/render-and-verify.d.ts +71 -0
  125. package/dist-package/packages/runtime/src/render/render-contract.d.ts +96 -0
  126. package/dist-package/packages/runtime/src/runtime.d.ts +85 -0
  127. package/dist-package/packages/runtime/src/skills/builtin.d.ts +2 -0
  128. package/dist-package/packages/runtime/src/skills/index.d.ts +3 -0
  129. package/dist-package/packages/runtime/src/skills/registry.d.ts +10 -0
  130. package/dist-package/packages/runtime/src/skills/requirements.d.ts +38 -0
  131. package/dist-package/packages/runtime/src/skills/runtime.d.ts +38 -0
  132. package/dist-package/packages/runtime/src/speech/analysis.d.ts +18 -0
  133. package/dist-package/packages/runtime/src/speech/analysis.js +67 -0
  134. package/dist-package/packages/runtime/src/speech/filler-detector.d.ts +49 -0
  135. package/dist-package/packages/runtime/src/speech/filler-removal.d.ts +37 -0
  136. package/dist-package/packages/runtime/src/speech/mapping.d.ts +56 -0
  137. package/dist-package/packages/runtime/src/speech/mapping.js +27 -4
  138. package/dist-package/packages/runtime/src/speech/safe-cut-resolver.d.ts +52 -0
  139. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.d.ts +42 -0
  140. package/dist-package/packages/runtime/src/timeline/editing-session.d.ts +271 -0
  141. package/dist-package/packages/runtime/src/timeline/editing-session.js +32 -2
  142. package/dist-package/packages/runtime/src/timeline/fast-observation.d.ts +77 -0
  143. package/dist-package/packages/runtime/src/timeline/rational-time.d.ts +11 -0
  144. package/dist-package/packages/runtime/src/timeline/reorder-preview.d.ts +32 -0
  145. package/dist-package/packages/runtime/src/timeline/reorder-preview.js +202 -0
  146. package/dist-package/packages/runtime/src/timeline/snapshot-diff.d.ts +3 -0
  147. package/dist-package/packages/runtime/src/timeline/snapshot-diff.js +1 -0
  148. package/dist-package/packages/runtime/src/timeline/snapshot-digest.d.ts +3 -0
  149. package/dist-package/packages/runtime/src/timeline/snapshot-digest.js +1 -1
  150. package/dist-package/packages/runtime/src/verification/verification.d.ts +6 -0
  151. package/dist-package/packages/testkit/src/fixture-analyzers.d.ts +37 -0
  152. package/dist-package/packages/testkit/src/in-memory-editor.d.ts +55 -0
  153. package/dist-package/packages/testkit/src/index.d.ts +4 -0
  154. package/dist-package/packages/testkit/src/sender-lifecycle-fixture.d.ts +47 -0
  155. package/dist-package/packages/testkit/src/skill-fixtures.d.ts +3 -0
  156. package/package.json +17 -12
@@ -0,0 +1,56 @@
1
+ import type { ContextRevision } from "../domain/primitives.js";
2
+ import { type TimelineIr } from "../timeline/editing-session.js";
3
+ export declare const FRAMEKIT_PROJECT_SCHEMA_VERSION: 1;
4
+ export interface FramekitProjectMetadata {
5
+ createdAt: string;
6
+ updatedAt: string;
7
+ }
8
+ /** The persisted envelope owns metadata; the Timeline IR remains the canonical model. */
9
+ export interface FramekitProjectDocument {
10
+ schemaVersion: typeof FRAMEKIT_PROJECT_SCHEMA_VERSION;
11
+ metadata: FramekitProjectMetadata;
12
+ timeline: TimelineIr;
13
+ }
14
+ export interface ProjectStore {
15
+ create(project: FramekitProjectDocument): Promise<FramekitProjectDocument>;
16
+ load(): Promise<FramekitProjectDocument>;
17
+ save(project: FramekitProjectDocument, expectedRevision?: ContextRevision): Promise<FramekitProjectDocument>;
18
+ }
19
+ export interface ProjectStoreFileSystem {
20
+ mkdir(path: string, options: {
21
+ recursive: true;
22
+ }): Promise<void>;
23
+ readFile(path: string, encoding: "utf8"): Promise<string>;
24
+ writeFile(path: string, data: string, options: {
25
+ encoding: "utf8";
26
+ flag: "wx";
27
+ }): Promise<void>;
28
+ link(from: string, to: string): Promise<void>;
29
+ rename(from: string, to: string): Promise<void>;
30
+ unlink(path: string): Promise<void>;
31
+ }
32
+ export type ProjectPersistenceErrorCode = "PROJECT_NOT_FOUND" | "PROJECT_ALREADY_EXISTS" | "PROJECT_INVALID" | "PROJECT_CORRUPT" | "PROJECT_SCHEMA_UNSUPPORTED" | "PROJECT_STALE_REVISION" | "PROJECT_SAVE_FAILED";
33
+ export declare class ProjectPersistenceError extends Error {
34
+ readonly code: ProjectPersistenceErrorCode;
35
+ readonly details?: Readonly<Record<string, unknown>>;
36
+ constructor(code: ProjectPersistenceErrorCode, message: string, details?: Readonly<Record<string, unknown>>, options?: ErrorOptions);
37
+ }
38
+ export interface FramekitProjectMigration {
39
+ fromSchemaVersion: number;
40
+ toSchemaVersion: number;
41
+ migrate(input: unknown): unknown;
42
+ }
43
+ export declare class FramekitProjectStore implements ProjectStore {
44
+ private readonly path;
45
+ private readonly fs;
46
+ constructor(path: string, fs?: ProjectStoreFileSystem);
47
+ create(project: FramekitProjectDocument): Promise<FramekitProjectDocument>;
48
+ load(): Promise<FramekitProjectDocument>;
49
+ save(project: FramekitProjectDocument, expectedRevision?: ContextRevision): Promise<FramekitProjectDocument>;
50
+ private saveUnlocked;
51
+ private withProjectLock;
52
+ private removeTemporaryFile;
53
+ }
54
+ export declare function encodeFramekitProject(project: FramekitProjectDocument): string;
55
+ export declare function decodeFramekitProject(input: string | unknown): FramekitProjectDocument;
56
+ export declare function validateFramekitProject(project: FramekitProjectDocument): void;
@@ -0,0 +1,51 @@
1
+ import type { ContextRevision } from "../domain/primitives.js";
2
+ import { type TimelineIrEditOperation } from "../timeline/editing-session.js";
3
+ import { type FramekitProjectDocument, type ProjectStore } from "./project-store.js";
4
+ export declare const PROJECT_EDIT_COMMAND_SCHEMA_VERSION: 1;
5
+ export interface ProjectEditCommand {
6
+ schemaVersion: typeof PROJECT_EDIT_COMMAND_SCHEMA_VERSION;
7
+ target: {
8
+ projectId: string;
9
+ sequenceId: string;
10
+ };
11
+ expectedRevision: ContextRevision;
12
+ operations: TimelineIrEditOperation[];
13
+ }
14
+ export interface ProjectEditDiff {
15
+ beforeDigest: string;
16
+ afterDigest: string;
17
+ operations: TimelineIrEditOperation[];
18
+ changedOccurrenceIds: string[];
19
+ changedMarkerIds: string[];
20
+ changedTitleIds: string[];
21
+ changedTransitionIds: string[];
22
+ }
23
+ export interface ProjectEditPreview {
24
+ command: ProjectEditCommand;
25
+ before: FramekitProjectDocument;
26
+ after: FramekitProjectDocument;
27
+ diff: ProjectEditDiff;
28
+ changedOccurrenceIds: string[];
29
+ changedMarkerIds: string[];
30
+ changedTitleIds: string[];
31
+ changedTransitionIds: string[];
32
+ }
33
+ export interface ProjectEditResult extends ProjectEditPreview {
34
+ committed: true;
35
+ }
36
+ export declare class ProjectTransactionError extends Error {
37
+ readonly code: "PROJECT_EDIT_INVALID" | "PROJECT_EDIT_UNSUPPORTED" | "PROJECT_EDIT_STALE_REVISION" | "PROJECT_EDIT_TARGET_MISMATCH";
38
+ readonly details?: Readonly<Record<string, unknown>>;
39
+ constructor(code: ProjectTransactionError["code"], message: string, details?: Readonly<Record<string, unknown>>, options?: ErrorOptions);
40
+ }
41
+ export declare class ProjectTransactionService {
42
+ private readonly store;
43
+ private readonly clock;
44
+ constructor(store: ProjectStore, options?: {
45
+ clock?: () => string;
46
+ });
47
+ preview(command: ProjectEditCommand): Promise<ProjectEditPreview>;
48
+ execute(command: ProjectEditCommand): Promise<ProjectEditResult>;
49
+ private loadAndGuard;
50
+ private invalid;
51
+ }
@@ -0,0 +1,15 @@
1
+ import type { AudioAnalyzer, NoiseAnalyzer, MetadataAnalyzer, SpeechAnalyzer, VisualAnalyzer } from "../domain/media.js";
2
+ import type { VerificationEngine } from "../domain/verification.js";
3
+ import type { SemanticMediaIndexStore } from "./semantic-media-index-store.js";
4
+ export interface RuntimeOptions {
5
+ speechAnalyzer?: SpeechAnalyzer;
6
+ audioAnalyzer?: AudioAnalyzer;
7
+ noiseAnalyzer?: NoiseAnalyzer;
8
+ visualAnalyzer?: VisualAnalyzer;
9
+ metadataAnalyzer?: MetadataAnalyzer;
10
+ semanticMediaIndexStore?: SemanticMediaIndexStore;
11
+ verificationEngine?: VerificationEngine;
12
+ now?: () => number;
13
+ previewTtlMs?: number;
14
+ maxActivePreviews?: number;
15
+ }
@@ -0,0 +1,28 @@
1
+ import type { MediaSourceIdentity, MediaUnderstanding } from "../domain/media.js";
2
+ export declare const SEMANTIC_MEDIA_INDEX_SCHEMA_VERSION: 1;
3
+ export interface SemanticMediaIndexDocument {
4
+ schemaVersion: typeof SEMANTIC_MEDIA_INDEX_SCHEMA_VERSION;
5
+ entries: MediaUnderstanding[];
6
+ }
7
+ /** Persistent, provider-neutral source-media analysis storage. */
8
+ export interface SemanticMediaIndexStore {
9
+ load(source: MediaSourceIdentity): Promise<MediaUnderstanding | undefined>;
10
+ list(): Promise<MediaUnderstanding[]>;
11
+ save(understanding: MediaUnderstanding): Promise<void>;
12
+ }
13
+ /** Deterministic store for runtime and integration tests. */
14
+ export declare class InMemorySemanticMediaIndexStore implements SemanticMediaIndexStore {
15
+ private readonly entries;
16
+ load(source: MediaSourceIdentity): Promise<MediaUnderstanding | undefined>;
17
+ list(): Promise<MediaUnderstanding[]>;
18
+ save(understanding: MediaUnderstanding): Promise<void>;
19
+ }
20
+ /** Atomic JSON persistence for a local semantic media index. */
21
+ export declare class JsonSemanticMediaIndexStore implements SemanticMediaIndexStore {
22
+ private readonly path;
23
+ constructor(path: string);
24
+ load(source: MediaSourceIdentity): Promise<MediaUnderstanding | undefined>;
25
+ list(): Promise<MediaUnderstanding[]>;
26
+ save(understanding: MediaUnderstanding): Promise<void>;
27
+ private readDocument;
28
+ }
@@ -0,0 +1,10 @@
1
+ import type { EditTransaction } from "../domain/editing.js";
2
+ export interface TransactionStore {
3
+ set(transaction: EditTransaction): void;
4
+ get(transactionId: string): EditTransaction;
5
+ }
6
+ export declare class InMemoryTransactionStore implements TransactionStore {
7
+ private readonly transactions;
8
+ set(transaction: EditTransaction): void;
9
+ get(transactionId: string): EditTransaction;
10
+ }
@@ -0,0 +1,3 @@
1
+ /** Validate the measurement payload before binding provenance or serializing it. */
2
+ export declare function validateAudioAnalysisPayload(value: unknown): void;
3
+ export declare function validateAudioAnalysisRange(value: unknown, label: string): void;
@@ -0,0 +1,95 @@
1
+ import { parseRational } from "../timeline/rational-time.js";
2
+ /** Validate the measurement payload before binding provenance or serializing it. */
3
+ export function validateAudioAnalysisPayload(value) {
4
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
5
+ throw new Error("ANALYSIS_INVALID: audio analysis must be an object");
6
+ }
7
+ const analysis = value;
8
+ if (analysis.signalScope !== undefined && analysis.signalScope !== "source" && analysis.signalScope !== "occurrence") {
9
+ throw new Error("ANALYSIS_INVALID: unsupported audio signal scope");
10
+ }
11
+ if (analysis.signalScope === "occurrence"
12
+ && (typeof analysis.occurrenceId !== "string" || !analysis.occurrenceId.trim())) {
13
+ throw new Error("ANALYSIS_INVALID: occurrence audio requires an occurrence identity");
14
+ }
15
+ for (const field of ["integratedLufs", "truePeakDb", "silenceMs"]) {
16
+ const measured = analysis[field];
17
+ if (typeof measured !== "number" || !Number.isFinite(measured)) {
18
+ throw new Error(`ANALYSIS_INVALID: audio ${field} must be finite`);
19
+ }
20
+ }
21
+ if (analysis.silenceMs < 0) {
22
+ throw new Error("ANALYSIS_INVALID: audio silenceMs must be nonnegative");
23
+ }
24
+ if (analysis.analyzedDurationSeconds !== undefined
25
+ && (typeof analysis.analyzedDurationSeconds !== "number"
26
+ || !Number.isFinite(analysis.analyzedDurationSeconds) || analysis.analyzedDurationSeconds <= 0)) {
27
+ throw new Error("ANALYSIS_INVALID: audio analyzedDurationSeconds must be finite and positive");
28
+ }
29
+ if (analysis.audibleSamples !== undefined
30
+ && (typeof analysis.audibleSamples !== "number" || !Number.isSafeInteger(analysis.audibleSamples)
31
+ || analysis.audibleSamples < 0)) {
32
+ throw new Error("ANALYSIS_INVALID: audio audibleSamples must be a nonnegative safe integer");
33
+ }
34
+ for (const field of ["dialoguePresent", "valid"]) {
35
+ if (analysis[field] !== undefined && typeof analysis[field] !== "boolean") {
36
+ throw new Error(`ANALYSIS_INVALID: audio ${field} must be boolean`);
37
+ }
38
+ }
39
+ if (analysis.invalidReason !== undefined && typeof analysis.invalidReason !== "string") {
40
+ throw new Error("ANALYSIS_INVALID: audio invalidReason must be text");
41
+ }
42
+ if (analysis.sourceTimebase !== undefined)
43
+ rationalSeconds(analysis.sourceTimebase, "sourceTimebase");
44
+ for (const field of ["requestedRange", "measuredRange"]) {
45
+ if (analysis[field] !== undefined)
46
+ validateAudioAnalysisRange(analysis[field], field);
47
+ }
48
+ if (analysis.signalFormat !== undefined) {
49
+ const format = analysis.signalFormat;
50
+ if (!format || typeof format !== "object" || Array.isArray(format)) {
51
+ throw new Error("ANALYSIS_INVALID: audio signalFormat must be an object");
52
+ }
53
+ for (const field of ["sampleRate", "channels"]) {
54
+ const count = format[field];
55
+ if (typeof count !== "number" || !Number.isSafeInteger(count) || count <= 0) {
56
+ throw new Error(`ANALYSIS_INVALID: audio signalFormat ${field} must be a positive safe integer`);
57
+ }
58
+ }
59
+ const layout = format.channelLayout;
60
+ if (layout !== undefined && (typeof layout !== "string" || !layout.trim())) {
61
+ throw new Error("ANALYSIS_INVALID: audio channelLayout must be nonempty text");
62
+ }
63
+ }
64
+ }
65
+ function rationalSeconds(value, label, allowZero = false) {
66
+ if (!value || typeof value !== "object" || Array.isArray(value)
67
+ || typeof value.value !== "string"
68
+ || typeof value.timescale !== "string") {
69
+ throw new Error(`ANALYSIS_INVALID: audio ${label} must be a rational time`);
70
+ }
71
+ const parsed = parseRational(value, "ANALYSIS_INVALID");
72
+ const seconds = Number(parsed.value) / Number(parsed.timescale);
73
+ if (!Number.isFinite(seconds) || (allowZero ? seconds < 0 : seconds <= 0)) {
74
+ throw new Error(`ANALYSIS_INVALID: audio ${label} must be ${allowZero ? "nonnegative" : "positive"}`);
75
+ }
76
+ return seconds;
77
+ }
78
+ export function validateAudioAnalysisRange(value, label) {
79
+ if (!value || typeof value !== "object" || Array.isArray(value)) {
80
+ throw new Error(`ANALYSIS_INVALID: audio ${label} must be a range`);
81
+ }
82
+ const range = value;
83
+ if (typeof range.start !== "number" || typeof range.end !== "number"
84
+ || !Number.isFinite(range.start) || !Number.isFinite(range.end) || range.start < 0 || range.end <= range.start) {
85
+ throw new Error(`ANALYSIS_INVALID: audio ${label} must be finite and positive`);
86
+ }
87
+ if (range.startTime !== undefined
88
+ && Math.abs(rationalSeconds(range.startTime, label + " start", true) - range.start) > 0.000000001) {
89
+ throw new Error(`ANALYSIS_INVALID: audio ${label} numeric and rational start differ`);
90
+ }
91
+ if (range.durationTime !== undefined
92
+ && Math.abs(rationalSeconds(range.durationTime, label + " duration") - (range.end - range.start)) > 0.000000001) {
93
+ throw new Error(`ANALYSIS_INVALID: audio ${label} numeric and rational duration differ`);
94
+ }
95
+ }
@@ -0,0 +1,47 @@
1
+ import type { AudioMeasurement } from "../domain/media.js";
2
+ import type { ContextRevision } from "../domain/primitives.js";
3
+ import type { EditOperation } from "../domain/editing.js";
4
+ import type { TimelineDiff } from "../domain/diff.js";
5
+ export type DialogueGainDecision = "APPLY" | "NO_OP" | "SKIP";
6
+ export type DialogueGainReasonCode = "APPLY_GAIN" | "ALREADY_IN_TOLERANCE" | "MEASUREMENT_INVALID" | "NO_DIALOGUE" | "SILENCE" | "DIALOGUE_TOO_SHORT" | "GAIN_OUT_OF_BOUNDS" | "PEAK_RISK";
7
+ export interface DialogueGainPlanningOptions {
8
+ targetLufs: number;
9
+ toleranceDb: number;
10
+ maxTruePeakDb: number;
11
+ minGainDb: number;
12
+ maxGainDb: number;
13
+ minDialogueDurationSeconds: number;
14
+ }
15
+ export interface DialogueGainPlan extends DialogueGainPlanningOptions {
16
+ decision: DialogueGainDecision;
17
+ currentLufs: number;
18
+ desiredGainDb: number;
19
+ clampedGainDb: number;
20
+ estimatedPeakDb: number;
21
+ reasonCodes: DialogueGainReasonCode[];
22
+ }
23
+ export interface DialogueNormalizationRequest extends DialogueGainPlanningOptions {
24
+ mediaId: string;
25
+ occurrenceId: string;
26
+ baseRevision: ContextRevision;
27
+ }
28
+ export interface DialogueNormalizationPreview {
29
+ measurement: AudioMeasurement;
30
+ plan: DialogueGainPlan;
31
+ operations: EditOperation[];
32
+ expectedDiff?: TimelineDiff;
33
+ previewToken?: string;
34
+ warnings: string[];
35
+ expiresAt?: string;
36
+ }
37
+ /** Defaults for the version 1.0.0 dialogue-normalization Skill. */
38
+ export declare const DIALOGUE_NORMALIZATION_DEFAULTS: {
39
+ readonly targetLufs: -16;
40
+ readonly toleranceDb: 0.5;
41
+ readonly maxTruePeakDb: -1;
42
+ readonly minGainDb: -6;
43
+ readonly maxGainDb: 6;
44
+ readonly minDialogueDurationSeconds: 1;
45
+ };
46
+ /** Plan a bounded clip-level gain change without mutating an editor. */
47
+ export declare function planDialogueGain(measurement: AudioMeasurement, options: DialogueGainPlanningOptions): DialogueGainPlan;
@@ -0,0 +1,34 @@
1
+ import type { ContextRevision } from "../domain/primitives.js";
2
+ import type { EditOperation } from "../domain/editing.js";
3
+ import type { NoiseMeasurement } from "../domain/media.js";
4
+ import type { TimelineDiff } from "../domain/diff.js";
5
+ export type NoiseReductionDecision = "APPLY" | "NO_OP" | "SKIP";
6
+ export type NoiseReductionReasonCode = "APPLY_NOISE_REDUCTION" | "ALREADY_BELOW_THRESHOLD" | "MEASUREMENT_INVALID" | "NO_AFFECTED_RANGE" | "CONFIDENCE_TOO_LOW" | "REDUCTION_INVALID";
7
+ export interface NoiseReductionPlanningOptions {
8
+ noiseThresholdDb: number;
9
+ maxReductionDb: number;
10
+ minConfidence: number;
11
+ }
12
+ export interface NoiseReductionRequest extends NoiseReductionPlanningOptions {
13
+ mediaId: string;
14
+ occurrenceId: string;
15
+ baseRevision: ContextRevision;
16
+ }
17
+ export interface NoiseReductionPlan extends NoiseReductionPlanningOptions {
18
+ decision: NoiseReductionDecision;
19
+ noiseFloorDb: number;
20
+ recommendedReductionDb: number;
21
+ reductionDb: number;
22
+ affectedRanges: NoiseMeasurement["affectedRanges"];
23
+ reasonCodes: NoiseReductionReasonCode[];
24
+ }
25
+ export interface NoiseReductionPreview {
26
+ measurement: NoiseMeasurement;
27
+ plan: NoiseReductionPlan;
28
+ operations: EditOperation[];
29
+ expectedDiff?: TimelineDiff;
30
+ previewToken?: string;
31
+ warnings: string[];
32
+ expiresAt?: string;
33
+ }
34
+ export declare function planNoiseReduction(measurement: NoiseMeasurement, options: NoiseReductionPlanningOptions): NoiseReductionPlan;
@@ -0,0 +1,45 @@
1
+ import type { CapabilityDescriptor, CapabilityFamilies, EditingCapabilityOperation, EditorIdentity, NativeCapabilityOperation, ProjectSelectionMode, RuntimeCapabilities, VersionedRuntimeCapabilities } from "./domain/capabilities.js";
2
+ export type CanonicalTimelineMode = "metadata-only" | "canonical-read" | "canonical-write";
3
+ export type CapabilityProcessMode = "headless" | "headed";
4
+ export type CapabilityPreflightMode = "fixture" | "fcpxml-artifact" | "metadata-only" | "canonical-live" | "native-write";
5
+ export interface CapabilityPreflight {
6
+ mode: CapabilityPreflightMode;
7
+ documentMode: Exclude<CapabilityPreflightMode, "native-write">;
8
+ processMode: CapabilityProcessMode;
9
+ backend: string;
10
+ capabilities: CapabilityFamilies;
11
+ }
12
+ export declare function canonicalTimelineMode(capabilities: RuntimeCapabilities): CanonicalTimelineMode;
13
+ export declare function projectSelectionMode(editor: RuntimeCapabilities["editor"]): ProjectSelectionMode;
14
+ export declare function withCanonicalTimelineMode(capabilities: RuntimeCapabilities): RuntimeCapabilities;
15
+ export interface CapabilityFamilyOptions {
16
+ backend?: string;
17
+ connectionBackend?: string;
18
+ nativeBackend?: string;
19
+ publishingBackend?: string;
20
+ exportBackend?: string;
21
+ backgroundExportBackend?: string;
22
+ externalExportBackend?: string;
23
+ analyzerBackend?: string;
24
+ analyzerBackends?: Partial<Record<keyof CapabilityFamilies["analyzers"], string | undefined>>;
25
+ observation?: Partial<Record<keyof CapabilityFamilies["observation"], boolean | CapabilityDescriptor>>;
26
+ canonicalDocument?: Partial<Record<"read" | "write" | "artifactWrite", boolean | CapabilityDescriptor>>;
27
+ editing?: Partial<Record<EditingCapabilityOperation, boolean | CapabilityDescriptor>>;
28
+ editingBackend?: string;
29
+ connection?: boolean | CapabilityDescriptor;
30
+ native?: Partial<Record<NativeCapabilityOperation, boolean>>;
31
+ publishing?: boolean | CapabilityDescriptor;
32
+ publishingGuarantee?: Exclude<CapabilityDescriptor["guarantee"], "none">;
33
+ export?: boolean | CapabilityDescriptor;
34
+ backgroundExport?: boolean | CapabilityDescriptor;
35
+ externalExport?: boolean | CapabilityDescriptor;
36
+ }
37
+ /**
38
+ * Adds the versioned operation-level contract while retaining the legacy
39
+ * boolean fields used by existing runtime consumers.
40
+ */
41
+ export declare function withCapabilityFamilies(capabilities: RuntimeCapabilities, options?: CapabilityFamilyOptions): VersionedRuntimeCapabilities;
42
+ export declare function createCapabilityPreflight(identity: EditorIdentity, capabilities: RuntimeCapabilities, options?: {
43
+ processMode?: CapabilityProcessMode;
44
+ nativeWrite?: boolean;
45
+ }): CapabilityPreflight;
@@ -0,0 +1,33 @@
1
+ import type { ContextRevision } from "./domain/primitives.js";
2
+ import type { EditOperation } from "./domain/editing.js";
3
+ import type { Clip, ColorCorrection, ColorCorrectionPreset } from "./domain/project.js";
4
+ import type { TimelineDiff } from "./domain/diff.js";
5
+ export interface ColorCorrectionRequest {
6
+ clipId: string;
7
+ baseRevision: ContextRevision;
8
+ preset?: ColorCorrectionPreset;
9
+ exposure?: number;
10
+ contrast?: number;
11
+ saturation?: number;
12
+ temperature?: number;
13
+ tint?: number;
14
+ }
15
+ export interface ColorCorrectionPlan {
16
+ decision: "APPLY" | "NO_OP";
17
+ clipId: string;
18
+ before: ColorCorrection;
19
+ after: ColorCorrection;
20
+ changedFields: Array<keyof ColorCorrection>;
21
+ reasonCodes: Array<"APPLY_COLOR_CORRECTION" | "ALREADY_MATCHES">;
22
+ }
23
+ export interface ColorCorrectionPreview {
24
+ plan: ColorCorrectionPlan;
25
+ operation?: EditOperation;
26
+ expectedDiff?: TimelineDiff;
27
+ previewToken?: string;
28
+ warnings: string[];
29
+ expiresAt?: string;
30
+ }
31
+ export declare const COLOR_CORRECTION_PRESETS: Record<ColorCorrectionPreset, ColorCorrection>;
32
+ export declare function planColorCorrection(clip: Clip, request: ColorCorrectionRequest): ColorCorrectionPlan;
33
+ export declare function normalizeCorrection(correction?: ColorCorrection): ColorCorrection;
@@ -0,0 +1,28 @@
1
+ import type { AgentContext, ContextCursor, ContextDiff, TimelineChangesRequest, TimelineChangesResult } from "../domain/context.js";
2
+ import type { AssetSearchQuery, EditorPort } from "../domain/ports.js";
3
+ import type { ContextRevision } from "../domain/primitives.js";
4
+ import { type MediaUnderstanding } from "../domain/media.js";
5
+ import type { ProjectSnapshot } from "../domain/project.js";
6
+ import type { RuntimeCapabilities } from "../domain/capabilities.js";
7
+ import type { TimelineDiff } from "../domain/diff.js";
8
+ export declare class ContextEngine {
9
+ private readonly editor;
10
+ private readonly snapshots;
11
+ private readonly mediaUnderstanding;
12
+ constructor(editor: EditorPort);
13
+ inspectProject(): Promise<ProjectSnapshot>;
14
+ changesSince(revision: ContextRevision): Promise<TimelineDiff>;
15
+ timelineChangesSince(request: TimelineChangesRequest): Promise<TimelineChangesResult>;
16
+ contextChangesSince(cursorOrRevision: ContextCursor | ContextRevision, waitMs?: number): Promise<ContextDiff>;
17
+ private validateCursorTarget;
18
+ inspectContext(capabilities: RuntimeCapabilities, options?: {
19
+ includeCanonicalSnapshot?: boolean;
20
+ }): Promise<AgentContext>;
21
+ attachMediaUnderstanding(understanding: MediaUnderstanding): void;
22
+ private resolveTimelineChangesTarget;
23
+ listAssets(query?: AssetSearchQuery): Promise<import("../domain/ports.js").EditorAsset[]>;
24
+ private optionalTimelineChanges;
25
+ private liveChangesSince;
26
+ private optionalLiveState;
27
+ private withAttachedUnderstanding;
28
+ }
@@ -0,0 +1,20 @@
1
+ import type { AgentContext, ContextCursor, ContextDiff, EditorChange, EditorLiveState, TimelineChangesRequest, TimelineChangesResult } from "../domain/context.js";
2
+ import type { ContextRevision } from "../domain/primitives.js";
3
+ import type { EditorPort } from "../domain/ports.js";
4
+ import type { RuntimeCapabilities } from "../domain/capabilities.js";
5
+ import type { TimelineDiff } from "../domain/diff.js";
6
+ import { ContextEngine } from "./context-engine.js";
7
+ export declare class ContextService {
8
+ private readonly adapter;
9
+ private readonly context;
10
+ constructor(adapter: EditorPort, context: ContextEngine);
11
+ inspectContext(capabilities: RuntimeCapabilities, options?: {
12
+ includeCanonicalSnapshot?: boolean;
13
+ }): Promise<AgentContext>;
14
+ inspectLiveEditor(): Promise<EditorLiveState>;
15
+ liveChangesSince(revision: ContextRevision, waitMs?: number): Promise<EditorChange[]>;
16
+ changesSince(revision: ContextRevision): Promise<TimelineDiff>;
17
+ timelineChangesSince(request: TimelineChangesRequest): Promise<TimelineChangesResult>;
18
+ contextChangesSince(cursorOrRevision: ContextCursor | ContextRevision, waitMs?: number): Promise<ContextDiff>;
19
+ private liveAdapter;
20
+ }
@@ -0,0 +1,12 @@
1
+ import type { EditorLiveState, ProjectCatalog, ProjectCatalogLiveSource, ProjectCatalogProvenance } from "../domain/context.js";
2
+ export interface ProjectCatalogReconciliationOptions {
3
+ before?: EditorLiveState;
4
+ after?: EditorLiveState;
5
+ provenance: {
6
+ catalog: ProjectCatalogProvenance["catalog"];
7
+ live?: ProjectCatalogLiveSource;
8
+ selection: ProjectCatalogProvenance["selection"];
9
+ };
10
+ }
11
+ export declare function reconcileProjectCatalog(catalog: ProjectCatalog, options: ProjectCatalogReconciliationOptions): ProjectCatalog;
12
+ export declare function validateProjectCatalog(catalog: ProjectCatalog): void;
@@ -0,0 +1,2 @@
1
+ import type { ContextRevision } from "../domain/primitives.js";
2
+ export declare function sameRevision(left: ContextRevision, right: ContextRevision): boolean;