@hashsome/runtime 0.3.0 → 0.5.0

package/dist/app/entry.client.js

@@ -2,6 +2,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { startTransition, StrictMode } from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { HydratedRouter } from 'react-router/dom';
+import { watchBrowserForNewVersion } from './version-watch.js';
 startTransition(() => {
     hydrateRoot(document, _jsx(StrictMode, { children: _jsx(HydratedRouter, {}) }));
 });
+// A dashboard left open for weeks is reloaded once a newer build is being served.
+watchBrowserForNewVersion();

package/dist/app/root.d.ts

@@ -1,8 +1,10 @@
-type ThemeMode = 'light' | 'dark' | 'system';
+import { type ThemeMode } from '@hashsome/ui';
 /** Builds the document shell's `Layout`, painted before any client JS runs — so its background
  * needs to already roughly match the configured theme, or hydration visibly swaps the color out
  * from under the user. `'system'` can't know the OS preference at render time, so it ships both
- * colors and lets a plain CSS media query (not JS) pick the right one with no flash either way.
+ * colors and lets a plain CSS media query (not JS) pick the right one with no flash either way. A
+ * schedule (by the clock or the sun) is not known yet either, so it starts as `'system'` does and
+ * the app takes over once it is running.
  * The Google Fonts `<link>` is rendered here too (not left to `HashsomeProvider`'s own client-side
  * fallback) so the chosen font is already loading before hydration, not swapped in after. */
 export declare function createLayout(theme?: ThemeMode, font?: string): ({ children }: {
@@ -15,4 +17,3 @@ export declare const Layout: ({ children }: {
     children: React.ReactNode;
 }) => import("react").JSX.Element;
 export declare function HydrateFallback(): null;
-export {};

package/dist/app/root.js

@@ -8,13 +8,16 @@ const SHELL = {
 /** Builds the document shell's `Layout`, painted before any client JS runs — so its background
  * needs to already roughly match the configured theme, or hydration visibly swaps the color out
  * from under the user. `'system'` can't know the OS preference at render time, so it ships both
- * colors and lets a plain CSS media query (not JS) pick the right one with no flash either way.
+ * colors and lets a plain CSS media query (not JS) pick the right one with no flash either way. A
+ * schedule (by the clock or the sun) is not known yet either, so it starts as `'system'` does and
+ * the app takes over once it is running.
  * The Google Fonts `<link>` is rendered here too (not left to `HashsomeProvider`'s own client-side
  * fallback) so the chosen font is already loading before hydration, not swapped in after. */
 export function createLayout(theme = 'dark', font = DEFAULT_FONT) {
-    const colorScheme = theme === 'system' ? 'light dark' : theme;
+    const followsSystem = typeof theme === 'object' || theme === 'system';
+    const colorScheme = followsSystem ? 'light dark' : theme;
     const initial = theme === 'light' ? SHELL.light : SHELL.dark;
-    const systemOverride = theme === 'system'
+    const systemOverride = followsSystem
         ? `@media (prefers-color-scheme: light) { html, body { background: ${SHELL.light.bg}; color: ${SHELL.light.fg}; } }`
         : '';
     const kioskCss = `

package/dist/app/version-watch.d.ts

@@ -0,0 +1,27 @@
+/** The id of the build this page came from; undefined in dev, where nothing is watched. */
+export declare const PAGE_BUILD_ID: string | undefined;
+export interface VersionWatchOptions {
+    /** The build this page is. */
+    buildId: string;
+    /** The build being served now; undefined when it cannot be told (offline, an old server). */
+    read: () => Promise<string | undefined>;
+    reload: () => void;
+    /** How often to ask while the page is open. Default one minute. */
+    intervalMs?: number;
+    /** Calls the function when the page may have been asleep: shown again, or back online. */
+    onWake: (check: () => void) => () => void;
+    /** Remembers when this page last reloaded for a new version, across the reload. */
+    lastReload: {
+        get: () => number | undefined;
+        set: (time: number) => void;
+    };
+    now?: () => number;
+}
+/**
+ * Reloads the page when the server is serving a different build than the one it was loaded from. A
+ * tablet or wall display keeps a dashboard open for weeks, and a deployment replaces the server
+ * under it without replacing the page. Returns a function that stops watching.
+ */
+export declare function watchForNewVersion(options: VersionWatchOptions): () => void;
+/** Starts watching in the browser, for a production build. Does nothing in dev. */
+export declare function watchBrowserForNewVersion(): void;

package/dist/app/version-watch.js

@@ -0,0 +1,84 @@
+import { VERSION_PATH } from '../src/build-id.js';
+/** The id of the build this page came from; undefined in dev, where nothing is watched. */
+export const PAGE_BUILD_ID = typeof HASHSOME_BUILD_ID === 'undefined' ? undefined : HASHSOME_BUILD_ID;
+/** Never reload twice within this long: if the server keeps answering with another id (a stale cache
+ * in front of it), the page would otherwise reload for ever. */
+const REPEAT_MS = 30_000;
+/**
+ * Reloads the page when the server is serving a different build than the one it was loaded from. A
+ * tablet or wall display keeps a dashboard open for weeks, and a deployment replaces the server
+ * under it without replacing the page. Returns a function that stops watching.
+ */
+export function watchForNewVersion(options) {
+    const now = options.now ?? Date.now;
+    let busy = false;
+    const check = () => {
+        if (busy) {
+            return;
+        }
+        busy = true;
+        options.read().then((served) => {
+            busy = false;
+            if (served === undefined || served === options.buildId) {
+                return;
+            }
+            const last = options.lastReload.get();
+            if (last !== undefined && now() - last < REPEAT_MS) {
+                return;
+            }
+            options.lastReload.set(now());
+            options.reload();
+        }, () => {
+            busy = false;
+        });
+    };
+    const timer = setInterval(check, options.intervalMs ?? 60_000);
+    const stopWake = options.onWake(check);
+    return () => {
+        clearInterval(timer);
+        stopWake();
+    };
+}
+/** Starts watching in the browser, for a production build. Does nothing in dev. */
+export function watchBrowserForNewVersion() {
+    const buildId = PAGE_BUILD_ID;
+    if (buildId === undefined) {
+        return;
+    }
+    const KEY = 'hashsome:reloaded-at';
+    watchForNewVersion({
+        buildId,
+        read: async () => {
+            const response = await fetch(VERSION_PATH, { cache: 'no-store' });
+            return response.ok ? (await response.json()).id : undefined;
+        },
+        reload: () => window.location.reload(),
+        onWake: (check) => {
+            const onVisible = () => document.visibilityState === 'visible' && check();
+            document.addEventListener('visibilitychange', onVisible);
+            window.addEventListener('online', check);
+            return () => {
+                document.removeEventListener('visibilitychange', onVisible);
+                window.removeEventListener('online', check);
+            };
+        },
+        lastReload: {
+            get: () => {
+                try {
+                    return Number(sessionStorage.getItem(KEY)) || undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            set: (time) => {
+                try {
+                    sessionStorage.setItem(KEY, String(time));
+                }
+                catch {
+                    // Without storage the guard is the page's own memory only, which a reload loses.
+                }
+            },
+        },
+    });
+}

package/dist/src/build-id.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from 'vite';
+/** Where a build records its id, next to the client files, and where the server tells it. */
+export declare const VERSION_FILE = "version.json";
+export declare const VERSION_PATH = "/_hashsome/version";
+/** One per `hashsome build` run: the same for everything that run produces. */
+export declare const buildId: () => string;
+/**
+ * Gives a production build an id that its client knows (as `HASHSOME_BUILD_ID`) and the server
+ * can tell (the client directory gets a `version.json`). A page left open compares the two and
+ * reloads when a newer build is being served. Dev builds have neither, so nothing is watched there.
+ */
+export declare function hashsomeBuildId(): Plugin;

package/dist/src/build-id.js

@@ -0,0 +1,29 @@
+/** Where a build records its id, next to the client files, and where the server tells it. */
+export const VERSION_FILE = 'version.json';
+export const VERSION_PATH = '/_hashsome/version';
+let id;
+/** One per `hashsome build` run: the same for everything that run produces. */
+export const buildId = () => (id ??= process.env.HASHSOME_BUILD_ID || Date.now().toString(36));
+/**
+ * Gives a production build an id that its client knows (as `HASHSOME_BUILD_ID`) and the server
+ * can tell (the client directory gets a `version.json`). A page left open compares the two and
+ * reloads when a newer build is being served. Dev builds have neither, so nothing is watched there.
+ */
+export function hashsomeBuildId() {
+    return {
+        name: 'hashsome:build-id',
+        apply: 'build',
+        config: () => ({ define: { HASHSOME_BUILD_ID: JSON.stringify(buildId()) } }),
+        generateBundle() {
+            // The server's own build has no use for it; the client's output is what gets served.
+            if (this.environment && this.environment.name !== 'client') {
+                return;
+            }
+            this.emitFile({
+                type: 'asset',
+                fileName: VERSION_FILE,
+                source: JSON.stringify({ id: buildId() }),
+            });
+        },
+    };
+}

package/dist/src/config.d.ts

@@ -19,6 +19,8 @@ export interface HashsomeConfig {
     host?: string;
     /** Defaults for `hashsome package`, so deploying is `pnpm package` with no flags. */
     package?: PackageConfig;
+    /** Answers the requests a device makes to check that an address is a Home Assistant (its login flow, `/api/`, `/api/config`, `/manifest.json`), so a wall display that only opens a Home Assistant, like the Shelly Wall Display, accepts this server's address. Off by default. Any login is accepted — nothing sits behind it, and Hashsome has no login of its own — so turn it on only for a server on a network you trust. */
+    homeAssistantCompat?: boolean;
 }
 export interface ResolvedConfig {
     root: string;
@@ -26,6 +28,7 @@ export interface ResolvedConfig {
     port: number;
     host: string;
     package: PackageConfig;
+    homeAssistantCompat: boolean;
 }
 export declare function defineConfig(config: HashsomeConfig): HashsomeConfig;
 export declare const CONFIG_FILE = "hashsome.config.ts";

package/dist/src/config.js

@@ -40,6 +40,7 @@ export function resolveConfig(root, user) {
         port: Number(process.env.PORT ?? user.port ?? 3000),
         host: process.env.HOST ?? user.host ?? '0.0.0.0',
         package: user.package ?? {},
+        homeAssistantCompat: user.homeAssistantCompat ?? false,
     };
 }
 /** Loads `<root>/hashsome.config.ts` (if present) and applies defaults. */

package/dist/src/server/ha-compat.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** The Home Assistant version this claims to be: a recent one, so a client with a minimum accepts it. */
+export declare const HA_COMPAT_VERSION = "2026.9.0";
+type Next = (error?: unknown) => void;
+/**
+ * Answers the requests a device makes to check that an address is a Home Assistant, as Home
+ * Assistant's own documented authentication and API do (https://developers.home-assistant.io/docs/auth_api/):
+ * the login flow, a token, `/api/`, `/api/config`, `/api/discovery_info` and `/manifest.json`. Any login
+ * is accepted, because there is nothing behind it: Hashsome has no login of its own. Everything else
+ * goes on to the app. For a wall display that only opens a Home Assistant (the Shelly Wall Display).
+ */
+export declare function homeAssistantCompat(): (req: IncomingMessage, res: ServerResponse, next: Next) => Promise<void>;
+export {};

package/dist/src/server/ha-compat.js

@@ -0,0 +1,132 @@
+import { randomBytes } from 'node:crypto';
+/** The Home Assistant version this claims to be: a recent one, so a client with a minimum accepts it. */
+export const HA_COMPAT_VERSION = '2026.9.0';
+const send = (res, body, type = 'application/json') => {
+    const text = JSON.stringify(body);
+    res.statusCode = 200;
+    res.setHeader('Content-Type', type);
+    res.setHeader('Content-Length', Buffer.byteLength(text));
+    res.end(text);
+};
+/** A request's body, JSON or a form (the token request is a form). Never throws. */
+async function bodyOf(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(chunk);
+    }
+    const text = Buffer.concat(chunks).toString('utf8');
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return Object.fromEntries(new URLSearchParams(text));
+    }
+}
+/**
+ * Answers the requests a device makes to check that an address is a Home Assistant, as Home
+ * Assistant's own documented authentication and API do (https://developers.home-assistant.io/docs/auth_api/):
+ * the login flow, a token, `/api/`, `/api/config`, `/api/discovery_info` and `/manifest.json`. Any login
+ * is accepted, because there is nothing behind it: Hashsome has no login of its own. Everything else
+ * goes on to the app. For a wall display that only opens a Home Assistant (the Shelly Wall Display).
+ */
+export function homeAssistantCompat() {
+    return async (req, res, next) => {
+        try {
+            const { pathname } = new URL(req.url ?? '/', 'http://localhost');
+            const method = req.method ?? 'GET';
+            const base = `http://${req.headers.host ?? 'localhost'}`;
+            const handler = ['homeassistant', null];
+            if (method === 'GET' && pathname === '/auth/providers') {
+                return send(res, {
+                    providers: [{ name: 'Home Assistant Local', id: null, type: 'homeassistant' }],
+                    preselect_remember_me: true,
+                });
+            }
+            if (method === 'POST' && pathname === '/auth/login_flow') {
+                await bodyOf(req);
+                return send(res, {
+                    type: 'form',
+                    flow_id: randomBytes(16).toString('hex'),
+                    handler,
+                    step_id: 'init',
+                    data_schema: [
+                        { type: 'string', name: 'username', required: true },
+                        { type: 'string', name: 'password', required: true },
+                    ],
+                    errors: {},
+                    description_placeholders: null,
+                    last_step: null,
+                    preview: null,
+                });
+            }
+            const step = /^\/auth\/login_flow\/([^/]+)$/.exec(pathname);
+            if (method === 'POST' && step) {
+                await bodyOf(req);
+                return send(res, {
+                    version: 1,
+                    type: 'create_entry',
+                    flow_id: step[1],
+                    handler,
+                    title: 'Home',
+                    result: randomBytes(16).toString('hex'),
+                    description: null,
+                    description_placeholders: null,
+                });
+            }
+            if (method === 'POST' && pathname === '/auth/token') {
+                await bodyOf(req);
+                return send(res, {
+                    access_token: randomBytes(24).toString('hex'),
+                    expires_in: 1800,
+                    refresh_token: randomBytes(24).toString('hex'),
+                    token_type: 'Bearer',
+                });
+            }
+            if (pathname === '/api' || pathname === '/api/') {
+                return send(res, { message: 'API running.' });
+            }
+            if (pathname === '/api/config') {
+                return send(res, {
+                    components: ['api', 'auth', 'config', 'frontend', 'http', 'lovelace', 'websocket_api'],
+                    config_dir: '/config',
+                    location_name: 'Home',
+                    time_zone: 'UTC',
+                    unit_system: { length: 'km', mass: 'g', temperature: '°C', volume: 'L' },
+                    state: 'RUNNING',
+                    internal_url: base,
+                    external_url: null,
+                    version: HA_COMPAT_VERSION,
+                });
+            }
+            if (pathname === '/api/discovery_info') {
+                return send(res, {
+                    base_url: base,
+                    location_name: 'Home',
+                    requires_api_password: false,
+                    uuid: 'hashsome',
+                    version: HA_COMPAT_VERSION,
+                });
+            }
+            if (pathname === '/manifest.json') {
+                return send(res, {
+                    name: 'Home Assistant',
+                    short_name: 'Home Assistant',
+                    description: 'Home automation platform that puts local control and privacy first.',
+                    id: '/?homescreen=1',
+                    start_url: '/?homescreen=1',
+                    display: 'standalone',
+                    dir: 'ltr',
+                    lang: 'en-US',
+                    background_color: '#FFFFFF',
+                    theme_color: '#2980b9',
+                    prefer_related_applications: true,
+                    related_applications: [{ platform: 'play', id: 'io.homeassistant.companion.android' }],
+                }, 'application/manifest+json');
+            }
+            next();
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}

package/dist/src/server/production.d.ts

@@ -1,7 +1,9 @@
 import type { Integration } from '@hashsome/core';
 import { type Express } from 'express';
 import type { ResolvedConfig } from '../config.ts';
-export declare function createApp(clientDir: string, integrations?: Integration[]): Express;
+export declare function createApp(clientDir: string, integrations?: Integration[], options?: {
+    homeAssistantCompat?: boolean;
+}): Express;
 /** Where `hashsome build` puts the client, under a project. A packaged release keeps it elsewhere. */
 export declare const BUILT_CLIENT: string;
 export declare function startServer(config: ResolvedConfig, clientDir?: string): import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;

package/dist/src/server/production.js

@@ -1,16 +1,44 @@
 import express, {} from 'express';
 import { createServer } from 'node:http';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { VERSION_FILE, VERSION_PATH } from '../build-id.js';
 import { serveAsset } from './assets.js';
+import { homeAssistantCompat } from './ha-compat.js';
 import { Proxy } from './proxy.js';
 import { startIntegrations } from './integrations.js';
 import { attachWebSocket } from './websocket.js';
-export function createApp(clientDir, integrations = []) {
+/** The id the build left in the client directory; none for a client built without one. */
+function readVersion(clientDir) {
+    try {
+        const { id } = JSON.parse(readFileSync(join(clientDir, VERSION_FILE), 'utf8'));
+        return typeof id === 'string' && id !== '' ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createApp(clientDir, integrations = [], options = {}) {
     const app = express();
     app.disable('x-powered-by');
+    if (options.homeAssistantCompat) {
+        app.use(homeAssistantCompat());
+    }
     app.get('/healthz', (_req, res) => {
         res.json({ status: 'ok' });
     });
+    // Which build this is, for a page that has been open a while to compare with its own and reload.
+    // Never cached: a stale answer is exactly what it is there to avoid.
+    const version = readVersion(clientDir);
+    app.get(VERSION_PATH, (_req, res) => {
+        res.setHeader('cache-control', 'no-store');
+        if (version) {
+            res.json({ id: version });
+        }
+        else {
+            res.status(404).end();
+        }
+    });
     app.use((req, res, next) => {
         serveAsset(integrations, req, res).then((served) => (served ? undefined : next()), next);
     });
@@ -27,7 +55,9 @@ export function createApp(clientDir, integrations = []) {
 /** Where `hashsome build` puts the client, under a project. A packaged release keeps it elsewhere. */
 export const BUILT_CLIENT = join('build', 'client');
 export function startServer(config, clientDir = join(config.root, BUILT_CLIENT)) {
-    const server = createServer(createApp(clientDir, config.integrations));
+    const server = createServer(createApp(clientDir, config.integrations, {
+        homeAssistantCompat: config.homeAssistantCompat,
+    }));
     const proxy = new Proxy(config.integrations, { log: console.log });
     attachWebSocket(server, proxy);
     const stop = startIntegrations(config.integrations, { log: console.log });

package/dist/src/vite-config.js

@@ -1,5 +1,6 @@
 import { reactRouter } from '@react-router/dev/vite';
 import { defineConfig } from 'vite';
+import { hashsomeBuildId } from './build-id.js';
 /**
  * Sensible default, re-exported by the project's own `vite.config.ts` (the React Router plugin
  * requires a config file at the project root). Server settings and the dev proxy are supplied
@@ -11,7 +12,7 @@ import { defineConfig } from 'vite';
  * ("Expected build manifest").
  */
 export default defineConfig(() => ({
-    plugins: [reactRouter()],
+    plugins: [reactRouter(), hashsomeBuildId()],
     // React Router's SPA prerender starts a private preview server; pin it to IPv4 so it is
     // reachable in containers where `localhost` resolves to ::1.
     preview: { host: '127.0.0.1' },

package/dist/src/vite.js

@@ -2,6 +2,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { searchForWorkspaceRoot } from 'vite';
 import { serveAsset } from './server/assets.js';
+import { homeAssistantCompat } from './server/ha-compat.js';
 import { attachWebSocket } from './server/websocket.js';
 const runtimeRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
 /** Dev only: `/healthz`, the `/ws` proxy and the asset route on Vite's own server. */
@@ -9,6 +10,9 @@ function hashsomeDevServer(proxy, config) {
     return {
         name: 'hashsome:dev-server',
         configureServer(server) {
+            if (config.homeAssistantCompat) {
+                server.middlewares.use(homeAssistantCompat());
+            }
             server.middlewares.use('/healthz', (_req, res) => {
                 res.setHeader('content-type', 'application/json');
                 res.end('{"status":"ok"}');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashsome/runtime",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Server + CLI that serves a project's own dashboards",
   "type": "module",
   "exports": {
@@ -38,8 +38,8 @@
     "jsdom": "30.1.1"
   },
   "dependencies": {
-    "@hashsome/core": "0.3.0",
-    "@hashsome/ui": "0.3.0",
+    "@hashsome/core": "0.5.0",
+    "@hashsome/ui": "0.5.0",
     "@react-router/dev": "8.4.0",
     "express": "5.2.1",
     "react": "19.3.0",