diff --git a/Cargo.lock b/Cargo.lock index 266e91f..ff4705e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -921,7 +921,7 @@ checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" [[package]] name = "visioncraft" -version = "0.1.0" +version = "0.2.0" dependencies = [ "clap", "nix", diff --git a/Cargo.toml b/Cargo.toml index 45ecbb9..e46c3bc 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "visioncraft" -version = "0.1.0" +version = "0.2.0" edition = "2024" rust-version = "1.88" description = "Explicit quality plans, bounded execution receipts and deterministic evidence gates" diff --git a/README.md b/README.md index 9dcac74..5559289 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Rust 1.88 or later is required. Native execution currently supports Linux with g the deterministic library remains independent of the operating system. ```sh -cargo install visioncraft --locked --version 0.1.0 +cargo install visioncraft --locked --version 0.2.0 visioncraft --help ``` @@ -40,7 +40,7 @@ For the pure Rust library without CLI/process dependencies: ```toml [dependencies] -visioncraft = { version = "0.1.0", default-features = false } +visioncraft = { version = "0.2.0", default-features = false } ``` For a coding agent, install the complete `skills/visioncraft/` directory from the diff --git a/skills/visioncraft/SKILL.md b/skills/visioncraft/SKILL.md index 821535a..2c38db1 100644 --- a/skills/visioncraft/SKILL.md +++ b/skills/visioncraft/SKILL.md @@ -1,9 +1,9 @@ --- name: visioncraft -description: Builds features with proportionate tests and evidence, diagnoses persistent bugs, and checks engineering designs and release gates. Use for expectation-driven development, difficult debugging, imported review findings, Rust changes, or a requested quality review. Simple edits and standalone prose changes do not need the full workflow. +description: Builds features with proportionate tests and evidence, diagnoses persistent bugs, and checks engineering designs and release gates. Use for expectation-driven development, difficult debugging, imported review findings, Rust changes, browser-targeted code (Rust compiled to WebAssembly by default), or a requested quality review. Simple edits and standalone prose changes do not need the full workflow. license: MIT OR Apache-2.0 metadata: - version: "0.1.0" + version: "0.2.0" category: "engineering-quality" --- @@ -34,6 +34,7 @@ command surface. | A merge/release needs applicable checks | [Quality gates](references/quality-gates.md), [Deepsec adapter](references/deepsec.md) | | Candidate tests, coverage gaps or measured quality tools would help | [Optional Agentic QE](references/agentic-qe.md) | | Rust is being written, reviewed or ported | [Steering](references/rust/steering.md), [review](references/rust/review.md), [port](references/rust/port.md) | +| Code will run in a browser | [Browser targets: Rust to WebAssembly](references/rust/browser-wasm.md) | | Several participants are actually available | [Logical roles](references/roles.md) | | A concrete project example helps scope the work | [Five worked examples](references/worked-examples.md) | diff --git a/skills/visioncraft/assets/provenance.json b/skills/visioncraft/assets/provenance.json index 9d869d2..3b0e54d 100644 --- a/skills/visioncraft/assets/provenance.json +++ b/skills/visioncraft/assets/provenance.json @@ -221,6 +221,12 @@ "sha256": "4dbf3367ff178738f248543e9ae298ad57c8de3fb797823e756b5edf3f7f9588" } }, + { + "path": "references/rust/browser-wasm.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance: Rust-to-WebAssembly default for browser targets", + "behavioural_sources": [] + }, { "path": "references/rust/port.md", "licence": "MIT; VisionCraft additions MIT OR Apache-2.0", diff --git a/skills/visioncraft/references/rust/browser-wasm.md b/skills/visioncraft/references/rust/browser-wasm.md new file mode 100644 index 0000000..fd1f331 --- /dev/null +++ b/skills/visioncraft/references/rust/browser-wasm.md @@ -0,0 +1,92 @@ +# Browser targets: Rust compiled to WebAssembly + +Independently written VisionCraft guidance (MIT OR Apache-2.0). Read it with +[steering.md](steering.md) whenever new or changed code will run in a browser. + +## 1. Default: logic in Rust, a thin JavaScript host + +When code targets a browser, write its logic in Rust compiled to +`wasm32-unknown-unknown` and keep JavaScript or TypeScript to the host shim the +platform requires. Logic means anything with behaviour worth testing: domain +models and state transitions, parsing and validation, serialisation and wire +formats, geometry, layout and simulation, search and filtering, persistence +schemas and migrations, and cryptography through maintained crates. + +The host shim is what only JavaScript can do or do cheaply: + +- loading and instantiating the module, and the bundler or framework entrypoint; +- DOM, event wiring and the existing UI framework's components; +- browser APIs not yet worth binding through `web-sys` for this change, such as + a single `fetch` call or a framework-owned router; +- handing typed arrays and handles across the boundary. + +The shim calls into Rust and renders what Rust returns. If a shim function +starts to branch on domain state, that logic belongs in the crate. + +This is a priority, not a licence to rewrite. The [port guide](port.md#0-establish-the-benefit-and-boundary) +still applies: port existing browser code when a change already touches its +logic or a maintenance, correctness or performance need justifies it, and +record the reason. Leave thin wrappers over a JavaScript-only library (a +charting package, an editor component, a vendor SDK) in JavaScript. An existing +project's UI framework stays; the default moves the logic beneath it. + +## 2. Shape of the crate + +- One crate per coherent browser capability, `crate-type = ["cdylib", "rlib"]`. + The `rlib` lets native `cargo test` exercise the same logic without a browser. +- Keep the core pure: no clock, randomness, storage or network in the domain + types. Pass time, seeds and fetched bytes in; return values or commands out. + The same core then builds for `wasm32` and native, and tests run natively. +- Put `wasm-bindgen` exports in a thin `wasm` module behind + `#[cfg(target_arch = "wasm32")]` or a feature. Export a small, coarse API: + a few calls that each do meaningful work, not a getter per field. +- Cross the boundary with owned, simple data: numbers, strings, typed arrays, + or `serde` structures through `serde-wasm-bindgen`. Return `Result` + so failures arrive as JavaScript exceptions with a message, never as a panic. + Install `console_error_panic_hook` in debug builds only. +- Enable only the `web-sys` features you call. Each one adds bindings and size. +- Release profile: `opt-level = "z"` or `"s"`, `lto = true`, + `codegen-units = 1`, and `wasm-opt` from the bundler or `wasm-pack` pipeline. + Set a size budget for the `.wasm` and check it. +- Hot paths that touch many elements (particles, graph layouts, meshes) should + share a `Float32Array` view over wasm memory rather than copy per frame. + Re-create the view after any call that can grow memory. + +## 3. Toolchain + +Use what the project already ships. Common pairings: + +| Host | Build | Notes | +|---|---|---| +| Vite/React or another JS framework | `wasm-pack build --target web` or `wasm-bindgen` CLI, then `vite-plugin-wasm` | A small typed bridge module owns `init()` and re-exports the API | +| Rust-only front end | `trunk` with Leptos, Yew, Dioxus or plain `web-sys` | Suitable when there is no existing JS shell to keep | +| Worker or WebGPU compute | `wasm-bindgen` with `--target web`, or `wgpu` | Keep GPU resource ownership on one side of the boundary | + +Pin `wasm-bindgen` to the same version as the CLI that generates the bindings; +a mismatch fails at load time, not compile time. Add `wasm32-unknown-unknown` +to the toolchain file or CI matrix so the target builds on every change. + +## 4. Evidence + +Treat the wasm target as a supported configuration with its own gates: + +1. `cargo test` on the native core for logic and edge cases. +2. `cargo build --target wasm32-unknown-unknown --release` (or the project's + wasm build) on every change to the crate, plus `cargo clippy` for that target. +3. `wasm-bindgen-test` for behaviour that depends on browser APIs, run headless. +4. At least one real browser journey through the actual bundle: load, call the + exported API, observe the rendered result. Use the host's browser tooling. +5. The `.wasm` size against its budget, and a load-time observation where + start-up matters. + +Report a missing wasm build or browser run as a visible non-pass. Native tests +alone do not show that the module loads, that bindings match, or that the +shim calls it correctly. + +## 5. When JavaScript stays the right answer + +Record the reason when you choose JavaScript or TypeScript for browser logic. +Acceptable reasons include: the code is only glue around a JavaScript-only +library; the logic is a few lines whose wasm start-up and boundary cost would +exceed its work; the project or its users cannot accept a wasm build step; or a +deadline-bound fix should not carry a port. Familiarity alone is not a reason. diff --git a/skills/visioncraft/references/rust/steering.md b/skills/visioncraft/references/rust/steering.md index 5377770..53206e3 100644 --- a/skills/visioncraft/references/rust/steering.md +++ b/skills/visioncraft/references/rust/steering.md @@ -30,6 +30,9 @@ external projects. - Describe gates as executed only after reading their actual results. After repeated unsuccessful repairs, reconsider the cause. The [debugging guide](../debugging.md) and [diagram diagnosis](../diagram-diagnosis.md) provide the deeper path. +- Browser-targeted logic defaults to Rust compiled to WebAssembly behind a thin + JavaScript host; see [browser-wasm.md](browser-wasm.md) for scope, crate shape + and the wasm-specific evidence gates. - These sections are a review rubric, not a demand for every possible tool on every edit. Scope tests and lint changes to meaningful risk; preserve existing compatibility and explain deliberate exceptions. diff --git a/skills/visioncraft/references/worked-examples.md b/skills/visioncraft/references/worked-examples.md index db41a28..3b7266a 100644 --- a/skills/visioncraft/references/worked-examples.md +++ b/skills/visioncraft/references/worked-examples.md @@ -14,7 +14,9 @@ do not require an AQE installation or an orchestration service. **Request.** Add creation, editing, completion, deletion, filtering and local persistence to a small browser app. Existing project conventions choose the UI -framework; no agent fleet or full domain programme is needed. +shell; the item model, state transitions, filtering and storage schema live in a +Rust crate compiled to WebAssembly ([browser targets](rust/browser-wasm.md)). +No agent fleet or full domain programme is needed. **Expectation.** A saved item survives reload with its stable identity and completion state. Editing its text preserves that identity. An empty title is @@ -22,12 +24,13 @@ rejected without changing the previous item. Filtering changes the visible set without deleting hidden items. Storage failure is reported without claiming the edit was durably saved. -**Implementation sequence.** Add a failing model test for state transitions, -implement the smallest reducer/store change, then test persistence through the -real browser storage boundary. Exercise create/edit/filter/reload in the browser. +**Implementation sequence.** Add a failing native Rust test for state +transitions, implement the smallest model change, export it through a thin +`wasm-bindgen` API, then test persistence through the real browser storage +boundary with the built module. Exercise create/edit/filter/reload in the browser. Keep a valid ordinary title control beside empty and markup-like input cases. -**Applicable gates.** Unit and browser journey checks; visible error behaviour; +**Applicable gates.** Native unit tests, the wasm target build and browser journey checks; visible error behaviour; keyboard operation, focus and appropriate labels; safe treatment of user text. A small prototype may defer multi-device sync explicitly. Do not claim sync or full accessibility conformance from these local checks.