ForgeUI Feature Improvements & Known Issues

Current milestone: FORGEUI_LVGL9_COMPLETE__44_OF_44_PRACTICAL_WIDGETS_PROVEN__ESP32P4_VALIDATED__DOCUMENTATION_COMPLETE__READY_FOR_NATIVE_FORGEUI_PLATFORM__2026-08-02.

Current ForgeUI Platform milestone: FORGEUI_V3_5_4__FOURTEEN_NATIVE_COMPONENTS__POWER_FLOW_HARDWARE_VALIDATED__NATIVE_PLATFORM_RUN_COMPLETE__READY_FOR_HARDWARE_IO_PROOF__2026-08-07.

This is the living ForgeUI engineering journal. It records change, evidence and open engineering work. It does not replace or duplicate 04_FEATURE_STATUS.md, which remains authoritative for the current status of each feature and the official widget totals.

Project Summary

Totals are copied only as a dated summary pointer. Change them in 04_FEATURE_STATUS.md after proof acceptance, then refresh this summary.

Deferred platform warnings — not Native Component blockers

• ESP-Hosted host/co-processor version mismatch warning.
• 32 MB physical flash versus 16 MB binary-header configuration warning.
• GPIO32 LEDC warning during display startup.

These items are recorded for later platform work and were intentionally not investigated during Native Component closure.

Recently Improved

2026-08-06 — ForgeUI Native Component #10 Tank Level Card hardware validation

Tank Level Card is HARDWARE VALIDATED after Studio and Inspector completion, Browser Preview, Live Studio, generated LVGL and Runtime SDK alignment, duplicate-instance isolation, ESP-IDF build, ESP32-P4 flash, physical rendering, and Browser/Live/Export parity. It is intentionally display-only, exposes six silent persisted-ID setters, and generates no UserEvents. Network Status Card is the next planned Native Component; implementation has not started. The Proof Module, Hardware Simulator, automated Runtime SDK proof harness, ESP-Hosted startup investigation, and export infrastructure improvements remain deferred.

2026-08-02 — ForgeUI Native Component #3 Relay Panel physical proof

Relay Panel is PROVEN on ESP32-P4. The active component identity was Comp_MSBHEOFNU0_CVL. Physical interaction confirmed channels 0–3 ON and master ON, OFF and ON with zero-based indexing. Wi-Fi remained connected at 192.168.0.90, SD remained ready, and no crash, watchdog, reset or visible runtime failure occurred. The Runtime SDK, genuine-user channel/master hooks, private LVGL composition and UserEvents reconciliation contract are retained. PWM Controller is next and has not started.

2026-08-02 — ForgeUI Native Component #3 Relay Panel implementation

Relay Panel now traverses the existing Registry, semantic serialization, Inspector, single-object Canvas, shared Browser Preview, shared Live/Standalone generator, Runtime SDK and UserEvents ownership reconciliation. Version 1 owns 1–8 stable-ID logical channels, individual and master control, enabled state, labels/status, compact/standard presentation and seven zero-based semantic APIs. Programmatic updates are silent and hardware drivers remain application-owned. Confirmation prompts are deliberately deferred until a shared Browser/LVGL primitive exists. Status is IMPLEMENTED — READY FOR ESP32-P4 PHYSICAL PROOF.

2026-08-02 — ForgeUI Native Component #2 Sensor Tile proof

Sensor Tile passed physical validation on the Waveshare ESP32-P4. Semantic serialization, Browser Preview parity, shared Live/Standalone output, all six Runtime SDK setters and the genuine-user click hook are validated. Stable Native Component identity keeps the public Runtime SDK names unchanged across regeneration, while UserEvents ownership reconciliation preserves the active developer hook and prevents stale custom APIs from compiling. Sensor Tile is PROVEN. Relay Panel is the next implementation target and has not begun.

2026-08-02 — ForgeUI Native Component #2 Sensor Tile implementation

