Add regression tests for AppRun routing bootstrap and pretty-link examples

- Introduced `apprun-routing-bootstrap.spec.ts` to cover routing bootstrap scenarios including hash/native routing, pretty-link opt-in, and initial-route suppression.
- Added `pretty-link-examples.spec.ts` to validate routing intent for runnable AppRun examples, ensuring proper configuration and behavior across various examples and documentation.

Author: yysun

.docs/plans/2026/07/13/plan-explicit-pretty-links.md

@@ -0,0 +1,85 @@
+# Plan: Configurable pretty-link routing for 6.0.0
+
+## Goal
+
+Align AppRun 6.0.0 with the 3.38.1 routing boundary: hash/native behavior without configuration, explicit `use_prettyLink()` or `true` for `/path` SPA navigation, and no false-mode boilerplate across ordinary examples and generated documentation.
+
+## Current Context
+
+- The uncommitted implementation already exposes `app.use_prettyLink(enabled = true)`, uses mutually exclusive listener wiring, removes hash-handler inference, and updates public declarations.
+- `src/apprun.ts` currently initializes its internal `prettyLinks` flag to `true`; this is the single framework control point that must return to the 3.38.1 value of `false`.
+- The default-on decision caused explicit false calls in Play iframe wrappers, complete HTML examples, `demo/main.ts`, `demo/apprun-play.html`, and 40 generated `docs/**/*.html` hosts.
+- `tests/apprun-routing-bootstrap.spec.ts` currently asserts default pathname routing and must be inverted to verify default hash/native routing plus explicit true.
+- `tests/pretty-link-examples.spec.ts` currently requires false calls in preview wrappers and generated documentation hosts; the revised policy must reject that boilerplate instead.
+- `README.md`, `WHATSNEW.md`, `MIGRATION.md`, routing references, and public type comments currently describe default-on behavior and must distinguish no call from the argument-free method call.
+- The TypeScript browser URL, sibling AppRun iframe runtime, synchronous compiled-script execution, CodeMirror selector fix, balanced invocation scanner, tracked Play bundle, and Play source map are independent fixes and remain in scope.
+- Verification remains Jest through `npm test`, the TypeScript/Rollup/Webpack pipeline through `npm run build`, ESLint through `npm run lint`, and the browser scenarios in `.docs/tests/test-explicit-pretty-links.md`.
+
+## Decisions
+
+- Initialize the internal `prettyLinks` flag to `false`; keep `app.use_prettyLink(enabled = true)` so `app.use_prettyLink()` is an explicit enable operation exactly like 3.38.1.
+- Install only hash initialization and `hashchange` when no call or false is selected. Install pathname initialization, `popstate`, and guarded anchor interception only after argument-free or explicit-true configuration.
+- Keep routing mode independent of registered `#` handlers and retain last-call-wins behavior before `DOMContentLoaded`.
+- Remove explicit false calls that exist only to counter the abandoned default-on policy: Play wrappers and hosts, generated documentation pages, complete non-routing examples, and the shared hash demo bootstrap.
+- Keep explicit routing calls where they teach or own routing: false in the hash-routing example, true in the path-routing example, CLI path SPA, add-components path SPA, and routing documentation.
+- Keep reusable Play bundles neutral about host routing. Under default-off, loading them must naturally preserve native host navigation without a host opt-out.
+- Preserve pinned TypeScript, sibling runtime resolution, classic compiled-script execution, editable CodeMirror input, `apprun-play.js` publishing, and its source map.
+- Do not add a feature flag, fallback detector, compatibility branch, or environment-specific routing mode.
+
+## Phased Tasks
+
+### Phase 1 - Reconcile the reversed default
+
+- [x] Update `.docs/reqs/2026/07/13/req-explicit-pretty-links.md` so no call or false means hash/native and argument-free or true means pretty links.
+- [x] Update `.docs/tests/test-explicit-pretty-links.md` so browser scenarios exercise default-off behavior and explicit enablement.
+- [x] Review the revised REQ, AP, and E2E spec together and confirm the 3.38.1 compatibility boundary is unambiguous.
+
+### Phase 2 - Restore the 3.38.1 framework default
+
+- [x] Update `src/apprun.ts` so `prettyLinks` initializes to `false` while `use_prettyLink(enabled = true)` remains unchanged.
+- [x] Update source and declaration comments in `src/apprun.ts`, `src/router.ts`, `src/types.ts`, and `apprun.d.ts` to describe default hash/native mode and explicit pretty-link enablement.
+- [x] Preserve mutually exclusive listeners, last-call precedence, no-init behavior, base-path normalization, and removal of hash-handler inference.
+
+### Phase 3 - Remove default-on configuration churn
+
+- [x] Remove preview-level false calls from `src/apprun-code.tsx`, `src/apprun-play.tsx`, and ordinary new-tab generation in `demo/components/play.tsx` without changing TypeScript loading or compiled-script timing.
+- [x] Remove false calls added solely for default-on behavior from `demo/main.ts`, `demo/apprun-play.html`, complete non-routing README/What's New examples, and all tracked generated documentation hosts.
+- [x] Keep false only in deliberate hash-routing guidance/examples and keep true in deliberate `/path` applications and examples.
+- [x] Remove the generated-host opt-out explanation from `docs/about/index.html` because reusable Play now inherits the framework's native-navigation default.
+
+### Phase 4 - Rewrite regression policy around opt-in pretty links
+
+- [x] Update `tests/apprun-routing-bootstrap.spec.ts` to execute default hash/native listeners and explicit argument-free/true path listeners.
+- [x] Update `tests/pretty-link-examples.spec.ts` so generic examples, Play wrappers, hash-default hosts, and generated docs contain no unnecessary false call.
+- [x] Retain coverage for multiline/nested/semicolonless invocation discovery, Play runtime alignment, source-map publishing, editor input, and the two explicit routing examples.
+- [x] Add built-bundle assertions that loading Play without configuration leaves native host links alone and that explicit true enables path interception.
+
+### Phase 5 - Align public guidance
+
+- [x] Update `README.md`, `WHATSNEW.md`, and `MIGRATION.md` to state that no call or false preserves hash/native behavior while argument-free or true enables pretty links.
+- [x] Update `ai/building-apprun-spa.md` and `skills/apprun/references/routing-navigation.md` so `/path` SPAs explicitly call true and generic examples remain configuration-free.
+- [x] Confirm documentation never describes argument-free `use_prettyLink()` as equivalent to making no call.
+
+### Phase 6 - Rebuild, verify, and review
+
+- [x] Run `npm test -- --runInBand tests/apprun-routing-bootstrap.spec.ts tests/router.spec.ts tests/typescript-declarations.spec.ts tests/pretty-link-examples.spec.ts` and record focused evidence.
+- [x] Run `npm test -- --runInBand`, `npm run build`, and `npm run lint`; retain generated Pages bundles and report only actual warnings or failures.
+- [x] Execute the built-bundle routing and Play scenarios from `.docs/tests/test-explicit-pretty-links.md`.
+- [x] Run `git diff --check` and repeated code review until no default-on wording, unnecessary false calls, stale generated-host changes, or major findings remain.
+
+## Validation
+
+- Focused routing tests: `npm test -- --runInBand tests/apprun-routing-bootstrap.spec.ts tests/router.spec.ts tests/typescript-declarations.spec.ts tests/pretty-link-examples.spec.ts`.
+- Full unit suite: `npm test -- --runInBand`.
+- Production build: `npm run build`.
+- Static analysis: `npm run lint`, reporting the existing warning baseline separately from errors.
+- Browser behavior: execute `.docs/tests/test-explicit-pretty-links.md` against built bundles and inspect click prevention, `pushState`, `hashchange`, `popstate`, compiler availability, and editor input.
+- Scope: `git diff --check`, `git status --short`, and a requirement-focused review of every remaining changed file.
+
+## Rollback / Risk
+
+- Applications that relied on the temporary uncommitted default-on behavior must explicitly call `app.use_prettyLink(true)`; this is intentional and matches 3.38.1.
+- The argument-free method call enables pretty links even though making no call leaves them disabled. Documentation and tests must keep that distinction explicit.
+- Removing false calls must not remove deliberate hash-mode teaching examples or disturb the Play compiler/runtime/editor fixes.
+- Generated documentation pages should return to their prior HTML except for independently required runtime asset changes; broad host-page churn is specifically rejected.
+- No schema, persisted data, dependency, package version, or release publication is involved.

