octane 0.1.1

package/src/compiler/index.js

@@ -0,0 +1,3 @@
+export { compile } from './compile.js';
+export { octane } from './vite.js';
+export { compileToVolarMappings } from './volar.js';

package/src/compiler/vite.js

@@ -0,0 +1,47 @@
+/**
+ * Vite plugin for compiling .tsrx files via octane-ts/compiler compiler.
+ *
+ * Per-module target is chosen from Vite's SSR signal: a module compiled for the
+ * server environment uses `mode: 'server'` (SSR HTML output), everything else
+ * uses `mode: 'client'` (template-clone DOM runtime). This auto-detection is
+ * what a standard Vite SSR setup relies on — the SAME `.tsrx` is compiled to
+ * client code for the browser bundle and to server code when loaded through
+ * `ssrLoadModule` / an SSR build (see playground/octane-ssr).
+ *
+ * Options:
+ *   - `ssr`: force the target for EVERY module — `true` always compiles server
+ *     mode, `false` always client. Leave it unset (the default) to use the
+ *     per-module auto-detection above. Useful for a dedicated server build.
+ *   - `hmr`: defaults to on in serve mode and is always off for SSR; pass
+ *     `true`/`false` to override the client default.
+ */
+import { compile } from './compile.js';
+
+export function octane(options = {}) {
+	let hmrEnabled = options.hmr;
+	// An explicit override of the per-module SSR auto-detection (true → always
+	// server, false → always client). `undefined` keeps auto-detection.
+	const forceSsr = options.ssr;
+	return {
+		name: 'octane',
+		enforce: 'pre',
+		configResolved(config) {
+			if (hmrEnabled === undefined) hmrEnabled = config.command === 'serve';
+		},
+		transform(code, id, transformOptions) {
+			if (!id.endsWith('.tsrx')) return null;
+			// Mirror Ripple's mode decision: an explicit `options.ssr` override wins;
+			// otherwise Vite's transform-level SSR flag OR the environment consumer
+			// (Vite 6+ environment API) marks a server build.
+			const ssr =
+				forceSsr !== undefined
+					? forceSsr
+					: transformOptions?.ssr === true || this.environment?.config?.consumer === 'server';
+			const out = compile(code, id, {
+				hmr: !ssr && !!hmrEnabled,
+				mode: ssr ? 'server' : 'client',
+			});
+			return { code: out.code, map: out.map };
+		},
+	};
+}

package/src/compiler/volar.js

