Complete Documentation (Docs & README.md)·Copyright © 2026 Peter Joram · Tanzania

Complete PXL Language Guide

Read and copy interactive tutorials alongside all 32 repository files including README.md, Core Specs, and the Web/UI Library directly on this site.

Site BuilderPlayground →
README.md

Official PXL repository documentation — copy any code block or the full Markdown file below.

PXL Programming Language (Peter eXtended Programming Language)

Founder & Creator: Peter Joram Country: Tanzania Official Slogan: Beyond Code. Beyond Limits. Contact: peterjoram897@gmail.com | +255677780801


Overview

PXL (Peter eXtended Programming Language) is a statically typed, sandbox-capable, multi-paradigm programming language engineered with a complete compiler and runtime pipeline:

  • Compiler Pipeline: Hand-written Lexer (src/pxl/core/lexer.ts), Recursive-Descent + Pratt Parser (src/pxl/core/parser.ts), typed AST (src/pxl/core/ast.ts), Semantic Analyzer & Static Type Checker (src/pxl/core/semantic.ts), Intermediate Representation (src/pxl/core/ir.ts) with disassembler, and AST/IR execution engine (src/pxl/core/vm.ts).
  • Managed Memory: Scoped lexical lifetimes + reference tracking + garbage collection sweep + hard heap quotas (src/pxl/core/memory.ts).
  • Security Sandbox: Zero eval / new Function in the core VM, default-deny host permissions (--allow-fs, --allow-fs-write, --allow-net, --allow-env, --allow-process), path traversal containment, infinite-loop maxSteps protection, call-depth cap, and Node node:crypto cryptographic primitives (SHA-256, SHA-512, HMAC-SHA256, AES-256-GCM, randomUUID).
  • Developer Tooling: Full CLI (bin/pxl.js), Package Manager with SHA-256 lockfile verification (src/pxl/pkg/manager.ts), Code Formatter (pxl fmt), Linter (pxl lint), Debugger (pxl run --debug), REPL (pxl repl), Language Server (pxl lsp), VS Code TextMate grammar (editors/vscode/), and Next.js Web Docs + Interactive Playground (/playground).

Quick Start

bash
# 1. Install dependencies & compile the PXL engine
npm install
npm run build:pxl

# 2. Check PXL CLI version & help
node bin/pxl.js --version
node bin/pxl.js --help

# 3. Type-check & run an example program
node bin/pxl.js check examples/hello.pxl
node bin/pxl.js run examples/hello.pxl
node bin/pxl.js run examples/oop_structs_enums.pxl

# 4. Run full automated test suite (Node unit/security tests + native .test.pxl suite)
npm test

# 5. Start the web documentation & interactive Playground (port 3000)
npm run dev

Example PXL Program

pxl
const CREATOR: string = "Peter Joram";

enum Role { Guest = 0, Developer = 1, Founder = 2 }

interface Describable {
  fn describe() -> string;
}

class Engineer implements Describable {
  flux name: string = "";
  flux role: Role = Role.Developer;

  fn init(name: string, role: Role) {
    this.name = name;
    this.role = role;
  }

  fn describe() -> string {
    return "${this.name} (${this.role}) — Beyond Code. Beyond Limits.";
  }
}

flux peter = new Engineer(CREATOR, Role.Founder);
println(peter.describe());

Documentation Index

DocumentDescription
Linux, macOS, and Windows setup and verification instructions
Step-by-step tutorial from Hello World to packages
Lexical grammar, types, scoping, OOP, and async semantics
Concise cheat sheet of every PXL keyword and construct
Built-in modules: core, math, json, csv, time, str, arr, url, fs, http, sys, crypto
Complete CLI subcommands and permission flags
Lexer -> Parser -> Semantic/Type -> IR pipeline details
VM interpreter, scopes, closures, and memory management model
Threat model, sandbox guarantees, cryptography policy, and honest limitations
Contribution workflow, testing, and coding standards
Release history
Engineering roadmap
Frequently asked questions
MIT License

