Changelog

The toast was already there

shadcn added a new Toast component built on Base UI. Applications installed @base-ui/react, imported Toast from @base-ui/react/toast, and mounted the generated Toaster from their app shell. The notification infrastructure was real and reachable, but shadscan still failed both toast checks.

The mismatch was in package identity. Existing toast runtimes use the same string in package.json and in source imports. Base UI does not: the installed package is @base-ui/react, while the toast runtime lives at its /toast subpath. The detector required an exact dependency/import match and stopped before following the mounted wrapper.

Package and subpath are now linked

Toast runtime detection now describes the dependency and import path separately. A mounted local Toaster can resolve through project-owned wrappers to @base-ui/react/toast, while dependency verification still checks for the actual @base-ui/react package.

Both toast-provider-present and toast-provider-mounted use the same runtime analysis, so they now agree on the Base UI setup and cite the toast subpath in their evidence.

What still does not count

Installing Base UI alone is not enough. Importing a button, dialog, or any other Base UI primitive from another subpath does not qualify, and a local component named Toaster without runtime provenance still fails. The provider must remain mounted from a supported app shell, directly or through a resolvable local wrapper.

This is a recognition fix only. Rule IDs, scoring weights, report schemas, and the bundled ruleset version do not change.

Earning the right to matter

button-group-holds-only-buttons shipped in 0.10.0 as an advisory. It caught a real defect — a text input joined to a button inside ButtonGroup, where the focus ring wraps the input and stops dead where the button begins — but it had only been checked against one author's projects, which is not enough evidence to start moving other people's scores.

It is now worth two points, and it is stricter about what it will penalise. It evaluates compositions that are actually mounted on a render surface rather than any that appear in source, and anything it cannot prove — a customized ButtonGroup, a composition it can only partly resolve — is reported as an advisory instead of costing you anything.

It also follows more of the ways people build forms: shadcn's FormField render prop, and bare react-hook-form Controller, which is what FormField wraps and what plenty of projects reach for directly.

The provider that hid an entire app

Promoting the rule surfaced something worse than the rule itself.

Rendered-surface analysis walks from a route down through everything it renders. When it met a component it could not see inside — a provider from a package, wrapping {children} — it stopped. In one real project, a single NuqsAdapter in the root layout meant the scanner reached one file in the entire application, and reported that surface as complete while doing so. Nothing downstream could tell that the evidence was missing.

Expansion now continues through wrappers that are known to render their children and nothing else: React's own Suspense, Fragment, StrictMode and Profiler, and the nuqs adapters, joining the next-themes and Radix navigation cases already handled. In that same project the scanner went from one file to twenty-four.

This is not a ButtonGroup fix. Any rule that reasons about what a route actually renders was working from the same truncated picture.

What it still cannot see

A provider written in your own project whose children projection cannot be proven still stops expansion. The difference is that those surfaces are marked incomplete, with the reason attached, rather than passed off as complete.

That honesty matters more than the coverage: a rule that knows what it has not seen can stay quiet, and a scanner that quietly guesses is worse than one that admits a gap.

What to expect on upgrade

If you join a text input to a button inside ButtonGroup on a page that actually renders, you will lose two points and get told where. The remedy is InputGroup, which is shadcn's component for exactly that composition and lights the whole control on focus rather than half of it.

The bundled ruleset advances to 2026.08.46.

Silence reads as failure

The source audit is fast enough that nobody wonders whether it hung. A rendered check is not: it starts a browser, resolves the target, loads each route, and lays every one out at two viewports. That is several seconds where a terminal showing nothing looks indistinguishable from a terminal that has stopped.

--check-ui now shows its work, in the same three phases it actually performs:

Resolving UI target
Checking mobile and desktop layouts
Preparing UI report

The checklist appears immediately rather than after the first phase finishes, and completed phases stay on screen. This is the treatment interactive scans have had since 0.8.0, applied to the check that needed it more.

Quiet whenever something is reading

Progress output is for a person watching a terminal, and for nobody else.

It goes to stderr, never stdout, so a piped or redirected report is byte-identical to before — the contract that lets --json be consumed by a script without filtering anything out. And it suppresses itself entirely under --json, in CI, under TERM=dumb, when stderr is not a terminal, and when you pass --no-interactive.

The rule of thumb is unchanged from the audit's own progress: if anything other than a human is likely reading, print nothing.

Nothing else moves

No new rule, no scoring change, no schema change. The bundled ruleset stays at 2026.08.45. This release only affects what you see while a check is running, not what it decides.

A command, not a flag per bug

Last release added --check-overflow: open the running app, fail if the page scrolls sideways. The check was right and the name was too small. Horizontal overflow is the first thing worth checking in a real browser, not the only one, and naming the command after one bug means a new flag for every bug after it.

So the public entry point is now --check-ui, with overflow as its first check and room for the next ones under the same roof.

shadscan --check-ui http://localhost:3000 --route /docs --route /pricing

--check-overflow keeps working. Nothing you already wrote into a CI job breaks.

The prompt stopped only reading your code

The copy-paste prompt has always handed an agent a deterministic source audit. That leaves out everything a browser knows.

It now pairs the audit with rendered verification, and it works out what to verify rather than being told: every application it detects, including each app in a monorepo, the concrete local pages those apps actually serve, and any production deployment it can confirm. Large route lists are batched instead of being run one at a time.

The part that matters most is what it does when it cannot look. A page behind a login, a route that only exists for a signed-in user, a deployment it cannot confirm — those are reported as uncovered. It does not invent a plausible URL, and it does not describe a partial run as a clean one. An agent that quietly skips half your app and reports success is worse than one that checks nothing.

