rework: theater zones and establish big wip dir

Author: chase-moskal

README.md

@@ -21,70 +21,74 @@ The theater coordinates your rendering thread and displays the results onto a ca
 
 The theater is split into two main parts. Each will live in its own separate bundle.
 - *The Frontstage* hosts the visible canvas in the dom. It doesn't import Babylon, and will be lean in filesize.
-- *The Backstage* run inside a web worker, and performs rendering work. It imports Babylon, and will be fat in filesize.
+- *The Backstage* runs inside a web worker, and performs rendering work. It imports Babylon, and will be fat in filesize.
 
 ### Theater project setup
 1. Write your `spec.ts` type, which describes your renderable world
     ```ts
+    import {AsFigmentSpec} from "@benev/marduk/x/theater/index.pure.js"
+
     export type MySpec = AsFigmentSpec<{
 
-      // Describe all the renderable objects in your world,
+      // Describe a renderable object in your world,
       // in terms of serializable data.
       hippo: {hungry: boolean}
     }>
     ```
+    - notice the specific locations from where we're importing things
 1. Establish your `backstage.ts` module (this will be a web worker)
     ```ts
     import {MySpec} from "./spec.js"
-    import {theaterWorker, babylonBackstage} from "@benev/marduk/x/theater/index.back.babylon.js"
+    import {babylonBackstage, theaterWorker} from "@benev/marduk/x/theater/index.babylon.js"
 
     void async function() {
-      await theaterWorker(
-        await babylonBackstage<MySpec>(async stagecraft => ({
-
-          // now we define a renderer for this object
-          hippo: (id, data) => {
-            console.log("spawn", id, data)
-            return {
-              update: data => console.log("update", id, data),
-              dispose: () => console.log("dispose", id, data),
-            }
-          },
-        }))
-      )
+
+      // defining a babylon backstage
+      // (you could make a backstage for a different kind of renderer)
+      const backstage = await babylonBackstage<MySpec>(async stagecraft => ({
+
+        // now we define a renderer for this object
+        hippo: (id, data) => {
+          console.log("spawn", id, data)
+          return {
+            update: data => console.log("update", id, data),
+            dispose: () => console.log("dispose", id, data),
+          }
+        },
+      }))
+
+      // establishing the web worker
+      await theaterWorker(backstage)
     }()
     ```
     - now bundle this module as `backstage.bundle.js` using `rollup`, `esbuild`, `parcel`, `vite`, or whatever
