@rocket/js 0.1.2 → 0.2.1

package/src/page-runtime.js

@@ -1,9 +1,10 @@
 import { collectResult } from '@lit-labs/ssr/lib/render-result.js';
-import { URLPattern } from 'urlpattern-polyfill';
+import { routePattern } from './route-pattern.js';
 import { layout, singleDemoLayout } from './layouts/layout.js';
 import { PageData } from './PageData.js';
 import { finalizeRocketIcons } from './icons.js';
 import { matchPaginatedArchivePath, pageDataWithPagination } from './page-pagination.js';
+import { createPageFeed, matchPageFeedPath } from './feeds.js';
 import { matchStandaloneDemoUrl } from './standalone-demo-url.js';
 
 /** @typedef {import('@rocket/js/types.js').PageRegistry} PageRegistry */
@@ -86,6 +87,14 @@ export class PageRuntime {
       });
     }
 
+    // A configured Page at the exact request path always wins over a Page Feed.
+    const feedMatch = this.pages.has(url.pathname)
+      ? null
+      : matchPageFeedPath(url.pathname, this.pages);
+    if (feedMatch) {
+      return this.renderPageFeed(feedMatch, url.origin);
+    }
+
     const pageMatch = findPage(url.pathname, url.origin, this.pages);
     if (!pageMatch) {
       return new Response('Page not found', { status: 404 });
@@ -134,11 +143,47 @@ export class PageRuntime {
       });
     }
 
-    throw new Error('Unsupported Page module kind');
+    throw new PageRuntimeError(
+      'INVALID_PAGE_MODULE',
+      `Unsupported Page module kind for ${pageMatch.routePath}`,
+      { page: pageMatch.page, routePath: pageMatch.routePath },
+    );
+  }
+
+  /**
+   * Development falls back to the request origin so Page Feeds work before a
+   * Site Origin is configured; builds always pass the configured Site Origin.
+   *
+   * @param {{ page: Page; routePath: string }} feedMatch
+   * @param {string} requestOrigin
+   */
+  renderPageFeed(feedMatch, requestOrigin) {
+    /** @type {string} */
+    let feed;
+    try {
+      feed = createPageFeed({
+        pages: this.pages,
+        page: feedMatch.page,
+        pagePath: feedMatch.routePath,
+        siteOrigin: this.siteOrigin || requestOrigin,
+      });
+    } catch (error) {
+      throw new PageRuntimeError(
+        'PAGE_RENDER_FAILED',
+        `Failed to render Page Feed for ${feedMatch.page.file}`,
+        { cause: error, page: feedMatch.page, routePath: feedMatch.routePath },
+      );
+    }
+    return new Response(feed, {
+      headers: { 'content-type': 'application/atom+xml; charset=utf-8' },
+    });
   }
 }
 
 /**
+ * Redirect sources intentionally match the request path exactly (no
+ * trailing-slash normalization) so authors control both URL forms explicitly.
+ *
  * @param {string} pathname
  * @param {RedirectConfig[] | undefined} redirects
  */
