@nutin/cli 2.1.1 → 3.0.0

package/templates/base/src/core/services/router/router.ts.hbs

@@ -1,23 +1,17 @@
-import { View, Navigation, Service, I18nService, AppEventBus } from '../../index.js';
-import { Language } from '../i18n/languages.js';
-import { Routes, RouteConfig, RouteGuardsManager, GuardResult } from './helpers/route-guard-manager.helper.js';
-import { ViewRenderManager } from './helpers/view-render-manager.helper.js';
-import { NavigationManager } from './helpers/navigation-manager.helper.js';
+import type { View } from '../../base-classes/view/view.js';
+import { Service } from '../../base-classes/service/service.js';
+import { Navigation } from '../event-bus/navigation.facade.js';
+import { AppEventBus } from '../event-bus/event-bus.js';
+import { I18nService } from '../i18n/i18n.js';
+import * as RouteGuardsManager from './helpers/route-guard-manager.helper.js';
+import type { GuardResult } from './helpers/route-guard-manager.helper.js';
+import * as ViewRenderManager from './helpers/view-render-manager.helper.js';
+import * as NavigationManager from './helpers/navigation-manager.helper.js';
+import type { HistoryMode } from './helpers/navigation-manager.helper.js';
+import { CONFIG } from '../../config.js';
 
 // centralized export
