feat(core): typed component props via defineComponent + .d.ts overlay

The existing static-properties pattern carried no compile-time type
information, so authors had to duplicate every field as `declare x: T`
for editor intellisense. This adds a TypeScript overlay plus a tiny
runtime helper so the descriptor map is the single source of truth for
both runtime behaviour and instance-level field types.

runtime
-------
• `defineComponent(descriptors)` — thin factory that returns a
  WebComponent subclass with `static properties` pre-set. At runtime
  it's equivalent to the manual pattern; the value is all in the types.
• `defineProp<T>(decl)` — identity at runtime; carries a phantom type
  parameter so the compiler recovers a caller-supplied value type when
  the constructor alone doesn't give enough information (custom classes,
  discriminated unions via converters).

types
-----
• packages/core/src/component.d.ts — typed WebComponent base,
  PropertyDeclaration<T>, PropertyValue<D>, PropertyValues<P>,
  defineComponent<P>, defineProp<T>.
• packages/core/index.d.ts — re-exports the overlay so `import { ... }
  from 'webjs'` resolves typed identifiers.
• package.json `exports` map now advertises `types` sibling entries so
  tsserver (VS Code, Neovim, Zed, WebStorm) picks the overlay up
  without any project configuration.

editor setup
------------
• new doc: docs/app/docs/editor-setup — Neovim (nvim-lspconfig +
  typescript-tools.nvim) and VS Code walkthrough, tsconfig baseline,
  optional lit-plugin for template-literal autocomplete, verification
  steps.
• sidebar updated to link the new page.

example + scaffold
------------------
• blog: components/counter.ts migrated to `defineComponent`, dropping
  the `declare count` line.
• packages/cli/templates/CONVENTIONS.md: Components section now leads
  with `defineComponent` and notes when to fall back to plain
  WebComponent.
• AGENTS.md: `WebComponent` section documents `defineComponent` /
  `defineProp` with before/after snippets, including the
  `declare`-based legacy pattern for pure-JS users.

tests
-----
• test/define-component.test.js — 7 runtime tests covering factory
  behaviour, property passthrough, converter wiring, and defineProp
  identity.
• test/types/component-types.test-d.ts — compile-time assertion
  fixtures (constructor inference, converter inference, class-typed
  properties, defineProp phantom type, backwards-compat with manual
  declare). Not executed by node:test; consumed by tsserver / a manual
  tsc run.

Tests: 255 → 262.

Author: vivek7405

AGENTS.md

@@ -439,6 +439,62 @@ Mutate state with `this.setState({...})` — it batches a re-render via microtas
 Attribute changes auto-trigger re-render when the attribute is declared in
 `static properties`.
 
+#### Typed props with `defineComponent` (TypeScript — recommended)
+
+For full type inference on `this.<prop>` without writing a `declare`
+field for every property, use the `defineComponent()` factory. It's a
+thin wrapper that sets `static properties` and threads the descriptor
+map through to TypeScript's type system:
+
+```ts
+import { defineComponent, defineProp, html } from 'webjs';
+
+class Counter extends defineComponent({
+  count: { type: Number, reflect: true },
+  label: { type: String },
+  active: { type: Boolean },
+}) {
+  static tag = 'my-counter';
+  // this.count: number, this.label: string, this.active: boolean — inferred
+  render() {
+    return html`<p>${this.label}: ${this.count} (${this.active ? 'on' : 'off'})</p>`;
+  }
+}
+Counter.register(import.meta.url);
+```
+
+For a property whose value type can't be derived from the constructor
+alone (e.g. `type: Object` with a specific shape, or a converter
+returning a user-defined class), use `defineProp<T>()`:
+
+```ts
+class Profile extends defineComponent({
+  user: defineProp<User>({ type: Object }),
+}) {
+  static tag = 'user-profile';
+  // this.user: User
+  render() { return html`${this.user.name}`; }
+}
+```
+
+Plain-JS classes still work — the legacy pattern is identical to what
+the snippet above shows. Use `declare <name>: <Type>` if you want
+type-only fields for the editor without duplicating at runtime:
+
+```ts
+class Legacy extends WebComponent {
+  static tag = 'x-legacy';
+  static properties = { count: { type: Number } };
+  declare count: number;           // compile-time only
+  render() { return html`${this.count}`; }
+}
+```
+
+Editor intellisense (VS Code + Neovim + any tsserver client) works
+out-of-the-box from the `.d.ts` overlay shipped with the package. See
+the [Editor Setup](docs/app/docs/editor-setup/page.ts) doc page for
+<code>tsconfig</code>, Neovim LSP, and tagged-template autocomplete.
+
 #### Lifecycle hooks
 
 The update cycle runs in this order when `setState()` or a property change triggers a re-render:

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

