@abide/abide 0.47.0 → 0.49.0

package/AGENTS.md

@@ -92,12 +92,17 @@ validate as args, `File` parts validate against `filesSchema`.
 
 **Consuming an rpc** — the bare call `fn(args, opts?)` IS the smart read:
 cached, coalesced, reactive, stale-while-revalidate for replayable (GET/HEAD)
-reads; the second arg takes `{ ttl, tags, throttle, debounce, global, n }`
-(retention and the refetch clock — not transport). `global: true` stores the
-entry in the process-level store instead of the request-scoped default
-(server), so later requests reuse the value — for memoising an external
-endpoint, never per-user data; on the client it is a no-op (one tab store).
-During SSR the same call resolves
+reads; the second arg takes `{ ttl, tags, throttle, debounce, shared, n }`
+(retention and the refetch clock — not transport). `ttl` defaults to `0` on
+the server (coalesce-only — the request is the atomic unit, nothing is
+retained past it) and `Infinity` on the client (retain until invalidate/
+refresh). `shared: true` selects the process-level store instead of the
+request-scoped default (server) — it does not by itself retain, pair it with
+an explicit `ttl` (e.g. `{ shared: true, ttl: Infinity }`) to memoise across
+requests, for an external endpoint, never per-user data; on the client it is
+a no-op (one tab store). A read with no request in flight (e.g. a background
+job) also resolves against the process-level store. During SSR the same call
+resolves
 in-process and its value is baked into the HTML so hydration starts warm —
 there is no `cache()` wrapper; the bare call carries the caching. Around it:
 `fn.raw(args, init?)` returns the raw `Response` (per-call transport options —
@@ -184,7 +189,7 @@ cells read/written through `.value`.
 | `state.share(key, value)` / `state.shared(key)` | members of `state` | Put a named value on the ambient scope / read the closest ancestor's |
 | `watch(source, handler)` | `@abide/abide/ui/watch` | The single reaction primitive (client-only, stripped from SSR). Sources: a bare thunk `watch(() => …)` (auto-tracked effect), a state cell, a cell array, a socket/stream (`handler(frame)` per frame with reconnect replay), an rpc (`watch(fn, args?, handler)` — runs the smart read, `handler(value)` on each change). Returns a scope-tied disposer |
 | `html(str)` / `` html`…` `` | `@abide/abide/ui/html` | Brands trusted raw HTML so `{expr}` inserts nodes instead of escaped text; plain `{value}` always escapes |
-| `props()` | ambient (no import) | The prop reader: `const { name = fallback, ...rest } = props()`; a page's props are its route params |
+| `props()` | `@abide/abide/ui/props` | The prop reader, resolved by import binding (alias-safe) like `state`: `const { name = fallback, ...rest } = props()`; a page/layout's declared props are additive with its route-param shape. `children` is an ordinary declared prop (`const { children } = props<{ children: Snippet }>()`), not ambient |
 
 Bindings and directives (the attribute kinds `readAttributes` parses):
 
@@ -216,9 +221,15 @@ error):
 | `{#snippet name(args)}…{/snippet}` | Declares a reusable builder, called as an interpolation: `{name(args)}`; a snippet value passes through props like any other value |
 
 Components are capitalised tags (`<Panel prop={x}>…</Panel>`); nested content
-renders where the component calls `{children()}` — the single fill point
-(`{#if children}{children()}{:else}…{/if}` for a fallback; there are no named
-slots and no `<slot>` element). A layout's `{children()}` is the route outlet.
+becomes the component's `children` prop — an ordinary declared prop of type
+`Snippet`, read with `const { children } = props<{ children: Snippet }>()`
+and called as `{children()}` — the single fill point (`{#if children}
+{children()}{:else}…{/if}` for a fallback; there are no named slots and no
+`<slot>` element). Slotted content (`<Panel>…</Panel>`) and an explicit
+`children={aSnippet}` attribute set the same prop — slotted content rides in
+as the trailing prop layer, so it wins over an explicit `children` attribute
+on the same tag (`mergeProps`, last layer wins per key). A layout's
+`{children()}` is the route outlet.
 
 `<script>` and `<style>` are **not component-root-only**: either may sit
 inside a control-flow branch, scoped to that branch. A nested `<script>`
