feat: usePreloaderInfo

packages/docs/src/routes/api/qwik-city/api.json

@@ -898,6 +898,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/runtime/src/use-functions.ts",
       "mdFile": "qwik-city.usenavigate.md"
     },
+    {
+      "name": "usePreloaderInfo",
+      "id": "usepreloaderinfo",
+      "hierarchy": [
+        {
+          "name": "usePreloaderInfo",
+          "id": "usepreloaderinfo"
+        }
+      ],
+      "kind": "Function",
+      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\nReactive hook exposing the current number of high-priority user-event preloads. Updates whenever the preloader recalculates the queue on the client.\n\n\n```typescript\nusePreloaderInfo: () => {\n    userEventPreloadsCount: ReadonlySignal<number>;\n    activePreloadsLength: ReadonlySignal;\n}\n```\n**Returns:**\n\n{ userEventPreloadsCount: ReadonlySignal&lt;number&gt;; activePreloadsLength: ReadonlySignal; }",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/runtime/src/use-functions.ts",
+      "mdFile": "qwik-city.usepreloaderinfo.md"
+    },
     {
       "name": "usePreventNavigate$",
       "id": "usepreventnavigate_",

packages/docs/src/routes/api/qwik-city/index.mdx

@@ -2435,6 +2435,25 @@ useNavigate: () => RouteNavigate;
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/runtime/src/use-functions.ts)
 
+## usePreloaderInfo
+
+> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+
+Reactive hook exposing the current number of high-priority user-event preloads. Updates whenever the preloader recalculates the queue on the client.
+
+```typescript
+usePreloaderInfo: () => {
+  userEventPreloadsCount: ReadonlySignal<number>;
+  activePreloadsLength: ReadonlySignal;
+};
+```
+
+**Returns:**
+
+\{ userEventPreloadsCount: ReadonlySignal&lt;number&gt;; activePreloadsLength: ReadonlySignal; }
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/runtime/src/use-functions.ts)
+
 ## usePreventNavigate$
 
 Prevent navigation attempts. This hook registers a callback that will be called before SPA or browser navigation.

packages/docs/src/routes/api/qwik-optimizer/api.json

@@ -147,7 +147,7 @@
         }
       ],
       "kind": "Enum",
-      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\nUse `__EXPERIMENTAL__.x` to check if feature `x` is enabled. It will be replaced with `true` or `false` via an exact string replacement.\n\nAdd experimental features to this enum definition.\n\n\n```typescript\nexport declare enum ExperimentalFeatures \n```\n\n\n<table><thead><tr><th>\n\nMember\n\n\n</th><th>\n\nValue\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nenableRequestRewrite\n\n\n</td><td>\n\n`\"enableRequestRewrite\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable request.rewrite()\n\n\n</td></tr>\n<tr><td>\n\nnoSPA\n\n\n</td><td>\n\n`\"noSPA\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Disable SPA navigation handler in Qwik City\n\n\n</td></tr>\n<tr><td>\n\npreventNavigate\n\n\n</td><td>\n\n`\"preventNavigate\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the usePreventNavigate hook\n\n\n</td></tr>\n<tr><td>\n\nvalibot\n\n\n</td><td>\n\n`\"valibot\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the Valibot form validation\n\n\n</td></tr>\n</tbody></table>",
+      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\nUse `__EXPERIMENTAL__.x` to check if feature `x` is enabled. It will be replaced with `true` or `false` via an exact string replacement.\n\nAdd experimental features to this enum definition.\n\n\n```typescript\nexport declare enum ExperimentalFeatures \n```\n\n\n<table><thead><tr><th>\n\nMember\n\n\n</th><th>\n\nValue\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nenableRequestRewrite\n\n\n</td><td>\n\n`\"enableRequestRewrite\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable request.rewrite()\n\n\n</td></tr>\n<tr><td>\n\nnoSPA\n\n\n</td><td>\n\n`\"noSPA\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Disable SPA navigation handler in Qwik City\n\n\n</td></tr>\n<tr><td>\n\npreventNavigate\n\n\n</td><td>\n\n`\"preventNavigate\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the usePreventNavigate hook\n\n\n</td></tr>\n<tr><td>\n\nusePreloaderInfo\n\n\n</td><td>\n\n`\"usePreloaderInfo\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the usePreloaderInfo hook\n\n\n</td></tr>\n<tr><td>\n\nvalibot\n\n\n</td><td>\n\n`\"valibot\"`\n\n\n</td><td>\n\n**_(ALPHA)_** Enable the Valibot form validation\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/optimizer/src/plugins/plugin.ts",
       "mdFile": "qwik.experimentalfeatures.md"
     },
@@ -949,6 +949,23 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/optimizer/src/types.ts",
       "mdFile": "qwik.transpileoption.md"
     },
