apprun 3.37.3 → 3.38.1

package/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx jest *)",
+      "Bash(git -C /Users/esun/Documents/Projects/apprun ls-files)",
+      "Bash(awk -F/ '{print $1}')",
+      "Bash(git -C /Users/esun/Documents/Projects/apprun log --oneline -1 --format=%ci)",
+      "Bash(node -p \"require\\('./package.json'\\).version\")",
+      "Bash(npm run *)",
+      "Bash(npx tsc *)",
+      "Bash(grep -rn '\\\\$bind\\\\|\\\\$on\\\\|directive' src/directive.ts)",
+      "Bash(git mv *)",
+      "Bash(mv docs/done/* .docs/done/2026/06/21/)",
+      "Bash(mv docs/plan/* .docs/plans/2026/06/21/)",
+      "Bash(node -e ' *)"
+    ]
+  }
+}

package/.docs/done/2026/07/13/explicit-pretty-links.md

@@ -0,0 +1,32 @@
+# Explicit pretty-link routing
+
+## Summary
+
+- Restored hash routing and ordinary browser navigation as AppRun's default, reversing the automatic anchor interception introduced after 3.30.2.
+- Restored the historical `app.use_prettyLink(enabled = true)` API so SPA path routing is explicit and can be disabled before startup.
+- Kept `apprun-no-init`, `app['no-init-route']`, `basePath`, route events, `pushState`, and `popstate` behavior within their existing boundaries.
+- Replaced a copied-conditional router test file with behavior-level coverage that executes AppRun's real browser listener wiring.
+- Updated source/package declarations and `WHATSNEW.md` with the public configuration contract.
+- Audited maintained examples by actual navigation behavior. README, What's New, the CLI starter, the standalone add-components demo, and the Play path-routing example now opt in; hash routing, direct route dispatch, historical plans, and deliberate full-page navigation remain unchanged.
+- Fixed both TypeScript-backed Play renderers so browser-global examples execute synchronously before `DOMContentLoaded`, removing the race that made a correct `app.use_prettyLink()` call arrive too late.
+- Added catalog-wide compilation coverage and fixed the existing `SVG - xlink` JSX parse error it exposed.
+
+## Verification
+
+- Pre-fix `npm test -- --runInBand tests/apprun-routing-bootstrap.spec.ts`: failed 6 of 8 tests on automatic path mode and the missing API.
+- Focused `npm test -- --runInBand tests/apprun-routing-bootstrap.spec.ts tests/router.spec.ts tests/typescript-declarations.spec.ts`: 3 suites and 45 tests passed.
+- Example-focused `npm test -- --runInBand tests/pretty-link-examples.spec.ts tests/apprun-routing-bootstrap.spec.ts tests/router.spec.ts`: 3 suites and 33 tests passed, including compilation of every Play catalog entry.
+- Full `npm test -- --runInBand`: 48 suites and 548 tests passed.
+- `npm run build`: TypeScript, Rollup, and Webpack completed successfully.
+- Generated bundle inspection found `app.use_prettyLink()` in `demo/app.js` and synchronous `module: none` / `text/javascript` execution in both Play bundles before generated outputs were restored.
+- Browser E2E: default full-page and hash navigation, opt-in click and Back routing, explicit opt-out, and both no-init modes passed against the built UMD bundle.
+- Example browser E2E: Playground Contact and About links rendered in-place, the hash example remained hash-routed, and the standalone add-components About link rendered at `/demo-html/add-components/about` under its base path.
+- rlp-com compatibility proof: its remaining Jest suite passed and all eight entries built with the shim temporarily removed against the corrected local AppRun checkout.
+- CR and VR passed with no blocking findings; `git diff --check` passed in both repositories.
+
+## Notes
+
+- Routing mode is locked at `DOMContentLoaded`; live mode switching remains out of scope.
+- rlp-com's shim remains committed until a fixed AppRun version is published and consumed. Removing it while the dependency still resolves the broken published 3.38.0 would make clean builds regress.
+- Generated AppRun build outputs were used for E2E and consumer verification, then restored according to repository convention.
+- Play snippets are intentionally browser-global script examples. Import/export module snippets are outside these Play surfaces' current example contract.

package/.docs/done/2026/07/13/first-render-dom-attributes.md

@@ -0,0 +1,18 @@
+# First-render DOM class reconciliation
+
+## Summary
+
+- Restored AppRun 3.30.2 behavior when a null- or undefined-props vnode reuses an element with a stale server class.
+- Kept the fix inside `mergeProps`; no application-specific spinner logic or DOM-attribute hydration was introduced.
+- Added targeted coverage for the loading-spinner failure, undefined/null props, explicit `className` replacement, and preservation of unrelated server attributes.
+
+## Verification
+
+- Pre-fix focused test failed both null and undefined cases by retaining `loader-ripple spinner`; the post-fix file passes all 14 tests.
+- Adjacent VDOM audit passed 7 suites and 90 tests covering normalization, booleans, datasets, styles, skip logic, SSR, and contamination cleanup.
+- Full `npm test -- --runInBand` passed 47 suites and 544 tests; `npm run build` completed TypeScript, Rollup, and Webpack successfully.
+
+## Notes
+
+- Historical merge-path comparison found no additional 3.38.0 regression from this guard change; only the synthesized null-props class-removal key was lost.
+- Existing expected console warnings/assertions remain in the full test output but do not fail the suite.

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

