@webstir-io/webstir 0.1.0

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

@@ -0,0 +1,370 @@
+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 reloadMarkerKey = 'webstir-hmr-last-reload';
+    if (typeof sessionStorage !== 'undefined') {
+        const marker = sessionStorage.getItem(reloadMarkerKey);
+        if (marker) {
+            console.info(`[webstir-hmr] Last update required full reload.${marker}`);
+            sessionStorage.removeItem(reloadMarkerKey);
+        }
+    }
+
+    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}`
+        );
+        if (typeof sessionStorage !== 'undefined') {
+            sessionStorage.setItem(
+                reloadMarkerKey,
+                ` 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/ssg/src/frontend/app/refresh.js

@@ -0,0 +1,163 @@
+const existingEventSource = window.__webstirEventSource;
+const eventSource = existingEventSource instanceof EventSource
+    ? existingEventSource
+    : new EventSource('/sse');
+window.__webstirEventSource = eventSource;
+let isShuttingDown = false;
+let resetTimer;
+let currentStatus;
+const STATUS_STORAGE_KEY = '__webstirDevStatus';
+const STATUS_MAX_AGE_MS = 5000;
+
+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) {
+    currentStatus = status;
+    const handler = statusHandlers[status];
+    if (typeof handler === 'function') {
+        handler(message);
+    }
+
+    if (status === 'connected' || status === 'disconnected') {
+        return;
+    }
+
+    try {
+        sessionStorage.setItem(
+            STATUS_STORAGE_KEY,
+            JSON.stringify({ status, message, timestamp: Date.now() })
+        );
+    } catch {
+        // ignore
+    }
+}
+
+window.__webstirSetDevStatus = applyStatus;
+
+try {
+    const raw = sessionStorage.getItem(STATUS_STORAGE_KEY);
+    if (raw) {
+        sessionStorage.removeItem(STATUS_STORAGE_KEY);
+        const saved = JSON.parse(raw);
+        if (saved && typeof saved === 'object') {
+            const age = Date.now() - (saved.timestamp ?? 0);
+            if (age >= 0 && age <= STATUS_MAX_AGE_MS && typeof saved.status === 'string') {
+                applyStatus(saved.status.trim(), typeof saved.message === 'string' ? saved.message : undefined);
+            }
+        }
+    }
+} catch {
+    // ignore
+}
+
+let loggedConnected = false;
+function markConnected() {
+    if (!loggedConnected) {
+        loggedConnected = true;
+        console.log('SSE connection established.');
+    }
+
+    if (indicator.style.opacity === '0' || currentStatus === 'disconnected') {
+        applyStatus('connected');
+    }
+}
+
+eventSource.onopen = () => {
+    markConnected();
+};
+
+if (eventSource.readyState === EventSource.OPEN) {
+    markConnected();
+}
+
+eventSource.onmessage = (event) => {
+    if (event.data === 'reload') {
+        applyStatus('success');
+        location.reload();
+    } else if (event.data === 'shutdown') {
+        isShuttingDown = true;
+        setDisconnected();
+        eventSource.close();
+    }
+};
+
+eventSource.addEventListener('status', (event) => {
+    applyStatus(String(event.data ?? '').trim());
+});
+
+eventSource.onerror = (error) => {
+    if (!isShuttingDown) {
+        console.error('SSE error:', error);
+        applyStatus('disconnected');
+    }
+};
+
+window.addEventListener('beforeunload', function () {
+    eventSource.close();
+});

package/assets/templates/ssg/src/frontend/app/scripts/components/drawer.ts

