@tsrx/mcp 0.1.18 → 0.1.20

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 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.18",
6
+ "version": "0.1.20",
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.5.4",
41
- "@tsrx/prettier-plugin": "0.6.2"
40
+ "@tsrx/prettier-plugin": "0.7.0",
41
+ "@tsrx/core": "0.6.0"
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.2.4"
47
+ "@tsrx/hono": "0.3.0"
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 (advice.length === 0 && compileResult.ok) {
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>&#64;{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
- if (advice.length === 0) {
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
- * }} input
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
- ok: errors.length === 0,
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
  };
@@ -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>&#64;{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(remote ? { ...input, cwd: undefined } : input);
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(remote ? { ...input, cwd: undefined } : input);
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) }],