VakCodingLanguage

.vak is a beginner-first language with multiple runtime targets:

• python (default)
• js (Node.js)
• electron (desktop app runtime)

Quick docs:

• vak-core/docs/AI_EXPERT_GUIDE.md - full maintainer-level handoff for AI and humans
• vak-core/docs/PHRASES.md - phrase catalog
• vak-core/docs/JS_ELECTRON_TARGET.md - JS + Electron architecture/security
• vak-core/docs/VAK_LANGUAGE_GROWTH_IDEAS.md - prioritized roadmap for expanding VAK
• vak-core/docs/PROJECT_STRUCTURE.md - organized vak-core file map
• vak-core/docs/AI_SYSTEM_PROMPT.md - copy/paste AI system prompt

Project layout

• vak.py - root compatibility launcher (calls vak-core/vak.py)
• vak-core/vak.py - main CLI entrypoint (run, transpile, init)
• vak-core/vak_runtime/engine.py - runtime facade
• vak-core/vak_runtime/compiler/ - transpiler core (python, js, electron)
• vak-core/vak_runtime/js_target.py - JS/Electron build + run integration
• vak-core/vak.spec - PyInstaller spec for Windows build
• vak-core/installer/ - Windows installer scripts/assets
• vak-core/vak_js_runtime/ - Node.js runtime helpers for JS target
• vak-core/vak_runtime/runtime_env.py - runtime environment + module import bridge
• vak-core/vak_runtime/modules/ - phrase function packs
• vak-core/vak_runtime/ui.py - desktop UI engine (windows, canvas, shell, timers, sprites)
• vak-core/templates/electron/ - generated Electron app template
• vak-core/vak-console-extension/ - editor syntax + diagnostics
• vak-core/examples/ - ready-to-run .vak programs
• vak-core/docs/ - architecture and phrase documentation
• workspace/ - generated build artifacts and temporary outputs

Legacy command (still supported)

python vak.py vak-core\examples\hello.vak
python vak.py vak-core\examples\snake.vak --check
python vak.py vak-core\examples\snake.vak --show-python

Run by target

python vak.py run vak-core\examples\hello.vak --target python
python vak.py run vak-core\examples\include_app\main.vak --target python
python vak.py run vak-core\examples\template_fill_demo.vak --target python
python vak.py run vak-core\examples\state_persistence_demo.vak --target python
python vak.py run vak-core\examples\task_background_demo.vak --target python
python vak.py run vak-core\examples\cpp_style.vak --target js
python vak.py run vak-core\examples\task_background_demo.vak --target js
python vak.py run vak-core\examples\electron_counter.vak --target electron
python vak.py run vak-core\examples\electron_app_controls_demo.vak --target electron
python vak.py run vak-core\examples\electron_full_demo.vak --target electron
python vak.py run vak-core\examples\vakterm.vak --target electron
python vak.py run vak-core\examples\electron_file_viewer\file_viewer.vak --target electron

Check syntax by target

python vak.py run vak-core\examples\snake.vak --check --target python
python vak.py run vak-core\examples\data_web_file.vak --check --target js
python vak.py run vak-core\examples\electron_canvas_demo.vak --check --target electron
python vak.py run vak-core\examples\electron_app_controls_demo.vak --check --target js --capabilities
python vak.py run vak-core\examples\electron_app_controls_demo.vak --check --target electron --capabilities

Capability preflight notes:

• --capabilities is only valid with --check.
• It reports phrase starters that are unsupported for the selected target and exits with VAK-CAP-001 when mismatches are found.

Show transpiled output

python vak.py run vak-core\examples\snake.vak --show-python --target python
python vak.py run vak-core\examples\cpp_style.vak --show-js --target js
python vak.py run vak-core\examples\electron_counter.vak --show-js --target electron

Explicit transpile command

python vak.py transpile vak-core\examples\hello.vak --target python --out build\hello.py
python vak.py transpile vak-core\examples\cpp_style.vak --target js --out build\cpp_style.mjs

Scaffold Electron app

python vak.py init electron my_vak_app
python vak.py init electron my_vak_app --dir C:\projects

Build Electron artifacts

python vak.py build vak-core\examples\electron_full_demo.vak --target electron --platform win
python vak.py build vak-core\examples\electron_full_demo.vak --target electron --platform linux
python vak.py build vak-core\examples\electron_full_demo.vak --target electron --platform mac

