lecodes-sdk 2.2.3 → 2.2.4

package/src/server/files/host.ts

@@ -29,12 +29,12 @@
 
 import { createReadStream } from "node:fs"
 import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises"
-import { join } from "node:path"
+import { basename, join } from "node:path"
 import { Readable } from "node:stream"
 import { currentRequest, type RequestContext } from "../context"
 import type { MarciOp, MarciTransport } from "../db/marci/query"
 import type { Db } from "../db/types"
-import { FILE_MODEL, setFilesSeam, type FilesSeam, type ImageFacts, type ImageRule } from "./models"
+import { FILE_MODEL, setFilesSeam, type FilesSeam, type ImageFacts, type ImageRule, type UploadedFile } from "./models"
 
 /** What the receiving process knows of one uploaded file; its bytes are in `<dir>/tmp/<id>`. */
 export type Upload = { id: string, name: string, type: string, size: number, width?: number, height?: number }
@@ -344,10 +344,18 @@ export type FilesHost = {
   install(): void
   /** The arguments with every `{ "$file": i }` turned into the `File` the endpoint receives. */
   adopt(args: unknown[], rc: RequestContext): Promise<unknown[]>
+  /** While a seed runs (runtime.ts runSeed): a resource of the project a row names by its path is read
+   *  through `read` and stored as an upload of `rc` would be — the field's rule applies, what the seed
+   *  writes nowhere is dropped by `finish`. Returns what ends it. */
+  seeding(rc: RequestContext, read: ResourceReader): () => void
   /** After the call, whatever it ended with. */
   finish(rc: RequestContext): Promise<void>
 }
 
+/** A resource of the project by the path the bundle has for it (`/images/a.jpg`): its bytes, or null when
+ *  the project has no such file. The host knows where the project's files are — a folder, a url. */
+export type ResourceReader = (path: string) => Promise<Uint8Array | null>
+
 const isPlaceholder = (v: unknown): v is { $file: number } =>
   typeof v === "object" && v !== null && typeof (v as { $file?: unknown }).$file === "number" && Object.keys(v).length === 1
 
@@ -434,10 +442,44 @@ export const createFilesHost = (cfg: FilesHostConfig): FilesHost => {
     }
   })().catch((e) => { ready = null; throw e }))
 
+  /** Uploads that lie in `tmp` become rows of `File` and files in place — the rows first, so a file on
+   *  disk always has its row — and the `File` objects the call sees, each known to the seam. */
+  const admit = async (uploads: Upload[], rc: RequestContext): Promise<UploadedFile[]> => {
+    await transport().batch(uploads.map(u => ({
+      model: FILE_MODEL, action: "insert",
+      data: { id: u.id, name: u.name, type: u.type, size: u.size, ...(u.width ? { width: u.width, height: u.height } : {}) },
+    })))
+    inFlight.set(rc, [...(inFlight.get(rc) ?? []), ...uploads.map(u => u.id)])
+    for (const u of uploads) names.set(u.id, u.name)
+    for (const u of uploads) await rename(join(cfg.dir, "tmp", u.id), join(cfg.dir, u.id))
+    return uploads.map((u) => {
+      const file = Object.freeze({ name: u.name, size: u.size, type: u.type })
+      uploaded.set(file, u.id)
+      return file
+    })
+  }
+
   return {
     enabled,
     install: () => setFilesSeam(enabled ? seam : null),
 
+    seeding: (rc, read) => {
+      if (!enabled) return () => {}
+      // a file belongs to one row: a picture two rows name is stored for each of them
+      seam.resource = async (path) => {
+        const bytes = await read(path)
+        if (!bytes) return undefined
+        await start()
+        const id = crypto.randomUUID()
+        const type = sniffType(bytes) ?? "application/octet-stream"
+        await writeFile(join(cfg.dir, "tmp", id), bytes)
+        const size = imageSize(bytes, type)
+        const [file] = await admit([{ id, name: basename(path), type, size: bytes.length, ...(size ?? {}) }], rc)
+        return uploaded.get(file!)
+      }
+      return () => { delete seam.resource }
+    },
+
     adopt: async (args, rc) => {
       const uploads = (rc.uploads ?? []) as Upload[]
       if (!uploads.length && !hasPlaceholder(args)) return args
@@ -448,21 +490,7 @@ export const createFilesHost = (cfg: FilesHostConfig): FilesHost => {
           const used = (await exec({ action: "aggregate", query: { $sum: "size" } }))?.sum ?? 0
           if (used + uploads.reduce((n, u) => n + u.size, 0) > cfg.quota) throw new UploadError(413, "the project's file storage is full")
         }
-        // the rows first, then the bytes into place: a file on disk always has its row
-        if (uploads.length) {
-          await transport().batch(uploads.map(u => ({
-            model: FILE_MODEL, action: "insert",
-            data: { id: u.id, name: u.name, type: u.type, size: u.size, ...(u.width ? { width: u.width, height: u.height } : {}) },
-          })))
-          inFlight.set(rc, uploads.map(u => u.id))
-          for (const u of uploads) names.set(u.id, u.name)
-          for (const u of uploads) await rename(join(cfg.dir, "tmp", u.id), join(cfg.dir, u.id))
-        }
-        const files = uploads.map((u) => {
-          const file = Object.freeze({ name: u.name, size: u.size, type: u.type })
-          uploaded.set(file, u.id)
-          return file
-        })
+        const files = uploads.length ? await admit(uploads, rc) : []
         const place = (v: unknown): unknown => {
           if (isPlaceholder(v)) return files[v.$file] ?? (() => { throw new UploadError(400, `the call names file ${v.$file}, and carries ${files.length}`) })()
           if (Array.isArray(v)) return v.map(place)

package/src/server/files/models.ts

@@ -96,6 +96,10 @@ export type FilesSeam = {
   /** The id of the `File` row behind an upload of the current request; undefined for anything else —
    *  a value the app sent as JSON is never an upload, whatever it looks like. */
   uploaded(value: unknown): string | undefined
+  /** While a seed runs: the id of a `File` row made from a resource of the project named by its path
+   *  (what a path literal of the design is in the server bundle); undefined for a path that is no file
+   *  of the project. Absent outside a seed: a string the app sent is never a file. */
+  resource?(path: string): Promise<string | undefined>
   url(id: string, name: string): string
   /** Make the upload `id` fit for a `t.image()` field (its bytes are rewritten in place) and say what
    *  it is now. Throws an `ApiError` for what is no picture. */

package/src/server/host.ts

@@ -6,9 +6,9 @@
  */
 
 export {
-  loadServerModules, createInvoker, createFileWriter, createSubscribeGuard, setChannelPublisher, setRequestProvider,
+  loadServerModules, createInvoker, createFileWriter, createSubscribeGuard, setChannelPublisher, setRequestProvider, runSeed, SeedError,
 } from "./runtime"
-export type { LoadedServer, InvokeResult, InvokerOptions, ServerRegistration } from "./runtime"
+export type { LoadedServer, InvokeResult, InvokerOptions, ServerRegistration, SeedOutcome } from "./runtime"
 export type { RequestContext } from "./context"
 export { createChannelHub } from "./channelHub"
 export type { ChannelHub, ChannelHubOptions, HubConnection, HubFanout } from "./channelHub"
@@ -26,7 +26,7 @@ export type { AuthState, AuthOps } from "./auth/types"
 export type { AppConfig } from "./auth/appConfig"
 export type { IdentityProvider } from "./auth/models"
 export { createFilesHost, receiveUploads, dropUploads, fileResponse, isMultipart, UploadError } from "./files/host"
-export type { FilesHost, FilesHostConfig, Heic, Sharp, Upload, UploadLimits } from "./files/host"
+export type { FilesHost, FilesHostConfig, Heic, ResourceReader, Sharp, Upload, UploadLimits } from "./files/host"
 export type { StoredFile, StoredImage } from "./files/models"
 import { FILE_MODEL, filePublicFields } from "./files/models"
 import { AUTH_IDENTITY_MODEL, AUTH_SESSION_MODEL, identityPublicFields, sessionPublicFields } from "./auth/models"

package/src/server/inject.ts

@@ -12,3 +12,6 @@ export { ApiError } from "./errors"
 export { channel } from "./channel"
 export { request } from "./context"
 export type { StoredFile, StoredImage } from "./files/models"
+/** The value an SVG source is to the client (`assetIcon(…)` compiles to `SvgSource(…)`): a shared module of
+ *  the design that names an icon per row loads on the server too. The server draws nothing with it. */
+export const SvgSource = (svg: string): { svg: string, tintColor: string | null } => ({ svg, tintColor: null })

package/src/server/runtime.ts

@@ -14,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 type { FilesHost } from "./files/host"
+import type { FilesHost, ResourceReader } from "./files/host"
 import { isChannel, isChannelGroup, setChannelPublisher, type ChannelRecord } from "./channel"
 import { setRequestProvider, type RequestContext } from "./context"
 import type { Db } from "./db/types"
@@ -55,7 +55,7 @@ export const loadServerModules = (
   // 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(" | ")
+    const each = out.dbs.map(db => Object.keys(db).filter(k => k !== "auth" && !k.startsWith("$") && k !== "withAuth" && k !== "seed").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
@@ -83,6 +83,19 @@ const apiStatus = (e: unknown): number | null =>
   e && typeof e === "object" && (e as { name?: string }).name === "ApiError" && typeof (e as { status?: unknown }).status === "number"
     ? (e as { status: number }).status : null
 
+/** What the app is told when the database refused a write a person could have caused: the engine's own
+ *  words — `Like.user, Like.post: the value is already taken (by the row with id 7)` — with the status
+ *  its kind means. A taken unique value, a pointer at no row, a delete other rows forbid: 409; a row that
+ *  is gone: 404. Anything else the database says (a bad payload, a fault) stays a 500: a mistake of the
+ *  code, not of the person. Both transports' errors carry `kind` (marcidb-embedded's, the HTTP one's). */
+const DB_ERROR_STATUS: Record<string, number> = { unique: 409, foreign_key: 409, restrict: 409, duplicate_id: 409, not_found: 404 }
+const dbStatus = (e: unknown): number | null => {
+  if (!e || typeof e !== "object") return null
+  const { name, kind } = e as { name?: unknown, kind?: unknown }
+  if ((name !== "MarciEmbeddedError" && name !== "MarciHttpError") || typeof kind !== "string") return null
+  return DB_ERROR_STATUS[kind] ?? null
+}
+
 /**
  * Build the invoker: `invoke(id, args, ctx)` runs endpoint `id` inside an AsyncLocalStorage-scoped
  * request context (what the `request` global and `db.auth` read) and returns the wire envelope.
@@ -119,7 +132,7 @@ export const createInvoker = (server: LoadedServer, opts: InvokerOptions = {}) =
       const result = await als.run(rc, () => fn(...args))
       return withSession({ ok: true, result: result === undefined ? null : result }, rc)
     } catch (e) {
-      const status = apiStatus(e)
+      const status = apiStatus(e) ?? dbStatus(e)
       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(id, e)
@@ -161,6 +174,54 @@ export const createFileWriter = (server: LoadedServer, opts: { files?: FilesHost
   }
 }
 
+/** What stops a seed — the project's own doing, in words the project's author can act on. */
+export class SeedError extends Error {
+  constructor(message: string) { super(message); this.name = "SeedError" }
+}
+
+export type SeedOutcome =
+  /** the definition has no seed */
+  | { status: "none" }
+  /** the database has rows already: the seed did not run */
+  | { status: "skipped" }
+  /** the seed ran: the rows of every table of the project */
+  | { status: "seeded", rows: Record<string, number> }
+
+/**
+ * The first rows of the project's database: `defineDb(...).seed(fn)` run ONCE, after the host has
+ * brought an EMPTY database to the bundle's schema — a check's, a dev backend's, a deploy's first.
+ * A database with any row of the project's own tables is left as it is (the seed is the start, not a
+ * migration). Inside the seed a file field takes a resource of the project by its path (what a path
+ * literal of a shared module is in the server bundle), read through `read` and stored as an upload
+ * would be. Throws a `SeedError` with the seed's own words when it fails — the host reports it, and the
+ * database is whatever the seed wrote before (the host that wants an all-or-nothing start starts over).
+ */
+export const runSeed = async (server: LoadedServer, opts: { files?: FilesHost | null, read?: ResourceReader } = {}): Promise<SeedOutcome> => {
+  installProvider()
+  const db = server.dbs[0]
+  const fn = db?.$seed
+  if (!db || !fn) return { status: "none" }
+  const names = Object.keys(db.$given)
+  const collection = (name: string) => (db as any)[name.charAt(0).toLowerCase() + name.slice(1)]
+  for (const name of names) if ((await collection(name).count()) > 0) return { status: "skipped" }
+  const rc: RequestContext = { id: "$seed", headers: {} }
+  const files = opts.files ?? null
+  const read: ResourceReader = opts.read ?? (async () => null)
+  const done = files?.enabled ? files.seeding(rc, read) : () => {}
+  try {
+    await als.run(rc, () => fn(db as any))
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e)
+    throw new SeedError(`seed: ${message}`)
+  } finally {
+    done()
+    if (files?.enabled) await als.run(rc, () => files.finish(rc))
+  }
+  const rows: Record<string, number> = {}
+  for (const name of names) rows[name] = await collection(name).count()
+  return { status: "seeded", rows }
+}
+
 /**
  * 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
@@ -187,7 +248,7 @@ export const createSubscribeGuard = (server: LoadedServer, opts: InvokerOptions
       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)
+      const status = apiStatus(e) ?? dbStatus(e)
       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)

package/src/ui/UINode.ts

@@ -41,6 +41,9 @@ export type Color = ColorInput | null
 /** Style props every element accepts. */
 export type BaseStyle = {
   opacity?: number | `${number}`,
+  /** A CSS-style list of `translate` / `scale` / `rotate`. A `%` in a translate is a percent of the
+   *  element's own box (`translate(-50%, -50%)` centres it on its corner), kept as a percent: it
+   *  follows the box through every layout. */
   transform?: string | null,
   /** Pivot of `transform` (CSS `transform-origin` subset): one or two values, each a keyword
    *  (`left`/`center`/`right`, `top`/`center`/`bottom`), a percentage of the box, or a px length

package/src/ui/UIVirtualizedList.ts

@@ -10,20 +10,14 @@ export type UIVirtualizedListStyle = DrawableStyle & ElementStyle & {
   keyboardDismissMode?: "interactive" | "scroll" | "none",
 }
 
-export interface VListConfig<T> {
-    /** The rows, read reactively: the list follows the signals this reads, the way a container's
-     *  function children do. Rows are told apart by `keyOf`; a row whose item is another object
-     *  re-renders. Appended rows and rows added at the start are told from a rewrite (a chat at
-     *  its bottom follows what is appended; older history above moves nothing). */
-    data: () => T[]
+interface VListBaseConfig<T> {
     /** Stable unique key of an item. */
     keyOf: (item: T) => string
     /** Subtree factory — called when the item enters the window; the subtree lives until it
      *  leaves. */
     render: (item: T) => UINodeChild
     /** Height estimate (px) used before the first measurement — a number, or a per-item function
-     *  (chat: `msg => 40 + Math.ceil(msg.text.length / 35) * 20`). Computed once when the item is
-     *  added. */
+     *  (chat: `msg => 40 + Math.ceil(msg.text.length / 35) * 20`). Read when the item is added. */
     estimatedHeight: number | ((item: T) => number)
     /** Extra px around the viewport kept mounted. Default: one viewport height. */
     overscan?: number
@@ -32,9 +26,26 @@ export interface VListConfig<T> {
     inverted?: boolean
 }
 
-/** A windowed (virtualized) list: only the items near the viewport are mounted — for long feeds
- *  and chats. Fed by `data`, a function over signals. */
-export interface UIVirtualizedList<T = unknown> extends UIElementBase<UIVirtualizedListStyle> {
+/** A list fed by `data`: the rows are read reactively, the way a container's function children
+ *  are. Such a list has no imperative feed (`append` and the rest are not on its type). */
+export interface VListBoundConfig<T> extends VListBaseConfig<T> {
+    /** The rows, read reactively: the list follows the signals this reads. Rows are told apart by
+     *  `keyOf`; a row whose item is another object re-renders. The change is told from the keys:
+     *  rows gone are removals, new rows are inserts where they stand (a chat at its bottom follows
+     *  an append; rows above the reader move nothing), a reorder rewrites the keys. */
+    data: () => T[]
+}
+
+/** A list fed by hand: `setData` / `append` / `prepend` / `update` / `removeByKey`. */
+export interface VListFedConfig<T> extends VListBaseConfig<T> {
+    data?: undefined
+}
+
+export type VListConfig<T> = VListBoundConfig<T> | VListFedConfig<T>
+
+/** What both forms of the list share: the items held, scrolling, the scroll / refresh / edge
+ *  callbacks. */
+export interface UIVirtualizedListBase<T = unknown> extends UIElementBase<UIVirtualizedListStyle> {
     readonly type: "vlist"
 
     /** Number of data items (mounted or not). */
@@ -60,7 +71,31 @@ export interface UIVirtualizedList<T = unknown> extends UIElementBase<UIVirtuali
     onStartReached(thresholdPx: number, callback: () => void): this
 }
 
-export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedList<T> {
+/** A virtualized list fed by `data` (a function over signals): write the signal, the list follows. */
+export interface UIBoundVirtualizedList<T = unknown> extends UIVirtualizedListBase<T> {}
+
+/** A virtualized list fed by hand. Each call goes straight to the runtime: `append` is O(1). */
+export interface UIFedVirtualizedList<T = unknown> extends UIVirtualizedListBase<T> {
+    /** Replace the data wholesale — diffed by key like a `data` write (vanished keys are removed,
+     *  new ones inserted where they stand, a reorder rewrites). */
+    setData(items: T[]): this
+    /** Append items to the end (auto-scrolls when `inverted` and resting at the bottom). */
+    append(...items: T[]): this
+    /** Insert at the start WITHOUT a scroll jump (the runtime compensates the offset). */
+    prepend(...items: T[]): this
+    /** Update items with the same keys: mounted ones re-render; the cached height persists until
+     *  re-measured. */
+    update(...items: T[]): this
+    /** Remove items by key. */
+    removeByKey(...keys: string[]): this
+}
+
+/** A windowed (virtualized) list: only the items near the viewport are mounted — for long feeds
+ *  and chats. Fed by `data`, a function over signals, or by hand (`append` and the rest); which
+ *  one is the config's and the type's. */
+export type UIVirtualizedList<T = unknown> = UIBoundVirtualizedList<T> | UIFedVirtualizedList<T>
+
+export class VListElement<T> extends Element<"vlist"> implements UIFedVirtualizedList<T> {
     private readonly sl: ((scrollPosition: number) => void)[] = []     // scroll
     private readonly erl: (() => void)[] = []                          // endReached
     private readonly strl: (() => void)[] = []                         // startReached
@@ -74,6 +109,7 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
     private estimate: (item: T) => number
     private readonly _overscan: number
     private readonly _inverted: boolean
+    private readonly _bound: boolean
     private _endThreshold = 0
     private _startThreshold = 0
     private _inited = false
@@ -90,10 +126,12 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
             : () => config.estimatedHeight as number
         this._overscan = config.overscan ?? -1
         this._inverted = config.inverted ?? false
+        const data = config.data
+        this._bound = data !== undefined
         // The data binding is the element's (it goes with it); its first run waits a microtask so the
         // edge thresholds chained after the constructor (`.onEndReached(…)`) are in the runtime's list
         // state, which is created on the first write.
-        Promise.resolve().then(() => { if (this._h.id !== 0) createBinding(this, "data", () => this._apply(config.data())) })
+        if (data !== undefined) Promise.resolve().then(() => { if (this._h.id !== 0) createBinding(this, "data", () => this._apply(data())) })
     }
 
     // The runtime's list state is created on the first data write — after the app had its chance to
@@ -104,42 +142,68 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
         tree().vlistInit(this._h.id, this._overscan, this._inverted, this._startThreshold, this._endThreshold)
     }
 
-    /** The data as it is now against what the runtime holds: rows added at the end or at the start
-     *  are inserts (the runtime anchors the scroll: a chat follows an append, history above moves
-     *  nothing), rows gone are removals, anything else a rewrite of the keys (measured heights stay). */
+    /** The two feeds are exclusive per list: a hand-made change to a list `data` feeds would be
+     *  undone by the binding's next run, so it is refused and logged. */
+    private _fed(method: string): boolean {
+        if (!this._bound) return true
+        console.error(`UIVirtualizedList.${method}(): the list is fed by data — write the signal it reads instead`)
+        return false
+    }
+
+    /** The data as it is now against what the runtime holds. Keys gone are removals, keys new are
+     *  inserts where they stand in the new order — both anchored by the runtime (a chat follows an
+     *  append, rows above the reader move nothing) — as long as the keys kept keep their order;
+     *  a reorder rewrites the keys (measured heights stay). A mounted row whose item is another
+     *  object re-renders. */
     private _apply(next: T[]): void {
         const prevKeys = this.keys
         const prevItems = this.items
         const keys: string[] = []
-        const estimates: number[] = []
         const items = new Map<string, T>()
         for (const item of next) {
             const k = this.keyOf(item)
             if (items.has(k)) continue                      // a repeated key: the first row stands
             items.set(k, item)
             keys.push(k)
-            estimates.push(this.estimate(item))
         }
         this.keys = keys
         this.items = items
         this._ensure()
         const id = this._h.id
         if (id === 0) return
+        // the estimates of keys[from, to): read for the rows the runtime is told of, not for every row
+        const estimates = (from: number, to: number): number[] => {
+            const out: number[] = []
+            for (let i = from; i < to; i++) out.push(this.estimate(items.get(keys[i])!))
+            return out
+        }
         const n = prevKeys.length, m = keys.length
-        const same = (from: number) => { for (let i = 0; i < n; i++) if (keys[from + i] !== prevKeys[i]) return false; return true }
         if (n === 0 || m === 0) {
-            tree().vlistSetKeys(id, keys, estimates)
-        } else if (m >= n && same(0)) {
-            if (m > n) tree().vlistInsertKeys(id, -1, keys.slice(n), estimates.slice(n))   // the same keys: nothing to tell
-        } else if (m > n && same(m - n)) {
-            tree().vlistInsertKeys(id, 0, keys.slice(0, m - n), estimates.slice(0, m - n))
+            tree().vlistSetKeys(id, keys, estimates(0, m))
         } else {
-            // removals only: the new keys are the old ones in order, some left out
+            // the keys kept, in the old order, must be the keys kept in the new order
             const gone: string[] = []
-            let j = 0
-            for (const k of prevKeys) { if (j < m && keys[j] === k) j++; else gone.push(k) }
-            if (m < n && j === m) tree().vlistRemoveKeys(id, gone)
-            else tree().vlistSetKeys(id, keys, estimates)
+            let j = 0, ordered = true
+            for (const k of prevKeys) {
+                if (!items.has(k)) { gone.push(k); continue }
+                while (j < m && !prevItems.has(keys[j])) j++    // skip the new rows
+                if (keys[j] !== k) { ordered = false; break }
+                j++
+            }
+            if (!ordered) {
+                tree().vlistSetKeys(id, keys, estimates(0, m))
+            } else {
+                if (gone.length > 0) tree().vlistRemoveKeys(id, gone)
+                // runs of new rows, in order: everything before a run is already in the list, so the
+                // run's position in the new array is its index in the list as it stands
+                for (let i = 0; i < m;) {
+                    if (prevItems.has(keys[i])) { i++; continue }
+                    let e = i + 1
+                    while (e < m && !prevItems.has(keys[e])) e++
+                    tree().vlistInsertKeys(id, e === m ? -1 : i, keys.slice(i, e), estimates(i, e))
+                    i = e
+                }
+            }
         }
         // a mounted row whose item is another object re-renders; the others pick theirs up when they re-enter
         for (const k of this.mounted.keys()) {
@@ -147,6 +211,67 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
         }
     }
 
+    /** The new rows of `items` (keys not held yet, repeats dropped), registered. */
+    private _register(items: T[]): [string[], number[]] {
+        const keys: string[] = []
+        const estimates: number[] = []
+        for (const item of items) {
+            const k = this.keyOf(item)
+            if (this.items.has(k)) continue
+            this.items.set(k, item)
+            keys.push(k)
+            estimates.push(this.estimate(item))
+        }
+        return [keys, estimates]
+    }
+
+    // --- the hand feed: each call is the runtime's operation, no diff ---
+    setData(items: T[]): this {
+        if (this._fed("setData")) this._apply(items)
+        return this
+    }
+
+    append(...items: T[]): this {
+        if (!this._fed("append")) return this
+        const [keys, estimates] = this._register(items)
+        if (keys.length === 0) return this
+        this.keys.push(...keys)
+        this._ensure()
+        if (this._h.id !== 0) tree().vlistInsertKeys(this._h.id, -1, keys, estimates)
+        return this
+    }
+
+    prepend(...items: T[]): this {
+        if (!this._fed("prepend")) return this
+        const [keys, estimates] = this._register(items)
+        if (keys.length === 0) return this
+        this.keys = keys.concat(this.keys)
+        this._ensure()
+        if (this._h.id !== 0) tree().vlistInsertKeys(this._h.id, 0, keys, estimates)
+        return this
+    }
+
+    update(...items: T[]): this {
+        if (!this._fed("update")) return this
+        for (const item of items) {
+            const k = this.keyOf(item)
+            if (!this.items.has(k) || this.items.get(k) === item) continue
+            this.items.set(k, item)
+            if (this._h.id !== 0 && this.mounted.has(k)) tree().vlistInvalidate(this._h.id, k)
+        }
+        return this
+    }
+
+    removeByKey(...keys: string[]): this {
+        if (!this._fed("removeByKey")) return this
+        const gone: string[] = []
+        for (const k of keys) if (this.items.delete(k)) gone.push(k)
+        if (gone.length === 0) return this
+        this.keys = this.keys.filter((k) => this.items.has(k))
+        if (this._h.id !== 0) tree().vlistRemoveKeys(this._h.id, gone)
+        return this
+    }
+
     get itemCount(): number { return this.items.size }
     getItem(key: string): T | undefined { return this.items.get(key) }
 
@@ -212,8 +337,11 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
     }
 }
 
-/** Create a virtualized list from a config (`data` + `keyOf` + `render` + `estimatedHeight`
- *  required). Give it a size (`flexGrow: 1` as a screen body). */
+/** Create a virtualized list (`keyOf` + `render` + `estimatedHeight` required). With `data` the
+ *  list follows the signals it reads and has no hand feed; without it, feed it with `setData` /
+ *  `append` / `prepend` / `update` / `removeByKey`. Give it a size (`flexGrow: 1` as a screen body). */
+export function UIVirtualizedList<T>(config: VListBoundConfig<T>): UIBoundVirtualizedList<T>
+export function UIVirtualizedList<T>(config: VListFedConfig<T>): UIFedVirtualizedList<T>
 export function UIVirtualizedList<T>(config: VListConfig<T>): UIVirtualizedList<T> {
     return new VListElement<T>(config)
 }

package/src/ui/transitions.ts

@@ -128,7 +128,7 @@ type Side = { lanes: Lane[], atMs: number, durMs: number, easing: EasingSpec }
 const list = <T>(v: T | T[]): T[] => (Array.isArray(v) ? v : [v])
 
 const transformLane = (value: string | string[]): Lane | null => {
-  const parsed = list(value).map((v) => parseTransformList(v, true))
+  const parsed = list(value).map((v) => parseTransformList(v))
   const first = parsed[0]
   if (!first || parsed.some((p) => p === null || p.sig !== first.sig)) {
     warnOnce("transition:transform", "a transition's transform must be a list of translate / scale / rotate, the same functions in every keyframe — ignored")

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.2.3"
+export const SDK_VERSION = "2.2.4"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {