Sroberge/three peerdep

[vim-sroberge]

Ship three as a peer dependency, drop the IIFE build, and tidy AI docs

Base: sroberge/1_0 ← Compare: sroberge/three-peerdep
Version: 1.0.0-beta.2 → 1.0.0-beta.3

Why

three was a hard dependency inlined into the bundle. Any host app that already used three ended up with two three instances in one page, which:

• breaks instanceof across the boundary — a host's THREE.Mesh is not our THREE.Mesh, so any API that accepts or returns three objects silently misbehaves. This is especially bad because vim-web re-exports THREE as VIM.THREE, so VIM.THREE.Mesh !== hostTHREE.Mesh today;
• duplicates three's module-level state (shader chunk registry, Object3D id counters, Layers, renderer bookkeeping);
• ships ~1.8 MB of three twice — the host already paid for it once.

Because of the re-export, this is a correctness fix for the existing public API, not just a packaging nicety.

What changed

three is now a peer dependency

• Moved three + @types/three from dependencies to devDependencies.
• Added three to peerDependencies at the tested range ^0.183.2 (i.e. the version the library is built and tested against — not a speculative wide range). Other three.js versions may work; only the pinned one is tested/supported.
• Externalized three and three/* in the Vite build (the /^three\// pattern also covers three/examples/jsm/* addon imports).
• main repointed from the deleted IIFE bundle to the ESM bundle.

IIFE build removed → ESM only

• vite.config.js now emits ['es'] only; dist/vim-web.iife.js is no longer produced.
• Rationale: the IIFE format can't cleanly externalize three (the three/examples/jsm/* passes have no UMD global), nothing in the repo documents or uses the <script>-tag path, and the exports map already routes modern consumers to ESM. Removed the now-dead output.globals map and UMD name.
• Breaking only for consumers loading the library via a raw <script> tag.

Docs & housekeeping (rides along with the beta.3 packaging change)

• AI docs/skills casing normalized to one rule: uppercase for tooling-required entry points (CLAUDE.md, README.md, SKILL.md), lowercase kebab-case for .claude/docs. Fixes two skills that used lowercase skill.md (the loader looks for SKILL.md and would miss them on case-sensitive systems) and repoints doc links (also fixing two that were missing the docs/ segment).
• .gitignore scoped: the bare docs pattern (meant for a root build dir) was collaterally hiding .claude/docs. Anchored to /docs / /docs2 so TypeDoc output stays ignored but .claude/docs is tracked.
• Two reference docs now tracked: styling.md (style.css tokens/patterns) and webgl-vs-ultra.md (WebGL/Ultra API comparison). Removed colors.md, a historical design plan for the already-shipped palette system that nothing referenced.
• Release notes / migration: RELEASE_NOTES.md beta.3 section + MIGRATION.md peer-dependency and IIFE-removal guidance.

Commits

Commit	Summary
982cfd78	Ship three as a peer dependency and drop the IIFE build
9cbe6b53	Normalize AI docs/skills filename casing
e8d80d9a	Document three peer-dependency and IIFE removal in release notes
4bcaa844	Track styling and webgl-vs-ultra docs; scope docs gitignore

Verification

• ✅ npm run build passes (vite + tsc declarations + both d.ts bundles).
• ✅ IIFE bundle no longer emitted.
• ✅ three no longer inlined — no __THREE__ duplicate-instance detector, no node_modules/three/build region in the output; three is imported as an external instead.
• ✅ ESM bundle: 3.43 MB → 1.57 MB (−54%), matching three's footprint.
• ✅ Rename commit is case-correct in the git index (input.md/optimization.md/rendering-optimizations.md lowercase; all SKILL.md uppercase) — correct on Linux/CI, not just Windows.

Consumer impact (breaking → beta.3)

Consumers must now install three themselves:

npm install vim-web three react react-dom
# TypeScript users also need @types/three matching their three version

• Bundler/ESM consumers: add three to their deps; one shared copy, no duplicate-instance issues.
• <script>-tag/IIFE consumers: switch to an ESM import (bundler or <script type="module">).
• Hosts pinned to a three version outside ^0.183 get a peer warning; they can override at their own risk and still keep a single copy.

Notes for reviewers

• styling.md / webgl-vs-ultra.md were never tracked before, so they land with their current local content and haven't had the repo's usual review history — worth a skim in the diff.
• Peer range is deliberately narrow (matches what's tested). Widening it later is a one-line change once other minors are verified.
• Scope grew past the original three/IIFE ask to include the docs housekeeping; if you'd rather review the three-fix in isolation, commits 9cbe6b53 and 4bcaa844 can be split into a separate PR.

[mavimaec]

@vim-sroberge please bump the version up to 1.0-beta.4 (beta.3 is already on NPM; the vim-hackathon repository references it)

[mavimaec]

Can you please also update vim-demo and vim-hackathon once beta.4 of vim-web is released?