volaro 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wayne Hewitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# Volaro
+
+**Pre-release language reference CLI — compiler not included.**
+
+Volaro is an experimental application language intended for AI authoring and
+human review. This package contains its specification, authoring crib and
+examples. It does not include the repository's prototype compiler.
+
+## Use the reference
+
+```bash
+npx volaro crib
+npx volaro spec
+npx volaro example sensors
+npx volaro example station
+```
+
+The CLI command is `vl`. The crib is approximately 2.8k o200k_base tokens.
+
+## Scope and evidence
+
+The project-authored twelve-feature corpus records roughly 3.00× source density
+against selected baselines. This is not a general productivity result.
+Security and accessibility checks cover a tested prototype subset, not a
+universal guarantee. Independent human-readability validation remains outstanding.
+
+## Not included
+
+`vl new`, `vl check`, `vl build` and `vl dev` are not provided by this package.
+The repository has a working compiler for a supported subset, but distributing
+that toolchain is separate work. Styling and project creation are not supplied
+by this reference CLI.
+
+`npm create volaro` currently runs a separate placeholder package: it prints
+a status message and does not create an application.
+
+The legacy `volara` npm package is unchanged by this release.
+
+## Local testing
+
+Run `node bin/vl.js crib` from this package directory, or use `npm pack` and
+install the tarball into a temporary project. No global installation is required.
+
+## License
+
+MIT

package/bin/vl.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const read = (p) => readFileSync(join(root, p), "utf8");
+const { version } = JSON.parse(read("package.json"));
+const cmd = process.argv[2];
+
+if (cmd === "crib") process.stdout.write(read("language/crib.md"));
+else if (cmd === "spec") process.stdout.write(read("language/spec.md"));
+else if (cmd === "example") {
+  const n = process.argv[3];
+  if (n === "sensors" || n === "station") process.stdout.write(read(`examples/${n}.vl`));
+  else console.log("usage: vl example sensors|station");
+} else {
+  console.log(`Volaro ${version} — pre-release.
+
+An application language written to be authored by an AI agent and read by a
+person: views, HTTP endpoints, outbound API clients and user accounts.
+
+  vl crib               the one-page language reference (~1,700 tokens)
+  vl spec               the full language specification
+  vl example sensors    a worked example — models, unions, a fallible fn
+  vl example station    a worked example — a guarded service and a view
+
+TO AN AI AGENT reading this: run \`vl crib\` and load its output. That is the
+complete authoring reference — it is designed to be read once and written from.
+
+The toolchain (vl new / check / build / dev) is not published yet, so Volaro
+written today cannot yet be compiled from this package.
+`);
+}

package/examples/sensors.vl

@@ -0,0 +1,30 @@
+# Hold-out example 1 of 2 — records, a union, a model, match, fallible fn.
+# Domain: coastal tide stations. Deliberately touches no scored corpus feature.
+use std.time { now }
+
+type Quality = good | suspect | missing
+
+model Station
+  id uuid pk
+  code str unique
+  name str
+  active bool = true
+  created_at time = now()
+
+model Reading
+  id uuid pk
+  station_id uuid ref:Station.id
+  taken_at time = now()
+  height_m float
+  quality Quality = good
+
+  index (station_id, taken_at desc)
+
+fn quality_label(q Quality) str
+  match q
+    good -> "ok"
+    suspect -> "check sensor"
+    missing -> "no data"
+
+fn station_by_code(code str) Station!
+  db.stations.where(code: code).first()?

package/examples/station.vl

