@webstir-io/webstir 0.1.0

package/assets/templates/full/src/frontend/app/hmr.js

@@ -0,0 +1,355 @@
+if (typeof window === 'undefined' || typeof document === 'undefined') {
+    console.warn('[webstir-hmr] Browser runtime not detected; hot updates disabled.');
+} else if (typeof EventSource === 'undefined') {
+    console.warn('[webstir-hmr] EventSource API unavailable; falling back to full reloads.');
+} else {
+    const eventSource = getOrCreateEventSource();
+    const updateQueue = [];
+    let applyingUpdate = false;
+    let reloadScheduled = false;
+
+    eventSource.addEventListener('hmr', (event) => {
+        if (!event || !event.data) {
+            return;
+        }
+
+        try {
+            const payload = JSON.parse(event.data);
+            enqueueHotUpdate(payload);
+        } catch (error) {
+            console.error('[webstir-hmr] Failed to parse hot update payload.', error);
+            requestReload('payload.parse');
+        }
+    });
+
+    function enqueueHotUpdate(payload) {
+        updateQueue.push(payload);
+        void processQueue();
+    }
+
+    async function processQueue() {
+        if (applyingUpdate || reloadScheduled || updateQueue.length === 0) {
+            return;
+        }
+
+        const payload = updateQueue.shift();
+        if (!payload) {
+            return;
+        }
+
+        applyingUpdate = true;
+        const result = await applyHotUpdate(payload).catch((error) => ({
+            success: false,
+            reason: 'runtime.error',
+            error
+        }));
+        applyingUpdate = false;
+
+        if (!result.success) {
+            requestReload(result.reason, result.error, payload, result.details);
+            return;
+        }
+
+        if (updateQueue.length > 0) {
+            await processQueue();
+        }
+    }
+
+    async function applyHotUpdate(payload) {
+        if (!payload || typeof payload !== 'object') {
+            return { success: false, reason: 'payload.invalid' };
+        }
+
+        if (payload.requiresReload) {
+            return { success: false, reason: 'payload.requiresReload' };
+        }
+
+        const modules = Array.isArray(payload.modules) ? payload.modules : [];
+        const styles = Array.isArray(payload.styles) ? payload.styles : [];
+        const cacheBuster = Date.now().toString(36);
+        const baseContext = {
+            changedFile: payload.changedFile ?? null,
+            modules,
+            styles,
+            cacheBuster,
+            timestamp: Date.now()
+        };
+
+        if (modules.length === 0 && styles.length === 0) {
+            console.info('[webstir-hmr] Received hot update with no changes.');
+            return { success: true };
+        }
+
+        const moduleResult = await applyModuleChanges(modules, baseContext);
+        if (!moduleResult.success) {
+            return moduleResult;
+        }
+
+        const styleResult = await applyStyleChanges(styles, baseContext);
+        if (!styleResult.success) {
+            return styleResult;
+        }
+
+        const changedFile = baseContext.changedFile ?? 'unknown';
+        console.info(`[webstir-hmr] Applied hot update for ${changedFile}.`);
+
+        return { success: true };
+    }
+
+    async function applyModuleChanges(modules, baseContext) {
+        if (modules.length === 0) {
+            return { success: true };
+        }
+
+        for (const asset of modules) {
+            if (!isValidAsset(asset)) {
+                return { success: false, reason: 'module.invalid', details: asset };
+            }
+
+            const context = createModuleContext(baseContext, asset);
+
+            if (!(await invokeDispose(asset, context))) {
+                return { success: false, reason: 'module.dispose', details: asset };
+            }
+
+            const specifier = withCacheBuster(asset.url, baseContext.cacheBuster);
+            let moduleExports;
+            try {
+                moduleExports = await import(specifier);
+            } catch (error) {
+                console.error(`[webstir-hmr] Failed to import module '${asset.url}'.`, error);
+                return { success: false, reason: 'module.import', error, details: asset };
+            }
+
+            if (!(await invokeAccept(moduleExports, context))) {
+                console.warn(`[webstir-hmr] Accept handler declined update for '${asset.relativePath}'.`);
+                return { success: false, reason: 'module.declined', details: asset };
+            }
+        }
+
+        return { success: true };
+    }
+
+    async function applyStyleChanges(styles, baseContext) {
+        if (styles.length === 0) {
+            return { success: true };
+        }
+
+        for (const asset of styles) {
+            if (!isValidAsset(asset)) {
+                return { success: false, reason: 'style.invalid', details: asset };
+            }
+
+            const success = await swapStylesheet(asset, baseContext.cacheBuster);
+            if (!success) {
+                return { success: false, reason: 'style.swap', details: asset };
+            }
+        }
+
+        return { success: true };
+    }
+
+    function createModuleContext(baseContext, asset) {
+        return {
+            changedFile: baseContext.changedFile,
+            modules: baseContext.modules,
+            styles: baseContext.styles,
+            cacheBuster: baseContext.cacheBuster,
+            timestamp: baseContext.timestamp,
+            asset
+        };
+    }
+
+    async function invokeDispose(asset, context) {
+        const handler = window.__webstirDispose;
+        if (typeof handler !== 'function') {
+            return true;
+        }
+
+        try {
+            const result = handler(asset, context);
+            if (isPromise(result)) {
+                await result;
+            }
+            return true;
+        } catch (error) {
+            console.error(`[webstir-hmr] Dispose handler threw for '${asset.relativePath}'.`, error);
+            return false;
+        }
+    }
+
+    async function invokeAccept(moduleExports, context) {
+        const handler = window.__webstirAccept;
+        if (typeof handler !== 'function') {
+            return true;
+        }
+
+        try {
+            const result = handler(moduleExports, context);
+            if (isPromise(result)) {
+                const resolved = await result;
+                return resolved !== false;
+            }
+            return result !== false;
+        } catch (error) {
+            console.error('[webstir-hmr] Accept handler threw.', error);
+            return false;
+        }
+    }
+
+    function swapStylesheet(asset, cacheBuster) {
+        return new Promise((resolve) => {
+            const specifier = withCacheBuster(asset.url, cacheBuster);
+            const existingLinks = Array.from(document.querySelectorAll('link[rel="stylesheet"]'));
+            const target = existingLinks.find((link) => normalizePath(link.href) === normalizePath(asset.url));
+            const replacement = document.createElement('link');
+            replacement.rel = 'stylesheet';
+            replacement.href = specifier;
+
+            replacement.addEventListener('load', () => {
+                if (target && target.parentNode) {
+                    requestAnimationFrame(() => target.remove());
+                }
+                resolve(true);
+            });
+
+            replacement.addEventListener('error', () => {
+                replacement.remove();
+                resolve(false);
+            });
+
+            if (target && target.parentNode) {
+                target.after(replacement);
+            } else {
+                document.head.appendChild(replacement);
+            }
+        });
+    }
+
+    function requestReload(reason, error, payload, details) {
+        if (reloadScheduled) {
+            return;
+        }
+
+        reloadScheduled = true;
+
+        if (error) {
+            console.error('[webstir-hmr] Hot update failed.', error);
+        }
+
+        const changedFile = payload?.changedFile ?? 'unknown';
+        const fallbackReasons = Array.isArray(payload?.fallbackReasons) && payload.fallbackReasons.length > 0
+            ? ` Fallback reasons: ${payload.fallbackReasons.join(', ')}.`
+            : '';
+        console.warn(
+            `[webstir-hmr] Falling back to full reload for ${changedFile}. ` +
+            `Reason: ${reason ?? 'unknown'}.${fallbackReasons}`
+        );
+
+        setStatus('hmr-fallback', 'Hot update fallback – reloading…');
+        notifyFallback(reason, payload, details);
+        updateQueue.length = 0;
+        setTimeout(() => window.location.reload(), 0);
+    }
+
+    function setStatus(status, message) {
+        const setter = window.__webstirSetDevStatus;
+        if (typeof setter === 'function') {
+            try {
+                setter(status, message);
+            } catch (error) {
+                console.debug('[webstir-hmr] Status handler failed.', error);
+            }
+        }
+    }
+
+    function notifyFallback(reason, payload, details) {
+        const handler = window.__webstirOnHmrFallback;
+        if (typeof handler === 'function') {
+            try {
+                handler({ reason, payload, details });
+            } catch (error) {
+                console.debug('[webstir-hmr] Fallback hook threw.', error);
+            }
+        }
+    }
+
+    function readStats(candidate) {
+        if (!candidate || typeof candidate !== 'object') {
+            return null;
+        }
+
+        const hotUpdates = coerceInteger(candidate.hotUpdates);
+        const reloadFallbacks = coerceInteger(candidate.reloadFallbacks);
+
+        if (hotUpdates === null || reloadFallbacks === null) {
+            return null;
+        }
+
+        return {
+            hotUpdates,
+            reloadFallbacks
+        };
+    }
+
+    function coerceInteger(value) {
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            return Math.trunc(value);
+        }
+
+        if (typeof value === 'string') {
+            const parsed = Number.parseInt(value, 10);
+            if (Number.isFinite(parsed)) {
+                return parsed;
+            }
+        }
+
+        return null;
+    }
+
+    function getOrCreateEventSource() {
+        if (window.__webstirEventSource instanceof EventSource) {
+            return window.__webstirEventSource;
+        }
+
+        const source = new EventSource('/sse');
+        window.__webstirEventSource = source;
+        return source;
+    }
+
+    function withCacheBuster(url, cacheBuster) {
+        if (typeof url !== 'string' || url.length === 0) {
+            return url;
+        }
+
+        try {
+            const parsed = new URL(url, window.location.origin);
+            parsed.searchParams.set('hmr', cacheBuster);
+            return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+        } catch {
+            const separator = url.includes('?') ? '&' : '?';
+            return `${url}${separator}hmr=${cacheBuster}`;
+        }
+    }
+
+    function normalizePath(url) {
+        if (typeof url !== 'string') {
+            return '';
+        }
+
+        try {
+            return new URL(url, window.location.origin).pathname;
+        } catch {
+            const index = url.indexOf('?');
+            return index === -1 ? url : url.slice(0, index);
+        }
+    }
+
+    function isValidAsset(asset) {
+        return Boolean(asset && typeof asset.url === 'string' && asset.url.length > 0);
+    }
+
+    function isPromise(value) {
+        return !!value && typeof value.then === 'function';
+    }
+ }

