@tsrx/mcp 0.0.33 → 0.0.35

package/README.md

@@ -88,7 +88,7 @@ Add the generic config above to your Codex MCP configuration.
   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.
+  form controls, and visible text accidentally wrapped in quote characters.
 - `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

package/package.json

@@ -3,7 +3,7 @@
   "description": "MCP server for TSRX documentation and project context",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "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.20",
-    "@tsrx/prettier-plugin": "0.3.72"
+    "@tsrx/core": "0.1.22",
+    "@tsrx/prettier-plugin": "0.3.74"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",

package/src/analyze.js

@@ -3,7 +3,11 @@ import {
 	TSRX_DO_WHILE_STATEMENT_ERROR,
 	TSRX_FOR_IN_STATEMENT_ERROR,
 	TSRX_FOR_STATEMENT_ERROR,
+	TSRX_IF_BREAK_ERROR,
+	TSRX_IF_CONTINUE_ERROR,
+	TSRX_IF_RETURN_ERROR,
 	TSRX_LOOP_BREAK_ERROR,
+	TSRX_LOOP_CONTINUE_ERROR,
 	TSRX_LOOP_RETURN_ERROR,
 	TSRX_RETURN_STATEMENT_ERROR,
 	TSRX_WHILE_STATEMENT_ERROR,
@@ -76,20 +80,39 @@ function create_advice(input) {
 		advice.push({
 			kind: 'jsx-expression-value',
 			severity: 'info',
-			title: 'Wrap expression-position JSX',
+			title: 'Use JSX-shaped expression values',
 			message:
-				'When JSX is needed as a value, wrap native TSRX in a fragment `<>...</>` or use a host compatibility island such as `<tsx:react>...</tsx:react>`.',
-			documentation: ['tsrx://docs/tsx-expression-values.md'],
+				'TSRX expression values use JSX-shaped nodes. Use a JSXElement directly for one child, a JSXFragment when the value needs multiple children, or a JSX statement container when setup must produce one final output.',
+			documentation: ['tsrx://docs/expression-values.md'],
 		});
 	}
 
-	if (error_messages.has(TSRX_LOOP_RETURN_ERROR) || error_messages.has(TSRX_LOOP_BREAK_ERROR)) {
+	if (
+		error_messages.has(TSRX_LOOP_RETURN_ERROR) ||
+		error_messages.has(TSRX_LOOP_BREAK_ERROR) ||
+		error_messages.has(TSRX_LOOP_CONTINUE_ERROR)
+	) {
 		advice.push({
 			kind: 'tsrx-loop-control-flow',
 			severity: 'error',
-			title: 'Use continue inside TSRX for...of loops',
+			title: 'Filter before TSRX for...of loops',
+			message:
+				'Direct continue, break, and return statements are not valid inside TSRX @for loops. Filter the iterable before rendering, use  { ... } for the no-items fallback, and keep ordinary JavaScript control flow inside nested functions.',
+			documentation: ['tsrx://docs/control-flow.md'],
+		});
+	}
+
+	if (
+		error_messages.has(TSRX_IF_RETURN_ERROR) ||
+		error_messages.has(TSRX_IF_BREAK_ERROR) ||
+		error_messages.has(TSRX_IF_CONTINUE_ERROR)
+	) {
+		advice.push({
+			kind: 'tsrx-if-control-flow',
+			severity: 'error',
+			title: 'Keep @if branches render-only',
 			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.',
+				'Direct return, continue, and break statements are not valid inside TSRX @if branches. Use an ordinary JavaScript if statement before template output for guard returns, or render the branch output conditionally.',
 			documentation: ['tsrx://docs/control-flow.md'],
 		});
 	}
@@ -98,9 +121,9 @@ function create_advice(input) {
 		advice.push({
 			kind: 'tsrx-template-return',
 			severity: 'error',
-			title: 'Move returns outside TSRX templates',
+			title: 'Put returns in TypeScript setup',
 			message:
-				'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.',
+				'Return statements are ordinary JavaScript control flow for functions, not template output. Use guard clauses before a JSX statement container or return value, or render conditionally inside the template.',
 			documentation: ['tsrx://docs/control-flow.md'],
 		});
 	}

package/src/authoring.js

@@ -129,11 +129,11 @@ function collect_direct_quoted_text_issues(code) {
 		issues.push({
 			kind: 'direct-quoted-text',
 			severity: match[1] === 'button' ? 'error' : 'warning',
-			title: 'Use expression text for visible TSRX text',
+			title: 'Write visible TSRX text without extra quotes',
 			message:
-				'Direct quoted text inside TSRX elements can be treated as a JavaScript string statement instead of rendered text in some target output.',
+				'Quoted text inside TSRX elements renders the quote characters as part of JSX text. Use plain JSX text unless you intentionally want visible quotes.',
 			snippet: line_snippet(match[0]),
-			recommendation: `Replace it with expression text, for example <${match[1]}>{'${match[3].replace(/'/g, "\\'")}'}</${match[1]}>.`,
+			recommendation: `Replace it with plain JSX text, for example <${match[1]}>${match[3]}</${match[1]}>.`,
 			documentation: ['tsrx://docs/text-and-template-expressions.md'],
 		});
 	}
