Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
65 commits
Select commit Hold shift + click to select a range
19042fd
feat: add keyboard command palette engine
VeloraTech Nov 19, 2026
0b714f4
feat: add non-destructive orbit preview controller
VeloraTech Nov 19, 2026
a28f38e
test: cover command palette matching and execution
VeloraTech Nov 19, 2026
5113e70
refactor: inject Three.js into orbit preview
VeloraTech Nov 19, 2026
640c357
fix: pause orbit preview during manual navigation
VeloraTech Nov 19, 2026
92abe9b
feat: integrate command mode and orbit preview in viewer
VeloraTech Nov 19, 2026
4b37b50
fix: pass frame delta to orbit preview
VeloraTech Nov 19, 2026
a10ff6b
build: include P1 editor modules in startup updates
VeloraTech Nov 19, 2026
2f0f51a
test: cover orbit preview camera behavior
VeloraTech Nov 19, 2026
b699156
test: complete orbit preview vector test double
VeloraTech Nov 19, 2026
fe14011
fix: reflect manual orbit pause in preview controls
VeloraTech Nov 19, 2026
f58800f
fix: resume orbit preview from manually adjusted camera
VeloraTech Nov 19, 2026
9ff8abc
Show unavailable commands with reasons and guard execution
VeloraTech Nov 19, 2026
6d193a3
Wire command palette and orbit preview into viewer
VeloraTech Nov 19, 2026
bcbecdc
Test disabled command reasons and exclusive command execution
VeloraTech Nov 19, 2026
1b965ba
Close command search when a command starts
VeloraTech Nov 19, 2026
b1b2ae0
Add viewport navigation and presentation controls
VeloraTech Nov 19, 2026
2d52a59
Integrate viewport navigation and material inspection tools
VeloraTech Nov 19, 2026
2f2f3bc
Add viewport grid, axes, shading and framing controls
VeloraTech Nov 19, 2026
0446f39
Include viewport workspace in installed-app updates
VeloraTech Nov 19, 2026
b579415
Add undoable scene object renaming
VeloraTech Nov 19, 2026
6c3be50
Implement P1 outliner, inspection, projection and GLB export
VeloraTech Nov 19, 2026
a104776
Test undoable object renaming
VeloraTech Nov 19, 2026
a7db99d
Add lighting management, pan mode and dirty tracking
VeloraTech Nov 19, 2026
02284c2
Persist editor preferences and improve pan reset
VeloraTech Nov 19, 2026
b2ba67c
Align key lighting with pan position and persist lighting changes
VeloraTech Nov 19, 2026
498251c
Add configurable additional scene lights
VeloraTech Nov 19, 2026
77f46d9
Harden pan and shadow interaction
VeloraTech Nov 19, 2026
98bacb7
Ensure spot light targets track model position
VeloraTech Nov 19, 2026
8025f41
fix: expose command id in palette search results
VeloraTech Nov 19, 2026
97ad138
fix: preserve synchronous command execution results
VeloraTech Nov 19, 2026
3ea16a6
fix: return execution success from command palette
VeloraTech Nov 19, 2026
5d21499
Build P1 transform gizmos, multi-object editing, and material slots
VeloraTech Nov 19, 2026
5cd12ee
Fix pan sensitivity for orthographic projection
VeloraTech Nov 19, 2026
52898ea
Prevent nested selection double transforms and handle zero scale
VeloraTech Nov 19, 2026
6902a00
Add undoable material property command
VeloraTech Nov 19, 2026
a835bac
Test undoable material property edits
VeloraTech Nov 19, 2026
b85ea66
Record material edits in undo and redo history
VeloraTech Nov 19, 2026
af7f2c9
Harden model inspection and preserve source materials on export
VeloraTech Nov 19, 2026
9323e96
Preserve animation clips and use tested model inspection
VeloraTech Nov 19, 2026
c113baf
Add reusable model inspection utility
VeloraTech Nov 19, 2026
68e01fd
Correct model inspection bounds and Three.js dependency
VeloraTech Nov 19, 2026
b3a5025
Wire tested model inspection results into viewer
VeloraTech Nov 19, 2026
4501624
Test model inspection counts and warnings
VeloraTech Nov 19, 2026
169debb
Include model inspection module in Windows updates
VeloraTech Nov 19, 2026
c362d4e
Keep edits made during export marked as unsaved
VeloraTech Nov 19, 2026
681a5e2
Add shared-pivot multi-object transform controller
VeloraTech Nov 19, 2026
d6f8f74
Integrate shared-pivot multi-object gizmo editing
VeloraTech Nov 19, 2026
ae4f2b7
Include multi-object transform module in updater bundle
VeloraTech Nov 19, 2026
6842f2f
Document reproducible P1 performance and editing benchmarks
VeloraTech Nov 19, 2026
95acc8c
Add reversible glTF material texture channel editing
VeloraTech Nov 19, 2026
e4439b6
Scope transform axis locks to the active gizmo mode
VeloraTech Nov 19, 2026
1935fb7
Pass pointer modifiers through viewport selection
VeloraTech Nov 19, 2026
6aefe40
Support modifier-assisted viewport multi-selection
VeloraTech Nov 19, 2026
d16939b
Add axis constraints to shared multi-object gizmo
VeloraTech Nov 19, 2026
6509ef7
Remove superseded multi-transform drag initializer
VeloraTech Nov 19, 2026
005094c
Wire axis locks into shared multi-object gizmo
VeloraTech Nov 19, 2026
cbe891e
Keep active object aligned with multi-selection toggles
VeloraTech Nov 19, 2026
c721384
Exclude locked objects from active editor selection
VeloraTech Nov 19, 2026
cf0fa95
Preserve texture references in material undo history
VeloraTech Nov 19, 2026
36b1879
Clear transform gizmo selection after deleting an object
VeloraTech Nov 19, 2026
3b0ef9f
Dispose temporary viewport shading materials on restore
VeloraTech Nov 19, 2026
1ba5d74
Prevent material edits against temporary viewport shading materials
VeloraTech Nov 19, 2026
c5204e0
fix: dispose viewport helper GPU resources
VeloraTech Nov 19, 2026
2e2817d
fix: ignore stale texture loads after model replacement
VeloraTech Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 139 additions & 0 deletions docs/P1_BENCHMARKS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
# GLB Viewer — P1 Benchmark Specification

