sommark 4.5.3 → 5.0.1

package/README.md

@@ -5,283 +5,420 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/sommark.svg)](https://github.com/Adam-Elmi/SomMark/blob/master/LICENSE)
 
-SomMark is a high-performance markup language designed for structured content. It acts as an extensible source language that can be transformed into multiple formats like HTML, JSON, MDX, XML, and Markdown.
+**SomMark** is a template language that compiles to multiple output formats — HTML, JSON, YAML, TOML, CSV, Markdown, XML, and more.
 
-SomMark uses explicit structural boundaries to ensure your document remains stable and predictable. It enables infinite nesting and provides total control over your contents.
+Write your content once with a single consistent block syntax. Add loops, compile-time logic, and file imports. Compile to whatever format your project needs.
 
-> **v4.2.0 — Browser Support**: SomMark now compiles templates directly in the browser with no Node.js dependencies. Use the `sommark/browser` entry point with any bundler (Vite, Webpack, Rollup, esbuild). See [Browser API docs](docs/api/Browser/) for `resolveBaseDir` and `renderCompiledHTML`.
+> **v5 is the official stable release and the recommended version to start with.**
+> SomMark has reached its main goal — a single consistent block syntax that compiles to any output format. v5 is the last major version. Future releases will be minor updates or patches.
 
 ---
 
 ## Install
 
-#### 1. Global (Command Line)
-Install SomMark globally to use the `sommark` command.
 ```bash
+# CLI
 npm install -g sommark
+
+# Use it with your project
+npm install sommark
 ```
 
-To verify it is working, check the version:
-```bash
-sommark --version
+---
+
+## Showcase
+
+**`team.smark`** (HTML mapper)
+
+```ini
+[import = Card: "./components/Card.smark" !]
+
+${
+  const team = [
+    { name: "Adam",  role: "Founder",  avatar: "adam.jpg"  },
+    { name: "Hawa",  role: "Engineer", avatar: "hawa.jpg"  },
+    { name: "Ilham", role: "Designer", avatar: "ilham.jpg" },
+  ];
+  const year = new Date().getFullYear();
+}$
+
+[main = class: "team-page"]
+  [h1]Our Team[end:h1]
+
+  [section = class: "grid"]
+    [for-each = ${ team }$, as: "member"]
+      [Card = name: ${ member.name }$, role: ${ member.role }$]
+        [img = src: ${ member.avatar }$, alt: ${ member.name }$ !]
+      [end:Card]
+    [end:for-each]
+  [end:section]
+
+  [footer]© ${ year }$ SomMark[end:footer]
+[end:main]
+```
+
+**`components/Card.smark`**
+
+```ini
+[div = class: "card"]
+  [h2]v{name}[end:h2]
+  [p]v{role}[end:p]
+  [slot!]
+[end:div]
 ```
 
-#### 2. Local (Project API)
-Add SomMark to your project as a dependency:
 ```bash
-npm install sommark
+sommark --html team.smark
+```
+
+```html
+<main class="team-page">
+  <h1>Our Team</h1>
+  <section class="grid">
+    <div class="card">
+      <h2>Adam</h2>
+      <p>Founder</p>
+      <img src="adam.jpg" alt="Adam">
+    </div>
+    <div class="card">
+      <h2>Hawa</h2>
+      <p>Engineer</p>
+      <img src="hawa.jpg" alt="Hawa">
+    </div>
+    <div class="card">
+      <h2>Ilham</h2>
+      <p>Designer</p>
+      <img src="ilham.jpg" alt="Ilham">
+    </div>
+  </section>
+  <footer>© 2026 SomMark</footer>
+</main>
 ```
 
 ---
 
+## Output formats
+
+| Format   | CLI Flag       |
+| -------- | -------------- |
+| HTML     | `--html`       |
+| Markdown | `--markdown`   |
+| MDX      | `--mdx`        |
+| JSON     | `--json`       |
+| JSONC    | `--jsonc`      |
+| YAML     | `--yaml`       |
+| TOML     | `--toml`       |
+| CSV      | `--csv`        |
+| XML      | `--xml`        |
+| Text     | `--text`       |
+
+---
+
 ## Features
 
 ### Blocks
 
-Blocks are the primary containers in SomMark, used to group, style, and organize structural content. A block starts with `[identifier]` and closes with a matching `[end]` or self-closing `!` if the block does not have any content, for example `[br!]` or `[img = src: "logo.png" !]`. 
+Every tag is a block. Open with `[name]`, close with `[end:name]`. A plain `[end]` also works, but `[end:name]` is recommended for readability.
 
 ```ini
-[div = class: "container"]
-  [h1]Welcome to SomMark[end]
-  [p]Structured content, zero guesswork.[end]
-  [hr = class: "divider" !]
-[end]
+[article = class: "post"]
+  [h1]Hello, SomMark[end:h1]
+  [p]Structured content, zero guesswork.[end:p]
+  [hr!]
+[end:article]
 ```
-[Read more about blocks](./docs/syntax/block.md)
-
-### Self-Closing Blocks
 
-Blocks that carry no body content close instantly with `!`.
+Self-closing blocks carry no body — append `!` inside the tag:
 
 ```ini
 [br!]
-[hr = class: "divider" !]
-[img = src: "logo.png", alt: "SomMark Logo" !]
+[img = src: "logo.png", alt: "Logo" !]
+[input = type: "text", name: "email" !]
 ```
-[Read more about self-closing blocks](./docs/syntax/self-closing.md)
 
-### Inline Elements
+### Compile-time JavaScript
 
-Apply styling or formatting to specific spans of text within a block using `(inline text)->(identifier = args)` or `(inline text)->(identifier: args)`. Internal newlines and duplicate spaces are automatically collapsed into a single space.
+`${ }$` runs JavaScript at build time inside a sandboxed QuickJS VM. The `static` keyword is optional — `${ expr }$` and `static ${ expr }$` are identical.
+
+The example below targets the **HTML mapper**:
 
 ```ini
-[p]
-  This is (important text)->(bold).
-  Visit the (SomMark Website)->(link = "https://sommark.org", target: "_blank").
-[end]
+${
+  import pkg from "./package.json";
+  const built = new Date().toISOString();
+}$
+
+[footer]
+  ${ pkg.name }$ v${ pkg.version }$ — built ${ built }$
+[end:footer]
 ```
-[Read more about inline elements](./docs/syntax/inline.md)
 
-### Props (Properties)
+Variables declared in one `${ }$` block are available in all blocks that follow in the same file.
 
-Pass metadata (called **Props**, similar to component properties in React/Vue) to Blocks, Inline Elements, and At-Blocks. SomMark supports positional, named, and mixed props with multiple value types (JS data, placeholders, and variables).
+### Loops
 
-> [!NOTE]
-> In the current major version, SomMark passes these properties under the **`args`** key to custom JavaScript `render` functions for backward compatibility. This will be renamed to `props` in the next major version.
+`[for-each]` iterates over any array. The current item is accessed via the `as:` alias. `${ i }$` gives the zero-based index.
 
-* **Blocks**: Passed after `=` (e.g., `[div = "container"][end]`).
-* **Inline Elements**: Passed after `=` or `:` inside the identifier parenthesis (e.g., `(text)->(link = "url")`).
-* **At-Blocks**: Passed after `:` and terminated with `;` (e.g., `@_code: lang: "js";`).
+The example below targets the **HTML mapper**:
 
-**Blocks** — props come after `=`, separated by commas. Positional args have no key; named args use `key: value`.
 ```ini
-[div = "container", class: "flex"][end]
-#      ↑ positional   ↑ named
+${
+  const links = ["Home", "Docs", "Blog", "Contact"];
+}$
+
+[nav]
+  [ul]
+    [for-each = ${ links }$, as: "link"]
+      [li][a = href: "#"]${ link }$[end:a][end:li]
+    [end:for-each]
+  [end:ul]
+[end:nav]
 ```
 
-**Inline Elements** — same prop syntax, after `=` or `:` inside the identifier.
-```ini
-(Visit Website)->(link = "https://sommark.org", target: "_blank")
-#                       ↑ positional url         ↑ named prop
+```html
+<nav>
+  <ul>
+    <li><a href="#">Home</a></li>
+    <li><a href="#">Docs</a></li>
+    <li><a href="#">Blog</a></li>
+    <li><a href="#">Contact</a></li>
+  </ul>
+</nav>
 ```
 
-**At-Blocks** — props follow `:` on the opening line and are terminated with `;`. The body is captured as raw text.
-```ini
-@_code: lang: "js", active: js{true}, user: v{userId};
-#               ↑ string   ↑ native JS value  ↑ local variable
-  console.log("Hello World");
-@_end_@
-```
+### Shorthand key-value for data formats
+
+When targeting JSON, YAML, or TOML, write key-value pairs using the tag name as the key. Type is inferred automatically — numbers stay numbers, `true`/`false` become booleans, everything else becomes a string.
+
+The example below targets the **JSON mapper**:
 
-**Static logic as a prop value** — any prop value can be a compile-time expression.
 ```ini
-[Date = year: static ${ new Date().getFullYear() }$][end]
+[Object]
+  [username = "Adam" !]
+  [age = 25 !]
+  [score = 9.8 !]
+  [isAdmin = false !]
+  [deletedAt = null !]
+[end:Object]
 ```
 
-### At-Blocks -- Raw Content
+```json
+{
+  "username": "Adam",
+  "age": 25,
+  "score": 9.8,
+  "isAdmin": false,
+  "deletedAt": null
+}
+```
 
-At-blocks capture raw text. Brackets, tags, and comments inside them are treated as literal characters and never parsed.
+Body form also works — useful for longer values:
 
 ```ini
-@_code_@: lang: "javascript";
-  const items = [1, 2, 3];
-  // This [div] won't be parsed
-@_end_@
+[Object]
+  [bio]Software developer based in Hargeisa.[end:bio]
+[end:Object]
 ```
 
-### Comments
-
-Single-line and multi-line. Completely removed from the compiled output.
+Generate config from data with a loop. The example below targets the **YAML mapper**:
 
 ```ini
-# This is a single-line comment
+${
+  const services = [
+    { name: "api",    port: 8080, replicas: 3 },
+    { name: "worker", port: 8081, replicas: 2 },
+  ];
+}$
+
+[seq = "services"]
+  [for-each = ${ services }$, as: "s"]
+    [map-item]
+      [name = ${ s.name }$ !]
+      [port = ${ s.port }$ !]
+      [replicas = ${ s.replicas }$ !]
+    [end:map-item]
+  [end:for-each]
+[end:seq]
+```
 
-###
-  This is a multi-line comment.
-  Nothing here reaches the output.
-###
+```yaml
+services:
+  - name: "api"
+    port: 8080
+    replicas: 3
+  - name: "worker"
+    port: 8081
+    replicas: 2
 ```
 
-### Static Logic -- Compile-Time JavaScript
+### Placeholders
+
+Inject values at build time from your JavaScript config using `p{}`. Add a fallback with `|` in case a value is not set.
 
-Run JavaScript during compilation inside a sandboxed QuickJS VM. The result replaces the block inline.
+The example below targets the **HTML mapper**:
 
 ```ini
-[footer]
-  Copyright static ${ new Date().getFullYear() }$
-[end]
-```
+[div = class: "env-badge"]
+  Environment: p{NODE_ENV}
+[end:div]
 
-Use it in props too:
+[footer]Built with p{engine | "SomMark"}[end:footer]
+```
 
-```ini
-[Date = year: static ${ new Date().getFullYear() }$][end]
+```js
+new SomMark({
+  src,
+  format: "html",
+  placeholders: { NODE_ENV: "production" }
+});
 ```
 
-### Runtime Logic -- Client-Side JavaScript
+### Module system
+
+Split templates into reusable `.smark` files. All `[import]` declarations must appear at the top of the file.
 
-Preserve JavaScript in the compiled output. It runs in the browser, not during compilation.
+**Static injection** — insert a module with no props or body content:
 
 ```ini
-[button]
-  runtime ${
-    self.addEventListener("click", () => alert("Hello from SomMark"))
-  }$
-  Click Me
-[end]
+[import = Nav: "./components/Nav.smark" !]
+[import = Footer: "./components/Footer.smark" !]
+
+[body]
+  [$use-module = Nav !]
+  [main]
+    [p]Page content.[end:p]
+  [end:main]
+  [$use-module = Footer !]
+[end:body]
 ```
 
-### For-Each Loop
-
-Iterate over arrays and render blocks for each item. Access the current item and its index.
+**Component block** — pass props and body content. Inside the component, `v{}` reads the props and `[slot]` marks where the body goes:
 
 ```ini
-[for-each = static ${ [{name: "Adam"}, {name: "Hawa"}, {name: "Ilham"}] }$, as: "user"]
-  [li]static ${ user.name }$ -- position static ${ user_index }$[end]
-[end]
-```
+[import = Card: "./components/Card.smark" !]
 
-### Modules and Components
+[Card = title: "Featured Post"]
+  This content fills the slot inside the card.
+[end:Card]
+```
 
-Split your project into reusable `.smark` files. Import them, pass props, and inject body content through slots.
+`Card.smark`:
 
-**`components/Card.smark`**
 ```ini
 [div = class: "card"]
-  [h2]v{title}[end]
-  [div = class: "card-body"]
-    [slot][end]
-  [end]
-[end]
+  [h2]v{title}[end:h2]
+  [div = class: "body"]
+    [slot!]
+  [end:div]
+[end:div]
 ```
 
-**`page.smark`**
-```ini
-[import = Card: "./components/Card.smark"][end]
-
-[Card = title: "Featured Product"]
-  This content fills the slot inside the card.
-[end]
-```
+### Comments
 
-You can also inject a module without passing body content:
+Completely removed at build time — never appear in the output:
 
 ```ini
-[import = Card: "./components/Card.smark"][end]
-[$use-module = Card][end]
+# single-line comment
+
+###
+  multi-line comment
+  write as much as you need
+###
 ```
 
 ---
 
-## Output Formats
+## CLI
 
-Write once, compile to any of these:
+### Global
 
-| Format   | CLI Flag     | Extension |
-|----------|--------------|-----------|
-| HTML     | `--html`     | `.html`   |
-| Markdown | `--markdown` | `.md`     |
-| MDX      | `--mdx`      | `.mdx`    |
-| JSON     | `--json`     | `.json`   |
-| JSONC    | `--jsonc`    | `.jsonc`  |
-| XML      | `--xml`      | `.xml`    |
-| Text     | `--text`     | `.txt`    |
+```bash
+sommark -h, --help                        # show help message
+sommark -v, --version                     # show version
+sommark init                              # generate smark.config.js
+sommark show config [file]                # show resolved config
+sommark show --path-config [file]         # show path to active config file
+sommark color on|off                      # help on enabling terminal colors
+```
 
----
+### Transpile
 
-## CLI
+```bash
+sommark --html input.smark                # compile to HTML
+sommark --markdown input.smark            # compile to Markdown
+sommark --mdx input.smark                 # compile to MDX
+sommark --xml input.smark                 # compile to XML
+sommark --json input.smark                # compile to JSON
+sommark --jsonc input.smark               # compile to JSONC
+sommark --toml input.smark                # compile to TOML
+sommark --yaml input.smark                # compile to YAML
+sommark --csv input.smark                 # compile to CSV
+sommark --text input.smark                # compile to plain text
+sommark --lex input.smark                 # print lexer token stream
+sommark --parse input.smark               # print parser AST
+```
+
+### Output
 
+```bash
+sommark --html -p input.smark             # print output to console
+sommark --html input.smark -o name ./dir/ # set output filename and directory
 ```
-sommark init                           Create a smark.config.js file
-sommark --html <file>                  Compile to HTML
-sommark --markdown <file>              Compile to Markdown
-sommark --html <file> -o <name> <dir>  Set output filename and directory
-sommark --html --print <file>          Print compiled output to terminal
-sommark --lex <file>                   Show the token stream
-sommark --parse <file>                 Show the syntax tree
-sommark show config [file]             Show the resolved configuration
-sommark -v                             Show version
-sommark -h                             Show help
+
+### Browser bundle
+
+```bash
+sommark bundle ./dist/                    # copy full bundle (JS + WASM)
+sommark bundle ./dist/ --lite             # lite bundle — no WASM
+sommark bundle ./dist/ --only-lexer       # lexer only
+sommark bundle ./dist/ --only-parser      # lexer + parser only
 ```
 
 ---
 
-## Programmatic Usage
+## Programmatic API
 
 **Node.js**
 ```js
 import SomMark from "sommark";
 
-const engine = new SomMark({
-  src: '[h1]Hello World[end]',
+const sm = new SomMark({
+  src,
   format: "html",
+  placeholders: { title: "My App" }
 });
 
-const output = await engine.transpile();
-// <h1>Hello World</h1>
+const output = await sm.transpile();
 ```
 
-**Browser** (v4.2.0+)
+**Browser**
 ```js
 import SomMark, { resolveBaseDir, renderCompiledHTML } from "sommark/browser";
 
 const src = await fetch("./main.smark").then(r => r.text());
 
-const engine = new SomMark({
+const sm = new SomMark({
   src,
   format: "html",
-  baseDir: resolveBaseDir("./templates/"), // resolves imports via fetch
+  baseDir: resolveBaseDir("./templates/"),
 });
 
-renderCompiledHTML(document.getElementById("output"), await engine.transpile());
+renderCompiledHTML(document.getElementById("app"), await sm.transpile());
 ```
 
 ---
 
 ## Configuration
 
-Run `sommark init` to generate a `smark.config.js` with all available settings:
+Run `sommark init` to generate `smark.config.js`:
 
 ```js
 export default {
   format: "html",
   removeComments: true,
-  generateRuntimeOutput: false,
-  hideRuntimeOutput: false,
-  customProps: [],
   placeholders: {},
   importAliases: { "@": "./" },
-  fallbackTarget: "style",
+  fallbackTarget: true,
   outputValidator: null,
   baseDir: null,
   showSpinner: true,
@@ -304,62 +441,61 @@ export default {
 
 ## Security
 
-All embedded JavaScript runs inside a **QuickJS sandbox** with strict restrictions:
+All `${ }$` expressions run inside a **QuickJS sandbox** — isolated from the host process:
 
-| Setting             | Default | What it does                                 |
-|---------------------|---------|----------------------------------------------|
-| `allowRaw`          | `true`  | Allow raw code in static blocks              |
-| `maxDepth`          | `5`     | Maximum import nesting depth                 |
-| `timeout`           | `5000`  | Script execution time limit (ms)             |
-| `allowFetch`        | `true`  | Allow network requests from scripts          |
-| `allowHttp`         | `false` | Block insecure HTTP (HTTPS only by default)  |
-| `allowedOrigins`    | `null`  | Restrict fetch to specific domains           |
-| `allowedExtensions` | `null`  | Restrict which file types can be imported    |
-| `sanitize`          | `null`  | Custom function to sanitize HTML output      |
+| Setting             | Default | Description                               |
+| ------------------- | ------- | ----------------------------------------- |
+| `allowRaw`          | `true`  | Allow JavaScript in compile-time blocks   |
+| `maxDepth`          | `5`     | Maximum import nesting depth              |
+| `timeout`           | `5000`  | Max execution time per script (ms)        |
+| `allowFetch`        | `true`  | Allow network requests from scripts       |
+| `allowHttp`         | `false` | Block plain HTTP — HTTPS only by default  |
+| `allowedOrigins`    | `[]`    | Restrict fetch to specific domains        |
+| `allowedExtensions` | `[]`    | Restrict which file types can be imported |
+| `sanitize`          | `null`  | Custom function to sanitize HTML output   |
 
 ---
 
-## Custom Output Rules
+## Custom mappers
 
 Define your own tags and rendering logic with the Mapper API:
 
 ```js
 import SomMark, { Mapper } from "sommark";
 
-const mapper = new Mapper("custom");
+const mapper = new Mapper();
 
-mapper.register("alert", (node) => {
-  return `<div class="alert">${node.body}</div>`;
+mapper.register("alert", function({ content, props }) {
+  const type = props.type || "info";
+  return `<div class="alert alert-${type}">${content}</div>`;
 });
 
-const engine = new SomMark({
-  src: '[alert]Check your configuration.[end]',
+const sm = new SomMark({
+  src: `[alert = type: "warning"]Check your config.[end:alert]`,
   format: "html",
   mapperFile: mapper,
 });
-
-const output = await engine.transpile();
 ```
 
-Full reference in [`docs/api/Mapper`](docs/api/Mapper).
+Full reference: [`docs/api/Mapper`](docs/api/Mapper)
 
 ---
 
 ## Documentation
 
-| Topic            | Location                                      |
-|------------------|-----------------------------------------------|
-| Syntax Reference | [`docs/syntax/`](docs/syntax)                 |
-| Core API         | [`docs/api/Core/`](docs/api/Core)             |
-| Browser API      | [`docs/api/Browser/`](docs/api/Browser)       |
-| Mapper API       | [`docs/api/Mapper/`](docs/api/Mapper)         |
-| Sandbox API      | [`docs/api/Sandbox/`](docs/api/Sandbox)       |
-| Output Formats   | [`docs/languages/`](docs/languages)           |
-| CLI Guide        | [`docs/cli/`](docs/cli)                       |
-| Configuration    | [`docs/cli/config.md`](docs/cli/config.md)    |
+| Topic            | Location                                   |
+| ---------------- | ------------------------------------------ |
+| Syntax Reference | [`docs/syntax/`](docs/syntax)              |
+| Output Formats   | [`docs/languages/`](docs/languages)        |
+| Core API         | [`docs/api/Core/`](docs/api/Core)          |
+| Browser API      | [`docs/api/Browser/`](docs/api/Browser)    |
+| Mapper API       | [`docs/api/Mapper/`](docs/api/Mapper)      |
+| Sandbox API      | [`docs/api/Sandbox/`](docs/api/Sandbox)    |
+| CLI Guide        | [`docs/cli/`](docs/cli)                    |
+| Configuration    | [`docs/cli/config.md`](docs/cli/config.md) |
 
 ---
 
 ## License
 
-[MIT](LICENSE) -- Adam Elmi
+[MIT](LICENSE) — Adam Elmi

package/cli/cli.mjs

@@ -76,7 +76,7 @@ async function main() {
 
 	// 5.5. Color
 	if (command === "color") {
-		runColor(args[1]);
+		await runColor(args[1]);
 		return;
 	}