@meddleware/walrus-storage-ui 0.0.0-stage → 0.1.62

package/src/components/WalrusStorageView.vue

@@ -0,0 +1,376 @@
+<script setup lang="ts">
+// Core Walrus tool UI (upload + owned-blob management), free of any app shell (header/footer).
+// Rendered standalone by walrus-storage-ui's App.vue and inline by the dashboard. Wallet state comes
+// from the shared @meddleware/wallet-adapter singleton (via ./wallet.js), so connecting here or
+// in any other inline tool view reflects everywhere.
+import { computed, ref, watch } from 'vue'
+import { normalizeSuiAddress } from '@mysten/sui/utils'
+import {
+  WalrusUpload,
+  AccessGateCta,
+  useAccessGate,
+  type WalrusNetwork,
+} from '@meddleware/walrus-storage-kit'
+import { AppTabNav, CopyableAddress, ExplorerLink, UiNotice, UiTabPanel, UiToolIntro, suiExplorerUrl, safeHref, type AppTab } from '@meddleware/ui'
+// Lightweight URL import — just the wasm asset URL (does not pull the walrus client).
+import walrusWasmUrl from '@mysten/walrus-wasm/web/walrus_wasm_bg.wasm?url'
+import { WalletGuard } from '@meddleware/wallet-adapter'
+import { useWallet, getSuiClient } from '../wallet.js'
+import { network, walrusNetwork, relayHosts, accessGate, uploadRelayMaxTipMist, walruscanBlobUrl } from '../config.js'
+import {
+  runBlobUpload,
+  createGatedAccess,
+  consumeStorageKey,
+  pendingCertifyKey,
+  savePendingCertify,
+  clearPendingCertify,
+  loadPendingCertifies,
+  type BlobUploadResult as UploadResult,
+  type ExistingCopy,
+  type UploadProgress,
+  browserStorage,
+} from '@meddleware/walrus-storage-client/flow'
+
+// Browser storage that never throws (blocked site data falls back to memory for this page).
+const storage = browserStorage()
+import { useOwnedBlobs } from '../composables/useOwnedBlobs.js'
+import MyBlobs from './MyBlobs.vue'
+
+const TABS: AppTab[] = [
+  { id: 'upload', label: 'Upload' },
+  { id: 'blobs', label: 'My Blobs' },
+]
+const activeTab = ref<string>('upload')
+
+const { account, signPersonalMessage, buildExecutor } = useWallet()
+
+// One access-gate state per Walrus network (the gate is a per-network setting); the active
+// network's is used. Each is inert until an ownership check runs.
+// `useAccessGate` throws for a gate that is not the published deployment on its network;
+// `accessGate()` only returns such configs (or null, ungated). The shared client serves the active
+// network only, so a state for another network refuses to read rather than reading the wrong chain.
+function gateClient(net: WalrusNetwork) {
+  if (net !== network.value) throw new Error(`No Sui client for ${net} while ${network.value} is active.`)
+  return getSuiClient()
+}
+const gateStates = {
+  testnet: useAccessGate({ network: 'testnet', gate: accessGate('testnet'), getClient: gateClient }),
+  mainnet: useAccessGate({ network: 'mainnet', gate: accessGate('mainnet'), getClient: gateClient }),
+}
+/** The active network's gate state (testnet's while the view is hidden on a non-Walrus network). */
+const gateState = computed(() => gateStates[walrusNetwork.value ?? 'testnet'])
+const purchasing = ref(false)
+const result = ref<UploadResult | null>(null)
+
+// Check gate ownership whenever the connected account or the network changes. A switched or
+// disconnected wallet never inherits the previous wallet's access state: `reset()` also discards
+// any in-flight check.
+watch(
+  [() => account.value?.address ?? null, walrusNetwork],
+  ([addr], previous) => {
+    const prevAddr = previous?.[0] ?? null
+    if (addr !== prevAddr) for (const s of Object.values(gateStates)) s.reset()
+    else gateState.value.reset()
+    result.value = null
+    if (addr && walrusNetwork.value && gateState.value.gate) void gateState.value.checkOwnership(addr)
+  },
+  { immediate: true },
+)
+
+async function onPurchase(): Promise<void> {
+  if (!account.value) return
+  purchasing.value = true
+  try {
+    const executor = await buildExecutor()
+    await gateState.value.purchase(executor, account.value.address)
+  } catch {
+    // The reason is published in `purchaseError` and shown by the prompt.
+  } finally {
+    purchasing.value = false
+  }
+}
+
+// Wire the shared WalrusUpload widget to walrus-storage-client's upload orchestrator and the wallet. The
+// orchestrator registers fresh on every attempt (the relay rejects an old register transaction),
+// and, for a gated relay, `createGatedAccess` keeps the single-use consume resumable: its digest is
+// persisted before the upload, reused after an interruption, cleared once the upload lands, and
+// replaced only after the gateway reports it redeemed.
+async function performUpload(
+  bytes: Uint8Array,
+  opts: {
+    relayHost: string
+    epochs: number
+    force?: boolean
+    deletable?: boolean
+    onStatus: (s: string | UploadProgress) => void
+  },
+): Promise<UploadResult> {
+  if (!account.value) throw new Error('Connect your wallet first.')
+  const net = walrusNetwork.value
+  if (!net) throw new Error(`Walrus storage is not available on ${network.value}.`)
+  const executor = await buildExecutor()
+  const address = account.value.address
+  const state = gateState.value
+  const gate = state.gate
+  const nftId = state.nftId.value
+
+  const access =
+    gate && state.hasAccess.value === true && nftId
+      ? createGatedAccess({
+          storage,
+          key: consumeStorageKey(net, gate.gateId, address),
+          relayHost: opts.relayHost,
+          address,
+          // Signed into every access proof with the relay's origin: a proof made here works nowhere else.
+          gateId: normalizeSuiAddress(gate.gateId),
+          network: net,
+          nftId,
+          singleUse: state.singleUse.value,
+          buildConsume: (id, nonce) => state.buildConsume(id, nonce),
+          signAndExecute: (tx) => executor.signAndExecute(tx),
+          waitForTransaction: (digest) => executor.waitForTransaction(digest),
+          sign: signPersonalMessage,
+          onStatus: opts.onStatus,
+        })
+      : undefined
+
+  return runBlobUpload({
+    bytes,
+    network: net,
+    relayHost: opts.relayHost,
+    address,
+    wasmUrl: walrusWasmUrl,
+    maxTipMist: uploadRelayMaxTipMist(),
+    epochs: opts.epochs,
+    deletable: opts.deletable,
+    force: opts.force,
+    findExistingCopy,
+    executor,
+    suiClient: getSuiClient(),
+    access,
+    onStatus: opts.onStatus,
+    // Persist the certificate the moment the upload lands, and drop it once certified — so a
+    // dismissed certify can be finished from My Blobs after a tab switch or reload.
+    onUploaded: (info) => savePendingCertify(storage, pendingCertifyKey(net, address), info),
+    onCertified: (blobObjectId) => clearPendingCertify(storage, pendingCertifyKey(net, address), blobObjectId),
+  })
+}
+
+// Precheck (before paying to register): does the wallet already own this exact blob? Returns a
+// `certified` match (offer Extend) or a `pending` one — uncertified but with a saved certificate
+// (offer Certify). Best-effort: any failure returns null so the upload simply proceeds.
+async function findExistingCopy(blobId: string): Promise<ExistingCopy | null> {
+  const address = account.value?.address
+  const net = walrusNetwork.value
+  if (!address || !net) return null
+  try {
+    const { createWalrusClient, fetchOwnedWalrusBlobs } = await import('@meddleware/walrus-storage-client')
+    const walrusClient = createWalrusClient({ network: net, wasmUrl: walrusWasmUrl })
+    const [sys, owned] = await Promise.all([
+      walrusClient.walrus.systemState(),
+      fetchOwnedWalrusBlobs(getSuiClient(), walrusClient, address),
+    ])
+    const currentEpoch = Number(sys.committee.epoch)
+    const copies = owned.filter((b) => b.blobId === blobId && b.endEpoch > currentEpoch)
+    const certified = copies.find((b) => b.certified)
+    if (certified) {
+      return { kind: 'certified', blobId, objectId: certified.objectId, endEpoch: certified.endEpoch }
+    }
+    const store = loadPendingCertifies(storage, pendingCertifyKey(net, address))
+    const pending = copies.find((b) => !b.certified && b.objectId in store)
+    if (pending) {
+      return { kind: 'pending', blobId, objectId: pending.objectId, endEpoch: pending.endEpoch }
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+// Injected into the upload widget so it can price a chosen reservation duration (storage is WAL,
+// billed per size × epochs). Returns total cost in FROST, or null on error.
+async function estimateUploadStorageCost(sizeBytes: number, epochs: number): Promise<bigint | null> {
+  const net = walrusNetwork.value
+  if (!net) return null
+  try {
+    const { createWalrusClient, estimateStorageCost } = await import('@meddleware/walrus-storage-client')
+    const walrusClient = createWalrusClient({ network: net, wasmUrl: walrusWasmUrl })
+    const cost = await estimateStorageCost(walrusClient, sizeBytes, epochs)
+    return cost.totalCost
+  } catch {
+    return null
+  }
+}
+
+// The user declined a duplicate upload and chose to manage the existing copy: jump to My Blobs and
+// highlight it (the grouped row exposes Extend for certified, Certify for pending).
+const highlightBlobId = ref<string | null>(null)
+function onManageExisting(existing: ExistingCopy): void {
+  highlightBlobId.value = existing.blobId
+  activeTab.value = 'blobs'
+}
+
+const ownedBlobs = useOwnedBlobs()
+
+function onUploaded(r: UploadResult): void {
+  result.value = r
+}
+
+// Fires after every upload attempt (success or failure) — a failed UI run may still have landed
+// on-chain, so force-refresh the owned-blobs cache and NFT ownership (uses remaining) in the
+// background regardless of outcome.
+function onSettled(): void {
+  if (account.value) {
+    void ownedBlobs.load(account.value.address, { force: true })
+    if (gateState.value.gate) void gateState.value.checkOwnership(account.value.address)
+  }
+}
+</script>
+
+<template>
+    <UiToolIntro>Upload and manage blobs on Walrus decentralised storage ({{ network }}).</UiToolIntro>
+
+    <UiNotice v-if="!walrusNetwork" type="info">Walrus storage is not available on {{ network }}. Switch to testnet or mainnet.</UiNotice>
+    <template v-else>
+
+    <AppTabNav v-model="activeTab" :tabs="TABS" id-prefix="walrus" aria-label="Feature tabs" class="walrus-tabs" />
+
+    <!-- The tab list and its panel always render (the selected tab controls a live panel); the wallet
+         prompt replaces only the panel's content until a wallet is connected. -->
+    <UiTabPanel id-prefix="walrus" :tab="activeTab">
+      <WalletGuard message="Connect a Sui wallet to upload and manage your blobs.">
+        <template v-if="activeTab === 'upload'">
+          <!-- Gated + no access: replace the form with the purchase CTA so the user is guided to buy
+               first, rather than facing a disabled form. -->
+          <div v-if="gateState.gateConfigured && gateState.hasAccess.value === false" class="gate-card">
+            <AccessGateCta
+              :gate-configured="gateState.gateConfigured"
+              :has-access="gateState.hasAccess.value"
+              :busy="purchasing"
+              :terms="gateState.terms.value"
+              :terms-error="gateState.termsError.value"
+              :purchase-error="gateState.purchaseError.value"
+              @purchase="onPurchase"
+            />
+            <button
+              v-if="gateState.termsError.value && !gateState.termsLoading.value"
+              type="button"
+              class="retry-terms"
+              @click="gateState.loadTerms()"
+            >
+              Read the price again
+            </button>
+          </div>
+
+          <!-- Ownership check still in flight. -->
+          <p
+            v-else-if="gateState.gateConfigured && gateState.hasAccess.value === null"
+            class="checking"
+          >
+            Checking access…
+          </p>
+
+          <!-- Access held (or ungated relay): show the upload form. -->
+          <template v-else>
+            <!-- Gated relays spend a credit before the file is stored — make the "attempt, not a
+                 guarantee" nature explicit, while reassuring that attempts resume. -->
+            <UiNotice v-if="gateState.gateConfigured" type="info" class="credit-notice">
+              Uploading spends <strong>one credit</strong> from your access NFT (an on-chain step)
+              before the file is stored — it pays for an upload <em>attempt</em>, not a guaranteed
+              upload. Your attempt resumes automatically, even after a page reload if you re-select
+              the same file, so a credit is normally not lost. A credit is spent without a completed
+              upload only if you abandon the upload entirely, cancel a required wallet approval, or
+              wait long enough that the reserved storage lapses.
+            </UiNotice>
+
+            <WalrusUpload
+              :hosts="relayHosts(walrusNetwork)"
+              :connected="!!account"
+              :access="{ gateConfigured: gateState.gateConfigured, hasAccess: gateState.hasAccess, singleUse: gateState.singleUse }"
+              :session-key="`${walrusNetwork}:${account?.address ?? ''}`"
+              :perform-upload="performUpload"
+              :estimate-storage-cost="estimateUploadStorageCost"
+              @uploaded="onUploaded"
+              @settled="onSettled"
+              @manage-existing="onManageExisting"
+            />
+
+            <section v-if="result" class="result">
+              <h2>Uploaded ✓</h2>
+              <p>
+                <strong>Blob ID:</strong>
+                <CopyableAddress :address="result.blobId" label="Copy blob ID">
+                  <ExplorerLink
+                    :href="walruscanBlobUrl(walrusNetwork, result.blobId)"
+                    :value="result.blobId"
+                    :chars="[8, 6]"
+                  />
+                </CopyableAddress>
+              </p>
+              <p>
+                <strong>URL:</strong>
+                <a :href="safeHref(result.url)" target="_blank" rel="noopener noreferrer">{{ result.url }}</a>
+              </p>
+              <p v-if="result.digest">
+                <strong>Certify tx:</strong>
+                <CopyableAddress :address="result.digest" label="Copy transaction digest">
+                  <ExplorerLink
+                    :href="suiExplorerUrl('txblock', result.digest, walrusNetwork)"
+                    :value="result.digest"
+                    :chars="[8, 6]"
+                  />
+                </CopyableAddress>
+              </p>
+            </section>
+          </template>
+        </template>
+
+        <MyBlobs
+          v-if="activeTab === 'blobs'"
+          :address="account?.address ?? null"
+          :build-executor="() => buildExecutor()"
+          :highlight-blob-id="highlightBlobId"
+        />
+      </WalletGuard>
+    </UiTabPanel>
+    </template>
+</template>
+
+<style scoped>
+.walrus-tabs {
+  margin: 1rem 0 0.5rem;
+}
+.result {
+  margin-top: 1.5rem;
+  padding: 1rem;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  word-break: break-all;
+}
+
+.result code {
+  font-size: 0.85rem;
+}
+
+.gate-card {
+  margin-top: 1rem;
+  padding: 1.5rem;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  background: var(--surface, transparent);
+  text-align: center;
+}
+
+.checking {
+  margin-top: 1.5rem;
+  color: var(--muted);
+  text-align: center;
+}
+
+.credit-notice {
+  margin: 1rem 0;
+  font-size: 0.85rem;
+  line-height: 1.5;
+}
+
+</style>

package/src/composables/useExtendQuotes.ts

@@ -0,0 +1,69 @@
+// Prices an Extend before the wallet opens (audit F12). A row's quote is the WAL cost of adding
+// `epochs`; Extend opens the wallet only for an amount whose quote the user has been shown. A quote is
+// an estimate (labelled `≈`): the wallet and the chain still decide the amount actually paid.
+import { ref } from 'vue'
+
+export type ExtendQuote =
+  | { epochs: number; state: 'ready'; costFrost: bigint }
+  | { epochs: number; state: 'unavailable'; costFrost: null }
+
+/** Cost in FROST of storing `size` bytes for `epochs`, or `null` when it cannot be priced. */
+export type EstimateExtendCost = (size: number, epochs: number) => Promise<bigint | null>
+
+export function useExtendQuotes(estimate: EstimateExtendCost) {
+  /** Latest quote per Blob object id (one per row). */
+  const quotes = ref<Record<string, ExtendQuote>>({})
+  const pricing = ref<Record<string, number>>({})
+  /** Per-row request counter: an older answer never replaces a newer amount's quote. */
+  const tokens: Record<string, number> = {}
+
+  /** Price `epochs` for the row; resolves to its quote, or `null` if a newer request replaced this one. */
+  async function price(id: string, size: number, epochs: number): Promise<ExtendQuote | null> {
+    const token = (tokens[id] = (tokens[id] ?? 0) + 1)
+    pricing.value = { ...pricing.value, [id]: epochs }
+    let cost: bigint | null
+    try {
+      cost = await estimate(size, epochs)
+    } catch {
+      cost = null
+    }
+    if (tokens[id] !== token) return null
+    const rest = { ...pricing.value }
+    delete rest[id]
+    pricing.value = rest
+    const quote: ExtendQuote =
+      cost === null ? { epochs, state: 'unavailable', costFrost: null } : { epochs, state: 'ready', costFrost: cost }
+    quotes.value = { ...quotes.value, [id]: quote }
+    return quote
+  }
+
+  /** The row's quote, only if it is for exactly `epochs` (an older amount's quote is not shown). */
+  function quoteFor(id: string, epochs: number | undefined): ExtendQuote | null {
+    const q = quotes.value[id]
+    return q && q.epochs === epochs ? q : null
+  }
+
+  /**
+   * Whether Extend may open the wallet now: only when the quote for `epochs` has been shown. If it has
+   * not (the seeded default, or a price still loading), it is fetched now, so the user sees the cost
+   * and presses Extend again — never a wallet prompt for an unpriced amount.
+   */
+  async function shownBeforeSigning(id: string, size: number, epochs: number): Promise<boolean> {
+    if (quoteFor(id, epochs)) return true
+    await price(id, size, epochs)
+    return false
+  }
+
+  /** Forget the row's quote (after its blob was extended, the next Extend is priced afresh). */
+  function clear(id: string): void {
+    tokens[id] = (tokens[id] ?? 0) + 1
+    const q = { ...quotes.value }
+    delete q[id]
+    quotes.value = q
+    const p = { ...pricing.value }
+    delete p[id]
+    pricing.value = p
+  }
+
+  return { quotes, pricing, price, quoteFor, shownBeforeSigning, clear }
+}

package/src/composables/useOwnedBlobs.ts

@@ -0,0 +1,91 @@
+// Module-singleton cache of the connected wallet's owned Walrus blobs.
+//
+// State lives at module scope (not inside the composable factory) so it is shared across every
+// `MyBlobs` mount in the session: switching the Upload/My-Blobs tabs — or navigating the whole
+// tool view in and out inline in the dashboard — no longer loses the list or forces a refetch.
+// `load()` is a no-op when the list is already loaded for the given address on the active network,
+// unless `force` is set
+// (used after an upload/extend, which can create or mutate on-chain blobs).
+import { ref } from 'vue'
+import type { OwnedBlob } from '@meddleware/walrus-storage-client'
+// Lightweight URL import — just the wasm asset URL (does not pull the walrus client eagerly).
+import walrusWasmUrl from '@mysten/walrus-wasm/web/walrus_wasm_bg.wasm?url'
+import { getSuiClient } from '../wallet.js'
+import { walrusNetwork } from '../config.js'
+
+const blobs = ref<OwnedBlob[]>([])
+const currentEpoch = ref(0)
+const loading = ref(false)
+const error = ref<string | null>(null)
+/** `<network>|<address>` the current `blobs` were fetched for; `null` until a successful load. */
+const loadedFor = ref<string | null>(null)
+
+/** Counts calls that decide what the list shows; a result is applied only if it is still the latest. */
+let latest = 0
+/** Key of the load in flight (the latest one), or `null` when none is. */
+let inflightKey: string | null = null
+
+/** Drop whatever load is in flight: its result will be discarded and it no longer owns `loading`. */
+function supersede(): void {
+  latest++
+  inflightKey = null
+  loading.value = false
+}
+
+async function load(address: string | null, opts: { force?: boolean } = {}): Promise<void> {
+  const net = walrusNetwork.value
+  if (!address || !net) {
+    supersede()
+    blobs.value = []
+    loadedFor.value = null
+    return
+  }
+  // Skip refetch when we already have this address's list and the last load succeeded.
+  const key = `${net}|${address}`
+  if (!opts.force && loadedFor.value === key && error.value === null) {
+    // Switching back to a list we hold: a slower load for another account or network must not land.
+    if (inflightKey !== null && inflightKey !== key) supersede()
+    return
+  }
+  if (loadedFor.value !== key) {
+    // Never show another network's or wallet's list; and a cleared list must not read as loaded.
+    blobs.value = []
+    loadedFor.value = null
+  }
+
+  const mine = ++latest
+  inflightKey = key
+  loading.value = true
+  error.value = null
+  try {
+    const { createWalrusClient, fetchOwnedWalrusBlobs } = await import('@meddleware/walrus-storage-client')
+    const suiClient = getSuiClient()
+    const walrusClient = createWalrusClient({ network: net, wasmUrl: walrusWasmUrl })
+    // Blob `endEpoch` is a WALRUS epoch, so compare against the Walrus committee epoch — NOT the
+    // Sui system-state epoch (they are different clocks; the Sui epoch, ~1218 vs ~570, made every
+    // blob read as "expired").
+    const [sys, fetched] = await Promise.all([
+      walrusClient.walrus.systemState(),
+      fetchOwnedWalrusBlobs(suiClient, walrusClient, address),
+    ])
+    // A newer load (or a switch) took over while this one was in flight: its answer is for another
+    // account or network, so drop it without touching the list, the error or `loading`.
+    if (mine !== latest) return
+    currentEpoch.value = Number(sys.committee.epoch)
+    blobs.value = fetched.sort((a: OwnedBlob, b: OwnedBlob) => a.endEpoch - b.endEpoch)
+    loadedFor.value = key
+  } catch (e) {
+    if (mine !== latest) return
+    error.value = e instanceof Error ? e.message : String(e)
+  } finally {
+    if (mine === latest) {
+      loading.value = false
+      inflightKey = null
+    }
+  }
+}
+
+/** Reactive access to the shared owned-blobs cache and its loader. */
+export function useOwnedBlobs() {
+  return { blobs, currentEpoch, loading, error, loadedFor, load }
+}

package/src/config.ts

@@ -0,0 +1,87 @@
+// Configuration. The network is wallet-adapter's shared runtime selector (the standalone build
+// selects VITE_NETWORK in main.ts; embedded, the host's selector rules). Operator settings are
+// build-time VITE_* per network: relay hostnames default to the public Mysten relay (set
+// VITE_WALRUS_RELAY_* to your operator relay to collect the tip); the access gate is optional
+// (unset ⇒ ungated), and its package + PlatformConfig come from the published deployment; the
+// purchase price and payees are read from the chain, never configured.
+import { computed } from 'vue'
+import type { WalrusNetwork, RelayGateConfig } from '@meddleware/walrus-storage-kit'
+import { relayGateConfig } from '@meddleware/walrus-storage-kit'
+import { useNetwork } from '@meddleware/wallet-adapter'
+
+/** Build-time env bag. Injectable on the env-reading helpers below purely so unit tests can exercise
+ *  each branch without depending on Vite's (frozen) `import.meta.env` inlining. */
+export type EnvSource = Record<string, string | undefined>
+
+const env: EnvSource = (import.meta as unknown as { env?: EnvSource }).env ?? {}
+
+/** The active network (read-only ref). */
+export const network = useNetwork().network
+
+/** The active network as a Walrus network, or null where Walrus has none (e.g. localnet). */
+export const walrusNetwork = computed<WalrusNetwork | null>(() =>
+  network.value === 'testnet' || network.value === 'mainnet' ? network.value : null,
+)
+
+/** Public Mysten relays — the fallback when no operator relay is configured. */
+export const PUBLIC_WALRUS_RELAY_HOSTS: Record<WalrusNetwork, string> = {
+  testnet: 'https://upload-relay.testnet.walrus.space',
+  mainnet: 'https://upload-relay.mainnet.walrus.space',
+}
+
+/** Operator relay host per network (env → public fallback). */
+export const OPERATOR_RELAY_HOSTS: Record<WalrusNetwork, string> = {
+  testnet: env.VITE_WALRUS_RELAY_TESTNET || PUBLIC_WALRUS_RELAY_HOSTS.testnet,
+  mainnet: env.VITE_WALRUS_RELAY_MAINNET || PUBLIC_WALRUS_RELAY_HOSTS.mainnet,
+}
+
+/** The operator/public host pair for `useWalrusRelay`. */
+export function relayHosts(network: WalrusNetwork): { operator: string; public: string } {
+  return { operator: OPERATOR_RELAY_HOSTS[network], public: PUBLIC_WALRUS_RELAY_HOSTS[network] }
+}
+
+/**
+ * Walruscan explorer URL for a blob. A Walrus blob id is not a Sui object, so it links to the
+ * Walrus-native explorer rather than a Sui explorer (SuiVision handles Sui entities elsewhere).
+ */
+export function walruscanBlobUrl(network: WalrusNetwork, blobId: string): string {
+  return `https://walruscan.com/${network}/blob/${blobId}`
+}
+
+/**
+ * Default relay tip ceiling (MIST) when `VITE_UPLOAD_RELAY_MAX_TIP_MIST` is unset: 0.005 SUI, the
+ * workspace-wide ceiling (~8× the operator relay's worst-case tip at the 100 MiB edge cap).
+ */
+export const DEFAULT_UPLOAD_RELAY_MAX_TIP_MIST = 5_000_000
+
+/**
+ * Cap on the relay tip payment in MIST, from `VITE_UPLOAD_RELAY_MAX_TIP_MIST`. This is a ceiling to
+ * prevent overpayment (the relay asks for the minimum), NOT a fixed charge. A non-positive or
+ * unparseable value falls back to {@link DEFAULT_UPLOAD_RELAY_MAX_TIP_MIST}.
+ */
+export function uploadRelayMaxTipMist(envSource: EnvSource = env): number {
+  const parsed = Number(envSource.VITE_UPLOAD_RELAY_MAX_TIP_MIST)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_UPLOAD_RELAY_MAX_TIP_MIST
+}
+
+/**
+ * The optional NFT access gate for a network: the operator supplies only the Gate id and soulbound
+ * flag (`VITE_ACCESS_GATE_*_{NET}`); `relayGateConfig` fixes the package and `PlatformConfig` to the
+ * published deployment (commission enforcement), and the price is read from the gate on the chain.
+ * `null` — an ungated
+ * relay — when no gate id is set, or when no access_gate deployment is recorded for the network.
+ */
+export function accessGate(network: WalrusNetwork, envSource: EnvSource = env): RelayGateConfig | null {
+  const NET = network.toUpperCase()
+  const gateId = envSource[`VITE_ACCESS_GATE_ID_${NET}`]
+  if (!gateId) return null
+  try {
+    return relayGateConfig(network, {
+      gateId,
+      soulbound: envSource[`VITE_ACCESS_GATE_SOULBOUND_${NET}`] === 'true',
+    })
+  } catch (e) {
+    console.warn(`[walrus-storage-ui] access gate for ${network} disabled: ${e instanceof Error ? e.message : String(e)}`)
+    return null
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+  export default component
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// @meddleware/walrus-storage-ui — library entry.
+//
+// Exports the core Walrus tool view (no app shell) for inline embedding in the dashboard.
+// The standalone SPA (App.vue + main.ts) is unaffected and still builds/deploys as before.
+//
+// Consumers must import the shared design tokens + UI base once at their entry:
+//   import '@meddleware/design-tokens/tokens.css'
+//   import '@meddleware/ui/base.css'
+
+export { default as WalrusStorageView } from './components/WalrusStorageView.vue'

package/src/main.ts

@@ -0,0 +1,16 @@
+import '@meddleware/design-tokens/tokens.css'
+import '@meddleware/design-tokens/seasons.css'
+import '@meddleware/ui/base.css'
+import { createApp } from 'vue'
+import { useSeason } from '@meddleware/ui'
+import { useNetwork } from '@meddleware/wallet-adapter'
+import App from './App.vue'
+
+// The standalone build targets one network; select it in the shared selector so the client, the
+// relay, the gate and the stored resume keys all agree. (Embedded, the host's selector rules.)
+const env = (import.meta as unknown as { env?: Record<string, string | undefined> }).env ?? {}
+const built = env.VITE_NETWORK || 'testnet'
+if (built === 'testnet' || built === 'mainnet') useNetwork().setNetwork(built)
+
+useSeason()
+createApp(App).mount('#app')