@aryacode/dsh-aryacode-polish 0.2.4 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## [0.3.5] - 2026-10-27
+
+### Fixed
+
+- **The card's own page described an older plugin.** The README that ships in the
+  tarball *is* the page body in the Plugins market, and it still said "0.2.0, one
+  feature shipped" and listed a layout directory that does not exist. Status,
+  layout, and requirements now match the package.
+
+### Changed
+
+- `HANDOFF.md` was rewritten for the shipped bundle: the contracts that cost time
+  (a row's config namespace is the row id, not the slot key; no bundler for the
+  face; the client session contract exposes no events), the slot geography around
+  the account row, the development loop, and the release order that keeps the
+  catalogue record. `test/docs.spec.mjs` now fails if the briefing drifts back to
+  the stale claims it once made.
+
+## [0.3.4] - 2026-10-27
+
+### Added
+
+- **The bundle says which Harness it runs on.** `dsh.engines.dsh` is now declared
+  (`^0.2.1-rc.3`, the revision the two surfaces were verified against), so the
+  market can read the requirement instead of labelling the card "Host requirement
+  unknown", and an install onto an older Host can be refused rather than failing
+  at mount time. `test/manifests.spec.mjs` keeps the field present and semver.
+
+## [0.3.3] - 2026-10-27
+
+### Fixed
+
+- **The balance read could wait forever.** When the Host withheld the
+  `account/watch` grant, the read's promise never settled: the callback never
+  ran, so nothing resolved and the line silently stayed empty for the life of the
+  page. The read now carries a timeout and also starts its call before the
+  effect's yielded disposer, so an effect runner that stops at the first yield
+  still performs it. `test/account.spec.mjs` pins all seven refusal paths.
+
+### Changed
+
+- The read itself moved into `client/account.js`, beside `client/money.js`, for
+  the same reason: the build inlines it into the browser bundle and the spec
+  imports the same source.
+
+## [0.3.2] - 2026-10-27
+
+### Changed
+
+- **The balance decisions are testable.** Which wallet a line shows, and how the
+  amount is rendered (currency symbol, two decimals, unparseable values shown
+  verbatim), moved into `client/money.js`. The build inlines that file into
+  `lib/client.js`, so `test/money.spec.mjs` covers the exact source the browser
+  runs instead of a copy.
+
+## [0.3.1] - 2026-10-27
+
+### Fixed
+
+- **The balance line had no observable mount point.** When the account exposed no
+  wallet it rendered `null`, which is correct for the user but indistinguishable
+  from "the surface was never registered" for anyone verifying the build. The
+  component now always renders its wrapper (`data-polish-balance="empty"`, hidden)
+  and fills it with the amount only when the Host returns one.
+
+## [0.3.0] - 2026-10-27
+
+### Added
+
+- **Remaining account balance in the sidebar foot.** A line above the account row
+  shows the account's own wallet (`$17.33`), read once through a
+  `remoteAccess.whenAccess('account/watch', …)` grant so the call is allowed and
+  the grant is released as soon as the read settles. It renders nothing at all
+  when the switch is off, when the Host exposes no wallet, or when the read is
+  refused — an empty line beats a number the Host did not give us.
+- **A second switch, `accountBalance`.** It is declared once in
+  `entries/registry.js` and once in `client/switches.json`, exactly like the cost
+  switch, so the Configure page grows it automatically.
+
+### Notes
+
+- The line sits in `sidebar.footer.action`, the one documented seat in the
+  sidebar foot. It renders *above* the account row, because
+  `SidebarRoot.tsx:405-411` puts `footerActions` before `settingsArea`; the only
+  seat below the login would be `settings.launcher`, which means shadowing the
+  account row and its whole menu.
+
 ## [0.2.4] - 2026-10-27
 
 ### Changed

package/README.md

@@ -7,7 +7,8 @@ installed into and patches nothing. It is one package, one Plugins row, and one
 switch per feature, so a refinement that turns out to be wrong for a machine can
 be turned off without uninstalling anything.
 