@@ -0,0 +1,121 @@
+/**
+ * Volar (IDE language-service) mappings for octane .tsrx files.
+ *
+ * Editors load this entry point to get a TYPED virtual TSX file the
+ * TypeScript language service can analyse — hover, autocomplete, go-to-def,
+ * diagnostics — without ever running our template-clone codegen. The TSX
+ * output is intentionally NOT the same shape as the runtime emit produced
+ * by `compile()`: it's a parallel pipeline that runs `@tsrx/core`'s shared
+ * `createJsxTransform` (the same machinery that powers tsrx-react / tsrx-
+ * preact's Volar paths) in `typeOnly: true` mode.
+ *
+ * Caller contract:
+ *   - Input: the original .tsrx source string + filename.
+ *   - Output: a `VolarMappingsResult` (see @tsrx/core/types) containing
+ *     `code` (generated TSX), `mappings` (per-token offsets the language
+ *     server uses to translate position queries from .tsrx → virtual TSX
+ *     and back), `cssMappings`, `errors`, and the source AST.
+ *
+ * Why a separate file: `compile.js` is the runtime-codegen path and ships
+ * to every consumer (Vite plugin, build pipeline). The Volar path pulls in
+ * extra @tsrx/core surface (`createJsxTransform`, `createVolarMappingsResult`,
+ * `dedupeMappings`) that build-time consumers don't need; isolating it
+ * keeps the runtime build small.
+ */
+
+import {
+	createJsxTransform,
+	createVolarMappingsResult,
+	dedupeMappings,
+	parseModule,
+} from '@tsrx/core';
+
+/**
+ * Platform descriptor for `createJsxTransform`. Mirrors `tsrx-react`'s React
+ * descriptor with the small set of differences for octane:
+ *
+ *   - `imports.errorBoundary` / `imports.dynamic` point at octane
+ *     itself (we don't ship separate sub-packages for these — the runtime
+ *     exports them directly).
+ *   - `jsx.classAttrName: 'class'` because octane keeps authored
+ *     `class` instead of rewriting to React's `className`.
+ *   - `jsx.multiRefStrategy: 'array'` — the octane runtime accepts a
+ *     plain array of refs natively (see the multi-ref attribute path in
+ *     `src/runtime.ts`'s ref binding), so no `mergeRefs` helper is needed.
+ *   - `validation.requireUseServerForAwait: false` — no server-component
+ *     concept in octane (no top-level await validation gates).
+ *
+ * `imports.suspense` and `imports.fragment` aren't real components in
+ * octane (we lower `@try`/`@pending` to `tryBlock` and fragments to
+ * concrete templates), but the descriptor still needs a value because the
+ * shared transform emits TSX-level `<Fragment>` / `<Suspense>` wrappers
+ * when running in TSX mode. We point them at `octane` so editors at
+ * least don't fail to resolve the imports; users won't actually see those
+ * names in source. (Volar TSX is virtual — its imports never run.)
+ */
+const OCTANE_PLATFORM = {
+	name: 'octane',
+	imports: {
+		fragment: 'octane-ts',
+		suspense: 'octane-ts',
+		dynamic: 'octane-ts',
+		errorBoundary: 'octane-ts',
+		forOfIterableHelper: '@tsrx/core/runtime/iterable',
+	},
+	jsx: {
+		rewriteClassAttr: false,
+		classAttrName: 'class',
+		multiRefStrategy: 'array',
+	},
+	validation: {
+		requireUseServerForAwait: false,
+	},
+};
+
+const octaneTransform = createJsxTransform(OCTANE_PLATFORM);
+
+/**
+ * Compile a .tsrx source string to a Volar `VolarMappingsResult`.
+ *
+ * Parse → JSX transform (typeOnly) → wrap as Volar payload. We always run
+ * with `collect: true` so the parser records errors instead of throwing
+ * mid-pipeline; that way a syntactically-broken file still produces a
+ * partial virtual TSX the language server can show diagnostics against.
+ *
+ * @param {string} source
+ * @param {string} [filename]
+ * @param {{ loose?: boolean }} [options]
+ * @returns {import('@tsrx/core/types').VolarMappingsResult}
+ */
+export function compileToVolarMappings(source, filename, options) {
+	/** @type {import('@tsrx/core/types').CompileError[]} */
+	const errors = [];
+	/** @type {import('@tsrx/core/types').AST.CommentWithLocation[]} */
+	const comments = [];
+	const ast = parseModule(source, filename, {
+		...options,
+		collect: true,
+		loose: !!options?.loose,
+		errors,
+		comments,
+	});
+	const transformed = octaneTransform(ast, source, filename, {
+		collect: true,
+		loose: !!options?.loose,
+		typeOnly: true,
+		errors,
+		comments,
+	});
+	const result = createVolarMappingsResult({
+		ast: transformed.ast,
+		ast_from_source: ast,
+		source,
+		generated_code: transformed.code,
+		source_map: transformed.map,
+		errors,
+	});
+	return {
+		...result,
+		mappings: dedupeMappings(result.mappings),
+	};
+}

package/src/constants.ts