.docs/reqs/2026/07/13/req-explicit-pretty-links.md

@@ -0,0 +1,48 @@
+# Configurable pretty-link routing for 6.0.0
+
+## Problem
+
+Making pretty-link routing the 6.0.0 default forces every hash-routed, multi-page, documentation, and non-routing host to add `app.use_prettyLink(false)` merely to preserve normal browser navigation. That creates broad example and generated-page churn for an opt-in SPA feature. AppRun 3.38.1 already established the safer boundary: routing remains hash/native by default, while applications that own `/path` navigation enable pretty links explicitly.
+
+## Requirement
+
+AppRun 6.0.0 must expose the typed `app.use_prettyLink` startup API with the same default-off behavior as 3.38.1. Loading AppRun without a configuration call must use hash initialization and native browser links. Calling `app.use_prettyLink()` or `app.use_prettyLink(true)` before `DOMContentLoaded` must enable pathname initialization, `popstate`, and guarded same-origin anchor interception. Calling `false` must explicitly select the default hash/native mode. Play compiler, runtime-alignment, generated-asset, and editor-input fixes must remain intact without requiring false-mode boilerplate in ordinary examples or hosts.
+
+## Acceptance Criteria
+
+- [x] AppRun 6.0.0 initializes in hash/native mode when the application makes no `use_prettyLink` call.
+- [x] Default startup initializes from `location.hash`, listens for `hashchange`, and does not attach the path `popstate` listener or body-level anchor interceptor.
+- [x] `app.use_prettyLink()` and `app.use_prettyLink(true)` enable pathname initialization, `popstate`, and eligible same-origin anchor interception with the existing `pushState` and route behavior.
+- [x] `app.use_prettyLink(false)` explicitly selects hash initialization, `hashchange`, and native ordinary links.
+- [x] The last `use_prettyLink` call before `DOMContentLoaded` determines the mode, and later calls do not rewire installed listeners.
+- [x] Registering `#` or `#/` handlers does not silently override the default or an explicit routing choice.
+- [x] `apprun-no-init` and `app['no-init-route']` suppress only the initial route call in either mode.
+- [x] Public TypeScript declarations expose `use_prettyLink(enabled?: boolean): void`.
+- [x] Public routing and migration documentation distinguishes no call or false as hash/native mode from argument-free or true as pretty-link mode.
+- [x] Ordinary Play previews, reusable Play bundles, generated documentation hosts, complete non-routing HTML examples, and the main hash-routed demo require no false-mode call.
+- [x] The two Play routing examples remain explicit: `Routing (component event)` demonstrates `false`, and `Routing (mount options)` demonstrates `true`.
+- [x] Repository examples call `use_prettyLink` only when routing behavior is the subject or when a page intentionally owns `/path` navigation.
+- [x] Automated coverage rejects false-mode boilerplate in generic examples and generated hosts while requiring explicit true in deliberate path-routing applications.
+- [x] Both Play generators load `typescript@5.8.3/lib/typescript.js` before calling `ts.transpileModule`.
+- [x] Play previews load the AppRun HTML runtime from the same local or deployed build as the Play component.
+- [x] The Play page hides only its direct source textarea so CodeMirror remains editable.
+- [x] Tracked Pages bundles and referenced source maps are published from the current 6.0 build.
+- [x] Listener-level routing tests, example-policy tests, the full unit suite, and the production build pass with the default-off contract.
+
+## Constraints
+
+- Preserve the public name and signature: `app.use_prettyLink(enabled?: boolean)`.
+- Match 3.38.1 semantics exactly at the configuration boundary: internal mode starts `false`, while an omitted method argument defaults to `true`.
+- Treat routing mode as startup configuration selected before `DOMContentLoaded`.
+- Preserve direct route events, hierarchical matching, `basePath`, no-init behavior, router events, 404 behavior, and guarded anchor eligibility.
+- Do not restore hash-handler detection as a hidden mode switch.
+- Remove only configuration and documentation churn made unnecessary by the default-off decision; preserve the Play compiler, runtime, editor, test-quality, and publishing fixes.
+- Preserve tracked deployment outputs under `demo/` and `docs/assets/` while keeping `dist/` generated and ignored.
+
+## Non-Goals
+
+- Supporting routing-mode changes after AppRun initializes.
+- Redesigning link eligibility, route matching, or component registration.
+- Adding an environment variable, compatibility shim, alias, or second routing API.
+- Preserving the abandoned 6.0.0 default-on policy through widespread explicit-false calls.
+- Changing the package version or publishing a release.

