feat: mix and match session document schema

Author: BrandonPacewic

fission/src/mix-and-match/MixAndMatchDocument.ts

@@ -0,0 +1,147 @@
+import type { mirabuf } from "@/proto/mirabuf"
+import {
+    createEmptySession,
+    MIX_AND_MATCH_SESSION_VERSION,
+    MIX_AND_MATCH_USER_DATA_KEY,
+    type MixAndMatchComponent,
+    type MixAndMatchSession,
+    type TimelineEntry,
+    type TransformArray,
+} from "./MixAndMatchTypes"
+
+/**
+ * Reads and writes the session document to `Parts.user_data["mixAndMatchSession"]` as a JSON string.
+ *
+ * A typed proto message is deliberately not used here: the map field is forward compatible, so a
+ * mira carrying this key is still an ordinary robot to every other consumer.
+ */
+
+const TRANSFORM_LENGTH = 16
+
+function isTransform(value: unknown): value is TransformArray {
+    return Array.isArray(value) && value.length === TRANSFORM_LENGTH && value.every(x => typeof x === "number")
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value != null && !Array.isArray(value)
+}
+
+function parseEntry(value: unknown): TimelineEntry | undefined {
+    if (!isRecord(value)) return undefined
+
+    switch (value.type) {
+        case "spawn":
+            return typeof value.componentId === "string" &&
+                typeof value.libraryPartRef === "string" &&
+                isTransform(value.transform)
+                ? {
+                      type: "spawn",
+                      componentId: value.componentId,
+                      libraryPartRef: value.libraryPartRef,
+                      transform: [...value.transform],
+                  }
+                : undefined
+        case "move":
+            return typeof value.componentId === "string" && isTransform(value.transform)
+                ? { type: "move", componentId: value.componentId, transform: [...value.transform] }
+                : undefined
+        case "weld":
+            return typeof value.componentA === "string" &&
+                typeof value.componentB === "string" &&
+                isTransform(value.relativeOffset)
+                ? {
+                      type: "weld",
+                      componentA: value.componentA,
+                      componentB: value.componentB,
+                      relativeOffset: [...value.relativeOffset],
+                  }
+                : undefined
+        case "resize":
+            return typeof value.componentId === "string" && typeof value.sizeOption === "string"
+                ? { type: "resize", componentId: value.componentId, sizeOption: value.sizeOption }
+                : undefined
+        case "delete":
+            return typeof value.componentId === "string"
+                ? { type: "delete", componentId: value.componentId }
+                : undefined
+        default:
+            return undefined
+    }
+}
+
+function parseComponent(value: unknown): MixAndMatchComponent | undefined {
+    if (!isRecord(value)) return undefined
+    if (typeof value.id !== "string" || typeof value.libraryPartRef !== "string") return undefined
+
+    return { id: value.id, libraryPartRef: value.libraryPartRef }
+}
+
+export function serializeSession(session: MixAndMatchSession): string {
+    return JSON.stringify(session)
+}
+
+/**
+ * Parses a serialized session, dropping anything malformed rather than throwing. A partially
+ * readable document is more useful than none: the user can still see and fix their build.
+ *
+ * @param   json    Raw JSON previously written by {@link serializeSession}.
+ * @returns The session, or undefined if the document isn't a mix-and-match session of a known version.
+ */
+export function parseSession(json: string): MixAndMatchSession | undefined {
+    let raw: unknown
+    try {
+        raw = JSON.parse(json)
+    } catch (e) {
+        console.warn("Malformed mix-and-match session", e)
+        return undefined
+    }
+
+    if (!isRecord(raw)) return undefined
+    if (raw.version !== MIX_AND_MATCH_SESSION_VERSION) {
+        console.warn(`Unsupported mix-and-match session version: ${raw.version}`)
+        return undefined
+    }
+
+    const session = createEmptySession()
+    if (Array.isArray(raw.components)) {
+        raw.components.forEach(x => {
+            const component = parseComponent(x)
+            if (component) session.components.push(component)
+        })
+    }
+    if (Array.isArray(raw.timeline)) {
+        raw.timeline.forEach(x => {
+            const entry = parseEntry(x)
+            if (entry) session.timeline.push(entry)
+        })
+    }
+
+    return session
+}
+
+export function hasMixAndMatchSession(assembly: mirabuf.IAssembly): boolean {
+    return assembly.data?.parts?.userData?.data?.[MIX_AND_MATCH_USER_DATA_KEY] != null
+}
+
+export function readSessionFromAssembly(assembly: mirabuf.IAssembly): MixAndMatchSession | undefined {
+    const raw = assembly.data?.parts?.userData?.data?.[MIX_AND_MATCH_USER_DATA_KEY]
+    return raw == null ? undefined : parseSession(raw)
+}
+
+/**
+ * Stamps the session onto an assembly's part user data. Mutates `assembly` in place, creating the
+ * `userData` map if the exporter left it off.
+ */
+export function writeSessionToAssembly(assembly: mirabuf.IAssembly, session: MixAndMatchSession): boolean {
+    const parts = assembly.data?.parts
+    if (!parts) {
+        console.warn("Cannot write mix-and-match session: assembly has no parts")
+        return false
+    }
+
+    parts.userData ??= { data: {} }
+    parts.userData.data ??= {}
+    parts.userData.data[MIX_AND_MATCH_USER_DATA_KEY] = serializeSession(session)
+
+    return true
+}

