azoxjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daril Pratomo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# Azox Framework
+
+[![CI](https://github.com/darilpratomo/azox/actions/workflows/ci.yml/badge.svg)](https://github.com/darilpratomo/azox/actions/workflows/ci.yml)
+
+**The Sound of Future Web**
+
+Azox is a web framework built from scratch — no Virtual DOM, no
+third-party CLI dependencies, no borrowed syntax from React, Vue, or
+Next.js. It compiles `.azox` components directly into fine-grained,
+signal-driven DOM updates.
+
+> Status: early development (v0.1.0). APIs are unstable and will
+> change without notice until v1.0.
+
+## Why Azox
+
+Most frameworks solve reactivity with a Virtual DOM (React) or a
+build-time compiler that inlines everything (Svelte). Azox takes a
+third path: **fine-grained signals**. Every dynamic binding in your
+template compiles to its own tiny `effect()` that writes directly to
+the one DOM node it owns. No tree diffing, no wasted re-renders.
+
+```html
+<script>
+  import { signal } from 'azox/reactivity';
+  const count = signal(0);
+</script>
+
+<button on:click={() => count.set(count() + 1)}>
+  Clicks: {count()}
+</button>
+```
+
+## Routing
+
+The file layout is the routing table. A page becomes a directory with
+an `index.html`, so URLs carry no extension and work on any static
+host without rewrite rules.
+
+```
+pages/index.azox            →  /
+pages/about.azox            →  /about
+pages/blog/index.azox       →  /blog
+pages/blog/first-post.azox  →  /blog/first-post
+```
+
+```
+.azox/build/
+├── index.html
+├── page.client.js
+├── azox-runtime.js          one runtime, shared by every page
+├── about/
+│   ├── index.html
+│   └── page.client.js
+└── blog/
+    ├── index.html
+    ├── page.client.js
+    └── first-post/
+        ├── index.html
+        └── page.client.js
+```
+
+Build one page with `azox compile --page=blog/first-post`, or by its
+URL: `azox compile --page=/blog/first-post`.
+
+## Components
+
+A component is a `.azox` file that declares what it accepts and
+renders markup. Import it, then use it as a capitalised tag:
+
+```html
+<!-- components/Card.azox -->
+<script>
+  const { title, body } = props();
+</script>
+
+<article class="card">
+  <h2>{title}</h2>
+  <p>{body}</p>
+</article>
+```
+
+```html
+<!-- pages/index.azox -->
+<script>
+  import Card from '../components/Card.azox';
+  import { signal } from 'azox/reactivity';
+
+  const count = signal(0);
+</script>
+
+<main>
+  <Card title="Live" body={count()} />
+  <button on:click={() => count.set(count() + 1)}>Add one</button>
+</main>
+```
+
+Components are resolved at build time: the markup is inlined into the
+caller, so there is no component instance and no per-component
+overhead at runtime. A prop passed as an expression stays reactive
+across the boundary — clicking the button above updates the text
+inside the card and nothing else. A prop passed as a plain string
+compiles to static text with no effect attached.
+
+`<slot />` renders whatever the caller nested inside the tag:
+
+```html
+<!-- components/Layout.azox -->
+<script>
+  const { heading } = props();
+</script>
+
+<section>
+  <header>{heading}</header>
+  <slot />
+</section>
+```
+
+Declaring props with `props()` is what lets the compiler reject a
+caller that passes something the component never asked for, instead
+of dropping it silently.
+
+In this version components are presentational: they take props and
+render markup, and state lives in the page that uses them. A
+component that declares its own logic is rejected with an explicit
+error rather than quietly sharing the caller's scope.
+
+## Getting Started
+
+The package on npm is `azoxjs`; the CLI it installs is `azox`.
+
+```bash
+npx azoxjs create my-app
+cd my-app
+npm install
+npm run dev
+```
+
+`azox dev` serves the project at `http://localhost:4321`, rebuilds on
+every save, and reloads the browser. When a page fails to compile it
+serves the error instead of stale output, then recovers on its own
+once the page is fixed.
+
+For a production build:
+
+```bash
+npm run build
+```
+
+The build lands in `.azox/build/` as a self-contained static bundle —
+an `index.html` per route, a compiled hydration module beside it, and
+one shared copy of the runtime. No dev machinery is included. Serve
+that directory with any static host and it works with no install
+step and no rewrite configuration.
+
+## CLI
+
+```
+azox create <name>   Scaffold a new Azox project
+azox dev             Serve the project, rebuilding on every change
+azox compile         Build every page (--page=<name|url> for one)
+azox doctor          Check that the toolchain and project are healthy
+azox -v              Print the version
+azox help            Show all commands
+```
+
+`azox dev` takes `--port=<n>` and `--host=<addr>`. If the port is
+busy it steps forward to the next free one rather than failing.
+
+## Project Structure
+
+```
+azox/
+├── bin/azox.js              CLI entry point
+├── core/
+│   ├── cli/                 argument parsing + command routing
+│   ├── commands/             built-in CLI commands
+│   ├── compiler/             .azox parser, component resolver, compiler
+│   ├── dev/                  dev server, file watching, live reload
+│   ├── reactivity/           signal() / effect() / computed()
+│   ├── renderer/             server-side HTML rendering
+│   ├── build.js              the build pipeline, shared by commands
+│   ├── routes.js             file layout → urls and output paths
+│   └── meta.js               version and identity strings
+├── pages/                    example .azox pages
+└── components/               example .azox components
+```
+
+## Tests
+
+```bash
+npm test
+```
+
+The suite runs on Node's built-in test runner — no test framework
+dependency. It covers the reactivity primitives, the parser, the
+compiler's emitted code, HTML escaping in the server renderer, CLI
+argument parsing, and an end-to-end pass that compiles a fixture
+project and executes the output to confirm the page really is
+reactive.
+
+## Design Principles
+
+1. **Zero dependencies at the core.** No Commander, no Yargs, no
+   Virtual DOM library. The CLI and compiler are written in plain
+   JavaScript.
+2. **Fine-grained reactivity, not a Virtual DOM.** Updates target
+   exact DOM nodes, not a re-rendered tree.
+3. **Its own syntax.** `.azox` files are not JSX. They're closer to
+   plain HTML with `{expr}` interpolation and `on:event` bindings.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/azox.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+// Azox CLI entry point. Kept thin on purpose — it just reads argv
+// and delegates to the engine in core/.
+
+import { parseArgs } from '../core/cli/parseArgs.js';
+import { runCommand } from '../core/cli/router.js';
+
+const { command, positionals, flags } = parseArgs(process.argv.slice(2));
+
+try {
+  await runCommand(command, { positionals, flags });
+} catch (error) {
+  // Anything reaching here is a bug rather than user error, so keep
+  // the stack: it's what makes the report actionable.
+  console.error(`Azox: ${error.stack ?? error.message}`);
+  process.exitCode = 1;
+}

package/core/build.js

@@ -0,0 +1,218 @@
+// The build pipeline, independent of any CLI command: parse a page,
+// server-render it, compile the hydration module, and write the
+// result. `azox compile` runs it once; `azox dev` runs it on every
+// change, so it returns data rather than printing.
+
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+
+import { parseAzox } from './compiler/parser.js';
+import { resolveComponents } from './compiler/resolveComponents.js';
+import { compileToModule } from './compiler/compileToJs.js';
+import { renderToHtml } from './renderer/renderToHtml.js';
+import { collectRoutes, findRoute } from './routes.js';
+import { ROOT_DIR } from './meta.js';
+import { BuildError } from './buildError.js';
+
+// Browsers can't resolve bare specifiers like "azox/reactivity", so
+// the runtime is copied into the build and imports are rewritten to
+// point at it. That also makes the output self-contained: any static
+// host can serve it with no install step.
+const RUNTIME_FILENAME = 'azox-runtime.js';
+
+export const PAGES_DIR = 'pages';
+export const BUILD_DIR = '.azox/build';
+
+export { BuildError };
+
+export function listRoutes(projectDir) {
+  return collectRoutes(resolve(projectDir, PAGES_DIR));
+}
+
+// transformHtml lets the dev server inject its live-reload snippet
+// without that ever reaching a production build.
+export function buildRoute(projectDir, route, { transformHtml } = {}) {
+  const { sourcePath, name } = route;
+  const parsed = parseAzox(readFileSync(sourcePath, 'utf8'));
+
+  // Components are inlined here, before either output is produced, so
+  // the compiler and the renderer both see plain markup.
+  const ast = resolveComponents(parsed, sourcePath);
+
+  // SSR pass: render initial markup without touching browser DOM APIs.
+  let html;
+  try {
+    html = renderToHtml(ast, buildServerScope(ast.script));
+  } catch (error) {
+    if (!(error instanceof BuildError)) throw error;
+    throw new BuildError(`in ${PAGES_DIR}/${name}.azox: ${error.message}`);
+  }
+
+  const buildRoot = resolve(projectDir, BUILD_DIR);
+  const outDir = resolve(buildRoot, route.outputDir);
+  mkdirSync(outDir, { recursive: true });
+
+  const clientPath = resolve(outDir, 'page.client.js');
+
+  // Client pass: the same AST becomes a hydration module that wires
+  // signals straight to DOM nodes once it runs in the browser.
+  // The runtime lives at the build root, so a nested page reaches it
+  // through its own prefix ("../", "../../", …).
+  const runtimeSpecifier = `${route.assetPrefix}${RUNTIME_FILENAME}`;
+
+  const clientModule = rewriteRuntimeImports(
+    compileToModule(ast, {
+      sourcePath,
+      outPath: clientPath,
+      runtimeSpecifier,
+    }),
+    runtimeSpecifier
+  );
+
+  assertValidJavaScript(clientModule, name);
+  writeFileSync(clientPath, clientModule, 'utf8');
+
+  // One runtime at the build root, shared by every page.
+  const runtimePath = resolve(buildRoot, RUNTIME_FILENAME);
+  copyFileSync(resolve(ROOT_DIR, 'core/reactivity/signal.js'), runtimePath);
+
+  let document = wrapDocument(html, projectTitle(projectDir));
+  if (transformHtml) document = transformHtml(document);
+
+  const htmlPath = resolve(buildRoot, route.htmlPath);
+  writeFileSync(htmlPath, document, 'utf8');
+
+  return { ...route, htmlPath, clientPath, runtimePath };
+}
+
+export function buildAll(projectDir, options) {
+  const routes = listRoutes(projectDir);
+
+  if (!routes.length) {
+    throw new BuildError(
+      `no .azox pages found in ${PAGES_DIR}/ — run "azox create <name>" to start one`
+    );
+  }
+
+  return routes.map((route) => buildRoute(projectDir, route, options));
+}
+
+// Builds a single page by route name or URL.
+export function buildPage(projectDir, pageName, options) {
+  const route = findRoute(listRoutes(projectDir), pageName);
+
+  if (!route) {
+    throw new BuildError(`page "${PAGES_DIR}/${pageName}.azox" not found in ${projectDir}`);
+  }
+
+  return buildRoute(projectDir, route, options);
+}
+
+// Rewrites the bare specifier a page's own <script> uses to the same
+// path the compiler emitted for the runtime import.
+function rewriteRuntimeImports(code, runtimeSpecifier) {
+  return code.replace(/(['"])azox(?:\/reactivity)?\1/g, `'${runtimeSpecifier}'`);
+}
+
+// A compiler must never write output it knows is broken. Parsing the
+// emitted module catches a malformed expression here, with the page
+// named, instead of leaving the user to find a syntax error in the
+// browser console.
+function assertValidJavaScript(code, pageName) {
+  try {
+    new Function(`return (async () => { ${stripModuleSyntax(code)} })`);
+  } catch (error) {
+    throw new BuildError(
+      `compiling ${PAGES_DIR}/${pageName}.azox produced invalid JavaScript ` +
+        `(${error.message}). This is an Azox bug — please report the page that caused it.`
+    );
+  }
+}
+
+// `new Function` cannot hold import/export statements, so they are
+// removed before the syntax check. What remains is the generated
+// body, which is where a malformed expression would land.
+function stripModuleSyntax(code) {
+  return code
+    .replace(/^\s*import\s[^;]+;?\s*$/gm, '')
+    .replace(/^\s*export\s+(?=function|const|let|class)/gm, '');
+}
+
+// Page title comes from the project's package.json name, falling back
+// to the directory name.
+function projectTitle(projectDir) {
+  const pkgPath = resolve(projectDir, 'package.json');
+
+  if (existsSync(pkgPath)) {
+    try {
+      const { name } = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      if (name) return name;
+    } catch {
+      // A malformed package.json shouldn't block a build.
+    }
+  }
+
+  return basename(projectDir);
+}
+
+// Runs the page's <script> block in a server-side scope so SSR can
+// evaluate the expressions the template references. The script is
+// trusted project source, not user input — the same assumption any
+// template engine's SSR step makes.
+function buildServerScope(script) {
+  // Strip imports: the server supplies its own `signal` stub rather
+  // than loading the real reactive runtime.
+  const body = script.replace(/^\s*import\s.+?;\s*$/gm, '');
+
+  try {
+    const fn = new Function('signal', `${body}\nreturn { ${declaredNames(body).join(', ')} };`);
+    return fn(serverSignal);
+  } catch (error) {
+    throw new BuildError(`failed to evaluate the page's <script> block: ${error.message}`);
+  }
+}
+
+// SSR needs only the current value, not reactivity, so `signal()` on
+// the server is a plain boxed value.
+function serverSignal(initial) {
+  let value = initial;
+  const read = () => value;
+  read.set = (next) => {
+    value = typeof next === 'function' ? next(value) : next;
+  };
+  read.peek = () => value;
+  return read;
+}
+
+function declaredNames(script) {
+  const names = [];
+  const regex = /const\s+(\w+)\s*=/g;
+  let match;
+  while ((match = regex.exec(script))) names.push(match[1]);
+  return names;
+}
+
+// The client module sits next to the page's index.html, so the src is
+// the same for every route regardless of how deep it is.
+function wrapDocument(bodyHtml, title) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(title)}</title>
+</head>
+<body>
+<div data-azox-root>${bodyHtml}</div>
+<script type="module" src="./page.client.js"></script>
+</body>
+</html>
+`;
+}
+
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}

package/core/buildError.js

@@ -0,0 +1,8 @@
+// Lives on its own so both the build pipeline and the compiler can
+// use it without importing each other.
+//
+// A BuildError means the user's project is wrong — a missing page, a
+// bad component reference — and the CLI prints its message plainly.
+// Anything else that escapes is a bug in Azox and keeps its stack.
+
+export class BuildError extends Error {}

package/core/cli/parseArgs.js

@@ -0,0 +1,39 @@
+// Minimal terminal argument parser. No Commander, no Yargs —
+// keeping the CLI dependency-free is part of the point.
+//
+// Usage: azox <command> [--flag] [-f] [--key=value] [positional...]
+//
+// Short flags are single-dash, single-letter (-v). Grouping like -abc
+// is deliberately not supported: it buys little for a framework CLI
+// and makes error messages harder to read.
+//
+// Returns:
+//   { command, positionals, flags }
+
+const isFlag = (arg) => arg.startsWith('-');
+
+export function parseArgs(argv) {
+  const command = argv.length > 0 && !isFlag(argv[0]) ? argv[0] : null;
+  const rest = command ? argv.slice(1) : argv;
+
+  const positionals = [];
+  const flags = {};
+
+  for (const arg of rest) {
+    if (!isFlag(arg)) {
+      positionals.push(arg);
+      continue;
+    }
+
+    const raw = arg.startsWith('--') ? arg.slice(2) : arg.slice(1);
+    const eqIndex = raw.indexOf('=');
+
+    if (eqIndex === -1) {
+      flags[raw] = true; // e.g. --watch, -v
+    } else {
+      flags[raw.slice(0, eqIndex)] = raw.slice(eqIndex + 1); // e.g. --port=3000
+    }
+  }
+
+  return { command, positionals, flags };
+}

package/core/cli/router.js

@@ -0,0 +1,76 @@
+// The command registry is the single source of truth: each entry
+// carries its handler, its one-line description, and example usage.
+// `azox help` renders itself from this, so adding a command here is
+// enough to make it discoverable.
+
+import { doctorCommand } from '../commands/doctor.js';
+import { compileCommand } from '../commands/compile.js';
+import { devCommand } from '../commands/dev.js';
+import { versionCommand } from '../commands/version.js';
+import { createCommand } from '../commands/create.js';
+import { helpCommand } from '../commands/help.js';
+
+export const registry = {
+  create: {
+    run: createCommand,
+    describe: 'Scaffold a new Azox project',
+    examples: ['azox create my-app'],
+  },
+  dev: {
+    run: devCommand,
+    describe: 'Serve the project and rebuild on every change',
+    examples: ['azox dev', 'azox dev --port=5000'],
+  },
+  compile: {
+    run: compileCommand,
+    describe: 'Compile pages to HTML + hydration modules',
+    examples: ['azox compile', 'azox compile --page=about'],
+  },
+  doctor: {
+    run: doctorCommand,
+    describe: 'Check that the toolchain and project are healthy',
+    examples: ['azox doctor'],
+  },
+  version: {
+    run: versionCommand,
+    describe: 'Print the Azox version',
+    examples: ['azox -v'],
+  },
+  help: {
+    run: helpCommand,
+    describe: 'Show this help',
+    examples: ['azox help'],
+  },
+};
+
+// Flags that stand in for a command, so `azox -v` works like
+// `azox version` without making every command parse them.
+const FLAG_ALIASES = {
+  v: 'version',
+  version: 'version',
+  h: 'help',
+  help: 'help',
+};
+
+// Returns whatever the handler returns, so an async command (dev)
+// can be awaited by the entry point.
+export function runCommand(command, context) {
+  const resolved = command ?? aliasFor(context.flags) ?? 'help';
+  const entry = registry[resolved];
+
+  if (!entry) {
+    console.error(`Azox: unknown command "${resolved}".`);
+    console.error(`Run "azox help" to see available commands.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  return entry.run({ ...context, registry });
+}
+
+function aliasFor(flags) {
+  for (const [flag, command] of Object.entries(FLAG_ALIASES)) {
+    if (flags[flag]) return command;
+  }
+  return null;
+}

package/core/commands/compile.js

@@ -0,0 +1,35 @@
+// `azox compile` — builds pages into static HTML plus hydration
+// modules.
+//
+//   azox compile                 build every page in pages/
+//   azox compile --page=about    build one page
+
+import { relative } from 'node:path';
+
+import { buildAll, buildPage, BuildError, BUILD_DIR } from '../build.js';
+import { BANNER } from '../meta.js';
+
+export function compileCommand({ flags }) {
+  // Rooted at the user's project, not the framework checkout, so
+  // `azox compile` inside a scaffolded app builds that app.
+  const projectDir = process.cwd();
+
+  try {
+    const results = flags.page ? [buildPage(projectDir, flags.page)] : buildAll(projectDir);
+
+    console.log(BANNER);
+    console.log('');
+    console.log(`Built ${results.length} page${results.length === 1 ? '' : 's'} to ${BUILD_DIR}/`);
+    console.log('');
+
+    const width = Math.max(...results.map((result) => result.url.length));
+    for (const result of results) {
+      console.log(`  ${result.url.padEnd(width)}  ${relative(projectDir, result.htmlPath)}`);
+    }
+  } catch (error) {
+    if (!(error instanceof BuildError)) throw error;
+
+    console.error(`Azox: ${error.message}`);
+    process.exitCode = 1;
+  }
+}