@sanity/ui 4.2.0 → 5.0.0-alpha.10

package/README.md

@@ -1,49 +1,215 @@
-# @sanity/ui
+# Sanity UI 5
 
-The Sanity UI components.
+The next version of Sanity's component library. Faster, simpler, and built on CSS instead of styled-components.
 
-```sh
-npm install @sanity/ui
+## What's different from v3
+
+- **CSS classes instead of styled-components.** No runtime style generation. Smaller bundles, faster renders.
+- **Direct props for layout.** Width, height, position, border, and overflow are first-class props — no more `style={{ ... }}` escape hatches.
+- **Works alongside v3.** Both versions run in the same app, in the same component tree. No forced migration.
+
+Requires React 19.2+ and Node >=20.19 <22 || >=22.12.
+
+## For new apps
 
-# Install peer dependencies
-npm install react react-dom styled-components
+### Install
+
+#### Recommended: the setup CLI
+
+```sh
+npx @sanity/ui@alpha init
 ```
 
-[![npm version](https://img.shields.io/npm/v/@sanity/ui.svg?style=flat-square)](https://www.npmjs.com/package/@sanity/ui)
+`init` detects your framework and package manager, checks your React and Node versions, then installs the package along with `@sanity/icons`, adds the stylesheet import to your entry file, reconciles `tsconfig.json`, and writes a `sanity-ui.json`. It prints a plan and asks before changing anything.
 
-## Usage
+`@sanity/icons` is a dependency of this package, so your package manager installs it either way. `init` also adds it to your own `package.json` because you import icons directly to pass to components, and under pnpm an import that isn't declared in your project doesn't resolve.
 
-```jsx
-import {Button, ThemeProvider} from '@sanity/ui'
-import {buildTheme} from '@sanity/ui/theme'
-import {createRoot} from 'react-dom/client'
+- `--dry` print the plan and exit without changing anything
+- `--yes` accept every prompt with its default (non-interactive, for CI and agents)
+- `--cwd <dir>` run against another directory
 
-// Static styles are shipped as a plain stylesheet (not injected at runtime) —
-// import it once, wherever your app loads global CSS
+#### Manual
+
+```sh
+pnpm add @sanity/ui@alpha
+```
+
+Using npm or yarn? Use `npm add` or `yarn add` instead. (`init` above picks the right one for you.)
+
+Then import the stylesheet at your app entry point. Without it, components render as unstyled HTML.
+
+```tsx
 import '@sanity/ui/styles.css'
+```
 
-const root = createRoot(document.getElementById('root'))
-const theme = buildTheme()
+### Usage
+
+```tsx
+import {Box, Flex, Card, Heading, Text, Button} from '@sanity/ui'
+import {AddIcon} from '@sanity/icons/Add'
+
+export default function App() {
+  return (
+    <Flex minHeight="100vh">
+      <Box as="nav" aria-label="Main" padding={3} borderRight width="240px">
+        <Heading as="h2" size={1}>
+          My App
+        </Heading>
+      </Box>
+      <Box as="main" padding={4} flexGrow={1}>
+        <Flex alignItems="center" justifyContent="space-between" flexWrap="wrap" gap={2}>
+          <Heading as="h1" size={2}>
+            Documents
+          </Heading>
+          <Button iconStart={AddIcon} text="New" />
+        </Flex>
+        <Box marginTop={3}>
+          <Card density="loose">
+            <Text size={1}>First document</Text>
+            <Text size={1} muted>
+              Edited 2 hours ago
+            </Text>
+          </Card>
+        </Box>
+      </Box>
+    </Flex>
+  )
+}
+```
 
-root.render(
-  <ThemeProvider theme={theme}>
-    <Button text="Hello, world" />
-  </ThemeProvider>,
-)
+### Checking your setup
+
+Run `doctor` at any time to verify an install and get a one-line fix for anything broken:
+
+```sh
+npx @sanity/ui@alpha doctor
 ```
 
