lecodes-sdk 2.0.4 → 2.0.6

package/src/server/db/defineDb.ts

@@ -9,7 +9,8 @@
  */
 
 import type { Field, FieldDef, ScalarKind } from "./fields"
-import { AUTH_SESSION_MODEL, AUTH_USER_MODEL, authSessionModel, isAuthModel, sessionUserField } from "../auth/models"
+import { createAuthApi } from "../auth/api"
+import { AUTH_IDENTITY_MODEL, AUTH_SESSION_MODEL, identityFields, sessionFields } from "../auth/models"
 import { createQueryLayer, type FieldDesc, type MarciOp, type MarciTransport, type ModelsMeta } from "./marci/query"
 import type { AuthBinding, Db, Fields, Model, Schema, ValidateRefs } from "./types"
 
@@ -138,7 +139,8 @@ const emitField = (owner: string, key: string, d: FieldDef, extra: string[]): st
   if (d.isId) attrs.unshift("@id")
   if (d.unique) attrs.push("@unique")
   if (d.index) attrs.push("@index")
-  if (d.hasDefault) attrs.push(`@default(${literal(d.default, d)})`)
+  // an array's default is filled in on insert (`withDefaults`): the engine reads `@default([])` as [""]
+  if (d.hasDefault && !d.array) attrs.push(`@default(${literal(d.default, d)})`)
   if (d.onDelete) attrs.push(`@onDelete(${ON_DELETE[d.onDelete]})`)
   if (d.fulltext) attrs.push(`@fulltext(${d.fulltext})`)
   if (d.vector) attrs.push(`@vector(${d.vector.metric})`)
@@ -190,48 +192,106 @@ export type DefineDbOptions = { transport?: MarciTransport }
 /**
  * The schema registry: model name = key (`db.user` ← `User`). Relation strings are checked against the
  * keys both at the type level (`ValidateRefs`) and at runtime.
+ *
+ * A db is SEALED by its first use — a query, a read of its schema, the host taking it after the file
+ * has loaded. Until then `.withAuth({ model })` may still change what it holds: it adds the platform's
+ * `Session` and `Identity` models (../auth/models.ts) pointing at the project's model of a user, and
+ * gives the db its `auth`. So `withAuth` belongs to the definition, written on `defineDb(...)` itself;
+ * on a db that has been used it throws.
  */