@@ -466,7 +511,7 @@ function archivePageNumber(variant) {
  * @param {string} routePath
  */
 function matchPagePath(pathname, origin, routePath) {
-  const pattern = new URLPattern({ pathname: routePath });
+  const pattern = routePattern(routePath);
   return pattern.exec(pathname, origin);
 }
 

package/src/pages.js

@@ -21,56 +21,49 @@ export async function getPages(root, include, exclude) {
     cwd: root,
     exclude: ignoreFn(exclude),
   })) {
-    if (file.endsWith('.rocket.md')) {
-      const module = await tryImport(`./${p.relative(process.cwd(), file)}`);
-      const path = module.config?.path;
-      if (!path) {
-        throw new Error('No path found in file: ' + file);
-      }
-      if (pages.has(path)) {
-        throw new Error(
-          'Duplicate path found: ' + path + ', used in ' + file + ' and ' + pages.get(path)?.file,
-        );
-      }
-      const normalizedModule = normalizePageModule(file, module);
+    const kind = file.endsWith('.rocket.md')
+      ? 'md'
+      : file.endsWith('.rocket.js')
+        ? 'js'
+        : undefined;
+    if (!kind) {
+      continue;
+    }
+    const specifier = `./${p.relative(process.cwd(), p.resolve(root, file))}`;
+    /** @type {import('@rocket/js/types.js').Module} */
+    const module =
+      kind === 'md'
+        ? await tryImport(specifier)
+        : await import(specifier, { with: { type: 'rocketSetupJsInitial' } });
+    const path = module.config?.path;
+    if (!path) {
+      throw new Error('No path found in file: ' + file);
+    }
+    if (pages.has(path)) {
+      throw new Error(
+        'Duplicate path found: ' + path + ', used in ' + file + ' and ' + pages.get(path)?.file,
+      );
+    }
+    const normalizedModule = normalizePageModule(file, module);
+    if (kind === 'md') {
       validateMarkdownPageComponents(file, normalizedModule);
-      const linkText =
-        (normalizedModule.config.menu === false
-          ? undefined
-          : normalizedModule.config.menu?.linkText) || normalizedModule._$menuLinkText$;
-      const metadataConfig = normalizePageMetadataConfig(file, normalizedModule.config.metadata);
-      const title = metadataConfig.title || module._$title$ || linkText || titleFromPath(path);
-      pages.set(path, {
-        file,
-        module: normalizedModule,
-        metadata: pageMetadata(title, linkText, metadataConfig),
-        demoNames: normalizedModule._$demoNames$ || [],
-      });
-    } else if (file.endsWith('.rocket.js')) {
-      /** @type {import('@rocket/js/types.js').Module} */
-      const module = await import(`./${p.relative(process.cwd(), file)}`, {
-        with: { type: 'rocketSetupJsInitial' },
-      });
-      const path = module.config?.path;
-      if (!path) {
-        throw new Error('No path found in file: ' + file);
-      }
-      if (pages.has(path)) {
-        throw new Error(
-          'Duplicate path found: ' + path + ', used in ' + file + ' and ' + pages.get(path)?.file,
-        );
-      }
-      const normalizedModule = normalizePageModule(file, module);
-      const linkText =
-        normalizedModule.config.menu === false ? undefined : normalizedModule.config.menu?.linkText;
-      const metadataConfig = normalizePageMetadataConfig(file, normalizedModule.config.metadata);
-      const title = metadataConfig.title || linkText || titleFromPath(path);
-      pages.set(path, {
-        file,
-        module: normalizedModule,
-        metadata: pageMetadata(title, linkText, metadataConfig),
-      });
     }
+    const configLinkText =
+      normalizedModule.config.menu === false ? undefined : normalizedModule.config.menu?.linkText;
+    const linkText =
+      kind === 'md' ? configLinkText || normalizedModule._$menuLinkText$ : configLinkText;
+    const metadataConfig = normalizePageMetadataConfig(file, normalizedModule.config.metadata);
+    const title =
+      metadataConfig.title ||
+      (kind === 'md' ? module._$title$ : undefined) ||
+      linkText ||
+      titleFromPath(path);
+    pages.set(path, {
+      file,
+      module: normalizedModule,
+      metadata: pageMetadata(title, linkText, metadataConfig),
+      ...(kind === 'md' ? { demoNames: normalizedModule._$demoNames$ || [] } : {}),
+    });
   }
   return pages;
 }