Sensor Tile now traverses the existing Registry, semantic serialization, Inspector, single-object Canvas, shared Browser Preview, shared Live/Standalone generator, Runtime SDK and UserEvents. Version 1 supports ten engineering sensor types, numeric formatting, measurement/threshold ranges, automatic severity, trend, progress and timestamp. Six semantic APIs and optional root click hooks are collision-safe across instances. Status is IMPLEMENTED — READY FOR ESP32-P4 PHYSICAL PROOF. Relay Panel has not begun.

2026-08-02 — ForgeUI Native Component #1 Dashboard Card proof

Dashboard Card passed physical validation on the Waveshare ESP32-P4. Browser Preview and hardware matched closely; Live Studio and Standalone Export behaved consistently; Runtime setters and UserEvents operated correctly; the Card remained one Canvas object; and multiple instances remained independent. Touch stayed responsive and RAM stable, with no crash, watchdog reset or rendering corruption. Dashboard Card is PROVEN. This is the first ForgeUI Native Component milestone and is separate from the completed 44/44 practical LVGL history. Sensor Tile is next; implementation has not begun.

2026-08-02 — Practical LVGL 9.2 completion

Menu passed physical validation on the Waveshare ESP32-P4. Two independent instances rendered correctly; child-page and Back navigation remained correct through approximately ten cycles; Wi-Fi, Diagnostics, SD Card and Storage remained operational; Wi-Fi stayed connected; and internal RAM remained stable at approximately 42 KB. No crash, watchdog reset or rendering corruption was observed. Menu is PROVEN, completing 44 of 44 practical registered LVGL widgets/components physically proven. Lottie remains intentionally excluded.

The next chapter is ForgeUI Platform, ordered as ForgeUI-native Widgets, Dashboard Widget Family, Dashboard Designer, Template Library, Runtime SDK Expansion, Background Designer and Higher-level Application Components.

2026-08-02 — Final practical LVGL Menu implementation

Menu now traverses the authoritative Registry, Tray, Canvas, Inspector, Browser Preview and shared Live/Standalone generator as a native multi-page navigation framework. A stable serialized page/section/item tree owns labels, subtitles, native symbols, enabled state and target-page links. Browser Preview supports forward/back history; export uses native lv_menu_create, page, section, container, separator and load-page APIs. Focused validation passes. Menu is IMPLEMENTED — READY FOR PHYSICAL PROOF, not PROVEN. The physical proof total remains 43 until hardware acceptance; Lottie remains excluded.

2026-08-02 — Closure Batch 2 Window ESP32-P4 proof

Two native LVGL Window instances rendered simultaneously on the Waveshare ESP32-P4 1024×600 display. Both headers and close controls rendered, each close control hid only its owning Window, and both instances closed independently without crash, reboot, watchdog or obvious rendering corruption. The export used lv_win_create, lv_win_get_header, lv_win_add_title, lv_win_add_button and lv_win_get_content. Window is PROVEN and the practical LVGL 9.2 proof total is 43. Menu is the only remaining practical closure widget; Lottie remains intentionally excluded. This proof does not claim scrolling, populated child-content behavior, action callbacks or public Runtime SDK/UserEvents hooks.

2026-08-02 — Closure Batch 1 ESP32-P4 proof

Span, Animation Image and Image Button passed physical ESP32-P4 validation and Canvas, Browser Preview, Live Studio and Standalone parity. Span proved ordered native rich text, semantic and explicit colours, sizing, underline and alignment. Animation Image proved Asset Manager authoring, ordered animation and zero-frame parity. Image Button proved native released, pressed, disabled and click behavior. The practical LVGL 9.2 proof total is now 42, with only Window and Menu remaining. No hardware regressions were observed.

2026-08-02 — Inspector native dropdown theme refinement

Chakra Inspector dropdowns are native HTML selects, not portal-rendered Chakra menus. The Studio previously forced pale selected text globally without owning the native option palette, allowing Windows to open a light popup with low-contrast text. One shared ForgeUI control contract now declares a dark native colour scheme plus dark option background, readable text, hover, teal-selected, disabled and keyboard-focus states. The correction applies to semantic colours, sizes/fonts, alignment, overflow, themes and widget options; it is not Span-specific and does not change widget data or export behavior.

