@tsrx/mcp 0.0.3 → 0.0.4

package/README.md

@@ -30,8 +30,9 @@ stdio command. This monorepo includes a deployment-neutral endpoint app in
 `website-mcp` that serves the same MCP server at `/mcp`.
 
 The hosted endpoint runs in remote-safe mode. It exposes documentation, prompts,
-`format-tsrx`, `compile-tsrx`, and `analyze-tsrx`, but omits local filesystem
-tools such as `inspect-project`, `detect-target`, and `validate-tsrx-file`.
+`format-tsrx`, `compile-tsrx`, `analyze-tsrx`, and source-level authoring review
+tools, but omits local filesystem tools such as `inspect-project`,
+`detect-target`, and `validate-tsrx-file`.
 
 Set `TSRX_MCP_BEARER_TOKEN` in the endpoint environment to require bearer-token
 auth. Set `TSRX_MCP_CORS_ORIGIN` to restrict CORS for browser-based clients.
@@ -85,6 +86,13 @@ Add the generic config above to your Codex MCP configuration.
 - `format-tsrx` - format TSRX code using the official Prettier plugin.
 - `analyze-tsrx` - compile TSRX code and convert common diagnostics into
   target-neutral authoring advice with linked docs resources.
+- `review-tsrx-accessibility` - review TSRX source for common accessibility issues
+  before browser-based Axe validation, including missing button names, unlabeled
+  form controls, and visible text written in a non-rendering shape.
+- `review-tsrx-styles` - review component-scoped style usage for malformed style
+  blocks, broad selectors, root styling, and contrast risks.
+- `review-tsrx-components` - review component structure and suggest extraction
+  points when control flow, repeated templates, or styles become dense.
 - `validate-tsrx-file` - read a `.tsrx` file and run formatting, compilation, and
   diagnostic advice in one read-only pass.
 
@@ -98,6 +106,11 @@ For generated code, run `format-tsrx` first, then `compile-tsrx` with the inferr
 or explicit target. If compilation fails, run `analyze-tsrx`, apply the advice,
 format again, and compile again.
 
+For user-facing generated UI, run `review-tsrx-accessibility`,
+`review-tsrx-styles`, and `review-tsrx-components` before finalizing. These tools
+do not replace browser validation, but they catch common source-level mistakes
+before the more expensive build, serve, Axe, and visual review loop.
+
 For an existing `.tsrx` file, prefer `validate-tsrx-file`. It reads the file and
 runs formatting, compilation, and diagnostic advice in one read-only pass.
 

package/package.json

