# TKForge-21
Structured Tkinter GUI Builder

Changelog
=========

This document tracks architectural evolution, stability milestones,
behavior guarantees, and known drift-sensitive areas.

The goal is deterministic growth without entropy.


---------------------------------------------------------------------
v0.1.0 — Initial Builder Baseline
---------------------------------------------------------------------

Core Features:
- Project model (Project, GUIElement dataclasses)
- JSON save/load
- EditorSurface with absolute positioning
- Widget instantiation (Button, Label, Entry, Text, Frame, Checkbutton, Radiobutton)
- Inspector for property editing
- Python export generator
- Render View (in-memory execution preview)
- GPT text export
- GPT JSON export

Behavior Guarantees:
- Deterministic widget placement
- Direct geometry editing
- Live property updates
- Stateless export generation
- No background processes

Architectural Notes:
- Absolute layout model (no grid/pack export yet)
- Flat hierarchy (parent_id reserved for future nesting)
- Theme switching initially implemented
- No delete support


---------------------------------------------------------------------
v0.2.0 — Stable Editing Baseline
---------------------------------------------------------------------

Major Improvements:
- Delete key removes selected widget safely
- Inspector field help system (FIELD_DESCRIPTIONS)
- Help panel with dynamic schema reflection
- Widget templates introduced (WIDGET_TEMPLATES)
- Theme switching removed (single canonical theme)
- set_theme() removed to reduce rebuild complexity
- Project open/save stability restored

Behavior Guarantees:
- Delete is idempotent and state-safe
- No orphan widget_map references
- Inspector always synchronized with selection
- Render View executes without writing temp files
- Project open does not mutate theme state
- No runtime UI rebuild on open

Resolved Issues:
- set_theme() dangling call during project load
- Inspector field_help duplication bug
- Notebook tab contrast styling conflict
- Project properties dialog clipping (geometry too small)

Drift-Sensitive Areas:
- EditorSurface.delete_selected()
- InspectorPanel.set_element()
- file_open() in app.py
- HelpPanel dynamic reflection
- Generator export consistency with model schema

These must remain tightly aligned with model structure.


---------------------------------------------------------------------
Architectural Principles (Locked)
---------------------------------------------------------------------

1. Deterministic State
   - Project model is the single source of truth.
   - Live widgets reflect model, not vice versa.

2. No Silent Magic
   - All behavior is explicit.
   - No hidden background rebuild logic.

3. Predictable File Structure
   Each module follows:
   - Imports
   - Class docstring
   - __init__
   - Public API
   - Internal logic
   - Event handlers

4. GPT-Compatible Structure
   - Clear section headers
   - Explicit naming
   - Schema reflection available
   - Export format stable

5. Single Theme Doctrine
   - Canonical dark theme
   - No runtime theme switching
   - Reduced rebuild complexity


---------------------------------------------------------------------
Known Limitations (Intentional)
---------------------------------------------------------------------

- No nested widget hierarchy (parent_id reserved)
- No alignment guides or snapping
- No grid/pack layout export
- No undo/redo stack
- No validation layer for overlap
- No command stub validation
- No template enforcement beyond default props

These are deliberate omissions for stability.


---------------------------------------------------------------------
Future Consideration (Not Committed)
---------------------------------------------------------------------

Potential Directions:
- Undo/Redo stack
- Alignment guides
- Snap-to-grid
- Overlap detection
- Event stub auto-generation enforcement
- Nested containers
- Layout mode switch (absolute vs structured export)

These must not compromise deterministic behavior.


---------------------------------------------------------------------
Stability Status
---------------------------------------------------------------------

Current Build Status:
✔ Full create/edit/delete loop stable
✔ Save/Load stable
✔ Render View stable
✔ GPT export stable
✔ Inspector help stable
✔ Help reflection stable

Baseline declared stable.

Perfect. You only need the **new additions** since your last documented state.

Below is **clean, paste-ready content** to append under `v0.2.0` as an incremental stability update (no formatting traps, no code blocks).

---

---

## v0.2.1 — Snap Grid & Basic Release Freeze

Major Improvements:

* Snap-to-grid introduced (10px increments)
* Grid snapping applied to:

  * Widget placement
  * Widget dragging
  * Geometry edits (x, y)
* Grid logic centralized via internal _snap() helper
* Basic / Lite version freeze declared
* Version display added to window title
* README and Release Notes standardized
* Deterministic packaging workflow documented

Behavior Guarantees:

* All widget placement is grid-aligned
* Drag movement cannot produce fractional geometry drift
* Geometry edits remain bounded and sanitized
* Project version visible in application title bar
* Snap behavior does not mutate stored geometry unexpectedly
* No regression in delete behavior
* No regression in export behavior

Resolved Issues:

* Missing Save button in Project Properties dialog (geometry clipping)
* Project Properties dialog height insufficient for controls
* set_theme() legacy references removed fully
* Inspector commit edge-case after selection change
* PyInstaller import path alignment for package structure

Drift-Sensitive Areas:

* EditorSurface._snap()
* EditorSurface._on_widget_drag()
* EditorSurface.add_element_at()
* Geometry handling inside update_element()
* Title refresh logic (_refresh_title)
* PyInstaller spec and package imports

Snap behavior must remain consistent across:

* Live placement
* Drag operations
* Manual geometry edits

Do not introduce alternate geometry flows without routing through _snap().

---

## Basic / Lite Release Identity (Locked)

This version is officially designated:

TKForge-21 v0.2.0-basic (engine v0.2.1 snap patch)

Scope Definition:

* Absolute layout only
* Single canonical theme
* Deterministic grid alignment
* Flat hierarchy model
* No runtime layout switching
* No alignment guides (visual)
* No undo stack

This release is a structural freeze point.

Future engine upgrades must branch forward without mutating this baseline.

---

## Packaging Stability Notes

Verified Build Path:

* python main.py runs clean
* No dynamic module import errors
* No attribute resolution errors
* PyInstaller onefile build validated
* Dist binary runs independently
* No orphan theme references
* No runtime rebuild dependency

Packaging Command:
pyinstaller --onefile --name TKForge-21 main.py

Clean build recommended before freeze:
Remove build/
Remove dist/
Remove **pycache**/

---

## Architectural Reinforcement

Snap-to-grid establishes first structural constraint layer.

This marks transition from:
Free-form editor
to
Constrained deterministic layout engine

Future features must respect:

* Model as single source of truth
* Grid alignment invariant
* No hidden state mutation
* No silent rebuild logic

Determinism remains primary doctrine.

---

## Stability Status Update

Current Build Status:
✔ Create/edit/delete stable
✔ Snap-to-grid stable
✔ Save/Load stable
✔ Render View stable
✔ GPT export stable
✔ Inspector help stable
✔ Help reflection stable
✔ Packaging validated

Basic / Lite release declared frozen.

---

Current Status:

• Baseline documented
• Snap integrated
• Packaging stable
• Release identity locked