Following a redirect without following it anywhere

Point a rendered check at example.com and the server may well send it to www.example.com. Refusing to follow that makes the check useless on most real deployments; following redirects freely makes it a tool that can be pointed at anything.

So the redirect handling is deliberately narrow: a conventional two-label apex host to its own www, or HTTP to HTTPS. The resolved origin is then pinned for every route in the run. An HTTPS downgrade, an unrelated origin, a project subdomain, or a client-side cross-origin navigation stays blocked.

Nothing about your score changes

The bundled ruleset stays at 2026.08.45, the rule catalog is unchanged, and the report schema is unchanged. Rendered checks still add no rule, no points, and no grade — they are a separate gate, deliberately kept out of a number that is supposed to depend only on your files.

Why this could not be a rule

Every other check shadscan makes reads your source. This one cannot.

A sideways-scrolling page is almost never a single wrong class. It is the sum of a fixed width here, a long unbroken string there, a chart that renders wider than its container, a negative margin that escapes its parent — none of which is wrong on its own, and none of which can be added up without a layout engine. The overflow exists only once a browser has measured the page.

So this is a separate mode rather than a sixty-second rule. --check-overflow takes the URL of an app you are already running — a dev server, a preview deployment — opens it in isolated Chromium contexts, and fails if the document scrolls horizontally or is forced to grow a root scrollbar.

shadscan --check-overflow http://localhost:3000 --route /docs --route /pricing

It checks a narrow phone (320 × 820) and a wide desktop (1440 × 1000), and up to ten same-origin routes in one run. When it fails, the report names the elements most likely responsible, bounded so a broken page cannot produce a thousand lines of blame.

It does not touch your score

This is deliberate. The static audit is deterministic: the same files always produce the same number. A browser check is not — it depends on a server being up, on fonts loading, on a viewport. Folding that into the score would make the score depend on the weather.

So --check-overflow adds no catalog rule, no points, and no grade. It is a pass-or-fail gate you run alongside the audit, and it keeps operational failures — the server was not up, Chromium was not installed — distinct from product failures, so a broken CI runner never masquerades as a broken layout.

What it costs you

Driving a browser needs a browser. The package now carries playwright-core as a runtime dependency, and the browser binary itself is a separate opt-in download the CLI tells you how to install.

That dependency is loaded lazily, only when you actually run --check-overflow. If you never use this mode, nothing about your install behaves differently, and every existing command is unchanged.

Nothing else moves

The bundled ruleset stays at 2026.08.45, the rule catalog is the same size, and the report schema is unchanged. Your score today is your score tomorrow.

The rule that could not see past the hook

React Hook Form is very often not called in the component that renders the fields. It is called once inside a project's own hook — useCheckoutForm, useSignupForm — which returns the form state for a component to spread across its inputs.

To two of shadscan's rules, that looked like nothing at all. The component rendering the fields had no useForm call in it, so validation-wired-to-form saw a form with no validation attached and said so. field-errors-rendered had the mirror-image problem: it found the form where it was created, in a hook with no JSX, and reported that nothing rendered the errors.

Both were wrong, and wrong in the worst way — an application doing the right thing was told it had done the wrong one. That was issue #32.

Following the hook

The rules now trace a project-owned hook from where the form is built to where it is used, and evaluate each half where it actually lives. Validation is judged in the hook that configures the resolver. Rendered field errors are judged in the component that renders the fields. A provider hook is no longer expected to render error UI that is not its job, and a consumer is no longer blamed for validation it did not configure.

Only project-owned hooks are followed. A hook from a dependency is somebody else's code, and shadscan does not audit it.

What happens when the trail runs cold

Not every hook can be followed. A hook selected at runtime, a form returned through a dynamic value, or a chain that leaves the project boundary — none of those can be resolved statically, and pretending otherwise is how a scanner starts inventing findings.

Where the flow cannot be resolved, the result is advisory rather than a failure. It is reported so you can look, but it does not move the score, and it never borrows evidence from an unrelated form elsewhere in the project to justify a verdict about this one.

What to expect on upgrade

If you build forms inside custom hooks, your score will go up on this release with no change to your code — those two rules were failing on an idiom that was never wrong. If you do not, nothing moves.

The bundled ruleset advances to 2026.08.45, which is how a report explains why the same project scores differently than it did yesterday.

The row that was always selected

A command palette opened, every row carried the same background, and the code looked right at first glance. The item used data-selected:bg-muted, which reads like “apply this when selected.” In this case it means something else: “apply this whenever the attribute exists.”

cmdk renders that attribute for every item. The selected row gets data-selected="true"; every other row gets data-selected="false". A presence selector matches both, so the palette paints every row as selected. The same trap exists for data-disabled.

A boolean attribute that never disappears

The safe spelling tests the value: data-[selected=true]:bg-muted. Named group selectors need the same treatment, for example group-data-[selected=true]/command-item:text-foreground.

Modern shadcn projects can keep the shorter spelling because shadcn/tailwind.css defines data-selected and data-disabled as value-aware custom variants. That means a useful rule cannot reject one token in isolation. It has to know which primitive renders the attribute and which Tailwind contract the application actually loads.

Detect the contract, not a spelling

cmdk-item-state-variants-use-values is deliberately specific to cmdk. Other component libraries may omit a data attribute when its state is false, where a presence selector is exactly right. The rule first finds a project-owned cmdk item, then checks its selected and disabled variants.

