@webjsdev/core 0.7.21 → 0.7.22

package/index-browser.js

@@ -24,7 +24,7 @@
 
 export { html, isTemplate, MARKER } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
-export { WebComponent } from './src/component.js';
+export { WebComponent, prop } from './src/component.js';
 export { register, lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
 export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';

package/index.js

@@ -8,7 +8,7 @@
 
 export { html, isTemplate, MARKER } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
-export { WebComponent } from './src/component.js';
+export { WebComponent, prop } from './src/component.js';
 export { register, lookup, lookupModuleUrl, isLazy, allTags, primeModuleUrl, tagOf } from './src/registry.js';
 export { renderToString, renderToStream } from './src/render-server.js';
 export { render } from './src/render-client.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.21",
+  "version": "0.7.22",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/component.d.ts

@@ -22,7 +22,7 @@ export type PropertyConstructor<T = unknown> =
   | (new (...args: any[]) => T)
   | ((v: any) => T);
 
-/** Runtime-level property declaration: matches `static properties = { … }`. */
+/** Runtime-level property declaration: one entry in `WebComponent({ … })`. */
 export interface PropertyDeclaration<T = unknown> {
   /** Constructor used for string → value coercion when the attribute changes. */
   type?: PropertyConstructor<T>;
@@ -52,27 +52,30 @@ export interface ReactiveController {
 /**
  * Base class for interactive web components.
  *
- * Declare runtime behaviour via `static properties = { … }` and type
- * each field with a sibling `declare foo: Foo`:
+ * Declare reactive properties via the `extends WebComponent({ … })`
+ * factory. It installs the reactive accessor AND types each field for
+ * you (no `declare`, no `static properties`):
  *
- *     class StudentCard extends WebComponent {
- *       static properties = { student: { type: Object } };
- *       declare student: Student;
+ *     class StudentCard extends WebComponent({ student: prop<Student>(Object) }) {
  *       render() { return html`<p>${this.student.name}</p>`; }
  *     }
  *     StudentCard.register('student-card');
  *
- * The `declare` field has no runtime cost: it tells TypeScript the
- * field's type without emitting a class-field initializer that would
- * clobber the reactive accessor the framework installs via
- * `Object.defineProperty` in the constructor.
+ * A bare constructor type covers the common case (`WebComponent({ count:
+ * Number })` gives `this.count: number`); use the `prop()` helper for
+ * options (`prop(Number, { reflect: true })`) or to narrow the type
+ * (`prop<Student>(Object)`). Set defaults via the `default` option or in
+ * the constructor, never a class-field initializer (it runs after super()
+ * and clobbers the reactive accessor). A hand-written `static properties`
+ * in a class body is no longer supported and throws at construction.
  *
  * See the Editor Setup doc for tooling that gives attribute/tag
  * intelligence inside `html\`…\`` templates.
  */
-export abstract class WebComponent extends HTMLElement {
+abstract class WebComponentBase extends HTMLElement {
   static shadow: boolean;
   static hydrate: 'visible' | undefined;
+  /** @internal Populated by the `WebComponent({ … })` factory, not by hand. */
   static properties: Record<string, PropertyDeclaration>;
   static styles: CSSResult | CSSResult[] | null;
   static lazy?: boolean;
@@ -84,8 +87,8 @@ export abstract class WebComponent extends HTMLElement {
    * Schedule a re-render. Optionally record a property change so lifecycle
    * hooks can branch on what changed via `changedProperties`.
    *
-   * For instance-local state, prefer a reactive property (`static
-   * properties = { foo: { state: true } }`) or a signal from
+   * For instance-local state, prefer a reactive property (`WebComponent({
+   * foo: prop({ state: true }) })`) or a signal from
    * `@webjsdev/core`'s `signal()`. The framework's built-in
    * SignalWatcher wires every signal read in `render()` to a re-render
    * automatically; explicit `requestUpdate()` is rarely needed.
@@ -129,3 +132,58 @@ export abstract class WebComponent extends HTMLElement {
   disconnectedCallback(): void;
   attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
+
+export type WebComponent = WebComponentBase;
+
+export type Infer<C> =
+  C extends BooleanConstructor ? boolean :
+  C extends NumberConstructor ? number :
+  C extends StringConstructor ? string :
+  C extends new (...a: any[]) => infer T ? T :
+  C extends (v: any) => infer T ? T : unknown;
+
+export type InferProps<S> = {
+  [K in keyof S]: S[K] extends PropertyDeclaration<infer T> ? T : Infer<S[K]>
+};
+
+export interface WebComponentConstructor {
+  new (): WebComponentBase;
+  prototype: WebComponentBase;
+
+  shadow: boolean;
+  hydrate: 'visible' | undefined;
+  properties: Record<string, PropertyDeclaration>;
+  styles: CSSResult | CSSResult[] | null;
+  lazy?: boolean;
+  register(tag: string): void;
+  readonly observedAttributes: string[];
+
+  <S extends Record<string, any>>(shape: S): {
+    new (): WebComponentBase & InferProps<S>;
+    prototype: WebComponentBase & InferProps<S>;
+
+    shadow: boolean;
+    hydrate: 'visible' | undefined;
+    properties: Record<string, PropertyDeclaration>;
+    styles: CSSResult | CSSResult[] | null;
+    lazy?: boolean;
+    register(tag: string): void;
+    readonly observedAttributes: string[];
+  };
+}
+
+export declare const WebComponent: WebComponentConstructor;
+
+export declare function prop<C extends PropertyConstructor<any>>(
+  type: C,
+  opts?: Omit<PropertyDeclaration<Infer<C>>, 'type'>
+): PropertyDeclaration<Infer<C>>;
+
+export declare function prop<T>(
+  type: PropertyConstructor<any>,
+  opts?: Omit<PropertyDeclaration<T>, 'type'>
+): PropertyDeclaration<T>;
+
+export declare function prop<T = string>(
+  opts?: PropertyDeclaration<T>
+): PropertyDeclaration<T>;

package/src/component.js

@@ -400,7 +400,18 @@ for (const idl of ARIA_IDL_PROPS) {
 // Base class choice: real HTMLElement on the browser, the shim on the server.
 const Base = isBrowser ? HTMLElement : /** @type {any} */ (ServerElement);
 
-export class WebComponent extends Base {
+/**
+ * Marker stamped on the anonymous subclass the `WebComponent({...})` factory
+ * produces. It lets `_assertFactoryProperties` tell the framework's own
+ * factory-generated `static properties` (allowed) apart from a `static
+ * properties` a user wrote by hand in a class body (no longer allowed).
+ */
+const FACTORY_PROPS = Symbol('webjs.factoryProps');
+
+// Per-class memo so the constructor-time enforcement walk runs once per class.
+const _propsChecked = new WeakSet();
+
+class WebComponentBase extends Base {
   /** Whether to use shadow DOM. Default: false (light DOM). @type {boolean} */
   static shadow = false;
 
@@ -531,10 +542,45 @@ export class WebComponent extends Base {
      */
     this._isUpdating = false;
 
+    // Enforce the declare-free factory DX: a hand-written `static properties`
+    // in a class body is a hard error (use `extends WebComponent({ … })`).
+    this._assertFactoryProperties();
+
     // Install reactive property accessors for `static properties` declarations.
     this._initializeProperties();
   }
 
+  /**
+   * Throw if a class in this instance's constructor chain declares its own
+   * `static properties`. Reactive properties must be declared via the
+   * `extends WebComponent({ … })` factory, which stamps {@link FACTORY_PROPS}
+   * on the subclass it generates; a `static properties` written by hand in a
+   * class body carries no such marker and is rejected here (issue #598).
+   *
+   * The walk stops at {@link WebComponentBase} (whose `static properties = {}`
+   * default is internal) and is memoized per class so it runs once.
+   * @private
+   */
+  _assertFactoryProperties() {
+    const Ctor = /** @type {any} */ (this.constructor);
+    if (_propsChecked.has(Ctor)) return;
+    let C = Ctor;
+    while (C && C !== WebComponentBase) {
+      if (Object.hasOwn(C, 'properties') && !Object.hasOwn(C, FACTORY_PROPS)) {
+        const name = C.name || 'a component';
+        throw new Error(
+          `${name}: \`static properties\` is no longer supported. Declare reactive ` +
+            `properties via the factory instead: \`class ${name} extends WebComponent({ ` +
+            `count: Number })\`. Use the \`prop()\` helper for options ` +
+            `(\`prop(Number, { reflect: true })\`) and set defaults via the \`default\` ` +
+            `option or in the constructor. See https://docs.webjs.com/docs/components.`,
+        );
+      }
+      C = Object.getPrototypeOf(C);
+    }
+    _propsChecked.add(Ctor);
+  }
+
   /**
    * For every key in `static properties`, create a getter/setter pair on
    * the instance that coerces values, runs `hasChanged`, schedules updates,
@@ -893,8 +939,13 @@ export class WebComponent extends Base {
 
     const Ctor = /** @type any */ (this.constructor);
     const propName = camelCase(name);
-    const def = Ctor.properties && (Ctor.properties[propName] || Ctor.properties[name]);
-    if (!def) return;
+    const raw = Ctor.properties && (Ctor.properties[propName] || Ctor.properties[name]);
+    if (!raw) return;
+    // A declaration is either a full descriptor (`{ type: Number, … }`) or the
+    // bare-constructor shorthand the factory accepts (`count: Number`), in which
+    // case the value IS the type. Normalise so type-based coercion fires either
+    // way (matches `_initializeProperties`).
+    const def = typeof raw === 'object' ? raw : { type: raw };
 
     let v;
     if (def.converter && def.converter.fromAttribute) {
@@ -1553,3 +1604,41 @@ function hyphenate(s) {
 function camelCase(s) {
   return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
+
+/**
+ * Dual-role WebComponent class and factory.
+ * Can be extended directly: `class X extends WebComponent`
+ * Or called as a class factory: `class X extends WebComponent({ count: Number })`
+ *
+ * @param {Record<string, any>} [properties]
+ * @returns {any}
+ */
+export function WebComponent(properties) {
+  if (new.target) {
+    return Reflect.construct(WebComponentBase, arguments, new.target);
+  } else {
+    return class extends WebComponentBase {
+      static properties = properties;
+      static [FACTORY_PROPS] = true;
+    };
+  }
+}
+
+// Ensure static inheritance and instanceof checks work
+Object.setPrototypeOf(WebComponent, WebComponentBase);
+WebComponent.prototype = WebComponentBase.prototype;
+
+/**
+ * Helper to define properties with custom options.
+ *
+ * @param {any} [type]
+ * @param {any} [opts]
+ * @returns {any}
+ */
+export function prop(type, opts = {}) {
+  if (type && typeof type === 'object' && !('call' in type)) {
+    opts = type;
+    type = undefined;
+  }
+  return { ...(type ? { type } : {}), ...opts };
+}

package/src/render-server.js

@@ -1052,12 +1052,16 @@ function appendReflectedAttrs(opening, instance, presentAttrNames) {
 function applyAttrsToInstance(instance, attrs, Cls) {
   const props = Cls.properties || {};
   for (const [key, raw] of Object.entries(attrs)) {
-    const def = props[key] || props[camelCase(key)];
+    const rawDef = props[key] || props[camelCase(key)];
     const propName = props[key] ? key : camelCase(key);
-    if (!def) {
+    if (!rawDef) {
       instance[propName] = raw;
       continue;
     }
+    // The factory accepts a bare constructor shorthand (`{ expanded: Boolean }`)
+    // alongside the long form (`{ expanded: { type: Boolean } }`); normalize so
+    // the type-based coercion below sees a `{ type }` object either way.
+    const def = typeof rawDef === 'object' ? rawDef : { type: rawDef };
     if (def.type === Number) instance[propName] = Number(raw);
     else if (def.type === Boolean) instance[propName] = raw !== 'false';
     else if (def.type === Object || def.type === Array) {

package/src/router-client.js

@@ -220,6 +220,7 @@ export function disableClientRouter() {
   document.removeEventListener('pointerout', onPrefetchOut, true);
   document.removeEventListener('webjs:navigate', refreshPrefetchObservers);
   clearPrefetchHover();
+  clearPrefetchViewTimers();
   if (prefetchViewObserver) { prefetchViewObserver.disconnect(); prefetchViewObserver = null; }
   if (typeof history !== 'undefined' && prevScrollRestoration !== null) {
     history.scrollRestoration = prevScrollRestoration;
@@ -960,12 +961,16 @@ function buildHaveHeader() {
  * warms a dedicated cache speculatively so the click reads it instantly.
  *
  * Strategy per anchor via a `data-prefetch` attribute (valid-HTML data-*,
- * like SvelteKit / Astro), defaulting to `intent` so the common case is
- * fast without per-link opt-in, the way Next / Nuxt / SvelteKit ship
- * auto-prefetch. Value vocabulary borrows Next's true/false/auto aliases:
- *   - intent    (default)    : hover / focus / touch, after a short dwell
+ * like SvelteKit / Astro). The default is DEVICE-ADAPTIVE so the common case
+ * is fast on every device without per-link opt-in: `intent` on a hover-capable
+ * pointer (a real head-start before the click), `viewport` on touch (no hover
+ * exists, and `touchstart` fires too close to the tap to front-run it). Value
+ * vocabulary borrows Next's true/false/auto aliases:
+ *   - absent (default)       : intent on pointer, viewport on touch (adaptive)
+ *   - intent                 : hover / focus / touch, after a short dwell
  *   - true / render          : eager, as soon as a document scan sees it
- *   - auto / viewport        : on viewport entry (IntersectionObserver, 0.5)
+ *   - auto / viewport        : on viewport entry (IntersectionObserver, 0.5),
+ *                              after a dwell so a fast scroll-through skips it
  *   - false / none           : never (also data-no-prefetch / rel="external")
  *
  * Why a separate cache, not snapshotCache: snapshotCache is keyed to the
@@ -976,7 +981,10 @@ function buildHaveHeader() {
  * prefetchTake() before falling back to the network.
  *
  * Only same-origin in-app links are prefetched (the same eligibility as
- * a click), and never under Save-Data / prefers-reduced-data. There is no
+ * a click), and never under Save-Data / prefers-reduced-data / a 2g link,
+ * never past a small concurrency cap, and never twice (deduped + cached). The
+ * viewport path additionally waits a dwell and cancels on scroll-out, so a
+ * fast scroll through a long list does not flood the network tab. There is no
  * logout-style heuristic: prefetch issues a real GET, so as everywhere in
  * the ecosystem (Next / Nuxt / Remix), a non-idempotent action must be a
  * POST or a `<form>`, and `data-no-prefetch` / `rel="external"` opt out.
@@ -996,6 +1004,13 @@ const PREFETCH_CONCURRENCY = 3;
 const PREFETCH_QUEUE_CAP = 24;
 /** Hover dwell before a prefetch fires (ms): filter drive-by pointer moves. Matches Remix's intent timeout. */
 const PREFETCH_HOVER_DELAY = 100;
+/**
+ * Viewport dwell before a prefetch fires (ms): a link must SETTLE on-screen,
+ * not merely flash past during a scroll. A fast scroll-through clears the
+ * timer on exit, so flicked-past links never fetch. Astro uses 300ms for the
+ * same purpose; we sit a touch lower so a deliberate stop still feels instant.
+ */
+const PREFETCH_VIEWPORT_DELAY = 250;
 
 /** @typedef {{ html: string, build: string | null, finalUrl: string, at: number }} PrefetchEntry */
 /** @type {Map<string, PrefetchEntry>} */
@@ -1011,18 +1026,28 @@ let prefetchHoverTimer = null;
 let prefetchHoverAnchor = null;
 /** IntersectionObserver for data-prefetch="viewport" anchors, or null. */
 let prefetchViewObserver = null;
+/** Per-anchor viewport-dwell timers, so a scroll-out can cancel before firing. */
+let prefetchViewTimers = new WeakMap();
+/** Live viewport-dwell timer ids, for bulk teardown on disable. */
+const prefetchViewPending = new Set();
 
 /**
- * True when the user or platform has asked us to conserve data. Both the
- * Save-Data client hint and the prefers-reduced-data media query disable
- * speculative fetching. Guarded for non-browser / partial DOM.
+ * True when the user or platform has asked us to conserve data, OR the
+ * connection is too slow to spend bytes speculatively. The Save-Data client
+ * hint, the prefers-reduced-data media query, and a 2g `effectiveType` all
+ * disable speculative fetching, the same gate Astro / Nuxt apply. Guarded for
+ * non-browser / partial DOM.
  *
  * @returns {boolean}
  */
 function prefetchSaysSaveData() {
   try {
     const c = typeof navigator !== 'undefined' ? /** @type any */ (navigator).connection : null;
-    if (c && c.saveData === true) return true;
+    if (c) {
+      if (c.saveData === true) return true;
+      // effectiveType is 'slow-2g' | '2g' | '3g' | '4g'; skip the 2g tiers.
+      if (typeof c.effectiveType === 'string' && /2g$/.test(c.effectiveType)) return true;
+    }
     if (typeof matchMedia === 'function' && matchMedia('(prefers-reduced-data: reduce)').matches) {
       return true;
     }
@@ -1030,6 +1055,27 @@ function prefetchSaysSaveData() {
   return false;
 }
 
+/**
+ * Whether the device drives a hover-capable fine pointer (a mouse or
+ * trackpad), as opposed to touch. This picks the ADAPTIVE prefetch default:
+ * `intent` (hover / focus) on a pointer device, `viewport` on touch, since a
+ * touch device has no hover and `touchstart` fires too close to the tap to
+ * front-run it. Detected with `matchMedia('(hover: hover) and (pointer: fine)')`
+ * rather than a user-agent sniff. When `matchMedia` is unavailable we assume a
+ * pointer (the historical default), so a non-browser / partial-DOM environment
+ * keeps the `intent` behaviour and never silently switches to viewport.
+ *
+ * @returns {boolean}
+ */
+function prefetchHasHoverPointer() {
+  try {
+    if (typeof matchMedia === 'function') {
+      return matchMedia('(hover: hover) and (pointer: fine)').matches;
+    }
+  } catch { /* ignore */ }
+  return true;
+}
+
 /**
  * Lowercased whitespace-separated rel tokens of an anchor.
  * @param {Element} anchor
@@ -1091,12 +1137,21 @@ function prefetchSuppressed(anchor) {
  * absent or unrecognised.
  *
  * Value mapping (case-insensitive):
- *   - absent / unknown   : `intent`  (the default)
+ *   - absent / unknown   : the DEVICE-ADAPTIVE default (intent on a pointer,
+ *                          viewport on touch); an explicit value always wins
  *   - `intent`           : hover / focus / touch, after a short dwell
  *   - `true` / `render`  : eager, as soon as a document scan sees the link
- *   - `auto` / `viewport`: on viewport entry (IntersectionObserver)
+ *   - `auto` / `viewport`: on viewport entry (IntersectionObserver), after a dwell
  *   - `false` / `none`   : never (also via data-no-prefetch / rel="external")
  *
+ * The default is adaptive (not a single `intent`) because `intent` does not
+ * help on mobile: a touch device has no hover, and `touchstart` fires at tap
+ * time, so the prefetch races the navigation. On touch we default to
+ * `viewport` (warm links as they settle on-screen) and keep `touchstart` as an
+ * extra warm for the tapped link; on a pointer device `intent` stays the
+ * default (precise, cheap, a real head-start before the click). A per-link
+ * `data-prefetch` always overrides the adaptive default.
+ *
  * Returns `none` for suppressed anchors so callers have a single check.
  *
  * @param {Element} anchor
@@ -1118,8 +1173,8 @@ function prefetchMode(anchor) {
     case 'intent':
       return 'intent';
     default:
-      // Unset or unrecognised value: the fast default.
-      return 'intent';
+      // Unset or unrecognised value: the device-adaptive default.
+      return prefetchHasHoverPointer() ? 'intent' : 'viewport';
   }
 }
 
@@ -1134,6 +1189,9 @@ function prefetchMode(anchor) {
  * @param {string} href
  */
 function prefetch(href) {
+  // Never speculate once the router is torn down: a leftover hover / queue /
+  // dwell timer that fires after disableClientRouter must not issue a fetch.
+  if (!enabled) return;
   if (typeof fetch !== 'function') return;
   if (prefetchSaysSaveData()) return;
   const key = cacheKey(href);
@@ -1245,12 +1303,19 @@ function onPrefetchIntent(e) {
   if (!enabled) return;
   const anchor = closestAnchor(/** @type any */ (e.target));
   if (!anchor) return;
-  // Only `intent` links prefetch on hover/focus/touch. `render` and
-  // `viewport` links are handled by the document scan / observer, and
-  // `none` is suppressed.
-  if (prefetchMode(anchor) !== 'intent') return;
+  const mode = prefetchMode(anchor);
+  // `none` is suppressed; `render` already prefetched on the document scan.
+  if (mode === 'none' || mode === 'render') return;
   const href = eligibleAnchorHref(anchor);
   if (!href) return;
+  // touchstart IS the tap: warm the tapped link immediately, for both intent
+  // and viewport modes (a single request for a link about to be navigated, the
+  // small mobile win the viewport default cannot give for the link just tapped).
+  // No dwell, since the tap is the intent.
+  if (e.type === 'touchstart') { prefetch(href); return; }
+  // hover / focus only warm `intent` links; `viewport` links are the
+  // observer's job (warmed on a dwell, not on a stray hover).
+  if (mode !== 'intent') return;
   // pointerover/focusin bubble, so re-entering a child of the same anchor
   // would re-arm; collapse to one timer per anchor.
   if (prefetchHoverAnchor === anchor && prefetchHoverTimer) return;
@@ -1274,6 +1339,13 @@ function clearPrefetchHover() {
   prefetchHoverAnchor = null;
 }
 
+/** Cancel every pending viewport-dwell timer and reset the per-anchor map. */
+function clearPrefetchViewTimers() {
+  for (const timer of prefetchViewPending) clearTimeout(timer);
+  prefetchViewPending.clear();
+  prefetchViewTimers = new WeakMap();
+}
+
 /**
  * Nearest enclosing <a>, crossing shadow boundaries, from an event
  * target. composedPath is click-only, so walk getRootNode().host here.
@@ -1314,15 +1386,40 @@ function refreshPrefetchObservers() {
     if (!prefetchViewObserver) {
       prefetchViewObserver = new IntersectionObserver((entries) => {
         for (const entry of entries) {
-          if (!entry.isIntersecting) continue;
           const anchor = /** @type {Element} */ (entry.target);
-          prefetchViewObserver.unobserve(anchor);
-          const href = eligibleAnchorHref(anchor);
-          if (href && prefetchMode(anchor) === 'viewport') prefetch(href);
+          if (entry.isIntersecting) {
+            // Arm a dwell timer; the link must STAY on-screen to warm. One
+            // timer per anchor, so re-entry while pending does not stack.
+            if (prefetchViewTimers.has(anchor)) continue;
+            const timer = setTimeout(() => {
+              prefetchViewPending.delete(timer);
+              prefetchViewTimers.delete(anchor);
+              prefetchViewObserver.unobserve(anchor);
+              const href = eligibleAnchorHref(anchor);
+              if (href && prefetchMode(anchor) === 'viewport') prefetch(href);
+            }, PREFETCH_VIEWPORT_DELAY);
+            prefetchViewTimers.set(anchor, timer);
+            prefetchViewPending.add(timer);
+          } else {
+            // Scrolled out before the dwell elapsed: cancel, so a fast
+            // scroll-through never spends a request.
+            const timer = prefetchViewTimers.get(anchor);
+            if (timer) {
+              clearTimeout(timer);
+              prefetchViewPending.delete(timer);
+              prefetchViewTimers.delete(anchor);
+            }
+          }
         }
       }, { threshold: 0.5 });
     } else {
+      // Re-scan: drop the old observation set AND cancel any pending dwell
+      // timers, so a timer armed for an anchor the soft-nav swap removed cannot
+      // fire a prefetch for a stale URL (its exit callback never comes once it
+      // is gone). Anchors still on-screen re-arm when observe() below redelivers
+      // their current intersection state.
       prefetchViewObserver.disconnect();
+      clearPrefetchViewTimers();
     }
   }
   for (const anchor of document.querySelectorAll('a[href]')) {
@@ -3070,6 +3167,7 @@ export {
   regraftPermanentInSlice as _regraftPermanentInSlice,
   prefetchSuppressed as _prefetchSuppressed,
   prefetchMode as _prefetchMode,
+  prefetchHasHoverPointer as _prefetchHasHoverPointer,
   prefetch as _prefetch,
   prefetchTake as _prefetchTake,
   prefetchSaysSaveData as _prefetchSaysSaveData,
@@ -3090,6 +3188,7 @@ export function _resetPrefetch() {
   prefetchQueue.length = 0;
   prefetchQueued.clear();
   clearPrefetchHover();
+  clearPrefetchViewTimers();
 }
 
 /** Test-only: read the monotonic navigation-token counter. */

package/src/task.js

@@ -29,9 +29,7 @@
  * import { WebComponent, html } from '@webjsdev/core';
  * import { Task } from '@webjsdev/core/task';
  *
- * class UserSearch extends WebComponent {
- *   static properties = { query: { type: String } };
- *
+ * class UserSearch extends WebComponent({ query: String }) {
  *   _search = new Task(this, {
  *     task: async (query, { signal }) => {
  *       const res = await fetch(`/api/users?q=${query}`, { signal });

package/src/webjs-config.d.ts

@@ -80,6 +80,32 @@ export interface WebjsRedirectRule {
 /** The trailing-slash canonicalization policy in `webjs.trailingSlash`. */
 export type WebjsTrailingSlash = 'never' | 'always' | 'ignore';
 
+/** Dev task orchestration in `webjs.dev` (#550). Read by the CLI, not the server. */
+export interface WebjsDevTasks {
+  /**
+   * One-shot commands run sequentially to completion BEFORE the dev server
+   * boots (the old `predev` hook: `webjs db migrate`, a registry copy). A
+   * non-zero exit aborts the boot.
+   */
+  before?: string[];
+  /**
+   * Long-lived commands run as child processes ALONGSIDE the dev server (the
+   * old `concurrently` watchers: the Tailwind CLI `--watch`). Spawned once in
+   * the parent and torn down on exit, so a watcher cannot leak past the server.
+   */
+  parallel?: string[];
+}
+
+/** Start task orchestration in `webjs.start` (#550). Read by the CLI, not the server. */
+export interface WebjsStartTasks {
+  /**
+   * One-shot commands run sequentially to completion BEFORE the prod server
+   * boots (the old `prestart` hook: `webjs db migrate`). A non-zero exit
+   * aborts the boot.
+   */
+  before?: string[];
+}
+
 /** The object form of `webjs.csp` (the non-boolean shape). */
 export interface WebjsCspConfig {
   /**
@@ -118,6 +144,14 @@ export interface WebjsConfig {
    */
   seed?: boolean;
 
+  /**
+   * Dev/start task orchestration (#550). `webjs dev` / `webjs start` run these
+   * so a bare CLI invocation matches `npm run dev` / `start`. Read by the CLI
+   * (`packages/cli/lib/app-tasks.js`), NOT the server readers.
+   */
+  dev?: WebjsDevTasks;
+  start?: WebjsStartTasks;
+
   /** Per-path response-header rules, shaped like Next's. */
   headers?: WebjsHeaderRule[];