@weft-js/start 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @weft-js/start
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Early release (0.1.0).** APIs will change between minor versions.
+
+The full-stack part of weft: routes from files, server functions, server rendering with streaming, a database, auth and
+realtime. It runs on Node, Bun or Deno, and doesn't need Rust. An app made with `npm create @weft-js` already has it.
+
+```bash
+npm install @weft-js/start
+```
+
+A server function in `src/server/` runs on the server. The client gets a stub that calls it:
+
+```ts
+// src/server/greeting.ts
+import { query } from '@weft-js/start'
+
+export const greeting = query({ run: () => `Hello at ${new Date().toISOString()}` })
+```
+
+A route in `src/routes/` reads it. Calling the query in a component gives a `Resource`, a box that fills when the data
+arrives:
+
+```tsx
+// src/routes/hello.tsx
+import { greeting } from '#/server/greeting'
+
+export default function Hello() {
+  const text = greeting()
+  return <p>{text.value ?? 'Loading…'}</p>
+}
+```
+
+`npx weft dev` serves it at `/hello`.
+
+## Docs
+
+- `weft docs start`: routes, `load`, `query`, `mutation`, the database, auth, runtimes and realtime.
+- `weft docs meta`: page metadata and share cards.
+- `weft docs rust`: server functions with a Rust body, if you want them.
+
+The source of each page is in [packages/cli/docs](../cli/docs).

package/package.json