@@ -160,6 +160,7 @@ export function review_tsrx_accessibility(input) {
 			has_attribute(attrs, 'aria-label') ||
 			has_attribute(attrs, 'aria-labelledby') ||
 			has_attribute(attrs, 'title') ||
+			has_visible_label_text(inner) ||
 			(has_expression_text(inner) && !/^\s*\{\s*['"`]\s*['"`]\s*\}\s*$/.test(inner));
 
 		if (!has_name || has_direct_quoted_text(inner)) {
@@ -171,7 +172,7 @@ export function review_tsrx_accessibility(input) {
 					'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.",
+					'Use visible JSX text such as Add task or add aria-label for icon-only buttons.',
 				documentation: ['tsrx://docs/text-and-template-expressions.md'],
 			});
 		}
@@ -227,7 +228,7 @@ export function review_tsrx_accessibility(input) {
 				? ['Run browser-based Axe or the benchmark validation loop.']
 				: [
 						'Fix error-severity issues before returning code.',
-						'Prefer expression text for visible labels.',
+						'Prefer plain JSX text for visible labels.',
 						'Run review-tsrx-accessibility again, then compile-tsrx and browser-based Axe.',
 					],
 	};

package/src/generated/docs.js

@@ -11,7 +11,7 @@ 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- 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 `<>...</>`.\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. Use a JSX statement container, `@{ ... }`, when the function body is mostly TSRX setup plus one rendered output.\n- JSXElement, JSXFragment, JSXText, JSXExpressionContainer, attributes, and spreads use the standard JSX node family.\n- A mixed setup/template scope must finish with exactly one output node: a JSXElement, JSXFragment, or JSX control-flow expression. Wrap plain text, expression containers, or multiple siblings in a fragment.\n- Template control flow uses directive expressions: `@if`, `@for`, `@switch`, and `@try`; every directive body uses a `{...}` template block.\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',
@@ -19,14 +19,15 @@ export const documentation_sections = [
 		use_cases:
 			'components, functions, props, authoring .tsrx files, jsx return syntax',
 		content:
-			'# 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',
+			'# Function Components\n\nAuthor UI as ordinary TypeScript functions. Components can return JSX directly, or use a JSX statement container when setup and output should live together.\n\n```tsx\nexport function Button({ label }: { label: string }) @{\n  <button>{label}</button>\n}\n```\n\nInside `@{ ... }`, put any setup statements first and end with one rendered output node. No JavaScript setup can appear after that output.\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, string literals',
+		use_cases:
+			'text children, jsx text, comments, string literals, expression containers',
 		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\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',
+			'# Text and Template Expressions\n\nStatic text is JSXText and can be written directly between tags. Dynamic values use normal JSX expression containers.\n\n```tsx\nfunction Greeting({ name }: { name: string }) @{\n  <>\n  <h1>Hello</h1>\n  <p>{name}</p>\n  </>\n}\n```\n\nJavaScript comments are also allowed between template children and are not rendered. Use braces for JavaScript expressions, including string literals that should be evaluated as JavaScript.\n\nSpecification grammar:\n\n```text\nJSXTextChild :\n  JSXTextCharacters\n\nJSXExpressionContainer :\n  { AssignmentExpression }\n\nJSXCodeBlock :\n  @{ StatementListItemListopt TemplateOutput }\n\nTemplateBlock :\n  { TemplateChildrenopt }\n  { StatementListItemList TemplateOutput }\n\nJSXIfExpression :\n  @if ( Expression ) TemplateBlock\n  @if ( Expression ) TemplateBlock else TemplateBlock\n\nJSXForExpression :\n  @for ( ForHeader TemplateForOptionsopt ) TemplateBlock\n  @for ( ForHeader TemplateForOptionsopt ) TemplateBlock empty TemplateBlock\n\nJSXSwitchExpression :\n  @switch ( Expression ) { JSXSwitchCaseListopt }\n\nJSXSwitchCase :\n  case Expression : TemplateBlock\n  default : TemplateBlock\n\nJSXTryExpression :\n  @try TemplateBlock pending TemplateBlock\n  @try TemplateBlock catch ( CatchParameteropt ) TemplateBlock\n  @try TemplateBlock finally TemplateBlock\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#templates',
 	},
 	{
 		slug: 'expression-values',
@@ -34,7 +35,7 @@ export const documentation_sections = [
 		use_cases:
 			'fragments, pass template as prop, return template from helper, render props, expression position jsx',
 		content:
-			'# 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```\n\nSource: website-tsrx/src/pages/specification.tsrx#expression-values',
+			'# Expression Values\n\nTSRX uses JSX-shaped expression values. A single JSXElement can be assigned, passed, or returned directly. Use a JSXFragment when the value needs multiple children, or use a JSX statement container when setup needs to produce one final output.\n\n```tsx\nfunction App() @{\n  const title = <span class="title">Settings</span>;\n  const badge = (label: string) => @{\n    const normalized = label.trim();\n\n    <span class="badge">{normalized}</span>\n  };\n\n  <Card title={title}>{badge(\'New\')}</Card>\n}\n```\n\n`@{ ... }` is a JSX statement container. A normal JSX fragment, element body, or control-flow branch can also contain setup before output, but that scope must still end with one output node. Use a fragment when the output is text, an expression container, or multiple siblings.\n\nSpecification grammar:\n\n```text\nPrimaryExpression :\n  JSXElement\n  JSXFragment\n  JSXStyleElement\n  JSXCodeBlock\n  JSXIfExpression\n  JSXForExpression\n  JSXSwitchExpression\n  JSXTryExpression\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#expression-values',
 	},
 	{
 		slug: 'control-flow',
@@ -42,7 +43,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 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',
+			'# Control Flow\n\nTemplate control flow uses directive-prefixed expressions inside JSX children.\n\n```tsx\nfunction List({ items }: { items: string[] }) @{\n  <>\n  @if (items.length === 0) {\n    <p>No items</p>\n  } @else {\n    <ul>\n      @for (const item of items.filter(Boolean); index i; key item) {\n        <li>{item}</li>\n      } @empty {\n        <li>No items</li>\n      }\n    </ul>\n  }\n  </>\n}\n```\n\nUse normal function returns for guard exits before entering template output. Filter a collection before passing it to `@for` when some items should not render, and use ` { ... }` for the no-items fallback.\n\n`return` statements are not template output. Put guard returns before the JSX statement container or return value, or render conditionally with `@if`. Inside TSRX `@if` branches and `@for ... of` loops, direct `continue`, `break`, and `return` statements are invalid. Inside a TSRX `@switch` case body, both `break` and `return` are invalid because cases are isolated template blocks.\n\nTSRX rendering supports `@for ... of` list loops. Regular `for`, `for...in`, `while`, and `do...while` loops are not rendering constructs. Move imperative loops into setup code, 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',
@@ -57,7 +58,7 @@ export const documentation_sections = [
 		use_cases:
 			'style expressions, scoped css, module server, submodule imports, compile-time identifiers',
 		content:
-			'# Style and Server Extensions\n\nAssign a `<style>` expression to expose scoped CSS class names declared in the current module.\n\n```tsx\nconst styles = <style>\n  .card { padding: 1rem; }\n</style>;\n\nreturn <Child class={styles.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\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',
+			'# Style and Server Extensions\n\nAssign a `<style>` expression to expose scoped CSS class names declared in the current module.\n\n```tsx\nconst styles = <style>\n  .card { padding: 1rem; }\n</style>;\n\nexport function ChildCard() @{\n  <>\n  <Child class={styles.card} />\n  </>\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\nJSXStyleElement :\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,10 @@ 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 functions, statement templates, control flow, TSX expression values, lazy destructuring, style identifiers, and submodule declarations.
+4. Keep core TSRX advice target-neutral: component functions, JSX expression values, JSX statement containers \`@{ ... }\`, JSX text, directive control flow, 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 \`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.
+5a. In template output, render lists with \`@for (... of ...)\`; filter the iterable before rendering when items should be skipped, and use \` { ... }\` for the no-items fallback; use \`@if\`, \`@switch\`, and \`@try\` for rendering control flow. Every directive body uses a \`{...}\` template block. When a scope mixes setup with output, setup comes first and the scope ends with exactly one JSX element, JSX fragment, or JSX control-flow expression.
+5b. \`return\` is JavaScript function control flow, not template output. Use guard returns before a JSX statement container or return value, or render conditionally with \`@if\`. Do not use \`continue\`, \`break\`, or \`return\` inside \`@if\` template branches or \`@for\` template loops. \`@switch\` cases are isolated blocks and do not use \`break\` or \`return\`.
 ${file_validation_step}
 ${compile_step}
 ${authoring_step}
@@ -600,7 +601,7 @@ export function createTSRXMcpServer(options = {}) {
 		{
 			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.',
+				'Reviews TSRX source for common accessibility issues before browser-based Axe validation, including missing button names, unlabeled form controls, and visible text accidentally wrapped in quote characters.',
 			inputSchema: {
 				code: z.string(),
 				filename: z.string().optional(),

package/src/target.js

@@ -5,7 +5,7 @@ export const TARGET_CANDIDATES = [
 	{
 		target: 'ripple',
 		compilerPackage: '@tsrx/ripple',
-		signals: ['@tsrx/ripple', 'ripple', '@ripple-ts/vite-plugin', '@ripple-ts/compat-react'],
+		signals: ['@tsrx/ripple', 'ripple', '@ripple-ts/vite-plugin'],
 	},
 	{
 		target: 'react',