WIP: Kita Html v5.0.0

[arthurfiorette]

This pull request introduces significant improvements to CI/CD workflows, documentation tooling, and package configuration. The CI pipeline now supports broader Node.js versions and operating systems, adds a dedicated docs deployment job, and optimizes build caching. Documentation quality is enhanced with new agent and skill files enforcing strict writing and structuring conventions. Several package changesets address test coverage, CLI reliability, and plugin improvements.

CI/CD Workflow Enhancements

• Expanded CI matrix to cover multiple Node.js LTS versions and all major OSes, improving test coverage and reliability (.github/workflows/ci.yml).
• Added a dedicated deploy-docs job for automatic documentation deployment to GitHub Pages on master and next branches (.github/workflows/ci.yml).
• Introduced turbo build caching to CI and release workflows for faster builds (.github/workflows/ci.yml, .github/workflows/release.yml) [1] [2].
• Removed the unused CodeQL workflow, streamlining CI configuration (.github/workflows/codeql.yml).

Documentation Tooling and Standards

• Added a new docs-writer agent and two skill files (information-mapping, rspress-writing) to enforce structured writing and Rspress conventions for documentation (.claude/agents/docs-writer/CLAUDE.md, .claude/skills/information-mapping/SKILL.md, .claude/skills/rspress-writing/SKILL.md, .claude/skills/rspress-writing/style-examples.md) [1] [2] [3] [4].

Package Configuration Improvements

• Updated .changeset/config.json to ignore additional example and docs packages in dependency updates, reducing unnecessary changes.

Package Changesets

• Broadened and improved test suite for @kitajs/html, removed deprecated @kitajs/html/register, and initiated a major overhaul (.changeset/slimy-wolves-buy.md, .changeset/stale-shrimps-spend.md, .changeset/warm-seas-kiss.md) [1] [2] [3].
• Improved CLI reliability, XSS detection, and multiline TSServer message support in @kitajs/ts-html-plugin (.changeset/metal-hairs-juggle.md, .changeset/metal-corners-type.md, .changeset/hip-trams-roll.md) [1] [2] [3].

[Copilot]

Pull request overview

This PR is a WIP v5 pre-release overhaul that modernizes the monorepo’s build/test tooling (Turbo + Vitest), adds a docs site and deployment pipeline, and migrates runtime packages toward TS-first source with updated exports and APIs.

Changes:

• Reworked CI/release workflows (expanded matrix, turbo caching, GitHub Pages docs deploy, removed CodeQL).
• Converted @kitajs/html and @kitajs/fastify-html-plugin tests/build to Vitest + TS-first sources; introduced new TS JSX runtimes and ErrorBoundary implementation.
• Added a new docs package (Rspress + custom theme/plugins) and updated examples/benchmarks to match new build tooling.

Reviewed changes

