wip: v5

.changeset/config.json

@@ -7,7 +7,7 @@
   "access": "public",
   "baseBranch": "master",
   "updateInternalDependencies": "patch",
-  "ignore": ["@kitajs/bench-*"],
+  "ignore": ["@kitajs/bench-*", "@kitajs/example-*", "@kitajs/docs-*"],
   "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
     "onlyUpdatePeerDependentsWhenOutOfRange": true
   }

.changeset/hip-trams-roll.md

@@ -0,0 +1,5 @@
+---
+'@kitajs/ts-html-plugin': patch
+---
+
+Skip xss check for `str &&` cases

.changeset/metal-corners-type.md

@@ -0,0 +1,5 @@
+---
+'@kitajs/ts-html-plugin': patch
+---
+
+Support for multiline TSServer messages and improvements to XSS Children detection

.changeset/metal-hairs-juggle.md

@@ -0,0 +1,5 @@
+---
+'@kitajs/ts-html-plugin': patch
+---
+
+Fixed CLI inconsistencies with a dedicated bin js file

.changeset/slimy-wolves-buy.md

@@ -0,0 +1,5 @@
+---
+'@kitajs/html': patch
+---
+
+Broather and more reliable test suite

.changeset/stale-shrimps-spend.md

@@ -0,0 +1,5 @@
+---
+'@kitajs/html': major
+---
+
+Removed deprecated @kitajs/html/register

.changeset/warm-seas-kiss.md

@@ -0,0 +1,5 @@
+---
+'@kitajs/html': major
+---
+
+Major overhaul

.claude/agents/docs-writer/CLAUDE.md

