feat(dev,html-app): introduce a Forecaster HTML app

Author: azasypkin

.env.example

@@ -78,6 +78,8 @@ COURIER_HTTP_REQUEST_CONFIG_AUTH_CONFIG_VALUE="Bearer <generated-kratos-jwt>"
 # SECUTILS_HTML_APP_RESPONDER_ID_PDF_EXTRACTOR_MD=
 # SECUTILS_HTML_APP_RESPONDER_ID_ECHO=
 # SECUTILS_HTML_APP_RESPONDER_ID_ECHO_MD=
+# SECUTILS_HTML_APP_RESPONDER_ID_FORECAST=
+# SECUTILS_HTML_APP_RESPONDER_ID_FORECAST_MD=
 # SECUTILS_HTML_APP_RESPONDER_ID_LLMS_TXT=
 # SECUTILS_HTML_APP_RESPONDER_ID_ROBOTS_TXT=
 # SECUTILS_HTML_APP_RESPONDER_ID_SITEMAP_XML=

README.md

@@ -42,6 +42,7 @@ A handful of focused, no-signup, browser-only tools is hosted at [tools.secutils
 | [Markdown to HTML](https://tools.secutils.dev/md-to-html)         | Self-contained HTML and PDF export from Markdown                   | [`/md-to-html.md`](https://tools.secutils.dev/md-to-html.md)  |
 | [PDF Extractor](https://tools.secutils.dev/pdf)                   | Extract spatial text and structured JSON from PDFs, in-browser     | [`/pdf.md`](https://tools.secutils.dev/pdf.md)                |
 | [HTTP Echo / Mock Response](https://tools.secutils.dev/echo)      | Build a customizable HTTP response, served as a shareable URL      | [`/echo.md`](https://tools.secutils.dev/echo.md)              |
+| [Forecast](https://tools.secutils.dev/forecast)                   | Fit trendlines, forecast future values, spot anomalies             | [`/forecast.md`](https://tools.secutils.dev/forecast.md)      |
 
 The aggregate index of all skills (including specialized ones not listed above) is published at [tools.secutils.dev/llms.txt](https://tools.secutils.dev/llms.txt) following the [llmstxt.org](https://llmstxt.org/) convention. Source HTML for every tool lives in [`dev/tools/`](dev/tools/) (see [`dev/tools/AGENTS.md`](dev/tools/AGENTS.md) for the deploy/SEO recipe).
 

components/secutils-docs/static/img/og/og-forecast-light.png

@@ -4,7 +4,7 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Free Developer and Security Tools | Secutils.dev</title>
-    <meta name="description" content="Free, no-signup single-page tools for developers and security engineers. Decode JWTs, SAML, X.509 chains, mock HTTP responses, convert Markdown, extract PDF text. Browser-only.">
+    <meta name="description" content="Free, no-signup single-page tools for developers and security engineers. Decode JWTs, SAML, X.509 chains, mock HTTP responses, convert Markdown, extract PDF text, fit trendlines and forecasts. Browser-only.">
     <meta name="robots" content="index, follow, max-image-preview:large">
     <link rel="canonical" href="https://{{TOOLS_HOST}}/">
     <meta name="su-tool-path" content="/">
@@ -14,7 +14,7 @@
     <meta property="og:type" content="website">
     <meta property="og:site_name" content="Secutils.dev">
     <meta property="og:title" content="Free Developer &amp; Security Tools &mdash; Secutils.dev">
-    <meta property="og:description" content="Free, no-signup single-page tools for developers and security engineers. Decode JWTs, SAML, X.509 chains, mock HTTP responses, convert Markdown, extract PDF text.">
+    <meta property="og:description" content="Free, no-signup single-page tools for developers and security engineers. Decode JWTs, SAML, X.509 chains, mock HTTP responses, convert Markdown, extract PDF text, fit trendlines and forecasts.">
     <meta property="og:url" content="https://{{TOOLS_HOST}}/">
     <meta property="og:image" content="https://secutils.dev/docs/img/og/og-index.png">
     <meta property="og:image:width" content="1200">
@@ -25,7 +25,7 @@
     <meta name="twitter:title" content="Free Developer &amp; Security Tools &mdash; Secutils.dev">
     <meta name="twitter:description" content="Free, no-signup single-page tools for developers and security engineers.">
     <meta name="twitter:image" content="https://secutils.dev/docs/img/og/og-index.png">
-    <script type="application/ld+json">{"@context":"https://schema.org","@type":"ItemList","name":"Secutils.dev Free Tools","url":"https://{{TOOLS_HOST}}/","itemListElement":[{"@type":"ListItem","position":1,"url":"https://{{TOOLS_HOST}}/jwt","name":"JWT Debugger"},{"@type":"ListItem","position":2,"url":"https://{{TOOLS_HOST}}/saml","name":"SAML Decoder"},{"@type":"ListItem","position":3,"url":"https://{{TOOLS_HOST}}/pem","name":"PEM Certificate Decoder"},{"@type":"ListItem","position":4,"url":"https://{{TOOLS_HOST}}/md-to-html","name":"Markdown to HTML"},{"@type":"ListItem","position":5,"url":"https://{{TOOLS_HOST}}/pdf","name":"PDF Extractor"},{"@type":"ListItem","position":6,"url":"https://{{TOOLS_HOST}}/echo","name":"HTTP Echo / Mock Response"}]}</script>
+    <script type="application/ld+json">{"@context":"https://schema.org","@type":"ItemList","name":"Secutils.dev Free Tools","url":"https://{{TOOLS_HOST}}/","itemListElement":[{"@type":"ListItem","position":1,"url":"https://{{TOOLS_HOST}}/jwt","name":"JWT Debugger"},{"@type":"ListItem","position":2,"url":"https://{{TOOLS_HOST}}/saml","name":"SAML Decoder"},{"@type":"ListItem","position":3,"url":"https://{{TOOLS_HOST}}/pem","name":"PEM Certificate Decoder"},{"@type":"ListItem","position":4,"url":"https://{{TOOLS_HOST}}/md-to-html","name":"Markdown to HTML"},{"@type":"ListItem","position":5,"url":"https://{{TOOLS_HOST}}/pdf","name":"PDF Extractor"},{"@type":"ListItem","position":6,"url":"https://{{TOOLS_HOST}}/echo","name":"HTTP Echo / Mock Response"},{"@type":"ListItem","position":7,"url":"https://{{TOOLS_HOST}}/forecast","name":"Forecast"}]}</script>
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300..700&family=Roboto+Mono:wght@400..700&display=swap" rel="stylesheet">
@@ -170,6 +170,10 @@ <h1 class="page-title">Developer Tools</h1>
                 <div class="tool-name">Echo <span class="tool-path">/echo</span> <span class="arrow">&rarr;</span></div>
                 <div class="tool-desc">Build a fully customizable HTTP response (status, headers, body) and serve it as a shareable URL.</div>
             </a>
+            <a class="tool-card" href="/forecast">
+                <div class="tool-name">Forecast <span class="tool-path">/forecast</span> <span class="arrow">&rarr;</span></div>
+                <div class="tool-desc">Fit trendlines, forecast future values, smooth noisy data, and spot anomalies in any numeric series. WASM-powered, single-page, shareable.</div>
+            </a>
         </div>
     </main>
 

components/secutils-docs/static/img/og/og-forecast.png

@@ -0,0 +1,2 @@
+node_modules/
+dist/

dev/tools/forecast.html

@@ -0,0 +1,96 @@
+# `@secutils-dev/micro-ml-browser`
+
+Browser-compatible Vite build of [`micro-ml`](https://github.com/AdamPerlinski/micro-ml).
+Produces a single self-contained ESM module at `dist/micro-ml.js` that is
+inlined into `dev/tools/forecast.html` at deploy time by
+`dev/tools/deploy.ts`'s `data-su-bundle="micro-ml"` mechanism.
+
+Not published. Internal to this repo. See
+[`dev/tools/AGENTS.md`](../../AGENTS.md) -> "Embedded JS bundles" for the
+inliner contract.
+
+## Build
+
+```bash
+npm ci
+npm run build
+# => dist/micro-ml.js
+```
+
+`make tools-bundles` from the repo root builds this (and any future
+bundles) in one go. `make deploy-tools` builds it on demand if
+`dist/micro-ml.js` is missing or older than the sources here.
+
+## Pinned upstream versions
+
+| dep         | version    | notes                                                   |
+|-------------|------------|---------------------------------------------------------|
+| `micro-ml`  | `1.0.0`    | exact pin -- we patch its WASM-loader path via the plugin in `vite.config.ts` |
+| `vite`      | `^7.1.13`  | bundler                                                 |
+| (vendored) `micro_ml_core_bg.wasm` | (~145 KB) | shipped inside `micro-ml` itself        |
+
+The bundle is shipped to the responder body in the `gzip-base64` encoding
+variant of `data-su-bundle` (~250 KB gzipped, ~340 KB base64'd). The
+forecast HTML loader reverses both steps via `DecompressionStream('gzip')`
+on first use.
+
+## How the WASM gets inlined
+
+Upstream `micro-ml@1.0.0`'s browser entry lazy-loads its Rust core via:
+
+```js
+const core = await import('./micro_ml_core-CYEMXCKP.js');
+await core.default(); // fetches micro_ml_core_bg.wasm via new URL(..., import.meta.url)
+```
+
+The `data-su-bundle` contract requires a **single self-contained** file --
+the responder body cannot ship a sibling `.wasm`. So `vite.config.ts`'s
+`microMlInlineWasmPlugin`:
+
+1. Reads `node_modules/micro-ml/dist/micro_ml_core_bg.wasm` at build time.
+2. Exposes the bytes via the virtual `virtual:micro-ml-wasm-bytes`
+   specifier (default export is a base64-decoded `Uint8Array`).
+3. Rewrites upstream `dist/index.js` to call
+   `core.initSync({ module: <bytes> })` directly, bypassing the
+   `default()` fetch path. The Node branch is left untouched; it's
+   harmless dead code in the browser bundle.
+
+If a future `micro-ml` release reshapes the minified source, the
+`ELSE_BRANCH_RE` regex stops matching and the build **throws** at the
+`transform` stage. Re-inspect `node_modules/micro-ml/dist/index.js` and
+update the regex.
+
+## Re-syncing against a newer `micro-ml`
+
+1. Bump the pin in `package.json` (exact version, not a range).
+2. `npm install`.
+3. `npm run build`. If it throws "could not find the browser branch of
+   micro-ml's lazy WASM initialiser", open
+   `node_modules/micro-ml/dist/index.js` and grep for `else await
+   ...default()` -- update `ELSE_BRANCH_RE` to match. The right-hand
+   replacement (`initSync({ module })`) does not change because
+   wasm-pack's `initSync({ module })` API is stable.
+4. Verify the bundle still inlines the WASM:
+   `grep -c '"data:application/wasm' dist/micro-ml.js` should print `0`
+   (we don't go through a data: URL; we feed bytes straight to
+   `initSync`), and `grep -c 'fetch' dist/micro-ml.js` should be 0
+   (no runtime fetch of the WASM).
+5. Smoke-test by loading the forecast tool and clicking a sample
+   dataset: the first chart paint should happen within ~50 ms after the
+   bundle is decoded.
+
+## Runtime caveats
+
+1. **First-use cost.** The bundle decodes a base64'd WASM blob and calls
+   `WebAssembly.Module()` synchronously on first ML invocation. On a
+   modern laptop this is ~10-30 ms. The forecast tool only loads the
+   bundle on the first user action, so a search-result visitor never pays
+   it.
+2. **Worker version is not bundled.** Upstream ships a `micro-ml/worker`
+   subpath that wraps the API in a Web Worker. The forecast tool runs on
+   the main thread (sub-millisecond on typical 200-point series), so we
+   don't bundle the worker variant.
+3. **The Node branch is dead code in the browser bundle.** It's preserved
+   so that running this bundle under Node would still work (defensive,
+   not load-bearing). esbuild's minifier does not fully drop it because
+   the `typeof globalThis.process` guard is opaque at compile time.