miskeyed-workbench 0.1.0__tar.gz

miskeyed_workbench-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.Python
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# ---- Virtual environments / lockfiles ----
+.venv/
+venv/
+env/
+uv.lock
+
+# ---- Build output ----
+build/
+dist/
+wheelhouse/
+_skbuild/
+
+# ---- scikit-build-core / CMake ----
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+CTestTestfile.cmake
+*_autogen/
+**/*.dir/
+
+# ---- Generated Shiboken bindings ----
+/shiboken/
+/build-bindings/
+
+# ---- Visual Studio / MSBuild (CMake-generated project files) ----
+*.sln
+*.vcxproj
+*.vcxproj.filters
+*.vcxproj.user
+Debug/
+Release/
+MinSizeRel/
+RelWithDebInfo/
+x64/
+.vs/
+
+# ---- Vendored SDKs (provisioned locally / in CI, never committed) ----
+# Qt runtime/dev SDK unpacked into the tree by aqtinstall.
+/6.8.3/
+.qt/
+aqtinstall.log
+# Slang SDK lives outside the repo (../../app/slang) or is provisioned in CI.
+
+# ---- Editor / OS noise ----
+.idea/
+.DS_Store
+Thumbs.db

miskeyed_workbench-0.1.0/AGENTS.md

@@ -0,0 +1,126 @@
+# AGENTS.md — Miskeyed Workbench contract for AI agents
+
+This file is the operating contract for AI coding agents (Codex, Copilot, Claude, and
+any successor) working in this repository. Read it before editing. It is short on
+trivia and long on **boundaries**, because boundaries are what this package is made of.
+The product intent lives in [VISION.md](VISION.md); the shipped-today design lives in
+[ARCHITECTURE.md](ARCHITECTURE.md).
+
+---
+
+## What this repo is
+
+`miskeyed-workbench`: a native **Slang + Qt 6.8 / QRhi** shader workbench with
+Shiboken6 Python bindings. Keep changes scoped to this package. Do not add
+speculative infrastructure (multi-app networking, DCC adapters, external transports)
+unless the current, concrete problem requires it.
+
+---
+
+## How to edit this repository
+
+1. **Solve the current problem first.** Do not build speculative infrastructure.
+2. **Prefer clear boundaries over clever abstractions.**
+3. **Do not create abstractions without at least one concrete reason.**
+4. **Remove obsolete prototype architecture** rather than preserving compatibility.
+5. **Avoid subprocesses when the relevant native / in-process API exists.**
+6. **Keep native systems native.** Python / PySide *exposes*; it does not *own*.
+7. **Prefer deterministic behavior.**
+8. **Treat incremental invalidation and identity as first-class concerns.**
+9. **Use existing standards** where appropriate rather than creating equivalents.
+10. **Keep integrations at the edges.** A convenience dependency must not invert the
+    architecture.
+11. **Tests protect architectural invariants** — hashing, invalidation, hot reload,
+    resource lifetime, deterministic outputs, API equivalence.
+12. **Comment *why* a boundary exists,** not what obvious code is doing.
+13. **When uncertain, optimize for** the smallest useful implementation + clean
+    ownership + the ability to replace the layer later.
+
+---
+
+## Ownership boundaries (do not blur)
+
+- **Slang owns GPU work** — geometry prep, deformation/skinning, culling, GPU-driven
+  draw prep, material evaluation, lighting, raster shaders, compute, post-processing.
+- **C++ owns system work** — app lifecycle, device/resource creation, synchronization,
+  command submission, OS/windowing, stable ownership, and Python exposure.
+- **Python / PySide exposes only.** There is no Python mirror of the render core. Do
+  not add one.
+
+---
+
+## No backward-compatibility baggage
+
+This package intentionally carries **no** compatibility layer with the old
+pure-Python prototype: no `slangc`/`qsb` subprocesses, no comment-parsed parameters,
+no Python-owned renderer. When you find dead prototype scaffolding, **delete it** —
+do not wrap it to keep something old alive.
+
+---
+
+## Working facts for this repo
+
+These are load-bearing details verified in practice. Respect them unless you have a
+concrete reason and a test proving the change is safe.
+
+**Build (editable, from the repo root):**
+
+```powershell
+# Build isolation MUST be off: shiboken6-generator comes from Qt's index, not PyPI.
+# SDKs come from the environment (identical to CI) — never hardcoded paths:
+$env:CMAKE_PREFIX_PATH = "<path-to>\Qt\6.8.3\msvc2022_64"   # Qt 6.8 dev SDK
+$env:SLANG_ROOT        = "<path-to>\slang"                  # Slang SDK
+.\.venv\Scripts\python.exe -m pip install --no-build-isolation -e . -v
+```
+
+- The base `python` on this machine is Python 2.7 — never use it. Use the venv python.
+- This is Windows PowerShell: chain with `;`, never `&&`.
+- SDKs are read from the environment, not the repo tree: `CMAKE_PREFIX_PATH` locates the
+  Qt 6.8 dev SDK and `SLANG_ROOT` the Slang SDK (see `cmake/FindSlang.cmake`). Editable
+  installs also read `SLANG_ROOT` at import time to load the Slang runtime DLLs; a
+  released wheel bundles them, so it needs neither.
+
+**Identity & naming:**
+
+- Distribution: `miskeyed-workbench`; import: `miskeyed.workbench` (PEP 420 namespace).
+- The native extension is `_slang_qrhi.pyd` and the **C++ namespace stays `slang_qrhi`.**
+  Do **not** rename the C++ internals — it is risky and buys nothing.
+
+**Rendering:**
+
+- The shipped backend is **Direct3D 11 + HLSL SM5.0** via FXC (`d3dcompiler_47.dll`,
+  always present on Windows). D3D12/DXC is not used, so no DXC DLLs are bundled.
+- Never `reset()`/free a QRhi resource synchronously in `render()`/`initialize()` while
+  a prior frame may still reference it — retire it through the deferred-release
+  graveyard for `>= maxFrameLatency + 1` frames. Synchronous frees crash the D3D11
+  backend (use-after-free, `0xC0000005`).
+
+**Reflection & invalidation:**
+
+- Uniform globals are wrapped in an implicit constant buffer — unwrap
+  `getElementTypeLayout()` before reading fields, or reflection returns zero params.
+- The uniform buffer is packed by each parameter's explicit `offset` (memcpy), not by
+  list order, so descriptor order is UI-only and safe to reorder/group.
+- Hash identity and required work are separate concepts. A source edit does not make
+  every product a hash-child of source; compiler outputs are independent semantic nodes.
+
+**Shiboken gotchas:**
+
+- `WorkbenchWindow.h` must `#include` `LspClient.h` (not forward-declare) because of
+  `QList<LspDiagnostic>` as a member.
+- Keep the `SlangRhiWidget` mouse/wheel event overrides **private** — Shiboken skips
+  private members; making them protected breaks binding generation.
+
+**Testing native windows headless:**
+
+- Only construct/exercise `WorkbenchWindow` inside a running event loop with a
+  `QTimer` quit. Building one headless without `app.exec()` throws a benign teardown
+  AV (slangd/QRhi with no loop) that is a harness artifact, not a real bug.
+
+---
+
+## What "done" looks like
+
+Edit Slang → dependency change detected → in-process compile → minimal QRhi state
+rebuild → viewport updates. Every change leaves the boundaries above intact and the
+core more portable, not less.

miskeyed_workbench-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,42 @@
+# slang-qrhi architecture
+
+`slang-qrhi` is a new native SDK. The old Python renderer/toolchain API is intentionally not part of this package.
+
+## Ownership
+
+- **Qt 6.8 / QRhi** owns the graphics device, render targets, command buffers, and widget lifecycle.
+- **Slang C++ API** owns source compilation, module composition, linking, reflection, entry-point hashes, and backend shader generation.
+- **QShader bridge** packages in-memory Slang output for QRhi. There are no runtime compiler subprocesses.
+- **ShaderDocument** is the live authoring state and connects source, reflection, parameters, dependency state, and generated shader packages.
+- **ShaderParameterModel** is the authoritative Qt model for reflected values. It backs both native Qt and Shiboken/PySide consumers.
+- **DependencyGraph** is a shader-specific persistent Merkle DAG. Hashes answer identity; dirty flags answer work scheduling.
+- **SlangRhiWidget** is the embeddable native viewport used by both the standalone executable and PySide6.
+
+## Merkle DAG rule
+
+A source edit does not make every semantic product a hash-child of source. Compiler outputs become independent semantic nodes after compilation.
+
+For example, an implementation-only source edit may change `EntryPoint` while `ParameterLayout` retains the same digest. The viewport then rebuilds the shader/pipeline while the parameter inspector remains untouched.
+
+```text
+Source -> EntryPoint ---------------------> Pipeline
+                 ^                           ^
+                 |                           |
+          Slang compile                ParameterLayout
+                                            |      |
+                                            v      v
+                                        UiSchema  Values
+```
+
+This is deliberately different from a serialized snapshot Merkle tree: the graph is long-lived, shared dependencies form a DAG, dependency ordering is canonicalized, and invalidation semantics are node-kind specific.
+
+## Runtime update classes
+
+- parameter value: uniform buffer update only
+- UI metadata: inspector/model update only
+- texture/resource content: resource upload only
+- reflected binding layout: bindings + pipeline rebuild
+- shader implementation: compile + shader package + pipeline rebuild
+- render state: pipeline rebuild only
+
+The target UX is Substance/Houdini-like: edit shader declarations, let reflection generate controls, and keep ordinary control changes out of the compiler path.

miskeyed_workbench-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## Unreleased — packaging
+
+- Rebranded to **Workbench**, distributed as `miskeyed-workbench` / imported as
+  `miskeyed.workbench` (PEP 420 namespace).
+- Added a `workbench` console entry point.
+- Modernized `pyproject.toml` for PyPI: PEP 639 SPDX `license` + `license-files`,
+  split build-only `shiboken6-generator` out of runtime dependencies,
+  `minimum-version = "build-system.requires"`, `sdist.exclude`, cached `build-dir`,
+  and `[project.urls]`.
+- The importable wheel no longer bundles the standalone executable
+  (`SLANG_QRHI_BUILD_APP=OFF`).
+- Added `.gitignore` and a tag-triggered GitHub Actions release workflow that
+  builds Windows wheels + sdist and publishes to PyPI via Trusted Publishing.
+- The build is fully environment-driven (Qt via `CMAKE_PREFIX_PATH`, Slang via
+  `SLANG_ROOT`); no machine-specific paths remain and CI provisions both SDKs.
+- Added a scalable SVG application icon (`assets/workbench.svg`, exported to
+  `assets/workbench.ico` + PNG sizes) and applied it via `QApplication.setWindowIcon`.
+
+Breaking reset; no compatibility layer with the previous pure-Python prototype.
+
+- Replaced Python-owned rendering with a C++20 `QRhiWidget` renderer.
+- Replaced `slangc`/`qsb` runtime subprocesses with the in-process Slang Compilation API.
+- Added a Qt 6.8 `QShader` bridge for Slang-generated shader binaries and reflection metadata.
+- Replaced comment parsing as the parameter source of truth with Slang reflection.
+- Added native dynamic parameter model and inspector widgets.
+- Added persistent shader-specific BLAKE2b Merkle DAG and dirty-state propagation.
+- Added native standalone workbench.
+- Added Shiboken6 bindings so the same Qt objects are directly usable from PySide6.
+- Added reflected global-uniform binding propagation into QRhi resource bindings.

miskeyed_workbench-0.1.0/CMakeLists.txt

@@ -0,0 +1,99 @@
+cmake_minimum_required(VERSION 3.24)
+project(slang_qrhi VERSION 0.2.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+set(CMAKE_AUTOMOC ON)
+
+option(SLANG_QRHI_BUILD_APP "Build native standalone workbench" ON)
+option(SLANG_QRHI_BUILD_PYTHON "Build Shiboken6 Python bindings" ON)
+
+# Build inputs come from the environment so a clean checkout and CI build identically,
+# with no machine-specific paths:
+#   * Qt 6.8 dev SDK  ->  CMAKE_PREFIX_PATH
+#   * Slang SDK       ->  SLANG_ROOT      (see cmake/FindSlang.cmake)
+
+find_package(Qt6 6.8 REQUIRED COMPONENTS Core Gui Widgets)
+find_package(Python 3.11 REQUIRED COMPONENTS Interpreter Development.Module)
+
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+find_package(Slang REQUIRED)
+
+add_library(slang_qrhi_core STATIC
+    cpp/src/Digest.cpp
+    cpp/src/DependencyGraph.cpp
+    cpp/src/ShaderParameterModel.cpp
+    cpp/src/ParameterInspector.cpp
+    cpp/src/SlangCompiler.cpp
+    cpp/src/Qt68ShaderBridge.cpp
+    cpp/src/ShaderDocument.cpp
+    cpp/src/SlangRhiWidget.cpp
+    cpp/src/CodeEditor.cpp
+    cpp/src/ShaderHighlighter.cpp
+    cpp/src/LspClient.cpp
+    cpp/src/WorkbenchWindow.cpp
+    # Q_OBJECT headers live in cpp/include; list them so AUTOMOC scans them (its
+    # basename heuristic only checks the source dir, which would skip moc otherwise).
+    cpp/include/slang_qrhi/DependencyGraph.h
+    cpp/include/slang_qrhi/ShaderParameterModel.h
+    cpp/include/slang_qrhi/ParameterInspector.h
+    cpp/include/slang_qrhi/ShaderDocument.h
+    cpp/include/slang_qrhi/SlangCompiler.h
+    cpp/include/slang_qrhi/SlangRhiWidget.h
+    cpp/include/slang_qrhi/CodeEditor.h
+    cpp/include/slang_qrhi/ShaderHighlighter.h
+    cpp/include/slang_qrhi/LspClient.h
+    cpp/include/slang_qrhi/WorkbenchWindow.h
+)
+
+target_compile_definitions(slang_qrhi_core PUBLIC SLANG_QRHI_STATIC)
+target_include_directories(slang_qrhi_core
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/cpp/include>
+        $<INSTALL_INTERFACE:include>
+)
+target_link_libraries(slang_qrhi_core
+    PUBLIC Qt6::Core Qt6::Gui Qt6::Widgets
+    PRIVATE Qt6::GuiPrivate Slang::slang
+)
+
+if(SLANG_QRHI_BUILD_APP)
+    add_executable(slang-qrhi app/main.cpp)
+    target_link_libraries(slang-qrhi PRIVATE slang_qrhi_core)
+    install(TARGETS slang-qrhi RUNTIME DESTINATION bin)
+endif()
+
+if(SLANG_QRHI_BUILD_PYTHON)
+    include(ShibokenBindings)
+    slang_qrhi_add_shiboken_module(
+        TARGET _slang_qrhi
+        MODULE_NAME _slang_qrhi
+        TYPESYSTEM "${CMAKE_CURRENT_SOURCE_DIR}/bindings/typesystem_slang_qrhi.xml"
+        GLOBAL_HEADER "${CMAKE_CURRENT_SOURCE_DIR}/bindings/slang_qrhi_bindings.h"
+        WRAPPED_HEADERS
+            "${CMAKE_CURRENT_SOURCE_DIR}/cpp/include/slang_qrhi/DependencyGraph.h"
+            "${CMAKE_CURRENT_SOURCE_DIR}/cpp/include/slang_qrhi/ShaderParameterModel.h"
+            "${CMAKE_CURRENT_SOURCE_DIR}/cpp/include/slang_qrhi/ShaderDocument.h"
+            "${CMAKE_CURRENT_SOURCE_DIR}/cpp/include/slang_qrhi/ParameterInspector.h"
+            "${CMAKE_CURRENT_SOURCE_DIR}/cpp/include/slang_qrhi/SlangRhiWidget.h"
+            "${CMAKE_CURRENT_SOURCE_DIR}/cpp/include/slang_qrhi/WorkbenchWindow.h"
+        LINK_LIBRARIES slang_qrhi_core
+    )
+
+    # Ship the Slang runtime next to the extension so the wheel imports without
+    # extra PATH setup (Qt/shiboken/pyside DLLs come from the PySide6 dependency).
+    if(WIN32)
+        find_file(SLANG_RUNTIME_DLL NAMES slang-compiler.dll slang.dll
+            HINTS "${slang_DIR}/../bin" "${SLANG_ROOT}/bin" "$ENV{SLANG_ROOT}/bin")
+        if(SLANG_RUNTIME_DLL)
+            get_filename_component(_slang_bin_dir "${SLANG_RUNTIME_DLL}" DIRECTORY)
+            file(GLOB _slang_runtime_dlls "${_slang_bin_dir}/*.dll")
+            install(FILES ${_slang_runtime_dlls} DESTINATION miskeyed/workbench)
+        endif()
+    endif()
+endif()
+
+install(TARGETS slang_qrhi_core ARCHIVE DESTINATION lib)
+install(DIRECTORY cpp/include/slang_qrhi DESTINATION include)
+install(DIRECTORY shaders/ DESTINATION miskeyed/workbench/shaders)

miskeyed_workbench-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Jay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.