summitjs 0.1.0

package/AGENTS.md

@@ -0,0 +1,105 @@
+# Summit.js for AI agents
+
+Summit is an HTML-first reactive framework. You add behavior to markup with
+`s-` attributes and `$` magics. There is no build step and no virtual DOM. A
+small, CSP-safe interpreter evaluates the expressions, so only a fixed,
+predictable vocabulary is allowed. This file tells you how to write Summit that
+runs correctly the first time.
+
+Full docs as one file: https://velofy.github.io/summit/llms-full.txt
+Index: https://velofy.github.io/summit/llms.txt
+Any page as markdown: append `index.md` to its URL.
+
+## Load it
+
+```html
+<script src="https://velofy.github.io/summit/summit.min.js" defer></script>
+```
+
+## The model
+
+- `s-data` declares reactive state on an element. Its descendants can read and
+  write that state in expressions.
+- State is signal-backed: reads track, writes notify, and only the affected DOM
+  updates. You never call render.
+- Expressions are a safe subset of JavaScript. You cannot reach arbitrary
+  globals. Allowed globals include `Math`, `JSON`, `Date`, `Object`, `Array`,
+  `Number`, `String`, `Boolean`, `console`, `window`, `document`, `location`,
+  `localStorage`, `setTimeout`, `fetch`, and other common read-only builtins.
+
+```html
+<div s-data="{ count: 0 }">
+  <button @click="count++">Add</button>
+  <span s-text="count"></span>
+</div>
+```
+
+## Directives
+
+| Directive | Shorthand | Purpose |
+| --- | --- | --- |
+| `s-data` | | declare reactive state |
+| `s-text` | | set textContent |
+| `s-html` | | set innerHTML (trusted content only) |
+| `s-bind:attr` | `:attr` | bind an attribute; `:class` and `:style` accept objects |
+| `s-on:event` | `@event` | run an expression on an event |
+| `s-model` | | two-way bind a form control |
+| `s-show` | | toggle visibility with `display` |
+| `s-if` | | add or remove from the DOM; a `<template s-if>` may hold multiple roots |
+| `s-for` | | render a list; use `:key` |
+| `s-ref` | | name an element, read it via `$refs` |
+| `s-init` | | run an expression once on init |
+| `s-effect` | | re-run an expression when its dependencies change |
+| `s-transition` | | animate enter and leave |
+| `s-teleport` | | move an element elsewhere in the DOM (dialogs, toasts) |
+| `s-intersect` | `s-intersect:leave` | run an expression when the element enters or leaves the viewport (`.once`, `.half`, `.full`) |
+| `s-trap` | | keep keyboard focus inside an element while an expression is truthy |
+| `s-anchor` | | position next to a reference element, flipping to stay in view (`.top`, `.end`, `.offset.N`) |
+| `s-collapse` | | animate an element open and closed by height |
+| `s-mask` | | format an input as you type (`9` digit, `a` letter, `*` either) |
+| `s-cloak` | | hide until initialized; pair with `[s-cloak]{display:none}` |
+| `s-ignore` | | skip a subtree |
+
+## Magics
+
+`$el`, `$refs`, `$root`, `$id`, `$store`, `$watch`, `$nextTick`, `$dispatch`,
+`$data`, `$persist`, `$focus`. Example: `@click="$dispatch('saved', { id: 3 })"`
+fires a custom event that a `@saved.window` handler can catch. Use
+`$persist(0)` in `s-data` for localStorage-backed state, and `$focus` to move
+keyboard focus.
+
+## Modifiers
+
+- Events: `.prevent`, `.stop`, `.self`, `.once`, `.window`, `.outside`,
+  `.capture`, `.passive`, `.debounce`, `.throttle`, and keys such as `.enter`,
+  `.escape`, `.cmd`, `.ctrl`, `.meta`, `.alt`, `.shift`.
+- Model: `.number`, `.trim`, `.lazy`.
+
+```html
+<input @keydown.enter="submit()" s-model.trim="query">
+<div @keydown.window.cmd.k.prevent="openPalette()"></div>
+<button @click.outside="open = false"></button>
+```
+
+## Rules that keep it correct
+
+- Every reactive expression must resolve against `s-data` state in scope. Do not
+  reference variables that are not declared in state or the allowed globals.
+- `s-for` needs a `:key` for stable, correct reconciliation.
+- Reach across components with events (`$dispatch`) or a shared `$store`, not by
+  reading another component's private state.
+- `s-html` is not sanitized. Use it only with content you trust.
+- Prefer `s-show` for frequent toggles and `s-if` to add or remove real DOM.
+
+## UI library
+
+Summit ships a copy-in component library. Load one stylesheet and use `s-`
+prefixed classes (`s-btn`, `s-input`, `s-card`, `s-alert`, `s-tabs`, `s-dialog`,
+and more). Theme everything by overriding CSS variables like `--accent`.
+
+```html
+<link rel="stylesheet" href="https://velofy.github.io/summit/assets/components.css">
+```
+
+See https://velofy.github.io/summit/components/ for every component with live
+demos and copy-paste markup.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Velofy
+
+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,160 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/velofy/summit/main/docs/assets/logo-dark.svg">
+    <img alt="Summit.js" src="https://raw.githubusercontent.com/velofy/summit/main/docs/assets/logo-light.svg" width="104">
+  </picture>
+</p>
+
+<h1 align="center">Summit.js</h1>
+
+<p align="center">The open source, AI Agent Native JavaScript framework for composing behavior directly in your HTML.<br>Drop in one script and go. No build step, no virtual DOM, no <code>eval</code>.</p>
+
+<p align="center"><strong>Open Source. by Nature.</strong></p>
+
+Started by [anishfyi](https://github.com/anishfyi), so that AI agents can make beautiful frontends.
+
+Summit is built in the spirit of Alpine's HTML-first ergonomics, then pushed further where it counts: a fine-grained signal engine, a CSP-safe expression evaluator, keyed list rendering, cached computed getters, a copy-in UI library, and full TypeScript types, all in about 16KB gzipped.
+
+## AI Agent Native
+
+Summit is designed so that an AI agent can write a working, good-looking frontend on the first try:
+
+- **HTML-first and local.** Behavior lives on the element it affects, so an agent edits one place and sees the result. No file graph to hold in context.
+- **Predictable vocabulary.** A small, closed set of `s-` directives and `$` magics. There is one obvious way to do most things, which is exactly what a model does best.
+- **Safe by construction.** Expressions are interpreted, never `eval`ed, so generated markup runs under a strict CSP and cannot reach outside its allowlist.
+- **A UI library, included.** Accessible, token-themed components an agent (or a person) drops in and themes with CSS variables. See the [UI Library](https://velofy.github.io/summit/components/).
+- **Built to be read by machines.** The whole framework is discoverable in one fetch: [`llms.txt`](https://velofy.github.io/summit/llms.txt) indexes every page, [`llms-full.txt`](https://velofy.github.io/summit/llms-full.txt) is the entire corpus as markdown, any page is available as markdown (append `index.md` to its URL) with a one-click "Copy for AI" button, and [`AGENTS.md`](./AGENTS.md) is a drop-in brief you can hand to your own agent.
+
+```html
+<script src="https://velofy.github.io/summit/summit.min.js" defer></script>
+
+<div s-data="{ open: false }">
+  <button @click="open = !open">Toggle</button>
+  <p s-show="open">Hello from Summit</p>
+</div>
+```
+
+## Why Summit
+
+| Capability | Summit | Classic HTML-sprinkle runtimes |
+| --- | --- | --- |
+| Reactivity | Fine-grained signals, surgical DOM updates | Effect re-runs, coarser |
+| Strict CSP (no `unsafe-eval`) | Default | Needs a separate, limited build |
+| Keyed list reconciliation | Built in | Limited |
+| Cached computed getters | Yes | Recomputed on every read |
+| `s-if` on any element | Yes | `<template>` only |
+| TypeScript types shipped | Yes | Partial |
+| Focus trap, floating menus, persisted state, input masking | Built in | Separate plugins |
+| Bundle size (gzip) | ~16KB, batteries included | ~16KB core, plugins extra |
+| Build step required | Never | Never |
+
+The headline difference is the engine. Summit owns a real signal core, so a change updates only the DOM that read the value that changed. And because expressions run through a hand-written interpreter rather than `new Function`, a strict Content-Security-Policy works out of the box.
+
+## Install
+
+Zero-build, drop in a script (auto-starts, exposes `window.Summit`):
+
+```html
+<script src="https://velofy.github.io/summit/summit.min.js" defer></script>
+```
+
+With a bundler:
+
+```bash
+npm install summitjs
+```
+
+```js
+import Summit from "summitjs";
+// register custom data, directives, magics, stores, or plugins here
+Summit.start();
+```
+
+## Directives
+
+Prefix `s-`, with `@` shorthand for `s-on:` and `:` for `s-bind:`.
+
+| Directive | Purpose |
+| --- | --- |
+| `s-data` | Declare a reactive component scope |
+| `s-text` / `s-html` | Set text or HTML content |
+| `s-bind` / `:` | Bind attributes, with class object and style object merging |
+| `s-on` / `@` | Listen for events, with a full modifier set |
+| `s-model` | Two-way form binding |
+| `s-show` | Toggle visibility via `display` |
+| `s-if` | Add or remove an element (works on any element, not just `<template>`) |
+| `s-for` | Keyed list rendering on a `<template>` |
+| `s-effect` | Run an expression reactively |
+| `s-transition` | Enter and leave animations, paired with `s-show` |
+| `s-teleport` | Render a `<template>` elsewhere while keeping its scope |
+| `s-ref` | Register an element into `$refs` (dynamic names supported) |
+| `s-init` | Run an expression once on init |
+| `s-id` | Open an id group for accessible `$id()` pairing |
+| `s-cloak` | Hide until initialized; pair with `[s-cloak]{display:none}` |
+
+### Event modifiers
+
+`.prevent .stop .self .outside .once .capture .passive .window .document .debounce .throttle`, key filters (`.enter .escape .arrow-up ...`), system keys (`.shift .ctrl .alt .cmd`), and name transforms (`.camel .dot`).
+
+### `s-model` modifiers
+
+`.lazy .change .blur .number .boolean .debounce .fill`.
+
+## Magics
+
+`$el`, `$refs`, `$root`, `$store`, `$data`, `$watch`, `$dispatch`, `$nextTick`, `$id`. They are available in expressions and as `this.$watch`, `this.$refs`, and so on inside component methods.
+
+`$watch` improves on the usual behavior: it returns an unwatch function and only fires on an actual change, so mutating the watched value inside its own callback cannot spin into an infinite loop.
+
+## Registration API
+
+```js
+Summit.data("dropdown", (open = false) => ({
+  open,
+  toggle() { this.open = !this.open },
+  init() { /* runs before the component renders */ },
+}));
+
+Summit.store("theme", { dark: false, toggle() { this.dark = !this.dark } });
+
+Summit.directive("uppercase", (el, meta, utils) => {
+  utils.effect(() => { el.textContent = String(utils.evaluate(meta.expression)).toUpperCase(); });
+});
+
+Summit.magic("now", () => () => new Date().toLocaleTimeString());
+
+Summit.plugin((s) => { /* register a bundle of the above */ });
+```
+
+Registration is timing-safe. Built-ins register at import, your registrations override them, and `Summit.start()` can be called whenever the DOM is ready. There is no load-order event to miss.
+
+## Reactivity primitives
+
+Summit's signal core is also usable standalone:
+
+```js
+import { signal, computed, effect, batch } from "summitjs";
+
+const count = signal(0);
+const doubled = computed(() => count() * 2);
+effect(() => console.log(doubled()));
+count.set(5); // logs 10
+```
+
+## Development
+
+```bash
+npm install
+npm run check   # typecheck + unit tests + build + size budget + bundle smoke + page verification
+```
+
+- `npm test` runs the Vitest suites (reactivity, evaluator, directives).
+- `npm run build` produces ESM, CJS, IIFE, and `.d.ts` in `dist/`, and syncs `docs/`.
+- `npm run smoke` drives the shipped bundle end to end.
+- `npm run verify` boots the real docs page under Summit and checks every demo.
+
+The documentation site in `docs/` dogfoods Summit and deploys to GitHub Pages.
+
+## License
+
+MIT