flash555588_ai-model-workbench/docs/release-notes/0.7.0.md

# AI Model Workbench 0.7.0

`0.7.0` is a compatibility, performance, and support-boundary release for large
local 3D model workflows in Obsidian. It keeps Babylon.js compatibility mode as
the default single-model route, adds user control over converted GLB fast-path
routing, improves conversion side-file placement, tightens heavy-model behavior,
and makes STEP/CAD risks explicit in the user-facing documentation.

## Warnings And Risks

- STEP/STP and CAD files are conversion-only, not direct-render formats. They
  require Obsidian Desktop plus a configured local Python + CadQuery/OCCT
  environment before the plugin can preview them as GLB.
- Mobile can view direct formats and already-converted GLB files, but it cannot
  run local conversion tools or converter diagnostics.
- Large GLB files and converted STEP/PCB assemblies can consume significant CPU,
  GPU, RAM, and disk I/O. First open can take a long time, stall Obsidian, or
  trigger WebGL context loss on constrained devices.
- Local converters are external desktop tools that parse model files on your
  machine. Use trusted model files and verify converter command paths before
  processing unknown CAD, FBX, 3MF, DAE, or SLDPRT assets.
- Generated side files can be large or sensitive. Converted GLBs, reports,
  indexes, JSON sidecars, snapshots, part IDs, dimensions, geometry summaries,
  and preview images should be placed in an intentional folder and excluded from
  sync or Git when needed.
- Babylon.js compatibility mode is the safest renderer path. Three.js fast paths
  can be faster, but colors, picking, measurement, or toolbar behavior can differ
  on some assets. Disable the Converted GLB Three fast path or return to
  compatibility mode when diagnosing display issues.
- Remote drafting is optional and local-first by default. If configured, remote
  draft requests can still include sanitized evidence such as model names, part
  names, counts, dimensions, tags, and note references depending on privacy
  settings.

## Highlights

- Adds a `Converted GLB Three fast path` setting so conversion-backed direct file
  views can use Three.js first with silent Babylon fallback, or follow normal
  Babylon compatibility routing when the setting is disabled.
- Adds an `Auxiliary file folder` setting for generated conversion side files,
  while the empty default keeps outputs under the active Obsidian config folder.
- Reuses relocated converted-asset cache records for moved STEP/FBX/etc. sources
  and reuses fresh converted GLB outputs before initializing converter adapters.
- Defaults single-model preview surfaces to Babylon.js compatibility mode while
  keeping Three.js available through explicit rollout controls.
- Pauses restored large or conversion-backed direct-file previews until the user
  clicks `Load model`, avoiding vault lockups during workspace restore.
- Adds a draggable right-side camera zoom control and smoother wheel zoom across
  Three.js, Babylon.js, and `3dgrid`.
- Redesigns measurement as an inspector-toolbar readout with synced records,
  transparent in-scene dimension text, copy/clear/calibration actions, and
  improved pointer feedback.
- Keeps direct file view canvases full-height by moving workbench metrics into a
  compact overlay and fixing the Obsidian leaf height chain.
- Adds README warning sections in English and Chinese that clearly describe
  STEP/CAD conversion limits, external tool risk, large-model pressure, generated
  side files, renderer-route differences, mobile limits, and optional remote
  drafting privacy.

## Detailed Changes

### Routing And Settings

- Added the Converted GLB Three fast-path toggle and diagnostics output.
- Added the Auxiliary file folder setting and diagnostics output.
- Kept Babylon.js as the default single-model compatibility route.
- Kept Three.js available for explicit single-model rollout and converted GLB
  fast-path use.
- Documented the converted GLB route contract in the preview routing matrix.
- Preserved Experimental Three workbench as a guarded direct GLB/GLTF option with
  Babylon fallback.

### Conversion And Cache

- Wrote new converted GLB outputs under the active `Vault#configDir` instead of
  assuming `.obsidian`.
- Allowed users to place generated conversion side files in a configured vault
  folder.
- Reused relocated cache records when a source file moved but a same-stem fresh
  converted GLB already exists.
- Reused existing converted outputs before probing converter identity or creating
  conversion managers.
- Reused source file stats across conversion-cache checks.
- Reused normalized converted-asset records during plugin startup.
- Clarified STEP/STP support as local desktop conversion only.

