@hraness/slopcamera 3.2.4

package/apps/desktop/contracts/spatial-project.ts

@@ -0,0 +1,159 @@
+import { z } from "zod";
+
+import {
+  SpatialDigestSchema,
+  SpatialSceneV1Schema,
+  SpatialShotIdSchema,
+  SpatialShotV1Schema,
+} from "../../../src/spatial-scene/contracts";
+import { RepositoryRelativePathSchema } from "./recording";
+import { ProjectEditPlanV1Schema, VideoProjectIdSchema, VideoProjectV1Schema } from "./project";
+
+export const SPATIAL_PROJECT_LIMITS = Object.freeze({
+  documentBytes: 32 * 1024 * 1024,
+  totalSceneBytes: 128 * 1024 * 1024,
+  scenes: 128,
+  shots: 1_024,
+  candidates: 1_024,
+  payloadBytes: 256 * 1024 * 1024,
+});
+export const SpatialTransactionIdSchema = z.string().regex(/^transaction_[a-f0-9]{32}$/u);
+export const SpatialProjectBasisSchema = z.strictObject({
+  version: z.union([z.literal(1), z.literal(2)]),
+  sha256: SpatialDigestSchema,
+});
+export const SpatialProjectArtifactSchema = z.strictObject({
+  path: z.string().regex(/^spatial\/(?:scenes|revisions|attempts|receipts)\/[a-f0-9]{64}\.json$/u),
+  sha256: SpatialDigestSchema,
+  bytes: z.number().int().positive().max(SPATIAL_PROJECT_LIMITS.documentBytes),
+}).superRefine((artifact, context) => {
+  if (!artifact.path.endsWith(`/${artifact.sha256}.json`)) {
+    context.addIssue({ code: "custom", message: "Artifact path must name its exact byte digest." });
+  }
+});
+export const SpatialSceneReferenceSchema = z.strictObject({
+  sceneSha256: SpatialDigestSchema,
+  artifact: SpatialProjectArtifactSchema.refine(value => value.path.startsWith("spatial/scenes/")),
+});
+/** These are frozen V1 values. Migration never rewrites their identity or hash domain. */
+export const SpatialProjectLegacySchema = z.strictObject({
+  project: VideoProjectV1Schema,
+  projectEditPlan: ProjectEditPlanV1Schema,
+});
+export const SpatialCandidateIdSchema = z.string().regex(/^candidate_[a-zA-Z0-9_-]{1,128}$/u);
+export const SpatialCandidateSchema = z.strictObject({
+  candidateId: SpatialCandidateIdSchema,
+  derivation: z.strictObject({
+    shotId: SpatialShotIdSchema,
+    shotSha256: SpatialDigestSchema,
+    sceneSha256: SpatialDigestSchema,
+    recipeSha256: SpatialDigestSchema,
+  }),
+  outputs: z.array(z.strictObject({
+    path: RepositoryRelativePathSchema.refine(path => /^spatial\/outputs\/[a-f0-9]{64}\.[a-z0-9]{1,8}$/u.test(path), "Candidate outputs must be content-addressed spatial artifacts."),
+    sha256: SpatialDigestSchema,
+    bytes: z.number().int().positive().max(SPATIAL_PROJECT_LIMITS.payloadBytes),
+  }).superRefine((output, context) => {
+    if (!output.path.startsWith(`spatial/outputs/${output.sha256}.`)) context.addIssue({ code: "custom", message: "Candidate path must name its payload digest." });
+  })).min(1).max(16),
+});
+export const SpatialCandidateSelectionSchema = z.strictObject({
+  shotId: SpatialShotIdSchema,
+  candidateId: SpatialCandidateIdSchema,
+});
+export const SpatialProjectRevisionV2Schema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-project-revision"),
+  schemaVersion: z.literal(2),
+  projectId: VideoProjectIdSchema,
+  parent: SpatialProjectBasisSchema,
+  transactionId: SpatialTransactionIdSchema,
+  legacy: SpatialProjectLegacySchema,
+  scenes: z.array(SpatialSceneReferenceSchema).max(SPATIAL_PROJECT_LIMITS.scenes),
+  shots: z.array(SpatialShotV1Schema).max(SPATIAL_PROJECT_LIMITS.shots),
+  candidates: z.array(SpatialCandidateSchema).max(SPATIAL_PROJECT_LIMITS.candidates),
+  selections: z.array(SpatialCandidateSelectionSchema).max(SPATIAL_PROJECT_LIMITS.shots),
+}).superRefine((revision, context) => {
+  if (revision.projectId !== revision.legacy.project.projectId
+    || revision.projectId !== revision.legacy.projectEditPlan.projectId) {
+    context.addIssue({ code: "custom", message: "Frozen media and spatial project identities must match." });
+  }
+  for (const ids of [revision.scenes.map(value => value.sceneSha256), revision.shots.map(value => value.shotId),
+    revision.candidates.map(value => value.candidateId), revision.selections.map(value => value.shotId)]) {
+    if (new Set(ids).size !== ids.length) context.addIssue({ code: "custom", message: "Duplicate project identity." });
+  }
+  if (revision.scenes.reduce((total, scene) => total + scene.artifact.bytes, 0) > SPATIAL_PROJECT_LIMITS.totalSceneBytes) {
+    context.addIssue({ code: "custom", message: "Project scene byte budget exceeded." });
+  }
+  for (const shot of revision.shots) {
+    if (!revision.scenes.some(scene => scene.sceneSha256 === shot.sceneSha256)) context.addIssue({ code: "custom", message: "Shot references an absent scene." });
+    if (shot.range.endUs > revision.legacy.project.timeline.durationUs) context.addIssue({ code: "custom", message: "Shot exceeds the project clock." });
+  }
+  for (const candidate of revision.candidates) {
+    if (!revision.scenes.some(scene => scene.sceneSha256 === candidate.derivation.sceneSha256)
+      || !revision.shots.some(shot => shot.shotId === candidate.derivation.shotId)) {
+      context.addIssue({ code: "custom", message: "Candidate derivation is not retained in this project." });
+    }
+  }
+  for (const selection of revision.selections) {
+    if (!revision.shots.some(shot => shot.shotId === selection.shotId)
+      || !revision.candidates.some(candidate => candidate.candidateId === selection.candidateId
+        && candidate.derivation.shotId === selection.shotId)) {
+      context.addIssue({ code: "custom", message: "Selection must bind a candidate for its exact shot." });
+    }
+  }
+});
+export const SpatialProjectHeadV2Schema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-project-head"),
+  schemaVersion: z.literal(2),
+  projectId: VideoProjectIdSchema,
+  projectRevisionSha256: SpatialDigestSchema,
+  revision: SpatialProjectArtifactSchema.refine(value => value.path.startsWith("spatial/revisions/")),
+  transactionId: SpatialTransactionIdSchema,
+});
+export const SpatialProjectAttemptV1Schema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-project-attempt"),
+  schemaVersion: z.literal(1),
+  beforeHeadSha256: SpatialDigestSchema,
+  expected: SpatialProjectBasisSchema,
+  after: SpatialProjectHeadV2Schema,
+});
+export const SpatialProjectSettlementV1Schema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-project-settlement"),
+  schemaVersion: z.literal(1),
+  attempt: SpatialProjectArtifactSchema.refine(value => value.path.startsWith("spatial/attempts/")),
+  headSha256: SpatialDigestSchema,
+});
+export const SpatialProjectSceneSourceSchema = z.strictObject({
+  sceneSha256: SpatialDigestSchema,
+  document: SpatialSceneV1Schema,
+});
+export const SpatialShotRetargetSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("all") }),
+  z.strictObject({ kind: z.literal("shots"), shotIds: z.array(SpatialShotIdSchema).min(1).max(SPATIAL_PROJECT_LIMITS.shots) }),
+]);
+export const SpatialProjectSceneDiffSchema = z.strictObject({
+  beforeSceneSha256: z.string().regex(/^[a-f0-9]{64}$/u),
+  afterSceneSha256: z.string().regex(/^[a-f0-9]{64}$/u),
+  affectedShotIds: z.array(SpatialShotIdSchema).max(SPATIAL_PROJECT_LIMITS.shots),
+  untouchedShotIds: z.array(SpatialShotIdSchema).max(SPATIAL_PROJECT_LIMITS.shots),
+  selectedCandidates: z.array(SpatialCandidateSelectionSchema.extend({ status: z.enum(["current", "stale"]) })).max(SPATIAL_PROJECT_LIMITS.shots),
+});
+/** Publication evidence is shared with run receipts and browser consumers. */
+export const SpatialProjectMutationOutputSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ projectId: VideoProjectIdSchema, kind: z.literal("completed"), attempt: SpatialProjectArtifactSchema, settlement: SpatialProjectArtifactSchema.refine(value => value.path.startsWith("spatial/receipts/")), projectRevisionSha256: z.string().regex(/^[a-f0-9]{64}$/u), currentHeadMatches: z.boolean(), diff: SpatialProjectSceneDiffSchema.optional() }),
+  z.strictObject({ projectId: VideoProjectIdSchema, kind: z.literal("conflict"), message: z.string().max(65_536), attempt: SpatialProjectArtifactSchema.optional() }),
+  z.strictObject({ projectId: VideoProjectIdSchema, kind: z.literal("precommit"), message: z.string().max(65_536), attempt: SpatialProjectArtifactSchema.optional() }),
+  z.strictObject({ projectId: VideoProjectIdSchema, kind: z.literal("ambiguous"), message: z.string().max(65_536), attempt: SpatialProjectArtifactSchema }),
+]);
+
+type SpatialReadonly<T> = T extends string | number | boolean | null | undefined | bigint | symbol
+  ? T : T extends object ? { readonly [Key in keyof T]: SpatialReadonly<T[Key]> } : T;
+export type SpatialProjectArtifact = SpatialReadonly<z.infer<typeof SpatialProjectArtifactSchema>>;
+export type SpatialProjectBasis = SpatialReadonly<z.infer<typeof SpatialProjectBasisSchema>>;
+export type SpatialProjectHeadV2 = SpatialReadonly<z.infer<typeof SpatialProjectHeadV2Schema>>;
+export type SpatialProjectRevisionV2 = SpatialReadonly<z.infer<typeof SpatialProjectRevisionV2Schema>>;
+export type SpatialProjectLegacy = SpatialReadonly<z.infer<typeof SpatialProjectLegacySchema>>;
+export type SpatialProjectSceneSource = SpatialReadonly<z.infer<typeof SpatialProjectSceneSourceSchema>>;
+export type SpatialCandidate = SpatialReadonly<z.infer<typeof SpatialCandidateSchema>>;
+export type SpatialShotRetarget = SpatialReadonly<z.infer<typeof SpatialShotRetargetSchema>>;
+export type SpatialProjectMutationOutput = z.infer<typeof SpatialProjectMutationOutputSchema>;

