WIP: Kita Html v5.0.0

.changeset/calm-bears-remain.md

@@ -0,0 +1,5 @@
+---
+'@kitajs/html': patch
+---
+
+Add safe attribute to Fragment component

.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/fix-double-escape-self-closing.md

@@ -0,0 +1,13 @@
+---
+'@kitajs/ts-html-plugin': patch
+---
+
+Fix double escape detection for self-closing components and JSX in expressions
+
+The TS88602 DoubleEscape error was not being triggered for self-closing components like
+`<UserBadge />` when used as direct children of elements with the `safe` attribute, or
+when used within expressions (ternary operators, binary operators).
+
+This fix ensures that all JSX types (elements with opening/closing tags, self-closing
+elements, and fragments) are properly detected in both direct children and expression
+contexts, preventing double-escaped HTML output that would corrupt markup.

.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/pre.json

@@ -0,0 +1,33 @@
+{
+  "mode": "pre",
+  "tag": "next",
+  "initialVersions": {
+    "@kitajs/bench-html-honojsx": "1.0.0",
+    "@kitajs/bench-html-jsxte": "1.0.0",
+    "@kitajs/bench-html-kitajs": "1.0.0",
+    "@kitajs/bench-html-preact": "1.0.0",
+    "@kitajs/bench-html-react": "1.0.0",
+    "@kitajs/bench-html-reactjsx": "1.0.0",
+    "@kitajs/bench-html-runner": "1.0.0",
+    "@kitajs/bench-html-templates": "1.0.0",
+    "@kitajs/bench-html-typed-html": "1.0.0",
+    "@kitajs/bench-html-vhtml": "1.0.0",
+    "@kitajs/example-fastify-htmx": "1.0.0",
+    "@kitajs/example-http-server": "1.0.0",
+    "@kitajs/docs-html": "1.0.0",
+    "@kitajs/fastify-html-plugin": "4.2.1",
+    "@kitajs/html": "4.2.13",
+    "@kitajs/ts-html-plugin": "4.1.4"
+  },
+  "changesets": [
+    "calm-bears-remain",
+    "fix-double-escape-self-closing",
+    "hip-trams-roll",
+    "metal-corners-type",
+    "metal-hairs-juggle",
+    "sharp-wombats-stay",
+    "slimy-wolves-buy",
+    "stale-shrimps-spend",
+    "tender-regions-cough"
+  ]
+}

.changeset/sharp-wombats-stay.md

@@ -0,0 +1,9 @@
+---
+'@kitajs/fastify-html-plugin': major
+'@kitajs/ts-html-plugin': major
+'@kitajs/html': major
+---
+
+Major overhaul: Rework the entire codebase to improve performance, reliability, and
+maintainability. This includes porting all code to TypeScript, improving the test suite,
+and removing deprecated APIs.

.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/tender-regions-cough.md

@@ -0,0 +1,5 @@
+---
+'@kitajs/ts-html-plugin': minor
+---
+
+Rework all error codes

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

@@ -0,0 +1,99 @@
+---
+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 three 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, writing style, and UI components (Tabs, Steps,
+   PackageManagerTabs).
+
+3. **twoslash**: TwoSlash annotations for TypeScript code blocks. Use whenever a code
+   block should show inferred types (`^?`), errors, completions, cut markers, or emitted
+   output.
+
+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