The Loup Web Book

⚠ Status: Loup 1.25.1. This book describes the web design in the Loup Language Reference (the v1.20 volumes, amended in place through 1.25). Anything marked ⚠ Planned is not in this release. Loup does not ship a browser runtime yet: there is no loup-rt.js, no HTML shell, no loup serve, and no DOM, reactive UI, Web Components, workers or JavaScript interop API. The language chapters are taught with listings that run on the 1.25.1 toolchain; the browser chapters are design previews.

This book teaches Loup for the web: the two web execution modes, web.compiled and web.scripted, and the language you write in them. It is for people who build web front ends and services and want static types, value types, explicit ownership and a single toolchain.

What works today, and what is planned

Known gaps in Loup 1.25.1

These are places where the toolchain does not yet do what the Language Reference specifies. The chapters show each one with real output where it comes up:

• int arithmetic wraps on overflow instead of throwing (the sized types such as int32 do throw).
• [1, 2] == [1, 2] is false: collection equality is not element-wise yet.
• A defer body never runs; use try/finally for cleanup.
• async functions run eagerly at the call; a failure surfaces at the call, not at await.
• html fences do not escape interpolated values; use the escape filter.
• panic is undefined in web code; throw an exception instead.
• A web.compiled file cannot import any standard-library module (E_COMPILED_IMPORT_SCRIPTED); web.scripted files can.
• In Wasm builds, i"…" interpolated strings, // and for await stop the program at run time; the same code runs under loup run.

The two web modes

Every Loup file declares its execution mode on its first line. The web book uses two modes, and web files use the .lpweb extension:

@mode(web.compiled)

func main(): void {
    println("Hello from web.compiled");
}

Hello from web.compiled

Save it as hello.lpweb and run it with loup run hello.lpweb.

• web.compiled is the browser's ahead-of-time mode. A file holds only declarations. The runner calls main(), so that is where the program starts (Chapter 2).
• web.scripted is the browser's just-in-time mode. Its top-level statements run in order, like a script.

The names @mode(compiled) and @mode(scripted) that older Loup material uses were retired in v1.17. The compiler does not reject them; it silently runs the file as host.scripted, so a web.compiled program written with the old name never calls main() and prints nothing. Always write the full mode name.

Installing Loup

The official builds are published on the code-craft-ai-company/loup-releases GitHub releases:

# Linux and macOS
curl -fsSL https://github.com/code-craft-ai-company/loup-releases/releases/latest/download/loup-install.sh | sh

# Windows (PowerShell)
irm https://github.com/code-craft-ai-company/loup-releases/releases/latest/download/loup-install.ps1 | iex

The installer puts the toolchain in ~/.loup (or %LOCALAPPDATA%\Programs\Loup on Windows) and adds its bin directory to your PATH. To pin a version, use sh -s -- --version 1.25.1 or set LOUP_VERSION. Every archive contains loup, loup-bootstrap (the compiler that builds Wasm) and loup-launcher (the Wasm runtime). Chapter 1 walks through the first project.

Where this book fits

There are four Loup books, one per environment:

The language is the same in every mode; what changes is the entry point, which features are available, and how the program is delivered. Chapters 3 to 13 of this book teach the core language, so you can read them without the other books.

How to read this book

Chapters 1 and 2 cover the toolchain and the rules of the two web modes. Chapters 3 to 13 teach the language. Chapter 14 covers template fences, Chapter 15 async code, and Chapter 20 the safety guarantees. Chapters 16 to 19 describe the planned browser runtime.

Listings follow these conventions:

• A plain loup listing compiles and runs; its output follows in a text block.
• A listing labelled as not compiling is followed by the compiler's real message, then by the fix.
• A listing labelled as throwing is followed by the real Uncaught … output.
• A listing labelled as a design sketch (in the ⚠ Planned chapters) shows the specified design and is not checked by the toolchain.

Every listing that is not a design sketch was run with Loup 1.25.1.

Table of contents

1. Getting Started: installing Loup, running a .lpweb file, a project with loup-bootstrap init, building Wasm, and what the planned browser pipeline looks like.
2. The Web Modes: web.compiled and web.scripted, entry points, what each mode allows, the standard library from web code.
3. Variables and Data Types: let, var, const, the primitive types, numeric conversions, strings.
4. Functions: declarations, default and named arguments, lambdas, closures, function types, generators.
5. Control Flow: if, while, for, match, with, try/finally, and the defer gap.
6. Collections: list, dict, set, tuples, and how collections are copied.
7. Structs: value types, construction, with copies, methods.
8. Enums and Pattern Matching: payloads, Option, Result, exhaustive match.
9. Classes and Objects: constructors, inheritance, visibility, modifier and safe, ownership verbs.
10. Interfaces: declaring and implementing interfaces, default methods, standard interfaces.
11. Generics: type parameters, bounds, generic types.
12. Error Handling: exceptions, Result, ?, attempt.
13. Modules and Packages: imports between .lpweb files, the .lppkg manifest, cross-mode import rules.
14. Template Fences — HTML and CSS: fence syntax, interpolation, directives, filters, and the planned context-aware escaping.
15. Async and Concurrency: async, await, await group, and what runs eagerly today.
16. ⚠ Reactive UI: signals, components, View, mount, the ui fence (planned).
17. ⚠ Web Components: @webcomponent, attributes, shadow DOM, slots (planned).
18. ⚠ DOM, Storage, Workers, and JavaScript Interop: extern js, @jsexport, lang.interop.js, workers (planned).
19. ⚠ SSR, Hydration, and Deployment: what --target browser produces today, and the planned SSR, hydration and deployment design.
20. Memory Safety in Web Apps: what Loup checks for you today, and what the planned browser runtime adds.

The Language Reference

The normative description of every feature is the Loup Language Reference: the core, runtime, compilation and data volumes (specs/loup-language-core-v1_20.md and its siblings). This book cites it as "Language Reference §V-N.M", where V is the volume (1 core, 2 runtime, 3 compilation, 4 data); for example, §1-2.6 is the feature matrix of the six modes in the core volume. Where this book and the Reference disagree, the Reference describes the intended design and the toolchain decides what works today; this book says which is which.