2026-08-02 — Span authoring workflow completion

Span previously had native export and a minimal panel, but its index-keyed, unlabelled collection controls did not form a dependable authoring workflow and the empty state was inert. One typed normalized span record now owns defaults, Inspector edits, both previews and export. Stable IDs and immutable helpers cover add, edit, reorder and removal; explicit colour is a clear override of the selected semantic role; alignment and clip/ellipsis are labelled. The empty placeholder creates the first persisted span. This is an authoring workflow repair subsequently accepted during Span's ESP32-P4 physical proof.

2026-08-02 — Animation Image authoring workflow completion

Animation Image now opens the existing Asset Manager in multi-select mode from both its empty-state button and Inspector. Applying a selection updates the ordered frame IDs in one component transaction. The Inspector supports individual replacement, empty-slot addition, Up/Down reordering, removal, duration, looping and initial running state. Browser Preview responds to the same serialized list consumed by Live and Standalone export. No second asset picker, registry or conversion path was introduced.

2026-08-01 — Animation Image empty-state parity refinement

Canvas and Browser Preview already communicated that frames must be added, but the generated zero-frame fallback retained native object defaults and displayed as a white clipped panel on ESP32-P4. The zero-frame path now uses an identical transparent, semantic-border panel with centred Add animation frames text in Canvas, Browser, Live and Standalone. Valid one-frame and multi-frame native lv_animimg output is unchanged. This is recorded as a visual parity refinement, not an implementation failure.

2026-08-01 — LVGL 9.2 practical closure Batch 1

Span, Animation Image and Image Button now use the authoritative Registry, Tray, Canvas, Inspector, shared Browser Preview, canonical uploaded-image pipeline and shared Live/Standalone LVGL generator. Span remains presentation-only. Image Button reuses the collision-safe enabled API and 95_UserEvents click path. All three subsequently passed ESP32-P4 validation and are PROVEN. Window and Menu remain next.

2026-08-01 — Batch D physical proof and Standard Widget Library completion

• QR Code: Registry-to-export software slice, typed payload editing,

semantic colours, native LVGL generation, shared previews and collision-safe multiple instances pass focused validation. ESP32-P4 display, successful mobile scan and Live/Standalone parity passed. Status is PROVEN.

• Icon Button: Added the missing Inspector control for serialized disabled

state. Canonical icon presentation, Browser pressed feedback, native LVGL pressed/disabled styling, the guarded enabled setter, genuine click hook and collision-safe multiple instances pass focused validation and physical ESP32-P4 operation. Status is PROVEN.

• Icon: Registry, Inspector, canonical ownership, semantic theme,

Browser/Canvas rendering, runtime generation and multiple-instance paths were audited without finding a new architectural defect and passed final ESP32-P4 re-proof. Status is PROVEN.

• Canvas: Standard Canvas preview/export and the Studio editing surface were

audited across selection, movement, resizing, supported rotation, ordering, hit testing, fractional geometry, property synchronization and Browser Preview handoff and physical Live/Standalone parity. No duplicate Canvas runtime was introduced. Status is PROVEN.

2026-08-01 — Batch C Clock and Wi-Fi Status physical proof

• Subsystem: Proven Widget Pipeline, Clock and Standard Wi-Fi Status.
• Improvement: Audited Clock formatting/parity and removed preview-only

literal styling drift. Replaced the fixed global Wi-Fi label with a shared serialized presentation model, Inspector controls, Canvas/Browser parity, collision-safe native labels, existing-backend state projection and optional RSSI. Internet Available is future-compatible.

• Ownership: Clock remains RTC-owned and Wi-Fi Status remains a presentation

consumer of 30_WIFI; neither emits a setter or 95_UserEvents hook.

• Validation: Focused Clock/Wi-Fi software suites pass and Canvas, Browser,

Live and Standalone behavior was physically accepted on ESP32-P4. Both are PROVEN.

2026-08-01 — End-of-sprint Standard proof and parity closure

• Subsystem: Button, Heading, Box, Divider, Text, Icon and native TileView.
• Improvement: Button, Heading, Box and Divider completed physical proof;

