# Qingkuai

> Qingkuai (from Chinese "轻快", meaning lightweight and fast) is a frontend framework for building web user interfaces. It compiles `.qk` component files into minimal, strictly optimized JavaScript with compiler-inferred reactivity, direct DOM updates without a Virtual DOM, and built-in TypeScript support.

## Agent Reference

- [Agent Reference Index](https://qingkuai.dev/agent/index.md): syntax cheat sheet, code-generation rules, task-to-docs routing, and cross-syntax dependency lookup.

## Getting Started

- [Installation](https://qingkuai.dev/agent/getting-started/install.md): Qingkuai installation: scaffold projects with create-qingkuai (npm/pnpm/yarn), the --ts TypeScript option, and the dev-server startup commands; with a globally installed qingkuai command you can init and run type checks directly.

- [Introduction](https://qingkuai.dev/agent/getting-started/introduction.md): Qingkuai framework overview: reactive-variable and component-based programming model, embedded language tags, design philosophy, and core advantages over other frameworks.

## Basic

- [Compilation Directives](https://qingkuai.dev/agent/basic/compilation-directives.md): Qingkuai compilation directives: #if/#elif/#else, #for, #key, #await/#then/#catch, #html, #target, #scope, #slot — exact usage forms, semantics, priority order, and constraints.

- [Event Handling](https://qingkuai.dev/agent/basic/event-handling.md): Binds DOM and component events via @-attributes: method references, inline handlers with $arg, event handler flags, and compiler-managed event delegation.

- [Form Handling](https://qingkuai.dev/agent/basic/forms.md): Form element two-way binding in Qingkuai via reference attributes: &value on input/textarea/select, &number on input, &checked and &group on radio/checkbox inputs.

- [Interpolation Blocks](https://qingkuai.dev/agent/basic/interpolation.md): Qingkuai interpolation blocks: text interpolation, dynamic attributes, dynamic class object/array forms, and the expression-only rule inside curly braces.

- [Reactivity](https://qingkuai.dev/agent/basic/reactivity.md): Qingkuai reactivity APIs and declaration forms: compiler-inferred reactivity, explicit raw/reactive/shallow markers, derived state (derived / derivedExp), alias bindings, reactivity modes, non-reactive reads (noTracking / raw), and toRaw/toReactive/createStore utilities.

- [Reference Attributes](https://qingkuai.dev/agent/basic/reference-attributes.md): Qingkuai reference attributes pass variable references through &-prefixed attributes (&handle for DOM elements, &value/&number/&checked/&group for form state) via setter invocations.

- [Watchers and Side Effects](https://qingkuai.dev/agent/basic/watchers-and-side-effects.md): Qingkuai watchers and side effects: watch/effect families across four trigger timings, shorthand *Exp registration, external registration with instance binding, and cleanup semantics.

## Components

- [Async Components](https://qingkuai.dev/agent/components/async-components.md): Qingkuai async components: Promise and dynamic-import component tags, #await/#then/#catch directive rendering, dynamic switching, and instance access via &handle.

- [Component Attributes](https://qingkuai.dev/agent/components/attributes.md): Passing data, events, and writable references into Qingkuai components through component tag attributes.

- [Component Basics](https://qingkuai.dev/agent/components/basic.md): Qingkuai component files: file-based definition model, import and tag usage, kebab-case/camelCase naming equivalence, and member access tags.

- [Component Contexts](https://qingkuai.dev/agent/components/contexts.md): Qingkuai component contexts: setContext/setContextGetter/setContextExp writes, prototype-chain reads via contexts, default values, and external instance-bound context APIs.

- [Dynamic Components](https://qingkuai.dev/agent/components/dynamic-components.md): Qingkuai dynamic components: variable component tags, automatic switching on value change, instance handle updates, and derived-based union type inference.

- [Member Exports](https://qingkuai.dev/agent/components/exports.md): Qingkuai member exports: supported export statement forms, consumption through the component instance via &handle, and prohibited export forms.

- [Component Lifecycle](https://qingkuai.dev/agent/components/lifecycle.md): Qingkuai component lifecycle: onAfterMount, onBeforeDestroy, onAfterDestroy, onBeforeUpdate, onAfterUpdate — built-in registration rules and external instance-bound registration.

- [Slots](https://qingkuai.dev/agent/components/slots.md): Declaring slot outlets, named slots, fallback content, scoped slot context, and slot presence checks in Qingkuai components.

- [Component Stylesheets](https://qingkuai.dev/agent/components/stylesheets.md): Qingkuai stylesheets: scoped embedded style blocks, #scope style penetration, src/@import external styles, global style blocks, and qk-scope selector positioning.

## References

- [API Reference](https://qingkuai.dev/agent/references/api.md): Qingkuai runtime and compiler package API reference: instance-bound runtime APIs, contexts operations, reactivity controls, state/scheduling functions, and compiler entry exports.

- [Error Code Reference](https://qingkuai.dev/agent/references/error-code.md): Qingkuai error code reference: 1xxx compilation errors, 9xxx compilation warnings, 2xxx runtime errors, 8xxx runtime warnings, 3xxx/7xxx language-service messages.

- [Built-in Identifiers](https://qingkuai.dev/agent/references/intrinsics.md): Complete reference of Qingkuai built-in identifiers: props, refs, slots, contexts, instance, reactivity markers, watcher/effect families, defaults, and context methods.

- [Reactivity Inference Rules](https://qingkuai.dev/agent/references/reactivity-infer-rules.md): Ordered rules the Qingkuai compiler uses to infer each top-level identifier's reactivity type: explicit markers, degeneration conditions, and implicit template-usage-based inference.

- [Terminology Reference](https://qingkuai.dev/agent/references/terminology.md): Qingkuai terminology reference: component file/instance, attribute kinds, interpolation terms, embedded language tags, slot terms, runtime package, built-in identifiers and methods.

## Misc

- [Built-in Elements](https://qingkuai.dev/agent/misc/builtin-elements.md): Qingkuai built-in elements: qk:spread as a virtual directive mounting point for sibling groups and text nodes, rendered as nothing.

- [Command Line Tool](https://qingkuai.dev/agent/misc/cli.md): Qingkuai command line tool: init scaffolding, dev/build/preview development and building, check type checking, format formatting, build-types declaration generation, and type re-exports of vite/prettier/typescript.

- [Configuration Files](https://qingkuai.dev/agent/misc/config-files.md): Qingkuai configuration: .qingkuairc runtime configuration options (reactivityMode, whitespace, resolveImportExtension, ...) and Prettier qingkuai formatting options.

- [Debugging](https://qingkuai.dev/agent/misc/debugging.md): Qingkuai debugging: source maps for script and style blocks, reactive identifier wrappers in DevTools, directive context debug info, and interpolation update mapping points.

- [Language Features](https://qingkuai.dev/agent/misc/language-features.md): Qingkuai language features: LSP-based service, VS Code extension, Emmet syntax difference, formatting, language-server restart, code navigation, and the MCP server for AI agents.

- [Optimization](https://qingkuai.dev/agent/misc/optimization.md): Qingkuai optimization: Signal Mode (reactivityMode: shallow + allowConstReactive: false), directive-level tree shaking, shared-style reuse rules to avoid duplicated scoped CSS, and code splitting with async components.

- [TypeScript Support](https://qingkuai.dev/agent/misc/typescript.md): Qingkuai TypeScript support: the Meta component contract, generics on Meta, defaults narrowing, slot/event inference, and runtime utility types (ComponentInstance, ComponentProps, ...).