@@ -3,7 +3,7 @@
   "description": "MCP server for TSRX documentation and project context",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "repository": {
     "type": "git",
@@ -37,8 +37,8 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "prettier": "^3.8.3",
     "zod": "^4.3.6",
-    "@tsrx/core": "0.0.22",
-    "@tsrx/prettier-plugin": "0.3.42"
+    "@tsrx/core": "0.0.23",
+    "@tsrx/prettier-plugin": "0.3.43"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",

package/src/authoring.js

@@ -0,0 +1,489 @@
+/**
+ * @typedef {{
+ *   kind: string,
+ *   severity: 'error' | 'warning' | 'info',
+ *   title: string,
+ *   message: string,
+ *   snippet: string | null,
+ *   recommendation: string,
+ *   documentation: string[],
+ * }} AuthoringIssue
+ */
+
+const DEFAULT_FILENAME = 'Component.tsrx';
+
+/**
+ * @param {string | undefined} filename
+ */
+function normalize_filename(filename) {
+	return filename?.trim() || DEFAULT_FILENAME;
+}
+
+/**
+ * @param {string | undefined} target
+ */
+function normalize_target(target) {
+	return target?.trim() || null;
+}
+
+/**
+ * @param {string} value
+ */
+function escape_regexp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * @param {string} attrs
+ * @param {string} name
+ */
+function has_attribute(attrs, name) {
+	return new RegExp(`\\b${escape_regexp(name)}\\s*=`).test(attrs);
+}
+
+/**
+ * @param {string} attrs
+ * @param {string} name
+ */
+function get_attribute(attrs, name) {
+	const match = attrs.match(
+		new RegExp(`\\b${escape_regexp(name)}\\s*=\\s*("[^"]*"|'[^']*'|\\{[^}]+\\})`),
+	);
+	if (!match) return null;
+	const value = match[1];
+	if (
+		(value.startsWith('"') && value.endsWith('"')) ||
+		(value.startsWith("'") && value.endsWith("'"))
+	) {
+		return value.slice(1, -1);
+	}
+	return value;
+}
+
+/**
+ * @param {string} text
+ */
+function line_snippet(text) {
+	return (
+		text
+			.split('\n')
+			.map((line) => line.trim())
+			.find(Boolean)
+			?.slice(0, 240) ?? null
+	);
+}
+
+/**
+ * @param {string} inner
+ */
+function has_expression_text(inner) {
+	return (
+		/\{\s*(['"`])[\s\S]*?\1\s*\}/.test(inner) || /\{[A-Za-z0-9_$.[\]?!:'"`\s+-]+\}/.test(inner)
+	);
+}
+
+/**
+ * @param {string} inner
+ */
+function has_direct_quoted_text(inner) {
+	return /(^|>)\s*"[^"]+"\s*(<|$)/.test(inner);
+}
+
+/**
+ * @param {string} inner
+ */
+function has_visible_label_text(inner) {
+	const without_tags = inner.replace(/<[^>]+>/g, ' ');
+	return has_expression_text(inner) || /[A-Za-z0-9]/.test(without_tags.replace(/"[^"]*"/g, ''));
+}
+
+/**
+ * @param {string} code
+ * @param {string} id
+ */
+function find_label_for_id(code, id) {
+	const quoted = escape_regexp(id);
+	const label_pattern = new RegExp(
+		`<label\\b([^>]*)\\bhtmlFor\\s*=\\s*["']${quoted}["']([^>]*)>([\\s\\S]*?)<\\/label>`,
+		'g',
+	);
+	const match = label_pattern.exec(code);
+	return match ? match[0] : null;
+}
+
+/**
+ * @param {string} attrs
+ */
+function get_input_type(attrs) {
+	return (get_attribute(attrs, 'type') ?? 'text').replace(/[{}'"`]/g, '').toLowerCase();
+}
+
+/**
+ * @param {string} code
+ */
+function collect_direct_quoted_text_issues(code) {
+	/** @type {AuthoringIssue[]} */
+	const issues = [];
+	const direct_text_regex = /<([a-z][\w.-]*)(\s[^>]*)?>\s*"([^"]+)"\s*<\/\1>/g;
+	for (const match of code.matchAll(direct_text_regex)) {
+		issues.push({
+			kind: 'direct-quoted-text',
+			severity: match[1] === 'button' ? 'error' : 'warning',
+			title: 'Use expression text for visible TSRX text',
+			message:
+				'Direct quoted text inside TSRX elements can be treated as a JavaScript string statement instead of rendered text in some target output.',
+			snippet: line_snippet(match[0]),
+			recommendation: `Replace it with expression text, for example <${match[1]}>{'${match[3].replace(/'/g, "\\'")}'}</${match[1]}>.`,
+			documentation: ['tsrx://docs/text-and-template-expressions.md'],
+		});
+	}
+	return issues;
+}
+
+/**
+ * Reviews generated TSRX source for common accessibility mistakes that are cheap
+ * to catch before a browser-based Axe run.
+ *
+ * @param {{ code: string, filename?: string, target?: string }} input
+ */
+export function review_tsrx_accessibility(input) {
+	const filename = normalize_filename(input.filename);
+	const target = normalize_target(input.target);
+	/** @type {AuthoringIssue[]} */
+	const issues = [...collect_direct_quoted_text_issues(input.code)];
+
+	const button_regex = /<button\b([^>]*)>([\s\S]*?)<\/button>/g;
+	for (const match of input.code.matchAll(button_regex)) {
+		const attrs = match[1] ?? '';
+		const inner = match[2] ?? '';
+		const has_name =
+			has_attribute(attrs, 'aria-label') ||
+			has_attribute(attrs, 'aria-labelledby') ||
+			has_attribute(attrs, 'title') ||
+			(has_expression_text(inner) && !/^\s*\{\s*['"`]\s*['"`]\s*\}\s*$/.test(inner));
+
+		if (!has_name || has_direct_quoted_text(inner)) {
+			issues.push({
+				kind: 'button-accessible-name',
+				severity: 'error',
+				title: 'Give every button a stable accessible name',
+				message:
+					'Buttons must expose a visible label or an aria-label. This is especially important for disabled submit buttons and icon-only controls.',
+				snippet: line_snippet(match[0]),
+				recommendation:
+					"Use visible expression text such as {'Add task'} or add aria-label for icon-only buttons.",
+				documentation: ['tsrx://docs/text-and-template-expressions.md'],
+			});
+		}
+	}
+
+	const input_regex = /<input\b([^>]*)\/?>/g;
+	for (const match of input.code.matchAll(input_regex)) {
+		const attrs = match[1] ?? '';
+		const type = get_input_type(attrs);
+		if (type === 'hidden' || type === 'submit' || type === 'button') continue;
+
+		const has_direct_name =
+			has_attribute(attrs, 'aria-label') ||
+			has_attribute(attrs, 'aria-labelledby') ||
+			has_attribute(attrs, 'title');
+		if (has_direct_name) continue;
+
+		const id = get_attribute(attrs, 'id');
+		const label = id && !id.startsWith('{') ? find_label_for_id(input.code, id) : null;
+		const has_text_label = label ? has_visible_label_text(label) : false;
+		const needs_direct_name = type === 'checkbox' || type === 'radio' || !has_text_label;
+
+		if (needs_direct_name) {
+			issues.push({
+				kind: 'input-accessible-name',
+				severity: 'error',
+				title: 'Give every form control a readable label',
+				message:
+					type === 'checkbox' || type === 'radio'
+						? 'Checkboxes and radios used as visual toggles still need an accessible name. A decorative checkmark is not a label.'
+						: 'Inputs need a text label, aria-label, aria-labelledby, or title that remains in the rendered DOM.',
+				snippet: line_snippet(match[0]),
+				recommendation:
+					type === 'checkbox' || type === 'radio'
+						? "Add aria-label={todo.completed ? 'Mark task as incomplete' : 'Mark task as complete'} or include visible label text."
+						: 'Add a matching text label with htmlFor, or add aria-label when a visible label is not appropriate.',
+				documentation: ['tsrx://docs/components.md'],
+			});
+		}
+	}
+
+	return {
+		ok: issues.every((issue) => issue.severity !== 'error'),
+		filename,
+		target,
+		summary:
+			issues.length === 0
+				? 'No source-level TSRX accessibility issues were found. Still run browser-based Axe for final verification.'
+				: `Found ${issues.length} source-level accessibility issue${issues.length === 1 ? '' : 's'} to fix before final Axe verification.`,
+		issues,
+		nextSteps:
+			issues.length === 0
+				? ['Run browser-based Axe or the benchmark validation loop.']
+				: [
+						'Fix error-severity issues before returning code.',
+						'Prefer expression text for visible labels.',
+						'Run review-tsrx-accessibility again, then compile-tsrx and browser-based Axe.',
+					],
+	};
+}
+
+/**
+ * @param {string} hex
+ */
+function hex_to_rgb(hex) {
+	const value = hex.replace('#', '');
+	const expanded =
+		value.length === 3
+			? value
+					.split('')
+					.map((char) => char + char)
+					.join('')
+			: value;
+	if (!/^[0-9a-f]{6}$/i.test(expanded)) return null;
+	const int_value = Number.parseInt(expanded, 16);
+	return {
+		r: (int_value >> 16) & 255,
+		g: (int_value >> 8) & 255,
+		b: int_value & 255,
+	};
+}
+
+/**
+ * @param {number} channel
+ */
+function relative_channel(channel) {
+	const value = channel / 255;
+	return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+
+/**
+ * @param {{ r: number, g: number, b: number }} rgb
+ */
+function luminance(rgb) {
+	return (
+		0.2126 * relative_channel(rgb.r) +
+		0.7152 * relative_channel(rgb.g) +
+		0.0722 * relative_channel(rgb.b)
+	);
+}
+
+/**
+ * @param {string} foreground
+ * @param {string} background
+ */
+function contrast_ratio(foreground, background) {
+	const fg = hex_to_rgb(foreground);
+	const bg = hex_to_rgb(background);
+	if (!fg || !bg) return null;
+	const lighter = Math.max(luminance(fg), luminance(bg));
+	const darker = Math.min(luminance(fg), luminance(bg));
+	return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Reviews TSRX scoped style authoring for patterns that commonly produce invalid
+ * CSS, missing root styling, or preventable contrast failures.
+ *
+ * @param {{ code: string, filename?: string, target?: string }} input
+ */
+export function review_tsrx_styles(input) {
+	const filename = normalize_filename(input.filename);
+	const target = normalize_target(input.target);
+	/** @type {AuthoringIssue[]} */
+	const issues = [];
+	const style_blocks = [...input.code.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/g)];
+
+	if (style_blocks.length === 0) {
+		issues.push({
+			kind: 'missing-style-block',
+			severity: 'warning',
+			title: 'Prefer component-scoped styles',
+			message:
+				'Non-trivial TSRX components should usually keep component styles in a scoped <style> block next to the component template.',
+			snippet: null,
+			recommendation:
+				'Add a <style> block in the component and reserve global CSS for document-level resets.',
+			documentation: ['tsrx://docs/style-and-server.md'],
+		});
+	}
+
+	for (const style_match of style_blocks) {
+		const css = style_match[1] ?? '';
+		if (/^\s*\{/.test(css)) {
+			issues.push({
+				kind: 'style-expression-body',
+				severity: 'error',
+				title: 'Write CSS directly inside <style>',
+				message:
+					'A TSRX <style> block should contain CSS text, not a JavaScript template literal expression.',
+				snippet: line_snippet(style_match[0]),
+				recommendation: 'Replace <style>{`...`}</style> with <style> ...CSS... </style>.',
+				documentation: ['tsrx://docs/style-and-server.md'],
+			});
+		}
+
+		if (/(^|[{};,\s])(:global\(\*\)|\*)\s*\{/.test(css)) {
+			issues.push({
+				kind: 'universal-selector',
+				severity: 'warning',
+				title: 'Avoid universal selectors in scoped styles',
+				message:
+					'Universal selectors make generated examples harder to reason about and can leak broad styling assumptions into nested UI.',
+				snippet: line_snippet(css.match(/(:global\(\*\)|\*)\s*\{[^}]*\}/)?.[0] ?? css),
+				recommendation: 'Style the component root and named classes instead.',
+				documentation: ['tsrx://docs/style-and-server.md'],
+			});
+		}
+
+		if (/:scope\s*\{/.test(css)) {
+			issues.push({
+				kind: 'scope-root-style',
+				severity: /:scope\s*\{[\s\S]*\b(background|color|min-height|padding|display)\s*:/.test(css)
+					? 'error'
+					: 'warning',
+				title: 'Put app-level visuals on an explicit root class',
+				message:
+					'For generated app examples, app background, text color, and layout are more robust when attached to the rendered root class, such as .app-shell, rather than only :scope.',
+				snippet: line_snippet(css.match(/:scope\s*\{[^}]*\}/)?.[0] ?? ':scope'),
+				recommendation:
+					'Move root layout/background/color declarations onto the top-level rendered element class.',
+				documentation: ['tsrx://docs/style-and-server.md'],
+			});
+		}
+
+		if (/:scope\s*\{[\s\S]*background/.test(css)) {
+			const low_contrast_on_white = [...css.matchAll(/color\s*:\s*(#[0-9a-fA-F]{3,6})\b/g)]
+				.map((match) => ({ color: match[1], ratio: contrast_ratio(match[1], '#ffffff') }))
+				.filter((entry) => entry.ratio !== null && entry.ratio < 4.5);
+			if (low_contrast_on_white.length > 0) {
+				issues.push({
+					kind: 'contrast-risk-with-scope-background',
+					severity: 'error',
+					title: 'Avoid contrast depending only on :scope background',
+					message:
+						'Some text colors in this style block would fail contrast on a default light background if the :scope background does not apply to the rendered root.',
+					snippet: `Low-contrast-on-white colors: ${low_contrast_on_white
+						.map((entry) => `${entry.color} (${entry.ratio?.toFixed(2)}:1)`)
+						.join(', ')}`,
+					recommendation:
+						'Place the dark background and base text color on the explicit root class, and choose secondary text colors that pass WCAG contrast there.',
+					documentation: ['tsrx://docs/style-and-server.md'],
+				});
+			}
+		}
+	}
+
+	return {
+		ok: issues.every((issue) => issue.severity !== 'error'),
+		filename,
+		target,
+		summary:
+			issues.length === 0
+				? 'No source-level TSRX style issues were found.'
+				: `Found ${issues.length} source-level style issue${issues.length === 1 ? '' : 's'} to review.`,
+		issues,
+		nextSteps:
+			issues.length === 0
+				? ['Run compile-tsrx and browser validation for final CSS behavior.']
+				: [
+						'Fix error-severity style issues first.',
+						'Put root layout, background, and text color on an explicit rendered class.',
+						'Run review-tsrx-styles again, then validate in a browser.',
+					],
+	};
+}
+
+/**
+ * @param {string} code
+ */
+function get_component_body_line_count(code) {
+	const match = code.match(/export\s+component\s+\w+[^{]*\{([\s\S]*)\}\s*$/);
+	if (!match) return code.split('\n').length;
+	return match[1].split('\n').length;
+}
+
+/**
+ * Reviews TSRX source for component decomposition opportunities.
+ *
+ * @param {{ code: string, filename?: string, target?: string }} input
+ */
+export function review_tsrx_components(input) {
+	const filename = normalize_filename(input.filename);
+	const target = normalize_target(input.target);
+	/** @type {AuthoringIssue[]} */
+	const issues = [];
+	const body_lines = get_component_body_line_count(input.code);
+	const control_flow_count = (input.code.match(/\b(if|for|switch)\s*\(/g) ?? []).length;
+	const element_count = (input.code.match(/<[a-z][\w.-]*(\s|>|\/)/g) ?? []).length;
+	const style_line_count = [...input.code.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/g)].reduce(
+		(total, match) => total + (match[1] ?? '').split('\n').length,
+		0,
+	);
+
+	if (body_lines > 180 || element_count > 45) {
+		issues.push({
+			kind: 'large-component',
+			severity: 'warning',
+			title: 'Split large TSRX components into focused subcomponents',
+			message:
+				'The component is large enough that generated code is likely to become harder to repair, test, and review.',
+			snippet: `${body_lines} component-body lines, ${element_count} template elements.`,
+			recommendation:
+				'Extract cohesive pieces such as Header, StatsSummary, TodoComposer, TodoList, TodoItem, and EmptyState.',
+			documentation: ['tsrx://docs/components.md', 'tsrx://docs/control-flow.md'],
+		});
+	}
+
+	if (control_flow_count >= 4) {
+		issues.push({
+			kind: 'control-flow-depth',
+			severity: 'info',
+			title: 'Use subcomponents around repeated or branching UI',
+			message:
+				'Multiple control-flow blocks are fine in TSRX, but deeply branching generated examples become more reliable when repeated item UI is moved into a named component.',
+			snippet: `${control_flow_count} control-flow blocks detected.`,
+			recommendation:
+				'When a for-loop item contains buttons, labels, conditionals, or several nested elements, extract an item component and pass typed props/callbacks.',
+			documentation: ['tsrx://docs/components.md', 'tsrx://docs/control-flow.md'],
+		});
+	}
+
+	if (style_line_count > 180) {
+		issues.push({
+			kind: 'large-style-block',
+			severity: 'info',
+			title: 'Keep style blocks navigable',
+			message:
+				'Very large style blocks make generated components harder to audit for accessibility and responsive behavior.',
+			snippet: `${style_line_count} style lines detected.`,
+			recommendation:
+				'Group styles by extracted component or reduce decorative styling before adding more behavior.',
+			documentation: ['tsrx://docs/style-and-server.md'],
+		});
+	}
+
+	return {
+		ok: true,
+		filename,
+		target,
+		summary:
+			issues.length === 0
+				? 'No component decomposition issues were found.'
+				: `Found ${issues.length} component-structure recommendation${issues.length === 1 ? '' : 's'}.`,
+		issues,
+		nextSteps:
+			issues.length === 0
+				? ['Keep related hooks, handlers, and template branches co-located.']
+				: [
+						'Extract repeated list items and major page regions into named TSRX components.',
+						'Keep hooks and handlers near the branch or component that uses them.',
+						'Compile after extracting components to confirm target output.',
+					],
+	};
+}

package/src/generated/docs.js

@@ -56,9 +56,9 @@ export const documentation_sections = [
 		slug: 'style-and-server',
 		title: 'Style and Server Extensions',
 		use_cases:
-			'#style, scoped css, #server, server blocks, compile-time identifiers',
+			'style directive, scoped css, module server, submodule imports, compile-time identifiers',
 		content:
-			'# Style and Server Extensions\n\n`#style` is a compile-time identifier for scoped CSS class names declared in the current module.\n\n```tsx\n<div class={#style.card} />\n```\n\n`#server { ... }` marks a lexical region intended for server compile targets. TSRX parses the block; target compilers decide how to emit or strip it.\n\nSpecification grammar:\n\n```text\nStyleIdentifier :\n  #style\n\nStyleAccess :\n  #style . IdentifierName\n  #style [ StringLiteral ]\n\nServerIdentifier :\n  #server\n\nServerBlock :\n  #server { StatementListopt }\n\nServerMemberAccess :\n  #server . IdentifierName\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#style',
+			'# Style and Server Extensions\n\n`{style "className"}` is an attribute-value directive for scoped CSS class names declared in the current module.\n\n```tsx\n<Child className={style "card"} />\n```\n\n`module server { ... }` declares a server-oriented submodule in the Ripple host profile. Import exported functions with `import { load } from server` before use.\n\nSpecification grammar:\n\n```text\nStyleAttributeExpression :\n  { style StringLiteral }\n\nSubmoduleDeclaration :\n  module Identifier { ModuleItemListopt }\n\nSubmoduleImportDeclaration :\n  import ImportClause from Identifier ;\n\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#style',
 	},
 	{
 		slug: 'target-integration',

package/src/http.js

@@ -82,8 +82,15 @@ export async function handleTSRXMcpNodeRequest(req, res, options = {}) {
 	});
 
 	try {
+		const req_with_body = /** @type {import('node:http').IncomingMessage & { body?: unknown }} */ (
+			req
+		);
+		const parsed_body = Object.prototype.hasOwnProperty.call(req_with_body, 'body')
+			? req_with_body.body
+			: undefined;
+
 		await server.connect(transport);
-		await transport.handleRequest(req, res);
+		await transport.handleRequest(req, res, parsed_body);
 	} catch (error) {
 		if (!res.headersSent) {
 			send_json(res, 500, {

package/src/index.js

@@ -7,11 +7,19 @@ export {
 	get_documentation_handler,
 	inspect_project_handler,
 	list_sections_handler,
+	review_tsrx_accessibility_handler,
+	review_tsrx_components_handler,
+	review_tsrx_styles_handler,
 	validate_tsrx_file_handler,
 } from './server.js';
 
 export { handleTSRXMcpNodeRequest } from './http.js';
 export { analyze_tsrx } from './analyze.js';
+export {
+	review_tsrx_accessibility,
+	review_tsrx_components,
+	review_tsrx_styles,
+} from './authoring.js';
 export { compile_tsrx } from './compile.js';
 export { format_tsrx } from './format.js';
 export { inspect_project } from './inspect.js';

package/src/schemas.js

@@ -66,6 +66,25 @@ export const advice_schema = z.object({
 	documentation: z.array(z.string()),
 });
 
+export const authoring_issue_schema = z.object({
+	kind: z.string(),
+	severity: z.enum(['error', 'warning', 'info']),
+	title: z.string(),
+	message: z.string(),
+	snippet: z.string().nullable(),
+	recommendation: z.string(),
+	documentation: z.array(z.string()),
+});
+
+export const authoring_review_result_schema = {
+	ok: z.boolean(),
+	filename: z.string(),
+	target: z.string().nullable(),
+	summary: z.string(),
+	issues: z.array(authoring_issue_schema),
+	nextSteps: z.array(z.string()),
+};
+
 export const analysis_result_schema = {
 	ok: z.boolean(),
 	target: z.string().nullable(),

package/src/server.js

@@ -13,9 +13,15 @@ import { format_tsrx } from './format.js';
 import { inspect_project } from './inspect.js';
 import { validate_tsrx_file } from './validate.js';
 import { detect_target } from './target.js';
+import {
+	review_tsrx_accessibility,
+	review_tsrx_components,
+	review_tsrx_styles,
+} from './authoring.js';
 import {
 	TARGET_SCHEMA,
 	analysis_result_schema,
+	authoring_review_result_schema,
 	compile_result_schema,
 	format_result_schema,
 	inspect_project_result_schema,
@@ -193,6 +199,27 @@ export function analyze_tsrx_handler(input) {
 	return analyze_tsrx(input);
 }
 
+/**
+ * @param {{ code: string, filename?: string, target?: string }} input
+ */
+export function review_tsrx_accessibility_handler(input) {
+	return review_tsrx_accessibility(input);
+}
+
+/**
+ * @param {{ code: string, filename?: string, target?: string }} input
+ */
+export function review_tsrx_styles_handler(input) {
+	return review_tsrx_styles(input);
+}
+
+/**
+ * @param {{ code: string, filename?: string, target?: string }} input
+ */
+export function review_tsrx_components_handler(input) {
+	return review_tsrx_components(input);
+}
+
 /**
  * @param {{
  *   code: string,
@@ -270,18 +297,21 @@ function create_tsrx_task_prompt(options) {
 	const compile_step = options.remote
 		? '7. Before presenting generated .tsrx code as final, call `format-tsrx`, then `compile-tsrx` with an explicit target.'
 		: '7. Before presenting generated .tsrx code as final, call `format-tsrx`, then `compile-tsrx` with the inferred or explicit target.';
+	const authoring_step =
+		'8. For user-facing UI, call `review-tsrx-accessibility`, `review-tsrx-styles`, and `review-tsrx-components` before finalizing. Fix error-severity accessibility/style issues and use component advice when control flow becomes dense.';
 
 	return `Use this workflow when helping with TSRX:
 
 1. Identify whether the task is about target-neutral TSRX syntax, target runtime behavior, or both.
 ${project_context_step}
 3. For syntax uncertainty, use \`list-sections\`, \`get-documentation\`, or read \`tsrx://docs/{slug}.md\`.
-4. Keep core TSRX advice target-neutral: component declarations, statement templates, control flow, TSX expression values, lazy destructuring, style identifiers, and server blocks.
+4. Keep core TSRX advice target-neutral: component declarations, statement templates, control flow, TSX expression values, lazy destructuring, style identifiers, and submodule declarations.
 5. Use \`tsrx://targets/{target}.md\` as the handoff point for target-specific responsibilities.
 ${file_validation_step}
 ${compile_step}
-8. If \`compile-tsrx\` returns diagnostics, call \`analyze-tsrx\` for targeted authoring advice, fix the code, format it, and compile again.
-9. Do not invent runtime APIs, imports, or bundler configuration from target-neutral TSRX docs. Use target-specific docs, resources, or skills for those details.`;
+${authoring_step}
+9. If \`compile-tsrx\` returns diagnostics, call \`analyze-tsrx\` for targeted authoring advice, fix the code, format it, and compile again.
+10. Do not invent runtime APIs, imports, or bundler configuration from target-neutral TSRX docs. Use target-specific docs, resources, or skills for those details.`;
 }
 
 /**
@@ -564,6 +594,87 @@ export function createTSRXMcpServer(options = {}) {
 		},
 	);
 
+	server.registerTool(
+		'review-tsrx-accessibility',
+		{
+			title: 'Review TSRX Accessibility',
+			description:
+				'Reviews TSRX source for common accessibility issues before browser-based Axe validation, including missing button names, unlabeled form controls, and direct quoted text that may not render as accessible text.',
+			inputSchema: {
+				code: z.string(),
+				filename: z.string().optional(),
+				target: TARGET_SCHEMA.optional(),
+			},
+			outputSchema: authoring_review_result_schema,
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				openWorldHint: false,
+			},
+		},
+		async (input) => {
+			const output = review_tsrx_accessibility_handler(input);
+			return {
+				content: [{ type: 'text', text: json_text(output) }],
+				structuredContent: output,
+			};
+		},
+	);
+
+	server.registerTool(
+		'review-tsrx-styles',
+		{
+			title: 'Review TSRX Styles',
+			description:
+				'Reviews TSRX source for style-authoring issues, including malformed style blocks, broad selectors, root styling that should live on explicit classes, and contrast risks.',
+			inputSchema: {
+				code: z.string(),
+				filename: z.string().optional(),
+				target: TARGET_SCHEMA.optional(),
+			},
+			outputSchema: authoring_review_result_schema,
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				openWorldHint: false,
+			},
+		},
+		async (input) => {
+			const output = review_tsrx_styles_handler(input);
+			return {
+				content: [{ type: 'text', text: json_text(output) }],
+				structuredContent: output,
+			};
+		},
+	);
+
+	server.registerTool(
+		'review-tsrx-components',
+		{
+			title: 'Review TSRX Component Structure',
+			description:
+				'Reviews TSRX source for component decomposition opportunities when control flow, repeated item templates, or style blocks become large enough to hurt generated-code reliability.',
+			inputSchema: {
+				code: z.string(),
+				filename: z.string().optional(),
+				target: TARGET_SCHEMA.optional(),
+			},
+			outputSchema: authoring_review_result_schema,
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				openWorldHint: false,
+			},
+		},
+		async (input) => {
+			const output = review_tsrx_components_handler(input);
+			return {
+				content: [{ type: 'text', text: json_text(output) }],
+				structuredContent: output,
+			};
+		},
+	);
+
 	if (!remote) {
 		server.registerTool(
 			'inspect-project',