# Gyral

> Gyral is a small framework for web components: intents in, a pure update, a pure view out. Server rendering, forms, routing and testing built in. Components are standard custom elements rendered by Gyral's own view layer: messages come in from DOM events (intent), a pure `update` makes the next state and describes side effects as data (commands run by drivers), and a pure `view` renders it. Pages render on the server or prerender to static HTML and hydrate in place. The public API is plain TypeScript. Current version: 0.3.6.

Writing Gyral code? Read https://gyral.dev/llms-small.txt first: the rules, a complete component and tested recipes in one small file. Start a project with `npm create gyral@latest my-app -- --template ssr` (or `--template basic`). Connect Gyral's MCP server for docs search, API lookup, examples and scaffolding: hosted at https://mcp.gyral.dev/mcp (Streamable HTTP, no token; in Claude Code `claude mcp add --transport http gyral https://mcp.gyral.dev/mcp`), or locally with `npx -y @gyral/mcp`, which also typechecks snippets against your project; setup for other clients is in https://gyral.dev/docs/coding-agents/index.md. In Claude Code, install the Gyral skill with `/plugin marketplace add gyraljs/gyral`, then `/plugin install gyral@gyral`. Every docs link below is a Markdown page; https://gyral.dev/llms-full.txt has the docs, API reference and examples in one file.

## Docs