+    {
+      "name": "usePreloaderInfo",
+      "id": "experimentalfeatures-usepreloaderinfo",
+      "hierarchy": [
+        {
+          "name": "ExperimentalFeatures",
+          "id": "experimentalfeatures-usepreloaderinfo"
+        },
+        {
+          "name": "usePreloaderInfo",
+          "id": "experimentalfeatures-usepreloaderinfo"
+        }
+      ],
+      "kind": "EnumMember",
+      "content": "",
+      "mdFile": "qwik.experimentalfeatures.usepreloaderinfo.md"
+    },
     {
       "name": "valibot",
       "id": "experimentalfeatures-valibot",

packages/docs/src/routes/api/qwik-optimizer/index.mdx

@@ -413,6 +413,19 @@ preventNavigate
 </td></tr>
 <tr><td>
 
+usePreloaderInfo
+
+</td><td>
+
+`"usePreloaderInfo"`
+
+</td><td>
+
+**_(ALPHA)_** Enable the usePreloaderInfo hook
+
+</td></tr>
+<tr><td>
+
 valibot
 
 </td><td>
@@ -3844,6 +3857,8 @@ export type TranspileOption = boolean | undefined | null;
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/optimizer/src/types.ts)
 
+## usePreloaderInfo
+
 ## valibot
 
 ## versions

packages/docs/src/routes/api/qwik-preloader/api.json

@@ -0,0 +1,5 @@
+{
+  "id": "qwik-preloader",
+  "package": "@builder.io/qwik/preloader",
+  "members": []
+}

packages/docs/src/routes/api/qwik-preloader/index.mdx

@@ -0,0 +1,5 @@
+---
+title: \@builder.io/qwik/preloader API Reference
+---
+
+# [API](/api) › @builder.io/qwik/preloader

packages/docs/src/routes/api/qwik/api.json

@@ -1774,7 +1774,7 @@
         }
       ],
       "kind": "Function",
-      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\n> Warning: This API is now obsolete.\n> \n> This is no longer needed as the preloading happens automatically in qrl-class.ts. Leave this in your app for a while so it uninstalls existing service workers, but don't use it for new projects.\n> \n\n\n```typescript\nPrefetchServiceWorker: (opts: {\n    base?: string;\n    scope?: string;\n    path?: string;\n    verbose?: boolean;\n    fetchBundleGraph?: boolean;\n    nonce?: string;\n}) => JSXNode<'script'>\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nopts\n\n\n</td><td>\n\n{ base?: string; scope?: string; path?: string; verbose?: boolean; fetchBundleGraph?: boolean; nonce?: string; }\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\n[JSXNode](#jsxnode)<!-- -->&lt;'script'&gt;",
+      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\n> Warning: This API is now obsolete.\n> \n> This is no longer needed as the preloading happens automatically in qrl-class.ts. Leave this in your app for a while so it uninstalls existing service workers, but don't use it for new projects.\n> \n\n\n```typescript\nPrefetchServiceWorker: (opts: {\n    base?: string;\n    scope?: string;\n    path?: string;\n    verbose?: boolean;\n    fetchBundleGraph?: boolean;\n    nonce?: string;\n}) => JSXNode<'script'>\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nopts\n\n\n</td><td>\n\n{ base?: string; scope?: string; path?: string; verbose?: boolean; fetchBundleGraph?: boolean; nonce?: string; }\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\nJSXNode&lt;'script'&gt;",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/components/prefetch.ts",
       "mdFile": "qwik.prefetchserviceworker.md"
     },

packages/docs/src/routes/api/qwik/index.mdx

@@ -3667,7 +3667,7 @@ opts
 
 **Returns:**
 
-[JSXNode](#jsxnode)<'script'>
+JSXNode<'script'>
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/components/prefetch.ts)
 

packages/qwik-city/src/runtime/src/client-navigate.ts

@@ -1,5 +1,4 @@
 import { isBrowser } from '@builder.io/qwik';
-// @ts-expect-error we don't have types for the preloader yet
 import { p as preload } from '@builder.io/qwik/preloader';
 import type { NavigationType, ScrollState } from './types';
 import { isSamePath, toPath } from './utils';

packages/qwik-city/src/runtime/src/index.ts

@@ -55,7 +55,13 @@ export {
 } from './qwik-city-component';
 export { type LinkProps, Link } from './link-component';
 export { ServiceWorkerRegister } from './sw-component';
-export { useDocumentHead, useLocation, useContent, useNavigate } from './use-functions';
+export {
+  useDocumentHead,
+  useLocation,
+  useContent,
+  useNavigate,
+  usePreloaderInfo,
+} from './use-functions';
 export { usePreventNavigate$, usePreventNavigateQrl } from './use-functions';
 export { routeAction$, routeActionQrl } from './server-functions';
 export { globalAction$, globalActionQrl } from './server-functions';

packages/qwik-city/src/runtime/src/qwik-city.runtime.api.md

@@ -15,7 +15,7 @@ import { QRL } from '@builder.io/qwik';
 import { QRLEventHandlerMulti } from '@builder.io/qwik';
 import { QwikIntrinsicElements } from '@builder.io/qwik';
 import { QwikJSX } from '@builder.io/qwik';