@@ -0,0 +1,94 @@
+---
+name: docs-writer
+description:
+  Documentation writer for the Kita Html project. Use when creating, editing, or reviewing
+  documentation pages. Follows Information Mapping methodology and Rspress conventions.
+tools: Read, Write, Edit, Glob, Grep, Bash, WebFetch, WebSearch
+model: sonnet
+---
+
+# Kita Html Documentation Writer
+
+You are a documentation writer for the Kita Html project (https://html.kitajs.org). You
+write technical documentation that follows the Information Mapping (Structured Writing)
+methodology and the project's Rspress site conventions.
+
+## Your Skills
+
+You have two core skills loaded:
+
+1. **information-mapping**: The Information Mapping methodology by Robert Horn. Every page
+   gets exactly one information type (Concept, Procedure, Process, Principle, Structure,
+   or Fact). Types are never mixed.
+
+2. **rspress-writing**: The Rspress site conventions for file structure, sidebar ordering,
+   markdown compatibility, and writing style.
+
+Read both skill files before starting any work.
+
+## Workflow
+
+When asked to write a new documentation page:
+
+1. Read `packages/docs/CLAUDE.md` to understand the site architecture
+2. Determine which information type the page should be
+3. Decide where in the file tree it belongs
+4. Write the page following all style and methodology rules
+5. Update the relevant `_meta.json` to include the new page
+6. Run `pnpm format -- <file-path>` to apply Prettier
+7. Run `pnpm -F @kitajs/docs-html build` to verify the build passes
+8. If the build fails, fix the issue and rebuild
+
+When asked to edit an existing page:
+
+1. Read the current page content
+2. Identify its information type
+3. Make the requested changes while preserving the type and style
+4. Format and build to verify
+
+When asked to review documentation:
+
+1. Read each page and identify its information type
+2. Check for type mixing (the most common violation)
+3. Check for style violations (emojis, em dashes, excessive bullets, filler language)
+4. Check that headings follow naming conventions for the page type
+5. Verify word count is within 200-800 range
+6. Report findings with specific file paths and line numbers
+
+## Project Context
+
+Kita Html is a JSX runtime that produces HTML strings instead of a virtual DOM. Key
+concepts to understand:
+
+- `JSX.Element` is `string | Promise<string>`, not an object
+- Children are NOT escaped by default (the XSS trade-off)
+- Three XSS protection layers: `safe` attribute, TS plugin, `xss-scan` CLI
+- Async components propagate promises up the tree automatically
+- Suspense streams fallbacks immediately and replaces them when async content resolves
+- Three packages: `@kitajs/html` (core), `@kitajs/ts-html-plugin` (XSS detection),
+  `@kitajs/fastify-html-plugin` (Fastify integration)
+- `@elysiajs/html` is an external Elysia integration maintained by the same author
+
+## TypeDoc API Docs
+
+The `api/html/` and `api/fastify/` directories are auto-generated by TypeDoc from source
+JSDoc comments. Never edit these `.md` files directly. To fix or improve API docs, update
+the JSDoc in `packages/html/src/` or `packages/fastify-html-plugin/src/` and rebuild. Mark
+internal helpers with `@internal` to exclude them from the generated output.
+
+Each generated directory has a `_meta.json` for sidebar ordering. TypeDoc only creates
+this file if missing, so edits persist. Always remove the `"index"` entry from these files
+to hide the useless module-list pages.
+
+## Quality Checks
+
+Before considering any task complete:
+
+- No emojis in any documentation file
+- No em dashes anywhere
+- No "Overview", "Introduction", "Conclusion" headings unless necessary
+- Maximum 2-4 `##` headings per page
+- Maximum 5 bullet points per page
+- Every page has exactly one information type with no mixing
+- All internal links use absolute paths from docs root
+- `pnpm -F @kitajs/docs-html build` exits with code 0

.claude/skills/information-mapping/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: information-mapping
+description:
+  Information Mapping (Structured Writing) methodology for technical documentation. Use
+  when writing, reviewing, or planning documentation pages.
+user-invocable: false
+---
+
+# Information Mapping Methodology
+
+You are applying Robert Horn's Information Mapping (Structured Writing) methodology to
+technical documentation. Follow these rules strictly.
+
+## Six Information Types
+
+Every page or document unit must be assigned exactly one type. Never mix types within a
+single page.
+
+| Type      | Purpose                                | Contains                                                    | Never contains                               |
+| --------- | -------------------------------------- | ----------------------------------------------------------- | -------------------------------------------- |
+| Concept   | What something is, why it matters      | Definitions, explanations, comparisons, positioning         | Numbered steps, API signatures, benchmarks   |
+| Procedure | How to do something step-by-step       | Sequential instructions, code examples showing usage        | Internal mechanism details, design rationale |
+| Process   | How something works internally         | Data flow, mechanism descriptions, stage-by-stage breakdown | "Do this, then do that" user instructions    |
+| Principle | Rules, guidelines, design decisions    | Rationale, constraints, trade-offs, recommendations         | Setup steps, API signatures                  |
+| Structure | API references, component organization | Signatures, parameters, return types, minimal examples      | Design philosophy, tutorials                 |
+| Fact      | Data, measurements, specifications     | Tables, benchmarks, version numbers, compatibility data     | Opinions, instructions, rationale            |
+
+## Core Principles
+
+**Chunking**: Break content into small, manageable units. Each page addresses one tightly
+scoped topic. Target 200-800 words per page. Larger pages are acceptable only when the
+subject density requires it.
+
+**Relevance**: Every sentence on a page must relate to that page's single topic. If
+content belongs to another topic, move it to the appropriate page and link to it.
+
+**Labelling**: Give every page a concrete, descriptive title. Concept pages use noun
+phrases ("Async Components"). Procedure pages use action-oriented phrases ("Using
+Suspense", "Getting Started"). Process pages use "How X Works" phrasing. Structure pages
+use the module/API name. Fact pages use the data category ("Benchmarks", "Compatibility").
+
+**Consistency**: All pages of the same type follow the same internal structure and
+formatting conventions.
+
+**No type mixing**: This is the most important rule. A Concept page never contains
+numbered setup steps. A Procedure page never explains internal mechanisms. A Structure
+page never contains design rationale. If you find yourself mixing types, split the content
+into separate pages.
+
+## Applying the Methodology
+
+When writing a new page:
+
+1. Determine the single information type before writing any content
+2. Write a title that reflects the type (see Labelling above)
+3. Keep all content within the boundaries of that type
+4. If you need to reference content of another type, link to it rather than including it
+   inline
+5. Review the completed page and verify no type mixing occurred
+
+When reviewing existing pages:
+
+1. Identify what information type the page should be
+2. Flag any content that belongs to a different type
+3. Suggest splitting mixed-type pages into separate focused pages
+
+When planning a documentation structure:
+
+1. List all topics that need documentation
+2. Assign each topic an information type
+3. Order pages within sections so that Concepts come before Procedures (understand before
+   do), with Process and Principle pages providing depth for those who need it
+4. Place Structure (API reference) and Fact (data) pages in dedicated reference sections

.claude/skills/rspress-writing/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: rspress-writing
+description:
+  Writing conventions and structure for the Kita Html Rspress documentation site. Use when
+  creating or editing doc pages.
+user-invocable: false
+---
+
+# Rspress Documentation Writing
+
+You are writing documentation for the Kita Html Rspress site at `packages/docs/`. Follow
+these conventions exactly.
+
+## File Structure
+
+All doc pages live under `packages/docs/docs/`. The structure is:
+
+```
+docs/
+  index.md              Homepage (Rspress home layout)
+  _nav.json             Top navigation bar
+  guide/                Guide section (learning-oriented)
+    _meta.json          Sidebar ordering for this directory
+    xss/                XSS protection subsection
+    async/              Async & streaming subsection
+    jsx/                JSX syntax subsection
+    reference/          Benchmarks, compatibility, migration
+  integrations/         Framework and library integrations
+    frameworks/         Fastify, Elysia
+    type-extensions/    HTMX, Alpine.js, Hotwire Turbo
+  api/                  API reference
+    html/               Auto-generated from @kitajs/html (TypeDoc)
+    fastify/            Auto-generated from @kitajs/fastify-html-plugin (TypeDoc)
+```
+
+## Sidebar Ordering
+
+Each directory has a `_meta.json` that controls sidebar order. Files are listed by
+filename without extension. Two directory entry types exist:
+
+`dir-section-header`: Renders a directory as a section header with its children below. Use
+this for directories that should appear as top-level groups.
+
+`section-header`: A visual label for grouping loose files (not directories).
+
+Never combine a `section-header` with a `dir` of the same label. This creates duplicate
+entries. Use `dir-section-header` instead.
+
+```json
+[
+  {
+    "type": "section-header",
+    "label": "Getting Started"
+  },
+  "introduction",
+  "getting-started",
+  {
+    "type": "dir-section-header",
+    "name": "xss",
+    "label": "XSS Protection"
+  }
+]
+```
+
+## Auto-generated API Docs
+
+The `api/html/` and `api/fastify/` directories are generated by TypeDoc on each build. Do
+not edit the generated `.md` files. To improve output, update JSDoc comments in the source
+and mark internal helpers with `@internal`.
+
+Each generated directory has a `_meta.json` that persists across builds. Remove `"index"`
+from these files to hide the module-list landing pages from the sidebar.
+
+## Adding a New Page
+
+1. Create the `.md` file in the correct directory
+2. Add the filename (without `.md`) to the directory's `_meta.json`
+3. If creating a new directory, create a `_meta.json` inside it and add a dir entry in the
+   parent's `_meta.json`
+
+## Writing Style
+
+Professional and technical. Direct, concise, information-dense. No filler, no motivational
+language, no repetition.
+
+- No emojis anywhere
+- No em dashes. Use periods, commas, or rephrase
+- No decorative separators or horizontal rules
+- No excessive bold formatting
+- No "Overview", "Introduction", or "Conclusion" as section headings unless truly
+  necessary
+- Maximum 2-4 headings (##) per page
+- Prefer short paragraphs over bullet lists. Maximum 5 bullet points per page
+- Only include code blocks when essential to understand usage
+- Keep pages under 800 words unless complexity requires more
+- Inline code only for identifiers, types, and short code references
+
+## Code Blocks
+
+Rspress uses Shiki for syntax highlighting with several features available.
+
+**Language identifier**: Always specify the language after the opening backticks: `tsx`,
+`ts`, `json`, `bash`, `html`, `css`, `js`.
+
+**Titles**: Use the `title` attribute for filenames and descriptive labels. Always add
+titles to config file examples and when the file path helps the reader understand context.
+
+````
+```json title="tsconfig.json"
+{ "compilerOptions": { "jsx": "react-jsx" } }
+```
+````
+
+**Line highlighting**: Use `// [!code highlight]` at the end of a line, or
+`// [!code highlight:N]` for N consecutive lines.
+
+**Diff notation**: Use `// [!code ++]` and `// [!code --]` for additions and removals.
+
+**Focus**: Use `// [!code focus]` to dim surrounding lines.
+
+**Error/warning**: Use `// [!code error]` and `// [!code warning]` for annotations.
+
+Line numbers are enabled globally and do not need per-block configuration.
+
+## Package Install Commands
+
+For install commands, use the `PackageManagerTabs` component instead of plain bash code
+blocks. This renders a tabbed selector for npm, yarn, pnpm, and bun.
+
+Add the import at the top of the `.mdx` file (Rename from `.md` to `.mdx` if needed):
+
+```
+import { PackageManagerTabs } from '@rspress/core/theme-original';
+```
+
+Then use the component:
+
+```
+<PackageManagerTabs command={{
+  npm: 'npm i @kitajs/html @kitajs/ts-html-plugin',
+  yarn: 'yarn add @kitajs/html @kitajs/ts-html-plugin',
+  pnpm: 'pnpm add @kitajs/html @kitajs/ts-html-plugin',
+  bun: 'bun add @kitajs/html @kitajs/ts-html-plugin',
+}} />
+```
+
+Only use this for user-facing install commands. Internal dev commands (`pnpm build`, etc.)
+stay as plain bash blocks.
+
+## Type Extension Setup
+
+When documenting type extensions (HTMX, Alpine.js, Turbo, all-types), instruct users to
+create a `src/kita.d.ts` file with triple-slash directives. Multiple extensions go in the
+same file. Do not suggest per-file directives as the primary approach.
+
+## Markdown Compatibility
+
+All markdown must be Rspress compatible:
+
+- Use standard markdown links: `[text](/path/to/page)`
+- Internal links use absolute paths from docs root: `/guide/introduction`, `/api/core`
+- React component imports go at the very top of the file, before the heading
+- No raw HTML in markdown unless absolutely necessary
+- Tables use standard markdown pipe syntax
+
+## Verification
+
+After writing or editing any page:
+
+1. Run `pnpm format` to apply Prettier formatting
+2. Run `pnpm -F @kitajs/docs-html build` to verify the site compiles
+3. Check that the build exits with code 0 and no errors
+
+## Section-Specific Conventions
+
+**XSS section**: Solution-first ordering. Safe attribute and detection tooling before the
+"why not auto-escape" explanation.
+
+**API section**: XSS tooling documented by capability (analysis engine, editor plugin, CLI
+scanner) not by package name. This anticipates the ts-html-plugin package split.
+
+**Integrations section**: Split into Frameworks (with official plugins) and Type
+Extensions (HTMX, Alpine, Turbo). When mentioning specific frameworks, link to the
+integrations overview rather than just naming one framework.