Clarity.js

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). On npm the framework ships as the scoped package @ozsarman/clarityjs.

• Site & docs: https://clarity-js.com
• Source: https://gitlab.com/ozsarman/clarity.js
• npm: @ozsarman/clarityjs (framework) · create-clarity (scaffolder)

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:

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' 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, ~13 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
• Published on npm — npm i @ozsarman/clarityjs and npm create clarity@latest both work today

What is still ahead (tracked in PRODUCTION_ROADMAP.md): broader security hardening (XSS/CSP/CSRF), published benchmarks vs React/Solid, a browser playground, release automation and wider coverage. Honest framing: this is research-grade and evolving fast.

Quick start

Scaffold a new app (Vite + routing + a working component):

npm create clarity@latest my-app
cd my-app
npm install
npm run dev

Or add the framework to an existing project:

npm i @ozsarman/clarityjs

import { mount, signal } from '@ozsarman/clarityjs'

The npm package name is @ozsarman/clarityjs (the unscoped clarity-js is Microsoft's analytics library). The brand, domain clarity-js.com and the GitLab repo are unchanged — only the npm identity is scoped.

Your first component:

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:

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:

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 — 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, ROADMAP.md and 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 234 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.