feat(core): Counter.register('my-counter') as the idiomatic registration

Adds a `static register(tag)` method on WebComponent. Delegates to the
internal registry (which in turn calls customElements.define / the
server shim), so every registration still lands in the native
customElements map and webjs's mirror map. Authors write:

  class Counter extends WebComponent { ... }
  Counter.register('my-counter');

Instead of:

  customElements.define('my-counter', Counter);

~12 characters shorter, class-first reading order.
customElements.define remains supported — both patterns work
interchangeably; the scanner, plugin, and lint rule all accept either.

scanner / plugin / lint
-----------------------
• component-scanner: extractor finds both Class.register('tag') AND
  customElements.define('tag', Class) patterns. Orphan detection
  accepts either as registration.
• webjs-plugin: getDefinitionAndBoundSpan resolves tags from both
  patterns; existing tests updated accordingly.
• check.js: rule renamed components-have-define →
  components-have-register. Accepts either pattern.
  tag-name-has-hyphen validates tag literals from both.
• Dev server orphan warning (unchanged wording) fires when neither
  pattern is present for a WebComponent subclass.

migration
---------
All 11 blog components, scaffold ThemeToggle template, 15+ doc pages,
AGENTS.md, README.md, CONVENTIONS.md swept via regex
`customElements.define\\('tag', Class\\)` → `Class.register('tag')`.

tests
-----
• test/check.test.js: 2 fixtures now cover both patterns (Class.register
  vs customElements.define), confirming the rule accepts either.
• test/component-scanner.test.js + test/webjs-plugin.test.js already
  covered both patterns via the extractor / resolver updates.

Tests: 269 → 270 unit. Browser: 21.

Author: vivek7405

AGENTS.md

@@ -308,7 +308,7 @@ import { html, css, WebComponent, render, renderToString } from 'webjs';
 | `html`            | Tagged template literal producing a `TemplateResult`. Use in pages, layouts, and component `render()`. |
 | `css`             | Tagged template literal producing a `CSSResult`. Assign to `static styles` on components. |
 | `WebComponent`    | Base class for interactive components. |
-| `register(tag,C)` | Register a tag → class. Called automatically by `customElements.define('tag', Class)`. |
+| `register(tag,C)` | Register a tag → class. Called automatically by `Class.register('tag')`. |
 | `render(v, el)`   | Client-side: render a value into a DOM element. |
 | `renderToString`  | Server-side: **async** — render a value to an HTML string with DSD injection. Awaits Promise-valued holes and async component `render()` methods. |
 | `notFound()`      | Throw inside a page/layout/server action to return a 404 rendered via `not-found.js`. |
@@ -431,7 +431,7 @@ class MyThing extends WebComponent {
     return html`…`;
   }
 }
-customElements.define('my-thing', MyThing);
+MyThing.register('my-thing');
 ```
 
 Mutate state with `this.setState({...})` — it batches a re-render via microtask.
@@ -456,7 +456,7 @@ class StudentCard extends WebComponent {
     return html`<p>${this.student.name}</p>`;
   }
 }
-customElements.define('student-card', StudentCard);
+StudentCard.register('student-card');
 ```
 
 Built-in constructors (`String`, `Number`, `Boolean`, `Array`, `Object`)
@@ -798,7 +798,7 @@ When you mark an action as `expose('METHOD /path', fn)`, you are declaring it pa
 
 ### Components (`components/*.js`)
 
-- Each file should define **one** custom element and call `customElements.define('tag', Class)` at module top level.
+- Each file should define **one** custom element and call `Class.register('tag')` at module top level.
   Passing `import.meta.url` lets the SSR shell emit a `<link rel="modulepreload">` so the browser can fetch the module without waiting for its parent to parse. Zero build step; big first-paint win.
 - Imported by pages (for SSR) and/or other components (for composition).
 - **Styling convention: shadow-DOM CSS via `static styles = css\`…\``, not inline `style="…"` attributes.** Any repeated visual chunk in pages (layout chrome, cards, muted labels, etc.) should become a component whose styles live in its shadow root. The example app's `<blog-shell>` and `<muted-text>` demonstrate this — pages emit semantic HTML with zero inline styles.