fission/src/mix-and-match/MixAndMatchTypes.ts

@@ -0,0 +1,82 @@
+/**
+ * Document schema for a mix-and-match build session.
+ *
+ * The timeline is the source of truth, not the derived weld graph. Re-entering build mode replays
+ * every entry in order to restore the exact state as of the last "OK", rather than reconstructing an
+ * equivalent-looking arrangement.
+ */
+
+/** Key under `Parts.user_data` that the serialized session lives at. Same field `urdfImport` uses. */
+export const MIX_AND_MATCH_USER_DATA_KEY = "mixAndMatchSession"
+
+export const MIX_AND_MATCH_SESSION_VERSION = 1
+
+/** Identifies one placed component within a session. Unique per session, not globally. */
+export type ComponentId = string
+
+/** Points at the library part a component was spawned from. Hash key into `MirabufCachingService`. */
+export type LibraryPartRef = string
+
+/** Column-major 4x4, matching `convertThreeMatrix4ToArray` / `convertArrayToThreeMatrix4`. */
+export type TransformArray = number[]
+
+export interface MixAndMatchComponent {
+    id: ComponentId
+    libraryPartRef: LibraryPartRef
+}
+
+/** A part was added to the build. `transform` is the world transform of its root body. */
+export interface SpawnTimelineEntry {
+    type: "spawn"
+    componentId: ComponentId
+    libraryPartRef: LibraryPartRef
+    transform: TransformArray
+}
+
+/** A part was repositioned. `transform` is absolute, not a delta, so replay never accumulates error. */
+export interface MoveTimelineEntry {
+    type: "move"
+    componentId: ComponentId
+    transform: TransformArray
+}
+
+/**
+ * `componentB` was welded onto `componentA`; B is the child. A component has at most one active weld,
+ * so a later weld naming the same B replaces this one.
+ */
+export interface WeldTimelineEntry {
+    type: "weld"
+    componentA: ComponentId
+    componentB: ComponentId
+    relativeOffset: TransformArray
+}
+
+export interface ResizeTimelineEntry {
+    type: "resize"
+    componentId: ComponentId
+    sizeOption: string
+}
+
+export interface DeleteTimelineEntry {
+    type: "delete"
+    componentId: ComponentId
+}
+
+export type TimelineEntry =
+    | SpawnTimelineEntry
+    | MoveTimelineEntry
+    | WeldTimelineEntry
+    | ResizeTimelineEntry
+    | DeleteTimelineEntry
+
+export type TimelineEntryType = TimelineEntry["type"]
+
+export interface MixAndMatchSession {
+    version: typeof MIX_AND_MATCH_SESSION_VERSION
+    components: MixAndMatchComponent[]
+    timeline: TimelineEntry[]
+}
+
+export function createEmptySession(): MixAndMatchSession {
+    return { version: MIX_AND_MATCH_SESSION_VERSION, components: [], timeline: [] }
+}

