create-pracht 0.7.0 → 0.7.1

package/README.md

@@ -17,7 +17,7 @@ npm run dev
 - Detects the active package manager from the current environment.
 - Lets the user choose between the Node.js, Cloudflare, Vercel, Netlify, and static adapters.
 - Optionally wires up Tailwind CSS (`tailwindcss` + `@tailwindcss/vite`, a global stylesheet, and the shell import).
-- Scaffolds a minimal app with a route manifest or pages router, shell, home route, not-found page, a sample API route for serverful adapters, runnable project README, TypeScript typecheck script, and (with agent tooling enabled) agent instructions.
+- Scaffolds a minimal app with a route manifest or pages router, shell, home route, not-found page, a sample API route for serverful adapters, runnable project README, TypeScript typecheck script, browser-aware package resolution that rejects server-only root exports in client code, and (with agent tooling enabled) agent instructions.
 - Manifest scaffolds include a commented-out `constraints` example in `src/routes.ts`, ready for `pracht verify`.
 - The generated `.gitignore` keeps `.pracht/app-graph.json` committable, and the README and agent instructions cover the `pracht verify` / `pracht plan` / `pracht report` loop.
 - Every standalone pnpm scaffold includes a narrow lifecycle-script policy for
@@ -100,7 +100,7 @@ writing it would leave a config in the repo that nothing in the repo reads.
 
 - `dev` -> `pracht dev`
 - `build` -> `pracht build`