@@ -448,10 +441,11 @@ function ignoreFn(exclude) {
    * @param {string} path
    */
   return function (path) {
+    if (path.includes('node_modules')) {
+      return true;
+    }
     for (const pattern of exclude) {
-      if (path.includes('node_modules')) {
-        return true;
-      } else if (typeof pattern === 'string') {
+      if (typeof pattern === 'string') {
         if (path.includes(pattern)) return true;
       } else {
         if (pattern.test(path)) return true;
@@ -466,12 +460,9 @@ function ignoreFn(exclude) {
  * @returns {string}
  */
 function titleFromPath(path) {
-  const parts = path.split('/');
+  const parts = path.split('/').filter(Boolean);
   const last = parts.findLast(part => !part.startsWith(':'));
-  if (!last) {
-    return parts[0] ? capitalize(parts[0].slice(1)) : 'Home';
-  }
-  return capitalize(last);
+  return last ? capitalize(last) : 'Home';
 }
 
 /**

package/src/prefer-project-packages-plugin.js

@@ -0,0 +1,31 @@
+import { resolveProjectBrowserPackage } from './project-package-resolution.js';
+import { resolve } from './resolve.js';
+
+/**
+ * Keeps browser packages shared between a Site Author project and a linked Rocket checkout.
+ * Packages absent from the project are left to normal Node resolution, which falls back to
+ * Rocket's dependency.
+ *
+ * @returns {import('@web/dev-server-core').Plugin}
+ */
+export function preferProjectPackagesPlugin() {
+  /** @type {Map<string, string | undefined>} */
+  const resolvedImports = new Map();
+
+  return {
+    name: 'rocket-prefer-project-packages',
+    resolveImport({ source }) {
+      if (resolvedImports.has(source)) {
+        return resolvedImports.get(source);
+      }
+      let resolved;
+      try {
+        resolved = resolveProjectBrowserPackage(source) ? resolve(source, import.meta) : undefined;
+      } catch {
+        resolved = undefined;
+      }
+      resolvedImports.set(source, resolved);
+      return resolved;
+    },
+  };
+}

package/src/project-package-resolution.js

@@ -0,0 +1,36 @@
+import { moduleResolve } from 'import-meta-resolve';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const browserImportConditions = new Set(['browser', 'import', 'module']);
+
+/**
+ * Resolve a bare package import from the Site Author project using browser ESM conditions.
+ * Built-in modules and packages absent from the project are left to another resolver.
+ *
+ * @param {string} specifier
+ */
+export function resolveProjectBrowserPackage(specifier) {
+  if (!isPackageSpecifier(specifier)) {
+    return undefined;
+  }
+  try {
+    const projectParent = pathToFileURL(path.join(process.cwd(), 'package.json'));
+    const resolved = moduleResolve(specifier, projectParent, browserImportConditions, false);
+    return resolved.protocol === 'file:' ? resolved.href : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {string} specifier
+ */
+function isPackageSpecifier(specifier) {
+  return (
+    !specifier.startsWith('.') &&
+    !specifier.startsWith('/') &&
+    !specifier.startsWith('#') &&
+    !URL.canParse(specifier)
+  );
+}

package/src/publicAssets.js

@@ -1,6 +1,6 @@
 import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { URLPattern } from 'urlpattern-polyfill';
+import { routePattern } from './route-pattern.js';
 import { paginatedArchivePaths } from './page-pagination.js';
 import { normalizeDocumentPath, standaloneDemoPaths } from './standalone-demo-url.js';
 import { needsDefaultSocialPreviewImage, publicSocialPreviewPages } from './socialPreviewImages.js';
@@ -250,7 +250,7 @@ function generatedOutputClaims({ pages, generatedPages, config, emitRedirectFall
  */
 function matchingPage(requestPath, pages) {
   for (const [routePath, page] of pages) {
-    const pattern = new URLPattern({ pathname: routePath });
+    const pattern = routePattern(routePath);
     if (pattern.exec(requestPath, 'http://localhost')) {
       return { routePath, page };
     }

package/src/resolve.js

@@ -1,5 +1,6 @@
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { resolveProjectBrowserPackage } from './project-package-resolution.js';
 
 /**
  * @param {string} url
@@ -9,7 +10,36 @@ import { fileURLToPath } from 'url';
 export function resolve(url, meta) {
   // get current directory
   const outputFilePath = process.cwd();
-  const resolvedPath = meta.resolve(url);
+  const resolvedPath = resolveProjectBrowserPackage(url) ?? meta.resolve(url);
   const rel = path.relative(outputFilePath, fileURLToPath(resolvedPath));
-  return (process.env.ENVIRONMENT === 'BUILD' ? '/../' : '/') + rel.split(path.sep).join('/');
+  if (process.env.ENVIRONMENT === 'BUILD') {
+    return `/../${toBrowserPath(rel)}`;
+  }
+  return developmentBrowserPath(rel);
+}
+
+/**
+ * Web Dev Server represents files outside its root with a path that records how many parent
+ * directories to traverse. Browsers normalize ordinary `/../` segments before making a request,
+ * so linked packages need this explicit form.
+ *
+ * @param {string} relativePath
+ */
+function developmentBrowserPath(relativePath) {
+  const parts = relativePath.split(path.sep);
+  let outsideRootDepth = 0;
+  while (parts[outsideRootDepth] === '..') {
+    outsideRootDepth += 1;
+  }
+  const browserPath = parts.slice(outsideRootDepth).join('/');
+  return outsideRootDepth
+    ? `/__wds-outside-root__/${outsideRootDepth}/${browserPath}`
+    : `/${browserPath}`;
+}
+
+/**
+ * @param {string} filePath
+ */
+function toBrowserPath(filePath) {
+  return filePath.split(path.sep).join('/');
 }

package/src/route-pattern.js

@@ -0,0 +1,21 @@
+/** Runs on: server */
+import { URLPattern } from 'urlpattern-polyfill';
+
+/** @type {Map<string, URLPattern>} */
+const patterns = new Map();
+
+/**
+ * Compiling a URLPattern is comparatively expensive and route paths repeat on
+ * every request, so compiled patterns are cached per route path.
+ *
+ * @param {string} routePath
+ * @returns {URLPattern}
+ */
+export function routePattern(routePath) {
+  let pattern = patterns.get(routePath);
+  if (!pattern) {
+    pattern = new URLPattern({ pathname: routePath });
+    patterns.set(routePath, pattern);
+  }
+  return pattern;
+}

package/src/siteDiscoverability.js

@@ -5,6 +5,7 @@ import {
   paginatedArchivePath,
   paginatedArchivePaths,
 } from './page-pagination.js';
+import { hasStaticParams, staticParamsPagePaths } from './static-params.js';
 
 /**
  * @param {{
@@ -55,6 +56,10 @@ export function createSitemap({ pages, siteOrigin }) {
 }
 
 /**
+ * The Robots File always references the canonical Sitemap URL, even when
+ * Rocket does not generate `sitemap.xml` itself — this is documented behavior
+ * so projects can supply a sitemap through other tooling.
+ *
  * @param {{
  *   pages?: import('@rocket/js/types.js').PageRegistry;
  *   siteOrigin: string;
@@ -82,7 +87,12 @@ export function createRobotsFile({ pages = new Map(), siteOrigin }) {
 function sitemapPageLocations({ pages, siteOrigin }) {
   return Array.from(pages.entries())
     .filter(([pagePath, page]) => {
-      return !hasPathParameter(pagePath) && page.module.config.discoverability?.sitemap !== false;
+      // Parameterized Pages join the Sitemap only when static params enumerate
+      // their public URLs.
+      return (
+        (!hasPathParameter(pagePath) || hasStaticParams(page)) &&
+        page.module.config.discoverability?.sitemap !== false
+      );
     })
     .flatMap(([pagePath, page]) => discoverabilityPagePaths({ pages, pagePath, page }))
     .map(pagePath => absolutePageUrl(siteOrigin, pagePath))
@@ -108,6 +118,9 @@ function robotsDisallowPaths({ pages }) {
  * }} options
  */
 function discoverabilityPagePaths({ pages, pagePath, page }) {
+  if (hasStaticParams(page)) {
+    return staticParamsPagePaths({ pages, page, pagePath });
+  }
   if (!hasPagePagination(page)) {
     return [pagePath];
   }

package/src/socialPreviewImages.js

@@ -57,7 +57,7 @@ export async function generateStaticDefaultSocialPreviewImages({
   siteHeadMetadata,
   siteOrigin,
   cacheDirectory,
-  captureSocialPreviewImage = captureSocialPreviewImageWithBrowser,
+  captureSocialPreviewImage,
 }) {
   /** @type {Map<string, DefaultSocialPreviewImageOutput>} */
   const outputs = new Map();
@@ -71,6 +71,43 @@ export async function generateStaticDefaultSocialPreviewImages({
     );
   }
 
+  // Launching Chromium costs seconds; share one browser across all uncached captures.
+  /** @type {import('puppeteer-core').Browser | undefined} */
+  let sharedBrowser;
+  /** @type {SocialPreviewCapture} */
+  const capture =
+    captureSocialPreviewImage ??
+    (async ({ html }) => {
+      sharedBrowser ??= await puppeteer.launch(await createSocialPreviewBrowserLaunchOptions());
+      return renderSocialPreviewImage(html, sharedBrowser);
+    });
+
+  try {
+    await generateInto({ outputs, pages, siteHeadMetadata, siteOrigin, cacheDirectory, capture });
+  } finally {
+    await sharedBrowser?.close();
+  }
+  return outputs;
+}
+
+/**
+ * @param {{
+ *   outputs: Map<string, DefaultSocialPreviewImageOutput>;
+ *   pages: import('@rocket/js/types.js').PageRegistry;
+ *   siteHeadMetadata: import('@rocket/js/types.js').SiteHeadMetadataConfig;
+ *   siteOrigin: string;
+ *   cacheDirectory?: string;
+ *   capture: SocialPreviewCapture;
+ * }} options
+ */
+async function generateInto({
+  outputs,
+  pages,
+  siteHeadMetadata,
+  siteOrigin,
+  cacheDirectory,
+  capture,
+}) {
   for (const [pagePath, page] of pages) {
     if (!needsDefaultSocialPreviewImage({ pagePath, page, siteHeadMetadata })) {
       continue;
@@ -101,7 +138,7 @@ export async function generateStaticDefaultSocialPreviewImages({
     }
 
     try {
-      const data = await captureSocialPreviewImage({
+      const data = await capture({
         html,
         width: DEFAULT_SOCIAL_PREVIEW_IMAGE_WIDTH,
         height: DEFAULT_SOCIAL_PREVIEW_IMAGE_HEIGHT,
@@ -121,7 +158,6 @@ export async function generateStaticDefaultSocialPreviewImages({
       );
     }
   }
-  return outputs;
 }
 
 /**
@@ -332,34 +368,39 @@ export async function captureSocialPreviewImageWithBrowser({ html }) {
 
 /**
  * @param {string} html
+ * @param {import('puppeteer-core').Browser} [existingBrowser] reused across captures; the caller owns closing it
  * @returns {Promise<Buffer>}
  */
-export async function renderSocialPreviewImage(html) {
-  /** @type {import('puppeteer-core').Browser | undefined} */
-  let browser;
+export async function renderSocialPreviewImage(html, existingBrowser) {
+  const browser =
+    existingBrowser ?? (await puppeteer.launch(await createSocialPreviewBrowserLaunchOptions()));
+  /** @type {import('puppeteer-core').Page | undefined} */
+  let page;
   try {
-    browser = await puppeteer.launch(await createSocialPreviewBrowserLaunchOptions());
-    const page = await browser.newPage();
-    await page.setViewport({
+    const capturePage = await browser.newPage();
+    page = capturePage;
+    await capturePage.setViewport({
       width: DEFAULT_SOCIAL_PREVIEW_IMAGE_WIDTH,
       height: DEFAULT_SOCIAL_PREVIEW_IMAGE_HEIGHT,
       deviceScaleFactor: 1,
     });
 
     await runSocialPreviewCaptureStep('set Social Preview HTML content', () =>
-      page.setContent(html, { waitUntil: 'load' }),
+      capturePage.setContent(html, { waitUntil: 'load' }),
     );
     await runSocialPreviewCaptureStep('wait for Social Preview fonts', () =>
-      page.evaluateHandle('document.fonts.ready'),
+      capturePage.evaluateHandle('document.fonts.ready'),
     );
     const screenshot = await runSocialPreviewCaptureStep('capture Social Preview screenshot', () =>
-      page.screenshot({
+      capturePage.screenshot({
         type: 'png',
       }),
     );
     return Buffer.from(screenshot);
   } finally {
-    if (browser) {
+    if (existingBrowser) {
+      await page?.close();
+    } else {
       await browser.close();
     }
   }
@@ -401,7 +442,21 @@ export async function resolveSocialPreviewBrowserExecutablePath({
     return explicitPath;
   }
   if (platform === 'linux') {
-    return chromiumExecutablePath();
+    // Prefer the bundled serverless Chromium (CI/deploy targets); fall back to
+    // a locally installed browser on regular Linux machines.
+    try {
+      return await chromiumExecutablePath();
+    } catch (error) {
+      const localBrowserPath = findLocalBrowserExecutable({ platform, env, fileExists });
+      if (localBrowserPath) {
+        return localBrowserPath;
+      }
+      throw new Error(
+        `Unable to resolve a browser for Social Preview Capture. ` +
+          `Install Google Chrome or set PUPPETEER_EXECUTABLE_PATH to a Chromium-compatible browser.`,
+        { cause: error },
+      );
+    }
   }
   const localBrowserPath = findLocalBrowserExecutable({ platform, env, fileExists });
   if (localBrowserPath) {
@@ -431,6 +486,17 @@ function findLocalBrowserExecutable({ platform, env, fileExists }) {
       '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
     );
   }
+  if (platform === 'linux') {
+    paths.push(
+      '/usr/bin/google-chrome',
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/chromium',
+      '/usr/bin/chromium-browser',
+      '/snap/bin/chromium',
+      '/usr/bin/microsoft-edge',
+      '/usr/bin/brave-browser',
+    );
+  }
   if (platform === 'win32') {
     for (const root of [env.PROGRAMFILES, env['PROGRAMFILES(X86)'], env.LOCALAPPDATA]) {
       if (!root) {

package/src/ssr.js

@@ -1,6 +1,9 @@
 /** Runs on: imported-js */
 import { render } from '@lit-labs/ssr';
 import { collectResult } from '@lit-labs/ssr/lib/render-result.js';
+import { html } from 'lit';
+
+export { html, render };
 
 /**
  * @param {string | import('lit').TemplateResult} template

package/src/standalone-demo-url.js

@@ -1,4 +1,4 @@
-import { URLPattern } from 'urlpattern-polyfill';
+import { routePattern } from './route-pattern.js';
 
 /** @typedef {import('@rocket/js/types.js').PageRegistry} PageRegistry */
 /** @typedef {import('@rocket/js/types.js').Page} Page */
@@ -124,7 +124,7 @@ export function normalizeDocumentPath(pagePath) {
  * @param {string} routePath
  */
 function matchPagePath(pathname, origin, routePath) {
-  const pattern = new URLPattern({ pathname: routePath });
+  const pattern = routePattern(routePath);
   return pattern.exec(pathname, origin);
 }