feat: diagnostics jump-to with keyboard navigation. (#17)

Author: knightedcodemonkey

README.md

@@ -1,60 +1,41 @@
-# @knighted/develop
+<h1>
+	<img src="src/logo.svg" alt="@knighted/develop logo" width="32" height="32" valign="middle" />
+	<code>@knighted/develop</code>
+</h1>
 
-Compiler-as-a-Service (at the edge of your browser) with `@knighted/jsx` and `@knighted/css`.
+CDN-first browser IDE for building UI components with [`@knighted/jsx`](https://github.com/knightedcodemonkey/jsx) and [`@knighted/css`](https://github.com/knightedcodemonkey/css).
 
-> ⚠️ Early project status: this package is pre-`1.0.0` and still actively evolving.
+![Animated flow showing editing, diagnostics, jump-to-source, and fix loop](docs/media/develop-ide-flow.gif)
 
 ## What it is
 
-`@knighted/develop` is a lightweight dev app that lets you:
+`@knighted/develop` is a browser-native IDE that demonstrates modern component
+authoring without a local bundler-first inner loop.
 
-- write component code in the browser
-- switch render mode between DOM and React
-- switch style mode between native CSS, CSS Modules, Less, and Sass
-- preview results immediately
-
-## Local development
-
-```bash
-npm install
-npm run dev
-```
-
-Then open the URL printed by the dev server (it should open `src/index.html`).
-
-## End-to-end tests
+The app is designed to showcase two libraries:
 
-Install Playwright browsers once before your first local run:
+- [`@knighted/jsx`](https://github.com/knightedcodemonkey/jsx) for DOM-first and React-mode JSX authoring
+- [`@knighted/css`](https://github.com/knightedcodemonkey/css) for in-browser CSS compilation workflows
 
-```bash
-npx playwright install
-```
+Dependencies are delivered over CDN ESM with on-demand loading by mode, so the
+browser acts as the runtime host for render, lint, and typecheck flows.
 
-If your environment needs system dependencies too (for example Linux CI-like containers), use:
+## Core capabilities
 
-```bash
-npx playwright install --with-deps
-```
+`@knighted/develop` lets you:
 
-Run local Playwright tests (Chromium):
-
-```bash
-npm run test:e2e
-```
-
-Run locally with headed browser:
-
-```bash
-npm run test:e2e:headed
-```
-
-CI runs Playwright on Chromium and WebKit.
+- write component code in the browser
+- switch render mode between DOM and React
+- switch style mode between native CSS, CSS Modules, Less, and Sass
+- run in-browser lint and type diagnostics
+- open diagnostics in a shared drawer and jump to source locations
+- toggle ShadowRoot preview isolation while iterating
+- switch layout and theme while preserving fast feedback loops
 
-## Notes
+## Try it
 
-- This is currently a development playground, not a stable product.
-- Expect breaking changes while APIs and UX are still being shaped.
-- Documentation will expand closer to `1.0.0`.
+- Live IDE: https://knightedcodemonkey.github.io/develop/
+- Source repository: https://github.com/knightedcodemonkey/develop
 
 ## License
 

docs/article.md

@@ -1,75 +1,78 @@
-# Forget The Build Step: Building A Compiler-as-a-Service Playground
+# Forget The Build Step: A Browser-Native IDE For JSX + CSS
 
-In modern frontend development, we have normalized a heavy local setup cost. Want JSX and modern CSS dialects? Install a large dependency graph, start a dev server, and wait for transpilation loops before you can really iterate.
+Frontend tooling has become incredibly capable.
 
-I wanted to test a different path: what if we removed the terminal from the inner loop?
+It has also become very heavy.
 
-That experiment became @knighted/develop, a browser-native playground that treats your tab as a real-time compiler host.
+For many UI experiments, the first thing you do is not write code. You install dependencies, run a dev server, wait for transforms, and only then start iterating.
 
-## The Core Idea
+I wanted to try a different baseline:
 
-Most playgrounds rely on a backend build service. @knighted/develop flips that model:
+What if the browser is the dev environment?
 
-- JSX compilation and execution happen in the browser.
-- CSS transforms (including CSS Modules, Less, and Sass) run in the browser.
-- Compilers are loaded on demand from CDN sources.
+That idea became [@knighted/develop](https://github.com/knightedcodemonkey/develop).
 
-The result is a development loop that feels direct: type, compile, render, repeat.
+It is a lightweight in-browser IDE built to showcase [@knighted/jsx](https://github.com/knightedcodemonkey/jsx) and [@knighted/css](https://github.com/knightedcodemonkey/css), with dependencies delivered over CDN ESM instead of requiring a local build step in the inner loop.
 
-## The Stack Behind It
+## The Loop, In Practice
 
-Two libraries power the runtime:
+Open a page, write JSX and styles, switch rendering/style modes, run lint/typecheck, and see results immediately.
 
-- @knighted/jsx: JSX that resolves to real DOM nodes.
-  - No virtual DOM requirement.
-  - You can use declarative JSX and imperative DOM APIs in the same flow.
-- @knighted/css: A browser-capable CSS compiler pipeline.
-  - Supports native CSS, CSS Modules, Less, and Sass.
-  - Uses WASM-backed tooling for modern transforms.
+No local bundler needed for that loop.
 
-Under the hood, the app leans on CDN resolution and lazy loading, so it fetches compiler/runtime pieces only when a mode needs them.
+## What Makes It Fun To Use
 
-## Why "Compiler-as-a-Service"?
+The app is intentionally practical, not just a demo shell:
 
-Compiler-as-a-Service here does not mean a remote build cluster.
+- Render mode switch: DOM or React
+- Style mode switch: CSS, CSS Modules, Less, Sass
+- Live preview with ShadowRoot toggle
+- In-browser lint and type diagnostics
+- Diagnostics drawer with jump-to-line navigation (mouse or keyboard)
 
-It means the service boundary is split between:
+So it is not only "can this compile?" It is closer to "can I actually iterate on a component quickly?"
 
-- global CDN infrastructure (module and WASM delivery), and
-- the user device (actual compilation and execution).
+## Why `@knighted/jsx` + `@knighted/css` Matter Here
 
-If you switch into Sass mode, the browser loads Sass support. If you stay in native CSS mode, it does not pay that cost. The compiler behaves like an on-demand service, but the work stays local to the tab.
+`@knighted/develop` is primarily a showcase app.
 
-## What This Enables
+It demonstrates how these libraries behave in a real authoring environment:
 
-- Fast feedback loops
-  - Rendering updates track edits with minimal overhead.
-- Mixed declarative and imperative workflows
-  - Useful for low-level UI experiments and DOM-heavy component prototypes.
-- Isolation testing with ShadowRoot
-  - Toggle encapsulation to verify style boundary behavior.
-- Zero install inner loop
-  - Open a page and start building.
+- `@knighted/jsx` gives you a direct path from JSX to rendered output, including DOM-first workflows.
+- `@knighted/css` handles modern style pipelines in-browser, including Modules/Less/Sass.
+
+Using both together in one interface makes the bigger point obvious: modern browsers can do much more of the compile/authoring cycle than we usually ask them to.
+
+## "Compiler-as-a-Service" Without A Backend Build Farm
+
+In this project, Compiler-as-a-Service means:
+
+- CDN handles module and WASM delivery.
+- The browser tab does the actual compile, lint, typecheck, and render work.
+
+It is service-oriented distribution, local execution.
+
+And because loading is mode-aware, you only pay for what you use. If you never touch Sass, you never load Sass.
 
 ## Why This Matters
 
-The point is not to replace every production build pipeline.
+This is not trying to replace production pipelines.
 
-The point is to prove a stronger baseline: modern browsers are now capable enough to host substantial parts of the authoring and compile cycle directly, without defaulting to local toolchain setup for every experiment.
+It is about lowering the cost of exploration.
 
-For prototyping and component iteration, that changes the cost model dramatically.
+When the setup tax drops, you try more ideas. When feedback is instant, you discover faster. And when the browser is the platform, sharing a repro can be as easy as sharing a URL.
 
-## Try It
+For prototyping and component iteration, that is a meaningful shift.
 
-- Live playground: https://knightedcodemonkey.github.io/develop/
-- Source repository: https://github.com/knightedcodemonkey/develop
+## Try It
 
-## Notes For Publishing
+- Live IDE: https://knightedcodemonkey.github.io/develop/
+- Source: https://github.com/knightedcodemonkey/develop
 
-If you post this on Medium (or similar), include a short screen recording that shows:
+If you are curious, start by toggling:
 
-- switching style modes (CSS -> Modules -> Less -> Sass),
-- toggling ShadowRoot on and off, and
-- immediate preview updates while typing.
+1. DOM -> React render mode
+2. CSS -> Modules -> Less -> Sass style mode
+3. ShadowRoot on/off
 
-That visual sequence communicates the Compiler-as-a-Service model faster than any architecture diagram.
+That sequence tells the story better than any architecture diagram.

docs/contributing.md

@@ -0,0 +1,120 @@
+# Contributing
+
+Thanks for contributing to `@knighted/develop`.
+
+This project is a CDN-first browser IDE for showcasing `@knighted/jsx` and
+`@knighted/css`, so local workflows should preserve browser execution behavior
+and avoid bundler-only assumptions in `src/` runtime code.
+
+## Project docs
+
+- Type checking notes: `docs/type-checking.md`
+- Build and deploy notes: `docs/build-and-deploy.md`
+- CodeMirror integration notes: `docs/code-mirror.md`
+- Roadmap: `docs/next-steps.md`
+- Article draft: `docs/article.md`
+
+## Prerequisites
+
+- Node.js `>= 22.22.1`
+- npm
+
+## Install
+
+```bash
+npm install
+```
+
+## Local development
+
+Start the local app:
+
+```bash
+npm run dev
+```
+
+The local server opens `src/index.html`.
+
+## Build commands
+
+Build prep + CSS + import map generation:
+
+```bash
+npm run build
+```
+
+Build with explicit primary CDN modes:
+
+```bash
+npm run build:esm
+npm run build:jspm
+npm run build:importmap-mode
+```
+
+Preview generated dist output:
+
+```bash
+npm run preview
+```
+
+## Validation commands
+
+Lint source and Playwright files:
+
+```bash
+npm run lint
+```
+
+Type check TS tooling files:
+
+```bash
+npm run check-types
+```
+
+## Playwright end-to-end tests
+
+Install browser binaries once:
+
+```bash
+npx playwright install
+```
+
+If your environment also needs system deps (for example CI-like Linux
+containers):
+
+```bash
+npx playwright install --with-deps
+```
+
+Run preview-mode E2E suite:
+
+```bash
+npm run test:e2e
+```
+
+Run dev-mode E2E suite:
+
+```bash
+npm run test:e2e:dev
+```
+
+Run preview-mode suite headed:
+
+```bash
+npm run test:e2e:headed
+```
+
+## Contributor checklist
+
+Before opening a PR:
+
+1. Run `npm run lint`.
+2. Run `npm run build:esm` for runtime/build changes.
+3. Run relevant Playwright tests for UI/runtime changes.
+4. Update docs when user-facing behavior or workflows change.
+
+## Scope guidance
+
+- Keep changes focused to `@knighted/develop`.
+- Preserve CDN-first loading and fallback behavior.
+- Avoid editing generated output unless explicitly required.

docs/media/develop-ide-flow.gif

@@ -2,54 +2,16 @@
 
 Focused follow-up work for `@knighted/develop`.
 
-1. **In-browser lint rules review and expansion**
-   - Review the currently active Biome lint configuration in `src/modules/lint-diagnostics.js`, including rule groups, severities, and any custom suppression behavior.
-   - Produce a recommended rule profile for component and style linting that balances signal quality with playground ergonomics.
-   - Evaluate additional Biome rules to enable (or elevate severity) for:
-     - correctness and suspicious patterns in component code,
-     - accessibility and style consistency in JSX output,
-     - CSS quality checks for style sources currently supported by Biome.
-   - Revisit existing exceptions (for example unused App/View/render bindings) and document clear criteria for when suppression is acceptable.
-   - Add/update regression coverage for the chosen rule profile in Playwright so diagnostics button/drawer behavior remains stable as rules evolve.
-   - Document the finalized lint rule strategy in project docs so contributors can reason about why each rule is enabled, disabled, or downgraded.
-   - Suggested implementation prompt:
-     - "Audit the current Biome lint rules used by `@knighted/develop`, propose and apply a refined rule profile for component/styles linting, and add/update Playwright coverage to keep diagnostics UX stable under the new rules. Preserve intentional suppressions only when justified and document the reasoning. Validate with `npm run lint`, `npm run build:esm`, and targeted lint diagnostics Playwright tests."
-
-2. **In-browser component type checking**
-   - Add editor-linked diagnostics navigation so each issue can jump to the exact line/column in the component source.
-   - Surface line/column context directly in the diagnostics UI (not just message text) to speed up triage.
-   - Continue improving typecheck performance for first-run and large sources while keeping the preview loop non-blocking.
-
-3. **In-browser component testing**
+1. **In-browser component testing**
    - Explore authoring and running component-focused tests in-browser (for example, a Vitest-compatible flow) using CDN-delivered tooling.
    - Define a lightweight test UX that supports writing tests, running them on demand, and displaying results in-app.
 
-4. **CDN failure recovery UX**
+2. **CDN failure recovery UX**
    - 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."
-
-6. **Deterministic E2E lane in CI**
+3. **Deterministic E2E lane in CI**
    - Add an integration-style E2E path that uses locally served/pinned copies of CDN runtime dependencies for test execution, while keeping production runtime behavior unchanged.
    - Keep the current true CDN-backed E2E path as a separate smoke check, but make the deterministic lane the required gate for pull requests.
    - Run this deterministic E2E suite on **every pull request** in CI.