diff --git a/mouse-data/docs/dasimgui-new-widget-module-needs-das-module-entry.md b/mouse-data/docs/dasimgui-new-widget-module-needs-das-module-entry.md new file mode 100644 index 000000000..102d4b76e --- /dev/null +++ b/mouse-data/docs/dasimgui-new-widget-module-needs-das-module-entry.md @@ -0,0 +1,24 @@ +--- +slug: dasimgui-new-widget-module-needs-das-module-entry +title: When adding a new .das sibling module under modules/dasImgui/widgets/, why does `require imgui/` fail with "missing prerequisite; file not found" (error 20605)? +created: 2026-05-15 +last_verified: 2026-05-15 +links: [] +--- + +**Cause:** dasImgui uses `.das_module` (at `modules/dasImgui/.das_module`) to map `imgui/` requires to widgets/*.das via `register_native_path("imgui", "name", "{project_path}/widgets/file.das")`. A new .das file under `widgets/` is **not** auto-discovered; the module path registration is what makes `require imgui/` resolve. + +**Fix:** add a `register_native_path` line in `modules/dasImgui/.das_module`'s `initialize()` function alongside the existing entries for `imgui_lint`, `imgui_live`, etc. + +```das +register_native_path("imgui", "imgui_harness", "{project_path}/widgets/imgui_harness.das") +``` + +No daslang rebuild needed — `.das_module` runs at module-load time on every invocation. + +**Counterpart for daslib/:** the `daslib/` path uses a different mechanism (auto-discovered from `modules/dasImgui/daslib/*.das`) and doesn't need `.das_module` entries. + +**Symptom this caused:** PR creating `widgets/imgui_harness.das` saw `require imgui/imgui_harness` fail with error 20605 until the `.das_module` line was added. + +## Questions +- When adding a new .das sibling module under modules/dasImgui/widgets/, why does `require imgui/` fail with "missing prerequisite; file not found" (error 20605)? diff --git a/mouse-data/docs/daslang-private-require-structural-symbol-gate.md b/mouse-data/docs/daslang-private-require-structural-symbol-gate.md new file mode 100644 index 000000000..600fd8a11 --- /dev/null +++ b/mouse-data/docs/daslang-private-require-structural-symbol-gate.md @@ -0,0 +1,29 @@ +--- +slug: daslang-private-require-structural-symbol-gate +title: How do I make a daslang wrapper module enforce "users cannot call symbols from the backend module" structurally — without relying on a lint or a runtime check? +created: 2026-05-15 +last_verified: 2026-05-15 +links: [] +--- + +**Pattern: private `require` for the backend.** + +```das +module my_wrapper shared public + +require imgui_backend_safe public // re-exported to consumers +require imgui_backend_glfw // PRIVATE — symbols stay inside this module +``` + +A `require X` (no `public`) is **private to the requiring module**. Symbols from X are visible inside `my_wrapper.das` but do NOT transitively re-export to anything that does `require my_wrapper`. Consumers literally cannot resolve `glfwInit` / `ImGui_ImplGlfw_*` etc. — those names aren't in their scope. + +**Why this matters:** lints catch use AFTER it happens; private-require prevents the symbol from existing in user scope at all. A user who tries to call a forbidden symbol gets the standard "function not found" diagnostic instead of a lint error. + +**A user who explicitly `require imgui_backend_glfw` themselves bypasses the structural guarantee** — and that's where a complementary lint catches the explicit-require attempt. Defense in depth: structure first, lint second. + +**Application:** dasImgui's `imgui_harness` (PR landing 2026-05-15) privately requires `imgui_app`, `glfw/glfw_boost`, `opengl/opengl_boost`, `live/glfw_live`, `live/opengl_live`, `imgui/imgui_live`, `imgui/imgui_visual_aids`. Consumers `require imgui/imgui_harness` and the GLFW/GL function names are not in their scope. + +**Source:** `modules/dasImgui/widgets/imgui_harness.das`. Same pattern works for any backend-abstraction wrapper. + +## Questions +- How do I make a daslang wrapper module enforce "users cannot call symbols from the backend module" structurally — without relying on a lint or a runtime check? diff --git a/mouse-data/docs/daslang-script-flags-need-dash-dash-separator.md b/mouse-data/docs/daslang-script-flags-need-dash-dash-separator.md new file mode 100644 index 000000000..ab78aaba7 --- /dev/null +++ b/mouse-data/docs/daslang-script-flags-need-dash-dash-separator.md @@ -0,0 +1,29 @@ +--- +slug: daslang-script-flags-need-dash-dash-separator +title: When daslang.exe runs a script with `daslang FILE.das --flag`, why doesn't the script's `get_user_args()` see `--flag`? +created: 2026-05-15 +last_verified: 2026-05-15 +links: [] +--- + +**Cause:** `get_user_args()` in `daslib/clargs` is **mode-aware**: +- Standalone exe (`daslang -exe`-built): returns `argv[1..]` +- Interpreter mode (regular `daslang.exe FILE.das`): returns the slice **after** the `--` separator. No `--` = empty args. + +So `daslang.exe FILE.das --headless` → `get_user_args()` returns `[]` because there's no `--` separator. The `--headless` token is consumed by daslang.exe itself (or treated as positional and ignored). + +**Fix — invoke with `--` separator:** +``` +daslang.exe FILE.das -- --headless +``` + +`get_user_args()` now returns `["--headless"]` and clargs `find_bool_flag_raw_value(args, "--headless")` resolves correctly. + +**For dastest:** `dastest --test FILE.das -- --headless` works the same way; dastest passes everything after its own `--` through to the script. + +**Source:** `daslib/clargs.das:74` `get_user_args()` / `:36` `get_cli_arguments()` — `find_index(all_args, "--")` is the gate. + +**Related memory:** `feedback_clargs_underscore_hyphen` (clargs field underscores → hyphens). Together they characterize the clargs invocation contract for daslang-script CLI flags. + +## Questions +- When daslang.exe runs a script with `daslang FILE.das --flag`, why doesn't the script's `get_user_args()` see `--flag`? diff --git a/mouse-data/docs/why-does-my-dastest-integration-test-hang-at-readiness-gate-failed-when-external-curl-to-status-works-fine-is-it-a-require-order.md b/mouse-data/docs/why-does-my-dastest-integration-test-hang-at-readiness-gate-failed-when-external-curl-to-status-works-fine-is-it-a-require-order.md new file mode 100644 index 000000000..efa990fc8 --- /dev/null +++ b/mouse-data/docs/why-does-my-dastest-integration-test-hang-at-readiness-gate-failed-when-external-curl-to-status-works-fine-is-it-a-require-order.md @@ -0,0 +1,75 @@ +--- +slug: why-does-my-dastest-integration-test-hang-at-readiness-gate-failed-when-external-curl-to-status-works-fine-is-it-a-require-order +title: why does my dastest integration test hang at "readiness gate FAILED" when external curl to /status works fine — is it a require-order issue in daslang-live? +created: 2026-05-16 +last_verified: 2026-05-16 +links: [] +--- + +# Symptom + +`dastest` integration tests hang at the `imgui_playwright` readiness gate: + +``` +[imgui_playwright] subprocess up, polling /status... +[imgui_playwright] readiness gate FAILED +``` + +(30s `wait_until_ready` timeout, then 120s popen drain timeout. External `curl http://localhost:9090/status` from a sibling shell returns 200 with proper status JSON throughout — only the popen parent's request loop can't see it.) + +# Root cause + +`live/live_api` was required BEFORE `imgui_app + glfw/glfw_boost + opengl/* + glfw_live + opengl_live` somewhere in the requirer chain (usually a wrapper module like `imgui/imgui_harness`). The `[_macro] installing` in `live_api.das` calls `fork_debug_agent_context(@@debug_agent)` at compile time. If that fork happens before GLFW is initialized in the live runtime, the resulting LiveApiServer becomes unreachable from a popen parent on Windows. + +Filed: [#2677](https://github.com/GaijinEntertainment/daScript/issues/2677). Distinct from #2675 (`ANY("*")` route shadowing). + +# Fix (mechanical) + +In the requirer module (yours or a wrapper you control), reorder requires so the **windowed backend stack comes first**: + +```das +// Windowed backend FIRST (correctness, not aesthetics). +require imgui +require imgui_app +require glfw/glfw_boost +require opengl/opengl_boost +require live/glfw_live +require live/opengl_live + +// Live-host + boost-runtime stack AFTER. +require live/live_api +require live/live_commands +require live/live_vars +require live_host +require imgui/imgui_live +require imgui/imgui_boost_runtime +require imgui/imgui_boost_v2 +require imgui/imgui_widgets_builtin +require imgui/imgui_containers_builtin +require imgui/imgui_visual_aids +``` + +This mirrors the canonical order every pre-`imgui_harness` example/test used verbatim. Reordering is a no-op for visibility / re-export semantics — purely a workaround for the install-time ordering bug. + +# How to recognize this gotcha + +- Test hangs at `readiness gate FAILED` (not at `body did not converge` or similar). +- External `curl` to `localhost:9090/status` works while the test hangs (proves the server is up — the popen parent specifically can't reach it). +- Always reproduces — not a flaky timing issue. +- ONLY triggers when run via `popen` (via `with_imgui_app` in `imgui_playwright`, or any `dastest` integration test). Direct `bin/Release/daslang-live.exe