octanejs/octane / .rulesync/skills/octane-core-extend
octane-core-extend
VerifiedChange Octane's runtime, compiler, scheduler, reconciler, SSR, or hydration engine. Use before editing packages/octane/src. Covers the observable contract, hot-path analysis, and the performance evidence required before handoff.
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.mdREADME.mddocs/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, orLiteBlockImplis adeclarefield, initialized unconditionally in the constructor withnull,undefined, or0when 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 inscope.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-instanceObject.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
hydratingguards that fold. Declare a driver above its readers and test it by truthiness (if (D),D ? D.f() : x), neverD !== nullorD?.f(), or Vite's minifier keeps the code it guards (see the driver declarations inruntime/drivers.ts). - DOM. The commit writes and does not read geometry. Measure in a batched phase or after paint.
- Scheduling.
scheduleRendercoalesces a synchronous burst into onequeueMicrotask(flush). Do not add a render or commit per microtask hop, value, item, or dispatch. Do not treatawait,queueMicrotask, orrequestAnimationFrameas a yield, and do not add another ad-hoc task poster. The microtask-batched contract indocs/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: the concept module in
packages/octane/src/runtime/(runtime.tsre-exports them) - 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
- Add a minimal
.tsrxor.tsxfixture underpackages/octane/tests/_fixtures/. - Add the regression test: assert runtime behavior, or emitted behavior through the public compiler path.
- Inspect
compile.jsand any@tsrx/coreAST assumptions. - Preserve source-location/dev diagnostics where applicable.
- Ensure generated code still works with hook-slot injection and server/client paths.
Runtime workflow
- Add the regression test before patching, and watch it fail.
- Identify whether behavior is mount, update, deletion, hydration, event delegation, scheduling, or effect flushing.
- Read nearby runtime comments; treat them as design spec.
- Preserve intentional divergences from React.
- For React parity, use conformance or differential harness appropriately.
Public API workflow
- Update exports, and add a test covering the new or changed surface.
- Update README/docs if user-facing.
- Add changeset unless docs/test-only.
- Consider ecosystem binding impacts and aliases in
vitest.config.js.
Strong diagnostics
A new or changed OCTANE_STRONG_* code, or a new hook that replaces a pattern
Strong rejects, belongs in packages/octane/src/compiler/strong-diagnostics.js.
Add its entry, and a recipe when it replaces a React idiom, then run
pnpm strong:diagnostics. That regenerates the website reference, llms.txt,
docs/strong-compiler-checks.md, and the MCP server's copy, and
strong-diagnostics-catalog.test.ts fails on a code without an entry or a
recipe the compiler does not accept. The message should name the replacement
API; the compile error is the documentation an agent reads first.
Validation
- New/changed targeted tests.
- Nearby core tests.
pnpm typecheckfor API/compiler TS changes.pnpm testfor broad runtime/compiler changes when feasible.- The relevant benchmark suite before and after performance-sensitive changes, using the same environment, warmup, iterations, and semantic controls. Run only the owning suite locally; CI runs the wide ones.
- The
perf-reviewskill on the final diff (node scripts/perf-review-scan.mjs), with everymust-fixfinding resolved and the report in the handoff. pnpm format:files <path...>while iterating andpnpm format:files:check <path...>for a scoped check.
Risk checks
- Does the change alter hook slot stability?
- Does it change SSR/hydration consistency?
- Does it change event semantics from native to synthetic? If yes, likely wrong.
- Does it add React controlled-input behavior? If yes, likely intentional divergence violation.
- Does keyed reconciliation preserve final DOM and survivor identity?
- Are
tsrxandtsx/jsxpaths both considered? - Does it add a field, receiver map, or allocation to a per-render or per-node path?
- Can a burst of ready values, dispatches, or notifications now render or commit once per microtask hop?
- Does a hot or compiled path now reach code it did not reach before?
Adversarial self-review
Inspect the complete diff after validation. Try applicable empty, large,
repeated, nested, reordered, reentrant, error, abort, cleanup, and hydration
cases. Trace each allocation and retained reference through release, inspect
adjacent fast paths and every changed caller, compare with a simpler design, and
remove complexity that does not justify its permanent cost, using the
concise-code simplification pass. Resolve findings and
repeat the review on the final diff.
The handoff must report the contract, correctness evidence, measured baseline and candidate deltas (or why trustworthy measurement was impossible), self-review improvements, and residual risk.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |