xmlui

Imported from xmlui-org/xmlui (AGENTS.md). Install upstream with npx skills add xmlui-org/xmlui. Copyright stays with the author.

AGENTS.md — XMLUI Monorepo

Agent-oriented reference for the XMLUI monorepo. Read this first for any task. For deeper detail, refer to:

• .plan/ — default location for new AI-authored plans. When asked to create or record a plan, place the markdown file here unless the user explicitly names another location. Keep plan filenames short and descriptive; do not include dates.
• xmlui/dev-docs/ — architecture & subsystem reference (rendering, containers, theming, forms, etc.)
• .ai/xmlui/ — contribution conventions and patterns (components, testing, QA checklist). Key files: .ai/xmlui/markup.md (XMLUI markup patterns, context variables, scripting semantics), .ai/xmlui/data.md (DataSource/APICall patterns), .ai/xmlui/component-architecture.md (component authoring — metadata, renderer, native patterns), .ai/xmlui/behaviors.md (auto-attached behaviors), .ai/xmlui/testing-conventions.md (E2E + unit test conventions), .ai/xmlui/qa-checklist.md (QA audit checklist).
• .github/prompts/ — task-specific AI workflow prompts. Before starting component creation, bug fixes, reviews, tests, docs, extension work, or refactors, check this folder for the matching prompt and follow it.

When converting documentation xmlui-pg examples from segmented ---app/---comp form to the single-file inline-component form, preserve section-level codefence options such as display, copy, and highlight selectors (/pattern/, !/pattern/) by moving them to the opening xmlui-pg fence line; otherwise source display and highlights disappear.

All documentation xmlui-pg fences should include a human-readable name="..." title. Keep or add id="..." only for examples that are covered by website example tests; id is the stable Playwright test.describe(...) identity, while name is display text and may change without making specs stale. Existing name-based spec titles are accepted as legacy identities.

Marker-free xmlui-pg examples may still include later sections such as ---api, ---config, or ---comp. In that form, all content before the first section marker is the app entrypoint content; do not drop it or require an explicit ---app.

Reusable user-defined components may be empty: <Component name="Empty" /> or <Component name="Empty"></Component> is valid and represents an empty Fragment. Do not reintroduce a parser error requiring at least one nested component definition.

Website E2E helper xmlui/src/testing/website-example-utils.ts must keep backward compatibility with specs that call initTestBed(app, { components, apiInterceptor }). When extracting marker-free one-file xmlui-pg examples with top-level inline <Component> declarations, split those declarations into components and return only the single non-Component app root as app.

What is XMLUI

User perspective: .ai/xmlui/overview.md describes XMLUI from the application developer's point of view — markup syntax, reactive binding, routing, forms, global functions. Read this to understand what the components you build are for.

XMLUI is a declarative, reactive frontend framework for building web applications using XML markup. Users write .xmlui files instead of JavaScript/JSX. The framework is fully reactive — expressions in markup re-evaluate automatically when their dependencies change, similar to a spreadsheet. There is no manual state wiring.

Under the hood XMLUI is built on React. Every XMLUI component is backed by a React component. Reactivity, routing, data fetching, and theming are all React-based internally, but users of the framework never interact with React directly.

Two Deployment Modes

XMLUI operates in one of two modes, determined when a project is created — not something that changes at runtime.

Standalone mode (buildless) The app is served as static files. The XMLUI runtime (xmlui-standalone.umd.js) is loaded via a <script> tag. On startup it fetches Main.xmlui, discovers referenced components from the components/ directory, and renders everything — all parsing happens in the browser at runtime. No build step required. Deploy by copying files to any static web server.

my-app/
├── index.html         ← loads xmlui-standalone.umd.js from a CDN or local path
├── Main.xmlui         ← app entry point
├── config.json        ← optional: routing, globals
├── components/        ← custom components, discovered automatically
├── themes/            ← optional: custom theme JSON files
└── xmlui/<version>.js ← the XMLUI runtime

Vite mode (built) The app uses Vite + the vite-xmlui-plugin. .xmlui files are compiled at build time into JS modules. import.meta.glob() in the entry point pre-bundles all components. The result is an optimized production bundle with no runtime parsing overhead. Used for production sites (like the XMLUI docs site) and when HMR during development is needed.

