@octanejs/mcp-server 0.2.23 → 0.2.25

package/README.md

@@ -167,7 +167,7 @@ one manifest suite by name (`js-framework`, `todomvc`, `weather-app`,
 `floating-tree-navigation`, `manifest-cache-invalidation`, `vite-client-assets`, `activity`,
 `streaming-ssr`, `streaming-backpressure`,
 `compiler-throughput`, `tsrx-component-graph`, `codegen-size`, `hook-memo`,
-`template-call-memo`, `tsrx-renderer-selection`, `bundle-size`, `bundle-reachability`, `three-renderer`,
+`transition-hooks`, `template-call-memo`, `tsrx-renderer-selection`, `bundle-size`, `bundle-reachability`, `three-renderer`,
 `three-bundle-size`, …)
 or every suite with `all`; `quick` selects the reduced-iteration smoke pass. The
 suite list mirrors the runner manifest and `node benchmarks/bench.mjs --list`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/mcp-server",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "type": "module",
   "engines": {
     "node": ">=22.22.2"

package/skills/build-octane-software.md

@@ -30,6 +30,15 @@ details but do not replace these gates.
   the retained state.
 - Use native event semantics. `onInput` is the per-edit event for text controls;
   do not add synthetic `onChange` compatibility or event wrapper allocation.
+- Style with sibling-scoped `<style>` blocks and assigned theme blocks
+  (`const theme = <style>…</style>`, `class={theme.card}`,
+  `<style apply={theme} />`) instead of a CSS-in-JS runtime. A block styles
+  the items beside it and everything below them, never the element that
+  contains it: put it beside the element in a fragment
+  (`<><style>…</style><div>…</div></>`), inside `@{ … }` and directive bodies
+  too. Keep block CSS static and pass runtime values through custom
+  properties. A block inside a control-flow branch ships its CSS whichever
+  branch renders, so keep branch-only rules small.
 - For SSR, avoid client/server data divergence and duplicate fetches. Exercise
   hydration with production-compiled output and preserve abort/error behavior.
 - Treat bundle size and dependency cost as performance. Check for an official

package/skills/migrate-react-component.md

@@ -45,6 +45,7 @@ locals, early returns) stays above it.
 | text `<input onChange={...}>` meaning every edit | `<input onInput={...}>` (native event) |
 | controlled `value={state}` | keep it — React's controlled semantics apply; pair with `onInput` |
 | `className={clsx(...)}` | `class={[...]}` composes clsx-style natively |
+| CSS Modules `styles.card` / CSS-in-JS | `const theme = <style>…</style>` (a class map: `$class` plus one key per class) and `class={theme.card}`; a `<style>` block among an element's or fragment's children styles the items beside it and below (never its container), and `<style apply={theme} />` applies a theme to those same items |
 | `useDebugValue(x)` | keep or delete — present as an accepted no-op |
 | `React.lazy(() => import(...))` | `lazy()` works as-is (and also accepts a bare component from the loader) |
 | `defaultProps` | parameter defaults / destructuring defaults |

package/skills/react-divergences.md

@@ -85,6 +85,28 @@ React's `{ default }` module shape works, and Octane additionally accepts a
 component directly from the loader. Suspense and ViewTransition are ordinary
 components, so wrapping them in `lazy()` is valid; nested lazy wrappers are not.
 
+## Scoped styles are sibling-scoped
+
+A `<style>` block with raw CSS is TSRX template syntax, not a global stylesheet
+as in React. It is a child of an element or a fragment and is scoped to its
+siblings, not to the `@{ … }` body around it: it styles the items beside it and
+everything below them — never the element that contains it —
+selectors are rewritten with the hash of that children list and the hash is
+stamped on those siblings and their descendants. To style an element, make the
+block and the element fragment siblings (`<><style>…</style><div>…</div></>`);
+a `@{ … }` or directive body holds one output node, so wrap the block and the
+output in a fragment there too. Nested scopes stack their hashes outer to
+inner; several blocks among the same children share one hash; `:global(…)` opts
+out. `const theme = <style>…</style>` yields a class map (`$class` plus one key
+per class) and `<style apply={theme} />` applies it to the items beside it,
+with `apply={[a, b]}` composing. A theme must be declared before its applier.
+The CSS of a control-flow branch is always emitted; only the stamping follows
+the branch. A raw-CSS block is allowed only inside a `@{ … }` or
+`@if`/`@for`/`@switch`/`@try` body; plain TSX keeps React's rule, where
+`<style>{css}</style>` is an ordinary element passed through untouched. Only
+`<style href precedence>` keeps React's Float semantics. Do not port this to
+CSS Modules or a CSS-in-JS runtime.
+
 ## class / className composes clsx-style
 
 Strings, numbers, arrays, objects, and nesting compose into a class string;

