Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,15 +32,15 @@ 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
```

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
Expand Down
5 changes: 3 additions & 2 deletions skills/visioncraft/SKILL.md
Original file line number Diff line number Diff line change
@@ -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"
---

Expand Down Expand Up @@ -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) |

Expand Down
6 changes: 6 additions & 0 deletions skills/visioncraft/assets/provenance.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
92 changes: 92 additions & 0 deletions skills/visioncraft/references/rust/browser-wasm.md
Original file line number Diff line number Diff line change
@@ -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<T, JsError>`
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.
3 changes: 3 additions & 0 deletions skills/visioncraft/references/rust/steering.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
13 changes: 8 additions & 5 deletions skills/visioncraft/references/worked-examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,20 +14,23 @@ 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
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.
Expand Down
Loading