docs + mouse: blog "Internal tools" + 4 new mouse cards

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/<name>` 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/<name>` 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/<name>` 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/<name>` fail with "missing prerequisite; file not found" (error 20605)?

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?

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`?

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 <script>.das` runs fine because there's no popen parent.
+
+# Verification commands
+
+After reordering, the full dasImgui suite passes:
+
+```bash
+bin/Release/daslang.exe dastest/dastest.das -- --test modules/dasImgui/tests/integration
+# 110 tests, 110 passed, 0 failed in ~500s
+```
+
+# Why not "just fix it in daslang"
+
+The bug is in dasLiveHost or libhv's interaction with [_macro]-driven debug-agent install ordering. Filed as #2677 for triage, but the fix isn't trivial — for now reorder requires in the consumer/wrapper, document the ordering as load-bearing, and move on.
+
+## Questions
+- 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?

site/blog/_posts/internal-tools.md

@@ -0,0 +1,24 @@
+---
+title: Internal tools
+date: 2026-05-15 19:56:22
+tags:
+    - daScript
+---
+
+Why internal tools?
+
+<!-- more -->
+
+Because intern wrote them. Another intern maintained them. And that good one talked master Yoda into doing touchups once; that did not last though. But I digress.
+
+Tools are hard - internal ones are harder yet. Think undesigned, undertested quick fix from 7 years ago; yea, that one. I feel lucky its not that other one, the shader compiler written in perl in 2004 (hi Shodan).
+
+Luckily its 2026. With the right direction that same intern+AI can clean them up, make them good, learn in the process. Focus on quality, tests, documentation; refactor like crazy - grown into a senior engineer, if that's still a thing.
+
+For me tools are an excellent case of dogfooding. Here is daslang MCP. Written in daslang. With test framework in daslang. Currently slightly monolithic, but I'm breaking it apart - JSON RPC section goes to daslib as we speak.
+
+I don't sweat the quality of code on that one though. As long as it's good. Just like with other internal tools. When it's not good - I'll add more lint.
+
+Tools tell stories. Mine tell me where daslang is lacking. I slap myself on the wrist every time 'its that small python script'. I stop and implement what's missing. Lately I get more ambitious - maybe because I miss getting slapped.
+
+This is where the productivity gains hide. Intern wrote them. AI cleans them up. Just keep them INTERNal.