@atelic-action/ui 0.17.1 → 1.0.0

package/bin/atelic-check-base-path.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+// atelic-check-base-path: fails a build whose pages or vercel.json disagree with the base path.
+import { main } from "../src/scripts/check-base-path";
+
+await main();

package/bin/atelic-clean-sitemap.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+// atelic-clean-sitemap: strips duplicate URLs out of the built sitemap.
+import { main } from "../src/scripts/clean-sitemap";
+
+main();

package/bin/atelic-contact-canary.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+// atelic-contact-canary: proves the live contact relay end to end.
+import { main } from "../src/scripts/contact-canary";
+
+await main();

package/bin/atelic-print-sheets.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Print an artifact page to PDF with headless Chrome and report its sheet
 # count. The writeup flows across as many letter pages as it needs, its
-# collapsibles printed open, so its count is a record of the print and not a
+# native disclosures printed open, so its count is a record of the print and not a
 # layout check. The monthly page is one sheet by construction, so pass 1 for
 # it and the script fails when it prints as anything else.
 #

package/bin/atelic-seal-document.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // atelic-seal-document <config.json> [out.json]: seals a document for its readers.
 import { argv } from "node:process";
-import { cli } from "../src/scripts/build-gate-payload.mjs";
+import { cli } from "../src/scripts/seal-document.mjs";
 
 await cli(argv.slice(2));

package/bin/atelic-serve-static.ts

@@ -2,4 +2,4 @@
 // atelic-serve-static: serves dist/client for the browser tests.
 import { main } from "../src/scripts/serve-static";
 
-main();
+await main();

package/dist/gate/index.d.ts

@@ -1,3 +1,3 @@
 export { safeNext } from "./next.js";
 export { signToken, type TokenClaims, type TokenPurpose, verifyToken } from "./tokens.js";
-export { needsSession } from "./wall.js";
+export { createNeedsSession, needsSession, OPEN_PATHS, type WallOpenings } from "./wall.js";

package/dist/gate/index.js

@@ -1,3 +1,3 @@
 export { safeNext } from "./next.js";
 export { signToken, verifyToken } from "./tokens.js";
-export { needsSession } from "./wall.js";
+export { createNeedsSession, needsSession, OPEN_PATHS } from "./wall.js";

package/dist/gate/middleware.d.ts

@@ -1,6 +1,9 @@
+import { type WallOpenings } from "./wall.js";
 export interface MiddlewareOptions {
-    /** Whether a path needs a session once the gate is armed. */
+    /** Whether a path needs a session once the gate is armed. Wins over `open`. */
     needsSession?: (pathname: string) => boolean;
+    /** Paths the site opens beyond the wall's own, added to its allowlist. */
+    open?: WallOpenings;
 }
 export declare function createMiddleware(options?: MiddlewareOptions): (request: Request) => Promise<Response | undefined>;
 declare const _default: (request: Request) => Promise<Response | undefined>;

package/dist/gate/middleware.js

@@ -16,13 +16,22 @@
  *
  * That matcher keeps only the two sign in functions away from the middleware,
  * so any other function a host adds is held like a page. The default holds
- * back everything `needsSession` in wall.ts does. A site
- * whose matcher already leaves its open paths out passes its own test to
- * `createMiddleware`.
+ * back everything `needsSession` in wall.ts does. A marketing site, whose
+ * other functions (the contact relay) are public by design, uses the simple
+ * matcher instead, everything but `api/` and the login page:
+ *
+ *   export const config = { matcher: ["/((?!api/|login$|login/).*)"] };
+ *
+ * and leaves the deciding here: a request passes with no session only when
+ * the wall's open exact paths and open prefixes name it, so a page is held by
+ * default whatever its path looks like (`/blog/release-2.0` included), where
+ * a matcher that let file extensions through let it escape. A site with an
+ * open file of its own passes `open`; one whose matcher already leaves its
+ * open paths out may still pass its own `needsSession`, which wins over both.
  */
 import { isAllowed } from "./config.js";
 import { verifyToken } from "./tokens.js";