@@ -0,0 +1,119 @@
+# Plan: Explicit pretty-link routing
+
+## Goal
+
+Restore normal browser navigation and hash routing as AppRun's default while making SPA path-link interception an explicit, typed startup choice through `app.use_prettyLink`.
+
+## Current Context
+
+- `src/apprun.ts` currently infers hash mode from `app.find('#')`/`app.find('#/')`; otherwise it initializes from `location.pathname` and installs a body-level same-origin anchor interceptor.
+- AppRun v3.30.2 initialized hash routing and did not intercept normal links. Commit `791b17d` introduced an explicit `app.use_prettyLink()` opt-in, while the later auto-routing change removed that API and changed the default.
+- AppRun v3.30.2 also registered a `#` no-op fallback. The current `/` no-op fallback alone would make an empty default hash initialization dispatch `/`, so the `#` fallback must be restored without removing the current path fallback.
+- `src/types.ts` and `apprun.d.ts` define the public `IApp` contract but currently expose no pretty-link configuration.
+- `tests/router-fix.spec.ts` copies the old routing conditionals instead of executing listeners registered by `src/apprun.ts`; the behavior-level bootstrap suite will replace it so stale auto-detection assertions do not survive the fix.
+- `README.md` and the Play `Routing (mount options)` example use ordinary `/path` anchors but do not call `app.use_prettyLink()`, so both examples contradict the restored explicit opt-in contract.
+- `cli/app.js` and `demo-html/add-components` are maintained runnable path-anchor examples and also need an explicit opt-in before their first AppRun mount.
+- The Play `Routing (component event)` example uses hash anchors and must remain in default hash mode.
+- The usage comments in `src/apprun.ts` and `src/router.ts` show path routes without clearly separating direct event routing from automatic browser path interception.
+- `src/apprun-code.tsx` and `src/apprun-play.tsx` dynamically append compiled code as a second module. The preview document can therefore fire `DOMContentLoaded` before `app.use_prettyLink()` runs, making an otherwise-correct path example navigate its iframe instead of routing in place.
+- rlp-com has eight esbuild entry points. `_esbuild.js` injects `src/apprun-disable-pretty-links.ts`, which registers a fake `#` route, and `src/__tests__/apprun-disable-pretty-links.spec.ts` locks in that workaround.
+- AppRun uses Jest/jsdom, `npm test`, and `npm run build`. rlp-com uses Jest and `npm run build` with AppRun 3.38.0 from `node_modules`.
+- rlp-com's only remaining non-shim unit file is `src/__tests__/search.spec.ts`, so its complete Jest suite is the narrowest honest post-cleanup test command.
+- This is a regression-prone routing change, so `.docs/tests/test-explicit-pretty-links.md` defines browser-level scenarios.
+
+## Decisions
+
+- Restore `app.use_prettyLink(enabled = true)` as a startup configuration method. The historical name is intentionally retained despite its casing and singular noun.
+- Default to hash routing and normal browser link navigation. Remove route-mode inference from registered `#` handlers; an explicit opt-in selects path mode.
+- Lock the selected mode when AppRun handles `DOMContentLoaded`. Dynamic listener installation/removal after initialization is rejected as unnecessary lifecycle complexity.
+- In hash mode, install only `hashchange` routing and initialize from `location.hash`. In pretty-link mode, install only path `popstate`, initialize from the normalized pathname, and install the existing body click handler.
+- Restore the built-in `#` no-op alongside the current `/` no-op so an empty hash dispatches the hash root without reintroducing handler-based mode inference.
+- Keep `apprun-no-init` and `app['no-init-route']` independent of mode selection so they suppress the initial call without disabling later navigation listeners.
+- Preserve the existing click eligibility and `basePath` implementation; tightening anchor interception is a separate behavior change.
+- Prove the rlp-com injected fake route and its test can be removed by building all entries against the corrected local checkout, then restore the workaround until a fixed AppRun package version is published. Do not commit a consumer state that still resolves the broken published 3.38.0 package.
+- Keep examples explicit at the point of use: runnable examples with ordinary path anchors call `app.use_prettyLink()` before rendering or mounting, while hash and programmatic routing examples remain unchanged.
+- Classify examples by navigation behavior, not slash-prefixed strings: CLI and standalone demo path anchors need opt-in; historical documentation, direct `route(...)`, and deliberate `window.location` navigation do not.
+- Clarify the API comments instead of implying that every slash-prefixed route requires pretty-link mode; direct `route(...)` and `app.run(...)` calls continue to work in either startup mode.
+- Compile TypeScript-backed Play examples as script-style code and append them synchronously from each bootstrap module, so startup configuration executes before the preview document's `DOMContentLoaded` boundary. The example surfaces use browser globals and contain no imports or exports; preserving dynamically inserted module semantics would keep the startup race. Detecting API names inside source strings is rejected as brittle.
+
+## Phased Tasks
+
+### Phase 1 - Lock the regression and public contract
+
+- [x] Compare `src/apprun.ts` at v3.30.2, commit `791b17d`, and v3.38.0 to confirm the legacy default, historical API name, and current interception path.
+- [x] Add a targeted AppRun routing-bootstrap spec that captures and executes the actual listeners registered by `src/apprun.ts`.
+- [x] Record a pre-fix failure proving default startup currently registers path interception and does not expose `use_prettyLink`: the targeted suite failed 6 of 8 tests, with default startup dispatching `/` instead of `#initial` and all opt-in cases reporting `use_prettyLink is not a function`.
+
+### Phase 2 - Restore explicit routing configuration
+
+- [x] Update `src/apprun.ts` with a top-level file comment update and `app.use_prettyLink(enabled = true)` startup state.
+- [x] Replace hash-handler inference with explicit mode branching so default startup installs hash routing without a body click interceptor.
+- [x] Restore the built-in `#` no-op fallback so empty default hash initialization resolves to `#` while explicit path initialization continues to resolve pathname routes.
+- [x] Preserve path-mode initial route normalization, `basePath`, `popstate`, anchor `pushState`, and route dispatch when pretty links are enabled.
+- [x] Keep `apprun-no-init` and `app['no-init-route']` limited to the initial route call in both modes.
+- [x] Update `src/types.ts` and `apprun.d.ts` so `use_prettyLink(enabled?: boolean): void` is part of the public `IApp` contract.
+- [x] Update `WHATSNEW.md` so the public routing example opts in explicitly and the restored default is unambiguous.
+
+### Phase 3 - Complete behavior-level routing coverage
+
+- [x] Add tests proving default hash initialization and hashchange routing execute through AppRun's registered listeners.
+- [x] Add tests proving `use_prettyLink()` and `use_prettyLink(true)` initialize and navigate paths through `popstate`, click interception, and `basePath` handling.
+- [x] Add tests proving `use_prettyLink(false)` overrides an earlier opt-in before initialization.
+- [x] Add tests proving `apprun-no-init` and `app['no-init-route']` suppress initial routing without suppressing the active mode's later listeners.
+- [x] Remove `tests/router-fix.spec.ts` after its no-init and routing-mode cases are covered through the real AppRun bootstrap.
+- [x] Extend `tests/typescript-declarations.spec.ts` to assert the restored public method exists and accepts omitted or boolean arguments.
+- [x] Run the focused AppRun routing tests: 3 suites and 45 tests passed.
+
+### Phase 4 - Prove the rlp-com shim is removable after release
+
+- [x] Temporarily remove `inject: ['src/apprun-disable-pretty-links.ts']`, the injected file, and its test from rlp-com without adding a replacement shim.
+- [x] Make rlp-com verification consume the corrected local AppRun package through a temporary `node_modules/apprun` symlink without changing its manifests or lockfile.
+- [x] Run rlp-com's complete `npm test -- --runInBand` suite (1 suite and 1 test passed) and `npm run build`; all eight entry points built without injected routing configuration.
+- [x] Restore rlp-com's workaround after verification because its package manifest still resolves the broken published `apprun@3.38.0`; deletion is a release follow-up, not part of this framework commit.
+
+### Phase 5 - Full verification and review
+
+- [x] Run AppRun's full `npm test -- --runInBand` suite: 47 suites and 538 tests passed, with existing expected console output remaining non-failing.
+- [x] Run AppRun's `npm run build`; TypeScript, Rollup, and Webpack passed, and generated build outputs were restored according to repository convention after E2E and local-package verification.
+- [x] Execute `.docs/tests/test-explicit-pretty-links.md` against built AppRun browser code: default and explicit opt-out links loaded the server page, hash routing fired, opt-in click and Back routing updated the URL and route state, and both no-init modes skipped only initial dispatch.
+- [x] Run `git diff --check` in both repositories and review both diffs against the requirement, plan, compatibility constraints, and non-goals; CR passed after restoring rlp-com to its release-safe state.
+
+### Phase 6 - Completion artifacts and commits
+
+- [x] Update the REQ acceptance criteria and this plan only after corresponding implementation and evidence exist.
+- [x] Create `.docs/done/2026/07/13/explicit-pretty-links.md` with the implemented contract, exact verification results, and any concrete residual risk.
+- [x] Commit the AppRun framework, tests, declarations, and RPD artifacts with `fix: make pretty-link routing explicit`.
+
+### Phase 7 - Align runnable examples and API documentation
+
+- [x] Update `README.md` so its SPA path-anchor example calls `app.use_prettyLink()` before rendering and states that automatic browser path routing is opt-in.
+- [x] Update `demo/components/play-examples.ts` with the required file comment block and make only `Routing (mount options)` opt into pretty-link routing before rendering.
+- [x] Update the CLI starter and standalone add-components demo to opt in before their first AppRun mount.
+- [x] Update `src/apprun.ts` and `src/router.ts` file comments so path-link startup, direct route dispatch, and hash routing have distinct documented contracts.
+- [x] Add `tests/pretty-link-examples.spec.ts` to prove all maintained path-anchor examples opt in before rendering, hash and deliberate browser-navigation examples remain opt-in free, and every Play catalog entry compiles in script mode.
+- [x] Update both `src/apprun-code.tsx` and `src/apprun-play.tsx` so compiled script-style examples execute synchronously before `DOMContentLoaded` can complete.
+- [x] Run `npm test -- --runInBand tests/pretty-link-examples.spec.ts tests/apprun-routing-bootstrap.spec.ts tests/router.spec.ts`: 3 suites and 33 tests passed.
+- [x] Run `npm run build`, verify the generated Play bundles contain the corrected example/runtime, and restore generated artifacts according to repository convention.
+- [x] Execute the Playground scenario added to `.docs/tests/test-explicit-pretty-links.md` and confirm mount-options links route in-place; smoke-test the standalone add-components demo.
+- [x] Run the full unit suite (48 suites and 548 tests), `git diff --check`, CR, and VR against the expanded acceptance criteria.
+- [x] Update `.docs/done/2026/07/13/explicit-pretty-links.md` with the example-alignment changes and exact verification evidence.
+- [x] Commit the example, Play runtime source, documentation, tests, and updated RPD artifacts as one scoped follow-up.
+
+## Validation
+
+- Pre-fix proof: `npm test -- --runInBand tests/apprun-routing-bootstrap.spec.ts` must fail because default startup selects path interception and `use_prettyLink` is absent.
+- Focused AppRun verification: `npm test -- --runInBand tests/apprun-routing-bootstrap.spec.ts tests/router.spec.ts tests/typescript-declarations.spec.ts`.
+- Full AppRun suite: `npm test -- --runInBand`.
+- AppRun build: `npm run build`.
+- rlp-com compatibility proof: temporarily remove the shim and its spec, run `npm test -- --runInBand`, temporarily replace `node_modules/apprun` with a symlink to the built local AppRun checkout, run `npm run build`, then restore the installed package and tracked workaround so the repo remains reproducible until release.
+- Browser E2E: execute `.docs/tests/test-explicit-pretty-links.md` with built AppRun assets and verify URL, default prevention state, path routing events, and back navigation.
+- Example verification: `npm test -- --runInBand tests/pretty-link-examples.spec.ts tests/apprun-routing-bootstrap.spec.ts tests/router.spec.ts`, then run the Playground mount-options scenario against the rebuilt `demo/app.js`.
+- Diff hygiene: `git diff --check` in both repositories plus requirement-focused code review.
+
+## Rollback / Risk
+
+- Applications that began relying on automatic path interception in 3.35.0-3.38.0 must opt in explicitly. This is intentional restoration of the pre-regression default and must be called out in release notes or completion notes.
+- The routing mode is read at `DOMContentLoaded`; calls after initialization do not rewire listeners. Tests and documentation must make that boundary clear.
+- Multiple bundles share AppRun's global singleton. Default-off behavior removes rlp-com's import-order dependency rather than adding another one.
+- rlp-com cannot safely commit shim removal until a fixed AppRun version is published and its dependency is advanced; local-link verification proves the future cleanup without hiding this release dependency.
+- Rollback is limited to the routing bootstrap, public declaration, tests, and docs; no persisted data or schema migration is involved.