@@ -952,7 +952,7 @@ the class-prefix rule documented in the Shadow-vs-Light DOM section.
 
 1. **Never import `@prisma/client`, `node:*`, or any server-only dependency from a file under `components/` or from a page's top-level module graph that isn't a server action.** The browser will try to load it and fail. Use a server action instead.
 2. **Every `*.server.js` export must be an `async` JSON-safe function.** Arguments/results are serialised over the wire.
-3. **Custom element tag names must contain a hyphen** (HTML spec). Set `static tag`, call `customElements.define('tag', Class)`.
+3. **Custom element tag names must contain a hyphen** (HTML spec). Set `static tag`, call `Class.register('tag')`.
 4. **Event (`@`), property (`.`), and boolean (`?`) holes in `html` must be unquoted** — e.g. `@click=${fn}`, never `@click="${fn}"`.
 5. **Do not mutate `this.state` directly** — use `setState`. State reads are fine.
 6. **Page and layout default exports must be functions.** They return a value (usually a `TemplateResult`); they do not call `render()` themselves.
@@ -1042,7 +1042,10 @@ import { WebComponent, html } from 'webjs';
 export class HelloWorld extends WebComponent {
   render() { return html`<p>Hello!</p>`; }
 }
-customElements.define('hello-wcustomElements.define('my-customElements.define('my-card', HelloWorld);Then use it as `<hello-world></hello-world>` in any page or component.
+HelloWorld.register('hello-world');
+```
+
+Then use it as `<hello-world></hello-world>` in any page or component.
 
 ### Scaffold commands
 

README.md

@@ -99,7 +99,7 @@ export class Counter extends WebComponent {
     `;
   }
 }