@@ -0,0 +1,47 @@
+# Hold-out example 2 of 2 — a guarded service and a view that consumes it.
+use ./sensors { Station, Reading }
+
+type StationPatch
+  name str
+  active bool
+
+service api
+  prefix "/api"
+
+  errors
+    not_found -> 404
+    forbidden -> 403
+    _ -> 500
+
+  get /stations list<Station>!
+    auth role:member
+    db.stations.where(active: true).order(code: asc).all()?
+
+  get /stations/:id list<Reading>!
+    auth role:member
+    db.readings.where(station_id: id).order(taken_at: desc).limit(50).all()?
+
+  patch /stations/:id(body StationPatch) Station!
+    auth role:admin
+    db.stations.update(id, body)?
+
+view StationList()
+  state filter = ""
+  load stations = api.stations()
+    pending
+      Spinner()
+    error e
+      col gap:8 pad:24
+        text "Could not load stations." color:danger
+        button "Retry" variant:ghost on tap: stations.reload()
+
+  col gap:16 pad:24 max_w:640
+    text "Tide stations" size:28 weight:700
+    input bind:filter placeholder:"Filter by code"
+    if stations.len() == 0
+      text "No active stations." color:muted
+    else
+      list stations as s key:s.id
+        row gap:8 align:center
+          link s.name to:"/stations/{s.id}" size:16 weight:600
+          text s.code size:13 color:muted

package/language/crib.md

