@thanhthbm/scene-editor 0.1.0

package/README.md

@@ -0,0 +1,169 @@
+# scene-editor
+
+Embeddable [three.js editor](https://github.com/mrdoob/three.js/tree/dev/editor) packaged as an installable npm library. It is designed to be **mounted into a Frappe Desk page / FormView (Vue)** to edit a single **Machine** figure or to assemble a **factory floor layout** from machine presets, and to receive live status updates from the outside (websocket / Frappe REST API).
+
+The library exposes a framework-agnostic `SceneEditor` class that mounts into any DOM container. All heavy third-party code (`three`, `three/addons/*`, `signals`) is **externalized** so your host bundler (Vite, webpack, Parcel) dedupes the single `three` instance in your app.
+
+## Install
+
+```bash
+npm install scene-editor three
+# peer dependency
+npm install three@">=0.165"
+```
+
+Optional runtime dep installed automatically: `signals`.
+
+## Quick start
+
+```js
+import { SceneEditor, registerBuiltinPresets } from 'scene-editor';
+import 'scene-editor/style.css';        // editor UI stylesheet (also auto-injected by the bundle)
+
+registerBuiltinPresets();               // registers press-machine, single-press, amada, compressor, coil-line
+
+const editor = new SceneEditor();
+editor.mount(document.getElementById('editor-host'));
+```
+
+## Public API
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `new SceneEditor(options?)` | `SceneEditor` | Construct (does not touch the DOM yet). |
+| `mount(containerOrSelector)` | `this` | Append the editor UI into a host element. |
+| `destroy()` | – | Disconnect observers / websocket, remove DOM, dispatch `editorCleared`. |
+| `getEditor()` | `Editor` | The upstream three.js `Editor` instance (full control). |
+| `getScene()` | `THREE.Scene` | Current scene. |
+| `getSceneJSON()` | `object` | Full editor state (scene + camera + history). Persist this in your DocType field. |
+| `setSceneJSON(json)` | `Promise<this>` | `editor.clear()` + `editor.fromJSON(json)`. |
+| `addObject(obj)` | `obj` | Add object through the undo history (`AddObjectCommand`). |
+| `addPreset(name, x=0, z=0, params?)` | `THREE.Object3D\|null` | Add a registered machine preset (see below). |
+| `registerPreset(name, factory)` | `PRESETS` | Register a custom preset factory `(x,z,params) => Object3D`. |
+| `getObjectByUuid(uuid)` | `Object3D` | Lookup. |
+| `selectByUuid(uuid)` | `this` | Select an object. |
+| `getSelected()` | `Object3D` | Current selection. |
+| `exportGLB(rootObject?)` | `Promise<ArrayBuffer>` | GLB binary of the object (or whole scene). Uses `GLTFExporter`. |
+| `exportGLBFile(rootObject?, filename?)` | `Promise<Blob>` | Same, triggers a browser download. |
+| `exportGLTF(rootObject?)` | `Promise<string>` | Pretty-printed glTF JSON. |
+| `on(signalName, fn)` | `unsubscribe()` | Subscribe to any `editor.signals.*` (e.g. `objectSelected`, `sceneGraphChanged`, `objectChanged`). |
+| `off(signalName, fn)` | – | Unsubscribe. |
+| `editor.events` | `EventBridge` | External event/data bindings (see below). |
+
+## Event binding — live data from Frappe / websocket
+
+`editor.events` is an `EventBridge` that maps scene objects to external data sources and pushes payloads into `object.userData` (and recolors a `beacon` mesh by status by default).
+
+```js
+const g = editor.addPreset('press-machine', 0, 0, { ton: 800, status: 'run', name: 'Press #12' });
+editor.events.bind(g, { topic: 'machine-status' });
+
+// Push from Frappe REST (polling / SSE / fetch):
+editor.events.dispatch(g.uuid, { status: 'err', curr: 412, oee: 24 });
+
+// Or open a shared websocket and route by { uuid, topic }:
+editor.events.connectWS('wss://frappe.example/socket', { reconnectMs: 3000 });
+// server -> { "uuid": "<machine uuid>", "status": "run", "oee": 88 }
+// or     -> { "topic": "machine-status", "status": "idle" }  (broadcasts to all bound objects of that topic)
+// or     -> { ... }  (broadcasts to ALL bindings)
+```
+
+Signals dispatched to refresh the sidebar when data changes: `objectChanged` + `sceneGraphChanged`.
+
+## Machine presets (built-in)
+
+`press-machine`, `single-press`, `amada`, `compressor`, `coil-line`. Each returns a `THREE.Group` placed at `(x, 0, z)` with a status beacon mesh tagged `userData.role === 'beacon'` (the bridge recolors it on `status` change). The group's `userData` carries `{ type:'machine', name, status, ... }`.
+
+```js
+editor.registerPreset('my-robot', (x, z, params) => {
+  const g = new THREE.Group();
+  // ...build geometry...
+  g.position.set(x, 0, z);
+  g.userData = { type: 'machine', name: params?.name || 'Robot' };
+  return g;
+});
+editor.addPreset('my-robot', 4, 4, { name: 'R2' });
+```
+
+## Frappe integration (Desk page + Vue)
+
+The editor is a plain DOM widget — wrap it in a Vue component:
+
+```vue
+<!-- frappe_custom/scene_editor/scene_editor_page.vue -->
+<template>
+  <div ref="host" class="se-host" />
+</template>
+
+<script setup>
+import { onMounted, onBeforeUnmount, ref } from 'vue';
+import { SceneEditor, registerBuiltinPresets } from 'scene-editor';
+import 'scene-editor/style.css';
+
+const props = defineProps({ machineDoc: Object });
+const emit  = defineEmits(['save']);
+const host  = ref(null);
+let editor;
+
+onMounted(() => {
+  registerBuiltinPresets();
+
+  editor = new SceneEditor();
+  editor.mount(host.value);
+
+  // load existing figure/config from the Machine document
+  frappe.model.with_doc('Machine', props.machineDoc.name, (doc) => {
+    if (doc.scene_json) editor.setSceneJSON(JSON.parse(doc.scene_json));
+  });
+
+  editor.events.connectWS(frappe.boot?.ws_url + '/machine-status', { reconnectMs: 5000 });
+});
+
+onBeforeUnmount(() => editor?.destroy());
+
+function persist() {
+  const json = JSON.stringify(editor.getSceneJSON());
+  frappe.db.set_value('Machine', props.machineDoc.name, 'scene_json', json);
+}
+defineExpose({ persist, exportGlb: () => editor.exportGLBFile() });
+</script>
+
+<style scoped>
+.se-host { width: 100%; height: calc(100vh - 96px); }
+</style>
+```
+
+Register a Vue-based Desk page via a Frappe custom app `page_js`, or render the component inside an HTML field / `_page` container. The host element just needs a fixed height.
+
+### Suggested DocType fields
+
+- **Machine**: `scene_json` (Long Text) — the editor state for that machine's figure; `glb_file` (Attach) — exported GLB.
+- **Factory Layout** (a separate DocType): `scene_json` (Long Text) — the factory-floor arrangement referencing placed machines.
+
+### Save / load workflow
+
+1. Open Machine doc → mount editor → `setSceneJSON(doc.scene_json)`.
+2. Edit geometry / material / transforms; Add menu adds primitives + your presets.
+3. On Save: `getSceneJSON()` → write to `scene_json`. On Export: `exportGLBFile()` → upload to `glb_file`.
+4. Open Factory Layout doc → mount editor → add machine presets (`addPreset`) → arrange on ground → save.
+
+## Development
+
+```bash
+npm run dev      # parcel dev server with a playground at src/index.html
+npm run build    # emits dist/index.js (ESM, externalized) + dist/index.css
+npm run clean
+```
+
+## Notes / current scope
+
+This build trims upstream-only features to keep the embed lean:
+- WebGPU renderer + GPU pathtracer (realistic viewport shading) — stubbed out.
+- WebXR session control — stubbed out.
+- CodeMirror/Tern script editor subsystem — not bundled (the script tab's "Edit" button is inert; add your own scripting UI via the `editScript` signal if needed).
+
+Everything else (Viewport, Toolbar, Sidebar *Scene/Properties/Project/Settings*, Menubar *File/Edit/Add/View/Render/Help/Status*, History, TransformControls, GLTF/3MF/FBX/OBJ/STL/etc. loaders via drag-&-drop, GLB/GLTF/OBJ/PLY/STL export, environment/fog/background) is intact upstream code.
+
+## License
+
+MIT — three.js editor code © three.js contributors (MIT); presets in `src/presets/` are project-specific.