Minml live preview

[phamelink]

This PR implements a real-time HTML previewer for MinML, powered by a new Go-based WebAssembly converter and a dedicated VS Code extension. It also streamlines the development and installation process for contributors.

Overview

The goal of this PR is to provide a seamless preview experience for MinML files (.minml, .m) directly within VS Code, ensuring that the rendering is 100% consistent with the Go implementation by using WASM.

Key Features

• WASM-Powered Conversion: Implemented a Go WASM bridge in go/wasm/main.go that exposes the core MinML-to-HTML conversion logic to the browser environment.
  • VS Code Live Preview Extension: A new extension in devtools/minml-preview that provides a side-by-side live preview panel.
  • Local Asset Support: Implemented a tag strategy in the webview to automatically resolve relative image paths (e.g., img{src=figure.png}[]) against the document's directory, fixing previous "403 Forbidden" errors.
  • Simplified Installation: Added a make vscode-live-preview command to the root Makefile with OS detection (Windows/Linux/macOS) and dependency safeguards for easy local installation.

Technical Details

• Go: The WASM implementation uses TreeParser and TreeWriter from the minml and html packages to maintain architectural consistency.
• TypeScript/JS: The extension handles the lifecycle of the WASM instance and ensures the preview updates in real-time as the user types.
• Infrastructure: Created a root Makefile for various build commands and to handle cross-platform paths for VS Code extensions (~/.vscode/extensions vs %USERPROFILE%.vscode\extensions).

How to Test

1. Install the extension: make vscode-live-preview
2. Verify:
   • Restart VS
   • Open any .minml
   • Run the command "MinML: Show Live Preview" from the Command
   • Add an image using img{src=relative/path.png}[] and verify it renders correctly without permission errors.

Files

• go/wasm/main.go: New WASM entry
• Makefile: Added vscode-live-preview and OS detection
• devtools/minml-preview/: Full extension
• README.md & devtools/README.md: Updated documentation and guides.

Note on Contribution: The initial code for this implementation was developed manually by a human, referencing a cat gif panel view extension.
Generative AI was subsequently used for technical research, troubleshooting specific browser security issues (such as the webview URI transformation), and generating parts of the documentation.

[CLAassistant]

All committers have signed the CLA.

[AntoineBastide47]

I get a bunch of errors when I run make build-wasm or open the main.go file in the editor I get a bunch of errors:

Build constraints exclude all the Go files in '/opt/homebrew/opt/go/libexec/src/syscall/js'
Unresolved type 'Value'
Unresolved type 'Value'
Unresolved reference 'String'
Unresolved reference 'ConvertString'
Unresolved reference 'Error'
Unresolved reference 'Global'
Unresolved reference 'Set'
Unresolved reference 'FuncOf'

Are your instructions missing a setup or download step ?

[phamelink]

Whoops sorry for some reason the file didn't commit. I needed the code from your convert file so I moved it up to make it aceessible. Things should work now. Thanks for the catch!

[AntoineBastide47]

I could not run the extension without tinkering with it using codex. Here is what it did:

I made three classes of changes in ~/.vscode/extensions:

  1. I fixed the install layout so VS Code would keep the extension after restart.
     The original make target copied it to ~/.vscode/extensions/minml-preview with no publisher, so VS Code treated it as undefined_publisher.minml-preview-0.0.1 and marked it
     obsolete. I added "publisher": "local", renamed the installed folder to ~/.vscode/extensions/local.minml-preview-0.0.1, and removed the stale undefined_publisher... entry from
     ~/.vscode/extensions/.obsolete.
  2. I fixed the version compatibility so VS Code would load the extension at all.
     Your editor is 1.109.5, but the installed manifest required "vscode": "^1.110.0". I changed that in the installed package.json to "^1.109.0".
  3. I made the command contribution explicit so it shows in the Command Palette.
     In the installed package.json, I added:

  - activationEvents: ["onCommand:minml-preview.showPreview"]
  - contributes.menus.commandPalette: [{ "command": "minml-preview.showPreview" }]
  - a command category of MinML

  The actual extension code in dist/extension.js was already fine. The problems were the install shape, the engine constraint, and the manifest contribution details.

If this is resolved I can start reviewing your PR. Also do you think you can add support for these icons to have it auto enabled:

But it does work as expected which means the review should be quick:

The setup needs a little rework and then its good.

[phamelink]

It should be good now, you now have a little button to open the preview to the side or in a full window. Also like I said it is generally good practice to commit the package-lock.json as it freezes the versions of each package used in javascript projects. So it is normal it is there!

[bford]

Nice work!

General question, which we can discuss further in our meeting today: is this minml previewers completely vscode-specific? How easy or difficult do you expect it would be to port to (extensions to) other IDEs, and how much of the code would be shareable as opposed to vscode-specific?

Minor directory-structure nitpick: I would like everything vscode-specific to be somewhere under an appropriate subdirectory probably named vscode; perhaps that could be at the top level, or perhaps it could be devtools/vscode or maybe more concisely just dev/vscode?

[AntoineBastide47]

LGTM !