Build output is written under:

• workspace\.vak-build\<program>\electron\dist\

Explain one line (Tutor Mode)

python vak.py run vak-core\examples\snake.vak --explain-line 12 --target python

Major shelves

• CanvasShelf - canvas drawing/events/timers/game loop
• SpriteShelf - image sprites and frame animation
• SoundShelf - sound playback/beeps (Windows)
• TutorShelf - line explanations and hint utilities
• CppShelf, DataShelf, FileShelf, MathShelf, SystemShelf, NetShelf, UiShelf

Electron security defaults

• contextIsolation: true
• nodeIntegration: false
• sandbox: true
• preload bridge only (window.vakBridge)
• run command disabled by default in vak.config.json
• file operations restricted to fsRoot (default ".")
• renderer crash/runtime problems are reported with VAK line + snippet context

Electron HTML boundaries

• Electron apps run on HTML/CSS/JS under the hood.
• VAK drives UI through phrase APIs (windows/controls/canvas/shell/sprites/sound/html blocks).
• HTML support is phrase-based via:
  • add html ... to <window> as <control>
  • set html of <control> to ...
  • load html file ... into <window> as <control>
• For a single-file Electron app, prefer inline HTML with:
  • remember panel_html as "<div>...</div>"
  • add html panel_html to app as panel
• vak-core/examples/vakterm.vak now uses this one-file pattern (no external dashboard HTML file required).
• Injected HTML is sanitized in renderer (scripts and inline JS handlers are removed).
• Companion asset files (assets/, .html, images, sounds) next to a .vak file are copied into generated Electron projects automatically.

Friendly errors (QoL)

Errors now provide:

• what went wrong
• where (line + source snippet)
• likely cause
• concrete fix
• extra tutor hint
• phrase-parser suggestions for unknown statements (closest valid phrase starters)
• clearer block-order diagnostics (otherwise/if it fails as placement)
• clearer indentation diagnostics (tabs vs 2-space steps)

Priority 1 additions

• Source composition: include "path/to/file.vak"
• Package phrase stub (friendly guidance): bring package "name"
• Main auto-discovery: exactly one top-level to main with: auto-runs
• Multiline templates:
  • remember dashboard_html as text block: ... finished
  • fill template dashboard_html with {"name": user_name}
• Error codes in friendly output (VAK-*) and optional raw trace mode:
  • python vak.py run <file.vak> --debug-errors
• Electron app controls:
  • set app icon to "assets/icon.png"
  • set app menu to [...]
  • open external url "https://..."
  • show message box titled "..." as "..."
• State shortcuts:
  • save state app_state to "state.json"
  • load state from "state.json" as app_state
  • remember settings as persistent notebook "settings.json"
• Task/background phrases:
  • run task fetch_news using url as news_task
  • when task news_task completes use handle_news
  • cancel task news_task

Explorer cleanup

Use the organizer script to keep root clean for contributors and users:

powershell -ExecutionPolicy Bypass -File vak-core\scripts\organize-explorer.ps1

This moves legacy generated folders (.vak-build, build, dist, __pycache__) into:

• workspace\legacy-artifacts\

New Electron examples

• vak-core/examples/electron_counter.vak
• vak-core/examples/electron_canvas_demo.vak
• vak-core/examples/electron_shell_demo.vak
• vak-core/examples/electron_full_demo.vak
• vak-core/examples/electron_html_demo.vak
• vak-core/examples/electron_app_controls_demo.vak
• vak-core/examples/vakterm.vak (single-file Electron terminal demo with inline HTML dashboard)
• vak-core/examples/electron_file_viewer/file_viewer.vak (single-file Electron file viewer app in its own example folder)

Install For A Friend (Windows)

To use Vak like an installed language on Windows:

1. Run dist\VakSetup.exe (installs vak.exe runtime).
2. In the installer, optionally check:
   • Add Vak to PATH
   • Associate .vak files with Vak
3. Install the VS Code extension separately from:
   • vak-core\vak-console-extension\vak-language-tools-0.1.2.vsix
   • VS Code -> Extensions -> ... -> Install from VSIX...

Important: .vak is not auto-recognized by VS Code from the runtime installer alone. Reason: VS Code language support is provided by a VS Code extension (.vsix), which is managed separately from system/runtime installers for security and per-user profile isolation.