@webstir-io/webstir-frontend 0.1.40

package/dist/core/constants.js

@@ -0,0 +1,70 @@
+export const FOLDERS = {
+    src: 'src',
+    build: 'build',
+    dist: 'dist',
+    webstir: '.webstir',
+    tests: 'tests',
+    frontend: 'frontend',
+    backend: 'backend',
+    shared: 'shared',
+    types: 'types',
+    app: 'app',
+    pages: 'pages',
+    styles: 'styles',
+    scripts: 'scripts',
+    images: 'images',
+    fonts: 'fonts',
+    media: 'media',
+    chunks: 'chunks',
+    home: 'home',
+    nodeModules: 'node_modules',
+    seed: 'seed',
+    demo: 'demo',
+    temp: 'temp'
+};
+export const FILES = {
+    packageJson: 'package.json',
+    packageLockJson: 'package-lock.json',
+    tsBuildInfo: '.tsbuildinfo',
+    baseTsConfigJson: 'base.tsconfig.json',
+    manifestJson: 'manifest.json',
+    test: '.test',
+    index: 'index',
+    indexHtml: 'index.html',
+    refreshJs: 'refresh.js',
+    hmrJs: 'hmr.js',
+    robotsTxt: 'robots.txt'
+};
+export const EXTENSIONS = {
+    html: '.html',
+    css: '.css',
+    br: '.br',
+    gz: '.gz',
+    dts: '.d.ts',
+    ts: '.ts',
+    js: '.js',
+    map: '.map',
+    png: '.png',
+    jpg: '.jpg',
+    jpeg: '.jpeg',
+    gif: '.gif',
+    svg: '.svg',
+    webp: '.webp',
+    avif: '.avif',
+    ico: '.ico',
+    woff: '.woff',
+    woff2: '.woff2',
+    ttf: '.ttf',
+    otf: '.otf',
+    eot: '.eot',
+    mp3: '.mp3',
+    m4a: '.m4a',
+    wav: '.wav',
+    ogg: '.ogg',
+    mp4: '.mp4',
+    webm: '.webm',
+    mov: '.mov'
+};
+export const FILE_NAMES = {
+    htmlAppTemplate: 'app.html'
+};

package/dist/core/diagnostics.d.ts

@@ -0,0 +1,15 @@
+export type DiagnosticSeverity = 'info' | 'warning' | 'error';
+export interface DiagnosticEvent {
+    readonly code: string;
+    readonly kind: string;
+    readonly stage: string;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    readonly data?: Record<string, unknown>;
+    readonly suggestion?: string;
+}
+export interface DiagnosticPayload extends DiagnosticEvent {
+    readonly type: 'diagnostic';
+}
+export declare const STRUCTURED_DIAGNOSTIC_PREFIX = "WEBSTIR_DIAGNOSTIC ";
+export declare function emitDiagnostic(event: DiagnosticEvent): void;

package/dist/core/diagnostics.js

@@ -0,0 +1,21 @@
+export const STRUCTURED_DIAGNOSTIC_PREFIX = 'WEBSTIR_DIAGNOSTIC ';
+export function emitDiagnostic(event) {
+    const payload = {
+        type: 'diagnostic',
+        ...event
+    };
+    const logMessage = `[webstir-frontend][${event.code}] ${event.message}`;
+    switch (event.severity) {
+        case 'error':
+            console.error(logMessage);
+            break;
+        case 'warning':
+            console.warn(logMessage);
+            break;
+        default:
+            console.info(logMessage);
+            break;
+    }
+    const serialized = JSON.stringify(payload);
+    console.log(`${STRUCTURED_DIAGNOSTIC_PREFIX}${serialized}`);
+}

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from './constants.js';
+export * from './diagnostics.js';
+export * from './pages.js';

package/dist/core/index.js

@@ -0,0 +1,3 @@
+export * from './constants.js';
+export * from './diagnostics.js';
+export * from './pages.js';

package/dist/core/pages.d.ts

@@ -0,0 +1,6 @@
+export interface PageInfo {
+    readonly name: string;
+    readonly directory: string;
+}
+export declare function getPages(root: string): Promise<PageInfo[]>;
+export declare function getPageDirectories(root: string): Promise<PageInfo[]>;

package/dist/core/pages.js

@@ -0,0 +1,23 @@
+import path from 'node:path';
+import { glob } from 'glob';
+import { pathExists } from '../utils/fs.js';
+export async function getPages(root) {
+    const directories = await getPageDirectories(root);
+    return directories.map((entry) => ({
+        name: entry.name,
+        directory: entry.directory
+    }));
+}
+export async function getPageDirectories(root) {
+    if (!(await pathExists(root))) {
+        return [];
+    }
+    const entries = await glob('*/', { cwd: root, absolute: false, withFileTypes: false });
+    return entries.map((entry) => {
+        const name = entry.endsWith('/') ? entry.slice(0, -1) : entry;
+        return {
+            name,
+            directory: path.join(root, name)
+        };
+    });
+}

package/dist/hooks.d.ts

@@ -0,0 +1,19 @@
+import type { FrontendConfig } from './types.js';
+import type { PipelineMode } from './pipeline.js';
+export interface HookContext {
+    readonly config: FrontendConfig;
+    readonly mode: PipelineMode;
+    readonly workspaceRoot: string;
+    readonly builderName?: string;
+    readonly changedFile?: string;
+}
+export type HookHandler = (context: HookContext) => unknown | Promise<unknown>;
+export interface ResolvedHooks {
+    readonly pipelineBefore: HookHandler[];
+    readonly pipelineAfter: HookHandler[];
+    readonly builderBefore: Map<string, HookHandler[]>;
+    readonly builderAfter: Map<string, HookHandler[]>;
+}
+export declare function loadHooks(workspaceRoot: string, cacheBust: boolean): Promise<ResolvedHooks>;
+export declare function createHookContext(config: FrontendConfig, mode: PipelineMode, changedFile: string | undefined, builderName?: string): HookContext;
+export declare function executeHooks(label: string, handlers: HookHandler[], context: HookContext): Promise<void>;

