lecodes-sdk 2.2.2 → 2.2.4

package/package.json

@@ -42,10 +42,10 @@
     "@types/node": "^25.9.1",
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4",
-    "marcidb-embedded": "^0.14.1",
+    "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.2.2",
+  "version": "2.2.4",
   "files": [
     "src",
     "dist",

package/prompts/ui.md

@@ -125,7 +125,9 @@ UIScrollable(...children)
 // visible rows (plus a buffer) are mounted. Use it instead of UIScrollable + map() whenever the item count
 // is large, grows over time, or is unknown.
 UIVirtualizedList<T>({
-    data: () => T[],                       // the rows, read reactively: write the signal, the list follows (new array, keys matched)
+    data?: () => T[],                      // the rows, read reactively: write the signal, the list follows (new array, keys matched)
+                                           // absent = fed by hand: .setData(items) / .append(...items) / .prepend(...items) / .update(...items) / .removeByKey(...keys)
+                                           // (one feed per list: a list with `data` has no append on its type)
     keyOf: (item: T) => string,            // STABLE unique id per item (never the array index)
     render: (item: T) => UINodeChild,      // builds one row; called lazily as rows enter the window
     estimatedHeight: number | ((item: T) => number),  // px guess per row (real height measured after mount)

package/src/animate/tween/spec.ts

@@ -200,7 +200,7 @@ export const uiValue = (v: unknown): ({ kind: number, sig?: string } & TweenValu
 
 /** Per-function argument counts of a UI transform list (degrees / px are the SDK's units). A
  *  translate named with a trailing `%` holds PERCENTS of the target's own box — a screen
- *  transition's pose (ui/transitions.ts), the only place that writes one. */
+ *  transition's pose (ui/transitions.ts) and a style's own `translate(-50%, -50%)` alike. */
 const TRANSFORM_FNS: Record<string, number> = {
   translate: 2, translateX: 1, translateY: 1, rotate: 1, scale: 2, scaleX: 1, scaleY: 1, skewX: 1, skewY: 1,
   "translate%": 2, "translateX%": 1, "translateY%": 1,
@@ -210,11 +210,10 @@ const TRANSFORM_FNS: Record<string, number> = {
  *  function is unknown (the caller falls back to matrix decomposition on the host). `scale(2)` and
  *  `translate(5px)` complete their second argument like CSS.
  *
- *  `percent`: a `%` in a translate is a percent of the target's box (`translateX(100%)` →
- *  `translateX%` [100]; a translate mixing the units splits into its two axes). Without it a `%`
- *  reads as px, as the style's own parser reads it — with a warning: only a screen transition
- *  measures a translate in percents. */
-export const parseTransformList = (s: string, percent = false): { sig: string, lanes: number[] } | null => {
+ *  A `%` in a translate is a percent of the target's own box (`translateX(100%)` → `translateX%`
+ *  [100]; a translate mixing the units splits into its two axes), the way the runtime reads a
+ *  style's transform: the box is measured when the matrix is composed, so a track fits any size. */
+export const parseTransformList = (s: string): { sig: string, lanes: number[] } | null => {
   const sig: string[] = []
   const lanes: number[] = []
   const re = /([a-zA-Z]+)\s*\(([^)]*)\)/g
@@ -236,17 +235,13 @@ export const parseTransformList = (s: string, percent = false): { sig: string, l
     if (args.length < n) { args.push(fn === "translate" ? 0 : args[0]!); units.push(units[0]!) }
     consumed = re.lastIndex
     if (fn.startsWith("translate") && units.includes("%")) {
-      if (!percent) {
-        warnOnce("transform:%", `transform: a % in ${fn}() is read as px — percents of the box work in a screen transition only`)
-      } else if (fn === "translate" && units[0] !== units[1]) {
+      if (fn === "translate" && units[0] !== units[1]) {
         sig.push(units[0] === "%" ? "translateX%" : "translateX", units[1] === "%" ? "translateY%" : "translateY")
-        lanes.push(...args)
-        continue
       } else {
         sig.push(fn + "%")
-        lanes.push(...args)
-        continue
       }
+      lanes.push(...args)
+      continue
     }
     sig.push(fn)
     lanes.push(...args)

package/src/chisel.ts

@@ -133,8 +133,8 @@ export const chiselVocab: ChiselVocab = {
       "append", "insert", "remove", "setContent", "keepAlive", "url",
       "detents", "dismissible", "transition", "setSourceRect",
       "push", "pop", "popToRoot", "replace", "select",
-      // UITabs / the native views (NativeView, CameraView, MapView, QRScanner)
-      "badge", "setData",
+      // UITabs / UIVirtualizedList's hand feed / the native views (NativeView, CameraView, MapView, QRScanner)
+      "badge", "setData", "update", "prepend", "removeByKey",
       "on", "off", "onReady", "onError", "onTap", "onMove", "onScan",
       "flyTo", "jumpTo", "fitPoints", "setPadding", "setUserLocation",
     ],

package/src/compile/serverSplit.ts

@@ -258,13 +258,15 @@ export const compileServerBundle = async (opts: CompileServerOptions): Promise<{
   // The server bundle sees the whole project map (a server module may import shared code), but the
   // bundler's asset check runs over EVERY file in the map — so binaries and svgs must be present as
   // stubs, or a client screen's `asset("./x.png")` fails the SERVER build ("asset not found", seen
-  // with a Figma-exported design next to app.server.ts). The board's `design/` files are never
-  // server code and stay out entirely.
+  // with a Figma-exported design next to app.server.ts). A stub's value is the resource's PATH: a
+  // row of shared data that names a picture (`photo: "images/a.jpg"`) reaches the server as the
+  // path of that picture, which a seed stores into a file field (files/db.ts). The board's `design/`
+  // files are never server code and stay out entirely.
   const files: MemoryFiles = {}
   for (const e of opts.entries) {
     const path = normalizePath(e.path)
     if (/^\/design\//.test(path)) continue
-    if (e.type !== "text" || path.toLowerCase().endsWith(".svg")) { files[path] = `export default ""`; continue }
+    if (e.type !== "text" || path.toLowerCase().endsWith(".svg")) { files[path] = `export default ${JSON.stringify(path)}`; continue }
     files[path] = e.text ?? ""
   }
   let params = opts.params

package/src/server/db/defineDb.ts

@@ -145,10 +145,10 @@ const emitField = (owner: string, key: string, d: FieldDef, extra: string[]): st
   if (d.array && d.kind !== "many" && d.kind !== "list") type += "[]"
   if (d.optional) type += "?"
   if (d.isId) attrs.unshift("@id")
-  if (d.unique) attrs.push("@unique")
+  if (d.unique === true) attrs.push("@unique")
+  else if (typeof d.unique === "string") attrs.push(`@unique(${d.unique})`)
   if (d.index) attrs.push("@index")
-  // 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.hasDefault) 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})`)
@@ -228,6 +228,7 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
   buildMeta({ ...own, [AUTH_SESSION_MODEL]: model({}) })
 
   let authModel: string | null = null
+  let seedFn: ((db: unknown) => Promise<void>) | null = null
   let sealed: { models: Record<string, Model>, schema: string, collections: Record<string, unknown>, auth: AuthBinding | null, files: FileField[] } | null = null
 
   const transport = () => {
@@ -272,20 +273,6 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       }
     }
     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
-    }
     const isFile = (name: string, key: string) => fileList.some(f => f.model === name && f.key === key)
     const meta = modelsMeta(metas, isFile)
     if (fileList.length) {
@@ -302,10 +289,9 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       models: meta,
       run: exec,
       // 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
-      },
+      prepareInsert: (name, data) => metas[name].uuidId && data?.id == null ? { ...data, id: crypto.randomUUID() } : data,
+      // an upsert that creates the row needs the id a uuid model leaves to the client; the key wins when it is the id
+      prepareUpsert: (name, onInsert) => metas[name].uuidId ? { id: crypto.randomUUID(), ...(onInsert ?? {}) } : onInsert,
     })
     const collections: Record<string, unknown> = {}
     for (const name of Object.keys(own)) collections[name] = collection(name)
@@ -335,8 +321,18 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       db.auth = createAuthApi(() => seal().auth!)
       return db
     },
+    // The first rows, written by the host on an empty database (runtime.ts runSeed). Kept as given: a
+    // seed may be declared before or after .withAuth, and whether the database is empty is the host's
+    // question at the time it opens.
+    seed: (fn: (db: unknown) => Promise<void>) => {
+      if (typeof fn !== "function") throw new Error("defineDb(...).seed(fn): fn is the async function that writes the first rows")
+      if (seedFn) throw new Error("defineDb(...).seed(): called twice on one db — one seed writes every table")
+      seedFn = fn
+      return db
+    },
   }
   Object.defineProperties(db, {
+    $seed: { get: () => seedFn },
     $schema: { get: () => seal().schema },
     $models: { get: () => seal().models },
     $given: { get: () => own },

package/src/server/db/fields.ts

@@ -34,7 +34,8 @@ export type FieldDef = {
   kind: FieldKind
   scalar?: ScalarKind
   optional: boolean
-  unique: boolean
+  /** `true` = `@unique`; a string = `@unique(<group>)`: the fields of a model sharing the group are unique together. */
+  unique: boolean | string
   index: boolean
   hasDefault: boolean
   default?: unknown
@@ -64,8 +65,10 @@ export interface Field<T, M extends FieldMeta = FieldMeta> {
   readonly def: FieldDef
   /** Nullable column (`String?`). */
   optional(): Field<T, SetMeta<M, "optional", true>>
-  /** `@unique` (on a relation: one-to-one). */
-  unique(): Field<T, M>
+  /** `@unique` (on a relation: one-to-one). With a group name, the fields of the model that share it are
+   *  unique TOGETHER — `user: t.one("User").unique("pair"), post: t.one("Post").unique("pair")` is one
+   *  like per user and post; a null part is not constrained. */
+  unique(group?: string): Field<T, M>
   /** `@index` — used by `$where`, `$order`, aggregations. */
   index(): Field<T, M>
   /** `@default(...)`; `"now"` on `t.date()` → `now()`. Makes the field optional on insert. */
@@ -87,7 +90,7 @@ const create = <T, M extends FieldMeta>(def: FieldDef): Field<T, M> => {
   return {
     def,
     optional: () => next({ optional: true }),
-    unique: () => next({ unique: true }),
+    unique: (group?: string) => next({ unique: group ?? true }),
     index: () => next({ index: true }),
     default: (value: unknown) => next({ hasDefault: true, default: value }),
     array: () => next({ array: true }),

package/src/server/db/httpTransport.ts

@@ -11,16 +11,31 @@
 
 import type { MarciOp, MarciTransport } from "./marci/query"
 
-/** A failed marcidb request: `status` is the HTTP status (0 = network failure), `message` its body. */
+/** A failed marcidb request: `status` is the HTTP status (0 = network failure), `kind` the server's class of the
+ *  failure — a constraint (`unique`, `foreign_key`, `restrict`, `duplicate_id`), `not_found`, `bad_request`,
+ *  `unauthorized`, `internal` —, `field` the `Model.field` a constraint is about, the message its text. */
 export class MarciHttpError extends Error {
   readonly status: number
-  constructor(status: number, message: string) {
+  readonly kind: string
+  readonly field: string | null
+  constructor(status: number, message: string, kind?: string, field: string | null = null) {
     super(message)
     this.name = "MarciHttpError"
     this.status = status
+    this.kind = kind ?? (status === 404 ? "not_found" : status === 401 ? "unauthorized" : status >= 500 || status === 0 ? "internal" : "bad_request")
+    this.field = field
   }
 }
 
+/** The error of a failed response: the server's JSON body (`error`, `kind`, `field`), or its text. */
+const failure = (status: number, text: string): MarciHttpError => {
+  try {
+    const body = JSON.parse(text)
+    if (body && typeof body.error === "string") return new MarciHttpError(status, body.error, body.kind, body.field ?? null)
+  } catch { /* plain text */ }
+  return new MarciHttpError(status, text || `HTTP ${status}`)
+}
+
 export type MarciHttpOptions = {
   token?: string | null
   fetch?: typeof fetch
@@ -62,7 +77,7 @@ export const marciRequest = async (
     throw new MarciHttpError(0, `marcidb unreachable: ${(e as Error)?.message ?? e}`)
   }
   const text = await res.text()
-  if (!res.ok) throw new MarciHttpError(res.status, text || `HTTP ${res.status}`)
+  if (!res.ok) throw failure(res.status, text)
   if (!text) return undefined
   try { return JSON.parse(text) } catch { return text }
 }
@@ -77,6 +92,7 @@ export const marciHttpTransport = (baseUrl: string, options: MarciHttpOptions =
         case "findFirst":  return call(`${op.model}/findFirst`, op.query ?? {})
         case "insert":     return call(`${op.model}/insert`, op.data)
         case "update":     return call(`${op.model}/update/${encodeMarciId(op.id)}`, op.data).then(() => null)
+        case "upsert":     return call(`${op.model}/upsert`, { key: op.key, data: op.data, ...(op.onInsert !== undefined ? { onInsert: op.onInsert } : {}) })
         // no id in the path — the filter and the payload travel together in the body
         case "updateMany": return call(`${op.model}/updateMany`, { ...(op.query ?? {}), data: op.data })
         case "delete":     return call(`${op.model}/delete/${encodeMarciId(op.id)}`).then(() => null)

package/src/server/db/marci/query.ts

@@ -177,7 +177,7 @@ export type Op<T> = PromiseLike<T> & { readonly [__op]: T }
 
 // A transport-neutral operation descriptor and the pluggable transport that runs it. The HTTP transport
 // is selected by passing a URL string; marcidb-embedded provides an in-process FFI transport.
-export type MarciOp = { model: string, action: string, query?: any, data?: any, id?: any, journal?: JournalArgs }
+export type MarciOp = { model: string, action: string, query?: any, data?: any, id?: any, key?: any, onInsert?: any, journal?: JournalArgs }
 /** The arguments of a journal action (`$journalOpen` / `$journalRead` / `$journalDrop`). `wait` is in seconds. */
 export type JournalArgs = { name: string, on?: readonly JournalOp[], after?: number, limit?: number, wait?: number }
 export type MarciTransport = {
@@ -235,9 +235,11 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Promise
   readonly [__sel]: Effective<T, Sel>
   /** Filter (marcidb `$where`). Repeated calls are ANDed. */
   where(where: T["where"]): Query<T, Sel>
-  /** Sort by one field: `order("age", "desc")` or `order({ age: "desc" })`. */
+  /** Sort: `order("age", "desc")` or `order({ age: "desc" })`. A second `order()` adds the next key — ties on
+   *  the first are broken by it (`order("createdAt", "desc").order("id")`); the keys may also come as an array
+   *  in one call. Several keys sort in memory. */
   order(field: keyof T["order"] & string, direction?: "asc" | "desc"): Query<T, Sel>
-  order(order: T["order"]): Query<T, Sel>
+  order(order: T["order"] | T["order"][]): Query<T, Sel>
   limit(n: number): Query<T, Sel>
   skip(n: number): Query<T, Sel>
   /** Keyset cursor: rows strictly after this id in the current order (`$cursor`). */
@@ -261,6 +263,13 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Promise
   /** The new row by `select`'s shape — its defaults, dates and files as stored: one call, nothing to read back. */
   insert<S extends T["query"]>(data: T["insert"], options: { select: S }): Promise<Rows<T, S>>
   update(id: IdArg<T["id"]>, data: T["update"]): Op<void>
+  /** Writes the row `key` names — the id, or the fields of ONE unique index (a `@unique` field, all the fields of
+   *  a `@unique(<name>)` group): an update of `data` when it exists, an insert of key + data when not. `data` is
+   *  in the insert form (plain values, `{ id }` for a relation; no `$` operators). `onInsert` adds fields used
+   *  only when the row is created. Resolves to the id, like `insert`. */
+  upsert<K extends Partial<T["insert"]> | T["id"]>(key: K, data: Omit<T["insert"], keyof K>, options?: { onInsert?: Partial<T["insert"]> }): Op<T["id"]>
+  /** The row written, by `select`'s shape — as stored, whichever path the upsert took. */
+  upsert<K extends Partial<T["insert"]> | T["id"], S extends T["query"]>(key: K, data: Omit<T["insert"], keyof K>, options: { onInsert?: Partial<T["insert"]>, select: S }): Promise<Rows<T, S>>
   /** Applies `data` to every row the chain's `where` matches (all rows without one); resolves to the number of rows. */
   updateMany(data: T["update"]): Op<number>
   /** @deprecated pass the filter through the chain: `db.user.where(w).updateMany(data)` (removed in the next minor). */
@@ -322,6 +331,9 @@ export type QueryLayerOptions = {
   run(op: MarciOp): Promise<any>;
   /** Hook for `insert` payloads (the lecodes SDK generates uuid ids here). */
   prepareInsert?(model: string, data: any): any;
+  /** Hook for the `onInsert` part of an `upsert` — the fields used only when the row is created (the lecodes SDK
+   *  puts a uuid id here). Receives what the caller gave (or undefined), returns what is sent. */
+  prepareUpsert?(model: string, onInsert: any): any;
 };
 
 const AGGREGATE_KEYS = ["$count", "$sum", "$avg", "$min", "$max"];
@@ -432,6 +444,10 @@ export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor:
         return w ? { $where: w } : {};
       };
       const findMany = (): MarciOp => ({ model, action: "findMany", query: build() });
+      // the row as stored, read back by the id the engine answered — a plain promise: a read is not a $transaction member
+      const readBack = (written: Op<any>, select: Record<string, any>) =>
+        written.then((id: any) => run({ model, action: "findFirst", query: resolveShape(model, { ...select, $where: id }) }))
+          .then((row: any) => { if (row === null) throw new Error(`marcidb: ${model}: the row just written is gone`); return row; });
       return {
         get __op() { return findMany(); },
         get __select() { return build(); },
@@ -440,7 +456,15 @@ export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor:
         finally: (onFinally?: any) => run(findMany()).finally(onFinally),
 
         where: (where: any) => make({ ...st, where: and(st.where, where) }),
-        order: (field: any, direction?: "asc" | "desc") => make({ ...st, order: typeof field === "string" ? { [field]: direction ?? "asc" } : field }),
+        order: (field: any, direction?: "asc" | "desc") => {
+          // one key per entry; an object with several keys is read in its key order
+          const given: any[] = typeof field === "string" ? [{ [field]: direction ?? "asc" }]
+            : Array.isArray(field) ? field
+            : Object.entries(field).map(([k, v]) => ({ [k]: v }));
+          const prev: any[] = st.order === undefined ? [] : Array.isArray(st.order) ? st.order : [st.order];
+          const keys = [...prev, ...given];
+          return make({ ...st, order: keys.length === 1 ? keys[0] : keys });
+        },
         limit: (n: number) => make({ ...st, limit: n }),
         skip: (n: number) => make({ ...st, skip: n }),
         after: (id: any) => make({ ...st, cursor: idObject(model, id) }),
@@ -458,12 +482,14 @@ export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor:
 
         insert: (data: any, extra?: { select?: Record<string, any> }) => {
           const inserted = op({ model, action: "insert", data: options.prepareInsert ? options.prepareInsert(model, data) : data });
-          if (!extra?.select) return inserted;
-          // the row as stored, read back by the id the engine answered — a plain promise: a read is not a $transaction member
-          return inserted.then((id: any) => run({ model, action: "findFirst", query: resolveShape(model, { ...extra.select, $where: id }) }))
-            .then((row: any) => { if (row === null) throw new Error(`marcidb: ${model}: the row just inserted is gone`); return row; });
+          return extra?.select ? readBack(inserted, extra.select) : inserted;
         },
         update: (id: any, data: any) => op({ model, action: "update", id: idObject(model, id), data }),
+        upsert: (key: any, data: any, o?: { onInsert?: any, select?: Record<string, any> }) => {
+          const onInsert = options.prepareUpsert ? options.prepareUpsert(model, o?.onInsert) : o?.onInsert;
+          const written = op({ model, action: "upsert", key, data, ...(onInsert !== undefined ? { onInsert } : {}) });
+          return o?.select ? readBack(written, o.select) : written;
+        },
         // `updateMany(data)`; the deprecated `updateMany(query, data)` form is told apart by arity
         updateMany: (a: any, b?: any) => (b === undefined
           ? op({ model, action: "updateMany", query: whereOnly(), data: a })

package/src/server/db/types.ts

@@ -68,11 +68,11 @@ export type ScalarSelect<S, N extends keyof S> = { [K in (ScalarKeys<FieldsOf<S[
 
 // ───────────────────────────── insert ─────────────────────────────
 
-type FieldInsert<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
+type FieldInsert<S, Fld, FW, M extends FieldMeta = MetaOf<Fld>> =
   M["kind"] extends "one" ? Nullable<M, Id<S, ModelName<S, Fld>>>
   : M["kind"] extends "many" | "list" ? Id<S, ModelName<S, Fld>>[]
-  : M["kind"] extends "struct" ? Nullable<M, StructInsert<S, StructFieldsOf<Fld>>>
-  : M["kind"] extends "file" ? Nullable<M, Arr<M, FileWrite>>      // a new row takes uploads
+  : M["kind"] extends "struct" ? Nullable<M, StructInsert<S, StructFieldsOf<Fld>, FW>>
+  : M["kind"] extends "file" ? Nullable<M, Arr<M, FW>>      // a new row takes uploads (a seed: a resource of the project too)
   : Nullable<M, Arr<M, TsOf<Fld>>>
 
 type RequiredKeys<F extends Fields> = {
@@ -84,12 +84,13 @@ type RequiredKeys<F extends Fields> = {
     : K
 }[keyof F]
 type Simplify<T> = { [K in keyof T]: T[K] } & {}
-type InsertOf<S, F extends Fields> = Simplify<
-  { [K in RequiredKeys<F>]: FieldInsert<S, F[K]> } &
-  { [K in Exclude<keyof F, RequiredKeys<F>>]?: FieldInsert<S, F[K]> }
+type InsertOf<S, F extends Fields, FW = FileWrite> = Simplify<
+  { [K in RequiredKeys<F>]: FieldInsert<S, F[K], FW> } &
+  { [K in Exclude<keyof F, RequiredKeys<F>>]?: FieldInsert<S, F[K], FW> }
 >
-export type Insert<S, N extends keyof S> = InsertOf<S, FieldsOf<S[N]>>
-type StructInsert<S, F extends Fields> = InsertOf<S, F>
+/** `FW` is what a file field is written with: an upload of the call; in a seed, a resource of the project as well. */
+export type Insert<S, N extends keyof S, FW = FileWrite> = InsertOf<S, FieldsOf<S[N]>, FW>
+type StructInsert<S, F extends Fields, FW = FileWrite> = InsertOf<S, F, FW>
 
 // ───────────────────────────── update ─────────────────────────────
 
@@ -138,7 +139,8 @@ export type Where<S, N extends keyof S> = WhereValue<WhereFieldsOf<S, FieldsOf<S
 type StructWhereFields<S, F extends Fields> = WhereFieldsOf<S, F>
 
 type OrderKeys<S, N extends keyof S> = (ValueKeys<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. */
+/** One field and its direction. Several keys are several of these, in an array (`$order: [{ createdAt: "desc" },
+ *  { id: "asc" }]`) or chained `.order()` calls — an object with two keys is refused, since JSON promises no key order. */
 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>]
@@ -146,7 +148,7 @@ export type Order<S, N extends keyof S> = {
 /** The query object — marcidb's wire form: a select shape plus the `$`-clauses. */
 export type QueryObject<S, N extends keyof S> = Select<S, N> & {
   $where?: Where<S, N>
-  $order?: Order<S, N>
+  $order?: Order<S, N> | Order<S, N>[]
   $limit?: number
   $skip?: number
   $cursor?: Id<S, N>
@@ -164,7 +166,7 @@ export type AggregateQuery<S, N extends keyof S> = {
 // ───────────────────────────── query / db ─────────────────────────────
 
 /** The per-model type bag marcidb's generic `Query<T>` is parametrised by (what its codegen emits as `UserTypes`). */
-export type Types<S, N extends keyof S> = {
+export type Types<S, N extends keyof S, FW = FileWrite> = {
   name: N & string
   model: Row<S, N>
   id: Id<S, N>
@@ -173,7 +175,7 @@ export type Types<S, N extends keyof S> = {
   query: QueryObject<S, N>
   where: Where<S, N>
   order: Order<S, N>
-  insert: Insert<S, N>
+  insert: Insert<S, N, FW>
   update: Update<S, N>
   aggregate: AggregateQuery<S, N>
   reindex: false
@@ -185,7 +187,7 @@ export type Types<S, N extends keyof S> = {
  * `updateMany(data)`/`deleteMany()` write through the chain's `where`; a query placed in another query's
  * select is a sub-query. `Sel` is the projection: id + scalars until `select(...)` sets a shape.
  */
-export type Query<S, N extends keyof S, Sel = ScalarSelect<S, N>> = MarciQuery<Types<S, N>, Sel>
+export type Query<S, N extends keyof S, Sel = ScalarSelect<S, N>, FW = FileWrite> = MarciQuery<Types<S, N, FW>, Sel>
 /** The rows a query with projection `Q` resolves to (no field keys = id + scalars; sub-queries resolved). */
 export type Result<S, N extends keyof S, Q> = Rows<Types<S, N>, Q>
 /** `db.<model>` — the root query of a model. */
@@ -212,8 +214,22 @@ type DbBase<S extends Schema> = {
   readonly $auth: AuthBinding | null
   /** @internal the schema's `t.file()` fields (../files/models.ts). */
   readonly $files: FileField[]
+  /** @internal the seed, when the definition has one (`.seed(fn)`); the host runs it on an empty database. */
+  readonly $seed: ((db: SeedDb<S>) => Promise<void>) | null
+  /**
+   * The first rows of this database: run by the host ONCE, on a database that is empty, wherever the
+   * database opens (a check, a dev backend, the first deploy). Part of the definition, like sign-in:
+   * written on `defineDb(...)` itself. Inside, a file field takes a resource of the project — the path
+   * of a picture the design shows (`photo: row.photo`) — and stores it the way an upload is stored.
+   */
+  seed(fn: (db: SeedDb<S>) => Promise<void>): Db<S>
 }
 
+/** The db a seed writes through: the same queries, a file field taking a resource of the project (its path) too. */
+export type SeedDb<S extends Schema> = {
+  [N in keyof S & string as Uncapitalize<N>]: Query<Full<S>, N, ScalarSelect<Full<S>, N>, FileWrite | string>
+} & Pick<DbBase<S>, "$transaction">
+
 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`
@@ -223,7 +239,10 @@ export type Db<S extends Schema> = DbBase<S> & {
    */
   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> }
+export type DbWithAuth<S extends Schema, N extends keyof S & string> = Omit<DbBase<S>, "seed"> & {
+  readonly auth: Auth<S, N>
+  seed(fn: (db: SeedDb<S>) => Promise<void>): DbWithAuth<S, N>
+}
 
 /** @internal */
 export type AuthBinding = { model: string, user: any, session: any, identity: any }

package/src/server/errors.ts

@@ -1,6 +1,9 @@
 /**
  * `throw new ApiError(404, "Not found")` inside an endpoint → the client's promise rejects with the
- * same status + message. Any other throw is a 500 (message hidden, logged to the server console).
+ * same status + message. A write the database refused for a reason a person could have caused reaches
+ * the app the same way, in the database's words: a taken unique value, a pointer at no row, a delete
+ * other rows forbid are 409, a row that is gone 404. Any other throw is a 500 (message hidden, logged
+ * to the server console).
  */
 export class ApiError extends Error {
   readonly status: number

package/src/server/files/db.ts

@@ -108,19 +108,38 @@ export const createFileLayer = (
     return { data: rest, files }
   }
 
-  const attach = async (field: FileField, id: string, owner: unknown, position: number): Promise<MarciOp> => {
-    const facts = field.image ? await filesSeam()!.image(id, field.image) : {}
+  const attach = async (field: FileField, id: string, owner: unknown, position: number, value?: unknown): Promise<MarciOp> => {
+    let facts = {}
+    if (field.image) {
+      try { facts = await filesSeam()!.image(id, field.image) } catch (e) {
+        // a resource of the project (a seed): the field and the path name what to fix
+        if (typeof value === "string") throw new Error(`${field.model}.${field.key}: "${value}": ${e instanceof Error ? e.message : e}`)
+        throw e
+      }
+    }
     return { model: FILE_MODEL, action: "update", id: { id }, data: { ...facts, [field.owner]: { $connect: owner }, position } }
   }
 
+  /** An upload of the current request — or, while a seed runs, a resource of the project named by its path. */
+  const uploadOf = async (value: unknown): Promise<string | undefined> => {
+    const seam = filesSeam()
+    const id = seam?.uploaded(value)
+    if (id) return id
+    return typeof value === "string" && seam?.resource ? seam.resource(value) : undefined
+  }
+
   const insert = async (op: MarciOp, index: number): Promise<Plan> => {
     const { data, files } = split(op.model, op.data)
     const after: MarciOp[] = []
     for (const [field, values] of files) {
       for (let position = 0; position < values.length; position++) {
-        const id = filesSeam()?.uploaded(values[position])
-        if (!id) throw new Error(`${op.model}.${field.key}: a new row takes uploaded files only — a file that is already stored belongs to its row`)
-        after.push(await attach(field, id, { $ref: String(index) }, position))
+        const value = values[position]
+        const id = await uploadOf(value)
+        if (!id) {
+          if (typeof value === "string" && filesSeam()?.resource) throw new Error(`${op.model}.${field.key}: "${value}" is not a file of the project`)
+          throw new Error(`${op.model}.${field.key}: a new row takes uploaded files only — a file that is already stored belongs to its row`)
+        }
+        after.push(await attach(field, id, { $ref: String(index) }, position, value))
       }
     }
     return { op: { ...op, data }, after }
@@ -134,11 +153,11 @@ export const createFileLayer = (
       const then: MarciOp[] = []
       for (let position = 0; position < values.length; position++) {
         const value = values[position]
-        const upload = filesSeam()?.uploaded(value)
+        const upload = await uploadOf(value)
         const id = upload ?? storedFileId(value)
         if (!id) throw new Error(`${op.model}.${field.key}: a file is expected — an upload, or the stored file the field already holds`)
         keep.push(id)
-        if (upload) then.push(await attach(field, upload, op.id, position))
+        if (upload) then.push(await attach(field, upload, op.id, position, value))
         // one that stays: its place in the list — and only where it IS this row's file
         else if (field.array) then.push({ model: FILE_MODEL, action: "updateMany", query: { $where: { id, [field.owner]: op.id } }, data: { position } })
       }