It accepts explicit true-value selectors. It also starts from the configured Tailwind stylesheet, follows reachable local imports, recognizes shadcn's package contract and value-aware custom variants, and applies later overrides in source order. If that stylesheet graph is missing, unreadable, too large or too repetitive to analyze safely, the result becomes advisory instead of a confident failure.

Tested against the bug that prompted it

The rule was run against justfuckinguseshadcn, the project where the visual regression appeared. Its fixed command item uses explicit =true variants and passes at 100/100. In a disposable copy, changing the selected background back to data-selected:bg-muted produced a high-confidence finding on the exact component line and moved the audit to 98/100.

The focused suite also covers aliases, named groups, module-level class constants, custom-variant overrides, quoted and commented CSS, cyclic and repeated imports, unsafe paths, missing files and resource limits. The rule is narrow because the underlying contract is narrow; that is what lets it affect the score without guessing.

The question that cannot fail out loud

shadcn's new questionnaire composes a multi-step form from fifteen parts. Two of them matter more than they look.

Mark an item required and forget <QuestionnaireError />, and validation still runs — it just has nowhere to speak. The user picks nothing, presses Next, and the form refuses to advance without saying why. Nothing is broken enough to notice in development, where you always fill the form in correctly.

Leave out <QuestionnaireTitle> and the question has no label at all: a bare set of choices, with nothing stating what is being asked.

Neither is a matter of taste. In shadcn's own example, 5 of 5 required items render an error and 7 of 7 items carry a title. The rule checks the convention the component already documents by using it.

Where the rule stops

questionnaire is a thin styling wrapper. The file you copy holds Tailwind classes; the state machine, focus movement, aria wiring and error association all live in the headless primitive underneath it.

So the rule says nothing about those. They are not yours to get wrong, and checking them would mean auditing a package you did not write and breaking every time it releases. It looks only at what you compose.

It is quiet in the same way elsewhere. A required value it cannot read statically — required={strict} — is treated as unknown rather than guessed at, because a false alarm costs more than a missed one on a rule that is advisory by design.

Honest about what could not be tested

The rules before this one earned their confidence on real projects. The ButtonGroup check in 0.10.0 ran across nine of them before shipping.

This component is days old, and nobody has adopted it yet, so there was no corpus to check against. What could be done was done: the rule was run against shadcn's published example verbatim — where any finding at all would be a false positive by definition — and it passed every item. Then the example was broken on purpose, one part at a time, and it named the right item and the right line each time.

That is a corpus of one, which is why it ships advisory and stays there until the component sees real use.

Also in this release

The js-yaml floor moves to 4.3.1, past an advisory about quadratic CPU consumption parsing ordered maps. The version override was pinning the old release across the whole tree, so raising the direct dependency alone would not have been enough.

A control that looks like one thing and focuses like two

Put an email field and a Subscribe button in a ButtonGroup and you get a single pill: one border, rounded ends, no seam. Then someone clicks into the field, and the focus ring wraps the input and stops dead where the button starts — square-cornered on the right, with the button hanging outside it. The control looks like one object at rest and two objects on focus.

Nobody wrote that bug. It falls out of what ButtonGroup is for.

Why it happens

ButtonGroup joins its children by squaring off the inner corners and dropping the inner borders. Its entire answer to focus is to lift whichever child has focus above its neighbours, so that child's own ring paints over the adjacent border instead of being clipped by it.

For buttons, that is exactly right. Every segment in a segmented control has the same shape and the same ring, so lifting the focused one reads as this one. For a text input it falls apart, because the input's ring is drawn around the input's own box — including the edge pressed flush against the button. The ring ends up running down the middle of the pill.

The fix is a different component, not a patch

shadcn already ships the right one. InputGroup puts the focus treatment on the wrapper and has the inner control give up its own ring, so focusing the field lights the entire shape — field, button, and the seam between them — as one object.

So the new rule does not ask you to patch ButtonGroup. It tells you that a text input has ended up in the component built for joining buttons, and points at the one built for attaching things to an input.

Built against real code

The rule looks through whatever wraps the control. In practice a text field is almost never a direct child of the group — it sits inside a form primitive first — and a rule that only checked direct children would have found nothing in any real project we tested.

It is deliberately quiet. ButtonGroup is an open container that legitimately holds buttons, selects, separators and arbitrary wrappers, and radio, checkbox and submit inputs carry no ring of their own. None of those are reported. Only text entry is — and only when something is actually joined to it, since a group holding one lone control has no seam to break.

Advisory, on purpose

It ships as an advisory, so it appears in your findings and in the agent handoff without changing your score. Across nine real shadcn projects it found four instances and flagged nothing it should not have — but those nine share one author, which is not yet a wide enough sample to justify moving everyone's score for what is, in the end, a cosmetic defect. It has to earn that.

Ask, don't parse

Agents already use shadscan — the --prompt handoff and --apply exist for exactly that. But both hand the agent everything at once, and an agent mid-task rarely wants everything. It wants the answer to one question: "which accessibility problems are left in apps/web?"

shadscan mcp makes that a tool call. The server speaks the Model Context Protocol over stdio, and setup is one line:

claude mcp add shadscan -- npx -y @shadscan/cli mcp

Three tools, all read-only. scan returns the score, the grade, and the actionable findings — each with its suggested fix, acceptance criteria, and score impact — filterable by category, severity, or workspace package. list_projects classifies a monorepo's packages the way --list-projects does. explain_rule describes what one rule checks, and guessing an id wrong answers with the nearest real ones.