package/.docs/plans/2026/07/13/plan-first-render-dom-attributes.md

@@ -0,0 +1,66 @@
+# Plan: First-render DOM class reconciliation
+
+## Goal
+
+Restore AppRun 3.30.2 class cleanup when AppRun first renders a null-props vnode over server or placeholder markup, without broadening attribute cleanup or changing later render behavior.
+
+## Current Context
+
+- `src/vdom-my.ts` reuses same-tag DOM children and delegates prop changes to `updateProps`.
+- `src/vdom-my-prop-attr.ts` normalizes `className` only when `newProps` is truthy. A null-props vnode therefore returns `{}` before the patcher receives a `class` key.
+- AppRun 3.30.2 normalized null props through an empty object and synthesized `class: undefined`, causing the shared attribute setter to remove a stale DOM class. AppRun 3.38.0 lost only that null-props class cleanup in this merge path.
+- `tests/vdom-my-dom-contamination.spec.tsx` owns DOM/VDOM exact-matching and property-cache regression coverage.
+- The repository uses Jest with jsdom, `npm test`, and `npm run build`. This is a renderer-internal change, so no separate E2E specification is needed.
+
+## Decisions
+
+- Normalize null or undefined `newProps` through an empty object before `className` conversion, restoring the legacy `class: undefined` removal signal.
+- Keep `mergeProps` as the single diff policy and keep actual removal in `setAttributeOrProperty`.
+- Do not seed the cache from DOM attributes; that would broaden behavior beyond the regression and could remove internal or intentionally preserved markup.
+- Reject an application-specific spinner rule, a feature flag, a hydration mode, and changes to child/key reconciliation.
+
+## Phased Tasks
+
+### Phase 1 - Reproduce and scope the regression
+
+- [x] Add a failing case to `tests/vdom-my-dom-contamination.spec.tsx` that renders a null-props vnode over a `loader-ripple spinner` placeholder and proves the stale class is removed.
+- [x] Add a same-tag placeholder case proving explicit `className` replaces the server class, and confirm existing `class`/`className` normalization coverage remains intact.
+- [x] Run `npm test -- --runInBand tests/vdom-my-dom-contamination.spec.tsx` and record the pre-fix failure: both null and undefined cases retained `loader-ripple spinner` while the explicit `className` replacement case passed.
+
+### Phase 2 - Repair the shared reconciliation boundary
+
+- [x] Update `src/vdom-my-prop-attr.ts` so null or undefined new props still produce the legacy class-removal signal.
+- [x] Preserve the existing cached-prop path for all subsequent renders so property nullification, style replacement, dataset cleanup, and event cleanup remain stable.
+- [x] Confirm the fix does not inspect or remove unrelated existing DOM attributes and does not weaken focus, selection, scroll, or media skip logic; the regression test preserves representative `data-*` and `title` attributes.
+
+### Phase 3 - Audit adjacent attribute families
+
+- [x] Compare the 3.30.2 and 3.38.0 merge paths and record whether any behavior besides null-props class cleanup changed: the null guard removed only the synthesized `class: undefined` key; cached and non-class prop paths are unchanged.
+- [x] Run the focused DOM-contamination, attribute-normalization, boolean-attribute, dataset, style, skip-logic, and SSR test files: 7 suites and 90 tests passed.
+- [x] Confirm no router, keyed-child, lifecycle, or application-specific behavior was introduced; the diff is limited to the shared prop merge and its regression coverage.
+
+### Phase 4 - Full verification and review
+
+- [x] Run `npm test -- --runInBand`: 47 suites and 544 tests passed; existing expected console warnings/assertions remained non-failing.
+- [x] Run `npm run build`: TypeScript, Rollup, and Webpack completed successfully.
+- [x] Run `git diff --check` and review the final diff for scope, correctness, performance, and compatibility risks; no blocking code-review findings remain.
+
+### Phase 5 - Completion artifacts
+
+- [x] Update this plan with completed task state only after corresponding code and evidence exist.
+- [x] Create `.docs/done/2026/07/13/first-render-dom-attributes.md` with the implemented contract, verification commands, and any concrete residual risk.
+- [x] Commit only the requirement, plan, test, renderer, and done-document changes with a user-visible conventional commit message.
+
+## Validation
+
+- Pre-fix proof: `npm test -- --runInBand tests/vdom-my-dom-contamination.spec.tsx` must fail on inherited first-render attributes.
+- Focused regression: `npm test -- --runInBand tests/vdom-my-dom-contamination.spec.tsx tests/vdom-my-attribute-normalization.spec.tsx tests/vdom-my-boolean-attributes.spec.tsx tests/vdom-my-dataset-handling.spec.tsx tests/style.spec.tsx tests/vdom-my-skip-logic.spec.tsx tests/vdom-my-ssr.spec.tsx`.
+- Full suite: `npm test -- --runInBand`.
+- Build: `npm run build`.
+- Diff hygiene: `git diff --check` and a requirement-focused code review.
+
+## Rollback / Risk
+
+- Restoring the legacy synthesized `class` key is narrow, but any code that intentionally relied on a stale server class surviving a null-props render will change back to the pre-3.38 behavior.
+- The fix must not read browser-managed state or arbitrary HTML attributes.
+- Rollback is limited to the null-props normalization change and its targeted test; no schema, migration, or persisted data is involved.