## Purpose

This document defines how GLB Viewer performance and editing behavior are to be evaluated. It separates intended product behavior, performance targets, and measurements collected from real runs.

A benchmark result is meaningful only when its environment and model are recorded. A result from one computer must not be presented as a universal guarantee.

## Product benchmark principles

1. Keep the viewer usable on modest Windows laptops, not only workstation-class hardware.
2. Prefer predictable interaction and stable resource use over visual effects that make editing unreliable.
3. Do not silently discard model content during editing or export.
4. Keep model files and diagnostics local unless a user explicitly chooses to share them.
5. Compare the same model, browser, resolution, and quality settings when measuring changes.

## Hardware profiles

Record the actual machine; do not assume a machine belongs to a profile from its model name alone.

| Profile | Intended use | Record |
|---|---|---|
| Minimum / constrained | Older dual-core CPU, 8 GB RAM, integrated graphics, HDD | CPU, RAM, GPU, storage type, OS |
| Recommended | Modern quad-core CPU, 16 GB RAM, integrated or entry GPU, SSD | CPU, RAM, GPU, storage type, OS |
| Higher capacity | Dedicated GPU and 16 GB+ RAM | Exact GPU and driver, CPU, RAM, storage |

The minimum profile is a compatibility target, not a promise that every arbitrarily large GLB will run smoothly.

## Model profiles

Use real GLB files and preserve the exact files used for each benchmark. Record filename, file size, mesh count, vertex count, triangle count, material count, texture count, animation count, and approximate texture dimensions.