The server that refuses to remember

The obvious design was a cache: scan once, let the agent query what is still broken. That design was measured and rejected. A scan takes about a second, and shadscan is deterministic over the state of your files — so the moment an agent edits one, any remembered answer is wrong, at precisely the moment the agent most needs the truth.

So every call re-scans. Fix something, call scan again, read the delta. The loop is honest because it never answers from memory, and cheap because the engine is fast. Responses carry the engine, ruleset, and schema versions, so results from different shadscan versions can never be silently compared.

Small on purpose

The server can only read inside the directories it was started with; tool calls cannot widen that. It never writes files, never touches the network, and strips the roast copy — agents quote tool output verbatim, and a roast belongs in your terminal, not your commit message.

The protocol SDK is bundled at build time rather than added as a dependency, so the published package still installs the same six runtime dependencies it did before. The packed-package smoke test now audits the shipped bundle to keep the SDK's HTTP transports — an entire server stack a stdio process never uses — from ever reaching your node_modules, and drives a real protocol session against the packed artifact so a stray print onto the protocol stream cannot ship.

Also in this release

The library API exports scanWorkspace and discoverWorkspace, so programmatic consumers get the same monorepo entry points the CLI and the MCP server use. Setup for every client, the full tool reference, and the security posture live in the new MCP runbook.

The problem was silence

Shadscan resolves your project, works out its structure, evaluates fifty-nine rules against your components, and assembles a report. On a large codebase that takes long enough that people assumed it had hung, and reached for Ctrl+C. The tool was working the whole time; it just never said so.

✓ Resolving project
✓ Discovering app structure
⠹ Evaluating UI rules
  Preparing report

The active phase spins, then settles into a tick and stays on screen. Four phases, always the same four, for single projects, monorepo workspaces, and shadscan setup alike.

No percentages, on purpose

A progress bar would have to guess. Rules vary enormously in cost — one reads a single manifest, another walks the render graph across every route — so any "73%, about 4 seconds left" would be invention dressed as measurement. For a tool whose entire claim is that it reports what it can prove, that seemed like the wrong thing to add. Naming the current phase is something shadscan actually knows.

It stays out of the way of machines

Progress is written to stderr, never stdout, and disables itself for JSON and prompt output, in CI, when either stream is piped or redirected, when stderr is not a terminal, under --no-interactive, and with SHADSCAN_INTERACTIVE=0. Scripts parsing the JSON report, the GitHub Action, and --fail-under score gates behave exactly as they did in 0.7.0.

Plain terminals are handled too: no Unicode means [ok] and a -\|/ spinner, no colour means no escape codes. There are no new dependencies, the animation timer is unreferenced so it can never hold the process open, and if writing to the terminal ever fails the progress display switches itself off rather than turning a cosmetic problem into a failed scan.

One change under the surface

The audit loop now yields to the event loop between rules, so the animation keeps moving during synchronous syntax-tree work. Rules still run one after another in the same order, so scores are unchanged and reruns stay identical. The same change makes cancellation land sooner, which the hosted API's timeouts benefit from.

A single unusually slow rule can still pause the spinner briefly. Moving the audit onto a worker thread would fix that completely, at the cost of worker bundling, report serialization, and extra packaging risk — too much to spend on an animation.

Credit

The progress checklist was contributed by @jojomensah89 in #21, with tests covering the renderer, the stream rules, and the event-loop yielding.

The dead end

Point shadscan at a monorepo root and it used to say "the nearest package does not declare React" and stop. The root of a workspace almost never declares React — that is what makes it a root. So the tool refused to audit precisely the repository layout that shadcn init --monorepo scaffolds.

It now walks the tree, finds every React application, audits each one, and pools the findings into a single score. Discovery works the same way for pnpm, npm, yarn, bun, Turborepo, Nx and Lerna, because it looks for package.json files rather than parsing each tool's own workspace configuration. That also means no YAML parser was added to a CLI that ships six runtime dependencies.

Why your design system is not in the score

This is the decision the feature rests on.

Audit a component library on its own and it scores badly — around 40, with the whole foundation category at zero. Not because it is bad, but because it has no page title, no favicon, no theme provider and no document shell. It should not have any of those. Pool that into a monorepo's score and every repository with a packages/ui takes a hit for owning a design system. "My score dropped because my component library has no favicon" is the kind of result that makes people stop trusting a number.

So packages are classified. Applications feed the score. Libraries are still scanned and still reported with their own score — their accessibility findings are genuinely useful — but they stay out of the headline figure, and the report says so in as many words.

The signal that decides it is an application entry point, not a main or exports field in the manifest. The first draft used the manifest and got it backwards on real repositories, where internal packages are consumed straight from source through a path alias and declare no entry at all. Every application has an entry point, so its absence is the half of the test that can be relied on.

A number you can take apart

A pooled score that silently means something new is worse than no score at all, so the report shows its working. Every package appears with its own score, adapter and the reason it was classified the way it was — worst first, because that is the one you want to read. Libraries sit in their own labelled block. Packages that could not be audited are listed with the reason.

--list-projects prints all of that without scanning anything, which is the right tool when the classification surprises you, and --project apps/web narrows a run to a single package.

A workspace holding one application at the repository root still takes the old single-package path, so the common "app at the root with shared packages beside it" layout keeps exactly the score it had.

Proven against real repositories