package/.docs/plans/2026/07/13/plan-play-typescript-runtime.md

@@ -0,0 +1,77 @@
+# Play TypeScript Runtime Plan
+
+## Goal
+
+Restore the local `#play` experience by making its generated iframe load a valid, versioned TypeScript browser bundle before calling `ts.transpileModule`.
+
+## Current Context
+
+- `demo/main.ts` registers `src/apprun-code.tsx`, and `demo/components/play.tsx` creates the `<apprun-code>` element used by `http://localhost:8080/#play`.
+- Before this fix, `src/apprun-code.tsx` generated iframe HTML that loaded `https://cdn.jsdelivr.net/npm/typescript@latest` before calling `ts.transpileModule`.
+- On 2026-07-13, that mutable CDN package URL returns HTTP 404 with `Couldn't resolve the default file in typescript.`; therefore no `ts` browser global is installed.
+- `https://cdn.jsdelivr.net/npm/typescript@5.8.3/lib/typescript.js` returns HTTP 200 and matches the repository's locked TypeScript version.
+- `webpack.config.cjs` builds `src/apprun-code.tsx` into `dist/apprun-code.js` and also includes it in `demo/app.js`, which is the bundle served by the local root page.
+- `docs/assets/apprun-code.js` is not used by the local root page and has separate historical content, so it is outside this fix.
+
+## Decisions
+
+- Replace the mutable package-root URL with the explicit `typescript@5.8.3/lib/typescript.js` browser bundle. This fixes both sources of nondeterminism: the version and the package entrypoint.
+- Preserve `ts.transpileModule`; changing compiler APIs would expand the problem without benefit.
+- Regenerate only the normal build outputs required by the repository's build. Do not hand-edit minified bundles.
+- Do not add a fallback CDN or a guard around `ts`; either would convert a deterministic dependency failure into a harder-to-diagnose partial failure.
+- Add a narrow source assertion if the existing test layout supports it; otherwise rely on build plus browser verification because the failure occurs in generated iframe HTML and external script loading.
+
+## Phased Tasks
+
+### Phase 1 - Discovery and scope lock
+
+- [x] Trace `index.html` through `demo/app.js`, `demo/main.ts`, `demo/components/play.tsx`, and `src/apprun-code.tsx` to identify the generated iframe as the failing control point.
+- [x] Reproduce the external dependency failure by confirming that `https://cdn.jsdelivr.net/npm/typescript@latest` returns HTTP 404.
+- [x] Confirm that `https://cdn.jsdelivr.net/npm/typescript@5.8.3/lib/typescript.js` returns HTTP 200 and matches `package-lock.json`.
+- [x] Exclude router changes, fallback loaders, editor replacement, and `docs/assets/apprun-code.js` reconciliation from scope.
+
+### Phase 2 - Runtime dependency fix
+
+- [x] Add the required source-file comment block to `src/apprun-code.tsx` and record the Play runtime dependency contract there.
+- [x] Update `src/apprun-code.tsx` to load the explicit TypeScript 5.8.3 browser bundle before the module script invokes `ts.transpileModule`.
+- [x] Confirm the change does not introduce a fallback CDN, environment variable, compatibility mode, or swallowed runtime error.
+
+### Phase 3 - Regression coverage and generated output
+
+- [x] Inspect the existing Jest patterns for a narrow assertion over the generated Play runtime URL; no unit test was added because the suite has no Play iframe seam and exporting the private HTML generator would weaken the module boundary.
+- [x] Run `npm run build` so `dist/apprun-code.js` and `demo/app.js` contain the corrected URL, recording any additional generated-file changes for scope review.
+- [x] Verify with `rg` that `typescript@latest` is absent from the source and locally served Play bundles, and the explicit browser bundle URL is present.
+
+### Phase 4 - Runtime verification
+
+- [x] Execute `.docs/tests/test-play-typescript-runtime.md` against `http://localhost:8080/#play`.
+- [x] Confirm the Play iframe loads the versioned TypeScript script with HTTP 200 and produces no `ts is not defined` console error.
+- [x] Confirm the default `Hello World ($bind)` example renders and entering text updates its greeting.
+
+### Phase 5 - Review and completion evidence
+
+- [x] Review the uncommitted diff against `req-play-typescript-runtime.md`, excluding unrelated generated churn.
+- [x] Record exact build, test, URL, console, and interaction evidence in the completed plan.
+- [x] Mark remaining tasks complete only after their code or verification evidence exists.
+
+## Validation
+
+- `npm run build` must exit successfully and regenerate the local demo/runtime bundles.
+- `rg -n "typescript@latest|typescript@5\\.8\\.3/lib/typescript\\.js" src/apprun-code.tsx dist/apprun-code.js demo/app.js` must show no mutable URL and must show the explicit browser bundle URL in each relevant artifact.
+- The scenario in `.docs/tests/test-play-typescript-runtime.md` must pass in the browser: no missing-`ts` console error, successful TypeScript request, rendered preview, and a greeting that responds to bound input.
+- If a focused Jest regression test is added, run that file with `npx jest <test-file> --runInBand`; otherwise document why browser verification is the direct regression check.
+
+## Rollback / Risk
+
+- The browser runtime remains CDN-dependent. Pinning the exact version and file path makes the dependency stable but does not make Play available offline.
+- `npm run build` may regenerate tracked artifacts unrelated to this one-line source change. Review and retain only outputs owned by the corrected Play source path.
+- Rollback is the source URL reversal plus regeneration of the same browser bundles; no data or migration rollback is involved.
+
+## Execution Evidence
+
+- `npm run build` passed: TypeScript, Rollup, and Webpack completed successfully; Webpack reported `compiled successfully`.
+- The generated-output review retained only `demo/app.js`, `dist/apprun-code.js`, `esm/apprun-code.js`, and their source maps; unrelated build churn was removed.
+- The focused `rg` check found `typescript@5.8.3/lib/typescript.js` exactly once in each of `src/apprun-code.tsx`, `esm/apprun-code.js`, `dist/apprun-code.js`, and `demo/app.js`, with no `typescript@latest` match.
+- The pinned CDN URL returned HTTP 200 with `application/javascript; charset=utf-8`.
+- Browser E2E passed at `http://localhost:8080/#play`: the iframe contained exactly one TypeScript script with the pinned URL, the error console was empty, and entering `AppRun` changed the heading to `Hello AppRun`.
+- CR passed: generated source maps parse successfully, the source and generated artifacts contain the pinned URL exactly once, `git diff --check` passes, and no major review flaws remain.