-import type { ReadonlySignal } from '@builder.io/qwik';
+import { ReadonlySignal } from '@builder.io/qwik';
 import { RequestEvent } from '@builder.io/qwik-city/middleware/request-handler';
 import { RequestEventAction } from '@builder.io/qwik-city/middleware/request-handler';
 import { RequestEventBase } from '@builder.io/qwik-city/middleware/request-handler';
@@ -485,6 +485,12 @@ export const useLocation: () => RouteLocation;
 // @public (undocumented)
 export const useNavigate: () => RouteNavigate;
 
+// @alpha
+export const usePreloaderInfo: () => {
+    userEventPreloadsCount: ReadonlySignal<number>;
+    activePreloadsLength: ReadonlySignal;
+};
+
 // @public
 export const usePreventNavigate$: (qrl: PreventNavigateCallback) => void;
 

packages/qwik-city/src/runtime/src/use-functions.ts

@@ -3,8 +3,11 @@ import {
   noSerialize,
   useContext,
   useServerData,
+  useSignal,
   useVisibleTask$,
   type QRL,
+  type ReadonlySignal,
+  type Signal,
 } from '@builder.io/qwik';
 import {
   ContentContext,
@@ -23,6 +26,8 @@ import type {
   PreventNavigateCallback,
 } from './types';
 
+import { isBrowser } from '@builder.io/qwik/build';
+
 /** @public */
 export const useContent = () => useContext(ContentContext);
 
@@ -95,3 +100,32 @@ export const usePreventNavigate$ = implicit$FirstArg(usePreventNavigateQrl);
 export const useAction = (): RouteAction => useContext(RouteActionContext);
 
 export const useQwikCityEnv = () => noSerialize(useServerData<QwikCityEnvData>('qwikcity'));
+
+/**
+ * Reactive hook exposing the current number of high-priority user-event preloads. Updates whenever
+ * the preloader recalculates the queue on the client.
+ *
+ * @alpha
+ */
+export const usePreloaderInfo = (): {
+  userEventPreloadsCount: ReadonlySignal<number>;
+  activePreloadsLength: ReadonlySignal;
+} => {
+  const userEventPreloadsCount: Signal<number> = useSignal(0);
+  const activePreloadsLength = useSignal(0);
+
+  useVisibleTask$(() => {
+    if (!isBrowser) {
+      return;
+    }
+    const handler = (ev: Event) => {
+      const detail = (ev as CustomEvent).detail;
+      userEventPreloadsCount.value = detail?.userEventPreloads?.length;
+      activePreloadsLength.value = detail?.activePreloads.length;
+    };
+    window.addEventListener('newPreloaderInfo', handler);
+    return () => window.removeEventListener('newPreloaderInfo', handler);
+  });
+
+  return { userEventPreloadsCount, activePreloadsLength };
+};

packages/qwik/package.json

@@ -113,6 +113,7 @@
       "require": "./dist/optimizer.cjs"
     },
     "./preloader": {
+      "types": "./dist/preloader.d.ts",
       "import": "./dist/preloader.mjs",
       "require": "./dist/preloader.cjs"
     },
@@ -145,6 +146,7 @@
     "optimizer.d.ts",
     "server.d.ts",
     "testing.d.ts",
+    "preloader.d.ts",
     "qwik-cli.cjs"
   ],
   "homepage": "https://qwik.dev/",

packages/qwik/preloader.d.ts

@@ -0,0 +1,2 @@
+// re-export for typescript in old resolution mode
+export * from './dist/loader';

packages/qwik/src/core/preloader/api-extractor.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../api-extractor.json",
+  "mainEntryPointFilePath": "<projectFolder>/../../dist-dev/dts-out/packages/qwik/src/core/preloader/index.d.ts",
+  "newlineKind": "lf",
+  "apiReport": {
+    "enabled": true,
+    "reportFileName": "qwik.preloader",
+    "reportFolder": "<projectFolder>/src/core/preloader/",
+    "reportTempFolder": "<projectFolder>/../../dist-dev/api-extractor/preloader/"
+  },
+  "dtsRollup": {
+    "enabled": true,
+    "untrimmedFilePath": "<projectFolder>/dist/preloader.d.ts"
+  },
+  "docModel": {
+    "enabled": true,
+    "apiJsonFilePath": "<projectFolder>/../../dist-dev/api/qwik/preloader/docs.api.json"
+  }
+}

packages/qwik/src/core/preloader/bundle-graph.ts

@@ -19,6 +19,7 @@ const makeBundle = (name: string, deps?: ImportProbability[]) => {
   };
 };
 
+/** @internal */
 export const parseBundleGraph = (serialized: (string | number)[]) => {
   const graph: BundleGraph = new Map();
   let i = 0;
@@ -64,6 +65,7 @@ export const getBundle = (name: string) => {
 };
 
 /** Used in browser */
+/** @internal */
 export const loadBundleGraph = (
   basePath: string,
   serializedResponse?: ReturnType<typeof fetch>,
@@ -118,6 +120,7 @@ export const loadBundleGraph = (
 };
 
 /** Used during SSR */
+/** @internal */
 export const initPreloader = (
   serializedBundleGraph?: (string | number)[],
   opts?: {