| Profile | Suggested characteristics | Purpose |
|---|---|---|
| Small | Under 5 MB, simple geometry, few materials | Startup and basic editing baseline |
| Medium | 5–30 MB, multiple meshes/materials, some textures | Typical editing workflow |
| Large | 30–100 MB or high geometry/texture complexity | Resource and stability behavior |
| Stress | Above 100 MB or unusually dense/texture-heavy | Limits and failure handling, not a minimum-device guarantee |

These are test groupings, not strict file-size-only complexity definitions. Geometry and texture memory can dominate compressed file size.

## Measurements to record

### Loading
- Time from selecting the file to the model becoming visible and interactive.
- Whether progress feedback remains responsive.
- Whether a failed load leaves the previously loaded model usable.
- Whether replacing models repeatedly causes visible resource accumulation.

### Viewport and editing
- Approximate frame rate or frame-time behavior while orbiting.
- Selection response and Outliner responsiveness.
- Transform responsiveness for one object and multiple objects.
- Whether locked objects remain unchanged.
- Whether undo and redo restore the exact prior state.
- Whether material, lighting, visibility, and hierarchy edits remain coherent.

### Export
- Time from export action to completed download.
- Output file size.
- Whether the exported file reopens.
- Whether hierarchy, transforms, materials, textures, visibility expectations, and animations are preserved.
- Any source features that the exporter or format cannot preserve must be recorded explicitly.

### Resource observations
- Browser memory observations where available.
- Three.js renderer memory counters and geometry/texture counts.
- WebGL context loss, tab crashes, and out-of-memory symptoms.
- Note that renderer counters are not total browser-process or system memory.

## Measurement procedure

For every run, record:

- Date and GLB Viewer commit/version.
- Operating system and browser version.
- CPU, installed RAM, GPU, graphics driver, and storage type.
- Display resolution, browser zoom, and device pixel ratio.
- Model profile and exact source filename.
- Whether the run was cold (first load) or warm (subsequent load).
- Any other applications consuming significant resources.

Run each scenario at least three times where practical. Report individual results and the median; do not report only the best run. Keep cold and warm loads separate.

## P1 workflow benchmark

Use one representative model containing multiple selectable meshes and at least one material with a texture when possible.

1. Open the model.
2. Inspect its metadata.
3. Select one object and manipulate it with the gizmo.
4. Select multiple objects and manipulate them together.
5. Apply numeric transforms.
6. Exercise X/Y/Z axis constraints and Local/World space.
7. Edit material properties and supported texture channels.
8. Change lighting and viewport settings.
9. Undo and redo representative edits.
10. Export the edited GLB and reopen it.
11. Compare the reopened result with the expected edited scene.

## Results template

Copy this block for each machine/model combination:

- Date:
- Viewer commit:
- OS / browser:
- CPU:
- RAM:
- GPU / driver:
- Storage:
- Resolution / device pixel ratio:
- Model filename / profile:
- File size:
- Meshes / vertices / triangles:
- Materials / textures / animations:
- Cold load time:
- Warm load time:
- Viewport observations:
- Multi-object transform observations:
- Undo/redo observations:
- Export duration / output size:
- Reopen and content-preservation observations:
- Memory / renderer observations:
- Errors or limitations:

## Targets versus measured results

Do not fill this document with guessed performance numbers. Numeric acceptance thresholds should be set only after baseline measurements on the minimum and recommended profiles.

A future benchmark report should publish:
- The exact environment and source models.
- Median and range, not only a best run.
- Known limitations and failed scenarios.
- Whether a result is a target, an observed measurement, or a regression comparison.

## Current status