package/.docs/plans/2026/07/13/plan-release-3-38-1-docs.md

@@ -0,0 +1,74 @@
+# Plan: AppRun 3.38.1 release documentation
+
+## Goal
+
+Make the public release documents accurately describe the fixes included after AppRun 3.38.0 and give path-routing users the migration instruction they need before 3.38.1 is versioned or published.
+
+## Current Context
+
+- `package.json` and `src/version.ts` still report `3.38.0`; this task prepares documentation only and must not imply that the release has already been cut.
+- Commit `668e291` is the 3.38.0 release baseline. The four commits after it are `3536c45` (first-render class cleanup), `b48df38` (explicit pretty-link routing), `001263f` (pinned Play TypeScript runtime), and `f7f8f3b` (pretty-link example alignment, Play startup timing, and SVG example repair).
+- `WHATSNEW.md` uses dated blockquote headings and longer user-oriented explanations. Its current top entry is `V3.38.0` dated July 26, 2025.
+- `WHATSNEW.md` currently contains the restored-routing bullet under `V3.38.0`, but that fix was implemented by post-release commit `b48df38`; leaving it there would make the published 3.38.0 history false.
+- `CHANGELOG.md` uses `## Vx.y.z` headings and concise bullets. Its current top entry is `V3.38.0`.
+- The routing change intentionally restores pre-3.35 behavior: hash routing and ordinary browser navigation are default; applications that want SPA `/path` interception must call `app.use_prettyLink()` before `DOMContentLoaded`.
+- Existing RPD done docs provide verified wording and evidence for the first-render and pretty-link fixes. The Play runtime requirement/plan records the pinned TypeScript browser bundle and successful browser verification.
+
+## Decisions
+
+- Add a new top-level 3.38.1 section to both public release documents and move the misplaced restored-routing bullet out of the historical 3.38.0 section. Preserve all other historical content.
+- Lead with the navigation compatibility correction because it changes how applications using ordinary path links must configure AppRun.
+- Include one compact migration snippet in `WHATSNEW.md`: `app.use_prettyLink();` before application startup. `CHANGELOG.md` will state the same contract without duplicating the full example.
+- Describe the DOM fix in user-visible terms—stale server/loading classes no longer survive the first client render—while retaining the null/undefined-props boundary for precision.
+- Group the Play runtime, startup timing, and example corrections into one coherent Play reliability item instead of presenting internal bundling details as separate features.
+- Do not add a feature flag, compatibility layer, separate migration document, package bump, publication step, or generated artifact change.
+- No E2E spec is needed: this is a documentation-only change over behavior already covered and verified by the completed implementation stories.
+
+## Phased Tasks
+
+### Phase 1 - Release scope and claim verification
+
+- [x] Compare commits `3536c45`, `b48df38`, `001263f`, and `f7f8f3b` with the 3.38.0 baseline so every proposed release-note claim has a concrete implementation source.
+- [x] Reconcile `.docs/done/2026/07/13/first-render-dom-attributes.md`, `.docs/done/2026/07/13/explicit-pretty-links.md`, and `.docs/plans/2026/07/13/plan-play-typescript-runtime.md` into a non-duplicative 3.38.1 change list.
+- [x] Confirm `package.json` remains `3.38.0` and record that versioning, tagging, and publication are excluded from this documentation task.
+
+### Phase 2 - User-oriented release notes
+
+- [x] Add a dated `V3.38.1` section at the top of `WHATSNEW.md` with the navigation compatibility correction, first-render class cleanup, and Play reliability fixes.
+- [x] Include an explicit `app.use_prettyLink()` migration example in `WHATSNEW.md` before describing SPA `/path` links as intercepted by AppRun.
+- [x] Move the unpublished restored-routing bullet from `V3.38.0` into `V3.38.1`, keeping all other historical `WHATSNEW.md` content intact.
+
+### Phase 3 - Concise changelog
+
+- [x] Add a `V3.38.1` section at the top of `CHANGELOG.md` with concise bullets matching the verified public behavior in `WHATSNEW.md`.
+- [x] State the restored routing default and opt-in requirement directly in `CHANGELOG.md` so the compatibility impact remains visible in abbreviated release views.
+- [x] Confirm the changelog does not claim a package bump, npm publication, git tag, or unrelated fixes.
+
+### Phase 4 - Documentation verification and completion
+
+- [x] Run a focused text check over `WHATSNEW.md` and `CHANGELOG.md` for `V3.38.1`, `use_prettyLink`, first-render class behavior, and Play runtime/example wording.
+- [x] Run `git diff --check` and review the documentation diff against every acceptance criterion and the four post-3.38.0 commits.
+- [x] Confirm `package.json`, lockfiles, `src/version.ts`, source files, tests, and generated bundles remain unchanged.
+- [x] Update the REQ and this plan only after the corresponding release-document edits and verification evidence exist.
+
+## Validation
+
+- `rg -n "V3\\.38\\.1|use_prettyLink|first render|TypeScript|Play" WHATSNEW.md CHANGELOG.md` must find the version heading and each required user-facing topic in the new sections.
+- `git diff --check` must pass.
+- `git diff --name-only` must contain only `WHATSNEW.md`, `CHANGELOG.md`, and the matching RPD documentation artifacts.
+- Review the final wording against `git log --oneline 668e291..HEAD` and the completed story docs; every claim must map to one of the four release commits.
+- No build, unit test, or E2E rerun is required because this task changes only Markdown release documentation and cites already-verified behavior.
+
+## Rollback / Risk
+
+- The main risk is release-note drift: describing 3.38.1 as already published or omitting the pretty-link opt-in would mislead users. Keep publication status and migration wording explicit.
+- Overly terse wording could hide the compatibility consequence; overly detailed wording could expose internal implementation noise. Use `WHATSNEW.md` for the explanation and `CHANGELOG.md` for the compact contract.
+- Rollback is limited to removing the new 3.38.1 sections and matching RPD docs; no runtime or package state changes are involved.
+
+## Execution Evidence
+
+- The focused `rg` check found the new 3.38.1 headings, `app.use_prettyLink()` migration guidance, first-render class fix, pinned TypeScript Play runtime, and repaired examples in both release documents.
+- `git diff --check` passed.
+- `git log --oneline 668e291..HEAD` contains exactly the four documented fix commits: `3536c45`, `b48df38`, `001263f`, and `f7f8f3b`.
+- Scope inspection found only `WHATSNEW.md`, `CHANGELOG.md`, and the matching RPD requirement/plan documents changed; `package.json`, `package-lock.json`, `src/version.ts`, source, tests, and generated bundles remain untouched.
+- CR passed with no blocking findings. No build, unit test, or E2E rerun was needed for this Markdown-only change.

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

