Home

Oriented-Direct (.osp) — Official Language Specification & Technical Manual (v1.4.0)

Oriented-Direct is a modern, high-performance, unambiguous programming language that transpiles directly into clean, standard ECMAScript (ES Modules) with zero external runtime dependencies.

Designed from mathematical first principles for browser and Node.js environments, Oriented-Direct eliminates historic JavaScript verbosity, replaces legacy DOM APIs with native compile-time directives, enforces immutability by default, guarantees strict equality, and provides a built-in zero-configuration multi-module bundler, local development server (ospc dev), and high-precision Source Maps (.map).

---

1. Core Architecture and Design Philosophy

JavaScript was conceived in 1995 as a lightweight browser scripting language. Over three decades, web development accumulated complex layers of external abstractions (frameworks, virtual DOM engines, transpilers, and package managers) to mitigate language deficiencies.

Oriented-Direct resolves these architectural challenges directly at the language level:

1. DOM as a First-Class Citizen: Native @ directives eliminate the verbosity of document.querySelector and event listener boilerplate.
2. Immutability by Default: Variables declared with val are immutable constants; mutable state requires explicit mut.
3. Strict Equality Guarantee: Comparison operators (is, is not, ==, !=) compile exclusively to strict identity checks (=== and !==). Loose type coercion bugs are eliminated.
4. Linear Data Pipelines: The pipeline operator (|>) allows clean, readable, left-to-right functional data transformations.
5. High-Precision Native Source Maps: Pure JavaScript Base64-VLQ differential delta state machine with zero coordinate drift and embedded sourcesContent.
6. Zero-Dependency Project Ecosystem: The compiler (ospc) contains a built-in module resolver, multi-module bundler, and development server, removing the requirement for Webpack, Vite, or Babel.

---

2. Compiler Installation and CLI Reference

The compiler binary is ospc (or oriented-direct).

CLI Command Matrix

Command	Description
ospc dev [port]	Compiles the project, copies declared assets, activates real-time Source Maps, and launches an HTTP development server with automatic file-watching recompilation (default port: 3000).
ospc serve [port]	Alias for ospc dev.
ospc build [entry.osp]	Compiles and bundles the project according to package.json or CLI flags.
ospc build --public	Bundles code into public/app.js and copies static assets (index.html, styles.css) into public/.
ospc build --public --sourcemap	Bundles code into public/ and generates public/app.js.map with full sourcesContent.
ospc compile <file.osp>	Transpiles a single .osp file to an equivalent .js file.
ospc run <file.osp>	Transpiles/bundles the target file and immediately executes it using Node.js.
ospc watch [entry.osp]	Monitors the file tree and recompiles automatically upon filesystem modifications.
ospc --help / ospc -v	Displays usage instructions or compiler version details.

Source Map CLI Flags

• -s, --sourcemap: Enables external .js.map generation.
• -s inline, --sourcemap inline: Emits Source Maps directly as inline Base64 Data URIs inside the bundled JavaScript output.

---

3. Project Configuration (package.json / osp.json)

Oriented-Direct projects are configured declaratively in package.json under the "osp" property or inside a dedicated osp.json file.

{
  "name": "my-oriented-direct-app",
  "version": "1.4.0",
  "type": "module",
  "scripts": {
    "dev": "ospc dev",
    "serve": "ospc dev",
    "build": "ospc build --public --sourcemap",
    "watch": "ospc watch --public"
  },
  "osp": {
    "entry": "src/main.osp",
    "outDir": "public",
    "outFile": "app.js",
    "bundle": true,
    "format": "esm",
    "port": 3000,
    "sourcemap": true,
    "minify": false,
    "assets": [
      "index.html",
      "styles.css",
      "assets/"
    ]
  }
}

Standard Project Layout

my-project/
├── package.json           # Build, bundler, server, and sourcemap configuration
├── index.html             # Source HTML5 interface
├── styles.css             # Source styles
├── src/                   # 100% Oriented-Direct source code
│   ├── main.osp           # Application entry point
│   ├── utils/             # Helper utilities and shared functions
│   └── modules/           # Domain-specific components
└── public/                # Self-contained production distribution directory
    ├── index.html         # Asset copied automatically by compiler
    ├── styles.css         # Asset copied automatically by compiler
    ├── app.js             # Monolithic bundled JavaScript output
    └── app.js.map         # High-precision Source Map with embedded sourcesContent

---

4. Language Grammar and Syntax Reference

4.1 Variable Declarations

Oriented-Direct prohibits let, const, and var.

val maximumDepth = 450;    // Immutable constant (compiles to const)
mut currentHeartRate = 110; // Reassignable variable (compiles to let)

currentHeartRate = 45;

---

