@hraness/slopcamera 3.2.4

package/apps/desktop/code/editing.ts

@@ -0,0 +1,284 @@
+import {
+  ManualProjectCameraMoveInputV2Schema,
+  ManualProjectZoomInputV3Schema,
+  type ManualProjectCameraMoveInputV2,
+  type ManualProjectZoomInputV3,
+  type OrderedProjectEditV2,
+  type OrderedProjectEditV3,
+} from "../application/operations/derive/edit-batch";
+import {
+  CameraPoseSchema,
+  type CameraPose,
+  type Easing,
+  type ProjectEditPlanV1,
+  type ProjectPlacementId,
+  type SourceInterval,
+  type ZoomOperation,
+  type ZoomTarget,
+} from "../contracts";
+import type { OperationInputValue } from "./contracts";
+
+type MetadataEffects = ProjectEditPlanV1["effects"];
+
+/** Binding-free manual move accepted by a checked v2 project commit. */
+export type ManualCameraMoveInput = ManualProjectCameraMoveInputV2;
+
+/** Binding-free manual zoom accepted by a checked v3 project commit. */
+export type ManualZoomInput = Omit<
+  ManualProjectZoomInputV3,
+  "displayId" | "placementId"
+> & {
+  readonly displayId?: string;
+  readonly placementId?: NonNullable<
+    ManualProjectZoomInputV3["placementId"]
+  >;
+};
+
+export type SetMetadataEffectsEdit = Extract<
+  OrderedProjectEditV2,
+  { readonly kind: "set-metadata-effects" }
+>;
+
+export type AddManualCameraMovesEdit = Extract<
+  OrderedProjectEditV2,
+  { readonly kind: "add-manual-camera-moves" }
+>;
+
+export type RemoveCameraMovesEdit = Extract<
+  OrderedProjectEditV2,
+  { readonly kind: "remove-camera-moves" }
+>;
+
+export type RemoveZoomsEdit = Extract<
+  OrderedProjectEditV2,
+  { readonly kind: "remove-zooms" }
+>;
+
+export type AddManualZoomsEdit = Extract<
+  OrderedProjectEditV3,
+  { readonly kind: "add-manual-zooms" }
+>;
+
+export interface MetadataEffectsOptions {
+  readonly clicks: OperationInputValue<MetadataEffects["clicks"]>;
+  readonly cursor: OperationInputValue<MetadataEffects["cursor"]>;
+  readonly keystrokes: OperationInputValue<MetadataEffects["keystrokes"]>;
+  readonly metadataPlacementId: OperationInputValue<ProjectPlacementId | null>;
+  readonly typedText: OperationInputValue<MetadataEffects["typedText"]>;
+}
+
+/**
+ * Replace the complete interaction-effect configuration in one explicit edit.
+ * Requiring every field prevents an agent from depending on hidden prior state.
+ */
+export function setMetadataEffects(
+  input: MetadataEffectsOptions,
+): OperationInputValue<SetMetadataEffectsEdit> {
+  return {
+    clicks: input.clicks,
+    cursor: input.cursor,
+    keystrokes: input.keystrokes,
+    kind: "set-metadata-effects",
+    metadataPlacementId: input.metadataPlacementId,
+    typedText: input.typedText,
+  };
+}
+
+/**
+ * Conservative screen-demo polish. Typed text stays off because capture is
+ * opt-in and secure-field suppression must never be weakened by a workflow.
+ */
+export function polishedInteractionEffects(
+  metadataPlacementId: OperationInputValue<ProjectPlacementId>,
+): OperationInputValue<SetMetadataEffectsEdit> {
+  return setMetadataEffects({
+    clicks: {
+      color: "#5B8CFF",
+      durationUs: 450_000,
+      enabled: true,
+      radiusPx: 28,
+      style: "ring",
+    },
+    cursor: {
+      enabled: true,
+      scale: 1.15,
+      smoothing: {
+        algorithm: "exponential",
+        strength: 0.42,
+      },
+      style: "captured",
+    },
+    keystrokes: {
+      enabled: true,
+      holdUs: 900_000,
+      maxKeys: 6,
+      position: "bottom-center",
+      secureText: "hide",
+    },
+    metadataPlacementId,
+    typedText: { enabled: false },
+  });
+}
+
+export function addManualCameraMoves(
+  cameraMoves: readonly OperationInputValue<ManualProjectCameraMoveInputV2>[],
+): OperationInputValue<AddManualCameraMovesEdit> {
+  return {
+    cameraMoves,
+    kind: "add-manual-camera-moves",
+  };
+}
+
+export function addManualZooms(
+  zooms: readonly (
+    | ManualZoomInput
+    | OperationInputValue<ManualProjectZoomInputV3>
+  )[],
+): OperationInputValue<AddManualZoomsEdit> {
+  return {
+    kind: "add-manual-zooms",
+    zooms,
+  };
+}
+
+export function removeCameraMoves(
+  cameraMoveIds: readonly OperationInputValue<
+    ManualProjectCameraMoveInputV2["cameraMoveId"]
+  >[],
+): OperationInputValue<RemoveCameraMovesEdit> {
+  return {
+    cameraMoveIds,
+    kind: "remove-camera-moves",
+  };
+}
+
+export function removeZooms(
+  zoomIds: readonly OperationInputValue<ZoomOperation["zoomId"]>[],
+): OperationInputValue<RemoveZoomsEdit> {
+  return {
+    kind: "remove-zooms",
+    zoomIds,
+  };
+}
+
+export interface ManualZoomOptions {
+  readonly displayId?: string;
+  readonly easing?: Easing;
+  readonly enterDurationUs?: number;
+  readonly exitDurationUs?: number;
+  readonly placementId?: string;
+  readonly range: SourceInterval;
+  readonly scale: number;
+  readonly target: ZoomTarget;
+  readonly zoomId: string;
+}
+
+/**
+ * Construct binding-free manual zoom intent. The host selects omitted
+ * placement/display identities and binds the exact recording manifest and
+ * placement synchronization during v3 commit planning.
+ */
+export function manualZoom(
+  input: ManualZoomOptions,
+): ManualZoomInput {
+  const durationUs = input.range.endUs - input.range.startUs;
+  const defaultTransitionUs = Math.min(
+    300_000,
+    Math.max(0, Math.floor(durationUs / 2)),
+  );
+  const parsed = ManualProjectZoomInputV3Schema.parse({
+    ...input,
+    easing: input.easing ?? { kind: "ease-in-out" },
+    enterDurationUs: input.enterDurationUs ?? defaultTransitionUs,
+    exitDurationUs: input.exitDurationUs ?? defaultTransitionUs,
+  });
+  return {
+    easing: parsed.easing,
+    enterDurationUs: parsed.enterDurationUs,
+    exitDurationUs: parsed.exitDurationUs,
+    range: parsed.range,
+    scale: parsed.scale,
+    target: parsed.target,
+    zoomId: parsed.zoomId,
+    ...(parsed.displayId === undefined
+      ? {}
+      : { displayId: parsed.displayId }),
+    ...(parsed.placementId === undefined
+      ? {}
+      : { placementId: parsed.placementId }),
+  };
+}
+
+export interface PreparedCameraPoseInput {
+  readonly centerX: number;
+  readonly centerY: number;
+  readonly zoom: number;
+}
+
+export function preparedCameraPose(
+  input: PreparedCameraPoseInput,
+): CameraPose {
+  return CameraPoseSchema.parse({
+    ...input,
+    space: "prepared-video-layer-normalized-v1",
+  });
+}
+
+export interface CameraReframeOptions extends Omit<
+  ManualProjectCameraMoveInputV2,
+  "cameraMoveId" | "keyframes" | "placementId" | "streamId"
+> {
+  readonly cameraMoveId: string;
+  readonly easing?: Easing;
+  readonly from: PreparedCameraPoseInput;
+  readonly placementId: string;
+  readonly streamId: string;
+  readonly to: PreparedCameraPoseInput;
+}
+
+/**
+ * Construct a binding-free manual camera move with exact endpoint keyframes.
+ * The checked commit binds it to the current placement synchronization and
+ * prepared-layer geometry.
+ */
+export function cameraReframe(
+  input: CameraReframeOptions,
+): ManualProjectCameraMoveInputV2 {
+  const easing = input.easing ?? { kind: "ease-in-out" };
+  return ManualProjectCameraMoveInputV2Schema.parse({
+    cameraMoveId: input.cameraMoveId,
+    keyframes: [
+      {
+        outgoingEasing: easing,
+        pose: preparedCameraPose(input.from),
+        projectTimeUs: input.projectRange.startUs,
+      },
+      {
+        outgoingEasing: { kind: "linear" },
+        pose: preparedCameraPose(input.to),
+        projectTimeUs: input.projectRange.endUs,
+      },
+    ],
+    placementId: input.placementId,
+    projectRange: input.projectRange,
+    streamId: input.streamId,
+  });
+}
+
+export interface CameraPushOptions extends Omit<CameraReframeOptions, "from"> {
+  readonly from?: PreparedCameraPoseInput;
+}
+
+/**
+ * Construct the common two-keyframe push-in move. Use cameraReframe when the
+ * endpoint may zoom out or only pan.
+ */
+export function cameraPush(
+  input: CameraPushOptions,
+): ManualProjectCameraMoveInputV2 {
+  const from = input.from ?? { centerX: 0.5, centerY: 0.5, zoom: 1 };
+  if (input.to.zoom <= from.zoom) {
+    throw new RangeError("A camera push must increase zoom from its first pose.");
+  }
+  return cameraReframe({ ...input, from });
+}

