@webjsdev/cli 0.10.64 → 0.10.66

package/bin/webjs.js

@@ -1577,7 +1577,16 @@ async function main() {
       let tscPath;
       try {
         const req = createRequire(join(cwd, 'package.json'));
-        tscPath = req.resolve('typescript/bin/tsc');
+        // The `tsc` bin the package itself declares. TypeScript 7 (the native
+        // compiler) restricts its subpaths with `exports`, so
+        // `typescript/bin/tsc` no longer resolves; its package.json does, in
+        // every major, and names the bin. Its launcher spawns the native
+        // binary: about a quarter of the 6.x compiler's memory, five times
+        // faster.
+        const pkgPath = req.resolve('typescript/package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.tsc;
+        tscPath = bin ? join(dirname(pkgPath), bin) : req.resolve('typescript/bin/tsc');
       } catch {
         console.error(
           'webjs typecheck: TypeScript is not installed in this project.\n' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.64",
+  "version": "0.10.66",
   "type": "module",
   "description": "The CLI for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Runs the dev and production servers, scaffolds apps, validates conventions, and drives the database. Node 24+ or Bun.",
   "bin": {
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "@webjsdev/mcp": "^0.1.0",
-    "@webjsdev/server": "^0.8.79",
+    "@webjsdev/server": "^0.8.81",
     "@webjsdev/ui": "^0.3.15"
   },
   "publishConfig": {

package/templates/.agents/skills/webjs/references/components.md

@@ -30,7 +30,7 @@ Most of what follows restates widely held component-model advice, ported. Lit's
 
 **4. ARIA state is a hole in `render()`, derived from the same state that drives behaviour.** `aria-expanded=${this.open ? 'true' : 'false'}` cannot disagree with `this.open`. A second function that re-finds the button and calls `setAttribute` can, and does, the first time someone adds a close path that forgets to call it. The same holds for `class`, `?disabled`, and any `.prop`. Two caveats ride this rule:
 
-- Write the string explicitly for a tri-state ARIA attribute. A plain-attribute hole holding `false` serves `aria-expanded="false"` from the server and hydrates to NO attribute, because the client removes an attribute for `null` / `undefined` / `false` while the server stringifies it. `?attr=${bool}` is not a substitute, since a boolean binding omits the attribute in BOTH renderers.
+- A plain-attribute hole follows one rule on the server and the client (#1573): `null` / `undefined` omit the attribute, `false` omits it except on an `aria-*` name, where it is written as `"false"`. So `aria-expanded=${this.open}` serves `"true"` / `"false"` and hydrates unchanged, and `aria-current=${active ? 'page' : null}` omits the attribute on an inactive link. `?attr=${bool}` is not a substitute for a tri-state ARIA attribute, since a boolean binding omits the attribute when false.
 - A hole commits on the next render, one microtask later. The one place a direct write is still correct is a synchronous snapshot read such as `webjs:before-cache`, where the router reads `outerHTML` in the same task. That is a documented exception, not the normal path.
 
 **5. Behaviour needs an importable surface, or its test is a copy of it.** An inline `<script>` in a layout has no module identity, so a browser test cannot import it. It can only transcribe the listener into the test file and assert against the transcription, which then needs a SECOND test to grep the original for drift. Two tests, neither running shipping code. A component is importable, so its browser test mounts the real element and drives real events. A page or layout may still carry an inline `<script>`, but only for pre-paint boot work no module can do: reading a stored theme before first paint so the wrong palette never flashes, or measuring the header height into a CSS custom property. It must not be interactivity, and WHERE it sits decides how often it runs. The ROOT layout's markup sits OUTSIDE every swap range, so a soft navigation does not re-run its script, which is what makes it the right home for boot work and the wrong home for anything that has to respond to a later navigation. A page or a NESTED layout sits inside the swap range instead, so its script re-executes on every navigation that swaps that range (#1102), which means it has to be idempotent or guard on a flag it sets the first time. Neither shape gives you a listener that simply works, which is what a custom element is for. Under an opt-in CSP the script also needs the nonce from `cspNonce()`. `client-router-and-streaming.md` carries the full re-execution rule.
@@ -402,7 +402,7 @@ A component that does no client-side work renders the same SSR'd HTML with or wi
 - a factory-declared reactive property that is not `{ state: true }`
 - an overridden lifecycle hook (including `renderFallback` / `renderError`)
 - an imported `signal` / `computed` / `watch` / `Task` / `ref` / streaming directive, or `addController` / `requestUpdate`
-- code that runs at module load (a top-level call, non-data `new`, dynamic `import(...)`, top-level `await`); only declarations and `X.register(...)` are allowed. TypeScript types are erased before the analyser reads a module, so an annotation can never be a blocker however call-shaped it looks (`readonly (readonly [number, number, number])[]` is fine)
+- code that runs at module load (a top-level call, non-data `new`, dynamic `import(...)`, top-level `await`); only declarations and `X.register(...)` are allowed. A call inside a declaration does not run at load, so it is not a blocker: an arrow's expression body (`export const usd = (m) => Math.round(m) / MICROS`) and a function parameter default (`function relativeTime(when, now = Date.now())`) are both fine. TypeScript types are erased before the analyser reads a module, so an annotation can never be a blocker however call-shaped it looks (`readonly (readonly [number, number, number])[]` is fine)
 - the dynamic slot READ surface (`slotchange`, `assignedNodes` / `assignedElements` / `assignedSlot`); merely RENDERING a `<slot>` does not ship (the SSR output carries the placed children, so a display-only slotted wrapper is byte-identical without its JS; native-write liveness is consumer-driven and the consumer's tag reference forces the ship)
 - being rendered by a component that itself ships
 

package/templates/.agents/skills/webjs/references/muscle-memory-gotchas.md

@@ -174,7 +174,7 @@ html`<form action=${submitFeedback}><input name="email"></form>`;
 html`<form method="post"><input name="email"></form>`;
 ```
 
-A hole that resolves to `null` is NOT the same as omitting the attribute. `method=${null}` renders `method=""`, which cannot submit and is refused; `?method=${false}` emits nothing at all, so WebJs supplies `method="post"` and the form works. Both leave no attribute in the DOM, which is exactly why the check reads your template rather than the rendered element.
+A plain attribute hole that resolves to `null` or `undefined` omits the attribute on both renderers (#1573), so `method=${null}` and `?method=${false}` both emit nothing and WebJs supplies `method="post"`. An EMPTY string is different: `method=${''}` renders `method=""`, which cannot submit and is refused.
 
 A string stays a string: `action="/search"` and `action=${'/search'}` are unchanged, which is what a search form (`<form method="get" action="/search">`) and a `route.ts` endpoint both want. Other attributes keep their existing stringify behaviour; only a FUNCTION under `action` / `formaction` is claimed.
 

package/templates/.agents/skills/webjs/references/routing-and-pages.md

@@ -138,6 +138,30 @@ export async function generateMetadata(ctx: MetadataContext): Promise<Metadata>
 
 Common fields: `title` (string or `{ template, default, absolute }`), `description`, `keywords`, `metadataBase` (resolves relative URLs in `openGraph` / `twitter` / `alternates` / `icons`), `openGraph`, `twitter`, `robots`, `alternates.canonical`, `icons`, `manifest`, and `jsonLd` (schema.org structured data, single object or array, HTML-safe-escaped automatically). `viewport`, `themeColor`, and `colorScheme` may also be set via a split `export const viewport = { ... }`. `cacheControl` is emitted as a response HEADER (not a `<meta>`); pages default to `no-store`, and any other value enables conditional GET (a weak `ETag` + `304`), `private` included. See https://webjs.dev/docs for the full field list.
 
+### Search and share defaults (SEO)
+
+Set `SITE_URL` (the app's public origin, e.g. `https://shop.example.com`) in production. It is the default `metadataBase`, and with it every page gets, unless it sets its own:
+
+- `<link rel="canonical">` = site URL + the page's pathname (query dropped). Opt one page out with `alternates: { canonical: null }`. Without a site URL no canonical is emitted, because the request host can be set by a client.
+- `og:title` / `og:description` from `title` / `description`, `og:type` `website`, `og:url` = the canonical.
+- `og:image` from the nearest `opengraph-image` route above the page (and `twitter:image` from `twitter-image`), when the page declares no image.
+- `twitter:card`: `summary_large_image` when there is an image, else `summary`.
+
+`openGraph` and `twitter` take Next's shapes: `images` is a string, `URL`, `{ url, width, height, alt, type }` or an array of those (emits `og:image` + `og:image:width` / `height` / `alt`); camelCase keys become snake_case (`siteName` -> `og:site_name`); `publishedTime` / `modifiedTime` / `authors` / `section` / `tags` emit `article:*`. `metadataBase` may be a string or a `URL`.
+
+So a public page needs only a specific title and description:
+
+```ts
+export const metadata: Metadata = {
+  title: 'Opening hours',
+  description: 'When the bakery is open, including public holidays.',
+};
+```
+
+A signed-in or private page says `robots: { index: false }` (put it on the private section's layout and every page below inherits it); `pages()` then leaves it out of the sitemap too.
+
+Structured data goes in `jsonLd` (from `generateMetadata` when it depends on a record): one schema.org object or an array, escaped safely into `<script type="application/ld+json">`.
+
 ## Control-flow throws
 
 From `@webjsdev/core`: throw to short-circuit a page / layout render or a form-bound action.
@@ -225,7 +249,30 @@ The BOUNDARY FILE's own crash (it throws, or fails to import at all) is reported
 Two further consequences: a layout that fetches runs its fetch again on a boundary response, and a `<webjs-suspense>` inside a wrapped layout shows its fallback, because a boundary response is buffered so its status is final before the first byte. A 404 for a URL that matched NO route has no chain to wrap in and stays a bare document.
 - Root-only (in `app/` exactly): `global-error.ts` is the app-wide catch-all after nested `error` boundaries are exhausted and renders its OWN `<!doctype><html><body>` (returned verbatim, so keep it static HTML with no components or hydration). That verbatim document is exactly why it is the one boundary left UNWRAPPED: a second shell would nest inside the root layout's, wrapping it would re-run the code that just threw, and with no boot script it could not soft-swap anyway. `global-not-found.ts` renders for an unmatched-anywhere URL when no `not-found` matches.
 
-Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments and default-export a possibly-async function; `sitemap()` / `sitemapIndex()` from `@webjsdev/server` serialize spec-valid XML.
+Metadata routes (`sitemap.ts`, `robots.ts`, `manifest.ts`, `icon.ts`, `apple-icon.ts`, `opengraph-image.ts`, `twitter-image.ts`) live at app root or static segments (a nested one answers under its segment: `app/blog/opengraph-image.ts` is `/blog/opengraph-image`) and default-export a possibly-async function that receives `{ request, url, siteUrl, pages }`. `siteUrl` is `SITE_URL`, else the request origin. `sitemap` may return an ARRAY of entries (urls may be paths, resolved against `siteUrl`) and `robots` an OBJECT (Next's `MetadataRoute.Robots` shape); the server serializes them. `sitemap()` / `sitemapIndex()` / `robots()` from `@webjsdev/server` are the same serializers, for a route that builds its own Response.
+
+`pages()` lists every public page as sitemap entries: each static page (route groups dropped), each dynamic page that exports `generateSitemapParams()`, and none whose static metadata chain says `robots: { index: false }`. So the sitemap follows the app as pages are added:
+
+```ts
+// app/sitemap.ts
+import type { MetadataRouteContext } from '@webjsdev/server';
+export default async function sitemap({ pages }: MetadataRouteContext) {
+  return pages();
+}
+
+// app/products/[id]/page.ts: list the products this route serves
+export async function generateSitemapParams() {
+  return (await listProducts()).map((p) => ({ params: { id: p.id }, lastModified: p.updatedAt }));
+}
+
+// app/robots.ts
+import type { MetadataRouteContext } from '@webjsdev/server';
+export default function robots({ siteUrl }: MetadataRouteContext) {
+  return { rules: { userAgent: '*', allow: '/', disallow: ['/account', '/api/'] }, sitemap: `${siteUrl}/sitemap.xml` };
+}
+```
+
+`generateSitemapParams()` returns params objects (`[{ id: '1' }]`) or entries carrying them (`[{ params: { id: '1' }, lastModified }]`).
 
 The IMAGE metadata routes (`icon`, `apple-icon`, `opengraph-image`, `twitter-image`) default-export a function returning a `Response` with an explicit `content-type`, so an inline SVG needs no asset file (buildless).
 
@@ -248,7 +295,7 @@ export const metadata = {
 
 Declare a favicon through `metadata.icons` (or a metadata route), never as a hand-written `<link rel="icon">`: only the root layout may write a shell at all (invariant 8), so a hand-written tag is unavailable to every other layout. A `public/favicon.ico` needs no declaration either way, since the framework serves it at the origin root for crawlers that read no markup.
 
-`opengraph-image` and `twitter-image` are NOT auto-linked (a preview image is a per-page editorial choice, not a site-wide default). Point `metadata` at those via `openGraph.images` / `twitter.images`.
+`opengraph-image` and `twitter-image` are LINKED too, Next's behaviour: a page that declares no `openGraph.images` gets `og:image` pointing at the nearest `opengraph-image` route above it (absolute against the site URL), and likewise `twitter:image`. A page that declares its own image keeps it.
 
 ```ts
 // app/opengraph-image.ts  (OG is 1200x630; apple-icon 180x180)
@@ -256,5 +303,5 @@ export default function OgImage() {
   const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">...</svg>`;
   return new Response(svg, { headers: { 'content-type': 'image/svg+xml' } });
 }
-// app/page.ts  ->  export const metadata = { openGraph: { images: ['/opengraph-image'] } };
+// every page without its own image now carries og:image = <site>/opengraph-image
 ```

package/templates/.agents/skills/webjs/references/ui-kit.md

@@ -81,9 +81,9 @@ So the loop is: `add` the component, then query `ui <name>` (MCP) or
 ## Inventory (run `npx webjsdev ui list` or the MCP `ui` tool for the authoritative, current set)
 
 **Tier 1 (class helpers):** accordion, alert, aspect-ratio, avatar, badge,
-breadcrumb, button, card, checkbox, collapsible, input, kbd, label,
-native-select, pagination, popover, progress, radio-group, separator, skeleton,
-switch, table, textarea.
+breadcrumb, button, card, checkbox, collapsible, empty, field, input, kbd,
+label, native-select, pagination, popover, progress, radio-group, separator,
+skeleton, spinner, switch, table, textarea.
 
 **Tier 2 (custom elements, own their ARIA):** alert-dialog, dialog,
 dropdown-menu, hover-card, sonner, tabs, tooltip, plus toggle and toggle-group
@@ -93,6 +93,17 @@ dropdown-menu, hover-card, sonner, tabs, tooltip, plus toggle and toggle-group
 
 - A helper is a function, so compose it: `class=${buttonClass({ variant: 'outline' })}`.
   The unquoted `${...}` is a normal `html` attribute hole.
+- The three states a screen owes its user each have a primitive, so do not hand-roll
+  them. A list or table with no rows renders `empty` (title as a real heading, a
+  description saying what to do next, and the create action). A form field is
+  `field` (`fieldClass()` holding a `<label for>`, the control, `fieldDescriptionClass()`
+  text, and on a validation error `data-invalid="true"`, `aria-invalid` on the control,
+  and a `fieldErrorClass()` message with `role="alert"` whose id the control's
+  `aria-describedby` lists, with the typed value kept). A pending save puts
+  `spinner({ decorative: true })` in a `disabled` + `aria-busy="true"` submit button
+  that keeps its text. The `fieldClass` / `fieldLabelClass` in `components/ui/field.ts`
+  are not the same-named rhythm helpers in `lib/utils/cn.ts`; import each from its own
+  module and alias one if a file needs both.
 - Tier-1 helpers assume the design tokens exist; if a component paints unstyled,
   the tokens are missing (re-run `npx webjsdev ui init` or let `add` self-heal them).
 - Custom elements are display-only-safe at SSR and hydrate in the browser, the

package/templates/gallery/app/opengraph-image.ts

@@ -1,9 +1,9 @@
 // app/opengraph-image.ts serves /opengraph-image (the preview card social
 // platforms show when the site is shared). The Open Graph spec wants 1200x630.
-// Returning a Response with an inline SVG keeps this buildless; for per-page
-// previews, read the request in a nested static segment's opengraph-image.ts
-// and compose the title in. Reference it from metadata via
-// `openGraph: { images: ['/opengraph-image'] }`.
+// Returning a Response with an inline SVG keeps this buildless. Every page that
+// declares no `openGraph.images` gets og:image pointing here automatically
+// (absolute against SITE_URL); a nested `app/<segment>/opengraph-image.ts`
+// covers the pages under that segment instead.
 export default function OpengraphImage() {
   const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
     <rect width="1200" height="630" fill="#1e2226"/>

package/templates/gallery/app/robots.ts

@@ -1,12 +1,16 @@
-// app/robots.ts serves /robots.txt. The default export returns a string (served
-// as text/plain) or an object. This example allows all crawlers and points them
-// at the sitemap. Tighten the rules (Disallow paths) for a real app.
-const SITE_URL = (process.env.SITE_URL || 'http://localhost:8080').replace(/\/$/, '');
+// app/robots.ts serves /robots.txt. `robots()` from @webjsdev/server writes the
+// file from Next's robots object (returning the bare object works too; the
+// server runs it through the same helper). `siteUrl` is SITE_URL (your public
+// origin) when set, else the request origin, so the Sitemap line is always
+// absolute. Disallow signed-in areas and API paths, and mark those pages
+// `robots: { index: false }` too, so a crawler that follows a link still does
+// not index them.
+import { robots } from '@webjsdev/server';
+import type { MetadataRouteContext } from '@webjsdev/server';
 
-export default function Robots() {
-  return [
-    'User-agent: *',
-    'Allow: /',
-    `Sitemap: ${SITE_URL}/sitemap.xml`,
-  ].join('\n');
+export default function Robots({ siteUrl }: MetadataRouteContext) {
+  return robots({
+    rules: { userAgent: '*', allow: '/', disallow: ['/api/'] },
+    sitemap: [`${siteUrl}/sitemap.xml`, `${siteUrl}/sitemaps`],
+  });
 }

package/templates/gallery/app/sitemap.ts

@@ -1,19 +1,13 @@
-// app/sitemap.ts serves /sitemap.xml. The default export is a (possibly async)
-// server function; `sitemap(entries)` from @webjsdev/server serializes a
-// spec-valid XML sitemap. In a real app, build the entries from your content
-// (a query over posts/products), so new content is discoverable without editing
-// this file. Here it lists the gallery's static routes as an example.
-import { sitemap } from '@webjsdev/server';
+// app/sitemap.ts serves /sitemap.xml. The route receives `{ pages, siteUrl, ... }`
+// and may return an ARRAY of entries, which the server serializes to spec-valid
+// XML. `pages()` lists every public page of the app: each static page, each
+// dynamic page that exports `generateSitemapParams()` (the params it serves,
+// usually from a query), and none whose metadata says `robots: { index: false }`.
+// So adding a page adds it here with no edit. URLs use SITE_URL (your public
+// origin) when it is set, else the request origin. Append data-driven entries
+// that are not pages (a feed, a file) to the array.
+import type { MetadataRouteContext } from '@webjsdev/server';
 
-const SITE_URL = (process.env.SITE_URL || 'http://localhost:8080').replace(/\/$/, '');
-
-export default function Sitemap() {
-  const routes = ['/', '/features/routing', '/features/boundaries'];
-  return sitemap(
-    routes.map((path) => ({
-      url: `${SITE_URL}${path}`,
-      changeFrequency: 'weekly' as const,
-      priority: path === '/' ? 1.0 : 0.7,
-    })),
-  );
+export default async function Sitemap({ pages }: MetadataRouteContext) {
+  return pages();
 }

package/templates/gallery/app/sitemaps/files/route.ts

@@ -0,0 +1,14 @@
+// A child sitemap built by hand with `sitemap(entries)`: for URLs that are not
+// pages (a feed, a downloadable file), which `pages()` in app/sitemap.ts cannot
+// know about. Each entry is { url, lastModified?, changeFrequency?, priority? };
+// the helper escapes every URL and drops a malformed entry instead of emitting
+// broken XML.
+import { sitemap } from '@webjsdev/server';
+
+export async function GET(req: Request) {
+  const site = (process.env.SITE_URL || new URL(req.url).origin).replace(/\/$/, '');
+  return new Response(
+    sitemap([{ url: `${site}/manifest.json`, changeFrequency: 'yearly', priority: 0.1 }]),
+    { headers: { 'content-type': 'application/xml; charset=utf-8' } },
+  );
+}

package/templates/gallery/app/sitemaps/route.ts

@@ -1,16 +1,17 @@
 // A sitemap INDEX: for a large site split across several sitemaps, this points
 // crawlers at each child sitemap. `sitemapIndex(sitemaps)` (from @webjsdev/server)
-// serializes the spec-valid <sitemapindex> XML, the counterpart of `sitemap(entries)`
-// in app/sitemap.ts (the single-file case). A route.ts serves it at /sitemaps;
-// in a real app the children would be sharded (posts, products, ...).
+// serializes the spec-valid <sitemapindex> XML; `sitemap(entries)` serializes one
+// child. app/sitemap.ts (the pages) is one child; ./files/route.ts (URLs that are
+// not pages) is another. In a real app the children would be sharded (posts,
+// products, ...). Build absolute URLs from SITE_URL, your public origin.
 import { sitemapIndex } from '@webjsdev/server';
 
-const SITE_URL = (process.env.SITE_URL || 'http://localhost:8080').replace(/\/$/, '');
-
-export async function GET() {
+export async function GET(req: Request) {
+  const site = (process.env.SITE_URL || new URL(req.url).origin).replace(/\/$/, '');
   return new Response(
     sitemapIndex([
-      { url: `${SITE_URL}/sitemap.xml` },
+      { url: `${site}/sitemap.xml` },
+      { url: `${site}/sitemaps/files` },
     ]),
     { headers: { 'content-type': 'application/xml; charset=utf-8' } },
   );