Web Development & UI Component Library (/docs/*.md)

GuideTopics Covered
AI-friendly PXL syntax, compiler pipeline, and safe component patterns
Prompt engineering templates for generating valid PXL sites
web.page, web.layout, web.app dynamic routing, sessions, HTML export
Full-page sections, cards, tables, modals, tabs, charts, and widgets
All 23 accessible button variants (WhatsApp, Call, Copy, Share, Payment, Download)
All 13 responsive header variants with mobile drawers & dropdowns
All 9 footer variants with multi-column links, newsletter & dynamic year
All 12 ARIA menu & sidebar navigation variants
All 14 loaders, skeletons, upload/download progress bars
All 15 form types + server-side forms.validate, CSRF & anti-spam checks
Motion transitions and prefers-reduced-motion support
12 curated design themes, dark/light toggling, CSS custom properties
Mobile-first breakpoints, .pxl-grid, viewport overflow guard
XSS escaping, URL allowlisting, CSP headers, upload validation
Complete runnable demos & all 8 starter templates (pxl templates)
Exact API signatures for ui, web, theme/design, forms, security
Master component index across all 30+ sections & helpers

Using PXL Inside Websites (<?pxl ... ?> + .pxl + HTML)

PXL is a complete, drop-in, higher-security alternative to PHP for building full-stack websites. You can run PXL directly on a server, embed .pxl files inside .html, or protect logic using PXL Vault V2 (pxl_vault).

1. Mixed <?pxl ... ?> + HTML (PHP Replacement)

Write server logic at the top with <?pxl ... ?>, mix <?pxl= $expr ?> (auto XSS-escaped via htmlspecialchars), loops, and conditionals directly with clean HTML/CSS below:

html
<?pxl
session_start();
$site_name = "Duka la Teknolojia PXL";
$csrf = csrf_token();

mysql.connect();
mysql.schema("products", [
  { id: 1, title: "PXL Pro Cloud", price: 95000, status: "Tayari" },
  { id: 2, title: "Vault V2 Shield", price: 150000, status: "Maarufu" }
]);

$stmt = mysql.prepare("SELECT id, title, price, status FROM products WHERE id >= ?");
$stmt.execute([1]);
$products = $stmt.fetchAll();
?>
<!doctype html>
<html lang="sw">
  <body style="background:#05050a;color:#f8fafc;font-family:system-ui,sans-serif;padding:24px">
    <h1><?pxl= $site_name ?></h1>
    <p>Tarehe: <?pxl= date("Y-m-d") ?></p>
    <?pxl for ($p in $products) { ?>
      <div style="border:1px solid #312e81;padding:14px;margin-top:10px;border-radius:12px">
        <strong><?pxl= $p.title ?></strong> — TZS <?pxl= $p.price ?> (<?pxl= $p.status ?>)
      </div>
    <?pxl } ?>
  </body>
</html>

Supported PHP-compatible globals & helpers built into <?pxl ... ?>:

  • Superglobals: $_GET, $_POST, $_REQUEST, $_SERVER, $_SESSION, $_COOKIE, $_FILES, $_ENV (auto $var assignment supported alongside flux).
  • Sessions, Cookies & Headers: session_start(), session_set(), session_get(), session_has(), session_destroy(), setcookie(), header(), http_response_code(), redirect().
  • Security: csrf_token(), csrf_verify(), password_hash() (node:crypto scryptSync), password_verify() (timingSafeEqual), htmlspecialchars(), urlencode(), urldecode().
  • Utilities: isset(), empty(), count(), explode(), implode(), trim(), strtolower(), strtoupper(), str_replace(), substr(), strpos(), json_encode(), json_decode(), date(), time_unix().

2. Running index.pxl Directly Inside .html (via CDN Script or Local Runtime)

Any .html page can load and execute .pxl files (index.pxl) or inline <script type="text/pxl"> scripts cleanly—without exposing raw source code—using either official runtime link (ptaditech.xyz or pxl-programming-language-wrii.vercel.app):

html
<!doctype html>
<html lang="sw">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>PXL Web App — Copyright (c) Peter Joram</title>
  </head>
  <body>
    <pxl-app src="index.pxl"></pxl-app>
    <!-- Official Script Links (both indexed in sitemap.xml): -->
    <script src="https://ptaditech.xyz/pxl-runtime.js"></script>
    <!-- Or: <script src="https://pxl-programming-language-wrii.vercel.app/pxl-runtime.js"></script> -->
  </body>
</html>

Stealth MySQL Database & Complete .env Setup Guide

PXL communicates with MySQL through a Stealth Bridge designed so external users and attackers cannot see table names, SQL statements, hostnames, or even confirm a SQL database is in use:

  • All credentials live strictly server-side in .env (never in HTML, .pxl frontend bundles, or client JS).
  • Queries enforce Prepared Statements (mysql.prepare("SELECT ... WHERE id = ?") / pdo.prepare(...)) preventing SQL Injection 100%.
  • All SQL or driver errors are masked behind opaque reference IDs (Ref: PXL-DB-xxxxxx).
  • Browser-to-server execution goes through the opaque Vault-V2-sealed endpoint /api/pxl/x (with X-Content-Type-Options: nosniff, Cache-Control: no-store, strict CSP, and X-Powered-By removed).
  • Use mysql.stealthBind(action, sql) + mysql.stealthCall(token, params) to hide every query behind a PXL Vault V2 token.

Complete .env Variables Reference

Create a .env file in your project root (or set these in your hosting dashboard's Environment Variables):

VariableRequired?DefaultAccepted Values & Explanation
MYSQL_HOSTYes (unless DATABASE_URL)127.0.0.1Hostname or IP of your MySQL server (e.g., 127.0.0.1, localhost, mysql.railway.internal, aws.connect.psdb.cloud).
MYSQL_PORTNo3306TCP port of MySQL server (usually 3306, or cloud-assigned port like 25060 / 4000).
MYSQL_USERYes (unless DATABASE_URL)rootDatabase username (e.g., root locally, or dedicated least-privilege user pxl_app_user in production).
MYSQL_PASSWORDProduction: Yes(empty)Database password. Leave empty only if local XAMPP/Laragon root has no password.
MYSQL_DATABASEYes (unless DATABASE_URL)pxl_appTarget MySQL schema/database name (must already exist on the MySQL server).
MYSQL_SSLRecommendedfalseTLS/SSL encryption mode for MySQL connections. See exact values below!
MYSQL_SSL_CAOptional(empty)Optional PEM root certificate string (use \n for line breaks) when using MYSQL_SSL=strict with custom CAs (Aiven / DigitalOcean / Cloud SQL).
DATABASE_URLOptional override(empty)Single-line MySQL URI: mysql://USER:PASS@HOST:PORT/DATABASE. When set, overrides MYSQL_HOST/PORT/USER/PASSWORD/DATABASE.
PXL_DB_STEALTH_KEYRecommendedpeter-joramServer-only secret shield key used to seal/unseal Vault V2 stealth tokens and /api/pxl/x RPC payloads. Change to a long random string in production.

What to Fill in MYSQL_SSL (Every Environment)

SettingAccepted ValuesWhen to UseHow PXL Configures mysql2
`MYSQL_SSL=false`false, 0, off, no, disableLocalhost / Development — XAMPP, WAMP, Laragon, MAMP, local MySQL (127.0.0.1), Docker containers without TLS.Disables SSL (ssl: undefined).
`MYSQL_SSL=true`true, 1, on, yes, require, requiredManaged Cloud MySQL — Railway, Aiven, DigitalOcean, Render, Hostinger, cPanel remote MySQL where TLS encryption is required without verifying custom CA bundles.Enables encrypted TLS (ssl: { rejectUnauthorized: false }, or attaches ca if MYSQL_SSL_CA is set).
`MYSQL_SSL=strict`strict, verify, verify-ca, verify-fullEnterprise / Strict Cloud TLS — PlanetScale, TiDB Cloud Serverless, AWS RDS, Google Cloud SQL, Azure Database for MySQL.Enforces full TLS certificate chain verification (ssl: { rejectUnauthorized: true }, plus optional MYSQL_SSL_CA).

Ready-to-Use .env Templates by Environment

A. Localhost (XAMPP / WAMP / Laragon / Local MySQL)

dotenv
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=
MYSQL_DATABASE=pxl_app
MYSQL_SSL=false
PXL_DB_STEALTH_KEY=peter-joram

B. Docker Compose / Internal Network

dotenv
MYSQL_HOST=mysql-service
MYSQL_PORT=3306
MYSQL_USER=pxl_worker
MYSQL_PASSWORD=strong_internal_password
MYSQL_DATABASE=pxl_prod
MYSQL_SSL=false
PXL_DB_STEALTH_KEY=change-this-to-a-32-char-random-secret

C. Cloud Hosting (Railway, Aiven, DigitalOcean, Render, cPanel/Hostinger)

dotenv
MYSQL_HOST=containers-us-west.railway.app
MYSQL_PORT=6543
MYSQL_USER=pxl_cloud_user
MYSQL_PASSWORD=your_strong_cloud_password
MYSQL_DATABASE=railway
MYSQL_SSL=true
# Optional if provider gives a CA certificate:
# MYSQL_SSL_CA="-----BEGIN CERTIFICATE-----\nMII...\n-----END CERTIFICATE-----"
PXL_DB_STEALTH_KEY=your-unique-production-stealth-key

D. Strict Verified TLS Cloud (PlanetScale, TiDB Cloud, AWS RDS, Google Cloud SQL)

dotenv
MYSQL_HOST=aws.connect.psdb.cloud
MYSQL_PORT=3306
MYSQL_USER=your_pscale_user
MYSQL_PASSWORD=pscale_pw_xxxxxxxxxxxx
MYSQL_DATABASE=pxl_production
MYSQL_SSL=strict
# Or use single URL mode:
# DATABASE_URL=mysql://your_pscale_user:pscale_pw_xxxxxxxxxxxx@aws.connect.psdb.cloud:3306/pxl_production
PXL_DB_STEALTH_KEY=your-unique-production-stealth-key

Connecting Every Layer in Production (Step-by-Step Checklist)

  1. Server-Side Database (`mysql` / `pdo` / `pxl_db`)
  • Always configure .env (never commit .env to Git; use .env.example as your template).
  • Call mysql.connect() or pdo.connect(), define initial schema (mysql.schema(...)), and use mysql.prepare(...) or mysql.stealthBind(...) + mysql.stealthCall(...).
  • Note: Without .env credentials (or inside the browser Playground sandbox), PXL automatically falls back to its parameterized In-Memory Stealth SQL Engine so your pages never crash during development or previews.
  1. Client-to-Server Stealth RPC (`/api/pxl/s` & `/api/pxl/x`)
  • pxl-runtime.js communicates secretly with the server-side companion file /pages/api/pxl/s.ts (backed by /src/pxl/web/stealthCompanion.ts) using PXL Vault V2 encrypted envelopes, per-request nonces, and HMAC-SHA256 signed ephemeral session tickets (PXLRuntime.secretHandshake() / PXLRuntime.runSecureRemote()). Sensitive .env credentials (MYSQL_*, PXL_COMPANION_SECRET, PXL_DB_STEALTH_KEY) never appear inside pxl-runtime.js or browser responses.
  1. Media, Maps, Camera & Wi-Fi Components
  • Use native PXL components (ui.image, ui.videoPlayer / render_video_player, ui.googleMap / render_google_map, ui.camera / render_camera, ui.wifiFinder / render_wifi_finder) with automatic XSS/protocol sanitization and strict CSP allowlisting.
  1. CLI Execution with Host Permissions
  • When running .pxl scripts with live network/env access from the CLI:
bash
     node bin/pxl.js run index.pxl --allow-env --allow-net
  1. Build, Verification & Google Image SEO Deployment
  • Verify TypeScript compiler + Next.js production build + ESLint + full test suite:
bash
     npm run generate:sitemap
     npm run build
     npm run lint
     npm test
     npm start
  • public/sitemap.xml and public/robots.txt index both official domains (https://pxl-programming-language-wrii.vercel.app and https://ptaditech.xyz), both pxl-runtime.js script URLs, and Google <image:image> metadata for the official PXL logo.
  • Copyright © 2026 Peter Joram · Tanzania · Beyond Code. Beyond Limits.
Want to test this code live or scaffold an index.pxl website?