dub pools to 21 — precisely the score its apps/web reported on its own, since it is the only application there. shadcn-ui/ui pools eleven applications into 40, and its apps/v4 still reports the 34 it always has. Scanning that repository first turned up 31 "projects", most of them test fixtures describing real frameworks; discovery now skips the same directories the scanner already refuses to read source from.

All nine framework adapters were re-scanned against the previous release on identical inputs. Every score matched.

Also in this release

no-nested-interactive-controls no longer reports a false positive for Base UI's render composition. <Button render={<Link />}> passes the link through the owner's attributes and renders it instead of the owner's own tag, so exactly one anchor reaches the DOM — but the JSX walker saw a link inside an interactive element and flagged it.

For JSON consumers

The report schema is version 9. Findings, agent actionables and agent work items gain packageDir; the report gains workspace, which is null for single-package scans; and framework.adapter accepts mixed when pooled applications use different frameworks. The GitHub Action reads score and grade and needs no change.

A separator in the wrong alphabet

Globs speak forward slashes on every platform. Windows paths do not. Several App Router rules built their match patterns with path.join, which on Windows produces app\dashboard\**\page.tsx — a string the glob matcher will never match against anything.

The result was not an error. The rules simply found no route boundaries and no metadata exports, concluded the project did not have them, and scored it accordingly. A Windows user and a macOS user could audit the same commit and get different grades, with nothing in either report to suggest why. Silent wrong answers are the worst kind for a tool whose entire promise is a deterministic score.

The fix normalizes the separators before the patterns reach the matcher, so the glob always sees the alphabet it expects.

Why this is its own release

This landed after 0.6.0 was cut, so it missed that build. It also arrived without a ruleset bump: the contribution branched before 2026.07.39 existed, and merging placed it on the same number 0.6.0 had already shipped. Two different rule behaviors under one ruleset identifier defeats the point of having the identifier, so this release advances it to 2026.07.40.

If you scan on Windows, upgrade — your previous scores were understated. If you scan on macOS or Linux, nothing changes.

Credit

Found and fixed by @robert-dudley-p1 in #8 — the kind of bug that is nearly invisible unless you are the person hitting it.

One flaw wearing three hats

Issue #10 reported three unrelated-looking failures in a TanStack Start app. They turned out to be one problem: each rule searched for its evidence inside a single lexical scope. That works for code written the way the rule's author pictured it, and fails the moment the implementation is composed — a shortcut registered by a library, a button owned by a shared form, a sidebar split across two modules. All three apps worked. Shadscan just could not see it.

The reporter was right on every count, and their write-up was precise enough to reproduce from directly.

Shortcuts you did not write by hand

theme-hotkey-present used to insist on a raw keydown listener with a literal key comparison and hand-rolled guards against typing targets. A one-line useHotkey("Mod+Shift+D", …) had none of those things and failed.

It now recognizes declarative registrations from @tanstack/react-hotkeys and react-hotkeys-hook, resolved through the import so a local hook that happens to share the name does not qualify.

The interesting part is the guard. Both libraries can ignore keystrokes typed into inputs, and they express it with opposite polarity. TanStack has ignoreInputs, whose default depends on the shortcut itself — on for bare keys and Shift/Alt combos, off for Ctrl/Meta ones, which is exactly why the reported Mod+Shift+D passes it explicitly. react-hotkeys-hook has no such option; it ignores form tags by default and only stops when you opt out with enableOnFormTags. A single matcher would have rejected every correct usage of the second library, so each is evaluated on its own terms.

A key spec that is not a static literal, or options hidden behind an identifier, still fails. The rule reports what it can prove.

Pending state that lives one component away

A shared form component that owns its submit button is good design and used to score badly. The call site had the pending flag; the disabled attribute and the spinner were one component down; the rule wanted all three together.

It now follows a pending value through JSX props into the component that receives it, across at most two boundaries, tracking renames along the way — isPending handed down as busy is still the same value. Spread props, external or unresolvable targets, ambiguous exports and computed expressions all end the chain instead of being assumed sound, and when the chain ends the failure says where.

The sidebar the CLI actually generates

mobile-nav-present required <SidebarProvider>, <Sidebar> and a link in one file. Nobody writes that. shadcn add sidebar nudges you toward a provider in the root layout and a <Sidebar> in app-sidebar.tsx, which never matched — so working mobile navigation was flagged.

The provider mount and the sidebar composition are now looked up separately and then linked by resolving what the provider renders, which keeps the check honest: an app-sidebar module that nothing mounts, or one rendered outside the provider, still fails.

Burn-in against real projects then caught a second layer of the same mistake. Requiring a link next to <Sidebar> was the single-file assumption again, one level down — real sidebars hold a nav component, and the nav component holds the links. The rule now reaches one hop further.

What this does to your score

These three rules are worth twelve points between them, so a project using these idioms will score higher after upgrading without changing a line. That is the bug being fixed, not a rescoring — but a number moving on its own deserves an explanation.

Every change here loosens a rule, which inverts the usual risk: the danger is passing an app that does not work, not failing one that does. Four public projects were audited before and after. Exactly one status changed, and it was checked by hand, end to end, before shipping.

Also in this release

Module resolution had been reimplemented in five places. The rules that need it now share one implementation, and the confined TypeScript host and compiler options are built once per project instead of once per rule.

Knowing when not to claim a project

React Router runs three ways. In declarative mode it is a <BrowserRouter> inside an ordinary Vite SPA. In data mode it is createBrowserRouter with loaders, still a SPA. Only in framework mode does it own the document, the routes, and the server — and only that mode has conventions worth auditing differently.