4.2 Logical Operators and Comparisons

All comparisons compile to strict JavaScript operators.

Operation	Oriented-Direct Syntax	Compiled JavaScript
Strict Equality	a is b or a == b	a === b
Strict Inequality	a is not b or a != b	a !== b
Logical Conjunction	a and b	a && b
Logical Disjunction	a or b	a || b
Logical Negation	not a	!a
Nullish Coalescing	a ?? b	a ?? b

if (currentHeartRate < 20 and not isSurfaceBreathing) {
  @info("Deep bradycardia active");
}

---

4.3 Control Flow and Pattern Matching

Conditionals

if (depth > 200) {
  @log("Mesopelagic zone");
} else {
  @log("Epipelagic zone");
}

// Inverted conditional (executes when condition is falsy)
unless (isInitialized) {
  initializeSubsystems();
}

Pattern Matching (match)

val label = match (statusCode) {
  case 200 => "Operation Successful"
  case 404 => "Resource Not Found"
  case 500 => "Internal System Fault"
  default => "Unrecognized Status"
};

---

4.4 Iteration Constructs

Oriented-Direct provides four optimized looping paradigms:

// 1. C-Style 3-Part Loop (Use 'mut' for mutable iteration counters)
for (mut i = 0; i < buffer.length; i += 4) {
  processBufferChunk(i);
}

// 2. Numeric Range Loop
for (val step in 0..100 step 10) {
  @log("Progress checkpoint:", step);
}

// 3. Iterable / Array Collection Loop
for (val item in itemArray) {
  renderItem(item);
}

// 4. Object Key Enumeration Loop
for (val key of configurationObject) {
  @log(key, configurationObject[key]);
}

---

4.5 Sealed Structs and Classes

struct (Sealed Data Model)

Defining a struct automatically generates a class constructor fortified with Object.seal(this). This guarantees memory integrity and prevents accidental property additions at runtime.

struct TelemetryRecord { specimenId, latitude, longitude, depthMeters }

val record = new TelemetryRecord("HS-409", 47.5, -61.8, 382.4);

class (Stateful Components)

class AcousticSynthesizer {
  constructor(sampleRate) {
    this.sampleRate = sampleRate;
    this.audioContext = null;
  }

  start() {
    this.audioContext = new (@win.AudioContext || @win.webkitAudioContext)();
  }
}

---

4.6 Pipeline Operator (|>)

The pipeline operator passes the result of the left-hand expression as the first argument to the right-hand function.

val normalizedString = rawInput |> trimText |> toLowerCase |> sanitize;

---

5. Directives Reference (@ Macro System)

Directives provide zero-cost abstractions over the DOM, browser window, and console subsystems.

5.1 DOM Querying and Manipulation

Directive	Signature	Description
@doc	@doc	Points safely to the global document object.
@win	@win	Points safely to the global window object.
@find	@find(selector, parent?)	Executes parent.querySelector(selector). Safe against null parents.
@all	@all(selector, parent?)	Executes Array.from(parent.querySelectorAll(selector)).
@id	@id(idString)	Fast lookup via document.getElementById(idString).
@text	@text(el, content?)	Getter/setter for el.textContent.
@html	@html(el, content?)	Getter/setter for el.innerHTML.
@val	@val(el, value?)	Getter/setter for form element value (el.value).
@attr	@attr(el, name, value?)	Getter/setter for element attributes.
@css	@css(el, { key: val })	Applies inline styles via Object.assign(el.style, { ... }).
@create	@create(tag, attrs, ...children)	Declaratively constructs DOM elements with properties, inline styles, and child nodes.

5.2 Event Management

Directive	Signature	Description
@on	@on(target, event, handler, opts?)	Attaches an event listener (addEventListener). Returns the target.
@off	@off(target, event, handler, opts?)	Detaches an event listener (removeEventListener).
@emit	@emit(target, event, detailObj)	Dispatches a CustomEvent with { detail: detailObj, bubbles: true }.

5.3 Diagnostics and Console Directives

Directive	Compiled Equivalent
@log(...)	console.log(...)
@info(...)	console.info(...)
@warn(...)	console.warn(...)
@error(...)	console.error(...)

---

6. Multi-Module Development & Source Maps Architecture

Oriented-Direct v1.4.0 introduces an integrated single-pass compilation and bundling engine.

6.1 Inline Export Assignments (TDZ Elimination)

The bundler assigns module exports inline simultaneously with declaration:

const formatPercentage = exports.formatPercentage = function(valNum) { ... };
const Specimen = exports.Specimen = class Specimen { ... };

This architectural improvement guarantees zero Temporal Dead Zone (TDZ) ReferenceError anomalies across all exported symbols (val, struct, class, and fn).