-1. Establish your `frontstage.ts` module (this will be your app's main entrypoint)
+1. Create your `frontstage.ts` module (this will be your app's main entrypoint)
     ```ts
     import {MySpec} from "./spec.js"
-    import {theaterHost, Frontstage, theaterElement, register} from "@benev/marduk/x/theater/index.front.js"
+    import {Frontstage, register} from "@benev/marduk/x/theater/index.dom.js"
 
     void async function() {
       const workerUrl = new URL("./backstage.bundle.js", import.meta.url)
-      const theater = await theaterHost<MySpec>({workerUrl})
-      const frontstage = new Frontstage(theater)
+      const frontstage = await Frontstage.make<MySpec>({workerUrl})
       register(frontstage.getElements())
 
       // okay, now you're ready to manipulate your world
 
-      // spawn a hippo
-      await frontstage.theater.backstage.setFigments([[0, ["hippo", {hungry: false}]]])
-
-      // update the hippo
-      await frontstage.theater.backstage.setFigments([[0, ["hippo", {hungry: true}]]])
-
-      // delete the hippo
-      await frontstage.theater.backstage.setFigments([[0, undefined]])
+      // spawn, then update, then delete a hippo (lol, just to exercise the full lifecycle)
+      await frontstage.syncFigments([[0, ["hippo", {hungry: false}]]])
+      await frontstage.syncFigments([[0, ["hippo", {hungry: true}]]])
+      await frontstage.syncFigments([[0, undefined]])
     }()
     ```
     - now bundle this module as `frontstage.bundle.js`
-1. Load the frontstage onto your web page
+1. Load the frontstage bundle onto your web page
     ```html
     <script type=module src="./frontstage.bundle.js"></script>
     ```
 1. Place the `<marduk-theater>` element in your html body
     ```html
     <marduk-theater></marduk-theater>
     ```
+1. 🎉 You're done!
+    - If you run the page, you should see the console logging about the hippo lifecycle events.
 

s/demo/main.bundle.ts

@@ -1,10 +1,8 @@
 
 import {register} from "@benev/slate"
 import {demoFrontstage} from "./theater/front.js"
-import {theaterElement} from "../theater/element/element.js"
 
 const frontstage = await demoFrontstage()
-const MardukTheater = theaterElement(frontstage)
-register({MardukTheater})
+register(frontstage.getElements())
 console.log("👁️")
 

s/demo/theater/back.worker.ts

@@ -1,7 +1,6 @@
 
 import {DemoFigmentSpec} from "./spec.js"
-import {theaterWorker} from "../../theater/theater-worker.js"
-import {babylonBackstage} from "../../theater/babylon-backstage.js"
+import {theaterWorker, babylonBackstage} from "../../theater/index.babylon.js"
 
 theaterWorker(
 	await babylonBackstage<DemoFigmentSpec>(async _stagecraft => ({

s/demo/theater/front.ts

@@ -1,19 +1,17 @@
 
 import {DemoFigmentSpec} from "./spec.js"
-import {theaterHost} from "../../theater/theater-host.js"
-import {Frontstage} from "../../theater/parts/frontstage.js"
+import {Frontstage} from "../../theater/index.dom.js"
 
 export async function demoFrontstage() {
 	const hash = document.head.querySelector("[data-commit-hash]")!.getAttribute("data-commit-hash")
 
 	const workerUrl = new URL(`./back.worker.bundle.js?v=${hash}`, import.meta.url)
-	const theater = await theaterHost<DemoFigmentSpec>({workerUrl})
-	const frontstage = new Frontstage(theater)
+	const frontstage = await Frontstage.make<DemoFigmentSpec>({workerUrl})
 
 	// test full lifecycle
-	await theater.backstage.setFigments([[0, ["hippo", {hungry: false}]]])
-	await theater.backstage.setFigments([[0, ["hippo", {hungry: true}]]])
-	await theater.backstage.setFigments([[0, undefined]])
+	await frontstage.syncFigments([[0, ["hippo", {hungry: false}]]])
+	await frontstage.syncFigments([[0, ["hippo", {hungry: true}]]])
+	await frontstage.syncFigments([[0, undefined]])
 
 	return frontstage
 }

s/demo/theater/spec.ts

@@ -1,5 +1,5 @@
 
-import {AsFigmentSpec} from "../../theater/parts/types.js"
+import {AsFigmentSpec} from "../../theater/index.pure.js"
 
 export type DemoFigmentSpec = AsFigmentSpec<{
 	hippo: {hungry: boolean}

s/index.ts

@@ -1,13 +1,12 @@
 
-export * from "./babylon/index.js"
-export * from "./buckets/index.js"
-export * from "./nametag/index.js"
-export * from "./theater/parts/types.js"
+export * from "./wip/babylon/index.js"
+export * from "./wip/buckets/index.js"
+export * from "./wip/nametag/index.js"
 
-export * from "./tools/loading/load-image.js"
-export * from "./tools/babyloid.js"
-export * from "./tools/label.js"
-export * from "./tools/obtain_babylon_quaternion_from_mesh.js"
+export * from "./wip/tools/loading/load-image.js"
+export * from "./wip/tools/babyloid.js"
+export * from "./wip/tools/label.js"
+export * from "./wip/tools/obtain_babylon_quaternion_from_mesh.js"
 export * from "./tools/quick_hash.js"
 export * from "./tools/uncapitalize.js"
 

s/tests.test.ts

@@ -1,7 +1,7 @@
 
 import {Science} from "@e280/science"
-import buckets from "./buckets/buckets.test.js"
-import nametag from "./nametag/nametag.test.js"
+import buckets from "./wip/buckets/buckets.test.js"
+import nametag from "./wip/nametag/nametag.test.js"
 
 await Science.run({
 	buckets,

s/theater/babylon-backstage.ts renamed to s/theater/babylon/babylon-backstage.ts

@@ -1,17 +1,18 @@
 
 import {sub} from "@e280/stz"
 import {Vec4} from "@benev/math"
-import {Scene} from "@babylonjs/core/scene.js"
-import {Engine} from "@babylonjs/core/Engines/engine.js"
-import {WebGPUEngine} from "@babylonjs/core/Engines/webgpuEngine.js"
 
-import {Backstage} from "./parts/backstage.js"
-import {make_scene} from "../babylon/iron/scene.js"
-import {Gameloop} from "../babylon/iron/gameloop.js"
-import {make_engine} from "../babylon/iron/engine.js"
-import {consolidateSpawners} from "./parts/spawners.js"
-import {Rendering} from "../babylon/iron/rendering/rendering.js"
-import {CanvasDetails, FigmentSpawners, FigmentSpec, Frame} from "./parts/types.js"
+import type {Scene} from "@babylonjs/core/scene.js"
+import type {Engine} from "@babylonjs/core/Engines/engine.js"
+import type {WebGPUEngine} from "@babylonjs/core/Engines/webgpuEngine.js"
+
+import {consolidateSpawners} from "../browser/spawners.js"
+import {make_scene} from "../../wip/babylon/iron/scene.js"
+import {Gameloop} from "../../wip/babylon/iron/gameloop.js"
+import {make_engine} from "../../wip/babylon/iron/engine.js"
+import {FigmentSpawners, FigmentSpec} from "../pure/types.js"
+import {Backstage, CanvasDetails, Frame} from "../browser/types.js"
+import {Rendering} from "../../wip/babylon/iron/rendering/rendering.js"
 
 export type BabylonStagecraft = {
 	canvas: OffscreenCanvas
@@ -23,7 +24,7 @@ export type BabylonStagecraft = {
 
 export async function babylonBackstage<Fs extends FigmentSpec>(
 		establish: (stagecraft: BabylonStagecraft) => Promise<FigmentSpawners<Fs>>,
-	) {
+	): Promise<Backstage<Fs> & BabylonStagecraft> {
 
 	let frameCount = 0
 	const onFrame = sub<[Frame]>()
@@ -53,7 +54,7 @@ export async function babylonBackstage<Fs extends FigmentSpec>(
 		onFrame,
 		updateCanvas,
 		spawn: consolidateSpawners(spawners),
-	} satisfies Backstage<Fs> & BabylonStagecraft
+	}
 }
 
 async function prepareBabylonStagecraft(): Promise<BabylonStagecraft> {

s/theater/parts/spawners.ts renamed to s/theater/browser/spawners.ts

@@ -1,6 +1,6 @@
 
 import {Spawn} from "../../tools/lifecycler.js"
-import {FigmentId, FigmentSpawners, FigmentSpec, FigmentTuple} from "./types.js"
+import {FigmentId, FigmentSpawners, FigmentSpec, FigmentTuple} from "../pure/types.js"
 
 export function consolidateSpawners<Fs extends FigmentSpec>(
 		spawners: FigmentSpawners<Fs>

s/theater/theater-worker.ts renamed to s/theater/browser/theater-worker.ts

@@ -1,8 +1,8 @@
 
 import {Comrade, tune} from "@e280/comrade"
-import {Backstage} from "./parts/backstage.js"
-import {Lifecycler} from "../tools/lifecycler.js"
-import {FigmentId, FigmentSpec, FigmentTuple, TheaterSchematic} from "./parts/types.js"
+import {Lifecycler} from "../../tools/lifecycler.js"
+import {Backstage, TheaterSchematic} from "./types.js"
+import {FigmentId, FigmentSpec, FigmentTuple} from "../pure/types.js"
 
 export async function theaterWorker<Fs extends FigmentSpec>(
 		backstage: Backstage<Fs>
@@ -16,7 +16,7 @@ export async function theaterWorker<Fs extends FigmentSpec>(
 		async setCanvasDetails(details) {
 			backstage.updateCanvas(details)
 		},
-		async setFigments(entries) {
+		async syncFigments(entries) {
 			for (const [id, tuple] of entries)
 				lifecycler.sync(id, tuple)
 		},