# PBXB64 feature status — Release V4 (0.50.0-z64)

> **Planning docs for 100% PowerBASIC 11 parity** (2026-06-12 audit):
> - `Compatibility.md` (repo root) — parity report, severity-classified gaps, silent advantages.
> - `docs/needed_features.md` — engineering TODO (10 P0 + 12 P1 + 12 P2 + 20 P3 items).
> - `help/PBXB64_Commands.md` — the user-facing command reference (regenerated from `docs/LOWERING_STATUS.md`).
> - `docs/NATIVE_HLIB_TYPES_PLAN.md` — phased implementation of all H-Lib3 container types; Phases 0-7 complete (10 families + UDT payload, 108 type variants supported).
>
> **Headline:** ~310/490 (~63%) of catalogued PBWin 11 commands at full parity with regression tests; ~40 partial; ~30 accepted as no-op; ~110 missing or planning. Path to 100% is in `docs/needed_features.md`. **We can be better than PBWin but not worse** — the list of silent advantages is in `Compatibility.md` §24.

## Status summary

| Area | Status | Notes |
|---|---|---|---:|---|
| Driver pipeline | Restored | `.b64` inputs now enter `b64_frontend_build_ir()` before middle-end/backend lowering. |
| B64 frontend | Working subset | 13/13 examples link+run end-to-end (added six_args, seven_args; upgraded div_rem). |
| B64 global data | Fixed | Integer `var` globals initialize `.data`; integer `const` globals initialize `.rdata`. |
| IR output | Fixed | `--emit-ir` now stops at IR and writes readable IR text. Use `--dump-ir` for sidecar dumps while continuing. |
| x64 MIR verifier | Fixed | `CQO` is emitted as a nullary machine instruction, matching verifier expectations. |
| C frontend | Active | Self-host lane now targets `core/source/`; stale root mirror references removed. |
| PB/BASIC frontend | 244/244 passes | All PB assembly tests pass (0 expected fails, 0 regressions). |
| PB Link+Run | 50/50 passes | All PB link+run tests pass, including 14 container/UDT/callback tests. |
| String concat fix | Fixed | `bestof_str_concat` relocation offsets corrected; BYVAL string param concat in user functions works. |
| New types | Partial | VARIANT, OBJECT, GUID, STRINGZ, WSTRINGZ parsed and have runtime stubs; full runtime semantics remain for V5. |
| H-Lib container types | Implemented | 10 container families (Arr, Stk, Que, Lst, Str, 2D, Hsh, Tre, DTre, Tri) with auto-init/final, method dispatch, UDT payloads for Arr/Lst/Hsh/Tre, `SortUsing` callbacks via `CODEPTR`, public C header, 14 passing container/UDT/callback tests + 1 C link+run test. |
| Debug hooks | New | `#DEBUG HOOKS ON/OFF`, `#HOOK var sub`, `#ENDHOOK var` directives inject lifecycle hook calls. |
| Silent expression eval | New | `pb_try_eval_expr()` helper silently evaluates args without diagnostic emissions. |
| DIALOG/CONTROL/TCP/UDP/HOST | Real handlers | Each parses arguments, emits IR calls to `bestof_*` runtime functions. |
| THREAD/XTHREAD/COMM/REGISTER KEY | Real handlers | With `pb_try_eval_expr()` for all argument positions. |
| GUI NEW/MESSAGE LOOP | Real handler | Creates window via `bestof_graphics_create_window`. |
| XPRINT/LPRINT | Real handlers | Commands handled as no-ops; print text forwarded to console statement. |
| DISPLAY/FONT/ACCEL/MENU | Real Win32 | Runtime functions call GetOpenFileName/SaveFile/ChooseColor/ChooseFont (comdlg32), SHBrowseForFolder (shell32), CreateMenu/AppendMenu/SetMenu (user32), CreateFont/DeleteObject (gdi32), LoadAccelerators (user32). |
| MOUSEPTR/PROCESS | Real handlers | Runtime functions call LoadCursor/SetCursor, Get/SetPriorityClass. |
| Build systems | Hardened | Makefile, batch, and CMake source lists share the current split-source layout and no longer reference removed files. |
| Packaging hygiene | Cleaned | Generated `.ir.txt`, `.res`, temporary object, scratch B64, and stale mirror artifacts are ignored/removed. |

