chore: harden react-mode typecheck.

Author: knightedcodemonkey

docs/next-steps.md

@@ -19,3 +19,23 @@ Focused follow-up work for `@knighted/develop`.
    - Detect transient CDN/module loading failures and surface a clear recovery action in-app.
    - Add a user-triggered retry path (for example, Reload page / Force reload) when runtime bootstrap imports fail.
    - Consider an optional automatic one-time retry before showing recovery controls, while avoiding infinite reload loops.
+
+5. **Type reference parsing hardening (TS preprocessor-first)**
+   - Transition declaration/reference discovery in in-browser type diagnostics to a TypeScript preprocessor-first flow (`ts.preProcessFile`) instead of regex-driven parsing.
+   - Scope this to the lazy React type environment loader first, then evaluate whether the same parser path should be reused for all type package graph walking.
+   - Keep current lazy-loading behavior intact: no React type graph fetch until the user switches to React render mode and triggers Typecheck.
+   - Preserve CDN provider fallback behavior and existing diagnostics UX while changing parser internals.
+   - Add a strict fallback contract:
+     - Primary: `preProcessFile` outputs (`importedFiles`, `referencedFiles`, `typeReferenceDirectives`).
+     - Secondary fallback only when unavailable: current lightweight parsing logic.
+     - Never treat commented example code as imports/references.
+   - Add guardrails around known failure classes discovered during development:
+     - Relative declaration references like `global.d.ts` must resolve as file paths, not package names.
+     - Extensionless declaration references (for example `./user-context`) must attempt `.d.ts` candidates first.
+     - Avoid noisy parallel fetch fan-out for bad candidates; use ordered fallback to reduce 404/CORS console noise.
+   - Add focused test coverage (unit or Playwright) that proves:
+     - React-mode typecheck does not trigger fake fetches from commented examples in declaration files.
+     - React-mode typecheck resolves `react` and `react-dom/client` without module-not-found diagnostics.
+     - DOM mode still avoids React type graph hydration.
+   - Suggested implementation prompt:
+     - "Refactor `src/modules/type-diagnostics.js` to make TypeScript preprocessor parsing (`preProcessFile`) the source of truth for declaration graph discovery in the lazy React type loader. Keep current CDN fallback and lazy hydration semantics. Ensure references from comments are ignored, `*.d.ts`/relative path handling is correct, and candidate fetch ordering minimizes noisy failed requests. Add regression coverage for `global.d.ts` and commented `./user-context` examples. Validate with `npm run lint`, `npm run build:esm`, and targeted React/typecheck Playwright runs."

playwright/app.spec.ts

@@ -334,6 +334,48 @@ test('transpiles TypeScript annotations in component source', async ({ page }) =
   await expect(page.locator('#preview-host button')).toContainText('typed')
 })
 
+test('react mode typecheck loads types without malformed URL fetches', async ({
+  page,
+}) => {
+  await waitForInitialRender(page)
+
+  await ensurePanelToolsVisible(page, 'component')
+
+  const typeRequestUrls: string[] = []
+  page.on('request', request => {
+    const url = request.url()
+    if (url.includes('@types/')) {
+      typeRequestUrls.push(url)
+    }
+  })
+
+  await page.locator('#render-mode').selectOption('react')
+  await page.getByRole('button', { name: 'Typecheck' }).click()
+
+  await page.locator('#diagnostics-toggle').click()
+  await expect(page.locator('#diagnostics-component')).toContainText(
+    'No TypeScript errors found.',
+  )
+
+  const diagnosticsText = await page.locator('#diagnostics-component').innerText()
+  expect(diagnosticsText).not.toContain("Cannot find type definition file for 'react'")
+  expect(diagnosticsText).not.toContain(
+    "Cannot find type definition file for 'react-dom'",
+  )
+
+  expect(typeRequestUrls.some(url => url.includes('@types/react'))).toBeTruthy()
+
+  const malformedTypeRequestPatterns = [
+    '/@types/global.d.ts/package.json',
+    '/user-context',
+    '/https:/',
+  ]
+
+  for (const pattern of malformedTypeRequestPatterns) {
+    expect(typeRequestUrls.some(url => url.includes(pattern))).toBeFalsy()
+  }
+})
+
 test('clearing component source reports clear action without error status', async ({
   page,
 }) => {

src/app.js

@@ -1,5 +1,6 @@
 import {
   cdnImports,
+  getTypePackageFileUrls,
   getTypeScriptLibUrls,
   importFromCdnWithFallback,
 } from './modules/cdn.js'
@@ -391,7 +392,9 @@ const typeDiagnostics = createTypeDiagnosticsController({
   cdnImports,
   importFromCdnWithFallback,
   getTypeScriptLibUrls,
+  getTypePackageFileUrls,
   getJsxSource: () => getJsxSource(),
+  getRenderMode: () => renderMode.value,
   setTypecheckButtonLoading,
   setTypeDiagnosticsDetails,
   setStatus,

src/modules/cdn.js

@@ -234,6 +234,16 @@ const typeScriptLibBaseByProvider = {
   jsdelivr: `https://cdn.jsdelivr.net/npm/typescript@${typeScriptVersion}/lib`,
 }
 
+const typePackageVersionByName = {
+  '@types/react': '19.2.2',
+  '@types/react-dom': '19.2.1',
+  '@types/prop-types': '15.7.15',
+  '@types/scheduler': '0.26.0',
+  csstype: '3.1.3',
+}
+
+const getTypePackageVersion = packageName => typePackageVersionByName[packageName]
+
 /*
  * Keep a reliable fallback order for .d.ts files when the active module provider
  * does not host TypeScript lib declarations consistently (e.g. import maps/jspmGa).
@@ -257,6 +267,47 @@ const getTypeScriptLibProviderPriority = typeScriptProvider => {
   return [...new Set(ordered)]
 }
 
+const typePackageBaseByProvider = {
+  esm: packageName => {
+    const version = getTypePackageVersion(packageName)
+    const versionSegment = version ? `@${version}` : ''
+    return `https://esm.sh/${packageName}${versionSegment}`
+  },
+  unpkg: packageName => {
+    const version = getTypePackageVersion(packageName)
+    const versionSegment = version ? `@${version}` : ''
+    return `https://unpkg.com/${packageName}${versionSegment}`
+  },
+  jsdelivr: packageName => {
+    const version = getTypePackageVersion(packageName)
+    const versionSegment = version ? `@${version}` : ''
+    return `https://cdn.jsdelivr.net/npm/${packageName}${versionSegment}`
+  },
+}
+
+export const getTypePackageFileUrls = (
+  packageName,
+  fileName,
+  { typeScriptProvider } = {},
+) => {
+  const normalizedFileName =
+    typeof fileName === 'string' && fileName.length > 0 ? fileName : 'package.json'
+  const typePackageProviderPriority = [
+    'jsdelivr',
+    'unpkg',
+    ...(typeof typeScriptProvider === 'string' ? [typeScriptProvider] : []),
+    'esm',
+  ]
+  const providerOrderedBases = [...new Set(typePackageProviderPriority)]
+    .map(provider => {
+      const createBase = typePackageBaseByProvider[provider]
+      return typeof createBase === 'function' ? createBase(packageName) : null
+    })
+    .filter(Boolean)
+
+  return providerOrderedBases.map(baseUrl => `${baseUrl}/${normalizedFileName}`)
+}
+
 export const getTypeScriptLibUrls = (fileName, { typeScriptProvider } = {}) => {
   const providerOrderedBases = getTypeScriptLibProviderPriority(typeScriptProvider)
     .map(provider => typeScriptLibBaseByProvider[provider])

src/modules/defaults.js

@@ -27,11 +27,12 @@ export const defaultJsx = [
 
 export const defaultReactJsx = [
   "import { useState } from 'react'",
+  "import type { MouseEvent } from 'react'",
   '',
   'type CounterButtonProps = {',
   '  label: string',
   '  active: boolean',
-  '  onClick: (event: MouseEvent) => void',
+  '  onClick: (event: MouseEvent<HTMLButtonElement>) => void',
   '}',
   '',
   'const CounterButton = ({ label, active, onClick }: CounterButtonProps) => (',
@@ -47,7 +48,7 @@ export const defaultReactJsx = [
   '',
   'const App = () => {',
   '  const [count, setCount] = useState(0)',
-  '  const handleClick = (_event: MouseEvent) => {',
+  '  const handleClick = (_event: MouseEvent<HTMLButtonElement>) => {',
   '    setCount(current => current + 1)',
   '  }',
   '',