@@ -0,0 +1,46 @@
+# Explicit pretty-link routing
+
+## Problem
+
+AppRun 3.35.0 through 3.38.0 automatically switches to path routing when no hash-route handler is registered. In that mode it installs a body-level click handler that prevents normal navigation for every same-origin anchor and replaces it with `history.pushState` plus an AppRun route event. This is a breaking change for multi-page applications such as rlp-com: ordinary links stop loading their server-rendered destination, and applications have no supported way to disable the interception.
+
+## Requirement
+
+AppRun must preserve normal browser navigation and legacy hash routing by default. SPA-style path routing and same-origin anchor interception must activate only when an application explicitly opts in through the restored `app.use_prettyLink` API. Applications must be able to opt out explicitly before AppRun initializes, and existing initial-route suppression and base-path behavior must remain intact.
+
+## Acceptance Criteria
+
+- [x] Without an explicit opt-in, AppRun initializes hash routing and does not attach a body-level anchor click interceptor.
+- [x] `app.use_prettyLink()` and `app.use_prettyLink(true)` enable path initialization, path `popstate` routing, and the existing same-origin anchor `pushState` behavior.
+- [x] `app.use_prettyLink(false)` disables pretty-link routing, including when it follows an earlier opt-in before initialization.
+- [x] `apprun-no-init` and `app['no-init-route']` continue to suppress only the initial route call in either routing mode.
+- [x] Path-mode base-path stripping and pushed navigation paths retain their current behavior.
+- [x] The public TypeScript declarations expose `use_prettyLink(enabled?: boolean): void`.
+- [x] Every maintained runnable example that uses ordinary `/path` anchors for AppRun SPA navigation opts into pretty-link routing before rendering or mounting route components, including README, What's New, the CLI starter, the standalone add-components demo, and the Play catalog.
+- [x] Hash-routing examples remain hash-based and do not opt into pretty-link routing.
+- [x] Public API documentation distinguishes direct route dispatch from automatic browser path navigation, which requires `app.use_prettyLink()` before initialization.
+- [x] Generated Play bundles contain the corrected mount-options example so locally served Playground and documentation Play surfaces match their sources.
+- [x] Both TypeScript-backed Play renderers execute compiled examples before their preview document reaches `DOMContentLoaded`, allowing startup configuration such as `app.use_prettyLink()` to take effect.
+- [x] Every maintained Play catalog example compiles under the synchronous script-mode compiler options.
+- [x] Targeted tests execute AppRun's real `DOMContentLoaded`, click, hashchange, and popstate wiring rather than duplicating the implementation logic inside the test.
+- [x] With its workaround temporarily removed, rlp-com's production build succeeds against the corrected local AppRun package, proving the workaround can be deleted after a fixed AppRun version is published and consumed.
+- [x] AppRun's focused router tests, full unit suite, and production build pass.
+
+## Constraints
+
+- Restore the historical `use_prettyLink` name so applications that used the earlier opt-in API remain source-compatible.
+- Treat the routing mode as startup configuration; callers must configure it before `DOMContentLoaded`.
+- Keep the event bus and direct `app.run('route', ...)` behavior available in both modes.
+- Preserve the existing `basePath`, router-event, and 404 contracts.
+- Keep changes surgical across the AppRun routing bootstrap and the obsolete rlp-com build shim.
+- Keep example changes surgical: opt in only examples that depend on browser `/path` anchor interception.
+- Treat historical plans, external links, explicit `window.location` navigation, and direct programmatic route dispatch as non-SPA-link examples; do not add pretty-link configuration to them.
+- Do not commit an rlp-com cleanup that still resolves the broken published `apprun@3.38.0`; consumer cleanup must follow a fixed package release.
+
+## Non-Goals
+
+- Supporting live routing-mode changes after AppRun has initialized.
+- Redesigning anchor eligibility for modifier keys, targets, downloads, query strings, or fragments.
+- Introducing a general configuration framework, environment variable, compatibility package, or application-specific click handler.
+- Changing hierarchical route matching or component route registration.
+- Publishing AppRun or changing rlp-com to an unpublished dependency during this implementation task.