package/apps/desktop/code/file-candidate-provenance.ts

@@ -0,0 +1,420 @@
+import { ApplicationError } from "../application/errors";
+import {
+  canonicalJson,
+  sha256Hex,
+} from "../core/canonical-json";
+import {
+  isOperationGraphNode,
+  type AuthoredWorkflowGraphV1,
+  type CandidateDescriptor,
+  type GraphInputValue,
+  type JsonValue,
+} from "./contracts";
+import type { NodeExecutionPlanningRequest } from "./scheduler";
+import {
+  WorkflowFileCandidateSchema,
+  type WorkflowFileCandidate,
+} from "./file-candidate";
+
+const FILE_CANDIDATE_DOMAIN = "studio.workflow.file-candidate/v1";
+
+interface FileClaim {
+  readonly bytes?: number;
+  readonly mediaType?: string;
+  readonly path: string;
+  readonly sha256?: string;
+}
+
+function record(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function reference(value: unknown): boolean {
+  return record(value) && Object.hasOwn(value, "$ref");
+}
+
+function field(value: unknown, key: string): unknown {
+  return record(value) ? value[key] : undefined;
+}
+
+function claim(value: unknown): FileClaim | undefined {
+  if (!record(value) || reference(value) || typeof value.path !== "string") {
+    return undefined;
+  }
+  return {
+    ...(typeof value.bytes === "number" ? { bytes: value.bytes } : {}),
+    ...(typeof value.mediaType === "string"
+      ? { mediaType: value.mediaType }
+      : {}),
+    path: value.path,
+    ...(typeof value.sha256 === "string" ? { sha256: value.sha256 } : {}),
+  };
+}
+
+function array(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function optionalClaim(value: unknown): readonly FileClaim[] {
+  const parsed = claim(value);
+  return parsed === undefined ? [] : [parsed];
+}
+
+function optionalPathClaim(value: unknown): readonly FileClaim[] {
+  if (typeof value === "string") return [{ path: value }];
+  return optionalClaim(value);
+}
+
+/**
+ * Returns only fields whose operation contract grants local-file authority.
+ * Other path-looking values (for example output destinations) are excluded.
+ */
+export function operationFileClaims(
+  operation: string,
+  input: GraphInputValue | JsonValue,
+): readonly FileClaim[] {
+  if (!record(input)) return [];
+  if (operation === "slopcamera.studio.run") return optionalClaim(field(input, "bundle"));
+  if (operation === "scene.render") {
+    return [
+      ...optionalClaim(field(input, "source")),
+      ...array(field(input, "assets")).flatMap(asset => optionalClaim(field(asset, "artifact"))),
+    ];
+  }
+  if (operation === "media.ingest") {
+    return optionalClaim(Reflect.get(input, "source"));
+  }
+  if (operation === "media.overlay") {
+    const source = field(input, "source");
+    return record(source)
+      ? optionalClaim(field(source, "artifact"))
+      : [];
+  }
+  if (operation === "media.html-overlay") {
+    return [
+      ...optionalClaim(field(input, "document")),
+      ...array(field(input, "resources")).flatMap((resource) => (
+        record(resource)
+          ? optionalClaim(field(resource, "artifact"))
+          : []
+      )),
+    ];
+  }
+  if (
+    operation === "media.audio-effects"
+    || operation === "media.color-grade"
+  ) {
+    return optionalClaim(Reflect.get(input, "input"));
+  }
+  if (
+    operation === "slopcamera.diagram.check"
+    || operation === "slopcamera.diagram.render"
+  ) {
+    return optionalPathClaim(Reflect.get(input, "path"));
+  }
+  if (operation === "slopcamera.image.vectorize") {
+    return optionalPathClaim(Reflect.get(input, "inputPath"));
+  }
+  if (operation === "gateway.image") {
+    return [
+      ...array(Reflect.get(input, "images")).flatMap(
+        value => claim(value) ?? [],
+      ),
+      ...optionalClaim(Reflect.get(input, "mask")),
+    ];
+  }
+  if (operation === "gateway.video") {
+    const frames = array(Reflect.get(input, "frames")).flatMap((value) => {
+      if (!record(value)) return [];
+      return optionalClaim(value.source);
+    });
+    return [
+      ...frames,
+      ...optionalClaim(Reflect.get(input, "promptImage")),
+      ...array(Reflect.get(input, "references")).flatMap(
+        value => claim(value) ?? [],
+      ),
+    ];
+  }
+  if (operation === "gateway.transcription") {
+    return optionalClaim(Reflect.get(input, "audio"));
+  }
+  return [];
+}
+
+function descriptorBody(
+  input: Omit<CandidateDescriptor, "descriptorSha256">,
+): Omit<CandidateDescriptor, "descriptorSha256"> {
+  return {
+    ...(input.bytes === undefined ? {} : { bytes: input.bytes }),
+    id: input.id,
+    kind: input.kind,
+    ...(input.mediaType === undefined ? {} : { mediaType: input.mediaType }),
+    ...(input.sha256 === undefined ? {} : { sha256: input.sha256 }),
+  };
+}
+
+export function fileCandidateDescriptor(
+  input: Omit<CandidateDescriptor, "descriptorSha256">,
+): CandidateDescriptor {
+  const body = descriptorBody(input);
+  return {
+    ...body,
+    descriptorSha256: sha256Hex(
+      `${FILE_CANDIDATE_DOMAIN}\0${canonicalJson(body)}`,
+    ),
+  };
+}
+
+function assertDescriptorIntegrity(candidate: CandidateDescriptor): void {
+  const expected = fileCandidateDescriptor(descriptorBody(candidate));
+  if (candidate.descriptorSha256 !== expected.descriptorSha256) {
+    throw new ApplicationError(
+      "invalid-data",
+      `Static file candidate ${candidate.id} has an invalid descriptor digest.`,
+    );
+  }
+}
+
+export function collectLiteralFileCandidates(
+  graph: AuthoredWorkflowGraphV1,
+): readonly CandidateDescriptor[] {
+  const claims = new Map<string, FileClaim>();
+  for (const node of graph.nodes) {
+    if (!isOperationGraphNode(node)) continue;
+    const operation = node.executor.operation.kind;
+    for (const authored of operationFileClaims(operation, node.input)) {
+      const existing = claims.get(authored.path);
+      if (
+        existing !== undefined
+        && (
+          (
+            existing.bytes !== undefined
+            && authored.bytes !== undefined
+            && existing.bytes !== authored.bytes
+          )
+          || (
+            existing.sha256 !== undefined
+            && authored.sha256 !== undefined
+            && existing.sha256 !== authored.sha256
+          )
+          || (
+            existing.mediaType !== undefined
+            && authored.mediaType !== undefined
+            && existing.mediaType !== authored.mediaType
+          )
+        )
+      ) {
+        throw new ApplicationError(
+          "conflict",
+          `File candidate ${authored.path} was authored with conflicting descriptors.`,
+        );
+      }
+      claims.set(authored.path, {
+        ...(existing?.bytes ?? authored.bytes) === undefined
+          ? {}
+          : { bytes: existing?.bytes ?? authored.bytes },
+        ...(existing?.mediaType ?? authored.mediaType) === undefined
+          ? {}
+          : { mediaType: existing?.mediaType ?? authored.mediaType },
+        path: authored.path,
+        ...(existing?.sha256 ?? authored.sha256) === undefined
+          ? {}
+          : { sha256: existing?.sha256 ?? authored.sha256 },
+      });
+    }
+  }
+  return [...claims.values()]
+    .map(candidate => fileCandidateDescriptor({
+      ...(candidate.bytes === undefined ? {} : { bytes: candidate.bytes }),
+      id: candidate.path,
+      kind: "file",
+      ...(candidate.mediaType === undefined
+        ? {}
+        : { mediaType: candidate.mediaType }),
+      ...(candidate.sha256 === undefined ? {} : { sha256: candidate.sha256 }),
+    }))
+    .sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function declaredCandidate(
+  declaration: WorkflowFileCandidate,
+): CandidateDescriptor {
+  return fileCandidateDescriptor({
+    ...(declaration.bytes === undefined ? {} : { bytes: declaration.bytes }),
+    id: declaration.path,
+    kind: "file",
+    ...(declaration.mediaType === undefined
+      ? {}
+      : { mediaType: declaration.mediaType }),
+    ...(declaration.sha256 === undefined
+      ? {}
+      : { sha256: declaration.sha256 }),
+  });
+}
+
+export function collectDeclaredFileCandidates(
+  value: unknown,
+): readonly CandidateDescriptor[] {
+  if (Array.isArray(value)) return value.flatMap(collectDeclaredFileCandidates);
+  if (!record(value)) return [];
+  if (
+    Reflect.get(value, "kind") === "file"
+    && Reflect.get(value, "version") === "slopcamera-workflow-file-candidate-v1"
+  ) {
+    return [declaredCandidate(WorkflowFileCandidateSchema.parse(value))];
+  }
+  return Object.values(value).flatMap(collectDeclaredFileCandidates);
+}
+
+export function mergeFileCandidateDescriptors(
+  groups: readonly (readonly CandidateDescriptor[])[],
+): readonly CandidateDescriptor[] {
+  const merged = new Map<string, FileClaim>();
+  for (const candidate of groups.flat()) {
+    if (candidate.kind !== "file") continue;
+    assertDescriptorIntegrity(candidate);
+    const existing = merged.get(candidate.id);
+    const next: FileClaim = {
+      ...(candidate.bytes === undefined ? {} : { bytes: candidate.bytes }),
+      ...(candidate.mediaType === undefined
+        ? {}
+        : { mediaType: candidate.mediaType }),
+      path: candidate.id,
+      ...(candidate.sha256 === undefined ? {} : { sha256: candidate.sha256 }),
+    };
+    if (
+      existing !== undefined
+      && (
+        (
+          existing.bytes !== undefined
+          && next.bytes !== undefined
+          && existing.bytes !== next.bytes
+        )
+        || (
+          existing.sha256 !== undefined
+          && next.sha256 !== undefined
+          && existing.sha256 !== next.sha256
+        )
+        || (
+          existing.mediaType !== undefined
+          && next.mediaType !== undefined
+          && existing.mediaType !== next.mediaType
+        )
+      )
+    ) {
+      throw new ApplicationError(
+        "conflict",
+        `File candidate ${candidate.id} was declared with conflicting descriptors.`,
+      );
+    }
+    merged.set(candidate.id, {
+      ...(existing?.bytes ?? next.bytes) === undefined
+        ? {}
+        : { bytes: existing?.bytes ?? next.bytes },
+      ...(existing?.mediaType ?? next.mediaType) === undefined
+        ? {}
+        : { mediaType: existing?.mediaType ?? next.mediaType },
+      path: candidate.id,
+      ...(existing?.sha256 ?? next.sha256) === undefined
+        ? {}
+        : { sha256: existing?.sha256 ?? next.sha256 },
+    });
+  }
+  return [...merged.values()]
+    .map(candidate => fileCandidateDescriptor({
+      ...(candidate.bytes === undefined ? {} : { bytes: candidate.bytes }),
+      id: candidate.path,
+      kind: "file",
+      ...(candidate.mediaType === undefined
+        ? {}
+        : { mediaType: candidate.mediaType }),
+      ...(candidate.sha256 === undefined ? {} : { sha256: candidate.sha256 }),
+    }))
+    .sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function exactClaimMatches(left: FileClaim, right: FileClaim): boolean {
+  return left.path === right.path
+    && (left.bytes === undefined || left.bytes === right.bytes)
+    && (left.sha256 === undefined || left.sha256 === right.sha256)
+    && (left.mediaType === undefined || left.mediaType === right.mediaType);
+}
+
+function candidateMatches(
+  requested: FileClaim,
+  candidate: CandidateDescriptor,
+): boolean {
+  return requested.path === candidate.id
+    && (candidate.bytes === undefined || candidate.bytes === requested.bytes)
+    && (
+      candidate.sha256 === undefined
+      || candidate.sha256 === requested.sha256
+    )
+    && (
+      candidate.mediaType === undefined
+      || candidate.mediaType === requested.mediaType
+    );
+}
+
+function collectExactClaims(value: unknown): readonly FileClaim[] {
+  if (Array.isArray(value)) return value.flatMap(collectExactClaims);
+  if (!record(value)) return [];
+  const direct = claim(value);
+  const nested = Object.values(value).flatMap(collectExactClaims);
+  if (
+    direct === undefined
+    || direct.bytes === undefined
+    || direct.sha256 === undefined
+  ) {
+    return nested;
+  }
+  return [direct, ...nested];
+}
+
+function hostDependencyClaims(
+  request: NodeExecutionPlanningRequest,
+): readonly FileClaim[] {
+  const nodes = new Map(
+    request.graphPlan.graph.nodes.map(node => [node.key, node]),
+  );
+  return Object.entries(request.dependencyOutputs).flatMap(
+    ([nodeKey, output]) => {
+      const node = nodes.get(nodeKey);
+      return node !== undefined && isOperationGraphNode(node)
+        ? collectExactClaims(output.value)
+        : [];
+    },
+  );
+}
+
+export function assertOperationFileProvenance(
+  request: NodeExecutionPlanningRequest,
+): void {
+  const claims = operationFileClaims(
+    request.operation.kind,
+    request.resolvedInput,
+  );
+  if (claims.length === 0) return;
+  const candidates = request.graphPlan.staticBindings.candidates.filter(
+    candidate => candidate.kind === "file",
+  );
+  for (const candidate of candidates) assertDescriptorIntegrity(candidate);
+  const hostClaims = hostDependencyClaims(request);
+  for (const requested of claims) {
+    const authorizedByPlan = candidates.some(candidate =>
+      candidateMatches(requested, candidate));
+    const authorizedByHost = hostClaims.some(candidate =>
+      exactClaimMatches(requested, candidate));
+    if (!authorizedByPlan && !authorizedByHost) {
+      throw new ApplicationError(
+        "authorization-required",
+        `Node ${request.node.key} received undeclared local media: ${requested.path}`,
+        {
+          operation: request.operation.kind,
+          path: requested.path,
+        },
+      );
+    }
+  }
+}