package/apps/desktop/contracts/spatial-world.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+
+import { createBoundedJsonSnapshot } from "../../../src/code/json-snapshot";
+import { SpatialAssetIdSchema, SpatialAssetManifestSchema, SpatialDigestSchema, SpatialEntityIdSchema, SpatialEntitySchema, SpatialPayloadSchema, SpatialTransformSchema } from "../../../src/spatial-scene/contracts";
+
+export const SPATIAL_SPLAT_LIMITS = Object.freeze({ splats: 500_000, sourceBytes: 128 * 1024 * 1024, decompressedBytes: 64 * 1024 * 1024, gpuBytes: 256 * 1024 * 1024, hostBytes: 768 * 1024 * 1024, metadataBytes: 1024 * 1024 });
+export function spatialSpzAllocationBounds(splats: number, sourceBytes: number, decompressedBytes: number) {
+  // Spark 2.1.0 utils.getTextureSize rounds rows to 2048; use a larger 65536 block.
+  // Ext source+SH: 32+64 B/splat; three accumulator MRT sets: 3*(16+16+4);
+  // ordering/readback buffers fit the remaining 52 B/splat. Browser/driver overhead
+  // is not a claim of resident process memory. LoD/paging/raycast are disabled.
+  const rounded = Math.ceil(splats / 65_536) * 65_536;
+  return { gpuBytesBound: rounded * 256, hostBytesBound: 128 * 1024 * 1024 + rounded * 512 + sourceBytes * 3 + decompressedBytes * 2 };
+}
+export const SpatialSpzFactsSchema = z.strictObject({
+  kind: z.literal("slopcamera.spz-admission"), schemaVersion: z.literal(1), version: z.union([z.literal(2), z.literal(3)]),
+  splats: z.number().int().min(1).max(SPATIAL_SPLAT_LIMITS.splats), shDegree: z.number().int().min(0).max(3), fractionalBits: z.number().int().min(0).max(24),
+  antialiased: z.literal(false), decompressedBytes: z.number().int().min(16).max(SPATIAL_SPLAT_LIMITS.decompressedBytes),
+  gpuBytesBound: z.number().int().min(1).max(SPATIAL_SPLAT_LIMITS.gpuBytes), hostBytesBound: z.number().int().min(1).max(SPATIAL_SPLAT_LIMITS.hostBytes),
+}).refine(value => value.decompressedBytes === 16 + value.splats * (19 + (value.version === 3 ? 1 : 0) + 3 * ((value.shDegree + 1) ** 2 - 1)), "SPZ body size must match the exact admitted attribute layout.");
+export type SpatialSpzFacts = Readonly<z.infer<typeof SpatialSpzFactsSchema>>;
+
+const normalizationSchema = z.strictObject({
+  metersPerUnit: z.number().finite().min(0.000001).max(1_000_000),
+  // Applied to decoded SPZ coordinates. Spark 2.1.0's SPZ decoder reads XYZ
+  // directly, without the format conversion sometimes used for PLY/OpenCV.
+  sourceUp: z.enum(["x", "y", "z"]), sourceHandedness: z.literal("right"),
+  transform: SpatialTransformSchema.refine(value => value.scale[0] === value.scale[1] && value.scale[1] === value.scale[2], "The initial splat profile requires a uniform authored scale."),
+});
+const identitiesSchema = z.strictObject({ assetId: SpatialAssetIdSchema, colliderAssetId: SpatialAssetIdSchema.optional(), entityId: SpatialEntityIdSchema, name: z.string().min(1).max(256) })
+  .refine(value => value.assetId !== value.colliderAssetId, "World and collider assets need distinct identities.");
+const provenanceSchema = z.strictObject({ kind: z.enum(["saved", "worldlabs-marble"]), description: z.string().min(1).max(2048), worldId: z.string().min(1).max(256).optional(), receipt: SpatialPayloadSchema.optional() })
+  .refine(value => value.kind !== "worldlabs-marble" || (value.worldId !== undefined && value.receipt !== undefined), "Generated Marble provenance requires its exact world ID and retained provider receipt.");
+const importSchema = z.strictObject({ splat: SpatialPayloadSchema, collider: SpatialPayloadSchema.optional(), identities: identitiesSchema, normalization: normalizationSchema, provenance: provenanceSchema })
+  .refine(value => (value.collider === undefined) === (value.identities.colliderAssetId === undefined), "Collider bytes and colliderAssetId must be supplied together.")
+  .refine(value => value.provenance.kind !== "worldlabs-marble" || value.collider !== undefined, "Generated Marble provenance requires its retained collider.");
+export const SavedSpatialWorldImportInputSchema = z.preprocess(value => createBoundedJsonSnapshot(value, SPATIAL_SPLAT_LIMITS.metadataBytes, "Saved world import", { maximumDepth: 16, maximumValues: 4096 }).value, importSchema);
+export type SavedSpatialWorldImportInput = Readonly<z.infer<typeof SavedSpatialWorldImportInputSchema>>;
+export const SpatialWorldImportManifestSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-world-import"), schemaVersion: z.literal(1),
+  splat: z.strictObject({ payload: SpatialPayloadSchema, facts: SpatialSpzFactsSchema }),
+  collider: z.strictObject({ payload: SpatialPayloadSchema, role: z.literal("approximate-collider"), validation: z.literal("bounded-glb-structure-only") }).nullable(),
+  identities: identitiesSchema, normalization: normalizationSchema, provenance: provenanceSchema,
+  capabilities: z.strictObject({ beauty: z.literal(true), semanticIds: z.literal("authored-wrapper-only"), depth: z.literal("unsupported"), objectId: z.literal("unsupported"), physics: z.enum(["unvalidated", "unavailable"]) }),
+}).refine(value => (value.collider === null) === (value.identities.colliderAssetId === undefined) && value.capabilities.physics === (value.collider === null ? "unavailable" : "unvalidated"), "Collider presence and capability evidence must agree.");
+export type SpatialWorldImportManifest = Readonly<z.infer<typeof SpatialWorldImportManifestSchema>>;
+export const SavedSpatialWorldImportOutputSchema = z.strictObject({ manifest: SpatialWorldImportManifestSchema, manifestArtifact: SpatialPayloadSchema, assets: z.array(SpatialAssetManifestSchema).min(2).max(4), entity: SpatialEntitySchema, manifestSha256: SpatialDigestSchema });
+export type SavedSpatialWorldImportOutput = Readonly<z.infer<typeof SavedSpatialWorldImportOutputSchema>>;

