AiVectra is the vector-based user interface system for AiLang.

It provides deterministic, resolution-independent rendering across platforms while preserving AiLang’s semantic authority.

AiVectra does not define language behavior. It renders it.

Curated public examples are in AiLangCore/ailang-examples. For contributor setup and verification, see CONTRIBUTING.md.

Current public beta: v0.0.1-beta.1.

Install the public AiLangCore SDK, including aivectra:

curl -fsSL https://ailang.codes/install.sh | sh
export PATH="$HOME/.ailang/bin:$PATH"
aivectra help

AiVectra is published as an AiLang package with library, tool, and template content. Public examples live in AiLangCore/ailang-examples.

Branch status: develop is the public default branch while the AiVectra runtime, package, and templates are being hardened for beta. Release tags and GitHub prereleases are the public artifact source; main is not the current integration branch during this beta cycle.

AiLangCore roadmap tracks the Alpha -> Beta -> RC -> 1.0 direction across AiLang, AiVM, and AiVectra.

AiVectra enables portable GUI applications for:

• macOS
• Linux
• iOS
• Android
• Web
• Embedded targets (future)

All UI is defined using vector primitives and layout constructs governed by AiLang.

All UI elements are defined as scalable vector primitives.

No raster-first assumptions. No fixed-resolution layouts.

Rendering must be resolution-independent.

Layout behavior must be:

• Predictable
• Canonical
• Spec-governed
• Testable via golden outputs

If layout behavior changes:

1. Update spec
2. Update golden tests
3. Then update implementation

Never the reverse.

AiVectra does not:

• Define UI behavior
• Interpret application logic
• Introduce host-specific semantics

UI structure, state transitions, and rendering rules are defined in AiLang.

AiVectra executes rendering instructions.

Platform renderers:

• Translate vector instructions to native surfaces
• Provide input events
• Provide surface lifecycle management

They must not introduce behavior not described in spec.

The host is replaceable.

AiLang Application ↓ AiLang Evaluator ↓ Vector Scene Graph (AiVectra) ↓ Platform Renderer (mechanical) ↓ Native Surface

AiVectra operates as a deterministic vector scene system.

AiVectra is designed as:

• Retained-mode scene graph
• Deterministic layout pass
• Deterministic paint pass
• Canonical ordering rules

No implicit z-index behavior. No platform-dependent layout differences. No hidden measurement passes.

All rendering must be reproducible.

• Vector primitives (path, rect, circle, text)
• Deterministic layout model
• Scene graph structure
• Platform abstraction layer

Not in scope:

• Animation systems (initially)
• GPU optimization passes
• Styling engines beyond spec definition
• Platform-specific visual effects

Stability over feature velocity.

AiLang defines:

• UI structure
• Component composition
• State transitions
• Layout rules
• Rendering instructions

AiVectra renders those instructions.

The runtime is an implementation detail. The spec is authoritative.

AiLang and AiVectra are AI-first tools.

Authoring style must optimize for:

• determinism
• explicit structure
• stable naming
• safe AI-driven modification

See:

• AiLang SPEC/STYLE_AILANG.md for canonical AiLang source style.
• SPEC/STYLE_AILANG.md for the local pointer to that canonical guide.
• SPEC/STYLE_AIVECTRA.md for AiVectra-specific UI and rendering style.
• SPEC/VISUAL_CONTRACT.md

Beta hardening phase.

Current focus:

• Scene graph design
• Layout determinism
• Platform abstraction boundary
• Golden test strategy
• Functional UI testing and agent-readable debug artifacts

This repository is an AiLang workspace with:

• src/AiVectra/project.aiproj - AiVectra library
• src/AiVectra.Cli/project.aiproj - AiVectra CLI
• templates/projects/ - package project templates
• templates/files/ - package file templates
• samples/HelloWorld/project.aiproj - hello-world sample
• samples/HelloName/project.aiproj - hello-name sample
• samples/InteractiveSvgMvp/project.aiproj - interactive SVG sample
• samples/WeatherApp/project.aiproj - weather sample (in progress)

Canonical AiVectra app structure:

• project.aiproj
• AGENTS.md (required)
• Src/app.aos
• Assets/icons/app.svg (single canonical icon source)
• Assets/images/ (optional)
• Assets/fonts/ (optional)
• Assets/styles/ (future)
• Assets/locale/en.toml (optional)
• See SPEC/APP_STRUCTURE.md for the normative layout.
• Targets/macos/* (optional platform overrides)
• Targets/windows/* (optional platform overrides)
• Targets/linux/* (optional platform overrides)
• .toolchain/ (generated by AI agents, gitignored)

Use ailang from your installed AiLang toolchain (PATH). If you have a temporary local binary in this repo, replace ailang with ./.tools/ailang.

Run the sample app from repo root:

ailang run ./samples/HelloWorld/

Run the named greeting example:

ailang run ./samples/HelloName/

HelloName uses GUI text entry from key events and a clickable Submit button to switch to the greeting view. On macOS, ./scripts/aivectra run uses direct ailang execution by default during development. Set AIVECTRA_USE_MACOS_BUNDLE=1 to exercise the generated .app bundle path.

Wrapper/CLI:

• ./scripts/aivectra is a thin wrapper over ailang (no project-specific default).
• Override runtime location with env or flag:
  • AILANG_BIN=/path/to/ailang ./scripts/aivectra
  • ./scripts/aivectra --ailang /path/to/ailang
• Example:
  • ./scripts/aivectra doctor
  • ./scripts/aivectra test
  • ./scripts/aivectra init MyApp
  • ./scripts/aivectra run ./samples/HelloWorld/
  • ./scripts/aivectra run ./samples/InteractiveSvgMvp/
  • ./scripts/aivectra icon ./samples/HelloWorld/
  • ./scripts/aivectra input --window "AiVectra Weather" --events "clickr:56,110;text:10001;key:enter"
• Tool-side input injection (no sample/app instrumentation required):
  • ./scripts/aivectra input --window "<title-substring>" --events "<tokens>"
  • tokens are semicolon-delimited:
    • text:<value>
    • key:<name> (enter, backspace, left, right, cmd+w, etc.)
    • click:x,y absolute screen coordinates
    • clickr:x,y relative to matched window origin
    • touch:x,y / touchr:x,y aliases to click
    • wait:ms
    • close (sends cmd+w)
  • optional flags:
    • --delay-ms N (default 35)
    • --dry-run
• Debug tooling (TOML artifacts; no sample instrumentation):
  • ./scripts/bootstrap-golden-publish-fixtures.sh
  • ./tools/ailang debug run ./examples/debug/apps/debug_minimal.aos --out .artifacts/debug/hello-world
  • ./tools/ailang debug scenario ./examples/debug/scenarios/minimal.scenario.toml --name minimal
  • ./scripts/test-debug-ci-parity.sh
  • Debug APIs in the SDK/CLI are generic only; sample-specific debug formats must stay out of src/AiVectra.
• Functional visual checks:
  • ./scripts/test-golden-ui.sh
  • ./scripts/test-interactive-svg-mvp.sh
  • ./scripts/test-screenshot-debug-reality.sh (requires macOS Screen Recording permission)
  • ./scripts/test-cli-contract.sh (CLI parse/forwarding/cwd/exit conformance)
  • ./scripts/test-all.sh (all gates; set AIVECTRA_SCREENSHOT_TEST=1 to include screenshot reality)
• Artifact bundle files:
  • config.toml
  • stdout.txt
  • vm_trace.toml
  • state_snapshots.toml
  • syscalls.toml
  • events.toml
  • diagnostics.toml

Package usage:

• AiVectra is published as an AiLang package with library, tool, and template content.
• Add it to a project with ailang package add aivectra.
• Restore packages with ailang package restore.
• After restore, run the package tool with ailang aivectra ....
• Package project templates are under templates/projects/.
• Package file templates are under templates/files/.

Agent debug workflow:

• Bootstrap fixtures from clean checkout:
  • ./scripts/bootstrap-golden-publish-fixtures.sh
• Run app with artifact capture:
  • ./tools/ailang debug run ./examples/debug/apps/debug_minimal.aos --out .artifacts/debug/my-run

CLI behavior contract:

• See SPEC/CLI.md for normative command grammar, forwarding, cwd inference, and exit semantics.
• Run deterministic replay from fixture (when provided by AiLang runtime):
  • ./tools/ailang debug run ./examples/debug/apps/debug_minimal.aos --events ./examples/debug/events/minimal.events.toml --out .artifacts/debug/replay-run
• Run named scenario fixture:
  • ./tools/ailang debug scenario ./examples/debug/scenarios/minimal.scenario.toml --name minimal
• CI parity check:
  • ./scripts/test-debug-ci-parity.sh

App icon generation:

• Standard command: ./scripts/aivectra icon <project-path>
• Default output style: AiLang logo mark (style=ailang_logo)
• Optional label override: ./scripts/aivectra icon <project-path> <label> (style=label_monogram)
• Output:
  • <project-path>/Assets/icons/app.svg
  • <project-path>/Assets/icons/manifest.txt
• Default logo source asset in this repo:
  • ./Assets/icons/ailang_default_appicon.svg

Run the library project directly (sanity check):

ailang run ./src/AiVectra/src/lib.aos

Native runtime note:

• ./scripts/aivectra checks runtime capabilities from ailang --help.
• When runtime requires prebuilt bytecode, wrapper emits:
  • Err#err1(code=AIV001 ... )
• When runtime supports source/project targets, wrapper runs .aos/project inputs directly.

Windowed hello world baseline:

• samples/HelloWorld/src/app.aos demonstrates direct syscall-backed rendering through AiVectra library primitives.

Resolution-independent. Deterministic. Spec-governed. Replaceable host. No semantic leakage.

AiVectra — deterministic vector UI for AiLang.