@@ -0,0 +1,183 @@
+export type DrawerController = {
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+  isOpen: () => boolean;
+  syncOverlayOffset: () => void;
+  destroy: () => void;
+};
+
+type DrawerOverlayOptions = {
+  headerSelector?: string;
+  target?: HTMLElement;
+  varName?: string;
+};
+
+type DrawerOptions = {
+  root: HTMLElement;
+  openAttribute?: string | null;
+  openClass?: string | null;
+  bodyClass?: string | null;
+  overlay?: DrawerOverlayOptions;
+  isActive?: () => boolean;
+  closeOnEscape?: boolean;
+  closeOnOutside?: boolean;
+  closeSelectors?: string[];
+  trapFocus?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+};
+
+function getFocusable(root: HTMLElement): HTMLElement[] {
+  const selectors = [
+    'button:not([disabled])',
+    'a[href]',
+    'input:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])'
+  ].join(',');
+  return Array.from(root.querySelectorAll<HTMLElement>(selectors))
+    .filter((el) => !el.hasAttribute('hidden') && el.offsetParent !== null);
+}
+
+export function createDrawer(options: DrawerOptions): DrawerController {
+  const openAttribute = options.openAttribute === undefined ? 'data-open' : options.openAttribute;
+  const openClass = options.openClass ?? null;
+  const bodyClass = options.bodyClass ?? null;
+  const overlayVar = options.overlay?.varName ?? '--ws-drawer-top';
+  const overlayTarget = options.overlay?.target ?? options.root;
+  const headerSelector = options.overlay?.headerSelector ?? '.app-header';
+  const isActive = options.isActive ?? (() => true);
+  const closeSelectors = options.closeSelectors?.filter(Boolean).join(',') ?? '';
+
+  let open = false;
+
+  const syncOverlayOffset = () => {
+    if (!options.overlay) {
+      return;
+    }
+
+    const header = document.querySelector<HTMLElement>(headerSelector);
+    if (!header) {
+      return;
+    }
+
+    const rect = header.getBoundingClientRect();
+    const top = Math.max(0, Math.round(rect.bottom));
+    overlayTarget.style.setProperty(overlayVar, `${top}px`);
+  };
+
+  const setOpen = (next: boolean) => {
+    if (open === next) {
+      return;
+    }
+
+    open = next;
+
+    if (openAttribute) {
+      if (open) {
+        options.root.setAttribute(openAttribute, 'true');
+      } else {
+        options.root.removeAttribute(openAttribute);
+      }
+    }
+
+    if (openClass) {
+      options.root.classList.toggle(openClass, open);
+    }
+
+    if (bodyClass) {
+      document.body.classList.toggle(bodyClass, open);
+    }
+
+    if (open) {
+      options.onOpen?.();
+      syncOverlayOffset();
+    } else {
+      options.onClose?.();
+    }
+  };
+
+  const handleKeydown = (event: KeyboardEvent) => {
+    if (!open || !isActive()) {
+      return;
+    }
+
+    if (options.closeOnEscape && event.key === 'Escape') {
+      event.preventDefault();
+      setOpen(false);
+      return;
+    }
+
+    if (options.trapFocus && event.key === 'Tab') {
+      const active = document.activeElement;
+      if (!(active instanceof HTMLElement) || !options.root.contains(active)) {
+        return;
+      }
+
+      const focusable = getFocusable(options.root);
+      if (focusable.length === 0) {
+        return;
+      }
+
+      const currentIndex = focusable.indexOf(active);
+      const nextIndex = event.shiftKey
+        ? (currentIndex <= 0 ? focusable.length - 1 : currentIndex - 1)
+        : (currentIndex === -1 || currentIndex >= focusable.length - 1 ? 0 : currentIndex + 1);
+
+      event.preventDefault();
+      focusable[nextIndex]?.focus();
+    }
+  };
+
+  const handleClick = (event: MouseEvent) => {
+    if (!open || !isActive()) {
+      return;
+    }
+
+    const target = event.target;
+    if (!(target instanceof Element)) {
+      return;
+    }
+
+    if (options.closeOnOutside && !options.root.contains(target)) {
+      setOpen(false);
+      return;
+    }
+
+    if (closeSelectors && target.closest(closeSelectors)) {
+      setOpen(false);
+    }
+  };
+
+  document.addEventListener('keydown', handleKeydown);
+  document.addEventListener('click', handleClick, true);
+
+  return {
+    open: () => {
+      if (!isActive()) {
+        return;
+      }
+      setOpen(true);
+    },
+    close: () => {
+      setOpen(false);
+    },
+    toggle: () => {
+      if (open) {
+        setOpen(false);
+        return;
+      }
+      if (!isActive()) {
+        return;
+      }
+      setOpen(true);
+    },
+    isOpen: () => open,
+    syncOverlayOffset,
+    destroy: () => {
+      document.removeEventListener('keydown', handleKeydown);
+      document.removeEventListener('click', handleClick, true);
+    }
+  };
+}