This document is the benchmark protocol. It does not claim that the benchmarks have been run or that any performance target has been achieved.
7 changes: 6 additions & 1 deletion scripts/update-viewer.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,18 @@ try {
'src/editor/WorkspaceManager.js',
'src/editor/ViewportInteraction.js',
'src/editor/SceneRuntime.js',
'src/editor/CommandPalette.js',
'src/editor/OrbitPreview.js',
'src/editor/ViewportWorkspace.js',
'src/editor/MultiObjectTransform.js',
'src/core/ResourceDisposer.js',
'src/core/PerformanceMonitor.js',
'src/core/HardwareProviders.js',
'src/core/AdaptiveQualityPolicy.js',
'src/core/SceneStore.js',
'src/core/CommandHistory.js',
'src/core/SceneCommands.js'
'src/core/SceneCommands.js',
'src/core/ModelInspector.js'
)
$stageRoot = Join-Path $UpdateRoot ('.staging-' + [guid]::NewGuid().ToString('N'))
$bundleRoot = Join-Path $UpdateRoot $commitSha
Expand Down
52 changes: 52 additions & 0 deletions src/core/ModelInspector.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
/**
* Inspect a loaded Three.js Object3D tree without mutating it.
* Returns primitive counts, material/texture totals, bounds and review warnings.
*/
export function inspectModel(root, THREE) {
if (!root || typeof root.traverse !== 'function' || !THREE?.Box3 || !THREE?.Vector3) {
throw new TypeError('A model and Three.js namespace are required.');
}
let meshes = 0, vertices = 0, triangles = 0, groups = 0;
const materials = new Set(), textures = new Set(), warnings = new Set();
const visited = new Set();
root.updateWorldMatrix?.(true, true);
const collectTextures = value => {
if (!value || typeof value !== 'object' || visited.has(value)) return;
visited.add(value);
if (value.isTexture) { textures.add(value); return; }
if (Array.isArray(value)) { value.forEach(collectTextures); return; }
for (const nested of Object.values(value)) collectTextures(nested);
};
root.traverse(object => {
if (object.isGroup) groups++;
if (object.isMesh) {
meshes++;
const geometry = object.geometry;
const position = geometry?.attributes?.position;
const count = geometry?.index ? geometry.index.count : position?.count || 0;
if (!position) warnings.add('A mesh has no position attribute.');
else {
vertices += position.count;
triangles += Math.floor(count / 3);
if (count % 3 !== 0) warnings.add('Some mesh geometry is not a complete set of triangles.');
}
if (geometry?.morphAttributes && Object.keys(geometry.morphAttributes).length) warnings.add('Morph targets are present; verify animation after export.');
if (object.isSkinnedMesh) warnings.add('Skinned mesh detected; verify skinning after export.');
const slots = Array.isArray(object.material) ? object.material : [object.material];
for (const material of slots) {
if (!material) continue;
materials.add(material);
collectTextures(material);
}
}
if (object.isLine || object.isPoints) warnings.add('Line or point geometry is present; GLB export compatibility should be checked.');
});
const bounds = new THREE.Box3().setFromObject(root);
const size = bounds.getSize(new THREE.Vector3());
if (bounds.isEmpty()) warnings.add('Model bounds could not be calculated.');
return {
meshes, vertices, triangles: Math.round(triangles), groups,
materials: materials.size, textures: textures.size,
warnings: [...warnings], size,
};
}
74 changes: 74 additions & 0 deletions src/core/SceneCommands.js
Original file line number Diff line number Diff line change
Expand Up @@ -171,3 +171,77 @@ export class ReparentObjectCommand {
this.sceneStore.reparentObject(this.objectId, this.snapshot.oldParent, this.snapshot.oldIndex);
}
}

export class RenameObjectCommand {
constructor(sceneStore, objectId, name) {
requireSceneMutationApi(sceneStore, 'requireObject');
this.sceneStore=sceneStore;this.objectId=String(objectId);this.name=String(name).trim();
if(!this.name)throw new TypeError('Object name cannot be empty.');
this.previousName=null;
}
do(){
const object=this.sceneStore.requireObject(this.objectId);
if(this.previousName===null)this.previousName=object.name||'';
object.name=this.name;
this.sceneStore.emit?.('object:changed',{action:'rename',object});
this.sceneStore.emit?.('scene:changed',{action:'rename',object});
}
undo(){
if(this.previousName===null)throw new Error('Cannot undo a rename before it executes.');
const object=this.sceneStore.requireObject(this.objectId);object.name=this.previousName;
this.sceneStore.emit?.('object:changed',{action:'rename',object});
this.sceneStore.emit?.('scene:changed',{action:'rename',object});
}
}


