# Changelog

All notable changes to **img2threejs** are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.4.4-beta.2]

### Added
- Add a repository-local mandatory workflow checklist, resume gate, and evidence-backed step
  tracking under `.img2threejs/state.json`.
- Add per-pass and total correction ceilings derived from `reviewHistory`; `forge/next.py` now
  hard-stops when either limit is reached.
- Add an executable CS2 review CLI and profile-specific CS2/character checklist gates.
- Add explicit suitability, projection-route, and material-evidence decisions to every profile.

### Changed
- Keep progressive-disclosure references while making CS2 intake, deterministic review gates,
  self-correction, multi-angle review, part coverage, and action-ready validation explicit router
  requirements.
- Order each pass as build, render, Tier 1, multi-angle, deterministic pass check, profile review,
  AI review, and sync.
- Make regeneration action-aware so `refine-code` cannot overwrite the artifact it must repair,
  and reject spec paths that disagree with local state.

## [1.4.3] — 2026-07-30

The accepted current release line is `1.4.x`. GitHub Releases are the canonical changelog from
the governed `v1.4.3` tag onward.

### Changed
- Release publication now occurs only from an approved annotated version tag; merging a pull
  request never changes the version or creates a release.

## Invalid historical record: 1.5.0 — not released

The entry below was generated by the retired push-to-`main` release automation. It is retained as
historical context only and does not represent an accepted release or release-note baseline.

### Added
- add Python CI and automated releases
- update changelog and roadmap
- enhance skill and strict cs2 component render