That distinction drove the design. The react-router package sits in a very large number of ordinary React apps, so detecting on it alone would have quietly reclassified them all. Detection instead requires three things together: the dependency, a framework marker (@react-router/dev or a react-router.config file), and an app/root module. Projects that have only some of those keep the adapter they had, and the test suite pins that behavior rather than trusting it.

Sharing a directory name with Next

Framework mode keeps its code in app/ — the same name Next's App Router uses, and a directory shadscan already tracked. Overloading that field would have coupled two frameworks through one value and made every rule that reads it ambiguous. React Router gets its own paths instead, filled in only when that adapter actually wins detection. A Next project that happens to contain an app/root.tsx still audits as Next, and a React Router project is never judged against Next's file conventions.

Rules that speak the framework

The document shell is app/root.tsx: language, theme provider, toast mounting, and — because framework mode renders on the server by default — hydration safety. Metadata comes from the route meta export. Not-found coverage is satisfied by an ErrorBoundary that handles isRouteErrorResponse or by a splat route. Error handling recognizes the ErrorBoundary export instead of asking for a component library. Routes that export a loader need pending UI, satisfied by HydrateFallback, useNavigation state, or a Suspense fallback — and resource routes, which return data rather than markup, are left out of that entirely.

The render graph seeds one surface per route module, read from routes.ts when its entries are literal and from directory discovery otherwise, saying so in the report when it falls back. ErrorBoundary and HydrateFallback exports become surfaces of their own; they render on real navigations and were invisible until now.

Burned in, and clean

Three public projects were audited before release: the official React Router template, a real authentication app, and a declarative-mode SPA kept as a control. All three classified correctly, the control stayed where it belonged, and repeated runs matched exactly. Nothing needed fixing — the first adapter of the recent four where the burn-in found no false positives, which is what you would hope for from the one whose files were ordinary TypeScript all along.

One note for JSON consumers

The report schema is now version 8: framework.adapter accepts react-router-framework, and versions includes reactRouter. The GitHub Action reads score and grade and needs no change.

A format we do not parse

Every adapter before this one kept its pages in TSX. Astro does not: the routes, the layouts, and the <html> element all live in .astro files, and the React components are islands mounted inside them. Auditing the islands without reading those files would mean seeing the components and missing the page.

So shadscan reads them, along one deliberate line. The frontmatter — the TypeScript between the --- fences — is parsed with the same TypeScript parser every other file gets, because it is TypeScript, and because it is the only reliable way to know which components a page imports. The template below the fences is treated as text. No template AST, no attempt to understand conditional rendering. Where composition cannot be proven, the report records a boundary reason instead of guessing.

What that buys you

Document rules now read your Astro layouts: the lang attribute, the title and description, the favicon link, Open Graph images, and src/pages/404.astro. Layouts are found by content rather than by convention, so it does not matter where you keep them.

The component render graph seeds one surface per .astro page or layout, rooted in the islands that file imports and renders — whether they carry a client:* directive or render on the server. Toast and theme-provider mounts trace from the layout into the island component, including islands imported straight from a package.

Found by running it on real sites

Before release, the adapter ran against three public Astro projects spanning Astro 4 through 7. Two false positives turned up that fixtures would never have shown: Astro passes metadata as expressions (content={description}), which the HTML patterns had been rejecting, and a toaster imported directly from its package in frontmatter was invisible to the mount trace. Both are fixed, with tests. One of those sites went from 45 to 64 once the audit stopped being wrong about it.

A quiet fix for Laravel too

Chasing the Astro work surfaced that hosted web scans were discarding .astro templates during extraction — and had been discarding Laravel's Blade views since 0.3.0. Scanning either stack through the web scanner reported generic React. Both are retained now; local CLI scans were never affected.

One note for JSON consumers

The report schema is now version 7: framework.adapter accepts astro-react, and versions includes astro. The GitHub Action reads score and grade and needs no change.

The audit finally sees Laravel

A Laravel Inertia app keeps its React under resources/js — a directory shadscan never read. Projects landed on the generic React adapter with most of the audit silently skipped. 0.3.0 adds a first-class laravel-inertia-react adapter: detection keys on the @inertiajs/react dependency, a Laravel marker (artisan or laravel-vite-plugin), and a resources/js/pages directory in either casing. Composer vendor/ directories stay out of the scan, and versions now reports both the Laravel framework and Inertia versions.

Two languages, one document

Laravel splits the document between Blade and React: app.blade.php owns the <html> element while Inertia's <Head> writes the metadata. Rules now read both sides — language, favicon, and social tags from the Blade root view as plain text; titles and descriptions from <Head> markup; resources/views/errors/404.blade.php or an Inertia error page for not-found coverage; and Inertia's built-in progress indicator for loading feedback, failing only when it is disabled with nothing in its place. Blade-only and Livewire applications get an honest error naming their UI stack instead of a generic complaint about React.

Pages become surfaces

The component render graph seeds one surface per Inertia page from its default export and resolves persistent Page.layout wrappers, so anatomy and navigation rules see every page composed the way it renders. Where page resolution is customized away from the default glob, the graph records an explicit boundary reason rather than guessing.

Burned in before shipping

Before release, the adapter was run against the official laravel/react-starter-kit, the canonical Ping CRM React demo, and a strict community starter kit. All three detect correctly with deterministic double-runs — and the one false positive the burn-in surfaced (an SVG favicon failing the favicon rule) was fixed with regression coverage before this release.

One note for JSON consumers