-import { needsSession as wallNeedsSession } from "./wall.js";
+import { createNeedsSession } from "./wall.js";
 function readCookie(header, name) {
     const match = header.match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`));
     if (!match)
@@ -35,7 +44,7 @@ function readCookie(header, name) {
     }
 }
 export function createMiddleware(options = {}) {
-    const needsSession = options.needsSession ?? wallNeedsSession;
+    const needsSession = options.needsSession ?? createNeedsSession(options.open);
     return async function middleware(request) {
         const secret = process.env.GATE_SESSION_SECRET;
         if (!secret)

package/dist/gate/wall.d.ts

@@ -30,9 +30,28 @@
  * it stays open on a private host too: a prospect reads the prototype
  * without a sign in while the documents beside it stay behind the wall.
  *
+ * A marketing site's login page loads the same kinds of file (its hashed
+ * assets, its fonts, its favicon), so the same lists hold a website by
+ * default: any path they do not name, a page whose last segment carries a
+ * dot (`/blog/release-2.0`) included, needs a session. A site with an open
+ * file of its own names it through `createNeedsSession` (or the middleware's
+ * `open` option), which adds to these lists and never opens the held corner.
+ *
  * Pure and dependency free, so the middleware imports it and the tests call
  * it directly.
  */
+/** What the wall leaves open with no session, exact paths and prefixes, before any a site adds. */
+export declare const OPEN_PATHS: {
+    readonly exact: readonly string[];
+    readonly prefixes: readonly string[];
+};
+/** Paths a site opens beyond the wall's own, for a file its login page needs. */
+export interface WallOpenings {
+    /** Paths opened as written, each starting with "/" (`/apple-touch-icon.png`). */
+    exact?: readonly string[];
+    /** Folders opened whole, each starting and ending with "/" and never "/" alone (`/icons/`). */
+    prefixes?: readonly string[];
+}
 /**
  * Whether a request for this path needs a session when the wall is armed.
  * The path is read the way a file server would read it (decoded, repeated
@@ -46,3 +65,9 @@
  * like an open one names some other file.
  */
 export declare function needsSession(pathname: string): boolean;
+/**
+ * `needsSession` with a site's own open paths added to the wall's, read the
+ * same way. Throws on an entry that is not a plain path, or a prefix that
+ * would open the whole host, so a typo cannot quietly unlock a site.
+ */
+export declare function createNeedsSession(open?: WallOpenings): (pathname: string) => boolean;

package/dist/gate/wall.js

@@ -30,6 +30,13 @@
  * it stays open on a private host too: a prospect reads the prototype
  * without a sign in while the documents beside it stay behind the wall.
  *
+ * A marketing site's login page loads the same kinds of file (its hashed
+ * assets, its fonts, its favicon), so the same lists hold a website by
+ * default: any path they do not name, a page whose last segment carries a
+ * dot (`/blog/release-2.0`) included, needs a session. A site with an open
+ * file of its own names it through `createNeedsSession` (or the middleware's
+ * `open` option), which adds to these lists and never opens the held corner.
+ *
  * Pure and dependency free, so the middleware imports it and the tests call
  * it directly.
  */
@@ -45,6 +52,8 @@ const OPEN_EXACT = new Set([
 const OPEN_PREFIXES = ["/api/auth/", "/assets/", "/brand/", "/fonts/", "/proto/"];
 /** The one corner of an open prefix that stays behind the wall. */
 const HELD_PREFIXES = ["/assets/doc/"];
+/** What the wall leaves open with no session, exact paths and prefixes, before any a site adds. */
+export const OPEN_PATHS = { exact: [...OPEN_EXACT], prefixes: [...OPEN_PREFIXES] };
 /**
  * Whether a request for this path needs a session when the wall is armed.
  * The path is read the way a file server would read it (decoded, repeated
@@ -58,6 +67,9 @@ const HELD_PREFIXES = ["/assets/doc/"];
  * like an open one names some other file.
  */
 export function needsSession(pathname) {
+    return judge(pathname, OPEN_EXACT, OPEN_PREFIXES);
+}
+function judge(pathname, exact, prefixes) {
     let path;
     try {
         path = decodeURIComponent(pathname);
@@ -71,7 +83,34 @@ export function needsSession(pathname) {
     const folded = path.toLowerCase();
     if (HELD_PREFIXES.some((prefix) => folded.startsWith(prefix)))
         return true;
-    if (OPEN_EXACT.has(path))
+    if (exact.has(path))
         return false;
-    return !OPEN_PREFIXES.some((prefix) => path.startsWith(prefix));
+    return !prefixes.some((prefix) => path.startsWith(prefix));
+}
+/**
+ * `needsSession` with a site's own open paths added to the wall's, read the
+ * same way. Throws on an entry that is not a plain path, or a prefix that
+ * would open the whole host, so a typo cannot quietly unlock a site.
+ */
+export function createNeedsSession(open = {}) {
+    const extraExact = open.exact ?? [];
+    const extraPrefixes = open.prefixes ?? [];
+    for (const path of extraExact) {
+        if (!path.startsWith("/") || path.includes("..") || path.includes("%")) {
+            throw new Error(`An open path must be a plain path starting with "/": ${JSON.stringify(path)}`);
+        }
+    }
+    for (const prefix of extraPrefixes) {
+        if (prefix === "/" ||
+            !prefix.startsWith("/") ||
+            !prefix.endsWith("/") ||
+            prefix.includes("..")) {
+            throw new Error(`An open prefix must be a folder such as "/icons/", never "/" alone: ${JSON.stringify(prefix)}`);
+        }
+    }
+    if (extraExact.length === 0 && extraPrefixes.length === 0)
+        return needsSession;
+    const exact = new Set([...OPEN_EXACT, ...extraExact]);
+    const prefixes = [...OPEN_PREFIXES, ...extraPrefixes];
+    return (pathname) => judge(pathname, exact, prefixes);
 }

package/dist/routing/basePath.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The base path: the prefix a site is served under when it does not own the
+ * root of its host (a website build previewed at `/proto` on the business's
+ * artifact host). A site sets it once; `BasePathProvider` hands it to every
+ * component below, and `marketingConfig` turns it into Vite's `base` and the
+ * router's `basepath`.
+ *
+ * Normalized form: "" for the root, otherwise a leading slash and no trailing
+ * slash ("/proto"). These helpers are pure and take the base explicitly, so
+ * the Vite config, the build commands, and the tests use them as they are.
+ * Plain TypeScript with no imports, since the built Vite entry imports it.
+ */
+/** Turns a configured value ("", "/", "proto", "/proto/") into "" or "/proto". Throws on anything else. */
+export declare function normalizeBasePath(raw: string | undefined): string;
+/** True when the path already carries the base (so applying it again is a no op). */
+export declare function hasBase(base: string, path: string): boolean;
+/**
+ * Prefixes a root absolute path with the base. External URLs, protocol links
+ * (mailto:, tel:), fragments, relative paths, and paths that already carry the
+ * base come back unchanged, so it is safe on any href and idempotent.
+ */
+export declare function joinBase(base: string, path: string): string;
+/** Removes the base from a path that carries it ("/proto/faqs" to "/faqs", "/proto" to "/"). */
+export declare function stripBase(base: string, path: string): string;

package/dist/routing/basePath.js

@@ -0,0 +1,54 @@
+/**
+ * The base path: the prefix a site is served under when it does not own the
+ * root of its host (a website build previewed at `/proto` on the business's
+ * artifact host). A site sets it once; `BasePathProvider` hands it to every
+ * component below, and `marketingConfig` turns it into Vite's `base` and the
+ * router's `basepath`.
+ *
+ * Normalized form: "" for the root, otherwise a leading slash and no trailing
+ * slash ("/proto"). These helpers are pure and take the base explicitly, so
+ * the Vite config, the build commands, and the tests use them as they are.
+ * Plain TypeScript with no imports, since the built Vite entry imports it.
+ */
+const SEGMENT = /^(\/[A-Za-z0-9._~-]+)+$/;
+/** Turns a configured value ("", "/", "proto", "/proto/") into "" or "/proto". Throws on anything else. */
+export function normalizeBasePath(raw) {
+    const trimmed = (raw ?? "").trim();
+    if (trimmed === "" || trimmed === "/")
+        return "";
+    const base = `/${trimmed.replace(/^\/+|\/+$/g, "")}`;
+    if (!SEGMENT.test(base)) {
+        throw new Error(`basePath must be a path such as "/proto" (letters, digits, dot, dash, underscore, tilde): got ${JSON.stringify(raw)}`);
+    }
+    return base;
+}
+/** True for a path the base applies to: root absolute, not protocol relative. */
+function isRootAbsolute(path) {
+    return path.startsWith("/") && !path.startsWith("//");
+}
+/** True when the path already carries the base (so applying it again is a no op). */
+export function hasBase(base, path) {
+    if (!base)
+        return true;
+    if (!path.startsWith(base))
+        return false;
+    const next = path.charAt(base.length);
+    return next === "" || next === "/" || next === "?" || next === "#";
+}
+/**
+ * Prefixes a root absolute path with the base. External URLs, protocol links
+ * (mailto:, tel:), fragments, relative paths, and paths that already carry the
+ * base come back unchanged, so it is safe on any href and idempotent.
+ */
+export function joinBase(base, path) {
+    if (!base || !isRootAbsolute(path) || hasBase(base, path))
+        return path;
+    return `${base}${path}`;
+}
+/** Removes the base from a path that carries it ("/proto/faqs" to "/faqs", "/proto" to "/"). */
+export function stripBase(base, path) {
+    if (!base || !isRootAbsolute(path) || !path.startsWith(base) || !hasBase(base, path))
+        return path;
+    const rest = path.slice(base.length);
+    return rest === "" || !rest.startsWith("/") ? `/${rest}` : rest;
+}

package/dist/vite/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * What a site's vite.config.ts imports (`@atelic-action/ui/vite`): the
- * configuration of an artifact site as one call, and the plugin inside it
- * for a site that writes its own.
+ * configuration of an artifact site or a marketing site as one call, and the
+ * plugin inside the artifact one for a site that writes its own.
  */
 export { type ArtifactConfigOptions, type ArtifactPage, artifactConfig, artifactPages, } from "./artifact-config.js";
+export { type MarketingConfigOptions, type MarketingPage, marketingBasePath, marketingConfig, NOT_FOUND_PAGE, } from "./marketing-config.js";
 export { DOC_DIR, isPrivateContent, privateChunks } from "./private-chunks.js";

package/dist/vite/index.js

@@ -1,7 +1,8 @@
 /**
  * What a site's vite.config.ts imports (`@atelic-action/ui/vite`): the
- * configuration of an artifact site as one call, and the plugin inside it
- * for a site that writes its own.
+ * configuration of an artifact site or a marketing site as one call, and the
+ * plugin inside the artifact one for a site that writes its own.
  */
 export { artifactConfig, artifactPages, } from "./artifact-config.js";
+export { marketingBasePath, marketingConfig, NOT_FOUND_PAGE, } from "./marketing-config.js";
 export { DOC_DIR, isPrivateContent, privateChunks } from "./private-chunks.js";

package/dist/vite/marketing-config.d.ts

@@ -0,0 +1,50 @@
+import { type UserConfig } from "vite";
+/** One entry of the prerender list, as TanStack Start takes it. */
+export interface MarketingPage {
+    path: string;
+    prerender?: {
+        enabled: boolean;
+    };
+    sitemap?: {
+        exclude: boolean;
+    };
+}
+export interface MarketingConfigOptions {
+    /**
+     * The two keys of the site's config the build reads: `url`, the canonical
+     * URL (with the base path on it for a based cut), and `basePath`.
+     */
+    site: {
+        url: string;
+        basePath?: string;
+    };
+    /**
+     * Pages the link crawler cannot reach on its own: a post on a dynamic
+     * route, a page nothing links to. The 404 page is always added.
+     */
+    pages?: readonly MarketingPage[];
+    /**
+     * The host the sitemap's URLs carry. Defaults to the origin of `site.url`.
+     */
+    sitemapHost?: string;
+    /**
+     * The escape hatch for a site with a real need of its own: merged over
+     * the result with Vite's `mergeConfig`.
+     */
+    extend?: UserConfig;
+    /** The environment to read `VITE_BASE_PATH` from; a test passes its own. */
+    env?: Record<string, string | undefined>;
+}
+/** The 404 page, prerendered and copied to 404.html by the build, never in the sitemap. */
+export declare const NOT_FOUND_PAGE: MarketingPage;
+/**
+ * The base the build uses: `VITE_BASE_PATH` when set (a rehearsal build,
+ * which CI runs under "/proto"), the config's `basePath` otherwise. Throws
+ * when a based config's `url` does not end with its base, since canonical and
+ * Open Graph URLs are built from it.
+ */
+export declare function marketingBasePath(site: {
+    url: string;
+    basePath?: string;
+}, env?: Record<string, string | undefined>): string;
+export declare function marketingConfig({ site, pages, sitemapHost, extend, env, }: MarketingConfigOptions): UserConfig;

package/dist/vite/marketing-config.js

@@ -0,0 +1,83 @@
+/**
+ * The whole Vite configuration of a marketing site, as one call. Every site
+ * cut from template-marketing carried its own copy of this configuration;
+ * here it is written once (0.19.0, ATE-643), and a site's vite.config.ts
+ * hands over its config and the pages the crawler cannot find:
+ *
+ *   import { marketingConfig } from "@atelic-action/ui/vite";
+ *   import { site } from "./src/site.config";
+ *
+ *   export default marketingConfig({ site, pages: [{ path: "/blog/first-post" }] });
+ *
+ * The site's own paths (the `@` alias to its src) are found from the
+ * directory Vite is run in, which is the site's root.
+ */
+import { resolve } from "node:path";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import react from "@vitejs/plugin-react";
+import { mergeConfig } from "vite";
+import { normalizeBasePath } from "../routing/basePath.js";
+/** The 404 page, prerendered and copied to 404.html by the build, never in the sitemap. */
+export const NOT_FOUND_PAGE = {
+    path: "/404",
+    prerender: { enabled: true },
+    sitemap: { exclude: true },
+};
+/**
+ * The base the build uses: `VITE_BASE_PATH` when set (a rehearsal build,
+ * which CI runs under "/proto"), the config's `basePath` otherwise. Throws
+ * when a based config's `url` does not end with its base, since canonical and
+ * Open Graph URLs are built from it.
+ */
+export function marketingBasePath(site, env = process.env) {
+    const override = env.VITE_BASE_PATH;
+    const basePath = normalizeBasePath(override ?? site.basePath);
+    if (override === undefined && basePath && !site.url.endsWith(basePath)) {
+        throw new Error(`site.url (${site.url}) must end with basePath (${basePath}): canonical and Open Graph URLs are built from it`);
+    }
+    return basePath;
+}
+export function marketingConfig({ site, pages = [], sitemapHost, extend, env = process.env, }) {
+    const basePath = marketingBasePath(site, env);
+    const listed = pages.filter((page) => page.path !== NOT_FOUND_PAGE.path);
+    const config = {
+        // The base becomes Vite's `base`, so every built asset URL and every
+        // rebased `url(/...)` in the CSS carries it, and the router's
+        // `basepath`, so the router and the prerender both work under it.
+        base: `${basePath}/`,
+        // No `build.cssCodeSplit: false`. Every sheet a site carries, the
+        // package's included, rides in the one base sheet its root route links
+        // (src/styles/base.css), so no component imports a stylesheet and there
+        // is no component bundle to fold. With the flag off, TanStack Start
+        // looks for the `style.css` that folding emits, finds none, and fails
+        // the build (ATE-643, as artifactConfig found first). A site that gives
+        // a component its own stylesheet again sets the flag through `extend`.
+        plugins: [
+            tanstackStart({
+                ...(basePath ? { router: { basepath: basePath } } : {}),
+                prerender: { enabled: true, crawlLinks: true },
+                pages: [NOT_FOUND_PAGE, ...listed],
+                sitemap: {
+                    // A based cut is a preview under another project's host, noindex
+                    // by that host's header rule, so it ships no sitemap.
+                    enabled: !basePath,
+                    host: sitemapHost ?? new URL(site.url).origin,
+                },
+            }),
+            react(),
+        ],
+        resolve: {
+            alias: {
+                // The site's src, from the directory Vite is run in: this file
+                // lives in the package, so nothing here can be found relative to it.
+                "@": resolve(process.cwd(), "./src"),
+            },
+        },
+        // @atelic-action/ui ships TSX and CSS as written, so the prerender's
+        // server build has to compile it rather than hand it to Node.
+        ssr: {
+            noExternal: ["@atelic-action/ui"],
+        },
+    };
+    return extend ? mergeConfig(config, extend) : config;
+}