@hashsome/runtime 0.4.0 → 0.6.0

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/bin/hashsome.js

@@ -5,7 +5,7 @@ export {};
 const commands = {
     dev: async () => (await import('../src/cli/dev.js')).dev(),
     build: async () => (await import('../src/cli/build.js')).build(),
-    start: async () => (await import('../src/cli/start.js')).start(),
+    start: async () => (await import('../src/cli/start.js')).start(process.argv.slice(3)),
     package: async () => (await import('../src/cli/package.js')).packageCommand(process.argv.slice(3)),
     upgrade: async () => (await import('../src/cli/upgrade.js')).upgradeCommandLine(process.argv.slice(3)),
 };

package/dist/src/cli/start.d.ts

@@ -1 +1,5 @@
-export declare function start(): Promise<void>;
+/** `start` builds first, so what it serves is the project as it is now and with the environment it is
+ * started with (the debug menu's `HASHSOME_DEBUG`, say, is part of the build); `--no-build` serves
+ * what is already built. */
+export declare function shouldBuild(args: string[]): boolean;
+export declare function start(args?: string[]): Promise<void>;

package/dist/src/cli/start.js

@@ -2,10 +2,20 @@ import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { loadConfig } from '../config.js';
 import { startServer } from '../server/production.js';
-export async function start() {
+/** `start` builds first, so what it serves is the project as it is now and with the environment it is
+ * started with (the debug menu's `HASHSOME_DEBUG`, say, is part of the build); `--no-build` serves
+ * what is already built. */
+export function shouldBuild(args) {
+    return !args.includes('--no-build');
+}
+export async function start(args = []) {
+    if (shouldBuild(args)) {
+        // Loaded only for this: serving a build needs none of Vite.
+        await (await import('./build.js')).build({ exit: false });
+    }
     const config = await loadConfig(resolve(process.cwd()));
     if (!existsSync(join(config.root, 'build', 'client', 'index.html'))) {
-        console.error('No build found. Run `hashsome build` first.');
+        console.error('No build found. Run `hashsome build` first, or start without `--no-build`.');
         process.exit(1);
     }
     startServer(config);

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

@@ -4,6 +4,7 @@ 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';
@@ -17,9 +18,12 @@ function readVersion(clientDir) {
         return undefined;
     }
 }
-export function createApp(clientDir, integrations = []) {
+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' });
     });
@@ -51,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.d.ts

@@ -1,5 +1,7 @@
 import { type InlineConfig } from 'vite';
 import type { ResolvedConfig } from './config.ts';
 import type { Proxy } from './server/proxy.ts';
+/** Whether `HASHSOME_DEBUG` asks for the debug menu: `1` or `true`. */
+export declare function debugRequested(env?: NodeJS.ProcessEnv): boolean;
 /** `proxy` is only passed for `dev`; `build` needs no server settings (its prerender starts a private preview server). */
 export declare function createViteConfig(config: ResolvedConfig, proxy?: Proxy): InlineConfig;

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"}');
@@ -22,11 +26,19 @@ function hashsomeDevServer(proxy, config) {
         },
     };
 }
+/** Whether `HASHSOME_DEBUG` asks for the debug menu: `1` or `true`. */
+export function debugRequested(env = process.env) {
+    const asked = (env['HASHSOME_DEBUG'] ?? '').toLowerCase();
+    return asked === '1' || asked === 'true';
+}
 /** `proxy` is only passed for `dev`; `build` needs no server settings (its prerender starts a private preview server). */
 export function createViteConfig(config, proxy) {
     return {
         root: config.root,
         configFile: join(config.root, 'vite.config.ts'),
+        // `HASHSOME_DEBUG=1` in the environment shows the debug menu: a constant `@hashsome/ui` reads,
+        // replaced in the code Vite serves and builds, the packages' own included.
+        define: { HASHSOME_DEBUG_ON: JSON.stringify(debugRequested()) },
         ...(proxy
             ? {
                 plugins: [hashsomeDevServer(proxy, config)],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashsome/runtime",
-  "version": "0.4.0",
+  "version": "0.6.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.4.0",
-    "@hashsome/ui": "0.4.0",
+    "@hashsome/core": "0.6.0",
+    "@hashsome/ui": "0.6.0",
     "@react-router/dev": "8.4.0",
     "express": "5.2.1",
     "react": "19.3.0",