@@ -1,6 +1,109 @@
 {
   "name": "@weft-js/start",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "weft Start: file routes, server functions, streaming SSR, a database and auth",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@fontsource/inter": "5.3.0",
+    "@takumi-rs/core": "2.18.2",
+    "@takumi-rs/helpers": "2.18.2",
+    "@takumi-rs/wasm": "2.18.2",
+    "@tanstack/history": "1.162.5",
+    "@tanstack/router-core": "1.171.39",
+    "nitro": "3.0.260903-beta",
+    "vite": "8.3.5"
+  },
+  "peerDependencies": {
+    "better-auth": "^1.7.0",
+    "drizzle-orm": "^0.45.0",
+    "drizzle-zod": "^0.8.0",
+    "mysql2": "^3.24.0",
+    "postgres": ">=3",
+    "@weft-js/core": "^0.1.0",
+    "zod": "^4.0.0"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./data": "./src/data.ts",
+    "./derive": "./src/derive.mjs",
+    "./media": "./src/media.ts",
+    "./hub": "./src/hub.ts",
+    "./live": "./src/stream.ts",
+    "./bus": "./src/bus.ts",
+    "./changes": "./src/changes.ts",
+    "./changes-sql": "./src/changes-sql.mjs",
+    "./live-target": "./src/live-target.mjs",
+    "./listen": "./src/listen.ts",
+    "./verify": "./src/verify.ts",
+    "./bus/postgres": "./src/bus/postgres.ts",
+    "./list": "./src/list.ts",
+    "./list/drizzle": "./src/list-drizzle.ts",
+    "./channel": "./src/channel.ts",
+    "./share": "./src/share.ts",
+    "./db": "./src/db/index.ts",
+    "./db/core": "./src/db/core.ts",
+    "./db/sqlite": "./src/db/sqlite.ts",
+    "./db/postgres": "./src/db/postgres.ts",
+    "./db/mysql": "./src/db/mysql.ts",
+    "./auth": "./src/auth.ts",
+    "./auth/better-auth": "./src/auth/better-auth.ts",
+    "./auth/drizzle": "./src/auth/drizzle.ts",
+    "./extension": "./src/extension.ts",
+    "./client": "./src/client.tsx",
+    "./server": "./src/server.tsx",
+    "./vite": "./src/vite.mjs",
+    "./routes": "./src/routes.mjs",
+    "./og": "./src/og/index.mjs",
+    "./app": "./src/app.mjs",
+    "./inspect": "./src/inspect.mjs",
+    "./contract": "./src/contract.mjs",
+    "./rust": "./src/rust.ts",
+    "./sidecar": "./src/sidecar.mjs"
+  },
+  "sideEffects": [
+    "**/*.css",
+    "./src/share.ts"
+  ],
+  "peerDependenciesMeta": {
+    "better-auth": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    },
+    "drizzle-zod": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "postgres": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "@nats-io/transport-node": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "files": [
+    "src",
+    "crate",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/app.mjs

@@ -0,0 +1,82 @@
+// `weft dev` and `weft build` for an app with src/routes (research 25 §6): Vite 8 with weft() (hydratable output),
+// weftStart() and Nitro's Vite plugin. A vite.config in the app is merged in. The CLI passes the config's `site`.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createBuilder, createServer } from 'vite'
+import { nitro } from 'nitro/vite'
+import weft from '@weft-js/core/vite'
+import { devRunner, devSockets } from './dev-runtime.mjs'
+import weftStart, { startDir } from './vite.mjs'
+
+/** An app with a `channel` or `sharedState`: only those pay for crossws in the server bundle (research 32 §1). */
+function usesSockets(root) {
+  const src = join(root, 'src')
+  if (!existsSync(src)) return false
+  return readdirSync(src, { recursive: true, withFileTypes: true }).some(f => f.isFile() && /\.[cm]?[jt]sx?$/.test(f.name) && /\b(channel|sharedState)\s*[(<]/.test(readFileSync(join(f.parentPath, f.name), 'utf8')))
+}
+
+function config({ root, site, hydration, preset, port, logLevel, command, nitro: nitroOptions = {} }) {
+  root = resolve(root)
+  const sockets = usesSockets(root)
+  const runner = devRunner(sockets)
+  const user = ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs'].map(f => join(root, f)).find(existsSync)
+  return {
+    root,
+    configFile: user ?? false,
+    logLevel,
+    server: { port: port ?? 5173, strictPort: port !== undefined },
+    plugins: [
+      weft({ hydratable: true }),
+      weftStart({ root, site, hydration }),
+      runner && devSockets(),
+      nitro({
+        preset,
+        // Every app gets this: built assets ship as .br and .gz next to the file, and Nitro picks by Accept-Encoding.
+        compressPublicAssets: { gzip: true, brotli: true },
+        ...(site?.headers && { routeRules: Object.fromEntries(Object.entries(site.headers).map(([path, headers]) => [path, { headers }])) }),
+        ...(sockets && { features: { websocket: true } }),
+        ...(runner && { devServer: { runner } }),
+        // Build mode for share cards (research 20 §4.3): the server lists them and Nitro's prerender writes the PNGs.
+        prerender: { routes: ['/_weft/og-routes'], failOnError: true },
+        // Prerendered cards are static files at content-addressed URLs: immutable. The rule names each file (a
+        // `/_weft/og/**` rule would also override the handler's no-cache for a stale `?v=` on demand). Prerender runs
+        // before Nitro bundles the server, so rules added when it is done are in the build. (Dev sends no-store.)
+        ...(command === 'build' && { hooks: immutableCards(), plugins: [fileURLToPath(new URL('./range.mjs', import.meta.url))] }),
+        // The media route: sharp's addon, and css-tree and csso (under svgo) read JSON from their packages at runtime.
+        ...(existsSync(join(root, '.weft/slots/media.server.ts')) && { traceDeps: ['css-tree*', 'csso*', 'sharp*'] }),
+        ...nitroOptions,
+      }),
+    ],
+  }
+}
+
+function immutableCards() {
+  let built
+  return {
+    'prerender:generate'(_route, instance) { built = instance },
+    'prerender:done'({ prerenderedRoutes }) {
+      if (!built) return
+      for (const r of prerenderedRoutes) {
+        if (r.route.startsWith('/_weft/og/') && r.route.endsWith('.png')) built.options.routeRules[r.route] = { headers: { 'cache-control': 'public, max-age=31536000, immutable' } }
+      }
+      built.routing.sync()
+    },
+  }
+}
+
+/** Start the dev server; resolves with it once it listens. */
+export async function dev(options) {
+  const server = await createServer(config(options))
+  await server.listen()
+  return server
+}
+
+/** Build client and server into `.output/` for `preset` (node by default; bun, deno_server…). */
+export async function build(options) {
+  process.env.WEFT_START_DIR ??= startDir // for the share cards a build draws (og/native.mjs)
+  const builder = await createBuilder(config({ ...options, command: 'build' }))
+  await builder.buildApp()
+  return { output: join(resolve(options.root), '.output') }
+}

package/src/auth/better-auth.ts

@@ -0,0 +1,58 @@
+// Better Auth as weft's default auth provider (research 28 §3, 34 §5). `src/auth.server.ts` default-exports `createAuth(…)`.
+// No client code: sign-in is a mutation, so nothing of Better Auth ships to the browser.
+
+import { betterAuth, type BetterAuthOptions } from 'better-auth'
+import { CLIENT_IP, StartError } from '../data'
+import type { DbHandle } from '../db/core'
+
+const SESSION = /(?:^|;\s*)(?:__Secure-)?[\w.-]*session_token=/
+const buildSecret = () => Array.from(crypto.getRandomValues(new Uint8Array(32)), x => x.toString(16).padStart(2, '0')).join('')
+
+/** `createAuth`: the database, the secret, and any Better Auth option on top. */
+export interface AuthOptions<S extends Record<string, unknown>, O extends BetterAuthOptions> {
+  db: { $weft: DbHandle }
+  /** The tables, Better Auth's included, for a data layer that needs them. */
+  schema?: S
+  /** 32+ characters (A001 in production). */
+  secret?: string
+  /** The rest of Better Auth's options; they win over the defaults here. */
+  options?: O
+}
+
+/** A Better Auth instance with Weft's defaults, on the store `options.database` names. */
+export function createAuth<S extends Record<string, unknown>, const O extends BetterAuthOptions = {}>({ db, secret, options }: AuthOptions<S, O>) {
+  const handle = db.$weft
+  if (options?.database) for (const name of ['user', 'session', 'account', 'verification']) handle.exempt.add(name)
+  else throw new StartError('A005', 'Better Auth has no store', 'pass `options.database`: `drizzleAuth(db, schema)` from @weft-js/start/auth/drizzle, or your data layer\'s adapter')
+  const auth = betterAuth({
+    // A build loads this module with no environment, and in production Better Auth refuses to start without a secret: the
+    // build gets one of its own, since nothing it makes is signed. A server still needs the real one (A001).
+    secret: secret ?? (process.env.WEFT_BUILD ? buildSecret() : undefined),
+    // A build's prerender holds no environment; a server takes `BETTER_AUTH_URL`, or the request's origin.
+    ...(process.env.WEFT_BUILD && { baseURL: 'http://localhost' }),
+    telemetry: { enabled: false },
+    emailAndPassword: { enabled: true },
+    ...options,
+    // The server stamps this header from the socket (server.tsx), so rate limits aren't one bucket for everyone.
+    // Its schema check runs when this module loads. On Kysely that connects, in a build, and before a fresh database has
+    // had weft's migrations. Q014 covers a schema that doesn't match, so it's off unless you turn it on.
+    advanced: { ...options?.advanced, database: { validateSchema: false, ...options?.advanced?.database }, ipAddress: { ipAddressHeaders: [CLIENT_IP], ...options?.advanced?.ipAddress } },
+  })
+  return Object.assign(auth, {
+    basePath: options?.basePath,
+    /** With no session cookie it's `null` without a query, so anonymous pages don't touch the database. */
+    async session(request: Request) {
+      if (!SESSION.test(request.headers.get('cookie') ?? '')) return { user: null, session: null }
+      const s = await (auth as unknown as ReturnType<typeof betterAuth<BetterAuthOptions>>).api.getSession({ headers: request.headers })
+      return { user: s?.user ?? null, session: s?.session ?? null }
+    },
+    $weft: {
+      /** On the first request (never in a build, which holds no secrets). */
+      check() {
+        if (process.env.NODE_ENV === 'production' && (secret?.length ?? 0) < 32)
+          throw new StartError('A001', 'the auth secret is missing or under 32 characters', 'set `BETTER_AUTH_SECRET` (`openssl rand -base64 32`) in the server\'s environment')
+      },
+    },
+  })
+}
+

package/src/auth/drizzle.ts

@@ -0,0 +1,17 @@
+// Better Auth on a Drizzle client, as `options.database`. It's an entry of its own so that a Drizzle app without auth
+// needs no better-auth, and an app on another data layer needs no drizzle-orm.
+
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { getTableName, isTable } from 'drizzle-orm'
+import type { DbHandle } from '../db/core'
+
+const PROVIDER = { sqlite: 'sqlite', postgresql: 'pg', mysql: 'mysql' } as const
+
+/** Better Auth's store on a Weft database, for `createAuth`'s `options.database`. */
+export function drizzleAuth(db: { $weft: DbHandle }, schema?: Record<string, unknown>) {
+  for (const name of ['user', 'session', 'account', 'verification']) {
+    const t = schema?.[name]
+    if (isTable(t)) db.$weft.exempt.add(getTableName(t))
+  }
+  return drizzleAdapter(db, { provider: PROVIDER[db.$weft.dialect], schema })
+}

package/src/auth.ts

@@ -0,0 +1,47 @@
+// `@weft-js/start/auth`: what weft needs from any auth provider (research 34 §5). A provider is `src/auth.server.ts`'s default
+// export: `handler` serves its routes under `basePath`, and `session` says who a request is. Nothing here knows Better
+// Auth (`@weft-js/start/auth/better-auth`, the default), so a hand-written provider has no private path to work around.
+
+import { FnError, type Context } from './data'
+
+/** Where a session comes from: Better Auth by default, or anything with a `handler` and a `session`. */
+export interface AuthProvider<U = unknown, S = unknown> {
+  /** Serves everything under `basePath`. */
+  handler(request: Request): Promise<Response> | Response
+  /** Who this request is. Anonymous is `{ user: null, session: null }`, and should cost no query. */
+  session(request: Request): Promise<{ user: U | null; session: S | null }>
+  /** Where `handler` is mounted (default `/api/auth`). */
+  basePath?: string
+  $weft?: {
+    /** On the first request, never in a build: throw for a server that can't run safely. */
+    check(): void
+  }
+}
+
+/** A provider you wrote: checks its shape, and types `ctx.user` from your `session`. */
+export function defineAuth<U, S>(provider: AuthProvider<U, S>): AuthProvider<U, S> {
+  return provider
+}
+
+/** `{ user, session }` for `ctx` (`src/context.server.ts`), from any provider. */
+export const session = <A extends { session(request: Request): unknown }>(auth: A, request: Request): ReturnType<A['session']> => auth.session(request) as ReturnType<A['session']>
+
+const changed = new WeakSet<Headers>()
+
+/** `forward` put a provider's cookie on this response, so who's signed in may have changed. */
+export const sessionChanged = (headers: Headers) => changed.has(headers)
+
+/**
+ * Finish a provider's Response (Better Auth's with `asResponse: true`): its cookies go on this response, so a redirect
+ * after it is a full load, and a failure rejects with the provider's message (`e.message` on the client).
+ */
+export async function forward<T = unknown>(ctx: Context, call: Response | Promise<Response>): Promise<T> {
+  const res = await call
+  for (const c of res.headers.getSetCookie()) {
+    ctx.response.headers.append('set-cookie', c)
+    changed.add(ctx.response.headers)
+  }
+  const body = await res.json().catch(() => null) as (T & { code?: string; message?: string }) | null
+  if (!res.ok) throw new FnError({ ...(body?.code && { code: body.code }), message: body?.message ?? 'Authentication failed' }, res.status)
+  return body as T
+}

package/src/boot.ts

@@ -0,0 +1,44 @@
+// All a page that's only being read runs (PLAN §11). It starts `full` (the router, the runtime) when the page needs code at once, when something happens on an island, or when an island that
+// wants to be running, or that isn't in the first view and so wasn't preloaded, comes into view. A visitor who asked for
+// less data gets it on interaction only. `#weft-route` and the islands' comments are read by `start()` once it's here.
+
+/** What the inline script left on `window`: the queue, and how to play or wake it. */
+export interface Held { q: unknown[]; p: (held: unknown) => void; w?: (k: Element, lead?: 1) => void; r?: 1; n?: unknown; l?: Element; d?: unknown }
+
+export function boot(full: () => Promise<unknown>) {
+  const q = (window as Window & { __wq?: Held }).__wq
+  let io: IntersectionObserver | undefined // oxlint-disable-line prefer-const -- `go` reads it, and can run before it's set
+  const go = () => {
+    if (q) q.w = () => {}
+    io?.disconnect()
+    full().catch(() => {
+      // No code is coming: what's held takes its default.
+      if (!q) return
+      q.r = 1
+      q.q.splice(0).forEach(q.p)
+    })
+  }
+  if (!q || q.n || q.q.length) return go()
+  q.w = (k: Element, lead?: 1) => {
+    if (lead) q.l = k
+    go()
+  }
+  if (q.d) return
+  const first = new WeakSet<Element>()
+  const needs = new WeakSet<Element>()
+  io = new IntersectionObserver(list => {
+    for (const e of list) {
+      const was = first.has(e.target)
+      first.add(e.target)
+      if (e.isIntersecting && (was || needs.has(e.target))) return go()
+    }
+  }, { rootMargin: '600px' })
+  const w = document.createTreeWalker(document.body, 128)
+  while (w.nextNode()) {
+    const c = w.currentNode as Comment
+    const el = c.data.startsWith('wi:') && c.nextElementSibling
+    if (!el) continue
+    if (JSON.parse(c.data.slice(3))[3] === 'v') needs.add(el)
+    io.observe(el)
+  }
+}

package/src/builtin.tsx

@@ -0,0 +1,19 @@
+// The 404 and error pages an app gets until it adds `src/routes/404.tsx` or `src/routes/_error.tsx`.
+
+export function NotFoundPage(props: { data: { path?: string } }) {
+  return (
+    <main>
+      <h1>Not found</h1>
+      <p>Nothing lives at {props.data?.path}.</p>
+    </main>
+  )
+}
+
+export function ErrorPage(props: { data: { status: number; message: string } }) {
+  return (
+    <main>
+      <h1>Something went wrong</h1>
+      <p>{props.data?.message}</p>
+    </main>
+  )
+}

package/src/bus/postgres.ts

@@ -0,0 +1,91 @@
+// LISTEN/NOTIFY (research 30 §3): one dedicated connection and one Postgres channel, with the logical channel in the
+// payload, because Postgres identifiers stop at 63 bytes and tags don't. NOTIFY stops at 8,000 bytes, so a longer
+// message goes base64 in numbered chunks inside one transaction, which Postgres delivers together and in order.
+
+import postgres from 'postgres'
+import type { Bus } from '../bus'
+import { StartError } from '../data'
+
+/** `postgresBus`: the database to send NOTIFY through. */
+export interface PostgresBusOptions {
+  /** `postgres://…`, direct: pgBouncer in transaction mode breaks LISTEN. */
+  url: string
+}
+
+const CHANNEL = 'weft_bus'
+const WHOLE = 7_900
+const CHUNK = 7_800
+
+/** A bus on Postgres NOTIFY, for several instances with no broker beside the database. */
+export function postgresBus({ url }: PostgresBusOptions): Bus {
+  if (!url && process.env.WEFT_BUILD) url = 'postgres://localhost/build' // a build loads this module and never connects
+  if (!/^postgres(ql)?:\/\//.test(url ?? ''))
+    throw new StartError('Q013', `\`postgresBus\` needs a \`postgres://\` URL, not \`${(url ?? '').replace(/\/\/.*@/, '//…@')}\``, 'set `DATABASE_URL`, or leave `bus` out for the memory bus on one instance')
+  let sql: ReturnType<typeof postgres> | undefined
+  const client = () => (sql ??= postgres(url, { max: 2, idle_timeout: 20, onnotice: () => {} }))
+  const listeners = new Map<string, Set<(message: string) => void>>()
+  const gaps = new Set<() => void>()
+  const parts = new Map<string, string[]>()
+  let listening: Promise<unknown> | undefined
+  let connected = false
+
+  const deliver = (text: string) => {
+    const at = text.indexOf('\n')
+    const list = listeners.get(text.slice(0, at))
+    if (list) for (const on of list) on(text.slice(at + 1))
+  }
+  const received = (payload: string) => {
+    if (payload[0] === '=') return deliver(payload.slice(1))
+    const [id, i, n, body] = payload.slice(1).split(':')
+    if (id === undefined || i === undefined || n === undefined || body === undefined) return undefined
+    const got = parts.get(id) ?? []
+    got[+i] = body
+    parts.set(id, got)
+    if (Object.keys(got).length < +n) return undefined
+    parts.delete(id)
+    deliver(Buffer.from(got.join(''), 'base64').toString())
+  }
+  /** `onlisten` runs on every (re)connect: after the first, whatever was published meanwhile is gone. */
+  const listen = () => (listening ??= client().listen(CHANNEL, received, () => {
+    if (connected) {
+      parts.clear()
+      for (const gap of gaps) gap()
+    }
+    connected = true
+  }).catch(e => {
+    listening = undefined // the next subscribe tries again
+    throw e
+  }))
+
+  return {
+    name: 'postgres',
+    async publish(channel, message) {
+      const text = `${channel}\n${message}`
+      if (Buffer.byteLength(text) <= WHOLE) return void (await client().notify(CHANNEL, '=' + text))
+      const b64 = Buffer.from(text).toString('base64')
+      const id = crypto.randomUUID()
+      const n = Math.ceil(b64.length / CHUNK)
+      await client().begin(async tx => {
+        for (let i = 0; i < n; i++) await tx`select pg_notify(${CHANNEL}, ${`+${id}:${i}:${n}:${b64.slice(i * CHUNK, (i + 1) * CHUNK)}`})`
+      })
+    },
+    async subscribe(channel, on, gap) {
+      let list = listeners.get(channel)
+      if (!list) listeners.set(channel, (list = new Set()))
+      list.add(on)
+      if (gap) gaps.add(gap)
+      await listen()
+      return () => {
+        list.delete(on)
+        if (!list.size) listeners.delete(channel)
+        if (gap) gaps.delete(gap)
+      }
+    },
+    async close() {
+      await sql?.end({ timeout: 1 })
+      sql = undefined
+      listening = undefined
+      connected = false
+    },
+  }
+}

package/src/bus.ts

@@ -0,0 +1,48 @@
+// The fan-out bus (research 30 §3): strings, at-most-once, ordered per publisher. Tags, topics, rings and cursors stay
+// in the hub, so a bus is three methods. `@weft-js/realtime-redis`, `-nats` and `-durable-object` implement this interface.
+
+/** How one instance reaches the others: the in-memory bus for one process, a plugin's for many. */
+export interface Bus {
+  readonly name: string
+  publish(channel: string, message: string): Promise<void>
+  /**
+   * Resolves once listening, with the way to stop. `gap` means messages may have been lost (a dropped connection):
+   * the hub treats everything before it as out of the resume window.
+   */
+  subscribe(channel: string, on: (message: string) => void, gap?: () => void): Promise<() => void>
+  close?(): Promise<void>
+}
+
+/** The bus a `realtime.bus` plugin provides, loaded on the first publish or subscribe: `weft build` reaches for neither. */
+export function slotBus(plugin: string, load: () => Promise<Bus>): Bus {
+  let bus: Promise<Bus> | undefined
+  const get = () => (bus ??= load())
+  return {
+    name: plugin.replace(/^.*realtime-/, ''),
+    publish: (channel, message) => get().then(b => b.publish(channel, message)),
+    subscribe: (channel, on, gap) => get().then(b => b.subscribe(channel, on, gap)),
+    close: () => (bus ? bus.then(b => b.close?.()) : Promise.resolve()),
+  }
+}
+
+/** One process (PLAN §4.2). Delivered in a microtask: no code may rely on a fan-out no other bus has. */
+export function memoryBus(): Bus {
+  const channels = new Map<string, Set<(message: string) => void>>()
+  return {
+    name: 'memory',
+    publish(channel, message) {
+      const list = channels.get(channel)
+      if (list) queueMicrotask(() => { for (const on of list) on(message) })
+      return Promise.resolve()
+    },
+    subscribe(channel, on) {
+      let list = channels.get(channel)
+      if (!list) channels.set(channel, (list = new Set()))
+      list.add(on)
+      return Promise.resolve(() => {
+        list.delete(on)
+        if (!list.size) channels.delete(channel)
+      })
+    },
+  }
+}

package/src/capture.d.mts

@@ -0,0 +1 @@
+export declare const capture: (now: boolean) => string

package/src/capture.mjs

@@ -0,0 +1,15 @@
+// What every page of an app with lazy islands carries inline, so nothing done before the code arrives is lost (PLAN §11). An element
+// with `wk` that hasn't been claimed (no `$k`) belongs to code that isn't there: its events go in `q` in order, and
+// `start()` replays them. A click, submit or reset waits with its default held, and the replay is what acts, so a page
+// whose code never comes just runs the defaults late. Everything else (typing, focus) has already happened in the DOM.
+// A modified click on a link is the browser's (a new tab), and stays out of it.
+//
+//   q  the events    n  the page needs its code at once    w  wake: (element, lead), a lead being only a hint of intent
+//   p  replay one    r  replaying, so don't capture        d  the visitor asked for less data      l  the last lead
+//
+// Written by hand and small, since every such page pays it: `boot.ts` and weft's `island.ts` are the other two halves.
+
+const CODE = `(n=>{var d=document,c=navigator.connection,q=window.__wq={q:[],n:n,w(){},d:matchMedia("(prefers-reduced-data: reduce)").matches||!!(c&&c.saveData),p(e){var t=e.target,r=q.r,s=e.submitter;if(t.isConnected){q.r=1;try{e.type=="submit"?t.requestSubmit(s&&s.isConnected?s:void 0):e.type=="reset"?t.reset():t.dispatchEvent(new e.constructor(e.type,e))}finally{q.r=r}}}},o=t=>t.closest&&t.closest("[wk]"),h=e=>{var k=!q.r&&o(e.target);if(k&&(!k.$k||q.q.length)&&!((e.metaKey||e.ctrlKey||e.shiftKey)&&e.type=="click"&&e.target.closest("a"))){q.q.push(e);/^(click|submit|reset)$/.test(e.type)&&e.preventDefault();q.w(k)}},l=e=>{var k=o(e.target);k&&!k.$k&&!q.d&&q.w(k,1)};"click dblclick pointerdown pointerup mousedown mouseup keydown keyup input change submit reset focus blur focusin focusout".split(" ").forEach(t=>d.addEventListener(t,h,!0));"pointerover touchstart".split(" ").forEach(t=>d.addEventListener(t,l,{capture:!0,passive:!0}))})`
+
+/** The script's text. `now`: the page has work that can't wait, so its code loads straight away. */
+export const capture = now => `${CODE}(${now ? 1 : 0})`

package/src/changes-sql.d.mts

@@ -0,0 +1,14 @@
+/** The NOTIFY channel Postgres triggers send on. */
+export const CHANNEL: string
+/** The log table SQLite and MySQL triggers write to. */
+export const LOG: string
+/** More ids than this in one statement is a table-level change. */
+export const MAX_IDS: number
+/** Rows SQLite's log keeps; a reader further behind pokes every table. */
+export const LOG_ROWS: number
+/** Between statements of generated SQL, as Drizzle splits them. */
+export const BREAK: string
+/** The trigger statements for these tables, one by one. */
+export function changeStatements(dialect: string, tables: readonly { name: string; pk?: string[] }[]): string[]
+/** The same statements as one migration. */
+export function changeSql(dialect: string, tables: readonly { name: string; pk?: string[] }[]): string