The report schema is now version 6: framework.adapter accepts laravel-inertia-react, and versions includes inertia and laravel. The GitHub Action reads score and grade and needs no change.

Recognized as itself

Until now, a TanStack Start app landed on the generic React adapter. Nothing failed loudly — the audit simply skipped the checks that had no Next.js equivalent, and the score came back thinner than it should have been.

Start apps are now detected from the @tanstack/react-start dependency together with a src/routes or app/routes directory, checked before the Vite adapter since Start builds on Vite. Projects that use TanStack Router without Start stay where they were, and say so in their evidence.

Rules that speak Start

Framework-aware rules learned Start's conventions rather than approximating them. Metadata is read from the head() route option, not a Next export. Not-found coverage comes from notFoundComponent or the router's defaultNotFoundComponent. Loading coverage is required for loader-backed routes and satisfied by pendingComponent. Because Start renders on the server by default, the theme-hydration check now applies — and it looks for suppressHydrationWarning in the root route's shell, where the <html> element actually lives.

The whole app, not just the entry

The component render graph seeds one surface per route file, expanding each route's statically resolvable component options. Anatomy, navigation, and composition rules see every route instead of whatever a single client entry reached. Where composition can't be proven — an <Outlet />, an inline arrow component — the graph records an explicit boundary reason instead of guessing.

One note for JSON consumers

The report schema is now version 5: framework.adapter accepts tanstack-start, and versions includes tanstackStart. If you validate schemaVersion strictly, accept 5. The GitHub Action reads score and grade and needs no change.

The last thing you see

The score summary has always led the report — which means on any project with real findings, it scrolls off screen long before the report finishes. By the time the post-scan menu appears, the verdict is gone.

Now the report ends the way it begins: with your grade. Local interactive scans close with the grade and score rendered as large shadowed block letters, colorized by the same green, yellow, and red bands as the score bar, sitting directly above the menu.

Honest by construction, still

The banner is a pure function of the score and grade, so determinism is untouched: the same source produces the same banner, every run. It renders only on local Unicode terminals — CI logs, piped output, and plain terminals keep the exact tight report they had in 0.1.0. Terminals too narrow for the letterforms get a single "Final grade" line instead.

One command, one answer

npx @shadscan/cli@0.1.0 audits the current project and scores its UI fundamentals from 0 to 100: command menus, theme shortcuts, route states, accessible controls, form feedback, metadata, mobile behavior, and the composition contracts of shadcn components themselves. The result is deterministic — the same source produces the same report, byte for byte — so scores are comparable across machines, teammates, and CI runs. Every finding carries repository-relative evidence and a suggested fix, and the rules that cannot be proven statically say so instead of guessing.

Built for the agent era

The audit is designed to be handed off. After every interactive scan, the agent handoff is one Enter away — a neutral, paste-ready plan that groups findings into fix, decide, and verify work items with acceptance criteria and the exact rescan command. --apply launches an installed Claude Code, Codex CLI, or Grok Build with that plan directly, and the same handoff is embedded in the tracked issues our GitHub Action maintains.

Guardrails that hold

--fail-under turns the score into a CI gate that cannot be satisfied by a partial scan. The composite GitHub Action posts the score and category table to the job summary on every push. shadscan setup --pre-commit installs a version-pinned score floor as a Git hook, and the shadscan-pre-commit agent skill holds AI agents to the same standard before every commit they make.

Honest by construction

Shadscan reads source and configuration — nothing else. It does not start your app, edit files, call an AI model, upload code, or require secrets. Rules that need a rendered browser to verify report as advisories rather than pretending certainty, and anatomy rules resolve against the components your project actually vendors, so your customizations are part of the contract rather than violations of it.

A menu you can feel

Typing 1 and pressing Enter worked, but it read as a form. The menu now renders a live cursor: arrows or j/k move it (wrapping at the ends), Enter confirms, and the row highlight follows you without the report above ever scrolling. The old number keys still act as instant shortcuts, so nothing you learned in rc.6 is wasted.

One keypress to the handoff

The agent handoff is why the menu exists, so it starts highlighted — a bare scan followed by a single Enter puts the paste-ready remediation plan on your clipboard and prints it. Pressing Esc (or q) dismisses the menu and keeps just the score, which the hint line below the menu spells out.

Careful with your terminal

Raw-mode input is easy to get wrong, so the selector treats restoration as a contract: raw mode, the cursor, and key listeners are restored on selection, escape, interrupt, and error alike — Ctrl+C hands the terminal back before forwarding the signal. Minimal terminals without raw-mode support fall back to the rc.6 numbered prompt, NO_COLOR and non-unicode environments get a plain ASCII pointer, and no new dependencies were added for any of it.

The handoff, one keypress away

The recommended shadscan workflow is to hand the audit to a coding agent — but until now the CLI printed a report and quietly exited, leaving the handoff behind a flag most first-time users never saw. Interactive scans now end with a short menu whose first option copies the paste-ready remediation plan to your clipboard and prints it, so the next step is always visible. Printing without copying, launching an installed agent, and adding a pre-commit score gate sit right below it, and Enter still means "just the score, thanks."

Clipboard that works everywhere, honestly

Copying uses the platform's own utilities — pbcopy on macOS, clip on Windows, wl-copy, xclip, or xsel on Linux — and falls back to the OSC 52 terminal escape for SSH sessions and minimal environments. When no channel is available, shadscan says so and prints the handoff instead of pretending. No new dependencies were added.

Automation is untouched

