uniweb 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/kit": "^0.13.7",
     "@uniweb/core": "^0.13.0",
-    "@uniweb/semantic-parser": "^1.3.1",
-    "@uniweb/runtime": "^0.13.0"
+    "@uniweb/runtime": "^0.13.0",
+    "@uniweb/kit": "^0.13.7",
+    "@uniweb/semantic-parser": "^1.3.1"
   },
   "peerDependencies": {
-    "@uniweb/semantic-parser": "^1.3.1",
-    "@uniweb/build": "^0.27.0",
-    "@uniweb/content-reader": "^1.2.4"
+    "@uniweb/build": "^0.28.0",
+    "@uniweb/content-reader": "^1.2.4",
+    "@uniweb/semantic-parser": "^1.3.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/src/backend/client.js

@@ -537,28 +537,6 @@ export class BackendClient {
     }
   }
 
-  /**
-   * ASSUMED endpoint (not built yet).
-   * GET /dev/site/{uuid}/can-go-live — the pre-go-live payment gate:
-   *   { ok: true }                                          // already paid → proceed
-   *   { payment_required: true, checkout_url, wait_token? } // open the URL, settle, retry
-   * The framework is provider-agnostic: it only opens `checkout_url` and waits.
-   * null on 404 / any failure → the caller PROCEEDS (degrade: publish ships
-   * before payment lands; same posture as siteStatus on a missing route).
-   * @param {string} uuid - the site-content uuid
-   * @returns {Promise<object|null>}
-   */
-  async canGoLive(uuid) {
-    try {
-      const res = await this.request(
-        `/dev/site/${encodeURIComponent(uuid)}/can-go-live`
-      )
-      return res.ok ? await res.json().catch(() => null) : null
-    } catch {
-      return null
-    }
-  }
-
   /**
    * Deliver a site's processed assets (plan → PUT-per-file) to the backend's
    * content-addressed store. Thin pass-through to utils/asset-upload.js with this

package/src/backend/payment-handoff.js

@@ -1,124 +1,160 @@
 /**
- * Payment handoff — the one piece of `uniweb publish` that's three-way
- * (framework + backend + the `uniweb.app` web app). Design: payment-handoff-plan.md.
+ * Payment refusal — what `uniweb publish` does when the backend says a site
+ * cannot go live until it is paid for.
  *
- * The intent: `uniweb publish` on an unpaid (or newly-charged) site should just
- * handle it — open a browser to `uniweb.app`, let the user pay, and continue.
- * An already-paid site never opens a browser.
+ * THE BACKEND IS THE ONLY GATE. It evaluates on every publish, on every
+ * backend, whatever that deployment is configured to require — a backend with
+ * subscriptions switched off simply never refuses. The CLI holds no opinion about whether a
+ * backend charges and must never form one: it attempts the publish and reads
+ * the answer.
  *
- * The framework's ENTIRE payment knowledge is "open this URL, wait for done" —
- * PROVIDER-AGNOSTIC. The CLI opens whatever `checkout_url` the backend hands it;
- * the app drives the provider (Stripe or anything else) and settles with the
- * backend. We reuse `awaitBrowserCallback` (the same loopback `uniweb login`
- * uses) for the open + wait.
+ * ⛔ THERE IS NO PRE-FLIGHT, AND ADDING ONE BACK IS A REGRESSION. A
+ * `GET …/can-go-live` probe used to run before go-live; it called a route no
+ * backend serves, and it folded every failure — 404 included — into
+ * "proceed". A check that answers "fine" when it cannot reach the server is not
+ * a check, and it made the CLI assume a posture it has no business assuming. A
+ * pre-flight also cannot be authoritative: the backend re-evaluates at publish
+ * time regardless, so a second asker is a second producer of one decision.
  *
- * DEGRADES: when the backend exposes no can-go-live route (404 / any failure),
- * `canGoLive` returns null and we PROCEED — so publish ships before the payment
- * route lands (same posture as `status --remote` on a missing endpoint). Live
- * acceptance is the three-way test.
+ * WHAT THE CLI KNOWS ABOUT PAYMENT: nothing. It opens whatever settlement URL
+ * the backend hands it, VERBATIM — provider-agnostic, and route-agnostic. The
+ * app drives the provider and settles with the backend.
+ *
+ * ⛔ AND IT APPENDS NOTHING TO THAT URL. The old handoff added
+ * `redirect_uri=http://127.0.0.1:<port>/callback`, `state` and `wait_token`,
+ * then waited on a loopback for the app to redirect back. Two reasons it is
+ * gone: it obliged the web app to know a CLI exists and honour a callback, and
+ * a loopback callback requires the browser and the CLI
+ * on the SAME MACHINE, so over SSH or in a container it hung for its full
+ * timeout and then reported "payment was not completed", which was false.
  */
 
-import { randomBytes } from 'node:crypto'
-
-import { awaitBrowserCallback } from '../utils/registry-auth.js'
-import { isNonInteractive } from '../utils/interactive.js'
-
-// Append query params to a backend-supplied URL without disturbing its own.
-function withParams(url, params) {
-  const u = new URL(url)
-  for (const [k, v] of Object.entries(params)) {
-    if (v != null) u.searchParams.set(k, String(v))
-  }
-  return u.toString()
-}
+/** Reasons the CLI knows how to act on. An ALLOWLIST, never an inventory. */
+const ACTIONABLE_REASONS = new Set(['no_subscription'])
 
 /**
- * Settle payment for a site before go-live, if the backend says it's needed.
+ * Read a `402` from the publish call and decide what the CLI does. Pure — no
+ * network, no browser, no process exit — so the decision is testable on its own.
+ *
+ * ⛔ THE RULE, and it is a property of the wire rather than a CLI preference:
+ * NEVER route to a purchase surface from the ABSENCE of a recognised token. A
+ * purchase surface is opened by a `reason` that NAMES one; everything else
+ * surfaces the backend's own sentence and stops. Degrading that way means an
+ * older CLI shows you the message — annoying, honest, recoverable. Degrading
+ * the other way sends someone to a checkout for something they cannot buy.
+ *
+ * ⛔ Do NOT turn `ACTIONABLE_REASONS` into "every reason the backend has". The
+ * set is open by design and a stale copy here fails in the worst direction; an
+ * allowlist is safe precisely because what it misses lands on `stop`.
+ * ⛔ Do NOT parse `detail` — it is deliberately not asserted word-for-word, and
+ * `reason` exists to do the job parsing it would.
+ *
+ * NOTE ON `reason`'s PRESENCE: it is NOT guaranteed by the content type. A 402
+ * naming a condition the caller can act on carries one; nothing guarantees it
+ * in general — a declined card is `problem+json` and deliberately carries none,
+ * because there is no machine decision for a client to make about it. This reads `reason` when it is there and needs
+ * no invariant, which is why that correction cost this branch nothing.
  *
  * @param {object} o
- * @param {import('./client.js').BackendClient} o.client
- * @param {string|null} o.uuid - the site-content uuid (null only on a dry run; a
- *   real publish creates the site before anything uploads, so it is set by here)
- * @param {string[]} o.args
- * @param {object} o.say - { ok, info, warn, err, dim } reporters
- * @param {boolean} [o.dryRun]
- * @returns {Promise<{ proceed: boolean }>} proceed:false → the caller aborts go-live.
+ * @param {number} o.status - the HTTP status
+ * @param {string} [o.contentType] - the response's content-type header
+ * @param {string} [o.body] - the raw response body
+ * @returns {{ kind: 'not-payment' }
+ *          | { kind: 'settle', url: string, handle: string|null, reason: string, message: string|null }
+ *          | { kind: 'stop', reason: string|null, message: string|null }}
  */
-export async function settlePaymentIfNeeded({
-  client,
-  uuid,
-  args,
-  say,
-  dryRun = false
-}) {
-  // No uuid yet (a first publish mints it on push) → nothing to check here; the
-  // post-push go-live is the moment the backend gates on payment.
-  if (!uuid) return { proceed: true }
+export function readPaymentRefusal({ status, contentType = '', body = '' } = {}) {
+  if (status !== 402) return { kind: 'not-payment' }
+
+  let problem = null
+  try {
+    problem = JSON.parse(body)
+  } catch {
+    /* a non-JSON 402 is simply unrecognised — it falls to `stop` below */
+  }
+  if (!problem || typeof problem !== 'object') {
+    return { kind: 'stop', reason: null, message: null }
+  }
+
+  // The human sentence, in the backend's own words. `detail` is the 7807
+  // member; `title` is the fallback when a body carries no detail.
+  const message =
+    (typeof problem.detail === 'string' && problem.detail) ||
+    (typeof problem.title === 'string' && problem.title) ||
+    null
+
+  // `status` is NOT a discriminator: the backend's problem bodies carry it as
+  // the NUMBER 402 while at least one hand-built 402 elsewhere on their wire
+  // carries a STRING. Same key, two types, neither failing loudly — so this
+  // reads `reason` and the content type instead, and never `body.status`.
+  const isProblem = String(contentType).includes('application/problem+json')
+  const reason =
+    isProblem && typeof problem.reason === 'string' && problem.reason
+      ? problem.reason
+      : null
 
-  // Dry-run reports the intent WITHOUT touching the network — the can-go-live
-  // read is auth-gated and must not force a login on a dry-run.
-  if (dryRun) {
-    say.dim(
-      `Payment     : would check whether go-live needs payment for ${uuid}`
-    )
-    return { proceed: true }
+  if (!reason || !ACTIONABLE_REASONS.has(reason)) {
+    return { kind: 'stop', reason, message }
   }
 
-  const verdict = await client.canGoLive(uuid)
-  // Degrade (no route) or already-paid → proceed.
-  if (!verdict || verdict.ok || !verdict.payment_required)
-    return { proceed: true }
+  // Actionable — but only if the backend actually handed over somewhere to go.
+  // A recognised reason with no settlement block is a backend that has not
+  // built that half yet: still a stop, and still with its own sentence.
+  const s = problem.settlement
+  const url = s && typeof s.url === 'string' && s.url ? s.url : null
+  if (!url) return { kind: 'stop', reason, message }
 
-  const checkoutUrl = verdict.checkout_url
-  if (!checkoutUrl) {
-    say.warn(
-      'The backend reports payment is required but returned no checkout URL — proceeding.'
-    )
-    return { proceed: true }
+  return {
+    kind: 'settle',
+    url,
+    handle: s && typeof s.handle === 'string' && s.handle ? s.handle : null,
+    reason,
+    message
   }
+}
+
+/**
+ * Report a payment refusal to the user, and open the settlement page when the
+ * backend supplied one.
+ *
+ * ⛔ Returns rather than exits — the caller owns the exit code, and a refusal
+ * is not a crash: the content is already synced as a draft, so re-running
+ * after paying is the recovery.
+ *
+ * @param {object} o
+ * @param {ReturnType<typeof readPaymentRefusal>} o.verdict
+ * @param {string[]} o.args - argv slice (for --non-interactive detection)
+ * @param {object} o.say - { ok, info, warn, err, dim } reporters
+ * @param {(url: string) => Promise<boolean>} [o.open] - injected for tests
+ * @returns {Promise<{ opened: boolean }>}
+ */
+export async function reportPaymentRefusal({ verdict, args = [], say, open }) {
+  // The backend's own sentence is the HEADLINE when there is one. A generic
+  // lead would be wrong as often as right — "payment is required" does not
+  // describe a declined card — and `detail` is written for this reader.
+  say.err(verdict.message || 'This site cannot go live until it is paid for.')
 
-  if (dryRun) {
-    say.dim(`Payment     : required — would open ${checkoutUrl}`)
-    return { proceed: true }
+  if (verdict.kind !== 'settle') {
+    // The push completed before go-live, so the content is safely stored.
+    say.dim('The site is synced as a draft; nothing was made live.')
+    return { opened: false }
   }
 
+  const { isNonInteractive } = await import('../utils/interactive.js')
   if (isNonInteractive(args)) {
-    say.err(
-      'Payment is required to publish this site, and the CLI is non-interactive.'
-    )
-    say.dim(`Complete it in a browser, then re-run: ${checkoutUrl}`)
-    return { proceed: false }
+    say.dim(`Complete it in a browser, then re-run \`uniweb publish\`:`)
+    say.dim(`  ${verdict.url}`)
+    return { opened: false }
   }
 
-  // The CSRF nonce the app echoes back on the done-signal redirect. The
-  // wait_token (when present) lets the app correlate the session backend-side.
-  const state = randomBytes(16).toString('hex')
-  say.info('Payment required — completing it in your browser…')
-  try {
-    await awaitBrowserCallback({
-      buildUrl: (redirectUri) =>
-        withParams(checkoutUrl, {
-          redirect_uri: redirectUri,
-          state,
-          wait_token: verdict.wait_token
-        }),
-      validate: (params) => {
-        if (params.get('error')) return { error: params.get('error') }
-        if (params.get('state') !== state)
-          return { error: 'state mismatch — please retry.' }
-        return { value: true } // ok=1 / any non-error return = the app settled with the backend
-      },
-      openingLabel: 'Opening uniweb.app to complete payment…',
-      waitingLabel: 'Waiting for payment to complete (5 min)…',
-      timeoutMs: 5 * 60 * 1000,
-      okTitle: 'Payment complete',
-      errTitle: 'Payment failed'
-    })
-  } catch (err) {
-    say.err(`Payment was not completed: ${err.message}`)
-    say.dim('Re-run `uniweb publish` once payment is done.')
-    return { proceed: false }
+  const openBrowser = open || (await import('../utils/registry-auth.js')).openBrowser
+  say.info('Opening your browser to complete it…')
+  say.dim(`  ${verdict.url}`)
+  // VERBATIM. Nothing is appended — see the header.
+  const opened = await openBrowser(verdict.url)
+  if (!opened) {
+    say.warn('Could not open a browser automatically — open the URL above.')
   }
-  say.ok('Payment complete.')
-  return { proceed: true }
+  say.dim('Once payment is complete, re-run `uniweb publish`.')
+  return { opened }
 }

package/src/backend/site-sync.js

@@ -26,6 +26,7 @@ import {
   describeSiteDiff,
   computeUnitHashes,
   collectUnitUuids,
+  collectFolderItemUuids,
   readAssetMap
 } from '@uniweb/build/uwx'
 
@@ -457,6 +458,20 @@ export function mergeBaseVersions(siteDir, versions) {
 export function readItemUuids(siteDir) {
   return readMap(siteDir, 'itemUuids')
 }
+/**
+ * Placement identity for the site's `@uniweb/folder` — path chain → `$uuid`.
+ *
+ * Kept separate from `itemUuids` (which is site-content units) because they key
+ * different trees: `pages/…/page.yml` there, `members/alice` here. One map with
+ * two key languages is a map nobody can validate.
+ */
+export function readFolderItemUuids(siteDir) {
+  return readMap(siteDir, 'folderItemUuids')
+}
+export function writeFolderItemUuids(siteDir, map) {
+  if (!map || !Object.keys(map).length) return
+  updateSyncCache(siteDir, { folderItemUuids: map })
+}
 export function writeItemUuids(siteDir, map) {
   if (!map || !Object.keys(map).length) return
   updateSyncCache(siteDir, { itemUuids: map })
@@ -1297,6 +1312,21 @@ export async function pushSyncPackages({
     for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
     if (bf.updated.length)
       wrote.push(`wrote ${bf.updated.length} record file(s)`)
+    // ⭐ BANK THE FOLDER'S PLACEMENT IDENTITY. The records back-fill their own
+    // `$uuid` into their source files (above); the folder's ITEMS have nowhere to
+    // be written, so they are banked here from the document the backend just
+    // returned.
+    //
+    // ⛔ Without this a `publish` after a `push` is refused: send-only-changed
+    // skips the unchanged records and re-sends the folder ALONE, its `contents`
+    // items carry no `$uuid`, and a `multi` item without one reads as new — so
+    // the backend refuses rather than replacing every placement. Reproduced on a
+    // live manor 2026-08-27; the identities were on the wire all along.
+    const folderDoc = finalized.find((f) => f?.document?.contents)?.document
+    if (folderDoc) {
+      const placements = collectFolderItemUuids(folderDoc)
+      if (Object.keys(placements).length) writeFolderItemUuids(siteDir, placements)
+    }
     finalizedTotal += finalized.length
   }
 
@@ -1323,6 +1353,26 @@ export async function pushSyncPackages({
     // Replaced wholesale: an item that no longer exists must not keep a uuid that
     // would re-target something else.
     if (theirs) writeItemUuids(siteDir, collectUnitUuids(theirs))
+    else {
+      // ⛔ BANKING IS BEST-EFFORT AND ITS FAILURE USED TO BE SILENT — say it here,
+      // because the cost lands two commands away and names something else.
+      //
+      // Without `finalized[0].document` (carrying `pages`) this push banks NO item
+      // identity. The push still reports success. The next `push`/`publish` then
+      // emits with no `$uuid` per item, and the backend refuses — correctly, since
+      // silently re-identifying every stored row is far worse. But that refusal
+      // reads as a stale-token or a producer bug, with nothing pointing back at the
+      // push that failed to bank.
+      //
+      // ⚠️ We cannot tell WHY it is absent from here — a response shape that
+      // changed, a lane that shipped nothing, a backend that does not echo the
+      // document. Report the observable fact and let the operator carry it.
+      note(
+        'identity not banked: this push returned no post-write document, so no per-item ' +
+          '$uuid was stored. The next push or publish will be identity-blind and the backend ' +
+          'may refuse it. `uniweb pull` re-arms identity if that happens.'
+      )
+    }
   }
   return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote }
 }

package/src/commands/publish.js

@@ -77,6 +77,7 @@ import {
   readBaseVersions,
   readItemBaseVersions,
   ensureItemUuids,
+  readFolderItemUuids,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
   pushSyncPackages,
@@ -88,7 +89,10 @@ import {
   bringFoundationAlong,
   bringExtensionsAlong
 } from '../backend/foundation-bring-along.js'
-import { settlePaymentIfNeeded } from '../backend/payment-handoff.js'
+import {
+  readPaymentRefusal,
+  reportPaymentRefusal
+} from '../backend/payment-handoff.js'
 import { reportSchemalessCollections } from '../utils/schemaless-report.js'
 import { uploadSiteData } from '../utils/site-data-upload.js'
 
@@ -353,13 +357,10 @@ export async function publish(args = []) {
       cliBin: process.argv[1],
       dryRun: true
     })
-    await settlePaymentIfNeeded({
-      client,
-      uuid: siteYml.$uuid || null,
-      args,
-      say,
-      dryRun: true
-    })
+    // No payment line on a dry run. The backend is the only gate and it
+    // answers at go-live, so the honest dry-run answer is silence rather than
+    // a guess. (The old "would check whether go-live needs payment" described
+    // a pre-flight probe that has been removed — payment-handoff.js.)
     return { exitCode: 0 }
   }
 
@@ -440,6 +441,10 @@ export async function publish(args = []) {
   let probe
   try {
     probe = await emitSyncPackages(siteDir, {
+      // Placement identity for the folder — see writeFolderItemUuids.
+      folderItemUuids: readFolderItemUuids(siteDir),
+      // Resolves a foundation-relative `@/x` model ref into `@org/x`.
+      ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),
       resolveModel
     })
@@ -639,6 +644,10 @@ export async function publish(args = []) {
   let pkg
   try {
     pkg = await emitSyncPackages(siteDir, {
+      // Placement identity for the folder — see writeFolderItemUuids.
+      folderItemUuids: readFolderItemUuids(siteDir),
+      // Resolves a foundation-relative `@/x` model ref into `@org/x`.
+      ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),
       resolveModel,
       priorHashes,
@@ -678,18 +687,6 @@ export async function publish(args = []) {
     return { exitCode: 1 }
   }
 
-  // 6. Payment gate — the backend says whether go-live needs payment. Settles
-  //    via a browser handoff to uniweb.app; degrades to "proceed" when the
-  //    backend exposes no payment route. The draft is already synced, so a
-  //    decline leaves a recoverable state (re-run after paying).
-  const pay = await settlePaymentIfNeeded({ client, uuid: siteUuid, args, say })
-  if (!pay.proceed) {
-    say.info(
-      'Site synced as a draft but not made live. Re-run `uniweb publish` once payment is complete.'
-    )
-    return { exitCode: 0 }
-  }
-
   // 7. Go live — make the just-pushed composite live (its current backend state).
   const siteContent = JSON.parse(await readFile(contentPath, 'utf8'))
   const languages = languagesFromContent(siteContent)
@@ -705,13 +702,29 @@ export async function publish(args = []) {
     return { exitCode: 1 }
   }
   if (!pubRes.ok) {
+    const body = await pubRes.text().catch(() => '')
+
+    // A 402 is the backend's payment gate — the ONLY gate, evaluated here on
+    // every publish against whatever posture that deployment runs. It is a
+    // refusal, not a fault: the content is already synced as a draft, so the
+    // recovery is to settle and re-run. Give it the backend's own sentence
+    // rather than the raw envelope.
+    const refusal = readPaymentRefusal({
+      status: pubRes.status,
+      contentType: pubRes.headers?.get?.('content-type') || '',
+      body
+    })
+    if (refusal.kind !== 'not-payment') {
+      await reportPaymentRefusal({ verdict: refusal, args, say })
+      return { exitCode: 1 }
+    }
+
     say.err(`Publish rejected: HTTP ${pubRes.status} ${pubRes.statusText}`)
     if (pubRes.status === 401 || pubRes.status === 403) {
       say.dim(
         "Credentials weren't accepted — run `uniweb login` (or pass --token <bearer>)."
       )
     }
-    const body = await pubRes.text().catch(() => '')
     if (body) say.dim(body.slice(0, 800))
     return { exitCode: 1 }
   }

package/src/commands/push.js

@@ -84,6 +84,7 @@ import {
   readBaseVersions,
   readItemBaseVersions,
   readItemUuids,
+  readFolderItemUuids,
   ensureItemUuids,
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
@@ -373,6 +374,10 @@ export async function push(args = [], deps = {}) {
     let mediaRefs = []
     try {
       const probe = await emitSyncPackages(siteDir, {
+      // Placement identity for the folder — see writeFolderItemUuids.
+      folderItemUuids: readFolderItemUuids(siteDir),
+      // Resolves a foundation-relative `@/x` model ref into `@org/x`.
+      ...(asOrg ? { org: asOrg } : {}),
         ...(foundationDir ? { foundationDir } : {}),
         resolveModel: makeModelResolver({ client, offline: false })
       })
@@ -467,6 +472,10 @@ export async function push(args = [], deps = {}) {
   let pkg
   try {
     pkg = await emitSyncPackages(siteDir, {
+      // Placement identity for the folder — see writeFolderItemUuids.
+      folderItemUuids: readFolderItemUuids(siteDir),
+      // Resolves a foundation-relative `@/x` model ref into `@org/x`.
+      ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),
       resolveModel: makeModelResolver({
         client,

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-27T04:57:15.265Z",
+  "generatedAt": "2026-08-27T21:10:42.589Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.27.0",
+      "version": "0.28.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -68,7 +68,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.3.7",
+      "version": "0.4.1",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -114,7 +114,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.13",
+      "version": "0.8.14",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/utils/registry-auth.js

@@ -321,7 +321,9 @@ async function loginViaTokenPaste({ apiBase, nonInteractive }) {
 }
 
 // Open a URL in the default browser. Returns whether it launched.
-async function openBrowser(url) {
+// Exported for the publish payment refusal, which opens the backend's
+// settlement URL VERBATIM and needs no loopback (backend/payment-handoff.js).
+export async function openBrowser(url) {
   try {
     const { exec } = await import('node:child_process')
     const cmd =