package/assets/templates/full/src/frontend/app/navigation.ts

@@ -0,0 +1,8 @@
+import { startRouter } from './router.js';
+
+export function navigate(url: string) {
+  return startRouter().navigate(url);
+}
+
+export { startRouter } from './router.js';
+export type { RouteHandler, RouteParams } from '@shared/router-types.js';

package/assets/templates/full/src/frontend/app/refresh.js

@@ -0,0 +1,114 @@
+const existingEventSource = window.__webstirEventSource;
+const eventSource = existingEventSource instanceof EventSource
+    ? existingEventSource
+    : new EventSource('/sse');
+window.__webstirEventSource = eventSource;
+let isShuttingDown = false;
+let resetTimer;
+
+const indicator = document.createElement('div');
+indicator.id = 'dev-server-indicator';
+indicator.style.cssText = `
+    position: fixed;
+    bottom: 20px;
+    right: 20px;
+    color: white;
+    padding: 12px 16px;
+    border-radius: 20px;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    font-size: 12px;
+    font-weight: 500;
+    z-index: 10000;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+    opacity: 0;
+    transition: opacity 0.3s ease;
+`;
+
+document.body.appendChild(indicator);
+
+function updateIndicator(background, text, shouldReset = false) {
+    indicator.style.opacity = '1';
+    indicator.style.background = background;
+    indicator.textContent = text;
+
+    if (resetTimer) {
+        clearTimeout(resetTimer);
+        resetTimer = undefined;
+    }
+
+    if (shouldReset) {
+        resetTimer = setTimeout(setConnected, 1500);
+    }
+}
+
+function setConnected(message) {
+    updateIndicator('#4CAF50', message ?? '● Dev Server Connected');
+}
+
+function setDisconnected(message) {
+    updateIndicator('#f44336', message ?? 'Dev Server Disconnected');
+}
+
+function setBuilding(message) {
+    updateIndicator('#FF9800', message ?? '● Rebuilding…');
+}
+
+function setBuildSuccess(message) {
+    updateIndicator('#4CAF50', message ?? '● Rebuild Complete', true);
+}
+
+function setBuildFailure(message) {
+    updateIndicator('#f44336', message ?? '● Build Failed');
+}
+
+function setHmrFallback(message) {
+    updateIndicator('#FF5722', message ?? '● Reloading (HMR fallback)…');
+}
+
+const statusHandlers = {
+    connected: setConnected,
+    disconnected: setDisconnected,
+    building: setBuilding,
+    success: setBuildSuccess,
+    error: setBuildFailure,
+    'hmr-fallback': setHmrFallback
+};
+
+function applyStatus(status, message) {
+    const handler = statusHandlers[status];
+    if (typeof handler === 'function') {
+        handler(message);
+    }
+}
+
+window.__webstirSetDevStatus = applyStatus;
+
+eventSource.onopen = () => {
+    console.log('SSE connection established.');
+    applyStatus('connected');
+};
+
+eventSource.onmessage = (event) => {
+    if (event.data === 'reload') {
+        location.reload();
+    } else if (event.data === 'shutdown') {
+        isShuttingDown = true;
+        setDisconnected();
+        eventSource.close();
+    }
+};
+
+eventSource.addEventListener('status', (event) => {
+    applyStatus(event.data);
+});
+
+eventSource.onerror = (error) => {
+    if (!isShuttingDown) {
+        console.error('SSE error:', error);
+        applyStatus('disconnected');
+    }
+};
+
+window.addEventListener('beforeunload', function () {
+    eventSource.close();
+});

