Fix Kiira docs snippet issues (#4526)

## Summary
- fix TypeScript client README snippets so they pass Kiira
- export FetchBackoffAbortError from @electric-sql/client to match
documented API
- add Kiira grouping metadata and fix high-signal docs snippets in sync
docs

## Verification
- npx kiira check --entry packages/typescript-client/README.md --static
--raw
- cd packages/typescript-client && pnpm exec tsc -p tsconfig.build.json

Note: package-level `pnpm --filter @electric-sql/client typecheck`
currently fails in this fresh worktree on existing test/dependency
typing issues (uuid/pg/fast-check declarations and Vitest mock typings),
unrelated to this change.

Author: KyleAMathews

.changeset/curly-pears-smell.md

@@ -0,0 +1,5 @@
+---
+"@electric-sql/client": patch
+---
+
+Export `FetchBackoffAbortError` from the package entrypoint to match the documented error handling API.

packages/typescript-client/README.md

@@ -48,6 +48,8 @@ The client exports a `ShapeStream` class for getting updates to shapes on a row-
 ```tsx
 import { ShapeStream } from '@electric-sql/client'
 
+const BASE_URL = 'http://localhost:3000'
+
 // Passes subscribers rows as they're inserted, updated, or deleted
 const stream = new ShapeStream({
   url: `${BASE_URL}/v1/shape`,
@@ -80,11 +82,13 @@ stream.subscribe((messages) => {
 ```tsx
 import { ShapeStream, Shape } from '@electric-sql/client'
 
+const BASE_URL = 'http://localhost:3000'
+
 const stream = new ShapeStream({
   url: `${BASE_URL}/v1/shape`,
   params: {
-    table: `foo`
-  }
+    table: `foo`,
+  },
 })
 const shape = new Shape(stream)
 
@@ -94,7 +98,7 @@ await shape.rows
 // passes subscribers shape data when the shape updates
 shape.subscribe(({ rows }) => {
   // rows is an array of the latest value of each row in a shape.
-}
+})
 ```
 
 ### Error Handling
@@ -105,7 +109,13 @@ The ShapeStream provides robust error handling with automatic retry support:
 
 The `onError` handler gives you full control over error recovery:
 
-```typescript
+```typescript group=readme
+import { ShapeStream, FetchError } from '@electric-sql/client'
+
+const BASE_URL = 'http://localhost:3000'
+const getRefreshedToken = () => 'refreshed-token'
+const fallbackUserId = 'fallback-user-id'
+
 const stream = new ShapeStream({
   url: `${BASE_URL}/v1/shape`,
   params: { table: `foo` },
@@ -158,15 +168,22 @@ const stream = new ShapeStream({
 The handler supports async operations:
 
 ```typescript