package/.docs/reqs/2026/07/13/req-first-render-dom-attributes.md

@@ -0,0 +1,31 @@
+# First-render DOM class reconciliation
+
+## Problem
+
+AppRun 3.38.0 can reuse a server-rendered or placeholder element without removing its class when the first VDOM node has null or undefined props. Loading classes can therefore leak into the rendered application and turn loading UI into persistent application behavior. AppRun 3.30.2 removed that stale class in the same render path.
+
+## Requirement
+
+On the first reconciliation of an existing same-tag DOM element, AppRun must restore the legacy class contract: a vnode with null or undefined props removes a stale DOM class, while explicit `class` or `className` props replace it. Other property families and later render cycles must retain their current behavior.
+
+## Acceptance Criteria
+
+- [x] A first same-tag VDOM render with null or undefined props removes a stale server-rendered class from the reused element.
+- [x] A first VDOM render with explicit `class` or `className` replaces the server-rendered class.
+- [x] Dataset handling, boolean attributes, styles, event handlers, and form properties retain their current behavior.
+- [x] Subsequent VDOM updates still remove props omitted from later renders without accumulating DOM state.
+- [x] A targeted regression test reproduces the loading-spinner failure mode, and an audit confirms whether the null-props merge change caused any other behavioral regression.
+- [x] The focused VDOM tests, complete unit suite, and production build pass.
+
+## Constraints
+
+- Restore AppRun 3.30.2 class behavior without broadening first-render cleanup semantics.
+- Preserve focus, selection, scroll, and media-property skip logic.
+- Keep the fix inside the shared property/attribute reconciliation boundary.
+
+## Non-Goals
+
+- Removing arbitrary server-rendered attributes that AppRun 3.30.2 also preserved.
+- Introducing a hydration mode or reading existing DOM attributes into the VDOM property cache.
+- Changing keyed-child reconciliation, routing, component lifecycle, or rendering-engine selection.
+- Adding an application-specific spinner exception or compatibility flag.

package/.docs/reqs/2026/07/13/req-play-typescript-runtime.md