-## Contributing and releasing new versions to npm
+It checks that the package and `@sanity/icons` are installed, the stylesheet resolves and is imported, `tsconfig.json` has the options the components need, and your React and Node versions are supported.
+
+## For apps using Sanity UI v3
 
-This package lives in the [`sanity-io/ui` monorepo](https://github.com/sanity-io/ui) and uses [Changesets](https://github.com/changesets/changesets) to manage versioning and publishing.
+### Install
 
-When you make a change that should be released, add a changeset to your pull request:
+v3 and v5 are the same npm package at different majors, so an app that wants both needs a package alias to tell them apart.
+
+In apps still using v3 components, we recommend installing v5 with a package alias. This way, your existing `@sanity/ui` imports keep resolving to v3, so nothing you have already written needs to change.
 
 ```sh
-pnpm changeset
+pnpm add ui5@npm:@sanity/ui@alpha
+```
+
+This gives you:
+
+```json
+{
+  "dependencies": {
+    "@sanity/ui": "^3.5.1",
+    "ui5": "npm:@sanity/ui@alpha"
+  }
+}
 ```
 
-Once pull requests with changesets are merged into the `main` branch, a "Version Packages" pull request is opened (and kept up to date) that bumps the affected package versions and updates their changelogs. Merging that pull request publishes the packages to npm through the [`Release` workflow](https://github.com/sanity-io/ui/actions/workflows/release.yml), which uses npm [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (OIDC).
+Now `@sanity/ui` means v3 everywhere in your codebase and `ui5` means v5. You migrate one import at a time, at whatever pace suits you, instead of rewriting every file before anything runs.
+
+The alias name is yours to choose. `ui5` is what we use internally. npm, pnpm, and yarn all support the `npm:` protocol.
+
+### Setup
+
+v5 has no `ThemeProvider`, and it does not read v3's theme. Keep your existing provider setup exactly as it is: v3 components still need it, and it has no effect on v5.
+
+With v5 installed under an alias, the stylesheet comes from the alias too.
+
+```tsx
+import {ThemeProvider, studioTheme, ToastProvider} from '@sanity/ui' // v3
+import 'ui5/styles.css' // v5
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <ThemeProvider theme={studioTheme}>
+    <ToastProvider>
+      <App />
+    </ToastProvider>
+  </ThemeProvider>,
+)
+```
+
+### Usage
+
+With v5 aliased, which version you get is just which specifier you import from. Anything without a v5 equivalent keeps coming from `@sanity/ui`, and the two sit next to each other in the same tree.
+
+```tsx
+import {Dialog} from '@sanity/ui' // v3
+import {Button, Card, Text} from 'ui5' // v5
+```
+
+## Components
+
+### Layout
+
+| Component   | What it does                                                                        |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `Box`       | General container. Padding, margin, border, overflow, and position as direct props. |
+| `Flex`      | Flexbox layout. `alignItems`, `justifyContent`, `flexDirection`, `gap`.             |
+| `Grid`      | CSS grid. Use `gridTemplateColumns` with a CSS string (e.g. `"repeat(3, 1fr)"`).    |
+| `Container` | Max-width content wrapper.                                                          |
+| `HStack`    | Horizontal stack. Accepts `gap` and `as` only — use `Flex` for alignment control.   |
+| `VStack`    | Vertical stack. Accepts `gap` and `as` only — use `Flex` for alignment control.     |
+| `Inline`    | Inline flow layout with wrapping and gap.                                           |
+
+### Typography
+
+| Component | What it does                                                            |
+| --------- | ----------------------------------------------------------------------- |
+| `Heading` | Semantic headings (`h1`–`h6`). Always set `as` to match the level.      |
+| `Text`    | Body copy, captions, labels. Props: `size`, `weight`, `muted`, `align`. |
+| `Label`   | Form input label. Use only with form elements.                          |
+| `Code`    | Inline or block code. Uses the system monospace font.                   |
+
+### Interactive
+
+| Component  | What it does                                                                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `Button`   | `level` (primary/secondary/tertiary), `tone` (neutral/critical), `iconStart`, `iconEnd`, `text`, `fullWidth`, `loading`. |
+| `Checkbox` | Controlled checkbox. Requires `label` (string).                                                                          |
+| `Radio`    | Controlled radio button.                                                                                                 |
+| `Switch`   | Toggle control. Requires `label` (string).                                                                               |
+| `Link`     | Anchor element styled as a link.                                                                                         |
+
+### Display
+
+| Component        | What it does                                                                                                         |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `Card`           | Raised surface with background and `tone`. Does not accept padding, margin, or layout props — wrap content in `Box`. |
+| `Divider`        | Horizontal rule between content sections.                                                                            |
+| `Icon`           | Renders a `@sanity/icons` icon component. Always set `aria-label` or `aria-hidden`.                                  |
+| `Indicator`      | Status dot with `tone`.                                                                                              |
+| `IndicatorStack` | Grouped `Indicator` elements.                                                                                        |
+| `Spinner`        | Loading indicator.                                                                                                   |
+
+### Lists
+
+| Component | What it does                                        |
+| --------- | --------------------------------------------------- |
+| `List`    | Semantic list. Use `List.Item` and `List.ItemText`. |
+
+### Accessibility
+
+| Component        | What it does                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------------------ |
+| `SkipToContent`  | Visually hidden skip-nav link. Must be the first focusable element. Requires `href` and `label`. |
+| `VisuallyHidden` | Hides content visually while keeping it in the accessibility tree.                               |
+
+### Still only in v3
+
+Menu, Dialog, TextInput, Select, Stack, Badge, ThemeProvider, ToastProvider, and other components not yet migrated to v5. Import these from `@sanity/ui` exactly as you do today.
+
+## Contributing
+
+We welcome feedback and contributions. Start here:
 
-## License
+1. **Try the components** and report what breaks, what confuses, or what's missing.
+2. **Read the contribution model** — build a recipe with existing building block components, then propose graduating it.
+3. **Open a PR** following the branch naming and checklist in the developer contribution docs.
 
-MIT-licensed. See LICENSE.
+During preview, the most useful contribution is using the components and telling us what happens.

package/bin/sanity-ui.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import process from 'node:process'
+
+import {main} from '../dist/cli/index.js'
+import {errorLine} from '../dist/cli/log.js'
+
+try {
+  const code = await main(process.argv.slice(2))
+  process.exitCode = code ?? 0
+} catch (error) {
+  errorLine(error instanceof Error ? error.message : String(error))
+  process.exitCode = 1
+}

package/dist/_chunks-es/LazyRefractor.js

@@ -0,0 +1,20 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { c } from "react/compiler-runtime";
+import { hasLanguage, Refractor } from "react-refractor";
+function LazyRefractor(t0) {
+  const $ = c(5), {
+    language,
+    value
+  } = t0;
+  if (!hasLanguage(language)) {
+    let t12;
+    return $[0] !== value ? (t12 = /* @__PURE__ */ jsx("code", { children: value }), $[0] = value, $[1] = t12) : t12 = $[1], t12;
+  }
+  let t1;
+  return $[2] !== language || $[3] !== value ? (t1 = /* @__PURE__ */ jsx(Refractor, { inline: !0, language, value }), $[2] = language, $[3] = value, $[4] = t1) : t1 = $[4], t1;
+}
+export {
+  LazyRefractor as default
+};
+//# sourceMappingURL=LazyRefractor.js.map

package/dist/_chunks-es/LazyRefractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LazyRefractor.js","sources":["../../src/components/code/LazyRefractor.tsx"],"sourcesContent":["import {hasLanguage, Refractor, type RefractorProps} from 'react-refractor'\n\nexport default function LazyRefractor({language, value}: RefractorProps) {\n  if (!hasLanguage(language)) {\n    return <code>{value}</code>\n  }\n\n  return <Refractor inline language={language} value={value} />\n}\n"],"names":["LazyRefractor","t0","$","_c","language","value","hasLanguage","t1"],"mappings":";;;;AAEA,SAAeA,cAAAC,IAAA;AAAA,QAAAC,IAAAC,EAAA,CAAA,GAAuB;AAAA,IAAAC;AAAAA,IAAAC;AAAAA,EAAAA,IAAAJ;AACpC,MAAI,CAACK,YAAYF,QAAQ,GAAC;AAAA,QAAAG;AAAA,WAAAL,SAAAG,SACjBE,MAAA,oBAAA,QAAA,EAAOF,iBAAM,GAAOH,OAAAG,OAAAH,OAAAK,OAAAA,MAAAL,EAAA,CAAA,GAApBK;AAAAA,EAAoB;AAC5B,MAAAA;AAAA,SAAAL,EAAA,CAAA,MAAAE,YAAAF,SAAAG,SAEME,yBAAC,WAAA,EAAU,YAAiBH,UAAiBC,MAAAA,CAAK,GAAIH,OAAAE,UAAAF,OAAAG,OAAAH,OAAAK,MAAAA,KAAAL,EAAA,CAAA,GAAtDK;AAAsD;"}

package/dist/cli/checks.js

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import { detect, isPackageInstalled, isLegacyUiVersion, PACKAGE_NAME, readInstalledPackageVersion, } from './detect.js';
+import { inspectStylesheet, STYLES_SPECIFIER } from './styles.js';
+import { inspectTsconfig } from './tsconfig.js';
+import { meetsNode, meetsReact, NODE_REQUIREMENT, REACT_MIN } from './versions.js';
+const ICONS = '@sanity/icons';
+/** Resolves the built stylesheet on disk (not the Node no-op shim). */
+function resolveStylesheet(cwd) {
+    try {
+        const require = createRequire(join(cwd, 'noop.js'));
+        const pkgJsonPath = require.resolve(`${PACKAGE_NAME}/package.json`);
+        const path = join(dirname(pkgJsonPath), 'dist/styles.css');
+        return existsSync(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Without a browser, "a component renders with a computed background" is
+ * verified by confirming the resolved stylesheet ships the component class and
+ * a background declaration for it. If both are present and the import is wired,
+ * the component renders styled.
+ */
+function stylesheetHasComponentStyles(path) {
+    try {
+        const css = readFileSync(path, 'utf8');
+        return /\.sui-Card\b/.test(css) && /background/.test(css);
+    }
+    catch {
+        return false;
+    }
+}
+function check(id, ok, meta) {
+    return {
+        id,
+        title: meta.title,
+        ok,
+        status: meta.status ?? (ok ? 'pass' : 'fail'),
+        detail: meta.detail,
+        fix: meta.fix,
+    };
+}
+/**
+ * Runs every verification and returns structured results. `doctor` prints them
+ * all; `init` reuses a subset on exit. Pure read-only.
+ */
+export function collectChecks(cwd) {
+    const detected = detect(cwd);
+    const checks = [];
+    const installedVersion = readInstalledPackageVersion(cwd, PACKAGE_NAME);
+    checks.push(check('install', Boolean(installedVersion), {
+        title: 'Package installed',
+        detail: installedVersion ? `${PACKAGE_NAME}@${installedVersion}` : 'not installed',
+        fix: `Run \`npx ${PACKAGE_NAME}@alpha init\` or install it with your package manager`,
+    }));
+    if (installedVersion) {
+        const legacyInstalled = isLegacyUiVersion(installedVersion);
+        checks.push(check('version', !legacyInstalled, {
+            title: 'Package version',
+            detail: legacyInstalled
+                ? `${PACKAGE_NAME}@${installedVersion} is pre-v5 (expected v5)`
+                : `${PACKAGE_NAME}@${installedVersion}`,
+            fix: `Remove the existing @sanity/ui version, or install v5 with a package alias — see README "For apps using Sanity UI v3"`,
+        }));
+    }
+    const iconsInstalled = isPackageInstalled(cwd, ICONS);
+    checks.push(check('icons', iconsInstalled, {
+        title: 'Icons installed',
+        detail: iconsInstalled ? `${ICONS} present` : `${ICONS} missing`,
+        fix: `Install it: add ${ICONS}`,
+    }));
+    const stylesheetPath = resolveStylesheet(cwd);
+    const stylesheetResolves = Boolean(stylesheetPath);
+    checks.push(check('stylesheet-resolves', stylesheetResolves, {
+        title: 'Stylesheet resolves',
+        detail: stylesheetResolves ? `${PACKAGE_NAME}/styles.css` : 'cannot resolve styles.css',
+        fix: 'Reinstall the package, or build it if working inside this monorepo',
+    }));
+    const stylesheet = inspectStylesheet(cwd, detected.entry);
+    checks.push(check('stylesheet-wired', stylesheet.imported, {
+        title: 'Stylesheet imported',
+        detail: stylesheet.imported
+            ? `imported in ${stylesheet.importedIn ?? detected.entry}`
+            : stylesheet.exists
+                ? `missing from ${detected.entry}`
+                : `entry file ${detected.entry} not found`,
+        fix: `Add \`import '${STYLES_SPECIFIER}'\` to ${detected.entry}`,
+    }));
+    if (detected.typescript) {
+        const tsconfig = inspectTsconfig(cwd);
+        const loadBearing = tsconfig.changes.filter((c) => c.load);
+        // An unreadable file has no changes to report, so guard against it explicitly
+        // rather than letting an empty change list read as "all good".
+        const ok = tsconfig.exists && !tsconfig.unreadable && loadBearing.length === 0;
+        checks.push(check('tsconfig', ok, {
+            title: 'tsconfig options',
+            detail: !tsconfig.exists
+                ? 'tsconfig.json not found'
+                : tsconfig.unreadable
+                    ? 'tsconfig.json could not be parsed'
+                    : loadBearing.length === 0
+                        ? tsconfig.changes.length === 0
+                            ? 'all required options set'
+                            : 'required options set (some optional additions available)'
+                        : `needs: ${loadBearing.map((c) => `${c.key}: ${String(c.to)}`).join(', ')}`,
+            fix: tsconfig.unreadable
+                ? 'Fix the JSON syntax in tsconfig.json'
+                : `Run \`npx ${PACKAGE_NAME}@alpha init\` to reconcile tsconfig.json`,
+        }));
+    }
+    const reactVersion = detected.react.version;
+    const reactOk = reactVersion ? meetsReact(reactVersion) : false;
+    checks.push(check('react', reactOk, {
+        title: 'React version',
+        status: reactVersion ? (reactOk ? 'pass' : 'fail') : 'warn',
+        detail: reactVersion ? `react ${reactVersion}` : 'react not detected',
+        fix: `Upgrade React to >= ${REACT_MIN}`,
+    }));
+    const nodeVersion = process.versions.node;
+    checks.push(check('node', meetsNode(nodeVersion), {
+        title: 'Node version',
+        detail: `node ${nodeVersion} (requires ${NODE_REQUIREMENT})`,
+        fix: `Use Node ${NODE_REQUIREMENT}`,
+    }));
+    return { detected, checks, stylesheetPath };
+}
+/** The subset `init` verifies on exit, plus the render probe. */
+export function verifyAfterInit(cwd) {
+    const { checks, stylesheetPath } = collectChecks(cwd);
+    const ids = new Set(['stylesheet-resolves', 'stylesheet-wired', 'tsconfig']);
+    const subset = checks.filter((c) => ids.has(c.id));
+    const probeOk = stylesheetPath ? stylesheetHasComponentStyles(stylesheetPath) : false;
+    subset.push({
+        id: 'probe',
+        title: 'Probe renders with background',
+        ok: probeOk,
+        status: probeOk ? 'pass' : 'fail',
+        detail: stylesheetPath
+            ? 'Card ships a background declaration'
+            : 'stylesheet not resolved, cannot probe',
+        fix: 'Ensure the package is installed and built',
+    });
+    return subset;
+}

package/dist/cli/config.js

@@ -0,0 +1,23 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const CONFIG_FILE = 'sanity-ui.json';
+/**
+ * Builds the sanity-ui.json contents: a small record of the detected setup
+ * (framework, entry) written to the project root for tooling to read.
+ */
+export function buildConfig({ framework, entry, }) {
+    return {
+        $schema: 'https://sanity-ui.sanity.dev/schema.json',
+        framework,
+        entry,
+    };
+}
+export function configExists(cwd) {
+    return existsSync(join(cwd, CONFIG_FILE));
+}
+export function writeConfig(cwd, config, { dryRun = false } = {}) {
+    const file = join(cwd, CONFIG_FILE);
+    if (!dryRun)
+        writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+    return { file, wrote: !dryRun };
+}

package/dist/cli/detect.js

@@ -0,0 +1,181 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseVersion } from './versions.js';
+export const PACKAGE_NAME = '@sanity/ui';
+export const LEGACY_COEXISTENCE_HINT = 'To add v5 alongside an existing @sanity/ui install, use a package alias — see the README section "For apps using Sanity UI v3".';
+/**
+ * Framework ids map 1:1 to the `framework` field written into sanity-ui.json.
+ * Each carries the ordered list of candidate entry files where the stylesheet
+ * import belongs.
+ */
+const FRAMEWORK_ENTRIES = {
+    'next-app': ['app/layout.tsx', 'app/layout.jsx', 'src/app/layout.tsx', 'src/app/layout.jsx'],
+    'next-pages': ['pages/_app.tsx', 'pages/_app.jsx', 'src/pages/_app.tsx', 'src/pages/_app.jsx'],
+    'react-router': ['app/root.tsx', 'app/root.jsx'],
+    'remix': ['app/root.tsx', 'app/root.jsx'],
+    'vite': ['src/main.tsx', 'src/main.jsx', 'src/main.ts'],
+    'astro': [],
+    'react': ['src/index.tsx', 'src/main.tsx', 'src/index.jsx', 'src/main.jsx'],
+};
+export function readPackageJson(cwd) {
+    const file = join(cwd, 'package.json');
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function allDeps(pkg) {
+    if (!pkg)
+        return {};
+    return { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies };
+}
+export function detectPackageManager(cwd) {
+    if (existsSync(join(cwd, 'bun.lockb')) || existsSync(join(cwd, 'bun.lock')))
+        return 'bun';
+    if (existsSync(join(cwd, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSync(join(cwd, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(join(cwd, 'package-lock.json')))
+        return 'npm';
+    const declared = readPackageJson(cwd)?.packageManager;
+    if (typeof declared === 'string') {
+        const name = declared.split('@')[0];
+        if (name === 'pnpm' || name === 'yarn' || name === 'npm' || name === 'bun')
+            return name;
+    }
+    return 'npm';
+}
+export function detectFramework(cwd, pkg = readPackageJson(cwd)) {
+    const deps = allDeps(pkg);
+    const has = (name) => Boolean(deps[name]);
+    const dir = (relative) => existsSync(join(cwd, relative));
+    if (has('next')) {
+        if (dir('app') || dir('src/app'))
+            return 'next-app';
+        if (dir('pages') || dir('src/pages'))
+            return 'next-pages';
+        return 'next-app';
+    }
+    if (has('@remix-run/react') || has('@remix-run/dev'))
+        return 'remix';
+    if (has('@react-router/dev') || has('react-router'))
+        return 'react-router';
+    if (has('astro'))
+        return 'astro';
+    if (has('vite'))
+        return 'vite';
+    return 'react';
+}
+export function detectTypeScript(cwd, pkg = readPackageJson(cwd)) {
+    return existsSync(join(cwd, 'tsconfig.json')) || Boolean(allDeps(pkg)['typescript']);
+}
+/**
+ * Returns the first existing candidate entry file, otherwise the first
+ * candidate as the place to create one. Astro has no fixed entry, so we look
+ * for a layout component.
+ */
+export function detectEntry(cwd, framework) {
+    if (framework === 'astro')
+        return detectAstroLayout(cwd);
+    const candidates = FRAMEWORK_ENTRIES[framework];
+    const existing = candidates.find((rel) => existsSync(join(cwd, rel)));
+    return { entry: existing ?? candidates[0] ?? 'src/index.tsx', exists: Boolean(existing) };
+}
+function detectAstroLayout(cwd) {
+    const candidates = [
+        'src/layouts/Layout.astro',
+        'src/layouts/BaseLayout.astro',
+        'src/layouts/index.astro',
+        'src/pages/index.astro',
+    ];
+    const existing = candidates.find((rel) => existsSync(join(cwd, rel)));
+    return { entry: existing ?? candidates[0] ?? 'src/layouts/Layout.astro', exists: Boolean(existing) };
+}
+/**
+ * Resolves the installed React version from node_modules, falling back to the
+ * declared range in package.json (carets/tildes stripped).
+ */
+export function detectReactVersion(cwd, pkg = readPackageJson(cwd)) {
+    const installed = readInstalledVersion(cwd, 'react');
+    if (installed)
+        return { version: installed, source: 'installed' };
+    const declared = allDeps(pkg)['react'];
+    if (typeof declared === 'string') {
+        return { version: declared.replace(/^[\^~>=<\s]+/, ''), source: 'declared' };
+    }
+    return { version: null, source: 'missing' };
+}
+function readInstalledVersion(cwd, name) {
+    const file = join(cwd, 'node_modules', name, 'package.json');
+    if (!existsSync(file))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(file, 'utf8'));
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function isPackageInstalled(cwd, name) {
+    return existsSync(join(cwd, 'node_modules', name, 'package.json'));
+}
+export function readInstalledPackageVersion(cwd, name) {
+    return readInstalledVersion(cwd, name);
+}
+export function isLegacyUiVersion(version) {
+    const major = parseVersion(version)?.[0];
+    return major !== undefined && major < 5;
+}
+function detectAliasedInstall(deps) {
+    for (const [name, spec] of Object.entries(deps)) {
+        if (typeof spec === 'string' && /^npm:@sanity\/ui@(5(?:\..*)?|alpha)$/.test(spec))
+            return name;
+    }
+    return null;
+}
+/** Reads the major from a declared range, skipping workspace/catalog/link specs. */
+function declaredMajor(spec) {
+    if (typeof spec !== 'string')
+        return null;
+    if (/^(workspace:|catalog:|link:|file:)/.test(spec))
+        return null;
+    const npmAlias = spec.match(/^npm:@sanity\/ui@(\d+)/);
+    if (npmAlias)
+        return Number(npmAlias[1]);
+    return parseVersion(spec.replace(/^[\^~>=<\s]+/, ''))?.[0] ?? null;
+}
+function detectLegacyInstall(cwd, deps) {
+    const installed = readInstalledPackageVersion(cwd, PACKAGE_NAME);
+    if (installed && isLegacyUiVersion(installed)) {
+        return installed;
+    }
+    const declared = deps[PACKAGE_NAME];
+    const major = declaredMajor(declared);
+    if (major !== null && major < 5) {
+        return declared ?? 'unknown';
+    }
+    return null;
+}
+export function detect(cwd) {
+    const pkg = readPackageJson(cwd);
+    const deps = allDeps(pkg);
+    const framework = detectFramework(cwd, pkg);
+    const entry = detectEntry(cwd, framework);
+    const typescript = detectTypeScript(cwd, pkg) || (entry.exists && /\.tsx?$/.test(entry.entry));
+    return {
+        pkg,
+        packageManager: detectPackageManager(cwd),
+        framework,
+        typescript,
+        ...entry,
+        react: detectReactVersion(cwd, pkg),
+        aliasedInstall: detectAliasedInstall(deps),
+        legacyInstall: detectLegacyInstall(cwd, deps),
+    };
+}