Copilot reviewed 218 out of 268 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
packages/html/test/style.test.tsx	Migrates tests to Vitest and snapshots; updates imports to new TS-first entrypoints.
packages/html/test/simple-html.test.tsx	Converts assertions to Vitest snapshots and expands basic HTML coverage.
packages/html/test/register.test.tsx	Removes global register behavior tests aligned with API removal.
packages/html/test/html-standards.test.tsx	Removes standalone standards test (select) now covered elsewhere.
packages/html/test/hotwire-turbo.test.tsx	Migrates Turbo type-extension tests to Vitest snapshots.
packages/html/test/error-boundary.test.tsx	Migrates ErrorBoundary tests to Vitest; aligns with new TS implementation path.
packages/html/test/encoding.test.tsx	Updates encoding tests to Vitest; reduces coverage scope.
packages/html/test/components.test.tsx	Removes component helper tests (coverage impact).
packages/html/test/async.test.tsx	Migrates async component tests to Vitest but weakens assertions.
packages/html/src/jsx-runtime.ts	Adds TS implementation of jsx/jsxs runtime used by react-jsx transform.
packages/html/src/jsx-dev-runtime.ts	Adds TS jsxDEV implementation for dev runtime compatibility.
packages/html/src/error-boundary.ts	Replaces type-only declarations with a concrete TS implementation.
packages/html/register.js	Removes deprecated global register entrypoint implementation.
packages/html/package.json	Bumps to 5.0.0-next.0, switches exports to dist/, updates scripts/deps.
packages/html/jsx.js	Removes deprecated shim entrypoint.
packages/html/jsx-runtime.js	Removes legacy JS runtime implementation in favor of TS build output.
packages/html/jsx-dev-runtime.js	Removes legacy JS dev runtime implementation.
packages/html/htmx.js	Removes deprecated shim entrypoint.
packages/html/hotwire-turbo.js	Removes deprecated shim entrypoint.
packages/html/error-boundary.js	Removes legacy JS ErrorBoundary (replaced by TS output).
packages/html/alpine.js	Removes deprecated shim entrypoint.
packages/html/all-types.js	Removes no-op JS entrypoint for type-only extension.
packages/html/LICENSE	Replaces package LICENSE contents with a relative pointer to repo license (packaging risk).
packages/html/CHANGELOG.md	Adds v5.0.0-next.0 changelog entries.
packages/html/.npmignore	Removes ignore file (moves to files whitelist in package.json).
packages/fastify-html-plugin/types/index.test-d.tsx	Removes tsd-style type test file (replaced by Vitest type tests).
packages/fastify-html-plugin/tsconfig.json	Updates TS config to nodenext + narrows include paths to src/test.
packages/fastify-html-plugin/tsconfig.build.json	Adds dedicated build tsconfig for TS output.
packages/fastify-html-plugin/test/types.test-d.tsx	Adds Vitest-based type assertions for plugin API.
packages/fastify-html-plugin/test/index.test.tsx	Migrates runtime tests to Vitest; updates async JSX handling.
packages/fastify-html-plugin/test/auto-doctype.test.tsx	Adds explicit tests for auto-doctype behavior variants.
packages/fastify-html-plugin/test/auto-detect.test.tsx	Removes old node:test-based auto-doctype test.
packages/fastify-html-plugin/src/utils.ts	Introduces kAutoDoctype symbol + isTagHtml helper.
packages/fastify-html-plugin/src/plugin.ts	Adds TS Fastify plugin with module augmentation and documented API.
packages/fastify-html-plugin/src/index.ts	Adds TS entrypoint re-exporting plugin and utilities.
packages/fastify-html-plugin/src/html.ts	Adds TS reply.html() implementation including Suspense streaming.
packages/fastify-html-plugin/package.json	Bumps to 5.0.0-next.0, adds build, switches types/main to dist, updates deps.
packages/fastify-html-plugin/index.js	Removes legacy JS implementation in favor of TS dist/.
packages/fastify-html-plugin/README.md	Updates package branding/content and documents per-request doctype disabling.
packages/fastify-html-plugin/LICENSE	Replaces package LICENSE contents with a relative pointer to repo license (packaging risk).
packages/fastify-html-plugin/CHANGELOG.md	Adds v5.0.0-next.0 changelog entries.
packages/docs/typedoc.json	Adds TypeDoc config file for docs build tooling.
packages/docs/tsconfig.typedoc.json	Adds TS config for TypeDoc path mappings to workspace sources.
packages/docs/tsconfig.json	Adds docs package TS config for Rspress/theme/plugins.
packages/docs/theme/index.tsx	Adds custom Rspress theme layout/hero/banner wiring.
packages/docs/theme/index.css	Adds docs theme styling and brand variables.
packages/docs/theme/components/KitaCodeBlock.module.scss	Adds custom code block styles for rendered output UI.
packages/docs/theme/components/Banner.tsx	Adds pre-release banner component.
packages/docs/theme/components/Banner.module.scss	Adds banner styles (includes unused .close).
packages/docs/plugins/kita/renderer.ts	Adds build-time TSX rendering to HTML via vm + prettier formatting.
packages/docs/plugins/kita/remarkPlugin.ts	Adds remark plugin to transform tsx/jsx code blocks with kita meta.
packages/docs/plugins/kita/highlighter.ts	Adds Shiki-based HTML highlighting with a CSS variables theme.
packages/docs/package.json	Introduces docs package with Rspress and related tooling deps.
packages/docs/docs/integrations/type-extensions/htmx.md	Adds HTMX type-extension docs page.
packages/docs/docs/integrations/type-extensions/hotwire-turbo.md	Adds Hotwire Turbo type-extension docs page.
packages/docs/docs/integrations/type-extensions/alpine.md	Adds Alpine.js type-extension docs page.
packages/docs/docs/integrations/type-extensions/_meta.json	Adds sidebar ordering for type-extensions section.
packages/docs/docs/integrations/overview.md	Adds integrations overview page.
packages/docs/docs/integrations/frameworks/fastify.mdx	Adds Fastify integration docs page.
packages/docs/docs/integrations/frameworks/elysia.mdx	Adds Elysia integration docs page.
packages/docs/docs/integrations/frameworks/_meta.json	Adds sidebar ordering for framework integrations section.
packages/docs/docs/integrations/base-templates.md	Adds base templates guide page.
packages/docs/docs/integrations/_meta.json	Adds integrations section navigation structure.
packages/docs/docs/index.md	Adds docs homepage frontmatter + marketing copy.
packages/docs/docs/guide/xss/why-not-auto-escape.md	Adds principle page for XSS design tradeoff.
packages/docs/docs/guide/xss/scanner-cli.md	Adds procedure page for running the scanner CLI.
packages/docs/docs/guide/xss/safety-rules.md	Adds principle/reference page for safety rules.
packages/docs/docs/guide/xss/detection.md	Adds process page explaining how detection works.
packages/docs/docs/guide/xss/_meta.json	Adds sidebar ordering for XSS section.
packages/docs/docs/guide/reference/migrating-from-html.md	Adds migration guide page.
packages/docs/docs/guide/reference/compatibility.md	Adds compatibility reference page.
packages/docs/docs/guide/reference/benchmarks.md	Adds benchmark results and methodology.
packages/docs/docs/guide/reference/additional-config.md	Adds config reference including formatting and legacy JSX transform.
packages/docs/docs/guide/reference/_meta.json	Adds sidebar ordering for reference section.
packages/docs/docs/guide/jsx/syntax.md	Adds JSX syntax guide page.
packages/docs/docs/guide/jsx/extending-types.md	Adds JSX types extension guide page.
packages/docs/docs/guide/jsx/_meta.json	Adds sidebar ordering for JSX guide section.
packages/docs/docs/guide/how-jsx-becomes-html.mdx	Adds process page describing compilation/runtime steps.
packages/docs/docs/guide/getting-started.mdx	Adds getting started procedure page.
packages/docs/docs/guide/design-decisions.md	Adds design decisions rationale page.
packages/docs/docs/guide/async/using-suspense.md	Adds Suspense usage procedure page.
packages/docs/docs/guide/async/suspense.md	Adds Suspense concept page.
packages/docs/docs/guide/async/streaming-internals.md	Adds streaming internals process page.
packages/docs/docs/guide/async/error-boundaries.md	Adds ErrorBoundary guide page.
packages/docs/docs/guide/async/async-components.md	Adds async components concept page.
packages/docs/docs/guide/async/_meta.json	Adds sidebar ordering for async section.
packages/docs/docs/guide/_meta.json	Adds overall guide section navigation.
packages/docs/docs/api/xss-analysis.md	Documents XSS engine API at a high level.
packages/docs/docs/api/scanner-cli.md	Documents CLI scanner interface and exit codes.
packages/docs/docs/api/index.md	Adds API reference landing page.
packages/docs/docs/api/html/_meta.json	Adds sidebar structure for TypeDoc-generated html API pages.
packages/docs/docs/api/fastify/_meta.json	Adds sidebar structure for TypeDoc-generated fastify API pages.
packages/docs/docs/api/editor-plugin.md	Adds editor plugin documentation page.
packages/docs/docs/api/_meta.json	Adds API section navigation.
packages/docs/docs/_nav.json	Adds top-level docs navigation.
packages/docs/.gitignore	Ignores TypeDoc-generated API markdown outputs.
package.json	Switches to Turbo workflows; updates engines and publish scripts.
examples/http-server/tsconfig.json	Adds example TS config aligned with react-jsx import source.
examples/http-server/src/templates/Layout.tsx	Adds example layout demonstrating doctype + template composition.
examples/http-server/src/server.ts	Adds streaming HTTP server example using Suspense stream.
examples/http-server/package.json	Adds standalone example package configuration.
examples/http-server.tsx	Removes old single-file HTTP server example.
examples/fastify-htmx/tsconfig.json	Adds example TS config aligned with new toolchain.
examples/fastify-htmx/src/templates/Layout.tsx	Adds HTMX Fastify layout example.
examples/fastify-htmx/src/store.ts	Adds in-memory store for example app.
examples/fastify-htmx/src/server.tsx	Adds server factory registering fastify + formbody + kita plugin.
examples/fastify-htmx/src/index.ts	Adds example entrypoint for running server.
examples/fastify-htmx/src/api/todos.tsx	Adds HTMX todo endpoints returning partial HTML via reply.html().
examples/fastify-htmx/src/api/misc.tsx	Adds miscellaneous endpoints used by HTMX dashboard widgets.
examples/fastify-htmx/package.json	Adds standalone example package configuration.
examples/fastify-htmx.tsx	Removes old single-file fastify+htmx example.
examples/README.md	Adds examples index documentation.
benchmarks/vhtml/tsconfig.json	Updates benchmark TS config toward nodenext and tsgo.
benchmarks/vhtml/package.json	Switches build to tsgo and updates deps to catalog.
benchmarks/vhtml/index.tsx	Adjusts benchmark HTML structure consistency (head/body composition).
benchmarks/typed-html/tsconfig.json	Updates benchmark TS config toward nodenext and tsgo.
benchmarks/typed-html/package.json	Switches build to tsgo and updates deps to catalog.
benchmarks/typed-html/index.tsx	Adjusts benchmark HTML structure consistency.
benchmarks/templates/tsconfig.json	Updates TS config and include pattern for templates bench.
benchmarks/templates/package.json	Switches build to tsgo and updates deps to catalog.
benchmarks/templates/normal.ts	Updates template tag usage and head markup structure.
benchmarks/templates/ghtml.ts	Updates template output structure consistency.
benchmarks/runner/samples/vHtml.html	Updates expected sample HTML to match new head structure.
benchmarks/runner/samples/TypedHtml.html	Updates expected sample HTML to match new head structure.
benchmarks/runner/samples/ReactJsx.html	Updates expected sample HTML to match new head structure.
benchmarks/runner/samples/React.html	Updates expected sample HTML to match new head structure.
benchmarks/runner/samples/Preact.html	Updates expected sample HTML to match new head structure.
benchmarks/runner/samples/KitaJs.html	Updates expected sample HTML to match new head structure.
benchmarks/runner/samples/Jsxte.html	Updates expected sample HTML to match new head structure.
benchmarks/runner/samples/HonoJsx.html	Updates expected sample HTML to match new head structure.
benchmarks/runner/samples/HonoHtml.html	Updates expected sample HTML to match new head structure.
benchmarks/runner/samples/Ghtml.html	Updates expected sample HTML to match new head structure.
benchmarks/runner/samples/CommonTags.html	Updates expected sample HTML to match new head structure.
benchmarks/runner/package.json	Adds explicit benchmark script and updates dependency versions.
benchmarks/runner/lib/profile.js	Tweaks profiling loop counts and dataset size.
benchmarks/reactjsx/tsconfig.json	Updates TS config toward nodenext and tsgo.
benchmarks/reactjsx/package.json	Switches build to tsgo and updates deps to catalog.
benchmarks/reactjsx/index.tsx	Adjusts benchmark HTML structure consistency.
benchmarks/react/tsconfig.json	Updates TS config toward nodenext and tsgo.
benchmarks/react/package.json	Switches build to tsgo and updates deps to catalog.
benchmarks/react/index.tsx	Adjusts benchmark HTML structure consistency.
benchmarks/preact/tsconfig.json	Updates TS config toward nodenext and tsgo.
benchmarks/preact/package.json	Switches build to tsgo and bumps preact version.
benchmarks/preact/index.tsx	Adjusts benchmark HTML structure consistency.
benchmarks/kitajs/tsconfig.json	Updates TS config toward nodenext and tsgo.
benchmarks/kitajs/package.json	Switches build to tsgo and updates deps to catalog.
benchmarks/kitajs/index.tsx	Adjusts benchmark HTML structure consistency.
benchmarks/jsxte/tsconfig.json	Updates TS config toward nodenext and tsgo.
benchmarks/jsxte/package.json	Switches build to tsgo and updates deps to catalog.
benchmarks/jsxte/index.tsx	Adjusts benchmark HTML structure consistency.
benchmarks/honojsx/tsconfig.json	Updates TS config toward nodenext and tsgo.
benchmarks/honojsx/package.json	Switches build to tsgo and updates deps versions.
benchmarks/honojsx/index.tsx	Adjusts benchmark HTML structure consistency.
README.md	Updates repo branding and points to new docs site; warns about next branch.
.vscode/settings.json	Adds workspace TS settings, formatting defaults, and status bar colors.
.serena/memories/task_completion_checklist.md	Adds contributor checklist for build/test/XSS practices.
.serena/memories/suggested_commands.md	Adds suggested commands reference for contributors.
.serena/memories/project_overview.md	Adds project overview documentation.
.serena/memories/code_style_and_conventions.md	Adds style/conventions reference.
.serena/.gitignore	Ignores Serena cache.
.prettierrc.js	Updates Prettier config to disable semicolons (docs-friendly).
.github/workflows/release.yml	Extends release to next branch, adds turbo cache and dynamic publish tag.
.github/workflows/codeql.yml	Removes CodeQL workflow.
.github/workflows/ci.yml	Expands CI matrix and adds docs deployment to GitHub Pages.
.claude/skills/rspress-writing/style-examples.md	Adds documentation style examples guidance.
.claude/skills/information-mapping/SKILL.md	Adds structured writing methodology guidance.
.claude/agents/docs-writer/CLAUDE.md	Adds docs writer agent configuration.
.changeset/tender-regions-cough.md	Adds changeset for ts-html-plugin error code rework.
.changeset/stale-shrimps-spend.md	Adds changeset for removing deprecated register API.
.changeset/slimy-wolves-buy.md	Adds changeset for expanded test suite.
.changeset/sharp-wombats-stay.md	Adds major overhaul changeset.
.changeset/pre.json	Adds pre-release config tagging versions as next.
.changeset/metal-hairs-juggle.md	Adds changeset for CLI reliability changes.
.changeset/metal-corners-type.md	Adds changeset for multiline messages + XSS detection improvements.
.changeset/hip-trams-roll.md	Adds changeset for XSS check edge case handling.
.changeset/fix-double-escape-self-closing.md	Adds changeset describing TS88602 fix details.
.changeset/config.json	Updates changeset ignore list to exclude examples/docs from dependency bumps.
.changeset/calm-bears-remain.md	Adds changeset for Fragment safe attribute behavior.