Heading gained multiline/alignment parity, Box gained authoritative child ownership and Browser nesting parity, Divider gained visible default vertical geometry, Text gained multiline wrapping/export parity, Icon gained source-aware 92% automatic fitting with centered native pivots, and TileView retained its native replacement for the former synthetic export.

• Reason: Hardware-first comparison exposed presentation, nesting, wrapping,

sizing and clipping differences that automation alone could not establish.

• Validation: Button, Heading, Box and Divider passed ESP32-P4 proof. Text

later passed physical proof, and Icon passed final Batch D re-proof. Both are included in the completed 39-widget proven total.

2026-08-01 — Standard Text parity

• Subsystem: Inspector, shared preview renderer and native LVGL exporter.
• Improvement: Standard Text gained unrestricted multiline authoring,

preserved whitespace/newlines, bounded Canvas/Browser wrapping, alignment parity and explicit native label geometry with LV_LABEL_LONG_WRAP.

• Reason: ESP32-P4 proof exposed a label that rendered only a short fragment

instead of the complete wrapped value.

• Validation: Focused Text suites passed 18/18; a broader documentation,

preview and export selection passed 72/72. Corrected hardware proof remains open, so this improvement is not a proof promotion.

2026-07-31 — Native TileView export and proof

• Subsystem: Standard TileView preview, generated runtime and UserEvents.
• Improvement: Replaced the simultaneous synthetic four-panel export with

native lv_tileview_create() / lv_tileview_add_tile() paging, retained coordinates, a silent setter and one genuine-user callback per transition.

• Reason: The synthetic representation did not exercise native LVGL paging

or match the intended hardware interaction.

• Validation: Horizontal and vertical navigation, coordinates (0,0)

through (1,1), repeated navigation and surrounding Wi-Fi, SD, TabView, Spinbox and List stability were physically verified on ESP32-P4.

2026-07-31 — Native Spinbox vertical slice

• Subsystem: Registry, Tray, Canvas, Inspector, Browser Preview, native

export, Runtime SDK, UserEvents, live firmware and Standalone Export.

• Improvement: Added native LVGL Spinbox with signed values, decimal display,

selected-digit editing, rollover, clamping, collision-safe instances and export-time feature gating.

• Reason: ForgeUI needed a native digit-selection control distinct from the

free-form NumberInput architecture.

• Validation: Live and Standalone builds, touch editing, setters, hooks,

multiple instances and physical ESP32-P4 behaviour passed.

2026-07-31 — Widget Registry authority cleanup

• Subsystem: Standard Widget Registry and Tray discovery.
• Improvement: Consolidated canonical identity, category, search metadata,

defaults, insertion, capability flags, documentation targets and availability in ForgeUIWidgetRegistry.ts; legacy lists became projections.

• Reason: Parallel widget catalogues allowed metadata and insertion behaviour

to drift.

• Validation: Registry completeness, unique metadata, documentation targets,

Tray insertion, search, keyboard access, undo/redo and hydration regressions are recorded in the architecture validation history.

2026-07-31 — Runtime SDK direction and contracts

• Subsystem: Generated application interface.
• Improvement: Documented and expanded the generated semantic layer above

private LVGL objects: silent FG_Set_* APIs, genuine-user FG_On_* hooks, collision-safe names, ownership boundaries and feature gating.

• Reason: Application code needs a stable integration surface without editing

replaceable generated LVGL.

• Validation: Spinbox and TabView contracts have physical evidence; broader

generated API and preservation suites are recorded in the code maps.

2026-07-31 — Standard widget proof milestones

• Subsystem: List, TabView, TileView, Spinbox and Button proof work.
• Improvement: Added or strengthened native runtime behaviour, callback

suppression, generated-code parity and physical evidence for the current proof batch.

• Reason: Automation alone is insufficient for touch, geometry and firmware

parity claims.

• Validation: Individual results are recorded in the Physical Proof Ledger

below and remain authoritative in 04_FEATURE_STATUS.md.

2026-07-30 — Documentation Centre and Runtime SDK documentation

