// ^ warns: did you mean `--cascivo-color-accent`? ``` Only the `--cascivo-` namespace is checked; your own custom properties are ignored. For the CSS half — and for `data-cascivo-*` selectors that match nothing — run `cascivo audit --ai`, which reports the same class at error level. ### Formatting: exclude vendored source from your formatter Owning the code means your formatter will reformat it, and `cascivo update` will then report drift on files you never edited. Add your `outputDir` to `.prettierignore` (or `.oxfmtignore`): ``` src/components/ui/ ``` `cascivo init` writes this for you when it finds a formatter config, and `cascivo doctor` reports it as a finding if it is missing. --- ## 1. `react-hooks/immutability` errors on every signal write **This affects every cascivo app, on both install paths.** It is not a strict-config problem — `eslint-plugin-react-hooks@7` with `recommended-latest` is what a stock 2026 React app gets. The error looks like this, and you will get one for every piece of state you wrote: ``` error Error: This value cannot be modified Modifying a value returned from a hook is not allowed. onValueChange={(v) => (env.value = v)} ^^^ `env` cannot be modified ``` The rule fires on assignments to a signal a hook returned — `open.value = !open.value` — which older cascivo docs taught as the way to write state. **Preferred fix: write through a setter.** Hold state with `useSignalState` and call its setter (`setOpen(!open.value)`); that is not a mutation, so the rule passes, and the same code compiles under the React Compiler (see [React Compiler](#react-compiler) below). [AI-RULES.md](/docs/ai-rules.md) and [HEADLESS.md](/docs/headless.md) teach this form. **If you have many existing assignments:** install `@cascivo/eslint-config` as above, or set the rule yourself: ```js { rules: { 'react-hooks/immutability': 'off' } } ``` **Why it can't be narrowed.** The rule cannot distinguish a deliberate signal write from an accidental mutation of `useState` output, and it offers no hook-name allowlist. Turning it off is the only mechanism available. **What that costs.** You lose the rule's protection against genuinely mutating React state elsewhere in your files. That is a real loss. If you would rather keep it, skip the `cascivoSignals` fragment and put a `// eslint-disable-next-line react-hooks/immutability` above each signal assignment instead. **Note the scope.** The directory-scoped recipe in §2 does **not** help here: signal writes live in your own page and component code, and on the prebuilt path (`@cascivo/react`) the `src/components/ui/**` directory does not exist at all. ### React Compiler Measured, not assumed — `apps/examples/react-vite` runs its tests a second time with its own source compiled by `babel-plugin-react-compiler` 1.x (`pnpm compiler:check`, in CI): - **`signal.value = next` does not compile.** The compiler rejects a component that assigns to a value returned from a hook ("This value cannot be modified") and, with `panicThreshold: 'all_errors'`, fails the build. With the default threshold it skips the component instead, so the component runs uncompiled — correct, but not optimized. - **Writing through a setter compiles, and updates correctly.** Hold state with `useSignalState` and call its setter; reading `signal.value` in render is fine: ```tsx const [open, setOpen] = useSignalState(false) // render: open.value · handlers: setOpen(!open.value) ``` A controlled prop bridged with `useControllableSignal` returns the same `[signal, setter]` pair and works the same way. Module-level `signal()`s can be assigned directly. The compiler tracks `open.value` as a dependency, so memoized output re-renders when the value changes — the example's interaction tests pass under it. - **The same form satisfies `react-hooks/immutability`**, so with setters you can keep that rule on instead of using the override above. cascivo's own components are unaffected either way: they ship `'use client'` and do not rely on compiler memoization. The rule applies to the signal-writing components _you_ write. --- ## 2. Host stylistic rules flag vendored source **Copy-paste path only.** When you `cascivo add` a component, you vendor its source into your project (`src/components/ui/**` by default). That code is generated-style code you own but did not write, and a strict host config — `@tanstack/eslint-config`, `eslint-config-airbnb`, a bespoke typescript-eslint strict setup — will flag it against **its** house style, not cascivo's. That is expected: cascivo's own lint bar (Oxlint) is deliberately not every downstream config's bar, and chasing every host's stylistic preferences inside vendored code is a losing game that `cascivo update` would undo on the next re-copy anyway. The fix is a one-time, durable ESLint override for your cascivo output directory — `@cascivo/eslint-config`'s `cascivoVendoredSource()` fragment is exactly the block below, or write it by hand: ### The recipe (flat config) Add this block to `eslint.config.js` (adjust the glob to your `outputDir` from `cascivo.config.ts` — the default is `src/components/ui/**`): ```js // eslint.config.js export default [ // …your existing config… { // Vendored cascivo source — you own it, but it is generated-style code. // Scope host stylistic rules off it; keep correctness rules on. files: ['src/components/ui/**'], rules: { // Style: `T[]` vs `Array`, import ordering, generic-param naming // (`Row` vs `TRow`), method-signature style — cascivo does not adopt these. '@typescript-eslint/array-type': 'off', '@typescript-eslint/naming-convention': 'off', '@typescript-eslint/method-signature-style': 'off', 'sort-imports': 'off', 'import/order': 'off', // Opinionated / misfires on legitimate cascivo patterns: 'react/no-array-index-key': 'off', // stable-content lists key by index intentionally 'no-shadow': 'off', // false-positives on TS declaration-merging (compound components) 'no-control-regex': 'off', // e.g. the log viewer strips ANSI escapes (\x1b) on purpose }, linterOptions: { // cascivo's rule-scoped `eslint-disable` directives may target rule ids // your config doesn't define — don't report them as "unused". reportUnusedDisableDirectives: 'off', }, }, ] ``` cascivo enforces the objective classes below in its own linter (oxlint) via `pnpm lint:host-strict`, so the copied source stays clean against a strict host config for every rule outside the scope-off list above. ### `.eslintrc` (legacy) equivalent ```json { "overrides": [ { "files": ["src/components/ui/**"], "rules": { "@typescript-eslint/array-type": "off", "@typescript-eslint/naming-convention": "off", "@typescript-eslint/method-signature-style": "off", "sort-imports": "off", "import/order": "off", "react/no-array-index-key": "off", "no-shadow": "off", "no-control-regex": "off" }, "linterOptions": { "reportUnusedDisableDirectives": false } } ] } ``` ## Why not just fix the vendored source? cascivo keeps the **objective** classes clean at the source — inline vs top-level type specifiers, unnecessary type assertions, `prefer-const`, and stale `eslint-disable` directives are treated as defects in the component library itself; the syntactic ones are enforced in CI by `pnpm lint:host-strict` (which runs oxlint, no ESLint dependency). What this page scopes off is the **stylistic** layer that is one config's opinion: generic-parameter naming (`Row` vs `TRow`), import ordering nuances, and unused- directive reporting for rule ids your config doesn't share. Those are not worth editing vendored files for, because: - `cascivo update` re-copies the source, so any manual edit is lost on the next update. - The readable single-letter-avoiding generic names (`Row`, `Column`) are part of the point of owning readable source; renaming them to `TRow` reduces readability to satisfy a naming convention cascivo intentionally does not adopt. ## See also - [GETTING-STARTED.md](/docs/getting-started.md) — install + the files the CLI manages. - [AI-RULES.md](/docs/ai-rules.md) — the reactivity contract that makes §1's rule fire. - [HEADLESS.md](/docs/headless.md) — the signal primitives, and the `open.value = !open.value` example the rule reports. - [TROUBLESHOOTING.md](/docs/troubleshooting.md) — keyed on the literal error text.