package/skills/setup-ssr.md

@@ -24,8 +24,10 @@ const { html, css } = await prerender(App, props, {
 - `html`: rendered markup with hydration markers, plus an inline suspense seed
   script when anything resolved. Hoisted `<title>/<meta>/<link>` fold in
   (spliced into `<head>` if present, else prepended).
-- `css`: deduped `<style data-octane>` tags from scoped styles; place inside
-  `<head>`.
+- `css`: deduped `<style data-octane>` tags from scoped styles, one per hash;
+  a component contributes one per style scope (nested `@{ … }` and
+  control-flow bodies have their own) plus one per assigned theme block. Place
+  them inside `<head>`.
 - Use `renderToString` (from `octane/server`) for a single synchronous pass that
   leaves `@pending` fallbacks in place; use `prerender` to await the data.
 - Options are optional: `nonce` stamps CSP nonces on the emitted inline tags (all
@@ -54,7 +56,9 @@ hydrateRoot(document.getElementById('app')!, App, props);
 ```
 
 Pass the same component and props on both sides. `useId` and scoped styles are
-hydration-stable; the client adopts server DOM instead of rebuilding it.
+hydration-stable, including the stacked scope hashes and applied theme classes
+(`<style apply={theme} />`, `theme.$class`); the client adopts server DOM
+instead of rebuilding it.
 
 ## Two integration paths
 

package/src/bridge.js

@@ -6,6 +6,7 @@ import { join, resolve } from 'node:path';
 // expected union from the workspace manifests, so publishing a new binding
 // without registering it in either catalog fails the mcp-server tests.
 export const KNOWN_BINDINGS = {
+	'react-is': '@octanejs/octane-is',
 	'@gsap/react': '@octanejs/gsap',
 	animejs: '@octanejs/animejs',
 	'usehooks-ts': '@octanejs/usehooks-ts',
@@ -67,6 +68,8 @@ export const KNOWN_BINDINGS = {
 	'react-hook-form': '@octanejs/hook-form',
 	'better-auth/react': '@octanejs/better-auth',
 	'@base-ui-components/react': '@octanejs/base-ui',
+	'@base-ui/react': '@octanejs/base-ui',
+	'@base-ui/utils': '@octanejs/base-ui-utils',
 	'@dnd-kit/react': '@octanejs/dnd-kit',
 	'embla-carousel-react': '@octanejs/embla-carousel',
 	'react-dropzone': '@octanejs/dropzone',
@@ -474,6 +477,20 @@ export async function collectSourceFiles(root, out = [], depth = 0) {
 
 export function scanSource(source) {
 	const apis = new Map();
+	const symbolExports = new Map();
+	// Introspection libraries export element-kind symbols, not components.
+	// Require the right-hand identifier to resolve to an actual Symbol.for
+	// declaration; ordinary component exports/render calls remain API uses.
+	const symbols = new Set(
+		[...source.matchAll(/\b([A-Za-z_$][\w$]*)\s*=\s*Symbol\.for\(\s*['"][^'"]+['"]\s*\)/g)].map(
+			(match) => match[1],
+		),
+	);
+	for (const match of source.matchAll(
+		/\bexports\.([A-Za-z_$][\w$]*)\s*=\s*([A-Za-z_$][\w$]*)\s*;/g,
+	)) {
+		if (symbols.has(match[2])) symbolExports.set(match[1], (symbolExports.get(match[1]) ?? 0) + 1);
+	}
 	for (const name of Object.keys(REACT_API_MAP)) {
 		if (name === 'onChange') continue;
 		const matches = source.match(new RegExp(`\\b${name}\\b`, 'g'));
@@ -493,13 +510,14 @@ export function scanSource(source) {
 		}
 	}
 	const classComponent = /\bextends\s+(React\.)?(Pure)?Component\b/.test(source);
-	return { apis, imports, classComponent };
+	return { apis, imports, classComponent, symbolExports };
 }
 
 export async function scanPath(root) {
 	const files = await collectSourceFiles(resolve(root));
 	const totals = new Map();
 	const imports = new Set();
+	const symbolExports = new Map();
 	let classComponents = false;
 	for (const file of files) {
 		let source;
@@ -513,14 +531,26 @@ export async function scanPath(root) {
 			totals.set(name, (totals.get(name) ?? 0) + count);
 		}
 		for (const spec of result.imports) imports.add(spec);
+		for (const [name, count] of result.symbolExports) {
+			symbolExports.set(name, (symbolExports.get(name) ?? 0) + count);
+		}
 		classComponents ||= result.classComponent;
 	}
-	return { filesScanned: files.length, totals, imports, classComponents };
+	return { filesScanned: files.length, totals, imports, classComponents, symbolExports };
 }
 
-function apiRows(totals) {
+function apiRows(totals, symbolExports) {
 	return [...totals.entries()]
-		.map(([name, count]) => ({ name, count, ...REACT_API_MAP[name] }))
+		.map(([name, count]) =>
+			symbolExports.get(name) === count
+				? {
+						name,
+						count,
+						status: 'rewrite',
+						note: 'Exported element-kind marker: map to the Octane kind; predicates for unsupported kinds remain false. This does not require rendering that component.',
+					}
+				: { name, count, ...REACT_API_MAP[name] },
+		)
 		.sort((a, b) => b.count - a.count);
 }
 
@@ -581,7 +611,7 @@ export async function bridgeReport({ packageName, path, projectRoot }) {
 	}
 
 	const scan = await scanPath(scanRoot);
-	const rows = apiRows(scan.totals);
+	const rows = apiRows(scan.totals, scan.symbolExports);
 	report.filesScanned = scan.filesScanned;
 	report.reactImports = [...scan.imports];
 	report.classComponents = scan.classComponents;
@@ -604,7 +634,7 @@ export function bridgeReportFromSource(source, { packageName } = {}) {
 		report.vanillaCore = detectVanillaCore(packageName, null);
 	}
 	const scan = scanSource(source);
-	const rows = apiRows(scan.apis);
+	const rows = apiRows(scan.apis, scan.symbolExports);
 	report.reactImports = [...scan.imports];
 	report.classComponents = scan.classComponent;
 	report.apis = rows;

package/src/bridge.test.js

@@ -41,6 +41,23 @@ describe('scanSource', () => {
 		expect(scanSource('class Memoish extends PureComponent {}').classComponent).toBe(true);
 	});
 
+	it('classifies symbol-kind exports without requiring the corresponding renderer', () => {
+		const report = bridgeReportFromSource(`
+			var REACT_PROFILER_TYPE = Symbol.for('react.profiler');
+			exports.Profiler = REACT_PROFILER_TYPE;
+			exports.isProfiler = value => value.type === REACT_PROFILER_TYPE;
+		`);
+		expect(report.apis.find((row) => row.name === 'Profiler').status).toBe('rewrite');
+		expect(report.verdict).toBe('bridgeable-with-rewrites');
+		const renderer = bridgeReportFromSource(`
+			import { Profiler } from 'react';
+			var REACT_PROFILER_TYPE = Symbol.for('react.profiler');
+			exports.Profiler = REACT_PROFILER_TYPE;
+			export const View = () => <Profiler />;
+		`);
+		expect(renderer.verdict).toBe('needs-rework');
+	});
+
 	it('targets only React-style text-host onChange wiring', () => {
 		const source = `
 			function Demo(props) {

package/src/index.js

@@ -79,6 +79,7 @@ export const BENCHMARK_SUITES = [
 	'radix-collection-order',
 	'router-dispatch',
 	'visx-categorical-scale',
+	'style-unitless',
 	'rspack-css-graph',
 	'floating-tree-navigation',
 	'ink-cursor-update',
@@ -114,6 +115,7 @@ export const BENCHMARK_SUITES = [
 	'lynx-bundle-size',
 	'codegen-size',
 	'hook-memo',
+	'transition-hooks',
 	'template-call-memo',
 	'compiler-throughput',
 	'tsrx-component-graph',