• Subsystem: Public ForgeUI website and engineering references.
• Improvement: Replaced placeholder documentation with a searchable,

statically exported Documentation Centre covering Studio workflow, generated C ownership, Runtime SDK, ESP-IDF integration and hardware validation.

• Reason: Public documentation needed to reflect the current native export

architecture and its evidence boundaries.

• Validation: Website production build, static routes, sitemap, local search,

internal links and documentation tests are part of the website validation suite.

Resolved Issues

2026-08-01 — Canonical Image Contain export parity

• Issue: Native Image export used scale 256 and clipped a centred uploaded

source even though Canvas and Browser Preview showed the complete image.

• Root cause: LVGL conversion replaced the temporary asset URL with its

persistent URL; the registry treated that as artwork replacement and cleared correct intrinsic dimensions, forcing the legacy scale-256 fallback.

• Resolution: Preserve intrinsic dimensions during URL replacement, recover

dimensions for legacy persisted assets, and use one source-aware canonical Contain model across Canvas, Browser Preview, Live and Standalone export.

• Regression protection: Landscape/portrait/bounds combinations, Contain,

Cover, Native, persistence/reload, opacity, visibility, non-clickable output, exporter tracing and Live/Standalone parity tests.

• Physical validation: The 1024 × 600 proof source in 240 × 160 bounds

generated calculated_scale=60, emitted_scale=60 and lv_image_set_scale(fg_image, 60). ESP32-P4 displayed the complete image without clipping. IMAGE — PROVEN.

2026-08-01 — Standard Line physical proof

• Resolution: Native lv_line_create() output passed geometry, horizontal,

vertical and arbitrary-angle rendering, colour, opacity, thickness, multiple instances and Live/Standalone parity on ESP32-P4. LINE — PROVEN.

2026-08-01 — Text wrapping correction (software resolved; re-proof open)

• Issue: Standard Text displayed only a short fragment and failed to wrap in

its configured bounds on ESP32-P4.

• Root cause: The native branch did not previously own complete label

geometry/wrap behaviour, and preview whitespace relied on browser defaults. The inspected flashed artifact also assigned text before size and long mode.

• Resolution: Use a multiline Inspector editor and one normalized text model;

previews use preserved whitespace and bounded wrapping; export applies actual width/height and LV_LABEL_LONG_WRAP before the complete escaped text plus normalized alignment/font styles.

• Regression protection: Inspector long-value/newline tests, JSON reload,

shared Canvas/Browser rendering tests, all alignments, full escaped C, geometry/call-order assertions and explicit absence of DOT/CLIP modes.

• Physical validation: Complete. The corrected Text build has been

physically accepted across Live and Standalone and Text is PROVEN.

2026-08-01 — Icon native scaling and clipping correction

• Issue: A 64 × 64 uploaded FiAirplay descriptor was emitted into a 48 × 48

native image object at scale 256, clipping the centered image at its bounds.

• Root cause: Uploaded images retained source scale instead of deriving

scale from the shared rendered target; exact-edge automatic fitting also left no allowance for transformed anti-aliased pixels.

• Resolution: Canvas, Browser Preview and export now share a 92% automatic

fit of the shorter component edge when boxSize is unset. Native export uses actual descriptor dimensions, a centered pivot and LV_IMAGE_ALIGN_CENTER. Explicit boxSize remains exact.

• Regression protection: Source-size, padding, scale, pivot, alignment,

opacity, recolour and deterministic Live/Standalone block tests.

• Physical validation: Final flash and visual comparison passed during

Batch D. Icon is PROVEN.

2026-07-31 — Spinbox export coordinates

• Issue: Generated increment/decrement helpers could be placed off-screen or

use malformed coordinates.

• Root cause: Helper geometry did not consistently derive from the actual

Spinbox component bounds.

• Resolution: Derive the field and helper-button coordinates from normalized

component geometry and keep the buttons in the component's generated layout.

• Regression protection: Focused Spinbox geometry/export tests and export

preflight coverage.

• Physical validation: Passed in live and Standalone ESP32-P4 firmware.

2026-07-31 — Canvas click suppression

