@webstir-io/webstir-frontend 0.1.40

package/src/html/criticalCss.ts

@@ -0,0 +1,214 @@
+import path from 'node:path';
+import * as cssoModule from 'csso';
+import type { CheerioAPI } from 'cheerio';
+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 as unknown as { default?: typeof cssoModule }).default ?? cssoModule) as typeof cssoModule;
+
+function minifyCriticalCss(css: string): string {
+    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: CheerioAPI,
+    pageName: string,
+    pagesRoot: string,
+    pagesUrlPrefix: string,
+    cssFile?: string
+): Promise<void> {
+    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: CheerioAPI, appCssHref: string): void {
+    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: CheerioAPI): void {
+    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/src/html/htmlSecurity.ts

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import type { CheerioAPI } from 'cheerio';
+
+const HTTP_TIMEOUT_MS = 5000;
+
+export interface SubresourceIntegrityResult {
+    readonly failures: string[];
+}
+
+export async function addSubresourceIntegrity(document: CheerioAPI): Promise<SubresourceIntegrityResult> {
+    const failures: string[] = [];
+    await Promise.all([
+        processScripts(document, failures),
+        processStylesheets(document, failures)
+    ]);
+    return { failures };
+}
+
+async function processScripts(document: CheerioAPI, failures: string[]): Promise<void> {
+    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: CheerioAPI, failures: string[]): Promise<void> {
+    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: string): boolean {
+    return url.startsWith('http://') || url.startsWith('https://') || url.startsWith('//');
+}
+
+async function fetchIntegrity(url: string): Promise<string | null> {
+    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/src/html/lazyLoad.ts

@@ -0,0 +1,30 @@
+import type { CheerioAPI } from 'cheerio';
+
+interface LazyOptions {
+    readonly skip: number;
+}
+
+const DEFAULT_OPTIONS: LazyOptions = {
+    skip: 1
+};
+
+export function applyLazyLoading(document: CheerioAPI, options: LazyOptions = DEFAULT_OPTIONS): void {
+    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/src/html/pageScaffold.ts

@@ -0,0 +1,70 @@
+import path from 'node:path';
+import { FOLDERS, FILES, EXTENSIONS } from '../core/constants.js';
+import { ensureDir, pathExists, writeFile } from '../utils/fs.js';
+
+export interface PageScaffoldOptions {
+    readonly workspaceRoot: string;
+    readonly pageName: string;
+    readonly mode?: 'standard' | 'ssg';
+    readonly paths: {
+        readonly pages: string;
+        readonly app: string;
+    };
+}
+
+export async function createPageScaffold(options: PageScaffoldOptions): Promise<void> {
+    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: Promise<void>[] = [
+        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: string, mode: 'standard' | 'ssg'): string {
+    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: string): string {
+    return `/* ${pageName} Page Styles */
+@import "@app/app.css";
+
+/* Add your page-specific styles here */
+`;
+}
+
+function buildScriptTemplate(): string {
+    return `// Page entry point
+import '../../app/app';
+
+// Add page-specific logic here
+`;
+}

package/src/html/resourceHints.ts

@@ -0,0 +1,91 @@
+import type { CheerioAPI } from 'cheerio';
+import { resolvePageHtmlUrl } from '../utils/pagePaths.js';
+
+export interface ResourceHintResult {
+    readonly added: number;
+    readonly candidates: string[];
+    readonly missingHead: boolean;
+}
+
+export function injectResourceHints(
+    document: CheerioAPI,
+    currentPage: string,
+    pagesUrlPrefix: string,
+    useRootIndex: boolean
+): ResourceHintResult {
+    const head = document('head').first();
+    const pages = [...collectInternalPages(document, currentPage, pagesUrlPrefix)];
+
+    if (head.length === 0) {
+        return {
+            added: 0,
+            candidates: pages,
+            missingHead: pages.length > 0
+        };
+    }
+
+    if (pages.length === 0) {
+        return { added: 0, candidates: [], missingHead: false };
+    }
+
+    for (const page of pages) {
+        const href = resolvePageHtmlUrl(pagesUrlPrefix, page, useRootIndex);
+        head.append(`\n<link rel="prefetch" href="${href}" as="document">`);
+    }
+
+    return { added: pages.length, candidates: pages, missingHead: false };
+}
+
+function collectInternalPages(document: CheerioAPI, currentPage: string, pagesUrlPrefix: string): Set<string> {
+    const pages = new Set<string>();
+    document('a[href]').each((_index, element) => {
+        const href = document(element).attr('href');
+        const pageName = normalizePageName(href, pagesUrlPrefix);
+        if (!pageName || pageName === currentPage) {
+            return;
+        }
+        pages.add(pageName);
+    });
+    return pages;
+}
+
+function normalizePageName(href: string | undefined, pagesUrlPrefix: string): string | null {
+    if (!href || href.length === 0) {
+        return null;
+    }
+
+    const lower = href.toLowerCase();
+    if (lower.startsWith('http://') || lower.startsWith('https://') || lower.startsWith('mailto:') || lower.startsWith('#')) {
+        return null;
+    }
+
+    let path = href.split('#')[0]?.split('?')[0] ?? '';
+    if (path.length === 0) {
+        return null;
+    }
+
+    if (path.startsWith('/')) {
+        path = path.slice(1);
+    }
+
+    const prefix = trimSlashes(pagesUrlPrefix);
+    if (prefix && path.startsWith(`${prefix}/`)) {
+        path = path.slice(prefix.length + 1);
+    }
+
+    if (path.endsWith('/')) {
+        path = path.slice(0, -1);
+    }
+
+    const segments = path.split('/');
+    const candidate = segments[0];
+    if (!candidate) {
+        return null;
+    }
+
+    return candidate;
+}
+
+function trimSlashes(value: string): string {
+    return value.replace(/^\/+|\/+$/g, '');
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './operations.js';
+export * from './config/manifest.js';
+export * from './config/schema.js';
+export * from './types.js';
+export { frontendProvider } from './provider.js';

package/src/modes/ssg/index.ts

@@ -0,0 +1,4 @@
+export { applySsgRouting } from './routing.js';
+export { ensureSsgViewMetadataForPage } from './metadata.js';
+export { assertNoSsgRoutes } from './validation.js';
+export { generateSsgViewData } from './views.js';

package/src/modes/ssg/metadata.ts

@@ -0,0 +1,63 @@
+import path from 'node:path';
+import { readJson, writeJson } from '../../utils/fs.js';
+import type { WorkspaceModuleView, WorkspacePackageJson } from '../../config/workspaceManifest.js';
+
+export interface SsgViewMetadataOptions {
+    readonly workspaceRoot: string;
+    readonly pageName: string;
+}
+
+export async function ensureSsgViewMetadataForPage(options: SsgViewMetadataOptions): Promise<void> {
+    const pkgPath = path.join(options.workspaceRoot, 'package.json');
+    const pkg = (await readJson<WorkspacePackageJson>(pkgPath)) ?? {};
+    const workspaceMode = pkg.webstir?.mode;
+    const isSsgWorkspace = typeof workspaceMode === 'string' && workspaceMode.toLowerCase() === 'ssg';
+    if (isSsgWorkspace) {
+        return;
+    }
+
+    const webstir = pkg.webstir ?? {};
+    const moduleConfig = webstir.moduleManifest ?? {};
+    const existingViews = Array.isArray(moduleConfig.views) ? [...moduleConfig.views] : [];
+
+    const pageName = options.pageName;
+    const isHome = pageName === 'home';
+    const viewName = `${capitalize(pageName)}View`;
+    const viewPath = isHome ? '/' : `/${pageName}`;
+
+    const existingIndex = existingViews.findIndex((view) => view?.name === viewName || view?.path === viewPath);
+    const existing = existingIndex >= 0 ? (existingViews[existingIndex] ?? {}) : {};
+    const nextView: WorkspaceModuleView = {
+        ...existing,
+        name: viewName,
+        path: viewPath,
+        renderMode: 'ssg',
+        staticPaths: [viewPath]
+    };
+
+    if (existingIndex >= 0) {
+        existingViews[existingIndex] = nextView;
+    } else {
+        existingViews.push(nextView);
+    }
+
+    const nextPkg: WorkspacePackageJson = {
+        ...pkg,
+        webstir: {
+            ...webstir,
+            moduleManifest: {
+                ...moduleConfig,
+                views: existingViews
+            }
+        }
+    };
+
+    await writeJson(pkgPath, nextPkg);
+}
+
+function capitalize(value: string): string {
+    if (!value) {
+        return value;
+    }
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}