@@ -0,0 +1,126 @@
+import { html } from 'webjs';
+
+export const metadata = { title: 'Editor Setup — webjs' };
+
+export default function EditorSetup() {
+  return html`
+    <h1>Editor Setup — Neovim &amp; VS Code</h1>
+    <p>webjs ships a TypeScript overlay (<code>packages/core/index.d.ts</code> and <code>packages/core/src/component.d.ts</code>) so any editor that speaks the TypeScript Language Server (<code>tsserver</code>) gets full autocomplete, hover documentation, and type-checking for framework APIs — component properties, template results, server actions — with zero build step.</p>
+
+    <h2>Prerequisites</h2>
+    <ul>
+      <li><strong>Node 23.6+</strong> for native TypeScript type-stripping at runtime.</li>
+      <li><strong>TypeScript 5.6+</strong> as a dev dependency in your app (<code>npm i -D typescript</code>). The framework itself has no TS dependency — you only need it for editor intellisense.</li>
+      <li>A <code>tsconfig.json</code> in your app. The scaffold generates one.</li>
+    </ul>
+
+    <h2><code>tsconfig.json</code> — recommended baseline</h2>
+    <p>The scaffold writes this file for you. Manual apps should match:</p>
+    <pre>{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true
+  }
+}</pre>
+    <p>Key points:</p>
+    <ul>
+      <li><code>moduleResolution: "NodeNext"</code> — required for the framework's <code>exports</code> map to resolve correctly.</li>
+      <li><code>allowImportingTsExtensions: true</code> — lets you write <code>import { x } from './foo.ts'</code> in pages and components, matching how webjs actually serves them.</li>
+      <li><code>noEmit: true</code> — TypeScript is used for type-checking only; the webjs dev server strips types via Node / esbuild at request time.</li>
+    </ul>
+
+    <h2>VS Code</h2>
+    <p>Works out of the box. The bundled TypeScript extension picks up your <code>tsconfig.json</code> and the framework's <code>.d.ts</code> overlay automatically. Optional extras:</p>
+    <ul>
+      <li><strong><a href="https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin" target="_blank">lit-plugin</a></strong> — extends syntax highlighting and offers autocomplete inside <code>html\`\`</code> tagged templates. webjs's template dialect is compatible with Lit's; this plugin works with no configuration.</li>
+      <li><strong>Tailwind CSS IntelliSense</strong> — suggests utility classes inside <code>class="..."</code> attributes.</li>
+    </ul>
+
+    <h2>Neovim</h2>
+    <p>Any TypeScript LSP client will work — the configuration is identical to any other TypeScript project.</p>
+
+    <h3>Option A — <code>nvim-lspconfig</code></h3>
+    <pre>-- lua/plugins/tsserver.lua (lazy.nvim)
+return {
+  'neovim/nvim-lspconfig',
+  config = function()
+    local lspconfig = require('lspconfig')
+    lspconfig.ts_ls.setup({
+      settings = {
+        typescript = { preferences = { importModuleSpecifier = 'non-relative' } },
+        javascript = { preferences = { importModuleSpecifier = 'non-relative' } },
+      },
+    })
+  end,
+}</pre>
+
+    <h3>Option B — <code>typescript-tools.nvim</code> (recommended)</h3>
+    <p>Faster for large projects because it talks to <code>tsserver</code> directly instead of going through <code>tsserver.js</code> over stdin. Setup:</p>
+    <pre>return {
+  'pmizio/typescript-tools.nvim',
+  dependencies = { 'nvim-lua/plenary.nvim', 'neovim/nvim-lspconfig' },
+  opts = {
+    settings = {
+      tsserver_file_preferences = {
+        importModuleSpecifier = 'non-relative',
+        includeCompletionsForModuleExports = true,
+      },
+    },
+  },
+}</pre>
+
+    <h3>Autocomplete + hover bindings</h3>
+    <p>Once the LSP is attached (check with <code>:LspInfo</code>), the standard keymaps from your LSP setup apply — commonly:</p>
+    <pre>K       -- show hover doc (types + JSDoc)
+gd      -- go to definition
+gr      -- list references
+&lt;leader&gt;ca -- code actions
+&lt;leader&gt;rn -- rename symbol</pre>
+
+    <h3>Completing in <code>html\`\`</code> templates</h3>
+    <p>Standard <code>tsserver</code> doesn't look inside tagged template literals. For element/attribute autocomplete inside <code>html\`\`</code> strings, install the <strong>lit-plugin</strong> TypeScript plugin, which works in any tsserver-backed editor (VS Code, Neovim, etc.):</p>
+    <pre># In your app root
+npm i -D typescript ts-lit-plugin
+
+# Add to tsconfig.json compilerOptions:
+"plugins": [{ "name": "ts-lit-plugin", "strict": true }]</pre>
+    <p>Neovim users also need to tell <code>tsserver</code> to load plugins from the workspace — <code>nvim-lspconfig</code> does this by default when you have a local <code>node_modules/typescript</code>.</p>
+
+    <h2>Verifying your setup</h2>
+    <p>Create <code>components/hello.ts</code>:</p>
+    <pre>import { defineComponent, html } from 'webjs';
+
+class Hello extends defineComponent({
+  name: { type: String },
+  times: { type: Number },
+}) {
+  static tag = 'hello-card';
+  render() {
+    return html\`&lt;p&gt;Hello \${this.name} — \${this.times} times&lt;/p&gt;\`;
+  }
+}
+Hello.register(import.meta.url);</pre>
+
+    <p>In your editor:</p>
+    <ul>
+      <li>Hover <code>this.name</code> → should show <code>(property) name: string</code>.</li>
+      <li>Hover <code>this.times</code> → should show <code>(property) times: number</code>.</li>
+      <li>Type <code>this.</code> → autocomplete lists <code>name</code>, <code>times</code>, <code>setState</code>, <code>requestUpdate</code>, <code>state</code>, etc.</li>
+      <li>Change a property usage to the wrong type (e.g. <code>this.name.toFixed(2)</code>) → red underline with <code>Property 'toFixed' does not exist on type 'string'.</code></li>
+    </ul>
+    <p>If any of these don't work, check <code>:checkhealth</code> (Neovim) or the TypeScript status bar (VS Code) — the most common issue is <code>tsserver</code> picking up a different <code>tsconfig.json</code> than the app's.</p>
+
+    <h2>See also</h2>
+    <ul>
+      <li><a href="/docs/components">Components</a> — <code>defineComponent</code> API details.</li>
+      <li><a href="/docs/typescript">TypeScript</a> — type safety end-to-end.</li>
+      <li><a href="/docs/conventions">Conventions</a> — project layout + AI-agent workflow.</li>
+    </ul>
+  `;
+}