• Issue: Canvas drag/selection handling could consume Spinbox helper clicks

and leave the preview state stale.

• Root cause: Wrapper pointer handling did not distinguish component

authoring gestures from control interaction.

• Resolution: Corrected the Canvas interaction path while retaining normal

selection and drag behaviour.

• Regression protection: Shared preview and Canvas interaction/state tests.
• Physical validation: Final Spinbox proof passed.

2026-07-31 — Synthetic TileView export

• Issue: TileView exported four ordinary visible child panels instead of a

native swipeable LVGL TileView.

• Root cause: The initial implementation modeled appearance without native

paging semantics.

• Resolution: Replaced it with native tiles, direction constraints,

active-tile lookup and retained coordinate transitions.

• Regression protection: Native-constructor, tile-map, setter, callback and

Canvas/Browser parity tests.

• Physical validation: Passed horizontal/vertical ESP32-P4 navigation and

repeated stability checks.

2026-07-31 — List callback validation

• Issue: List required proof that a controlled tap emitted exactly one

callback with the correct row identity.

• Root cause: Software coverage alone did not prove physical touch/event

behaviour.

• Resolution: Retained native list/button ownership and collision-safe

indexed/text hooks, then exercised rows individually.

• Regression protection: Exporter callback/index/text and collision tests.
• Physical validation: Passed; controlled taps returned matching row indices

and labels without duplicate callbacks.

2026-07-31 — TabView startup suppression

• Issue: Initial selection and programmatic selection could be confused with

genuine user changes.

• Root cause: Native value-change events needed one guarded retained-state

transition boundary.

• Resolution: Startup hydration and setters remain silent; genuine effective

touch changes update state and emit one hook.

• Regression protection: Initial selection, repeated selection, clamp,

collision and callback-count tests.

• Physical validation: Passed for physical selection of tab indices 0, 1

and 2.

2026-07-31 — SD filename compatibility

• Issue: SD workflows could fail when generated or copied filenames did not

remain compatible with the bounded firmware path/name contract.

• Root cause: Host/export and firmware filename expectations were not fully

aligned.

• Resolution: Aligned bounded filename/path handling and retained safe

validation for storage operations.

• Regression protection: Export-server and storage-path validation plus

bounded firmware checks.

• Physical validation: SD remained ready during the recorded widget proof

sessions; storage operation evidence is maintained in the hardware guide.

Known Active Issues

P1 — Standard Text hardware re-proof

• Subsystem: Standard Text / generated LVGL.
• Description: The software parity correction is implemented, but the new

C has not yet been clean-built, flashed and visually verified with the long paragraph and explicit multiline proof strings.

• Current workaround: Use explicit manual line breaks and generous bounds,

but do not treat the result as proven.

• Next action: Inspect the regenerated live and Standalone Text blocks,

clean-build/flash the reference ESP32-P4, and verify full wrapping and all alignments before changing totals.

• Date last reviewed: 2026-08-01.

P1 — Standard Icon hardware re-proof

• Subsystem: Standard Icon / generated LVGL image sizing.
• Description: Source resolution and scaling now work, and the native

clipping defect has a shared 92% automatic-fit correction, but the corrected Live and Standalone builds still need final visual hardware acceptance.

• Current workaround: Set an explicit conservative boxSize; do not treat

the current software result as proven.

• Next action: Compare regenerated Live and Standalone Icon blocks, flash

both and confirm all anti-aliased edges match Canvas and Browser Preview.

• Date last reviewed: 2026-08-01.

P2 — Existing TypeScript diagnostics

• Subsystem: Studio test/preview typing.
• Description: Full tsc --noEmit currently reports the pre-existing

CircularProgress BrowserPreview JSX return-type diagnostic and a StandardListPreview polymorphic type prop diagnostic. The Text path adds no TypeScript diagnostic.

• Current workaround: Run focused suites and inspect TypeScript output for

changed-path diagnostics; do not report the repository-wide check as clean.

• Next action: Resolve each typing issue in its owning widget task without

weakening compiler settings.

• Date last reviewed: 2026-08-01.

