# 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

| Piece | Loup 1.25.1 |
|---|---|
| The language in `.lpweb` files (`@mode(web.compiled)`, `@mode(web.scripted)`) | **Works.** `loup run app.lpweb` runs the file on the host interpreter. |
| Type-checking a project | **Works.** `loup-bootstrap check` |
| Template fences (`html`, `css`, …) rendered to strings | **Works**, but `html` fences do **not** auto-escape yet (Chapter 14). |
| `async` / `await` | **Works**, but an `async` call runs eagerly, to completion, when it is called; there is no task scheduler yet (Chapter 15). |
| Compiling to WebAssembly | **Experimental, not audited.** `loup-bootstrap build --target browser` writes one bare `build/<name>.wasm`, which runs under `loup-launcher --run-bare`. |
| Browser runtime (`loup-rt.js`), generated HTML shell, `loup serve` | ⚠ Planned |
| DOM, `ui` reactive components and signals, `mount`, Web Components | ⚠ Planned |
| `extern js`, `@jsexport`, `lang.interop.js`, workers | ⚠ Planned |
| Server-side rendering, hydration, deployment layout | ⚠ 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:

```loup
@mode(web.compiled)

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

```text
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`](https://github.com/code-craft-ai-company/loup-releases/releases)
GitHub releases:

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

```powershell
# 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:

| Book | Modes |
|---|---|
| [The Loup Scripting Book](../loup-scripting/README.md) | `host.scripted`, `host.dual` |
| **The Loup Web Book** (this book) | `web.compiled`, `web.scripted` |
| [The Loup Native Book](../loup-native/README.md) | `host.native`, `host.dual` |
| [The Loup Freestanding Book](../loup-freestanding/README.md) | `freestanding` |

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](ch01-getting-started.md): 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](ch02-compiled-mode-rules.md): `web.compiled` and
   `web.scripted`, entry points, what each mode allows, the standard library
   from web code.
3. [Variables and Data Types](ch03-variables-and-data-types.md): `let`,
   `var`, `const`, the primitive types, numeric conversions, strings.
4. [Functions](ch04-functions.md): declarations, default and named arguments,
   lambdas, closures, function types, generators.
5. [Control Flow](ch05-control-flow.md): `if`, `while`, `for`, `match`,
   `with`, `try`/`finally`, and the `defer` gap.
6. [Collections](ch06-collections.md): `list`, `dict`, `set`, tuples, and how
   collections are copied.
7. [Structs](ch07-structs.md): value types, construction, `with` copies,
   methods.
8. [Enums and Pattern Matching](ch08-enums-and-pattern-matching.md):
   payloads, `Option`, `Result`, exhaustive `match`.
9. [Classes and Objects](ch09-classes-and-objects.md): constructors,
   inheritance, visibility, `modifier` and `safe`, ownership verbs.
10. [Interfaces](ch10-interfaces.md): declaring and implementing interfaces,
    default methods, standard interfaces.
11. [Generics](ch11-generics.md): type parameters, bounds, generic types.
12. [Error Handling](ch12-error-handling.md): exceptions, `Result`, `?`,
    `attempt`.
13. [Modules and Packages](ch13-modules-and-packages.md): imports between
    `.lpweb` files, the `.lppkg` manifest, cross-mode import rules.
14. [Template Fences — HTML and CSS](ch14-template-fences-html-and-css.md):
    fence syntax, interpolation, directives, filters, and the planned
    context-aware escaping.
15. [Async and Concurrency](ch15-async-and-concurrency.md): `async`,
    `await`, `await group`, and what runs eagerly today.
16. ⚠ [Reactive UI](ch16-reactive-ui.md): signals, components, `View`,
    `mount`, the `ui` fence (planned).
17. ⚠ [Web Components](ch17-web-components.md): `@webcomponent`, attributes,
    shadow DOM, slots (planned).
18. ⚠ [DOM, Storage, Workers, and JavaScript Interop](ch18-dom-storage-workers-js-interop.md):
    `extern js`, `@jsexport`, `lang.interop.js`, workers (planned).
19. ⚠ [SSR, Hydration, and Deployment](ch19-ssr-hydration-and-deployment.md):
    what `--target browser` produces today, and the planned SSR, hydration
    and deployment design.
20. [Memory Safety in Web Apps](ch20-memory-safety.md): 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`](../../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.