-/**
- * The auth models (docs/backend-plan.md §3.4): `auth.model.user()` must be registered as `User`,
- * `auth.model.session()` as `Session`; `Session` is added when the project doesn't declare it (a device
- * session exists before any login), and gets its `user` column exactly when a `User` model exists.
- */
-const withAuthModels = (models: Record<string, Model>): { models: Record<string, Model>, auth: AuthBinding } => {
-  for (const [name, m] of Object.entries(models)) {
-    if (isAuthModel(m, "user") && name !== AUTH_USER_MODEL) throw new Error(`defineDb: auth.model.user() must be registered as "${AUTH_USER_MODEL}" (got "${name}")`)
-    if (isAuthModel(m, "session") && name !== AUTH_SESSION_MODEL) throw new Error(`defineDb: auth.model.session() must be registered as "${AUTH_SESSION_MODEL}" (got "${name}")`)
+export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>, options: DefineDbOptions = {}): Db<S> => {
+  const own = declared as Record<string, Model>
+  for (const name of [AUTH_SESSION_MODEL, AUTH_IDENTITY_MODEL]) {
+    if (name in own) throw new Error(`defineDb: "${name}" is the platform's own model (it comes with .withAuth) — name yours differently`)
   }
-  // A plain `model()` named User is just a model (no auth binding); only auth.model.user() binds.
-  const user = isAuthModel(models[AUTH_USER_MODEL], "user") ? models[AUTH_USER_MODEL] : null
-  let session = models[AUTH_SESSION_MODEL]
-  if (session && !isAuthModel(session, "session")) throw new Error(`defineDb: "${AUTH_SESSION_MODEL}" is reserved for auth.model.session()`)
-  if (!session) session = authSessionModel()
-  if (user && !("user" in session.fields)) session = { ...session, fields: { ...session.fields, user: sessionUserField() } }
-  return { models: { ...models, [AUTH_SESSION_MODEL]: session }, auth: { user: user ? AUTH_USER_MODEL : null, session: AUTH_SESSION_MODEL } }
-}
+  // What is wrong with the project's own models is said HERE, at the definition, not at the first use:
+  // checked against a stand-in for the one platform model they may point at.
+  buildMeta({ ...own, [AUTH_SESSION_MODEL]: model({}) })
+
+  let authModel: string | null = null
+  let sealed: { models: Record<string, Model>, schema: string, collections: Record<string, unknown>, auth: AuthBinding | null } | null = null
 
-export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>, options: DefineDbOptions = {}): Db<S> => {
-  const { models, auth } = withAuthModels(declared as Record<string, Model>)
-  const metas = buildMeta(models)
   const transport = () => {
     const t = options.transport ?? seam.__lecodesDbTransport
     if (!t) throw new Error("db: no transport — the host must call setDbTransport() before user code runs")
     return t
   }
-  // marcidb's own query builder over our metadata; the transport is the only host-specific piece
-  const { collection } = createQueryLayer({
-    models: modelsMeta(metas),
-    run: op => transport().exec(op),
-    // a single uuid key is generated client-side so `insert` needs no id (the .marci says @format(uuid))
-    prepareInsert: (name, data) => (metas[name].uuidId && data?.id == null ? { ...data, id: crypto.randomUUID() } : data),
-  })
+  const seal = () => {
+    if (sealed) return sealed
+    const models: Record<string, Model> = { ...own }
+    if (authModel) {
+      models[AUTH_SESSION_MODEL] = model(sessionFields(authModel))
+      models[AUTH_IDENTITY_MODEL] = model(identityFields(authModel))
+    } else {
+      for (const [name, m] of Object.entries(own)) {
+        for (const [key, f] of Object.entries(m.fields as Fields)) {
+          if ((f as Field<any, any>).def.model === AUTH_SESSION_MODEL) {
+            throw new Error(`defineDb: ${name}.${key} points at "${AUTH_SESSION_MODEL}" — sessions come with sign-in: defineDb({...}).withAuth({ model: "<your user model>" })`)
+          }
+        }
+      }
+    }
+    const metas = buildMeta(models)
+    // the defaults the schema does not carry: an array's (a copy per row)
+    const arrayDefaults: Record<string, [string, unknown[]][]> = {}
+    for (const meta of Object.values(metas)) {
+      arrayDefaults[meta.name] = Object.entries(meta.fields)
+        .filter(([, d]) => d.array && d.hasDefault && Array.isArray(d.default))
+        .map(([key, d]) => [key, d.default as unknown[]])
+    }
+    const withDefaults = (name: string, data: any) => {
+      const missing = arrayDefaults[name].filter(([key]) => data?.[key] === undefined)
+      if (!missing.length) return data
+      const out = { ...data }
+      for (const [key, value] of missing) out[key] = [...value]
+      return out
+    }
+    // marcidb's own query builder over our metadata; the transport is the only host-specific piece
+    const { collection } = createQueryLayer({
+      models: modelsMeta(metas),
+      run: op => transport().exec(op),
+      // a single uuid key is generated client-side so `insert` needs no id (the .marci says @format(uuid))
+      prepareInsert: (name, raw) => {
+        const data = withDefaults(name, raw)
+        return metas[name].uuidId && data?.id == null ? { ...data, id: crypto.randomUUID() } : data
+      },
+    })
+    const collections: Record<string, unknown> = {}
+    for (const name of Object.keys(own)) collections[name] = collection(name)
+    sealed = {
+      models, schema: toMarci(metas), collections,
+      // the platform's models are reached by role, never as `db.session` / `db.identity`
+      auth: authModel ? { model: authModel, user: collection(authModel), session: collection(AUTH_SESSION_MODEL), identity: collection(AUTH_IDENTITY_MODEL) } : null,
+    }
+    return sealed
+  }
+
   const db: Record<string, unknown> = {
-    $schema: toMarci(metas),
-    $models: models,
-    $auth: auth,
-    $transaction: async (ops: unknown[]) => transport().batch(ops.map(opOf)),
+    $transaction: async (ops: unknown[]) => { seal(); return transport().batch(ops.map(opOf)) },
+    withAuth: ({ model: name }: { model: string }) => {
+      if (sealed) throw new Error("defineDb(...).withAuth(): this db has already been used — sign-in is part of the definition, write it on defineDb(...) itself")
+      if (authModel) throw new Error("defineDb(...).withAuth(): called twice on one db")
+      const user = own[name]
+      if (!user) throw new Error(`defineDb(...).withAuth(): "${name}" is not a model of this db`)
+      for (const [key, f] of Object.entries(user.fields as Fields)) {
+        const d = (f as Field<any, any>).def
+        if (d.isId || key === "id") throw new Error(`defineDb(...).withAuth(): ${name} must keep the built-in id (it declares "${key}" as its key) — sessions and sign-in methods point at it`)
+        if (d.kind === "many" || d.kind === "list" || d.optional || d.hasDefault) continue
+        throw new Error(`defineDb(...).withAuth(): ${name}.${key} needs .optional() or .default(...) — the platform creates the row the first time someone signs in`)
+      }
+      authModel = name
+      db.auth = createAuthApi(() => seal().auth!)
+      return db
+    },
+  }
+  Object.defineProperties(db, {
+    $schema: { get: () => seal().schema },
+    $models: { get: () => seal().models },
+    $auth: { get: () => seal().auth },
+  })
+  for (const name of Object.keys(own)) {
+    Object.defineProperty(db, uncap(name), { enumerable: true, get: () => seal().collections[name] })
   }
-  for (const name of Object.keys(metas)) db[uncap(name)] = collection(name)
-  ;(seam.__lecodesDbs ??= []).push(db as Db<any>)
-  return db as Db<S>
+  ;(seam.__lecodesDbs ??= []).push(db as unknown as Db<any>)
+  return db as unknown as Db<S>
 }