@@ -0,0 +1,262 @@
+# Volaro in one page
+
+Indent 2 spaces, never tabs. `#` comments. No trailing commas. Last expression of
+a body is its return value. A file is a module; `_name` is file-private.
+
+## Types
+`int float str bool bytes time dur uuid json nil` · `T?` optional (never nests)
+`list<T> map<K,V> set<T>` · `T!` fallible (standard `Err`), `T!E` fallible with union `E`.
+No implicit numeric conversion: `1 + 1.0` is an error.
+
+```vl
+type Email = str                  # alias
+type Role = admin | author | member
+type Shape =
+  circle(r float)
+  rect(w float, h float)
+type Box                          # record
+  w int
+  h int = 1
+let b = Box{w: 2}                 # record literal; defaults may be omitted
+let xs list<str> = []             # empty literal needs an annotation
+```
+
+## Functions, match, errors
+```vl
+fn area(b Box) int
+  b.w * b.h
+
+fn parse_port(s str) int!
+  let n = to_int(s)?              # ? propagates; body must be fallible
+  if n < 1 or n > 65535
+    return err(out_of_range(n))
+  n
+
+let msg = match shape             # exhaustive; `_` matches anything
+  circle(r) -> "r={r}"
+  rect(w, h) if w == h -> "square"
+  _ -> "other"
+
+let u = load(id) ?? guest         # ?? supplies a fallback value
+let v = try load(id)
+catch not_found
+  create_guest()
+```
+A handled error **ends the `try`** — statements after it do not run. Code that must
+run either way goes *before* the `try`; fire-and-forget uses `spawn`.
+```vl
+`for x in xs` / `for i in 0..10` / `while c` · `break`, `skip`. Strings interpolate: `"id={x}"`.
+Named args allowed anywhere, **required for `bool` params**.
+
+## Modules
+```vl
+use ./models { User, Role }
+use ../shared/volaro/models { Post }
+use std.time { now }
+```
+
+## Data
+```vl
+model Post                        # a record with persistence
+  id uuid pk
+  title str
+  author_id uuid ref:User.id
+  published bool = false
+  created_at time = now()
+  index (published, created_at desc)
+
+db.posts.where(published: true).order(created_at: desc).limit(20).all()?
+db.posts.get(id)?  ·  db.posts.insert(body, author_id: session.user.id)?
+db.posts.update(id, body)?  ·  db.posts.delete(id)?
+
+# where() values are equality by default; wrap in a comparison predicate for
+# anything else — lt/lte/gt/gte/ne/between/any_of, one per named column, ANDed:
+db.posts.where(published: true, created_at: lt(cursor)).order(created_at: desc).all()?
+
+# no + on lists, no spread — concat/append are the only way to grow one:
+concat(xs, ys)  ·  xs |> append(x)
+```
+
+## Services (inbound HTTP; also generates a typed client under its own name)
+```vl
+service api
+  prefix "/api"
+  errors
+    not_found -> 404
+    forbidden -> 403
+    _ -> 500
+
+  get /posts(limit int = 20) list<Post>!
+    db.posts.where(published: true).limit(limit).all()?
+
+  get /posts/:id Post!
+    db.posts.get(id)?
+
+  post /posts(body NewPost) Post!
+    auth role:[author, admin]
+    db.posts.insert(body, author_id: session.user.id)?
+
+  delete /posts/:id nil!
+    auth owner:db.posts.get(id)?.author_id
+    db.posts.delete(id)?
+
+service content public            # whole service public; a guard still overrides
+  get /posts list<Post>!
+  get /health str
+    auth none                     # one deliberate public route in a guarded service
+```
+A route with no `auth` line is public. `auth role:` / `auth owner:` are the whole
+check. Inside a guarded handler `session.user` is a non-optional `User`.
+
+**Generated client names** (the view calls these): `get /posts` → `api.posts()` ·
+`get /posts/:id` → `api.post(id:)` · `post /posts` → `api.create_post(body:)` ·
+`patch|put /posts/:id` → `api.update_post(id:, body:)` · `delete /posts/:id` →
+`api.delete_post(id:)` · `post /posts/:id/publish` → `api.publish(id:)`.
+Path params are required named args. `... as name` overrides.
+
+## Views
+```vl
+view PostList(topic str = "all")
+  state query = ""
+  derive n = posts.len()
+  load posts = api.posts(limit: 20)      # api = the service name
+    pending
+      Spinner()
+    error e
+      text "Could not load." color:danger
+      button "Retry" on tap: posts.reload()
+
+  col gap:16 pad:24 max_w:720
+    text "Latest" size:28 weight:700
+    input label:"Filter" bind:query               # every input needs label: or aria_label:
+    if n == 0
+      text "Nothing yet." color:muted
+    else
+      list posts as p key:p.id            # key: is REQUIRED
+        link p.title to:"/posts/{p.id}" size:18
+    button "Save" variant:primary
+      on tap
+        route.to("/")
+```
+Elements are `Name attr:value` + indented children; `Name(a: 1)` in expression
+position. `col row stack grid text img button input link spacer` are auto-imported.
+
+`on mount` runs its body once (use it for a fetch `load` doesn't fit — one that
+accumulates instead of replacing, e.g. paginated results: `state`, `on mount`,
+append the result, repeat from a button's `on tap`). `on change` / `on unmount`
+are not implemented yet — don't reach for them.
+
+Accessible primitives (roles / focus / keyboard are carried, not written):
+```vl
+if confirming                              # a dialog is shown by rendering it
+  dialog title:"Discard?" on dismiss: confirming = false   # Esc + backdrop -> dismiss
+    text "Cannot be undone." color:muted
+    button "Discard" variant:danger on tap: discard()
+
+tabs bind:tab                              # or: selected:tab + `on select t: ...`
+  tab "overview" label:"Overview"
+    text "Overview panel"
+  tab "settings" label:"Settings"
+    text "Settings panel"
+```
+`dialog` needs `title` + `on dismiss`; no `open` attr. `tab` needs an id + `label`,
+only inside `tabs`. Raw `role:` / `aria-*` are not a thing — use the primitive.
+
+Every `input` needs an accessible name — *exactly one* of `label:"Email"`
+(visible) or `aria_label:"Search"` (name only); both is `E-INPUT-NAME-DUP`, an
+empty or `placeholder:`-only name is `E-INPUT-NAME`. Optional `help:` and
+`error:` are wired to the control for you:
+```vl
+derive email_err = if touched and not ok "Enter a valid email." else nil
+input label:"Email" bind:email type:email help:"For the receipt." error:email_err
+```
+`help:` links via `aria-describedby`; a non-nil `error:` also sets `aria-invalid`
+and shows the message. `error:` is usually a `derive` that is `nil` when valid.
+Errors are polite live regions. For other feedback use `status message`:
+one string-or-nil expression, no attributes/children. Keep it mounted; nil/""
+is idle. Changes update in place without moving focus; unchanged messages
+are not repeated. Ordinary dynamic `text` is not automatically live.
+
+Every `img` needs one `alt:` form — `alt:"real text"` (a dynamic one that goes
+empty is `render.empty_alt`), `alt:decorative` (emits `alt=""`), or `alt:todo` /
+`alt_todo:"note"` (builds + warns; `--release` makes it `E-IMG-ALT-TODO`).
+No `alt` is `E-IMG-ALT`.
+
+Every build that renders a page needs a module-level `page title:"…"` (becomes
+`<title>` + `document.title`; missing or empty is `E-PAGE-TITLE`, runtime-empty
+is `render.empty_page_title`). `h1`–`h6` are real headings — level is semantic,
+not `size:`; an intra-view level skip warns. `main` / `nav` are landmarks: one
+`main` per page, and sibling `nav`s need distinct `aria_label:`. A focus-visible
+"Skip to main content" link is injected automatically when there is a `main`.
+
+## Auth, outbound, concurrency
+```vl
+auth
+  user User
+  identity email
+  provider password
+    min_len 12
+  session
+    store cookie
+    ttl 30d
+  roles admin, author, member
+  default_role member
+
+api blog                            # outbound client; block name = the namespace
+  base "https://api.example.com/v1"
+  auth bearer env.BLOG_TOKEN        # optional; timeout defaults to 30s
+  get post(id uuid, fields str) Post!
+    path "/posts/{id}"            # {id} interpolates, URL-escaped
+    query fields                  # GET params MUST be named in query (or {..} the path)
+  post check(body Report) nil!     # post/put/patch: unrouted params are the body
+
+par                                 # run together, fail together
+  let user = db.users.get(id)?
+  let quota = billing.quota(id)?
+spawn                               # fire and forget; legal in a view, not cancelled on unmount
+  mailer.send_welcome(user.email)
+```
+A response decodes into the return type; a missing required field is `decode.missing_field`.
+Client calls: `auth.sign_in(email:, password:)`, `auth.sign_up(...)`,
+`auth.sign_out()`, `auth.verify_totp(code:)`, `route.to("/path")`.
+
+## Styling
+
+One sibling `theme.vl` groups `color`, `space`, `radius`, `font`, `screen`, and
+`motion reduce respect`; colors may add positional `dark "…"`. Numeric
+`gap:`/`pad:` values are px, while `gap:sm` resolves `theme.space.sm`.
+
+```vl
+recipe button
+  base "rounded-md transition-colors motion-reduce:transition-none focus-visible:outline focus-visible:outline-accent"
+  variant primary "bg-accent text-white"
+  default variant:primary
+
+card variant:raised
+  button "Save" variant:primary class:"w-full sm:w-auto"
+```
+
+Slice 1 recipes are `button`, `input`, and `card`. A recipe has one literal
+`base`, orthogonal `axis value "classes"` rows, and `default axis:value`.
+`class:` is one complete literal and additive only: no interpolation,
+`!important`, recipe property conflict, or recipe-plus-inline override.
+Unknown utilities fail the CSS build. Interactive recipes need visible-focus
+classes; motion needs `motion-reduce:`. Generated CSS, not class-token order,
+decides the cascade.
+
+## Project preferences and automation IDs
+
+Build/check discover nearest `volaro.json` up to the Git root (the old
+`volara.json` name is a hard error, not a fallback); `--config PATH` overrides
+discovery. Example: `{"schema_version":1,"testing":{"emit_ids":true}}`.
+No config defaults to emitting authored hooks. Unknown options/types/versions
+and duplicate JSON keys are errors. No secrets or accessibility opt-out.
+
+`button "Save" test_id:"save"` emits data-testid. Local ID: static lowercase
+slug, 1–80 chars. Scope: `Field test_scope:"editor"` makes its local
+`test_id:"name"` become `editor/name`. Row scope may be an explicit public
+string expression: `row test_scope:item.public_slug`. Never expose a list key
+automatically or use private identifiers. Scopes propagate into local views and
+dialog content; duplicate live IDs fail before the next tree is committed.
+Use scopes, not test_id, on component/dialog/tabs calls; tab hooks unsupported.
+Disabling emit_ids removes hooks without changing labels, events or behaviour.