@tsrx/mcp 0.1.19 → 0.1.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/package.json +4 -4
- package/src/analyze.js +25 -5
- package/src/compile.js +46 -6
- package/src/generated/docs.js +2 -2
- package/src/schemas.js +1 -0
- package/src/server.js +10 -4
package/README.md
CHANGED
|
@@ -84,7 +84,8 @@ Add the generic config above to your Codex MCP configuration.
|
|
|
84
84
|
- `inspect-project` - inspect target signals, TSRX packages, tooling, scripts, and
|
|
85
85
|
likely project commands.
|
|
86
86
|
- `compile-tsrx` - compile TSRX code with the inferred or explicit target compiler
|
|
87
|
-
and return diagnostics.
|
|
87
|
+
and return diagnostics. Platform flags use the `tsrx.platform` from the nearest
|
|
88
|
+
`tsconfig.json` (the hosted endpoint does not read one).
|
|
88
89
|
- `format-tsrx` - format TSRX code using the official Prettier plugin.
|
|
89
90
|
- `analyze-tsrx` - compile TSRX code and convert common diagnostics into
|
|
90
91
|
target-neutral authoring advice with linked docs resources.
|
package/package.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"description": "MCP server for TSRX documentation and project context",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"author": "Dominic Gannaway",
|
|
6
|
-
"version": "0.1.
|
|
6
|
+
"version": "0.1.21",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"repository": {
|
|
9
9
|
"type": "git",
|
|
@@ -37,14 +37,14 @@
|
|
|
37
37
|
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
38
38
|
"prettier": "^3.9.9",
|
|
39
39
|
"zod": "^4.3.6",
|
|
40
|
-
"@tsrx/core": "0.
|
|
41
|
-
"@tsrx/prettier-plugin": "0.
|
|
40
|
+
"@tsrx/core": "0.6.1",
|
|
41
|
+
"@tsrx/prettier-plugin": "0.7.1"
|
|
42
42
|
},
|
|
43
43
|
"devDependencies": {
|
|
44
44
|
"@types/node": "^24.3.0",
|
|
45
45
|
"typescript": "^5.9.3",
|
|
46
46
|
"vitest": "^4.1.6",
|
|
47
|
-
"@tsrx/hono": "0.
|
|
47
|
+
"@tsrx/hono": "0.3.1"
|
|
48
48
|
},
|
|
49
49
|
"scripts": {
|
|
50
50
|
"generate:docs": "node scripts/generate-docs-index.js"
|
package/src/analyze.js
CHANGED
|
@@ -28,7 +28,7 @@ import { compile_tsrx } from './compile.js';
|
|
|
28
28
|
* @typedef {{
|
|
29
29
|
* ok: boolean,
|
|
30
30
|
* target: string | null,
|
|
31
|
-
* errors: Array<{ message: string, code?: string | null }>,
|
|
31
|
+
* errors: Array<{ message: string, code?: string | null, severity?: 'error' | 'warning' }>,
|
|
32
32
|
* }} TSRXCompileSummary
|
|
33
33
|
*/
|
|
34
34
|
|
|
@@ -144,7 +144,21 @@ function create_advice(input) {
|
|
|
144
144
|
});
|
|
145
145
|
}
|
|
146
146
|
|
|
147
|
-
if (
|
|
147
|
+
if (error_codes.has(DIAGNOSTIC_CODES.CODE_BLOCK_EXPRESSION_ONLY)) {
|
|
148
|
+
advice.push({
|
|
149
|
+
kind: 'code-block-expression-only',
|
|
150
|
+
severity: 'warning',
|
|
151
|
+
title: 'Give a @{...} block output, or use the value directly',
|
|
152
|
+
message:
|
|
153
|
+
"`@{...}` is always a code block, so a block that holds only an expression runs it and renders nothing. As a child, as in `<p>@{user.name}</p>`, render an `@` and then the value with `<p>@{user.name}</p>`, ``<p>{`@${user.name}`}</p>``, or `<p>{'@' + user.name}</p>`, or only the value with `<p>{user.name}</p>`. Elsewhere, as in `const title = @{user.name};` or `title={@{user.name}}`, use the expression itself (`title={user.name}`), or end the block with output: `@{ <>{user.name}</> }`.",
|
|
154
|
+
documentation: [
|
|
155
|
+
'tsrx://docs/text-and-template-expressions.md',
|
|
156
|
+
'tsrx://docs/expression-values.md',
|
|
157
|
+
],
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
if (advice.length === 0 && compileResult.errors.length === 0) {
|
|
148
162
|
advice.push({
|
|
149
163
|
kind: 'compile-clean',
|
|
150
164
|
severity: 'info',
|
|
@@ -155,10 +169,14 @@ function create_advice(input) {
|
|
|
155
169
|
});
|
|
156
170
|
}
|
|
157
171
|
|
|
158
|
-
|
|
172
|
+
// An error no hint covers needs advice too, even next to a warning's.
|
|
173
|
+
if (
|
|
174
|
+
advice.length === 0 ||
|
|
175
|
+
(!compileResult.ok && advice.every((item) => item.severity !== 'error'))
|
|
176
|
+
) {
|
|
159
177
|
advice.push({
|
|
160
178
|
kind: 'compiler-diagnostic',
|
|
161
|
-
severity: 'error',
|
|
179
|
+
severity: compileResult.ok ? 'warning' : 'error',
|
|
162
180
|
title: 'Compiler diagnostics need review',
|
|
163
181
|
message:
|
|
164
182
|
'The TSRX compiler returned diagnostics that do not match a known MCP hint yet. Use the normalized compiler errors and relevant docs sections to revise the source.',
|
|
@@ -181,6 +199,7 @@ function create_advice(input) {
|
|
|
181
199
|
* errors: Array<{
|
|
182
200
|
* message: string,
|
|
183
201
|
* code: string | null,
|
|
202
|
+
* severity?: 'error' | 'warning',
|
|
184
203
|
* type: string | null,
|
|
185
204
|
* fileName: string | null,
|
|
186
205
|
* pos: number | null,
|
|
@@ -226,7 +245,8 @@ export function analyze_tsrx_result(input) {
|
|
|
226
245
|
* cwd?: string,
|
|
227
246
|
* collect?: boolean,
|
|
228
247
|
* loose?: boolean,
|
|
229
|
-
* mode?: 'client' | 'server'
|
|
248
|
+
* mode?: 'client' | 'server',
|
|
249
|
+
* resolvePlatform?: boolean
|
|
230
250
|
* }} input
|
|
231
251
|
*/
|
|
232
252
|
export async function analyze_tsrx(input) {
|
package/src/compile.js
CHANGED
|
@@ -2,6 +2,7 @@ import path from 'node:path';
|
|
|
2
2
|
import { createRequire } from 'node:module';
|
|
3
3
|
import { pathToFileURL } from 'node:url';
|
|
4
4
|
import { DIAGNOSTIC_CODES } from '@tsrx/core';
|
|
5
|
+
import { resolveBuildPlatform } from '@tsrx/core/config';
|
|
5
6
|
import { detect_target, TARGET_CANDIDATES } from './target.js';
|
|
6
7
|
|
|
7
8
|
const VALID_TARGETS = new Set(TARGET_CANDIDATES.map((candidate) => candidate.target));
|
|
@@ -10,6 +11,7 @@ const VALID_TARGETS = new Set(TARGET_CANDIDATES.map((candidate) => candidate.tar
|
|
|
10
11
|
* @typedef {{
|
|
11
12
|
* message: string,
|
|
12
13
|
* code: string | null,
|
|
14
|
+
* severity: 'error' | 'warning',
|
|
13
15
|
* type: string | null,
|
|
14
16
|
* fileName: string | null,
|
|
15
17
|
* pos: number | null,
|
|
@@ -58,11 +60,15 @@ const LEGACY_CODES = {
|
|
|
58
60
|
};
|
|
59
61
|
|
|
60
62
|
/**
|
|
63
|
+
* A collected diagnostic keeps its severity. One the compiler threw stopped
|
|
64
|
+
* the compile, so it is an error whatever it says, as the language server and
|
|
65
|
+
* `tsrx-tsc` show it.
|
|
61
66
|
* @param {unknown} error
|
|
62
67
|
* @param {string} filename
|
|
68
|
+
* @param {boolean} [thrown]
|
|
63
69
|
* @returns {NormalizedCompileError}
|
|
64
70
|
*/
|
|
65
|
-
function normalize_error(error, filename) {
|
|
71
|
+
function normalize_error(error, filename, thrown = false) {
|
|
66
72
|
if (error && typeof error === 'object') {
|
|
67
73
|
const candidate = /** @type {Record<string, unknown>} */ (error);
|
|
68
74
|
return {
|
|
@@ -70,6 +76,7 @@ function normalize_error(error, filename) {
|
|
|
70
76
|
code: candidate.code
|
|
71
77
|
? (LEGACY_CODES[String(candidate.code)] ?? String(candidate.code))
|
|
72
78
|
: null,
|
|
79
|
+
severity: !thrown && candidate.severity === 'warning' ? 'warning' : 'error',
|
|
73
80
|
type: candidate.type ? String(candidate.type) : null,
|
|
74
81
|
fileName: candidate.fileName ? String(candidate.fileName) : filename,
|
|
75
82
|
pos: typeof candidate.pos === 'number' ? candidate.pos : null,
|
|
@@ -81,6 +88,7 @@ function normalize_error(error, filename) {
|
|
|
81
88
|
return {
|
|
82
89
|
message: String(error),
|
|
83
90
|
code: null,
|
|
91
|
+
severity: 'error',
|
|
84
92
|
type: null,
|
|
85
93
|
fileName: filename,
|
|
86
94
|
pos: null,
|
|
@@ -142,8 +150,10 @@ function get_generated_css(result) {
|
|
|
142
150
|
* collect?: boolean,
|
|
143
151
|
* loose?: boolean,
|
|
144
152
|
* includeCode?: boolean,
|
|
145
|
-
* mode?: 'client' | 'server'
|
|
146
|
-
*
|
|
153
|
+
* mode?: 'client' | 'server',
|
|
154
|
+
* resolvePlatform?: boolean
|
|
155
|
+
* }} input `resolvePlatform: false` skips reading `tsrx.platform` from the
|
|
156
|
+
* tsconfig nearest the file, as the hosted server does.
|
|
147
157
|
*/
|
|
148
158
|
export async function compile_tsrx(input) {
|
|
149
159
|
const filename = input.filename ?? 'Component.tsrx';
|
|
@@ -165,6 +175,7 @@ export async function compile_tsrx(input) {
|
|
|
165
175
|
? detection.message
|
|
166
176
|
: `Could not infer a TSRX target. Pass target explicitly. ${detection.message}`,
|
|
167
177
|
code: null,
|
|
178
|
+
severity: /** @type {const} */ ('error'),
|
|
168
179
|
type: null,
|
|
169
180
|
fileName: filename,
|
|
170
181
|
pos: null,
|
|
@@ -189,6 +200,7 @@ export async function compile_tsrx(input) {
|
|
|
189
200
|
{
|
|
190
201
|
message: `Unknown TSRX target "${target}".`,
|
|
191
202
|
code: null,
|
|
203
|
+
severity: /** @type {const} */ ('error'),
|
|
192
204
|
type: null,
|
|
193
205
|
fileName: filename,
|
|
194
206
|
pos: null,
|
|
@@ -209,6 +221,32 @@ export async function compile_tsrx(input) {
|
|
|
209
221
|
const compiler_package =
|
|
210
222
|
target === 'hono' && input.mode === 'client' ? '@tsrx/hono/dom' : candidate.compilerPackage;
|
|
211
223
|
|
|
224
|
+
// A file without platform flags compiles the same for every platform, so a
|
|
225
|
+
// tsconfig graph that does not resolve one is only reported once the
|
|
226
|
+
// compiler asks for a platform.
|
|
227
|
+
/** @type {import('@tsrx/core/types').Platform | undefined} */
|
|
228
|
+
let platform;
|
|
229
|
+
/** @type {unknown} */
|
|
230
|
+
let platform_error = null;
|
|
231
|
+
if (input.resolvePlatform !== false) {
|
|
232
|
+
try {
|
|
233
|
+
platform = resolveBuildPlatform({
|
|
234
|
+
root: path.dirname(path.resolve(cwd, filename)),
|
|
235
|
+
integration: '@tsrx/mcp',
|
|
236
|
+
});
|
|
237
|
+
} catch (error) {
|
|
238
|
+
platform_error = error;
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
/** @param {NormalizedCompileError} error */
|
|
242
|
+
const explain_platform = (error) =>
|
|
243
|
+
platform_error !== null && error.code === DIAGNOSTIC_CODES.PLATFORM_REQUIRED
|
|
244
|
+
? {
|
|
245
|
+
...error,
|
|
246
|
+
message: `${error.message} The project's tsconfig did not resolve a platform: ${platform_error instanceof Error ? platform_error.message : String(platform_error)}`,
|
|
247
|
+
}
|
|
248
|
+
: error;
|
|
249
|
+
|
|
212
250
|
try {
|
|
213
251
|
const compiler = await import_compiler(compiler_package, cwd, detection.packageJsonPath);
|
|
214
252
|
if (typeof compiler.compile !== 'function') {
|
|
@@ -219,13 +257,15 @@ export async function compile_tsrx(input) {
|
|
|
219
257
|
collect: input.collect ?? true,
|
|
220
258
|
loose: input.loose,
|
|
221
259
|
mode: input.mode,
|
|
260
|
+
platform,
|
|
222
261
|
});
|
|
223
|
-
const errors = normalize_errors(result?.errors, filename);
|
|
262
|
+
const errors = normalize_errors(result?.errors, filename).map(explain_platform);
|
|
224
263
|
const code = get_generated_code(result);
|
|
225
264
|
const css = get_generated_css(result);
|
|
226
265
|
|
|
227
266
|
return {
|
|
228
|
-
|
|
267
|
+
// A warning doesn't fail the compile.
|
|
268
|
+
ok: errors.every((error) => error.severity === 'warning'),
|
|
229
269
|
target,
|
|
230
270
|
compilerPackage: compiler_package,
|
|
231
271
|
filename,
|
|
@@ -241,7 +281,7 @@ export async function compile_tsrx(input) {
|
|
|
241
281
|
compilerPackage: compiler_package,
|
|
242
282
|
filename,
|
|
243
283
|
cwd,
|
|
244
|
-
errors: [normalize_error(error, filename)],
|
|
284
|
+
errors: [explain_platform(normalize_error(error, filename, true))],
|
|
245
285
|
code: null,
|
|
246
286
|
css: null,
|
|
247
287
|
};
|
package/src/generated/docs.js
CHANGED
|
@@ -27,7 +27,7 @@ export const documentation_sections = [
|
|
|
27
27
|
use_cases:
|
|
28
28
|
'text children, jsx text, comments, string literals, expression containers, script elements, raw text',
|
|
29
29
|
content:
|
|
30
|
-
"# 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\nA `<script>` body is raw text, like a `<style>` body, in a template and in plain TSX: everything up to `</script>`, kept as written, with its comments, `<`, `>`, character references, and line breaks. `{…}` in it is text, not an expression container: `<script>{code}</script>` is a script whose text is `{code}`. The body ends at `</script`, optional whitespace, and `>`; any other `</script` in it, in any letter case, is the `TSRX1004` error, so write `<\\/script` instead. For a body computed at runtime, use the target's property on a self-closing `<script>`: `dangerouslySetInnerHTML={{ __html: code }}` in React, Preact, and Hono, `innerHTML={code}` in Solid and Vue. Whether a script runs is each target's decision.\n\nSpecification grammar:\n\n```text\nJSXTextChild :\n JSXTextCharacters\n\nJSXExpressionContainer :\n { AssignmentExpression }\n\nJSXCodeBlock :\n @{ TemplateSetupListopt TemplateOutput JSXStyleElementListopt }\n\nTemplateSetupList :\n TemplateSetupItem\n TemplateSetupList TemplateSetupItem\n\nTemplateSetupItem :\n StatementListItem\n JSXStyleElement\n\nJSXStyleElementList :\n JSXStyleElement\n JSXStyleElementList JSXStyleElement\n\nTemplateBlock :\n { TemplateChildrenopt }\n { TemplateSetupList TemplateOutput JSXStyleElementListopt }\n\nJSXIfExpression :\n @if ( Expression ) TemplateBlock\n @if ( Expression ) TemplateBlock @else TemplateBlock\n @if ( Expression ) TemplateBlock @else JSXIfExpression\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\nJSXElement :\n <script JSXAttributesopt> ScriptSourceopt ScriptEndTag\n <script JSXAttributesopt />\n\nScriptEndTag :\n </script HTMLWhitespaceopt >\n\nScriptSource :\n any source text that does not contain </script, in any letter case\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#templates, website-tsrx/src/pages/specification.tsrx#script",
|
|
30
|
+
"# 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\nAn `@` right before `{` opens a `@{ ... }` code block, in children too, so `<p>@{user.name}</p>` runs `user.name` as a statement and renders nothing (the `TSRX2035` warning). To render an `@` and then a value, write `<p>@{user.name}</p>`, ``<p>{`@${user.name}`}</p>``, or `<p>{'@' + user.name}</p>`.\n\nA `<script>` body is raw text, like a `<style>` body, in a template and in plain TSX: everything up to `</script>`, kept as written, with its comments, `<`, `>`, character references, and line breaks. `{…}` in it is text, not an expression container: `<script>{code}</script>` is a script whose text is `{code}`. The body ends at `</script`, optional whitespace, and `>`; any other `</script` in it, in any letter case, is the `TSRX1004` error, so write `<\\/script` instead. For a body computed at runtime, use the target's property on a self-closing `<script>`: `dangerouslySetInnerHTML={{ __html: code }}` in React, Preact, and Hono, `innerHTML={code}` in Solid and Vue. Whether a script runs is each target's decision.\n\nSpecification grammar:\n\n```text\nJSXTextChild :\n JSXTextCharacters\n\nJSXExpressionContainer :\n { AssignmentExpression }\n\nJSXCodeBlock :\n @{ TemplateSetupListopt TemplateOutput JSXStyleElementListopt }\n\nTemplateSetupList :\n TemplateSetupItem\n TemplateSetupList TemplateSetupItem\n\nTemplateSetupItem :\n StatementListItem\n JSXStyleElement\n\nJSXStyleElementList :\n JSXStyleElement\n JSXStyleElementList JSXStyleElement\n\nTemplateBlock :\n { TemplateChildrenopt }\n { TemplateSetupList TemplateOutput JSXStyleElementListopt }\n\nJSXIfExpression :\n @if ( Expression ) TemplateBlock\n @if ( Expression ) TemplateBlock @else TemplateBlock\n @if ( Expression ) TemplateBlock @else JSXIfExpression\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\nJSXElement :\n <script JSXAttributesopt> ScriptSourceopt ScriptEndTag\n <script JSXAttributesopt />\n\nScriptEndTag :\n </script HTMLWhitespaceopt >\n\nScriptSource :\n any source text that does not contain </script, in any letter case\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#templates, website-tsrx/src/pages/specification.tsrx#script",
|
|
31
31
|
},
|
|
32
32
|
{
|
|
33
33
|
slug: 'expression-values',
|
|
@@ -51,7 +51,7 @@ export const documentation_sections = [
|
|
|
51
51
|
use_cases:
|
|
52
52
|
'style expressions, scoped css, scoped style blocks, sibling scope, sibling-scoped styles, $class, apply, themes, class maps, :global, global selectors, unscoped selectors, escape scoping, third-party component styles, page-level styles, style diagnostics, module server, submodule imports, compile-time identifiers, ripple server modules, octane rpc, server functions',
|
|
53
53
|
content:
|
|
54
|
-
'# Style and Server Extensions\n\nA `<style>` block written as template content is a standalone block. It is a child of an element or fragment, and that children list is its sibling scope: the block styles its siblings and everything below them, and it never styles the element that contains it. The compiler rewrites every selector in the block to require a hash class: a class it adds to each element the block reaches, so the selectors match only there. Sibling blocks share one hash class; a nested children list with blocks of its own gets a hash class of its own. Every element gets the hash class of each scope around it, outer first. A `<style>` block is an output node, so in a `@{ ... }` or control-flow body wrap it with its output in a fragment (`<><style>...</style><div /></>`); a lone block there is an error. A block inside an `@if` or `@for` branch styles only the elements that branch renders. Its CSS is still always part of the file\'s stylesheet, whether or not the branch ever renders, because CSS is static. Raw CSS in `<style>` is TSRX template syntax: a block with CSS in it outside every `@{ ... }` and control-flow body is an error; in plain TSX write `<style>{css}</style>`, an ordinary element. A standalone block at module scope is an error: assign it instead.\n\n```tsx\nexport function Panel() @{\n <>\n <style>\n /* sibling scope A: the children list of this fragment */\n div { color: black; }\n </style>\n <div>Black</div>\n\n <style>\n /* still scope A: shares the hash of the first block */\n p { margin: 0; }\n </style>\n <p>No margin</p>\n\n <section>\n <style>\n /* sibling scope B: the children list of <section>, nested in A. It\n styles its siblings and everything below them, never <section>. */\n div { font-weight: bold; }\n </style>\n <div>Black and bold: A and B both reach here</div>\n </section>\n </>\n}\n\n// Stamped classes: the outer div, p, and section carry "<A>"; the nested div carries "<A> <B>".\n// Emitted CSS order: div.<A>, p.<A>, div.<B>.\n```\n\nAssign a `<style>` block to get an object: `$class` (the block\'s hash class, preceded by the `$class` of every block it applies) plus one property per class name (`styles.card`). Every assigned block is a theme and keeps every selector, element and descendant selectors included: `$class` is an ordinary string that any JavaScript use can carry to an element. `<style apply={theme} />` adds `theme.$class` to every element of a scope, `<style apply={theme}>...</style>` also declares local rules that come after the theme\'s and so win at equal specificity, and `class={theme.$class}` adds it to one element. `apply` takes an identifier, a member expression, or an array of those, and every target must be an assigned block that is imported or declared before the applying block.\n\n```tsx\n// theme.tsrx\nexport const base = <style>\n div { font-family: system-ui; }\n .muted { color: gray; }\n</style>;\n// base is { $class: "<base>", muted: "<base> muted" }\n\nexport const theme = <style apply={base}>\n div { color: green; }\n .dark { color: purple; }\n</style>;\n// theme.$class is "<base> <theme>"; theme.dark is "<theme> dark"\n\n// panel.tsrx\nimport { theme } from "./theme.tsrx";\n\nexport function Panel() @{\n <>\n <style apply={theme}>\n /* scope A; every element of A also carries theme.$class */\n div { color: black; }\n </style>\n <span class={theme.dark}>Purple</span>\n <div>Black: the local rule follows the sheet of theme</div>\n @{\n <>\n <style>div { font-weight: bold; }</style>\n <div>Carries "<A> <B> " + theme.$class</div>\n </>\n }\n </>\n}\n// Emitted CSS order: base, theme (theme.tsrx); then scope A, scope B (panel.tsrx).\n\n// card.tsrx: opting elements in with $class\nfunction Card({ parentClass }: { parentClass: string }) @{\n <>\n <style>.local { padding: 0; }</style>\n <article class={`local ${parentClass}`}>\n <h2 class={parentClass}>Title</h2>\n </article>\n </>\n}\n\nexport function App() @{\n const palette = <style>\n div { color: blue; }\n .card { color: red; }\n </style>;\n <>\n <Card parentClass={palette.$class} />\n <div class={palette.$class}>Blue: carries palette.$class</div>\n <div class={palette.card}>Red: carries palette.card</div>\n <p>Untouched: carries nothing from palette</p>\n </>\n}\n// palette is assigned, so it is a theme and div { color: blue } is kept.\n// <article> and <h2> carry palette.$class, then the hash of the scope of Card.\n```\n\nLater rules win: CSS is output in source order, outer first. Outer before inner: a scope\'s sheets come before the sheets of the scopes nested in it. Applied theme before the block that applies it: an applied block\'s CSS always comes before the CSS of the block that applies it. Source order within a scope: the later block wins.\n\n`:global(...)` marks the wrapped part of a selector as unscoped: it gets no hash class, everything outside the parentheses is still scoped, and it may only start or end a selector (`TSRX3011` otherwise). Bare `:global(.toast)` outputs `.toast`, a page-wide rule that matches anywhere on the page. Prefixed `.card :global(.note)` outputs `.card.<hash> .note`: only elements below the scoped `.card`, a child component\'s internals included, never upward. Leading `:global(.theme-dark) .card` outputs `.theme-dark .card.<hash>`, and compound `.card:global(.is-open)` outputs `.card.<hash>.is-open`. The block form `:global { .toast { ... } body { ... } }` drops its wrapper (left behind as a comment) and outputs `.toast { ... } body { ... }`, several page-wide rules at once. Both forms work with CSS nesting: `.card { :global { .note { ... } } }` and `.card { :global(.note) { ... } }` both output `.card.<hash> { .note { ... } }`, the same reach as the prefixed form with the scoped prefix written once, while plain nesting `.card { .note { ... } }` outputs `.card.<hash> { .note.<hash> { ... } }`, both parts scoped. A scoped rule adds one hash class to its first compound only; later compounds get `:where(.<hash>)`, which adds no specificity. So a scoped `.note.<hash>` (0,2,0) beats a bare `:global(.note)` (0,1,0) from anywhere, a `theme.$class` or class-map rule carries its hash and beats a bare global too, and a prefixed `.card.<hash> .note` (0,3,0) beats a child\'s own `.note.<hash>`.\n\nPrefer passing `theme.$class` (or a class-map entry) as a prop over `:global` for a child you own: the dependency is a visible prop, the child decides which elements receive it, renaming a class inside the child cannot silently break the parent, and the hash keeps the rule on the elements that carry it. With `:global` the child has no say and cannot see who styles it. To style several of a child\'s classes, nest one `:global { ... }` block under your scoped selector. Never write a bare `:global` selector or a top-level `:global { ... }` block for anything but page-level elements.\n\n| I want to ... | Use ... |\n| --- | --- |\n| Style my own elements | A `<style>` block beside them; nothing global |\n| Let a child component pick up my styles | Pass `theme.$class` or `theme.card` as a prop |\n| Style a child I cannot change (third-party, rendered HTML) | `.wrapper :global(.their-class)`, or `.wrapper { :global { ... } }` for several classes; scoped prefix first, keep it narrow |\n| React to page-level state | `:global(.theme-dark) .card` or `:global([data-theme=\'dark\']) .card` |\n| Style my element with a class another library toggles | `.card:global(.is-open)` |\n| Page-wide rules (`body`, resets, fonts) | A `.css` file; a bare `:global(body)` works but hides a global sheet in a component |\n\n`module server { ... }` declares an explicit server-oriented submodule in the Ripple and Octane host profiles. Ripple exposes proposal-aligned imports such as `import { load } from server`; Octane uses the file-local module specifier `import { load } from \'server\'` for RPC imports. Transport, serialization, and runtime behavior remain target-defined.\n\nFor Octane compiler, runtime, and validation guidance, use the Octane target documentation at https://octanejs.dev/llms.txt. The MCP `compile-tsrx` tool does not expose an Octane target.\n\nThe nested module scope gives host compilers and tooling a structural boundary for isolation and static analysis, including rejecting implicit cross-boundary captures and keeping server-only dependencies out of client output. It is not interchangeable with a target-specific `"use server"` directive.\n\nSpecification grammar:\n\n```text\nJSXStyleElement :\n <style JSXAttributesopt> CSSSource </style>\n <style JSXAttributesopt />\n\nStyleApplyValue :\n { StyleApplyTarget }\n { [ StyleApplyTargetListopt ] }\n\nStyleApplyTargetList :\n StyleApplyTarget\n StyleApplyTargetList , StyleApplyTarget\n\nStyleApplyTarget :\n IdentifierReference\n StyleApplyTarget . IdentifierName\n\nSubmoduleDeclaration :\n module Identifier { ModuleItemListopt }\n\nSubmoduleImportDeclaration :\n import ImportClause from Identifier ;\n\n```\n\nStatic constraints on style blocks, with their diagnostic codes:\n\n```text\nTSRX3007\n A standalone <style> block must sit inside a template scope. At module scope\n assign it: const theme = <style>...</style>.\nTSRX3009\n A standalone <style> block must be a child of an element or a fragment. As the\n lone output of a @{ ... } body or a control-flow body, or as a statement, it\n styles nothing: wrap it with the output it styles in a fragment. Beside another\n output node it is the ordinary multiple-outputs error.\nTSRX3008\n Raw CSS in <style> is TSRX template syntax. A standalone block with CSS text\n must sit lexically inside a @{ ... } body or an @if/@for/@switch/@try body, at\n any depth. In plain TSX give <style> an expression child (<style>{css}</style>)\n or assign the block. Head styles and resource styles are exempt.\nTSRX3010\n A scoped <style> block admits only the attributes ref and apply. Head styles\n and resource styles (href) admit any attribute.\nTSRX3001\n apply requires an expression container: apply={theme} or apply={[a, b]}.\n A bare attribute, a string value, or an empty container is an error.\nTSRX3004\n A <style> block carries at most one apply attribute; pass several targets\n as an array.\nTSRX3005\n apply is not admitted on a <head> style or on a resource style.\nTSRX3002\n Every apply entry is an identifier or non-computed member chain that resolves\n by lexical scoping to an assigned <style> block: a binding initialized with a\n block, an import, or a member of an import or of a module-local object literal\n whose property holds a block. Calls, conditionals, spreads, and holes are errors.\nTSRX3003\n A same-module target must be declared before the block that applies it, by\n source position; stricter than the temporal dead zone because same-module CSS\n is emitted in lexical order.\nTSRX3006\n An assigned block must not declare a class selector named $class.\nTSRX3011\n :global(...) may begin or end a selector sequence but not sit in its middle,\n and a bare :global must not be nested inside another pseudo-class.\nTSRX3012\n A style body must not contain an @import rule; the imported rules would not\n be scoped.\n\nEmission order (normative): outer scope before inner scope; applied block\nbefore the block that applies it; source order within one scope, later wins.\n```\n\nThe identifier-source import production describes Ripple\'s proposal-aligned form. Octane\'s quoted `\'server\'` specifier uses the ordinary TypeScript import grammar.\n\nSource: website-tsrx/src/pages/specification.tsrx#server-profile',
|
|
54
|
+
'# Style and Server Extensions\n\nA `<style>` block written as template content is a standalone block. It is a child of an element or fragment, and that children list is its sibling scope: the block styles its siblings and everything below them, and it never styles the element that contains it. The compiler rewrites every selector in the block to require a hash class: a class it adds to each element the block reaches, so the selectors match only there. Sibling blocks share one hash class; a nested children list with blocks of its own gets a hash class of its own. Every element gets the hash class of each scope around it, outer first. A `<style>` block is an output node, so in a `@{ ... }` or control-flow body wrap it with its output in a fragment (`<><style>...</style><div /></>`); a lone block there is an error. A block inside an `@if` or `@for` branch styles only the elements that branch renders. Its CSS is still always part of the file\'s stylesheet, whether or not the branch ever renders, because CSS is static. Raw CSS in `<style>` is TSRX template syntax: a block with CSS in it outside every `@{ ... }` and control-flow body is an error; in plain TSX write `<style>{css}</style>`, an ordinary element. A standalone block at module scope is an error: assign it instead.\n\n```tsx\nexport function Panel() @{\n <>\n <style>\n /* sibling scope A: the children list of this fragment */\n div { color: black; }\n </style>\n <div>Black</div>\n\n <style>\n /* still scope A: shares the hash of the first block */\n p { margin: 0; }\n </style>\n <p>No margin</p>\n\n <section>\n <style>\n /* sibling scope B: the children list of <section>, nested in A. It\n styles its siblings and everything below them, never <section>. */\n div { font-weight: bold; }\n </style>\n <div>Black and bold: A and B both reach here</div>\n </section>\n </>\n}\n\n// Stamped classes: the outer div, p, and section carry "<A>"; the nested div carries "<A> <B>".\n// Emitted CSS order: div.<A>, p.<A>, div.<B>.\n```\n\nAssign a `<style>` block to get an object: `$class` (the block\'s hash class, preceded by the `$class` of every block it applies) plus one property per class name (`styles.card`). Every assigned block is a theme and keeps every selector, element and descendant selectors included: `$class` is an ordinary string that any JavaScript use can carry to an element. `<style apply={theme} />` adds `theme.$class` to every element of a scope, `<style apply={theme}>...</style>` also declares local rules that come after the theme\'s and so win at equal specificity, and `class={theme.$class}` adds it to one element. `apply` takes an identifier, a member expression, or an array of those, and every target must be an assigned block that is imported or declared before the applying block.\n\n```tsx\n// theme.tsrx\nexport const base = <style>\n div { font-family: system-ui; }\n .muted { color: gray; }\n</style>;\n// base is { $class: "<base>", muted: "<base> muted" }\n\nexport const theme = <style apply={base}>\n div { color: green; }\n .dark { color: purple; }\n</style>;\n// theme.$class is "<base> <theme>"; theme.dark is "<theme> dark"\n\n// panel.tsrx\nimport { theme } from "./theme.tsrx";\n\nexport function Panel() @{\n <>\n <style apply={theme}>\n /* scope A; every element of A also carries theme.$class */\n div { color: black; }\n </style>\n <span class={theme.dark}>Purple</span>\n <div>Black: the local rule follows the sheet of theme</div>\n @{\n <>\n <style>div { font-weight: bold; }</style>\n <div>Carries "<A> <B> " + theme.$class</div>\n </>\n }\n </>\n}\n// Emitted CSS order: base, theme (theme.tsrx); then scope A, scope B (panel.tsrx).\n\n// card.tsrx: opting elements in with $class\nfunction Card({ parentClass }: { parentClass: string }) @{\n <>\n <style>.local { padding: 0; }</style>\n <article class={`local ${parentClass}`}>\n <h2 class={parentClass}>Title</h2>\n </article>\n </>\n}\n\nexport function App() @{\n const palette = <style>\n div { color: blue; }\n .card { color: red; }\n </style>;\n <>\n <Card parentClass={palette.$class} />\n <div class={palette.$class}>Blue: carries palette.$class</div>\n <div class={palette.card}>Red: carries palette.card</div>\n <p>Untouched: carries nothing from palette</p>\n </>\n}\n// palette is assigned, so it is a theme and div { color: blue } is kept.\n// <article> and <h2> carry palette.$class, then the hash of the scope of Card.\n```\n\nLater rules win: CSS is output in source order, outer first. Outer before inner: a scope\'s sheets come before the sheets of the scopes nested in it. Applied theme before the block that applies it: an applied block\'s CSS always comes before the CSS of the block that applies it. Source order within a scope: the later block wins.\n\n`:global(...)` marks the wrapped part of a selector as unscoped: it gets no hash class, everything outside the parentheses is still scoped, and it may only start or end a selector (`TSRX3011` otherwise). Bare `:global(.toast)` outputs `.toast`, a page-wide rule that matches anywhere on the page. Prefixed `.card :global(.note)` outputs `.card.<hash> .note`: only elements below the scoped `.card`, a child component\'s internals included, never upward. Leading `:global(.theme-dark) .card` outputs `.theme-dark .card.<hash>`, and compound `.card:global(.is-open)` outputs `.card.<hash>.is-open`. The block form `:global { .toast { ... } body { ... } }` drops its wrapper (left behind as a comment) and outputs `.toast { ... } body { ... }`, several page-wide rules at once. Both forms work with CSS nesting: `.card { :global { .note { ... } } }` and `.card { :global(.note) { ... } }` both output `.card.<hash> { .note { ... } }`, the same reach as the prefixed form with the scoped prefix written once, while plain nesting `.card { .note { ... } }` outputs `.card.<hash> { .note.<hash> { ... } }`, both parts scoped. A scoped rule adds one hash class to its first compound only; later compounds get `:where(.<hash>)`, which adds no specificity. So a scoped `.note.<hash>` (0,2,0) beats a bare `:global(.note)` (0,1,0) from anywhere, a `theme.$class` or class-map rule carries its hash and beats a bare global too, and a prefixed `.card.<hash> .note` (0,3,0) beats a child\'s own `.note.<hash>`.\n\nPrefer passing `theme.$class` (or a class-map entry) as a prop over `:global` for a child you own: the dependency is a visible prop, the child decides which elements receive it, renaming a class inside the child cannot silently break the parent, and the hash keeps the rule on the elements that carry it. With `:global` the child has no say and cannot see who styles it. To style several of a child\'s classes, nest one `:global { ... }` block under your scoped selector. Never write a bare `:global` selector or a top-level `:global { ... }` block for anything but page-level elements.\n\n| I want to ... | Use ... |\n| --- | --- |\n| Style my own elements | A `<style>` block beside them; nothing global |\n| Let a child component pick up my styles | Pass `theme.$class` or `theme.card` as a prop |\n| Style a child I cannot change (third-party, rendered HTML) | `.wrapper :global(.their-class)`, or `.wrapper { :global { ... } }` for several classes; scoped prefix first, keep it narrow |\n| React to page-level state | `:global(.theme-dark) .card` or `:global([data-theme=\'dark\']) .card` |\n| Style my element with a class another library toggles | `.card:global(.is-open)` |\n| Page-wide rules (`body`, resets, fonts) | A `.css` file; a bare `:global(body)` works but hides a global sheet in a component |\n\n`module server { ... }` declares an explicit server-oriented submodule in the Ripple and Octane host profiles. Ripple exposes proposal-aligned imports such as `import { load } from server`; Octane uses the file-local module specifier `import { load } from \'server\'` for RPC imports. Transport, serialization, and runtime behavior remain target-defined.\n\nFor Octane compiler, runtime, and validation guidance, use the Octane target documentation at https://octanejs.dev/llms.txt. The MCP `compile-tsrx` tool does not expose an Octane target.\n\nThe nested module scope gives host compilers and tooling a structural boundary for isolation and static analysis, including rejecting implicit cross-boundary captures and keeping server-only dependencies out of client output. It is not interchangeable with a target-specific `"use server"` directive.\n\nSpecification grammar:\n\n```text\nJSXStyleElement :\n <style JSXAttributesopt> CSSSource </style>\n <style JSXAttributesopt />\n\nStyleApplyValue :\n { StyleApplyTarget }\n { [ StyleApplyTargetListopt ] }\n\nStyleApplyTargetList :\n StyleApplyTarget\n StyleApplyTargetList , StyleApplyTarget\n\nStyleApplyTarget :\n IdentifierReference\n StyleApplyTarget . IdentifierName\n\nSubmoduleDeclaration :\n module Identifier { ModuleItemListopt }\n\nSubmoduleImportDeclaration :\n import ImportClause from Identifier ;\n\n```\n\nStatic constraints on style blocks, with their diagnostic codes:\n\n```text\nTSRX3007\n A standalone <style> block must sit inside a template scope. At module scope\n assign it: const theme = <style>...</style>.\nTSRX3009\n A standalone <style> block must be a child of an element or a fragment. As the\n lone output of a @{ ... } body or a control-flow body, or as a statement, it\n styles nothing: wrap it with the output it styles in a fragment. Beside another\n output node it is the ordinary multiple-outputs error.\nTSRX3008\n Raw CSS in <style> is TSRX template syntax. A standalone block with CSS text\n must sit lexically inside a @{ ... } body or an @if/@for/@switch/@try body, at\n any depth. In plain TSX give <style> an expression child (<style>{css}</style>)\n or assign the block. Head styles and resource styles are exempt.\nTSRX3010\n A scoped <style> block admits only the attributes ref and apply. Head styles\n and resource styles (href) admit any attribute.\nTSRX3001\n apply requires an expression container: apply={theme} or apply={[a, b]}.\n A bare attribute, a string value, or an empty container is an error.\nTSRX3004\n A <style> block carries at most one apply attribute; pass several targets\n as an array.\nTSRX3005\n apply is not admitted on a <head> style or on a resource style.\nTSRX3002\n Every apply entry is an identifier or non-computed member chain that resolves\n by lexical scoping to an assigned <style> block: a binding initialized with a\n block, an import, or a member of an import or of a module-local object literal\n whose property holds a block. Calls, conditionals, spreads, and holes are errors.\nTSRX3003\n A same-module target must be declared before the block that applies it, by\n source position; stricter than the temporal dead zone because same-module CSS\n is emitted in lexical order.\nTSRX3006\n An assigned block must not declare a class selector named $class.\nTSRX3011\n :global(...) may begin or end a selector sequence but not sit in its middle,\n and a bare :global must not be nested inside another pseudo-class.\nTSRX3012\n A style body must not contain an @import rule; the imported rules would not\n be scoped.\nTSRX3014\n A style element must not be rendered as an expression child: the expression of\n a child expression container, directly or as a branch of a conditional or\n logical expression. There it evaluates to its class map and styles nothing.\n\nEmission order (normative): outer scope before inner scope; applied block\nbefore the block that applies it; source order within one scope, later wins.\n```\n\nThe identifier-source import production describes Ripple\'s proposal-aligned form. Octane\'s quoted `\'server\'` specifier uses the ordinary TypeScript import grammar.\n\nSource: website-tsrx/src/pages/specification.tsrx#server-profile',
|
|
55
55
|
},
|
|
56
56
|
{
|
|
57
57
|
slug: 'dynamic-elements-and-components',
|
package/src/schemas.js
CHANGED
|
@@ -21,6 +21,7 @@ export const target_detection_schema = {
|
|
|
21
21
|
export const compile_error_schema = z.object({
|
|
22
22
|
message: z.string(),
|
|
23
23
|
code: z.string().nullable(),
|
|
24
|
+
severity: z.enum(['error', 'warning']),
|
|
24
25
|
type: z.string().nullable(),
|
|
25
26
|
fileName: z.string().nullable(),
|
|
26
27
|
pos: z.number().nullable(),
|
package/src/server.js
CHANGED
|
@@ -204,7 +204,8 @@ export function detect_target_handler(input = {}) {
|
|
|
204
204
|
* collect?: boolean,
|
|
205
205
|
* loose?: boolean,
|
|
206
206
|
* includeCode?: boolean,
|
|
207
|
-
* mode?: 'client' | 'server'
|
|
207
|
+
* mode?: 'client' | 'server',
|
|
208
|
+
* resolvePlatform?: boolean
|
|
208
209
|
* }} input
|
|
209
210
|
*/
|
|
210
211
|
export function compile_tsrx_handler(input) {
|
|
@@ -219,7 +220,8 @@ export function compile_tsrx_handler(input) {
|
|
|
219
220
|
* cwd?: string,
|
|
220
221
|
* collect?: boolean,
|
|
221
222
|
* loose?: boolean,
|
|
222
|
-
* mode?: 'client' | 'server'
|
|
223
|
+
* mode?: 'client' | 'server',
|
|
224
|
+
* resolvePlatform?: boolean
|
|
223
225
|
* }} input
|
|
224
226
|
*/
|
|
225
227
|
export function analyze_tsrx_handler(input) {
|
|
@@ -547,7 +549,9 @@ export function createTSRXMcpServer(options = {}) {
|
|
|
547
549
|
},
|
|
548
550
|
},
|
|
549
551
|
async (input) => {
|
|
550
|
-
const output = await compile_tsrx_handler(
|
|
552
|
+
const output = await compile_tsrx_handler(
|
|
553
|
+
remote ? { ...input, cwd: undefined, resolvePlatform: false } : input,
|
|
554
|
+
);
|
|
551
555
|
if (remote) output.cwd = 'remote';
|
|
552
556
|
return {
|
|
553
557
|
content: [{ type: 'text', text: json_text(output) }],
|
|
@@ -615,7 +619,9 @@ export function createTSRXMcpServer(options = {}) {
|
|
|
615
619
|
},
|
|
616
620
|
},
|
|
617
621
|
async (input) => {
|
|
618
|
-
const output = await analyze_tsrx_handler(
|
|
622
|
+
const output = await analyze_tsrx_handler(
|
|
623
|
+
remote ? { ...input, cwd: undefined, resolvePlatform: false } : input,
|
|
624
|
+
);
|
|
619
625
|
if (remote) output.cwd = 'remote';
|
|
620
626
|
return {
|
|
621
627
|
content: [{ type: 'text', text: json_text(output) }],
|