@ozsarman/clarityjs 0.6.0

package/README.md

@@ -0,0 +1,178 @@
+# Clarity.js
+
+[![pipeline status](https://gitlab.com/ozsarman/clarity.js/badges/master/pipeline.svg)](https://gitlab.com/ozsarman/clarity.js/-/pipelines)
+
+**An AI-native, permission-aware frontend framework and DSL.**
+Components declare what AI agents may read, act on, and must never touch — directly in the markup.
+
+> **Disclaimer:** Clarity.js is an AI-native frontend framework and DSL. It is **not** affiliated with, and is unrelated to, Microsoft Clarity (the web analytics product).
+
+- Site & docs: **https://clarity-js.com**
+- Source: **https://gitlab.com/ozsarman/clarity.js**
+
+---
+
+## The idea
+
+Everyone is building AI agents. Almost nobody defines what those agents are allowed
+to **see** or **change** inside a user interface. We have authentication,
+authorization and RBAC for *people* — but almost no AI-specific access control for
+*interfaces*.
+
+Clarity.js makes that a first-class language feature. A component states its AI
+permissions right where the UI is declared:
+
+```clarity
+component Checkout() {
+  state email        = ""
+  state total        = 0
+  state paymentToken = ""
+
+  ai:readable    [email, total]     // agents may read these
+  ai:actionable  [applyCoupon]      // agents may call this
+  ai:forbidden   [paymentToken]     // agents must never touch this
+
+  action applyCoupon(code) { /* ... */ }
+
+  render {
+    <form>
+      <input bind:value={ email } />
+      <button on:click={ applyCoupon('SAVE10') }>Apply</button>
+    </form>
+  }
+}
+```
+
+The UI itself becomes the source of truth for what an agent may do — instead of
+teaching every agent, per integration, what it can and cannot touch. Every agent
+interaction flows through an **audited contract** (`readable` · `snapshot` · `act` ·
+`forbidden`) with a timestamped log.
+
+This is the part of Clarity.js worth caring about. The signals, router and SSR are
+solid table stakes; the **AI permission model is the differentiator**. There are
+hundreds of frontend frameworks — but almost none that govern AI agents&#39; access at
+the component level.
+
+---
+
+## Status — building in public
+
+Clarity.js is an **early, experimental framework**: a strong, well-tested foundation,
+**not yet production-hardened**. What exists today:
+
+- A real compiler pipeline — `.clarity` DSL → lexer → parser → codegen → lean JS
+- Signal-based, fine-grained reactivity — **no virtual DOM**, ~11.5 KB runtime
+- AI directives with **enforced `ai:forbidden`** — reads/writes blocked in agent
+  context, typed errors and an audit trail (not just a declaration)
+- A full-stack toolkit (routing, SSR/SSG, forms, i18n, testing, devtools…)
+- 234 passing tests, and a docs site built with the framework itself
+
+What is still ahead (tracked in [PRODUCTION_ROADMAP.md](PRODUCTION_ROADMAP.md)):
+broader security hardening (XSS/CSP/CSRF), benchmarks, npm publishing, release
+automation and wider coverage. Honest framing: this is research-grade and evolving fast.
+
+---
+
+## Quick start
+
+```bash
+npm create clarity@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Your first component:
+
+```clarity
+component Counter() {
+  state count = 0
+
+  render {
+    <button on:click={ count++ }>Clicked { count } times</button>
+  }
+}
+```
+
+`count++` writes to a signal; only the text node that reads `count` updates — there
+is no component re-render and no virtual DOM.
+
+---
+
+## The AI contract
+
+The `ai:` directives compile into an audited contract attached to each component, so
+an agent interacts through one guarded surface:
+
+```js
+const contract = el.__clarity_ai__
+
+contract.snapshot()              // audited read of all `ai:readable` state
+contract.read('email')          // audited single read — throws for non-readable fields
+contract.act('applyCoupon', '…') // guarded, logged action call
+contract.forbidden               // ['paymentToken'] — off-limits
+
+import { getAIAuditLog } from '@ozsarman/clarityjs'
+getAIAuditLog()                  // full timestamped trail of every interaction
+```
+
+`ai:forbidden` is **enforced, not just declared**. Forbidden fields are excluded from
+`readable` / `snapshot` / `read`, and the underlying signal blocks **both reads and
+writes** from inside any agent `act()` call — throwing a typed `ClarityAIForbiddenError`
+and recording an audit entry. An agent cannot read, alias, or return a forbidden field
+through the contract:
+
+```js
+import { ClarityAIForbiddenError } from '@ozsarman/clarityjs'
+try { contract.read('paymentToken') }      // ✗ throws ClarityAIForbiddenError (audited)
+catch (e) { e instanceof ClarityAIForbiddenError }  // true
+```
+
+Normal user/app code is completely unaffected — the guard fires only inside AI-action
+context. This is the boundary that turns the idea into a working AI security layer.
+
+---
+
+## What is in the box
+
+Beyond the reactive core and the AI layer, Clarity ships a full-stack toolkit — use
+only what you need:
+
+- **File-based routing** — `pages/` with dynamic `[slug]` routes, code-split (`scanPages`)
+- **Server rendering** — SSR, SSG, ISR, islands; `useServerData()` for component-level data
+- **Server actions** — `<form action={serverAction}>`, Express + edge adapters
+- **Async state** — `createQuery` / `useFetch` / `createMutation` (SWR/TanStack-style)
+- **Styling** — scoped CSS and CSS Modules (compile-time, no runtime CSS-in-JS)
+- **Tooling** — `create-clarity`, `eslint-plugin-clarity` (9 rules), test utilities,
+  in-browser devtools, a VS Code extension and language server
+
+A small `createGameLoop()` helper also powers the DOM games on the
+[showcase](https://clarity-js.com) — Clarity is a UI framework, not a game engine,
+but its reactivity drives more than forms.
+
+---
+
+## Documentation
+
+Full guides and an API reference live at **https://clarity-js.com** (itself built
+with Clarity.js). See also [CHANGES.md](CHANGES.md), [ROADMAP.md](ROADMAP.md) and
+[GAP_ANALYSIS.md](GAP_ANALYSIS.md).
+
+---
+
+## Contributing
+
+This is an open-source project, built in public. Issues, ideas and pull requests are
+welcome at https://gitlab.com/ozsarman/clarity.js. Run `npm test` before submitting —
+all 228 tests should stay green.
+
+---
+
+## License
+
+MIT
+
+---
+
+*Created by Özdemir Şarman. Built in public, with heavy use of AI tooling — fittingly,
+for a framework about humans and AI agents sharing the same UI.*

package/package.json

@@ -0,0 +1,168 @@
+{
+  "name": "@ozsarman/clarityjs",
+  "version": "0.6.0",
+  "description": "An AI-native, permission-aware frontend framework and DSL — components declare what AI agents may read, act on, and never touch.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./runtime": {
+      "import": "./src/runtime.js",
+      "default": "./src/runtime.js"
+    },
+    "./hydrate": {
+      "import": "./src/hydrate.js",
+      "default": "./src/hydrate.js"
+    },
+    "./ssr": {
+      "import": "./src/ssr.js",
+      "default": "./src/ssr.js"
+    },
+    "./vite": {
+      "import": "./src/vite-plugin.js",
+      "default": "./src/vite-plugin.js"
+    },
+    "./router": {
+      "import": "./src/router.js",
+      "default": "./src/router.js"
+    },
+    "./test": {
+      "import": "./src/clarity-test.js",
+      "default": "./src/clarity-test.js"
+    },
+    "./bundle": {
+      "import": "./src/clarity-bundle.js",
+      "default": "./src/clarity-bundle.js"
+    },
+    "./async-state": {
+      "import": "./src/async-state.js",
+      "default": "./src/async-state.js"
+    },
+    "./devtools": {
+      "import": "./src/devtools.js",
+      "default": "./src/devtools.js"
+    },
+    "./head": {
+      "import": "./src/head.js",
+      "default": "./src/head.js"
+    },
+    "./image": {
+      "import": "./src/image.js",
+      "default": "./src/image.js"
+    },
+    "./font": {
+      "import": "./src/font.js",
+      "default": "./src/font.js"
+    },
+    "./layout": {
+      "import": "./src/layout.js",
+      "default": "./src/layout.js"
+    },
+    "./linter": {
+      "import": "./src/linter.js",
+      "default": "./src/linter.js"
+    },
+    "./ssg": {
+      "import": "./src/ssg.js",
+      "default": "./src/ssg.js"
+    },
+    "./isr": {
+      "import": "./src/isr.js",
+      "default": "./src/isr.js"
+    },
+    "./islands": {
+      "import": "./src/islands.js",
+      "default": "./src/islands.js"
+    },
+    "./server-actions": {
+      "import": "./src/server-actions.js",
+      "default": "./src/server-actions.js"
+    },
+    "./edge": {
+      "import": "./src/edge.js",
+      "default": "./src/edge.js"
+    },
+    "./ts-plugin": {
+      "import": "./src/ts-plugin.js",
+      "default": "./src/ts-plugin.js"
+    },
+    "./file-conventions": {
+      "import": "./src/file-conventions.js",
+      "default": "./src/file-conventions.js"
+    },
+    "./pages-router": {
+      "import": "./src/pages-router.js",
+      "default": "./src/pages-router.js"
+    },
+    "./server-data": {
+      "import": "./src/server-data.js",
+      "default": "./src/server-data.js"
+    },
+    "./game-loop": {
+      "import": "./src/game-loop.js",
+      "default": "./src/game-loop.js"
+    },
+    "./error-overlay": {
+      "import": "./src/error-overlay.js",
+      "default": "./src/error-overlay.js"
+    },
+    "./analyze": {
+      "import": "./src/analyze.js",
+      "default": "./src/analyze.js"
+    },
+    "./i18n": {
+      "import": "./src/i18n.js",
+      "default": "./src/i18n.js"
+    }
+  },
+  "bin": {
+    "clarity": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "types/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --experimental-vm-modules tests/run.js",
+    "build:examples": "node src/cli.js build examples/",
+    "demo": "node src/cli.js demo",
+    "size": "npx esbuild src/runtime.js --bundle --format=esm --minify | wc -c | xargs -I{} sh -c 'echo \"Runtime minified: {} bytes ({KB} KB)\" | sed s/{KB}/$(echo \"scale=1; {} / 1024\" | bc)/'",
+    "size:full": "npx esbuild src/index.js --bundle --format=esm --minify --outfile=/tmp/clarity-full.min.js && echo \"Full bundle:\" && wc -c /tmp/clarity-full.min.js",
+    "prepublishOnly": "npm test",
+    "release:patch": "node scripts/release.js patch",
+    "release:minor": "node scripts/release.js minor",
+    "release:major": "node scripts/release.js major"
+  },
+  "keywords": [
+    "ai-native",
+    "ai-permissions",
+    "ai-agents",
+    "permission-aware",
+    "framework",
+    "frontend",
+    "signals",
+    "reactivity",
+    "compiler",
+    "dsl"
+  ],
+  "author": "Özdemir Şarman",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/ozsarman/clarity.js.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/ozsarman/clarity.js/-/issues"
+  },
+  "homepage": "https://clarity-js.com"
+}