-Status: **0.2.0.** One feature shipped: the estimated session cost pill.
+Status: **0.3.4.** Two features shipped and released: the estimated session cost
+pill and the account balance line.
 
 ## What it is
 
@@ -30,6 +31,7 @@ Configure page automatically.
 | Switch | Default | What it does |
 | --- | --- | --- |
 | **Estimated session cost** (`sessionCost`) | On | A `≈$0.39` pill in the composer dock that opens a breakdown card — cache hit, uncached input, cached input, output, requests, and the estimate — priced from the session's recorded usage at the published DeepSeek rates. |
+| **Account balance** (`accountBalance`) | On | The account's remaining wallet (`$17.33`) in the sidebar foot, above the account row. Renders nothing when the Host exposes no wallet, so it never shows a number nobody gave it. |
 
 ### How the cost is computed
 
@@ -91,6 +93,8 @@ node --import tsx/esm apps/cli/src/bin.ts plugin --profile web add <path-to-tgz>
 
 ## Requirements
 
+- AryaCode `^0.2.1-rc.3` (declared as `dsh.engines.dsh`; the revision both
+  surfaces were verified against).
 - AryaCode with the Cordis plugin API (`@deepseek-ai/cordis ~4.0.4`).
 - Node `^22.19.0 || >=24.0.0` to build from source.
 
@@ -113,10 +117,11 @@ entries/polish.js    the row: Config derived from the registry, apply()
 entries/registry.js  the feature list — the one place a feature is declared
 entries/usage.js     the fold: model-attributed usage out of the session log
 entries/cost.js      the polishCost projection: rates, pricing, host mount
-entries/features/    one module per feature
 entries/config.js    volatile-reference accessors (resolve/flag/list/text)
 lib/index.js         mount point re-exporting the row
 client/face.js       browser face source: the Configure page and every surface
+client/money.js      which wallet is shown, and how the amount is rendered
+client/account.js    the granted, timeout-bounded balance read
 client/switches.json the browser half of the seam — one entry per switch
 scripts/build-client.mjs  wraps client/face.js into lib/client.js
 lib/client.js        generated: the bundle the Shell loads

package/client/account.js

@@ -0,0 +1,96 @@
+/**
+ * Reading the account balance from a plugin face.
+ *
+ * The account Remote methods are gated, so the read runs inside a
+ * `remoteAccess.whenAccess('account/watch', …)` grant and the grant is released
+ * as soon as the read settles. Every failure — no service in this Shell, a
+ * refused grant, a failed call — resolves to `undefined` instead of throwing: a
+ * sidebar line is never worth breaking the shell over, and a line that stays
+ * empty is honest about a number it never received.
+ *
+ * This module is inlined into `lib/client.js` by `scripts/build-client.mjs` and
+ * imported directly by `test/account.spec.mjs`, so the tested source is the one
+ * the browser runs.
+ */
+
+/**
+ * Build the account request identity for one balance read.
+ *
+ * The shipped account bundle inlines `DSH_CLIENT_VERSION` at build time; a plugin
+ * bundle has no such define, so the build stamps this package's own version and
+ * prefers the shell's value when one is inlined.
+ *
+ * @param version - the version this build stamps.
+ * @returns the metadata the account Remote methods carry.
+ */
+export function clientMetadata(version) {
+  const stamped = typeof process !== 'undefined' && process.env !== undefined ? process.env.DSH_CLIENT_VERSION : undefined
+  return {
+    version: typeof stamped === 'string' && stamped !== '' ? stamped : version,
+    locale: typeof navigator !== 'undefined' && typeof navigator.language === 'string' && navigator.language !== ''
+      ? navigator.language
+      : 'en',
+    timezoneOffsetSeconds: -new Date().getTimezoneOffset() * 60,
+  }
+}
+
+/**
+ * Build the one-shot balance reader.
+ *
+ * @param ctx - the browser plugin context; `ctx.get` resolves an optional service.
+ * @param version - the version this build stamps into the account metadata.
+ * @returns a reader that resolves to the balance view, or undefined when unavailable.
+ */
+export function makeBalanceReader(ctx, version, { timeoutMs = 10000 } = {}) {
+  const service = name => {
+    try {
+      return ctx.get(name)
+    } catch {
+      return undefined
+    }
+  }
+  return async () => {
+    const access = service('remoteAccess')
+    const remote = service('remote')
+    if (access === undefined || remote === undefined) return undefined
+    const metadata = clientMetadata(version)
+    return await new Promise(resolve => {
+      let settled = false
+      let stop
+      const timer = setTimeout(() => finish(undefined), timeoutMs)
+      const finish = value => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        resolve(value)
+        if (typeof stop === 'function') {
+          try {
+            stop()
+          } catch {
+            /* the grant may already have been released */
+          }
+        }
+      }
+      // The read starts before the yield so an effect runner that stops at the
+      // first yielded disposer still performs the call.
+      stop = access.whenAccess('account/watch', function* () {
+        void (async () => {
+          try {
+            const result = await remote.account.getBalance(metadata)
+            const value = result !== undefined && result.ok === true ? result.value : undefined
+            finish(value !== undefined && value.status === 'ready' ? value : undefined)
+          } catch {
+            finish(undefined)
+          }
+        })()
+        yield () => {
+          if (!settled) {
+            settled = true
+            clearTimeout(timer)
+            resolve(undefined)
+          }
+        }
+      })
+    })
+  }
+}