docs/components/doc-shell.ts

@@ -57,6 +57,7 @@ const NAV_SECTIONS = [
       { href: '/docs/task', label: 'Task (Async Data)' },
       { href: '/docs/lazy-loading', label: 'Lazy Loading' },
       { href: '/docs/typescript', label: 'TypeScript' },
+      { href: '/docs/editor-setup', label: 'Editor Setup (Neovim, VS Code)' },
       { href: '/docs/middleware', label: 'Middleware' },
       { href: '/docs/deployment', label: 'Deployment' },
       { href: '/docs/testing', label: 'Testing' },

examples/blog/components/counter.ts

@@ -1,13 +1,17 @@
-import { WebComponent, html } from 'webjs';
+import { defineComponent, html } from 'webjs';
 
 /**
  * `<my-counter>` — demo counter with the current design system.
  * Tabular monospace output; warm-accent focus ring.
+ *
+ * Uses `defineComponent` so `this.count` is typed as `number` without
+ * a `declare` line — the descriptor is the single source of truth for
+ * both runtime and compile-time types.
  */
-export class Counter extends WebComponent {
+export class Counter extends defineComponent({
+  count: { type: Number },
+}) {
   static tag = 'my-counter';
-  static properties = { count: { type: Number } };
-  count = 0;
   _bump(d: number) { this.count = (Number(this.count) || 0) + d; this.requestUpdate(); }
   render() {
     const v = Number(this.count) || 0;

packages/cli/templates/CONVENTIONS.md

@@ -212,23 +212,33 @@ with puppeteer or playwright imports.
 <!-- OVERRIDE -->
 
 ```ts
-import { WebComponent, html } from 'webjs';
+import { defineComponent, html } from 'webjs';
 
-export class MyWidget extends WebComponent {
+export class MyWidget extends defineComponent({
+  label: { type: String },
+  count: { type: Number },
+}) {
   static tag = 'my-widget';
-  // Light DOM is the default — Tailwind utility classes apply directly.
+  // `this.label: string` and `this.count: number` are inferred — no
+  // `declare` boilerplate. Light DOM is the default; Tailwind classes
+  // apply directly.
 
   render() {
     return html`
       <div class="p-4 border border-border rounded-lg">
-        <p class="font-serif text-fg">Hello</p>
+        <p class="font-serif text-fg">${this.label}: ${this.count}</p>
       </div>
     `;
   }
 }
 MyWidget.register(import.meta.url);
 ```
 
+Prefer `defineComponent(...)` over plain `WebComponent` when you have
+properties — it's the recommended pattern for TypeScript apps. Pure JS
+consumers can still subclass `WebComponent` directly and set
+`static properties` manually.
+
 **Rules:**
 - One component per file
 - **Light DOM by default.** Opt in to shadow DOM with `static shadow = true` when you need scoped styles, `<slot>` projection, or third-party-embed isolation.

packages/core/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Public type surface for `webjs`.
+ *
+ * The runtime is packages/core/index.js (JSDoc-annotated JavaScript); this
+ * overlay exists so TypeScript-based editors (tsserver under VS Code,
+ * Neovim, Zed, WebStorm) resolve richer types than JSDoc alone can express
+ * — specifically the generic component factory and property-descriptor
+ * inference helpers. Zero runtime cost.
+ */
+
+export * from './src/component.d.ts';
+
+export { html, isTemplate, MARKER } from './src/html.js';
+export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
+export { register, lookup, lookupModuleUrl, isLazy, allTags } from './src/registry.js';
+export { renderToString, renderToStream } from './src/render-server.js';
+export { render } from './src/render-client.js';
+export { escapeText, escapeAttr } from './src/escape.js';
+export { notFound, redirect, isNotFound, isRedirect } from './src/nav.js';
+export { expose, getExposed } from './src/expose.js';
+export { repeat, isRepeat } from './src/repeat.js';
+export { Suspense, isSuspense } from './src/suspense.js';
+export { connectWS } from './src/websocket-client.js';
+export { richFetch } from './src/rich-fetch.js';
+export { enableClientRouter, disableClientRouter, navigate } from './src/router-client.js';
+export { unsafeHTML, isUnsafeHTML, live, isLive } from './src/directives.js';
+export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';
+export { Task, TaskStatus } from './src/task.js';

packages/core/index.js

@@ -8,7 +8,7 @@
 
 export { html, isTemplate, MARKER } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
-export { WebComponent } from './src/component.js';
+export { WebComponent, defineComponent, defineProp } from './src/component.js';
 export { register, lookup, lookupModuleUrl, isLazy, allTags } from './src/registry.js';
 export { renderToString, renderToStream } from './src/render-server.js';
 export { render } from './src/render-client.js';

packages/core/package.json

@@ -3,16 +3,24 @@
   "version": "0.1.0",
   "type": "module",
   "description": "webjs core runtime — html/css tags, WebComponent base, isomorphic renderers",
+  "types": "./index.d.ts",
   "exports": {
-    ".": "./index.js",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
     "./client": "./src/render-client.js",
     "./server": "./src/render-server.js",
-    "./component": "./src/component.js",
+    "./component": {
+      "types": "./src/component.d.ts",
+      "default": "./src/component.js"
+    },
     "./registry": "./src/registry.js",
     "./client-router": "./src/router-client.js"
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "src"
   ]
 }