Comments suppressed due to low confidence (3)

.github/workflows/ci.yml:37

• actions/checkout@v6 is not a valid release (checkout is currently v4). Pin to an existing major version (e.g. actions/checkout@v4) to avoid workflow failures.

      - name: Checkout
        uses: actions/checkout@v6

packages/html/test/encoding.test.tsx:1

• This file previously covered additional critical encoding behaviors (e.g., & handling and Date attribute serialization). Those behaviors appear untested after this change. Reintroduce equivalent cases (either here or in a dedicated test) to avoid regressions in escaping/serialization.

import { describe, expect, test } from 'vitest';

packages/fastify-html-plugin/LICENSE:1

• Same issue as packages/html/LICENSE: a relative path string is not a usable license file when published. Include the full license text in this package or ensure the license content is included in the published artifact.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The deploy-docs job pins Node 20, but the repo root package.json now requires Node >= 24. This will likely cause docs builds/installs to fail or behave inconsistently versus CI. Use a Node version that satisfies the root engine constraint (or relax the engine constraint if Node 20 must remain supported).

Suggested change

	node-version: 20
	node-version: 24

[Copilot]

Root engines were bumped to Node >= 24, but CI runs lts/-2 and lts/-1 (likely including Node 20/22 depending on current LTS lineup). Either update CI matrix to only versions satisfying >=24, or lower the engine requirement to match the intended supported range.