fission/src/test/mix-and-match/MixAndMatchDocument.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "vitest"
+import {
+    hasMixAndMatchSession,
+    parseSession,
+    readSessionFromAssembly,
+    serializeSession,
+    writeSessionToAssembly,
+} from "@/mix-and-match/MixAndMatchDocument"
+import { createEmptySession, type MixAndMatchSession } from "@/mix-and-match/MixAndMatchTypes"
+import { mirabuf } from "@/proto/mirabuf"
+
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+const SHIFTED = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 2, 0, 3, 1]
+
+function sampleSession(): MixAndMatchSession {
+    const session = createEmptySession()
+    session.components.push({ id: "c1", libraryPartRef: "hash-frame" }, { id: "c2", libraryPartRef: "hash-pod" })
+    session.timeline.push(
+        { type: "spawn", componentId: "c1", libraryPartRef: "hash-frame", transform: IDENTITY },
+        { type: "spawn", componentId: "c2", libraryPartRef: "hash-pod", transform: SHIFTED },
+        { type: "move", componentId: "c2", transform: SHIFTED },
+        { type: "weld", componentA: "c1", componentB: "c2", relativeOffset: SHIFTED },
+        { type: "resize", componentId: "c1", sizeOption: "28x28" },
+        { type: "delete", componentId: "c2" }
+    )
+
+    return session
+}
+
+function emptyAssembly(): mirabuf.Assembly {
+    return mirabuf.Assembly.create({ data: mirabuf.AssemblyData.create({ parts: mirabuf.Parts.create({}) }) })
+}
+
+describe("Mix and Match Document", () => {
+    test("Round Trips Every Entry Type", () => {
+        const original = sampleSession()
+        const parsed = parseSession(serializeSession(original))
+
+        expect(parsed).toEqual(original)
+    })
+
+    test("Rejects Unknown Version", () => {
+        expect(parseSession(JSON.stringify({ version: 99, components: [], timeline: [] }))).toBeUndefined()
+    })
+
+    test("Rejects Malformed JSON", () => {
+        expect(parseSession("{ not json")).toBeUndefined()
+    })
+
+    test("Drops Malformed Entries Instead Of Failing", () => {
+        const parsed = parseSession(
+            JSON.stringify({
+                version: 1,
+                components: [{ id: "c1", libraryPartRef: "hash" }, { id: 7 }],
+                timeline: [
+                    { type: "spawn", componentId: "c1", libraryPartRef: "hash", transform: IDENTITY },
+                    { type: "spawn", componentId: "c2", libraryPartRef: "hash", transform: [1, 2, 3] },
+                    { type: "not-a-real-type", componentId: "c1" },
+                    { type: "delete", componentId: "c1" },
+                ],
+            })
+        )
+
+        expect(parsed?.components).toHaveLength(1)
+        expect(parsed?.timeline.map(x => x.type)).toEqual(["spawn", "delete"])
+    })
+
+    test("Writes And Reads Back Through Part User Data", () => {
+        const assembly = emptyAssembly()
+        expect(hasMixAndMatchSession(assembly)).toBe(false)
+
+        const session = sampleSession()
+        expect(writeSessionToAssembly(assembly, session)).toBe(true)
+        expect(hasMixAndMatchSession(assembly)).toBe(true)
+        expect(readSessionFromAssembly(assembly)).toEqual(session)
+    })
+
+    test("Survives A Protobuf Encode And Decode", () => {
+        const assembly = emptyAssembly()
+        const session = sampleSession()
+        writeSessionToAssembly(assembly, session)
+
+        const decoded = mirabuf.Assembly.decode(mirabuf.Assembly.encode(assembly).finish())
+
+        expect(readSessionFromAssembly(decoded)).toEqual(session)
+    })
+
+    test("Reports No Session On An Ordinary Assembly", () => {
+        const assembly = emptyAssembly()
+        assembly.data!.parts!.userData = mirabuf.UserData.create({ data: { urdfImport: "true" } })
+
+        expect(hasMixAndMatchSession(assembly)).toBe(false)
+        expect(readSessionFromAssembly(assembly)).toBeUndefined()
+    })
+})