package/client/face.js

@@ -313,6 +313,60 @@ function CostPill(props) {
     : null)
 }
 
+/**
+ * The remaining-balance line in the sidebar foot.
+ *
+ * It renders nothing at all when the switch is off, the account exposes no
+ * wallet, or the read was refused — an empty line is better than a line that
+ * claims a number the Host did not give us.
+ *
+ * @param props - the slot's `wide` flag, our lazy `configForms`, and the balance reader.
+ * @returns the balance line, or null.
+ */
+function BalanceLine(props) {
+  const enabled = useSwitch(props.configForms, 'accountBalance', true)
+  const [wallet, setWallet] = React.useState(undefined)
+  const read = props.loadBalance
+  React.useEffect(() => {
+    if (!enabled || typeof read !== 'function') return undefined
+    let live = true
+    Promise.resolve()
+      .then(() => read())
+      .then(view => {
+        if (live) setWallet(walletOf(view))
+      }, () => {
+        if (live) setWallet(undefined)
+      })
+    return () => {
+      live = false
+    }
+  }, [enabled, read])
+  if (!enabled) return null
+  // The wrapper stays in the DOM even when there is no number to show, so a
+  // reader (and the verification script) can tell "registered but empty" from
+  // "not registered at all". An empty flex line costs the layout nothing.
+  if (wallet === undefined) {
+    return React.createElement('div', { 'data-polish-balance': 'empty', style: { display: 'none' } })
+  }
+  const money = formatBalance(wallet)
+  return React.createElement('div', {
+    title: 'Remaining account balance',
+    style: {
+      display: 'flex',
+      alignItems: 'center',
+      gap: '6px',
+      padding: '2px 8px 4px',
+      fontSize: '12px',
+      lineHeight: '16px',
+      minWidth: 0,
+      overflow: 'hidden',
+      whiteSpace: 'nowrap',
+      textOverflow: 'ellipsis',
+      opacity: 0.75,
+    },
+  }, props.wide === false ? money : 'Balance ' + money)
+}
+
 return {
   inject: ['slots'],
   /**
@@ -338,5 +392,12 @@ return {
       order: 2,
       inject: () => ({ configForms }),
     }, CostPill))
+    const loadBalance = makeBalanceReader(ctx, CLIENT_VERSION)
+    ctx.slots.inject('sidebar.footer.action', () => ctx.slots.register({
+      name: 'sidebar.footer.action',
+      id: 'polish-balance',
+      order: 3,
+      inject: () => ({ configForms, loadBalance }),
+    }, BalanceLine))
   },
 }

package/client/money.js

@@ -0,0 +1,31 @@
+/**
+ * The two pure decisions behind the balance line: which wallet to show, and how
+ * to render it.
+ *
+ * They live in their own file because the browser face bundle is only ever run
+ * inside the Shell, where nothing can be imported and asserted — so the build
+ * inlines this module into `lib/client.js` (with the `export` keywords dropped)
+ * while `test/money.spec.mjs` imports it directly. What the test covers is
+ * therefore the same source the browser runs, not a copy of it.
+ */
+
+/**
+ * Pick the wallet a balance line should show.
+ * @param view - the balance view the account Remote returned.
+ * @returns the first wallet carrying a balance, or undefined when the view has none.
+ */
+export function walletOf(view) {
+  if (view === undefined || view === null || view.status !== 'ready' || !Array.isArray(view.value)) return undefined
+  return view.value.find(wallet => wallet !== null && typeof wallet === 'object' && typeof wallet.balance === 'string')
+}
+
+/**
+ * Format one wallet as money.
+ * @param wallet - a wallet with `currency` and `balance`.
+ * @returns the amount with its currency symbol, at two decimals.
+ */
+export function formatBalance(wallet) {
+  const symbol = wallet.currency === 'CNY' ? '\u00A5' : '$'
+  const amount = Number(wallet.balance)
+  return Number.isFinite(amount) ? symbol + amount.toFixed(2) : symbol + String(wallet.balance)
+}

package/client/switches.json

@@ -6,6 +6,12 @@
       "label": "Estimated session cost",
       "description": "Show what the open session has cost so far, priced from recorded usage at the published DeepSeek rates.",
       "defaultOn": true
+    },
+    {
+      "key": "accountBalance",
+      "label": "Account balance",
+      "description": "Show the remaining account balance in the sidebar foot, above the account row.",
+      "defaultOn": true
     }
   ]
 }

