webjsdev
diff --git a/‎AGENTS.md‎
Lines changed: 3 additions & 0 deletions b/‎AGENTS.md‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎agent-docs/components-shadowing.md‎
Lines changed: 87 additions & 0 deletions b/‎agent-docs/components-shadowing.md‎
Lines changed: 87 additions & 0 deletions
diff --git a/‎agent-docs/orm.md‎
Lines changed: 198 additions & 0 deletions b/‎agent-docs/orm.md‎
Lines changed: 198 additions & 0 deletions
@@ -22,6 +22,9 @@ reference there.
 | `agent-docs/testing.md` | Unit, browser, convention validation, the `handle()` test harness (`@webjsdev/server/testing`) |
 | `agent-docs/framework-dev.md` | Monorepo dev (only when editing webjs itself): commands, repo-health git config, changelog flow, dev error overlay |
 | `agent-docs/recipes.md` | Page / route / action / component recipes |
+| `agent-docs/orm.md` | Drizzle rc.3 query surface: `db.query` reads, the removed `db.select({...})` projection overload, no-arg `.returning()` (#804) |
+| `agent-docs/types-and-mutations.md` | Where server-derived types live so a shipping module does not pin `db/*.server.ts` (`import type` vs value import, the carrier rule) (#804) |
+| `agent-docs/components-shadowing.md` | Inherited `WebComponent` members app code must not shadow (`title`, `remove`, ...) and the `TS2415`/`TS2416` each produces (#804) |
 | `agent-docs/lit-muscle-memory-gotchas.md` | **READ FIRST** when writing components. Lit patterns that break webjs SSR or reactivity, with the webjs-shaped fix for each |
 
 ---
 
@@ -0,0 +1,87 @@
+# Component member shadowing: names a WebComponent must not reuse
+
+A `WebComponent` inherits two layers of members. In the browser it extends
+`HTMLElement` (so every DOM property and method is present), and it extends the
+framework base that owns the reactivity lifecycle (`render`, `update`,
+`requestUpdate`, and the lit-aligned hooks). SSR swaps `HTMLElement` for an
+`ElementShim`-style stand-in with the same public surface. When app code
+declares a reactive property (via the `WebComponent({ ... })` factory) or a
+method whose NAME collides with one of those inherited members, one of two
+things happens.
+
+- **Type-incompatible collision.** TypeScript refuses the class. A reactive
+  property that shadows a native property of a different type raises **`TS2415`**
+  on the `class X extends WebComponent({ ... })` line ("Class 'X' incorrectly
+  extends base class ...; types of property 'y' are incompatible"). A method or
+  field in the class body whose signature differs from the inherited one raises
+  **`TS2416`** on that member ("Property 'y' in type 'X' is not assignable to the
+  same property in base type").
+- **Type-compatible collision.** It compiles, then silently hijacks the native
+  member at runtime (a `title` reactive prop overrides the element's tooltip /
+  `title`-attribute reflection, a `hidden` prop overrides native hide behavior).
+  No error, wrong behavior.
+
+The fix for every row below is the same. **Rename the field or method** to a
+name that is not an inherited member (`postTitle` instead of `title`,
+`removeItem` instead of `remove`). Only override an inherited lifecycle method
+deliberately and with its exact signature (override `render` / `connectedCallback`
+on purpose, never repurpose the name for unrelated app logic).
+
+## Members not to shadow
+
+| Member | Origin | Base type or signature | Shadow with an app prop / method | Error | Fix (rename to) |
+|---|---|---|---|---|---|
+| `title` | HTMLElement | `string` | `title: prop<Post>(Object)` (a post object) | `TS2415` | `post`, `heading` |
+| `id` | HTMLElement | `string` | `id: prop(Number)` (a numeric row id) | `TS2415` | `postId`, `rowId` |
+| `slot` | HTMLElement | `string` | `slot: prop<Slot>(Object)` | `TS2415` | `bookingSlot` |
+| `role` | HTMLElement | `string \| null` | `role: prop<Role>(Object)` (a user role) | `TS2415` | `userRole` |
+| `hidden` | HTMLElement | `boolean` | `hidden: prop(String)` | `TS2415` | `isHidden` (or keep `boolean`) |
+| `dir` | HTMLElement | `string` | `dir: prop<Direction>(Object)` | `TS2415` | `direction` |
+| `lang` | HTMLElement | `string` | `lang: prop<Lang>(Object)` | `TS2415` | `language` |
+| `translate` | HTMLElement | `boolean` | `translate: prop(String)` | `TS2415` | `translationKey` |
+| `draggable` | HTMLElement | `boolean` | `draggable: prop(String)` | `TS2415` | `isDraggable` |
+| `tabIndex` | HTMLElement | `number` | `tabIndex: prop(String)` | `TS2415` | `tabOrder` |
+| `className` | HTMLElement | `string` | `className: prop<string[]>(Array)` | `TS2415` | `variantClasses` |
+| `dataset` | HTMLElement | `DOMStringMap` | `dataset: prop<Data>(Object)` | `TS2415` | `payload`, `meta` |
+| `remove` | Element | `(): void` | `remove(id: number): Promise<void>` | `TS2416` | `removeItem`, `deleteRow` |
+| `closest` | Element | `(sel: string) => Element \| null` | `closest(n: number)` | `TS2416` | `nearest` |
+| `matches` | Element | `(sel: string) => boolean` | `matches(other: T)` | `TS2416` | `isMatch` |
+| `focus` | HTMLElement | `(opts?) => void` | `focus(field: string)` | `TS2416` | `focusField` |
+| `blur` | HTMLElement | `(): void` | `blur(amount: number)` | `TS2416` | `applyBlur` |
+| `click` | HTMLElement | `(): void` | `click(e: Event)` | `TS2416` | `handleClick` |
+| `append` / `prepend` | Element | `(...nodes) => void` | `append(item: T)` | `TS2416` | `appendItem` |
+| `before` / `after` | Element | `(...nodes) => void` | `after(cb: () => void)` | `TS2416` | `runAfter` |
+| `render` | WebComponent | `() => TemplateResult \| Promise<...>` | `render(data: T)` (arg added) | `TS2416` | override with the real signature |
+| `update` | WebComponent | `(changed: Map) => void` | `update(input: T)` | `TS2416` | `applyUpdate`, `save` |
+| `requestUpdate` | WebComponent | `(name?, old?) => void` | `requestUpdate(payload: T)` | `TS2416` | `queueUpdate` |
+| `updated` / `firstUpdated` | WebComponent | `(changed: Map) => void` | `updated(row: T)` | `TS2416` | `onUpdated` |
+| `willUpdate` / `shouldUpdate` | WebComponent | `(changed: Map) => boolean \| void` | repurposed for app logic | `TS2416` | rename or override correctly |
+| `connectedCallback` | WebComponent | `(): void` | `connectedCallback(user: T)` | `TS2416` | override with no args |
+| `renderError` / `renderFallback` | WebComponent | `(err?) => TemplateResult` | `renderFallback(id: number)` | `TS2416` | override with the real signature |
+| `addController` / `removeController` | WebComponent | `(c: Controller) => void` | app method of the same name | `TS2416` | rename |
+| `updateComplete` | WebComponent | `get(): Promise<boolean>` | `updateComplete: prop(Boolean)` | `TS2415` | `isComplete` |
+
+Framework-private fields are all underscore-prefixed (`_renderRoot`,
+`_connected`, `_changedProperties`, `_updatePromise`, `_isUpdating`). Never
+declare a reactive prop or field with a leading underscore that matches one, and
+never write to them from app code. Use a plainly-named reactive prop or a signal
+instead.
+
+## Names that are safe (not inherited)
+
+Common component prop names that do NOT collide, so they need no rename.
+
+`label`, `open`, `count`, `value` (declare it, native `HTMLElement` has none),
+`name`, `items`, `todos`, `active`, `variant`, `size`, `checked`, `selected`,
+`heading`, `caption`, `message`, `status`.
+
+Note. `open`, `value`, `checked`, and `selected` ARE native properties on
+specific built-in elements (`<details>`, `<input>`, `<option>`), but a
+`WebComponent` extends the generic `HTMLElement`, which does not define them, so
+they are free on a custom element. When in doubt, grep the base surface in
+`packages/core/src/component.js` (or `node_modules/@webjsdev/core/src/component.js`
+in an app) rather than guessing.
+
+Cross-references. Reactive property declaration is in the root `AGENTS.md`
+(`WebComponent` essentials) and `agent-docs/components.md`. The lit patterns that
+break webjs reactivity are in `agent-docs/lit-muscle-memory-gotchas.md`.
@@ -0,0 +1,198 @@
+# ORM: the Drizzle query surface (rc.3)
+
+The scaffold pins **`drizzle-orm@^1.0.0-rc.3`** (`db/columns.server.ts` header
+records this, research #562). rc.3 is the 1.0 release candidate with the new
+Relational Query Builder v2 (RQBv2) wired up in `db/connection.server.ts` via
+`drizzle({ client, relations })`. Several method overloads that older Drizzle
+tutorials rely on do NOT exist in rc.3, so training-data patterns from
+Drizzle 0.29 through 0.36 trip real TypeScript errors here. This page codifies
+the shapes that compile against the installed version.
+
+Ground rules for this version.
+
+1. **Reads go through the relational query API** (`db.query.<table>.findFirst`
+   / `.findMany`), not `db.select().from()`. Relations are pre-registered in
+   `db/connection.server.ts`, so `with` joins work with zero boilerplate.
+2. **`db.select()` takes no argument in rc.3.** The projection overload
+   (`db.select({ ... })`) was removed. Passing a projection object is a
+   `TS2554` compile error.
+3. **`.returning()` takes no argument in rc.3.** It always returns the full
+   inserted / updated / deleted rows (columns only, no relations). Passing a
+   field object is a `TS2554` compile error.
+
+All examples assume the scaffold imports.
+
+```ts
+import { eq, and, inArray, desc } from 'drizzle-orm';
+import { db } from '#db/connection.server.ts';
+import { posts, users } from '#db/schema.server.ts';
+```
+
+These belong in a `*.server.ts` query or action (never a page or component,
+invariant 1). Reads live in `modules/<feature>/queries/*.server.ts`, mutations
+in `modules/<feature>/actions/*.server.ts`, one function per file.
+
+---
+
+## Reads: use the relational query API
+
+`db.query.<table>` reads a whole row by default, filters with a **plain object**
+`where` (the RQBv2 shape, not a `sql` expression), orders with an `orderBy`
+object, and pulls relations with `with`. This is the shape every scaffold query
+uses.
+
+```ts
+// RIGHT: single row by a unique column
+const post = await db.query.posts.findFirst({
+  where: { slug: input.slug },
+  with: { author: { columns: { name: true, email: true } } },
+});
+
+// RIGHT: a list, newest first, with a projected column set
+const rows = await db.query.posts.findMany({
+  orderBy: { createdAt: 'desc' },
+  where: { authorId: me.id },
+  columns: { id: true, slug: true, title: true },
+  with: { author: { columns: { name: true } } },
+});
+
+// RIGHT: existence check, pull only the id
+const exists = await db.query.posts.findFirst({
+  where: { slug },
+  columns: { id: true },
+});
+```
+
+The `where` object supports equality directly (`{ slug }`), nested operators
+(`{ createdAt: { gt: cutoff } }`), and `AND` by listing multiple keys. Reach for
+the imported `eq` / `and` / `inArray` operators only on the `db.select` /
+`db.delete` / `db.update` builders below, where the `.where()` clause is an SQL
+expression rather than the RQBv2 object.
+
+### Pitfall: the `db.select({ ... })` projection overload is gone
+
+Older Drizzle let you project columns by passing an object to `select`. rc.3
+removed that overload, so the argument no longer type-checks.
+
+```ts
+// WRONG (rc.3): TS2554 "Expected 0 arguments, but got 1"
+const rows = await db
+  .select({ id: posts.id, title: posts.title })
+  .from(posts);
+```
+
+If you genuinely need the query-builder (a manual join, a `groupBy`, an
+aggregate the RQB does not express), call `select` with **no arguments** to get
+the full row, then narrow in JS.
+
+```ts
+// RIGHT: full-row select, no projection argument
+const rows = await db.select().from(posts).where(eq(posts.authorId, me.id));
+```
+
+For anything the relational API covers (by-id lookups, ordered lists, relation
+joins, column subsets), prefer `db.query.*`. It is the shorter, typed,
+relation-aware path and it sidesteps the removed overload entirely.
+
+---
+
+## Mutations: `insert` / `update` / `delete` with a no-arg `.returning()`
+
+Mutations use the query-builder, filter with the imported SQL operators, and
+read back rows with `.returning()`. In rc.3 `.returning()` has **only the
+no-argument overload**, so it yields the full row set every time.
+
+```ts
+// RIGHT: insert, read back the created row
+const [row] = await db
+  .insert(posts)
+  .values({ title, body, slug, authorId: me.id })
+  .returning();
+
+// RIGHT: update by id, read back the updated row
+const [row] = await db
+  .update(posts)
+  .set({ title, body })
+  .where(eq(posts.id, id))
+  .returning();
+
+// RIGHT: delete by id (no read-back needed)
+await db.delete(posts).where(eq(posts.id, id));
+```
+
+### Pitfall: `.returning({ ... })` with a field argument
+
+The older field-selecting `.returning({ id: posts.id })` overload does not exist
+in rc.3.
+
+```ts
+// WRONG (rc.3): TS2554 "Expected 0 arguments, but got 1"
+const [row] = await db
+  .insert(posts)
+  .values({ title, body, slug, authorId: me.id })
+  .returning({ id: posts.id, slug: posts.slug });
+```
+
+Call `.returning()` bare and destructure or map the fields you need in JS.
+
+```ts
+// RIGHT: full row back, then pick fields
+const [row] = await db.insert(posts).values({ ... }).returning();
+const created = { id: row.id, slug: row.slug };
+```
+
+### `.returning()` yields columns only, never relations
+
+A `.returning()` row is the table's own columns. It does NOT carry `with`
+relations the way a `db.query.*` read does. When the caller expects a joined
+shape (an author name alongside the post), insert then re-read, or splice the
+already-known related value in by hand.
+
+```ts
+// RIGHT: insert returns columns; add the known author locally
+const [row] = await db.insert(posts).values({ title, body, slug, authorId: me.id }).returning();
+return { success: true, data: { ...formatPost(row), authorName: me.name } };
+```
+
+---
+
+## Column helpers live in `db/columns.server.ts` (the one dialect seam)
+
+The schema is written against helpers (`table`, `pk`, `uuidPk`, `uuid`, `bool`,
+`timestamp`, `createdAt`, `updatedAt`, `index`) rather than raw drizzle
+builders, so the same `db/schema.server.ts` runs on SQLite and Postgres. Only
+`db/columns.server.ts` differs per dialect. Two of those helpers exist because
+rc.3 has not yet exposed a stable no-arg overload.
+
+- **`table`** wraps `sqliteTableCreator((name) => name, 'snake_case')`. In rc.3
+  the snake_case casing lives on the table factory, so column keys map to
+  snake_case SQL names automatically. Do not restate a `snake_case` casing
+  option on `drizzle()`.
+- **`index(...cols)`** wraps rc.3's `index(name)`, which still requires a name
+  argument the runtime auto-fills. The helper synthesizes drizzle-kit's own
+  collision-free name, so schema authors call `index(t.createdAt)` with no name.
+  Replace it with a bare `index()` once 1.0 stable ships the no-arg overload.
+
+When you add a table, use the helpers (`pk()` for an integer autoincrement id,
+`uuidPk()` for an app-generated uuid string id, `createdAt()` for a
+default-to-now timestamp) rather than reaching for raw `integer(...).primaryKey(...)`
+call sites, so the Postgres swap stays a one-file change.
+
+---
+
+## Where each query shape belongs
+
+| Task | API | File |
+|---|---|---|
+| Row by unique column | `db.query.t.findFirst({ where })` | `queries/*.server.ts` |
+| Ordered / filtered list | `db.query.t.findMany({ orderBy, where, with })` | `queries/*.server.ts` |
+| Manual join / aggregate | `db.select().from(t)` (no projection arg) | `queries/*.server.ts` |
+| Create | `db.insert(t).values(...).returning()` | `actions/*.server.ts` |
+| Update | `db.update(t).set(...).where(eq(...)).returning()` | `actions/*.server.ts` |
+| Delete | `db.delete(t).where(eq(...))` | `actions/*.server.ts` |
+
+Cross-references. Derived row TYPES and the `ActionResult<T>` envelope belong in
+a browser-safe `modules/<feature>/types.ts` (see `agent-docs/types-and-mutations.md`).
+Full page / action / query recipes live in `agent-docs/recipes.md`. The
+server-only boundary that keeps `db` off the client is in the root `AGENTS.md`
+(invariant 1).