CLARABY MINESPACE INC.Open Studio ↗
DEVELOPER DOCUMENTATIONCLARA / 1.0.0-rc.1 · Native v16
CLARA DEVELOPER HANDBOOK / PUBLIC REFERENCE

Make the logic.
Build the world.

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.

Typed languageNative WebAssembly subsetTestable browser VMGame & physics scripting
ReferenceLanguage & platform
01 / INTRODUCTION

Build with CLARA

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.

{ }

Language & APIs

Typed functions, declared HTTP routes, bounded execution, explicit storage and safe report templates.

▣

Applications

Native API backends with normal browser HTML, CSS and JavaScript through App Builder.

◈

Compute & graphics

Numeric WASM kernels, deterministically tested game scenes and programmable Cubie physics examples.

Accurate mental model: CLARA is not a drop-in replacement for browser JavaScript, Python, a full graphics shader language or general native systems programming. Graphics rendering, browser DOM and some physics orchestration still use JavaScript/WebGL. The .clara programs define typed logic and numerical kernels inside that architecture.

Choose your starting point

02 / WHY CLARA

Benefits and architectural tradeoffs

BenefitWhere it comes fromImportant qualification
Predictable API behaviorTyped source and explicit routes compiled into checked bytecodeLogic correctness still requires tests and input validation
Portable developmentBrowser-side compilation, local project packages and same-origin server runtimesHosted CGI must be configured separately
Limited execution capabilitiesBounded VM steps, time, depth and storage operationsNot a formal security proof of the complete host
Fast numerical kernelsNative WebAssembly emission for supported pure numerical and Boolean functionsSupports typed numerical/Boolean pure functions only, not host capabilities
Inspectable, reproducible projectsSource, test definitions and SHA-256 package verificationHash integrity is not publisher authentication
Cross-subsystem reuseShared rules can feed APIs, AppMaker, games and terrain generationSubsystem adapters remain distinct implementations
03 / APPLICATIONS

Major use cases

04

Games and simulations

Use CLARA to author numeric scoring or physics kernels while the graphics engine supplies rendering, input, assets and simulation orchestration.

Open the game workspace →
05

Programmable companions

The Book of Cubie reconstructs mesh and motion data through native CLARA accessors and an editable assembly spell.

Open the storybook →
06

Offline-first experimentation

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 →
04 / GET STARTED

Your first native CLARA script

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.

01 / hello.clara
route GET "/api/hello" -> hello;
fn hello(req: Request): Response {
  let name: String = query(req, "name", "world");
  return json(200, {message: "Hello, " + name});
}
  1. Open Studio → Projects and select Hello API.
  2. Compile and activate the project; look for a successful build before testing.
  3. Send a browser test request to GET /api/hello?name=Cubie.
  4. Confirm the JSON body contains "Hello, Cubie".
  5. Edit the text, compile again, and rerun the test. Export the source and tests before clearing browser storage.

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.

05 / LANGUAGE

Syntax, statements, and expressions

Function declarations require named, typed parameters and a return type. Declarations end in semicolons. Curly braces define statement blocks. Comments can use // or /* ... */.

02 / control-flow.clara
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;
}
ConstructFormBehavior
Functionfn name(arg: Int): Int { ... }Named, typed entry point
Immutable locallet x: Int = 5;Cannot be reassigned
Mutable localmut x: Int = 5;May be reassigned with x = 6;
Conditionalif condition { ... } else { ... }else if is supported
Loopwhile condition { ... }Bounded by VM execution budget
Returnreturn result;Returns from current function
Arrays / objects[1,2] · {name:"A"}Indexed or named data
Indexingobj.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.

06 / LANGUAGE

Types and data structures

TypeExampleUsage
Int42Integer calculations; numeric WASM subset
Float0.5VM and supported native WASM finite floating-point operations, e.g. animation curves
BooltrueConditions and pure WASM Boolean results
String"Hello"Text and route payloads
NullnullAbsent value
Object{x: 1}Key/value records and JSON payloads
Array<Int>[1, 2, 3]Typed collections
AnystoreGet("key")Dynamic values from storage or requests
Requestreq: RequestHTTP handler argument
Responsejson(200, {})HTTP handler result
Voidfn f(): VoidDeclared 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.

07 / BUILD APIS

HTTP routes and typed handlers

Map a method and a URL path to a function, optionally requiring authentication. Route handlers accept Request and return Response.

03 / parameterized API
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.

Authorization: An 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.
08 / BUILD APIS

Storage, revisions, and access control

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.

04 / authenticated storage
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")});
}
FunctionPurpose
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.

09 / BUILD APIS

Safe HTML report templates

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.