@@ -0,0 +1,45 @@
+/**
+ * Hydration marker protocol — the single source of truth shared by the server
+ * emit (the `octane-ts/compiler` compiler's server mode) and the client `hydrate`
+ * runtime. The server writes these comment markers into the HTML it produces and
+ * the client hydration cursor scans for them to align with the server output, so
+ * BOTH sides must use byte-identical strings or hydration fails.
+ *
+ * Values follow the Svelte/Ripple convention (`[` open, `]` close) so the
+ * protocol is familiar and the marker comments are compact.
+ *
+ * Nothing emits these yet — SSR codegen and the hydrate runtime are built in
+ * later phases of the SSR plan. This module is the shared home they'll import.
+ */
+
+/** Single-character payload of a block-open comment. */
+export const HYDRATION_START = '[';
+/** Single-character payload of a block-close comment. */
+export const HYDRATION_END = ']';
+
+/** Opens a hydratable block (component output / control-flow branch). */
+export const BLOCK_OPEN = `<!--${HYDRATION_START}-->`;
+/** Closes a hydratable block. */
+export const BLOCK_CLOSE = `<!--${HYDRATION_END}-->`;
+/** A bare anchor comment used where the client would otherwise clone a `<!>`. */
+export const EMPTY_COMMENT = '<!---->';
+
+/**
+ * Marker attribute on the inline `<script type="application/json">` that the
+ * server emits to carry the JSON-serialized `use(thenable)` values it resolved
+ * during render (SSR Phase 4 — Suspense). The client `hydrate()` finds this
+ * script by attribute, parses it, and seeds the values back into `use()` (in
+ * render order) so a hydrating boundary returns synchronously instead of
+ * re-suspending. Shared so server emit and client read stay byte-identical.
+ */
+export const SUSPENSE_SCRIPT_ATTR = 'data-octane-suspense';
+
+/**
+ * Sentinel marker for a `use(thenable)` value that resolved to `undefined`.
+ * JSON can't represent `undefined` (an array element round-trips to `null`, an
+ * object property is dropped), so the server's seed serializer encodes any
+ * `undefined` as `{ [UNDEFINED_SENTINEL_KEY]: true }` and the client's parser
+ * reviver decodes it back to `undefined`. Shared so both sides agree, and keyed
+ * obscurely enough that real resolved data won't collide.
+ */
+export const UNDEFINED_SENTINEL_KEY = '__octane_new_undefined__';

package/src/index.ts

@@ -0,0 +1,102 @@
+import pkg from '../package.json' with { type: 'json' };
+
+// Source the version from package.json so it can't drift from the published
+// package version (the previous hardcoded literal already had).
+export const version: string = pkg.version;
+
+export {
+	// Public API
+	createRoot,
+	hydrate,
+	flushSync,
+	drainPassiveEffects,
+	act,
+	setIsOctaneActEnvironment,
+	type Root,
+
+	// Hooks
+	useState,
+	useReducer,
+	useEffect,
+	useLayoutEffect,
+	useInsertionEffect,
+	useMemo,
+	useCallback,
+	useRef,
+	useId,
+	useImperativeHandle,
+	useEffectEvent,
+	useSyncExternalStore,
+	useDeferredValue,
+	useTransition,
+	useActionState,
+	useFormStatus,
+	useOptimistic,
+	type FormStatus,
+	startTransition,
+	setTransitionFallbackTimeout,
+	getTransitionFallbackTimeout,
+	memo,
+
+	// Context
+	createContext,
+	provideContext,
+	use,
+	useContext,
+	type Context,
+
+	// Suspense / error boundaries as JSX components (alongside the @try directive)
+	Suspense,
+	ErrorBoundary,
+
+	// HMR (compiler-emitted when the Vite plugin's hmr option is on)
+	hmr,
+	HMR,
+
+	// Compiler-emitted runtime helpers
+	template,
+	clone,
+	htext,
+	htextSwap,
+	child,
+	sibling,
+	setText,
+	setAttribute,
+	setClassName,
+	setStyle,
+	setSpread,
+	setFormAction,
+	attachRef,
+	queueRefAttach,
+	injectStyle,
+	headBlock,
+	delegateEvents,
+	forBlock,
+	ifBlock,
+	tryBlock,
+	switchBlock,
+	activityBlock,
+	Activity,
+	componentSlot,
+	componentSlotLite,
+	childSlot,
+	hostComponent,
+	Fragment,
+	FragmentInstance,
+	mountFragmentRef,
+	portal,
+	createPortal,
+	type PortalDescriptor,
+	createElement,
+	type ElementDescriptor,
+	withScope,
+	renderBlock,
+	createBlock,
+	unmountBlock,
+	scheduleRender,
+	getCurrentScope,
+	getCurrentBlock,
+	type ComponentBody,
+	type Scope,
+	type Block,
+} from './runtime';