-onError: async (error) => {
-  if (error instanceof FetchError && error.status === 401) {
-    // Perform async token refresh
-    const newToken = await refreshAuthToken()
-    return {
-      headers: { Authorization: `Bearer ${newToken}` },
+import { FetchError } from '@electric-sql/client'
+
+const refreshAuthToken = async () => 'refreshed-token'
+
+const options = {
+  onError: async (error: Error) => {
+    if (error instanceof FetchError && error.status === 401) {
+      // Perform async token refresh
+      const newToken = await refreshAuthToken()
+      return {
+        headers: { Authorization: `Bearer ${newToken}` },
+      }
     }
-  }
-  return {} // Retry other errors
+
+    return {} // Retry other errors
+  },
 }
 ```
 
@@ -178,7 +195,7 @@ onError: async (error) => {
 
 Individual subscribers can handle errors specific to their subscription:
 
-```typescript
+```typescript group=readme
 stream.subscribe(
   (messages) => {
     // Handle messages

packages/typescript-client/src/index.ts

@@ -6,7 +6,7 @@ export {
   isControlMessage,
   isVisibleInSnapshot,
 } from './helpers'
-export { FetchError } from './error'
+export { FetchError, FetchBackoffAbortError } from './error'
 export { type BackoffOptions, BackoffDefaults } from './fetch'
 export { ELECTRIC_PROTOCOL_QUERY_PARAMS } from './constants'
 export {

website/docs/sync/api/clients/typescript.md

@@ -623,7 +623,7 @@ The `subscribe` method allows you to receive updates whenever the shape changes.
 1. A message handler callback (required)
 2. An error handler callback (optional)
 
-```typescript
+```typescript group=typescript-1
 const stream = new ShapeStream({
   url: 'http://localhost:3000/v1/shape',
   params: {
@@ -651,7 +651,7 @@ To stop receiving updates, you can either:
 - Unsubscribe a specific subscription using the function returned by `subscribe`
 - Unsubscribe all subscriptions using `unsubscribeAll()`
 
-```typescript
+```typescript group=typescript-1
 // Store the unsubscribe function
 const unsubscribe = stream.subscribe((messages) => {
   console.log('Received messages:', messages)
@@ -673,15 +673,17 @@ The ShapeStream provides robust error handling with automatic retry support thro
 The `onError` option provides powerful error recovery with automatic retry support:
 
 ```typescript
-onError?: ShapeStreamErrorHandler
+type RetryOpts = {
+  params?: Record<string, string | string[]>
+  headers?: Record<string, string>
+}
 
 type ShapeStreamErrorHandler = (
   error: Error
 ) => void | RetryOpts | Promise<void | RetryOpts>
 
-type RetryOpts = {
-  params?: ParamsRecord
-  headers?: Record<string, string>
+interface ShapeStreamOptions {
+  onError?: ShapeStreamErrorHandler
 }
 ```
 
@@ -941,7 +943,7 @@ GET requests (the default) with subset parameters in the URL can fail with `414
 
 To avoid this, use POST requests by setting `subsetMethod: 'POST'` on the stream:
 
-```typescript
+```typescript group=typescript-2
 const stream = new ShapeStream({
   url: 'http://localhost:3000/v1/shape',
   params: { table: 'items' },
@@ -952,7 +954,7 @@ const stream = new ShapeStream({
 
 Or override per-request with `method: 'POST'`:
 
-```typescript
+```typescript group=typescript-2
 const { metadata, data } = await stream.requestSnapshot({
   where: "status = 'active'",
   method: 'POST', // Use POST body instead of query parameters
@@ -980,15 +982,15 @@ The snapshot data is automatically injected into the subscribed message stream w
 
 A `snapshot-end` control message is added after the snapshot data to mark its boundary:
 
-```typescript
+```json
 {
-  headers: {
-    control: "snapshot-end",
-    xmin: "1234",
-    xmax: "1240",
-    xip_list: ["1235", "1237"],
-    snapshot_mark: 42,
-    database_lsn: "0/12345678"
+  "headers": {
+    "control": "snapshot-end",
+    "xmin": "1234",
+    "xmax": "1240",
+    "xip_list": ["1235", "1237"],
+    "snapshot_mark": 42,
+    "database_lsn": "0/12345678"
   }
 }
 ```

website/docs/sync/guides/shapes.md

@@ -127,13 +127,14 @@ Electric has preview support for subqueries in where clauses, allowing you to fi
 
 For example, you can sync only users who belong to a specific organization:
 
-```ts
+```ts group=shapes-1
 import { electricCollectionOptions } from '@tanstack/electric-db-collection'
 import { createCollection } from '@tanstack/react-db'
 
 const usersCollection = createCollection(
   electricCollectionOptions({
     id: 'org-users',
+    getKey: (row: { id: string }) => row.id,
     shapeOptions: {
       url: 'http://localhost:3000/v1/shape',
       params: {
@@ -148,10 +149,11 @@ const usersCollection = createCollection(
 
 Or combine subqueries with boolean logic to express more realistic access rules:
 
-```ts
+```ts group=shapes-1
 const documentsCollection = createCollection(
   electricCollectionOptions({
     id: 'visible-documents',
+    getKey: (row: { id: string }) => row.id,
     shapeOptions: {
       url: 'http://localhost:3000/v1/shape',
       params: {
@@ -298,7 +300,7 @@ npm i @electric-sql/client
 
 Instantiate a `ShapeStream` and materialise into a `Shape`:
 
-```ts
+```ts group=shapes-2
 import { ShapeStream, Shape } from '@electric-sql/client'
 
 const stream = new ShapeStream({
@@ -315,7 +317,7 @@ await shape.rows
 
 You can register a callback to be notified whenever the shape data changes:
 
-```ts
+```ts group=shapes-2
 shape.subscribe(({ rows }) => {
   // rows is an array of the latest value of each row in a shape.
 })
@@ -329,13 +331,14 @@ See the [Quickstart](/docs/sync/quickstart) and [HTTP API](/docs/sync/api/http)
 
 Or with [TanStack DB](/sync/tanstack-db), you can sync shapes into collections:
 
-```ts
+```ts group=shapes-3
 import { electricCollectionOptions } from '@tanstack/electric-db-collection'
 import { createCollection } from '@tanstack/react-db'
 
 const todosCollection = createCollection(
   electricCollectionOptions({
     id: 'todos',
+    getKey: (row: { id: string }) => row.id,
     shapeOptions: {
       url: 'http://localhost:3000/v1/shape',
       params: {
@@ -348,7 +351,7 @@ const todosCollection = createCollection(
 
 Then query your collections with live queries:
 
-```tsx
+```tsx group=shapes-3
 import { useLiveQuery, eq } from '@tanstack/react-db'
 
 const Todos = () => {
@@ -428,13 +431,14 @@ See the [TypeScript client docs](/docs/sync/api/clients/typescript#requesting-su
 
 Or with [TanStack DB](/sync/tanstack-db), you can use [query-driven sync](https://tanstack.com/blog/tanstack-db-0.5-query-driven-sync) where your live queries define what data to sync:
 
-```ts
+```ts group=shapes-4
 import { electricCollectionOptions } from '@tanstack/electric-db-collection'
 import { createCollection } from '@tanstack/react-db'
 
 const itemsCollection = createCollection(
   electricCollectionOptions({
     id: 'items',
+    getKey: (row: { id: string }) => row.id,
     shapeOptions: {
       url: 'http://localhost:3000/v1/shape',
       params: {
@@ -448,7 +452,7 @@ const itemsCollection = createCollection(
 
 Then query data progressively with live queries:
 
-```tsx
+```tsx group=shapes-4
 import { useLiveQuery, eq } from '@tanstack/react-db'
 
 const ItemsList = ({ priority }: { priority: string }) => {

website/docs/sync/guides/sharding.md

@@ -195,7 +195,7 @@ This works well when:
 
 For more control, route requests through a proxy that determines the shard server-side. This hides sharding complexity from clients.
 
-```typescript
+```typescript group=sharding
 // proxy/server.ts
 import express from 'express'
 
@@ -409,7 +409,7 @@ function getShardId(userId: string): number {
 
 Sharding works naturally with Electric's [auth patterns](/docs/sync/guides/auth). Your proxy can handle both shard routing and authorization:
 
-```typescript
+```typescript group=sharding
 app.get('/v1/shape', async (req, res) => {
   // 1. Authenticate
   const user = await validateToken(req.headers.authorization)
@@ -445,7 +445,7 @@ app.get('/v1/shape', async (req, res) => {
 
 Monitor all Electric instances for a complete view of your sharded deployment:
 
-```typescript
+```typescript group=sharding
 // Health check aggregator
 async function checkAllShards(): Promise<ShardHealth[]> {
   const checks = Object.entries(SHARD_URLS).map(async ([shardId, url]) => {

website/docs/sync/integrations/react.md

@@ -65,7 +65,7 @@ const MyComponent = () => {
 
 For development, you can connect directly to Electric:
 
-```tsx
+```tsx group=react
 // ⚠️ Development only - exposes database structure
 import { useShape } from '@electric-sql/react'
 
@@ -93,7 +93,7 @@ const MyComponent = () => {
 
 You can also include additional PostgreSQL-specific parameters:
 
-```tsx
+```tsx group=react
 const MyFilteredComponent = () => {
   const { isLoading, data } = useShape<{ id: number; title: string }>({
     url: `http://localhost:3000/v1/shape`,

website/docs/sync/stacks.md

@@ -360,7 +360,7 @@ Having a Postgres database is as simple as:
 npm install @electric-sql/pglite
 ```
 
-```ts
+```ts group=stacks
 import { PGlite } from '@electric-sql/pglite'
 
 const db = new PGlite()
@@ -376,7 +376,7 @@ PGlite is a Postgres database that runs inside your dev environment. With it, yo
 
 Electric can be used to hydrate data into a PGlite instance using the [sync plugin](https://pglite.dev/docs/sync):
 
-```ts
+```ts group=stacks
 import { electricSync } from '@electric-sql/pglite-sync'
 
 const pg = await PGlite.create({