05 / report template
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")});
}
Security boundary: Raw triple-brace interpolation, script/style/iframe/form tags, inline event handlers, JavaScript URLs and interpolated attributes are rejected. Create interactive frontends in App Builder using standard HTML, CSS and JS, connected to a CLARA backend.
10 / REFERENCE

Built-in functions

The following identifiers are from the actual checked VM built-in signature table. They are functions, not JavaScript APIs available directly from CLARA source.

FunctionReturnsParameters
queryStringRequest, String, String
pathStringRequest, String, String
bodyStringStringRequest, String, String
bodyIntIntRequest, String, Int
bodyBoolBoolRequest, String, Bool
jsonResponseInt, Any
textResponseInt, String
renderResponseInt, String, Object
htmlEscapeStringAny
requireBoolBool, String
assertBoolBool, String
storeGetAnyString
storePutBoolString, Any
storeDeleteBoolString
storeListArray<Any>String
storeGetVersionObjectString
storeComparePutBoolString, Int, Any
sha256StringAny
lenIntAny
strStringAny
intIntAny
nowString—

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.

11 / NATIVE COMPUTE

Compiling native WebAssembly

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.

06 / native Clara module
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.

Execution boundary: Safe-integer arithmetic is checked, floats must remain finite, and every native helper shares one execution budget. Recursion, I/O, requests, DOM operations, arrays, objects, built-ins, host calls, and floating-point remainder still require the regular VM or JavaScript integration. Native division returns Float; division by zero traps. Every wasmRun creates a new isolated instance for a fresh work budget.

Native function grammar

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.

12 / GRAPHICS

Scripting Cubie, games, and physics

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.

WorkspaceCLARA sourceWhat you can customize
Game Enginegame-rule.claraScoring rules consumed by the game
2D Physicsmultiphysics.claraMotion, collision and energy calculation kernels
3D Dynamicsdynamics3d.claraNumerical 3D motion and reflection kernels
Cubie Worldcubie-world.claraWorld velocity, gravity and terrain responses
Book of Cubiecubie-magic.claraPart assembly and animation curves
07 / Cubie assembly 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};
}
The original Cubie model data can be reconstructed from CLARA-generated accessors, but browser renderer, gesture input, physics integration and audio are separate runtime subsystems. Changing numeric code does not by itself create a new rendering engine.
13 / APPLICATIONS

Build a complete application

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.

  1. Open App Builder and create a project.
  2. Edit the HTML, CSS and JavaScript tabs for the UI.
  3. Edit the CLARA tab to define backend functions and routes.
  4. Select Build & preview. Inspect the preview console and native API test panel.
  5. Export both the frontend ZIP and native backend package for controlled deployment.

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.

14 / PROJECTS

Projects, tests and reproducible builds

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.

08 / project input to packageProject
{
  "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.

15 / LIVE EXAMPLES

Script playground

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.

LOCAL EXECUTION

Write, compile, run.

Ready

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.
16 / REFERENCE

Language grammar at a glance

Condensed core grammar
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.

17 / REFERENCES

Public interfaces and technical specifications

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.

WORKFLOW / OPERATIONS

Build diagnostics and recovery

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.

WORKFLOW / OPERATIONS

2. Host a real application

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.

  1. Open Settings and run the runtime checks. The server health endpoint must return a CLARA response.
  2. Get the hosting administrator token from the host's private file system; see DEPLOY.txt. Never expose it in a public file or send it to visitors.
  3. Open Teams and create an organization. Save the organization ID. Redeem the invitation separately for member access.
  4. Choose a project with passing tests. In Deploy, enter the organization ID and hosting administrator token. Build, test & stage runs the local checks and server VM check; the candidate is inaccessible before promotion.
  5. Choose a slug and preview channel, review the report, then promote explicitly. Copy the channel base URL and append a declared route. Promote to production only after verification.
  6. For protected API calls, select the release and issue a scoped application credential. Copy it once and keep it in a trusted client or server. Never embed a write key in JavaScript shipped to anonymous users.

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.

WORKFLOW / OPERATIONS

3. Compute and automate

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.

WORKFLOW / OPERATIONS

4. Collaborate, resolve and publish

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.

WORKFLOW / OPERATIONS

5. Connect agents and inspect adoption

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.

WORKFLOW / OPERATIONS

AI training and agent creation

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.

WORKFLOW / OPERATIONS

Working example: CLARA Projects

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.

WORKFLOW / OPERATIONS

The Book of Cubie

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 ↗
WORKFLOW / OPERATIONS

6. Before production use

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.

18 / TROUBLESHOOTING

Compiler and deployment troubleshooting

Why does my CLARA code compile but not run as WASM?

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.

Why does a write return 401 or 403?

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.

Why am I seeing HTTP 500 on hosting?

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.

How do I prevent losing my work?

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.

How do I make a photorealistic game?

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.

Keep building.

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.