Suggested change

	"node": ">=24",
	"node": ">=20",

[Copilot]

Transfer-Encoding: identity is not a valid/standard Transfer-Encoding value for HTTP/1.1 responses, and can cause interoperability issues. For non-streaming responses, rely on Content-Length (and let Node/Fastify omit Transfer-Encoding) instead of setting transfer-encoding explicitly.

Suggested change

.header('transfer-encoding', 'identity')

[Copilot]

Passing (props.error || HtmlTimeout).reject as a bare callback can lose the method receiver for non-static implementations (i.e., reject that relies on this). Wrap the call so reject() is invoked on the selected object/class (e.g., via a lambda) to preserve semantics.

Suggested change

	setTimeout(props.timeout).then((props.error || HtmlTimeout).reject)
	setTimeout(props.timeout).then(() => (props.error || HtmlTimeout).reject())

[Copilot]

Correct spelling in JSDoc tag: @retuns -> @returns.

Suggested change

	* @retuns The generated html string or a promise that resolves to the generated html string
	* @returns The generated html string or a promise that resolves to the generated html string

[Copilot]

Replacing the package LICENSE with a relative path string will ship an invalid license file in the published package tarball (the path won't resolve on npm). Keep the full license text in packages/html/LICENSE (or ensure the actual license file is included in package files and referenced appropriately).

[Copilot]

Package-level Node engine (>=12) conflicts with the repo-level Node requirement (>=24) and the v5 docs stating Node 20.13+. This mismatch can lead to installs on unsupported runtimes. Align packages/html engines with actual supported Node versions for v5.

Suggested change

	"node": ">=12"
	"node": ">=20.13.0"

[Copilot]

Executing docs code in vm.runInContext is a high-risk pattern for CI (untrusted MDX/TSX can run during builds, including infinite loops/CPU exhaustion and potential sandbox escapes). At minimum, set an execution timeout and disable code generation in the context options; consider running this renderer in a separate process with strict resource limits.

Suggested change

	const context = vm.createContext({
	Html,
	html: undefined,
	exports: {},
	module: { exports: {} },
	require: (id: string) => {
	if (id === '@kitajs/html/jsx-runtime') {
	return JsxRuntime
	}
	if (id === '@kitajs/html') {
	return Html
	}
	if (id === '@kitajs/html/suspense') {
	return Suspense
	}
	throw new Error(`Cannot require '${id}' in sandboxed code`)
	}
	})
	vm.runInContext(transpiled.outputText, context, {
	filename: 'kita-code-block.js'
	const context = vm.createContext(
	{
	Html,
	html: undefined,
	exports: {},
	module: { exports: {} },
	require: (id: string) => {
	if (id === '@kitajs/html/jsx-runtime') {
	return JsxRuntime
	}
	if (id === '@kitajs/html') {
	return Html
	}
	if (id === '@kitajs/html/suspense') {
	return Suspense
	}
	throw new Error(`Cannot require '${id}' in sandboxed code`)
	}
	},
	{
	codeGeneration: {
	strings: false,
	wasm: false
	}
	}
	)
	vm.runInContext(transpiled.outputText, context, {
	filename: 'kita-code-block.js',
	timeout: 1000

[Copilot]

The exported name highligherPromise looks like a typo and can propagate through the codebase/API surface. Rename to highlighterPromise (and update import sites) for clarity.

Suggested change

	export const highligherPromise = createHighlighter({
	export const highlighterPromise = createHighlighter({

[Copilot]

.close is defined but Banner.tsx doesn't render any close button or reference styles.close. Either implement the close UI (if intended) or remove the unused styles to avoid dead CSS in the docs bundle.

Suggested change

	.close {
	position: absolute;
	right: 1rem;
	top: 50%;
	transform: translateY(-50%);
	background: none;
	border: none;
	cursor: pointer;
	font-size: 1.25rem;
	line-height: 1;
	color: var(--rp-c-text-2);
	padding: 0.25rem 0.5rem;
	&:hover {
	color: var(--rp-c-text-1);
	}
	}

[tomasstrejcek]

any ETA on this? can you include typescript 6 support? thanks
if you need beta testers let me know

[arthurfiorette]

typescript 6 is already supported in kita this next branch. You can install the next version using @next

https://www.npmjs.com/package/@kitajs/html?activeTab=versions