- [Gyral for coding agents](https://gyral.dev/llms-small.txt): Use when you are about to write or fix Gyral code; read it first. The mental model, MUST and DO NOT rules, a complete component, recipes with tests and an import map, in under 40 KB.
- [Gyral documentation](https://gyral.dev/docs/index.md): Use when you want the map of the docs and where to start. Learn Gyral, the Model-View-Intent framework for web components: guides, concepts and reference.
- [Getting started](https://gyral.dev/docs/getting-started/index.md): Use when creating a new Gyral app, or writing and testing your first component. Install Gyral, write your first Model-View-Intent component, use it in a page, and test it without a browser.
- [Recipes](https://gyral.dev/docs/recipes/index.md): Use when building a list with add, toggle, delete and filters, or a form with validation and custom error messages; you want a complete, tested component to start from. Complete components to copy, with their tests. A todo list with filters, a signup form with native validation, and fixes for common bugs.
- [Use Gyral with coding agents](https://gyral.dev/docs/coding-agents/index.md): Use when setting up a coding agent to write Gyral code, connecting the Gyral MCP server, or installing the Gyral skill. Connect Claude Code, VS Code or any MCP client to the Gyral MCP server, hosted or local, install the agent skill, and give agents llms-small.txt.
- [Components](https://gyral.dev/docs/components/index.md): Use when defining a component: the spec fields, props, child components, outputs and escape hatches. How define() turns a spec into a custom element, and how components pass data to each other with props and outputs.
- [Intent](https://gyral.dev/docs/intent/index.md): Use when turning clicks, keys, input, form submits or third-party events into messages; parsers, declining and preventDefault. How Gyral turns clicks, input, form submissions and keys into typed messages, and why the view never holds event handlers.
- [Model and update](https://gyral.dev/docs/update/index.md): Use when writing state, reducers and commands, subscriptions for long-lived work, or handling framework messages. State as plain data, one pure reducer per message, commands returned as data, and the framework messages Gyral sends you.
- [Views](https://gyral.dev/docs/views/index.md): Use when writing templates: bindings, keyed lists with each, form state, hooks, dialogs, focus and view transitions. Views are pure functions from state to html templates. Name intents, render keyed lists, bind form state, and let the compiler check markup.
- [Styling and themes](https://gyral.dev/docs/styling/index.md): Use when styling a component with css, themes, custom properties, custom states or document CSS. Style Gyral components with Shadow DOM, cascade layers, custom properties and custom states, and make a whole site themeable from CSS alone.
- [Forms](https://gyral.dev/docs/forms/index.md): Use when building a form with validation and error messages (the page starts with one complete component to copy), with no extra packages or with one schema shared by client and server; posting a form; file uploads. A complete validated form to copy, then the browser's own checks or one Standard Schema for client and server. Works with or without JavaScript.
- [Custom form controls](https://gyral.dev/docs/form-associated/index.md): Use when writing a custom element that takes part in a native form: value, validity, reset and restore. Make a Gyral component participate in native forms, with reset, disabled state, validity and a server-rendered fallback.
- [Effects and drivers](https://gyral.dev/docs/effects/index.md): Use when doing anything outside the model: HTTP, timers, randomness, the clipboard, your own driver, concurrency and retries. Reducers return commands, side effects described as data. Drivers run them, with built-in concurrency, retries and cancellation, and answer with messages.
- [Error handling](https://gyral.dev/docs/error-handling/index.md): Use when handling a reducer, parser, view or command that throws, or reporting errors to monitoring. How Gyral reports each failure once, lets a parent catch a child's failure, shows a component's fallback and keeps a server-rendered page going.
- [Browser storage](https://gyral.dev/docs/browser-storage/index.md): Use when saving state in localStorage or IndexedDB, with typed decoding, watches and migrations. Typed localStorage and IndexedDB drivers: persist values, watch settings, query records and run atomic transactions.
- [Network streams](https://gyral.dev/docs/network-streams/index.md): Use when reading a WebSocket or EventSource stream as messages. Native EventSource and WebSocket drivers: receive validated streams, send messages and handle connection lifecycles.
- [Shared state](https://gyral.dev/docs/stores/index.md): Use when sharing state between components, such as a cart or a session. Share state between distant components with stores, read like props from the side and written with messages, on the client and per request on the server.
- [State Gyral doesn't own](https://gyral.dev/docs/outside-state/index.md): Use when reading state Gyral does not own (signals, Redux, XState, a socket) with subscription(), or running long-lived work. Read signals, Redux-style stores, XState actors and WebSocket feeds with subscription(), write to them with plain drivers, and test both.
- [Routing](https://gyral.dev/docs/routing/index.md): Use when adding URLs and navigation, links, route tables and page heads. Typed route tables that work on the server and in the browser, navigation as commands, and the current URL streamed into your model.
- [Rendering modes](https://gyral.dev/docs/rendering-modes/index.md): Use when choosing between client-only, prerendered and server-rendered pages, or mixing them in one app. Choose how each page renders - in the browser only, once at build time, or on every request - and mix all three in one app.
- [Server rendering](https://gyral.dev/docs/server-rendering/index.md): Use when rendering pages on a server and hydrating them in the browser. Render pages on the server with Declarative Shadow DOM, hydrate them in place, keep a strict CSP, and ship a production build.
- [Static sites and prerendering](https://gyral.dev/docs/static-sites/index.md): Use when prerendering pages to static HTML at build time. Render pages to HTML files at build time with @gyral/ssr/static, ship zero JavaScript where nothing is interactive, and host them anywhere.
- [Code-splitting and lazy loading](https://gyral.dev/docs/code-splitting/index.md): Use when loading each component's code only on pages that use it, or delaying hydration until it is needed. Load each component's code only on the pages that use it, delay hydration until it's needed, and see what each page downloads.
- [Deploying](https://gyral.dev/docs/deploying/index.md): Use when shipping an app to a static host, Node, Bun, Deno or Cloudflare Workers, with cache headers and a CSP. Ship a Gyral app to a static host, a Node server, Bun, Deno or Cloudflare Workers, with the right cache headers and a strict Content Security Policy.
- [Rust servers](https://gyral.dev/docs/rust-servers/index.md): Use when your server is written in Rust: choosing between build-time pages, Rust templates with browser-rendered components, or embedded server rendering with gyral-rs. Serve Gyral from a Rust backend with build-time pages, with Askama pages and browser-rendered components, or with embedded server rendering through gyral-rs.
- [Testing](https://gyral.dev/docs/testing/index.md): Use when testing a model or a view without a browser, a component in a browser, fake drivers, virtual time, SSR and hydration, or coverage. Test models without a DOM, components in a real browser with fake drivers and virtual time, and server-rendered pages through hydration.
- [Devtools](https://gyral.dev/docs/devtools/index.md): Use when debugging which messages, states and commands a component went through. Watch every message, state change and command in your app with an in-page panel that costs nothing in production builds.
- [Using Gyral in other frameworks](https://gyral.dev/docs/other-frameworks/index.md): Use when using a Gyral component inside React, Vue, Svelte or plain HTML pages. Gyral components are standard custom elements. Use them in plain HTML, React, Vue or Svelte - set their props and listen to their outputs.
- [Using third-party web components](https://gyral.dev/docs/third-party-components/index.md): Use when using a web component from another library inside a Gyral view. Use Web Awesome, Shoelace, Material Web or any other custom element inside a Gyral view - turn its events into intents and style it through parts.
- [Security](https://gyral.dev/docs/security/index.md): Use when handling user input, CSRF, uploaded files, trusted markup or a Content Security Policy. Escape template data, protect form requests, keep secrets out of hydration seeds, and serve Gyral with a strict Content Security Policy.
- [Accessibility](https://gyral.dev/docs/accessibility/index.md): Use when checking labels, form errors, focus, announcements and motion in a component, or testing the real interface. Build Gyral views with native controls, useful labels, announced errors, predictable focus, and browser tests that cover keyboard interaction.
- [Performance](https://gyral.dev/docs/performance/index.md): Use when making long lists, frequent updates, payloads or hydration fast, or reproducing a speed claim. Measure Gyral's production payload, rendering work and hydration cost, then use keyed rows, structural sharing and islands where they help.
- [Packages](https://gyral.dev/docs/packages/index.md): Use when choosing which @gyral package to install, checking sizes, or reading known issues. Every @gyral package, what it's for, how to install it, and the optional build tools Gyral works with.
- [API reference](https://gyral.dev/docs/api/index.md): Use when you need to know which package exports a name, or the API reference for one package. The public API of every Gyral package, generated from the type declarations at build time so it always matches the code.
- [Browser support](https://gyral.dev/docs/browser-support/index.md): Use when checking which browsers Gyral supports and what happens where a newer API is missing. Gyral targets Baseline widely available browser features, with explicit fallbacks and progressive enhancement for newer platform APIs.
- [Versioning and stability](https://gyral.dev/docs/versioning/index.md): Use when checking what counts as public API, how releases work, and how to upgrade safely. Understand Gyral's 0.x API policy, package versions, how to upgrade and which entry points are internal.
- [Error codes](https://gyral.dev/errors/index.md): Use when a production build logs a code such as "Gyral G0010 …" and you need what it means and how to fix it. Every code a production build of Gyral prints, such as G0010: what the message says, what it means and how to fix it.

## API reference

- [@gyral/core](https://gyral.dev/docs/api/core/index.md): Use when you need the exact signature, options or doc comment of an @gyral/core export you already saw in an example or a compiler error; to write code, start from Recipes or Forms. Gyral core: Model-View-Intent web components on the web platform, with their own view layer.
- [@gyral/http](https://gyral.dev/docs/api/http/index.md): Use when you need the exact signature, options or doc comment of an @gyral/http export you already saw in an example or a compiler error; to write code, start from Effects and drivers. Gyral HTTP driver: fetch requests as data, typed errors, Standard Schema decoding.
- [@gyral/router](https://gyral.dev/docs/api/router/index.md): Use when you need the exact signature, options or doc comment of an @gyral/router export you already saw in an example or a compiler error; to write code, start from Routing. Gyral router: typed route tables, navigation as commands, History API baseline with Navigation API enhancement.
- [@gyral/time](https://gyral.dev/docs/api/time/index.md): Use when you need the exact signature, options or doc comment of an @gyral/time export you already saw in an example or a compiler error; to write code, start from Effects and drivers. Gyral time: delays, debounces and wall-clock ticks (every) as commands.
- [@gyral/ssr](https://gyral.dev/docs/api/ssr/index.md): Use when you need the exact signature, options or doc comment of an @gyral/ssr export you already saw in an example or a compiler error; to write code, start from Server rendering. Gyral server rendering: Declarative Shadow DOM pages with hydration seeds.
- [@gyral/testing](https://gyral.dev/docs/api/testing/index.md): Use when you need the exact signature, options or doc comment of an @gyral/testing export you already saw in an example or a compiler error; to write code, start from Testing. Gyral test helpers: pure update stepping, command helpers, fake drivers, virtual time, SSR page mounting, server rendering in Vitest browser tests.
- [@gyral/devtools](https://gyral.dev/docs/api/devtools/index.md): Use when you need the exact signature, options or doc comment of an @gyral/devtools export you already saw in an example or a compiler error; to write code, start from Devtools. Gyral devtools: an in-page timeline of messages, state, commands and stores (development builds).

## Examples

- [Gyral examples](https://gyral.dev/examples/index.md): Use when you want a working app to read or adapt: forms, HTTP, routing, shared state, animation or server rendering. Gyral examples with their source, from a counter to a server-rendered app, plus gyral-shop.
- [What you can build with Gyral](https://gyral.dev/what-you-can-build/index.md): Use when deciding whether Gyral fits a project, or explaining what it makes easy; no code. What Gyral makes easy, shown as short recordings of examples: undo and replay, type-ahead without stale results, and pages that work before JavaScript.

## Optional

- [Coming from Cycle.js](https://gyral.dev/docs/coming-from-cyclejs/index.md): Use when you know Cycle.js and want to map its streams, drivers and sources onto Gyral. What Gyral keeps from Cycle.js, what it changes and why, the counter side by side, and how Cycle.js concepts map to Gyral.
- [Design principles](https://gyral.dev/docs/principles/index.md): Use when you want the reasons behind Gyral's design. The beliefs behind Gyral, from "the platform is the framework" to "parse at boundaries", and what each one means for your code.
- [Coming from Lit](https://gyral.dev/docs/coming-from-lit/index.md): Use when porting a Lit component or app to Gyral, or comparing the two. Move a Lit component to Gyral's Model-View-Intent loop: explicit props, pure views, typed messages, keyed rows, drivers, stores and native hydration.
- [Brand and press](https://gyral.dev/brand/): Use when you need a Gyral logo, its colours or the trademark rules. Logos, colours and trademark guidelines (HTML).
- [Source code](https://github.com/gyraljs/gyral): Use when you need Gyral's own source, its examples or its issue tracker. The Gyral repository on GitHub.