## Native H-Lib container types

PBXB64 implements the H-Lib3 container family as first-class native PB types. Declaring `LOCAL a AS LNARR` allocates the container on the heap, initializes it at function entry, and finalizes it automatically at scope exit. Method dispatch (`a.Push 5`, `n = a.Count`) is lowered to calls into the `c_hlib_*` runtime loaded from disk.

| Family | Type keyword | Variants | Auto cleanup | Notes |
|---|---|---:|---|---|
| Arr | `LNARR`, etc. | 14 + UDT | Yes | Full `Add/Get/Set/Ins/Del/Swap/Reverse/Push*/Pop*/Peek*` surface. |
| Stk | `LNSTK`, etc. | 13 | Yes | LIFO `Push`/`Pop`/`Peek`. |
| Que | `LNQUE`, etc. | 13 | Yes | FIFO `Push`/`Pop`/`Peek`. |
| Lst | `LNLST`, etc. | 13 + UDT | Yes | Doubly-linked list with cursor methods. |
| Str | `SSSTR`, `WSSTR` | 2 | Yes | Mutable string buffer. |
| 2D | `LN2D` | 1 | Yes | Two-dimensional Long array. |
| Hsh | `LNHSH`, `SSHSH`, `WSHSH` | 25 + UDT (Ln-keyed) | Yes | Hash table with `Set`/`Get`/`Got`/`Del`/`Clone`. |
| Tre | `LNTRE`, `SSTRE`, `WSTRE` | 25 + UDT (Ln-keyed) | Yes | AVL tree with cursor traversal. |
| DTre | `WSDTRE` | 1 | Yes | Deep tree (per-node child tree). |
| Tri | `SSTRI` | 1 | Yes | 256-ary trie. |

UDT payloads use `AS LNARR OF MyType`, `AS LNLST OF MyType`, `AS LNUTHSH OF MyType`, and `AS LNUTTRE OF MyType`. The compiler passes UDT variables by address and the runtime copies `elem_size` bytes per element.

`Arr.SortUsing CODEPTR(MyComparator)` is supported. `CODEPTR` returns the real address of a PB function; the runtime calls the comparator with two element values.

A public C header is available at `core/include/c17/pbxb64/hlib.h` and is consumed by `examples/c/c_hlib_lnarr.c`.

## B64 examples covered

| File | Expected behavior |
|---|---|
| `answer.b64` | returns 42 from `answer()` |
| `simple.b64` | returns 42 from `main()` |
| `comprehensive.b64` | arithmetic/control-flow sample; returns 90 |
| `hello.b64` | imports `putchar`, prints `H`, returns 0 |
| `call.b64` | direct function call; returns 42 |
| `if_else.b64` | conditional branch; returns 42 |
| `loop_control.b64` | `while`, `continue`, `break`; returns 25 |
| `params.b64` | two-parameter call; returns 42 |
| `five_args.b64` | five-argument Win64 ABI call; returns 15 (1+2+3+4+5) |
| `div_rem.b64` | signed divide/remainder path; returns 27 (81/3=27; 100%5=0, 100%7=2, 17%5=2) |
| `six_args.b64` | six-argument Win64 ABI call; returns 21 (1+2+3+4+5+6) |
| `seven_args.b64` | seven-argument Win64 ABI call; returns 28 (1+2+3+4+5+6+7) |
| `shift_count.b64` | shift-count lowering; returns 36 |
| `global_data.b64` | mutable global data load; returns 42 |
| `global_expr.b64` | constant global expression; returns 42 |
| `call_add.b64` | nested direct call; returns 42 |

## Confirmed native validation

```text
cmake -S core -B core/build_native -DCMAKE_BUILD_TYPE=Debug
cmake --build core/build_native -j2
core/build_native/PBXB64 --version
core/build_native/PBXB64 --emit-ir examples/b64/answer.b64 -o /tmp/answer.ir
core/build_native/PBXB64 -S examples/b64/*.b64 --verify-ir --verify-mir
core/build_native/PBXB64 examples/b64/*.b64 -o /tmp/*.exe --verify-ir --verify-mir
```

The Linux container did not include MinGW-w64, PowerShell, or Wine, so Windows executable runtime exit-code checks are staged in `run_pb_tests.ps1` but not executed here.