package/dist/hooks.js

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+const CONFIG_CANDIDATES = ['webstir.config.mjs', 'webstir.config.js', 'webstir.config.cjs'];
+const EMPTY_HOOKS = {
+    pipelineBefore: [],
+    pipelineAfter: [],
+    builderBefore: new Map(),
+    builderAfter: new Map()
+};
+export async function loadHooks(workspaceRoot, cacheBust) {
+    const configPath = findConfigPath(workspaceRoot);
+    if (!configPath) {
+        return EMPTY_HOOKS;
+    }
+    let moduleConfig;
+    try {
+        const fileUrl = pathToFileURL(configPath).href;
+        const url = cacheBust ? `${fileUrl}?update=${Date.now()}` : fileUrl;
+        moduleConfig = await import(url);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to load hooks from ${configPath}: ${message}`);
+    }
+    const exported = moduleConfig?.default ?? moduleConfig;
+    if (!exported || typeof exported !== 'object') {
+        return EMPTY_HOOKS;
+    }
+    const rawHooks = exported.hooks ?? exported;
+    if (!rawHooks || typeof rawHooks !== 'object') {
+        return EMPTY_HOOKS;
+    }
+    return normalizeHooks(rawHooks, configPath);
+}
+export function createHookContext(config, mode, changedFile, builderName) {
+    return {
+        config,
+        mode,
+        workspaceRoot: config.paths.workspace,
+        builderName,
+        changedFile
+    };
+}
+export async function executeHooks(label, handlers, context) {
+    for (const handler of handlers) {
+        try {
+            await handler(context);
+        }
+        catch (error) {
+            throw wrapHookError(label, error);
+        }
+    }
+}
+function wrapHookError(label, error) {
+    if (error instanceof Error) {
+        error.message = `[hook:${label}] ${error.message}`;
+        return error;
+    }
+    return new Error(`[hook:${label}] ${String(error)}`);
+}
+function normalizeHooks(raw, configPath) {
+    const pipeline = raw.pipeline ?? {};
+    const pipelineBefore = normalizeHandlerSet(pipeline.beforeAll, `${configPath} pipeline.beforeAll`);
+    const pipelineAfter = normalizeHandlerSet(pipeline.afterAll, `${configPath} pipeline.afterAll`);
+    const builderBefore = new Map();
+    const builderAfter = new Map();
+    const builders = raw.builders ?? {};
+    for (const [name, value] of Object.entries(builders)) {
+        if (typeof value === 'function' || Array.isArray(value)) {
+            builderBefore.set(name, normalizeHandlerSet(value, `${configPath} builders.${name}`));
+            continue;
+        }
+        if (!value || typeof value !== 'object') {
+            continue;
+        }
+        const before = normalizeHandlerSet(value.before, `${configPath} builders.${name}.before`);
+        const after = normalizeHandlerSet(value.after, `${configPath} builders.${name}.after`);
+        if (before.length > 0) {
+            builderBefore.set(name, before);
+        }
+        if (after.length > 0) {
+            builderAfter.set(name, after);
+        }
+    }
+    return {
+        pipelineBefore,
+        pipelineAfter,
+        builderBefore,
+        builderAfter
+    };
+}
+function normalizeHandlerSet(value, label) {
+    if (value === undefined) {
+        return [];
+    }
+    const handlers = Array.isArray(value) ? value : [value];
+    const normalized = [];
+    for (const handler of handlers) {
+        if (typeof handler !== 'function') {
+            throw new Error(`Invalid hook handler in ${label}; expected function`);
+        }
+        normalized.push(handler);
+    }
+    return normalized;
+}
+function findConfigPath(workspaceRoot) {
+    for (const candidate of CONFIG_CANDIDATES) {
+        const fullPath = path.join(workspaceRoot, candidate);
+        if (fs.existsSync(fullPath)) {
+            return fullPath;
+        }
+    }
+    return undefined;
+}

package/dist/html/criticalCss.d.ts

@@ -0,0 +1,4 @@
+import type { CheerioAPI } from 'cheerio';
+export declare function inlineCriticalCss(document: CheerioAPI, pageName: string, pagesRoot: string, pagesUrlPrefix: string, cssFile?: string): Promise<void>;
+export declare function ensureAppShellCriticalCss(document: CheerioAPI, appCssHref: string): void;
+export declare function ensureDocsShellCriticalCss(document: CheerioAPI): void;

package/dist/html/criticalCss.js

@@ -0,0 +1,192 @@
+import path from 'node:path';
+import * as cssoModule from 'csso';
+import { EXTENSIONS } from '../core/constants.js';
+import { pathExists, readFile, stat } from '../utils/fs.js';
+import { resolvePageAssetUrl } from '../utils/pagePaths.js';
+const INLINE_THRESHOLD_BYTES = 6 * 1024;
+const csso = (cssoModule.default ?? cssoModule);
+function minifyCriticalCss(css) {
+    return csso.minify(css).css;
+}
+const APP_SHELL_CRITICAL_CSS = minifyCriticalCss(`
+@layer tokens {
+    :root {
+        --ws-header-control-size: 2.6rem;
+        --ws-header-block-padding: 0.75rem;
+        --ws-header-sticky-offset: calc(var(--ws-header-control-size) + (var(--ws-header-block-padding) * 2) + 1px);
+        --ws-font-sans: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+            Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", Arial, sans-serif;
+    }
+}
+
+@layer reset {
+    *,
+    *::before,
+    *::after {
+        box-sizing: border-box;
+    }
+}
+
+@layer base {
+    html,
+    body {
+        height: 100%;
+    }
+
+    body {
+        margin: 0;
+        font-family: var(--ws-font-sans);
+        font-size: 16px;
+        line-height: 1.6;
+        padding-top: var(--ws-header-sticky-offset, 0px);
+    }
+
+    h1,
+    h2,
+    h3,
+    h4,
+    h5,
+    h6 {
+        line-height: 1.25;
+        margin: 0 0 0.5rem 0;
+    }
+
+    h1 {
+        font-size: clamp(2rem, 4vw, 2.75rem);
+        letter-spacing: -0.02em;
+    }
+
+    h2 {
+        font-size: clamp(1.5rem, 2.5vw, 2rem);
+        letter-spacing: -0.01em;
+    }
+
+    h3 {
+        font-size: 1.35rem;
+    }
+
+    p {
+        margin: 0 0 1rem 0;
+    }
+}
+
+@layer components {
+    .app-header {
+        position: fixed;
+        top: 0;
+        left: 0;
+        right: 0;
+        height: calc(var(--ws-header-sticky-offset) - 1px);
+    }
+}
+`.trim());
+const DOCS_SHELL_CRITICAL_CSS = minifyCriticalCss(`
+@layer overrides {
+    .docs-layout {
+        --ws-docs-sidebar-width: clamp(14rem, 20vw, 18rem);
+        --ws-docs-layout-padding: 48px 0 96px;
+        --ws-container: 100%;
+        padding: var(--ws-docs-layout-padding);
+        padding-top: 0;
+    }
+
+    .docs-layout__inner {
+        display: grid;
+        grid-template-columns: var(--ws-docs-sidebar-width, 16rem) minmax(0, 1fr);
+        gap: var(--ws-space-6, 1.5rem);
+        align-items: start;
+        padding-inline: 0;
+        margin-inline: 0;
+        min-height: calc(100vh - var(--ws-header-sticky-offset, 0px));
+    }
+
+    .docs-main {
+        width: 100%;
+        max-width: var(--ws-article, 72ch);
+        margin-inline: 0;
+        min-width: 0;
+        grid-column: 2;
+        padding-top: var(--ws-space-5, 1.25rem);
+        padding-right: var(--ws-space-6, 1.5rem);
+    }
+
+    @media (max-width: 40rem) {
+        .docs-layout__inner {
+            grid-template-columns: minmax(0, 1fr);
+            padding-left: max(var(--ws-container-pad, 1rem), env(safe-area-inset-left));
+            padding-right: max(var(--ws-container-pad, 1rem), env(safe-area-inset-right));
+        }
+
+        .docs-main {
+            max-width: none;
+            justify-self: stretch;
+            grid-column: auto;
+            padding-top: var(--ws-space-4, 1rem);
+            padding-right: 0;
+        }
+    }
+}
+`.trim());
+export async function inlineCriticalCss(document, pageName, pagesRoot, pagesUrlPrefix, cssFile) {
+    if (!cssFile) {
+        return;
+    }
+    const cssPath = path.join(pagesRoot, pageName, cssFile);
+    if (!(await pathExists(cssPath))) {
+        return;
+    }
+    const info = await stat(cssPath).catch(() => null);
+    if (!info || !info.isFile() || info.size > INLINE_THRESHOLD_BYTES) {
+        return;
+    }
+    const cssContent = minifyCriticalCss(await readFile(cssPath));
+    const head = document('head').first();
+    if (head.length === 0) {
+        return;
+    }
+    const href = resolvePageAssetUrl(pagesUrlPrefix, pageName, cssFile);
+    document(`link[href="${href}"]`).remove();
+    if (cssFile.endsWith(EXTENSIONS.css)) {
+        document(`link[rel="preload"][href="${href}"]`).remove();
+    }
+    head.append(`\n<style data-critical>\n${cssContent}\n</style>\n`);
+}
+export function ensureAppShellCriticalCss(document, appCssHref) {
+    const head = document('head').first();
+    if (head.length === 0) {
+        return;
+    }
+    const existing = head.find('style[data-critical="app"]').first();
+    if (existing.length > 0) {
+        return;
+    }
+    const stylesheet = document(`link[rel="stylesheet"][href="${appCssHref}"]`).first();
+    const styleTag = `<style data-critical="app">\n${APP_SHELL_CRITICAL_CSS}\n</style>`;
+    if (stylesheet.length > 0) {
+        stylesheet.before(styleTag);
+    }
+    else {
+        head.append(styleTag);
+    }
+}
+export function ensureDocsShellCriticalCss(document) {
+    const head = document('head').first();
+    if (head.length === 0) {
+        return;
+    }
+    const existing = head.find('style[data-critical="docs"]').first();
+    if (existing.length > 0) {
+        return;
+    }
+    const docsStylesheet = document('link[rel="stylesheet"]').filter((_, element) => {
+        const href = document(element).attr('href');
+        return typeof href === 'string' && href.includes('/docs/');
+    }).first();
+    const styleTag = `<style data-critical="docs">\n${DOCS_SHELL_CRITICAL_CSS}\n</style>`;
+    if (docsStylesheet.length > 0) {
+        docsStylesheet.before(styleTag);
+    }
+    else {
+        head.append(styleTag);
+    }
+}

package/dist/html/htmlSecurity.d.ts

@@ -0,0 +1,5 @@
+import type { CheerioAPI } from 'cheerio';
+export interface SubresourceIntegrityResult {
+    readonly failures: string[];
+}
+export declare function addSubresourceIntegrity(document: CheerioAPI): Promise<SubresourceIntegrityResult>;

package/dist/html/htmlSecurity.js

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+const HTTP_TIMEOUT_MS = 5000;
+export async function addSubresourceIntegrity(document) {
+    const failures = [];
+    await Promise.all([
+        processScripts(document, failures),
+        processStylesheets(document, failures)
+    ]);
+    return { failures };
+}
+async function processScripts(document, failures) {
+    const scripts = document('script[src]').toArray();
+    await Promise.all(scripts.map(async (element) => {
+        const script = document(element);
+        const src = script.attr('src');
+        if (!src || !isExternal(src) || script.attr('integrity')) {
+            return;
+        }
+        const sri = await fetchIntegrity(src);
+        if (!sri) {
+            failures.push(src);
+            return;
+        }
+        script.attr('integrity', sri);
+        if (!script.attr('crossorigin')) {
+            script.attr('crossorigin', 'anonymous');
+        }
+    }));
+}
+async function processStylesheets(document, failures) {
+    const links = document('link[rel="stylesheet"][href]').toArray();
+    await Promise.all(links.map(async (element) => {
+        const link = document(element);
+        const href = link.attr('href');
+        if (!href || !isExternal(href) || link.attr('integrity')) {
+            return;
+        }
+        const sri = await fetchIntegrity(href);
+        if (!sri) {
+            failures.push(href);
+            return;
+        }
+        link.attr('integrity', sri);
+        if (!link.attr('crossorigin')) {
+            link.attr('crossorigin', 'anonymous');
+        }
+    }));
+}
+function isExternal(url) {
+    return url.startsWith('http://') || url.startsWith('https://') || url.startsWith('//');
+}
+async function fetchIntegrity(url) {
+    try {
+        const normalizedUrl = url.startsWith('//') ? `https:${url}` : url;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
+        try {
+            const response = await fetch(normalizedUrl, { signal: controller.signal });
+            if (!response.ok) {
+                return null;
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            const hash = createHash('sha384').update(Buffer.from(arrayBuffer)).digest('base64');
+            return `sha384-${hash}`;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch {
+        return null;
+    }
+}

package/dist/html/lazyLoad.d.ts

@@ -0,0 +1,6 @@
+import type { CheerioAPI } from 'cheerio';
+interface LazyOptions {
+    readonly skip: number;
+}
+export declare function applyLazyLoading(document: CheerioAPI, options?: LazyOptions): void;
+export {};

package/dist/html/lazyLoad.js

@@ -0,0 +1,21 @@
+const DEFAULT_OPTIONS = {
+    skip: 1
+};
+export function applyLazyLoading(document, options = DEFAULT_OPTIONS) {
+    const { skip } = options;
+    let index = 0;
+    document('img').each((_i, element) => {
+        const img = document(element);
+        if (img.attr('loading')) {
+            return;
+        }
+        index += 1;
+        if (index <= skip) {
+            return;
+        }
+        img.attr('loading', 'lazy');
+        if (!img.attr('fetchpriority')) {
+            img.attr('fetchpriority', 'low');
+        }
+    });
+}

package/dist/html/pageScaffold.d.ts

@@ -0,0 +1,10 @@
+export interface PageScaffoldOptions {
+    readonly workspaceRoot: string;
+    readonly pageName: string;
+    readonly mode?: 'standard' | 'ssg';
+    readonly paths: {
+        readonly pages: string;
+        readonly app: string;
+    };
+}
+export declare function createPageScaffold(options: PageScaffoldOptions): Promise<void>;

package/dist/html/pageScaffold.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import { FILES, EXTENSIONS } from '../core/constants.js';
+import { ensureDir, pathExists, writeFile } from '../utils/fs.js';
+export async function createPageScaffold(options) {
+    const pageDir = path.join(options.paths.pages, options.pageName);
+    if (await pathExists(pageDir)) {
+        throw new Error(`Page '${options.pageName}' already exists.`);
+    }
+    await ensureDir(pageDir);
+    const mode = options.mode ?? 'standard';
+    const writes = [
+        writeFile(path.join(pageDir, `${FILES.index}${EXTENSIONS.html}`), buildHtmlTemplate(options.pageName, mode)),
+        writeFile(path.join(pageDir, `${FILES.index}${EXTENSIONS.css}`), buildCssTemplate(options.pageName))
+    ];
+    if (mode === 'standard') {
+        writes.push(writeFile(path.join(pageDir, `${FILES.index}${EXTENSIONS.ts}`), buildScriptTemplate()));
+    }
+    await Promise.all(writes);
+}
+function buildHtmlTemplate(pageName, mode) {
+    const script = mode === 'standard'
+        ? `    <script type="module" src="${FILES.index}${EXTENSIONS.js}" async></script>`
+        : `    <!-- Add ${FILES.index}${EXTENSIONS.ts} to enable JS on this page. -->`;
+    return `<head>
+    <meta charset="utf-8">
+    <title>${pageName}</title>
+    <link rel="stylesheet" href="${FILES.index}${EXTENSIONS.css}">
+</head>
+<body>
+    <main>
+        <h1>${pageName}</h1>
+        <p>Content for the ${pageName} page.</p>
+    </main>
+${script}
+</body>
+`;
+}
+function buildCssTemplate(pageName) {
+    return `/* ${pageName} Page Styles */
+@import "@app/app.css";
+
+/* Add your page-specific styles here */
+`;
+}
+function buildScriptTemplate() {
+    return `// Page entry point
+import '../../app/app';
+
+// Add page-specific logic here
+`;
+}

package/dist/html/resourceHints.d.ts

@@ -0,0 +1,7 @@
+import type { CheerioAPI } from 'cheerio';
+export interface ResourceHintResult {
+    readonly added: number;
+    readonly candidates: string[];
+    readonly missingHead: boolean;
+}
+export declare function injectResourceHints(document: CheerioAPI, currentPage: string, pagesUrlPrefix: string, useRootIndex: boolean): ResourceHintResult;