Octane Core Extend

Skill: Extend Octane core

Use this when changing core runtime, compiler, AST/TSRX transforms, SSR, hydration, or public octane APIs.

Read first

• AGENTS.md
• .rulesync/rules/core-engineering.md
• README.md
• docs/differences-from-react.md
• Owning source comments and nearby tests

Required preflight

Before editing, write down:

• the consumer-observable contract and invariants;
• affected execution modes (dev/prod, client/server, render/hydrate, error/abort);
• hot paths and expected call frequency: per render, node, item, event, signal notification, or request, versus once per root or module;
• a credible failing behavioral test for a bug, or a relevant benchmark baseline for an optimization;
• what the plan adds and the smaller alternatives you weighed, per concise-code.

Assume framework-fundamental code is performance-sensitive until the call graph shows otherwise. Use the performance-audit skill alongside this skill whenever the change can affect per-component, per-render, per-node, compiler-output, SSR, hydration, scheduling, reconciliation, or bundle costs.

Every change lands with a regression test

No exceptions, and not only for bug fixes. Core code multiplies across every Octane application, so each change ships with a test that would catch the regression it could introduce.

• Bug fix: the test reproduces the report and fails before the fix.
• New behavior: the test pins the new contract, and a separate one pins the neighbouring behavior the change could have disturbed.
• Refactor or optimization: behavior is supposed to be identical, so the test pins the behavior being preserved. "The existing tests still pass" is not enough on its own; if no existing test would have caught the breakage you were worried about, that gap is the test to add.

A test only counts once you have seen it fail. Break the implementation deliberately, confirm the test goes red, then restore. If it stays green it is not protecting anything.

Cover the execution modes the change actually reaches: dev and prod compile, client and server, render and hydrate, and the error, abort, and cleanup paths. Assert consumer-observable behavior, never internals; .rulesync/rules/testing.md sets the observation boundary and the harness to use.

Exact render counts, allocation identity, and codegen size are optimization claims, so they belong in the benchmark ratio system with semantic controls rather than in a correctness test.

Hot-path rules

The full rules, with the runtime code that already follows each one, are in performance-audit's references: V8 shapes, DOM work, and scheduling. The ones core changes break most often:

• Block and Scope shape. A new field on BlockImpl, ScopeImpl, or LiteBlockImpl is a declare field, initialized unconditionally in the constructor with null, undefined, or 0 when it is feature-only. Never write an undeclared field, even through (block as any). Before #990, 13 such writes forked the Block map until that PR declared and initialized their fields. Per-call-site state goes in scope.slots, not on the instance.
• Records. Build hot records in one literal or constructor with every key, in one order, across every allocation site. No delete, conditional spreads, or per-instance Object.freeze. Keep numeric fields integral and arrays packed.
• Reachability. Never name a heavy function from a compiled hot path. Optional features stay behind their driver or capability, and hydration-only reads behind hydrating guards that fold. Declare a driver above its readers and test it by truthiness (if (D), D ? D.f() : x), never D !== null or D?.f(), or Vite's minifier keeps the code it guards (see the driver declarations in runtime.ts).
• DOM. The commit writes and does not read geometry. Measure in a batched phase or after paint.
• Scheduling. scheduleRender coalesces a synchronous burst into one queueMicrotask(flush). Do not add a render or commit per microtask hop, value, item, or dispatch. Do not treat await, queueMicrotask, or requestAnimationFrame as a yield, and do not add another ad-hoc task poster. The microtask-batched contract in docs/differences-from-react.md §Scheduler changes only through issue #1864's decisions, never in passing.

Decide owner

• Client behavior/hooks/events/refs/scheduler/context/Suspense/transitions/reconciler: packages/octane/src/runtime.ts
• SSR/server render: packages/octane/src/runtime.server.ts, packages/octane/src/server/index.ts
• Compiler/AST/TSRX lowering/Vite/Volar: packages/octane/src/compiler/*
• Public API: packages/octane/src/index.ts, constants.ts, README/types/tests
• Vite metaframework behavior: packages/vite-plugin-octane/*

Compiler/AST workflow

1. Add a minimal .tsrx or .tsx fixture under packages/octane/tests/_fixtures/.
2. Add the regression test: assert runtime behavior, or emitted behavior through the public compiler path.
3. Inspect compile.js and any @tsrx/core AST assumptions.
4. Preserve source-location/dev diagnostics where applicable.
5. Ensure generated code still works with hook-slot injection and server/client paths.