Language & APIs
Typed functions, declared HTTP routes, bounded execution, explicit storage and safe report templates.
The language, the runtime, the workflows. A practical, source-aligned guide to writing, testing and deploying CLARA—built for first-time creators and experienced developers.
CLARA is a typed web-application language and development platform from MineSpace Inc. Its browser VM compiles source into checked bytecode; a pure, bounded numerical subset can compile to native WebAssembly. The wider platform provides application workflows, isolated previews, portable projects, compute adapters, and graphics/physics studios.
Typed functions, declared HTTP routes, bounded execution, explicit storage and safe report templates.
Native API backends with normal browser HTML, CSS and JavaScript through App Builder.
Numeric WASM kernels, deterministically tested game scenes and programmable Cubie physics examples.
.clara programs define typed logic and numerical kernels inside that architecture.| Benefit | Where it comes from | Important qualification |
|---|---|---|
| Predictable API behavior | Typed source and explicit routes compiled into checked bytecode | Logic correctness still requires tests and input validation |
| Portable development | Browser-side compilation, local project packages and same-origin server runtimes | Hosted CGI must be configured separately |
| Limited execution capabilities | Bounded VM steps, time, depth and storage operations | Not a formal security proof of the complete host |
| Fast numerical kernels | Native WebAssembly emission for supported pure numerical and Boolean functions | Supports typed numerical/Boolean pure functions only, not host capabilities |
| Inspectable, reproducible projects | Source, test definitions and SHA-256 package verification | Hash integrity is not publisher authentication |
| Cross-subsystem reuse | Shared rules can feed APIs, AppMaker, games and terrain generation | Subsystem adapters remain distinct implementations |
Task tracking, approvals, local dashboards and operational tools with typed endpoints and revision-checked records.
Inspect the CLARA Projects example →Same-origin JSON APIs, route-level authentication, bounded storage and testable client/server contract behavior.
Learn routes and request handling →Pure numerical rules compiled to WASM; verified score, dispatch, and game-rule calculations.
Learn native compute boundaries →Use CLARA to author numeric scoring or physics kernels while the graphics engine supplies rendering, input, assets and simulation orchestration.
Open the game workspace →The Book of Cubie reconstructs mesh and motion data through native CLARA accessors and an editable assembly spell.
Open the storybook →Write locally, compile in the browser, test against scratch data and export packages without deploying arbitrary source to a public server.
Start a local project →CLARA uses .clara source files. A program declares named functions, optional HTTP routes and optional safe HTML templates. Begin with a minimal route that returns JSON.
route GET "/api/hello" -> hello;
fn hello(req: Request): Response {
let name: String = query(req, "name", "world");
return json(200, {message: "Hello, " + name});
}GET /api/hello?name=Cubie."Hello, Cubie".Read the code: route maps HTTP to a function; req: Request is the typed parameter; query reads a query value with a default; json constructs the response.
Function declarations require named, typed parameters and a return type. Declarations end in semicolons. Curly braces define statement blocks. Comments can use // or /* ... */.
fn clamp(value: Int, low: Int, high: Int): Int {
mut result: Int = value;
if result < low { result = low; }
if result > high { result = high; }
return result;
}
fn sumTo(n: Int): Int {
mut i: Int = 0;
mut total: Int = 0;
while i < n { total = total + i; i = i + 1; }
return total;
}| Construct | Form | Behavior |
|---|---|---|
| Function | fn name(arg: Int): Int { ... } | Named, typed entry point |
| Immutable local | let x: Int = 5; | Cannot be reassigned |
| Mutable local | mut x: Int = 5; | May be reassigned with x = 6; |
| Conditional | if condition { ... } else { ... } | else if is supported |
| Loop | while condition { ... } | Bounded by VM execution budget |
| Return | return result; | Returns from current function |
| Arrays / objects | [1,2] · {name:"A"} | Indexed or named data |
| Indexing | obj.name · obj["name"] · list[0] | Returns null for missing values |
Operators: arithmetic + - * / %; comparisons == != === !== < > <= >=; logical && || !; unary minus. There are no documented for loops, classes, imports, asynchronous function declarations or arbitrary DOM calls in the core grammar.
| Type | Example | Usage |
|---|---|---|
Int | 42 | Integer calculations; numeric WASM subset |
Float | 0.5 | VM and supported native WASM finite floating-point operations, e.g. animation curves |
Bool | true | Conditions and pure WASM Boolean results |
String | "Hello" | Text and route payloads |
Null | null | Absent value |
Object | {x: 1} | Key/value records and JSON payloads |
Array<Int> | [1, 2, 3] | Typed collections |
Any | storeGet("key") | Dynamic values from storage or requests |
Request | req: Request | HTTP handler argument |
Response | json(200, {}) | HTTP handler result |
Void | fn f(): Void | Declared no-result function |
Types are checked by the compiler. Int may be passed where Float is expected. String concatenation uses +. Division produces a floating-point value in the VM. Avoid assuming a JavaScript type or general-purpose dynamic language behavior.
Map a method and a URL path to a function, optionally requiring authentication. Route handlers accept Request and return Response.
route GET "/api/square/:n" -> squareApi;
fn square(n: Int): Int { return n * n; }
fn squareApi(req: Request): Response {
let n: Int = int(path(req, "n", "0"));
require(n >= 0 && n <= 1000, "n must be 0..1000");
return json(200, {result: square(n)});
}Supported declaration methods are GET, POST, PUT, PATCH, and DELETE. Use query(req, name, default), path(req, name, default), and typed body helpers to validate data.
auth route requires a bearer credential. Non-GET writes also require authorization under the browser/server VM capability policy. The guide playground supplies a test-only token against disposable in-memory data; it never uses your real keys.Use the VM storage built-ins for scoped key/value persistence. Direct storage writes require an authorized request. Keep write credentials on trusted server-side clients; do not embed them in a public frontend.
route POST "/api/item" auth -> save;
route GET "/api/item" auth -> read;
fn save(req: Request): Response {
let value: String = bodyString(req, "value", "");
require(len(value) > 0, "Value required");
storePut("item", value);
return json(201, {saved: true});
}
fn read(req: Request): Response {
return json(200, {value: storeGet("item")});
}| Function | Purpose |
|---|---|
storeGet(key) | Read one value or null |
storePut(key, value) | Write a value when authorized |
storeDelete(key) | Remove a value when authorized |
storeList(prefix) | List matching records |
storeGetVersion(key) | Read value and revision |
storeComparePut(key, rev, value) | Write only if the revision still matches |
Core VM enforces a storage key maximum of 256 UTF-8 bytes and a stored JSON value maximum of 32 KiB. Project, hosted and scratch storage have their own isolation and quota constraints. Prefer revision-aware writes when multiple clients can edit the same record.
CLARA report templates interpolate escaped scalar text values using {{field}}. They are intended for simple server-rendered documents and reports, not arbitrary interactive web pages.
route GET "/api/page" -> page;
template "page" = "<main><h1>{{name}}</h1><p>Welcome to CLARA.</p></main>";
fn page(req: Request): Response {
return render(200, "page", {name: query(req, "name", "Visitor")});
}The following identifiers are from the actual checked VM built-in signature table. They are functions, not JavaScript APIs available directly from CLARA source.
| Function | Returns | Parameters |
|---|---|---|
query | String | Request, String, String |
path | String | Request, String, String |
bodyString | String | Request, String, String |
bodyInt | Int | Request, String, Int |
bodyBool | Bool | Request, String, Bool |
json | Response | Int, Any |
text | Response | Int, String |
render | Response | Int, String, Object |
htmlEscape | String | Any |
require | Bool | Bool, String |
assert | Bool | Bool, String |
storeGet | Any | String |
storePut | Bool | String, Any |
storeDelete | Bool | String |
storeList | Array<Any> | String |
storeGetVersion | Object | String |
storeComparePut | Bool | String, Int, Any |
sha256 | String | Any |
len | Int | Any |
str | String | Any |
int | Int | Any |
now | String | — |
require reports an input error (HTTP 422 in the API handler); assert reports an assertion failure. now() is environment-dependent and unsuitable for deterministic pure rules. The VM limits execution to configured step, time and call-depth budgets.
compileWasm(source, functionName) compiles a reachable graph of pure, nonrecursive Clara functions into a standard WebAssembly module. Parameters and returns may use Int, Float, and Bool. Numerical helpers compile together; no JavaScript host imports are required.
fn square(value: Int): Int {
return value * value;
}
fn score(value: Int): Int {
return square(value) + 10;
}
fn parity(value: Int): Int {
return value % 2;
}
fn easeInOut(time: Float): Float {
return time * time * (3.0 - 2.0 * time);
}Compile score with [7] to receive 59. Switch the function to easeInOut with [0.5] to execute a floating-point animation curve. parity demonstrates signed integer remainder. The actual native module and its helper functions appear in the playground output.
Float; division by zero traps. Every wasmRun creates a new isolated instance for a fresh work budget.Pure helpers, if, bounded while, locals, typed arguments, return values, short-circuit Boolean logic, numeric comparisons, addition, subtraction, multiplication, division, and signed Int % Int are supported. Float literals support exponent form such as 2.5e-4. Integers must stay inside JavaScript's exact safe-integer range.
For host networking, storage and graphics, use the full CLARA VM and platform APIs. The unified pipeline still validates its own restricted numerical rules separately.
CLARA's graphics environments use a hybrid architecture: .clara code defines numerical rules, geometry-data accessors and assembly curves, while existing JavaScript and WebGL systems perform draw calls, input handling and orchestration.
| Workspace | CLARA source | What you can customize |
|---|---|---|
| Game Engine | game-rule.clara | Scoring rules consumed by the game |
| 2D Physics | multiphysics.clara | Motion, collision and energy calculation kernels |
| 3D Dynamics | dynamics3d.clara | Numerical 3D motion and reflection kernels |
| Cubie World | cubie-world.clara | World velocity, gravity and terrain responses |
| Book of Cubie | cubie-magic.clara | Part assembly and animation curves |
// Actual style of Cubie's assembly spell (VM Float / Object; not numeric WASM)
fn ease(t: Float): Float { return t * t * (3.0 - 2.0 * t); }
fn pose(t: Float, x: Float, y: Float, z: Float): Object {
let u: Float = ease(t / 1000.0);
let away: Float = 1.0 - u;
let arc: Float = 4.0 * u * away;
return {spread: 1.65 * away, rise: 0.85 * arc,
twist: 1.2 * away, turn: 0.60 * arc,
x: x, y: y, z: z};
}A full CLARA app has two complementary pieces: a standard browser interface in HTML, CSS and JavaScript, and a native CLARA backend that declares routes and data operations. App Builder packages the frontend, previews the backend in an isolated local VM and exports a site bundle.
Preview data is separate from hosted databases. Browser scripts use the provided Clara.api integration in the preview; deploy a backend release and configure a trusted endpoint before treating it as a production app. Public websites must not embed privileged application credentials.
A portable project package uses format CLARA-PROJECT-1 with a name, source, up to 16 HTTP tests, compiled bytecode and SHA-256 integrity metadata. The compiler regenerates bytecode during verification; imported untrusted bytecode is not executed as-is.
{
"name": "Hello API",
"source": "route GET \"/api/hello\" -> hello; ...",
"tests": [
{"name": "Greeting", "method": "GET",
"path": "/api/hello?name=Clara", "status": 200,
"contains": "Hello, Clara"}
]
}The snippet is the input to project packaging, not the complete exported package. The actual exported package adds format, program and sha256 fields. Use the existing project schema and reviewed starter tests as the authoritative formats.
In Studio, compile and activate after source changes; run tests against isolated scratch storage; restore the last working source if a draft fails. A passed compilation does not imply tests have passed. Back up projects before clearing local data.
Compile against the actual clara-core.mjs VM, or compile a supported numerical function to native WebAssembly. All API executions here use a throwaway, in-memory store and a test-only bearer token; they never connect to production data.
Runs against local JavaScript modules in the browser. Route mode requires a declared route; WASM mode requires a supported pure function.
Select an example and run it. Compilation and API execution occur only after you press a button.
program := (function | route | template)*
function := "fn" IDENT "(" typed_params ")" ":" TYPE block
route := "route" METHOD STRING ["auth"] "->" IDENT ";"
template := "template" STRING "=" STRING ";"
block := "{" statement* "}"
statement:= ("let" | "mut") IDENT ":" TYPE "=" expr ";"
| "return" [expr] ";"
| "if" expr block ["else" (block | if_stmt)]
| "while" expr block
| expr ";" | block
TYPE := Int | Float | Bool | String | Null | Void | Any
| Object | Request | Response | Array<TYPE>This is a readable summary of the actual parser, not a normative machine grammar. Named function calls, literals, object/array expressions, indexing and ordinary infix operators follow the precedences implemented in clara-core.mjs. Unsupported syntax produces a compiler error with source line and column.
Full module-specific specifications are in the corresponding .json manifests. This guide covers the language and developer workflow; it does not replace the machine-readable contract of every optional service.
In Studio → Build, the Build health panel shows the current compiler error, line and column, a source excerpt and a jump-to-error action. A failed compile or an edited draft has no active browser build. Rebuild after editing. Clear build removes compiled artifacts while preserving source, tests and runtime data. Restore last good source reinstates the last successfully compiled draft. Raw recovery backups can be exported and imported even if compilation or test JSON is invalid. Reset to blank application or to the example resets source and tests, detaches the remote sync binding, and preserves runtime data and deployed releases. Erase local application data is a separate confirmed operation affecting only the current browser project.
CLARA server HTML templates use escaped text fields like {{title}}. Active tags (script, style, iframe, object, embed, form), inline event assignments, JavaScript URLs, raw triple braces and interpolated attributes are rejected. Put interactive UI and styling in a separate frontend. The compiler identifies the offending template and location. No HTML validation bypass is provided.
Upload the Clara directory to the document root, including its hidden .htaccess file. Python 3 CGI and executable permissions (755) on runtime.cgi and platform.cgi are needed for hosted services. HTTPS is required for private operations. The browser runtime does not require PHP, Node or installation.
Application keys are bound to an immutable release; issuing a different release requires a new key. Channel switching is routing, not a database migration. A release has its own database; preview and production sharing a release share its database.
Use Compute for supported straight-line integer/Boolean functions and generated WASM/WGSL/GLSL artifacts. Use Fabric for bounded parallel range workloads, and Grid for persistent same-origin jobs with leases, retry and replay. GPU availability is device dependent. Grid does not continue with every worker tab closed. Runtimes provides the separate WASM compiler and optional host-configured cron. Public IPFS distribution is a static copy, not a server runtime.
Teams provides private organizations and owner/editor/viewer access. Connect supports explicit revision-safe push/pull, client-encrypted package exchange, scoped team credentials and verified function library linking. Ordinary synchronization is server-readable. Encrypted exchange needs a strong passphrase shared separately; there is no recovery. Public software metadata is published through NEXUS; WORLD searches explicitly trusted registries and discovers DNS descriptors through DNS-over-HTTPS. A CLARA name is an application identifier, not an operating-system DNS address. Private discovery uses independent credentials and explicit peers.
Public discovery: capabilities, OpenAPI, agent guide, MCP configuration. Public MCP offers reviewed tools; custom compilation and execution use the local stdio MCP server from the full source package on Node.js 22 or newer. Private administrative actions are not public MCP tools.
Company Insights is administrator-only. Browser analytics are opt-in; aggregate public tool counts are separate. Settings includes consent controls. No source, request bodies or credentials are collected by the optional feature analytics.
CLARA AI provides a persistent word-bigram model and compact trained 890-parameter neural character model, not a general-purpose conversational LLM. Open AI Studio, add the included teaching corpus or approve your own permitted text, train a batch, and create an evidence, word-prediction or neural-character agent. Use separate held-out documents for evaluation. Browser and server models are independent. Hosted access requires the installation administrator bearer; never share it with other developers or expose it in a client app.
For hosted automatic learning, enable automatic processing and optionally configure a cron command: /usr/bin/python3 /absolute/path/Clara/ai_cron.py. The operator-only ai_ingest.py --help command imports rights-cleared local UTF-8 text and explicitly allowlisted HTTPS plaintext. It does not fetch arbitrary web pages. Keep model snapshots and backups private, and remove deleted data from copies under your control. See training and data policy.
Launch the application to manage tasks on this device, run verified priority calculations and transfer encrypted snapshots. Open its Developer view to inspect the real request trace and run isolated tests. Use Open source in Studio to create an editable copy, or download its native package. The application includes a same-origin hosted API connection for a deployed release; local and server data are separate.
Machine-readable application specification · Language source.
Learn Clara through a seven-chapter animated construction story. Compile the original mesh and animation data, edit a live assembly spell, and install a verified Clara-built Cubie.
Open the storybook ↗Before hosting an application, verify the installation and the environments your users will rely on. Configure HTTPS, request throttling and private backups; test the real host, actual browsers, agents and GPU hardware you intend to support. The server checks uploaded bytecode, not an independent source compiler. Public writes require a credential; there is no general-purpose end-user authentication system. Do not use shared administrator credentials in application clients. Review applicable legal and licensing requirements, privacy handling and the MineSpace notices before launch.
The VM compiler supports strings, objects, built-ins, routes and host integration. Native WASM supports pure Int/Float/Bool functions and nonrecursive helper calls, but not host APIs, recursion or collections. Try a fn points(value: Int): Int with arithmetic and no calls.
Write operations and auth routes require authorization. Run the code in an isolated test console to validate logic, then configure a scoped credential for the deployed release. Never publish your administrator token.
Check the separate shell and Python CGI probes in Diagnostics. If minimal probes fail, inspect DreamHost file ownership, executable permissions, line endings, and web server error logs before modifying source code.
Export project packages and website ZIPs regularly. Browser storage can be cleared by the user or device. Release packages do not include hosted databases or secrets.
Use the existing graphics and game workspaces for assets, rendering and input, and CLARA numeric functions for supported game rules and physics kernels. The current engine is not a production-ready AAA renderer or physics implementation.
Open Studio, explore the sample projects, or inspect the real compiler and runtime definitions. Every example in the playground is executed locally, against the shipped modules.