The menu exists only for interactive terminals. CI environments, piped output, --json, --prompt, and --no-interactive behave byte-for-byte as they did in rc.5.

Composition contracts, checked

shadcn components are composition contracts: items belong in groups, InputGroup provides its own input and addon parts, and an Alert is built from a leading icon, a title, and a description. A new anatomy engine encodes those contracts declaratively and checks them across your JSX — starting with three advisory rules that never move your score while they earn trust.

Two design decisions keep them honest. Anatomy is resolved against the components your project actually vendors, so a part you added to your own components/ui/alert.tsx is part of the contract, not a violation. And composition that crosses component boundaries — an item rendered by a helper, children passed through props — is treated as unknowable rather than wrong.

The audit in your CI

The repository now doubles as a composite GitHub Action. Point a workflow at TheOrcDev/shadscan, and every push gets a deterministic score with a category table in the job summary. Add fail-under to gate merges, and enable create-issue to keep a single tracked issue up to date — its body embeds the same paste-ready remediation handoff --prompt generates, so assigning the issue to a coding agent hands it a complete plan.

The ruleset, in the open

Every rule shadscan runs is now documented on the public rules page, generated from the same catalog the CLI bundles, and releases are published on the changelog page you are reading. Both are a keyboard shortcut away behind the site's command menu.

Monorepos, finally

Pointing the web scanner at a monorepo used to mean acquiring everything and auditing whatever the root looked like. Discovery is now bounded and explicit: shadscan finds the package roots that look like real apps, asks you to choose one, and audits exactly that project — nothing else is fetched or retained.

Bounded acquisition

GitHub archives stream through bounded source profiles that classify every entry as it arrives and keep only what the audit needs. Small selected manifests skip the archive entirely and fetch just their files. Limits are reported precisely: the failed counter, the configured threshold, the observed value, and the affected path.

Durable queued scans

Scans too large for the inline budget are dispatched to a durable queue with token-protected polling, and immutable results can be cached so repeat scans of the same commit answer instantly. Source never persists either way.

Ruleset 2026.07.33

The bundled ruleset grows to 56 rules, adding a high-confidence check that inline icons and spinners inside shadcn Buttons carry position-correct data-icon="inline-start" or data-icon="inline-end" attributes, while icon-only controls stay excluded.

See the score, then act on it

Local scans now end with a width-aware score bar and an interactive post-scan menu. From there, --apply --agent <provider> validates an installed Claude Code, Codex CLI, or Grok Build and launches it with a private, neutral remediation prompt — no copy-paste required. CI and redirected output stay deterministic and color-free by default.

Pre-commit gates you can trust

shadscan setup --pre-commit (also offered from the post-scan menu) installs a score gate pinned to the exact shadscan version and your current assessed score. It safely updates simple POSIX-native hooks, preserves existing commands, and hands you a manual plan for hook managers, other interpreters, and complex hooks instead of touching them.

Deeper, safer analysis

Navigation landmarks are now correlated through a bounded component render graph that understands route surfaces, repeated instances, child projection, responsive visibility, and mutually exclusive branches — without executing application code. Projects mixing App Router and Pages Router are detected and audited as hybrids, with both root shells and route-boundary families covered.

Hardened hosting

Hosted TypeScript parsing and rule evaluation moved into disposable, resource-limited workers that terminate on request abort and receive no deployment secrets. Each process is bounded to two active scans with a retryable SCAN_BUSY contract, rate limiting is atomic and epoch-based, and public GitHub archives download without the server token. Reports also became byte-stable across runtime locales.

Pages Router, covered

Discovery and rules now understand the Pages Router as thoroughly as the App Router: _app, _document, route-level loading, error, and not-found boundaries, metadata, theme, toast, and mounted-component analysis all participate in the audit, and the web scanner returns complete Pages Router reports.

Documentation that leads with the CLI

The docs were rebuilt around how shadscan is actually used: output formats, category scopes, score thresholds, project paths, agent prompts, and running it before AI-agent commits.

Stricter credit, stabler contracts

Command-menu and shortcut findings now require mounted application surfaces instead of awarding credit for orphaned components, and the exact hotkey evidence that satisfied a rule is reported. Hosted scan quota consumption became atomic under a single end-to-end deadline, empty GitHub archives are classified correctly, and migration and runtime database roles were separated for least-privilege access.

Supply-chain hardening

Published source maps no longer contain original TypeScript source, every privileged GitHub Actions dependency is pinned to an immutable commit, and the CLI bundles its argument parser so clean installs stop depending on an expired historical npm signing key — while keeping Node 18 support.

One command, one answer

npx @shadscan/cli audits the current project and prints an evidence-backed score across six weighted categories. The result is deterministic: the same source produces the same report, byte for byte, so scores are comparable across runs, machines, and CI.

Built for handoff

Beyond the human report, --json exposes the complete machine-readable audit and the agent prompt output groups related findings into fix, decide, and verify work items — including discovered project gates and a version-pinned rerun command — so an AI coding agent can start from evidence instead of guesswork.

Hosted scanning

A hosted scan API audits public GitHub repositories and sanitized snapshots with authentication, archive extraction limits, source timeouts, and rate limits. Local scanning stays read-only with no source upload, telemetry, install scripts, or AI dependencies.

Fewer false alarms

The rule engine invests heavily in not crying wolf: empty-state checks demand real query calls or mapped collection data, heading checks treat separate component returns as exclusive branches, focus checks inspect actual JSX focus targets, and label checks correlate dynamic id/htmlFor pairs — among many other refinements that keep findings trustworthy.