package/assets/templates/full/src/frontend/app/router.ts

@@ -0,0 +1,126 @@
+import type { RouteHandler, RouteParams, RoutingMetadata } from '@shared/router-types.js';
+
+export class Router {
+  private routes = new Map<string, RouteHandler>();
+  private currentHandler: RouteHandler | null = null;
+  
+  constructor() {
+    this.loadRoutingMetadataFromDom();
+    this.setupBrowserNavigation();
+    this.interceptLinkClicks();
+  }
+  
+  registerRoute(path: string, handler: RouteHandler) {
+    this.routes.set(path, handler);
+  }
+  
+  async navigate(url: string) {
+    const targetPath = new URL(url, window.location.origin).pathname;
+    const routeHandler = this.routes.get(targetPath);
+    
+    if (!routeHandler) {
+      window.location.href = url;
+      return;
+    }
+    
+    window.history.pushState({}, '', url);
+    await this.handleRouteChange();
+  }
+  
+  private loadRoutingMetadataFromDom() {
+    const metadataElement = document.getElementById('app-routing-metadata');
+    if (!metadataElement?.textContent) return;
+    
+    try {
+      const metadata: RoutingMetadata = JSON.parse(metadataElement.textContent);
+    } catch (error) {
+      console.warn('Failed to parse routing metadata:', error);
+    }
+  }
+  
+  private setupBrowserNavigation() {
+    window.addEventListener('popstate', () => {
+      this.handleRouteChange();
+    });
+  }
+  
+  private interceptLinkClicks() {
+    document.addEventListener('click', (event) => {
+      const target = event.target as EventTarget | null;
+
+      // Only handle element targets; respect modifier keys and prior handlers
+      if (!(target instanceof Element)) return;
+      if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+
+      const clickedLink = target.closest('a');
+      if (!clickedLink || !this.shouldInterceptLink(clickedLink as HTMLAnchorElement)) return;
+
+      event.preventDefault();
+      this.navigate((clickedLink as HTMLAnchorElement).href);
+    });
+  }
+  
+  private async handleRouteChange() {
+    const currentPath = window.location.pathname;
+    const routeParams = this.extractQueryParams();
+    
+    await this.callOnLeaveHandler();
+    
+    const newHandler = this.routes.get(currentPath);
+    if (newHandler) {
+      this.currentHandler = newHandler;
+      await this.callOnEnterHandler(newHandler, routeParams);
+    }
+  }
+  
+  private async callOnLeaveHandler() {
+    if (this.currentHandler?.onLeave) {
+      await this.currentHandler.onLeave();
+    }
+  }
+  
+  private async callOnEnterHandler(handler: RouteHandler, params: RouteParams) {
+    if (handler.onEnter) {
+      await handler.onEnter(params);
+    }
+  }
+  
+  private shouldInterceptLink(link: HTMLAnchorElement): boolean {
+    const isExternalLink = link.origin !== window.location.origin;
+    const isDownloadLink = link.hasAttribute('download');
+    const opensInNewTab = link.getAttribute('target') === '_blank';
+    const hasRouteHandler = this.routes.has(link.pathname);
+    
+    return !isExternalLink && !isDownloadLink && !opensInNewTab && hasRouteHandler;
+  }
+  
+  private extractQueryParams(): RouteParams {
+    const params: RouteParams = {};
+    const urlSearchParams = new URLSearchParams(window.location.search);
+    
+    urlSearchParams.forEach((value, key) => {
+      params[key] = value;
+    });
+    
+    return params;
+  }
+}
+
+let singleton: Router | null = null;
+
+export function startRouter(): Router {
+  if (!singleton) {
+    singleton = new Router();
+  }
+  return singleton;
+}
+
+export function getRouter(): Router | null {
+  return singleton;
+}
+
+export function navigate(url: string) {
+  return startRouter().navigate(url);
+}
+
+export type { RouteHandler, RouteParams };