package/apps/desktop/contracts/video-effects.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+
+import { ColorGradeSelectionSchema } from "./media-effects";
+import type { DeepReadonly, ReadonlyInferred } from "./recording";
+
+export const VIDEO_LOOK_PRESETS = [
+  "blue-16mm",
+  "warm-super-8",
+  "photocopy",
+  "soft-vhs",
+] as const;
+
+export const ERROR_DIFFUSION_DITHER_ALGORITHMS = [
+  "atkinson",
+  "floyd-steinberg",
+] as const;
+
+const UnitIntervalSchema = z.number().finite().min(0).max(1);
+const CanonicalRgbHexSchema = z.string()
+  .regex(/^#[0-9a-fA-F]{6}$/u, "Expected a six-digit RGB hex color.")
+  .transform(value => value.toLocaleLowerCase("en-US"));
+
+export const VideoLookPresetSchema = z.enum(VIDEO_LOOK_PRESETS);
+
+export const VideoLookPresetOptionsSchema = z.strictObject({
+  intensity: UnitIntervalSchema.default(1),
+  seed: z.number().int().safe().nonnegative().max(2_147_483_647).default(19_840_123),
+});
+
+export const ColorGradeVideoEffectSchema = z.strictObject({
+  amount: UnitIntervalSchema.default(1),
+  grade: ColorGradeSelectionSchema,
+  kind: z.literal("color-grade"),
+});
+
+export const DuotoneVideoEffectSchema = z.strictObject({
+  amount: UnitIntervalSchema.default(1),
+  highlights: CanonicalRgbHexSchema,
+  kind: z.literal("duotone"),
+  shadows: CanonicalRgbHexSchema,
+});
+
+export const DiffusionVideoEffectSchema = z.strictObject({
+  amount: UnitIntervalSchema.default(0.15),
+  blendMode: z.enum(["screen", "soft-light"]).default("screen"),
+  kind: z.literal("diffusion"),
+  radiusPx: z.number().finite().min(0.25).max(64).default(4),
+});
+
+export const FilmGrainVideoEffectSchema = z.strictObject({
+  amount: UnitIntervalSchema.default(0.25),
+  cadence: z.enum(["fixed", "frame-varying"]).default("frame-varying"),
+  chroma: UnitIntervalSchema.default(0.15),
+  kind: z.literal("film-grain"),
+  seed: z.number().int().safe().nonnegative().max(2_147_483_647),
+});
+
+export const VignetteVideoEffectSchema = z.strictObject({
+  amount: UnitIntervalSchema.default(0.2),
+  center: z.strictObject({
+    xUnit: UnitIntervalSchema.default(0.5),
+    yUnit: UnitIntervalSchema.default(0.5),
+  }).default({ xUnit: 0.5, yUnit: 0.5 }),
+  kind: z.literal("vignette"),
+});
+
+export const ScanlinesVideoEffectSchema = z.strictObject({
+  amount: UnitIntervalSchema.default(0.15),
+  kind: z.literal("scanlines"),
+  spacingPx: z.number().int().safe().min(4).max(64).default(4),
+  thicknessPx: z.number().int().safe().min(1).max(3).default(1),
+});
+
+export const OrderedDitherVideoEffectSchema = z.strictObject({
+  amount: UnitIntervalSchema.default(1),
+  bayerScale: z.number().int().safe().min(0).max(5).default(2),
+  colors: z.number().int().safe().min(2).max(256).default(16),
+  kind: z.literal("ordered-dither"),
+  matrix: z.literal("bayer-8x8").default("bayer-8x8"),
+});
+
+export const ErrorDiffusionDitherVideoEffectSchema = z.strictObject({
+  algorithm: z.enum(ERROR_DIFFUSION_DITHER_ALGORITHMS).default("floyd-steinberg"),
+  amount: UnitIntervalSchema.default(1),
+  colors: z.number().int().safe().min(2).max(256).default(16),
+  kind: z.literal("error-diffusion-dither"),
+});
+
+/**
+ * These are artistic, display-referred effects. Codec/output dithering remains
+ * a separate renderer concern so an aesthetic dither cannot accidentally be
+ * treated as a bit-depth conversion policy.
+ */
+export const VideoEffectSchema = z.discriminatedUnion("kind", [
+  ColorGradeVideoEffectSchema,
+  DuotoneVideoEffectSchema,
+  DiffusionVideoEffectSchema,
+  FilmGrainVideoEffectSchema,
+  VignetteVideoEffectSchema,
+  ScanlinesVideoEffectSchema,
+  OrderedDitherVideoEffectSchema,
+  ErrorDiffusionDitherVideoEffectSchema,
+]);
+
+export const VideoLookV1Schema = z.strictObject({
+  effects: z.array(VideoEffectSchema).min(1).max(16),
+  kind: z.union([
+    z.literal("slopcamera.video-look"),
+    z.literal("studio.video-look"),
+  ]),
+  processingColorSpace: z.literal("bt709-display").default("bt709-display"),
+  schemaVersion: z.literal(1),
+});
+
+export type VideoEffect = ReadonlyInferred<typeof VideoEffectSchema>;
+export type VideoEffectInput = DeepReadonly<z.input<typeof VideoEffectSchema>>;
+export type VideoLookPreset = ReadonlyInferred<typeof VideoLookPresetSchema>;
+export type VideoLookPresetOptions = ReadonlyInferred<typeof VideoLookPresetOptionsSchema>;
+export type VideoLookPresetOptionsInput = DeepReadonly<z.input<typeof VideoLookPresetOptionsSchema>>;
+export type VideoLookV1 = ReadonlyInferred<typeof VideoLookV1Schema>;