@pracht/vite-plugin 0.10.0 → 0.11.1

package/dist/{pages-router-KcCRkhnf.mjs → pages-router-MA9rOl88.mjs}

@@ -46,6 +46,7 @@ function namedDeclarationRe(exportName) {
 	return new RegExp(`export\\s+(?:async\\s+)?(?:function|const|let|var)\\s+${exportName}\\b`);
 }
 const HEAD_DECLARATION_RE = namedDeclarationRe("head");
+const HEADERS_DECLARATION_RE = namedDeclarationRe("headers");
 const STATIC_PATHS_DECLARATION_RE = namedDeclarationRe("getStaticPaths");
 const EXPORT_BLOCK_RE = /export\s*\{([^}]*)\}\s*(?:from\s*["'][^"']+["'])?/g;
 const EXPORT_ALL_RE = /export\s+\*\s+from\b/;
@@ -168,10 +169,13 @@ function exportSpecifiersInclude(specifiers, exportName) {
 * Whether `source` exports `exportName`, via a declaration, an export block,
 * or an `export *` re-export (which could expose anything, so it counts).
 *
-* Comments and strings are masked first, so prose or a string literal
-* mentioning the name cannot produce a false positive.
+* Ordinary TS/JS is parsed exactly, including string-literal export names.
+* Custom syntaxes fall back to masked lexical detection so prose or a string
+* literal mentioning the name cannot produce a false positive.
 */
 function detectNamedExport(source, exportName, declarationRe) {
+	const parsedResult = inspectParsedModule(source, exportName);
+	if (parsedResult !== void 0) return parsedResult;
 	const analysisSource = maskCommentsAndStrings(source);
 	if (declarationRe.test(analysisSource) || variableDeclarationExports(analysisSource, exportName)) return true;
 	for (const match of analysisSource.matchAll(EXPORT_BLOCK_RE)) if (exportSpecifiersInclude(match[1], exportName)) return true;
@@ -180,6 +184,10 @@ function detectNamedExport(source, exportName, declarationRe) {
 function detectHeadExport(source) {
 	return detectNamedExport(source, "head", HEAD_DECLARATION_RE);
 }
+/** Whether the route or shell module exports document response headers. */
+function detectHeadersExport(source) {
+	return detectNamedExport(source, "headers", HEADERS_DECLARATION_RE);
+}
 /**
 * Whether the route module exports `getStaticPaths()`.
 *
@@ -195,25 +203,25 @@ function detectStaticPathsExport(source) {
 function isSyntaxNode(value) {
 	return typeof value === "object" && value !== null && typeof value.type === "string";
 }
-function bindingIncludesLoader(node) {
+function bindingIncludesName(node, exportName) {
 	if (!isSyntaxNode(node)) return false;
-	if (node.type === "Identifier") return node.name === "loader";
-	if (node.type === "AssignmentPattern") return bindingIncludesLoader(node.left);
-	if (node.type === "RestElement") return bindingIncludesLoader(node.argument);
-	if (node.type === "ArrayPattern") return Array.isArray(node.elements) && node.elements.some(bindingIncludesLoader);
+	if (node.type === "Identifier") return node.name === exportName;
+	if (node.type === "AssignmentPattern") return bindingIncludesName(node.left, exportName);
+	if (node.type === "RestElement") return bindingIncludesName(node.argument, exportName);
+	if (node.type === "ArrayPattern") return Array.isArray(node.elements) && node.elements.some((element) => bindingIncludesName(element, exportName));
 	if (node.type === "ObjectPattern") return Array.isArray(node.properties) && node.properties.some((property) => {
 		if (!isSyntaxNode(property)) return false;
-		return property.type === "RestElement" ? bindingIncludesLoader(property.argument) : bindingIncludesLoader(property.value);
+		return property.type === "RestElement" ? bindingIncludesName(property.argument, exportName) : bindingIncludesName(property.value, exportName);
 	});
 	return false;
 }
-function exportedNameIsLoader(node) {
+function exportedNameMatches(node, exportName) {
 	if (!isSyntaxNode(node)) return false;
-	if (node.type === "Identifier") return node.name === "loader";
-	if (node.type === "StringLiteral") return node.value === "loader";
+	if (node.type === "Identifier") return node.name === exportName;
+	if (node.type === "StringLiteral") return node.value === exportName;
 	return false;
 }
-function inspectParsedModule(source) {
+function inspectParsedModule(source, exportName) {
 	for (const plugins of [["typescript", "jsx"], ["typescript"]]) {
 		let body;
 		try {
@@ -230,19 +238,19 @@ function inspectParsedModule(source) {
 				continue;
 			}
 			if (statement.type !== "ExportNamedDeclaration" || statement.exportKind === "type") continue;
-			if (Array.isArray(statement.specifiers) && statement.specifiers.some((specifier) => isSyntaxNode(specifier) && specifier.exportKind !== "type" && exportedNameIsLoader(specifier.exported))) return true;
+			if (Array.isArray(statement.specifiers) && statement.specifiers.some((specifier) => isSyntaxNode(specifier) && specifier.exportKind !== "type" && exportedNameMatches(specifier.exported, exportName))) return true;
 			const declaration = statement.declaration;
 			if (!isSyntaxNode(declaration)) continue;
 			if (declaration.declare === true || declaration.type.startsWith("TS")) continue;
 			if (declaration.type === "VariableDeclaration") {
-				if (Array.isArray(declaration.declarations) && declaration.declarations.some((declarator) => isSyntaxNode(declarator) && bindingIncludesLoader(declarator.id))) return true;
-			} else if (bindingIncludesLoader(declaration.id)) return true;
+				if (Array.isArray(declaration.declarations) && declaration.declarations.some((declarator) => isSyntaxNode(declarator) && bindingIncludesName(declarator.id, exportName))) return true;
+			} else if (bindingIncludesName(declaration.id, exportName)) return true;
 		}
 		return false;
 	}
 }
 function detectLoaderExport(source) {
-	const parsedResult = inspectParsedModule(source);
+	const parsedResult = inspectParsedModule(source, "loader");
 	if (parsedResult !== void 0) return parsedResult;
 	try {
 		const [imports, exports] = parse$1(source);
@@ -309,6 +317,26 @@ function createRouteHeadHints(routesDir, options = {}) {
 	}
 	return hints;
 }
+function createRouteHeadersHints(routesDir, options = {}) {
+	const files = [];
+	const hints = {};
+	const additionalExtensions = normalizeAdditionalExtensions(options.additionalExtensions);
+	scanRouteFiles(routesDir, files, withAdditionalExtensions(DEFAULT_ROUTE_EXTENSIONS, additionalExtensions));
+	for (const file of files) {
+		const extension = extname(file);
+		const hasHeaders = extension === ".md" || extension === ".mdx" || additionalExtensions.includes(extension) || detectHeadersExport(readFileSync(file, "utf-8"));
+		const relativeToRoutesDir = toPosixPath(relative(routesDir, file));
+		const routeRootPrefix = options.rootRelativePrefix?.replace(/\/$/, "");
+		const keys = /* @__PURE__ */ new Set();
+		if (options.appFileDir) {
+			const relativeToAppFile = toPosixPath(relative(options.appFileDir, file));
+			keys.add(relativeToAppFile.startsWith(".") ? relativeToAppFile : `./${relativeToAppFile}`);
+		}
+		if (routeRootPrefix) keys.add(`${routeRootPrefix}/${relativeToRoutesDir}`);
+		for (const key of keys) hints[key] = hasHeaders;
+	}
+	return hints;
+}
 /**
 * Per-route-file `getStaticPaths()` presence, keyed the same way as the loader
 * and head hints.
@@ -375,6 +403,7 @@ function scan(dir, root, pages, pageExtensions, shellExtensions, additionalExten
 		const revalidate = extractRevalidateSeconds(analysisSource, rel);
 		const hasLoader = detectLoaderExport(analysisSource);
 		const hasHead = ext === ".md" || ext === ".mdx" || additionalExtensions.has(ext) || detectHeadExport(analysisSource);
+		const hasHeaders = ext === ".md" || ext === ".mdx" || additionalExtensions.has(ext) || detectHeadersExport(analysisSource);
 		pages.push({
 			absolutePath: abs,
 			relativePath: rel,
@@ -387,7 +416,8 @@ function scan(dir, root, pages, pageExtensions, shellExtensions, additionalExten
 			revalidateSeconds: revalidate.seconds,
 			hasRevalidateExport: revalidate.present,
 			hasLoader,
-			hasHead
+			hasHead,
+			hasHeaders
 		});
 	}
 }
@@ -585,4 +615,4 @@ function generateRoutesFile(pagesDir, outputPath, options) {
 	].join("\n"), "utf-8");
 }
 //#endregion
-export { sortRoutes as a, createRouteStaticPathsHints as c, extensionGlob as d, normalizeAdditionalExtensions as f, scanPagesDirectory as i, DEFAULT_ROUTE_EXTENSIONS as l, generatePagesManifestSource as n, createRouteHeadHints as o, withAdditionalExtensions as p, generateRoutesFile as r, createRouteLoaderHints as s, filePathToRoutePath as t, LEGACY_BARE_ROUTE_EXTENSIONS as u };
+export { sortRoutes as a, createRouteLoaderHints as c, LEGACY_BARE_ROUTE_EXTENSIONS as d, extensionGlob as f, scanPagesDirectory as i, createRouteStaticPathsHints as l, withAdditionalExtensions as m, generatePagesManifestSource as n, createRouteHeadHints as o, normalizeAdditionalExtensions as p, generateRoutesFile as r, createRouteHeadersHints as s, filePathToRoutePath as t, DEFAULT_ROUTE_EXTENSIONS as u };

package/dist/pages-router.d.mts

@@ -12,6 +12,7 @@ interface ScannedPage {
   hasRevalidateExport?: boolean;
   hasLoader?: boolean;
   hasHead?: boolean;
+  hasHeaders?: boolean;
 }
 interface PagesRouterOptions {
   pagesDir: string;

package/dist/pages-router.mjs

@@ -1,2 +1,2 @@
-import { a as sortRoutes, i as scanPagesDirectory, n as generatePagesManifestSource, r as generateRoutesFile, t as filePathToRoutePath } from "./pages-router-KcCRkhnf.mjs";
+import { a as sortRoutes, i as scanPagesDirectory, n as generatePagesManifestSource, r as generateRoutesFile, t as filePathToRoutePath } from "./pages-router-MA9rOl88.mjs";
 export { filePathToRoutePath, generatePagesManifestSource, generateRoutesFile, scanPagesDirectory, sortRoutes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pracht/vite-plugin",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Vite plugin for Pracht apps with virtual modules, dev SSR, prerendering, route inspection, and multi-adapter builds.",
   "keywords": [
     "pracht",
@@ -25,7 +25,8 @@
     "directory": "packages/vite-plugin"
   },
   "files": [
-    "dist"
+    "dist",
+    "virtual.d.ts"
   ],
   "type": "module",
   "exports": {
@@ -36,6 +37,9 @@
     "./pages-router": {
       "types": "./dist/pages-router.d.mts",
       "default": "./dist/pages-router.mjs"
+    },
+    "./virtual": {
+      "types": "./virtual.d.ts"
     }
   },
   "publishConfig": {
@@ -46,9 +50,9 @@
     "@preact/preset-vite": "^2.10.5",
     "@prefresh/vite": "^2.0.0",
     "es-module-lexer": "^1.7.0",
-    "@pracht/adapter-node": "0.4.1",
-    "@pracht/capabilities": "0.2.0",
-    "@pracht/core": "0.15.0",
+    "@pracht/adapter-node": "0.4.2",
+    "@pracht/capabilities": "0.3.0",
+    "@pracht/core": "0.16.0",
     "@pracht/preact-ssr-precompile": "0.1.3"
   },
   "peerDependencies": {

package/virtual.d.ts

@@ -0,0 +1,255 @@
+declare module "virtual:pracht/server" {
+  const mod: { fetch: (request: Request, env: any, ctx: any) => Promise<Response> };
+  export default mod;
+}
+
+declare module "virtual:pracht/client" {}
+
+declare module "virtual:pracht/capabilities" {
+  import type {
+    CapabilityBrowserCallOptions,
+    CapabilityCallOptionsFor,
+    CapabilityInputArgs,
+    CapabilityInputFor,
+    CapabilityOutputFor,
+    HasRegisteredCapabilities,
+    HttpCapabilityName,
+    NonDestructiveCapabilityName,
+    Register,
+  } from "@pracht/core";
+  import type {
+    CapabilityEffect,
+    CapabilityEnvelope,
+    CapabilityErrorPayload,
+    CapabilityIssue,
+  } from "@pracht/capabilities";
+
+  // The envelope types are the protocol package's — re-exported so existing
+  // `import type { ... } from "virtual:pracht/capabilities"` keeps working.
+  export type { CapabilityEnvelope, CapabilityErrorPayload, CapabilityIssue };
+
+  export interface CallCapabilityOptions extends CapabilityBrowserCallOptions {
+    /**
+     * Confirmation token for committing a destructive capability, taken from
+     * the prior call's `confirmation_required` error envelope. Sets the
+     * confirmation header for you. A destructive call must either prepare with
+     * `{ prepare: true }` or commit with this token once `pracht typegen` has
+     * registered its effect class.
+     */
+    confirm?: string;
+    /**
+     * Start the prepare half of a destructive call. The server returns a
+     * `confirmation_required` envelope containing the token; repeat the call
+     * with `confirm` to commit. Typed destructive calls require exactly one of
+     * `prepare: true` or `confirm`.
+     */
+    prepare?: true;
+    /**
+     * Successful non-`read` calls revalidate the active route's data
+     * automatically; pass `false` to skip it for this call.
+     */
+    revalidate?: boolean;
+  }
+
+  /**
+   * Destructive calls require exactly one of `{ prepare: true }` or
+   * `{ confirm }`. `prepare` is not sent over the wire; the dispatcher uses it
+   * only to remove any confirmation token inherited through caller-supplied
+   * headers. The server is what refuses to run the unconfirmed call.
+   */
+  type OptionsFor<TName extends string> = CapabilityCallOptionsFor<TName, CallCapabilityOptions>;
+
+  /**
+   * HTTP endpoints of http-exposed capabilities, keyed by capability name.
+   *
+   * Has a **null prototype**, so a capability named `toString` cannot shadow an
+   * inherited member during lookup. Index it and enumerate it as usual, but
+   * reach for `Object.hasOwn(capabilityEndpoints, name)` rather than
+   * `capabilityEndpoints.hasOwnProperty(name)` — there is no `Object.prototype`
+   * to inherit that from. TypeScript cannot express the missing prototype, so
+   * the `Record` type below overstates what is available.
+   */
+  export const capabilityEndpoints: Record<
+    string,
+    { method: string; path: string; effect: CapabilityEffect | null }
+  >;
+
+  interface TypedCallCapability {
+    /**
+     * Names that cannot be `destructive`. Listed first and with an optional
+     * options argument, so it is always arity-compatible with a one- or
+     * two-argument call — which makes it the signature that reports what is
+     * wrong with an unresolvable name, instead of an argument count.
+     */
+    <TName extends NonDestructiveCapabilityName>(
+      name: TName,
+      ...args: CapabilityInputArgs<TName, CallCapabilityOptions>
+    ): Promise<CapabilityEnvelope<CapabilityOutputFor<TName>>>;
+    /** Possibly `destructive`: the prepare marker or the token is required. */
+    <TName extends HttpCapabilityName>(
+      name: TName,
+      input: CapabilityInputFor<TName>,
+      options: OptionsFor<TName>,
+    ): Promise<CapabilityEnvelope<CapabilityOutputFor<TName>>>;
+  }
+
+  interface UntypedCallCapability {
+    <T = unknown>(
+      name: string,
+      input?: unknown,
+      opts?: CallCapabilityOptions,
+    ): Promise<CapabilityEnvelope<T>>;
+  }
+
+  /**
+   * Invoke an http-exposed capability from the browser via its HTTP projection.
+   * Once `pracht typegen` has registered the capability graph on
+   * `Register["capabilities"]`, the name, input, output, and confirmation
+   * requirement all come from the registration: a private capability, an
+   * unknown name, a mismatched input, or a `destructive` call without an
+   * explicit prepare/commit choice are compile errors rather than runtime
+   * envelopes.
+   *
+   * Declared as a conditionally-typed value rather than as an overload pair
+   * whose fallback `name` resolves to `never`. That fallback survived overload
+   * resolution and absorbed anything arity filtering rejected, so every
+   * mistake — including a `destructive` call that merely forgot its options —
+   * came back as `'"notes.purge"' is not assignable to 'never'`: blaming the
+   * name, never naming the cause. Here the untyped form is simply absent for a
+   * registered app, and the two typed signatures split by effect class so that
+   * an unresolvable name is always arity-compatible with the first one and gets
+   * reported as a name.
+   *
+   * A dynamic name is no longer accepted once typegen has run; assert it with
+   * `name as HttpCapabilityName` when the name genuinely comes from data, and
+   * keep in mind the runtime still answers an unknown one with
+   * `unknown_capability`.
+   */
+  export const callCapability: HasRegisteredCapabilities extends true
+    ? TypedCallCapability
+    : UntypedCallCapability;
+
+  /**
+   * The same calls as `callCapability`, reached as a nested object built from
+   * the dotted capability names — `capabilities.notes.search({ query })`.
+   * Private capabilities are simply absent from it. Because the members are
+   * real property accesses, a typo here reports as "Property 'serach' does not
+   * exist … Did you mean 'search'?" — which `callCapability("notes.serach")`
+   * cannot do, since a string literal argument has no such suggestion.
+   *
+   * Current typegen output declares the nested client explicitly, so each leaf
+   * carries the capability's title and description as JSDoc. The mapped type
+   * below remains the compatibility fallback for older generated files.
+   *
+   * Identical runtime path to `callCapability` (same endpoint table, same
+   * settled event, same revalidation), so nothing forks between the two.
+   */
+  export const capabilities: PrachtCapabilityClient;
+
+  type GeneratedCapabilityClient = Register extends { capabilityClient: infer TClient }
+    ? TClient
+    : never;
+
+  /**
+   * Dotted names expanded into nested namespaces, http-exposed only. Current
+   * typegen output supplies the explicit client (including JSDoc); older
+   * generated files use the mapped fallback. Before typegen has run, every
+   * segment stays callable with unknown input/output.
+   */
+  export type PrachtCapabilityClient = HasRegisteredCapabilities extends true
+    ? [GeneratedCapabilityClient] extends [never]
+      ? CapabilityClientNode<HttpCapabilityName>
+      : GeneratedCapabilityClient
+    : Record<string, UntypedCapabilityClientNode>;
+
+  interface UntypedCapabilityClientNode {
+    <T = unknown>(input?: unknown, opts?: CallCapabilityOptions): Promise<CapabilityEnvelope<T>>;
+    [segment: string]: UntypedCapabilityClientNode;
+  }
+
+  type CapabilityMethod<TName extends string> = (
+    ...args: CapabilityInputArgs<TName, OptionsFor<TName>>
+  ) => Promise<CapabilityEnvelope<CapabilityOutputFor<TName>>>;
+
+  /**
+   * `Prefix` carries the already-consumed path so a leaf can look its own full
+   * dotted name back up in the flat registration map.
+   */
+  type CapabilitySegment<
+    TAll extends string,
+    TPrefix extends string,
+  > = TAll extends `${TPrefix}${infer TRest}`
+    ? TRest extends `${infer THead}.${string}`
+      ? THead
+      : TRest
+    : never;
+
+  /**
+   * A name that is also a prefix of another (`notes` alongside `notes.search`)
+   * cannot be both a function and a namespace. The runtime builder resolves
+   * that by letting the namespace win, so the type must too — otherwise
+   * `capabilities.notes(...)` would typecheck and throw at runtime. The
+   * shadowed name stays callable through `callCapability()`, and
+   * `pracht verify` warns about it.
+   */
+  type CapabilityClientNode<TAll extends string, TPrefix extends string = ""> = {
+    [TSeg in CapabilitySegment<TAll, TPrefix>]: [
+      Extract<TAll, `${TPrefix}${TSeg}.${string}`>,
+    ] extends [never]
+      ? CapabilityMethod<`${TPrefix}${TSeg}`>
+      : CapabilityClientNode<TAll, `${TPrefix}${TSeg}.`>;
+  };
+
+  /**
+   * Call state for a user-triggered capability call — a button, a search box, a
+   * picker. `call()` takes the same arguments as `callCapability` minus the
+   * name, and resolves to the same envelope.
+   *
+   * This is a mutation-shaped hook, not a fetch-on-render one: it dispatches
+   * when you call it, never during render. For data a page needs on load, run
+   * the capability in a `loader` with `invokeCapability()` — that result is
+   * server-rendered into the HTML and revalidates automatically after
+   * non-`read` calls, which a render-time fetch cannot do.
+   *
+   * ```tsx
+   * const search = useCapability("notes.search");
+   * await search.call({ query });
+   * // search.data / search.error / search.pending / search.reset()
+   * ```
+   *
+   * Concurrent calls are last-one-wins: an earlier response that arrives after
+   * a later one is discarded, so typing into a search box cannot show a stale
+   * result. `data` stays visible while a follow-up call is `pending`.
+   * It also remains the most recent successful result when that follow-up fails;
+   * only `reset()` or changing the capability name clears it.
+   */
+  export function useCapability<TName extends HttpCapabilityName>(
+    name: TName,
+  ): PrachtCapabilityHook<TName>;
+
+  export interface PrachtCapabilityHook<TName extends HttpCapabilityName> {
+    call: (
+      ...args: CapabilityInputArgs<TName, OptionsFor<TName>>
+    ) => Promise<CapabilityEnvelope<CapabilityOutputFor<TName>>>;
+    /** Data from the most recent successful call, until `reset()`. */
+    data: CapabilityOutputFor<TName> | undefined;
+    /** Error payload from the most recent failed call, until `reset()`. */
+    error: CapabilityErrorPayload | undefined;
+    /** Whether a call is in flight. */
+    pending: boolean;
+    /** Clear `data`/`error`/`pending` and abandon any in-flight result. */
+    reset: () => void;
+  }
+}
+
+declare module "virtual:pracht/webmcp" {
+  /** Registers WebMCP page tools; returns false when the API is unavailable. */
+  export function registerPrachtWebmcpTools(): boolean;
+}
+
+// Preserve the ambient declaration shipped with Pracht's compatibility-level
+// `.tsrx` discovery. Other custom formats provide their own declaration.
+declare module "*.tsrx" {
+  const mod: Record<string, unknown>;
+  export = mod;
+}