package/assets/templates/full/src/frontend/app/styles/base.css

@@ -0,0 +1,2 @@
+/* Base styles placeholder (extend as needed) */
+/* This file can be extended by projects if desired. */

package/assets/templates/full/src/frontend/app/styles/reset.css

@@ -0,0 +1,48 @@
+/* Basic CSS Reset */
+*, *::before, *::after {
+  box-sizing: border-box;
+}
+
+html, body, h1, h2, h3, h4, h5, h6, p, figure, blockquote, dl, dd {
+  margin: 0;
+}
+
+ul[role='list'], ol[role='list'] {
+  list-style: none;
+}
+
+html:focus-within {
+  scroll-behavior: smooth;
+}
+
+body {
+  min-height: 100vh;
+  text-rendering: optimizeSpeed;
+  line-height: 1.5;
+}
+
+a:not([class]) {
+  text-decoration-skip-ink: auto;
+}
+
+img, picture {
+  max-width: 100%;
+  display: block;
+}
+
+input, button, textarea, select {
+  font: inherit;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  html:focus-within {
+    scroll-behavior: auto;
+  }
+
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}

package/assets/templates/full/src/frontend/pages/home/index.css

@@ -0,0 +1,21 @@
+/* Index Page Styles */
+@import "@app/app.css";
+
+.hero {
+    display: grid;
+    gap: 2rem;
+    align-items: center;
+    text-align: center;
+}
+
+.hero h1 {
+    font-size: clamp(2.5rem, 6vw, 4rem);
+    font-weight: 600;
+}
+
+.hero p {
+    font-size: 1.125rem;
+    color: var(--text-secondary);
+    margin: 0 auto;
+    max-width: 42ch;
+}

package/assets/templates/full/src/frontend/pages/home/index.html

@@ -0,0 +1,10 @@
+<head>
+    <title>Home</title>
+    <link rel="stylesheet" href="index.css" />
+    <script type="module" src="index.js" async></script>
+</head>
+<body>
+    <main>
+        Home
+    </main>
+</body>

package/assets/templates/full/src/frontend/pages/home/index.ts

@@ -0,0 +1,18 @@
+// TypeScript file for index page
+
+import { registerHotModule } from '../../app/app';
+
+const main = document.querySelector('main');
+if (main) {
+  main.dataset.hmrRendered = String(Date.now());
+}
+
+registerHotModule(import.meta.url, {
+  accept: (_, context) => {
+    console.info('[webstir-hmr] Home page accepted update for', context.asset?.relativePath ?? 'unknown module');
+    return true;
+  },
+  dispose: (context) => {
+    console.info('[webstir-hmr] Preparing to update', context.asset?.relativePath ?? 'home page module');
+  }
+});