Both modes share the same rendering pipeline once components are resolved. The same .xmlui markup syntax works in both.

High-Level App Architecture

An XMLUI app has these layers:

1. Markup — .xmlui files describing the UI tree in XML. Components are XML tags; attributes are props; {expression} syntax binds values reactively.
2. Component registry — maps component names to their React renderer. Built-in components live in xmlui/src/components/. Extension packages add more.
3. Rendering pipeline — the framework parses component definitions, evaluates expressions, and produces a React element tree. The renderChild() function is the recursive heart of this.
4. State containers — each component tree node that has state lives in a container. The container holds a flat key-value state object and a reducer. Reactivity flows through this.
5. Provider stack — the app wraps everything in providers for: routing (react-router-dom), data fetching (@tanstack/react-query), theming, icons, confirmation modals, debug tooling, and more.
6. Global context — AppContext exposes global functions to markup: navigate(), toast(), confirm(), Actions.*, and utilities like date/math helpers.

Repository Layout

xmlui-repo-root/
├── xmlui/           # Main framework package — PRIMARY FOCUS
│   ├── src/
│   │   ├── components/       # All built-in XMLUI components (~104 components)
│   │   ├── components-core/  # Core rendering infrastructure, theming, parts
│   │   ├── parsers/          # Expression / XML parsers
│   │   └── testing/          # Test fixtures and infrastructure
│   ├── tests/                # Unit tests (Vitest), mirrors src/ structure
│   └── dev-docs/             # Architecture & subsystem reference docs
├── guidelines/      # Contribution conventions and patterns (xmlui/, packages/, tools/, …)
├── packages/        # Extension packages (xmlui-animations, xmlui-pdf, xmlui-spreadsheet, etc.)
├── docs/            # Documentation website (built-mode XMLUI app)
├── blog/            # Blog site
└── tools/           # create-app CLI, VS Code extension

The extension packages in packages/ follow the same component conventions as xmlui/ and depend on it.

Monorepo Tooling

npm workspaces + Turborepo 2.x for task orchestration. Vite 7.x for builds, Vitest for unit tests, Playwright for E2E tests. @changesets/cli for versioning.

Changesets

When a change impacts framework users (new feature, bug fix, API change) and not xmlui developers or applications, add a changeset before finishing. The cli tool is interactive, so instead do the following manual steps:

1. create a file in .changeset/.md
2. The frontmatter contains pairs of (affected package name - semver increments), like "xmlui": patch. All changes are strictly marked as patch changes, unless stated otherwise.
3. Markdow body is the change description
4. Check your changes are recognised by running npx changeset status at the monorepo root

Metadata snapshot

When changing component metadata, theme variables, default theme variables, props, events, APIs, parts, or context variables, rebuild the language-server metadata snapshot before committing:

npm --prefix xmlui run check:metadata-snapshot

This command intentionally fails when xmlui/src/language-server/xmlui-metadata-generated.js changes. Include that regenerated file in the commit, then rerun the command; CI expects the snapshot to match the metadata source.

Task Quick Reference

Use the prompt files in .github/prompts/ for step-by-step workflows. Invoke with #prompt-name in VS Code Copilot chat.

If no prompt is invoked, use the documentation map below to find the right reference material for your task.

Documentation Map

Architecture & Internals (.ai/xmlui/)

| qa-checklist.md | QA audit checklist — actionable per-section checklist for component reviews |

Human-Readable Guides (xmlui/dev-docs/guide/)

Numbered 01–25, same topics as above. Read for deeper explanations and conceptual context. AI docs are sufficient for most implementation tasks.

Project Rules (guidelines.md)

Contains ~300 lines of verified rules organized by topic. Read the section relevant to your task:

• Topics 4–5: Component architecture and wrapComponent rules
• Topics 7: Theming and SCSS conventions
• Topics 9: Behavior attachment rules
• Topics 12: Form infrastructure rules
• Topics 17: Error handling rules
• Topics 23: Testing conventions
• Topics 24: Accessibility rules