P2 — Remaining Standard Widget proof backlog

• Subsystem: Proven Widget Pipeline.
• Description: The authoritative ledger records 5 Standard widgets still

outside full physical proof. QR Code has software coverage but still needs recorded phone scans; Text, Clock and Wi-Fi Status are now PROVEN.

• Current workaround: Use the per-widget status and evidence boundaries in

04_FEATURE_STATUS.md; never infer hardware proof from automation.

• Next action: Complete one isolated widget proof at a time through live and

Standalone generated-C comparison, ESP-IDF build, flash and physical review.

• Date last reviewed: 2026-08-01.

Physical Proof Ledger

This is a compact evidence journal, not the full status catalogue.

Validation History

Only completed, recorded runs belong in this section.

Failures remain visible rather than being rewritten as historical passes.

Current Sprint

• Current objective: Begin ForgeUI Platform development on the completed

practical LVGL 9.2 foundation.

• Current proven pipeline set: All 44 practical registered Standard LVGL

widgets/components.

• Next action: Begin ForgeUI-native Widgets. Keep Lottie explicitly

excluded pending a separate ThorVG/vector/C++ and framebuffer decision.

Engineering Notes

Registry authority

ForgeUIWidgetRegistry.ts is the authoritative Standard Widget catalogue. Tray data and compatibility sets derive from it. New parallel lists are prohibited.

Proven Widget Pipeline

Proof follows Official LVGL Reference → Registry → Tray → Canvas → Inspector → Browser Preview → native export → Runtime SDK where applicable → UserEvents for genuine interaction → live firmware → Standalone Export → ESP32-P4 → documentation. Automation readiness is not physical proof.

Runtime SDK philosophy

The Runtime SDK is generated with each interface. It is a semantic boundary above private LVGL, not a universal binary library. Setters project state silently; hooks report genuine user actions; presentation-only widgets remain API-free unless their Registry contract says otherwise.

Live versus Standalone ownership

Both workflows consume the same native LVGL generator and preflight. Live firmware is Studio-managed. A Standalone project becomes developer-owned, with product behaviour kept in 95_UserEvents or ordinary application modules rather than replaceable 90_Studio_Export files.

Feature gating

Board Profiles, Widget Registry capabilities and serialized usage determine generated features, sources and dependencies. Unused runtime families should not be included by broad type exclusions or hard-coded board checks.

Hardware-first validation

Canvas and Browser Preview are authoring evidence; generated C is export evidence; a successful build is firmware evidence; photographed and observed ESP32-P4 behaviour is physical proof. The journal preserves these boundaries.

2026-08-01 — Generic Fi Icon Runtime

Authoritative architecture: `09_FORGEUI_FI_RUNTIME_GUIDE.md`. This journal records the milestone and outstanding proof rather than duplicating the guide.

• Subsystem: Standard Icon, Runtime SDK, UserEvents and export server.
• Improvement: Added per-instance, component-name-based Visible, Opacity

and Color APIs in generated 96_FiRuntime.c/.h, plus default-off optional click hooks in 95 for image-backed and supported symbol-backed icons.

• Reason: A selected Fi asset needed to become a reusable runtime object

without coupling public APIs to catalogue identity or emitting unused code.

• Validation: Focused generator, naming, Registry, canonical icon, selector,

preview and export-server tests passed. ESP32-P4 evidence now proves only the 90 → 95 click path, so overall status is PROVEN ON ESP32-P4 after Batch D completed the presentation path.

Resolved — Fi Icon Runtime physical proof

• Priority: Complete
• Subsystem: Standard Icon runtime presentation and optional input.
• Description: Software contracts are complete. Click cardinality and three

collision-safe click-hook instances are physically proven through 90 → 95. The 90 → 96 presentation path and remaining acceptance checks were completed on ESP32-P4 during Batch D.

• Resolution: Batch D physically proved the Icon presentation setters,

click-disabled behavior, independent instances and Standalone parity. Icon and the complete Fi Runtime are PROVEN.

• Date last reviewed: 2026-08-01

2026-08-01 — Fi Icon Runtime validation