@webstir-io/webstir 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# webstir
+
+Bun-first CLI for Webstir.
+
+Primary command name: `webstir`
+
+Current command surface:
+
+- `init`
+- `refresh`
+- `repair`
+- `enable`
+- `add-page`
+- `add-test`
+- `add-route`
+- `add-job`
+- `backend-inspect`
+- `build`
+- `publish`
+- `watch`
+- `test`
+- `smoke`
+
+Repo-local use:
+
+```bash
+bun run webstir -- --help
+bun run webstir -- build --workspace /absolute/path/to/workspace
+```
+
+Local machine install for external workspaces:
+
+```bash
+cd /Users/iamce/dev/webstir-io/webstir/orchestrators/bun
+bun link
+
+mkdir -p ~/tmp/webstir-check
+cd ~/tmp/webstir-check
+bun link @webstir-io/webstir
+
+./node_modules/.bin/webstir init ssg site
+cd site
+bun install
+../node_modules/.bin/webstir build --workspace "$PWD"
+```
+
+For a tarball install, pack the CLI locally with:
+
+```bash
+cd /Users/iamce/dev/webstir-io/webstir/orchestrators/bun
+bun run pack:local
+```
+
+For a machine-local standalone tarball that bundles the current Webstir packages:
+
+```bash
+cd /Users/iamce/dev/webstir-io/webstir/orchestrators/bun
+bun run pack:standalone
+
+mkdir -p ~/tmp/webstir-standalone
+cd ~/tmp/webstir-standalone
+printf '{"name":"webstir-local","private":true}\n' > package.json
+bun add /Users/iamce/dev/webstir-io/webstir/orchestrators/bun/artifacts/webstir-io-webstir-0.1.0-standalone.tgz
+
+./node_modules/.bin/webstir init ssg site
+cd site
+bun install
+../node_modules/.bin/webstir build --workspace "$PWD"
+```

package/assets/features/client_nav/client_nav.ts

