@tsrx/mcp 0.1.11 → 0.1.13
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/package.json +5 -5
- package/src/analyze.js +0 -11
- package/src/compile.js +34 -1
- package/src/generated/docs.js +4 -4
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.13",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"repository": {
|
|
9
9
|
"type": "git",
|
|
@@ -35,16 +35,16 @@
|
|
|
35
35
|
},
|
|
36
36
|
"dependencies": {
|
|
37
37
|
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
38
|
-
"prettier": "^3.9.
|
|
38
|
+
"prettier": "^3.9.9",
|
|
39
39
|
"zod": "^4.3.6",
|
|
40
|
-
"@tsrx/core": "0.
|
|
41
|
-
"@tsrx/prettier-plugin": "0.
|
|
40
|
+
"@tsrx/core": "0.5.0",
|
|
41
|
+
"@tsrx/prettier-plugin": "0.5.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.
|
|
47
|
+
"@tsrx/hono": "0.2.0"
|
|
48
48
|
},
|
|
49
49
|
"scripts": {
|
|
50
50
|
"generate:docs": "node scripts/generate-docs-index.js"
|
package/src/analyze.js
CHANGED
|
@@ -76,17 +76,6 @@ function create_advice(input) {
|
|
|
76
76
|
});
|
|
77
77
|
}
|
|
78
78
|
|
|
79
|
-
if (error_codes.has(DIAGNOSTIC_CODES.JSX_EXPRESSION_VALUE)) {
|
|
80
|
-
advice.push({
|
|
81
|
-
kind: 'jsx-expression-value',
|
|
82
|
-
severity: 'info',
|
|
83
|
-
title: 'Use JSX-shaped expression values',
|
|
84
|
-
message:
|
|
85
|
-
'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.',
|
|
86
|
-
documentation: ['tsrx://docs/expression-values.md'],
|
|
87
|
-
});
|
|
88
|
-
}
|
|
89
|
-
|
|
90
79
|
if (error_codes.has(DIAGNOSTIC_CODES.FORGOTTEN_STATEMENT_CONTAINER)) {
|
|
91
80
|
advice.push({
|
|
92
81
|
kind: 'forgotten-statement-container',
|
package/src/compile.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import path from 'node:path';
|
|
2
2
|
import { createRequire } from 'node:module';
|
|
3
3
|
import { pathToFileURL } from 'node:url';
|
|
4
|
+
import { DIAGNOSTIC_CODES } from '@tsrx/core';
|
|
4
5
|
import { detect_target, TARGET_CANDIDATES } from './target.js';
|
|
5
6
|
|
|
6
7
|
const VALID_TARGETS = new Set(TARGET_CANDIDATES.map((candidate) => candidate.target));
|
|
@@ -26,6 +27,36 @@ function get_target_candidate(target) {
|
|
|
26
27
|
return TARGET_CANDIDATES.find((candidate) => candidate.target === target) ?? null;
|
|
27
28
|
}
|
|
28
29
|
|
|
30
|
+
/**
|
|
31
|
+
* The codes of `@tsrx/core` before 0.5.0 (tsrx-org/tsrx#843), which a target's
|
|
32
|
+
* compiler built on an older core still reports, with today's code for each.
|
|
33
|
+
* @type {Record<string, string>}
|
|
34
|
+
*/
|
|
35
|
+
const LEGACY_CODES = {
|
|
36
|
+
'tsrx-platform-required': DIAGNOSTIC_CODES.PLATFORM_REQUIRED,
|
|
37
|
+
'tsrx-unclosed-tag': DIAGNOSTIC_CODES.UNCLOSED_TAG,
|
|
38
|
+
'tsrx-mismatched-closing-tag': DIAGNOSTIC_CODES.MISMATCHED_CLOSING_TAG,
|
|
39
|
+
'tsrx-template-expression-trailing-semicolon':
|
|
40
|
+
DIAGNOSTIC_CODES.TEMPLATE_EXPRESSION_TRAILING_SEMICOLON,
|
|
41
|
+
'tsrx-template-return-statement': DIAGNOSTIC_CODES.TEMPLATE_RETURN_STATEMENT,
|
|
42
|
+
'tsrx-forgotten-statement-container': DIAGNOSTIC_CODES.FORGOTTEN_STATEMENT_CONTAINER,
|
|
43
|
+
'tsrx-jsx-spread-child': DIAGNOSTIC_CODES.JSX_SPREAD_CHILD,
|
|
44
|
+
'tsrx-dynamic-tag-expression': DIAGNOSTIC_CODES.DYNAMIC_TAG_EXPRESSION,
|
|
45
|
+
'tsrx-style-apply-value': DIAGNOSTIC_CODES.STYLE_APPLY_VALUE,
|
|
46
|
+
'tsrx-style-apply-target': DIAGNOSTIC_CODES.STYLE_APPLY_TARGET,
|
|
47
|
+
'tsrx-style-apply-before-declaration': DIAGNOSTIC_CODES.STYLE_APPLY_BEFORE_DECLARATION,
|
|
48
|
+
'tsrx-style-apply-duplicate': DIAGNOSTIC_CODES.STYLE_APPLY_DUPLICATE,
|
|
49
|
+
'tsrx-style-apply-unsupported-host': DIAGNOSTIC_CODES.STYLE_APPLY_UNSUPPORTED_HOST,
|
|
50
|
+
'tsrx-style-reserved-class-key': DIAGNOSTIC_CODES.STYLE_RESERVED_CLASS_KEY,
|
|
51
|
+
'tsrx-style-standalone-at-module-scope': DIAGNOSTIC_CODES.STYLE_STANDALONE_AT_MODULE_SCOPE,
|
|
52
|
+
'tsrx-style-standalone-outside-template': DIAGNOSTIC_CODES.STYLE_STANDALONE_OUTSIDE_TEMPLATE,
|
|
53
|
+
'tsrx-style-standalone-needs-fragment': DIAGNOSTIC_CODES.STYLE_STANDALONE_NEEDS_FRAGMENT,
|
|
54
|
+
'tsrx-style-unknown-attribute': DIAGNOSTIC_CODES.STYLE_UNKNOWN_ATTRIBUTE,
|
|
55
|
+
'tsrx-css-global-placement': DIAGNOSTIC_CODES.CSS_GLOBAL_PLACEMENT,
|
|
56
|
+
'tsrx-css-import': DIAGNOSTIC_CODES.CSS_IMPORT,
|
|
57
|
+
'tsrx-script-end-tag-in-body': DIAGNOSTIC_CODES.SCRIPT_END_TAG_IN_BODY,
|
|
58
|
+
};
|
|
59
|
+
|
|
29
60
|
/**
|
|
30
61
|
* @param {unknown} error
|
|
31
62
|
* @param {string} filename
|
|
@@ -36,7 +67,9 @@ function normalize_error(error, filename) {
|
|
|
36
67
|
const candidate = /** @type {Record<string, unknown>} */ (error);
|
|
37
68
|
return {
|
|
38
69
|
message: candidate.message ? String(candidate.message) : String(error),
|
|
39
|
-
code: candidate.code
|
|
70
|
+
code: candidate.code
|
|
71
|
+
? (LEGACY_CODES[String(candidate.code)] ?? String(candidate.code))
|
|
72
|
+
: null,
|
|
40
73
|
type: candidate.type ? String(candidate.type) : null,
|
|
41
74
|
fileName: candidate.fileName ? String(candidate.fileName) : filename,
|
|
42
75
|
pos: typeof candidate.pos === 'number' ? candidate.pos : null,
|
package/src/generated/docs.js
CHANGED
|
@@ -25,9 +25,9 @@ export const documentation_sections = [
|
|
|
25
25
|
slug: 'text-and-template-expressions',
|
|
26
26
|
title: 'Text and Template Expressions',
|
|
27
27
|
use_cases:
|
|
28
|
-
'text children, jsx text, comments, string literals, expression containers',
|
|
28
|
+
'text children, jsx text, comments, string literals, expression containers, script elements, raw text',
|
|
29
29
|
content:
|
|
30
|
-
|
|
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",
|
|
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`). An assigned block that is exported, applied, or whose `$class` is read is a theme and keeps every selector; otherwise it is a class map and keeps only its class selectors. `<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.$class is read, so palette 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 (`tsrx-css-global-placement` 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\ntsrx-style-standalone-at-module-scope\n A standalone <style> block must sit inside a template scope. At module scope\n assign it: const theme = <style>...</style>.\ntsrx-style-standalone-needs-fragment\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.\ntsrx-style-standalone-outside-template\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.\ntsrx-style-unknown-attribute\n A scoped <style> block admits only the attributes ref and apply. Head styles\n and resource styles (href) admit any attribute.\ntsrx-style-apply-value\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.\ntsrx-style-apply-duplicate\n A <style> block carries at most one apply attribute; pass several targets\n as an array.\ntsrx-style-apply-unsupported-host\n apply is not admitted on a <head> style or on a resource style.\ntsrx-style-apply-target\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.\ntsrx-style-apply-before-declaration\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.\ntsrx-style-reserved-class-key\n An assigned block must not declare a class selector named $class.\ntsrx-css-global-placement\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.\ntsrx-css-import\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.\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',
|
|
@@ -59,7 +59,7 @@ export const documentation_sections = [
|
|
|
59
59
|
use_cases:
|
|
60
60
|
'dynamic elements, dynamic components, dynamic tag syntax, runtime tag, runtime component, removed <@tag syntax, removed Dynamic component',
|
|
61
61
|
content:
|
|
62
|
-
"# Dynamic Elements and Components\n\nUse the dynamic tag syntax `<{expression}>` when the element tag or component constructor is chosen at runtime. The expression can evaluate to a string tag name or a component value, and a non-self-closing element repeats the same expression in its closing tag: `</{expression}>`. No import is required; each target compiler lowers the form to its own runtime helper.\n\n```tsx\ntype Tag = 'section' | 'article';\n\nexport function Panel({ as = 'section', title }: { as?: Tag; title: string }) @{\n <{as} className=\"panel\">\n <h2>{title}</h2>\n </{as}>\n}\n```\n\nThe tag expression can be a string tag name or a component value:\n\n```tsx\nconst Body = expanded ? ExpandedBody : CompactBody;\n\n<{Body} item={item} />\n```\n\nThe tag expression must
|
|
62
|
+
"# Dynamic Elements and Components\n\nUse the dynamic tag syntax `<{expression}>` when the element tag or component constructor is chosen at runtime. The expression can evaluate to a string tag name or a component value, and a non-self-closing element repeats the same expression in its closing tag: `</{expression}>`. No import is required; each target compiler lowers the form to its own runtime helper.\n\n```tsx\ntype Tag = 'section' | 'article';\n\nexport function Panel({ as = 'section', title }: { as?: Tag; title: string }) @{\n <{as} className=\"panel\">\n <h2>{title}</h2>\n </{as}>\n}\n```\n\nThe tag expression can be a string tag name or a component value:\n\n```tsx\nconst Body = expanded ? ExpandedBody : CompactBody;\n\n<{Body} item={item} />\n```\n\nThe tag expression must be an identifier (`tag`), a member access including chains (`props.as`, `this.tag`, `registry[name]`, `items[0]`, where each computed key is an identifier, a string or number literal, or a member access), or a string literal (`'section'`). Any other expression is a compile error: a conditional, `||`, `??` or `&&`, parentheses and type-only wrappers (`as`, `satisfies`, `!`), optional member access, calls, `new`, spreads, string concatenation, template literals, assignments, sequences, functions, elements, and literals other than strings. A non-self-closing element repeats the expression in its closing tag, so compute anything more above the element and use the result: `const Tag = c ? Child : Fallback;` followed by `<{Tag} />`.\n\nFor React host classes, use `className`. For Preact, Solid, Vue, and Ripple host classes, use `class`.\n\nDo not use removed dynamic tag syntax such as `<@tag />` or `<@Component />`, and do not import a runtime `Dynamic` component with an `is` prop. Use `<{tag}>` instead.\n\nSource: website-tsrx/src/pages/features.tsrx#dynamic",
|
|
63
63
|
},
|
|
64
64
|
{
|
|
65
65
|
slug: 'target-integration',
|