progress: ImGui Port - Desktop UI + ImGui rendering performance overhaul

Full ImGui desktop environment (desktop.pas):
- Gradient wallpaper, taskbar with clock, start menu
- Desktop icons with click-to-open
- Windowed apps: System Info, Terminal, File Browser, Task Manager
- Terminal dispatches to registered kernel commands with output capture

Performance: Software rasterizer rewrite (imgui.pas, imgbridge.c)
- Quad detection: merge consecutive triangle pairs into fast rect fills
- 3 new fast-path rect fillers (solid/gradient/textured) using REP STOSD
  and 16.16 fixed-point integer inner loops
- Triangle rasterizer rewritten with fixed-point edge functions
- Back-buffer clear: DrawPixel loop -> REP STOSD (~200x faster)
- Render stat debug counters added

ISR-safe input buffering (imgbridge.c)
- Keyboard/mouse events buffered in lock-free ring buffers from ISR context
- Drained once per frame from main loop to prevent data races

Other changes:
- imguitypes.pas: InputTextFlags renumbered for cimgui 1.91+
- video.pas: backBufferLocation getter added
- kernel.pas: VFS init moved earlier, main loop uses desktop_frame,
  mouse hook uses ISR-safe buffering
- lmemorymanager.pas: kalloc/kfree exported with public aliases for C linkage
- scheduler.pas: Root_Task moved to interface for desktop task manager
- terminal.pas: freeParams exposed in interface

.drone.yml

@@ -50,17 +50,3 @@ steps:
       - |
         curl -X PUT https://gitea.spexeah.com/api/packages/Spexeah/generic/asuro-iso/latest/Asuro.iso \
         -H "Authorization: token $GITEA_TOKEN" --upload-file "Asuro-$(git rev-parse --short HEAD).iso"
-
-  - name: msg status
-    image: appleboy/drone-discord
-    failure: ignore
-    depends_on:
-      - compile
-    when:
-      status: [success, failure, changed]
-    settings:
-      webhook_id:
-        from_secret: discord_webhook_id
-      webhook_token:
-        from_secret: discord_webhook_secret
-      message: "**Asuro Build**\n\n{{#success build.status}}✅ Build successful!\n\n{{else}}❌ Build failed!\n\n{{/success}}Repository: `{{repo.namespace}}/{{repo.name}}`\nBranch: `{{commit.branch}}`\nCommit: `{{commit.sha}}`\nAuthor: `{{commit.author}} <{{commit.email}}>`\n\nGitea Diff: [Link](<{{commit.link}}>)\nDrone Build: [Link](<{{build.link}}>)\n\nMessage: {{commit.message}}"

.gitattributes

@@ -1,8 +1 @@
 * text=auto eol=lf