### Direct View, Grid, And UI

- Cancelled stale direct-file preview load sessions during rapid model switches.
- Disposed interrupted Three.js and Babylon.js GLB results before they can
  compete with the newest load.
- Paused restored large/conversion-backed direct file previews until explicit
  user load.
- Kept direct file view canvases full-height.
- Added a right-side draggable camera zoom slider.
- Improved wheel zoom behavior across preview backends.
- Redesigned the distance measurement UI and records.
- Kept Babylon `3dgrid` warmup frames dirty briefly after load to avoid blank
  first frames.
- Released offscreen `3dgrid` Babylon engines and gave grid canvases a stable
  default height.
- Added multi-block `3dgrid` preview verification for nonblank pixels and WebGL
  context-loss warnings.

### Performance

- Deferred reading-mode, Live Preview, annotation, heading-pin, settings, import,
  converter, and direct-view workbench modules until visible or needed.
- Serialized inline and Live Preview loads through a queue and added a settle
  window between heavy visible model loads.
- Cached Live Preview embed path resolution and skipped full rescans for ordinary
  note edits.
- Loaded external `.gltf` buffers and textures with temporary Blob URLs and
  deduplicated concurrent resource reads.
- Included external `.gltf` buffers and textures in pre-parse render budgeting.
- Applied render quality earlier and pre-budgeted direct, inline, and Live
  Preview render quality from model file size.
- Avoided extra full-buffer copies for absolute-path model files.
- Deferred Three.js PMREM, shadow, geometry snapshot, evidence registration, and
  registered-match preview work so large models become interactive sooner.
- Cached Three.js root bounds, child-mesh descendant indexes, renderable bounds,
  renderable indexes, material preparation, and Babylon/Three geometry stats.
- Reduced disassembly drag and focus-selection work for large assemblies.
- Compacted persisted registered parts, mesh refs, bounding boxes, centers, and
  automatic observation text to reduce `data.json` startup cost.
- Avoided unchanged plugin-state rewrites during startup and unload.
- Skipped or delayed low-value automatic evidence registration for heavy models.

### Rendering And Interaction

- Included Three.js PLY point clouds in summary, part evidence, picking,
  measurement, material audit, and disposal paths.
- Kept Three.js orthographic camera, shadow, and grid helper scales tied to real
  tiny-model bounds.
- Promoted converted component child-mesh picks to their parent registered
  component/group for selection, focus, and disassembly behavior.
- Preserved nested component world transforms during disassembly drag.
- Throttled Three.js measurement preview-line raycasts to animation frames.
- Scaled Three.js texture anisotropy by render quality.
- Resolved parent-directory GLTF/OBJ resource paths consistently across desktop
  platforms.

### Knowledge, Diagnostics, And Docs

- Preserved part-splitting format lineage across direct and converted formats in
  reports, sidecars, draft input, and registered part profiles.
- Merged generic tiny mesh fragments into lower-confidence detail clusters.
- Skipped direct-view auto part registration writes when regenerated candidates
  match saved profiles.
- Improved direct-view registered part match previews by skipping sidecar reads,
  capping sample sizes, and reusing indexed match tokens.
- Expanded diagnostics with the converted GLB fast-path setting and auxiliary
  file folder.
- Trimmed redundant README copy and moved detailed syntax to dedicated usage
  docs.
- Added explicit warning/risk sections to README and README.zh-CN.
- Updated the development handoff, preview routing matrix, changelog, and release
  docs for the 0.7.0 route and settings contract.

## Release Contract

- Release assets remain limited to `main.js`, `manifest.json`, and `styles.css`.
- Minimum Obsidian version remains `1.5.0`.
- Local conversion remains desktop-only and does not upload model files.
- Knowledge generation remains local-first. Remote draft support remains optional
  and uses sanitized evidence only when explicitly configured.
- Babylon.js remains the production compatibility backend for default
  single-model previews, `3dgrid`, conservative fallback behavior, and future
  local-only SPLAT restoration.

## Verification

- `npm run typecheck`
- `npm run lint`
- `npm run verify:settings`
- `npm run verify:diagnostics`
- `npx vitest run src/view/direct-view-routing.test.ts src/diagnostics/report.test.ts`
- `npm run verify:preview`
- `npm run build`
- `npm run verify:release`