@@ -228,8 +239,9 @@ there — imports live in the leading `<script>`). A **root** `<style>` is
 component-scoped; a nested `<style>` scopes to its sibling subtree only.
 
 Removed forms throw migration errors at parse time: the `<slot>` element (use
-`{children()}`), `<template name>` snippets (use `{#snippet}`), and all
-`<template if/each/await/switch/…>` control flow (use `{#…}` blocks).
+a declared `children: Snippet` prop, called `{children()}`), `<template
+name>` snippets (use `{#snippet}`), and all `<template
+if/each/await/switch/…>` control flow (use `{#…}` blocks).
 
 ## Server surface — `abide/server/*`
 
@@ -320,7 +332,7 @@ Probes report, never act — reading one opens no fetch and no stream.
 
 ### Templating — `@documentation templating`
 
-- `@abide/abide/shared/snippet` — `snippet(payload)`: brands a snippet payload so a `{expr}` interpolation mounts it (client: a DOM builder; server: the rendered string); the compiler wraps `{#snippet}` bodies in this. Also exports the `Snippet<P>` type and `snippetPayload(value)` (the payload, or undefined for plain values).
+- `@abide/abide/shared/snippet` — `snippet(payload)`: brands a snippet payload so a `{expr}` interpolation mounts it (client: a DOM builder; server: the rendered string); the compiler wraps `{#snippet}` bodies in this. Also exports the `Snippet<Args>` type — a callable `(...args: Args) => SnippetValue`, generic over its call arguments (`children` is `Snippet`, invoked `children()`; a row snippet is `Snippet<[Item]>`, invoked `row(item)`) — plus `SnippetValue` (the internal payload brand) and `snippetPayload(value)` (a branded value's payload, or undefined for plain values).
 
 ### Shared plumbing — `@documentation plumbing`
 
@@ -332,6 +344,7 @@ Probes report, never act — reading one opens no fetch and no stream.
 
 - `@abide/abide/ui/state` — the `state` primitive: `state(initial, transform?)` writable cell, `state.computed(fn)` read-only derived, `state.linked(fn, transform?)` writable-reseeded, `state.share(key, value)` / `state.shared(key)` ambient context. In `.abide` files the compiler lowers reads/writes to plain variable syntax; in `.ts` the cell is read/written through `.value`.
 - `@abide/abide/ui/watch` — `watch(source, handler)`: the single reaction primitive over a thunk, cell, cell array, socket/stream, or rpc (see the grammar table). Client-only; the compiler strips author calls from SSR, and the `socket.watch` / `fn.watch` instance sugar is SSR-inert.
+- `@abide/abide/ui/props` — `props<T>()`: the prop reader, resolved by import binding (alias-safe) like `state`; a required import — there is no ambient `props()`. Destructure declared props off it (`const { name, ...rest } = props<T>()`); a page/layout's declared `T` is additive with its auto-typed route-param shape. `children` is an ordinary declared prop, not ambient: `const { children } = props<{ children: Snippet }>()` (`Snippet` from `@abide/abide/shared/snippet`).
 
 ### Templating — `@documentation templating`
 

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # abide
 
+## 0.49.0
+
+### Minor Changes
+
+- dfb4f13: props import required + additive route-shape type; drop ambient children ([`0dbe248`](https://github.com/briancray/abide/commit/0dbe248fc959f3ca8168fb83e6f30619a17eff3b))
+- dfb4f13: slotted content rides the children prop key as a Snippet ([`0de19e5`](https://github.com/briancray/abide/commit/0de19e594dabb6ddd92b08d5e473f13296f17247))
+- dfb4f13: publish abide/ui/props module for the props reader ([`197c1a9`](https://github.com/briancray/abide/commit/197c1a900c0ea81b40d1cbb4a6bec1e021b9e932))
+- dfb4f13: type element attach node param from the element tag ([`444ef35`](https://github.com/briancray/abide/commit/444ef356372f8fc39a0b5786bca2f70dcf750c53))
+- 951e90b: `props` is now a required import (`@abide/abide/ui/props`), resolved by import binding like `state` — a bare ambient `props()` no longer works, and every component that reads props must `import { props } from '@abide/abide/ui/props'`.
+
+    `children` is now an ordinary declared prop instead of an ambient callable: read it with `const { children } = props<{ children: Snippet }>()` (`Snippet` from `@abide/abide/shared/snippet`). Slotted content (`<Panel>…</Panel>`) and an explicit `children={aSnippet}` attribute now set the same `children` prop key (slotted content wins if both are present). `props<T>()` stays additive — a page/layout still gets its route-param shape auto-typed, and declaring `children` (or any other prop) only adds to it.
+
+    The `Snippet` type's generic changed from its internal payload to its call arguments: `Snippet<Args extends unknown[] = []>` is now `(...args: Args) => SnippetValue` — `children` is `Snippet` (invoked `children()`), a row/label snippet is `Snippet<[Item]>` (invoked `row(item)`). The former payload-generic form (`Snippet<Payload>` describing the value flowing through) is gone; the internal payload is the newly exported `SnippetValue`.
+
+    **Behavior change:** an unguarded `{children()}` on a component mounted without children now throws at render, where it previously rendered nothing. Guard with `{#if children}{children()}{:else}…{/if}`, or declare `children: Snippet` as a required (non-optional) prop so `abide check` catches missing children at the call site.
+
+    Migration: add `import { props } from '@abide/abide/ui/props'` to every component that calls `props()`; for any component that reads `children`, add `import type { Snippet } from '@abide/abide/shared/snippet'` and declare it — `const { children } = props<{ children: Snippet }>()` (or `children?: Snippet` if optional).
+
+### Patch Changes
+
+- 4a6bf93: mount a reactive/loop-bound component tag by its value, not the cell ([`32a7cb8`](https://github.com/briancray/abide/commit/32a7cb8bdef0800d76b418eefbe550b0a939cd73))
+- dfb4f13: correct UiProps.children to the ordinary prop-thunk shape ([`33a0de7`](https://github.com/briancray/abide/commit/33a0de72dc2fe6ce4a0e025e4158ab192e47f1f0))
+- c7d25e4: type state<T>(undefined) and binding-annotated state() as T | undefined ([`3c40d99`](https://github.com/briancray/abide/commit/3c40d9981617968330a00bc2f034456b80365419))
+- c7d25e4: await a snippet whose body fills a {children()} slot ([`4c2744b`](https://github.com/briancray/abide/commit/4c2744bc1aa42728a80adb3426a77c02c79b30d4))
+- dfb4f13: repair pre-existing gate failures blocking release ([`4c55a4a`](https://github.com/briancray/abide/commit/4c55a4a1cbcb0b2afc842f7cc7134aed590006ce))
+- dfb4f13: layout child sentinel + restProps skip move to the children key ([`500d1d8`](https://github.com/briancray/abide/commit/500d1d8d696147602eb1ce34706cbbbf724ceb0b))
+- dfb4f13: fix stale props-declaration comment in compileShadow ([`532e079`](https://github.com/briancray/abide/commit/532e0796c54aa77c7b155145ae2d16193b7de4e5))
+- c7d25e4: expand a thrown Bun.build AggregateError into per-file diagnostics ([`5643d95`](https://github.com/briancray/abide/commit/5643d95691dd9211bc5f3edb5a2ae77aa3989f63))
+- dfb4f13: children lowers as a destructured prop, not $children ([`60bbbeb`](https://github.com/briancray/abide/commit/60bbbeb15cae41d34e5f5b4f07590bf0a5a1b795))
+- dfb4f13: resolve 35 correctness/ergonomics findings from full-tree audit ([`73a72ac`](https://github.com/briancray/abide/commit/73a72ac1946f901f76d790b38fa3ebbf29b661fe))
+- dfb4f13: extract buildArtifact (build-or-die primitive) ([`938e312`](https://github.com/briancray/abide/commit/938e3129f03cb6787624703422cd9472fbdcb83b))
+- dfb4f13: format spreadProps + renderChain to canonical prettier ([`97b1565`](https://github.com/briancray/abide/commit/97b1565670eb0977b8079425f8e92becd6deb68e))
+- dfb4f13: thunk-wrap layout children sentinel so {#if children} presence reads truthy ([`a884de1`](https://github.com/briancray/abide/commit/a884de1bbb0fcffaea91268cf49aa1d1b24a3d7a))
+- 4a6bf93: drop an await settle whose anchor was detached from the tree ([`ad3d00c`](https://github.com/briancray/abide/commit/ad3d00c36ecfd935721164e7ebff7a7b3fffca4e))
+- dfb4f13: resolve props by import binding, not ambient special-case ([`b624893`](https://github.com/briancray/abide/commit/b624893745aa0e1fdb407047b15f29ac0ceac3ec))
+- dfb4f13: shadow declares props under the author's local alias ([`b821a5b`](https://github.com/briancray/abide/commit/b821a5bfef17233b2aa24502ea397eede62329a0))
+- dfb4f13: extract withoutHydration (5 sites -> 1 helper) ([`c36be09`](https://github.com/briancray/abide/commit/c36be09d64846f76216bfcc7932cdbc026631f04))
+- dfb4f13: redefine Snippet<Args> as a callable; add SnippetValue ([`ecc861f`](https://github.com/briancray/abide/commit/ecc861f589d5149a299b92ba6d08fd362644bcd1))
+
+## 0.48.0
+
+### Minor Changes
+
+- 182cdf5: server reads coalesce-only by default, SWR retain client-only ([`98a3e84`](https://github.com/briancray/abide/commit/98a3e84b1e6bdb50b8950a4197ec4a255c560d2a))
+- 182cdf5: warn on a request-scoped ttl>0 read (add shared or drop ttl) ([`b55425c`](https://github.com/briancray/abide/commit/b55425c986fb4c7cebcb1e8c29d1c616466d7d63))
+
+### Patch Changes
+
+- 182cdf5: rename global option/exports/comments to shared ([`1256934`](https://github.com/briancray/abide/commit/125693481ba23152a44375bbe200d575b66fdf9a))
+- 182cdf5: evict outside-request coalesce-only entries; correct shared help copy ([`1b73e21`](https://github.com/briancray/abide/commit/1b73e21c33c8ee985f7109fdedcbe302322ce7d1))
+- 182cdf5: route outside-a-request server reads to the shared store ([`456cfa6`](https://github.com/briancray/abide/commit/456cfa662405714df99545e02ed6e3b851da84df))
+- 182cdf5: Breaking: the `global` cache option is renamed `shared`, and it no longer implies retention. `{ global: true }` (memoise across requests forever) becomes `{ shared: true, ttl: Infinity }` — `shared` now only selects the process store, while `ttl` alone controls retention (default `0` on the server = coalesce-only, `Infinity` on the client). Reads made with no request in flight resolve to the shared store instead of an orphan fallback. ([`d94f0f9`](https://github.com/briancray/abide/commit/d94f0f9cb15a5822b2d5824db7e32da27368fe04))
+
 ## 0.47.0
 
 ### Minor Changes

package/README.md

@@ -130,11 +130,16 @@ component you read and write state as plain variables. The same file renders on
 the server — blocking awaits inline, streaming awaits out of order, cached
 reads seeded warm — and hydrates in the browser.
 
-A child component renders whatever you nest in it at `{children()}`:
+Nested content becomes the component's `children` prop — an ordinary declared
+prop of type `Snippet` — and renders wherever the component calls
+`{children()}`:
 
 ```html
 <script>
-    const { title } = props()
+    import { props } from '@abide/abide/ui/props'
+    import type { Snippet } from '@abide/abide/shared/snippet'
+
+    const { title, children } = props<{ title: string; children?: Snippet }>()
 </script>
 
 <section>
@@ -160,9 +165,10 @@ template grammar:
     import { state } from '@abide/abide/ui/state'
     import { watch } from '@abide/abide/ui/watch'
     import { html } from '@abide/abide/ui/html'
+    import { props } from '@abide/abide/ui/props'
     import Panel from '$ui/components/Panel.abide'
 
-    const { room = 'lobby' } = props()
+    const { room = 'lobby' } = props<{ room?: string }>()
 
     let draft = state('')
     let author = state('anon')

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.47.0",
+    "version": "0.49.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
@@ -77,6 +77,7 @@
         "./shared/createSubscriber": "./src/lib/shared/createSubscriber.ts",
         "./ui/html": "./src/lib/ui/html.ts",
         "./ui/state": "./src/lib/ui/state.ts",
+        "./ui/props": "./src/lib/ui/props.ts",
         "./ui/effect": "./src/lib/ui/effect.ts",
         "./ui/currentScope": "./src/lib/ui/scope.ts",
         "./ui/enterRenderScope": "./src/lib/ui/enterScope.ts",
@@ -89,6 +90,7 @@
         "./ui/dom/restProps": "./src/lib/ui/dom/restProps.ts",
         "./ui/dom/spreadAttrs": "./src/lib/ui/dom/spreadAttrs.ts",
         "./ui/dom/readCall": "./src/lib/ui/dom/readCall.ts",
+        "./ui/dom/mutateDocArray": "./src/lib/ui/dom/mutateDocArray.ts",
         "./ui/dom/hydrate": "./src/lib/ui/dom/hydrate.ts",
         "./ui/dom/text": "./src/lib/ui/dom/text.ts",
         "./ui/dom/appendText": "./src/lib/ui/dom/appendText.ts",

package/src/buildCli.ts

@@ -2,9 +2,9 @@ import { dirname, join } from 'node:path'
 import { build } from './build.ts'
 import { compile } from './compile.ts'
 import { abideLog } from './lib/shared/abideLog.ts'
+import { buildArtifact } from './lib/shared/buildArtifact.ts'
 import { detectTarget } from './lib/shared/detectTarget.ts'
 import { exeSuffix } from './lib/shared/exeSuffix.ts'
-import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
 import { programNameForPackage } from './lib/shared/programNameForPackage.ts'
 import { readPackageJson } from './lib/shared/readPackageJson.ts'
 import type { CompileTarget } from './lib/shared/types/CompileTarget.ts'
@@ -56,14 +56,13 @@ export async function buildCli({
     stdout. We don't `bun build --compile` here because the discovery output is
     throwaway; a plain JS bundle runs faster. Additive — does not clear dist.
     */
-    const discoveryResult = await Bun.build({
+    await buildArtifact({
         entrypoints: [DISCOVERY_ENTRY],
         target: 'bun',
         outdir: distDir,
         naming: '_discovery.js',
         plugins,
     })
-    exitOnBuildFailure(discoveryResult)
 
     const proc = Bun.spawn({
         cmd: ['bun', discoveryOut],
@@ -94,13 +93,12 @@ export async function buildCli({
     async function buildTargetPair(platformTarget: CompileTarget, cliOut: string): Promise<string> {
         const serverOut = join(dirname(cliOut), `server${exeSuffix(platformTarget)}`)
         await compile({ cwd, target: platformTarget, outfile: serverOut, buildClient: false })
-        const result = await Bun.build({
+        await buildArtifact({
             entrypoints: [CLI_ENTRY],
             target: 'bun',
             compile: { target: platformTarget, outfile: cliOut },
             plugins,
         })
-        exitOnBuildFailure(result)
         abideLog.success(`compiled cli + server: ${cliOut}`)
         return cliOut
     }

package/src/buildDisconnected.ts

@@ -1,6 +1,6 @@
 import { clientBuildPlugins } from './clientBuildPlugins.ts'
 import { abideLog } from './lib/shared/abideLog.ts'
-import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
+import { buildArtifact } from './lib/shared/buildArtifact.ts'
 
 const ENTRY = new URL('./bundleDisconnectedEntry.ts', import.meta.url).pathname
 const CSS_ENTRY = new URL('./lib/bundle/disconnected.css', import.meta.url).pathname
@@ -47,7 +47,7 @@ export async function buildDisconnected({
     the entry (which TS can't type), so it compiles to a standalone artifact we
     inline alongside the JS — the component carries no <style> of its own.
     */
-    const result = await Bun.build({
+    const result = await buildArtifact({
         entrypoints: [ENTRY, CSS_ENTRY],
         target: 'browser',
         minify: true,
@@ -55,7 +55,6 @@ export async function buildDisconnected({
         define: { __ABIDE_DEV__: 'false' },
         plugins,
     })
-    exitOnBuildFailure(result)
 
     // Collect the JS bundle + extracted CSS from the in-memory artifacts.
     let js = ''

package/src/bundleApp.ts

@@ -8,9 +8,9 @@ import { serverBinaryFilename } from './lib/bundle/serverBinaryFilename.ts'
 import { signMacApp } from './lib/bundle/signMacApp.ts'
 import { webviewLibName } from './lib/bundle/webviewLibName.ts'
 import { abideLog } from './lib/shared/abideLog.ts'
+import { buildArtifact } from './lib/shared/buildArtifact.ts'
 import { bundleLayout } from './lib/shared/bundleLayout.ts'
 import { detectTarget } from './lib/shared/detectTarget.ts'
-import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
 import { programNameForPackage } from './lib/shared/programNameForPackage.ts'
 import { readPackageJson } from './lib/shared/readPackageJson.ts'
 import { serverBuildPlugins } from './serverBuildPlugins.ts'
@@ -82,7 +82,7 @@ export async function bundleApp({ cwd = process.cwd() }: { cwd?: string } = {}):
     // 3. Launcher binary — named after the program so CFBundleExecutable matches.
     const launcherSuffix = target.includes('windows') ? '.exe' : ''
     const launcherPath = `${binDir}/${programName}${launcherSuffix}`
-    const launcherResult = await Bun.build({
+    await buildArtifact({
         entrypoints: [APP_ENTRY],
         target: 'bun',
         compile: { target, outfile: launcherPath },
@@ -96,7 +96,6 @@ export async function bundleApp({ cwd = process.cwd() }: { cwd?: string } = {}):
         */
         define: { __ABIDE_WORKER_ENTRY__: JSON.stringify(WORKER_ENTRY) },
     })
-    exitOnBuildFailure(launcherResult)
 
     // 4. Webview lib — built from the vendored source if needed, then copied
     // beside the binaries (or into Frameworks on macOS) so the bundle is self-contained.

package/src/compile.ts

@@ -1,8 +1,8 @@
 import { build } from './build.ts'
 import { abideLog } from './lib/shared/abideLog.ts'
+import { buildArtifact } from './lib/shared/buildArtifact.ts'
 import { detectTarget } from './lib/shared/detectTarget.ts'
 import { exeSuffix } from './lib/shared/exeSuffix.ts'
-import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
 import type { CompileTarget } from './lib/shared/types/CompileTarget.ts'
 import { serverBuildPlugins } from './serverBuildPlugins.ts'
 
@@ -40,7 +40,7 @@ export async function compile({
 
     const outPath = outfile ?? `${cwd}/dist/app${exeSuffix(target)}`
 
-    const result = await Bun.build({
+    await buildArtifact({
         entrypoints: [SERVER_ENTRY],
         target: 'bun',
         format: 'esm',
@@ -56,8 +56,6 @@ export async function compile({
         plugins: serverBuildPlugins({ cwd, embedAssets: true }),
     })
 
-    exitOnBuildFailure(result)
-
     abideLog.success(`compiled standalone binary: ${outPath} (target: ${target})`)
     return outPath
 }

package/src/lib/bundle/installDownloads.ts

@@ -16,9 +16,19 @@ export function installDownloads(libPath: string, webviewHandle: Pointer | null)
     if (process.platform !== 'darwin') {
         return
     }
-    const { symbols, close } = dlopen(libPath, {
-        abide_install_downloads: { args: [FFIType.ptr], returns: FFIType.void },
-    })
+    /* abide_install_downloads exists only in abide's own webview lib. A vanilla
+       ABIDE_WEBVIEW_LIB on darwin lacks it, so dlopen throws — degrade to a no-op
+       (downloads simply unhandled) instead of crashing the launcher, matching the
+       optional-symbol FFI binders. */
+    let symbols: { abide_install_downloads: (handle: Pointer | null) => void }
+    let close: () => void
+    try {
+        ;({ symbols, close } = dlopen(libPath, {
+            abide_install_downloads: { args: [FFIType.ptr], returns: FFIType.void },
+        }))
+    } catch {
+        return
+    }
     symbols.abide_install_downloads(webviewHandle)
     close()
 }

package/src/lib/bundle/installMacMenu.ts

@@ -30,9 +30,19 @@ export function installMacMenu(
     if (process.platform !== 'darwin') {
         return
     }
-    const { symbols, close } = dlopen(libPath, {
-        abide_install_app_menu: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
-    })
+    /* The abide_install_app_menu symbol is compiled only into abide's own webview lib.
+       A user who points ABIDE_WEBVIEW_LIB at a vanilla webview.dylib is on darwin but
+       lacks the symbol, so dlopen throws — degrade to a no-op (native menu simply absent)
+       rather than crashing the launcher, matching bindConnectedFlag/bindRequestNavigate. */
+    let symbols: { abide_install_app_menu: (handle: Pointer | null, config: Uint8Array) => void }
+    let close: () => void
+    try {
+        ;({ symbols, close } = dlopen(libPath, {
+            abide_install_app_menu: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+        }))
+    } catch {
+        return
+    }
     const config = JSON.stringify({ appName, fileMenu, menu })
     symbols.abide_install_app_menu(webviewHandle, new TextEncoder().encode(`${config}\0`))
     close()

package/src/lib/cli/parseArgvForRpc.ts

@@ -74,8 +74,36 @@ export async function parseArgvForRpc(
         }
         const name = token.name
         const propType = properties[name]?.type
+        /* Coerce one string token to a schema scalar type (or throw). Shared by scalar
+           props and array ELEMENTS so `--tags 1 --tags 2` on `z.array(z.number())` yields
+           numbers, not strings the server then rejects. */
+        const coerceScalar = (raw: string, type: string | undefined): unknown => {
+            if (type === 'number' || type === 'integer') {
+                // Reject a blank value explicitly — `Number('')` / `Number('  ')` is 0,
+                // not NaN, so the NaN guard alone would silently coerce it to zero.
+                const n = raw.trim() === '' ? Number.NaN : Number(raw)
+                if (Number.isNaN(n)) {
+                    throw new Error(`--${name} expects a number, got ${raw}`)
+                }
+                return n
+            }
+            if (type === 'boolean') {
+                const lowered = raw.trim().toLowerCase()
+                if (lowered === 'true' || lowered === '1') {
+                    return true
+                }
+                if (lowered === 'false' || lowered === '0') {
+                    return false
+                }
+                throw new Error(`--${name} expects true or false, got ${raw}`)
+            }
+            return raw
+        }
         if (propType === 'boolean') {
-            args[name] = !token.negated
+            /* Bare `--flag` / `--no-flag` toggles; inline `--flag=false` honours the RHS
+               instead of always resolving to true. */
+            args[name] =
+                token.value !== undefined ? coerceScalar(token.value, 'boolean') : !token.negated
             continue
         }
         if (token.missingValue || token.value === undefined) {
@@ -83,18 +111,17 @@ export async function parseArgvForRpc(
         }
         const value = token.value
         if (propType === 'number' || propType === 'integer') {
-            // Reject a blank value explicitly — `Number('')` / `Number('  ')` is 0,
-            // not NaN, so the NaN guard alone would silently coerce it to zero.
-            const n = value.trim() === '' ? Number.NaN : Number(value)
-            if (Number.isNaN(n)) {
-                throw new Error(`--${name} expects a number, got ${value}`)
-            }
-            args[name] = n
+            args[name] = coerceScalar(value, propType)
             continue
         }
         if (propType === 'array') {
+            /* Coerce each repeated element per the schema's `items.type` — a string-only
+               array arg silently fails server-side Zod validation for numeric/boolean items. */
+            const itemType = (properties[name] as { items?: { type?: string } } | undefined)?.items
+                ?.type
+            const element = coerceScalar(value, itemType)
             const existing = args[name]
-            args[name] = Array.isArray(existing) ? [...existing, value] : [value]
+            args[name] = Array.isArray(existing) ? [...existing, element] : [element]
             continue
         }
         args[name] = value

package/src/lib/cli/tokenizeArgvFlags.ts

@@ -64,9 +64,11 @@ export function* tokenizeArgvFlags(
             : undefined
         const negated = negatedName !== undefined && properties[negatedName]?.type === 'boolean'
         const name = negated ? (negatedName as string) : literalName
-        // Boolean props and inline `--name=value` consume no following token.
+        // Boolean props and inline `--name=value` consume no following token. Pass any
+        // inline value through (`--flag=false`) so the parser can honour the RHS instead
+        // of the boolean always resolving to true.
         if (properties[name]?.type === 'boolean') {
-            yield { name, negated }
+            yield { name, negated, value: inlineValue }
             continue
         }
         if (inlineValue !== undefined) {

package/src/lib/mcp/createMcpResourceServer.ts

@@ -1,5 +1,6 @@
 // node:fs existsSync — cheap sync presence check, mirrors createPublicAssetServer
 import { existsSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
 import { Glob } from 'bun'
 import { mimeForExtension } from '../server/runtime/mimeForExtension.ts'
 import type { Assets } from '../server/runtime/types/Assets.ts'
@@ -81,8 +82,10 @@ export function createMcpResourceServer({
                 return undefined
             }
             const relativePath = uri.slice(URI_PREFIX.length)
-            // reject `..` traversal in the requested uri before any disk read
-            if (relativePath.split('/').includes('..')) {
+            // reject `..` traversal on EITHER separator — a backslash-joined `..\` escapes
+            // resourcesDir on Windows (its OS layer treats `\` as a separator regardless of
+            // how the JS string was built), so a `/`-only split lets it through.
+            if (relativePath.split(/[\\/]/).includes('..')) {
                 return undefined
             }
             if (mcpResources) {
@@ -92,6 +95,14 @@ export function createMcpResourceServer({
                 }
                 return contentsFor(relativePath, Bun.gunzipSync(compressed))
             }
+            // Belt-and-braces for the on-disk branch: resolve the target and confirm it
+            // stays inside resourcesDir, catching any traversal the segment check missed
+            // (absolute paths, platform separator quirks).
+            const root = resolve(resourcesDir)
+            const target = resolve(root, relativePath)
+            if (target !== root && !target.startsWith(root + sep)) {
+                return undefined
+            }
             const file = Bun.file(`${resourcesDir}/${relativePath}`)
             if (!(await file.exists())) {
                 return undefined

package/src/lib/mcp/toolResultFromResponse.ts

@@ -4,6 +4,12 @@ import { messageFromError } from '../shared/messageFromError.ts'
 import { responseErrorText } from '../shared/responseErrorText.ts'
 import { streamResponse } from '../shared/streamResponse.ts'
 
+/* MCP `tools/call` is request/response, not a streaming transport, so a genuinely live
+   stream must be bounded: return what arrived within these limits (with a truncation note)
+   rather than buffering forever and never answering. */
+const MAX_STREAM_FRAMES = 1000
+const STREAM_TOOL_TIMEOUT_MS = 30_000
+
 // Frames a value as MCP text content — strings verbatim, everything else as JSON.
 // An undefined body (204 / empty) becomes '' — `JSON.stringify(undefined)` is the
 // value `undefined`, not a string, which would make an invalid text content block.
@@ -38,26 +44,48 @@ export async function toolResultFromResponse(response: Response): Promise<Record
 
     if (isStreamingResponse(response)) {
         const frames: unknown[] = []
+        // Set when WE stop the stream (cap/timeout), so the iterator's resulting end/throw
+        // reads as truncation, not a stream error.
+        let truncated: string | undefined
+        const timer = setTimeout(() => {
+            truncated = `stream truncated after ${STREAM_TOOL_TIMEOUT_MS}ms — MCP tools/call is request/response, not a live stream`
+            void response.body?.cancel()
+        }, STREAM_TOOL_TIMEOUT_MS)
         try {
             for await (const frame of streamResponse(response)) {
                 frames.push(frame)
+                if (frames.length >= MAX_STREAM_FRAMES) {
+                    truncated = `stream truncated at ${MAX_STREAM_FRAMES} frames`
+                    void response.body?.cancel()
+                    break
+                }
             }
         } catch (error) {
-            return {
-                content: [
-                    { type: 'text', text: frames.map(asText).join('\n') },
-                    {
-                        type: 'text',
-                        text: `stream error: ${messageFromError(error)}`,
-                    },
-                ],
-                structuredContent: { frames },
-                isError: true,
+            /* A real mid-stream error (we didn't cancel) surfaces as isError; a throw caused
+               by our own cancel falls through to the truncated result below. */
+            if (truncated === undefined) {
+                clearTimeout(timer)
+                return {
+                    content: [
+                        { type: 'text', text: frames.map(asText).join('\n') },
+                        { type: 'text', text: `stream error: ${messageFromError(error)}` },
+                    ],
+                    structuredContent: { frames },
+                    isError: true,
+                }
             }
+        } finally {
+            clearTimeout(timer)
+        }
+        const content: { type: 'text'; text: string }[] = [
+            { type: 'text', text: frames.map(asText).join('\n') },
+        ]
+        if (truncated !== undefined) {
+            content.push({ type: 'text', text: truncated })
         }
         return {
-            content: [{ type: 'text', text: frames.map(asText).join('\n') }],
-            structuredContent: { frames },
+            content,
+            structuredContent: truncated === undefined ? { frames } : { frames, truncated },
         }
     }
 

package/src/lib/server/rpc/parseArgs.ts

@@ -137,7 +137,21 @@ export async function parseArgs(
     needs the schema threaded in here (or a coercing schema adapter at the rpc).
     */
     const bodyObject = (body ?? {}) as Record<string, unknown>
-    const merged = { ...Object.fromEntries(url.searchParams), ...bodyObject }
+    /* Collect the query into an object, arraying repeated keys (`?tag=a&tag=b` → `['a','b']`)
+       rather than letting `Object.fromEntries` silently keep only the last — mirrors
+       splitFormData, so a repeated field reaches the schema as an array, not a dropped value. */
+    const queryObject: Record<string, unknown> = {}
+    for (const [key, value] of url.searchParams) {
+        const existing = queryObject[key]
+        if (!(key in queryObject)) {
+            queryObject[key] = value
+        } else if (Array.isArray(existing)) {
+            existing.push(value)
+        } else {
+            queryObject[key] = [existing, value]
+        }
+    }
+    const merged = { ...queryObject, ...bodyObject }
     if (Object.keys(merged).length === 0) {
         return undefined
     }

package/src/lib/server/rpc/runWithRpcTimeout.ts

@@ -1,3 +1,4 @@
+import { abideLog } from '../../shared/abideLog.ts'
 import { error } from '../error.ts'
 
 /*
@@ -39,7 +40,17 @@ export function runWithRpcTimeout(
                     (late) => {
                         void late.body?.cancel()
                     },
-                    () => {},
+                    (rejection) => {
+                        /* The handler outlived its timeout and then rejected. A cooperative
+                           abort (it honoured the composed signal) is expected and stays quiet;
+                           any other error is a genuine handler bug and would otherwise leave
+                           zero server-side trace behind the client's 504 — log it. */
+                        const aborted =
+                            (rejection as { name?: string } | undefined)?.name === 'AbortError'
+                        if (!aborted) {
+                            abideLog.error(rejection)
+                        }
+                    },
                 )
             }
         }