.docs/tests/test-explicit-pretty-links.md

@@ -0,0 +1,72 @@
+# E2E: Configurable pretty-link routing for 6.0.0
+
+## Scenario 1 - Hash and native navigation are the default
+
+1. Load a page that imports the built AppRun browser bundle without calling `app.use_prettyLink`.
+2. Register observable hash and path route handlers plus an ordinary same-origin anchor.
+3. Confirm startup dispatches `location.hash`, installs `hashchange`, and does not install `popstate` or body-level click interception.
+4. Click the anchor and confirm AppRun does not prevent native browser navigation.
+5. Change the hash and confirm AppRun dispatches the hash route.
+
+## Scenario 2 - Argument-free and true explicitly enable pretty links
+
+1. Load one page that calls `app.use_prettyLink()` and another that calls `app.use_prettyLink(true)` before `DOMContentLoaded`.
+2. Register a path route and a same-origin anchor on each page.
+3. Confirm pathname initialization, `popstate`, body-level guarded anchor interception, `history.pushState`, and path dispatch on both pages.
+4. Use browser Back and confirm the restored pathname is dispatched.
+
+## Scenario 3 - Explicit false matches the default
+
+1. Load a page that calls `app.use_prettyLink(false)` before `DOMContentLoaded`.
+2. Confirm its listener set and native-link behavior match an unconfigured page.
+3. Confirm false remains useful as explicit documentation for a hash-routing example.
+
+## Scenario 4 - The last pre-startup configuration wins
+
+1. Call false and then true before `DOMContentLoaded`; confirm pretty-link path navigation.
+2. Repeat with true followed by false; confirm hash routing and native ordinary links.
+3. Call either mode after `DOMContentLoaded`; confirm installed listeners are not rewired.
+
+## Scenario 5 - Hash handlers are not a hidden mode switch
+
+1. Load an unconfigured page with and without `#` handlers; confirm both remain in default hash/native mode.
+2. Load an explicit-true page with a `#` handler; confirm it still uses pathname routing and path-link interception.
+
+## Scenario 6 - Initial-route suppression is mode-independent
+
+1. Load default-off and explicit-true pages with `apprun-no-init`, then repeat with `app['no-init-route']`.
+2. Confirm no page dispatches an initial route.
+3. Confirm later hash navigation still works in default mode and later path/Back navigation works in explicit-true mode.
+
+## Scenario 7 - Play and examples avoid false-mode boilerplate
+
+1. Load all 30 named Play entries.
+2. Confirm `Routing (component event)` explicitly demonstrates false and `Routing (mount options)` explicitly demonstrates true.
+3. Confirm the other 28 entries contain no routing-mode call.
+4. Confirm ordinary preview wrappers, reusable Play bundles, the main hash demo, complete non-routing documents, and generated documentation hosts contain no false call needed solely for startup.
+5. Confirm CLI and add-components `/path` applications explicitly call true.
+6. Confirm both preview documents load `typescript@5.8.3/lib/typescript.js`, expose `ts.transpileModule`, and load the sibling AppRun HTML runtime without a missing-method error.
+
+## Scenario 8 - Published Play assets preserve host behavior
+
+1. Build the repository and load `docs/assets/apprun-play.js` on an unconfigured host with an ordinary same-origin link.
+2. Confirm the link is not prevented because AppRun defaults to hash/native mode.
+3. Repeat on a host that calls `app.use_prettyLink(true)` before `DOMContentLoaded`; confirm path interception remains enabled after Play loads.
+4. Confirm Play iframes resolve `docs/assets/apprun-html.js` beside the Play bundle.
+5. Confirm `docs/assets/apprun-play.js.map` exists beside the bundle referenced by its `sourceMappingURL`.
+
+## Scenario 9 - Play source editor accepts input
+
+1. Load the root Play page and focus the left CodeMirror editor.
+2. Type a visible change into the current example.
+3. Confirm the editor content changes and the preview reruns with the edited source.
+4. Confirm the original source textarea remains hidden without hiding CodeMirror's internal input textarea.
+
+## Verification Evidence
+
+- Focused routing and example-policy tests: 4 suites, 106 tests passed.
+- Full unit suite: 47 suites, 620 tests passed.
+- Production build: TypeScript, Rollup, Webpack, and Pages asset sync passed.
+- Lint: 0 errors; 87 pre-existing warnings.
+- Browser catalog sweep: all 30 Play entries loaded one preview iframe with no TypeScript diagnostics or console errors.
+- Browser interaction: the left CodeMirror editor accepted input and reran the preview; explicit true intercepted a `/contact` link and rendered the Contact route.