-export { Routes, RouteGuard } from './helpers/route-guard-manager.helper.js';
-export { NavigationManager } from './helpers/navigation-manager.helper.js';
-
-/**
- * IRouter is a type alias for the instance of Router, not a true interface 
- */
-export type IRouter = InstanceType<typeof Router>;
-
-export interface RouteMatch {
-  route: RouteConfig;
-  params: Record<string, string>;
-  pattern: string;
-}
+export * as NavigationManager from './helpers/navigation-manager.helper.js';
 
 class Router extends Service<Router> {
   private _currentView: View | null = null;
@@ -26,11 +20,16 @@ class Router extends Service<Router> {
   private onNavigate = (data: { path: string }) => this.navigate(data.path);
   private onReload = () => this.reload();
   private _busSubscriptions: Array<() => void> = [];
+  // Bumped by every navigation: one whose guards resolve after a newer navigation started
+  // is dropped instead of rendering over it.
+  private _navId = 0;
+  // False until the first view is rendered: the first load leaves focus to the browser.
+  private _hasRendered = false;
 
-  constructor(private routes: Routes) {
+  constructor(private routes: Nutin.Routes) {
     super();
     this.initializeEventListeners();
-    this.navigate(NavigationManager.getCurrentPath() + window.location.hash);
+    this.navigate(this.currentLocation());
     this.registerCleanup(this.removeEventListeners);
   }
 
@@ -42,13 +41,34 @@ class Router extends Service<Router> {
     window.removeEventListener('popstate', this.onPopState);
   }
 
+  // Re-renders the current page, so focus isn't moved (see focusView()).
   public async reload(): Promise<void> {
-    const currentRoute = NavigationManager.getCurrentPath();
-    await this.navigate(currentRoute + window.location.hash, false);
+    await this.navigateWithMode(this.currentLocation(), 'none', false);
   }
 
   public async navigate(path: string | '', pushState: boolean = true): Promise<void> {
-    const [rawPath = '', hash] = path.split('#');
+    await this.navigateWithMode(path, pushState ? 'push' : 'none', this._hasRendered);
+  }
+
+  public getCurrentParams(): Record<string, string> {
+    return { ...this._currentParams };
+  }
+
+  public getParam(key: string): string | undefined {
+    return this._currentParams[key];
+  }
+
+  // Path, query and hash of the current URL, as navigate() takes them.
+  private currentLocation(): string {
+    return NavigationManager.getCurrentPath() + window.location.search + window.location.hash;
+  }
+
+  private async navigateWithMode(path: string, mode: HistoryMode, moveFocus: boolean): Promise<void> {
+    const navId = ++this._navId;
+    const isStale = () => navId !== this._navId;
+    const [pathAndQuery = '', hash] = path.split('#');
+    const [rawPath = '', query] = pathAndQuery.split('?');
+    const search = query ? `?${query}` : '';
     const normalizedPath = NavigationManager.normalizePath(rawPath);
     const currentPath = NavigationManager.getCurrentPath();
 
@@ -56,7 +76,7 @@ class Router extends Service<Router> {
     const routeMatch = this.matchRoute(normalizedPath);
 
     if (!routeMatch) {
-      await this.handleNotFound(normalizedPath, currentPath, pushState);
+      await this.handleNotFound(normalizedPath, currentPath, mode, isStale, moveFocus);
       return;
     }
 
@@ -64,35 +84,58 @@ class Router extends Service<Router> {
       normalizedPath,
       routeMatch.route,
       routeMatch.params,
-      pushState
+      currentPath,
+      mode,
+      moveFocus
     );
 
-    if (!guardResult) return;
+    if (!guardResult || isStale()) return;
+
+    // Before the current view is torn down: it stays up while a lazy route's chunk loads.
+    const view = await this.resolveView(guardResult.viewConstructor!, NavigationManager.localizedUrl(normalizedPath, search, hash), isStale);
+    if (!view) return;
 
     this._currentView = await ViewRenderManager.transitionOutCurrentView(this._currentView);
     this._currentParams = routeMatch.params;
 
-    // Must run before renderNewView(): a view's onEnter() may rewrite the URL via
-    // NavigationManager.replaceState (e.g. canonicalizing a bare route to a default
-    // sub-page), which acts on whatever history entry is current — so that entry needs
-    // to already be this route's, not the previous view's, before onEnter() fires.
-    NavigationManager.updateHistory(normalizedPath, currentPath, pushState, hash);
+    // Must run before renderNewView(): a view's onEnter() may rewrite the URL via NavigationManager.replaceState(), 
+    // which acts on whatever history entry is current. This ensures current before onEnter() fires.
+    NavigationManager.updateHistory(normalizedPath, currentPath, mode, hash, search);
 
-    this._currentView = ViewRenderManager.renderNewView(
-      guardResult.viewConstructor!,
-      routeMatch.params
-    );
+    this._currentView = ViewRenderManager.renderNewView(view, routeMatch.params);
 
     NavigationManager.updateDocumentTitle(this._currentView, routeMatch.pattern);
     NavigationManager.scrollToHash(hash);
+    this.afterRender(moveFocus);
   }
 
-  public getCurrentParams(): Record<string, string> {
-    return { ...this._currentParams };
+  // Runs a route's view factory. A sync one behaves as it always did (its errors propagate).
+  // A lazy one is awaited: if it fails to load, recoverFromFailedViewLoad() takes over; if a
+  // newer navigation started meanwhile, the view (already mounted, empty, by its
+  // constructor) is destroyed and dropped.
+  private async resolveView(factory: Nutin.ViewFactory, url: string, isStale: () => boolean): Promise<View | null> {
+    if (isStale()) return null;
+    const result = factory();
+    if (!isPromise(result)) return result;
+
+    let view: View;
+    try {
+      view = await result;
+    } catch (error) {
+      if (!isStale()) NavigationManager.recoverFromFailedViewLoad(url, error);
+      return null;
+    }
+    if (isStale()) {
+      view.destroy();
+      return null;
+    }
+    return view;
   }
 
-  public getParam(key: string): string | undefined {
-    return this._currentParams[key];
+  // After updateDocumentTitle(): focusView() announces document.title when the view has no h1.
+  private afterRender(moveFocus: boolean): void {
+    if (moveFocus && this._currentView) NavigationManager.focusView(this._currentView);
+    this._hasRendered = true;
   }
 
   private initializeEventListeners(): void {
@@ -115,11 +158,13 @@ class Router extends Service<Router> {
   }
 
   private async handlePopState(): Promise<void> {
-    const newLocale = NavigationManager.getCurrentLocale();
-    if (newLocale && newLocale !== I18nService.currentLanguage) {
-      await I18nService.setCurrentLanguage(newLocale as Language);
+    if (globalThis.__NUTIN_I18N__ ?? CONFIG.i18n) {
+      const newLocale = NavigationManager.getCurrentLocale();
+      if (newLocale && newLocale !== I18nService.currentLanguage) {
+        await I18nService.setCurrentLanguage(newLocale as Nutin.Language);
+      }
     }
-    this.navigate(NavigationManager.getCurrentPath() + window.location.hash, false);
+    this.navigateWithMode(this.currentLocation(), 'none', this._hasRendered);
   }
 
   /**
@@ -128,7 +173,7 @@ class Router extends Service<Router> {
    * - '/users/:id?' matches '/users' and '/users/123'
    * - '/posts/:id' matches '/posts/123' but not '/posts'
    */
-  private matchRoute(path: string): RouteMatch | null {
+  private matchRoute(path: string): Nutin.RouteMatch | null {
     for (const [pattern, routeConfig] of Object.entries(this.routes)) {
       const match = NavigationManager.matchPattern(pattern, path);
       if (match) {
@@ -141,7 +186,9 @@ class Router extends Service<Router> {
   private async handleNotFound(
     normalizedPath: string, 
     currentPath: string, 
-    pushState: boolean
+    mode: HistoryMode,
+    isStale: () => boolean,
+    moveFocus: boolean
   ): Promise<void> {
     const notFoundRoute = this.routes['/404'];
 
@@ -150,21 +197,26 @@ class Router extends Service<Router> {
       return;
     }
 
-    const notFoundConstructor = RouteGuardsManager.getViewConstructor(notFoundRoute);
-    
+    const notFoundFactory = RouteGuardsManager.getViewConstructor(notFoundRoute);
+    const view = await this.resolveView(notFoundFactory, NavigationManager.localizedUrl(normalizedPath), isStale);
+    if (!view) return;
+
     this._currentView = await ViewRenderManager.transitionOutCurrentView(this._currentView);
     this._currentParams = {};
-    this._currentView = ViewRenderManager.renderNewView(notFoundConstructor, {});
+    this._currentView = ViewRenderManager.renderNewView(view, {});
 
     NavigationManager.updateDocumentTitle(this._currentView, '/404');
-    NavigationManager.updateHistory(normalizedPath, currentPath, pushState);
+    NavigationManager.updateHistory(normalizedPath, currentPath, mode);
+    this.afterRender(moveFocus);
   }
 
   private async handleGuards(
     normalizedPath: string,
-    routeConfig: RouteConfig,
+    routeConfig: Nutin.RouteConfig,
     params: Record<string, string>,
-    pushState: boolean
+    currentPath: string,
+    mode: HistoryMode,
+    moveFocus: boolean
   ): Promise<GuardResult | false> {
     const guardResult = await RouteGuardsManager.processRouteGuards(
       routeConfig, 
@@ -174,7 +226,11 @@ class Router extends Service<Router> {
 
     if (!guardResult.allowed) {
       if (guardResult.redirectTo) {
-        await this.navigate(guardResult.redirectTo, pushState);
+        // A guarded URL that's already the current history entry (back/forward,
+        // reload, first load) is replaced by the redirect target, so the address
+        // bar matches what's rendered and Back doesn't land on the guarded URL again.
+        const redirectMode = mode === 'push' && normalizedPath !== currentPath ? 'push' : 'replace';
+        await this.navigateWithMode(guardResult.redirectTo, redirectMode, moveFocus);
       }
       // If no redirect, stay on current route (guard blocked navigation)
       return false;
@@ -184,4 +240,8 @@ class Router extends Service<Router> {
   }
 }
 
-export const AppRouter = (routes: Routes) => Router.getInstance(routes);
+function isPromise<T>(value: T | Promise<T>): value is Promise<T> {
+  return typeof (value as Promise<T> | null)?.then === 'function';
+}
+
+export const AppRouter = (routes: Nutin.Routes) => Router.getInstance(routes);

package/templates/base/tools/builder/builder.config.js.hbs

@@ -19,6 +19,11 @@ function validateConfig(config) {
 
 validateConfig(nutinConfig);
 
+// `build:prod` passes --prod rather than a NODE_ENV=production prefix, which Windows shells
+// don't understand. Every build step is a separate process that only inherits the env (see
+// runScript), so the flag is turned into NODE_ENV here, for them and for this process.
+if (process.argv.includes('--prod')) process.env.NODE_ENV = 'production';
+
 const wellKnownNonSEORoutes = [
   '/400',
   '/401',
@@ -34,6 +39,7 @@ export const builderConfig = {
   ...nutinConfig.builder,
   isProd: process.env.NODE_ENV === 'production',
   i18n: nutinConfig.i18n,
+  markdownSources: nutinConfig.markdownSources,
   tailwind: nutinConfig.tailwind,
   generateSEO: nutinConfig.generateSEOFiles,
   WELL_KNOWN_NON_SEO_ROUTES: wellKnownNonSEORoutes,

package/templates/base/tools/builder/builder.js.hbs

@@ -13,14 +13,25 @@ const scriptsDir = path.join(process.cwd(), 'tools', 'builder', 'core');
 
 print.boldHead(`\nStarting build...`);
 
+// runScript forwards env vars but not argv, so -y/--yes (auto-install an opt-in
+// feature's missing dependencies, see utils/ensure-deps.js) is passed through the env.
+if (process.argv.includes('-y') || process.argv.includes('--yes')) process.env.NUTIN_ASSUME_YES = '1';
+
 runScript(path.join(scriptsDir, 'app', 'copy-static.js'), 'Copying files...');
+{{#if markdown}}
+
+runScript(path.join(scriptsDir, 'markdown', 'generate-markdown-pages.js'), 'Compiling Markdown pages...');
+{{/if}}
 
 runScript(path.join(scriptsDir, 'html-index', 'validate-html.js'), 'Processing index.html...');
 runScript(path.join(scriptsDir, 'app', 'validate-routes.js'), 'Validating app routes...');
 
-runScript(path.join(scriptsDir, 'app', 'compile-ts.js'), 'Compiling TypeScript...');
-
 runScript(path.join(scriptsDir, 'html-templates', 'process-html-templates.js'), 'Processing HTML templates...');
+{{#unless (eq lang "js")}}
+// After the templates are merged, so they're type-checked too.
+runScript(path.join(scriptsDir, 'app', 'compile-ts.js'), 'Compiling TypeScript...');
+{{/unless}}
+runScript(path.join(scriptsDir, 'html-templates', 'minify-templates.js'), 'Minifying HTML templates...');
 
 runScript(path.join(scriptsDir, 'styles', 'sass.js'), 'Compiling styles...');
 if (builderConfig.tailwind) runScript(path.join(scriptsDir, 'styles', 'tailwind.js'), 'Compiling Tailwind CSS...');
@@ -30,12 +41,13 @@ if (builderConfig.i18n) runScript(path.join(scriptsDir, 'i18n', 'build-i18n.js')
 runScript(path.join(scriptsDir, 'prod-bundle', 'esbuild.js'), 'Running esbuild...');
 
 if (builderConfig.isProd) {
-	runScript(path.join(scriptsDir, 'prod-bundle', 'hash-files.js'), 'Hashing files...');
-	runScript(path.join(scriptsDir, 'prod-bundle', 'compress-files.js'), 'Compressing files...');
-	if (builderConfig.generateSEO) runScript(path.join(scriptsDir, 'seo', 'generate-seo-files.js'), 'Generating SEO Files...');
+  runScript(path.join(scriptsDir, 'prod-bundle', 'hash-files.js'), 'Hashing files...');
+  if (builderConfig.generateSEO) runScript(path.join(scriptsDir, 'seo', 'generate-seo-files.js'), 'Generating SEO Files...');
+  // Last, so the prerendered SEO pages, sitemap.xml and robots.txt get compressed too.
+  runScript(path.join(scriptsDir, 'prod-bundle', 'compress-files.js'), 'Compressing files...');
 }
 
-runScript(path.join(scriptsDir, 'finalize-build.js'), 'Finalizing build...')
+runScript(path.join(scriptsDir, 'finalize-build.js'), 'Finalizing build...');
 
 print.boldSuccess(`\nBuild successful!\n`);
 

package/templates/base/tools/builder/core/app/compile-ts.js.hbs

@@ -1,14 +1,89 @@
-import { runCommand, print, errorExit } from "../../../utils/index.js";
+import fs from 'fs';
+import path from 'path';
+import { captureCommand, errorExit } from "../../../utils/index.js";
 import { builderConfig } from '../../builder.config.js';
+import { PATHS } from './paths.js';
+import { readTemplateMap } from '../html-templates/merge-templates.js';
+import { remapTscOutput } from './ts-errors.js';
+import { injectHandlerRefs, stripHandlerRefs } from './handler-refs.js';
+
+// Runs after the .html templates are merged (process-html-templates), on dist-build's copies,
+// so templates are type-checked like the rest of the code. A tsconfig generated there extends
+// the project's: dist-build/src mirrors src, so its include/exclude apply as written.
+const BUILD_TSCONFIG = path.join(PATHS.temp, 'tsconfig.json');
 
 async function compileTS() {
-  // Prod bundles straight from .ts source (see prod-bundle/esbuild.js), so tsc only
-  // needs to type-check there, not emit — emitting would leave a stale, unmerged .js
-  // sibling next to each merged .ts view/component's source.
-  const args = ['--project', 'tsconfig.json'];
+  writeBuildTsconfig();
+
+  // Prod bundles straight from the merged .ts (see prod-bundle/esbuild.js), so tsc only
+  // type-checks there. Dev emits each .js next to its .ts, for the dev bundle and testin-nutin.
+  const args = ['--project', BUILD_TSCONFIG, '--pretty', 'false'];
   if (builderConfig.isProd) args.push('--noEmit');
 
-  await runCommand('tsc', args);
+  // data-event handlers are type-checked through references injected for tsc only, then
+  // removed from the .ts copies the prod bundle is built from (see handler-refs.js).
+  const handlerRefs = await injectHandlerRefs();
+  const { code, output } = await captureCommand('tsc', args);
+  await stripHandlerRefs(handlerRefs);
+  const report = remapTscOutput(output, {
+    cwd: process.cwd(),
+    tempDir: PATHS.temp,
+    templateMap: await readTemplateMap(),
+    handlerRefs,
+  }).trim();
+
+  // On stdout, where tsc itself writes its diagnostics.
+  if (report) console.log(report);
+  if (code !== 0) throw new Error(`tsc exited with code ${code}`);
+}
+
+function writeBuildTsconfig() {
+  const project = readTsconfig(path.resolve('tsconfig.json'));
+  const config = {
+    extends: '../tsconfig.json',
+    compilerOptions: { rootDir: 'src', outDir: 'src' },
+    include: (project.include ?? ['src']).map(toBuildPath),
+    exclude: (project.exclude ?? []).map(toBuildPath),
+  };
+  if (project.files) config.files = project.files.map(toBuildPath);
+  fs.writeFileSync(BUILD_TSCONFIG, JSON.stringify(config, null, 2));
+}
+
+// Paths in src/ are mirrored in dist-build/src; anything else stays where it is, one level up.
+function toBuildPath(entry) {
+  const normalized = entry.replace(/^\.\//, '');
+  return normalized === 'src' || normalized.startsWith('src/') ? normalized : `../${normalized}`;
+}
+
+// tsconfig.json is JSONC: comments and trailing commas are allowed.
+function readTsconfig(file) {
+  const source = fs.readFileSync(file, 'utf-8');
+  let json = '';
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === '"') {
+      const end = endOfString(source, i);
+      json += source.slice(i, end);
+      i = end - 1;
+    } else if (ch === '/' && source[i + 1] === '/') {
+      while (i < source.length && source[i] !== '\n') i++;
+      json += '\n';
+    } else if (ch === '/' && source[i + 1] === '*') {
+      i = source.indexOf('*/', i + 2) + 1;
+      if (i === 0) break;
+    } else {
+      json += ch;
+    }
+  }
+  return JSON.parse(json.replace(/,(\s*[}\]])/g, '$1'));
+}
+
+function endOfString(source, start) {
+  for (let i = start + 1; i < source.length; i++) {
+    if (source[i] === '\\') i++;
+    else if (source[i] === '"') return i + 1;
+  }
+  return source.length;
 }
 
 compileTS().catch((err) => {

package/templates/base/tools/builder/core/app/copy-static.js.hbs

@@ -7,7 +7,13 @@ import { builderConfig } from '../../builder.config.js';
 
 async function copyStatic() {
   const extensions = [...BINARY_EXTENSIONS, '.html'];
-  if (builderConfig.isProd) extensions.push('.ts');
+{{#if (eq lang "js")}}
+  // No compile step emits .js here, so sources are copied in dev and prod alike.
+  extensions.push('.js');
+{{else}}
+  // Templates are merged into these copies, then tsc checks them (and emits .js in dev).
+  extensions.push('.ts');
+{{/if}}
 
   // Every build starts from a clean dist-build: a failed/interrupted prior
   // build never gets renamed away by finalize-build.js, so a stale sibling
@@ -23,6 +29,11 @@ async function copyStatic() {
     const files = await getFilesRecursive(PATHS.source, extension);
 
     for (const file of files) {
+{{#if (eq lang "js")}}
+      // Tests import the build output; they must not end up in it.
+      if (file.endsWith('.test.js')) continue;
+
+{{/if}}
       const relative = path.relative(PATHS.source, file);
       const dest = path.join(PATHS.tempSource, relative);
 

package/templates/base/tools/builder/core/app/handler-refs.js.hbs

@@ -0,0 +1,114 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { getFilesRecursive } from '../../../utils/index.js';
+import { findInlineTemplate } from '../html-templates/template-literal.js';
+import { PATHS } from './paths.js';
+
+// data-event handlers are looked up by name at runtime, so tsc can't see them: a typo binds
+// nothing, and noUnusedLocals flags every private handler. Before tsc, each component/view's
+// handler names are referenced from its own class, on the class's opening line (no line shifts):
+//   class TaskCardComponent extends Component { static { void ((c: InstanceType<typeof TaskCardComponent>) => [c._save]); }
+// A class body may read its own private members, so a missing handler is a tsc error and an
+// existing one counts as used. The arrow is never called; stripHandlerRefs() removes it after tsc.
+
+const DATA_EVENT = /\bdata-event\s*=\s*(["'])(.*?)\1/gs;
+const CLASS_OPEN = /\bclass\s+([A-Za-z_$][\w$]*)\b[^{;]*?\bextends\b[^{;]*\{/g;
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+// Injects the references into every .ts under src/app; returns where they went, by path
+// relative to dist-build (as ts-errors.js receives tsc's paths).
+export async function injectHandlerRefs() {
+  const refs = {};
+  for (const codePath of await getFilesRecursive(PATHS.tempApp, ['.ts'])) {
+    const content = await fs.readFile(codePath, 'utf-8');
+    const result = addHandlerRefs(content);
+    if (!result) continue;
+    await fs.writeFile(codePath, result.content);
+    refs[toPosix(path.relative(PATHS.temp, codePath))] = result.entry;
+  }
+  return refs;
+}
+
+export async function stripHandlerRefs(refs) {
+  for (const [relPath, entry] of Object.entries(refs)) {
+    const codePath = path.join(PATHS.temp, relPath);
+    const content = await fs.readFile(codePath, 'utf-8');
+    await fs.writeFile(codePath, removeHandlerRefs(content, entry));
+  }
+}
+
+// The template's handler names, referenced from the class that follows (or precedes) it.
+// Returns null when there's nothing to check. entry: { className, line, col, segment, handlers }
+// with 1-based positions; each handler's col is where it sits in the injected line, and its
+// templateLine/templateCol where its name is written in the template.
+export function addHandlerRefs(content) {
+  const template = findInlineTemplate(content);
+  if (!template || template.body === null) return null;
+
+  const handlers = collectHandlers(content, template);
+  if (!handlers.length) return null;
+
+  const classOpen = findClassOpen(content, template);
+  if (!classOpen) return null;
+
+  const prefix = ` static { void ((c: InstanceType<typeof ${classOpen.name}>) => [`;
+  let segment = prefix;
+  const { line, col } = positionOf(content, classOpen.end);
+  const located = handlers.map((handler, i) => {
+    if (i > 0) segment += ', ';
+    const handlerCol = col + segment.length + 2; // past "c."
+    segment += `c.${handler.name}`;
+    return { ...handler, col: handlerCol };
+  });
+  segment += ']); }';
+
+  return {
+    content: content.slice(0, classOpen.end) + segment + content.slice(classOpen.end),
+    entry: { className: classOpen.name, line, col, segment, handlers: located },
+  };
+}
+
+export function removeHandlerRefs(content, entry) {
+  const index = content.indexOf(entry.segment);
+  return index === -1 ? content : content.slice(0, index) + content.slice(index + entry.segment.length);
+}
+
+// Each handler named in a static data-event (one built with ${} is skipped), once, at its
+// first occurrence.
+function collectHandlers(content, template) {
+  const handlers = new Map();
+  for (const match of template.body.matchAll(DATA_EVENT)) {
+    const value = match[2];
+    if (value.includes('${')) continue;
+    const name = value.split(':')[1]?.trim();
+    if (!name || !IDENTIFIER.test(name) || handlers.has(name)) continue;
+
+    const valueStart = match.index + match[0].indexOf(match[1]) + 1;
+    const afterColon = value.indexOf(':') + 1;
+    const nameOffset = template.open + valueStart + afterColon + value.slice(afterColon).indexOf(name);
+    const { line, col } = positionOf(content, nameOffset);
+    handlers.set(name, { name, templateLine: line, templateCol: col });
+  }
+  return [...handlers.values()];
+}
+
+// The first `class X ... extends ... {` outside the template: after it first, else before it.
+function findClassOpen(content, template) {
+  const end = template.end ?? template.open;
+  let found = null;
+  for (const match of content.matchAll(CLASS_OPEN)) {
+    const inTemplate = match.index >= template.open && match.index < end;
+    if (inTemplate) continue;
+    const candidate = { name: match[1], end: match.index + match[0].length };
+    if (match.index >= end) return candidate;
+    found ??= candidate;
+  }
+  return found;
+}
+
+function positionOf(content, offset) {
+  const before = content.slice(0, offset);
+  return { line: before.split('\n').length, col: offset - before.lastIndexOf('\n') };
+}
+
+const toPosix = (p) => p.split(path.sep).join('/');

package/templates/base/tools/builder/core/app/handler-refs.test.js.hbs

@@ -0,0 +1,70 @@
+import { addHandlerRefs, removeHandlerRefs } from './handler-refs.js';
+
+const VIEW = [
+  "import { View, html } from '../../../core/index.js';",
+  '',
+  'const template = html`<div>',
+  '  <button data-event="click:_save:@value">Save</button>',
+  '  <a data-event=\'click:_open\' data-event-extra="x">Open</a>',
+  '  <button data-event="click:_save">Again</button>',
+  '</div>`;',
+  '',
+  'export class TaskView extends View {',
+  '  private _save(): void {}',
+  '  private _open(): void {}',
+  '}',
+].join('\n');
+
+describe('handler-refs', () => {
+  it('references each data-event handler once, from the class\'s opening line', () => {
+    const { content, entry } = addHandlerRefs(VIEW);
+    const classLine = content.split('\n')[8];
+
+    expect(classLine).toBe(
+      'export class TaskView extends View { static { void ((c: InstanceType<typeof TaskView>) => [c._save, c._open]); }'
+    );
+    expect(content.split('\n').length).toBe(VIEW.split('\n').length);
+    expect(entry.className).toBe('TaskView');
+    expect(entry.line).toBe(9);
+    expect(entry.handlers.map((h) => h.name)).toEqual(['_save', '_open']);
+  });
+
+  it('records where each handler is named in the template and in the injected line', () => {
+    const { content, entry } = addHandlerRefs(VIEW);
+    const [save, open] = entry.handlers;
+
+    expect(save.templateLine).toBe(4);
+    expect(VIEW.split('\n')[3].slice(save.templateCol - 1).startsWith('_save:@value')).toBeTruthy();
+    expect(open.templateLine).toBe(5);
+    expect(VIEW.split('\n')[4].slice(open.templateCol - 1).startsWith('_open\'')).toBeTruthy();
+
+    const classLine = content.split('\n')[8];
+    expect(classLine.slice(save.col - 1).startsWith('_save,')).toBeTruthy();
+    expect(classLine.slice(open.col - 1).startsWith('_open]')).toBeTruthy();
+  });
+
+  it('skips data-event values built with ${}, and files without handlers', () => {
+    const dynamic = VIEW
+      .replace('click:_save:@value', 'click:${handler}')
+      .replace("'click:_open'", "'click:${other}'")
+      .replace('"click:_save"', '"${evt}:_save"');
+    expect(addHandlerRefs(dynamic)).toBe(null);
+    expect(addHandlerRefs("export class A extends View {}")).toBe(null);
+  });
+
+  it('finds the class after the template, even when the markup mentions a class', () => {
+    const source = [
+      'const templateFn = (t: T) => html`<p class="x">the class Foo extends Bar { }</p><i data-event="click:_go"></i>`;',
+      'export class CardComponent<T = string> extends Component<T> {',
+      '}',
+    ].join('\n');
+    const { content, entry } = addHandlerRefs(source);
+    expect(entry.className).toBe('CardComponent');
+    expect(content.split('\n')[1]).toContain('extends Component<T> { static { void ((c: InstanceType<typeof CardComponent>) => [c._go]); }');
+  });
+
+  it('removes exactly the injected references', () => {
+    const { content, entry } = addHandlerRefs(VIEW);
+    expect(removeHandlerRefs(content, entry)).toBe(VIEW);
+  });
+});