@tsrx/mcp 0.0.29 → 0.0.30

package/README.md

@@ -89,7 +89,7 @@ Add the generic config above to your Codex MCP configuration.
 - `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
+- `review-tsrx-styles` - review function-local 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.

package/package.json

@@ -3,7 +3,7 @@
   "description": "MCP server for TSRX documentation and project context",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "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.1.16",
-    "@tsrx/prettier-plugin": "0.3.68"
+    "@tsrx/core": "0.1.17",
+    "@tsrx/prettier-plugin": "0.3.69"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",

package/src/analyze.js

@@ -1,11 +1,12 @@
 import {
-	COMPONENT_DO_WHILE_STATEMENT_ERROR,
-	COMPONENT_FOR_IN_STATEMENT_ERROR,
-	COMPONENT_FOR_STATEMENT_ERROR,
-	COMPONENT_LOOP_BREAK_ERROR,
-	COMPONENT_LOOP_RETURN_ERROR,
-	COMPONENT_WHILE_STATEMENT_ERROR,
 	DIAGNOSTIC_CODES,
+	TSRX_DO_WHILE_STATEMENT_ERROR,
+	TSRX_FOR_IN_STATEMENT_ERROR,
+	TSRX_FOR_STATEMENT_ERROR,
+	TSRX_LOOP_BREAK_ERROR,
+	TSRX_LOOP_RETURN_ERROR,
+	TSRX_RETURN_STATEMENT_ERROR,
+	TSRX_WHILE_STATEMENT_ERROR,
 } from '@tsrx/core';
 import { compile_tsrx } from './compile.js';
 
@@ -49,31 +50,6 @@ function create_advice(input) {
 		});
 	}
 
-	const has_function_component_syntax = error_codes.has(DIAGNOSTIC_CODES.FUNCTION_COMPONENT_SYNTAX);
-	if (has_function_component_syntax) {
-		advice.push({
-			kind: 'function-component-syntax',
-			severity: 'warning',
-			title: 'Use TSRX component declarations',
-			message:
-				'.tsrx component files should use the component keyword. A React-style function returning JSX is usually the wrong authoring shape for TSRX.',
-			documentation: ['tsrx://docs/components.md'],
-		});
-	}
-
-	const fired_jsx_return = error_codes.has(DIAGNOSTIC_CODES.JSX_RETURN_IN_COMPONENT);
-
-	if (fired_jsx_return) {
-		advice.push({
-			kind: 'jsx-return-in-component',
-			severity: 'error',
-			title: 'Do not return JSX from component bodies',
-			message:
-				'Inside a TSRX component body, template elements are statements. Replace `return <div />` with a template statement like `<div />`; use bare `return;` only for guard exits.',
-			documentation: ['tsrx://docs/components.md', 'tsrx://docs/tsx-expression-values.md'],
-		});
-	}
-
 	if (error_codes.has(DIAGNOSTIC_CODES.UNCLOSED_TAG)) {
 		advice.push({
 			kind: 'unclosed-tag',
@@ -107,25 +83,33 @@ function create_advice(input) {
 		});
 	}
 
-	if (
-		error_messages.has(COMPONENT_LOOP_RETURN_ERROR) ||
-		error_messages.has(COMPONENT_LOOP_BREAK_ERROR)
-	) {
+	if (error_messages.has(TSRX_LOOP_RETURN_ERROR) || error_messages.has(TSRX_LOOP_BREAK_ERROR)) {
+		advice.push({
+			kind: 'tsrx-loop-control-flow',
+			severity: 'error',
+			title: 'Use continue inside TSRX for...of loops',
+			message:
+				'Return statements are not valid inside TSRX templates, and break statements are not valid inside TSRX for...of loops. Use continue to skip the current rendered item. Nested functions inside the loop keep ordinary JavaScript control flow.',
+			documentation: ['tsrx://docs/control-flow.md'],
+		});
+	}
+
+	if (error_messages.has(TSRX_RETURN_STATEMENT_ERROR)) {
 		advice.push({
-			kind: 'component-loop-control-flow',
+			kind: 'tsrx-template-return',
 			severity: 'error',
-			title: 'Use continue inside component for...of loops',
+			title: 'Move returns outside TSRX templates',
 			message:
-				'Top-level return and break statements are not valid inside a component for...of loop. Use continue to skip the current rendered item. Nested functions inside the loop keep ordinary JavaScript control flow.',
+				'Return statements are ordinary JavaScript control flow for functions, not template control flow. Use guard clauses before returning TSRX, or render conditionally inside the template.',
 			documentation: ['tsrx://docs/control-flow.md'],
 		});
 	}
 
 	if (
-		error_messages.has(COMPONENT_FOR_STATEMENT_ERROR) ||
-		error_messages.has(COMPONENT_FOR_IN_STATEMENT_ERROR) ||
-		error_messages.has(COMPONENT_WHILE_STATEMENT_ERROR) ||
-		error_messages.has(COMPONENT_DO_WHILE_STATEMENT_ERROR)
+		error_messages.has(TSRX_FOR_STATEMENT_ERROR) ||
+		error_messages.has(TSRX_FOR_IN_STATEMENT_ERROR) ||
+		error_messages.has(TSRX_WHILE_STATEMENT_ERROR) ||
+		error_messages.has(TSRX_DO_WHILE_STATEMENT_ERROR)
 	) {
 		advice.push({
 			kind: 'unsupported-component-loop',

package/src/generated/docs.js

@@ -11,23 +11,22 @@ export const documentation_sections = [
 		use_cases:
 			'always, introduction, explain tsrx, compare jsx, language model context, runtime targets',
 		content:
-			'# TSRX Overview\n\nTSRX is a TypeScript language extension for authoring declarative UI in .tsrx files. It adds a small set of syntax forms on top of TypeScript, while letting each target compiler define the runtime semantics.\n\nCore ideas:\n- component declarations use the component keyword.\n- JSX-like elements can be written as statements inside component bodies.\n- control-flow statements can contain template output.\n- expression-position native TSRX must use <tsrx>...</tsrx>; JSX-style values use <>...</> or <tsx>...</tsx>.\n- lazy destructuring uses &[] and &{} for by-reference bindings.\n\nThe core language docs should stay target-neutral. After identifying the active runtime target, use target-specific docs, prompts, or skills for runtime imports, bundler setup, and semantics that are not defined by TSRX itself.\n\nSource: website-tsrx/src/pages/specification.tsrx',
+			'# TSRX Overview\n\nTSRX is a TypeScript language extension for authoring declarative UI in .tsrx files. It adds a small set of syntax forms on top of TypeScript, while letting each target compiler define the runtime semantics.\n\nCore ideas:\n- Components are ordinary TypeScript functions that return TSRX.\n- TSRX opens in expression position, then template children use a template statement list inside the fragment.\n- control-flow statements can contain template output.\n- native TSRX can be returned directly as `<div />` or `<>...</>`; JSX-style values can use `<tsx>...</tsx>` when needed.\n- lazy destructuring uses &[] and &{} for by-reference bindings.\n\nThe core language docs should stay target-neutral. After identifying the active runtime target, use target-specific docs, prompts, or skills for runtime imports, bundler setup, and semantics that are not defined by TSRX itself.\n\nSource: website-tsrx/src/pages/specification.tsrx',
 	},
 	{
 		slug: 'components',
-		title: 'Component Declarations',
+		title: 'Function Components',
 		use_cases:
-			'components, component keyword, props, authoring .tsrx files, no jsx return syntax',
+			'components, functions, props, authoring .tsrx files, jsx return syntax',
 		content:
-			'# Component Declarations\n\nComponents are declared with the component keyword, not as functions returning JSX.\n\n```tsx\ncomponent Button(props: { label: string }) {\n  <button>{props.label}</button>\n}\n```\n\nInside a component body, template elements are statements. Do not generate `return <div />` from a component body. Use a bare `return;` only as a guard exit after emitting fallback template statements.\n\nSpecification grammar:\n\n```text\nComponentDeclaration :\n  component BindingIdentifier ( FormalParametersopt ) { ComponentBody }\n\nComponentExpression :\n  component BindingIdentifieropt ( FormalParametersopt ) { ComponentBody }\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#components',
+			'# Function Components\n\nAuthor UI as ordinary TypeScript functions that return TSRX.\n\n```tsx\nfunction Button(props: { label: string }) {\n  return <button>{props.label}</button>;\n}\n```\n\nInside the returned TSRX fragment, template elements and control flow share the same template statement list.\n\nSource: website-tsrx/src/pages/specification.tsrx#components',
 	},
 	{
 		slug: 'text-and-template-expressions',
 		title: 'Text and Template Expressions',
-		use_cases:
-			'text children, quoted text, raw text errors, html, text directive, string literals',
+		use_cases: 'text children, quoted text, raw text errors, string literals',
 		content:
-			'# Text and Template Expressions\n\nRaw unquoted text children are not valid TSRX. Static text should be written as a direct double-quoted child, and dynamic values should be wrapped in braces.\n\n```tsx\ncomponent Greeting({ name }: { name: string }) {\n  <h1>"Hello"</h1>\n  <p>{name}</p>\n}\n```\n\nSingle-quoted strings and template literals remain JavaScript expressions, so they must be inside braces. Use `{text expression}` for explicit text and `{html expression}` only for trusted HTML.\n\nSpecification grammar:\n\n```text\nDoubleQuotedTextChild :\n  " JSXStringCharactersopt "\n\nTemplateExpression :\n  { AssignmentExpression }\n  { text AssignmentExpression }\n  { html AssignmentExpression }\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#templates',
+			'# Text and Template Expressions\n\nRaw unquoted text children are not valid TSRX. Static text should be written as a direct double-quoted child, and dynamic values should be wrapped in braces.\n\n```tsx\nfunction Greeting({ name }: { name: string }) {\n  return <>\n  <h1>"Hello"</h1>\n  <p>{name}</p>\n  </>;\n}\n```\n\nSingle-quoted strings and template literals remain JavaScript expressions, so they must be inside braces. When you need explicit string coercion, write it in JavaScript with `String(value)`, `value + \'\'`, or a typed string value.\n\nSpecification grammar:\n\n```text\nDoubleQuotedTextChild :\n  " JSXStringCharactersopt "\n\nTemplateExpression :\n  { AssignmentExpression }\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#templates',
 	},
 	{
 		slug: 'tsx-expression-values',
@@ -35,7 +34,7 @@ export const documentation_sections = [
 		use_cases:
 			'fragments, tsrx tag, tsx tag, pass template as prop, return template from helper, render props, expression position jsx',
 		content:
-			'# Expression Values\n\nRegular template elements in component bodies are statements and have no value. When native TSRX must be used in expression position, wrap it in `<tsrx>...</tsrx>`. When JSX-style children must be used in expression position, wrap them in `<>...</>` or `<tsx>...</tsx>`.\n\n```tsx\ncomponent App() {\n  const title = <tsrx><span>"Settings"</span></tsrx>;\n\n  <Card title={title} />\n}\n```\n\nNative TSRX expression fragments can contain setup statements and template control flow:\n\n```tsx\nfunction badge(label: string) {\n  return <tsrx>\n    const normalized = label.trim();\n    <span class="badge">{normalized}</span>\n  </tsrx>;\n}\n```\n\nUse these wrappers for assigning UI to variables, returning UI from helper functions, or passing UI as props. Do not write `const el = <div />` directly in TSRX component code.\n\nSpecification grammar:\n\n```text\nTsrxExpression :\n  <tsrx> TemplateChildrenopt </tsrx>\n\nTsxElement :\n  <tsx> TsxChildrenopt </tsx>\n\nTsxCompatElement :\n  <tsx: IdentifierName> TsxChildrenopt </tsx: IdentifierName>\n\nTsxFragmentShorthand :\n  <> TsxChildrenopt </>\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#tsx-islands',
+			'# Expression Values\n\nReturned TSRX opens in expression position. Inside the TSRX fragment, template elements are statements and control flow can emit UI.\n\n```tsx\nfunction App() {\n  const title = <>"Settings"</>;\n\n  return <Card title={title} />;\n}\n```\n\nNative TSRX expression fragments can contain setup statements and template control flow:\n\n```tsx\nfunction badge(label: string) {\n  return <>\n    const normalized = label.trim();\n    <span class="badge">{normalized}</span>\n  </>;\n}\n```\n\nUse fragments for assigning UI to variables, returning UI from helper functions, or passing UI as props.\n\nSpecification grammar:\n\n```text\nTsrxExpression :\n  Element\n  <> TemplateChildrenopt </>\n\nTsxElement :\n  <tsx> TsxChildrenopt </tsx>\n\nTsxCompatElement :\n  <tsx: IdentifierName> TsxChildrenopt </tsx: IdentifierName>\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#tsx-islands',
 	},
 	{
 		slug: 'control-flow',
@@ -43,7 +42,7 @@ export const documentation_sections = [
 		use_cases:
 			'if else, for loops, switch, try catch, conditional rendering, lists, guard returns',
 		content:
-			'# Control Flow\n\nStandard JavaScript control flow can contain template statements inside component bodies and nested element children.\n\n```tsx\ncomponent List({ items }: { items: string[] }) {\n  if (items.length === 0) {\n    <p>"No items"</p>\n    return;\n  }\n\n  <ul>\n    for (const item of items; index i; key item) {\n      if (!item) continue;\n      <li>{item}</li>\n    }\n  </ul>\n}\n```\n\nA bare `return;` exits the current render path. A return with a value is invalid inside a TSRX component body.\n\nInside a component `for...of` loop, `continue` skips the current rendered iteration and is the only supported top-level loop control-flow statement. Top-level `return` and `break` are invalid inside component `for...of` loops; use `continue` for item skips, `return;` for non-loop guard exits, and `break` only for `switch` cases.\n\nComponent rendering supports `for...of` list loops. Regular `for`, `for...in`, `while`, and `do...while` loops are not supported in component template scope. Move imperative loops into a nested function, event handler, effect, or helper where normal JavaScript control flow rules apply.\n\nSource: website-tsrx/src/pages/features.tsrx#for',
+			'# Control Flow\n\nStandard JavaScript control flow can contain template statements inside returned TSRX fragments and nested element children.\n\n```tsx\nfunction List({ items }: { items: string[] }) {\n  return <>\n  if (items.length === 0) {\n    <p>"No items"</p>\n  } else {\n    <ul>\n      for (const item of items; index i; key item) {\n        if (!item) continue;\n        <li>{item}</li>\n      }\n    </ul>\n  }\n  </>;\n}\n```\n\nUse normal function returns for guard exits before TSRX opens. Inside a nested TSRX loop body, `continue` skips the current rendered iteration.\n\n`return` statements are invalid anywhere inside returned TSRX element or fragment bodies. Inside a TSRX `for...of` loop, `continue` skips the current rendered iteration and is the only supported top-level loop control-flow statement. `break` is invalid inside TSRX `for...of` loops; use `continue` for item skips and `break` only for `switch` cases.\n\nTSRX rendering supports `for...of` list loops. Regular `for`, `for...in`, `while`, and `do...while` loops are not supported in TSRX template scope. Move imperative loops into a nested function, event handler, effect, or helper where normal JavaScript control flow rules apply.\n\nSource: website-tsrx/src/pages/features.tsrx#for',
 	},
 	{
 		slug: 'lazy-destructuring',
@@ -56,9 +55,9 @@ export const documentation_sections = [
 		slug: 'style-and-server',
 		title: 'Style and Server Extensions',
 		use_cases:
-			'style directive, scoped css, module server, submodule imports, compile-time identifiers',
+			'style refs, scoped css, module server, submodule imports, compile-time identifiers',
 		content:
-			'# 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',
+			'# Style and Server Extensions\n\nUse `<style ref>` to expose scoped CSS class names declared in the current module.\n\n```tsx\nlet styles;\nreturn <>\n  <Child className={styles.card} />\n  <style ref={(s) => styles = s}>\n    .card { padding: 1rem; }\n  </style>\n</>;\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\nStyleElement :\n  <style JSXAttributesopt> CSSSource </style>\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/server.js

@@ -305,9 +305,9 @@ function create_tsrx_task_prompt(options) {
 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 submodule declarations.
+4. Keep core TSRX advice target-neutral: component functions, 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.
-5a. In component template scope, render lists with \`for...of\`; use \`continue\` to skip an item; do not use top-level \`return\` or \`break\` inside the loop, and do not use regular \`for\`, \`for...in\`, \`while\`, or \`do...while\` loops there.
+5a. In component template scope, render lists with \`for...of\`; use \`continue\` to skip an item; do not use \`return\` anywhere inside TSRX element or fragment bodies, do not use \`break\` inside \`for...of\` template loops, and do not use regular \`for\`, \`for...in\`, \`while\`, or \`do...while\` loops there.
 ${file_validation_step}
 ${compile_step}
 ${authoring_step}