### Fixed
- stabilize pHash brightness invariance
- align tests with review evidence gates
- sponsor donate link + weekly and all-language Trendshift badges (#42)
- use the logo mark for the README, at its real aspect ratio (#36)
- restore assets/logo.svg so the README logo stops 404-ing (#35)

## [1.4.1] — 2026-07-26

The hardening update for the CS2 reconstruction pipeline: explicit component coverage, a pistol
assembly contract, and review evidence that distinguishes real structure from a convincing texture.

### Added
- **Assembly coverage gate** — `stage4_review/check_part_coverage.py` verifies that every specified
  component is built, prevents multiple specified components from collapsing into one mesh, and
  reports unowned meshes and inventory details that never reached the spec.
- **Glock-18 adapter** — the CS2 route now supports a dedicated `pistol` / `glock-18` component tree
  with separate slide, frame, magazine, trigger-guard, control, barrel, and internal-mechanism
  contracts; it does not reuse the knife topology.
- **Structure-first guidance** — documented rules for named, explodable and selectable parts, plus
  correct layout scaling for exploded views in `SKILL.md` and
  `grimoire/build/geometry_patterns.md`.

### Changed
- **Strict review evidence** — the pipeline requires map-stripped blockout evidence, ordered pass
  credit, and thickness- and long-axis viewpoints before a visual pass can continue.
- **Geometry-integrity checks** — Tier 1 now surfaces open separate geometry, insufficient seams,
  constant blade grinds, and missing distal taper so projection cannot hide structural defects.

## [1.4.0] — 2026-07-25

**Theme: Weapon Pipeline.** Image-matched CS2 hard-surface reconstruction: evidence-backed identity,
projection-first finish matching, family-specific geometry, and gate-driven review.

### Added
- **CS2 intake and provenance contract** — reference admission, technical probing, identity routing,
  metadata lookup, VPK/texture discovery, and an atomic `cs2-intake.json` hand-off that preserves
  uncertainty instead of guessing.
- **CS2 knowledge base and local search** — bilingual BM25 search profiles, curated vocabulary and
  anatomy references, plus provenance-aware result handling for specification work.
- **Family-specific reconstruction** — knife adapters, supported subtype validation, component-tree
  contracts, projected-texture baking, and a strict-quality route for CS2 assets.
- **Evidence-backed CS2 review** — `cs2_review.py`, geometry-integrity measurements, fixed and orbit
  review views, family/finish/projection/critical-detail gates, and versioned review-scene metadata.
- **Reference preview and prompt assets** — a browser smoke-tested CS2 knife preview, reference
  fixture, and focused knife, pistol, and technical-analysis skill prompts.

### Changed
- **Projection-first finish workflow** — de-lit reference crops are the default path for matching
  skin patterns, decals, and painted surfaces; procedural finishes remain an explicitly disclosed
  fallback.
- **Divine Eye calibration** — scale and aspect signals are live, and the reconstruction rescue path
  now requires objectness, soft-fidelity, and proportion evidence rather than accepting an IoU-only
  result.

## [1.3.0] — 2026-07-22

The "quality & efficiency" line: a deterministic-first review harness (Divine Eye), stronger
input integrity, geometry-truth gates, and reference-grounded texture/material analysis.

### Added — Plan 1.3 (Phases 1–7)
- **Input integrity** — reference admission (`check_reference_admission.py`), intake-correctness
  cross-check (`check_intake_correctness.py`), property auto-binding, shared pHash.
- **Geometry truth** — curve-sweep (F.6), flatness gate (G.1), Blum lathe-profile derivation.
- **Divine Eye** — deterministic multi-signal ensemble (`divine_eye.py`): IoU/scale hard gates;
  proportion / symmetry-parity / pHash / SSIM / edge / blowout / flat / tonal-parity soft signals;
  self-uncertainty `probe` routing.
- **Multi-angle** — degenerate-view detection (`diagnose_render_multi_angle.py`) with reference-free
  self-consistency; auto-framing.
- **Eye judgment layers** — gated VLM gate (`vlm_gate.py`), per-feature verification (§3.8),
  bounded stop policy (§3.6), calibration harness (report-only + separation check).
- **Efficiency** — per-module codegen cache (§3.7 neighbor invalidation).
- **Presentation** — reference-conditional post-fx (DOF/bloom) strictly off the evaluation path.

### Added — session capability work (folded into 1.3)
- **Texture-finish analysis** — `stage1_intake/analyze_texture.py`: classifies finish
  (gem-metal / gemstone / painted-metal / worn-composite / brushed-steel / plastic) and writes
  doc-grounded MeshPhysicalMaterial scalars; `grimoire/build/threejs_texture_reference.md`.
- **Objectness (OSIM-lite)** — `stage4_review/objectness.py`: pure-stdlib HOG-like descriptor +
  cosine similarity; wired into Divine Eye as a soft signal + reconstruction-mode rescue.
- **`ground-blade` primitive** — lofted beveled cross-section (primary bevel + swedge/false edge)
  in the generator + validator whitelist.
- **Color-gate fix** — `diagnose_render.py` `color_is_gated(pass_id)` (color hard-fail only from
  the material pass onward, so clay blockouts don't false-fail).

### Added — reconstruction-fidelity upgrades (folded into 1.3)
- **Reference-grounded gradient stops** — `stage1_intake/extract_gradient_stops.py`: foreground-masked
  per-band median sampling extracts a material's true gradient from the reference (kills hand-guessed
  STOPS), names hue zones, and flags blue-leaning violet/blue stops (`B > R`) as `blue-collapse`
  (collapses to blue under tone-mapping) with a magenta-lean suggested correction.
- **`candy-coat` finish class** — `stage1_intake/analyze_texture.py`: an anodized/PVD/doppler
  dielectric-led recipe (metalness 0.35 / clearcoat 0.60 / envMapIntensity 0.70) so a saturated
  coloured coat keeps its hue instead of the environment stealing it; chrome-specular stays
  `gem-metal`, bright-clean stays `gemstone`. Plus a `paletteHueRisk` hue-survival annotation.
- **CIEDE2000 colour math** — `_shared/color_metrics.py`: sRGB→CIELAB + full ΔE00, verified against
  the canonical Sharma test pairs.
- **Colour-aware Divine Eye signals (report-only)** — `hue_zone_parity` (per-band CIEDE2000 along the
  axis; catches "purple rendered blue" that luma/structure signals miss) and `specular_wash`
  (saturation-decay + hue-drift-toward-cyan detector). Both ship report-only (no ensemble weight)
  until calibrated, so they never silently move a verdict.
- **InstancedMesh emission** — repetition systems now emit one `THREE.InstancedMesh` (single
  draw-call) instead of a per-instance `Mesh` clone loop; the `instanced-cluster` primitive resolves
  to its base geometry instead of failing.
- **`ground-blade` UV fix** — blade UVs now span the geometry's actual Y bounds instead of a
  hardcoded range, so an off-origin blade no longer clamps every face to the bright spine-rim row
  (the flat "one colour" / white-tip bug); the length gradient reads correctly.
- **Dep-free cutouts** — `extrude` supports `THREE.Shape.holes` + an `ovalLoop` helper (e.g. a
  wire-cutter oval hole) with no CSG dependency.

### Notes
- Pure Python 3.10+ stdlib in `forge/` (no pip installs). 20/20 forge test suites green.
- Grimoire lessons updated: shading realism (hue-survival under tone-mapping; reference beats prose),
  geometry patterns, self-correction.

## [1.2.0] - 2026-07-21

**Theme: Humanoid character generator.** Characters and hybrid subjects become
first-class citizens of the reconstruction pipeline, alongside a round of engine
and harness improvements to the underlying code generator.

### Added

- **Character / hybrid domain detection.** Assessment now recognizes character-like
  form language and routes the reconstruction through an anatomy-aware track instead
  of the hard-surface object path.
- **Humanoid component template.** A flattened humanoid template with measured
  head-unit proportions, facial landmark placement, and pose alignment is emitted
  from the assessment stage.
- **Proportion-lock build pass.** New gated pass that enforces anatomical proportion
  correctness before form/material work proceeds.
- **Feature-placement build pass.** New gated pass that places and validates facial
  and body landmarks against the reference.
- **Per-part character materials.** Skin, hair, cloth, and accessory materials
  integrate with the Track A detail machinery for stylized human figures with
  recognizable likeness.
- **Surface topology classification.** Parts are classified by surface topology to
  drive more accurate geometry choices.
- **Per-part color / RGBA recipes.** Explicit per-part color and RGBA material
  recipes for tighter reference matching.
- **Tier-1 diagnostics.** Diagnostic reporting layer for the generation harness.
- **Hash caching.** Content-hash caching to avoid redundant recompute across passes.
- **Real extrude / lathe / tube geometry.** Genuine extrude, lathe, and tube geometry
  generation replaces prior approximations.

### Changed

- Restructured the project layout ahead of the full harness rebuild, including
  stage-prefixed script names for clearer pipeline ordering.

### Docs

- Published a public ROADMAP (v1.0 → v1.5) and a token-cost document.
- README remake: 3D showcase, live-demo links, new logo, and animated GIF previews
  (shotgun, knife, war-hauler, Sony, Doraemon House, Crowned Loot Chest).
- Added LICENSE, CONTRIBUTING, and a community-outreach promotion playbook.
- Funding pointed to the VN donate page (MoMo / VietQR).

## [1.1.0] - 2026-07-15

**Theme: Detail-first analysis.**

### Added

- Required `detailInventory` artifact enumerating identity-defining micro-details
  (gloss zones, bevels, fasteners, engraved/painted linework, contours, stains, wear).
- Strict-quality gate that blocks code generation until every detail maps to a real
  component or material entry, preventing shallow specs from reaching the renderer.

## [1.0.0] - 2026-07-15

**Theme: Object pipeline.** Initial release.

### Added

- Staged sculpt pipeline: blockout → structure → form → material → lighting →
  interaction → optimization, with a visual gate on each pass.
- Image suitability validation and `ObjectSculptSpec` authoring (components + materials).
- Render-vs-reference review loop using side-by-side comparison sheets.
- Action-ready runtime hierarchy exposing pivots, sockets, and colliders.
- Token-efficient, code-only output (diffable TypeScript + JSON spec, no binaries).

[1.4.1]: https://github.com/hoainho/img2threejs/compare/v1.4.0...4e9fbecae0e63b370581737c89991d4dca84c287
[1.4.0]: https://github.com/hoainho/img2threejs/releases/tag/v1.4.0
[1.3.0]: https://github.com/hoainho/img2threejs/releases/tag/v1.3
[1.2.0]: https://github.com/hoainho/img2threejs/releases/tag/v1.2.0
[1.1.0]: https://github.com/hoainho/img2threejs/releases/tag/v1.1.0
[1.0.0]: https://github.com/hoainho/img2threejs/releases/tag/v1.0.0
[1.4.3]: https://github.com/img2threejs/img2threejs/releases/tag/v1.4.3