6.2 Base64-VLQ Differential Delta State Machine

Source Maps in Oriented-Direct are computed natively without third-party dependencies:

• VLQ Engine (src/sourcemap/vlq.js): Pure bitwise variable-length quantity serializer formally verified over 100,000+ integer conversions.
• Delta Vector Compression: Mappings compute differential displacements ($\Delta C_{gen}, \Delta SourceID, \Delta L_{orig}, \Delta C_{orig}$) per AST statement.
• Embedded sourcesContent: The complete source text of all .osp modules is included in the .map file, enabling offline and zero-config in-browser DevTools debugging even when source directories are not served publicly.
• 0% Coordinate Drift: Formally verified with 10,000 mapping points across 100 synthetic modules.

---

7. Advanced Integration Patterns

7.1 WebGL, Three.js & Touch Gestures for Smartphones

Oriented-Direct interfaces directly with WebGL contexts and 3D graphics libraries with native smartphone touch gestures.

import { setupLighting } from "./observatory/lighting.osp";
import { buildEnvironment } from "./observatory/environment.osp";

export fn init3DHabitat() {
  val container = @id("webglViewport");
  unless (container) return;

  try {
    val THREE = @win.THREE;
    unless (THREE) throw new Error("Three.js runtime unavailable");

    val scene = new THREE.Scene();
    val camera = new THREE.PerspectiveCamera(45, container.clientWidth / container.clientHeight, 0.1, 1000);
    val renderer = new THREE.WebGLRenderer({ antialias: true, powerPreference: "high-performance" });

    renderer.setSize(container.clientWidth, container.clientHeight);
    renderer.setPixelRatio(Math.min(@win.devicePixelRatio || 1, 2));
    container.appendChild(renderer.domElement);

    setupLighting(scene, THREE);
    buildEnvironment(scene, THREE);

    fn renderLoop() {
      requestAnimationFrame(renderLoop);
      renderer.render(scene, camera);
    }
    renderLoop();
  } catch (err) {
    @error("WebGL Initialization Notice:", err);
  }
}

7.2 Web Audio API & Mobile Autoplay Policy Unlock

export fn synthesizeSignal(frequencyHz, durationSeconds) {
  try {
    val AudioContextClass = @win.AudioContext || @win.webkitAudioContext;
    unless (AudioContextClass) return;

    val ctx = new AudioContextClass();
    if (ctx.state is "suspended") {
      ctx.resume();
    }

    val osc = ctx.createOscillator();
    val gain = ctx.createGain();

    osc.type = "sine";
    osc.frequency.setValueAtTime(frequencyHz, ctx.currentTime);

    gain.gain.setValueAtTime(0.01, ctx.currentTime);
    gain.gain.linearRampToValueAtTime(0.3, ctx.currentTime + 0.05);
    gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + durationSeconds);

    osc.connect(gain);
    gain.connect(ctx.destination);

    osc.start();
    osc.stop(ctx.currentTime + durationSeconds + 0.05);
  } catch (err) {
    @error("Audio synthesis notice:", err);
  }
}

---

8. Anti-Patterns and Troubleshooting Guide

1. Using JavaScript Logical Operators

• Incorrect: if (isValid && !hasError)
• Correct: if (isValid and not hasError)

2. Using val in Mutable C-Style Loop Counters

• Incorrect: for (val i = 0; i < count; i++) (Triggers constant mutation error)
• Correct: for (mut i = 0; i < count; i++)

3. Emitting let, const, or var

• Incorrect: let status = "ready";
• Correct: mut status = "ready";

4. Forgetting File Extensions in Imports

• Incorrect: import { helper } from "./utils/math"
• Correct: import { helper } from "./utils/math.osp"

5. Compiling Output Directly to Project Root

• Incorrect: Manually transpiling single files to root app.js.
• Correct: Configure package.json with "outDir": "public" and execute ospc build --public --sourcemap or ospc dev.

---

9. Verification, Fuzzing & Quality Metrics

Oriented-Direct v1.4.0 undergoes rigorous mathematical verification and stress testing:

• Unit Test Suite: 21 / 21 tests passing (npm test).
• CLI Flag Matrix Integration: 13 / 13 scenarios verified across all flag permutations.
• Differential Fuzzing vs. v1.3.0: 13,038 / 13,038 assertions verified with zero regressions across Lexer, Parser AST, Codegen, and sandboxed Node.js VM execution.
• Source Map Coordinate Precision: 10,000 mapping points verified across 100 synthetic modules with 0.0% coordinate drift error.
• Token Density: ~45% to 50% fewer source tokens required compared to equivalent TypeScript / JavaScript codebases.
• Runtime Footprint: Zero runtime framework overhead (~1 KB micro-helper injection).