-lvglh/** linguist-vendored
-lvgl/** linguist-vendored
-.vscode/* linguist-vendored
-lib/* linguist-generated
-release/* linguist-generated
-iso/* linguist-generated
-*.asm linguist-detectable

.gitignore

@@ -11,8 +11,3 @@
 /*.img
 src/include/asuro.pas
 localenv.json
-/lvgl/
-dockerout.txt
-AGENTS.md
-*.log
-/doc/*.md

.mailmap

@@ -1,13 +0,0 @@
-# Map all Aaron identities to a single preferred identity
-Aaron Hance <[email protected]> aaron <aaron@6dbc8c32-bb84-406f-8558-d1cf31a0ab0c>
-Aaron Hance <[email protected]> aaronhance <[email protected]>
-Aaron Hance <[email protected]> aaron hance <[email protected]>
-Aaron Hance <[email protected]> Aaron <[email protected]>
-
-# Map all Kieron identities to a single preferred identity
-Kieron Morris <[email protected]> kieron <kieron@6dbc8c32-bb84-406f-8558-d1cf31a0ab0c>
-Kieron Morris <[email protected]> Kieron <[email protected]>
-Kieron Morris <[email protected]> t3hn3rd <[email protected]>
-
-# Map goose's multiple identities
-goose <goose@6dbc8c32-bb84-406f-8558-d1cf31a0ab0c> goose <[email protected]>

Dockerfile

@@ -5,11 +5,14 @@ VOLUME ["/code"]
 ENV DEBIAN_FRONTEND=noninteractive
 RUN dpkg --add-architecture i386
 RUN apt-get update && apt-get install -y \
-	curl dos2unix wget git make nasm binutils xorriso grub-pc-bin gcc gcc-multilib && \
+	curl dos2unix wget git make nasm binutils xorriso grub-pc-bin \
+	gcc-multilib g++-multilib && \
 	apt-get clean my room
 
+RUN git clone --depth=1 --recurse-submodules https://github.com/cimgui/cimgui.git /cimgui
+
 SHELL ["/bin/bash", "-c"]
-ARG FPC_VERSION=3.2.2
+ARG FPC_VERSION=2.6.4
 RUN curl -sL https://sourceforge.net/projects/freepascal/files/Linux/$FPC_VERSION/fpc-$FPC_VERSION.i386-linux.tar/download | tar -xf - && \
 	pushd fpc-$FPC_VERSION.i386-linux && ./install.sh && popd && \
 	rm -rf fpc-$FPC_VERSION.i386-linux

compile.sh

@@ -7,7 +7,7 @@ echo "Asuro Compilation"
 echo " "
 
 #Compile Stub.asm
-rm -f lib/*
+rm lib/*
 
 runOrFail() {
 	local binary=$1
@@ -23,7 +23,7 @@ runOrFail() {
 declare -a run_steps=(
 	"compile_stub.sh" "Failed to compile stub!"
 	"compile_vergen.sh" "Versions failed to compile"
-	"compile_lvgl.sh" "Failed to compile LVGL!"
+	"compile_imgui.sh" "Failed to compile ImGui!"
 	"compile_sources.sh" "Failed to compile FPC Sources!"
 	"compile_link.sh" "Failed linking!"
 	"compile_isogen.sh" "Failed to create ISO!"

compile_imgui.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+echo " "
+echo "======================="
+echo " "
+echo "Compiling ImGui (cimgui)..."
+echo " "
+
+IMGUI_DIR=/cimgui
+IMGUI_SRC=$IMGUI_DIR/imgui
+BRIDGE_SRC=src/driver/video/imgui
+
+# Flags shared by all C/C++ compilation units:
+#   -m32              -> i386 target
+#   -ffreestanding    -> no implicit stdlib inclusion
+#   -fno-builtin      -> don't inline memcpy/memset/etc. so our stubs are used
+#   -O2               -> optimise for speed
+#   -ffunction-sections -fdata-sections -> allow --gc-sections in linker
+C_FLAGS="-m32 -ffreestanding -fno-builtin -O2 -ffunction-sections -fdata-sections"
+
+# Extra flags for C++ translation units (cimgui/imgui sources):
+#   -fno-exceptions         -> no stack-unwinding machinery
+#   -fno-rtti               -> no typeinfo / dynamic_cast
+#   -fno-use-cxa-atexit     -> don't emit __cxa_atexit calls for static dtors
+#   -fno-threadsafe-statics -> no guard-variable emission for local statics
+# NOTE: *not* -ffreestanding / -fno-builtin here — imgui includes <cmath> and
+#       other hosted headers that refuse to compile in freestanding mode.
+#       The object files are archived into a static lib and linked freestanding;
+#       any hosted-stdlib calls (malloc/free/sin/cos/…) resolve to crtshim.c.
+CPP_FLAGS="-m32 -O2 -ffunction-sections -fdata-sections -fno-exceptions -fno-rtti -fno-use-cxa-atexit -fno-threadsafe-statics -fno-stack-protector -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 -DNDEBUG -DIMGUI_ENABLE_STB_TRUETYPE"
+
+INCLUDE="-I$IMGUI_DIR -I$IMGUI_SRC"
+
+echo "Compiling C runtime shim..."
+gcc $C_FLAGS $INCLUDE \
+    -c $BRIDGE_SRC/crtshim.c \
+    -o lib/imgui_crtshim.o || { echo "Failed: crtshim.c"; exit 1; }
+
+echo "Compiling render bridge..."
+# imgbridge is compiled as C++ so it sees cimgui.h function declarations
+# (C++ mode is required; the .c extension is overridden with -x c++)
+g++ $CPP_FLAGS $INCLUDE \
+    -x c++ \
+    -DCIMGUI_DEFINE_ENUMS_AND_STRUCTS \
+    -c $BRIDGE_SRC/imgbridge.c \
+    -o lib/imgui_bridge.o || { echo "Failed: imgbridge.c"; exit 1; }
+
+echo "Compiling cimgui wrapper..."
+g++ $CPP_FLAGS $INCLUDE \
+    -c $IMGUI_DIR/cimgui.cpp \
+    -o lib/imgui_cimgui.o || { echo "Failed: cimgui.cpp"; exit 1; }
+
+echo "Compiling imgui core..."
+g++ $CPP_FLAGS $INCLUDE \
+    -c $IMGUI_SRC/imgui.cpp \
+    -o lib/imgui_core.o || { echo "Failed: imgui.cpp"; exit 1; }
+
+echo "Compiling imgui draw..."
+g++ $CPP_FLAGS $INCLUDE \
+    -c $IMGUI_SRC/imgui_draw.cpp \
+    -o lib/imgui_draw.o || { echo "Failed: imgui_draw.cpp"; exit 1; }
+
+echo "Compiling imgui tables..."
+g++ $CPP_FLAGS $INCLUDE \
+    -c $IMGUI_SRC/imgui_tables.cpp \
+    -o lib/imgui_tables.o || { echo "Failed: imgui_tables.cpp"; exit 1; }
+
+echo "Compiling imgui widgets..."
+g++ $CPP_FLAGS $INCLUDE \
+    -c $IMGUI_SRC/imgui_widgets.cpp \
+    -o lib/imgui_widgets.o || { echo "Failed: imgui_widgets.cpp"; exit 1; }
+
+echo "Compiling imgui demo..."
+g++ $CPP_FLAGS $INCLUDE \
+    -c $IMGUI_SRC/imgui_demo.cpp \
+    -o lib/imgui_demo.o || { echo "Failed: imgui_demo.cpp"; exit 1; }
+
+echo "Archiving cimgui.a..."
+# NOTE: imgui_bridge.o and imgui_crtshim.o are NOT in the archive because
+# compile_link.sh already picks them up individually via find lib/ -name "*.o".
+# Including them here would cause duplicate symbol errors.
+ar rcs lib/cimgui.a \
+    lib/imgui_cimgui.o \
+    lib/imgui_core.o \
+    lib/imgui_draw.o \
+    lib/imgui_tables.o \
+    lib/imgui_widgets.o \
+    lib/imgui_demo.o || { echo "Failed: ar"; exit 1; }
+
+echo "ImGui compiled successfully."
+exit 0

compile_link.sh

@@ -14,9 +14,6 @@ done;
 objstring=lib/stub.o" "$objstring 
 echo "Object Files: "$objstring
 echo " "
-
-# Find libgcc for i386 (needed by LVGL compiled with gcc)
 LIBGCC=$(gcc -m32 -print-libgcc-file-name)
-echo "libgcc: ${LIBGCC}"
+ld -m elf_i386 -s --gc-sections -Tlinker.script -o bin/kernel.bin $objstring \
-
+    --start-group lib/cimgui.a $LIBGCC --end-group
-ld -m elf_i386 -s --gc-sections -Tlinker.script -o bin/kernel.bin $objstring --start-group lib/liblvgl.a ${LIBGCC} --end-group

compile_lvgl.sh

@@ -1,132 +0,0 @@
-#!/usr/bin/env bash
-# compile_lvgl.sh — Download LVGL v9.2 source and compile into lib/liblvgl.a
-# Clone & compile in /tmp (fast container-local fs).
-# Cache liblvgl.a on host mount (/code/lvgl/) to skip rebuild.
-set -e
-
-LVGL_VERSION="v9.2.2"
-LVGL_REPO="https://github.com/lvgl/lvgl.git"
-LVGL_DIR="/tmp/lvgl"
-OBJ_DIR="/tmp/lvgl_obj"
-CONF_DIR="$(pwd)/lvglh"
-OUT_DIR="$(pwd)/lib"
-CACHE_DIR="/code/lvgl"
-
-CC="gcc"
-CFLAGS="-m32 -march=i686 -ffreestanding \
-    -fno-builtin -fno-stack-protector -fno-pic -fno-pie \
-    -O2 -Wall -Wno-unused-function -Wno-unused-variable \
-    -I${CONF_DIR} \
-    -I${LVGL_DIR} \
-    -I${LVGL_DIR}/.. \
-    -DLV_CONF_INCLUDE_SIMPLE"
-
-echo " "
-echo "======================="
-echo " "
-echo "Compiling LVGL..."
-echo " "
-
-# If cached liblvgl.a exists on host mount, just copy it and skip everything
-if [ -f "${CACHE_DIR}/liblvgl.a" ]; then
-    echo "Found cached liblvgl.a in ${CACHE_DIR}, copying to ${OUT_DIR}..."
-    cp "${CACHE_DIR}/liblvgl.a" "${OUT_DIR}/liblvgl.a"
-    echo "(Delete lvgl/liblvgl.a to force a full rebuild.)"
-    echo " "
-    echo "LVGL compilation complete (cached)."
-    echo " "
-    exit 0
-fi
-
-# Clone LVGL into /tmp (container-local)
-rm -rf "$LVGL_DIR"
-echo "Downloading LVGL ${LVGL_VERSION}..."
-git clone --depth 1 --branch "${LVGL_VERSION}" "${LVGL_REPO}" "${LVGL_DIR}" 2>&1
-echo "Download complete."
-
-# Gather all LVGL .c source files (core library only, no demos/examples)
-SOURCES=$(find "${LVGL_DIR}/src" -name '*.c' -not -path '*/test/*')
-TOTAL=$(echo "$SOURCES" | wc -l)
-echo "Found ${TOTAL} LVGL source files."
-
-# Compile each .c file to .o (container-local)
-rm -rf "$OBJ_DIR"
-mkdir -p "$OBJ_DIR"
-
-COUNT=0
-ERRORS=0
-for src in $SOURCES; do
-    COUNT=$((COUNT + 1))
-    rel="${src#${LVGL_DIR}/src/}"
-    obj_path="${OBJ_DIR}/${rel%.c}.o"
-    mkdir -p "$(dirname "$obj_path")"
-
-    if ! $CC $CFLAGS -c "$src" -o "$obj_path" 2>&1; then
-        echo "FAILED: $rel"
-        ERRORS=$((ERRORS + 1))
-    fi
-
-    if [ $((COUNT % 50)) -eq 0 ]; then
-        echo "  Compiled ${COUNT}/${TOTAL}..."
-    fi
-done
-
-echo "Compiled ${COUNT} files (${ERRORS} errors)."
-
-if [ "$ERRORS" -ne 0 ]; then
-    echo "LVGL compilation FAILED with ${ERRORS} errors."
-    exit 1
-fi
-
-# Archive into static library
-OBJECTS=$(find "$OBJ_DIR" -name '*.o')
-ar rcs "${OUT_DIR}/liblvgl.a" $OBJECTS
-echo "Created ${OUT_DIR}/liblvgl.a"
-
-# Compile custom LVGL extension files from lvglh/
-LVGLH_SOURCES=$(find "${CONF_DIR}" -name '*.c' 2>/dev/null || true)
-if [ -n "$LVGLH_SOURCES" ]; then
-    echo " "
-    echo "Compiling custom LVGL files from lvglh/..."
-    LVGLH_OBJ_DIR="/tmp/lvglh_obj"
-    rm -rf "$LVGLH_OBJ_DIR"
-    mkdir -p "$LVGLH_OBJ_DIR"
-    HCOUNT=0
-    HERRORS=0
-    for src in $LVGLH_SOURCES; do
-        HCOUNT=$((HCOUNT + 1))
-        rel="${src#${CONF_DIR}/}"
-        obj_path="${LVGLH_OBJ_DIR}/${rel%.c}.o"
-        mkdir -p "$(dirname "$obj_path")"
-        echo "  [lvglh] $rel"
-        if ! $CC $CFLAGS -c "$src" -o "$obj_path" 2>&1; then
-            echo "  FAILED: $rel"
-            HERRORS=$((HERRORS + 1))
-        fi
-    done
-    echo "Compiled ${HCOUNT} custom files (${HERRORS} errors)."
-    if [ "$HERRORS" -ne 0 ]; then
-        echo "Custom LVGL compilation FAILED."
-        exit 1
-    fi
-    # Append custom objects into the existing archive
-    HOBJECTS=$(find "$LVGLH_OBJ_DIR" -name '*.o')
-    ar rcs "${OUT_DIR}/liblvgl.a" $HOBJECTS
-    echo "Updated ${OUT_DIR}/liblvgl.a with custom objects."
-else
-    echo "No custom LVGL files in lvglh/."
-fi
-
-# Cache liblvgl.a and source to host mount for next build
-echo "Caching LVGL to host mount..."
-mkdir -p "$CACHE_DIR"
-rm -rf ${CACHE_DIR}/* ${CACHE_DIR}/.[!.]* ${CACHE_DIR}/..?* 2>/dev/null || true
-cp "${OUT_DIR}/liblvgl.a" "${CACHE_DIR}/liblvgl.a"
-cp -a "$LVGL_DIR/src" "${CACHE_DIR}/src"
-cp -a "$LVGL_DIR"/*.h "${CACHE_DIR}/" 2>/dev/null || true
-cp -a "$OBJ_DIR" "${CACHE_DIR}/obj"
-echo "Done."
-
-echo " "
-echo "LVGL compilation complete."
-echo " "

compile_sources.sh

@@ -4,10 +4,4 @@ echo "======================="
 echo " "
 echo "Compiling FPC Sources..."
 echo " "
-# Build -Fu flags for all directories under src/ and wasuro/
+fpc -Aelf -gw -g -gl -n -vlewn -O3 -Op3 -Si -Sc -Sg -Xd -CX -XXs -CfSSE -CfSSE2 -Rintel -Pi386 -Tlinux -FElib/ -Fusrc/* -Fusrc/driver/* -Fusrc/driver/net/* -Fusrc/driver/video/* -Fusrc/driver/video/imgui/* src/kernel.pas
-FU_PATHS="-Fusrc -Fuwasuro"
-for dir in $(find src wasuro -type d 2>/dev/null); do
-    FU_PATHS="$FU_PATHS -Fu$dir"
-done
-
-fpc -Aelf -gw -g -gl -n -v0ew -O3 -OpPENTIUM3 -Si -Sc -Sg -Xd -CX -XXs -CfSSE -CfSSE2 -Rintel -Pi386 -Tlinux -FElib/ $FU_PATHS src/kernel.pas

doc/flatfs.md

@@ -1,32 +0,0 @@
-#Flat filesystem
-
-A super simple filesystem for asuro. Folders are emulated in filenames.
-
-Starts with disk info sector, sector 0 of volume
-
----
-#### disk info
-
-jmp2boot        : ubit24;
-OEMName         : array[0..7] of char;
-version         : uint16 // numerical version of filesystem
-sectorCount      : uint16;
-fileCount       : uint16
-signature       : uint32 = 0x0B00B1E5
-
-
-the Rest of the sector is reserved
-
----
-
-Starting from sector 1 is the file table. Table size is determined by entry size (64) * fileCount
-
----
-####File entry
-
-name : array[0..59] of char //file name max 60 chars
-fileStart : 16bit // start sector of data
-fileSize : 16bit // data size in sectors
-
----
-

dockerout.txt

@@ -0,0 +1,20 @@
+4023:CIMGUI_API float igGetWindowDpiScale(void);
+4081:CIMGUI_API const ImVec4_c* igGetStyleColorVec4(ImGuiCol idx);
+4082:CIMGUI_API ImVec2_c igGetCursorScreenPos(void);
+4084:CIMGUI_API ImVec2_c igGetContentRegionAvail(void);
+4085:CIMGUI_API ImVec2_c igGetCursorPos(void);
+4086:CIMGUI_API float igGetCursorPosX(void);
+4087:CIMGUI_API float igGetCursorPosY(void);
+4091:CIMGUI_API ImVec2_c igGetCursorStartPos(void);
+4350:CIMGUI_API void igBeginDisabled(bool disabled);
+4372:CIMGUI_API ImVec2_c igGetItemRectMin(void);
+4373:CIMGUI_API ImVec2_c igGetItemRectMax(void);
+4374:CIMGUI_API ImVec2_c igGetItemRectSize(void);
+4377:CIMGUI_API ImDrawList* igGetBackgroundDrawList(ImGuiViewport* viewport);
+4378:CIMGUI_API ImDrawList* igGetForegroundDrawList_ViewportPtr(ImGuiViewport* viewport);
+4387:CIMGUI_API ImVec2_c igCalcTextSize(const char* text,const char* text_end,bool hide_text_after_double_hash,float wrap_width);
+4388:CIMGUI_API ImVec4_c igColorConvertU32ToFloat4(ImU32 in);
+4405:CIMGUI_API bool igIsMouseDoubleClicked_Nil(ImGuiMouseButton button);
+5092:CIMGUI_API ImDrawList* igGetForegroundDrawList_WindowPtr(ImGuiWindow* window);
+5161:CIMGUI_API void igBeginDisabledOverrideReenable(void);
+5244:CIMGUI_API bool igIsMouseDoubleClicked_ID(ImGuiMouseButton button,ImGuiID owner_id);

iso/hello.txt

@@ -1 +0,0 @@
-Hello from the Asuro ISO!

lessons_learnt.md

@@ -1,40 +0,0 @@
-# Lessons Learnt
-
-## 1. File Pickers Must Be Proper Reusable OS Components
-Inline pickers hacked into app code are broken and not reusable. Build file pickers as a standalone unit (`filepicker.pas`) that any program can call via a callback.
-
-## 2. All Errors Need Visible In-App Feedback
-Never use `syslog.logln` as the only error output. Always show the user a dialog, msgbox, or status bar message. Syslog is supplemental only.
-
-## 4. Shell Command Output Goes to stdout_buf, Not syslog
-Use `stdio.bufWriteStr(stdout_buf, ...)` for all shell command output. `syslog` is for kernel diagnostics only.
-
-## 5. Unit Test Convention
-New subsystem units get a `procedure UnitTest` (called at boot from kernel.pas) and a `procedure init` that registers a CLI command so tests can be re-run at runtime. Tests use a nested `Assert(condition, name)` that increments `passed`/`failed` and logs failures via `syslog.logln`. At-boot tests must not do disk I/O — only test in-memory/virtual structures.
-
-## 6. ISR-Visible Spin-Wait Flags Must Use Pointer Dereferencing
-FPC has no `volatile` keyword. Any `while flag = 0 do asm hlt end` loop where `flag` is set by an ISR will hang forever because FPC hoists the load into a register before the loop and never re-reads memory. Always access the flag through a pointer: `while puint32(@flag)^ = 0 do proc_yield()`. This applies everywhere in the kernel that spins waiting for ISR-written state (e.g. `submit_io_wait`, `proc_await`-style loops, DMA done flags).
-
-## 7. Never Spawn a Process Per I/O Operation
-Spawning a new kernel process for each FAT32 read/write/dir operation is pure overhead: process creation (kalloc 8 KB stack, fake IRET frame, DList insertion), an extra context switch, and a double-wait (VFS spins on the worker, worker spins on AHCI). Instead, submit the I/O directly and park the calling process via `psAwaiting` until the AHCI ISR fires the completion callback — zero extra processes, zero wasted scheduler ticks.
-
-## 8. Use psAwaiting to Park a Process Pending Async I/O (not proc_yield spin)
-The correct way to block a process on an async I/O result is: (1) set up a completion callback that sets `State := psReady` then `Done := 1`, (2) atomically check if the operation is already done (under CLI) and set `CurrentProcess^.State := psAwaiting` if not, (3) spin on `Done` via `puint32(@wait.Done)^` per Lesson #6 with `asm hlt end` inside the loop. The process is removed from the runnable set while hardware works. **Do NOT call `proc_await` from `submit_io_wait`** — `proc_await` spins on `CurrentProcess^.State = psAwaiting` without pointer indirection and FPC caches the value in a register, causing it to return immediately before the I/O completes. The calling code then reads garbage from the DMA buffer, causing invalid pointer dereferences and page faults.
-
-## 9. VFS GetDirectoryListing Must Return a Snapshot, Not a Live Tree Reference
-`GetDirectoryListing` for `otVDIRECTORY` nodes previously returned `PHashMap(Obj^.Reference)` — a direct pointer into the live VFS tree. When callers called `FreeDirectoryListing` on the returned map, it freed the live VFSObjects and their name strings, destroying the VFS tree. Any subsequent `GetObjectFromPath` call would then dereference the trashed memory and page fault. **Fix**: always return a heap-allocated snapshot copy of the directory (new `PHashMap`, new `PVFSObject` entries with `stringCopy`'d keys). `FreeDirectoryListing` can then safely own and free the snapshot without touching the live tree. The rule: any function that returns a `PHashMap` to a caller who will call `FreeDirectoryListing` must allocate a fresh map — never return a raw interior pointer to a live data structure.
-
-## 10. Never Call Synchronous Disk I/O From an LVGL Timer or Event Callback
-LVGL timer callbacks (`lv_timer_create`) and event callbacks run synchronously inside the LVGL render loop. Calling any function that parks the current process waiting for disk I/O (e.g. `vfs.FileSize`, `vfs.OpenFile`, `vfs.ReadFile`) from inside a timer or event callback will hang the entire UI — the process blocks mid-callback and the LVGL loop never resumes. All disk I/O that must occur in a UI context must either: (a) use the async VFS API (`OpenFileAsync`, `WriteFileAsync`) with a completion callback that triggers a deferred LVGL update, or (b) be deferred to a dedicated worker process that signals back via a flag the UI can poll. `GetDirectoryListingFrom` is the one bulk exception — it was already present in the original picker and works because it loads into a snapshot synchronously as a single operation; per-file calls like `FileSize` in a loop are the problem.
-
-## 11. Never Allocate Large Arrays as Local Variables in Deep Kernel Call Chains
-Local variables are stack-allocated in Pascal. Kernel processes have a fixed, limited stack (≈8 KB). In deep LVGL callback chains (kernel → LVGL render loop → timer callback → app code), there may only be a few KB of usable stack remaining by the time app code executes. Declaring local arrays larger than ~200–400 bytes (e.g. `array[0..255] of pchar` = 1024 bytes) inside any procedure that runs in this context will silently overflow the stack, corruptung adjacent memory and causing a page fault with a garbled call trace. **Rule**: any local variable array larger than ~128 bytes in a UI callback or procedure called from one must be moved to the heap with `kalloc`/`kfree`. The corruption pattern is a page fault with a call stack full of completely unrelated function names.
-
-## 12. Pascal Silently Ignores Everything After `end.` — Dead Code Masquerades as Live Code
-FPC compiles everything up to and including the first `end.` and silently discards the rest of the file. If a file is partially rewritten by prepending a new implementation but the old implementation is not deleted, the old code survives after `end.`. Forward declarations resolve to the **last** implementation before `end.` — so if the new code was added before the old `end.` but the old procedures were in the "dead" zone they have no effect. However the reverse is dangerous: if the old `end.` was replaced/removed and the new code placed before it, the old procedures in the dead zone still compile to nothing but pollute the source. **Rule**: after any large-scale replacement of a Pascal unit, explicitly check where `end.` falls with a text search and PowerShell-truncate the file at the first `end.`. Never assume a multi-step replacement tool correctly removed all old code — always verify with `Select-String -Pattern "^end\.$"`.
-
-## 13. `for i := 0 to uint32_count - 1` Wraps to 4 Billion When Count is Zero
-In Free Pascal, `uint32` arithmetic wraps: if `dir_count` is `uint32` and equals `0`, then `dir_count - 1 = 0xFFFFFFFF`. A `for i := 0 to dir_count - 1 do` loop with zero count does NOT skip — it runs 4 billion iterations, immediately accessing invalid memory and page faulting. FPC does not emit a warning for this. **Rule**: always guard `uint32`-bounded for loops: `if count > 0 then for i := 0 to count - 1 do`. Alternatively, use `sint32` for loop counters that might legitimately be zero.
-
-## 14. FAT32 Deleted Entries ($E5) Must Be Filtered in getDirEntries
-When a FAT32 directory entry is deleted, `fileName[0]` is overwritten with `$E5` but the rest of the entry (including the cluster pointer) remains intact on disk. `getDirEntries` must explicitly skip entries where `fileName[0] = char($E5)` — stopping only at `char(0)` (end-of-directory) is not enough. If `$E5` entries are returned to callers, they appear in directory listings with a garbage first character, and navigating into them follows a stale/freed cluster chain, which causes reads into arbitrary memory or FAT data, leading to a triple fault. Fix location: the `while i < maxEntries` loop in `fat32.getDirEntries`.