package/entries/registry.js

@@ -40,6 +40,12 @@ export const features = [
     defaultOn: true,
     mount: mountCost,
   },
+  {
+    id: 'accountBalance',
+    label: 'Account balance',
+    description: 'Show the remaining account balance in the sidebar foot, above the account row.',
+    defaultOn: true,
+  },
 ]
 
 /**

package/lib/client.js

@@ -13,10 +13,146 @@ window.__ModuleLoader__.load({
         "label": "Estimated session cost",
         "description": "Show what the open session has cost so far, priced from recorded usage at the published DeepSeek rates.",
         "defaultOn": true
+      },
+      {
+        "key": "accountBalance",
+        "label": "Account balance",
+        "description": "Show the remaining account balance in the sidebar foot, above the account row.",
+        "defaultOn": true
       }
     ]
     const ROW_ID = "polish"
     const ROW_KEY = "@aryacode/dsh-aryacode-polish" + '#' + ROW_ID
+    const CLIENT_VERSION = "0.3.5"
+
+    /**
+     * The two pure decisions behind the balance line: which wallet to show, and how
+     * to render it.
+     *
+     * They live in their own file because the browser face bundle is only ever run
+     * inside the Shell, where nothing can be imported and asserted — so the build
+     * inlines this module into `lib/client.js` (with the `export` keywords dropped)
+     * while `test/money.spec.mjs` imports it directly. What the test covers is
+     * therefore the same source the browser runs, not a copy of it.
+     */
+
+    /**
+     * Pick the wallet a balance line should show.
+     * @param view - the balance view the account Remote returned.
+     * @returns the first wallet carrying a balance, or undefined when the view has none.
+     */
+    function walletOf(view) {
+      if (view === undefined || view === null || view.status !== 'ready' || !Array.isArray(view.value)) return undefined
+      return view.value.find(wallet => wallet !== null && typeof wallet === 'object' && typeof wallet.balance === 'string')
+    }
+
+    /**
+     * Format one wallet as money.
+     * @param wallet - a wallet with `currency` and `balance`.
+     * @returns the amount with its currency symbol, at two decimals.
+     */
+    function formatBalance(wallet) {
+      const symbol = wallet.currency === 'CNY' ? '\u00A5' : '$'
+      const amount = Number(wallet.balance)
+      return Number.isFinite(amount) ? symbol + amount.toFixed(2) : symbol + String(wallet.balance)
+    }
+
+    /**
+     * Reading the account balance from a plugin face.
+     *
+     * The account Remote methods are gated, so the read runs inside a
+     * `remoteAccess.whenAccess('account/watch', …)` grant and the grant is released
+     * as soon as the read settles. Every failure — no service in this Shell, a
+     * refused grant, a failed call — resolves to `undefined` instead of throwing: a
+     * sidebar line is never worth breaking the shell over, and a line that stays
+     * empty is honest about a number it never received.
+     *
+     * This module is inlined into `lib/client.js` by `scripts/build-client.mjs` and
+     * imported directly by `test/account.spec.mjs`, so the tested source is the one
+     * the browser runs.
+     */
+
+    /**
+     * Build the account request identity for one balance read.
+     *
+     * The shipped account bundle inlines `DSH_CLIENT_VERSION` at build time; a plugin
+     * bundle has no such define, so the build stamps this package's own version and
+     * prefers the shell's value when one is inlined.
+     *
+     * @param version - the version this build stamps.
+     * @returns the metadata the account Remote methods carry.
+     */
+    function clientMetadata(version) {
+      const stamped = typeof process !== 'undefined' && process.env !== undefined ? process.env.DSH_CLIENT_VERSION : undefined
+      return {
+        version: typeof stamped === 'string' && stamped !== '' ? stamped : version,
+        locale: typeof navigator !== 'undefined' && typeof navigator.language === 'string' && navigator.language !== ''
+          ? navigator.language
+          : 'en',
+        timezoneOffsetSeconds: -new Date().getTimezoneOffset() * 60,
+      }
+    }
+
+    /**
+     * Build the one-shot balance reader.
+     *
+     * @param ctx - the browser plugin context; `ctx.get` resolves an optional service.
+     * @param version - the version this build stamps into the account metadata.
+     * @returns a reader that resolves to the balance view, or undefined when unavailable.
+     */
+    function makeBalanceReader(ctx, version, { timeoutMs = 10000 } = {}) {
+      const service = name => {
+        try {
+          return ctx.get(name)
+        } catch {
+          return undefined
+        }
+      }
+      return async () => {
+        const access = service('remoteAccess')
+        const remote = service('remote')
+        if (access === undefined || remote === undefined) return undefined
+        const metadata = clientMetadata(version)
+        return await new Promise(resolve => {
+          let settled = false
+          let stop
+          const timer = setTimeout(() => finish(undefined), timeoutMs)
+          const finish = value => {
+            if (settled) return
+            settled = true
+            clearTimeout(timer)
+            resolve(value)
+            if (typeof stop === 'function') {
+              try {
+                stop()
+              } catch {
+                /* the grant may already have been released */
+              }
+            }
+          }
+          // The read starts before the yield so an effect runner that stops at the
+          // first yielded disposer still performs the call.
+          stop = access.whenAccess('account/watch', function* () {
+            void (async () => {
+              try {
+                const result = await remote.account.getBalance(metadata)
+                const value = result !== undefined && result.ok === true ? result.value : undefined
+                finish(value !== undefined && value.status === 'ready' ? value : undefined)
+              } catch {
+                finish(undefined)
+              }
+            })()
+            yield () => {
+              if (!settled) {
+                settled = true
+                clearTimeout(timer)
+                resolve(undefined)
+              }
+            }
+          })
+        })
+      }
+    }
 
     /**
      * AryaCode Polish — the browser face.
@@ -333,6 +469,60 @@ window.__ModuleLoader__.load({
         : null)
     }
 
+    /**
+     * The remaining-balance line in the sidebar foot.
+     *
+     * It renders nothing at all when the switch is off, the account exposes no
+     * wallet, or the read was refused — an empty line is better than a line that
+     * claims a number the Host did not give us.
+     *
+     * @param props - the slot's `wide` flag, our lazy `configForms`, and the balance reader.
+     * @returns the balance line, or null.
+     */
+    function BalanceLine(props) {
+      const enabled = useSwitch(props.configForms, 'accountBalance', true)
+      const [wallet, setWallet] = React.useState(undefined)
+      const read = props.loadBalance
+      React.useEffect(() => {
+        if (!enabled || typeof read !== 'function') return undefined
+        let live = true
+        Promise.resolve()
+          .then(() => read())
+          .then(view => {
+            if (live) setWallet(walletOf(view))
+          }, () => {
+            if (live) setWallet(undefined)
+          })
+        return () => {
+          live = false
+        }
+      }, [enabled, read])
+      if (!enabled) return null
+      // The wrapper stays in the DOM even when there is no number to show, so a
+      // reader (and the verification script) can tell "registered but empty" from
+      // "not registered at all". An empty flex line costs the layout nothing.
+      if (wallet === undefined) {
+        return React.createElement('div', { 'data-polish-balance': 'empty', style: { display: 'none' } })
+      }
+      const money = formatBalance(wallet)
+      return React.createElement('div', {
+        title: 'Remaining account balance',
+        style: {
+          display: 'flex',
+          alignItems: 'center',
+          gap: '6px',
+          padding: '2px 8px 4px',
+          fontSize: '12px',
+          lineHeight: '16px',
+          minWidth: 0,
+          overflow: 'hidden',
+          whiteSpace: 'nowrap',
+          textOverflow: 'ellipsis',
+          opacity: 0.75,
+        },
+      }, props.wide === false ? money : 'Balance ' + money)
+    }
+
     return {
       inject: ['slots'],
       /**
@@ -358,6 +548,13 @@ window.__ModuleLoader__.load({
           order: 2,
           inject: () => ({ configForms }),
         }, CostPill))
+        const loadBalance = makeBalanceReader(ctx, CLIENT_VERSION)
+        ctx.slots.inject('sidebar.footer.action', () => ctx.slots.register({
+          name: 'sidebar.footer.action',
+          id: 'polish-balance',
+          order: 3,
+          inject: () => ({ configForms, loadBalance }),
+        }, BalanceLine))
       },
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aryacode/dsh-aryacode-polish",
-  "version": "0.2.4",
+  "version": "0.3.5",
   "description": "AryaCode Polish: one install for the small things that make AryaCode feel finished. One Plugins row, one switch per quality-of-life feature.",
   "keywords": [
     "dsh",
@@ -43,8 +43,16 @@
     },
     "client": {
       "platform": "web"
+    },
+    "engines": {
+      "dsh": "^0.2.1-rc.3"
     }
   },
+  "scripts": {
+    "build:client": "node scripts/build-client.mjs",
+    "prepack": "node scripts/build-client.mjs",
+    "test": "node --test test/patch.spec.mjs test/config.spec.mjs test/registry.spec.mjs test/cost.spec.mjs test/money.spec.mjs test/account.spec.mjs test/docs.spec.mjs test/manifests.spec.mjs test/client-face.spec.mjs"
+  },
   "dependencies": {
     "zod": "^4.4.3"
   },
@@ -63,9 +71,5 @@
     "./package.json": "./package.json",
     "./client": "./lib/client.js",
     "./polish": "./entries/polish.js"
-  },
-  "scripts": {
-    "build:client": "node scripts/build-client.mjs",
-    "test": "node --test test/patch.spec.mjs test/config.spec.mjs test/registry.spec.mjs test/cost.spec.mjs test/docs.spec.mjs test/manifests.spec.mjs test/client-face.spec.mjs"
   }
-}
+}