create-sia-app 0.1.11 → 0.1.13

package/dist/index.js

@@ -54,7 +54,7 @@ async function runPrompts() {
   }
   const indexerUrl = await p.text({
     message: "Indexer URL",
-    initialValue: "https://app.sia.storage"
+    initialValue: "https://sia.storage"
   });
   if (p.isCancel(indexerUrl)) {
     p.cancel("Cancelled.");
@@ -173,7 +173,7 @@ function getDefaultOptions(projectName) {
   return {
     projectName,
     appKey: crypto2.randomBytes(32).toString("hex"),
-    indexerUrl: "https://app.sia.storage",
+    indexerUrl: "https://sia.storage",
     appDescription: "A Sia storage app"
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sia-app",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "bin": {
     "create-sia-app": "./dist/index.js"

package/template/CLAUDE.md

@@ -2,9 +2,9 @@
 
 ## Overview
 
-A starter template for building decentralized storage apps on the Sia network. Uses `@siafoundation/sia` — a TypeScript SDK that ships a pre-compiled WASM binary for encryption, uploads, downloads, and key management.
+A starter template for building decentralized storage apps on the Sia network. Uses [`sia-storage`](https://www.npmjs.com/package/sia-storage) — a TypeScript SDK that ships a pre-compiled WASM binary for encryption, uploads, downloads, and key management. WASM runs on the main thread (Rust async — no workers required).
 
-**Tech stack:** React 19, TypeScript, Vite, Tailwind CSS 4, Zustand, `@siafoundation/sia`
+**Tech stack:** React 19, TypeScript, Vite, Tailwind CSS 4, Zustand, `sia-storage`
 
 ## Architecture
 
@@ -17,79 +17,93 @@ loading → connect → approve → recovery → connected
 ```
 
 - **loading**: WASM initializes, checks for stored app key
-- **connect**: User enters indexer URL, app requests connection
-- **approve**: User visits approval URL in another tab
-- **recovery**: User generates or enters 12-word recovery phrase
-- **connected**: SDK is ready, main app UI renders
+- **connect**: User enters indexer URL, app constructs a `Builder` and calls `requestConnection()`
+- **approve**: User visits approval URL in another tab; app polls `builder.waitForApproval()`
+- **recovery**: User generates or enters a 12-word BIP-39 recovery phrase; `builder.register(phrase)` returns the `Sdk`
+- **connected**: `Sdk` is ready, main app UI renders
+
+### Returning users
+
+Returning users skip `requestConnection`/`waitForApproval`/`register` entirely. `AuthFlow` constructs a `Builder` and calls `builder.connected(appKey)` with the persisted key — it returns an `Sdk` if the key is still valid, or `undefined` to fall back to the `connect` step.
 
 ### SDK
 
-The SDK (`@siafoundation/sia`) is an npm package that handles:
+`sia-storage` handles:
 - Encrypted file uploads/downloads (erasure coding + encryption)
 - Key derivation from recovery phrases (BIP-39)
 - Object pinning and metadata management
 - Connection auth with indexers
-- Parallel multi-worker uploads and downloads
+- Direct streaming to/from Sia hosts (no worker pool needed)
 
 ### Zustand Persistence
 
-Auth state persists to localStorage via Zustand's `persist` middleware. The storage key is `{app-name}-auth`. Persisted fields: `storedKeyHex`, `indexerUrl`.
+Auth state persists to localStorage via Zustand's `persist` middleware. The storage key is `{app-name}-auth`. Persisted fields: `storedKeyHex`, `indexerUrl`. The app key is stored as hex via the TC39 `Uint8Array.prototype.toHex` method.
 
 ## Key Files
 
 | File | Description |
 |------|-------------|
-| `src/lib/constants.ts` | App key, app name, indexer URL, app metadata |
-| `src/stores/auth.ts` | Auth state machine (Zustand + persist) |
+| `src/lib/constants.ts` | App key, app name, indexer URL, app metadata (typed `AppMetadata`) |
+| `src/stores/auth.ts` | Auth state machine (Zustand + persist), holds the `Sdk` |
 | `src/stores/toast.ts` | Toast notification store (auto-dismiss) |
 | `src/components/Navbar.tsx` | App navbar with title, public key, sign out |
 | `src/components/Toast.tsx` | Toast overlay component |
 | `src/components/CopyButton.tsx` | Copy-to-clipboard button with toast |
-| `src/components/auth/AuthFlow.tsx` | Auth orchestrator |
-| `src/components/auth/ConnectScreen.tsx` | Indexer connection + CORS fallback |
+| `src/components/auth/AuthFlow.tsx` | Auth orchestrator — `initSia()`, returning-user reconnect via `Builder.connected` |
+| `src/components/auth/ConnectScreen.tsx` | Indexer URL form; constructs `new Builder(url, APP_META)` and calls `requestConnection()` |
 | `src/components/auth/ApproveScreen.tsx` | Approval polling (auto-polls on mount) |
-| `src/components/auth/RecoveryScreen.tsx` | Recovery phrase generation/import |
+| `src/components/auth/RecoveryScreen.tsx` | Recovery phrase generation/import; `builder.register(phrase)` → `Sdk` |
 | `src/components/upload/UploadZone.tsx` | File upload/download dropzone + file list |
-| `src/components/DevNote.tsx` | Developer callout component (unused, available for customization) |
+| `src/components/DevNote.tsx` | Developer callout component |
+| `src/types/uint8array-hex.d.ts` | Ambient types for TC39 `Uint8Array.toHex`/`fromHex` (drop once TS lib ships them) |
 
 ## SDK Usage Patterns
 
 ### Upload a file
 
 ```ts
-const pinnedObject = await client.upload(file, (progress) => {
-  // progress.phase: 'connecting' | 'uploading' | 'assembling' | 'pinning'
-  console.log(`${progress.slabsComplete}/${progress.slabsTotal} slabs`)
+import { PinnedObject } from 'sia-storage'
+
+const object = new PinnedObject()
+const pinnedObject = await sdk.upload(object, file.stream(), {
+  maxInflight: 10,
+  onShardUploaded: (progress) => {
+    // progress: { hostKey, shardSize, shardIndex, slabIndex, elapsedMs }
+    console.log(`shard ${progress.shardIndex} uploaded (${progress.shardSize}b)`)
+  },
 })
+
 pinnedObject.updateMetadata(new TextEncoder().encode(JSON.stringify({
   name: 'file.txt',
   type: 'text/plain',
   size: file.size,
   hash: '...',
 })))
-await client.pinObject(pinnedObject)
-await client.updateObjectMetadata(pinnedObject)
+await sdk.pinObject(pinnedObject)
+await sdk.updateObjectMetadata(pinnedObject)
 ```
 
 ### Download a file
 
+`sdk.download` returns a `ReadableStream` of `Uint8Array` chunks. Buffer it, or stream it directly into a `Response`/`Blob`:
+
 ```ts
-const data = await client.download(pinnedObject, (progress) => {
-  // progress.phase: 'connecting' | 'downloading' | 'assembling'
-  console.log(`${progress.slabsComplete}/${progress.slabsTotal} slabs`)
+const stream = sdk.download(pinnedObject, {
+  maxInflight: 10,
+  onShardDownloaded: (progress) => {
+    console.log(`shard ${progress.shardIndex} downloaded`)
+  },
 })
-// data is Uint8Array
+const blob = await new Response(stream).blob()
 ```
 
 ### List files
 
 ```ts
-import { decodeMetadata } from '@siafoundation/sia'
-
-const events = await client.objectEvents(null, 100)
+const events = await sdk.objectEvents(undefined, 100)
 for (const event of events) {
   if (!event.deleted && event.object) {
-    const meta = decodeMetadata(event.object.metadata())
+    const meta = JSON.parse(new TextDecoder().decode(event.object.metadata()))
     console.log(meta.name, event.object.size())
   }
 }
@@ -98,21 +112,21 @@ for (const event of events) {
 ### Delete a file
 
 ```ts
-await client.deleteObject(objectId)
+await sdk.deleteObject(objectId)
 ```
 
 ### Share a file
 
 ```ts
-const validUntil = Date.now() + 7 * 24 * 60 * 60 * 1000 // 7 days
-const shareUrl = client.shareObject(pinnedObject, validUntil)
+const validUntil = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000) // 7 days
+const shareUrl = sdk.shareObject(pinnedObject, validUntil)
 ```
 
-### Download shared file
+### Download a shared file
 
 ```ts
-const object = await client.sharedObject(shareUrl)
-const data = await client.download(object)
+const object = await sdk.sharedObject(shareUrl)
+const stream = sdk.download(object)
 ```
 
 ## Customization
@@ -122,12 +136,12 @@ const data = await client.download(object)
 Edit `src/lib/constants.ts`. The app key is a 32-byte hex string that identifies your app to the indexer. Generate one with:
 
 ```ts
-crypto.randomBytes(32).toString('hex')
+crypto.getRandomValues(new Uint8Array(32)).toHex()
 ```
 
 ### Replace the upload UI
 
-The post-auth UI is rendered in `src/App.tsx`. Replace `<UploadZone />` with your own component. The `SiaClient` is available via `useAuthStore((s) => s.client)`. `SiaClient` exposes all SDK methods directly — use `client.upload()`, `client.download()`, `client.objectEvents()`, etc.
+The post-auth UI is rendered in `src/App.tsx`. Replace `<UploadZone />` with your own component. The `Sdk` is available via `useAuthStore((s) => s.sdk)`. All SDK methods live directly on `Sdk` — `sdk.upload()`, `sdk.download()`, `sdk.objectEvents()`, etc.
 
 ### Add routes
 

package/template/README.md

@@ -45,14 +45,14 @@ Indexer service
 
 ### Auth Flow
 
-1. **Connect** — Enter an indexer URL (default: `https://app.sia.storage`). The app sends your app metadata to request a connection.
+1. **Connect** — Enter an indexer URL (default: `https://sia.storage`). The app sends your app metadata to request a connection.
 2. **Approve** — Visit the approval URL in another tab to authorize your app.
 3. **Recovery Phrase** — Generate a new 12-word phrase or enter an existing one. This deterministically derives all cryptographic keys.
 4. **Connected** — The SDK is ready. Your app key is saved to localStorage for future sessions.
 
 ### Upload Flow
 
-Files are encrypted in the browser, erasure coded into shards, and uploaded directly to Sia hosts. The SDK handles all of this — your code just calls `client.upload(file, onProgress)`. Metadata (filename, type, size) is also encrypted and pinned to the indexer.
+Files are encrypted in the browser, erasure coded into shards, and streamed directly to Sia hosts. The SDK handles all of this — your code just calls `sdk.upload(object, file.stream(), { onShardUploaded })`. Metadata (filename, type, size) is also encrypted and pinned to the indexer.
 
 ## Customization
 
@@ -65,7 +65,7 @@ Edit `src/lib/constants.ts` to set your app key, name, description, and indexer
 The main post-auth component is `src/components/upload/UploadZone.tsx`. Replace it with your own UI — the SDK is available via:
 
 ```tsx
-const client = useAuthStore((s) => s.client)
+const sdk = useAuthStore((s) => s.sdk)
 ```
 
 ## Tech Stack
@@ -76,14 +76,15 @@ const client = useAuthStore((s) => s.client)
 - [Tailwind CSS](https://tailwindcss.com) 4
 - [Zustand](https://zustand.docs.pmnd.rs) (state management)
 - [Biome](https://biomejs.dev) (linting & formatting)
-- [@siafoundation/sia](https://www.npmjs.com/package/@siafoundation/sia) (Sia SDK — encryption, erasure coding, host transfers)
+- [sia-storage](https://www.npmjs.com/package/sia-storage) (Sia SDK — encryption, erasure coding, direct host transfers via WASM)
 
 ## Project Structure
 
 ```
 src/
 ├── lib/            # Constants, utilities
-├── stores/         # Zustand auth store
+├── stores/         # Zustand stores (auth + toast)
+├── types/          # Ambient type declarations (TC39 Uint8Array.toHex/fromHex)
 └── components/
     ├── auth/       # Auth flow screens
     ├── upload/     # Upload dropzone
@@ -93,4 +94,4 @@ src/
 ## Learn More
 
 - [Sia Documentation](https://docs.sia.tech)
-- [@siafoundation/sia](https://www.npmjs.com/package/@siafoundation/sia)
+- [sia-storage](https://www.npmjs.com/package/sia-storage)

package/template/biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.1/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.12/schema.json",
   "vcs": {
     "enabled": false,
     "clientKind": "git",

package/template/package.json

@@ -10,21 +10,20 @@
     "check": "biome check ."
   },
   "dependencies": {
-    "@siafoundation/sia": "^0.6.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "sia-storage": "^0.0.8",
     "zustand": "^5.0.11"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.0",
+    "@biomejs/biome": "^2.4.12",
+    "@playwright/test": "^1.59.1",
     "@tailwindcss/vite": "^4.1.18",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.1.1",
     "tailwindcss": "^4.1.18",
     "typescript": "~5.9.3",
-    "vite": "^7.3.1",
-    "vite-plugin-top-level-await": "^1.6.0",
-    "vite-plugin-wasm": "^3.5.0"
+    "vite": "^7.3.1"
   }
 }

package/template/src/components/Navbar.tsx

@@ -5,17 +5,17 @@ import { CopyButton } from './CopyButton'
 
 export function Navbar() {
   const step = useAuthStore((s) => s.step)
-  const client = useAuthStore((s) => s.client)
+  const sdk = useAuthStore((s) => s.sdk)
   const reset = useAuthStore((s) => s.reset)
   const isConnected = step === 'connected'
 
   const publicKey = useMemo(() => {
     try {
-      return client?.appKey().publicKey() ?? null
+      return sdk?.appKey().publicKey() ?? null
     } catch {
       return null
     }
-  }, [client])
+  }, [sdk])
 
   function handleSignOut() {
     reset()

package/template/src/components/auth/ApproveScreen.tsx

@@ -1,5 +1,5 @@
-import type { Builder } from '@siafoundation/sia'
 import { useEffect, useRef, useState } from 'react'
+import type { Builder } from 'sia-storage'
 import { useAuthStore } from '../../stores/auth'
 import { CopyButton } from '../CopyButton'
 import { DevNote } from '../DevNote'

package/template/src/components/auth/AuthFlow.tsx

@@ -1,11 +1,6 @@
-import {
-  AppKey,
-  type Builder,
-  connect,
-  fromHex,
-  initSia,
-} from '@siafoundation/sia'
 import { useEffect, useRef } from 'react'
+import { AppKey, Builder, initSia } from 'sia-storage'
+import { APP_META } from '../../lib/constants'
 import { useAuthStore } from '../../stores/auth'
 import { ApproveScreen } from './ApproveScreen'
 import { ConnectScreen } from './ConnectScreen'
@@ -22,19 +17,19 @@ export function AuthFlow() {
     let cancelled = false
 
     async function init() {
-      const { storedKeyHex, indexerUrl, setClient, setStep } =
+      const { storedKeyHex, indexerUrl, setSdk, setStep } =
         useAuthStore.getState()
       try {
         await initSia()
 
         if (storedKeyHex && indexerUrl) {
-          const keyBytes = fromHex(storedKeyHex)
-          const appKey = new AppKey(keyBytes)
-          const client = await connect(indexerUrl, appKey)
+          const appKey = new AppKey(Uint8Array.fromHex(storedKeyHex))
+          const builder = new Builder(indexerUrl, APP_META)
+          const sdk = await builder.connected(appKey)
 
           if (cancelled) return
-          if (client) {
-            setClient(client)
+          if (sdk) {
+            setSdk(sdk)
             return
           }
         }

package/template/src/components/auth/ConnectScreen.tsx

@@ -1,6 +1,6 @@
-import { Builder } from '@siafoundation/sia'
 import { useState } from 'react'
-import { APP_KEY, APP_META, DEFAULT_INDEXER_URL } from '../../lib/constants'
+import { Builder } from 'sia-storage'
+import { APP_META, DEFAULT_INDEXER_URL } from '../../lib/constants'
 import { useAuthStore } from '../../stores/auth'
 import { DevNote } from '../DevNote'
 
@@ -13,24 +13,26 @@ export function ConnectScreen({
     useAuthStore()
   const [url, setUrl] = useState(indexerUrl || DEFAULT_INDEXER_URL)
   const [loading, setLoading] = useState(false)
-  const [showCurl, setShowCurl] = useState(false)
-  const [curlResponse, setCurlResponse] = useState('')
 
   async function handleConnect() {
     setLoading(true)
     setError(null)
     try {
-      const b = new Builder(url)
+      const b = new Builder(url, APP_META)
       builder.current = b
       setIndexerUrl(url)
 
       try {
-        await b.requestConnection(APP_META)
+        await b.requestConnection()
         const approvalUrl = b.responseUrl()
         setApprovalUrl(approvalUrl)
         setStep('approve')
-      } catch {
-        setShowCurl(true)
+      } catch (e) {
+        setError(
+          e instanceof Error
+            ? `Connection failed: ${e.message}. Check the indexer URL and that it allows requests from this origin (CORS).`
+            : 'Connection failed. Check the indexer URL and CORS configuration.',
+        )
       }
     } catch (e) {
       setError(e instanceof Error ? e.message : 'Failed to connect')
@@ -39,26 +41,6 @@ export function ConnectScreen({
     }
   }
 
-  function handleCurlSubmit() {
-    try {
-      const b = builder.current
-      if (!b) {
-        setError('No builder instance')
-        return
-      }
-      b.setConnectionResponse(APP_KEY, curlResponse)
-      const approvalUrl = b.responseUrl()
-      setApprovalUrl(approvalUrl)
-      setStep('approve')
-    } catch (e) {
-      setError(e instanceof Error ? e.message : 'Invalid response')
-    }
-  }
-
-  const curlCommand = `curl -X POST ${url}/auth/connect \\
-  -H "Content-Type: application/json" \\
-  -d '${APP_META}'`
-
   return (
     <div className="flex flex-col items-center justify-center flex-1 px-4">
       <div className="w-full max-w-md space-y-6">
@@ -74,14 +56,14 @@ export function ConnectScreen({
         <DevNote title="Indexer URL & App Key">
           <p>
             The indexer URL points to your Sia storage provider. The default is{' '}
-            <code className="text-amber-300">https://app.sia.storage</code>.
-            Your app key (set in{' '}
+            <code className="text-amber-300">https://sia.storage</code>. Your
+            app key (set in{' '}
             <code className="text-amber-300">src/lib/constants.ts</code>)
             uniquely identifies your app to the indexer.
           </p>
           <p className="mt-1">
-            If the direct connection fails (CORS), the app falls back to a
-            manual curl flow where the user pastes the response.
+            If the connection fails with a CORS error, the indexer must allow
+            requests from this app&apos;s origin.
           </p>
         </DevNote>
 
@@ -90,7 +72,7 @@ export function ConnectScreen({
             type="url"
             value={url}
             onChange={(e) => setUrl(e.target.value)}
-            placeholder="https://app.sia.storage"
+            placeholder="https://sia.storage"
             className="w-full px-4 py-3 bg-neutral-900 border border-neutral-700 rounded-lg text-white placeholder-neutral-500 focus:outline-none focus:border-green-500"
           />
 
@@ -103,33 +85,6 @@ export function ConnectScreen({
             {loading ? 'Connecting...' : 'Connect'}
           </button>
         </div>
-
-        {showCurl && (
-          <div className="space-y-4 p-4 bg-neutral-900 rounded-lg border border-neutral-700">
-            <p className="text-sm text-neutral-300">
-              Direct connection failed (CORS). Run this command and paste the
-              response:
-            </p>
-            <pre className="text-xs bg-neutral-950 p-3 rounded overflow-x-auto text-green-400">
-              {curlCommand}
-            </pre>
-            <textarea
-              value={curlResponse}
-              onChange={(e) => setCurlResponse(e.target.value)}
-              placeholder="Paste the JSON response here..."
-              rows={4}
-              className="w-full px-3 py-2 bg-neutral-950 border border-neutral-700 rounded text-sm text-white placeholder-neutral-500 focus:outline-none focus:border-green-500 font-mono"
-            />
-            <button
-              type="button"
-              onClick={handleCurlSubmit}
-              disabled={!curlResponse}
-              className="w-full py-2 bg-green-600 hover:bg-green-700 disabled:bg-neutral-700 disabled:text-neutral-500 text-white text-sm font-medium rounded-lg transition-colors"
-            >
-              Submit Response
-            </button>
-          </div>
-        )}
       </div>
     </div>
   )

package/template/src/components/auth/RecoveryScreen.tsx

@@ -1,10 +1,9 @@
+import { useState } from 'react'
 import {
   type Builder,
   generateRecoveryPhrase,
-  toHex,
   validateRecoveryPhrase,
-} from '@siafoundation/sia'
-import { useState } from 'react'
+} from 'sia-storage'
 import { useAuthStore } from '../../stores/auth'
 import { CopyButton } from '../CopyButton'
 import { DevNote } from '../DevNote'
@@ -14,7 +13,7 @@ export function RecoveryScreen({
 }: {
   builder: React.RefObject<Builder | null>
 }) {
-  const { setClient, setStoredKeyHex, setError } = useAuthStore()
+  const { setSdk, setStoredKeyHex, setError } = useAuthStore()
   const [mode, setMode] = useState<'choose' | 'generate' | 'import'>('choose')
   const [phrase, setPhrase] = useState('')
   const [generatedPhrase, setGeneratedPhrase] = useState('')
@@ -57,11 +56,9 @@ export function RecoveryScreen({
 
     setLoading(true)
     try {
-      const client = await b.register(mnemonic)
-      const appKey = client.appKey()
-      const exported = appKey.export()
-      setStoredKeyHex(toHex(exported))
-      setClient(client)
+      const sdk = await b.register(mnemonic)
+      setStoredKeyHex(sdk.appKey().export().toHex())
+      setSdk(sdk)
     } catch (e) {
       setError(e instanceof Error ? e.message : 'Registration failed')
     } finally {

package/template/src/components/upload/UploadZone.tsx

@@ -1,11 +1,5 @@
-import {
-  type DownloadProgress,
-  decodeMetadata,
-  type PinnedObject,
-  toHex,
-  type UploadProgress,
-} from '@siafoundation/sia'
 import { useCallback, useEffect, useRef, useState } from 'react'
+import { PinnedObject, type ShardProgress } from 'sia-storage'
 import { APP_KEY } from '../../lib/constants'
 import { useAuthStore } from '../../stores/auth'
 import { DevNote } from '../DevNote'
@@ -27,26 +21,40 @@ function formatBytes(bytes: number): string {
   return `${parseFloat((bytes / k ** i).toFixed(1))} ${sizes[i]}`
 }
 
+function decodeMetadata(bytes: Uint8Array): FileMetadata | null {
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes)) as FileMetadata
+  } catch {
+    return null
+  }
+}
+
 type UploadedFile = {
   id: string
   metadata: FileMetadata
   object: PinnedObject
 }
 
-type ActiveUpload = {
+type UploadProgress = {
   fileName: string
-  progress: UploadProgress
+  shardsDone: number
+  bytesUploaded: number
+  totalBytes: number
+}
+
+type DownloadProgress = {
+  shardsDone: number
+  bytesDownloaded: number
+  totalBytes: number
 }
 
-// Detect unconfigured template placeholder. The string is split so the
-// scaffolder's {{APP_KEY}} replacement doesn't rewrite this check.
 const isPlaceholderKey = APP_KEY.startsWith('{' + '{')
 
 export function UploadZone() {
-  const client = useAuthStore((s) => s.client)
+  const sdk = useAuthStore((s) => s.sdk)
   const [files, setFiles] = useState<UploadedFile[]>([])
   const [uploading, setUploading] = useState(false)
-  const [activeUpload, setActiveUpload] = useState<ActiveUpload | null>(null)
+  const [activeUpload, setActiveUpload] = useState<UploadProgress | null>(null)
   const [dragOver, setDragOver] = useState(false)
   const [error, setError] = useState<string | null>(null)
   const [downloading, setDownloading] = useState<string | null>(null)
@@ -55,14 +63,14 @@ export function UploadZone() {
   const fileInputRef = useRef<HTMLInputElement>(null)
 
   const loadFiles = useCallback(async () => {
-    if (!client) return
+    if (!sdk) return
     try {
-      const events = await client.objectEvents(null, 100)
+      const events = await sdk.objectEvents(undefined, 100)
       const loaded: UploadedFile[] = []
       for (const event of events) {
         if (event.deleted || !event.object) continue
-        const meta = decodeMetadata(event.object.metadata()) as FileMetadata
-        if (meta.name) {
+        const meta = decodeMetadata(event.object.metadata())
+        if (meta?.name) {
           loaded.push({ id: event.id, metadata: meta, object: event.object })
         }
       }
@@ -70,37 +78,45 @@ export function UploadZone() {
     } catch (e) {
       console.error('Failed to load files:', e)
     }
-  }, [client])
+  }, [sdk])
 
   useEffect(() => {
     loadFiles()
   }, [loadFiles])
 
   async function uploadFile(file: File) {
-    if (!client) return
+    if (!sdk) return
     setUploading(true)
     setError(null)
     setActiveUpload({
       fileName: file.name,
-      progress: {
-        phase: 'connecting',
-        slabsComplete: 0,
-        slabsTotal: 0,
-        shardsComplete: 0,
-        shardsTotal: 0,
-      },
+      shardsDone: 0,
+      bytesUploaded: 0,
+      totalBytes: file.size,
     })
 
     try {
-      // Compute SHA-256 hash for metadata
       const hashBuffer = await crypto.subtle.digest(
         'SHA-256',
         await file.arrayBuffer(),
       )
-      const hash = toHex(new Uint8Array(hashBuffer))
+      const hash = new Uint8Array(hashBuffer).toHex()
 
-      const pinnedObject = await client.upload(file, (p) => {
-        setActiveUpload({ fileName: file.name, progress: p })
+      const object = new PinnedObject()
+      let shardsDone = 0
+      let bytesUploaded = 0
+      const pinnedObject = await sdk.upload(object, file.stream(), {
+        maxInflight: 10,
+        onShardUploaded: (progress: ShardProgress) => {
+          shardsDone++
+          bytesUploaded += progress.shardSize
+          setActiveUpload({
+            fileName: file.name,
+            shardsDone,
+            bytesUploaded,
+            totalBytes: file.size,
+          })
+        },
       })
 
       const metadata: FileMetadata = {
@@ -114,8 +130,8 @@ export function UploadZone() {
       pinnedObject.updateMetadata(
         new TextEncoder().encode(JSON.stringify(metadata)),
       )
-      await client.pinObject(pinnedObject)
-      await client.updateObjectMetadata(pinnedObject)
+      await sdk.pinObject(pinnedObject)
+      await sdk.updateObjectMetadata(pinnedObject)
 
       setFiles((prev) => [
         { id: pinnedObject.id(), metadata, object: pinnedObject },
@@ -130,14 +146,43 @@ export function UploadZone() {
   }
 
   async function downloadFile(file: UploadedFile) {
-    if (!client) return
+    if (!sdk) return
     setDownloading(file.id)
-    setDownloadProgress(null)
+    setDownloadProgress({
+      shardsDone: 0,
+      bytesDownloaded: 0,
+      totalBytes: file.metadata.size,
+    })
     try {
-      const data = await client.download(file.object, (p) => {
-        setDownloadProgress(p)
+      let shardsDone = 0
+      const stream = sdk.download(file.object, {
+        maxInflight: 10,
+        onShardDownloaded: () => {
+          shardsDone++
+          setDownloadProgress((prev) => ({
+            shardsDone,
+            bytesDownloaded: prev?.bytesDownloaded ?? 0,
+            totalBytes: file.metadata.size,
+          }))
+        },
       })
-      const blob = new Blob([data as BlobPart], { type: file.metadata.type })
+
+      const reader = stream.getReader()
+      const chunks: Uint8Array[] = []
+      let bytesDownloaded = 0
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        chunks.push(value)
+        bytesDownloaded += value.length
+        setDownloadProgress((prev) => ({
+          shardsDone: prev?.shardsDone ?? 0,
+          bytesDownloaded,
+          totalBytes: file.metadata.size,
+        }))
+      }
+
+      const blob = new Blob(chunks as BlobPart[], { type: file.metadata.type })
       const url = URL.createObjectURL(blob)
       const a = document.createElement('a')
       a.href = url
@@ -166,30 +211,14 @@ export function UploadZone() {
     }
   }
 
-  const progress = activeUpload?.progress
-  const isIndeterminate =
-    progress &&
-    (progress.phase === 'connecting' ||
-      progress.phase === 'assembling' ||
-      progress.phase === 'pinning')
-  const progressPercent =
-    progress && progress.slabsTotal > 0
-      ? Math.round((progress.slabsComplete / progress.slabsTotal) * 100)
-      : 0
-
-  function progressLabel(): string {
-    if (!progress) return ''
-    switch (progress.phase) {
-      case 'connecting':
-        return 'Connecting to hosts...'
-      case 'uploading':
-        return `${progress.slabsComplete}/${progress.slabsTotal} slabs \u00B7 ${progressPercent}%`
-      case 'assembling':
-        return 'Assembling object...'
-      case 'pinning':
-        return 'Pinning object...'
-    }
-  }
+  const uploadPercent = activeUpload
+    ? Math.min(
+        100,
+        Math.round(
+          (activeUpload.bytesUploaded / activeUpload.totalBytes) * 100,
+        ),
+      )
+    : 0
 
   return (
     <div className="flex-1 p-6 space-y-5 max-w-5xl mx-auto w-full">
@@ -208,14 +237,14 @@ export function UploadZone() {
       <DevNote title="Upload & Download">
         <p>
           <code className="text-amber-300">
-            client.upload(file, onProgress)
+            sdk.upload(object, file.stream(), opts)
           </code>{' '}
-          encrypts, erasure-codes, and uploads to Sia hosts using parallel Web
-          Workers.{' '}
-          <code className="text-amber-300">
-            client.download(object, onProgress)
-          </code>{' '}
-          retrieves and decrypts files the same way.
+          encrypts, erasure-codes, and streams shards directly to Sia hosts.{' '}
+          <code className="text-amber-300">sdk.download(object, opts)</code>{' '}
+          returns a <code className="text-amber-300">ReadableStream</code> of
+          decrypted bytes. Per-shard progress is reported via{' '}
+          <code className="text-amber-300">onShardUploaded</code> /{' '}
+          <code className="text-amber-300">onShardDownloaded</code>.
         </p>
       </DevNote>
 
@@ -266,30 +295,23 @@ export function UploadZone() {
         {activeUpload ? (
           <div className="space-y-4">
             <p className="text-neutral-300 text-sm">
-              {progress?.phase === 'connecting' ? (
-                <>
-                  Preparing upload for{' '}
-                  <span className="text-white">{activeUpload.fileName}</span>
-                </>
-              ) : (
-                <>
-                  Uploading{' '}
-                  <span className="text-white">{activeUpload.fileName}</span>
-                </>
-              )}
+              Uploading{' '}
+              <span className="text-white">{activeUpload.fileName}</span>
             </p>
             <div className="w-full max-w-xs mx-auto bg-neutral-800 rounded-full h-1.5 overflow-hidden">
-              {isIndeterminate ? (
+              {activeUpload.shardsDone === 0 ? (
                 <div className="bg-green-500 h-full rounded-full w-1/4 animate-indeterminate" />
               ) : (
                 <div
                   className="bg-green-500 h-full rounded-full transition-all duration-300"
-                  style={{ width: `${progressPercent}%` }}
+                  style={{ width: `${uploadPercent}%` }}
                 />
               )}
             </div>
             <p className="text-neutral-600 text-xs font-mono">
-              {progressLabel()}
+              {activeUpload.shardsDone} shards &middot;{' '}
+              {formatBytes(activeUpload.bytesUploaded)} /{' '}
+              {formatBytes(activeUpload.totalBytes)}
             </p>
           </div>
         ) : (
@@ -340,12 +362,11 @@ export function UploadZone() {
                       )}
                       {isDownloading && downloadProgress && (
                         <span>
-                          {' &middot; '}
-                          {downloadProgress.phase === 'downloading'
-                            ? `${downloadProgress.slabsComplete}/${downloadProgress.slabsTotal} slabs`
-                            : downloadProgress.phase === 'connecting'
-                              ? 'Connecting...'
-                              : 'Assembling...'}
+                          {' '}
+                          &middot;{' '}
+                          {formatBytes(downloadProgress.bytesDownloaded)} /{' '}
+                          {formatBytes(downloadProgress.totalBytes)} (
+                          {downloadProgress.shardsDone} shards)
                         </span>
                       )}
                     </p>

package/template/src/lib/constants.ts

@@ -1,9 +1,14 @@
+import type { AppMetadata } from 'sia-storage'
+
+// biome-ignore format: scaffolder substitutes a 64-char hex string here
 export const APP_KEY = '{{APP_KEY}}'
 export const APP_NAME = '{{APP_NAME}}'
 export const DEFAULT_INDEXER_URL = '{{INDEXER_URL}}'
-export const APP_META = JSON.stringify({
-  appID: APP_KEY,
+export const APP_META: AppMetadata = {
+  appId: APP_KEY,
   name: APP_NAME,
   description: '{{APP_DESCRIPTION}}',
-  serviceURL: '{{INDEXER_URL}}',
-})
+  serviceUrl: '{{INDEXER_URL}}',
+  logoUrl: undefined,
+  callbackUrl: undefined,
+}

package/template/src/stores/auth.ts

@@ -1,4 +1,4 @@
-import type { SiaClient } from '@siafoundation/sia'
+import type { Sdk } from 'sia-storage'
 import { create } from 'zustand'
 import { persist } from 'zustand/middleware'
 
@@ -10,13 +10,13 @@ export type AuthStep =
   | 'connected'
 
 type AuthState = {
-  client: SiaClient | null
+  sdk: Sdk | null
   storedKeyHex: string | null
   indexerUrl: string
   step: AuthStep
   error: string | null
   approvalUrl: string | null
-  setClient: (client: SiaClient) => void
+  setSdk: (sdk: Sdk) => void
   setStep: (step: AuthStep) => void
   setError: (error: string | null) => void
   setStoredKeyHex: (hex: string) => void
@@ -28,13 +28,13 @@ type AuthState = {
 export const useAuthStore = create<AuthState>()(
   persist(
     (set) => ({
-      client: null,
+      sdk: null,
       storedKeyHex: null,
       indexerUrl: '',
       step: 'loading',
       error: null,
       approvalUrl: null,
-      setClient: (client) => set({ client, step: 'connected', error: null }),
+      setSdk: (sdk) => set({ sdk, step: 'connected', error: null }),
       setStep: (step) => set({ step, error: null }),
       setError: (error) => set({ error }),
       setStoredKeyHex: (hex) => set({ storedKeyHex: hex }),
@@ -42,7 +42,7 @@ export const useAuthStore = create<AuthState>()(
       setApprovalUrl: (url) => set({ approvalUrl: url }),
       reset: () =>
         set({
-          client: null,
+          sdk: null,
           storedKeyHex: null,
           step: 'loading',
           error: null,

package/template/src/types/uint8array-hex.d.ts

@@ -0,0 +1,10 @@
+// TC39 Uint8Array hex methods (Stage 3, supported in modern browsers).
+// Drop this file once `lib.es*.d.ts` ships them.
+
+interface Uint8Array {
+  toHex(): string
+}
+
+interface Uint8ArrayConstructor {
+  fromHex(hex: string): Uint8Array
+}

package/template/tsconfig.app.json

@@ -15,9 +15,6 @@
     "moduleDetection": "force",
     "noEmit": true,
     "jsx": "react-jsx",
-    "paths": {
-      "sia-wasm": ["./node_modules/@siafoundation/sia/wasm/sia.d.ts"]
-    },
 
     /* Linting */
     "strict": true,

package/template/vite.config.ts

@@ -1,17 +1,10 @@
 import tailwindcss from '@tailwindcss/vite'
 import react from '@vitejs/plugin-react'
 import { defineConfig } from 'vite'
-import topLevelAwait from 'vite-plugin-top-level-await'
-import wasm from 'vite-plugin-wasm'
 
 export default defineConfig({
-  plugins: [react(), tailwindcss(), wasm(), topLevelAwait()],
-  optimizeDeps: {
-    exclude: ['@siafoundation/sia', 'sia-wasm'],
-  },
-  resolve: {
-    alias: {
-      'sia-wasm': '@siafoundation/sia/wasm',
-    },
-  },
+  plugins: [react(), tailwindcss()],
+  // sia-storage loads its WASM via `new URL(..., import.meta.url)`; excluding
+  // it from the deps pre-bundler keeps that URL pointing at the real file.
+  optimizeDeps: { exclude: ['sia-storage'] },
 })

package/template/AGENTS.md

@@ -1,143 +0,0 @@
-# Sia Starter — AI Assistant Guide
-
-## Overview
-
-A starter template for building decentralized storage apps on the Sia network. Uses `@siafoundation/sia` — a TypeScript SDK that ships a pre-compiled WASM binary for encryption, uploads, downloads, and key management.
-
-**Tech stack:** React 19, TypeScript, Vite, Tailwind CSS 4, Zustand, `@siafoundation/sia`
-
-## Architecture
-
-### Auth Flow State Machine
-
-The app uses a step-based auth flow managed by Zustand (`src/stores/auth.ts`):
-
-```
-loading → connect → approve → recovery → connected
-```
-
-- **loading**: WASM initializes, checks for stored app key
-- **connect**: User enters indexer URL, app requests connection
-- **approve**: User visits approval URL in another tab
-- **recovery**: User generates or enters 12-word recovery phrase
-- **connected**: SDK is ready, main app UI renders
-
-### SDK
-
-The SDK (`@siafoundation/sia`) is an npm package that handles:
-- Encrypted file uploads/downloads (erasure coding + encryption)
-- Key derivation from recovery phrases (BIP-39)
-- Object pinning and metadata management
-- Connection auth with indexers
-- Parallel multi-worker uploads and downloads
-
-### Zustand Persistence
-
-Auth state persists to localStorage via Zustand's `persist` middleware. The storage key is `{app-name}-auth`. Persisted fields: `storedKeyHex`, `indexerUrl`.
-
-## Key Files
-
-| File | Description |
-|------|-------------|
-| `src/lib/constants.ts` | App key, app name, indexer URL, app metadata |
-| `src/stores/auth.ts` | Auth state machine (Zustand + persist) |
-| `src/stores/toast.ts` | Toast notification store (auto-dismiss) |
-| `src/components/Navbar.tsx` | App navbar with title, public key, sign out |
-| `src/components/Toast.tsx` | Toast overlay component |
-| `src/components/CopyButton.tsx` | Copy-to-clipboard button with toast |
-| `src/components/auth/AuthFlow.tsx` | Auth orchestrator |
-| `src/components/auth/ConnectScreen.tsx` | Indexer connection + CORS fallback |
-| `src/components/auth/ApproveScreen.tsx` | Approval polling (auto-polls on mount) |
-| `src/components/auth/RecoveryScreen.tsx` | Recovery phrase generation/import |
-| `src/components/upload/UploadZone.tsx` | File upload/download dropzone + file list |
-| `src/components/DevNote.tsx` | Developer callout component (unused, available for customization) |
-
-## SDK Usage Patterns
-
-### Upload a file
-
-```ts
-const pinnedObject = await client.upload(file, (progress) => {
-  // progress.phase: 'connecting' | 'uploading' | 'assembling' | 'pinning'
-  console.log(`${progress.slabsComplete}/${progress.slabsTotal} slabs`)
-})
-pinnedObject.updateMetadata(new TextEncoder().encode(JSON.stringify({
-  name: 'file.txt',
-  type: 'text/plain',
-  size: file.size,
-  hash: '...',
-})))
-await client.pinObject(pinnedObject)
-await client.updateObjectMetadata(pinnedObject)
-```
-
-### Download a file
-
-```ts
-const data = await client.download(pinnedObject, (progress) => {
-  // progress.phase: 'connecting' | 'downloading' | 'assembling'
-  console.log(`${progress.slabsComplete}/${progress.slabsTotal} slabs`)
-})
-// data is Uint8Array
-```
-
-### List files
-
-```ts
-import { decodeMetadata } from '@siafoundation/sia'
-
-const events = await client.objectEvents(null, 100)
-for (const event of events) {
-  if (!event.deleted && event.object) {
-    const meta = decodeMetadata(event.object.metadata())
-    console.log(meta.name, event.object.size())
-  }
-}
-```
-
-### Delete a file
-
-```ts
-await client.deleteObject(objectId)
-```
-
-### Share a file
-
-```ts
-const validUntil = Date.now() + 7 * 24 * 60 * 60 * 1000 // 7 days
-const shareUrl = client.shareObject(pinnedObject, validUntil)
-```
-
-### Download shared file
-
-```ts
-const object = await client.sharedObject(shareUrl)
-const data = await client.download(object)
-```
-
-## Customization
-
-### Change app key
-
-Edit `src/lib/constants.ts`. The app key is a 32-byte hex string that identifies your app to the indexer. Generate one with:
-
-```ts
-crypto.randomBytes(32).toString('hex')
-```
-
-### Replace the upload UI
-
-The post-auth UI is rendered in `src/App.tsx`. Replace `<UploadZone />` with your own component. The `SiaClient` is available via `useAuthStore((s) => s.client)`. `SiaClient` exposes all SDK methods directly — use `client.upload()`, `client.download()`, `client.objectEvents()`, etc.
-
-### Add routes
-
-Install `react-router-dom` and wrap your app. The auth flow should gate all routes.
-
-## Common Commands
-
-```bash
-bun install     # Install dependencies
-bun dev         # Start dev server
-bun run build   # Production build
-bun run check   # Lint with Biome
-```