/**
* Reversible material-property edit. Values with clone()/copy() (for example
* THREE.Color) are snapshotted by value; textures and other resource objects
* are retained by reference so undo can restore the original resource.
*/
export class SetMaterialPropertiesCommand {
constructor(material, properties) {
if (!material || typeof material !== 'object') {
throw new TypeError('A material object is required.');
}
if (!properties || typeof properties !== 'object' || Array.isArray(properties) ||
Object.keys(properties).length === 0) {
throw new TypeError('At least one material property is required.');
}
this.material = material;
this.properties = { ...properties };
this.previous = null;
}

snapshot() {
const values = {};
for (const key of Object.keys(this.properties)) {
const value = this.material[key];
values[key] = value && !value.isTexture && typeof value.clone === 'function' ? value.clone() : value;
}
return values;
}

apply(values) {
for (const [key, value] of Object.entries(values)) {
const current = this.material[key];
if (current && value && !current.isTexture && !value.isTexture && typeof current.copy === 'function' && typeof value === 'object') {
current.copy(value);
} else {
this.material[key] = value;
}
}
this.material.needsUpdate = true;
}

do() {
if (this.previous === null) this.previous = this.snapshot();
this.apply(this.properties);
}

undo() {
if (this.previous === null) throw new Error('Cannot undo a material edit before it executes.');
this.apply(this.previous);
}
}
88 changes: 88 additions & 0 deletions src/editor/CommandPalette.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
/** CommandPalette — state-aware keyboard command search for the editor. */
const normalize = (value) => String(value || "").trim().toUpperCase().replace(/\\s+/g, " ");