-- `typecheck` -> `tsc --noEmit`
+- `typecheck` -> checks the server-capable base TypeScript program, then the browser-conditioned routes, shells, and islands in `tsconfig.client.json`
 
 Node starters also include:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pracht",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Interactive and scriptable starter CLI for creating full-stack Preact apps with Pracht.",
   "keywords": [
     "pracht",

package/skills/add-capabilities/SKILL.md

@@ -176,11 +176,15 @@ export const CAPABILITIES = ["notes.search"];
 
 `CAPABILITIES` must be an inline array of non-empty registered names and cannot
 appear on `_app` or `404`. In a manifest, group capability lists are additive.
+
 Unknown names, capabilities without `expose.webmcp`, and activation on
 `hydration: "none"` routes are rejected. Initial hydration registers the matched
 route's set; every committed client navigation replaces it, so never assume a
 tool exposed on one page persists globally.
 
+In dev, the tab's `pracht_page_tools` WebMCP tool lists the tools active on
+the route and why a declared capability is not one.
+
 Each `agents` sub-option is independent — add only what the app uses. Web Bot
 Auth `policy: "require"` gates capability HTTP endpoints (not pages or API
 routes) with `401 agent_required`; `agentPolicy: "require"` on a capability
@@ -381,14 +385,13 @@ same prepare/commit round trip as HTTP, with the token in the call's
 `createCapabilityTestHost()` from `@pracht/core` covers the same pipeline in
 unit tests, without a server.
 
-WebMCP specifics `pracht verify` checks: tool names must fit the spec's
-grammar (1–128 ASCII `[a-zA-Z0-9_.-]`); an effective `agentPolicy: "require"`
-makes a page tool dead (unsigned browser fetches always 401 — warned);
-descriptions have advisory budgets (~500 chars per tool, ~150 per schema
-parameter). Hosts: the ChatGPT desktop browser enables the API itself, but
-stable Chrome/Edge visitors only get `document.modelContext` if the page head
-carries an origin-trial token — the docs site's capabilities page shows the
-shell `head()` recipe.
+WebMCP: names must fit the draft's 1–128 ASCII `[a-zA-Z0-9_.-]` grammar;
+Chrome advises 30 chars/name, 500/tool description, 150/parameter description,
+and 1.5K/result. `pracht verify` checks static limits; bound outputs yourself.
+Stable Chrome needs an origin-trial token. No mainstream production agent
+consumes these tools yet, so retain HTTP or remote MCP. See the capabilities
+site page for current compatibility. An effective `agentPolicy: "require"`
+always 401s unsigned page-tool calls and is warned.
 
 To audit what the whole agent surface exposes, run `/audit-agent-surface`.
 

package/skills/audit-agent-surface/SKILL.md

@@ -89,7 +89,8 @@ For every exposed capability, ask whether the exposure is deliberate:
   the tool is dead — every call 401s. Also check that capabilities returning
   user-generated or third-party content set
   `expose.webmcp: { untrustedContent: true }` so hosts treat the output as
-  untrusted.
+  untrusted. Flag `exposedTo` and outputs above 1.5K. Consequential work is
+  `destructive`, so never WebMCP.
 - Private capabilities used as building blocks: `invokeCapability()` runs their
   named middleware but **not** app-level `api.middleware`. Their named
   middleware is the only authorization seam — flag private capabilities with an

package/skills/audit-bundles/SKILL.md

@@ -181,6 +181,16 @@ pracht injects per route. Compare `<link rel="stylesheet">` tags in
 that wants Preact inside its own chunks or places `frameworkChunkGroups()`
 itself.
 
+Pracht contributes one group to the **server** build too: each island becomes
+its own chunk, so a route that does not fully hydrate can resolve its CSS from
+that build without inheriting the server entry's merged stylesheet. An app that
+configures SSR chunking composes with it the same way the client side does; a
+group that pulls islands back into the entry shows up as extra `<link
+rel="stylesheet">` tags on static pages, and the build warns.
+
+`build.cssCodeSplit: false` is rejected outright — there is no `index.html` to
+link the single stylesheet it produces, so every page would ship without one.
+
 ## Step 7: Report
 
 Three sections:

package/skills/pracht-debug/SKILL.md

@@ -36,6 +36,7 @@ Reach for these before deep manual inspection:
 | `pracht inspect routes\|api\|build --json` | The resolved graph — never reconstruct it from source |
 | `GET /_pracht` (JSON at `/_pracht.json`) | Same graph from a running dev server, no CLI needed |
 | `Server-Timing` on dev SSR responses | `mw` / `loader` / `render` durations in ms — which phase is slow |
+| `pracht_*` WebMCP page tools in the open tab | Tab-scoped view from an agent-driven browser: `pracht_route`, `pracht_loader_data`, `pracht_islands`, `pracht_last_error`, `pracht_page_tools` |
 
 `pracht inspect` needs the pracht plugin in the vite config; `inspect build`
 needs a prior `pracht build`. Under a Vite deploy base, prefix `/_pracht` with
@@ -44,6 +45,18 @@ pracht MCP server is registered (docs/MCP.md), prefer the
 `inspect_routes`/`inspect_api`/`doctor`/`verify` MCP tools — same payloads,
 structured results.
 
+When you are driving a browser against `pracht dev` with a WebMCP-compatible
+test harness or host, ask the tab before reading logs: every dev document registers read-only
+`pracht_*` page tools with `document.modelContext`. `pracht_route` gives the
+matched route, files, render/hydration mode, and middleware; `pracht_loader_data`
+the data the page holds now (`{ path: "a.0.b" }` narrows it; islands/none routes
+answer with the route-state request to make instead); `pracht_islands` each
+island's file, strategy, props, and hydration status; `pracht_last_error` the
+structured server error behind an overlay or `ErrorBoundary` plus recent client
+errors; `pracht_page_tools` the app's active WebMCP tools on the route. All
+resolve to `{ ok, data }` / `{ ok: false, error }` envelopes and follow client
+navigation.
+
 ## Checklist
 
 Work in order; stop at the root cause.
@@ -94,7 +107,10 @@ Work in order; stop at the root cause.
   component (via Preact's `options.__m` hook). Compare server HTML against
   client output. Usual causes: date/time differences, browser-only APIs during
   SSR (`window`, `document`, `localStorage`), conditional rendering on client
-  state — or two copies of `@pracht/core` in the SSR module graph. The tell for
+  state — or, on Preact 10, a suspending boundary resolving to zero or multiple
+  DOM nodes. Preact 11 supports those boundary shapes, so Pracht skips that
+  legacy diagnostic there. Another cause is two copies of `@pracht/core` in
+  the SSR module graph. The tell for
   that last one: in the server-rendered HTML of *every* page, `useLocation()`
   returns `/`, `useParams()` returns `{}`, and `useRouteData()` returns
   `undefined`, while the hydrated client is correct — provider and hooks hold

package/skills/pre-deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pre-deploy
-version: 1.4.0
+version: 1.5.0
 description: |
   Adapter-aware pre-deployment checklist (Node, Cloudflare Workers, Vercel, static)
   for the failures that only surface in production: missing env vars, Node-only
@@ -55,6 +55,20 @@ reports errors, stop here**; the remaining checks will be noisy false
 positives. Stale generated typed-route files block deployment; if the app does
 not use them yet, note that `typegen --check` is optional.
 
+If `pracht inspect agents --json` reports any WebMCP exposure, run the live
+browser boundary too. Point it at the already-started preview, or let it own the
+server lifecycle:
+
+```bash
+pracht verify webmcp --start "pracht preview" --json
+```
+
+CI must install a pinned Chrome 150+ build and pass its executable with
+`--browser`; the verifier never silently downloads one. Treat unsupported API,
+startup/registration failure, and graph drift as deployment errors. Do not add
+`--scenario` unless the repository already supplies an explicitly safe WebMCP
+eval scenario.
+
 For a PR deploy, `pracht report --base origin/main` produces a markdown summary
 (graph diff + verify + budgets) worth attaching.
 

package/src/index.js

@@ -754,6 +754,7 @@ async function buildProjectFiles({
     }),
     "vite.config.ts": createViteConfig(adapter, router, tailwind),
     "tsconfig.json": createBaseTSConfig(adapter),
+    "tsconfig.client.json": createClientTSConfig(router),
   };
 
   // A static export has no server, so an API route would be a hard build
@@ -871,7 +872,7 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
   const scripts = {
     build: "pracht build",
     dev: "pracht dev",
-    typecheck: "tsc --noEmit",
+    typecheck: "tsc --noEmit && tsc --noEmit --project tsconfig.client.json",
   };
 
   if (adapter.id === "node") {
@@ -1164,6 +1165,27 @@ function createBaseTSConfig(_adapter) {
   return `${JSON.stringify(config, null, 2)}\n`;
 }
 
+function createClientTSConfig(router) {
+  const config = {
+    extends: "./tsconfig.json",
+    compilerOptions: {
+      customConditions: ["browser"],
+    },
+    include:
+      router === "pages"
+        ? ["src/pages/**/*", "src/islands/**/*"]
+        : ["src/routes/**/*", "src/shells/**/*", "src/islands/**/*"],
+  };
+
+  // Pages route modules are shared with the browser, but these two convention
+  // files are server-only. The base program still checks the whole project.
+  if (router === "pages") {
+    config.exclude = ["src/pages/**/_app.config.*", "src/pages/**/_middleware.*"];
+  }
+
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
 function createHealthRoute(adapter) {
   return [
     "export function GET() {",
@@ -1606,6 +1628,10 @@ function createAgentInstructions({
     lines.push("- `src/api/` — API route handlers");
   }
   lines.push(`- \`vite.config.ts\` — Vite config with the ${adapter.label} adapter`);
+  lines.push("- `tsconfig.json` — server-capable whole-project TypeScript checks");
+  lines.push(
+    "- `tsconfig.client.json` — browser-conditioned checks for routes, shells, islands, and their imports",
+  );
 
   if (tailwind) {
     lines.push("- `src/styles/global.css` — Tailwind CSS entry stylesheet, imported by the shell");
@@ -1781,6 +1807,11 @@ function createReadme({
     lines.push("- `src/api/health.ts` is a sample API route.");
   }
 
+  lines.push("- `tsconfig.json` — server-capable whole-project TypeScript checks.");
+  lines.push(
+    "- `tsconfig.client.json` — browser-conditioned checks for routes, shells, islands, and their imports.",
+  );
+
   if (tailwind) {
     lines.push("- `src/styles/global.css` is the Tailwind CSS entry, imported by the shell.");
   }