Published by SAGEWORKS AI — Maun, Botswana
There are moments when you are building something and you realize the tool you need does not exist. Not a library. Not a framework. Not a configuration layer. The language itself is missing.
That is what happened with WebScript.
The Problem That Started This
The browser is a spatial environment. Every element has a position. Every transition has a curve. Every layout is a geometric relationship between objects in space.
And yet every language we use to program the browser is either document-oriented (HTML), cascade-oriented (CSS), imperative and procedural (JavaScript), or a type system overlay (TypeScript). Not one of them treats the browser as what it actually is: a spatial field where entities exist in geometric relationship to each other.
You want a panel that orbits the cursor with a harmonic depth transition? You write 40 lines of JavaScript. You want three cards positioned at phi-distributed angles on a circle? You calculate the trigonometry by hand, write the DOM manipulation, wire the animation frame, and manage the state.
The gap between what you mean and what you have to write is enormous.
WebScript closes that gap. It is the language that should have existed for the spatial web from the beginning.
What WebScript Is
WebScript is a declarative constraint-based spatial DSL that compiles simultaneously to HTML, CSS, SVG, JavaScript, TypeScript, and SQL.
Not a framework. Not a library. Not a preprocessor. A compiled language with its own grammar, type system, compiler pipeline, and browser runtime.
Four properties define it:
Declarative — you describe spatial relationships, not procedures.
Constraint-based — properties are bound to live equations, not static values. When an input changes, every dependent property updates automatically.
Spatial — geometry and position are first-class citizens of the language. orbit, distance, harmonic, phi are not imported utilities. They are primitives.
Relational — entities know each other. A panel knows its viewport. A card knows its cursor. A node knows its cluster. The language graph is a live relational system.
The Grammar — Six Constructs, No More
WebScript has exactly six sentence patterns. This is the complete language:
Construct 1 — Entity Declaration
card {
depth : 300
rotate : harmonic(0.5)
position : orbit(cursor)
}
Construct 2 — Relational Binding
The of particle comes from Mandarin topic-comment grammar. It declares ownership, containment, and membership.
panel of viewport {
sync : parent.rhythm
opacity : field(0.85)
depth : phi * 300
}
Particles available: of · at · as · by · through · into · from
Construct 3 — Equation Constraint
A live reactive binding. Re-evaluates whenever its inputs change.
card.rotation = cursor.angle * harmonic(0.4)
card.scale = distance(origin) ^ 0.5
Construct 4 — Classifier Generation
From Mandarin measure words. Declares batch spatial generation.
7 orbital nodes
3 harmonic layers
1 depth field
7 orbital nodes generates seven positioned entities distributed on an orbital path. The mathematics of the distribution is handled by the language.
Construct 5 — Fetch Declaration (WSQL)
Declares a data retrieval that simultaneously generates a SQL query and a spatial layout.
fetch nodes from sales_data {
where : revenue > harmonic(0.5)
order : spatial(distance(origin))
limit : fibonacci(6)[5]
map : orbital(result.count)
radius : phi^i * 40
color : hue(revenue.normalized)
}
One declaration. One SQL query. One spatial layout. They are the same thing.
Construct 6 — Page Boundary
Redefines the coordinate origin and containment boundary of a spatial environment.
page {
boundary : circle(phi * viewport.width)
origin : viewport.center
}
The Compilation Model
Every WebScript declaration compiles to all six targets simultaneously from a single relational graph.
Take one declaration:
panel of viewport {
depth : phi * 300
rotation : harmonic(cursor.angle * 0.4)
position : orbit(cursor, phi * 80)
}
This produces:
HTML
<div class="ws-panel" data-ws-depth="485.4" data-ws-orbit="cursor">
CSS
.ws-panel {
perspective: 485.4px;
transform: rotate(var(--ws-panel-rotation));
}
SVG
<circle data-entity="panel" />
positioned at dynamically calculated orbit coordinates.
JavaScript
document.addEventListener('mousemove', e => {
const angle = Math.atan2(e.clientY - cy, e.clientX - cx);
panel.style.setProperty('--ws-panel-rotation',
(0.5 - Math.cos(Math.PI * (angle * 0.4)) / 2) + 'rad');
});
TypeScript
interface WSPanel extends WSEntity {
depth : number;
rotation : WSHarmonic;
position : WSOrbit;
}
SQL
SELECT *, atan2(cursor_y - panel_y, cursor_x - panel_x) AS orbital_angle
FROM panels
One source. Six manifestations. All mathematically coherent because they all derive from the same relational constraint graph.
The Type System
WebScript has a spatial type system. Every value belongs to one of these types:
WSScalar → a number, possibly equation-derived
WSEquation → a live expression that resolves to a scalar
WSEntity → a named spatial object in the graph
WSParticle → a relational operator
WSClassifier → a spatial type qualifier (orbital, harmonic, depth, fibonacci)
WSFunction → a built-in spatial function
WSBoundary → a page boundary equation
WSField → a spatial influence area
WSConstraint → a reactive binding between entity.property and expression
WSNode → a data-carrying spatial entity (from WSQL)
The Built-in Function Library
These are the only built-in functions in v0.1. Every one is a spatial or mathematical primitive:
harmonic(t) 0.5 − cos(π·t) / 2
Easing. Maps [0,1] to [0,1] with smooth curve.
orbit(target, r) Position on circle of radius r around target
distance(a, b) Euclidean distance between two entities
field(value) Spatially typed scalar wrapper
phi 1.618033988749895
pi 3.14159265358979
fibonacci(n) First n Fibonacci numbers as array
hue(angle) HSL color derived from spatial angle
decay(rate) Trail fade multiplier for motion history
harmonic_scale(n) Distortion scale from polygon side count
No bloat. No utility sprawl. A closed set of spatial primitives that compose into everything else.
The Compiler Pipeline
Five stages. Clear build path.
Stage 1 — Lexer: Reads WebScript source. Produces a token stream. The six grammar constructs are the complete token set.
Stage 2 — Parser: Takes tokens. Produces the Abstract Syntax Tree as a JSON-native structure. Every WS declaration maps 1:1 to a JSON node. This is the bidirectional bridge — the AST is simultaneously the JSON API and the AI-generatable format.
Stage 3 — Graph Resolver: Takes the AST. Builds the relational constraint graph. Resolves entity references, particle relationships, and equation dependencies.
Stage 4 — Target Compilers: Six separate compilers, each consuming the runtime graph simultaneously.
Stage 5 — Runtime Engine: The browser-injected webscript.js. Approximately 8-12kb minified. Executes constraint equations reactively. Maintains the spatial index. Updates CSS custom properties when inputs change.
What WebScript Is Not
These boundaries are permanent:
WebScript does not replace JavaScript's control flow. No if, for, while, function in WebScript. JavaScript handles all procedural logic.
WebScript does not handle data validation, authentication, business logic, or server-side operations. These remain in their own layers.
WebScript does not transform HTML into geometry. HTML keeps its rectangular document model. WebScript projects geometry inside it.
WebScript does not replace CSS's cascade, specificity, or responsive design system. It generates mathematically coherent values for CSS to apply.
WebScript does not attempt to be general-purpose. It is a domain-specific language for one domain: spatial relational computation in the browser.
The Intellectual Lineage
WebScript draws from four sources and is none of them:
CSS — the declarative model, the property-value syntax, the idea that you describe what you want rather than how to achieve it.
GLSL — mathematical spatial thinking as a first-class mode. The browser as a field of values rather than a document of nodes.
GraphQL — the unified query philosophy. One declaration surfaces in multiple layers simultaneously. The query and the presentation are the same expression.
Mandarin grammar — the topic-comment structure and classifier system. panel of viewport reads as a topicalized statement: "speaking of the viewport, here is the panel." 7 orbital nodes uses measure-word logic — a spatial classifier before a noun.
The result is something none of those are: a language that treats the browser as a spatial field and programs it as a relational mathematical system.
Where It Goes
WebScript is one language with many native communities. The grammar does not change between them. The demonstrations do.
For web game developers: a declarative spatial layer for entity positions, collision constraints, camera following, and particle systems. The first language where game spatial logic is declared rather than procedurally written.
For data visualization engineers: a single declaration that simultaneously produces a SQL query and a spatial layout. The gap between data and geometry, closed.
For creative coders: the mental model of p5.js — fields, forces, particles, harmonics — expressed as a constraint grammar rather than a procedural script. Browser-native. No wrapper required.
For TypeScript developers: generated typed interfaces for every spatial entity. The mathematical coherence of the layout enforced at compile time.
For spatial / XR web: a declarative syntax for scene graphs, proximity constraints, and gaze-reactive positioning that reads as clearly as CSS but reasons in three dimensions.
For educators: the first programming language where spatial mathematics and visual output are the same syntax. A geometry class and a programming class simultaneously.
The Repository
The v0.1 implementation is live.
The repository contains the full language specification, compiler architecture, type system, runtime engine, standard library, WSQL bridge, CLI, playground, and test suite.
Source, specification, and build path: https://github.com/PEACEBINFLOW/webscript
The implementation is MIT licensed. The specification is Creative Commons Attribution 4.0 — anyone may implement WebScript, but Peace Thabiwa must be credited as the language designer.
The name WEBSCRIPT and the ⟁ symbol are trademarks of SAGEWORKS AI.
The Statement
The browser has been a spatial environment for thirty years.
It has never had a spatial language.
WebScript is that language.
Peace Thabiwa
SAGEWORKS AI — Maun, Botswana
https://github.com/PEACEBINFLOW/webscript
Top comments (0)