@@ -0,0 +1,29 @@
+# Play TypeScript Runtime
+
+## Problem
+
+The local Play page at `http://localhost:8080/#play` cannot render its examples. The generated preview iframe references `ts`, but the CDN request intended to define that browser global returns a 404 response. Users see `Uncaught ReferenceError: ts is not defined` instead of a working preview.
+
+## Requirement
+
+The Play page must load a valid, deterministic TypeScript browser runtime before compiling an example, so the preview can execute without a missing-`ts` error.
+
+## Acceptance Criteria
+
+- [ ] The generated Play iframe loads a concrete TypeScript browser bundle that returns JavaScript successfully.
+- [ ] Opening `http://localhost:8080/#play` produces no `ts is not defined` error.
+- [ ] The default `Hello World ($bind)` example renders and updates its greeting when text is entered.
+- [ ] The browser bundles served by the local development server contain the corrected runtime URL.
+
+## Constraints
+
+- Keep the current in-browser TypeScript compilation behavior and `ts.transpileModule` contract.
+- Use an explicit TypeScript version and browser bundle path; do not depend on the package's mutable default CDN entrypoint.
+- Keep the fix inside the existing Play component and normal build pipeline.
+
+## Non-Goals
+
+- Replacing the Play compiler or editor.
+- Adding fallback CDNs, runtime retries, or error suppression.
+- Refactoring routing, AppRun rendering, or the Play examples.
+- Reconciling unrelated historical differences in `docs/assets/apprun-code.js`.

package/.docs/reqs/2026/07/13/req-release-3-38-1-docs.md

@@ -0,0 +1,34 @@
+# AppRun 3.38.1 release documentation
+
+## Problem
+
+AppRun contains four fixes after 3.38.0, but its public release documents still stop at 3.38.0. Without a 3.38.1 entry, users cannot see that normal browser navigation is restored by default, path-routing applications must opt in explicitly, stale first-render classes are removed again, and the Play examples have been repaired.
+
+## Requirement
+
+Prepare the public AppRun release documentation for version 3.38.1. The documentation must accurately summarize the user-visible changes already present after the 3.38.0 release commit, make the pretty-link migration requirement explicit, and avoid claiming that 3.38.1 has already been versioned or published.
+
+## Acceptance Criteria
+
+- [x] `WHATSNEW.md` begins with a dated `V3.38.1` section above `V3.38.0`.
+- [x] `CHANGELOG.md` begins with a `V3.38.1` section above `V3.38.0`.
+- [x] Both release documents state that hash routing and normal browser navigation are the default again, and that SPA `/path` interception requires `app.use_prettyLink()` before AppRun initializes.
+- [x] The release notes mention the restored first-render removal of stale DOM classes when the new vnode has null or undefined props.
+- [x] The release notes mention the fixed Play TypeScript runtime and the repaired routing/examples behavior without overstating implementation detail.
+- [x] The release notes distinguish compatibility guidance from feature marketing and do not describe the 3.38.0 auto-interception behavior as still current.
+- [x] All release-note claims are traceable to commits after the 3.38.0 release commit.
+
+## Constraints
+
+- Keep `WHATSNEW.md` explanatory and user-oriented; keep `CHANGELOG.md` concise and scannable.
+- Use the repository's existing version-heading and chronological ordering conventions.
+- Preserve historical 3.38.0 and earlier entries except for moving the unpublished restored-routing bullet from 3.38.0 into its correct 3.38.1 section.
+- Do not edit source code, tests, generated bundles, dependency files, or package metadata.
+- Do not claim that npm publication, tagging, or a package-version bump has happened.
+
+## Non-Goals
+
+- Bumping `package.json`, lockfiles, or runtime version constants to 3.38.1.
+- Publishing to npm, creating a git tag, or drafting a GitHub release.
+- Rewriting historical release entries beyond correcting the misplaced 3.38.1 routing bullet, or documenting unrelated repository work.
+- Adding a separate migration guide when the required compatibility guidance fits directly in the release notes.

package/.playwright-mcp/console-2026-06-24T18-37-47-881Z.log

@@ -0,0 +1,17 @@
+[  488682ms] [ERROR] Failed to load resource: the server responded with a status of 404 () @ https://apprun.js.org/favicon.ico:0
+[  489109ms] [ERROR] Failed to load resource: the server responded with a status of 404 () @ https://apprun.js.org/dist/apprun-html.js:0
+[  489188ms] [ERROR] Failed to load resource: the server responded with a status of 404 () @ https://apprun.js.org/dist/apprun-html.js:0
+[  489188ms] [ERROR] Failed to load resource: the server responded with a status of 404 () @ https://apprun.js.org/dist/apprun-html.js:0
+[  489188ms] [ERROR] Failed to load resource: the server responded with a status of 404 () @ https://apprun.js.org/dist/apprun-html.js:0
+[  489524ms] ReferenceError: app is not defined
+    at <anonymous>:15:1
+[  489524ms] ReferenceError: app is not defined
+    at <anonymous>:15:1
+[  489524ms] ReferenceError: app is not defined
+    at <anonymous>:14:1
+[  489524ms] ReferenceError: app is not defined
+    at <anonymous>:12:1
+[  489515ms] [ERROR] Failed to load resource: the server responded with a status of 404 () @ https://apprun.js.org/dist/apprun-html.js:0
+[  489614ms] ReferenceError: Component is not defined
+    at <anonymous>:1:1
+[  491281ms] [INFO] Autofocus processing was blocked because a document already has a focused element. @ https://apprun.js.org/#play:0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Change Log
 
+## V3.38.1
+
+* Restore hash routing and normal browser navigation as the default; SPA `/path` interception now requires `app.use_prettyLink()` before AppRun initializes
+* Restore first-render removal of stale DOM classes when the new vnode has null or undefined props
+* Fix Play's TypeScript runtime and startup timing so browser-global examples and routing configuration run reliably
+* Align path-routing examples with the explicit pretty-link contract and repair the SVG xlink example
+
+## V3.38.0
+
+* Support for binding to nested objects and arrays with `$bind`
+* Support for type safe props and children in components
+* Use `unknown` instead of `any` for generic defaults
+
 ## V3.37.3
 
 * Updated skip logic for - removed `value` property
@@ -334,4 +347,4 @@
 * Event pubsub
 * Used virtual-dom, virtual-dom-html
 * Three versions: zero, jsx and html
-* Demo apps
+* Demo apps