export class CommandPalette {
constructor({ root = document, input, overlay, registry, onExecute = () => {} }) {
if (!input || !overlay || !registry) throw new TypeError("CommandPalette requires input, overlay and registry.");
this.root=root; this.input=input; this.overlay=overlay; this.registry=registry; this.onExecute=onExecute;
this.query=""; this.activeIndex=0; this.opened=false; this.commands=new Map(); this.runningGroups=new Set();
this.onKeyDown=(event)=>this.handleKeyDown(event);
this.onInput=()=>{this.query=this.input.value;this.activeIndex=0;this.render();};
this.onClick=(event)=>{const item=event.target.closest("[data-command-id]");if(item)this.execute(item.dataset.commandId);};
this.root.addEventListener("keydown",this.onKeyDown,true);
this.input.addEventListener("input",this.onInput);
this.overlay.addEventListener("click",this.onClick);
}
register(command) {
if(!command||!/^[a-z0-9][a-z0-9-]*$/i.test(command.id||"")||typeof command.execute!=="function") throw new TypeError("A command requires a valid id and execute function.");
if(this.commands.has(command.id)) throw new Error(`Command "${command.id}" is already registered.`);
const entry={label:command.id.toUpperCase(),description:"",aliases:[],keywords:[],enabled:()=>true,disabledReason:()=>"Unavailable",...command};
this.commands.set(entry.id,entry);this.refresh();return()=>{this.commands.delete(entry.id);this.refresh();};
}
state(command) {
let enabled=false,reason="";
try { enabled=Boolean(command.enabled()); if(!enabled) reason=typeof command.disabledReason==="function"?command.disabledReason():command.disabledReason||"Currently unavailable"; }
catch(error){reason=error?.message||"Availability check failed";}
if(command.exclusiveGroup&&this.runningGroups.has(command.exclusiveGroup)){enabled=false;reason="Another "+command.exclusiveGroup+" operation is running";}
return {enabled,reason};
}
list(query=this.query) {
const q=normalize(query),tokens=q.split(" ").filter(Boolean);
return [...this.commands.values()].map(command=>{
const candidates=[command.label,command.id,...command.aliases,...command.keywords].map(normalize);
let score=0;
if(!q)score=1;else if(candidates.some(v=>v===q))score=100;else if(candidates.some(v=>v.startsWith(q)))score=80;else if(tokens.every(t=>candidates.some(v=>v.includes(t))))score=50;else return null;
return {id:command.id,command,score,...this.state(command)};
}).filter(Boolean).sort((a,b)=>b.score-a.score||a.command.label.localeCompare(b.command.label));
}
refresh(){if(this.opened)this.render();}
open(initial=""){this.opened=true;this.query=initial;this.activeIndex=0;this.overlay.hidden=false;this.input.value=initial;this.render();this.input.focus();this.input.setSelectionRange(this.input.value.length,this.input.value.length);}
close(){this.opened=false;this.overlay.hidden=true;this.input.value="";this.query="";}
handleKeyDown(event){
const target=event.target,isEditable=target?.matches?.("input, textarea, select, [contenteditable='true']")||target?.isContentEditable;
if(this.opened){
if(event.key==="Escape"){event.preventDefault();event.stopPropagation();this.close();return;}
const items=this.list(),available=items.map((item,index)=>item.enabled?index:-1).filter(index=>index>=0);
if(event.key==="ArrowDown"||event.key==="ArrowUp"){event.preventDefault();if(available.length){const current=available.indexOf(this.activeIndex),step=event.key==="ArrowDown"?1:-1;this.activeIndex=available[(current+step+available.length)%available.length];}this.render();return;}
if(event.key==="Tab"){const selected=items[this.activeIndex];if(selected?.enabled){event.preventDefault();this.input.value=selected.command.label;this.query=selected.command.label;this.activeIndex=0;this.render();}return;}
if(event.key==="Enter"){event.preventDefault();event.stopPropagation();const selected=items[this.activeIndex];if(selected?.enabled)this.execute(selected.command.id);return;}
return;
}
if(isEditable||event.defaultPrevented||event.ctrlKey||event.metaKey||event.altKey)return;
if(event.key==="F3"||(event.key===" "&&event.shiftKey)){event.preventDefault();this.open();return;}
if(event.key.length===1&&!event.repeat){event.preventDefault();this.open(event.key);}
}
execute(id){
const command=this.commands.get(id);if(!command)return false;
const status=this.state(command);if(!status.enabled)return false;
this.close();
const group=command.exclusiveGroup;if(group)this.runningGroups.add(group);
this.refresh();
const release=()=>{if(group)this.runningGroups.delete(group);this.refresh();};
let result;
try{result=command.execute();}
catch(error){this.onExecute(command,error);release();throw error;}
if(result&&typeof result.then==="function"){
return Promise.resolve(result)
.then(()=>{this.onExecute(command);return true;})
.catch(error=>{this.onExecute(command,error);throw error;})
.finally(release);
}
this.onExecute(command);
release();
return true;
}
render(){
const items=this.list(),list=this.overlay.querySelector("[data-command-results]");list.replaceChildren();
if(!items.length){const empty=this.root.createElement("div");empty.className="command-empty";empty.textContent="No matching commands";list.append(empty);return;}
if(this.activeIndex>=items.length||!items[this.activeIndex]?.enabled)this.activeIndex=Math.max(0,items.findIndex(item=>item.enabled));
items.forEach(({command,enabled,reason},index)=>{
const button=this.root.createElement("button");button.type="button";button.className="command-result"+(enabled?"":" is-disabled");
button.dataset.commandId=command.id;button.disabled=!enabled;button.setAttribute("aria-disabled",String(!enabled));button.setAttribute("aria-selected",String(index===this.activeIndex));
const title=this.root.createElement("span");title.textContent=command.label;
const description=this.root.createElement("small");description.textContent=enabled?command.description:(reason||command.description);
button.append(title,description);list.append(button);
});
}
dispose(){this.root.removeEventListener("keydown",this.onKeyDown,true);this.input.removeEventListener("input",this.onInput);this.overlay.removeEventListener("click",this.onClick);this.close();this.commands.clear();this.runningGroups.clear();}
}
Loading
Loading