-customElements.define('my-counter', Counter);
+Counter.register('my-counter');
 ```
 
 Need scoped styles, `<slot>` projection, or embed-ready isolation? Opt

docs/app/docs/components/page.ts

@@ -35,7 +35,7 @@ class MyCounter extends WebComponent {
   }
 }
 
-customElements.define('my-counter', MyCounter);</pre>
+MyCounter.register('my-counter');</pre>
 
     <p>That is a complete, working component. Import it from a page or layout and use it like any HTML element:</p>
 
@@ -46,14 +46,14 @@ export default function Home() {
 }</pre>
 
     <h2>Tag Names</h2>
-    <p>The HTML spec requires that custom element names contain a <strong>hyphen</strong>. This is how the browser distinguishes <code>&lt;my-counter&gt;</code> from built-in elements like <code>&lt;div&gt;</code>. Register the component with the standard <code>customElements.define()</code> API at the bottom of the file:</p>
+    <p>The HTML spec requires that custom element names contain a <strong>hyphen</strong>. This is how the browser distinguishes <code>&lt;my-counter&gt;</code> from built-in elements like <code>&lt;div&gt;</code>. Register the component with <code>Class.register('tag')</code> at the bottom of the file:</p>
 
     <pre>class UserCard extends WebComponent {
   // ...
 }
-customElements.define('user-card', UserCard);</pre>
+UserCard.register('user-card');</pre>
 
-    <p>If you forget the hyphen, the browser throws at <code>customElements.define</code> time with a clear error message.</p>
+    <p>If you forget the hyphen, the browser throws at registration time with a clear error message.</p>
 
     <h2>Properties</h2>
     <p>The <code>static properties</code> object declares which HTML attributes the component observes, along with their type for coercion. The browser's <code>observedAttributes</code> list is auto-derived from the property names — you never write it by hand.</p>
@@ -83,7 +83,7 @@ customElements.define('user-card', UserCard);</pre>
     \`;
   }
 }
-customElements.define('user-card', UserCard);</pre>
+UserCard.register('user-card');</pre>
 
     <h3>Attribute-to-Property Coercion</h3>
     <p>When an attribute changes on the DOM element, webjs coerces the string value to the declared type:</p>
@@ -143,7 +143,7 @@ customElements.define('user-card', UserCard);</pre>
     \`;
   }
 }
-customElements.define('todo-list', TodoList);</pre>
+TodoList.register('todo-list');</pre>
 
     <h3>How setState Works</h3>
     <ul>
@@ -185,7 +185,7 @@ class StyledCard extends WebComponent {
     \`;
   }
 }
-customElements.define('styled-card', StyledCard);</pre>
+StyledCard.register('styled-card');</pre>
 
     <h3>How Styles Are Applied</h3>
     <ul>
@@ -238,7 +238,7 @@ static styles = css\`
     \`;
   }
 }
-customElements.define('app-card', AppCard);</pre>
+AppCard.register('app-card');</pre>
 
     <h3>Class-prefix rule for custom CSS</h3>
     <p>Tailwind utilities are unique by construction, so most light-DOM components need zero custom CSS. If you <em>do</em> author a <code>&lt;style&gt;</code> block or import a stylesheet, <strong>every class selector MUST be prefixed with the component's tag name</strong>. Otherwise two components with a <code>.card</code> or <code>.header</code> class will style each other.</p>
@@ -291,7 +291,7 @@ class MyCard extends WebComponent {
     \`;
   }
 }
-customElements.define('my-card', Card);
+Card.register('my-card');
 
     <p><code>static styles</code> on a light-DOM component is silently ignored — there's no shadow root to adopt them into. If you see your styles failing, check whether you forgot <code>static shadow = true</code>.</p>
 
@@ -361,7 +361,7 @@ html\`
     \`;
   }
 }
-customElements.define('page-layout', PageLayout);
+PageLayout.register('page-layout');
 
 // Usage: assign content to named slots with the slot="" attribute
 html\`
@@ -481,10 +481,10 @@ render() {
 
     <p>During SSR, <code>?disabled=\${true}</code> emits <code>disabled=""</code> and <code>?disabled=\${false}</code> emits nothing — matching how the browser interprets boolean attributes.</p>
 
-    <h2>customElements.define()</h2>
-    <p>Register the component with the web-standard <code>customElements.define()</code> API at the bottom of the file:</p>
+    <h2>Class.register('tag')</h2>
+    <p>Register the component with <code>Class.register('tag')</code> at the bottom of the file:</p>
 
-    <pre>customElements.define('my-counter', MyCounter);</pre>
+    <pre>MyCounter.register('my-counter');</pre>
 
     <p>webjs wraps the native API (and installs a compatible shim on the server) so the same line works in both environments:</p>
     <ul>
@@ -494,7 +494,7 @@ render() {
 
     <p>Module URLs for <code>&lt;link rel="modulepreload"&gt;</code> hints are discovered separately, by a server-side scanner that walks the app tree at boot and derives the file path for each discovered tag. No per-component <code>import.meta.url</code> argument needed.</p>
 
-    <blockquote>Always call <code>customElements.define</code> at the module's top level, outside the class body. The component registers as soon as the module is imported, both on server and client.</blockquote>
+    <blockquote>Always call <code>Class.register</code> at the module's top level, outside the class body. The component registers as soon as the module is imported, both on server and client.</blockquote>
 
     <h2>Server Rendering</h2>
     <p>webjs components are server-rendered using <strong>Declarative Shadow DOM</strong>. When the server renders a page containing <code>&lt;my-counter count="5"&gt;&lt;/my-counter&gt;</code>, the output looks like:</p>
@@ -513,7 +513,7 @@ render() {
 
     <h3>How SSR Works</h3>
     <ul>
-      <li>The server imports the component module, which calls <code>customElements.define()</code> and stores the class in the registry.</li>
+      <li>The server imports the component module, which calls <code>Class.register('tag')</code> and stores the class in the registry.</li>
       <li>During <code>renderToString()</code>, the server scans the output HTML for registered custom element tags.</li>
       <li>For each match, it creates a temporary instance, applies attributes from the HTML, calls <code>render()</code>, and wraps the result in a <code>&lt;template shadowrootmode="open"&gt;</code> block with the component's styles.</li>
       <li>The browser parses this as a native declarative shadow root — the content is visible <strong>before any JavaScript loads</strong>.</li>
@@ -537,7 +537,7 @@ render() {
     \`;
   }
 }
-customElements.define('user-profile', UserProfile);</pre>
+UserProfile.register('user-profile');</pre>
 
     <p>On the client, <code>render()</code> is called synchronously. If you need async data on the client, fetch it in <code>connectedCallback()</code> and call <code>setState()</code> when the data arrives.</p>
 
@@ -605,7 +605,7 @@ class TaskList extends WebComponent {
     \`;
   }
 }
-customElements.define('task-list', TaskList);</pre>
+TaskList.register('task-list');</pre>
 
     <h3>How repeat() Works</h3>
     <ul>
@@ -683,13 +683,13 @@ class ChatBox extends WebComponent {
     \`;
   }
 }
-customElements.define('chat-box', ChatBox);</pre>
+ChatBox.register('chat-box');</pre>
 
     <h2>Quick Reference</h2>
     <ul>
       <li><strong>Extend</strong> <code>WebComponent</code> and set <code>static tag</code>, <code>static properties</code>, <code>static styles</code>.</li>
       <li><strong>Implement</strong> <code>render()</code> returning <code>html\`...\`</code>.</li>
-      <li><strong>Register</strong> with <code>customElements.define('tag', ClassName)</code>.</li>
+      <li><strong>Register</strong> with <code>ClassName.register('tag')</code>.</li>
       <li><strong>State</strong> — use <code>this.setState({...})</code> for shallow merge + batched re-render.</li>
       <li><strong>Events</strong> — <code>@click</code>, <code>@submit</code>, <code>@input</code> in templates. Stable dispatchers, no listener churn.</li>
       <li><strong>Bindings</strong> — <code>attr=\${v}</code> for attributes, <code>.prop=\${v}</code> for properties, <code>?bool=\${v}</code> for booleans.</li>

docs/app/docs/context/page.ts

@@ -70,7 +70,7 @@ class AppShell extends WebComponent {
     \`;
   }
 }
-customElements.define('app-shell', AppShell);</pre>
+AppShell.register('app-shell');</pre>
 
     <p>When you call <code>provider.setValue(newValue)</code>, every subscribed consumer is notified and its host component re-renders automatically.</p>
 
@@ -104,7 +104,7 @@ class ThemedCard extends WebComponent {
     \`;
   }
 }
-customElements.define('themed-card', ThemedCard);</pre>
+ThemedCard.register('themed-card');</pre>
 
     <h2>Subscribe vs One-Shot Mode</h2>
     <p>The <code>subscribe</code> option controls whether the consumer receives ongoing updates:</p>
@@ -175,7 +175,7 @@ class AppRoot extends WebComponent {
     return html\`&lt;slot&gt;&lt;/slot&gt;\`;
   }
 }
-customElements.define('app-root', AppRoot);</pre>
+AppRoot.register('app-root');</pre>
 
     <h2>Nested Providers</h2>
     <p>Providers can be nested. A consumer resolves to the nearest ancestor provider with a matching context key:</p>
@@ -226,7 +226,7 @@ class AuthProvider extends WebComponent {
     return html\`&lt;slot&gt;&lt;/slot&gt;\`;
   }
 }
-customElements.define('auth-provider', AuthProvider);
+AuthProvider.register('auth-provider');
 
 // components/user-menu.ts
 import { WebComponent, html } from 'webjs';
@@ -247,7 +247,7 @@ class UserMenu extends WebComponent {
     return html\`&lt;span&gt;Hi, \${user.name}&lt;/span&gt;\`;
   }
 }
-customElements.define('user-menu', UserMenu);</pre>
+UserMenu.register('user-menu');</pre>
 
     <h2>Next Steps</h2>
     <ul>

docs/app/docs/controllers/page.ts

@@ -78,7 +78,7 @@ class LazyImage extends WebComponent {
     \`;
   }
 }
-customElements.define('lazy-image', LazyImage);</pre>
+LazyImage.register('lazy-image');</pre>
 
     <h2>Example: FetchController</h2>
     <p>A reusable controller that fetches data from a URL and exposes loading/error/data states:</p>
@@ -135,7 +135,7 @@ class UserList extends WebComponent {
     \`;
   }
 }
-customElements.define('user-list', UserList);</pre>
+UserList.register('user-list');</pre>
 
     <h2>Multiple Controllers on One Component</h2>
     <p>Controllers compose naturally. A single component can use any number of controllers:</p>
@@ -156,7 +156,7 @@ customElements.define('user-list', UserList);</pre>
     return html\`&lt;div&gt;\${this.#data.data?.summary}&lt;/div&gt;\`;
   }
 }
-customElements.define('dashboard-widget', DashboardWidget);</pre>
+DashboardWidget.register('dashboard-widget');</pre>
 
     <h2>Built-in Controllers</h2>
     <p>webjs ships three controllers out of the box:</p>

docs/app/docs/conventions/page.ts

@@ -13,7 +13,7 @@ export default function Conventions() {
     <ul>
       <li><strong>Module architecture</strong> — where actions, queries, and components go.</li>
       <li><strong>Testing rules</strong> — when unit vs E2E tests are required.</li>
-      <li><strong>Component patterns</strong> — light DOM by default with Tailwind; shadow DOM opt-in; <code>customElements.define()</code>; the class-prefix rule for light-DOM custom CSS.</li>
+      <li><strong>Component patterns</strong> — light DOM by default with Tailwind; shadow DOM opt-in; <code>Class.register('tag')</code>; the class-prefix rule for light-DOM custom CSS.</li>
       <li><strong>Styling convention</strong> — Tailwind browser runtime + <code>@theme</code> tokens; JS helpers in <code>app/_utils/ui.ts</code> to dedupe repeated class bundles; no <code>@apply</code>.</li>
       <li><strong>Server action patterns</strong> — one function per file, <code>ActionResult</code> envelope.</li>
       <li><strong>Code style</strong> — TypeScript extensions, const/let preferences, async/await patterns.</li>
@@ -52,7 +52,7 @@ webjs check --rules</pre>
     <ul>
       <li><strong>Actions in modules</strong> — server actions live under <code>modules/&lt;feature&gt;/actions/</code>, not scattered in random directories.</li>
       <li><strong>One function per action</strong> — each <code>.server.ts</code> file exports a single named async function.</li>
-      <li><strong>Components have register()</strong> — every component class calls <code>customElements.define()</code> at module top level.</li>
+      <li><strong>Components have register()</strong> — every component class calls <code>Class.register('tag')</code> at module top level.</li>
       <li><strong>No server imports in client code</strong> — <code>@prisma/client</code>, <code>node:*</code>, and other server-only modules are not imported from components or pages.</li>
       <li><strong>Tests exist for modules</strong> — every module under <code>modules/</code> has corresponding test files.</li>
       <li><strong>Tag names have hyphens</strong> — custom element tags contain at least one hyphen (HTML spec requirement).</li>

docs/app/docs/editor-setup/page.ts

@@ -56,7 +56,7 @@ export class StudentCard extends WebComponent {
     return html\`<p>\${this.student.name}</p>\`;
   }
 }
-customElements.define('student-card', StudentCard);</pre>
+StudentCard.register('student-card');</pre>
 
     <p>Inside the class, <code>this.student</code> is a real <code>Student</code> — hover, autocomplete, type-checking all work. <code>this.setState</code>, <code>this.state</code>, <code>this.requestUpdate</code>, and all lifecycle hooks are typed by the framework's <code>.d.ts</code> overlay.</p>
 

docs/app/docs/getting-started/page.ts

@@ -108,7 +108,7 @@ export class Counter extends WebComponent {
     \`;
   }
 }
-customElements.define('my-counter', Counter);</pre>
+Counter.register('my-counter');</pre>
 
     <h3>Run it</h3>
     <pre>npx webjs dev

docs/app/docs/lazy-loading/page.ts

@@ -34,7 +34,7 @@ class HeavyChart extends WebComponent {
     return html${'`'}<canvas></canvas>${'`'};
   }
 }
-customElements.define('heavy-chart', HeavyChart);</pre>
+HeavyChart.register('heavy-chart');</pre>
 
     <h2>How it works</h2>
     <ol>

docs/app/docs/server-actions/page.ts

@@ -111,7 +111,7 @@ export class PostForm extends WebComponent {
     \`;
   }
 }
-customElements.define('post-form', PostForm);</pre>
+PostForm.register('post-form');</pre>
 
     <h2>The superjson Wire Format</h2>
     <p>Server actions use <strong>superjson</strong> for serialisation, not plain <code>JSON.stringify</code>. The content type is <code>application/vnd.webjs+json</code>. This means rich JavaScript types survive the round trip:</p>
@@ -321,7 +321,7 @@ export class TodoApp extends WebComponent {
     \`;
   }
 }
-customElements.define('todo-app', TodoApp);
+TodoApp.register('todo-app');
 
 // 3. Call the REST endpoint from curl
 // curl -X POST http://localhost:3000/api/todos \\