MIGRATION.md

@@ -55,6 +55,30 @@ import { ROUTER_EVENT } from 'apprun';
 
 AppRun no longer aliases itself to `window.React` or stores the previous React value under `window._React`. That avoids React collisions while preserving the script-tag workflow existing examples use.
 
+### Routing Mode Is Explicit
+
+AppRun 6.0 keeps the 3.38.1 default: hash routing and native browser links unless the application explicitly enables pretty links.
+
+The startup API has two modes:
+
+- No call or `app.use_prettyLink(false)`: hash routing and native browser handling for ordinary links.
+- `app.use_prettyLink()` or `app.use_prettyLink(true)`: pretty-link path routing.
+
+Registering a `#` or `#/` handler no longer switches modes. Hash applications need no configuration, but can state the default explicitly:
+
+```ts
+import { app } from 'apprun';
+
+app.use_prettyLink(false);
+app.on('#home', () => {
+  // render home
+});
+```
+
+The last call before `DOMContentLoaded` determines the mode. Calls after that event do not remove or replace installed listeners. Put the selection in one startup entry point, immediately after loading or importing AppRun.
+
+Use argument-free or explicit `true` when an application owns `/path` navigation. Generic examples and Play previews need no call.
+
 ### `query()` Removed
 
 `app.query()` and `component.query()` have been removed. Use `runAsync()`.