@sigil-dev/compiler 0.5.0 → 0.6.1

package/README.md

@@ -1,3 +1,162 @@
-# Sigil Compiler
+# @sigil-dev/compiler
 
-Compiles JSX down to `document.createElement()` calls
+Compile-time JSX transform for Sigil.  
+Turns reactive macros and JSX into direct DOM operations with a tiny runtime overhead.
+
+```bash
+bun add -d @sigil-dev/compiler
+```
+
+## What it does
+
+The compiler runs at build time and does two things:
+
+**1. Transforms reactive macros into signal primitives**  
+This helps you avoid footguns ~~which should hardly be possible, we're not react~~
+
+```typescript
+// you write:
+let count = $state(0);
+let doubled = $derived(count * 2);
+
+$effect(() => {
+  console.log(doubled);
+});
+
+// compiler outputs:
+const count = createSignal(0);
+const doubled = createMemo(() => count() * 2);
+
+createEffect(() => {
+  console.log(doubled());
+});
+```
+
+**2. Transforms JSX into imperative DOM**
+
+```tsx
+// you write:
+const el = <div class="box">{count}</div>;
+
+// compiler outputs (dom mode):
+const el = document.createElement("div");
+el.className = "box";
+const t = document.createTextNode("");
+createEffect(() => { t.data = String(count()); });
+el.appendChild(t);
+```
+There's no virtual DOM involved, and none of the nonsense involved with it. Output is either a string or DOM manipulation. You won't fight with the runtime over what actually changed and what didn't
+
+## Modes
+
+Three output modes for the full SSR lifecycle:
+ 
+| Mode | Use | Output |
+|------|-----|--------|
+| `dom` | Client SPA navigation | Imperative DOM calls |
+| `ssr` | Server render | HTML string concatenation |
+| `hydrate` | Initial client load | Claims existing SSR nodes |
+
+The same source file compiles to different output depending on mode. In `ssr` mode, `$effect` is dropped entirely (effects don't make sense on the server). In `hydrate` mode, `claim()` calls replace `createElement` to reuse server-rendered nodes.
+
+## Macros
+
+### `$state`
+
+Declares a reactive variable. Primitive values use subscription sets. Objects and arrays use Proxy for deep reactivity.
+
+```typescript
+let count = $state(0);
+count++;           // compiled to count.set(count.peek() + 1)
+count = 10;        // compiled to count.set(10)
+
+let user = $state({ name: "Rei" });
+user.name = "Asuka"; // proxy handles this — no rewrite needed
+```
+
+### `$derived`
+
+A memoized value derived from other reactive state. Cached until dependencies change.
+
+```typescript
+let doubled = $derived(count * 2);
+// compiled to: const doubled = createMemo(() => count() * 2)
+// which is another tiny shim over createEffect()
+```
+
+### `$effect`
+
+Runs a side effect that re-runs when its reactive dependencies change.
+
+```typescript
+$effect(() => {
+  document.title = `Count: ${count}`;
+});
+// compiled to: createEffect(() => { document.title = `Count: ${count()}`; })
+```
+
+## Keyed lists
+
+`.map()` with a `key` prop compiles to a reconciled list that surgically updates only changed items:
+
+```tsx
+const items = $state([{ id: 1, name: "Rei" }, { id: 2, name: "Asuka" }]);
+
+<ul>
+  {items.map(item => (
+    <li key={item.id}>{item.name}</li>
+  ))}
+</ul>
+```
+
+Compiled to `reconcile()` — moves, inserts, and removes DOM nodes by key without recreating unchanged elements.
+
+## Scoped CSS
+
+CSS defined in a component file is automatically scoped with a deterministic hash:
+
+```tsx
+// styles in your component file get a unique hash prefix
+// .box → .box.s-a3f9b2c1
+// :global(.reset) escapes scoping
+```
+
+## Setup
+
+### Vite
+
+```typescript
+// vite.config.ts
+import { sigil } from "@sigil-dev/compiler/vite";
+
+export default {
+  plugins: [sigil()]
+};
+```
+
+### Bun (reccommended)
+
+```typescript
+// build script
+import { sigil } from "@sigil-dev/compiler/bun";
+
+await Bun.build({
+  entrypoints: ["src/index.tsx"],
+  plugins: [sigil({ mode: "dom" })],
+});
+```
+
+### Babel
+
+```typescript
+// babel.config.ts
+import { sigilBabelPlugin } from "@sigil-dev/compiler/babel";
+
+export default {
+  plugins: [sigilBabelPlugin({ mode: "dom" })]
+};
+```
+
+## Used by
+
+`@sigil-dev/grimoire` uses this compiler internally to process route files in three passes (ssr, hydrate, dom) during the build step. You can use it standalone for SPA projects via Vite, or wire it into any Babel-compatible build pipeline.

package/jsr.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sigil-dev/compiler",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"exports": "./index.ts",
 	"publish": {
 		"exclude": ["src/**/*.test.ts"]

package/package.json

@@ -1,24 +1,24 @@
 {
-	"name": "@sigil-dev/compiler",
-	"module": "index.ts",
-	"type": "module",
-	"version": "0.5.0",
-	"private": false,
-	"description": "Compiler for the Sigil framework",
-	"peerDependencies": {
-		"typescript": "^5"
-	},
-	"exports": {
-		".": "./index.ts",
-		"./babel": "./src/babel/index.ts",
-		"./vite": "./src/vite/index.ts",
-		"./bun": "./src/bun-plugin.ts"
-	},
-	"devDependencies": {
-		"@babel/core": "next",
-		"@babel/plugin-syntax-jsx": "next",
-		"@babel/plugin-syntax-typescript": "next",
-		"@babel/traverse": "next",
-		"@babel/types": "next"
-	}
+  "name": "@sigil-dev/compiler",
+  "module": "index.ts",
+  "type": "module",
+  "version": "0.6.1",
+  "private": false,
+  "description": "Compiler for the Sigil framework",
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./babel": "./src/babel/index.ts",
+    "./vite": "./src/vite/index.ts",
+    "./bun": "./src/bun-plugin.ts"
+  },
+  "devDependencies": {
+    "@babel/core": "next",
+    "@babel/plugin-syntax-jsx": "next",
+    "@babel/plugin-syntax-typescript": "next",
+    "@babel/traverse": "next",
+    "@babel/types": "next"
+  }
 }

package/src/babel/jsx/element.ts

@@ -153,7 +153,8 @@ export function processElement(
 		seenAttrs.add(realAttr);
 		if (attrName === "use") {
 			// use={directive} or use={[directive, params]}
-			const expr = (attr.value as t.JSXExpressionContainer).expression as t.Expression;
+			const expr = (attr.value as t.JSXExpressionContainer)
+				.expression as t.Expression;
 			statements.push(
 				t.expressionStatement(
 					t.callExpression(t.identifier("applyDirective"), [
@@ -335,7 +336,10 @@ export function processElement(
 						t.binaryExpression("===", poolLen, t.numericLiteral(0)),
 						t.expressionStatement(
 							t.callExpression(
-								t.memberExpression(t.identifier(varName), t.identifier("append")),
+								t.memberExpression(
+									t.identifier(varName),
+									t.identifier("append"),
+								),
 								[
 									t.callExpression(
 										t.memberExpression(

package/src/babel/jsx/fragment.ts

@@ -90,7 +90,10 @@ export function processFragment(
 						t.binaryExpression("===", poolLen, t.numericLiteral(0)),
 						t.expressionStatement(
 							t.callExpression(
-								t.memberExpression(t.identifier(effectiveParent), t.identifier("append")),
+								t.memberExpression(
+									t.identifier(effectiveParent),
+									t.identifier("append"),
+								),
 								[
 									t.callExpression(
 										t.memberExpression(