@rocket/js 0.1.2 → 0.2.0

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/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/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/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);
 }
 

package/src/static-params.js

@@ -0,0 +1,114 @@
+import { PageData } from './PageData.js';
+
+/** @typedef {import('@rocket/js/types.js').Page} Page */
+/** @typedef {import('@rocket/js/types.js').PageRegistry} PageRegistry */
+/** @typedef {import('@rocket/js/types.js').PageStaticParams} PageStaticParams */
+/** @typedef {import('@rocket/js/types.js').PageStaticParamsDeclaration} PageStaticParamsDeclaration */
+
+/**
+ * @param {Page} page
+ */
+export function hasStaticParams(page) {
+  return page.file.endsWith('.js') && page.module.staticParams !== undefined;
+}
+
+/**
+ * @param {string} pagePath
+ */
+export function hasPathParameter(pagePath) {
+  return /(^|\/):[^/]+/.test(pagePath);
+}
+
+/**
+ * Enumerates the concrete output paths of a parameterized static JavaScript
+ * Page from its `staticParams` export.
+ *
+ * @param {{
+ *   pages: PageRegistry;
+ *   page: Page;
+ *   pagePath: string;
+ * }} options
+ * @returns {string[]}
+ */
+export function staticParamsPagePaths({ pages, page, pagePath }) {
+  if (!hasPathParameter(pagePath)) {
+    throw new Error(
+      `Static params for ${page.file} require a parameterized Page path, ` +
+        `but its path ${pagePath} has no route params.`,
+    );
+  }
+  const declaration = /** @type {PageStaticParamsDeclaration} */ (page.module.staticParams);
+  const paramsList =
+    typeof declaration === 'function'
+      ? declaration(new PageData(pages, page.metadata, pagePath))
+      : declaration;
+  if (!Array.isArray(paramsList)) {
+    throw new Error(`Static params for ${page.file} must be an array of route param objects.`);
+  }
+  const paths = [];
+  const seen = new Set();
+  for (const params of paramsList) {
+    const concretePath = substituteRouteParams(pagePath, params, page);
+    if (seen.has(concretePath)) {
+      throw new Error(
+        `Static params for ${page.file} produce the duplicate output path ${concretePath}.`,
+      );
+    }
+    seen.add(concretePath);
+    paths.push(concretePath);
+  }
+  return paths;
+}
+
+/**
+ * @param {string} pagePath
+ * @param {unknown} params
+ * @param {Page} page
+ * @returns {string}
+ */
+function substituteRouteParams(pagePath, params, page) {
+  if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+    throw new Error(`Static params for ${page.file} must be objects with string values.`);
+  }
+  const paramValues = /** @type {Record<string, unknown>} */ (params);
+  const usedNames = new Set();
+  const segments = pagePath.split('/').map(segment => {
+    if (!segment.startsWith(':')) {
+      return segment;
+    }
+    const name = segment.slice(1);
+    usedNames.add(name);
+    return routeParamValue(name, paramValues[name], page);
+  });
+  for (const name of Object.keys(paramValues)) {
+    if (!usedNames.has(name)) {
+      throw new Error(
+        `Static params for ${page.file} set unknown route param "${name}" ` +
+          `for the Page path ${pagePath}.`,
+      );
+    }
+  }
+  return segments.join('/');
+}
+
+/**
+ * @param {string} name
+ * @param {unknown} value
+ * @param {Page} page
+ * @returns {string}
+ */
+function routeParamValue(name, value, page) {
+  if (typeof value !== 'string' || value === '') {
+    throw new Error(
+      `Static params for ${page.file} must provide a non-empty string ` +
+        `for route param "${name}".`,
+    );
+  }
+  if (encodeURIComponent(value) !== value) {
+    throw new Error(
+      `Static params for ${page.file} route param "${name}" value ${JSON.stringify(value)} ` +
+        `is not a URL-safe path segment. Slugify param values before returning them.`,
+    );
+  }
+  return value;
+}