@@ -0,0 +1,469 @@
+export {};
+
+/**
+ * Minimal PJAX-style navigation: swaps the <main> content, updates title/URL,
+ * and restores scroll/focus.
+ *
+ * Opt out per-link with:
+ * - data-no-client-nav
+ * - data-client-nav="off"
+ */
+export function enableClientNav(): void {
+    document.addEventListener('click', async (event) => {
+        const target = event.target;
+        if (!(target instanceof Element)) {
+            return;
+        }
+        if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+            return;
+        }
+
+        const link = target.closest('a');
+        if (!link || !(link instanceof HTMLAnchorElement)) {
+            return;
+        }
+
+        const setting = link.getAttribute('data-client-nav');
+        const optOut = link.hasAttribute('data-no-client-nav')
+            || setting === 'off'
+            || setting === 'false';
+        if (optOut) {
+            return;
+        }
+
+        const isExternal = link.origin !== window.location.origin;
+        const opensInNewTab = link.getAttribute('target') === '_blank';
+        const isDownload = link.hasAttribute('download');
+        if (isExternal || opensInNewTab || isDownload) {
+            return;
+        }
+
+        const isSameDocumentAnchor = link.hash
+            && link.pathname === window.location.pathname
+            && link.search === window.location.search;
+        if (isSameDocumentAnchor) {
+            return;
+        }
+
+        event.preventDefault();
+        await renderUrl(link.href, { pushHistory: true });
+    });
+
+    window.addEventListener('popstate', async () => {
+        await renderUrl(window.location.href, { pushHistory: false });
+    });
+}
+
+let activeRequestId = 0;
+let activeController: AbortController | null = null;
+const DYNAMIC_ATTR = 'data-webstir-dynamic';
+const DYNAMIC_VALUE = 'client-nav';
+const BASE_PATH = resolveBasePath();
+
+function resolveBasePath(): string {
+    const raw = document.documentElement?.getAttribute('data-webstir-base') ?? '';
+    return normalizeBasePath(raw);
+}
+
+function normalizeBasePath(value: string): string {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed === '/') {
+        return '';
+    }
+    if (!trimmed.startsWith('/')) {
+        return `/${trimmed}`;
+    }
+    return trimmed.endsWith('/') ? trimmed.slice(0, -1) : trimmed;
+}
+
+function withBasePath(value: string): string {
+    if (!BASE_PATH) {
+        return value;
+    }
+    if (!value.startsWith('/') || value.startsWith('//')) {
+        return value;
+    }
+    if (value === BASE_PATH || value.startsWith(`${BASE_PATH}/`) || value.startsWith(`${BASE_PATH}?`) || value.startsWith(`${BASE_PATH}#`)) {
+        return value;
+    }
+    return `${BASE_PATH}${value}`;
+}
+
+function stripBasePath(value: string): string {
+    if (!BASE_PATH || !value.startsWith('/')) {
+        return value;
+    }
+    if (value === BASE_PATH) {
+        return '/';
+    }
+    if (value.startsWith(`${BASE_PATH}/`) || value.startsWith(`${BASE_PATH}?`) || value.startsWith(`${BASE_PATH}#`)) {
+        return value.slice(BASE_PATH.length);
+    }
+    return value;
+}
+
+async function renderUrl(url: string, { pushHistory }: { pushHistory: boolean }): Promise<void> {
+    activeRequestId += 1;
+    const requestId = activeRequestId;
+
+    if (activeController) {
+        activeController.abort();
+    }
+
+    const controller = new AbortController();
+    activeController = controller;
+
+    let response: Response;
+    try {
+        response = await fetch(url, {
+            headers: { 'X-Webstir-Client-Nav': '1' },
+            signal: controller.signal
+        });
+    } catch {
+        if (controller.signal.aborted) {
+            return;
+        }
+
+        window.location.href = url;
+        return;
+    }
+
+    if (!response.ok) {
+        window.location.href = url;
+        return;
+    }
+
+    const html = await response.text();
+    if (requestId !== activeRequestId) {
+        return;
+    }
+
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(html, 'text/html');
+
+    await syncHead(doc, url);
+
+    const newMain = doc.querySelector('main');
+    const currentMain = document.querySelector('main');
+    if (newMain && currentMain) {
+        currentMain.replaceWith(newMain);
+    }
+
+    const newTitle = doc.querySelector('title');
+    if (newTitle && newTitle.textContent) {
+        document.title = newTitle.textContent;
+    }
+
+    if (pushHistory) {
+        window.history.pushState({}, '', url);
+    }
+    window.scrollTo({ top: 0, behavior: 'smooth' });
+    const focusTarget = document.querySelector('[autofocus]');
+    if (focusTarget instanceof HTMLElement) {
+        focusTarget.focus();
+    }
+
+    executeScripts(document.querySelector('main'));
+    window.dispatchEvent(new CustomEvent('webstir:client-nav', { detail: { url } }));
+}
+
+enableClientNav();
+
+async function syncHead(doc: Document, url: string): Promise<void> {
+    const head = document.head;
+    const newHead = doc.head;
+    if (!head || !newHead) {
+        return;
+    }
+
+    const preservedClientNav = head.querySelector('script[data-webstir="client-nav"]');
+    const preservedAppCss = Array.from(head.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]'))
+        .find((link) => isAppStylesheetHref(link.getAttribute('href'))) ?? null;
+
+    for (const element of Array.from(head.querySelectorAll(`script[${DYNAMIC_ATTR}="${DYNAMIC_VALUE}"]`))) {
+        element.remove();
+    }
+
+    for (const script of Array.from(head.querySelectorAll('script[src]'))) {
+        const src = script.getAttribute('src') ?? '';
+        const normalizedSrc = stripBasePath(src);
+        if (script === preservedClientNav) {
+            continue;
+        }
+        if (normalizedSrc === '/hmr.js' || normalizedSrc === '/refresh.js') {
+            continue;
+        }
+        if (normalizedSrc.startsWith('/pages/')) {
+            script.remove();
+        }
+    }
+
+    const desiredStyles = new Map<string, string>();
+    for (const link of Array.from(newHead.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]'))) {
+        const href = link.getAttribute('href');
+        if (!href) {
+            continue;
+        }
+        const resolved = resolveUrl(href, url);
+        if (!resolved) {
+            continue;
+        }
+        const key = stripBasePath(stripQueryAndHash(resolved));
+        const finalHref = key === '/app/app.css' && preservedAppCss
+            ? (preservedAppCss.getAttribute('href') ?? resolved)
+            : withBasePath(resolved);
+        desiredStyles.set(key, finalHref);
+    }
+
+    if (preservedAppCss) {
+        const appHref = preservedAppCss.getAttribute('href') ?? withBasePath('/app/app.css');
+        desiredStyles.set('/app/app.css', appHref);
+    }
+
+    const existingStyles = new Map<string, HTMLLinkElement>();
+    const staleStyles: HTMLLinkElement[] = [];
+    for (const link of Array.from(head.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]'))) {
+        const key = normalizeStylesheetKey(link.getAttribute('href'), window.location.href);
+        if (!key) {
+            link.remove();
+            continue;
+        }
+        if (desiredStyles.has(key)) {
+            if (!existingStyles.has(key)) {
+                existingStyles.set(key, link);
+            }
+            continue;
+        }
+        staleStyles.push(link);
+    }
+
+    const pendingStyles: HTMLLinkElement[] = [];
+    for (const [key, href] of desiredStyles.entries()) {
+        if (existingStyles.has(key)) {
+            continue;
+        }
+        const next = document.createElement('link');
+        next.rel = 'stylesheet';
+        next.href = href;
+        head.appendChild(next);
+        existingStyles.set(key, next);
+        pendingStyles.push(next);
+    }
+
+    const stylesReady = pendingStyles.length > 0
+        ? waitForStylesheets(pendingStyles)
+        : Promise.resolve();
+    if (staleStyles.length > 0) {
+        void stylesReady.then(() => {
+            requestAnimationFrame(() => {
+                for (const link of staleStyles) {
+                    link.remove();
+                }
+            });
+        });
+    }
+
+    syncCriticalStyles(head, newHead);
+
+    for (const script of Array.from(newHead.querySelectorAll('script[src]'))) {
+        const src = script.getAttribute('src');
+        if (!src) {
+            continue;
+        }
+        if (src === '/clientNav.js' || src.endsWith('/clientNav.js')) {
+            continue;
+        }
+        if (src === '/hmr.js' || src === '/refresh.js') {
+            continue;
+        }
+
+        const resolved = resolveUrl(src, url);
+        if (!resolved) {
+            continue;
+        }
+
+        const next = document.createElement('script');
+        const type = script.getAttribute('type');
+        if (type) {
+            next.type = type;
+        }
+        next.src = resolved;
+        next.setAttribute(DYNAMIC_ATTR, DYNAMIC_VALUE);
+        head.appendChild(next);
+    }
+
+    if (preservedClientNav && !head.contains(preservedClientNav)) {
+        head.appendChild(preservedClientNav);
+    }
+
+    await stylesReady;
+}
+
+function executeScripts(container: Element | null): void {
+    if (!container) {
+        return;
+    }
+
+    const scripts = Array.from(container.querySelectorAll('script'));
+    for (const script of scripts) {
+        const src = script.getAttribute('src');
+        const type = script.getAttribute('type');
+
+        const normalizedSrc = src ? stripBasePath(src) : '';
+        if (normalizedSrc && (normalizedSrc === '/clientNav.js' || normalizedSrc.endsWith('/clientNav.js'))) {
+            script.remove();
+            continue;
+        }
+        if (normalizedSrc === '/hmr.js' || normalizedSrc === '/refresh.js') {
+            script.remove();
+            continue;
+        }
+
+        const next = document.createElement('script');
+        if (type) {
+            next.type = type;
+        }
+
+        if (src) {
+            const resolved = resolveUrl(src, window.location.href);
+            if (resolved) {
+                next.src = resolved;
+            }
+        } else if (script.textContent) {
+            next.textContent = script.textContent;
+        }
+
+        script.replaceWith(next);
+    }
+}
+
+function resolveUrl(value: string, baseUrl: string): string | null {
+    try {
+        const trimmed = String(value ?? '').trim();
+        const [path, suffix] = splitPathSuffix(trimmed);
+        if (path && !path.startsWith('/') && !path.startsWith('http:') && !path.startsWith('https:')) {
+            if (path === 'index.js' || path === 'index.css') {
+                const pageName = getPageNameFromUrl(baseUrl);
+                return withBasePath(`/pages/${pageName}/${path}${suffix}`);
+            }
+        }
+
+        const resolved = new URL(value, baseUrl);
+        return withBasePath(resolved.pathname + resolved.search + resolved.hash);
+    } catch {
+        return null;
+    }
+}
+
+function normalizeStylesheetKey(href: string | null, baseUrl: string): string | null {
+    const resolved = resolveUrl(href ?? '', baseUrl);
+    if (!resolved) {
+        return null;
+    }
+    return stripBasePath(stripQueryAndHash(resolved));
+}
+
+function stripQueryAndHash(value: string): string {
+    return value.split(/[?#]/)[0] ?? value;
+}
+
+function waitForStylesheets(links: HTMLLinkElement[], timeoutMs = 2000): Promise<void> {
+    if (links.length === 0) {
+        return Promise.resolve();
+    }
+
+    return new Promise((resolve) => {
+        let remaining = links.length;
+        let done = false;
+        const finish = () => {
+            if (done) {
+                return;
+            }
+            done = true;
+            resolve();
+        };
+
+        const timer = window.setTimeout(finish, timeoutMs);
+        const handle = () => {
+            if (done) {
+                return;
+            }
+            remaining -= 1;
+            if (remaining <= 0) {
+                window.clearTimeout(timer);
+                finish();
+            }
+        };
+
+        for (const link of links) {
+            if (link.sheet) {
+                handle();
+                continue;
+            }
+            link.addEventListener('load', handle, { once: true });
+            link.addEventListener('error', handle, { once: true });
+        }
+    });
+}
+
+function syncCriticalStyles(head: HTMLHeadElement, newHead: HTMLHeadElement): void {
+    for (const style of Array.from(head.querySelectorAll<HTMLStyleElement>('style[data-critical]'))) {
+        style.remove();
+    }
+
+    for (const style of Array.from(newHead.querySelectorAll<HTMLStyleElement>('style[data-critical]'))) {
+        const next = document.createElement('style');
+        for (const attribute of Array.from(style.attributes)) {
+            next.setAttribute(attribute.name, attribute.value);
+        }
+        if (style.textContent) {
+            next.textContent = style.textContent;
+        }
+        head.appendChild(next);
+    }
+}
+
+function splitPathSuffix(value: string): [string, string] {
+    const [path, suffix = ''] = value.split(/(?=[?#])/);
+    return [path ?? '', suffix ?? ''];
+}
+
+function isAppStylesheetHref(href: string | null): boolean {
+    if (!href) {
+        return false;
+    }
+
+    try {
+        const normalized = stripBasePath(new URL(href, window.location.origin).pathname);
+        return normalized === '/app/app.css';
+    } catch {
+        const trimmed = href.trim();
+        if (!trimmed) {
+            return false;
+        }
+        const [path] = trimmed.split(/[?#]/);
+        return stripBasePath(path) === '/app/app.css';
+    }
+}
+
+function getPageNameFromUrl(url: string): string {
+    try {
+        const pathname = stripBasePath(new URL(url, window.location.href).pathname);
+        const trimmed = pathname.replace(/^\/+|\/+$/g, '');
+        if (!trimmed) {
+            return 'home';
+        }
+
+        const firstSegment = trimmed.split('/')[0];
+        return firstSegment || 'home';
+    } catch {
+        return 'home';
+    }
+}
+
+function cssEscape(value: string): string {
+    if (typeof CSS !== 'undefined' && typeof (CSS as { escape?: (value: string) => string }).escape === 'function') {
+        return (CSS as { escape: (value: string) => string }).escape(value);
+    }
+    return value.replace(/[\"\\\\]/g, '\\\\$&');
+}

package/assets/features/content_nav/content_nav.css

@@ -0,0 +1,170 @@
+@layer features {
+  .docs-layout[data-content-nav="true"] .docs-sidebar {
+    position: fixed;
+    top: var(--ws-header-sticky-offset, 0px);
+    bottom: 0;
+    left: 0;
+    width: var(--ws-docs-sidebar-width, 16rem);
+    border: 0;
+    border-right: 1px solid var(--ws-border);
+    border-radius: 0;
+    background: var(--ws-surface-1);
+    padding: var(--ws-space-5) var(--ws-space-6);
+  }
+
+  .docs-panel__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--ws-space-3);
+    margin-bottom: var(--ws-space-3);
+  }
+
+  .docs-panel__title {
+    font-size: 0.75rem;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    font-weight: 700;
+    color: var(--ws-muted);
+  }
+
+  .docs-panel__link {
+    font-size: 1rem;
+    letter-spacing: 0;
+    font-weight: 600;
+    color: var(--ws-fg);
+    text-decoration: none;
+  }
+
+  .docs-panel__link:hover {
+    color: var(--ws-accent);
+  }
+
+  .docs-panel__link:focus-visible {
+    outline: 0.1875rem solid var(--ws-focus);
+    outline-offset: 0.125rem;
+    border-radius: var(--ws-radius-2);
+  }
+
+  .docs-toolbar {
+    display: flex;
+    align-items: center;
+    gap: var(--ws-space-3);
+    flex-wrap: wrap;
+    margin-bottom: var(--ws-space-4);
+  }
+
+  .docs-breadcrumb {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+
+  .docs-breadcrumb__list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--ws-space-2);
+    color: var(--ws-muted);
+    font-size: 0.9rem;
+  }
+
+  .docs-breadcrumb__item {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ws-space-2);
+  }
+
+  .docs-breadcrumb__item:not(:first-child)::before {
+    content: "/";
+    color: var(--ws-muted);
+  }
+
+  .docs-breadcrumb__link {
+    color: inherit;
+    text-decoration: none;
+  }
+
+  .docs-breadcrumb__link:hover {
+    color: var(--ws-accent);
+  }
+
+  .docs-nav__list--nested {
+    margin-top: var(--ws-space-2);
+    padding-left: var(--ws-space-4);
+    border-left: 1px solid var(--ws-border);
+  }
+
+  .docs-nav__link,
+  .docs-nav__label {
+    color: inherit;
+    text-decoration: none;
+    font-weight: 600;
+    line-height: 1.4;
+  }
+
+  .docs-nav__label {
+    display: inline-flex;
+    color: var(--ws-muted);
+  }
+
+  .docs-nav__link {
+    color: var(--ws-fg);
+    font-size: 0.95rem;
+    padding-left: var(--ws-space-3);
+  }
+
+  .docs-nav__link:hover {
+    color: var(--ws-accent);
+  }
+
+  .docs-nav__item[data-active="true"] > .docs-nav__link,
+  .docs-nav__item[data-active-branch="true"] > .docs-nav__label {
+    color: var(--ws-accent);
+  }
+
+  .app-nav__docs {
+    display: none;
+  }
+
+  .app-nav__docs > .docs-nav__list {
+    padding-left: var(--ws-space-3);
+  }
+
+  .app-nav__docs .docs-nav__link {
+    color: var(--ws-fg);
+    font-weight: 400;
+  }
+
+  .app-nav__docs .docs-nav__link:focus-visible {
+    outline: 0.1875rem solid var(--ws-focus);
+    outline-offset: 0.125rem;
+    border-radius: var(--ws-radius-1);
+  }
+
+  .app-nav__docs .docs-nav__list--nested {
+    padding-left: var(--ws-space-2);
+  }
+
+  @media (--ws-sm) {
+    .docs-layout[data-content-nav="true"] .docs-sidebar {
+      display: none;
+    }
+
+    .docs-toolbar {
+      margin-bottom: var(--ws-space-2);
+    }
+
+    .app-nav__docs {
+      display: grid;
+      gap: var(--ws-space-1);
+    }
+
+    .app-menu.is-open .app-nav__docs .docs-nav__link {
+      width: 100%;
+      justify-content: space-between;
+    }
+  }
+}