package/src/server/db/index.ts

@@ -3,5 +3,5 @@ export { t } from "./fields"
 export type { Field, FieldDef, FieldMeta } from "./fields"
 export { model, defineDb, ref, setDbTransport, toMarci } from "./defineDb"
 export type { DefineDbOptions } from "./defineDb"
-export type { Db, Model, Schema, Row, Id, Insert, Update, Select, Where, Query, QueryObject, Result, Collection, ScalarSelect, Types } from "./types"
+export type { Auth, Db, DbWithAuth, UserQuery, Model, Schema, Row, Id, Insert, Update, Select, Where, Query, QueryObject, Result, Collection, ScalarSelect, Types } from "./types"
 export type { Op, MarciOp, MarciTransport, JsonValue, Sub } from "./marci/query"

package/src/server/db/types.ts

@@ -8,6 +8,7 @@
  */
 
 import type { Field, FieldMeta } from "./fields"
+import type { IdentityPublicFields, SessionPublicFields } from "../auth/models"
 import type {
   CompareNumValue, CompareRefListValue, CompareRefValue, CompareStrValue, CompareValue, CustomSearchValue,
   FullTextSearch, JsonCondition, JsonPathWhere, Op, PrimitiveListUpdate, Query as MarciQuery, RefListUpdate,
@@ -119,7 +120,7 @@ type FieldWhere<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
   : M["kind"] extends "many" | "list" ? CompareRefListValue<Where<S, ModelName<S, Fld>>>
   : M["kind"] extends "struct" ? CompareRefValue<WhereValue<StructWhereFields<S, StructFieldsOf<Fld>>> | null>
   : M["kind"] extends "json" ? JsonPathWhere | JsonCondition
-  : M["array"] extends true ? CompareValue<TsOf<Fld>>
+  : M["array"] extends true ? TsOf<Fld>[]          // the whole array, equal — the engine has no filter by an item
   : ScalarWhere<TsOf<Fld>, M> | CustomSearchValue<FullTextSearch> | CustomSearchValue<VectorSearch>
 
 type WhereFieldsOf<S, F extends Fields> = { [K in keyof F]?: FieldWhere<S, F[K]> }
@@ -127,7 +128,11 @@ type IdWhere<S, N extends keyof S> = { [K in keyof Id<S, N> as K extends keyof F
 export type Where<S, N extends keyof S> = WhereValue<WhereFieldsOf<S, FieldsOf<S[N]>> & IdWhere<S, N>>
 type StructWhereFields<S, F extends Fields> = WhereFieldsOf<S, F>
 
-export type Order<S, N extends keyof S> = { [K in (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>]?: "asc" | "desc" }
+type OrderKeys<S, N extends keyof S> = (ScalarKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>
+/** ONE field and its direction: the engine sorts by a single field, so a second key is a type error. */
+export type Order<S, N extends keyof S> = {
+  [K in OrderKeys<S, N>]: { [P in K]: "asc" | "desc" } & { [P in Exclude<OrderKeys<S, N>, K>]?: never }
+}[OrderKeys<S, N>]
 
 /** The query object — marcidb's wire form: a select shape plus the `$`-clauses. */
 export type QueryObject<S, N extends keyof S> = Select<S, N> & {
@@ -177,26 +182,89 @@ export type Result<S, N extends keyof S, Q> = Rows<Types<S, N>, Q>
 /** `db.<model>` — the root query of a model. */
 export type Collection<S, N extends keyof S> = Query<S, N>
 
-export type Db<S extends Schema> = {
-  [N in keyof S & string as Uncapitalize<N>]: Query<S, N>
+/** The platform's models a project's own may point at (`t.one("Session")`) — see ../auth/models.ts. */
+type PlatformModels = { Session: Model<SessionPublicFields> }
+/** What a db's queries are typed against: the project's models and what they may point at. */
+type Full<S> = S & PlatformModels
+
+type DbBase<S extends Schema> = {
+  [N in keyof S & string as Uncapitalize<N>]: Query<Full<S>, N>
 } & {
   /** Atomic batch: all ops commit or none. `ref("0.id")` feeds a generated id into a later op. */
   $transaction<P extends readonly Op<any>[]>(ops: [...P]): Promise<{ [K in keyof P]: P[K] extends Op<infer T> ? T : never }>
   /** The `.marci` schema text this db syncs with. */
   readonly $schema: string
   /** @internal */ readonly $models: Record<string, Model>
-  /** @internal which models the auth runtime binds to (`Session` always exists; `User` when declared). */
-  readonly $auth: AuthBinding
+  /** @internal the collections sign-in works on; null = a db without `withAuth`. */
+  readonly $auth: AuthBinding | null
+}
+
+export type Db<S extends Schema> = DbBase<S> & {
+  /**
+   * Sign-in for this database: `model` is the project's model of a user. Adds the platform's `Session`
+   * and `Identity` models beside it and gives the db its `auth`. Part of the definition — call it on
+   * `defineDb(...)` itself, before the db is used. Every field of the user model must be optional or
+   * have a default: the platform creates the row the first time someone signs in.
+   */
+  withAuth<N extends keyof S & string>(options: { model: N }): DbWithAuth<S, N>
 }
+export type DbWithAuth<S extends Schema, N extends keyof S & string> = DbBase<S> & { readonly auth: Auth<S, N> }
+
 /** @internal */
-export type AuthBinding = { user: string | null, session: string }
+export type AuthBinding = { model: string, user: any, session: any, identity: any }
+
+// ───────────────────────────── auth ─────────────────────────────
+
+/**
+ * The user of the current request, as a query over the project's user model: `select(shape)` picks the
+ * fields (id + scalars without it), `await` runs it. Nothing happens until it is awaited — a query that
+ * is never awaited checks nothing, which is why the compiler refuses one.
+ */
+export interface UserQuery<S, N extends keyof S, Sel, Nil> extends PromiseLike<Result<S, N, Sel> | Nil> {
+  select<Q extends Select<S, N>>(shape: Q): UserQuery<S, N, Q, Nil>
+}
+
+type AuthTables = { Session: Model<SessionPublicFields>, Identity: Model<IdentityPublicFields> }
+
+/** `db.auth` — see ../auth/api.ts. */
+export type Auth<S extends Schema, N extends keyof S & string> = {
+  /** The signed-in user, or `null` for a guest. */
+  user(): UserQuery<Full<S>, N, ScalarSelect<Full<S>, N>, null>
+  /**
+   * The signed-in user; a guest is a 401. With `where` it is a check of access too: a user the filter
+   * does not match is a 403 — `await db.auth.requireUser({ role: "admin" }).select({ id: true })`.
+   */
+  requireUser(where?: Where<Full<S>, N>): UserQuery<Full<S>, N, ScalarSelect<Full<S>, N>, never>
+  /** The device's session — there from the first request, before any sign-in (a guest's cart points at it). */
+  readonly sessionId: number
+
+  /** A new account: `login` is an email or a name (3–32 letters, digits, `. _ -`), `data` the fields of the
+   *  user's row. 409 when the login is taken. Signs this device in. */
+  signUpWithPassword(login: string, password: string, data?: Insert<Full<S>, N>): Promise<void>
+  /** Signs this device in; 401 on any failure (rate-limited per login and ip). */
+  signInWithPassword(login: string, password: string): Promise<void>
+  /** Sets the current user's password; every other device is signed out. */
+  setPassword(password: string): Promise<void>
+  /** Emails a 6-digit code (always resolves — no "email exists" oracle; rate-limited). */
+  sendCode(email: string): Promise<void>
+  /** Checks the code sent to this device, finds or creates the user, signs this device in. */
+  signInWithCode(email: string, code: string): Promise<void>
+  /** For a person the project verified itself (a provider's sign-in, Telegram initData, SSO): binds this device to the user. */
+  signIn(userId: number): Promise<void>
+  /** The device stays, as a guest. */
+  signOut(): Promise<void>
+  /** The current user's devices, as a query: `await`, `.select()`, `.where(...).updateMany({ revoked: true })`. */
+  readonly sessions: Query<AuthTables, "Session">
+  /** How the current user signs in, as a query: provider (`"email"` | `"login"`), subject, verifiedAt. */
+  readonly identities: Query<AuthTables, "Identity">
+}
 
 // ───────────────────────────── relation-name validation ─────────────────────────────
 
 type RelKinds = "one" | "many" | "list"
 type CheckField<S, Fld> =
   MetaOf<Fld>["kind"] extends RelKinds
-    ? MetaOf<Fld>["model"] extends keyof S ? Fld : `Unknown model "${MetaOf<Fld>["model"]}" — not a key of defineDb({...})`
+    ? MetaOf<Fld>["model"] extends keyof S | keyof PlatformModels ? Fld : `Unknown model "${MetaOf<Fld>["model"]}" — not a key of defineDb({...})`
     : Fld
 /** Intersected with `S` in `defineDb`'s parameter: an unknown relation target fails to type-check on that field. */
 export type ValidateRefs<S extends Schema> = { [N in keyof S]: { readonly fields: { [K in keyof FieldsOf<S[N]>]: CheckField<S, FieldsOf<S[N]>[K]> } } }

package/src/server/host.ts

@@ -6,10 +6,13 @@
  */
 
 export {
-  loadServerModules, createInvoker, createJoinGuard, setChannelPublisher, setRequestProvider,
+  loadServerModules, createInvoker, createSubscribeGuard, setChannelPublisher, setRequestProvider,
 } from "./runtime"
 export type { LoadedServer, InvokeResult, InvokerOptions, ServerRegistration } from "./runtime"
 export type { RequestContext } from "./context"
+export { createChannelHub } from "./channelHub"
+export type { ChannelHub, ChannelHubOptions, HubConnection, HubFanout } from "./channelHub"
+export type { ChannelGroup, ClientFrame, ServerFrame } from "../runtime/wire"
 export { setDbTransport } from "./db/defineDb"
 export { marciHttpTransport, marciRequest, encodeMarciId, MarciHttpError } from "./db/httpTransport"
 export type { MarciHttpOptions } from "./db/httpTransport"
@@ -17,10 +20,12 @@ export type { MarciOp, MarciTransport } from "./db/marci/query"
 export type { ServerManifest, ServerExport } from "../compile/serverSplit"
 export { validateArgs, ValidationError } from "./validate"
 export type { ParamSchema, Schema as ParamSchemaNode } from "./validate"
-export { createAuthHost, signNonce, verifyNonce, sha256 } from "./auth/host"
+export { createAuthHost, sha256, hashPassword, verifyPassword } from "./auth/host"
 export type { AuthHost, AuthHostConfig, AuthMail } from "./auth/host"
-export type { AuthUser, AuthState, AuthOps, OAuthProfile, OAuthCredential } from "./auth/types"
-export type { AuthProvider, AppConfig } from "./auth/appConfig"
+export type { AuthState, AuthOps } from "./auth/types"
+export type { AppConfig } from "./auth/appConfig"
+export type { IdentityProvider } from "./auth/models"
+import { AUTH_IDENTITY_MODEL, AUTH_SESSION_MODEL, identityPublicFields, sessionPublicFields } from "./auth/models"
 
 import type { LoadedServer } from "./runtime"
 import type { Field, FieldDef } from "./db/fields"
@@ -35,11 +40,14 @@ export type FieldDescription = Omit<FieldDef, "fields" | "default"> & { fields?:
 export type ServerDescription = {
   /** `.marci` schema text ("" when the project defines no db). */
   marci: string
-  models: Record<string, { fields: Record<string, FieldDescription> }>
+  /** `auth: true` = one of the platform's two models (`Session`, `Identity` — they come with
+   *  `withAuth`), described WITHOUT its secrets (token and password hashes, a pending code): what a
+   *  data browser may show, read-only. */
+  models: Record<string, { fields: Record<string, FieldDescription>, auth?: true }>
   endpoints: { id: string, params: unknown[] | null }[]
   channels: string[]
-  /** Which models the auth runtime binds to (`null` = the project has no db) and the app.json providers. */
-  auth: { user: string | null, session: string | null, providers: string[] }
+  /** The project's model of a user (`null` = its db has no sign-in). */
+  auth: { model: string | null }
   /** `app.json` name (when the compile embedded one). */
   appName?: string
 }
@@ -55,11 +63,18 @@ const describeField = (f: Field<any, any>): FieldDescription => {
 }
 
 export const describeServer = (server: LoadedServer): ServerDescription => {
-  const db = server.dbs[0]
+  // normally one db; with several, the one with sign-in speaks for the project
+  const db = server.dbs.find(d => d.$auth) ?? server.dbs[0]
   const models: ServerDescription["models"] = {}
   if (db) {
+    // what of the platform's models is not a secret: their public fields, and whose row it is
+    const shown: Record<string, string[]> = db.$auth ? {
+      [AUTH_SESSION_MODEL]: [...Object.keys(sessionPublicFields()), "user"],
+      [AUTH_IDENTITY_MODEL]: [...Object.keys(identityPublicFields()), "user"],
+    } : {}
     for (const [name, m] of Object.entries(db.$models as Record<string, Model>)) {
-      models[name] = { fields: Object.fromEntries(Object.entries(m.fields as Record<string, Field<any, any>>).map(([k, f]) => [k, describeField(f)])) }
+      const fields = Object.entries(m.fields as Record<string, Field<any, any>>).filter(([k]) => !shown[name] || shown[name].includes(k))
+      models[name] = { fields: Object.fromEntries(fields.map(([k, f]) => [k, describeField(f)])), ...(shown[name] ? { auth: true as const } : {}) }
     }
   }
   const params = (server.manifest.params ?? {}) as Record<string, unknown[]>
@@ -68,7 +83,7 @@ export const describeServer = (server: LoadedServer): ServerDescription => {
     models,
     endpoints: [...server.endpoints.keys()].map(id => ({ id, params: params[id] ?? null })),
     channels: [...server.channels.keys()],
-    auth: { user: db?.$auth.user ?? null, session: db?.$auth.session ?? null, providers: server.manifest.app?.auth?.providers ?? [] },
+    auth: { model: db?.$auth?.model ?? null },
     appName: server.manifest.app?.name,
   }
 }

package/src/server/inject.ts

@@ -3,11 +3,11 @@
  * chisel injects these into the server bundle exactly like ./inject.ts does for the client bundle;
  * nothing here may reach the client bundle. Keep this the ONLY file that exports server globals.
  *
- * Globals: t, model, defineDb, ref (schema + queries), ApiError, channel, request, auth.
+ * Globals: t, model, defineDb, ref (schema + queries), ApiError, channel, request. Sign-in is not a
+ * global: it is `db.auth` of a db made with `defineDb({...}).withAuth({ model })`.
  */
 
 export { t, model, defineDb, ref } from "./db"
 export { ApiError } from "./errors"
 export { channel } from "./channel"
 export { request } from "./context"
-export { auth } from "./auth/global"

package/src/server/runtime.ts

@@ -6,6 +6,7 @@
  *   evaluate the bundle (it sets globalThis.__lecodesServer)
  *   const server = loadServerModules()          // classify exports, name channels
  *   const invoke = createInvoker(server)        // validate → run in request context → envelope
+ *   const subscribe = createSubscribeGuard(server)   // a channel's hooks → the subscriber's group
  *   await invoke("notes.server.ts#listNotes", [20], { headers, ip })
  */
 
@@ -13,7 +14,7 @@ import { AsyncLocalStorage } from "node:async_hooks"
 import type { ServerManifest } from "../compile/serverSplit"
 import type { AuthHost } from "./auth/host"
 import type { AuthState } from "./auth/types"
-import { setChannelPublisher, type Channel } from "./channel"
+import { isChannel, isChannelGroup, setChannelPublisher, type ChannelRecord } from "./channel"
 import { setRequestProvider, type RequestContext } from "./context"
 import type { Db } from "./db/types"
 import { takeRegisteredDbs } from "./db/defineDb"
@@ -23,14 +24,13 @@ export type ServerRegistration = { modules: Record<string, Record<string, unknow
 
 export type LoadedServer = {
   endpoints: Map<string, (...args: any[]) => unknown>
-  channels: Map<string, Channel<any>>
-  /** Every `defineDb` handle — exported or not (the bundle registers them on globalThis; normally exactly one). */
+  channels: Map<string, ChannelRecord>
+  /** The project's `defineDb` handle — exported or not (the bundle registers it on globalThis); none or one. */
   dbs: Db<any>[]
   manifest: ServerManifest
 }
 
 const isDb = (v: unknown): v is Db<any> => typeof v === "object" && v !== null && typeof (v as Db<any>).$schema === "string"
-const isChannel = (v: unknown): v is Channel<any> => typeof v === "object" && v !== null && (v as Channel<any>).__channel === true
 
 /** Read the registration a server bundle left on `globalThis.__lecodesServer` (or a given one). */
 export const loadServerModules = (
@@ -48,6 +48,12 @@ export const loadServerModules = (
   }
   // Non-exported handles (`const db = defineDb(...)`): the bundle's SDK copy registered them on globalThis.
   for (const db of takeRegisteredDbs()) if (!out.dbs.includes(db)) out.dbs.push(db)
+  // One database per project: the host syncs one schema, so the models of a second `defineDb` would not exist.
+  if (out.dbs.length > 1) {
+    // named by their collections (own enumerable keys): reading `$models` would seal a db that is being refused
+    const each = out.dbs.map(db => Object.keys(db).filter(k => k !== "auth" && !k.startsWith("$") && k !== "withAuth").map(k => `db.${k}`).join(", ")).join(" | ")
+    throw new Error(`a project has one database, and defineDb is called ${out.dbs.length} times (${each}) — put every model in one defineDb({...}) and import that db where it is needed`)
+  }
   return out
 }
 
@@ -72,9 +78,9 @@ const apiStatus = (e: unknown): number | null =>
 
 /**
  * Build the invoker: `invoke(id, args, ctx)` runs endpoint `id` inside an AsyncLocalStorage-scoped
- * request context (what the `request`/`auth` globals read) and returns the wire envelope.
+ * request context (what the `request` global and `db.auth` read) and returns the wire envelope.
  */
-// One request store for endpoints AND channel guards (a second store would steal the provider).
+// One request store for endpoints AND channel hooks (a second store would steal the provider).
 const als = new AsyncLocalStorage<RequestContext>()
 const installProvider = () => setRequestProvider(() => als.getStore())
 
@@ -111,21 +117,37 @@ export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) =
   }
 }
 
-/** Run a channel's `onJoin` guard for a subscription (same request scoping as endpoints). */
-export const createJoinGuard = (server: LoadedServer, opts: Pick<InvokerOptions, "auth"> = {}) => {
+/**
+ * A subscription to a channel: run its hooks (`authorize`, then `groupBy`) in the subscriber's
+ * request scope. The envelope's `result` is the group the subscriber is in — `null` for a channel
+ * without groups. `args` come from the client and are validated like an endpoint's.
+ */
+export const createSubscribeGuard = (server: LoadedServer, opts: InvokerOptions = {}) => {
   installProvider()
+  const validate = opts.validate ?? true
+  const onError = opts.onError ?? ((id, e) => console.error(`[server] ${id}:`, e))
+  const params = server.manifest.params as Record<string, ParamSchema[]> | undefined
   const auth = opts.auth ?? null
-  return async (channelId: string, topic: string, ctx: Omit<RequestContext, "id"> = { headers: {} }): Promise<InvokeResult> => {
+  return async (channelId: string, args: unknown[] = [], ctx: Omit<RequestContext, "id"> = { headers: {} }): Promise<InvokeResult> => {
     const ch = server.channels.get(channelId)
     if (!ch) return { ok: false, status: 404, message: `Unknown channel ${channelId}` }
+    if (!Array.isArray(args)) return { ok: false, status: 400, message: "args must be an array" }
     const rc: RequestContext = { ...ctx, id: channelId }
     try {
+      if (validate && ch.__groupBy && params?.[channelId]) validateArgs(params[channelId], args)
       if (auth) await auth.resolve(rc)
-      await als.run(rc, () => ch.options.onJoin?.(topic))
-      return withSession({ ok: true, result: null }, rc)
+      const group = await als.run(rc, async () => {
+        await ch.__authorize?.()
+        return ch.__groupBy ? await ch.__groupBy(...args) : null
+      })
+      if (group !== null && !isChannelGroup(group)) throw new Error(`groupBy answered ${group === undefined ? "nothing" : typeof group} — a group is a string or a number`)
+      return withSession({ ok: true, result: group }, rc)
     } catch (e) {
       const status = apiStatus(e)
-      return withSession({ ok: false, status: status ?? 500, message: status !== null ? (e as Error).message : "Internal error" }, rc)
+      if (status !== null) return withSession({ ok: false, status, message: (e as Error).message }, rc)
+      if (e instanceof ValidationError) return { ok: false, status: 400, message: e.message }
+      onError(channelId, e)
+      return withSession({ ok: false, status: 500, message: "Internal error" }, rc)
     }
   }
 }

package/src/ui/UINode.ts

@@ -1,10 +1,12 @@
 import type { FetchResponse } from "../runtime/fetch"
+import type { SvgSourceValue } from "../runtime/misc"
 import type { ColorInput } from "../core/color"
 import { createBinding, disposeBinding } from "../core/signals"
 import type { Animation } from "../animate/tween/Animation"
 import { CLOCK_UI, DOM_UI, KIND_DISCRETE, KIND_TRANSFORM, KIND_TRANSFORM_MATRIX, parseTransformList, uiValue, type TweenChannel, type TweenMeta } from "../animate/tween/spec"
 import { tweenBag } from "../animate/tween/Timeline"
 import { wireStyle, wireValue } from "./styleColor"
+import { _setNodeTheme, type ThemeRoles } from "./theme"
 import { DEAD_HANDLE, TREE_FLAG_LAYOUT, elementsOf, ensureEmitter, pin, tree, unpin, type TreeElement } from "./tree"
 
 // The UI element model since phase 9 (docs/plans/hosts-unification-plan.md): the runtime OWNS the tree —
@@ -31,7 +33,7 @@ export type UINodeChild = UINode | null | undefined | false
 export type UIChildArg = UINodeChild | UINodeChild[]
 
 /** A color: any CSS color string (`"#1c1c1e"`, `"rgba(0,0,0,0.5)"`, `"green"`, `"hsl(210 50% 40%)"`),
- *  a theme reference (`"var(--primaryColor)"`), an opaque `0xRRGGBB` number or `[r, g, b(, a)]` in
+ *  a theme reference (`"var(--accent)"`), an opaque `0xRRGGBB` number or `[r, g, b(, a)]` in
  *  0..1; `null` clears. A string is the core's to parse (an unknown one is transparent, as in
  *  CSS); a number or an array that is not a color throws at the write. */
 export type Color = ColorInput | null
@@ -52,12 +54,13 @@ export type BaseStyle = {
 
 /** Painted-box props: background, gradient, border, radius. */
 export type DrawableStyle = {
-  backgroundImage?: FetchResponse | File | string | null,
+  backgroundImage?: FetchResponse | File | SvgSourceValue | string | null,
   bgGradient?: string,
   backgroundGradient?: string,
-  bgImage?: FetchResponse  | File | string | null,
-  backgroundSize?: "cover" | "contain" | "tile",
-  bgSize?: "cover" | "contain" | "tile",
+  bgImage?: FetchResponse | File | SvgSourceValue | string | null,
+  /** How the image fills the box. "tile": repeated at its own size from the top-left corner. */
+  backgroundSize?: "cover" | "contain" | "fill" | "tile",
+  bgSize?: "cover" | "contain" | "fill" | "tile",
   border?: string | number | null,
   borderWidth?: number,
   borderColor?: Color,
@@ -258,6 +261,16 @@ export interface UIElementBase<S extends object, A extends object = S> {
   name?: string
   /** Set the semantic name (chainable). */
   named(name: string): this
+  /** Theme variables for THIS element's subtree (chainable): the same keys as the app-wide
+   *  `theme()`, read by everything under the element — and by the kit components there — before
+   *  the app's table. `null` takes a key out of the scope. Reaches the element's descendants in
+   *  the tree (a pager's pages and a list's items included); a screen pushed over it and a widget
+   *  are roots of their own. Re-calling restyles the live subtree.
+   *  ```ts
+   *  promo.theme({ accent: "#FF3B30" })            // one card in another accent
+   *  sheet.theme({ bg: "#000", text: "#FFF" })     // a dark screen in a light app
+   *  ``` */
+  theme(values: ThemeRoles & Record<string, string | number | null>): this
   /** Tween to the target style — meta keys `duration`/`delay`/`loop`/…, see {@link AnimateStyle}. */
   animateTo: AnimateStyle<this, A>
   /** Tween from the given style to the current one (entrance animations). */
@@ -531,6 +544,10 @@ export class Element<T extends string> implements TreeElement {
     this.name = name
     return this
   }
+  theme(values: Record<string, string | number | null>): this {
+    _setNodeTheme(this._h.id, values)
+    return this
+  }
 
   get style(): any {
     if (this._styleProxy) return this._styleProxy

package/src/ui/UIScreen.ts

@@ -61,6 +61,11 @@ export interface UIScreen extends UIContainerBase<UIScreenStyle, DrawableStyle &
 }
 
 export class ScreenElement extends ContainerElement<"screen"> {
+  // The per-type default: a screen's background is the theme's `bg` (no theme = none, the host's).
+  constructor(type: "screen", style: any, children: any) {
+    super(type, { bgColor: "var(--bg)", ...style }, children)
+  }
+
   /** @internal */
   _dest(): DestTuple { return [TREE_DEST_SCREEN, this._h.id, "", ""] }